diff --git a/.gitattributes b/.gitattributes index 5ccea84ce598e4331da41abe291c9ff999e9d7ff..e75c5bffcae50e90df1b2bc35bbe879052950515 100644 --- a/.gitattributes +++ b/.gitattributes @@ -63,3 +63,39 @@ .venv/lib/python3.13/site-packages/numpy.libs/libgfortran-83c28eba-b4027c22.so.5.0.0 filter=lfs diff=lfs merge=lfs -text .venv/lib/python3.13/site-packages/numpy.libs/libquadmath-2284e583-a9307bba.so.0.0.0 filter=lfs diff=lfs merge=lfs -text .venv/lib/python3.13/site-packages/numpy.libs/libscipy_openblas64_-017048f4.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/orjson/orjson.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/algos.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/arrays.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/groupby.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/hashing.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/index.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/internals.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/interval.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/join.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/lib.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/missing.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/ops.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/parsers.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/reshape.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/sas.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/sparse.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/testing.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslib.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text +.venv/lib/python3.13/site-packages/pandas/_libs/writers.cpython-313-x86_64-linux-gnu.so filter=lfs diff=lfs merge=lfs -text diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/INSTALLER b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/INSTALLER new file mode 100644 index 0000000000000000000000000000000000000000..a1b589e38a32041e49332e5e81c2d363dc418d68 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/INSTALLER @@ -0,0 +1 @@ +pip diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/METADATA b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/METADATA new file mode 100644 index 0000000000000000000000000000000000000000..c697bd142b88856c78b0b5ccf41fcd8ae67fb1a3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/METADATA @@ -0,0 +1,905 @@ +Metadata-Version: 2.3 +Name: openai +Version: 1.109.1 +Summary: The official Python library for the openai API +Project-URL: Homepage, https://github.com/openai/openai-python +Project-URL: Repository, https://github.com/openai/openai-python +Author-email: OpenAI +License: Apache-2.0 +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: Apache Software License +Classifier: Operating System :: MacOS +Classifier: Operating System :: Microsoft :: Windows +Classifier: Operating System :: OS Independent +Classifier: Operating System :: POSIX +Classifier: Operating System :: POSIX :: Linux +Classifier: Programming Language :: Python :: 3.8 +Classifier: Programming Language :: Python :: 3.9 +Classifier: Programming Language :: Python :: 3.10 +Classifier: Programming Language :: Python :: 3.11 +Classifier: Programming Language :: Python :: 3.12 +Classifier: Programming Language :: Python :: 3.13 +Classifier: Topic :: Software Development :: Libraries :: Python Modules +Classifier: Typing :: Typed +Requires-Python: >=3.8 +Requires-Dist: anyio<5,>=3.5.0 +Requires-Dist: distro<2,>=1.7.0 +Requires-Dist: httpx<1,>=0.23.0 +Requires-Dist: jiter<1,>=0.4.0 +Requires-Dist: pydantic<3,>=1.9.0 +Requires-Dist: sniffio +Requires-Dist: tqdm>4 +Requires-Dist: typing-extensions<5,>=4.11 +Provides-Extra: aiohttp +Requires-Dist: aiohttp; extra == 'aiohttp' +Requires-Dist: httpx-aiohttp>=0.1.8; extra == 'aiohttp' +Provides-Extra: datalib +Requires-Dist: numpy>=1; extra == 'datalib' +Requires-Dist: pandas-stubs>=1.1.0.11; extra == 'datalib' +Requires-Dist: pandas>=1.2.3; extra == 'datalib' +Provides-Extra: realtime +Requires-Dist: websockets<16,>=13; extra == 'realtime' +Provides-Extra: voice-helpers +Requires-Dist: numpy>=2.0.2; extra == 'voice-helpers' +Requires-Dist: sounddevice>=0.5.1; extra == 'voice-helpers' +Description-Content-Type: text/markdown + +# OpenAI Python API library + + +[![PyPI version](https://img.shields.io/pypi/v/openai.svg?label=pypi%20(stable))](https://pypi.org/project/openai/) + +The OpenAI Python library provides convenient access to the OpenAI REST API from any Python 3.8+ +application. The library includes type definitions for all request params and response fields, +and offers both synchronous and asynchronous clients powered by [httpx](https://github.com/encode/httpx). + +It is generated from our [OpenAPI specification](https://github.com/openai/openai-openapi) with [Stainless](https://stainlessapi.com/). + +## Documentation + +The REST API documentation can be found on [platform.openai.com](https://platform.openai.com/docs/api-reference). The full API of this library can be found in [api.md](https://github.com/openai/openai-python/tree/main/api.md). + +## Installation + +```sh +# install from PyPI +pip install openai +``` + +## Usage + +The full API of this library can be found in [api.md](https://github.com/openai/openai-python/tree/main/api.md). + +The primary API for interacting with OpenAI models is the [Responses API](https://platform.openai.com/docs/api-reference/responses). You can generate text from the model with the code below. + +```python +import os +from openai import OpenAI + +client = OpenAI( + # This is the default and can be omitted + api_key=os.environ.get("OPENAI_API_KEY"), +) + +response = client.responses.create( + model="gpt-4o", + instructions="You are a coding assistant that talks like a pirate.", + input="How do I check if a Python object is an instance of a class?", +) + +print(response.output_text) +``` + +The previous standard (supported indefinitely) for generating text is the [Chat Completions API](https://platform.openai.com/docs/api-reference/chat). You can use that API to generate text from the model with the code below. + +```python +from openai import OpenAI + +client = OpenAI() + +completion = client.chat.completions.create( + model="gpt-4o", + messages=[ + {"role": "developer", "content": "Talk like a pirate."}, + { + "role": "user", + "content": "How do I check if a Python object is an instance of a class?", + }, + ], +) + +print(completion.choices[0].message.content) +``` + +While you can provide an `api_key` keyword argument, +we recommend using [python-dotenv](https://pypi.org/project/python-dotenv/) +to add `OPENAI_API_KEY="My API Key"` to your `.env` file +so that your API key is not stored in source control. +[Get an API key here](https://platform.openai.com/settings/organization/api-keys). + +### Vision + +With an image URL: + +```python +prompt = "What is in this image?" +img_url = "https://upload.wikimedia.org/wikipedia/commons/thumb/d/d5/2023_06_08_Raccoon1.jpg/1599px-2023_06_08_Raccoon1.jpg" + +response = client.responses.create( + model="gpt-4o-mini", + input=[ + { + "role": "user", + "content": [ + {"type": "input_text", "text": prompt}, + {"type": "input_image", "image_url": f"{img_url}"}, + ], + } + ], +) +``` + +With the image as a base64 encoded string: + +```python +import base64 +from openai import OpenAI + +client = OpenAI() + +prompt = "What is in this image?" +with open("path/to/image.png", "rb") as image_file: + b64_image = base64.b64encode(image_file.read()).decode("utf-8") + +response = client.responses.create( + model="gpt-4o-mini", + input=[ + { + "role": "user", + "content": [ + {"type": "input_text", "text": prompt}, + {"type": "input_image", "image_url": f"data:image/png;base64,{b64_image}"}, + ], + } + ], +) +``` + +## Async usage + +Simply import `AsyncOpenAI` instead of `OpenAI` and use `await` with each API call: + +```python +import os +import asyncio +from openai import AsyncOpenAI + +client = AsyncOpenAI( + # This is the default and can be omitted + api_key=os.environ.get("OPENAI_API_KEY"), +) + + +async def main() -> None: + response = await client.responses.create( + model="gpt-4o", input="Explain disestablishmentarianism to a smart five year old." + ) + print(response.output_text) + + +asyncio.run(main()) +``` + +Functionality between the synchronous and asynchronous clients is otherwise identical. + +### With aiohttp + +By default, the async client uses `httpx` for HTTP requests. However, for improved concurrency performance you may also use `aiohttp` as the HTTP backend. + +You can enable this by installing `aiohttp`: + +```sh +# install from PyPI +pip install openai[aiohttp] +``` + +Then you can enable it by instantiating the client with `http_client=DefaultAioHttpClient()`: + +```python +import asyncio +from openai import DefaultAioHttpClient +from openai import AsyncOpenAI + + +async def main() -> None: + async with AsyncOpenAI( + api_key="My API Key", + http_client=DefaultAioHttpClient(), + ) as client: + chat_completion = await client.chat.completions.create( + messages=[ + { + "role": "user", + "content": "Say this is a test", + } + ], + model="gpt-4o", + ) + + +asyncio.run(main()) +``` + +## Streaming responses + +We provide support for streaming responses using Server Side Events (SSE). + +```python +from openai import OpenAI + +client = OpenAI() + +stream = client.responses.create( + model="gpt-4o", + input="Write a one-sentence bedtime story about a unicorn.", + stream=True, +) + +for event in stream: + print(event) +``` + +The async client uses the exact same interface. + +```python +import asyncio +from openai import AsyncOpenAI + +client = AsyncOpenAI() + + +async def main(): + stream = await client.responses.create( + model="gpt-4o", + input="Write a one-sentence bedtime story about a unicorn.", + stream=True, + ) + + async for event in stream: + print(event) + + +asyncio.run(main()) +``` + +## Realtime API + +The Realtime API enables you to build low-latency, multi-modal conversational experiences. It currently supports text and audio as both input and output, as well as [function calling](https://platform.openai.com/docs/guides/function-calling) through a WebSocket connection. + +Under the hood the SDK uses the [`websockets`](https://websockets.readthedocs.io/en/stable/) library to manage connections. + +The Realtime API works through a combination of client-sent events and server-sent events. Clients can send events to do things like update session configuration or send text and audio inputs. Server events confirm when audio responses have completed, or when a text response from the model has been received. A full event reference can be found [here](https://platform.openai.com/docs/api-reference/realtime-client-events) and a guide can be found [here](https://platform.openai.com/docs/guides/realtime). + +Basic text based example: + +```py +import asyncio +from openai import AsyncOpenAI + +async def main(): + client = AsyncOpenAI() + + async with client.realtime.connect(model="gpt-realtime") as connection: + await connection.session.update(session={'modalities': ['text']}) + + await connection.conversation.item.create( + item={ + "type": "message", + "role": "user", + "content": [{"type": "input_text", "text": "Say hello!"}], + } + ) + await connection.response.create() + + async for event in connection: + if event.type == 'response.text.delta': + print(event.delta, flush=True, end="") + + elif event.type == 'response.text.done': + print() + + elif event.type == "response.done": + break + +asyncio.run(main()) +``` + +However the real magic of the Realtime API is handling audio inputs / outputs, see this example [TUI script](https://github.com/openai/openai-python/blob/main/examples/realtime/push_to_talk_app.py) for a fully fledged example. + +### Realtime error handling + +Whenever an error occurs, the Realtime API will send an [`error` event](https://platform.openai.com/docs/guides/realtime-model-capabilities#error-handling) and the connection will stay open and remain usable. This means you need to handle it yourself, as _no errors are raised directly_ by the SDK when an `error` event comes in. + +```py +client = AsyncOpenAI() + +async with client.realtime.connect(model="gpt-realtime") as connection: + ... + async for event in connection: + if event.type == 'error': + print(event.error.type) + print(event.error.code) + print(event.error.event_id) + print(event.error.message) +``` + +## Using types + +Nested request parameters are [TypedDicts](https://docs.python.org/3/library/typing.html#typing.TypedDict). Responses are [Pydantic models](https://docs.pydantic.dev) which also provide helper methods for things like: + +- Serializing back into JSON, `model.to_json()` +- Converting to a dictionary, `model.to_dict()` + +Typed requests and responses provide autocomplete and documentation within your editor. If you would like to see type errors in VS Code to help catch bugs earlier, set `python.analysis.typeCheckingMode` to `basic`. + +## Pagination + +List methods in the OpenAI API are paginated. + +This library provides auto-paginating iterators with each list response, so you do not have to request successive pages manually: + +```python +from openai import OpenAI + +client = OpenAI() + +all_jobs = [] +# Automatically fetches more pages as needed. +for job in client.fine_tuning.jobs.list( + limit=20, +): + # Do something with job here + all_jobs.append(job) +print(all_jobs) +``` + +Or, asynchronously: + +```python +import asyncio +from openai import AsyncOpenAI + +client = AsyncOpenAI() + + +async def main() -> None: + all_jobs = [] + # Iterate through items across all pages, issuing requests as needed. + async for job in client.fine_tuning.jobs.list( + limit=20, + ): + all_jobs.append(job) + print(all_jobs) + + +asyncio.run(main()) +``` + +Alternatively, you can use the `.has_next_page()`, `.next_page_info()`, or `.get_next_page()` methods for more granular control working with pages: + +```python +first_page = await client.fine_tuning.jobs.list( + limit=20, +) +if first_page.has_next_page(): + print(f"will fetch next page using these details: {first_page.next_page_info()}") + next_page = await first_page.get_next_page() + print(f"number of items we just fetched: {len(next_page.data)}") + +# Remove `await` for non-async usage. +``` + +Or just work directly with the returned data: + +```python +first_page = await client.fine_tuning.jobs.list( + limit=20, +) + +print(f"next page cursor: {first_page.after}") # => "next page cursor: ..." +for job in first_page.data: + print(job.id) + +# Remove `await` for non-async usage. +``` + +## Nested params + +Nested parameters are dictionaries, typed using `TypedDict`, for example: + +```python +from openai import OpenAI + +client = OpenAI() + +response = client.chat.responses.create( + input=[ + { + "role": "user", + "content": "How much ?", + } + ], + model="gpt-4o", + response_format={"type": "json_object"}, +) +``` + +## File uploads + +Request parameters that correspond to file uploads can be passed as `bytes`, or a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance or a tuple of `(filename, contents, media type)`. + +```python +from pathlib import Path +from openai import OpenAI + +client = OpenAI() + +client.files.create( + file=Path("input.jsonl"), + purpose="fine-tune", +) +``` + +The async client uses the exact same interface. If you pass a [`PathLike`](https://docs.python.org/3/library/os.html#os.PathLike) instance, the file contents will be read asynchronously automatically. + +## Webhook Verification + +Verifying webhook signatures is _optional but encouraged_. + +For more information about webhooks, see [the API docs](https://platform.openai.com/docs/guides/webhooks). + +### Parsing webhook payloads + +For most use cases, you will likely want to verify the webhook and parse the payload at the same time. To achieve this, we provide the method `client.webhooks.unwrap()`, which parses a webhook request and verifies that it was sent by OpenAI. This method will raise an error if the signature is invalid. + +Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). The `.unwrap()` method will parse this JSON for you into an event object after verifying the webhook was sent from OpenAI. + +```python +from openai import OpenAI +from flask import Flask, request + +app = Flask(__name__) +client = OpenAI() # OPENAI_WEBHOOK_SECRET environment variable is used by default + + +@app.route("/webhook", methods=["POST"]) +def webhook(): + request_body = request.get_data(as_text=True) + + try: + event = client.webhooks.unwrap(request_body, request.headers) + + if event.type == "response.completed": + print("Response completed:", event.data) + elif event.type == "response.failed": + print("Response failed:", event.data) + else: + print("Unhandled event type:", event.type) + + return "ok" + except Exception as e: + print("Invalid signature:", e) + return "Invalid signature", 400 + + +if __name__ == "__main__": + app.run(port=8000) +``` + +### Verifying webhook payloads directly + +In some cases, you may want to verify the webhook separately from parsing the payload. If you prefer to handle these steps separately, we provide the method `client.webhooks.verify_signature()` to _only verify_ the signature of a webhook request. Like `.unwrap()`, this method will raise an error if the signature is invalid. + +Note that the `body` parameter must be the raw JSON string sent from the server (do not parse it first). You will then need to parse the body after verifying the signature. + +```python +import json +from openai import OpenAI +from flask import Flask, request + +app = Flask(__name__) +client = OpenAI() # OPENAI_WEBHOOK_SECRET environment variable is used by default + + +@app.route("/webhook", methods=["POST"]) +def webhook(): + request_body = request.get_data(as_text=True) + + try: + client.webhooks.verify_signature(request_body, request.headers) + + # Parse the body after verification + event = json.loads(request_body) + print("Verified event:", event) + + return "ok" + except Exception as e: + print("Invalid signature:", e) + return "Invalid signature", 400 + + +if __name__ == "__main__": + app.run(port=8000) +``` + +## Handling errors + +When the library is unable to connect to the API (for example, due to network connection problems or a timeout), a subclass of `openai.APIConnectionError` is raised. + +When the API returns a non-success status code (that is, 4xx or 5xx +response), a subclass of `openai.APIStatusError` is raised, containing `status_code` and `response` properties. + +All errors inherit from `openai.APIError`. + +```python +import openai +from openai import OpenAI + +client = OpenAI() + +try: + client.fine_tuning.jobs.create( + model="gpt-4o", + training_file="file-abc123", + ) +except openai.APIConnectionError as e: + print("The server could not be reached") + print(e.__cause__) # an underlying Exception, likely raised within httpx. +except openai.RateLimitError as e: + print("A 429 status code was received; we should back off a bit.") +except openai.APIStatusError as e: + print("Another non-200-range status code was received") + print(e.status_code) + print(e.response) +``` + +Error codes are as follows: + +| Status Code | Error Type | +| ----------- | -------------------------- | +| 400 | `BadRequestError` | +| 401 | `AuthenticationError` | +| 403 | `PermissionDeniedError` | +| 404 | `NotFoundError` | +| 422 | `UnprocessableEntityError` | +| 429 | `RateLimitError` | +| >=500 | `InternalServerError` | +| N/A | `APIConnectionError` | + +## Request IDs + +> For more information on debugging requests, see [these docs](https://platform.openai.com/docs/api-reference/debugging-requests) + +All object responses in the SDK provide a `_request_id` property which is added from the `x-request-id` response header so that you can quickly log failing requests and report them back to OpenAI. + +```python +response = await client.responses.create( + model="gpt-4o-mini", + input="Say 'this is a test'.", +) +print(response._request_id) # req_123 +``` + +Note that unlike other properties that use an `_` prefix, the `_request_id` property +_is_ public. Unless documented otherwise, _all_ other `_` prefix properties, +methods and modules are _private_. + +> [!IMPORTANT] +> If you need to access request IDs for failed requests you must catch the `APIStatusError` exception + +```python +import openai + +try: + completion = await client.chat.completions.create( + messages=[{"role": "user", "content": "Say this is a test"}], model="gpt-4" + ) +except openai.APIStatusError as exc: + print(exc.request_id) # req_123 + raise exc +``` + +## Retries + +Certain errors are automatically retried 2 times by default, with a short exponential backoff. +Connection errors (for example, due to a network connectivity problem), 408 Request Timeout, 409 Conflict, +429 Rate Limit, and >=500 Internal errors are all retried by default. + +You can use the `max_retries` option to configure or disable retry settings: + +```python +from openai import OpenAI + +# Configure the default for all requests: +client = OpenAI( + # default is 2 + max_retries=0, +) + +# Or, configure per-request: +client.with_options(max_retries=5).chat.completions.create( + messages=[ + { + "role": "user", + "content": "How can I get the name of the current day in JavaScript?", + } + ], + model="gpt-4o", +) +``` + +## Timeouts + +By default requests time out after 10 minutes. You can configure this with a `timeout` option, +which accepts a float or an [`httpx.Timeout`](https://www.python-httpx.org/advanced/timeouts/#fine-tuning-the-configuration) object: + +```python +from openai import OpenAI + +# Configure the default for all requests: +client = OpenAI( + # 20 seconds (default is 10 minutes) + timeout=20.0, +) + +# More granular control: +client = OpenAI( + timeout=httpx.Timeout(60.0, read=5.0, write=10.0, connect=2.0), +) + +# Override per-request: +client.with_options(timeout=5.0).chat.completions.create( + messages=[ + { + "role": "user", + "content": "How can I list all files in a directory using Python?", + } + ], + model="gpt-4o", +) +``` + +On timeout, an `APITimeoutError` is thrown. + +Note that requests that time out are [retried twice by default](https://github.com/openai/openai-python/tree/main/#retries). + +## Advanced + +### Logging + +We use the standard library [`logging`](https://docs.python.org/3/library/logging.html) module. + +You can enable logging by setting the environment variable `OPENAI_LOG` to `info`. + +```shell +$ export OPENAI_LOG=info +``` + +Or to `debug` for more verbose logging. + +### How to tell whether `None` means `null` or missing + +In an API response, a field may be explicitly `null`, or missing entirely; in either case, its value is `None` in this library. You can differentiate the two cases with `.model_fields_set`: + +```py +if response.my_field is None: + if 'my_field' not in response.model_fields_set: + print('Got json like {}, without a "my_field" key present at all.') + else: + print('Got json like {"my_field": null}.') +``` + +### Accessing raw response data (e.g. headers) + +The "raw" Response object can be accessed by prefixing `.with_raw_response.` to any HTTP method call, e.g., + +```py +from openai import OpenAI + +client = OpenAI() +response = client.chat.completions.with_raw_response.create( + messages=[{ + "role": "user", + "content": "Say this is a test", + }], + model="gpt-4o", +) +print(response.headers.get('X-My-Header')) + +completion = response.parse() # get the object that `chat.completions.create()` would have returned +print(completion) +``` + +These methods return a [`LegacyAPIResponse`](https://github.com/openai/openai-python/tree/main/src/openai/_legacy_response.py) object. This is a legacy class as we're changing it slightly in the next major version. + +For the sync client this will mostly be the same with the exception +of `content` & `text` will be methods instead of properties. In the +async client, all methods will be async. + +A migration script will be provided & the migration in general should +be smooth. + +#### `.with_streaming_response` + +The above interface eagerly reads the full response body when you make the request, which may not always be what you want. + +To stream the response body, use `.with_streaming_response` instead, which requires a context manager and only reads the response body once you call `.read()`, `.text()`, `.json()`, `.iter_bytes()`, `.iter_text()`, `.iter_lines()` or `.parse()`. In the async client, these are async methods. + +As such, `.with_streaming_response` methods return a different [`APIResponse`](https://github.com/openai/openai-python/tree/main/src/openai/_response.py) object, and the async client returns an [`AsyncAPIResponse`](https://github.com/openai/openai-python/tree/main/src/openai/_response.py) object. + +```python +with client.chat.completions.with_streaming_response.create( + messages=[ + { + "role": "user", + "content": "Say this is a test", + } + ], + model="gpt-4o", +) as response: + print(response.headers.get("X-My-Header")) + + for line in response.iter_lines(): + print(line) +``` + +The context manager is required so that the response will reliably be closed. + +### Making custom/undocumented requests + +This library is typed for convenient access to the documented API. + +If you need to access undocumented endpoints, params, or response properties, the library can still be used. + +#### Undocumented endpoints + +To make requests to undocumented endpoints, you can make requests using `client.get`, `client.post`, and other +http verbs. Options on the client will be respected (such as retries) when making this request. + +```py +import httpx + +response = client.post( + "/foo", + cast_to=httpx.Response, + body={"my_param": True}, +) + +print(response.headers.get("x-foo")) +``` + +#### Undocumented request params + +If you want to explicitly send an extra param, you can do so with the `extra_query`, `extra_body`, and `extra_headers` request +options. + +#### Undocumented response properties + +To access undocumented response properties, you can access the extra fields like `response.unknown_prop`. You +can also get all the extra fields on the Pydantic model as a dict with +[`response.model_extra`](https://docs.pydantic.dev/latest/api/base_model/#pydantic.BaseModel.model_extra). + +### Configuring the HTTP client + +You can directly override the [httpx client](https://www.python-httpx.org/api/#client) to customize it for your use case, including: + +- Support for [proxies](https://www.python-httpx.org/advanced/proxies/) +- Custom [transports](https://www.python-httpx.org/advanced/transports/) +- Additional [advanced](https://www.python-httpx.org/advanced/clients/) functionality + +```python +import httpx +from openai import OpenAI, DefaultHttpxClient + +client = OpenAI( + # Or use the `OPENAI_BASE_URL` env var + base_url="http://my.test.server.example.com:8083/v1", + http_client=DefaultHttpxClient( + proxy="http://my.test.proxy.example.com", + transport=httpx.HTTPTransport(local_address="0.0.0.0"), + ), +) +``` + +You can also customize the client on a per-request basis by using `with_options()`: + +```python +client.with_options(http_client=DefaultHttpxClient(...)) +``` + +### Managing HTTP resources + +By default the library closes underlying HTTP connections whenever the client is [garbage collected](https://docs.python.org/3/reference/datamodel.html#object.__del__). You can manually close the client using the `.close()` method if desired, or with a context manager that closes when exiting. + +```py +from openai import OpenAI + +with OpenAI() as client: + # make requests here + ... + +# HTTP client is now closed +``` + +## Microsoft Azure OpenAI + +To use this library with [Azure OpenAI](https://learn.microsoft.com/azure/ai-services/openai/overview), use the `AzureOpenAI` +class instead of the `OpenAI` class. + +> [!IMPORTANT] +> The Azure API shape differs from the core API shape which means that the static types for responses / params +> won't always be correct. + +```py +from openai import AzureOpenAI + +# gets the API Key from environment variable AZURE_OPENAI_API_KEY +client = AzureOpenAI( + # https://learn.microsoft.com/azure/ai-services/openai/reference#rest-api-versioning + api_version="2023-07-01-preview", + # https://learn.microsoft.com/azure/cognitive-services/openai/how-to/create-resource?pivots=web-portal#create-a-resource + azure_endpoint="https://example-endpoint.openai.azure.com", +) + +completion = client.chat.completions.create( + model="deployment-name", # e.g. gpt-35-instant + messages=[ + { + "role": "user", + "content": "How do I output all files in a directory using Python?", + }, + ], +) +print(completion.to_json()) +``` + +In addition to the options provided in the base `OpenAI` client, the following options are provided: + +- `azure_endpoint` (or the `AZURE_OPENAI_ENDPOINT` environment variable) +- `azure_deployment` +- `api_version` (or the `OPENAI_API_VERSION` environment variable) +- `azure_ad_token` (or the `AZURE_OPENAI_AD_TOKEN` environment variable) +- `azure_ad_token_provider` + +An example of using the client with Microsoft Entra ID (formerly known as Azure Active Directory) can be found [here](https://github.com/openai/openai-python/blob/main/examples/azure_ad.py). + +## Versioning + +This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) conventions, though certain backwards-incompatible changes may be released as minor versions: + +1. Changes that only affect static types, without breaking runtime behavior. +2. Changes to library internals which are technically public but not intended or documented for external use. _(Please open a GitHub issue to let us know if you are relying on such internals.)_ +3. Changes that we do not expect to impact the vast majority of users in practice. + +We take backwards-compatibility seriously and work hard to ensure you can rely on a smooth upgrade experience. + +We are keen for your feedback; please open an [issue](https://www.github.com/openai/openai-python/issues) with questions, bugs, or suggestions. + +### Determining the installed version + +If you've upgraded to the latest version but aren't seeing any new features you were expecting then your python environment is likely still using an older version. + +You can determine the version that is being used at runtime with: + +```py +import openai +print(openai.__version__) +``` + +## Requirements + +Python 3.8 or higher. + +## Contributing + +See [the contributing documentation](https://github.com/openai/openai-python/tree/main/./CONTRIBUTING.md). diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/RECORD b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/RECORD new file mode 100644 index 0000000000000000000000000000000000000000..c2427e9ea6ffd3d4b15f986e8e2a9237bfca1295 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/RECORD @@ -0,0 +1,1839 @@ +../../../bin/openai,sha256=Gqf3fhWW20g_JStMmtd-hmPYKBEGlJt3sEAAu9ZhcK8,188 +openai-1.109.1.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4 +openai-1.109.1.dist-info/METADATA,sha256=xdtvY5rpUMWc_ewqYPdexVTV1eWEZhbGQDFxsJD7DSk,29030 +openai-1.109.1.dist-info/RECORD,, +openai-1.109.1.dist-info/WHEEL,sha256=C2FUgwZgiLbznR-k0b_5k3Ai_1aASOXDss3lzCUsUug,87 +openai-1.109.1.dist-info/entry_points.txt,sha256=kAYhQEmziJwsKs5raYAIOvJ2LWmbz5dulEXOzsY71ro,43 +openai-1.109.1.dist-info/licenses/LICENSE,sha256=1xHtN7sZrnJJr40JO4_G6nWP01VLkqxhUAwa08wOP7k,11336 +openai/__init__.py,sha256=XlxmnHgXI2-SHYrHSNTghBAUOI-186ySd8jWyRrZ0wk,11174 +openai/__main__.py,sha256=bYt9eEaoRQWdejEHFD8REx9jxVEdZptECFsV7F49Ink,30 +openai/__pycache__/__init__.cpython-313.pyc,, +openai/__pycache__/__main__.cpython-313.pyc,, +openai/__pycache__/_base_client.cpython-313.pyc,, +openai/__pycache__/_client.cpython-313.pyc,, +openai/__pycache__/_compat.cpython-313.pyc,, +openai/__pycache__/_constants.cpython-313.pyc,, +openai/__pycache__/_exceptions.cpython-313.pyc,, +openai/__pycache__/_files.cpython-313.pyc,, +openai/__pycache__/_legacy_response.cpython-313.pyc,, +openai/__pycache__/_models.cpython-313.pyc,, +openai/__pycache__/_module_client.cpython-313.pyc,, +openai/__pycache__/_qs.cpython-313.pyc,, +openai/__pycache__/_resource.cpython-313.pyc,, +openai/__pycache__/_response.cpython-313.pyc,, +openai/__pycache__/_streaming.cpython-313.pyc,, +openai/__pycache__/_types.cpython-313.pyc,, +openai/__pycache__/_version.cpython-313.pyc,, +openai/__pycache__/pagination.cpython-313.pyc,, +openai/__pycache__/version.cpython-313.pyc,, +openai/_base_client.py,sha256=VjNDJ-oPNC34F3NRHbRSVRpsQM-sazL4fljxad_5tLQ,68237 +openai/_client.py,sha256=Q3woLHUFnpMBmGOY2374w1eHRgio-pLyG9tOq-ycg4A,43458 +openai/_compat.py,sha256=k2XpUhYfgp5ZXkZkQAftJHt_UWFjUct1Sm2ye2kPBXo,6964 +openai/_constants.py,sha256=WmCwgT4tGmFsSrltb26f3bM8ftUyFYkzh32Ny5yl-So,467 +openai/_exceptions.py,sha256=TYcCxnfT7fln5duvVnCVJ0znuUHXSAbCT5sAMnaeKjU,5008 +openai/_extras/__init__.py,sha256=sainrYWujCxIyL24wNpKfMVr-ZyBPlnSZfqXcg2S6Xg,165 +openai/_extras/__pycache__/__init__.cpython-313.pyc,, +openai/_extras/__pycache__/_common.cpython-313.pyc,, +openai/_extras/__pycache__/numpy_proxy.cpython-313.pyc,, +openai/_extras/__pycache__/pandas_proxy.cpython-313.pyc,, +openai/_extras/__pycache__/sounddevice_proxy.cpython-313.pyc,, +openai/_extras/_common.py,sha256=NWWtgbdJsO3hQGQxaXGfVk0LjeIE5AFZ8VS_795hhMc,364 +openai/_extras/numpy_proxy.py,sha256=LyTZkKDdnjz0h1SKLsphrhmXyUsJ_xEUhTFMrCf7k7g,805 +openai/_extras/pandas_proxy.py,sha256=NCEt1Dqwc_0H85YdsWPDE3lPDJtYnBT8G-gJE_BCeEc,637 +openai/_extras/sounddevice_proxy.py,sha256=xDoE21YGu13dSAJJkiOM9Qdb7uOIv5zskaJRX6xciEg,725 +openai/_files.py,sha256=cQOoF0UFpnyH5JMIdu_EvGpj_dGzH1ojtJvyX7Xwqn0,3612 +openai/_legacy_response.py,sha256=fx9I0IInZY1zr2bUmpqW2ZUcL9JW2xS6S4NqFuwhdPM,16237 +openai/_models.py,sha256=3a_WIVJsJSD3NvO0w1r8ockx1aH8BETdvluPWZK9Ci8,32192 +openai/_module_client.py,sha256=bIfYb6J1rtubuqEkiZVf5zdu9RmKWQiDeudded9Ch80,4817 +openai/_qs.py,sha256=craIKyvPktJ94cvf9zn8j8ekG9dWJzhWv0ob34lIOv4,4828 +openai/_resource.py,sha256=IQihFzFLhGOiGSlT2dO1ESWSTg2XypgbtAldtGdTOqU,1100 +openai/_response.py,sha256=zLVaMPYE1o2Tz1eS5_bnJNGMikRN1byMpMcVpW1tgIU,29510 +openai/_streaming.py,sha256=eT79w7kiXCR_PGRAC9veunVnlMKau1yP0xUMUMKagp0,13390 +openai/_types.py,sha256=ducEA5cX8RYL6KegX0S9zNZIx2CvDS4kadu24_JozoM,7364 +openai/_utils/__init__.py,sha256=qiOG_n0G-sP5r5jNvD4OUaeaVLFEw5s-h7h7b0nD7Nk,2465 +openai/_utils/__pycache__/__init__.cpython-313.pyc,, +openai/_utils/__pycache__/_compat.cpython-313.pyc,, +openai/_utils/__pycache__/_datetime_parse.cpython-313.pyc,, +openai/_utils/__pycache__/_logs.cpython-313.pyc,, +openai/_utils/__pycache__/_proxy.cpython-313.pyc,, +openai/_utils/__pycache__/_reflection.cpython-313.pyc,, +openai/_utils/__pycache__/_resources_proxy.cpython-313.pyc,, +openai/_utils/__pycache__/_streams.cpython-313.pyc,, +openai/_utils/__pycache__/_sync.cpython-313.pyc,, +openai/_utils/__pycache__/_transform.cpython-313.pyc,, +openai/_utils/__pycache__/_typing.cpython-313.pyc,, +openai/_utils/__pycache__/_utils.cpython-313.pyc,, +openai/_utils/_compat.py,sha256=D8gtAvjJQrDWt9upS0XaG9Rr5l1QhiAx_I_1utT_tt0,1195 +openai/_utils/_datetime_parse.py,sha256=bABTs0Bc6rabdFvnIwXjEhWL15TcRgWZ_6XGTqN8xUk,4204 +openai/_utils/_logs.py,sha256=IC5iwPflwelNpJEpWsvK3up-pol5hR8k_VL9fSukk_Y,1351 +openai/_utils/_proxy.py,sha256=aglnj2yBTDyGX9Akk2crZHrl10oqRmceUy2Zp008XEs,1975 +openai/_utils/_reflection.py,sha256=aTXm-W0Kww4PJo5LPkUnQ92N-2UvrK1-D67cJVBlIgw,1426 +openai/_utils/_resources_proxy.py,sha256=AHHZCOgv-2CRqB4B52dB7ySlE5q6QCWj0bsTqNmzikw,589 +openai/_utils/_streams.py,sha256=SMC90diFFecpEg_zgDRVbdR3hSEIgVVij4taD-noMLM,289 +openai/_utils/_sync.py,sha256=TpGLrrhRNWTJtODNE6Fup3_k7zrWm1j2RlirzBwre-0,2862 +openai/_utils/_transform.py,sha256=hzILp2ijV9J7D-uoEDmadtyCmzMK6DprJP8IlwEg0ZY,15999 +openai/_utils/_typing.py,sha256=N_5PPuFNsaygbtA_npZd98SVN1LQQvFTKL6bkWPBZGU,4786 +openai/_utils/_utils.py,sha256=zAVS9ZzVFdWx6j2xYA9Rg1SxIuqGrAgX2OQbdWyZkIY,12668 +openai/_version.py,sha256=rA0Yl4PN3VpGj1zQ1EyLpQwebtIUjpPiMi3-IF4mKqg,160 +openai/cli/__init__.py,sha256=soGgtqyomgddl92H0KJRqHqGuaXIaghq86qkzLuVp7U,31 +openai/cli/__pycache__/__init__.cpython-313.pyc,, +openai/cli/__pycache__/_cli.cpython-313.pyc,, +openai/cli/__pycache__/_errors.cpython-313.pyc,, +openai/cli/__pycache__/_models.cpython-313.pyc,, +openai/cli/__pycache__/_progress.cpython-313.pyc,, +openai/cli/__pycache__/_utils.cpython-313.pyc,, +openai/cli/_api/__init__.py,sha256=cj92MZq-9_1PQM8A4TQVsqKn5mcTDAGxHllJ0UvJOPE,58 +openai/cli/_api/__pycache__/__init__.cpython-313.pyc,, +openai/cli/_api/__pycache__/_main.cpython-313.pyc,, +openai/cli/_api/__pycache__/audio.cpython-313.pyc,, +openai/cli/_api/__pycache__/completions.cpython-313.pyc,, +openai/cli/_api/__pycache__/files.cpython-313.pyc,, +openai/cli/_api/__pycache__/image.cpython-313.pyc,, +openai/cli/_api/__pycache__/models.cpython-313.pyc,, +openai/cli/_api/_main.py,sha256=3xVyycq-4HEYMBdMDJFk893PTXpr8yvkGL3eCiuSx8E,501 +openai/cli/_api/audio.py,sha256=0GU49a-XurLlyVEy2V9IZ_pDmjL1XEBI7Jp7fQfJ5Sk,3757 +openai/cli/_api/chat/__init__.py,sha256=MhFUQH9F6QCtbPMlbsU_DWTd7wc5DSCZ7Wy3FBGVij0,300 +openai/cli/_api/chat/__pycache__/__init__.cpython-313.pyc,, +openai/cli/_api/chat/__pycache__/completions.cpython-313.pyc,, +openai/cli/_api/chat/completions.py,sha256=GyfAo3B2w2ySV0dK9D2IIVA4fOb0zqJZadQ-Yc8a_yU,5536 +openai/cli/_api/completions.py,sha256=Jy1rlQqw__12ZfbTrnZJgoGBbDKJ58kOUAT-vkLr5kE,6334 +openai/cli/_api/files.py,sha256=6nKXFnsC2QE0bGnVUAG7BTLSu6K1_MhPE0ZJACmzgRY,2345 +openai/cli/_api/fine_tuning/__init__.py,sha256=hZeWhTZtIRAl1xgSbznjpCYy9lnUUXngh8uEIbVn__Y,286 +openai/cli/_api/fine_tuning/__pycache__/__init__.cpython-313.pyc,, +openai/cli/_api/fine_tuning/__pycache__/jobs.cpython-313.pyc,, +openai/cli/_api/fine_tuning/jobs.py,sha256=4wj9DPfw3343fJQW9j52Q-ga4jYa1haOTn4yYsH_zqk,5311 +openai/cli/_api/image.py,sha256=3UDZ1R8SjYh4IOhhdJqf20FPqPgPdhpRxqu3eo5BKhU,5014 +openai/cli/_api/models.py,sha256=pGmIGZToj3raGGpKvPSq_EVUR-dqg4Vi0PNfZH98D2E,1295 +openai/cli/_cli.py,sha256=42j_eI8PPdFbVjufluregmNYTdwrw3yQtsHtTzyNvcQ,6779 +openai/cli/_errors.py,sha256=nejlu1HnOyAIr2n7uqpFtWn8XclWj_9N8FwgfT3BPK8,471 +openai/cli/_models.py,sha256=_budygMbXh3Fv-w-TDfWecZNiKfox6f0lliCUytxE1Q,491 +openai/cli/_progress.py,sha256=aMLssU9jh-LoqRYH3608jNos7r6vZKnHTRlHxFznzv4,1406 +openai/cli/_tools/__init__.py,sha256=cj92MZq-9_1PQM8A4TQVsqKn5mcTDAGxHllJ0UvJOPE,58 +openai/cli/_tools/__pycache__/__init__.cpython-313.pyc,, +openai/cli/_tools/__pycache__/_main.cpython-313.pyc,, +openai/cli/_tools/__pycache__/fine_tunes.cpython-313.pyc,, +openai/cli/_tools/__pycache__/migrate.cpython-313.pyc,, +openai/cli/_tools/_main.py,sha256=pakjEXHRHqYlTml-RxV7fNrRtRXzmZBinoPi1AJipFY,467 +openai/cli/_tools/fine_tunes.py,sha256=RQgYMzifk6S7Y1I1K6huqco2QxmXa7gVUlHl6SrKTSU,1543 +openai/cli/_tools/migrate.py,sha256=o-iomzhtC6N6X5H5GDlgQ_QOaIovE2YA9oHc_tIAUj8,4497 +openai/cli/_utils.py,sha256=oiTc9MnxQh_zxAZ1OIHPkoDpCll0NF9ZgkdFHz4T-Bs,848 +openai/helpers/__init__.py,sha256=F0x_Pguq1XC2KXZYbfxUG-G_FxJ3mlsi7HaFZ1x-g9A,130 +openai/helpers/__pycache__/__init__.cpython-313.pyc,, +openai/helpers/__pycache__/local_audio_player.cpython-313.pyc,, +openai/helpers/__pycache__/microphone.cpython-313.pyc,, +openai/helpers/local_audio_player.py,sha256=7MWwt1BYEh579z1brnQ2mUEB0Ble4UoGMHDKusOfZJQ,5852 +openai/helpers/microphone.py,sha256=6tIHWZGpRA5XvUoer-nPBvHbrmxK7CWx3_Ta-qp1H54,3341 +openai/lib/.keep,sha256=wuNrz-5SXo3jJaJOJgz4vFHM41YH_g20F5cRQo0vLes,224 +openai/lib/__init__.py,sha256=BMTfMnlbugMgDA1STDIAlx4bI4t4l_8bQmJxd0th0n8,126 +openai/lib/__pycache__/__init__.cpython-313.pyc,, +openai/lib/__pycache__/_old_api.cpython-313.pyc,, +openai/lib/__pycache__/_pydantic.cpython-313.pyc,, +openai/lib/__pycache__/_tools.cpython-313.pyc,, +openai/lib/__pycache__/_validators.cpython-313.pyc,, +openai/lib/__pycache__/azure.cpython-313.pyc,, +openai/lib/_old_api.py,sha256=XZnXBrEKuTd70iJirj5mGW35fZoqruJobbBTq6bvg10,1947 +openai/lib/_parsing/__init__.py,sha256=wS3BYvMGj9TqiPqOe3rO1sleaAJqHVuCaQuCE5rZIUw,539 +openai/lib/_parsing/__pycache__/__init__.cpython-313.pyc,, +openai/lib/_parsing/__pycache__/_completions.cpython-313.pyc,, +openai/lib/_parsing/__pycache__/_responses.cpython-313.pyc,, +openai/lib/_parsing/_completions.py,sha256=3vihFrFWJIrToaWYjJMqn42gTyNmrQhXvi2vr5Wduo8,10629 +openai/lib/_parsing/_responses.py,sha256=uweKd5rcBfkl_Kv6DCQdvGGW6ZR2M5dUStsVla_HAUI,6005 +openai/lib/_pydantic.py,sha256=Cf0vGwuWdNEuIUg8WNREjWRGApMObgl8DjdLU4f5jAc,5623 +openai/lib/_tools.py,sha256=Dc4U2TXKvfAvVUvDS30SDeftrwgGM2vZ85t5ojLHiEg,1969 +openai/lib/_validators.py,sha256=cXJXFuaAl7jeJcYHXXnFa4NHGtHs-_zt3Zs1VVCmQo4,35288 +openai/lib/azure.py,sha256=dLzUXTXUOnfarLdDyO6dVzp8wY2vTMFFHUJZLuFznWY,26537 +openai/lib/streaming/__init__.py,sha256=kD3LpjsqU7caDQDhB-YjTUl9qqbb5sPnGGSI2yQYC70,379 +openai/lib/streaming/__pycache__/__init__.cpython-313.pyc,, +openai/lib/streaming/__pycache__/_assistants.cpython-313.pyc,, +openai/lib/streaming/__pycache__/_deltas.cpython-313.pyc,, +openai/lib/streaming/_assistants.py,sha256=LUWSinmYopQIkQ5xSg73b6BWbkRkQS5JvX62w_V9xSw,40692 +openai/lib/streaming/_deltas.py,sha256=I7B_AznXZwlBmE8Puau7ayTQUx6hMIEVE8FYTQm2fjs,2502 +openai/lib/streaming/chat/__init__.py,sha256=7krL_atOvvpQkY_byWSglSfDsMs5hdoxHmz4Ulq7lcc,1305 +openai/lib/streaming/chat/__pycache__/__init__.cpython-313.pyc,, +openai/lib/streaming/chat/__pycache__/_completions.cpython-313.pyc,, +openai/lib/streaming/chat/__pycache__/_events.cpython-313.pyc,, +openai/lib/streaming/chat/__pycache__/_types.cpython-313.pyc,, +openai/lib/streaming/chat/_completions.py,sha256=4PDLu_1-wQOrAwHY-Gz8NIQ8UnJ9gshwrmxuMDesFp8,30775 +openai/lib/streaming/chat/_events.py,sha256=lstVmM6YR2Cs9drikzrY9JCZn9Nbfym0aKIPtNpxL6w,2618 +openai/lib/streaming/chat/_types.py,sha256=-SYVBNhGkOUoJ-8dotxpCRqPJpfyOQ8hwR2_HrsQCRI,739 +openai/lib/streaming/responses/__init__.py,sha256=MwE1Oc3OIiXjtuRFsuP_k5Ra8pNiqKpc1GZum-8ZRJM,543 +openai/lib/streaming/responses/__pycache__/__init__.cpython-313.pyc,, +openai/lib/streaming/responses/__pycache__/_events.cpython-313.pyc,, +openai/lib/streaming/responses/__pycache__/_responses.cpython-313.pyc,, +openai/lib/streaming/responses/__pycache__/_types.cpython-313.pyc,, +openai/lib/streaming/responses/_events.py,sha256=3UWmeYgg23E3XTkYVlrpXJPnhBM2kmQFoXh3WiT9CrE,5576 +openai/lib/streaming/responses/_responses.py,sha256=Myeo4so-aMFrzEyNCjX0ypYWTWvY5uDelhe2ygC93lY,13614 +openai/lib/streaming/responses/_types.py,sha256=msq1KWj3e3BLn7NKu5j2kzHgj9kShuoitgXEyTmQxus,276 +openai/pagination.py,sha256=dtPji3wApb_0rkvYDwh50rl8cjxT3i6EUS6PfTXwhQI,4770 +openai/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0 +openai/resources/__init__.py,sha256=3vxUFYFi0I0JQ1tbQ8irmHiHCNd4sJ1Pc0_EnVk2SxE,5713 +openai/resources/__pycache__/__init__.cpython-313.pyc,, +openai/resources/__pycache__/batches.cpython-313.pyc,, +openai/resources/__pycache__/completions.cpython-313.pyc,, +openai/resources/__pycache__/embeddings.cpython-313.pyc,, +openai/resources/__pycache__/files.cpython-313.pyc,, +openai/resources/__pycache__/images.cpython-313.pyc,, +openai/resources/__pycache__/models.cpython-313.pyc,, +openai/resources/__pycache__/moderations.cpython-313.pyc,, +openai/resources/__pycache__/webhooks.cpython-313.pyc,, +openai/resources/audio/__init__.py,sha256=YM7FHvPKVlj_v6EIgfpUQsb6q4hS2hVQ3gfkgic0sP0,1687 +openai/resources/audio/__pycache__/__init__.cpython-313.pyc,, +openai/resources/audio/__pycache__/audio.cpython-313.pyc,, +openai/resources/audio/__pycache__/speech.cpython-313.pyc,, +openai/resources/audio/__pycache__/transcriptions.cpython-313.pyc,, +openai/resources/audio/__pycache__/translations.cpython-313.pyc,, +openai/resources/audio/audio.py,sha256=nEIB4q7a1MSYdQkcYH2O6jB-_rNCMDCBJyUuqOL67CI,5491 +openai/resources/audio/speech.py,sha256=ajss0PEI4CnOhYO5tGtZEodIBh4PDh21bhQ7w4uYyjU,10172 +openai/resources/audio/transcriptions.py,sha256=btyG4K9bSpTsNNC62_Pe4P-Jiqma8W9938O5YIq5W7A,39217 +openai/resources/audio/translations.py,sha256=0OJJh5-lQN-0G5DqqPKbhWU7WuOf1yqAb3XiJ4ipp2k,15499 +openai/resources/batches.py,sha256=0WyWzYyxdEj0nuRk5Fnreb_6mLx1Zo7-2OzyxQg_yss,20854 +openai/resources/beta/__init__.py,sha256=rQz4y41YG2U8oSunK-nWrWBNbE_sIiEAjSLMzLIf4gU,1203 +openai/resources/beta/__pycache__/__init__.cpython-313.pyc,, +openai/resources/beta/__pycache__/assistants.cpython-313.pyc,, +openai/resources/beta/__pycache__/beta.cpython-313.pyc,, +openai/resources/beta/assistants.py,sha256=bCFwib270D_8J3B9Wl3sMEqUIX1OznVAIGIAUI9lHPY,45641 +openai/resources/beta/beta.py,sha256=YyQeQiy7gdy6vyG9Q0AUqCzFb6Ow1BFKXj6QvtHFhDI,4771 +openai/resources/beta/realtime/__init__.py,sha256=dOXRjPiDqRJXIFoGKSVjzKh3IwSXnLbwHx4ND5OdnVs,1412 +openai/resources/beta/realtime/__pycache__/__init__.cpython-313.pyc,, +openai/resources/beta/realtime/__pycache__/realtime.cpython-313.pyc,, +openai/resources/beta/realtime/__pycache__/sessions.cpython-313.pyc,, +openai/resources/beta/realtime/__pycache__/transcription_sessions.cpython-313.pyc,, +openai/resources/beta/realtime/realtime.py,sha256=tuiq_0PdFmC2p-LNOfQNrVuDEMlLAHKEgeAsPsHLUHU,43694 +openai/resources/beta/realtime/sessions.py,sha256=XwW877IGqRZDl5DB055KcrrAsz4YrFoVTVF40tgMxVQ,21964 +openai/resources/beta/realtime/transcription_sessions.py,sha256=uTDGEat50lojdD0N8slnZu2RVzMP96rlicpDp4tpl34,14124 +openai/resources/beta/threads/__init__.py,sha256=fQ_qdUVSfouVS5h47DlTb5mamChT4K-v-siPuuAB6do,1177 +openai/resources/beta/threads/__pycache__/__init__.cpython-313.pyc,, +openai/resources/beta/threads/__pycache__/messages.cpython-313.pyc,, +openai/resources/beta/threads/__pycache__/threads.cpython-313.pyc,, +openai/resources/beta/threads/messages.py,sha256=a8HEG-QKIgG8r4XtE0M7ixRBikAmdQEUDWUDf1gkaSg,30794 +openai/resources/beta/threads/runs/__init__.py,sha256=2FfDaqwmJJCd-IVpY_CrzWcFvw0KFyQ3cm5jnTfI-DQ,771 +openai/resources/beta/threads/runs/__pycache__/__init__.cpython-313.pyc,, +openai/resources/beta/threads/runs/__pycache__/runs.cpython-313.pyc,, +openai/resources/beta/threads/runs/__pycache__/steps.cpython-313.pyc,, +openai/resources/beta/threads/runs/runs.py,sha256=xKoMlwFOq7JaSxLmY51pI7FVrbQp4ZA7GhEPi6SnGrU,152061 +openai/resources/beta/threads/runs/steps.py,sha256=YkoPMeMXEzoL09AWF7Eh1lNaJocykV1igmcsZpXKw5Y,16981 +openai/resources/beta/threads/threads.py,sha256=3C3OzlgL0S1mDdnRBowU14Di8W7T81C2BEGFm5Mx42Y,97651 +openai/resources/chat/__init__.py,sha256=8Q9ODRo1wIpFa34VaNwuaWFmxqFxagDtUhIAkQNvxEU,849 +openai/resources/chat/__pycache__/__init__.cpython-313.pyc,, +openai/resources/chat/__pycache__/chat.cpython-313.pyc,, +openai/resources/chat/chat.py,sha256=HjcasSCmt-g3-J-RkZQ9HRj_-hPfImakFxdUvvk5mCg,3364 +openai/resources/chat/completions/__init__.py,sha256=KOi8blzNyHWD7nKgcoW3CxZ4428IcNVP0gCU74HySf8,901 +openai/resources/chat/completions/__pycache__/__init__.cpython-313.pyc,, +openai/resources/chat/completions/__pycache__/completions.cpython-313.pyc,, +openai/resources/chat/completions/__pycache__/messages.cpython-313.pyc,, +openai/resources/chat/completions/completions.py,sha256=Pq_CaOcQku6LlhsRrELDV2X8MwNI3gsYSONYOF_j3VY,157706 +openai/resources/chat/completions/messages.py,sha256=AYVwQ24jPQGs2Y-vE6Yjl5nbCECtuw-HpcBEEpCgC-0,8010 +openai/resources/completions.py,sha256=wO39_sLxmSzTI6Mp13KzjqaxMgFZw4l-t0_9xxDbX_4,59201 +openai/resources/containers/__init__.py,sha256=7VzY-TFwG3x5D_kUCs_iAQaaCKAswt1Jk70KpmnU8Do,849 +openai/resources/containers/__pycache__/__init__.cpython-313.pyc,, +openai/resources/containers/__pycache__/containers.cpython-313.pyc,, +openai/resources/containers/containers.py,sha256=yz2zZoHT_rjXh-_Ij2-shBgerSkal61DqA1TNWkDqog,19240 +openai/resources/containers/files/__init__.py,sha256=nDhg0wY7eHRMO-xOErno0mV0Ya_ynlmKAp-4a3nj-us,810 +openai/resources/containers/files/__pycache__/__init__.cpython-313.pyc,, +openai/resources/containers/files/__pycache__/content.cpython-313.pyc,, +openai/resources/containers/files/__pycache__/files.cpython-313.pyc,, +openai/resources/containers/files/content.py,sha256=-jupriq97X2kq_yCdYihZ1h2qCx-IMbaaR10M4lz6TA,6491 +openai/resources/containers/files/files.py,sha256=jjiRGS489CzoOXb3nvsD-i3qTSINE9CrAo2jZPWxyLI,21042 +openai/resources/conversations/__init__.py,sha256=Uslb4pakT8pQJGQ29CvoiN-SvN2AgMum-TeIDyYTzQE,888 +openai/resources/conversations/__pycache__/__init__.cpython-313.pyc,, +openai/resources/conversations/__pycache__/conversations.cpython-313.pyc,, +openai/resources/conversations/__pycache__/items.cpython-313.pyc,, +openai/resources/conversations/conversations.py,sha256=IjnSvilsJG_yK4IoRP86R6_5MFlHSpZt6lWxgpbGP-Y,19151 +openai/resources/conversations/items.py,sha256=q3XbPsh09Gb9qYisb6BEa9BExX4HF5oMu-Z0khdAFlY,23969 +openai/resources/embeddings.py,sha256=GYA_sI2h5auPwyHKm44-brPxRxqvcQaH0JQMZW13bMA,12374 +openai/resources/evals/__init__.py,sha256=DXhYb6mCKKY2bDdS3s4raH1SvwPUyaBFvdHgPEbwRWY,771 +openai/resources/evals/__pycache__/__init__.cpython-313.pyc,, +openai/resources/evals/__pycache__/evals.cpython-313.pyc,, +openai/resources/evals/evals.py,sha256=goQ9ek2_xI34SG7GkwpqKhXO2hZouq5bxS26EejY-cI,25904 +openai/resources/evals/runs/__init__.py,sha256=7EtKZ43tGlmAOYyDdyFXy80tk2X8AmXb5taTWRRXBXE,850 +openai/resources/evals/runs/__pycache__/__init__.cpython-313.pyc,, +openai/resources/evals/runs/__pycache__/output_items.cpython-313.pyc,, +openai/resources/evals/runs/__pycache__/runs.cpython-313.pyc,, +openai/resources/evals/runs/output_items.py,sha256=7pcGpGc61Df4jQIgxRYLX-27wz_8qc0Ux-ni_EfVvwA,12530 +openai/resources/evals/runs/runs.py,sha256=228Vf9S8_dz0tZAWCh2ehECQYg_Z4JXNV5MRuvUtDh4,24359 +openai/resources/files.py,sha256=s0LrzYQxKzuw1oSPI4wPXEXqSvsSAdnyzAbsL9lzvv4,30298 +openai/resources/fine_tuning/__init__.py,sha256=RQPC5QfqE-ByhRQbJK-j7ooUrkBO9s9bKt5xkzOL8ls,1597 +openai/resources/fine_tuning/__pycache__/__init__.cpython-313.pyc,, +openai/resources/fine_tuning/__pycache__/fine_tuning.cpython-313.pyc,, +openai/resources/fine_tuning/alpha/__init__.py,sha256=QKAYZscx1Fw3GLD8cVdZAYG9L_i6MnPGeifn8GgcztU,810 +openai/resources/fine_tuning/alpha/__pycache__/__init__.cpython-313.pyc,, +openai/resources/fine_tuning/alpha/__pycache__/alpha.cpython-313.pyc,, +openai/resources/fine_tuning/alpha/__pycache__/graders.cpython-313.pyc,, +openai/resources/fine_tuning/alpha/alpha.py,sha256=P-zLOHpI-Aa0jUUWspkanL7WpUtfjwIGDH8KTGDNeHY,3274 +openai/resources/fine_tuning/alpha/graders.py,sha256=TA39PsdXWjxsts6p_UjPhyTwE4a1O7nQOkUC0V2ZHbU,10758 +openai/resources/fine_tuning/checkpoints/__init__.py,sha256=rvsbut5FCQNAr-VjvL-14GFT3Tld49FlFuBJDpfxBug,940 +openai/resources/fine_tuning/checkpoints/__pycache__/__init__.cpython-313.pyc,, +openai/resources/fine_tuning/checkpoints/__pycache__/checkpoints.cpython-313.pyc,, +openai/resources/fine_tuning/checkpoints/__pycache__/permissions.cpython-313.pyc,, +openai/resources/fine_tuning/checkpoints/checkpoints.py,sha256=njpz496JifeZ8RXjoYUb1Tj9tBItuXRxGJHW2jrrfwo,3606 +openai/resources/fine_tuning/checkpoints/permissions.py,sha256=A9SfSQk7o0gbqhu2NMZTW53Tq5c3zbBDSgL_0K0t1WQ,17103 +openai/resources/fine_tuning/fine_tuning.py,sha256=UL4MXoUqEnbSZ5e4dnbUPTtd4tE-1p2L7Hh_0CQ_0s0,5410 +openai/resources/fine_tuning/jobs/__init__.py,sha256=_smlrwijZOCcsDWqKnofLxQM2QLucZzXgboL9zJBPHw,849 +openai/resources/fine_tuning/jobs/__pycache__/__init__.cpython-313.pyc,, +openai/resources/fine_tuning/jobs/__pycache__/checkpoints.cpython-313.pyc,, +openai/resources/fine_tuning/jobs/__pycache__/jobs.cpython-313.pyc,, +openai/resources/fine_tuning/jobs/checkpoints.py,sha256=-QQNOZJplnCJyHCFTFO-DMN-AWc1Dp8p9Hifffgz5a0,7442 +openai/resources/fine_tuning/jobs/jobs.py,sha256=jIXuCijf7v9ufH3SqgWBrQAFg5uqPKAuyXgNDmLEXK4,37033 +openai/resources/images.py,sha256=M-9aHweEET--pH6fqHhLM4JUQR1HQUOOdsdm00GuoaA,95349 +openai/resources/models.py,sha256=1PDMpmdtaGiNHZNWPL-sI_I-SDOjuK-yfm2oq7mKiGI,11232 +openai/resources/moderations.py,sha256=8BWoTw8QHsSUbgByBlLxHHYEeeozFsY8n3j-ah13YdI,7808 +openai/resources/realtime/__init__.py,sha256=c4zQkJRr5mnDpJtVkY4w7abaPQaTNIw7DJ-h1XFWiAM,928 +openai/resources/realtime/__pycache__/__init__.cpython-313.pyc,, +openai/resources/realtime/__pycache__/client_secrets.cpython-313.pyc,, +openai/resources/realtime/__pycache__/realtime.cpython-313.pyc,, +openai/resources/realtime/client_secrets.py,sha256=Z8NmSg2GGN3we3w89Un26jWp5OO9lxOi8oS4lSYMrUg,7700 +openai/resources/realtime/realtime.py,sha256=nkKUhrA6nVDo83KkXrQV_yC6yD-4Gnx_GpuqKwtVH1E,42853 +openai/resources/responses/__init__.py,sha256=nqybLst4yLblEyC-vAJYOVgM2X4BvcFmgluRNqOGIhk,902 +openai/resources/responses/__pycache__/__init__.cpython-313.pyc,, +openai/resources/responses/__pycache__/input_items.cpython-313.pyc,, +openai/resources/responses/__pycache__/responses.cpython-313.pyc,, +openai/resources/responses/input_items.py,sha256=tzg31yUowcCMqU32TBHI18YzRjqNs_EGwKdpSU8bSTs,8774 +openai/resources/responses/responses.py,sha256=8zjpVTDeeGMa9rBXdC9hwookwgUVB4PsYTgeS0t2kyY,155491 +openai/resources/uploads/__init__.py,sha256=HmY3WQgvUI2bN3CjfWHWQOk7UUC6Ozna97_lHhrrRSA,810 +openai/resources/uploads/__pycache__/__init__.cpython-313.pyc,, +openai/resources/uploads/__pycache__/parts.cpython-313.pyc,, +openai/resources/uploads/__pycache__/uploads.cpython-313.pyc,, +openai/resources/uploads/parts.py,sha256=2Vov0reg5wdOSGSJ7hhs9pqsIofkhqjoUoE_AgXHLZM,8121 +openai/resources/uploads/uploads.py,sha256=cG6VELxImBy_6sxD1VH20dWzk2fNJJ9NaIUzx8pXJNk,25501 +openai/resources/vector_stores/__init__.py,sha256=11Xn1vhgndWiI0defJHv31vmbtbDgh2GwZT3gX8GgHk,1296 +openai/resources/vector_stores/__pycache__/__init__.cpython-313.pyc,, +openai/resources/vector_stores/__pycache__/file_batches.cpython-313.pyc,, +openai/resources/vector_stores/__pycache__/files.cpython-313.pyc,, +openai/resources/vector_stores/__pycache__/vector_stores.cpython-313.pyc,, +openai/resources/vector_stores/file_batches.py,sha256=M1SzkpjCBFgn8aYryQeZl49k_mCv-IG20-s5ddGh1-c,32942 +openai/resources/vector_stores/files.py,sha256=xJStwcbKIzVzqIXK7G-Mfll61wbt154SObua945XXEI,39703 +openai/resources/vector_stores/vector_stores.py,sha256=zIAovVVYjmV48JFrTqLUmORmEQfdHayylWdIOyR4WK4,35023 +openai/resources/webhooks.py,sha256=wz3filqxxUEhhW5RSa-1LiN10MzafKXJPl5-Wb1mCew,7820 +openai/types/__init__.py,sha256=r4ftepF2GBzDtkmXwvkG6-HIg5wvz6wr9x2ulnB8fVE,6873 +openai/types/__pycache__/__init__.cpython-313.pyc,, +openai/types/__pycache__/audio_model.cpython-313.pyc,, +openai/types/__pycache__/audio_response_format.cpython-313.pyc,, +openai/types/__pycache__/auto_file_chunking_strategy_param.cpython-313.pyc,, +openai/types/__pycache__/batch.cpython-313.pyc,, +openai/types/__pycache__/batch_create_params.cpython-313.pyc,, +openai/types/__pycache__/batch_error.cpython-313.pyc,, +openai/types/__pycache__/batch_list_params.cpython-313.pyc,, +openai/types/__pycache__/batch_request_counts.cpython-313.pyc,, +openai/types/__pycache__/chat_model.cpython-313.pyc,, +openai/types/__pycache__/completion.cpython-313.pyc,, +openai/types/__pycache__/completion_choice.cpython-313.pyc,, +openai/types/__pycache__/completion_create_params.cpython-313.pyc,, +openai/types/__pycache__/completion_usage.cpython-313.pyc,, +openai/types/__pycache__/container_create_params.cpython-313.pyc,, +openai/types/__pycache__/container_create_response.cpython-313.pyc,, +openai/types/__pycache__/container_list_params.cpython-313.pyc,, +openai/types/__pycache__/container_list_response.cpython-313.pyc,, +openai/types/__pycache__/container_retrieve_response.cpython-313.pyc,, +openai/types/__pycache__/create_embedding_response.cpython-313.pyc,, +openai/types/__pycache__/embedding.cpython-313.pyc,, +openai/types/__pycache__/embedding_create_params.cpython-313.pyc,, +openai/types/__pycache__/embedding_model.cpython-313.pyc,, +openai/types/__pycache__/eval_create_params.cpython-313.pyc,, +openai/types/__pycache__/eval_create_response.cpython-313.pyc,, +openai/types/__pycache__/eval_custom_data_source_config.cpython-313.pyc,, +openai/types/__pycache__/eval_delete_response.cpython-313.pyc,, +openai/types/__pycache__/eval_list_params.cpython-313.pyc,, +openai/types/__pycache__/eval_list_response.cpython-313.pyc,, +openai/types/__pycache__/eval_retrieve_response.cpython-313.pyc,, +openai/types/__pycache__/eval_stored_completions_data_source_config.cpython-313.pyc,, +openai/types/__pycache__/eval_update_params.cpython-313.pyc,, +openai/types/__pycache__/eval_update_response.cpython-313.pyc,, +openai/types/__pycache__/file_chunking_strategy.cpython-313.pyc,, +openai/types/__pycache__/file_chunking_strategy_param.cpython-313.pyc,, +openai/types/__pycache__/file_content.cpython-313.pyc,, +openai/types/__pycache__/file_create_params.cpython-313.pyc,, +openai/types/__pycache__/file_deleted.cpython-313.pyc,, +openai/types/__pycache__/file_list_params.cpython-313.pyc,, +openai/types/__pycache__/file_object.cpython-313.pyc,, +openai/types/__pycache__/file_purpose.cpython-313.pyc,, +openai/types/__pycache__/image.cpython-313.pyc,, +openai/types/__pycache__/image_create_variation_params.cpython-313.pyc,, +openai/types/__pycache__/image_edit_completed_event.cpython-313.pyc,, +openai/types/__pycache__/image_edit_params.cpython-313.pyc,, +openai/types/__pycache__/image_edit_partial_image_event.cpython-313.pyc,, +openai/types/__pycache__/image_edit_stream_event.cpython-313.pyc,, +openai/types/__pycache__/image_gen_completed_event.cpython-313.pyc,, +openai/types/__pycache__/image_gen_partial_image_event.cpython-313.pyc,, +openai/types/__pycache__/image_gen_stream_event.cpython-313.pyc,, +openai/types/__pycache__/image_generate_params.cpython-313.pyc,, +openai/types/__pycache__/image_model.cpython-313.pyc,, +openai/types/__pycache__/images_response.cpython-313.pyc,, +openai/types/__pycache__/model.cpython-313.pyc,, +openai/types/__pycache__/model_deleted.cpython-313.pyc,, +openai/types/__pycache__/moderation.cpython-313.pyc,, +openai/types/__pycache__/moderation_create_params.cpython-313.pyc,, +openai/types/__pycache__/moderation_create_response.cpython-313.pyc,, +openai/types/__pycache__/moderation_image_url_input_param.cpython-313.pyc,, +openai/types/__pycache__/moderation_model.cpython-313.pyc,, +openai/types/__pycache__/moderation_multi_modal_input_param.cpython-313.pyc,, +openai/types/__pycache__/moderation_text_input_param.cpython-313.pyc,, +openai/types/__pycache__/other_file_chunking_strategy_object.cpython-313.pyc,, +openai/types/__pycache__/static_file_chunking_strategy.cpython-313.pyc,, +openai/types/__pycache__/static_file_chunking_strategy_object.cpython-313.pyc,, +openai/types/__pycache__/static_file_chunking_strategy_object_param.cpython-313.pyc,, +openai/types/__pycache__/static_file_chunking_strategy_param.cpython-313.pyc,, +openai/types/__pycache__/upload.cpython-313.pyc,, +openai/types/__pycache__/upload_complete_params.cpython-313.pyc,, +openai/types/__pycache__/upload_create_params.cpython-313.pyc,, +openai/types/__pycache__/vector_store.cpython-313.pyc,, +openai/types/__pycache__/vector_store_create_params.cpython-313.pyc,, +openai/types/__pycache__/vector_store_deleted.cpython-313.pyc,, +openai/types/__pycache__/vector_store_list_params.cpython-313.pyc,, +openai/types/__pycache__/vector_store_search_params.cpython-313.pyc,, +openai/types/__pycache__/vector_store_search_response.cpython-313.pyc,, +openai/types/__pycache__/vector_store_update_params.cpython-313.pyc,, +openai/types/__pycache__/websocket_connection_options.cpython-313.pyc,, +openai/types/audio/__init__.py,sha256=l_ZTfiqnguKJfEEb61zegs8QsVdW9MlIkGkn8jIDRlU,1426 +openai/types/audio/__pycache__/__init__.cpython-313.pyc,, +openai/types/audio/__pycache__/speech_create_params.cpython-313.pyc,, +openai/types/audio/__pycache__/speech_model.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_create_params.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_create_response.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_include.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_segment.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_stream_event.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_text_delta_event.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_text_done_event.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_verbose.cpython-313.pyc,, +openai/types/audio/__pycache__/transcription_word.cpython-313.pyc,, +openai/types/audio/__pycache__/translation.cpython-313.pyc,, +openai/types/audio/__pycache__/translation_create_params.cpython-313.pyc,, +openai/types/audio/__pycache__/translation_create_response.cpython-313.pyc,, +openai/types/audio/__pycache__/translation_verbose.cpython-313.pyc,, +openai/types/audio/speech_create_params.py,sha256=u7FQabjLOgNhZu4FMyk1sa9qbadrmWzc-VnSesZXz3M,1780 +openai/types/audio/speech_model.py,sha256=i_YqCZ4AWN0jCY70F8FAazQAsbQyG-VUQGxSJnLsviw,237 +openai/types/audio/transcription.py,sha256=lUl3qdjgrK94zCjgpD4f9xa9w-vNhOTxh9hPeYj3ymc,2102 +openai/types/audio/transcription_create_params.py,sha256=f9UYHgxv1NY6CxvO2Nw0UuGMDkYqdb1PfipJnFc0idE,5682 +openai/types/audio/transcription_create_response.py,sha256=-PLGH8he9EdJtvBXV-ZrE31CLVnk4bc0VQ1ixRoN8Ck,378 +openai/types/audio/transcription_include.py,sha256=mclUP_50njW7TG4d9m_E6zSjAFW8djPJ6ZTYub71kq0,227 +openai/types/audio/transcription_segment.py,sha256=-pPAGolwIIXUBMic-H5U7aR0u_Aq-pipSA4xTtn_viA,1153 +openai/types/audio/transcription_stream_event.py,sha256=e0ZMA1Ls5bR4C5NnPxZxfs-xiSczi8hrWMaF27pneUU,536 +openai/types/audio/transcription_text_delta_event.py,sha256=jbfzVsjefZm64HAHXkKm4QskXxNqeEPj23xRt1clqvc,1075 +openai/types/audio/transcription_text_done_event.py,sha256=Q2-fKHeO_niBWWSCl-ZehKKz9DDM7KEimBx5Ha5e4t8,1940 +openai/types/audio/transcription_verbose.py,sha256=Dm5rPAMeMD-ZwijA8xff34QdOGLiRD5J2CN9R_dTIRo,1114 +openai/types/audio/transcription_word.py,sha256=s2aWssAgHjMOZHhiihs1m4gYWQpjBP2rkI1DE5eZBXc,367 +openai/types/audio/translation.py,sha256=Dlu9YMo0cc44NSCAtLfZnEugkM7VBA6zw2v9bfrLMh0,193 +openai/types/audio/translation_create_params.py,sha256=ejrom_64QOe47gZtrYmDAQkb65wLaZL4-iU-mKVTVq0,1572 +openai/types/audio/translation_create_response.py,sha256=x6H0yjTbZR3vd3d7LdABcn9nrMDNdeMjepcjW1oUfVc,362 +openai/types/audio/translation_verbose.py,sha256=lGB5FqkV-ne__aaGbMTFbEciJ-Sl3wBhlKmETmtROT8,615 +openai/types/audio_model.py,sha256=suo0Ei6ODS2ksMRicXAzCfuDTGcbiMjwzVLi-bf4A6s,255 +openai/types/audio_response_format.py,sha256=EEItnQdwXinG8bOe1We2039Z7lp2Z8wSXXvTlFlkXzM,259 +openai/types/auto_file_chunking_strategy_param.py,sha256=hbBtARkJXSJE7_4RqC-ZR3NiztUp9S4WuG3s3W0GpqY,351 +openai/types/batch.py,sha256=FuGQ-x8kK6VMyYIQeP5gu_LEmfzXMCht5ySHdFfJQnE,2880 +openai/types/batch_create_params.py,sha256=p5qhTnzYVsAcXFuCj4Qyk3yPIo-FxSllTecdidq3dSs,2467 +openai/types/batch_error.py,sha256=Xxl-gYm0jerpYyI-mKSSVxRMQRubkoLUiOP9U3v72EM,622 +openai/types/batch_list_params.py,sha256=X1_sfRspuIMSDyXWVh0YnJ9vJLeOOH66TrvgEHueC84,705 +openai/types/batch_request_counts.py,sha256=u_a_hehmqYE6N6lA3MfvF1-CVzR9phiMlHgh_sRff0Y,408 +openai/types/beta/__init__.py,sha256=uCm_uj8IYmxFZYD9tmGcEqpeEKnlzo64pNHcwdvnNv0,2328 +openai/types/beta/__pycache__/__init__.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_create_params.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_deleted.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_list_params.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_response_format_option.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_response_format_option_param.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_stream_event.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice_function.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice_function_param.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice_option.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice_option_param.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_choice_param.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_tool_param.cpython-313.pyc,, +openai/types/beta/__pycache__/assistant_update_params.cpython-313.pyc,, +openai/types/beta/__pycache__/code_interpreter_tool.cpython-313.pyc,, +openai/types/beta/__pycache__/code_interpreter_tool_param.cpython-313.pyc,, +openai/types/beta/__pycache__/file_search_tool.cpython-313.pyc,, +openai/types/beta/__pycache__/file_search_tool_param.cpython-313.pyc,, +openai/types/beta/__pycache__/function_tool.cpython-313.pyc,, +openai/types/beta/__pycache__/function_tool_param.cpython-313.pyc,, +openai/types/beta/__pycache__/thread.cpython-313.pyc,, +openai/types/beta/__pycache__/thread_create_and_run_params.cpython-313.pyc,, +openai/types/beta/__pycache__/thread_create_params.cpython-313.pyc,, +openai/types/beta/__pycache__/thread_deleted.cpython-313.pyc,, +openai/types/beta/__pycache__/thread_update_params.cpython-313.pyc,, +openai/types/beta/assistant.py,sha256=_OgFKmjaMXM2yNOTFTcCj5qVo_-F9p7uiEXJnYbB0XE,5054 +openai/types/beta/assistant_create_params.py,sha256=vmQlDewm-Zoa8jjZc4FGV_ocGtXlMbIaqShJHbpwsf4,7948 +openai/types/beta/assistant_deleted.py,sha256=bTTUl5FPHTBI5nRm7d0sGuR9VCSBDZ-IbOn9G_IpmJQ,301 +openai/types/beta/assistant_list_params.py,sha256=yW-lj6AUkG0IRZQKre0veEr9p4VMN-9YdELFMYs74Cw,1222 +openai/types/beta/assistant_response_format_option.py,sha256=yNeoAWxM-_8Sjmwqu8exqyKRFhVZIKeTypetPY55VFA,561 +openai/types/beta/assistant_response_format_option_param.py,sha256=dyPMhwRSLBZ0ltpxiD7KM-9X6BzWnbGeG-nT_3SenuQ,628 +openai/types/beta/assistant_stream_event.py,sha256=vP4LDqYWzSKGcZ1JAfyNw7YqC__XsVPe0nqZ2qdn93E,6930 +openai/types/beta/assistant_tool.py,sha256=_0FC7Db4Ctq_0yLaKJ93zNTB5HthuJWEAHx3fadDRlw,506 +openai/types/beta/assistant_tool_choice.py,sha256=Hy4HIfPQCkWD8VruHHicuTkomNwljGHviQHk36prKhg,544 +openai/types/beta/assistant_tool_choice_function.py,sha256=p5YEbTnED_kZpPfj5fMQqWSgLXAUEajsDd0LXGdlENU,269 +openai/types/beta/assistant_tool_choice_function_param.py,sha256=-O38277LhSaqOVhTp0haHP0ZnVTLpEBvcLJa5MRo7wE,355 +openai/types/beta/assistant_tool_choice_option.py,sha256=jrXMd_IYIQ1pt8Lkc-KrPd4CR3lR8sFV4m7_lpG8A4Y,362 +openai/types/beta/assistant_tool_choice_option_param.py,sha256=VcatO5Nej9e5eqfrwetG4uM1vFoewnBEcFz47IxAK2E,424 +openai/types/beta/assistant_tool_choice_param.py,sha256=NOWx9SzZEwYaHeAyFZTQlG3pmogMNXzjPJDGQUlbv7Q,572 +openai/types/beta/assistant_tool_param.py,sha256=6DcaU3nMjurur2VkVIYcCaRAY1QLQscXXjCd0ZHHGho,501 +openai/types/beta/assistant_update_params.py,sha256=HMgyYQ9tNL9ab33VacvsJV1o1ebKXxAzOuva7wWx2Ck,6646 +openai/types/beta/chat/__init__.py,sha256=OKfJYcKb4NObdiRObqJV_dOyDQ8feXekDUge2o_4pXQ,122 +openai/types/beta/chat/__pycache__/__init__.cpython-313.pyc,, +openai/types/beta/code_interpreter_tool.py,sha256=7mgQc9OtD_ZUnZeNhoobMFcmmvtZPFCNYGB-PEnNnfs,333 +openai/types/beta/code_interpreter_tool_param.py,sha256=X6mwzFyZx1RCKEYbBCPs4kh_tZkxFxydPMK4yFNJkLs,389 +openai/types/beta/file_search_tool.py,sha256=5aNU8RZj-UNdmuqqpjCXNaa1pI9GzSP5qCPtvVSJ1oQ,1769 +openai/types/beta/file_search_tool_param.py,sha256=o6sWPrzRYY8wtNaVuF8h3D1sAQV3N0L3dbdiiaMisW0,1765 +openai/types/beta/function_tool.py,sha256=oYGJfcfPpUohKw2ikgshDjOI1HXCK-5pAWyegYNezeU,397 +openai/types/beta/function_tool_param.py,sha256=hCclpGO4Re-TxiGy_QxX75g1kcN6_ElubicO6SdJ_YI,471 +openai/types/beta/realtime/__init__.py,sha256=trJb-lqh3vHHMYdohrgiU2cHwReFZyw4cXM-Xj8Dwq8,7364 +openai/types/beta/realtime/__pycache__/__init__.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_created_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_content.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_content_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_create_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_create_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_created_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_delete_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_delete_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_deleted_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_input_audio_transcription_completed_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_input_audio_transcription_delta_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_input_audio_transcription_failed_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_retrieve_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_retrieve_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_truncate_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_truncate_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_truncated_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_with_reference.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/conversation_item_with_reference_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/error_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_append_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_append_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_clear_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_clear_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_cleared_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_commit_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_commit_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_committed_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_speech_started_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/input_audio_buffer_speech_stopped_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/rate_limits_updated_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_client_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_client_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_connect_params.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_response.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_response_status.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_response_usage.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/realtime_server_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_audio_delta_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_audio_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_audio_transcript_delta_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_audio_transcript_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_cancel_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_cancel_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_content_part_added_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_content_part_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_create_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_create_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_created_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_function_call_arguments_delta_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_function_call_arguments_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_output_item_added_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_output_item_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_text_delta_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/response_text_done_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_create_params.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_create_response.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_created_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_update_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_update_event_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/session_updated_event.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/transcription_session.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/transcription_session_create_params.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/transcription_session_update.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/transcription_session_update_param.cpython-313.pyc,, +openai/types/beta/realtime/__pycache__/transcription_session_updated_event.cpython-313.pyc,, +openai/types/beta/realtime/conversation_created_event.py,sha256=U4-nesN8rAep2_25E2DrkXUMafQejj3NE_0llXKj5Y8,752 +openai/types/beta/realtime/conversation_item.py,sha256=eIFg9zl3qzEijcQZvCnkvVLpSZgvEdubasgxGsQuFM4,2327 +openai/types/beta/realtime/conversation_item_content.py,sha256=KWZY8EUkjAi6K_IkWVjjrNZLG3KK2vGCy2_O30CEhzY,1050 +openai/types/beta/realtime/conversation_item_content_param.py,sha256=CrGi3XKwnfJdQGs-kJaGCsn53omdJF6_je0GWnVXhjQ,972 +openai/types/beta/realtime/conversation_item_create_event.py,sha256=jYXYdmqJh_znzcAgDuCxJXo5shf-t_DwmsyFkaDVnAE,1081 +openai/types/beta/realtime/conversation_item_create_event_param.py,sha256=vxTag6TrOLu1bf46F3mUmRkl5dd1Kb6bUp65gBDVmhM,1101 +openai/types/beta/realtime/conversation_item_created_event.py,sha256=cZBm_uKk5dkQXLlbF0Aetg4NJge3Ftz9kwRu2kCI3m4,817 +openai/types/beta/realtime/conversation_item_delete_event.py,sha256=p-O6R1Ku5pxZvaxhSi4YTPqLXS1SHhdLGgJuPQyPcHY,549 +openai/types/beta/realtime/conversation_item_delete_event_param.py,sha256=a17h8Hd8MxUbXT6NQg8YpTr1ICt1ztRecpfukHw4g34,569 +openai/types/beta/realtime/conversation_item_deleted_event.py,sha256=uWHSqX5ig550romSdhtROwrdQmdeN31Oz1Vpr9IuQFI,492 +openai/types/beta/realtime/conversation_item_input_audio_transcription_completed_event.py,sha256=FwZHHO4ZGMKoeQ80snCh_S-7anNUQtRLOhGjb8ScGOQ,2538 +openai/types/beta/realtime/conversation_item_input_audio_transcription_delta_event.py,sha256=5kjLmnRJug7L5fHxSSWWbhB70jGwNaMwbdENEwz9Xek,1143 +openai/types/beta/realtime/conversation_item_input_audio_transcription_failed_event.py,sha256=xYNSBIyERQJ4P-5YoFF1VptfPa8JnJ0sWaH6LGsPow0,1077 +openai/types/beta/realtime/conversation_item_param.py,sha256=HMB7MFR6WkztV1vMCFdIYNv8qOY4jzI2MIDtr9y8nEo,2207 +openai/types/beta/realtime/conversation_item_retrieve_event.py,sha256=5Cc7f0fM8ujwER0eIcQRwz0rmc6hdCUrAqiAvRNn9Zc,559 +openai/types/beta/realtime/conversation_item_retrieve_event_param.py,sha256=TRYaZ3btNaywRPaMOVRzK5VT7wh4taIGjbUdhkZ7gFc,579 +openai/types/beta/realtime/conversation_item_truncate_event.py,sha256=1c2_BamaTkgD26eyGZJU5xwbz7lRHupqU2HqcK0VniI,943 +openai/types/beta/realtime/conversation_item_truncate_event_param.py,sha256=hSnVOSMMtLf16nn4ISHkevYCfEsiN9kNcgxXRtHa8Kc,983 +openai/types/beta/realtime/conversation_item_truncated_event.py,sha256=K4S35U85J-UNRba9nkm-7G1ReZu8gA8Sa1z0-Vlozc0,704 +openai/types/beta/realtime/conversation_item_with_reference.py,sha256=NDMfbnG0YKLqWJskFSHRIMkN2ISs8yNRxP6d6sZshws,3288 +openai/types/beta/realtime/conversation_item_with_reference_param.py,sha256=X0iEdjijFkoGtZtp0viB8bAFqMn4fNNSvJiCZbgJ-3Q,3079 +openai/types/beta/realtime/error_event.py,sha256=goNkorKXUHKiYVsVunEsnaRa6_3dsDKVtrxXQtzZCmk,877 +openai/types/beta/realtime/input_audio_buffer_append_event.py,sha256=lTKWd_WFbtDAy6AdaCjeQYBV0dgHuVNNt_PbrtPB8tg,662 +openai/types/beta/realtime/input_audio_buffer_append_event_param.py,sha256=XmN2bE6jBRrkKGVPJdnPjJql5dqMPqwbmFnxo-z22JE,682 +openai/types/beta/realtime/input_audio_buffer_clear_event.py,sha256=7AfCQfMxZQ-UoQXF9edYKw5GcTELPcfvvJWWpuLS41c,489 +openai/types/beta/realtime/input_audio_buffer_clear_event_param.py,sha256=y-zfWqJsh1n6r2i0MgLDpnNC4g1dq3GCS66Twfkng38,499 +openai/types/beta/realtime/input_audio_buffer_cleared_event.py,sha256=j9gpm7aGVmrUt48wqtvBMN8NOgtvqHciegjXjOnWm7A,429 +openai/types/beta/realtime/input_audio_buffer_commit_event.py,sha256=SLZR2xxRd6uO3IQL6-LuozkjROXiGyblKoHYQjwXk4I,493 +openai/types/beta/realtime/input_audio_buffer_commit_event_param.py,sha256=B8agXC-rUl-D-RijJ5MeTLgw43qVYzmf2_2oAVokhLY,503 +openai/types/beta/realtime/input_audio_buffer_committed_event.py,sha256=76XHl3ETfG5YiYce2OCUsv0wNfSiaabLzYVjGtBwux0,733 +openai/types/beta/realtime/input_audio_buffer_speech_started_event.py,sha256=NVp60RUsLFtte9Ilknmu_5lRk2dZp_1fXCgGHd4EvSM,861 +openai/types/beta/realtime/input_audio_buffer_speech_stopped_event.py,sha256=gszRuYQtAW8upIhd7CJZ7pxboDk-K7sqidjqxgf47q4,779 +openai/types/beta/realtime/rate_limits_updated_event.py,sha256=kBnf_p-49Q_LNdJsj0R1Szi8R4TGYAAJ_KifLuuyFZw,949 +openai/types/beta/realtime/realtime_client_event.py,sha256=0c48JcJH5yruF52zl0Sanm_dd2W5ZHV5GocRG0Xm6m4,1839 +openai/types/beta/realtime/realtime_client_event_param.py,sha256=xBeZ60Q-OWuZxstPQaoqE0DUTDOPOwrL8LWMmDJI2rM,1887 +openai/types/beta/realtime/realtime_connect_params.py,sha256=AvTypkFCYmDn9qMeektVqij6cqzgovr3PpgpMalJoJ4,290 +openai/types/beta/realtime/realtime_response.py,sha256=iUOItlPQv6-okCuiTsloe0LDVyJ0MUQ64ug8ZaLePnw,3567 +openai/types/beta/realtime/realtime_response_status.py,sha256=gU-59Pr_58TRfMZqFzdCloc53e1qOnU4aaHY3yURUK8,1326 +openai/types/beta/realtime/realtime_response_usage.py,sha256=6XOFjCjPWioHoICZ0Q8KXuUzktQugx6WuTz0O5UvzZg,1541 +openai/types/beta/realtime/realtime_server_event.py,sha256=-PpqZpg-DL_C_wseLMRQHWdBvxnVGRAfOF7x13Qr34E,5408 +openai/types/beta/realtime/response_audio_delta_event.py,sha256=UjbnK4u_WSNTOColZj8SmJgHnAc2H8iRXD76ZnPbz7E,742 +openai/types/beta/realtime/response_audio_done_event.py,sha256=1XEWBPh1JiOgyr6V03mRt_3sLm0YFUq5ft1AhfFlNEg,679 +openai/types/beta/realtime/response_audio_transcript_delta_event.py,sha256=HEVNQ_R2_Nyo6BvNvsliMnN__b17eVd2Jx5udRHg0Hg,773 +openai/types/beta/realtime/response_audio_transcript_done_event.py,sha256=Cn5l4mJnKK3LeSN9qFL4LLqs1WOWg4kt1SaYThB-5c0,787 +openai/types/beta/realtime/response_cancel_event.py,sha256=EKx8IZUISJHdl-_3tCdHtz2BINQ85Tq_ocadnsEGPSk,637 +openai/types/beta/realtime/response_cancel_event_param.py,sha256=nidzBL83liHwyImiNGiz9Ad0V34EtFAQDw1utqcF6ns,630 +openai/types/beta/realtime/response_content_part_added_event.py,sha256=a8-rm1NAwX685fk7GdT6Xi0Yr-JfeAkyUr94-RoFe34,1232 +openai/types/beta/realtime/response_content_part_done_event.py,sha256=jO2TZygxPabbnEG9E1AfNP-JYJv1QtCMnCzgcZ_3n18,1190 +openai/types/beta/realtime/response_create_event.py,sha256=46i-O9wwvhr1CzHNMDzhs2SGVwHiFJDOkQfOZZRfAWo,4763 +openai/types/beta/realtime/response_create_event_param.py,sha256=IPJlTWH0HzsknpSRrFgrQ3bfxsFZVRdQ6IYEsiGSZOk,4619 +openai/types/beta/realtime/response_created_event.py,sha256=zZtHx-1YjehXxX6aNE88SFINDaKOBzpzejo6sTNjq9g,506 +openai/types/beta/realtime/response_done_event.py,sha256=_yUPoECCli89iHLtV3NQkXQOW6Lc1JlxVPFw04ziBGY,494 +openai/types/beta/realtime/response_function_call_arguments_delta_event.py,sha256=Yh2mQZDucfnTLiO8LRyG9r7zeS1sjwLcMF1JPMdTFJc,793 +openai/types/beta/realtime/response_function_call_arguments_done_event.py,sha256=kxSPK6nbNWL6pxveY7zaNGgCkCXqyBFJPVYJrw9cbOw,793 +openai/types/beta/realtime/response_output_item_added_event.py,sha256=-_BZjvAqcgv3NIz-EMhvYMxIwvcXTt68FVNp0pw09dI,713 +openai/types/beta/realtime/response_output_item_done_event.py,sha256=0ClNVMZmeIxKghlEid9VGoWiZ97wp00hIdNnev4qBD8,709 +openai/types/beta/realtime/response_text_delta_event.py,sha256=B1yyuc6iMOMoG5Wh6W5KoQNYtVD1vEm2cKqHnl2CuFQ,721 +openai/types/beta/realtime/response_text_done_event.py,sha256=mPgVG6nWxwkZ3aZOX-JkVF7CpaWP5-bvtbxFrr4fK7g,724 +openai/types/beta/realtime/session.py,sha256=fAG4Z404H11aHq46KbcwZV9DoZ4QZV8UWZRtEOLS2b0,10116 +openai/types/beta/realtime/session_create_params.py,sha256=GJoh-uXky8uj0BX0_pw1LWFUmmIb7bpcg7HEsbH4hVc,10192 +openai/types/beta/realtime/session_create_response.py,sha256=HfCFE46q3IEfvLFEdU06DAg5GKIPlJjaU9DtKzKcr2U,6574 +openai/types/beta/realtime/session_created_event.py,sha256=rTElnBlE7z1htmkdmpdPN4q_dUYS6Su4BkmsqO65hUc,489 +openai/types/beta/realtime/session_update_event.py,sha256=7OSTuP3u2-QqsR4W_ApQoBVkBD3akYmbrzJi6m608rg,11170 +openai/types/beta/realtime/session_update_event_param.py,sha256=0n9BfkIDIIRP3BIz3jltuOxokbii06ZoHIS4gKBzBjk,10690 +openai/types/beta/realtime/session_updated_event.py,sha256=HyR-Pz3U9finVO-bUCvnmeqsANw-fceNvVqEIF6ey10,489 +openai/types/beta/realtime/transcription_session.py,sha256=Soo2LuEMJtkUD2oPJ1E23GUcoUrYBiSu_UtbLUKemfw,3184 +openai/types/beta/realtime/transcription_session_create_params.py,sha256=BVwSY41UX2njXAJpWynMJtC5XuKv6sNs7kp2Y8KSjnk,5976 +openai/types/beta/realtime/transcription_session_update.py,sha256=YMP9OB9P5FaSwaicXtYELjm4hD1gDSvKFq9YtF2sq64,6694 +openai/types/beta/realtime/transcription_session_update_param.py,sha256=b99v4yKnB2lC_cnYGiaxKnQuHB4eUW-v3eKT2UDsamk,6453 +openai/types/beta/realtime/transcription_session_updated_event.py,sha256=CKAS98QL7CuOVEWF6qGcC9qhTktdG2CPPJXbrW75GIM,833 +openai/types/beta/thread.py,sha256=RrArSK1-_prQY_YBexgD_SU87y_k2rmRq_tti66i7s4,2132 +openai/types/beta/thread_create_and_run_params.py,sha256=MPLDgaZ69PR-WZRPN_zwwF1--Cg9d99oD3rC2aWiCCk,14875 +openai/types/beta/thread_create_params.py,sha256=T0ok3yJ6ZXqPbX5dqwpQp7YFWCXoAhz_zbroMo6rPDQ,6561 +openai/types/beta/thread_deleted.py,sha256=MaYG_jZIjSiB9h_ZBiTtpMsRSwFKkCY83ziM5GO_oUk,292 +openai/types/beta/thread_update_params.py,sha256=eN1VyP4lk6puJseydX9Ac9CLZLobYQJcijEWk1RlHKc,1928 +openai/types/beta/threads/__init__.py,sha256=0WsJo0tXp08CgayozR7Tqc3b8sqzotWzvBun19CEIWc,3066 +openai/types/beta/threads/__pycache__/__init__.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/annotation.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/annotation_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/file_citation_annotation.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/file_citation_delta_annotation.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/file_path_annotation.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/file_path_delta_annotation.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file_content_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file_content_block_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file_delta_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_file_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url_content_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url_content_block_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url_delta_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/image_url_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_content.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_content_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_content_part_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_create_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_deleted.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_delta_event.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_list_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/message_update_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/refusal_content_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/refusal_delta_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/required_action_function_tool_call.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run_create_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run_list_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run_status.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run_submit_tool_outputs_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/run_update_params.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/text.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/text_content_block.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/text_content_block_param.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/text_delta.cpython-313.pyc,, +openai/types/beta/threads/__pycache__/text_delta_block.cpython-313.pyc,, +openai/types/beta/threads/annotation.py,sha256=Ce3Y0mSodmYRkoqyhtyIdep6WfWew6KJJgtrENOnfek,462 +openai/types/beta/threads/annotation_delta.py,sha256=iNsE-1Gn1yU0TlTHoxqKbOvPRUxWuXsF72qY_mMnWGY,510 +openai/types/beta/threads/file_citation_annotation.py,sha256=0Rs1Sr-eCLQpLsu8-WwHG7kv5Ihud4kiHO1NL7xHO0s,595 +openai/types/beta/threads/file_citation_delta_annotation.py,sha256=R87tcXkJ0RiH5UJo0Qknwk7X_c4qF1qvGsu2spOPx-I,873 +openai/types/beta/threads/file_path_annotation.py,sha256=hNc4ebprJynqMG1yk0gLvgzTpjtVzgEbXriMZftkgew,552 +openai/types/beta/threads/file_path_delta_annotation.py,sha256=RW9dgDF9Ggf357fPZ-vUu2ge3U-Hf11DVTr-ecklsBY,755 +openai/types/beta/threads/image_file.py,sha256=QVXLiplb-CigZqdMZtXlmebXKt6tF74kI-3vHxe_qUE,707 +openai/types/beta/threads/image_file_content_block.py,sha256=31I5trSERP2qLZpJ4ugZtIyta4DDoBhBvxkM4LovL3w,363 +openai/types/beta/threads/image_file_content_block_param.py,sha256=3ryZ6AV-DLwWYVP2XSK11UHkvutTUollxn6z8BZ4rSA,445 +openai/types/beta/threads/image_file_delta.py,sha256=nUJoSuP-3YyqqwBsmPJ0AqiQydz2FymVDCXQVkNYwOk,734 +openai/types/beta/threads/image_file_delta_block.py,sha256=XJ2YVX_cq0OiNcGbNmXO0_dca1IvPockOvvoM7pDvbI,492 +openai/types/beta/threads/image_file_param.py,sha256=BaKD31JPxQ5CjRfZ_0RcOG3lDTZeW_k85XCvwyctD54,717 +openai/types/beta/threads/image_url.py,sha256=EzEK-CYoO0YyqFmejIPu7pMfTEgMmp5NFscsRd2pCos,592 +openai/types/beta/threads/image_url_content_block.py,sha256=_sg3BWrtVGw-8XtAh15Rs4co6NCBB9Y3zCp_XOAz4U8,365 +openai/types/beta/threads/image_url_content_block_param.py,sha256=RWzo5KkBiwvgJSviZl6JUlsfv3VQKIFr6cp9lhkLu8E,447 +openai/types/beta/threads/image_url_delta.py,sha256=MXCp-OmuNT4njbWA9DWAbocP7pD3VpdcUy2wgeOjwm4,582 +openai/types/beta/threads/image_url_delta_block.py,sha256=Jjdfub4g9ceNKF8GuuTIghOmYba2vEeX3320mg5PWIA,484 +openai/types/beta/threads/image_url_param.py,sha256=VRLaxZf-wxnvAOcKGwyF_o6KEvwktBfE3B6KmYE5LZo,602 +openai/types/beta/threads/message.py,sha256=vk5lEpeA_aykADtn9GB8sLye7TByWZmV3ghauCh2s3c,3414 +openai/types/beta/threads/message_content.py,sha256=b8IC_EG28hcXk28z09EABfJwPkYZ7U-lTp_9ykdoxvU,630 +openai/types/beta/threads/message_content_delta.py,sha256=o4Edlx9BtdH2Z4OMwGWWXex8wiijknNRihJ-wu8PDUQ,615 +openai/types/beta/threads/message_content_part_param.py,sha256=RXrnoDP2-UMQHoR2jJvaT3JHrCeffLi6WzXzH05cDGI,550 +openai/types/beta/threads/message_create_params.py,sha256=7fXlNyqy7tzuLgMsCYfJegL2sZcjKwYNLihwteODyg0,2083 +openai/types/beta/threads/message_deleted.py,sha256=DNnrSfGZ3kWEazmo4mVTdLhiKlIHxs-D8Ef5sNdHY1o,303 +openai/types/beta/threads/message_delta.py,sha256=-kaRyvnIA8Yr2QV5jKRn15BU2Ni068a_WtWJ4PqlLfE,570 +openai/types/beta/threads/message_delta_event.py,sha256=7SpE4Dd3Lrc_cm97SzBwZzGGhfLqiFViDeTRQz-5YmQ,579 +openai/types/beta/threads/message_list_params.py,sha256=iuwzDccnViooUxHlq-WoE1FEJArNy5-zrYCoaNgVS8k,1296 +openai/types/beta/threads/message_update_params.py,sha256=XNCSLfRkk531F8mNbUB9bRYcCzJfW8NiFQ9c0Aq75Dk,757 +openai/types/beta/threads/refusal_content_block.py,sha256=qB9jrS2Wv9UQ7XXaIVKe62dTAU1WOnN3qenR_E43mhg,310 +openai/types/beta/threads/refusal_delta_block.py,sha256=ZhgFC8KqA9LIwo_CQIX-w3VVg3Vj0h71xC1Hh1bwmnU,423 +openai/types/beta/threads/required_action_function_tool_call.py,sha256=XsR4OBbxI-RWteLvhcLEDBan6eUUGvhLORFRKjPbsLg,888 +openai/types/beta/threads/run.py,sha256=cFOL77mXgELKefaRVN9Ds2jKoxYtBYwE6-82iegarcA,8338 +openai/types/beta/threads/run_create_params.py,sha256=qVaLiQDkZBBRAH5iaV8vRKycStlF1SCbEErQpp4SfOQ,10307 +openai/types/beta/threads/run_list_params.py,sha256=TgepSLrupUUtuQV2kbVcoGH1YA0FVUX9ESkszKuwyHY,1210 +openai/types/beta/threads/run_status.py,sha256=OU1hzoyYXaRJ3lupX4YcZ-HZkTpctNE4tzAcp6X8Q9U,351 +openai/types/beta/threads/run_submit_tool_outputs_params.py,sha256=cKiyD374BsZN_Oih5o5n5gOf_DYsxErVrbgxveNhmPI,1643 +openai/types/beta/threads/run_update_params.py,sha256=sVjkl6ayjU75Tk8t69r6xgIg80OlTikyRdS0sa2Gavg,749 +openai/types/beta/threads/runs/__init__.py,sha256=mg_roY9yL1bClJ8isizkQgHOAkN17iSdVr2m65iyBrs,1653 +openai/types/beta/threads/runs/__pycache__/__init__.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/code_interpreter_logs.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/code_interpreter_output_image.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/code_interpreter_tool_call.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/code_interpreter_tool_call_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/file_search_tool_call.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/file_search_tool_call_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/function_tool_call.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/function_tool_call_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/message_creation_step_details.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/run_step.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/run_step_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/run_step_delta_event.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/run_step_delta_message_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/run_step_include.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/step_list_params.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/step_retrieve_params.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/tool_call.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/tool_call_delta.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/tool_call_delta_object.cpython-313.pyc,, +openai/types/beta/threads/runs/__pycache__/tool_calls_step_details.cpython-313.pyc,, +openai/types/beta/threads/runs/code_interpreter_logs.py,sha256=7wXZpUE9I-oZJ0K3mFG0Nwmfm2bKGiSpWJyBeo7txwo,482 +openai/types/beta/threads/runs/code_interpreter_output_image.py,sha256=8o99k0ZHMHpqH0taXkOkYR9WaDUpCN-G0Ifd5XsJpb8,613 +openai/types/beta/threads/runs/code_interpreter_tool_call.py,sha256=ekiIuH1kVCN51hCzY3AYr5i3_a4vlgUiZHJ59pl17oY,1810 +openai/types/beta/threads/runs/code_interpreter_tool_call_delta.py,sha256=Qr2cen-bKyXTW2NDEUHnmJRE0jY-nkLcnO4NzCbBPDo,1479 +openai/types/beta/threads/runs/file_search_tool_call.py,sha256=R5mYh5W2qbVnz-fkAAqLlSqBQ2Gint1gSE_UBGum5-E,1962 +openai/types/beta/threads/runs/file_search_tool_call_delta.py,sha256=Gx8c7GSgGYuOvGadcAr3ZIspEFMZS3e2OY7vBo_MYnM,655 +openai/types/beta/threads/runs/function_tool_call.py,sha256=aOq5yOtKOi6C5Q1FIQRxqtJJR1AcSW_K5PvRiKISNCI,920 +openai/types/beta/threads/runs/function_tool_call_delta.py,sha256=VFRtCJkj4PHX97upM1cXpJAk9-JvJSgyngie06fBIjQ,1076 +openai/types/beta/threads/runs/message_creation_step_details.py,sha256=tRFMNF2Rf4DekVliUKkoujItiOjjAE9EG9bbxJvpVPA,506 +openai/types/beta/threads/runs/run_step.py,sha256=zTSlNBowJx507-oo6QJ7A30BFXdUt9k3lTZ4o34L1wI,3589 +openai/types/beta/threads/runs/run_step_delta.py,sha256=FNYDTddRrTO3PT_fgi7AsJ1PeMtyWsVzcxoihjbBzAw,663 +openai/types/beta/threads/runs/run_step_delta_event.py,sha256=rkDyvHSXt-hc1LngB41f9vglkn6t03kS62bsn0iGaxU,585 +openai/types/beta/threads/runs/run_step_delta_message_delta.py,sha256=UIo6oPH8STLjPHiWL-A4CtKfYe49uptvIAHWNnZ3Ums,564 +openai/types/beta/threads/runs/run_step_include.py,sha256=u-9Cw1hruRiWr70f_hw4XG0w1cwOAYfRJYKva2dEacs,264 +openai/types/beta/threads/runs/step_list_params.py,sha256=zorF5juogCzLMsZLjzMZTs_iIBcPj9WUur5HcrXuH8M,1752 +openai/types/beta/threads/runs/step_retrieve_params.py,sha256=aJ7l8RDJLPyEmqjfO4XsTV54VZOOqyb_gKSUvqp33ZI,815 +openai/types/beta/threads/runs/tool_call.py,sha256=1rwq4IbLgjQAQ-ORXYkNpmJyi9SREDnqA57nJbj_NiU,537 +openai/types/beta/threads/runs/tool_call_delta.py,sha256=t5wF8ndW3z99lHF981FL-IN5xXBS9p7eonH9bxvKu_c,600 +openai/types/beta/threads/runs/tool_call_delta_object.py,sha256=eK20VsIswEyT48XbkGu60HUrE7OD3fhpn1fbXrVauM4,615 +openai/types/beta/threads/runs/tool_calls_step_details.py,sha256=bDa-yybVF3a8H6VqhDGmFZMkpn-0gtPQM2jWWsmUvYo,574 +openai/types/beta/threads/text.py,sha256=9gjmDCqoptnxQ8Jhym87pECyd6m1lB3daCxKNzSFp4Y,319 +openai/types/beta/threads/text_content_block.py,sha256=pdGlKYM1IF9PjTvxjxo1oDg1XeGCFdJdl0kJVpZ7jIs,319 +openai/types/beta/threads/text_content_block_param.py,sha256=feQr0muF845tc1q3FJrzgYOhXeuKLU3x1x5DGFTN2Q0,407 +openai/types/beta/threads/text_delta.py,sha256=2EFeQCkg_cc8nYEJ6BtYAA3_TqgMTbmEXoMvLjzaB34,389 +openai/types/beta/threads/text_delta_block.py,sha256=pkHkVBgNsmHi9JURzs5ayPqxQXSkex3F0jH0MqJXik0,448 +openai/types/chat/__init__.py,sha256=wyA0EWb0utj19dX0tCeGh4Jg5GrO3TGjmfQkR9HVxxE,6102 +openai/types/chat/__pycache__/__init__.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_allowed_tool_choice_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_allowed_tools_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_assistant_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_audio.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_audio_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_chunk.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_image.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_image_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_input_audio_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_refusal_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_text.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_content_part_text_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_custom_tool_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_deleted.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_developer_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_function_call_option_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_function_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_function_tool.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_function_tool_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_custom_tool_call.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_custom_tool_call_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_function_tool_call.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_function_tool_call_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_tool_call.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_tool_call_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_message_tool_call_union_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_modality.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_named_tool_choice_custom_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_named_tool_choice_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_prediction_content_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_reasoning_effort.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_role.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_store_message.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_stream_options_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_system_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_token_logprob.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_tool_choice_option_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_tool_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_tool_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_tool_union_param.cpython-313.pyc,, +openai/types/chat/__pycache__/chat_completion_user_message_param.cpython-313.pyc,, +openai/types/chat/__pycache__/completion_create_params.cpython-313.pyc,, +openai/types/chat/__pycache__/completion_list_params.cpython-313.pyc,, +openai/types/chat/__pycache__/completion_update_params.cpython-313.pyc,, +openai/types/chat/__pycache__/parsed_chat_completion.cpython-313.pyc,, +openai/types/chat/__pycache__/parsed_function_tool_call.cpython-313.pyc,, +openai/types/chat/chat_completion.py,sha256=cQQEYFoF1Cs3Xy_nskiwo0nrDGmdu5t4TtiQ03xA8T4,3488 +openai/types/chat/chat_completion_allowed_tool_choice_param.py,sha256=kQgAzwedjhFLqSzkhI59rJ2ZtfyMIhBQf09I9oJvpII,636 +openai/types/chat/chat_completion_allowed_tools_param.py,sha256=q7PeluUYm0xA9EbwwHdbbk72obyFyuChFDfG4zwIBto,1010 +openai/types/chat/chat_completion_assistant_message_param.py,sha256=2hLVB-u2C20B2QBREBEymXJfFSwiGnnzv3jbKyHdSrY,2441 +openai/types/chat/chat_completion_audio.py,sha256=ioAcuhkIdk1TSZK1LqTXYcjTPxoaM2b0RhGJekyCABY,655 +openai/types/chat/chat_completion_audio_param.py,sha256=FLcawzQQpYPC4_yC7h3hOvFa1NyvLECKGSAoKB1d-Mk,811 +openai/types/chat/chat_completion_chunk.py,sha256=zySvwbuKEVrPLuKVZgPUsIqq1D4nRjSp1U6nCkVFxGI,6006 +openai/types/chat/chat_completion_content_part_image.py,sha256=G51SQ-Pjc2FO8vtq_DizAlPe7WhloVZMK7L84Y2kECI,753 +openai/types/chat/chat_completion_content_part_image_param.py,sha256=Gqv98qyD8jB81THZp49c8v2tHrId_iQp4NzciT9SKI0,797 +openai/types/chat/chat_completion_content_part_input_audio_param.py,sha256=r1EXNEtjJo5oJ9AnP3omaJzACE1gSfdmob5Q0HKsOm4,704 +openai/types/chat/chat_completion_content_part_param.py,sha256=0S9iFE1p93HG_Yx7Wj_TR2CmBNK_i7TaWE7HuE-tLc4,1259 +openai/types/chat/chat_completion_content_part_refusal_param.py,sha256=TV1vu-IgrvKa5IBlPSIdBxUaW8g1zDhMOOBOEmhU2w0,467 +openai/types/chat/chat_completion_content_part_text.py,sha256=A9WfAYjt-8fbCzEn8kC9pTpK9e2G0aua58FqssXXfrY,363 +openai/types/chat/chat_completion_content_part_text_param.py,sha256=4IpiXMKM9AuTyop5PRptPBbBhh9s93xy2vjg4Yw6NIw,429 +openai/types/chat/chat_completion_custom_tool_param.py,sha256=n-ThsvnkdKvRePzRdHEjikeXtju4K9Uc-ueB4LnByyM,1638 +openai/types/chat/chat_completion_deleted.py,sha256=O7oRuPI6YDa_h7uKnEubsjtw8raTcyVmVk95hoDfo74,470 +openai/types/chat/chat_completion_developer_message_param.py,sha256=OCFKdTWkff94VtgY7AaDUUFiZLT8LBn7WWxjbcIq2OM,830 +openai/types/chat/chat_completion_function_call_option_param.py,sha256=M-IqWHyBLkvYBcwFxxp4ydCIxbPDaMlNl4bik9UoFd4,365 +openai/types/chat/chat_completion_function_message_param.py,sha256=jIaZbBHHbt4v4xHCIyvYtYLst_X4jOznRjYNcTf0MF0,591 +openai/types/chat/chat_completion_function_tool.py,sha256=Yw3wlkMQPjs-j2JQaBEcbxtXv9b0w2FJryRPegWknjc,445 +openai/types/chat/chat_completion_function_tool_param.py,sha256=isNPdszq2CXOZB6a-ALjTBRaX8T-BeToe2tApMepmto,519 +openai/types/chat/chat_completion_message.py,sha256=iC4SMjhTCVVO1Xueb_iAObMB_nLRc_PFxasfZK0A1kM,2521 +openai/types/chat/chat_completion_message_custom_tool_call.py,sha256=fbnL3fERlW4E9hd5EoCcb43zgCoaPc11tZ0AlBjoegM,643 +openai/types/chat/chat_completion_message_custom_tool_call_param.py,sha256=OvZxmUFfz7SDl55gvfscHaKPHUe8DmV83JzkQhJQplo,752 +openai/types/chat/chat_completion_message_function_tool_call.py,sha256=9KJxJ6T40mFBtznBnPE3wfHlzhQtNG_ayrn3ZYuIlyA,916 +openai/types/chat/chat_completion_message_function_tool_call_param.py,sha256=V09BFjYcP2pYigtrBfFtg6PfEPKbD0E6MAUxrDWyn_g,1025 +openai/types/chat/chat_completion_message_param.py,sha256=aLrz_cX_CYymFdW9cMIPZpv0Z4zM50RECV3SH6QNZsc,1019 +openai/types/chat/chat_completion_message_tool_call.py,sha256=aWpKcV6NZZfx_-aGEwPz99IDWNCdRuwoYpUChs0Uvvc,738 +openai/types/chat/chat_completion_message_tool_call_param.py,sha256=rE_TbdN3N6JGzHecykgdFHZgI66p2lsl0loPpz5TxW0,458 +openai/types/chat/chat_completion_message_tool_call_union_param.py,sha256=L8IoSHXgIFxYyHSfXQJNN7FJlp31ez8X4l5eSPKGmYM,602 +openai/types/chat/chat_completion_modality.py,sha256=8Ga0kruwJc43WD2OIqNudn7KrVRTPDQaalVkh_8bp9I,236 +openai/types/chat/chat_completion_named_tool_choice_custom_param.py,sha256=K7LbF_AYWRohfzsVj8iCYNYePdAmqsqWmWoQBw_nsXk,565 +openai/types/chat/chat_completion_named_tool_choice_param.py,sha256=bS9rzU0SzIZCQCfOlEoRaRtFr10oIUV9HRQ_-iv6W0M,559 +openai/types/chat/chat_completion_prediction_content_param.py,sha256=Xw4K_4F379LsXENOpZvREDn55cCnbmZ69xa4fw9w3bg,868 +openai/types/chat/chat_completion_reasoning_effort.py,sha256=9sAGlM21dgRNOQRSsL_znZf9ruXcmvVriWeex0fRgMk,235 +openai/types/chat/chat_completion_role.py,sha256=LW6-tqXaqpD7H53PiSXrjvIo6g4RfHhWityDm6Nfvig,275 +openai/types/chat/chat_completion_store_message.py,sha256=krUE7xzu6DWc64_yAOABOGfM8-aFeE59HDF1QLoOgek,916 +openai/types/chat/chat_completion_stream_options_param.py,sha256=5didkVskgUUcVH6BjfCnA6hG4lp9LOiBU7cDnx3abh0,1311 +openai/types/chat/chat_completion_system_message_param.py,sha256=WYtzmsNP8ZI3Ie8cd-oU7RuNoaBF6-bBR3mOzST9hMw,815 +openai/types/chat/chat_completion_token_logprob.py,sha256=6-ipUFfsXMf5L7FDFi127NaVkDtmEooVgGBF6Ts965A,1769 +openai/types/chat/chat_completion_tool_choice_option_param.py,sha256=wPIjU-eeybPjRFr28mx8Njp2OCrKw3Xpu0231z4Kz1A,758 +openai/types/chat/chat_completion_tool_message_param.py,sha256=5K7jfKpwTuKNi1PTFabq_LHH-7wun8CUsLDh90U8zQE,730 +openai/types/chat/chat_completion_tool_param.py,sha256=5hFt0Izat_o50JMJzspCYeB0gubilRDB3a6yIfGHoN8,431 +openai/types/chat/chat_completion_tool_union_param.py,sha256=smpIoekwuuXKQx9jRRB2cqc3L7_fmN5lB4IIJHlKhys,504 +openai/types/chat/chat_completion_user_message_param.py,sha256=mik-MRkwb543C5FSJ52LtTkeA2E_HdLUgtoHEdO73XQ,792 +openai/types/chat/completion_create_params.py,sha256=KM9_hrGMpifTmzvO9S2GU71Xlhl7zSDxm5yl8P9VFtM,17246 +openai/types/chat/completion_list_params.py,sha256=jOAiZ6vYSrxyD-3qzIXvXofJkejl6bet9_yNsC9p5ws,1154 +openai/types/chat/completion_update_params.py,sha256=VRDF28qoonjrveHhw8BT4Yo_NlLsV2Qzd_KUUQ6AEG8,742 +openai/types/chat/completions/__init__.py,sha256=nmKlohYbZmr7Pzv1qCDMSDbthcH6ySPFIgvXpHZtxK8,195 +openai/types/chat/completions/__pycache__/__init__.cpython-313.pyc,, +openai/types/chat/completions/__pycache__/message_list_params.cpython-313.pyc,, +openai/types/chat/completions/message_list_params.py,sha256=IArlye40xGlMVIDHxsK9RX_5usPL71wXPMgdwI7_wYU,583 +openai/types/chat/parsed_chat_completion.py,sha256=KwcwCtj0yexl6gB7yuOnyETRW-uUvNRYbVzPMkwCe5Q,1437 +openai/types/chat/parsed_function_tool_call.py,sha256=JDWYo1XhTDQ8CxssbgjpzBhUw8jeXAmEd5Tr_CqFrVA,945 +openai/types/chat_model.py,sha256=yFvzwm6VJXCn6jN21FS-utN6bcBBzRIpKYk1VTP8sdo,177 +openai/types/completion.py,sha256=yuYVEVkJcMVUINNLglkxOJqCx097HKCYFeJun3Js73A,1172 +openai/types/completion_choice.py,sha256=PUk77T3Cp34UJSXoMfSzTKGWDK0rQQwq84X_PSlOUJo,965 +openai/types/completion_create_params.py,sha256=UqgYjUpYbQYPdYETVxhkwgbGRKTQCBoyeSFtrB8iuAo,7652 +openai/types/completion_usage.py,sha256=uf5n0vzlCkGAU67BBn_h7yhjd_G4OHpQbJnvzz0eO2A,1735 +openai/types/container_create_params.py,sha256=119x8wG_Cz_IC-N1ha02h9IlHBjh8DPHOkr2o6FiMa8,814 +openai/types/container_create_response.py,sha256=5tItbVA4xiJRcJMvqPbSoIIO49n-Hmtq_MnLBz_ww-w,1129 +openai/types/container_list_params.py,sha256=7RiUMBOEJj9QH9LYtPiwUrIufx8czF6kk2JcfO_LP_s,893 +openai/types/container_list_response.py,sha256=LVxHagc20cMD9brVMMJaQ-LTO-9uACqF8nUupsO1bsY,1125 +openai/types/container_retrieve_response.py,sha256=mqPMgQXPBDm72O2eLj8CdZgcdX0uVH28cCUL6g6sqtg,1133 +openai/types/containers/__init__.py,sha256=SCdMa4GNxw-I23CwW03iVOoHRfDybyKEMmpDkdVuUcI,480 +openai/types/containers/__pycache__/__init__.cpython-313.pyc,, +openai/types/containers/__pycache__/file_create_params.cpython-313.pyc,, +openai/types/containers/__pycache__/file_create_response.cpython-313.pyc,, +openai/types/containers/__pycache__/file_list_params.cpython-313.pyc,, +openai/types/containers/__pycache__/file_list_response.cpython-313.pyc,, +openai/types/containers/__pycache__/file_retrieve_response.cpython-313.pyc,, +openai/types/containers/file_create_params.py,sha256=KXoZNG4DpiD7NDeQixdKJsuOv-iCZAlSN4sz7AQm49k,412 +openai/types/containers/file_create_response.py,sha256=Dh1OWf86XNMfmvVwfRGezfihdDuuAcdiQxT_3iefBzw,722 +openai/types/containers/file_list_params.py,sha256=9bU7uKeXPk7adFzwvKHFitFOV4phnIbbfFx5u6n1OFY,883 +openai/types/containers/file_list_response.py,sha256=xwvdMIUafkHSXJGQT1_mxt6T_8nJo-isp9M_5YTq-J8,718 +openai/types/containers/file_retrieve_response.py,sha256=wGPU9o5SKkg8s4aUJXhwC38u8KfTFKmIUk1ItUdYxJg,726 +openai/types/containers/files/__init__.py,sha256=OKfJYcKb4NObdiRObqJV_dOyDQ8feXekDUge2o_4pXQ,122 +openai/types/containers/files/__pycache__/__init__.cpython-313.pyc,, +openai/types/conversations/__init__.py,sha256=N7GRumNq1KeGR4X9STSKWLM1axUntyaMI_OwPihZmjI,1854 +openai/types/conversations/__pycache__/__init__.cpython-313.pyc,, +openai/types/conversations/__pycache__/computer_screenshot_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation_create_params.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation_deleted_resource.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation_item.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation_item_list.cpython-313.pyc,, +openai/types/conversations/__pycache__/conversation_update_params.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_file_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_file_content_param.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_image_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_image_content_param.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_text_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/input_text_content_param.cpython-313.pyc,, +openai/types/conversations/__pycache__/item_create_params.cpython-313.pyc,, +openai/types/conversations/__pycache__/item_list_params.cpython-313.pyc,, +openai/types/conversations/__pycache__/item_retrieve_params.cpython-313.pyc,, +openai/types/conversations/__pycache__/message.cpython-313.pyc,, +openai/types/conversations/__pycache__/output_text_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/output_text_content_param.cpython-313.pyc,, +openai/types/conversations/__pycache__/refusal_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/refusal_content_param.cpython-313.pyc,, +openai/types/conversations/__pycache__/summary_text_content.cpython-313.pyc,, +openai/types/conversations/__pycache__/text_content.cpython-313.pyc,, +openai/types/conversations/computer_screenshot_content.py,sha256=yJ-i6Z9VxHt21iuz2K9i0saVWOsMzpLjqjjDoob1AAk,632 +openai/types/conversations/conversation.py,sha256=BVpec4hLHle_8iRf6v5y4CPYHtMhEntP0m8PDG_5GSY,886 +openai/types/conversations/conversation_create_params.py,sha256=dtgIXlZj1yKP3oJUYdFCb2MKIk6BH8e4QbKIPPGjHf8,976 +openai/types/conversations/conversation_deleted_resource.py,sha256=HagMTsOrDL7QYQSeZqMbBMfRzhWAgnrxtinGT5uhog4,326 +openai/types/conversations/conversation_item.py,sha256=gvJBsNG0n00pKeQ3UTV_6v-FX8gloDQvusdHaYinL8g,6189 +openai/types/conversations/conversation_item_list.py,sha256=FvZW9mcZsKpaWNAI1PRuBtnKWt8vB1PEbDLmKN7ZF5o,667 +openai/types/conversations/conversation_update_params.py,sha256=YMyThjw2ObnqY-dhI4iy2pqf0cZW7rNV0TcxpBMs1bs,746 +openai/types/conversations/input_file_content.py,sha256=xxG8_PMhnjH1F6jXs6vZyj_T1HdO--48fTYFrvWCPzk,219 +openai/types/conversations/input_file_content_param.py,sha256=ATFOU1VRdw8SDRvwdC1KEamfAMna-mIfpER5bLpGIeg,244 +openai/types/conversations/input_image_content.py,sha256=LKKWx1y5Gi0nu34a8CFbDUaXUWQACeQ80lwJtukOx3U,224 +openai/types/conversations/input_image_content_param.py,sha256=AceRCBW-WuXG5rI4uDF2w0n_eaa8DzpCmbdWm3ofVMg,248 +openai/types/conversations/input_text_content.py,sha256=G5L4ln3tkWqSzaZlAkFuzkFOpjYqPVnE3QyXafiA6YU,219 +openai/types/conversations/input_text_content_param.py,sha256=HPl92LQHoA3_2azNJcVF1FD6OTJY200uwbCodF7_xPg,244 +openai/types/conversations/item_create_params.py,sha256=TRAsvDuMBjLeL5DzqC-WyqmorZTnu4qZRt9eE13SJ8E,874 +openai/types/conversations/item_list_params.py,sha256=nMzeK_XkVTWsa5pMQDGDuRPfGwiXFBDcdZ4NYwYV7H4,1896 +openai/types/conversations/item_retrieve_params.py,sha256=lHK-Sqbd7DXWQKuXGRBUvu_a7LxYNAT_tBQqLP-OC5A,690 +openai/types/conversations/message.py,sha256=6rgMphWrnp4S3WmKEEVsnk2dhgMXtZhrYrgcMci4NtI,2033 +openai/types/conversations/output_text_content.py,sha256=bFDVfODBGMwRLcKeo0OZzZumZdZwHzHkG1B_Bw43vWA,224 +openai/types/conversations/output_text_content_param.py,sha256=8NlazI-VuJ9DgQ-ZGt9xJ8su2-CZ1mb_ebI9O19YC7Q,248 +openai/types/conversations/refusal_content.py,sha256=ThoHeemlqaKlUf7oVYOTUwnHuqph-4RXS4Ud_kGbGg0,227 +openai/types/conversations/refusal_content_param.py,sha256=hWb2AoU0oTKCNLRZs5kzxY2Uk7HkeHhEy5leL29Uy64,254 +openai/types/conversations/summary_text_content.py,sha256=M7-_fLUFx_L7hOcn4i4e8jyNNWKwHmU8bSMWGhyuAj4,405 +openai/types/conversations/text_content.py,sha256=SV7snTCpe8X3CJy1T1uOMiFn0IyZjWzj7GCtPJRezv8,259 +openai/types/create_embedding_response.py,sha256=lTAu_Pym76kFljDnnDRoDB2GNQSzWmwwlqf5ff7FNPM,798 +openai/types/embedding.py,sha256=2pV6RTSf5UV6E86Xeud5ZwmjQjMS93m_4LrQ0GN3fho,637 +openai/types/embedding_create_params.py,sha256=asahWWNcMvXGDfbTMz4uDy7DU9g6OJ9wowqZByghzw8,2039 +openai/types/embedding_model.py,sha256=0dDL87len4vZ4DR6eCp7JZJCJpgwWphRmJhMK3Se8f4,281 +openai/types/eval_create_params.py,sha256=EMEE1XtHP_AGF_R3ptJe55-uNbfvThBmKzN-sEq49mo,6703 +openai/types/eval_create_response.py,sha256=h8o7zz_pat94dmryy2QDMOK3Lz-szPkmD52faYtBK0c,3531 +openai/types/eval_custom_data_source_config.py,sha256=-39Cjr1v2C1Fer4PLl7rfA-bDK08I-bM4cqlp9Z_mzE,589 +openai/types/eval_delete_response.py,sha256=iCMGN0JG5kFIYNPSCOMSWlTu0FDkd2lbAw1VLO73-bQ,245 +openai/types/eval_list_params.py,sha256=WmIJa3O9wyuDKXXwE3tSnQv1XOTe1hngttSvvhbtf28,754 +openai/types/eval_list_response.py,sha256=mTm1vQbqAfG9u2rfUH8UkJC1vPi_1Z1snKPlYA1EKE4,3527 +openai/types/eval_retrieve_response.py,sha256=pn5FaZ5_dzhX3iiCTlu0iHa9w-bc7Gk1ZHvFllQWVA4,3535 +openai/types/eval_stored_completions_data_source_config.py,sha256=7CYy14MMLj6HBJULXploJPQLs-4wpzlXUazw7oJZAjo,1081 +openai/types/eval_update_params.py,sha256=Wooz-3SDznbC3ihrhOs-10y9cxpTKGQgobDLfZ-23c0,757 +openai/types/eval_update_response.py,sha256=D9ItfznRN1jwp_w48r-i4jvH1_h2uiSpleHePrVigJs,3531 +openai/types/evals/__init__.py,sha256=wiXRqdkT-SkjE0Sgv6MixeECZjF0xaoCPdSGFEh0rEs,1193 +openai/types/evals/__pycache__/__init__.cpython-313.pyc,, +openai/types/evals/__pycache__/create_eval_completions_run_data_source.cpython-313.pyc,, +openai/types/evals/__pycache__/create_eval_completions_run_data_source_param.cpython-313.pyc,, +openai/types/evals/__pycache__/create_eval_jsonl_run_data_source.cpython-313.pyc,, +openai/types/evals/__pycache__/create_eval_jsonl_run_data_source_param.cpython-313.pyc,, +openai/types/evals/__pycache__/eval_api_error.cpython-313.pyc,, +openai/types/evals/__pycache__/run_cancel_response.cpython-313.pyc,, +openai/types/evals/__pycache__/run_create_params.cpython-313.pyc,, +openai/types/evals/__pycache__/run_create_response.cpython-313.pyc,, +openai/types/evals/__pycache__/run_delete_response.cpython-313.pyc,, +openai/types/evals/__pycache__/run_list_params.cpython-313.pyc,, +openai/types/evals/__pycache__/run_list_response.cpython-313.pyc,, +openai/types/evals/__pycache__/run_retrieve_response.cpython-313.pyc,, +openai/types/evals/create_eval_completions_run_data_source.py,sha256=vz4ZTUyHKjsEv6U1yeKlwzAgobnmj0UfZuXyU4OdiKE,7817 +openai/types/evals/create_eval_completions_run_data_source_param.py,sha256=VGvohk9Vhe1BNktpLcZpnxQf9yvKCMO1sn3xPkjbzgw,7888 +openai/types/evals/create_eval_jsonl_run_data_source.py,sha256=GzE9S1AZy46LOooR61Nwmp5yGUMoFGU5yk4g18BP72E,1219 +openai/types/evals/create_eval_jsonl_run_data_source_param.py,sha256=sM4-h4qDDkttGeaKgip8JZeuiaghPTBmwwxb5Xa6zhk,1285 +openai/types/evals/eval_api_error.py,sha256=VvRO-N9_tIxpRiSi17PXiMpleowg_Y-Rq2kqiRgmpC4,268 +openai/types/evals/run_cancel_response.py,sha256=pxSmKYzP2tqPUv6hehCZMAz-1F2cucd3HpKsD0VScFI,13669 +openai/types/evals/run_create_params.py,sha256=f7B6HIxX2E0KwEtsw2Y4OEStSgiuKXKpuVP6MipbcxQ,12721 +openai/types/evals/run_create_response.py,sha256=pDERgsUWNG3n1o9M94e3xDKiqT3nhjWhm2JyOgWWins,13669 +openai/types/evals/run_delete_response.py,sha256=WSQpOlZu53eWBCXSRGkthFn_Yz5rDCcSomqoa4HpUrk,323 +openai/types/evals/run_list_params.py,sha256=vgbJMYybzCep7e9rxUVHlWy_o4GNy4tJyGTwNu4n4ys,758 +openai/types/evals/run_list_response.py,sha256=kZwwxzDdXvFENsJRyUXuUF69j7tN8XeWbOSh5sas0SQ,13665 +openai/types/evals/run_retrieve_response.py,sha256=f8nc2ujEZK_In7nnBzlVOaSNSCLhnJdQh0SvRGO8OUU,13673 +openai/types/evals/runs/__init__.py,sha256=sltNV1VwseIVr09gQ5E4IKbRKJuWJSLY1xUvAuC97Ec,393 +openai/types/evals/runs/__pycache__/__init__.cpython-313.pyc,, +openai/types/evals/runs/__pycache__/output_item_list_params.cpython-313.pyc,, +openai/types/evals/runs/__pycache__/output_item_list_response.cpython-313.pyc,, +openai/types/evals/runs/__pycache__/output_item_retrieve_response.cpython-313.pyc,, +openai/types/evals/runs/output_item_list_params.py,sha256=Lp1OQV1qXeEUwMS90_-BpOnO1jICwJOo9QgNC9OGJ2U,821 +openai/types/evals/runs/output_item_list_response.py,sha256=p-fc6-5-5VCvsaNuMefoOtf6htw8eqwKWj7qSjUEOfI,3836 +openai/types/evals/runs/output_item_retrieve_response.py,sha256=Yb-w50QBxucfI3D07pjqNIZ4rmUclbcLfmZGTFiTSBE,3844 +openai/types/file_chunking_strategy.py,sha256=oT5tAbwt3wJsFqSj2sjDPBcisegNwJOecxS_V7M4EdA,559 +openai/types/file_chunking_strategy_param.py,sha256=mOFh18BKAGkzVTrWv_3Iphzbs-EbT6hq-jChCA4HgAE,517 +openai/types/file_content.py,sha256=qLlM4J8kgu1BfrtlmYftPsQVCJu4VqYeiS1T28u8EQ8,184 +openai/types/file_create_params.py,sha256=Ame7qem1zNkBzHFLv5AOB1DnrIgAsIGdzOr6dr3NWZc,1394 +openai/types/file_deleted.py,sha256=H_r9U7XthT5xHAo_4ay1EGGkc21eURt8MkkIBRYiQcw,277 +openai/types/file_list_params.py,sha256=TmmqvM7droAJ49YlgpeFzrhPv5uVkSZDxqlG6hhumPo,960 +openai/types/file_object.py,sha256=Qu0rci3ec0iPh36ThAK4tiCN_BRmULnOFU8jzzFYhB4,1504 +openai/types/file_purpose.py,sha256=aNd8G-GC1UVCL9bvTgtL4kfkiF0uEjfiimRS-eh8VrY,265 +openai/types/fine_tuning/__init__.py,sha256=f8GH2rKGcIU1Kjrfjw5J0QoqlsC4jRmH96bU6axGD64,1832 +openai/types/fine_tuning/__pycache__/__init__.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/dpo_hyperparameters.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/dpo_hyperparameters_param.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/dpo_method.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/dpo_method_param.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/fine_tuning_job.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/fine_tuning_job_event.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/fine_tuning_job_integration.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/fine_tuning_job_wandb_integration.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/fine_tuning_job_wandb_integration_object.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/job_create_params.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/job_list_events_params.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/job_list_params.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/reinforcement_hyperparameters.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/reinforcement_hyperparameters_param.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/reinforcement_method.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/reinforcement_method_param.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/supervised_hyperparameters.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/supervised_hyperparameters_param.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/supervised_method.cpython-313.pyc,, +openai/types/fine_tuning/__pycache__/supervised_method_param.cpython-313.pyc,, +openai/types/fine_tuning/alpha/__init__.py,sha256=e_Evj3xLs7o_SONlqoXDM75oZMbxuGWhxBW-azsXD_w,429 +openai/types/fine_tuning/alpha/__pycache__/__init__.cpython-313.pyc,, +openai/types/fine_tuning/alpha/__pycache__/grader_run_params.cpython-313.pyc,, +openai/types/fine_tuning/alpha/__pycache__/grader_run_response.cpython-313.pyc,, +openai/types/fine_tuning/alpha/__pycache__/grader_validate_params.cpython-313.pyc,, +openai/types/fine_tuning/alpha/__pycache__/grader_validate_response.cpython-313.pyc,, +openai/types/fine_tuning/alpha/grader_run_params.py,sha256=ECVczgghTZ8J9xfqAbNc_VvAHfhOpkaVzQw_wUmE4r8,1414 +openai/types/fine_tuning/alpha/grader_run_response.py,sha256=So-fvQMRvpccsSYb0jfKGQ_MNWdqqS71OcE9GbeLASs,1556 +openai/types/fine_tuning/alpha/grader_validate_params.py,sha256=Jd6m3DjIZAUNY-PlLUWDbH3ojm8ztnfjHmPjKw2DrLM,875 +openai/types/fine_tuning/alpha/grader_validate_response.py,sha256=nLldMLyNG-ICS3HwykDWdKuAPKu4gR2A2I0C79C4khs,773 +openai/types/fine_tuning/checkpoints/__init__.py,sha256=xA69SYwf79pe8QIq9u9vXPjjCw7lf3ZW2arzg9c_bus,588 +openai/types/fine_tuning/checkpoints/__pycache__/__init__.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/__pycache__/permission_create_params.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/__pycache__/permission_create_response.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/__pycache__/permission_delete_response.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/__pycache__/permission_retrieve_params.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/__pycache__/permission_retrieve_response.cpython-313.pyc,, +openai/types/fine_tuning/checkpoints/permission_create_params.py,sha256=TI90xY-4dv8vDKKZ0FBdbly9JTCrw4FgXkcXz_gTUlk,407 +openai/types/fine_tuning/checkpoints/permission_create_response.py,sha256=F-A0bNQ5iTNUDmtCbQwv1PUDrJWSsdymcbCqfiZ3TwE,636 +openai/types/fine_tuning/checkpoints/permission_delete_response.py,sha256=X_RuOvxa6i3wGLP5joHixv4tNLUpuK-2umiUf6P7Ha8,558 +openai/types/fine_tuning/checkpoints/permission_retrieve_params.py,sha256=3zVCOq1676MizKhKSba2OLmBSPlBx6Az2ZdxyVl580o,610 +openai/types/fine_tuning/checkpoints/permission_retrieve_response.py,sha256=Z2Iz3u9-BJ2dENhBz54d9qVarl0H67B8H268Ybz6lQE,848 +openai/types/fine_tuning/dpo_hyperparameters.py,sha256=RTcK6yOw8CgwKL6CHtxcvY1ucD37d0TXArBb5h_fShQ,1064 +openai/types/fine_tuning/dpo_hyperparameters_param.py,sha256=T3AX6qWEhl-vukTDj6h0cknhlHkiKY1bTsjzAORnWM0,1048 +openai/types/fine_tuning/dpo_method.py,sha256=i6jDyRNOxYb8c_YnsZa5qThpDPUBkO-rTFbpQT2hA5Q,377 +openai/types/fine_tuning/dpo_method_param.py,sha256=v3CD8Ywn-SuIFJyHJsRN3nF379d3MK8jwz1WUU_Q3O0,414 +openai/types/fine_tuning/fine_tuning_job.py,sha256=p1HKONRbL4cnXJaG6zQv_v8L6InFTz5cdmGH9yH1uTk,5238 +openai/types/fine_tuning/fine_tuning_job_event.py,sha256=POxSD7-WxAtJV2KuEpA9EmZi7W_u0PikOUtUzxIXii4,854 +openai/types/fine_tuning/fine_tuning_job_integration.py,sha256=uNFfuBV87nUHQORNGVLP_HbotooR_e37Bgd0dyZ4nUM,241 +openai/types/fine_tuning/fine_tuning_job_wandb_integration.py,sha256=YnBeiz14UuhUSpnD0KBj5V143qLvJbDIMcUVWOCBLXY,1026 +openai/types/fine_tuning/fine_tuning_job_wandb_integration_object.py,sha256=7vEc2uEV2c_DENBjhq0Qy5X8B-rzxsKvGECjnvF1Wdw,804 +openai/types/fine_tuning/job_create_params.py,sha256=p42ebOzvo_ghEitjITP4Qg-mhUvQchreeDrd_FR5YKA,6178 +openai/types/fine_tuning/job_list_events_params.py,sha256=4xOED4H2ky2mI9sIDytjmfJz5bNAdNWb70WIb_0bBWs,400 +openai/types/fine_tuning/job_list_params.py,sha256=wUGXsQ4UDCKvAjHDZAZ-JDU6XAouiTGThb0Jo_9XX08,623 +openai/types/fine_tuning/jobs/__init__.py,sha256=nuWhOUsmsoVKTKMU35kknmr8sfpTF-kkIzyuOlRbJj0,295 +openai/types/fine_tuning/jobs/__pycache__/__init__.cpython-313.pyc,, +openai/types/fine_tuning/jobs/__pycache__/checkpoint_list_params.cpython-313.pyc,, +openai/types/fine_tuning/jobs/__pycache__/fine_tuning_job_checkpoint.cpython-313.pyc,, +openai/types/fine_tuning/jobs/checkpoint_list_params.py,sha256=XoDLkkKCWmf5an5rnoVEpNK8mtQHq1fHw9EqmezfrXM,415 +openai/types/fine_tuning/jobs/fine_tuning_job_checkpoint.py,sha256=Z_sUhebJY9nWSssZU7QoOJwe5sez76sCAuVeSO63XhY,1347 +openai/types/fine_tuning/reinforcement_hyperparameters.py,sha256=Iu2MstoQBzXTmifW_jyWfomBT6nOUA6COO3_m0ufm2Q,1426 +openai/types/fine_tuning/reinforcement_hyperparameters_param.py,sha256=_NwYZjJ1bKN_ePxITeB0rgLMhO8Xpm8xNoYQ9aB_c_8,1357 +openai/types/fine_tuning/reinforcement_method.py,sha256=pGc_df_gFfIvCfqFeYH7vlrMBhw44LZt70L0s18EK6I,958 +openai/types/fine_tuning/reinforcement_method_param.py,sha256=FpgTPJewfFQB9ZU0IrmHWyEAmcQ8cxDqmEu15xwOAhg,1090 +openai/types/fine_tuning/supervised_hyperparameters.py,sha256=F3fY--I2O4cBOHflfn09aeHW8iZKA7cIhAMdMzPqc4I,865 +openai/types/fine_tuning/supervised_hyperparameters_param.py,sha256=WogLPJmKhsqgj6YMGxXQ3mY8BusZgCx45StftqNTayg,862 +openai/types/fine_tuning/supervised_method.py,sha256=p9lV9DCi7KbkfOuZdytm1Sguqt-0AWtRiNawxxSuCgA,408 +openai/types/fine_tuning/supervised_method_param.py,sha256=LNvDK4FdDWflr7KQHYBDcWP9UB5UBcGP3YohVsnvi7s,445 +openai/types/graders/__init__.py,sha256=GiHbVTKVpfAqbbzZrtF-N00Njkr28cNG26wd_EDLPGI,1019 +openai/types/graders/__pycache__/__init__.cpython-313.pyc,, +openai/types/graders/__pycache__/label_model_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/label_model_grader_param.cpython-313.pyc,, +openai/types/graders/__pycache__/multi_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/multi_grader_param.cpython-313.pyc,, +openai/types/graders/__pycache__/python_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/python_grader_param.cpython-313.pyc,, +openai/types/graders/__pycache__/score_model_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/score_model_grader_param.cpython-313.pyc,, +openai/types/graders/__pycache__/string_check_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/string_check_grader_param.cpython-313.pyc,, +openai/types/graders/__pycache__/text_similarity_grader.cpython-313.pyc,, +openai/types/graders/__pycache__/text_similarity_grader_param.cpython-313.pyc,, +openai/types/graders/label_model_grader.py,sha256=z7YmiMn7suYk5CbIFAn8MLTnYeJgxhJNiDcI5S4rDGQ,2026 +openai/types/graders/label_model_grader_param.py,sha256=21MydaUGP5Y5zBW61ShSxwtpzY-NcC3gGJaaCWka1KU,2310 +openai/types/graders/multi_grader.py,sha256=QyTkY28D7_DyZHOdlTCpLHHyzWFYDs8KT4-30_XgSLY,1018 +openai/types/graders/multi_grader_param.py,sha256=6-AOnwpdJt5yGBqdtSu7fPOIav0GuipZMg5ZnDskYtc,1191 +openai/types/graders/python_grader.py,sha256=WnZ24W9dtfqX8ZEPgVArYNkyAQElz2j-6no03u1wcU0,534 +openai/types/graders/python_grader_param.py,sha256=ss-fnK1MZe9eDLvFd2sz1AayD3cbuIMBn3mXCDUZMb8,565 +openai/types/graders/score_model_grader.py,sha256=9-Z83d1YfuEeL-o1fUjreSc-7hLTzNi66QVLjfJIjSg,3034 +openai/types/graders/score_model_grader_param.py,sha256=JdEZTVr-2-4ACcE8R5n3m2yPh7JdfQFO0pQqgYRAnlc,3199 +openai/types/graders/string_check_grader.py,sha256=Ofmiv6cZw6Le42M-XQ2p_IJqazRLN626xf_zie5LVKE,675 +openai/types/graders/string_check_grader_param.py,sha256=gwIhLOMY4xyI6lKLwGTrTlorb98mODRATC1Ei2KbvrY,771 +openai/types/graders/text_similarity_grader.py,sha256=SYoSbN81qi3_Q-y_l7H4B_ATbwfLlx_RnzY2J11f1FQ,887 +openai/types/graders/text_similarity_grader_param.py,sha256=fWPcnMC6Qp0NjsaQOm7wJ0eCumyXex99MX7URGm2ja4,1045 +openai/types/image.py,sha256=cWbI4EZxZ_etXKGl0u-7sr3_fJEaWwP0RpJ2fSIDYfc,766 +openai/types/image_create_variation_params.py,sha256=Xeka4vp5V0o8R_6vnLsqiQhWH5O6tUSCyO3FKGVmAeU,1426 +openai/types/image_edit_completed_event.py,sha256=E19lxYAYTACjUME298BXryQdQZ0DnzWZPbzM636el6k,1736 +openai/types/image_edit_params.py,sha256=mm2OrOvhOK9-bnBNx9OU5qy-fQhrYwu29uYXyuADsKI,5330 +openai/types/image_edit_partial_image_event.py,sha256=kgMb_9JveHjePvhZFhUnj5-us1mdZhgzFaoOUPmFBLU,1095 +openai/types/image_edit_stream_event.py,sha256=GtHKc8VdumW5RnQtIiyMqhwIIaqYogKXZF1QNuq9Bd4,516 +openai/types/image_gen_completed_event.py,sha256=sA2Ezhl-Gwh0cPq3VFmDSZDD8yiO1i5mkB-BziIdqd8,1745 +openai/types/image_gen_partial_image_event.py,sha256=vTArcJ1v00opWXiP8iUr9L886cg1VUCtoJLL8NCUH8I,1077 +openai/types/image_gen_stream_event.py,sha256=gVzdE6qzBPpK3kEFM7EdoUzBa4DgCaS3AdF9gjd0pUs,508 +openai/types/image_generate_params.py,sha256=7GBDjcoEdKX8buOK6IroOn7eH9GFkcXb-LGYKfVuRMU,5323 +openai/types/image_model.py,sha256=v8nkOop8L8LS6WSMhl4poJ0edMN9Khkdn9epylLQDvE,234 +openai/types/images_response.py,sha256=cpbt5tKIax5JIDM4FSj3hjo2RO7AFN2pJPNQm4AWqeM,1905 +openai/types/model.py,sha256=DMw8KwQx8B6S6sAI038D0xdzkmYdY5-r0oMhCUG4l6w,532 +openai/types/model_deleted.py,sha256=ntKUfq9nnKB6esFmLBla1hYU29KjmFElr_i14IcWIUA,228 +openai/types/moderation.py,sha256=6mV-unXrz5mA47tFzMNPiB--ilWRpOXlCtT5HKZE7vg,6840 +openai/types/moderation_create_params.py,sha256=bv5qr2y_MQ1MYBhWWUiCET2L18ypWtQpaIKzYTrl9xs,1032 +openai/types/moderation_create_response.py,sha256=e6SVfWX2_JX25Za0C6KojcnbMTtDB2A7cjUm6cFMKcs,484 +openai/types/moderation_image_url_input_param.py,sha256=t1r9WD3c-CK2Al1lpB4-DjfzLFSwgETR0g8nsRdoL0Y,622 +openai/types/moderation_model.py,sha256=BFeqSyel2My2WKC6MCa_mAIHJx4uXU3-p8UNudJANeM,319 +openai/types/moderation_multi_modal_input_param.py,sha256=RFdiEPsakWIscutX896ir5_rnEA2TLX5xQkjO5QR2vs,483 +openai/types/moderation_text_input_param.py,sha256=ardCbBcdaULf8bkFuzkSKukV9enrINSjNWvb7m0LjZg,406 +openai/types/other_file_chunking_strategy_object.py,sha256=Hf9XBL1RpF9ySZDchijlsJQ59wXghbVa0jp8MaEoC-4,310 +openai/types/realtime/__init__.py,sha256=0TmyntMzkZibpUpZzkosNpMcycv0w32QlNEjh8cb9Qo,16664 +openai/types/realtime/__pycache__/__init__.cpython-313.pyc,, +openai/types/realtime/__pycache__/audio_transcription.cpython-313.pyc,, +openai/types/realtime/__pycache__/audio_transcription_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/client_secret_create_params.cpython-313.pyc,, +openai/types/realtime/__pycache__/client_secret_create_response.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_created_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_added.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_create_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_create_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_created_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_delete_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_delete_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_deleted_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_done.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_input_audio_transcription_completed_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_input_audio_transcription_delta_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_input_audio_transcription_failed_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_input_audio_transcription_segment.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_retrieve_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_retrieve_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_truncate_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_truncate_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/conversation_item_truncated_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_append_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_append_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_clear_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_clear_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_cleared_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_commit_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_commit_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_committed_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_speech_started_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_speech_stopped_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/input_audio_buffer_timeout_triggered.cpython-313.pyc,, +openai/types/realtime/__pycache__/log_prob_properties.cpython-313.pyc,, +openai/types/realtime/__pycache__/mcp_list_tools_completed.cpython-313.pyc,, +openai/types/realtime/__pycache__/mcp_list_tools_failed.cpython-313.pyc,, +openai/types/realtime/__pycache__/mcp_list_tools_in_progress.cpython-313.pyc,, +openai/types/realtime/__pycache__/noise_reduction_type.cpython-313.pyc,, +openai/types/realtime/__pycache__/output_audio_buffer_clear_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/output_audio_buffer_clear_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/rate_limits_updated_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config_input.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config_input_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config_output.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config_output_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_config_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_formats.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_formats_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_input_turn_detection.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_audio_input_turn_detection_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_client_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_client_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_connect_params.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_assistant_message.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_assistant_message_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_function_call.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_function_call_output.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_function_call_output_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_function_call_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_system_message.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_system_message_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_user_message.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_conversation_item_user_message_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_error.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_error_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_function_tool.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_function_tool_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_approval_request.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_approval_request_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_approval_response.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_approval_response_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_list_tools.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_list_tools_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_protocol_error.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_protocol_error_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_tool_call.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_tool_call_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_tool_execution_error.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcp_tool_execution_error_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcphttp_error.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_mcphttp_error_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_audio_output.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_audio_output_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_mcp_tool.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_mcp_tool_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_params.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_create_params_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_status.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_usage.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_usage_input_token_details.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_response_usage_output_token_details.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_server_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_session_client_secret.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_session_create_request.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_session_create_request_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_session_create_response.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tool_choice_config.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tool_choice_config_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tools_config.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tools_config_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tools_config_union.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tools_config_union_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tracing_config.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_tracing_config_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio_input.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio_input_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio_input_turn_detection.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio_input_turn_detection_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_audio_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_create_request.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_create_request_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_create_response.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_transcription_session_turn_detection.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_truncation.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_truncation_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_truncation_retention_ratio.cpython-313.pyc,, +openai/types/realtime/__pycache__/realtime_truncation_retention_ratio_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_audio_delta_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_audio_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_audio_transcript_delta_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_audio_transcript_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_cancel_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_cancel_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_content_part_added_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_content_part_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_create_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_create_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_created_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_function_call_arguments_delta_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_function_call_arguments_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_mcp_call_arguments_delta.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_mcp_call_arguments_done.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_mcp_call_completed.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_mcp_call_failed.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_mcp_call_in_progress.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_output_item_added_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_output_item_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_text_delta_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/response_text_done_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/session_created_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/session_update_event.cpython-313.pyc,, +openai/types/realtime/__pycache__/session_update_event_param.cpython-313.pyc,, +openai/types/realtime/__pycache__/session_updated_event.cpython-313.pyc,, +openai/types/realtime/audio_transcription.py,sha256=p3L99f6gmcnYTNfde6bUsevaRPpVCDh-CXiHcyHYrGg,1209 +openai/types/realtime/audio_transcription_param.py,sha256=ZIvJL36zOMYEZ3A5fXplV3lgx64oVTISyiGNvbXVKwE,1150 +openai/types/realtime/client_secret_create_params.py,sha256=g1pj1BB4T5ZvUltoj6BgfAEqzL2zCtMYV5Ai_ZJioLM,1674 +openai/types/realtime/client_secret_create_response.py,sha256=maHTZ6A_YogizgdV4jy5xOakvVMRUc6NRyWxzC9hObY,932 +openai/types/realtime/conversation_created_event.py,sha256=dJiXF9qKzTyPGFjURZYRrtu0np1ZtDpSYUpQgXPzrRo,751 +openai/types/realtime/conversation_item.py,sha256=BGqZp9UpybVbEyr6enYqdleryy4NMbXpzkUPX03cvoI,1437 +openai/types/realtime/conversation_item_added.py,sha256=3cMQ_vYbEUlnPTYFZmayW4dqkt-gpbzNxDHI0RJhWL8,742 +openai/types/realtime/conversation_item_create_event.py,sha256=-42Pp6Kswz74lpWr7sHbDI3FO4byz5TJvD3VLMNRwhg,1089 +openai/types/realtime/conversation_item_create_event_param.py,sha256=14RaZ7n5CRh6cKaOsOsN6n94MLLijFzY9KmltHnH8xk,1110 +openai/types/realtime/conversation_item_created_event.py,sha256=2err9ZwNCqt9oxy-jvp5y_T8C0_OkHl_KxJCwyHesaY,825 +openai/types/realtime/conversation_item_delete_event.py,sha256=Ao3zKkKF_JQyBwFK1fGojKw96cZjIfHziwvRyLPpgMQ,548 +openai/types/realtime/conversation_item_delete_event_param.py,sha256=a17h8Hd8MxUbXT6NQg8YpTr1ICt1ztRecpfukHw4g34,569 +openai/types/realtime/conversation_item_deleted_event.py,sha256=7dZc3PmGyeSwNGwHCvQgoHwYK4QN9kcv9kRPL4QfSak,491 +openai/types/realtime/conversation_item_done.py,sha256=2dlfFQgk0mSVCoOPUdXKbKShbzsesucxkk84bob_R1A,738 +openai/types/realtime/conversation_item_input_audio_transcription_completed_event.py,sha256=1GEybZ5q1L8lH0p0lA-grhCmm8F8WN3mUcLAC-FG-vg,2440 +openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py,sha256=xy20zUa5uSj0HtefAbOq5ZgG_N4o-HkAbxecbIhvOhc,1349 +openai/types/realtime/conversation_item_input_audio_transcription_failed_event.py,sha256=Gwm8rry9Tsv2eNkfrjsjDE69K9qmc27KXcps3zdCTGA,1076 +openai/types/realtime/conversation_item_input_audio_transcription_segment.py,sha256=hBP5di6OQ9u5fhKjKz6XKmy7T-An8orAlZfboIYukHo,990 +openai/types/realtime/conversation_item_param.py,sha256=yrtdTZDIfAsJGwSXDY7v-_e9GtOPqRNXQAM2LWjxOOI,1483 +openai/types/realtime/conversation_item_retrieve_event.py,sha256=qGlMQI_0YfoO11d0VgV5iVFLHMCjHErPWN516xn0h9s,558 +openai/types/realtime/conversation_item_retrieve_event_param.py,sha256=TRYaZ3btNaywRPaMOVRzK5VT7wh4taIGjbUdhkZ7gFc,579 +openai/types/realtime/conversation_item_truncate_event.py,sha256=IcWi21tiuaduW2S_-w5qSYZIIYEY5c-mRvpb54In_pM,944 +openai/types/realtime/conversation_item_truncate_event_param.py,sha256=-rMZ2Y1TJ-naH6g7Ht8dipjQRnOnSW8xWHrzT9Up4P4,985 +openai/types/realtime/conversation_item_truncated_event.py,sha256=W2L6YmRG-YQ3YZd0knL-EUL3_qPColjJj-DzdECYwv0,703 +openai/types/realtime/input_audio_buffer_append_event.py,sha256=iY7_Acz5Lu6Ul_2d-Ho0Tnjo4b8y-eZuztjsgJtqVPQ,661 +openai/types/realtime/input_audio_buffer_append_event_param.py,sha256=XmN2bE6jBRrkKGVPJdnPjJql5dqMPqwbmFnxo-z22JE,682 +openai/types/realtime/input_audio_buffer_clear_event.py,sha256=8qKqJLRpEhiMcGiuosO5TRx6e0qCIZq3F-TF-pWqIcU,488 +openai/types/realtime/input_audio_buffer_clear_event_param.py,sha256=y-zfWqJsh1n6r2i0MgLDpnNC4g1dq3GCS66Twfkng38,499 +openai/types/realtime/input_audio_buffer_cleared_event.py,sha256=L4tqLyaTqQGdBoZudMxF0BJNqT5-lUVWKuSudIFKA6U,428 +openai/types/realtime/input_audio_buffer_commit_event.py,sha256=gXFJz3MRKaOcjMB5MpmzPSM3tj5HHPxWSScpGJCVEpE,492 +openai/types/realtime/input_audio_buffer_commit_event_param.py,sha256=B8agXC-rUl-D-RijJ5MeTLgw43qVYzmf2_2oAVokhLY,503 +openai/types/realtime/input_audio_buffer_committed_event.py,sha256=_u1WZzg0jTPr4NEwav7dVpYJNDPjv0sI-4XzFSFlJj0,732 +openai/types/realtime/input_audio_buffer_speech_started_event.py,sha256=e7EScZ7HN3GL9jvQVMKz7qRZ6vPIsRO6yPGkHlFBvIs,860 +openai/types/realtime/input_audio_buffer_speech_stopped_event.py,sha256=VAHzgW0UzAQz2cA_j3VgVmfbiRJeH7GzhugeyAXGfC0,778 +openai/types/realtime/input_audio_buffer_timeout_triggered.py,sha256=Q8Og1NhtzVz_YLVm2VWk7ZqxB00lVn5H7anwvG12wVo,853 +openai/types/realtime/log_prob_properties.py,sha256=ADUI2Bprv-PM8EGaMLOo77UpbYQKttIOyLuR1lsEJd0,452 +openai/types/realtime/mcp_list_tools_completed.py,sha256=jc7_Cz3ZPrxrHFIoRaesudFHm7XLwEfbxASknRBR-1w,473 +openai/types/realtime/mcp_list_tools_failed.py,sha256=do32WvGDKI15Mcwp86_eUU1Yj3JGs7KOctwrddchlwM,461 +openai/types/realtime/mcp_list_tools_in_progress.py,sha256=4nOZiQCY6DAAxpST0K2wQGSvqsffgWczyyxaFgoPOJI,479 +openai/types/realtime/noise_reduction_type.py,sha256=lrAb7YhMM-anRYzzOha8hcVloNJR_zWuFrO2SccrcIo,238 +openai/types/realtime/output_audio_buffer_clear_event.py,sha256=VP4gqG3Mkc4n3uo_AuGzC9062yRAVc5h-wpRk0bga1g,493 +openai/types/realtime/output_audio_buffer_clear_event_param.py,sha256=gUnmGZhwaMW5tpfYkEjafmcjuxe6eVk0CwQsq_od0Pc,504 +openai/types/realtime/rate_limits_updated_event.py,sha256=lPYwNoaEopdkfIr5KDOz0ns1OJKEn-2HI209zpDzeuQ,948 +openai/types/realtime/realtime_audio_config.py,sha256=TXlcVjt8PwthyneFJ0kUqF4j2nwG-ubJyHENzrcd0gU,467 +openai/types/realtime/realtime_audio_config_input.py,sha256=48ANMlwtkmcH04CvcDXJxJYF4VIhaBzJSdXn3a3eV1Y,2874 +openai/types/realtime/realtime_audio_config_input_param.py,sha256=grQocM_NhSJlByguflJ7jc4H1O6CknI5Im_A85_NbDg,2926 +openai/types/realtime/realtime_audio_config_output.py,sha256=DdlfBuf2quGvKikEcNFRx8C41B-fO6iENK9L5Y6DCHA,1389 +openai/types/realtime/realtime_audio_config_output_param.py,sha256=elX8xA49gDbbFjvJv24dquBwJVyxtOJHIwHN6XWR2Vg,1371 +openai/types/realtime/realtime_audio_config_param.py,sha256=RcizKdhyXCLKrykVY3pQx_z_w4Oe1Xk5p2IqcHgvZu8,503 +openai/types/realtime/realtime_audio_formats.py,sha256=YTBxJ-D1AHA0EoaH1s-N99489Y57beSn7RiA6SjxIuQ,926 +openai/types/realtime/realtime_audio_formats_param.py,sha256=jtxa21eFt-2XkhMMadEvZ7MTv-itqCRWqDi4VEmMjwI,817 +openai/types/realtime/realtime_audio_input_turn_detection.py,sha256=b3xLXLZ7tsLoTKE2Ex-dqK5mir0QhA0ohpKEgErwDZg,3449 +openai/types/realtime/realtime_audio_input_turn_detection_param.py,sha256=ulsMAl_sDB6In9I9aGI1XERH-cVUtEyQPU9uyOtF0rk,3280 +openai/types/realtime/realtime_client_event.py,sha256=4_lYEyK-wj25VTh8GTaV0mZ0t17KhkfJrQ0yUF0mCYU,1473 +openai/types/realtime/realtime_client_event_param.py,sha256=YPveu8tNyKmZkK24qEJv8js5l5NNygDyAcsza2iOmKw,1543 +openai/types/realtime/realtime_connect_params.py,sha256=AvTypkFCYmDn9qMeektVqij6cqzgovr3PpgpMalJoJ4,290 +openai/types/realtime/realtime_conversation_item_assistant_message.py,sha256=g67lu3x-Z3zw9RdXyEOWTbmsDKlmRNZErtE510jMsy8,1715 +openai/types/realtime/realtime_conversation_item_assistant_message_param.py,sha256=vlSO9xgZHh099lbQU4FqngPEIgkNDB9AsFwatJeFR0I,1683 +openai/types/realtime/realtime_conversation_item_function_call.py,sha256=7HTj4l_AtGBPxRZqQ9JlY9uuBLrOIDatyBE_JVji9YU,1202 +openai/types/realtime/realtime_conversation_item_function_call_output.py,sha256=E5BtjqP6anIi9XpdVKtpd8pFh8SXoersKOpn6hbrS5o,1103 +openai/types/realtime/realtime_conversation_item_function_call_output_param.py,sha256=45NvbyGoO4V6lbeQn5mKck8SQJGHQb3xtgTy2GmnuqE,1100 +openai/types/realtime/realtime_conversation_item_function_call_param.py,sha256=hxeYcWk09Lota1TqIZvg5kXMu_0S0y9iDGJxPlzHmVA,1182 +openai/types/realtime/realtime_conversation_item_system_message.py,sha256=mq0tDiLi7r4bMRqI83lgnSF1uJwGsFUfhKr2181ELYI,1224 +openai/types/realtime/realtime_conversation_item_system_message_param.py,sha256=0iLyhkIE6xLzjDI7vqa-bbs73kWnaCQz8rHBujMY6nA,1226 +openai/types/realtime/realtime_conversation_item_user_message.py,sha256=N7jJ9WlJMabAyvldcGJzfVL1w2Nw-wDcBJma3lyIJeQ,2111 +openai/types/realtime/realtime_conversation_item_user_message_param.py,sha256=b6KnyeTZty254f5A2GCCoiH-cvIXffs9UrLJprlRSFQ,2045 +openai/types/realtime/realtime_error.py,sha256=1pg3if_lIqzP7Ow23UGQyqs8x0PLdiLIC-Ax79TLe6Y,625 +openai/types/realtime/realtime_error_event.py,sha256=fAosJOL7vMbG5JYMwzg8yrRBaT0INz4W_1XCxIUFzTw,466 +openai/types/realtime/realtime_function_tool.py,sha256=3CDiCZCM0A1VLRxOFdG4teFXr8dx0JFU94KbSn-JgGc,734 +openai/types/realtime/realtime_function_tool_param.py,sha256=-vDBSmMWNdbABC8dxVckkNeRdEujAKeff6icJvYrM0I,674 +openai/types/realtime/realtime_mcp_approval_request.py,sha256=Li-i-Sa7tfiI5nWA4Dyz4ac3_KTWd_qLc3u7KNOcMjM,621 +openai/types/realtime/realtime_mcp_approval_request_param.py,sha256=zdoRzHIrSzhfa3DTO4XyYQ4P1hNq4J3XesJFQmuD-9Q,717 +openai/types/realtime/realtime_mcp_approval_response.py,sha256=3GcWB31Mg2pWynk3-IqflayLAD6QRt_UXB2-4sKxgOU,676 +openai/types/realtime/realtime_mcp_approval_response_param.py,sha256=CU8G-jv5aYbTrts4JQuZeLHf3RZ2HgIrsCDtwkqSxk8,755 +openai/types/realtime/realtime_mcp_list_tools.py,sha256=MzGc-pTTKpBqweIMwvz5BOzBtDQGmqXFkY0En81l1Xw,889 +openai/types/realtime/realtime_mcp_list_tools_param.py,sha256=8L8i5K1xUxvT2Op4B5hN-x9YoclR9Wlb9vNi2q1TQo4,975 +openai/types/realtime/realtime_mcp_protocol_error.py,sha256=4jqkfl6h7tFT5kQy40VW24LrokpKe6X4VROYlNmOHDQ,313 +openai/types/realtime/realtime_mcp_protocol_error_param.py,sha256=jlufPTMU_9JuYtqzQGTmb0o978gDiOFxkNx0yJAvwx8,389 +openai/types/realtime/realtime_mcp_tool_call.py,sha256=s1sx6konXKS340J7oI01BOKnwm2uP2aOlmOmBwKdnnQ,1325 +openai/types/realtime/realtime_mcp_tool_call_param.py,sha256=9-ks4Mhu91HzzgZBjq1zHqO1zP4ae4ezdbYgI367O34,1339 +openai/types/realtime/realtime_mcp_tool_execution_error.py,sha256=swcOrTKO5cx1kkfGS_5PhBPEQx_Vf_ZW04HbA5eRa0g,314 +openai/types/realtime/realtime_mcp_tool_execution_error_param.py,sha256=3IuPmvy52n_VByGYqfCr87kciEQdJMTcwGWj4__PiX8,380 +openai/types/realtime/realtime_mcphttp_error.py,sha256=-Zqz0xr2gPs6peG_wC3S8qVgtEUJNrZm4Mm5BIvmZw0,301 +openai/types/realtime/realtime_mcphttp_error_param.py,sha256=GcmAMBvZVNrN9p_tneHPu_pyN7D8wCytaAKruFtMfwI,377 +openai/types/realtime/realtime_response.py,sha256=IvGy_VZPIRVCD4-mLElif7bOVMFJglR0tvU1zpfz6ys,3826 +openai/types/realtime/realtime_response_create_audio_output.py,sha256=gnMvrt0BR440zNDOmYB-j_Eh9WcaDExnZE8P68ptmdc,1004 +openai/types/realtime/realtime_response_create_audio_output_param.py,sha256=u1kCAMUjCRFoM402IZbfvRxvQLzrKN66PLqKG-yD2i4,999 +openai/types/realtime/realtime_response_create_mcp_tool.py,sha256=OhQM73g8gqOgsWphIb6Jw31ZaaucbG9BKDu7qk6mc2Y,4512 +openai/types/realtime/realtime_response_create_mcp_tool_param.py,sha256=2kxSDx7qzMPwB-pizGyqlr6QA2EnaSoEI3U_3RE0Ykg,4415 +openai/types/realtime/realtime_response_create_params.py,sha256=VECIsK9brymU5sgjGwDtTbb8-X_jYvcVEHo1QMLIFE4,4284 +openai/types/realtime/realtime_response_create_params_param.py,sha256=85nEALuSKC4TBGSj6qlZEUrqnNHEkhKsZuFtxTIqh-w,4316 +openai/types/realtime/realtime_response_status.py,sha256=bSeFcCy9c4jyf12ZzJFcxpCYKrSwMEgpNipOE1SNqcA,1325 +openai/types/realtime/realtime_response_usage.py,sha256=rxUW5DM1d4BY3F74KaImcADVnWasSv_Zj_febO30Vms,1429 +openai/types/realtime/realtime_response_usage_input_token_details.py,sha256=YcOrEtHj9QjJ-s3fmNqGMJ2nJUcJO_J9yXbCueppqZo,1244 +openai/types/realtime/realtime_response_usage_output_token_details.py,sha256=9wWB5tRft0LQsIgsIBsSaAhv4rDGgTl9Y5svpGU4ooE,459 +openai/types/realtime/realtime_server_event.py,sha256=5XfW7BkJMsJJUGXq0hCd7AtCa2uPPKnQbqkrorx_LYk,6578 +openai/types/realtime/realtime_session_client_secret.py,sha256=hjco-0FnTvhnMSLezczUBDz739hbvZSbxB4BeZCeark,583 +openai/types/realtime/realtime_session_create_request.py,sha256=05tGSOefe55ZmPjBBqZ7RsrT_OyXcx-fHohbFJymGrY,4142 +openai/types/realtime/realtime_session_create_request_param.py,sha256=tFkmJJROx7z2KXTMeYJqjZDg799UQ2Ou8_33KraoCRM,4128 +openai/types/realtime/realtime_session_create_response.py,sha256=GPhTQCPUoPQQkiYT85jEEgunMJcM5oG6guylOEuO9Ws,16791 +openai/types/realtime/realtime_tool_choice_config.py,sha256=DV0uuyfK59paj5NC9adQskUF2km5TRSiHAlMDu1Fmdo,472 +openai/types/realtime/realtime_tool_choice_config_param.py,sha256=0vqYNM4MkU5d8GXfitT6AoE9AubKeLZOSHGOH8q73QU,550 +openai/types/realtime/realtime_tools_config.py,sha256=JSxehiQnA_tJUeXvi2h9H6wlYsnhhtRWB_o5S20V-oQ,318 +openai/types/realtime/realtime_tools_config_param.py,sha256=0jxEaIIHOdhLLAN2zQqsx8hrHSjWWeVvTW-896ye3gs,4708 +openai/types/realtime/realtime_tools_config_union.py,sha256=FbA6HwGnNC9AKBNh-3vjb7yzag5Snc88RY18gim-fY8,4769 +openai/types/realtime/realtime_tools_config_union_param.py,sha256=Wkxn6uvJDWi1IadV_DjbPmYeyThJlB50S4iizpw5Xvk,4595 +openai/types/realtime/realtime_tracing_config.py,sha256=TzKfoTJuLjPBG-qozwigXQv1uAZszgVX_K-U6HaiEjY,871 +openai/types/realtime/realtime_tracing_config_param.py,sha256=SqfUQ8RO0Re28Lb2AF2HlaJj7LS_3OK3kHXrUsKPcDc,840 +openai/types/realtime/realtime_transcription_session_audio.py,sha256=yGDcdMTaxGZKIgmDKnKQeEtgEH5SVYJfPXpr_zAr03c,414 +openai/types/realtime/realtime_transcription_session_audio_input.py,sha256=IXUUnr2WbKCeqPyd9VTge1Ho0MQvy0FZMh2l0awdTZs,3003 +openai/types/realtime/realtime_transcription_session_audio_input_param.py,sha256=sCvGim5THVMJ1c1a5ipyiht85tcrkgt75OsLIUp8ncs,3055 +openai/types/realtime/realtime_transcription_session_audio_input_turn_detection.py,sha256=nLF5DpguSg4-ectSCSSvbV7t7X2Z_yUvSCNQEdEuFEM,3489 +openai/types/realtime/realtime_transcription_session_audio_input_turn_detection_param.py,sha256=VL4MchzWUsCShFXvTnfJOKUqOh71mtZ_0YmEBrJ_ofQ,3320 +openai/types/realtime/realtime_transcription_session_audio_param.py,sha256=IdEgpkEbtPrEHJ-KkvEcV_8aSvCBzxBQDUQhB6ehQgI,451 +openai/types/realtime/realtime_transcription_session_create_request.py,sha256=-hJUbNd0rR0pbMnCzXvCylhOSLWUG42RNweAk_KhpXw,899 +openai/types/realtime/realtime_transcription_session_create_request_param.py,sha256=kP35GihtGw5L6T1okdSRJ9rJrs7FDBURy7htgKPDMR0,928 +openai/types/realtime/realtime_transcription_session_create_response.py,sha256=dpnCsv19sMo4aQ3oYIcStplpKft1EFRxQFLzLvaCaUM,2434 +openai/types/realtime/realtime_transcription_session_turn_detection.py,sha256=hFAIILzs1QaQ8JvX8PoHBExUm3eNZKWnJQfjQKnGBfE,1040 +openai/types/realtime/realtime_truncation.py,sha256=lnr1Uq9kSs6OfJb_TcvQrs7jx92UuSKaIhGNvwUK-qU,380 +openai/types/realtime/realtime_truncation_param.py,sha256=wBXHiAPS_HA6MWBqhRGEtqZxu6RdIrgnTVRYgUljwq4,442 +openai/types/realtime/realtime_truncation_retention_ratio.py,sha256=443HkkzJeCKSvLGYOGENOnsFOECc_k8RK9rNrpgtir0,515 +openai/types/realtime/realtime_truncation_retention_ratio_param.py,sha256=_hvzGBKDeouf3aJsB0EYK6UsL1UnH0rq1zKyzMW98tQ,581 +openai/types/realtime/response_audio_delta_event.py,sha256=9-CcYOY4JeBiFYVkGwQ1uOVHrtRNxsMg43M3csgaOw4,755 +openai/types/realtime/response_audio_done_event.py,sha256=Kuc7DYWSIcNfCH8M2HIl80phHyYnHnChfSdp30qXqUA,692 +openai/types/realtime/response_audio_transcript_delta_event.py,sha256=Pr0dP0Up-jY-QQiyL07q9kByaOMkV0WIaYrkDOCLhXY,786 +openai/types/realtime/response_audio_transcript_done_event.py,sha256=IEbDxwWpjCIoMpT5-iu3gTSAqbmqvOcjsKsj3PuYKvQ,800 +openai/types/realtime/response_cancel_event.py,sha256=WCXDsVwgkgyb3L8Nh-bPaaiDnifXjLyPbxvoIkN7YA8,636 +openai/types/realtime/response_cancel_event_param.py,sha256=nidzBL83liHwyImiNGiz9Ad0V34EtFAQDw1utqcF6ns,630 +openai/types/realtime/response_content_part_added_event.py,sha256=CSsdmclKPRCclNpUixYg54tUmJG3Dy1fgKe2-D7E8fs,1231 +openai/types/realtime/response_content_part_done_event.py,sha256=ws8nIPrUln5ue45ID_UdR8AjgYQiL6F0imrv7TMRsfc,1189 +openai/types/realtime/response_create_event.py,sha256=GlWcb2kLyq9oDcsJQ4nkwWjfGjleMQWy6HmDKztCXU4,654 +openai/types/realtime/response_create_event_param.py,sha256=_NQArkqOHZCFJsxq26HjHGS2IgVh8cy4VcjN9M80cj8,665 +openai/types/realtime/response_created_event.py,sha256=7LMTqoVE0WiqlAdEYMN0weSTBBhU_4CyD3gFxLAeKcg,505 +openai/types/realtime/response_done_event.py,sha256=u44ZBOYbzqiC8VqqDp8YuA9qBmVHWLXMJZGvOqJOIks,493 +openai/types/realtime/response_function_call_arguments_delta_event.py,sha256=8mQkxsj6MEUMtVutdqQG3ERqL4u1qNY55WKSXMol-0s,792 +openai/types/realtime/response_function_call_arguments_done_event.py,sha256=iIDsECFP-jj_fkcDGa1ZHstjkBVYxdbFeNvZV3_z0sk,792 +openai/types/realtime/response_mcp_call_arguments_delta.py,sha256=wXMighxToTIFK2ElkOrIYKvxqN9i-tZDR3iUdTFvRFc,831 +openai/types/realtime/response_mcp_call_arguments_done.py,sha256=3Hlq2bJW31yvvPOin3IOf1XSRMLMwPoZL5Kn9uTm1-o,708 +openai/types/realtime/response_mcp_call_completed.py,sha256=OlfSjKJmHn77tdwgt5wVGbGXL8HHQWhYQzpFf8QuOWg,563 +openai/types/realtime/response_mcp_call_failed.py,sha256=m3AZktEUCOzRp6UKCLPhLDhgYYkaWmO3hUTwTRERBmA,551 +openai/types/realtime/response_mcp_call_in_progress.py,sha256=PjME9TvWMBBR5gnEgrOf8zbuliR3eYW1h48RDsRgPfA,569 +openai/types/realtime/response_output_item_added_event.py,sha256=B_H6V9ijObo-JOUFIEH1JqMdKhhSuY24K5I9rly1j6c,721 +openai/types/realtime/response_output_item_done_event.py,sha256=64b5NILItLOAi9IxkYEhfAkmJSzoYjDLo4WJaL-zdOY,717 +openai/types/realtime/response_text_delta_event.py,sha256=Al1GXaZ55DQbrEyou48U8IfP2525e9G7277YfFM9VSU,734 +openai/types/realtime/response_text_done_event.py,sha256=bhm59wW9hARgdl55rzzEvx33Xajy5gQ9Fr11RUWOeno,737 +openai/types/realtime/session_created_event.py,sha256=nPM98I--WtKuzs3Srofj6kptYbRYt9x5LBMxxL7j9mQ,770 +openai/types/realtime/session_update_event.py,sha256=TmxL9PYD7GD_MAhRoGsor7mhAp2PZl4JaWl_APLteew,1088 +openai/types/realtime/session_update_event_param.py,sha256=7uKlFHpoKcvYMCeAJ2cwCWe-dDPW6XeMV-zNgRvtX1E,1160 +openai/types/realtime/session_updated_event.py,sha256=a5zFzk9iBCpB6TOjb_x_KjTdOhIPOSlW3cpx3nGNiKk,770 +openai/types/responses/__init__.py,sha256=yNb-l2XC4L8jRJu9GLt3KJCJ6kgHj8GDZP6wC1nex6s,14969 +openai/types/responses/__pycache__/__init__.cpython-313.pyc,, +openai/types/responses/__pycache__/computer_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/computer_tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/custom_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/custom_tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/easy_input_message.cpython-313.pyc,, +openai/types/responses/__pycache__/easy_input_message_param.cpython-313.pyc,, +openai/types/responses/__pycache__/file_search_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/file_search_tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/function_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/function_tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/input_item_list_params.cpython-313.pyc,, +openai/types/responses/__pycache__/parsed_response.cpython-313.pyc,, +openai/types/responses/__pycache__/response.cpython-313.pyc,, +openai/types/responses/__pycache__/response_audio_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_audio_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_audio_transcript_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_audio_transcript_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_call_code_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_call_code_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_call_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_call_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_call_interpreting_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_tool_call.cpython-313.pyc,, +openai/types/responses/__pycache__/response_code_interpreter_tool_call_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_computer_tool_call.cpython-313.pyc,, +openai/types/responses/__pycache__/response_computer_tool_call_output_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_computer_tool_call_output_screenshot.cpython-313.pyc,, +openai/types/responses/__pycache__/response_computer_tool_call_output_screenshot_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_computer_tool_call_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_content_part_added_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_content_part_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_conversation_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_create_params.cpython-313.pyc,, +openai/types/responses/__pycache__/response_created_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call_input_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call_input_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call_output.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call_output_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_custom_tool_call_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_error.cpython-313.pyc,, +openai/types/responses/__pycache__/response_error_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_failed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_file_search_call_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_file_search_call_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_file_search_call_searching_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_file_search_tool_call.cpython-313.pyc,, +openai/types/responses/__pycache__/response_file_search_tool_call_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_format_text_config.cpython-313.pyc,, +openai/types/responses/__pycache__/response_format_text_config_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_format_text_json_schema_config.cpython-313.pyc,, +openai/types/responses/__pycache__/response_format_text_json_schema_config_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_call_arguments_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_call_arguments_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_tool_call.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_tool_call_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_tool_call_output_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_tool_call_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_web_search.cpython-313.pyc,, +openai/types/responses/__pycache__/response_function_web_search_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_image_gen_call_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_image_gen_call_generating_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_image_gen_call_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_image_gen_call_partial_image_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_includable.cpython-313.pyc,, +openai/types/responses/__pycache__/response_incomplete_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_audio.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_audio_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_content.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_content_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_file.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_file_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_image.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_image_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_item_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_message_content_list.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_message_content_list_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_message_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_text.cpython-313.pyc,, +openai/types/responses/__pycache__/response_input_text_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_item_list.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_call_arguments_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_call_arguments_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_call_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_call_failed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_call_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_list_tools_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_list_tools_failed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_mcp_list_tools_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_item_added_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_item_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_message.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_message_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_refusal.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_refusal_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_text.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_text_annotation_added_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_output_text_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_prompt.cpython-313.pyc,, +openai/types/responses/__pycache__/response_prompt_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_queued_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_item.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_item_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_summary_part_added_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_summary_part_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_summary_text_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_summary_text_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_text_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_reasoning_text_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_refusal_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_refusal_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_retrieve_params.cpython-313.pyc,, +openai/types/responses/__pycache__/response_status.cpython-313.pyc,, +openai/types/responses/__pycache__/response_stream_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_text_config.cpython-313.pyc,, +openai/types/responses/__pycache__/response_text_config_param.cpython-313.pyc,, +openai/types/responses/__pycache__/response_text_delta_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_text_done_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_usage.cpython-313.pyc,, +openai/types/responses/__pycache__/response_web_search_call_completed_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_web_search_call_in_progress_event.cpython-313.pyc,, +openai/types/responses/__pycache__/response_web_search_call_searching_event.cpython-313.pyc,, +openai/types/responses/__pycache__/tool.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_allowed.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_allowed_param.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_custom.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_custom_param.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_function.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_function_param.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_mcp.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_mcp_param.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_options.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_types.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_choice_types_param.cpython-313.pyc,, +openai/types/responses/__pycache__/tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/web_search_preview_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/web_search_preview_tool_param.cpython-313.pyc,, +openai/types/responses/__pycache__/web_search_tool.cpython-313.pyc,, +openai/types/responses/__pycache__/web_search_tool_param.cpython-313.pyc,, +openai/types/responses/computer_tool.py,sha256=bigJ0RyhP6jKtAB7YM-oP2sPtL1isCnZufTue80u9vg,607 +openai/types/responses/computer_tool_param.py,sha256=7SJn4rXdQeAt-DiMiXfdPI6Q_X6S7Wfxrc1Am8nPZeg,693 +openai/types/responses/custom_tool.py,sha256=WcsLiBUJbnMhjFF3hAFCP8SsCzzcbJh4BhC3NiVIl0c,736 +openai/types/responses/custom_tool_param.py,sha256=cAbh_D2pQa0SPEFrrRVPXXoQCndExjjqKrwRaBghWZk,748 +openai/types/responses/easy_input_message.py,sha256=4rPo04A1WVaCxLpPn3e_gJNgdNuAKlH9k6ijLK3-Bdc,817 +openai/types/responses/easy_input_message_param.py,sha256=8kM4AkSoiUOspuDTQPfdLjkgydQ9yHmo-FCfjdthtgU,873 +openai/types/responses/file_search_tool.py,sha256=WquLED7txr7E_6-YebznUuEwNDnMRbXW8fKEQdqro80,1369 +openai/types/responses/file_search_tool_param.py,sha256=pPJBWiEY_JwT0mon35qpD55yjgNTGHrP34YFxNgvNAw,1423 +openai/types/responses/function_tool.py,sha256=gpcLwRIXSp92jVJcIXBUnsSH_FzJrlH-jLIo-IbE1IY,796 +openai/types/responses/function_tool_param.py,sha256=ZDGBcqx-T24wgum2YHr3kBzk-P8lH-lCkuAHxyzKxGI,861 +openai/types/responses/input_item_list_params.py,sha256=wazm2tELpbpBWdAQrXGBq88Bm5RsxWXmlVJAV3f_k-I,964 +openai/types/responses/parsed_response.py,sha256=1rKsrhTtF8LhoRt_SHtBtQcRbztxAvPgZvTqGB9AMsY,3315 +openai/types/responses/response.py,sha256=WZcotgnNu3UrRgrClMXNYJAisVlGC12MX9hF-F6YFYQ,11617 +openai/types/responses/response_audio_delta_event.py,sha256=mXPosLnDn72HLG-Lk3EdyOw7isLm3HgpqQoYkG6XrJY,515 +openai/types/responses/response_audio_done_event.py,sha256=26KUM9PJlWIQi80FKo5TSD9lKJh7JnPHnUCD5cqIcrg,414 +openai/types/responses/response_audio_transcript_delta_event.py,sha256=Q3nSbPpT5Ij3iIvpweMF9KCct20B8MWJWOFV5pVqC8k,533 +openai/types/responses/response_audio_transcript_done_event.py,sha256=92_yKmcs8ILjaA6NeoZR1wuzUS0VXLzCfMNcdRji6-o,457 +openai/types/responses/response_code_interpreter_call_code_delta_event.py,sha256=mPveF26pvu_3esV1tMUnqfsT_NnZ1HWeqNM4F38NqUU,840 +openai/types/responses/response_code_interpreter_call_code_done_event.py,sha256=M5bmLyCJX8YFJv4GPtPBQZuXvt-ObQE9fztWnMli9rU,806 +openai/types/responses/response_code_interpreter_call_completed_event.py,sha256=STgdlJ5gQFLJeDwJGTGgvKKaJ_Ihz3qMNWWVjC9Wu4E,759 +openai/types/responses/response_code_interpreter_call_in_progress_event.py,sha256=4G7za-MHwtjkSILQeV_oQ6LEIzK35ak5HE3oi1pYFzA,767 +openai/types/responses/response_code_interpreter_call_interpreting_event.py,sha256=n8gNOqoJf47KE1T7kYE7q9bCeFnIUeODuFHmlGZcYkE,774 +openai/types/responses/response_code_interpreter_tool_call.py,sha256=QsApZaqsr9H2383UVyPw6_Xlf0sC3ciP1HS-R9Gq6QY,1650 +openai/types/responses/response_code_interpreter_tool_call_param.py,sha256=SHyZZ5nG-pch6XGBeDgw-exDnECNwXdwJSwHmvoZ684,1723 +openai/types/responses/response_completed_event.py,sha256=lpsi8GcuDN1Jk624y6TsUjpxRO39-Pt_QeuVtU8g-QA,517 +openai/types/responses/response_computer_tool_call.py,sha256=DZpxSuTbYHt4XDW50wpWm167hgHxZhBCnGbHN8SgUjQ,4644 +openai/types/responses/response_computer_tool_call_output_item.py,sha256=BYBAJUKqSsAbUpe099JeaWCmTsk4yt-9_RnRroWV2N0,1493 +openai/types/responses/response_computer_tool_call_output_screenshot.py,sha256=HVkJ_VJx1L9-sdIVzfdlk1EkrA3QSGJU24rcwqfvGzo,662 +openai/types/responses/response_computer_tool_call_output_screenshot_param.py,sha256=YJ3_l0_Z_sAbhIVMnBeCriUn1Izql404_YEQHLbt2Xg,656 +openai/types/responses/response_computer_tool_call_param.py,sha256=stigaaGzVgCkjN8vCCdOgpcpxYUhm-PYJNjJyElOR6c,5089 +openai/types/responses/response_content_part_added_event.py,sha256=P2CBuVxxxAgFzTP481h5hGa4IsfxYguwAQnbJLZQpcs,1337 +openai/types/responses/response_content_part_done_event.py,sha256=PosTBej2YbmUZmBWOZrxivITJIUryLWaT-jc65ZA0QY,1329 +openai/types/responses/response_conversation_param.py,sha256=sEhOVnULPS7_ZFHZ81YkLcF9yzlWd4OxWTuOvDdOcgE,340 +openai/types/responses/response_create_params.py,sha256=D3xjGayQxBOX_m7I7jZb46NWrjTEdAV92G1QRGQRbzo,13382 +openai/types/responses/response_created_event.py,sha256=YfL3CDI_3OJ18RqU898KtZyrf0Z9x8PdKJF2DSXgZrc,502 +openai/types/responses/response_custom_tool_call.py,sha256=3OFPImUjDkZPRnyf1anPoUD_UedOotTAF3wAeVs-BUM,730 +openai/types/responses/response_custom_tool_call_input_delta_event.py,sha256=AuKmvk_LEcZGNS3G8MwfAlGgizrPD5T-WwPV5XcwH7s,695 +openai/types/responses/response_custom_tool_call_input_done_event.py,sha256=6sVGqvbECYHfrb1pqbg0zPSO6aFu4BfG5fwI-EkCHOA,681 +openai/types/responses/response_custom_tool_call_output.py,sha256=XAwmrZXrzPCUvL7ngGBEe8SG89tmwUm6HSTk2dcl5dM,712 +openai/types/responses/response_custom_tool_call_output_param.py,sha256=vwB0jeJgbSsbPr77TYMUlhmyhR2didIiAXWDGdUmzPY,743 +openai/types/responses/response_custom_tool_call_param.py,sha256=bNJuc1YiF8SToRWjP0GiVgmttQieNPW0G5cfuKpvRhQ,771 +openai/types/responses/response_error.py,sha256=k6GX4vV8zgqJaW6Z15ij0N0Yammcgbxv3NyMxZeJsdQ,915 +openai/types/responses/response_error_event.py,sha256=695pQwl1Z2Ig7-NaicKxmOnhBDQKAcM44OiYCwl3bRc,576 +openai/types/responses/response_failed_event.py,sha256=Y0g4NnAuY3ESLzrkJ6VUqQ2CuQYBQ3gCK5ioqj4r9Rg,492 +openai/types/responses/response_file_search_call_completed_event.py,sha256=6gpE8B-RMbcnniTAZOaXG8Aaphy4A0--lbzKc7mwojg,671 +openai/types/responses/response_file_search_call_in_progress_event.py,sha256=wM-A66CcIlOiZL-78U76IjlrQo2DWEuR6Ce-vlRlNLQ,677 +openai/types/responses/response_file_search_call_searching_event.py,sha256=wdDdm9zEPEFx6dNZx1omfN4Qlchf92vXh6s6AojYWM8,671 +openai/types/responses/response_file_search_tool_call.py,sha256=DE3NhTc7hR5ZcTfHHV7FddimfuMIu5bjLIWJPRe0_9E,1664 +openai/types/responses/response_file_search_tool_call_param.py,sha256=uNt3RQNJtRIhuyJ6iEadR_1KQ_urwzszo8hdCbuof30,1737 +openai/types/responses/response_format_text_config.py,sha256=Z1uv9YytZAXaMtD_faYD6SL9Q8kOjSvRQXFkSZc0_hY,647 +openai/types/responses/response_format_text_config_param.py,sha256=T6cMHds5NYojK9fZMMldWYBypWwVmywIIbkRm5e4pMc,625 +openai/types/responses/response_format_text_json_schema_config.py,sha256=Bg7fRMlXuBz95kDZnee3cTNavvZNbPganIL4QI-rPLg,1414 +openai/types/responses/response_format_text_json_schema_config_param.py,sha256=7Uaoc1Uj60cVFL6_XRtErwi5veXJO-v_T3KIpS6XTdE,1396 +openai/types/responses/response_function_call_arguments_delta_event.py,sha256=qXcRpMudoAGWOHo-SaBDq9V9ZrIm1qtiCbBU0pPbj04,792 +openai/types/responses/response_function_call_arguments_done_event.py,sha256=Pw3Yhurnq2xyRmj-HpNPp3mU9rg8ZgSMulHlb4NTDQ8,572 +openai/types/responses/response_function_tool_call.py,sha256=SNaR7XXA6x5hFWMVjB2gsa-VBViodKSDb72eNdbHp8Q,917 +openai/types/responses/response_function_tool_call_item.py,sha256=Xbkpq2_-OQ70p-yA---inPz6YaRU8x1R4E6eTiWN7Zs,340 +openai/types/responses/response_function_tool_call_output_item.py,sha256=NlYlCJW1hEn61heh9TMdrYHRVpOYXHucOH6IXVA6588,886 +openai/types/responses/response_function_tool_call_param.py,sha256=k153-Qo1k-VPZidjuBPp2VcB6RGYGEQjGbZO2_RJ6ZY,941 +openai/types/responses/response_function_web_search.py,sha256=72x-qMcenYqDZfLRuFa3wA19jsXZn6UDnB0uRRtNi18,1794 +openai/types/responses/response_function_web_search_param.py,sha256=d_STmLPRRJki_Q533r2RlW_g3FktylWVxCvG3UI2Z5M,1937 +openai/types/responses/response_image_gen_call_completed_event.py,sha256=sOYW6800BE6U2JnP-mEU3HjubGd-KkiPwZ7jisDT_7Y,671 +openai/types/responses/response_image_gen_call_generating_event.py,sha256=1mjodLwyfkMBzcgQQhTix_EzQFNAWKnL6aycczObXJI,706 +openai/types/responses/response_image_gen_call_in_progress_event.py,sha256=DxvV9tMMGGcu5lTgIuHTL7Kbt3bO40NKg6Qd8kATvkQ,708 +openai/types/responses/response_image_gen_call_partial_image_event.py,sha256=xN3hw_RbEiD9ZoSZCf3TJZcL3JUIWCVzd5cha20s_7I,971 +openai/types/responses/response_in_progress_event.py,sha256=uvYzRXq4v6LuXY8fNyGbzbTt4tySoSskzz_hUFWc-64,518 +openai/types/responses/response_includable.py,sha256=A4cf5h8hd2QheP1IKGrvCThGy0mzyZ73MeiJ-yhTNU4,436 +openai/types/responses/response_incomplete_event.py,sha256=0EP3BJzI2E6VXcpEvaPenBKHGocEZbFjToSMMktUo7U,516 +openai/types/responses/response_input_audio.py,sha256=OUNcmcb1VfKnxNIuDRunZNGp564UHOHUreiWhmQzOUE,574 +openai/types/responses/response_input_audio_param.py,sha256=-B87XBc8ndNEgOkm7U5ZI380fEmkDcAPa9fIzIPb7q4,673 +openai/types/responses/response_input_content.py,sha256=Xh7fU7qlvBR_-RjNSK0Nny8vqAFLAtKxrOJu8IwaPpE,620 +openai/types/responses/response_input_content_param.py,sha256=nnfvXgu3yeQdEMxwRkJQ69sCQvYpQOxqd5TJNx0xlbo,632 +openai/types/responses/response_input_file.py,sha256=Sp8QjnKF3XgUbPXRRpOhJAnlpbyVdAFM8AY-9Xa3JZo,717 +openai/types/responses/response_input_file_param.py,sha256=1v_0w7IsMTeasMI97k5RtWF2XsqJGEgoV7Urzm7_Rio,715 +openai/types/responses/response_input_image.py,sha256=zHA7iFssu0aFcivwzyurAJgGpFdmzxq1BooVp5magsI,778 +openai/types/responses/response_input_image_param.py,sha256=5qhS_nF1GH3buGga8HSz9Ds2gVqQ8OqhfhkvssciIHE,830 +openai/types/responses/response_input_item.py,sha256=o-uhywXY8scND8qVqVGKzd-MKbllzyRsjU5Wug2V6Ps,9101 +openai/types/responses/response_input_item_param.py,sha256=CSzrMeHdhOxx-XOJJyMp_P15JXy7q7dJ0L6lTCsFk5g,9642 +openai/types/responses/response_input_message_content_list.py,sha256=LEaQ_x6dRt3w5Sl7R-Ewu89KlLyGFhMf31OHAHPD3U8,329 +openai/types/responses/response_input_message_content_list_param.py,sha256=cCy7w0Qwk8aiID12bCM6JidTSlPqNsVeDXho3DUX2n4,761 +openai/types/responses/response_input_message_item.py,sha256=_zXthGtO0zstLvIHg9XesNAme6yNa8JOejkBYLwXm70,1029 +openai/types/responses/response_input_param.py,sha256=3t232yWf5z_gK9QejJujbt64JncZGlVJugH90Kl5CEc,9736 +openai/types/responses/response_input_text.py,sha256=L7ikIc1qFUSjB9FLeKiy6uwa2y-TkN1bMMgq7PpGOuE,375 +openai/types/responses/response_input_text_param.py,sha256=N9k0QajI4grRD44GKOz4qG4nrU_au1kVZWmwX3o0koU,441 +openai/types/responses/response_item.py,sha256=TciYLydeQfdkGXqlD_DXd4BG3b5Z1sbT6ydgJ7AIIAc,5918 +openai/types/responses/response_item_list.py,sha256=uGGJlbBtuaNadG9PjebjngvtKdXTcI7MIvF05m7qtjc,665 +openai/types/responses/response_mcp_call_arguments_delta_event.py,sha256=dq4_Z156rwK6F9_97sgEOZJHNNPxt6ZfGHX8b_MSWS8,778 +openai/types/responses/response_mcp_call_arguments_done_event.py,sha256=16ETbPuAreyAapg7rKMLWtSOlu6-mxfrkJUfVKiV9dM,752 +openai/types/responses/response_mcp_call_completed_event.py,sha256=ylzTH1FOI2Ha8PABzWOF_ais1_GgMsBmUklaTkR18bU,600 +openai/types/responses/response_mcp_call_failed_event.py,sha256=BmPnCvz72x-lgUK6x8Svmxo1y4ep0FJWYh5ROgYyuCU,582 +openai/types/responses/response_mcp_call_in_progress_event.py,sha256=Em1Xni2Ah6m7pF4wsvI_7Q0UMIlHsd75uF0r2Z6RI14,638 +openai/types/responses/response_mcp_list_tools_completed_event.py,sha256=3tLqKFzakR7H9_gPdYBzyLlKmIOrjtWuULex2069EY0,637 +openai/types/responses/response_mcp_list_tools_failed_event.py,sha256=NhjpRJ5jTrsc7qhQYL9aKTdL6FT6LClZB03G25WySQM,604 +openai/types/responses/response_mcp_list_tools_in_progress_event.py,sha256=_mfZNKGLIVvEmvmfBie4Q5QMUmzAiSyjdHQdORfcqWY,646 +openai/types/responses/response_output_item.py,sha256=rZk_B9avi1xxzktkaSXqEduSjHz3VHSKIMIPuvMYbUQ,4669 +openai/types/responses/response_output_item_added_event.py,sha256=ct7JDhk7EzyD7oDFVFx1X8T2hblAuDQea3GPXY61Fzw,644 +openai/types/responses/response_output_item_done_event.py,sha256=adnds7wknAbha4-USAUosKuQTMFwA58pZC842VUrJO0,652 +openai/types/responses/response_output_message.py,sha256=FXVWYe6pptTXvCxwadX602dL4xNjl1GKugTOrlFCBuU,1104 +openai/types/responses/response_output_message_param.py,sha256=VfnkR1ClDhUq3uoGsrp-HmmYoDmkY6X3wNcdXC7NHjU,1148 +openai/types/responses/response_output_refusal.py,sha256=oraX9ZXcD4B7w8t9jcbZPACp-8puytJX_1SSQfTAy_M,388 +openai/types/responses/response_output_refusal_param.py,sha256=kCxtRvVJ6PF75Svmd3JUXyV_W-m9VqV-SpjSe6VUt3Y,454 +openai/types/responses/response_output_text.py,sha256=dZwIefV0zZmQJZ-7jfbgQwu6BJRHuFlG3V_AjxNRy3s,2810 +openai/types/responses/response_output_text_annotation_added_event.py,sha256=xGlSoFd2n9hjLeVKCQPh-yBtI2uS-d3ckJBHHmEoXg4,963 +openai/types/responses/response_output_text_param.py,sha256=H9Hq_D5Unp1Y1m4QDblzpcJiZ-5yDuhCtQSvIYSVddY,3113 +openai/types/responses/response_prompt.py,sha256=hIkV3qs1eSvczvxif_w-QSAIRuUjNc-Iukl447udRQ4,936 +openai/types/responses/response_prompt_param.py,sha256=SC4_UYJudF-inMfJ-PBNRGPOO0gNE9IbQ3ZO0loqzVY,1027 +openai/types/responses/response_queued_event.py,sha256=EDgtn58yhHg9784KjOwIK5_qRxZOnRdX25gKNMCt958,508 +openai/types/responses/response_reasoning_item.py,sha256=UOuGhZL0BqW4-HGD5PKCgWqFCNFUXUIobRDbPBNrytQ,1426 +openai/types/responses/response_reasoning_item_param.py,sha256=NuF_7zDG8x2yhyq-7A8u0oIlIzgZ3bZQotCqHZq0upk,1539 +openai/types/responses/response_reasoning_summary_part_added_event.py,sha256=wFecLMHuG4cmznOQvr9lD31qg9ebU8E6T7IVXxTR3EM,1006 +openai/types/responses/response_reasoning_summary_part_done_event.py,sha256=VhU-pOK6fGfCsarOUZ5PD-GTHIvKspOuiWqG709_KMM,997 +openai/types/responses/response_reasoning_summary_text_delta_event.py,sha256=GtOuch2QaTXItNJR9hk0Y9TD5s_INjc22a9-e52KfBM,846 +openai/types/responses/response_reasoning_summary_text_done_event.py,sha256=_fPOh7N6naMEHcRv42nUlb9vKC9lI8BJ0ll20T1ejzg,833 +openai/types/responses/response_reasoning_text_delta_event.py,sha256=Bv6wVhRCIve81iyl8287xssRVbg1SRZA8__GCx3Lrec,841 +openai/types/responses/response_reasoning_text_done_event.py,sha256=4F30ObYxJKBjjoXbz5Vsij4PVWo_5M3FjPlMTT8Q29Q,788 +openai/types/responses/response_refusal_delta_event.py,sha256=ss7m9NX5doTFE6g79k3iBK_z5gXstGFeM2Z2gcO-cPo,770 +openai/types/responses/response_refusal_done_event.py,sha256=0iI5jIbuDuHAPnzSK0zWVf8RdjiXTt1HoYEVy4ngIKI,775 +openai/types/responses/response_retrieve_params.py,sha256=Y_4UacCQ7xUYXc7_QTCJt-zLzIuv-PWocNQ1k0RnPsw,2372 +openai/types/responses/response_status.py,sha256=289NTnFcyk0195A2E15KDILXNLpHbfo6q4tcvezYWgs,278 +openai/types/responses/response_stream_event.py,sha256=uPEbNTxXOaiEFRVt_PbdeecyfS9rgjaYU7m15NIvSbo,6916 +openai/types/responses/response_text_config.py,sha256=dM28UJfEjLSKBcRHNmBQJjkZSVdZ-vDFccPTVmXYs00,1352 +openai/types/responses/response_text_config_param.py,sha256=348GrnnGUF8fGEfRSW-Vw1wFoqTqQw7FfcgIvc1usCg,1381 +openai/types/responses/response_text_delta_event.py,sha256=e96nx3l-1Q3r9jCGyGgiH-siauP5Ka4LJ8THgUrkEXk,1374 +openai/types/responses/response_text_done_event.py,sha256=PDENYq1-kdZD19eps5qY3-Ih96obk75iUSVO-XUmkig,1380 +openai/types/responses/response_usage.py,sha256=DFA8WjqKGl7iGCmZl2G18y48xT82UTZ_NCKm0MAuRDY,945 +openai/types/responses/response_web_search_call_completed_event.py,sha256=gWv2xgDeGbvN0oqm96uuecGBy1SkbF_yNA56h5hMlOE,698 +openai/types/responses/response_web_search_call_in_progress_event.py,sha256=XxOSK7EI1d0WDkfG5jgU_LIXz72CGixqp4uYW88-dY8,704 +openai/types/responses/response_web_search_call_searching_event.py,sha256=sYr9K30DjDeD_h5Jj41OwoTrvUkF--dCQGnQuEnggcw,698 +openai/types/responses/tool.py,sha256=9GnnyntzEL4bozEsEXhK41QobtcvMDJYCT-aw0Ipxns,8439 +openai/types/responses/tool_choice_allowed.py,sha256=I0bB6Gq7aIswr3mWH3TN6aOgtun01Kaopa72AhZJG9I,1023 +openai/types/responses/tool_choice_allowed_param.py,sha256=PMokbtPLR48_b_ZNe0AMyZx-C-OrcwPsbeX31DpoIwE,1107 +openai/types/responses/tool_choice_custom.py,sha256=xi7cPj8VJn4qYXXSkZwFoV_WdYbyGwEVTDIcdHL9AQo,382 +openai/types/responses/tool_choice_custom_param.py,sha256=0ZHVrSkRkVFuCC27k6TQKy2hBoCDt6NB2f8fVnLNrXM,448 +openai/types/responses/tool_choice_function.py,sha256=X51PqYW8HMrJcxSkaTCF-uDG_KetD_6WqU1TgmCPR-k,384 +openai/types/responses/tool_choice_function_param.py,sha256=UzIJgiqJV7fj0nRDWyzwxpwJmZd0czZVciq4ffvfl_4,450 +openai/types/responses/tool_choice_mcp.py,sha256=iq6CwniC-hOQ9TmH4D4Wo6hT5V0J_4XbZ1TTtf0xEf8,481 +openai/types/responses/tool_choice_mcp_param.py,sha256=E4VcW1YhjYJgYaSw74NuluyM9WylELUZIs7-s4u-N1A,540 +openai/types/responses/tool_choice_options.py,sha256=gJHrNT72mRECrN7hQKRHAOA-OS0JJo51YnXvUcMfqMQ,237 +openai/types/responses/tool_choice_types.py,sha256=-3FM-g4h0122Aq2CxEqiNt2A4hjYWPrJJ9MKh_hEROs,740 +openai/types/responses/tool_choice_types_param.py,sha256=_EqjVdOTy8bjKho3ZGdwYAgc11PaXp804jkBvj9dCz4,838 +openai/types/responses/tool_param.py,sha256=dwTDq9TJVxlLbnYHKq2NV4Cg8aSlVGw2qMD4yZyxNps,8393 +openai/types/responses/web_search_preview_tool.py,sha256=jIoIdmR4tzsIjT2a_5II0tHCnJsea4HTirBR2u00hFk,1469 +openai/types/responses/web_search_preview_tool_param.py,sha256=W64kS2h1cm2lY9ODnp_YoLojRyjei9SZq2UU7X2AJ48,1496 +openai/types/responses/web_search_tool.py,sha256=WuPSLv-W8j8LQvUyHA7S6gGtJrQmGP_t0QCrbh6qPYI,1821 +openai/types/responses/web_search_tool_param.py,sha256=6iMdaKKYaO7bTUzSfmfw3owAjiQGh55qgjr8E1geCPc,1862 +openai/types/shared/__init__.py,sha256=EVk-X1P3R7YWmlYmrbpMrjAeZEfVfudF-Tw7fbOC90o,1267 +openai/types/shared/__pycache__/__init__.cpython-313.pyc,, +openai/types/shared/__pycache__/all_models.cpython-313.pyc,, +openai/types/shared/__pycache__/chat_model.cpython-313.pyc,, +openai/types/shared/__pycache__/comparison_filter.cpython-313.pyc,, +openai/types/shared/__pycache__/compound_filter.cpython-313.pyc,, +openai/types/shared/__pycache__/custom_tool_input_format.cpython-313.pyc,, +openai/types/shared/__pycache__/error_object.cpython-313.pyc,, +openai/types/shared/__pycache__/function_definition.cpython-313.pyc,, +openai/types/shared/__pycache__/function_parameters.cpython-313.pyc,, +openai/types/shared/__pycache__/metadata.cpython-313.pyc,, +openai/types/shared/__pycache__/reasoning.cpython-313.pyc,, +openai/types/shared/__pycache__/reasoning_effort.cpython-313.pyc,, +openai/types/shared/__pycache__/response_format_json_object.cpython-313.pyc,, +openai/types/shared/__pycache__/response_format_json_schema.cpython-313.pyc,, +openai/types/shared/__pycache__/response_format_text.cpython-313.pyc,, +openai/types/shared/__pycache__/response_format_text_grammar.cpython-313.pyc,, +openai/types/shared/__pycache__/response_format_text_python.cpython-313.pyc,, +openai/types/shared/__pycache__/responses_model.cpython-313.pyc,, +openai/types/shared/all_models.py,sha256=CmrA5mmrt16Bi15rvPf1-5BMIXoQu4al5Jnx49VFdUc,634 +openai/types/shared/chat_model.py,sha256=6VpDw8bZPrezzjN8UfBwKpIWokakgU-12rdLzQulLHo,1731 +openai/types/shared/comparison_filter.py,sha256=Y77SD30trdlW0E8BUIMHrugp2N_4I78JJabD2Px6edU,766 +openai/types/shared/compound_filter.py,sha256=QhKPeKKdtWvMDDO85YLKUGgdxBQfrYiFimjadAM31Bs,581 +openai/types/shared/custom_tool_input_format.py,sha256=cO7pX1O0k8J6FgERYUqNjafjjYiwS7GCmIw3E_xSiVQ,773 +openai/types/shared/error_object.py,sha256=G7SGPZ9Qw3gewTKbi3fK69eM6L2Ur0C2D57N8iEapJA,305 +openai/types/shared/function_definition.py,sha256=2F07J5Q7r2Iwg74dC5rarhwWTnt579Y5LUrNc8OdqSc,1475 +openai/types/shared/function_parameters.py,sha256=Dkc_pm98zCKyouQmYrl934cK8ZWX7heY_IIyunW8x7c,236 +openai/types/shared/metadata.py,sha256=DC0SFof2EeVvFK0EsmQH8W5b_HnpI_bdp47s51E5LKw,213 +openai/types/shared/reasoning.py,sha256=FvPkybiYMTz2wqeTAAm0f1nWqUlvTXT1IEnCXzwU95Q,1241 +openai/types/shared/reasoning_effort.py,sha256=oK9lKsN8e2SZ8jV49MZ7PBxbnCP1MxGUQDLYMxlGQYE,279 +openai/types/shared/response_format_json_object.py,sha256=E1KGMUZnaj8fLnQXQC8_m9rMp8F6vIqeR9T1RmFNvE4,352 +openai/types/shared/response_format_json_schema.py,sha256=SsiLtgrudK4Dvxi2Kx0qUFiBQt26y5uGw_33te7L0Gg,1568 +openai/types/shared/response_format_text.py,sha256=p_JASD-xQ4ZveWnAtSoB8a19kVYc9vOZeg6WRMYHKDE,326 +openai/types/shared/response_format_text_grammar.py,sha256=PvmYxTEH_2r2nJsacTs6_Yw88ED1VbBuQJy_jZVbZwo,418 +openai/types/shared/response_format_text_python.py,sha256=Rfkd4jhzndD0Nw5H6LLnR4Y3MySyTz331MwoxcBL-Ek,342 +openai/types/shared/responses_model.py,sha256=vQzcFkclfiWLjCtRpuTL6Ob7p-XrH19WOekpTYsOU6U,644 +openai/types/shared_params/__init__.py,sha256=Jtx94DUXqIaXTb7Sgsx3MPoB9nViBlYEy0DlQ3VcOJU,976 +openai/types/shared_params/__pycache__/__init__.cpython-313.pyc,, +openai/types/shared_params/__pycache__/chat_model.cpython-313.pyc,, +openai/types/shared_params/__pycache__/comparison_filter.cpython-313.pyc,, +openai/types/shared_params/__pycache__/compound_filter.cpython-313.pyc,, +openai/types/shared_params/__pycache__/custom_tool_input_format.cpython-313.pyc,, +openai/types/shared_params/__pycache__/function_definition.cpython-313.pyc,, +openai/types/shared_params/__pycache__/function_parameters.cpython-313.pyc,, +openai/types/shared_params/__pycache__/metadata.cpython-313.pyc,, +openai/types/shared_params/__pycache__/reasoning.cpython-313.pyc,, +openai/types/shared_params/__pycache__/reasoning_effort.cpython-313.pyc,, +openai/types/shared_params/__pycache__/response_format_json_object.cpython-313.pyc,, +openai/types/shared_params/__pycache__/response_format_json_schema.cpython-313.pyc,, +openai/types/shared_params/__pycache__/response_format_text.cpython-313.pyc,, +openai/types/shared_params/__pycache__/responses_model.cpython-313.pyc,, +openai/types/shared_params/chat_model.py,sha256=S0JO3lMtaZ7CG8ZvjYcRls-CF5qLL7AUUDuj1peeKDE,1767 +openai/types/shared_params/comparison_filter.py,sha256=ayLPPfnlufcZnpgmWXZ-iuwpacUk5L7_hITuDyegFiQ,832 +openai/types/shared_params/compound_filter.py,sha256=dJrqaoOVY8QBEZPCjjD3hhf4qwcJLJ26jgK4N85bEFc,646 +openai/types/shared_params/custom_tool_input_format.py,sha256=ifDywFgUir2J2CPm1vyNcGnwl6nJFQsMFF1-qOvAdJA,769 +openai/types/shared_params/function_definition.py,sha256=6JjuRmXIofTv76GCC4XFssqgZw-iKbBazjWqKerfq6Q,1510 +openai/types/shared_params/function_parameters.py,sha256=UvxKz_3b9b5ECwWr8RFrIH511htbU2JZsp9Z9BMkF-o,272 +openai/types/shared_params/metadata.py,sha256=YCb9eFyy17EuLwtVHjUBUjW2FU8SbWp4NV-aEr_it54,249 +openai/types/shared_params/reasoning.py,sha256=iHGUp7rPlMczbNWCJe4Jaz0IMBpRBGaxUfU8qkbbZoA,1255 +openai/types/shared_params/reasoning_effort.py,sha256=d_oflloFU0aeSyJrEZKwpwi0kZNUsg8rEZ4XUU-5eoE,315 +openai/types/shared_params/response_format_json_object.py,sha256=aEdVMoEkiEVE_YX6pfj5VqRVqfRIPju5hU-lqNubhVE,398 +openai/types/shared_params/response_format_json_schema.py,sha256=iCr7oU2jaHmVAi60mG90uksfv1QQjtvrVT9Vd3paE0k,1529 +openai/types/shared_params/response_format_text.py,sha256=N3-JNmbAjreYMj8KBkYb5kZhbblR9ds_6vwYLzUAWDA,372 +openai/types/shared_params/responses_model.py,sha256=Fk-OQdxCsO7q5OmdvoBuI3tl_KKM8rl356LgYLirbOU,688 +openai/types/static_file_chunking_strategy.py,sha256=JmAzT2-9eaG9ZTH8X0jS1IVCOE3Jgi1PzE11oMST3Fc,595 +openai/types/static_file_chunking_strategy_object.py,sha256=MTwQ1olGZHoC26xxCKw0U0RvWORIJLgWzNWRQ1V0KmA,424 +openai/types/static_file_chunking_strategy_object_param.py,sha256=OwAOs1PT2ygBm4RpzHVVsr-93-Uqjg_IcCoNhtEPT7I,508 +openai/types/static_file_chunking_strategy_param.py,sha256=kCMmgyOxO0XIF2wjCWjUXtyn9S6q_7mNmyUCauqrjsg,692 +openai/types/upload.py,sha256=lFrEOsbVJwQ6jzzhn307AvBVjyF85lYHdig5ZvQQypE,1207 +openai/types/upload_complete_params.py,sha256=PW5mCxJt7eg7F5sttX5LCE43m9FX8oZs3P5i9HvjRoU,527 +openai/types/upload_create_params.py,sha256=n9BNQ7GasHGCQf7poS5NKSEQM8eUCzb6rRBVFqylmlw,1507 +openai/types/uploads/__init__.py,sha256=fDsmd3L0nIWbFldbViOLvcQavsFA4SL3jsXDfAueAck,242 +openai/types/uploads/__pycache__/__init__.cpython-313.pyc,, +openai/types/uploads/__pycache__/part_create_params.cpython-313.pyc,, +openai/types/uploads/__pycache__/upload_part.cpython-313.pyc,, +openai/types/uploads/part_create_params.py,sha256=pBByUzngaj70ov1knoSo_gpeBjaWP9D5EdiHwiG4G7U,362 +openai/types/uploads/upload_part.py,sha256=U9953cr9lJJLWEfhTiwHphRzLKARq3gWAWqrjxbhTR4,590 +openai/types/vector_store.py,sha256=hS30tSgL_s1BC04nIHfZL95-uD60t5Oe44JUQnVD8T8,2470 +openai/types/vector_store_create_params.py,sha256=mmOkVJk2qH2SeUos0p1keKCFYp7xUTWe00ielN0LCpE,1764 +openai/types/vector_store_deleted.py,sha256=BbtnlZ0Z5f4ncDyHLKrEfmY6Uuc0xOg3WBxvMoR8Wxk,307 +openai/types/vector_store_list_params.py,sha256=KeSeQaEdqO2EiPEVtq1Nun-uRRdkfwW0P8aHeCmL5zA,1226 +openai/types/vector_store_search_params.py,sha256=EnYfNFP4dgovZeLLPeGofA3TCJatJDYt4aoppMOto9g,1262 +openai/types/vector_store_search_response.py,sha256=qlhdAjqLPZg_JQmsqQCzAgT2Pxc2C-vGZmh64kR8y-M,1156 +openai/types/vector_store_update_params.py,sha256=RJm0qkqLOsHjhPIiOWPNwkrEIqHjDukyZT52mle4gWc,1240 +openai/types/vector_stores/__init__.py,sha256=F_DyW6EqxOJTBPKE5LUSzgTibcZM6axMo-irysr52ro,818 +openai/types/vector_stores/__pycache__/__init__.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_batch_create_params.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_batch_list_files_params.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_content_response.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_create_params.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_list_params.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/file_update_params.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/vector_store_file.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/vector_store_file_batch.cpython-313.pyc,, +openai/types/vector_stores/__pycache__/vector_store_file_deleted.cpython-313.pyc,, +openai/types/vector_stores/file_batch_create_params.py,sha256=f931A3sW8V30WGXQYCU561EqG3XRxShgE_hSpu-hFrM,1302 +openai/types/vector_stores/file_batch_list_files_params.py,sha256=FPpQvCQI2skyLB8YCuwdCj7RbO9ba1UjaHAtvrWxAbs,1451 +openai/types/vector_stores/file_content_response.py,sha256=uAFvFDE_NVRzg0xm1fLJ2zEd62qzq8rPYko7xpDjbaU,367 +openai/types/vector_stores/file_create_params.py,sha256=nTHWG0OMqqLRjWFH2qbif89fpCJQCzGGdXDjCqPbq1Y,1229 +openai/types/vector_stores/file_list_params.py,sha256=AIzmNH1oFuy-qlpRhj9eXu9yyTA-2z_IppLYFclMtZw,1385 +openai/types/vector_stores/file_update_params.py,sha256=NGah01luDW_W3psfsYa3ShlswH8pAhC_EebLMvd925I,781 +openai/types/vector_stores/vector_store_file.py,sha256=mfmXBL4EqHuaoamRnZ2TS1oX3k1okTREU2vLOrbVglw,2247 +openai/types/vector_stores/vector_store_file_batch.py,sha256=MnRehH5Mc0VOhSCZtniMDz8eH72syy2RScmECR_BEhE,1456 +openai/types/vector_stores/vector_store_file_deleted.py,sha256=sOds3FSmDBFhe25zoSAz2vHsmG2bo4s2PASgB_M6UU0,321 +openai/types/webhooks/__init__.py,sha256=T8XC8KrJNXiNUPevxpO4PJi__C-HZgd0TMg7D2bRPh4,1828 +openai/types/webhooks/__pycache__/__init__.cpython-313.pyc,, +openai/types/webhooks/__pycache__/batch_cancelled_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/batch_completed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/batch_expired_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/batch_failed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/eval_run_canceled_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/eval_run_failed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/eval_run_succeeded_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/fine_tuning_job_cancelled_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/fine_tuning_job_failed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/fine_tuning_job_succeeded_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/realtime_call_incoming_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/response_cancelled_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/response_completed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/response_failed_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/response_incomplete_webhook_event.cpython-313.pyc,, +openai/types/webhooks/__pycache__/unwrap_webhook_event.cpython-313.pyc,, +openai/types/webhooks/batch_cancelled_webhook_event.py,sha256=9eadXH42hNN8ZEnkvT1xP4-tXJSSU1EnFo0407UphUU,770 +openai/types/webhooks/batch_completed_webhook_event.py,sha256=HTcSImBaYwlnm8wQdvjPaWzyFIS-KBSSA_E2WkQ1uqg,770 +openai/types/webhooks/batch_expired_webhook_event.py,sha256=fbrvrZrbQZNf_aPBm08HSD99NFaAHVjv4nQg3pNmh9w,756 +openai/types/webhooks/batch_failed_webhook_event.py,sha256=WRxFObJMtp7zPJTl_pa4ppVhKSxHwNMvQdqyR0CqdV8,751 +openai/types/webhooks/eval_run_canceled_webhook_event.py,sha256=hLoN9c6C5QDPJEOLpOInSiGRgqsrtZmwE3NIOjiowtM,757 +openai/types/webhooks/eval_run_failed_webhook_event.py,sha256=rMoiy66aVGgyA2Fxu3ypg1Q1moIj0yDyMsL4ZVJAe6s,743 +openai/types/webhooks/eval_run_succeeded_webhook_event.py,sha256=GFRFtx7JxtUGeWEoQRpbeE3oPoOhPhW1BskJOxuaFI8,758 +openai/types/webhooks/fine_tuning_job_cancelled_webhook_event.py,sha256=kFx4imcbFxTD4L4G6h6kSINfX7yLpo4GQDAuYBGd9wM,802 +openai/types/webhooks/fine_tuning_job_failed_webhook_event.py,sha256=YjfTRr2mvpiJB4IZkzcFNNLwnhrUKVKkLP7RpPgHTnA,783 +openai/types/webhooks/fine_tuning_job_succeeded_webhook_event.py,sha256=wxUg8-llqFJ6K--LI3JHXgTJ1IY2vCD7rO1eq8RWoYo,798 +openai/types/webhooks/realtime_call_incoming_webhook_event.py,sha256=E7mD7ZO6_1v_SAn60-8pDzR5q2WRM0cFygkJ1I-pUpo,1019 +openai/types/webhooks/response_cancelled_webhook_event.py,sha256=60u91Tcsy_qNaPDqQM_tqWQHXVoSB0-rodF3Llkzzmk,776 +openai/types/webhooks/response_completed_webhook_event.py,sha256=OGSfVNA6Vgugplf4LxXhSkk-ScVvElekoQeksT93z_Q,776 +openai/types/webhooks/response_failed_webhook_event.py,sha256=SWMK_kc1o8WKeQPZudQx7VwU25oAHf_yLR6fKdXKd2E,757 +openai/types/webhooks/response_incomplete_webhook_event.py,sha256=O0LrpnzzxClQf0vQOwF6s_5EAUxM4TdTfEd8uc84iLs,782 +openai/types/webhooks/unwrap_webhook_event.py,sha256=KrfVL0-NsOuWHtRGiJfGMYwI8blUr09vUqUVJdZNpDQ,2039 +openai/types/websocket_connection_options.py,sha256=4cAWpv1KKp_9pvnez7pGYzO3s8zh1WvX2xpBhpe-96k,1840 +openai/version.py,sha256=cjbXKO8Ut3aiv4YlQnugff7AdC48MpSndcx96q88Yb8,62 diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/WHEEL b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/WHEEL new file mode 100644 index 0000000000000000000000000000000000000000..21aaa72961a8af71c17d2cb3b76d5f7f567100e4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/WHEEL @@ -0,0 +1,4 @@ +Wheel-Version: 1.0 +Generator: hatchling 1.26.3 +Root-Is-Purelib: true +Tag: py3-none-any diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/entry_points.txt b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/entry_points.txt new file mode 100644 index 0000000000000000000000000000000000000000..989993968b142c5540dedfd048fef222a6c29b15 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/entry_points.txt @@ -0,0 +1,2 @@ +[console_scripts] +openai = openai.cli:main diff --git a/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/licenses/LICENSE b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/licenses/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..f011417af6f72ab5e00e7f48931028fa202ca7cb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai-1.109.1.dist-info/licenses/LICENSE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright 2025 OpenAI + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. diff --git a/.venv/lib/python3.13/site-packages/openai/types/conversations/text_content.py b/.venv/lib/python3.13/site-packages/openai/types/conversations/text_content.py new file mode 100644 index 0000000000000000000000000000000000000000..f1ae079597c2fd3763697535f3a620628984deb6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/conversations/text_content.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["TextContent"] + + +class TextContent(BaseModel): + text: str + + type: Literal["text"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/create_embedding_response.py b/.venv/lib/python3.13/site-packages/openai/types/create_embedding_response.py new file mode 100644 index 0000000000000000000000000000000000000000..eff247a11279ce4c6c0d2af36665fddbdafc9411 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/create_embedding_response.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List +from typing_extensions import Literal + +from .._models import BaseModel +from .embedding import Embedding + +__all__ = ["CreateEmbeddingResponse", "Usage"] + + +class Usage(BaseModel): + prompt_tokens: int + """The number of tokens used by the prompt.""" + + total_tokens: int + """The total number of tokens used by the request.""" + + +class CreateEmbeddingResponse(BaseModel): + data: List[Embedding] + """The list of embeddings generated by the model.""" + + model: str + """The name of the model used to generate the embedding.""" + + object: Literal["list"] + """The object type, which is always "list".""" + + usage: Usage + """The usage information for the request.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/embedding.py b/.venv/lib/python3.13/site-packages/openai/types/embedding.py new file mode 100644 index 0000000000000000000000000000000000000000..769b1d165faf65308a87c2c0aba33e96e898825d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/embedding.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["Embedding"] + + +class Embedding(BaseModel): + embedding: List[float] + """The embedding vector, which is a list of floats. + + The length of vector depends on the model as listed in the + [embedding guide](https://platform.openai.com/docs/guides/embeddings). + """ + + index: int + """The index of the embedding in the list of embeddings.""" + + object: Literal["embedding"] + """The object type, which is always "embedding".""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/embedding_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/embedding_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..ab3e8779642727135e767773749bc691cc1d250a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/embedding_create_params.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypedDict + +from .._types import SequenceNotStr +from .embedding_model import EmbeddingModel + +__all__ = ["EmbeddingCreateParams"] + + +class EmbeddingCreateParams(TypedDict, total=False): + input: Required[Union[str, SequenceNotStr[str], Iterable[int], Iterable[Iterable[int]]]] + """Input text to embed, encoded as a string or array of tokens. + + To embed multiple inputs in a single request, pass an array of strings or array + of token arrays. The input must not exceed the max input tokens for the model + (8192 tokens for all embedding models), cannot be an empty string, and any array + must be 2048 dimensions or less. + [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) + for counting tokens. In addition to the per-input token limit, all embedding + models enforce a maximum of 300,000 tokens summed across all inputs in a single + request. + """ + + model: Required[Union[str, EmbeddingModel]] + """ID of the model to use. + + You can use the + [List models](https://platform.openai.com/docs/api-reference/models/list) API to + see all of your available models, or see our + [Model overview](https://platform.openai.com/docs/models) for descriptions of + them. + """ + + dimensions: int + """The number of dimensions the resulting output embeddings should have. + + Only supported in `text-embedding-3` and later models. + """ + + encoding_format: Literal["float", "base64"] + """The format to return the embeddings in. + + Can be either `float` or [`base64`](https://pypi.org/project/pybase64/). + """ + + user: str + """ + A unique identifier representing your end-user, which can help OpenAI to monitor + and detect abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/embedding_model.py b/.venv/lib/python3.13/site-packages/openai/types/embedding_model.py new file mode 100644 index 0000000000000000000000000000000000000000..075ff9764412316c537626ff2c24651793dc7fa2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/embedding_model.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["EmbeddingModel"] + +EmbeddingModel: TypeAlias = Literal["text-embedding-ada-002", "text-embedding-3-small", "text-embedding-3-large"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/eval_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..eb7f86cd921a1824c082b044e2845a718d3f230b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_create_params.py @@ -0,0 +1,202 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .._types import SequenceNotStr +from .shared_params.metadata import Metadata +from .graders.python_grader_param import PythonGraderParam +from .graders.score_model_grader_param import ScoreModelGraderParam +from .graders.string_check_grader_param import StringCheckGraderParam +from .responses.response_input_text_param import ResponseInputTextParam +from .graders.text_similarity_grader_param import TextSimilarityGraderParam +from .responses.response_input_audio_param import ResponseInputAudioParam + +__all__ = [ + "EvalCreateParams", + "DataSourceConfig", + "DataSourceConfigCustom", + "DataSourceConfigLogs", + "DataSourceConfigStoredCompletions", + "TestingCriterion", + "TestingCriterionLabelModel", + "TestingCriterionLabelModelInput", + "TestingCriterionLabelModelInputSimpleInputMessage", + "TestingCriterionLabelModelInputEvalItem", + "TestingCriterionLabelModelInputEvalItemContent", + "TestingCriterionLabelModelInputEvalItemContentOutputText", + "TestingCriterionLabelModelInputEvalItemContentInputImage", + "TestingCriterionTextSimilarity", + "TestingCriterionPython", + "TestingCriterionScoreModel", +] + + +class EvalCreateParams(TypedDict, total=False): + data_source_config: Required[DataSourceConfig] + """The configuration for the data source used for the evaluation runs. + + Dictates the schema of the data used in the evaluation. + """ + + testing_criteria: Required[Iterable[TestingCriterion]] + """A list of graders for all eval runs in this group. + + Graders can reference variables in the data source using double curly braces + notation, like `{{item.variable_name}}`. To reference the model's output, use + the `sample` namespace (ie, `{{sample.output_text}}`). + """ + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the evaluation.""" + + +class DataSourceConfigCustom(TypedDict, total=False): + item_schema: Required[Dict[str, object]] + """The json schema for each row in the data source.""" + + type: Required[Literal["custom"]] + """The type of data source. Always `custom`.""" + + include_sample_schema: bool + """ + Whether the eval should expect you to populate the sample namespace (ie, by + generating responses off of your data source) + """ + + +class DataSourceConfigLogs(TypedDict, total=False): + type: Required[Literal["logs"]] + """The type of data source. Always `logs`.""" + + metadata: Dict[str, object] + """Metadata filters for the logs data source.""" + + +class DataSourceConfigStoredCompletions(TypedDict, total=False): + type: Required[Literal["stored_completions"]] + """The type of data source. Always `stored_completions`.""" + + metadata: Dict[str, object] + """Metadata filters for the stored completions data source.""" + + +DataSourceConfig: TypeAlias = Union[DataSourceConfigCustom, DataSourceConfigLogs, DataSourceConfigStoredCompletions] + + +class TestingCriterionLabelModelInputSimpleInputMessage(TypedDict, total=False): + content: Required[str] + """The content of the message.""" + + role: Required[str] + """The role of the message (e.g. "system", "assistant", "user").""" + + +class TestingCriterionLabelModelInputEvalItemContentOutputText(TypedDict, total=False): + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + +class TestingCriterionLabelModelInputEvalItemContentInputImage(TypedDict, total=False): + image_url: Required[str] + """The URL of the image input.""" + + type: Required[Literal["input_image"]] + """The type of the image input. Always `input_image`.""" + + detail: str + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +TestingCriterionLabelModelInputEvalItemContent: TypeAlias = Union[ + str, + ResponseInputTextParam, + TestingCriterionLabelModelInputEvalItemContentOutputText, + TestingCriterionLabelModelInputEvalItemContentInputImage, + ResponseInputAudioParam, + Iterable[object], +] + + +class TestingCriterionLabelModelInputEvalItem(TypedDict, total=False): + content: Required[TestingCriterionLabelModelInputEvalItemContent] + """Inputs to the model - can contain template strings.""" + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" + + +TestingCriterionLabelModelInput: TypeAlias = Union[ + TestingCriterionLabelModelInputSimpleInputMessage, TestingCriterionLabelModelInputEvalItem +] + + +class TestingCriterionLabelModel(TypedDict, total=False): + input: Required[Iterable[TestingCriterionLabelModelInput]] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + labels: Required[SequenceNotStr[str]] + """The labels to classify to each item in the evaluation.""" + + model: Required[str] + """The model to use for the evaluation. Must support structured outputs.""" + + name: Required[str] + """The name of the grader.""" + + passing_labels: Required[SequenceNotStr[str]] + """The labels that indicate a passing result. Must be a subset of labels.""" + + type: Required[Literal["label_model"]] + """The object type, which is always `label_model`.""" + + +class TestingCriterionTextSimilarity(TextSimilarityGraderParam, total=False): + pass_threshold: Required[float] + """The threshold for the score.""" + + +class TestingCriterionPython(PythonGraderParam, total=False): + pass_threshold: float + """The threshold for the score.""" + + +class TestingCriterionScoreModel(ScoreModelGraderParam, total=False): + pass_threshold: float + """The threshold for the score.""" + + +TestingCriterion: TypeAlias = Union[ + TestingCriterionLabelModel, + StringCheckGraderParam, + TestingCriterionTextSimilarity, + TestingCriterionPython, + TestingCriterionScoreModel, +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/eval_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..20b0e3127f28041d2e1805ced1d095266502d706 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_create_response.py @@ -0,0 +1,111 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from .._utils import PropertyInfo +from .._models import BaseModel +from .shared.metadata import Metadata +from .graders.python_grader import PythonGrader +from .graders.label_model_grader import LabelModelGrader +from .graders.score_model_grader import ScoreModelGrader +from .graders.string_check_grader import StringCheckGrader +from .eval_custom_data_source_config import EvalCustomDataSourceConfig +from .graders.text_similarity_grader import TextSimilarityGrader +from .eval_stored_completions_data_source_config import EvalStoredCompletionsDataSourceConfig + +__all__ = [ + "EvalCreateResponse", + "DataSourceConfig", + "DataSourceConfigLogs", + "TestingCriterion", + "TestingCriterionEvalGraderTextSimilarity", + "TestingCriterionEvalGraderPython", + "TestingCriterionEvalGraderScoreModel", +] + + +class DataSourceConfigLogs(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["logs"] + """The type of data source. Always `logs`.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + +DataSourceConfig: TypeAlias = Annotated[ + Union[EvalCustomDataSourceConfig, DataSourceConfigLogs, EvalStoredCompletionsDataSourceConfig], + PropertyInfo(discriminator="type"), +] + + +class TestingCriterionEvalGraderTextSimilarity(TextSimilarityGrader): + __test__ = False + pass_threshold: float + """The threshold for the score.""" + + +class TestingCriterionEvalGraderPython(PythonGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +class TestingCriterionEvalGraderScoreModel(ScoreModelGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +TestingCriterion: TypeAlias = Union[ + LabelModelGrader, + StringCheckGrader, + TestingCriterionEvalGraderTextSimilarity, + TestingCriterionEvalGraderPython, + TestingCriterionEvalGraderScoreModel, +] + + +class EvalCreateResponse(BaseModel): + id: str + """Unique identifier for the evaluation.""" + + created_at: int + """The Unix timestamp (in seconds) for when the eval was created.""" + + data_source_config: DataSourceConfig + """Configuration of data sources used in runs of the evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the evaluation.""" + + object: Literal["eval"] + """The object type.""" + + testing_criteria: List[TestingCriterion] + """A list of testing criteria.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_custom_data_source_config.py b/.venv/lib/python3.13/site-packages/openai/types/eval_custom_data_source_config.py new file mode 100644 index 0000000000000000000000000000000000000000..d99701cc7176bfb5e0cba7fab05bbf6c5ca246d2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_custom_data_source_config.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from .._models import BaseModel + +__all__ = ["EvalCustomDataSourceConfig"] + + +class EvalCustomDataSourceConfig(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["custom"] + """The type of data source. Always `custom`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_delete_response.py b/.venv/lib/python3.13/site-packages/openai/types/eval_delete_response.py new file mode 100644 index 0000000000000000000000000000000000000000..a27261e242b4544d06af84f85ed5bc4f1be33622 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_delete_response.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .._models import BaseModel + +__all__ = ["EvalDeleteResponse"] + + +class EvalDeleteResponse(BaseModel): + deleted: bool + + eval_id: str + + object: str diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/eval_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..d9a12d0ddf81ad73f8b6b2ef5532908b9ee703f7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_list_params.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["EvalListParams"] + + +class EvalListParams(TypedDict, total=False): + after: str + """Identifier for the last eval from the previous pagination request.""" + + limit: int + """Number of evals to retrieve.""" + + order: Literal["asc", "desc"] + """Sort order for evals by timestamp. + + Use `asc` for ascending order or `desc` for descending order. + """ + + order_by: Literal["created_at", "updated_at"] + """Evals can be ordered by creation time or last updated time. + + Use `created_at` for creation time or `updated_at` for last updated time. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_list_response.py b/.venv/lib/python3.13/site-packages/openai/types/eval_list_response.py new file mode 100644 index 0000000000000000000000000000000000000000..5ac4997cf69df492a9e289fccd82f4435469fcd6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_list_response.py @@ -0,0 +1,111 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from .._utils import PropertyInfo +from .._models import BaseModel +from .shared.metadata import Metadata +from .graders.python_grader import PythonGrader +from .graders.label_model_grader import LabelModelGrader +from .graders.score_model_grader import ScoreModelGrader +from .graders.string_check_grader import StringCheckGrader +from .eval_custom_data_source_config import EvalCustomDataSourceConfig +from .graders.text_similarity_grader import TextSimilarityGrader +from .eval_stored_completions_data_source_config import EvalStoredCompletionsDataSourceConfig + +__all__ = [ + "EvalListResponse", + "DataSourceConfig", + "DataSourceConfigLogs", + "TestingCriterion", + "TestingCriterionEvalGraderTextSimilarity", + "TestingCriterionEvalGraderPython", + "TestingCriterionEvalGraderScoreModel", +] + + +class DataSourceConfigLogs(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["logs"] + """The type of data source. Always `logs`.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + +DataSourceConfig: TypeAlias = Annotated[ + Union[EvalCustomDataSourceConfig, DataSourceConfigLogs, EvalStoredCompletionsDataSourceConfig], + PropertyInfo(discriminator="type"), +] + + +class TestingCriterionEvalGraderTextSimilarity(TextSimilarityGrader): + __test__ = False + pass_threshold: float + """The threshold for the score.""" + + +class TestingCriterionEvalGraderPython(PythonGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +class TestingCriterionEvalGraderScoreModel(ScoreModelGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +TestingCriterion: TypeAlias = Union[ + LabelModelGrader, + StringCheckGrader, + TestingCriterionEvalGraderTextSimilarity, + TestingCriterionEvalGraderPython, + TestingCriterionEvalGraderScoreModel, +] + + +class EvalListResponse(BaseModel): + id: str + """Unique identifier for the evaluation.""" + + created_at: int + """The Unix timestamp (in seconds) for when the eval was created.""" + + data_source_config: DataSourceConfig + """Configuration of data sources used in runs of the evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the evaluation.""" + + object: Literal["eval"] + """The object type.""" + + testing_criteria: List[TestingCriterion] + """A list of testing criteria.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_retrieve_response.py b/.venv/lib/python3.13/site-packages/openai/types/eval_retrieve_response.py new file mode 100644 index 0000000000000000000000000000000000000000..758f9cc040d4468651d76bf4037855d970447814 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_retrieve_response.py @@ -0,0 +1,111 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from .._utils import PropertyInfo +from .._models import BaseModel +from .shared.metadata import Metadata +from .graders.python_grader import PythonGrader +from .graders.label_model_grader import LabelModelGrader +from .graders.score_model_grader import ScoreModelGrader +from .graders.string_check_grader import StringCheckGrader +from .eval_custom_data_source_config import EvalCustomDataSourceConfig +from .graders.text_similarity_grader import TextSimilarityGrader +from .eval_stored_completions_data_source_config import EvalStoredCompletionsDataSourceConfig + +__all__ = [ + "EvalRetrieveResponse", + "DataSourceConfig", + "DataSourceConfigLogs", + "TestingCriterion", + "TestingCriterionEvalGraderTextSimilarity", + "TestingCriterionEvalGraderPython", + "TestingCriterionEvalGraderScoreModel", +] + + +class DataSourceConfigLogs(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["logs"] + """The type of data source. Always `logs`.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + +DataSourceConfig: TypeAlias = Annotated[ + Union[EvalCustomDataSourceConfig, DataSourceConfigLogs, EvalStoredCompletionsDataSourceConfig], + PropertyInfo(discriminator="type"), +] + + +class TestingCriterionEvalGraderTextSimilarity(TextSimilarityGrader): + __test__ = False + pass_threshold: float + """The threshold for the score.""" + + +class TestingCriterionEvalGraderPython(PythonGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +class TestingCriterionEvalGraderScoreModel(ScoreModelGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +TestingCriterion: TypeAlias = Union[ + LabelModelGrader, + StringCheckGrader, + TestingCriterionEvalGraderTextSimilarity, + TestingCriterionEvalGraderPython, + TestingCriterionEvalGraderScoreModel, +] + + +class EvalRetrieveResponse(BaseModel): + id: str + """Unique identifier for the evaluation.""" + + created_at: int + """The Unix timestamp (in seconds) for when the eval was created.""" + + data_source_config: DataSourceConfig + """Configuration of data sources used in runs of the evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the evaluation.""" + + object: Literal["eval"] + """The object type.""" + + testing_criteria: List[TestingCriterion] + """A list of testing criteria.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_stored_completions_data_source_config.py b/.venv/lib/python3.13/site-packages/openai/types/eval_stored_completions_data_source_config.py new file mode 100644 index 0000000000000000000000000000000000000000..98f86a47198097ce228f12b6b135c13649b7a47e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_stored_completions_data_source_config.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from .._models import BaseModel +from .shared.metadata import Metadata + +__all__ = ["EvalStoredCompletionsDataSourceConfig"] + + +class EvalStoredCompletionsDataSourceConfig(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["stored_completions"] + """The type of data source. Always `stored_completions`.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_update_params.py b/.venv/lib/python3.13/site-packages/openai/types/eval_update_params.py new file mode 100644 index 0000000000000000000000000000000000000000..042db29af5210fa0d26d6dfcdef2ffdba470f1e0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_update_params.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import TypedDict + +from .shared_params.metadata import Metadata + +__all__ = ["EvalUpdateParams"] + + +class EvalUpdateParams(TypedDict, total=False): + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """Rename the evaluation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/eval_update_response.py b/.venv/lib/python3.13/site-packages/openai/types/eval_update_response.py new file mode 100644 index 0000000000000000000000000000000000000000..3f0b90ae0309a9b0b7848f89d1865b55f7821af4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/eval_update_response.py @@ -0,0 +1,111 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from .._utils import PropertyInfo +from .._models import BaseModel +from .shared.metadata import Metadata +from .graders.python_grader import PythonGrader +from .graders.label_model_grader import LabelModelGrader +from .graders.score_model_grader import ScoreModelGrader +from .graders.string_check_grader import StringCheckGrader +from .eval_custom_data_source_config import EvalCustomDataSourceConfig +from .graders.text_similarity_grader import TextSimilarityGrader +from .eval_stored_completions_data_source_config import EvalStoredCompletionsDataSourceConfig + +__all__ = [ + "EvalUpdateResponse", + "DataSourceConfig", + "DataSourceConfigLogs", + "TestingCriterion", + "TestingCriterionEvalGraderTextSimilarity", + "TestingCriterionEvalGraderPython", + "TestingCriterionEvalGraderScoreModel", +] + + +class DataSourceConfigLogs(BaseModel): + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The json schema for the run data source items. Learn how to build JSON schemas + [here](https://json-schema.org/). + """ + + type: Literal["logs"] + """The type of data source. Always `logs`.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + +DataSourceConfig: TypeAlias = Annotated[ + Union[EvalCustomDataSourceConfig, DataSourceConfigLogs, EvalStoredCompletionsDataSourceConfig], + PropertyInfo(discriminator="type"), +] + + +class TestingCriterionEvalGraderTextSimilarity(TextSimilarityGrader): + __test__ = False + pass_threshold: float + """The threshold for the score.""" + + +class TestingCriterionEvalGraderPython(PythonGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +class TestingCriterionEvalGraderScoreModel(ScoreModelGrader): + __test__ = False + pass_threshold: Optional[float] = None + """The threshold for the score.""" + + +TestingCriterion: TypeAlias = Union[ + LabelModelGrader, + StringCheckGrader, + TestingCriterionEvalGraderTextSimilarity, + TestingCriterionEvalGraderPython, + TestingCriterionEvalGraderScoreModel, +] + + +class EvalUpdateResponse(BaseModel): + id: str + """Unique identifier for the evaluation.""" + + created_at: int + """The Unix timestamp (in seconds) for when the eval was created.""" + + data_source_config: DataSourceConfig + """Configuration of data sources used in runs of the evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the evaluation.""" + + object: Literal["eval"] + """The object type.""" + + testing_criteria: List[TestingCriterion] + """A list of testing criteria.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/evals/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..ebf84c6b8d7b72dcbf8987ea44aab4cbcc93742e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/__init__.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .eval_api_error import EvalAPIError as EvalAPIError +from .run_list_params import RunListParams as RunListParams +from .run_create_params import RunCreateParams as RunCreateParams +from .run_list_response import RunListResponse as RunListResponse +from .run_cancel_response import RunCancelResponse as RunCancelResponse +from .run_create_response import RunCreateResponse as RunCreateResponse +from .run_delete_response import RunDeleteResponse as RunDeleteResponse +from .run_retrieve_response import RunRetrieveResponse as RunRetrieveResponse +from .create_eval_jsonl_run_data_source import CreateEvalJSONLRunDataSource as CreateEvalJSONLRunDataSource +from .create_eval_completions_run_data_source import ( + CreateEvalCompletionsRunDataSource as CreateEvalCompletionsRunDataSource, +) +from .create_eval_jsonl_run_data_source_param import ( + CreateEvalJSONLRunDataSourceParam as CreateEvalJSONLRunDataSourceParam, +) +from .create_eval_completions_run_data_source_param import ( + CreateEvalCompletionsRunDataSourceParam as CreateEvalCompletionsRunDataSourceParam, +) diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source.py b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source.py new file mode 100644 index 0000000000000000000000000000000000000000..74323a735e9be847d891904bbd21a869c2aa52b8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source.py @@ -0,0 +1,229 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from ..shared.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..shared.response_format_text import ResponseFormatText +from ..responses.easy_input_message import EasyInputMessage +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio +from ..chat.chat_completion_function_tool import ChatCompletionFunctionTool +from ..shared.response_format_json_object import ResponseFormatJSONObject +from ..shared.response_format_json_schema import ResponseFormatJSONSchema + +__all__ = [ + "CreateEvalCompletionsRunDataSource", + "Source", + "SourceFileContent", + "SourceFileContentContent", + "SourceFileID", + "SourceStoredCompletions", + "InputMessages", + "InputMessagesTemplate", + "InputMessagesTemplateTemplate", + "InputMessagesTemplateTemplateEvalItem", + "InputMessagesTemplateTemplateEvalItemContent", + "InputMessagesTemplateTemplateEvalItemContentOutputText", + "InputMessagesTemplateTemplateEvalItemContentInputImage", + "InputMessagesItemReference", + "SamplingParams", + "SamplingParamsResponseFormat", +] + + +class SourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class SourceFileContent(BaseModel): + content: List[SourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class SourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +class SourceStoredCompletions(BaseModel): + type: Literal["stored_completions"] + """The type of source. Always `stored_completions`.""" + + created_after: Optional[int] = None + """An optional Unix timestamp to filter items created after this time.""" + + created_before: Optional[int] = None + """An optional Unix timestamp to filter items created before this time.""" + + limit: Optional[int] = None + """An optional maximum number of items to return.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: Optional[str] = None + """An optional model to filter by (e.g., 'gpt-4o').""" + + +Source: TypeAlias = Annotated[ + Union[SourceFileContent, SourceFileID, SourceStoredCompletions], PropertyInfo(discriminator="type") +] + + +class InputMessagesTemplateTemplateEvalItemContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class InputMessagesTemplateTemplateEvalItemContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputText, + InputMessagesTemplateTemplateEvalItemContentOutputText, + InputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudio, + List[object], +] + + +class InputMessagesTemplateTemplateEvalItem(BaseModel): + content: InputMessagesTemplateTemplateEvalItemContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +InputMessagesTemplateTemplate: TypeAlias = Union[EasyInputMessage, InputMessagesTemplateTemplateEvalItem] + + +class InputMessagesTemplate(BaseModel): + template: List[InputMessagesTemplateTemplate] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Literal["template"] + """The type of input messages. Always `template`.""" + + +class InputMessagesItemReference(BaseModel): + item_reference: str + """A reference to a variable in the `item` namespace. Ie, "item.input_trajectory" """ + + type: Literal["item_reference"] + """The type of input messages. Always `item_reference`.""" + + +InputMessages: TypeAlias = Annotated[ + Union[InputMessagesTemplate, InputMessagesItemReference], PropertyInfo(discriminator="type") +] + +SamplingParamsResponseFormat: TypeAlias = Union[ResponseFormatText, ResponseFormatJSONSchema, ResponseFormatJSONObject] + + +class SamplingParams(BaseModel): + max_completion_tokens: Optional[int] = None + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + response_format: Optional[SamplingParamsResponseFormat] = None + """An object specifying the format that the model must output. + + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured + Outputs which ensures the model will match your supplied JSON schema. Learn more + in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + tools: Optional[List[ChatCompletionFunctionTool]] = None + """A list of tools the model may call. + + Currently, only functions are supported as a tool. Use this to provide a list of + functions the model may generate JSON inputs for. A max of 128 functions are + supported. + """ + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class CreateEvalCompletionsRunDataSource(BaseModel): + source: Source + """Determines what populates the `item` namespace in this run's data source.""" + + type: Literal["completions"] + """The type of run data source. Always `completions`.""" + + input_messages: Optional[InputMessages] = None + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: Optional[str] = None + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: Optional[SamplingParams] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source_param.py b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source_param.py new file mode 100644 index 0000000000000000000000000000000000000000..4e9c1fdeb838a16308546a4d84c66c1681243def --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_completions_run_data_source_param.py @@ -0,0 +1,225 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..shared_params.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.easy_input_message_param import EasyInputMessageParam +from ..shared_params.response_format_text import ResponseFormatText +from ..responses.response_input_text_param import ResponseInputTextParam +from ..responses.response_input_audio_param import ResponseInputAudioParam +from ..chat.chat_completion_function_tool_param import ChatCompletionFunctionToolParam +from ..shared_params.response_format_json_object import ResponseFormatJSONObject +from ..shared_params.response_format_json_schema import ResponseFormatJSONSchema + +__all__ = [ + "CreateEvalCompletionsRunDataSourceParam", + "Source", + "SourceFileContent", + "SourceFileContentContent", + "SourceFileID", + "SourceStoredCompletions", + "InputMessages", + "InputMessagesTemplate", + "InputMessagesTemplateTemplate", + "InputMessagesTemplateTemplateEvalItem", + "InputMessagesTemplateTemplateEvalItemContent", + "InputMessagesTemplateTemplateEvalItemContentOutputText", + "InputMessagesTemplateTemplateEvalItemContentInputImage", + "InputMessagesItemReference", + "SamplingParams", + "SamplingParamsResponseFormat", +] + + +class SourceFileContentContent(TypedDict, total=False): + item: Required[Dict[str, object]] + + sample: Dict[str, object] + + +class SourceFileContent(TypedDict, total=False): + content: Required[Iterable[SourceFileContentContent]] + """The content of the jsonl file.""" + + type: Required[Literal["file_content"]] + """The type of jsonl source. Always `file_content`.""" + + +class SourceFileID(TypedDict, total=False): + id: Required[str] + """The identifier of the file.""" + + type: Required[Literal["file_id"]] + """The type of jsonl source. Always `file_id`.""" + + +class SourceStoredCompletions(TypedDict, total=False): + type: Required[Literal["stored_completions"]] + """The type of source. Always `stored_completions`.""" + + created_after: Optional[int] + """An optional Unix timestamp to filter items created after this time.""" + + created_before: Optional[int] + """An optional Unix timestamp to filter items created before this time.""" + + limit: Optional[int] + """An optional maximum number of items to return.""" + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: Optional[str] + """An optional model to filter by (e.g., 'gpt-4o').""" + + +Source: TypeAlias = Union[SourceFileContent, SourceFileID, SourceStoredCompletions] + + +class InputMessagesTemplateTemplateEvalItemContentOutputText(TypedDict, total=False): + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + +class InputMessagesTemplateTemplateEvalItemContentInputImage(TypedDict, total=False): + image_url: Required[str] + """The URL of the image input.""" + + type: Required[Literal["input_image"]] + """The type of the image input. Always `input_image`.""" + + detail: str + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputTextParam, + InputMessagesTemplateTemplateEvalItemContentOutputText, + InputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudioParam, + Iterable[object], +] + + +class InputMessagesTemplateTemplateEvalItem(TypedDict, total=False): + content: Required[InputMessagesTemplateTemplateEvalItemContent] + """Inputs to the model - can contain template strings.""" + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" + + +InputMessagesTemplateTemplate: TypeAlias = Union[EasyInputMessageParam, InputMessagesTemplateTemplateEvalItem] + + +class InputMessagesTemplate(TypedDict, total=False): + template: Required[Iterable[InputMessagesTemplateTemplate]] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Required[Literal["template"]] + """The type of input messages. Always `template`.""" + + +class InputMessagesItemReference(TypedDict, total=False): + item_reference: Required[str] + """A reference to a variable in the `item` namespace. Ie, "item.input_trajectory" """ + + type: Required[Literal["item_reference"]] + """The type of input messages. Always `item_reference`.""" + + +InputMessages: TypeAlias = Union[InputMessagesTemplate, InputMessagesItemReference] + +SamplingParamsResponseFormat: TypeAlias = Union[ResponseFormatText, ResponseFormatJSONSchema, ResponseFormatJSONObject] + + +class SamplingParams(TypedDict, total=False): + max_completion_tokens: int + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + response_format: SamplingParamsResponseFormat + """An object specifying the format that the model must output. + + Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured + Outputs which ensures the model will match your supplied JSON schema. Learn more + in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + seed: int + """A seed value to initialize the randomness, during sampling.""" + + temperature: float + """A higher temperature increases randomness in the outputs.""" + + tools: Iterable[ChatCompletionFunctionToolParam] + """A list of tools the model may call. + + Currently, only functions are supported as a tool. Use this to provide a list of + functions the model may generate JSON inputs for. A max of 128 functions are + supported. + """ + + top_p: float + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class CreateEvalCompletionsRunDataSourceParam(TypedDict, total=False): + source: Required[Source] + """Determines what populates the `item` namespace in this run's data source.""" + + type: Required[Literal["completions"]] + """The type of run data source. Always `completions`.""" + + input_messages: InputMessages + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: str + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: SamplingParams diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source.py b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source.py new file mode 100644 index 0000000000000000000000000000000000000000..ae36f8c55f81fa2f901bd84038e7cd478d341866 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["CreateEvalJSONLRunDataSource", "Source", "SourceFileContent", "SourceFileContentContent", "SourceFileID"] + + +class SourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class SourceFileContent(BaseModel): + content: List[SourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class SourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +Source: TypeAlias = Annotated[Union[SourceFileContent, SourceFileID], PropertyInfo(discriminator="type")] + + +class CreateEvalJSONLRunDataSource(BaseModel): + source: Source + """Determines what populates the `item` namespace in the data source.""" + + type: Literal["jsonl"] + """The type of data source. Always `jsonl`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source_param.py b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source_param.py new file mode 100644 index 0000000000000000000000000000000000000000..217ee363465939a5f8055a37e2ab508bfc004e43 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/create_eval_jsonl_run_data_source_param.py @@ -0,0 +1,47 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = [ + "CreateEvalJSONLRunDataSourceParam", + "Source", + "SourceFileContent", + "SourceFileContentContent", + "SourceFileID", +] + + +class SourceFileContentContent(TypedDict, total=False): + item: Required[Dict[str, object]] + + sample: Dict[str, object] + + +class SourceFileContent(TypedDict, total=False): + content: Required[Iterable[SourceFileContentContent]] + """The content of the jsonl file.""" + + type: Required[Literal["file_content"]] + """The type of jsonl source. Always `file_content`.""" + + +class SourceFileID(TypedDict, total=False): + id: Required[str] + """The identifier of the file.""" + + type: Required[Literal["file_id"]] + """The type of jsonl source. Always `file_id`.""" + + +Source: TypeAlias = Union[SourceFileContent, SourceFileID] + + +class CreateEvalJSONLRunDataSourceParam(TypedDict, total=False): + source: Required[Source] + """Determines what populates the `item` namespace in the data source.""" + + type: Required[Literal["jsonl"]] + """The type of data source. Always `jsonl`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/eval_api_error.py b/.venv/lib/python3.13/site-packages/openai/types/evals/eval_api_error.py new file mode 100644 index 0000000000000000000000000000000000000000..fe768710241747717d47fa3a04c057d9a8f09f7d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/eval_api_error.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from ..._models import BaseModel + +__all__ = ["EvalAPIError"] + + +class EvalAPIError(BaseModel): + code: str + """The error code.""" + + message: str + """The error message.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_cancel_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_cancel_response.py new file mode 100644 index 0000000000000000000000000000000000000000..d04d4ff657e0043f4fc59fa820b2d621ee859cf1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_cancel_response.py @@ -0,0 +1,403 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .eval_api_error import EvalAPIError +from ..responses.tool import Tool +from ..shared.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio +from .create_eval_jsonl_run_data_source import CreateEvalJSONLRunDataSource +from ..responses.response_format_text_config import ResponseFormatTextConfig +from .create_eval_completions_run_data_source import CreateEvalCompletionsRunDataSource + +__all__ = [ + "RunCancelResponse", + "DataSource", + "DataSourceResponses", + "DataSourceResponsesSource", + "DataSourceResponsesSourceFileContent", + "DataSourceResponsesSourceFileContentContent", + "DataSourceResponsesSourceFileID", + "DataSourceResponsesSourceResponses", + "DataSourceResponsesInputMessages", + "DataSourceResponsesInputMessagesTemplate", + "DataSourceResponsesInputMessagesTemplateTemplate", + "DataSourceResponsesInputMessagesTemplateTemplateChatMessage", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItem", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage", + "DataSourceResponsesInputMessagesItemReference", + "DataSourceResponsesSamplingParams", + "DataSourceResponsesSamplingParamsText", + "PerModelUsage", + "PerTestingCriteriaResult", + "ResultCounts", +] + + +class DataSourceResponsesSourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class DataSourceResponsesSourceFileContent(BaseModel): + content: List[DataSourceResponsesSourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class DataSourceResponsesSourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +class DataSourceResponsesSourceResponses(BaseModel): + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + created_after: Optional[int] = None + """Only include items created after this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + created_before: Optional[int] = None + """Only include items created before this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + instructions_search: Optional[str] = None + """Optional string to search the 'instructions' field. + + This is a query parameter used to select responses. + """ + + metadata: Optional[object] = None + """Metadata filter for the responses. + + This is a query parameter used to select responses. + """ + + model: Optional[str] = None + """The name of the model to find responses for. + + This is a query parameter used to select responses. + """ + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + temperature: Optional[float] = None + """Sampling temperature. This is a query parameter used to select responses.""" + + tools: Optional[List[str]] = None + """List of tool names. This is a query parameter used to select responses.""" + + top_p: Optional[float] = None + """Nucleus sampling parameter. This is a query parameter used to select responses.""" + + users: Optional[List[str]] = None + """List of user identifiers. This is a query parameter used to select responses.""" + + +DataSourceResponsesSource: TypeAlias = Annotated[ + Union[DataSourceResponsesSourceFileContent, DataSourceResponsesSourceFileID, DataSourceResponsesSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesInputMessagesTemplateTemplateChatMessage(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message (e.g. "system", "assistant", "user").""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudio, + List[object], +] + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItem(BaseModel): + content: DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +DataSourceResponsesInputMessagesTemplateTemplate: TypeAlias = Union[ + DataSourceResponsesInputMessagesTemplateTemplateChatMessage, + DataSourceResponsesInputMessagesTemplateTemplateEvalItem, +] + + +class DataSourceResponsesInputMessagesTemplate(BaseModel): + template: List[DataSourceResponsesInputMessagesTemplateTemplate] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Literal["template"] + """The type of input messages. Always `template`.""" + + +class DataSourceResponsesInputMessagesItemReference(BaseModel): + item_reference: str + """A reference to a variable in the `item` namespace. Ie, "item.name" """ + + type: Literal["item_reference"] + """The type of input messages. Always `item_reference`.""" + + +DataSourceResponsesInputMessages: TypeAlias = Annotated[ + Union[DataSourceResponsesInputMessagesTemplate, DataSourceResponsesInputMessagesItemReference], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesSamplingParamsText(BaseModel): + format: Optional[ResponseFormatTextConfig] = None + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + +class DataSourceResponsesSamplingParams(BaseModel): + max_completion_tokens: Optional[int] = None + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + text: Optional[DataSourceResponsesSamplingParamsText] = None + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tools: Optional[List[Tool]] = None + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + The two categories of tools you can provide the model are: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + """ + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class DataSourceResponses(BaseModel): + source: DataSourceResponsesSource + """Determines what populates the `item` namespace in this run's data source.""" + + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + input_messages: Optional[DataSourceResponsesInputMessages] = None + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: Optional[str] = None + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: Optional[DataSourceResponsesSamplingParams] = None + + +DataSource: TypeAlias = Annotated[ + Union[CreateEvalJSONLRunDataSource, CreateEvalCompletionsRunDataSource, DataSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class PerModelUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + invocation_count: int + """The number of invocations.""" + + run_model_name: str = FieldInfo(alias="model_name") + """The name of the model.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class PerTestingCriteriaResult(BaseModel): + failed: int + """Number of tests failed for this criteria.""" + + passed: int + """Number of tests passed for this criteria.""" + + testing_criteria: str + """A description of the testing criteria.""" + + +class ResultCounts(BaseModel): + errored: int + """Number of output items that resulted in an error.""" + + failed: int + """Number of output items that failed to pass the evaluation.""" + + passed: int + """Number of output items that passed the evaluation.""" + + total: int + """Total number of executed output items.""" + + +class RunCancelResponse(BaseModel): + id: str + """Unique identifier for the evaluation run.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + data_source: DataSource + """Information about the run's data source.""" + + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + eval_id: str + """The identifier of the associated evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: str + """The model that is evaluated, if applicable.""" + + name: str + """The name of the evaluation run.""" + + object: Literal["eval.run"] + """The type of the object. Always "eval.run".""" + + per_model_usage: List[PerModelUsage] + """Usage statistics for each model during the evaluation run.""" + + per_testing_criteria_results: List[PerTestingCriteriaResult] + """Results per testing criteria applied during the evaluation run.""" + + report_url: str + """The URL to the rendered evaluation run report on the UI dashboard.""" + + result_counts: ResultCounts + """Counters summarizing the outcomes of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..6ff897b5de2e1ccb0c60ff6f3c7de26a17caa95d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_params.py @@ -0,0 +1,326 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from ..responses.tool_param import ToolParam +from ..shared_params.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text_param import ResponseInputTextParam +from ..responses.response_input_audio_param import ResponseInputAudioParam +from .create_eval_jsonl_run_data_source_param import CreateEvalJSONLRunDataSourceParam +from ..responses.response_format_text_config_param import ResponseFormatTextConfigParam +from .create_eval_completions_run_data_source_param import CreateEvalCompletionsRunDataSourceParam + +__all__ = [ + "RunCreateParams", + "DataSource", + "DataSourceCreateEvalResponsesRunDataSource", + "DataSourceCreateEvalResponsesRunDataSourceSource", + "DataSourceCreateEvalResponsesRunDataSourceSourceFileContent", + "DataSourceCreateEvalResponsesRunDataSourceSourceFileContentContent", + "DataSourceCreateEvalResponsesRunDataSourceSourceFileID", + "DataSourceCreateEvalResponsesRunDataSourceSourceResponses", + "DataSourceCreateEvalResponsesRunDataSourceInputMessages", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplate", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplate", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateChatMessage", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItem", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContent", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentOutputText", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentInputImage", + "DataSourceCreateEvalResponsesRunDataSourceInputMessagesItemReference", + "DataSourceCreateEvalResponsesRunDataSourceSamplingParams", + "DataSourceCreateEvalResponsesRunDataSourceSamplingParamsText", +] + + +class RunCreateParams(TypedDict, total=False): + data_source: Required[DataSource] + """Details about the run's data source.""" + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the run.""" + + +class DataSourceCreateEvalResponsesRunDataSourceSourceFileContentContent(TypedDict, total=False): + item: Required[Dict[str, object]] + + sample: Dict[str, object] + + +class DataSourceCreateEvalResponsesRunDataSourceSourceFileContent(TypedDict, total=False): + content: Required[Iterable[DataSourceCreateEvalResponsesRunDataSourceSourceFileContentContent]] + """The content of the jsonl file.""" + + type: Required[Literal["file_content"]] + """The type of jsonl source. Always `file_content`.""" + + +class DataSourceCreateEvalResponsesRunDataSourceSourceFileID(TypedDict, total=False): + id: Required[str] + """The identifier of the file.""" + + type: Required[Literal["file_id"]] + """The type of jsonl source. Always `file_id`.""" + + +class DataSourceCreateEvalResponsesRunDataSourceSourceResponses(TypedDict, total=False): + type: Required[Literal["responses"]] + """The type of run data source. Always `responses`.""" + + created_after: Optional[int] + """Only include items created after this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + created_before: Optional[int] + """Only include items created before this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + instructions_search: Optional[str] + """Optional string to search the 'instructions' field. + + This is a query parameter used to select responses. + """ + + metadata: Optional[object] + """Metadata filter for the responses. + + This is a query parameter used to select responses. + """ + + model: Optional[str] + """The name of the model to find responses for. + + This is a query parameter used to select responses. + """ + + reasoning_effort: Optional[ReasoningEffort] + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + temperature: Optional[float] + """Sampling temperature. This is a query parameter used to select responses.""" + + tools: Optional[SequenceNotStr[str]] + """List of tool names. This is a query parameter used to select responses.""" + + top_p: Optional[float] + """Nucleus sampling parameter. This is a query parameter used to select responses.""" + + users: Optional[SequenceNotStr[str]] + """List of user identifiers. This is a query parameter used to select responses.""" + + +DataSourceCreateEvalResponsesRunDataSourceSource: TypeAlias = Union[ + DataSourceCreateEvalResponsesRunDataSourceSourceFileContent, + DataSourceCreateEvalResponsesRunDataSourceSourceFileID, + DataSourceCreateEvalResponsesRunDataSourceSourceResponses, +] + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateChatMessage(TypedDict, total=False): + content: Required[str] + """The content of the message.""" + + role: Required[str] + """The role of the message (e.g. "system", "assistant", "user").""" + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentOutputText( + TypedDict, total=False +): + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentInputImage( + TypedDict, total=False +): + image_url: Required[str] + """The URL of the image input.""" + + type: Required[Literal["input_image"]] + """The type of the image input. Always `input_image`.""" + + detail: str + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputTextParam, + DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentOutputText, + DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudioParam, + Iterable[object], +] + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItem(TypedDict, total=False): + content: Required[DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItemContent] + """Inputs to the model - can contain template strings.""" + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" + + +DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplate: TypeAlias = Union[ + DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateChatMessage, + DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplateEvalItem, +] + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplate(TypedDict, total=False): + template: Required[Iterable[DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplateTemplate]] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Required[Literal["template"]] + """The type of input messages. Always `template`.""" + + +class DataSourceCreateEvalResponsesRunDataSourceInputMessagesItemReference(TypedDict, total=False): + item_reference: Required[str] + """A reference to a variable in the `item` namespace. Ie, "item.name" """ + + type: Required[Literal["item_reference"]] + """The type of input messages. Always `item_reference`.""" + + +DataSourceCreateEvalResponsesRunDataSourceInputMessages: TypeAlias = Union[ + DataSourceCreateEvalResponsesRunDataSourceInputMessagesTemplate, + DataSourceCreateEvalResponsesRunDataSourceInputMessagesItemReference, +] + + +class DataSourceCreateEvalResponsesRunDataSourceSamplingParamsText(TypedDict, total=False): + format: ResponseFormatTextConfigParam + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + +class DataSourceCreateEvalResponsesRunDataSourceSamplingParams(TypedDict, total=False): + max_completion_tokens: int + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: int + """A seed value to initialize the randomness, during sampling.""" + + temperature: float + """A higher temperature increases randomness in the outputs.""" + + text: DataSourceCreateEvalResponsesRunDataSourceSamplingParamsText + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tools: Iterable[ToolParam] + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + The two categories of tools you can provide the model are: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + """ + + top_p: float + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class DataSourceCreateEvalResponsesRunDataSource(TypedDict, total=False): + source: Required[DataSourceCreateEvalResponsesRunDataSourceSource] + """Determines what populates the `item` namespace in this run's data source.""" + + type: Required[Literal["responses"]] + """The type of run data source. Always `responses`.""" + + input_messages: DataSourceCreateEvalResponsesRunDataSourceInputMessages + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: str + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: DataSourceCreateEvalResponsesRunDataSourceSamplingParams + + +DataSource: TypeAlias = Union[ + CreateEvalJSONLRunDataSourceParam, + CreateEvalCompletionsRunDataSourceParam, + DataSourceCreateEvalResponsesRunDataSource, +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..defa275c8c40ad2079d9a022e17d72e6a54f1265 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_create_response.py @@ -0,0 +1,403 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .eval_api_error import EvalAPIError +from ..responses.tool import Tool +from ..shared.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio +from .create_eval_jsonl_run_data_source import CreateEvalJSONLRunDataSource +from ..responses.response_format_text_config import ResponseFormatTextConfig +from .create_eval_completions_run_data_source import CreateEvalCompletionsRunDataSource + +__all__ = [ + "RunCreateResponse", + "DataSource", + "DataSourceResponses", + "DataSourceResponsesSource", + "DataSourceResponsesSourceFileContent", + "DataSourceResponsesSourceFileContentContent", + "DataSourceResponsesSourceFileID", + "DataSourceResponsesSourceResponses", + "DataSourceResponsesInputMessages", + "DataSourceResponsesInputMessagesTemplate", + "DataSourceResponsesInputMessagesTemplateTemplate", + "DataSourceResponsesInputMessagesTemplateTemplateChatMessage", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItem", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage", + "DataSourceResponsesInputMessagesItemReference", + "DataSourceResponsesSamplingParams", + "DataSourceResponsesSamplingParamsText", + "PerModelUsage", + "PerTestingCriteriaResult", + "ResultCounts", +] + + +class DataSourceResponsesSourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class DataSourceResponsesSourceFileContent(BaseModel): + content: List[DataSourceResponsesSourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class DataSourceResponsesSourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +class DataSourceResponsesSourceResponses(BaseModel): + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + created_after: Optional[int] = None + """Only include items created after this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + created_before: Optional[int] = None + """Only include items created before this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + instructions_search: Optional[str] = None + """Optional string to search the 'instructions' field. + + This is a query parameter used to select responses. + """ + + metadata: Optional[object] = None + """Metadata filter for the responses. + + This is a query parameter used to select responses. + """ + + model: Optional[str] = None + """The name of the model to find responses for. + + This is a query parameter used to select responses. + """ + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + temperature: Optional[float] = None + """Sampling temperature. This is a query parameter used to select responses.""" + + tools: Optional[List[str]] = None + """List of tool names. This is a query parameter used to select responses.""" + + top_p: Optional[float] = None + """Nucleus sampling parameter. This is a query parameter used to select responses.""" + + users: Optional[List[str]] = None + """List of user identifiers. This is a query parameter used to select responses.""" + + +DataSourceResponsesSource: TypeAlias = Annotated[ + Union[DataSourceResponsesSourceFileContent, DataSourceResponsesSourceFileID, DataSourceResponsesSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesInputMessagesTemplateTemplateChatMessage(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message (e.g. "system", "assistant", "user").""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudio, + List[object], +] + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItem(BaseModel): + content: DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +DataSourceResponsesInputMessagesTemplateTemplate: TypeAlias = Union[ + DataSourceResponsesInputMessagesTemplateTemplateChatMessage, + DataSourceResponsesInputMessagesTemplateTemplateEvalItem, +] + + +class DataSourceResponsesInputMessagesTemplate(BaseModel): + template: List[DataSourceResponsesInputMessagesTemplateTemplate] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Literal["template"] + """The type of input messages. Always `template`.""" + + +class DataSourceResponsesInputMessagesItemReference(BaseModel): + item_reference: str + """A reference to a variable in the `item` namespace. Ie, "item.name" """ + + type: Literal["item_reference"] + """The type of input messages. Always `item_reference`.""" + + +DataSourceResponsesInputMessages: TypeAlias = Annotated[ + Union[DataSourceResponsesInputMessagesTemplate, DataSourceResponsesInputMessagesItemReference], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesSamplingParamsText(BaseModel): + format: Optional[ResponseFormatTextConfig] = None + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + +class DataSourceResponsesSamplingParams(BaseModel): + max_completion_tokens: Optional[int] = None + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + text: Optional[DataSourceResponsesSamplingParamsText] = None + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tools: Optional[List[Tool]] = None + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + The two categories of tools you can provide the model are: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + """ + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class DataSourceResponses(BaseModel): + source: DataSourceResponsesSource + """Determines what populates the `item` namespace in this run's data source.""" + + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + input_messages: Optional[DataSourceResponsesInputMessages] = None + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: Optional[str] = None + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: Optional[DataSourceResponsesSamplingParams] = None + + +DataSource: TypeAlias = Annotated[ + Union[CreateEvalJSONLRunDataSource, CreateEvalCompletionsRunDataSource, DataSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class PerModelUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + invocation_count: int + """The number of invocations.""" + + run_model_name: str = FieldInfo(alias="model_name") + """The name of the model.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class PerTestingCriteriaResult(BaseModel): + failed: int + """Number of tests failed for this criteria.""" + + passed: int + """Number of tests passed for this criteria.""" + + testing_criteria: str + """A description of the testing criteria.""" + + +class ResultCounts(BaseModel): + errored: int + """Number of output items that resulted in an error.""" + + failed: int + """Number of output items that failed to pass the evaluation.""" + + passed: int + """Number of output items that passed the evaluation.""" + + total: int + """Total number of executed output items.""" + + +class RunCreateResponse(BaseModel): + id: str + """Unique identifier for the evaluation run.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + data_source: DataSource + """Information about the run's data source.""" + + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + eval_id: str + """The identifier of the associated evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: str + """The model that is evaluated, if applicable.""" + + name: str + """The name of the evaluation run.""" + + object: Literal["eval.run"] + """The type of the object. Always "eval.run".""" + + per_model_usage: List[PerModelUsage] + """Usage statistics for each model during the evaluation run.""" + + per_testing_criteria_results: List[PerTestingCriteriaResult] + """Results per testing criteria applied during the evaluation run.""" + + report_url: str + """The URL to the rendered evaluation run report on the UI dashboard.""" + + result_counts: ResultCounts + """Counters summarizing the outcomes of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_delete_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_delete_response.py new file mode 100644 index 0000000000000000000000000000000000000000..d48d01f86c430217ca9f55185019a368381b1176 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_delete_response.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["RunDeleteResponse"] + + +class RunDeleteResponse(BaseModel): + deleted: Optional[bool] = None + + object: Optional[str] = None + + run_id: Optional[str] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..383b89d85ce826a783a81cc5810daa2f2eaf565a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_params.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["RunListParams"] + + +class RunListParams(TypedDict, total=False): + after: str + """Identifier for the last run from the previous pagination request.""" + + limit: int + """Number of runs to retrieve.""" + + order: Literal["asc", "desc"] + """Sort order for runs by timestamp. + + Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`. + """ + + status: Literal["queued", "in_progress", "completed", "canceled", "failed"] + """Filter runs by status. + + One of `queued` | `in_progress` | `failed` | `completed` | `canceled`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_response.py new file mode 100644 index 0000000000000000000000000000000000000000..7fe0e55ace6612f48eb7e9e3fcbb6510d0188257 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_list_response.py @@ -0,0 +1,403 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .eval_api_error import EvalAPIError +from ..responses.tool import Tool +from ..shared.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio +from .create_eval_jsonl_run_data_source import CreateEvalJSONLRunDataSource +from ..responses.response_format_text_config import ResponseFormatTextConfig +from .create_eval_completions_run_data_source import CreateEvalCompletionsRunDataSource + +__all__ = [ + "RunListResponse", + "DataSource", + "DataSourceResponses", + "DataSourceResponsesSource", + "DataSourceResponsesSourceFileContent", + "DataSourceResponsesSourceFileContentContent", + "DataSourceResponsesSourceFileID", + "DataSourceResponsesSourceResponses", + "DataSourceResponsesInputMessages", + "DataSourceResponsesInputMessagesTemplate", + "DataSourceResponsesInputMessagesTemplateTemplate", + "DataSourceResponsesInputMessagesTemplateTemplateChatMessage", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItem", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage", + "DataSourceResponsesInputMessagesItemReference", + "DataSourceResponsesSamplingParams", + "DataSourceResponsesSamplingParamsText", + "PerModelUsage", + "PerTestingCriteriaResult", + "ResultCounts", +] + + +class DataSourceResponsesSourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class DataSourceResponsesSourceFileContent(BaseModel): + content: List[DataSourceResponsesSourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class DataSourceResponsesSourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +class DataSourceResponsesSourceResponses(BaseModel): + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + created_after: Optional[int] = None + """Only include items created after this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + created_before: Optional[int] = None + """Only include items created before this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + instructions_search: Optional[str] = None + """Optional string to search the 'instructions' field. + + This is a query parameter used to select responses. + """ + + metadata: Optional[object] = None + """Metadata filter for the responses. + + This is a query parameter used to select responses. + """ + + model: Optional[str] = None + """The name of the model to find responses for. + + This is a query parameter used to select responses. + """ + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + temperature: Optional[float] = None + """Sampling temperature. This is a query parameter used to select responses.""" + + tools: Optional[List[str]] = None + """List of tool names. This is a query parameter used to select responses.""" + + top_p: Optional[float] = None + """Nucleus sampling parameter. This is a query parameter used to select responses.""" + + users: Optional[List[str]] = None + """List of user identifiers. This is a query parameter used to select responses.""" + + +DataSourceResponsesSource: TypeAlias = Annotated[ + Union[DataSourceResponsesSourceFileContent, DataSourceResponsesSourceFileID, DataSourceResponsesSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesInputMessagesTemplateTemplateChatMessage(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message (e.g. "system", "assistant", "user").""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudio, + List[object], +] + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItem(BaseModel): + content: DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +DataSourceResponsesInputMessagesTemplateTemplate: TypeAlias = Union[ + DataSourceResponsesInputMessagesTemplateTemplateChatMessage, + DataSourceResponsesInputMessagesTemplateTemplateEvalItem, +] + + +class DataSourceResponsesInputMessagesTemplate(BaseModel): + template: List[DataSourceResponsesInputMessagesTemplateTemplate] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Literal["template"] + """The type of input messages. Always `template`.""" + + +class DataSourceResponsesInputMessagesItemReference(BaseModel): + item_reference: str + """A reference to a variable in the `item` namespace. Ie, "item.name" """ + + type: Literal["item_reference"] + """The type of input messages. Always `item_reference`.""" + + +DataSourceResponsesInputMessages: TypeAlias = Annotated[ + Union[DataSourceResponsesInputMessagesTemplate, DataSourceResponsesInputMessagesItemReference], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesSamplingParamsText(BaseModel): + format: Optional[ResponseFormatTextConfig] = None + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + +class DataSourceResponsesSamplingParams(BaseModel): + max_completion_tokens: Optional[int] = None + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + text: Optional[DataSourceResponsesSamplingParamsText] = None + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tools: Optional[List[Tool]] = None + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + The two categories of tools you can provide the model are: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + """ + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class DataSourceResponses(BaseModel): + source: DataSourceResponsesSource + """Determines what populates the `item` namespace in this run's data source.""" + + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + input_messages: Optional[DataSourceResponsesInputMessages] = None + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: Optional[str] = None + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: Optional[DataSourceResponsesSamplingParams] = None + + +DataSource: TypeAlias = Annotated[ + Union[CreateEvalJSONLRunDataSource, CreateEvalCompletionsRunDataSource, DataSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class PerModelUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + invocation_count: int + """The number of invocations.""" + + run_model_name: str = FieldInfo(alias="model_name") + """The name of the model.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class PerTestingCriteriaResult(BaseModel): + failed: int + """Number of tests failed for this criteria.""" + + passed: int + """Number of tests passed for this criteria.""" + + testing_criteria: str + """A description of the testing criteria.""" + + +class ResultCounts(BaseModel): + errored: int + """Number of output items that resulted in an error.""" + + failed: int + """Number of output items that failed to pass the evaluation.""" + + passed: int + """Number of output items that passed the evaluation.""" + + total: int + """Total number of executed output items.""" + + +class RunListResponse(BaseModel): + id: str + """Unique identifier for the evaluation run.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + data_source: DataSource + """Information about the run's data source.""" + + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + eval_id: str + """The identifier of the associated evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: str + """The model that is evaluated, if applicable.""" + + name: str + """The name of the evaluation run.""" + + object: Literal["eval.run"] + """The type of the object. Always "eval.run".""" + + per_model_usage: List[PerModelUsage] + """Usage statistics for each model during the evaluation run.""" + + per_testing_criteria_results: List[PerTestingCriteriaResult] + """Results per testing criteria applied during the evaluation run.""" + + report_url: str + """The URL to the rendered evaluation run report on the UI dashboard.""" + + result_counts: ResultCounts + """Counters summarizing the outcomes of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/run_retrieve_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/run_retrieve_response.py new file mode 100644 index 0000000000000000000000000000000000000000..a50520f17dc9072d5f241c1d091e8897ec5ecdeb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/run_retrieve_response.py @@ -0,0 +1,403 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from pydantic import Field as FieldInfo + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .eval_api_error import EvalAPIError +from ..responses.tool import Tool +from ..shared.metadata import Metadata +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio +from .create_eval_jsonl_run_data_source import CreateEvalJSONLRunDataSource +from ..responses.response_format_text_config import ResponseFormatTextConfig +from .create_eval_completions_run_data_source import CreateEvalCompletionsRunDataSource + +__all__ = [ + "RunRetrieveResponse", + "DataSource", + "DataSourceResponses", + "DataSourceResponsesSource", + "DataSourceResponsesSourceFileContent", + "DataSourceResponsesSourceFileContentContent", + "DataSourceResponsesSourceFileID", + "DataSourceResponsesSourceResponses", + "DataSourceResponsesInputMessages", + "DataSourceResponsesInputMessagesTemplate", + "DataSourceResponsesInputMessagesTemplateTemplate", + "DataSourceResponsesInputMessagesTemplateTemplateChatMessage", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItem", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText", + "DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage", + "DataSourceResponsesInputMessagesItemReference", + "DataSourceResponsesSamplingParams", + "DataSourceResponsesSamplingParamsText", + "PerModelUsage", + "PerTestingCriteriaResult", + "ResultCounts", +] + + +class DataSourceResponsesSourceFileContentContent(BaseModel): + item: Dict[str, object] + + sample: Optional[Dict[str, object]] = None + + +class DataSourceResponsesSourceFileContent(BaseModel): + content: List[DataSourceResponsesSourceFileContentContent] + """The content of the jsonl file.""" + + type: Literal["file_content"] + """The type of jsonl source. Always `file_content`.""" + + +class DataSourceResponsesSourceFileID(BaseModel): + id: str + """The identifier of the file.""" + + type: Literal["file_id"] + """The type of jsonl source. Always `file_id`.""" + + +class DataSourceResponsesSourceResponses(BaseModel): + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + created_after: Optional[int] = None + """Only include items created after this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + created_before: Optional[int] = None + """Only include items created before this timestamp (inclusive). + + This is a query parameter used to select responses. + """ + + instructions_search: Optional[str] = None + """Optional string to search the 'instructions' field. + + This is a query parameter used to select responses. + """ + + metadata: Optional[object] = None + """Metadata filter for the responses. + + This is a query parameter used to select responses. + """ + + model: Optional[str] = None + """The name of the model to find responses for. + + This is a query parameter used to select responses. + """ + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + temperature: Optional[float] = None + """Sampling temperature. This is a query parameter used to select responses.""" + + tools: Optional[List[str]] = None + """List of tool names. This is a query parameter used to select responses.""" + + top_p: Optional[float] = None + """Nucleus sampling parameter. This is a query parameter used to select responses.""" + + users: Optional[List[str]] = None + """List of user identifiers. This is a query parameter used to select responses.""" + + +DataSourceResponsesSource: TypeAlias = Annotated[ + Union[DataSourceResponsesSourceFileContent, DataSourceResponsesSourceFileID, DataSourceResponsesSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesInputMessagesTemplateTemplateChatMessage(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message (e.g. "system", "assistant", "user").""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent: TypeAlias = Union[ + str, + ResponseInputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentOutputText, + DataSourceResponsesInputMessagesTemplateTemplateEvalItemContentInputImage, + ResponseInputAudio, + List[object], +] + + +class DataSourceResponsesInputMessagesTemplateTemplateEvalItem(BaseModel): + content: DataSourceResponsesInputMessagesTemplateTemplateEvalItemContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +DataSourceResponsesInputMessagesTemplateTemplate: TypeAlias = Union[ + DataSourceResponsesInputMessagesTemplateTemplateChatMessage, + DataSourceResponsesInputMessagesTemplateTemplateEvalItem, +] + + +class DataSourceResponsesInputMessagesTemplate(BaseModel): + template: List[DataSourceResponsesInputMessagesTemplateTemplate] + """A list of chat messages forming the prompt or context. + + May include variable references to the `item` namespace, ie {{item.name}}. + """ + + type: Literal["template"] + """The type of input messages. Always `template`.""" + + +class DataSourceResponsesInputMessagesItemReference(BaseModel): + item_reference: str + """A reference to a variable in the `item` namespace. Ie, "item.name" """ + + type: Literal["item_reference"] + """The type of input messages. Always `item_reference`.""" + + +DataSourceResponsesInputMessages: TypeAlias = Annotated[ + Union[DataSourceResponsesInputMessagesTemplate, DataSourceResponsesInputMessagesItemReference], + PropertyInfo(discriminator="type"), +] + + +class DataSourceResponsesSamplingParamsText(BaseModel): + format: Optional[ResponseFormatTextConfig] = None + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + +class DataSourceResponsesSamplingParams(BaseModel): + max_completion_tokens: Optional[int] = None + """The maximum number of tokens in the generated output.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + text: Optional[DataSourceResponsesSamplingParamsText] = None + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tools: Optional[List[Tool]] = None + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + The two categories of tools you can provide the model are: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code. Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + """ + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class DataSourceResponses(BaseModel): + source: DataSourceResponsesSource + """Determines what populates the `item` namespace in this run's data source.""" + + type: Literal["responses"] + """The type of run data source. Always `responses`.""" + + input_messages: Optional[DataSourceResponsesInputMessages] = None + """Used when sampling from a model. + + Dictates the structure of the messages passed into the model. Can either be a + reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template + with variable references to the `item` namespace. + """ + + model: Optional[str] = None + """The name of the model to use for generating completions (e.g. "o3-mini").""" + + sampling_params: Optional[DataSourceResponsesSamplingParams] = None + + +DataSource: TypeAlias = Annotated[ + Union[CreateEvalJSONLRunDataSource, CreateEvalCompletionsRunDataSource, DataSourceResponses], + PropertyInfo(discriminator="type"), +] + + +class PerModelUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + invocation_count: int + """The number of invocations.""" + + run_model_name: str = FieldInfo(alias="model_name") + """The name of the model.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class PerTestingCriteriaResult(BaseModel): + failed: int + """Number of tests failed for this criteria.""" + + passed: int + """Number of tests passed for this criteria.""" + + testing_criteria: str + """A description of the testing criteria.""" + + +class ResultCounts(BaseModel): + errored: int + """Number of output items that resulted in an error.""" + + failed: int + """Number of output items that failed to pass the evaluation.""" + + passed: int + """Number of output items that passed the evaluation.""" + + total: int + """Total number of executed output items.""" + + +class RunRetrieveResponse(BaseModel): + id: str + """Unique identifier for the evaluation run.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + data_source: DataSource + """Information about the run's data source.""" + + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + eval_id: str + """The identifier of the associated evaluation.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: str + """The model that is evaluated, if applicable.""" + + name: str + """The name of the evaluation run.""" + + object: Literal["eval.run"] + """The type of the object. Always "eval.run".""" + + per_model_usage: List[PerModelUsage] + """Usage statistics for each model during the evaluation run.""" + + per_testing_criteria_results: List[PerTestingCriteriaResult] + """Results per testing criteria applied during the evaluation run.""" + + report_url: str + """The URL to the rendered evaluation run report on the UI dashboard.""" + + result_counts: ResultCounts + """Counters summarizing the outcomes of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/runs/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..b77cbb6acd6081ad51ac61921a9c93a51a9ff67a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/__init__.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .output_item_list_params import OutputItemListParams as OutputItemListParams +from .output_item_list_response import OutputItemListResponse as OutputItemListResponse +from .output_item_retrieve_response import OutputItemRetrieveResponse as OutputItemRetrieveResponse diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..073bfc69a7ae83145b0807448bc2d031541015e3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_params.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["OutputItemListParams"] + + +class OutputItemListParams(TypedDict, total=False): + eval_id: Required[str] + + after: str + """Identifier for the last output item from the previous pagination request.""" + + limit: int + """Number of output items to retrieve.""" + + order: Literal["asc", "desc"] + """Sort order for output items by timestamp. + + Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`. + """ + + status: Literal["fail", "pass"] + """Filter output items by status. + + Use `failed` to filter by failed output items or `pass` to filter by passed + output items. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_response.py new file mode 100644 index 0000000000000000000000000000000000000000..e88c21766f9f96d01c116b9b9e7802485dd6df0a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_list_response.py @@ -0,0 +1,134 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import TYPE_CHECKING, Dict, List, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from ...._models import BaseModel +from ..eval_api_error import EvalAPIError + +__all__ = ["OutputItemListResponse", "Result", "Sample", "SampleInput", "SampleOutput", "SampleUsage"] + + +class Result(BaseModel): + name: str + """The name of the grader.""" + + passed: bool + """Whether the grader considered the output a pass.""" + + score: float + """The numeric score produced by the grader.""" + + sample: Optional[Dict[str, object]] = None + """Optional sample or intermediate data produced by the grader.""" + + type: Optional[str] = None + """The grader type (for example, "string-check-grader").""" + + if TYPE_CHECKING: + # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a + # value to this field, so for compatibility we avoid doing it at runtime. + __pydantic_extra__: Dict[str, object] = FieldInfo(init=False) # pyright: ignore[reportIncompatibleVariableOverride] + + # Stub to indicate that arbitrary properties are accepted. + # To access properties that are not valid identifiers you can use `getattr`, e.g. + # `getattr(obj, '$type')` + def __getattr__(self, attr: str) -> object: ... + else: + __pydantic_extra__: Dict[str, object] + + +class SampleInput(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message sender (e.g., system, user, developer).""" + + +class SampleOutput(BaseModel): + content: Optional[str] = None + """The content of the message.""" + + role: Optional[str] = None + """The role of the message (e.g. "system", "assistant", "user").""" + + +class SampleUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class Sample(BaseModel): + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + finish_reason: str + """The reason why the sample generation was finished.""" + + input: List[SampleInput] + """An array of input messages.""" + + max_completion_tokens: int + """The maximum number of tokens allowed for completion.""" + + model: str + """The model used for generating the sample.""" + + output: List[SampleOutput] + """An array of output messages.""" + + seed: int + """The seed used for generating the sample.""" + + temperature: float + """The sampling temperature used.""" + + top_p: float + """The top_p value used for sampling.""" + + usage: SampleUsage + """Token usage details for the sample.""" + + +class OutputItemListResponse(BaseModel): + id: str + """Unique identifier for the evaluation run output item.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + datasource_item: Dict[str, object] + """Details of the input data source item.""" + + datasource_item_id: int + """The identifier for the data source item.""" + + eval_id: str + """The identifier of the evaluation group.""" + + object: Literal["eval.run.output_item"] + """The type of the object. Always "eval.run.output_item".""" + + results: List[Result] + """A list of grader results for this output item.""" + + run_id: str + """The identifier of the evaluation run associated with this output item.""" + + sample: Sample + """A sample containing the input and output of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_retrieve_response.py b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_retrieve_response.py new file mode 100644 index 0000000000000000000000000000000000000000..c728629b4176de763c69bcbb74a0d17ecb091928 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/evals/runs/output_item_retrieve_response.py @@ -0,0 +1,134 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import TYPE_CHECKING, Dict, List, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from ...._models import BaseModel +from ..eval_api_error import EvalAPIError + +__all__ = ["OutputItemRetrieveResponse", "Result", "Sample", "SampleInput", "SampleOutput", "SampleUsage"] + + +class Result(BaseModel): + name: str + """The name of the grader.""" + + passed: bool + """Whether the grader considered the output a pass.""" + + score: float + """The numeric score produced by the grader.""" + + sample: Optional[Dict[str, object]] = None + """Optional sample or intermediate data produced by the grader.""" + + type: Optional[str] = None + """The grader type (for example, "string-check-grader").""" + + if TYPE_CHECKING: + # Some versions of Pydantic <2.8.0 have a bug and don’t allow assigning a + # value to this field, so for compatibility we avoid doing it at runtime. + __pydantic_extra__: Dict[str, object] = FieldInfo(init=False) # pyright: ignore[reportIncompatibleVariableOverride] + + # Stub to indicate that arbitrary properties are accepted. + # To access properties that are not valid identifiers you can use `getattr`, e.g. + # `getattr(obj, '$type')` + def __getattr__(self, attr: str) -> object: ... + else: + __pydantic_extra__: Dict[str, object] + + +class SampleInput(BaseModel): + content: str + """The content of the message.""" + + role: str + """The role of the message sender (e.g., system, user, developer).""" + + +class SampleOutput(BaseModel): + content: Optional[str] = None + """The content of the message.""" + + role: Optional[str] = None + """The role of the message (e.g. "system", "assistant", "user").""" + + +class SampleUsage(BaseModel): + cached_tokens: int + """The number of tokens retrieved from cache.""" + + completion_tokens: int + """The number of completion tokens generated.""" + + prompt_tokens: int + """The number of prompt tokens used.""" + + total_tokens: int + """The total number of tokens used.""" + + +class Sample(BaseModel): + error: EvalAPIError + """An object representing an error response from the Eval API.""" + + finish_reason: str + """The reason why the sample generation was finished.""" + + input: List[SampleInput] + """An array of input messages.""" + + max_completion_tokens: int + """The maximum number of tokens allowed for completion.""" + + model: str + """The model used for generating the sample.""" + + output: List[SampleOutput] + """An array of output messages.""" + + seed: int + """The seed used for generating the sample.""" + + temperature: float + """The sampling temperature used.""" + + top_p: float + """The top_p value used for sampling.""" + + usage: SampleUsage + """Token usage details for the sample.""" + + +class OutputItemRetrieveResponse(BaseModel): + id: str + """Unique identifier for the evaluation run output item.""" + + created_at: int + """Unix timestamp (in seconds) when the evaluation run was created.""" + + datasource_item: Dict[str, object] + """Details of the input data source item.""" + + datasource_item_id: int + """The identifier for the data source item.""" + + eval_id: str + """The identifier of the evaluation group.""" + + object: Literal["eval.run.output_item"] + """The type of the object. Always "eval.run.output_item".""" + + results: List[Result] + """A list of grader results for this output item.""" + + run_id: str + """The identifier of the evaluation run associated with this output item.""" + + sample: Sample + """A sample containing the input and output of the evaluation run.""" + + status: str + """The status of the evaluation run.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy.py b/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy.py new file mode 100644 index 0000000000000000000000000000000000000000..ee96bd7884ca4325561d995699a38a108ebd9798 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from .._utils import PropertyInfo +from .other_file_chunking_strategy_object import OtherFileChunkingStrategyObject +from .static_file_chunking_strategy_object import StaticFileChunkingStrategyObject + +__all__ = ["FileChunkingStrategy"] + +FileChunkingStrategy: TypeAlias = Annotated[ + Union[StaticFileChunkingStrategyObject, OtherFileChunkingStrategyObject], PropertyInfo(discriminator="type") +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy_param.py b/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy_param.py new file mode 100644 index 0000000000000000000000000000000000000000..25d94286d8bc54293365772cfc68642f27c4f6a1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_chunking_strategy_param.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from .auto_file_chunking_strategy_param import AutoFileChunkingStrategyParam +from .static_file_chunking_strategy_object_param import StaticFileChunkingStrategyObjectParam + +__all__ = ["FileChunkingStrategyParam"] + +FileChunkingStrategyParam: TypeAlias = Union[AutoFileChunkingStrategyParam, StaticFileChunkingStrategyObjectParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_content.py b/.venv/lib/python3.13/site-packages/openai/types/file_content.py new file mode 100644 index 0000000000000000000000000000000000000000..d89eee623e36e3475322b43a4cec91716703b700 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_content.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import TypeAlias + +__all__ = ["FileContent"] + +FileContent: TypeAlias = str diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/file_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..f4583b16a39ea9525e28b6adf8f88cbd1b85dcd9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_create_params.py @@ -0,0 +1,45 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .._types import FileTypes +from .file_purpose import FilePurpose + +__all__ = ["FileCreateParams", "ExpiresAfter"] + + +class FileCreateParams(TypedDict, total=False): + file: Required[FileTypes] + """The File object (not file name) to be uploaded.""" + + purpose: Required[FilePurpose] + """The intended purpose of the uploaded file. + + One of: - `assistants`: Used in the Assistants API - `batch`: Used in the Batch + API - `fine-tune`: Used for fine-tuning - `vision`: Images used for vision + fine-tuning - `user_data`: Flexible file type for any purpose - `evals`: Used + for eval data sets + """ + + expires_after: ExpiresAfter + """The expiration policy for a file. + + By default, files with `purpose=batch` expire after 30 days and all other files + are persisted until they are manually deleted. + """ + + +class ExpiresAfter(TypedDict, total=False): + anchor: Required[Literal["created_at"]] + """Anchor timestamp after which the expiration policy applies. + + Supported anchors: `created_at`. + """ + + seconds: Required[int] + """The number of seconds after the anchor time that the file will expire. + + Must be between 3600 (1 hour) and 2592000 (30 days). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_deleted.py b/.venv/lib/python3.13/site-packages/openai/types/file_deleted.py new file mode 100644 index 0000000000000000000000000000000000000000..f25fa87a8db0742882efd7dbfffeb9235184eae1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_deleted.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["FileDeleted"] + + +class FileDeleted(BaseModel): + id: str + + deleted: bool + + object: Literal["file"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/file_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..058d874c2967a24783bcc01c45e51c5c0a5b638c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_list_params.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["FileListParams"] + + +class FileListParams(TypedDict, total=False): + after: str + """A cursor for use in pagination. + + `after` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, ending with obj_foo, your + subsequent call can include after=obj_foo in order to fetch the next page of the + list. + """ + + limit: int + """A limit on the number of objects to be returned. + + Limit can range between 1 and 10,000, and the default is 10,000. + """ + + order: Literal["asc", "desc"] + """Sort order by the `created_at` timestamp of the objects. + + `asc` for ascending order and `desc` for descending order. + """ + + purpose: str + """Only return files with the given purpose.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_object.py b/.venv/lib/python3.13/site-packages/openai/types/file_object.py new file mode 100644 index 0000000000000000000000000000000000000000..883c2de0194e1ed6ce51989c5b778114d70fea22 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_object.py @@ -0,0 +1,58 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["FileObject"] + + +class FileObject(BaseModel): + id: str + """The file identifier, which can be referenced in the API endpoints.""" + + bytes: int + """The size of the file, in bytes.""" + + created_at: int + """The Unix timestamp (in seconds) for when the file was created.""" + + filename: str + """The name of the file.""" + + object: Literal["file"] + """The object type, which is always `file`.""" + + purpose: Literal[ + "assistants", + "assistants_output", + "batch", + "batch_output", + "fine-tune", + "fine-tune-results", + "vision", + "user_data", + ] + """The intended purpose of the file. + + Supported values are `assistants`, `assistants_output`, `batch`, `batch_output`, + `fine-tune`, `fine-tune-results`, `vision`, and `user_data`. + """ + + status: Literal["uploaded", "processed", "error"] + """Deprecated. + + The current status of the file, which can be either `uploaded`, `processed`, or + `error`. + """ + + expires_at: Optional[int] = None + """The Unix timestamp (in seconds) for when the file will expire.""" + + status_details: Optional[str] = None + """Deprecated. + + For details on why a fine-tuning training file failed validation, see the + `error` field on `fine_tuning.job`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/file_purpose.py b/.venv/lib/python3.13/site-packages/openai/types/file_purpose.py new file mode 100644 index 0000000000000000000000000000000000000000..b2c2d5f9fcb374c956eebe1f49aebd9fd3aafb5e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/file_purpose.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["FilePurpose"] + +FilePurpose: TypeAlias = Literal["assistants", "batch", "fine-tune", "vision", "user_data", "evals"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..cc664eacea86c98ea283d54a1fd2bc91c2e0f644 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/__init__.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .dpo_method import DpoMethod as DpoMethod +from .fine_tuning_job import FineTuningJob as FineTuningJob +from .job_list_params import JobListParams as JobListParams +from .dpo_method_param import DpoMethodParam as DpoMethodParam +from .job_create_params import JobCreateParams as JobCreateParams +from .supervised_method import SupervisedMethod as SupervisedMethod +from .dpo_hyperparameters import DpoHyperparameters as DpoHyperparameters +from .reinforcement_method import ReinforcementMethod as ReinforcementMethod +from .fine_tuning_job_event import FineTuningJobEvent as FineTuningJobEvent +from .job_list_events_params import JobListEventsParams as JobListEventsParams +from .supervised_method_param import SupervisedMethodParam as SupervisedMethodParam +from .dpo_hyperparameters_param import DpoHyperparametersParam as DpoHyperparametersParam +from .reinforcement_method_param import ReinforcementMethodParam as ReinforcementMethodParam +from .supervised_hyperparameters import SupervisedHyperparameters as SupervisedHyperparameters +from .fine_tuning_job_integration import FineTuningJobIntegration as FineTuningJobIntegration +from .reinforcement_hyperparameters import ReinforcementHyperparameters as ReinforcementHyperparameters +from .supervised_hyperparameters_param import SupervisedHyperparametersParam as SupervisedHyperparametersParam +from .fine_tuning_job_wandb_integration import FineTuningJobWandbIntegration as FineTuningJobWandbIntegration +from .reinforcement_hyperparameters_param import ReinforcementHyperparametersParam as ReinforcementHyperparametersParam +from .fine_tuning_job_wandb_integration_object import ( + FineTuningJobWandbIntegrationObject as FineTuningJobWandbIntegrationObject, +) diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..6394961b0b76af24d7c75fdfa5d8d50f8ff9319e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/__init__.py @@ -0,0 +1,8 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .grader_run_params import GraderRunParams as GraderRunParams +from .grader_run_response import GraderRunResponse as GraderRunResponse +from .grader_validate_params import GraderValidateParams as GraderValidateParams +from .grader_validate_response import GraderValidateResponse as GraderValidateResponse diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_params.py new file mode 100644 index 0000000000000000000000000000000000000000..646407fe0924f41c13585013a3193e6d6fbe75b1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_params.py @@ -0,0 +1,40 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Required, TypeAlias, TypedDict + +from ...graders.multi_grader_param import MultiGraderParam +from ...graders.python_grader_param import PythonGraderParam +from ...graders.score_model_grader_param import ScoreModelGraderParam +from ...graders.string_check_grader_param import StringCheckGraderParam +from ...graders.text_similarity_grader_param import TextSimilarityGraderParam + +__all__ = ["GraderRunParams", "Grader"] + + +class GraderRunParams(TypedDict, total=False): + grader: Required[Grader] + """The grader used for the fine-tuning job.""" + + model_sample: Required[str] + """The model sample to be evaluated. + + This value will be used to populate the `sample` namespace. See + [the guide](https://platform.openai.com/docs/guides/graders) for more details. + The `output_json` variable will be populated if the model sample is a valid JSON + string. + """ + + item: object + """The dataset item provided to the grader. + + This will be used to populate the `item` namespace. See + [the guide](https://platform.openai.com/docs/guides/graders) for more details. + """ + + +Grader: TypeAlias = Union[ + StringCheckGraderParam, TextSimilarityGraderParam, PythonGraderParam, ScoreModelGraderParam, MultiGraderParam +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_response.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_response.py new file mode 100644 index 0000000000000000000000000000000000000000..8ef046d1334ed33e5ef92e15b7076f2caa4e3d82 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_run_response.py @@ -0,0 +1,67 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Optional + +from pydantic import Field as FieldInfo + +from ...._models import BaseModel + +__all__ = ["GraderRunResponse", "Metadata", "MetadataErrors"] + + +class MetadataErrors(BaseModel): + formula_parse_error: bool + + invalid_variable_error: bool + + api_model_grader_parse_error: bool = FieldInfo(alias="model_grader_parse_error") + + api_model_grader_refusal_error: bool = FieldInfo(alias="model_grader_refusal_error") + + api_model_grader_server_error: bool = FieldInfo(alias="model_grader_server_error") + + api_model_grader_server_error_details: Optional[str] = FieldInfo( + alias="model_grader_server_error_details", default=None + ) + + other_error: bool + + python_grader_runtime_error: bool + + python_grader_runtime_error_details: Optional[str] = None + + python_grader_server_error: bool + + python_grader_server_error_type: Optional[str] = None + + sample_parse_error: bool + + truncated_observation_error: bool + + unresponsive_reward_error: bool + + +class Metadata(BaseModel): + errors: MetadataErrors + + execution_time: float + + name: str + + sampled_model_name: Optional[str] = None + + scores: Dict[str, object] + + token_usage: Optional[int] = None + + type: str + + +class GraderRunResponse(BaseModel): + metadata: Metadata + + api_model_grader_token_usage_per_model: Dict[str, object] = FieldInfo(alias="model_grader_token_usage_per_model") + + reward: float + + sub_rewards: Dict[str, object] diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_params.py new file mode 100644 index 0000000000000000000000000000000000000000..fe9eb44e328399f9979c6067d74d3ec959c0cc1f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_params.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Required, TypeAlias, TypedDict + +from ...graders.multi_grader_param import MultiGraderParam +from ...graders.python_grader_param import PythonGraderParam +from ...graders.score_model_grader_param import ScoreModelGraderParam +from ...graders.string_check_grader_param import StringCheckGraderParam +from ...graders.text_similarity_grader_param import TextSimilarityGraderParam + +__all__ = ["GraderValidateParams", "Grader"] + + +class GraderValidateParams(TypedDict, total=False): + grader: Required[Grader] + """The grader used for the fine-tuning job.""" + + +Grader: TypeAlias = Union[ + StringCheckGraderParam, TextSimilarityGraderParam, PythonGraderParam, ScoreModelGraderParam, MultiGraderParam +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_response.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_response.py new file mode 100644 index 0000000000000000000000000000000000000000..b373292d80ca94b22240e4f10641855f1fd404c9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/alpha/grader_validate_response.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import TypeAlias + +from ...._models import BaseModel +from ...graders.multi_grader import MultiGrader +from ...graders.python_grader import PythonGrader +from ...graders.score_model_grader import ScoreModelGrader +from ...graders.string_check_grader import StringCheckGrader +from ...graders.text_similarity_grader import TextSimilarityGrader + +__all__ = ["GraderValidateResponse", "Grader"] + +Grader: TypeAlias = Union[StringCheckGrader, TextSimilarityGrader, PythonGrader, ScoreModelGrader, MultiGrader] + + +class GraderValidateResponse(BaseModel): + grader: Optional[Grader] = None + """The grader used for the fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..2947b33145f8a3f494f400198127e9f11c21b952 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/__init__.py @@ -0,0 +1,9 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .permission_create_params import PermissionCreateParams as PermissionCreateParams +from .permission_create_response import PermissionCreateResponse as PermissionCreateResponse +from .permission_delete_response import PermissionDeleteResponse as PermissionDeleteResponse +from .permission_retrieve_params import PermissionRetrieveParams as PermissionRetrieveParams +from .permission_retrieve_response import PermissionRetrieveResponse as PermissionRetrieveResponse diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..e7cf4e4ee401767a5cb8d2c838b46070197972f9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_params.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +from ...._types import SequenceNotStr + +__all__ = ["PermissionCreateParams"] + + +class PermissionCreateParams(TypedDict, total=False): + project_ids: Required[SequenceNotStr[str]] + """The project identifiers to grant access to.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..9bc14c00cc3179edfeba861b8cced4d022180037 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_create_response.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ...._models import BaseModel + +__all__ = ["PermissionCreateResponse"] + + +class PermissionCreateResponse(BaseModel): + id: str + """The permission identifier, which can be referenced in the API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the permission was created.""" + + object: Literal["checkpoint.permission"] + """The object type, which is always "checkpoint.permission".""" + + project_id: str + """The project identifier that the permission is for.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_delete_response.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_delete_response.py new file mode 100644 index 0000000000000000000000000000000000000000..1a92d912facbc602d271b8e346e52b595d7df1a1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_delete_response.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ...._models import BaseModel + +__all__ = ["PermissionDeleteResponse"] + + +class PermissionDeleteResponse(BaseModel): + id: str + """The ID of the fine-tuned model checkpoint permission that was deleted.""" + + deleted: bool + """Whether the fine-tuned model checkpoint permission was successfully deleted.""" + + object: Literal["checkpoint.permission"] + """The object type, which is always "checkpoint.permission".""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_params.py new file mode 100644 index 0000000000000000000000000000000000000000..6e66a867ca4f01cec6f467ff27826ef24c147723 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_params.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["PermissionRetrieveParams"] + + +class PermissionRetrieveParams(TypedDict, total=False): + after: str + """Identifier for the last permission ID from the previous pagination request.""" + + limit: int + """Number of permissions to retrieve.""" + + order: Literal["ascending", "descending"] + """The order in which to retrieve permissions.""" + + project_id: str + """The ID of the project to get permissions for.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_response.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_response.py new file mode 100644 index 0000000000000000000000000000000000000000..14c73b55d0656f49800bd655e8a72db3b4d900e3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/checkpoints/permission_retrieve_response.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ...._models import BaseModel + +__all__ = ["PermissionRetrieveResponse", "Data"] + + +class Data(BaseModel): + id: str + """The permission identifier, which can be referenced in the API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the permission was created.""" + + object: Literal["checkpoint.permission"] + """The object type, which is always "checkpoint.permission".""" + + project_id: str + """The project identifier that the permission is for.""" + + +class PermissionRetrieveResponse(BaseModel): + data: List[Data] + + has_more: bool + + object: Literal["list"] + + first_id: Optional[str] = None + + last_id: Optional[str] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters.py new file mode 100644 index 0000000000000000000000000000000000000000..b0b3f0581b194647a1bdc0058aa5e2db45a57f59 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["DpoHyperparameters"] + + +class DpoHyperparameters(BaseModel): + batch_size: Union[Literal["auto"], int, None] = None + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + beta: Union[Literal["auto"], float, None] = None + """The beta value for the DPO method. + + A higher beta value will increase the weight of the penalty between the policy + and reference model. + """ + + learning_rate_multiplier: Union[Literal["auto"], float, None] = None + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int, None] = None + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters_param.py new file mode 100644 index 0000000000000000000000000000000000000000..87c6ee80a507a975cdb3f3074184813fdae5e8ec --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_hyperparameters_param.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypedDict + +__all__ = ["DpoHyperparametersParam"] + + +class DpoHyperparametersParam(TypedDict, total=False): + batch_size: Union[Literal["auto"], int] + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + beta: Union[Literal["auto"], float] + """The beta value for the DPO method. + + A higher beta value will increase the weight of the penalty between the policy + and reference model. + """ + + learning_rate_multiplier: Union[Literal["auto"], float] + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int] + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method.py new file mode 100644 index 0000000000000000000000000000000000000000..3e20f360dd8d554031f67c3d63e9a4dcc856af24 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .dpo_hyperparameters import DpoHyperparameters + +__all__ = ["DpoMethod"] + + +class DpoMethod(BaseModel): + hyperparameters: Optional[DpoHyperparameters] = None + """The hyperparameters used for the DPO fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method_param.py new file mode 100644 index 0000000000000000000000000000000000000000..ce6b6510f6c467056c8603ef4c3fd0ab0250d391 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/dpo_method_param.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +from .dpo_hyperparameters_param import DpoHyperparametersParam + +__all__ = ["DpoMethodParam"] + + +class DpoMethodParam(TypedDict, total=False): + hyperparameters: DpoHyperparametersParam + """The hyperparameters used for the DPO fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job.py new file mode 100644 index 0000000000000000000000000000000000000000..f626fbba64d050f46fd4e41220f169b13f69541d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job.py @@ -0,0 +1,161 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .dpo_method import DpoMethod +from ..shared.metadata import Metadata +from .supervised_method import SupervisedMethod +from .reinforcement_method import ReinforcementMethod +from .fine_tuning_job_wandb_integration_object import FineTuningJobWandbIntegrationObject + +__all__ = ["FineTuningJob", "Error", "Hyperparameters", "Method"] + + +class Error(BaseModel): + code: str + """A machine-readable error code.""" + + message: str + """A human-readable error message.""" + + param: Optional[str] = None + """The parameter that was invalid, usually `training_file` or `validation_file`. + + This field will be null if the failure was not parameter-specific. + """ + + +class Hyperparameters(BaseModel): + batch_size: Union[Literal["auto"], int, None] = None + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + learning_rate_multiplier: Union[Literal["auto"], float, None] = None + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int, None] = None + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ + + +class Method(BaseModel): + type: Literal["supervised", "dpo", "reinforcement"] + """The type of method. Is either `supervised`, `dpo`, or `reinforcement`.""" + + dpo: Optional[DpoMethod] = None + """Configuration for the DPO fine-tuning method.""" + + reinforcement: Optional[ReinforcementMethod] = None + """Configuration for the reinforcement fine-tuning method.""" + + supervised: Optional[SupervisedMethod] = None + """Configuration for the supervised fine-tuning method.""" + + +class FineTuningJob(BaseModel): + id: str + """The object identifier, which can be referenced in the API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the fine-tuning job was created.""" + + error: Optional[Error] = None + """ + For fine-tuning jobs that have `failed`, this will contain more information on + the cause of the failure. + """ + + fine_tuned_model: Optional[str] = None + """The name of the fine-tuned model that is being created. + + The value will be null if the fine-tuning job is still running. + """ + + finished_at: Optional[int] = None + """The Unix timestamp (in seconds) for when the fine-tuning job was finished. + + The value will be null if the fine-tuning job is still running. + """ + + hyperparameters: Hyperparameters + """The hyperparameters used for the fine-tuning job. + + This value will only be returned when running `supervised` jobs. + """ + + model: str + """The base model that is being fine-tuned.""" + + object: Literal["fine_tuning.job"] + """The object type, which is always "fine_tuning.job".""" + + organization_id: str + """The organization that owns the fine-tuning job.""" + + result_files: List[str] + """The compiled results file ID(s) for the fine-tuning job. + + You can retrieve the results with the + [Files API](https://platform.openai.com/docs/api-reference/files/retrieve-contents). + """ + + seed: int + """The seed used for the fine-tuning job.""" + + status: Literal["validating_files", "queued", "running", "succeeded", "failed", "cancelled"] + """ + The current status of the fine-tuning job, which can be either + `validating_files`, `queued`, `running`, `succeeded`, `failed`, or `cancelled`. + """ + + trained_tokens: Optional[int] = None + """The total number of billable tokens processed by this fine-tuning job. + + The value will be null if the fine-tuning job is still running. + """ + + training_file: str + """The file ID used for training. + + You can retrieve the training data with the + [Files API](https://platform.openai.com/docs/api-reference/files/retrieve-contents). + """ + + validation_file: Optional[str] = None + """The file ID used for validation. + + You can retrieve the validation results with the + [Files API](https://platform.openai.com/docs/api-reference/files/retrieve-contents). + """ + + estimated_finish: Optional[int] = None + """ + The Unix timestamp (in seconds) for when the fine-tuning job is estimated to + finish. The value will be null if the fine-tuning job is not running. + """ + + integrations: Optional[List[FineTuningJobWandbIntegrationObject]] = None + """A list of integrations to enable for this fine-tuning job.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + method: Optional[Method] = None + """The method used for fine-tuning.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_event.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_event.py new file mode 100644 index 0000000000000000000000000000000000000000..1d728bd765d03d8d47aa28de866aacd0b1e694c6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_event.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +import builtins +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["FineTuningJobEvent"] + + +class FineTuningJobEvent(BaseModel): + id: str + """The object identifier.""" + + created_at: int + """The Unix timestamp (in seconds) for when the fine-tuning job was created.""" + + level: Literal["info", "warn", "error"] + """The log level of the event.""" + + message: str + """The message of the event.""" + + object: Literal["fine_tuning.job.event"] + """The object type, which is always "fine_tuning.job.event".""" + + data: Optional[builtins.object] = None + """The data associated with the event.""" + + type: Optional[Literal["message", "metrics"]] = None + """The type of event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_integration.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_integration.py new file mode 100644 index 0000000000000000000000000000000000000000..2af73fbffb3bfddecffb3eea40ed642330d3c627 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_integration.py @@ -0,0 +1,5 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .fine_tuning_job_wandb_integration_object import FineTuningJobWandbIntegrationObject + +FineTuningJobIntegration = FineTuningJobWandbIntegrationObject diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration.py new file mode 100644 index 0000000000000000000000000000000000000000..4ac282eb5411a80b327605af2f7e14039bd13ebe --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional + +from ..._models import BaseModel + +__all__ = ["FineTuningJobWandbIntegration"] + + +class FineTuningJobWandbIntegration(BaseModel): + project: str + """The name of the project that the new run will be created under.""" + + entity: Optional[str] = None + """The entity to use for the run. + + This allows you to set the team or username of the WandB user that you would + like associated with the run. If not set, the default entity for the registered + WandB API key is used. + """ + + name: Optional[str] = None + """A display name to set for the run. + + If not set, we will use the Job ID as the name. + """ + + tags: Optional[List[str]] = None + """A list of tags to be attached to the newly created run. + + These tags are passed through directly to WandB. Some default tags are generated + by OpenAI: "openai/finetune", "openai/{base-model}", "openai/{ftjob-abcdef}". + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration_object.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration_object.py new file mode 100644 index 0000000000000000000000000000000000000000..5b94354d505ca790cc96a9c9b461bfae0672ea34 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/fine_tuning_job_wandb_integration_object.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .fine_tuning_job_wandb_integration import FineTuningJobWandbIntegration + +__all__ = ["FineTuningJobWandbIntegrationObject"] + + +class FineTuningJobWandbIntegrationObject(BaseModel): + type: Literal["wandb"] + """The type of the integration being enabled for the fine-tuning job""" + + wandb: FineTuningJobWandbIntegration + """The settings for your integration with Weights and Biases. + + This payload specifies the project that metrics will be sent to. Optionally, you + can set an explicit display name for your run, add tags to your run, and set a + default entity (team, username, etc) to be associated with your run. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..351d4e0e1bf18e3d862011e5443ef9e94c1a8900 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_create_params.py @@ -0,0 +1,176 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable, Optional +from typing_extensions import Literal, Required, TypedDict + +from ..._types import SequenceNotStr +from .dpo_method_param import DpoMethodParam +from ..shared_params.metadata import Metadata +from .supervised_method_param import SupervisedMethodParam +from .reinforcement_method_param import ReinforcementMethodParam + +__all__ = ["JobCreateParams", "Hyperparameters", "Integration", "IntegrationWandb", "Method"] + + +class JobCreateParams(TypedDict, total=False): + model: Required[Union[str, Literal["babbage-002", "davinci-002", "gpt-3.5-turbo", "gpt-4o-mini"]]] + """The name of the model to fine-tune. + + You can select one of the + [supported models](https://platform.openai.com/docs/guides/fine-tuning#which-models-can-be-fine-tuned). + """ + + training_file: Required[str] + """The ID of an uploaded file that contains training data. + + See [upload file](https://platform.openai.com/docs/api-reference/files/create) + for how to upload a file. + + Your dataset must be formatted as a JSONL file. Additionally, you must upload + your file with the purpose `fine-tune`. + + The contents of the file should differ depending on if the model uses the + [chat](https://platform.openai.com/docs/api-reference/fine-tuning/chat-input), + [completions](https://platform.openai.com/docs/api-reference/fine-tuning/completions-input) + format, or if the fine-tuning method uses the + [preference](https://platform.openai.com/docs/api-reference/fine-tuning/preference-input) + format. + + See the + [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization) + for more details. + """ + + hyperparameters: Hyperparameters + """ + The hyperparameters used for the fine-tuning job. This value is now deprecated + in favor of `method`, and should be passed in under the `method` parameter. + """ + + integrations: Optional[Iterable[Integration]] + """A list of integrations to enable for your fine-tuning job.""" + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + method: Method + """The method used for fine-tuning.""" + + seed: Optional[int] + """The seed controls the reproducibility of the job. + + Passing in the same seed and job parameters should produce the same results, but + may differ in rare cases. If a seed is not specified, one will be generated for + you. + """ + + suffix: Optional[str] + """ + A string of up to 64 characters that will be added to your fine-tuned model + name. + + For example, a `suffix` of "custom-model-name" would produce a model name like + `ft:gpt-4o-mini:openai:custom-model-name:7p4lURel`. + """ + + validation_file: Optional[str] + """The ID of an uploaded file that contains validation data. + + If you provide this file, the data is used to generate validation metrics + periodically during fine-tuning. These metrics can be viewed in the fine-tuning + results file. The same data should not be present in both train and validation + files. + + Your dataset must be formatted as a JSONL file. You must upload your file with + the purpose `fine-tune`. + + See the + [fine-tuning guide](https://platform.openai.com/docs/guides/model-optimization) + for more details. + """ + + +class Hyperparameters(TypedDict, total=False): + batch_size: Union[Literal["auto"], int] + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + learning_rate_multiplier: Union[Literal["auto"], float] + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int] + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ + + +class IntegrationWandb(TypedDict, total=False): + project: Required[str] + """The name of the project that the new run will be created under.""" + + entity: Optional[str] + """The entity to use for the run. + + This allows you to set the team or username of the WandB user that you would + like associated with the run. If not set, the default entity for the registered + WandB API key is used. + """ + + name: Optional[str] + """A display name to set for the run. + + If not set, we will use the Job ID as the name. + """ + + tags: SequenceNotStr[str] + """A list of tags to be attached to the newly created run. + + These tags are passed through directly to WandB. Some default tags are generated + by OpenAI: "openai/finetune", "openai/{base-model}", "openai/{ftjob-abcdef}". + """ + + +class Integration(TypedDict, total=False): + type: Required[Literal["wandb"]] + """The type of integration to enable. + + Currently, only "wandb" (Weights and Biases) is supported. + """ + + wandb: Required[IntegrationWandb] + """The settings for your integration with Weights and Biases. + + This payload specifies the project that metrics will be sent to. Optionally, you + can set an explicit display name for your run, add tags to your run, and set a + default entity (team, username, etc) to be associated with your run. + """ + + +class Method(TypedDict, total=False): + type: Required[Literal["supervised", "dpo", "reinforcement"]] + """The type of method. Is either `supervised`, `dpo`, or `reinforcement`.""" + + dpo: DpoMethodParam + """Configuration for the DPO fine-tuning method.""" + + reinforcement: ReinforcementMethodParam + """Configuration for the reinforcement fine-tuning method.""" + + supervised: SupervisedMethodParam + """Configuration for the supervised fine-tuning method.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_events_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_events_params.py new file mode 100644 index 0000000000000000000000000000000000000000..e1c9a64dc85b994ac92deb3fa5fa216c13bd16c4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_events_params.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +__all__ = ["JobListEventsParams"] + + +class JobListEventsParams(TypedDict, total=False): + after: str + """Identifier for the last event from the previous pagination request.""" + + limit: int + """Number of events to retrieve.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..b79f3ce86ad106d9d9424d37df9860b96c67cae5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/job_list_params.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Optional +from typing_extensions import TypedDict + +__all__ = ["JobListParams"] + + +class JobListParams(TypedDict, total=False): + after: str + """Identifier for the last job from the previous pagination request.""" + + limit: int + """Number of fine-tuning jobs to retrieve.""" + + metadata: Optional[Dict[str, str]] + """Optional metadata filter. + + To filter, use the syntax `metadata[k]=v`. Alternatively, set `metadata=null` to + indicate no metadata. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..6c93da1b69f90552c97167f86cd345fd8dc05867 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/__init__.py @@ -0,0 +1,6 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .checkpoint_list_params import CheckpointListParams as CheckpointListParams +from .fine_tuning_job_checkpoint import FineTuningJobCheckpoint as FineTuningJobCheckpoint diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/checkpoint_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/checkpoint_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..adceb3b218c8c2cf5eb6c6ce8b975766e5a93c7a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/checkpoint_list_params.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +__all__ = ["CheckpointListParams"] + + +class CheckpointListParams(TypedDict, total=False): + after: str + """Identifier for the last checkpoint ID from the previous pagination request.""" + + limit: int + """Number of checkpoints to retrieve.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/fine_tuning_job_checkpoint.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/fine_tuning_job_checkpoint.py new file mode 100644 index 0000000000000000000000000000000000000000..bd07317a3e94bff0f2943504d6058da9026d1588 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/jobs/fine_tuning_job_checkpoint.py @@ -0,0 +1,47 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ...._models import BaseModel + +__all__ = ["FineTuningJobCheckpoint", "Metrics"] + + +class Metrics(BaseModel): + full_valid_loss: Optional[float] = None + + full_valid_mean_token_accuracy: Optional[float] = None + + step: Optional[float] = None + + train_loss: Optional[float] = None + + train_mean_token_accuracy: Optional[float] = None + + valid_loss: Optional[float] = None + + valid_mean_token_accuracy: Optional[float] = None + + +class FineTuningJobCheckpoint(BaseModel): + id: str + """The checkpoint identifier, which can be referenced in the API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the checkpoint was created.""" + + fine_tuned_model_checkpoint: str + """The name of the fine-tuned checkpoint model that is created.""" + + fine_tuning_job_id: str + """The name of the fine-tuning job that this checkpoint was created from.""" + + metrics: Metrics + """Metrics at the step number during the fine-tuning job.""" + + object: Literal["fine_tuning.job.checkpoint"] + """The object type, which is always "fine_tuning.job.checkpoint".""" + + step_number: int + """The step number that the checkpoint was created at.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters.py new file mode 100644 index 0000000000000000000000000000000000000000..7c1762d38ca9ec615257e3f85d258ce2b04095d8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters.py @@ -0,0 +1,43 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ReinforcementHyperparameters"] + + +class ReinforcementHyperparameters(BaseModel): + batch_size: Union[Literal["auto"], int, None] = None + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + compute_multiplier: Union[Literal["auto"], float, None] = None + """ + Multiplier on amount of compute used for exploring search space during training. + """ + + eval_interval: Union[Literal["auto"], int, None] = None + """The number of training steps between evaluation runs.""" + + eval_samples: Union[Literal["auto"], int, None] = None + """Number of evaluation samples to generate per training step.""" + + learning_rate_multiplier: Union[Literal["auto"], float, None] = None + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int, None] = None + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ + + reasoning_effort: Optional[Literal["default", "low", "medium", "high"]] = None + """Level of reasoning effort.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0cc12fcb178e06ba8c6cab70125c452b57aa3296 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_hyperparameters_param.py @@ -0,0 +1,43 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypedDict + +__all__ = ["ReinforcementHyperparametersParam"] + + +class ReinforcementHyperparametersParam(TypedDict, total=False): + batch_size: Union[Literal["auto"], int] + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + compute_multiplier: Union[Literal["auto"], float] + """ + Multiplier on amount of compute used for exploring search space during training. + """ + + eval_interval: Union[Literal["auto"], int] + """The number of training steps between evaluation runs.""" + + eval_samples: Union[Literal["auto"], int] + """Number of evaluation samples to generate per training step.""" + + learning_rate_multiplier: Union[Literal["auto"], float] + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int] + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ + + reasoning_effort: Literal["default", "low", "medium", "high"] + """Level of reasoning effort.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method.py new file mode 100644 index 0000000000000000000000000000000000000000..9b65c41033992e97f119f888960c3f0232bee747 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import TypeAlias + +from ..._models import BaseModel +from ..graders.multi_grader import MultiGrader +from ..graders.python_grader import PythonGrader +from ..graders.score_model_grader import ScoreModelGrader +from ..graders.string_check_grader import StringCheckGrader +from .reinforcement_hyperparameters import ReinforcementHyperparameters +from ..graders.text_similarity_grader import TextSimilarityGrader + +__all__ = ["ReinforcementMethod", "Grader"] + +Grader: TypeAlias = Union[StringCheckGrader, TextSimilarityGrader, PythonGrader, ScoreModelGrader, MultiGrader] + + +class ReinforcementMethod(BaseModel): + grader: Grader + """The grader used for the fine-tuning job.""" + + hyperparameters: Optional[ReinforcementHyperparameters] = None + """The hyperparameters used for the reinforcement fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method_param.py new file mode 100644 index 0000000000000000000000000000000000000000..00d5060536b08871f18affbbbaf9bf581eb9d4f0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/reinforcement_method_param.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Required, TypeAlias, TypedDict + +from ..graders.multi_grader_param import MultiGraderParam +from ..graders.python_grader_param import PythonGraderParam +from ..graders.score_model_grader_param import ScoreModelGraderParam +from ..graders.string_check_grader_param import StringCheckGraderParam +from .reinforcement_hyperparameters_param import ReinforcementHyperparametersParam +from ..graders.text_similarity_grader_param import TextSimilarityGraderParam + +__all__ = ["ReinforcementMethodParam", "Grader"] + +Grader: TypeAlias = Union[ + StringCheckGraderParam, TextSimilarityGraderParam, PythonGraderParam, ScoreModelGraderParam, MultiGraderParam +] + + +class ReinforcementMethodParam(TypedDict, total=False): + grader: Required[Grader] + """The grader used for the fine-tuning job.""" + + hyperparameters: ReinforcementHyperparametersParam + """The hyperparameters used for the reinforcement fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters.py new file mode 100644 index 0000000000000000000000000000000000000000..3955ecf437dfb00197a7b36e09cf7338311338db --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["SupervisedHyperparameters"] + + +class SupervisedHyperparameters(BaseModel): + batch_size: Union[Literal["auto"], int, None] = None + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + learning_rate_multiplier: Union[Literal["auto"], float, None] = None + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int, None] = None + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters_param.py new file mode 100644 index 0000000000000000000000000000000000000000..bd37d9b23959ede6b272798ea1b915382bbdb75b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_hyperparameters_param.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypedDict + +__all__ = ["SupervisedHyperparametersParam"] + + +class SupervisedHyperparametersParam(TypedDict, total=False): + batch_size: Union[Literal["auto"], int] + """Number of examples in each batch. + + A larger batch size means that model parameters are updated less frequently, but + with lower variance. + """ + + learning_rate_multiplier: Union[Literal["auto"], float] + """Scaling factor for the learning rate. + + A smaller learning rate may be useful to avoid overfitting. + """ + + n_epochs: Union[Literal["auto"], int] + """The number of epochs to train the model for. + + An epoch refers to one full cycle through the training dataset. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method.py new file mode 100644 index 0000000000000000000000000000000000000000..3a32bf27a061b6904c8afaf7f3b01052138fde62 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .supervised_hyperparameters import SupervisedHyperparameters + +__all__ = ["SupervisedMethod"] + + +class SupervisedMethod(BaseModel): + hyperparameters: Optional[SupervisedHyperparameters] = None + """The hyperparameters used for the fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method_param.py b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method_param.py new file mode 100644 index 0000000000000000000000000000000000000000..ba277853d7776769a5ed751d1e1ba1b7a7ca7d59 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/fine_tuning/supervised_method_param.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +from .supervised_hyperparameters_param import SupervisedHyperparametersParam + +__all__ = ["SupervisedMethodParam"] + + +class SupervisedMethodParam(TypedDict, total=False): + hyperparameters: SupervisedHyperparametersParam + """The hyperparameters used for the fine-tuning job.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/graders/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..e0a909125ec24809c4a36833e95744e66a97a411 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/__init__.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .multi_grader import MultiGrader as MultiGrader +from .python_grader import PythonGrader as PythonGrader +from .label_model_grader import LabelModelGrader as LabelModelGrader +from .multi_grader_param import MultiGraderParam as MultiGraderParam +from .score_model_grader import ScoreModelGrader as ScoreModelGrader +from .python_grader_param import PythonGraderParam as PythonGraderParam +from .string_check_grader import StringCheckGrader as StringCheckGrader +from .text_similarity_grader import TextSimilarityGrader as TextSimilarityGrader +from .label_model_grader_param import LabelModelGraderParam as LabelModelGraderParam +from .score_model_grader_param import ScoreModelGraderParam as ScoreModelGraderParam +from .string_check_grader_param import StringCheckGraderParam as StringCheckGraderParam +from .text_similarity_grader_param import TextSimilarityGraderParam as TextSimilarityGraderParam diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..0929349c2465d2fd2b4a3c1abd1c07bad84c9d38 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader.py @@ -0,0 +1,70 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio + +__all__ = ["LabelModelGrader", "Input", "InputContent", "InputContentOutputText", "InputContentInputImage"] + + +class InputContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class InputContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputContent: TypeAlias = Union[ + str, ResponseInputText, InputContentOutputText, InputContentInputImage, ResponseInputAudio, List[object] +] + + +class Input(BaseModel): + content: InputContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +class LabelModelGrader(BaseModel): + input: List[Input] + + labels: List[str] + """The labels to assign to each item in the evaluation.""" + + model: str + """The model to use for the evaluation. Must support structured outputs.""" + + name: str + """The name of the grader.""" + + passing_labels: List[str] + """The labels that indicate a passing result. Must be a subset of labels.""" + + type: Literal["label_model"] + """The object type, which is always `label_model`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..7bd6fdb4a7ddf1cf5f9876d6fe570e77c2b1007f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/label_model_grader_param.py @@ -0,0 +1,77 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from ..responses.response_input_text_param import ResponseInputTextParam +from ..responses.response_input_audio_param import ResponseInputAudioParam + +__all__ = ["LabelModelGraderParam", "Input", "InputContent", "InputContentOutputText", "InputContentInputImage"] + + +class InputContentOutputText(TypedDict, total=False): + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + +class InputContentInputImage(TypedDict, total=False): + image_url: Required[str] + """The URL of the image input.""" + + type: Required[Literal["input_image"]] + """The type of the image input. Always `input_image`.""" + + detail: str + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputContent: TypeAlias = Union[ + str, + ResponseInputTextParam, + InputContentOutputText, + InputContentInputImage, + ResponseInputAudioParam, + Iterable[object], +] + + +class Input(TypedDict, total=False): + content: Required[InputContent] + """Inputs to the model - can contain template strings.""" + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" + + +class LabelModelGraderParam(TypedDict, total=False): + input: Required[Iterable[Input]] + + labels: Required[SequenceNotStr[str]] + """The labels to assign to each item in the evaluation.""" + + model: Required[str] + """The model to use for the evaluation. Must support structured outputs.""" + + name: Required[str] + """The name of the grader.""" + + passing_labels: Required[SequenceNotStr[str]] + """The labels that indicate a passing result. Must be a subset of labels.""" + + type: Required[Literal["label_model"]] + """The object type, which is always `label_model`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..7539c68ef57df0a8ff049a4cd2ace458265579e6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .python_grader import PythonGrader +from .label_model_grader import LabelModelGrader +from .score_model_grader import ScoreModelGrader +from .string_check_grader import StringCheckGrader +from .text_similarity_grader import TextSimilarityGrader + +__all__ = ["MultiGrader", "Graders"] + +Graders: TypeAlias = Union[StringCheckGrader, TextSimilarityGrader, PythonGrader, ScoreModelGrader, LabelModelGrader] + + +class MultiGrader(BaseModel): + calculate_output: str + """A formula to calculate the output based on grader results.""" + + graders: Graders + """ + A StringCheckGrader object that performs a string comparison between input and + reference using a specified operation. + """ + + name: str + """The name of the grader.""" + + type: Literal["multi"] + """The object type, which is always `multi`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..28a6705b8151a3686bad972c8eddf77859f8a6ce --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/multi_grader_param.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .python_grader_param import PythonGraderParam +from .label_model_grader_param import LabelModelGraderParam +from .score_model_grader_param import ScoreModelGraderParam +from .string_check_grader_param import StringCheckGraderParam +from .text_similarity_grader_param import TextSimilarityGraderParam + +__all__ = ["MultiGraderParam", "Graders"] + +Graders: TypeAlias = Union[ + StringCheckGraderParam, TextSimilarityGraderParam, PythonGraderParam, ScoreModelGraderParam, LabelModelGraderParam +] + + +class MultiGraderParam(TypedDict, total=False): + calculate_output: Required[str] + """A formula to calculate the output based on grader results.""" + + graders: Required[Graders] + """ + A StringCheckGrader object that performs a string comparison between input and + reference using a specified operation. + """ + + name: Required[str] + """The name of the grader.""" + + type: Required[Literal["multi"]] + """The object type, which is always `multi`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..faa10b1ef90c7ab98786b916766fb5534682c6a0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["PythonGrader"] + + +class PythonGrader(BaseModel): + name: str + """The name of the grader.""" + + source: str + """The source code of the python script.""" + + type: Literal["python"] + """The object type, which is always `python`.""" + + image_tag: Optional[str] = None + """The image tag to use for the python script.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..efb923751e29972a01a199c44b138f385e17ca43 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/python_grader_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["PythonGraderParam"] + + +class PythonGraderParam(TypedDict, total=False): + name: Required[str] + """The name of the grader.""" + + source: Required[str] + """The source code of the python script.""" + + type: Required[Literal["python"]] + """The object type, which is always `python`.""" + + image_tag: str + """The image tag to use for the python script.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..908c6f91d3e9699cc5073a7d09c368cc0d2ffb0d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader.py @@ -0,0 +1,102 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text import ResponseInputText +from ..responses.response_input_audio import ResponseInputAudio + +__all__ = [ + "ScoreModelGrader", + "Input", + "InputContent", + "InputContentOutputText", + "InputContentInputImage", + "SamplingParams", +] + + +class InputContentOutputText(BaseModel): + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + +class InputContentInputImage(BaseModel): + image_url: str + """The URL of the image input.""" + + type: Literal["input_image"] + """The type of the image input. Always `input_image`.""" + + detail: Optional[str] = None + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputContent: TypeAlias = Union[ + str, ResponseInputText, InputContentOutputText, InputContentInputImage, ResponseInputAudio, List[object] +] + + +class Input(BaseModel): + content: InputContent + """Inputs to the model - can contain template strings.""" + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" + + +class SamplingParams(BaseModel): + max_completions_tokens: Optional[int] = None + """The maximum number of tokens the grader model may generate in its response.""" + + reasoning_effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] = None + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] = None + """A higher temperature increases randomness in the outputs.""" + + top_p: Optional[float] = None + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class ScoreModelGrader(BaseModel): + input: List[Input] + """The input text. This may include template strings.""" + + model: str + """The model to use for the evaluation.""" + + name: str + """The name of the grader.""" + + type: Literal["score_model"] + """The object type, which is always `score_model`.""" + + range: Optional[List[float]] = None + """The range of the score. Defaults to `[0, 1]`.""" + + sampling_params: Optional[SamplingParams] = None + """The sampling parameters for the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..743944e099c5c2b43f31010e20c2f06769d369af --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/score_model_grader_param.py @@ -0,0 +1,108 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..shared.reasoning_effort import ReasoningEffort +from ..responses.response_input_text_param import ResponseInputTextParam +from ..responses.response_input_audio_param import ResponseInputAudioParam + +__all__ = [ + "ScoreModelGraderParam", + "Input", + "InputContent", + "InputContentOutputText", + "InputContentInputImage", + "SamplingParams", +] + + +class InputContentOutputText(TypedDict, total=False): + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + +class InputContentInputImage(TypedDict, total=False): + image_url: Required[str] + """The URL of the image input.""" + + type: Required[Literal["input_image"]] + """The type of the image input. Always `input_image`.""" + + detail: str + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + +InputContent: TypeAlias = Union[ + str, + ResponseInputTextParam, + InputContentOutputText, + InputContentInputImage, + ResponseInputAudioParam, + Iterable[object], +] + + +class Input(TypedDict, total=False): + content: Required[InputContent] + """Inputs to the model - can contain template strings.""" + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" + + +class SamplingParams(TypedDict, total=False): + max_completions_tokens: Optional[int] + """The maximum number of tokens the grader model may generate in its response.""" + + reasoning_effort: Optional[ReasoningEffort] + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + seed: Optional[int] + """A seed value to initialize the randomness, during sampling.""" + + temperature: Optional[float] + """A higher temperature increases randomness in the outputs.""" + + top_p: Optional[float] + """An alternative to temperature for nucleus sampling; 1.0 includes all tokens.""" + + +class ScoreModelGraderParam(TypedDict, total=False): + input: Required[Iterable[Input]] + """The input text. This may include template strings.""" + + model: Required[str] + """The model to use for the evaluation.""" + + name: Required[str] + """The name of the grader.""" + + type: Required[Literal["score_model"]] + """The object type, which is always `score_model`.""" + + range: Iterable[float] + """The range of the score. Defaults to `[0, 1]`.""" + + sampling_params: SamplingParams + """The sampling parameters for the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..3bf0b8c8680916336a76b930d74cb6c36b68911c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["StringCheckGrader"] + + +class StringCheckGrader(BaseModel): + input: str + """The input text. This may include template strings.""" + + name: str + """The name of the grader.""" + + operation: Literal["eq", "ne", "like", "ilike"] + """The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`.""" + + reference: str + """The reference text. This may include template strings.""" + + type: Literal["string_check"] + """The object type, which is always `string_check`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..27b204cec0cfe7878b95249bcd6c307c552755a5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/string_check_grader_param.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["StringCheckGraderParam"] + + +class StringCheckGraderParam(TypedDict, total=False): + input: Required[str] + """The input text. This may include template strings.""" + + name: Required[str] + """The name of the grader.""" + + operation: Required[Literal["eq", "ne", "like", "ilike"]] + """The string check operation to perform. One of `eq`, `ne`, `like`, or `ilike`.""" + + reference: Required[str] + """The reference text. This may include template strings.""" + + type: Required[Literal["string_check"]] + """The object type, which is always `string_check`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader.py b/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader.py new file mode 100644 index 0000000000000000000000000000000000000000..9082ac8969a92e16176d116efe64ecb7977899bc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader.py @@ -0,0 +1,40 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["TextSimilarityGrader"] + + +class TextSimilarityGrader(BaseModel): + evaluation_metric: Literal[ + "cosine", + "fuzzy_match", + "bleu", + "gleu", + "meteor", + "rouge_1", + "rouge_2", + "rouge_3", + "rouge_4", + "rouge_5", + "rouge_l", + ] + """The evaluation metric to use. + + One of `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, + `rouge_3`, `rouge_4`, `rouge_5`, or `rouge_l`. + """ + + input: str + """The text being graded.""" + + name: str + """The name of the grader.""" + + reference: str + """The text being graded against.""" + + type: Literal["text_similarity"] + """The type of grader.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader_param.py b/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader_param.py new file mode 100644 index 0000000000000000000000000000000000000000..1646afc84b9e80e51fb403acc31e68fb7186e434 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/graders/text_similarity_grader_param.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["TextSimilarityGraderParam"] + + +class TextSimilarityGraderParam(TypedDict, total=False): + evaluation_metric: Required[ + Literal[ + "cosine", + "fuzzy_match", + "bleu", + "gleu", + "meteor", + "rouge_1", + "rouge_2", + "rouge_3", + "rouge_4", + "rouge_5", + "rouge_l", + ] + ] + """The evaluation metric to use. + + One of `cosine`, `fuzzy_match`, `bleu`, `gleu`, `meteor`, `rouge_1`, `rouge_2`, + `rouge_3`, `rouge_4`, `rouge_5`, or `rouge_l`. + """ + + input: Required[str] + """The text being graded.""" + + name: Required[str] + """The name of the grader.""" + + reference: Required[str] + """The text being graded against.""" + + type: Required[Literal["text_similarity"]] + """The type of grader.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/image.py b/.venv/lib/python3.13/site-packages/openai/types/image.py new file mode 100644 index 0000000000000000000000000000000000000000..ecaef3fd580da87b62a6f33ffa8d97fe5dd89240 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from .._models import BaseModel + +__all__ = ["Image"] + + +class Image(BaseModel): + b64_json: Optional[str] = None + """The base64-encoded JSON of the generated image. + + Default value for `gpt-image-1`, and only present if `response_format` is set to + `b64_json` for `dall-e-2` and `dall-e-3`. + """ + + revised_prompt: Optional[str] = None + """For `dall-e-3` only, the revised prompt that was used to generate the image.""" + + url: Optional[str] = None + """ + When using `dall-e-2` or `dall-e-3`, the URL of the generated image if + `response_format` is set to `url` (default value). Unsupported for + `gpt-image-1`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_create_variation_params.py b/.venv/lib/python3.13/site-packages/openai/types/image_create_variation_params.py new file mode 100644 index 0000000000000000000000000000000000000000..d10b74b2c218b69ba7a82c8d05c4487077851157 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_create_variation_params.py @@ -0,0 +1,48 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypedDict + +from .._types import FileTypes +from .image_model import ImageModel + +__all__ = ["ImageCreateVariationParams"] + + +class ImageCreateVariationParams(TypedDict, total=False): + image: Required[FileTypes] + """The image to use as the basis for the variation(s). + + Must be a valid PNG file, less than 4MB, and square. + """ + + model: Union[str, ImageModel, None] + """The model to use for image generation. + + Only `dall-e-2` is supported at this time. + """ + + n: Optional[int] + """The number of images to generate. Must be between 1 and 10.""" + + response_format: Optional[Literal["url", "b64_json"]] + """The format in which the generated images are returned. + + Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the + image has been generated. + """ + + size: Optional[Literal["256x256", "512x512", "1024x1024"]] + """The size of the generated images. + + Must be one of `256x256`, `512x512`, or `1024x1024`. + """ + + user: str + """ + A unique identifier representing your end-user, which can help OpenAI to monitor + and detect abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_edit_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_edit_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..a40682da6a5871fc415f7cb60a666d269027c67d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_edit_completed_event.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["ImageEditCompletedEvent", "Usage", "UsageInputTokensDetails"] + + +class UsageInputTokensDetails(BaseModel): + image_tokens: int + """The number of image tokens in the input prompt.""" + + text_tokens: int + """The number of text tokens in the input prompt.""" + + +class Usage(BaseModel): + input_tokens: int + """The number of tokens (images and text) in the input prompt.""" + + input_tokens_details: UsageInputTokensDetails + """The input tokens detailed information for the image generation.""" + + output_tokens: int + """The number of image tokens in the output image.""" + + total_tokens: int + """The total number of tokens (images and text) used for the image generation.""" + + +class ImageEditCompletedEvent(BaseModel): + b64_json: str + """Base64-encoded final edited image data, suitable for rendering as an image.""" + + background: Literal["transparent", "opaque", "auto"] + """The background setting for the edited image.""" + + created_at: int + """The Unix timestamp when the event was created.""" + + output_format: Literal["png", "webp", "jpeg"] + """The output format for the edited image.""" + + quality: Literal["low", "medium", "high", "auto"] + """The quality setting for the edited image.""" + + size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] + """The size of the edited image.""" + + type: Literal["image_edit.completed"] + """The type of the event. Always `image_edit.completed`.""" + + usage: Usage + """For `gpt-image-1` only, the token usage information for the image generation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_edit_params.py b/.venv/lib/python3.13/site-packages/openai/types/image_edit_params.py new file mode 100644 index 0000000000000000000000000000000000000000..065d9789fcebabb07de4004c006973d1b85a5b53 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_edit_params.py @@ -0,0 +1,144 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypedDict + +from .._types import FileTypes, SequenceNotStr +from .image_model import ImageModel + +__all__ = ["ImageEditParamsBase", "ImageEditParamsNonStreaming", "ImageEditParamsStreaming"] + + +class ImageEditParamsBase(TypedDict, total=False): + image: Required[Union[FileTypes, SequenceNotStr[FileTypes]]] + """The image(s) to edit. Must be a supported image file or an array of images. + + For `gpt-image-1`, each image should be a `png`, `webp`, or `jpg` file less than + 50MB. You can provide up to 16 images. + + For `dall-e-2`, you can only provide one image, and it should be a square `png` + file less than 4MB. + """ + + prompt: Required[str] + """A text description of the desired image(s). + + The maximum length is 1000 characters for `dall-e-2`, and 32000 characters for + `gpt-image-1`. + """ + + background: Optional[Literal["transparent", "opaque", "auto"]] + """Allows to set transparency for the background of the generated image(s). + + This parameter is only supported for `gpt-image-1`. Must be one of + `transparent`, `opaque` or `auto` (default value). When `auto` is used, the + model will automatically determine the best background for the image. + + If `transparent`, the output format needs to support transparency, so it should + be set to either `png` (default value) or `webp`. + """ + + input_fidelity: Optional[Literal["high", "low"]] + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. This parameter is only supported + for `gpt-image-1`. Supports `high` and `low`. Defaults to `low`. + """ + + mask: FileTypes + """An additional image whose fully transparent areas (e.g. + + where alpha is zero) indicate where `image` should be edited. If there are + multiple images provided, the mask will be applied on the first image. Must be a + valid PNG file, less than 4MB, and have the same dimensions as `image`. + """ + + model: Union[str, ImageModel, None] + """The model to use for image generation. + + Only `dall-e-2` and `gpt-image-1` are supported. Defaults to `dall-e-2` unless a + parameter specific to `gpt-image-1` is used. + """ + + n: Optional[int] + """The number of images to generate. Must be between 1 and 10.""" + + output_compression: Optional[int] + """The compression level (0-100%) for the generated images. + + This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` + output formats, and defaults to 100. + """ + + output_format: Optional[Literal["png", "jpeg", "webp"]] + """The format in which the generated images are returned. + + This parameter is only supported for `gpt-image-1`. Must be one of `png`, + `jpeg`, or `webp`. The default value is `png`. + """ + + partial_images: Optional[int] + """The number of partial images to generate. + + This parameter is used for streaming responses that return partial images. Value + must be between 0 and 3. When set to 0, the response will be a single image sent + in one streaming event. + + Note that the final image may be sent before the full number of partial images + are generated if the full image is generated more quickly. + """ + + quality: Optional[Literal["standard", "low", "medium", "high", "auto"]] + """The quality of the image that will be generated. + + `high`, `medium` and `low` are only supported for `gpt-image-1`. `dall-e-2` only + supports `standard` quality. Defaults to `auto`. + """ + + response_format: Optional[Literal["url", "b64_json"]] + """The format in which the generated images are returned. + + Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the + image has been generated. This parameter is only supported for `dall-e-2`, as + `gpt-image-1` will always return base64-encoded images. + """ + + size: Optional[Literal["256x256", "512x512", "1024x1024", "1536x1024", "1024x1536", "auto"]] + """The size of the generated images. + + Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or + `auto` (default value) for `gpt-image-1`, and one of `256x256`, `512x512`, or + `1024x1024` for `dall-e-2`. + """ + + user: str + """ + A unique identifier representing your end-user, which can help OpenAI to monitor + and detect abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). + """ + + +class ImageEditParamsNonStreaming(ImageEditParamsBase, total=False): + stream: Optional[Literal[False]] + """Edit the image in streaming mode. + + Defaults to `false`. See the + [Image generation guide](https://platform.openai.com/docs/guides/image-generation) + for more information. + """ + + +class ImageEditParamsStreaming(ImageEditParamsBase): + stream: Required[Literal[True]] + """Edit the image in streaming mode. + + Defaults to `false`. See the + [Image generation guide](https://platform.openai.com/docs/guides/image-generation) + for more information. + """ + + +ImageEditParams = Union[ImageEditParamsNonStreaming, ImageEditParamsStreaming] diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_edit_partial_image_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_edit_partial_image_event.py new file mode 100644 index 0000000000000000000000000000000000000000..20da45efc34a3330ad5bd294ae235f83efc87141 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_edit_partial_image_event.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["ImageEditPartialImageEvent"] + + +class ImageEditPartialImageEvent(BaseModel): + b64_json: str + """Base64-encoded partial image data, suitable for rendering as an image.""" + + background: Literal["transparent", "opaque", "auto"] + """The background setting for the requested edited image.""" + + created_at: int + """The Unix timestamp when the event was created.""" + + output_format: Literal["png", "webp", "jpeg"] + """The output format for the requested edited image.""" + + partial_image_index: int + """0-based index for the partial image (streaming).""" + + quality: Literal["low", "medium", "high", "auto"] + """The quality setting for the requested edited image.""" + + size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] + """The size of the requested edited image.""" + + type: Literal["image_edit.partial_image"] + """The type of the event. Always `image_edit.partial_image`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_edit_stream_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_edit_stream_event.py new file mode 100644 index 0000000000000000000000000000000000000000..759f6c6db5c6f2d1ad1560464ddf20771c694d61 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_edit_stream_event.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from .._utils import PropertyInfo +from .image_edit_completed_event import ImageEditCompletedEvent +from .image_edit_partial_image_event import ImageEditPartialImageEvent + +__all__ = ["ImageEditStreamEvent"] + +ImageEditStreamEvent: TypeAlias = Annotated[ + Union[ImageEditPartialImageEvent, ImageEditCompletedEvent], PropertyInfo(discriminator="type") +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_gen_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_gen_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..e78da842d459afb1a17cbdd7506e656eba95ba16 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_gen_completed_event.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["ImageGenCompletedEvent", "Usage", "UsageInputTokensDetails"] + + +class UsageInputTokensDetails(BaseModel): + image_tokens: int + """The number of image tokens in the input prompt.""" + + text_tokens: int + """The number of text tokens in the input prompt.""" + + +class Usage(BaseModel): + input_tokens: int + """The number of tokens (images and text) in the input prompt.""" + + input_tokens_details: UsageInputTokensDetails + """The input tokens detailed information for the image generation.""" + + output_tokens: int + """The number of image tokens in the output image.""" + + total_tokens: int + """The total number of tokens (images and text) used for the image generation.""" + + +class ImageGenCompletedEvent(BaseModel): + b64_json: str + """Base64-encoded image data, suitable for rendering as an image.""" + + background: Literal["transparent", "opaque", "auto"] + """The background setting for the generated image.""" + + created_at: int + """The Unix timestamp when the event was created.""" + + output_format: Literal["png", "webp", "jpeg"] + """The output format for the generated image.""" + + quality: Literal["low", "medium", "high", "auto"] + """The quality setting for the generated image.""" + + size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] + """The size of the generated image.""" + + type: Literal["image_generation.completed"] + """The type of the event. Always `image_generation.completed`.""" + + usage: Usage + """For `gpt-image-1` only, the token usage information for the image generation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_gen_partial_image_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_gen_partial_image_event.py new file mode 100644 index 0000000000000000000000000000000000000000..965d4506041d4d664c33d26381a4d85568ee5a45 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_gen_partial_image_event.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["ImageGenPartialImageEvent"] + + +class ImageGenPartialImageEvent(BaseModel): + b64_json: str + """Base64-encoded partial image data, suitable for rendering as an image.""" + + background: Literal["transparent", "opaque", "auto"] + """The background setting for the requested image.""" + + created_at: int + """The Unix timestamp when the event was created.""" + + output_format: Literal["png", "webp", "jpeg"] + """The output format for the requested image.""" + + partial_image_index: int + """0-based index for the partial image (streaming).""" + + quality: Literal["low", "medium", "high", "auto"] + """The quality setting for the requested image.""" + + size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] + """The size of the requested image.""" + + type: Literal["image_generation.partial_image"] + """The type of the event. Always `image_generation.partial_image`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_gen_stream_event.py b/.venv/lib/python3.13/site-packages/openai/types/image_gen_stream_event.py new file mode 100644 index 0000000000000000000000000000000000000000..7dde5d524519ffaf57dfc5a47e6552708bd9a00c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_gen_stream_event.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from .._utils import PropertyInfo +from .image_gen_completed_event import ImageGenCompletedEvent +from .image_gen_partial_image_event import ImageGenPartialImageEvent + +__all__ = ["ImageGenStreamEvent"] + +ImageGenStreamEvent: TypeAlias = Annotated[ + Union[ImageGenPartialImageEvent, ImageGenCompletedEvent], PropertyInfo(discriminator="type") +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_generate_params.py b/.venv/lib/python3.13/site-packages/openai/types/image_generate_params.py new file mode 100644 index 0000000000000000000000000000000000000000..e9e9292cc27fd0d41d27a215a8ac73b81d4b7f46 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_generate_params.py @@ -0,0 +1,143 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypedDict + +from .image_model import ImageModel + +__all__ = ["ImageGenerateParamsBase", "ImageGenerateParamsNonStreaming", "ImageGenerateParamsStreaming"] + + +class ImageGenerateParamsBase(TypedDict, total=False): + prompt: Required[str] + """A text description of the desired image(s). + + The maximum length is 32000 characters for `gpt-image-1`, 1000 characters for + `dall-e-2` and 4000 characters for `dall-e-3`. + """ + + background: Optional[Literal["transparent", "opaque", "auto"]] + """Allows to set transparency for the background of the generated image(s). + + This parameter is only supported for `gpt-image-1`. Must be one of + `transparent`, `opaque` or `auto` (default value). When `auto` is used, the + model will automatically determine the best background for the image. + + If `transparent`, the output format needs to support transparency, so it should + be set to either `png` (default value) or `webp`. + """ + + model: Union[str, ImageModel, None] + """The model to use for image generation. + + One of `dall-e-2`, `dall-e-3`, or `gpt-image-1`. Defaults to `dall-e-2` unless a + parameter specific to `gpt-image-1` is used. + """ + + moderation: Optional[Literal["low", "auto"]] + """Control the content-moderation level for images generated by `gpt-image-1`. + + Must be either `low` for less restrictive filtering or `auto` (default value). + """ + + n: Optional[int] + """The number of images to generate. + + Must be between 1 and 10. For `dall-e-3`, only `n=1` is supported. + """ + + output_compression: Optional[int] + """The compression level (0-100%) for the generated images. + + This parameter is only supported for `gpt-image-1` with the `webp` or `jpeg` + output formats, and defaults to 100. + """ + + output_format: Optional[Literal["png", "jpeg", "webp"]] + """The format in which the generated images are returned. + + This parameter is only supported for `gpt-image-1`. Must be one of `png`, + `jpeg`, or `webp`. + """ + + partial_images: Optional[int] + """The number of partial images to generate. + + This parameter is used for streaming responses that return partial images. Value + must be between 0 and 3. When set to 0, the response will be a single image sent + in one streaming event. + + Note that the final image may be sent before the full number of partial images + are generated if the full image is generated more quickly. + """ + + quality: Optional[Literal["standard", "hd", "low", "medium", "high", "auto"]] + """The quality of the image that will be generated. + + - `auto` (default value) will automatically select the best quality for the + given model. + - `high`, `medium` and `low` are supported for `gpt-image-1`. + - `hd` and `standard` are supported for `dall-e-3`. + - `standard` is the only option for `dall-e-2`. + """ + + response_format: Optional[Literal["url", "b64_json"]] + """The format in which generated images with `dall-e-2` and `dall-e-3` are + returned. + + Must be one of `url` or `b64_json`. URLs are only valid for 60 minutes after the + image has been generated. This parameter isn't supported for `gpt-image-1` which + will always return base64-encoded images. + """ + + size: Optional[ + Literal["auto", "1024x1024", "1536x1024", "1024x1536", "256x256", "512x512", "1792x1024", "1024x1792"] + ] + """The size of the generated images. + + Must be one of `1024x1024`, `1536x1024` (landscape), `1024x1536` (portrait), or + `auto` (default value) for `gpt-image-1`, one of `256x256`, `512x512`, or + `1024x1024` for `dall-e-2`, and one of `1024x1024`, `1792x1024`, or `1024x1792` + for `dall-e-3`. + """ + + style: Optional[Literal["vivid", "natural"]] + """The style of the generated images. + + This parameter is only supported for `dall-e-3`. Must be one of `vivid` or + `natural`. Vivid causes the model to lean towards generating hyper-real and + dramatic images. Natural causes the model to produce more natural, less + hyper-real looking images. + """ + + user: str + """ + A unique identifier representing your end-user, which can help OpenAI to monitor + and detect abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#end-user-ids). + """ + + +class ImageGenerateParamsNonStreaming(ImageGenerateParamsBase, total=False): + stream: Optional[Literal[False]] + """Generate the image in streaming mode. + + Defaults to `false`. See the + [Image generation guide](https://platform.openai.com/docs/guides/image-generation) + for more information. This parameter is only supported for `gpt-image-1`. + """ + + +class ImageGenerateParamsStreaming(ImageGenerateParamsBase): + stream: Required[Literal[True]] + """Generate the image in streaming mode. + + Defaults to `false`. See the + [Image generation guide](https://platform.openai.com/docs/guides/image-generation) + for more information. This parameter is only supported for `gpt-image-1`. + """ + + +ImageGenerateParams = Union[ImageGenerateParamsNonStreaming, ImageGenerateParamsStreaming] diff --git a/.venv/lib/python3.13/site-packages/openai/types/image_model.py b/.venv/lib/python3.13/site-packages/openai/types/image_model.py new file mode 100644 index 0000000000000000000000000000000000000000..7fed69ed82f8319ce06f6f190bd56ca09e9c195b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/image_model.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ImageModel"] + +ImageModel: TypeAlias = Literal["dall-e-2", "dall-e-3", "gpt-image-1"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/images_response.py b/.venv/lib/python3.13/site-packages/openai/types/images_response.py new file mode 100644 index 0000000000000000000000000000000000000000..89cc71df240a4a83d3aecda794f3b2c5058abe42 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/images_response.py @@ -0,0 +1,60 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from .image import Image +from .._models import BaseModel + +__all__ = ["ImagesResponse", "Usage", "UsageInputTokensDetails"] + + +class UsageInputTokensDetails(BaseModel): + image_tokens: int + """The number of image tokens in the input prompt.""" + + text_tokens: int + """The number of text tokens in the input prompt.""" + + +class Usage(BaseModel): + input_tokens: int + """The number of tokens (images and text) in the input prompt.""" + + input_tokens_details: UsageInputTokensDetails + """The input tokens detailed information for the image generation.""" + + output_tokens: int + """The number of output tokens generated by the model.""" + + total_tokens: int + """The total number of tokens (images and text) used for the image generation.""" + + +class ImagesResponse(BaseModel): + created: int + """The Unix timestamp (in seconds) of when the image was created.""" + + background: Optional[Literal["transparent", "opaque"]] = None + """The background parameter used for the image generation. + + Either `transparent` or `opaque`. + """ + + data: Optional[List[Image]] = None + """The list of generated images.""" + + output_format: Optional[Literal["png", "webp", "jpeg"]] = None + """The output format of the image generation. Either `png`, `webp`, or `jpeg`.""" + + quality: Optional[Literal["low", "medium", "high"]] = None + """The quality of the image generated. Either `low`, `medium`, or `high`.""" + + size: Optional[Literal["1024x1024", "1024x1536", "1536x1024"]] = None + """The size of the image generated. + + Either `1024x1024`, `1024x1536`, or `1536x1024`. + """ + + usage: Optional[Usage] = None + """For `gpt-image-1` only, the token usage information for the image generation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/model.py b/.venv/lib/python3.13/site-packages/openai/types/model.py new file mode 100644 index 0000000000000000000000000000000000000000..2631ee8d1a9da956f4b1ba2f1f055ef1f1868dd0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/model.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["Model"] + + +class Model(BaseModel): + id: str + """The model identifier, which can be referenced in the API endpoints.""" + + created: int + """The Unix timestamp (in seconds) when the model was created.""" + + object: Literal["model"] + """The object type, which is always "model".""" + + owned_by: str + """The organization that owns the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/model_deleted.py b/.venv/lib/python3.13/site-packages/openai/types/model_deleted.py new file mode 100644 index 0000000000000000000000000000000000000000..e7601f74e4938fa1970e01a45f32bb413d14ac99 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/model_deleted.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .._models import BaseModel + +__all__ = ["ModelDeleted"] + + +class ModelDeleted(BaseModel): + id: str + + deleted: bool + + object: str diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation.py b/.venv/lib/python3.13/site-packages/openai/types/moderation.py new file mode 100644 index 0000000000000000000000000000000000000000..608f56221822e4a79348d9d47df28bee3e09deb4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation.py @@ -0,0 +1,186 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from .._models import BaseModel + +__all__ = ["Moderation", "Categories", "CategoryAppliedInputTypes", "CategoryScores"] + + +class Categories(BaseModel): + harassment: bool + """ + Content that expresses, incites, or promotes harassing language towards any + target. + """ + + harassment_threatening: bool = FieldInfo(alias="harassment/threatening") + """ + Harassment content that also includes violence or serious harm towards any + target. + """ + + hate: bool + """ + Content that expresses, incites, or promotes hate based on race, gender, + ethnicity, religion, nationality, sexual orientation, disability status, or + caste. Hateful content aimed at non-protected groups (e.g., chess players) is + harassment. + """ + + hate_threatening: bool = FieldInfo(alias="hate/threatening") + """ + Hateful content that also includes violence or serious harm towards the targeted + group based on race, gender, ethnicity, religion, nationality, sexual + orientation, disability status, or caste. + """ + + illicit: Optional[bool] = None + """ + Content that includes instructions or advice that facilitate the planning or + execution of wrongdoing, or that gives advice or instruction on how to commit + illicit acts. For example, "how to shoplift" would fit this category. + """ + + illicit_violent: Optional[bool] = FieldInfo(alias="illicit/violent", default=None) + """ + Content that includes instructions or advice that facilitate the planning or + execution of wrongdoing that also includes violence, or that gives advice or + instruction on the procurement of any weapon. + """ + + self_harm: bool = FieldInfo(alias="self-harm") + """ + Content that promotes, encourages, or depicts acts of self-harm, such as + suicide, cutting, and eating disorders. + """ + + self_harm_instructions: bool = FieldInfo(alias="self-harm/instructions") + """ + Content that encourages performing acts of self-harm, such as suicide, cutting, + and eating disorders, or that gives instructions or advice on how to commit such + acts. + """ + + self_harm_intent: bool = FieldInfo(alias="self-harm/intent") + """ + Content where the speaker expresses that they are engaging or intend to engage + in acts of self-harm, such as suicide, cutting, and eating disorders. + """ + + sexual: bool + """ + Content meant to arouse sexual excitement, such as the description of sexual + activity, or that promotes sexual services (excluding sex education and + wellness). + """ + + sexual_minors: bool = FieldInfo(alias="sexual/minors") + """Sexual content that includes an individual who is under 18 years old.""" + + violence: bool + """Content that depicts death, violence, or physical injury.""" + + violence_graphic: bool = FieldInfo(alias="violence/graphic") + """Content that depicts death, violence, or physical injury in graphic detail.""" + + +class CategoryAppliedInputTypes(BaseModel): + harassment: List[Literal["text"]] + """The applied input type(s) for the category 'harassment'.""" + + harassment_threatening: List[Literal["text"]] = FieldInfo(alias="harassment/threatening") + """The applied input type(s) for the category 'harassment/threatening'.""" + + hate: List[Literal["text"]] + """The applied input type(s) for the category 'hate'.""" + + hate_threatening: List[Literal["text"]] = FieldInfo(alias="hate/threatening") + """The applied input type(s) for the category 'hate/threatening'.""" + + illicit: List[Literal["text"]] + """The applied input type(s) for the category 'illicit'.""" + + illicit_violent: List[Literal["text"]] = FieldInfo(alias="illicit/violent") + """The applied input type(s) for the category 'illicit/violent'.""" + + self_harm: List[Literal["text", "image"]] = FieldInfo(alias="self-harm") + """The applied input type(s) for the category 'self-harm'.""" + + self_harm_instructions: List[Literal["text", "image"]] = FieldInfo(alias="self-harm/instructions") + """The applied input type(s) for the category 'self-harm/instructions'.""" + + self_harm_intent: List[Literal["text", "image"]] = FieldInfo(alias="self-harm/intent") + """The applied input type(s) for the category 'self-harm/intent'.""" + + sexual: List[Literal["text", "image"]] + """The applied input type(s) for the category 'sexual'.""" + + sexual_minors: List[Literal["text"]] = FieldInfo(alias="sexual/minors") + """The applied input type(s) for the category 'sexual/minors'.""" + + violence: List[Literal["text", "image"]] + """The applied input type(s) for the category 'violence'.""" + + violence_graphic: List[Literal["text", "image"]] = FieldInfo(alias="violence/graphic") + """The applied input type(s) for the category 'violence/graphic'.""" + + +class CategoryScores(BaseModel): + harassment: float + """The score for the category 'harassment'.""" + + harassment_threatening: float = FieldInfo(alias="harassment/threatening") + """The score for the category 'harassment/threatening'.""" + + hate: float + """The score for the category 'hate'.""" + + hate_threatening: float = FieldInfo(alias="hate/threatening") + """The score for the category 'hate/threatening'.""" + + illicit: float + """The score for the category 'illicit'.""" + + illicit_violent: float = FieldInfo(alias="illicit/violent") + """The score for the category 'illicit/violent'.""" + + self_harm: float = FieldInfo(alias="self-harm") + """The score for the category 'self-harm'.""" + + self_harm_instructions: float = FieldInfo(alias="self-harm/instructions") + """The score for the category 'self-harm/instructions'.""" + + self_harm_intent: float = FieldInfo(alias="self-harm/intent") + """The score for the category 'self-harm/intent'.""" + + sexual: float + """The score for the category 'sexual'.""" + + sexual_minors: float = FieldInfo(alias="sexual/minors") + """The score for the category 'sexual/minors'.""" + + violence: float + """The score for the category 'violence'.""" + + violence_graphic: float = FieldInfo(alias="violence/graphic") + """The score for the category 'violence/graphic'.""" + + +class Moderation(BaseModel): + categories: Categories + """A list of the categories, and whether they are flagged or not.""" + + category_applied_input_types: CategoryAppliedInputTypes + """ + A list of the categories along with the input type(s) that the score applies to. + """ + + category_scores: CategoryScores + """A list of the categories along with their scores as predicted by model.""" + + flagged: bool + """Whether any of the below categories are flagged.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..65d9b7e5614b7d597b52321b8c8bb47a783b143c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_create_params.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Required, TypedDict + +from .._types import SequenceNotStr +from .moderation_model import ModerationModel +from .moderation_multi_modal_input_param import ModerationMultiModalInputParam + +__all__ = ["ModerationCreateParams"] + + +class ModerationCreateParams(TypedDict, total=False): + input: Required[Union[str, SequenceNotStr[str], Iterable[ModerationMultiModalInputParam]]] + """Input (or inputs) to classify. + + Can be a single string, an array of strings, or an array of multi-modal input + objects similar to other models. + """ + + model: Union[str, ModerationModel] + """The content moderation model you would like to use. + + Learn more in + [the moderation guide](https://platform.openai.com/docs/guides/moderation), and + learn about available models + [here](https://platform.openai.com/docs/models#moderation). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..79684f8a70453e06d59f44716321f2d733114dcc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_create_response.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List + +from .._models import BaseModel +from .moderation import Moderation + +__all__ = ["ModerationCreateResponse"] + + +class ModerationCreateResponse(BaseModel): + id: str + """The unique identifier for the moderation request.""" + + model: str + """The model used to generate the moderation results.""" + + results: List[Moderation] + """A list of moderation objects.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_image_url_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_image_url_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..9a69a6a257cd1db3f22d204fa1fb1f7478208f0d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_image_url_input_param.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ModerationImageURLInputParam", "ImageURL"] + + +class ImageURL(TypedDict, total=False): + url: Required[str] + """Either a URL of the image or the base64 encoded image data.""" + + +class ModerationImageURLInputParam(TypedDict, total=False): + image_url: Required[ImageURL] + """Contains either an image URL or a data URL for a base64 encoded image.""" + + type: Required[Literal["image_url"]] + """Always `image_url`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_model.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_model.py new file mode 100644 index 0000000000000000000000000000000000000000..64954c4547746e36538525f4921c7e5494a258be --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_model.py @@ -0,0 +1,9 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ModerationModel"] + +ModerationModel: TypeAlias = Literal[ + "omni-moderation-latest", "omni-moderation-2024-09-26", "text-moderation-latest", "text-moderation-stable" +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_multi_modal_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_multi_modal_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..4314e7b0314c29bcf76137284ebb7755bc51501a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_multi_modal_input_param.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from .moderation_text_input_param import ModerationTextInputParam +from .moderation_image_url_input_param import ModerationImageURLInputParam + +__all__ = ["ModerationMultiModalInputParam"] + +ModerationMultiModalInputParam: TypeAlias = Union[ModerationImageURLInputParam, ModerationTextInputParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/moderation_text_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/moderation_text_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..e5da53337bb9839211090431d42919aa813e3f59 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/moderation_text_input_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ModerationTextInputParam"] + + +class ModerationTextInputParam(TypedDict, total=False): + text: Required[str] + """A string of text to classify.""" + + type: Required[Literal["text"]] + """Always `text`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/other_file_chunking_strategy_object.py b/.venv/lib/python3.13/site-packages/openai/types/other_file_chunking_strategy_object.py new file mode 100644 index 0000000000000000000000000000000000000000..e4cd61a8fce3f2d2073eff3753554876974094ff --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/other_file_chunking_strategy_object.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["OtherFileChunkingStrategyObject"] + + +class OtherFileChunkingStrategyObject(BaseModel): + type: Literal["other"] + """Always `other`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..2d947c8a2f77046088b1f5b0afde380019415348 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/__init__.py @@ -0,0 +1,233 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .realtime_error import RealtimeError as RealtimeError +from .conversation_item import ConversationItem as ConversationItem +from .realtime_response import RealtimeResponse as RealtimeResponse +from .audio_transcription import AudioTranscription as AudioTranscription +from .log_prob_properties import LogProbProperties as LogProbProperties +from .realtime_truncation import RealtimeTruncation as RealtimeTruncation +from .response_done_event import ResponseDoneEvent as ResponseDoneEvent +from .noise_reduction_type import NoiseReductionType as NoiseReductionType +from .realtime_error_event import RealtimeErrorEvent as RealtimeErrorEvent +from .session_update_event import SessionUpdateEvent as SessionUpdateEvent +from .mcp_list_tools_failed import McpListToolsFailed as McpListToolsFailed +from .realtime_audio_config import RealtimeAudioConfig as RealtimeAudioConfig +from .realtime_client_event import RealtimeClientEvent as RealtimeClientEvent +from .realtime_server_event import RealtimeServerEvent as RealtimeServerEvent +from .realtime_tools_config import RealtimeToolsConfig as RealtimeToolsConfig +from .response_cancel_event import ResponseCancelEvent as ResponseCancelEvent +from .response_create_event import ResponseCreateEvent as ResponseCreateEvent +from .session_created_event import SessionCreatedEvent as SessionCreatedEvent +from .session_updated_event import SessionUpdatedEvent as SessionUpdatedEvent +from .conversation_item_done import ConversationItemDone as ConversationItemDone +from .realtime_audio_formats import RealtimeAudioFormats as RealtimeAudioFormats +from .realtime_function_tool import RealtimeFunctionTool as RealtimeFunctionTool +from .realtime_mcp_tool_call import RealtimeMcpToolCall as RealtimeMcpToolCall +from .realtime_mcphttp_error import RealtimeMcphttpError as RealtimeMcphttpError +from .response_created_event import ResponseCreatedEvent as ResponseCreatedEvent +from .conversation_item_added import ConversationItemAdded as ConversationItemAdded +from .conversation_item_param import ConversationItemParam as ConversationItemParam +from .realtime_connect_params import RealtimeConnectParams as RealtimeConnectParams +from .realtime_mcp_list_tools import RealtimeMcpListTools as RealtimeMcpListTools +from .realtime_response_usage import RealtimeResponseUsage as RealtimeResponseUsage +from .realtime_tracing_config import RealtimeTracingConfig as RealtimeTracingConfig +from .mcp_list_tools_completed import McpListToolsCompleted as McpListToolsCompleted +from .realtime_response_status import RealtimeResponseStatus as RealtimeResponseStatus +from .response_mcp_call_failed import ResponseMcpCallFailed as ResponseMcpCallFailed +from .response_text_done_event import ResponseTextDoneEvent as ResponseTextDoneEvent +from .audio_transcription_param import AudioTranscriptionParam as AudioTranscriptionParam +from .rate_limits_updated_event import RateLimitsUpdatedEvent as RateLimitsUpdatedEvent +from .realtime_truncation_param import RealtimeTruncationParam as RealtimeTruncationParam +from .response_audio_done_event import ResponseAudioDoneEvent as ResponseAudioDoneEvent +from .response_text_delta_event import ResponseTextDeltaEvent as ResponseTextDeltaEvent +from .conversation_created_event import ConversationCreatedEvent as ConversationCreatedEvent +from .mcp_list_tools_in_progress import McpListToolsInProgress as McpListToolsInProgress +from .response_audio_delta_event import ResponseAudioDeltaEvent as ResponseAudioDeltaEvent +from .session_update_event_param import SessionUpdateEventParam as SessionUpdateEventParam +from .client_secret_create_params import ClientSecretCreateParams as ClientSecretCreateParams +from .realtime_audio_config_input import RealtimeAudioConfigInput as RealtimeAudioConfigInput +from .realtime_audio_config_param import RealtimeAudioConfigParam as RealtimeAudioConfigParam +from .realtime_client_event_param import RealtimeClientEventParam as RealtimeClientEventParam +from .realtime_mcp_protocol_error import RealtimeMcpProtocolError as RealtimeMcpProtocolError +from .realtime_tool_choice_config import RealtimeToolChoiceConfig as RealtimeToolChoiceConfig +from .realtime_tools_config_param import RealtimeToolsConfigParam as RealtimeToolsConfigParam +from .realtime_tools_config_union import RealtimeToolsConfigUnion as RealtimeToolsConfigUnion +from .response_cancel_event_param import ResponseCancelEventParam as ResponseCancelEventParam +from .response_create_event_param import ResponseCreateEventParam as ResponseCreateEventParam +from .response_mcp_call_completed import ResponseMcpCallCompleted as ResponseMcpCallCompleted +from .realtime_audio_config_output import RealtimeAudioConfigOutput as RealtimeAudioConfigOutput +from .realtime_audio_formats_param import RealtimeAudioFormatsParam as RealtimeAudioFormatsParam +from .realtime_function_tool_param import RealtimeFunctionToolParam as RealtimeFunctionToolParam +from .realtime_mcp_tool_call_param import RealtimeMcpToolCallParam as RealtimeMcpToolCallParam +from .realtime_mcphttp_error_param import RealtimeMcphttpErrorParam as RealtimeMcphttpErrorParam +from .client_secret_create_response import ClientSecretCreateResponse as ClientSecretCreateResponse +from .realtime_mcp_approval_request import RealtimeMcpApprovalRequest as RealtimeMcpApprovalRequest +from .realtime_mcp_list_tools_param import RealtimeMcpListToolsParam as RealtimeMcpListToolsParam +from .realtime_tracing_config_param import RealtimeTracingConfigParam as RealtimeTracingConfigParam +from .response_mcp_call_in_progress import ResponseMcpCallInProgress as ResponseMcpCallInProgress +from .conversation_item_create_event import ConversationItemCreateEvent as ConversationItemCreateEvent +from .conversation_item_delete_event import ConversationItemDeleteEvent as ConversationItemDeleteEvent +from .input_audio_buffer_clear_event import InputAudioBufferClearEvent as InputAudioBufferClearEvent +from .realtime_mcp_approval_response import RealtimeMcpApprovalResponse as RealtimeMcpApprovalResponse +from .realtime_session_client_secret import RealtimeSessionClientSecret as RealtimeSessionClientSecret +from .conversation_item_created_event import ConversationItemCreatedEvent as ConversationItemCreatedEvent +from .conversation_item_deleted_event import ConversationItemDeletedEvent as ConversationItemDeletedEvent +from .input_audio_buffer_append_event import InputAudioBufferAppendEvent as InputAudioBufferAppendEvent +from .input_audio_buffer_commit_event import InputAudioBufferCommitEvent as InputAudioBufferCommitEvent +from .output_audio_buffer_clear_event import OutputAudioBufferClearEvent as OutputAudioBufferClearEvent +from .realtime_response_create_params import RealtimeResponseCreateParams as RealtimeResponseCreateParams +from .realtime_session_create_request import RealtimeSessionCreateRequest as RealtimeSessionCreateRequest +from .response_output_item_done_event import ResponseOutputItemDoneEvent as ResponseOutputItemDoneEvent +from .conversation_item_retrieve_event import ConversationItemRetrieveEvent as ConversationItemRetrieveEvent +from .conversation_item_truncate_event import ConversationItemTruncateEvent as ConversationItemTruncateEvent +from .input_audio_buffer_cleared_event import InputAudioBufferClearedEvent as InputAudioBufferClearedEvent +from .realtime_session_create_response import RealtimeSessionCreateResponse as RealtimeSessionCreateResponse +from .response_content_part_done_event import ResponseContentPartDoneEvent as ResponseContentPartDoneEvent +from .response_mcp_call_arguments_done import ResponseMcpCallArgumentsDone as ResponseMcpCallArgumentsDone +from .response_output_item_added_event import ResponseOutputItemAddedEvent as ResponseOutputItemAddedEvent +from .conversation_item_truncated_event import ConversationItemTruncatedEvent as ConversationItemTruncatedEvent +from .realtime_audio_config_input_param import RealtimeAudioConfigInputParam as RealtimeAudioConfigInputParam +from .realtime_mcp_protocol_error_param import RealtimeMcpProtocolErrorParam as RealtimeMcpProtocolErrorParam +from .realtime_mcp_tool_execution_error import RealtimeMcpToolExecutionError as RealtimeMcpToolExecutionError +from .realtime_response_create_mcp_tool import RealtimeResponseCreateMcpTool as RealtimeResponseCreateMcpTool +from .realtime_tool_choice_config_param import RealtimeToolChoiceConfigParam as RealtimeToolChoiceConfigParam +from .realtime_tools_config_union_param import RealtimeToolsConfigUnionParam as RealtimeToolsConfigUnionParam +from .response_content_part_added_event import ResponseContentPartAddedEvent as ResponseContentPartAddedEvent +from .response_mcp_call_arguments_delta import ResponseMcpCallArgumentsDelta as ResponseMcpCallArgumentsDelta +from .input_audio_buffer_committed_event import InputAudioBufferCommittedEvent as InputAudioBufferCommittedEvent +from .realtime_audio_config_output_param import RealtimeAudioConfigOutputParam as RealtimeAudioConfigOutputParam +from .realtime_audio_input_turn_detection import RealtimeAudioInputTurnDetection as RealtimeAudioInputTurnDetection +from .realtime_mcp_approval_request_param import RealtimeMcpApprovalRequestParam as RealtimeMcpApprovalRequestParam +from .realtime_truncation_retention_ratio import RealtimeTruncationRetentionRatio as RealtimeTruncationRetentionRatio +from .conversation_item_create_event_param import ConversationItemCreateEventParam as ConversationItemCreateEventParam +from .conversation_item_delete_event_param import ConversationItemDeleteEventParam as ConversationItemDeleteEventParam +from .input_audio_buffer_clear_event_param import InputAudioBufferClearEventParam as InputAudioBufferClearEventParam +from .input_audio_buffer_timeout_triggered import InputAudioBufferTimeoutTriggered as InputAudioBufferTimeoutTriggered +from .realtime_mcp_approval_response_param import RealtimeMcpApprovalResponseParam as RealtimeMcpApprovalResponseParam +from .realtime_transcription_session_audio import RealtimeTranscriptionSessionAudio as RealtimeTranscriptionSessionAudio +from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent as ResponseAudioTranscriptDoneEvent +from .input_audio_buffer_append_event_param import InputAudioBufferAppendEventParam as InputAudioBufferAppendEventParam +from .input_audio_buffer_commit_event_param import InputAudioBufferCommitEventParam as InputAudioBufferCommitEventParam +from .output_audio_buffer_clear_event_param import OutputAudioBufferClearEventParam as OutputAudioBufferClearEventParam +from .realtime_response_create_audio_output import ( + RealtimeResponseCreateAudioOutput as RealtimeResponseCreateAudioOutput, +) +from .realtime_response_create_params_param import ( + RealtimeResponseCreateParamsParam as RealtimeResponseCreateParamsParam, +) +from .realtime_session_create_request_param import ( + RealtimeSessionCreateRequestParam as RealtimeSessionCreateRequestParam, +) +from .response_audio_transcript_delta_event import ( + ResponseAudioTranscriptDeltaEvent as ResponseAudioTranscriptDeltaEvent, +) +from .conversation_item_retrieve_event_param import ( + ConversationItemRetrieveEventParam as ConversationItemRetrieveEventParam, +) +from .conversation_item_truncate_event_param import ( + ConversationItemTruncateEventParam as ConversationItemTruncateEventParam, +) +from .input_audio_buffer_speech_started_event import ( + InputAudioBufferSpeechStartedEvent as InputAudioBufferSpeechStartedEvent, +) +from .input_audio_buffer_speech_stopped_event import ( + InputAudioBufferSpeechStoppedEvent as InputAudioBufferSpeechStoppedEvent, +) +from .realtime_conversation_item_user_message import ( + RealtimeConversationItemUserMessage as RealtimeConversationItemUserMessage, +) +from .realtime_mcp_tool_execution_error_param import ( + RealtimeMcpToolExecutionErrorParam as RealtimeMcpToolExecutionErrorParam, +) +from .realtime_response_create_mcp_tool_param import ( + RealtimeResponseCreateMcpToolParam as RealtimeResponseCreateMcpToolParam, +) +from .realtime_conversation_item_function_call import ( + RealtimeConversationItemFunctionCall as RealtimeConversationItemFunctionCall, +) +from .realtime_audio_input_turn_detection_param import ( + RealtimeAudioInputTurnDetectionParam as RealtimeAudioInputTurnDetectionParam, +) +from .realtime_conversation_item_system_message import ( + RealtimeConversationItemSystemMessage as RealtimeConversationItemSystemMessage, +) +from .realtime_truncation_retention_ratio_param import ( + RealtimeTruncationRetentionRatioParam as RealtimeTruncationRetentionRatioParam, +) +from .realtime_transcription_session_audio_input import ( + RealtimeTranscriptionSessionAudioInput as RealtimeTranscriptionSessionAudioInput, +) +from .realtime_transcription_session_audio_param import ( + RealtimeTranscriptionSessionAudioParam as RealtimeTranscriptionSessionAudioParam, +) +from .realtime_response_create_audio_output_param import ( + RealtimeResponseCreateAudioOutputParam as RealtimeResponseCreateAudioOutputParam, +) +from .realtime_response_usage_input_token_details import ( + RealtimeResponseUsageInputTokenDetails as RealtimeResponseUsageInputTokenDetails, +) +from .response_function_call_arguments_done_event import ( + ResponseFunctionCallArgumentsDoneEvent as ResponseFunctionCallArgumentsDoneEvent, +) +from .realtime_conversation_item_assistant_message import ( + RealtimeConversationItemAssistantMessage as RealtimeConversationItemAssistantMessage, +) +from .realtime_response_usage_output_token_details import ( + RealtimeResponseUsageOutputTokenDetails as RealtimeResponseUsageOutputTokenDetails, +) +from .response_function_call_arguments_delta_event import ( + ResponseFunctionCallArgumentsDeltaEvent as ResponseFunctionCallArgumentsDeltaEvent, +) +from .realtime_conversation_item_user_message_param import ( + RealtimeConversationItemUserMessageParam as RealtimeConversationItemUserMessageParam, +) +from .realtime_transcription_session_create_request import ( + RealtimeTranscriptionSessionCreateRequest as RealtimeTranscriptionSessionCreateRequest, +) +from .realtime_transcription_session_turn_detection import ( + RealtimeTranscriptionSessionTurnDetection as RealtimeTranscriptionSessionTurnDetection, +) +from .realtime_conversation_item_function_call_param import ( + RealtimeConversationItemFunctionCallParam as RealtimeConversationItemFunctionCallParam, +) +from .realtime_transcription_session_create_response import ( + RealtimeTranscriptionSessionCreateResponse as RealtimeTranscriptionSessionCreateResponse, +) +from .realtime_conversation_item_function_call_output import ( + RealtimeConversationItemFunctionCallOutput as RealtimeConversationItemFunctionCallOutput, +) +from .realtime_conversation_item_system_message_param import ( + RealtimeConversationItemSystemMessageParam as RealtimeConversationItemSystemMessageParam, +) +from .realtime_transcription_session_audio_input_param import ( + RealtimeTranscriptionSessionAudioInputParam as RealtimeTranscriptionSessionAudioInputParam, +) +from .realtime_conversation_item_assistant_message_param import ( + RealtimeConversationItemAssistantMessageParam as RealtimeConversationItemAssistantMessageParam, +) +from .conversation_item_input_audio_transcription_segment import ( + ConversationItemInputAudioTranscriptionSegment as ConversationItemInputAudioTranscriptionSegment, +) +from .realtime_transcription_session_create_request_param import ( + RealtimeTranscriptionSessionCreateRequestParam as RealtimeTranscriptionSessionCreateRequestParam, +) +from .realtime_conversation_item_function_call_output_param import ( + RealtimeConversationItemFunctionCallOutputParam as RealtimeConversationItemFunctionCallOutputParam, +) +from .conversation_item_input_audio_transcription_delta_event import ( + ConversationItemInputAudioTranscriptionDeltaEvent as ConversationItemInputAudioTranscriptionDeltaEvent, +) +from .conversation_item_input_audio_transcription_failed_event import ( + ConversationItemInputAudioTranscriptionFailedEvent as ConversationItemInputAudioTranscriptionFailedEvent, +) +from .realtime_transcription_session_audio_input_turn_detection import ( + RealtimeTranscriptionSessionAudioInputTurnDetection as RealtimeTranscriptionSessionAudioInputTurnDetection, +) +from .conversation_item_input_audio_transcription_completed_event import ( + ConversationItemInputAudioTranscriptionCompletedEvent as ConversationItemInputAudioTranscriptionCompletedEvent, +) +from .realtime_transcription_session_audio_input_turn_detection_param import ( + RealtimeTranscriptionSessionAudioInputTurnDetectionParam as RealtimeTranscriptionSessionAudioInputTurnDetectionParam, +) diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription.py new file mode 100644 index 0000000000000000000000000000000000000000..cf662b3aa266acd24fba7fafbdb1324df41b71ac --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["AudioTranscription"] + + +class AudioTranscription(BaseModel): + language: Optional[str] = None + """The language of the input audio. + + Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) + format will improve accuracy and latency. + """ + + model: Optional[Literal["whisper-1", "gpt-4o-transcribe-latest", "gpt-4o-mini-transcribe", "gpt-4o-transcribe"]] = ( + None + ) + """The model to use for transcription. + + Current options are `whisper-1`, `gpt-4o-transcribe-latest`, + `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`. + """ + + prompt: Optional[str] = None + """ + An optional text to guide the model's style or continue a previous audio + segment. For `whisper-1`, the + [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting). + For `gpt-4o-transcribe` models, the prompt is a free text string, for example + "expect words related to technology". + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription_param.py new file mode 100644 index 0000000000000000000000000000000000000000..fb09f105b8c21165e33050d1e82c836a3cf8afcb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/audio_transcription_param.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["AudioTranscriptionParam"] + + +class AudioTranscriptionParam(TypedDict, total=False): + language: str + """The language of the input audio. + + Supplying the input language in + [ISO-639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) (e.g. `en`) + format will improve accuracy and latency. + """ + + model: Literal["whisper-1", "gpt-4o-transcribe-latest", "gpt-4o-mini-transcribe", "gpt-4o-transcribe"] + """The model to use for transcription. + + Current options are `whisper-1`, `gpt-4o-transcribe-latest`, + `gpt-4o-mini-transcribe`, and `gpt-4o-transcribe`. + """ + + prompt: str + """ + An optional text to guide the model's style or continue a previous audio + segment. For `whisper-1`, the + [prompt is a list of keywords](https://platform.openai.com/docs/guides/speech-to-text#prompting). + For `gpt-4o-transcribe` models, the prompt is a free text string, for example + "expect words related to technology". + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..5f0b0d796f33a2d7f5598d0e0b43e0591d319eed --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_params.py @@ -0,0 +1,46 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypeAlias, TypedDict + +from .realtime_session_create_request_param import RealtimeSessionCreateRequestParam +from .realtime_transcription_session_create_request_param import RealtimeTranscriptionSessionCreateRequestParam + +__all__ = ["ClientSecretCreateParams", "ExpiresAfter", "Session"] + + +class ClientSecretCreateParams(TypedDict, total=False): + expires_after: ExpiresAfter + """Configuration for the client secret expiration. + + Expiration refers to the time after which a client secret will no longer be + valid for creating sessions. The session itself may continue after that time + once started. A secret can be used to create multiple sessions until it expires. + """ + + session: Session + """Session configuration to use for the client secret. + + Choose either a realtime session or a transcription session. + """ + + +class ExpiresAfter(TypedDict, total=False): + anchor: Literal["created_at"] + """ + The anchor point for the client secret expiration, meaning that `seconds` will + be added to the `created_at` time of the client secret to produce an expiration + timestamp. Only `created_at` is currently supported. + """ + + seconds: int + """The number of seconds from the anchor point to the expiration. + + Select a value between `10` and `7200` (2 hours). This default to 600 seconds + (10 minutes) if not specified. + """ + + +Session: TypeAlias = Union[RealtimeSessionCreateRequestParam, RealtimeTranscriptionSessionCreateRequestParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..2aed66a25b8d6c05ae46c73b3ba87c0cd72ba021 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/client_secret_create_response.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .realtime_session_create_response import RealtimeSessionCreateResponse +from .realtime_transcription_session_create_response import RealtimeTranscriptionSessionCreateResponse + +__all__ = ["ClientSecretCreateResponse", "Session"] + +Session: TypeAlias = Annotated[ + Union[RealtimeSessionCreateResponse, RealtimeTranscriptionSessionCreateResponse], PropertyInfo(discriminator="type") +] + + +class ClientSecretCreateResponse(BaseModel): + expires_at: int + """Expiration timestamp for the client secret, in seconds since epoch.""" + + session: Session + """The session configuration for either a realtime or transcription session.""" + + value: str + """The generated client secret value.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_created_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_created_event.py new file mode 100644 index 0000000000000000000000000000000000000000..6ec1dc8c857c58c78b3983a6396a5bb2ad7fc26e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_created_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationCreatedEvent", "Conversation"] + + +class Conversation(BaseModel): + id: Optional[str] = None + """The unique ID of the conversation.""" + + object: Optional[Literal["realtime.conversation"]] = None + """The object type, must be `realtime.conversation`.""" + + +class ConversationCreatedEvent(BaseModel): + conversation: Conversation + """The conversation resource.""" + + event_id: str + """The unique ID of the server event.""" + + type: Literal["conversation.created"] + """The event type, must be `conversation.created`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item.py new file mode 100644 index 0000000000000000000000000000000000000000..be021520a2e881b5ec4bc46b72fefb6865d6a078 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .realtime_mcp_tool_call import RealtimeMcpToolCall +from .realtime_mcp_list_tools import RealtimeMcpListTools +from .realtime_mcp_approval_request import RealtimeMcpApprovalRequest +from .realtime_mcp_approval_response import RealtimeMcpApprovalResponse +from .realtime_conversation_item_user_message import RealtimeConversationItemUserMessage +from .realtime_conversation_item_function_call import RealtimeConversationItemFunctionCall +from .realtime_conversation_item_system_message import RealtimeConversationItemSystemMessage +from .realtime_conversation_item_assistant_message import RealtimeConversationItemAssistantMessage +from .realtime_conversation_item_function_call_output import RealtimeConversationItemFunctionCallOutput + +__all__ = ["ConversationItem"] + +ConversationItem: TypeAlias = Annotated[ + Union[ + RealtimeConversationItemSystemMessage, + RealtimeConversationItemUserMessage, + RealtimeConversationItemAssistantMessage, + RealtimeConversationItemFunctionCall, + RealtimeConversationItemFunctionCallOutput, + RealtimeMcpApprovalResponse, + RealtimeMcpListTools, + RealtimeMcpToolCall, + RealtimeMcpApprovalRequest, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_added.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_added.py new file mode 100644 index 0000000000000000000000000000000000000000..ae9f6803e48f8af5676dc01bf0916ecfb867d4d6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_added.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ConversationItemAdded"] + + +class ConversationItemAdded(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + type: Literal["conversation.item.added"] + """The event type, must be `conversation.item.added`.""" + + previous_item_id: Optional[str] = None + """The ID of the item that precedes this one, if any. + + This is used to maintain ordering when items are inserted. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event.py new file mode 100644 index 0000000000000000000000000000000000000000..8fa2dfe08c956bdf50d47e0b84073e2eb1bae511 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ConversationItemCreateEvent"] + + +class ConversationItemCreateEvent(BaseModel): + item: ConversationItem + """A single item within a Realtime conversation.""" + + type: Literal["conversation.item.create"] + """The event type, must be `conversation.item.create`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" + + previous_item_id: Optional[str] = None + """The ID of the preceding item after which the new item will be inserted. + + If not set, the new item will be appended to the end of the conversation. If set + to `root`, the new item will be added to the beginning of the conversation. If + set to an existing ID, it allows an item to be inserted mid-conversation. If the + ID cannot be found, an error will be returned and the item will not be added. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..8530dc72cd81e71e5acb1d72bbc9313493256204 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_create_event_param.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .conversation_item_param import ConversationItemParam + +__all__ = ["ConversationItemCreateEventParam"] + + +class ConversationItemCreateEventParam(TypedDict, total=False): + item: Required[ConversationItemParam] + """A single item within a Realtime conversation.""" + + type: Required[Literal["conversation.item.create"]] + """The event type, must be `conversation.item.create`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" + + previous_item_id: str + """The ID of the preceding item after which the new item will be inserted. + + If not set, the new item will be appended to the end of the conversation. If set + to `root`, the new item will be added to the beginning of the conversation. If + set to an existing ID, it allows an item to be inserted mid-conversation. If the + ID cannot be found, an error will be returned and the item will not be added. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_created_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_created_event.py new file mode 100644 index 0000000000000000000000000000000000000000..13f24ad31a9204236a4633c34ff79d932c3448c1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_created_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ConversationItemCreatedEvent"] + + +class ConversationItemCreatedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + type: Literal["conversation.item.created"] + """The event type, must be `conversation.item.created`.""" + + previous_item_id: Optional[str] = None + """ + The ID of the preceding item in the Conversation context, allows the client to + understand the order of the conversation. Can be `null` if the item has no + predecessor. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event.py new file mode 100644 index 0000000000000000000000000000000000000000..3734f72e9dda28bf542e794069bdb44911a23f7e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemDeleteEvent"] + + +class ConversationItemDeleteEvent(BaseModel): + item_id: str + """The ID of the item to delete.""" + + type: Literal["conversation.item.delete"] + """The event type, must be `conversation.item.delete`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..c3f88d66277337fe1cb97223cde9d24e89dbce83 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_delete_event_param.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ConversationItemDeleteEventParam"] + + +class ConversationItemDeleteEventParam(TypedDict, total=False): + item_id: Required[str] + """The ID of the item to delete.""" + + type: Required[Literal["conversation.item.delete"]] + """The event type, must be `conversation.item.delete`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_deleted_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_deleted_event.py new file mode 100644 index 0000000000000000000000000000000000000000..cfe6fe85fc6d9641ca3df9194aacd86379fd6825 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_deleted_event.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemDeletedEvent"] + + +class ConversationItemDeletedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item that was deleted.""" + + type: Literal["conversation.item.deleted"] + """The event type, must be `conversation.item.deleted`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_done.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_done.py new file mode 100644 index 0000000000000000000000000000000000000000..a4c9b8a84097aa56df9c88ce05bcaf7e0b1b955f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_done.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ConversationItemDone"] + + +class ConversationItemDone(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + type: Literal["conversation.item.done"] + """The event type, must be `conversation.item.done`.""" + + previous_item_id: Optional[str] = None + """The ID of the item that precedes this one, if any. + + This is used to maintain ordering when items are inserted. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..09b20aa18418c67eb1c7acde716f60118825f817 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_completed_event.py @@ -0,0 +1,79 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .log_prob_properties import LogProbProperties + +__all__ = [ + "ConversationItemInputAudioTranscriptionCompletedEvent", + "Usage", + "UsageTranscriptTextUsageTokens", + "UsageTranscriptTextUsageTokensInputTokenDetails", + "UsageTranscriptTextUsageDuration", +] + + +class UsageTranscriptTextUsageTokensInputTokenDetails(BaseModel): + audio_tokens: Optional[int] = None + """Number of audio tokens billed for this request.""" + + text_tokens: Optional[int] = None + """Number of text tokens billed for this request.""" + + +class UsageTranscriptTextUsageTokens(BaseModel): + input_tokens: int + """Number of input tokens billed for this request.""" + + output_tokens: int + """Number of output tokens generated.""" + + total_tokens: int + """Total number of tokens used (input + output).""" + + type: Literal["tokens"] + """The type of the usage object. Always `tokens` for this variant.""" + + input_token_details: Optional[UsageTranscriptTextUsageTokensInputTokenDetails] = None + """Details about the input tokens billed for this request.""" + + +class UsageTranscriptTextUsageDuration(BaseModel): + seconds: float + """Duration of the input audio in seconds.""" + + type: Literal["duration"] + """The type of the usage object. Always `duration` for this variant.""" + + +Usage: TypeAlias = Union[UsageTranscriptTextUsageTokens, UsageTranscriptTextUsageDuration] + + +class ConversationItemInputAudioTranscriptionCompletedEvent(BaseModel): + content_index: int + """The index of the content part containing the audio.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item containing the audio that is being transcribed.""" + + transcript: str + """The transcribed text.""" + + type: Literal["conversation.item.input_audio_transcription.completed"] + """ + The event type, must be `conversation.item.input_audio_transcription.completed`. + """ + + usage: Usage + """ + Usage statistics for the transcription, this is billed according to the ASR + model's pricing rather than the realtime model's pricing. + """ + + logprobs: Optional[List[LogProbProperties]] = None + """The log probabilities of the transcription.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..f49e6f636fdcf6d1f2fa92759b77b12fe305c6b5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_delta_event.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .log_prob_properties import LogProbProperties + +__all__ = ["ConversationItemInputAudioTranscriptionDeltaEvent"] + + +class ConversationItemInputAudioTranscriptionDeltaEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item containing the audio that is being transcribed.""" + + type: Literal["conversation.item.input_audio_transcription.delta"] + """The event type, must be `conversation.item.input_audio_transcription.delta`.""" + + content_index: Optional[int] = None + """The index of the content part in the item's content array.""" + + delta: Optional[str] = None + """The text delta.""" + + logprobs: Optional[List[LogProbProperties]] = None + """The log probabilities of the transcription. + + These can be enabled by configurating the session with + `"include": ["item.input_audio_transcription.logprobs"]`. Each entry in the + array corresponds a log probability of which token would be selected for this + chunk of transcription. This can help to identify if it was possible there were + multiple valid options for a given chunk of transcription. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_failed_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_failed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..edb97bbf6f2a500c1f59b9a95b97f51dae203f97 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_failed_event.py @@ -0,0 +1,39 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemInputAudioTranscriptionFailedEvent", "Error"] + + +class Error(BaseModel): + code: Optional[str] = None + """Error code, if any.""" + + message: Optional[str] = None + """A human-readable error message.""" + + param: Optional[str] = None + """Parameter related to the error, if any.""" + + type: Optional[str] = None + """The type of error.""" + + +class ConversationItemInputAudioTranscriptionFailedEvent(BaseModel): + content_index: int + """The index of the content part containing the audio.""" + + error: Error + """Details of the transcription error.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the user message item.""" + + type: Literal["conversation.item.input_audio_transcription.failed"] + """The event type, must be `conversation.item.input_audio_transcription.failed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_segment.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_segment.py new file mode 100644 index 0000000000000000000000000000000000000000..e2cbc9d29997681e02f3ac4d4245d1ba465b3d89 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_input_audio_transcription_segment.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemInputAudioTranscriptionSegment"] + + +class ConversationItemInputAudioTranscriptionSegment(BaseModel): + id: str + """The segment identifier.""" + + content_index: int + """The index of the input audio content part within the item.""" + + end: float + """End time of the segment in seconds.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item containing the input audio content.""" + + speaker: str + """The detected speaker label for this segment.""" + + start: float + """Start time of the segment in seconds.""" + + text: str + """The text for this segment.""" + + type: Literal["conversation.item.input_audio_transcription.segment"] + """The event type, must be `conversation.item.input_audio_transcription.segment`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_param.py new file mode 100644 index 0000000000000000000000000000000000000000..c8b442ecaddef10088e7db8815de7d6c8fe8c9fc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_param.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from .realtime_mcp_tool_call_param import RealtimeMcpToolCallParam +from .realtime_mcp_list_tools_param import RealtimeMcpListToolsParam +from .realtime_mcp_approval_request_param import RealtimeMcpApprovalRequestParam +from .realtime_mcp_approval_response_param import RealtimeMcpApprovalResponseParam +from .realtime_conversation_item_user_message_param import RealtimeConversationItemUserMessageParam +from .realtime_conversation_item_function_call_param import RealtimeConversationItemFunctionCallParam +from .realtime_conversation_item_system_message_param import RealtimeConversationItemSystemMessageParam +from .realtime_conversation_item_assistant_message_param import RealtimeConversationItemAssistantMessageParam +from .realtime_conversation_item_function_call_output_param import RealtimeConversationItemFunctionCallOutputParam + +__all__ = ["ConversationItemParam"] + +ConversationItemParam: TypeAlias = Union[ + RealtimeConversationItemSystemMessageParam, + RealtimeConversationItemUserMessageParam, + RealtimeConversationItemAssistantMessageParam, + RealtimeConversationItemFunctionCallParam, + RealtimeConversationItemFunctionCallOutputParam, + RealtimeMcpApprovalResponseParam, + RealtimeMcpListToolsParam, + RealtimeMcpToolCallParam, + RealtimeMcpApprovalRequestParam, +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event.py new file mode 100644 index 0000000000000000000000000000000000000000..018c2ccc5924dcf81fe7b8cf26ff4fa73cef2d51 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemRetrieveEvent"] + + +class ConversationItemRetrieveEvent(BaseModel): + item_id: str + """The ID of the item to retrieve.""" + + type: Literal["conversation.item.retrieve"] + """The event type, must be `conversation.item.retrieve`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..71b3ffa499e323b9aca3c2c92c26648e0bff1cf9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_retrieve_event_param.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ConversationItemRetrieveEventParam"] + + +class ConversationItemRetrieveEventParam(TypedDict, total=False): + item_id: Required[str] + """The ID of the item to retrieve.""" + + type: Required[Literal["conversation.item.retrieve"]] + """The event type, must be `conversation.item.retrieve`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event.py new file mode 100644 index 0000000000000000000000000000000000000000..d6c6779cc83cf775902720b063d802a7fd00a122 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemTruncateEvent"] + + +class ConversationItemTruncateEvent(BaseModel): + audio_end_ms: int + """Inclusive duration up to which audio is truncated, in milliseconds. + + If the audio_end_ms is greater than the actual audio duration, the server will + respond with an error. + """ + + content_index: int + """The index of the content part to truncate. Set this to `0`.""" + + item_id: str + """The ID of the assistant message item to truncate. + + Only assistant message items can be truncated. + """ + + type: Literal["conversation.item.truncate"] + """The event type, must be `conversation.item.truncate`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f5ab13a419ed6f03568f1150eb683c1e8ec5bd8f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncate_event_param.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ConversationItemTruncateEventParam"] + + +class ConversationItemTruncateEventParam(TypedDict, total=False): + audio_end_ms: Required[int] + """Inclusive duration up to which audio is truncated, in milliseconds. + + If the audio_end_ms is greater than the actual audio duration, the server will + respond with an error. + """ + + content_index: Required[int] + """The index of the content part to truncate. Set this to `0`.""" + + item_id: Required[str] + """The ID of the assistant message item to truncate. + + Only assistant message items can be truncated. + """ + + type: Required[Literal["conversation.item.truncate"]] + """The event type, must be `conversation.item.truncate`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncated_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncated_event.py new file mode 100644 index 0000000000000000000000000000000000000000..f56cabc3d901e1773d121dfd1b169a916ca1016e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/conversation_item_truncated_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ConversationItemTruncatedEvent"] + + +class ConversationItemTruncatedEvent(BaseModel): + audio_end_ms: int + """The duration up to which the audio was truncated, in milliseconds.""" + + content_index: int + """The index of the content part that was truncated.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the assistant message item that was truncated.""" + + type: Literal["conversation.item.truncated"] + """The event type, must be `conversation.item.truncated`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event.py new file mode 100644 index 0000000000000000000000000000000000000000..8562cf0af4dc9fd91e9fdb09e865b7d02f4821d9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferAppendEvent"] + + +class InputAudioBufferAppendEvent(BaseModel): + audio: str + """Base64-encoded audio bytes. + + This must be in the format specified by the `input_audio_format` field in the + session configuration. + """ + + type: Literal["input_audio_buffer.append"] + """The event type, must be `input_audio_buffer.append`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..3ad0bc737d13a24f168c73ed149fe65595e6f5e5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_append_event_param.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["InputAudioBufferAppendEventParam"] + + +class InputAudioBufferAppendEventParam(TypedDict, total=False): + audio: Required[str] + """Base64-encoded audio bytes. + + This must be in the format specified by the `input_audio_format` field in the + session configuration. + """ + + type: Required[Literal["input_audio_buffer.append"]] + """The event type, must be `input_audio_buffer.append`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event.py new file mode 100644 index 0000000000000000000000000000000000000000..9922ff3b32c0797a37d6fec015cd2962dae2442c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferClearEvent"] + + +class InputAudioBufferClearEvent(BaseModel): + type: Literal["input_audio_buffer.clear"] + """The event type, must be `input_audio_buffer.clear`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..2bd6bc5a02c18d705d8cc9a8fc8801d98352de35 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_clear_event_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["InputAudioBufferClearEventParam"] + + +class InputAudioBufferClearEventParam(TypedDict, total=False): + type: Required[Literal["input_audio_buffer.clear"]] + """The event type, must be `input_audio_buffer.clear`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_cleared_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_cleared_event.py new file mode 100644 index 0000000000000000000000000000000000000000..af71844f2f7a00df1e62c02230003cdb97ce6a9b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_cleared_event.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferClearedEvent"] + + +class InputAudioBufferClearedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + type: Literal["input_audio_buffer.cleared"] + """The event type, must be `input_audio_buffer.cleared`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event.py new file mode 100644 index 0000000000000000000000000000000000000000..125c3ba1e8dcb0f714eaa8f435b9b9fd30f4c261 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferCommitEvent"] + + +class InputAudioBufferCommitEvent(BaseModel): + type: Literal["input_audio_buffer.commit"] + """The event type, must be `input_audio_buffer.commit`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..c9c927ab98b44782a262e95c695fab002c502c7a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_commit_event_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["InputAudioBufferCommitEventParam"] + + +class InputAudioBufferCommitEventParam(TypedDict, total=False): + type: Required[Literal["input_audio_buffer.commit"]] + """The event type, must be `input_audio_buffer.commit`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_committed_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_committed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..5ed1b4ccc71c3268353df226b85efaac8e35cc6b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_committed_event.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferCommittedEvent"] + + +class InputAudioBufferCommittedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the user message item that will be created.""" + + type: Literal["input_audio_buffer.committed"] + """The event type, must be `input_audio_buffer.committed`.""" + + previous_item_id: Optional[str] = None + """ + The ID of the preceding item after which the new item will be inserted. Can be + `null` if the item has no predecessor. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_started_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_started_event.py new file mode 100644 index 0000000000000000000000000000000000000000..865205d786bdeff3903ae033c4179c84e48a2d2f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_started_event.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferSpeechStartedEvent"] + + +class InputAudioBufferSpeechStartedEvent(BaseModel): + audio_start_ms: int + """ + Milliseconds from the start of all audio written to the buffer during the + session when speech was first detected. This will correspond to the beginning of + audio sent to the model, and thus includes the `prefix_padding_ms` configured in + the Session. + """ + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the user message item that will be created when speech stops.""" + + type: Literal["input_audio_buffer.speech_started"] + """The event type, must be `input_audio_buffer.speech_started`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_stopped_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_stopped_event.py new file mode 100644 index 0000000000000000000000000000000000000000..6cb7845ff44191705e9a25c8f15f8a9100da9da6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_speech_stopped_event.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferSpeechStoppedEvent"] + + +class InputAudioBufferSpeechStoppedEvent(BaseModel): + audio_end_ms: int + """Milliseconds since the session started when speech stopped. + + This will correspond to the end of audio sent to the model, and thus includes + the `min_silence_duration_ms` configured in the Session. + """ + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the user message item that will be created.""" + + type: Literal["input_audio_buffer.speech_stopped"] + """The event type, must be `input_audio_buffer.speech_stopped`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_timeout_triggered.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_timeout_triggered.py new file mode 100644 index 0000000000000000000000000000000000000000..5c5dc5cfa6c32aacaec92a157a3fa6949df8c0bb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/input_audio_buffer_timeout_triggered.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["InputAudioBufferTimeoutTriggered"] + + +class InputAudioBufferTimeoutTriggered(BaseModel): + audio_end_ms: int + """ + Millisecond offset of audio written to the input audio buffer at the time the + timeout was triggered. + """ + + audio_start_ms: int + """ + Millisecond offset of audio written to the input audio buffer that was after the + playback time of the last model response. + """ + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item associated with this segment.""" + + type: Literal["input_audio_buffer.timeout_triggered"] + """The event type, must be `input_audio_buffer.timeout_triggered`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/log_prob_properties.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/log_prob_properties.py new file mode 100644 index 0000000000000000000000000000000000000000..92477d67d004572834facdd911191d27337f3da6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/log_prob_properties.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List + +from ..._models import BaseModel + +__all__ = ["LogProbProperties"] + + +class LogProbProperties(BaseModel): + token: str + """The token that was used to generate the log probability.""" + + bytes: List[int] + """The bytes that were used to generate the log probability.""" + + logprob: float + """The log probability of the token.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_completed.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_completed.py new file mode 100644 index 0000000000000000000000000000000000000000..941280f01aad7811bff455d8e0177a0c7fa18ffd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_completed.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["McpListToolsCompleted"] + + +class McpListToolsCompleted(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP list tools item.""" + + type: Literal["mcp_list_tools.completed"] + """The event type, must be `mcp_list_tools.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_failed.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_failed.py new file mode 100644 index 0000000000000000000000000000000000000000..892eda21bd11c07a8a16e38011e0c553c10c0d81 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_failed.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["McpListToolsFailed"] + + +class McpListToolsFailed(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP list tools item.""" + + type: Literal["mcp_list_tools.failed"] + """The event type, must be `mcp_list_tools.failed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_in_progress.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_in_progress.py new file mode 100644 index 0000000000000000000000000000000000000000..4254b5fd332940f0bb76950271e67e51ac9112aa --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/mcp_list_tools_in_progress.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["McpListToolsInProgress"] + + +class McpListToolsInProgress(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP list tools item.""" + + type: Literal["mcp_list_tools.in_progress"] + """The event type, must be `mcp_list_tools.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/noise_reduction_type.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/noise_reduction_type.py new file mode 100644 index 0000000000000000000000000000000000000000..f4338991bbc38b2a50744673da2f0e238c7d5472 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/noise_reduction_type.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["NoiseReductionType"] + +NoiseReductionType: TypeAlias = Literal["near_field", "far_field"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b4c95039f3764181154be4ddd754d3e0b9fe2db6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["OutputAudioBufferClearEvent"] + + +class OutputAudioBufferClearEvent(BaseModel): + type: Literal["output_audio_buffer.clear"] + """The event type, must be `output_audio_buffer.clear`.""" + + event_id: Optional[str] = None + """The unique ID of the client event used for error handling.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..a3205ebc6cc6fafb6eafb9bef980a0da9d4da9ea --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/output_audio_buffer_clear_event_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["OutputAudioBufferClearEventParam"] + + +class OutputAudioBufferClearEventParam(TypedDict, total=False): + type: Required[Literal["output_audio_buffer.clear"]] + """The event type, must be `output_audio_buffer.clear`.""" + + event_id: str + """The unique ID of the client event used for error handling.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/rate_limits_updated_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/rate_limits_updated_event.py new file mode 100644 index 0000000000000000000000000000000000000000..048a4028a1b4613bc00d0399e4638fa1fabcff0d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/rate_limits_updated_event.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RateLimitsUpdatedEvent", "RateLimit"] + + +class RateLimit(BaseModel): + limit: Optional[int] = None + """The maximum allowed value for the rate limit.""" + + name: Optional[Literal["requests", "tokens"]] = None + """The name of the rate limit (`requests`, `tokens`).""" + + remaining: Optional[int] = None + """The remaining value before the limit is reached.""" + + reset_seconds: Optional[float] = None + """Seconds until the rate limit resets.""" + + +class RateLimitsUpdatedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + rate_limits: List[RateLimit] + """List of rate limit information.""" + + type: Literal["rate_limits.updated"] + """The event type, must be `rate_limits.updated`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config.py new file mode 100644 index 0000000000000000000000000000000000000000..72d7cc59cca27a188f20f909675c9c9c9886281e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .realtime_audio_config_input import RealtimeAudioConfigInput +from .realtime_audio_config_output import RealtimeAudioConfigOutput + +__all__ = ["RealtimeAudioConfig"] + + +class RealtimeAudioConfig(BaseModel): + input: Optional[RealtimeAudioConfigInput] = None + + output: Optional[RealtimeAudioConfigOutput] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input.py new file mode 100644 index 0000000000000000000000000000000000000000..cfcb7f22d43aef24435ab6aadbb32017a5d9e92d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input.py @@ -0,0 +1,63 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .audio_transcription import AudioTranscription +from .noise_reduction_type import NoiseReductionType +from .realtime_audio_formats import RealtimeAudioFormats +from .realtime_audio_input_turn_detection import RealtimeAudioInputTurnDetection + +__all__ = ["RealtimeAudioConfigInput", "NoiseReduction"] + + +class NoiseReduction(BaseModel): + type: Optional[NoiseReductionType] = None + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class RealtimeAudioConfigInput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the input audio.""" + + noise_reduction: Optional[NoiseReduction] = None + """Configuration for input audio noise reduction. + + This can be set to `null` to turn off. Noise reduction filters audio added to + the input audio buffer before it is sent to VAD and the model. Filtering the + audio can improve VAD and turn detection accuracy (reducing false positives) and + model performance by improving perception of the input audio. + """ + + transcription: Optional[AudioTranscription] = None + """ + Configuration for input audio transcription, defaults to off and can be set to + `null` to turn off once on. Input audio transcription is not native to the + model, since the model consumes audio directly. Transcription runs + asynchronously through + [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as guidance of input audio content rather than precisely + what the model heard. The client can optionally set the language and prompt for + transcription, these offer additional guidance to the transcription service. + """ + + turn_detection: Optional[RealtimeAudioInputTurnDetection] = None + """Configuration for turn detection, ether Server VAD or Semantic VAD. + + This can be set to `null` to turn off, in which case the client must manually + trigger model response. + + Server VAD means that the model will detect the start and end of speech based on + audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in conjunction + with VAD) to semantically estimate whether the user has finished speaking, then + dynamically sets a timeout based on this probability. For example, if user audio + trails off with "uhhm", the model will score a low probability of turn end and + wait longer for the user to continue speaking. This can be useful for more + natural conversations, but may have a higher latency. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..730f46cfec8a168ca9849ca747d0ab68af5d6130 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_input_param.py @@ -0,0 +1,65 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import TypedDict + +from .noise_reduction_type import NoiseReductionType +from .audio_transcription_param import AudioTranscriptionParam +from .realtime_audio_formats_param import RealtimeAudioFormatsParam +from .realtime_audio_input_turn_detection_param import RealtimeAudioInputTurnDetectionParam + +__all__ = ["RealtimeAudioConfigInputParam", "NoiseReduction"] + + +class NoiseReduction(TypedDict, total=False): + type: NoiseReductionType + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class RealtimeAudioConfigInputParam(TypedDict, total=False): + format: RealtimeAudioFormatsParam + """The format of the input audio.""" + + noise_reduction: NoiseReduction + """Configuration for input audio noise reduction. + + This can be set to `null` to turn off. Noise reduction filters audio added to + the input audio buffer before it is sent to VAD and the model. Filtering the + audio can improve VAD and turn detection accuracy (reducing false positives) and + model performance by improving perception of the input audio. + """ + + transcription: AudioTranscriptionParam + """ + Configuration for input audio transcription, defaults to off and can be set to + `null` to turn off once on. Input audio transcription is not native to the + model, since the model consumes audio directly. Transcription runs + asynchronously through + [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as guidance of input audio content rather than precisely + what the model heard. The client can optionally set the language and prompt for + transcription, these offer additional guidance to the transcription service. + """ + + turn_detection: Optional[RealtimeAudioInputTurnDetectionParam] + """Configuration for turn detection, ether Server VAD or Semantic VAD. + + This can be set to `null` to turn off, in which case the client must manually + trigger model response. + + Server VAD means that the model will detect the start and end of speech based on + audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in conjunction + with VAD) to semantically estimate whether the user has finished speaking, then + dynamically sets a timeout based on this probability. For example, if user audio + trails off with "uhhm", the model will score a low probability of turn end and + wait longer for the user to continue speaking. This can be useful for more + natural conversations, but may have a higher latency. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output.py new file mode 100644 index 0000000000000000000000000000000000000000..a8af237c1d0af1e745bfc42da2aa56c1db27716f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_audio_formats import RealtimeAudioFormats + +__all__ = ["RealtimeAudioConfigOutput"] + + +class RealtimeAudioConfigOutput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the output audio.""" + + speed: Optional[float] = None + """ + The speed of the model's spoken response as a multiple of the original speed. + 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. + This value can only be changed in between model turns, not while a response is + in progress. + + This parameter is a post-processing adjustment to the audio after it is + generated, it's also possible to prompt the model to speak faster or slower. + """ + + voice: Union[ + str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"], None + ] = None + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output_param.py new file mode 100644 index 0000000000000000000000000000000000000000..8e887d3464b29f2f132c407b1b3c62969b6de35e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_output_param.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypedDict + +from .realtime_audio_formats_param import RealtimeAudioFormatsParam + +__all__ = ["RealtimeAudioConfigOutputParam"] + + +class RealtimeAudioConfigOutputParam(TypedDict, total=False): + format: RealtimeAudioFormatsParam + """The format of the output audio.""" + + speed: float + """ + The speed of the model's spoken response as a multiple of the original speed. + 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. + This value can only be changed in between model turns, not while a response is + in progress. + + This parameter is a post-processing adjustment to the audio after it is + generated, it's also possible to prompt the model to speak faster or slower. + """ + + voice: Union[str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"]] + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..2c41de35aee4b658902ca2868b2f1f98d18aff79 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_config_param.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +from .realtime_audio_config_input_param import RealtimeAudioConfigInputParam +from .realtime_audio_config_output_param import RealtimeAudioConfigOutputParam + +__all__ = ["RealtimeAudioConfigParam"] + + +class RealtimeAudioConfigParam(TypedDict, total=False): + input: RealtimeAudioConfigInputParam + + output: RealtimeAudioConfigOutputParam diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats.py new file mode 100644 index 0000000000000000000000000000000000000000..10f91883b6328acf273a398196c488ca7588639a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["RealtimeAudioFormats", "AudioPCM", "AudioPCMU", "AudioPCMA"] + + +class AudioPCM(BaseModel): + rate: Optional[Literal[24000]] = None + """The sample rate of the audio. Always `24000`.""" + + type: Optional[Literal["audio/pcm"]] = None + """The audio format. Always `audio/pcm`.""" + + +class AudioPCMU(BaseModel): + type: Optional[Literal["audio/pcmu"]] = None + """The audio format. Always `audio/pcmu`.""" + + +class AudioPCMA(BaseModel): + type: Optional[Literal["audio/pcma"]] = None + """The audio format. Always `audio/pcma`.""" + + +RealtimeAudioFormats: TypeAlias = Annotated[Union[AudioPCM, AudioPCMU, AudioPCMA], PropertyInfo(discriminator="type")] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats_param.py new file mode 100644 index 0000000000000000000000000000000000000000..cf58577f38361f694b7e95e760b0609610ce0796 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_formats_param.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypeAlias, TypedDict + +__all__ = ["RealtimeAudioFormatsParam", "AudioPCM", "AudioPCMU", "AudioPCMA"] + + +class AudioPCM(TypedDict, total=False): + rate: Literal[24000] + """The sample rate of the audio. Always `24000`.""" + + type: Literal["audio/pcm"] + """The audio format. Always `audio/pcm`.""" + + +class AudioPCMU(TypedDict, total=False): + type: Literal["audio/pcmu"] + """The audio format. Always `audio/pcmu`.""" + + +class AudioPCMA(TypedDict, total=False): + type: Literal["audio/pcma"] + """The audio format. Always `audio/pcma`.""" + + +RealtimeAudioFormatsParam: TypeAlias = Union[AudioPCM, AudioPCMU, AudioPCMA] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection.py new file mode 100644 index 0000000000000000000000000000000000000000..d3f4e003167c2121482f1f68195fc44d427f8cf1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection.py @@ -0,0 +1,98 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["RealtimeAudioInputTurnDetection", "ServerVad", "SemanticVad"] + + +class ServerVad(BaseModel): + type: Literal["server_vad"] + """Type of turn detection, `server_vad` to turn on simple Server VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + idle_timeout_ms: Optional[int] = None + """Optional timeout after which a model response will be triggered automatically. + + This is useful for situations in which a long pause from the user is unexpected, + such as a phone call. The model will effectively prompt the user to continue the + conversation based on the current context. + + The timeout value will be applied after the last model response's audio has + finished playing, i.e. it's set to the `response.done` time plus audio playback + duration. + + An `input_audio_buffer.timeout_triggered` event (plus events associated with the + Response) will be emitted when the timeout is reached. Idle timeout is currently + only supported for `server_vad` mode. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + prefix_padding_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Amount of audio to include before the VAD detected speech (in milliseconds). + Defaults to 300ms. + """ + + silence_duration_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. + With shorter values the model will respond more quickly, but may jump in on + short pauses from the user. + """ + + threshold: Optional[float] = None + """Used only for `server_vad` mode. + + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher + threshold will require louder audio to activate the model, and thus might + perform better in noisy environments. + """ + + +class SemanticVad(BaseModel): + type: Literal["semantic_vad"] + """Type of turn detection, `semantic_vad` to turn on Semantic VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + eagerness: Optional[Literal["low", "medium", "high", "auto"]] = None + """Used only for `semantic_vad` mode. + + The eagerness of the model to respond. `low` will wait longer for the user to + continue speaking, `high` will respond more quickly. `auto` is the default and + is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, + 4s, and 2s respectively. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + +RealtimeAudioInputTurnDetection: TypeAlias = Annotated[ + Union[ServerVad, SemanticVad, None], PropertyInfo(discriminator="type") +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection_param.py new file mode 100644 index 0000000000000000000000000000000000000000..09b8cfd15944db040763bc6a950db6499ae8dc8c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_audio_input_turn_detection_param.py @@ -0,0 +1,95 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = ["RealtimeAudioInputTurnDetectionParam", "ServerVad", "SemanticVad"] + + +class ServerVad(TypedDict, total=False): + type: Required[Literal["server_vad"]] + """Type of turn detection, `server_vad` to turn on simple Server VAD.""" + + create_response: bool + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + idle_timeout_ms: Optional[int] + """Optional timeout after which a model response will be triggered automatically. + + This is useful for situations in which a long pause from the user is unexpected, + such as a phone call. The model will effectively prompt the user to continue the + conversation based on the current context. + + The timeout value will be applied after the last model response's audio has + finished playing, i.e. it's set to the `response.done` time plus audio playback + duration. + + An `input_audio_buffer.timeout_triggered` event (plus events associated with the + Response) will be emitted when the timeout is reached. Idle timeout is currently + only supported for `server_vad` mode. + """ + + interrupt_response: bool + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + prefix_padding_ms: int + """Used only for `server_vad` mode. + + Amount of audio to include before the VAD detected speech (in milliseconds). + Defaults to 300ms. + """ + + silence_duration_ms: int + """Used only for `server_vad` mode. + + Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. + With shorter values the model will respond more quickly, but may jump in on + short pauses from the user. + """ + + threshold: float + """Used only for `server_vad` mode. + + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher + threshold will require louder audio to activate the model, and thus might + perform better in noisy environments. + """ + + +class SemanticVad(TypedDict, total=False): + type: Required[Literal["semantic_vad"]] + """Type of turn detection, `semantic_vad` to turn on Semantic VAD.""" + + create_response: bool + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + eagerness: Literal["low", "medium", "high", "auto"] + """Used only for `semantic_vad` mode. + + The eagerness of the model to respond. `low` will wait longer for the user to + continue speaking, `high` will respond more quickly. `auto` is the default and + is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, + 4s, and 2s respectively. + """ + + interrupt_response: bool + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + +RealtimeAudioInputTurnDetectionParam: TypeAlias = Union[ServerVad, SemanticVad] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event.py new file mode 100644 index 0000000000000000000000000000000000000000..3b1c348daa213a3664d00d651c30457402f17591 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .session_update_event import SessionUpdateEvent +from .response_cancel_event import ResponseCancelEvent +from .response_create_event import ResponseCreateEvent +from .conversation_item_create_event import ConversationItemCreateEvent +from .conversation_item_delete_event import ConversationItemDeleteEvent +from .input_audio_buffer_clear_event import InputAudioBufferClearEvent +from .input_audio_buffer_append_event import InputAudioBufferAppendEvent +from .input_audio_buffer_commit_event import InputAudioBufferCommitEvent +from .output_audio_buffer_clear_event import OutputAudioBufferClearEvent +from .conversation_item_retrieve_event import ConversationItemRetrieveEvent +from .conversation_item_truncate_event import ConversationItemTruncateEvent + +__all__ = ["RealtimeClientEvent"] + +RealtimeClientEvent: TypeAlias = Annotated[ + Union[ + ConversationItemCreateEvent, + ConversationItemDeleteEvent, + ConversationItemRetrieveEvent, + ConversationItemTruncateEvent, + InputAudioBufferAppendEvent, + InputAudioBufferClearEvent, + OutputAudioBufferClearEvent, + InputAudioBufferCommitEvent, + ResponseCancelEvent, + ResponseCreateEvent, + SessionUpdateEvent, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..cda5766e2a443f1308cdb2b791ab4f6cea94ef94 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_client_event_param.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from .session_update_event_param import SessionUpdateEventParam +from .response_cancel_event_param import ResponseCancelEventParam +from .response_create_event_param import ResponseCreateEventParam +from .conversation_item_create_event_param import ConversationItemCreateEventParam +from .conversation_item_delete_event_param import ConversationItemDeleteEventParam +from .input_audio_buffer_clear_event_param import InputAudioBufferClearEventParam +from .input_audio_buffer_append_event_param import InputAudioBufferAppendEventParam +from .input_audio_buffer_commit_event_param import InputAudioBufferCommitEventParam +from .output_audio_buffer_clear_event_param import OutputAudioBufferClearEventParam +from .conversation_item_retrieve_event_param import ConversationItemRetrieveEventParam +from .conversation_item_truncate_event_param import ConversationItemTruncateEventParam + +__all__ = ["RealtimeClientEventParam"] + +RealtimeClientEventParam: TypeAlias = Union[ + ConversationItemCreateEventParam, + ConversationItemDeleteEventParam, + ConversationItemRetrieveEventParam, + ConversationItemTruncateEventParam, + InputAudioBufferAppendEventParam, + InputAudioBufferClearEventParam, + OutputAudioBufferClearEventParam, + InputAudioBufferCommitEventParam, + ResponseCancelEventParam, + ResponseCreateEventParam, + SessionUpdateEventParam, +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_connect_params.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_connect_params.py new file mode 100644 index 0000000000000000000000000000000000000000..76474f3de4c0bea69e25ae92675f79e127c0c134 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_connect_params.py @@ -0,0 +1,11 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +__all__ = ["RealtimeConnectParams"] + + +class RealtimeConnectParams(TypedDict, total=False): + model: Required[str] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message.py new file mode 100644 index 0000000000000000000000000000000000000000..6b0f86ee324b18e43f0f07a899919da4da29d365 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message.py @@ -0,0 +1,58 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeConversationItemAssistantMessage", "Content"] + + +class Content(BaseModel): + audio: Optional[str] = None + """ + Base64-encoded audio bytes, these will be parsed as the format specified in the + session output audio type configuration. This defaults to PCM 16-bit 24kHz mono + if not specified. + """ + + text: Optional[str] = None + """The text content.""" + + transcript: Optional[str] = None + """ + The transcript of the audio content, this will always be present if the output + type is `audio`. + """ + + type: Optional[Literal["output_text", "output_audio"]] = None + """ + The content type, `output_text` or `output_audio` depending on the session + `output_modalities` configuration. + """ + + +class RealtimeConversationItemAssistantMessage(BaseModel): + content: List[Content] + """The content of the message.""" + + role: Literal["assistant"] + """The role of the message sender. Always `assistant`.""" + + type: Literal["message"] + """The type of the item. Always `message`.""" + + id: Optional[str] = None + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Optional[Literal["realtime.item"]] = None + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Optional[Literal["completed", "incomplete", "in_progress"]] = None + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message_param.py new file mode 100644 index 0000000000000000000000000000000000000000..93699afba29196cc3bcecb8e057046360ec3bbd9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_assistant_message_param.py @@ -0,0 +1,58 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Iterable +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeConversationItemAssistantMessageParam", "Content"] + + +class Content(TypedDict, total=False): + audio: str + """ + Base64-encoded audio bytes, these will be parsed as the format specified in the + session output audio type configuration. This defaults to PCM 16-bit 24kHz mono + if not specified. + """ + + text: str + """The text content.""" + + transcript: str + """ + The transcript of the audio content, this will always be present if the output + type is `audio`. + """ + + type: Literal["output_text", "output_audio"] + """ + The content type, `output_text` or `output_audio` depending on the session + `output_modalities` configuration. + """ + + +class RealtimeConversationItemAssistantMessageParam(TypedDict, total=False): + content: Required[Iterable[Content]] + """The content of the message.""" + + role: Required[Literal["assistant"]] + """The role of the message sender. Always `assistant`.""" + + type: Required[Literal["message"]] + """The type of the item. Always `message`.""" + + id: str + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Literal["realtime.item"] + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Literal["completed", "incomplete", "in_progress"] + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call.py new file mode 100644 index 0000000000000000000000000000000000000000..279a2fcdc5a7f3ba66ba1aecdafac233f9b8f370 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call.py @@ -0,0 +1,41 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeConversationItemFunctionCall"] + + +class RealtimeConversationItemFunctionCall(BaseModel): + arguments: str + """The arguments of the function call. + + This is a JSON-encoded string representing the arguments passed to the function, + for example `{"arg1": "value1", "arg2": 42}`. + """ + + name: str + """The name of the function being called.""" + + type: Literal["function_call"] + """The type of the item. Always `function_call`.""" + + id: Optional[str] = None + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + call_id: Optional[str] = None + """The ID of the function call.""" + + object: Optional[Literal["realtime.item"]] = None + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Optional[Literal["completed", "incomplete", "in_progress"]] = None + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output.py new file mode 100644 index 0000000000000000000000000000000000000000..4b6b15d0ad63f00ea622b1864c6a107f6c436020 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output.py @@ -0,0 +1,37 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeConversationItemFunctionCallOutput"] + + +class RealtimeConversationItemFunctionCallOutput(BaseModel): + call_id: str + """The ID of the function call this output is for.""" + + output: str + """ + The output of the function call, this is free text and can contain any + information or simply be empty. + """ + + type: Literal["function_call_output"] + """The type of the item. Always `function_call_output`.""" + + id: Optional[str] = None + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Optional[Literal["realtime.item"]] = None + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Optional[Literal["completed", "incomplete", "in_progress"]] = None + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output_param.py new file mode 100644 index 0000000000000000000000000000000000000000..56d62da5636d890c3070b25303966c650498c8d2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_output_param.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeConversationItemFunctionCallOutputParam"] + + +class RealtimeConversationItemFunctionCallOutputParam(TypedDict, total=False): + call_id: Required[str] + """The ID of the function call this output is for.""" + + output: Required[str] + """ + The output of the function call, this is free text and can contain any + information or simply be empty. + """ + + type: Required[Literal["function_call_output"]] + """The type of the item. Always `function_call_output`.""" + + id: str + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Literal["realtime.item"] + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Literal["completed", "incomplete", "in_progress"] + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..36a16a27b39bdbcc7a87a4a55d616a2e5728eb13 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_function_call_param.py @@ -0,0 +1,40 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeConversationItemFunctionCallParam"] + + +class RealtimeConversationItemFunctionCallParam(TypedDict, total=False): + arguments: Required[str] + """The arguments of the function call. + + This is a JSON-encoded string representing the arguments passed to the function, + for example `{"arg1": "value1", "arg2": 42}`. + """ + + name: Required[str] + """The name of the function being called.""" + + type: Required[Literal["function_call"]] + """The type of the item. Always `function_call`.""" + + id: str + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + call_id: str + """The ID of the function call.""" + + object: Literal["realtime.item"] + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Literal["completed", "incomplete", "in_progress"] + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message.py new file mode 100644 index 0000000000000000000000000000000000000000..7dac5c9fe2c2747d1992f5260561b76ed0a6e98c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeConversationItemSystemMessage", "Content"] + + +class Content(BaseModel): + text: Optional[str] = None + """The text content.""" + + type: Optional[Literal["input_text"]] = None + """The content type. Always `input_text` for system messages.""" + + +class RealtimeConversationItemSystemMessage(BaseModel): + content: List[Content] + """The content of the message.""" + + role: Literal["system"] + """The role of the message sender. Always `system`.""" + + type: Literal["message"] + """The type of the item. Always `message`.""" + + id: Optional[str] = None + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Optional[Literal["realtime.item"]] = None + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Optional[Literal["completed", "incomplete", "in_progress"]] = None + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message_param.py new file mode 100644 index 0000000000000000000000000000000000000000..a2790fcf6787a04248f7be0156d3d970b1a17f34 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_system_message_param.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Iterable +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeConversationItemSystemMessageParam", "Content"] + + +class Content(TypedDict, total=False): + text: str + """The text content.""" + + type: Literal["input_text"] + """The content type. Always `input_text` for system messages.""" + + +class RealtimeConversationItemSystemMessageParam(TypedDict, total=False): + content: Required[Iterable[Content]] + """The content of the message.""" + + role: Required[Literal["system"]] + """The role of the message sender. Always `system`.""" + + type: Required[Literal["message"]] + """The type of the item. Always `message`.""" + + id: str + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Literal["realtime.item"] + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Literal["completed", "incomplete", "in_progress"] + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message.py new file mode 100644 index 0000000000000000000000000000000000000000..30d9bb10e3081ba7e188d954d1727f4c8858d115 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message.py @@ -0,0 +1,69 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeConversationItemUserMessage", "Content"] + + +class Content(BaseModel): + audio: Optional[str] = None + """ + Base64-encoded audio bytes (for `input_audio`), these will be parsed as the + format specified in the session input audio type configuration. This defaults to + PCM 16-bit 24kHz mono if not specified. + """ + + detail: Optional[Literal["auto", "low", "high"]] = None + """The detail level of the image (for `input_image`). + + `auto` will default to `high`. + """ + + image_url: Optional[str] = None + """Base64-encoded image bytes (for `input_image`) as a data URI. + + For example `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...`. Supported + formats are PNG and JPEG. + """ + + text: Optional[str] = None + """The text content (for `input_text`).""" + + transcript: Optional[str] = None + """Transcript of the audio (for `input_audio`). + + This is not sent to the model, but will be attached to the message item for + reference. + """ + + type: Optional[Literal["input_text", "input_audio", "input_image"]] = None + """The content type (`input_text`, `input_audio`, or `input_image`).""" + + +class RealtimeConversationItemUserMessage(BaseModel): + content: List[Content] + """The content of the message.""" + + role: Literal["user"] + """The role of the message sender. Always `user`.""" + + type: Literal["message"] + """The type of the item. Always `message`.""" + + id: Optional[str] = None + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Optional[Literal["realtime.item"]] = None + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Optional[Literal["completed", "incomplete", "in_progress"]] = None + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message_param.py new file mode 100644 index 0000000000000000000000000000000000000000..7d3b9bc1374de3f5374463746c49a0ec500efa71 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_conversation_item_user_message_param.py @@ -0,0 +1,69 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Iterable +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeConversationItemUserMessageParam", "Content"] + + +class Content(TypedDict, total=False): + audio: str + """ + Base64-encoded audio bytes (for `input_audio`), these will be parsed as the + format specified in the session input audio type configuration. This defaults to + PCM 16-bit 24kHz mono if not specified. + """ + + detail: Literal["auto", "low", "high"] + """The detail level of the image (for `input_image`). + + `auto` will default to `high`. + """ + + image_url: str + """Base64-encoded image bytes (for `input_image`) as a data URI. + + For example `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAA...`. Supported + formats are PNG and JPEG. + """ + + text: str + """The text content (for `input_text`).""" + + transcript: str + """Transcript of the audio (for `input_audio`). + + This is not sent to the model, but will be attached to the message item for + reference. + """ + + type: Literal["input_text", "input_audio", "input_image"] + """The content type (`input_text`, `input_audio`, or `input_image`).""" + + +class RealtimeConversationItemUserMessageParam(TypedDict, total=False): + content: Required[Iterable[Content]] + """The content of the message.""" + + role: Required[Literal["user"]] + """The role of the message sender. Always `user`.""" + + type: Required[Literal["message"]] + """The type of the item. Always `message`.""" + + id: str + """The unique ID of the item. + + This may be provided by the client or generated by the server. + """ + + object: Literal["realtime.item"] + """Identifier for the API object being returned - always `realtime.item`. + + Optional when creating a new item. + """ + + status: Literal["completed", "incomplete", "in_progress"] + """The status of the item. Has no effect on the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error.py new file mode 100644 index 0000000000000000000000000000000000000000..f1017d09e48cef25329e8565bece3bd9a1d3c7ad --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["RealtimeError"] + + +class RealtimeError(BaseModel): + message: str + """A human-readable error message.""" + + type: str + """The type of error (e.g., "invalid_request_error", "server_error").""" + + code: Optional[str] = None + """Error code, if any.""" + + event_id: Optional[str] = None + """The event_id of the client event that caused the error, if applicable.""" + + param: Optional[str] = None + """Parameter related to the error, if any.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error_event.py new file mode 100644 index 0000000000000000000000000000000000000000..8b501d6b218c7aab5b595451b8da0a05945a3198 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_error_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_error import RealtimeError + +__all__ = ["RealtimeErrorEvent"] + + +class RealtimeErrorEvent(BaseModel): + error: RealtimeError + """Details of the error.""" + + event_id: str + """The unique ID of the server event.""" + + type: Literal["error"] + """The event type, must be `error`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..48dbf9929db26ed4ec35f0ba86cd372aa48521ae --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeFunctionTool"] + + +class RealtimeFunctionTool(BaseModel): + description: Optional[str] = None + """ + The description of the function, including guidance on when and how to call it, + and guidance about what to tell the user when calling (if anything). + """ + + name: Optional[str] = None + """The name of the function.""" + + parameters: Optional[object] = None + """Parameters of the function in JSON Schema.""" + + type: Optional[Literal["function"]] = None + """The type of the tool, i.e. `function`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f42e3e497c16b12050834fe79bd67c3ce7fae738 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_function_tool_param.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["RealtimeFunctionToolParam"] + + +class RealtimeFunctionToolParam(TypedDict, total=False): + description: str + """ + The description of the function, including guidance on when and how to call it, + and guidance about what to tell the user when calling (if anything). + """ + + name: str + """The name of the function.""" + + parameters: object + """Parameters of the function in JSON Schema.""" + + type: Literal["function"] + """The type of the tool, i.e. `function`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request.py new file mode 100644 index 0000000000000000000000000000000000000000..bafc8d89d4f6d39c0a5b26dc7da14815e779e75a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcpApprovalRequest"] + + +class RealtimeMcpApprovalRequest(BaseModel): + id: str + """The unique ID of the approval request.""" + + arguments: str + """A JSON string of arguments for the tool.""" + + name: str + """The name of the tool to run.""" + + server_label: str + """The label of the MCP server making the request.""" + + type: Literal["mcp_approval_request"] + """The type of the item. Always `mcp_approval_request`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request_param.py new file mode 100644 index 0000000000000000000000000000000000000000..57c21a487fdfe1b16fcda5c2b6a718c630ae52a9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_request_param.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcpApprovalRequestParam"] + + +class RealtimeMcpApprovalRequestParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the approval request.""" + + arguments: Required[str] + """A JSON string of arguments for the tool.""" + + name: Required[str] + """The name of the tool to run.""" + + server_label: Required[str] + """The label of the MCP server making the request.""" + + type: Required[Literal["mcp_approval_request"]] + """The type of the item. Always `mcp_approval_request`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response.py new file mode 100644 index 0000000000000000000000000000000000000000..2cb03bc61aa5a0b6761bc03b74b24b507bf75991 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcpApprovalResponse"] + + +class RealtimeMcpApprovalResponse(BaseModel): + id: str + """The unique ID of the approval response.""" + + approval_request_id: str + """The ID of the approval request being answered.""" + + approve: bool + """Whether the request was approved.""" + + type: Literal["mcp_approval_response"] + """The type of the item. Always `mcp_approval_response`.""" + + reason: Optional[str] = None + """Optional reason for the decision.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response_param.py new file mode 100644 index 0000000000000000000000000000000000000000..19b6337004d044a1448a04de1da136b4cc6cda35 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_approval_response_param.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcpApprovalResponseParam"] + + +class RealtimeMcpApprovalResponseParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the approval response.""" + + approval_request_id: Required[str] + """The ID of the approval request being answered.""" + + approve: Required[bool] + """Whether the request was approved.""" + + type: Required[Literal["mcp_approval_response"]] + """The type of the item. Always `mcp_approval_response`.""" + + reason: Optional[str] + """Optional reason for the decision.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools.py new file mode 100644 index 0000000000000000000000000000000000000000..aeb58a1faf20021a3c704d9b35a2543ca726a912 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcpListTools", "Tool"] + + +class Tool(BaseModel): + input_schema: object + """The JSON schema describing the tool's input.""" + + name: str + """The name of the tool.""" + + annotations: Optional[object] = None + """Additional annotations about the tool.""" + + description: Optional[str] = None + """The description of the tool.""" + + +class RealtimeMcpListTools(BaseModel): + server_label: str + """The label of the MCP server.""" + + tools: List[Tool] + """The tools available on the server.""" + + type: Literal["mcp_list_tools"] + """The type of the item. Always `mcp_list_tools`.""" + + id: Optional[str] = None + """The unique ID of the list.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools_param.py new file mode 100644 index 0000000000000000000000000000000000000000..eb8605a0617daf9ebcfe2c73db8fb5c7eccc32af --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_list_tools_param.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Iterable, Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcpListToolsParam", "Tool"] + + +class Tool(TypedDict, total=False): + input_schema: Required[object] + """The JSON schema describing the tool's input.""" + + name: Required[str] + """The name of the tool.""" + + annotations: Optional[object] + """Additional annotations about the tool.""" + + description: Optional[str] + """The description of the tool.""" + + +class RealtimeMcpListToolsParam(TypedDict, total=False): + server_label: Required[str] + """The label of the MCP server.""" + + tools: Required[Iterable[Tool]] + """The tools available on the server.""" + + type: Required[Literal["mcp_list_tools"]] + """The type of the item. Always `mcp_list_tools`.""" + + id: str + """The unique ID of the list.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error.py new file mode 100644 index 0000000000000000000000000000000000000000..2e7cfdffa36e4ebc083a1b1202b8b695d1cfc5ed --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcpProtocolError"] + + +class RealtimeMcpProtocolError(BaseModel): + code: int + + message: str + + type: Literal["protocol_error"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error_param.py new file mode 100644 index 0000000000000000000000000000000000000000..bebe3d379e190b260d719f529f52a166afd8b25f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_protocol_error_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcpProtocolErrorParam"] + + +class RealtimeMcpProtocolErrorParam(TypedDict, total=False): + code: Required[int] + + message: Required[str] + + type: Required[Literal["protocol_error"]] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..019aee25c0e63f23362fea959cdea5c9dff27e9a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call.py @@ -0,0 +1,43 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .realtime_mcphttp_error import RealtimeMcphttpError +from .realtime_mcp_protocol_error import RealtimeMcpProtocolError +from .realtime_mcp_tool_execution_error import RealtimeMcpToolExecutionError + +__all__ = ["RealtimeMcpToolCall", "Error"] + +Error: TypeAlias = Annotated[ + Union[RealtimeMcpProtocolError, RealtimeMcpToolExecutionError, RealtimeMcphttpError, None], + PropertyInfo(discriminator="type"), +] + + +class RealtimeMcpToolCall(BaseModel): + id: str + """The unique ID of the tool call.""" + + arguments: str + """A JSON string of the arguments passed to the tool.""" + + name: str + """The name of the tool that was run.""" + + server_label: str + """The label of the MCP server running the tool.""" + + type: Literal["mcp_call"] + """The type of the item. Always `mcp_call`.""" + + approval_request_id: Optional[str] = None + """The ID of an associated approval request, if any.""" + + error: Optional[Error] = None + """The error from the tool call, if any.""" + + output: Optional[str] = None + """The output from the tool call.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0ba16d3dc166ac87646e819727e58288ccef6cdd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_call_param.py @@ -0,0 +1,40 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .realtime_mcphttp_error_param import RealtimeMcphttpErrorParam +from .realtime_mcp_protocol_error_param import RealtimeMcpProtocolErrorParam +from .realtime_mcp_tool_execution_error_param import RealtimeMcpToolExecutionErrorParam + +__all__ = ["RealtimeMcpToolCallParam", "Error"] + +Error: TypeAlias = Union[RealtimeMcpProtocolErrorParam, RealtimeMcpToolExecutionErrorParam, RealtimeMcphttpErrorParam] + + +class RealtimeMcpToolCallParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the tool call.""" + + arguments: Required[str] + """A JSON string of the arguments passed to the tool.""" + + name: Required[str] + """The name of the tool that was run.""" + + server_label: Required[str] + """The label of the MCP server running the tool.""" + + type: Required[Literal["mcp_call"]] + """The type of the item. Always `mcp_call`.""" + + approval_request_id: Optional[str] + """The ID of an associated approval request, if any.""" + + error: Optional[Error] + """The error from the tool call, if any.""" + + output: Optional[str] + """The output from the tool call.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error.py new file mode 100644 index 0000000000000000000000000000000000000000..a2ed06312925606dd57e820fb4ff575f5b0f5d98 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcpToolExecutionError"] + + +class RealtimeMcpToolExecutionError(BaseModel): + message: str + + type: Literal["tool_execution_error"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error_param.py new file mode 100644 index 0000000000000000000000000000000000000000..619e11c30532c10533afdfc928fa132f362f08c9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcp_tool_execution_error_param.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcpToolExecutionErrorParam"] + + +class RealtimeMcpToolExecutionErrorParam(TypedDict, total=False): + message: Required[str] + + type: Required[Literal["tool_execution_error"]] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error.py new file mode 100644 index 0000000000000000000000000000000000000000..53cff91e6ea15c12eccfce69e37e488ae1150631 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeMcphttpError"] + + +class RealtimeMcphttpError(BaseModel): + code: int + + message: str + + type: Literal["http_error"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error_param.py new file mode 100644 index 0000000000000000000000000000000000000000..2b80a6f0a4c29c18dfa4e6d27be21d887aac73e8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_mcphttp_error_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeMcphttpErrorParam"] + + +class RealtimeMcphttpErrorParam(TypedDict, total=False): + code: Required[int] + + message: Required[str] + + type: Required[Literal["http_error"]] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response.py new file mode 100644 index 0000000000000000000000000000000000000000..92d75491c0bbaaa4038acc8d560711e0ad5c9a7c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response.py @@ -0,0 +1,98 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from ..shared.metadata import Metadata +from .conversation_item import ConversationItem +from .realtime_audio_formats import RealtimeAudioFormats +from .realtime_response_usage import RealtimeResponseUsage +from .realtime_response_status import RealtimeResponseStatus + +__all__ = ["RealtimeResponse", "Audio", "AudioOutput"] + + +class AudioOutput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the output audio.""" + + voice: Union[ + str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"], None + ] = None + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ + + +class Audio(BaseModel): + output: Optional[AudioOutput] = None + + +class RealtimeResponse(BaseModel): + id: Optional[str] = None + """The unique ID of the response, will look like `resp_1234`.""" + + audio: Optional[Audio] = None + """Configuration for audio output.""" + + conversation_id: Optional[str] = None + """ + Which conversation the response is added to, determined by the `conversation` + field in the `response.create` event. If `auto`, the response will be added to + the default conversation and the value of `conversation_id` will be an id like + `conv_1234`. If `none`, the response will not be added to any conversation and + the value of `conversation_id` will be `null`. If responses are being triggered + automatically by VAD the response will be added to the default conversation + """ + + max_output_tokens: Union[int, Literal["inf"], None] = None + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls, that was used in this response. + """ + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + object: Optional[Literal["realtime.response"]] = None + """The object type, must be `realtime.response`.""" + + output: Optional[List[ConversationItem]] = None + """The list of output items generated by the response.""" + + output_modalities: Optional[List[Literal["text", "audio"]]] = None + """ + The set of modalities the model used to respond, currently the only possible + values are `[\"audio\"]`, `[\"text\"]`. Audio output always include a text + transcript. Setting the output to mode `text` will disable audio output from the + model. + """ + + status: Optional[Literal["completed", "cancelled", "failed", "incomplete", "in_progress"]] = None + """ + The final status of the response (`completed`, `cancelled`, `failed`, or + `incomplete`, `in_progress`). + """ + + status_details: Optional[RealtimeResponseStatus] = None + """Additional details about the status.""" + + usage: Optional[RealtimeResponseUsage] = None + """Usage statistics for the Response, this will correspond to billing. + + A Realtime API session will maintain a conversation context and append new Items + to the Conversation, thus output from previous turns (text and audio tokens) + will become the input for later turns. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output.py new file mode 100644 index 0000000000000000000000000000000000000000..48a5d67e20973e390bf7633c545d23ea72a0e084 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_audio_formats import RealtimeAudioFormats + +__all__ = ["RealtimeResponseCreateAudioOutput", "Output"] + + +class Output(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the output audio.""" + + voice: Union[ + str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"], None + ] = None + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ + + +class RealtimeResponseCreateAudioOutput(BaseModel): + output: Optional[Output] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output_param.py new file mode 100644 index 0000000000000000000000000000000000000000..9aa6d288354a9d2312a34906546f6779ddc2a712 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_audio_output_param.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypedDict + +from .realtime_audio_formats_param import RealtimeAudioFormatsParam + +__all__ = ["RealtimeResponseCreateAudioOutputParam", "Output"] + + +class Output(TypedDict, total=False): + format: RealtimeAudioFormatsParam + """The format of the output audio.""" + + voice: Union[str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"]] + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ + + +class RealtimeResponseCreateAudioOutputParam(TypedDict, total=False): + output: Output diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..119b4a455d252b00a1a75b0feb08463ab39d4e14 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool.py @@ -0,0 +1,135 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel + +__all__ = [ + "RealtimeResponseCreateMcpTool", + "AllowedTools", + "AllowedToolsMcpToolFilter", + "RequireApproval", + "RequireApprovalMcpToolApprovalFilter", + "RequireApprovalMcpToolApprovalFilterAlways", + "RequireApprovalMcpToolApprovalFilterNever", +] + + +class AllowedToolsMcpToolFilter(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +AllowedTools: TypeAlias = Union[List[str], AllowedToolsMcpToolFilter, None] + + +class RequireApprovalMcpToolApprovalFilterAlways(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class RequireApprovalMcpToolApprovalFilterNever(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class RequireApprovalMcpToolApprovalFilter(BaseModel): + always: Optional[RequireApprovalMcpToolApprovalFilterAlways] = None + """A filter object to specify which tools are allowed.""" + + never: Optional[RequireApprovalMcpToolApprovalFilterNever] = None + """A filter object to specify which tools are allowed.""" + + +RequireApproval: TypeAlias = Union[RequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None] + + +class RealtimeResponseCreateMcpTool(BaseModel): + server_label: str + """A label for this MCP server, used to identify it in tool calls.""" + + type: Literal["mcp"] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[AllowedTools] = None + """List of allowed tool names or a filter object.""" + + authorization: Optional[str] = None + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Optional[ + Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + ] = None + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] = None + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[RequireApproval] = None + """Specify which of the MCP server's tools require approval.""" + + server_description: Optional[str] = None + """Optional description of the MCP server, used to provide more context.""" + + server_url: Optional[str] = None + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..3b9cf047c1bc0b88c03aeef22dd73c57719c0ab3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_mcp_tool_param.py @@ -0,0 +1,135 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr + +__all__ = [ + "RealtimeResponseCreateMcpToolParam", + "AllowedTools", + "AllowedToolsMcpToolFilter", + "RequireApproval", + "RequireApprovalMcpToolApprovalFilter", + "RequireApprovalMcpToolApprovalFilterAlways", + "RequireApprovalMcpToolApprovalFilterNever", +] + + +class AllowedToolsMcpToolFilter(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +AllowedTools: TypeAlias = Union[SequenceNotStr[str], AllowedToolsMcpToolFilter] + + +class RequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class RequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class RequireApprovalMcpToolApprovalFilter(TypedDict, total=False): + always: RequireApprovalMcpToolApprovalFilterAlways + """A filter object to specify which tools are allowed.""" + + never: RequireApprovalMcpToolApprovalFilterNever + """A filter object to specify which tools are allowed.""" + + +RequireApproval: TypeAlias = Union[RequireApprovalMcpToolApprovalFilter, Literal["always", "never"]] + + +class RealtimeResponseCreateMcpToolParam(TypedDict, total=False): + server_label: Required[str] + """A label for this MCP server, used to identify it in tool calls.""" + + type: Required[Literal["mcp"]] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[AllowedTools] + """List of allowed tool names or a filter object.""" + + authorization: str + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[RequireApproval] + """Specify which of the MCP server's tools require approval.""" + + server_description: str + """Optional description of the MCP server, used to provide more context.""" + + server_url: str + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..e8486220bf07ad3290cb72ce7c14d5806df9c066 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params.py @@ -0,0 +1,98 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from ..shared.metadata import Metadata +from .conversation_item import ConversationItem +from .realtime_function_tool import RealtimeFunctionTool +from ..responses.response_prompt import ResponsePrompt +from ..responses.tool_choice_mcp import ToolChoiceMcp +from ..responses.tool_choice_options import ToolChoiceOptions +from ..responses.tool_choice_function import ToolChoiceFunction +from .realtime_response_create_mcp_tool import RealtimeResponseCreateMcpTool +from .realtime_response_create_audio_output import RealtimeResponseCreateAudioOutput + +__all__ = ["RealtimeResponseCreateParams", "ToolChoice", "Tool"] + +ToolChoice: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunction, ToolChoiceMcp] + +Tool: TypeAlias = Union[RealtimeFunctionTool, RealtimeResponseCreateMcpTool] + + +class RealtimeResponseCreateParams(BaseModel): + audio: Optional[RealtimeResponseCreateAudioOutput] = None + """Configuration for audio input and output.""" + + conversation: Union[str, Literal["auto", "none"], None] = None + """Controls which conversation the response is added to. + + Currently supports `auto` and `none`, with `auto` as the default value. The + `auto` value means that the contents of the response will be added to the + default conversation. Set this to `none` to create an out-of-band response which + will not add items to default conversation. + """ + + input: Optional[List[ConversationItem]] = None + """Input items to include in the prompt for the model. + + Using this field creates a new context for this Response instead of using the + default conversation. An empty array `[]` will clear the context for this + Response. Note that this can include references to items that previously + appeared in the session using their id. + """ + + instructions: Optional[str] = None + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. Note that the server sets default instructions which will be used if + this field is not set and are visible in the `session.created` event at the + start of the session. + """ + + max_output_tokens: Union[int, Literal["inf"], None] = None + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + output_modalities: Optional[List[Literal["text", "audio"]]] = None + """ + The set of modalities the model used to respond, currently the only possible + values are `[\"audio\"]`, `[\"text\"]`. Audio output always include a text + transcript. Setting the output to mode `text` will disable audio output from the + model. + """ + + prompt: Optional[ResponsePrompt] = None + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + tool_choice: Optional[ToolChoice] = None + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: Optional[List[Tool]] = None + """Tools available to the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params_param.py new file mode 100644 index 0000000000000000000000000000000000000000..116384bd826fd4360dcbe8aacc3c702ec2ea8bd3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_create_params_param.py @@ -0,0 +1,99 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union, Iterable, Optional +from typing_extensions import Literal, TypeAlias, TypedDict + +from ..shared_params.metadata import Metadata +from .conversation_item_param import ConversationItemParam +from .realtime_function_tool_param import RealtimeFunctionToolParam +from ..responses.tool_choice_options import ToolChoiceOptions +from ..responses.response_prompt_param import ResponsePromptParam +from ..responses.tool_choice_mcp_param import ToolChoiceMcpParam +from ..responses.tool_choice_function_param import ToolChoiceFunctionParam +from .realtime_response_create_mcp_tool_param import RealtimeResponseCreateMcpToolParam +from .realtime_response_create_audio_output_param import RealtimeResponseCreateAudioOutputParam + +__all__ = ["RealtimeResponseCreateParamsParam", "ToolChoice", "Tool"] + +ToolChoice: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunctionParam, ToolChoiceMcpParam] + +Tool: TypeAlias = Union[RealtimeFunctionToolParam, RealtimeResponseCreateMcpToolParam] + + +class RealtimeResponseCreateParamsParam(TypedDict, total=False): + audio: RealtimeResponseCreateAudioOutputParam + """Configuration for audio input and output.""" + + conversation: Union[str, Literal["auto", "none"]] + """Controls which conversation the response is added to. + + Currently supports `auto` and `none`, with `auto` as the default value. The + `auto` value means that the contents of the response will be added to the + default conversation. Set this to `none` to create an out-of-band response which + will not add items to default conversation. + """ + + input: Iterable[ConversationItemParam] + """Input items to include in the prompt for the model. + + Using this field creates a new context for this Response instead of using the + default conversation. An empty array `[]` will clear the context for this + Response. Note that this can include references to items that previously + appeared in the session using their id. + """ + + instructions: str + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. Note that the server sets default instructions which will be used if + this field is not set and are visible in the `session.created` event at the + start of the session. + """ + + max_output_tokens: Union[int, Literal["inf"]] + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + output_modalities: List[Literal["text", "audio"]] + """ + The set of modalities the model used to respond, currently the only possible + values are `[\"audio\"]`, `[\"text\"]`. Audio output always include a text + transcript. Setting the output to mode `text` will disable audio output from the + model. + """ + + prompt: Optional[ResponsePromptParam] + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + tool_choice: ToolChoice + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: Iterable[Tool] + """Tools available to the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_status.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_status.py new file mode 100644 index 0000000000000000000000000000000000000000..12999f61a136789e0f5f04a62262643cb489918a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_status.py @@ -0,0 +1,39 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeResponseStatus", "Error"] + + +class Error(BaseModel): + code: Optional[str] = None + """Error code, if any.""" + + type: Optional[str] = None + """The type of error.""" + + +class RealtimeResponseStatus(BaseModel): + error: Optional[Error] = None + """ + A description of the error that caused the response to fail, populated when the + `status` is `failed`. + """ + + reason: Optional[Literal["turn_detected", "client_cancelled", "max_output_tokens", "content_filter"]] = None + """The reason the Response did not complete. + + For a `cancelled` Response, one of `turn_detected` (the server VAD detected a + new start of speech) or `client_cancelled` (the client sent a cancel event). For + an `incomplete` Response, one of `max_output_tokens` or `content_filter` (the + server-side safety filter activated and cut off the response). + """ + + type: Optional[Literal["completed", "cancelled", "incomplete", "failed"]] = None + """ + The type of error that caused the response to fail, corresponding with the + `status` field (`completed`, `cancelled`, `incomplete`, `failed`). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage.py new file mode 100644 index 0000000000000000000000000000000000000000..fb8893b346220e2839a7776def21de7671b93ac3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage.py @@ -0,0 +1,41 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .realtime_response_usage_input_token_details import RealtimeResponseUsageInputTokenDetails +from .realtime_response_usage_output_token_details import RealtimeResponseUsageOutputTokenDetails + +__all__ = ["RealtimeResponseUsage"] + + +class RealtimeResponseUsage(BaseModel): + input_token_details: Optional[RealtimeResponseUsageInputTokenDetails] = None + """Details about the input tokens used in the Response. + + Cached tokens are tokens from previous turns in the conversation that are + included as context for the current response. Cached tokens here are counted as + a subset of input tokens, meaning input tokens will include cached and uncached + tokens. + """ + + input_tokens: Optional[int] = None + """ + The number of input tokens used in the Response, including text and audio + tokens. + """ + + output_token_details: Optional[RealtimeResponseUsageOutputTokenDetails] = None + """Details about the output tokens used in the Response.""" + + output_tokens: Optional[int] = None + """ + The number of output tokens sent in the Response, including text and audio + tokens. + """ + + total_tokens: Optional[int] = None + """ + The total number of tokens in the Response including input and output text and + audio tokens. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_input_token_details.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_input_token_details.py new file mode 100644 index 0000000000000000000000000000000000000000..e14a74a84e1cb067a78e5ed517c09f7cadc430d2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_input_token_details.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["RealtimeResponseUsageInputTokenDetails", "CachedTokensDetails"] + + +class CachedTokensDetails(BaseModel): + audio_tokens: Optional[int] = None + """The number of cached audio tokens used as input for the Response.""" + + image_tokens: Optional[int] = None + """The number of cached image tokens used as input for the Response.""" + + text_tokens: Optional[int] = None + """The number of cached text tokens used as input for the Response.""" + + +class RealtimeResponseUsageInputTokenDetails(BaseModel): + audio_tokens: Optional[int] = None + """The number of audio tokens used as input for the Response.""" + + cached_tokens: Optional[int] = None + """The number of cached tokens used as input for the Response.""" + + cached_tokens_details: Optional[CachedTokensDetails] = None + """Details about the cached tokens used as input for the Response.""" + + image_tokens: Optional[int] = None + """The number of image tokens used as input for the Response.""" + + text_tokens: Optional[int] = None + """The number of text tokens used as input for the Response.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_output_token_details.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_output_token_details.py new file mode 100644 index 0000000000000000000000000000000000000000..dfa97a1f4782dd2e675d5d907957882e9534d844 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_response_usage_output_token_details.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["RealtimeResponseUsageOutputTokenDetails"] + + +class RealtimeResponseUsageOutputTokenDetails(BaseModel): + audio_tokens: Optional[int] = None + """The number of audio tokens used in the Response.""" + + text_tokens: Optional[int] = None + """The number of text tokens used in the Response.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_server_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_server_event.py new file mode 100644 index 0000000000000000000000000000000000000000..1605b81a971f3a6fb3ae2115adf3673182aa8870 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_server_event.py @@ -0,0 +1,155 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .conversation_item import ConversationItem +from .response_done_event import ResponseDoneEvent +from .realtime_error_event import RealtimeErrorEvent +from .mcp_list_tools_failed import McpListToolsFailed +from .session_created_event import SessionCreatedEvent +from .session_updated_event import SessionUpdatedEvent +from .conversation_item_done import ConversationItemDone +from .response_created_event import ResponseCreatedEvent +from .conversation_item_added import ConversationItemAdded +from .mcp_list_tools_completed import McpListToolsCompleted +from .response_mcp_call_failed import ResponseMcpCallFailed +from .response_text_done_event import ResponseTextDoneEvent +from .rate_limits_updated_event import RateLimitsUpdatedEvent +from .response_audio_done_event import ResponseAudioDoneEvent +from .response_text_delta_event import ResponseTextDeltaEvent +from .conversation_created_event import ConversationCreatedEvent +from .mcp_list_tools_in_progress import McpListToolsInProgress +from .response_audio_delta_event import ResponseAudioDeltaEvent +from .response_mcp_call_completed import ResponseMcpCallCompleted +from .response_mcp_call_in_progress import ResponseMcpCallInProgress +from .conversation_item_created_event import ConversationItemCreatedEvent +from .conversation_item_deleted_event import ConversationItemDeletedEvent +from .response_output_item_done_event import ResponseOutputItemDoneEvent +from .input_audio_buffer_cleared_event import InputAudioBufferClearedEvent +from .response_content_part_done_event import ResponseContentPartDoneEvent +from .response_mcp_call_arguments_done import ResponseMcpCallArgumentsDone +from .response_output_item_added_event import ResponseOutputItemAddedEvent +from .conversation_item_truncated_event import ConversationItemTruncatedEvent +from .response_content_part_added_event import ResponseContentPartAddedEvent +from .response_mcp_call_arguments_delta import ResponseMcpCallArgumentsDelta +from .input_audio_buffer_committed_event import InputAudioBufferCommittedEvent +from .input_audio_buffer_timeout_triggered import InputAudioBufferTimeoutTriggered +from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent +from .response_audio_transcript_delta_event import ResponseAudioTranscriptDeltaEvent +from .input_audio_buffer_speech_started_event import InputAudioBufferSpeechStartedEvent +from .input_audio_buffer_speech_stopped_event import InputAudioBufferSpeechStoppedEvent +from .response_function_call_arguments_done_event import ResponseFunctionCallArgumentsDoneEvent +from .response_function_call_arguments_delta_event import ResponseFunctionCallArgumentsDeltaEvent +from .conversation_item_input_audio_transcription_segment import ConversationItemInputAudioTranscriptionSegment +from .conversation_item_input_audio_transcription_delta_event import ConversationItemInputAudioTranscriptionDeltaEvent +from .conversation_item_input_audio_transcription_failed_event import ConversationItemInputAudioTranscriptionFailedEvent +from .conversation_item_input_audio_transcription_completed_event import ( + ConversationItemInputAudioTranscriptionCompletedEvent, +) + +__all__ = [ + "RealtimeServerEvent", + "ConversationItemRetrieved", + "OutputAudioBufferStarted", + "OutputAudioBufferStopped", + "OutputAudioBufferCleared", +] + + +class ConversationItemRetrieved(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + type: Literal["conversation.item.retrieved"] + """The event type, must be `conversation.item.retrieved`.""" + + +class OutputAudioBufferStarted(BaseModel): + event_id: str + """The unique ID of the server event.""" + + response_id: str + """The unique ID of the response that produced the audio.""" + + type: Literal["output_audio_buffer.started"] + """The event type, must be `output_audio_buffer.started`.""" + + +class OutputAudioBufferStopped(BaseModel): + event_id: str + """The unique ID of the server event.""" + + response_id: str + """The unique ID of the response that produced the audio.""" + + type: Literal["output_audio_buffer.stopped"] + """The event type, must be `output_audio_buffer.stopped`.""" + + +class OutputAudioBufferCleared(BaseModel): + event_id: str + """The unique ID of the server event.""" + + response_id: str + """The unique ID of the response that produced the audio.""" + + type: Literal["output_audio_buffer.cleared"] + """The event type, must be `output_audio_buffer.cleared`.""" + + +RealtimeServerEvent: TypeAlias = Annotated[ + Union[ + ConversationCreatedEvent, + ConversationItemCreatedEvent, + ConversationItemDeletedEvent, + ConversationItemInputAudioTranscriptionCompletedEvent, + ConversationItemInputAudioTranscriptionDeltaEvent, + ConversationItemInputAudioTranscriptionFailedEvent, + ConversationItemRetrieved, + ConversationItemTruncatedEvent, + RealtimeErrorEvent, + InputAudioBufferClearedEvent, + InputAudioBufferCommittedEvent, + InputAudioBufferSpeechStartedEvent, + InputAudioBufferSpeechStoppedEvent, + RateLimitsUpdatedEvent, + ResponseAudioDeltaEvent, + ResponseAudioDoneEvent, + ResponseAudioTranscriptDeltaEvent, + ResponseAudioTranscriptDoneEvent, + ResponseContentPartAddedEvent, + ResponseContentPartDoneEvent, + ResponseCreatedEvent, + ResponseDoneEvent, + ResponseFunctionCallArgumentsDeltaEvent, + ResponseFunctionCallArgumentsDoneEvent, + ResponseOutputItemAddedEvent, + ResponseOutputItemDoneEvent, + ResponseTextDeltaEvent, + ResponseTextDoneEvent, + SessionCreatedEvent, + SessionUpdatedEvent, + OutputAudioBufferStarted, + OutputAudioBufferStopped, + OutputAudioBufferCleared, + ConversationItemAdded, + ConversationItemDone, + InputAudioBufferTimeoutTriggered, + ConversationItemInputAudioTranscriptionSegment, + McpListToolsInProgress, + McpListToolsCompleted, + McpListToolsFailed, + ResponseMcpCallArgumentsDelta, + ResponseMcpCallArgumentsDone, + ResponseMcpCallInProgress, + ResponseMcpCallCompleted, + ResponseMcpCallFailed, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_client_secret.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_client_secret.py new file mode 100644 index 0000000000000000000000000000000000000000..a4998802bb348ac85a8751b8f8c0f567f260b756 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_client_secret.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from ..._models import BaseModel + +__all__ = ["RealtimeSessionClientSecret"] + + +class RealtimeSessionClientSecret(BaseModel): + expires_at: int + """Timestamp for when the token expires. + + Currently, all tokens expire after one minute. + """ + + value: str + """ + Ephemeral key usable in client environments to authenticate connections to the + Realtime API. Use this in client-side environments rather than a standard API + token, which should only be used server-side. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request.py new file mode 100644 index 0000000000000000000000000000000000000000..755dbe863831cbc4c9cdf5c191b2154827a8fe72 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request.py @@ -0,0 +1,107 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_truncation import RealtimeTruncation +from .realtime_audio_config import RealtimeAudioConfig +from .realtime_tools_config import RealtimeToolsConfig +from .realtime_tracing_config import RealtimeTracingConfig +from ..responses.response_prompt import ResponsePrompt +from .realtime_tool_choice_config import RealtimeToolChoiceConfig + +__all__ = ["RealtimeSessionCreateRequest"] + + +class RealtimeSessionCreateRequest(BaseModel): + type: Literal["realtime"] + """The type of session to create. Always `realtime` for the Realtime API.""" + + audio: Optional[RealtimeAudioConfig] = None + """Configuration for input and output audio.""" + + include: Optional[List[Literal["item.input_audio_transcription.logprobs"]]] = None + """Additional fields to include in server outputs. + + `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ + + instructions: Optional[str] = None + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. + + Note that the server sets default instructions which will be used if this field + is not set and are visible in the `session.created` event at the start of the + session. + """ + + max_output_tokens: Union[int, Literal["inf"], None] = None + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + model: Union[ + str, + Literal[ + "gpt-realtime", + "gpt-realtime-2025-08-28", + "gpt-4o-realtime-preview", + "gpt-4o-realtime-preview-2024-10-01", + "gpt-4o-realtime-preview-2024-12-17", + "gpt-4o-realtime-preview-2025-06-03", + "gpt-4o-mini-realtime-preview", + "gpt-4o-mini-realtime-preview-2024-12-17", + ], + None, + ] = None + """The Realtime model used for this session.""" + + output_modalities: Optional[List[Literal["text", "audio"]]] = None + """The set of modalities the model can respond with. + + It defaults to `["audio"]`, indicating that the model will respond with audio + plus a transcript. `["text"]` can be used to make the model respond with text + only. It is not possible to request both `text` and `audio` at the same time. + """ + + prompt: Optional[ResponsePrompt] = None + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + tool_choice: Optional[RealtimeToolChoiceConfig] = None + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: Optional[RealtimeToolsConfig] = None + """Tools available to the model.""" + + tracing: Optional[RealtimeTracingConfig] = None + """ + Realtime API can write session traces to the + [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once + tracing is enabled for a session, the configuration cannot be modified. + + `auto` will create a trace for the session with default values for the workflow + name, group id, and metadata. + """ + + truncation: Optional[RealtimeTruncation] = None + """ + Controls how the realtime conversation is truncated prior to model inference. + The default is `auto`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request_param.py new file mode 100644 index 0000000000000000000000000000000000000000..cd4ef71ba2a8bac0ebbeac1552e03ad42e8fca55 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_request_param.py @@ -0,0 +1,107 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union, Optional +from typing_extensions import Literal, Required, TypedDict + +from .realtime_truncation_param import RealtimeTruncationParam +from .realtime_audio_config_param import RealtimeAudioConfigParam +from .realtime_tools_config_param import RealtimeToolsConfigParam +from .realtime_tracing_config_param import RealtimeTracingConfigParam +from ..responses.response_prompt_param import ResponsePromptParam +from .realtime_tool_choice_config_param import RealtimeToolChoiceConfigParam + +__all__ = ["RealtimeSessionCreateRequestParam"] + + +class RealtimeSessionCreateRequestParam(TypedDict, total=False): + type: Required[Literal["realtime"]] + """The type of session to create. Always `realtime` for the Realtime API.""" + + audio: RealtimeAudioConfigParam + """Configuration for input and output audio.""" + + include: List[Literal["item.input_audio_transcription.logprobs"]] + """Additional fields to include in server outputs. + + `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ + + instructions: str + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. + + Note that the server sets default instructions which will be used if this field + is not set and are visible in the `session.created` event at the start of the + session. + """ + + max_output_tokens: Union[int, Literal["inf"]] + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + model: Union[ + str, + Literal[ + "gpt-realtime", + "gpt-realtime-2025-08-28", + "gpt-4o-realtime-preview", + "gpt-4o-realtime-preview-2024-10-01", + "gpt-4o-realtime-preview-2024-12-17", + "gpt-4o-realtime-preview-2025-06-03", + "gpt-4o-mini-realtime-preview", + "gpt-4o-mini-realtime-preview-2024-12-17", + ], + ] + """The Realtime model used for this session.""" + + output_modalities: List[Literal["text", "audio"]] + """The set of modalities the model can respond with. + + It defaults to `["audio"]`, indicating that the model will respond with audio + plus a transcript. `["text"]` can be used to make the model respond with text + only. It is not possible to request both `text` and `audio` at the same time. + """ + + prompt: Optional[ResponsePromptParam] + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + tool_choice: RealtimeToolChoiceConfigParam + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: RealtimeToolsConfigParam + """Tools available to the model.""" + + tracing: Optional[RealtimeTracingConfigParam] + """ + Realtime API can write session traces to the + [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once + tracing is enabled for a session, the configuration cannot be modified. + + `auto` will create a trace for the session with default values for the workflow + name, group id, and metadata. + """ + + truncation: RealtimeTruncationParam + """ + Controls how the realtime conversation is truncated prior to model inference. + The default is `auto`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..2d6912d072069312071ae54c974c20b11a135114 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_session_create_response.py @@ -0,0 +1,460 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .audio_transcription import AudioTranscription +from .realtime_truncation import RealtimeTruncation +from .noise_reduction_type import NoiseReductionType +from .realtime_audio_formats import RealtimeAudioFormats +from .realtime_function_tool import RealtimeFunctionTool +from ..responses.response_prompt import ResponsePrompt +from ..responses.tool_choice_mcp import ToolChoiceMcp +from ..responses.tool_choice_options import ToolChoiceOptions +from .realtime_session_client_secret import RealtimeSessionClientSecret +from ..responses.tool_choice_function import ToolChoiceFunction + +__all__ = [ + "RealtimeSessionCreateResponse", + "Audio", + "AudioInput", + "AudioInputNoiseReduction", + "AudioInputTurnDetection", + "AudioInputTurnDetectionServerVad", + "AudioInputTurnDetectionSemanticVad", + "AudioOutput", + "ToolChoice", + "Tool", + "ToolMcpTool", + "ToolMcpToolAllowedTools", + "ToolMcpToolAllowedToolsMcpToolFilter", + "ToolMcpToolRequireApproval", + "ToolMcpToolRequireApprovalMcpToolApprovalFilter", + "ToolMcpToolRequireApprovalMcpToolApprovalFilterAlways", + "ToolMcpToolRequireApprovalMcpToolApprovalFilterNever", + "Tracing", + "TracingTracingConfiguration", +] + + +class AudioInputNoiseReduction(BaseModel): + type: Optional[NoiseReductionType] = None + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class AudioInputTurnDetectionServerVad(BaseModel): + type: Literal["server_vad"] + """Type of turn detection, `server_vad` to turn on simple Server VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + idle_timeout_ms: Optional[int] = None + """Optional timeout after which a model response will be triggered automatically. + + This is useful for situations in which a long pause from the user is unexpected, + such as a phone call. The model will effectively prompt the user to continue the + conversation based on the current context. + + The timeout value will be applied after the last model response's audio has + finished playing, i.e. it's set to the `response.done` time plus audio playback + duration. + + An `input_audio_buffer.timeout_triggered` event (plus events associated with the + Response) will be emitted when the timeout is reached. Idle timeout is currently + only supported for `server_vad` mode. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + prefix_padding_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Amount of audio to include before the VAD detected speech (in milliseconds). + Defaults to 300ms. + """ + + silence_duration_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. + With shorter values the model will respond more quickly, but may jump in on + short pauses from the user. + """ + + threshold: Optional[float] = None + """Used only for `server_vad` mode. + + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher + threshold will require louder audio to activate the model, and thus might + perform better in noisy environments. + """ + + +class AudioInputTurnDetectionSemanticVad(BaseModel): + type: Literal["semantic_vad"] + """Type of turn detection, `semantic_vad` to turn on Semantic VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + eagerness: Optional[Literal["low", "medium", "high", "auto"]] = None + """Used only for `semantic_vad` mode. + + The eagerness of the model to respond. `low` will wait longer for the user to + continue speaking, `high` will respond more quickly. `auto` is the default and + is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, + 4s, and 2s respectively. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + +AudioInputTurnDetection: TypeAlias = Annotated[ + Union[AudioInputTurnDetectionServerVad, AudioInputTurnDetectionSemanticVad, None], + PropertyInfo(discriminator="type"), +] + + +class AudioInput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the input audio.""" + + noise_reduction: Optional[AudioInputNoiseReduction] = None + """Configuration for input audio noise reduction. + + This can be set to `null` to turn off. Noise reduction filters audio added to + the input audio buffer before it is sent to VAD and the model. Filtering the + audio can improve VAD and turn detection accuracy (reducing false positives) and + model performance by improving perception of the input audio. + """ + + transcription: Optional[AudioTranscription] = None + """ + Configuration for input audio transcription, defaults to off and can be set to + `null` to turn off once on. Input audio transcription is not native to the + model, since the model consumes audio directly. Transcription runs + asynchronously through + [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as guidance of input audio content rather than precisely + what the model heard. The client can optionally set the language and prompt for + transcription, these offer additional guidance to the transcription service. + """ + + turn_detection: Optional[AudioInputTurnDetection] = None + """Configuration for turn detection, ether Server VAD or Semantic VAD. + + This can be set to `null` to turn off, in which case the client must manually + trigger model response. + + Server VAD means that the model will detect the start and end of speech based on + audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in conjunction + with VAD) to semantically estimate whether the user has finished speaking, then + dynamically sets a timeout based on this probability. For example, if user audio + trails off with "uhhm", the model will score a low probability of turn end and + wait longer for the user to continue speaking. This can be useful for more + natural conversations, but may have a higher latency. + """ + + +class AudioOutput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The format of the output audio.""" + + speed: Optional[float] = None + """ + The speed of the model's spoken response as a multiple of the original speed. + 1.0 is the default speed. 0.25 is the minimum speed. 1.5 is the maximum speed. + This value can only be changed in between model turns, not while a response is + in progress. + + This parameter is a post-processing adjustment to the audio after it is + generated, it's also possible to prompt the model to speak faster or slower. + """ + + voice: Union[ + str, Literal["alloy", "ash", "ballad", "coral", "echo", "sage", "shimmer", "verse", "marin", "cedar"], None + ] = None + """The voice the model uses to respond. + + Voice cannot be changed during the session once the model has responded with + audio at least once. Current voice options are `alloy`, `ash`, `ballad`, + `coral`, `echo`, `sage`, `shimmer`, `verse`, `marin`, and `cedar`. We recommend + `marin` and `cedar` for best quality. + """ + + +class Audio(BaseModel): + input: Optional[AudioInput] = None + + output: Optional[AudioOutput] = None + + +ToolChoice: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunction, ToolChoiceMcp] + + +class ToolMcpToolAllowedToolsMcpToolFilter(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +ToolMcpToolAllowedTools: TypeAlias = Union[List[str], ToolMcpToolAllowedToolsMcpToolFilter, None] + + +class ToolMcpToolRequireApprovalMcpToolApprovalFilterAlways(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class ToolMcpToolRequireApprovalMcpToolApprovalFilterNever(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class ToolMcpToolRequireApprovalMcpToolApprovalFilter(BaseModel): + always: Optional[ToolMcpToolRequireApprovalMcpToolApprovalFilterAlways] = None + """A filter object to specify which tools are allowed.""" + + never: Optional[ToolMcpToolRequireApprovalMcpToolApprovalFilterNever] = None + """A filter object to specify which tools are allowed.""" + + +ToolMcpToolRequireApproval: TypeAlias = Union[ + ToolMcpToolRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None +] + + +class ToolMcpTool(BaseModel): + server_label: str + """A label for this MCP server, used to identify it in tool calls.""" + + type: Literal["mcp"] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[ToolMcpToolAllowedTools] = None + """List of allowed tool names or a filter object.""" + + authorization: Optional[str] = None + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Optional[ + Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + ] = None + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] = None + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[ToolMcpToolRequireApproval] = None + """Specify which of the MCP server's tools require approval.""" + + server_description: Optional[str] = None + """Optional description of the MCP server, used to provide more context.""" + + server_url: Optional[str] = None + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +Tool: TypeAlias = Union[RealtimeFunctionTool, ToolMcpTool] + + +class TracingTracingConfiguration(BaseModel): + group_id: Optional[str] = None + """ + The group id to attach to this trace to enable filtering and grouping in the + Traces Dashboard. + """ + + metadata: Optional[object] = None + """ + The arbitrary metadata to attach to this trace to enable filtering in the Traces + Dashboard. + """ + + workflow_name: Optional[str] = None + """The name of the workflow to attach to this trace. + + This is used to name the trace in the Traces Dashboard. + """ + + +Tracing: TypeAlias = Union[Literal["auto"], TracingTracingConfiguration, None] + + +class RealtimeSessionCreateResponse(BaseModel): + client_secret: RealtimeSessionClientSecret + """Ephemeral key returned by the API.""" + + type: Literal["realtime"] + """The type of session to create. Always `realtime` for the Realtime API.""" + + audio: Optional[Audio] = None + """Configuration for input and output audio.""" + + include: Optional[List[Literal["item.input_audio_transcription.logprobs"]]] = None + """Additional fields to include in server outputs. + + `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ + + instructions: Optional[str] = None + """The default system instructions (i.e. + + system message) prepended to model calls. This field allows the client to guide + the model on desired responses. The model can be instructed on response content + and format, (e.g. "be extremely succinct", "act friendly", "here are examples of + good responses") and on audio behavior (e.g. "talk quickly", "inject emotion + into your voice", "laugh frequently"). The instructions are not guaranteed to be + followed by the model, but they provide guidance to the model on the desired + behavior. + + Note that the server sets default instructions which will be used if this field + is not set and are visible in the `session.created` event at the start of the + session. + """ + + max_output_tokens: Union[int, Literal["inf"], None] = None + """ + Maximum number of output tokens for a single assistant response, inclusive of + tool calls. Provide an integer between 1 and 4096 to limit output tokens, or + `inf` for the maximum available tokens for a given model. Defaults to `inf`. + """ + + model: Union[ + str, + Literal[ + "gpt-realtime", + "gpt-realtime-2025-08-28", + "gpt-4o-realtime-preview", + "gpt-4o-realtime-preview-2024-10-01", + "gpt-4o-realtime-preview-2024-12-17", + "gpt-4o-realtime-preview-2025-06-03", + "gpt-4o-mini-realtime-preview", + "gpt-4o-mini-realtime-preview-2024-12-17", + ], + None, + ] = None + """The Realtime model used for this session.""" + + output_modalities: Optional[List[Literal["text", "audio"]]] = None + """The set of modalities the model can respond with. + + It defaults to `["audio"]`, indicating that the model will respond with audio + plus a transcript. `["text"]` can be used to make the model respond with text + only. It is not possible to request both `text` and `audio` at the same time. + """ + + prompt: Optional[ResponsePrompt] = None + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + tool_choice: Optional[ToolChoice] = None + """How the model chooses tools. + + Provide one of the string modes or force a specific function/MCP tool. + """ + + tools: Optional[List[Tool]] = None + """Tools available to the model.""" + + tracing: Optional[Tracing] = None + """ + Realtime API can write session traces to the + [Traces Dashboard](/logs?api=traces). Set to null to disable tracing. Once + tracing is enabled for a session, the configuration cannot be modified. + + `auto` will create a trace for the session with default values for the workflow + name, group id, and metadata. + """ + + truncation: Optional[RealtimeTruncation] = None + """ + Controls how the realtime conversation is truncated prior to model inference. + The default is `auto`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config.py new file mode 100644 index 0000000000000000000000000000000000000000..f93c49000460dcef4ae8760b2b6ce7f423f9ad9b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import TypeAlias + +from ..responses.tool_choice_mcp import ToolChoiceMcp +from ..responses.tool_choice_options import ToolChoiceOptions +from ..responses.tool_choice_function import ToolChoiceFunction + +__all__ = ["RealtimeToolChoiceConfig"] + +RealtimeToolChoiceConfig: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunction, ToolChoiceMcp] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..af92f243b06f0d4c492dc18797bcafc34d17d195 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tool_choice_config_param.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from ..responses.tool_choice_options import ToolChoiceOptions +from ..responses.tool_choice_mcp_param import ToolChoiceMcpParam +from ..responses.tool_choice_function_param import ToolChoiceFunctionParam + +__all__ = ["RealtimeToolChoiceConfigParam"] + +RealtimeToolChoiceConfigParam: TypeAlias = Union[ToolChoiceOptions, ToolChoiceFunctionParam, ToolChoiceMcpParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config.py new file mode 100644 index 0000000000000000000000000000000000000000..b97599ab42244cd3009ac4cb18249195c8fefd08 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List +from typing_extensions import TypeAlias + +from .realtime_tools_config_union import RealtimeToolsConfigUnion + +__all__ = ["RealtimeToolsConfig"] + +RealtimeToolsConfig: TypeAlias = List[RealtimeToolsConfigUnion] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..630fc74691ab01b1b287e9e8c3e3fd8b3321f8f9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_param.py @@ -0,0 +1,143 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from .realtime_function_tool_param import RealtimeFunctionToolParam + +__all__ = [ + "RealtimeToolsConfigParam", + "RealtimeToolsConfigUnionParam", + "Mcp", + "McpAllowedTools", + "McpAllowedToolsMcpToolFilter", + "McpRequireApproval", + "McpRequireApprovalMcpToolApprovalFilter", + "McpRequireApprovalMcpToolApprovalFilterAlways", + "McpRequireApprovalMcpToolApprovalFilterNever", +] + + +class McpAllowedToolsMcpToolFilter(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +McpAllowedTools: TypeAlias = Union[SequenceNotStr[str], McpAllowedToolsMcpToolFilter] + + +class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False): + always: McpRequireApprovalMcpToolApprovalFilterAlways + """A filter object to specify which tools are allowed.""" + + never: McpRequireApprovalMcpToolApprovalFilterNever + """A filter object to specify which tools are allowed.""" + + +McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]] + + +class Mcp(TypedDict, total=False): + server_label: Required[str] + """A label for this MCP server, used to identify it in tool calls.""" + + type: Required[Literal["mcp"]] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[McpAllowedTools] + """List of allowed tool names or a filter object.""" + + authorization: str + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[McpRequireApproval] + """Specify which of the MCP server's tools require approval.""" + + server_description: str + """Optional description of the MCP server, used to provide more context.""" + + server_url: str + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +RealtimeToolsConfigUnionParam: TypeAlias = Union[RealtimeFunctionToolParam, Mcp] + +RealtimeToolsConfigParam: TypeAlias = List[RealtimeToolsConfigUnionParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union.py new file mode 100644 index 0000000000000000000000000000000000000000..e7126ed60d9392131308a340fa4ed2aead63be1c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union.py @@ -0,0 +1,141 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .realtime_function_tool import RealtimeFunctionTool + +__all__ = [ + "RealtimeToolsConfigUnion", + "Mcp", + "McpAllowedTools", + "McpAllowedToolsMcpToolFilter", + "McpRequireApproval", + "McpRequireApprovalMcpToolApprovalFilter", + "McpRequireApprovalMcpToolApprovalFilterAlways", + "McpRequireApprovalMcpToolApprovalFilterNever", +] + + +class McpAllowedToolsMcpToolFilter(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter, None] + + +class McpRequireApprovalMcpToolApprovalFilterAlways(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilterNever(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilter(BaseModel): + always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways] = None + """A filter object to specify which tools are allowed.""" + + never: Optional[McpRequireApprovalMcpToolApprovalFilterNever] = None + """A filter object to specify which tools are allowed.""" + + +McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None] + + +class Mcp(BaseModel): + server_label: str + """A label for this MCP server, used to identify it in tool calls.""" + + type: Literal["mcp"] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[McpAllowedTools] = None + """List of allowed tool names or a filter object.""" + + authorization: Optional[str] = None + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Optional[ + Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + ] = None + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] = None + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[McpRequireApproval] = None + """Specify which of the MCP server's tools require approval.""" + + server_description: Optional[str] = None + """Optional description of the MCP server, used to provide more context.""" + + server_url: Optional[str] = None + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +RealtimeToolsConfigUnion: TypeAlias = Annotated[Union[RealtimeFunctionTool, Mcp], PropertyInfo(discriminator="type")] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union_param.py new file mode 100644 index 0000000000000000000000000000000000000000..9ee58fdbe69e4fd24e31cf5c29c51f2fa320d7fc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tools_config_union_param.py @@ -0,0 +1,140 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from .realtime_function_tool_param import RealtimeFunctionToolParam + +__all__ = [ + "RealtimeToolsConfigUnionParam", + "Mcp", + "McpAllowedTools", + "McpAllowedToolsMcpToolFilter", + "McpRequireApproval", + "McpRequireApprovalMcpToolApprovalFilter", + "McpRequireApprovalMcpToolApprovalFilterAlways", + "McpRequireApprovalMcpToolApprovalFilterNever", +] + + +class McpAllowedToolsMcpToolFilter(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +McpAllowedTools: TypeAlias = Union[SequenceNotStr[str], McpAllowedToolsMcpToolFilter] + + +class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False): + always: McpRequireApprovalMcpToolApprovalFilterAlways + """A filter object to specify which tools are allowed.""" + + never: McpRequireApprovalMcpToolApprovalFilterNever + """A filter object to specify which tools are allowed.""" + + +McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]] + + +class Mcp(TypedDict, total=False): + server_label: Required[str] + """A label for this MCP server, used to identify it in tool calls.""" + + type: Required[Literal["mcp"]] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[McpAllowedTools] + """List of allowed tool names or a filter object.""" + + authorization: str + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[McpRequireApproval] + """Specify which of the MCP server's tools require approval.""" + + server_description: str + """Optional description of the MCP server, used to provide more context.""" + + server_url: str + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +RealtimeToolsConfigUnionParam: TypeAlias = Union[RealtimeFunctionToolParam, Mcp] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config.py new file mode 100644 index 0000000000000000000000000000000000000000..1c46de79281815670ba992900538fb9372d09d5c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel + +__all__ = ["RealtimeTracingConfig", "TracingConfiguration"] + + +class TracingConfiguration(BaseModel): + group_id: Optional[str] = None + """ + The group id to attach to this trace to enable filtering and grouping in the + Traces Dashboard. + """ + + metadata: Optional[object] = None + """ + The arbitrary metadata to attach to this trace to enable filtering in the Traces + Dashboard. + """ + + workflow_name: Optional[str] = None + """The name of the workflow to attach to this trace. + + This is used to name the trace in the Traces Dashboard. + """ + + +RealtimeTracingConfig: TypeAlias = Union[Literal["auto"], TracingConfiguration, None] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..fd9e266244a0d0f9f9b81e10263aeca498e380cb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_tracing_config_param.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypeAlias, TypedDict + +__all__ = ["RealtimeTracingConfigParam", "TracingConfiguration"] + + +class TracingConfiguration(TypedDict, total=False): + group_id: str + """ + The group id to attach to this trace to enable filtering and grouping in the + Traces Dashboard. + """ + + metadata: object + """ + The arbitrary metadata to attach to this trace to enable filtering in the Traces + Dashboard. + """ + + workflow_name: str + """The name of the workflow to attach to this trace. + + This is used to name the trace in the Traces Dashboard. + """ + + +RealtimeTracingConfigParam: TypeAlias = Union[Literal["auto"], TracingConfiguration] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio.py new file mode 100644 index 0000000000000000000000000000000000000000..a5506947f16dbb011c4125525d4514c64d8ee81c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .realtime_transcription_session_audio_input import RealtimeTranscriptionSessionAudioInput + +__all__ = ["RealtimeTranscriptionSessionAudio"] + + +class RealtimeTranscriptionSessionAudio(BaseModel): + input: Optional[RealtimeTranscriptionSessionAudioInput] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input.py new file mode 100644 index 0000000000000000000000000000000000000000..efc321cbeb58720f69e0f4d5536aeaa7ed910c6c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input.py @@ -0,0 +1,65 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .audio_transcription import AudioTranscription +from .noise_reduction_type import NoiseReductionType +from .realtime_audio_formats import RealtimeAudioFormats +from .realtime_transcription_session_audio_input_turn_detection import ( + RealtimeTranscriptionSessionAudioInputTurnDetection, +) + +__all__ = ["RealtimeTranscriptionSessionAudioInput", "NoiseReduction"] + + +class NoiseReduction(BaseModel): + type: Optional[NoiseReductionType] = None + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class RealtimeTranscriptionSessionAudioInput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The PCM audio format. Only a 24kHz sample rate is supported.""" + + noise_reduction: Optional[NoiseReduction] = None + """Configuration for input audio noise reduction. + + This can be set to `null` to turn off. Noise reduction filters audio added to + the input audio buffer before it is sent to VAD and the model. Filtering the + audio can improve VAD and turn detection accuracy (reducing false positives) and + model performance by improving perception of the input audio. + """ + + transcription: Optional[AudioTranscription] = None + """ + Configuration for input audio transcription, defaults to off and can be set to + `null` to turn off once on. Input audio transcription is not native to the + model, since the model consumes audio directly. Transcription runs + asynchronously through + [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as guidance of input audio content rather than precisely + what the model heard. The client can optionally set the language and prompt for + transcription, these offer additional guidance to the transcription service. + """ + + turn_detection: Optional[RealtimeTranscriptionSessionAudioInputTurnDetection] = None + """Configuration for turn detection, ether Server VAD or Semantic VAD. + + This can be set to `null` to turn off, in which case the client must manually + trigger model response. + + Server VAD means that the model will detect the start and end of speech based on + audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in conjunction + with VAD) to semantically estimate whether the user has finished speaking, then + dynamically sets a timeout based on this probability. For example, if user audio + trails off with "uhhm", the model will score a low probability of turn end and + wait longer for the user to continue speaking. This can be useful for more + natural conversations, but may have a higher latency. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..c9153b68a4a8c086d6021940798e0309b767606a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_param.py @@ -0,0 +1,67 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import TypedDict + +from .noise_reduction_type import NoiseReductionType +from .audio_transcription_param import AudioTranscriptionParam +from .realtime_audio_formats_param import RealtimeAudioFormatsParam +from .realtime_transcription_session_audio_input_turn_detection_param import ( + RealtimeTranscriptionSessionAudioInputTurnDetectionParam, +) + +__all__ = ["RealtimeTranscriptionSessionAudioInputParam", "NoiseReduction"] + + +class NoiseReduction(TypedDict, total=False): + type: NoiseReductionType + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class RealtimeTranscriptionSessionAudioInputParam(TypedDict, total=False): + format: RealtimeAudioFormatsParam + """The PCM audio format. Only a 24kHz sample rate is supported.""" + + noise_reduction: NoiseReduction + """Configuration for input audio noise reduction. + + This can be set to `null` to turn off. Noise reduction filters audio added to + the input audio buffer before it is sent to VAD and the model. Filtering the + audio can improve VAD and turn detection accuracy (reducing false positives) and + model performance by improving perception of the input audio. + """ + + transcription: AudioTranscriptionParam + """ + Configuration for input audio transcription, defaults to off and can be set to + `null` to turn off once on. Input audio transcription is not native to the + model, since the model consumes audio directly. Transcription runs + asynchronously through + [the /audio/transcriptions endpoint](https://platform.openai.com/docs/api-reference/audio/createTranscription) + and should be treated as guidance of input audio content rather than precisely + what the model heard. The client can optionally set the language and prompt for + transcription, these offer additional guidance to the transcription service. + """ + + turn_detection: Optional[RealtimeTranscriptionSessionAudioInputTurnDetectionParam] + """Configuration for turn detection, ether Server VAD or Semantic VAD. + + This can be set to `null` to turn off, in which case the client must manually + trigger model response. + + Server VAD means that the model will detect the start and end of speech based on + audio volume and respond at the end of user speech. + + Semantic VAD is more advanced and uses a turn detection model (in conjunction + with VAD) to semantically estimate whether the user has finished speaking, then + dynamically sets a timeout based on this probability. For example, if user audio + trails off with "uhhm", the model will score a low probability of turn end and + wait longer for the user to continue speaking. This can be useful for more + natural conversations, but may have a higher latency. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection.py new file mode 100644 index 0000000000000000000000000000000000000000..7dc7a8f3028d4853149afa48962455b2b6bd115b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection.py @@ -0,0 +1,98 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["RealtimeTranscriptionSessionAudioInputTurnDetection", "ServerVad", "SemanticVad"] + + +class ServerVad(BaseModel): + type: Literal["server_vad"] + """Type of turn detection, `server_vad` to turn on simple Server VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + idle_timeout_ms: Optional[int] = None + """Optional timeout after which a model response will be triggered automatically. + + This is useful for situations in which a long pause from the user is unexpected, + such as a phone call. The model will effectively prompt the user to continue the + conversation based on the current context. + + The timeout value will be applied after the last model response's audio has + finished playing, i.e. it's set to the `response.done` time plus audio playback + duration. + + An `input_audio_buffer.timeout_triggered` event (plus events associated with the + Response) will be emitted when the timeout is reached. Idle timeout is currently + only supported for `server_vad` mode. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + prefix_padding_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Amount of audio to include before the VAD detected speech (in milliseconds). + Defaults to 300ms. + """ + + silence_duration_ms: Optional[int] = None + """Used only for `server_vad` mode. + + Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. + With shorter values the model will respond more quickly, but may jump in on + short pauses from the user. + """ + + threshold: Optional[float] = None + """Used only for `server_vad` mode. + + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher + threshold will require louder audio to activate the model, and thus might + perform better in noisy environments. + """ + + +class SemanticVad(BaseModel): + type: Literal["semantic_vad"] + """Type of turn detection, `semantic_vad` to turn on Semantic VAD.""" + + create_response: Optional[bool] = None + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + eagerness: Optional[Literal["low", "medium", "high", "auto"]] = None + """Used only for `semantic_vad` mode. + + The eagerness of the model to respond. `low` will wait longer for the user to + continue speaking, `high` will respond more quickly. `auto` is the default and + is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, + 4s, and 2s respectively. + """ + + interrupt_response: Optional[bool] = None + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + +RealtimeTranscriptionSessionAudioInputTurnDetection: TypeAlias = Annotated[ + Union[ServerVad, SemanticVad, None], PropertyInfo(discriminator="type") +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection_param.py new file mode 100644 index 0000000000000000000000000000000000000000..d899b8c5c1db9a9a8120708f73cab51cc0c63ea4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_input_turn_detection_param.py @@ -0,0 +1,95 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = ["RealtimeTranscriptionSessionAudioInputTurnDetectionParam", "ServerVad", "SemanticVad"] + + +class ServerVad(TypedDict, total=False): + type: Required[Literal["server_vad"]] + """Type of turn detection, `server_vad` to turn on simple Server VAD.""" + + create_response: bool + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + idle_timeout_ms: Optional[int] + """Optional timeout after which a model response will be triggered automatically. + + This is useful for situations in which a long pause from the user is unexpected, + such as a phone call. The model will effectively prompt the user to continue the + conversation based on the current context. + + The timeout value will be applied after the last model response's audio has + finished playing, i.e. it's set to the `response.done` time plus audio playback + duration. + + An `input_audio_buffer.timeout_triggered` event (plus events associated with the + Response) will be emitted when the timeout is reached. Idle timeout is currently + only supported for `server_vad` mode. + """ + + interrupt_response: bool + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + prefix_padding_ms: int + """Used only for `server_vad` mode. + + Amount of audio to include before the VAD detected speech (in milliseconds). + Defaults to 300ms. + """ + + silence_duration_ms: int + """Used only for `server_vad` mode. + + Duration of silence to detect speech stop (in milliseconds). Defaults to 500ms. + With shorter values the model will respond more quickly, but may jump in on + short pauses from the user. + """ + + threshold: float + """Used only for `server_vad` mode. + + Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. A higher + threshold will require louder audio to activate the model, and thus might + perform better in noisy environments. + """ + + +class SemanticVad(TypedDict, total=False): + type: Required[Literal["semantic_vad"]] + """Type of turn detection, `semantic_vad` to turn on Semantic VAD.""" + + create_response: bool + """ + Whether or not to automatically generate a response when a VAD stop event + occurs. + """ + + eagerness: Literal["low", "medium", "high", "auto"] + """Used only for `semantic_vad` mode. + + The eagerness of the model to respond. `low` will wait longer for the user to + continue speaking, `high` will respond more quickly. `auto` is the default and + is equivalent to `medium`. `low`, `medium`, and `high` have max timeouts of 8s, + 4s, and 2s respectively. + """ + + interrupt_response: bool + """ + Whether or not to automatically interrupt any ongoing response with output to + the default conversation (i.e. `conversation` of `auto`) when a VAD start event + occurs. + """ + + +RealtimeTranscriptionSessionAudioInputTurnDetectionParam: TypeAlias = Union[ServerVad, SemanticVad] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_param.py new file mode 100644 index 0000000000000000000000000000000000000000..1503a606d3128692c563cc92c40fac59a288fd7d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_audio_param.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import TypedDict + +from .realtime_transcription_session_audio_input_param import RealtimeTranscriptionSessionAudioInputParam + +__all__ = ["RealtimeTranscriptionSessionAudioParam"] + + +class RealtimeTranscriptionSessionAudioParam(TypedDict, total=False): + input: RealtimeTranscriptionSessionAudioInputParam diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request.py new file mode 100644 index 0000000000000000000000000000000000000000..102f2b14fb2437eda5d51c04e91da484a3f53a4a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_transcription_session_audio import RealtimeTranscriptionSessionAudio + +__all__ = ["RealtimeTranscriptionSessionCreateRequest"] + + +class RealtimeTranscriptionSessionCreateRequest(BaseModel): + type: Literal["transcription"] + """The type of session to create. + + Always `transcription` for transcription sessions. + """ + + audio: Optional[RealtimeTranscriptionSessionAudio] = None + """Configuration for input and output audio.""" + + include: Optional[List[Literal["item.input_audio_transcription.logprobs"]]] = None + """Additional fields to include in server outputs. + + `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request_param.py new file mode 100644 index 0000000000000000000000000000000000000000..80cbe2d4148ca48b8de5df41e42dc478197c5330 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_request_param.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List +from typing_extensions import Literal, Required, TypedDict + +from .realtime_transcription_session_audio_param import RealtimeTranscriptionSessionAudioParam + +__all__ = ["RealtimeTranscriptionSessionCreateRequestParam"] + + +class RealtimeTranscriptionSessionCreateRequestParam(TypedDict, total=False): + type: Required[Literal["transcription"]] + """The type of session to create. + + Always `transcription` for transcription sessions. + """ + + audio: RealtimeTranscriptionSessionAudioParam + """Configuration for input and output audio.""" + + include: List[Literal["item.input_audio_transcription.logprobs"]] + """Additional fields to include in server outputs. + + `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_response.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_response.py new file mode 100644 index 0000000000000000000000000000000000000000..301af1ac3f98fec07b11cb2baa0436caddf78f3e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_create_response.py @@ -0,0 +1,68 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .audio_transcription import AudioTranscription +from .noise_reduction_type import NoiseReductionType +from .realtime_audio_formats import RealtimeAudioFormats +from .realtime_transcription_session_turn_detection import RealtimeTranscriptionSessionTurnDetection + +__all__ = ["RealtimeTranscriptionSessionCreateResponse", "Audio", "AudioInput", "AudioInputNoiseReduction"] + + +class AudioInputNoiseReduction(BaseModel): + type: Optional[NoiseReductionType] = None + """Type of noise reduction. + + `near_field` is for close-talking microphones such as headphones, `far_field` is + for far-field microphones such as laptop or conference room microphones. + """ + + +class AudioInput(BaseModel): + format: Optional[RealtimeAudioFormats] = None + """The PCM audio format. Only a 24kHz sample rate is supported.""" + + noise_reduction: Optional[AudioInputNoiseReduction] = None + """Configuration for input audio noise reduction.""" + + transcription: Optional[AudioTranscription] = None + """Configuration of the transcription model.""" + + turn_detection: Optional[RealtimeTranscriptionSessionTurnDetection] = None + """Configuration for turn detection. + + Can be set to `null` to turn off. Server VAD means that the model will detect + the start and end of speech based on audio volume and respond at the end of user + speech. + """ + + +class Audio(BaseModel): + input: Optional[AudioInput] = None + + +class RealtimeTranscriptionSessionCreateResponse(BaseModel): + id: str + """Unique identifier for the session that looks like `sess_1234567890abcdef`.""" + + object: str + """The object type. Always `realtime.transcription_session`.""" + + type: Literal["transcription"] + """The type of session. Always `transcription` for transcription sessions.""" + + audio: Optional[Audio] = None + """Configuration for input audio for the session.""" + + expires_at: Optional[int] = None + """Expiration timestamp for the session, in seconds since epoch.""" + + include: Optional[List[Literal["item.input_audio_transcription.logprobs"]]] = None + """Additional fields to include in server outputs. + + - `item.input_audio_transcription.logprobs`: Include logprobs for input audio + transcription. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_turn_detection.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_turn_detection.py new file mode 100644 index 0000000000000000000000000000000000000000..f5da31ce77ab4c954ebc8b9b460cec098e17882c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_transcription_session_turn_detection.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["RealtimeTranscriptionSessionTurnDetection"] + + +class RealtimeTranscriptionSessionTurnDetection(BaseModel): + prefix_padding_ms: Optional[int] = None + """Amount of audio to include before the VAD detected speech (in milliseconds). + + Defaults to 300ms. + """ + + silence_duration_ms: Optional[int] = None + """Duration of silence to detect speech stop (in milliseconds). + + Defaults to 500ms. With shorter values the model will respond more quickly, but + may jump in on short pauses from the user. + """ + + threshold: Optional[float] = None + """Activation threshold for VAD (0.0 to 1.0), this defaults to 0.5. + + A higher threshold will require louder audio to activate the model, and thus + might perform better in noisy environments. + """ + + type: Optional[str] = None + """Type of turn detection, only `server_vad` is currently supported.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation.py new file mode 100644 index 0000000000000000000000000000000000000000..515f869071710eb83cbf50bb144ce37df8ba40e0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from .realtime_truncation_retention_ratio import RealtimeTruncationRetentionRatio + +__all__ = ["RealtimeTruncation"] + +RealtimeTruncation: TypeAlias = Union[Literal["auto", "disabled"], RealtimeTruncationRetentionRatio] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_param.py new file mode 100644 index 0000000000000000000000000000000000000000..5e42b27418dd3c2b960888333c999dc4a943be4a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_param.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from .realtime_truncation_retention_ratio_param import RealtimeTruncationRetentionRatioParam + +__all__ = ["RealtimeTruncationParam"] + +RealtimeTruncationParam: TypeAlias = Union[Literal["auto", "disabled"], RealtimeTruncationRetentionRatioParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio.py new file mode 100644 index 0000000000000000000000000000000000000000..b40427244e013822e331a308f9c331080a09752e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeTruncationRetentionRatio"] + + +class RealtimeTruncationRetentionRatio(BaseModel): + retention_ratio: float + """ + Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the + conversation exceeds the input token limit. + """ + + type: Literal["retention_ratio"] + """Use retention ratio truncation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio_param.py new file mode 100644 index 0000000000000000000000000000000000000000..b65d65666a415888874a0228b1a66f46fdd3b4e7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/realtime_truncation_retention_ratio_param.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["RealtimeTruncationRetentionRatioParam"] + + +class RealtimeTruncationRetentionRatioParam(TypedDict, total=False): + retention_ratio: Required[float] + """ + Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the + conversation exceeds the input token limit. + """ + + type: Required[Literal["retention_ratio"]] + """Use retention ratio truncation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..d92c5462d0f5eed22a9490729036e9948fc33b26 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_delta_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioDeltaEvent"] + + +class ResponseAudioDeltaEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + delta: str + """Base64-encoded audio data delta.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.output_audio.delta"] + """The event type, must be `response.output_audio.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..5ea0f07e36d220d9666821783e181b38557330a6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_done_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioDoneEvent"] + + +class ResponseAudioDoneEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.output_audio.done"] + """The event type, must be `response.output_audio.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..4dd5fecac0db91253e652f5dab234468e56814d5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_delta_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioTranscriptDeltaEvent"] + + +class ResponseAudioTranscriptDeltaEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + delta: str + """The transcript delta.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.output_audio_transcript.delta"] + """The event type, must be `response.output_audio_transcript.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..2de913d2774a20e9d6145424f6de3179dfe596b7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_audio_transcript_done_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioTranscriptDoneEvent"] + + +class ResponseAudioTranscriptDoneEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + transcript: str + """The final transcript of the audio.""" + + type: Literal["response.output_audio_transcript.done"] + """The event type, must be `response.output_audio_transcript.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event.py new file mode 100644 index 0000000000000000000000000000000000000000..15dc141cbf5f6bb7c68909d7ef8f29e44a1ef026 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCancelEvent"] + + +class ResponseCancelEvent(BaseModel): + type: Literal["response.cancel"] + """The event type, must be `response.cancel`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" + + response_id: Optional[str] = None + """ + A specific response ID to cancel - if not provided, will cancel an in-progress + response in the default conversation. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f33740730af3210602799522684bce3134092d7e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_cancel_event_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseCancelEventParam"] + + +class ResponseCancelEventParam(TypedDict, total=False): + type: Required[Literal["response.cancel"]] + """The event type, must be `response.cancel`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" + + response_id: str + """ + A specific response ID to cancel - if not provided, will cancel an in-progress + response in the default conversation. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..aca965c3d82c611624f82a410a01d31cee6af708 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_added_event.py @@ -0,0 +1,45 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseContentPartAddedEvent", "Part"] + + +class Part(BaseModel): + audio: Optional[str] = None + """Base64-encoded audio data (if type is "audio").""" + + text: Optional[str] = None + """The text content (if type is "text").""" + + transcript: Optional[str] = None + """The transcript of the audio (if type is "audio").""" + + type: Optional[Literal["text", "audio"]] = None + """The content type ("text", "audio").""" + + +class ResponseContentPartAddedEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item to which the content part was added.""" + + output_index: int + """The index of the output item in the response.""" + + part: Part + """The content part that was added.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.content_part.added"] + """The event type, must be `response.content_part.added`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..59af808a90b660677a530bb912b501d9e3eac414 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_content_part_done_event.py @@ -0,0 +1,45 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseContentPartDoneEvent", "Part"] + + +class Part(BaseModel): + audio: Optional[str] = None + """Base64-encoded audio data (if type is "audio").""" + + text: Optional[str] = None + """The text content (if type is "text").""" + + transcript: Optional[str] = None + """The transcript of the audio (if type is "audio").""" + + type: Optional[Literal["text", "audio"]] = None + """The content type ("text", "audio").""" + + +class ResponseContentPartDoneEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + part: Part + """The content part that is done.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.content_part.done"] + """The event type, must be `response.content_part.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event.py new file mode 100644 index 0000000000000000000000000000000000000000..75a08ee4603729a699871c9676ab812593380b02 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_response_create_params import RealtimeResponseCreateParams + +__all__ = ["ResponseCreateEvent"] + + +class ResponseCreateEvent(BaseModel): + type: Literal["response.create"] + """The event type, must be `response.create`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event.""" + + response: Optional[RealtimeResponseCreateParams] = None + """Create a new Realtime response with these parameters""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..e5dd46d9b68ec5450c8f3941a2b7f58ba563f2bd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_create_event_param.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .realtime_response_create_params_param import RealtimeResponseCreateParamsParam + +__all__ = ["ResponseCreateEventParam"] + + +class ResponseCreateEventParam(TypedDict, total=False): + type: Required[Literal["response.create"]] + """The event type, must be `response.create`.""" + + event_id: str + """Optional client-generated ID used to identify this event.""" + + response: RealtimeResponseCreateParamsParam + """Create a new Realtime response with these parameters""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_created_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_created_event.py new file mode 100644 index 0000000000000000000000000000000000000000..996bf26f754efef14d6ba92b974ac4704dc937e6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_created_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_response import RealtimeResponse + +__all__ = ["ResponseCreatedEvent"] + + +class ResponseCreatedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + response: RealtimeResponse + """The response resource.""" + + type: Literal["response.created"] + """The event type, must be `response.created`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..ce9a4b9f1dae8cf5884907f5b6a318c367ca2a0a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_done_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .realtime_response import RealtimeResponse + +__all__ = ["ResponseDoneEvent"] + + +class ResponseDoneEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + response: RealtimeResponse + """The response resource.""" + + type: Literal["response.done"] + """The event type, must be `response.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..6d96e78b24ba98c7c7d4858e6f556c0800ddda8e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_delta_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionCallArgumentsDeltaEvent"] + + +class ResponseFunctionCallArgumentsDeltaEvent(BaseModel): + call_id: str + """The ID of the function call.""" + + delta: str + """The arguments delta as a JSON string.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the function call item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.function_call_arguments.delta"] + """The event type, must be `response.function_call_arguments.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..be7fae9a1b201ebc351e151c93dd08c68d6aa6bd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_function_call_arguments_done_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionCallArgumentsDoneEvent"] + + +class ResponseFunctionCallArgumentsDoneEvent(BaseModel): + arguments: str + """The final arguments as a JSON string.""" + + call_id: str + """The ID of the function call.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the function call item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.function_call_arguments.done"] + """The event type, must be `response.function_call_arguments.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_delta.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_delta.py new file mode 100644 index 0000000000000000000000000000000000000000..0a02a1a578158d24c937fea5029120f055630bdd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_delta.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallArgumentsDelta"] + + +class ResponseMcpCallArgumentsDelta(BaseModel): + delta: str + """The JSON-encoded arguments delta.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP tool call item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.mcp_call_arguments.delta"] + """The event type, must be `response.mcp_call_arguments.delta`.""" + + obfuscation: Optional[str] = None + """If present, indicates the delta text was obfuscated.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_done.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_done.py new file mode 100644 index 0000000000000000000000000000000000000000..5ec95f172876181ae1f07c0bd400641c496863c7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_arguments_done.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallArgumentsDone"] + + +class ResponseMcpCallArgumentsDone(BaseModel): + arguments: str + """The final JSON-encoded arguments string.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP tool call item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.mcp_call_arguments.done"] + """The event type, must be `response.mcp_call_arguments.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_completed.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_completed.py new file mode 100644 index 0000000000000000000000000000000000000000..e3fcec21f0dd5923f715c59b209d92299afc367a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_completed.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallCompleted"] + + +class ResponseMcpCallCompleted(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP tool call item.""" + + output_index: int + """The index of the output item in the response.""" + + type: Literal["response.mcp_call.completed"] + """The event type, must be `response.mcp_call.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_failed.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_failed.py new file mode 100644 index 0000000000000000000000000000000000000000..b7adc8c2a7e99706d226a3a1c4a28fe692b4b693 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_failed.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallFailed"] + + +class ResponseMcpCallFailed(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP tool call item.""" + + output_index: int + """The index of the output item in the response.""" + + type: Literal["response.mcp_call.failed"] + """The event type, must be `response.mcp_call.failed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_in_progress.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_in_progress.py new file mode 100644 index 0000000000000000000000000000000000000000..d0fcc7615c15e236a98bd4ee14290cb543fbf5d0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_mcp_call_in_progress.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallInProgress"] + + +class ResponseMcpCallInProgress(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the MCP tool call item.""" + + output_index: int + """The index of the output item in the response.""" + + type: Literal["response.mcp_call.in_progress"] + """The event type, must be `response.mcp_call.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..509dfcaeafcd40bb9c5ce78656d9a48c9455baba --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_added_event.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ResponseOutputItemAddedEvent"] + + +class ResponseOutputItemAddedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + output_index: int + """The index of the output item in the Response.""" + + response_id: str + """The ID of the Response to which the item belongs.""" + + type: Literal["response.output_item.added"] + """The event type, must be `response.output_item.added`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..800e4ae8ee1473af0bbf72adea178be748846aa5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_output_item_done_event.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .conversation_item import ConversationItem + +__all__ = ["ResponseOutputItemDoneEvent"] + + +class ResponseOutputItemDoneEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + item: ConversationItem + """A single item within a Realtime conversation.""" + + output_index: int + """The index of the output item in the Response.""" + + response_id: str + """The ID of the Response to which the item belongs.""" + + type: Literal["response.output_item.done"] + """The event type, must be `response.output_item.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..493348aa22e06455ba205e52ea7dd1529bdbcfd0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_delta_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseTextDeltaEvent"] + + +class ResponseTextDeltaEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + delta: str + """The text delta.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + type: Literal["response.output_text.delta"] + """The event type, must be `response.output_text.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..83c6cf06944449b69c37cac857d1f3ead8beceba --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/response_text_done_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseTextDoneEvent"] + + +class ResponseTextDoneEvent(BaseModel): + content_index: int + """The index of the content part in the item's content array.""" + + event_id: str + """The unique ID of the server event.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item in the response.""" + + response_id: str + """The ID of the response.""" + + text: str + """The final text content.""" + + type: Literal["response.output_text.done"] + """The event type, must be `response.output_text.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/session_created_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_created_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b5caad35d7950a8c1372fae55d3e7e6c0b0d32f8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_created_event.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .realtime_session_create_request import RealtimeSessionCreateRequest +from .realtime_transcription_session_create_request import RealtimeTranscriptionSessionCreateRequest + +__all__ = ["SessionCreatedEvent", "Session"] + +Session: TypeAlias = Union[RealtimeSessionCreateRequest, RealtimeTranscriptionSessionCreateRequest] + + +class SessionCreatedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + session: Session + """The session configuration.""" + + type: Literal["session.created"] + """The event type, must be `session.created`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event.py new file mode 100644 index 0000000000000000000000000000000000000000..2e226162c42d06acc1b2262ee13a39cd8a2e8cc6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .realtime_session_create_request import RealtimeSessionCreateRequest +from .realtime_transcription_session_create_request import RealtimeTranscriptionSessionCreateRequest + +__all__ = ["SessionUpdateEvent", "Session"] + +Session: TypeAlias = Union[RealtimeSessionCreateRequest, RealtimeTranscriptionSessionCreateRequest] + + +class SessionUpdateEvent(BaseModel): + session: Session + """Update the Realtime session. + + Choose either a realtime session or a transcription session. + """ + + type: Literal["session.update"] + """The event type, must be `session.update`.""" + + event_id: Optional[str] = None + """Optional client-generated ID used to identify this event. + + This is an arbitrary string that a client may assign. It will be passed back if + there is an error with the event, but the corresponding `session.updated` event + will not include it. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event_param.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event_param.py new file mode 100644 index 0000000000000000000000000000000000000000..59623614314aec9b891e8bf92ad8cf704fe30e3b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_update_event_param.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .realtime_session_create_request_param import RealtimeSessionCreateRequestParam +from .realtime_transcription_session_create_request_param import RealtimeTranscriptionSessionCreateRequestParam + +__all__ = ["SessionUpdateEventParam", "Session"] + +Session: TypeAlias = Union[RealtimeSessionCreateRequestParam, RealtimeTranscriptionSessionCreateRequestParam] + + +class SessionUpdateEventParam(TypedDict, total=False): + session: Required[Session] + """Update the Realtime session. + + Choose either a realtime session or a transcription session. + """ + + type: Required[Literal["session.update"]] + """The event type, must be `session.update`.""" + + event_id: str + """Optional client-generated ID used to identify this event. + + This is an arbitrary string that a client may assign. It will be passed back if + there is an error with the event, but the corresponding `session.updated` event + will not include it. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/realtime/session_updated_event.py b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_updated_event.py new file mode 100644 index 0000000000000000000000000000000000000000..eb7ee0332d47d80522af1b75039a6f61d30e10a5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/realtime/session_updated_event.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .realtime_session_create_request import RealtimeSessionCreateRequest +from .realtime_transcription_session_create_request import RealtimeTranscriptionSessionCreateRequest + +__all__ = ["SessionUpdatedEvent", "Session"] + +Session: TypeAlias = Union[RealtimeSessionCreateRequest, RealtimeTranscriptionSessionCreateRequest] + + +class SessionUpdatedEvent(BaseModel): + event_id: str + """The unique ID of the server event.""" + + session: Session + """The session configuration.""" + + type: Literal["session.updated"] + """The event type, must be `session.updated`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/responses/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..d59f0a74b8d895e50d21f58d98d11b5a3a07a9be --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/__init__.py @@ -0,0 +1,232 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .tool import Tool as Tool +from .response import Response as Response +from .tool_param import ToolParam as ToolParam +from .custom_tool import CustomTool as CustomTool +from .computer_tool import ComputerTool as ComputerTool +from .function_tool import FunctionTool as FunctionTool +from .response_item import ResponseItem as ResponseItem +from .response_error import ResponseError as ResponseError +from .response_usage import ResponseUsage as ResponseUsage +from .parsed_response import ( + ParsedContent as ParsedContent, + ParsedResponse as ParsedResponse, + ParsedResponseOutputItem as ParsedResponseOutputItem, + ParsedResponseOutputText as ParsedResponseOutputText, + ParsedResponseOutputMessage as ParsedResponseOutputMessage, + ParsedResponseFunctionToolCall as ParsedResponseFunctionToolCall, +) +from .response_prompt import ResponsePrompt as ResponsePrompt +from .response_status import ResponseStatus as ResponseStatus +from .tool_choice_mcp import ToolChoiceMcp as ToolChoiceMcp +from .web_search_tool import WebSearchTool as WebSearchTool +from .file_search_tool import FileSearchTool as FileSearchTool +from .custom_tool_param import CustomToolParam as CustomToolParam +from .tool_choice_types import ToolChoiceTypes as ToolChoiceTypes +from .easy_input_message import EasyInputMessage as EasyInputMessage +from .response_item_list import ResponseItemList as ResponseItemList +from .tool_choice_custom import ToolChoiceCustom as ToolChoiceCustom +from .computer_tool_param import ComputerToolParam as ComputerToolParam +from .function_tool_param import FunctionToolParam as FunctionToolParam +from .response_includable import ResponseIncludable as ResponseIncludable +from .response_input_file import ResponseInputFile as ResponseInputFile +from .response_input_item import ResponseInputItem as ResponseInputItem +from .response_input_text import ResponseInputText as ResponseInputText +from .tool_choice_allowed import ToolChoiceAllowed as ToolChoiceAllowed +from .tool_choice_options import ToolChoiceOptions as ToolChoiceOptions +from .response_error_event import ResponseErrorEvent as ResponseErrorEvent +from .response_input_audio import ResponseInputAudio as ResponseInputAudio +from .response_input_image import ResponseInputImage as ResponseInputImage +from .response_input_param import ResponseInputParam as ResponseInputParam +from .response_output_item import ResponseOutputItem as ResponseOutputItem +from .response_output_text import ResponseOutputText as ResponseOutputText +from .response_text_config import ResponseTextConfig as ResponseTextConfig +from .tool_choice_function import ToolChoiceFunction as ToolChoiceFunction +from .response_failed_event import ResponseFailedEvent as ResponseFailedEvent +from .response_prompt_param import ResponsePromptParam as ResponsePromptParam +from .response_queued_event import ResponseQueuedEvent as ResponseQueuedEvent +from .response_stream_event import ResponseStreamEvent as ResponseStreamEvent +from .tool_choice_mcp_param import ToolChoiceMcpParam as ToolChoiceMcpParam +from .web_search_tool_param import WebSearchToolParam as WebSearchToolParam +from .file_search_tool_param import FileSearchToolParam as FileSearchToolParam +from .input_item_list_params import InputItemListParams as InputItemListParams +from .response_create_params import ResponseCreateParams as ResponseCreateParams +from .response_created_event import ResponseCreatedEvent as ResponseCreatedEvent +from .response_input_content import ResponseInputContent as ResponseInputContent +from .response_output_message import ResponseOutputMessage as ResponseOutputMessage +from .response_output_refusal import ResponseOutputRefusal as ResponseOutputRefusal +from .response_reasoning_item import ResponseReasoningItem as ResponseReasoningItem +from .tool_choice_types_param import ToolChoiceTypesParam as ToolChoiceTypesParam +from .web_search_preview_tool import WebSearchPreviewTool as WebSearchPreviewTool +from .easy_input_message_param import EasyInputMessageParam as EasyInputMessageParam +from .response_completed_event import ResponseCompletedEvent as ResponseCompletedEvent +from .response_retrieve_params import ResponseRetrieveParams as ResponseRetrieveParams +from .response_text_done_event import ResponseTextDoneEvent as ResponseTextDoneEvent +from .tool_choice_custom_param import ToolChoiceCustomParam as ToolChoiceCustomParam +from .response_audio_done_event import ResponseAudioDoneEvent as ResponseAudioDoneEvent +from .response_custom_tool_call import ResponseCustomToolCall as ResponseCustomToolCall +from .response_incomplete_event import ResponseIncompleteEvent as ResponseIncompleteEvent +from .response_input_file_param import ResponseInputFileParam as ResponseInputFileParam +from .response_input_item_param import ResponseInputItemParam as ResponseInputItemParam +from .response_input_text_param import ResponseInputTextParam as ResponseInputTextParam +from .response_text_delta_event import ResponseTextDeltaEvent as ResponseTextDeltaEvent +from .tool_choice_allowed_param import ToolChoiceAllowedParam as ToolChoiceAllowedParam +from .response_audio_delta_event import ResponseAudioDeltaEvent as ResponseAudioDeltaEvent +from .response_in_progress_event import ResponseInProgressEvent as ResponseInProgressEvent +from .response_input_audio_param import ResponseInputAudioParam as ResponseInputAudioParam +from .response_input_image_param import ResponseInputImageParam as ResponseInputImageParam +from .response_output_text_param import ResponseOutputTextParam as ResponseOutputTextParam +from .response_text_config_param import ResponseTextConfigParam as ResponseTextConfigParam +from .tool_choice_function_param import ToolChoiceFunctionParam as ToolChoiceFunctionParam +from .response_computer_tool_call import ResponseComputerToolCall as ResponseComputerToolCall +from .response_conversation_param import ResponseConversationParam as ResponseConversationParam +from .response_format_text_config import ResponseFormatTextConfig as ResponseFormatTextConfig +from .response_function_tool_call import ResponseFunctionToolCall as ResponseFunctionToolCall +from .response_input_message_item import ResponseInputMessageItem as ResponseInputMessageItem +from .response_refusal_done_event import ResponseRefusalDoneEvent as ResponseRefusalDoneEvent +from .response_function_web_search import ResponseFunctionWebSearch as ResponseFunctionWebSearch +from .response_input_content_param import ResponseInputContentParam as ResponseInputContentParam +from .response_refusal_delta_event import ResponseRefusalDeltaEvent as ResponseRefusalDeltaEvent +from .response_output_message_param import ResponseOutputMessageParam as ResponseOutputMessageParam +from .response_output_refusal_param import ResponseOutputRefusalParam as ResponseOutputRefusalParam +from .response_reasoning_item_param import ResponseReasoningItemParam as ResponseReasoningItemParam +from .web_search_preview_tool_param import WebSearchPreviewToolParam as WebSearchPreviewToolParam +from .response_file_search_tool_call import ResponseFileSearchToolCall as ResponseFileSearchToolCall +from .response_mcp_call_failed_event import ResponseMcpCallFailedEvent as ResponseMcpCallFailedEvent +from .response_custom_tool_call_param import ResponseCustomToolCallParam as ResponseCustomToolCallParam +from .response_output_item_done_event import ResponseOutputItemDoneEvent as ResponseOutputItemDoneEvent +from .response_content_part_done_event import ResponseContentPartDoneEvent as ResponseContentPartDoneEvent +from .response_custom_tool_call_output import ResponseCustomToolCallOutput as ResponseCustomToolCallOutput +from .response_function_tool_call_item import ResponseFunctionToolCallItem as ResponseFunctionToolCallItem +from .response_output_item_added_event import ResponseOutputItemAddedEvent as ResponseOutputItemAddedEvent +from .response_computer_tool_call_param import ResponseComputerToolCallParam as ResponseComputerToolCallParam +from .response_content_part_added_event import ResponseContentPartAddedEvent as ResponseContentPartAddedEvent +from .response_format_text_config_param import ResponseFormatTextConfigParam as ResponseFormatTextConfigParam +from .response_function_tool_call_param import ResponseFunctionToolCallParam as ResponseFunctionToolCallParam +from .response_mcp_call_completed_event import ResponseMcpCallCompletedEvent as ResponseMcpCallCompletedEvent +from .response_function_web_search_param import ResponseFunctionWebSearchParam as ResponseFunctionWebSearchParam +from .response_reasoning_text_done_event import ResponseReasoningTextDoneEvent as ResponseReasoningTextDoneEvent +from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall as ResponseCodeInterpreterToolCall +from .response_input_message_content_list import ResponseInputMessageContentList as ResponseInputMessageContentList +from .response_mcp_call_in_progress_event import ResponseMcpCallInProgressEvent as ResponseMcpCallInProgressEvent +from .response_reasoning_text_delta_event import ResponseReasoningTextDeltaEvent as ResponseReasoningTextDeltaEvent +from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent as ResponseAudioTranscriptDoneEvent +from .response_file_search_tool_call_param import ResponseFileSearchToolCallParam as ResponseFileSearchToolCallParam +from .response_mcp_list_tools_failed_event import ResponseMcpListToolsFailedEvent as ResponseMcpListToolsFailedEvent +from .response_audio_transcript_delta_event import ( + ResponseAudioTranscriptDeltaEvent as ResponseAudioTranscriptDeltaEvent, +) +from .response_custom_tool_call_output_param import ( + ResponseCustomToolCallOutputParam as ResponseCustomToolCallOutputParam, +) +from .response_mcp_call_arguments_done_event import ( + ResponseMcpCallArgumentsDoneEvent as ResponseMcpCallArgumentsDoneEvent, +) +from .response_computer_tool_call_output_item import ( + ResponseComputerToolCallOutputItem as ResponseComputerToolCallOutputItem, +) +from .response_format_text_json_schema_config import ( + ResponseFormatTextJSONSchemaConfig as ResponseFormatTextJSONSchemaConfig, +) +from .response_function_tool_call_output_item import ( + ResponseFunctionToolCallOutputItem as ResponseFunctionToolCallOutputItem, +) +from .response_image_gen_call_completed_event import ( + ResponseImageGenCallCompletedEvent as ResponseImageGenCallCompletedEvent, +) +from .response_mcp_call_arguments_delta_event import ( + ResponseMcpCallArgumentsDeltaEvent as ResponseMcpCallArgumentsDeltaEvent, +) +from .response_mcp_list_tools_completed_event import ( + ResponseMcpListToolsCompletedEvent as ResponseMcpListToolsCompletedEvent, +) +from .response_image_gen_call_generating_event import ( + ResponseImageGenCallGeneratingEvent as ResponseImageGenCallGeneratingEvent, +) +from .response_web_search_call_completed_event import ( + ResponseWebSearchCallCompletedEvent as ResponseWebSearchCallCompletedEvent, +) +from .response_web_search_call_searching_event import ( + ResponseWebSearchCallSearchingEvent as ResponseWebSearchCallSearchingEvent, +) +from .response_code_interpreter_tool_call_param import ( + ResponseCodeInterpreterToolCallParam as ResponseCodeInterpreterToolCallParam, +) +from .response_file_search_call_completed_event import ( + ResponseFileSearchCallCompletedEvent as ResponseFileSearchCallCompletedEvent, +) +from .response_file_search_call_searching_event import ( + ResponseFileSearchCallSearchingEvent as ResponseFileSearchCallSearchingEvent, +) +from .response_image_gen_call_in_progress_event import ( + ResponseImageGenCallInProgressEvent as ResponseImageGenCallInProgressEvent, +) +from .response_input_message_content_list_param import ( + ResponseInputMessageContentListParam as ResponseInputMessageContentListParam, +) +from .response_mcp_list_tools_in_progress_event import ( + ResponseMcpListToolsInProgressEvent as ResponseMcpListToolsInProgressEvent, +) +from .response_custom_tool_call_input_done_event import ( + ResponseCustomToolCallInputDoneEvent as ResponseCustomToolCallInputDoneEvent, +) +from .response_reasoning_summary_part_done_event import ( + ResponseReasoningSummaryPartDoneEvent as ResponseReasoningSummaryPartDoneEvent, +) +from .response_reasoning_summary_text_done_event import ( + ResponseReasoningSummaryTextDoneEvent as ResponseReasoningSummaryTextDoneEvent, +) +from .response_web_search_call_in_progress_event import ( + ResponseWebSearchCallInProgressEvent as ResponseWebSearchCallInProgressEvent, +) +from .response_custom_tool_call_input_delta_event import ( + ResponseCustomToolCallInputDeltaEvent as ResponseCustomToolCallInputDeltaEvent, +) +from .response_file_search_call_in_progress_event import ( + ResponseFileSearchCallInProgressEvent as ResponseFileSearchCallInProgressEvent, +) +from .response_function_call_arguments_done_event import ( + ResponseFunctionCallArgumentsDoneEvent as ResponseFunctionCallArgumentsDoneEvent, +) +from .response_image_gen_call_partial_image_event import ( + ResponseImageGenCallPartialImageEvent as ResponseImageGenCallPartialImageEvent, +) +from .response_output_text_annotation_added_event import ( + ResponseOutputTextAnnotationAddedEvent as ResponseOutputTextAnnotationAddedEvent, +) +from .response_reasoning_summary_part_added_event import ( + ResponseReasoningSummaryPartAddedEvent as ResponseReasoningSummaryPartAddedEvent, +) +from .response_reasoning_summary_text_delta_event import ( + ResponseReasoningSummaryTextDeltaEvent as ResponseReasoningSummaryTextDeltaEvent, +) +from .response_function_call_arguments_delta_event import ( + ResponseFunctionCallArgumentsDeltaEvent as ResponseFunctionCallArgumentsDeltaEvent, +) +from .response_computer_tool_call_output_screenshot import ( + ResponseComputerToolCallOutputScreenshot as ResponseComputerToolCallOutputScreenshot, +) +from .response_format_text_json_schema_config_param import ( + ResponseFormatTextJSONSchemaConfigParam as ResponseFormatTextJSONSchemaConfigParam, +) +from .response_code_interpreter_call_code_done_event import ( + ResponseCodeInterpreterCallCodeDoneEvent as ResponseCodeInterpreterCallCodeDoneEvent, +) +from .response_code_interpreter_call_completed_event import ( + ResponseCodeInterpreterCallCompletedEvent as ResponseCodeInterpreterCallCompletedEvent, +) +from .response_code_interpreter_call_code_delta_event import ( + ResponseCodeInterpreterCallCodeDeltaEvent as ResponseCodeInterpreterCallCodeDeltaEvent, +) +from .response_code_interpreter_call_in_progress_event import ( + ResponseCodeInterpreterCallInProgressEvent as ResponseCodeInterpreterCallInProgressEvent, +) +from .response_code_interpreter_call_interpreting_event import ( + ResponseCodeInterpreterCallInterpretingEvent as ResponseCodeInterpreterCallInterpretingEvent, +) +from .response_computer_tool_call_output_screenshot_param import ( + ResponseComputerToolCallOutputScreenshotParam as ResponseComputerToolCallOutputScreenshotParam, +) diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..5b844f5bf4a354ecf6520f7491096fea91a5b9fc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ComputerTool"] + + +class ComputerTool(BaseModel): + display_height: int + """The height of the computer display.""" + + display_width: int + """The width of the computer display.""" + + environment: Literal["windows", "mac", "linux", "ubuntu", "browser"] + """The type of computer environment to control.""" + + type: Literal["computer_use_preview"] + """The type of the computer use tool. Always `computer_use_preview`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..06a5c132ec5eac31081c2a242d753538a54c7b15 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/computer_tool_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ComputerToolParam"] + + +class ComputerToolParam(TypedDict, total=False): + display_height: Required[int] + """The height of the computer display.""" + + display_width: Required[int] + """The width of the computer display.""" + + environment: Required[Literal["windows", "mac", "linux", "ubuntu", "browser"]] + """The type of computer environment to control.""" + + type: Required[Literal["computer_use_preview"]] + """The type of the computer use tool. Always `computer_use_preview`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..c16ae715ebac810f659c2b134f369b5452ad7944 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from ..shared.custom_tool_input_format import CustomToolInputFormat + +__all__ = ["CustomTool"] + + +class CustomTool(BaseModel): + name: str + """The name of the custom tool, used to identify it in tool calls.""" + + type: Literal["custom"] + """The type of the custom tool. Always `custom`.""" + + description: Optional[str] = None + """Optional description of the custom tool, used to provide more context.""" + + format: Optional[CustomToolInputFormat] = None + """The input format for the custom tool. Default is unconstrained text.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..2afc8b19b8f519ed0af6c1010507e8f6e525d6f1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/custom_tool_param.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from ..shared_params.custom_tool_input_format import CustomToolInputFormat + +__all__ = ["CustomToolParam"] + + +class CustomToolParam(TypedDict, total=False): + name: Required[str] + """The name of the custom tool, used to identify it in tool calls.""" + + type: Required[Literal["custom"]] + """The type of the custom tool. Always `custom`.""" + + description: str + """Optional description of the custom tool, used to provide more context.""" + + format: CustomToolInputFormat + """The input format for the custom tool. Default is unconstrained text.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message.py b/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message.py new file mode 100644 index 0000000000000000000000000000000000000000..4ed0194f9fce2d6c2c9c4290bf4706c074669745 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_input_message_content_list import ResponseInputMessageContentList + +__all__ = ["EasyInputMessage"] + + +class EasyInputMessage(BaseModel): + content: Union[str, ResponseInputMessageContentList] + """ + Text, image, or audio input to the model, used to generate a response. Can also + contain previous assistant responses. + """ + + role: Literal["user", "assistant", "system", "developer"] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always `message`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message_param.py new file mode 100644 index 0000000000000000000000000000000000000000..ef2f1c5f37d9005bc5023912569485a2e6fb26d1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/easy_input_message_param.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypedDict + +from .response_input_message_content_list_param import ResponseInputMessageContentListParam + +__all__ = ["EasyInputMessageParam"] + + +class EasyInputMessageParam(TypedDict, total=False): + content: Required[Union[str, ResponseInputMessageContentListParam]] + """ + Text, image, or audio input to the model, used to generate a response. Can also + contain previous assistant responses. + """ + + role: Required[Literal["user", "assistant", "system", "developer"]] + """The role of the message input. + + One of `user`, `assistant`, `system`, or `developer`. + """ + + type: Literal["message"] + """The type of the message input. Always `message`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..dbdd8cffab362ac3f5aa0419b8fb14b7f7479968 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool.py @@ -0,0 +1,44 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from ..shared.compound_filter import CompoundFilter +from ..shared.comparison_filter import ComparisonFilter + +__all__ = ["FileSearchTool", "Filters", "RankingOptions"] + +Filters: TypeAlias = Union[ComparisonFilter, CompoundFilter, None] + + +class RankingOptions(BaseModel): + ranker: Optional[Literal["auto", "default-2024-11-15"]] = None + """The ranker to use for the file search.""" + + score_threshold: Optional[float] = None + """The score threshold for the file search, a number between 0 and 1. + + Numbers closer to 1 will attempt to return only the most relevant results, but + may return fewer results. + """ + + +class FileSearchTool(BaseModel): + type: Literal["file_search"] + """The type of the file search tool. Always `file_search`.""" + + vector_store_ids: List[str] + """The IDs of the vector stores to search.""" + + filters: Optional[Filters] = None + """A filter to apply.""" + + max_num_results: Optional[int] = None + """The maximum number of results to return. + + This number should be between 1 and 50 inclusive. + """ + + ranking_options: Optional[RankingOptions] = None + """Ranking options for search.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..c7641c1b867af5411d799f5ebd8a5e15cad9e7f2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/file_search_tool_param.py @@ -0,0 +1,46 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from ..shared_params.compound_filter import CompoundFilter +from ..shared_params.comparison_filter import ComparisonFilter + +__all__ = ["FileSearchToolParam", "Filters", "RankingOptions"] + +Filters: TypeAlias = Union[ComparisonFilter, CompoundFilter] + + +class RankingOptions(TypedDict, total=False): + ranker: Literal["auto", "default-2024-11-15"] + """The ranker to use for the file search.""" + + score_threshold: float + """The score threshold for the file search, a number between 0 and 1. + + Numbers closer to 1 will attempt to return only the most relevant results, but + may return fewer results. + """ + + +class FileSearchToolParam(TypedDict, total=False): + type: Required[Literal["file_search"]] + """The type of the file search tool. Always `file_search`.""" + + vector_store_ids: Required[SequenceNotStr[str]] + """The IDs of the vector stores to search.""" + + filters: Optional[Filters] + """A filter to apply.""" + + max_num_results: int + """The maximum number of results to return. + + This number should be between 1 and 50 inclusive. + """ + + ranking_options: RankingOptions + """Ranking options for search.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..d881565356b8336c3a23b3b7b97199b060a984bc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["FunctionTool"] + + +class FunctionTool(BaseModel): + name: str + """The name of the function to call.""" + + parameters: Optional[Dict[str, object]] = None + """A JSON schema object describing the parameters of the function.""" + + strict: Optional[bool] = None + """Whether to enforce strict parameter validation. Default `true`.""" + + type: Literal["function"] + """The type of the function tool. Always `function`.""" + + description: Optional[str] = None + """A description of the function. + + Used by the model to determine whether or not to call the function. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..56bab36f47e6aa42f56e6e337ee3a785034a0151 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/function_tool_param.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["FunctionToolParam"] + + +class FunctionToolParam(TypedDict, total=False): + name: Required[str] + """The name of the function to call.""" + + parameters: Required[Optional[Dict[str, object]]] + """A JSON schema object describing the parameters of the function.""" + + strict: Required[Optional[bool]] + """Whether to enforce strict parameter validation. Default `true`.""" + + type: Required[Literal["function"]] + """The type of the function tool. Always `function`.""" + + description: Optional[str] + """A description of the function. + + Used by the model to determine whether or not to call the function. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/input_item_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/responses/input_item_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..44a8dc5de331f93873b7951d978cc53ace7ba4f5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/input_item_list_params.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List +from typing_extensions import Literal, TypedDict + +from .response_includable import ResponseIncludable + +__all__ = ["InputItemListParams"] + + +class InputItemListParams(TypedDict, total=False): + after: str + """An item ID to list items after, used in pagination.""" + + include: List[ResponseIncludable] + """Additional fields to include in the response. + + See the `include` parameter for Response creation above for more information. + """ + + limit: int + """A limit on the number of objects to be returned. + + Limit can range between 1 and 100, and the default is 20. + """ + + order: Literal["asc", "desc"] + """The order to return the input items in. Default is `desc`. + + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/parsed_response.py b/.venv/lib/python3.13/site-packages/openai/types/responses/parsed_response.py new file mode 100644 index 0000000000000000000000000000000000000000..1d9db361ddf0b8edd0243b2117ccad4ce8330ab8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/parsed_response.py @@ -0,0 +1,97 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import TYPE_CHECKING, List, Union, Generic, TypeVar, Optional +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .response import Response +from ..._models import GenericModel +from ..._utils._transform import PropertyInfo +from .response_output_item import ( + McpCall, + McpListTools, + LocalShellCall, + McpApprovalRequest, + ImageGenerationCall, + LocalShellCallAction, +) +from .response_output_text import ResponseOutputText +from .response_output_message import ResponseOutputMessage +from .response_output_refusal import ResponseOutputRefusal +from .response_reasoning_item import ResponseReasoningItem +from .response_custom_tool_call import ResponseCustomToolCall +from .response_computer_tool_call import ResponseComputerToolCall +from .response_function_tool_call import ResponseFunctionToolCall +from .response_function_web_search import ResponseFunctionWebSearch +from .response_file_search_tool_call import ResponseFileSearchToolCall +from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall + +__all__ = ["ParsedResponse", "ParsedResponseOutputMessage", "ParsedResponseOutputText"] + +ContentType = TypeVar("ContentType") + +# we need to disable this check because we're overriding properties +# with subclasses of their types which is technically unsound as +# properties can be mutated. +# pyright: reportIncompatibleVariableOverride=false + + +class ParsedResponseOutputText(ResponseOutputText, GenericModel, Generic[ContentType]): + parsed: Optional[ContentType] = None + + +ParsedContent: TypeAlias = Annotated[ + Union[ParsedResponseOutputText[ContentType], ResponseOutputRefusal], + PropertyInfo(discriminator="type"), +] + + +class ParsedResponseOutputMessage(ResponseOutputMessage, GenericModel, Generic[ContentType]): + if TYPE_CHECKING: + content: List[ParsedContent[ContentType]] # type: ignore[assignment] + else: + content: List[ParsedContent] + + +class ParsedResponseFunctionToolCall(ResponseFunctionToolCall): + parsed_arguments: object = None + + __api_exclude__ = {"parsed_arguments"} + + +ParsedResponseOutputItem: TypeAlias = Annotated[ + Union[ + ParsedResponseOutputMessage[ContentType], + ParsedResponseFunctionToolCall, + ResponseFileSearchToolCall, + ResponseFunctionWebSearch, + ResponseComputerToolCall, + ResponseReasoningItem, + McpCall, + McpApprovalRequest, + ImageGenerationCall, + LocalShellCall, + LocalShellCallAction, + McpListTools, + ResponseCodeInterpreterToolCall, + ResponseCustomToolCall, + ], + PropertyInfo(discriminator="type"), +] + + +class ParsedResponse(Response, GenericModel, Generic[ContentType]): + if TYPE_CHECKING: + output: List[ParsedResponseOutputItem[ContentType]] # type: ignore[assignment] + else: + output: List[ParsedResponseOutputItem] + + @property + def output_parsed(self) -> Optional[ContentType]: + for output in self.output: + if output.type == "message": + for content in output.content: + if content.type == "output_text" and content.parsed: + return content.parsed + + return None diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response.py new file mode 100644 index 0000000000000000000000000000000000000000..a1133a41f5f661b2bb743a9d11dff1114134bf58 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response.py @@ -0,0 +1,290 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, TypeAlias + +from .tool import Tool +from ..._models import BaseModel +from .response_error import ResponseError +from .response_usage import ResponseUsage +from .response_prompt import ResponsePrompt +from .response_status import ResponseStatus +from .tool_choice_mcp import ToolChoiceMcp +from ..shared.metadata import Metadata +from ..shared.reasoning import Reasoning +from .tool_choice_types import ToolChoiceTypes +from .tool_choice_custom import ToolChoiceCustom +from .response_input_item import ResponseInputItem +from .tool_choice_allowed import ToolChoiceAllowed +from .tool_choice_options import ToolChoiceOptions +from .response_output_item import ResponseOutputItem +from .response_text_config import ResponseTextConfig +from .tool_choice_function import ToolChoiceFunction +from ..shared.responses_model import ResponsesModel + +__all__ = ["Response", "IncompleteDetails", "ToolChoice", "Conversation"] + + +class IncompleteDetails(BaseModel): + reason: Optional[Literal["max_output_tokens", "content_filter"]] = None + """The reason why the response is incomplete.""" + + +ToolChoice: TypeAlias = Union[ + ToolChoiceOptions, ToolChoiceAllowed, ToolChoiceTypes, ToolChoiceFunction, ToolChoiceMcp, ToolChoiceCustom +] + + +class Conversation(BaseModel): + id: str + """The unique ID of the conversation.""" + + +class Response(BaseModel): + id: str + """Unique identifier for this Response.""" + + created_at: float + """Unix timestamp (in seconds) of when this Response was created.""" + + error: Optional[ResponseError] = None + """An error object returned when the model fails to generate a Response.""" + + incomplete_details: Optional[IncompleteDetails] = None + """Details about why the response is incomplete.""" + + instructions: Union[str, List[ResponseInputItem], None] = None + """A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple to + swap out system (or developer) messages in new responses. + """ + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: ResponsesModel + """Model ID used to generate the response, like `gpt-4o` or `o3`. + + OpenAI offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the + [model guide](https://platform.openai.com/docs/models) to browse and compare + available models. + """ + + object: Literal["response"] + """The object type of this resource - always set to `response`.""" + + output: List[ResponseOutputItem] + """An array of content items generated by the model. + + - The length and order of items in the `output` array is dependent on the + model's response. + - Rather than accessing the first item in the `output` array and assuming it's + an `assistant` message with the content generated by the model, you might + consider using the `output_text` property where supported in SDKs. + """ + + parallel_tool_calls: bool + """Whether to allow the model to run tool calls in parallel.""" + + temperature: Optional[float] = None + """What sampling temperature to use, between 0 and 2. + + Higher values like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. We generally recommend altering + this or `top_p` but not both. + """ + + tool_choice: ToolChoice + """ + How the model should select which tool (or tools) to use when generating a + response. See the `tools` parameter to see how to specify which tools the model + can call. + """ + + tools: List[Tool] + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers or + predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code with strongly typed arguments and outputs. + Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + You can also use custom tools to call your own code. + """ + + top_p: Optional[float] = None + """ + An alternative to sampling with temperature, called nucleus sampling, where the + model considers the results of the tokens with top_p probability mass. So 0.1 + means only the tokens comprising the top 10% probability mass are considered. + + We generally recommend altering this or `temperature` but not both. + """ + + background: Optional[bool] = None + """ + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + """ + + conversation: Optional[Conversation] = None + """The conversation that this response belongs to. + + Input items and output items from this response are automatically added to this + conversation. + """ + + max_output_tokens: Optional[int] = None + """ + An upper bound for the number of tokens that can be generated for a response, + including visible output tokens and + [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + """ + + max_tool_calls: Optional[int] = None + """ + The maximum number of total calls to built-in tools that can be processed in a + response. This maximum number applies across all built-in tool calls, not per + individual tool. Any further attempts to call a tool by the model will be + ignored. + """ + + previous_response_id: Optional[str] = None + """The unique ID of the previous response to the model. + + Use this to create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). + Cannot be used in conjunction with `conversation`. + """ + + prompt: Optional[ResponsePrompt] = None + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + prompt_cache_key: Optional[str] = None + """ + Used by OpenAI to cache responses for similar requests to optimize your cache + hit rates. Replaces the `user` field. + [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + """ + + reasoning: Optional[Reasoning] = None + """**gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + """ + + safety_identifier: Optional[str] = None + """ + A stable identifier used to help detect users of your application that may be + violating OpenAI's usage policies. The IDs should be a string that uniquely + identifies each user. We recommend hashing their username or email address, in + order to avoid sending us any identifying information. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + """ + + service_tier: Optional[Literal["auto", "default", "flex", "scale", "priority"]] = None + """Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier + configured in the Project settings. Unless otherwise configured, the Project + will use 'default'. + - If set to 'default', then the request will be processed with the standard + pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or + '[priority](https://openai.com/api-priority-processing/)', then the request + will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the + `service_tier` value based on the processing mode actually used to serve the + request. This response value may be different from the value set in the + parameter. + """ + + status: Optional[ResponseStatus] = None + """The status of the response generation. + + One of `completed`, `failed`, `in_progress`, `cancelled`, `queued`, or + `incomplete`. + """ + + text: Optional[ResponseTextConfig] = None + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + top_logprobs: Optional[int] = None + """ + An integer between 0 and 20 specifying the number of most likely tokens to + return at each token position, each with an associated log probability. + """ + + truncation: Optional[Literal["auto", "disabled"]] = None + """The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds the model's context window size, + the model will truncate the response to fit the context window by dropping + items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window size + for a model, the request will fail with a 400 error. + """ + + usage: Optional[ResponseUsage] = None + """ + Represents token usage details including input tokens, output tokens, a + breakdown of output tokens, and the total tokens used. + """ + + user: Optional[str] = None + """This field is being replaced by `safety_identifier` and `prompt_cache_key`. + + Use `prompt_cache_key` instead to maintain caching optimizations. A stable + identifier for your end-users. Used to boost cache hit rates by better bucketing + similar requests and to help OpenAI detect and prevent abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + """ + + @property + def output_text(self) -> str: + """Convenience property that aggregates all `output_text` items from the `output` list. + + If no `output_text` content blocks exist, then an empty string is returned. + """ + texts: List[str] = [] + for output in self.output: + if output.type == "message": + for content in output.content: + if content.type == "output_text": + texts.append(content.text) + + return "".join(texts) diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..6fb7887b8030b3ac986b0b6060096027f4c00829 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_delta_event.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioDeltaEvent"] + + +class ResponseAudioDeltaEvent(BaseModel): + delta: str + """A chunk of Base64 encoded response audio bytes.""" + + sequence_number: int + """A sequence number for this chunk of the stream response.""" + + type: Literal["response.audio.delta"] + """The type of the event. Always `response.audio.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..2592ae8dcdde08788a6fd106cd3a553ec78b389d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_done_event.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioDoneEvent"] + + +class ResponseAudioDoneEvent(BaseModel): + sequence_number: int + """The sequence number of the delta.""" + + type: Literal["response.audio.done"] + """The type of the event. Always `response.audio.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..830c133d614eb56129850cd432445d7b8911b5e3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_delta_event.py @@ -0,0 +1,18 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioTranscriptDeltaEvent"] + + +class ResponseAudioTranscriptDeltaEvent(BaseModel): + delta: str + """The partial transcript of the audio response.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.audio.transcript.delta"] + """The type of the event. Always `response.audio.transcript.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..e39f501cf01c8a9968c2b5e5a821bf628ba0b0d9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_audio_transcript_done_event.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseAudioTranscriptDoneEvent"] + + +class ResponseAudioTranscriptDoneEvent(BaseModel): + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.audio.transcript.done"] + """The type of the event. Always `response.audio.transcript.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..c5fef939b1b9a78daf7c6515407bff2d92abc4a1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_delta_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterCallCodeDeltaEvent"] + + +class ResponseCodeInterpreterCallCodeDeltaEvent(BaseModel): + delta: str + """The partial code snippet being streamed by the code interpreter.""" + + item_id: str + """The unique identifier of the code interpreter tool call item.""" + + output_index: int + """ + The index of the output item in the response for which the code is being + streamed. + """ + + sequence_number: int + """The sequence number of this event, used to order streaming events.""" + + type: Literal["response.code_interpreter_call_code.delta"] + """The type of the event. Always `response.code_interpreter_call_code.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..5201a02d3617124eeb8c94652055126c41aec858 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_code_done_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterCallCodeDoneEvent"] + + +class ResponseCodeInterpreterCallCodeDoneEvent(BaseModel): + code: str + """The final code snippet output by the code interpreter.""" + + item_id: str + """The unique identifier of the code interpreter tool call item.""" + + output_index: int + """The index of the output item in the response for which the code is finalized.""" + + sequence_number: int + """The sequence number of this event, used to order streaming events.""" + + type: Literal["response.code_interpreter_call_code.done"] + """The type of the event. Always `response.code_interpreter_call_code.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..bb9563a16b89ae3bf7d5c1fc0e762775ebc6d2b1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_completed_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterCallCompletedEvent"] + + +class ResponseCodeInterpreterCallCompletedEvent(BaseModel): + item_id: str + """The unique identifier of the code interpreter tool call item.""" + + output_index: int + """ + The index of the output item in the response for which the code interpreter call + is completed. + """ + + sequence_number: int + """The sequence number of this event, used to order streaming events.""" + + type: Literal["response.code_interpreter_call.completed"] + """The type of the event. Always `response.code_interpreter_call.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..9c6b22100486fa2690786426f4522e7590330ee9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_in_progress_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterCallInProgressEvent"] + + +class ResponseCodeInterpreterCallInProgressEvent(BaseModel): + item_id: str + """The unique identifier of the code interpreter tool call item.""" + + output_index: int + """ + The index of the output item in the response for which the code interpreter call + is in progress. + """ + + sequence_number: int + """The sequence number of this event, used to order streaming events.""" + + type: Literal["response.code_interpreter_call.in_progress"] + """The type of the event. Always `response.code_interpreter_call.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_interpreting_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_interpreting_event.py new file mode 100644 index 0000000000000000000000000000000000000000..f6191e41650ba0b40355cac56fdf83d489efa035 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_call_interpreting_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterCallInterpretingEvent"] + + +class ResponseCodeInterpreterCallInterpretingEvent(BaseModel): + item_id: str + """The unique identifier of the code interpreter tool call item.""" + + output_index: int + """ + The index of the output item in the response for which the code interpreter is + interpreting code. + """ + + sequence_number: int + """The sequence number of this event, used to order streaming events.""" + + type: Literal["response.code_interpreter_call.interpreting"] + """The type of the event. Always `response.code_interpreter_call.interpreting`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..ed720ecd42fcf576ac5cbaf99b472acdcaea2cd2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["ResponseCodeInterpreterToolCall", "Output", "OutputLogs", "OutputImage"] + + +class OutputLogs(BaseModel): + logs: str + """The logs output from the code interpreter.""" + + type: Literal["logs"] + """The type of the output. Always 'logs'.""" + + +class OutputImage(BaseModel): + type: Literal["image"] + """The type of the output. Always 'image'.""" + + url: str + """The URL of the image output from the code interpreter.""" + + +Output: TypeAlias = Annotated[Union[OutputLogs, OutputImage], PropertyInfo(discriminator="type")] + + +class ResponseCodeInterpreterToolCall(BaseModel): + id: str + """The unique ID of the code interpreter tool call.""" + + code: Optional[str] = None + """The code to run, or null if not available.""" + + container_id: str + """The ID of the container used to run the code.""" + + outputs: Optional[List[Output]] = None + """ + The outputs generated by the code interpreter, such as logs or images. Can be + null if no outputs are available. + """ + + status: Literal["in_progress", "completed", "incomplete", "interpreting", "failed"] + """The status of the code interpreter tool call. + + Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and + `failed`. + """ + + type: Literal["code_interpreter_call"] + """The type of the code interpreter tool call. Always `code_interpreter_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..78b90ca87e0a92462c111ef437c993d4ae30727f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_code_interpreter_tool_call_param.py @@ -0,0 +1,54 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = ["ResponseCodeInterpreterToolCallParam", "Output", "OutputLogs", "OutputImage"] + + +class OutputLogs(TypedDict, total=False): + logs: Required[str] + """The logs output from the code interpreter.""" + + type: Required[Literal["logs"]] + """The type of the output. Always 'logs'.""" + + +class OutputImage(TypedDict, total=False): + type: Required[Literal["image"]] + """The type of the output. Always 'image'.""" + + url: Required[str] + """The URL of the image output from the code interpreter.""" + + +Output: TypeAlias = Union[OutputLogs, OutputImage] + + +class ResponseCodeInterpreterToolCallParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the code interpreter tool call.""" + + code: Required[Optional[str]] + """The code to run, or null if not available.""" + + container_id: Required[str] + """The ID of the container used to run the code.""" + + outputs: Required[Optional[Iterable[Output]]] + """ + The outputs generated by the code interpreter, such as logs or images. Can be + null if no outputs are available. + """ + + status: Required[Literal["in_progress", "completed", "incomplete", "interpreting", "failed"]] + """The status of the code interpreter tool call. + + Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and + `failed`. + """ + + type: Required[Literal["code_interpreter_call"]] + """The type of the code interpreter tool call. Always `code_interpreter_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..8a2bd51f7596bebd9ded7f3f2106dedb3570bd9e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_completed_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseCompletedEvent"] + + +class ResponseCompletedEvent(BaseModel): + response: Response + """Properties of the completed response.""" + + sequence_number: int + """The sequence number for this event.""" + + type: Literal["response.completed"] + """The type of the event. Always `response.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..994837567afb48387674af5d983f50792e3c86a4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call.py @@ -0,0 +1,212 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = [ + "ResponseComputerToolCall", + "Action", + "ActionClick", + "ActionDoubleClick", + "ActionDrag", + "ActionDragPath", + "ActionKeypress", + "ActionMove", + "ActionScreenshot", + "ActionScroll", + "ActionType", + "ActionWait", + "PendingSafetyCheck", +] + + +class ActionClick(BaseModel): + button: Literal["left", "right", "wheel", "back", "forward"] + """Indicates which mouse button was pressed during the click. + + One of `left`, `right`, `wheel`, `back`, or `forward`. + """ + + type: Literal["click"] + """Specifies the event type. + + For a click action, this property is always set to `click`. + """ + + x: int + """The x-coordinate where the click occurred.""" + + y: int + """The y-coordinate where the click occurred.""" + + +class ActionDoubleClick(BaseModel): + type: Literal["double_click"] + """Specifies the event type. + + For a double click action, this property is always set to `double_click`. + """ + + x: int + """The x-coordinate where the double click occurred.""" + + y: int + """The y-coordinate where the double click occurred.""" + + +class ActionDragPath(BaseModel): + x: int + """The x-coordinate.""" + + y: int + """The y-coordinate.""" + + +class ActionDrag(BaseModel): + path: List[ActionDragPath] + """An array of coordinates representing the path of the drag action. + + Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + """ + + type: Literal["drag"] + """Specifies the event type. + + For a drag action, this property is always set to `drag`. + """ + + +class ActionKeypress(BaseModel): + keys: List[str] + """The combination of keys the model is requesting to be pressed. + + This is an array of strings, each representing a key. + """ + + type: Literal["keypress"] + """Specifies the event type. + + For a keypress action, this property is always set to `keypress`. + """ + + +class ActionMove(BaseModel): + type: Literal["move"] + """Specifies the event type. + + For a move action, this property is always set to `move`. + """ + + x: int + """The x-coordinate to move to.""" + + y: int + """The y-coordinate to move to.""" + + +class ActionScreenshot(BaseModel): + type: Literal["screenshot"] + """Specifies the event type. + + For a screenshot action, this property is always set to `screenshot`. + """ + + +class ActionScroll(BaseModel): + scroll_x: int + """The horizontal scroll distance.""" + + scroll_y: int + """The vertical scroll distance.""" + + type: Literal["scroll"] + """Specifies the event type. + + For a scroll action, this property is always set to `scroll`. + """ + + x: int + """The x-coordinate where the scroll occurred.""" + + y: int + """The y-coordinate where the scroll occurred.""" + + +class ActionType(BaseModel): + text: str + """The text to type.""" + + type: Literal["type"] + """Specifies the event type. + + For a type action, this property is always set to `type`. + """ + + +class ActionWait(BaseModel): + type: Literal["wait"] + """Specifies the event type. + + For a wait action, this property is always set to `wait`. + """ + + +Action: TypeAlias = Annotated[ + Union[ + ActionClick, + ActionDoubleClick, + ActionDrag, + ActionKeypress, + ActionMove, + ActionScreenshot, + ActionScroll, + ActionType, + ActionWait, + ], + PropertyInfo(discriminator="type"), +] + + +class PendingSafetyCheck(BaseModel): + id: str + """The ID of the pending safety check.""" + + code: str + """The type of the pending safety check.""" + + message: str + """Details about the pending safety check.""" + + +class ResponseComputerToolCall(BaseModel): + id: str + """The unique ID of the computer call.""" + + action: Action + """A click action.""" + + call_id: str + """An identifier used when responding to the tool call with output.""" + + pending_safety_checks: List[PendingSafetyCheck] + """The pending safety checks for the computer call.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Literal["computer_call"] + """The type of the computer call. Always `computer_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_item.py new file mode 100644 index 0000000000000000000000000000000000000000..a2dd68f5791880be3ba6ddb9afb62ddcdae51727 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_item.py @@ -0,0 +1,47 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_computer_tool_call_output_screenshot import ResponseComputerToolCallOutputScreenshot + +__all__ = ["ResponseComputerToolCallOutputItem", "AcknowledgedSafetyCheck"] + + +class AcknowledgedSafetyCheck(BaseModel): + id: str + """The ID of the pending safety check.""" + + code: str + """The type of the pending safety check.""" + + message: str + """Details about the pending safety check.""" + + +class ResponseComputerToolCallOutputItem(BaseModel): + id: str + """The unique ID of the computer call tool output.""" + + call_id: str + """The ID of the computer tool call that produced the output.""" + + output: ResponseComputerToolCallOutputScreenshot + """A computer screenshot image used with the computer use tool.""" + + type: Literal["computer_call_output"] + """The type of the computer tool call output. Always `computer_call_output`.""" + + acknowledged_safety_checks: Optional[List[AcknowledgedSafetyCheck]] = None + """ + The safety checks reported by the API that have been acknowledged by the + developer. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot.py new file mode 100644 index 0000000000000000000000000000000000000000..a500da85c1db02dcdeb9de0e20101cda075abd58 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseComputerToolCallOutputScreenshot"] + + +class ResponseComputerToolCallOutputScreenshot(BaseModel): + type: Literal["computer_screenshot"] + """Specifies the event type. + + For a computer screenshot, this property is always set to `computer_screenshot`. + """ + + file_id: Optional[str] = None + """The identifier of an uploaded file that contains the screenshot.""" + + image_url: Optional[str] = None + """The URL of the screenshot image.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot_param.py new file mode 100644 index 0000000000000000000000000000000000000000..efc2028aa4195ddff532c50c4b47b9b2079e9fdf --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_output_screenshot_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseComputerToolCallOutputScreenshotParam"] + + +class ResponseComputerToolCallOutputScreenshotParam(TypedDict, total=False): + type: Required[Literal["computer_screenshot"]] + """Specifies the event type. + + For a computer screenshot, this property is always set to `computer_screenshot`. + """ + + file_id: str + """The identifier of an uploaded file that contains the screenshot.""" + + image_url: str + """The URL of the screenshot image.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0be63db2fe6c960f5927c3616a06f409638a1370 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_computer_tool_call_param.py @@ -0,0 +1,210 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr + +__all__ = [ + "ResponseComputerToolCallParam", + "Action", + "ActionClick", + "ActionDoubleClick", + "ActionDrag", + "ActionDragPath", + "ActionKeypress", + "ActionMove", + "ActionScreenshot", + "ActionScroll", + "ActionType", + "ActionWait", + "PendingSafetyCheck", +] + + +class ActionClick(TypedDict, total=False): + button: Required[Literal["left", "right", "wheel", "back", "forward"]] + """Indicates which mouse button was pressed during the click. + + One of `left`, `right`, `wheel`, `back`, or `forward`. + """ + + type: Required[Literal["click"]] + """Specifies the event type. + + For a click action, this property is always set to `click`. + """ + + x: Required[int] + """The x-coordinate where the click occurred.""" + + y: Required[int] + """The y-coordinate where the click occurred.""" + + +class ActionDoubleClick(TypedDict, total=False): + type: Required[Literal["double_click"]] + """Specifies the event type. + + For a double click action, this property is always set to `double_click`. + """ + + x: Required[int] + """The x-coordinate where the double click occurred.""" + + y: Required[int] + """The y-coordinate where the double click occurred.""" + + +class ActionDragPath(TypedDict, total=False): + x: Required[int] + """The x-coordinate.""" + + y: Required[int] + """The y-coordinate.""" + + +class ActionDrag(TypedDict, total=False): + path: Required[Iterable[ActionDragPath]] + """An array of coordinates representing the path of the drag action. + + Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + """ + + type: Required[Literal["drag"]] + """Specifies the event type. + + For a drag action, this property is always set to `drag`. + """ + + +class ActionKeypress(TypedDict, total=False): + keys: Required[SequenceNotStr[str]] + """The combination of keys the model is requesting to be pressed. + + This is an array of strings, each representing a key. + """ + + type: Required[Literal["keypress"]] + """Specifies the event type. + + For a keypress action, this property is always set to `keypress`. + """ + + +class ActionMove(TypedDict, total=False): + type: Required[Literal["move"]] + """Specifies the event type. + + For a move action, this property is always set to `move`. + """ + + x: Required[int] + """The x-coordinate to move to.""" + + y: Required[int] + """The y-coordinate to move to.""" + + +class ActionScreenshot(TypedDict, total=False): + type: Required[Literal["screenshot"]] + """Specifies the event type. + + For a screenshot action, this property is always set to `screenshot`. + """ + + +class ActionScroll(TypedDict, total=False): + scroll_x: Required[int] + """The horizontal scroll distance.""" + + scroll_y: Required[int] + """The vertical scroll distance.""" + + type: Required[Literal["scroll"]] + """Specifies the event type. + + For a scroll action, this property is always set to `scroll`. + """ + + x: Required[int] + """The x-coordinate where the scroll occurred.""" + + y: Required[int] + """The y-coordinate where the scroll occurred.""" + + +class ActionType(TypedDict, total=False): + text: Required[str] + """The text to type.""" + + type: Required[Literal["type"]] + """Specifies the event type. + + For a type action, this property is always set to `type`. + """ + + +class ActionWait(TypedDict, total=False): + type: Required[Literal["wait"]] + """Specifies the event type. + + For a wait action, this property is always set to `wait`. + """ + + +Action: TypeAlias = Union[ + ActionClick, + ActionDoubleClick, + ActionDrag, + ActionKeypress, + ActionMove, + ActionScreenshot, + ActionScroll, + ActionType, + ActionWait, +] + + +class PendingSafetyCheck(TypedDict, total=False): + id: Required[str] + """The ID of the pending safety check.""" + + code: Required[str] + """The type of the pending safety check.""" + + message: Required[str] + """Details about the pending safety check.""" + + +class ResponseComputerToolCallParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the computer call.""" + + action: Required[Action] + """A click action.""" + + call_id: Required[str] + """An identifier used when responding to the tool call with output.""" + + pending_safety_checks: Required[Iterable[PendingSafetyCheck]] + """The pending safety checks for the computer call.""" + + status: Required[Literal["in_progress", "completed", "incomplete"]] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Required[Literal["computer_call"]] + """The type of the computer call. Always `computer_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..c78e80d1c4c555c2fd89b6d95fc2c94839c5c814 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_added_event.py @@ -0,0 +1,44 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .response_output_text import ResponseOutputText +from .response_output_refusal import ResponseOutputRefusal + +__all__ = ["ResponseContentPartAddedEvent", "Part", "PartReasoningText"] + + +class PartReasoningText(BaseModel): + text: str + """The reasoning text from the model.""" + + type: Literal["reasoning_text"] + """The type of the reasoning text. Always `reasoning_text`.""" + + +Part: TypeAlias = Annotated[ + Union[ResponseOutputText, ResponseOutputRefusal, PartReasoningText], PropertyInfo(discriminator="type") +] + + +class ResponseContentPartAddedEvent(BaseModel): + content_index: int + """The index of the content part that was added.""" + + item_id: str + """The ID of the output item that the content part was added to.""" + + output_index: int + """The index of the output item that the content part was added to.""" + + part: Part + """The content part that was added.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.content_part.added"] + """The type of the event. Always `response.content_part.added`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..732f2303ef729e8bbdf3e7752a14d17dbf774061 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_content_part_done_event.py @@ -0,0 +1,44 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .response_output_text import ResponseOutputText +from .response_output_refusal import ResponseOutputRefusal + +__all__ = ["ResponseContentPartDoneEvent", "Part", "PartReasoningText"] + + +class PartReasoningText(BaseModel): + text: str + """The reasoning text from the model.""" + + type: Literal["reasoning_text"] + """The type of the reasoning text. Always `reasoning_text`.""" + + +Part: TypeAlias = Annotated[ + Union[ResponseOutputText, ResponseOutputRefusal, PartReasoningText], PropertyInfo(discriminator="type") +] + + +class ResponseContentPartDoneEvent(BaseModel): + content_index: int + """The index of the content part that is done.""" + + item_id: str + """The ID of the output item that the content part was added to.""" + + output_index: int + """The index of the output item that the content part was added to.""" + + part: Part + """The content part that is done.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.content_part.done"] + """The type of the event. Always `response.content_part.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_conversation_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_conversation_param.py new file mode 100644 index 0000000000000000000000000000000000000000..067bdc7a3147a8c0cba938602ba5b0d64fb7a33e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_conversation_param.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +__all__ = ["ResponseConversationParam"] + + +class ResponseConversationParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the conversation.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..ba5c45ffee0f00c1a61c72743f87600cd8ed38da --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_create_params.py @@ -0,0 +1,322 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .tool_param import ToolParam +from .response_includable import ResponseIncludable +from .tool_choice_options import ToolChoiceOptions +from .response_input_param import ResponseInputParam +from .response_prompt_param import ResponsePromptParam +from .tool_choice_mcp_param import ToolChoiceMcpParam +from ..shared_params.metadata import Metadata +from .tool_choice_types_param import ToolChoiceTypesParam +from ..shared_params.reasoning import Reasoning +from .tool_choice_custom_param import ToolChoiceCustomParam +from .tool_choice_allowed_param import ToolChoiceAllowedParam +from .response_text_config_param import ResponseTextConfigParam +from .tool_choice_function_param import ToolChoiceFunctionParam +from .response_conversation_param import ResponseConversationParam +from ..shared_params.responses_model import ResponsesModel + +__all__ = [ + "ResponseCreateParamsBase", + "Conversation", + "StreamOptions", + "ToolChoice", + "ResponseCreateParamsNonStreaming", + "ResponseCreateParamsStreaming", +] + + +class ResponseCreateParamsBase(TypedDict, total=False): + background: Optional[bool] + """ + Whether to run the model response in the background. + [Learn more](https://platform.openai.com/docs/guides/background). + """ + + conversation: Optional[Conversation] + """The conversation that this response belongs to. + + Items from this conversation are prepended to `input_items` for this response + request. Input items and output items from this response are automatically added + to this conversation after this response completes. + """ + + include: Optional[List[ResponseIncludable]] + """Specify additional output data to include in the model response. + + Currently supported values are: + + - `web_search_call.action.sources`: Include the sources of the web search tool + call. + - `code_interpreter_call.outputs`: Includes the outputs of python code execution + in code interpreter tool call items. + - `computer_call_output.output.image_url`: Include image urls from the computer + call output. + - `file_search_call.results`: Include the search results of the file search tool + call. + - `message.input_image.image_url`: Include image urls from the input message. + - `message.output_text.logprobs`: Include logprobs with assistant messages. + - `reasoning.encrypted_content`: Includes an encrypted version of reasoning + tokens in reasoning item outputs. This enables reasoning items to be used in + multi-turn conversations when using the Responses API statelessly (like when + the `store` parameter is set to `false`, or when an organization is enrolled + in the zero data retention program). + """ + + input: Union[str, ResponseInputParam] + """Text, image, or file inputs to the model, used to generate a response. + + Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Image inputs](https://platform.openai.com/docs/guides/images) + - [File inputs](https://platform.openai.com/docs/guides/pdf-files) + - [Conversation state](https://platform.openai.com/docs/guides/conversation-state) + - [Function calling](https://platform.openai.com/docs/guides/function-calling) + """ + + instructions: Optional[str] + """A system (or developer) message inserted into the model's context. + + When using along with `previous_response_id`, the instructions from a previous + response will not be carried over to the next response. This makes it simple to + swap out system (or developer) messages in new responses. + """ + + max_output_tokens: Optional[int] + """ + An upper bound for the number of tokens that can be generated for a response, + including visible output tokens and + [reasoning tokens](https://platform.openai.com/docs/guides/reasoning). + """ + + max_tool_calls: Optional[int] + """ + The maximum number of total calls to built-in tools that can be processed in a + response. This maximum number applies across all built-in tool calls, not per + individual tool. Any further attempts to call a tool by the model will be + ignored. + """ + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + model: ResponsesModel + """Model ID used to generate the response, like `gpt-4o` or `o3`. + + OpenAI offers a wide range of models with different capabilities, performance + characteristics, and price points. Refer to the + [model guide](https://platform.openai.com/docs/models) to browse and compare + available models. + """ + + parallel_tool_calls: Optional[bool] + """Whether to allow the model to run tool calls in parallel.""" + + previous_response_id: Optional[str] + """The unique ID of the previous response to the model. + + Use this to create multi-turn conversations. Learn more about + [conversation state](https://platform.openai.com/docs/guides/conversation-state). + Cannot be used in conjunction with `conversation`. + """ + + prompt: Optional[ResponsePromptParam] + """ + Reference to a prompt template and its variables. + [Learn more](https://platform.openai.com/docs/guides/text?api-mode=responses#reusable-prompts). + """ + + prompt_cache_key: str + """ + Used by OpenAI to cache responses for similar requests to optimize your cache + hit rates. Replaces the `user` field. + [Learn more](https://platform.openai.com/docs/guides/prompt-caching). + """ + + reasoning: Optional[Reasoning] + """**gpt-5 and o-series models only** + + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). + """ + + safety_identifier: str + """ + A stable identifier used to help detect users of your application that may be + violating OpenAI's usage policies. The IDs should be a string that uniquely + identifies each user. We recommend hashing their username or email address, in + order to avoid sending us any identifying information. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + """ + + service_tier: Optional[Literal["auto", "default", "flex", "scale", "priority"]] + """Specifies the processing type used for serving the request. + + - If set to 'auto', then the request will be processed with the service tier + configured in the Project settings. Unless otherwise configured, the Project + will use 'default'. + - If set to 'default', then the request will be processed with the standard + pricing and performance for the selected model. + - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or + '[priority](https://openai.com/api-priority-processing/)', then the request + will be processed with the corresponding service tier. + - When not set, the default behavior is 'auto'. + + When the `service_tier` parameter is set, the response body will include the + `service_tier` value based on the processing mode actually used to serve the + request. This response value may be different from the value set in the + parameter. + """ + + store: Optional[bool] + """Whether to store the generated model response for later retrieval via API.""" + + stream_options: Optional[StreamOptions] + """Options for streaming responses. Only set this when you set `stream: true`.""" + + temperature: Optional[float] + """What sampling temperature to use, between 0 and 2. + + Higher values like 0.8 will make the output more random, while lower values like + 0.2 will make it more focused and deterministic. We generally recommend altering + this or `top_p` but not both. + """ + + text: ResponseTextConfigParam + """Configuration options for a text response from the model. + + Can be plain text or structured JSON data. Learn more: + + - [Text inputs and outputs](https://platform.openai.com/docs/guides/text) + - [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs) + """ + + tool_choice: ToolChoice + """ + How the model should select which tool (or tools) to use when generating a + response. See the `tools` parameter to see how to specify which tools the model + can call. + """ + + tools: Iterable[ToolParam] + """An array of tools the model may call while generating a response. + + You can specify which tool to use by setting the `tool_choice` parameter. + + We support the following categories of tools: + + - **Built-in tools**: Tools that are provided by OpenAI that extend the model's + capabilities, like + [web search](https://platform.openai.com/docs/guides/tools-web-search) or + [file search](https://platform.openai.com/docs/guides/tools-file-search). + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + - **MCP Tools**: Integrations with third-party systems via custom MCP servers or + predefined connectors such as Google Drive and SharePoint. Learn more about + [MCP Tools](https://platform.openai.com/docs/guides/tools-connectors-mcp). + - **Function calls (custom tools)**: Functions that are defined by you, enabling + the model to call your own code with strongly typed arguments and outputs. + Learn more about + [function calling](https://platform.openai.com/docs/guides/function-calling). + You can also use custom tools to call your own code. + """ + + top_logprobs: Optional[int] + """ + An integer between 0 and 20 specifying the number of most likely tokens to + return at each token position, each with an associated log probability. + """ + + top_p: Optional[float] + """ + An alternative to sampling with temperature, called nucleus sampling, where the + model considers the results of the tokens with top_p probability mass. So 0.1 + means only the tokens comprising the top 10% probability mass are considered. + + We generally recommend altering this or `temperature` but not both. + """ + + truncation: Optional[Literal["auto", "disabled"]] + """The truncation strategy to use for the model response. + + - `auto`: If the input to this Response exceeds the model's context window size, + the model will truncate the response to fit the context window by dropping + items from the beginning of the conversation. + - `disabled` (default): If the input size will exceed the context window size + for a model, the request will fail with a 400 error. + """ + + user: str + """This field is being replaced by `safety_identifier` and `prompt_cache_key`. + + Use `prompt_cache_key` instead to maintain caching optimizations. A stable + identifier for your end-users. Used to boost cache hit rates by better bucketing + similar requests and to help OpenAI detect and prevent abuse. + [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers). + """ + + +Conversation: TypeAlias = Union[str, ResponseConversationParam] + + +class StreamOptions(TypedDict, total=False): + include_obfuscation: bool + """When true, stream obfuscation will be enabled. + + Stream obfuscation adds random characters to an `obfuscation` field on streaming + delta events to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a small + amount of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between your + application and the OpenAI API. + """ + + +ToolChoice: TypeAlias = Union[ + ToolChoiceOptions, + ToolChoiceAllowedParam, + ToolChoiceTypesParam, + ToolChoiceFunctionParam, + ToolChoiceMcpParam, + ToolChoiceCustomParam, +] + + +class ResponseCreateParamsNonStreaming(ResponseCreateParamsBase, total=False): + stream: Optional[Literal[False]] + """ + If set to true, the model response data will be streamed to the client as it is + generated using + [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the + [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + """ + + +class ResponseCreateParamsStreaming(ResponseCreateParamsBase): + stream: Required[Literal[True]] + """ + If set to true, the model response data will be streamed to the client as it is + generated using + [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the + [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + """ + + +ResponseCreateParams = Union[ResponseCreateParamsNonStreaming, ResponseCreateParamsStreaming] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_created_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_created_event.py new file mode 100644 index 0000000000000000000000000000000000000000..73a9d700d4b3a736d1b539e8ae4bddd7671076b5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_created_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseCreatedEvent"] + + +class ResponseCreatedEvent(BaseModel): + response: Response + """The response that was created.""" + + sequence_number: int + """The sequence number for this event.""" + + type: Literal["response.created"] + """The type of the event. Always `response.created`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..38c650e662c9224a6a364e5e797085968d4bbddd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCustomToolCall"] + + +class ResponseCustomToolCall(BaseModel): + call_id: str + """An identifier used to map this custom tool call to a tool call output.""" + + input: str + """The input for the custom tool call generated by the model.""" + + name: str + """The name of the custom tool being called.""" + + type: Literal["custom_tool_call"] + """The type of the custom tool call. Always `custom_tool_call`.""" + + id: Optional[str] = None + """The unique ID of the custom tool call in the OpenAI platform.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..6c33102d75f9ca52ca15fa9b495984463657a175 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_delta_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCustomToolCallInputDeltaEvent"] + + +class ResponseCustomToolCallInputDeltaEvent(BaseModel): + delta: str + """The incremental input data (delta) for the custom tool call.""" + + item_id: str + """Unique identifier for the API item associated with this event.""" + + output_index: int + """The index of the output this delta applies to.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.custom_tool_call_input.delta"] + """The event type identifier.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..35a2fee22bea1d4fcdd3ec93d74c005857164f78 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_input_done_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCustomToolCallInputDoneEvent"] + + +class ResponseCustomToolCallInputDoneEvent(BaseModel): + input: str + """The complete input data for the custom tool call.""" + + item_id: str + """Unique identifier for the API item associated with this event.""" + + output_index: int + """The index of the output this event applies to.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.custom_tool_call_input.done"] + """The event type identifier.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output.py new file mode 100644 index 0000000000000000000000000000000000000000..a2b4cc3000e4c9f35332e79a84cd1eba557f7410 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCustomToolCallOutput"] + + +class ResponseCustomToolCallOutput(BaseModel): + call_id: str + """The call ID, used to map this custom tool call output to a custom tool call.""" + + output: str + """The output from the custom tool call generated by your code.""" + + type: Literal["custom_tool_call_output"] + """The type of the custom tool call output. Always `custom_tool_call_output`.""" + + id: Optional[str] = None + """The unique ID of the custom tool call output in the OpenAI platform.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output_param.py new file mode 100644 index 0000000000000000000000000000000000000000..d52c525467366a068e0e01c81bc542af46cefdca --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_output_param.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseCustomToolCallOutputParam"] + + +class ResponseCustomToolCallOutputParam(TypedDict, total=False): + call_id: Required[str] + """The call ID, used to map this custom tool call output to a custom tool call.""" + + output: Required[str] + """The output from the custom tool call generated by your code.""" + + type: Required[Literal["custom_tool_call_output"]] + """The type of the custom tool call output. Always `custom_tool_call_output`.""" + + id: str + """The unique ID of the custom tool call output in the OpenAI platform.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..e15beac29fbe4e19744dd945a3dee45e7c443287 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_custom_tool_call_param.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseCustomToolCallParam"] + + +class ResponseCustomToolCallParam(TypedDict, total=False): + call_id: Required[str] + """An identifier used to map this custom tool call to a tool call output.""" + + input: Required[str] + """The input for the custom tool call generated by the model.""" + + name: Required[str] + """The name of the custom tool being called.""" + + type: Required[Literal["custom_tool_call"]] + """The type of the custom tool call. Always `custom_tool_call`.""" + + id: str + """The unique ID of the custom tool call in the OpenAI platform.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_error.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_error.py new file mode 100644 index 0000000000000000000000000000000000000000..90f1fcf5da1a815243ab32c2ea8c19566b1d5a52 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_error.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseError"] + + +class ResponseError(BaseModel): + code: Literal[ + "server_error", + "rate_limit_exceeded", + "invalid_prompt", + "vector_store_timeout", + "invalid_image", + "invalid_image_format", + "invalid_base64_image", + "invalid_image_url", + "image_too_large", + "image_too_small", + "image_parse_error", + "image_content_policy_violation", + "invalid_image_mode", + "image_file_too_large", + "unsupported_image_media_type", + "empty_image_file", + "failed_to_download_image", + "image_file_not_found", + ] + """The error code for the response.""" + + message: str + """A human-readable description of the error.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_error_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_error_event.py new file mode 100644 index 0000000000000000000000000000000000000000..826c395125f08d30957efe060f9cec1af1ecc31a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_error_event.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseErrorEvent"] + + +class ResponseErrorEvent(BaseModel): + code: Optional[str] = None + """The error code.""" + + message: str + """The error message.""" + + param: Optional[str] = None + """The error parameter.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["error"] + """The type of the event. Always `error`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_failed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_failed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..cdd3d7d808ef59cddfff8c75028992ba685afe3f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_failed_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseFailedEvent"] + + +class ResponseFailedEvent(BaseModel): + response: Response + """The response that failed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.failed"] + """The type of the event. Always `response.failed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..08e51b2d3f434dc92b199722f39e1ce7464708fa --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_completed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFileSearchCallCompletedEvent"] + + +class ResponseFileSearchCallCompletedEvent(BaseModel): + item_id: str + """The ID of the output item that the file search call is initiated.""" + + output_index: int + """The index of the output item that the file search call is initiated.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.file_search_call.completed"] + """The type of the event. Always `response.file_search_call.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..63840a649f5562eb9114fd11e9cd8eadc4a16c33 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_in_progress_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFileSearchCallInProgressEvent"] + + +class ResponseFileSearchCallInProgressEvent(BaseModel): + item_id: str + """The ID of the output item that the file search call is initiated.""" + + output_index: int + """The index of the output item that the file search call is initiated.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.file_search_call.in_progress"] + """The type of the event. Always `response.file_search_call.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_searching_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_searching_event.py new file mode 100644 index 0000000000000000000000000000000000000000..706c8c57ad4eadc8e4e2c29042a2b478c7f2f6c7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_call_searching_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFileSearchCallSearchingEvent"] + + +class ResponseFileSearchCallSearchingEvent(BaseModel): + item_id: str + """The ID of the output item that the file search call is initiated.""" + + output_index: int + """The index of the output item that the file search call is searching.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.file_search_call.searching"] + """The type of the event. Always `response.file_search_call.searching`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..ef1c6a560887e42ee63af55756ad3bf10bd56586 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call.py @@ -0,0 +1,51 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFileSearchToolCall", "Result"] + + +class Result(BaseModel): + attributes: Optional[Dict[str, Union[str, float, bool]]] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + file_id: Optional[str] = None + """The unique ID of the file.""" + + filename: Optional[str] = None + """The name of the file.""" + + score: Optional[float] = None + """The relevance score of the file - a value between 0 and 1.""" + + text: Optional[str] = None + """The text that was retrieved from the file.""" + + +class ResponseFileSearchToolCall(BaseModel): + id: str + """The unique ID of the file search tool call.""" + + queries: List[str] + """The queries used to search for files.""" + + status: Literal["in_progress", "searching", "completed", "incomplete", "failed"] + """The status of the file search tool call. + + One of `in_progress`, `searching`, `incomplete` or `failed`, + """ + + type: Literal["file_search_call"] + """The type of the file search tool call. Always `file_search_call`.""" + + results: Optional[List[Result]] = None + """The results of the file search tool call.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..4903dca4fbc2c59e4dad2f60292fe8644e47fd97 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_file_search_tool_call_param.py @@ -0,0 +1,53 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypedDict + +from ..._types import SequenceNotStr + +__all__ = ["ResponseFileSearchToolCallParam", "Result"] + + +class Result(TypedDict, total=False): + attributes: Optional[Dict[str, Union[str, float, bool]]] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + file_id: str + """The unique ID of the file.""" + + filename: str + """The name of the file.""" + + score: float + """The relevance score of the file - a value between 0 and 1.""" + + text: str + """The text that was retrieved from the file.""" + + +class ResponseFileSearchToolCallParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the file search tool call.""" + + queries: Required[SequenceNotStr[str]] + """The queries used to search for files.""" + + status: Required[Literal["in_progress", "searching", "completed", "incomplete", "failed"]] + """The status of the file search tool call. + + One of `in_progress`, `searching`, `incomplete` or `failed`, + """ + + type: Required[Literal["file_search_call"]] + """The type of the file search tool call. Always `file_search_call`.""" + + results: Optional[Iterable[Result]] + """The results of the file search tool call.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config.py new file mode 100644 index 0000000000000000000000000000000000000000..a4896bf9fed2ff9e47277ea5b379710bbffb36b0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..shared.response_format_text import ResponseFormatText +from ..shared.response_format_json_object import ResponseFormatJSONObject +from .response_format_text_json_schema_config import ResponseFormatTextJSONSchemaConfig + +__all__ = ["ResponseFormatTextConfig"] + +ResponseFormatTextConfig: TypeAlias = Annotated[ + Union[ResponseFormatText, ResponseFormatTextJSONSchemaConfig, ResponseFormatJSONObject], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..fcaf8f3fb6b9e5b3d4c349ed54f1186840d66ea9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_config_param.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from ..shared_params.response_format_text import ResponseFormatText +from ..shared_params.response_format_json_object import ResponseFormatJSONObject +from .response_format_text_json_schema_config_param import ResponseFormatTextJSONSchemaConfigParam + +__all__ = ["ResponseFormatTextConfigParam"] + +ResponseFormatTextConfigParam: TypeAlias = Union[ + ResponseFormatText, ResponseFormatTextJSONSchemaConfigParam, ResponseFormatJSONObject +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config.py new file mode 100644 index 0000000000000000000000000000000000000000..001fcf5baba0209c87d924cb7bd7c93ce70121b4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config.py @@ -0,0 +1,43 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from ..._models import BaseModel + +__all__ = ["ResponseFormatTextJSONSchemaConfig"] + + +class ResponseFormatTextJSONSchemaConfig(BaseModel): + name: str + """The name of the response format. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + schema_: Dict[str, object] = FieldInfo(alias="schema") + """ + The schema for the response format, described as a JSON Schema object. Learn how + to build JSON schemas [here](https://json-schema.org/). + """ + + type: Literal["json_schema"] + """The type of response format being defined. Always `json_schema`.""" + + description: Optional[str] = None + """ + A description of what the response format is for, used by the model to determine + how to respond in the format. + """ + + strict: Optional[bool] = None + """ + Whether to enable strict schema adherence when generating the output. If set to + true, the model will always follow the exact schema defined in the `schema` + field. Only a subset of JSON Schema is supported when `strict` is `true`. To + learn more, read the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f293a80c5a3d3518bfb12dc0e8733e2999409633 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_format_text_json_schema_config_param.py @@ -0,0 +1,41 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseFormatTextJSONSchemaConfigParam"] + + +class ResponseFormatTextJSONSchemaConfigParam(TypedDict, total=False): + name: Required[str] + """The name of the response format. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + schema: Required[Dict[str, object]] + """ + The schema for the response format, described as a JSON Schema object. Learn how + to build JSON schemas [here](https://json-schema.org/). + """ + + type: Required[Literal["json_schema"]] + """The type of response format being defined. Always `json_schema`.""" + + description: str + """ + A description of what the response format is for, used by the model to determine + how to respond in the format. + """ + + strict: Optional[bool] + """ + Whether to enable strict schema adherence when generating the output. If set to + true, the model will always follow the exact schema defined in the `schema` + field. Only a subset of JSON Schema is supported when `strict` is `true`. To + learn more, read the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..c6bc5dfad731ab1258d27ccdcd43c4a5261574d6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_delta_event.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionCallArgumentsDeltaEvent"] + + +class ResponseFunctionCallArgumentsDeltaEvent(BaseModel): + delta: str + """The function-call arguments delta that is added.""" + + item_id: str + """The ID of the output item that the function-call arguments delta is added to.""" + + output_index: int + """ + The index of the output item that the function-call arguments delta is added to. + """ + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.function_call_arguments.delta"] + """The type of the event. Always `response.function_call_arguments.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..875e7a6875b450747cdf0d56a1af04a569cbc869 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_call_arguments_done_event.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionCallArgumentsDoneEvent"] + + +class ResponseFunctionCallArgumentsDoneEvent(BaseModel): + arguments: str + """The function-call arguments.""" + + item_id: str + """The ID of the item.""" + + output_index: int + """The index of the output item.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.function_call_arguments.done"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call.py new file mode 100644 index 0000000000000000000000000000000000000000..2a8482204e553bc4aea91df9a3ae0605f4f6f3e2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call.py @@ -0,0 +1,32 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionToolCall"] + + +class ResponseFunctionToolCall(BaseModel): + arguments: str + """A JSON string of the arguments to pass to the function.""" + + call_id: str + """The unique ID of the function tool call generated by the model.""" + + name: str + """The name of the function to run.""" + + type: Literal["function_call"] + """The type of the function tool call. Always `function_call`.""" + + id: Optional[str] = None + """The unique ID of the function tool call.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_item.py new file mode 100644 index 0000000000000000000000000000000000000000..762015a4b1aaeabe9f1d0360d28361d6a98b0cd9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_item.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .response_function_tool_call import ResponseFunctionToolCall + +__all__ = ["ResponseFunctionToolCallItem"] + + +class ResponseFunctionToolCallItem(ResponseFunctionToolCall): + id: str # type: ignore + """The unique ID of the function tool call.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_output_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_output_item.py new file mode 100644 index 0000000000000000000000000000000000000000..4c8c41a6fe48c364e68c1aee20c24ee543ff4e4e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_output_item.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFunctionToolCallOutputItem"] + + +class ResponseFunctionToolCallOutputItem(BaseModel): + id: str + """The unique ID of the function call tool output.""" + + call_id: str + """The unique ID of the function tool call generated by the model.""" + + output: str + """A JSON string of the output of the function tool call.""" + + type: Literal["function_call_output"] + """The type of the function tool call output. Always `function_call_output`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_param.py new file mode 100644 index 0000000000000000000000000000000000000000..eaa263cf67b6d0f3517c4fcab77536d212202bfa --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_tool_call_param.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseFunctionToolCallParam"] + + +class ResponseFunctionToolCallParam(TypedDict, total=False): + arguments: Required[str] + """A JSON string of the arguments to pass to the function.""" + + call_id: Required[str] + """The unique ID of the function tool call generated by the model.""" + + name: Required[str] + """The name of the function to run.""" + + type: Required[Literal["function_call"]] + """The type of the function tool call. Always `function_call`.""" + + id: str + """The unique ID of the function tool call.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search.py new file mode 100644 index 0000000000000000000000000000000000000000..f3e80e6a8f9773e517299d72c8e0b832d968101b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search.py @@ -0,0 +1,67 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["ResponseFunctionWebSearch", "Action", "ActionSearch", "ActionSearchSource", "ActionOpenPage", "ActionFind"] + + +class ActionSearchSource(BaseModel): + type: Literal["url"] + """The type of source. Always `url`.""" + + url: str + """The URL of the source.""" + + +class ActionSearch(BaseModel): + query: str + """The search query.""" + + type: Literal["search"] + """The action type.""" + + sources: Optional[List[ActionSearchSource]] = None + """The sources used in the search.""" + + +class ActionOpenPage(BaseModel): + type: Literal["open_page"] + """The action type.""" + + url: str + """The URL opened by the model.""" + + +class ActionFind(BaseModel): + pattern: str + """The pattern or text to search for within the page.""" + + type: Literal["find"] + """The action type.""" + + url: str + """The URL of the page searched for the pattern.""" + + +Action: TypeAlias = Annotated[Union[ActionSearch, ActionOpenPage, ActionFind], PropertyInfo(discriminator="type")] + + +class ResponseFunctionWebSearch(BaseModel): + id: str + """The unique ID of the web search tool call.""" + + action: Action + """ + An object describing the specific action taken in this web search call. Includes + details on how the model used the web (search, open_page, find). + """ + + status: Literal["in_progress", "searching", "completed", "failed"] + """The status of the web search tool call.""" + + type: Literal["web_search_call"] + """The type of the web search tool call. Always `web_search_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search_param.py new file mode 100644 index 0000000000000000000000000000000000000000..fc019d3eb7e9ff57a9c39ce67dd849947af963bd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_function_web_search_param.py @@ -0,0 +1,73 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = [ + "ResponseFunctionWebSearchParam", + "Action", + "ActionSearch", + "ActionSearchSource", + "ActionOpenPage", + "ActionFind", +] + + +class ActionSearchSource(TypedDict, total=False): + type: Required[Literal["url"]] + """The type of source. Always `url`.""" + + url: Required[str] + """The URL of the source.""" + + +class ActionSearch(TypedDict, total=False): + query: Required[str] + """The search query.""" + + type: Required[Literal["search"]] + """The action type.""" + + sources: Iterable[ActionSearchSource] + """The sources used in the search.""" + + +class ActionOpenPage(TypedDict, total=False): + type: Required[Literal["open_page"]] + """The action type.""" + + url: Required[str] + """The URL opened by the model.""" + + +class ActionFind(TypedDict, total=False): + pattern: Required[str] + """The pattern or text to search for within the page.""" + + type: Required[Literal["find"]] + """The action type.""" + + url: Required[str] + """The URL of the page searched for the pattern.""" + + +Action: TypeAlias = Union[ActionSearch, ActionOpenPage, ActionFind] + + +class ResponseFunctionWebSearchParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the web search tool call.""" + + action: Required[Action] + """ + An object describing the specific action taken in this web search call. Includes + details on how the model used the web (search, open_page, find). + """ + + status: Required[Literal["in_progress", "searching", "completed", "failed"]] + """The status of the web search tool call.""" + + type: Required[Literal["web_search_call"]] + """The type of the web search tool call. Always `web_search_call`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..a554273ed0025970c9702527e28f3bcc068f684e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_completed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseImageGenCallCompletedEvent"] + + +class ResponseImageGenCallCompletedEvent(BaseModel): + item_id: str + """The unique identifier of the image generation item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.image_generation_call.completed"] + """The type of the event. Always 'response.image_generation_call.completed'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_generating_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_generating_event.py new file mode 100644 index 0000000000000000000000000000000000000000..74b4f57333666a5516c99ef990ff60c99631cdab --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_generating_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseImageGenCallGeneratingEvent"] + + +class ResponseImageGenCallGeneratingEvent(BaseModel): + item_id: str + """The unique identifier of the image generation item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of the image generation item being processed.""" + + type: Literal["response.image_generation_call.generating"] + """The type of the event. Always 'response.image_generation_call.generating'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b36ff5fa47e8be9ae77fd3dd8c7b04007cab440c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_in_progress_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseImageGenCallInProgressEvent"] + + +class ResponseImageGenCallInProgressEvent(BaseModel): + item_id: str + """The unique identifier of the image generation item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of the image generation item being processed.""" + + type: Literal["response.image_generation_call.in_progress"] + """The type of the event. Always 'response.image_generation_call.in_progress'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_partial_image_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_partial_image_event.py new file mode 100644 index 0000000000000000000000000000000000000000..e69c95fb33be387715674d712a4550477b2f5fd5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_image_gen_call_partial_image_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseImageGenCallPartialImageEvent"] + + +class ResponseImageGenCallPartialImageEvent(BaseModel): + item_id: str + """The unique identifier of the image generation item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + partial_image_b64: str + """Base64-encoded partial image data, suitable for rendering as an image.""" + + partial_image_index: int + """ + 0-based index for the partial image (backend is 1-based, but this is 0-based for + the user). + """ + + sequence_number: int + """The sequence number of the image generation item being processed.""" + + type: Literal["response.image_generation_call.partial_image"] + """The type of the event. Always 'response.image_generation_call.partial_image'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b82e10b3575d735019a0bad1ca3fd807d6b0c3f2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_in_progress_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseInProgressEvent"] + + +class ResponseInProgressEvent(BaseModel): + response: Response + """The response that is in progress.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.in_progress"] + """The type of the event. Always `response.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_includable.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_includable.py new file mode 100644 index 0000000000000000000000000000000000000000..c17a02560fcecf135ba2ca1ea532b3e9c27302cf --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_includable.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ResponseIncludable"] + +ResponseIncludable: TypeAlias = Literal[ + "code_interpreter_call.outputs", + "computer_call_output.output.image_url", + "file_search_call.results", + "message.input_image.image_url", + "message.output_text.logprobs", + "reasoning.encrypted_content", +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_incomplete_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_incomplete_event.py new file mode 100644 index 0000000000000000000000000000000000000000..63c969a4289fec92a88e55b2c292eaff57d1dc96 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_incomplete_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseIncompleteEvent"] + + +class ResponseIncompleteEvent(BaseModel): + response: Response + """The response that was incomplete.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.incomplete"] + """The type of the event. Always `response.incomplete`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio.py new file mode 100644 index 0000000000000000000000000000000000000000..9fef6de0fd83543ecccb20e8f6dd68b444812578 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseInputAudio", "InputAudio"] + + +class InputAudio(BaseModel): + data: str + """Base64-encoded audio data.""" + + format: Literal["mp3", "wav"] + """The format of the audio data. Currently supported formats are `mp3` and `wav`.""" + + +class ResponseInputAudio(BaseModel): + input_audio: InputAudio + + type: Literal["input_audio"] + """The type of the input item. Always `input_audio`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f3fc913cca373b2aa268715f5e4793c05748f039 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_audio_param.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseInputAudioParam", "InputAudio"] + + +class InputAudio(TypedDict, total=False): + data: Required[str] + """Base64-encoded audio data.""" + + format: Required[Literal["mp3", "wav"]] + """The format of the audio data. Currently supported formats are `mp3` and `wav`.""" + + +class ResponseInputAudioParam(TypedDict, total=False): + input_audio: Required[InputAudio] + + type: Required[Literal["input_audio"]] + """The type of the input item. Always `input_audio`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content.py new file mode 100644 index 0000000000000000000000000000000000000000..376b9ffce80adb13211b667e72097ec321ad7bd5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content.py @@ -0,0 +1,17 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .response_input_file import ResponseInputFile +from .response_input_text import ResponseInputText +from .response_input_audio import ResponseInputAudio +from .response_input_image import ResponseInputImage + +__all__ = ["ResponseInputContent"] + +ResponseInputContent: TypeAlias = Annotated[ + Union[ResponseInputText, ResponseInputImage, ResponseInputFile, ResponseInputAudio], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content_param.py new file mode 100644 index 0000000000000000000000000000000000000000..a95e026a53803aafd98e55a12d2a19fc931b9d6e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_content_param.py @@ -0,0 +1,17 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import TypeAlias + +from .response_input_file_param import ResponseInputFileParam +from .response_input_text_param import ResponseInputTextParam +from .response_input_audio_param import ResponseInputAudioParam +from .response_input_image_param import ResponseInputImageParam + +__all__ = ["ResponseInputContentParam"] + +ResponseInputContentParam: TypeAlias = Union[ + ResponseInputTextParam, ResponseInputImageParam, ResponseInputFileParam, ResponseInputAudioParam +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file.py new file mode 100644 index 0000000000000000000000000000000000000000..1eecd6a2b6d2501548640f6ceb35b1bba9d65fe3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseInputFile"] + + +class ResponseInputFile(BaseModel): + type: Literal["input_file"] + """The type of the input item. Always `input_file`.""" + + file_data: Optional[str] = None + """The content of the file to be sent to the model.""" + + file_id: Optional[str] = None + """The ID of the file to be sent to the model.""" + + file_url: Optional[str] = None + """The URL of the file to be sent to the model.""" + + filename: Optional[str] = None + """The name of the file to be sent to the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0b5f513ec6b3b97b444086cce6173e69eefff55c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_file_param.py @@ -0,0 +1,25 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseInputFileParam"] + + +class ResponseInputFileParam(TypedDict, total=False): + type: Required[Literal["input_file"]] + """The type of the input item. Always `input_file`.""" + + file_data: str + """The content of the file to be sent to the model.""" + + file_id: Optional[str] + """The ID of the file to be sent to the model.""" + + file_url: str + """The URL of the file to be sent to the model.""" + + filename: str + """The name of the file to be sent to the model.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image.py new file mode 100644 index 0000000000000000000000000000000000000000..f2d760b25e2ac925c695397c0db7aa01015d395e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseInputImage"] + + +class ResponseInputImage(BaseModel): + detail: Literal["low", "high", "auto"] + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + type: Literal["input_image"] + """The type of the input item. Always `input_image`.""" + + file_id: Optional[str] = None + """The ID of the file to be sent to the model.""" + + image_url: Optional[str] = None + """The URL of the image to be sent to the model. + + A fully qualified URL or base64 encoded image in a data URL. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image_param.py new file mode 100644 index 0000000000000000000000000000000000000000..bc17e4f1c295a9a19c036cd80b9e025d472e9b67 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_image_param.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseInputImageParam"] + + +class ResponseInputImageParam(TypedDict, total=False): + detail: Required[Literal["low", "high", "auto"]] + """The detail level of the image to be sent to the model. + + One of `high`, `low`, or `auto`. Defaults to `auto`. + """ + + type: Required[Literal["input_image"]] + """The type of the input item. Always `input_image`.""" + + file_id: Optional[str] + """The ID of the file to be sent to the model.""" + + image_url: Optional[str] + """The URL of the image to be sent to the model. + + A fully qualified URL or base64 encoded image in a data URL. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item.py new file mode 100644 index 0000000000000000000000000000000000000000..d2b454fd2ceaabf80925fbd8e1c1baf562687c3e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item.py @@ -0,0 +1,309 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .easy_input_message import EasyInputMessage +from .response_output_message import ResponseOutputMessage +from .response_reasoning_item import ResponseReasoningItem +from .response_custom_tool_call import ResponseCustomToolCall +from .response_computer_tool_call import ResponseComputerToolCall +from .response_function_tool_call import ResponseFunctionToolCall +from .response_function_web_search import ResponseFunctionWebSearch +from .response_file_search_tool_call import ResponseFileSearchToolCall +from .response_custom_tool_call_output import ResponseCustomToolCallOutput +from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall +from .response_input_message_content_list import ResponseInputMessageContentList +from .response_computer_tool_call_output_screenshot import ResponseComputerToolCallOutputScreenshot + +__all__ = [ + "ResponseInputItem", + "Message", + "ComputerCallOutput", + "ComputerCallOutputAcknowledgedSafetyCheck", + "FunctionCallOutput", + "ImageGenerationCall", + "LocalShellCall", + "LocalShellCallAction", + "LocalShellCallOutput", + "McpListTools", + "McpListToolsTool", + "McpApprovalRequest", + "McpApprovalResponse", + "McpCall", + "ItemReference", +] + + +class Message(BaseModel): + content: ResponseInputMessageContentList + """ + A list of one or many input items to the model, containing different content + types. + """ + + role: Literal["user", "system", "developer"] + """The role of the message input. One of `user`, `system`, or `developer`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always set to `message`.""" + + +class ComputerCallOutputAcknowledgedSafetyCheck(BaseModel): + id: str + """The ID of the pending safety check.""" + + code: Optional[str] = None + """The type of the pending safety check.""" + + message: Optional[str] = None + """Details about the pending safety check.""" + + +class ComputerCallOutput(BaseModel): + call_id: str + """The ID of the computer tool call that produced the output.""" + + output: ResponseComputerToolCallOutputScreenshot + """A computer screenshot image used with the computer use tool.""" + + type: Literal["computer_call_output"] + """The type of the computer tool call output. Always `computer_call_output`.""" + + id: Optional[str] = None + """The ID of the computer tool call output.""" + + acknowledged_safety_checks: Optional[List[ComputerCallOutputAcknowledgedSafetyCheck]] = None + """ + The safety checks reported by the API that have been acknowledged by the + developer. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ + + +class FunctionCallOutput(BaseModel): + call_id: str + """The unique ID of the function tool call generated by the model.""" + + output: str + """A JSON string of the output of the function tool call.""" + + type: Literal["function_call_output"] + """The type of the function tool call output. Always `function_call_output`.""" + + id: Optional[str] = None + """The unique ID of the function tool call output. + + Populated when this item is returned via API. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + +class ImageGenerationCall(BaseModel): + id: str + """The unique ID of the image generation call.""" + + result: Optional[str] = None + """The generated image encoded in base64.""" + + status: Literal["in_progress", "completed", "generating", "failed"] + """The status of the image generation call.""" + + type: Literal["image_generation_call"] + """The type of the image generation call. Always `image_generation_call`.""" + + +class LocalShellCallAction(BaseModel): + command: List[str] + """The command to run.""" + + env: Dict[str, str] + """Environment variables to set for the command.""" + + type: Literal["exec"] + """The type of the local shell action. Always `exec`.""" + + timeout_ms: Optional[int] = None + """Optional timeout in milliseconds for the command.""" + + user: Optional[str] = None + """Optional user to run the command as.""" + + working_directory: Optional[str] = None + """Optional working directory to run the command in.""" + + +class LocalShellCall(BaseModel): + id: str + """The unique ID of the local shell call.""" + + action: LocalShellCallAction + """Execute a shell command on the server.""" + + call_id: str + """The unique ID of the local shell tool call generated by the model.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the local shell call.""" + + type: Literal["local_shell_call"] + """The type of the local shell call. Always `local_shell_call`.""" + + +class LocalShellCallOutput(BaseModel): + id: str + """The unique ID of the local shell tool call generated by the model.""" + + output: str + """A JSON string of the output of the local shell tool call.""" + + type: Literal["local_shell_call_output"] + """The type of the local shell tool call output. Always `local_shell_call_output`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. One of `in_progress`, `completed`, or `incomplete`.""" + + +class McpListToolsTool(BaseModel): + input_schema: object + """The JSON schema describing the tool's input.""" + + name: str + """The name of the tool.""" + + annotations: Optional[object] = None + """Additional annotations about the tool.""" + + description: Optional[str] = None + """The description of the tool.""" + + +class McpListTools(BaseModel): + id: str + """The unique ID of the list.""" + + server_label: str + """The label of the MCP server.""" + + tools: List[McpListToolsTool] + """The tools available on the server.""" + + type: Literal["mcp_list_tools"] + """The type of the item. Always `mcp_list_tools`.""" + + error: Optional[str] = None + """Error message if the server could not list tools.""" + + +class McpApprovalRequest(BaseModel): + id: str + """The unique ID of the approval request.""" + + arguments: str + """A JSON string of arguments for the tool.""" + + name: str + """The name of the tool to run.""" + + server_label: str + """The label of the MCP server making the request.""" + + type: Literal["mcp_approval_request"] + """The type of the item. Always `mcp_approval_request`.""" + + +class McpApprovalResponse(BaseModel): + approval_request_id: str + """The ID of the approval request being answered.""" + + approve: bool + """Whether the request was approved.""" + + type: Literal["mcp_approval_response"] + """The type of the item. Always `mcp_approval_response`.""" + + id: Optional[str] = None + """The unique ID of the approval response""" + + reason: Optional[str] = None + """Optional reason for the decision.""" + + +class McpCall(BaseModel): + id: str + """The unique ID of the tool call.""" + + arguments: str + """A JSON string of the arguments passed to the tool.""" + + name: str + """The name of the tool that was run.""" + + server_label: str + """The label of the MCP server running the tool.""" + + type: Literal["mcp_call"] + """The type of the item. Always `mcp_call`.""" + + error: Optional[str] = None + """The error from the tool call, if any.""" + + output: Optional[str] = None + """The output from the tool call.""" + + +class ItemReference(BaseModel): + id: str + """The ID of the item to reference.""" + + type: Optional[Literal["item_reference"]] = None + """The type of item to reference. Always `item_reference`.""" + + +ResponseInputItem: TypeAlias = Annotated[ + Union[ + EasyInputMessage, + Message, + ResponseOutputMessage, + ResponseFileSearchToolCall, + ResponseComputerToolCall, + ComputerCallOutput, + ResponseFunctionWebSearch, + ResponseFunctionToolCall, + FunctionCallOutput, + ResponseReasoningItem, + ImageGenerationCall, + ResponseCodeInterpreterToolCall, + LocalShellCall, + LocalShellCallOutput, + McpListTools, + McpApprovalRequest, + McpApprovalResponse, + McpCall, + ResponseCustomToolCallOutput, + ResponseCustomToolCall, + ItemReference, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item_param.py new file mode 100644 index 0000000000000000000000000000000000000000..5ad83fc03a41e39a78085eba7747075bc8ac95f2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_item_param.py @@ -0,0 +1,307 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from .easy_input_message_param import EasyInputMessageParam +from .response_output_message_param import ResponseOutputMessageParam +from .response_reasoning_item_param import ResponseReasoningItemParam +from .response_custom_tool_call_param import ResponseCustomToolCallParam +from .response_computer_tool_call_param import ResponseComputerToolCallParam +from .response_function_tool_call_param import ResponseFunctionToolCallParam +from .response_function_web_search_param import ResponseFunctionWebSearchParam +from .response_file_search_tool_call_param import ResponseFileSearchToolCallParam +from .response_custom_tool_call_output_param import ResponseCustomToolCallOutputParam +from .response_code_interpreter_tool_call_param import ResponseCodeInterpreterToolCallParam +from .response_input_message_content_list_param import ResponseInputMessageContentListParam +from .response_computer_tool_call_output_screenshot_param import ResponseComputerToolCallOutputScreenshotParam + +__all__ = [ + "ResponseInputItemParam", + "Message", + "ComputerCallOutput", + "ComputerCallOutputAcknowledgedSafetyCheck", + "FunctionCallOutput", + "ImageGenerationCall", + "LocalShellCall", + "LocalShellCallAction", + "LocalShellCallOutput", + "McpListTools", + "McpListToolsTool", + "McpApprovalRequest", + "McpApprovalResponse", + "McpCall", + "ItemReference", +] + + +class Message(TypedDict, total=False): + content: Required[ResponseInputMessageContentListParam] + """ + A list of one or many input items to the model, containing different content + types. + """ + + role: Required[Literal["user", "system", "developer"]] + """The role of the message input. One of `user`, `system`, or `developer`.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Literal["message"] + """The type of the message input. Always set to `message`.""" + + +class ComputerCallOutputAcknowledgedSafetyCheck(TypedDict, total=False): + id: Required[str] + """The ID of the pending safety check.""" + + code: Optional[str] + """The type of the pending safety check.""" + + message: Optional[str] + """Details about the pending safety check.""" + + +class ComputerCallOutput(TypedDict, total=False): + call_id: Required[str] + """The ID of the computer tool call that produced the output.""" + + output: Required[ResponseComputerToolCallOutputScreenshotParam] + """A computer screenshot image used with the computer use tool.""" + + type: Required[Literal["computer_call_output"]] + """The type of the computer tool call output. Always `computer_call_output`.""" + + id: Optional[str] + """The ID of the computer tool call output.""" + + acknowledged_safety_checks: Optional[Iterable[ComputerCallOutputAcknowledgedSafetyCheck]] + """ + The safety checks reported by the API that have been acknowledged by the + developer. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ + + +class FunctionCallOutput(TypedDict, total=False): + call_id: Required[str] + """The unique ID of the function tool call generated by the model.""" + + output: Required[str] + """A JSON string of the output of the function tool call.""" + + type: Required[Literal["function_call_output"]] + """The type of the function tool call output. Always `function_call_output`.""" + + id: Optional[str] + """The unique ID of the function tool call output. + + Populated when this item is returned via API. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + +class ImageGenerationCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the image generation call.""" + + result: Required[Optional[str]] + """The generated image encoded in base64.""" + + status: Required[Literal["in_progress", "completed", "generating", "failed"]] + """The status of the image generation call.""" + + type: Required[Literal["image_generation_call"]] + """The type of the image generation call. Always `image_generation_call`.""" + + +class LocalShellCallAction(TypedDict, total=False): + command: Required[SequenceNotStr[str]] + """The command to run.""" + + env: Required[Dict[str, str]] + """Environment variables to set for the command.""" + + type: Required[Literal["exec"]] + """The type of the local shell action. Always `exec`.""" + + timeout_ms: Optional[int] + """Optional timeout in milliseconds for the command.""" + + user: Optional[str] + """Optional user to run the command as.""" + + working_directory: Optional[str] + """Optional working directory to run the command in.""" + + +class LocalShellCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the local shell call.""" + + action: Required[LocalShellCallAction] + """Execute a shell command on the server.""" + + call_id: Required[str] + """The unique ID of the local shell tool call generated by the model.""" + + status: Required[Literal["in_progress", "completed", "incomplete"]] + """The status of the local shell call.""" + + type: Required[Literal["local_shell_call"]] + """The type of the local shell call. Always `local_shell_call`.""" + + +class LocalShellCallOutput(TypedDict, total=False): + id: Required[str] + """The unique ID of the local shell tool call generated by the model.""" + + output: Required[str] + """A JSON string of the output of the local shell tool call.""" + + type: Required[Literal["local_shell_call_output"]] + """The type of the local shell tool call output. Always `local_shell_call_output`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the item. One of `in_progress`, `completed`, or `incomplete`.""" + + +class McpListToolsTool(TypedDict, total=False): + input_schema: Required[object] + """The JSON schema describing the tool's input.""" + + name: Required[str] + """The name of the tool.""" + + annotations: Optional[object] + """Additional annotations about the tool.""" + + description: Optional[str] + """The description of the tool.""" + + +class McpListTools(TypedDict, total=False): + id: Required[str] + """The unique ID of the list.""" + + server_label: Required[str] + """The label of the MCP server.""" + + tools: Required[Iterable[McpListToolsTool]] + """The tools available on the server.""" + + type: Required[Literal["mcp_list_tools"]] + """The type of the item. Always `mcp_list_tools`.""" + + error: Optional[str] + """Error message if the server could not list tools.""" + + +class McpApprovalRequest(TypedDict, total=False): + id: Required[str] + """The unique ID of the approval request.""" + + arguments: Required[str] + """A JSON string of arguments for the tool.""" + + name: Required[str] + """The name of the tool to run.""" + + server_label: Required[str] + """The label of the MCP server making the request.""" + + type: Required[Literal["mcp_approval_request"]] + """The type of the item. Always `mcp_approval_request`.""" + + +class McpApprovalResponse(TypedDict, total=False): + approval_request_id: Required[str] + """The ID of the approval request being answered.""" + + approve: Required[bool] + """Whether the request was approved.""" + + type: Required[Literal["mcp_approval_response"]] + """The type of the item. Always `mcp_approval_response`.""" + + id: Optional[str] + """The unique ID of the approval response""" + + reason: Optional[str] + """Optional reason for the decision.""" + + +class McpCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the tool call.""" + + arguments: Required[str] + """A JSON string of the arguments passed to the tool.""" + + name: Required[str] + """The name of the tool that was run.""" + + server_label: Required[str] + """The label of the MCP server running the tool.""" + + type: Required[Literal["mcp_call"]] + """The type of the item. Always `mcp_call`.""" + + error: Optional[str] + """The error from the tool call, if any.""" + + output: Optional[str] + """The output from the tool call.""" + + +class ItemReference(TypedDict, total=False): + id: Required[str] + """The ID of the item to reference.""" + + type: Optional[Literal["item_reference"]] + """The type of item to reference. Always `item_reference`.""" + + +ResponseInputItemParam: TypeAlias = Union[ + EasyInputMessageParam, + Message, + ResponseOutputMessageParam, + ResponseFileSearchToolCallParam, + ResponseComputerToolCallParam, + ComputerCallOutput, + ResponseFunctionWebSearchParam, + ResponseFunctionToolCallParam, + FunctionCallOutput, + ResponseReasoningItemParam, + ImageGenerationCall, + ResponseCodeInterpreterToolCallParam, + LocalShellCall, + LocalShellCallOutput, + McpListTools, + McpApprovalRequest, + McpApprovalResponse, + McpCall, + ResponseCustomToolCallOutputParam, + ResponseCustomToolCallParam, + ItemReference, +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list.py new file mode 100644 index 0000000000000000000000000000000000000000..99b7c10f1295d4e49dc680b67a4faead0eab7b70 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List +from typing_extensions import TypeAlias + +from .response_input_content import ResponseInputContent + +__all__ = ["ResponseInputMessageContentList"] + +ResponseInputMessageContentList: TypeAlias = List[ResponseInputContent] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list_param.py new file mode 100644 index 0000000000000000000000000000000000000000..8e3778d15a2c4c22ccc4fbff3455faaa24124c13 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_content_list_param.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union +from typing_extensions import TypeAlias + +from .response_input_file_param import ResponseInputFileParam +from .response_input_text_param import ResponseInputTextParam +from .response_input_audio_param import ResponseInputAudioParam +from .response_input_image_param import ResponseInputImageParam + +__all__ = ["ResponseInputMessageContentListParam", "ResponseInputContentParam"] + +ResponseInputContentParam: TypeAlias = Union[ + ResponseInputTextParam, ResponseInputImageParam, ResponseInputFileParam, ResponseInputAudioParam +] + +ResponseInputMessageContentListParam: TypeAlias = List[ResponseInputContentParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_item.py new file mode 100644 index 0000000000000000000000000000000000000000..6a788e7fa49d87318cafbaf41a87185087ee293a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_message_item.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_input_message_content_list import ResponseInputMessageContentList + +__all__ = ["ResponseInputMessageItem"] + + +class ResponseInputMessageItem(BaseModel): + id: str + """The unique ID of the message input.""" + + content: ResponseInputMessageContentList + """ + A list of one or many input items to the model, containing different content + types. + """ + + role: Literal["user", "system", "developer"] + """The role of the message input. One of `user`, `system`, or `developer`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Optional[Literal["message"]] = None + """The type of the message input. Always set to `message`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_param.py new file mode 100644 index 0000000000000000000000000000000000000000..73eac62428e3dbbbfdce10b8f4b1ca77acd6c5db --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_param.py @@ -0,0 +1,310 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, List, Union, Iterable, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from ..._types import SequenceNotStr +from .easy_input_message_param import EasyInputMessageParam +from .response_output_message_param import ResponseOutputMessageParam +from .response_reasoning_item_param import ResponseReasoningItemParam +from .response_custom_tool_call_param import ResponseCustomToolCallParam +from .response_computer_tool_call_param import ResponseComputerToolCallParam +from .response_function_tool_call_param import ResponseFunctionToolCallParam +from .response_function_web_search_param import ResponseFunctionWebSearchParam +from .response_file_search_tool_call_param import ResponseFileSearchToolCallParam +from .response_custom_tool_call_output_param import ResponseCustomToolCallOutputParam +from .response_code_interpreter_tool_call_param import ResponseCodeInterpreterToolCallParam +from .response_input_message_content_list_param import ResponseInputMessageContentListParam +from .response_computer_tool_call_output_screenshot_param import ResponseComputerToolCallOutputScreenshotParam + +__all__ = [ + "ResponseInputParam", + "ResponseInputItemParam", + "Message", + "ComputerCallOutput", + "ComputerCallOutputAcknowledgedSafetyCheck", + "FunctionCallOutput", + "ImageGenerationCall", + "LocalShellCall", + "LocalShellCallAction", + "LocalShellCallOutput", + "McpListTools", + "McpListToolsTool", + "McpApprovalRequest", + "McpApprovalResponse", + "McpCall", + "ItemReference", +] + + +class Message(TypedDict, total=False): + content: Required[ResponseInputMessageContentListParam] + """ + A list of one or many input items to the model, containing different content + types. + """ + + role: Required[Literal["user", "system", "developer"]] + """The role of the message input. One of `user`, `system`, or `developer`.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + type: Literal["message"] + """The type of the message input. Always set to `message`.""" + + +class ComputerCallOutputAcknowledgedSafetyCheck(TypedDict, total=False): + id: Required[str] + """The ID of the pending safety check.""" + + code: Optional[str] + """The type of the pending safety check.""" + + message: Optional[str] + """Details about the pending safety check.""" + + +class ComputerCallOutput(TypedDict, total=False): + call_id: Required[str] + """The ID of the computer tool call that produced the output.""" + + output: Required[ResponseComputerToolCallOutputScreenshotParam] + """A computer screenshot image used with the computer use tool.""" + + type: Required[Literal["computer_call_output"]] + """The type of the computer tool call output. Always `computer_call_output`.""" + + id: Optional[str] + """The ID of the computer tool call output.""" + + acknowledged_safety_checks: Optional[Iterable[ComputerCallOutputAcknowledgedSafetyCheck]] + """ + The safety checks reported by the API that have been acknowledged by the + developer. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ + + +class FunctionCallOutput(TypedDict, total=False): + call_id: Required[str] + """The unique ID of the function tool call generated by the model.""" + + output: Required[str] + """A JSON string of the output of the function tool call.""" + + type: Required[Literal["function_call_output"]] + """The type of the function tool call output. Always `function_call_output`.""" + + id: Optional[str] + """The unique ID of the function tool call output. + + Populated when this item is returned via API. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ + + +class ImageGenerationCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the image generation call.""" + + result: Required[Optional[str]] + """The generated image encoded in base64.""" + + status: Required[Literal["in_progress", "completed", "generating", "failed"]] + """The status of the image generation call.""" + + type: Required[Literal["image_generation_call"]] + """The type of the image generation call. Always `image_generation_call`.""" + + +class LocalShellCallAction(TypedDict, total=False): + command: Required[SequenceNotStr[str]] + """The command to run.""" + + env: Required[Dict[str, str]] + """Environment variables to set for the command.""" + + type: Required[Literal["exec"]] + """The type of the local shell action. Always `exec`.""" + + timeout_ms: Optional[int] + """Optional timeout in milliseconds for the command.""" + + user: Optional[str] + """Optional user to run the command as.""" + + working_directory: Optional[str] + """Optional working directory to run the command in.""" + + +class LocalShellCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the local shell call.""" + + action: Required[LocalShellCallAction] + """Execute a shell command on the server.""" + + call_id: Required[str] + """The unique ID of the local shell tool call generated by the model.""" + + status: Required[Literal["in_progress", "completed", "incomplete"]] + """The status of the local shell call.""" + + type: Required[Literal["local_shell_call"]] + """The type of the local shell call. Always `local_shell_call`.""" + + +class LocalShellCallOutput(TypedDict, total=False): + id: Required[str] + """The unique ID of the local shell tool call generated by the model.""" + + output: Required[str] + """A JSON string of the output of the local shell tool call.""" + + type: Required[Literal["local_shell_call_output"]] + """The type of the local shell tool call output. Always `local_shell_call_output`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] + """The status of the item. One of `in_progress`, `completed`, or `incomplete`.""" + + +class McpListToolsTool(TypedDict, total=False): + input_schema: Required[object] + """The JSON schema describing the tool's input.""" + + name: Required[str] + """The name of the tool.""" + + annotations: Optional[object] + """Additional annotations about the tool.""" + + description: Optional[str] + """The description of the tool.""" + + +class McpListTools(TypedDict, total=False): + id: Required[str] + """The unique ID of the list.""" + + server_label: Required[str] + """The label of the MCP server.""" + + tools: Required[Iterable[McpListToolsTool]] + """The tools available on the server.""" + + type: Required[Literal["mcp_list_tools"]] + """The type of the item. Always `mcp_list_tools`.""" + + error: Optional[str] + """Error message if the server could not list tools.""" + + +class McpApprovalRequest(TypedDict, total=False): + id: Required[str] + """The unique ID of the approval request.""" + + arguments: Required[str] + """A JSON string of arguments for the tool.""" + + name: Required[str] + """The name of the tool to run.""" + + server_label: Required[str] + """The label of the MCP server making the request.""" + + type: Required[Literal["mcp_approval_request"]] + """The type of the item. Always `mcp_approval_request`.""" + + +class McpApprovalResponse(TypedDict, total=False): + approval_request_id: Required[str] + """The ID of the approval request being answered.""" + + approve: Required[bool] + """Whether the request was approved.""" + + type: Required[Literal["mcp_approval_response"]] + """The type of the item. Always `mcp_approval_response`.""" + + id: Optional[str] + """The unique ID of the approval response""" + + reason: Optional[str] + """Optional reason for the decision.""" + + +class McpCall(TypedDict, total=False): + id: Required[str] + """The unique ID of the tool call.""" + + arguments: Required[str] + """A JSON string of the arguments passed to the tool.""" + + name: Required[str] + """The name of the tool that was run.""" + + server_label: Required[str] + """The label of the MCP server running the tool.""" + + type: Required[Literal["mcp_call"]] + """The type of the item. Always `mcp_call`.""" + + error: Optional[str] + """The error from the tool call, if any.""" + + output: Optional[str] + """The output from the tool call.""" + + +class ItemReference(TypedDict, total=False): + id: Required[str] + """The ID of the item to reference.""" + + type: Optional[Literal["item_reference"]] + """The type of item to reference. Always `item_reference`.""" + + +ResponseInputItemParam: TypeAlias = Union[ + EasyInputMessageParam, + Message, + ResponseOutputMessageParam, + ResponseFileSearchToolCallParam, + ResponseComputerToolCallParam, + ComputerCallOutput, + ResponseFunctionWebSearchParam, + ResponseFunctionToolCallParam, + FunctionCallOutput, + ResponseReasoningItemParam, + ImageGenerationCall, + ResponseCodeInterpreterToolCallParam, + LocalShellCall, + LocalShellCallOutput, + McpListTools, + McpApprovalRequest, + McpApprovalResponse, + McpCall, + ResponseCustomToolCallOutputParam, + ResponseCustomToolCallParam, + ItemReference, +] + +ResponseInputParam: TypeAlias = List[ResponseInputItemParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text.py new file mode 100644 index 0000000000000000000000000000000000000000..ba8d1ea18b2d0d2bc393b62439ab81db805faae1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseInputText"] + + +class ResponseInputText(BaseModel): + text: str + """The text input to the model.""" + + type: Literal["input_text"] + """The type of the input item. Always `input_text`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f2ba8340824fce9416dce69fa42d9ebe7de76811 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_input_text_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseInputTextParam"] + + +class ResponseInputTextParam(TypedDict, total=False): + text: Required[str] + """The text input to the model.""" + + type: Required[Literal["input_text"]] + """The type of the input item. Always `input_text`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_item.py new file mode 100644 index 0000000000000000000000000000000000000000..cba89390ed050dbef23ba95610b7ecc5eb4ef534 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_item.py @@ -0,0 +1,205 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .response_output_message import ResponseOutputMessage +from .response_computer_tool_call import ResponseComputerToolCall +from .response_input_message_item import ResponseInputMessageItem +from .response_function_web_search import ResponseFunctionWebSearch +from .response_file_search_tool_call import ResponseFileSearchToolCall +from .response_function_tool_call_item import ResponseFunctionToolCallItem +from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall +from .response_computer_tool_call_output_item import ResponseComputerToolCallOutputItem +from .response_function_tool_call_output_item import ResponseFunctionToolCallOutputItem + +__all__ = [ + "ResponseItem", + "ImageGenerationCall", + "LocalShellCall", + "LocalShellCallAction", + "LocalShellCallOutput", + "McpListTools", + "McpListToolsTool", + "McpApprovalRequest", + "McpApprovalResponse", + "McpCall", +] + + +class ImageGenerationCall(BaseModel): + id: str + """The unique ID of the image generation call.""" + + result: Optional[str] = None + """The generated image encoded in base64.""" + + status: Literal["in_progress", "completed", "generating", "failed"] + """The status of the image generation call.""" + + type: Literal["image_generation_call"] + """The type of the image generation call. Always `image_generation_call`.""" + + +class LocalShellCallAction(BaseModel): + command: List[str] + """The command to run.""" + + env: Dict[str, str] + """Environment variables to set for the command.""" + + type: Literal["exec"] + """The type of the local shell action. Always `exec`.""" + + timeout_ms: Optional[int] = None + """Optional timeout in milliseconds for the command.""" + + user: Optional[str] = None + """Optional user to run the command as.""" + + working_directory: Optional[str] = None + """Optional working directory to run the command in.""" + + +class LocalShellCall(BaseModel): + id: str + """The unique ID of the local shell call.""" + + action: LocalShellCallAction + """Execute a shell command on the server.""" + + call_id: str + """The unique ID of the local shell tool call generated by the model.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the local shell call.""" + + type: Literal["local_shell_call"] + """The type of the local shell call. Always `local_shell_call`.""" + + +class LocalShellCallOutput(BaseModel): + id: str + """The unique ID of the local shell tool call generated by the model.""" + + output: str + """A JSON string of the output of the local shell tool call.""" + + type: Literal["local_shell_call_output"] + """The type of the local shell tool call output. Always `local_shell_call_output`.""" + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. One of `in_progress`, `completed`, or `incomplete`.""" + + +class McpListToolsTool(BaseModel): + input_schema: object + """The JSON schema describing the tool's input.""" + + name: str + """The name of the tool.""" + + annotations: Optional[object] = None + """Additional annotations about the tool.""" + + description: Optional[str] = None + """The description of the tool.""" + + +class McpListTools(BaseModel): + id: str + """The unique ID of the list.""" + + server_label: str + """The label of the MCP server.""" + + tools: List[McpListToolsTool] + """The tools available on the server.""" + + type: Literal["mcp_list_tools"] + """The type of the item. Always `mcp_list_tools`.""" + + error: Optional[str] = None + """Error message if the server could not list tools.""" + + +class McpApprovalRequest(BaseModel): + id: str + """The unique ID of the approval request.""" + + arguments: str + """A JSON string of arguments for the tool.""" + + name: str + """The name of the tool to run.""" + + server_label: str + """The label of the MCP server making the request.""" + + type: Literal["mcp_approval_request"] + """The type of the item. Always `mcp_approval_request`.""" + + +class McpApprovalResponse(BaseModel): + id: str + """The unique ID of the approval response""" + + approval_request_id: str + """The ID of the approval request being answered.""" + + approve: bool + """Whether the request was approved.""" + + type: Literal["mcp_approval_response"] + """The type of the item. Always `mcp_approval_response`.""" + + reason: Optional[str] = None + """Optional reason for the decision.""" + + +class McpCall(BaseModel): + id: str + """The unique ID of the tool call.""" + + arguments: str + """A JSON string of the arguments passed to the tool.""" + + name: str + """The name of the tool that was run.""" + + server_label: str + """The label of the MCP server running the tool.""" + + type: Literal["mcp_call"] + """The type of the item. Always `mcp_call`.""" + + error: Optional[str] = None + """The error from the tool call, if any.""" + + output: Optional[str] = None + """The output from the tool call.""" + + +ResponseItem: TypeAlias = Annotated[ + Union[ + ResponseInputMessageItem, + ResponseOutputMessage, + ResponseFileSearchToolCall, + ResponseComputerToolCall, + ResponseComputerToolCallOutputItem, + ResponseFunctionWebSearch, + ResponseFunctionToolCallItem, + ResponseFunctionToolCallOutputItem, + ImageGenerationCall, + ResponseCodeInterpreterToolCall, + LocalShellCall, + LocalShellCallOutput, + McpListTools, + McpApprovalRequest, + McpApprovalResponse, + McpCall, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_item_list.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_item_list.py new file mode 100644 index 0000000000000000000000000000000000000000..b43eacdb510140ff7a8241c4a72fd20887304f12 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_item_list.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_item import ResponseItem + +__all__ = ["ResponseItemList"] + + +class ResponseItemList(BaseModel): + data: List[ResponseItem] + """A list of items used to generate this response.""" + + first_id: str + """The ID of the first item in the list.""" + + has_more: bool + """Whether there are more items available.""" + + last_id: str + """The ID of the last item in the list.""" + + object: Literal["list"] + """The type of object returned, must be `list`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..54eff3837362d083bdb65dc1a3eae85d84cd9224 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_delta_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallArgumentsDeltaEvent"] + + +class ResponseMcpCallArgumentsDeltaEvent(BaseModel): + delta: str + """ + A JSON string containing the partial update to the arguments for the MCP tool + call. + """ + + item_id: str + """The unique identifier of the MCP tool call item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_call_arguments.delta"] + """The type of the event. Always 'response.mcp_call_arguments.delta'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..59ce9bc944af7345b1a8400163945490af394740 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_arguments_done_event.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallArgumentsDoneEvent"] + + +class ResponseMcpCallArgumentsDoneEvent(BaseModel): + arguments: str + """A JSON string containing the finalized arguments for the MCP tool call.""" + + item_id: str + """The unique identifier of the MCP tool call item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_call_arguments.done"] + """The type of the event. Always 'response.mcp_call_arguments.done'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..2fee5dff81502913126aa1dd586f8305bc7410f4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_completed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallCompletedEvent"] + + +class ResponseMcpCallCompletedEvent(BaseModel): + item_id: str + """The ID of the MCP tool call item that completed.""" + + output_index: int + """The index of the output item that completed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_call.completed"] + """The type of the event. Always 'response.mcp_call.completed'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_failed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_failed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..ca41ab7159388172ad007b2622b565405d84d0c8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_failed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallFailedEvent"] + + +class ResponseMcpCallFailedEvent(BaseModel): + item_id: str + """The ID of the MCP tool call item that failed.""" + + output_index: int + """The index of the output item that failed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_call.failed"] + """The type of the event. Always 'response.mcp_call.failed'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..401c31685140008f298394e6b27ada3d982e5ee0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_call_in_progress_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpCallInProgressEvent"] + + +class ResponseMcpCallInProgressEvent(BaseModel): + item_id: str + """The unique identifier of the MCP tool call item being processed.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_call.in_progress"] + """The type of the event. Always 'response.mcp_call.in_progress'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..c60ad88ee598cbe72f2b95431393c829d7f1341f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_completed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpListToolsCompletedEvent"] + + +class ResponseMcpListToolsCompletedEvent(BaseModel): + item_id: str + """The ID of the MCP tool call item that produced this output.""" + + output_index: int + """The index of the output item that was processed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_list_tools.completed"] + """The type of the event. Always 'response.mcp_list_tools.completed'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_failed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_failed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..0c966c447a1d7c6e170f0e5c467494f2d6e152ba --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_failed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpListToolsFailedEvent"] + + +class ResponseMcpListToolsFailedEvent(BaseModel): + item_id: str + """The ID of the MCP tool call item that failed.""" + + output_index: int + """The index of the output item that failed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_list_tools.failed"] + """The type of the event. Always 'response.mcp_list_tools.failed'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..f451db1ed5e4c1d159d99f57b63e5bcabe69fd58 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_mcp_list_tools_in_progress_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseMcpListToolsInProgressEvent"] + + +class ResponseMcpListToolsInProgressEvent(BaseModel): + item_id: str + """The ID of the MCP tool call item that is being processed.""" + + output_index: int + """The index of the output item that is being processed.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.mcp_list_tools.in_progress"] + """The type of the event. Always 'response.mcp_list_tools.in_progress'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item.py new file mode 100644 index 0000000000000000000000000000000000000000..2d3ee7b64e33611fc75cd551e20e199f5fc5cd33 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item.py @@ -0,0 +1,168 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .response_output_message import ResponseOutputMessage +from .response_reasoning_item import ResponseReasoningItem +from .response_custom_tool_call import ResponseCustomToolCall +from .response_computer_tool_call import ResponseComputerToolCall +from .response_function_tool_call import ResponseFunctionToolCall +from .response_function_web_search import ResponseFunctionWebSearch +from .response_file_search_tool_call import ResponseFileSearchToolCall +from .response_code_interpreter_tool_call import ResponseCodeInterpreterToolCall + +__all__ = [ + "ResponseOutputItem", + "ImageGenerationCall", + "LocalShellCall", + "LocalShellCallAction", + "McpCall", + "McpListTools", + "McpListToolsTool", + "McpApprovalRequest", +] + + +class ImageGenerationCall(BaseModel): + id: str + """The unique ID of the image generation call.""" + + result: Optional[str] = None + """The generated image encoded in base64.""" + + status: Literal["in_progress", "completed", "generating", "failed"] + """The status of the image generation call.""" + + type: Literal["image_generation_call"] + """The type of the image generation call. Always `image_generation_call`.""" + + +class LocalShellCallAction(BaseModel): + command: List[str] + """The command to run.""" + + env: Dict[str, str] + """Environment variables to set for the command.""" + + type: Literal["exec"] + """The type of the local shell action. Always `exec`.""" + + timeout_ms: Optional[int] = None + """Optional timeout in milliseconds for the command.""" + + user: Optional[str] = None + """Optional user to run the command as.""" + + working_directory: Optional[str] = None + """Optional working directory to run the command in.""" + + +class LocalShellCall(BaseModel): + id: str + """The unique ID of the local shell call.""" + + action: LocalShellCallAction + """Execute a shell command on the server.""" + + call_id: str + """The unique ID of the local shell tool call generated by the model.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the local shell call.""" + + type: Literal["local_shell_call"] + """The type of the local shell call. Always `local_shell_call`.""" + + +class McpCall(BaseModel): + id: str + """The unique ID of the tool call.""" + + arguments: str + """A JSON string of the arguments passed to the tool.""" + + name: str + """The name of the tool that was run.""" + + server_label: str + """The label of the MCP server running the tool.""" + + type: Literal["mcp_call"] + """The type of the item. Always `mcp_call`.""" + + error: Optional[str] = None + """The error from the tool call, if any.""" + + output: Optional[str] = None + """The output from the tool call.""" + + +class McpListToolsTool(BaseModel): + input_schema: object + """The JSON schema describing the tool's input.""" + + name: str + """The name of the tool.""" + + annotations: Optional[object] = None + """Additional annotations about the tool.""" + + description: Optional[str] = None + """The description of the tool.""" + + +class McpListTools(BaseModel): + id: str + """The unique ID of the list.""" + + server_label: str + """The label of the MCP server.""" + + tools: List[McpListToolsTool] + """The tools available on the server.""" + + type: Literal["mcp_list_tools"] + """The type of the item. Always `mcp_list_tools`.""" + + error: Optional[str] = None + """Error message if the server could not list tools.""" + + +class McpApprovalRequest(BaseModel): + id: str + """The unique ID of the approval request.""" + + arguments: str + """A JSON string of arguments for the tool.""" + + name: str + """The name of the tool to run.""" + + server_label: str + """The label of the MCP server making the request.""" + + type: Literal["mcp_approval_request"] + """The type of the item. Always `mcp_approval_request`.""" + + +ResponseOutputItem: TypeAlias = Annotated[ + Union[ + ResponseOutputMessage, + ResponseFileSearchToolCall, + ResponseFunctionToolCall, + ResponseFunctionWebSearch, + ResponseComputerToolCall, + ResponseReasoningItem, + ImageGenerationCall, + ResponseCodeInterpreterToolCall, + LocalShellCall, + McpCall, + McpListTools, + McpApprovalRequest, + ResponseCustomToolCall, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..7cd2a3946d9ed7330a4844fca1db3c8c11b079e5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_added_event.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_output_item import ResponseOutputItem + +__all__ = ["ResponseOutputItemAddedEvent"] + + +class ResponseOutputItemAddedEvent(BaseModel): + item: ResponseOutputItem + """The output item that was added.""" + + output_index: int + """The index of the output item that was added.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.output_item.added"] + """The type of the event. Always `response.output_item.added`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..37d3694cf7c3604ca405f5a395561bd35c809925 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_item_done_event.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_output_item import ResponseOutputItem + +__all__ = ["ResponseOutputItemDoneEvent"] + + +class ResponseOutputItemDoneEvent(BaseModel): + item: ResponseOutputItem + """The output item that was marked done.""" + + output_index: int + """The index of the output item that was marked done.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.output_item.done"] + """The type of the event. Always `response.output_item.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message.py new file mode 100644 index 0000000000000000000000000000000000000000..3864aa2111bdbb437dc362a1a9117167f80fb0ec --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .response_output_text import ResponseOutputText +from .response_output_refusal import ResponseOutputRefusal + +__all__ = ["ResponseOutputMessage", "Content"] + +Content: TypeAlias = Annotated[Union[ResponseOutputText, ResponseOutputRefusal], PropertyInfo(discriminator="type")] + + +class ResponseOutputMessage(BaseModel): + id: str + """The unique ID of the output message.""" + + content: List[Content] + """The content of the output message.""" + + role: Literal["assistant"] + """The role of the output message. Always `assistant`.""" + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ + + type: Literal["message"] + """The type of the output message. Always `message`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message_param.py new file mode 100644 index 0000000000000000000000000000000000000000..46cbbd20def4fde850d9150c37933deed430d9f9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_message_param.py @@ -0,0 +1,34 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .response_output_text_param import ResponseOutputTextParam +from .response_output_refusal_param import ResponseOutputRefusalParam + +__all__ = ["ResponseOutputMessageParam", "Content"] + +Content: TypeAlias = Union[ResponseOutputTextParam, ResponseOutputRefusalParam] + + +class ResponseOutputMessageParam(TypedDict, total=False): + id: Required[str] + """The unique ID of the output message.""" + + content: Required[Iterable[Content]] + """The content of the output message.""" + + role: Required[Literal["assistant"]] + """The role of the output message. Always `assistant`.""" + + status: Required[Literal["in_progress", "completed", "incomplete"]] + """The status of the message input. + + One of `in_progress`, `completed`, or `incomplete`. Populated when input items + are returned via API. + """ + + type: Required[Literal["message"]] + """The type of the output message. Always `message`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal.py new file mode 100644 index 0000000000000000000000000000000000000000..685c8722a6bc202b414545ecf863d503e5f0b716 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseOutputRefusal"] + + +class ResponseOutputRefusal(BaseModel): + refusal: str + """The refusal explanation from the model.""" + + type: Literal["refusal"] + """The type of the refusal. Always `refusal`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal_param.py new file mode 100644 index 0000000000000000000000000000000000000000..54cfaf0791a7fef9b82cad821df68fd3176cbd19 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_refusal_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseOutputRefusalParam"] + + +class ResponseOutputRefusalParam(TypedDict, total=False): + refusal: Required[str] + """The refusal explanation from the model.""" + + type: Required[Literal["refusal"]] + """The type of the refusal. Always `refusal`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text.py new file mode 100644 index 0000000000000000000000000000000000000000..aa97b629f00e24a9ff2efbbe121837196bc6014a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text.py @@ -0,0 +1,117 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = [ + "ResponseOutputText", + "Annotation", + "AnnotationFileCitation", + "AnnotationURLCitation", + "AnnotationContainerFileCitation", + "AnnotationFilePath", + "Logprob", + "LogprobTopLogprob", +] + + +class AnnotationFileCitation(BaseModel): + file_id: str + """The ID of the file.""" + + filename: str + """The filename of the file cited.""" + + index: int + """The index of the file in the list of files.""" + + type: Literal["file_citation"] + """The type of the file citation. Always `file_citation`.""" + + +class AnnotationURLCitation(BaseModel): + end_index: int + """The index of the last character of the URL citation in the message.""" + + start_index: int + """The index of the first character of the URL citation in the message.""" + + title: str + """The title of the web resource.""" + + type: Literal["url_citation"] + """The type of the URL citation. Always `url_citation`.""" + + url: str + """The URL of the web resource.""" + + +class AnnotationContainerFileCitation(BaseModel): + container_id: str + """The ID of the container file.""" + + end_index: int + """The index of the last character of the container file citation in the message.""" + + file_id: str + """The ID of the file.""" + + filename: str + """The filename of the container file cited.""" + + start_index: int + """The index of the first character of the container file citation in the message.""" + + type: Literal["container_file_citation"] + """The type of the container file citation. Always `container_file_citation`.""" + + +class AnnotationFilePath(BaseModel): + file_id: str + """The ID of the file.""" + + index: int + """The index of the file in the list of files.""" + + type: Literal["file_path"] + """The type of the file path. Always `file_path`.""" + + +Annotation: TypeAlias = Annotated[ + Union[AnnotationFileCitation, AnnotationURLCitation, AnnotationContainerFileCitation, AnnotationFilePath], + PropertyInfo(discriminator="type"), +] + + +class LogprobTopLogprob(BaseModel): + token: str + + bytes: List[int] + + logprob: float + + +class Logprob(BaseModel): + token: str + + bytes: List[int] + + logprob: float + + top_logprobs: List[LogprobTopLogprob] + + +class ResponseOutputText(BaseModel): + annotations: List[Annotation] + """The annotations of the text output.""" + + text: str + """The text output from the model.""" + + type: Literal["output_text"] + """The type of the output text. Always `output_text`.""" + + logprobs: Optional[List[Logprob]] = None diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_annotation_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_annotation_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..62d8f72863a7f49cdd899459c0c6a03be6ea8e99 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_annotation_added_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseOutputTextAnnotationAddedEvent"] + + +class ResponseOutputTextAnnotationAddedEvent(BaseModel): + annotation: object + """The annotation object being added. (See annotation schema for details.)""" + + annotation_index: int + """The index of the annotation within the content part.""" + + content_index: int + """The index of the content part within the output item.""" + + item_id: str + """The unique identifier of the item to which the annotation is being added.""" + + output_index: int + """The index of the output item in the response's output array.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.output_text.annotation.added"] + """The type of the event. Always 'response.output_text.annotation.added'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_param.py new file mode 100644 index 0000000000000000000000000000000000000000..63d2d394a884672d041546223435a004873fcc0b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_output_text_param.py @@ -0,0 +1,115 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = [ + "ResponseOutputTextParam", + "Annotation", + "AnnotationFileCitation", + "AnnotationURLCitation", + "AnnotationContainerFileCitation", + "AnnotationFilePath", + "Logprob", + "LogprobTopLogprob", +] + + +class AnnotationFileCitation(TypedDict, total=False): + file_id: Required[str] + """The ID of the file.""" + + filename: Required[str] + """The filename of the file cited.""" + + index: Required[int] + """The index of the file in the list of files.""" + + type: Required[Literal["file_citation"]] + """The type of the file citation. Always `file_citation`.""" + + +class AnnotationURLCitation(TypedDict, total=False): + end_index: Required[int] + """The index of the last character of the URL citation in the message.""" + + start_index: Required[int] + """The index of the first character of the URL citation in the message.""" + + title: Required[str] + """The title of the web resource.""" + + type: Required[Literal["url_citation"]] + """The type of the URL citation. Always `url_citation`.""" + + url: Required[str] + """The URL of the web resource.""" + + +class AnnotationContainerFileCitation(TypedDict, total=False): + container_id: Required[str] + """The ID of the container file.""" + + end_index: Required[int] + """The index of the last character of the container file citation in the message.""" + + file_id: Required[str] + """The ID of the file.""" + + filename: Required[str] + """The filename of the container file cited.""" + + start_index: Required[int] + """The index of the first character of the container file citation in the message.""" + + type: Required[Literal["container_file_citation"]] + """The type of the container file citation. Always `container_file_citation`.""" + + +class AnnotationFilePath(TypedDict, total=False): + file_id: Required[str] + """The ID of the file.""" + + index: Required[int] + """The index of the file in the list of files.""" + + type: Required[Literal["file_path"]] + """The type of the file path. Always `file_path`.""" + + +Annotation: TypeAlias = Union[ + AnnotationFileCitation, AnnotationURLCitation, AnnotationContainerFileCitation, AnnotationFilePath +] + + +class LogprobTopLogprob(TypedDict, total=False): + token: Required[str] + + bytes: Required[Iterable[int]] + + logprob: Required[float] + + +class Logprob(TypedDict, total=False): + token: Required[str] + + bytes: Required[Iterable[int]] + + logprob: Required[float] + + top_logprobs: Required[Iterable[LogprobTopLogprob]] + + +class ResponseOutputTextParam(TypedDict, total=False): + annotations: Required[Iterable[Annotation]] + """The annotations of the text output.""" + + text: Required[str] + """The text output from the model.""" + + type: Required[Literal["output_text"]] + """The type of the output text. Always `output_text`.""" + + logprobs: Iterable[Logprob] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt.py new file mode 100644 index 0000000000000000000000000000000000000000..537c2f8fbcf5750f510a3a171ca7a8669daa1ce3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Union, Optional +from typing_extensions import TypeAlias + +from ..._models import BaseModel +from .response_input_file import ResponseInputFile +from .response_input_text import ResponseInputText +from .response_input_image import ResponseInputImage + +__all__ = ["ResponsePrompt", "Variables"] + +Variables: TypeAlias = Union[str, ResponseInputText, ResponseInputImage, ResponseInputFile] + + +class ResponsePrompt(BaseModel): + id: str + """The unique identifier of the prompt template to use.""" + + variables: Optional[Dict[str, Variables]] = None + """Optional map of values to substitute in for variables in your prompt. + + The substitution values can either be strings, or other Response input types + like images or files. + """ + + version: Optional[str] = None + """Optional version of the prompt template.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt_param.py new file mode 100644 index 0000000000000000000000000000000000000000..d935fa51914c0210832ce8d77b3151c6446afb5b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_prompt_param.py @@ -0,0 +1,29 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Required, TypeAlias, TypedDict + +from .response_input_file_param import ResponseInputFileParam +from .response_input_text_param import ResponseInputTextParam +from .response_input_image_param import ResponseInputImageParam + +__all__ = ["ResponsePromptParam", "Variables"] + +Variables: TypeAlias = Union[str, ResponseInputTextParam, ResponseInputImageParam, ResponseInputFileParam] + + +class ResponsePromptParam(TypedDict, total=False): + id: Required[str] + """The unique identifier of the prompt template to use.""" + + variables: Optional[Dict[str, Variables]] + """Optional map of values to substitute in for variables in your prompt. + + The substitution values can either be strings, or other Response input types + like images or files. + """ + + version: Optional[str] + """Optional version of the prompt template.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_queued_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_queued_event.py new file mode 100644 index 0000000000000000000000000000000000000000..40257408a43855a3425f2aad904cd552b1da9bef --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_queued_event.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .response import Response +from ..._models import BaseModel + +__all__ = ["ResponseQueuedEvent"] + + +class ResponseQueuedEvent(BaseModel): + response: Response + """The full response object that is queued.""" + + sequence_number: int + """The sequence number for this event.""" + + type: Literal["response.queued"] + """The type of the event. Always 'response.queued'.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item.py new file mode 100644 index 0000000000000000000000000000000000000000..fc582cf7c5587142dd3d45850e706caafd01bbb6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item.py @@ -0,0 +1,51 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningItem", "Summary", "Content"] + + +class Summary(BaseModel): + text: str + """A summary of the reasoning output from the model so far.""" + + type: Literal["summary_text"] + """The type of the object. Always `summary_text`.""" + + +class Content(BaseModel): + text: str + """The reasoning text from the model.""" + + type: Literal["reasoning_text"] + """The type of the reasoning text. Always `reasoning_text`.""" + + +class ResponseReasoningItem(BaseModel): + id: str + """The unique identifier of the reasoning content.""" + + summary: List[Summary] + """Reasoning summary content.""" + + type: Literal["reasoning"] + """The type of the object. Always `reasoning`.""" + + content: Optional[List[Content]] = None + """Reasoning text content.""" + + encrypted_content: Optional[str] = None + """ + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + """ + + status: Optional[Literal["in_progress", "completed", "incomplete"]] = None + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item_param.py new file mode 100644 index 0000000000000000000000000000000000000000..56e88ba28de27d70d90422b28bc3a8edc2a7be51 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_item_param.py @@ -0,0 +1,51 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Iterable, Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseReasoningItemParam", "Summary", "Content"] + + +class Summary(TypedDict, total=False): + text: Required[str] + """A summary of the reasoning output from the model so far.""" + + type: Required[Literal["summary_text"]] + """The type of the object. Always `summary_text`.""" + + +class Content(TypedDict, total=False): + text: Required[str] + """The reasoning text from the model.""" + + type: Required[Literal["reasoning_text"]] + """The type of the reasoning text. Always `reasoning_text`.""" + + +class ResponseReasoningItemParam(TypedDict, total=False): + id: Required[str] + """The unique identifier of the reasoning content.""" + + summary: Required[Iterable[Summary]] + """Reasoning summary content.""" + + type: Required[Literal["reasoning"]] + """The type of the object. Always `reasoning`.""" + + content: Iterable[Content] + """Reasoning text content.""" + + encrypted_content: Optional[str] + """ + The encrypted content of the reasoning item - populated when a response is + generated with `reasoning.encrypted_content` in the `include` parameter. + """ + + status: Literal["in_progress", "completed", "incomplete"] + """The status of the item. + + One of `in_progress`, `completed`, or `incomplete`. Populated when items are + returned via API. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_added_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_added_event.py new file mode 100644 index 0000000000000000000000000000000000000000..dc755b253a7148ceb20255eced36b34f0dd438db --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_added_event.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningSummaryPartAddedEvent", "Part"] + + +class Part(BaseModel): + text: str + """The text of the summary part.""" + + type: Literal["summary_text"] + """The type of the summary part. Always `summary_text`.""" + + +class ResponseReasoningSummaryPartAddedEvent(BaseModel): + item_id: str + """The ID of the item this summary part is associated with.""" + + output_index: int + """The index of the output item this summary part is associated with.""" + + part: Part + """The summary part that was added.""" + + sequence_number: int + """The sequence number of this event.""" + + summary_index: int + """The index of the summary part within the reasoning summary.""" + + type: Literal["response.reasoning_summary_part.added"] + """The type of the event. Always `response.reasoning_summary_part.added`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..7cc0b56d6677a740e04f8155aa199d9f0068987a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_part_done_event.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningSummaryPartDoneEvent", "Part"] + + +class Part(BaseModel): + text: str + """The text of the summary part.""" + + type: Literal["summary_text"] + """The type of the summary part. Always `summary_text`.""" + + +class ResponseReasoningSummaryPartDoneEvent(BaseModel): + item_id: str + """The ID of the item this summary part is associated with.""" + + output_index: int + """The index of the output item this summary part is associated with.""" + + part: Part + """The completed summary part.""" + + sequence_number: int + """The sequence number of this event.""" + + summary_index: int + """The index of the summary part within the reasoning summary.""" + + type: Literal["response.reasoning_summary_part.done"] + """The type of the event. Always `response.reasoning_summary_part.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..96652991b68ce31e74d65d5d7038d66f49f1e043 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_delta_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningSummaryTextDeltaEvent"] + + +class ResponseReasoningSummaryTextDeltaEvent(BaseModel): + delta: str + """The text delta that was added to the summary.""" + + item_id: str + """The ID of the item this summary text delta is associated with.""" + + output_index: int + """The index of the output item this summary text delta is associated with.""" + + sequence_number: int + """The sequence number of this event.""" + + summary_index: int + """The index of the summary part within the reasoning summary.""" + + type: Literal["response.reasoning_summary_text.delta"] + """The type of the event. Always `response.reasoning_summary_text.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b35b82316ae85ef5cb84c113e3acc3022c338c2e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_summary_text_done_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningSummaryTextDoneEvent"] + + +class ResponseReasoningSummaryTextDoneEvent(BaseModel): + item_id: str + """The ID of the item this summary text is associated with.""" + + output_index: int + """The index of the output item this summary text is associated with.""" + + sequence_number: int + """The sequence number of this event.""" + + summary_index: int + """The index of the summary part within the reasoning summary.""" + + text: str + """The full text of the completed reasoning summary.""" + + type: Literal["response.reasoning_summary_text.done"] + """The type of the event. Always `response.reasoning_summary_text.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..e1df893bac81361a4200349ccc7ac38ee68061db --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_delta_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningTextDeltaEvent"] + + +class ResponseReasoningTextDeltaEvent(BaseModel): + content_index: int + """The index of the reasoning content part this delta is associated with.""" + + delta: str + """The text delta that was added to the reasoning content.""" + + item_id: str + """The ID of the item this reasoning text delta is associated with.""" + + output_index: int + """The index of the output item this reasoning text delta is associated with.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.reasoning_text.delta"] + """The type of the event. Always `response.reasoning_text.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..d22d984e478f8203a4424aec3e4eb87f620467c4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_reasoning_text_done_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseReasoningTextDoneEvent"] + + +class ResponseReasoningTextDoneEvent(BaseModel): + content_index: int + """The index of the reasoning content part.""" + + item_id: str + """The ID of the item this reasoning text is associated with.""" + + output_index: int + """The index of the output item this reasoning text is associated with.""" + + sequence_number: int + """The sequence number of this event.""" + + text: str + """The full text of the completed reasoning content.""" + + type: Literal["response.reasoning_text.done"] + """The type of the event. Always `response.reasoning_text.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..03c903ed2818b235a2f21ccbcf36454ea0dc96c9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_delta_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseRefusalDeltaEvent"] + + +class ResponseRefusalDeltaEvent(BaseModel): + content_index: int + """The index of the content part that the refusal text is added to.""" + + delta: str + """The refusal text that is added.""" + + item_id: str + """The ID of the output item that the refusal text is added to.""" + + output_index: int + """The index of the output item that the refusal text is added to.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.refusal.delta"] + """The type of the event. Always `response.refusal.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..61fd51aab00508952bd53165f1dfb3f72c9bc6d7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_refusal_done_event.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseRefusalDoneEvent"] + + +class ResponseRefusalDoneEvent(BaseModel): + content_index: int + """The index of the content part that the refusal text is finalized.""" + + item_id: str + """The ID of the output item that the refusal text is finalized.""" + + output_index: int + """The index of the output item that the refusal text is finalized.""" + + refusal: str + """The refusal text that is finalized.""" + + sequence_number: int + """The sequence number of this event.""" + + type: Literal["response.refusal.done"] + """The type of the event. Always `response.refusal.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_retrieve_params.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_retrieve_params.py new file mode 100644 index 0000000000000000000000000000000000000000..4013db85cef816ad7d0c90bf5f11a2ab39bf8d5d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_retrieve_params.py @@ -0,0 +1,59 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import List, Union +from typing_extensions import Literal, Required, TypedDict + +from .response_includable import ResponseIncludable + +__all__ = ["ResponseRetrieveParamsBase", "ResponseRetrieveParamsNonStreaming", "ResponseRetrieveParamsStreaming"] + + +class ResponseRetrieveParamsBase(TypedDict, total=False): + include: List[ResponseIncludable] + """Additional fields to include in the response. + + See the `include` parameter for Response creation above for more information. + """ + + include_obfuscation: bool + """When true, stream obfuscation will be enabled. + + Stream obfuscation adds random characters to an `obfuscation` field on streaming + delta events to normalize payload sizes as a mitigation to certain side-channel + attacks. These obfuscation fields are included by default, but add a small + amount of overhead to the data stream. You can set `include_obfuscation` to + false to optimize for bandwidth if you trust the network links between your + application and the OpenAI API. + """ + + starting_after: int + """The sequence number of the event after which to start streaming.""" + + +class ResponseRetrieveParamsNonStreaming(ResponseRetrieveParamsBase, total=False): + stream: Literal[False] + """ + If set to true, the model response data will be streamed to the client as it is + generated using + [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the + [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + """ + + +class ResponseRetrieveParamsStreaming(ResponseRetrieveParamsBase): + stream: Required[Literal[True]] + """ + If set to true, the model response data will be streamed to the client as it is + generated using + [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format). + See the + [Streaming section below](https://platform.openai.com/docs/api-reference/responses-streaming) + for more information. + """ + + +ResponseRetrieveParams = Union[ResponseRetrieveParamsNonStreaming, ResponseRetrieveParamsStreaming] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_status.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_status.py new file mode 100644 index 0000000000000000000000000000000000000000..a7887b92d2932e830f634b0b6863396569180319 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_status.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ResponseStatus"] + +ResponseStatus: TypeAlias = Literal["completed", "failed", "in_progress", "cancelled", "queued", "incomplete"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_stream_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_stream_event.py new file mode 100644 index 0000000000000000000000000000000000000000..c0a317cd9dff7f2bdb80881c9f34dd5e21c5dda1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_stream_event.py @@ -0,0 +1,120 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .response_error_event import ResponseErrorEvent +from .response_failed_event import ResponseFailedEvent +from .response_queued_event import ResponseQueuedEvent +from .response_created_event import ResponseCreatedEvent +from .response_completed_event import ResponseCompletedEvent +from .response_text_done_event import ResponseTextDoneEvent +from .response_audio_done_event import ResponseAudioDoneEvent +from .response_incomplete_event import ResponseIncompleteEvent +from .response_text_delta_event import ResponseTextDeltaEvent +from .response_audio_delta_event import ResponseAudioDeltaEvent +from .response_in_progress_event import ResponseInProgressEvent +from .response_refusal_done_event import ResponseRefusalDoneEvent +from .response_refusal_delta_event import ResponseRefusalDeltaEvent +from .response_mcp_call_failed_event import ResponseMcpCallFailedEvent +from .response_output_item_done_event import ResponseOutputItemDoneEvent +from .response_content_part_done_event import ResponseContentPartDoneEvent +from .response_output_item_added_event import ResponseOutputItemAddedEvent +from .response_content_part_added_event import ResponseContentPartAddedEvent +from .response_mcp_call_completed_event import ResponseMcpCallCompletedEvent +from .response_reasoning_text_done_event import ResponseReasoningTextDoneEvent +from .response_mcp_call_in_progress_event import ResponseMcpCallInProgressEvent +from .response_reasoning_text_delta_event import ResponseReasoningTextDeltaEvent +from .response_audio_transcript_done_event import ResponseAudioTranscriptDoneEvent +from .response_mcp_list_tools_failed_event import ResponseMcpListToolsFailedEvent +from .response_audio_transcript_delta_event import ResponseAudioTranscriptDeltaEvent +from .response_mcp_call_arguments_done_event import ResponseMcpCallArgumentsDoneEvent +from .response_image_gen_call_completed_event import ResponseImageGenCallCompletedEvent +from .response_mcp_call_arguments_delta_event import ResponseMcpCallArgumentsDeltaEvent +from .response_mcp_list_tools_completed_event import ResponseMcpListToolsCompletedEvent +from .response_image_gen_call_generating_event import ResponseImageGenCallGeneratingEvent +from .response_web_search_call_completed_event import ResponseWebSearchCallCompletedEvent +from .response_web_search_call_searching_event import ResponseWebSearchCallSearchingEvent +from .response_file_search_call_completed_event import ResponseFileSearchCallCompletedEvent +from .response_file_search_call_searching_event import ResponseFileSearchCallSearchingEvent +from .response_image_gen_call_in_progress_event import ResponseImageGenCallInProgressEvent +from .response_mcp_list_tools_in_progress_event import ResponseMcpListToolsInProgressEvent +from .response_custom_tool_call_input_done_event import ResponseCustomToolCallInputDoneEvent +from .response_reasoning_summary_part_done_event import ResponseReasoningSummaryPartDoneEvent +from .response_reasoning_summary_text_done_event import ResponseReasoningSummaryTextDoneEvent +from .response_web_search_call_in_progress_event import ResponseWebSearchCallInProgressEvent +from .response_custom_tool_call_input_delta_event import ResponseCustomToolCallInputDeltaEvent +from .response_file_search_call_in_progress_event import ResponseFileSearchCallInProgressEvent +from .response_function_call_arguments_done_event import ResponseFunctionCallArgumentsDoneEvent +from .response_image_gen_call_partial_image_event import ResponseImageGenCallPartialImageEvent +from .response_output_text_annotation_added_event import ResponseOutputTextAnnotationAddedEvent +from .response_reasoning_summary_part_added_event import ResponseReasoningSummaryPartAddedEvent +from .response_reasoning_summary_text_delta_event import ResponseReasoningSummaryTextDeltaEvent +from .response_function_call_arguments_delta_event import ResponseFunctionCallArgumentsDeltaEvent +from .response_code_interpreter_call_code_done_event import ResponseCodeInterpreterCallCodeDoneEvent +from .response_code_interpreter_call_completed_event import ResponseCodeInterpreterCallCompletedEvent +from .response_code_interpreter_call_code_delta_event import ResponseCodeInterpreterCallCodeDeltaEvent +from .response_code_interpreter_call_in_progress_event import ResponseCodeInterpreterCallInProgressEvent +from .response_code_interpreter_call_interpreting_event import ResponseCodeInterpreterCallInterpretingEvent + +__all__ = ["ResponseStreamEvent"] + +ResponseStreamEvent: TypeAlias = Annotated[ + Union[ + ResponseAudioDeltaEvent, + ResponseAudioDoneEvent, + ResponseAudioTranscriptDeltaEvent, + ResponseAudioTranscriptDoneEvent, + ResponseCodeInterpreterCallCodeDeltaEvent, + ResponseCodeInterpreterCallCodeDoneEvent, + ResponseCodeInterpreterCallCompletedEvent, + ResponseCodeInterpreterCallInProgressEvent, + ResponseCodeInterpreterCallInterpretingEvent, + ResponseCompletedEvent, + ResponseContentPartAddedEvent, + ResponseContentPartDoneEvent, + ResponseCreatedEvent, + ResponseErrorEvent, + ResponseFileSearchCallCompletedEvent, + ResponseFileSearchCallInProgressEvent, + ResponseFileSearchCallSearchingEvent, + ResponseFunctionCallArgumentsDeltaEvent, + ResponseFunctionCallArgumentsDoneEvent, + ResponseInProgressEvent, + ResponseFailedEvent, + ResponseIncompleteEvent, + ResponseOutputItemAddedEvent, + ResponseOutputItemDoneEvent, + ResponseReasoningSummaryPartAddedEvent, + ResponseReasoningSummaryPartDoneEvent, + ResponseReasoningSummaryTextDeltaEvent, + ResponseReasoningSummaryTextDoneEvent, + ResponseReasoningTextDeltaEvent, + ResponseReasoningTextDoneEvent, + ResponseRefusalDeltaEvent, + ResponseRefusalDoneEvent, + ResponseTextDeltaEvent, + ResponseTextDoneEvent, + ResponseWebSearchCallCompletedEvent, + ResponseWebSearchCallInProgressEvent, + ResponseWebSearchCallSearchingEvent, + ResponseImageGenCallCompletedEvent, + ResponseImageGenCallGeneratingEvent, + ResponseImageGenCallInProgressEvent, + ResponseImageGenCallPartialImageEvent, + ResponseMcpCallArgumentsDeltaEvent, + ResponseMcpCallArgumentsDoneEvent, + ResponseMcpCallCompletedEvent, + ResponseMcpCallFailedEvent, + ResponseMcpCallInProgressEvent, + ResponseMcpListToolsCompletedEvent, + ResponseMcpListToolsFailedEvent, + ResponseMcpListToolsInProgressEvent, + ResponseOutputTextAnnotationAddedEvent, + ResponseQueuedEvent, + ResponseCustomToolCallInputDeltaEvent, + ResponseCustomToolCallInputDoneEvent, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config.py new file mode 100644 index 0000000000000000000000000000000000000000..c53546da6df71539f05b0c3cf85789ec2c220861 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .response_format_text_config import ResponseFormatTextConfig + +__all__ = ["ResponseTextConfig"] + + +class ResponseTextConfig(BaseModel): + format: Optional[ResponseFormatTextConfig] = None + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + verbosity: Optional[Literal["low", "medium", "high"]] = None + """Constrains the verbosity of the model's response. + + Lower values will result in more concise responses, while higher values will + result in more verbose responses. Currently supported values are `low`, + `medium`, and `high`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config_param.py new file mode 100644 index 0000000000000000000000000000000000000000..1229fce35b725fa3f8cf7d26bee5c057b95688c5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_config_param.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, TypedDict + +from .response_format_text_config_param import ResponseFormatTextConfigParam + +__all__ = ["ResponseTextConfigParam"] + + +class ResponseTextConfigParam(TypedDict, total=False): + format: ResponseFormatTextConfigParam + """An object specifying the format that the model must output. + + Configuring `{ "type": "json_schema" }` enables Structured Outputs, which + ensures the model will match your supplied JSON schema. Learn more in the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + + The default format is `{ "type": "text" }` with no additional options. + + **Not recommended for gpt-4o and newer models:** + + Setting to `{ "type": "json_object" }` enables the older JSON mode, which + ensures the message the model generates is valid JSON. Using `json_schema` is + preferred for models that support it. + """ + + verbosity: Optional[Literal["low", "medium", "high"]] + """Constrains the verbosity of the model's response. + + Lower values will result in more concise responses, while higher values will + result in more verbose responses. Currently supported values are `low`, + `medium`, and `high`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_delta_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_delta_event.py new file mode 100644 index 0000000000000000000000000000000000000000..b5379b7ac3258a09bce11ff9c324756df7050f14 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_delta_event.py @@ -0,0 +1,50 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseTextDeltaEvent", "Logprob", "LogprobTopLogprob"] + + +class LogprobTopLogprob(BaseModel): + token: Optional[str] = None + """A possible text token.""" + + logprob: Optional[float] = None + """The log probability of this token.""" + + +class Logprob(BaseModel): + token: str + """A possible text token.""" + + logprob: float + """The log probability of this token.""" + + top_logprobs: Optional[List[LogprobTopLogprob]] = None + """The log probability of the top 20 most likely tokens.""" + + +class ResponseTextDeltaEvent(BaseModel): + content_index: int + """The index of the content part that the text delta was added to.""" + + delta: str + """The text delta that was added.""" + + item_id: str + """The ID of the output item that the text delta was added to.""" + + logprobs: List[Logprob] + """The log probabilities of the tokens in the delta.""" + + output_index: int + """The index of the output item that the text delta was added to.""" + + sequence_number: int + """The sequence number for this event.""" + + type: Literal["response.output_text.delta"] + """The type of the event. Always `response.output_text.delta`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_done_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_done_event.py new file mode 100644 index 0000000000000000000000000000000000000000..d9776a1844b9d59d24d4b62c7074170a7427e72a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_text_done_event.py @@ -0,0 +1,50 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseTextDoneEvent", "Logprob", "LogprobTopLogprob"] + + +class LogprobTopLogprob(BaseModel): + token: Optional[str] = None + """A possible text token.""" + + logprob: Optional[float] = None + """The log probability of this token.""" + + +class Logprob(BaseModel): + token: str + """A possible text token.""" + + logprob: float + """The log probability of this token.""" + + top_logprobs: Optional[List[LogprobTopLogprob]] = None + """The log probability of the top 20 most likely tokens.""" + + +class ResponseTextDoneEvent(BaseModel): + content_index: int + """The index of the content part that the text content is finalized.""" + + item_id: str + """The ID of the output item that the text content is finalized.""" + + logprobs: List[Logprob] + """The log probabilities of the tokens in the delta.""" + + output_index: int + """The index of the output item that the text content is finalized.""" + + sequence_number: int + """The sequence number for this event.""" + + text: str + """The text content that is finalized.""" + + type: Literal["response.output_text.done"] + """The type of the event. Always `response.output_text.done`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_usage.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_usage.py new file mode 100644 index 0000000000000000000000000000000000000000..52b93ac5783970194cba4398b62d6485bec69e5b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_usage.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from ..._models import BaseModel + +__all__ = ["ResponseUsage", "InputTokensDetails", "OutputTokensDetails"] + + +class InputTokensDetails(BaseModel): + cached_tokens: int + """The number of tokens that were retrieved from the cache. + + [More on prompt caching](https://platform.openai.com/docs/guides/prompt-caching). + """ + + +class OutputTokensDetails(BaseModel): + reasoning_tokens: int + """The number of reasoning tokens.""" + + +class ResponseUsage(BaseModel): + input_tokens: int + """The number of input tokens.""" + + input_tokens_details: InputTokensDetails + """A detailed breakdown of the input tokens.""" + + output_tokens: int + """The number of output tokens.""" + + output_tokens_details: OutputTokensDetails + """A detailed breakdown of the output tokens.""" + + total_tokens: int + """The total number of tokens used.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_completed_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_completed_event.py new file mode 100644 index 0000000000000000000000000000000000000000..497f7bfe35b4f7d0225dd6fdb99836eb80dab282 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_completed_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseWebSearchCallCompletedEvent"] + + +class ResponseWebSearchCallCompletedEvent(BaseModel): + item_id: str + """Unique ID for the output item associated with the web search call.""" + + output_index: int + """The index of the output item that the web search call is associated with.""" + + sequence_number: int + """The sequence number of the web search call being processed.""" + + type: Literal["response.web_search_call.completed"] + """The type of the event. Always `response.web_search_call.completed`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_in_progress_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_in_progress_event.py new file mode 100644 index 0000000000000000000000000000000000000000..da8b3fe404506b217dbd3a4d888e513f3cbb42df --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_in_progress_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseWebSearchCallInProgressEvent"] + + +class ResponseWebSearchCallInProgressEvent(BaseModel): + item_id: str + """Unique ID for the output item associated with the web search call.""" + + output_index: int + """The index of the output item that the web search call is associated with.""" + + sequence_number: int + """The sequence number of the web search call being processed.""" + + type: Literal["response.web_search_call.in_progress"] + """The type of the event. Always `response.web_search_call.in_progress`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_searching_event.py b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_searching_event.py new file mode 100644 index 0000000000000000000000000000000000000000..42df9cb2985cc5ce5a002554a7954c08b8d57f88 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/response_web_search_call_searching_event.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseWebSearchCallSearchingEvent"] + + +class ResponseWebSearchCallSearchingEvent(BaseModel): + item_id: str + """Unique ID for the output item associated with the web search call.""" + + output_index: int + """The index of the output item that the web search call is associated with.""" + + sequence_number: int + """The sequence number of the web search call being processed.""" + + type: Literal["response.web_search_call.searching"] + """The type of the event. Always `response.web_search_call.searching`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool.py new file mode 100644 index 0000000000000000000000000000000000000000..8dd2bd598108be56b458aaf12a2f45df4ad9961a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool.py @@ -0,0 +1,264 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal, Annotated, TypeAlias + +from . import web_search_tool +from ..._utils import PropertyInfo +from ..._models import BaseModel +from .custom_tool import CustomTool +from .computer_tool import ComputerTool +from .function_tool import FunctionTool +from .web_search_tool import WebSearchTool +from .file_search_tool import FileSearchTool +from .web_search_preview_tool import WebSearchPreviewTool + +__all__ = [ + "Tool", + "WebSearchTool", + "Mcp", + "McpAllowedTools", + "McpAllowedToolsMcpToolFilter", + "McpRequireApproval", + "McpRequireApprovalMcpToolApprovalFilter", + "McpRequireApprovalMcpToolApprovalFilterAlways", + "McpRequireApprovalMcpToolApprovalFilterNever", + "CodeInterpreter", + "CodeInterpreterContainer", + "CodeInterpreterContainerCodeInterpreterToolAuto", + "ImageGeneration", + "ImageGenerationInputImageMask", + "LocalShell", +] + +WebSearchToolFilters = web_search_tool.Filters +WebSearchToolUserLocation = web_search_tool.UserLocation + + +class McpAllowedToolsMcpToolFilter(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +McpAllowedTools: TypeAlias = Union[List[str], McpAllowedToolsMcpToolFilter, None] + + +class McpRequireApprovalMcpToolApprovalFilterAlways(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilterNever(BaseModel): + read_only: Optional[bool] = None + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: Optional[List[str]] = None + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilter(BaseModel): + always: Optional[McpRequireApprovalMcpToolApprovalFilterAlways] = None + """A filter object to specify which tools are allowed.""" + + never: Optional[McpRequireApprovalMcpToolApprovalFilterNever] = None + """A filter object to specify which tools are allowed.""" + + +McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"], None] + + +class Mcp(BaseModel): + server_label: str + """A label for this MCP server, used to identify it in tool calls.""" + + type: Literal["mcp"] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[McpAllowedTools] = None + """List of allowed tool names or a filter object.""" + + authorization: Optional[str] = None + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Optional[ + Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + ] = None + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] = None + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[McpRequireApproval] = None + """Specify which of the MCP server's tools require approval.""" + + server_description: Optional[str] = None + """Optional description of the MCP server, used to provide more context.""" + + server_url: Optional[str] = None + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +class CodeInterpreterContainerCodeInterpreterToolAuto(BaseModel): + type: Literal["auto"] + """Always `auto`.""" + + file_ids: Optional[List[str]] = None + """An optional list of uploaded files to make available to your code.""" + + +CodeInterpreterContainer: TypeAlias = Union[str, CodeInterpreterContainerCodeInterpreterToolAuto] + + +class CodeInterpreter(BaseModel): + container: CodeInterpreterContainer + """The code interpreter container. + + Can be a container ID or an object that specifies uploaded file IDs to make + available to your code. + """ + + type: Literal["code_interpreter"] + """The type of the code interpreter tool. Always `code_interpreter`.""" + + +class ImageGenerationInputImageMask(BaseModel): + file_id: Optional[str] = None + """File ID for the mask image.""" + + image_url: Optional[str] = None + """Base64-encoded mask image.""" + + +class ImageGeneration(BaseModel): + type: Literal["image_generation"] + """The type of the image generation tool. Always `image_generation`.""" + + background: Optional[Literal["transparent", "opaque", "auto"]] = None + """Background type for the generated image. + + One of `transparent`, `opaque`, or `auto`. Default: `auto`. + """ + + input_fidelity: Optional[Literal["high", "low"]] = None + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. This parameter is only supported + for `gpt-image-1`. Supports `high` and `low`. Defaults to `low`. + """ + + input_image_mask: Optional[ImageGenerationInputImageMask] = None + """Optional mask for inpainting. + + Contains `image_url` (string, optional) and `file_id` (string, optional). + """ + + model: Optional[Literal["gpt-image-1"]] = None + """The image generation model to use. Default: `gpt-image-1`.""" + + moderation: Optional[Literal["auto", "low"]] = None + """Moderation level for the generated image. Default: `auto`.""" + + output_compression: Optional[int] = None + """Compression level for the output image. Default: 100.""" + + output_format: Optional[Literal["png", "webp", "jpeg"]] = None + """The output format of the generated image. + + One of `png`, `webp`, or `jpeg`. Default: `png`. + """ + + partial_images: Optional[int] = None + """ + Number of partial images to generate in streaming mode, from 0 (default value) + to 3. + """ + + quality: Optional[Literal["low", "medium", "high", "auto"]] = None + """The quality of the generated image. + + One of `low`, `medium`, `high`, or `auto`. Default: `auto`. + """ + + size: Optional[Literal["1024x1024", "1024x1536", "1536x1024", "auto"]] = None + """The size of the generated image. + + One of `1024x1024`, `1024x1536`, `1536x1024`, or `auto`. Default: `auto`. + """ + + +class LocalShell(BaseModel): + type: Literal["local_shell"] + """The type of the local shell tool. Always `local_shell`.""" + + +Tool: TypeAlias = Annotated[ + Union[ + FunctionTool, + FileSearchTool, + ComputerTool, + WebSearchTool, + Mcp, + CodeInterpreter, + ImageGeneration, + LocalShell, + CustomTool, + WebSearchPreviewTool, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed.py new file mode 100644 index 0000000000000000000000000000000000000000..d7921dcb2a35d15216cce630bdb781882ad90594 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ToolChoiceAllowed"] + + +class ToolChoiceAllowed(BaseModel): + mode: Literal["auto", "required"] + """Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + """ + + tools: List[Dict[str, object]] + """A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + """ + + type: Literal["allowed_tools"] + """Allowed tool configuration type. Always `allowed_tools`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0712cab43be2937be548006cb727a8820a5eba0f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_allowed_param.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Iterable +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ToolChoiceAllowedParam"] + + +class ToolChoiceAllowedParam(TypedDict, total=False): + mode: Required[Literal["auto", "required"]] + """Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + """ + + tools: Required[Iterable[Dict[str, object]]] + """A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + """ + + type: Required[Literal["allowed_tools"]] + """Allowed tool configuration type. Always `allowed_tools`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom.py new file mode 100644 index 0000000000000000000000000000000000000000..d600e536168da22d5def4f49faaff64dd67706b3 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ToolChoiceCustom"] + + +class ToolChoiceCustom(BaseModel): + name: str + """The name of the custom tool to call.""" + + type: Literal["custom"] + """For custom tool calling, the type is always `custom`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom_param.py new file mode 100644 index 0000000000000000000000000000000000000000..55bc53b730d3d2ea786b9c351424fb9adbef2253 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_custom_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ToolChoiceCustomParam"] + + +class ToolChoiceCustomParam(TypedDict, total=False): + name: Required[str] + """The name of the custom tool to call.""" + + type: Required[Literal["custom"]] + """For custom tool calling, the type is always `custom`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function.py new file mode 100644 index 0000000000000000000000000000000000000000..8d2a4f2822f40f8c8a30b3035e4cee96de848909 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ToolChoiceFunction"] + + +class ToolChoiceFunction(BaseModel): + name: str + """The name of the function to call.""" + + type: Literal["function"] + """For function calling, the type is always `function`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function_param.py new file mode 100644 index 0000000000000000000000000000000000000000..910537fd970618e4124b131c1765ab35158cb025 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_function_param.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ToolChoiceFunctionParam"] + + +class ToolChoiceFunctionParam(TypedDict, total=False): + name: Required[str] + """The name of the function to call.""" + + type: Required[Literal["function"]] + """For function calling, the type is always `function`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp.py new file mode 100644 index 0000000000000000000000000000000000000000..8763d81635b9a39f670ef0dcc956c4e14cdf57c0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ToolChoiceMcp"] + + +class ToolChoiceMcp(BaseModel): + server_label: str + """The label of the MCP server to use.""" + + type: Literal["mcp"] + """For MCP tools, the type is always `mcp`.""" + + name: Optional[str] = None + """The name of the tool to call on the server.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp_param.py new file mode 100644 index 0000000000000000000000000000000000000000..afcceb8cc5764b207306e383f0d2a0e1e1b24b57 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_mcp_param.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ToolChoiceMcpParam"] + + +class ToolChoiceMcpParam(TypedDict, total=False): + server_label: Required[str] + """The label of the MCP server to use.""" + + type: Required[Literal["mcp"]] + """For MCP tools, the type is always `mcp`.""" + + name: Optional[str] + """The name of the tool to call on the server.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_options.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_options.py new file mode 100644 index 0000000000000000000000000000000000000000..c200db54e1f546a9712720773c57f1f8ec7f68bb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_options.py @@ -0,0 +1,7 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ToolChoiceOptions"] + +ToolChoiceOptions: TypeAlias = Literal["none", "auto", "required"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types.py new file mode 100644 index 0000000000000000000000000000000000000000..b31a82605171f0dcd7523d5205563eb140fe9339 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types.py @@ -0,0 +1,31 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ToolChoiceTypes"] + + +class ToolChoiceTypes(BaseModel): + type: Literal[ + "file_search", + "web_search_preview", + "computer_use_preview", + "web_search_preview_2025_03_11", + "image_generation", + "code_interpreter", + ] + """The type of hosted tool the model should to use. + + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer_use_preview` + - `code_interpreter` + - `image_generation` + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types_param.py new file mode 100644 index 0000000000000000000000000000000000000000..15e0357471115abfc7a0ebb2fe15acdd4dba5610 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_choice_types_param.py @@ -0,0 +1,33 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ToolChoiceTypesParam"] + + +class ToolChoiceTypesParam(TypedDict, total=False): + type: Required[ + Literal[ + "file_search", + "web_search_preview", + "computer_use_preview", + "web_search_preview_2025_03_11", + "image_generation", + "code_interpreter", + ] + ] + """The type of hosted tool the model should to use. + + Learn more about + [built-in tools](https://platform.openai.com/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer_use_preview` + - `code_interpreter` + - `image_generation` + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..e84abc439077869a0122afeb23e38fcd37e0328c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/tool_param.py @@ -0,0 +1,264 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from . import web_search_tool_param +from ..chat import ChatCompletionFunctionToolParam +from ..._types import SequenceNotStr +from .custom_tool_param import CustomToolParam +from .computer_tool_param import ComputerToolParam +from .function_tool_param import FunctionToolParam +from .web_search_tool_param import WebSearchToolParam +from .file_search_tool_param import FileSearchToolParam +from .web_search_preview_tool_param import WebSearchPreviewToolParam + +__all__ = [ + "ToolParam", + "Mcp", + "McpAllowedTools", + "McpAllowedToolsMcpToolFilter", + "McpRequireApproval", + "McpRequireApprovalMcpToolApprovalFilter", + "McpRequireApprovalMcpToolApprovalFilterAlways", + "McpRequireApprovalMcpToolApprovalFilterNever", + "CodeInterpreter", + "CodeInterpreterContainer", + "CodeInterpreterContainerCodeInterpreterToolAuto", + "ImageGeneration", + "ImageGenerationInputImageMask", + "LocalShell", +] + +WebSearchTool = web_search_tool_param.WebSearchToolParam +WebSearchToolFilters = web_search_tool_param.Filters +WebSearchToolUserLocation = web_search_tool_param.UserLocation + + +class McpAllowedToolsMcpToolFilter(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +McpAllowedTools: TypeAlias = Union[SequenceNotStr[str], McpAllowedToolsMcpToolFilter] + + +class McpRequireApprovalMcpToolApprovalFilterAlways(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilterNever(TypedDict, total=False): + read_only: bool + """Indicates whether or not a tool modifies data or is read-only. + + If an MCP server is + [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + """ + + tool_names: SequenceNotStr[str] + """List of allowed tool names.""" + + +class McpRequireApprovalMcpToolApprovalFilter(TypedDict, total=False): + always: McpRequireApprovalMcpToolApprovalFilterAlways + """A filter object to specify which tools are allowed.""" + + never: McpRequireApprovalMcpToolApprovalFilterNever + """A filter object to specify which tools are allowed.""" + + +McpRequireApproval: TypeAlias = Union[McpRequireApprovalMcpToolApprovalFilter, Literal["always", "never"]] + + +class Mcp(TypedDict, total=False): + server_label: Required[str] + """A label for this MCP server, used to identify it in tool calls.""" + + type: Required[Literal["mcp"]] + """The type of the MCP tool. Always `mcp`.""" + + allowed_tools: Optional[McpAllowedTools] + """List of allowed tool names or a filter object.""" + + authorization: str + """ + An OAuth access token that can be used with a remote MCP server, either with a + custom MCP server URL or a service connector. Your application must handle the + OAuth authorization flow and provide the token here. + """ + + connector_id: Literal[ + "connector_dropbox", + "connector_gmail", + "connector_googlecalendar", + "connector_googledrive", + "connector_microsoftteams", + "connector_outlookcalendar", + "connector_outlookemail", + "connector_sharepoint", + ] + """Identifier for service connectors, like those available in ChatGPT. + + One of `server_url` or `connector_id` must be provided. Learn more about service + connectors + [here](https://platform.openai.com/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + """ + + headers: Optional[Dict[str, str]] + """Optional HTTP headers to send to the MCP server. + + Use for authentication or other purposes. + """ + + require_approval: Optional[McpRequireApproval] + """Specify which of the MCP server's tools require approval.""" + + server_description: str + """Optional description of the MCP server, used to provide more context.""" + + server_url: str + """The URL for the MCP server. + + One of `server_url` or `connector_id` must be provided. + """ + + +class CodeInterpreterContainerCodeInterpreterToolAuto(TypedDict, total=False): + type: Required[Literal["auto"]] + """Always `auto`.""" + + file_ids: SequenceNotStr[str] + """An optional list of uploaded files to make available to your code.""" + + +CodeInterpreterContainer: TypeAlias = Union[str, CodeInterpreterContainerCodeInterpreterToolAuto] + + +class CodeInterpreter(TypedDict, total=False): + container: Required[CodeInterpreterContainer] + """The code interpreter container. + + Can be a container ID or an object that specifies uploaded file IDs to make + available to your code. + """ + + type: Required[Literal["code_interpreter"]] + """The type of the code interpreter tool. Always `code_interpreter`.""" + + +class ImageGenerationInputImageMask(TypedDict, total=False): + file_id: str + """File ID for the mask image.""" + + image_url: str + """Base64-encoded mask image.""" + + +class ImageGeneration(TypedDict, total=False): + type: Required[Literal["image_generation"]] + """The type of the image generation tool. Always `image_generation`.""" + + background: Literal["transparent", "opaque", "auto"] + """Background type for the generated image. + + One of `transparent`, `opaque`, or `auto`. Default: `auto`. + """ + + input_fidelity: Optional[Literal["high", "low"]] + """ + Control how much effort the model will exert to match the style and features, + especially facial features, of input images. This parameter is only supported + for `gpt-image-1`. Supports `high` and `low`. Defaults to `low`. + """ + + input_image_mask: ImageGenerationInputImageMask + """Optional mask for inpainting. + + Contains `image_url` (string, optional) and `file_id` (string, optional). + """ + + model: Literal["gpt-image-1"] + """The image generation model to use. Default: `gpt-image-1`.""" + + moderation: Literal["auto", "low"] + """Moderation level for the generated image. Default: `auto`.""" + + output_compression: int + """Compression level for the output image. Default: 100.""" + + output_format: Literal["png", "webp", "jpeg"] + """The output format of the generated image. + + One of `png`, `webp`, or `jpeg`. Default: `png`. + """ + + partial_images: int + """ + Number of partial images to generate in streaming mode, from 0 (default value) + to 3. + """ + + quality: Literal["low", "medium", "high", "auto"] + """The quality of the generated image. + + One of `low`, `medium`, `high`, or `auto`. Default: `auto`. + """ + + size: Literal["1024x1024", "1024x1536", "1536x1024", "auto"] + """The size of the generated image. + + One of `1024x1024`, `1024x1536`, `1536x1024`, or `auto`. Default: `auto`. + """ + + +class LocalShell(TypedDict, total=False): + type: Required[Literal["local_shell"]] + """The type of the local shell tool. Always `local_shell`.""" + + +ToolParam: TypeAlias = Union[ + FunctionToolParam, + FileSearchToolParam, + ComputerToolParam, + WebSearchToolParam, + Mcp, + CodeInterpreter, + ImageGeneration, + LocalShell, + CustomToolParam, + WebSearchPreviewToolParam, +] + + +ParseableToolParam: TypeAlias = Union[ToolParam, ChatCompletionFunctionToolParam] diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..66d6a2467939b672724ddecca071597298e35529 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool.py @@ -0,0 +1,49 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["WebSearchPreviewTool", "UserLocation"] + + +class UserLocation(BaseModel): + type: Literal["approximate"] + """The type of location approximation. Always `approximate`.""" + + city: Optional[str] = None + """Free text input for the city of the user, e.g. `San Francisco`.""" + + country: Optional[str] = None + """ + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + the user, e.g. `US`. + """ + + region: Optional[str] = None + """Free text input for the region of the user, e.g. `California`.""" + + timezone: Optional[str] = None + """ + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + user, e.g. `America/Los_Angeles`. + """ + + +class WebSearchPreviewTool(BaseModel): + type: Literal["web_search_preview", "web_search_preview_2025_03_11"] + """The type of the web search tool. + + One of `web_search_preview` or `web_search_preview_2025_03_11`. + """ + + search_context_size: Optional[Literal["low", "medium", "high"]] = None + """High level guidance for the amount of context window space to use for the + search. + + One of `low`, `medium`, or `high`. `medium` is the default. + """ + + user_location: Optional[UserLocation] = None + """The user's location.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..ec2173f8e890ef5f2afeb0d61ceffabf09f964c5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_preview_tool_param.py @@ -0,0 +1,49 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["WebSearchPreviewToolParam", "UserLocation"] + + +class UserLocation(TypedDict, total=False): + type: Required[Literal["approximate"]] + """The type of location approximation. Always `approximate`.""" + + city: Optional[str] + """Free text input for the city of the user, e.g. `San Francisco`.""" + + country: Optional[str] + """ + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + the user, e.g. `US`. + """ + + region: Optional[str] + """Free text input for the region of the user, e.g. `California`.""" + + timezone: Optional[str] + """ + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + user, e.g. `America/Los_Angeles`. + """ + + +class WebSearchPreviewToolParam(TypedDict, total=False): + type: Required[Literal["web_search_preview", "web_search_preview_2025_03_11"]] + """The type of the web search tool. + + One of `web_search_preview` or `web_search_preview_2025_03_11`. + """ + + search_context_size: Literal["low", "medium", "high"] + """High level guidance for the amount of context window space to use for the + search. + + One of `low`, `medium`, or `high`. `medium` is the default. + """ + + user_location: Optional[UserLocation] + """The user's location.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool.py b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool.py new file mode 100644 index 0000000000000000000000000000000000000000..bde9600c873c423d51b98dbe4dffe884a7f22ee1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool.py @@ -0,0 +1,63 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["WebSearchTool", "Filters", "UserLocation"] + + +class Filters(BaseModel): + allowed_domains: Optional[List[str]] = None + """Allowed domains for the search. + + If not provided, all domains are allowed. Subdomains of the provided domains are + allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + """ + + +class UserLocation(BaseModel): + city: Optional[str] = None + """Free text input for the city of the user, e.g. `San Francisco`.""" + + country: Optional[str] = None + """ + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + the user, e.g. `US`. + """ + + region: Optional[str] = None + """Free text input for the region of the user, e.g. `California`.""" + + timezone: Optional[str] = None + """ + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + user, e.g. `America/Los_Angeles`. + """ + + type: Optional[Literal["approximate"]] = None + """The type of location approximation. Always `approximate`.""" + + +class WebSearchTool(BaseModel): + type: Literal["web_search", "web_search_2025_08_26"] + """The type of the web search tool. + + One of `web_search` or `web_search_2025_08_26`. + """ + + filters: Optional[Filters] = None + """Filters for the search.""" + + search_context_size: Optional[Literal["low", "medium", "high"]] = None + """High level guidance for the amount of context window space to use for the + search. + + One of `low`, `medium`, or `high`. `medium` is the default. + """ + + user_location: Optional[UserLocation] = None + """The approximate location of the user.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool_param.py b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool_param.py new file mode 100644 index 0000000000000000000000000000000000000000..7fa19e9c23f788d638e1c7ed87fb9d539e72d907 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/responses/web_search_tool_param.py @@ -0,0 +1,65 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +from ..._types import SequenceNotStr + +__all__ = ["WebSearchToolParam", "Filters", "UserLocation"] + + +class Filters(TypedDict, total=False): + allowed_domains: Optional[SequenceNotStr[str]] + """Allowed domains for the search. + + If not provided, all domains are allowed. Subdomains of the provided domains are + allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + """ + + +class UserLocation(TypedDict, total=False): + city: Optional[str] + """Free text input for the city of the user, e.g. `San Francisco`.""" + + country: Optional[str] + """ + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of + the user, e.g. `US`. + """ + + region: Optional[str] + """Free text input for the region of the user, e.g. `California`.""" + + timezone: Optional[str] + """ + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the + user, e.g. `America/Los_Angeles`. + """ + + type: Literal["approximate"] + """The type of location approximation. Always `approximate`.""" + + +class WebSearchToolParam(TypedDict, total=False): + type: Required[Literal["web_search", "web_search_2025_08_26"]] + """The type of the web search tool. + + One of `web_search` or `web_search_2025_08_26`. + """ + + filters: Optional[Filters] + """Filters for the search.""" + + search_context_size: Literal["low", "medium", "high"] + """High level guidance for the amount of context window space to use for the + search. + + One of `low`, `medium`, or `high`. `medium` is the default. + """ + + user_location: Optional[UserLocation] + """The approximate location of the user.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/shared/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..2930b9ae3bb637be259ce0b3d2831ea75b8f9251 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/__init__.py @@ -0,0 +1,19 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .metadata import Metadata as Metadata +from .reasoning import Reasoning as Reasoning +from .all_models import AllModels as AllModels +from .chat_model import ChatModel as ChatModel +from .error_object import ErrorObject as ErrorObject +from .compound_filter import CompoundFilter as CompoundFilter +from .responses_model import ResponsesModel as ResponsesModel +from .reasoning_effort import ReasoningEffort as ReasoningEffort +from .comparison_filter import ComparisonFilter as ComparisonFilter +from .function_definition import FunctionDefinition as FunctionDefinition +from .function_parameters import FunctionParameters as FunctionParameters +from .response_format_text import ResponseFormatText as ResponseFormatText +from .custom_tool_input_format import CustomToolInputFormat as CustomToolInputFormat +from .response_format_json_object import ResponseFormatJSONObject as ResponseFormatJSONObject +from .response_format_json_schema import ResponseFormatJSONSchema as ResponseFormatJSONSchema +from .response_format_text_python import ResponseFormatTextPython as ResponseFormatTextPython +from .response_format_text_grammar import ResponseFormatTextGrammar as ResponseFormatTextGrammar diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/all_models.py b/.venv/lib/python3.13/site-packages/openai/types/shared/all_models.py new file mode 100644 index 0000000000000000000000000000000000000000..76ca1ffd2950727c7cabe9779b663eaff6f6bce9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/all_models.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from .chat_model import ChatModel + +__all__ = ["AllModels"] + +AllModels: TypeAlias = Union[ + str, + ChatModel, + Literal[ + "o1-pro", + "o1-pro-2025-03-19", + "o3-pro", + "o3-pro-2025-06-10", + "o3-deep-research", + "o3-deep-research-2025-06-26", + "o4-mini-deep-research", + "o4-mini-deep-research-2025-06-26", + "computer-use-preview", + "computer-use-preview-2025-03-11", + "gpt-5-codex", + ], +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/chat_model.py b/.venv/lib/python3.13/site-packages/openai/types/shared/chat_model.py new file mode 100644 index 0000000000000000000000000000000000000000..727c60c1c02f924bc29dc3c28b853fbc120c076e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/chat_model.py @@ -0,0 +1,70 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ChatModel"] + +ChatModel: TypeAlias = Literal[ + "gpt-5", + "gpt-5-mini", + "gpt-5-nano", + "gpt-5-2025-08-07", + "gpt-5-mini-2025-08-07", + "gpt-5-nano-2025-08-07", + "gpt-5-chat-latest", + "gpt-4.1", + "gpt-4.1-mini", + "gpt-4.1-nano", + "gpt-4.1-2025-04-14", + "gpt-4.1-mini-2025-04-14", + "gpt-4.1-nano-2025-04-14", + "o4-mini", + "o4-mini-2025-04-16", + "o3", + "o3-2025-04-16", + "o3-mini", + "o3-mini-2025-01-31", + "o1", + "o1-2024-12-17", + "o1-preview", + "o1-preview-2024-09-12", + "o1-mini", + "o1-mini-2024-09-12", + "gpt-4o", + "gpt-4o-2024-11-20", + "gpt-4o-2024-08-06", + "gpt-4o-2024-05-13", + "gpt-4o-audio-preview", + "gpt-4o-audio-preview-2024-10-01", + "gpt-4o-audio-preview-2024-12-17", + "gpt-4o-audio-preview-2025-06-03", + "gpt-4o-mini-audio-preview", + "gpt-4o-mini-audio-preview-2024-12-17", + "gpt-4o-search-preview", + "gpt-4o-mini-search-preview", + "gpt-4o-search-preview-2025-03-11", + "gpt-4o-mini-search-preview-2025-03-11", + "chatgpt-4o-latest", + "codex-mini-latest", + "gpt-4o-mini", + "gpt-4o-mini-2024-07-18", + "gpt-4-turbo", + "gpt-4-turbo-2024-04-09", + "gpt-4-0125-preview", + "gpt-4-turbo-preview", + "gpt-4-1106-preview", + "gpt-4-vision-preview", + "gpt-4", + "gpt-4-0314", + "gpt-4-0613", + "gpt-4-32k", + "gpt-4-32k-0314", + "gpt-4-32k-0613", + "gpt-3.5-turbo", + "gpt-3.5-turbo-16k", + "gpt-3.5-turbo-0301", + "gpt-3.5-turbo-0613", + "gpt-3.5-turbo-1106", + "gpt-3.5-turbo-0125", + "gpt-3.5-turbo-16k-0613", +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/comparison_filter.py b/.venv/lib/python3.13/site-packages/openai/types/shared/comparison_filter.py new file mode 100644 index 0000000000000000000000000000000000000000..2ec2651ff2ba5da630b6fc8dc06f58983aac7da4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/comparison_filter.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ComparisonFilter"] + + +class ComparisonFilter(BaseModel): + key: str + """The key to compare against the value.""" + + type: Literal["eq", "ne", "gt", "gte", "lt", "lte"] + """Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + """ + + value: Union[str, float, bool] + """ + The value to compare against the attribute key; supports string, number, or + boolean types. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/compound_filter.py b/.venv/lib/python3.13/site-packages/openai/types/shared/compound_filter.py new file mode 100644 index 0000000000000000000000000000000000000000..3aefa43647f18723ea2ae903255b62bfec1f2f0f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/compound_filter.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Union +from typing_extensions import Literal, TypeAlias + +from ..._models import BaseModel +from .comparison_filter import ComparisonFilter + +__all__ = ["CompoundFilter", "Filter"] + +Filter: TypeAlias = Union[ComparisonFilter, object] + + +class CompoundFilter(BaseModel): + filters: List[Filter] + """Array of filters to combine. + + Items can be `ComparisonFilter` or `CompoundFilter`. + """ + + type: Literal["and", "or"] + """Type of operation: `and` or `or`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/custom_tool_input_format.py b/.venv/lib/python3.13/site-packages/openai/types/shared/custom_tool_input_format.py new file mode 100644 index 0000000000000000000000000000000000000000..53c8323ed2c0067de6b122b7de97f6bab05725a2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/custom_tool_input_format.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, Annotated, TypeAlias + +from ..._utils import PropertyInfo +from ..._models import BaseModel + +__all__ = ["CustomToolInputFormat", "Text", "Grammar"] + + +class Text(BaseModel): + type: Literal["text"] + """Unconstrained text format. Always `text`.""" + + +class Grammar(BaseModel): + definition: str + """The grammar definition.""" + + syntax: Literal["lark", "regex"] + """The syntax of the grammar definition. One of `lark` or `regex`.""" + + type: Literal["grammar"] + """Grammar format. Always `grammar`.""" + + +CustomToolInputFormat: TypeAlias = Annotated[Union[Text, Grammar], PropertyInfo(discriminator="type")] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/error_object.py b/.venv/lib/python3.13/site-packages/openai/types/shared/error_object.py new file mode 100644 index 0000000000000000000000000000000000000000..32d7045e006a37eb761dff818da642a6cf5d9a24 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/error_object.py @@ -0,0 +1,17 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["ErrorObject"] + + +class ErrorObject(BaseModel): + code: Optional[str] = None + + message: str + + param: Optional[str] = None + + type: str diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/function_definition.py b/.venv/lib/python3.13/site-packages/openai/types/shared/function_definition.py new file mode 100644 index 0000000000000000000000000000000000000000..33ebb9ad3e6c3300ad8c8bb88ac058919957f0e4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/function_definition.py @@ -0,0 +1,43 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel +from .function_parameters import FunctionParameters + +__all__ = ["FunctionDefinition"] + + +class FunctionDefinition(BaseModel): + name: str + """The name of the function to be called. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + description: Optional[str] = None + """ + A description of what the function does, used by the model to choose when and + how to call the function. + """ + + parameters: Optional[FunctionParameters] = None + """The parameters the functions accepts, described as a JSON Schema object. + + See the [guide](https://platform.openai.com/docs/guides/function-calling) for + examples, and the + [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for + documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + """ + + strict: Optional[bool] = None + """Whether to enable strict schema adherence when generating the function call. + + If set to true, the model will follow the exact schema defined in the + `parameters` field. Only a subset of JSON Schema is supported when `strict` is + `true`. Learn more about Structured Outputs in the + [function calling guide](https://platform.openai.com/docs/guides/function-calling). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/function_parameters.py b/.venv/lib/python3.13/site-packages/openai/types/shared/function_parameters.py new file mode 100644 index 0000000000000000000000000000000000000000..a3d83e3496f94ba1ff63ca2b1088ac48a64d07f2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/function_parameters.py @@ -0,0 +1,8 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict +from typing_extensions import TypeAlias + +__all__ = ["FunctionParameters"] + +FunctionParameters: TypeAlias = Dict[str, object] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/metadata.py b/.venv/lib/python3.13/site-packages/openai/types/shared/metadata.py new file mode 100644 index 0000000000000000000000000000000000000000..0da88c679c27f27642b9162a17780c8930cc3bdc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/metadata.py @@ -0,0 +1,8 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict +from typing_extensions import TypeAlias + +__all__ = ["Metadata"] + +Metadata: TypeAlias = Dict[str, str] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning.py b/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning.py new file mode 100644 index 0000000000000000000000000000000000000000..24ce3015264f48f0bbb5bb9589e47907526d20d2 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from .reasoning_effort import ReasoningEffort + +__all__ = ["Reasoning"] + + +class Reasoning(BaseModel): + effort: Optional[ReasoningEffort] = None + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + generate_summary: Optional[Literal["auto", "concise", "detailed"]] = None + """**Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be useful for + debugging and understanding the model's reasoning process. One of `auto`, + `concise`, or `detailed`. + """ + + summary: Optional[Literal["auto", "concise", "detailed"]] = None + """A summary of the reasoning performed by the model. + + This can be useful for debugging and understanding the model's reasoning + process. One of `auto`, `concise`, or `detailed`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning_effort.py b/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning_effort.py new file mode 100644 index 0000000000000000000000000000000000000000..4b960cd7e66912e7f0621355c4f034a9bb6c6f0e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/reasoning_effort.py @@ -0,0 +1,8 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal, TypeAlias + +__all__ = ["ReasoningEffort"] + +ReasoningEffort: TypeAlias = Optional[Literal["minimal", "low", "medium", "high"]] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_object.py b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_object.py new file mode 100644 index 0000000000000000000000000000000000000000..2aaa5dbdfe548aef9663e2b6e0481964d4436201 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_object.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFormatJSONObject"] + + +class ResponseFormatJSONObject(BaseModel): + type: Literal["json_object"] + """The type of response format being defined. Always `json_object`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_schema.py b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_schema.py new file mode 100644 index 0000000000000000000000000000000000000000..c7924446f4602303708fb4a10289bdc8a162f0b8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_json_schema.py @@ -0,0 +1,48 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Optional +from typing_extensions import Literal + +from pydantic import Field as FieldInfo + +from ..._models import BaseModel + +__all__ = ["ResponseFormatJSONSchema", "JSONSchema"] + + +class JSONSchema(BaseModel): + name: str + """The name of the response format. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + description: Optional[str] = None + """ + A description of what the response format is for, used by the model to determine + how to respond in the format. + """ + + schema_: Optional[Dict[str, object]] = FieldInfo(alias="schema", default=None) + """ + The schema for the response format, described as a JSON Schema object. Learn how + to build JSON schemas [here](https://json-schema.org/). + """ + + strict: Optional[bool] = None + """ + Whether to enable strict schema adherence when generating the output. If set to + true, the model will always follow the exact schema defined in the `schema` + field. Only a subset of JSON Schema is supported when `strict` is `true`. To + learn more, read the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + """ + + +class ResponseFormatJSONSchema(BaseModel): + json_schema: JSONSchema + """Structured Outputs configuration options, including a JSON Schema.""" + + type: Literal["json_schema"] + """The type of response format being defined. Always `json_schema`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text.py b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text.py new file mode 100644 index 0000000000000000000000000000000000000000..f0c8cfb7002ca8ae19e793116f285052d2ba2544 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFormatText"] + + +class ResponseFormatText(BaseModel): + type: Literal["text"] + """The type of response format being defined. Always `text`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_grammar.py b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_grammar.py new file mode 100644 index 0000000000000000000000000000000000000000..b02f99c1b8357083c58f30d202abf5c7808f58b5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_grammar.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFormatTextGrammar"] + + +class ResponseFormatTextGrammar(BaseModel): + grammar: str + """The custom grammar for the model to follow.""" + + type: Literal["grammar"] + """The type of response format being defined. Always `grammar`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_python.py b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_python.py new file mode 100644 index 0000000000000000000000000000000000000000..4cd18d46fa759e4bad3a93575b34b2371ad88f92 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/response_format_text_python.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFormatTextPython"] + + +class ResponseFormatTextPython(BaseModel): + type: Literal["python"] + """The type of response format being defined. Always `python`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared/responses_model.py b/.venv/lib/python3.13/site-packages/openai/types/shared/responses_model.py new file mode 100644 index 0000000000000000000000000000000000000000..4fbdce8db98585dcf0a89be1712903bd6d2690c8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared/responses_model.py @@ -0,0 +1,26 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from .chat_model import ChatModel + +__all__ = ["ResponsesModel"] + +ResponsesModel: TypeAlias = Union[ + str, + ChatModel, + Literal[ + "o1-pro", + "o1-pro-2025-03-19", + "o3-pro", + "o3-pro-2025-06-10", + "o3-deep-research", + "o3-deep-research-2025-06-26", + "o4-mini-deep-research", + "o4-mini-deep-research-2025-06-26", + "computer-use-preview", + "computer-use-preview-2025-03-11", + "gpt-5-codex", + ], +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..b6c0912b0f923f4aa04a6295004ca0824b6e2df0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/__init__.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .metadata import Metadata as Metadata +from .reasoning import Reasoning as Reasoning +from .chat_model import ChatModel as ChatModel +from .compound_filter import CompoundFilter as CompoundFilter +from .responses_model import ResponsesModel as ResponsesModel +from .reasoning_effort import ReasoningEffort as ReasoningEffort +from .comparison_filter import ComparisonFilter as ComparisonFilter +from .function_definition import FunctionDefinition as FunctionDefinition +from .function_parameters import FunctionParameters as FunctionParameters +from .response_format_text import ResponseFormatText as ResponseFormatText +from .custom_tool_input_format import CustomToolInputFormat as CustomToolInputFormat +from .response_format_json_object import ResponseFormatJSONObject as ResponseFormatJSONObject +from .response_format_json_schema import ResponseFormatJSONSchema as ResponseFormatJSONSchema diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/chat_model.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/chat_model.py new file mode 100644 index 0000000000000000000000000000000000000000..a1e5ab9f304e5e21dd004e2c06a5259cbdcd528a --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/chat_model.py @@ -0,0 +1,72 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypeAlias + +__all__ = ["ChatModel"] + +ChatModel: TypeAlias = Literal[ + "gpt-5", + "gpt-5-mini", + "gpt-5-nano", + "gpt-5-2025-08-07", + "gpt-5-mini-2025-08-07", + "gpt-5-nano-2025-08-07", + "gpt-5-chat-latest", + "gpt-4.1", + "gpt-4.1-mini", + "gpt-4.1-nano", + "gpt-4.1-2025-04-14", + "gpt-4.1-mini-2025-04-14", + "gpt-4.1-nano-2025-04-14", + "o4-mini", + "o4-mini-2025-04-16", + "o3", + "o3-2025-04-16", + "o3-mini", + "o3-mini-2025-01-31", + "o1", + "o1-2024-12-17", + "o1-preview", + "o1-preview-2024-09-12", + "o1-mini", + "o1-mini-2024-09-12", + "gpt-4o", + "gpt-4o-2024-11-20", + "gpt-4o-2024-08-06", + "gpt-4o-2024-05-13", + "gpt-4o-audio-preview", + "gpt-4o-audio-preview-2024-10-01", + "gpt-4o-audio-preview-2024-12-17", + "gpt-4o-audio-preview-2025-06-03", + "gpt-4o-mini-audio-preview", + "gpt-4o-mini-audio-preview-2024-12-17", + "gpt-4o-search-preview", + "gpt-4o-mini-search-preview", + "gpt-4o-search-preview-2025-03-11", + "gpt-4o-mini-search-preview-2025-03-11", + "chatgpt-4o-latest", + "codex-mini-latest", + "gpt-4o-mini", + "gpt-4o-mini-2024-07-18", + "gpt-4-turbo", + "gpt-4-turbo-2024-04-09", + "gpt-4-0125-preview", + "gpt-4-turbo-preview", + "gpt-4-1106-preview", + "gpt-4-vision-preview", + "gpt-4", + "gpt-4-0314", + "gpt-4-0613", + "gpt-4-32k", + "gpt-4-32k-0314", + "gpt-4-32k-0613", + "gpt-3.5-turbo", + "gpt-3.5-turbo-16k", + "gpt-3.5-turbo-0301", + "gpt-3.5-turbo-0613", + "gpt-3.5-turbo-1106", + "gpt-3.5-turbo-0125", + "gpt-3.5-turbo-16k-0613", +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/comparison_filter.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/comparison_filter.py new file mode 100644 index 0000000000000000000000000000000000000000..38edd315ed51de3479206a3a0f89788c928b2b81 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/comparison_filter.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ComparisonFilter"] + + +class ComparisonFilter(TypedDict, total=False): + key: Required[str] + """The key to compare against the value.""" + + type: Required[Literal["eq", "ne", "gt", "gte", "lt", "lte"]] + """Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`. + + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + """ + + value: Required[Union[str, float, bool]] + """ + The value to compare against the attribute key; supports string, number, or + boolean types. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/compound_filter.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/compound_filter.py new file mode 100644 index 0000000000000000000000000000000000000000..d12e9b1bda5863f4053360088da8907bb5ee05f5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/compound_filter.py @@ -0,0 +1,23 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union, Iterable +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .comparison_filter import ComparisonFilter + +__all__ = ["CompoundFilter", "Filter"] + +Filter: TypeAlias = Union[ComparisonFilter, object] + + +class CompoundFilter(TypedDict, total=False): + filters: Required[Iterable[Filter]] + """Array of filters to combine. + + Items can be `ComparisonFilter` or `CompoundFilter`. + """ + + type: Required[Literal["and", "or"]] + """Type of operation: `and` or `or`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/custom_tool_input_format.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/custom_tool_input_format.py new file mode 100644 index 0000000000000000000000000000000000000000..37df393e393864485aa724397051060b7daf3f03 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/custom_tool_input_format.py @@ -0,0 +1,27 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +__all__ = ["CustomToolInputFormat", "Text", "Grammar"] + + +class Text(TypedDict, total=False): + type: Required[Literal["text"]] + """Unconstrained text format. Always `text`.""" + + +class Grammar(TypedDict, total=False): + definition: Required[str] + """The grammar definition.""" + + syntax: Required[Literal["lark", "regex"]] + """The syntax of the grammar definition. One of `lark` or `regex`.""" + + type: Required[Literal["grammar"]] + """Grammar format. Always `grammar`.""" + + +CustomToolInputFormat: TypeAlias = Union[Text, Grammar] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_definition.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_definition.py new file mode 100644 index 0000000000000000000000000000000000000000..b3fdaf86ff0a83b3d2145cab583ae56a49bf1eb9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_definition.py @@ -0,0 +1,45 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Required, TypedDict + +from .function_parameters import FunctionParameters + +__all__ = ["FunctionDefinition"] + + +class FunctionDefinition(TypedDict, total=False): + name: Required[str] + """The name of the function to be called. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + description: str + """ + A description of what the function does, used by the model to choose when and + how to call the function. + """ + + parameters: FunctionParameters + """The parameters the functions accepts, described as a JSON Schema object. + + See the [guide](https://platform.openai.com/docs/guides/function-calling) for + examples, and the + [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for + documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + """ + + strict: Optional[bool] + """Whether to enable strict schema adherence when generating the function call. + + If set to true, the model will follow the exact schema defined in the + `parameters` field. Only a subset of JSON Schema is supported when `strict` is + `true`. Learn more about Structured Outputs in the + [function calling guide](https://platform.openai.com/docs/guides/function-calling). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_parameters.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_parameters.py new file mode 100644 index 0000000000000000000000000000000000000000..45fc742d3ba84a7ec508b1122fe106c23f484a78 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/function_parameters.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict +from typing_extensions import TypeAlias + +__all__ = ["FunctionParameters"] + +FunctionParameters: TypeAlias = Dict[str, object] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/metadata.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/metadata.py new file mode 100644 index 0000000000000000000000000000000000000000..821650b48b0210e86c02d8964bd5f7d427767c14 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/metadata.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict +from typing_extensions import TypeAlias + +__all__ = ["Metadata"] + +Metadata: TypeAlias = Dict[str, str] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning.py new file mode 100644 index 0000000000000000000000000000000000000000..7eab2c76f746a4824b13dd522eff0030a1d33c64 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, TypedDict + +from ..shared.reasoning_effort import ReasoningEffort + +__all__ = ["Reasoning"] + + +class Reasoning(TypedDict, total=False): + effort: Optional[ReasoningEffort] + """ + Constrains effort on reasoning for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently + supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning + effort can result in faster responses and fewer tokens used on reasoning in a + response. + """ + + generate_summary: Optional[Literal["auto", "concise", "detailed"]] + """**Deprecated:** use `summary` instead. + + A summary of the reasoning performed by the model. This can be useful for + debugging and understanding the model's reasoning process. One of `auto`, + `concise`, or `detailed`. + """ + + summary: Optional[Literal["auto", "concise", "detailed"]] + """A summary of the reasoning performed by the model. + + This can be useful for debugging and understanding the model's reasoning + process. One of `auto`, `concise`, or `detailed`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning_effort.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning_effort.py new file mode 100644 index 0000000000000000000000000000000000000000..4c095a28d7b2bf24628f9a9b156722f02b7e3eab --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/reasoning_effort.py @@ -0,0 +1,10 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, TypeAlias + +__all__ = ["ReasoningEffort"] + +ReasoningEffort: TypeAlias = Optional[Literal["minimal", "low", "medium", "high"]] diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_object.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_object.py new file mode 100644 index 0000000000000000000000000000000000000000..d4d1deaae57a8c891c5e48052fc2a903f72b6ad5 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_object.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseFormatJSONObject"] + + +class ResponseFormatJSONObject(TypedDict, total=False): + type: Required[Literal["json_object"]] + """The type of response format being defined. Always `json_object`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_schema.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_schema.py new file mode 100644 index 0000000000000000000000000000000000000000..5b0a13ee06a32351ce6039eb0d2d3a86fc639171 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_json_schema.py @@ -0,0 +1,46 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Optional +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseFormatJSONSchema", "JSONSchema"] + + +class JSONSchema(TypedDict, total=False): + name: Required[str] + """The name of the response format. + + Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length + of 64. + """ + + description: str + """ + A description of what the response format is for, used by the model to determine + how to respond in the format. + """ + + schema: Dict[str, object] + """ + The schema for the response format, described as a JSON Schema object. Learn how + to build JSON schemas [here](https://json-schema.org/). + """ + + strict: Optional[bool] + """ + Whether to enable strict schema adherence when generating the output. If set to + true, the model will always follow the exact schema defined in the `schema` + field. Only a subset of JSON Schema is supported when `strict` is `true`. To + learn more, read the + [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs). + """ + + +class ResponseFormatJSONSchema(TypedDict, total=False): + json_schema: Required[JSONSchema] + """Structured Outputs configuration options, including a JSON Schema.""" + + type: Required[Literal["json_schema"]] + """The type of response format being defined. Always `json_schema`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_text.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_text.py new file mode 100644 index 0000000000000000000000000000000000000000..c3ef2b0816e12ac263e041e4bc16a02073be8fb1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/response_format_text.py @@ -0,0 +1,12 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["ResponseFormatText"] + + +class ResponseFormatText(TypedDict, total=False): + type: Required[Literal["text"]] + """The type of response format being defined. Always `text`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/shared_params/responses_model.py b/.venv/lib/python3.13/site-packages/openai/types/shared_params/responses_model.py new file mode 100644 index 0000000000000000000000000000000000000000..2feaa22b6752862e3798d504df46dda7e7750fd9 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/shared_params/responses_model.py @@ -0,0 +1,28 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, TypeAlias + +from ..shared.chat_model import ChatModel + +__all__ = ["ResponsesModel"] + +ResponsesModel: TypeAlias = Union[ + str, + ChatModel, + Literal[ + "o1-pro", + "o1-pro-2025-03-19", + "o3-pro", + "o3-pro-2025-06-10", + "o3-deep-research", + "o3-deep-research-2025-06-26", + "o4-mini-deep-research", + "o4-mini-deep-research-2025-06-26", + "computer-use-preview", + "computer-use-preview-2025-03-11", + "gpt-5-codex", + ], +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy.py b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy.py new file mode 100644 index 0000000000000000000000000000000000000000..cb842442c1f1a7dde8d6db54c97afbf5bb4cffbc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from .._models import BaseModel + +__all__ = ["StaticFileChunkingStrategy"] + + +class StaticFileChunkingStrategy(BaseModel): + chunk_overlap_tokens: int + """The number of tokens that overlap between chunks. The default value is `400`. + + Note that the overlap must not exceed half of `max_chunk_size_tokens`. + """ + + max_chunk_size_tokens: int + """The maximum number of tokens in each chunk. + + The default value is `800`. The minimum value is `100` and the maximum value is + `4096`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object.py b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object.py new file mode 100644 index 0000000000000000000000000000000000000000..2a95dce5b369be7195160272a94e7dd5660d640e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel +from .static_file_chunking_strategy import StaticFileChunkingStrategy + +__all__ = ["StaticFileChunkingStrategyObject"] + + +class StaticFileChunkingStrategyObject(BaseModel): + static: StaticFileChunkingStrategy + + type: Literal["static"] + """Always `static`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object_param.py b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object_param.py new file mode 100644 index 0000000000000000000000000000000000000000..0cdf35c0df3470fc56682bd032fb4a0457e4ae19 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_object_param.py @@ -0,0 +1,16 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .static_file_chunking_strategy_param import StaticFileChunkingStrategyParam + +__all__ = ["StaticFileChunkingStrategyObjectParam"] + + +class StaticFileChunkingStrategyObjectParam(TypedDict, total=False): + static: Required[StaticFileChunkingStrategyParam] + + type: Required[Literal["static"]] + """Always `static`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_param.py b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_param.py new file mode 100644 index 0000000000000000000000000000000000000000..f917ac56470cff3fa22929082358a5e958062339 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/static_file_chunking_strategy_param.py @@ -0,0 +1,22 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +__all__ = ["StaticFileChunkingStrategyParam"] + + +class StaticFileChunkingStrategyParam(TypedDict, total=False): + chunk_overlap_tokens: Required[int] + """The number of tokens that overlap between chunks. The default value is `400`. + + Note that the overlap must not exceed half of `max_chunk_size_tokens`. + """ + + max_chunk_size_tokens: Required[int] + """The maximum number of tokens in each chunk. + + The default value is `800`. The minimum value is `100` and the maximum value is + `4096`. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/upload.py b/.venv/lib/python3.13/site-packages/openai/types/upload.py new file mode 100644 index 0000000000000000000000000000000000000000..914b69a8632779ef85ea9660635ad660ac677b21 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/upload.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from .._models import BaseModel +from .file_object import FileObject + +__all__ = ["Upload"] + + +class Upload(BaseModel): + id: str + """The Upload unique identifier, which can be referenced in API endpoints.""" + + bytes: int + """The intended number of bytes to be uploaded.""" + + created_at: int + """The Unix timestamp (in seconds) for when the Upload was created.""" + + expires_at: int + """The Unix timestamp (in seconds) for when the Upload will expire.""" + + filename: str + """The name of the file to be uploaded.""" + + object: Literal["upload"] + """The object type, which is always "upload".""" + + purpose: str + """The intended purpose of the file. + + [Please refer here](https://platform.openai.com/docs/api-reference/files/object#files/object-purpose) + for acceptable values. + """ + + status: Literal["pending", "completed", "cancelled", "expired"] + """The status of the Upload.""" + + file: Optional[FileObject] = None + """The `File` object represents a document that has been uploaded to OpenAI.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/upload_complete_params.py b/.venv/lib/python3.13/site-packages/openai/types/upload_complete_params.py new file mode 100644 index 0000000000000000000000000000000000000000..846a241dc7b5003bf2ae896be34fb107ca53d9de --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/upload_complete_params.py @@ -0,0 +1,20 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +from .._types import SequenceNotStr + +__all__ = ["UploadCompleteParams"] + + +class UploadCompleteParams(TypedDict, total=False): + part_ids: Required[SequenceNotStr[str]] + """The ordered list of Part IDs.""" + + md5: str + """ + The optional md5 checksum for the file contents to verify if the bytes uploaded + matches what you expect. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/upload_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/upload_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..ab4cded81d473578b72b236875ad7f7164026f3f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/upload_create_params.py @@ -0,0 +1,52 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +from .file_purpose import FilePurpose + +__all__ = ["UploadCreateParams", "ExpiresAfter"] + + +class UploadCreateParams(TypedDict, total=False): + bytes: Required[int] + """The number of bytes in the file you are uploading.""" + + filename: Required[str] + """The name of the file to upload.""" + + mime_type: Required[str] + """The MIME type of the file. + + This must fall within the supported MIME types for your file purpose. See the + supported MIME types for assistants and vision. + """ + + purpose: Required[FilePurpose] + """The intended purpose of the uploaded file. + + See the + [documentation on File purposes](https://platform.openai.com/docs/api-reference/files/create#files-create-purpose). + """ + + expires_after: ExpiresAfter + """The expiration policy for a file. + + By default, files with `purpose=batch` expire after 30 days and all other files + are persisted until they are manually deleted. + """ + + +class ExpiresAfter(TypedDict, total=False): + anchor: Required[Literal["created_at"]] + """Anchor timestamp after which the expiration policy applies. + + Supported anchors: `created_at`. + """ + + seconds: Required[int] + """The number of seconds after the anchor time that the file will expire. + + Must be between 3600 (1 hour) and 2592000 (30 days). + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/uploads/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/uploads/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..41deb0ab4bf9c1987cbe67c34b010f30902dea4d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/uploads/__init__.py @@ -0,0 +1,6 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .upload_part import UploadPart as UploadPart +from .part_create_params import PartCreateParams as PartCreateParams diff --git a/.venv/lib/python3.13/site-packages/openai/types/uploads/part_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/uploads/part_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..9851ca41e96ae6019038c7ce9e26c6cc13d1e84e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/uploads/part_create_params.py @@ -0,0 +1,14 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Required, TypedDict + +from ..._types import FileTypes + +__all__ = ["PartCreateParams"] + + +class PartCreateParams(TypedDict, total=False): + data: Required[FileTypes] + """The chunk of bytes for this Part.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/uploads/upload_part.py b/.venv/lib/python3.13/site-packages/openai/types/uploads/upload_part.py new file mode 100644 index 0000000000000000000000000000000000000000..e09621d8f93536a7d8ea66b26d0e1bf0bb873646 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/uploads/upload_part.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["UploadPart"] + + +class UploadPart(BaseModel): + id: str + """The upload Part unique identifier, which can be referenced in API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the Part was created.""" + + object: Literal["upload.part"] + """The object type, which is always `upload.part`.""" + + upload_id: str + """The ID of the Upload object that this Part was added to.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store.py new file mode 100644 index 0000000000000000000000000000000000000000..2473a442d229211186e12a8e09ee30d120220f9f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store.py @@ -0,0 +1,82 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from .._models import BaseModel +from .shared.metadata import Metadata + +__all__ = ["VectorStore", "FileCounts", "ExpiresAfter"] + + +class FileCounts(BaseModel): + cancelled: int + """The number of files that were cancelled.""" + + completed: int + """The number of files that have been successfully processed.""" + + failed: int + """The number of files that have failed to process.""" + + in_progress: int + """The number of files that are currently being processed.""" + + total: int + """The total number of files.""" + + +class ExpiresAfter(BaseModel): + anchor: Literal["last_active_at"] + """Anchor timestamp after which the expiration policy applies. + + Supported anchors: `last_active_at`. + """ + + days: int + """The number of days after the anchor time that the vector store will expire.""" + + +class VectorStore(BaseModel): + id: str + """The identifier, which can be referenced in API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the vector store was created.""" + + file_counts: FileCounts + + last_active_at: Optional[int] = None + """The Unix timestamp (in seconds) for when the vector store was last active.""" + + metadata: Optional[Metadata] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the vector store.""" + + object: Literal["vector_store"] + """The object type, which is always `vector_store`.""" + + status: Literal["expired", "in_progress", "completed"] + """ + The status of the vector store, which can be either `expired`, `in_progress`, or + `completed`. A status of `completed` indicates that the vector store is ready + for use. + """ + + usage_bytes: int + """The total number of bytes used by the files in the vector store.""" + + expires_after: Optional[ExpiresAfter] = None + """The expiration policy for a vector store.""" + + expires_at: Optional[int] = None + """The Unix timestamp (in seconds) for when the vector store will expire.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..945a9886a348c0a264e18e05374c72f221425104 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_create_params.py @@ -0,0 +1,55 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +from .._types import SequenceNotStr +from .shared_params.metadata import Metadata +from .file_chunking_strategy_param import FileChunkingStrategyParam + +__all__ = ["VectorStoreCreateParams", "ExpiresAfter"] + + +class VectorStoreCreateParams(TypedDict, total=False): + chunking_strategy: FileChunkingStrategyParam + """The chunking strategy used to chunk the file(s). + + If not set, will use the `auto` strategy. Only applicable if `file_ids` is + non-empty. + """ + + expires_after: ExpiresAfter + """The expiration policy for a vector store.""" + + file_ids: SequenceNotStr[str] + """ + A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that + the vector store should use. Useful for tools like `file_search` that can access + files. + """ + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: str + """The name of the vector store.""" + + +class ExpiresAfter(TypedDict, total=False): + anchor: Required[Literal["last_active_at"]] + """Anchor timestamp after which the expiration policy applies. + + Supported anchors: `last_active_at`. + """ + + days: Required[int] + """The number of days after the anchor time that the vector store will expire.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_deleted.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_deleted.py new file mode 100644 index 0000000000000000000000000000000000000000..dfac9ce8bdfb5c93b7a3b2046437dd327759474e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_deleted.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["VectorStoreDeleted"] + + +class VectorStoreDeleted(BaseModel): + id: str + + deleted: bool + + object: Literal["vector_store.deleted"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..e26ff90a85b7d8c7c98ecb50b19e86622e3e29f0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_list_params.py @@ -0,0 +1,39 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["VectorStoreListParams"] + + +class VectorStoreListParams(TypedDict, total=False): + after: str + """A cursor for use in pagination. + + `after` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, ending with obj_foo, your + subsequent call can include after=obj_foo in order to fetch the next page of the + list. + """ + + before: str + """A cursor for use in pagination. + + `before` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the previous page + of the list. + """ + + limit: int + """A limit on the number of objects to be returned. + + Limit can range between 1 and 100, and the default is 20. + """ + + order: Literal["asc", "desc"] + """Sort order by the `created_at` timestamp of the objects. + + `asc` for ascending order and `desc` for descending order. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_params.py new file mode 100644 index 0000000000000000000000000000000000000000..8b7b13c4a18451fb4804b2d7f216991c730e9faf --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_params.py @@ -0,0 +1,42 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Union +from typing_extensions import Literal, Required, TypeAlias, TypedDict + +from .._types import SequenceNotStr +from .shared_params.compound_filter import CompoundFilter +from .shared_params.comparison_filter import ComparisonFilter + +__all__ = ["VectorStoreSearchParams", "Filters", "RankingOptions"] + + +class VectorStoreSearchParams(TypedDict, total=False): + query: Required[Union[str, SequenceNotStr[str]]] + """A query string for a search""" + + filters: Filters + """A filter to apply based on file attributes.""" + + max_num_results: int + """The maximum number of results to return. + + This number should be between 1 and 50 inclusive. + """ + + ranking_options: RankingOptions + """Ranking options for search.""" + + rewrite_query: bool + """Whether to rewrite the natural language query for vector search.""" + + +Filters: TypeAlias = Union[ComparisonFilter, CompoundFilter] + + +class RankingOptions(TypedDict, total=False): + ranker: Literal["none", "auto", "default-2024-11-15"] + """Enable re-ranking; set to `none` to disable, which can help reduce latency.""" + + score_threshold: float diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_response.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_response.py new file mode 100644 index 0000000000000000000000000000000000000000..d78b71bfba907fb570dd279456d285bd431d0661 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_search_response.py @@ -0,0 +1,39 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, List, Union, Optional +from typing_extensions import Literal + +from .._models import BaseModel + +__all__ = ["VectorStoreSearchResponse", "Content"] + + +class Content(BaseModel): + text: str + """The text content returned from search.""" + + type: Literal["text"] + """The type of content.""" + + +class VectorStoreSearchResponse(BaseModel): + attributes: Optional[Dict[str, Union[str, float, bool]]] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + content: List[Content] + """Content chunks from the file.""" + + file_id: str + """The ID of the vector store file.""" + + filename: str + """The name of the vector store file.""" + + score: float + """The similarity score for the result.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_store_update_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_store_update_params.py new file mode 100644 index 0000000000000000000000000000000000000000..4f6ac639638c1a066415944d78687e50c972458c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_store_update_params.py @@ -0,0 +1,39 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Optional +from typing_extensions import Literal, Required, TypedDict + +from .shared_params.metadata import Metadata + +__all__ = ["VectorStoreUpdateParams", "ExpiresAfter"] + + +class VectorStoreUpdateParams(TypedDict, total=False): + expires_after: Optional[ExpiresAfter] + """The expiration policy for a vector store.""" + + metadata: Optional[Metadata] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. + + Keys are strings with a maximum length of 64 characters. Values are strings with + a maximum length of 512 characters. + """ + + name: Optional[str] + """The name of the vector store.""" + + +class ExpiresAfter(TypedDict, total=False): + anchor: Required[Literal["last_active_at"]] + """Anchor timestamp after which the expiration policy applies. + + Supported anchors: `last_active_at`. + """ + + days: Required[int] + """The number of days after the anchor time that the vector store will expire.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..96ce301481563e2ee8e8b8f5d836f8b6b2e795e1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/__init__.py @@ -0,0 +1,13 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .file_list_params import FileListParams as FileListParams +from .vector_store_file import VectorStoreFile as VectorStoreFile +from .file_create_params import FileCreateParams as FileCreateParams +from .file_update_params import FileUpdateParams as FileUpdateParams +from .file_content_response import FileContentResponse as FileContentResponse +from .vector_store_file_batch import VectorStoreFileBatch as VectorStoreFileBatch +from .file_batch_create_params import FileBatchCreateParams as FileBatchCreateParams +from .vector_store_file_deleted import VectorStoreFileDeleted as VectorStoreFileDeleted +from .file_batch_list_files_params import FileBatchListFilesParams as FileBatchListFilesParams diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..d8d7b448885baad4eb62241f8844adc8a3a08939 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_create_params.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Required, TypedDict + +from ..._types import SequenceNotStr +from ..file_chunking_strategy_param import FileChunkingStrategyParam + +__all__ = ["FileBatchCreateParams"] + + +class FileBatchCreateParams(TypedDict, total=False): + file_ids: Required[SequenceNotStr[str]] + """ + A list of [File](https://platform.openai.com/docs/api-reference/files) IDs that + the vector store should use. Useful for tools like `file_search` that can access + files. + """ + + attributes: Optional[Dict[str, Union[str, float, bool]]] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + chunking_strategy: FileChunkingStrategyParam + """The chunking strategy used to chunk the file(s). + + If not set, will use the `auto` strategy. Only applicable if `file_ids` is + non-empty. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_list_files_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_list_files_params.py new file mode 100644 index 0000000000000000000000000000000000000000..2a0a6c6aa74bf301c4bbaed44a0bffab017f05d7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_batch_list_files_params.py @@ -0,0 +1,47 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, Required, TypedDict + +__all__ = ["FileBatchListFilesParams"] + + +class FileBatchListFilesParams(TypedDict, total=False): + vector_store_id: Required[str] + + after: str + """A cursor for use in pagination. + + `after` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, ending with obj_foo, your + subsequent call can include after=obj_foo in order to fetch the next page of the + list. + """ + + before: str + """A cursor for use in pagination. + + `before` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the previous page + of the list. + """ + + filter: Literal["in_progress", "completed", "failed", "cancelled"] + """Filter by file status. + + One of `in_progress`, `completed`, `failed`, `cancelled`. + """ + + limit: int + """A limit on the number of objects to be returned. + + Limit can range between 1 and 100, and the default is 20. + """ + + order: Literal["asc", "desc"] + """Sort order by the `created_at` timestamp of the objects. + + `asc` for ascending order and `desc` for descending order. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_content_response.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_content_response.py new file mode 100644 index 0000000000000000000000000000000000000000..32db2f2ce92229bdf92c698c854cd6424c45ebc7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_content_response.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional + +from ..._models import BaseModel + +__all__ = ["FileContentResponse"] + + +class FileContentResponse(BaseModel): + text: Optional[str] = None + """The text content""" + + type: Optional[str] = None + """The content type (currently only `"text"`)""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_create_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_create_params.py new file mode 100644 index 0000000000000000000000000000000000000000..5b8989251a0d96ddf647b6f15e45f688041d462f --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_create_params.py @@ -0,0 +1,35 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Required, TypedDict + +from ..file_chunking_strategy_param import FileChunkingStrategyParam + +__all__ = ["FileCreateParams"] + + +class FileCreateParams(TypedDict, total=False): + file_id: Required[str] + """ + A [File](https://platform.openai.com/docs/api-reference/files) ID that the + vector store should use. Useful for tools like `file_search` that can access + files. + """ + + attributes: Optional[Dict[str, Union[str, float, bool]]] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + chunking_strategy: FileChunkingStrategyParam + """The chunking strategy used to chunk the file(s). + + If not set, will use the `auto` strategy. Only applicable if `file_ids` is + non-empty. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_list_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_list_params.py new file mode 100644 index 0000000000000000000000000000000000000000..867b5fb3bbc2f9d14a7a62116166ddb0cc6d00e7 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_list_params.py @@ -0,0 +1,45 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing_extensions import Literal, TypedDict + +__all__ = ["FileListParams"] + + +class FileListParams(TypedDict, total=False): + after: str + """A cursor for use in pagination. + + `after` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, ending with obj_foo, your + subsequent call can include after=obj_foo in order to fetch the next page of the + list. + """ + + before: str + """A cursor for use in pagination. + + `before` is an object ID that defines your place in the list. For instance, if + you make a list request and receive 100 objects, starting with obj_foo, your + subsequent call can include before=obj_foo in order to fetch the previous page + of the list. + """ + + filter: Literal["in_progress", "completed", "failed", "cancelled"] + """Filter by file status. + + One of `in_progress`, `completed`, `failed`, `cancelled`. + """ + + limit: int + """A limit on the number of objects to be returned. + + Limit can range between 1 and 100, and the default is 20. + """ + + order: Literal["asc", "desc"] + """Sort order by the `created_at` timestamp of the objects. + + `asc` for ascending order and `desc` for descending order. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_update_params.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_update_params.py new file mode 100644 index 0000000000000000000000000000000000000000..ebf540d046b3f666cc404fafa35d3fe5aac570c8 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/file_update_params.py @@ -0,0 +1,21 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import Dict, Union, Optional +from typing_extensions import Required, TypedDict + +__all__ = ["FileUpdateParams"] + + +class FileUpdateParams(TypedDict, total=False): + vector_store_id: Required[str] + + attributes: Required[Optional[Dict[str, Union[str, float, bool]]]] + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file.py new file mode 100644 index 0000000000000000000000000000000000000000..b59a61dfb02c3855bf8f3e403d8aec087d46c437 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file.py @@ -0,0 +1,67 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Dict, Union, Optional +from typing_extensions import Literal + +from ..._models import BaseModel +from ..file_chunking_strategy import FileChunkingStrategy + +__all__ = ["VectorStoreFile", "LastError"] + + +class LastError(BaseModel): + code: Literal["server_error", "unsupported_file", "invalid_file"] + """One of `server_error` or `rate_limit_exceeded`.""" + + message: str + """A human-readable description of the error.""" + + +class VectorStoreFile(BaseModel): + id: str + """The identifier, which can be referenced in API endpoints.""" + + created_at: int + """The Unix timestamp (in seconds) for when the vector store file was created.""" + + last_error: Optional[LastError] = None + """The last error associated with this vector store file. + + Will be `null` if there are no errors. + """ + + object: Literal["vector_store.file"] + """The object type, which is always `vector_store.file`.""" + + status: Literal["in_progress", "completed", "cancelled", "failed"] + """ + The status of the vector store file, which can be either `in_progress`, + `completed`, `cancelled`, or `failed`. The status `completed` indicates that the + vector store file is ready for use. + """ + + usage_bytes: int + """The total vector store usage in bytes. + + Note that this may be different from the original file size. + """ + + vector_store_id: str + """ + The ID of the + [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) + that the [File](https://platform.openai.com/docs/api-reference/files) is + attached to. + """ + + attributes: Optional[Dict[str, Union[str, float, bool]]] = None + """Set of 16 key-value pairs that can be attached to an object. + + This can be useful for storing additional information about the object in a + structured format, and querying for objects via API or the dashboard. Keys are + strings with a maximum length of 64 characters. Values are strings with a + maximum length of 512 characters, booleans, or numbers. + """ + + chunking_strategy: Optional[FileChunkingStrategy] = None + """The strategy used to chunk the file.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_batch.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_batch.py new file mode 100644 index 0000000000000000000000000000000000000000..57dbfbd809d9f1dce9c0d6ca976073ffff57590e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_batch.py @@ -0,0 +1,54 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["VectorStoreFileBatch", "FileCounts"] + + +class FileCounts(BaseModel): + cancelled: int + """The number of files that where cancelled.""" + + completed: int + """The number of files that have been processed.""" + + failed: int + """The number of files that have failed to process.""" + + in_progress: int + """The number of files that are currently being processed.""" + + total: int + """The total number of files.""" + + +class VectorStoreFileBatch(BaseModel): + id: str + """The identifier, which can be referenced in API endpoints.""" + + created_at: int + """ + The Unix timestamp (in seconds) for when the vector store files batch was + created. + """ + + file_counts: FileCounts + + object: Literal["vector_store.files_batch"] + """The object type, which is always `vector_store.file_batch`.""" + + status: Literal["in_progress", "completed", "cancelled", "failed"] + """ + The status of the vector store files batch, which can be either `in_progress`, + `completed`, `cancelled` or `failed`. + """ + + vector_store_id: str + """ + The ID of the + [vector store](https://platform.openai.com/docs/api-reference/vector-stores/object) + that the [File](https://platform.openai.com/docs/api-reference/files) is + attached to. + """ diff --git a/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_deleted.py b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_deleted.py new file mode 100644 index 0000000000000000000000000000000000000000..5c856f26cd4e10b70de23219a23cfe4006e5d33b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/vector_stores/vector_store_file_deleted.py @@ -0,0 +1,15 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["VectorStoreFileDeleted"] + + +class VectorStoreFileDeleted(BaseModel): + id: str + + deleted: bool + + object: Literal["vector_store.file.deleted"] diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/__init__.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..8b9e55653be6e842910741d515247ceabe6a35a0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/__init__.py @@ -0,0 +1,24 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from .unwrap_webhook_event import UnwrapWebhookEvent as UnwrapWebhookEvent +from .batch_failed_webhook_event import BatchFailedWebhookEvent as BatchFailedWebhookEvent +from .batch_expired_webhook_event import BatchExpiredWebhookEvent as BatchExpiredWebhookEvent +from .batch_cancelled_webhook_event import BatchCancelledWebhookEvent as BatchCancelledWebhookEvent +from .batch_completed_webhook_event import BatchCompletedWebhookEvent as BatchCompletedWebhookEvent +from .eval_run_failed_webhook_event import EvalRunFailedWebhookEvent as EvalRunFailedWebhookEvent +from .response_failed_webhook_event import ResponseFailedWebhookEvent as ResponseFailedWebhookEvent +from .eval_run_canceled_webhook_event import EvalRunCanceledWebhookEvent as EvalRunCanceledWebhookEvent +from .eval_run_succeeded_webhook_event import EvalRunSucceededWebhookEvent as EvalRunSucceededWebhookEvent +from .response_cancelled_webhook_event import ResponseCancelledWebhookEvent as ResponseCancelledWebhookEvent +from .response_completed_webhook_event import ResponseCompletedWebhookEvent as ResponseCompletedWebhookEvent +from .response_incomplete_webhook_event import ResponseIncompleteWebhookEvent as ResponseIncompleteWebhookEvent +from .fine_tuning_job_failed_webhook_event import FineTuningJobFailedWebhookEvent as FineTuningJobFailedWebhookEvent +from .realtime_call_incoming_webhook_event import RealtimeCallIncomingWebhookEvent as RealtimeCallIncomingWebhookEvent +from .fine_tuning_job_cancelled_webhook_event import ( + FineTuningJobCancelledWebhookEvent as FineTuningJobCancelledWebhookEvent, +) +from .fine_tuning_job_succeeded_webhook_event import ( + FineTuningJobSucceededWebhookEvent as FineTuningJobSucceededWebhookEvent, +) diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_cancelled_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_cancelled_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..4bbd7307a542a86d33a2d8ccee257ffc44ad6557 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_cancelled_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["BatchCancelledWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the batch API request.""" + + +class BatchCancelledWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the batch API request was cancelled.""" + + data: Data + """Event data payload.""" + + type: Literal["batch.cancelled"] + """The type of the event. Always `batch.cancelled`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_completed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_completed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..a47ca156fa1d0f7f5ea25d9f9d06248b591638b6 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_completed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["BatchCompletedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the batch API request.""" + + +class BatchCompletedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the batch API request was completed.""" + + data: Data + """Event data payload.""" + + type: Literal["batch.completed"] + """The type of the event. Always `batch.completed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_expired_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_expired_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..e91001e8d8a80ac8205cbb854b124ac1d11ca945 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_expired_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["BatchExpiredWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the batch API request.""" + + +class BatchExpiredWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the batch API request expired.""" + + data: Data + """Event data payload.""" + + type: Literal["batch.expired"] + """The type of the event. Always `batch.expired`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_failed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_failed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..ef80863edb94427c394eee3a1a2e7440a6d75842 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/batch_failed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["BatchFailedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the batch API request.""" + + +class BatchFailedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the batch API request failed.""" + + data: Data + """Event data payload.""" + + type: Literal["batch.failed"] + """The type of the event. Always `batch.failed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_canceled_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_canceled_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..855359f743ea24affce8db05bde7e288c26eaa8b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_canceled_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["EvalRunCanceledWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the eval run.""" + + +class EvalRunCanceledWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the eval run was canceled.""" + + data: Data + """Event data payload.""" + + type: Literal["eval.run.canceled"] + """The type of the event. Always `eval.run.canceled`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_failed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_failed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..7671680720695745b4d70fcae4e950a2f9e2f03e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_failed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["EvalRunFailedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the eval run.""" + + +class EvalRunFailedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the eval run failed.""" + + data: Data + """Event data payload.""" + + type: Literal["eval.run.failed"] + """The type of the event. Always `eval.run.failed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_succeeded_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_succeeded_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..d0d1fc2b04621852033aa97b1112d350573baf51 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/eval_run_succeeded_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["EvalRunSucceededWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the eval run.""" + + +class EvalRunSucceededWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the eval run succeeded.""" + + data: Data + """Event data payload.""" + + type: Literal["eval.run.succeeded"] + """The type of the event. Always `eval.run.succeeded`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_cancelled_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_cancelled_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..1fe3c06096d4e78dbf718f832d3e1d1d358ad622 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_cancelled_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["FineTuningJobCancelledWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the fine-tuning job.""" + + +class FineTuningJobCancelledWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the fine-tuning job was cancelled.""" + + data: Data + """Event data payload.""" + + type: Literal["fine_tuning.job.cancelled"] + """The type of the event. Always `fine_tuning.job.cancelled`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_failed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_failed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..71d899c8ef671a138b4cb7a78fca1a857edb7ae4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_failed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["FineTuningJobFailedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the fine-tuning job.""" + + +class FineTuningJobFailedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the fine-tuning job failed.""" + + data: Data + """Event data payload.""" + + type: Literal["fine_tuning.job.failed"] + """The type of the event. Always `fine_tuning.job.failed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_succeeded_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_succeeded_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..470f1fcfaa34f346c07a9e6b081ba03a0d7f6ae0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/fine_tuning_job_succeeded_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["FineTuningJobSucceededWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the fine-tuning job.""" + + +class FineTuningJobSucceededWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the fine-tuning job succeeded.""" + + data: Data + """Event data payload.""" + + type: Literal["fine_tuning.job.succeeded"] + """The type of the event. Always `fine_tuning.job.succeeded`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/realtime_call_incoming_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/realtime_call_incoming_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..a166a3471bc01605f78292092e530b3223cd5640 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/realtime_call_incoming_webhook_event.py @@ -0,0 +1,41 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import List, Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["RealtimeCallIncomingWebhookEvent", "Data", "DataSipHeader"] + + +class DataSipHeader(BaseModel): + name: str + """Name of the SIP Header.""" + + value: str + """Value of the SIP Header.""" + + +class Data(BaseModel): + call_id: str + """The unique ID of this call.""" + + sip_headers: List[DataSipHeader] + """Headers from the SIP Invite.""" + + +class RealtimeCallIncomingWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the model response was completed.""" + + data: Data + """Event data payload.""" + + type: Literal["realtime.call.incoming"] + """The type of the event. Always `realtime.call.incoming`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_cancelled_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_cancelled_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..443e360e9096138166fe39234ff95844a5237730 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_cancelled_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCancelledWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the model response.""" + + +class ResponseCancelledWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the model response was cancelled.""" + + data: Data + """Event data payload.""" + + type: Literal["response.cancelled"] + """The type of the event. Always `response.cancelled`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_completed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_completed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..ac1feff32b79b435e9b3b42e01f18a21fda27dbb --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_completed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseCompletedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the model response.""" + + +class ResponseCompletedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the model response was completed.""" + + data: Data + """Event data payload.""" + + type: Literal["response.completed"] + """The type of the event. Always `response.completed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_failed_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_failed_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..5b4ba65e187efe9f1731e53d447bfc2686930951 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_failed_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseFailedWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the model response.""" + + +class ResponseFailedWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the model response failed.""" + + data: Data + """Event data payload.""" + + type: Literal["response.failed"] + """The type of the event. Always `response.failed`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_incomplete_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_incomplete_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..01609314e091f01c6e5457a42d5b0ebf09aa62ae --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/response_incomplete_webhook_event.py @@ -0,0 +1,30 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Optional +from typing_extensions import Literal + +from ..._models import BaseModel + +__all__ = ["ResponseIncompleteWebhookEvent", "Data"] + + +class Data(BaseModel): + id: str + """The unique ID of the model response.""" + + +class ResponseIncompleteWebhookEvent(BaseModel): + id: str + """The unique ID of the event.""" + + created_at: int + """The Unix timestamp (in seconds) of when the model response was interrupted.""" + + data: Data + """Event data payload.""" + + type: Literal["response.incomplete"] + """The type of the event. Always `response.incomplete`.""" + + object: Optional[Literal["event"]] = None + """The object of the event. Always `event`.""" diff --git a/.venv/lib/python3.13/site-packages/openai/types/webhooks/unwrap_webhook_event.py b/.venv/lib/python3.13/site-packages/openai/types/webhooks/unwrap_webhook_event.py new file mode 100644 index 0000000000000000000000000000000000000000..952383c04921c4a91ed3d9e440f683c91bb6d367 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/webhooks/unwrap_webhook_event.py @@ -0,0 +1,44 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from typing import Union +from typing_extensions import Annotated, TypeAlias + +from ..._utils import PropertyInfo +from .batch_failed_webhook_event import BatchFailedWebhookEvent +from .batch_expired_webhook_event import BatchExpiredWebhookEvent +from .batch_cancelled_webhook_event import BatchCancelledWebhookEvent +from .batch_completed_webhook_event import BatchCompletedWebhookEvent +from .eval_run_failed_webhook_event import EvalRunFailedWebhookEvent +from .response_failed_webhook_event import ResponseFailedWebhookEvent +from .eval_run_canceled_webhook_event import EvalRunCanceledWebhookEvent +from .eval_run_succeeded_webhook_event import EvalRunSucceededWebhookEvent +from .response_cancelled_webhook_event import ResponseCancelledWebhookEvent +from .response_completed_webhook_event import ResponseCompletedWebhookEvent +from .response_incomplete_webhook_event import ResponseIncompleteWebhookEvent +from .fine_tuning_job_failed_webhook_event import FineTuningJobFailedWebhookEvent +from .realtime_call_incoming_webhook_event import RealtimeCallIncomingWebhookEvent +from .fine_tuning_job_cancelled_webhook_event import FineTuningJobCancelledWebhookEvent +from .fine_tuning_job_succeeded_webhook_event import FineTuningJobSucceededWebhookEvent + +__all__ = ["UnwrapWebhookEvent"] + +UnwrapWebhookEvent: TypeAlias = Annotated[ + Union[ + BatchCancelledWebhookEvent, + BatchCompletedWebhookEvent, + BatchExpiredWebhookEvent, + BatchFailedWebhookEvent, + EvalRunCanceledWebhookEvent, + EvalRunFailedWebhookEvent, + EvalRunSucceededWebhookEvent, + FineTuningJobCancelledWebhookEvent, + FineTuningJobFailedWebhookEvent, + FineTuningJobSucceededWebhookEvent, + RealtimeCallIncomingWebhookEvent, + ResponseCancelledWebhookEvent, + ResponseCompletedWebhookEvent, + ResponseFailedWebhookEvent, + ResponseIncompleteWebhookEvent, + ], + PropertyInfo(discriminator="type"), +] diff --git a/.venv/lib/python3.13/site-packages/openai/types/websocket_connection_options.py b/.venv/lib/python3.13/site-packages/openai/types/websocket_connection_options.py new file mode 100644 index 0000000000000000000000000000000000000000..40fd24ab03386d64de2f2d0ad5280f6dbaa5a97c --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/types/websocket_connection_options.py @@ -0,0 +1,36 @@ +# File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. + +from __future__ import annotations + +from typing import TYPE_CHECKING +from typing_extensions import Sequence, TypedDict + +if TYPE_CHECKING: + from websockets import Subprotocol + from websockets.extensions import ClientExtensionFactory + + +class WebsocketConnectionOptions(TypedDict, total=False): + """Websocket connection options copied from `websockets`. + + For example: https://websockets.readthedocs.io/en/stable/reference/asyncio/client.html#websockets.asyncio.client.connect + """ + + extensions: Sequence[ClientExtensionFactory] | None + """List of supported extensions, in order in which they should be negotiated and run.""" + + subprotocols: Sequence[Subprotocol] | None + """List of supported subprotocols, in order of decreasing preference.""" + + compression: str | None + """The “permessage-deflate” extension is enabled by default. Set compression to None to disable it. See the [compression guide](https://websockets.readthedocs.io/en/stable/topics/compression.html) for details.""" + + # limits + max_size: int | None + """Maximum size of incoming messages in bytes. None disables the limit.""" + + max_queue: int | None | tuple[int | None, int | None] + """High-water mark of the buffer where frames are received. It defaults to 16 frames. The low-water mark defaults to max_queue // 4. You may pass a (high, low) tuple to set the high-water and low-water marks. If you want to disable flow control entirely, you may set it to None, although that’s a bad idea.""" + + write_limit: int | tuple[int, int | None] + """High-water mark of write buffer in bytes. It is passed to set_write_buffer_limits(). It defaults to 32 KiB. You may pass a (high, low) tuple to set the high-water and low-water marks.""" diff --git a/.venv/lib/python3.13/site-packages/openai/version.py b/.venv/lib/python3.13/site-packages/openai/version.py new file mode 100644 index 0000000000000000000000000000000000000000..01a08ab5a93de69d97a4639113dfa0bede48ddba --- /dev/null +++ b/.venv/lib/python3.13/site-packages/openai/version.py @@ -0,0 +1,3 @@ +from ._version import __version__ + +VERSION: str = __version__ diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/INSTALLER b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/INSTALLER new file mode 100644 index 0000000000000000000000000000000000000000..a1b589e38a32041e49332e5e81c2d363dc418d68 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/INSTALLER @@ -0,0 +1 @@ +pip diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/METADATA b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/METADATA new file mode 100644 index 0000000000000000000000000000000000000000..ad8407757d7731d6c7ebf6aa6f61e792eb8eb644 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/METADATA @@ -0,0 +1,1140 @@ +Metadata-Version: 2.4 +Name: orjson +Version: 3.11.9 +Classifier: Development Status :: 5 - Production/Stable +Classifier: Intended Audience :: Developers +Classifier: License :: OSI Approved :: Apache Software License +Classifier: License :: OSI Approved :: MIT License +Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0) +Classifier: Operating System :: MacOS +Classifier: Operating System :: Microsoft :: Windows +Classifier: Operating System :: POSIX :: Linux +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 3.10 +Classifier: Programming Language :: Python :: 3.11 +Classifier: Programming Language :: Python :: 3.12 +Classifier: Programming Language :: Python :: 3.13 +Classifier: Programming Language :: Python :: 3.14 +Classifier: Programming Language :: Python :: 3.15 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python +Classifier: Programming Language :: Rust +Classifier: Typing :: Typed +License-File: LICENSE-APACHE +License-File: LICENSE-MIT +License-File: LICENSE-MPL-2.0 +Summary: Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy +License-Expression: MPL-2.0 AND (Apache-2.0 OR MIT) +Requires-Python: >=3.10 +Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM +Project-URL: changelog, https://github.com/ijl/orjson/blob/master/CHANGELOG.md +Project-URL: documentation, https://github.com/ijl/orjson +Project-URL: source, https://github.com/ijl/orjson + +# orjson + +orjson is a fast, correct JSON library for Python. It +[benchmarks](https://github.com/ijl/orjson?tab=readme-ov-file#performance) as the fastest Python +library for JSON and is more correct than the standard json library or other +third-party libraries. It serializes +[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass), +[datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime), +[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy), and +[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#uuid) instances natively. + +[orjson.dumps()](https://github.com/ijl/orjson?tab=readme-ov-file#serialize) is +something like 10x as fast as `json`, serializes +common types and subtypes, has a `default` parameter for the caller to specify +how to serialize arbitrary types, and has a number of flags controlling output. + +[orjson.loads()](https://github.com/ijl/orjson?tab=readme-ov-file#deserialize) +is something like 2x as fast as `json`, and is strictly compliant with UTF-8 and +RFC 8259 ("The JavaScript Object Notation (JSON) Data Interchange Format"). + +Reading from and writing to files, line-delimited JSON files, and so on is +not provided by the library. + +orjson supports CPython 3.10, 3.11, 3.12, 3.13, 3.14, and 3.15. + +It distributes amd64/x86_64/x64, i686/x86, aarch64/arm64/armv8, arm7, +ppc64le/POWER8, and s390x wheels for Linux, amd64 and aarch64 wheels +for macOS, and amd64, i686, and aarch64 wheels for Windows. + +Wheels published to PyPI for amd64 run on x86-64-v1 (2003) +or later, but will at runtime use AVX-512 if available for a +significant performance benefit; aarch64 wheels run on ARMv8-A (2011) or +later. + +orjson does not and will not support PyPy, embedded Python builds for +Android/iOS, or PEP 554 subinterpreters. + +orjson may support PEP 703 free-threading when it is stable. + +Releases follow semantic versioning and serializing a new object type +without an opt-in flag is considered a breaking change. + +orjson contains source code licensed under the Mozilla Public License 2.0, +Apache 2.0, and MIT licenses. The repository from which PyPI artifacts are +published is [github.com/ijl/orjson](https://github.com/ijl/orjson) and an +alternative repository is [codeberg.org/ijl/orjson](https://codeberg.org/ijl/orjson). +There is no open issue tracker or pull requests due to signal-to-noise ratio. +There is a [CHANGELOG](https://github.com/ijl/orjson/blob/master/CHANGELOG.md) +available in the repository. + +1. [Usage](https://github.com/ijl/orjson?tab=readme-ov-file#usage) + 1. [Install](https://github.com/ijl/orjson?tab=readme-ov-file#install) + 2. [Quickstart](https://github.com/ijl/orjson?tab=readme-ov-file#quickstart) + 3. [Migrating](https://github.com/ijl/orjson?tab=readme-ov-file#migrating) + 4. [Serialize](https://github.com/ijl/orjson?tab=readme-ov-file#serialize) + 1. [default](https://github.com/ijl/orjson?tab=readme-ov-file#default) + 2. [option](https://github.com/ijl/orjson?tab=readme-ov-file#option) + 3. [Fragment](https://github.com/ijl/orjson?tab=readme-ov-file#fragment) + 5. [Deserialize](https://github.com/ijl/orjson?tab=readme-ov-file#deserialize) +2. [Types](https://github.com/ijl/orjson?tab=readme-ov-file#types) + 1. [dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass) + 2. [datetime](https://github.com/ijl/orjson?tab=readme-ov-file#datetime) + 3. [enum](https://github.com/ijl/orjson?tab=readme-ov-file#enum) + 4. [float](https://github.com/ijl/orjson?tab=readme-ov-file#float) + 5. [int](https://github.com/ijl/orjson?tab=readme-ov-file#int) + 6. [numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy) + 7. [str](https://github.com/ijl/orjson?tab=readme-ov-file#str) + 8. [uuid](https://github.com/ijl/orjson?tab=readme-ov-file#uuid) +3. [Testing](https://github.com/ijl/orjson?tab=readme-ov-file#testing) +4. [Performance](https://github.com/ijl/orjson?tab=readme-ov-file#performance) + 1. [Latency](https://github.com/ijl/orjson?tab=readme-ov-file#latency) + 2. [Reproducing](https://github.com/ijl/orjson?tab=readme-ov-file#reproducing) +5. [Questions](https://github.com/ijl/orjson?tab=readme-ov-file#questions) +6. [Packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging) +7. [License](https://github.com/ijl/orjson?tab=readme-ov-file#license) + +## Usage + +### Install + +To install a wheel from PyPI, install the `orjson` package. + +In `requirements.in` or `requirements.txt` format, specify: + +```txt +orjson >= 3.10,<4 +``` + +In `pyproject.toml` format, specify: + +```toml +orjson = "^3.10" +``` + +To build a wheel, see [packaging](https://github.com/ijl/orjson?tab=readme-ov-file#packaging). + +### Quickstart + +This is an example of serializing, with options specified, and deserializing: + +```python +>>> import orjson, datetime, numpy +>>> data = { + "type": "job", + "created_at": datetime.datetime(1970, 1, 1), + "status": "🆗", + "payload": numpy.array([[1, 2], [3, 4]]), +} +>>> orjson.dumps(data, option=orjson.OPT_NAIVE_UTC | orjson.OPT_SERIALIZE_NUMPY) +b'{"type":"job","created_at":"1970-01-01T00:00:00+00:00","status":"\xf0\x9f\x86\x97","payload":[[1,2],[3,4]]}' +>>> orjson.loads(_) +{'type': 'job', 'created_at': '1970-01-01T00:00:00+00:00', 'status': '🆗', 'payload': [[1, 2], [3, 4]]} +``` + +### Migrating + +orjson version 3 serializes more types than version 2. Subclasses of `str`, +`int`, `dict`, and `list` are now serialized. This is faster and more similar +to the standard library. It can be disabled with +`orjson.OPT_PASSTHROUGH_SUBCLASS`.`dataclasses.dataclass` instances +are now serialized by default and cannot be customized in a +`default` function unless `option=orjson.OPT_PASSTHROUGH_DATACLASS` is +specified. `uuid.UUID` instances are serialized by default. +For any type that is now serialized, +implementations in a `default` function and options enabling them can be +removed but do not need to be. There was no change in deserialization. + +To migrate from the standard library, the largest difference is that +`orjson.dumps` returns `bytes` and `json.dumps` returns a `str`. + +Users with `dict` objects using non-`str` keys should specify `option=orjson.OPT_NON_STR_KEYS`. + +`sort_keys` is replaced by `option=orjson.OPT_SORT_KEYS`. + +`indent` is replaced by `option=orjson.OPT_INDENT_2` and other levels of indentation are not +supported. + +`ensure_ascii` is probably not relevant today and UTF-8 characters cannot be +escaped to ASCII. + +### Serialize + +```python +def dumps( + __obj: Any, + default: Optional[Callable[[Any], Any]] = ..., + option: Optional[int] = ..., +) -> bytes: ... +``` + +`dumps()` serializes Python objects to JSON. + +It natively serializes +`str`, `dict`, `list`, `tuple`, `int`, `float`, `bool`, `None`, +`dataclasses.dataclass`, `typing.TypedDict`, `datetime.datetime`, +`datetime.date`, `datetime.time`, `uuid.UUID`, `numpy.ndarray`, and +`orjson.Fragment` instances. It supports arbitrary types through `default`. It +serializes subclasses of `str`, `int`, `dict`, `list`, +`dataclasses.dataclass`, and `enum.Enum`. It does not serialize subclasses +of `tuple` to avoid serializing `namedtuple` objects as arrays. To avoid +serializing subclasses, specify the option `orjson.OPT_PASSTHROUGH_SUBCLASS`. + +The output is a `bytes` object containing UTF-8. + +The global interpreter lock (GIL) is held for the duration of the call. + +It raises `JSONEncodeError` on an unsupported type. This exception message +describes the invalid object with the error message +`Type is not JSON serializable: ...`. To fix this, specify +[default](https://github.com/ijl/orjson?tab=readme-ov-file#default). + +It raises `JSONEncodeError` on a `str` that contains invalid UTF-8. + +It raises `JSONEncodeError` on an integer that exceeds 64 bits by default or, +with `OPT_STRICT_INTEGER`, 53 bits. + +It raises `JSONEncodeError` if a `dict` has a key of a type other than `str`, +unless `OPT_NON_STR_KEYS` is specified. + +It raises `JSONEncodeError` if the output of `default` recurses to handling by +`default` more than 254 levels deep. + +It raises `JSONEncodeError` on circular references. + +It raises `JSONEncodeError` if a `tzinfo` on a datetime object is +unsupported. + +`JSONEncodeError` is a subclass of `TypeError`. This is for compatibility +with the standard library. + +If the failure was caused by an exception in `default` then +`JSONEncodeError` chains the original exception as `__cause__`. + +#### default + +To serialize a subclass or arbitrary types, specify `default` as a +callable that returns a supported type. `default` may be a function, +lambda, or callable class instance. To specify that a type was not +handled by `default`, raise an exception such as `TypeError`. + +```python +>>> import orjson, decimal +>>> +def default(obj): + if isinstance(obj, decimal.Decimal): + return str(obj) + raise TypeError + +>>> orjson.dumps(decimal.Decimal("0.0842389659712649442845")) +JSONEncodeError: Type is not JSON serializable: decimal.Decimal +>>> orjson.dumps(decimal.Decimal("0.0842389659712649442845"), default=default) +b'"0.0842389659712649442845"' +>>> orjson.dumps({1, 2}, default=default) +orjson.JSONEncodeError: Type is not JSON serializable: set +``` + +The `default` callable may return an object that itself +must be handled by `default` up to 254 times before an exception +is raised. + +It is important that `default` raise an exception if a type cannot be handled. +Python otherwise implicitly returns `None`, which appears to the caller +like a legitimate value and is serialized: + +```python +>>> import orjson, json +>>> +def default(obj): + if isinstance(obj, decimal.Decimal): + return str(obj) + +>>> orjson.dumps({"set":{1, 2}}, default=default) +b'{"set":null}' +>>> json.dumps({"set":{1, 2}}, default=default) +'{"set":null}' +``` + +#### option + +To modify how data is serialized, specify `option`. Each `option` is an integer +constant in `orjson`. To specify multiple options, mask them together, e.g., +`option=orjson.OPT_STRICT_INTEGER | orjson.OPT_NAIVE_UTC`. + +##### OPT_APPEND_NEWLINE + +Append `\n` to the output. This is a convenience and optimization for the +pattern of `dumps(...) + "\n"`. `bytes` objects are immutable and this +pattern copies the original contents. + +```python +>>> import orjson +>>> orjson.dumps([]) +b"[]" +>>> orjson.dumps([], option=orjson.OPT_APPEND_NEWLINE) +b"[]\n" +``` + +##### OPT_INDENT_2 + +Pretty-print output with an indent of two spaces. This is equivalent to +`indent=2` in the standard library. Pretty printing is slower and the output +larger. This option is compatible with all other options. + +```python +>>> import orjson +>>> orjson.dumps({"a": "b", "c": {"d": True}, "e": [1, 2]}) +b'{"a":"b","c":{"d":true},"e":[1,2]}' +>>> orjson.dumps( + {"a": "b", "c": {"d": True}, "e": [1, 2]}, + option=orjson.OPT_INDENT_2 +) +b'{\n "a": "b",\n "c": {\n "d": true\n },\n "e": [\n 1,\n 2\n ]\n}' +``` + +If displayed, the indentation and linebreaks appear like this: + +```json +{ + "a": "b", + "c": { + "d": true + }, + "e": [ + 1, + 2 + ] +} +``` + +This measures serializing the github.json fixture as compact (52KiB) or +pretty (64KiB): + +| Library | compact (ms) | pretty (ms) | vs. orjson | +|-----------|----------------|---------------|--------------| +| orjson | 0.01 | 0.02 | 1 | +| json | 0.13 | 0.54 | 34 | + +This measures serializing the citm_catalog.json fixture, more of a worst +case due to the amount of nesting and newlines, as compact (489KiB) or +pretty (1.1MiB): + +| Library | compact (ms) | pretty (ms) | vs. orjson | +|-----------|----------------|---------------|--------------| +| orjson | 0.25 | 0.45 | 1 | +| json | 3.01 | 24.42 | 54.4 | + +This can be reproduced using the `pyindent` script. + +##### OPT_NAIVE_UTC + +Serialize `datetime.datetime` objects without a `tzinfo` as UTC. This +has no effect on `datetime.datetime` objects that have `tzinfo` set. + +```python +>>> import orjson, datetime +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0), + ) +b'"1970-01-01T00:00:00"' +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0), + option=orjson.OPT_NAIVE_UTC, + ) +b'"1970-01-01T00:00:00+00:00"' +``` + +##### OPT_NON_STR_KEYS + +Serialize `dict` keys of type other than `str`. This allows `dict` keys +to be one of `str`, `int`, `float`, `bool`, `None`, `datetime.datetime`, +`datetime.date`, `datetime.time`, `enum.Enum`, and `uuid.UUID`. For comparison, +the standard library serializes `str`, `int`, `float`, `bool` or `None` by +default. orjson benchmarks as being faster at serializing non-`str` keys +than other libraries. This option is slower for `str` keys than the default. + +```python +>>> import orjson, datetime, uuid +>>> orjson.dumps( + {uuid.UUID("7202d115-7ff3-4c81-a7c1-2a1f067b1ece"): [1, 2, 3]}, + option=orjson.OPT_NON_STR_KEYS, + ) +b'{"7202d115-7ff3-4c81-a7c1-2a1f067b1ece":[1,2,3]}' +>>> orjson.dumps( + {datetime.datetime(1970, 1, 1, 0, 0, 0): [1, 2, 3]}, + option=orjson.OPT_NON_STR_KEYS | orjson.OPT_NAIVE_UTC, + ) +b'{"1970-01-01T00:00:00+00:00":[1,2,3]}' +``` + +These types are generally serialized how they would be as +values, e.g., `datetime.datetime` is still an RFC 3339 string and respects +options affecting it. The exception is that `int` serialization does not +respect `OPT_STRICT_INTEGER`. + +This option has the risk of creating duplicate keys. This is because non-`str` +objects may serialize to the same `str` as an existing key, e.g., +`{"1": true, 1: false}`. The last key to be inserted to the `dict` will be +serialized last and a JSON deserializer will presumably take the last +occurrence of a key (in the above, `false`). The first value will be lost. + +This option is compatible with `orjson.OPT_SORT_KEYS`. If sorting is used, +note the sort is unstable and will be unpredictable for duplicate keys. + +```python +>>> import orjson, datetime +>>> orjson.dumps( + {"other": 1, datetime.date(1970, 1, 5): 2, datetime.date(1970, 1, 3): 3}, + option=orjson.OPT_NON_STR_KEYS | orjson.OPT_SORT_KEYS +) +b'{"1970-01-03":3,"1970-01-05":2,"other":1}' +``` + +This measures serializing 589KiB of JSON comprising a `list` of 100 `dict` +in which each `dict` has both 365 randomly-sorted `int` keys representing epoch +timestamps as well as one `str` key and the value for each key is a +single integer. In "str keys", the keys were converted to `str` before +serialization, and orjson still specifes `option=orjson.OPT_NON_STR_KEYS` +(which is always somewhat slower). + +| Library | str keys (ms) | int keys (ms) | int keys sorted (ms) | +|-----------|-----------------|-----------------|------------------------| +| orjson | 0.5 | 0.93 | 2.08 | +| json | 2.72 | 3.59 | | + +json is blank because it +raises `TypeError` on attempting to sort before converting all keys to `str`. +This can be reproduced using the `pynonstr` script. + +##### OPT_OMIT_MICROSECONDS + +Do not serialize the `microsecond` field on `datetime.datetime` and +`datetime.time` instances. + +```python +>>> import orjson, datetime +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0, 1), + ) +b'"1970-01-01T00:00:00.000001"' +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0, 1), + option=orjson.OPT_OMIT_MICROSECONDS, + ) +b'"1970-01-01T00:00:00"' +``` + +##### OPT_PASSTHROUGH_DATACLASS + +Passthrough `dataclasses.dataclass` instances to `default`. This allows +customizing their output but is much slower. + + +```python +>>> import orjson, dataclasses +>>> +@dataclasses.dataclass +class User: + id: str + name: str + password: str + +def default(obj): + if isinstance(obj, User): + return {"id": obj.id, "name": obj.name} + raise TypeError + +>>> orjson.dumps(User("3b1", "asd", "zxc")) +b'{"id":"3b1","name":"asd","password":"zxc"}' +>>> orjson.dumps(User("3b1", "asd", "zxc"), option=orjson.OPT_PASSTHROUGH_DATACLASS) +TypeError: Type is not JSON serializable: User +>>> orjson.dumps( + User("3b1", "asd", "zxc"), + option=orjson.OPT_PASSTHROUGH_DATACLASS, + default=default, + ) +b'{"id":"3b1","name":"asd"}' +``` + +##### OPT_PASSTHROUGH_DATETIME + +Passthrough `datetime.datetime`, `datetime.date`, and `datetime.time` instances +to `default`. This allows serializing datetimes to a custom format, e.g., +HTTP dates: + +```python +>>> import orjson, datetime +>>> +def default(obj): + if isinstance(obj, datetime.datetime): + return obj.strftime("%a, %d %b %Y %H:%M:%S GMT") + raise TypeError + +>>> orjson.dumps({"created_at": datetime.datetime(1970, 1, 1)}) +b'{"created_at":"1970-01-01T00:00:00"}' +>>> orjson.dumps({"created_at": datetime.datetime(1970, 1, 1)}, option=orjson.OPT_PASSTHROUGH_DATETIME) +TypeError: Type is not JSON serializable: datetime.datetime +>>> orjson.dumps( + {"created_at": datetime.datetime(1970, 1, 1)}, + option=orjson.OPT_PASSTHROUGH_DATETIME, + default=default, + ) +b'{"created_at":"Thu, 01 Jan 1970 00:00:00 GMT"}' +``` + +This does not affect datetimes in `dict` keys if using OPT_NON_STR_KEYS. + +##### OPT_PASSTHROUGH_SUBCLASS + +Passthrough subclasses of builtin types to `default`. + +```python +>>> import orjson +>>> +class Secret(str): + pass + +def default(obj): + if isinstance(obj, Secret): + return "******" + raise TypeError + +>>> orjson.dumps(Secret("zxc")) +b'"zxc"' +>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS) +TypeError: Type is not JSON serializable: Secret +>>> orjson.dumps(Secret("zxc"), option=orjson.OPT_PASSTHROUGH_SUBCLASS, default=default) +b'"******"' +``` + +This does not affect serializing subclasses as `dict` keys if using +OPT_NON_STR_KEYS. + +##### OPT_SERIALIZE_DATACLASS + +This is deprecated and has no effect in version 3. In version 2 this was +required to serialize `dataclasses.dataclass` instances. For more, see +[dataclass](https://github.com/ijl/orjson?tab=readme-ov-file#dataclass). + +##### OPT_SERIALIZE_NUMPY + +Serialize `numpy.ndarray` instances. For more, see +[numpy](https://github.com/ijl/orjson?tab=readme-ov-file#numpy). + +##### OPT_SERIALIZE_UUID + +This is deprecated and has no effect in version 3. In version 2 this was +required to serialize `uuid.UUID` instances. For more, see +[UUID](https://github.com/ijl/orjson?tab=readme-ov-file#UUID). + +##### OPT_SORT_KEYS + +Serialize `dict` keys in sorted order. The default is to serialize in an +unspecified order. This is equivalent to `sort_keys=True` in the standard +library. + +This can be used to ensure the order is deterministic for hashing or tests. +It has a substantial performance penalty and is not recommended in general. + +```python +>>> import orjson +>>> orjson.dumps({"b": 1, "c": 2, "a": 3}) +b'{"b":1,"c":2,"a":3}' +>>> orjson.dumps({"b": 1, "c": 2, "a": 3}, option=orjson.OPT_SORT_KEYS) +b'{"a":3,"b":1,"c":2}' +``` + +This measures serializing the twitter.json fixture unsorted and sorted: + +| Library | unsorted (ms) | sorted (ms) | vs. orjson | +|-----------|-----------------|---------------|--------------| +| orjson | 0.11 | 0.3 | 1 | +| json | 1.36 | 1.93 | 6.4 | + +The benchmark can be reproduced using the `pysort` script. + +The sorting is not collation/locale-aware: + +```python +>>> import orjson +>>> orjson.dumps({"a": 1, "ä": 2, "A": 3}, option=orjson.OPT_SORT_KEYS) +b'{"A":3,"a":1,"\xc3\xa4":2}' +``` + +This is the same sorting behavior as the standard library. + +`dataclass` also serialize as maps but this has no effect on them. + +##### OPT_STRICT_INTEGER + +Enforce 53-bit limit on integers. The limit is otherwise 64 bits, the same as +the Python standard library. For more, see [int](https://github.com/ijl/orjson?tab=readme-ov-file#int). + +##### OPT_UTC_Z + +Serialize a UTC timezone on `datetime.datetime` instances as `Z` instead +of `+00:00`. + +```python +>>> import orjson, datetime, zoneinfo +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")), + ) +b'"1970-01-01T00:00:00+00:00"' +>>> orjson.dumps( + datetime.datetime(1970, 1, 1, 0, 0, 0, tzinfo=zoneinfo.ZoneInfo("UTC")), + option=orjson.OPT_UTC_Z + ) +b'"1970-01-01T00:00:00Z"' +``` + +#### Fragment + +`orjson.Fragment` includes already-serialized JSON in a document. This is an +efficient way to include JSON blobs from a cache, JSONB field, or separately +serialized object without first deserializing to Python objects via `loads()`. + +```python +>>> import orjson +>>> orjson.dumps({"key": "zxc", "data": orjson.Fragment(b'{"a": "b", "c": 1}')}) +b'{"key":"zxc","data":{"a": "b", "c": 1}}' +``` + +It does no reformatting: `orjson.OPT_INDENT_2` will not affect a +compact blob nor will a pretty-printed JSON blob be rewritten as compact. + +The input must be `bytes` or `str` and given as a positional argument. + +This raises `orjson.JSONEncodeError` if a `str` is given and the input is +not valid UTF-8. It otherwise does no validation and it is possible to +write invalid JSON. This does not escape characters. The implementation is +tested to not crash if given invalid strings or invalid JSON. + +### Deserialize + +```python +def loads(__obj: Union[bytes, bytearray, memoryview, str]) -> Any: ... +``` + +`loads()` deserializes JSON to Python objects. It deserializes to `dict`, +`list`, `int`, `float`, `str`, `bool`, and `None` objects. + +`bytes`, `bytearray`, `memoryview`, and `str` input are accepted. If the input +exists as a `memoryview`, `bytearray`, or `bytes` object, it is recommended to +pass these directly rather than creating an unnecessary `str` object. That is, +`orjson.loads(b"{}")` instead of `orjson.loads(b"{}".decode("utf-8"))`. This +has lower memory usage and lower latency. + +The input must be valid UTF-8. + +orjson maintains a cache of map keys for the duration of the process. This +causes a net reduction in memory usage by avoiding duplicate strings. The +keys must be at most 64 bytes to be cached and 2048 entries are stored. + +The global interpreter lock (GIL) is held for the duration of the call. + +It raises `JSONDecodeError` if given an invalid type or invalid +JSON. This includes if the input contains `NaN`, `Infinity`, or `-Infinity`, +which the standard library allows, but is not valid JSON. + +It raises `JSONDecodeError` if a combination of array or object recurses +1024 levels deep. + +It raises `JSONDecodeError` if unable to allocate a buffer large enough +to parse the document. + +`JSONDecodeError` is a subclass of `json.JSONDecodeError` and `ValueError`. +This is for compatibility with the standard library. + +## Types + +### dataclass + +orjson serializes instances of `dataclasses.dataclass` natively. It serializes +instances 40-50x as fast as other libraries and avoids a severe slowdown seen +in other libraries compared to serializing `dict`. + +It is supported to pass all variants of dataclasses, including dataclasses +using `__slots__`, frozen dataclasses, those with optional or default +attributes, and subclasses. There is a performance benefit to not +using `__slots__`. + +| Library | dict (ms) | dataclass (ms) | vs. orjson | +|-----------|-------------|------------------|--------------| +| orjson | 0.43 | 0.95 | 1 | +| json | 5.81 | 38.32 | 40 | + +This measures serializing 555KiB of JSON, orjson natively and other libraries +using `default` to serialize the output of `dataclasses.asdict()`. This can be +reproduced using the `pydataclass` script. + +Dataclasses are serialized as maps, with every attribute serialized and in +the order given on class definition: + +```python +>>> import dataclasses, orjson, typing + +@dataclasses.dataclass +class Member: + id: int + active: bool = dataclasses.field(default=False) + +@dataclasses.dataclass +class Object: + id: int + name: str + members: typing.List[Member] + +>>> orjson.dumps(Object(1, "a", [Member(1, True), Member(2)])) +b'{"id":1,"name":"a","members":[{"id":1,"active":true},{"id":2,"active":false}]}' +``` + +### datetime + +orjson serializes `datetime.datetime` objects to +[RFC 3339](https://tools.ietf.org/html/rfc3339) format, +e.g., "1970-01-01T00:00:00+00:00". This is a subset of ISO 8601 and is +compatible with `isoformat()` in the standard library. + +```python +>>> import orjson, datetime, zoneinfo +>>> orjson.dumps( + datetime.datetime(2018, 12, 1, 2, 3, 4, 9, tzinfo=zoneinfo.ZoneInfo("Australia/Adelaide")) +) +b'"2018-12-01T02:03:04.000009+10:30"' +>>> orjson.dumps( + datetime.datetime(2100, 9, 1, 21, 55, 2).replace(tzinfo=zoneinfo.ZoneInfo("UTC")) +) +b'"2100-09-01T21:55:02+00:00"' +>>> orjson.dumps( + datetime.datetime(2100, 9, 1, 21, 55, 2) +) +b'"2100-09-01T21:55:02"' +``` + +`datetime.datetime` supports instances with a `tzinfo` that is `None`, +`datetime.timezone.utc`, a timezone instance from the standard library `zoneinfo` +module, or a timezone instance from the third-party `pendulum`, `pytz`, or +`dateutil`/`arrow` libraries. + +It is fastest to use the standard library's `zoneinfo.ZoneInfo` for timezones. + +`datetime.time` objects must not have a `tzinfo`. + +```python +>>> import orjson, datetime +>>> orjson.dumps(datetime.time(12, 0, 15, 290)) +b'"12:00:15.000290"' +``` + +`datetime.date` objects will always serialize. + +```python +>>> import orjson, datetime +>>> orjson.dumps(datetime.date(1900, 1, 2)) +b'"1900-01-02"' +``` + +Errors with `tzinfo` result in `JSONEncodeError` being raised. + +To disable serialization of `datetime` objects specify the option +`orjson.OPT_PASSTHROUGH_DATETIME`. + +To use "Z" suffix instead of "+00:00" to indicate UTC ("Zulu") time, use the option +`orjson.OPT_UTC_Z`. + +To assume datetimes without timezone are UTC, use the option `orjson.OPT_NAIVE_UTC`. + +### enum + +orjson serializes enums natively. Options apply to their values. + +```python +>>> import enum, datetime, orjson +>>> +class DatetimeEnum(enum.Enum): + EPOCH = datetime.datetime(1970, 1, 1, 0, 0, 0) +>>> orjson.dumps(DatetimeEnum.EPOCH) +b'"1970-01-01T00:00:00"' +>>> orjson.dumps(DatetimeEnum.EPOCH, option=orjson.OPT_NAIVE_UTC) +b'"1970-01-01T00:00:00+00:00"' +``` + +Enums with members that are not supported types can be serialized using +`default`: + +```python +>>> import enum, orjson +>>> +class Custom: + def __init__(self, val): + self.val = val + +def default(obj): + if isinstance(obj, Custom): + return obj.val + raise TypeError + +class CustomEnum(enum.Enum): + ONE = Custom(1) + +>>> orjson.dumps(CustomEnum.ONE, default=default) +b'1' +``` + +### float + +orjson serializes and deserializes double precision floats with no loss of +precision and consistent rounding. + +`orjson.dumps()` serializes Nan, Infinity, and -Infinity, which are not +compliant JSON, as `null`: + +```python +>>> import orjson, json +>>> orjson.dumps([float("NaN"), float("Infinity"), float("-Infinity")]) +b'[null,null,null]' +>>> json.dumps([float("NaN"), float("Infinity"), float("-Infinity")]) +'[NaN, Infinity, -Infinity]' +``` + +### int + +orjson serializes and deserializes 64-bit integers by default. The range +supported is a signed 64-bit integer's minimum (-9223372036854775807) to +an unsigned 64-bit integer's maximum (18446744073709551615). This +is widely compatible, but there are implementations +that only support 53-bits for integers, e.g., +web browsers. For those implementations, `dumps()` can be configured to +raise a `JSONEncodeError` on values exceeding the 53-bit range. + +```python +>>> import orjson +>>> orjson.dumps(9007199254740992) +b'9007199254740992' +>>> orjson.dumps(9007199254740992, option=orjson.OPT_STRICT_INTEGER) +JSONEncodeError: Integer exceeds 53-bit range +>>> orjson.dumps(-9007199254740992, option=orjson.OPT_STRICT_INTEGER) +JSONEncodeError: Integer exceeds 53-bit range +``` + +### numpy + +orjson natively serializes `numpy.ndarray` and individual +`numpy.float64`, `numpy.float32`, `numpy.float16` (`numpy.half`), +`numpy.int64`, `numpy.int32`, `numpy.int16`, `numpy.int8`, +`numpy.uint64`, `numpy.uint32`, `numpy.uint16`, `numpy.uint8`, +`numpy.uintp`, `numpy.intp`, `numpy.datetime64`, and `numpy.bool` +instances. + +orjson is compatible with both numpy v1 and v2. + +orjson is faster than all compared libraries at serializing +numpy instances. Serializing numpy data requires specifying +`option=orjson.OPT_SERIALIZE_NUMPY`. + +```python +>>> import orjson, numpy +>>> orjson.dumps( + numpy.array([[1, 2, 3], [4, 5, 6]]), + option=orjson.OPT_SERIALIZE_NUMPY, +) +b'[[1,2,3],[4,5,6]]' +``` + +The array must be a contiguous C array (`C_CONTIGUOUS`) and one of the +supported datatypes. + +Note a difference between serializing `numpy.float32` using `ndarray.tolist()` +or `orjson.dumps(..., option=orjson.OPT_SERIALIZE_NUMPY)`: `tolist()` converts +to a `double` before serializing and orjson's native path does not. This +can result in different rounding. + +`numpy.datetime64` instances are serialized as RFC 3339 strings and +datetime options affect them. + +```python +>>> import orjson, numpy +>>> orjson.dumps( + numpy.datetime64("2021-01-01T00:00:00.172"), + option=orjson.OPT_SERIALIZE_NUMPY, +) +b'"2021-01-01T00:00:00.172000"' +>>> orjson.dumps( + numpy.datetime64("2021-01-01T00:00:00.172"), + option=( + orjson.OPT_SERIALIZE_NUMPY | + orjson.OPT_NAIVE_UTC | + orjson.OPT_OMIT_MICROSECONDS + ), +) +b'"2021-01-01T00:00:00+00:00"' +``` + +If an array is not a contiguous C array, contains an unsupported datatype, +or contains a `numpy.datetime64` using an unsupported representation +(e.g., picoseconds), orjson falls through to `default`. In `default`, +`obj.tolist()` can be specified. + +If an array is not in the native endianness, e.g., an array of big-endian values +on a little-endian system, `orjson.JSONEncodeError` is raised. + +If an array is malformed, `orjson.JSONEncodeError` is raised. + +This measures serializing 92MiB of JSON from an `numpy.ndarray` with +dimensions of `(50000, 100)` and `numpy.float64` values: + +| Library | Latency (ms) | RSS diff (MiB) | vs. orjson | +|-----------|----------------|------------------|--------------| +| orjson | 105 | 105 | 1 | +| json | 1,481 | 295 | 14.2 | + +This measures serializing 100MiB of JSON from an `numpy.ndarray` with +dimensions of `(100000, 100)` and `numpy.int32` values: + +| Library | Latency (ms) | RSS diff (MiB) | vs. orjson | +|-----------|----------------|------------------|--------------| +| orjson | 68 | 119 | 1 | +| json | 684 | 501 | 10.1 | + +This measures serializing 105MiB of JSON from an `numpy.ndarray` with +dimensions of `(100000, 200)` and `numpy.bool` values: + +| Library | Latency (ms) | RSS diff (MiB) | vs. orjson | +|-----------|----------------|------------------|--------------| +| orjson | 50 | 125 | 1 | +| json | 573 | 398 | 11.5 | + +In these benchmarks, orjson serializes natively and `json` serializes +`ndarray.tolist()` via `default`. The RSS column measures peak memory +usage during serialization. This can be reproduced using the `pynumpy` script. + +orjson does not have an installation or compilation dependency on numpy. The +implementation is independent, reading `numpy.ndarray` using +`PyArrayInterface`. + +### str + +orjson is strict about UTF-8 conformance. This is stricter than the standard +library's json module, which will serialize and deserialize UTF-16 surrogates, +e.g., "\ud800", that are invalid UTF-8. + +If `orjson.dumps()` is given a `str` that does not contain valid UTF-8, +`orjson.JSONEncodeError` is raised. If `loads()` receives invalid UTF-8, +`orjson.JSONDecodeError` is raised. + +```python +>>> import orjson, json +>>> orjson.dumps('\ud800') +JSONEncodeError: str is not valid UTF-8: surrogates not allowed +>>> json.dumps('\ud800') +'"\\ud800"' +>>> orjson.loads('"\\ud800"') +JSONDecodeError: unexpected end of hex escape at line 1 column 8: line 1 column 1 (char 0) +>>> json.loads('"\\ud800"') +'\ud800' +``` + +To make a best effort at deserializing bad input, first decode `bytes` using +the `replace` or `lossy` argument for `errors`: + +```python +>>> import orjson +>>> orjson.loads(b'"\xed\xa0\x80"') +JSONDecodeError: str is not valid UTF-8: surrogates not allowed +>>> orjson.loads(b'"\xed\xa0\x80"'.decode("utf-8", "replace")) +'���' +``` + +### uuid + +orjson serializes `uuid.UUID` instances to +[RFC 4122](https://tools.ietf.org/html/rfc4122) format, e.g., +"f81d4fae-7dec-11d0-a765-00a0c91e6bf6". + +``` python +>>> import orjson, uuid +>>> orjson.dumps(uuid.uuid5(uuid.NAMESPACE_DNS, "python.org")) +b'"886313e1-3b8a-5372-9b90-0c9aee199e5d"' +``` + +## Testing + +The library has comprehensive tests. There are tests against fixtures in the +[JSONTestSuite](https://github.com/nst/JSONTestSuite) and +[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) +repositories. It is tested to not crash against the +[Big List of Naughty Strings](https://github.com/minimaxir/big-list-of-naughty-strings). +It is tested to not leak memory. It is tested to not crash +against and not accept invalid UTF-8. There are integration tests +exercising the library's use in web servers (gunicorn using multiprocess/forked +workers) and when multithreaded. + +orjson is the most correct of the compared libraries. This graph shows how each +library handles a combined 342 JSON fixtures from the +[JSONTestSuite](https://github.com/nst/JSONTestSuite) and +[nativejson-benchmark](https://github.com/miloyip/nativejson-benchmark) tests: + +| Library | Invalid JSON documents not rejected | Valid JSON documents not deserialized | +|------------|---------------------------------------|-----------------------------------------| +| orjson | 0 | 0 | +| json | 17 | 0 | + +This shows that all libraries deserialize valid JSON but only orjson +correctly rejects the given invalid JSON fixtures. Errors are largely due to +accepting invalid strings and numbers. + +The graph above can be reproduced using the `pycorrectness` script. + +## Performance + +Serialization and deserialization performance of orjson is consistently better +than the standard library's `json`. The graphs below illustrate a few commonly +used documents. + +### Latency + +![Serialization](doc/serialization.png) + +![Deserialization](doc/deserialization.png) + +#### twitter.json serialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 0.1 | 8453 | 1 | +| json | 1.3 | 765 | 11.1 | + +#### twitter.json deserialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 0.5 | 1889 | 1 | +| json | 2.2 | 453 | 4.2 | + +#### github.json serialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 0.01 | 103693 | 1 | +| json | 0.13 | 7648 | 13.6 | + +#### github.json deserialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 0.04 | 23264 | 1 | +| json | 0.1 | 10430 | 2.2 | + +#### citm_catalog.json serialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 0.3 | 3975 | 1 | +| json | 3 | 338 | 11.8 | + +#### citm_catalog.json deserialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 1.3 | 781 | 1 | +| json | 4 | 250 | 3.1 | + +#### canada.json serialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 2.5 | 399 | 1 | +| json | 29.8 | 33 | 11.9 | + +#### canada.json deserialization + +| Library | Median latency (milliseconds) | Operations per second | Relative (latency) | +|-----------|---------------------------------|-------------------------|----------------------| +| orjson | 3 | 333 | 1 | +| json | 18 | 55 | 6 | + +### Reproducing + +The above was measured using Python 3.11.10 in a Fedora 42 container on an +x86-64-v4 machine using the +`orjson-3.10.11-cp311-cp311-manylinux_2_17_x86_64.manylinux2014_x86_64.whl` +artifact on PyPI. The latency results can be reproduced using the `pybench` script. + +## Questions + +### Will it deserialize to dataclasses, UUIDs, decimals, etc or support object_hook? + +No. This requires a schema specifying what types are expected and how to +handle errors etc. This is addressed by data validation libraries a +level above this. + +### Will it serialize to `str`? + +No. `bytes` is the correct type for a serialized blob. + +### Will it support NDJSON or JSONL? + +No. [orjsonl](https://github.com/umarbutler/orjsonl) may be appropriate. + +### Will it support JSON5 or RJSON? + +No, it supports RFC 8259. + +### How do I depend on orjson in a Rust project? + +orjson is only shipped as a Python module. The project should depend on +`orjson` in its own Python requirements and should obtain pointers to +functions and objects using the normal `PyImport_*` APIs. + +## Packaging + +To package orjson requires at least [Rust](https://www.rust-lang.org/) 1.95, +a C compiler, and the [maturin](https://github.com/PyO3/maturin) build tool. +The recommended build command is: + +```sh +maturin build --release --strip +``` + +The project's own CI tests against `nightly-2026-05-01` and stable 1.95. It +is prudent to pin the nightly version because that channel can introduce +breaking changes. There is a significant performance benefit to using +nightly. + +orjson is tested on native hardware for amd64, aarch64, and i686 on Linux. It is +cross-compiled and may be tested via emulation for arm7, ppc64le, and s390x. It +is tested for aarch64 on macOS and cross-compiles for amd64. For +Windows it is tested on amd64, i686, and aarch64. + +There are no runtime dependencies other than libc. + +The source distribution on PyPI contains all dependencies' source and can be +built without network access. The file can be downloaded from +`https://files.pythonhosted.org/packages/source/o/orjson/orjson-${version}.tar.gz`. + +orjson's tests are included in the source distribution on PyPI. The tests +require only `pytest`. There are optional packages such as `pytz` and `numpy` +listed in `test/requirements.txt` and used in ~10% of tests. Not having these +dependencies causes the tests needing them to skip. Tests can be run +with `pytest -q test`. + +## License + +orjson was written by ijl <>, copyright 2018 - 2026, with +some source files available under the Mozilla Public License 2.0 and some +available under your choice of the Apache 2 license or MIT license. + diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/RECORD b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/RECORD new file mode 100644 index 0000000000000000000000000000000000000000..93b5cfa19d0a95f7e5dc11a383296357569aee3d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/RECORD @@ -0,0 +1,13 @@ +orjson-3.11.9.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4 +orjson-3.11.9.dist-info/METADATA,sha256=KIpNYW5og375gFm7cQWbeRC3IVm3t60odci7gUY8GIc,41968 +orjson-3.11.9.dist-info/RECORD,, +orjson-3.11.9.dist-info/WHEEL,sha256=K7WEhceKrUcmvtDDTcmMfFZMFbiOevaadPlGHHcaRsQ,147 +orjson-3.11.9.dist-info/licenses/LICENSE-APACHE,sha256=pg7qgXUUUxZo1-AHZXMUSf4U0FnTJJ4LyTs23kX3WfI,10847 +orjson-3.11.9.dist-info/licenses/LICENSE-MIT,sha256=I_GOA9xJ35FiL-KnYXZJdATkbO2KcV2dK2enRGVxzKM,1023 +orjson-3.11.9.dist-info/licenses/LICENSE-MPL-2.0,sha256=ZqMQfVrWoFiqt1PqrCBHzLLtDjlGXdD-WETaPjANUXI,16727 +orjson-3.11.9.dist-info/sboms/orjson.cyclonedx.json,sha256=ZMvvnLgMVQlER4EICuWRqagmel8_0hHpcqNllRsv2kQ,33096 +orjson/__init__.py,sha256=ejoFsSgbZapQVMNTh_vlvJkwW_lLnsd3SmzUpvWxSPU,693 +orjson/__init__.pyi,sha256=ApTAgpg75i1fKjyi5QwAkB2eP0w73IJFNaqKSx70ASE,876 +orjson/__pycache__/__init__.cpython-313.pyc,, +orjson/orjson.cpython-313-x86_64-linux-gnu.so,sha256=9CxwFEc_oLfrcy_hZTx4x5w5VCiIEqR_bKj3TCszKj4,246184 +orjson/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0 diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/WHEEL b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/WHEEL new file mode 100644 index 0000000000000000000000000000000000000000..298751c27dcc9bf0653e67833f5ef649ea8d41cc --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/WHEEL @@ -0,0 +1,5 @@ +Wheel-Version: 1.0 +Generator: maturin (1.13.1) +Root-Is-Purelib: false +Tag: cp313-cp313-manylinux_2_17_x86_64 +Tag: cp313-cp313-manylinux2014_x86_64 diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-APACHE b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-APACHE new file mode 100644 index 0000000000000000000000000000000000000000..16fe87b06e802f094b3fbb0894b137bca2b16ef1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-APACHE @@ -0,0 +1,201 @@ + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + +TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + +1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + +2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + +3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + +4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + +5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + +6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + +7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + +8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + +9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + +END OF TERMS AND CONDITIONS + +APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + +Copyright [yyyy] [name of copyright owner] + +Licensed under the Apache License, Version 2.0 (the "License"); +you may not use this file except in compliance with the License. +You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +See the License for the specific language governing permissions and +limitations under the License. diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MIT b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MIT new file mode 100644 index 0000000000000000000000000000000000000000..31aa79387f27e730e33d871925e152e35e428031 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MIT @@ -0,0 +1,23 @@ +Permission is hereby granted, free of charge, to any +person obtaining a copy of this software and associated +documentation files (the "Software"), to deal in the +Software without restriction, including without +limitation the rights to use, copy, modify, merge, +publish, distribute, sublicense, and/or sell copies of +the Software, and to permit persons to whom the Software +is furnished to do so, subject to the following +conditions: + +The above copyright notice and this permission notice +shall be included in all copies or substantial portions +of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF +ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED +TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT +SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR +IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER +DEALINGS IN THE SOFTWARE. diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MPL-2.0 b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MPL-2.0 new file mode 100644 index 0000000000000000000000000000000000000000..ee6256cdb62a765749a71aae3abea32884301cd1 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/licenses/LICENSE-MPL-2.0 @@ -0,0 +1,373 @@ +Mozilla Public License Version 2.0 +================================== + +1. Definitions +-------------- + +1.1. "Contributor" + means each individual or legal entity that creates, contributes to + the creation of, or owns Covered Software. + +1.2. "Contributor Version" + means the combination of the Contributions of others (if any) used + by a Contributor and that particular Contributor's Contribution. + +1.3. "Contribution" + means Covered Software of a particular Contributor. + +1.4. "Covered Software" + means Source Code Form to which the initial Contributor has attached + the notice in Exhibit A, the Executable Form of such Source Code + Form, and Modifications of such Source Code Form, in each case + including portions thereof. + +1.5. "Incompatible With Secondary Licenses" + means + + (a) that the initial Contributor has attached the notice described + in Exhibit B to the Covered Software; or + + (b) that the Covered Software was made available under the terms of + version 1.1 or earlier of the License, but not also under the + terms of a Secondary License. + +1.6. "Executable Form" + means any form of the work other than Source Code Form. + +1.7. "Larger Work" + means a work that combines Covered Software with other material, in + a separate file or files, that is not Covered Software. + +1.8. "License" + means this document. + +1.9. "Licensable" + means having the right to grant, to the maximum extent possible, + whether at the time of the initial grant or subsequently, any and + all of the rights conveyed by this License. + +1.10. "Modifications" + means any of the following: + + (a) any file in Source Code Form that results from an addition to, + deletion from, or modification of the contents of Covered + Software; or + + (b) any new file in Source Code Form that contains any Covered + Software. + +1.11. "Patent Claims" of a Contributor + means any patent claim(s), including without limitation, method, + process, and apparatus claims, in any patent Licensable by such + Contributor that would be infringed, but for the grant of the + License, by the making, using, selling, offering for sale, having + made, import, or transfer of either its Contributions or its + Contributor Version. + +1.12. "Secondary License" + means either the GNU General Public License, Version 2.0, the GNU + Lesser General Public License, Version 2.1, the GNU Affero General + Public License, Version 3.0, or any later versions of those + licenses. + +1.13. "Source Code Form" + means the form of the work preferred for making modifications. + +1.14. "You" (or "Your") + means an individual or a legal entity exercising rights under this + License. For legal entities, "You" includes any entity that + controls, is controlled by, or is under common control with You. For + purposes of this definition, "control" means (a) the power, direct + or indirect, to cause the direction or management of such entity, + whether by contract or otherwise, or (b) ownership of more than + fifty percent (50%) of the outstanding shares or beneficial + ownership of such entity. + +2. License Grants and Conditions +-------------------------------- + +2.1. Grants + +Each Contributor hereby grants You a world-wide, royalty-free, +non-exclusive license: + +(a) under intellectual property rights (other than patent or trademark) + Licensable by such Contributor to use, reproduce, make available, + modify, display, perform, distribute, and otherwise exploit its + Contributions, either on an unmodified basis, with Modifications, or + as part of a Larger Work; and + +(b) under Patent Claims of such Contributor to make, use, sell, offer + for sale, have made, import, and otherwise transfer either its + Contributions or its Contributor Version. + +2.2. Effective Date + +The licenses granted in Section 2.1 with respect to any Contribution +become effective for each Contribution on the date the Contributor first +distributes such Contribution. + +2.3. Limitations on Grant Scope + +The licenses granted in this Section 2 are the only rights granted under +this License. No additional rights or licenses will be implied from the +distribution or licensing of Covered Software under this License. +Notwithstanding Section 2.1(b) above, no patent license is granted by a +Contributor: + +(a) for any code that a Contributor has removed from Covered Software; + or + +(b) for infringements caused by: (i) Your and any other third party's + modifications of Covered Software, or (ii) the combination of its + Contributions with other software (except as part of its Contributor + Version); or + +(c) under Patent Claims infringed by Covered Software in the absence of + its Contributions. + +This License does not grant any rights in the trademarks, service marks, +or logos of any Contributor (except as may be necessary to comply with +the notice requirements in Section 3.4). + +2.4. Subsequent Licenses + +No Contributor makes additional grants as a result of Your choice to +distribute the Covered Software under a subsequent version of this +License (see Section 10.2) or under the terms of a Secondary License (if +permitted under the terms of Section 3.3). + +2.5. Representation + +Each Contributor represents that the Contributor believes its +Contributions are its original creation(s) or it has sufficient rights +to grant the rights to its Contributions conveyed by this License. + +2.6. Fair Use + +This License is not intended to limit any rights You have under +applicable copyright doctrines of fair use, fair dealing, or other +equivalents. + +2.7. Conditions + +Sections 3.1, 3.2, 3.3, and 3.4 are conditions of the licenses granted +in Section 2.1. + +3. Responsibilities +------------------- + +3.1. Distribution of Source Form + +All distribution of Covered Software in Source Code Form, including any +Modifications that You create or to which You contribute, must be under +the terms of this License. You must inform recipients that the Source +Code Form of the Covered Software is governed by the terms of this +License, and how they can obtain a copy of this License. You may not +attempt to alter or restrict the recipients' rights in the Source Code +Form. + +3.2. Distribution of Executable Form + +If You distribute Covered Software in Executable Form then: + +(a) such Covered Software must also be made available in Source Code + Form, as described in Section 3.1, and You must inform recipients of + the Executable Form how they can obtain a copy of such Source Code + Form by reasonable means in a timely manner, at a charge no more + than the cost of distribution to the recipient; and + +(b) You may distribute such Executable Form under the terms of this + License, or sublicense it under different terms, provided that the + license for the Executable Form does not attempt to limit or alter + the recipients' rights in the Source Code Form under this License. + +3.3. Distribution of a Larger Work + +You may create and distribute a Larger Work under terms of Your choice, +provided that You also comply with the requirements of this License for +the Covered Software. If the Larger Work is a combination of Covered +Software with a work governed by one or more Secondary Licenses, and the +Covered Software is not Incompatible With Secondary Licenses, this +License permits You to additionally distribute such Covered Software +under the terms of such Secondary License(s), so that the recipient of +the Larger Work may, at their option, further distribute the Covered +Software under the terms of either this License or such Secondary +License(s). + +3.4. Notices + +You may not remove or alter the substance of any license notices +(including copyright notices, patent notices, disclaimers of warranty, +or limitations of liability) contained within the Source Code Form of +the Covered Software, except that You may alter any license notices to +the extent required to remedy known factual inaccuracies. + +3.5. Application of Additional Terms + +You may choose to offer, and to charge a fee for, warranty, support, +indemnity or liability obligations to one or more recipients of Covered +Software. However, You may do so only on Your own behalf, and not on +behalf of any Contributor. You must make it absolutely clear that any +such warranty, support, indemnity, or liability obligation is offered by +You alone, and You hereby agree to indemnify every Contributor for any +liability incurred by such Contributor as a result of warranty, support, +indemnity or liability terms You offer. You may include additional +disclaimers of warranty and limitations of liability specific to any +jurisdiction. + +4. Inability to Comply Due to Statute or Regulation +--------------------------------------------------- + +If it is impossible for You to comply with any of the terms of this +License with respect to some or all of the Covered Software due to +statute, judicial order, or regulation then You must: (a) comply with +the terms of this License to the maximum extent possible; and (b) +describe the limitations and the code they affect. Such description must +be placed in a text file included with all distributions of the Covered +Software under this License. Except to the extent prohibited by statute +or regulation, such description must be sufficiently detailed for a +recipient of ordinary skill to be able to understand it. + +5. Termination +-------------- + +5.1. The rights granted under this License will terminate automatically +if You fail to comply with any of its terms. However, if You become +compliant, then the rights granted under this License from a particular +Contributor are reinstated (a) provisionally, unless and until such +Contributor explicitly and finally terminates Your grants, and (b) on an +ongoing basis, if such Contributor fails to notify You of the +non-compliance by some reasonable means prior to 60 days after You have +come back into compliance. Moreover, Your grants from a particular +Contributor are reinstated on an ongoing basis if such Contributor +notifies You of the non-compliance by some reasonable means, this is the +first time You have received notice of non-compliance with this License +from such Contributor, and You become compliant prior to 30 days after +Your receipt of the notice. + +5.2. If You initiate litigation against any entity by asserting a patent +infringement claim (excluding declaratory judgment actions, +counter-claims, and cross-claims) alleging that a Contributor Version +directly or indirectly infringes any patent, then the rights granted to +You by any and all Contributors for the Covered Software under Section +2.1 of this License shall terminate. + +5.3. In the event of termination under Sections 5.1 or 5.2 above, all +end user license agreements (excluding distributors and resellers) which +have been validly granted by You or Your distributors under this License +prior to termination shall survive termination. + +************************************************************************ +* * +* 6. Disclaimer of Warranty * +* ------------------------- * +* * +* Covered Software is provided under this License on an "as is" * +* basis, without warranty of any kind, either expressed, implied, or * +* statutory, including, without limitation, warranties that the * +* Covered Software is free of defects, merchantable, fit for a * +* particular purpose or non-infringing. The entire risk as to the * +* quality and performance of the Covered Software is with You. * +* Should any Covered Software prove defective in any respect, You * +* (not any Contributor) assume the cost of any necessary servicing, * +* repair, or correction. This disclaimer of warranty constitutes an * +* essential part of this License. No use of any Covered Software is * +* authorized under this License except under this disclaimer. * +* * +************************************************************************ + +************************************************************************ +* * +* 7. Limitation of Liability * +* -------------------------- * +* * +* Under no circumstances and under no legal theory, whether tort * +* (including negligence), contract, or otherwise, shall any * +* Contributor, or anyone who distributes Covered Software as * +* permitted above, be liable to You for any direct, indirect, * +* special, incidental, or consequential damages of any character * +* including, without limitation, damages for lost profits, loss of * +* goodwill, work stoppage, computer failure or malfunction, or any * +* and all other commercial damages or losses, even if such party * +* shall have been informed of the possibility of such damages. This * +* limitation of liability shall not apply to liability for death or * +* personal injury resulting from such party's negligence to the * +* extent applicable law prohibits such limitation. Some * +* jurisdictions do not allow the exclusion or limitation of * +* incidental or consequential damages, so this exclusion and * +* limitation may not apply to You. * +* * +************************************************************************ + +8. Litigation +------------- + +Any litigation relating to this License may be brought only in the +courts of a jurisdiction where the defendant maintains its principal +place of business and such litigation shall be governed by laws of that +jurisdiction, without reference to its conflict-of-law provisions. +Nothing in this Section shall prevent a party's ability to bring +cross-claims or counter-claims. + +9. Miscellaneous +---------------- + +This License represents the complete agreement concerning the subject +matter hereof. If any provision of this License is held to be +unenforceable, such provision shall be reformed only to the extent +necessary to make it enforceable. Any law or regulation which provides +that the language of a contract shall be construed against the drafter +shall not be used to construe this License against a Contributor. + +10. Versions of the License +--------------------------- + +10.1. New Versions + +Mozilla Foundation is the license steward. Except as provided in Section +10.3, no one other than the license steward has the right to modify or +publish new versions of this License. Each version will be given a +distinguishing version number. + +10.2. Effect of New Versions + +You may distribute the Covered Software under the terms of the version +of the License under which You originally received the Covered Software, +or under the terms of any subsequent version published by the license +steward. + +10.3. Modified Versions + +If you create software not governed by this License, and you want to +create a new license for such software, you may create and use a +modified version of this License if you rename the license and remove +any references to the name of the license steward (except to note that +such modified license differs from this License). + +10.4. Distributing Source Code Form that is Incompatible With Secondary +Licenses + +If You choose to distribute Source Code Form that is Incompatible With +Secondary Licenses under the terms of this version of the License, the +notice described in Exhibit B of this License must be attached. + +Exhibit A - Source Code Form License Notice +------------------------------------------- + + This Source Code Form is subject to the terms of the Mozilla Public + License, v. 2.0. If a copy of the MPL was not distributed with this + file, You can obtain one at https://mozilla.org/MPL/2.0/. + +If it is not possible or desirable to put the notice in a particular +file, then You may include the notice in a location (such as a LICENSE +file in a relevant directory) where a recipient would be likely to look +for such a notice. + +You may add additional accurate notices of copyright ownership. + +Exhibit B - "Incompatible With Secondary Licenses" Notice +--------------------------------------------------------- + + This Source Code Form is "Incompatible With Secondary Licenses", as + defined by the Mozilla Public License, v. 2.0. diff --git a/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/sboms/orjson.cyclonedx.json b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/sboms/orjson.cyclonedx.json new file mode 100644 index 0000000000000000000000000000000000000000..f0f505f5d1bd2c6031df68fa0b4b751e2006715e --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson-3.11.9.dist-info/sboms/orjson.cyclonedx.json @@ -0,0 +1,1079 @@ +{ + "bomFormat": "CycloneDX", + "specVersion": "1.5", + "version": 1, + "serialNumber": "urn:uuid:9e1aa4ea-bad4-44cc-b6e1-483b6748d3f2", + "metadata": { + "timestamp": "2026-05-06T14:56:17.635909202Z", + "tools": [ + { + "vendor": "CycloneDX", + "name": "cargo-cyclonedx", + "version": "0.5.9" + } + ], + "authors": [ + { + "name": "ijl", + "email": "ijl@mailbox.org" + } + ], + "component": { + "type": "library", + "bom-ref": "path+file:///__w/orjson/orjson#3.11.9", + "author": "ijl ", + "name": "orjson", + "version": "3.11.9", + "description": "Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy", + "scope": "required", + "licenses": [ + { + "expression": "MPL-2.0 AND (Apache-2.0 OR MIT)" + } + ], + "purl": "pkg:cargo/orjson@3.11.9?download_url=file://.", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/ijl/orjson" + } + ], + "components": [ + { + "type": "library", + "bom-ref": "path+file:///__w/orjson/orjson#3.11.9 bin-target-0", + "name": "orjson", + "version": "3.11.9", + "purl": "pkg:cargo/orjson@3.11.9?download_url=file://.#src/lib.rs" + } + ] + }, + "properties": [ + { + "name": "cdx:rustc:sbom:target:all_targets", + "value": "true" + } + ] + }, + "components": [ + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#associative-cache@3.0.1", + "author": "Nick Fitzgerald ", + "name": "associative-cache", + "version": "3.0.1", + "description": "A generic N-way associative cache with fixed-size capacity and random or least recently used (LRU) replacement.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "138b4febdc7d0135523c55358c97361fd45089bc65fe859ef21a58d0892deb00" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/associative-cache@3.0.1", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/associative-cache" + }, + { + "type": "vcs", + "url": "https://github.com/fitzgen/associative-cache" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#bytecount@0.6.9", + "author": "Andre Bogus , Joshua Landau ", + "name": "bytecount", + "version": "0.6.9", + "description": "count occurrences of a given byte, or the number of UTF-8 code points, in a byte slice, fast", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "175812e0be2bccb6abe50bb8d566126198344f707e304f45c648fd8f2cc0365e" + } + ], + "licenses": [ + { + "expression": "Apache-2.0 OR MIT" + } + ], + "purl": "pkg:cargo/bytecount@0.6.9", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/llogiq/bytecount" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#bytes@1.11.1", + "author": "Carl Lerche , Sean McArthur ", + "name": "bytes", + "version": "1.11.1", + "description": "Types and traits for working with bytes", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "1e748733b7cbc798e1434b6ac524f0c1ff2ab456fe201501e6497c8417a4fc33" + } + ], + "licenses": [ + { + "expression": "MIT" + } + ], + "purl": "pkg:cargo/bytes@1.11.1", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/tokio-rs/bytes" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#cc@1.2.61", + "author": "Alex Crichton ", + "name": "cc", + "version": "1.2.61", + "description": "A build-time dependency for Cargo build scripts to assist in invoking the native C compiler to compile native C code into a static archive to be linked into Rust code. ", + "scope": "excluded", + "hashes": [ + { + "alg": "SHA-256", + "content": "d16d90359e986641506914ba71350897565610e87ce0ad9e6f28569db3dd5c6d" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/cc@1.2.61", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/cc" + }, + { + "type": "website", + "url": "https://github.com/rust-lang/cc-rs" + }, + { + "type": "vcs", + "url": "https://github.com/rust-lang/cc-rs" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#cfg-if@1.0.4", + "author": "Alex Crichton ", + "name": "cfg-if", + "version": "1.0.4", + "description": "A macro to ergonomically define an item depending on a large number of #[cfg] parameters. Structured like an if-else chain, the first matching branch is the item that gets emitted. ", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "9330f8b2ff13f34540b44e946ef35111825727b38d33286ef986142615121801" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/cfg-if@1.0.4", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/rust-lang/cfg-if" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#encoding_rs@0.8.35", + "author": "Henri Sivonen ", + "name": "encoding_rs", + "version": "0.8.35", + "description": "A Gecko-oriented implementation of the Encoding Standard", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "75030f3c4f45dafd7586dd6780965a8c7e8e285a5ecb86713e63a79c5b2766f3" + } + ], + "licenses": [ + { + "expression": "(Apache-2.0 OR MIT) AND BSD-3-Clause" + } + ], + "purl": "pkg:cargo/encoding_rs@0.8.35", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/encoding_rs/" + }, + { + "type": "website", + "url": "https://docs.rs/encoding_rs/" + }, + { + "type": "vcs", + "url": "https://github.com/hsivonen/encoding_rs" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#find-msvc-tools@0.1.9", + "name": "find-msvc-tools", + "version": "0.1.9", + "description": "Find windows-specific tools, read MSVC versions from the registry and from COM interfaces", + "scope": "excluded", + "hashes": [ + { + "alg": "SHA-256", + "content": "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/find-msvc-tools@0.1.9", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/find-msvc-tools" + }, + { + "type": "vcs", + "url": "https://github.com/rust-lang/cc-rs" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#itoa@1.0.18", + "author": "David Tolnay ", + "name": "itoa", + "version": "1.0.18", + "description": "Fast integer primitive to string conversion", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "8f42a60cbdf9a97f5d2305f08a87dc4e09308d1276d28c869c684d7777685682" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/itoa@1.0.18", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/itoa" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/itoa" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#itoap@1.0.1", + "author": "Ryohei Machida ", + "name": "itoap", + "version": "1.0.1", + "description": "Even faster functions for printing integers with decimal format", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "9028f49264629065d057f340a86acb84867925865f73bbf8d47b4d149a7e88b8" + } + ], + "licenses": [ + { + "expression": "MIT" + } + ], + "purl": "pkg:cargo/itoap@1.0.1", + "externalReferences": [ + { + "type": "website", + "url": "https://github.com/Kogia-sima/itoap" + }, + { + "type": "vcs", + "url": "https://github.com/Kogia-sima/itoap" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#jiff@0.2.24", + "author": "Andrew Gallant ", + "name": "jiff", + "version": "0.2.24", + "description": "A date-time library that encourages you to jump into the pit of success. This library is heavily inspired by the Temporal project. ", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "f00b5dbd620d61dfdcb6007c9c1f6054ebd75319f163d886a9055cec1155073d" + } + ], + "licenses": [ + { + "expression": "Unlicense OR MIT" + } + ], + "purl": "pkg:cargo/jiff@0.2.24", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/jiff" + }, + { + "type": "vcs", + "url": "https://github.com/BurntSushi/jiff" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#libc@0.2.186", + "author": "The Rust Project Developers", + "name": "libc", + "version": "0.2.186", + "description": "Raw FFI bindings to platform libraries like libc.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "68ab91017fe16c622486840e4c83c9a37afeff978bd239b5293d61ece587de66" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/libc@0.2.186", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/rust-lang/libc" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#memchr@2.8.0", + "author": "Andrew Gallant , bluss", + "name": "memchr", + "version": "2.8.0", + "description": "Provides extremely fast (uses SIMD on x86_64, aarch64 and wasm32) routines for 1, 2 or 3 byte search and single substring search. ", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "f8ca58f447f06ed17d5fc4043ce1b10dd205e060fb3ce5b979b8ed8e59ff3f79" + } + ], + "licenses": [ + { + "expression": "Unlicense OR MIT" + } + ], + "purl": "pkg:cargo/memchr@2.8.0", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/memchr/" + }, + { + "type": "website", + "url": "https://github.com/BurntSushi/memchr" + }, + { + "type": "vcs", + "url": "https://github.com/BurntSushi/memchr" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#no-panic@0.1.36", + "author": "David Tolnay ", + "name": "no-panic", + "version": "0.1.36", + "description": "Attribute macro to require that the compiler prove a function can't ever panic.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "f967505aabc8af5752d098c34146544a43684817cdba8f9725b292530cabbf53" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/no-panic@0.1.36", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/no-panic" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/no-panic" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#once_cell@1.21.4", + "author": "Aleksey Kladov ", + "name": "once_cell", + "version": "1.21.4", + "description": "Single assignment cells and lazy values.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/once_cell@1.21.4", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/once_cell" + }, + { + "type": "vcs", + "url": "https://github.com/matklad/once_cell" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#proc-macro2@1.0.106", + "author": "David Tolnay , Alex Crichton ", + "name": "proc-macro2", + "version": "1.0.106", + "description": "A substitute implementation of the compiler's `proc_macro` API to decouple token-based libraries from the procedural macro use case.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "8fd00f0bb2e90d81d1044c2b32617f68fcb9fa3bb7640c23e9c748e53fb30934" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/proc-macro2@1.0.106", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/proc-macro2" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/proc-macro2" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#pyo3-build-config@0.28.3", + "author": "PyO3 Project and Contributors ", + "name": "pyo3-build-config", + "version": "0.28.3", + "description": "Build configuration for the PyO3 ecosystem", + "scope": "excluded", + "hashes": [ + { + "alg": "SHA-256", + "content": "e368e7ddfdeb98c9bca7f8383be1648fd84ab466bf2bc015e94008db6d35611e" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/pyo3-build-config@0.28.3", + "externalReferences": [ + { + "type": "website", + "url": "https://github.com/pyo3/pyo3" + }, + { + "type": "vcs", + "url": "https://github.com/pyo3/pyo3" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#pyo3-ffi@0.28.3", + "author": "PyO3 Project and Contributors ", + "name": "pyo3-ffi", + "version": "0.28.3", + "description": "Python-API bindings for the PyO3 ecosystem", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "7f29e10af80b1f7ccaf7f69eace800a03ecd13e883acfacc1e5d0988605f651e" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/pyo3-ffi@0.28.3", + "externalReferences": [ + { + "type": "website", + "url": "https://github.com/pyo3/pyo3" + }, + { + "type": "other", + "url": "python" + }, + { + "type": "vcs", + "url": "https://github.com/pyo3/pyo3" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#quote@1.0.45", + "author": "David Tolnay ", + "name": "quote", + "version": "1.0.45", + "description": "Quasi-quoting macro quote!(...)", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "41f2619966050689382d2b44f664f4bc593e129785a36d6ee376ddf37259b924" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/quote@1.0.45", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/quote/" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/quote" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#serde@1.0.228", + "author": "Erick Tryzelaar , David Tolnay ", + "name": "serde", + "version": "1.0.228", + "description": "A generic serialization/deserialization framework", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "9a8e94ea7f378bd32cbbd37198a4a91436180c5bb472411e48b5ec2e2124ae9e" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/serde@1.0.228", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/serde" + }, + { + "type": "website", + "url": "https://serde.rs" + }, + { + "type": "vcs", + "url": "https://github.com/serde-rs/serde" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#serde_core@1.0.228", + "author": "Erick Tryzelaar , David Tolnay ", + "name": "serde_core", + "version": "1.0.228", + "description": "Serde traits only, with no support for derive -- use the `serde` crate instead", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "41d385c7d4ca58e59fc732af25c3983b67ac852c1a25000afe1175de458b67ad" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/serde_core@1.0.228", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/serde_core" + }, + { + "type": "website", + "url": "https://serde.rs" + }, + { + "type": "vcs", + "url": "https://github.com/serde-rs/serde" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#serde_json@1.0.149", + "author": "Erick Tryzelaar , David Tolnay ", + "name": "serde_json", + "version": "1.0.149", + "description": "A JSON serialization file format", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "83fc039473c5595ace860d8c4fafa220ff474b3fc6bfdb4293327f1a37e94d86" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/serde_json@1.0.149", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/serde_json" + }, + { + "type": "vcs", + "url": "https://github.com/serde-rs/json" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#shlex@1.3.0", + "author": "comex , Fenhl , Adrian Taylor , Alex Touchet , Daniel Parks , Garrett Berg ", + "name": "shlex", + "version": "1.3.0", + "description": "Split a string into shell words, like Python's shlex.", + "scope": "excluded", + "hashes": [ + { + "alg": "SHA-256", + "content": "0fda2ff0d084019ba4d7c6f371c95d8fd75ce3524c3cb8fb653a3023f6323e64" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/shlex@1.3.0", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/comex/rust-shlex" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#simdutf8@0.1.5", + "author": "Hans Kratz ", + "name": "simdutf8", + "version": "0.1.5", + "description": "SIMD-accelerated UTF-8 validation.", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "e3a9fe34e3e7a50316060351f37187a3f546bce95496156754b601a5fa71b76e" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/simdutf8@0.1.5", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/simdutf8/" + }, + { + "type": "website", + "url": "https://github.com/rusticstuff/simdutf8" + }, + { + "type": "vcs", + "url": "https://github.com/rusticstuff/simdutf8" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#syn@2.0.117", + "author": "David Tolnay ", + "name": "syn", + "version": "2.0.117", + "description": "Parser for Rust source code", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "e665b8803e7b1d2a727f4023456bbbbe74da67099c585258af0ad9c5013b9b99" + } + ], + "licenses": [ + { + "expression": "MIT OR Apache-2.0" + } + ], + "purl": "pkg:cargo/syn@2.0.117", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/syn" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/syn" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#target-lexicon@0.13.5", + "author": "Dan Gohman ", + "name": "target-lexicon", + "version": "0.13.5", + "description": "LLVM target triple types", + "scope": "excluded", + "hashes": [ + { + "alg": "SHA-256", + "content": "adb6935a6f5c20170eeceb1a3835a49e12e19d792f6dd344ccc76a985ca5a6ca" + } + ], + "licenses": [ + { + "expression": "Apache-2.0 WITH LLVM-exception" + } + ], + "purl": "pkg:cargo/target-lexicon@0.13.5", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/target-lexicon/" + }, + { + "type": "vcs", + "url": "https://github.com/bytecodealliance/target-lexicon" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#unicode-ident@1.0.24", + "author": "David Tolnay ", + "name": "unicode-ident", + "version": "1.0.24", + "description": "Determine whether characters have the XID_Start or XID_Continue properties according to Unicode Standard Annex #31", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "e6e4313cd5fcd3dad5cafa179702e2b244f760991f45397d14d4ebf38247da75" + } + ], + "licenses": [ + { + "expression": "(MIT OR Apache-2.0) AND Unicode-3.0" + } + ], + "purl": "pkg:cargo/unicode-ident@1.0.24", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/unicode-ident" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/unicode-ident" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#xxhash-rust@0.8.15", + "author": "Douman ", + "name": "xxhash-rust", + "version": "0.8.15", + "description": "Implementation of xxhash", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "fdd20c5420375476fbd4394763288da7eb0cc0b8c11deed431a91562af7335d3" + } + ], + "licenses": [ + { + "expression": "BSL-1.0" + } + ], + "purl": "pkg:cargo/xxhash-rust@0.8.15", + "externalReferences": [ + { + "type": "vcs", + "url": "https://github.com/DoumanAsh/xxhash-rust" + } + ] + }, + { + "type": "library", + "bom-ref": "registry+https://github.com/rust-lang/crates.io-index#zmij@1.0.21", + "author": "David Tolnay ", + "name": "zmij", + "version": "1.0.21", + "description": "A double-to-string conversion algorithm based on Schubfach and yy", + "scope": "required", + "hashes": [ + { + "alg": "SHA-256", + "content": "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" + } + ], + "licenses": [ + { + "expression": "MIT" + } + ], + "purl": "pkg:cargo/zmij@1.0.21", + "externalReferences": [ + { + "type": "documentation", + "url": "https://docs.rs/zmij" + }, + { + "type": "vcs", + "url": "https://github.com/dtolnay/zmij" + } + ] + } + ], + "dependencies": [ + { + "ref": "path+file:///__w/orjson/orjson#3.11.9", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#associative-cache@3.0.1", + "registry+https://github.com/rust-lang/crates.io-index#bytecount@0.6.9", + "registry+https://github.com/rust-lang/crates.io-index#bytes@1.11.1", + "registry+https://github.com/rust-lang/crates.io-index#cc@1.2.61", + "registry+https://github.com/rust-lang/crates.io-index#encoding_rs@0.8.35", + "registry+https://github.com/rust-lang/crates.io-index#itoap@1.0.1", + "registry+https://github.com/rust-lang/crates.io-index#jiff@0.2.24", + "registry+https://github.com/rust-lang/crates.io-index#once_cell@1.21.4", + "registry+https://github.com/rust-lang/crates.io-index#pyo3-build-config@0.28.3", + "registry+https://github.com/rust-lang/crates.io-index#pyo3-ffi@0.28.3", + "registry+https://github.com/rust-lang/crates.io-index#serde@1.0.228", + "registry+https://github.com/rust-lang/crates.io-index#serde_json@1.0.149", + "registry+https://github.com/rust-lang/crates.io-index#simdutf8@0.1.5", + "registry+https://github.com/rust-lang/crates.io-index#xxhash-rust@0.8.15", + "registry+https://github.com/rust-lang/crates.io-index#zmij@1.0.21" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#associative-cache@3.0.1" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#bytecount@0.6.9" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#bytes@1.11.1" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#cc@1.2.61", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#find-msvc-tools@0.1.9", + "registry+https://github.com/rust-lang/crates.io-index#shlex@1.3.0" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#cfg-if@1.0.4" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#encoding_rs@0.8.35", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#cfg-if@1.0.4" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#find-msvc-tools@0.1.9" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#itoa@1.0.18" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#itoap@1.0.1" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#jiff@0.2.24" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#libc@0.2.186" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#memchr@2.8.0" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#no-panic@0.1.36", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#proc-macro2@1.0.106", + "registry+https://github.com/rust-lang/crates.io-index#quote@1.0.45", + "registry+https://github.com/rust-lang/crates.io-index#syn@2.0.117" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#once_cell@1.21.4" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#proc-macro2@1.0.106", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#unicode-ident@1.0.24" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#pyo3-build-config@0.28.3", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#target-lexicon@0.13.5" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#pyo3-ffi@0.28.3", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#libc@0.2.186", + "registry+https://github.com/rust-lang/crates.io-index#pyo3-build-config@0.28.3" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#quote@1.0.45", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#proc-macro2@1.0.106" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#serde@1.0.228", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#serde_core@1.0.228" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#serde_core@1.0.228" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#serde_json@1.0.149", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#itoa@1.0.18", + "registry+https://github.com/rust-lang/crates.io-index#memchr@2.8.0", + "registry+https://github.com/rust-lang/crates.io-index#serde_core@1.0.228", + "registry+https://github.com/rust-lang/crates.io-index#zmij@1.0.21" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#shlex@1.3.0" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#simdutf8@0.1.5" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#syn@2.0.117", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#proc-macro2@1.0.106", + "registry+https://github.com/rust-lang/crates.io-index#quote@1.0.45", + "registry+https://github.com/rust-lang/crates.io-index#unicode-ident@1.0.24" + ] + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#target-lexicon@0.13.5" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#unicode-ident@1.0.24" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#xxhash-rust@0.8.15" + }, + { + "ref": "registry+https://github.com/rust-lang/crates.io-index#zmij@1.0.21", + "dependsOn": [ + "registry+https://github.com/rust-lang/crates.io-index#no-panic@0.1.36" + ] + } + ] +} \ No newline at end of file diff --git a/.venv/lib/python3.13/site-packages/orjson/__init__.py b/.venv/lib/python3.13/site-packages/orjson/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..c6a12ab65c6e434dbcf11a055cf271a946501250 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson/__init__.py @@ -0,0 +1,32 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright ijl (2023-2026) + +""" +Fast, correct Python JSON library supporting dataclasses, datetimes, and numpy +""" + +from .orjson import * +from .orjson import __version__ + +__all__ = ( + "__version__", + "dumps", + "Fragment", + "JSONDecodeError", + "JSONEncodeError", + "loads", + "OPT_APPEND_NEWLINE", + "OPT_INDENT_2", + "OPT_NAIVE_UTC", + "OPT_NON_STR_KEYS", + "OPT_OMIT_MICROSECONDS", + "OPT_PASSTHROUGH_DATACLASS", + "OPT_PASSTHROUGH_DATETIME", + "OPT_PASSTHROUGH_SUBCLASS", + "OPT_SERIALIZE_DATACLASS", + "OPT_SERIALIZE_NUMPY", + "OPT_SERIALIZE_UUID", + "OPT_SORT_KEYS", + "OPT_STRICT_INTEGER", + "OPT_UTC_Z", +) diff --git a/.venv/lib/python3.13/site-packages/orjson/__init__.pyi b/.venv/lib/python3.13/site-packages/orjson/__init__.pyi new file mode 100644 index 0000000000000000000000000000000000000000..9804cee53a5248f62bba23d7c3d07a151c701ff4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson/__init__.pyi @@ -0,0 +1,36 @@ +# SPDX-License-Identifier: (Apache-2.0 OR MIT) +# Copyright ijl (2019-2026), Eric Jolibois (2022), Anders Kaseorg (2020) + +import json +from collections.abc import Callable +from typing import Any + +__version__: str + +def dumps( + __obj: Any, + default: Callable[[Any], Any] | None = ..., + option: int | None = ..., +) -> bytes: ... +def loads(__obj: bytes | bytearray | memoryview | str) -> Any: ... + +class JSONDecodeError(json.JSONDecodeError): ... +class JSONEncodeError(TypeError): ... + +class Fragment(tuple): + contents: bytes | str + +OPT_APPEND_NEWLINE: int +OPT_INDENT_2: int +OPT_NAIVE_UTC: int +OPT_NON_STR_KEYS: int +OPT_OMIT_MICROSECONDS: int +OPT_PASSTHROUGH_DATACLASS: int +OPT_PASSTHROUGH_DATETIME: int +OPT_PASSTHROUGH_SUBCLASS: int +OPT_SERIALIZE_DATACLASS: int +OPT_SERIALIZE_NUMPY: int +OPT_SERIALIZE_UUID: int +OPT_SORT_KEYS: int +OPT_STRICT_INTEGER: int +OPT_UTC_Z: int diff --git a/.venv/lib/python3.13/site-packages/orjson/orjson.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/orjson/orjson.cpython-313-x86_64-linux-gnu.so new file mode 100644 index 0000000000000000000000000000000000000000..46fa60feef5ec84a61a740ebdc2fb42d973ab93d --- /dev/null +++ b/.venv/lib/python3.13/site-packages/orjson/orjson.cpython-313-x86_64-linux-gnu.so @@ -0,0 +1,3 @@ +version https://git-lfs.github.com/spec/v1 +oid sha256:f42c7014473fa0b7eb732fe1653c78c79c3954288812a47f6ca8f74c2b332a3e +size 246184 diff --git a/.venv/lib/python3.13/site-packages/orjson/py.typed b/.venv/lib/python3.13/site-packages/orjson/py.typed new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/INSTALLER b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/INSTALLER new file mode 100644 index 0000000000000000000000000000000000000000..a1b589e38a32041e49332e5e81c2d363dc418d68 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/INSTALLER @@ -0,0 +1 @@ +pip diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/METADATA b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/METADATA new file mode 100644 index 0000000000000000000000000000000000000000..d7ca45662842ba99c3ecaf0c6771029f4afef966 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/METADATA @@ -0,0 +1,112 @@ +Metadata-Version: 2.4 +Name: packaging +Version: 26.2 +Summary: Core utilities for Python packages +Author-email: Donald Stufft +Requires-Python: >=3.8 +Description-Content-Type: text/x-rst +License-Expression: Apache-2.0 OR BSD-2-Clause +Classifier: Development Status :: 5 - Production/Stable +Classifier: Intended Audience :: Developers +Classifier: Programming Language :: Python +Classifier: Programming Language :: Python :: 3 +Classifier: Programming Language :: Python :: 3 :: Only +Classifier: Programming Language :: Python :: 3.8 +Classifier: Programming Language :: Python :: 3.9 +Classifier: Programming Language :: Python :: 3.10 +Classifier: Programming Language :: Python :: 3.11 +Classifier: Programming Language :: Python :: 3.12 +Classifier: Programming Language :: Python :: 3.13 +Classifier: Programming Language :: Python :: 3.14 +Classifier: Programming Language :: Python :: Implementation :: CPython +Classifier: Programming Language :: Python :: Implementation :: PyPy +Classifier: Programming Language :: Python :: Free Threading :: 4 - Resilient +Classifier: Typing :: Typed +License-File: LICENSE +License-File: LICENSE.APACHE +License-File: LICENSE.BSD +Project-URL: Documentation, https://packaging.pypa.io/ +Project-URL: Source, https://github.com/pypa/packaging + +packaging +========= + +.. start-intro + +Reusable core utilities for various Python Packaging +`interoperability specifications `_. + +This library provides utilities that implement the interoperability +specifications which have clearly one correct behaviour (eg: :pep:`440`) +or benefit greatly from having a single shared implementation (eg: :pep:`425`). + +.. end-intro + +The ``packaging`` project includes the following: version handling, specifiers, +markers, requirements, tags, metadata, lockfiles, utilities. + +Documentation +------------- + +The `documentation`_ provides information and the API for the following: + +- Version Handling +- Specifiers +- Markers +- Licenses +- Requirements +- Metadata +- Tags +- Lockfiles (pylock) +- Direct URL helpers +- Dependency groups +- Errors +- Utilities + +Installation +------------ + +Use ``pip`` to install these utilities:: + + pip install packaging + +The ``packaging`` library uses calendar-based versioning (``YY.N``). + +Discussion +---------- + +If you run into bugs, you can file them in our `issue tracker`_. + +You can also join discussions on `GitHub Discussions`_ to ask questions or get involved. + +.. _`documentation`: https://packaging.pypa.io/ +.. _`issue tracker`: https://github.com/pypa/packaging/issues +.. _`GitHub Discussions`: https://github.com/pypa/packaging/discussions + + +Code of Conduct +--------------- + +Everyone interacting in the packaging project's codebases, issue trackers, chat +rooms, and mailing lists is expected to follow the `PSF Code of Conduct`_. + +.. _PSF Code of Conduct: https://github.com/pypa/.github/blob/main/CODE_OF_CONDUCT.md + +Contributing +------------ + +The ``CONTRIBUTING.rst`` file outlines how to contribute to this project as +well as how to report a potential security issue. The documentation for this +project also covers information about `project development`_ and `security`_. + +.. _`project development`: https://packaging.pypa.io/en/latest/development/ +.. _`security`: https://packaging.pypa.io/en/latest/security/ + +Project History +--------------- + +Please review the ``CHANGELOG.rst`` file or the `Changelog documentation`_ for +recent changes and project history. + +.. _`Changelog documentation`: https://packaging.pypa.io/en/latest/changelog/ + diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/RECORD b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/RECORD new file mode 100644 index 0000000000000000000000000000000000000000..f16d2dbc4e32086e3affcaacd48118d4e7d4feab --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/RECORD @@ -0,0 +1,48 @@ +packaging-26.2.dist-info/INSTALLER,sha256=zuuue4knoyJ-UwPPXg8fezS7VCrXJQrAP7zeNuwvFQg,4 +packaging-26.2.dist-info/METADATA,sha256=T5y815M0FaR5P3dnyYoralEsgj_IHIczeBVwXyMOyr8,3543 +packaging-26.2.dist-info/RECORD,, +packaging-26.2.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82 +packaging-26.2.dist-info/licenses/LICENSE,sha256=ytHvW9NA1z4HS6YU0m996spceUDD2MNIUuZcSQlobEg,197 +packaging-26.2.dist-info/licenses/LICENSE.APACHE,sha256=DVQuDIgE45qn836wDaWnYhSdxoLXgpRRKH4RuTjpRZQ,10174 +packaging-26.2.dist-info/licenses/LICENSE.BSD,sha256=tw5-m3QvHMb5SLNMFqo5_-zpQZY2S8iP8NIYDwAo-sU,1344 +packaging/__init__.py,sha256=QhMEdPu2XogrJzV3S0KWS6t7l0I9k8EeDRJl4fnw87s,494 +packaging/__pycache__/__init__.cpython-313.pyc,, +packaging/__pycache__/_elffile.cpython-313.pyc,, +packaging/__pycache__/_manylinux.cpython-313.pyc,, +packaging/__pycache__/_musllinux.cpython-313.pyc,, +packaging/__pycache__/_parser.cpython-313.pyc,, +packaging/__pycache__/_structures.cpython-313.pyc,, +packaging/__pycache__/_tokenizer.cpython-313.pyc,, +packaging/__pycache__/dependency_groups.cpython-313.pyc,, +packaging/__pycache__/direct_url.cpython-313.pyc,, +packaging/__pycache__/errors.cpython-313.pyc,, +packaging/__pycache__/markers.cpython-313.pyc,, +packaging/__pycache__/metadata.cpython-313.pyc,, +packaging/__pycache__/pylock.cpython-313.pyc,, +packaging/__pycache__/requirements.cpython-313.pyc,, +packaging/__pycache__/specifiers.cpython-313.pyc,, +packaging/__pycache__/tags.cpython-313.pyc,, +packaging/__pycache__/utils.cpython-313.pyc,, +packaging/__pycache__/version.cpython-313.pyc,, +packaging/_elffile.py,sha256=-sKkptYqzYw2-x3QByJa5mB4rfPWu1pxkZHRx1WAFCY,3211 +packaging/_manylinux.py,sha256=Hf6nB0cOrayEs96-p3oIXAgGnFquv20DO5l-o2_Xnv0,9559 +packaging/_musllinux.py,sha256=Z6swjH3MA7XS3qXnmMN7QPhqP3fnoYI0eQ18e9-HgAE,2707 +packaging/_parser.py,sha256=Kf2nsDw4c54X82pY8ba4F02Bve6OygGMAjL-Begqcew,11698 +packaging/_structures.py,sha256=60jRbF78p8z5MKnNd6cAprgOadCJHV0DlmUmRBqFZcs,1109 +packaging/_tokenizer.py,sha256=tFU2Wr-ZZJdAbkXLEJo7qUQDJaIkfft9DqaifiEND7A,5391 +packaging/dependency_groups.py,sha256=XZIAVFK9uHG4RCGprmJn3VInUWMesxha_kytJuMO9eY,10218 +packaging/direct_url.py,sha256=eKmbDiPP1sLV4Mj_kCSZqqknrIyVO9Sr7JpF8KCjp4U,10917 +packaging/errors.py,sha256=6hfEYXAf8v_IF65-lFadJOMIieBP2xIKtyEXjG1nGIs,2680 +packaging/licenses/__init__.py,sha256=_Jx0XRiD_58palsWnyLrLuh59ZpGCPIPXLKdZo9OJvQ,7293 +packaging/licenses/__pycache__/__init__.cpython-313.pyc,, +packaging/licenses/__pycache__/_spdx.cpython-313.pyc,, +packaging/licenses/_spdx.py,sha256=WW7DXiyg68up_YND_wpRYlr1SHhiV4FfJLQffghhMxQ,51122 +packaging/markers.py,sha256=8fDIUhAF6YMnCNB5FSiwh9pEIusiFzAF73J-0OB8bTk,17055 +packaging/metadata.py,sha256=crAh0E3GVGVqPlu6EdRFsaG-Y6UYznTUqjuGKRGPv6c,38770 +packaging/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0 +packaging/pylock.py,sha256=G_1gncTmDbRLY1jo4VDI9Uw-b5IErh_Q9V_BbVJTmD8,33890 +packaging/requirements.py,sha256=dd1c9aa1gp5NI6btF6UFRQjPn1nxQXnE_T34yDDTEpc,4383 +packaging/specifiers.py,sha256=Mfp8avQg0lVot17to9lVKBtZD1FsWBTItoGwFUZ3wtg,71514 +packaging/tags.py,sha256=NQ1weo69_Sjte3xBZ1I_G63CIgCmaN0C24mz-z3hGYo,34224 +packaging/utils.py,sha256=M7-JMKic2sP1YtV_8aW7eVGB-x3ADuKCiSrsVeCd2Uo,9848 +packaging/version.py,sha256=Y1aTtxe3sn2xOMa5BdI85-AcHuybbanOVkEvvSRRC8I,38369 diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/WHEEL b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/WHEEL new file mode 100644 index 0000000000000000000000000000000000000000..d8b9936dad9ab2513fa6979f411560d3b6b57e37 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/WHEEL @@ -0,0 +1,4 @@ +Wheel-Version: 1.0 +Generator: flit 3.12.0 +Root-Is-Purelib: true +Tag: py3-none-any diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE new file mode 100644 index 0000000000000000000000000000000000000000..6f62d44e4ef733c0e713afcd2371fed7f2b3de67 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE @@ -0,0 +1,3 @@ +This software is made available under the terms of *either* of the licenses +found in LICENSE.APACHE or LICENSE.BSD. Contributions to this software is made +under the terms of *both* these licenses. diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.APACHE b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.APACHE new file mode 100644 index 0000000000000000000000000000000000000000..f433b1a53f5b830a205fd2df78e2b34974656c7b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.APACHE @@ -0,0 +1,177 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS diff --git a/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.BSD b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.BSD new file mode 100644 index 0000000000000000000000000000000000000000..42ce7b75c92fb01a3f6ed17eea363f756b7da582 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging-26.2.dist-info/licenses/LICENSE.BSD @@ -0,0 +1,23 @@ +Copyright (c) Donald Stufft and individual contributors. +All rights reserved. + +Redistribution and use in source and binary forms, with or without +modification, are permitted provided that the following conditions are met: + + 1. Redistributions of source code must retain the above copyright notice, + this list of conditions and the following disclaimer. + + 2. Redistributions in binary form must reproduce the above copyright + notice, this list of conditions and the following disclaimer in the + documentation and/or other materials provided with the distribution. + +THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND +ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED +WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE +DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE +FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR +SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER +CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, +OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE +OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. diff --git a/.venv/lib/python3.13/site-packages/packaging/__init__.py b/.venv/lib/python3.13/site-packages/packaging/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..a6bdf59cd713d41593ba3da47032a831a1be1504 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/__init__.py @@ -0,0 +1,15 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +__title__ = "packaging" +__summary__ = "Core utilities for Python packages" +__uri__ = "https://github.com/pypa/packaging" + +__version__ = "26.2" + +__author__ = "Donald Stufft and individual contributors" +__email__ = "donald@stufft.io" + +__license__ = "BSD-2-Clause or Apache-2.0" +__copyright__ = f"2014 {__author__}" diff --git a/.venv/lib/python3.13/site-packages/packaging/_elffile.py b/.venv/lib/python3.13/site-packages/packaging/_elffile.py new file mode 100644 index 0000000000000000000000000000000000000000..497b0645217512ae2ba8ff61341fd2bbfa3648cd --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_elffile.py @@ -0,0 +1,108 @@ +""" +ELF file parser. + +This provides a class ``ELFFile`` that parses an ELF executable in a similar +interface to ``ZipFile``. Only the read interface is implemented. + +ELF header: https://refspecs.linuxfoundation.org/elf/gabi4+/ch4.eheader.html +""" + +from __future__ import annotations + +import enum +import os +import struct +from typing import IO + + +class ELFInvalid(ValueError): + pass + + +class EIClass(enum.IntEnum): + C32 = 1 + C64 = 2 + + +class EIData(enum.IntEnum): + Lsb = 1 + Msb = 2 + + +class EMachine(enum.IntEnum): + I386 = 3 + S390 = 22 + Arm = 40 + X8664 = 62 + AArc64 = 183 + + +class ELFFile: + """ + Representation of an ELF executable. + """ + + def __init__(self, f: IO[bytes]) -> None: + self._f = f + + try: + ident = self._read("16B") + except struct.error as e: + raise ELFInvalid("unable to parse identification") from e + magic = bytes(ident[:4]) + if magic != b"\x7fELF": + raise ELFInvalid(f"invalid magic: {magic!r}") + + self.capacity = ident[4] # Format for program header (bitness). + self.encoding = ident[5] # Data structure encoding (endianness). + + try: + # e_fmt: Format for program header. + # p_fmt: Format for section header. + # p_idx: Indexes to find p_type, p_offset, and p_filesz. + e_fmt, self._p_fmt, self._p_idx = { + (1, 1): ("HHIIIIIHHH", ">IIIIIIII", (0, 1, 4)), # 32-bit MSB. + (2, 1): ("HHIQQQIHHH", ">IIQQQQQQ", (0, 2, 5)), # 64-bit MSB. + }[(self.capacity, self.encoding)] + except KeyError as e: + raise ELFInvalid( + f"unrecognized capacity ({self.capacity}) or encoding ({self.encoding})" + ) from e + + try: + ( + _, + self.machine, # Architecture type. + _, + _, + self._e_phoff, # Offset of program header. + _, + self.flags, # Processor-specific flags. + _, + self._e_phentsize, # Size of section. + self._e_phnum, # Number of sections. + ) = self._read(e_fmt) + except struct.error as e: + raise ELFInvalid("unable to parse machine and section information") from e + + def _read(self, fmt: str) -> tuple[int, ...]: + return struct.unpack(fmt, self._f.read(struct.calcsize(fmt))) + + @property + def interpreter(self) -> str | None: + """ + The path recorded in the ``PT_INTERP`` section header. + """ + for index in range(self._e_phnum): + self._f.seek(self._e_phoff + self._e_phentsize * index) + try: + data = self._read(self._p_fmt) + except struct.error: + continue + if data[self._p_idx[0]] != 3: # Not PT_INTERP. + continue + self._f.seek(data[self._p_idx[1]]) + return os.fsdecode(self._f.read(data[self._p_idx[2]])).strip("\0") + return None diff --git a/.venv/lib/python3.13/site-packages/packaging/_manylinux.py b/.venv/lib/python3.13/site-packages/packaging/_manylinux.py new file mode 100644 index 0000000000000000000000000000000000000000..0e79e8a882be74fe76c80ccf49a9cd68fb636fd4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_manylinux.py @@ -0,0 +1,262 @@ +from __future__ import annotations + +import collections +import contextlib +import functools +import os +import re +import sys +import warnings +from typing import Generator, Iterator, NamedTuple, Sequence + +from ._elffile import EIClass, EIData, ELFFile, EMachine + +EF_ARM_ABIMASK = 0xFF000000 +EF_ARM_ABI_VER5 = 0x05000000 +EF_ARM_ABI_FLOAT_HARD = 0x00000400 + +_ALLOWED_ARCHS = { + "x86_64", + "aarch64", + "ppc64", + "ppc64le", + "s390x", + "loongarch64", + "riscv64", +} + + +# `os.PathLike` not a generic type until Python 3.9, so sticking with `str` +# as the type for `path` until then. +@contextlib.contextmanager +def _parse_elf(path: str) -> Generator[ELFFile | None, None, None]: + try: + with open(path, "rb") as f: + yield ELFFile(f) + except (OSError, TypeError, ValueError): + yield None + + +def _is_linux_armhf(executable: str) -> bool: + # hard-float ABI can be detected from the ELF header of the running + # process + # https://static.docs.arm.com/ihi0044/g/aaelf32.pdf + with _parse_elf(executable) as f: + return ( + f is not None + and f.capacity == EIClass.C32 + and f.encoding == EIData.Lsb + and f.machine == EMachine.Arm + and f.flags & EF_ARM_ABIMASK == EF_ARM_ABI_VER5 + and f.flags & EF_ARM_ABI_FLOAT_HARD == EF_ARM_ABI_FLOAT_HARD + ) + + +def _is_linux_i686(executable: str) -> bool: + with _parse_elf(executable) as f: + return ( + f is not None + and f.capacity == EIClass.C32 + and f.encoding == EIData.Lsb + and f.machine == EMachine.I386 + ) + + +def _have_compatible_abi(executable: str, archs: Sequence[str]) -> bool: + if "armv7l" in archs: + return _is_linux_armhf(executable) + if "i686" in archs: + return _is_linux_i686(executable) + return any(arch in _ALLOWED_ARCHS for arch in archs) + + +# If glibc ever changes its major version, we need to know what the last +# minor version was, so we can build the complete list of all versions. +# For now, guess what the highest minor version might be, assume it will +# be 50 for testing. Once this actually happens, update the dictionary +# with the actual value. +_LAST_GLIBC_MINOR: dict[int, int] = collections.defaultdict(lambda: 50) + + +class _GLibCVersion(NamedTuple): + major: int + minor: int + + +def _glibc_version_string_confstr() -> str | None: + """ + Primary implementation of glibc_version_string using os.confstr. + """ + # os.confstr is quite a bit faster than ctypes.DLL. It's also less likely + # to be broken or missing. This strategy is used in the standard library + # platform module. + # https://github.com/python/cpython/blob/fcf1d003bf4f0100c/Lib/platform.py#L175-L183 + try: + # Should be a string like "glibc 2.17". + version_string: str | None = os.confstr("CS_GNU_LIBC_VERSION") + assert version_string is not None + _, version = version_string.rsplit() + except (AssertionError, AttributeError, OSError, ValueError): + # os.confstr() or CS_GNU_LIBC_VERSION not available (or a bad value)... + return None + return version + + +def _glibc_version_string_ctypes() -> str | None: + """ + Fallback implementation of glibc_version_string using ctypes. + """ + try: + import ctypes # noqa: PLC0415 + except ImportError: + return None + + # ctypes.CDLL(None) internally calls dlopen(NULL), and as the dlopen + # manpage says, "If filename is NULL, then the returned handle is for the + # main program". This way we can let the linker do the work to figure out + # which libc our process is actually using. + # + # We must also handle the special case where the executable is not a + # dynamically linked executable. This can occur when using musl libc, + # for example. In this situation, dlopen() will error, leading to an + # OSError. Interestingly, at least in the case of musl, there is no + # errno set on the OSError. The single string argument used to construct + # OSError comes from libc itself and is therefore not portable to + # hard code here. In any case, failure to call dlopen() means we + # can proceed, so we bail on our attempt. + try: + process_namespace = ctypes.CDLL(None) + except OSError: + return None + + try: + gnu_get_libc_version = process_namespace.gnu_get_libc_version + except AttributeError: + # Symbol doesn't exist -> therefore, we are not linked to + # glibc. + return None + + # Call gnu_get_libc_version, which returns a string like "2.5" + gnu_get_libc_version.restype = ctypes.c_char_p + version_str: str = gnu_get_libc_version() + # py2 / py3 compatibility: + if not isinstance(version_str, str): + version_str = version_str.decode("ascii") + + return version_str + + +def _glibc_version_string() -> str | None: + """Returns glibc version string, or None if not using glibc.""" + return _glibc_version_string_confstr() or _glibc_version_string_ctypes() + + +def _parse_glibc_version(version_str: str) -> _GLibCVersion: + """Parse glibc version. + + We use a regexp instead of str.split because we want to discard any + random junk that might come after the minor version -- this might happen + in patched/forked versions of glibc (e.g. Linaro's version of glibc + uses version strings like "2.20-2014.11"). See gh-3588. + """ + m = re.match(r"(?P[0-9]+)\.(?P[0-9]+)", version_str) + if not m: + warnings.warn( + f"Expected glibc version with 2 components major.minor, got: {version_str}", + RuntimeWarning, + stacklevel=2, + ) + return _GLibCVersion(-1, -1) + return _GLibCVersion(int(m.group("major")), int(m.group("minor"))) + + +@functools.lru_cache +def _get_glibc_version() -> _GLibCVersion: + version_str = _glibc_version_string() + if version_str is None: + return _GLibCVersion(-1, -1) + return _parse_glibc_version(version_str) + + +# From PEP 513, PEP 600 +def _is_compatible(arch: str, version: _GLibCVersion) -> bool: + sys_glibc = _get_glibc_version() + if sys_glibc < version: + return False + # Check for presence of _manylinux module. + try: + import _manylinux # noqa: PLC0415 + except ImportError: + return True + if hasattr(_manylinux, "manylinux_compatible"): + result = _manylinux.manylinux_compatible(version[0], version[1], arch) + if result is not None: + return bool(result) + return True + if version == _GLibCVersion(2, 5) and hasattr(_manylinux, "manylinux1_compatible"): + return bool(_manylinux.manylinux1_compatible) + if version == _GLibCVersion(2, 12) and hasattr( + _manylinux, "manylinux2010_compatible" + ): + return bool(_manylinux.manylinux2010_compatible) + if version == _GLibCVersion(2, 17) and hasattr( + _manylinux, "manylinux2014_compatible" + ): + return bool(_manylinux.manylinux2014_compatible) + return True + + +_LEGACY_MANYLINUX_MAP: dict[_GLibCVersion, str] = { + # CentOS 7 w/ glibc 2.17 (PEP 599) + _GLibCVersion(2, 17): "manylinux2014", + # CentOS 6 w/ glibc 2.12 (PEP 571) + _GLibCVersion(2, 12): "manylinux2010", + # CentOS 5 w/ glibc 2.5 (PEP 513) + _GLibCVersion(2, 5): "manylinux1", +} + + +def platform_tags(archs: Sequence[str]) -> Iterator[str]: + """Generate manylinux tags compatible to the current platform. + + :param archs: Sequence of compatible architectures. + The first one shall be the closest to the actual architecture and be the part of + platform tag after the ``linux_`` prefix, e.g. ``x86_64``. + The ``linux_`` prefix is assumed as a prerequisite for the current platform to + be manylinux-compatible. + + :returns: An iterator of compatible manylinux tags. + """ + if not _have_compatible_abi(sys.executable, archs): + return + # Oldest glibc to be supported regardless of architecture is (2, 17). + too_old_glibc2 = _GLibCVersion(2, 16) + if set(archs) & {"x86_64", "i686"}: + # On x86/i686 also oldest glibc to be supported is (2, 5). + too_old_glibc2 = _GLibCVersion(2, 4) + current_glibc = _GLibCVersion(*_get_glibc_version()) + glibc_max_list = [current_glibc] + # We can assume compatibility across glibc major versions. + # https://sourceware.org/bugzilla/show_bug.cgi?id=24636 + # + # Build a list of maximum glibc versions so that we can + # output the canonical list of all glibc from current_glibc + # down to too_old_glibc2, including all intermediary versions. + for glibc_major in range(current_glibc.major - 1, 1, -1): + glibc_minor = _LAST_GLIBC_MINOR[glibc_major] + glibc_max_list.append(_GLibCVersion(glibc_major, glibc_minor)) + for arch in archs: + for glibc_max in glibc_max_list: + if glibc_max.major == too_old_glibc2.major: + min_minor = too_old_glibc2.minor + else: + # For other glibc major versions oldest supported is (x, 0). + min_minor = -1 + for glibc_minor in range(glibc_max.minor, min_minor, -1): + glibc_version = _GLibCVersion(glibc_max.major, glibc_minor) + if _is_compatible(arch, glibc_version): + yield "manylinux_{}_{}_{}".format(*glibc_version, arch) + + # Handle the legacy manylinux1, manylinux2010, manylinux2014 tags. + if legacy_tag := _LEGACY_MANYLINUX_MAP.get(glibc_version): + yield f"{legacy_tag}_{arch}" diff --git a/.venv/lib/python3.13/site-packages/packaging/_musllinux.py b/.venv/lib/python3.13/site-packages/packaging/_musllinux.py new file mode 100644 index 0000000000000000000000000000000000000000..4e8116a79ca80d60657542a23b4bbcbc3c518eaf --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_musllinux.py @@ -0,0 +1,85 @@ +"""PEP 656 support. + +This module implements logic to detect if the currently running Python is +linked against musl, and what musl version is used. +""" + +from __future__ import annotations + +import functools +import re +import subprocess +import sys +from typing import Iterator, NamedTuple, Sequence + +from ._elffile import ELFFile + + +class _MuslVersion(NamedTuple): + major: int + minor: int + + +def _parse_musl_version(output: str) -> _MuslVersion | None: + lines = [n for n in (n.strip() for n in output.splitlines()) if n] + if len(lines) < 2 or lines[0][:4] != "musl": + return None + m = re.match(r"Version (\d+)\.(\d+)", lines[1]) + if not m: + return None + return _MuslVersion(major=int(m.group(1)), minor=int(m.group(2))) + + +@functools.lru_cache +def _get_musl_version(executable: str) -> _MuslVersion | None: + """Detect currently-running musl runtime version. + + This is done by checking the specified executable's dynamic linking + information, and invoking the loader to parse its output for a version + string. If the loader is musl, the output would be something like:: + + musl libc (x86_64) + Version 1.2.2 + Dynamic Program Loader + """ + try: + with open(executable, "rb") as f: + ld = ELFFile(f).interpreter + except (OSError, TypeError, ValueError): + return None + if ld is None or "musl" not in ld: + return None + proc = subprocess.run([ld], check=False, stderr=subprocess.PIPE, text=True) + return _parse_musl_version(proc.stderr) + + +def platform_tags(archs: Sequence[str]) -> Iterator[str]: + """Generate musllinux tags compatible to the current platform. + + :param archs: Sequence of compatible architectures. + The first one shall be the closest to the actual architecture and be the part of + platform tag after the ``linux_`` prefix, e.g. ``x86_64``. + The ``linux_`` prefix is assumed as a prerequisite for the current platform to + be musllinux-compatible. + + :returns: An iterator of compatible musllinux tags. + """ + sys_musl = _get_musl_version(sys.executable) + if sys_musl is None: # Python not dynamically linked against musl. + return + for arch in archs: + for minor in range(sys_musl.minor, -1, -1): + yield f"musllinux_{sys_musl.major}_{minor}_{arch}" + + +if __name__ == "__main__": # pragma: no cover + import sysconfig + + plat = sysconfig.get_platform() + assert plat.startswith("linux-"), "not linux" + + print("plat:", plat) + print("musl:", _get_musl_version(sys.executable)) + print("tags:", end=" ") + for t in platform_tags(re.sub(r"[.-]", "_", plat.split("-", 1)[-1])): + print(t, end="\n ") diff --git a/.venv/lib/python3.13/site-packages/packaging/_parser.py b/.venv/lib/python3.13/site-packages/packaging/_parser.py new file mode 100644 index 0000000000000000000000000000000000000000..d320269e1531d822003bde7a826ba24eecca3bae --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_parser.py @@ -0,0 +1,393 @@ +"""Handwritten parser of dependency specifiers. + +The docstring for each __parse_* function contains EBNF-inspired grammar representing +the implementation. +""" + +from __future__ import annotations + +import ast +from typing import List, Literal, NamedTuple, Sequence, Tuple, Union + +from ._tokenizer import DEFAULT_RULES, Tokenizer + + +class Node: + __slots__ = ("value",) + + def __init__(self, value: str) -> None: + self.value = value + + def __str__(self) -> str: + return self.value + + def __repr__(self) -> str: + return f"<{self.__class__.__name__}({self.value!r})>" + + def serialize(self) -> str: + raise NotImplementedError + + def __getstate__(self) -> str: + # Return just the value string for compactness and stability. + return self.value + + def _restore_value(self, value: object) -> None: + if not isinstance(value, str): + raise TypeError( + f"Cannot restore {self.__class__.__name__} value from {value!r}" + ) + self.value = value + + def __setstate__(self, state: object) -> None: + if isinstance(state, str): + # New format (26.2+): just the value string. + self._restore_value(state) + return + if isinstance(state, tuple) and len(state) == 2: + # Old format (packaging <= 26.0, __slots__): (None, {slot: value}). + _, slot_dict = state + if isinstance(slot_dict, dict) and "value" in slot_dict: + self._restore_value(slot_dict["value"]) + return + if isinstance(state, dict) and "value" in state: + # Old format (packaging <= 25.0, no __slots__): plain __dict__. + self._restore_value(state["value"]) + return + raise TypeError(f"Cannot restore {self.__class__.__name__} from {state!r}") + + +class Variable(Node): + __slots__ = () + + def serialize(self) -> str: + return str(self) + + +class Value(Node): + __slots__ = () + + def serialize(self) -> str: + return f'"{self}"' + + +class Op(Node): + __slots__ = () + + def serialize(self) -> str: + return str(self) + + +MarkerLogical = Literal["and", "or"] +MarkerVar = Union[Variable, Value] +MarkerItem = Tuple[MarkerVar, Op, MarkerVar] +MarkerAtom = Union[MarkerItem, Sequence["MarkerAtom"]] +MarkerList = List[Union["MarkerList", MarkerAtom, MarkerLogical]] + + +class ParsedRequirement(NamedTuple): + name: str + url: str + extras: list[str] + specifier: str + marker: MarkerList | None + + +# -------------------------------------------------------------------------------------- +# Recursive descent parser for dependency specifier +# -------------------------------------------------------------------------------------- +def parse_requirement(source: str) -> ParsedRequirement: + return _parse_requirement(Tokenizer(source, rules=DEFAULT_RULES)) + + +def _parse_requirement(tokenizer: Tokenizer) -> ParsedRequirement: + """ + requirement = WS? IDENTIFIER WS? extras WS? requirement_details + """ + tokenizer.consume("WS") + + name_token = tokenizer.expect( + "IDENTIFIER", expected="package name at the start of dependency specifier" + ) + name = name_token.text + tokenizer.consume("WS") + + extras = _parse_extras(tokenizer) + tokenizer.consume("WS") + + url, specifier, marker = _parse_requirement_details(tokenizer) + tokenizer.expect("END", expected="end of dependency specifier") + + return ParsedRequirement(name, url, extras, specifier, marker) + + +def _parse_requirement_details( + tokenizer: Tokenizer, +) -> tuple[str, str, MarkerList | None]: + """ + requirement_details = AT URL (WS requirement_marker?)? + | specifier WS? (requirement_marker)? + """ + + specifier = "" + url = "" + marker = None + + if tokenizer.check("AT"): + tokenizer.read() + tokenizer.consume("WS") + + url_start = tokenizer.position + url = tokenizer.expect("URL", expected="URL after @").text + if tokenizer.check("END", peek=True): + return (url, specifier, marker) + + tokenizer.expect("WS", expected="whitespace after URL") + + # The input might end after whitespace. + if tokenizer.check("END", peek=True): + return (url, specifier, marker) + + marker = _parse_requirement_marker( + tokenizer, + span_start=url_start, + expected="semicolon (after URL and whitespace)", + ) + else: + specifier_start = tokenizer.position + specifier = _parse_specifier(tokenizer) + tokenizer.consume("WS") + + if tokenizer.check("END", peek=True): + return (url, specifier, marker) + + marker = _parse_requirement_marker( + tokenizer, + span_start=specifier_start, + expected=( + "comma (within version specifier), semicolon (after version specifier)" + if specifier + else "semicolon (after name with no version specifier)" + ), + ) + + return (url, specifier, marker) + + +def _parse_requirement_marker( + tokenizer: Tokenizer, *, span_start: int, expected: str +) -> MarkerList: + """ + requirement_marker = SEMICOLON marker WS? + """ + + if not tokenizer.check("SEMICOLON"): + tokenizer.raise_syntax_error( + f"Expected {expected} or end", + span_start=span_start, + span_end=None, + ) + tokenizer.read() + + marker = _parse_marker(tokenizer) + tokenizer.consume("WS") + + return marker + + +def _parse_extras(tokenizer: Tokenizer) -> list[str]: + """ + extras = (LEFT_BRACKET wsp* extras_list? wsp* RIGHT_BRACKET)? + """ + if not tokenizer.check("LEFT_BRACKET", peek=True): + return [] + + with tokenizer.enclosing_tokens( + "LEFT_BRACKET", + "RIGHT_BRACKET", + around="extras", + ): + tokenizer.consume("WS") + extras = _parse_extras_list(tokenizer) + tokenizer.consume("WS") + + return extras + + +def _parse_extras_list(tokenizer: Tokenizer) -> list[str]: + """ + extras_list = identifier (wsp* ',' wsp* identifier)* + """ + extras: list[str] = [] + + if not tokenizer.check("IDENTIFIER"): + return extras + + extras.append(tokenizer.read().text) + + while True: + tokenizer.consume("WS") + if tokenizer.check("IDENTIFIER", peek=True): + tokenizer.raise_syntax_error("Expected comma between extra names") + elif not tokenizer.check("COMMA"): + break + + tokenizer.read() + tokenizer.consume("WS") + + extra_token = tokenizer.expect("IDENTIFIER", expected="extra name after comma") + extras.append(extra_token.text) + + return extras + + +def _parse_specifier(tokenizer: Tokenizer) -> str: + """ + specifier = LEFT_PARENTHESIS WS? version_many WS? RIGHT_PARENTHESIS + | WS? version_many WS? + """ + with tokenizer.enclosing_tokens( + "LEFT_PARENTHESIS", + "RIGHT_PARENTHESIS", + around="version specifier", + ): + tokenizer.consume("WS") + parsed_specifiers = _parse_version_many(tokenizer) + tokenizer.consume("WS") + + return parsed_specifiers + + +def _parse_version_many(tokenizer: Tokenizer) -> str: + """ + version_many = (SPECIFIER (WS? COMMA WS? SPECIFIER)*)? + """ + parsed_specifiers = "" + while tokenizer.check("SPECIFIER"): + span_start = tokenizer.position + parsed_specifiers += tokenizer.read().text + if tokenizer.check("VERSION_PREFIX_TRAIL", peek=True): + tokenizer.raise_syntax_error( + ".* suffix can only be used with `==` or `!=` operators", + span_start=span_start, + span_end=tokenizer.position + 1, + ) + if tokenizer.check("VERSION_LOCAL_LABEL_TRAIL", peek=True): + tokenizer.raise_syntax_error( + "Local version label can only be used with `==` or `!=` operators", + span_start=span_start, + span_end=tokenizer.position, + ) + tokenizer.consume("WS") + if not tokenizer.check("COMMA"): + break + parsed_specifiers += tokenizer.read().text + tokenizer.consume("WS") + + return parsed_specifiers + + +# -------------------------------------------------------------------------------------- +# Recursive descent parser for marker expression +# -------------------------------------------------------------------------------------- +def parse_marker(source: str) -> MarkerList: + return _parse_full_marker(Tokenizer(source, rules=DEFAULT_RULES)) + + +def _parse_full_marker(tokenizer: Tokenizer) -> MarkerList: + retval = _parse_marker(tokenizer) + tokenizer.expect("END", expected="end of marker expression") + return retval + + +def _parse_marker(tokenizer: Tokenizer) -> MarkerList: + """ + marker = marker_atom (BOOLOP marker_atom)+ + """ + expression = [_parse_marker_atom(tokenizer)] + while tokenizer.check("BOOLOP"): + token = tokenizer.read() + expr_right = _parse_marker_atom(tokenizer) + expression.extend((token.text, expr_right)) + return expression + + +def _parse_marker_atom(tokenizer: Tokenizer) -> MarkerAtom: + """ + marker_atom = WS? LEFT_PARENTHESIS WS? marker WS? RIGHT_PARENTHESIS WS? + | WS? marker_item WS? + """ + + tokenizer.consume("WS") + if tokenizer.check("LEFT_PARENTHESIS", peek=True): + with tokenizer.enclosing_tokens( + "LEFT_PARENTHESIS", + "RIGHT_PARENTHESIS", + around="marker expression", + ): + tokenizer.consume("WS") + marker: MarkerAtom = _parse_marker(tokenizer) + tokenizer.consume("WS") + else: + marker = _parse_marker_item(tokenizer) + tokenizer.consume("WS") + return marker + + +def _parse_marker_item(tokenizer: Tokenizer) -> MarkerItem: + """ + marker_item = WS? marker_var WS? marker_op WS? marker_var WS? + """ + tokenizer.consume("WS") + marker_var_left = _parse_marker_var(tokenizer) + tokenizer.consume("WS") + marker_op = _parse_marker_op(tokenizer) + tokenizer.consume("WS") + marker_var_right = _parse_marker_var(tokenizer) + tokenizer.consume("WS") + return (marker_var_left, marker_op, marker_var_right) + + +def _parse_marker_var(tokenizer: Tokenizer) -> MarkerVar: # noqa: RET503 + """ + marker_var = VARIABLE | QUOTED_STRING + """ + if tokenizer.check("VARIABLE"): + return process_env_var(tokenizer.read().text.replace(".", "_")) + elif tokenizer.check("QUOTED_STRING"): + return process_python_str(tokenizer.read().text) + else: + tokenizer.raise_syntax_error( + message="Expected a marker variable or quoted string" + ) + + +def process_env_var(env_var: str) -> Variable: + if env_var in ("platform_python_implementation", "python_implementation"): + return Variable("platform_python_implementation") + else: + return Variable(env_var) + + +def process_python_str(python_str: str) -> Value: + value = ast.literal_eval(python_str) + return Value(str(value)) + + +def _parse_marker_op(tokenizer: Tokenizer) -> Op: + """ + marker_op = IN | NOT IN | OP + """ + if tokenizer.check("IN"): + tokenizer.read() + return Op("in") + elif tokenizer.check("NOT"): + tokenizer.read() + tokenizer.expect("WS", expected="whitespace after 'not'") + tokenizer.expect("IN", expected="'in' after 'not'") + return Op("not in") + elif tokenizer.check("OP"): + return Op(tokenizer.read().text) + else: + return tokenizer.raise_syntax_error( + "Expected marker operator, one of <=, <, !=, ==, >=, >, ~=, ===, in, not in" + ) diff --git a/.venv/lib/python3.13/site-packages/packaging/_structures.py b/.venv/lib/python3.13/site-packages/packaging/_structures.py new file mode 100644 index 0000000000000000000000000000000000000000..4306784d9a26466aa0a210cb2f262903c67d46ca --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_structures.py @@ -0,0 +1,33 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +"""Backward-compatibility shim for unpickling Version objects serialized before +packaging 26.1. + +Old pickles reference ``packaging._structures.InfinityType`` and +``packaging._structures.NegativeInfinityType``. This module provides minimal +stand-in classes so that ``pickle.loads()`` can resolve those references. +The deserialized objects are not used for comparisons — ``Version.__setstate__`` +discards the stale ``_key`` cache and recomputes it from the core version fields. +""" + +from __future__ import annotations + + +class InfinityType: + """Stand-in for the removed ``InfinityType`` used in old comparison keys.""" + + def __repr__(self) -> str: + return "Infinity" + + +class NegativeInfinityType: + """Stand-in for the removed ``NegativeInfinityType`` used in old comparison keys.""" + + def __repr__(self) -> str: + return "-Infinity" + + +Infinity = InfinityType() +NegativeInfinity = NegativeInfinityType() diff --git a/.venv/lib/python3.13/site-packages/packaging/_tokenizer.py b/.venv/lib/python3.13/site-packages/packaging/_tokenizer.py new file mode 100644 index 0000000000000000000000000000000000000000..5ab891ccb8e9048cf64573ca303357efe6afae32 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/_tokenizer.py @@ -0,0 +1,193 @@ +from __future__ import annotations + +import contextlib +import re +from dataclasses import dataclass +from typing import Generator, Mapping, NoReturn + +from .specifiers import Specifier + + +@dataclass +class Token: + name: str + text: str + position: int + + +class ParserSyntaxError(Exception): + """The provided source text could not be parsed correctly.""" + + def __init__( + self, + message: str, + *, + source: str, + span: tuple[int, int], + ) -> None: + self.span = span + self.message = message + self.source = source + + super().__init__() + + def __str__(self) -> str: + marker = " " * self.span[0] + "~" * (self.span[1] - self.span[0]) + "^" + return f"{self.message}\n {self.source}\n {marker}" + + +DEFAULT_RULES: dict[str, re.Pattern[str]] = { + "LEFT_PARENTHESIS": re.compile(r"\("), + "RIGHT_PARENTHESIS": re.compile(r"\)"), + "LEFT_BRACKET": re.compile(r"\["), + "RIGHT_BRACKET": re.compile(r"\]"), + "SEMICOLON": re.compile(r";"), + "COMMA": re.compile(r","), + "QUOTED_STRING": re.compile( + r""" + ( + ('[^']*') + | + ("[^"]*") + ) + """, + re.VERBOSE, + ), + "OP": re.compile(r"(===|==|~=|!=|<=|>=|<|>)"), + "BOOLOP": re.compile(r"\b(or|and)\b"), + "IN": re.compile(r"\bin\b"), + "NOT": re.compile(r"\bnot\b"), + "VARIABLE": re.compile( + r""" + \b( + python_version + |python_full_version + |os[._]name + |sys[._]platform + |platform_(release|system) + |platform[._](version|machine|python_implementation) + |python_implementation + |implementation_(name|version) + |extras? + |dependency_groups + )\b + """, + re.VERBOSE, + ), + "SPECIFIER": re.compile( + Specifier._specifier_regex_str, + re.VERBOSE | re.IGNORECASE, + ), + "AT": re.compile(r"\@"), + "URL": re.compile(r"[^ \t]+"), + "IDENTIFIER": re.compile(r"\b[a-zA-Z0-9][a-zA-Z0-9._-]*\b"), + "VERSION_PREFIX_TRAIL": re.compile(r"\.\*"), + "VERSION_LOCAL_LABEL_TRAIL": re.compile(r"\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*"), + "WS": re.compile(r"[ \t]+"), + "END": re.compile(r"$"), +} + + +class Tokenizer: + """Context-sensitive token parsing. + + Provides methods to examine the input stream to check whether the next token + matches. + """ + + def __init__( + self, + source: str, + *, + rules: Mapping[str, re.Pattern[str]], + ) -> None: + self.source = source + self.rules = rules + self.next_token: Token | None = None + self.position = 0 + + def consume(self, name: str) -> None: + """Move beyond provided token name, if at current position.""" + if self.check(name): + self.read() + + def check(self, name: str, *, peek: bool = False) -> bool: + """Check whether the next token has the provided name. + + By default, if the check succeeds, the token *must* be read before + another check. If `peek` is set to `True`, the token is not loaded and + would need to be checked again. + """ + assert self.next_token is None, ( + f"Cannot check for {name!r}, already have {self.next_token!r}" + ) + assert name in self.rules, f"Unknown token name: {name!r}" + + expression = self.rules[name] + + match = expression.match(self.source, self.position) + if match is None: + return False + if not peek: + self.next_token = Token(name, match[0], self.position) + return True + + def expect(self, name: str, *, expected: str) -> Token: + """Expect a certain token name next, failing with a syntax error otherwise. + + The token is *not* read. + """ + if not self.check(name): + raise self.raise_syntax_error(f"Expected {expected}") + return self.read() + + def read(self) -> Token: + """Consume the next token and return it.""" + token = self.next_token + assert token is not None + + self.position += len(token.text) + self.next_token = None + + return token + + def raise_syntax_error( + self, + message: str, + *, + span_start: int | None = None, + span_end: int | None = None, + ) -> NoReturn: + """Raise ParserSyntaxError at the given position.""" + span = ( + self.position if span_start is None else span_start, + self.position if span_end is None else span_end, + ) + raise ParserSyntaxError( + message, + source=self.source, + span=span, + ) + + @contextlib.contextmanager + def enclosing_tokens( + self, open_token: str, close_token: str, *, around: str + ) -> Generator[None, None, None]: + if self.check(open_token): + open_position = self.position + self.read() + else: + open_position = None + + yield + + if open_position is None: + return + + if not self.check(close_token): + self.raise_syntax_error( + f"Expected matching {close_token} for {open_token}, after {around}", + span_start=open_position, + ) + + self.read() diff --git a/.venv/lib/python3.13/site-packages/packaging/dependency_groups.py b/.venv/lib/python3.13/site-packages/packaging/dependency_groups.py new file mode 100644 index 0000000000000000000000000000000000000000..413e5cb4b40d734564b99092320bb58a8f3c2c2b --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/dependency_groups.py @@ -0,0 +1,302 @@ +from __future__ import annotations + +import re +from collections.abc import Mapping, Sequence + +from .errors import _ErrorCollector +from .requirements import Requirement + +__all__ = [ + "CyclicDependencyGroup", + "DependencyGroupInclude", + "DependencyGroupResolver", + "DuplicateGroupNames", + "InvalidDependencyGroupObject", + "resolve_dependency_groups", +] + + +def __dir__() -> list[str]: + return __all__ + + +# ----------- +# Error Types +# ----------- + + +class DuplicateGroupNames(ValueError): + """ + The same dependency groups were defined twice, with different non-normalized names. + """ + + +class CyclicDependencyGroup(ValueError): + """ + The dependency group includes form a cycle. + """ + + def __init__(self, requested_group: str, group: str, include_group: str) -> None: + self.requested_group = requested_group + self.group = group + self.include_group = include_group + + if include_group == group: + reason = f"{group} includes itself" + else: + reason = f"{include_group} -> {group}, {group} -> {include_group}" + super().__init__( + "Cyclic dependency group include while resolving " + f"{requested_group}: {reason}" + ) + + +# in the PEP 735 spec, the tables in dependency group lists were described as +# "Dependency Object Specifiers", but the only defined type of object was a +# "Dependency Group Include" -- hence the naming of this error as "Object" +class InvalidDependencyGroupObject(ValueError): + """ + A member of a dependency group was identified as a dict, but was not in a valid + format. + """ + + +# ------------------------ +# Object Model & Interface +# ------------------------ + + +class DependencyGroupInclude: + __slots__ = ("include_group",) + + def __init__(self, include_group: str) -> None: + """ + Initialize a DependencyGroupInclude. + + :param include_group: The name of the group referred to by this include. + """ + self.include_group = include_group + + def __repr__(self) -> str: + return f"{self.__class__.__name__}({self.include_group!r})" + + +class DependencyGroupResolver: + """ + A resolver for Dependency Group data. + + This class handles caching, name normalization, cycle detection, and other + parsing requirements. There are only two public methods for exploring the data: + ``lookup()`` and ``resolve()``. + + :param dependency_groups: A mapping, as provided via pyproject + ``[dependency-groups]``. + """ + + def __init__( + self, + dependency_groups: Mapping[str, Sequence[str | Mapping[str, str]]], + ) -> None: + errors = _ErrorCollector() + + self.dependency_groups = _normalize_group_names(dependency_groups, errors) + + # a map of group names to parsed data + self._parsed_groups: dict[ + str, tuple[Requirement | DependencyGroupInclude, ...] + ] = {} + # a map of group names to their ancestors, used for cycle detection + self._include_graph_ancestors: dict[str, tuple[str, ...]] = {} + # a cache of completed resolutions to Requirement lists + self._resolve_cache: dict[str, tuple[Requirement, ...]] = {} + + errors.finalize("[dependency-groups] data was invalid") + + def lookup(self, group: str) -> tuple[Requirement | DependencyGroupInclude, ...]: + """ + Lookup a group name, returning the parsed dependency data for that group. + This will not resolve includes. + + :param group: the name of the group to lookup + """ + group = _normalize_name(group) + + with _ErrorCollector().on_exit( + f"[dependency-groups] data for {group!r} was malformed" + ) as errors: + return self._parse_group(group, errors) + + def resolve(self, group: str) -> tuple[Requirement, ...]: + """ + Resolve a dependency group to a list of requirements. + + :param group: the name of the group to resolve + """ + group = _normalize_name(group) + + with _ErrorCollector().on_exit( + f"[dependency-groups] data for {group!r} was malformed" + ) as errors: + return self._resolve(group, group, errors) + + def _resolve( + self, group: str, requested_group: str, errors: _ErrorCollector + ) -> tuple[Requirement, ...]: + """ + This is a helper for cached resolution to strings. It preserves the name of the + group which the user initially requested in order to present a clearer error in + the event that a cycle is detected. + + :param group: The normalized name of the group to resolve. + :param requested_group: The group which was used in the original, user-facing + request. + """ + if group in self._resolve_cache: + return self._resolve_cache[group] + + parsed = self._parse_group(group, errors) + + resolved_group = [] + + for item in parsed: + if isinstance(item, Requirement): + resolved_group.append(item) + elif isinstance(item, DependencyGroupInclude): + include_group = _normalize_name(item.include_group) + + # if a group is cyclic, record the error + # otherwise, follow the include_group reference + # + # this allows us to examine all includes in a group, even in the + # presence of errors + if include_group in self._include_graph_ancestors.get(group, ()): + errors.error( + CyclicDependencyGroup( + requested_group, group, item.include_group + ) + ) + else: + self._include_graph_ancestors[include_group] = ( + *self._include_graph_ancestors.get(group, ()), + group, + ) + resolved_group.extend( + self._resolve(include_group, requested_group, errors) + ) + else: # pragma: no cover + raise NotImplementedError( + f"Invalid dependency group item after parse: {item}" + ) + + # in the event that errors were detected, present the group as empty and do not + # cache the result + # this ensures that repeated access to a cyclic group will raise multiple errors + if errors.errors: + return () + + self._resolve_cache[group] = tuple(resolved_group) + return self._resolve_cache[group] + + def _parse_group( + self, group: str, errors: _ErrorCollector + ) -> tuple[Requirement | DependencyGroupInclude, ...]: + # short circuit -- never do the work twice + if group in self._parsed_groups: + return self._parsed_groups[group] + + if group not in self.dependency_groups: + errors.error(LookupError(f"Dependency group '{group}' not found")) + return () + + raw_group = self.dependency_groups[group] + if isinstance(raw_group, str): + errors.error( + TypeError( + f"Dependency group {group!r} contained a string rather than a list." + ) + ) + return () + + if not isinstance(raw_group, Sequence): + errors.error( + TypeError(f"Dependency group {group!r} is not a sequence type.") + ) + return () + + elements: list[Requirement | DependencyGroupInclude] = [] + for item in raw_group: + if isinstance(item, str): + # packaging.requirements.Requirement parsing ensures that this is a + # valid PEP 508 Dependency Specifier + # raises InvalidRequirement on failure + elements.append(Requirement(item)) + elif isinstance(item, Mapping): + if tuple(item.keys()) != ("include-group",): + errors.error( + InvalidDependencyGroupObject( + f"Invalid dependency group item: {item!r}" + ) + ) + else: + include_group = item["include-group"] + elements.append(DependencyGroupInclude(include_group=include_group)) + else: + errors.error(TypeError(f"Invalid dependency group item: {item!r}")) + + self._parsed_groups[group] = tuple(elements) + return self._parsed_groups[group] + + +# -------------------- +# Functional Interface +# -------------------- + + +def resolve_dependency_groups( + dependency_groups: Mapping[str, Sequence[str | Mapping[str, str]]], /, *groups: str +) -> tuple[str, ...]: + """ + Resolve a dependency group to a tuple of requirements, as strings. + + :param dependency_groups: the parsed contents of the ``[dependency-groups]`` table + from ``pyproject.toml`` + :param groups: the name of the group(s) to resolve + """ + resolver = DependencyGroupResolver(dependency_groups) + return tuple(str(r) for group in groups for r in resolver.resolve(group)) + + +# ---------------- +# internal helpers +# ---------------- + + +_NORMALIZE_PATTERN = re.compile(r"[-_.]+") + + +def _normalize_name(name: str) -> str: + return _NORMALIZE_PATTERN.sub("-", name).lower() + + +def _normalize_group_names( + dependency_groups: Mapping[str, Sequence[str | Mapping[str, str]]], + errors: _ErrorCollector, +) -> dict[str, Sequence[str | Mapping[str, str]]]: + original_names: dict[str, list[str]] = {} + normalized_groups: dict[str, Sequence[str | Mapping[str, str]]] = {} + + for group_name, value in dependency_groups.items(): + normed_group_name = _normalize_name(group_name) + original_names.setdefault(normed_group_name, []).append(group_name) + normalized_groups[normed_group_name] = value + + for normed_name, names in original_names.items(): + if len(names) > 1: + errors.error( + DuplicateGroupNames( + "Duplicate dependency group names: " + f"{normed_name} ({', '.join(names)})" + ) + ) + + return normalized_groups diff --git a/.venv/lib/python3.13/site-packages/packaging/direct_url.py b/.venv/lib/python3.13/site-packages/packaging/direct_url.py new file mode 100644 index 0000000000000000000000000000000000000000..5d1c56ca9d6fcd92111b0a86258853224509abb0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/direct_url.py @@ -0,0 +1,325 @@ +from __future__ import annotations + +import dataclasses +import re +import urllib.parse +from collections.abc import Mapping +from typing import TYPE_CHECKING, Any, Protocol, TypeVar + +if TYPE_CHECKING: # pragma: no cover + import sys + from collections.abc import Collection + + if sys.version_info >= (3, 11): + from typing import Self + else: + from typing_extensions import Self + +__all__ = [ + "ArchiveInfo", + "DirInfo", + "DirectUrl", + "DirectUrlValidationError", + "VcsInfo", +] + + +def __dir__() -> list[str]: + return __all__ + + +_T = TypeVar("_T") + + +class _FromMappingProtocol(Protocol): # pragma: no cover + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: ... + + +_FromMappingProtocolT = TypeVar("_FromMappingProtocolT", bound=_FromMappingProtocol) + + +def _json_dict_factory(data: list[tuple[str, Any]]) -> dict[str, Any]: + return {key: value for key, value in data if value is not None} + + +def _get(d: Mapping[str, Any], expected_type: type[_T], key: str) -> _T | None: + """Get a value from the dictionary and verify it's the expected type.""" + if (value := d.get(key)) is None: + return None + if not isinstance(value, expected_type): + raise DirectUrlValidationError( + f"Unexpected type {type(value).__name__} " + f"(expected {expected_type.__name__})", + context=key, + ) + return value + + +def _get_required(d: Mapping[str, Any], expected_type: type[_T], key: str) -> _T: + """Get a required value from the dictionary and verify it's the expected type.""" + if (value := _get(d, expected_type, key)) is None: + raise _DirectUrlRequiredKeyError(key) + return value + + +def _get_object( + d: Mapping[str, Any], target_type: type[_FromMappingProtocolT], key: str +) -> _FromMappingProtocolT | None: + """Get a dictionary value from the dictionary and convert it to a dataclass.""" + if (value := _get(d, Mapping, key)) is None: # type: ignore[type-abstract] + return None + try: + return target_type._from_dict(value) + except Exception as e: + raise DirectUrlValidationError(e, context=key) from e + + +_PEP610_USER_PASS_ENV_VARS_REGEX = re.compile( + r"^\$\{[A-Za-z0-9-_]+\}(:\$\{[A-Za-z0-9-_]+\})?$" +) + + +def _strip_auth_from_netloc(netloc: str, safe_user_passwords: Collection[str]) -> str: + if "@" not in netloc: + return netloc + user_pass, netloc_no_user_pass = netloc.split("@", 1) + if user_pass in safe_user_passwords: + return netloc + if _PEP610_USER_PASS_ENV_VARS_REGEX.match(user_pass): + return netloc + return netloc_no_user_pass + + +def _strip_url(url: str, safe_user_passwords: Collection[str]) -> str: + """url with user:password part removed unless it is formed with + environment variables as specified in PEP 610, or it is a safe user:password + such as `git`. + """ + parsed_url = urllib.parse.urlsplit(url) + netloc = _strip_auth_from_netloc(parsed_url.netloc, safe_user_passwords) + return urllib.parse.urlunsplit( + ( + parsed_url.scheme, + netloc, + parsed_url.path, + parsed_url.query, + parsed_url.fragment, + ) + ) + + +class DirectUrlValidationError(Exception): + """Raised when when input data is not spec-compliant.""" + + context: str | None = None + message: str + + def __init__( + self, + cause: str | Exception, + *, + context: str | None = None, + ) -> None: + if isinstance(cause, DirectUrlValidationError): + if cause.context: + self.context = ( + f"{context}.{cause.context}" if context else cause.context + ) + else: + self.context = context # pragma: no cover + self.message = cause.message + else: + self.context = context + self.message = str(cause) + + def __str__(self) -> str: + if self.context: + return f"{self.message} in {self.context!r}" + return self.message + + +class _DirectUrlRequiredKeyError(DirectUrlValidationError): + def __init__(self, key: str) -> None: + super().__init__("Missing required value", context=key) + + +@dataclasses.dataclass(frozen=True, init=False) +class VcsInfo: + vcs: str + commit_id: str + requested_revision: str | None = None + + def __init__( + self, + *, + vcs: str, + commit_id: str, + requested_revision: str | None = None, + ) -> None: + object.__setattr__(self, "vcs", vcs) + object.__setattr__(self, "commit_id", commit_id) + object.__setattr__(self, "requested_revision", requested_revision) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + # We can't validate vcs value because is not closed. + return cls( + vcs=_get_required(d, str, "vcs"), + requested_revision=_get(d, str, "requested_revision"), + commit_id=_get_required(d, str, "commit_id"), + ) + + +@dataclasses.dataclass(frozen=True, init=False) +class ArchiveInfo: + hashes: Mapping[str, str] | None = None + + def __init__( + self, + *, + hashes: Mapping[str, str] | None = None, + ) -> None: + object.__setattr__(self, "hashes", hashes) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + hashes = _get(d, Mapping, "hashes") # type: ignore[type-abstract] + if hashes is not None and not all(isinstance(h, str) for h in hashes.values()): + raise DirectUrlValidationError( + "Hash values must be strings", context="hashes" + ) + legacy_hash = _get(d, str, "hash") + if legacy_hash is not None: + if "=" not in legacy_hash: + raise DirectUrlValidationError( + "Invalid hash format (expected '=')", + context="hash", + ) + hash_algorithm, hash_value = legacy_hash.split("=", 1) + if hashes is None: + # if `hashes` are not present, we can derive it from the legacy `hash` + hashes = {hash_algorithm: hash_value} + else: + # if `hashes` are present, the legacy `hash` must match one of them + if hash_algorithm not in hashes: + raise DirectUrlValidationError( + f"Algorithm {hash_algorithm!r} used in hash field " + f"is not present in hashes field", + context="hashes", + ) + if hashes[hash_algorithm] != hash_value: + raise DirectUrlValidationError( + f"Algorithm {hash_algorithm!r} used in hash field " + f"has different value in hashes field", + context="hash", + ) + return cls(hashes=hashes) + + +@dataclasses.dataclass(frozen=True, init=False) +class DirInfo: + editable: bool | None = None + + def __init__( + self, + *, + editable: bool | None = None, + ) -> None: + object.__setattr__(self, "editable", editable) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + return cls( + editable=_get(d, bool, "editable"), + ) + + +@dataclasses.dataclass(frozen=True, init=False) +class DirectUrl: + """A class representing a direct URL.""" + + url: str + archive_info: ArchiveInfo | None = None + vcs_info: VcsInfo | None = None + dir_info: DirInfo | None = None + subdirectory: str | None = None # XXX Path or str? + + def __init__( + self, + *, + url: str, + archive_info: ArchiveInfo | None = None, + vcs_info: VcsInfo | None = None, + dir_info: DirInfo | None = None, + subdirectory: str | None = None, + ) -> None: + object.__setattr__(self, "url", url) + object.__setattr__(self, "archive_info", archive_info) + object.__setattr__(self, "vcs_info", vcs_info) + object.__setattr__(self, "dir_info", dir_info) + object.__setattr__(self, "subdirectory", subdirectory) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + direct_url = cls( + url=_get_required(d, str, "url"), + archive_info=_get_object(d, ArchiveInfo, "archive_info"), + vcs_info=_get_object(d, VcsInfo, "vcs_info"), + dir_info=_get_object(d, DirInfo, "dir_info"), + subdirectory=_get(d, str, "subdirectory"), + ) + if ( + bool(direct_url.vcs_info) + + bool(direct_url.archive_info) + + bool(direct_url.dir_info) + ) != 1: + raise DirectUrlValidationError( + "Exactly one of vcs_info, archive_info, dir_info must be present" + ) + if direct_url.dir_info is not None and not direct_url.url.startswith("file://"): + raise DirectUrlValidationError( + "URL scheme must be file:// when dir_info is present", + context="url", + ) + # XXX subdirectory must be relative, can we, should we validate that here? + return direct_url + + @classmethod + def from_dict(cls, d: Mapping[str, Any], /) -> Self: + """Create and validate a DirectUrl instance from a JSON dictionary.""" + return cls._from_dict(d) + + def to_dict( + self, + *, + generate_legacy_hash: bool = False, + strip_user_password: bool = True, + safe_user_passwords: Collection[str] = ("git",), + ) -> Mapping[str, Any]: + """Convert the DirectUrl instance to a JSON dictionary. + + :param generate_legacy_hash: If True, include a legacy `hash` field in + `archive_info` for backward compatibility with tools that don't + support the `hashes` field. + :param strip_user_password: If True, strip user:password from the URL + unless it is formed with environment variables as specified in PEP + 610, or it is a safe user:password such as `git`. + :param safe_user_passwords: A collection of user:password strings that + should not be stripped from the URL even if `strip_user_password` is + True. + """ + res = dataclasses.asdict(self, dict_factory=_json_dict_factory) + if generate_legacy_hash and self.archive_info and self.archive_info.hashes: + hash_algorithm, hash_value = next(iter(self.archive_info.hashes.items())) + res["archive_info"]["hash"] = f"{hash_algorithm}={hash_value}" + if strip_user_password: + res["url"] = _strip_url(self.url, safe_user_passwords) + return res + + def validate(self) -> None: + """Validate the DirectUrl instance against the specification. + + Raises :class:`DirectUrlValidationError` if invalid. + """ + self.from_dict(self.to_dict()) diff --git a/.venv/lib/python3.13/site-packages/packaging/errors.py b/.venv/lib/python3.13/site-packages/packaging/errors.py new file mode 100644 index 0000000000000000000000000000000000000000..d1d47cf6c3416179750bf5bf170aafe9d0fa6497 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/errors.py @@ -0,0 +1,94 @@ +from __future__ import annotations + +import contextlib +import dataclasses +import sys +import typing + +__all__ = ["ExceptionGroup"] + + +def __dir__() -> list[str]: + return __all__ + + +if sys.version_info >= (3, 11): # pragma: no cover + from builtins import ExceptionGroup +else: # pragma: no cover + + class ExceptionGroup(Exception): + """A minimal implementation of :external:exc:`ExceptionGroup` from Python 3.11. + + If :external:exc:`ExceptionGroup` is already defined by Python itself, + that version is used instead. + """ + + message: str + exceptions: list[Exception] + + def __init__(self, message: str, exceptions: list[Exception]) -> None: + self.message = message + self.exceptions = exceptions + + def __repr__(self) -> str: + return f"{self.__class__.__name__}({self.message!r}, {self.exceptions!r})" + + +@dataclasses.dataclass +class _ErrorCollector: + """ + Collect errors into ExceptionGroups. + + Used like this: + + collector = _ErrorCollector() + # Add a single exception + collector.error(ValueError("one")) + + # Supports nesting, including combining ExceptionGroups + with collector.collect(): + raise ValueError("two") + collector.finalize("Found some errors") + + Since making a collector and then calling finalize later is a common pattern, + a convenience method ``on_exit`` is provided. + """ + + errors: list[Exception] = dataclasses.field(default_factory=list, init=False) + + def finalize(self, msg: str) -> None: + """Raise a group exception if there are any errors.""" + if self.errors: + raise ExceptionGroup(msg, self.errors) + + @contextlib.contextmanager + def on_exit(self, msg: str) -> typing.Generator[_ErrorCollector, None, None]: + """ + Calls finalize if no uncollected errors were present. + + Uncollected errors are raised normally. + """ + yield self + self.finalize(msg) + + @contextlib.contextmanager + def collect(self, *err_cls: type[Exception]) -> typing.Generator[None, None, None]: + """ + Context manager to collect errors into the error list. + + Must be inside loops, as only one error can be collected at a time. + """ + error_classes = err_cls or (Exception,) + try: + yield + except ExceptionGroup as error: + self.errors.extend(error.exceptions) + except error_classes as error: + self.errors.append(error) + + def error( + self, + error: Exception, + ) -> None: + """Add an error to the list.""" + self.errors.append(error) diff --git a/.venv/lib/python3.13/site-packages/packaging/licenses/__init__.py b/.venv/lib/python3.13/site-packages/packaging/licenses/__init__.py new file mode 100644 index 0000000000000000000000000000000000000000..36e46ed02ca7aa6690928cf33868ae9cd1ab1d17 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/licenses/__init__.py @@ -0,0 +1,186 @@ +####################################################################################### +# +# Adapted from: +# https://github.com/pypa/hatch/blob/5352e44/backend/src/hatchling/licenses/parse.py +# +# MIT License +# +# Copyright (c) 2017-present Ofek Lev +# +# Permission is hereby granted, free of charge, to any person obtaining a copy of this +# software and associated documentation files (the "Software"), to deal in the Software +# without restriction, including without limitation the rights to use, copy, modify, +# merge, publish, distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to the following +# conditions: +# +# The above copyright notice and this permission notice shall be included in all copies +# or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, +# INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A +# PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT +# HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF +# CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE +# OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. +# +# +# With additional allowance of arbitrary `LicenseRef-` identifiers, not just +# `LicenseRef-Public-Domain` and `LicenseRef-Proprietary`. +# +####################################################################################### +from __future__ import annotations + +import re +from typing import NewType, cast + +from ._spdx import EXCEPTIONS, LICENSES + +__all__ = [ + "InvalidLicenseExpression", + "NormalizedLicenseExpression", + "canonicalize_license_expression", +] + + +# Simple __dir__ implementation since there are no public submodules +def __dir__() -> list[str]: + return __all__ + + +license_ref_allowed = re.compile("^[A-Za-z0-9.-]*$") + +NormalizedLicenseExpression = NewType("NormalizedLicenseExpression", str) +""" +A :class:`typing.NewType` of :class:`str`, representing a normalized +License-Expression. +""" + + +class InvalidLicenseExpression(ValueError): + """Raised when a license-expression string is invalid + + >>> from packaging.licenses import canonicalize_license_expression + >>> canonicalize_license_expression("invalid") + Traceback (most recent call last): + ... + packaging.licenses.InvalidLicenseExpression: Invalid license expression: 'invalid' + """ + + +def canonicalize_license_expression( + raw_license_expression: str, +) -> NormalizedLicenseExpression: + """ + This function takes a valid License-Expression, and returns the normalized + form of it. + + The return type is typed as :class:`NormalizedLicenseExpression`. This + allows type checkers to help require that a string has passed through this + function before use. + + :param str raw_license_expression: The License-Expression to canonicalize. + :raises InvalidLicenseExpression: If the License-Expression is invalid due to an + invalid/unknown license identifier or invalid syntax. + + .. doctest:: + + >>> from packaging.licenses import canonicalize_license_expression + >>> canonicalize_license_expression("mit") + 'MIT' + >>> canonicalize_license_expression("mit and (apache-2.0 or bsd-2-clause)") + 'MIT AND (Apache-2.0 OR BSD-2-Clause)' + >>> canonicalize_license_expression("(mit") + Traceback (most recent call last): + ... + InvalidLicenseExpression: Invalid license expression: '(mit' + >>> canonicalize_license_expression("Use-it-after-midnight") + Traceback (most recent call last): + ... + InvalidLicenseExpression: Unknown license: 'Use-it-after-midnight' + """ + if not raw_license_expression: + message = f"Invalid license expression: {raw_license_expression!r}" + raise InvalidLicenseExpression(message) + + # Pad any parentheses so tokenization can be achieved by merely splitting on + # whitespace. + license_expression = raw_license_expression.replace("(", " ( ").replace(")", " ) ") + licenseref_prefix = "LicenseRef-" + license_refs = { + ref.lower(): "LicenseRef-" + ref[len(licenseref_prefix) :] + for ref in license_expression.split() + if ref.lower().startswith(licenseref_prefix.lower()) + } + + # Normalize to lower case so we can look up licenses/exceptions + # and so boolean operators are Python-compatible. + license_expression = license_expression.lower() + + tokens = license_expression.split() + + # Rather than implementing a parenthesis/boolean logic parser, create an + # expression that Python can parse. Everything that is not involved with the + # grammar itself is replaced with the placeholder `False` and the resultant + # expression should become a valid Python expression. + python_tokens = [] + for token in tokens: + if token not in {"or", "and", "with", "(", ")"}: + python_tokens.append("False") + elif token == "with": + python_tokens.append("or") + elif ( + token == "(" + and python_tokens + and python_tokens[-1] not in {"or", "and", "("} + ) or (token == ")" and python_tokens and python_tokens[-1] == "("): + message = f"Invalid license expression: {raw_license_expression!r}" + raise InvalidLicenseExpression(message) + else: + python_tokens.append(token) + + python_expression = " ".join(python_tokens) + try: + compile(python_expression, "", "eval") + except SyntaxError: + message = f"Invalid license expression: {raw_license_expression!r}" + raise InvalidLicenseExpression(message) from None + + # Take a final pass to check for unknown licenses/exceptions. + normalized_tokens = [] + for token in tokens: + if token in {"or", "and", "with", "(", ")"}: + normalized_tokens.append(token.upper()) + continue + + if normalized_tokens and normalized_tokens[-1] == "WITH": + if token not in EXCEPTIONS: + message = f"Unknown license exception: {token!r}" + raise InvalidLicenseExpression(message) + + normalized_tokens.append(EXCEPTIONS[token]["id"]) + else: + if token.endswith("+"): + final_token = token[:-1] + suffix = "+" + else: + final_token = token + suffix = "" + + if final_token.startswith("licenseref-"): + if not license_ref_allowed.match(final_token): + message = f"Invalid licenseref: {final_token!r}" + raise InvalidLicenseExpression(message) + normalized_tokens.append(license_refs[final_token] + suffix) + else: + if final_token not in LICENSES: + message = f"Unknown license: {final_token!r}" + raise InvalidLicenseExpression(message) + normalized_tokens.append(LICENSES[final_token]["id"] + suffix) + + normalized_expression = " ".join(normalized_tokens) + + return cast( + "NormalizedLicenseExpression", + normalized_expression.replace("( ", "(").replace(" )", ")"), + ) diff --git a/.venv/lib/python3.13/site-packages/packaging/licenses/_spdx.py b/.venv/lib/python3.13/site-packages/packaging/licenses/_spdx.py new file mode 100644 index 0000000000000000000000000000000000000000..a277af28220b6dbe4599471104d1c7a2bd1e1288 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/licenses/_spdx.py @@ -0,0 +1,799 @@ + +from __future__ import annotations + +from typing import TypedDict + +class SPDXLicense(TypedDict): + id: str + deprecated: bool + +class SPDXException(TypedDict): + id: str + deprecated: bool + + +VERSION = '3.27.0' + +LICENSES: dict[str, SPDXLicense] = { + '0bsd': {'id': '0BSD', 'deprecated': False}, + '3d-slicer-1.0': {'id': '3D-Slicer-1.0', 'deprecated': False}, + 'aal': {'id': 'AAL', 'deprecated': False}, + 'abstyles': {'id': 'Abstyles', 'deprecated': False}, + 'adacore-doc': {'id': 'AdaCore-doc', 'deprecated': False}, + 'adobe-2006': {'id': 'Adobe-2006', 'deprecated': False}, + 'adobe-display-postscript': {'id': 'Adobe-Display-PostScript', 'deprecated': False}, + 'adobe-glyph': {'id': 'Adobe-Glyph', 'deprecated': False}, + 'adobe-utopia': {'id': 'Adobe-Utopia', 'deprecated': False}, + 'adsl': {'id': 'ADSL', 'deprecated': False}, + 'afl-1.1': {'id': 'AFL-1.1', 'deprecated': False}, + 'afl-1.2': {'id': 'AFL-1.2', 'deprecated': False}, + 'afl-2.0': {'id': 'AFL-2.0', 'deprecated': False}, + 'afl-2.1': {'id': 'AFL-2.1', 'deprecated': False}, + 'afl-3.0': {'id': 'AFL-3.0', 'deprecated': False}, + 'afmparse': {'id': 'Afmparse', 'deprecated': False}, + 'agpl-1.0': {'id': 'AGPL-1.0', 'deprecated': True}, + 'agpl-1.0-only': {'id': 'AGPL-1.0-only', 'deprecated': False}, + 'agpl-1.0-or-later': {'id': 'AGPL-1.0-or-later', 'deprecated': False}, + 'agpl-3.0': {'id': 'AGPL-3.0', 'deprecated': True}, + 'agpl-3.0-only': {'id': 'AGPL-3.0-only', 'deprecated': False}, + 'agpl-3.0-or-later': {'id': 'AGPL-3.0-or-later', 'deprecated': False}, + 'aladdin': {'id': 'Aladdin', 'deprecated': False}, + 'amd-newlib': {'id': 'AMD-newlib', 'deprecated': False}, + 'amdplpa': {'id': 'AMDPLPA', 'deprecated': False}, + 'aml': {'id': 'AML', 'deprecated': False}, + 'aml-glslang': {'id': 'AML-glslang', 'deprecated': False}, + 'ampas': {'id': 'AMPAS', 'deprecated': False}, + 'antlr-pd': {'id': 'ANTLR-PD', 'deprecated': False}, + 'antlr-pd-fallback': {'id': 'ANTLR-PD-fallback', 'deprecated': False}, + 'any-osi': {'id': 'any-OSI', 'deprecated': False}, + 'any-osi-perl-modules': {'id': 'any-OSI-perl-modules', 'deprecated': False}, + 'apache-1.0': {'id': 'Apache-1.0', 'deprecated': False}, + 'apache-1.1': {'id': 'Apache-1.1', 'deprecated': False}, + 'apache-2.0': {'id': 'Apache-2.0', 'deprecated': False}, + 'apafml': {'id': 'APAFML', 'deprecated': False}, + 'apl-1.0': {'id': 'APL-1.0', 'deprecated': False}, + 'app-s2p': {'id': 'App-s2p', 'deprecated': False}, + 'apsl-1.0': {'id': 'APSL-1.0', 'deprecated': False}, + 'apsl-1.1': {'id': 'APSL-1.1', 'deprecated': False}, + 'apsl-1.2': {'id': 'APSL-1.2', 'deprecated': False}, + 'apsl-2.0': {'id': 'APSL-2.0', 'deprecated': False}, + 'arphic-1999': {'id': 'Arphic-1999', 'deprecated': False}, + 'artistic-1.0': {'id': 'Artistic-1.0', 'deprecated': False}, + 'artistic-1.0-cl8': {'id': 'Artistic-1.0-cl8', 'deprecated': False}, + 'artistic-1.0-perl': {'id': 'Artistic-1.0-Perl', 'deprecated': False}, + 'artistic-2.0': {'id': 'Artistic-2.0', 'deprecated': False}, + 'artistic-dist': {'id': 'Artistic-dist', 'deprecated': False}, + 'aspell-ru': {'id': 'Aspell-RU', 'deprecated': False}, + 'aswf-digital-assets-1.0': {'id': 'ASWF-Digital-Assets-1.0', 'deprecated': False}, + 'aswf-digital-assets-1.1': {'id': 'ASWF-Digital-Assets-1.1', 'deprecated': False}, + 'baekmuk': {'id': 'Baekmuk', 'deprecated': False}, + 'bahyph': {'id': 'Bahyph', 'deprecated': False}, + 'barr': {'id': 'Barr', 'deprecated': False}, + 'bcrypt-solar-designer': {'id': 'bcrypt-Solar-Designer', 'deprecated': False}, + 'beerware': {'id': 'Beerware', 'deprecated': False}, + 'bitstream-charter': {'id': 'Bitstream-Charter', 'deprecated': False}, + 'bitstream-vera': {'id': 'Bitstream-Vera', 'deprecated': False}, + 'bittorrent-1.0': {'id': 'BitTorrent-1.0', 'deprecated': False}, + 'bittorrent-1.1': {'id': 'BitTorrent-1.1', 'deprecated': False}, + 'blessing': {'id': 'blessing', 'deprecated': False}, + 'blueoak-1.0.0': {'id': 'BlueOak-1.0.0', 'deprecated': False}, + 'boehm-gc': {'id': 'Boehm-GC', 'deprecated': False}, + 'boehm-gc-without-fee': {'id': 'Boehm-GC-without-fee', 'deprecated': False}, + 'borceux': {'id': 'Borceux', 'deprecated': False}, + 'brian-gladman-2-clause': {'id': 'Brian-Gladman-2-Clause', 'deprecated': False}, + 'brian-gladman-3-clause': {'id': 'Brian-Gladman-3-Clause', 'deprecated': False}, + 'bsd-1-clause': {'id': 'BSD-1-Clause', 'deprecated': False}, + 'bsd-2-clause': {'id': 'BSD-2-Clause', 'deprecated': False}, + 'bsd-2-clause-darwin': {'id': 'BSD-2-Clause-Darwin', 'deprecated': False}, + 'bsd-2-clause-first-lines': {'id': 'BSD-2-Clause-first-lines', 'deprecated': False}, + 'bsd-2-clause-freebsd': {'id': 'BSD-2-Clause-FreeBSD', 'deprecated': True}, + 'bsd-2-clause-netbsd': {'id': 'BSD-2-Clause-NetBSD', 'deprecated': True}, + 'bsd-2-clause-patent': {'id': 'BSD-2-Clause-Patent', 'deprecated': False}, + 'bsd-2-clause-pkgconf-disclaimer': {'id': 'BSD-2-Clause-pkgconf-disclaimer', 'deprecated': False}, + 'bsd-2-clause-views': {'id': 'BSD-2-Clause-Views', 'deprecated': False}, + 'bsd-3-clause': {'id': 'BSD-3-Clause', 'deprecated': False}, + 'bsd-3-clause-acpica': {'id': 'BSD-3-Clause-acpica', 'deprecated': False}, + 'bsd-3-clause-attribution': {'id': 'BSD-3-Clause-Attribution', 'deprecated': False}, + 'bsd-3-clause-clear': {'id': 'BSD-3-Clause-Clear', 'deprecated': False}, + 'bsd-3-clause-flex': {'id': 'BSD-3-Clause-flex', 'deprecated': False}, + 'bsd-3-clause-hp': {'id': 'BSD-3-Clause-HP', 'deprecated': False}, + 'bsd-3-clause-lbnl': {'id': 'BSD-3-Clause-LBNL', 'deprecated': False}, + 'bsd-3-clause-modification': {'id': 'BSD-3-Clause-Modification', 'deprecated': False}, + 'bsd-3-clause-no-military-license': {'id': 'BSD-3-Clause-No-Military-License', 'deprecated': False}, + 'bsd-3-clause-no-nuclear-license': {'id': 'BSD-3-Clause-No-Nuclear-License', 'deprecated': False}, + 'bsd-3-clause-no-nuclear-license-2014': {'id': 'BSD-3-Clause-No-Nuclear-License-2014', 'deprecated': False}, + 'bsd-3-clause-no-nuclear-warranty': {'id': 'BSD-3-Clause-No-Nuclear-Warranty', 'deprecated': False}, + 'bsd-3-clause-open-mpi': {'id': 'BSD-3-Clause-Open-MPI', 'deprecated': False}, + 'bsd-3-clause-sun': {'id': 'BSD-3-Clause-Sun', 'deprecated': False}, + 'bsd-4-clause': {'id': 'BSD-4-Clause', 'deprecated': False}, + 'bsd-4-clause-shortened': {'id': 'BSD-4-Clause-Shortened', 'deprecated': False}, + 'bsd-4-clause-uc': {'id': 'BSD-4-Clause-UC', 'deprecated': False}, + 'bsd-4.3reno': {'id': 'BSD-4.3RENO', 'deprecated': False}, + 'bsd-4.3tahoe': {'id': 'BSD-4.3TAHOE', 'deprecated': False}, + 'bsd-advertising-acknowledgement': {'id': 'BSD-Advertising-Acknowledgement', 'deprecated': False}, + 'bsd-attribution-hpnd-disclaimer': {'id': 'BSD-Attribution-HPND-disclaimer', 'deprecated': False}, + 'bsd-inferno-nettverk': {'id': 'BSD-Inferno-Nettverk', 'deprecated': False}, + 'bsd-protection': {'id': 'BSD-Protection', 'deprecated': False}, + 'bsd-source-beginning-file': {'id': 'BSD-Source-beginning-file', 'deprecated': False}, + 'bsd-source-code': {'id': 'BSD-Source-Code', 'deprecated': False}, + 'bsd-systemics': {'id': 'BSD-Systemics', 'deprecated': False}, + 'bsd-systemics-w3works': {'id': 'BSD-Systemics-W3Works', 'deprecated': False}, + 'bsl-1.0': {'id': 'BSL-1.0', 'deprecated': False}, + 'busl-1.1': {'id': 'BUSL-1.1', 'deprecated': False}, + 'bzip2-1.0.5': {'id': 'bzip2-1.0.5', 'deprecated': True}, + 'bzip2-1.0.6': {'id': 'bzip2-1.0.6', 'deprecated': False}, + 'c-uda-1.0': {'id': 'C-UDA-1.0', 'deprecated': False}, + 'cal-1.0': {'id': 'CAL-1.0', 'deprecated': False}, + 'cal-1.0-combined-work-exception': {'id': 'CAL-1.0-Combined-Work-Exception', 'deprecated': False}, + 'caldera': {'id': 'Caldera', 'deprecated': False}, + 'caldera-no-preamble': {'id': 'Caldera-no-preamble', 'deprecated': False}, + 'catharon': {'id': 'Catharon', 'deprecated': False}, + 'catosl-1.1': {'id': 'CATOSL-1.1', 'deprecated': False}, + 'cc-by-1.0': {'id': 'CC-BY-1.0', 'deprecated': False}, + 'cc-by-2.0': {'id': 'CC-BY-2.0', 'deprecated': False}, + 'cc-by-2.5': {'id': 'CC-BY-2.5', 'deprecated': False}, + 'cc-by-2.5-au': {'id': 'CC-BY-2.5-AU', 'deprecated': False}, + 'cc-by-3.0': {'id': 'CC-BY-3.0', 'deprecated': False}, + 'cc-by-3.0-at': {'id': 'CC-BY-3.0-AT', 'deprecated': False}, + 'cc-by-3.0-au': {'id': 'CC-BY-3.0-AU', 'deprecated': False}, + 'cc-by-3.0-de': {'id': 'CC-BY-3.0-DE', 'deprecated': False}, + 'cc-by-3.0-igo': {'id': 'CC-BY-3.0-IGO', 'deprecated': False}, + 'cc-by-3.0-nl': {'id': 'CC-BY-3.0-NL', 'deprecated': False}, + 'cc-by-3.0-us': {'id': 'CC-BY-3.0-US', 'deprecated': False}, + 'cc-by-4.0': {'id': 'CC-BY-4.0', 'deprecated': False}, + 'cc-by-nc-1.0': {'id': 'CC-BY-NC-1.0', 'deprecated': False}, + 'cc-by-nc-2.0': {'id': 'CC-BY-NC-2.0', 'deprecated': False}, + 'cc-by-nc-2.5': {'id': 'CC-BY-NC-2.5', 'deprecated': False}, + 'cc-by-nc-3.0': {'id': 'CC-BY-NC-3.0', 'deprecated': False}, + 'cc-by-nc-3.0-de': {'id': 'CC-BY-NC-3.0-DE', 'deprecated': False}, + 'cc-by-nc-4.0': {'id': 'CC-BY-NC-4.0', 'deprecated': False}, + 'cc-by-nc-nd-1.0': {'id': 'CC-BY-NC-ND-1.0', 'deprecated': False}, + 'cc-by-nc-nd-2.0': {'id': 'CC-BY-NC-ND-2.0', 'deprecated': False}, + 'cc-by-nc-nd-2.5': {'id': 'CC-BY-NC-ND-2.5', 'deprecated': False}, + 'cc-by-nc-nd-3.0': {'id': 'CC-BY-NC-ND-3.0', 'deprecated': False}, + 'cc-by-nc-nd-3.0-de': {'id': 'CC-BY-NC-ND-3.0-DE', 'deprecated': False}, + 'cc-by-nc-nd-3.0-igo': {'id': 'CC-BY-NC-ND-3.0-IGO', 'deprecated': False}, + 'cc-by-nc-nd-4.0': {'id': 'CC-BY-NC-ND-4.0', 'deprecated': False}, + 'cc-by-nc-sa-1.0': {'id': 'CC-BY-NC-SA-1.0', 'deprecated': False}, + 'cc-by-nc-sa-2.0': {'id': 'CC-BY-NC-SA-2.0', 'deprecated': False}, + 'cc-by-nc-sa-2.0-de': {'id': 'CC-BY-NC-SA-2.0-DE', 'deprecated': False}, + 'cc-by-nc-sa-2.0-fr': {'id': 'CC-BY-NC-SA-2.0-FR', 'deprecated': False}, + 'cc-by-nc-sa-2.0-uk': {'id': 'CC-BY-NC-SA-2.0-UK', 'deprecated': False}, + 'cc-by-nc-sa-2.5': {'id': 'CC-BY-NC-SA-2.5', 'deprecated': False}, + 'cc-by-nc-sa-3.0': {'id': 'CC-BY-NC-SA-3.0', 'deprecated': False}, + 'cc-by-nc-sa-3.0-de': {'id': 'CC-BY-NC-SA-3.0-DE', 'deprecated': False}, + 'cc-by-nc-sa-3.0-igo': {'id': 'CC-BY-NC-SA-3.0-IGO', 'deprecated': False}, + 'cc-by-nc-sa-4.0': {'id': 'CC-BY-NC-SA-4.0', 'deprecated': False}, + 'cc-by-nd-1.0': {'id': 'CC-BY-ND-1.0', 'deprecated': False}, + 'cc-by-nd-2.0': {'id': 'CC-BY-ND-2.0', 'deprecated': False}, + 'cc-by-nd-2.5': {'id': 'CC-BY-ND-2.5', 'deprecated': False}, + 'cc-by-nd-3.0': {'id': 'CC-BY-ND-3.0', 'deprecated': False}, + 'cc-by-nd-3.0-de': {'id': 'CC-BY-ND-3.0-DE', 'deprecated': False}, + 'cc-by-nd-4.0': {'id': 'CC-BY-ND-4.0', 'deprecated': False}, + 'cc-by-sa-1.0': {'id': 'CC-BY-SA-1.0', 'deprecated': False}, + 'cc-by-sa-2.0': {'id': 'CC-BY-SA-2.0', 'deprecated': False}, + 'cc-by-sa-2.0-uk': {'id': 'CC-BY-SA-2.0-UK', 'deprecated': False}, + 'cc-by-sa-2.1-jp': {'id': 'CC-BY-SA-2.1-JP', 'deprecated': False}, + 'cc-by-sa-2.5': {'id': 'CC-BY-SA-2.5', 'deprecated': False}, + 'cc-by-sa-3.0': {'id': 'CC-BY-SA-3.0', 'deprecated': False}, + 'cc-by-sa-3.0-at': {'id': 'CC-BY-SA-3.0-AT', 'deprecated': False}, + 'cc-by-sa-3.0-de': {'id': 'CC-BY-SA-3.0-DE', 'deprecated': False}, + 'cc-by-sa-3.0-igo': {'id': 'CC-BY-SA-3.0-IGO', 'deprecated': False}, + 'cc-by-sa-4.0': {'id': 'CC-BY-SA-4.0', 'deprecated': False}, + 'cc-pddc': {'id': 'CC-PDDC', 'deprecated': False}, + 'cc-pdm-1.0': {'id': 'CC-PDM-1.0', 'deprecated': False}, + 'cc-sa-1.0': {'id': 'CC-SA-1.0', 'deprecated': False}, + 'cc0-1.0': {'id': 'CC0-1.0', 'deprecated': False}, + 'cddl-1.0': {'id': 'CDDL-1.0', 'deprecated': False}, + 'cddl-1.1': {'id': 'CDDL-1.1', 'deprecated': False}, + 'cdl-1.0': {'id': 'CDL-1.0', 'deprecated': False}, + 'cdla-permissive-1.0': {'id': 'CDLA-Permissive-1.0', 'deprecated': False}, + 'cdla-permissive-2.0': {'id': 'CDLA-Permissive-2.0', 'deprecated': False}, + 'cdla-sharing-1.0': {'id': 'CDLA-Sharing-1.0', 'deprecated': False}, + 'cecill-1.0': {'id': 'CECILL-1.0', 'deprecated': False}, + 'cecill-1.1': {'id': 'CECILL-1.1', 'deprecated': False}, + 'cecill-2.0': {'id': 'CECILL-2.0', 'deprecated': False}, + 'cecill-2.1': {'id': 'CECILL-2.1', 'deprecated': False}, + 'cecill-b': {'id': 'CECILL-B', 'deprecated': False}, + 'cecill-c': {'id': 'CECILL-C', 'deprecated': False}, + 'cern-ohl-1.1': {'id': 'CERN-OHL-1.1', 'deprecated': False}, + 'cern-ohl-1.2': {'id': 'CERN-OHL-1.2', 'deprecated': False}, + 'cern-ohl-p-2.0': {'id': 'CERN-OHL-P-2.0', 'deprecated': False}, + 'cern-ohl-s-2.0': {'id': 'CERN-OHL-S-2.0', 'deprecated': False}, + 'cern-ohl-w-2.0': {'id': 'CERN-OHL-W-2.0', 'deprecated': False}, + 'cfitsio': {'id': 'CFITSIO', 'deprecated': False}, + 'check-cvs': {'id': 'check-cvs', 'deprecated': False}, + 'checkmk': {'id': 'checkmk', 'deprecated': False}, + 'clartistic': {'id': 'ClArtistic', 'deprecated': False}, + 'clips': {'id': 'Clips', 'deprecated': False}, + 'cmu-mach': {'id': 'CMU-Mach', 'deprecated': False}, + 'cmu-mach-nodoc': {'id': 'CMU-Mach-nodoc', 'deprecated': False}, + 'cnri-jython': {'id': 'CNRI-Jython', 'deprecated': False}, + 'cnri-python': {'id': 'CNRI-Python', 'deprecated': False}, + 'cnri-python-gpl-compatible': {'id': 'CNRI-Python-GPL-Compatible', 'deprecated': False}, + 'coil-1.0': {'id': 'COIL-1.0', 'deprecated': False}, + 'community-spec-1.0': {'id': 'Community-Spec-1.0', 'deprecated': False}, + 'condor-1.1': {'id': 'Condor-1.1', 'deprecated': False}, + 'copyleft-next-0.3.0': {'id': 'copyleft-next-0.3.0', 'deprecated': False}, + 'copyleft-next-0.3.1': {'id': 'copyleft-next-0.3.1', 'deprecated': False}, + 'cornell-lossless-jpeg': {'id': 'Cornell-Lossless-JPEG', 'deprecated': False}, + 'cpal-1.0': {'id': 'CPAL-1.0', 'deprecated': False}, + 'cpl-1.0': {'id': 'CPL-1.0', 'deprecated': False}, + 'cpol-1.02': {'id': 'CPOL-1.02', 'deprecated': False}, + 'cronyx': {'id': 'Cronyx', 'deprecated': False}, + 'crossword': {'id': 'Crossword', 'deprecated': False}, + 'cryptoswift': {'id': 'CryptoSwift', 'deprecated': False}, + 'crystalstacker': {'id': 'CrystalStacker', 'deprecated': False}, + 'cua-opl-1.0': {'id': 'CUA-OPL-1.0', 'deprecated': False}, + 'cube': {'id': 'Cube', 'deprecated': False}, + 'curl': {'id': 'curl', 'deprecated': False}, + 'cve-tou': {'id': 'cve-tou', 'deprecated': False}, + 'd-fsl-1.0': {'id': 'D-FSL-1.0', 'deprecated': False}, + 'dec-3-clause': {'id': 'DEC-3-Clause', 'deprecated': False}, + 'diffmark': {'id': 'diffmark', 'deprecated': False}, + 'dl-de-by-2.0': {'id': 'DL-DE-BY-2.0', 'deprecated': False}, + 'dl-de-zero-2.0': {'id': 'DL-DE-ZERO-2.0', 'deprecated': False}, + 'doc': {'id': 'DOC', 'deprecated': False}, + 'docbook-dtd': {'id': 'DocBook-DTD', 'deprecated': False}, + 'docbook-schema': {'id': 'DocBook-Schema', 'deprecated': False}, + 'docbook-stylesheet': {'id': 'DocBook-Stylesheet', 'deprecated': False}, + 'docbook-xml': {'id': 'DocBook-XML', 'deprecated': False}, + 'dotseqn': {'id': 'Dotseqn', 'deprecated': False}, + 'drl-1.0': {'id': 'DRL-1.0', 'deprecated': False}, + 'drl-1.1': {'id': 'DRL-1.1', 'deprecated': False}, + 'dsdp': {'id': 'DSDP', 'deprecated': False}, + 'dtoa': {'id': 'dtoa', 'deprecated': False}, + 'dvipdfm': {'id': 'dvipdfm', 'deprecated': False}, + 'ecl-1.0': {'id': 'ECL-1.0', 'deprecated': False}, + 'ecl-2.0': {'id': 'ECL-2.0', 'deprecated': False}, + 'ecos-2.0': {'id': 'eCos-2.0', 'deprecated': True}, + 'efl-1.0': {'id': 'EFL-1.0', 'deprecated': False}, + 'efl-2.0': {'id': 'EFL-2.0', 'deprecated': False}, + 'egenix': {'id': 'eGenix', 'deprecated': False}, + 'elastic-2.0': {'id': 'Elastic-2.0', 'deprecated': False}, + 'entessa': {'id': 'Entessa', 'deprecated': False}, + 'epics': {'id': 'EPICS', 'deprecated': False}, + 'epl-1.0': {'id': 'EPL-1.0', 'deprecated': False}, + 'epl-2.0': {'id': 'EPL-2.0', 'deprecated': False}, + 'erlpl-1.1': {'id': 'ErlPL-1.1', 'deprecated': False}, + 'etalab-2.0': {'id': 'etalab-2.0', 'deprecated': False}, + 'eudatagrid': {'id': 'EUDatagrid', 'deprecated': False}, + 'eupl-1.0': {'id': 'EUPL-1.0', 'deprecated': False}, + 'eupl-1.1': {'id': 'EUPL-1.1', 'deprecated': False}, + 'eupl-1.2': {'id': 'EUPL-1.2', 'deprecated': False}, + 'eurosym': {'id': 'Eurosym', 'deprecated': False}, + 'fair': {'id': 'Fair', 'deprecated': False}, + 'fbm': {'id': 'FBM', 'deprecated': False}, + 'fdk-aac': {'id': 'FDK-AAC', 'deprecated': False}, + 'ferguson-twofish': {'id': 'Ferguson-Twofish', 'deprecated': False}, + 'frameworx-1.0': {'id': 'Frameworx-1.0', 'deprecated': False}, + 'freebsd-doc': {'id': 'FreeBSD-DOC', 'deprecated': False}, + 'freeimage': {'id': 'FreeImage', 'deprecated': False}, + 'fsfap': {'id': 'FSFAP', 'deprecated': False}, + 'fsfap-no-warranty-disclaimer': {'id': 'FSFAP-no-warranty-disclaimer', 'deprecated': False}, + 'fsful': {'id': 'FSFUL', 'deprecated': False}, + 'fsfullr': {'id': 'FSFULLR', 'deprecated': False}, + 'fsfullrsd': {'id': 'FSFULLRSD', 'deprecated': False}, + 'fsfullrwd': {'id': 'FSFULLRWD', 'deprecated': False}, + 'fsl-1.1-alv2': {'id': 'FSL-1.1-ALv2', 'deprecated': False}, + 'fsl-1.1-mit': {'id': 'FSL-1.1-MIT', 'deprecated': False}, + 'ftl': {'id': 'FTL', 'deprecated': False}, + 'furuseth': {'id': 'Furuseth', 'deprecated': False}, + 'fwlw': {'id': 'fwlw', 'deprecated': False}, + 'game-programming-gems': {'id': 'Game-Programming-Gems', 'deprecated': False}, + 'gcr-docs': {'id': 'GCR-docs', 'deprecated': False}, + 'gd': {'id': 'GD', 'deprecated': False}, + 'generic-xts': {'id': 'generic-xts', 'deprecated': False}, + 'gfdl-1.1': {'id': 'GFDL-1.1', 'deprecated': True}, + 'gfdl-1.1-invariants-only': {'id': 'GFDL-1.1-invariants-only', 'deprecated': False}, + 'gfdl-1.1-invariants-or-later': {'id': 'GFDL-1.1-invariants-or-later', 'deprecated': False}, + 'gfdl-1.1-no-invariants-only': {'id': 'GFDL-1.1-no-invariants-only', 'deprecated': False}, + 'gfdl-1.1-no-invariants-or-later': {'id': 'GFDL-1.1-no-invariants-or-later', 'deprecated': False}, + 'gfdl-1.1-only': {'id': 'GFDL-1.1-only', 'deprecated': False}, + 'gfdl-1.1-or-later': {'id': 'GFDL-1.1-or-later', 'deprecated': False}, + 'gfdl-1.2': {'id': 'GFDL-1.2', 'deprecated': True}, + 'gfdl-1.2-invariants-only': {'id': 'GFDL-1.2-invariants-only', 'deprecated': False}, + 'gfdl-1.2-invariants-or-later': {'id': 'GFDL-1.2-invariants-or-later', 'deprecated': False}, + 'gfdl-1.2-no-invariants-only': {'id': 'GFDL-1.2-no-invariants-only', 'deprecated': False}, + 'gfdl-1.2-no-invariants-or-later': {'id': 'GFDL-1.2-no-invariants-or-later', 'deprecated': False}, + 'gfdl-1.2-only': {'id': 'GFDL-1.2-only', 'deprecated': False}, + 'gfdl-1.2-or-later': {'id': 'GFDL-1.2-or-later', 'deprecated': False}, + 'gfdl-1.3': {'id': 'GFDL-1.3', 'deprecated': True}, + 'gfdl-1.3-invariants-only': {'id': 'GFDL-1.3-invariants-only', 'deprecated': False}, + 'gfdl-1.3-invariants-or-later': {'id': 'GFDL-1.3-invariants-or-later', 'deprecated': False}, + 'gfdl-1.3-no-invariants-only': {'id': 'GFDL-1.3-no-invariants-only', 'deprecated': False}, + 'gfdl-1.3-no-invariants-or-later': {'id': 'GFDL-1.3-no-invariants-or-later', 'deprecated': False}, + 'gfdl-1.3-only': {'id': 'GFDL-1.3-only', 'deprecated': False}, + 'gfdl-1.3-or-later': {'id': 'GFDL-1.3-or-later', 'deprecated': False}, + 'giftware': {'id': 'Giftware', 'deprecated': False}, + 'gl2ps': {'id': 'GL2PS', 'deprecated': False}, + 'glide': {'id': 'Glide', 'deprecated': False}, + 'glulxe': {'id': 'Glulxe', 'deprecated': False}, + 'glwtpl': {'id': 'GLWTPL', 'deprecated': False}, + 'gnuplot': {'id': 'gnuplot', 'deprecated': False}, + 'gpl-1.0': {'id': 'GPL-1.0', 'deprecated': True}, + 'gpl-1.0+': {'id': 'GPL-1.0+', 'deprecated': True}, + 'gpl-1.0-only': {'id': 'GPL-1.0-only', 'deprecated': False}, + 'gpl-1.0-or-later': {'id': 'GPL-1.0-or-later', 'deprecated': False}, + 'gpl-2.0': {'id': 'GPL-2.0', 'deprecated': True}, + 'gpl-2.0+': {'id': 'GPL-2.0+', 'deprecated': True}, + 'gpl-2.0-only': {'id': 'GPL-2.0-only', 'deprecated': False}, + 'gpl-2.0-or-later': {'id': 'GPL-2.0-or-later', 'deprecated': False}, + 'gpl-2.0-with-autoconf-exception': {'id': 'GPL-2.0-with-autoconf-exception', 'deprecated': True}, + 'gpl-2.0-with-bison-exception': {'id': 'GPL-2.0-with-bison-exception', 'deprecated': True}, + 'gpl-2.0-with-classpath-exception': {'id': 'GPL-2.0-with-classpath-exception', 'deprecated': True}, + 'gpl-2.0-with-font-exception': {'id': 'GPL-2.0-with-font-exception', 'deprecated': True}, + 'gpl-2.0-with-gcc-exception': {'id': 'GPL-2.0-with-GCC-exception', 'deprecated': True}, + 'gpl-3.0': {'id': 'GPL-3.0', 'deprecated': True}, + 'gpl-3.0+': {'id': 'GPL-3.0+', 'deprecated': True}, + 'gpl-3.0-only': {'id': 'GPL-3.0-only', 'deprecated': False}, + 'gpl-3.0-or-later': {'id': 'GPL-3.0-or-later', 'deprecated': False}, + 'gpl-3.0-with-autoconf-exception': {'id': 'GPL-3.0-with-autoconf-exception', 'deprecated': True}, + 'gpl-3.0-with-gcc-exception': {'id': 'GPL-3.0-with-GCC-exception', 'deprecated': True}, + 'graphics-gems': {'id': 'Graphics-Gems', 'deprecated': False}, + 'gsoap-1.3b': {'id': 'gSOAP-1.3b', 'deprecated': False}, + 'gtkbook': {'id': 'gtkbook', 'deprecated': False}, + 'gutmann': {'id': 'Gutmann', 'deprecated': False}, + 'haskellreport': {'id': 'HaskellReport', 'deprecated': False}, + 'hdf5': {'id': 'HDF5', 'deprecated': False}, + 'hdparm': {'id': 'hdparm', 'deprecated': False}, + 'hidapi': {'id': 'HIDAPI', 'deprecated': False}, + 'hippocratic-2.1': {'id': 'Hippocratic-2.1', 'deprecated': False}, + 'hp-1986': {'id': 'HP-1986', 'deprecated': False}, + 'hp-1989': {'id': 'HP-1989', 'deprecated': False}, + 'hpnd': {'id': 'HPND', 'deprecated': False}, + 'hpnd-dec': {'id': 'HPND-DEC', 'deprecated': False}, + 'hpnd-doc': {'id': 'HPND-doc', 'deprecated': False}, + 'hpnd-doc-sell': {'id': 'HPND-doc-sell', 'deprecated': False}, + 'hpnd-export-us': {'id': 'HPND-export-US', 'deprecated': False}, + 'hpnd-export-us-acknowledgement': {'id': 'HPND-export-US-acknowledgement', 'deprecated': False}, + 'hpnd-export-us-modify': {'id': 'HPND-export-US-modify', 'deprecated': False}, + 'hpnd-export2-us': {'id': 'HPND-export2-US', 'deprecated': False}, + 'hpnd-fenneberg-livingston': {'id': 'HPND-Fenneberg-Livingston', 'deprecated': False}, + 'hpnd-inria-imag': {'id': 'HPND-INRIA-IMAG', 'deprecated': False}, + 'hpnd-intel': {'id': 'HPND-Intel', 'deprecated': False}, + 'hpnd-kevlin-henney': {'id': 'HPND-Kevlin-Henney', 'deprecated': False}, + 'hpnd-markus-kuhn': {'id': 'HPND-Markus-Kuhn', 'deprecated': False}, + 'hpnd-merchantability-variant': {'id': 'HPND-merchantability-variant', 'deprecated': False}, + 'hpnd-mit-disclaimer': {'id': 'HPND-MIT-disclaimer', 'deprecated': False}, + 'hpnd-netrek': {'id': 'HPND-Netrek', 'deprecated': False}, + 'hpnd-pbmplus': {'id': 'HPND-Pbmplus', 'deprecated': False}, + 'hpnd-sell-mit-disclaimer-xserver': {'id': 'HPND-sell-MIT-disclaimer-xserver', 'deprecated': False}, + 'hpnd-sell-regexpr': {'id': 'HPND-sell-regexpr', 'deprecated': False}, + 'hpnd-sell-variant': {'id': 'HPND-sell-variant', 'deprecated': False}, + 'hpnd-sell-variant-mit-disclaimer': {'id': 'HPND-sell-variant-MIT-disclaimer', 'deprecated': False}, + 'hpnd-sell-variant-mit-disclaimer-rev': {'id': 'HPND-sell-variant-MIT-disclaimer-rev', 'deprecated': False}, + 'hpnd-uc': {'id': 'HPND-UC', 'deprecated': False}, + 'hpnd-uc-export-us': {'id': 'HPND-UC-export-US', 'deprecated': False}, + 'htmltidy': {'id': 'HTMLTIDY', 'deprecated': False}, + 'ibm-pibs': {'id': 'IBM-pibs', 'deprecated': False}, + 'icu': {'id': 'ICU', 'deprecated': False}, + 'iec-code-components-eula': {'id': 'IEC-Code-Components-EULA', 'deprecated': False}, + 'ijg': {'id': 'IJG', 'deprecated': False}, + 'ijg-short': {'id': 'IJG-short', 'deprecated': False}, + 'imagemagick': {'id': 'ImageMagick', 'deprecated': False}, + 'imatix': {'id': 'iMatix', 'deprecated': False}, + 'imlib2': {'id': 'Imlib2', 'deprecated': False}, + 'info-zip': {'id': 'Info-ZIP', 'deprecated': False}, + 'inner-net-2.0': {'id': 'Inner-Net-2.0', 'deprecated': False}, + 'innosetup': {'id': 'InnoSetup', 'deprecated': False}, + 'intel': {'id': 'Intel', 'deprecated': False}, + 'intel-acpi': {'id': 'Intel-ACPI', 'deprecated': False}, + 'interbase-1.0': {'id': 'Interbase-1.0', 'deprecated': False}, + 'ipa': {'id': 'IPA', 'deprecated': False}, + 'ipl-1.0': {'id': 'IPL-1.0', 'deprecated': False}, + 'isc': {'id': 'ISC', 'deprecated': False}, + 'isc-veillard': {'id': 'ISC-Veillard', 'deprecated': False}, + 'jam': {'id': 'Jam', 'deprecated': False}, + 'jasper-2.0': {'id': 'JasPer-2.0', 'deprecated': False}, + 'jove': {'id': 'jove', 'deprecated': False}, + 'jpl-image': {'id': 'JPL-image', 'deprecated': False}, + 'jpnic': {'id': 'JPNIC', 'deprecated': False}, + 'json': {'id': 'JSON', 'deprecated': False}, + 'kastrup': {'id': 'Kastrup', 'deprecated': False}, + 'kazlib': {'id': 'Kazlib', 'deprecated': False}, + 'knuth-ctan': {'id': 'Knuth-CTAN', 'deprecated': False}, + 'lal-1.2': {'id': 'LAL-1.2', 'deprecated': False}, + 'lal-1.3': {'id': 'LAL-1.3', 'deprecated': False}, + 'latex2e': {'id': 'Latex2e', 'deprecated': False}, + 'latex2e-translated-notice': {'id': 'Latex2e-translated-notice', 'deprecated': False}, + 'leptonica': {'id': 'Leptonica', 'deprecated': False}, + 'lgpl-2.0': {'id': 'LGPL-2.0', 'deprecated': True}, + 'lgpl-2.0+': {'id': 'LGPL-2.0+', 'deprecated': True}, + 'lgpl-2.0-only': {'id': 'LGPL-2.0-only', 'deprecated': False}, + 'lgpl-2.0-or-later': {'id': 'LGPL-2.0-or-later', 'deprecated': False}, + 'lgpl-2.1': {'id': 'LGPL-2.1', 'deprecated': True}, + 'lgpl-2.1+': {'id': 'LGPL-2.1+', 'deprecated': True}, + 'lgpl-2.1-only': {'id': 'LGPL-2.1-only', 'deprecated': False}, + 'lgpl-2.1-or-later': {'id': 'LGPL-2.1-or-later', 'deprecated': False}, + 'lgpl-3.0': {'id': 'LGPL-3.0', 'deprecated': True}, + 'lgpl-3.0+': {'id': 'LGPL-3.0+', 'deprecated': True}, + 'lgpl-3.0-only': {'id': 'LGPL-3.0-only', 'deprecated': False}, + 'lgpl-3.0-or-later': {'id': 'LGPL-3.0-or-later', 'deprecated': False}, + 'lgpllr': {'id': 'LGPLLR', 'deprecated': False}, + 'libpng': {'id': 'Libpng', 'deprecated': False}, + 'libpng-1.6.35': {'id': 'libpng-1.6.35', 'deprecated': False}, + 'libpng-2.0': {'id': 'libpng-2.0', 'deprecated': False}, + 'libselinux-1.0': {'id': 'libselinux-1.0', 'deprecated': False}, + 'libtiff': {'id': 'libtiff', 'deprecated': False}, + 'libutil-david-nugent': {'id': 'libutil-David-Nugent', 'deprecated': False}, + 'liliq-p-1.1': {'id': 'LiLiQ-P-1.1', 'deprecated': False}, + 'liliq-r-1.1': {'id': 'LiLiQ-R-1.1', 'deprecated': False}, + 'liliq-rplus-1.1': {'id': 'LiLiQ-Rplus-1.1', 'deprecated': False}, + 'linux-man-pages-1-para': {'id': 'Linux-man-pages-1-para', 'deprecated': False}, + 'linux-man-pages-copyleft': {'id': 'Linux-man-pages-copyleft', 'deprecated': False}, + 'linux-man-pages-copyleft-2-para': {'id': 'Linux-man-pages-copyleft-2-para', 'deprecated': False}, + 'linux-man-pages-copyleft-var': {'id': 'Linux-man-pages-copyleft-var', 'deprecated': False}, + 'linux-openib': {'id': 'Linux-OpenIB', 'deprecated': False}, + 'loop': {'id': 'LOOP', 'deprecated': False}, + 'lpd-document': {'id': 'LPD-document', 'deprecated': False}, + 'lpl-1.0': {'id': 'LPL-1.0', 'deprecated': False}, + 'lpl-1.02': {'id': 'LPL-1.02', 'deprecated': False}, + 'lppl-1.0': {'id': 'LPPL-1.0', 'deprecated': False}, + 'lppl-1.1': {'id': 'LPPL-1.1', 'deprecated': False}, + 'lppl-1.2': {'id': 'LPPL-1.2', 'deprecated': False}, + 'lppl-1.3a': {'id': 'LPPL-1.3a', 'deprecated': False}, + 'lppl-1.3c': {'id': 'LPPL-1.3c', 'deprecated': False}, + 'lsof': {'id': 'lsof', 'deprecated': False}, + 'lucida-bitmap-fonts': {'id': 'Lucida-Bitmap-Fonts', 'deprecated': False}, + 'lzma-sdk-9.11-to-9.20': {'id': 'LZMA-SDK-9.11-to-9.20', 'deprecated': False}, + 'lzma-sdk-9.22': {'id': 'LZMA-SDK-9.22', 'deprecated': False}, + 'mackerras-3-clause': {'id': 'Mackerras-3-Clause', 'deprecated': False}, + 'mackerras-3-clause-acknowledgment': {'id': 'Mackerras-3-Clause-acknowledgment', 'deprecated': False}, + 'magaz': {'id': 'magaz', 'deprecated': False}, + 'mailprio': {'id': 'mailprio', 'deprecated': False}, + 'makeindex': {'id': 'MakeIndex', 'deprecated': False}, + 'man2html': {'id': 'man2html', 'deprecated': False}, + 'martin-birgmeier': {'id': 'Martin-Birgmeier', 'deprecated': False}, + 'mcphee-slideshow': {'id': 'McPhee-slideshow', 'deprecated': False}, + 'metamail': {'id': 'metamail', 'deprecated': False}, + 'minpack': {'id': 'Minpack', 'deprecated': False}, + 'mips': {'id': 'MIPS', 'deprecated': False}, + 'miros': {'id': 'MirOS', 'deprecated': False}, + 'mit': {'id': 'MIT', 'deprecated': False}, + 'mit-0': {'id': 'MIT-0', 'deprecated': False}, + 'mit-advertising': {'id': 'MIT-advertising', 'deprecated': False}, + 'mit-click': {'id': 'MIT-Click', 'deprecated': False}, + 'mit-cmu': {'id': 'MIT-CMU', 'deprecated': False}, + 'mit-enna': {'id': 'MIT-enna', 'deprecated': False}, + 'mit-feh': {'id': 'MIT-feh', 'deprecated': False}, + 'mit-festival': {'id': 'MIT-Festival', 'deprecated': False}, + 'mit-khronos-old': {'id': 'MIT-Khronos-old', 'deprecated': False}, + 'mit-modern-variant': {'id': 'MIT-Modern-Variant', 'deprecated': False}, + 'mit-open-group': {'id': 'MIT-open-group', 'deprecated': False}, + 'mit-testregex': {'id': 'MIT-testregex', 'deprecated': False}, + 'mit-wu': {'id': 'MIT-Wu', 'deprecated': False}, + 'mitnfa': {'id': 'MITNFA', 'deprecated': False}, + 'mmixware': {'id': 'MMIXware', 'deprecated': False}, + 'motosoto': {'id': 'Motosoto', 'deprecated': False}, + 'mpeg-ssg': {'id': 'MPEG-SSG', 'deprecated': False}, + 'mpi-permissive': {'id': 'mpi-permissive', 'deprecated': False}, + 'mpich2': {'id': 'mpich2', 'deprecated': False}, + 'mpl-1.0': {'id': 'MPL-1.0', 'deprecated': False}, + 'mpl-1.1': {'id': 'MPL-1.1', 'deprecated': False}, + 'mpl-2.0': {'id': 'MPL-2.0', 'deprecated': False}, + 'mpl-2.0-no-copyleft-exception': {'id': 'MPL-2.0-no-copyleft-exception', 'deprecated': False}, + 'mplus': {'id': 'mplus', 'deprecated': False}, + 'ms-lpl': {'id': 'MS-LPL', 'deprecated': False}, + 'ms-pl': {'id': 'MS-PL', 'deprecated': False}, + 'ms-rl': {'id': 'MS-RL', 'deprecated': False}, + 'mtll': {'id': 'MTLL', 'deprecated': False}, + 'mulanpsl-1.0': {'id': 'MulanPSL-1.0', 'deprecated': False}, + 'mulanpsl-2.0': {'id': 'MulanPSL-2.0', 'deprecated': False}, + 'multics': {'id': 'Multics', 'deprecated': False}, + 'mup': {'id': 'Mup', 'deprecated': False}, + 'naist-2003': {'id': 'NAIST-2003', 'deprecated': False}, + 'nasa-1.3': {'id': 'NASA-1.3', 'deprecated': False}, + 'naumen': {'id': 'Naumen', 'deprecated': False}, + 'nbpl-1.0': {'id': 'NBPL-1.0', 'deprecated': False}, + 'ncbi-pd': {'id': 'NCBI-PD', 'deprecated': False}, + 'ncgl-uk-2.0': {'id': 'NCGL-UK-2.0', 'deprecated': False}, + 'ncl': {'id': 'NCL', 'deprecated': False}, + 'ncsa': {'id': 'NCSA', 'deprecated': False}, + 'net-snmp': {'id': 'Net-SNMP', 'deprecated': True}, + 'netcdf': {'id': 'NetCDF', 'deprecated': False}, + 'newsletr': {'id': 'Newsletr', 'deprecated': False}, + 'ngpl': {'id': 'NGPL', 'deprecated': False}, + 'ngrep': {'id': 'ngrep', 'deprecated': False}, + 'nicta-1.0': {'id': 'NICTA-1.0', 'deprecated': False}, + 'nist-pd': {'id': 'NIST-PD', 'deprecated': False}, + 'nist-pd-fallback': {'id': 'NIST-PD-fallback', 'deprecated': False}, + 'nist-software': {'id': 'NIST-Software', 'deprecated': False}, + 'nlod-1.0': {'id': 'NLOD-1.0', 'deprecated': False}, + 'nlod-2.0': {'id': 'NLOD-2.0', 'deprecated': False}, + 'nlpl': {'id': 'NLPL', 'deprecated': False}, + 'nokia': {'id': 'Nokia', 'deprecated': False}, + 'nosl': {'id': 'NOSL', 'deprecated': False}, + 'noweb': {'id': 'Noweb', 'deprecated': False}, + 'npl-1.0': {'id': 'NPL-1.0', 'deprecated': False}, + 'npl-1.1': {'id': 'NPL-1.1', 'deprecated': False}, + 'nposl-3.0': {'id': 'NPOSL-3.0', 'deprecated': False}, + 'nrl': {'id': 'NRL', 'deprecated': False}, + 'ntia-pd': {'id': 'NTIA-PD', 'deprecated': False}, + 'ntp': {'id': 'NTP', 'deprecated': False}, + 'ntp-0': {'id': 'NTP-0', 'deprecated': False}, + 'nunit': {'id': 'Nunit', 'deprecated': True}, + 'o-uda-1.0': {'id': 'O-UDA-1.0', 'deprecated': False}, + 'oar': {'id': 'OAR', 'deprecated': False}, + 'occt-pl': {'id': 'OCCT-PL', 'deprecated': False}, + 'oclc-2.0': {'id': 'OCLC-2.0', 'deprecated': False}, + 'odbl-1.0': {'id': 'ODbL-1.0', 'deprecated': False}, + 'odc-by-1.0': {'id': 'ODC-By-1.0', 'deprecated': False}, + 'offis': {'id': 'OFFIS', 'deprecated': False}, + 'ofl-1.0': {'id': 'OFL-1.0', 'deprecated': False}, + 'ofl-1.0-no-rfn': {'id': 'OFL-1.0-no-RFN', 'deprecated': False}, + 'ofl-1.0-rfn': {'id': 'OFL-1.0-RFN', 'deprecated': False}, + 'ofl-1.1': {'id': 'OFL-1.1', 'deprecated': False}, + 'ofl-1.1-no-rfn': {'id': 'OFL-1.1-no-RFN', 'deprecated': False}, + 'ofl-1.1-rfn': {'id': 'OFL-1.1-RFN', 'deprecated': False}, + 'ogc-1.0': {'id': 'OGC-1.0', 'deprecated': False}, + 'ogdl-taiwan-1.0': {'id': 'OGDL-Taiwan-1.0', 'deprecated': False}, + 'ogl-canada-2.0': {'id': 'OGL-Canada-2.0', 'deprecated': False}, + 'ogl-uk-1.0': {'id': 'OGL-UK-1.0', 'deprecated': False}, + 'ogl-uk-2.0': {'id': 'OGL-UK-2.0', 'deprecated': False}, + 'ogl-uk-3.0': {'id': 'OGL-UK-3.0', 'deprecated': False}, + 'ogtsl': {'id': 'OGTSL', 'deprecated': False}, + 'oldap-1.1': {'id': 'OLDAP-1.1', 'deprecated': False}, + 'oldap-1.2': {'id': 'OLDAP-1.2', 'deprecated': False}, + 'oldap-1.3': {'id': 'OLDAP-1.3', 'deprecated': False}, + 'oldap-1.4': {'id': 'OLDAP-1.4', 'deprecated': False}, + 'oldap-2.0': {'id': 'OLDAP-2.0', 'deprecated': False}, + 'oldap-2.0.1': {'id': 'OLDAP-2.0.1', 'deprecated': False}, + 'oldap-2.1': {'id': 'OLDAP-2.1', 'deprecated': False}, + 'oldap-2.2': {'id': 'OLDAP-2.2', 'deprecated': False}, + 'oldap-2.2.1': {'id': 'OLDAP-2.2.1', 'deprecated': False}, + 'oldap-2.2.2': {'id': 'OLDAP-2.2.2', 'deprecated': False}, + 'oldap-2.3': {'id': 'OLDAP-2.3', 'deprecated': False}, + 'oldap-2.4': {'id': 'OLDAP-2.4', 'deprecated': False}, + 'oldap-2.5': {'id': 'OLDAP-2.5', 'deprecated': False}, + 'oldap-2.6': {'id': 'OLDAP-2.6', 'deprecated': False}, + 'oldap-2.7': {'id': 'OLDAP-2.7', 'deprecated': False}, + 'oldap-2.8': {'id': 'OLDAP-2.8', 'deprecated': False}, + 'olfl-1.3': {'id': 'OLFL-1.3', 'deprecated': False}, + 'oml': {'id': 'OML', 'deprecated': False}, + 'openpbs-2.3': {'id': 'OpenPBS-2.3', 'deprecated': False}, + 'openssl': {'id': 'OpenSSL', 'deprecated': False}, + 'openssl-standalone': {'id': 'OpenSSL-standalone', 'deprecated': False}, + 'openvision': {'id': 'OpenVision', 'deprecated': False}, + 'opl-1.0': {'id': 'OPL-1.0', 'deprecated': False}, + 'opl-uk-3.0': {'id': 'OPL-UK-3.0', 'deprecated': False}, + 'opubl-1.0': {'id': 'OPUBL-1.0', 'deprecated': False}, + 'oset-pl-2.1': {'id': 'OSET-PL-2.1', 'deprecated': False}, + 'osl-1.0': {'id': 'OSL-1.0', 'deprecated': False}, + 'osl-1.1': {'id': 'OSL-1.1', 'deprecated': False}, + 'osl-2.0': {'id': 'OSL-2.0', 'deprecated': False}, + 'osl-2.1': {'id': 'OSL-2.1', 'deprecated': False}, + 'osl-3.0': {'id': 'OSL-3.0', 'deprecated': False}, + 'padl': {'id': 'PADL', 'deprecated': False}, + 'parity-6.0.0': {'id': 'Parity-6.0.0', 'deprecated': False}, + 'parity-7.0.0': {'id': 'Parity-7.0.0', 'deprecated': False}, + 'pddl-1.0': {'id': 'PDDL-1.0', 'deprecated': False}, + 'php-3.0': {'id': 'PHP-3.0', 'deprecated': False}, + 'php-3.01': {'id': 'PHP-3.01', 'deprecated': False}, + 'pixar': {'id': 'Pixar', 'deprecated': False}, + 'pkgconf': {'id': 'pkgconf', 'deprecated': False}, + 'plexus': {'id': 'Plexus', 'deprecated': False}, + 'pnmstitch': {'id': 'pnmstitch', 'deprecated': False}, + 'polyform-noncommercial-1.0.0': {'id': 'PolyForm-Noncommercial-1.0.0', 'deprecated': False}, + 'polyform-small-business-1.0.0': {'id': 'PolyForm-Small-Business-1.0.0', 'deprecated': False}, + 'postgresql': {'id': 'PostgreSQL', 'deprecated': False}, + 'ppl': {'id': 'PPL', 'deprecated': False}, + 'psf-2.0': {'id': 'PSF-2.0', 'deprecated': False}, + 'psfrag': {'id': 'psfrag', 'deprecated': False}, + 'psutils': {'id': 'psutils', 'deprecated': False}, + 'python-2.0': {'id': 'Python-2.0', 'deprecated': False}, + 'python-2.0.1': {'id': 'Python-2.0.1', 'deprecated': False}, + 'python-ldap': {'id': 'python-ldap', 'deprecated': False}, + 'qhull': {'id': 'Qhull', 'deprecated': False}, + 'qpl-1.0': {'id': 'QPL-1.0', 'deprecated': False}, + 'qpl-1.0-inria-2004': {'id': 'QPL-1.0-INRIA-2004', 'deprecated': False}, + 'radvd': {'id': 'radvd', 'deprecated': False}, + 'rdisc': {'id': 'Rdisc', 'deprecated': False}, + 'rhecos-1.1': {'id': 'RHeCos-1.1', 'deprecated': False}, + 'rpl-1.1': {'id': 'RPL-1.1', 'deprecated': False}, + 'rpl-1.5': {'id': 'RPL-1.5', 'deprecated': False}, + 'rpsl-1.0': {'id': 'RPSL-1.0', 'deprecated': False}, + 'rsa-md': {'id': 'RSA-MD', 'deprecated': False}, + 'rscpl': {'id': 'RSCPL', 'deprecated': False}, + 'ruby': {'id': 'Ruby', 'deprecated': False}, + 'ruby-pty': {'id': 'Ruby-pty', 'deprecated': False}, + 'sax-pd': {'id': 'SAX-PD', 'deprecated': False}, + 'sax-pd-2.0': {'id': 'SAX-PD-2.0', 'deprecated': False}, + 'saxpath': {'id': 'Saxpath', 'deprecated': False}, + 'scea': {'id': 'SCEA', 'deprecated': False}, + 'schemereport': {'id': 'SchemeReport', 'deprecated': False}, + 'sendmail': {'id': 'Sendmail', 'deprecated': False}, + 'sendmail-8.23': {'id': 'Sendmail-8.23', 'deprecated': False}, + 'sendmail-open-source-1.1': {'id': 'Sendmail-Open-Source-1.1', 'deprecated': False}, + 'sgi-b-1.0': {'id': 'SGI-B-1.0', 'deprecated': False}, + 'sgi-b-1.1': {'id': 'SGI-B-1.1', 'deprecated': False}, + 'sgi-b-2.0': {'id': 'SGI-B-2.0', 'deprecated': False}, + 'sgi-opengl': {'id': 'SGI-OpenGL', 'deprecated': False}, + 'sgp4': {'id': 'SGP4', 'deprecated': False}, + 'shl-0.5': {'id': 'SHL-0.5', 'deprecated': False}, + 'shl-0.51': {'id': 'SHL-0.51', 'deprecated': False}, + 'simpl-2.0': {'id': 'SimPL-2.0', 'deprecated': False}, + 'sissl': {'id': 'SISSL', 'deprecated': False}, + 'sissl-1.2': {'id': 'SISSL-1.2', 'deprecated': False}, + 'sl': {'id': 'SL', 'deprecated': False}, + 'sleepycat': {'id': 'Sleepycat', 'deprecated': False}, + 'smail-gpl': {'id': 'SMAIL-GPL', 'deprecated': False}, + 'smlnj': {'id': 'SMLNJ', 'deprecated': False}, + 'smppl': {'id': 'SMPPL', 'deprecated': False}, + 'snia': {'id': 'SNIA', 'deprecated': False}, + 'snprintf': {'id': 'snprintf', 'deprecated': False}, + 'sofa': {'id': 'SOFA', 'deprecated': False}, + 'softsurfer': {'id': 'softSurfer', 'deprecated': False}, + 'soundex': {'id': 'Soundex', 'deprecated': False}, + 'spencer-86': {'id': 'Spencer-86', 'deprecated': False}, + 'spencer-94': {'id': 'Spencer-94', 'deprecated': False}, + 'spencer-99': {'id': 'Spencer-99', 'deprecated': False}, + 'spl-1.0': {'id': 'SPL-1.0', 'deprecated': False}, + 'ssh-keyscan': {'id': 'ssh-keyscan', 'deprecated': False}, + 'ssh-openssh': {'id': 'SSH-OpenSSH', 'deprecated': False}, + 'ssh-short': {'id': 'SSH-short', 'deprecated': False}, + 'ssleay-standalone': {'id': 'SSLeay-standalone', 'deprecated': False}, + 'sspl-1.0': {'id': 'SSPL-1.0', 'deprecated': False}, + 'standardml-nj': {'id': 'StandardML-NJ', 'deprecated': True}, + 'sugarcrm-1.1.3': {'id': 'SugarCRM-1.1.3', 'deprecated': False}, + 'sul-1.0': {'id': 'SUL-1.0', 'deprecated': False}, + 'sun-ppp': {'id': 'Sun-PPP', 'deprecated': False}, + 'sun-ppp-2000': {'id': 'Sun-PPP-2000', 'deprecated': False}, + 'sunpro': {'id': 'SunPro', 'deprecated': False}, + 'swl': {'id': 'SWL', 'deprecated': False}, + 'swrule': {'id': 'swrule', 'deprecated': False}, + 'symlinks': {'id': 'Symlinks', 'deprecated': False}, + 'tapr-ohl-1.0': {'id': 'TAPR-OHL-1.0', 'deprecated': False}, + 'tcl': {'id': 'TCL', 'deprecated': False}, + 'tcp-wrappers': {'id': 'TCP-wrappers', 'deprecated': False}, + 'termreadkey': {'id': 'TermReadKey', 'deprecated': False}, + 'tgppl-1.0': {'id': 'TGPPL-1.0', 'deprecated': False}, + 'thirdeye': {'id': 'ThirdEye', 'deprecated': False}, + 'threeparttable': {'id': 'threeparttable', 'deprecated': False}, + 'tmate': {'id': 'TMate', 'deprecated': False}, + 'torque-1.1': {'id': 'TORQUE-1.1', 'deprecated': False}, + 'tosl': {'id': 'TOSL', 'deprecated': False}, + 'tpdl': {'id': 'TPDL', 'deprecated': False}, + 'tpl-1.0': {'id': 'TPL-1.0', 'deprecated': False}, + 'trustedqsl': {'id': 'TrustedQSL', 'deprecated': False}, + 'ttwl': {'id': 'TTWL', 'deprecated': False}, + 'ttyp0': {'id': 'TTYP0', 'deprecated': False}, + 'tu-berlin-1.0': {'id': 'TU-Berlin-1.0', 'deprecated': False}, + 'tu-berlin-2.0': {'id': 'TU-Berlin-2.0', 'deprecated': False}, + 'ubuntu-font-1.0': {'id': 'Ubuntu-font-1.0', 'deprecated': False}, + 'ucar': {'id': 'UCAR', 'deprecated': False}, + 'ucl-1.0': {'id': 'UCL-1.0', 'deprecated': False}, + 'ulem': {'id': 'ulem', 'deprecated': False}, + 'umich-merit': {'id': 'UMich-Merit', 'deprecated': False}, + 'unicode-3.0': {'id': 'Unicode-3.0', 'deprecated': False}, + 'unicode-dfs-2015': {'id': 'Unicode-DFS-2015', 'deprecated': False}, + 'unicode-dfs-2016': {'id': 'Unicode-DFS-2016', 'deprecated': False}, + 'unicode-tou': {'id': 'Unicode-TOU', 'deprecated': False}, + 'unixcrypt': {'id': 'UnixCrypt', 'deprecated': False}, + 'unlicense': {'id': 'Unlicense', 'deprecated': False}, + 'unlicense-libtelnet': {'id': 'Unlicense-libtelnet', 'deprecated': False}, + 'unlicense-libwhirlpool': {'id': 'Unlicense-libwhirlpool', 'deprecated': False}, + 'upl-1.0': {'id': 'UPL-1.0', 'deprecated': False}, + 'urt-rle': {'id': 'URT-RLE', 'deprecated': False}, + 'vim': {'id': 'Vim', 'deprecated': False}, + 'vostrom': {'id': 'VOSTROM', 'deprecated': False}, + 'vsl-1.0': {'id': 'VSL-1.0', 'deprecated': False}, + 'w3c': {'id': 'W3C', 'deprecated': False}, + 'w3c-19980720': {'id': 'W3C-19980720', 'deprecated': False}, + 'w3c-20150513': {'id': 'W3C-20150513', 'deprecated': False}, + 'w3m': {'id': 'w3m', 'deprecated': False}, + 'watcom-1.0': {'id': 'Watcom-1.0', 'deprecated': False}, + 'widget-workshop': {'id': 'Widget-Workshop', 'deprecated': False}, + 'wsuipa': {'id': 'Wsuipa', 'deprecated': False}, + 'wtfpl': {'id': 'WTFPL', 'deprecated': False}, + 'wwl': {'id': 'wwl', 'deprecated': False}, + 'wxwindows': {'id': 'wxWindows', 'deprecated': True}, + 'x11': {'id': 'X11', 'deprecated': False}, + 'x11-distribute-modifications-variant': {'id': 'X11-distribute-modifications-variant', 'deprecated': False}, + 'x11-swapped': {'id': 'X11-swapped', 'deprecated': False}, + 'xdebug-1.03': {'id': 'Xdebug-1.03', 'deprecated': False}, + 'xerox': {'id': 'Xerox', 'deprecated': False}, + 'xfig': {'id': 'Xfig', 'deprecated': False}, + 'xfree86-1.1': {'id': 'XFree86-1.1', 'deprecated': False}, + 'xinetd': {'id': 'xinetd', 'deprecated': False}, + 'xkeyboard-config-zinoviev': {'id': 'xkeyboard-config-Zinoviev', 'deprecated': False}, + 'xlock': {'id': 'xlock', 'deprecated': False}, + 'xnet': {'id': 'Xnet', 'deprecated': False}, + 'xpp': {'id': 'xpp', 'deprecated': False}, + 'xskat': {'id': 'XSkat', 'deprecated': False}, + 'xzoom': {'id': 'xzoom', 'deprecated': False}, + 'ypl-1.0': {'id': 'YPL-1.0', 'deprecated': False}, + 'ypl-1.1': {'id': 'YPL-1.1', 'deprecated': False}, + 'zed': {'id': 'Zed', 'deprecated': False}, + 'zeeff': {'id': 'Zeeff', 'deprecated': False}, + 'zend-2.0': {'id': 'Zend-2.0', 'deprecated': False}, + 'zimbra-1.3': {'id': 'Zimbra-1.3', 'deprecated': False}, + 'zimbra-1.4': {'id': 'Zimbra-1.4', 'deprecated': False}, + 'zlib': {'id': 'Zlib', 'deprecated': False}, + 'zlib-acknowledgement': {'id': 'zlib-acknowledgement', 'deprecated': False}, + 'zpl-1.1': {'id': 'ZPL-1.1', 'deprecated': False}, + 'zpl-2.0': {'id': 'ZPL-2.0', 'deprecated': False}, + 'zpl-2.1': {'id': 'ZPL-2.1', 'deprecated': False}, +} + +EXCEPTIONS: dict[str, SPDXException] = { + '389-exception': {'id': '389-exception', 'deprecated': False}, + 'asterisk-exception': {'id': 'Asterisk-exception', 'deprecated': False}, + 'asterisk-linking-protocols-exception': {'id': 'Asterisk-linking-protocols-exception', 'deprecated': False}, + 'autoconf-exception-2.0': {'id': 'Autoconf-exception-2.0', 'deprecated': False}, + 'autoconf-exception-3.0': {'id': 'Autoconf-exception-3.0', 'deprecated': False}, + 'autoconf-exception-generic': {'id': 'Autoconf-exception-generic', 'deprecated': False}, + 'autoconf-exception-generic-3.0': {'id': 'Autoconf-exception-generic-3.0', 'deprecated': False}, + 'autoconf-exception-macro': {'id': 'Autoconf-exception-macro', 'deprecated': False}, + 'bison-exception-1.24': {'id': 'Bison-exception-1.24', 'deprecated': False}, + 'bison-exception-2.2': {'id': 'Bison-exception-2.2', 'deprecated': False}, + 'bootloader-exception': {'id': 'Bootloader-exception', 'deprecated': False}, + 'cgal-linking-exception': {'id': 'CGAL-linking-exception', 'deprecated': False}, + 'classpath-exception-2.0': {'id': 'Classpath-exception-2.0', 'deprecated': False}, + 'clisp-exception-2.0': {'id': 'CLISP-exception-2.0', 'deprecated': False}, + 'cryptsetup-openssl-exception': {'id': 'cryptsetup-OpenSSL-exception', 'deprecated': False}, + 'digia-qt-lgpl-exception-1.1': {'id': 'Digia-Qt-LGPL-exception-1.1', 'deprecated': False}, + 'digirule-foss-exception': {'id': 'DigiRule-FOSS-exception', 'deprecated': False}, + 'ecos-exception-2.0': {'id': 'eCos-exception-2.0', 'deprecated': False}, + 'erlang-otp-linking-exception': {'id': 'erlang-otp-linking-exception', 'deprecated': False}, + 'fawkes-runtime-exception': {'id': 'Fawkes-Runtime-exception', 'deprecated': False}, + 'fltk-exception': {'id': 'FLTK-exception', 'deprecated': False}, + 'fmt-exception': {'id': 'fmt-exception', 'deprecated': False}, + 'font-exception-2.0': {'id': 'Font-exception-2.0', 'deprecated': False}, + 'freertos-exception-2.0': {'id': 'freertos-exception-2.0', 'deprecated': False}, + 'gcc-exception-2.0': {'id': 'GCC-exception-2.0', 'deprecated': False}, + 'gcc-exception-2.0-note': {'id': 'GCC-exception-2.0-note', 'deprecated': False}, + 'gcc-exception-3.1': {'id': 'GCC-exception-3.1', 'deprecated': False}, + 'gmsh-exception': {'id': 'Gmsh-exception', 'deprecated': False}, + 'gnat-exception': {'id': 'GNAT-exception', 'deprecated': False}, + 'gnome-examples-exception': {'id': 'GNOME-examples-exception', 'deprecated': False}, + 'gnu-compiler-exception': {'id': 'GNU-compiler-exception', 'deprecated': False}, + 'gnu-javamail-exception': {'id': 'gnu-javamail-exception', 'deprecated': False}, + 'gpl-3.0-389-ds-base-exception': {'id': 'GPL-3.0-389-ds-base-exception', 'deprecated': False}, + 'gpl-3.0-interface-exception': {'id': 'GPL-3.0-interface-exception', 'deprecated': False}, + 'gpl-3.0-linking-exception': {'id': 'GPL-3.0-linking-exception', 'deprecated': False}, + 'gpl-3.0-linking-source-exception': {'id': 'GPL-3.0-linking-source-exception', 'deprecated': False}, + 'gpl-cc-1.0': {'id': 'GPL-CC-1.0', 'deprecated': False}, + 'gstreamer-exception-2005': {'id': 'GStreamer-exception-2005', 'deprecated': False}, + 'gstreamer-exception-2008': {'id': 'GStreamer-exception-2008', 'deprecated': False}, + 'harbour-exception': {'id': 'harbour-exception', 'deprecated': False}, + 'i2p-gpl-java-exception': {'id': 'i2p-gpl-java-exception', 'deprecated': False}, + 'independent-modules-exception': {'id': 'Independent-modules-exception', 'deprecated': False}, + 'kicad-libraries-exception': {'id': 'KiCad-libraries-exception', 'deprecated': False}, + 'lgpl-3.0-linking-exception': {'id': 'LGPL-3.0-linking-exception', 'deprecated': False}, + 'libpri-openh323-exception': {'id': 'libpri-OpenH323-exception', 'deprecated': False}, + 'libtool-exception': {'id': 'Libtool-exception', 'deprecated': False}, + 'linux-syscall-note': {'id': 'Linux-syscall-note', 'deprecated': False}, + 'llgpl': {'id': 'LLGPL', 'deprecated': False}, + 'llvm-exception': {'id': 'LLVM-exception', 'deprecated': False}, + 'lzma-exception': {'id': 'LZMA-exception', 'deprecated': False}, + 'mif-exception': {'id': 'mif-exception', 'deprecated': False}, + 'mxml-exception': {'id': 'mxml-exception', 'deprecated': False}, + 'nokia-qt-exception-1.1': {'id': 'Nokia-Qt-exception-1.1', 'deprecated': True}, + 'ocaml-lgpl-linking-exception': {'id': 'OCaml-LGPL-linking-exception', 'deprecated': False}, + 'occt-exception-1.0': {'id': 'OCCT-exception-1.0', 'deprecated': False}, + 'openjdk-assembly-exception-1.0': {'id': 'OpenJDK-assembly-exception-1.0', 'deprecated': False}, + 'openvpn-openssl-exception': {'id': 'openvpn-openssl-exception', 'deprecated': False}, + 'pcre2-exception': {'id': 'PCRE2-exception', 'deprecated': False}, + 'polyparse-exception': {'id': 'polyparse-exception', 'deprecated': False}, + 'ps-or-pdf-font-exception-20170817': {'id': 'PS-or-PDF-font-exception-20170817', 'deprecated': False}, + 'qpl-1.0-inria-2004-exception': {'id': 'QPL-1.0-INRIA-2004-exception', 'deprecated': False}, + 'qt-gpl-exception-1.0': {'id': 'Qt-GPL-exception-1.0', 'deprecated': False}, + 'qt-lgpl-exception-1.1': {'id': 'Qt-LGPL-exception-1.1', 'deprecated': False}, + 'qwt-exception-1.0': {'id': 'Qwt-exception-1.0', 'deprecated': False}, + 'romic-exception': {'id': 'romic-exception', 'deprecated': False}, + 'rrdtool-floss-exception-2.0': {'id': 'RRDtool-FLOSS-exception-2.0', 'deprecated': False}, + 'sane-exception': {'id': 'SANE-exception', 'deprecated': False}, + 'shl-2.0': {'id': 'SHL-2.0', 'deprecated': False}, + 'shl-2.1': {'id': 'SHL-2.1', 'deprecated': False}, + 'stunnel-exception': {'id': 'stunnel-exception', 'deprecated': False}, + 'swi-exception': {'id': 'SWI-exception', 'deprecated': False}, + 'swift-exception': {'id': 'Swift-exception', 'deprecated': False}, + 'texinfo-exception': {'id': 'Texinfo-exception', 'deprecated': False}, + 'u-boot-exception-2.0': {'id': 'u-boot-exception-2.0', 'deprecated': False}, + 'ubdl-exception': {'id': 'UBDL-exception', 'deprecated': False}, + 'universal-foss-exception-1.0': {'id': 'Universal-FOSS-exception-1.0', 'deprecated': False}, + 'vsftpd-openssl-exception': {'id': 'vsftpd-openssl-exception', 'deprecated': False}, + 'wxwindows-exception-3.1': {'id': 'WxWindows-exception-3.1', 'deprecated': False}, + 'x11vnc-openssl-exception': {'id': 'x11vnc-openssl-exception', 'deprecated': False}, +} diff --git a/.venv/lib/python3.13/site-packages/packaging/markers.py b/.venv/lib/python3.13/site-packages/packaging/markers.py new file mode 100644 index 0000000000000000000000000000000000000000..564451f530bad3dbbd95ae7575835967b1ea45df --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/markers.py @@ -0,0 +1,492 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import annotations + +import operator +import os +import platform +import sys +from typing import AbstractSet, Callable, Literal, Mapping, TypedDict, Union, cast + +from ._parser import MarkerAtom, MarkerList, Op, Value, Variable +from ._parser import parse_marker as _parse_marker +from ._tokenizer import ParserSyntaxError +from .specifiers import InvalidSpecifier, Specifier +from .utils import canonicalize_name + +__all__ = [ + "Environment", + "EvaluateContext", + "InvalidMarker", + "Marker", + "UndefinedComparison", + "UndefinedEnvironmentName", + "default_environment", +] + + +def __dir__() -> list[str]: + return __all__ + + +Operator = Callable[[str, Union[str, AbstractSet[str]]], bool] +EvaluateContext = Literal["metadata", "lock_file", "requirement"] +"""A ``typing.Literal`` enumerating valid marker evaluation contexts. + +Valid values for the ``context`` passed to :meth:`Marker.evaluate` are: + +* ``"metadata"`` (for core metadata; default) +* ``"lock_file"`` (for lock files) +* ``"requirement"`` (i.e. all other situations) +""" + +MARKERS_ALLOWING_SET = {"extras", "dependency_groups"} +MARKERS_REQUIRING_VERSION = { + "implementation_version", + "platform_release", + "python_full_version", + "python_version", +} + + +class InvalidMarker(ValueError): + """Raised when attempting to create a :class:`Marker` from invalid input. + + This error indicates that the given marker string does not conform to the + :ref:`specification of dependency specifiers `. + """ + + +class UndefinedComparison(ValueError): + """Raised when evaluating an unsupported marker comparison. + + This can happen when marker values are compared as versions but do not + conform to the :ref:`specification of version specifiers + `. + """ + + +class UndefinedEnvironmentName(ValueError): + """Raised when evaluating a marker that references a missing environment key.""" + + +class Environment(TypedDict): + """ + A dictionary that represents a Python environment as captured by + :func:`default_environment`. All fields are required. + """ + + implementation_name: str + """The implementation's identifier, e.g. ``'cpython'``.""" + + implementation_version: str + """ + The implementation's version, e.g. ``'3.13.0a2'`` for CPython 3.13.0a2, or + ``'7.3.13'`` for PyPy3.10 v7.3.13. + """ + + os_name: str + """ + The value of :py:data:`os.name`. The name of the operating system dependent module + imported, e.g. ``'posix'``. + """ + + platform_machine: str + """ + Returns the machine type, e.g. ``'i386'``. + + An empty string if the value cannot be determined. + """ + + platform_release: str + """ + The system's release, e.g. ``'2.2.0'`` or ``'NT'``. + + An empty string if the value cannot be determined. + """ + + platform_system: str + """ + The system/OS name, e.g. ``'Linux'``, ``'Windows'`` or ``'Java'``. + + An empty string if the value cannot be determined. + """ + + platform_version: str + """ + The system's release version, e.g. ``'#3 on degas'``. + + An empty string if the value cannot be determined. + """ + + python_full_version: str + """ + The Python version as string ``'major.minor.patchlevel'``. + + Note that unlike the Python :py:data:`sys.version`, this value will always include + the patchlevel (it defaults to 0). + """ + + platform_python_implementation: str + """ + A string identifying the Python implementation, e.g. ``'CPython'``. + """ + + python_version: str + """The Python version as string ``'major.minor'``.""" + + sys_platform: str + """ + This string contains a platform identifier that can be used to append + platform-specific components to :py:data:`sys.path`, for instance. + + For Unix systems, except on Linux and AIX, this is the lowercased OS name as + returned by ``uname -s`` with the first part of the version as returned by + ``uname -r`` appended, e.g. ``'sunos5'`` or ``'freebsd8'``, at the time when Python + was built. + """ + + +def _normalize_extras( + result: MarkerList | MarkerAtom | str, +) -> MarkerList | MarkerAtom | str: + if not isinstance(result, tuple): + return result + + lhs, op, rhs = result + if isinstance(lhs, Variable) and lhs.value == "extra": + normalized_extra = canonicalize_name(rhs.value) + rhs = Value(normalized_extra) + elif isinstance(rhs, Variable) and rhs.value == "extra": + normalized_extra = canonicalize_name(lhs.value) + lhs = Value(normalized_extra) + return lhs, op, rhs + + +def _normalize_extra_values(results: MarkerList) -> MarkerList: + """ + Normalize extra values. + """ + + return [_normalize_extras(r) for r in results] + + +def _format_marker( + marker: list[str] | MarkerAtom | str, first: bool | None = True +) -> str: + assert isinstance(marker, (list, tuple, str)) + + # Sometimes we have a structure like [[...]] which is a single item list + # where the single item is itself it's own list. In that case we want skip + # the rest of this function so that we don't get extraneous () on the + # outside. + if ( + isinstance(marker, list) + and len(marker) == 1 + and isinstance(marker[0], (list, tuple)) + ): + return _format_marker(marker[0]) + + if isinstance(marker, list): + inner = (_format_marker(m, first=False) for m in marker) + if first: + return " ".join(inner) + else: + return "(" + " ".join(inner) + ")" + elif isinstance(marker, tuple): + return " ".join([m.serialize() for m in marker]) + else: + return marker + + +_operators: dict[str, Operator] = { + "in": lambda lhs, rhs: lhs in rhs, + "not in": lambda lhs, rhs: lhs not in rhs, + "<": lambda _lhs, _rhs: False, + "<=": operator.eq, + "==": operator.eq, + "!=": operator.ne, + ">=": operator.eq, + ">": lambda _lhs, _rhs: False, +} + + +def _eval_op(lhs: str, op: Op, rhs: str | AbstractSet[str], *, key: str) -> bool: + op_str = op.serialize() + if key in MARKERS_REQUIRING_VERSION: + try: + spec = Specifier(f"{op_str}{rhs}") + except InvalidSpecifier: + pass + else: + return spec.contains(lhs, prereleases=True) + + oper: Operator | None = _operators.get(op_str) + if oper is None: + raise UndefinedComparison(f"Undefined {op!r} on {lhs!r} and {rhs!r}.") + + return oper(lhs, rhs) + + +def _normalize( + lhs: str, rhs: str | AbstractSet[str], key: str +) -> tuple[str, str | AbstractSet[str]]: + # PEP 685 - Comparison of extra names for optional distribution dependencies + # https://peps.python.org/pep-0685/ + # > When comparing extra names, tools MUST normalize the names being + # > compared using the semantics outlined in PEP 503 for names + if key == "extra": + assert isinstance(rhs, str), "extra value must be a string" + # Both sides are normalized at this point already + return (lhs, rhs) + if key in MARKERS_ALLOWING_SET: + if isinstance(rhs, str): # pragma: no cover + return (canonicalize_name(lhs), canonicalize_name(rhs)) + else: + return (canonicalize_name(lhs), {canonicalize_name(v) for v in rhs}) + + # other environment markers don't have such standards + return lhs, rhs + + +def _evaluate_markers( + markers: MarkerList, environment: dict[str, str | AbstractSet[str]] +) -> bool: + groups: list[list[bool]] = [[]] + + for marker in markers: + if isinstance(marker, list): + groups[-1].append(_evaluate_markers(marker, environment)) + elif isinstance(marker, tuple): + lhs, op, rhs = marker + + if isinstance(lhs, Variable): + environment_key = lhs.value + lhs_value = environment[environment_key] + rhs_value = rhs.value + else: + lhs_value = lhs.value + environment_key = rhs.value + rhs_value = environment[environment_key] + + assert isinstance(lhs_value, str), "lhs must be a string" + lhs_value, rhs_value = _normalize(lhs_value, rhs_value, key=environment_key) + groups[-1].append(_eval_op(lhs_value, op, rhs_value, key=environment_key)) + elif marker == "or": + groups.append([]) + elif marker == "and": + pass + else: # pragma: nocover + raise TypeError(f"Unexpected marker {marker!r}") + + return any(all(item) for item in groups) + + +def _format_full_version(info: sys._version_info) -> str: + version = f"{info.major}.{info.minor}.{info.micro}" + kind = info.releaselevel + if kind != "final": + version += kind[0] + str(info.serial) + return version + + +def default_environment() -> Environment: + """Return the default marker environment for the current Python process. + + This is the base environment used by :meth:`Marker.evaluate`. + """ + iver = _format_full_version(sys.implementation.version) + implementation_name = sys.implementation.name + return { + "implementation_name": implementation_name, + "implementation_version": iver, + "os_name": os.name, + "platform_machine": platform.machine(), + "platform_release": platform.release(), + "platform_system": platform.system(), + "platform_version": platform.version(), + "python_full_version": platform.python_version(), + "platform_python_implementation": platform.python_implementation(), + "python_version": ".".join(platform.python_version_tuple()[:2]), + "sys_platform": sys.platform, + } + + +class Marker: + """Represents a parsed dependency marker expression. + + Marker expressions are parsed according to the + :ref:`specification of dependency specifiers `. + + :param marker: The string representation of a marker expression. + :raises InvalidMarker: If ``marker`` cannot be parsed. + + Instances are safe to serialize with :mod:`pickle`. They use a stable + format so the same pickle can be loaded in future packaging releases. + + .. versionchanged:: 26.2 + + Added a stable pickle format. Pickles created with packaging 26.2+ can + be unpickled with future releases. Backward compatibility with pickles + from packaging < 26.2 is supported but may be removed in a future + release. + """ + + __slots__ = ("_markers",) + + def __init__(self, marker: str) -> None: + # Note: We create a Marker object without calling this constructor in + # packaging.requirements.Requirement. If any additional logic is + # added here, make sure to mirror/adapt Requirement. + + # If this fails and throws an error, the repr still expects _markers to + # be defined. + self._markers: MarkerList = [] + + try: + self._markers = _normalize_extra_values(_parse_marker(marker)) + # The attribute `_markers` can be described in terms of a recursive type: + # MarkerList = List[Union[Tuple[Node, ...], str, MarkerList]] + # + # For example, the following expression: + # python_version > "3.6" or (python_version == "3.6" and os_name == "unix") + # + # is parsed into: + # [ + # (, ')>, ), + # 'and', + # [ + # (, , ), + # 'or', + # (, , ) + # ] + # ] + except ParserSyntaxError as e: + raise InvalidMarker(str(e)) from e + + @classmethod + def _from_markers(cls, markers: MarkerList) -> Marker: + """Create a Marker instance from a pre-parsed marker tree. + + This avoids re-parsing serialised marker strings when combining markers. + """ + new = cls.__new__(cls) + new._markers = markers + return new + + def __str__(self) -> str: + return _format_marker(self._markers) + + def __repr__(self) -> str: + return f"<{self.__class__.__name__}({str(self)!r})>" + + def __hash__(self) -> int: + return hash(str(self)) + + def __eq__(self, other: object) -> bool: + if not isinstance(other, Marker): + return NotImplemented + + return str(self) == str(other) + + def __getstate__(self) -> str: + # Return the marker expression string for compactness and stability. + # Internal Node objects are excluded; the string is re-parsed on load. + return str(self) + + def __setstate__(self, state: object) -> None: + if isinstance(state, str): + # New format (26.2+): just the marker expression string. + try: + self._markers = _normalize_extra_values(_parse_marker(state)) + except ParserSyntaxError as exc: + raise TypeError(f"Cannot restore Marker from {state!r}") from exc + return + if isinstance(state, dict) and "_markers" in state: + # Old format (packaging <= 26.1, no __slots__): plain __dict__. + markers = state["_markers"] + if isinstance(markers, list): + self._markers = markers + return + if isinstance(state, tuple) and len(state) == 2: + # Old format (packaging <= 26.1, __slots__): (None, {slot: value}). + _, slot_dict = state + if isinstance(slot_dict, dict) and "_markers" in slot_dict: + markers = slot_dict["_markers"] + if isinstance(markers, list): + self._markers = markers + return + raise TypeError(f"Cannot restore Marker from {state!r}") + + def __and__(self, other: Marker) -> Marker: + if not isinstance(other, Marker): + return NotImplemented + return self._from_markers([self._markers, "and", other._markers]) + + def __or__(self, other: Marker) -> Marker: + if not isinstance(other, Marker): + return NotImplemented + return self._from_markers([self._markers, "or", other._markers]) + + def evaluate( + self, + environment: Mapping[str, str | AbstractSet[str]] | None = None, + context: EvaluateContext = "metadata", + ) -> bool: + """Evaluate a marker. + + Return the boolean from evaluating this marker against the environment. + The environment is determined from the current Python process unless + passed in explicitly. + + :param environment: Mapping containing keys and values to override the + detected environment. + :param EvaluateContext context: The context in which the marker is + evaluated, which influences what marker names are considered valid. + Accepted values are ``"metadata"`` (for core metadata; default), + ``"lock_file"``, and ``"requirement"`` (i.e. all other situations). + :raises UndefinedComparison: If the marker uses a comparison on values + that are not valid versions per the :ref:`specification of version + specifiers `. + :raises UndefinedEnvironmentName: If the marker references a value that + is missing from the evaluation environment. + :returns: ``True`` if the marker matches, otherwise ``False``. + + """ + current_environment = cast( + "dict[str, str | AbstractSet[str]]", default_environment() + ) + if context == "lock_file": + current_environment.update( + extras=frozenset(), dependency_groups=frozenset() + ) + elif context == "metadata": + current_environment["extra"] = "" + + if environment is not None: + current_environment.update(environment) + if "extra" in current_environment: + # The API used to allow setting extra to None. We need to handle + # this case for backwards compatibility. Also skip running + # normalize name if extra is empty. + extra = cast("str | None", current_environment["extra"]) + current_environment["extra"] = canonicalize_name(extra) if extra else "" + + return _evaluate_markers( + self._markers, _repair_python_full_version(current_environment) + ) + + +def _repair_python_full_version( + env: dict[str, str | AbstractSet[str]], +) -> dict[str, str | AbstractSet[str]]: + """ + Work around platform.python_version() returning something that is not PEP 440 + compliant for non-tagged Python builds. + """ + python_full_version = cast("str", env["python_full_version"]) + if python_full_version.endswith("+"): + env["python_full_version"] = f"{python_full_version}local" + return env diff --git a/.venv/lib/python3.13/site-packages/packaging/metadata.py b/.venv/lib/python3.13/site-packages/packaging/metadata.py new file mode 100644 index 0000000000000000000000000000000000000000..dccb627dea31193b8bb1082223dcdc4305fcfb18 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/metadata.py @@ -0,0 +1,964 @@ +from __future__ import annotations + +import email.header +import email.message +import email.parser +import email.policy +import keyword +import pathlib +import typing +from typing import ( + Any, + Callable, + Generic, + Literal, + TypedDict, + cast, +) + +from . import licenses, requirements, specifiers, utils +from . import version as version_module +from .errors import ExceptionGroup, _ErrorCollector + +if typing.TYPE_CHECKING: + from .licenses import NormalizedLicenseExpression + +T = typing.TypeVar("T") + + +__all__ = [ + "ExceptionGroup", # Keep this for a bit (makes mypy happy w/ 26.0 compat) + "InvalidMetadata", + "Metadata", + "RFC822Message", + "RFC822Policy", + "RawMetadata", + "parse_email", +] + + +def __dir__() -> list[str]: + return __all__ + + +class InvalidMetadata(ValueError): + """A metadata field contains invalid data.""" + + field: str + """The name of the field that contains invalid data.""" + + def __init__(self, field: str, message: str) -> None: + self.field = field + super().__init__(message) + + +# The RawMetadata class attempts to make as few assumptions about the underlying +# serialization formats as possible. The idea is that as long as a serialization +# formats offer some very basic primitives in *some* way then we can support +# serializing to and from that format. +class RawMetadata(TypedDict, total=False): + """A dictionary of raw core metadata. + + Each field in core metadata maps to a key of this dictionary (when data is + provided). The key is lower-case and underscores are used instead of dashes + compared to the equivalent core metadata field. Any core metadata field that + can be specified multiple times or can hold multiple values in a single + field have a key with a plural name. See :class:`Metadata` whose attributes + match the keys of this dictionary. + + Core metadata fields that can be specified multiple times are stored as a + list or dict depending on which is appropriate for the field. Any fields + which hold multiple values in a single field are stored as a list. All fields + are considered optional. + """ + + # Metadata 1.0 - PEP 241 + metadata_version: str + name: str + version: str + platforms: list[str] + summary: str + description: str + keywords: list[str] + home_page: str + author: str + author_email: str + license: str + + # Metadata 1.1 - PEP 314 + supported_platforms: list[str] + download_url: str + classifiers: list[str] + requires: list[str] + provides: list[str] + obsoletes: list[str] + + # Metadata 1.2 - PEP 345 + maintainer: str + maintainer_email: str + requires_dist: list[str] + provides_dist: list[str] + obsoletes_dist: list[str] + requires_python: str + requires_external: list[str] + project_urls: dict[str, str] + + # Metadata 2.0 + # PEP 426 attempted to completely revamp the metadata format + # but got stuck without ever being able to build consensus on + # it and ultimately ended up withdrawn. + # + # However, a number of tools had started emitting METADATA with + # `2.0` Metadata-Version, so for historical reasons, this version + # was skipped. + + # Metadata 2.1 - PEP 566 + description_content_type: str + provides_extra: list[str] + + # Metadata 2.2 - PEP 643 + dynamic: list[str] + + # Metadata 2.3 - PEP 685 + # No new fields were added in PEP 685, just some edge case were + # tightened up to provide better interoperability. + + # Metadata 2.4 - PEP 639 + license_expression: str + license_files: list[str] + + # Metadata 2.5 - PEP 794 + import_names: list[str] + import_namespaces: list[str] + + +# 'keywords' is special as it's a string in the core metadata spec, but we +# represent it as a list. +_STRING_FIELDS = { + "author", + "author_email", + "description", + "description_content_type", + "download_url", + "home_page", + "license", + "license_expression", + "maintainer", + "maintainer_email", + "metadata_version", + "name", + "requires_python", + "summary", + "version", +} + +_LIST_FIELDS = { + "classifiers", + "dynamic", + "license_files", + "obsoletes", + "obsoletes_dist", + "platforms", + "provides", + "provides_dist", + "provides_extra", + "requires", + "requires_dist", + "requires_external", + "supported_platforms", + "import_names", + "import_namespaces", +} + +_DICT_FIELDS = { + "project_urls", +} + + +def _parse_keywords(data: str) -> list[str]: + """Split a string of comma-separated keywords into a list of keywords.""" + return [k.strip() for k in data.split(",")] + + +def _parse_project_urls(data: list[str]) -> dict[str, str]: + """Parse a list of label/URL string pairings separated by a comma.""" + urls = {} + for pair in data: + # Our logic is slightly tricky here as we want to try and do + # *something* reasonable with malformed data. + # + # The main thing that we have to worry about, is data that does + # not have a ',' at all to split the label from the Value. There + # isn't a singular right answer here, and we will fail validation + # later on (if the caller is validating) so it doesn't *really* + # matter, but since the missing value has to be an empty str + # and our return value is dict[str, str], if we let the key + # be the missing value, then they'd have multiple '' values that + # overwrite each other in a accumulating dict. + # + # The other potential issue is that it's possible to have the + # same label multiple times in the metadata, with no solid "right" + # answer with what to do in that case. As such, we'll do the only + # thing we can, which is treat the field as unparsable and add it + # to our list of unparsed fields. + # + # TODO: The spec doesn't say anything about if the keys should be + # considered case sensitive or not... logically they should + # be case-preserving and case-insensitive, but doing that + # would open up more cases where we might have duplicate + # entries. + label, _, url = (s.strip() for s in pair.partition(",")) + + if label in urls: + # The label already exists in our set of urls, so this field + # is unparsable, and we can just add the whole thing to our + # unparsable data and stop processing it. + raise KeyError("duplicate labels in project urls") + urls[label] = url + + return urls + + +def _get_payload(msg: email.message.Message, source: bytes | str) -> str: + """Get the body of the message.""" + # If our source is a str, then our caller has managed encodings for us, + # and we don't need to deal with it. + if isinstance(source, str): + payload = msg.get_payload() + assert isinstance(payload, str) + return payload + # If our source is a bytes, then we're managing the encoding and we need + # to deal with it. + else: + bpayload = msg.get_payload(decode=True) + assert isinstance(bpayload, bytes) + try: + return bpayload.decode("utf8", "strict") + except UnicodeDecodeError as exc: + raise ValueError("payload in an invalid encoding") from exc + + +# The various parse_FORMAT functions here are intended to be as lenient as +# possible in their parsing, while still returning a correctly typed +# RawMetadata. +# +# To aid in this, we also generally want to do as little touching of the +# data as possible, except where there are possibly some historic holdovers +# that make valid data awkward to work with. +# +# While this is a lower level, intermediate format than our ``Metadata`` +# class, some light touch ups can make a massive difference in usability. + +# Map METADATA fields to RawMetadata. +_EMAIL_TO_RAW_MAPPING = { + "author": "author", + "author-email": "author_email", + "classifier": "classifiers", + "description": "description", + "description-content-type": "description_content_type", + "download-url": "download_url", + "dynamic": "dynamic", + "home-page": "home_page", + "import-name": "import_names", + "import-namespace": "import_namespaces", + "keywords": "keywords", + "license": "license", + "license-expression": "license_expression", + "license-file": "license_files", + "maintainer": "maintainer", + "maintainer-email": "maintainer_email", + "metadata-version": "metadata_version", + "name": "name", + "obsoletes": "obsoletes", + "obsoletes-dist": "obsoletes_dist", + "platform": "platforms", + "project-url": "project_urls", + "provides": "provides", + "provides-dist": "provides_dist", + "provides-extra": "provides_extra", + "requires": "requires", + "requires-dist": "requires_dist", + "requires-external": "requires_external", + "requires-python": "requires_python", + "summary": "summary", + "supported-platform": "supported_platforms", + "version": "version", +} +_RAW_TO_EMAIL_MAPPING = {raw: email for email, raw in _EMAIL_TO_RAW_MAPPING.items()} + + +# This class is for writing RFC822 messages +class RFC822Policy(email.policy.EmailPolicy): + """ + This is :class:`email.policy.EmailPolicy`, but with a simple ``header_store_parse`` + implementation that handles multi-line values, and some nice defaults. + """ + + utf8 = True + mangle_from_ = False + max_line_length = 0 + + def header_store_parse(self, name: str, value: str) -> tuple[str, str]: + size = len(name) + 2 + value = value.replace("\n", "\n" + " " * size) + return (name, value) + + +# This class is for writing RFC822 messages +class RFC822Message(email.message.EmailMessage): + """ + This is :class:`email.message.EmailMessage` with two small changes: it defaults to + our `RFC822Policy`, and it correctly writes unicode when being called + with `bytes()`. + """ + + def __init__(self) -> None: + super().__init__(policy=RFC822Policy()) + + def as_bytes( + self, unixfrom: bool = False, policy: email.policy.Policy | None = None + ) -> bytes: + """ + Return the bytes representation of the message. + + This handles unicode encoding. + """ + return self.as_string(unixfrom, policy=policy).encode("utf-8") + + +def parse_email(data: bytes | str) -> tuple[RawMetadata, dict[str, list[str]]]: + """Parse a distribution's metadata stored as email headers (e.g. from ``METADATA``). + + This function returns a two-item tuple of dicts. The first dict is of + recognized fields from the core metadata specification. Fields that can be + parsed and translated into Python's built-in types are converted + appropriately. All other fields are left as-is. Fields that are allowed to + appear multiple times are stored as lists. + + The second dict contains all other fields from the metadata. This includes + any unrecognized fields. It also includes any fields which are expected to + be parsed into a built-in type but were not formatted appropriately. Finally, + any fields that are expected to appear only once but are repeated are + included in this dict. + + """ + raw: dict[str, str | list[str] | dict[str, str]] = {} + unparsed: dict[str, list[str]] = {} + + if isinstance(data, str): + parsed = email.parser.Parser(policy=email.policy.compat32).parsestr(data) + else: + parsed = email.parser.BytesParser(policy=email.policy.compat32).parsebytes(data) + + # We have to wrap parsed.keys() in a set, because in the case of multiple + # values for a key (a list), the key will appear multiple times in the + # list of keys, but we're avoiding that by using get_all(). + for name_with_case in frozenset(parsed.keys()): + # Header names in RFC are case insensitive, so we'll normalize to all + # lower case to make comparisons easier. + name = name_with_case.lower() + + # We use get_all() here, even for fields that aren't multiple use, + # because otherwise someone could have e.g. two Name fields, and we + # would just silently ignore it rather than doing something about it. + headers = parsed.get_all(name) or [] + + # The way the email module works when parsing bytes is that it + # unconditionally decodes the bytes as ascii using the surrogateescape + # handler. When you pull that data back out (such as with get_all() ), + # it looks to see if the str has any surrogate escapes, and if it does + # it wraps it in a Header object instead of returning the string. + # + # As such, we'll look for those Header objects, and fix up the encoding. + value = [] + # Flag if we have run into any issues processing the headers, thus + # signalling that the data belongs in 'unparsed'. + valid_encoding = True + for h in headers: + # It's unclear if this can return more types than just a Header or + # a str, so we'll just assert here to make sure. + assert isinstance(h, (email.header.Header, str)) + + # If it's a header object, we need to do our little dance to get + # the real data out of it. In cases where there is invalid data + # we're going to end up with mojibake, but there's no obvious, good + # way around that without reimplementing parts of the Header object + # ourselves. + # + # That should be fine since, if mojibacked happens, this key is + # going into the unparsed dict anyways. + if isinstance(h, email.header.Header): + # The Header object stores it's data as chunks, and each chunk + # can be independently encoded, so we'll need to check each + # of them. + chunks: list[tuple[bytes, str | None]] = [] + for binary, _encoding in email.header.decode_header(h): + try: + binary.decode("utf8", "strict") + except UnicodeDecodeError: + # Enable mojibake. + encoding = "latin1" + valid_encoding = False + else: + encoding = "utf8" + chunks.append((binary, encoding)) + + # Turn our chunks back into a Header object, then let that + # Header object do the right thing to turn them into a + # string for us. + value.append(str(email.header.make_header(chunks))) + # This is already a string, so just add it. + else: + value.append(h) + + # We've processed all of our values to get them into a list of str, + # but we may have mojibake data, in which case this is an unparsed + # field. + if not valid_encoding: + unparsed[name] = value + continue + + raw_name = _EMAIL_TO_RAW_MAPPING.get(name) + if raw_name is None: + # This is a bit of a weird situation, we've encountered a key that + # we don't know what it means, so we don't know whether it's meant + # to be a list or not. + # + # Since we can't really tell one way or another, we'll just leave it + # as a list, even though it may be a single item list, because that's + # what makes the most sense for email headers. + unparsed[name] = value + continue + + # If this is one of our string fields, then we'll check to see if our + # value is a list of a single item. If it is then we'll assume that + # it was emitted as a single string, and unwrap the str from inside + # the list. + # + # If it's any other kind of data, then we haven't the faintest clue + # what we should parse it as, and we have to just add it to our list + # of unparsed stuff. + if raw_name in _STRING_FIELDS and len(value) == 1: + raw[raw_name] = value[0] + # If this is import_names, we need to special case the empty field + # case, which converts to an empty list instead of None. We can't let + # the empty case slip through, as it will fail validation. + elif raw_name == "import_names" and value == [""]: + raw[raw_name] = [] + # If this is one of our list of string fields, then we can just assign + # the value, since email *only* has strings, and our get_all() call + # above ensures that this is a list. + elif raw_name in _LIST_FIELDS: + raw[raw_name] = value + # Special Case: Keywords + # The keywords field is implemented in the metadata spec as a str, + # but it conceptually is a list of strings, and is serialized using + # ", ".join(keywords), so we'll do some light data massaging to turn + # this into what it logically is. + elif raw_name == "keywords" and len(value) == 1: + raw[raw_name] = _parse_keywords(value[0]) + # Special Case: Project-URL + # The project urls is implemented in the metadata spec as a list of + # specially-formatted strings that represent a key and a value, which + # is fundamentally a mapping, however the email format doesn't support + # mappings in a sane way, so it was crammed into a list of strings + # instead. + # + # We will do a little light data massaging to turn this into a map as + # it logically should be. + elif raw_name == "project_urls": + try: + raw[raw_name] = _parse_project_urls(value) + except KeyError: + unparsed[name] = value + # Nothing that we've done has managed to parse this, so it'll just + # throw it in our unparsable data and move on. + else: + unparsed[name] = value + + # We need to support getting the Description from the message payload in + # addition to getting it from the the headers. This does mean, though, there + # is the possibility of it being set both ways, in which case we put both + # in 'unparsed' since we don't know which is right. + try: + payload = _get_payload(parsed, data) + except ValueError: + unparsed.setdefault("description", []).append( + parsed.get_payload(decode=isinstance(data, bytes)) # type: ignore[call-overload] + ) + else: + if payload: + # Check to see if we've already got a description, if so then both + # it, and this body move to unparsable. + if "description" in raw: + description_header = cast("str", raw.pop("description")) + unparsed.setdefault("description", []).extend( + [description_header, payload] + ) + elif "description" in unparsed: + unparsed["description"].append(payload) + else: + raw["description"] = payload + + # We need to cast our `raw` to a metadata, because a TypedDict only support + # literal key names, but we're computing our key names on purpose, but the + # way this function is implemented, our `TypedDict` can only have valid key + # names. + return cast("RawMetadata", raw), unparsed + + +_NOT_FOUND = object() + + +# Keep the two values in sync. +_VALID_METADATA_VERSIONS = ["1.0", "1.1", "1.2", "2.1", "2.2", "2.3", "2.4", "2.5"] +_MetadataVersion = Literal["1.0", "1.1", "1.2", "2.1", "2.2", "2.3", "2.4", "2.5"] + +_REQUIRED_ATTRS = frozenset(["metadata_version", "name", "version"]) + + +class _Validator(Generic[T]): + """Validate a metadata field. + + All _process_*() methods correspond to a core metadata field. The method is + called with the field's raw value. If the raw value is valid it is returned + in its "enriched" form (e.g. ``version.Version`` for the ``Version`` field). + If the raw value is invalid, :exc:`InvalidMetadata` is raised (with a cause + as appropriate). + """ + + name: str + raw_name: str + added: _MetadataVersion + + def __init__( + self, + *, + added: _MetadataVersion = "1.0", + ) -> None: + self.added = added + + def __set_name__(self, _owner: Metadata, name: str) -> None: + self.name = name + self.raw_name = _RAW_TO_EMAIL_MAPPING[name] + + def __get__(self, instance: Metadata, _owner: type[Metadata]) -> T: + # With Python 3.8, the caching can be replaced with functools.cached_property(). + # No need to check the cache as attribute lookup will resolve into the + # instance's __dict__ before __get__ is called. + cache = instance.__dict__ + value = instance._raw.get(self.name) + + # To make the _process_* methods easier, we'll check if the value is None + # and if this field is NOT a required attribute, and if both of those + # things are true, we'll skip the the converter. This will mean that the + # converters never have to deal with the None union. + if self.name in _REQUIRED_ATTRS or value is not None: + try: + converter: Callable[[Any], T] = getattr(self, f"_process_{self.name}") + except AttributeError: + pass + else: + value = converter(value) + + cache[self.name] = value + try: + del instance._raw[self.name] # type: ignore[misc] + except KeyError: + pass + + return cast("T", value) + + def _invalid_metadata( + self, msg: str, cause: Exception | None = None + ) -> InvalidMetadata: + exc = InvalidMetadata( + self.raw_name, msg.format_map({"field": repr(self.raw_name)}) + ) + exc.__cause__ = cause + return exc + + def _process_metadata_version(self, value: str) -> _MetadataVersion: + # Implicitly makes Metadata-Version required. + if value not in _VALID_METADATA_VERSIONS: + raise self._invalid_metadata(f"{value!r} is not a valid metadata version") + return cast("_MetadataVersion", value) + + def _process_name(self, value: str) -> str: + if not value: + raise self._invalid_metadata("{field} is a required field") + # Validate the name as a side-effect. + try: + utils.canonicalize_name(value, validate=True) + except utils.InvalidName as exc: + raise self._invalid_metadata( + f"{value!r} is invalid for {{field}}", cause=exc + ) from exc + else: + return value + + def _process_version(self, value: str) -> version_module.Version: + if not value: + raise self._invalid_metadata("{field} is a required field") + try: + return version_module.parse(value) + except version_module.InvalidVersion as exc: + raise self._invalid_metadata( + f"{value!r} is invalid for {{field}}", cause=exc + ) from exc + + def _process_summary(self, value: str) -> str: + """Check the field contains no newlines.""" + if "\n" in value: + raise self._invalid_metadata("{field} must be a single line") + return value + + def _process_description_content_type(self, value: str) -> str: + content_types = {"text/plain", "text/x-rst", "text/markdown"} + message = email.message.EmailMessage() + message["content-type"] = value + + content_type, parameters = ( + # Defaults to `text/plain` if parsing failed. + message.get_content_type().lower(), + message["content-type"].params, + ) + # Check if content-type is valid or defaulted to `text/plain` and thus was + # not parseable. + if content_type not in content_types or content_type not in value.lower(): + raise self._invalid_metadata( + f"{{field}} must be one of {list(content_types)}, not {value!r}" + ) + + charset = parameters.get("charset", "UTF-8") + if charset != "UTF-8": + raise self._invalid_metadata( + f"{{field}} can only specify the UTF-8 charset, not {charset!r}" + ) + + markdown_variants = {"GFM", "CommonMark"} + variant = parameters.get("variant", "GFM") # Use an acceptable default. + if content_type == "text/markdown" and variant not in markdown_variants: + raise self._invalid_metadata( + f"valid Markdown variants for {{field}} are {list(markdown_variants)}, " + f"not {variant!r}", + ) + return value + + def _process_dynamic(self, value: list[str]) -> list[str]: + for dynamic_field in map(str.lower, value): + if dynamic_field in {"name", "version", "metadata-version"}: + raise self._invalid_metadata( + f"{dynamic_field!r} is not allowed as a dynamic field" + ) + elif dynamic_field not in _EMAIL_TO_RAW_MAPPING: + raise self._invalid_metadata( + f"{dynamic_field!r} is not a valid dynamic field" + ) + return list(map(str.lower, value)) + + def _process_provides_extra( + self, + value: list[str], + ) -> list[utils.NormalizedName]: + normalized_names = [] + try: + for name in value: + normalized_names.append(utils.canonicalize_name(name, validate=True)) + except utils.InvalidName as exc: + raise self._invalid_metadata( + f"{name!r} is invalid for {{field}}", cause=exc + ) from exc + else: + return normalized_names + + def _process_requires_python(self, value: str) -> specifiers.SpecifierSet: + try: + return specifiers.SpecifierSet(value) + except specifiers.InvalidSpecifier as exc: + raise self._invalid_metadata( + f"{value!r} is invalid for {{field}}", cause=exc + ) from exc + + def _process_requires_dist( + self, + value: list[str], + ) -> list[requirements.Requirement]: + reqs = [] + try: + for req in value: + reqs.append(requirements.Requirement(req)) + except requirements.InvalidRequirement as exc: + raise self._invalid_metadata( + f"{req!r} is invalid for {{field}}", cause=exc + ) from exc + else: + return reqs + + def _process_license_expression(self, value: str) -> NormalizedLicenseExpression: + try: + return licenses.canonicalize_license_expression(value) + except ValueError as exc: + raise self._invalid_metadata( + f"{value!r} is invalid for {{field}}", cause=exc + ) from exc + + def _process_license_files(self, value: list[str]) -> list[str]: + paths = [] + for path in value: + if ".." in path: + raise self._invalid_metadata( + f"{path!r} is invalid for {{field}}, " + "parent directory indicators are not allowed" + ) + if "*" in path: + raise self._invalid_metadata( + f"{path!r} is invalid for {{field}}, paths must be resolved" + ) + if ( + pathlib.PurePosixPath(path).is_absolute() + or pathlib.PureWindowsPath(path).is_absolute() + ): + raise self._invalid_metadata( + f"{path!r} is invalid for {{field}}, paths must be relative" + ) + if pathlib.PureWindowsPath(path).as_posix() != path: + raise self._invalid_metadata( + f"{path!r} is invalid for {{field}}, paths must use '/' delimiter" + ) + paths.append(path) + return paths + + def _process_import_names(self, value: list[str]) -> list[str]: + for import_name in value: + name, semicolon, private = import_name.partition(";") + name = name.rstrip() + for identifier in name.split("."): + if not identifier.isidentifier(): + raise self._invalid_metadata( + f"{name!r} is invalid for {{field}}; " + f"{identifier!r} is not a valid identifier" + ) + elif keyword.iskeyword(identifier): + raise self._invalid_metadata( + f"{name!r} is invalid for {{field}}; " + f"{identifier!r} is a keyword" + ) + if semicolon and private.lstrip() != "private": + raise self._invalid_metadata( + f"{import_name!r} is invalid for {{field}}; " + "the only valid option is 'private'" + ) + return value + + _process_import_namespaces = _process_import_names + + +class Metadata: + """Representation of distribution metadata. + + Compared to :class:`RawMetadata`, this class provides objects representing + metadata fields instead of only using built-in types. Any invalid metadata + will cause :exc:`InvalidMetadata` to be raised (with a + :py:attr:`~BaseException.__cause__` attribute as appropriate). + """ + + _raw: RawMetadata + + @classmethod + def from_raw(cls, data: RawMetadata, *, validate: bool = True) -> Metadata: + """Create an instance from :class:`RawMetadata`. + + If *validate* is true, all metadata will be validated. All exceptions + related to validation will be gathered and raised as an :class:`ExceptionGroup`. + """ + ins = cls() + ins._raw = data.copy() # Mutations occur due to caching enriched values. + + if validate: + collector = _ErrorCollector() + metadata_version = None + with collector.collect(InvalidMetadata): + metadata_version = ins.metadata_version + metadata_age = _VALID_METADATA_VERSIONS.index(metadata_version) + + # Make sure to check for the fields that are present, the required + # fields (so their absence can be reported). + fields_to_check = frozenset(ins._raw) | _REQUIRED_ATTRS + # Remove fields that have already been checked. + fields_to_check -= {"metadata_version"} + + for key in fields_to_check: + try: + if metadata_version: + # Can't use getattr() as that triggers descriptor protocol which + # will fail due to no value for the instance argument. + try: + field_metadata_version = cls.__dict__[key].added + except KeyError: + exc = InvalidMetadata(key, f"unrecognized field: {key!r}") + collector.error(exc) + continue + field_age = _VALID_METADATA_VERSIONS.index( + field_metadata_version + ) + if field_age > metadata_age: + field = _RAW_TO_EMAIL_MAPPING[key] + exc = InvalidMetadata( + field, + f"{field} introduced in metadata version " + f"{field_metadata_version}, not {metadata_version}", + ) + collector.error(exc) + continue + getattr(ins, key) + except InvalidMetadata as exc: + collector.error(exc) + + collector.finalize("invalid metadata") + + return ins + + @classmethod + def from_email(cls, data: bytes | str, *, validate: bool = True) -> Metadata: + """Parse metadata from email headers. + + If *validate* is true, the metadata will be validated. All exceptions + related to validation will be gathered and raised as an :class:`ExceptionGroup`. + """ + raw, unparsed = parse_email(data) + + if validate: + with _ErrorCollector().on_exit("unparsed") as collector: + for unparsed_key in unparsed: + if unparsed_key in _EMAIL_TO_RAW_MAPPING: + message = f"{unparsed_key!r} has invalid data" + else: + message = f"unrecognized field: {unparsed_key!r}" + collector.error(InvalidMetadata(unparsed_key, message)) + + try: + return cls.from_raw(raw, validate=validate) + except ExceptionGroup as exc_group: + raise ExceptionGroup( + "invalid or unparsed metadata", exc_group.exceptions + ) from None + + metadata_version: _Validator[_MetadataVersion] = _Validator() + """:external:ref:`core-metadata-metadata-version` + (required; validated to be a valid metadata version)""" + # `name` is not normalized/typed to NormalizedName so as to provide access to + # the original/raw name. + name: _Validator[str] = _Validator() + """:external:ref:`core-metadata-name` + (required; validated using :func:`~packaging.utils.canonicalize_name` and its + *validate* parameter)""" + version: _Validator[version_module.Version] = _Validator() + """:external:ref:`core-metadata-version` (required)""" + dynamic: _Validator[list[str] | None] = _Validator( + added="2.2", + ) + """:external:ref:`core-metadata-dynamic` + (validated against core metadata field names and lowercased)""" + platforms: _Validator[list[str] | None] = _Validator() + """:external:ref:`core-metadata-platform`""" + supported_platforms: _Validator[list[str] | None] = _Validator(added="1.1") + """:external:ref:`core-metadata-supported-platform`""" + summary: _Validator[str | None] = _Validator() + """:external:ref:`core-metadata-summary` (validated to contain no newlines)""" + description: _Validator[str | None] = _Validator() # TODO 2.1: can be in body + """:external:ref:`core-metadata-description`""" + description_content_type: _Validator[str | None] = _Validator(added="2.1") + """:external:ref:`core-metadata-description-content-type` (validated)""" + keywords: _Validator[list[str] | None] = _Validator() + """:external:ref:`core-metadata-keywords`""" + home_page: _Validator[str | None] = _Validator() + """:external:ref:`core-metadata-home-page`""" + download_url: _Validator[str | None] = _Validator(added="1.1") + """:external:ref:`core-metadata-download-url`""" + author: _Validator[str | None] = _Validator() + """:external:ref:`core-metadata-author`""" + author_email: _Validator[str | None] = _Validator() + """:external:ref:`core-metadata-author-email`""" + maintainer: _Validator[str | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-maintainer`""" + maintainer_email: _Validator[str | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-maintainer-email`""" + license: _Validator[str | None] = _Validator() + """:external:ref:`core-metadata-license`""" + license_expression: _Validator[NormalizedLicenseExpression | None] = _Validator( + added="2.4" + ) + """:external:ref:`core-metadata-license-expression`""" + license_files: _Validator[list[str] | None] = _Validator(added="2.4") + """:external:ref:`core-metadata-license-file`""" + classifiers: _Validator[list[str] | None] = _Validator(added="1.1") + """:external:ref:`core-metadata-classifier`""" + requires_dist: _Validator[list[requirements.Requirement] | None] = _Validator( + added="1.2" + ) + """:external:ref:`core-metadata-requires-dist`""" + requires_python: _Validator[specifiers.SpecifierSet | None] = _Validator( + added="1.2" + ) + """:external:ref:`core-metadata-requires-python`""" + # Because `Requires-External` allows for non-PEP 440 version specifiers, we + # don't do any processing on the values. + requires_external: _Validator[list[str] | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-requires-external`""" + project_urls: _Validator[dict[str, str] | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-project-url`""" + # PEP 685 lets us raise an error if an extra doesn't pass `Name` validation + # regardless of metadata version. + provides_extra: _Validator[list[utils.NormalizedName] | None] = _Validator( + added="2.1", + ) + """:external:ref:`core-metadata-provides-extra`""" + provides_dist: _Validator[list[str] | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-provides-dist`""" + obsoletes_dist: _Validator[list[str] | None] = _Validator(added="1.2") + """:external:ref:`core-metadata-obsoletes-dist`""" + import_names: _Validator[list[str] | None] = _Validator(added="2.5") + """:external:ref:`core-metadata-import-name`""" + import_namespaces: _Validator[list[str] | None] = _Validator(added="2.5") + """:external:ref:`core-metadata-import-namespace`""" + requires: _Validator[list[str] | None] = _Validator(added="1.1") + """``Requires`` (deprecated)""" + provides: _Validator[list[str] | None] = _Validator(added="1.1") + """``Provides`` (deprecated)""" + obsoletes: _Validator[list[str] | None] = _Validator(added="1.1") + """``Obsoletes`` (deprecated)""" + + def as_rfc822(self) -> RFC822Message: + """ + Return an RFC822 message with the metadata. + """ + message = RFC822Message() + self._write_metadata(message) + return message + + def _write_metadata(self, message: RFC822Message) -> None: + """ + Return an RFC822 message with the metadata. + """ + for name, validator in self.__class__.__dict__.items(): + if isinstance(validator, _Validator) and name != "description": + value = getattr(self, name) + email_name = _RAW_TO_EMAIL_MAPPING[name] + if value is not None: + if email_name == "project-url": + for label, url in value.items(): + message[email_name] = f"{label}, {url}" + elif email_name == "keywords": + message[email_name] = ",".join(value) + elif email_name == "import-name" and value == []: + message[email_name] = "" + elif isinstance(value, list): + for item in value: + message[email_name] = str(item) + else: + message[email_name] = str(value) + + # The description is a special case because it is in the body of the message. + if self.description is not None: + message.set_payload(self.description) diff --git a/.venv/lib/python3.13/site-packages/packaging/py.typed b/.venv/lib/python3.13/site-packages/packaging/py.typed new file mode 100644 index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391 diff --git a/.venv/lib/python3.13/site-packages/packaging/pylock.py b/.venv/lib/python3.13/site-packages/packaging/pylock.py new file mode 100644 index 0000000000000000000000000000000000000000..84e25378fc6fa21d2d637dbcc6cd43c0dd2ad1d4 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/pylock.py @@ -0,0 +1,905 @@ +from __future__ import annotations + +import dataclasses +import logging +import re +from collections.abc import Mapping, Sequence +from dataclasses import dataclass +from datetime import datetime +from typing import ( + TYPE_CHECKING, + Any, + Callable, + Protocol, + TypeVar, + cast, +) +from urllib.parse import urlparse + +from .markers import Environment, Marker, default_environment +from .specifiers import SpecifierSet +from .tags import create_compatible_tags_selector, sys_tags +from .utils import ( + NormalizedName, + is_normalized_name, + parse_sdist_filename, + parse_wheel_filename, +) +from .version import Version + +if TYPE_CHECKING: # pragma: no cover + from collections.abc import Collection, Iterator + from pathlib import Path + + from typing_extensions import Self + + from .tags import Tag + +_logger = logging.getLogger(__name__) + +__all__ = [ + "Package", + "PackageArchive", + "PackageDirectory", + "PackageSdist", + "PackageVcs", + "PackageWheel", + "Pylock", + "PylockUnsupportedVersionError", + "PylockValidationError", + "is_valid_pylock_path", +] + + +def __dir__() -> list[str]: + return __all__ + + +_T = TypeVar("_T") +_T2 = TypeVar("_T2") + + +class _FromMappingProtocol(Protocol): # pragma: no cover + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: ... + + +_FromMappingProtocolT = TypeVar("_FromMappingProtocolT", bound=_FromMappingProtocol) + + +_PYLOCK_FILE_NAME_RE = re.compile(r"^pylock\.([^.]+)\.toml$") + + +def is_valid_pylock_path(path: Path) -> bool: + """Check if the given path is a valid pylock file path.""" + return path.name == "pylock.toml" or bool(_PYLOCK_FILE_NAME_RE.match(path.name)) + + +def _toml_key(key: str) -> str: + return key.replace("_", "-") + + +def _toml_value(key: str, value: Any) -> Any: # noqa: ANN401 + if isinstance(value, (Version, Marker, SpecifierSet)): + return str(value) + if isinstance(value, Sequence) and key == "environments": + return [str(v) for v in value] + return value + + +def _toml_dict_factory(data: list[tuple[str, Any]]) -> dict[str, Any]: + return { + _toml_key(key): _toml_value(key, value) + for key, value in data + if value is not None + } + + +def _get(d: Mapping[str, Any], expected_type: type[_T], key: str) -> _T | None: + """Get a value from the dictionary and verify it's the expected type.""" + if (value := d.get(key)) is None: + return None + if not isinstance(value, expected_type): + raise PylockValidationError( + f"Unexpected type {type(value).__name__} " + f"(expected {expected_type.__name__})", + context=key, + ) + return value + + +def _get_required(d: Mapping[str, Any], expected_type: type[_T], key: str) -> _T: + """Get a required value from the dictionary and verify it's the expected type.""" + if (value := _get(d, expected_type, key)) is None: + raise _PylockRequiredKeyError(key) + return value + + +def _get_sequence( + d: Mapping[str, Any], expected_item_type: type[_T], key: str +) -> Sequence[_T] | None: + """Get a list value from the dictionary and verify it's the expected items type.""" + if (value := _get(d, Sequence, key)) is None: # type: ignore[type-abstract] + return None + if isinstance(value, (str, bytes)): + # special case: str and bytes are Sequences, but we want to reject it + raise PylockValidationError( + f"Unexpected type {type(value).__name__} (expected Sequence)", + context=key, + ) + for i, item in enumerate(value): + if not isinstance(item, expected_item_type): + raise PylockValidationError( + f"Unexpected type {type(item).__name__} " + f"(expected {expected_item_type.__name__})", + context=f"{key}[{i}]", + ) + return value + + +def _get_as( + d: Mapping[str, Any], + expected_type: type[_T], + target_type: Callable[[_T], _T2], + key: str, +) -> _T2 | None: + """Get a value from the dictionary, verify it's the expected type, + and convert to the target type. + + This assumes the target_type constructor accepts the value. + """ + if (value := _get(d, expected_type, key)) is None: + return None + try: + return target_type(value) + except Exception as e: + raise PylockValidationError(e, context=key) from e + + +def _get_required_as( + d: Mapping[str, Any], + expected_type: type[_T], + target_type: Callable[[_T], _T2], + key: str, +) -> _T2: + """Get a required value from the dict, verify it's the expected type, + and convert to the target type.""" + if (value := _get_as(d, expected_type, target_type, key)) is None: + raise _PylockRequiredKeyError(key) + return value + + +def _get_sequence_as( + d: Mapping[str, Any], + expected_item_type: type[_T], + target_item_type: Callable[[_T], _T2], + key: str, +) -> list[_T2] | None: + """Get list value from dictionary and verify expected items type.""" + if (value := _get_sequence(d, expected_item_type, key)) is None: + return None + result = [] + try: + for item in value: + typed_item = target_item_type(item) + result.append(typed_item) + except Exception as e: + raise PylockValidationError(e, context=f"{key}[{len(result)}]") from e + return result + + +def _get_object( + d: Mapping[str, Any], target_type: type[_FromMappingProtocolT], key: str +) -> _FromMappingProtocolT | None: + """Get a dictionary value from the dictionary and convert it to a dataclass.""" + if (value := _get(d, Mapping, key)) is None: # type: ignore[type-abstract] + return None + try: + return target_type._from_dict(value) + except Exception as e: + raise PylockValidationError(e, context=key) from e + + +def _get_sequence_of_objects( + d: Mapping[str, Any], target_item_type: type[_FromMappingProtocolT], key: str +) -> list[_FromMappingProtocolT] | None: + """Get a list value from the dictionary and convert its items to a dataclass.""" + if (value := _get_sequence(d, Mapping, key)) is None: # type: ignore[type-abstract] + return None + result: list[_FromMappingProtocolT] = [] + try: + for item in value: + typed_item = target_item_type._from_dict(item) + result.append(typed_item) + except Exception as e: + raise PylockValidationError(e, context=f"{key}[{len(result)}]") from e + return result + + +def _get_required_sequence_of_objects( + d: Mapping[str, Any], target_item_type: type[_FromMappingProtocolT], key: str +) -> Sequence[_FromMappingProtocolT]: + """Get a required list value from the dictionary and convert its items to a + dataclass.""" + if (result := _get_sequence_of_objects(d, target_item_type, key)) is None: + raise _PylockRequiredKeyError(key) + return result + + +def _validate_normalized_name(name: str) -> NormalizedName: + """Validate that a string is a NormalizedName.""" + if not is_normalized_name(name): + raise PylockValidationError(f"Name {name!r} is not normalized") + return NormalizedName(name) + + +def _validate_path_url(path: str | None, url: str | None) -> None: + if not path and not url: + raise PylockValidationError("path or url must be provided") + + +def _path_name(path: str | None) -> str | None: + if not path: + return None + # If the path is relative it MAY use POSIX-style path separators explicitly + # for portability + if "/" in path: + return path.rsplit("/", 1)[-1] + elif "\\" in path: + return path.rsplit("\\", 1)[-1] + else: + return path + + +def _url_name(url: str | None) -> str | None: + if not url: + return None + url_path = urlparse(url).path + return url_path.rsplit("/", 1)[-1] + + +def _validate_hashes(hashes: Mapping[str, Any]) -> Mapping[str, Any]: + if not hashes: + raise PylockValidationError("At least one hash must be provided") + if not all(isinstance(hash_val, str) for hash_val in hashes.values()): + raise PylockValidationError("Hash values must be strings") + return hashes + + +class PylockValidationError(Exception): + """Raised when when input data is not spec-compliant.""" + + context: str | None = None + message: str + + def __init__( + self, + cause: str | Exception, + *, + context: str | None = None, + ) -> None: + if isinstance(cause, PylockValidationError): + if cause.context: + self.context = ( + f"{context}.{cause.context}" if context else cause.context + ) + else: + self.context = context + self.message = cause.message + else: + self.context = context + self.message = str(cause) + + def __str__(self) -> str: + if self.context: + return f"{self.message} in {self.context!r}" + return self.message + + +class _PylockRequiredKeyError(PylockValidationError): + def __init__(self, key: str) -> None: + super().__init__("Missing required value", context=key) + + +class PylockUnsupportedVersionError(PylockValidationError): + """Raised when encountering an unsupported `lock_version`.""" + + +class PylockSelectError(Exception): + """Base exception for errors raised by :meth:`Pylock.select`.""" + + +@dataclass(frozen=True, init=False) +class PackageVcs: + type: str + url: str | None = None + path: str | None = None + requested_revision: str | None = None + commit_id: str # type: ignore[misc] + subdirectory: str | None = None + + def __init__( + self, + *, + type: str, + url: str | None = None, + path: str | None = None, + requested_revision: str | None = None, + commit_id: str, + subdirectory: str | None = None, + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "type", type) + object.__setattr__(self, "url", url) + object.__setattr__(self, "path", path) + object.__setattr__(self, "requested_revision", requested_revision) + object.__setattr__(self, "commit_id", commit_id) + object.__setattr__(self, "subdirectory", subdirectory) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + package_vcs = cls( + type=_get_required(d, str, "type"), + url=_get(d, str, "url"), + path=_get(d, str, "path"), + requested_revision=_get(d, str, "requested-revision"), + commit_id=_get_required(d, str, "commit-id"), + subdirectory=_get(d, str, "subdirectory"), + ) + _validate_path_url(package_vcs.path, package_vcs.url) + return package_vcs + + +@dataclass(frozen=True, init=False) +class PackageDirectory: + path: str + editable: bool | None = None + subdirectory: str | None = None + + def __init__( + self, + *, + path: str, + editable: bool | None = None, + subdirectory: str | None = None, + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "path", path) + object.__setattr__(self, "editable", editable) + object.__setattr__(self, "subdirectory", subdirectory) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + return cls( + path=_get_required(d, str, "path"), + editable=_get(d, bool, "editable"), + subdirectory=_get(d, str, "subdirectory"), + ) + + +@dataclass(frozen=True, init=False) +class PackageArchive: + url: str | None = None + path: str | None = None + size: int | None = None + upload_time: datetime | None = None + hashes: Mapping[str, str] # type: ignore[misc] + subdirectory: str | None = None + + def __init__( + self, + *, + url: str | None = None, + path: str | None = None, + size: int | None = None, + upload_time: datetime | None = None, + hashes: Mapping[str, str], + subdirectory: str | None = None, + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "url", url) + object.__setattr__(self, "path", path) + object.__setattr__(self, "size", size) + object.__setattr__(self, "upload_time", upload_time) + object.__setattr__(self, "hashes", hashes) + object.__setattr__(self, "subdirectory", subdirectory) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + package_archive = cls( + url=_get(d, str, "url"), + path=_get(d, str, "path"), + size=_get(d, int, "size"), + upload_time=_get(d, datetime, "upload-time"), + hashes=_get_required_as(d, Mapping, _validate_hashes, "hashes"), # type: ignore[type-abstract] + subdirectory=_get(d, str, "subdirectory"), + ) + _validate_path_url(package_archive.path, package_archive.url) + return package_archive + + +@dataclass(frozen=True, init=False) +class PackageSdist: + name: str | None = None + upload_time: datetime | None = None + url: str | None = None + path: str | None = None + size: int | None = None + hashes: Mapping[str, str] # type: ignore[misc] + + def __init__( + self, + *, + name: str | None = None, + upload_time: datetime | None = None, + url: str | None = None, + path: str | None = None, + size: int | None = None, + hashes: Mapping[str, str], + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "name", name) + object.__setattr__(self, "upload_time", upload_time) + object.__setattr__(self, "url", url) + object.__setattr__(self, "path", path) + object.__setattr__(self, "size", size) + object.__setattr__(self, "hashes", hashes) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + package_sdist = cls( + name=_get(d, str, "name"), + upload_time=_get(d, datetime, "upload-time"), + url=_get(d, str, "url"), + path=_get(d, str, "path"), + size=_get(d, int, "size"), + hashes=_get_required_as(d, Mapping, _validate_hashes, "hashes"), # type: ignore[type-abstract] + ) + _validate_path_url(package_sdist.path, package_sdist.url) + return package_sdist + + @property + def filename(self) -> str: + """Get the filename of the sdist.""" + filename = self.name or _path_name(self.path) or _url_name(self.url) + if not filename: + raise PylockValidationError("Cannot determine sdist filename") + return filename + + +@dataclass(frozen=True, init=False) +class PackageWheel: + name: str | None = None + upload_time: datetime | None = None + url: str | None = None + path: str | None = None + size: int | None = None + hashes: Mapping[str, str] # type: ignore[misc] + + def __init__( + self, + *, + name: str | None = None, + upload_time: datetime | None = None, + url: str | None = None, + path: str | None = None, + size: int | None = None, + hashes: Mapping[str, str], + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "name", name) + object.__setattr__(self, "upload_time", upload_time) + object.__setattr__(self, "url", url) + object.__setattr__(self, "path", path) + object.__setattr__(self, "size", size) + object.__setattr__(self, "hashes", hashes) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + package_wheel = cls( + name=_get(d, str, "name"), + upload_time=_get(d, datetime, "upload-time"), + url=_get(d, str, "url"), + path=_get(d, str, "path"), + size=_get(d, int, "size"), + hashes=_get_required_as(d, Mapping, _validate_hashes, "hashes"), # type: ignore[type-abstract] + ) + _validate_path_url(package_wheel.path, package_wheel.url) + return package_wheel + + @property + def filename(self) -> str: + """Get the filename of the wheel.""" + filename = self.name or _path_name(self.path) or _url_name(self.url) + if not filename: + raise PylockValidationError("Cannot determine wheel filename") + return filename + + +@dataclass(frozen=True, init=False) +class Package: + name: NormalizedName + version: Version | None = None + marker: Marker | None = None + requires_python: SpecifierSet | None = None + dependencies: Sequence[Mapping[str, Any]] | None = None + vcs: PackageVcs | None = None + directory: PackageDirectory | None = None + archive: PackageArchive | None = None + index: str | None = None + sdist: PackageSdist | None = None + wheels: Sequence[PackageWheel] | None = None + attestation_identities: Sequence[Mapping[str, Any]] | None = None + tool: Mapping[str, Any] | None = None + + def __init__( + self, + *, + name: NormalizedName, + version: Version | None = None, + marker: Marker | None = None, + requires_python: SpecifierSet | None = None, + dependencies: Sequence[Mapping[str, Any]] | None = None, + vcs: PackageVcs | None = None, + directory: PackageDirectory | None = None, + archive: PackageArchive | None = None, + index: str | None = None, + sdist: PackageSdist | None = None, + wheels: Sequence[PackageWheel] | None = None, + attestation_identities: Sequence[Mapping[str, Any]] | None = None, + tool: Mapping[str, Any] | None = None, + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "name", name) + object.__setattr__(self, "version", version) + object.__setattr__(self, "marker", marker) + object.__setattr__(self, "requires_python", requires_python) + object.__setattr__(self, "dependencies", dependencies) + object.__setattr__(self, "vcs", vcs) + object.__setattr__(self, "directory", directory) + object.__setattr__(self, "archive", archive) + object.__setattr__(self, "index", index) + object.__setattr__(self, "sdist", sdist) + object.__setattr__(self, "wheels", wheels) + object.__setattr__(self, "attestation_identities", attestation_identities) + object.__setattr__(self, "tool", tool) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + package = cls( + name=_get_required_as(d, str, _validate_normalized_name, "name"), + version=_get_as(d, str, Version, "version"), + requires_python=_get_as(d, str, SpecifierSet, "requires-python"), + dependencies=_get_sequence(d, Mapping, "dependencies"), # type: ignore[type-abstract] + marker=_get_as(d, str, Marker, "marker"), + vcs=_get_object(d, PackageVcs, "vcs"), + directory=_get_object(d, PackageDirectory, "directory"), + archive=_get_object(d, PackageArchive, "archive"), + index=_get(d, str, "index"), + sdist=_get_object(d, PackageSdist, "sdist"), + wheels=_get_sequence_of_objects(d, PackageWheel, "wheels"), + attestation_identities=_get_sequence(d, Mapping, "attestation-identities"), # type: ignore[type-abstract] + tool=_get(d, Mapping, "tool"), # type: ignore[type-abstract] + ) + distributions = bool(package.sdist) + len(package.wheels or []) + direct_urls = ( + bool(package.vcs) + bool(package.directory) + bool(package.archive) + ) + if distributions > 0 and direct_urls > 0: + raise PylockValidationError( + "None of vcs, directory, archive must be set if sdist or wheels are set" + ) + if distributions == 0 and direct_urls != 1: + raise PylockValidationError( + "Exactly one of vcs, directory, archive must be set " + "if sdist and wheels are not set" + ) + for i, wheel in enumerate(package.wheels or []): + try: + (name, version, _, _) = parse_wheel_filename(wheel.filename) + except Exception as e: + raise PylockValidationError( + f"Invalid wheel filename {wheel.filename!r}", + context=f"wheels[{i}]", + ) from e + if name != package.name: + raise PylockValidationError( + f"Name in {wheel.filename!r} is not consistent with " + f"package name {package.name!r}", + context=f"wheels[{i}]", + ) + if package.version and version != package.version: + raise PylockValidationError( + f"Version in {wheel.filename!r} is not consistent with " + f"package version {str(package.version)!r}", + context=f"wheels[{i}]", + ) + if package.sdist: + try: + name, version = parse_sdist_filename(package.sdist.filename) + except Exception as e: + raise PylockValidationError( + f"Invalid sdist filename {package.sdist.filename!r}", + context="sdist", + ) from e + if name != package.name: + raise PylockValidationError( + f"Name in {package.sdist.filename!r} is not consistent with " + f"package name {package.name!r}", + context="sdist", + ) + if package.version and version != package.version: + raise PylockValidationError( + f"Version in {package.sdist.filename!r} is not consistent with " + f"package version {str(package.version)!r}", + context="sdist", + ) + try: + for i, attestation_identity in enumerate( # noqa: B007 + package.attestation_identities or [] + ): + _get_required(attestation_identity, str, "kind") + except Exception as e: + raise PylockValidationError( + e, context=f"attestation-identities[{i}]" + ) from e + return package + + @property + def is_direct(self) -> bool: + return not (self.sdist or self.wheels) + + +@dataclass(frozen=True, init=False) +class Pylock: + """A class representing a pylock file.""" + + lock_version: Version + environments: Sequence[Marker] | None = None + requires_python: SpecifierSet | None = None + extras: Sequence[NormalizedName] | None = None + dependency_groups: Sequence[str] | None = None + default_groups: Sequence[str] | None = None + created_by: str # type: ignore[misc] + packages: Sequence[Package] # type: ignore[misc] + tool: Mapping[str, Any] | None = None + + def __init__( + self, + *, + lock_version: Version, + environments: Sequence[Marker] | None = None, + requires_python: SpecifierSet | None = None, + extras: Sequence[NormalizedName] | None = None, + dependency_groups: Sequence[str] | None = None, + default_groups: Sequence[str] | None = None, + created_by: str, + packages: Sequence[Package], + tool: Mapping[str, Any] | None = None, + ) -> None: + # In Python 3.10+ make dataclass kw_only=True and remove __init__ + object.__setattr__(self, "lock_version", lock_version) + object.__setattr__(self, "environments", environments) + object.__setattr__(self, "requires_python", requires_python) + object.__setattr__(self, "extras", extras) + object.__setattr__(self, "dependency_groups", dependency_groups) + object.__setattr__(self, "default_groups", default_groups) + object.__setattr__(self, "created_by", created_by) + object.__setattr__(self, "packages", packages) + object.__setattr__(self, "tool", tool) + + @classmethod + def _from_dict(cls, d: Mapping[str, Any]) -> Self: + pylock = cls( + lock_version=_get_required_as(d, str, Version, "lock-version"), + environments=_get_sequence_as(d, str, Marker, "environments"), + extras=_get_sequence_as(d, str, _validate_normalized_name, "extras"), + dependency_groups=_get_sequence(d, str, "dependency-groups"), + default_groups=_get_sequence(d, str, "default-groups"), + created_by=_get_required(d, str, "created-by"), + requires_python=_get_as(d, str, SpecifierSet, "requires-python"), + packages=_get_required_sequence_of_objects(d, Package, "packages"), + tool=_get(d, Mapping, "tool"), # type: ignore[type-abstract] + ) + if not Version("1") <= pylock.lock_version < Version("2"): + raise PylockUnsupportedVersionError( + f"pylock version {pylock.lock_version} is not supported" + ) + if pylock.lock_version > Version("1.0"): + _logger.warning( + "pylock minor version %s is not supported", pylock.lock_version + ) + return pylock + + @classmethod + def from_dict(cls, d: Mapping[str, Any], /) -> Self: + """Create and validate a Pylock instance from a TOML dictionary. + + Raises :class:`PylockValidationError` if the input data is not + spec-compliant. + """ + return cls._from_dict(d) + + def to_dict(self) -> Mapping[str, Any]: + """Convert the Pylock instance to a TOML dictionary.""" + return dataclasses.asdict(self, dict_factory=_toml_dict_factory) + + def validate(self) -> None: + """Validate the Pylock instance against the specification. + + Raises :class:`PylockValidationError` otherwise.""" + self.from_dict(self.to_dict()) + + def select( + self, + *, + environment: Environment | None = None, + tags: Sequence[Tag] | None = None, + extras: Collection[str] | None = None, + dependency_groups: Collection[str] | None = None, + ) -> Iterator[ + tuple[ + Package, + PackageVcs + | PackageDirectory + | PackageArchive + | PackageWheel + | PackageSdist, + ] + ]: + """Select what to install from the lock file. + + The *environment* and *tags* parameters represent the environment being + selected for. If unspecified, ``packaging.markers.default_environment()`` and + ``packaging.tags.sys_tags()`` are used. + + The *extras* parameter represents the extras to install. + + The *dependency_groups* parameter represents the groups to install. If + unspecified, the default groups are used. + + This method must be used on valid Pylock instances (i.e. one obtained + from :meth:`Pylock.from_dict` or if constructed manually, after calling + :meth:`Pylock.validate`). + """ + compatible_tags_selector = create_compatible_tags_selector(tags or sys_tags()) + + # #. Gather the extras and dependency groups to install and set ``extras`` and + # ``dependency_groups`` for marker evaluation, respectively. + # + # #. ``extras`` SHOULD be set to the empty set by default. + # #. ``dependency_groups`` SHOULD be the set created from + # :ref:`pylock-default-groups` by default. + env = cast( + "dict[str, str | frozenset[str]]", + dict( + environment or {}, # Marker.evaluate will fill-up + extras=frozenset(extras or []), + dependency_groups=frozenset( + (self.default_groups or []) + if dependency_groups is None # to allow selecting no group + else dependency_groups + ), + ), + ) + env_python_full_version = ( + environment["python_full_version"] + if environment + else default_environment()["python_full_version"] + ) + + # #. Check if the metadata version specified by :ref:`pylock-lock-version` is + # supported; an error or warning MUST be raised as appropriate. + # Covered by lock.validate() which is a precondition for this method. + + # #. If :ref:`pylock-requires-python` is specified, check that the environment + # being installed for meets the requirement; an error MUST be raised if it is + # not met. + if self.requires_python and not self.requires_python.contains( + env_python_full_version, + ): + raise PylockSelectError( + f"python_full_version {env_python_full_version!r} " + f"in provided environment does not satisfy the Python version " + f"requirement {str(self.requires_python)!r}" + ) + + # #. If :ref:`pylock-environments` is specified, check that at least one of the + # environment marker expressions is satisfied; an error MUST be raised if no + # expression is satisfied. + if self.environments: + for env_marker in self.environments: + if env_marker.evaluate( + cast("dict[str, str]", environment or {}), context="requirement" + ): + break + else: + raise PylockSelectError( + "Provided environment does not satisfy any of the " + "environments specified in the lock file" + ) + + # #. For each package listed in :ref:`pylock-packages`: + selected_packages_by_name: dict[str, tuple[int, Package]] = {} + for package_index, package in enumerate(self.packages): + # #. If :ref:`pylock-packages-marker` is specified, check if it is + # satisfied;if it isn't, skip to the next package. + if package.marker and not package.marker.evaluate(env, context="lock_file"): + continue + + # #. If :ref:`pylock-packages-requires-python` is specified, check if it is + # satisfied; an error MUST be raised if it isn't. + if package.requires_python and not package.requires_python.contains( + env_python_full_version, + ): + raise PylockSelectError( + f"python_full_version {env_python_full_version!r} " + f"in provided environment does not satisfy the Python version " + f"requirement {str(package.requires_python)!r} for package " + f"{package.name!r} at packages[{package_index}]" + ) + + # #. Check that no other conflicting instance of the package has been slated + # to be installed; an error about the ambiguity MUST be raised otherwise. + if package.name in selected_packages_by_name: + raise PylockSelectError( + f"Multiple packages with the name {package.name!r} are " + f"selected at packages[{package_index}] and " + f"packages[{selected_packages_by_name[package.name][0]}]" + ) + + # #. Check that the source of the package is specified appropriately (i.e. + # there are no conflicting sources in the package entry); + # an error MUST be raised if any issues are found. + # Covered by lock.validate() which is a precondition for this method. + + # #. Add the package to the set of packages to install. + selected_packages_by_name[package.name] = (package_index, package) + + # #. For each package to be installed: + for package_index, package in selected_packages_by_name.values(): + # - If :ref:`pylock-packages-vcs` is set: + if package.vcs is not None: + yield package, package.vcs + + # - Else if :ref:`pylock-packages-directory` is set: + elif package.directory is not None: + yield package, package.directory + + # - Else if :ref:`pylock-packages-archive` is set: + elif package.archive is not None: + yield package, package.archive + + # - Else if there are entries for :ref:`pylock-packages-wheels`: + elif package.wheels: + # #. Look for the appropriate wheel file based on + # :ref:`pylock-packages-wheels-name`; if one is not found then move + # on to :ref:`pylock-packages-sdist` or an error MUST be raised about + # a lack of source for the project. + best_wheel = next( + compatible_tags_selector( + (wheel, parse_wheel_filename(wheel.filename)[-1]) + for wheel in package.wheels + ), + None, + ) + if best_wheel: + yield package, best_wheel + elif package.sdist is not None: + yield package, package.sdist + else: + raise PylockSelectError( + f"No wheel found matching the provided tags " + f"for package {package.name!r} " + f"at packages[{package_index}], " + f"and no sdist available as a fallback" + ) + + # - Else if no :ref:`pylock-packages-wheels` file is found or + # :ref:`pylock-packages-sdist` is solely set: + elif package.sdist is not None: + yield package, package.sdist + + else: + # Covered by lock.validate() which is a precondition for this method. + raise NotImplementedError # pragma: no cover diff --git a/.venv/lib/python3.13/site-packages/packaging/requirements.py b/.venv/lib/python3.13/site-packages/packaging/requirements.py new file mode 100644 index 0000000000000000000000000000000000000000..5892aee6ee2e391673a8609eecb5e43be4931a89 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/requirements.py @@ -0,0 +1,129 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. +from __future__ import annotations + +from typing import Iterator + +from ._parser import parse_requirement as _parse_requirement +from ._tokenizer import ParserSyntaxError +from .markers import Marker, _normalize_extra_values +from .specifiers import SpecifierSet +from .utils import canonicalize_name + +__all__ = [ + "InvalidRequirement", + "Requirement", +] + + +def __dir__() -> list[str]: + return __all__ + + +class InvalidRequirement(ValueError): + """ + An invalid requirement was found, users should refer to PEP 508. + """ + + +class Requirement: + """Parse a requirement. + + Parse a given requirement string into its parts, such as name, specifier, + URL, and extras. Raises InvalidRequirement on a badly-formed requirement + string. + + Instances are safe to serialize with :mod:`pickle`. They use a stable + format so the same pickle can be loaded in future packaging releases. + + .. versionchanged:: 26.2 + + Added a stable pickle format. Pickles created with packaging 26.2+ can + be unpickled with future releases. Backward compatibility with pickles + from packaging < 26.2 is supported but may be removed in a future + release. + """ + + # TODO: Can we test whether something is contained within a requirement? + # If so how do we do that? Do we need to test against the _name_ of + # the thing as well as the version? What about the markers? + # TODO: Can we normalize the name and extra name? + + def __init__(self, requirement_string: str) -> None: + try: + parsed = _parse_requirement(requirement_string) + except ParserSyntaxError as e: + raise InvalidRequirement(str(e)) from e + + self.name: str = parsed.name + self.url: str | None = parsed.url or None + self.extras: set[str] = set(parsed.extras or []) + self.specifier: SpecifierSet = SpecifierSet(parsed.specifier) + self.marker: Marker | None = None + if parsed.marker is not None: + self.marker = Marker.__new__(Marker) + self.marker._markers = _normalize_extra_values(parsed.marker) + + def _iter_parts(self, name: str) -> Iterator[str]: + yield name + + if self.extras: + formatted_extras = ",".join(sorted(self.extras)) + yield f"[{formatted_extras}]" + + if self.specifier: + yield str(self.specifier) + + if self.url: + yield f" @ {self.url}" + if self.marker: + yield " " + + if self.marker: + yield f"; {self.marker}" + + def __getstate__(self) -> str: + # Return the requirement string for compactness and stability. + # Re-parsed on load to reconstruct all fields. + return str(self) + + def __setstate__(self, state: object) -> None: + if isinstance(state, str): + # New format (26.2+): just the requirement string. + try: + tmp = Requirement(state) + except InvalidRequirement as exc: + raise TypeError(f"Cannot restore Requirement from {state!r}") from exc + self.name = tmp.name + self.url = tmp.url + self.extras = tmp.extras + self.specifier = tmp.specifier + self.marker = tmp.marker + return + if isinstance(state, dict): + # Old format (packaging <= 26.1, no __slots__): plain __dict__. + self.__dict__.update(state) + return + raise TypeError(f"Cannot restore Requirement from {state!r}") + + def __str__(self) -> str: + return "".join(self._iter_parts(self.name)) + + def __repr__(self) -> str: + return f"<{self.__class__.__name__}({str(self)!r})>" + + def __hash__(self) -> int: + return hash(tuple(self._iter_parts(canonicalize_name(self.name)))) + + def __eq__(self, other: object) -> bool: + if not isinstance(other, Requirement): + return NotImplemented + + return ( + canonicalize_name(self.name) == canonicalize_name(other.name) + and self.extras == other.extras + and self.specifier == other.specifier + and self.url == other.url + and self.marker == other.marker + ) diff --git a/.venv/lib/python3.13/site-packages/packaging/specifiers.py b/.venv/lib/python3.13/site-packages/packaging/specifiers.py new file mode 100644 index 0000000000000000000000000000000000000000..b165dc0f7c8201f2291780ce0273af8127105ab0 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/specifiers.py @@ -0,0 +1,1943 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. +""" +.. testsetup:: + + from packaging.specifiers import Specifier, SpecifierSet, InvalidSpecifier + from packaging.version import Version +""" + +from __future__ import annotations + +import abc +import enum +import functools +import itertools +import re +import sys +import typing +from typing import ( + TYPE_CHECKING, + Any, + Callable, + Final, + Iterable, + Iterator, + Sequence, + TypeVar, + Union, +) + +from .utils import canonicalize_version +from .version import InvalidVersion, Version + +if sys.version_info >= (3, 10): + from typing import TypeGuard # pragma: no cover +elif TYPE_CHECKING: + from typing_extensions import TypeGuard + +__all__ = [ + "BaseSpecifier", + "InvalidSpecifier", + "Specifier", + "SpecifierSet", +] + + +def __dir__() -> list[str]: + return __all__ + + +def _validate_spec(spec: object, /) -> TypeGuard[tuple[str, str]]: + return ( + isinstance(spec, tuple) + and len(spec) == 2 + and isinstance(spec[0], str) + and isinstance(spec[1], str) + ) + + +def _validate_pre(pre: object, /) -> TypeGuard[bool | None]: + return pre is None or isinstance(pre, bool) + + +T = TypeVar("T") +UnparsedVersion = Union[Version, str] +UnparsedVersionVar = TypeVar("UnparsedVersionVar", bound=UnparsedVersion) +CallableOperator = Callable[[Version, str], bool] + +# The smallest possible PEP 440 version. No valid version is less than this. +_MIN_VERSION: Final[Version] = Version("0.dev0") + + +def _trim_release(release: tuple[int, ...]) -> tuple[int, ...]: + """Strip trailing zeros from a release tuple for normalized comparison.""" + end = len(release) + while end > 1 and release[end - 1] == 0: + end -= 1 + return release if end == len(release) else release[:end] + + +class _BoundaryKind(enum.Enum): + """Where a boundary marker sits in the version ordering.""" + + AFTER_LOCALS = enum.auto() # after V+local, before V.post0 + AFTER_POSTS = enum.auto() # after V.postN, before next release + + +@functools.total_ordering +class _BoundaryVersion: + """A point on the version line between two real PEP 440 versions. + + Some specifier semantics imply boundaries between real versions: + ``<=1.0`` includes ``1.0+local`` and ``>1.0`` excludes + ``1.0.post0``. No real :class:`Version` falls on those boundaries, + so this class creates values that sort between the real versions + on either side. + + Two kinds exist, shown relative to a base version V:: + + V < V+local < AFTER_LOCALS(V) < V.post0 < AFTER_POSTS(V) + + ``AFTER_LOCALS`` sits after V and every V+local, but before + V.post0. Upper bound of ``<=V``, ``==V``, ``!=V``. + + ``AFTER_POSTS`` sits after every V.postN, but before the next + release segment. Lower bound of ``>V`` (final or pre-release V) + to exclude post-releases per PEP 440. + """ + + __slots__ = ("_kind", "_trimmed_release", "version") + + def __init__(self, version: Version, kind: _BoundaryKind) -> None: + self.version = version + self._kind = kind + self._trimmed_release = _trim_release(version.release) + + def _is_family(self, other: Version) -> bool: + """Is ``other`` a version that this boundary sorts above?""" + v = self.version + if not ( + other.epoch == v.epoch + and _trim_release(other.release) == self._trimmed_release + and other.pre == v.pre + ): + return False + if self._kind == _BoundaryKind.AFTER_LOCALS: + # Local family: exact same public version (any local label). + return other.post == v.post and other.dev == v.dev + # Post family: same base + any post-release (or identical). + return other.dev == v.dev or other.post is not None + + def __eq__(self, other: object) -> bool: + if isinstance(other, _BoundaryVersion): + return self.version == other.version and self._kind == other._kind + return NotImplemented + + def __lt__(self, other: _BoundaryVersion | Version) -> bool: + if isinstance(other, _BoundaryVersion): + if self.version != other.version: + return self.version < other.version + return self._kind.value < other._kind.value + return not self._is_family(other) and self.version < other + + def __hash__(self) -> int: + return hash((self.version, self._kind)) + + def __repr__(self) -> str: + return f"{self.__class__.__name__}({self.version!r}, {self._kind.name})" + + +@functools.total_ordering +class _LowerBound: + """Lower bound of a version range. + + A version *v* of ``None`` means unbounded below (-inf). + At equal versions, ``[v`` sorts before ``(v`` because an inclusive + bound starts earlier. + """ + + __slots__ = ("inclusive", "version") + + def __init__(self, version: _VersionOrBoundary, inclusive: bool) -> None: + self.version = version + self.inclusive = inclusive + + def __eq__(self, other: object) -> bool: + if not isinstance(other, _LowerBound): + return NotImplemented # pragma: no cover + return self.version == other.version and self.inclusive == other.inclusive + + def __lt__(self, other: _LowerBound) -> bool: + if not isinstance(other, _LowerBound): # pragma: no cover + return NotImplemented + # -inf < anything (except -inf). + if self.version is None: + return other.version is not None + if other.version is None: + return False + if self.version != other.version: + return self.version < other.version + # [v < (v: inclusive starts earlier. + return self.inclusive and not other.inclusive + + def __hash__(self) -> int: + return hash((self.version, self.inclusive)) + + def __repr__(self) -> str: + bracket = "[" if self.inclusive else "(" + return f"<{self.__class__.__name__} {bracket}{self.version!r}>" + + +@functools.total_ordering +class _UpperBound: + """Upper bound of a version range. + + A version *v* of ``None`` means unbounded above (+inf). + At equal versions, ``v)`` sorts before ``v]`` because an exclusive + bound ends earlier. + """ + + __slots__ = ("inclusive", "version") + + def __init__(self, version: _VersionOrBoundary, inclusive: bool) -> None: + self.version = version + self.inclusive = inclusive + + def __eq__(self, other: object) -> bool: + if not isinstance(other, _UpperBound): + return NotImplemented # pragma: no cover + return self.version == other.version and self.inclusive == other.inclusive + + def __lt__(self, other: _UpperBound) -> bool: + if not isinstance(other, _UpperBound): # pragma: no cover + return NotImplemented + # Nothing < +inf (except +inf itself). + if self.version is None: + return False + if other.version is None: + return True + if self.version != other.version: + return self.version < other.version + # v) < v]: exclusive ends earlier. + return not self.inclusive and other.inclusive + + def __hash__(self) -> int: + return hash((self.version, self.inclusive)) + + def __repr__(self) -> str: + bracket = "]" if self.inclusive else ")" + return f"<{self.__class__.__name__} {self.version!r}{bracket}>" + + +if typing.TYPE_CHECKING: + _VersionOrBoundary = Union[Version, _BoundaryVersion, None] + + #: A single contiguous version range, represented as a + #: (lower bound, upper bound) pair. + _VersionRange = tuple[_LowerBound, _UpperBound] + +_NEG_INF = _LowerBound(None, False) +_POS_INF = _UpperBound(None, False) +_FULL_RANGE: tuple[_VersionRange] = ((_NEG_INF, _POS_INF),) + + +def _range_is_empty(lower: _LowerBound, upper: _UpperBound) -> bool: + """True when the range defined by *lower* and *upper* contains no versions.""" + if lower.version is None or upper.version is None: + return False + if lower.version == upper.version: + return not (lower.inclusive and upper.inclusive) + return lower.version > upper.version + + +def _intersect_ranges( + left: Sequence[_VersionRange], + right: Sequence[_VersionRange], +) -> list[_VersionRange]: + """Intersect two sorted, non-overlapping range lists (two-pointer merge).""" + result: list[_VersionRange] = [] + left_index = right_index = 0 + while left_index < len(left) and right_index < len(right): + left_lower, left_upper = left[left_index] + right_lower, right_upper = right[right_index] + + lower = max(left_lower, right_lower) + upper = min(left_upper, right_upper) + + if not _range_is_empty(lower, upper): + result.append((lower, upper)) + + # Advance whichever side has the smaller upper bound. + if left_upper < right_upper: + left_index += 1 + else: + right_index += 1 + + return result + + +def _next_prefix_dev0(version: Version) -> Version: + """Smallest version in the next prefix: 1.2 -> 1.3.dev0.""" + release = (*version.release[:-1], version.release[-1] + 1) + return Version.from_parts(epoch=version.epoch, release=release, dev=0) + + +def _base_dev0(version: Version) -> Version: + """The .dev0 of a version's base release: 1.2 -> 1.2.dev0.""" + return Version.from_parts(epoch=version.epoch, release=version.release, dev=0) + + +def _coerce_version(version: UnparsedVersion) -> Version | None: + if not isinstance(version, Version): + try: + version = Version(version) + except InvalidVersion: + return None + return version + + +def _public_version(version: Version) -> Version: + if version.local is None: + return version + return version.__replace__(local=None) + + +def _post_base(version: Version) -> Version: + """The version that *version* is a post-release of. + + 1.0.post1 -> 1.0, 1.0a1.post0 -> 1.0a1, 1.0.post0.dev1 -> 1.0. + """ + return version.__replace__(post=None, dev=None, local=None) + + +def _earliest_prerelease(version: Version) -> Version: + """Earliest pre-release of *version*. + + 1.2 -> 1.2.dev0, 1.2.post1 -> 1.2.post1.dev0. + """ + return version.__replace__(dev=0, local=None) + + +def _nearest_non_prerelease( + v: _VersionOrBoundary, +) -> Version | None: + """Smallest non-pre-release version at or above *v*, or None.""" + if v is None: + return None + if isinstance(v, _BoundaryVersion): + inner = v.version + if inner.is_prerelease: + # AFTER_LOCALS(1.0a1) -> nearest non-pre is 1.0 + return inner.__replace__(pre=None, dev=None, local=None) + # AFTER_LOCALS(1.0) -> nearest non-pre is 1.0.post0 + # AFTER_LOCALS(1.0.post0) -> nearest non-pre is 1.0.post1 + k = (inner.post + 1) if inner.post is not None else 0 + return inner.__replace__(post=k, local=None) + if not v.is_prerelease: + return v + # Strip pre/dev to get the final or post-release form. + return v.__replace__(pre=None, dev=None, local=None) + + +class InvalidSpecifier(ValueError): + """ + Raised when attempting to create a :class:`Specifier` with a specifier + string that is invalid. + + >>> Specifier("lolwat") + Traceback (most recent call last): + ... + packaging.specifiers.InvalidSpecifier: Invalid specifier: 'lolwat' + """ + + +class BaseSpecifier(metaclass=abc.ABCMeta): + __slots__ = () + __match_args__ = ("_str",) + + @property + def _str(self) -> str: + """Internal property for match_args""" + return str(self) + + @abc.abstractmethod + def __str__(self) -> str: + """ + Returns the str representation of this Specifier-like object. This + should be representative of the Specifier itself. + """ + + @abc.abstractmethod + def __hash__(self) -> int: + """ + Returns a hash value for this Specifier-like object. + """ + + @abc.abstractmethod + def __eq__(self, other: object) -> bool: + """ + Returns a boolean representing whether or not the two Specifier-like + objects are equal. + + :param other: The other object to check against. + """ + + @property + @abc.abstractmethod + def prereleases(self) -> bool | None: + """Whether or not pre-releases as a whole are allowed. + + This can be set to either ``True`` or ``False`` to explicitly enable or disable + prereleases or it can be set to ``None`` (the default) to use default semantics. + """ + + @prereleases.setter # noqa: B027 + def prereleases(self, value: bool) -> None: + """Setter for :attr:`prereleases`. + + :param value: The value to set. + """ + + @abc.abstractmethod + def contains(self, item: str, prereleases: bool | None = None) -> bool: + """ + Determines if the given item is contained within this specifier. + """ + + @typing.overload + def filter( + self, + iterable: Iterable[UnparsedVersionVar], + prereleases: bool | None = None, + key: None = ..., + ) -> Iterator[UnparsedVersionVar]: ... + + @typing.overload + def filter( + self, + iterable: Iterable[T], + prereleases: bool | None = None, + key: Callable[[T], UnparsedVersion] = ..., + ) -> Iterator[T]: ... + + @abc.abstractmethod + def filter( + self, + iterable: Iterable[Any], + prereleases: bool | None = None, + key: Callable[[Any], UnparsedVersion] | None = None, + ) -> Iterator[Any]: + """ + Takes an iterable of items and filters them so that only items which + are contained within this specifier are allowed in it. + """ + + +class Specifier(BaseSpecifier): + """This class abstracts handling of version specifiers. + + .. tip:: + + It is generally not required to instantiate this manually. You should instead + prefer to work with :class:`SpecifierSet` instead, which can parse + comma-separated version specifiers (which is what package metadata contains). + + Instances are safe to serialize with :mod:`pickle`. They use a stable + format so the same pickle can be loaded in future packaging releases. + + .. versionchanged:: 26.2 + + Added a stable pickle format. Pickles created with packaging 26.2+ can + be unpickled with future releases. Backward compatibility with pickles + from packaging < 26.2 is supported but may be removed in a future + release. + """ + + __slots__ = ( + "_prereleases", + "_ranges", + "_spec", + "_spec_version", + "_wildcard_split", + ) + + _specifier_regex_str = r""" + (?: + (?: + # The identity operators allow for an escape hatch that will + # do an exact string match of the version you wish to install. + # This will not be parsed by PEP 440 and we cannot determine + # any semantic meaning from it. This operator is discouraged + # but included entirely as an escape hatch. + === # Only match for the identity operator + \s* + [^\s;)]* # The arbitrary version can be just about anything, + # we match everything except for whitespace, a + # semi-colon for marker support, and a closing paren + # since versions can be enclosed in them. + ) + | + (?: + # The (non)equality operators allow for wild card and local + # versions to be specified so we have to define these two + # operators separately to enable that. + (?:==|!=) # Only match for equals and not equals + + \s* + v? + (?:[0-9]+!)? # epoch + [0-9]+(?:\.[0-9]+)* # release + + # You cannot use a wild card and a pre-release, post-release, a dev or + # local version together so group them with a | and make them optional. + (?: + \.\* # Wild card syntax of .* + | + (?a: # pre release + [-_\.]? + (alpha|beta|preview|pre|a|b|c|rc) + [-_\.]? + [0-9]* + )? + (?a: # post release + (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*) + )? + (?a:[-_\.]?dev[-_\.]?[0-9]*)? # dev release + (?a:\+[a-z0-9]+(?:[-_\.][a-z0-9]+)*)? # local + )? + ) + | + (?: + # The compatible operator requires at least two digits in the + # release segment. + (?:~=) # Only match for the compatible operator + + \s* + v? + (?:[0-9]+!)? # epoch + [0-9]+(?:\.[0-9]+)+ # release (We have a + instead of a *) + (?: # pre release + [-_\.]? + (alpha|beta|preview|pre|a|b|c|rc) + [-_\.]? + [0-9]* + )? + (?: # post release + (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*) + )? + (?:[-_\.]?dev[-_\.]?[0-9]*)? # dev release + ) + | + (?: + # All other operators only allow a sub set of what the + # (non)equality operators do. Specifically they do not allow + # local versions to be specified nor do they allow the prefix + # matching wild cards. + (?:<=|>=|<|>) + + \s* + v? + (?:[0-9]+!)? # epoch + [0-9]+(?:\.[0-9]+)* # release + (?a: # pre release + [-_\.]? + (alpha|beta|preview|pre|a|b|c|rc) + [-_\.]? + [0-9]* + )? + (?a: # post release + (?:-[0-9]+)|(?:[-_\.]?(post|rev|r)[-_\.]?[0-9]*) + )? + (?a:[-_\.]?dev[-_\.]?[0-9]*)? # dev release + ) + ) + """ + + _regex = re.compile( + r"\s*" + _specifier_regex_str + r"\s*", re.VERBOSE | re.IGNORECASE + ) + + _operators: Final = { + "~=": "compatible", + "==": "equal", + "!=": "not_equal", + "<=": "less_than_equal", + ">=": "greater_than_equal", + "<": "less_than", + ">": "greater_than", + "===": "arbitrary", + } + + def __init__(self, spec: str = "", prereleases: bool | None = None) -> None: + """Initialize a Specifier instance. + + :param spec: + The string representation of a specifier which will be parsed and + normalized before use. + :param prereleases: + This tells the specifier if it should accept prerelease versions if + applicable or not. The default of ``None`` will autodetect it from the + given specifiers. + :raises InvalidSpecifier: + If the given specifier is invalid (i.e. bad syntax). + """ + if not self._regex.fullmatch(spec): + raise InvalidSpecifier(f"Invalid specifier: {spec!r}") + + spec = spec.strip() + if spec.startswith("==="): + operator, version = spec[:3], spec[3:].strip() + elif spec.startswith(("~=", "==", "!=", "<=", ">=")): + operator, version = spec[:2], spec[2:].strip() + else: + operator, version = spec[:1], spec[1:].strip() + + self._spec: tuple[str, str] = (operator, version) + + # Store whether or not this Specifier should accept prereleases + self._prereleases = prereleases + + # Specifier version cache + self._spec_version: tuple[str, Version] | None = None + + # Populated on first wildcard (==X.*) comparison + self._wildcard_split: tuple[list[str], int] | None = None + + # Version range cache (populated by _to_ranges) + self._ranges: Sequence[_VersionRange] | None = None + + def _get_spec_version(self, version: str) -> Version | None: + """One element cache, as only one spec Version is needed per Specifier.""" + if self._spec_version is not None and self._spec_version[0] == version: + return self._spec_version[1] + + version_specifier = _coerce_version(version) + if version_specifier is None: + return None + + self._spec_version = (version, version_specifier) + return version_specifier + + def _require_spec_version(self, version: str) -> Version: + """Get spec version, asserting it's valid (not for === operator). + + This method should only be called for operators where version + strings are guaranteed to be valid PEP 440 versions (not ===). + """ + spec_version = self._get_spec_version(version) + assert spec_version is not None + return spec_version + + def _to_ranges(self) -> Sequence[_VersionRange]: + """Convert this specifier to sorted, non-overlapping version ranges. + + Each standard operator maps to one or two ranges. ``===`` is + modeled as full range (actual check done separately). Cached. + """ + if self._ranges is not None: + return self._ranges + + op = self.operator + ver_str = self.version + + if op == "===": + self._ranges = _FULL_RANGE + return _FULL_RANGE + + if ver_str.endswith(".*"): + result = self._wildcard_ranges(op, ver_str) + else: + result = self._standard_ranges(op, ver_str) + + self._ranges = result + return result + + def _wildcard_ranges(self, op: str, ver_str: str) -> list[_VersionRange]: + # ==1.2.* -> [1.2.dev0, 1.3.dev0); !=1.2.* -> complement. + base = self._require_spec_version(ver_str[:-2]) + lower = _base_dev0(base) + upper = _next_prefix_dev0(base) + if op == "==": + return [(_LowerBound(lower, True), _UpperBound(upper, False))] + # != + return [ + (_NEG_INF, _UpperBound(lower, False)), + (_LowerBound(upper, True), _POS_INF), + ] + + def _standard_ranges(self, op: str, ver_str: str) -> list[_VersionRange]: + v = self._require_spec_version(ver_str) + + if op == ">=": + return [(_LowerBound(v, True), _POS_INF)] + + if op == "<=": + return [ + ( + _NEG_INF, + _UpperBound(_BoundaryVersion(v, _BoundaryKind.AFTER_LOCALS), True), + ) + ] + + if op == ">": + if v.dev is not None: + # >V.devN: dev versions have no post-releases, so the + # next real version is V.dev(N+1). + lower_ver = v.__replace__(dev=v.dev + 1, local=None) + return [(_LowerBound(lower_ver, True), _POS_INF)] + if v.post is not None: + # >V.postN: next real version is V.post(N+1).dev0. + lower_ver = v.__replace__(post=v.post + 1, dev=0, local=None) + return [(_LowerBound(lower_ver, True), _POS_INF)] + # >V (final or pre-release): skip V+local and all V.postN. + return [ + ( + _LowerBound(_BoundaryVersion(v, _BoundaryKind.AFTER_POSTS), False), + _POS_INF, + ) + ] + + if op == "<": + # bool | None: + # If there is an explicit prereleases set for this, then we'll just + # blindly use that. + if self._prereleases is not None: + return self._prereleases + + # Only the "!=" operator does not imply prereleases when + # the version in the specifier is a prerelease. + operator, version_str = self._spec + if operator == "!=": + return False + + # The == specifier with trailing .* cannot include prereleases + # e.g. "==1.0a1.*" is not valid. + if operator == "==" and version_str.endswith(".*"): + return False + + # "===" can have arbitrary string versions, so we cannot parse + # those, we take prereleases as unknown (None) for those. + version = self._get_spec_version(version_str) + if version is None: + return None + + # For all other operators, use the check if spec Version + # object implies pre-releases. + return version.is_prerelease + + @prereleases.setter + def prereleases(self, value: bool | None) -> None: + self._prereleases = value + + def __getstate__(self) -> tuple[tuple[str, str], bool | None]: + # Return state as a 2-item tuple for compactness: + # ((operator, version), prereleases) + # Cache members are excluded and will be recomputed on demand. + return (self._spec, self._prereleases) + + def __setstate__(self, state: object) -> None: + # Always discard cached values - they will be recomputed on demand. + self._spec_version = None + self._wildcard_split = None + self._ranges = None + + if isinstance(state, tuple): + if len(state) == 2: + # New format (26.2+): ((operator, version), prereleases) + spec, prereleases = state + if _validate_spec(spec) and _validate_pre(prereleases): + self._spec = spec + self._prereleases = prereleases + return + if len(state) == 2 and isinstance(state[1], dict): + # Format (packaging 26.0-26.1): (None, {slot: value}). + _, slot_dict = state + spec = slot_dict.get("_spec") + prereleases = slot_dict.get("_prereleases", "invalid") + if _validate_spec(spec) and _validate_pre(prereleases): + self._spec = spec + self._prereleases = prereleases + return + if isinstance(state, dict): + # Old format (packaging <= 25.x, no __slots__): state is a plain dict. + spec = state.get("_spec") + prereleases = state.get("_prereleases", "invalid") + if _validate_spec(spec) and _validate_pre(prereleases): + self._spec = spec + self._prereleases = prereleases + return + + raise TypeError(f"Cannot restore Specifier from {state!r}") + + @property + def operator(self) -> str: + """The operator of this specifier. + + >>> Specifier("==1.2.3").operator + '==' + """ + return self._spec[0] + + @property + def version(self) -> str: + """The version of this specifier. + + >>> Specifier("==1.2.3").version + '1.2.3' + """ + return self._spec[1] + + def __repr__(self) -> str: + """A representation of the Specifier that shows all internal state. + + >>> Specifier('>=1.0.0') + =1.0.0')> + >>> Specifier('>=1.0.0', prereleases=False) + =1.0.0', prereleases=False)> + >>> Specifier('>=1.0.0', prereleases=True) + =1.0.0', prereleases=True)> + """ + pre = ( + f", prereleases={self.prereleases!r}" + if self._prereleases is not None + else "" + ) + + return f"<{self.__class__.__name__}({str(self)!r}{pre})>" + + def __str__(self) -> str: + """A string representation of the Specifier that can be round-tripped. + + >>> str(Specifier('>=1.0.0')) + '>=1.0.0' + >>> str(Specifier('>=1.0.0', prereleases=False)) + '>=1.0.0' + """ + return "{}{}".format(*self._spec) + + @property + def _canonical_spec(self) -> tuple[str, str]: + operator, version = self._spec + if operator == "===" or version.endswith(".*"): + return operator, version + + spec_version = self._require_spec_version(version) + + canonical_version = canonicalize_version( + spec_version, strip_trailing_zero=(operator != "~=") + ) + + return operator, canonical_version + + def __hash__(self) -> int: + return hash(self._canonical_spec) + + def __eq__(self, other: object) -> bool: + """Whether or not the two Specifier-like objects are equal. + + :param other: The other object to check against. + + The value of :attr:`prereleases` is ignored. + + >>> Specifier("==1.2.3") == Specifier("== 1.2.3.0") + True + >>> (Specifier("==1.2.3", prereleases=False) == + ... Specifier("==1.2.3", prereleases=True)) + True + >>> Specifier("==1.2.3") == "==1.2.3" + True + >>> Specifier("==1.2.3") == Specifier("==1.2.4") + False + >>> Specifier("==1.2.3") == Specifier("~=1.2.3") + False + """ + if isinstance(other, str): + try: + other = self.__class__(str(other)) + except InvalidSpecifier: + return NotImplemented + elif not isinstance(other, self.__class__): + return NotImplemented + + return self._canonical_spec == other._canonical_spec + + def _get_operator(self, op: str) -> CallableOperator: + operator_callable: CallableOperator = getattr( + self, f"_compare_{self._operators[op]}" + ) + return operator_callable + + def _compare_compatible(self, prospective: Version, spec: str) -> bool: + # Compatible releases have an equivalent combination of >= and ==. That + # is that ~=2.2 is equivalent to >=2.2,==2.*. This allows us to + # implement this in terms of the other specifiers instead of + # implementing it ourselves. The only thing we need to do is construct + # the other specifiers. + + # We want everything but the last item in the version, but we want to + # ignore suffix segments. + prefix = _version_join( + list(itertools.takewhile(_is_not_suffix, _version_split(spec)))[:-1] + ) + + # Add the prefix notation to the end of our string + prefix += ".*" + + return (self._compare_greater_than_equal(prospective, spec)) and ( + self._compare_equal(prospective, prefix) + ) + + def _get_wildcard_split(self, spec: str) -> tuple[list[str], int]: + """Cached split of a wildcard spec into components and numeric length. + + >>> Specifier("==1.*")._get_wildcard_split("1.*") + (['0', '1'], 2) + >>> Specifier("==3.10.*")._get_wildcard_split("3.10.*") + (['0', '3', '10'], 3) + """ + wildcard_split = self._wildcard_split + if wildcard_split is None: + normalized = canonicalize_version(spec[:-2], strip_trailing_zero=False) + split_spec = _version_split(normalized) + wildcard_split = (split_spec, _numeric_prefix_len(split_spec)) + self._wildcard_split = wildcard_split + return wildcard_split + + def _compare_equal(self, prospective: Version, spec: str) -> bool: + # We need special logic to handle prefix matching + if spec.endswith(".*"): + split_spec, spec_numeric_len = self._get_wildcard_split(spec) + + # In the case of prefix matching we want to ignore local segment. + normalized_prospective = canonicalize_version( + _public_version(prospective), strip_trailing_zero=False + ) + # Split the prospective version out by bangs and dots, and pretend + # that there is an implicit dot in between a release segment and + # a pre-release segment. + split_prospective = _version_split(normalized_prospective) + + # 0-pad the prospective version before shortening it to get the correct + # shortened version. + padded_prospective = _left_pad(split_prospective, spec_numeric_len) + + # Shorten the prospective version to be the same length as the spec + # so that we can determine if the specifier is a prefix of the + # prospective version or not. + shortened_prospective = padded_prospective[: len(split_spec)] + + return shortened_prospective == split_spec + else: + # Convert our spec string into a Version + spec_version = self._require_spec_version(spec) + + # If the specifier does not have a local segment, then we want to + # act as if the prospective version also does not have a local + # segment. + if not spec_version.local: + prospective = _public_version(prospective) + + return prospective == spec_version + + def _compare_not_equal(self, prospective: Version, spec: str) -> bool: + return not self._compare_equal(prospective, spec) + + def _compare_less_than_equal(self, prospective: Version, spec: str) -> bool: + # NB: Local version identifiers are NOT permitted in the version + # specifier, so local version labels can be universally removed from + # the prospective version. + return _public_version(prospective) <= self._require_spec_version(spec) + + def _compare_greater_than_equal(self, prospective: Version, spec: str) -> bool: + # NB: Local version identifiers are NOT permitted in the version + # specifier, so local version labels can be universally removed from + # the prospective version. + return _public_version(prospective) >= self._require_spec_version(spec) + + def _compare_less_than(self, prospective: Version, spec_str: str) -> bool: + # Convert our spec to a Version instance, since we'll want to work with + # it as a version. + spec = self._require_spec_version(spec_str) + + # Check to see if the prospective version is less than the spec + # version. If it's not we can short circuit and just return False now + # instead of doing extra unneeded work. + if not prospective < spec: + return False + + # The spec says: "= _earliest_prerelease(spec) + ): + return False + + # If we've gotten to here, it means that prospective version is both + # less than the spec version *and* it's not a pre-release of the same + # version in the spec. + return True + + def _compare_greater_than(self, prospective: Version, spec_str: str) -> bool: + # Convert our spec to a Version instance, since we'll want to work with + # it as a version. + spec = self._require_spec_version(spec_str) + + # Check to see if the prospective version is greater than the spec + # version. If it's not we can short circuit and just return False now + # instead of doing extra unneeded work. + if not prospective > spec: + return False + + # The spec says: ">V MUST NOT allow a post-release of the specified + # version unless the specified version is itself a post-release." + if ( + not spec.is_postrelease + and prospective.is_postrelease + and _post_base(prospective) == spec + ): + return False + + # Per the spec: ">V MUST NOT match a local version of the specified + # version". A "local version of V" is any version whose public part + # equals V. So >1.0a1 must not match 1.0a1+local, but must still + # match 1.0a2+local. + if prospective.local is not None and _public_version(prospective) == spec: + return False + + # If we've gotten to here, it means that prospective version is both + # greater than the spec version *and* it's not a pre-release of the + # same version in the spec. + return True + + def _compare_arbitrary(self, prospective: Version | str, spec: str) -> bool: + return str(prospective).lower() == str(spec).lower() + + def __contains__(self, item: str | Version) -> bool: + """Return whether or not the item is contained in this specifier. + + :param item: The item to check for. + + This is used for the ``in`` operator and behaves the same as + :meth:`contains` with no ``prereleases`` argument passed. + + >>> "1.2.3" in Specifier(">=1.2.3") + True + >>> Version("1.2.3") in Specifier(">=1.2.3") + True + >>> "1.0.0" in Specifier(">=1.2.3") + False + >>> "1.3.0a1" in Specifier(">=1.2.3") + True + >>> "1.3.0a1" in Specifier(">=1.2.3", prereleases=True) + True + """ + return self.contains(item) + + def contains(self, item: UnparsedVersion, prereleases: bool | None = None) -> bool: + """Return whether or not the item is contained in this specifier. + + :param item: + The item to check for, which can be a version string or a + :class:`Version` instance. + :param prereleases: + Whether or not to match prereleases with this Specifier. If set to + ``None`` (the default), it will follow the recommendation from + :pep:`440` and match prereleases, as there are no other versions. + + >>> Specifier(">=1.2.3").contains("1.2.3") + True + >>> Specifier(">=1.2.3").contains(Version("1.2.3")) + True + >>> Specifier(">=1.2.3").contains("1.0.0") + False + >>> Specifier(">=1.2.3").contains("1.3.0a1") + True + >>> Specifier(">=1.2.3", prereleases=False).contains("1.3.0a1") + False + >>> Specifier(">=1.2.3").contains("1.3.0a1") + True + """ + + return bool(list(self.filter([item], prereleases=prereleases))) + + @typing.overload + def filter( + self, + iterable: Iterable[UnparsedVersionVar], + prereleases: bool | None = None, + key: None = ..., + ) -> Iterator[UnparsedVersionVar]: ... + + @typing.overload + def filter( + self, + iterable: Iterable[T], + prereleases: bool | None = None, + key: Callable[[T], UnparsedVersion] = ..., + ) -> Iterator[T]: ... + + def filter( + self, + iterable: Iterable[Any], + prereleases: bool | None = None, + key: Callable[[Any], UnparsedVersion] | None = None, + ) -> Iterator[Any]: + """Filter items in the given iterable, that match the specifier. + + :param iterable: + An iterable that can contain version strings and :class:`Version` instances. + The items in the iterable will be filtered according to the specifier. + :param prereleases: + Whether or not to allow prereleases in the returned iterator. If set to + ``None`` (the default), it will follow the recommendation from :pep:`440` + and match prereleases if there are no other versions. + :param key: + A callable that takes a single argument (an item from the iterable) and + returns a version string or :class:`Version` instance to be used for + filtering. + + >>> list(Specifier(">=1.2.3").filter(["1.2", "1.3", "1.5a1"])) + ['1.3'] + >>> list(Specifier(">=1.2.3").filter(["1.2", "1.2.3", "1.3", Version("1.4")])) + ['1.2.3', '1.3', ] + >>> list(Specifier(">=1.2.3").filter(["1.2", "1.5a1"])) + ['1.5a1'] + >>> list(Specifier(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True)) + ['1.3', '1.5a1'] + >>> list(Specifier(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"])) + ['1.3', '1.5a1'] + >>> list(Specifier(">=1.2.3").filter( + ... [{"ver": "1.2"}, {"ver": "1.3"}], + ... key=lambda x: x["ver"])) + [{'ver': '1.3'}] + """ + prereleases_versions = [] + found_non_prereleases = False + + # Determine if to include prereleases by default + include_prereleases = ( + prereleases if prereleases is not None else self.prereleases + ) + + # Get the matching operator + operator_callable = self._get_operator(self.operator) + + # Filter versions + for version in iterable: + parsed_version = _coerce_version(version if key is None else key(version)) + match = False + if parsed_version is None: + # === operator can match arbitrary (non-version) strings + if self.operator == "===" and self._compare_arbitrary( + version, self.version + ): + yield version + elif self.operator == "===": + match = self._compare_arbitrary( + version if key is None else key(version), self.version + ) + else: + match = operator_callable(parsed_version, self.version) + + if match and parsed_version is not None: + # If it's not a prerelease or prereleases are allowed, yield it directly + if not parsed_version.is_prerelease or include_prereleases: + found_non_prereleases = True + yield version + # Otherwise collect prereleases for potential later use + elif prereleases is None and self._prereleases is not False: + prereleases_versions.append(version) + + # If no non-prereleases were found and prereleases weren't + # explicitly forbidden, yield the collected prereleases + if ( + not found_non_prereleases + and prereleases is None + and self._prereleases is not False + ): + yield from prereleases_versions + + +_prefix_regex = re.compile(r"([0-9]+)((?:a|b|c|rc)[0-9]+)") + + +def _pep440_filter_prereleases( + iterable: Iterable[Any], key: Callable[[Any], UnparsedVersion] | None +) -> Iterator[Any]: + """Filter per PEP 440: exclude prereleases unless no finals exist.""" + # Two lists used: + # * all_nonfinal to preserve order if no finals exist + # * arbitrary_strings for streaming when first final found + all_nonfinal: list[Any] = [] + arbitrary_strings: list[Any] = [] + + found_final = False + for item in iterable: + parsed = _coerce_version(item if key is None else key(item)) + + if parsed is None: + # Arbitrary strings are always included as it is not + # possible to determine if they are prereleases, + # and they have already passed all specifiers. + if found_final: + yield item + else: + arbitrary_strings.append(item) + all_nonfinal.append(item) + continue + + if not parsed.is_prerelease: + # Final release found - flush arbitrary strings, then yield + if not found_final: + yield from arbitrary_strings + found_final = True + yield item + continue + + # Prerelease - buffer if no finals yet, otherwise skip + if not found_final: + all_nonfinal.append(item) + + # No finals found - yield all buffered items + if not found_final: + yield from all_nonfinal + + +def _version_split(version: str) -> list[str]: + """Split version into components. + + The split components are intended for version comparison. The logic does + not attempt to retain the original version string, so joining the + components back with :func:`_version_join` may not produce the original + version string. + """ + result: list[str] = [] + + epoch, _, rest = version.rpartition("!") + result.append(epoch or "0") + + for item in rest.split("."): + match = _prefix_regex.fullmatch(item) + if match: + result.extend(match.groups()) + else: + result.append(item) + return result + + +def _version_join(components: list[str]) -> str: + """Join split version components into a version string. + + This function assumes the input came from :func:`_version_split`, where the + first component must be the epoch (either empty or numeric), and all other + components numeric. + """ + epoch, *rest = components + return f"{epoch}!{'.'.join(rest)}" + + +def _is_not_suffix(segment: str) -> bool: + return not any( + segment.startswith(prefix) for prefix in ("dev", "a", "b", "rc", "post") + ) + + +def _numeric_prefix_len(split: list[str]) -> int: + """Count leading numeric components in a :func:`_version_split` result. + + >>> _numeric_prefix_len(["0", "1", "2", "a1"]) + 3 + """ + count = 0 + for segment in split: + if not segment.isdigit(): + break + count += 1 + return count + + +def _left_pad(split: list[str], target_numeric_len: int) -> list[str]: + """Pad a :func:`_version_split` result with ``"0"`` segments to reach + ``target_numeric_len`` numeric components. Suffix segments are preserved. + + >>> _left_pad(["0", "1", "a1"], 4) + ['0', '1', '0', '0', 'a1'] + """ + numeric_len = _numeric_prefix_len(split) + pad_needed = target_numeric_len - numeric_len + if pad_needed <= 0: + return split + return [*split[:numeric_len], *(["0"] * pad_needed), *split[numeric_len:]] + + +def _operator_cost(op_entry: tuple[CallableOperator, str, str]) -> int: + """Sort key for Cost Based Ordering of specifier operators in _filter_versions. + + Operators run sequentially on a shrinking candidate set, so operators that + reject the most versions should run first to minimize work for later ones. + + Tier 0: Exact equality (==, ===), likely to narrow candidates to one version + Tier 1: Range checks (>=, <=, >, <), cheap and usually reject a large portion + Tier 2: Wildcard equality (==.*) and compatible release (~=), more expensive + Tier 3: Exact !=, cheap but rarely rejects + Tier 4: Wildcard !=.*, expensive and rarely rejects + """ + _, ver, op = op_entry + if op == "==": + return 0 if not ver.endswith(".*") else 2 + if op in (">=", "<=", ">", "<"): + return 1 + if op == "~=": + return 2 + if op == "!=": + return 3 if not ver.endswith(".*") else 4 + if op == "===": + return 0 + + raise ValueError(f"Unknown operator: {op!r}") # pragma: no cover + + +class SpecifierSet(BaseSpecifier): + """This class abstracts handling of a set of version specifiers. + + It can be passed a single specifier (``>=3.0``), a comma-separated list of + specifiers (``>=3.0,!=3.1``), or no specifier at all. + + Instances are safe to serialize with :mod:`pickle`. They use a stable + format so the same pickle can be loaded in future packaging + releases. + + .. versionchanged:: 26.2 + + Added a stable pickle format. Pickles created with + packaging 26.2+ can be unpickled with future releases. + Backward compatibility with pickles from + packaging < 26.2 is supported but may be removed in a future + release. + """ + + __slots__ = ( + "_canonicalized", + "_has_arbitrary", + "_is_unsatisfiable", + "_prereleases", + "_resolved_ops", + "_specs", + ) + + def __init__( + self, + specifiers: str | Iterable[Specifier] = "", + prereleases: bool | None = None, + ) -> None: + """Initialize a SpecifierSet instance. + + :param specifiers: + The string representation of a specifier or a comma-separated list of + specifiers which will be parsed and normalized before use. + May also be an iterable of ``Specifier`` instances, which will be used + as is. + :param prereleases: + This tells the SpecifierSet if it should accept prerelease versions if + applicable or not. The default of ``None`` will autodetect it from the + given specifiers. + + :raises InvalidSpecifier: + If the given ``specifiers`` are not parseable than this exception will be + raised. + """ + + if isinstance(specifiers, str): + # Split on `,` to break each individual specifier into its own item, and + # strip each item to remove leading/trailing whitespace. + split_specifiers = [s.strip() for s in specifiers.split(",") if s.strip()] + + self._specs: tuple[Specifier, ...] = tuple(map(Specifier, split_specifiers)) + # Fast substring check; avoids iterating parsed specs. + self._has_arbitrary = "===" in specifiers + else: + self._specs = tuple(specifiers) + # Substring check works for both Specifier objects and plain + # strings (setuptools passes lists of strings). + self._has_arbitrary = any("===" in str(s) for s in self._specs) + + self._canonicalized = len(self._specs) <= 1 + self._resolved_ops: list[tuple[CallableOperator, str, str]] | None = None + + # Store our prereleases value so we can use it later to determine if + # we accept prereleases or not. + self._prereleases = prereleases + + self._is_unsatisfiable: bool | None = None + + def _canonical_specs(self) -> tuple[Specifier, ...]: + """Deduplicate, sort, and cache specs for order-sensitive operations.""" + if not self._canonicalized: + self._specs = tuple(dict.fromkeys(sorted(self._specs, key=str))) + self._canonicalized = True + self._resolved_ops = None + self._is_unsatisfiable = None + return self._specs + + @property + def prereleases(self) -> bool | None: + # If we have been given an explicit prerelease modifier, then we'll + # pass that through here. + if self._prereleases is not None: + return self._prereleases + + # If we don't have any specifiers, and we don't have a forced value, + # then we'll just return None since we don't know if this should have + # pre-releases or not. + if not self._specs: + return None + + # Otherwise we'll see if any of the given specifiers accept + # prereleases, if any of them do we'll return True, otherwise False. + if any(s.prereleases for s in self._specs): + return True + + return None + + @prereleases.setter + def prereleases(self, value: bool | None) -> None: + self._prereleases = value + self._is_unsatisfiable = None + + def __getstate__(self) -> tuple[tuple[Specifier, ...], bool | None]: + # Return state as a 2-item tuple for compactness: + # (specs, prereleases) + # Cache members are excluded and will be recomputed on demand. + return (self._specs, self._prereleases) + + def __setstate__(self, state: object) -> None: + # Always discard cached values - they will be recomputed on demand. + self._resolved_ops = None + self._is_unsatisfiable = None + + if isinstance(state, tuple): + if len(state) == 2: + # New format (26.2+): (specs, prereleases) + specs, prereleases = state + if ( + isinstance(specs, tuple) + and all(isinstance(s, Specifier) for s in specs) + and _validate_pre(prereleases) + ): + self._specs = specs + self._prereleases = prereleases + self._canonicalized = len(specs) <= 1 + self._has_arbitrary = any("===" in str(s) for s in specs) + return + if len(state) == 2 and isinstance(state[1], dict): + # Format (packaging 26.0-26.1): (None, {slot: value}). + _, slot_dict = state + specs = slot_dict.get("_specs", ()) + prereleases = slot_dict.get("_prereleases") + # Convert frozenset to tuple (26.0 stored as frozenset) + if isinstance(specs, frozenset): + specs = tuple(sorted(specs, key=str)) + if ( + isinstance(specs, tuple) + and all(isinstance(s, Specifier) for s in specs) + and _validate_pre(prereleases) + ): + self._specs = specs + self._prereleases = prereleases + self._canonicalized = len(self._specs) <= 1 + self._has_arbitrary = any("===" in str(s) for s in self._specs) + return + if isinstance(state, dict): + # Old format (packaging <= 25.x, no __slots__): state is a plain dict. + specs = state.get("_specs", ()) + prereleases = state.get("_prereleases") + # Convert frozenset to tuple (26.0 stored as frozenset) + if isinstance(specs, frozenset): + specs = tuple(sorted(specs, key=str)) + if ( + isinstance(specs, tuple) + and all(isinstance(s, Specifier) for s in specs) + and _validate_pre(prereleases) + ): + self._specs = specs + self._prereleases = prereleases + self._canonicalized = len(self._specs) <= 1 + self._has_arbitrary = any("===" in str(s) for s in self._specs) + return + + raise TypeError(f"Cannot restore SpecifierSet from {state!r}") + + def __repr__(self) -> str: + """A representation of the specifier set that shows all internal state. + + Note that the ordering of the individual specifiers within the set may not + match the input string. + + >>> SpecifierSet('>=1.0.0,!=2.0.0') + =1.0.0')> + >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=False) + =1.0.0', prereleases=False)> + >>> SpecifierSet('>=1.0.0,!=2.0.0', prereleases=True) + =1.0.0', prereleases=True)> + """ + pre = ( + f", prereleases={self.prereleases!r}" + if self._prereleases is not None + else "" + ) + + return f"<{self.__class__.__name__}({str(self)!r}{pre})>" + + def __str__(self) -> str: + """A string representation of the specifier set that can be round-tripped. + + Note that the ordering of the individual specifiers within the set may not + match the input string. + + >>> str(SpecifierSet(">=1.0.0,!=1.0.1")) + '!=1.0.1,>=1.0.0' + >>> str(SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False)) + '!=1.0.1,>=1.0.0' + """ + return ",".join(str(s) for s in self._canonical_specs()) + + def __hash__(self) -> int: + return hash(self._canonical_specs()) + + def __and__(self, other: SpecifierSet | str) -> SpecifierSet: + """Return a SpecifierSet which is a combination of the two sets. + + :param other: The other object to combine with. + + >>> SpecifierSet(">=1.0.0,!=1.0.1") & '<=2.0.0,!=2.0.1' + =1.0.0')> + >>> SpecifierSet(">=1.0.0,!=1.0.1") & SpecifierSet('<=2.0.0,!=2.0.1') + =1.0.0')> + """ + if isinstance(other, str): + other = SpecifierSet(other) + elif not isinstance(other, SpecifierSet): + return NotImplemented + + specifier = SpecifierSet() + specifier._specs = self._specs + other._specs + specifier._canonicalized = len(specifier._specs) <= 1 + specifier._has_arbitrary = self._has_arbitrary or other._has_arbitrary + specifier._resolved_ops = None + + # Combine prerelease settings: use common or non-None value + if self._prereleases is None or self._prereleases == other._prereleases: + specifier._prereleases = other._prereleases + elif other._prereleases is None: + specifier._prereleases = self._prereleases + else: + raise ValueError( + "Cannot combine SpecifierSets with True and False prerelease overrides." + ) + + return specifier + + def __eq__(self, other: object) -> bool: + """Whether or not the two SpecifierSet-like objects are equal. + + :param other: The other object to check against. + + The value of :attr:`prereleases` is ignored. + + >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.1") + True + >>> (SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False) == + ... SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True)) + True + >>> SpecifierSet(">=1.0.0,!=1.0.1") == ">=1.0.0,!=1.0.1" + True + >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0") + False + >>> SpecifierSet(">=1.0.0,!=1.0.1") == SpecifierSet(">=1.0.0,!=1.0.2") + False + """ + if isinstance(other, (str, Specifier)): + other = SpecifierSet(str(other)) + elif not isinstance(other, SpecifierSet): + return NotImplemented + + return self._canonical_specs() == other._canonical_specs() + + def __len__(self) -> int: + """Returns the number of specifiers in this specifier set.""" + return len(self._specs) + + def __iter__(self) -> Iterator[Specifier]: + """ + Returns an iterator over all the underlying :class:`Specifier` instances + in this specifier set. + + >>> sorted(SpecifierSet(">=1.0.0,!=1.0.1"), key=str) + [, =1.0.0')>] + """ + return iter(self._specs) + + def _get_ranges(self) -> Sequence[_VersionRange]: + """Intersect all specifiers into a single list of version ranges. + + Returns an empty list when unsatisfiable. ``===`` specs are + modeled as full range; string matching is checked separately + by :meth:`_check_arbitrary_unsatisfiable`. + """ + specs = self._specs + + result: Sequence[_VersionRange] | None = None + for s in specs: + if result is None: + result = s._to_ranges() + else: + result = _intersect_ranges(result, s._to_ranges()) + if not result: + break + + if result is None: # pragma: no cover + raise RuntimeError("_get_ranges called with no specs") + return result + + def is_unsatisfiable(self) -> bool: + """Check whether this specifier set can never be satisfied. + + Returns True if no version can satisfy all specifiers simultaneously. + + >>> SpecifierSet(">=2.0,<1.0").is_unsatisfiable() + True + >>> SpecifierSet(">=1.0,<2.0").is_unsatisfiable() + False + >>> SpecifierSet("").is_unsatisfiable() + False + >>> SpecifierSet("==1.0,!=1.0").is_unsatisfiable() + True + """ + cached = self._is_unsatisfiable + if cached is not None: + return cached + + if not self._specs: + self._is_unsatisfiable = False + return False + + result = not self._get_ranges() + + if not result: + result = self._check_arbitrary_unsatisfiable() + + if not result and self.prereleases is False: + result = self._check_prerelease_only_ranges() + + self._is_unsatisfiable = result + return result + + def _check_prerelease_only_ranges(self) -> bool: + """With prereleases=False, check if every range contains only + pre-release versions (which would be excluded from matching).""" + for lower, upper in self._get_ranges(): + nearest = _nearest_non_prerelease(lower.version) + if nearest is None: + return False + if upper.version is None or nearest < upper.version: + return False + if nearest == upper.version and upper.inclusive: + return False + return True + + def _check_arbitrary_unsatisfiable(self) -> bool: + """Check === (arbitrary equality) specs for unsatisfiability. + + === uses case-insensitive string comparison, so the only candidate + that can match ``===V`` is the literal string V. This method + checks whether that candidate is excluded by other specifiers. + """ + arbitrary = [s for s in self._specs if s.operator == "==="] + if not arbitrary: + return False + + # Multiple === must agree on the same string (case-insensitive). + first = arbitrary[0].version.lower() + if any(s.version.lower() != first for s in arbitrary[1:]): + return True + + # The sole candidate is the === version string. Check whether + # it can satisfy every standard spec. + candidate = _coerce_version(arbitrary[0].version) + + # With prereleases=False, a prerelease candidate is excluded + # by contains() before the === string check even runs. + if ( + self.prereleases is False + and candidate is not None + and candidate.is_prerelease + ): + return True + + standard = [s for s in self._specs if s.operator != "==="] + if not standard: + return False + + if candidate is None: + # Unparsable string cannot satisfy any standard spec. + return True + + return not all(s.contains(candidate) for s in standard) + + def __contains__(self, item: UnparsedVersion) -> bool: + """Return whether or not the item is contained in this specifier. + + :param item: The item to check for. + + This is used for the ``in`` operator and behaves the same as + :meth:`contains` with no ``prereleases`` argument passed. + + >>> "1.2.3" in SpecifierSet(">=1.0.0,!=1.0.1") + True + >>> Version("1.2.3") in SpecifierSet(">=1.0.0,!=1.0.1") + True + >>> "1.0.1" in SpecifierSet(">=1.0.0,!=1.0.1") + False + >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1") + True + >>> "1.3.0a1" in SpecifierSet(">=1.0.0,!=1.0.1", prereleases=True) + True + """ + return self.contains(item) + + def contains( + self, + item: UnparsedVersion, + prereleases: bool | None = None, + installed: bool | None = None, + ) -> bool: + """Return whether or not the item is contained in this SpecifierSet. + + :param item: + The item to check for, which can be a version string or a + :class:`Version` instance. + :param prereleases: + Whether or not to match prereleases with this SpecifierSet. If set to + ``None`` (the default), it will follow the recommendation from :pep:`440` + and match prereleases, as there are no other versions. + :param installed: + Whether or not the item is installed. If set to ``True``, it will + accept prerelease versions even if the specifier does not allow them. + + >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.2.3") + True + >>> SpecifierSet(">=1.0.0,!=1.0.1").contains(Version("1.2.3")) + True + >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.0.1") + False + >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1") + True + >>> SpecifierSet(">=1.0.0,!=1.0.1", prereleases=False).contains("1.3.0a1") + False + >>> SpecifierSet(">=1.0.0,!=1.0.1").contains("1.3.0a1", prereleases=True) + True + """ + version = _coerce_version(item) + + if version is not None and installed and version.is_prerelease: + prereleases = True + + # When item is a string and === is involved, keep it as-is + # so the comparison isn't done against the normalized form. + if version is None or (self._has_arbitrary and not isinstance(item, Version)): + check_item = item + else: + check_item = version + return bool(list(self.filter([check_item], prereleases=prereleases))) + + @typing.overload + def filter( + self, + iterable: Iterable[UnparsedVersionVar], + prereleases: bool | None = None, + key: None = ..., + ) -> Iterator[UnparsedVersionVar]: ... + + @typing.overload + def filter( + self, + iterable: Iterable[T], + prereleases: bool | None = None, + key: Callable[[T], UnparsedVersion] = ..., + ) -> Iterator[T]: ... + + def filter( + self, + iterable: Iterable[Any], + prereleases: bool | None = None, + key: Callable[[Any], UnparsedVersion] | None = None, + ) -> Iterator[Any]: + """Filter items in the given iterable, that match the specifiers in this set. + + :param iterable: + An iterable that can contain version strings and :class:`Version` instances. + The items in the iterable will be filtered according to the specifier. + :param prereleases: + Whether or not to allow prereleases in the returned iterator. If set to + ``None`` (the default), it will follow the recommendation from :pep:`440` + and match prereleases if there are no other versions. + :param key: + A callable that takes a single argument (an item from the iterable) and + returns a version string or :class:`Version` instance to be used for + filtering. + + >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", "1.5a1"])) + ['1.3'] + >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.3", Version("1.4")])) + ['1.3', ] + >>> list(SpecifierSet(">=1.2.3").filter(["1.2", "1.5a1"])) + ['1.5a1'] + >>> list(SpecifierSet(">=1.2.3").filter(["1.3", "1.5a1"], prereleases=True)) + ['1.3', '1.5a1'] + >>> list(SpecifierSet(">=1.2.3", prereleases=True).filter(["1.3", "1.5a1"])) + ['1.3', '1.5a1'] + >>> list(SpecifierSet(">=1.2.3").filter( + ... [{"ver": "1.2"}, {"ver": "1.3"}], + ... key=lambda x: x["ver"])) + [{'ver': '1.3'}] + + An "empty" SpecifierSet will filter items based on the presence of prerelease + versions in the set. + + >>> list(SpecifierSet("").filter(["1.3", "1.5a1"])) + ['1.3'] + >>> list(SpecifierSet("").filter(["1.5a1"])) + ['1.5a1'] + >>> list(SpecifierSet("", prereleases=True).filter(["1.3", "1.5a1"])) + ['1.3', '1.5a1'] + >>> list(SpecifierSet("").filter(["1.3", "1.5a1"], prereleases=True)) + ['1.3', '1.5a1'] + """ + # Determine if we're forcing a prerelease or not, if we're not forcing + # one for this particular filter call, then we'll use whatever the + # SpecifierSet thinks for whether or not we should support prereleases. + if prereleases is None and self.prereleases is not None: + prereleases = self.prereleases + + # Filter versions that match all specifiers using Cost Based Ordering. + if self._specs: + # When prereleases is None, we need to let all versions through + # the individual filters, then decide about prereleases at the end + # based on whether any non-prereleases matched ALL specs. + + # Fast path: single specifier, delegate directly. + if len(self._specs) == 1: + filtered = self._specs[0].filter( + iterable, + prereleases=True if prereleases is None else prereleases, + key=key, + ) + else: + filtered = self._filter_versions( + iterable, + key, + prereleases=True if prereleases is None else prereleases, + ) + + if prereleases is not None: + return filtered + + return _pep440_filter_prereleases(filtered, key) + + # Handle Empty SpecifierSet. + if prereleases is True: + return iter(iterable) + + if prereleases is False: + return ( + item + for item in iterable + if ( + (version := _coerce_version(item if key is None else key(item))) + is None + or not version.is_prerelease + ) + ) + + # PEP 440: exclude prereleases unless no final releases matched + return _pep440_filter_prereleases(iterable, key) + + def _filter_versions( + self, + iterable: Iterable[Any], + key: Callable[[Any], UnparsedVersion] | None, + prereleases: bool | None = None, + ) -> Iterator[Any]: + """Filter versions against all specifiers in a single pass. + + Uses Cost Based Ordering: specifiers are sorted by _operator_cost so + that cheap range operators reject versions early, avoiding expensive + wildcard or compatible operators on versions that would have been + rejected anyway. + """ + # Pre-resolve operators and sort (cached after first call). + if self._resolved_ops is None: + self._resolved_ops = sorted( + ( + (spec._get_operator(spec.operator), spec.version, spec.operator) + for spec in self._specs + ), + key=_operator_cost, + ) + ops = self._resolved_ops + exclude_prereleases = prereleases is False + + for item in iterable: + parsed = _coerce_version(item if key is None else key(item)) + + if parsed is None: + # Only === can match non-parseable versions. + if all( + op == "===" and str(item).lower() == ver.lower() + for _, ver, op in ops + ): + yield item + elif exclude_prereleases and parsed.is_prerelease: + pass + elif all( + str(item if key is None else key(item)).lower() == ver.lower() + if op == "===" + else op_fn(parsed, ver) + for op_fn, ver, op in ops + ): + # Short-circuits on the first failing operator. + yield item diff --git a/.venv/lib/python3.13/site-packages/packaging/tags.py b/.venv/lib/python3.13/site-packages/packaging/tags.py new file mode 100644 index 0000000000000000000000000000000000000000..9980ab3c63c0c4caf0045af55751a19a4d68ed92 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/tags.py @@ -0,0 +1,932 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import annotations + +import logging +import operator +import platform +import re +import struct +import subprocess +import sys +import sysconfig +from importlib.machinery import EXTENSION_SUFFIXES +from typing import ( + TYPE_CHECKING, + Iterable, + Iterator, + Sequence, + Tuple, + TypeVar, + cast, +) + +from . import _manylinux, _musllinux + +if TYPE_CHECKING: + from collections.abc import Callable, Iterable + from typing import AbstractSet + + +__all__ = [ + "INTERPRETER_SHORT_NAMES", + "AppleVersion", + "PythonVersion", + "Tag", + "UnsortedTagsError", + "android_platforms", + "compatible_tags", + "cpython_tags", + "create_compatible_tags_selector", + "generic_tags", + "interpreter_name", + "interpreter_version", + "ios_platforms", + "mac_platforms", + "parse_tag", + "platform_tags", + "sys_tags", +] + + +def __dir__() -> list[str]: + return __all__ + + +logger = logging.getLogger(__name__) + +PythonVersion = Sequence[int] +AppleVersion = Tuple[int, int] +_T = TypeVar("_T") + +INTERPRETER_SHORT_NAMES: dict[str, str] = { + "python": "py", # Generic. + "cpython": "cp", + "pypy": "pp", + "ironpython": "ip", + "jython": "jy", +} + + +# This function can be unit tested without reloading the module +# (Unlike _32_BIT_INTERPRETER) +def _compute_32_bit_interpreter() -> bool: + return struct.calcsize("P") == 4 + + +_32_BIT_INTERPRETER = _compute_32_bit_interpreter() + + +class UnsortedTagsError(ValueError): + """ + Raised when a tag component is not in sorted order per PEP 425. + """ + + +class Tag: + """ + A representation of the tag triple for a wheel. + + Instances are considered immutable and thus are hashable. Equality checking + is also supported. + + Instances are safe to serialize with :mod:`pickle`. They use a stable + format so the same pickle can be loaded in future packaging releases. + + .. versionchanged:: 26.2 + + Added a stable pickle format. Pickles created with packaging 26.2+ can + be unpickled with future releases. Backward compatibility with pickles + from packaging < 26.2 is supported but may be removed in a future + release. + """ + + __slots__ = ["_abi", "_hash", "_interpreter", "_platform"] + + def __init__(self, interpreter: str, abi: str, platform: str) -> None: + """ + :param str interpreter: The interpreter name, e.g. ``"py"`` + (see :attr:`INTERPRETER_SHORT_NAMES` for mapping + well-known interpreter names to their short names). + :param str abi: The ABI that a wheel supports, e.g. ``"cp37m"``. + :param str platform: The OS/platform the wheel supports, + e.g. ``"win_amd64"``. + """ + self._interpreter = interpreter.lower() + self._abi = abi.lower() + self._platform = platform.lower() + # The __hash__ of every single element in a Set[Tag] will be evaluated each time + # that a set calls its `.disjoint()` method, which may be called hundreds of + # times when scanning a page of links for packages with tags matching that + # Set[Tag]. Pre-computing the value here produces significant speedups for + # downstream consumers. + self._hash = hash((self._interpreter, self._abi, self._platform)) + + @property + def interpreter(self) -> str: + """ + The interpreter name, e.g. ``"py"`` (see + :attr:`INTERPRETER_SHORT_NAMES` for mapping well-known interpreter + names to their short names). + """ + return self._interpreter + + @property + def abi(self) -> str: + """ + The supported ABI. + """ + return self._abi + + @property + def platform(self) -> str: + """ + The OS/platform. + """ + return self._platform + + def __eq__(self, other: object) -> bool: + if not isinstance(other, Tag): + return NotImplemented + + return ( + (self._hash == other._hash) # Short-circuit ASAP for perf reasons. + and (self._platform == other._platform) + and (self._abi == other._abi) + and (self._interpreter == other._interpreter) + ) + + def __hash__(self) -> int: + return self._hash + + def __str__(self) -> str: + return f"{self._interpreter}-{self._abi}-{self._platform}" + + def __repr__(self) -> str: + return f"<{self} @ {id(self)}>" + + def __getstate__(self) -> tuple[str, str, str]: + # Return state as a 3-item tuple: (interpreter, abi, platform). + # Cache member _hash is excluded and will be recomputed. + return (self._interpreter, self._abi, self._platform) + + def __setstate__(self, state: object) -> None: + if isinstance(state, tuple): + if len(state) == 3 and all(isinstance(s, str) for s in state): + # New format (26.2+): (interpreter, abi, platform) + self._interpreter, self._abi, self._platform = state + self._hash = hash((self._interpreter, self._abi, self._platform)) + return + if len(state) == 2 and isinstance(state[1], dict): + # Old format (packaging <= 26.1, __slots__): (None, {slot: value}). + _, slots = state + try: + interpreter = slots["_interpreter"] + abi = slots["_abi"] + platform = slots["_platform"] + except KeyError: + raise TypeError(f"Cannot restore Tag from {state!r}") from None + if not all( + isinstance(value, str) for value in (interpreter, abi, platform) + ): + raise TypeError(f"Cannot restore Tag from {state!r}") + self._interpreter = interpreter.lower() + self._abi = abi.lower() + self._platform = platform.lower() + self._hash = hash((self._interpreter, self._abi, self._platform)) + return + raise TypeError(f"Cannot restore Tag from {state!r}") + + +def parse_tag(tag: str, *, validate_order: bool = False) -> frozenset[Tag]: + """ + Parses the provided tag (e.g. `py3-none-any`) into a frozenset of + :class:`Tag` instances. + + Returning a set is required due to the possibility that the tag is a + `compressed tag set`_, e.g. ``"py2.py3-none-any"`` which supports both + Python 2 and Python 3. + + If **validate_order** is true, compressed tag set components are checked + to be in sorted order as required by PEP 425. + + :param str tag: The tag to parse, e.g. ``"py3-none-any"``. + :param bool validate_order: Check whether compressed tag set components + are in sorted order. + :raises UnsortedTagsError: If **validate_order** is true and any compressed tag + set component is not in sorted order. + + .. versionadded:: 26.1 + The *validate_order* parameter. + """ + tags = set() + interpreters, abis, platforms = tag.split("-") + if validate_order: + for component in (interpreters, abis, platforms): + parts = component.split(".") + if parts != sorted(parts): + raise UnsortedTagsError( + f"Tag component {component!r} is not in sorted order per PEP 425" + ) + for interpreter in interpreters.split("."): + for abi in abis.split("."): + for platform_ in platforms.split("."): + tags.add(Tag(interpreter, abi, platform_)) + return frozenset(tags) + + +def _get_config_var(name: str, warn: bool = False) -> int | str | None: + value: int | str | None = sysconfig.get_config_var(name) + if value is None and warn: + logger.debug( + "Config variable '%s' is unset, Python ABI tag may be incorrect", name + ) + return value + + +def _normalize_string(string: str) -> str: + return string.replace(".", "_").replace("-", "_").replace(" ", "_") + + +def _is_threaded_cpython(abis: list[str]) -> bool: + """ + Determine if the ABI corresponds to a threaded (`--disable-gil`) build. + + The threaded builds are indicated by a "t" in the abiflags. + """ + if len(abis) == 0: + return False + # expect e.g., cp313 + m = re.match(r"cp\d+(.*)", abis[0]) + if not m: + return False + abiflags = m.group(1) + return "t" in abiflags + + +def _abi3_applies(python_version: PythonVersion, threading: bool) -> bool: + """ + Determine if the Python version supports abi3. + + PEP 384 was first implemented in Python 3.2. The free-threaded + builds do not support abi3. + """ + return len(python_version) > 1 and tuple(python_version) >= (3, 2) and not threading + + +def _abi3t_applies(python_version: PythonVersion, threading: bool) -> bool: + """ + Determine if the Python version supports abi3t. + + PEP 803 was first implemented in Python 3.15 but, per PEP 803, this + returns tags going back to Python 3.2 to mirror the abi3 + implementation and leave open the possibility of abi3t wheels + supporting older Python versions. + + """ + return len(python_version) > 1 and tuple(python_version) >= (3, 2) and threading + + +def _cpython_abis(py_version: PythonVersion, warn: bool = False) -> list[str]: + py_version = tuple(py_version) # To allow for version comparison. + abis = [] + version = _version_nodot(py_version[:2]) + threading = debug = pymalloc = ucs4 = "" + with_debug = _get_config_var("Py_DEBUG", warn) + has_refcount = hasattr(sys, "gettotalrefcount") + # Windows doesn't set Py_DEBUG, so checking for support of debug-compiled + # extension modules is the best option. + # https://github.com/pypa/pip/issues/3383#issuecomment-173267692 + has_ext = "_d.pyd" in EXTENSION_SUFFIXES + if with_debug or (with_debug is None and (has_refcount or has_ext)): + debug = "d" + if py_version >= (3, 13) and _get_config_var("Py_GIL_DISABLED", warn): + threading = "t" + if py_version < (3, 8): + with_pymalloc = _get_config_var("WITH_PYMALLOC", warn) + if with_pymalloc or with_pymalloc is None: + pymalloc = "m" + if py_version < (3, 3): + unicode_size = _get_config_var("Py_UNICODE_SIZE", warn) + if unicode_size == 4 or ( + unicode_size is None and sys.maxunicode == 0x10FFFF + ): + ucs4 = "u" + elif debug: + # Debug builds can also load "normal" extension modules. + # We can also assume no UCS-4 or pymalloc requirement. + abis.append(f"cp{version}{threading}") + abis.insert(0, f"cp{version}{threading}{debug}{pymalloc}{ucs4}") + return abis + + +def cpython_tags( + python_version: PythonVersion | None = None, + abis: Iterable[str] | None = None, + platforms: Iterable[str] | None = None, + *, + warn: bool = False, +) -> Iterator[Tag]: + """ + Yields the tags for the CPython interpreter. + + The specific tags generated are: + + - ``cp--`` + - ``cp--`` + - ``cp-none-`` + - ``cp--`` where "older version" is all older + minor versions down to Python 3.2 (when ``abi3`` was introduced) + + If ``python_version`` only provides a major-only version then only + user-provided ABIs via ``abis`` and the ``none`` ABI will be used. + + The ``stable_abi`` will be either ``abi3`` or ``abi3t`` if `abi` is a + GIL-enabled ABI like `"cp315"` or a free-threaded ABI like `"cp315t"`, + respectively. + + :param Sequence python_version: A one- or two-item sequence representing the + targeted Python version. Defaults to + ``sys.version_info[:2]``. + :param Iterable abis: Iterable of compatible ABIs. Defaults to the ABIs + compatible with the current system. + :param Iterable platforms: Iterable of compatible platforms. Defaults to the + platforms compatible with the current system. + :param bool warn: Whether warnings should be logged. Defaults to ``False``. + """ + if not python_version: + python_version = sys.version_info[:2] + + interpreter = f"cp{_version_nodot(python_version[:2])}" + + if abis is None: + abis = _cpython_abis(python_version, warn) if len(python_version) > 1 else [] + abis = list(abis) + # 'abi3' and 'none' are explicitly handled later. + for explicit_abi in ("abi3", "none"): + try: + abis.remove(explicit_abi) + except ValueError: # noqa: PERF203 + pass + + platforms = list(platforms or platform_tags()) + for abi in abis: + for platform_ in platforms: + yield Tag(interpreter, abi, platform_) + + threading = _is_threaded_cpython(abis) + use_abi3 = _abi3_applies(python_version, threading) + use_abi3t = _abi3t_applies(python_version, threading) + + if use_abi3: + yield from (Tag(interpreter, "abi3", platform_) for platform_ in platforms) + if use_abi3t: + yield from (Tag(interpreter, "abi3t", platform_) for platform_ in platforms) + + yield from (Tag(interpreter, "none", platform_) for platform_ in platforms) + + if use_abi3 or use_abi3t: + for minor_version in range(python_version[1] - 1, 1, -1): + for platform_ in platforms: + version = _version_nodot((python_version[0], minor_version)) + interpreter = f"cp{version}" + if use_abi3: + yield Tag(interpreter, "abi3", platform_) + if use_abi3t: + # Support for abi3t was introduced in Python 3.15, but in + # principle abi3t wheels are possible for older limited API + # versions, so allow things like ("cp37", "abi3t", "platform") + yield Tag(interpreter, "abi3t", platform_) + + +def _generic_abi() -> list[str]: + """ + Return the ABI tag based on EXT_SUFFIX. + """ + # The following are examples of `EXT_SUFFIX`. + # We want to keep the parts which are related to the ABI and remove the + # parts which are related to the platform: + # - linux: '.cpython-310-x86_64-linux-gnu.so' => cp310 + # - mac: '.cpython-310-darwin.so' => cp310 + # - win: '.cp310-win_amd64.pyd' => cp310 + # - win: '.pyd' => cp37 (uses _cpython_abis()) + # - pypy: '.pypy38-pp73-x86_64-linux-gnu.so' => pypy38_pp73 + # - graalpy: '.graalpy-38-native-x86_64-darwin.dylib' + # => graalpy_38_native + + ext_suffix = _get_config_var("EXT_SUFFIX", warn=True) + if not isinstance(ext_suffix, str) or ext_suffix[0] != ".": + raise SystemError("invalid sysconfig.get_config_var('EXT_SUFFIX')") + parts = ext_suffix.split(".") + if len(parts) < 3: + # CPython3.7 and earlier uses ".pyd" on Windows. + return _cpython_abis(sys.version_info[:2]) + soabi = parts[1] + if soabi.startswith("cpython"): + # non-windows + abi = "cp" + soabi.split("-")[1] + elif soabi.startswith("cp"): + # windows + abi = soabi.split("-")[0] + elif soabi.startswith("pypy"): + abi = "-".join(soabi.split("-")[:2]) + elif soabi.startswith("graalpy"): + abi = "-".join(soabi.split("-")[:3]) + elif soabi: + # pyston, ironpython, others? + abi = soabi + else: + return [] + return [_normalize_string(abi)] + + +def generic_tags( + interpreter: str | None = None, + abis: Iterable[str] | None = None, + platforms: Iterable[str] | None = None, + *, + warn: bool = False, +) -> Iterator[Tag]: + """ + Yields the tags for an interpreter which requires no specialization. + + This function should be used if one of the other interpreter-specific + functions provided by this module is not appropriate (i.e. not calculating + tags for a CPython interpreter). + + The specific tags generated are: + + - ``--`` + + The ``"none"`` ABI will be added if it was not explicitly provided. + + :param str interpreter: The name of the interpreter. Defaults to being + calculated. + :param Iterable abis: Iterable of compatible ABIs. Defaults to the ABIs + compatible with the current system. + :param Iterable platforms: Iterable of compatible platforms. Defaults to the + platforms compatible with the current system. + :param bool warn: Whether warnings should be logged. Defaults to ``False``. + """ + if not interpreter: + interp_name = interpreter_name() + interp_version = interpreter_version(warn=warn) + interpreter = f"{interp_name}{interp_version}" + abis = _generic_abi() if abis is None else list(abis) + platforms = list(platforms or platform_tags()) + if "none" not in abis: + abis.append("none") + for abi in abis: + for platform_ in platforms: + yield Tag(interpreter, abi, platform_) + + +def _py_interpreter_range(py_version: PythonVersion) -> Iterator[str]: + """ + Yields Python versions in descending order. + + After the latest version, the major-only version will be yielded, and then + all previous versions of that major version. + """ + if len(py_version) > 1: + yield f"py{_version_nodot(py_version[:2])}" + yield f"py{py_version[0]}" + if len(py_version) > 1: + for minor in range(py_version[1] - 1, -1, -1): + yield f"py{_version_nodot((py_version[0], minor))}" + + +def compatible_tags( + python_version: PythonVersion | None = None, + interpreter: str | None = None, + platforms: Iterable[str] | None = None, +) -> Iterator[Tag]: + """ + Yields the tags for an interpreter compatible with the Python version + specified by ``python_version``. + + The specific tags generated are: + + - ``py*-none-`` + - ``-none-any`` if ``interpreter`` is provided + - ``py*-none-any`` + + :param Sequence python_version: A one- or two-item sequence representing the + compatible version of Python. Defaults to + ``sys.version_info[:2]``. + :param str interpreter: The name of the interpreter (if known), e.g. + ``"cp38"``. Defaults to the current interpreter. + :param Iterable platforms: Iterable of compatible platforms. Defaults to the + platforms compatible with the current system. + """ + if not python_version: + python_version = sys.version_info[:2] + platforms = list(platforms or platform_tags()) + for version in _py_interpreter_range(python_version): + for platform_ in platforms: + yield Tag(version, "none", platform_) + if interpreter: + yield Tag(interpreter, "none", "any") + for version in _py_interpreter_range(python_version): + yield Tag(version, "none", "any") + + +def _mac_arch(arch: str, is_32bit: bool = _32_BIT_INTERPRETER) -> str: + if not is_32bit: + return arch + + if arch.startswith("ppc"): + return "ppc" + + return "i386" + + +def _mac_binary_formats(version: AppleVersion, cpu_arch: str) -> list[str]: + formats = [cpu_arch] + if cpu_arch == "x86_64": + if version < (10, 4): + return [] + formats.extend(["intel", "fat64", "fat32"]) + + elif cpu_arch == "i386": + if version < (10, 4): + return [] + formats.extend(["intel", "fat32", "fat"]) + + elif cpu_arch == "ppc64": + # TODO: Need to care about 32-bit PPC for ppc64 through 10.2? + if version > (10, 5) or version < (10, 4): + return [] + formats.append("fat64") + + elif cpu_arch == "ppc": + if version > (10, 6): + return [] + formats.extend(["fat32", "fat"]) + + if cpu_arch in {"arm64", "x86_64"}: + formats.append("universal2") + + if cpu_arch in {"x86_64", "i386", "ppc64", "ppc", "intel"}: + formats.append("universal") + + return formats + + +def mac_platforms( + version: AppleVersion | None = None, arch: str | None = None +) -> Iterator[str]: + """ + Yields the :attr:`~Tag.platform` tags for macOS. + + The `version` parameter is a two-item tuple specifying the macOS version to + generate platform tags for. The `arch` parameter is the CPU architecture to + generate platform tags for. Both parameters default to the appropriate value + for the current system. + + :param tuple version: A two-item tuple representing the version of macOS. + Defaults to the current system's version. + :param str arch: The CPU architecture. Defaults to the architecture of the + current system, e.g. ``"x86_64"``. + + .. note:: + Equivalent support for the other major platforms is purposefully not + provided: + + - On Windows, platform compatibility is statically specified + - On Linux, code must be run on the system itself to determine + compatibility + """ + version_str, _, cpu_arch = platform.mac_ver() + if version is None: + version = cast("AppleVersion", tuple(map(int, version_str.split(".")[:2]))) + if version == (10, 16): + # When built against an older macOS SDK, Python will report macOS 10.16 + # instead of the real version. + version_str = subprocess.run( + [ + sys.executable, + "-sS", + "-c", + "import platform; print(platform.mac_ver()[0])", + ], + check=True, + env={"SYSTEM_VERSION_COMPAT": "0"}, + stdout=subprocess.PIPE, + text=True, + ).stdout + version = cast("AppleVersion", tuple(map(int, version_str.split(".")[:2]))) + + if arch is None: + arch = _mac_arch(cpu_arch) + + if (10, 0) <= version < (11, 0): + # Prior to Mac OS 11, each yearly release of Mac OS bumped the + # "minor" version number. The major version was always 10. + major_version = 10 + for minor_version in range(version[1], -1, -1): + compat_version = major_version, minor_version + binary_formats = _mac_binary_formats(compat_version, arch) + for binary_format in binary_formats: + yield f"macosx_{major_version}_{minor_version}_{binary_format}" + + if version >= (11, 0): + # Starting with Mac OS 11, each yearly release bumps the major version + # number. The minor versions are now the midyear updates. + minor_version = 0 + for major_version in range(version[0], 10, -1): + compat_version = major_version, minor_version + binary_formats = _mac_binary_formats(compat_version, arch) + for binary_format in binary_formats: + yield f"macosx_{major_version}_{minor_version}_{binary_format}" + + if version >= (11, 0): + # Mac OS 11 on x86_64 is compatible with binaries from previous releases. + # Arm64 support was introduced in 11.0, so no Arm binaries from previous + # releases exist. + # + # However, the "universal2" binary format can have a + # macOS version earlier than 11.0 when the x86_64 part of the binary supports + # that version of macOS. + major_version = 10 + if arch == "x86_64": + for minor_version in range(16, 3, -1): + compat_version = major_version, minor_version + binary_formats = _mac_binary_formats(compat_version, arch) + for binary_format in binary_formats: + yield f"macosx_{major_version}_{minor_version}_{binary_format}" + else: + for minor_version in range(16, 3, -1): + compat_version = major_version, minor_version + binary_format = "universal2" + yield f"macosx_{major_version}_{minor_version}_{binary_format}" + + +def ios_platforms( + version: AppleVersion | None = None, multiarch: str | None = None +) -> Iterator[str]: + """ + + Yields the :attr:`~Tag.platform` tags for iOS. + + :param tuple version: A two-item tuple representing the version of iOS. + Defaults to the current system's version. + :param str multiarch: The CPU architecture+ABI to be used. This should be in + the format by ``sys.implementation._multiarch`` (e.g., + ``arm64_iphoneos`` or ``x86_64_iphonesimulator``). + Defaults to the current system's multiarch value. + + .. note:: + Behavior of this method is undefined if invoked on non-iOS platforms + without providing explicit version and multiarch arguments. + """ + if version is None: + # if iOS is the current platform, ios_ver *must* be defined. However, + # it won't exist for CPython versions before 3.13, which causes a mypy + # error. + _, release, _, _ = platform.ios_ver() # type: ignore[attr-defined, unused-ignore] + version = cast("AppleVersion", tuple(map(int, release.split(".")[:2]))) + + if multiarch is None: + multiarch = sys.implementation._multiarch + multiarch = multiarch.replace("-", "_") + + ios_platform_template = "ios_{major}_{minor}_{multiarch}" + + # Consider any iOS major.minor version from the version requested, down to + # 12.0. 12.0 is the first iOS version that is known to have enough features + # to support CPython. Consider every possible minor release up to X.9. There + # highest the minor has ever gone is 8 (14.8 and 15.8) but having some extra + # candidates that won't ever match doesn't really hurt, and it saves us from + # having to keep an explicit list of known iOS versions in the code. Return + # the results descending order of version number. + + # If the requested major version is less than 12, there won't be any matches. + if version[0] < 12: + return + + # Consider the actual X.Y version that was requested. + yield ios_platform_template.format( + major=version[0], minor=version[1], multiarch=multiarch + ) + + # Consider every minor version from X.0 to the minor version prior to the + # version requested by the platform. + for minor in range(version[1] - 1, -1, -1): + yield ios_platform_template.format( + major=version[0], minor=minor, multiarch=multiarch + ) + + for major in range(version[0] - 1, 11, -1): + for minor in range(9, -1, -1): + yield ios_platform_template.format( + major=major, minor=minor, multiarch=multiarch + ) + + +def android_platforms( + api_level: int | None = None, abi: str | None = None +) -> Iterator[str]: + """ + Yields the :attr:`~Tag.platform` tags for Android. If this function is invoked on + non-Android platforms, the ``api_level`` and ``abi`` arguments are required. + + :param int api_level: The maximum `API level + `__ to return. Defaults + to the current system's version, as returned by ``platform.android_ver``. + :param str abi: The `Android ABI `__, + e.g. ``arm64_v8a``. Defaults to the current system's ABI , as returned by + ``sysconfig.get_platform``. Hyphens and periods will be replaced with + underscores. + """ + if platform.system() != "Android" and (api_level is None or abi is None): + raise TypeError( + "on non-Android platforms, the api_level and abi arguments are required" + ) + + if api_level is None: + # Python 3.13 was the first version to return platform.system() == "Android", + # and also the first version to define platform.android_ver(). + api_level = platform.android_ver().api_level # type: ignore[attr-defined] + + if abi is None: + abi = sysconfig.get_platform().split("-")[-1] + abi = _normalize_string(abi) + + # 16 is the minimum API level known to have enough features to support CPython + # without major patching. Yield every API level from the maximum down to the + # minimum, inclusive. + min_api_level = 16 + for ver in range(api_level, min_api_level - 1, -1): + yield f"android_{ver}_{abi}" + + +def _linux_platforms(is_32bit: bool = _32_BIT_INTERPRETER) -> Iterator[str]: + linux = _normalize_string(sysconfig.get_platform()) + if not linux.startswith("linux_"): + # we should never be here, just yield the sysconfig one and return + yield linux + return + if is_32bit: + if linux == "linux_x86_64": + linux = "linux_i686" + elif linux == "linux_aarch64": + linux = "linux_armv8l" + _, arch = linux.split("_", 1) + archs = {"armv8l": ["armv8l", "armv7l"]}.get(arch, [arch]) + yield from _manylinux.platform_tags(archs) + yield from _musllinux.platform_tags(archs) + for arch in archs: + yield f"linux_{arch}" + + +def _emscripten_platforms() -> Iterator[str]: + pyemscripten_platform_version = sysconfig.get_config_var( + "PYEMSCRIPTEN_PLATFORM_VERSION" + ) + if pyemscripten_platform_version: + yield f"pyemscripten_{pyemscripten_platform_version}_wasm32" + yield from _generic_platforms() + + +def _generic_platforms() -> Iterator[str]: + yield _normalize_string(sysconfig.get_platform()) + + +def platform_tags() -> Iterator[str]: + """ + Yields the :attr:`~Tag.platform` tags for the running interpreter. + """ + if platform.system() == "Darwin": + return mac_platforms() + elif platform.system() == "iOS": + return ios_platforms() + elif platform.system() == "Android": + return android_platforms() + elif platform.system() == "Linux": + return _linux_platforms() + elif platform.system() == "Emscripten": + return _emscripten_platforms() + else: + return _generic_platforms() + + +def interpreter_name() -> str: + """ + Returns the name of the running interpreter. + + Some implementations have a reserved, two-letter abbreviation which will + be returned when appropriate. + + This typically acts as the prefix to the :attr:`~Tag.interpreter` tag. + """ + name = sys.implementation.name + return INTERPRETER_SHORT_NAMES.get(name) or name + + +def interpreter_version(*, warn: bool = False) -> str: + """ + Returns the running interpreter's version. + + This typically acts as the suffix to the :attr:`~Tag.interpreter` tag. + + :param bool warn: Whether warnings should be logged. Defaults to ``False``. + """ + version = _get_config_var("py_version_nodot", warn=warn) + return str(version) if version else _version_nodot(sys.version_info[:2]) + + +def _version_nodot(version: PythonVersion) -> str: + return "".join(map(str, version)) + + +def sys_tags(*, warn: bool = False) -> Iterator[Tag]: + """ + Yields the sequence of tag triples that the running interpreter supports. + + The iterable is ordered so that the best-matching tag is first in the + sequence. The exact preferential order to tags is interpreter-specific, but + in general the tag importance is in the order of: + + 1. Interpreter + 2. Platform + 3. ABI + + This order is due to the fact that an ABI is inherently tied to the + platform, but platform-specific code is not necessarily tied to the ABI. The + interpreter is the most important tag as it dictates basic support for any + wheel. + + The function returns an iterable in order to allow for the possible + short-circuiting of tag generation if the entire sequence is not necessary + and tag calculation happens to be expensive. + + :param bool warn: Whether warnings should be logged. Defaults to ``False``. + + .. versionchanged:: 21.3 + Added the `pp3-none-any` tag (:issue:`311`). + .. versionchanged:: 27.0 + Added the `abi3t` tag (:issue:`1099`). + """ + + interp_name = interpreter_name() + if interp_name == "cp": + yield from cpython_tags(warn=warn) + else: + yield from generic_tags() + + if interp_name == "pp": + interp = "pp3" + elif interp_name == "cp": + interp = "cp" + interpreter_version(warn=warn) + else: + interp = None + yield from compatible_tags(interpreter=interp) + + +def create_compatible_tags_selector( + tags: Iterable[Tag], +) -> Callable[[Iterable[tuple[_T, AbstractSet[Tag]]]], Iterator[_T]]: + """Create a callable to select things compatible with supported tags. + + This function accepts an ordered sequence of tags, with the preferred + tags first. + + The returned callable accepts an iterable of tuples (thing, set[Tag]), + and returns an iterator of things, with the things with the best + matching tags first. + + Example to select compatible wheel filenames: + + >>> from packaging import tags + >>> from packaging.utils import parse_wheel_filename + >>> selector = tags.create_compatible_tags_selector(tags.sys_tags()) + >>> filenames = ["foo-1.0-py3-none-any.whl", "foo-1.0-py2-none-any.whl"] + >>> list(selector([ + ... (filename, parse_wheel_filename(filename)[-1]) for filename in filenames + ... ])) + ['foo-1.0-py3-none-any.whl'] + + .. versionadded:: 26.1 + """ + tag_ranks: dict[Tag, int] = {} + for rank, tag in enumerate(tags): + tag_ranks.setdefault(tag, rank) # ignore duplicate tags, keep first + supported_tags = tag_ranks.keys() + + def selector( + tagged_things: Iterable[tuple[_T, AbstractSet[Tag]]], + ) -> Iterator[_T]: + ranked_things: list[tuple[_T, int]] = [] + for thing, thing_tags in tagged_things: + supported_thing_tags = thing_tags & supported_tags + if supported_thing_tags: + thing_rank = min(tag_ranks[t] for t in supported_thing_tags) + ranked_things.append((thing, thing_rank)) + return iter( + thing for thing, _ in sorted(ranked_things, key=operator.itemgetter(1)) + ) + + return selector diff --git a/.venv/lib/python3.13/site-packages/packaging/utils.py b/.venv/lib/python3.13/site-packages/packaging/utils.py new file mode 100644 index 0000000000000000000000000000000000000000..cbd3be27c4211f73330a318debf6a490b8b9d8ba --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/utils.py @@ -0,0 +1,296 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. + +from __future__ import annotations + +import re +from typing import NewType, Tuple, Union, cast + +from .tags import Tag, UnsortedTagsError, parse_tag +from .version import InvalidVersion, Version, _TrimmedRelease + +__all__ = [ + "BuildTag", + "InvalidName", + "InvalidSdistFilename", + "InvalidWheelFilename", + "NormalizedName", + "canonicalize_name", + "canonicalize_version", + "is_normalized_name", + "parse_sdist_filename", + "parse_wheel_filename", +] + + +def __dir__() -> list[str]: + return __all__ + + +BuildTag = Union[Tuple[()], Tuple[int, str]] + +NormalizedName = NewType("NormalizedName", str) +""" +A :class:`typing.NewType` of :class:`str`, representing a normalized name. +""" + + +class InvalidName(ValueError): + """ + An invalid distribution name; users should refer to the packaging user guide. + """ + + +class InvalidWheelFilename(ValueError): + """ + An invalid wheel filename was found, users should refer to PEP 427. + """ + + +class InvalidSdistFilename(ValueError): + """ + An invalid sdist filename was found, users should refer to the packaging user guide. + """ + + +# Core metadata spec for `Name` +_validate_regex = re.compile( + r"[a-z0-9]|[a-z0-9][a-z0-9._-]*[a-z0-9]", re.IGNORECASE | re.ASCII +) +_normalized_regex = re.compile(r"[a-z0-9]|[a-z0-9]([a-z0-9-](?!--))*[a-z0-9]", re.ASCII) +# PEP 427: The build number must start with a digit. +_build_tag_regex = re.compile(r"(\d+)(.*)", re.ASCII) + + +def canonicalize_name(name: str, *, validate: bool = False) -> NormalizedName: + """ + This function takes a valid Python package or extra name, and returns the + normalized form of it. + + The return type is typed as :class:`NormalizedName`. This allows type + checkers to help require that a string has passed through this function + before use. + + If **validate** is true, then the function will check if **name** is a valid + distribution name before normalizing. + + :param str name: The name to normalize. + :param bool validate: Check whether the name is a valid distribution name. + :raises InvalidName: If **validate** is true and the name is not an + acceptable distribution name. + + >>> from packaging.utils import canonicalize_name + >>> canonicalize_name("Django") + 'django' + >>> canonicalize_name("oslo.concurrency") + 'oslo-concurrency' + >>> canonicalize_name("requests") + 'requests' + """ + if validate and not _validate_regex.fullmatch(name): + raise InvalidName(f"name is invalid: {name!r}") + # Ensure all ``.`` and ``_`` are ``-`` + # Emulates ``re.sub(r"[-_.]+", "-", name).lower()`` from PEP 503 + # Much faster than re, and even faster than str.translate + value = name.lower().replace("_", "-").replace(".", "-") + # Condense repeats (faster than regex) + while "--" in value: + value = value.replace("--", "-") + return cast("NormalizedName", value) + + +def is_normalized_name(name: str) -> bool: + """ + Check if a name is already normalized (i.e. :func:`canonicalize_name` would + roundtrip to the same value). + + :param str name: The name to check. + + >>> from packaging.utils import is_normalized_name + >>> is_normalized_name("requests") + True + >>> is_normalized_name("Django") + False + """ + return _normalized_regex.fullmatch(name) is not None + + +def canonicalize_version( + version: Version | str, *, strip_trailing_zero: bool = True +) -> str: + """Return a canonical form of a version as a string. + + This function takes a string representing a package version (or a + :class:`~packaging.version.Version` instance), and returns the + normalized form of it. By default, it strips trailing zeros from + the release segment. + + >>> from packaging.utils import canonicalize_version + >>> canonicalize_version('1.0.1') + '1.0.1' + + Per PEP 625, versions may have multiple canonical forms, differing + only by trailing zeros. + + >>> canonicalize_version('1.0.0') + '1' + >>> canonicalize_version('1.0.0', strip_trailing_zero=False) + '1.0.0' + + Invalid versions are returned unaltered. + + >>> canonicalize_version('foo bar baz') + 'foo bar baz' + + >>> canonicalize_version('1.4.0.0.0') + '1.4' + """ + if isinstance(version, str): + try: + version = Version(version) + except InvalidVersion: + return str(version) + return str(_TrimmedRelease(version) if strip_trailing_zero else version) + + +def parse_wheel_filename( + filename: str, + *, + validate_order: bool = False, +) -> tuple[NormalizedName, Version, BuildTag, frozenset[Tag]]: + """ + This function takes the filename of a wheel file, and parses it, + returning a tuple of name, version, build number, and tags. + + The name part of the tuple is normalized and typed as + :class:`NormalizedName`. The version portion is an instance of + :class:`~packaging.version.Version`. The build number is ``()`` if + there is no build number in the wheel filename, otherwise a + two-item tuple of an integer for the leading digits and + a string for the rest of the build number. The tags portion is a + frozen set of :class:`~packaging.tags.Tag` instances (as the tag + string format allows multiple tags to be combined into a single + string). + + If **validate_order** is true, compressed tag set components are + checked to be in sorted order as required by PEP 425. + + :param str filename: The name of the wheel file. + :param bool validate_order: Check whether compressed tag set components + are in sorted order. + :raises InvalidWheelFilename: If the filename in question + does not follow the :ref:`wheel specification + `. + + >>> from packaging.utils import parse_wheel_filename + >>> from packaging.tags import Tag + >>> from packaging.version import Version + >>> name, ver, build, tags = parse_wheel_filename("foo-1.0-py3-none-any.whl") + >>> name + 'foo' + >>> ver == Version('1.0') + True + >>> tags == {Tag("py3", "none", "any")} + True + >>> not build + True + + .. versionadded:: 26.1 + The *validate_order* parameter. + """ + if not filename.endswith(".whl"): + raise InvalidWheelFilename( + f"Invalid wheel filename (extension must be '.whl'): {filename!r}" + ) + + filename = filename[:-4] + dashes = filename.count("-") + if dashes not in (4, 5): + raise InvalidWheelFilename( + f"Invalid wheel filename (wrong number of parts): {filename!r}" + ) + + parts = filename.split("-", dashes - 2) + name_part = parts[0] + # See PEP 427 for the rules on escaping the project name. + if "__" in name_part or re.match(r"^[\w\d._]*$", name_part, re.UNICODE) is None: + raise InvalidWheelFilename(f"Invalid project name: {filename!r}") + name = canonicalize_name(name_part) + + try: + version = Version(parts[1]) + except InvalidVersion as e: + raise InvalidWheelFilename( + f"Invalid wheel filename (invalid version): {filename!r}" + ) from e + + if dashes == 5: + build_part = parts[2] + build_match = _build_tag_regex.match(build_part) + if build_match is None: + raise InvalidWheelFilename( + f"Invalid build number: {build_part} in {filename!r}" + ) + build = cast("BuildTag", (int(build_match.group(1)), build_match.group(2))) + else: + build = () + tag_str = parts[-1] + try: + tags = parse_tag(tag_str, validate_order=validate_order) + except UnsortedTagsError: + raise InvalidWheelFilename( + f"Invalid wheel filename (compressed tag set components must be in " + f"sorted order per PEP 425): {filename!r}" + ) from None + return (name, version, build, tags) + + +def parse_sdist_filename(filename: str) -> tuple[NormalizedName, Version]: + """ + This function takes the filename of a sdist file (as specified + in the `Source distribution format`_ documentation), and parses + it, returning a tuple of the normalized name and version as + represented by an instance of :class:`~packaging.version.Version`. + + :param str filename: The name of the sdist file. + :raises InvalidSdistFilename: If the filename does not end + with an sdist extension (``.zip`` or ``.tar.gz``), or if it does not + contain a dash separating the name and the version of the distribution. + + >>> from packaging.utils import parse_sdist_filename + >>> from packaging.version import Version + >>> name, ver = parse_sdist_filename("foo-1.0.tar.gz") + >>> name + 'foo' + >>> ver == Version('1.0') + True + + .. _Source distribution format: https://packaging.python.org/specifications/source-distribution-format/#source-distribution-file-name + """ + if filename.endswith(".tar.gz"): + file_stem = filename[: -len(".tar.gz")] + elif filename.endswith(".zip"): + file_stem = filename[: -len(".zip")] + else: + raise InvalidSdistFilename( + f"Invalid sdist filename (extension must be '.tar.gz' or '.zip'):" + f" {filename!r}" + ) + + # We are requiring a PEP 440 version, which cannot contain dashes, + # so we split on the last dash. + name_part, sep, version_part = file_stem.rpartition("-") + if not sep: + raise InvalidSdistFilename(f"Invalid sdist filename: {filename!r}") + + name = canonicalize_name(name_part) + + try: + version = Version(version_part) + except InvalidVersion as e: + raise InvalidSdistFilename( + f"Invalid sdist filename (invalid version): {filename!r}" + ) from e + + return (name, version) diff --git a/.venv/lib/python3.13/site-packages/packaging/version.py b/.venv/lib/python3.13/site-packages/packaging/version.py new file mode 100644 index 0000000000000000000000000000000000000000..97f23fd9ad66a66ecfb8ebbabebc08d4cc51d683 --- /dev/null +++ b/.venv/lib/python3.13/site-packages/packaging/version.py @@ -0,0 +1,1231 @@ +# This file is dual licensed under the terms of the Apache License, Version +# 2.0, and the BSD License. See the LICENSE file in the root of this repository +# for complete details. +""" +.. testsetup:: + + from packaging.version import parse, normalize_pre, Version, _cmpkey +""" + +from __future__ import annotations + +import re +import sys +import typing +from typing import ( + Any, + Callable, + Literal, + NamedTuple, + SupportsInt, + Tuple, + TypedDict, + Union, +) + +if typing.TYPE_CHECKING: + from typing_extensions import Self, Unpack + +if sys.version_info >= (3, 13): # pragma: no cover + from warnings import deprecated as _deprecated +elif typing.TYPE_CHECKING: + from typing_extensions import deprecated as _deprecated +else: # pragma: no cover + import functools + import warnings + + def _deprecated(message: str) -> object: + def decorator(func: Callable[[...], object]) -> object: + @functools.wraps(func) + def wrapper(*args: object, **kwargs: object) -> object: + warnings.warn( + message, + category=DeprecationWarning, + stacklevel=2, + ) + return func(*args, **kwargs) + + return wrapper + + return decorator + + +_LETTER_NORMALIZATION = { + "alpha": "a", + "beta": "b", + "c": "rc", + "pre": "rc", + "preview": "rc", + "rev": "post", + "r": "post", +} + +__all__ = ["VERSION_PATTERN", "InvalidVersion", "Version", "normalize_pre", "parse"] + + +def __dir__() -> list[str]: + return __all__ + + +LocalType = Tuple[Union[int, str], ...] + +CmpLocalType = Tuple[Tuple[int, str], ...] +CmpSuffix = Tuple[int, int, int, int, int, int] +CmpKey = Union[ + Tuple[int, Tuple[int, ...], CmpSuffix], + Tuple[int, Tuple[int, ...], CmpSuffix, CmpLocalType], +] +VersionComparisonMethod = Callable[[CmpKey, CmpKey], bool] + + +class _VersionReplace(TypedDict, total=False): + epoch: int | None + release: tuple[int, ...] | None + pre: tuple[str, int] | None + post: int | None + dev: int | None + local: str | None + + +def normalize_pre(letter: str, /) -> str: + """Normalize the pre-release segment of a version string. + + Returns a lowercase version of the string if not a known pre-release + identifier. + + >>> normalize_pre('alpha') + 'a' + >>> normalize_pre('BETA') + 'b' + >>> normalize_pre('rc') + 'rc' + + :param letter: + + .. versionadded:: 26.1 + """ + letter = letter.lower() + return _LETTER_NORMALIZATION.get(letter, letter) + + +def parse(version: str) -> Version: + """Parse the given version string. + + This is identical to the :class:`Version` constructor. + + >>> parse('1.0.dev1') + + + :param version: The version string to parse. + :raises InvalidVersion: When the version string is not a valid version. + """ + return Version(version) + + +class InvalidVersion(ValueError): + """Raised when a version string is not a valid version. + + >>> Version("invalid") + Traceback (most recent call last): + ... + packaging.version.InvalidVersion: Invalid version: 'invalid' + """ + + +class _BaseVersion: + __slots__ = () + + # This can also be a normal member (see the packaging_legacy package); + # we are just requiring it to be readable. Actually defining a property + # has runtime effect on subclasses, so it's typing only. + if typing.TYPE_CHECKING: + + @property + def _key(self) -> tuple[Any, ...]: ... + + def __hash__(self) -> int: + return hash(self._key) + + # Please keep the duplicated `isinstance` check + # in the six comparisons hereunder + # unless you find a way to avoid adding overhead function calls. + def __lt__(self, other: _BaseVersion) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key < other._key + + def __le__(self, other: _BaseVersion) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key <= other._key + + def __eq__(self, other: object) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key == other._key + + def __ge__(self, other: _BaseVersion) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key >= other._key + + def __gt__(self, other: _BaseVersion) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key > other._key + + def __ne__(self, other: object) -> bool: + if not isinstance(other, _BaseVersion): + return NotImplemented + + return self._key != other._key + + +# Deliberately not anchored to the start and end of the string, to make it +# easier for 3rd party code to reuse + +# Note that ++ doesn't behave identically on CPython and PyPy, so not using it here +_VERSION_PATTERN = r""" + v?+ # optional leading v + (?a: + (?:(?P[0-9]+)!)?+ # epoch + (?P[0-9]+(?:\.[0-9]+)*+) # release segment + (?P
                                          # pre-release
+            [._-]?+
+            (?Palpha|a|beta|b|preview|pre|c|rc)
+            [._-]?+
+            (?P[0-9]+)?
+        )?+
+        (?P                                         # post release
+            (?:-(?P[0-9]+))
+            |
+            (?:
+                [._-]?
+                (?Ppost|rev|r)
+                [._-]?
+                (?P[0-9]+)?
+            )
+        )?+
+        (?P                                          # dev release
+            [._-]?+
+            (?Pdev)
+            [._-]?+
+            (?P[0-9]+)?
+        )?+
+    )
+    (?a:\+
+        (?P                                        # local version
+            [a-z0-9]+
+            (?:[._-][a-z0-9]+)*+
+        )
+    )?+
+"""
+
+_VERSION_PATTERN_OLD = _VERSION_PATTERN.replace("*+", "*").replace("?+", "?")
+
+# Possessive qualifiers were added in Python 3.11.
+# CPython 3.11.0-3.11.4 had a bug: https://github.com/python/cpython/pull/107795
+# Older PyPy also had a bug.
+VERSION_PATTERN = (
+    _VERSION_PATTERN_OLD
+    if (sys.implementation.name == "cpython" and sys.version_info < (3, 11, 5))
+    or (sys.implementation.name == "pypy" and sys.version_info < (3, 11, 13))
+    or sys.version_info < (3, 11)
+    else _VERSION_PATTERN
+)
+"""
+A string containing the regular expression used to match a valid version.
+
+The pattern is not anchored at either end, and is intended for embedding in larger
+expressions (for example, matching a version number as part of a file name). The
+regular expression should be compiled with the ``re.VERBOSE`` and ``re.IGNORECASE``
+flags set.
+
+.. versionchanged:: 26.0
+
+   The regex now uses possessive qualifiers on Python 3.11 if they are
+   supported (CPython 3.11.5+, PyPy 3.11.13+).
+
+:meta hide-value:
+"""
+
+
+# Validation pattern for local version in replace()
+_LOCAL_PATTERN = re.compile(r"[a-z0-9]+(?:[._-][a-z0-9]+)*", re.IGNORECASE | re.ASCII)
+
+# Fast path: If a version has only digits and dots then we
+# can skip the regex and parse it as a release segment
+_SIMPLE_VERSION_INDICATORS = frozenset(".0123456789")
+
+
+def _validate_epoch(value: object, /) -> int:
+    epoch = value or 0
+    if isinstance(epoch, int) and epoch >= 0:
+        return epoch
+    msg = f"epoch must be non-negative integer, got {epoch}"
+    raise InvalidVersion(msg)
+
+
+def _validate_release(value: object, /) -> tuple[int, ...]:
+    release = (0,) if value is None else value
+    if (
+        isinstance(release, tuple)
+        and len(release) > 0
+        and all(isinstance(i, int) and i >= 0 for i in release)
+    ):
+        return release
+    msg = f"release must be a non-empty tuple of non-negative integers, got {release}"
+    raise InvalidVersion(msg)
+
+
+def _validate_pre(value: object, /) -> tuple[Literal["a", "b", "rc"], int] | None:
+    if value is None:
+        return value
+    if isinstance(value, tuple) and len(value) == 2:
+        letter, number = value
+        letter = normalize_pre(letter)
+        if letter in {"a", "b", "rc"} and isinstance(number, int) and number >= 0:
+            # type checkers can't infer the Literal type here on letter
+            return (letter, number)  # type: ignore[return-value]
+    msg = f"pre must be a tuple of ('a'|'b'|'rc', non-negative int), got {value}"
+    raise InvalidVersion(msg)
+
+
+def _validate_post(value: object, /) -> tuple[Literal["post"], int] | None:
+    if value is None:
+        return value
+    if isinstance(value, int) and value >= 0:
+        return ("post", value)
+    msg = f"post must be non-negative integer, got {value}"
+    raise InvalidVersion(msg)
+
+
+def _validate_dev(value: object, /) -> tuple[Literal["dev"], int] | None:
+    if value is None:
+        return value
+    if isinstance(value, int) and value >= 0:
+        return ("dev", value)
+    msg = f"dev must be non-negative integer, got {value}"
+    raise InvalidVersion(msg)
+
+
+def _validate_local(value: object, /) -> LocalType | None:
+    if value is None:
+        return value
+    if isinstance(value, str) and _LOCAL_PATTERN.fullmatch(value):
+        return _parse_local_version(value)
+    msg = f"local must be a valid version string, got {value!r}"
+    raise InvalidVersion(msg)
+
+
+# Backward compatibility for internals before 26.0. Do not use.
+class _Version(NamedTuple):
+    epoch: int
+    release: tuple[int, ...]
+    dev: tuple[Literal["dev"], int] | None
+    pre: tuple[Literal["a", "b", "rc"], int] | None
+    post: tuple[Literal["post"], int] | None
+    local: LocalType | None
+
+
+class Version(_BaseVersion):
+    """This class abstracts handling of a project's versions.
+
+    A :class:`Version` instance is comparison aware and can be compared and
+    sorted using the standard Python interfaces.
+
+    >>> v1 = Version("1.0a5")
+    >>> v2 = Version("1.0")
+    >>> v1
+    
+    >>> v2
+    
+    >>> v1 < v2
+    True
+    >>> v1 == v2
+    False
+    >>> v1 > v2
+    False
+    >>> v1 >= v2
+    False
+    >>> v1 <= v2
+    True
+
+    :class:`Version` is immutable; use :meth:`__replace__` to change
+    part of a version.
+
+    Instances are safe to serialize with :mod:`pickle`. They use a stable
+    format so the same pickle can be loaded in future packaging releases.
+
+    .. versionchanged:: 26.2
+
+        Added a stable pickle format. Pickles created with packaging 26.2+ can
+        be unpickled with future releases.  Backward compatibility with pickles
+        from packaging < 26.2 is supported but may be removed in a future
+        release.
+    """
+
+    __slots__ = (
+        "_dev",
+        "_epoch",
+        "_hash_cache",
+        "_key_cache",
+        "_local",
+        "_post",
+        "_pre",
+        "_release",
+    )
+    __match_args__ = ("_str",)
+    """
+    Pattern matching is supported on Python 3.10+.
+
+    .. versionadded:: 26.0
+
+    :meta hide-value:
+    """
+
+    _regex = re.compile(r"\s*" + VERSION_PATTERN + r"\s*", re.VERBOSE | re.IGNORECASE)
+
+    _epoch: int
+    _release: tuple[int, ...]
+    _dev: tuple[Literal["dev"], int] | None
+    _pre: tuple[Literal["a", "b", "rc"], int] | None
+    _post: tuple[Literal["post"], int] | None
+    _local: LocalType | None
+
+    _hash_cache: int | None
+    _key_cache: CmpKey | None
+
+    def __init__(self, version: str) -> None:
+        """Initialize a Version object.
+
+        :param version:
+            The string representation of a version which will be parsed and normalized
+            before use.
+        :raises InvalidVersion:
+            If the ``version`` does not conform to PEP 440 in any way then this
+            exception will be raised.
+        """
+        if _SIMPLE_VERSION_INDICATORS.issuperset(version):
+            try:
+                self._release = tuple(map(int, version.split(".")))
+            except ValueError:
+                # Empty parts (from "1..2", ".1", etc.) are invalid versions.
+                # Any other ValueError (e.g. int str-digits limit) should
+                # propagate to the caller.
+                if "" in version.split("."):
+                    raise InvalidVersion(f"Invalid version: {version!r}") from None
+                # TODO: remove "no cover" when Python 3.9 is dropped.
+                raise  # pragma: no cover
+
+            self._epoch = 0
+            self._pre = None
+            self._post = None
+            self._dev = None
+            self._local = None
+            self._key_cache = None
+            self._hash_cache = None
+            return
+
+        # Validate the version and parse it into pieces
+        match = self._regex.fullmatch(version)
+        if not match:
+            raise InvalidVersion(f"Invalid version: {version!r}")
+        self._epoch = int(match.group("epoch")) if match.group("epoch") else 0
+        self._release = tuple(map(int, match.group("release").split(".")))
+        # We can type ignore the assignments below because the regex guarantees
+        # the correct strings
+        self._pre = _parse_letter_version(match.group("pre_l"), match.group("pre_n"))  # type: ignore[assignment]
+        self._post = _parse_letter_version(  # type: ignore[assignment]
+            match.group("post_l"), match.group("post_n1") or match.group("post_n2")
+        )
+        self._dev = _parse_letter_version(match.group("dev_l"), match.group("dev_n"))  # type: ignore[assignment]
+        self._local = _parse_local_version(match.group("local"))
+
+        # Key which will be used for sorting
+        self._key_cache = None
+        self._hash_cache = None
+
+    @classmethod
+    def from_parts(
+        cls,
+        *,
+        epoch: int = 0,
+        release: tuple[int, ...],
+        pre: tuple[str, int] | None = None,
+        post: int | None = None,
+        dev: int | None = None,
+        local: str | None = None,
+    ) -> Self:
+        """
+        Return a new version composed of the various parts.
+
+        This allows you to build a version without going though a string and
+        running a regular expression. It normalizes pre-release strings. The
+        ``release=`` keyword argument is required.
+
+        >>> Version.from_parts(release=(1,2,3))
+        
+        >>> Version.from_parts(release=(0,1,0), pre=("b", 1))
+        
+
+        :param epoch:
+        :param release: This version tuple is required
+
+        .. versionadded:: 26.1
+        """
+        _epoch = _validate_epoch(epoch)
+        _release = _validate_release(release)
+        _pre = _validate_pre(pre) if pre is not None else None
+        _post = _validate_post(post) if post is not None else None
+        _dev = _validate_dev(dev) if dev is not None else None
+        _local = _validate_local(local) if local is not None else None
+
+        new_version = cls.__new__(cls)
+        new_version._key_cache = None
+        new_version._hash_cache = None
+        new_version._epoch = _epoch
+        new_version._release = _release
+        new_version._pre = _pre
+        new_version._post = _post
+        new_version._dev = _dev
+        new_version._local = _local
+
+        return new_version
+
+    def __replace__(self, **kwargs: Unpack[_VersionReplace]) -> Self:
+        """
+        __replace__(*, epoch=..., release=..., pre=..., post=..., dev=..., local=...)
+
+        Return a new version with parts replaced.
+
+        This returns a new version (unless no parts were changed). The
+        pre-release is normalized. Setting a value to ``None`` clears it.
+
+        >>> v = Version("1.2.3")
+        >>> v.__replace__(pre=("a", 1))
+        
+
+        :param int | None epoch:
+        :param tuple[int, ...] | None release:
+        :param tuple[str, int] | None pre:
+        :param int | None post:
+        :param int | None dev:
+        :param str | None local:
+
+        .. versionadded:: 26.0
+        .. versionchanged:: 26.1
+
+           The pre-release portion is now normalized.
+        """
+        epoch = _validate_epoch(kwargs["epoch"]) if "epoch" in kwargs else self._epoch
+        release = (
+            _validate_release(kwargs["release"])
+            if "release" in kwargs
+            else self._release
+        )
+        pre = _validate_pre(kwargs["pre"]) if "pre" in kwargs else self._pre
+        post = _validate_post(kwargs["post"]) if "post" in kwargs else self._post
+        dev = _validate_dev(kwargs["dev"]) if "dev" in kwargs else self._dev
+        local = _validate_local(kwargs["local"]) if "local" in kwargs else self._local
+
+        if (
+            epoch == self._epoch
+            and release == self._release
+            and pre == self._pre
+            and post == self._post
+            and dev == self._dev
+            and local == self._local
+        ):
+            return self
+
+        new_version = self.__class__.__new__(self.__class__)
+        new_version._key_cache = None
+        new_version._hash_cache = None
+        new_version._epoch = epoch
+        new_version._release = release
+        new_version._pre = pre
+        new_version._post = post
+        new_version._dev = dev
+        new_version._local = local
+
+        return new_version
+
+    @property
+    def _key(self) -> CmpKey:
+        if self._key_cache is None:
+            self._key_cache = _cmpkey(
+                self._epoch,
+                self._release,
+                self._pre,
+                self._post,
+                self._dev,
+                self._local,
+            )
+        return self._key_cache
+
+    # __hash__ must be defined when __eq__ is overridden,
+    # otherwise Python sets __hash__ to None.
+    def __hash__(self) -> int:
+        if (cached_hash := self._hash_cache) is not None:
+            return cached_hash
+
+        if (key := self._key_cache) is None:
+            self._key_cache = key = _cmpkey(
+                self._epoch,
+                self._release,
+                self._pre,
+                self._post,
+                self._dev,
+                self._local,
+            )
+        self._hash_cache = cached_hash = hash(key)
+        return cached_hash
+
+    # Override comparison methods to use direct _key_cache access
+    # This is faster than property access, especially before Python 3.12
+    def __lt__(self, other: _BaseVersion) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache < other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__lt__(other)
+
+    def __le__(self, other: _BaseVersion) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache <= other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__le__(other)
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache == other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__eq__(other)
+
+    def __ge__(self, other: _BaseVersion) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache >= other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__ge__(other)
+
+    def __gt__(self, other: _BaseVersion) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache > other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__gt__(other)
+
+    def __ne__(self, other: object) -> bool:
+        if isinstance(other, Version):
+            if self._key_cache is None:
+                self._key_cache = _cmpkey(
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                )
+            if other._key_cache is None:
+                other._key_cache = _cmpkey(
+                    other._epoch,
+                    other._release,
+                    other._pre,
+                    other._post,
+                    other._dev,
+                    other._local,
+                )
+            return self._key_cache != other._key_cache
+
+        if not isinstance(other, _BaseVersion):
+            return NotImplemented
+
+        return super().__ne__(other)
+
+    def __getstate__(
+        self,
+    ) -> tuple[
+        int,
+        tuple[int, ...],
+        tuple[str, int] | None,
+        tuple[str, int] | None,
+        tuple[str, int] | None,
+        LocalType | None,
+    ]:
+        # Return state as a 6-item tuple for compactness:
+        #   (epoch, release, pre, post, dev, local)
+        # Cache members are excluded and will be recomputed on demand
+        return (
+            self._epoch,
+            self._release,
+            self._pre,
+            self._post,
+            self._dev,
+            self._local,
+        )
+
+    def __setstate__(self, state: object) -> None:
+        # Always discard cached values — they may contain stale references
+        # (e.g. packaging._structures.InfinityType from pre-26.1 pickles)
+        # and will be recomputed on demand from the core fields above.
+        self._key_cache = None
+        self._hash_cache = None
+
+        if isinstance(state, tuple):
+            if len(state) == 6:
+                # New format (26.2+): (epoch, release, pre, post, dev, local)
+                (
+                    self._epoch,
+                    self._release,
+                    self._pre,
+                    self._post,
+                    self._dev,
+                    self._local,
+                ) = state
+                return
+            if len(state) == 2:
+                # Format (packaging 26.0-26.1): (None, {slot: value}).
+                _, slot_dict = state
+                if isinstance(slot_dict, dict):
+                    self._epoch = slot_dict["_epoch"]
+                    self._release = slot_dict["_release"]
+                    self._pre = slot_dict.get("_pre")
+                    self._post = slot_dict.get("_post")
+                    self._dev = slot_dict.get("_dev")
+                    self._local = slot_dict.get("_local")
+                    return
+        if isinstance(state, dict):
+            # Old format (packaging <= 25.x, no __slots__): state is a plain
+            # dict with "_version" (_Version NamedTuple) and "_key" entries.
+            version_nt = state.get("_version")
+            if version_nt is not None:
+                self._epoch = version_nt.epoch
+                self._release = version_nt.release
+                self._pre = version_nt.pre
+                self._post = version_nt.post
+                self._dev = version_nt.dev
+                self._local = version_nt.local
+                return
+
+        raise TypeError(f"Cannot restore Version from {state!r}")
+
+    @property
+    @_deprecated("Version._version is private and will be removed soon")
+    def _version(self) -> _Version:
+        return _Version(
+            self._epoch, self._release, self._dev, self._pre, self._post, self._local
+        )
+
+    @_version.setter
+    @_deprecated("Version._version is private and will be removed soon")
+    def _version(self, value: _Version) -> None:
+        self._epoch = value.epoch
+        self._release = value.release
+        self._dev = value.dev
+        self._pre = value.pre
+        self._post = value.post
+        self._local = value.local
+        self._key_cache = None
+        self._hash_cache = None
+
+    def __repr__(self) -> str:
+        """A representation of the Version that shows all internal state.
+
+        >>> Version('1.0.0')
+        
+        """
+        return f"<{self.__class__.__name__}({str(self)!r})>"
+
+    def __str__(self) -> str:
+        """A string representation of the version that can be round-tripped.
+
+        >>> str(Version("1.0a5"))
+        '1.0a5'
+        """
+        # This is a hot function, so not calling self.base_version
+        version = ".".join(map(str, self.release))
+
+        # Epoch
+        if self.epoch:
+            version = f"{self.epoch}!{version}"
+
+        # Pre-release
+        if self.pre is not None:
+            version += "".join(map(str, self.pre))
+
+        # Post-release
+        if self.post is not None:
+            version += f".post{self.post}"
+
+        # Development release
+        if self.dev is not None:
+            version += f".dev{self.dev}"
+
+        # Local version segment
+        if self.local is not None:
+            version += f"+{self.local}"
+
+        return version
+
+    @property
+    def _str(self) -> str:
+        """Internal property for match_args"""
+        return str(self)
+
+    @property
+    def epoch(self) -> int:
+        """The epoch of the version.
+
+        >>> Version("2.0.0").epoch
+        0
+        >>> Version("1!2.0.0").epoch
+        1
+        """
+        return self._epoch
+
+    @property
+    def release(self) -> tuple[int, ...]:
+        """The components of the "release" segment of the version.
+
+        >>> Version("1.2.3").release
+        (1, 2, 3)
+        >>> Version("2.0.0").release
+        (2, 0, 0)
+        >>> Version("1!2.0.0.post0").release
+        (2, 0, 0)
+
+        Includes trailing zeroes but not the epoch or any pre-release / development /
+        post-release suffixes.
+        """
+        return self._release
+
+    @property
+    def pre(self) -> tuple[Literal["a", "b", "rc"], int] | None:
+        """The pre-release segment of the version.
+
+        >>> print(Version("1.2.3").pre)
+        None
+        >>> Version("1.2.3a1").pre
+        ('a', 1)
+        >>> Version("1.2.3b1").pre
+        ('b', 1)
+        >>> Version("1.2.3rc1").pre
+        ('rc', 1)
+        """
+        return self._pre
+
+    @property
+    def post(self) -> int | None:
+        """The post-release number of the version.
+
+        >>> print(Version("1.2.3").post)
+        None
+        >>> Version("1.2.3.post1").post
+        1
+        """
+        return self._post[1] if self._post else None
+
+    @property
+    def dev(self) -> int | None:
+        """The development number of the version.
+
+        >>> print(Version("1.2.3").dev)
+        None
+        >>> Version("1.2.3.dev1").dev
+        1
+        """
+        return self._dev[1] if self._dev else None
+
+    @property
+    def local(self) -> str | None:
+        """The local version segment of the version.
+
+        >>> print(Version("1.2.3").local)
+        None
+        >>> Version("1.2.3+abc").local
+        'abc'
+        """
+        if self._local:
+            return ".".join(str(x) for x in self._local)
+        else:
+            return None
+
+    @property
+    def public(self) -> str:
+        """The public portion of the version.
+
+        This returns a string. If you want a :class:`Version` again and care
+        about performance, use ``v.__replace__(local=None)`` instead.
+
+        >>> Version("1.2.3").public
+        '1.2.3'
+        >>> Version("1.2.3+abc").public
+        '1.2.3'
+        >>> Version("1!1.2.3dev1+abc").public
+        '1!1.2.3.dev1'
+        """
+        return str(self).split("+", 1)[0]
+
+    @property
+    def base_version(self) -> str:
+        """The "base version" of the version.
+
+        This returns a string. If you want a :class:`Version` again and care
+        about performance, use
+        ``v.__replace__(pre=None, post=None, dev=None, local=None)`` instead.
+
+        >>> Version("1.2.3").base_version
+        '1.2.3'
+        >>> Version("1.2.3+abc").base_version
+        '1.2.3'
+        >>> Version("1!1.2.3dev1+abc").base_version
+        '1!1.2.3'
+
+        The "base version" is the public version of the project without any pre or post
+        release markers.
+        """
+        release_segment = ".".join(map(str, self.release))
+        return f"{self.epoch}!{release_segment}" if self.epoch else release_segment
+
+    @property
+    def is_prerelease(self) -> bool:
+        """Whether this version is a pre-release.
+
+        >>> Version("1.2.3").is_prerelease
+        False
+        >>> Version("1.2.3a1").is_prerelease
+        True
+        >>> Version("1.2.3b1").is_prerelease
+        True
+        >>> Version("1.2.3rc1").is_prerelease
+        True
+        >>> Version("1.2.3dev1").is_prerelease
+        True
+        """
+        return self.dev is not None or self.pre is not None
+
+    @property
+    def is_postrelease(self) -> bool:
+        """Whether this version is a post-release.
+
+        >>> Version("1.2.3").is_postrelease
+        False
+        >>> Version("1.2.3.post1").is_postrelease
+        True
+        """
+        return self.post is not None
+
+    @property
+    def is_devrelease(self) -> bool:
+        """Whether this version is a development release.
+
+        >>> Version("1.2.3").is_devrelease
+        False
+        >>> Version("1.2.3.dev1").is_devrelease
+        True
+        """
+        return self.dev is not None
+
+    @property
+    def major(self) -> int:
+        """The first item of :attr:`release` or ``0`` if unavailable.
+
+        >>> Version("1.2.3").major
+        1
+        """
+        return self.release[0] if len(self.release) >= 1 else 0
+
+    @property
+    def minor(self) -> int:
+        """The second item of :attr:`release` or ``0`` if unavailable.
+
+        >>> Version("1.2.3").minor
+        2
+        >>> Version("1").minor
+        0
+        """
+        return self.release[1] if len(self.release) >= 2 else 0
+
+    @property
+    def micro(self) -> int:
+        """The third item of :attr:`release` or ``0`` if unavailable.
+
+        >>> Version("1.2.3").micro
+        3
+        >>> Version("1").micro
+        0
+        """
+        return self.release[2] if len(self.release) >= 3 else 0
+
+
+class _TrimmedRelease(Version):
+    __slots__ = ()
+
+    def __init__(self, version: str | Version) -> None:
+        if isinstance(version, Version):
+            self._epoch = version._epoch
+            self._release = version._release
+            self._dev = version._dev
+            self._pre = version._pre
+            self._post = version._post
+            self._local = version._local
+            self._key_cache = version._key_cache
+            return
+        super().__init__(version)  # pragma: no cover
+
+    @property
+    def release(self) -> tuple[int, ...]:
+        """
+        Release segment without any trailing zeros.
+
+        >>> _TrimmedRelease('1.0.0').release
+        (1,)
+        >>> _TrimmedRelease('0.0').release
+        (0,)
+        """
+        # This leaves one 0.
+        rel = super().release
+        len_release = len(rel)
+        i = len_release
+        while i > 1 and rel[i - 1] == 0:
+            i -= 1
+        return rel if i == len_release else rel[:i]
+
+
+def _parse_letter_version(
+    letter: str | None, number: str | bytes | SupportsInt | None
+) -> tuple[str, int] | None:
+    if letter:
+        # We normalize any letters to their lower case form
+        letter = letter.lower()
+
+        # We consider some words to be alternate spellings of other words and
+        # in those cases we want to normalize the spellings to our preferred
+        # spelling.
+        letter = _LETTER_NORMALIZATION.get(letter, letter)
+
+        # We consider there to be an implicit 0 in a pre-release if there is
+        # not a numeral associated with it.
+        return letter, int(number or 0)
+
+    if number:
+        # We assume if we are given a number, but we are not given a letter
+        # then this is using the implicit post release syntax (e.g. 1.0-1)
+        return "post", int(number)
+
+    return None
+
+
+_local_version_separators = re.compile(r"[\._-]")
+
+
+def _parse_local_version(local: str | None) -> LocalType | None:
+    """
+    Takes a string like ``"abc.1.twelve"`` and turns it into
+    ``("abc", 1, "twelve")``.
+    """
+    if local is not None:
+        return tuple(
+            part.lower() if not part.isdigit() else int(part)
+            for part in _local_version_separators.split(local)
+        )
+    return None
+
+
+# Sort ranks for pre-release: dev-only < a < b < rc < stable (no pre-release).
+_PRE_RANK = {"a": 0, "b": 1, "rc": 2}
+_PRE_RANK_DEV_ONLY = -1  # sorts before a(0)
+_PRE_RANK_STABLE = 3  # sorts after rc(2)
+
+# In local version segments, strings sort before ints per PEP 440.
+_LOCAL_STR_RANK = -1  # sorts before all non-negative ints
+
+# Pre-computed suffix for stable releases (no pre, post, or dev segments).
+# See _cmpkey() for the suffix layout.
+_STABLE_SUFFIX = (_PRE_RANK_STABLE, 0, 0, 0, 1, 0)
+
+
+def _cmpkey(
+    epoch: int,
+    release: tuple[int, ...],
+    pre: tuple[str, int] | None,
+    post: tuple[str, int] | None,
+    dev: tuple[str, int] | None,
+    local: LocalType | None,
+) -> CmpKey:
+    """Build a comparison key for PEP 440 ordering.
+
+    Returns ``(epoch, release, suffix)`` or
+    ``(epoch, release, suffix, local)`` so that plain tuple
+    comparison gives the correct order.
+
+    Trailing zeros are stripped from the release so that ``1.0.0 == 1``.
+
+    The suffix is a flat 6-int tuple that encodes pre/post/dev:
+    ``(pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)``
+
+    pre_rank: dev-only=-1, a=0, b=1, rc=2, no-pre=3
+        Dev-only releases (no pre or post) get -1 so they sort before
+        any alpha/beta/rc.  Releases without a pre-release tag get 3
+        so they sort after rc.
+    post_rank: no-post=0, post=1
+        Releases without a post segment sort before those with one.
+    dev_rank: dev=0, no-dev=1
+        Releases without a dev segment sort after those with one.
+
+    Local segments use ``(n, "")`` for ints and ``(-1, s)`` for strings,
+    following PEP 440: strings sort before ints, strings compare
+    lexicographically, ints compare numerically, and shorter segments
+    sort before longer when prefixes match.  Versions without a local
+    segment sort before those with one (3-tuple < 4-tuple).
+
+    >>> _cmpkey(0, (1, 0, 0), None, None, None, None)
+    (0, (1,), (3, 0, 0, 0, 1, 0))
+    >>> _cmpkey(0, (1,), ("a", 1), None, None, None)
+    (0, (1,), (0, 1, 0, 0, 1, 0))
+    >>> _cmpkey(0, (1,), None, None, None, ("ubuntu", 1))
+    (0, (1,), (3, 0, 0, 0, 1, 0), ((-1, 'ubuntu'), (1, '')))
+    """
+    # Strip trailing zeros: 1.0.0 compares equal to 1.
+    len_release = len(release)
+    i = len_release
+    while i and release[i - 1] == 0:
+        i -= 1
+    trimmed = release if i == len_release else release[:i]
+
+    # Fast path: stable release with no local segment.
+    if pre is None and post is None and dev is None and local is None:
+        return epoch, trimmed, _STABLE_SUFFIX
+
+    if pre is None and post is None and dev is not None:
+        # dev-only (e.g. 1.0.dev1) sorts before all pre-releases.
+        pre_rank, pre_n = _PRE_RANK_DEV_ONLY, 0
+    elif pre is None:
+        pre_rank, pre_n = _PRE_RANK_STABLE, 0
+    else:
+        pre_rank, pre_n = _PRE_RANK[pre[0]], pre[1]
+
+    post_rank = 0 if post is None else 1
+    post_n = 0 if post is None else post[1]
+
+    dev_rank = 1 if dev is None else 0
+    dev_n = 0 if dev is None else dev[1]
+
+    suffix = (pre_rank, pre_n, post_rank, post_n, dev_rank, dev_n)
+
+    if local is None:
+        return epoch, trimmed, suffix
+
+    cmp_local: CmpLocalType = tuple(
+        (seg, "") if isinstance(seg, int) else (_LOCAL_STR_RANK, seg) for seg in local
+    )
+    return epoch, trimmed, suffix, cmp_local
diff --git a/.venv/lib/python3.13/site-packages/pandas/__init__.py b/.venv/lib/python3.13/site-packages/pandas/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..ca2eba20432924304517be99d5113bc9f57614d2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/__init__.py
@@ -0,0 +1,367 @@
+from __future__ import annotations
+
+import os
+import warnings
+
+__docformat__ = "restructuredtext"
+
+# Let users know if they're missing any of our hard dependencies
+_hard_dependencies = ("numpy", "pytz", "dateutil")
+_missing_dependencies = []
+
+for _dependency in _hard_dependencies:
+    try:
+        __import__(_dependency)
+    except ImportError as _e:  # pragma: no cover
+        _missing_dependencies.append(f"{_dependency}: {_e}")
+
+if _missing_dependencies:  # pragma: no cover
+    raise ImportError(
+        "Unable to import required dependencies:\n" + "\n".join(_missing_dependencies)
+    )
+del _hard_dependencies, _dependency, _missing_dependencies
+
+try:
+    # numpy compat
+    from pandas.compat import (
+        is_numpy_dev as _is_numpy_dev,  # pyright: ignore[reportUnusedImport] # noqa: F401
+    )
+except ImportError as _err:  # pragma: no cover
+    _module = _err.name
+    raise ImportError(
+        f"C extension: {_module} not built. If you want to import "
+        "pandas from the source directory, you may need to run "
+        "'python setup.py build_ext' to build the C extensions first."
+    ) from _err
+
+from pandas._config import (
+    get_option,
+    set_option,
+    reset_option,
+    describe_option,
+    option_context,
+    options,
+)
+
+# let init-time option registration happen
+import pandas.core.config_init  # pyright: ignore[reportUnusedImport] # noqa: F401
+
+from pandas.core.api import (
+    # dtype
+    ArrowDtype,
+    Int8Dtype,
+    Int16Dtype,
+    Int32Dtype,
+    Int64Dtype,
+    UInt8Dtype,
+    UInt16Dtype,
+    UInt32Dtype,
+    UInt64Dtype,
+    Float32Dtype,
+    Float64Dtype,
+    CategoricalDtype,
+    PeriodDtype,
+    IntervalDtype,
+    DatetimeTZDtype,
+    StringDtype,
+    BooleanDtype,
+    # missing
+    NA,
+    isna,
+    isnull,
+    notna,
+    notnull,
+    # indexes
+    Index,
+    CategoricalIndex,
+    RangeIndex,
+    MultiIndex,
+    IntervalIndex,
+    TimedeltaIndex,
+    DatetimeIndex,
+    PeriodIndex,
+    IndexSlice,
+    # tseries
+    NaT,
+    Period,
+    period_range,
+    Timedelta,
+    timedelta_range,
+    Timestamp,
+    date_range,
+    bdate_range,
+    Interval,
+    interval_range,
+    DateOffset,
+    # conversion
+    to_numeric,
+    to_datetime,
+    to_timedelta,
+    # misc
+    Flags,
+    Grouper,
+    factorize,
+    unique,
+    value_counts,
+    NamedAgg,
+    array,
+    Categorical,
+    set_eng_float_format,
+    Series,
+    DataFrame,
+)
+
+from pandas.core.dtypes.dtypes import SparseDtype
+
+from pandas.tseries.api import infer_freq
+from pandas.tseries import offsets
+
+from pandas.core.computation.api import eval
+
+from pandas.core.reshape.api import (
+    concat,
+    lreshape,
+    melt,
+    wide_to_long,
+    merge,
+    merge_asof,
+    merge_ordered,
+    crosstab,
+    pivot,
+    pivot_table,
+    get_dummies,
+    from_dummies,
+    cut,
+    qcut,
+)
+
+from pandas import api, arrays, errors, io, plotting, tseries
+from pandas import testing
+from pandas.util._print_versions import show_versions
+
+from pandas.io.api import (
+    # excel
+    ExcelFile,
+    ExcelWriter,
+    read_excel,
+    # parsers
+    read_csv,
+    read_fwf,
+    read_table,
+    # pickle
+    read_pickle,
+    to_pickle,
+    # pytables
+    HDFStore,
+    read_hdf,
+    # sql
+    read_sql,
+    read_sql_query,
+    read_sql_table,
+    # misc
+    read_clipboard,
+    read_parquet,
+    read_orc,
+    read_feather,
+    read_gbq,
+    read_html,
+    read_xml,
+    read_json,
+    read_stata,
+    read_sas,
+    read_spss,
+)
+
+from pandas.io.json._normalize import json_normalize
+
+from pandas.util._tester import test
+
+# use the closest tagged version if possible
+_built_with_meson = False
+try:
+    from pandas._version_meson import (  # pyright: ignore [reportMissingImports]
+        __version__,
+        __git_version__,
+    )
+
+    _built_with_meson = True
+except ImportError:
+    from pandas._version import get_versions
+
+    v = get_versions()
+    __version__ = v.get("closest-tag", v["version"])
+    __git_version__ = v.get("full-revisionid")
+    del get_versions, v
+
+# GH#55043 - deprecation of the data_manager option
+if "PANDAS_DATA_MANAGER" in os.environ:
+    warnings.warn(
+        "The env variable PANDAS_DATA_MANAGER is set. The data_manager option is "
+        "deprecated and will be removed in a future version. Only the BlockManager "
+        "will be available. Unset this environment variable to silence this warning.",
+        FutureWarning,
+        stacklevel=2,
+    )
+
+del warnings, os
+
+# module level doc-string
+__doc__ = """
+pandas - a powerful data analysis and manipulation library for Python
+=====================================================================
+
+**pandas** is a Python package providing fast, flexible, and expressive data
+structures designed to make working with "relational" or "labeled" data both
+easy and intuitive. It aims to be the fundamental high-level building block for
+doing practical, **real world** data analysis in Python. Additionally, it has
+the broader goal of becoming **the most powerful and flexible open source data
+analysis / manipulation tool available in any language**. It is already well on
+its way toward this goal.
+
+Main Features
+-------------
+Here are just a few of the things that pandas does well:
+
+  - Easy handling of missing data in floating point as well as non-floating
+    point data.
+  - Size mutability: columns can be inserted and deleted from DataFrame and
+    higher dimensional objects
+  - Automatic and explicit data alignment: objects can be explicitly aligned
+    to a set of labels, or the user can simply ignore the labels and let
+    `Series`, `DataFrame`, etc. automatically align the data for you in
+    computations.
+  - Powerful, flexible group by functionality to perform split-apply-combine
+    operations on data sets, for both aggregating and transforming data.
+  - Make it easy to convert ragged, differently-indexed data in other Python
+    and NumPy data structures into DataFrame objects.
+  - Intelligent label-based slicing, fancy indexing, and subsetting of large
+    data sets.
+  - Intuitive merging and joining data sets.
+  - Flexible reshaping and pivoting of data sets.
+  - Hierarchical labeling of axes (possible to have multiple labels per tick).
+  - Robust IO tools for loading data from flat files (CSV and delimited),
+    Excel files, databases, and saving/loading data from the ultrafast HDF5
+    format.
+  - Time series-specific functionality: date range generation and frequency
+    conversion, moving window statistics, date shifting and lagging.
+"""
+
+# Use __all__ to let type checkers know what is part of the public API.
+# Pandas is not (yet) a py.typed library: the public API is determined
+# based on the documentation.
+__all__ = [
+    "ArrowDtype",
+    "BooleanDtype",
+    "Categorical",
+    "CategoricalDtype",
+    "CategoricalIndex",
+    "DataFrame",
+    "DateOffset",
+    "DatetimeIndex",
+    "DatetimeTZDtype",
+    "ExcelFile",
+    "ExcelWriter",
+    "Flags",
+    "Float32Dtype",
+    "Float64Dtype",
+    "Grouper",
+    "HDFStore",
+    "Index",
+    "IndexSlice",
+    "Int16Dtype",
+    "Int32Dtype",
+    "Int64Dtype",
+    "Int8Dtype",
+    "Interval",
+    "IntervalDtype",
+    "IntervalIndex",
+    "MultiIndex",
+    "NA",
+    "NaT",
+    "NamedAgg",
+    "Period",
+    "PeriodDtype",
+    "PeriodIndex",
+    "RangeIndex",
+    "Series",
+    "SparseDtype",
+    "StringDtype",
+    "Timedelta",
+    "TimedeltaIndex",
+    "Timestamp",
+    "UInt16Dtype",
+    "UInt32Dtype",
+    "UInt64Dtype",
+    "UInt8Dtype",
+    "api",
+    "array",
+    "arrays",
+    "bdate_range",
+    "concat",
+    "crosstab",
+    "cut",
+    "date_range",
+    "describe_option",
+    "errors",
+    "eval",
+    "factorize",
+    "get_dummies",
+    "from_dummies",
+    "get_option",
+    "infer_freq",
+    "interval_range",
+    "io",
+    "isna",
+    "isnull",
+    "json_normalize",
+    "lreshape",
+    "melt",
+    "merge",
+    "merge_asof",
+    "merge_ordered",
+    "notna",
+    "notnull",
+    "offsets",
+    "option_context",
+    "options",
+    "period_range",
+    "pivot",
+    "pivot_table",
+    "plotting",
+    "qcut",
+    "read_clipboard",
+    "read_csv",
+    "read_excel",
+    "read_feather",
+    "read_fwf",
+    "read_gbq",
+    "read_hdf",
+    "read_html",
+    "read_json",
+    "read_orc",
+    "read_parquet",
+    "read_pickle",
+    "read_sas",
+    "read_spss",
+    "read_sql",
+    "read_sql_query",
+    "read_sql_table",
+    "read_stata",
+    "read_table",
+    "read_xml",
+    "reset_option",
+    "set_eng_float_format",
+    "set_option",
+    "show_versions",
+    "test",
+    "testing",
+    "timedelta_range",
+    "to_datetime",
+    "to_numeric",
+    "to_pickle",
+    "to_timedelta",
+    "tseries",
+    "unique",
+    "value_counts",
+    "wide_to_long",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_config/__init__.py b/.venv/lib/python3.13/site-packages/pandas/_config/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..838b6affd283633c2269cb91db4bf9eaebda318e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_config/__init__.py
@@ -0,0 +1,57 @@
+"""
+pandas._config is considered explicitly upstream of everything else in pandas,
+should have no intra-pandas dependencies.
+
+importing `dates` and `display` ensures that keys needed by _libs
+are initialized.
+"""
+__all__ = [
+    "config",
+    "detect_console_encoding",
+    "get_option",
+    "set_option",
+    "reset_option",
+    "describe_option",
+    "option_context",
+    "options",
+    "using_copy_on_write",
+    "warn_copy_on_write",
+]
+from pandas._config import config
+from pandas._config import dates  # pyright: ignore[reportUnusedImport]  # noqa: F401
+from pandas._config.config import (
+    _global_config,
+    describe_option,
+    get_option,
+    option_context,
+    options,
+    reset_option,
+    set_option,
+)
+from pandas._config.display import detect_console_encoding
+
+
+def using_copy_on_write() -> bool:
+    _mode_options = _global_config["mode"]
+    return (
+        _mode_options["copy_on_write"] is True
+        and _mode_options["data_manager"] == "block"
+    )
+
+
+def warn_copy_on_write() -> bool:
+    _mode_options = _global_config["mode"]
+    return (
+        _mode_options["copy_on_write"] == "warn"
+        and _mode_options["data_manager"] == "block"
+    )
+
+
+def using_nullable_dtypes() -> bool:
+    _mode_options = _global_config["mode"]
+    return _mode_options["nullable_dtypes"]
+
+
+def using_string_dtype() -> bool:
+    _mode_options = _global_config["future"]
+    return _mode_options["infer_string"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_config/config.py b/.venv/lib/python3.13/site-packages/pandas/_config/config.py
new file mode 100644
index 0000000000000000000000000000000000000000..c391939d22491099652e13ad81e83b201f140b60
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_config/config.py
@@ -0,0 +1,948 @@
+"""
+The config module holds package-wide configurables and provides
+a uniform API for working with them.
+
+Overview
+========
+
+This module supports the following requirements:
+- options are referenced using keys in dot.notation, e.g. "x.y.option - z".
+- keys are case-insensitive.
+- functions should accept partial/regex keys, when unambiguous.
+- options can be registered by modules at import time.
+- options can be registered at init-time (via core.config_init)
+- options have a default value, and (optionally) a description and
+  validation function associated with them.
+- options can be deprecated, in which case referencing them
+  should produce a warning.
+- deprecated options can optionally be rerouted to a replacement
+  so that accessing a deprecated option reroutes to a differently
+  named option.
+- options can be reset to their default value.
+- all option can be reset to their default value at once.
+- all options in a certain sub - namespace can be reset at once.
+- the user can set / get / reset or ask for the description of an option.
+- a developer can register and mark an option as deprecated.
+- you can register a callback to be invoked when the option value
+  is set or reset. Changing the stored value is considered misuse, but
+  is not verboten.
+
+Implementation
+==============
+
+- Data is stored using nested dictionaries, and should be accessed
+  through the provided API.
+
+- "Registered options" and "Deprecated options" have metadata associated
+  with them, which are stored in auxiliary dictionaries keyed on the
+  fully-qualified key, e.g. "x.y.z.option".
+
+- the config_init module is imported by the package's __init__.py file.
+  placing any register_option() calls there will ensure those options
+  are available as soon as pandas is loaded. If you use register_option
+  in a module, it will only be available after that module is imported,
+  which you should be aware of.
+
+- `config_prefix` is a context_manager (for use with the `with` keyword)
+  which can save developers some typing, see the docstring.
+
+"""
+
+from __future__ import annotations
+
+from contextlib import (
+    ContextDecorator,
+    contextmanager,
+)
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    NamedTuple,
+    cast,
+)
+import warnings
+
+from pandas._typing import (
+    F,
+    T,
+)
+from pandas.util._exceptions import find_stack_level
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Iterable,
+    )
+
+
+class DeprecatedOption(NamedTuple):
+    key: str
+    msg: str | None
+    rkey: str | None
+    removal_ver: str | None
+
+
+class RegisteredOption(NamedTuple):
+    key: str
+    defval: object
+    doc: str
+    validator: Callable[[object], Any] | None
+    cb: Callable[[str], Any] | None
+
+
+# holds deprecated option metadata
+_deprecated_options: dict[str, DeprecatedOption] = {}
+
+# holds registered option metadata
+_registered_options: dict[str, RegisteredOption] = {}
+
+# holds the current values for registered options
+_global_config: dict[str, Any] = {}
+
+# keys which have a special meaning
+_reserved_keys: list[str] = ["all"]
+
+
+class OptionError(AttributeError, KeyError):
+    """
+    Exception raised for pandas.options.
+
+    Backwards compatible with KeyError checks.
+
+    Examples
+    --------
+    >>> pd.options.context
+    Traceback (most recent call last):
+    OptionError: No such option
+    """
+
+
+#
+# User API
+
+
+def _get_single_key(pat: str, silent: bool) -> str:
+    keys = _select_options(pat)
+    if len(keys) == 0:
+        if not silent:
+            _warn_if_deprecated(pat)
+        raise OptionError(f"No such keys(s): {repr(pat)}")
+    if len(keys) > 1:
+        raise OptionError("Pattern matched multiple keys")
+    key = keys[0]
+
+    if not silent:
+        _warn_if_deprecated(key)
+
+    key = _translate_key(key)
+
+    return key
+
+
+def _get_option(pat: str, silent: bool = False) -> Any:
+    key = _get_single_key(pat, silent)
+
+    # walk the nested dict
+    root, k = _get_root(key)
+    return root[k]
+
+
+def _set_option(*args, **kwargs) -> None:
+    # must at least 1 arg deal with constraints later
+    nargs = len(args)
+    if not nargs or nargs % 2 != 0:
+        raise ValueError("Must provide an even number of non-keyword arguments")
+
+    # default to false
+    silent = kwargs.pop("silent", False)
+
+    if kwargs:
+        kwarg = next(iter(kwargs.keys()))
+        raise TypeError(f'_set_option() got an unexpected keyword argument "{kwarg}"')
+
+    for k, v in zip(args[::2], args[1::2]):
+        key = _get_single_key(k, silent)
+
+        o = _get_registered_option(key)
+        if o and o.validator:
+            o.validator(v)
+
+        # walk the nested dict
+        root, k_root = _get_root(key)
+        root[k_root] = v
+
+        if o.cb:
+            if silent:
+                with warnings.catch_warnings(record=True):
+                    o.cb(key)
+            else:
+                o.cb(key)
+
+
+def _describe_option(pat: str = "", _print_desc: bool = True) -> str | None:
+    keys = _select_options(pat)
+    if len(keys) == 0:
+        raise OptionError("No such keys(s)")
+
+    s = "\n".join([_build_option_description(k) for k in keys])
+
+    if _print_desc:
+        print(s)
+        return None
+    return s
+
+
+def _reset_option(pat: str, silent: bool = False) -> None:
+    keys = _select_options(pat)
+
+    if len(keys) == 0:
+        raise OptionError("No such keys(s)")
+
+    if len(keys) > 1 and len(pat) < 4 and pat != "all":
+        raise ValueError(
+            "You must specify at least 4 characters when "
+            "resetting multiple keys, use the special keyword "
+            '"all" to reset all the options to their default value'
+        )
+
+    for k in keys:
+        _set_option(k, _registered_options[k].defval, silent=silent)
+
+
+def get_default_val(pat: str):
+    key = _get_single_key(pat, silent=True)
+    return _get_registered_option(key).defval
+
+
+class DictWrapper:
+    """provide attribute-style access to a nested dict"""
+
+    d: dict[str, Any]
+
+    def __init__(self, d: dict[str, Any], prefix: str = "") -> None:
+        object.__setattr__(self, "d", d)
+        object.__setattr__(self, "prefix", prefix)
+
+    def __setattr__(self, key: str, val: Any) -> None:
+        prefix = object.__getattribute__(self, "prefix")
+        if prefix:
+            prefix += "."
+        prefix += key
+        # you can't set new keys
+        # can you can't overwrite subtrees
+        if key in self.d and not isinstance(self.d[key], dict):
+            _set_option(prefix, val)
+        else:
+            raise OptionError("You can only set the value of existing options")
+
+    def __getattr__(self, key: str):
+        prefix = object.__getattribute__(self, "prefix")
+        if prefix:
+            prefix += "."
+        prefix += key
+        try:
+            v = object.__getattribute__(self, "d")[key]
+        except KeyError as err:
+            raise OptionError("No such option") from err
+        if isinstance(v, dict):
+            return DictWrapper(v, prefix)
+        else:
+            return _get_option(prefix)
+
+    def __dir__(self) -> list[str]:
+        return list(self.d.keys())
+
+
+# For user convenience,  we'd like to have the available options described
+# in the docstring. For dev convenience we'd like to generate the docstrings
+# dynamically instead of maintaining them by hand. To this, we use the
+# class below which wraps functions inside a callable, and converts
+# __doc__ into a property function. The doctsrings below are templates
+# using the py2.6+ advanced formatting syntax to plug in a concise list
+# of options, and option descriptions.
+
+
+class CallableDynamicDoc(Generic[T]):
+    def __init__(self, func: Callable[..., T], doc_tmpl: str) -> None:
+        self.__doc_tmpl__ = doc_tmpl
+        self.__func__ = func
+
+    def __call__(self, *args, **kwds) -> T:
+        return self.__func__(*args, **kwds)
+
+    # error: Signature of "__doc__" incompatible with supertype "object"
+    @property
+    def __doc__(self) -> str:  # type: ignore[override]
+        opts_desc = _describe_option("all", _print_desc=False)
+        opts_list = pp_options_list(list(_registered_options.keys()))
+        return self.__doc_tmpl__.format(opts_desc=opts_desc, opts_list=opts_list)
+
+
+_get_option_tmpl = """
+get_option(pat)
+
+Retrieves the value of the specified option.
+
+Available options:
+
+{opts_list}
+
+Parameters
+----------
+pat : str
+    Regexp which should match a single option.
+    Note: partial matches are supported for convenience, but unless you use the
+    full option name (e.g. x.y.z.option_name), your code may break in future
+    versions if new options with similar names are introduced.
+
+Returns
+-------
+result : the value of the option
+
+Raises
+------
+OptionError : if no such option exists
+
+Notes
+-----
+Please reference the :ref:`User Guide ` for more information.
+
+The available options with its descriptions:
+
+{opts_desc}
+
+Examples
+--------
+>>> pd.get_option('display.max_columns')  # doctest: +SKIP
+4
+"""
+
+_set_option_tmpl = """
+set_option(pat, value)
+
+Sets the value of the specified option.
+
+Available options:
+
+{opts_list}
+
+Parameters
+----------
+pat : str
+    Regexp which should match a single option.
+    Note: partial matches are supported for convenience, but unless you use the
+    full option name (e.g. x.y.z.option_name), your code may break in future
+    versions if new options with similar names are introduced.
+value : object
+    New value of option.
+
+Returns
+-------
+None
+
+Raises
+------
+OptionError if no such option exists
+
+Notes
+-----
+Please reference the :ref:`User Guide ` for more information.
+
+The available options with its descriptions:
+
+{opts_desc}
+
+Examples
+--------
+>>> pd.set_option('display.max_columns', 4)
+>>> df = pd.DataFrame([[1, 2, 3, 4, 5], [6, 7, 8, 9, 10]])
+>>> df
+   0  1  ...  3   4
+0  1  2  ...  4   5
+1  6  7  ...  9  10
+[2 rows x 5 columns]
+>>> pd.reset_option('display.max_columns')
+"""
+
+_describe_option_tmpl = """
+describe_option(pat, _print_desc=False)
+
+Prints the description for one or more registered options.
+
+Call with no arguments to get a listing for all registered options.
+
+Available options:
+
+{opts_list}
+
+Parameters
+----------
+pat : str
+    Regexp pattern. All matching keys will have their description displayed.
+_print_desc : bool, default True
+    If True (default) the description(s) will be printed to stdout.
+    Otherwise, the description(s) will be returned as a unicode string
+    (for testing).
+
+Returns
+-------
+None by default, the description(s) as a unicode string if _print_desc
+is False
+
+Notes
+-----
+Please reference the :ref:`User Guide ` for more information.
+
+The available options with its descriptions:
+
+{opts_desc}
+
+Examples
+--------
+>>> pd.describe_option('display.max_columns')  # doctest: +SKIP
+display.max_columns : int
+    If max_cols is exceeded, switch to truncate view...
+"""
+
+_reset_option_tmpl = """
+reset_option(pat)
+
+Reset one or more options to their default value.
+
+Pass "all" as argument to reset all options.
+
+Available options:
+
+{opts_list}
+
+Parameters
+----------
+pat : str/regex
+    If specified only options matching `prefix*` will be reset.
+    Note: partial matches are supported for convenience, but unless you
+    use the full option name (e.g. x.y.z.option_name), your code may break
+    in future versions if new options with similar names are introduced.
+
+Returns
+-------
+None
+
+Notes
+-----
+Please reference the :ref:`User Guide ` for more information.
+
+The available options with its descriptions:
+
+{opts_desc}
+
+Examples
+--------
+>>> pd.reset_option('display.max_columns')  # doctest: +SKIP
+"""
+
+# bind the functions with their docstrings into a Callable
+# and use that as the functions exposed in pd.api
+get_option = CallableDynamicDoc(_get_option, _get_option_tmpl)
+set_option = CallableDynamicDoc(_set_option, _set_option_tmpl)
+reset_option = CallableDynamicDoc(_reset_option, _reset_option_tmpl)
+describe_option = CallableDynamicDoc(_describe_option, _describe_option_tmpl)
+options = DictWrapper(_global_config)
+
+#
+# Functions for use by pandas developers, in addition to User - api
+
+
+class option_context(ContextDecorator):
+    """
+    Context manager to temporarily set options in the `with` statement context.
+
+    You need to invoke as ``option_context(pat, val, [(pat, val), ...])``.
+
+    Examples
+    --------
+    >>> from pandas import option_context
+    >>> with option_context('display.max_rows', 10, 'display.max_columns', 5):
+    ...     pass
+    """
+
+    def __init__(self, *args) -> None:
+        if len(args) % 2 != 0 or len(args) < 2:
+            raise ValueError(
+                "Need to invoke as option_context(pat, val, [(pat, val), ...])."
+            )
+
+        self.ops = list(zip(args[::2], args[1::2]))
+
+    def __enter__(self) -> None:
+        self.undo = [(pat, _get_option(pat)) for pat, val in self.ops]
+
+        for pat, val in self.ops:
+            _set_option(pat, val, silent=True)
+
+    def __exit__(self, *args) -> None:
+        if self.undo:
+            for pat, val in self.undo:
+                _set_option(pat, val, silent=True)
+
+
+def register_option(
+    key: str,
+    defval: object,
+    doc: str = "",
+    validator: Callable[[object], Any] | None = None,
+    cb: Callable[[str], Any] | None = None,
+) -> None:
+    """
+    Register an option in the package-wide pandas config object
+
+    Parameters
+    ----------
+    key : str
+        Fully-qualified key, e.g. "x.y.option - z".
+    defval : object
+        Default value of the option.
+    doc : str
+        Description of the option.
+    validator : Callable, optional
+        Function of a single argument, should raise `ValueError` if
+        called with a value which is not a legal value for the option.
+    cb
+        a function of a single argument "key", which is called
+        immediately after an option value is set/reset. key is
+        the full name of the option.
+
+    Raises
+    ------
+    ValueError if `validator` is specified and `defval` is not a valid value.
+
+    """
+    import keyword
+    import tokenize
+
+    key = key.lower()
+
+    if key in _registered_options:
+        raise OptionError(f"Option '{key}' has already been registered")
+    if key in _reserved_keys:
+        raise OptionError(f"Option '{key}' is a reserved key")
+
+    # the default value should be legal
+    if validator:
+        validator(defval)
+
+    # walk the nested dict, creating dicts as needed along the path
+    path = key.split(".")
+
+    for k in path:
+        if not re.match("^" + tokenize.Name + "$", k):
+            raise ValueError(f"{k} is not a valid identifier")
+        if keyword.iskeyword(k):
+            raise ValueError(f"{k} is a python keyword")
+
+    cursor = _global_config
+    msg = "Path prefix to option '{option}' is already an option"
+
+    for i, p in enumerate(path[:-1]):
+        if not isinstance(cursor, dict):
+            raise OptionError(msg.format(option=".".join(path[:i])))
+        if p not in cursor:
+            cursor[p] = {}
+        cursor = cursor[p]
+
+    if not isinstance(cursor, dict):
+        raise OptionError(msg.format(option=".".join(path[:-1])))
+
+    cursor[path[-1]] = defval  # initialize
+
+    # save the option metadata
+    _registered_options[key] = RegisteredOption(
+        key=key, defval=defval, doc=doc, validator=validator, cb=cb
+    )
+
+
+def deprecate_option(
+    key: str,
+    msg: str | None = None,
+    rkey: str | None = None,
+    removal_ver: str | None = None,
+) -> None:
+    """
+    Mark option `key` as deprecated, if code attempts to access this option,
+    a warning will be produced, using `msg` if given, or a default message
+    if not.
+    if `rkey` is given, any access to the key will be re-routed to `rkey`.
+
+    Neither the existence of `key` nor that if `rkey` is checked. If they
+    do not exist, any subsequence access will fail as usual, after the
+    deprecation warning is given.
+
+    Parameters
+    ----------
+    key : str
+        Name of the option to be deprecated.
+        must be a fully-qualified option name (e.g "x.y.z.rkey").
+    msg : str, optional
+        Warning message to output when the key is referenced.
+        if no message is given a default message will be emitted.
+    rkey : str, optional
+        Name of an option to reroute access to.
+        If specified, any referenced `key` will be
+        re-routed to `rkey` including set/get/reset.
+        rkey must be a fully-qualified option name (e.g "x.y.z.rkey").
+        used by the default message if no `msg` is specified.
+    removal_ver : str, optional
+        Specifies the version in which this option will
+        be removed. used by the default message if no `msg` is specified.
+
+    Raises
+    ------
+    OptionError
+        If the specified key has already been deprecated.
+    """
+    key = key.lower()
+
+    if key in _deprecated_options:
+        raise OptionError(f"Option '{key}' has already been defined as deprecated.")
+
+    _deprecated_options[key] = DeprecatedOption(key, msg, rkey, removal_ver)
+
+
+#
+# functions internal to the module
+
+
+def _select_options(pat: str) -> list[str]:
+    """
+    returns a list of keys matching `pat`
+
+    if pat=="all", returns all registered options
+    """
+    # short-circuit for exact key
+    if pat in _registered_options:
+        return [pat]
+
+    # else look through all of them
+    keys = sorted(_registered_options.keys())
+    if pat == "all":  # reserved key
+        return keys
+
+    return [k for k in keys if re.search(pat, k, re.I)]
+
+
+def _get_root(key: str) -> tuple[dict[str, Any], str]:
+    path = key.split(".")
+    cursor = _global_config
+    for p in path[:-1]:
+        cursor = cursor[p]
+    return cursor, path[-1]
+
+
+def _is_deprecated(key: str) -> bool:
+    """Returns True if the given option has been deprecated"""
+    key = key.lower()
+    return key in _deprecated_options
+
+
+def _get_deprecated_option(key: str):
+    """
+    Retrieves the metadata for a deprecated option, if `key` is deprecated.
+
+    Returns
+    -------
+    DeprecatedOption (namedtuple) if key is deprecated, None otherwise
+    """
+    try:
+        d = _deprecated_options[key]
+    except KeyError:
+        return None
+    else:
+        return d
+
+
+def _get_registered_option(key: str):
+    """
+    Retrieves the option metadata if `key` is a registered option.
+
+    Returns
+    -------
+    RegisteredOption (namedtuple) if key is deprecated, None otherwise
+    """
+    return _registered_options.get(key)
+
+
+def _translate_key(key: str) -> str:
+    """
+    if key id deprecated and a replacement key defined, will return the
+    replacement key, otherwise returns `key` as - is
+    """
+    d = _get_deprecated_option(key)
+    if d:
+        return d.rkey or key
+    else:
+        return key
+
+
+def _warn_if_deprecated(key: str) -> bool:
+    """
+    Checks if `key` is a deprecated option and if so, prints a warning.
+
+    Returns
+    -------
+    bool - True if `key` is deprecated, False otherwise.
+    """
+    d = _get_deprecated_option(key)
+    if d:
+        if d.msg:
+            warnings.warn(
+                d.msg,
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            msg = f"'{key}' is deprecated"
+            if d.removal_ver:
+                msg += f" and will be removed in {d.removal_ver}"
+            if d.rkey:
+                msg += f", please use '{d.rkey}' instead."
+            else:
+                msg += ", please refrain from using it."
+
+            warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+        return True
+    return False
+
+
+def _build_option_description(k: str) -> str:
+    """Builds a formatted description of a registered option and prints it"""
+    o = _get_registered_option(k)
+    d = _get_deprecated_option(k)
+
+    s = f"{k} "
+
+    if o.doc:
+        s += "\n".join(o.doc.strip().split("\n"))
+    else:
+        s += "No description available."
+
+    if o:
+        s += f"\n    [default: {o.defval}] [currently: {_get_option(k, True)}]"
+
+    if d:
+        rkey = d.rkey or ""
+        s += "\n    (Deprecated"
+        s += f", use `{rkey}` instead."
+        s += ")"
+
+    return s
+
+
+def pp_options_list(keys: Iterable[str], width: int = 80, _print: bool = False):
+    """Builds a concise listing of available options, grouped by prefix"""
+    from itertools import groupby
+    from textwrap import wrap
+
+    def pp(name: str, ks: Iterable[str]) -> list[str]:
+        pfx = "- " + name + ".[" if name else ""
+        ls = wrap(
+            ", ".join(ks),
+            width,
+            initial_indent=pfx,
+            subsequent_indent="  ",
+            break_long_words=False,
+        )
+        if ls and ls[-1] and name:
+            ls[-1] = ls[-1] + "]"
+        return ls
+
+    ls: list[str] = []
+    singles = [x for x in sorted(keys) if x.find(".") < 0]
+    if singles:
+        ls += pp("", singles)
+    keys = [x for x in keys if x.find(".") >= 0]
+
+    for k, g in groupby(sorted(keys), lambda x: x[: x.rfind(".")]):
+        ks = [x[len(k) + 1 :] for x in list(g)]
+        ls += pp(k, ks)
+    s = "\n".join(ls)
+    if _print:
+        print(s)
+    else:
+        return s
+
+
+#
+# helpers
+
+
+@contextmanager
+def config_prefix(prefix: str) -> Generator[None, None, None]:
+    """
+    contextmanager for multiple invocations of API with a common prefix
+
+    supported API functions: (register / get / set )__option
+
+    Warning: This is not thread - safe, and won't work properly if you import
+    the API functions into your module using the "from x import y" construct.
+
+    Example
+    -------
+    import pandas._config.config as cf
+    with cf.config_prefix("display.font"):
+        cf.register_option("color", "red")
+        cf.register_option("size", " 5 pt")
+        cf.set_option(size, " 6 pt")
+        cf.get_option(size)
+        ...
+
+        etc'
+
+    will register options "display.font.color", "display.font.size", set the
+    value of "display.font.size"... and so on.
+    """
+    # Note: reset_option relies on set_option, and on key directly
+    # it does not fit in to this monkey-patching scheme
+
+    global register_option, get_option, set_option
+
+    def wrap(func: F) -> F:
+        def inner(key: str, *args, **kwds):
+            pkey = f"{prefix}.{key}"
+            return func(pkey, *args, **kwds)
+
+        return cast(F, inner)
+
+    _register_option = register_option
+    _get_option = get_option
+    _set_option = set_option
+    set_option = wrap(set_option)
+    get_option = wrap(get_option)
+    register_option = wrap(register_option)
+    try:
+        yield
+    finally:
+        set_option = _set_option
+        get_option = _get_option
+        register_option = _register_option
+
+
+# These factories and methods are handy for use as the validator
+# arg in register_option
+
+
+def is_type_factory(_type: type[Any]) -> Callable[[Any], None]:
+    """
+
+    Parameters
+    ----------
+    `_type` - a type to be compared against (e.g. type(x) == `_type`)
+
+    Returns
+    -------
+    validator - a function of a single argument x , which raises
+                ValueError if type(x) is not equal to `_type`
+
+    """
+
+    def inner(x) -> None:
+        if type(x) != _type:
+            raise ValueError(f"Value must have type '{_type}'")
+
+    return inner
+
+
+def is_instance_factory(_type) -> Callable[[Any], None]:
+    """
+
+    Parameters
+    ----------
+    `_type` - the type to be checked against
+
+    Returns
+    -------
+    validator - a function of a single argument x , which raises
+                ValueError if x is not an instance of `_type`
+
+    """
+    if isinstance(_type, (tuple, list)):
+        _type = tuple(_type)
+        type_repr = "|".join(map(str, _type))
+    else:
+        type_repr = f"'{_type}'"
+
+    def inner(x) -> None:
+        if not isinstance(x, _type):
+            raise ValueError(f"Value must be an instance of {type_repr}")
+
+    return inner
+
+
+def is_one_of_factory(legal_values) -> Callable[[Any], None]:
+    callables = [c for c in legal_values if callable(c)]
+    legal_values = [c for c in legal_values if not callable(c)]
+
+    def inner(x) -> None:
+        if x not in legal_values:
+            if not any(c(x) for c in callables):
+                uvals = [str(lval) for lval in legal_values]
+                pp_values = "|".join(uvals)
+                msg = f"Value must be one of {pp_values}"
+                if len(callables):
+                    msg += " or a callable"
+                raise ValueError(msg)
+
+    return inner
+
+
+def is_nonnegative_int(value: object) -> None:
+    """
+    Verify that value is None or a positive int.
+
+    Parameters
+    ----------
+    value : None or int
+            The `value` to be checked.
+
+    Raises
+    ------
+    ValueError
+        When the value is not None or is a negative integer
+    """
+    if value is None:
+        return
+
+    elif isinstance(value, int):
+        if value >= 0:
+            return
+
+    msg = "Value must be a nonnegative integer or None"
+    raise ValueError(msg)
+
+
+# common type validators, for convenience
+# usage: register_option(... , validator = is_int)
+is_int = is_type_factory(int)
+is_bool = is_type_factory(bool)
+is_float = is_type_factory(float)
+is_str = is_type_factory(str)
+is_text = is_instance_factory((str, bytes))
+
+
+def is_callable(obj) -> bool:
+    """
+
+    Parameters
+    ----------
+    `obj` - the object to be checked
+
+    Returns
+    -------
+    validator - returns True if object is callable
+        raises ValueError otherwise.
+
+    """
+    if not callable(obj):
+        raise ValueError("Value must be a callable")
+    return True
diff --git a/.venv/lib/python3.13/site-packages/pandas/_config/dates.py b/.venv/lib/python3.13/site-packages/pandas/_config/dates.py
new file mode 100644
index 0000000000000000000000000000000000000000..b37831f96eb73bf2f128929a1769db6c141eebad
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_config/dates.py
@@ -0,0 +1,25 @@
+"""
+config for datetime formatting
+"""
+from __future__ import annotations
+
+from pandas._config import config as cf
+
+pc_date_dayfirst_doc = """
+: boolean
+    When True, prints and parses dates with the day first, eg 20/01/2005
+"""
+
+pc_date_yearfirst_doc = """
+: boolean
+    When True, prints and parses dates with the year first, eg 2005/01/20
+"""
+
+with cf.config_prefix("display"):
+    # Needed upstream of `_libs` because these are used in tslibs.parsing
+    cf.register_option(
+        "date_dayfirst", False, pc_date_dayfirst_doc, validator=cf.is_bool
+    )
+    cf.register_option(
+        "date_yearfirst", False, pc_date_yearfirst_doc, validator=cf.is_bool
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/_config/display.py b/.venv/lib/python3.13/site-packages/pandas/_config/display.py
new file mode 100644
index 0000000000000000000000000000000000000000..df2c3ad36c855d77c33d80c78c3d83ab3c09d5f9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_config/display.py
@@ -0,0 +1,62 @@
+"""
+Unopinionated display configuration.
+"""
+
+from __future__ import annotations
+
+import locale
+import sys
+
+from pandas._config import config as cf
+
+# -----------------------------------------------------------------------------
+# Global formatting options
+_initial_defencoding: str | None = None
+
+
+def detect_console_encoding() -> str:
+    """
+    Try to find the most capable encoding supported by the console.
+    slightly modified from the way IPython handles the same issue.
+    """
+    global _initial_defencoding
+
+    encoding = None
+    try:
+        encoding = sys.stdout.encoding or sys.stdin.encoding
+    except (AttributeError, OSError):
+        pass
+
+    # try again for something better
+    if not encoding or "ascii" in encoding.lower():
+        try:
+            encoding = locale.getpreferredencoding()
+        except locale.Error:
+            # can be raised by locale.setlocale(), which is
+            #  called by getpreferredencoding
+            #  (on some systems, see stdlib locale docs)
+            pass
+
+    # when all else fails. this will usually be "ascii"
+    if not encoding or "ascii" in encoding.lower():
+        encoding = sys.getdefaultencoding()
+
+    # GH#3360, save the reported defencoding at import time
+    # MPL backends may change it. Make available for debugging.
+    if not _initial_defencoding:
+        _initial_defencoding = sys.getdefaultencoding()
+
+    return encoding
+
+
+pc_encoding_doc = """
+: str/unicode
+    Defaults to the detected encoding of the console.
+    Specifies the encoding to be used for strings returned by to_string,
+    these are generally strings meant to be displayed on the console.
+"""
+
+with cf.config_prefix("display"):
+    cf.register_option(
+        "encoding", detect_console_encoding(), pc_encoding_doc, validator=cf.is_text
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/_config/localization.py b/.venv/lib/python3.13/site-packages/pandas/_config/localization.py
new file mode 100644
index 0000000000000000000000000000000000000000..5c1a0ff1395334a55baa6c5d77a71635872fe824
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_config/localization.py
@@ -0,0 +1,172 @@
+"""
+Helpers for configuring locale settings.
+
+Name `localization` is chosen to avoid overlap with builtin `locale` module.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+import locale
+import platform
+import re
+import subprocess
+from typing import TYPE_CHECKING
+
+from pandas._config.config import options
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+@contextmanager
+def set_locale(
+    new_locale: str | tuple[str, str], lc_var: int = locale.LC_ALL
+) -> Generator[str | tuple[str, str], None, None]:
+    """
+    Context manager for temporarily setting a locale.
+
+    Parameters
+    ----------
+    new_locale : str or tuple
+        A string of the form .. For example to set
+        the current locale to US English with a UTF8 encoding, you would pass
+        "en_US.UTF-8".
+    lc_var : int, default `locale.LC_ALL`
+        The category of the locale being set.
+
+    Notes
+    -----
+    This is useful when you want to run a particular block of code under a
+    particular locale, without globally setting the locale. This probably isn't
+    thread-safe.
+    """
+    # getlocale is not always compliant with setlocale, use setlocale. GH#46595
+    current_locale = locale.setlocale(lc_var)
+
+    try:
+        locale.setlocale(lc_var, new_locale)
+        normalized_code, normalized_encoding = locale.getlocale()
+        if normalized_code is not None and normalized_encoding is not None:
+            yield f"{normalized_code}.{normalized_encoding}"
+        else:
+            yield new_locale
+    finally:
+        locale.setlocale(lc_var, current_locale)
+
+
+def can_set_locale(lc: str, lc_var: int = locale.LC_ALL) -> bool:
+    """
+    Check to see if we can set a locale, and subsequently get the locale,
+    without raising an Exception.
+
+    Parameters
+    ----------
+    lc : str
+        The locale to attempt to set.
+    lc_var : int, default `locale.LC_ALL`
+        The category of the locale being set.
+
+    Returns
+    -------
+    bool
+        Whether the passed locale can be set
+    """
+    try:
+        with set_locale(lc, lc_var=lc_var):
+            pass
+    except (ValueError, locale.Error):
+        # horrible name for a Exception subclass
+        return False
+    else:
+        return True
+
+
+def _valid_locales(locales: list[str] | str, normalize: bool) -> list[str]:
+    """
+    Return a list of normalized locales that do not throw an ``Exception``
+    when set.
+
+    Parameters
+    ----------
+    locales : str
+        A string where each locale is separated by a newline.
+    normalize : bool
+        Whether to call ``locale.normalize`` on each locale.
+
+    Returns
+    -------
+    valid_locales : list
+        A list of valid locales.
+    """
+    return [
+        loc
+        for loc in (
+            locale.normalize(loc.strip()) if normalize else loc.strip()
+            for loc in locales
+        )
+        if can_set_locale(loc)
+    ]
+
+
+def get_locales(
+    prefix: str | None = None,
+    normalize: bool = True,
+) -> list[str]:
+    """
+    Get all the locales that are available on the system.
+
+    Parameters
+    ----------
+    prefix : str
+        If not ``None`` then return only those locales with the prefix
+        provided. For example to get all English language locales (those that
+        start with ``"en"``), pass ``prefix="en"``.
+    normalize : bool
+        Call ``locale.normalize`` on the resulting list of available locales.
+        If ``True``, only locales that can be set without throwing an
+        ``Exception`` are returned.
+
+    Returns
+    -------
+    locales : list of strings
+        A list of locale strings that can be set with ``locale.setlocale()``.
+        For example::
+
+            locale.setlocale(locale.LC_ALL, locale_string)
+
+    On error will return an empty list (no locale available, e.g. Windows)
+
+    """
+    if platform.system() in ("Linux", "Darwin"):
+        raw_locales = subprocess.check_output(["locale", "-a"])
+    else:
+        # Other platforms e.g. windows platforms don't define "locale -a"
+        #  Note: is_platform_windows causes circular import here
+        return []
+
+    try:
+        # raw_locales is "\n" separated list of locales
+        # it may contain non-decodable parts, so split
+        # extract what we can and then rejoin.
+        split_raw_locales = raw_locales.split(b"\n")
+        out_locales = []
+        for x in split_raw_locales:
+            try:
+                out_locales.append(str(x, encoding=options.display.encoding))
+            except UnicodeError:
+                # 'locale -a' is used to populated 'raw_locales' and on
+                # Redhat 7 Linux (and maybe others) prints locale names
+                # using windows-1252 encoding.  Bug only triggered by
+                # a few special characters and when there is an
+                # extensive list of installed locales.
+                out_locales.append(str(x, encoding="windows-1252"))
+
+    except TypeError:
+        pass
+
+    if prefix is None:
+        return _valid_locales(out_locales, normalize)
+
+    pattern = re.compile(f"{prefix}.*")
+    found = pattern.findall("\n".join(out_locales))
+    return _valid_locales(found, normalize)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/__init__.py b/.venv/lib/python3.13/site-packages/pandas/_libs/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..26a872a90e4934c929d168228125f2e43936c774
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/__init__.py
@@ -0,0 +1,27 @@
+__all__ = [
+    "NaT",
+    "NaTType",
+    "OutOfBoundsDatetime",
+    "Period",
+    "Timedelta",
+    "Timestamp",
+    "iNaT",
+    "Interval",
+]
+
+
+# Below imports needs to happen first to ensure pandas top level
+# module gets monkeypatched with the pandas_datetime_CAPI
+# see pandas_datetime_exec in pd_datetime.c
+import pandas._libs.pandas_parser  # isort: skip # type: ignore[reportUnusedImport]
+import pandas._libs.pandas_datetime  # noqa: F401 # isort: skip # type: ignore[reportUnusedImport]
+from pandas._libs.interval import Interval
+from pandas._libs.tslibs import (
+    NaT,
+    NaTType,
+    OutOfBoundsDatetime,
+    Period,
+    Timedelta,
+    Timestamp,
+    iNaT,
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/algos.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/algos.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..5b80a972fab15f16ccfbad81d1a48e7df3238539
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/algos.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e786c886e2973cc54dadf1caf6b22daa3f102acdcaca904be7c429704f03da36
+size 2126992
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/algos.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/algos.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..caf5425dfc7b44cbb2fea103e56d4584709eca1e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/algos.pyi
@@ -0,0 +1,416 @@
+from typing import Any
+
+import numpy as np
+
+from pandas._typing import npt
+
+class Infinity:
+    def __eq__(self, other) -> bool: ...
+    def __ne__(self, other) -> bool: ...
+    def __lt__(self, other) -> bool: ...
+    def __le__(self, other) -> bool: ...
+    def __gt__(self, other) -> bool: ...
+    def __ge__(self, other) -> bool: ...
+
+class NegInfinity:
+    def __eq__(self, other) -> bool: ...
+    def __ne__(self, other) -> bool: ...
+    def __lt__(self, other) -> bool: ...
+    def __le__(self, other) -> bool: ...
+    def __gt__(self, other) -> bool: ...
+    def __ge__(self, other) -> bool: ...
+
+def unique_deltas(
+    arr: np.ndarray,  # const int64_t[:]
+) -> np.ndarray: ...  # np.ndarray[np.int64, ndim=1]
+def is_lexsorted(list_of_arrays: list[npt.NDArray[np.int64]]) -> bool: ...
+def groupsort_indexer(
+    index: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+) -> tuple[
+    np.ndarray,  # ndarray[int64_t, ndim=1]
+    np.ndarray,  # ndarray[int64_t, ndim=1]
+]: ...
+def kth_smallest(
+    arr: np.ndarray,  # numeric[:]
+    k: int,
+) -> Any: ...  # numeric
+
+# ----------------------------------------------------------------------
+# Pairwise correlation/covariance
+
+def nancorr(
+    mat: npt.NDArray[np.float64],  # const float64_t[:, :]
+    cov: bool = ...,
+    minp: int | None = ...,
+) -> npt.NDArray[np.float64]: ...  # ndarray[float64_t, ndim=2]
+def nancorr_spearman(
+    mat: npt.NDArray[np.float64],  # ndarray[float64_t, ndim=2]
+    minp: int = ...,
+) -> npt.NDArray[np.float64]: ...  # ndarray[float64_t, ndim=2]
+
+# ----------------------------------------------------------------------
+
+def validate_limit(nobs: int | None, limit=...) -> int: ...
+def get_fill_indexer(
+    mask: npt.NDArray[np.bool_],
+    limit: int | None = None,
+) -> npt.NDArray[np.intp]: ...
+def pad(
+    old: np.ndarray,  # ndarray[numeric_object_t]
+    new: np.ndarray,  # ndarray[numeric_object_t]
+    limit=...,
+) -> npt.NDArray[np.intp]: ...  # np.ndarray[np.intp, ndim=1]
+def pad_inplace(
+    values: np.ndarray,  # numeric_object_t[:]
+    mask: np.ndarray,  # uint8_t[:]
+    limit=...,
+) -> None: ...
+def pad_2d_inplace(
+    values: np.ndarray,  # numeric_object_t[:, :]
+    mask: np.ndarray,  # const uint8_t[:, :]
+    limit=...,
+) -> None: ...
+def backfill(
+    old: np.ndarray,  # ndarray[numeric_object_t]
+    new: np.ndarray,  # ndarray[numeric_object_t]
+    limit=...,
+) -> npt.NDArray[np.intp]: ...  # np.ndarray[np.intp, ndim=1]
+def backfill_inplace(
+    values: np.ndarray,  # numeric_object_t[:]
+    mask: np.ndarray,  # uint8_t[:]
+    limit=...,
+) -> None: ...
+def backfill_2d_inplace(
+    values: np.ndarray,  # numeric_object_t[:, :]
+    mask: np.ndarray,  # const uint8_t[:, :]
+    limit=...,
+) -> None: ...
+def is_monotonic(
+    arr: np.ndarray,  # ndarray[numeric_object_t, ndim=1]
+    timelike: bool,
+) -> tuple[bool, bool, bool]: ...
+
+# ----------------------------------------------------------------------
+# rank_1d, rank_2d
+# ----------------------------------------------------------------------
+
+def rank_1d(
+    values: np.ndarray,  # ndarray[numeric_object_t, ndim=1]
+    labels: np.ndarray | None = ...,  # const int64_t[:]=None
+    is_datetimelike: bool = ...,
+    ties_method=...,
+    ascending: bool = ...,
+    pct: bool = ...,
+    na_option=...,
+    mask: npt.NDArray[np.bool_] | None = ...,
+) -> np.ndarray: ...  # np.ndarray[float64_t, ndim=1]
+def rank_2d(
+    in_arr: np.ndarray,  # ndarray[numeric_object_t, ndim=2]
+    axis: int = ...,
+    is_datetimelike: bool = ...,
+    ties_method=...,
+    ascending: bool = ...,
+    na_option=...,
+    pct: bool = ...,
+) -> np.ndarray: ...  # np.ndarray[float64_t, ndim=1]
+def diff_2d(
+    arr: np.ndarray,  # ndarray[diff_t, ndim=2]
+    out: np.ndarray,  # ndarray[out_t, ndim=2]
+    periods: int,
+    axis: int,
+    datetimelike: bool = ...,
+) -> None: ...
+def ensure_platform_int(arr: object) -> npt.NDArray[np.intp]: ...
+def ensure_object(arr: object) -> npt.NDArray[np.object_]: ...
+def ensure_float64(arr: object) -> npt.NDArray[np.float64]: ...
+def ensure_int8(arr: object) -> npt.NDArray[np.int8]: ...
+def ensure_int16(arr: object) -> npt.NDArray[np.int16]: ...
+def ensure_int32(arr: object) -> npt.NDArray[np.int32]: ...
+def ensure_int64(arr: object) -> npt.NDArray[np.int64]: ...
+def ensure_uint64(arr: object) -> npt.NDArray[np.uint64]: ...
+def take_1d_int8_int8(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int8_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int8_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int8_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int16_int16(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int16_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int16_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int16_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int32_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int32_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int64_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_int64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_float32_float32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_float32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_float64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_object_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_bool_bool(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_1d_bool_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int8_int8(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int8_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int8_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int8_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int16_int16(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int16_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int16_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int16_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int32_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int32_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int64_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_int64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_float32_float32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_float32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_float64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_object_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_bool_bool(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis0_bool_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int8_int8(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int8_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int8_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int8_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int16_int16(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int16_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int16_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int16_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int32_int32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int32_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int64_int64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_int64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_float32_float32(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_float32_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_float64_float64(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_object_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_bool_bool(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_axis1_bool_object(
+    values: np.ndarray, indexer: npt.NDArray[np.intp], out: np.ndarray, fill_value=...
+) -> None: ...
+def take_2d_multi_int8_int8(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int8_int32(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int8_int64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int8_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int16_int16(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int16_int32(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int16_int64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int16_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int32_int32(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int32_int64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int32_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int64_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_float32_float32(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_float32_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_float64_float64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_object_object(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_bool_bool(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_bool_object(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
+def take_2d_multi_int64_int64(
+    values: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value=...,
+) -> None: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..fe7c41de44de48fed6c5cf7eb68116045758b59f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0d14b620aebc1a46eb9e63a3b48f5d272acdd7cf6ec96d2b02f133859dd6cab3
+size 129456
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..86f69c3cdfc75f3101a8e0afe59f9b102d90ad79
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/arrays.pyi
@@ -0,0 +1,40 @@
+from typing import Sequence
+
+import numpy as np
+
+from pandas._typing import (
+    AxisInt,
+    DtypeObj,
+    Self,
+    Shape,
+)
+
+class NDArrayBacked:
+    _dtype: DtypeObj
+    _ndarray: np.ndarray
+    def __init__(self, values: np.ndarray, dtype: DtypeObj) -> None: ...
+    @classmethod
+    def _simple_new(cls, values: np.ndarray, dtype: DtypeObj): ...
+    def _from_backing_data(self, values: np.ndarray): ...
+    def __setstate__(self, state): ...
+    def __len__(self) -> int: ...
+    @property
+    def shape(self) -> Shape: ...
+    @property
+    def ndim(self) -> int: ...
+    @property
+    def size(self) -> int: ...
+    @property
+    def nbytes(self) -> int: ...
+    def copy(self, order=...): ...
+    def delete(self, loc, axis=...): ...
+    def swapaxes(self, axis1, axis2): ...
+    def repeat(self, repeats: int | Sequence[int], axis: int | None = ...): ...
+    def reshape(self, *args, **kwargs): ...
+    def ravel(self, order=...): ...
+    @property
+    def T(self): ...
+    @classmethod
+    def _concat_same_type(
+        cls, to_concat: Sequence[Self], axis: AxisInt = ...
+    ) -> Self: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..99e99fe795549141ae472aee666fdc32d7ffeda7
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bb0dbfc6a50b1bb7cd509dc5b3dfeed55ad70b09
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/byteswap.pyi
@@ -0,0 +1,5 @@
+def read_float_with_byteswap(data: bytes, offset: int, byteswap: bool) -> float: ...
+def read_double_with_byteswap(data: bytes, offset: int, byteswap: bool) -> float: ...
+def read_uint16_with_byteswap(data: bytes, offset: int, byteswap: bool) -> int: ...
+def read_uint32_with_byteswap(data: bytes, offset: int, byteswap: bool) -> int: ...
+def read_uint64_with_byteswap(data: bytes, offset: int, byteswap: bool) -> int: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..9d4c987a23f4f270cb7c1b070814d52da7fa08c5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:87bc23dbf9dc37a8b97d44df97b679227385373d89645fcfed9a792e1484afaf
+size 2765128
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..eebd9331ab393d832c8c0099084a95a6aed0c460
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/groupby.pyi
@@ -0,0 +1,217 @@
+from typing import Literal
+
+import numpy as np
+
+from pandas._typing import npt
+
+def group_median_float64(
+    out: np.ndarray,  # ndarray[float64_t, ndim=2]
+    counts: npt.NDArray[np.int64],
+    values: np.ndarray,  # ndarray[float64_t, ndim=2]
+    labels: npt.NDArray[np.int64],
+    min_count: int = ...,  # Py_ssize_t
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_cumprod(
+    out: np.ndarray,  # float64_t[:, ::1]
+    values: np.ndarray,  # const float64_t[:, :]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    is_datetimelike: bool,
+    skipna: bool = ...,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_cumsum(
+    out: np.ndarray,  # int64float_t[:, ::1]
+    values: np.ndarray,  # ndarray[int64float_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    is_datetimelike: bool,
+    skipna: bool = ...,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_shift_indexer(
+    out: np.ndarray,  # int64_t[::1]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    periods: int,
+) -> None: ...
+def group_fillna_indexer(
+    out: np.ndarray,  # ndarray[intp_t]
+    labels: np.ndarray,  # ndarray[int64_t]
+    sorted_labels: npt.NDArray[np.intp],
+    mask: npt.NDArray[np.uint8],
+    limit: int,  # int64_t
+    dropna: bool,
+) -> None: ...
+def group_any_all(
+    out: np.ndarray,  # uint8_t[::1]
+    values: np.ndarray,  # const uint8_t[::1]
+    labels: np.ndarray,  # const int64_t[:]
+    mask: np.ndarray,  # const uint8_t[::1]
+    val_test: Literal["any", "all"],
+    skipna: bool,
+    result_mask: np.ndarray | None,
+) -> None: ...
+def group_sum(
+    out: np.ndarray,  # complexfloatingintuint_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[complexfloatingintuint_t, ndim=2]
+    labels: np.ndarray,  # const intp_t[:]
+    mask: np.ndarray | None,
+    result_mask: np.ndarray | None = ...,
+    min_count: int = ...,
+    is_datetimelike: bool = ...,
+    initial: object = ...,
+) -> None: ...
+def group_prod(
+    out: np.ndarray,  # int64float_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[int64float_t, ndim=2]
+    labels: np.ndarray,  # const intp_t[:]
+    mask: np.ndarray | None,
+    result_mask: np.ndarray | None = ...,
+    min_count: int = ...,
+) -> None: ...
+def group_var(
+    out: np.ndarray,  # floating[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[floating, ndim=2]
+    labels: np.ndarray,  # const intp_t[:]
+    min_count: int = ...,  # Py_ssize_t
+    ddof: int = ...,  # int64_t
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+    is_datetimelike: bool = ...,
+    name: str = ...,
+) -> None: ...
+def group_skew(
+    out: np.ndarray,  # float64_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[float64_T, ndim=2]
+    labels: np.ndarray,  # const intp_t[::1]
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+    skipna: bool = ...,
+) -> None: ...
+def group_mean(
+    out: np.ndarray,  # floating[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[floating, ndim=2]
+    labels: np.ndarray,  # const intp_t[:]
+    min_count: int = ...,  # Py_ssize_t
+    is_datetimelike: bool = ...,  # bint
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_ohlc(
+    out: np.ndarray,  # floatingintuint_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[floatingintuint_t, ndim=2]
+    labels: np.ndarray,  # const intp_t[:]
+    min_count: int = ...,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_quantile(
+    out: npt.NDArray[np.float64],
+    values: np.ndarray,  # ndarray[numeric, ndim=1]
+    labels: npt.NDArray[np.intp],
+    mask: npt.NDArray[np.uint8],
+    qs: npt.NDArray[np.float64],  # const
+    starts: npt.NDArray[np.int64],
+    ends: npt.NDArray[np.int64],
+    interpolation: Literal["linear", "lower", "higher", "nearest", "midpoint"],
+    result_mask: np.ndarray | None,
+    is_datetimelike: bool,
+) -> None: ...
+def group_last(
+    out: np.ndarray,  # rank_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[rank_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    mask: npt.NDArray[np.bool_] | None,
+    result_mask: npt.NDArray[np.bool_] | None = ...,
+    min_count: int = ...,  # Py_ssize_t
+    is_datetimelike: bool = ...,
+    skipna: bool = ...,
+) -> None: ...
+def group_nth(
+    out: np.ndarray,  # rank_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[rank_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    mask: npt.NDArray[np.bool_] | None,
+    result_mask: npt.NDArray[np.bool_] | None = ...,
+    min_count: int = ...,  # int64_t
+    rank: int = ...,  # int64_t
+    is_datetimelike: bool = ...,
+    skipna: bool = ...,
+) -> None: ...
+def group_rank(
+    out: np.ndarray,  # float64_t[:, ::1]
+    values: np.ndarray,  # ndarray[rank_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    is_datetimelike: bool,
+    ties_method: Literal["average", "min", "max", "first", "dense"] = ...,
+    ascending: bool = ...,
+    pct: bool = ...,
+    na_option: Literal["keep", "top", "bottom"] = ...,
+    mask: npt.NDArray[np.bool_] | None = ...,
+) -> None: ...
+def group_max(
+    out: np.ndarray,  # groupby_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[groupby_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    min_count: int = ...,
+    is_datetimelike: bool = ...,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_min(
+    out: np.ndarray,  # groupby_t[:, ::1]
+    counts: np.ndarray,  # int64_t[::1]
+    values: np.ndarray,  # ndarray[groupby_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    min_count: int = ...,
+    is_datetimelike: bool = ...,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_idxmin_idxmax(
+    out: npt.NDArray[np.intp],
+    counts: npt.NDArray[np.int64],
+    values: np.ndarray,  # ndarray[groupby_t, ndim=2]
+    labels: npt.NDArray[np.intp],
+    min_count: int = ...,
+    is_datetimelike: bool = ...,
+    mask: np.ndarray | None = ...,
+    name: str = ...,
+    skipna: bool = ...,
+    result_mask: np.ndarray | None = ...,
+) -> None: ...
+def group_cummin(
+    out: np.ndarray,  # groupby_t[:, ::1]
+    values: np.ndarray,  # ndarray[groupby_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    is_datetimelike: bool,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+    skipna: bool = ...,
+) -> None: ...
+def group_cummax(
+    out: np.ndarray,  # groupby_t[:, ::1]
+    values: np.ndarray,  # ndarray[groupby_t, ndim=2]
+    labels: np.ndarray,  # const int64_t[:]
+    ngroups: int,
+    is_datetimelike: bool,
+    mask: np.ndarray | None = ...,
+    result_mask: np.ndarray | None = ...,
+    skipna: bool = ...,
+) -> None: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..72ee8a94ebf7680adf397b5d81de16b019dd6d6e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6339334e87a8087c5db52986f9c285103282e5343158c033d8c87e58f24e9cc0
+size 213136
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..8361026e4a87d462e04c53f7f1f8aee8a7f6ffe0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/hashing.pyi
@@ -0,0 +1,9 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def hash_object_array(
+    arr: npt.NDArray[np.object_],
+    key: str,
+    encoding: str = ...,
+) -> npt.NDArray[np.uint64]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..2b16ad4216ec8635ba55c04edae0014d2fb6264b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e893c243ebe773a4675fc4bd634ed51bcad54294693e36f17d1ede0e9bb1ed68
+size 2248272
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..555ec73acd9b2e9ccbb5ea145db77862e2c54dbf
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/hashtable.pyi
@@ -0,0 +1,252 @@
+from typing import (
+    Any,
+    Hashable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._typing import npt
+
+def unique_label_indices(
+    labels: np.ndarray,  # const int64_t[:]
+) -> np.ndarray: ...
+
+class Factorizer:
+    count: int
+    uniques: Any
+    def __init__(self, size_hint: int) -> None: ...
+    def get_count(self) -> int: ...
+    def factorize(
+        self,
+        values: np.ndarray,
+        na_sentinel=...,
+        na_value=...,
+        mask=...,
+    ) -> npt.NDArray[np.intp]: ...
+
+class ObjectFactorizer(Factorizer):
+    table: PyObjectHashTable
+    uniques: ObjectVector
+
+class Int64Factorizer(Factorizer):
+    table: Int64HashTable
+    uniques: Int64Vector
+
+class UInt64Factorizer(Factorizer):
+    table: UInt64HashTable
+    uniques: UInt64Vector
+
+class Int32Factorizer(Factorizer):
+    table: Int32HashTable
+    uniques: Int32Vector
+
+class UInt32Factorizer(Factorizer):
+    table: UInt32HashTable
+    uniques: UInt32Vector
+
+class Int16Factorizer(Factorizer):
+    table: Int16HashTable
+    uniques: Int16Vector
+
+class UInt16Factorizer(Factorizer):
+    table: UInt16HashTable
+    uniques: UInt16Vector
+
+class Int8Factorizer(Factorizer):
+    table: Int8HashTable
+    uniques: Int8Vector
+
+class UInt8Factorizer(Factorizer):
+    table: UInt8HashTable
+    uniques: UInt8Vector
+
+class Float64Factorizer(Factorizer):
+    table: Float64HashTable
+    uniques: Float64Vector
+
+class Float32Factorizer(Factorizer):
+    table: Float32HashTable
+    uniques: Float32Vector
+
+class Complex64Factorizer(Factorizer):
+    table: Complex64HashTable
+    uniques: Complex64Vector
+
+class Complex128Factorizer(Factorizer):
+    table: Complex128HashTable
+    uniques: Complex128Vector
+
+class Int64Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.int64]: ...
+
+class Int32Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.int32]: ...
+
+class Int16Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.int16]: ...
+
+class Int8Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.int8]: ...
+
+class UInt64Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.uint64]: ...
+
+class UInt32Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.uint32]: ...
+
+class UInt16Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.uint16]: ...
+
+class UInt8Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.uint8]: ...
+
+class Float64Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.float64]: ...
+
+class Float32Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.float32]: ...
+
+class Complex128Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.complex128]: ...
+
+class Complex64Vector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.complex64]: ...
+
+class StringVector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.object_]: ...
+
+class ObjectVector:
+    def __init__(self, *args) -> None: ...
+    def __len__(self) -> int: ...
+    def to_array(self) -> npt.NDArray[np.object_]: ...
+
+class HashTable:
+    # NB: The base HashTable class does _not_ actually have these methods;
+    #  we are putting them here for the sake of mypy to avoid
+    #  reproducing them in each subclass below.
+    def __init__(self, size_hint: int = ..., uses_mask: bool = ...) -> None: ...
+    def __len__(self) -> int: ...
+    def __contains__(self, key: Hashable) -> bool: ...
+    def sizeof(self, deep: bool = ...) -> int: ...
+    def get_state(self) -> dict[str, int]: ...
+    # TODO: `val/key` type is subclass-specific
+    def get_item(self, val): ...  # TODO: return type?
+    def set_item(self, key, val) -> None: ...
+    def get_na(self): ...  # TODO: return type?
+    def set_na(self, val) -> None: ...
+    def map_locations(
+        self,
+        values: np.ndarray,  # np.ndarray[subclass-specific]
+        mask: npt.NDArray[np.bool_] | None = ...,
+    ) -> None: ...
+    def lookup(
+        self,
+        values: np.ndarray,  # np.ndarray[subclass-specific]
+        mask: npt.NDArray[np.bool_] | None = ...,
+    ) -> npt.NDArray[np.intp]: ...
+    def get_labels(
+        self,
+        values: np.ndarray,  # np.ndarray[subclass-specific]
+        uniques,  # SubclassTypeVector
+        count_prior: int = ...,
+        na_sentinel: int = ...,
+        na_value: object = ...,
+        mask=...,
+    ) -> npt.NDArray[np.intp]: ...
+    def unique(
+        self,
+        values: np.ndarray,  # np.ndarray[subclass-specific]
+        return_inverse: bool = ...,
+        mask=...,
+    ) -> (
+        tuple[
+            np.ndarray,  # np.ndarray[subclass-specific]
+            npt.NDArray[np.intp],
+        ]
+        | np.ndarray
+    ): ...  # np.ndarray[subclass-specific]
+    def factorize(
+        self,
+        values: np.ndarray,  # np.ndarray[subclass-specific]
+        na_sentinel: int = ...,
+        na_value: object = ...,
+        mask=...,
+        ignore_na: bool = True,
+    ) -> tuple[np.ndarray, npt.NDArray[np.intp]]: ...  # np.ndarray[subclass-specific]
+
+class Complex128HashTable(HashTable): ...
+class Complex64HashTable(HashTable): ...
+class Float64HashTable(HashTable): ...
+class Float32HashTable(HashTable): ...
+
+class Int64HashTable(HashTable):
+    # Only Int64HashTable has get_labels_groupby, map_keys_to_values
+    def get_labels_groupby(
+        self,
+        values: npt.NDArray[np.int64],  # const int64_t[:]
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.int64]]: ...
+    def map_keys_to_values(
+        self,
+        keys: npt.NDArray[np.int64],
+        values: npt.NDArray[np.int64],  # const int64_t[:]
+    ) -> None: ...
+
+class Int32HashTable(HashTable): ...
+class Int16HashTable(HashTable): ...
+class Int8HashTable(HashTable): ...
+class UInt64HashTable(HashTable): ...
+class UInt32HashTable(HashTable): ...
+class UInt16HashTable(HashTable): ...
+class UInt8HashTable(HashTable): ...
+class StringHashTable(HashTable): ...
+class PyObjectHashTable(HashTable): ...
+class IntpHashTable(HashTable): ...
+
+def duplicated(
+    values: np.ndarray,
+    keep: Literal["last", "first", False] = ...,
+    mask: npt.NDArray[np.bool_] | None = ...,
+) -> npt.NDArray[np.bool_]: ...
+def mode(
+    values: np.ndarray, dropna: bool, mask: npt.NDArray[np.bool_] | None = ...
+) -> np.ndarray: ...
+def value_count(
+    values: np.ndarray,
+    dropna: bool,
+    mask: npt.NDArray[np.bool_] | None = ...,
+) -> tuple[np.ndarray, npt.NDArray[np.int64], int]: ...  # np.ndarray[same-as-values]
+
+# arr and values should have same dtype
+def ismember(
+    arr: np.ndarray,
+    values: np.ndarray,
+) -> npt.NDArray[np.bool_]: ...
+def object_hash(obj) -> int: ...
+def objects_are_equal(a, b) -> bool: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/index.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/index.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..9c11b7c72832f17648a268c7c3635f84846bea29
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/index.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:4d449b1e6c5d418e36b696395955f9e63fef4de741d33bf5b25498eca7469f61
+size 873792
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/index.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/index.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..9c3791a642768ccfb13f681a31ac993c606c2304
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/index.pyi
@@ -0,0 +1,103 @@
+import numpy as np
+
+from pandas._typing import npt
+
+from pandas import MultiIndex
+from pandas.core.arrays import ExtensionArray
+
+multiindex_nulls_shift: int
+
+class IndexEngine:
+    over_size_threshold: bool
+    def __init__(self, values: np.ndarray) -> None: ...
+    def __contains__(self, val: object) -> bool: ...
+
+    # -> int | slice | np.ndarray[bool]
+    def get_loc(self, val: object) -> int | slice | np.ndarray: ...
+    def sizeof(self, deep: bool = ...) -> int: ...
+    def __sizeof__(self) -> int: ...
+    @property
+    def is_unique(self) -> bool: ...
+    @property
+    def is_monotonic_increasing(self) -> bool: ...
+    @property
+    def is_monotonic_decreasing(self) -> bool: ...
+    @property
+    def is_mapping_populated(self) -> bool: ...
+    def clear_mapping(self): ...
+    def get_indexer(self, values: np.ndarray) -> npt.NDArray[np.intp]: ...
+    def get_indexer_non_unique(
+        self,
+        targets: np.ndarray,
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+
+class MaskedIndexEngine(IndexEngine):
+    def __init__(self, values: object) -> None: ...
+    def get_indexer_non_unique(
+        self, targets: object
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+
+class Float64Engine(IndexEngine): ...
+class Float32Engine(IndexEngine): ...
+class Complex128Engine(IndexEngine): ...
+class Complex64Engine(IndexEngine): ...
+class Int64Engine(IndexEngine): ...
+class Int32Engine(IndexEngine): ...
+class Int16Engine(IndexEngine): ...
+class Int8Engine(IndexEngine): ...
+class UInt64Engine(IndexEngine): ...
+class UInt32Engine(IndexEngine): ...
+class UInt16Engine(IndexEngine): ...
+class UInt8Engine(IndexEngine): ...
+class ObjectEngine(IndexEngine): ...
+class DatetimeEngine(Int64Engine): ...
+class TimedeltaEngine(DatetimeEngine): ...
+class PeriodEngine(Int64Engine): ...
+class BoolEngine(UInt8Engine): ...
+class MaskedFloat64Engine(MaskedIndexEngine): ...
+class MaskedFloat32Engine(MaskedIndexEngine): ...
+class MaskedComplex128Engine(MaskedIndexEngine): ...
+class MaskedComplex64Engine(MaskedIndexEngine): ...
+class MaskedInt64Engine(MaskedIndexEngine): ...
+class MaskedInt32Engine(MaskedIndexEngine): ...
+class MaskedInt16Engine(MaskedIndexEngine): ...
+class MaskedInt8Engine(MaskedIndexEngine): ...
+class MaskedUInt64Engine(MaskedIndexEngine): ...
+class MaskedUInt32Engine(MaskedIndexEngine): ...
+class MaskedUInt16Engine(MaskedIndexEngine): ...
+class MaskedUInt8Engine(MaskedIndexEngine): ...
+class MaskedBoolEngine(MaskedUInt8Engine): ...
+
+class StringObjectEngine(ObjectEngine):
+    def __init__(self, values: object, na_value) -> None: ...
+
+class BaseMultiIndexCodesEngine:
+    levels: list[np.ndarray]
+    offsets: np.ndarray  # ndarray[uint64_t, ndim=1]
+
+    def __init__(
+        self,
+        levels: list[np.ndarray],  # all entries hashable
+        labels: list[np.ndarray],  # all entries integer-dtyped
+        offsets: np.ndarray,  # np.ndarray[np.uint64, ndim=1]
+    ) -> None: ...
+    def get_indexer(self, target: npt.NDArray[np.object_]) -> npt.NDArray[np.intp]: ...
+    def _extract_level_codes(self, target: MultiIndex) -> np.ndarray: ...
+
+class ExtensionEngine:
+    def __init__(self, values: ExtensionArray) -> None: ...
+    def __contains__(self, val: object) -> bool: ...
+    def get_loc(self, val: object) -> int | slice | np.ndarray: ...
+    def get_indexer(self, values: np.ndarray) -> npt.NDArray[np.intp]: ...
+    def get_indexer_non_unique(
+        self,
+        targets: np.ndarray,
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+    @property
+    def is_unique(self) -> bool: ...
+    @property
+    def is_monotonic_increasing(self) -> bool: ...
+    @property
+    def is_monotonic_decreasing(self) -> bool: ...
+    def sizeof(self, deep: bool = ...) -> int: ...
+    def clear_mapping(self): ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..35fc62c4980a8274820041879510d11f6a3b2db2
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..3ae5c5044a2f75452fa57ba578af2c7b4c78ec96
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/indexing.pyi
@@ -0,0 +1,17 @@
+from typing import (
+    Generic,
+    TypeVar,
+)
+
+from pandas.core.indexing import IndexingMixin
+
+_IndexingMixinT = TypeVar("_IndexingMixinT", bound=IndexingMixin)
+
+class NDFrameIndexerBase(Generic[_IndexingMixinT]):
+    name: str
+    # in practice obj is either a DataFrame or a Series
+    obj: _IndexingMixinT
+
+    def __init__(self, name: str, obj: _IndexingMixinT) -> None: ...
+    @property
+    def ndim(self) -> int: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/internals.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/internals.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..30f67c4ef58e509d0034d943266c43c81d22e242
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/internals.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bf2ca274548d85eb770fada8470cd3b999b3484f7cb6998f1672e02a1740faae
+size 407392
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/internals.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/internals.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..ffe6c7730bcdcfb8af1407bf55b59170c4093699
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/internals.pyi
@@ -0,0 +1,94 @@
+from typing import (
+    Iterator,
+    Sequence,
+    final,
+    overload,
+)
+import weakref
+
+import numpy as np
+
+from pandas._typing import (
+    ArrayLike,
+    Self,
+    npt,
+)
+
+from pandas import Index
+from pandas.core.internals.blocks import Block as B
+
+def slice_len(slc: slice, objlen: int = ...) -> int: ...
+def get_concat_blkno_indexers(
+    blknos_list: list[npt.NDArray[np.intp]],
+) -> list[tuple[npt.NDArray[np.intp], BlockPlacement]]: ...
+def get_blkno_indexers(
+    blknos: np.ndarray,  # int64_t[:]
+    group: bool = ...,
+) -> list[tuple[int, slice | np.ndarray]]: ...
+def get_blkno_placements(
+    blknos: np.ndarray,
+    group: bool = ...,
+) -> Iterator[tuple[int, BlockPlacement]]: ...
+def update_blklocs_and_blknos(
+    blklocs: npt.NDArray[np.intp],
+    blknos: npt.NDArray[np.intp],
+    loc: int,
+    nblocks: int,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+@final
+class BlockPlacement:
+    def __init__(self, val: int | slice | np.ndarray) -> None: ...
+    @property
+    def indexer(self) -> np.ndarray | slice: ...
+    @property
+    def as_array(self) -> np.ndarray: ...
+    @property
+    def as_slice(self) -> slice: ...
+    @property
+    def is_slice_like(self) -> bool: ...
+    @overload
+    def __getitem__(
+        self, loc: slice | Sequence[int] | npt.NDArray[np.intp]
+    ) -> BlockPlacement: ...
+    @overload
+    def __getitem__(self, loc: int) -> int: ...
+    def __iter__(self) -> Iterator[int]: ...
+    def __len__(self) -> int: ...
+    def delete(self, loc) -> BlockPlacement: ...
+    def add(self, other) -> BlockPlacement: ...
+    def append(self, others: list[BlockPlacement]) -> BlockPlacement: ...
+    def tile_for_unstack(self, factor: int) -> npt.NDArray[np.intp]: ...
+
+class Block:
+    _mgr_locs: BlockPlacement
+    ndim: int
+    values: ArrayLike
+    refs: BlockValuesRefs
+    def __init__(
+        self,
+        values: ArrayLike,
+        placement: BlockPlacement,
+        ndim: int,
+        refs: BlockValuesRefs | None = ...,
+    ) -> None: ...
+    def slice_block_rows(self, slicer: slice) -> Self: ...
+
+class BlockManager:
+    blocks: tuple[B, ...]
+    axes: list[Index]
+    _known_consolidated: bool
+    _is_consolidated: bool
+    _blknos: np.ndarray
+    _blklocs: np.ndarray
+    def __init__(
+        self, blocks: tuple[B, ...], axes: list[Index], verify_integrity=...
+    ) -> None: ...
+    def get_slice(self, slobj: slice, axis: int = ...) -> Self: ...
+    def _rebuild_blknos_and_blklocs(self) -> None: ...
+
+class BlockValuesRefs:
+    referenced_blocks: list[weakref.ref]
+    def __init__(self, blk: Block | None = ...) -> None: ...
+    def add_reference(self, blk: Block) -> None: ...
+    def add_index_reference(self, index: Index) -> None: ...
+    def has_reference(self) -> bool: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/interval.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/interval.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..7a117cc5b2a607a070b618712416394e628940f5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/interval.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:671479c65def45c8eb81e674f46f1f260d765901c13bf63e8280b99ccbbb315a
+size 1347984
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/interval.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/interval.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..587fdf84f2f85520713352bbcab29804c95621e5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/interval.pyi
@@ -0,0 +1,174 @@
+from typing import (
+    Any,
+    Generic,
+    TypeVar,
+    overload,
+)
+
+import numpy as np
+import numpy.typing as npt
+
+from pandas._typing import (
+    IntervalClosedType,
+    Timedelta,
+    Timestamp,
+)
+
+VALID_CLOSED: frozenset[str]
+
+_OrderableScalarT = TypeVar("_OrderableScalarT", int, float)
+_OrderableTimesT = TypeVar("_OrderableTimesT", Timestamp, Timedelta)
+_OrderableT = TypeVar("_OrderableT", int, float, Timestamp, Timedelta)
+
+class _LengthDescriptor:
+    @overload
+    def __get__(
+        self, instance: Interval[_OrderableScalarT], owner: Any
+    ) -> _OrderableScalarT: ...
+    @overload
+    def __get__(
+        self, instance: Interval[_OrderableTimesT], owner: Any
+    ) -> Timedelta: ...
+
+class _MidDescriptor:
+    @overload
+    def __get__(self, instance: Interval[_OrderableScalarT], owner: Any) -> float: ...
+    @overload
+    def __get__(
+        self, instance: Interval[_OrderableTimesT], owner: Any
+    ) -> _OrderableTimesT: ...
+
+class IntervalMixin:
+    @property
+    def closed_left(self) -> bool: ...
+    @property
+    def closed_right(self) -> bool: ...
+    @property
+    def open_left(self) -> bool: ...
+    @property
+    def open_right(self) -> bool: ...
+    @property
+    def is_empty(self) -> bool: ...
+    def _check_closed_matches(self, other: IntervalMixin, name: str = ...) -> None: ...
+
+class Interval(IntervalMixin, Generic[_OrderableT]):
+    @property
+    def left(self: Interval[_OrderableT]) -> _OrderableT: ...
+    @property
+    def right(self: Interval[_OrderableT]) -> _OrderableT: ...
+    @property
+    def closed(self) -> IntervalClosedType: ...
+    mid: _MidDescriptor
+    length: _LengthDescriptor
+    def __init__(
+        self,
+        left: _OrderableT,
+        right: _OrderableT,
+        closed: IntervalClosedType = ...,
+    ) -> None: ...
+    def __hash__(self) -> int: ...
+    @overload
+    def __contains__(
+        self: Interval[Timedelta], key: Timedelta | Interval[Timedelta]
+    ) -> bool: ...
+    @overload
+    def __contains__(
+        self: Interval[Timestamp], key: Timestamp | Interval[Timestamp]
+    ) -> bool: ...
+    @overload
+    def __contains__(
+        self: Interval[_OrderableScalarT],
+        key: _OrderableScalarT | Interval[_OrderableScalarT],
+    ) -> bool: ...
+    @overload
+    def __add__(
+        self: Interval[_OrderableTimesT], y: Timedelta
+    ) -> Interval[_OrderableTimesT]: ...
+    @overload
+    def __add__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __add__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __radd__(
+        self: Interval[_OrderableTimesT], y: Timedelta
+    ) -> Interval[_OrderableTimesT]: ...
+    @overload
+    def __radd__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __radd__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __sub__(
+        self: Interval[_OrderableTimesT], y: Timedelta
+    ) -> Interval[_OrderableTimesT]: ...
+    @overload
+    def __sub__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __sub__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __rsub__(
+        self: Interval[_OrderableTimesT], y: Timedelta
+    ) -> Interval[_OrderableTimesT]: ...
+    @overload
+    def __rsub__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __rsub__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __mul__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __mul__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __rmul__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __rmul__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __truediv__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __truediv__(self: Interval[float], y: float) -> Interval[float]: ...
+    @overload
+    def __floordiv__(
+        self: Interval[int], y: _OrderableScalarT
+    ) -> Interval[_OrderableScalarT]: ...
+    @overload
+    def __floordiv__(self: Interval[float], y: float) -> Interval[float]: ...
+    def overlaps(self: Interval[_OrderableT], other: Interval[_OrderableT]) -> bool: ...
+
+def intervals_to_interval_bounds(
+    intervals: np.ndarray, validate_closed: bool = ...
+) -> tuple[np.ndarray, np.ndarray, IntervalClosedType]: ...
+
+class IntervalTree(IntervalMixin):
+    def __init__(
+        self,
+        left: np.ndarray,
+        right: np.ndarray,
+        closed: IntervalClosedType = ...,
+        leaf_size: int = ...,
+    ) -> None: ...
+    @property
+    def mid(self) -> np.ndarray: ...
+    @property
+    def length(self) -> np.ndarray: ...
+    def get_indexer(self, target) -> npt.NDArray[np.intp]: ...
+    def get_indexer_non_unique(
+        self, target
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+    _na_count: int
+    @property
+    def is_overlapping(self) -> bool: ...
+    @property
+    def is_monotonic_increasing(self) -> bool: ...
+    def clear_mapping(self) -> None: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/join.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/join.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..c310529f1a376505043dbfd1a6e7c9168b6bd15f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/join.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:ed1840f2dd903c052dbd5629393567bd62c7585310fbba16cd8a4f071685f980
+size 1380080
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/join.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/join.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..1d4e8c90bc5593eae650319e9ca1b58cbd7eed73
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/join.pyi
@@ -0,0 +1,79 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def inner_join(
+    left: np.ndarray,  # const intp_t[:]
+    right: np.ndarray,  # const intp_t[:]
+    max_groups: int,
+    sort: bool = ...,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+def left_outer_join(
+    left: np.ndarray,  # const intp_t[:]
+    right: np.ndarray,  # const intp_t[:]
+    max_groups: int,
+    sort: bool = ...,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+def full_outer_join(
+    left: np.ndarray,  # const intp_t[:]
+    right: np.ndarray,  # const intp_t[:]
+    max_groups: int,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+def ffill_indexer(
+    indexer: np.ndarray,  # const intp_t[:]
+) -> npt.NDArray[np.intp]: ...
+def left_join_indexer_unique(
+    left: np.ndarray,  # ndarray[join_t]
+    right: np.ndarray,  # ndarray[join_t]
+) -> npt.NDArray[np.intp]: ...
+def left_join_indexer(
+    left: np.ndarray,  # ndarray[join_t]
+    right: np.ndarray,  # ndarray[join_t]
+) -> tuple[
+    np.ndarray,  # np.ndarray[join_t]
+    npt.NDArray[np.intp],
+    npt.NDArray[np.intp],
+]: ...
+def inner_join_indexer(
+    left: np.ndarray,  # ndarray[join_t]
+    right: np.ndarray,  # ndarray[join_t]
+) -> tuple[
+    np.ndarray,  # np.ndarray[join_t]
+    npt.NDArray[np.intp],
+    npt.NDArray[np.intp],
+]: ...
+def outer_join_indexer(
+    left: np.ndarray,  # ndarray[join_t]
+    right: np.ndarray,  # ndarray[join_t]
+) -> tuple[
+    np.ndarray,  # np.ndarray[join_t]
+    npt.NDArray[np.intp],
+    npt.NDArray[np.intp],
+]: ...
+def asof_join_backward_on_X_by_Y(
+    left_values: np.ndarray,  # ndarray[numeric_t]
+    right_values: np.ndarray,  # ndarray[numeric_t]
+    left_by_values: np.ndarray,  # const int64_t[:]
+    right_by_values: np.ndarray,  # const int64_t[:]
+    allow_exact_matches: bool = ...,
+    tolerance: np.number | float | None = ...,
+    use_hashtable: bool = ...,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+def asof_join_forward_on_X_by_Y(
+    left_values: np.ndarray,  # ndarray[numeric_t]
+    right_values: np.ndarray,  # ndarray[numeric_t]
+    left_by_values: np.ndarray,  # const int64_t[:]
+    right_by_values: np.ndarray,  # const int64_t[:]
+    allow_exact_matches: bool = ...,
+    tolerance: np.number | float | None = ...,
+    use_hashtable: bool = ...,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
+def asof_join_nearest_on_X_by_Y(
+    left_values: np.ndarray,  # ndarray[numeric_t]
+    right_values: np.ndarray,  # ndarray[numeric_t]
+    left_by_values: np.ndarray,  # const int64_t[:]
+    right_by_values: np.ndarray,  # const int64_t[:]
+    allow_exact_matches: bool = ...,
+    tolerance: np.number | float | None = ...,
+    use_hashtable: bool = ...,
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/json.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/json.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..a70720f1bfebe3fde6bb8ff1731fab852c423736
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/json.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/json.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/json.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bc4fe68573b94290cfba2e66950c1b6d45ccf0dc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/json.pyi
@@ -0,0 +1,23 @@
+from typing import (
+    Any,
+    Callable,
+)
+
+def ujson_dumps(
+    obj: Any,
+    ensure_ascii: bool = ...,
+    double_precision: int = ...,
+    indent: int = ...,
+    orient: str = ...,
+    date_unit: str = ...,
+    iso_dates: bool = ...,
+    default_handler: None
+    | Callable[[Any], str | float | bool | list | dict | None] = ...,
+) -> str: ...
+def ujson_loads(
+    s: str,
+    precise_float: bool = ...,
+    numpy: bool = ...,
+    dtype: None = ...,
+    labelled: bool = ...,
+) -> Any: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/lib.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/lib.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..6f7b9d783344d87c158ade79a6264a8b06603a5d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/lib.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:58f0414aae7a3ea6463031219aeb03a8b375f725d825dd51ce724a6071d13869
+size 862992
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/lib.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/lib.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..71a4d3ae2575ffd646568080485d9afada47d599
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/lib.pyi
@@ -0,0 +1,216 @@
+# TODO(npdtypes): Many types specified here can be made more specific/accurate;
+#  the more specific versions are specified in comments
+from decimal import Decimal
+from typing import (
+    Any,
+    Callable,
+    Final,
+    Generator,
+    Hashable,
+    Literal,
+    TypeAlias,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs.interval import Interval
+from pandas._libs.tslibs import Period
+from pandas._typing import (
+    ArrayLike,
+    DtypeObj,
+    TypeGuard,
+    npt,
+)
+
+# placeholder until we can specify np.ndarray[object, ndim=2]
+ndarray_obj_2d = np.ndarray
+
+from enum import Enum
+
+class _NoDefault(Enum):
+    no_default = ...
+
+no_default: Final = _NoDefault.no_default
+NoDefault: TypeAlias = Literal[_NoDefault.no_default]
+
+i8max: int
+u8max: int
+
+def is_np_dtype(dtype: object, kinds: str | None = ...) -> TypeGuard[np.dtype]: ...
+def item_from_zerodim(val: object) -> object: ...
+def infer_dtype(value: object, skipna: bool = ...) -> str: ...
+def is_iterator(obj: object) -> bool: ...
+def is_scalar(val: object) -> bool: ...
+def is_list_like(obj: object, allow_sets: bool = ...) -> bool: ...
+def is_pyarrow_array(obj: object) -> bool: ...
+def is_period(val: object) -> TypeGuard[Period]: ...
+def is_interval(obj: object) -> TypeGuard[Interval]: ...
+def is_decimal(obj: object) -> TypeGuard[Decimal]: ...
+def is_complex(obj: object) -> TypeGuard[complex]: ...
+def is_bool(obj: object) -> TypeGuard[bool | np.bool_]: ...
+def is_integer(obj: object) -> TypeGuard[int | np.integer]: ...
+def is_int_or_none(obj) -> bool: ...
+def is_float(obj: object) -> TypeGuard[float]: ...
+def is_interval_array(values: np.ndarray) -> bool: ...
+def is_datetime64_array(values: np.ndarray, skipna: bool = True) -> bool: ...
+def is_timedelta_or_timedelta64_array(
+    values: np.ndarray, skipna: bool = True
+) -> bool: ...
+def is_datetime_with_singletz_array(values: np.ndarray) -> bool: ...
+def is_time_array(values: np.ndarray, skipna: bool = ...): ...
+def is_date_array(values: np.ndarray, skipna: bool = ...): ...
+def is_datetime_array(values: np.ndarray, skipna: bool = ...): ...
+def is_string_array(values: np.ndarray, skipna: bool = ...): ...
+def is_float_array(values: np.ndarray): ...
+def is_integer_array(values: np.ndarray, skipna: bool = ...): ...
+def is_bool_array(values: np.ndarray, skipna: bool = ...): ...
+def fast_multiget(
+    mapping: dict,
+    keys: np.ndarray,  # object[:]
+    default=...,
+) -> np.ndarray: ...
+def fast_unique_multiple_list_gen(gen: Generator, sort: bool = ...) -> list: ...
+def fast_unique_multiple_list(lists: list, sort: bool | None = ...) -> list: ...
+def map_infer(
+    arr: np.ndarray,
+    f: Callable[[Any], Any],
+    convert: bool = ...,
+    ignore_na: bool = ...,
+) -> np.ndarray: ...
+@overload
+def maybe_convert_objects(
+    objects: npt.NDArray[np.object_],
+    *,
+    try_float: bool = ...,
+    safe: bool = ...,
+    convert_numeric: bool = ...,
+    convert_non_numeric: Literal[False] = ...,
+    convert_string: Literal[False] = ...,
+    convert_to_nullable_dtype: Literal[False] = ...,
+    dtype_if_all_nat: DtypeObj | None = ...,
+) -> npt.NDArray[np.object_ | np.number]: ...
+@overload
+def maybe_convert_objects(
+    objects: npt.NDArray[np.object_],
+    *,
+    try_float: bool = ...,
+    safe: bool = ...,
+    convert_numeric: bool = ...,
+    convert_non_numeric: bool = ...,
+    convert_string: bool = ...,
+    convert_to_nullable_dtype: Literal[True] = ...,
+    dtype_if_all_nat: DtypeObj | None = ...,
+) -> ArrayLike: ...
+@overload
+def maybe_convert_objects(
+    objects: npt.NDArray[np.object_],
+    *,
+    try_float: bool = ...,
+    safe: bool = ...,
+    convert_numeric: bool = ...,
+    convert_non_numeric: bool = ...,
+    convert_string: bool = ...,
+    convert_to_nullable_dtype: bool = ...,
+    dtype_if_all_nat: DtypeObj | None = ...,
+) -> ArrayLike: ...
+@overload
+def maybe_convert_numeric(
+    values: npt.NDArray[np.object_],
+    na_values: set,
+    convert_empty: bool = ...,
+    coerce_numeric: bool = ...,
+    convert_to_masked_nullable: Literal[False] = ...,
+) -> tuple[np.ndarray, None]: ...
+@overload
+def maybe_convert_numeric(
+    values: npt.NDArray[np.object_],
+    na_values: set,
+    convert_empty: bool = ...,
+    coerce_numeric: bool = ...,
+    *,
+    convert_to_masked_nullable: Literal[True],
+) -> tuple[np.ndarray, np.ndarray]: ...
+
+# TODO: restrict `arr`?
+def ensure_string_array(
+    arr,
+    na_value: object = ...,
+    convert_na_value: bool = ...,
+    copy: bool = ...,
+    skipna: bool = ...,
+) -> npt.NDArray[np.object_]: ...
+def convert_nans_to_NA(
+    arr: npt.NDArray[np.object_],
+) -> npt.NDArray[np.object_]: ...
+def fast_zip(ndarrays: list) -> npt.NDArray[np.object_]: ...
+
+# TODO: can we be more specific about rows?
+def to_object_array_tuples(rows: object) -> ndarray_obj_2d: ...
+def tuples_to_object_array(
+    tuples: npt.NDArray[np.object_],
+) -> ndarray_obj_2d: ...
+
+# TODO: can we be more specific about rows?
+def to_object_array(rows: object, min_width: int = ...) -> ndarray_obj_2d: ...
+def dicts_to_array(dicts: list, columns: list) -> ndarray_obj_2d: ...
+def maybe_booleans_to_slice(
+    mask: npt.NDArray[np.uint8],
+) -> slice | npt.NDArray[np.uint8]: ...
+def maybe_indices_to_slice(
+    indices: npt.NDArray[np.intp],
+    max_len: int,
+) -> slice | npt.NDArray[np.intp]: ...
+def is_all_arraylike(obj: list) -> bool: ...
+
+# -----------------------------------------------------------------
+# Functions which in reality take memoryviews
+
+def memory_usage_of_objects(arr: np.ndarray) -> int: ...  # object[:]  # np.int64
+def map_infer_mask(
+    arr: np.ndarray,
+    f: Callable[[Any], Any],
+    mask: np.ndarray,  # const uint8_t[:]
+    convert: bool = ...,
+    na_value: Any = ...,
+    dtype: np.dtype = ...,
+) -> np.ndarray: ...
+def indices_fast(
+    index: npt.NDArray[np.intp],
+    labels: np.ndarray,  # const int64_t[:]
+    keys: list,
+    sorted_labels: list[npt.NDArray[np.int64]],
+) -> dict[Hashable, npt.NDArray[np.intp]]: ...
+def generate_slices(
+    labels: np.ndarray, ngroups: int  # const intp_t[:]
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]: ...
+def count_level_2d(
+    mask: np.ndarray,  # ndarray[uint8_t, ndim=2, cast=True],
+    labels: np.ndarray,  # const intp_t[:]
+    max_bin: int,
+) -> np.ndarray: ...  # np.ndarray[np.int64, ndim=2]
+def get_level_sorter(
+    codes: np.ndarray,  # const int64_t[:]
+    starts: np.ndarray,  # const intp_t[:]
+) -> np.ndarray: ...  # np.ndarray[np.intp, ndim=1]
+def generate_bins_dt64(
+    values: npt.NDArray[np.int64],
+    binner: np.ndarray,  # const int64_t[:]
+    closed: object = ...,
+    hasnans: bool = ...,
+) -> np.ndarray: ...  # np.ndarray[np.int64, ndim=1]
+def array_equivalent_object(
+    left: npt.NDArray[np.object_],
+    right: npt.NDArray[np.object_],
+) -> bool: ...
+def has_infs(arr: np.ndarray) -> bool: ...  # const floating[:]
+def has_only_ints_or_nan(arr: np.ndarray) -> bool: ...  # const floating[:]
+def get_reverse_indexer(
+    indexer: np.ndarray,  # const intp_t[:]
+    length: int,
+) -> npt.NDArray[np.intp]: ...
+def is_bool_list(obj: list) -> bool: ...
+def dtypes_all_equal(types: list[DtypeObj]) -> bool: ...
+def is_range_indexer(
+    left: np.ndarray, n: int  # np.ndarray[np.int64, ndim=1]
+) -> bool: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/missing.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/missing.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..bae144ba2bff39ed6ddb06006322bcb60f78291a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/missing.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0fc8b4fac0b3ba0c7c21b023269060277a2542b0836ae2a81f1699f700232edb
+size 195376
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/missing.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/missing.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..282dcee3ed6cfdd5cd83e5c78a69c422831b4cac
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/missing.pyi
@@ -0,0 +1,16 @@
+import numpy as np
+from numpy import typing as npt
+
+class NAType:
+    def __new__(cls, *args, **kwargs): ...
+
+NA: NAType
+
+def is_matching_na(
+    left: object, right: object, nan_matches_none: bool = ...
+) -> bool: ...
+def isposinf_scalar(val: object) -> bool: ...
+def isneginf_scalar(val: object) -> bool: ...
+def checknull(val: object, inf_as_na: bool = ...) -> bool: ...
+def isnaobj(arr: np.ndarray, inf_as_na: bool = ...) -> npt.NDArray[np.bool_]: ...
+def is_numeric_na(values: np.ndarray) -> npt.NDArray[np.bool_]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/ops.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/ops.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..544251cca3e9386b16ce2990f22299d98f19bca7
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/ops.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:d5b74e500642d20ac15b3e6d61fbe2a8968585f78644a1d04f9912157fb36c7b
+size 254256
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/ops.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/ops.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..6738a1dff4a9eb272f3e6c88a31b0bd7386aebd2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/ops.pyi
@@ -0,0 +1,51 @@
+from typing import (
+    Any,
+    Callable,
+    Iterable,
+    Literal,
+    TypeAlias,
+    overload,
+)
+
+import numpy as np
+
+from pandas._typing import npt
+
+_BinOp: TypeAlias = Callable[[Any, Any], Any]
+_BoolOp: TypeAlias = Callable[[Any, Any], bool]
+
+def scalar_compare(
+    values: np.ndarray,  # object[:]
+    val: object,
+    op: _BoolOp,  # {operator.eq, operator.ne, ...}
+) -> npt.NDArray[np.bool_]: ...
+def vec_compare(
+    left: npt.NDArray[np.object_],
+    right: npt.NDArray[np.object_],
+    op: _BoolOp,  # {operator.eq, operator.ne, ...}
+) -> npt.NDArray[np.bool_]: ...
+def scalar_binop(
+    values: np.ndarray,  # object[:]
+    val: object,
+    op: _BinOp,  # binary operator
+) -> np.ndarray: ...
+def vec_binop(
+    left: np.ndarray,  # object[:]
+    right: np.ndarray,  # object[:]
+    op: _BinOp,  # binary operator
+) -> np.ndarray: ...
+@overload
+def maybe_convert_bool(
+    arr: npt.NDArray[np.object_],
+    true_values: Iterable | None = None,
+    false_values: Iterable | None = None,
+    convert_to_masked_nullable: Literal[False] = ...,
+) -> tuple[np.ndarray, None]: ...
+@overload
+def maybe_convert_bool(
+    arr: npt.NDArray[np.object_],
+    true_values: Iterable = ...,
+    false_values: Iterable = ...,
+    *,
+    convert_to_masked_nullable: Literal[True],
+) -> tuple[np.ndarray, np.ndarray]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..a28a2dfef1d9f386eb6a6db296e0a1a06ac2f605
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..91b5a4dbaaebc177191d3189f12e4e20d56ca0fa
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/ops_dispatch.pyi
@@ -0,0 +1,5 @@
+import numpy as np
+
+def maybe_dispatch_ufunc_to_dunder_op(
+    self, ufunc: np.ufunc, method: str, *inputs, **kwargs
+): ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_datetime.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_datetime.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..7bf3a108b9292f6720047bc9d4e514d5993400ca
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_datetime.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_parser.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_parser.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..583857681bddb22586c44b4a6b8f6078284f8b50
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/pandas_parser.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..9d80ce26188f361b6e05d46d918b44667aa062ee
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:bc79b0c8c1f0abcfe82d5b9bd50f85e46dd25748de546563674d810b49efaf0a
+size 558080
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..253bb7303cefb81f61692c8d7bd9812a191d9ac5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/parsers.pyi
@@ -0,0 +1,77 @@
+from typing import (
+    Hashable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._typing import (
+    ArrayLike,
+    Dtype,
+    npt,
+)
+
+STR_NA_VALUES: set[str]
+DEFAULT_BUFFER_HEURISTIC: int
+
+def sanitize_objects(
+    values: npt.NDArray[np.object_],
+    na_values: set,
+) -> int: ...
+
+class TextReader:
+    unnamed_cols: set[str]
+    table_width: int  # int64_t
+    leading_cols: int  # int64_t
+    header: list[list[int]]  # non-negative integers
+    def __init__(
+        self,
+        source,
+        delimiter: bytes | str = ...,  # single-character only
+        header=...,
+        header_start: int = ...,  # int64_t
+        header_end: int = ...,  # uint64_t
+        index_col=...,
+        names=...,
+        tokenize_chunksize: int = ...,  # int64_t
+        delim_whitespace: bool = ...,
+        converters=...,
+        skipinitialspace: bool = ...,
+        escapechar: bytes | str | None = ...,  # single-character only
+        doublequote: bool = ...,
+        quotechar: str | bytes | None = ...,  # at most 1 character
+        quoting: int = ...,
+        lineterminator: bytes | str | None = ...,  # at most 1 character
+        comment=...,
+        decimal: bytes | str = ...,  # single-character only
+        thousands: bytes | str | None = ...,  # single-character only
+        dtype: Dtype | dict[Hashable, Dtype] = ...,
+        usecols=...,
+        error_bad_lines: bool = ...,
+        warn_bad_lines: bool = ...,
+        na_filter: bool = ...,
+        na_values=...,
+        na_fvalues=...,
+        keep_default_na: bool = ...,
+        true_values=...,
+        false_values=...,
+        allow_leading_cols: bool = ...,
+        skiprows=...,
+        skipfooter: int = ...,  # int64_t
+        verbose: bool = ...,
+        float_precision: Literal["round_trip", "legacy", "high"] | None = ...,
+        skip_blank_lines: bool = ...,
+        encoding_errors: bytes | str = ...,
+    ) -> None: ...
+    def set_noconvert(self, i: int) -> None: ...
+    def remove_noconvert(self, i: int) -> None: ...
+    def close(self) -> None: ...
+    def read(self, rows: int | None = ...) -> dict[int, ArrayLike]: ...
+    def read_low_memory(self, rows: int | None) -> list[dict[int, ArrayLike]]: ...
+
+# _maybe_upcast, na_values are only exposed for testing
+na_values: dict
+
+def _maybe_upcast(
+    arr, use_dtype_backend: bool = ..., dtype_backend: str = ...
+) -> np.ndarray: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/properties.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/properties.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..247498ff0ad14bcfc48d8a99d73161b7bfab6ca3
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/properties.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/properties.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/properties.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..aaa44a0cf47bf8635727ea9f354227de72bbff29
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/properties.pyi
@@ -0,0 +1,27 @@
+from typing import (
+    Sequence,
+    overload,
+)
+
+from pandas._typing import (
+    AnyArrayLike,
+    DataFrame,
+    Index,
+    Series,
+)
+
+# note: this is a lie to make type checkers happy (they special
+# case property). cache_readonly uses attribute names similar to
+# property (fget) but it does not provide fset and fdel.
+cache_readonly = property
+
+class AxisProperty:
+    axis: int
+    def __init__(self, axis: int = ..., doc: str = ...) -> None: ...
+    @overload
+    def __get__(self, obj: DataFrame | Series, type) -> Index: ...
+    @overload
+    def __get__(self, obj: None, type) -> AxisProperty: ...
+    def __set__(
+        self, obj: DataFrame | Series, value: AnyArrayLike | Sequence
+    ) -> None: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..6527f7fe92afdd997a50fe0c6c35704fafb06c4a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:57478d4e2098174f7743f90f851cbccb1ea46055f33511f77b81a198d77ab955
+size 312784
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..110687fcd0c313c45e8b025083fa5790fb9913b1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/reshape.pyi
@@ -0,0 +1,16 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def unstack(
+    values: np.ndarray,  # reshape_t[:, :]
+    mask: np.ndarray,  # const uint8_t[:]
+    stride: int,
+    length: int,
+    width: int,
+    new_values: np.ndarray,  # reshape_t[:, :]
+    new_mask: np.ndarray,  # uint8_t[:, :]
+) -> None: ...
+def explode(
+    values: npt.NDArray[np.object_],
+) -> tuple[npt.NDArray[np.object_], npt.NDArray[np.int64]]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/sas.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/sas.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..49c3e3da697d02443f92c3ed491d29fcd645a47d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/sas.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:3e04d83a6b5f3f374e16f3cbd8e7797af0d723e43c1090e957fadd5b83fc9b48
+size 262896
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/sas.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/sas.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..5d65e2b56b5916ed1e76e1409e4f75c652ee8fc9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/sas.pyi
@@ -0,0 +1,7 @@
+from pandas.io.sas.sas7bdat import SAS7BDATReader
+
+class Parser:
+    def __init__(self, parser: SAS7BDATReader) -> None: ...
+    def read(self, nrows: int) -> None: ...
+
+def get_subheader_index(signature: bytes) -> int: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..9db81cf10bceca6f30f2d6a5a88cf9f064153441
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:307f805a82a1a3483345c4d4ea7800c96d6b0b0a05dcc84069b3346eb3b07d4a
+size 951504
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..536265b25425e9e7ecabd37f095115442a7cb209
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/sparse.pyi
@@ -0,0 +1,51 @@
+from typing import Sequence
+
+import numpy as np
+
+from pandas._typing import (
+    Self,
+    npt,
+)
+
+class SparseIndex:
+    length: int
+    npoints: int
+    def __init__(self) -> None: ...
+    @property
+    def ngaps(self) -> int: ...
+    @property
+    def nbytes(self) -> int: ...
+    @property
+    def indices(self) -> npt.NDArray[np.int32]: ...
+    def equals(self, other) -> bool: ...
+    def lookup(self, index: int) -> np.int32: ...
+    def lookup_array(self, indexer: npt.NDArray[np.int32]) -> npt.NDArray[np.int32]: ...
+    def to_int_index(self) -> IntIndex: ...
+    def to_block_index(self) -> BlockIndex: ...
+    def intersect(self, y_: SparseIndex) -> Self: ...
+    def make_union(self, y_: SparseIndex) -> Self: ...
+
+class IntIndex(SparseIndex):
+    indices: npt.NDArray[np.int32]
+    def __init__(
+        self, length: int, indices: Sequence[int], check_integrity: bool = ...
+    ) -> None: ...
+
+class BlockIndex(SparseIndex):
+    nblocks: int
+    blocs: np.ndarray
+    blengths: np.ndarray
+    def __init__(
+        self, length: int, blocs: np.ndarray, blengths: np.ndarray
+    ) -> None: ...
+
+    # Override to have correct parameters
+    def intersect(self, other: SparseIndex) -> Self: ...
+    def make_union(self, y: SparseIndex) -> Self: ...
+
+def make_mask_object_ndarray(
+    arr: npt.NDArray[np.object_], fill_value
+) -> npt.NDArray[np.bool_]: ...
+def get_blocks(
+    indices: npt.NDArray[np.int32],
+) -> tuple[npt.NDArray[np.int32], npt.NDArray[np.int32]]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/testing.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/testing.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..0a238f98aaa4627c223eaa79edc277b11b229265
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/testing.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:e3b135ea41eafbbec6f90b91d0ff411942e8e90c834707d184becbd4bfd65c91
+size 115536
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/testing.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/testing.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..01da496975f512b204defb06fcd19a36e235f97a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/testing.pyi
@@ -0,0 +1,12 @@
+def assert_dict_equal(a, b, compare_keys: bool = ...): ...
+def assert_almost_equal(
+    a,
+    b,
+    rtol: float = ...,
+    atol: float = ...,
+    check_dtype: bool = ...,
+    obj=...,
+    lobj=...,
+    robj=...,
+    index_values=...,
+): ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..c3f9b1cc43c4f1408a24305f57c88f51708a6627
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5099213422ab8eea17c7e137c5c1cb375e7ab5e3c8f672d160b342cd36bee53b
+size 332624
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..5a340c1d88bc439663c2e482c9eb7270f8ebc5c6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslib.pyi
@@ -0,0 +1,37 @@
+from datetime import tzinfo
+
+import numpy as np
+
+from pandas._typing import npt
+
+def format_array_from_datetime(
+    values: npt.NDArray[np.int64],
+    tz: tzinfo | None = ...,
+    format: str | None = ...,
+    na_rep: str | float = ...,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.object_]: ...
+def array_with_unit_to_datetime(
+    values: npt.NDArray[np.object_],
+    unit: str,
+    errors: str = ...,
+) -> tuple[np.ndarray, tzinfo | None]: ...
+def first_non_null(values: np.ndarray) -> int: ...
+def array_to_datetime(
+    values: npt.NDArray[np.object_],
+    errors: str = ...,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    utc: bool = ...,
+    creso: int = ...,
+) -> tuple[np.ndarray, tzinfo | None]: ...
+
+# returned ndarray may be object dtype or datetime64[ns]
+
+def array_to_datetime_with_tz(
+    values: npt.NDArray[np.object_],
+    tz: tzinfo,
+    dayfirst: bool,
+    yearfirst: bool,
+    creso: int,
+) -> npt.NDArray[np.int64]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/__init__.py b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..88a9a259ac8ec87255b25b3e15375b1c92099999
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/__init__.py
@@ -0,0 +1,87 @@
+__all__ = [
+    "dtypes",
+    "localize_pydatetime",
+    "NaT",
+    "NaTType",
+    "iNaT",
+    "nat_strings",
+    "OutOfBoundsDatetime",
+    "OutOfBoundsTimedelta",
+    "IncompatibleFrequency",
+    "Period",
+    "Resolution",
+    "Timedelta",
+    "normalize_i8_timestamps",
+    "is_date_array_normalized",
+    "dt64arr_to_periodarr",
+    "delta_to_nanoseconds",
+    "ints_to_pydatetime",
+    "ints_to_pytimedelta",
+    "get_resolution",
+    "Timestamp",
+    "tz_convert_from_utc_single",
+    "tz_convert_from_utc",
+    "to_offset",
+    "Tick",
+    "BaseOffset",
+    "tz_compare",
+    "is_unitless",
+    "astype_overflowsafe",
+    "get_unit_from_dtype",
+    "periods_per_day",
+    "periods_per_second",
+    "guess_datetime_format",
+    "add_overflowsafe",
+    "get_supported_dtype",
+    "is_supported_dtype",
+]
+
+from pandas._libs.tslibs import dtypes  # pylint: disable=import-self
+from pandas._libs.tslibs.conversion import localize_pydatetime
+from pandas._libs.tslibs.dtypes import (
+    Resolution,
+    periods_per_day,
+    periods_per_second,
+)
+from pandas._libs.tslibs.nattype import (
+    NaT,
+    NaTType,
+    iNaT,
+    nat_strings,
+)
+from pandas._libs.tslibs.np_datetime import (
+    OutOfBoundsDatetime,
+    OutOfBoundsTimedelta,
+    add_overflowsafe,
+    astype_overflowsafe,
+    get_supported_dtype,
+    is_supported_dtype,
+    is_unitless,
+    py_get_unit_from_dtype as get_unit_from_dtype,
+)
+from pandas._libs.tslibs.offsets import (
+    BaseOffset,
+    Tick,
+    to_offset,
+)
+from pandas._libs.tslibs.parsing import guess_datetime_format
+from pandas._libs.tslibs.period import (
+    IncompatibleFrequency,
+    Period,
+)
+from pandas._libs.tslibs.timedeltas import (
+    Timedelta,
+    delta_to_nanoseconds,
+    ints_to_pytimedelta,
+)
+from pandas._libs.tslibs.timestamps import Timestamp
+from pandas._libs.tslibs.timezones import tz_compare
+from pandas._libs.tslibs.tzconversion import tz_convert_from_utc_single
+from pandas._libs.tslibs.vectorized import (
+    dt64arr_to_periodarr,
+    get_resolution,
+    ints_to_pydatetime,
+    is_date_array_normalized,
+    normalize_i8_timestamps,
+    tz_convert_from_utc,
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/base.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/base.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..6bf183cba12921482828c6dfd0613894f60f32de
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/base.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..8e1690c228b9bbe5f27b0ed9268a3663810f3358
Binary files /dev/null and b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.cpython-313-x86_64-linux-gnu.so differ
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..993f18a61d74aaa643e9790df70ede618b917223
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/ccalendar.pyi
@@ -0,0 +1,12 @@
+DAYS: list[str]
+MONTH_ALIASES: dict[int, str]
+MONTH_NUMBERS: dict[str, int]
+MONTHS: list[str]
+int_to_weekday: dict[int, str]
+
+def get_firstbday(year: int, month: int) -> int: ...
+def get_lastbday(year: int, month: int) -> int: ...
+def get_day_of_year(year: int, month: int, day: int) -> int: ...
+def get_iso_calendar(year: int, month: int, day: int) -> tuple[int, int, int]: ...
+def get_week_of_year(year: int, month: int, day: int) -> int: ...
+def get_days_in_month(year: int, month: int) -> int: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..f362331489a1d17419c55dc719cdf2ebf3ad3002
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5c927964adc62ac1b84095a69c973ee8c3f64876f98f8d82986863fafa4e4b3e
+size 296048
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..26affae577f4d3f4ecda2ac9c1bc0cb748a35d4d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/conversion.pyi
@@ -0,0 +1,14 @@
+from datetime import (
+    datetime,
+    tzinfo,
+)
+
+import numpy as np
+
+DT64NS_DTYPE: np.dtype
+TD64NS_DTYPE: np.dtype
+
+def localize_pydatetime(dt: datetime, tz: tzinfo | None) -> datetime: ...
+def cast_from_unit_vectorized(
+    values: np.ndarray, unit: str, out_unit: str = ...
+) -> np.ndarray: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..7fc3d474e7e7826e75128126b43e250c30572d6a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:7d23a243ebb4a4f1379910802d6ff9716b9ce4a502fb9be92ec4f0d9bf972c56
+size 186608
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..7fdeb88d498ac88b6d023e25409e8f756b12c07a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/dtypes.pyi
@@ -0,0 +1,83 @@
+from enum import Enum
+
+OFFSET_TO_PERIOD_FREQSTR: dict[str, str]
+
+def periods_per_day(reso: int = ...) -> int: ...
+def periods_per_second(reso: int) -> int: ...
+def abbrev_to_npy_unit(abbrev: str | None) -> int: ...
+def freq_to_period_freqstr(freq_n: int, freq_name: str) -> str: ...
+
+class PeriodDtypeBase:
+    _dtype_code: int  # PeriodDtypeCode
+    _n: int
+
+    # actually __cinit__
+    def __new__(cls, code: int, n: int): ...
+    @property
+    def _freq_group_code(self) -> int: ...
+    @property
+    def _resolution_obj(self) -> Resolution: ...
+    def _get_to_timestamp_base(self) -> int: ...
+    @property
+    def _freqstr(self) -> str: ...
+    def __hash__(self) -> int: ...
+    def _is_tick_like(self) -> bool: ...
+    @property
+    def _creso(self) -> int: ...
+    @property
+    def _td64_unit(self) -> str: ...
+
+class FreqGroup(Enum):
+    FR_ANN: int
+    FR_QTR: int
+    FR_MTH: int
+    FR_WK: int
+    FR_BUS: int
+    FR_DAY: int
+    FR_HR: int
+    FR_MIN: int
+    FR_SEC: int
+    FR_MS: int
+    FR_US: int
+    FR_NS: int
+    FR_UND: int
+    @staticmethod
+    def from_period_dtype_code(code: int) -> FreqGroup: ...
+
+class Resolution(Enum):
+    RESO_NS: int
+    RESO_US: int
+    RESO_MS: int
+    RESO_SEC: int
+    RESO_MIN: int
+    RESO_HR: int
+    RESO_DAY: int
+    RESO_MTH: int
+    RESO_QTR: int
+    RESO_YR: int
+    def __lt__(self, other: Resolution) -> bool: ...
+    def __ge__(self, other: Resolution) -> bool: ...
+    @property
+    def attrname(self) -> str: ...
+    @classmethod
+    def from_attrname(cls, attrname: str) -> Resolution: ...
+    @classmethod
+    def get_reso_from_freqstr(cls, freq: str) -> Resolution: ...
+    @property
+    def attr_abbrev(self) -> str: ...
+
+class NpyDatetimeUnit(Enum):
+    NPY_FR_Y: int
+    NPY_FR_M: int
+    NPY_FR_W: int
+    NPY_FR_D: int
+    NPY_FR_h: int
+    NPY_FR_m: int
+    NPY_FR_s: int
+    NPY_FR_ms: int
+    NPY_FR_us: int
+    NPY_FR_ns: int
+    NPY_FR_ps: int
+    NPY_FR_fs: int
+    NPY_FR_as: int
+    NPY_FR_GENERIC: int
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..1a96b068d7449c804eb99a736b1cdb2bda1586b0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:0cd471890b6a2cadf54a5536e7e0ee110cfaae674a94b5ba4215d5770a273090
+size 336944
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..c6cfd44e9f6ab76ee4bc3be7c765569991514d18
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/fields.pyi
@@ -0,0 +1,62 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def build_field_sarray(
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
+    reso: int,  # NPY_DATETIMEUNIT
+) -> np.ndarray: ...
+def month_position_check(fields, weekdays) -> str | None: ...
+def get_date_name_field(
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
+    field: str,
+    locale: str | None = ...,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.object_]: ...
+def get_start_end_field(
+    dtindex: npt.NDArray[np.int64],
+    field: str,
+    freqstr: str | None = ...,
+    month_kw: int = ...,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.bool_]: ...
+def get_date_field(
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
+    field: str,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int32]: ...
+def get_timedelta_field(
+    tdindex: npt.NDArray[np.int64],  # const int64_t[:]
+    field: str,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int32]: ...
+def get_timedelta_days(
+    tdindex: npt.NDArray[np.int64],  # const int64_t[:]
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int64]: ...
+def isleapyear_arr(
+    years: np.ndarray,
+) -> npt.NDArray[np.bool_]: ...
+def build_isocalendar_sarray(
+    dtindex: npt.NDArray[np.int64],  # const int64_t[:]
+    reso: int,  # NPY_DATETIMEUNIT
+) -> np.ndarray: ...
+def _get_locale_names(name_type: str, locale: str | None = ...): ...
+
+class RoundTo:
+    @property
+    def MINUS_INFTY(self) -> int: ...
+    @property
+    def PLUS_INFTY(self) -> int: ...
+    @property
+    def NEAREST_HALF_EVEN(self) -> int: ...
+    @property
+    def NEAREST_HALF_PLUS_INFTY(self) -> int: ...
+    @property
+    def NEAREST_HALF_MINUS_INFTY(self) -> int: ...
+
+def round_nsint64(
+    values: npt.NDArray[np.int64],
+    mode: RoundTo,
+    nanos: int,
+) -> npt.NDArray[np.int64]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..6ffdf450bd864f10385ba9dccba7617ae706ae9e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:66ed812a0d4360eb2103e515775638e8b6b594e828b6bb5e6b0e6e14ef8a1bc1
+size 221360
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..bd86a6fdc2174a38bdd0845019e0afd6f2aecbf1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/nattype.pyi
@@ -0,0 +1,141 @@
+from datetime import (
+    datetime,
+    timedelta,
+    tzinfo as _tzinfo,
+)
+import typing
+
+import numpy as np
+
+from pandas._libs.tslibs.period import Period
+from pandas._typing import Self
+
+NaT: NaTType
+iNaT: int
+nat_strings: set[str]
+
+_NaTComparisonTypes: typing.TypeAlias = (
+    datetime | timedelta | Period | np.datetime64 | np.timedelta64
+)
+
+class _NatComparison:
+    def __call__(self, other: _NaTComparisonTypes) -> bool: ...
+
+class NaTType:
+    _value: np.int64
+    @property
+    def value(self) -> int: ...
+    @property
+    def asm8(self) -> np.datetime64: ...
+    def to_datetime64(self) -> np.datetime64: ...
+    def to_numpy(
+        self, dtype: np.dtype | str | None = ..., copy: bool = ...
+    ) -> np.datetime64 | np.timedelta64: ...
+    @property
+    def is_leap_year(self) -> bool: ...
+    @property
+    def is_month_start(self) -> bool: ...
+    @property
+    def is_quarter_start(self) -> bool: ...
+    @property
+    def is_year_start(self) -> bool: ...
+    @property
+    def is_month_end(self) -> bool: ...
+    @property
+    def is_quarter_end(self) -> bool: ...
+    @property
+    def is_year_end(self) -> bool: ...
+    @property
+    def day_of_year(self) -> float: ...
+    @property
+    def dayofyear(self) -> float: ...
+    @property
+    def days_in_month(self) -> float: ...
+    @property
+    def daysinmonth(self) -> float: ...
+    @property
+    def day_of_week(self) -> float: ...
+    @property
+    def dayofweek(self) -> float: ...
+    @property
+    def week(self) -> float: ...
+    @property
+    def weekofyear(self) -> float: ...
+    def day_name(self) -> float: ...
+    def month_name(self) -> float: ...
+    def weekday(self) -> float: ...
+    def isoweekday(self) -> float: ...
+    def total_seconds(self) -> float: ...
+    def today(self, *args, **kwargs) -> NaTType: ...
+    def now(self, *args, **kwargs) -> NaTType: ...
+    def to_pydatetime(self) -> NaTType: ...
+    def date(self) -> NaTType: ...
+    def round(self) -> NaTType: ...
+    def floor(self) -> NaTType: ...
+    def ceil(self) -> NaTType: ...
+    @property
+    def tzinfo(self) -> None: ...
+    @property
+    def tz(self) -> None: ...
+    def tz_convert(self, tz: _tzinfo | str | None) -> NaTType: ...
+    def tz_localize(
+        self,
+        tz: _tzinfo | str | None,
+        ambiguous: str = ...,
+        nonexistent: str = ...,
+    ) -> NaTType: ...
+    def replace(
+        self,
+        year: int | None = ...,
+        month: int | None = ...,
+        day: int | None = ...,
+        hour: int | None = ...,
+        minute: int | None = ...,
+        second: int | None = ...,
+        microsecond: int | None = ...,
+        nanosecond: int | None = ...,
+        tzinfo: _tzinfo | None = ...,
+        fold: int | None = ...,
+    ) -> NaTType: ...
+    @property
+    def year(self) -> float: ...
+    @property
+    def quarter(self) -> float: ...
+    @property
+    def month(self) -> float: ...
+    @property
+    def day(self) -> float: ...
+    @property
+    def hour(self) -> float: ...
+    @property
+    def minute(self) -> float: ...
+    @property
+    def second(self) -> float: ...
+    @property
+    def millisecond(self) -> float: ...
+    @property
+    def microsecond(self) -> float: ...
+    @property
+    def nanosecond(self) -> float: ...
+    # inject Timedelta properties
+    @property
+    def days(self) -> float: ...
+    @property
+    def microseconds(self) -> float: ...
+    @property
+    def nanoseconds(self) -> float: ...
+    # inject Period properties
+    @property
+    def qyear(self) -> float: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    __lt__: _NatComparison
+    __le__: _NatComparison
+    __gt__: _NatComparison
+    __ge__: _NatComparison
+    def __sub__(self, other: Self | timedelta | datetime) -> Self: ...
+    def __rsub__(self, other: Self | timedelta | datetime) -> Self: ...
+    def __add__(self, other: Self | timedelta | datetime) -> Self: ...
+    def __radd__(self, other: Self | timedelta | datetime) -> Self: ...
+    def __hash__(self) -> int: ...
+    def as_unit(self, unit: str, round_ok: bool = ...) -> NaTType: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..74052ea098aea2c26cf4c8f3155a70a4607f668e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:29381d49a0ff2d910f85761923c09d3c2a8c2856b536484cca5b910400edc6e8
+size 136144
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..00ef35c50e53251d5ca6f6c6d5ad28a67a695a21
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/np_datetime.pyi
@@ -0,0 +1,27 @@
+import numpy as np
+
+from pandas._typing import npt
+
+class OutOfBoundsDatetime(ValueError): ...
+class OutOfBoundsTimedelta(ValueError): ...
+
+# only exposed for testing
+def py_get_unit_from_dtype(dtype: np.dtype): ...
+def py_td64_to_tdstruct(td64: int, unit: int) -> dict: ...
+def astype_overflowsafe(
+    values: np.ndarray,
+    dtype: np.dtype,
+    copy: bool = ...,
+    round_ok: bool = ...,
+    is_coerce: bool = ...,
+) -> np.ndarray: ...
+def is_unitless(dtype: np.dtype) -> bool: ...
+def compare_mismatched_resolutions(
+    left: np.ndarray, right: np.ndarray, op
+) -> npt.NDArray[np.bool_]: ...
+def add_overflowsafe(
+    left: npt.NDArray[np.int64],
+    right: npt.NDArray[np.int64],
+) -> npt.NDArray[np.int64]: ...
+def get_supported_dtype(dtype: np.dtype) -> np.dtype: ...
+def is_supported_dtype(dtype: np.dtype) -> bool: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..2fb23a856e69009d7138e32a2c7e67ff8c6e385f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:a6b8947793e0607100da1fe566627e3a2c9488f8822baeac2b9a396642738736
+size 1061376
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..7eb8dc0813868de9ca96c086f5506619719937f4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/offsets.pyi
@@ -0,0 +1,287 @@
+from datetime import (
+    datetime,
+    time,
+    timedelta,
+)
+from typing import (
+    Any,
+    Collection,
+    Literal,
+    TypeVar,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs.nattype import NaTType
+from pandas._typing import (
+    OffsetCalendar,
+    Self,
+    npt,
+)
+
+from .timedeltas import Timedelta
+
+_BaseOffsetT = TypeVar("_BaseOffsetT", bound=BaseOffset)
+_DatetimeT = TypeVar("_DatetimeT", bound=datetime)
+_TimedeltaT = TypeVar("_TimedeltaT", bound=timedelta)
+
+_relativedelta_kwds: set[str]
+prefix_mapping: dict[str, type]
+
+class ApplyTypeError(TypeError): ...
+
+class BaseOffset:
+    n: int
+    normalize: bool
+    def __init__(self, n: int = ..., normalize: bool = ...) -> None: ...
+    def __eq__(self, other) -> bool: ...
+    def __ne__(self, other) -> bool: ...
+    def __hash__(self) -> int: ...
+    @property
+    def kwds(self) -> dict: ...
+    @property
+    def base(self) -> BaseOffset: ...
+    @overload
+    def __add__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
+    @overload
+    def __add__(self, other: BaseOffset) -> Self: ...
+    @overload
+    def __add__(self, other: _DatetimeT) -> _DatetimeT: ...
+    @overload
+    def __add__(self, other: _TimedeltaT) -> _TimedeltaT: ...
+    @overload
+    def __radd__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
+    @overload
+    def __radd__(self, other: BaseOffset) -> Self: ...
+    @overload
+    def __radd__(self, other: _DatetimeT) -> _DatetimeT: ...
+    @overload
+    def __radd__(self, other: _TimedeltaT) -> _TimedeltaT: ...
+    @overload
+    def __radd__(self, other: NaTType) -> NaTType: ...
+    def __sub__(self, other: BaseOffset) -> Self: ...
+    @overload
+    def __rsub__(self, other: npt.NDArray[np.object_]) -> npt.NDArray[np.object_]: ...
+    @overload
+    def __rsub__(self, other: BaseOffset): ...
+    @overload
+    def __rsub__(self, other: _DatetimeT) -> _DatetimeT: ...
+    @overload
+    def __rsub__(self, other: _TimedeltaT) -> _TimedeltaT: ...
+    @overload
+    def __mul__(self, other: np.ndarray) -> np.ndarray: ...
+    @overload
+    def __mul__(self, other: int): ...
+    @overload
+    def __rmul__(self, other: np.ndarray) -> np.ndarray: ...
+    @overload
+    def __rmul__(self, other: int) -> Self: ...
+    def __neg__(self) -> Self: ...
+    def copy(self) -> Self: ...
+    @property
+    def name(self) -> str: ...
+    @property
+    def rule_code(self) -> str: ...
+    @property
+    def freqstr(self) -> str: ...
+    def _apply(self, other): ...
+    def _apply_array(self, dtarr: np.ndarray) -> np.ndarray: ...
+    def rollback(self, dt: datetime) -> datetime: ...
+    def rollforward(self, dt: datetime) -> datetime: ...
+    def is_on_offset(self, dt: datetime) -> bool: ...
+    def __setstate__(self, state) -> None: ...
+    def __getstate__(self): ...
+    @property
+    def nanos(self) -> int: ...
+    def is_anchored(self) -> bool: ...
+
+def _get_offset(name: str) -> BaseOffset: ...
+
+class SingleConstructorOffset(BaseOffset):
+    @classmethod
+    def _from_name(cls, suffix: None = ...): ...
+    def __reduce__(self): ...
+
+@overload
+def to_offset(freq: None, is_period: bool = ...) -> None: ...
+@overload
+def to_offset(freq: _BaseOffsetT, is_period: bool = ...) -> _BaseOffsetT: ...
+@overload
+def to_offset(freq: timedelta | str, is_period: bool = ...) -> BaseOffset: ...
+
+class Tick(SingleConstructorOffset):
+    _creso: int
+    _prefix: str
+    def __init__(self, n: int = ..., normalize: bool = ...) -> None: ...
+    @property
+    def delta(self) -> Timedelta: ...
+    @property
+    def nanos(self) -> int: ...
+
+def delta_to_tick(delta: timedelta) -> Tick: ...
+
+class Day(Tick): ...
+class Hour(Tick): ...
+class Minute(Tick): ...
+class Second(Tick): ...
+class Milli(Tick): ...
+class Micro(Tick): ...
+class Nano(Tick): ...
+
+class RelativeDeltaOffset(BaseOffset):
+    def __init__(self, n: int = ..., normalize: bool = ..., **kwds: Any) -> None: ...
+
+class BusinessMixin(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., offset: timedelta = ...
+    ) -> None: ...
+
+class BusinessDay(BusinessMixin): ...
+
+class BusinessHour(BusinessMixin):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        start: str | time | Collection[str | time] = ...,
+        end: str | time | Collection[str | time] = ...,
+        offset: timedelta = ...,
+    ) -> None: ...
+
+class WeekOfMonthMixin(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., weekday: int = ...
+    ) -> None: ...
+
+class YearOffset(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., month: int | None = ...
+    ) -> None: ...
+
+class BYearEnd(YearOffset): ...
+class BYearBegin(YearOffset): ...
+class YearEnd(YearOffset): ...
+class YearBegin(YearOffset): ...
+
+class QuarterOffset(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., startingMonth: int | None = ...
+    ) -> None: ...
+
+class BQuarterEnd(QuarterOffset): ...
+class BQuarterBegin(QuarterOffset): ...
+class QuarterEnd(QuarterOffset): ...
+class QuarterBegin(QuarterOffset): ...
+class MonthOffset(SingleConstructorOffset): ...
+class MonthEnd(MonthOffset): ...
+class MonthBegin(MonthOffset): ...
+class BusinessMonthEnd(MonthOffset): ...
+class BusinessMonthBegin(MonthOffset): ...
+
+class SemiMonthOffset(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., day_of_month: int | None = ...
+    ) -> None: ...
+
+class SemiMonthEnd(SemiMonthOffset): ...
+class SemiMonthBegin(SemiMonthOffset): ...
+
+class Week(SingleConstructorOffset):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., weekday: int | None = ...
+    ) -> None: ...
+
+class WeekOfMonth(WeekOfMonthMixin):
+    def __init__(
+        self, n: int = ..., normalize: bool = ..., week: int = ..., weekday: int = ...
+    ) -> None: ...
+
+class LastWeekOfMonth(WeekOfMonthMixin): ...
+
+class FY5253Mixin(SingleConstructorOffset):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        weekday: int = ...,
+        startingMonth: int = ...,
+        variation: Literal["nearest", "last"] = ...,
+    ) -> None: ...
+
+class FY5253(FY5253Mixin): ...
+
+class FY5253Quarter(FY5253Mixin):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        weekday: int = ...,
+        startingMonth: int = ...,
+        qtr_with_extra_week: int = ...,
+        variation: Literal["nearest", "last"] = ...,
+    ) -> None: ...
+
+class Easter(SingleConstructorOffset): ...
+
+class _CustomBusinessMonth(BusinessMixin):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        weekmask: str = ...,
+        holidays: list | None = ...,
+        calendar: OffsetCalendar | None = ...,
+        offset: timedelta = ...,
+    ) -> None: ...
+
+class CustomBusinessDay(BusinessDay):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        weekmask: str = ...,
+        holidays: list | None = ...,
+        calendar: OffsetCalendar | None = ...,
+        offset: timedelta = ...,
+    ) -> None: ...
+
+class CustomBusinessHour(BusinessHour):
+    def __init__(
+        self,
+        n: int = ...,
+        normalize: bool = ...,
+        weekmask: str = ...,
+        holidays: list | None = ...,
+        calendar: OffsetCalendar | None = ...,
+        start: str | time | Collection[str | time] = ...,
+        end: str | time | Collection[str | time] = ...,
+        offset: timedelta = ...,
+    ) -> None: ...
+
+class CustomBusinessMonthEnd(_CustomBusinessMonth): ...
+class CustomBusinessMonthBegin(_CustomBusinessMonth): ...
+class OffsetMeta(type): ...
+class DateOffset(RelativeDeltaOffset, metaclass=OffsetMeta): ...
+
+BDay = BusinessDay
+BMonthEnd = BusinessMonthEnd
+BMonthBegin = BusinessMonthBegin
+CBMonthEnd = CustomBusinessMonthEnd
+CBMonthBegin = CustomBusinessMonthBegin
+CDay = CustomBusinessDay
+
+def roll_qtrday(
+    other: datetime, n: int, month: int, day_opt: str, modby: int
+) -> int: ...
+
+INVALID_FREQ_ERR_MSG: Literal["Invalid frequency: {0}"]
+
+def shift_months(
+    dtindex: npt.NDArray[np.int64],
+    months: int,
+    day_opt: str | None = ...,
+    reso: int = ...,
+) -> npt.NDArray[np.int64]: ...
+
+_offset_map: dict[str, BaseOffset]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..1a40c291774e67027b58c3800757c970b6d89a95
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c32fbb600add2ace82d78c7a71d1cc4ceedd051252dca63c083712552cb07ea3
+size 432608
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..40394f915d4b0f12d3631d997c46381757152bfe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/parsing.pyi
@@ -0,0 +1,33 @@
+from datetime import datetime
+
+import numpy as np
+
+from pandas._typing import npt
+
+class DateParseError(ValueError): ...
+
+def py_parse_datetime_string(
+    date_string: str,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+) -> datetime: ...
+def parse_datetime_string_with_reso(
+    date_string: str,
+    freq: str | None = ...,
+    dayfirst: bool | None = ...,
+    yearfirst: bool | None = ...,
+) -> tuple[datetime, str]: ...
+def _does_string_look_like_datetime(py_string: str) -> bool: ...
+def quarter_to_myear(year: int, quarter: int, freq: str) -> tuple[int, int]: ...
+def try_parse_dates(
+    values: npt.NDArray[np.object_],  # object[:]
+    parser,
+) -> npt.NDArray[np.object_]: ...
+def guess_datetime_format(
+    dt_str: str,
+    dayfirst: bool | None = ...,
+) -> str | None: ...
+def concat_date_cols(
+    date_cols: tuple,
+) -> npt.NDArray[np.object_]: ...
+def get_rule_month(source: str) -> str: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..de962b10d3f9d798367b790a092505845c737d7a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:606c287dd23449368336d66ab4c7aa1c85fc8fb70e54895359b8120eae355e9f
+size 503600
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..22f3bdbe668decaac0c53cf080ae5c3f098d7a48
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/period.pyi
@@ -0,0 +1,135 @@
+from datetime import timedelta
+from typing import Literal
+
+import numpy as np
+
+from pandas._libs.tslibs.dtypes import PeriodDtypeBase
+from pandas._libs.tslibs.nattype import NaTType
+from pandas._libs.tslibs.offsets import BaseOffset
+from pandas._libs.tslibs.timestamps import Timestamp
+from pandas._typing import (
+    Frequency,
+    npt,
+)
+
+INVALID_FREQ_ERR_MSG: str
+DIFFERENT_FREQ: str
+
+class IncompatibleFrequency(ValueError): ...
+
+def periodarr_to_dt64arr(
+    periodarr: npt.NDArray[np.int64],  # const int64_t[:]
+    freq: int,
+) -> npt.NDArray[np.int64]: ...
+def period_asfreq_arr(
+    arr: npt.NDArray[np.int64],
+    freq1: int,
+    freq2: int,
+    end: bool,
+) -> npt.NDArray[np.int64]: ...
+def get_period_field_arr(
+    field: str,
+    arr: npt.NDArray[np.int64],  # const int64_t[:]
+    freq: int,
+) -> npt.NDArray[np.int64]: ...
+def from_ordinals(
+    values: npt.NDArray[np.int64],  # const int64_t[:]
+    freq: timedelta | BaseOffset | str,
+) -> npt.NDArray[np.int64]: ...
+def extract_ordinals(
+    values: npt.NDArray[np.object_],
+    freq: Frequency | int,
+) -> npt.NDArray[np.int64]: ...
+def extract_freq(
+    values: npt.NDArray[np.object_],
+) -> BaseOffset: ...
+def period_array_strftime(
+    values: npt.NDArray[np.int64],
+    dtype_code: int,
+    na_rep,
+    date_format: str | None,
+) -> npt.NDArray[np.object_]: ...
+
+# exposed for tests
+def period_asfreq(ordinal: int, freq1: int, freq2: int, end: bool) -> int: ...
+def period_ordinal(
+    y: int, m: int, d: int, h: int, min: int, s: int, us: int, ps: int, freq: int
+) -> int: ...
+def freq_to_dtype_code(freq: BaseOffset) -> int: ...
+def validate_end_alias(how: str) -> Literal["E", "S"]: ...
+
+class PeriodMixin:
+    @property
+    def end_time(self) -> Timestamp: ...
+    @property
+    def start_time(self) -> Timestamp: ...
+    def _require_matching_freq(self, other: BaseOffset, base: bool = ...) -> None: ...
+
+class Period(PeriodMixin):
+    ordinal: int  # int64_t
+    freq: BaseOffset
+    _dtype: PeriodDtypeBase
+
+    # error: "__new__" must return a class instance (got "Union[Period, NaTType]")
+    def __new__(  # type: ignore[misc]
+        cls,
+        value=...,
+        freq: int | str | BaseOffset | None = ...,
+        ordinal: int | None = ...,
+        year: int | None = ...,
+        month: int | None = ...,
+        quarter: int | None = ...,
+        day: int | None = ...,
+        hour: int | None = ...,
+        minute: int | None = ...,
+        second: int | None = ...,
+    ) -> Period | NaTType: ...
+    @classmethod
+    def _maybe_convert_freq(cls, freq) -> BaseOffset: ...
+    @classmethod
+    def _from_ordinal(cls, ordinal: int, freq: BaseOffset) -> Period: ...
+    @classmethod
+    def now(cls, freq: Frequency) -> Period: ...
+    def strftime(self, fmt: str | None) -> str: ...
+    def to_timestamp(
+        self,
+        freq: str | BaseOffset | None = ...,
+        how: str = ...,
+    ) -> Timestamp: ...
+    def asfreq(self, freq: str | BaseOffset, how: str = ...) -> Period: ...
+    @property
+    def freqstr(self) -> str: ...
+    @property
+    def is_leap_year(self) -> bool: ...
+    @property
+    def daysinmonth(self) -> int: ...
+    @property
+    def days_in_month(self) -> int: ...
+    @property
+    def qyear(self) -> int: ...
+    @property
+    def quarter(self) -> int: ...
+    @property
+    def day_of_year(self) -> int: ...
+    @property
+    def weekday(self) -> int: ...
+    @property
+    def day_of_week(self) -> int: ...
+    @property
+    def week(self) -> int: ...
+    @property
+    def weekofyear(self) -> int: ...
+    @property
+    def second(self) -> int: ...
+    @property
+    def minute(self) -> int: ...
+    @property
+    def hour(self) -> int: ...
+    @property
+    def day(self) -> int: ...
+    @property
+    def month(self) -> int: ...
+    @property
+    def year(self) -> int: ...
+    def __sub__(self, other) -> Period | BaseOffset: ...
+    def __add__(self, other) -> Period: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..b19c123dcf6fc23f1081dc596643bce18825a774
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:8b7b29a0e67108ee696381769a7fb6b4d345e41d9764ecfe2e10b575560b2c26
+size 378256
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..0ec1a1e25a2b3cfe974baebfe32d686435f73e11
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/strptime.pyi
@@ -0,0 +1,14 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def array_strptime(
+    values: npt.NDArray[np.object_],
+    fmt: str | None,
+    exact: bool = ...,
+    errors: str = ...,
+    utc: bool = ...,
+    creso: int = ...,  # NPY_DATETIMEUNIT
+) -> tuple[np.ndarray, np.ndarray]: ...
+
+# first ndarray is M8[ns], second is object ndarray of tzinfo | None
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..eaef62950b6463da97d183d784aaa43126db642a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:86faeb35c1e95b2fc9c79c0cf31a9294d340dcb1c1563fd8c61875d7bbb63e03
+size 586928
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..24ec6c8891a89a7af4042df066fec6bc9d7b0e04
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timedeltas.pyi
@@ -0,0 +1,174 @@
+from datetime import timedelta
+from typing import (
+    ClassVar,
+    Literal,
+    TypeAlias,
+    TypeVar,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import (
+    NaTType,
+    Tick,
+)
+from pandas._typing import (
+    Frequency,
+    Self,
+    npt,
+)
+
+# This should be kept consistent with the keys in the dict timedelta_abbrevs
+# in pandas/_libs/tslibs/timedeltas.pyx
+UnitChoices: TypeAlias = Literal[
+    "Y",
+    "y",
+    "M",
+    "W",
+    "w",
+    "D",
+    "d",
+    "days",
+    "day",
+    "hours",
+    "hour",
+    "hr",
+    "h",
+    "m",
+    "minute",
+    "min",
+    "minutes",
+    "T",
+    "t",
+    "s",
+    "seconds",
+    "sec",
+    "second",
+    "ms",
+    "milliseconds",
+    "millisecond",
+    "milli",
+    "millis",
+    "L",
+    "l",
+    "us",
+    "microseconds",
+    "microsecond",
+    "µs",
+    "micro",
+    "micros",
+    "u",
+    "ns",
+    "nanoseconds",
+    "nano",
+    "nanos",
+    "nanosecond",
+    "n",
+]
+_S = TypeVar("_S", bound=timedelta)
+
+def get_unit_for_round(freq, creso: int) -> int: ...
+def disallow_ambiguous_unit(unit: str | None) -> None: ...
+def ints_to_pytimedelta(
+    m8values: npt.NDArray[np.timedelta64],
+    box: bool = ...,
+) -> npt.NDArray[np.object_]: ...
+def array_to_timedelta64(
+    values: npt.NDArray[np.object_],
+    unit: str | None = ...,
+    errors: str = ...,
+) -> np.ndarray: ...  # np.ndarray[m8ns]
+def parse_timedelta_unit(unit: str | None) -> UnitChoices: ...
+def delta_to_nanoseconds(
+    delta: np.timedelta64 | timedelta | Tick,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+    round_ok: bool = ...,
+) -> int: ...
+def floordiv_object_array(
+    left: np.ndarray, right: npt.NDArray[np.object_]
+) -> np.ndarray: ...
+def truediv_object_array(
+    left: np.ndarray, right: npt.NDArray[np.object_]
+) -> np.ndarray: ...
+
+class Timedelta(timedelta):
+    _creso: int
+    min: ClassVar[Timedelta]
+    max: ClassVar[Timedelta]
+    resolution: ClassVar[Timedelta]
+    value: int  # np.int64
+    _value: int  # np.int64
+    # error: "__new__" must return a class instance (got "Union[Timestamp, NaTType]")
+    def __new__(  # type: ignore[misc]
+        cls: type[_S],
+        value=...,
+        unit: str | None = ...,
+        **kwargs: float | np.integer | np.floating,
+    ) -> _S | NaTType: ...
+    @classmethod
+    def _from_value_and_reso(cls, value: np.int64, reso: int) -> Timedelta: ...
+    @property
+    def days(self) -> int: ...
+    @property
+    def seconds(self) -> int: ...
+    @property
+    def microseconds(self) -> int: ...
+    def total_seconds(self) -> float: ...
+    def to_pytimedelta(self) -> timedelta: ...
+    def to_timedelta64(self) -> np.timedelta64: ...
+    @property
+    def asm8(self) -> np.timedelta64: ...
+    # TODO: round/floor/ceil could return NaT?
+    def round(self, freq: Frequency) -> Self: ...
+    def floor(self, freq: Frequency) -> Self: ...
+    def ceil(self, freq: Frequency) -> Self: ...
+    @property
+    def resolution_string(self) -> str: ...
+    def __add__(self, other: timedelta) -> Timedelta: ...
+    def __radd__(self, other: timedelta) -> Timedelta: ...
+    def __sub__(self, other: timedelta) -> Timedelta: ...
+    def __rsub__(self, other: timedelta) -> Timedelta: ...
+    def __neg__(self) -> Timedelta: ...
+    def __pos__(self) -> Timedelta: ...
+    def __abs__(self) -> Timedelta: ...
+    def __mul__(self, other: float) -> Timedelta: ...
+    def __rmul__(self, other: float) -> Timedelta: ...
+    # error: Signature of "__floordiv__" incompatible with supertype "timedelta"
+    @overload  # type: ignore[override]
+    def __floordiv__(self, other: timedelta) -> int: ...
+    @overload
+    def __floordiv__(self, other: float) -> Timedelta: ...
+    @overload
+    def __floordiv__(
+        self, other: npt.NDArray[np.timedelta64]
+    ) -> npt.NDArray[np.intp]: ...
+    @overload
+    def __floordiv__(
+        self, other: npt.NDArray[np.number]
+    ) -> npt.NDArray[np.timedelta64] | Timedelta: ...
+    @overload
+    def __rfloordiv__(self, other: timedelta | str) -> int: ...
+    @overload
+    def __rfloordiv__(self, other: None | NaTType) -> NaTType: ...
+    @overload
+    def __rfloordiv__(self, other: np.ndarray) -> npt.NDArray[np.timedelta64]: ...
+    @overload
+    def __truediv__(self, other: timedelta) -> float: ...
+    @overload
+    def __truediv__(self, other: float) -> Timedelta: ...
+    def __mod__(self, other: timedelta) -> Timedelta: ...
+    def __divmod__(self, other: timedelta) -> tuple[int, Timedelta]: ...
+    def __le__(self, other: timedelta) -> bool: ...
+    def __lt__(self, other: timedelta) -> bool: ...
+    def __ge__(self, other: timedelta) -> bool: ...
+    def __gt__(self, other: timedelta) -> bool: ...
+    def __hash__(self) -> int: ...
+    def isoformat(self) -> str: ...
+    def to_numpy(
+        self, dtype: npt.DTypeLike = ..., copy: bool = False
+    ) -> np.timedelta64: ...
+    def view(self, dtype: npt.DTypeLike) -> object: ...
+    @property
+    def unit(self) -> str: ...
+    def as_unit(self, unit: str, round_ok: bool = ...) -> Timedelta: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..19b6bf9d5bef6078dab4704bece39167f6ca2b25
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:9c4a7227439f17c3bd405d521c14e2e70e0d304b205a27f5982acf6ec6c76a83
+size 620384
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..c769b09d1b7a1adc4532dd367bcbc4cf522419cd
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timestamps.pyi
@@ -0,0 +1,241 @@
+from datetime import (
+    date as _date,
+    datetime,
+    time as _time,
+    timedelta,
+    tzinfo as _tzinfo,
+)
+from time import struct_time
+from typing import (
+    ClassVar,
+    Literal,
+    TypeAlias,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import (
+    BaseOffset,
+    NaTType,
+    Period,
+    Tick,
+    Timedelta,
+)
+from pandas._typing import (
+    Self,
+    TimestampNonexistent,
+)
+
+_TimeZones: TypeAlias = str | _tzinfo | None | int
+
+def integer_op_not_supported(obj: object) -> TypeError: ...
+
+class Timestamp(datetime):
+    _creso: int
+    min: ClassVar[Timestamp]
+    max: ClassVar[Timestamp]
+
+    resolution: ClassVar[Timedelta]
+    _value: int  # np.int64
+    # error: "__new__" must return a class instance (got "Union[Timestamp, NaTType]")
+    def __new__(  # type: ignore[misc]
+        cls: type[Self],
+        ts_input: np.integer | float | str | _date | datetime | np.datetime64 = ...,
+        year: int | None = ...,
+        month: int | None = ...,
+        day: int | None = ...,
+        hour: int | None = ...,
+        minute: int | None = ...,
+        second: int | None = ...,
+        microsecond: int | None = ...,
+        tzinfo: _tzinfo | None = ...,
+        *,
+        nanosecond: int | None = ...,
+        tz: _TimeZones = ...,
+        unit: str | int | None = ...,
+        fold: int | None = ...,
+    ) -> Self | NaTType: ...
+    @classmethod
+    def _from_value_and_reso(
+        cls, value: int, reso: int, tz: _TimeZones
+    ) -> Timestamp: ...
+    @property
+    def value(self) -> int: ...  # np.int64
+    @property
+    def year(self) -> int: ...
+    @property
+    def month(self) -> int: ...
+    @property
+    def day(self) -> int: ...
+    @property
+    def hour(self) -> int: ...
+    @property
+    def minute(self) -> int: ...
+    @property
+    def second(self) -> int: ...
+    @property
+    def microsecond(self) -> int: ...
+    @property
+    def nanosecond(self) -> int: ...
+    @property
+    def tzinfo(self) -> _tzinfo | None: ...
+    @property
+    def tz(self) -> _tzinfo | None: ...
+    @property
+    def fold(self) -> int: ...
+    @classmethod
+    def fromtimestamp(cls, ts: float, tz: _TimeZones = ...) -> Self: ...
+    @classmethod
+    def utcfromtimestamp(cls, ts: float) -> Self: ...
+    @classmethod
+    def today(cls, tz: _TimeZones = ...) -> Self: ...
+    @classmethod
+    def fromordinal(
+        cls,
+        ordinal: int,
+        tz: _TimeZones = ...,
+    ) -> Self: ...
+    @classmethod
+    def now(cls, tz: _TimeZones = ...) -> Self: ...
+    @classmethod
+    def utcnow(cls) -> Self: ...
+    # error: Signature of "combine" incompatible with supertype "datetime"
+    @classmethod
+    def combine(  # type: ignore[override]
+        cls, date: _date, time: _time
+    ) -> datetime: ...
+    @classmethod
+    def fromisoformat(cls, date_string: str) -> Self: ...
+    def strftime(self, format: str) -> str: ...
+    def __format__(self, fmt: str) -> str: ...
+    def toordinal(self) -> int: ...
+    def timetuple(self) -> struct_time: ...
+    def timestamp(self) -> float: ...
+    def utctimetuple(self) -> struct_time: ...
+    def date(self) -> _date: ...
+    def time(self) -> _time: ...
+    def timetz(self) -> _time: ...
+    # LSP violation: nanosecond is not present in datetime.datetime.replace
+    # and has positional args following it
+    def replace(  # type: ignore[override]
+        self,
+        year: int | None = ...,
+        month: int | None = ...,
+        day: int | None = ...,
+        hour: int | None = ...,
+        minute: int | None = ...,
+        second: int | None = ...,
+        microsecond: int | None = ...,
+        nanosecond: int | None = ...,
+        tzinfo: _tzinfo | type[object] | None = ...,
+        fold: int | None = ...,
+    ) -> Self: ...
+    # LSP violation: datetime.datetime.astimezone has a default value for tz
+    def astimezone(self, tz: _TimeZones) -> Self: ...  # type: ignore[override]
+    def ctime(self) -> str: ...
+    def isoformat(self, sep: str = ..., timespec: str = ...) -> str: ...
+    @classmethod
+    def strptime(
+        # Note: strptime is actually disabled and raises NotImplementedError
+        cls,
+        date_string: str,
+        format: str,
+    ) -> Self: ...
+    def utcoffset(self) -> timedelta | None: ...
+    def tzname(self) -> str | None: ...
+    def dst(self) -> timedelta | None: ...
+    def __le__(self, other: datetime) -> bool: ...  # type: ignore[override]
+    def __lt__(self, other: datetime) -> bool: ...  # type: ignore[override]
+    def __ge__(self, other: datetime) -> bool: ...  # type: ignore[override]
+    def __gt__(self, other: datetime) -> bool: ...  # type: ignore[override]
+    # error: Signature of "__add__" incompatible with supertype "date"/"datetime"
+    @overload  # type: ignore[override]
+    def __add__(self, other: np.ndarray) -> np.ndarray: ...
+    @overload
+    def __add__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
+    def __radd__(self, other: timedelta) -> Self: ...
+    @overload  # type: ignore[override]
+    def __sub__(self, other: datetime) -> Timedelta: ...
+    @overload
+    def __sub__(self, other: timedelta | np.timedelta64 | Tick) -> Self: ...
+    def __hash__(self) -> int: ...
+    def weekday(self) -> int: ...
+    def isoweekday(self) -> int: ...
+    # Return type "Tuple[int, int, int]" of "isocalendar" incompatible with return
+    # type "_IsoCalendarDate" in supertype "date"
+    def isocalendar(self) -> tuple[int, int, int]: ...  # type: ignore[override]
+    @property
+    def is_leap_year(self) -> bool: ...
+    @property
+    def is_month_start(self) -> bool: ...
+    @property
+    def is_quarter_start(self) -> bool: ...
+    @property
+    def is_year_start(self) -> bool: ...
+    @property
+    def is_month_end(self) -> bool: ...
+    @property
+    def is_quarter_end(self) -> bool: ...
+    @property
+    def is_year_end(self) -> bool: ...
+    def to_pydatetime(self, warn: bool = ...) -> datetime: ...
+    def to_datetime64(self) -> np.datetime64: ...
+    def to_period(self, freq: BaseOffset | str | None = None) -> Period: ...
+    def to_julian_date(self) -> np.float64: ...
+    @property
+    def asm8(self) -> np.datetime64: ...
+    def tz_convert(self, tz: _TimeZones) -> Self: ...
+    # TODO: could return NaT?
+    def tz_localize(
+        self,
+        tz: _TimeZones,
+        ambiguous: bool | Literal["raise", "NaT"] = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> Self: ...
+    def normalize(self) -> Self: ...
+    # TODO: round/floor/ceil could return NaT?
+    def round(
+        self,
+        freq: str,
+        ambiguous: bool | Literal["raise", "NaT"] = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> Self: ...
+    def floor(
+        self,
+        freq: str,
+        ambiguous: bool | Literal["raise", "NaT"] = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> Self: ...
+    def ceil(
+        self,
+        freq: str,
+        ambiguous: bool | Literal["raise", "NaT"] = ...,
+        nonexistent: TimestampNonexistent = ...,
+    ) -> Self: ...
+    def day_name(self, locale: str | None = ...) -> str: ...
+    def month_name(self, locale: str | None = ...) -> str: ...
+    @property
+    def day_of_week(self) -> int: ...
+    @property
+    def dayofweek(self) -> int: ...
+    @property
+    def day_of_year(self) -> int: ...
+    @property
+    def dayofyear(self) -> int: ...
+    @property
+    def quarter(self) -> int: ...
+    @property
+    def week(self) -> int: ...
+    def to_numpy(
+        self, dtype: np.dtype | None = ..., copy: bool = ...
+    ) -> np.datetime64: ...
+    @property
+    def _date_repr(self) -> str: ...
+    @property
+    def days_in_month(self) -> int: ...
+    @property
+    def daysinmonth(self) -> int: ...
+    @property
+    def unit(self) -> str: ...
+    def as_unit(self, unit: str, round_ok: bool = ...) -> Timestamp: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..0fe9f9812bcc785449c65accf6a252219447109e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:5ea668aae01eccd5c4d648d521a163a9b341b81d1dbe5320703ef6203b1d09b0
+size 274768
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..4e9f0c6ae6c33447ebc86d3daf5bf5cedbe5b0cb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/timezones.pyi
@@ -0,0 +1,21 @@
+from datetime import (
+    datetime,
+    tzinfo,
+)
+from typing import Callable
+
+import numpy as np
+
+# imported from dateutil.tz
+dateutil_gettz: Callable[[str], tzinfo]
+
+def tz_standardize(tz: tzinfo) -> tzinfo: ...
+def tz_compare(start: tzinfo | None, end: tzinfo | None) -> bool: ...
+def infer_tzinfo(
+    start: datetime | None,
+    end: datetime | None,
+) -> tzinfo | None: ...
+def maybe_get_tz(tz: str | int | np.int64 | tzinfo | None) -> tzinfo | None: ...
+def get_timezone(tz: tzinfo) -> tzinfo | str: ...
+def is_utc(tz: tzinfo | None) -> bool: ...
+def is_fixed_offset(tz: tzinfo) -> bool: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..d2a9e72191a0088879e80a34aed0435009349dd1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fa4362a9e655be4c0fe00ac27994f5b3e239739881be81329a5c4dc4f08b3661
+size 324816
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..2108fa0f35547191c3db683f8cc1015e5bda4abb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/tzconversion.pyi
@@ -0,0 +1,21 @@
+from datetime import (
+    timedelta,
+    tzinfo,
+)
+from typing import Iterable
+
+import numpy as np
+
+from pandas._typing import npt
+
+# tz_convert_from_utc_single exposed for testing
+def tz_convert_from_utc_single(
+    utc_val: np.int64, tz: tzinfo, creso: int = ...
+) -> np.int64: ...
+def tz_localize_to_utc(
+    vals: npt.NDArray[np.int64],
+    tz: tzinfo | None,
+    ambiguous: str | bool | Iterable[bool] | None = ...,
+    nonexistent: str | timedelta | np.timedelta64 | None = ...,
+    creso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int64]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..71c1964a3ff8b575f9cd51abb3115c3acc4d0084
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:fe628f5f23634948b6d0826c1bedd2d06df0b8e77d0d960c3be3f64e5716fd7c
+size 246384
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..de19f592da62bbeb0b3ab267039abd902d4bb854
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/tslibs/vectorized.pyi
@@ -0,0 +1,43 @@
+"""
+For cython types that cannot be represented precisely, closest-available
+python equivalents are used, and the precise types kept as adjacent comments.
+"""
+from datetime import tzinfo
+
+import numpy as np
+
+from pandas._libs.tslibs.dtypes import Resolution
+from pandas._typing import npt
+
+def dt64arr_to_periodarr(
+    stamps: npt.NDArray[np.int64],
+    freq: int,
+    tz: tzinfo | None,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int64]: ...
+def is_date_array_normalized(
+    stamps: npt.NDArray[np.int64],
+    tz: tzinfo | None,
+    reso: int,  # NPY_DATETIMEUNIT
+) -> bool: ...
+def normalize_i8_timestamps(
+    stamps: npt.NDArray[np.int64],
+    tz: tzinfo | None,
+    reso: int,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int64]: ...
+def get_resolution(
+    stamps: npt.NDArray[np.int64],
+    tz: tzinfo | None = ...,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> Resolution: ...
+def ints_to_pydatetime(
+    stamps: npt.NDArray[np.int64],
+    tz: tzinfo | None = ...,
+    box: str = ...,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.object_]: ...
+def tz_convert_from_utc(
+    stamps: npt.NDArray[np.int64],
+    tz: tzinfo | None,
+    reso: int = ...,  # NPY_DATETIMEUNIT
+) -> npt.NDArray[np.int64]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/window/__init__.py b/.venv/lib/python3.13/site-packages/pandas/_libs/window/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..00ff7932a146041682b194c3fea76feb40cc166d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:f8620a56b7bbdfb72feb0d97f97ea84e254b84643b16930f22663b2abbbebc02
+size 410984
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..a6cfbec9b15b9aa13a15dab3ff35b0d8761f1036
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/window/aggregations.pyi
@@ -0,0 +1,127 @@
+from typing import (
+    Any,
+    Callable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._typing import (
+    WindowingRankType,
+    npt,
+)
+
+def roll_sum(
+    values: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_mean(
+    values: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_var(
+    values: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+    ddof: int = ...,
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_skew(
+    values: np.ndarray,  # np.ndarray[np.float64]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_kurt(
+    values: np.ndarray,  # np.ndarray[np.float64]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_median_c(
+    values: np.ndarray,  # np.ndarray[np.float64]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_max(
+    values: np.ndarray,  # np.ndarray[np.float64]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_min(
+    values: np.ndarray,  # np.ndarray[np.float64]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_quantile(
+    values: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+    quantile: float,  # float64_t
+    interpolation: Literal["linear", "lower", "higher", "nearest", "midpoint"],
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_rank(
+    values: np.ndarray,
+    start: np.ndarray,
+    end: np.ndarray,
+    minp: int,
+    percentile: bool,
+    method: WindowingRankType,
+    ascending: bool,
+) -> np.ndarray: ...  # np.ndarray[float]
+def roll_apply(
+    obj: object,
+    start: np.ndarray,  # np.ndarray[np.int64]
+    end: np.ndarray,  # np.ndarray[np.int64]
+    minp: int,  # int64_t
+    function: Callable[..., Any],
+    raw: bool,
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> npt.NDArray[np.float64]: ...
+def roll_weighted_sum(
+    values: np.ndarray,  # const float64_t[:]
+    weights: np.ndarray,  # const float64_t[:]
+    minp: int,
+) -> np.ndarray: ...  # np.ndarray[np.float64]
+def roll_weighted_mean(
+    values: np.ndarray,  # const float64_t[:]
+    weights: np.ndarray,  # const float64_t[:]
+    minp: int,
+) -> np.ndarray: ...  # np.ndarray[np.float64]
+def roll_weighted_var(
+    values: np.ndarray,  # const float64_t[:]
+    weights: np.ndarray,  # const float64_t[:]
+    minp: int,  # int64_t
+    ddof: int,  # unsigned int
+) -> np.ndarray: ...  # np.ndarray[np.float64]
+def ewm(
+    vals: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # const int64_t[:]
+    end: np.ndarray,  # const int64_t[:]
+    minp: int,
+    com: float,  # float64_t
+    adjust: bool,
+    ignore_na: bool,
+    deltas: np.ndarray | None = None,  # const float64_t[:]
+    normalize: bool = True,
+) -> np.ndarray: ...  # np.ndarray[np.float64]
+def ewmcov(
+    input_x: np.ndarray,  # const float64_t[:]
+    start: np.ndarray,  # const int64_t[:]
+    end: np.ndarray,  # const int64_t[:]
+    minp: int,
+    input_y: np.ndarray,  # const float64_t[:]
+    com: float,  # float64_t
+    adjust: bool,
+    ignore_na: bool,
+    bias: bool,
+) -> np.ndarray: ...  # np.ndarray[np.float64]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..7a4b24daa6b42f4d7daac8a88c72a18fae40b496
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c791e77817cc549508102e8fd90779fd7224ae4842e9d9004b5734f6f4d52c40
+size 209008
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..c9bc64be34ac9a41d14fef33b0fc76bdf66527e9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/window/indexers.pyi
@@ -0,0 +1,12 @@
+import numpy as np
+
+from pandas._typing import npt
+
+def calculate_variable_window_bounds(
+    num_values: int,  # int64_t
+    window_size: int,  # int64_t
+    min_periods,
+    center: bool,
+    closed: str | None,
+    index: np.ndarray,  # const int64_t[:]
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/writers.cpython-313-x86_64-linux-gnu.so b/.venv/lib/python3.13/site-packages/pandas/_libs/writers.cpython-313-x86_64-linux-gnu.so
new file mode 100644
index 0000000000000000000000000000000000000000..5234089d0bbae872f3a68227200f2c6009d0ca48
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/writers.cpython-313-x86_64-linux-gnu.so
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:04b787b78ab58ec1e327a2848c57aea1cf008ca9f4075454ec7b64253ee0a8b3
+size 247024
diff --git a/.venv/lib/python3.13/site-packages/pandas/_libs/writers.pyi b/.venv/lib/python3.13/site-packages/pandas/_libs/writers.pyi
new file mode 100644
index 0000000000000000000000000000000000000000..7b41856525dadf79a2bf4b29c7ddebfedaa880db
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_libs/writers.pyi
@@ -0,0 +1,20 @@
+import numpy as np
+
+from pandas._typing import ArrayLike
+
+def write_csv_rows(
+    data: list[ArrayLike],
+    data_index: np.ndarray,
+    nlevels: int,
+    cols: np.ndarray,
+    writer: object,  # _csv.writer
+) -> None: ...
+def convert_json_to_lines(arr: str) -> str: ...
+def max_len_string_array(
+    arr: np.ndarray,  # pandas_string[:]
+) -> int: ...
+def word_len(val: object) -> int: ...
+def string_array_replace_from_nan_rep(
+    arr: np.ndarray,  # np.ndarray[object, ndim=1]
+    nan_rep: object,
+) -> None: ...
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/__init__.py b/.venv/lib/python3.13/site-packages/pandas/_testing/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..d7197f23ce1e4981fd7dcea5bdc4f8db8810f277
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/__init__.py
@@ -0,0 +1,635 @@
+from __future__ import annotations
+
+from decimal import Decimal
+import operator
+import os
+from sys import byteorder
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    ContextManager,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+from pandas._config.localization import (
+    can_set_locale,
+    get_locales,
+    set_locale,
+)
+
+from pandas.compat import pa_version_under10p1
+
+import pandas as pd
+from pandas import (
+    ArrowDtype,
+    DataFrame,
+    Index,
+    MultiIndex,
+    RangeIndex,
+    Series,
+)
+from pandas._testing._io import (
+    round_trip_localpath,
+    round_trip_pathlib,
+    round_trip_pickle,
+    write_to_compressed,
+)
+from pandas._testing._warnings import (
+    assert_produces_warning,
+    maybe_produces_warning,
+)
+from pandas._testing.asserters import (
+    assert_almost_equal,
+    assert_attr_equal,
+    assert_categorical_equal,
+    assert_class_equal,
+    assert_contains_all,
+    assert_copy,
+    assert_datetime_array_equal,
+    assert_dict_equal,
+    assert_equal,
+    assert_extension_array_equal,
+    assert_frame_equal,
+    assert_index_equal,
+    assert_indexing_slices_equivalent,
+    assert_interval_array_equal,
+    assert_is_sorted,
+    assert_is_valid_plot_return_object,
+    assert_metadata_equivalent,
+    assert_numpy_array_equal,
+    assert_period_array_equal,
+    assert_series_equal,
+    assert_sp_array_equal,
+    assert_timedelta_array_equal,
+    raise_assert_detail,
+)
+from pandas._testing.compat import (
+    get_dtype,
+    get_obj,
+)
+from pandas._testing.contexts import (
+    assert_cow_warning,
+    decompress_file,
+    ensure_clean,
+    raises_chained_assignment_error,
+    set_timezone,
+    use_numexpr,
+    with_csv_dialect,
+)
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    BaseMaskedArray,
+    NumpyExtensionArray,
+)
+from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+from pandas.core.construction import extract_array
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Dtype,
+        NpDtype,
+    )
+
+
+UNSIGNED_INT_NUMPY_DTYPES: list[NpDtype] = ["uint8", "uint16", "uint32", "uint64"]
+UNSIGNED_INT_EA_DTYPES: list[Dtype] = ["UInt8", "UInt16", "UInt32", "UInt64"]
+SIGNED_INT_NUMPY_DTYPES: list[NpDtype] = [int, "int8", "int16", "int32", "int64"]
+SIGNED_INT_EA_DTYPES: list[Dtype] = ["Int8", "Int16", "Int32", "Int64"]
+ALL_INT_NUMPY_DTYPES = UNSIGNED_INT_NUMPY_DTYPES + SIGNED_INT_NUMPY_DTYPES
+ALL_INT_EA_DTYPES = UNSIGNED_INT_EA_DTYPES + SIGNED_INT_EA_DTYPES
+ALL_INT_DTYPES: list[Dtype] = [*ALL_INT_NUMPY_DTYPES, *ALL_INT_EA_DTYPES]
+
+FLOAT_NUMPY_DTYPES: list[NpDtype] = [float, "float32", "float64"]
+FLOAT_EA_DTYPES: list[Dtype] = ["Float32", "Float64"]
+ALL_FLOAT_DTYPES: list[Dtype] = [*FLOAT_NUMPY_DTYPES, *FLOAT_EA_DTYPES]
+
+COMPLEX_DTYPES: list[Dtype] = [complex, "complex64", "complex128"]
+if using_string_dtype():
+    STRING_DTYPES: list[Dtype] = ["U"]
+else:
+    STRING_DTYPES: list[Dtype] = [str, "str", "U"]  # type: ignore[no-redef]
+COMPLEX_FLOAT_DTYPES: list[Dtype] = [*COMPLEX_DTYPES, *FLOAT_NUMPY_DTYPES]
+
+DATETIME64_DTYPES: list[Dtype] = ["datetime64[ns]", "M8[ns]"]
+TIMEDELTA64_DTYPES: list[Dtype] = ["timedelta64[ns]", "m8[ns]"]
+
+BOOL_DTYPES: list[Dtype] = [bool, "bool"]
+BYTES_DTYPES: list[Dtype] = [bytes, "bytes"]
+OBJECT_DTYPES: list[Dtype] = [object, "object"]
+
+ALL_REAL_NUMPY_DTYPES = FLOAT_NUMPY_DTYPES + ALL_INT_NUMPY_DTYPES
+ALL_REAL_EXTENSION_DTYPES = FLOAT_EA_DTYPES + ALL_INT_EA_DTYPES
+ALL_REAL_DTYPES: list[Dtype] = [*ALL_REAL_NUMPY_DTYPES, *ALL_REAL_EXTENSION_DTYPES]
+ALL_NUMERIC_DTYPES: list[Dtype] = [*ALL_REAL_DTYPES, *COMPLEX_DTYPES]
+
+ALL_NUMPY_DTYPES = (
+    ALL_REAL_NUMPY_DTYPES
+    + COMPLEX_DTYPES
+    + STRING_DTYPES
+    + DATETIME64_DTYPES
+    + TIMEDELTA64_DTYPES
+    + BOOL_DTYPES
+    + OBJECT_DTYPES
+    + BYTES_DTYPES
+)
+
+NARROW_NP_DTYPES = [
+    np.float16,
+    np.float32,
+    np.int8,
+    np.int16,
+    np.int32,
+    np.uint8,
+    np.uint16,
+    np.uint32,
+]
+
+PYTHON_DATA_TYPES = [
+    str,
+    int,
+    float,
+    complex,
+    list,
+    tuple,
+    range,
+    dict,
+    set,
+    frozenset,
+    bool,
+    bytes,
+    bytearray,
+    memoryview,
+]
+
+ENDIAN = {"little": "<", "big": ">"}[byteorder]
+
+NULL_OBJECTS = [None, np.nan, pd.NaT, float("nan"), pd.NA, Decimal("NaN")]
+NP_NAT_OBJECTS = [
+    cls("NaT", unit)
+    for cls in [np.datetime64, np.timedelta64]
+    for unit in [
+        "Y",
+        "M",
+        "W",
+        "D",
+        "h",
+        "m",
+        "s",
+        "ms",
+        "us",
+        "ns",
+        "ps",
+        "fs",
+        "as",
+    ]
+]
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+
+    UNSIGNED_INT_PYARROW_DTYPES = [pa.uint8(), pa.uint16(), pa.uint32(), pa.uint64()]
+    SIGNED_INT_PYARROW_DTYPES = [pa.int8(), pa.int16(), pa.int32(), pa.int64()]
+    ALL_INT_PYARROW_DTYPES = UNSIGNED_INT_PYARROW_DTYPES + SIGNED_INT_PYARROW_DTYPES
+    ALL_INT_PYARROW_DTYPES_STR_REPR = [
+        str(ArrowDtype(typ)) for typ in ALL_INT_PYARROW_DTYPES
+    ]
+
+    # pa.float16 doesn't seem supported
+    # https://github.com/apache/arrow/blob/master/python/pyarrow/src/arrow/python/helpers.cc#L86
+    FLOAT_PYARROW_DTYPES = [pa.float32(), pa.float64()]
+    FLOAT_PYARROW_DTYPES_STR_REPR = [
+        str(ArrowDtype(typ)) for typ in FLOAT_PYARROW_DTYPES
+    ]
+    DECIMAL_PYARROW_DTYPES = [pa.decimal128(7, 3)]
+    STRING_PYARROW_DTYPES = [pa.string()]
+    BINARY_PYARROW_DTYPES = [pa.binary()]
+
+    TIME_PYARROW_DTYPES = [
+        pa.time32("s"),
+        pa.time32("ms"),
+        pa.time64("us"),
+        pa.time64("ns"),
+    ]
+    DATE_PYARROW_DTYPES = [pa.date32(), pa.date64()]
+    DATETIME_PYARROW_DTYPES = [
+        pa.timestamp(unit=unit, tz=tz)
+        for unit in ["s", "ms", "us", "ns"]
+        for tz in [None, "UTC", "US/Pacific", "US/Eastern"]
+    ]
+    TIMEDELTA_PYARROW_DTYPES = [pa.duration(unit) for unit in ["s", "ms", "us", "ns"]]
+
+    BOOL_PYARROW_DTYPES = [pa.bool_()]
+
+    # TODO: Add container like pyarrow types:
+    #  https://arrow.apache.org/docs/python/api/datatypes.html#factory-functions
+    ALL_PYARROW_DTYPES = (
+        ALL_INT_PYARROW_DTYPES
+        + FLOAT_PYARROW_DTYPES
+        + DECIMAL_PYARROW_DTYPES
+        + STRING_PYARROW_DTYPES
+        + BINARY_PYARROW_DTYPES
+        + TIME_PYARROW_DTYPES
+        + DATE_PYARROW_DTYPES
+        + DATETIME_PYARROW_DTYPES
+        + TIMEDELTA_PYARROW_DTYPES
+        + BOOL_PYARROW_DTYPES
+    )
+    ALL_REAL_PYARROW_DTYPES_STR_REPR = (
+        ALL_INT_PYARROW_DTYPES_STR_REPR + FLOAT_PYARROW_DTYPES_STR_REPR
+    )
+else:
+    FLOAT_PYARROW_DTYPES_STR_REPR = []
+    ALL_INT_PYARROW_DTYPES_STR_REPR = []
+    ALL_PYARROW_DTYPES = []
+    ALL_REAL_PYARROW_DTYPES_STR_REPR = []
+
+ALL_REAL_NULLABLE_DTYPES = (
+    FLOAT_NUMPY_DTYPES + ALL_REAL_EXTENSION_DTYPES + ALL_REAL_PYARROW_DTYPES_STR_REPR
+)
+
+arithmetic_dunder_methods = [
+    "__add__",
+    "__radd__",
+    "__sub__",
+    "__rsub__",
+    "__mul__",
+    "__rmul__",
+    "__floordiv__",
+    "__rfloordiv__",
+    "__truediv__",
+    "__rtruediv__",
+    "__pow__",
+    "__rpow__",
+    "__mod__",
+    "__rmod__",
+]
+
+comparison_dunder_methods = ["__eq__", "__ne__", "__le__", "__lt__", "__ge__", "__gt__"]
+
+
+# -----------------------------------------------------------------------------
+# Comparators
+
+
+def box_expected(expected, box_cls, transpose: bool = True):
+    """
+    Helper function to wrap the expected output of a test in a given box_class.
+
+    Parameters
+    ----------
+    expected : np.ndarray, Index, Series
+    box_cls : {Index, Series, DataFrame}
+
+    Returns
+    -------
+    subclass of box_cls
+    """
+    if box_cls is pd.array:
+        if isinstance(expected, RangeIndex):
+            # pd.array would return an IntegerArray
+            expected = NumpyExtensionArray(np.asarray(expected._values))
+        else:
+            expected = pd.array(expected, copy=False)
+    elif box_cls is Index:
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", "Dtype inference", category=FutureWarning)
+            expected = Index(expected)
+    elif box_cls is Series:
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", "Dtype inference", category=FutureWarning)
+            expected = Series(expected)
+    elif box_cls is DataFrame:
+        with warnings.catch_warnings():
+            warnings.filterwarnings("ignore", "Dtype inference", category=FutureWarning)
+            expected = Series(expected).to_frame()
+        if transpose:
+            # for vector operations, we need a DataFrame to be a single-row,
+            #  not a single-column, in order to operate against non-DataFrame
+            #  vectors of the same length. But convert to two rows to avoid
+            #  single-row special cases in datetime arithmetic
+            expected = expected.T
+            expected = pd.concat([expected] * 2, ignore_index=True)
+    elif box_cls is np.ndarray or box_cls is np.array:
+        expected = np.array(expected)
+    elif box_cls is to_array:
+        expected = to_array(expected)
+    else:
+        raise NotImplementedError(box_cls)
+    return expected
+
+
+def to_array(obj):
+    """
+    Similar to pd.array, but does not cast numpy dtypes to nullable dtypes.
+    """
+    # temporary implementation until we get pd.array in place
+    dtype = getattr(obj, "dtype", None)
+
+    if dtype is None:
+        return np.asarray(obj)
+
+    return extract_array(obj, extract_numpy=True)
+
+
+class SubclassedSeries(Series):
+    _metadata = ["testattr", "name"]
+
+    @property
+    def _constructor(self):
+        # For testing, those properties return a generic callable, and not
+        # the actual class. In this case that is equivalent, but it is to
+        # ensure we don't rely on the property returning a class
+        # See https://github.com/pandas-dev/pandas/pull/46018 and
+        # https://github.com/pandas-dev/pandas/issues/32638 and linked issues
+        return lambda *args, **kwargs: SubclassedSeries(*args, **kwargs)
+
+    @property
+    def _constructor_expanddim(self):
+        return lambda *args, **kwargs: SubclassedDataFrame(*args, **kwargs)
+
+
+class SubclassedDataFrame(DataFrame):
+    _metadata = ["testattr"]
+
+    @property
+    def _constructor(self):
+        return lambda *args, **kwargs: SubclassedDataFrame(*args, **kwargs)
+
+    @property
+    def _constructor_sliced(self):
+        return lambda *args, **kwargs: SubclassedSeries(*args, **kwargs)
+
+
+def convert_rows_list_to_csv_str(rows_list: list[str]) -> str:
+    """
+    Convert list of CSV rows to single CSV-formatted string for current OS.
+
+    This method is used for creating expected value of to_csv() method.
+
+    Parameters
+    ----------
+    rows_list : List[str]
+        Each element represents the row of csv.
+
+    Returns
+    -------
+    str
+        Expected output of to_csv() in current OS.
+    """
+    sep = os.linesep
+    return sep.join(rows_list) + sep
+
+
+def external_error_raised(expected_exception: type[Exception]) -> ContextManager:
+    """
+    Helper function to mark pytest.raises that have an external error message.
+
+    Parameters
+    ----------
+    expected_exception : Exception
+        Expected error to raise.
+
+    Returns
+    -------
+    Callable
+        Regular `pytest.raises` function with `match` equal to `None`.
+    """
+    import pytest
+
+    return pytest.raises(expected_exception, match=None)
+
+
+cython_table = pd.core.common._cython_table.items()
+
+
+def get_cython_table_params(ndframe, func_names_and_expected):
+    """
+    Combine frame, functions from com._cython_table
+    keys and expected result.
+
+    Parameters
+    ----------
+    ndframe : DataFrame or Series
+    func_names_and_expected : Sequence of two items
+        The first item is a name of a NDFrame method ('sum', 'prod') etc.
+        The second item is the expected return value.
+
+    Returns
+    -------
+    list
+        List of three items (DataFrame, function, expected result)
+    """
+    results = []
+    for func_name, expected in func_names_and_expected:
+        results.append((ndframe, func_name, expected))
+        results += [
+            (ndframe, func, expected)
+            for func, name in cython_table
+            if name == func_name
+        ]
+    return results
+
+
+def get_op_from_name(op_name: str) -> Callable:
+    """
+    The operator function for a given op name.
+
+    Parameters
+    ----------
+    op_name : str
+        The op name, in form of "add" or "__add__".
+
+    Returns
+    -------
+    function
+        A function performing the operation.
+    """
+    short_opname = op_name.strip("_")
+    try:
+        op = getattr(operator, short_opname)
+    except AttributeError:
+        # Assume it is the reverse operator
+        rop = getattr(operator, short_opname[1:])
+        op = lambda x, y: rop(y, x)
+
+    return op
+
+
+# -----------------------------------------------------------------------------
+# Indexing test helpers
+
+
+def getitem(x):
+    return x
+
+
+def setitem(x):
+    return x
+
+
+def loc(x):
+    return x.loc
+
+
+def iloc(x):
+    return x.iloc
+
+
+def at(x):
+    return x.at
+
+
+def iat(x):
+    return x.iat
+
+
+# -----------------------------------------------------------------------------
+
+_UNITS = ["s", "ms", "us", "ns"]
+
+
+def get_finest_unit(left: str, right: str):
+    """
+    Find the higher of two datetime64 units.
+    """
+    if _UNITS.index(left) >= _UNITS.index(right):
+        return left
+    return right
+
+
+def shares_memory(left, right) -> bool:
+    """
+    Pandas-compat for np.shares_memory.
+    """
+    if isinstance(left, np.ndarray) and isinstance(right, np.ndarray):
+        return np.shares_memory(left, right)
+    elif isinstance(left, np.ndarray):
+        # Call with reversed args to get to unpacking logic below.
+        return shares_memory(right, left)
+
+    if isinstance(left, RangeIndex):
+        return False
+    if isinstance(left, MultiIndex):
+        return shares_memory(left._codes, right)
+    if isinstance(left, (Index, Series)):
+        if isinstance(right, (Index, Series)):
+            return shares_memory(left._values, right._values)
+        return shares_memory(left._values, right)
+
+    if isinstance(left, NDArrayBackedExtensionArray):
+        return shares_memory(left._ndarray, right)
+    if isinstance(left, pd.core.arrays.SparseArray):
+        return shares_memory(left.sp_values, right)
+    if isinstance(left, pd.core.arrays.IntervalArray):
+        return shares_memory(left._left, right) or shares_memory(left._right, right)
+
+    if isinstance(left, ArrowExtensionArray):
+        if isinstance(right, ArrowExtensionArray):
+            # https://github.com/pandas-dev/pandas/pull/43930#discussion_r736862669
+            left_pa_data = left._pa_array
+            right_pa_data = right._pa_array
+            left_buf1 = left_pa_data.chunk(0).buffers()[1]
+            right_buf1 = right_pa_data.chunk(0).buffers()[1]
+            return left_buf1.address == right_buf1.address
+        else:
+            # if we have one one ArrowExtensionArray and one other array, assume
+            # they can only share memory if they share the same numpy buffer
+            return np.shares_memory(left, right)
+
+    if isinstance(left, BaseMaskedArray) and isinstance(right, BaseMaskedArray):
+        # By convention, we'll say these share memory if they share *either*
+        #  the _data or the _mask
+        return np.shares_memory(left._data, right._data) or np.shares_memory(
+            left._mask, right._mask
+        )
+
+    if isinstance(left, DataFrame) and len(left._mgr.arrays) == 1:
+        arr = left._mgr.arrays[0]
+        return shares_memory(arr, right)
+
+    raise NotImplementedError(type(left), type(right))
+
+
+__all__ = [
+    "ALL_INT_EA_DTYPES",
+    "ALL_INT_NUMPY_DTYPES",
+    "ALL_NUMPY_DTYPES",
+    "ALL_REAL_NUMPY_DTYPES",
+    "assert_almost_equal",
+    "assert_attr_equal",
+    "assert_categorical_equal",
+    "assert_class_equal",
+    "assert_contains_all",
+    "assert_copy",
+    "assert_datetime_array_equal",
+    "assert_dict_equal",
+    "assert_equal",
+    "assert_extension_array_equal",
+    "assert_frame_equal",
+    "assert_index_equal",
+    "assert_indexing_slices_equivalent",
+    "assert_interval_array_equal",
+    "assert_is_sorted",
+    "assert_is_valid_plot_return_object",
+    "assert_metadata_equivalent",
+    "assert_numpy_array_equal",
+    "assert_period_array_equal",
+    "assert_produces_warning",
+    "assert_series_equal",
+    "assert_sp_array_equal",
+    "assert_timedelta_array_equal",
+    "assert_cow_warning",
+    "at",
+    "BOOL_DTYPES",
+    "box_expected",
+    "BYTES_DTYPES",
+    "can_set_locale",
+    "COMPLEX_DTYPES",
+    "convert_rows_list_to_csv_str",
+    "DATETIME64_DTYPES",
+    "decompress_file",
+    "ENDIAN",
+    "ensure_clean",
+    "external_error_raised",
+    "FLOAT_EA_DTYPES",
+    "FLOAT_NUMPY_DTYPES",
+    "get_cython_table_params",
+    "get_dtype",
+    "getitem",
+    "get_locales",
+    "get_finest_unit",
+    "get_obj",
+    "get_op_from_name",
+    "iat",
+    "iloc",
+    "loc",
+    "maybe_produces_warning",
+    "NARROW_NP_DTYPES",
+    "NP_NAT_OBJECTS",
+    "NULL_OBJECTS",
+    "OBJECT_DTYPES",
+    "raise_assert_detail",
+    "raises_chained_assignment_error",
+    "round_trip_localpath",
+    "round_trip_pathlib",
+    "round_trip_pickle",
+    "setitem",
+    "set_locale",
+    "set_timezone",
+    "shares_memory",
+    "SIGNED_INT_EA_DTYPES",
+    "SIGNED_INT_NUMPY_DTYPES",
+    "STRING_DTYPES",
+    "SubclassedDataFrame",
+    "SubclassedSeries",
+    "TIMEDELTA64_DTYPES",
+    "to_array",
+    "UNSIGNED_INT_EA_DTYPES",
+    "UNSIGNED_INT_NUMPY_DTYPES",
+    "use_numexpr",
+    "with_csv_dialect",
+    "write_to_compressed",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/_hypothesis.py b/.venv/lib/python3.13/site-packages/pandas/_testing/_hypothesis.py
new file mode 100644
index 0000000000000000000000000000000000000000..084ca9c306d192a2543108249dbc345d1259be01
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/_hypothesis.py
@@ -0,0 +1,93 @@
+"""
+Hypothesis data generator helpers.
+"""
+from datetime import datetime
+
+from hypothesis import strategies as st
+from hypothesis.extra.dateutil import timezones as dateutil_timezones
+from hypothesis.extra.pytz import timezones as pytz_timezones
+
+from pandas.compat import is_platform_windows
+
+import pandas as pd
+
+from pandas.tseries.offsets import (
+    BMonthBegin,
+    BMonthEnd,
+    BQuarterBegin,
+    BQuarterEnd,
+    BYearBegin,
+    BYearEnd,
+    MonthBegin,
+    MonthEnd,
+    QuarterBegin,
+    QuarterEnd,
+    YearBegin,
+    YearEnd,
+)
+
+OPTIONAL_INTS = st.lists(st.one_of(st.integers(), st.none()), max_size=10, min_size=3)
+
+OPTIONAL_FLOATS = st.lists(st.one_of(st.floats(), st.none()), max_size=10, min_size=3)
+
+OPTIONAL_TEXT = st.lists(st.one_of(st.none(), st.text()), max_size=10, min_size=3)
+
+OPTIONAL_DICTS = st.lists(
+    st.one_of(st.none(), st.dictionaries(st.text(), st.integers())),
+    max_size=10,
+    min_size=3,
+)
+
+OPTIONAL_LISTS = st.lists(
+    st.one_of(st.none(), st.lists(st.text(), max_size=10, min_size=3)),
+    max_size=10,
+    min_size=3,
+)
+
+OPTIONAL_ONE_OF_ALL = st.one_of(
+    OPTIONAL_DICTS, OPTIONAL_FLOATS, OPTIONAL_INTS, OPTIONAL_LISTS, OPTIONAL_TEXT
+)
+
+if is_platform_windows():
+    DATETIME_NO_TZ = st.datetimes(min_value=datetime(1900, 1, 1))
+else:
+    DATETIME_NO_TZ = st.datetimes()
+
+DATETIME_JAN_1_1900_OPTIONAL_TZ = st.datetimes(
+    min_value=pd.Timestamp(
+        1900, 1, 1
+    ).to_pydatetime(),  # pyright: ignore[reportGeneralTypeIssues]
+    max_value=pd.Timestamp(
+        1900, 1, 1
+    ).to_pydatetime(),  # pyright: ignore[reportGeneralTypeIssues]
+    timezones=st.one_of(st.none(), dateutil_timezones(), pytz_timezones()),
+)
+
+DATETIME_IN_PD_TIMESTAMP_RANGE_NO_TZ = st.datetimes(
+    min_value=pd.Timestamp.min.to_pydatetime(warn=False),
+    max_value=pd.Timestamp.max.to_pydatetime(warn=False),
+)
+
+INT_NEG_999_TO_POS_999 = st.integers(-999, 999)
+
+# The strategy for each type is registered in conftest.py, as they don't carry
+# enough runtime information (e.g. type hints) to infer how to build them.
+YQM_OFFSET = st.one_of(
+    *map(
+        st.from_type,
+        [
+            MonthBegin,
+            MonthEnd,
+            BMonthBegin,
+            BMonthEnd,
+            QuarterBegin,
+            QuarterEnd,
+            BQuarterBegin,
+            BQuarterEnd,
+            YearBegin,
+            YearEnd,
+            BYearBegin,
+            BYearEnd,
+        ],
+    )
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/_io.py b/.venv/lib/python3.13/site-packages/pandas/_testing/_io.py
new file mode 100644
index 0000000000000000000000000000000000000000..95977edb600ade42a8f8a1fada2b5085cee1da56
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/_io.py
@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import gzip
+import io
+import pathlib
+import tarfile
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+import uuid
+import zipfile
+
+from pandas.compat import (
+    get_bz2_file,
+    get_lzma_file,
+)
+from pandas.compat._optional import import_optional_dependency
+
+import pandas as pd
+from pandas._testing.contexts import ensure_clean
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        FilePath,
+        ReadPickleBuffer,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+# ------------------------------------------------------------------
+# File-IO
+
+
+def round_trip_pickle(
+    obj: Any, path: FilePath | ReadPickleBuffer | None = None
+) -> DataFrame | Series:
+    """
+    Pickle an object and then read it again.
+
+    Parameters
+    ----------
+    obj : any object
+        The object to pickle and then re-read.
+    path : str, path object or file-like object, default None
+        The path where the pickled object is written and then read.
+
+    Returns
+    -------
+    pandas object
+        The original object that was pickled and then re-read.
+    """
+    _path = path
+    if _path is None:
+        _path = f"__{uuid.uuid4()}__.pickle"
+    with ensure_clean(_path) as temp_path:
+        pd.to_pickle(obj, temp_path)
+        return pd.read_pickle(temp_path)
+
+
+def round_trip_pathlib(writer, reader, path: str | None = None):
+    """
+    Write an object to file specified by a pathlib.Path and read it back
+
+    Parameters
+    ----------
+    writer : callable bound to pandas object
+        IO writing function (e.g. DataFrame.to_csv )
+    reader : callable
+        IO reading function (e.g. pd.read_csv )
+    path : str, default None
+        The path where the object is written and then read.
+
+    Returns
+    -------
+    pandas object
+        The original object that was serialized and then re-read.
+    """
+    Path = pathlib.Path
+    if path is None:
+        path = "___pathlib___"
+    with ensure_clean(path) as path:
+        writer(Path(path))  # type: ignore[arg-type]
+        obj = reader(Path(path))  # type: ignore[arg-type]
+    return obj
+
+
+def round_trip_localpath(writer, reader, path: str | None = None):
+    """
+    Write an object to file specified by a py.path LocalPath and read it back.
+
+    Parameters
+    ----------
+    writer : callable bound to pandas object
+        IO writing function (e.g. DataFrame.to_csv )
+    reader : callable
+        IO reading function (e.g. pd.read_csv )
+    path : str, default None
+        The path where the object is written and then read.
+
+    Returns
+    -------
+    pandas object
+        The original object that was serialized and then re-read.
+    """
+    import pytest
+
+    LocalPath = pytest.importorskip("py.path").local
+    if path is None:
+        path = "___localpath___"
+    with ensure_clean(path) as path:
+        writer(LocalPath(path))
+        obj = reader(LocalPath(path))
+    return obj
+
+
+def write_to_compressed(compression, path, data, dest: str = "test") -> None:
+    """
+    Write data to a compressed file.
+
+    Parameters
+    ----------
+    compression : {'gzip', 'bz2', 'zip', 'xz', 'zstd'}
+        The compression type to use.
+    path : str
+        The file path to write the data.
+    data : str
+        The data to write.
+    dest : str, default "test"
+        The destination file (for ZIP only)
+
+    Raises
+    ------
+    ValueError : An invalid compression value was passed in.
+    """
+    args: tuple[Any, ...] = (data,)
+    mode = "wb"
+    method = "write"
+    compress_method: Callable
+
+    if compression == "zip":
+        compress_method = zipfile.ZipFile
+        mode = "w"
+        args = (dest, data)
+        method = "writestr"
+    elif compression == "tar":
+        compress_method = tarfile.TarFile
+        mode = "w"
+        file = tarfile.TarInfo(name=dest)
+        bytes = io.BytesIO(data)
+        file.size = len(data)
+        args = (file, bytes)
+        method = "addfile"
+    elif compression == "gzip":
+        compress_method = gzip.GzipFile
+    elif compression == "bz2":
+        compress_method = get_bz2_file()
+    elif compression == "zstd":
+        compress_method = import_optional_dependency("zstandard").open
+    elif compression == "xz":
+        compress_method = get_lzma_file()
+    else:
+        raise ValueError(f"Unrecognized compression type: {compression}")
+
+    with compress_method(path, mode=mode) as f:
+        getattr(f, method)(*args)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/_warnings.py b/.venv/lib/python3.13/site-packages/pandas/_testing/_warnings.py
new file mode 100644
index 0000000000000000000000000000000000000000..c9a287942f2dac5ddbaf49168db280ec2ba3f2c4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/_warnings.py
@@ -0,0 +1,232 @@
+from __future__ import annotations
+
+from contextlib import (
+    contextmanager,
+    nullcontext,
+)
+import inspect
+import re
+import sys
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+)
+import warnings
+
+from pandas.compat import PY311
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Sequence,
+    )
+
+
+@contextmanager
+def assert_produces_warning(
+    expected_warning: type[Warning] | bool | tuple[type[Warning], ...] | None = Warning,
+    filter_level: Literal[
+        "error", "ignore", "always", "default", "module", "once"
+    ] = "always",
+    check_stacklevel: bool = True,
+    raise_on_extra_warnings: bool = True,
+    match: str | None = None,
+) -> Generator[list[warnings.WarningMessage], None, None]:
+    """
+    Context manager for running code expected to either raise a specific warning,
+    multiple specific warnings, or not raise any warnings. Verifies that the code
+    raises the expected warning(s), and that it does not raise any other unexpected
+    warnings. It is basically a wrapper around ``warnings.catch_warnings``.
+
+    Parameters
+    ----------
+    expected_warning : {Warning, False, tuple[Warning, ...], None}, default Warning
+        The type of Exception raised. ``exception.Warning`` is the base
+        class for all warnings. To raise multiple types of exceptions,
+        pass them as a tuple. To check that no warning is returned,
+        specify ``False`` or ``None``.
+    filter_level : str or None, default "always"
+        Specifies whether warnings are ignored, displayed, or turned
+        into errors.
+        Valid values are:
+
+        * "error" - turns matching warnings into exceptions
+        * "ignore" - discard the warning
+        * "always" - always emit a warning
+        * "default" - print the warning the first time it is generated
+          from each location
+        * "module" - print the warning the first time it is generated
+          from each module
+        * "once" - print the warning the first time it is generated
+
+    check_stacklevel : bool, default True
+        If True, displays the line that called the function containing
+        the warning to show were the function is called. Otherwise, the
+        line that implements the function is displayed.
+    raise_on_extra_warnings : bool, default True
+        Whether extra warnings not of the type `expected_warning` should
+        cause the test to fail.
+    match : str, optional
+        Match warning message.
+
+    Examples
+    --------
+    >>> import warnings
+    >>> with assert_produces_warning():
+    ...     warnings.warn(UserWarning())
+    ...
+    >>> with assert_produces_warning(False):
+    ...     warnings.warn(RuntimeWarning())
+    ...
+    Traceback (most recent call last):
+        ...
+    AssertionError: Caused unexpected warning(s): ['RuntimeWarning'].
+    >>> with assert_produces_warning(UserWarning):
+    ...     warnings.warn(RuntimeWarning())
+    Traceback (most recent call last):
+        ...
+    AssertionError: Did not see expected warning of class 'UserWarning'.
+
+    ..warn:: This is *not* thread-safe.
+    """
+    __tracebackhide__ = True
+
+    with warnings.catch_warnings(record=True) as w:
+        warnings.simplefilter(filter_level)
+        try:
+            yield w
+        finally:
+            if expected_warning:
+                expected_warning = cast(type[Warning], expected_warning)
+                _assert_caught_expected_warning(
+                    caught_warnings=w,
+                    expected_warning=expected_warning,
+                    match=match,
+                    check_stacklevel=check_stacklevel,
+                )
+            if raise_on_extra_warnings:
+                _assert_caught_no_extra_warnings(
+                    caught_warnings=w,
+                    expected_warning=expected_warning,
+                )
+
+
+def maybe_produces_warning(warning: type[Warning], condition: bool, **kwargs):
+    """
+    Return a context manager that possibly checks a warning based on the condition
+    """
+    if condition:
+        return assert_produces_warning(warning, **kwargs)
+    else:
+        return nullcontext()
+
+
+def _assert_caught_expected_warning(
+    *,
+    caught_warnings: Sequence[warnings.WarningMessage],
+    expected_warning: type[Warning],
+    match: str | None,
+    check_stacklevel: bool,
+) -> None:
+    """Assert that there was the expected warning among the caught warnings."""
+    saw_warning = False
+    matched_message = False
+    unmatched_messages = []
+
+    for actual_warning in caught_warnings:
+        if issubclass(actual_warning.category, expected_warning):
+            saw_warning = True
+
+            if check_stacklevel:
+                _assert_raised_with_correct_stacklevel(actual_warning)
+
+            if match is not None:
+                if re.search(match, str(actual_warning.message)):
+                    matched_message = True
+                else:
+                    unmatched_messages.append(actual_warning.message)
+
+    if not saw_warning:
+        raise AssertionError(
+            f"Did not see expected warning of class "
+            f"{repr(expected_warning.__name__)}"
+        )
+
+    if match and not matched_message:
+        raise AssertionError(
+            f"Did not see warning {repr(expected_warning.__name__)} "
+            f"matching '{match}'. The emitted warning messages are "
+            f"{unmatched_messages}"
+        )
+
+
+def _assert_caught_no_extra_warnings(
+    *,
+    caught_warnings: Sequence[warnings.WarningMessage],
+    expected_warning: type[Warning] | bool | tuple[type[Warning], ...] | None,
+) -> None:
+    """Assert that no extra warnings apart from the expected ones are caught."""
+    extra_warnings = []
+
+    for actual_warning in caught_warnings:
+        if _is_unexpected_warning(actual_warning, expected_warning):
+            # GH#38630 pytest.filterwarnings does not suppress these.
+            if actual_warning.category == ResourceWarning:
+                # GH 44732: Don't make the CI flaky by filtering SSL-related
+                # ResourceWarning from dependencies
+                if "unclosed  bool:
+    """Check if the actual warning issued is unexpected."""
+    if actual_warning and not expected_warning:
+        return True
+    expected_warning = cast(type[Warning], expected_warning)
+    return bool(not issubclass(actual_warning.category, expected_warning))
+
+
+def _assert_raised_with_correct_stacklevel(
+    actual_warning: warnings.WarningMessage,
+) -> None:
+    # https://stackoverflow.com/questions/17407119/python-inspect-stack-is-slow
+    frame = inspect.currentframe()
+    for _ in range(4):
+        frame = frame.f_back  # type: ignore[union-attr]
+    try:
+        caller_filename = inspect.getfile(frame)  # type: ignore[arg-type]
+    finally:
+        # See note in
+        # https://docs.python.org/3/library/inspect.html#inspect.Traceback
+        del frame
+    msg = (
+        "Warning not set with correct stacklevel. "
+        f"File where warning is raised: {actual_warning.filename} != "
+        f"{caller_filename}. Warning message: {actual_warning.message}"
+    )
+    assert actual_warning.filename == caller_filename, msg
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/asserters.py b/.venv/lib/python3.13/site-packages/pandas/_testing/asserters.py
new file mode 100644
index 0000000000000000000000000000000000000000..a1f9844669c8c99848796e102878848d565bbd5c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/asserters.py
@@ -0,0 +1,1459 @@
+from __future__ import annotations
+
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    NoReturn,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.missing import is_matching_na
+from pandas._libs.sparse import SparseIndex
+import pandas._libs.testing as _testing
+from pandas._libs.tslibs.np_datetime import compare_mismatched_resolutions
+
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_float_dtype,
+    is_integer_dtype,
+    is_number,
+    is_numeric_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    NumpyEADtype,
+)
+from pandas.core.dtypes.missing import array_equivalent
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    DataFrame,
+    DatetimeIndex,
+    Index,
+    IntervalDtype,
+    IntervalIndex,
+    MultiIndex,
+    PeriodIndex,
+    RangeIndex,
+    Series,
+    TimedeltaIndex,
+)
+from pandas.core.arrays import (
+    DatetimeArray,
+    ExtensionArray,
+    IntervalArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.datetimelike import DatetimeLikeArrayMixin
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.indexes.api import safe_sort_index
+
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from pandas._typing import DtypeObj
+
+
+def assert_almost_equal(
+    left,
+    right,
+    check_dtype: bool | Literal["equiv"] = "equiv",
+    rtol: float = 1.0e-5,
+    atol: float = 1.0e-8,
+    **kwargs,
+) -> None:
+    """
+    Check that the left and right objects are approximately equal.
+
+    By approximately equal, we refer to objects that are numbers or that
+    contain numbers which may be equivalent to specific levels of precision.
+
+    Parameters
+    ----------
+    left : object
+    right : object
+    check_dtype : bool or {'equiv'}, default 'equiv'
+        Check dtype if both a and b are the same type. If 'equiv' is passed in,
+        then `RangeIndex` and `Index` with int64 dtype are also considered
+        equivalent when doing type checking.
+    rtol : float, default 1e-5
+        Relative tolerance.
+    atol : float, default 1e-8
+        Absolute tolerance.
+    """
+    if isinstance(left, Index):
+        assert_index_equal(
+            left,
+            right,
+            check_exact=False,
+            exact=check_dtype,
+            rtol=rtol,
+            atol=atol,
+            **kwargs,
+        )
+
+    elif isinstance(left, Series):
+        assert_series_equal(
+            left,
+            right,
+            check_exact=False,
+            check_dtype=check_dtype,
+            rtol=rtol,
+            atol=atol,
+            **kwargs,
+        )
+
+    elif isinstance(left, DataFrame):
+        assert_frame_equal(
+            left,
+            right,
+            check_exact=False,
+            check_dtype=check_dtype,
+            rtol=rtol,
+            atol=atol,
+            **kwargs,
+        )
+
+    else:
+        # Other sequences.
+        if check_dtype:
+            if is_number(left) and is_number(right):
+                # Do not compare numeric classes, like np.float64 and float.
+                pass
+            elif is_bool(left) and is_bool(right):
+                # Do not compare bool classes, like np.bool_ and bool.
+                pass
+            else:
+                if isinstance(left, np.ndarray) or isinstance(right, np.ndarray):
+                    obj = "numpy array"
+                else:
+                    obj = "Input"
+                assert_class_equal(left, right, obj=obj)
+
+        # if we have "equiv", this becomes True
+        _testing.assert_almost_equal(
+            left, right, check_dtype=bool(check_dtype), rtol=rtol, atol=atol, **kwargs
+        )
+
+
+def _check_isinstance(left, right, cls) -> None:
+    """
+    Helper method for our assert_* methods that ensures that
+    the two objects being compared have the right type before
+    proceeding with the comparison.
+
+    Parameters
+    ----------
+    left : The first object being compared.
+    right : The second object being compared.
+    cls : The class type to check against.
+
+    Raises
+    ------
+    AssertionError : Either `left` or `right` is not an instance of `cls`.
+    """
+    cls_name = cls.__name__
+
+    if not isinstance(left, cls):
+        raise AssertionError(
+            f"{cls_name} Expected type {cls}, found {type(left)} instead"
+        )
+    if not isinstance(right, cls):
+        raise AssertionError(
+            f"{cls_name} Expected type {cls}, found {type(right)} instead"
+        )
+
+
+def assert_dict_equal(left, right, compare_keys: bool = True) -> None:
+    _check_isinstance(left, right, dict)
+    _testing.assert_dict_equal(left, right, compare_keys=compare_keys)
+
+
+def assert_index_equal(
+    left: Index,
+    right: Index,
+    exact: bool | str = "equiv",
+    check_names: bool = True,
+    check_exact: bool = True,
+    check_categorical: bool = True,
+    check_order: bool = True,
+    rtol: float = 1.0e-5,
+    atol: float = 1.0e-8,
+    obj: str = "Index",
+) -> None:
+    """
+    Check that left and right Index are equal.
+
+    Parameters
+    ----------
+    left : Index
+    right : Index
+    exact : bool or {'equiv'}, default 'equiv'
+        Whether to check the Index class, dtype and inferred_type
+        are identical. If 'equiv', then RangeIndex can be substituted for
+        Index with an int64 dtype as well.
+    check_names : bool, default True
+        Whether to check the names attribute.
+    check_exact : bool, default True
+        Whether to compare number exactly.
+    check_categorical : bool, default True
+        Whether to compare internal Categorical exactly.
+    check_order : bool, default True
+        Whether to compare the order of index entries as well as their values.
+        If True, both indexes must contain the same elements, in the same order.
+        If False, both indexes must contain the same elements, but in any order.
+    rtol : float, default 1e-5
+        Relative tolerance. Only used when check_exact is False.
+    atol : float, default 1e-8
+        Absolute tolerance. Only used when check_exact is False.
+    obj : str, default 'Index'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+
+    Examples
+    --------
+    >>> from pandas import testing as tm
+    >>> a = pd.Index([1, 2, 3])
+    >>> b = pd.Index([1, 2, 3])
+    >>> tm.assert_index_equal(a, b)
+    """
+    __tracebackhide__ = True
+
+    def _check_types(left, right, obj: str = "Index") -> None:
+        if not exact:
+            return
+
+        assert_class_equal(left, right, exact=exact, obj=obj)
+        assert_attr_equal("inferred_type", left, right, obj=obj)
+
+        # Skip exact dtype checking when `check_categorical` is False
+        if isinstance(left.dtype, CategoricalDtype) and isinstance(
+            right.dtype, CategoricalDtype
+        ):
+            if check_categorical:
+                assert_attr_equal("dtype", left, right, obj=obj)
+                assert_index_equal(left.categories, right.categories, exact=exact)
+            return
+
+        assert_attr_equal("dtype", left, right, obj=obj)
+
+    # instance validation
+    _check_isinstance(left, right, Index)
+
+    # class / dtype comparison
+    _check_types(left, right, obj=obj)
+
+    # level comparison
+    if left.nlevels != right.nlevels:
+        msg1 = f"{obj} levels are different"
+        msg2 = f"{left.nlevels}, {left}"
+        msg3 = f"{right.nlevels}, {right}"
+        raise_assert_detail(obj, msg1, msg2, msg3)
+
+    # length comparison
+    if len(left) != len(right):
+        msg1 = f"{obj} length are different"
+        msg2 = f"{len(left)}, {left}"
+        msg3 = f"{len(right)}, {right}"
+        raise_assert_detail(obj, msg1, msg2, msg3)
+
+    # If order doesn't matter then sort the index entries
+    if not check_order:
+        left = safe_sort_index(left)
+        right = safe_sort_index(right)
+
+    # MultiIndex special comparison for little-friendly error messages
+    if isinstance(left, MultiIndex):
+        right = cast(MultiIndex, right)
+
+        for level in range(left.nlevels):
+            lobj = f"MultiIndex level [{level}]"
+            try:
+                # try comparison on levels/codes to avoid densifying MultiIndex
+                assert_index_equal(
+                    left.levels[level],
+                    right.levels[level],
+                    exact=exact,
+                    check_names=check_names,
+                    check_exact=check_exact,
+                    check_categorical=check_categorical,
+                    rtol=rtol,
+                    atol=atol,
+                    obj=lobj,
+                )
+                assert_numpy_array_equal(left.codes[level], right.codes[level])
+            except AssertionError:
+                llevel = left.get_level_values(level)
+                rlevel = right.get_level_values(level)
+
+                assert_index_equal(
+                    llevel,
+                    rlevel,
+                    exact=exact,
+                    check_names=check_names,
+                    check_exact=check_exact,
+                    check_categorical=check_categorical,
+                    rtol=rtol,
+                    atol=atol,
+                    obj=lobj,
+                )
+            # get_level_values may change dtype
+            _check_types(left.levels[level], right.levels[level], obj=obj)
+
+    # skip exact index checking when `check_categorical` is False
+    elif check_exact and check_categorical:
+        if not left.equals(right):
+            mismatch = left._values != right._values
+
+            if not isinstance(mismatch, np.ndarray):
+                mismatch = cast("ExtensionArray", mismatch).fillna(True)
+
+            diff = np.sum(mismatch.astype(int)) * 100.0 / len(left)
+            msg = f"{obj} values are different ({np.round(diff, 5)} %)"
+            raise_assert_detail(obj, msg, left, right)
+    else:
+        # if we have "equiv", this becomes True
+        exact_bool = bool(exact)
+        _testing.assert_almost_equal(
+            left.values,
+            right.values,
+            rtol=rtol,
+            atol=atol,
+            check_dtype=exact_bool,
+            obj=obj,
+            lobj=left,
+            robj=right,
+        )
+
+    # metadata comparison
+    if check_names:
+        assert_attr_equal("names", left, right, obj=obj)
+    if isinstance(left, PeriodIndex) or isinstance(right, PeriodIndex):
+        assert_attr_equal("dtype", left, right, obj=obj)
+    if isinstance(left, IntervalIndex) or isinstance(right, IntervalIndex):
+        assert_interval_array_equal(left._values, right._values)
+
+    if check_categorical:
+        if isinstance(left.dtype, CategoricalDtype) or isinstance(
+            right.dtype, CategoricalDtype
+        ):
+            assert_categorical_equal(left._values, right._values, obj=f"{obj} category")
+
+
+def assert_class_equal(
+    left, right, exact: bool | str = True, obj: str = "Input"
+) -> None:
+    """
+    Checks classes are equal.
+    """
+    __tracebackhide__ = True
+
+    def repr_class(x):
+        if isinstance(x, Index):
+            # return Index as it is to include values in the error message
+            return x
+
+        return type(x).__name__
+
+    def is_class_equiv(idx: Index) -> bool:
+        """Classes that are a RangeIndex (sub-)instance or exactly an `Index` .
+
+        This only checks class equivalence. There is a separate check that the
+        dtype is int64.
+        """
+        return type(idx) is Index or isinstance(idx, RangeIndex)
+
+    if type(left) == type(right):
+        return
+
+    if exact == "equiv":
+        if is_class_equiv(left) and is_class_equiv(right):
+            return
+
+    msg = f"{obj} classes are different"
+    raise_assert_detail(obj, msg, repr_class(left), repr_class(right))
+
+
+def assert_attr_equal(attr: str, left, right, obj: str = "Attributes") -> None:
+    """
+    Check attributes are equal. Both objects must have attribute.
+
+    Parameters
+    ----------
+    attr : str
+        Attribute name being compared.
+    left : object
+    right : object
+    obj : str, default 'Attributes'
+        Specify object name being compared, internally used to show appropriate
+        assertion message
+    """
+    __tracebackhide__ = True
+
+    left_attr = getattr(left, attr)
+    right_attr = getattr(right, attr)
+
+    if left_attr is right_attr or is_matching_na(left_attr, right_attr):
+        # e.g. both np.nan, both NaT, both pd.NA, ...
+        return None
+
+    try:
+        result = left_attr == right_attr
+    except TypeError:
+        # datetimetz on rhs may raise TypeError
+        result = False
+    if (left_attr is pd.NA) ^ (right_attr is pd.NA):
+        result = False
+    elif not isinstance(result, bool):
+        result = result.all()
+
+    if not result:
+        msg = f'Attribute "{attr}" are different'
+        raise_assert_detail(obj, msg, left_attr, right_attr)
+    return None
+
+
+def assert_is_valid_plot_return_object(objs) -> None:
+    from matplotlib.artist import Artist
+    from matplotlib.axes import Axes
+
+    if isinstance(objs, (Series, np.ndarray)):
+        if isinstance(objs, Series):
+            objs = objs._values
+        for el in objs.ravel():
+            msg = (
+                "one of 'objs' is not a matplotlib Axes instance, "
+                f"type encountered {repr(type(el).__name__)}"
+            )
+            assert isinstance(el, (Axes, dict)), msg
+    else:
+        msg = (
+            "objs is neither an ndarray of Artist instances nor a single "
+            "ArtistArtist instance, tuple, or dict, 'objs' is a "
+            f"{repr(type(objs).__name__)}"
+        )
+        assert isinstance(objs, (Artist, tuple, dict)), msg
+
+
+def assert_is_sorted(seq) -> None:
+    """Assert that the sequence is sorted."""
+    if isinstance(seq, (Index, Series)):
+        seq = seq.values
+    # sorting does not change precisions
+    if isinstance(seq, np.ndarray):
+        assert_numpy_array_equal(seq, np.sort(np.array(seq)))
+    else:
+        assert_extension_array_equal(seq, seq[seq.argsort()])
+
+
+def assert_categorical_equal(
+    left,
+    right,
+    check_dtype: bool = True,
+    check_category_order: bool = True,
+    obj: str = "Categorical",
+) -> None:
+    """
+    Test that Categoricals are equivalent.
+
+    Parameters
+    ----------
+    left : Categorical
+    right : Categorical
+    check_dtype : bool, default True
+        Check that integer dtype of the codes are the same.
+    check_category_order : bool, default True
+        Whether the order of the categories should be compared, which
+        implies identical integer codes.  If False, only the resulting
+        values are compared.  The ordered attribute is
+        checked regardless.
+    obj : str, default 'Categorical'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+    """
+    _check_isinstance(left, right, Categorical)
+
+    exact: bool | str
+    if isinstance(left.categories, RangeIndex) or isinstance(
+        right.categories, RangeIndex
+    ):
+        exact = "equiv"
+    else:
+        # We still want to require exact matches for Index
+        exact = True
+
+    if check_category_order:
+        assert_index_equal(
+            left.categories, right.categories, obj=f"{obj}.categories", exact=exact
+        )
+        assert_numpy_array_equal(
+            left.codes, right.codes, check_dtype=check_dtype, obj=f"{obj}.codes"
+        )
+    else:
+        try:
+            lc = left.categories.sort_values()
+            rc = right.categories.sort_values()
+        except TypeError:
+            # e.g. '<' not supported between instances of 'int' and 'str'
+            lc, rc = left.categories, right.categories
+        assert_index_equal(lc, rc, obj=f"{obj}.categories", exact=exact)
+        assert_index_equal(
+            left.categories.take(left.codes),
+            right.categories.take(right.codes),
+            obj=f"{obj}.values",
+            exact=exact,
+        )
+
+    assert_attr_equal("ordered", left, right, obj=obj)
+
+
+def assert_interval_array_equal(
+    left, right, exact: bool | Literal["equiv"] = "equiv", obj: str = "IntervalArray"
+) -> None:
+    """
+    Test that two IntervalArrays are equivalent.
+
+    Parameters
+    ----------
+    left, right : IntervalArray
+        The IntervalArrays to compare.
+    exact : bool or {'equiv'}, default 'equiv'
+        Whether to check the Index class, dtype and inferred_type
+        are identical. If 'equiv', then RangeIndex can be substituted for
+        Index with an int64 dtype as well.
+    obj : str, default 'IntervalArray'
+        Specify object name being compared, internally used to show appropriate
+        assertion message
+    """
+    _check_isinstance(left, right, IntervalArray)
+
+    kwargs = {}
+    if left._left.dtype.kind in "mM":
+        # We have a DatetimeArray or TimedeltaArray
+        kwargs["check_freq"] = False
+
+    assert_equal(left._left, right._left, obj=f"{obj}.left", **kwargs)
+    assert_equal(left._right, right._right, obj=f"{obj}.left", **kwargs)
+
+    assert_attr_equal("closed", left, right, obj=obj)
+
+
+def assert_period_array_equal(left, right, obj: str = "PeriodArray") -> None:
+    _check_isinstance(left, right, PeriodArray)
+
+    assert_numpy_array_equal(left._ndarray, right._ndarray, obj=f"{obj}._ndarray")
+    assert_attr_equal("dtype", left, right, obj=obj)
+
+
+def assert_datetime_array_equal(
+    left, right, obj: str = "DatetimeArray", check_freq: bool = True
+) -> None:
+    __tracebackhide__ = True
+    _check_isinstance(left, right, DatetimeArray)
+
+    assert_numpy_array_equal(left._ndarray, right._ndarray, obj=f"{obj}._ndarray")
+    if check_freq:
+        assert_attr_equal("freq", left, right, obj=obj)
+    assert_attr_equal("tz", left, right, obj=obj)
+
+
+def assert_timedelta_array_equal(
+    left, right, obj: str = "TimedeltaArray", check_freq: bool = True
+) -> None:
+    __tracebackhide__ = True
+    _check_isinstance(left, right, TimedeltaArray)
+    assert_numpy_array_equal(left._ndarray, right._ndarray, obj=f"{obj}._ndarray")
+    if check_freq:
+        assert_attr_equal("freq", left, right, obj=obj)
+
+
+def raise_assert_detail(
+    obj, message, left, right, diff=None, first_diff=None, index_values=None
+) -> NoReturn:
+    __tracebackhide__ = True
+
+    msg = f"""{obj} are different
+
+{message}"""
+
+    if isinstance(index_values, Index):
+        index_values = np.asarray(index_values)
+
+    if isinstance(index_values, np.ndarray):
+        msg += f"\n[index]: {pprint_thing(index_values)}"
+
+    if isinstance(left, np.ndarray):
+        left = pprint_thing(left)
+    elif isinstance(left, (CategoricalDtype, NumpyEADtype)):
+        left = repr(left)
+    elif isinstance(left, StringDtype):
+        # TODO(infer_string) this special case could be avoided if we have
+        # a more informative repr https://github.com/pandas-dev/pandas/issues/59342
+        left = f"StringDtype(storage={left.storage}, na_value={left.na_value})"
+
+    if isinstance(right, np.ndarray):
+        right = pprint_thing(right)
+    elif isinstance(right, (CategoricalDtype, NumpyEADtype)):
+        right = repr(right)
+    elif isinstance(right, StringDtype):
+        right = f"StringDtype(storage={right.storage}, na_value={right.na_value})"
+
+    msg += f"""
+[left]:  {left}
+[right]: {right}"""
+
+    if diff is not None:
+        msg += f"\n[diff]: {diff}"
+
+    if first_diff is not None:
+        msg += f"\n{first_diff}"
+
+    raise AssertionError(msg)
+
+
+def assert_numpy_array_equal(
+    left,
+    right,
+    strict_nan: bool = False,
+    check_dtype: bool | Literal["equiv"] = True,
+    err_msg=None,
+    check_same=None,
+    obj: str = "numpy array",
+    index_values=None,
+) -> None:
+    """
+    Check that 'np.ndarray' is equivalent.
+
+    Parameters
+    ----------
+    left, right : numpy.ndarray or iterable
+        The two arrays to be compared.
+    strict_nan : bool, default False
+        If True, consider NaN and None to be different.
+    check_dtype : bool, default True
+        Check dtype if both a and b are np.ndarray.
+    err_msg : str, default None
+        If provided, used as assertion message.
+    check_same : None|'copy'|'same', default None
+        Ensure left and right refer/do not refer to the same memory area.
+    obj : str, default 'numpy array'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+    index_values : Index | numpy.ndarray, default None
+        optional index (shared by both left and right), used in output.
+    """
+    __tracebackhide__ = True
+
+    # instance validation
+    # Show a detailed error message when classes are different
+    assert_class_equal(left, right, obj=obj)
+    # both classes must be an np.ndarray
+    _check_isinstance(left, right, np.ndarray)
+
+    def _get_base(obj):
+        return obj.base if getattr(obj, "base", None) is not None else obj
+
+    left_base = _get_base(left)
+    right_base = _get_base(right)
+
+    if check_same == "same":
+        if left_base is not right_base:
+            raise AssertionError(f"{repr(left_base)} is not {repr(right_base)}")
+    elif check_same == "copy":
+        if left_base is right_base:
+            raise AssertionError(f"{repr(left_base)} is {repr(right_base)}")
+
+    def _raise(left, right, err_msg) -> NoReturn:
+        if err_msg is None:
+            if left.shape != right.shape:
+                raise_assert_detail(
+                    obj, f"{obj} shapes are different", left.shape, right.shape
+                )
+
+            diff = 0
+            for left_arr, right_arr in zip(left, right):
+                # count up differences
+                if not array_equivalent(left_arr, right_arr, strict_nan=strict_nan):
+                    diff += 1
+
+            diff = diff * 100.0 / left.size
+            msg = f"{obj} values are different ({np.round(diff, 5)} %)"
+            raise_assert_detail(obj, msg, left, right, index_values=index_values)
+
+        raise AssertionError(err_msg)
+
+    # compare shape and values
+    if not array_equivalent(left, right, strict_nan=strict_nan):
+        _raise(left, right, err_msg)
+
+    if check_dtype:
+        if isinstance(left, np.ndarray) and isinstance(right, np.ndarray):
+            assert_attr_equal("dtype", left, right, obj=obj)
+
+
+def assert_extension_array_equal(
+    left,
+    right,
+    check_dtype: bool | Literal["equiv"] = True,
+    index_values=None,
+    check_exact: bool | lib.NoDefault = lib.no_default,
+    rtol: float | lib.NoDefault = lib.no_default,
+    atol: float | lib.NoDefault = lib.no_default,
+    obj: str = "ExtensionArray",
+) -> None:
+    """
+    Check that left and right ExtensionArrays are equal.
+
+    Parameters
+    ----------
+    left, right : ExtensionArray
+        The two arrays to compare.
+    check_dtype : bool, default True
+        Whether to check if the ExtensionArray dtypes are identical.
+    index_values : Index | numpy.ndarray, default None
+        Optional index (shared by both left and right), used in output.
+    check_exact : bool, default False
+        Whether to compare number exactly.
+
+        .. versionchanged:: 2.2.0
+
+            Defaults to True for integer dtypes if none of
+            ``check_exact``, ``rtol`` and ``atol`` are specified.
+    rtol : float, default 1e-5
+        Relative tolerance. Only used when check_exact is False.
+    atol : float, default 1e-8
+        Absolute tolerance. Only used when check_exact is False.
+    obj : str, default 'ExtensionArray'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+
+        .. versionadded:: 2.0.0
+
+    Notes
+    -----
+    Missing values are checked separately from valid values.
+    A mask of missing values is computed for each and checked to match.
+    The remaining all-valid values are cast to object dtype and checked.
+
+    Examples
+    --------
+    >>> from pandas import testing as tm
+    >>> a = pd.Series([1, 2, 3, 4])
+    >>> b, c = a.array, a.array
+    >>> tm.assert_extension_array_equal(b, c)
+    """
+    if (
+        check_exact is lib.no_default
+        and rtol is lib.no_default
+        and atol is lib.no_default
+    ):
+        check_exact = (
+            is_numeric_dtype(left.dtype)
+            and not is_float_dtype(left.dtype)
+            or is_numeric_dtype(right.dtype)
+            and not is_float_dtype(right.dtype)
+        )
+    elif check_exact is lib.no_default:
+        check_exact = False
+
+    rtol = rtol if rtol is not lib.no_default else 1.0e-5
+    atol = atol if atol is not lib.no_default else 1.0e-8
+
+    assert isinstance(left, ExtensionArray), "left is not an ExtensionArray"
+    assert isinstance(right, ExtensionArray), "right is not an ExtensionArray"
+    if check_dtype:
+        assert_attr_equal("dtype", left, right, obj=f"Attributes of {obj}")
+
+    if (
+        isinstance(left, DatetimeLikeArrayMixin)
+        and isinstance(right, DatetimeLikeArrayMixin)
+        and type(right) == type(left)
+    ):
+        # GH 52449
+        if not check_dtype and left.dtype.kind in "mM":
+            if not isinstance(left.dtype, np.dtype):
+                l_unit = cast(DatetimeTZDtype, left.dtype).unit
+            else:
+                l_unit = np.datetime_data(left.dtype)[0]
+            if not isinstance(right.dtype, np.dtype):
+                r_unit = cast(DatetimeTZDtype, right.dtype).unit
+            else:
+                r_unit = np.datetime_data(right.dtype)[0]
+            if (
+                l_unit != r_unit
+                and compare_mismatched_resolutions(
+                    left._ndarray, right._ndarray, operator.eq
+                ).all()
+            ):
+                return
+        # Avoid slow object-dtype comparisons
+        # np.asarray for case where we have a np.MaskedArray
+        assert_numpy_array_equal(
+            np.asarray(left.asi8),
+            np.asarray(right.asi8),
+            index_values=index_values,
+            obj=obj,
+        )
+        return
+
+    left_na = np.asarray(left.isna())
+    right_na = np.asarray(right.isna())
+    assert_numpy_array_equal(
+        left_na, right_na, obj=f"{obj} NA mask", index_values=index_values
+    )
+
+    # Specifically for StringArrayNumpySemantics, validate here we have a valid array
+    if (
+        isinstance(left.dtype, StringDtype)
+        and left.dtype.storage == "python"
+        and left.dtype.na_value is np.nan
+    ):
+        assert np.all(
+            [np.isnan(val) for val in left._ndarray[left_na]]  # type: ignore[attr-defined]
+        ), "wrong missing value sentinels"
+    if (
+        isinstance(right.dtype, StringDtype)
+        and right.dtype.storage == "python"
+        and right.dtype.na_value is np.nan
+    ):
+        assert np.all(
+            [np.isnan(val) for val in right._ndarray[right_na]]  # type: ignore[attr-defined]
+        ), "wrong missing value sentinels"
+
+    left_valid = left[~left_na].to_numpy(dtype=object)
+    right_valid = right[~right_na].to_numpy(dtype=object)
+    if check_exact:
+        assert_numpy_array_equal(
+            left_valid, right_valid, obj=obj, index_values=index_values
+        )
+    else:
+        _testing.assert_almost_equal(
+            left_valid,
+            right_valid,
+            check_dtype=bool(check_dtype),
+            rtol=rtol,
+            atol=atol,
+            obj=obj,
+            index_values=index_values,
+        )
+
+
+# This could be refactored to use the NDFrame.equals method
+def assert_series_equal(
+    left,
+    right,
+    check_dtype: bool | Literal["equiv"] = True,
+    check_index_type: bool | Literal["equiv"] = "equiv",
+    check_series_type: bool = True,
+    check_names: bool = True,
+    check_exact: bool | lib.NoDefault = lib.no_default,
+    check_datetimelike_compat: bool = False,
+    check_categorical: bool = True,
+    check_category_order: bool = True,
+    check_freq: bool = True,
+    check_flags: bool = True,
+    rtol: float | lib.NoDefault = lib.no_default,
+    atol: float | lib.NoDefault = lib.no_default,
+    obj: str = "Series",
+    *,
+    check_index: bool = True,
+    check_like: bool = False,
+) -> None:
+    """
+    Check that left and right Series are equal.
+
+    Parameters
+    ----------
+    left : Series
+    right : Series
+    check_dtype : bool, default True
+        Whether to check the Series dtype is identical.
+    check_index_type : bool or {'equiv'}, default 'equiv'
+        Whether to check the Index class, dtype and inferred_type
+        are identical.
+    check_series_type : bool, default True
+         Whether to check the Series class is identical.
+    check_names : bool, default True
+        Whether to check the Series and Index names attribute.
+    check_exact : bool, default False
+        Whether to compare number exactly.
+
+        .. versionchanged:: 2.2.0
+
+            Defaults to True for integer dtypes if none of
+            ``check_exact``, ``rtol`` and ``atol`` are specified.
+    check_datetimelike_compat : bool, default False
+        Compare datetime-like which is comparable ignoring dtype.
+    check_categorical : bool, default True
+        Whether to compare internal Categorical exactly.
+    check_category_order : bool, default True
+        Whether to compare category order of internal Categoricals.
+    check_freq : bool, default True
+        Whether to check the `freq` attribute on a DatetimeIndex or TimedeltaIndex.
+    check_flags : bool, default True
+        Whether to check the `flags` attribute.
+    rtol : float, default 1e-5
+        Relative tolerance. Only used when check_exact is False.
+    atol : float, default 1e-8
+        Absolute tolerance. Only used when check_exact is False.
+    obj : str, default 'Series'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+    check_index : bool, default True
+        Whether to check index equivalence. If False, then compare only values.
+
+        .. versionadded:: 1.3.0
+    check_like : bool, default False
+        If True, ignore the order of the index. Must be False if check_index is False.
+        Note: same labels must be with the same data.
+
+        .. versionadded:: 1.5.0
+
+    Examples
+    --------
+    >>> from pandas import testing as tm
+    >>> a = pd.Series([1, 2, 3, 4])
+    >>> b = pd.Series([1, 2, 3, 4])
+    >>> tm.assert_series_equal(a, b)
+    """
+    __tracebackhide__ = True
+    check_exact_index = False if check_exact is lib.no_default else check_exact
+    if (
+        check_exact is lib.no_default
+        and rtol is lib.no_default
+        and atol is lib.no_default
+    ):
+        check_exact = (
+            is_numeric_dtype(left.dtype)
+            and not is_float_dtype(left.dtype)
+            or is_numeric_dtype(right.dtype)
+            and not is_float_dtype(right.dtype)
+        )
+    elif check_exact is lib.no_default:
+        check_exact = False
+
+    rtol = rtol if rtol is not lib.no_default else 1.0e-5
+    atol = atol if atol is not lib.no_default else 1.0e-8
+
+    if not check_index and check_like:
+        raise ValueError("check_like must be False if check_index is False")
+
+    # instance validation
+    _check_isinstance(left, right, Series)
+
+    if check_series_type:
+        assert_class_equal(left, right, obj=obj)
+
+    # length comparison
+    if len(left) != len(right):
+        msg1 = f"{len(left)}, {left.index}"
+        msg2 = f"{len(right)}, {right.index}"
+        raise_assert_detail(obj, "Series length are different", msg1, msg2)
+
+    if check_flags:
+        assert left.flags == right.flags, f"{repr(left.flags)} != {repr(right.flags)}"
+
+    if check_index:
+        # GH #38183
+        assert_index_equal(
+            left.index,
+            right.index,
+            exact=check_index_type,
+            check_names=check_names,
+            check_exact=check_exact_index,
+            check_categorical=check_categorical,
+            check_order=not check_like,
+            rtol=rtol,
+            atol=atol,
+            obj=f"{obj}.index",
+        )
+
+    if check_like:
+        left = left.reindex_like(right)
+
+    if check_freq and isinstance(left.index, (DatetimeIndex, TimedeltaIndex)):
+        lidx = left.index
+        ridx = right.index
+        assert lidx.freq == ridx.freq, (lidx.freq, ridx.freq)
+
+    if check_dtype:
+        # We want to skip exact dtype checking when `check_categorical`
+        # is False. We'll still raise if only one is a `Categorical`,
+        # regardless of `check_categorical`
+        if (
+            isinstance(left.dtype, CategoricalDtype)
+            and isinstance(right.dtype, CategoricalDtype)
+            and not check_categorical
+        ):
+            pass
+        else:
+            assert_attr_equal("dtype", left, right, obj=f"Attributes of {obj}")
+    if check_exact:
+        left_values = left._values
+        right_values = right._values
+        # Only check exact if dtype is numeric
+        if isinstance(left_values, ExtensionArray) and isinstance(
+            right_values, ExtensionArray
+        ):
+            assert_extension_array_equal(
+                left_values,
+                right_values,
+                check_dtype=check_dtype,
+                index_values=left.index,
+                obj=str(obj),
+            )
+        else:
+            # convert both to NumPy if not, check_dtype would raise earlier
+            lv, rv = left_values, right_values
+            if isinstance(left_values, ExtensionArray):
+                lv = left_values.to_numpy()
+            if isinstance(right_values, ExtensionArray):
+                rv = right_values.to_numpy()
+            assert_numpy_array_equal(
+                lv,
+                rv,
+                check_dtype=check_dtype,
+                obj=str(obj),
+                index_values=left.index,
+            )
+    elif check_datetimelike_compat and (
+        needs_i8_conversion(left.dtype) or needs_i8_conversion(right.dtype)
+    ):
+        # we want to check only if we have compat dtypes
+        # e.g. integer and M|m are NOT compat, but we can simply check
+        # the values in that case
+
+        # datetimelike may have different objects (e.g. datetime.datetime
+        # vs Timestamp) but will compare equal
+        if not Index(left._values).equals(Index(right._values)):
+            msg = (
+                f"[datetimelike_compat=True] {left._values} "
+                f"is not equal to {right._values}."
+            )
+            raise AssertionError(msg)
+    elif isinstance(left.dtype, IntervalDtype) and isinstance(
+        right.dtype, IntervalDtype
+    ):
+        assert_interval_array_equal(left.array, right.array)
+    elif isinstance(left.dtype, CategoricalDtype) or isinstance(
+        right.dtype, CategoricalDtype
+    ):
+        _testing.assert_almost_equal(
+            left._values,
+            right._values,
+            rtol=rtol,
+            atol=atol,
+            check_dtype=bool(check_dtype),
+            obj=str(obj),
+            index_values=left.index,
+        )
+    elif isinstance(left.dtype, ExtensionDtype) and isinstance(
+        right.dtype, ExtensionDtype
+    ):
+        assert_extension_array_equal(
+            left._values,
+            right._values,
+            rtol=rtol,
+            atol=atol,
+            check_dtype=check_dtype,
+            index_values=left.index,
+            obj=str(obj),
+        )
+    elif is_extension_array_dtype_and_needs_i8_conversion(
+        left.dtype, right.dtype
+    ) or is_extension_array_dtype_and_needs_i8_conversion(right.dtype, left.dtype):
+        assert_extension_array_equal(
+            left._values,
+            right._values,
+            check_dtype=check_dtype,
+            index_values=left.index,
+            obj=str(obj),
+        )
+    elif needs_i8_conversion(left.dtype) and needs_i8_conversion(right.dtype):
+        # DatetimeArray or TimedeltaArray
+        assert_extension_array_equal(
+            left._values,
+            right._values,
+            check_dtype=check_dtype,
+            index_values=left.index,
+            obj=str(obj),
+        )
+    else:
+        _testing.assert_almost_equal(
+            left._values,
+            right._values,
+            rtol=rtol,
+            atol=atol,
+            check_dtype=bool(check_dtype),
+            obj=str(obj),
+            index_values=left.index,
+        )
+
+    # metadata comparison
+    if check_names:
+        assert_attr_equal("name", left, right, obj=obj)
+
+    if check_categorical:
+        if isinstance(left.dtype, CategoricalDtype) or isinstance(
+            right.dtype, CategoricalDtype
+        ):
+            assert_categorical_equal(
+                left._values,
+                right._values,
+                obj=f"{obj} category",
+                check_category_order=check_category_order,
+            )
+
+
+# This could be refactored to use the NDFrame.equals method
+def assert_frame_equal(
+    left,
+    right,
+    check_dtype: bool | Literal["equiv"] = True,
+    check_index_type: bool | Literal["equiv"] = "equiv",
+    check_column_type: bool | Literal["equiv"] = "equiv",
+    check_frame_type: bool = True,
+    check_names: bool = True,
+    by_blocks: bool = False,
+    check_exact: bool | lib.NoDefault = lib.no_default,
+    check_datetimelike_compat: bool = False,
+    check_categorical: bool = True,
+    check_like: bool = False,
+    check_freq: bool = True,
+    check_flags: bool = True,
+    rtol: float | lib.NoDefault = lib.no_default,
+    atol: float | lib.NoDefault = lib.no_default,
+    obj: str = "DataFrame",
+) -> None:
+    """
+    Check that left and right DataFrame are equal.
+
+    This function is intended to compare two DataFrames and output any
+    differences. It is mostly intended for use in unit tests.
+    Additional parameters allow varying the strictness of the
+    equality checks performed.
+
+    Parameters
+    ----------
+    left : DataFrame
+        First DataFrame to compare.
+    right : DataFrame
+        Second DataFrame to compare.
+    check_dtype : bool, default True
+        Whether to check the DataFrame dtype is identical.
+    check_index_type : bool or {'equiv'}, default 'equiv'
+        Whether to check the Index class, dtype and inferred_type
+        are identical.
+    check_column_type : bool or {'equiv'}, default 'equiv'
+        Whether to check the columns class, dtype and inferred_type
+        are identical. Is passed as the ``exact`` argument of
+        :func:`assert_index_equal`.
+    check_frame_type : bool, default True
+        Whether to check the DataFrame class is identical.
+    check_names : bool, default True
+        Whether to check that the `names` attribute for both the `index`
+        and `column` attributes of the DataFrame is identical.
+    by_blocks : bool, default False
+        Specify how to compare internal data. If False, compare by columns.
+        If True, compare by blocks.
+    check_exact : bool, default False
+        Whether to compare number exactly.
+
+        .. versionchanged:: 2.2.0
+
+            Defaults to True for integer dtypes if none of
+            ``check_exact``, ``rtol`` and ``atol`` are specified.
+    check_datetimelike_compat : bool, default False
+        Compare datetime-like which is comparable ignoring dtype.
+    check_categorical : bool, default True
+        Whether to compare internal Categorical exactly.
+    check_like : bool, default False
+        If True, ignore the order of index & columns.
+        Note: index labels must match their respective rows
+        (same as in columns) - same labels must be with the same data.
+    check_freq : bool, default True
+        Whether to check the `freq` attribute on a DatetimeIndex or TimedeltaIndex.
+    check_flags : bool, default True
+        Whether to check the `flags` attribute.
+    rtol : float, default 1e-5
+        Relative tolerance. Only used when check_exact is False.
+    atol : float, default 1e-8
+        Absolute tolerance. Only used when check_exact is False.
+    obj : str, default 'DataFrame'
+        Specify object name being compared, internally used to show appropriate
+        assertion message.
+
+    See Also
+    --------
+    assert_series_equal : Equivalent method for asserting Series equality.
+    DataFrame.equals : Check DataFrame equality.
+
+    Examples
+    --------
+    This example shows comparing two DataFrames that are equal
+    but with columns of differing dtypes.
+
+    >>> from pandas.testing import assert_frame_equal
+    >>> df1 = pd.DataFrame({'a': [1, 2], 'b': [3, 4]})
+    >>> df2 = pd.DataFrame({'a': [1, 2], 'b': [3.0, 4.0]})
+
+    df1 equals itself.
+
+    >>> assert_frame_equal(df1, df1)
+
+    df1 differs from df2 as column 'b' is of a different type.
+
+    >>> assert_frame_equal(df1, df2)
+    Traceback (most recent call last):
+    ...
+    AssertionError: Attributes of DataFrame.iloc[:, 1] (column name="b") are different
+
+    Attribute "dtype" are different
+    [left]:  int64
+    [right]: float64
+
+    Ignore differing dtypes in columns with check_dtype.
+
+    >>> assert_frame_equal(df1, df2, check_dtype=False)
+    """
+    __tracebackhide__ = True
+    _rtol = rtol if rtol is not lib.no_default else 1.0e-5
+    _atol = atol if atol is not lib.no_default else 1.0e-8
+    _check_exact = check_exact if check_exact is not lib.no_default else False
+
+    # instance validation
+    _check_isinstance(left, right, DataFrame)
+
+    if check_frame_type:
+        assert isinstance(left, type(right))
+        # assert_class_equal(left, right, obj=obj)
+
+    # shape comparison
+    if left.shape != right.shape:
+        raise_assert_detail(
+            obj, f"{obj} shape mismatch", f"{repr(left.shape)}", f"{repr(right.shape)}"
+        )
+
+    if check_flags:
+        assert left.flags == right.flags, f"{repr(left.flags)} != {repr(right.flags)}"
+
+    # index comparison
+    assert_index_equal(
+        left.index,
+        right.index,
+        exact=check_index_type,
+        check_names=check_names,
+        check_exact=_check_exact,
+        check_categorical=check_categorical,
+        check_order=not check_like,
+        rtol=_rtol,
+        atol=_atol,
+        obj=f"{obj}.index",
+    )
+
+    # column comparison
+    assert_index_equal(
+        left.columns,
+        right.columns,
+        exact=check_column_type,
+        check_names=check_names,
+        check_exact=_check_exact,
+        check_categorical=check_categorical,
+        check_order=not check_like,
+        rtol=_rtol,
+        atol=_atol,
+        obj=f"{obj}.columns",
+    )
+
+    if check_like:
+        left = left.reindex_like(right)
+
+    # compare by blocks
+    if by_blocks:
+        rblocks = right._to_dict_of_blocks()
+        lblocks = left._to_dict_of_blocks()
+        for dtype in list(set(list(lblocks.keys()) + list(rblocks.keys()))):
+            assert dtype in lblocks
+            assert dtype in rblocks
+            assert_frame_equal(
+                lblocks[dtype], rblocks[dtype], check_dtype=check_dtype, obj=obj
+            )
+
+    # compare by columns
+    else:
+        for i, col in enumerate(left.columns):
+            # We have already checked that columns match, so we can do
+            #  fast location-based lookups
+            lcol = left._ixs(i, axis=1)
+            rcol = right._ixs(i, axis=1)
+
+            # GH #38183
+            # use check_index=False, because we do not want to run
+            # assert_index_equal for each column,
+            # as we already checked it for the whole dataframe before.
+            assert_series_equal(
+                lcol,
+                rcol,
+                check_dtype=check_dtype,
+                check_index_type=check_index_type,
+                check_exact=check_exact,
+                check_names=check_names,
+                check_datetimelike_compat=check_datetimelike_compat,
+                check_categorical=check_categorical,
+                check_freq=check_freq,
+                obj=f'{obj}.iloc[:, {i}] (column name="{col}")',
+                rtol=rtol,
+                atol=atol,
+                check_index=False,
+                check_flags=False,
+            )
+
+
+def assert_equal(left, right, **kwargs) -> None:
+    """
+    Wrapper for tm.assert_*_equal to dispatch to the appropriate test function.
+
+    Parameters
+    ----------
+    left, right : Index, Series, DataFrame, ExtensionArray, or np.ndarray
+        The two items to be compared.
+    **kwargs
+        All keyword arguments are passed through to the underlying assert method.
+    """
+    __tracebackhide__ = True
+
+    if isinstance(left, Index):
+        assert_index_equal(left, right, **kwargs)
+        if isinstance(left, (DatetimeIndex, TimedeltaIndex)):
+            assert left.freq == right.freq, (left.freq, right.freq)
+    elif isinstance(left, Series):
+        assert_series_equal(left, right, **kwargs)
+    elif isinstance(left, DataFrame):
+        assert_frame_equal(left, right, **kwargs)
+    elif isinstance(left, IntervalArray):
+        assert_interval_array_equal(left, right, **kwargs)
+    elif isinstance(left, PeriodArray):
+        assert_period_array_equal(left, right, **kwargs)
+    elif isinstance(left, DatetimeArray):
+        assert_datetime_array_equal(left, right, **kwargs)
+    elif isinstance(left, TimedeltaArray):
+        assert_timedelta_array_equal(left, right, **kwargs)
+    elif isinstance(left, ExtensionArray):
+        assert_extension_array_equal(left, right, **kwargs)
+    elif isinstance(left, np.ndarray):
+        assert_numpy_array_equal(left, right, **kwargs)
+    elif isinstance(left, str):
+        assert kwargs == {}
+        assert left == right
+    else:
+        assert kwargs == {}
+        assert_almost_equal(left, right)
+
+
+def assert_sp_array_equal(left, right) -> None:
+    """
+    Check that the left and right SparseArray are equal.
+
+    Parameters
+    ----------
+    left : SparseArray
+    right : SparseArray
+    """
+    _check_isinstance(left, right, pd.arrays.SparseArray)
+
+    assert_numpy_array_equal(left.sp_values, right.sp_values)
+
+    # SparseIndex comparison
+    assert isinstance(left.sp_index, SparseIndex)
+    assert isinstance(right.sp_index, SparseIndex)
+
+    left_index = left.sp_index
+    right_index = right.sp_index
+
+    if not left_index.equals(right_index):
+        raise_assert_detail(
+            "SparseArray.index", "index are not equal", left_index, right_index
+        )
+    else:
+        # Just ensure a
+        pass
+
+    assert_attr_equal("fill_value", left, right)
+    assert_attr_equal("dtype", left, right)
+    assert_numpy_array_equal(left.to_dense(), right.to_dense())
+
+
+def assert_contains_all(iterable, dic) -> None:
+    for k in iterable:
+        assert k in dic, f"Did not contain item: {repr(k)}"
+
+
+def assert_copy(iter1, iter2, **eql_kwargs) -> None:
+    """
+    iter1, iter2: iterables that produce elements
+    comparable with assert_almost_equal
+
+    Checks that the elements are equal, but not
+    the same object. (Does not check that items
+    in sequences are also not the same object)
+    """
+    for elem1, elem2 in zip(iter1, iter2):
+        assert_almost_equal(elem1, elem2, **eql_kwargs)
+        msg = (
+            f"Expected object {repr(type(elem1))} and object {repr(type(elem2))} to be "
+            "different objects, but they were the same object."
+        )
+        assert elem1 is not elem2, msg
+
+
+def is_extension_array_dtype_and_needs_i8_conversion(
+    left_dtype: DtypeObj, right_dtype: DtypeObj
+) -> bool:
+    """
+    Checks that we have the combination of an ExtensionArraydtype and
+    a dtype that should be converted to int64
+
+    Returns
+    -------
+    bool
+
+    Related to issue #37609
+    """
+    return isinstance(left_dtype, ExtensionDtype) and needs_i8_conversion(right_dtype)
+
+
+def assert_indexing_slices_equivalent(ser: Series, l_slc: slice, i_slc: slice) -> None:
+    """
+    Check that ser.iloc[i_slc] matches ser.loc[l_slc] and, if applicable,
+    ser[l_slc].
+    """
+    expected = ser.iloc[i_slc]
+
+    assert_series_equal(ser.loc[l_slc], expected)
+
+    if not is_integer_dtype(ser.index):
+        # For integer indices, .loc and plain getitem are position-based.
+        assert_series_equal(ser[l_slc], expected)
+
+
+def assert_metadata_equivalent(
+    left: DataFrame | Series, right: DataFrame | Series | None = None
+) -> None:
+    """
+    Check that ._metadata attributes are equivalent.
+    """
+    for attr in left._metadata:
+        val = getattr(left, attr, None)
+        if right is None:
+            assert val is None
+        else:
+            assert val == getattr(right, attr, None)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/compat.py b/.venv/lib/python3.13/site-packages/pandas/_testing/compat.py
new file mode 100644
index 0000000000000000000000000000000000000000..cc352ba7b8f2f5a5548d4d5749d3b48ac838aced
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/compat.py
@@ -0,0 +1,29 @@
+"""
+Helpers for sharing tests between DataFrame/Series
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pandas import DataFrame
+
+if TYPE_CHECKING:
+    from pandas._typing import DtypeObj
+
+
+def get_dtype(obj) -> DtypeObj:
+    if isinstance(obj, DataFrame):
+        # Note: we are assuming only one column
+        return obj.dtypes.iat[0]
+    else:
+        return obj.dtype
+
+
+def get_obj(df: DataFrame, klass):
+    """
+    For sharing tests using frame_or_series, either return the DataFrame
+    unchanged or return it's first column as a Series.
+    """
+    if klass is DataFrame:
+        return df
+    return df._ixs(0, axis=1)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_testing/contexts.py b/.venv/lib/python3.13/site-packages/pandas/_testing/contexts.py
new file mode 100644
index 0000000000000000000000000000000000000000..aa409a90a22f86b03dbcabcce28d4f4663876a4b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_testing/contexts.py
@@ -0,0 +1,261 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+import os
+from pathlib import Path
+import tempfile
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+)
+import uuid
+
+from pandas._config import using_copy_on_write
+
+from pandas.compat import (
+    PYPY,
+    WARNING_CHECK_DISABLED,
+)
+from pandas.errors import ChainedAssignmentError
+
+from pandas import set_option
+
+from pandas.io.common import get_handle
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from pandas._typing import (
+        BaseBuffer,
+        CompressionOptions,
+        FilePath,
+    )
+
+
+@contextmanager
+def decompress_file(
+    path: FilePath | BaseBuffer, compression: CompressionOptions
+) -> Generator[IO[bytes], None, None]:
+    """
+    Open a compressed file and return a file object.
+
+    Parameters
+    ----------
+    path : str
+        The path where the file is read from.
+
+    compression : {'gzip', 'bz2', 'zip', 'xz', 'zstd', None}
+        Name of the decompression to use
+
+    Returns
+    -------
+    file object
+    """
+    with get_handle(path, "rb", compression=compression, is_text=False) as handle:
+        yield handle.handle
+
+
+@contextmanager
+def set_timezone(tz: str) -> Generator[None, None, None]:
+    """
+    Context manager for temporarily setting a timezone.
+
+    Parameters
+    ----------
+    tz : str
+        A string representing a valid timezone.
+
+    Examples
+    --------
+    >>> from datetime import datetime
+    >>> from dateutil.tz import tzlocal
+    >>> tzlocal().tzname(datetime(2021, 1, 1))  # doctest: +SKIP
+    'IST'
+
+    >>> with set_timezone('US/Eastern'):
+    ...     tzlocal().tzname(datetime(2021, 1, 1))
+    ...
+    'EST'
+    """
+    import time
+
+    def setTZ(tz) -> None:
+        if hasattr(time, "tzset"):
+            if tz is None:
+                try:
+                    del os.environ["TZ"]
+                except KeyError:
+                    pass
+            else:
+                os.environ["TZ"] = tz
+                time.tzset()
+
+    orig_tz = os.environ.get("TZ")
+    setTZ(tz)
+    try:
+        yield
+    finally:
+        setTZ(orig_tz)
+
+
+@contextmanager
+def ensure_clean(
+    filename=None, return_filelike: bool = False, **kwargs: Any
+) -> Generator[Any, None, None]:
+    """
+    Gets a temporary path and agrees to remove on close.
+
+    This implementation does not use tempfile.mkstemp to avoid having a file handle.
+    If the code using the returned path wants to delete the file itself, windows
+    requires that no program has a file handle to it.
+
+    Parameters
+    ----------
+    filename : str (optional)
+        suffix of the created file.
+    return_filelike : bool (default False)
+        if True, returns a file-like which is *always* cleaned. Necessary for
+        savefig and other functions which want to append extensions.
+    **kwargs
+        Additional keywords are passed to open().
+
+    """
+    folder = Path(tempfile.gettempdir())
+
+    if filename is None:
+        filename = ""
+    filename = str(uuid.uuid4()) + filename
+    path = folder / filename
+
+    path.touch()
+
+    handle_or_str: str | IO = str(path)
+    encoding = kwargs.pop("encoding", None)
+    if return_filelike:
+        kwargs.setdefault("mode", "w+b")
+        if encoding is None and "b" not in kwargs["mode"]:
+            encoding = "utf-8"
+        handle_or_str = open(path, encoding=encoding, **kwargs)
+
+    try:
+        yield handle_or_str
+    finally:
+        if not isinstance(handle_or_str, str):
+            handle_or_str.close()
+        if path.is_file():
+            path.unlink()
+
+
+@contextmanager
+def with_csv_dialect(name: str, **kwargs) -> Generator[None, None, None]:
+    """
+    Context manager to temporarily register a CSV dialect for parsing CSV.
+
+    Parameters
+    ----------
+    name : str
+        The name of the dialect.
+    kwargs : mapping
+        The parameters for the dialect.
+
+    Raises
+    ------
+    ValueError : the name of the dialect conflicts with a builtin one.
+
+    See Also
+    --------
+    csv : Python's CSV library.
+    """
+    import csv
+
+    _BUILTIN_DIALECTS = {"excel", "excel-tab", "unix"}
+
+    if name in _BUILTIN_DIALECTS:
+        raise ValueError("Cannot override builtin dialect.")
+
+    csv.register_dialect(name, **kwargs)
+    try:
+        yield
+    finally:
+        csv.unregister_dialect(name)
+
+
+@contextmanager
+def use_numexpr(use, min_elements=None) -> Generator[None, None, None]:
+    from pandas.core.computation import expressions as expr
+
+    if min_elements is None:
+        min_elements = expr._MIN_ELEMENTS
+
+    olduse = expr.USE_NUMEXPR
+    oldmin = expr._MIN_ELEMENTS
+    set_option("compute.use_numexpr", use)
+    expr._MIN_ELEMENTS = min_elements
+    try:
+        yield
+    finally:
+        expr._MIN_ELEMENTS = oldmin
+        set_option("compute.use_numexpr", olduse)
+
+
+def raises_chained_assignment_error(warn=True, extra_warnings=(), extra_match=()):
+    from pandas._testing import assert_produces_warning
+
+    if not warn:
+        from contextlib import nullcontext
+
+        return nullcontext()
+
+    if (PYPY or WARNING_CHECK_DISABLED) and not extra_warnings:
+        from contextlib import nullcontext
+
+        return nullcontext()
+    elif (PYPY or WARNING_CHECK_DISABLED) and extra_warnings:
+        return assert_produces_warning(
+            extra_warnings,
+            match="|".join(extra_match),
+        )
+    else:
+        if using_copy_on_write():
+            warning = ChainedAssignmentError
+            match = (
+                "A value is trying to be set on a copy of a DataFrame or Series "
+                "through chained assignment"
+            )
+        else:
+            warning = FutureWarning  # type: ignore[assignment]
+            # TODO update match
+            match = "ChainedAssignmentError"
+        if extra_warnings:
+            warning = (warning, *extra_warnings)  # type: ignore[assignment]
+        return assert_produces_warning(
+            warning,
+            match="|".join((match, *extra_match)),
+        )
+
+
+def assert_cow_warning(warn=True, match=None, **kwargs):
+    """
+    Assert that a warning is raised in the CoW warning mode.
+
+    Parameters
+    ----------
+    warn : bool, default True
+        By default, check that a warning is raised. Can be turned off by passing False.
+    match : str
+        The warning message to match against, if different from the default.
+    kwargs
+        Passed through to assert_produces_warning
+    """
+    from pandas._testing import assert_produces_warning
+
+    if not warn or WARNING_CHECK_DISABLED:
+        from contextlib import nullcontext
+
+        return nullcontext()
+
+    if not match:
+        match = "Setting a value on a view"
+
+    return assert_produces_warning(FutureWarning, match=match, **kwargs)
diff --git a/.venv/lib/python3.13/site-packages/pandas/_typing.py b/.venv/lib/python3.13/site-packages/pandas/_typing.py
new file mode 100644
index 0000000000000000000000000000000000000000..3df9a47a35fca32547947560a8df1cea1d1863c2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_typing.py
@@ -0,0 +1,525 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterator,
+    Mapping,
+    MutableMapping,
+    Sequence,
+)
+from datetime import (
+    date,
+    datetime,
+    timedelta,
+    tzinfo,
+)
+from os import PathLike
+import sys
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    Optional,
+    Protocol,
+    Type as type_t,
+    TypeVar,
+    Union,
+    overload,
+)
+
+import numpy as np
+
+# To prevent import cycles place any internal imports in the branch below
+# and use a string literal forward reference to it in subsequent types
+# https://mypy.readthedocs.io/en/latest/common_issues.html#import-cycles
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+    from pandas._libs import (
+        NaTType,
+        Period,
+        Timedelta,
+        Timestamp,
+    )
+    from pandas._libs.tslibs import BaseOffset
+
+    from pandas.core.dtypes.dtypes import ExtensionDtype
+
+    from pandas import Interval
+    from pandas.arrays import (
+        DatetimeArray,
+        TimedeltaArray,
+    )
+    from pandas.core.arrays.base import ExtensionArray
+    from pandas.core.frame import DataFrame
+    from pandas.core.generic import NDFrame
+    from pandas.core.groupby.generic import (
+        DataFrameGroupBy,
+        GroupBy,
+        SeriesGroupBy,
+    )
+    from pandas.core.indexes.base import Index
+    from pandas.core.internals import (
+        ArrayManager,
+        BlockManager,
+        SingleArrayManager,
+        SingleBlockManager,
+    )
+    from pandas.core.resample import Resampler
+    from pandas.core.series import Series
+    from pandas.core.window.rolling import BaseWindow
+
+    from pandas.io.formats.format import EngFormatter
+    from pandas.tseries.holiday import AbstractHolidayCalendar
+
+    ScalarLike_co = Union[
+        int,
+        float,
+        complex,
+        str,
+        bytes,
+        np.generic,
+    ]
+
+    # numpy compatible types
+    NumpyValueArrayLike = Union[ScalarLike_co, npt.ArrayLike]
+    # Name "npt._ArrayLikeInt_co" is not defined  [name-defined]
+    NumpySorter = Optional[npt._ArrayLikeInt_co]  # type: ignore[name-defined]
+
+    from typing import SupportsIndex
+
+    if sys.version_info >= (3, 10):
+        from typing import TypeGuard  # pyright: ignore[reportUnusedImport]
+    else:
+        from typing_extensions import TypeGuard  # pyright: ignore[reportUnusedImport]
+
+    if sys.version_info >= (3, 11):
+        from typing import Self  # pyright: ignore[reportUnusedImport]
+    else:
+        from typing_extensions import Self  # pyright: ignore[reportUnusedImport]
+else:
+    npt: Any = None
+    Self: Any = None
+    TypeGuard: Any = None
+
+HashableT = TypeVar("HashableT", bound=Hashable)
+MutableMappingT = TypeVar("MutableMappingT", bound=MutableMapping)
+
+# array-like
+
+ArrayLike = Union["ExtensionArray", np.ndarray]
+AnyArrayLike = Union[ArrayLike, "Index", "Series"]
+TimeArrayLike = Union["DatetimeArray", "TimedeltaArray"]
+
+# list-like
+
+# from https://github.com/hauntsaninja/useful_types
+# includes Sequence-like objects but excludes str and bytes
+_T_co = TypeVar("_T_co", covariant=True)
+
+
+class SequenceNotStr(Protocol[_T_co]):
+    @overload
+    def __getitem__(self, index: SupportsIndex, /) -> _T_co:
+        ...
+
+    @overload
+    def __getitem__(self, index: slice, /) -> Sequence[_T_co]:
+        ...
+
+    def __contains__(self, value: object, /) -> bool:
+        ...
+
+    def __len__(self) -> int:
+        ...
+
+    def __iter__(self) -> Iterator[_T_co]:
+        ...
+
+    def index(self, value: Any, /, start: int = 0, stop: int = ...) -> int:
+        ...
+
+    def count(self, value: Any, /) -> int:
+        ...
+
+    def __reversed__(self) -> Iterator[_T_co]:
+        ...
+
+
+ListLike = Union[AnyArrayLike, SequenceNotStr, range]
+
+# scalars
+
+PythonScalar = Union[str, float, bool]
+DatetimeLikeScalar = Union["Period", "Timestamp", "Timedelta"]
+PandasScalar = Union["Period", "Timestamp", "Timedelta", "Interval"]
+Scalar = Union[PythonScalar, PandasScalar, np.datetime64, np.timedelta64, date]
+IntStrT = TypeVar("IntStrT", bound=Union[int, str])
+
+
+# timestamp and timedelta convertible types
+
+TimestampConvertibleTypes = Union[
+    "Timestamp", date, np.datetime64, np.int64, float, str
+]
+TimestampNonexistent = Union[
+    Literal["shift_forward", "shift_backward", "NaT", "raise"], timedelta
+]
+TimedeltaConvertibleTypes = Union[
+    "Timedelta", timedelta, np.timedelta64, np.int64, float, str
+]
+Timezone = Union[str, tzinfo]
+
+ToTimestampHow = Literal["s", "e", "start", "end"]
+
+# NDFrameT is stricter and ensures that the same subclass of NDFrame always is
+# used. E.g. `def func(a: NDFrameT) -> NDFrameT: ...` means that if a
+# Series is passed into a function, a Series is always returned and if a DataFrame is
+# passed in, a DataFrame is always returned.
+NDFrameT = TypeVar("NDFrameT", bound="NDFrame")
+
+NumpyIndexT = TypeVar("NumpyIndexT", np.ndarray, "Index")
+
+AxisInt = int
+Axis = Union[AxisInt, Literal["index", "columns", "rows"]]
+IndexLabel = Union[Hashable, Sequence[Hashable]]
+Level = Hashable
+Shape = tuple[int, ...]
+Suffixes = tuple[Optional[str], Optional[str]]
+Ordered = Optional[bool]
+JSONSerializable = Optional[Union[PythonScalar, list, dict]]
+Frequency = Union[str, "BaseOffset"]
+Axes = ListLike
+
+RandomState = Union[
+    int,
+    np.ndarray,
+    np.random.Generator,
+    np.random.BitGenerator,
+    np.random.RandomState,
+]
+
+# dtypes
+NpDtype = Union[str, np.dtype, type_t[Union[str, complex, bool, object]]]
+Dtype = Union["ExtensionDtype", NpDtype]
+AstypeArg = Union["ExtensionDtype", "npt.DTypeLike"]
+# DtypeArg specifies all allowable dtypes in a functions its dtype argument
+DtypeArg = Union[Dtype, dict[Hashable, Dtype]]
+DtypeObj = Union[np.dtype, "ExtensionDtype"]
+
+# converters
+ConvertersArg = dict[Hashable, Callable[[Dtype], Dtype]]
+
+# parse_dates
+ParseDatesArg = Union[
+    bool, list[Hashable], list[list[Hashable]], dict[Hashable, list[Hashable]]
+]
+
+# For functions like rename that convert one label to another
+Renamer = Union[Mapping[Any, Hashable], Callable[[Any], Hashable]]
+
+# to maintain type information across generic functions and parametrization
+T = TypeVar("T")
+
+# used in decorators to preserve the signature of the function it decorates
+# see https://mypy.readthedocs.io/en/stable/generics.html#declaring-decorators
+FuncType = Callable[..., Any]
+F = TypeVar("F", bound=FuncType)
+
+# types of vectorized key functions for DataFrame::sort_values and
+# DataFrame::sort_index, among others
+ValueKeyFunc = Optional[Callable[["Series"], Union["Series", AnyArrayLike]]]
+IndexKeyFunc = Optional[Callable[["Index"], Union["Index", AnyArrayLike]]]
+
+# types of `func` kwarg for DataFrame.aggregate and Series.aggregate
+AggFuncTypeBase = Union[Callable, str]
+AggFuncTypeDict = MutableMapping[
+    Hashable, Union[AggFuncTypeBase, list[AggFuncTypeBase]]
+]
+AggFuncType = Union[
+    AggFuncTypeBase,
+    list[AggFuncTypeBase],
+    AggFuncTypeDict,
+]
+AggObjType = Union[
+    "Series",
+    "DataFrame",
+    "GroupBy",
+    "SeriesGroupBy",
+    "DataFrameGroupBy",
+    "BaseWindow",
+    "Resampler",
+]
+
+PythonFuncType = Callable[[Any], Any]
+
+# filenames and file-like-objects
+AnyStr_co = TypeVar("AnyStr_co", str, bytes, covariant=True)
+AnyStr_contra = TypeVar("AnyStr_contra", str, bytes, contravariant=True)
+
+
+class BaseBuffer(Protocol):
+    @property
+    def mode(self) -> str:
+        # for _get_filepath_or_buffer
+        ...
+
+    def seek(self, __offset: int, __whence: int = ...) -> int:
+        # with one argument: gzip.GzipFile, bz2.BZ2File
+        # with two arguments: zip.ZipFile, read_sas
+        ...
+
+    def seekable(self) -> bool:
+        # for bz2.BZ2File
+        ...
+
+    def tell(self) -> int:
+        # for zip.ZipFile, read_stata, to_stata
+        ...
+
+
+class ReadBuffer(BaseBuffer, Protocol[AnyStr_co]):
+    def read(self, __n: int = ...) -> AnyStr_co:
+        # for BytesIOWrapper, gzip.GzipFile, bz2.BZ2File
+        ...
+
+
+class WriteBuffer(BaseBuffer, Protocol[AnyStr_contra]):
+    def write(self, __b: AnyStr_contra) -> Any:
+        # for gzip.GzipFile, bz2.BZ2File
+        ...
+
+    def flush(self) -> Any:
+        # for gzip.GzipFile, bz2.BZ2File
+        ...
+
+
+class ReadPickleBuffer(ReadBuffer[bytes], Protocol):
+    def readline(self) -> bytes:
+        ...
+
+
+class WriteExcelBuffer(WriteBuffer[bytes], Protocol):
+    def truncate(self, size: int | None = ...) -> int:
+        ...
+
+
+class ReadCsvBuffer(ReadBuffer[AnyStr_co], Protocol):
+    def __iter__(self) -> Iterator[AnyStr_co]:
+        # for engine=python
+        ...
+
+    def fileno(self) -> int:
+        # for _MMapWrapper
+        ...
+
+    def readline(self) -> AnyStr_co:
+        # for engine=python
+        ...
+
+    @property
+    def closed(self) -> bool:
+        # for enine=pyarrow
+        ...
+
+
+FilePath = Union[str, "PathLike[str]"]
+
+# for arbitrary kwargs passed during reading/writing files
+StorageOptions = Optional[dict[str, Any]]
+
+
+# compression keywords and compression
+CompressionDict = dict[str, Any]
+CompressionOptions = Optional[
+    Union[Literal["infer", "gzip", "bz2", "zip", "xz", "zstd", "tar"], CompressionDict]
+]
+
+# types in DataFrameFormatter
+FormattersType = Union[
+    list[Callable], tuple[Callable, ...], Mapping[Union[str, int], Callable]
+]
+ColspaceType = Mapping[Hashable, Union[str, int]]
+FloatFormatType = Union[str, Callable, "EngFormatter"]
+ColspaceArgType = Union[
+    str, int, Sequence[Union[str, int]], Mapping[Hashable, Union[str, int]]
+]
+
+# Arguments for fillna()
+FillnaOptions = Literal["backfill", "bfill", "ffill", "pad"]
+InterpolateOptions = Literal[
+    "linear",
+    "time",
+    "index",
+    "values",
+    "nearest",
+    "zero",
+    "slinear",
+    "quadratic",
+    "cubic",
+    "barycentric",
+    "polynomial",
+    "krogh",
+    "piecewise_polynomial",
+    "spline",
+    "pchip",
+    "akima",
+    "cubicspline",
+    "from_derivatives",
+]
+
+# internals
+Manager = Union[
+    "ArrayManager", "SingleArrayManager", "BlockManager", "SingleBlockManager"
+]
+SingleManager = Union["SingleArrayManager", "SingleBlockManager"]
+Manager2D = Union["ArrayManager", "BlockManager"]
+
+# indexing
+# PositionalIndexer -> valid 1D positional indexer, e.g. can pass
+# to ndarray.__getitem__
+# ScalarIndexer is for a single value as the index
+# SequenceIndexer is for list like or slices (but not tuples)
+# PositionalIndexerTuple is extends the PositionalIndexer for 2D arrays
+# These are used in various __getitem__ overloads
+# TODO(typing#684): add Ellipsis, see
+# https://github.com/python/typing/issues/684#issuecomment-548203158
+# https://bugs.python.org/issue41810
+# Using List[int] here rather than Sequence[int] to disallow tuples.
+ScalarIndexer = Union[int, np.integer]
+SequenceIndexer = Union[slice, list[int], np.ndarray]
+PositionalIndexer = Union[ScalarIndexer, SequenceIndexer]
+PositionalIndexerTuple = tuple[PositionalIndexer, PositionalIndexer]
+PositionalIndexer2D = Union[PositionalIndexer, PositionalIndexerTuple]
+if TYPE_CHECKING:
+    TakeIndexer = Union[Sequence[int], Sequence[np.integer], npt.NDArray[np.integer]]
+else:
+    TakeIndexer = Any
+
+# Shared by functions such as drop and astype
+IgnoreRaise = Literal["ignore", "raise"]
+
+# Windowing rank methods
+WindowingRankType = Literal["average", "min", "max"]
+
+# read_csv engines
+CSVEngine = Literal["c", "python", "pyarrow", "python-fwf"]
+
+# read_json engines
+JSONEngine = Literal["ujson", "pyarrow"]
+
+# read_xml parsers
+XMLParsers = Literal["lxml", "etree"]
+
+# read_html flavors
+HTMLFlavors = Literal["lxml", "html5lib", "bs4"]
+
+# Interval closed type
+IntervalLeftRight = Literal["left", "right"]
+IntervalClosedType = Union[IntervalLeftRight, Literal["both", "neither"]]
+
+# datetime and NaTType
+DatetimeNaTType = Union[datetime, "NaTType"]
+DateTimeErrorChoices = Union[IgnoreRaise, Literal["coerce"]]
+
+# sort_index
+SortKind = Literal["quicksort", "mergesort", "heapsort", "stable"]
+NaPosition = Literal["first", "last"]
+
+# Arguments for nsmalles and n_largest
+NsmallestNlargestKeep = Literal["first", "last", "all"]
+
+# quantile interpolation
+QuantileInterpolation = Literal["linear", "lower", "higher", "midpoint", "nearest"]
+
+# plotting
+PlottingOrientation = Literal["horizontal", "vertical"]
+
+# dropna
+AnyAll = Literal["any", "all"]
+
+# merge
+MergeHow = Literal["left", "right", "inner", "outer", "cross"]
+MergeValidate = Literal[
+    "one_to_one",
+    "1:1",
+    "one_to_many",
+    "1:m",
+    "many_to_one",
+    "m:1",
+    "many_to_many",
+    "m:m",
+]
+
+# join
+JoinHow = Literal["left", "right", "inner", "outer"]
+JoinValidate = Literal[
+    "one_to_one",
+    "1:1",
+    "one_to_many",
+    "1:m",
+    "many_to_one",
+    "m:1",
+    "many_to_many",
+    "m:m",
+]
+
+# reindex
+ReindexMethod = Union[FillnaOptions, Literal["nearest"]]
+
+MatplotlibColor = Union[str, Sequence[float]]
+TimeGrouperOrigin = Union[
+    "Timestamp", Literal["epoch", "start", "start_day", "end", "end_day"]
+]
+TimeAmbiguous = Union[Literal["infer", "NaT", "raise"], "npt.NDArray[np.bool_]"]
+TimeNonexistent = Union[
+    Literal["shift_forward", "shift_backward", "NaT", "raise"], timedelta
+]
+DropKeep = Literal["first", "last", False]
+CorrelationMethod = Union[
+    Literal["pearson", "kendall", "spearman"], Callable[[np.ndarray, np.ndarray], float]
+]
+AlignJoin = Literal["outer", "inner", "left", "right"]
+DtypeBackend = Literal["pyarrow", "numpy_nullable"]
+
+TimeUnit = Literal["s", "ms", "us", "ns"]
+OpenFileErrors = Literal[
+    "strict",
+    "ignore",
+    "replace",
+    "surrogateescape",
+    "xmlcharrefreplace",
+    "backslashreplace",
+    "namereplace",
+]
+
+# update
+UpdateJoin = Literal["left"]
+
+# applymap
+NaAction = Literal["ignore"]
+
+# from_dict
+FromDictOrient = Literal["columns", "index", "tight"]
+
+# to_gbc
+ToGbqIfexist = Literal["fail", "replace", "append"]
+
+# to_stata
+ToStataByteorder = Literal[">", "<", "little", "big"]
+
+# ExcelWriter
+ExcelWriterIfSheetExists = Literal["error", "new", "replace", "overlay"]
+
+# Offsets
+OffsetCalendar = Union[np.busdaycalendar, "AbstractHolidayCalendar"]
+
+# read_csv: usecols
+UsecolsArgType = Union[
+    SequenceNotStr[Hashable],
+    range,
+    AnyArrayLike,
+    Callable[[HashableT], bool],
+    None,
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/_version.py b/.venv/lib/python3.13/site-packages/pandas/_version.py
new file mode 100644
index 0000000000000000000000000000000000000000..a4d9a4555018d906c11433c95ef0277a7550c862
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_version.py
@@ -0,0 +1,692 @@
+# This file helps to compute a version number in source trees obtained from
+# git-archive tarball (such as those provided by githubs download-from-tag
+# feature). Distribution tarballs (built by setup.py sdist) and build
+# directories (produced by setup.py build) will contain a much shorter file
+# that just contains the computed version number.
+
+# This file is released into the public domain.
+# Generated by versioneer-0.28
+# https://github.com/python-versioneer/python-versioneer
+
+"""Git implementation of _version.py."""
+
+import errno
+import functools
+import os
+import re
+import subprocess
+import sys
+from typing import Callable
+
+
+def get_keywords():
+    """Get the keywords needed to look up the version information."""
+    # these strings will be replaced by git during git-archive.
+    # setup.py/versioneer.py will grep for the variable names, so they must
+    # each be defined on a line of their own. _version.py will just call
+    # get_keywords().
+    git_refnames = " (HEAD, tag: v2.3.3, origin/2.3.x)"
+    git_full = "9c8bc3e55188c8aff37207a74f1dd144980b8874"
+    git_date = "2025-09-30 00:12:09 +0200"
+    keywords = {"refnames": git_refnames, "full": git_full, "date": git_date}
+    return keywords
+
+
+class VersioneerConfig:
+    """Container for Versioneer configuration parameters."""
+
+
+def get_config():
+    """Create, populate and return the VersioneerConfig() object."""
+    # these strings are filled in when 'setup.py versioneer' creates
+    # _version.py
+    cfg = VersioneerConfig()
+    cfg.VCS = "git"
+    cfg.style = "pep440"
+    cfg.tag_prefix = "v"
+    cfg.parentdir_prefix = "pandas-"
+    cfg.versionfile_source = "pandas/_version.py"
+    cfg.verbose = False
+    return cfg
+
+
+class NotThisMethod(Exception):
+    """Exception raised if a method is not valid for the current scenario."""
+
+
+LONG_VERSION_PY: dict[str, str] = {}
+HANDLERS: dict[str, dict[str, Callable]] = {}
+
+
+def register_vcs_handler(vcs, method):  # decorator
+    """Create decorator to mark a method as the handler of a VCS."""
+
+    def decorate(f):
+        """Store f in HANDLERS[vcs][method]."""
+        if vcs not in HANDLERS:
+            HANDLERS[vcs] = {}
+        HANDLERS[vcs][method] = f
+        return f
+
+    return decorate
+
+
+def run_command(commands, args, cwd=None, verbose=False, hide_stderr=False, env=None):
+    """Call the given command(s)."""
+    assert isinstance(commands, list)
+    process = None
+
+    popen_kwargs = {}
+    if sys.platform == "win32":
+        # This hides the console window if pythonw.exe is used
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        popen_kwargs["startupinfo"] = startupinfo
+
+    for command in commands:
+        dispcmd = str([command] + args)
+        try:
+            # remember shell=False, so use git.cmd on windows, not just git
+            process = subprocess.Popen(
+                [command] + args,
+                cwd=cwd,
+                env=env,
+                stdout=subprocess.PIPE,
+                stderr=(subprocess.PIPE if hide_stderr else None),
+                **popen_kwargs,
+            )
+            break
+        except OSError:
+            e = sys.exc_info()[1]
+            if e.errno == errno.ENOENT:
+                continue
+            if verbose:
+                print(f"unable to run {dispcmd}")
+                print(e)
+            return None, None
+    else:
+        if verbose:
+            print(f"unable to find command, tried {commands}")
+        return None, None
+    stdout = process.communicate()[0].strip().decode()
+    if process.returncode != 0:
+        if verbose:
+            print(f"unable to run {dispcmd} (error)")
+            print(f"stdout was {stdout}")
+        return None, process.returncode
+    return stdout, process.returncode
+
+
+def versions_from_parentdir(parentdir_prefix, root, verbose):
+    """Try to determine the version from the parent directory name.
+
+    Source tarballs conventionally unpack into a directory that includes both
+    the project name and a version string. We will also support searching up
+    two directory levels for an appropriately named parent directory
+    """
+    rootdirs = []
+
+    for _ in range(3):
+        dirname = os.path.basename(root)
+        if dirname.startswith(parentdir_prefix):
+            return {
+                "version": dirname[len(parentdir_prefix) :],
+                "full-revisionid": None,
+                "dirty": False,
+                "error": None,
+                "date": None,
+            }
+        rootdirs.append(root)
+        root = os.path.dirname(root)  # up a level
+
+    if verbose:
+        print(
+            f"Tried directories {str(rootdirs)} \
+            but none started with prefix {parentdir_prefix}"
+        )
+    raise NotThisMethod("rootdir doesn't start with parentdir_prefix")
+
+
+@register_vcs_handler("git", "get_keywords")
+def git_get_keywords(versionfile_abs):
+    """Extract version information from the given file."""
+    # the code embedded in _version.py can just fetch the value of these
+    # keywords. When used from setup.py, we don't want to import _version.py,
+    # so we do it with a regexp instead. This function is not used from
+    # _version.py.
+    keywords = {}
+    try:
+        with open(versionfile_abs, encoding="utf-8") as fobj:
+            for line in fobj:
+                if line.strip().startswith("git_refnames ="):
+                    mo = re.search(r'=\s*"(.*)"', line)
+                    if mo:
+                        keywords["refnames"] = mo.group(1)
+                if line.strip().startswith("git_full ="):
+                    mo = re.search(r'=\s*"(.*)"', line)
+                    if mo:
+                        keywords["full"] = mo.group(1)
+                if line.strip().startswith("git_date ="):
+                    mo = re.search(r'=\s*"(.*)"', line)
+                    if mo:
+                        keywords["date"] = mo.group(1)
+    except OSError:
+        pass
+    return keywords
+
+
+@register_vcs_handler("git", "keywords")
+def git_versions_from_keywords(keywords, tag_prefix, verbose):
+    """Get version information from git keywords."""
+    if "refnames" not in keywords:
+        raise NotThisMethod("Short version file found")
+    date = keywords.get("date")
+    if date is not None:
+        # Use only the last line.  Previous lines may contain GPG signature
+        # information.
+        date = date.splitlines()[-1]
+
+        # git-2.2.0 added "%cI", which expands to an ISO-8601 -compliant
+        # datestamp. However we prefer "%ci" (which expands to an "ISO-8601
+        # -like" string, which we must then edit to make compliant), because
+        # it's been around since git-1.5.3, and it's too difficult to
+        # discover which version we're using, or to work around using an
+        # older one.
+        date = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
+    refnames = keywords["refnames"].strip()
+    if refnames.startswith("$Format"):
+        if verbose:
+            print("keywords are unexpanded, not using")
+        raise NotThisMethod("unexpanded keywords, not a git-archive tarball")
+    refs = {r.strip() for r in refnames.strip("()").split(",")}
+    # starting in git-1.8.3, tags are listed as "tag: foo-1.0" instead of
+    # just "foo-1.0". If we see a "tag: " prefix, prefer those.
+    TAG = "tag: "
+    tags = {r[len(TAG) :] for r in refs if r.startswith(TAG)}
+    if not tags:
+        # Either we're using git < 1.8.3, or there really are no tags. We use
+        # a heuristic: assume all version tags have a digit. The old git %d
+        # expansion behaves like git log --decorate=short and strips out the
+        # refs/heads/ and refs/tags/ prefixes that would let us distinguish
+        # between branches and tags. By ignoring refnames without digits, we
+        # filter out many common branch names like "release" and
+        # "stabilization", as well as "HEAD" and "master".
+        tags = {r for r in refs if re.search(r"\d", r)}
+        if verbose:
+            print(f"discarding '{','.join(refs - tags)}', no digits")
+    if verbose:
+        print(f"likely tags: {','.join(sorted(tags))}")
+    for ref in sorted(tags):
+        # sorting will prefer e.g. "2.0" over "2.0rc1"
+        if ref.startswith(tag_prefix):
+            r = ref[len(tag_prefix) :]
+            # Filter out refs that exactly match prefix or that don't start
+            # with a number once the prefix is stripped (mostly a concern
+            # when prefix is '')
+            if not re.match(r"\d", r):
+                continue
+            if verbose:
+                print(f"picking {r}")
+            return {
+                "version": r,
+                "full-revisionid": keywords["full"].strip(),
+                "dirty": False,
+                "error": None,
+                "date": date,
+            }
+    # no suitable tags, so version is "0+unknown", but full hex is still there
+    if verbose:
+        print("no suitable tags, using unknown + full revision id")
+    return {
+        "version": "0+unknown",
+        "full-revisionid": keywords["full"].strip(),
+        "dirty": False,
+        "error": "no suitable tags",
+        "date": None,
+    }
+
+
+@register_vcs_handler("git", "pieces_from_vcs")
+def git_pieces_from_vcs(tag_prefix, root, verbose, runner=run_command):
+    """Get version from 'git describe' in the root of the source tree.
+
+    This only gets called if the git-archive 'subst' keywords were *not*
+    expanded, and _version.py hasn't already been rewritten with a short
+    version string, meaning we're inside a checked out source tree.
+    """
+    GITS = ["git"]
+    if sys.platform == "win32":
+        GITS = ["git.cmd", "git.exe"]
+
+    # GIT_DIR can interfere with correct operation of Versioneer.
+    # It may be intended to be passed to the Versioneer-versioned project,
+    # but that should not change where we get our version from.
+    env = os.environ.copy()
+    env.pop("GIT_DIR", None)
+    runner = functools.partial(runner, env=env)
+
+    _, rc = runner(GITS, ["rev-parse", "--git-dir"], cwd=root, hide_stderr=not verbose)
+    if rc != 0:
+        if verbose:
+            print(f"Directory {root} not under git control")
+        raise NotThisMethod("'git rev-parse --git-dir' returned error")
+
+    # if there is a tag matching tag_prefix, this yields TAG-NUM-gHEX[-dirty]
+    # if there isn't one, this yields HEX[-dirty] (no NUM)
+    describe_out, rc = runner(
+        GITS,
+        [
+            "describe",
+            "--tags",
+            "--dirty",
+            "--always",
+            "--long",
+            "--match",
+            f"{tag_prefix}[[:digit:]]*",
+        ],
+        cwd=root,
+    )
+    # --long was added in git-1.5.5
+    if describe_out is None:
+        raise NotThisMethod("'git describe' failed")
+    describe_out = describe_out.strip()
+    full_out, rc = runner(GITS, ["rev-parse", "HEAD"], cwd=root)
+    if full_out is None:
+        raise NotThisMethod("'git rev-parse' failed")
+    full_out = full_out.strip()
+
+    pieces = {}
+    pieces["long"] = full_out
+    pieces["short"] = full_out[:7]  # maybe improved later
+    pieces["error"] = None
+
+    branch_name, rc = runner(GITS, ["rev-parse", "--abbrev-ref", "HEAD"], cwd=root)
+    # --abbrev-ref was added in git-1.6.3
+    if rc != 0 or branch_name is None:
+        raise NotThisMethod("'git rev-parse --abbrev-ref' returned error")
+    branch_name = branch_name.strip()
+
+    if branch_name == "HEAD":
+        # If we aren't exactly on a branch, pick a branch which represents
+        # the current commit. If all else fails, we are on a branchless
+        # commit.
+        branches, rc = runner(GITS, ["branch", "--contains"], cwd=root)
+        # --contains was added in git-1.5.4
+        if rc != 0 or branches is None:
+            raise NotThisMethod("'git branch --contains' returned error")
+        branches = branches.split("\n")
+
+        # Remove the first line if we're running detached
+        if "(" in branches[0]:
+            branches.pop(0)
+
+        # Strip off the leading "* " from the list of branches.
+        branches = [branch[2:] for branch in branches]
+        if "master" in branches:
+            branch_name = "master"
+        elif not branches:
+            branch_name = None
+        else:
+            # Pick the first branch that is returned. Good or bad.
+            branch_name = branches[0]
+
+    pieces["branch"] = branch_name
+
+    # parse describe_out. It will be like TAG-NUM-gHEX[-dirty] or HEX[-dirty]
+    # TAG might have hyphens.
+    git_describe = describe_out
+
+    # look for -dirty suffix
+    dirty = git_describe.endswith("-dirty")
+    pieces["dirty"] = dirty
+    if dirty:
+        git_describe = git_describe[: git_describe.rindex("-dirty")]
+
+    # now we have TAG-NUM-gHEX or HEX
+
+    if "-" in git_describe:
+        # TAG-NUM-gHEX
+        mo = re.search(r"^(.+)-(\d+)-g([0-9a-f]+)$", git_describe)
+        if not mo:
+            # unparsable. Maybe git-describe is misbehaving?
+            pieces["error"] = f"unable to parse git-describe output: '{describe_out}'"
+            return pieces
+
+        # tag
+        full_tag = mo.group(1)
+        if not full_tag.startswith(tag_prefix):
+            if verbose:
+                fmt = "tag '%s' doesn't start with prefix '%s'"
+                print(fmt % (full_tag, tag_prefix))
+            pieces[
+                "error"
+            ] = f"tag '{full_tag}' doesn't start with prefix '{tag_prefix}'"
+            return pieces
+        pieces["closest-tag"] = full_tag[len(tag_prefix) :]
+
+        # distance: number of commits since tag
+        pieces["distance"] = int(mo.group(2))
+
+        # commit: short hex revision ID
+        pieces["short"] = mo.group(3)
+
+    else:
+        # HEX: no tags
+        pieces["closest-tag"] = None
+        out, rc = runner(GITS, ["rev-list", "HEAD", "--left-right"], cwd=root)
+        pieces["distance"] = len(out.split())  # total number of commits
+
+    # commit date: see ISO-8601 comment in git_versions_from_keywords()
+    date = runner(GITS, ["show", "-s", "--format=%ci", "HEAD"], cwd=root)[0].strip()
+    # Use only the last line.  Previous lines may contain GPG signature
+    # information.
+    date = date.splitlines()[-1]
+    pieces["date"] = date.strip().replace(" ", "T", 1).replace(" ", "", 1)
+
+    return pieces
+
+
+def plus_or_dot(pieces) -> str:
+    """Return a + if we don't already have one, else return a ."""
+    if "+" in pieces.get("closest-tag", ""):
+        return "."
+    return "+"
+
+
+def render_pep440(pieces):
+    """Build up version string, with post-release "local version identifier".
+
+    Our goal: TAG[+DISTANCE.gHEX[.dirty]] . Note that if you
+    get a tagged build and then dirty it, you'll get TAG+0.gHEX.dirty
+
+    Exceptions:
+    1: no tags. git_describe was just HEX. 0+untagged.DISTANCE.gHEX[.dirty]
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"] or pieces["dirty"]:
+            rendered += plus_or_dot(pieces)
+            rendered += f"{pieces['distance']}.g{pieces['short']}"
+            if pieces["dirty"]:
+                rendered += ".dirty"
+    else:
+        # exception #1
+        rendered = f"0+untagged.{pieces['distance']}.g{pieces['short']}"
+        if pieces["dirty"]:
+            rendered += ".dirty"
+    return rendered
+
+
+def render_pep440_branch(pieces):
+    """TAG[[.dev0]+DISTANCE.gHEX[.dirty]] .
+
+    The ".dev0" means not master branch. Note that .dev0 sorts backwards
+    (a feature branch will appear "older" than the master branch).
+
+    Exceptions:
+    1: no tags. 0[.dev0]+untagged.DISTANCE.gHEX[.dirty]
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"] or pieces["dirty"]:
+            if pieces["branch"] != "master":
+                rendered += ".dev0"
+            rendered += plus_or_dot(pieces)
+            rendered += f"{pieces['distance']}.g{pieces['short']}"
+            if pieces["dirty"]:
+                rendered += ".dirty"
+    else:
+        # exception #1
+        rendered = "0"
+        if pieces["branch"] != "master":
+            rendered += ".dev0"
+        rendered += f"+untagged.{pieces['distance']}.g{pieces['short']}"
+        if pieces["dirty"]:
+            rendered += ".dirty"
+    return rendered
+
+
+def pep440_split_post(ver):
+    """Split pep440 version string at the post-release segment.
+
+    Returns the release segments before the post-release and the
+    post-release version number (or -1 if no post-release segment is present).
+    """
+    vc = str.split(ver, ".post")
+    return vc[0], int(vc[1] or 0) if len(vc) == 2 else None
+
+
+def render_pep440_pre(pieces):
+    """TAG[.postN.devDISTANCE] -- No -dirty.
+
+    Exceptions:
+    1: no tags. 0.post0.devDISTANCE
+    """
+    if pieces["closest-tag"]:
+        if pieces["distance"]:
+            # update the post release segment
+            tag_version, post_version = pep440_split_post(pieces["closest-tag"])
+            rendered = tag_version
+            if post_version is not None:
+                rendered += f".post{post_version + 1}.dev{pieces['distance']}"
+            else:
+                rendered += f".post0.dev{pieces['distance']}"
+        else:
+            # no commits, use the tag as the version
+            rendered = pieces["closest-tag"]
+    else:
+        # exception #1
+        rendered = f"0.post0.dev{pieces['distance']}"
+    return rendered
+
+
+def render_pep440_post(pieces):
+    """TAG[.postDISTANCE[.dev0]+gHEX] .
+
+    The ".dev0" means dirty. Note that .dev0 sorts backwards
+    (a dirty tree will appear "older" than the corresponding clean one),
+    but you shouldn't be releasing software with -dirty anyways.
+
+    Exceptions:
+    1: no tags. 0.postDISTANCE[.dev0]
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"] or pieces["dirty"]:
+            rendered += f".post{pieces['distance']}"
+            if pieces["dirty"]:
+                rendered += ".dev0"
+            rendered += plus_or_dot(pieces)
+            rendered += f"g{pieces['short']}"
+    else:
+        # exception #1
+        rendered = f"0.post{pieces['distance']}"
+        if pieces["dirty"]:
+            rendered += ".dev0"
+        rendered += f"+g{pieces['short']}"
+    return rendered
+
+
+def render_pep440_post_branch(pieces):
+    """TAG[.postDISTANCE[.dev0]+gHEX[.dirty]] .
+
+    The ".dev0" means not master branch.
+
+    Exceptions:
+    1: no tags. 0.postDISTANCE[.dev0]+gHEX[.dirty]
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"] or pieces["dirty"]:
+            rendered += f".post{pieces['distance']}"
+            if pieces["branch"] != "master":
+                rendered += ".dev0"
+            rendered += plus_or_dot(pieces)
+            rendered += f"g{pieces['short']}"
+            if pieces["dirty"]:
+                rendered += ".dirty"
+    else:
+        # exception #1
+        rendered = f"0.post{pieces['distance']}"
+        if pieces["branch"] != "master":
+            rendered += ".dev0"
+        rendered += f"+g{pieces['short']}"
+        if pieces["dirty"]:
+            rendered += ".dirty"
+    return rendered
+
+
+def render_pep440_old(pieces):
+    """TAG[.postDISTANCE[.dev0]] .
+
+    The ".dev0" means dirty.
+
+    Exceptions:
+    1: no tags. 0.postDISTANCE[.dev0]
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"] or pieces["dirty"]:
+            rendered += f"0.post{pieces['distance']}"
+            if pieces["dirty"]:
+                rendered += ".dev0"
+    else:
+        # exception #1
+        rendered = f"0.post{pieces['distance']}"
+        if pieces["dirty"]:
+            rendered += ".dev0"
+    return rendered
+
+
+def render_git_describe(pieces):
+    """TAG[-DISTANCE-gHEX][-dirty].
+
+    Like 'git describe --tags --dirty --always'.
+
+    Exceptions:
+    1: no tags. HEX[-dirty]  (note: no 'g' prefix)
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        if pieces["distance"]:
+            rendered += f"-{pieces['distance']}-g{pieces['short']}"
+    else:
+        # exception #1
+        rendered = pieces["short"]
+    if pieces["dirty"]:
+        rendered += "-dirty"
+    return rendered
+
+
+def render_git_describe_long(pieces):
+    """TAG-DISTANCE-gHEX[-dirty].
+
+    Like 'git describe --tags --dirty --always -long'.
+    The distance/hash is unconditional.
+
+    Exceptions:
+    1: no tags. HEX[-dirty]  (note: no 'g' prefix)
+    """
+    if pieces["closest-tag"]:
+        rendered = pieces["closest-tag"]
+        rendered += f"-{pieces['distance']}-g{pieces['short']}"
+    else:
+        # exception #1
+        rendered = pieces["short"]
+    if pieces["dirty"]:
+        rendered += "-dirty"
+    return rendered
+
+
+def render(pieces, style):
+    """Render the given version pieces into the requested style."""
+    if pieces["error"]:
+        return {
+            "version": "unknown",
+            "full-revisionid": pieces.get("long"),
+            "dirty": None,
+            "error": pieces["error"],
+            "date": None,
+        }
+
+    if not style or style == "default":
+        style = "pep440"  # the default
+
+    if style == "pep440":
+        rendered = render_pep440(pieces)
+    elif style == "pep440-branch":
+        rendered = render_pep440_branch(pieces)
+    elif style == "pep440-pre":
+        rendered = render_pep440_pre(pieces)
+    elif style == "pep440-post":
+        rendered = render_pep440_post(pieces)
+    elif style == "pep440-post-branch":
+        rendered = render_pep440_post_branch(pieces)
+    elif style == "pep440-old":
+        rendered = render_pep440_old(pieces)
+    elif style == "git-describe":
+        rendered = render_git_describe(pieces)
+    elif style == "git-describe-long":
+        rendered = render_git_describe_long(pieces)
+    else:
+        raise ValueError(f"unknown style '{style}'")
+
+    return {
+        "version": rendered,
+        "full-revisionid": pieces["long"],
+        "dirty": pieces["dirty"],
+        "error": None,
+        "date": pieces.get("date"),
+    }
+
+
+def get_versions():
+    """Get version information or return default if unable to do so."""
+    # I am in _version.py, which lives at ROOT/VERSIONFILE_SOURCE. If we have
+    # __file__, we can work backwards from there to the root. Some
+    # py2exe/bbfreeze/non-CPython implementations don't do __file__, in which
+    # case we can only use expanded keywords.
+
+    cfg = get_config()
+    verbose = cfg.verbose
+
+    try:
+        return git_versions_from_keywords(get_keywords(), cfg.tag_prefix, verbose)
+    except NotThisMethod:
+        pass
+
+    try:
+        root = os.path.realpath(__file__)
+        # versionfile_source is the relative path from the top of the source
+        # tree (where the .git directory might live) to this file. Invert
+        # this to find the root from __file__.
+        for _ in cfg.versionfile_source.split("/"):
+            root = os.path.dirname(root)
+    except NameError:
+        return {
+            "version": "0+unknown",
+            "full-revisionid": None,
+            "dirty": None,
+            "error": "unable to find root of source tree",
+            "date": None,
+        }
+
+    try:
+        pieces = git_pieces_from_vcs(cfg.tag_prefix, root, verbose)
+        return render(pieces, cfg.style)
+    except NotThisMethod:
+        pass
+
+    try:
+        if cfg.parentdir_prefix:
+            return versions_from_parentdir(cfg.parentdir_prefix, root, verbose)
+    except NotThisMethod:
+        pass
+
+    return {
+        "version": "0+unknown",
+        "full-revisionid": None,
+        "dirty": None,
+        "error": "unable to compute version",
+        "date": None,
+    }
diff --git a/.venv/lib/python3.13/site-packages/pandas/_version_meson.py b/.venv/lib/python3.13/site-packages/pandas/_version_meson.py
new file mode 100644
index 0000000000000000000000000000000000000000..f6c87a5bfbdbaf252f1b13ec01220ac1c58d9984
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/_version_meson.py
@@ -0,0 +1,2 @@
+__version__="2.3.3"
+__git_version__="9c8bc3e55188c8aff37207a74f1dd144980b8874"
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..a0d42b6541fdf8817b996ef9804db8a87a2bcd2c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/__init__.py
@@ -0,0 +1,16 @@
+""" public toolkit API """
+from pandas.api import (
+    extensions,
+    indexers,
+    interchange,
+    types,
+    typing,
+)
+
+__all__ = [
+    "interchange",
+    "extensions",
+    "indexers",
+    "types",
+    "typing",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/extensions/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/extensions/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..ea5f1ba926899f9d11e34e70181ed77cae7ead1d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/extensions/__init__.py
@@ -0,0 +1,33 @@
+"""
+Public API for extending pandas objects.
+"""
+
+from pandas._libs.lib import no_default
+
+from pandas.core.dtypes.base import (
+    ExtensionDtype,
+    register_extension_dtype,
+)
+
+from pandas.core.accessor import (
+    register_dataframe_accessor,
+    register_index_accessor,
+    register_series_accessor,
+)
+from pandas.core.algorithms import take
+from pandas.core.arrays import (
+    ExtensionArray,
+    ExtensionScalarOpsMixin,
+)
+
+__all__ = [
+    "no_default",
+    "ExtensionDtype",
+    "register_extension_dtype",
+    "register_dataframe_accessor",
+    "register_index_accessor",
+    "register_series_accessor",
+    "take",
+    "ExtensionArray",
+    "ExtensionScalarOpsMixin",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/indexers/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/indexers/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..78357f11dc3b79f13490b91c69ef5457fbfa9768
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/indexers/__init__.py
@@ -0,0 +1,17 @@
+"""
+Public API for Rolling Window Indexers.
+"""
+
+from pandas.core.indexers import check_array_indexer
+from pandas.core.indexers.objects import (
+    BaseIndexer,
+    FixedForwardWindowIndexer,
+    VariableOffsetWindowIndexer,
+)
+
+__all__ = [
+    "check_array_indexer",
+    "BaseIndexer",
+    "FixedForwardWindowIndexer",
+    "VariableOffsetWindowIndexer",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/interchange/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/interchange/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..2f3a73bc46b3109c3c13e1a3468a69aed2ffb2e8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/interchange/__init__.py
@@ -0,0 +1,8 @@
+"""
+Public API for DataFrame interchange protocol.
+"""
+
+from pandas.core.interchange.dataframe_protocol import DataFrame
+from pandas.core.interchange.from_dataframe import from_dataframe
+
+__all__ = ["from_dataframe", "DataFrame"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/types/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/types/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..c601086bb9f86a633d6a3f2245779fea9428bf95
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/types/__init__.py
@@ -0,0 +1,23 @@
+"""
+Public toolkit API.
+"""
+
+from pandas._libs.lib import infer_dtype
+
+from pandas.core.dtypes.api import *  # noqa: F403
+from pandas.core.dtypes.concat import union_categoricals
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    IntervalDtype,
+    PeriodDtype,
+)
+
+__all__ = [
+    "infer_dtype",
+    "union_categoricals",
+    "CategoricalDtype",
+    "DatetimeTZDtype",
+    "IntervalDtype",
+    "PeriodDtype",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/api/typing/__init__.py b/.venv/lib/python3.13/site-packages/pandas/api/typing/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..9b5d2cb06b523508b15025be804a66daaaaf7a45
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/api/typing/__init__.py
@@ -0,0 +1,55 @@
+"""
+Public API classes that store intermediate results useful for type-hinting.
+"""
+
+from pandas._libs import NaTType
+from pandas._libs.missing import NAType
+
+from pandas.core.groupby import (
+    DataFrameGroupBy,
+    SeriesGroupBy,
+)
+from pandas.core.resample import (
+    DatetimeIndexResamplerGroupby,
+    PeriodIndexResamplerGroupby,
+    Resampler,
+    TimedeltaIndexResamplerGroupby,
+    TimeGrouper,
+)
+from pandas.core.window import (
+    Expanding,
+    ExpandingGroupby,
+    ExponentialMovingWindow,
+    ExponentialMovingWindowGroupby,
+    Rolling,
+    RollingGroupby,
+    Window,
+)
+
+# TODO: Can't import Styler without importing jinja2
+# from pandas.io.formats.style import Styler
+from pandas.io.json._json import JsonReader
+from pandas.io.stata import StataReader
+
+__all__ = [
+    "DataFrameGroupBy",
+    "DatetimeIndexResamplerGroupby",
+    "Expanding",
+    "ExpandingGroupby",
+    "ExponentialMovingWindow",
+    "ExponentialMovingWindowGroupby",
+    "JsonReader",
+    "NaTType",
+    "NAType",
+    "PeriodIndexResamplerGroupby",
+    "Resampler",
+    "Rolling",
+    "RollingGroupby",
+    "SeriesGroupBy",
+    "StataReader",
+    # See TODO above
+    # "Styler",
+    "TimedeltaIndexResamplerGroupby",
+    "TimeGrouper",
+    "Window",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/arrays/__init__.py b/.venv/lib/python3.13/site-packages/pandas/arrays/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..a11755275d00e070bea6ab73a881b98d0b976551
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/arrays/__init__.py
@@ -0,0 +1,53 @@
+"""
+All of pandas' ExtensionArrays.
+
+See :ref:`extending.extension-types` for more.
+"""
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    ArrowStringArray,
+    BooleanArray,
+    Categorical,
+    DatetimeArray,
+    FloatingArray,
+    IntegerArray,
+    IntervalArray,
+    NumpyExtensionArray,
+    PeriodArray,
+    SparseArray,
+    StringArray,
+    TimedeltaArray,
+)
+
+__all__ = [
+    "ArrowExtensionArray",
+    "ArrowStringArray",
+    "BooleanArray",
+    "Categorical",
+    "DatetimeArray",
+    "FloatingArray",
+    "IntegerArray",
+    "IntervalArray",
+    "NumpyExtensionArray",
+    "PeriodArray",
+    "SparseArray",
+    "StringArray",
+    "TimedeltaArray",
+]
+
+
+def __getattr__(name: str) -> type[NumpyExtensionArray]:
+    if name == "PandasArray":
+        # GH#53694
+        import warnings
+
+        from pandas.util._exceptions import find_stack_level
+
+        warnings.warn(
+            "PandasArray has been renamed NumpyExtensionArray. Use that "
+            "instead. This alias will be removed in a future version.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return NumpyExtensionArray
+    raise AttributeError(f"module 'pandas.arrays' has no attribute '{name}'")
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/__init__.py b/.venv/lib/python3.13/site-packages/pandas/compat/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..c8554be0a18b1bb6a7ad6a0b43fe5cfc29f27864
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/__init__.py
@@ -0,0 +1,213 @@
+"""
+compat
+======
+
+Cross-compatible functions for different versions of Python.
+
+Other items:
+* platform checker
+"""
+from __future__ import annotations
+
+import os
+import platform
+import sys
+from typing import TYPE_CHECKING
+
+from pandas.compat._constants import (
+    IS64,
+    ISMUSL,
+    PY310,
+    PY311,
+    PY312,
+    PY314,
+    PYPY,
+    WARNING_CHECK_DISABLED,
+)
+import pandas.compat.compressors
+from pandas.compat.numpy import is_numpy_dev
+from pandas.compat.pyarrow import (
+    HAS_PYARROW,
+    pa_version_under10p1,
+    pa_version_under11p0,
+    pa_version_under13p0,
+    pa_version_under14p0,
+    pa_version_under14p1,
+    pa_version_under16p0,
+    pa_version_under17p0,
+    pa_version_under18p0,
+    pa_version_under19p0,
+    pa_version_under20p0,
+    pa_version_under21p0,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import F
+
+
+def set_function_name(f: F, name: str, cls: type) -> F:
+    """
+    Bind the name/qualname attributes of the function.
+    """
+    f.__name__ = name
+    f.__qualname__ = f"{cls.__name__}.{name}"
+    f.__module__ = cls.__module__
+    return f
+
+
+def is_platform_little_endian() -> bool:
+    """
+    Checking if the running platform is little endian.
+
+    Returns
+    -------
+    bool
+        True if the running platform is little endian.
+    """
+    return sys.byteorder == "little"
+
+
+def is_platform_windows() -> bool:
+    """
+    Checking if the running platform is windows.
+
+    Returns
+    -------
+    bool
+        True if the running platform is windows.
+    """
+    return sys.platform in ["win32", "cygwin"]
+
+
+def is_platform_linux() -> bool:
+    """
+    Checking if the running platform is linux.
+
+    Returns
+    -------
+    bool
+        True if the running platform is linux.
+    """
+    return sys.platform == "linux"
+
+
+def is_platform_mac() -> bool:
+    """
+    Checking if the running platform is mac.
+
+    Returns
+    -------
+    bool
+        True if the running platform is mac.
+    """
+    return sys.platform == "darwin"
+
+
+def is_platform_arm() -> bool:
+    """
+    Checking if the running platform use ARM architecture.
+
+    Returns
+    -------
+    bool
+        True if the running platform uses ARM architecture.
+    """
+    return platform.machine() in ("arm64", "aarch64") or platform.machine().startswith(
+        "armv"
+    )
+
+
+def is_platform_power() -> bool:
+    """
+    Checking if the running platform use Power architecture.
+
+    Returns
+    -------
+    bool
+        True if the running platform uses ARM architecture.
+    """
+    return platform.machine() in ("ppc64", "ppc64le")
+
+
+def is_ci_environment() -> bool:
+    """
+    Checking if running in a continuous integration environment by checking
+    the PANDAS_CI environment variable.
+
+    Returns
+    -------
+    bool
+        True if the running in a continuous integration environment.
+    """
+    return os.environ.get("PANDAS_CI", "0") == "1"
+
+
+def get_lzma_file() -> type[pandas.compat.compressors.LZMAFile]:
+    """
+    Importing the `LZMAFile` class from the `lzma` module.
+
+    Returns
+    -------
+    class
+        The `LZMAFile` class from the `lzma` module.
+
+    Raises
+    ------
+    RuntimeError
+        If the `lzma` module was not imported correctly, or didn't exist.
+    """
+    if not pandas.compat.compressors.has_lzma:
+        raise RuntimeError(
+            "lzma module not available. "
+            "A Python re-install with the proper dependencies, "
+            "might be required to solve this issue."
+        )
+    return pandas.compat.compressors.LZMAFile
+
+
+def get_bz2_file() -> type[pandas.compat.compressors.BZ2File]:
+    """
+    Importing the `BZ2File` class from the `bz2` module.
+
+    Returns
+    -------
+    class
+        The `BZ2File` class from the `bz2` module.
+
+    Raises
+    ------
+    RuntimeError
+        If the `bz2` module was not imported correctly, or didn't exist.
+    """
+    if not pandas.compat.compressors.has_bz2:
+        raise RuntimeError(
+            "bz2 module not available. "
+            "A Python re-install with the proper dependencies, "
+            "might be required to solve this issue."
+        )
+    return pandas.compat.compressors.BZ2File
+
+
+__all__ = [
+    "is_numpy_dev",
+    "pa_version_under10p1",
+    "pa_version_under11p0",
+    "pa_version_under13p0",
+    "pa_version_under14p0",
+    "pa_version_under14p1",
+    "pa_version_under16p0",
+    "pa_version_under17p0",
+    "pa_version_under18p0",
+    "pa_version_under19p0",
+    "pa_version_under20p0",
+    "pa_version_under21p0",
+    "HAS_PYARROW",
+    "IS64",
+    "ISMUSL",
+    "PY310",
+    "PY311",
+    "PY312",
+    "PY314",
+    "PYPY",
+    "WARNING_CHECK_DISABLED",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/_constants.py b/.venv/lib/python3.13/site-packages/pandas/compat/_constants.py
new file mode 100644
index 0000000000000000000000000000000000000000..fb011603712c61ae1dcc745148a6dfb2c05b803f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/_constants.py
@@ -0,0 +1,34 @@
+"""
+_constants
+======
+
+Constants relevant for the Python implementation.
+"""
+
+from __future__ import annotations
+
+import platform
+import sys
+import sysconfig
+
+IS64 = sys.maxsize > 2**32
+
+PY310 = sys.version_info >= (3, 10)
+PY311 = sys.version_info >= (3, 11)
+PY312 = sys.version_info >= (3, 12)
+PY314 = sys.version_info >= (3, 14)
+PYPY = platform.python_implementation() == "PyPy"
+ISMUSL = "musl" in (sysconfig.get_config_var("HOST_GNU_TYPE") or "")
+REF_COUNT = 2 if PY311 else 3
+WARNING_CHECK_DISABLED = PY314
+
+
+__all__ = [
+    "IS64",
+    "ISMUSL",
+    "PY310",
+    "PY311",
+    "PY312",
+    "PY314",
+    "PYPY",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/_optional.py b/.venv/lib/python3.13/site-packages/pandas/compat/_optional.py
new file mode 100644
index 0000000000000000000000000000000000000000..2bc6cd46f09a7e4b103658f9c2ec9a69d93d00b9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/_optional.py
@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+import importlib
+import sys
+from typing import TYPE_CHECKING
+import warnings
+
+from pandas.util._exceptions import find_stack_level
+
+from pandas.util.version import Version
+
+if TYPE_CHECKING:
+    import types
+
+# Update install.rst & setup.cfg when updating versions!
+
+VERSIONS = {
+    "adbc-driver-postgresql": "0.8.0",
+    "adbc-driver-sqlite": "0.8.0",
+    "bs4": "4.11.2",
+    "blosc": "1.21.3",
+    "bottleneck": "1.3.6",
+    "dataframe-api-compat": "0.1.7",
+    "fastparquet": "2022.12.0",
+    "fsspec": "2022.11.0",
+    "html5lib": "1.1",
+    "hypothesis": "6.46.1",
+    "gcsfs": "2022.11.0",
+    "jinja2": "3.1.2",
+    "lxml.etree": "4.9.2",
+    "matplotlib": "3.6.3",
+    "numba": "0.56.4",
+    "numexpr": "2.8.4",
+    "odfpy": "1.4.1",
+    "openpyxl": "3.1.0",
+    "pandas_gbq": "0.19.0",
+    "psycopg2": "2.9.6",  # (dt dec pq3 ext lo64)
+    "pymysql": "1.0.2",
+    "pyarrow": "10.0.1",
+    "pyreadstat": "1.2.0",
+    "pytest": "7.3.2",
+    "python-calamine": "0.1.7",
+    "pyxlsb": "1.0.10",
+    "s3fs": "2022.11.0",
+    "scipy": "1.10.0",
+    "sqlalchemy": "2.0.0",
+    "tables": "3.8.0",
+    "tabulate": "0.9.0",
+    "xarray": "2022.12.0",
+    "xlrd": "2.0.1",
+    "xlsxwriter": "3.0.5",
+    "zstandard": "0.19.0",
+    "tzdata": "2022.7",
+    "qtpy": "2.3.0",
+    "pyqt5": "5.15.9",
+}
+
+# A mapping from import name to package name (on PyPI) for packages where
+# these two names are different.
+
+INSTALL_MAPPING = {
+    "bs4": "beautifulsoup4",
+    "bottleneck": "Bottleneck",
+    "jinja2": "Jinja2",
+    "lxml.etree": "lxml",
+    "odf": "odfpy",
+    "pandas_gbq": "pandas-gbq",
+    "python_calamine": "python-calamine",
+    "sqlalchemy": "SQLAlchemy",
+    "tables": "pytables",
+}
+
+
+def get_version(module: types.ModuleType) -> str:
+    version = getattr(module, "__version__", None)
+
+    if version is None:
+        raise ImportError(f"Can't determine version for {module.__name__}")
+    if module.__name__ == "psycopg2":
+        # psycopg2 appends " (dt dec pq3 ext lo64)" to it's version
+        version = version.split()[0]
+    return version
+
+
+def import_optional_dependency(
+    name: str,
+    extra: str = "",
+    errors: str = "raise",
+    min_version: str | None = None,
+):
+    """
+    Import an optional dependency.
+
+    By default, if a dependency is missing an ImportError with a nice
+    message will be raised. If a dependency is present, but too old,
+    we raise.
+
+    Parameters
+    ----------
+    name : str
+        The module name.
+    extra : str
+        Additional text to include in the ImportError message.
+    errors : str {'raise', 'warn', 'ignore'}
+        What to do when a dependency is not found or its version is too old.
+
+        * raise : Raise an ImportError
+        * warn : Only applicable when a module's version is to old.
+          Warns that the version is too old and returns None
+        * ignore: If the module is not installed, return None, otherwise,
+          return the module, even if the version is too old.
+          It's expected that users validate the version locally when
+          using ``errors="ignore"`` (see. ``io/html.py``)
+    min_version : str, default None
+        Specify a minimum version that is different from the global pandas
+        minimum version required.
+    Returns
+    -------
+    maybe_module : Optional[ModuleType]
+        The imported module, when found and the version is correct.
+        None is returned when the package is not found and `errors`
+        is False, or when the package's version is too old and `errors`
+        is ``'warn'`` or ``'ignore'``.
+    """
+    assert errors in {"warn", "raise", "ignore"}
+
+    package_name = INSTALL_MAPPING.get(name)
+    install_name = package_name if package_name is not None else name
+
+    msg = (
+        f"Missing optional dependency '{install_name}'. {extra} "
+        f"Use pip or conda to install {install_name}."
+    )
+    try:
+        module = importlib.import_module(name)
+    except ImportError:
+        if errors == "raise":
+            raise ImportError(msg)
+        return None
+
+    # Handle submodules: if we have submodule, grab parent module from sys.modules
+    parent = name.split(".")[0]
+    if parent != name:
+        install_name = parent
+        module_to_get = sys.modules[install_name]
+    else:
+        module_to_get = module
+    minimum_version = min_version if min_version is not None else VERSIONS.get(parent)
+    if minimum_version:
+        version = get_version(module_to_get)
+        if version and Version(version) < Version(minimum_version):
+            msg = (
+                f"Pandas requires version '{minimum_version}' or newer of '{parent}' "
+                f"(version '{version}' currently installed)."
+            )
+            if errors == "warn":
+                warnings.warn(
+                    msg,
+                    UserWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return None
+            elif errors == "raise":
+                raise ImportError(msg)
+            else:
+                return None
+
+    return module
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/compressors.py b/.venv/lib/python3.13/site-packages/pandas/compat/compressors.py
new file mode 100644
index 0000000000000000000000000000000000000000..1f31e34c092c9672559ca2f5194cb1da7083d03b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/compressors.py
@@ -0,0 +1,77 @@
+"""
+Patched ``BZ2File`` and ``LZMAFile`` to handle pickle protocol 5.
+"""
+
+from __future__ import annotations
+
+from pickle import PickleBuffer
+
+from pandas.compat._constants import PY310
+
+try:
+    import bz2
+
+    has_bz2 = True
+except ImportError:
+    has_bz2 = False
+
+try:
+    import lzma
+
+    has_lzma = True
+except ImportError:
+    has_lzma = False
+
+
+def flatten_buffer(
+    b: bytes | bytearray | memoryview | PickleBuffer,
+) -> bytes | bytearray | memoryview:
+    """
+    Return some 1-D `uint8` typed buffer.
+
+    Coerces anything that does not match that description to one that does
+    without copying if possible (otherwise will copy).
+    """
+
+    if isinstance(b, (bytes, bytearray)):
+        return b
+
+    if not isinstance(b, PickleBuffer):
+        b = PickleBuffer(b)
+
+    try:
+        # coerce to 1-D `uint8` C-contiguous `memoryview` zero-copy
+        return b.raw()
+    except BufferError:
+        # perform in-memory copy if buffer is not contiguous
+        return memoryview(b).tobytes("A")
+
+
+if has_bz2:
+
+    class BZ2File(bz2.BZ2File):
+        if not PY310:
+
+            def write(self, b) -> int:
+                # Workaround issue where `bz2.BZ2File` expects `len`
+                # to return the number of bytes in `b` by converting
+                # `b` into something that meets that constraint with
+                # minimal copying.
+                #
+                # Note: This is fixed in Python 3.10.
+                return super().write(flatten_buffer(b))
+
+
+if has_lzma:
+
+    class LZMAFile(lzma.LZMAFile):
+        if not PY310:
+
+            def write(self, b) -> int:
+                # Workaround issue where `lzma.LZMAFile` expects `len`
+                # to return the number of bytes in `b` by converting
+                # `b` into something that meets that constraint with
+                # minimal copying.
+                #
+                # Note: This is fixed in Python 3.10.
+                return super().write(flatten_buffer(b))
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/numpy/__init__.py b/.venv/lib/python3.13/site-packages/pandas/compat/numpy/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..a06761d03887bc2a2dd186fe2d3ac781f7222aeb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/numpy/__init__.py
@@ -0,0 +1,53 @@
+""" support numpy compatibility across versions """
+import warnings
+
+import numpy as np
+
+from pandas.util.version import Version
+
+# numpy versioning
+_np_version = np.__version__
+_nlv = Version(_np_version)
+np_version_lt1p23 = _nlv < Version("1.23")
+np_version_gte1p24 = _nlv >= Version("1.24")
+np_version_gte1p24p3 = _nlv >= Version("1.24.3")
+np_version_gte1p25 = _nlv >= Version("1.25")
+np_version_gt2 = _nlv >= Version("2.0.0")
+is_numpy_dev = _nlv.dev is not None
+_min_numpy_ver = "1.22.4"
+
+
+if _nlv < Version(_min_numpy_ver):
+    raise ImportError(
+        f"this version of pandas is incompatible with numpy < {_min_numpy_ver}\n"
+        f"your numpy version is {_np_version}.\n"
+        f"Please upgrade numpy to >= {_min_numpy_ver} to use this pandas version"
+    )
+
+
+np_long: type
+np_ulong: type
+
+if np_version_gt2:
+    try:
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                r".*In the future `np\.long` will be defined as.*",
+                FutureWarning,
+            )
+            np_long = np.long  # type: ignore[attr-defined]
+            np_ulong = np.ulong  # type: ignore[attr-defined]
+    except AttributeError:
+        np_long = np.int_
+        np_ulong = np.uint
+else:
+    np_long = np.int_
+    np_ulong = np.uint
+
+
+__all__ = [
+    "np",
+    "_np_version",
+    "is_numpy_dev",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/numpy/function.py b/.venv/lib/python3.13/site-packages/pandas/compat/numpy/function.py
new file mode 100644
index 0000000000000000000000000000000000000000..4df30f7f4a8a79984ca6de521ac058bd30fd8faf
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/numpy/function.py
@@ -0,0 +1,418 @@
+"""
+For compatibility with numpy libraries, pandas functions or methods have to
+accept '*args' and '**kwargs' parameters to accommodate numpy arguments that
+are not actually used or respected in the pandas implementation.
+
+To ensure that users do not abuse these parameters, validation is performed in
+'validators.py' to make sure that any extra parameters passed correspond ONLY
+to those in the numpy signature. Part of that validation includes whether or
+not the user attempted to pass in non-default values for these extraneous
+parameters. As we want to discourage users from relying on these parameters
+when calling the pandas implementation, we want them only to pass in the
+default values for these parameters.
+
+This module provides a set of commonly used default arguments for functions and
+methods that are spread throughout the codebase. This module will make it
+easier to adjust to future upstream changes in the analogous numpy signatures.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+    cast,
+    overload,
+)
+
+import numpy as np
+from numpy import ndarray
+
+from pandas._libs.lib import (
+    is_bool,
+    is_integer,
+)
+from pandas.errors import UnsupportedFunctionCall
+from pandas.util._validators import (
+    validate_args,
+    validate_args_and_kwargs,
+    validate_kwargs,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Axis,
+        AxisInt,
+    )
+
+    AxisNoneT = TypeVar("AxisNoneT", Axis, None)
+
+
+class CompatValidator:
+    def __init__(
+        self,
+        defaults,
+        fname=None,
+        method: str | None = None,
+        max_fname_arg_count=None,
+    ) -> None:
+        self.fname = fname
+        self.method = method
+        self.defaults = defaults
+        self.max_fname_arg_count = max_fname_arg_count
+
+    def __call__(
+        self,
+        args,
+        kwargs,
+        fname=None,
+        max_fname_arg_count=None,
+        method: str | None = None,
+    ) -> None:
+        if not args and not kwargs:
+            return None
+
+        fname = self.fname if fname is None else fname
+        max_fname_arg_count = (
+            self.max_fname_arg_count
+            if max_fname_arg_count is None
+            else max_fname_arg_count
+        )
+        method = self.method if method is None else method
+
+        if method == "args":
+            validate_args(fname, args, max_fname_arg_count, self.defaults)
+        elif method == "kwargs":
+            validate_kwargs(fname, kwargs, self.defaults)
+        elif method == "both":
+            validate_args_and_kwargs(
+                fname, args, kwargs, max_fname_arg_count, self.defaults
+            )
+        else:
+            raise ValueError(f"invalid validation method '{method}'")
+
+
+ARGMINMAX_DEFAULTS = {"out": None}
+validate_argmin = CompatValidator(
+    ARGMINMAX_DEFAULTS, fname="argmin", method="both", max_fname_arg_count=1
+)
+validate_argmax = CompatValidator(
+    ARGMINMAX_DEFAULTS, fname="argmax", method="both", max_fname_arg_count=1
+)
+
+
+def process_skipna(skipna: bool | ndarray | None, args) -> tuple[bool, Any]:
+    if isinstance(skipna, ndarray) or skipna is None:
+        args = (skipna,) + args
+        skipna = True
+
+    return skipna, args
+
+
+def validate_argmin_with_skipna(skipna: bool | ndarray | None, args, kwargs) -> bool:
+    """
+    If 'Series.argmin' is called via the 'numpy' library, the third parameter
+    in its signature is 'out', which takes either an ndarray or 'None', so
+    check if the 'skipna' parameter is either an instance of ndarray or is
+    None, since 'skipna' itself should be a boolean
+    """
+    skipna, args = process_skipna(skipna, args)
+    validate_argmin(args, kwargs)
+    return skipna
+
+
+def validate_argmax_with_skipna(skipna: bool | ndarray | None, args, kwargs) -> bool:
+    """
+    If 'Series.argmax' is called via the 'numpy' library, the third parameter
+    in its signature is 'out', which takes either an ndarray or 'None', so
+    check if the 'skipna' parameter is either an instance of ndarray or is
+    None, since 'skipna' itself should be a boolean
+    """
+    skipna, args = process_skipna(skipna, args)
+    validate_argmax(args, kwargs)
+    return skipna
+
+
+ARGSORT_DEFAULTS: dict[str, int | str | None] = {}
+ARGSORT_DEFAULTS["axis"] = -1
+ARGSORT_DEFAULTS["kind"] = "quicksort"
+ARGSORT_DEFAULTS["order"] = None
+ARGSORT_DEFAULTS["kind"] = None
+ARGSORT_DEFAULTS["stable"] = None
+
+
+validate_argsort = CompatValidator(
+    ARGSORT_DEFAULTS, fname="argsort", max_fname_arg_count=0, method="both"
+)
+
+# two different signatures of argsort, this second validation for when the
+# `kind` param is supported
+ARGSORT_DEFAULTS_KIND: dict[str, int | None] = {}
+ARGSORT_DEFAULTS_KIND["axis"] = -1
+ARGSORT_DEFAULTS_KIND["order"] = None
+ARGSORT_DEFAULTS_KIND["stable"] = None
+validate_argsort_kind = CompatValidator(
+    ARGSORT_DEFAULTS_KIND, fname="argsort", max_fname_arg_count=0, method="both"
+)
+
+
+def validate_argsort_with_ascending(ascending: bool | int | None, args, kwargs) -> bool:
+    """
+    If 'Categorical.argsort' is called via the 'numpy' library, the first
+    parameter in its signature is 'axis', which takes either an integer or
+    'None', so check if the 'ascending' parameter has either integer type or is
+    None, since 'ascending' itself should be a boolean
+    """
+    if is_integer(ascending) or ascending is None:
+        args = (ascending,) + args
+        ascending = True
+
+    validate_argsort_kind(args, kwargs, max_fname_arg_count=3)
+    ascending = cast(bool, ascending)
+    return ascending
+
+
+CLIP_DEFAULTS: dict[str, Any] = {"out": None}
+validate_clip = CompatValidator(
+    CLIP_DEFAULTS, fname="clip", method="both", max_fname_arg_count=3
+)
+
+
+@overload
+def validate_clip_with_axis(axis: ndarray, args, kwargs) -> None:
+    ...
+
+
+@overload
+def validate_clip_with_axis(axis: AxisNoneT, args, kwargs) -> AxisNoneT:
+    ...
+
+
+def validate_clip_with_axis(
+    axis: ndarray | AxisNoneT, args, kwargs
+) -> AxisNoneT | None:
+    """
+    If 'NDFrame.clip' is called via the numpy library, the third parameter in
+    its signature is 'out', which can takes an ndarray, so check if the 'axis'
+    parameter is an instance of ndarray, since 'axis' itself should either be
+    an integer or None
+    """
+    if isinstance(axis, ndarray):
+        args = (axis,) + args
+        # error: Incompatible types in assignment (expression has type "None",
+        # variable has type "Union[ndarray[Any, Any], str, int]")
+        axis = None  # type: ignore[assignment]
+
+    validate_clip(args, kwargs)
+    # error: Incompatible return value type (got "Union[ndarray[Any, Any],
+    # str, int]", expected "Union[str, int, None]")
+    return axis  # type: ignore[return-value]
+
+
+CUM_FUNC_DEFAULTS: dict[str, Any] = {}
+CUM_FUNC_DEFAULTS["dtype"] = None
+CUM_FUNC_DEFAULTS["out"] = None
+validate_cum_func = CompatValidator(
+    CUM_FUNC_DEFAULTS, method="both", max_fname_arg_count=1
+)
+validate_cumsum = CompatValidator(
+    CUM_FUNC_DEFAULTS, fname="cumsum", method="both", max_fname_arg_count=1
+)
+
+
+def validate_cum_func_with_skipna(skipna: bool, args, kwargs, name) -> bool:
+    """
+    If this function is called via the 'numpy' library, the third parameter in
+    its signature is 'dtype', which takes either a 'numpy' dtype or 'None', so
+    check if the 'skipna' parameter is a boolean or not
+    """
+    if not is_bool(skipna):
+        args = (skipna,) + args
+        skipna = True
+    elif isinstance(skipna, np.bool_):
+        skipna = bool(skipna)
+
+    validate_cum_func(args, kwargs, fname=name)
+    return skipna
+
+
+ALLANY_DEFAULTS: dict[str, bool | None] = {}
+ALLANY_DEFAULTS["dtype"] = None
+ALLANY_DEFAULTS["out"] = None
+ALLANY_DEFAULTS["keepdims"] = False
+ALLANY_DEFAULTS["axis"] = None
+validate_all = CompatValidator(
+    ALLANY_DEFAULTS, fname="all", method="both", max_fname_arg_count=1
+)
+validate_any = CompatValidator(
+    ALLANY_DEFAULTS, fname="any", method="both", max_fname_arg_count=1
+)
+
+LOGICAL_FUNC_DEFAULTS = {"out": None, "keepdims": False}
+validate_logical_func = CompatValidator(LOGICAL_FUNC_DEFAULTS, method="kwargs")
+
+MINMAX_DEFAULTS = {"axis": None, "dtype": None, "out": None, "keepdims": False}
+validate_min = CompatValidator(
+    MINMAX_DEFAULTS, fname="min", method="both", max_fname_arg_count=1
+)
+validate_max = CompatValidator(
+    MINMAX_DEFAULTS, fname="max", method="both", max_fname_arg_count=1
+)
+
+RESHAPE_DEFAULTS: dict[str, str] = {"order": "C"}
+validate_reshape = CompatValidator(
+    RESHAPE_DEFAULTS, fname="reshape", method="both", max_fname_arg_count=1
+)
+
+REPEAT_DEFAULTS: dict[str, Any] = {"axis": None}
+validate_repeat = CompatValidator(
+    REPEAT_DEFAULTS, fname="repeat", method="both", max_fname_arg_count=1
+)
+
+ROUND_DEFAULTS: dict[str, Any] = {"out": None}
+validate_round = CompatValidator(
+    ROUND_DEFAULTS, fname="round", method="both", max_fname_arg_count=1
+)
+
+SORT_DEFAULTS: dict[str, int | str | None] = {}
+SORT_DEFAULTS["axis"] = -1
+SORT_DEFAULTS["kind"] = "quicksort"
+SORT_DEFAULTS["order"] = None
+validate_sort = CompatValidator(SORT_DEFAULTS, fname="sort", method="kwargs")
+
+STAT_FUNC_DEFAULTS: dict[str, Any | None] = {}
+STAT_FUNC_DEFAULTS["dtype"] = None
+STAT_FUNC_DEFAULTS["out"] = None
+
+SUM_DEFAULTS = STAT_FUNC_DEFAULTS.copy()
+SUM_DEFAULTS["axis"] = None
+SUM_DEFAULTS["keepdims"] = False
+SUM_DEFAULTS["initial"] = None
+
+PROD_DEFAULTS = SUM_DEFAULTS.copy()
+
+MEAN_DEFAULTS = SUM_DEFAULTS.copy()
+
+MEDIAN_DEFAULTS = STAT_FUNC_DEFAULTS.copy()
+MEDIAN_DEFAULTS["overwrite_input"] = False
+MEDIAN_DEFAULTS["keepdims"] = False
+
+STAT_FUNC_DEFAULTS["keepdims"] = False
+
+validate_stat_func = CompatValidator(STAT_FUNC_DEFAULTS, method="kwargs")
+validate_sum = CompatValidator(
+    SUM_DEFAULTS, fname="sum", method="both", max_fname_arg_count=1
+)
+validate_prod = CompatValidator(
+    PROD_DEFAULTS, fname="prod", method="both", max_fname_arg_count=1
+)
+validate_mean = CompatValidator(
+    MEAN_DEFAULTS, fname="mean", method="both", max_fname_arg_count=1
+)
+validate_median = CompatValidator(
+    MEDIAN_DEFAULTS, fname="median", method="both", max_fname_arg_count=1
+)
+
+STAT_DDOF_FUNC_DEFAULTS: dict[str, bool | None] = {}
+STAT_DDOF_FUNC_DEFAULTS["dtype"] = None
+STAT_DDOF_FUNC_DEFAULTS["out"] = None
+STAT_DDOF_FUNC_DEFAULTS["keepdims"] = False
+validate_stat_ddof_func = CompatValidator(STAT_DDOF_FUNC_DEFAULTS, method="kwargs")
+
+TAKE_DEFAULTS: dict[str, str | None] = {}
+TAKE_DEFAULTS["out"] = None
+TAKE_DEFAULTS["mode"] = "raise"
+validate_take = CompatValidator(TAKE_DEFAULTS, fname="take", method="kwargs")
+
+
+def validate_take_with_convert(convert: ndarray | bool | None, args, kwargs) -> bool:
+    """
+    If this function is called via the 'numpy' library, the third parameter in
+    its signature is 'axis', which takes either an ndarray or 'None', so check
+    if the 'convert' parameter is either an instance of ndarray or is None
+    """
+    if isinstance(convert, ndarray) or convert is None:
+        args = (convert,) + args
+        convert = True
+
+    validate_take(args, kwargs, max_fname_arg_count=3, method="both")
+    return convert
+
+
+TRANSPOSE_DEFAULTS = {"axes": None}
+validate_transpose = CompatValidator(
+    TRANSPOSE_DEFAULTS, fname="transpose", method="both", max_fname_arg_count=0
+)
+
+
+def validate_groupby_func(name: str, args, kwargs, allowed=None) -> None:
+    """
+    'args' and 'kwargs' should be empty, except for allowed kwargs because all
+    of their necessary parameters are explicitly listed in the function
+    signature
+    """
+    if allowed is None:
+        allowed = []
+
+    kwargs = set(kwargs) - set(allowed)
+
+    if len(args) + len(kwargs) > 0:
+        raise UnsupportedFunctionCall(
+            "numpy operations are not valid with groupby. "
+            f"Use .groupby(...).{name}() instead"
+        )
+
+
+RESAMPLER_NUMPY_OPS = ("min", "max", "sum", "prod", "mean", "std", "var")
+
+
+def validate_resampler_func(method: str, args, kwargs) -> None:
+    """
+    'args' and 'kwargs' should be empty because all of their necessary
+    parameters are explicitly listed in the function signature
+    """
+    if len(args) + len(kwargs) > 0:
+        if method in RESAMPLER_NUMPY_OPS:
+            raise UnsupportedFunctionCall(
+                "numpy operations are not valid with resample. "
+                f"Use .resample(...).{method}() instead"
+            )
+        raise TypeError("too many arguments passed in")
+
+
+def validate_minmax_axis(axis: AxisInt | None, ndim: int = 1) -> None:
+    """
+    Ensure that the axis argument passed to min, max, argmin, or argmax is zero
+    or None, as otherwise it will be incorrectly ignored.
+
+    Parameters
+    ----------
+    axis : int or None
+    ndim : int, default 1
+
+    Raises
+    ------
+    ValueError
+    """
+    if axis is None:
+        return
+    if axis >= ndim or (axis < 0 and ndim + axis < 0):
+        raise ValueError(f"`axis` must be fewer than the number of dimensions ({ndim})")
+
+
+_validation_funcs = {
+    "median": validate_median,
+    "mean": validate_mean,
+    "min": validate_min,
+    "max": validate_max,
+    "sum": validate_sum,
+    "prod": validate_prod,
+}
+
+
+def validate_func(fname, args, kwargs) -> None:
+    if fname not in _validation_funcs:
+        return validate_stat_func(args, kwargs, fname=fname)
+
+    validation_func = _validation_funcs[fname]
+    return validation_func(args, kwargs)
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/pickle_compat.py b/.venv/lib/python3.13/site-packages/pandas/compat/pickle_compat.py
new file mode 100644
index 0000000000000000000000000000000000000000..cd98087c06c18634304c29d88837017a6952a4fc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/pickle_compat.py
@@ -0,0 +1,262 @@
+"""
+Support pre-0.12 series pickle compatibility.
+"""
+from __future__ import annotations
+
+import contextlib
+import copy
+import io
+import pickle as pkl
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs.arrays import NDArrayBacked
+from pandas._libs.tslibs import BaseOffset
+
+from pandas import Index
+from pandas.core.arrays import (
+    DatetimeArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.internals import BlockManager
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+
+def load_reduce(self) -> None:
+    stack = self.stack
+    args = stack.pop()
+    func = stack[-1]
+
+    try:
+        stack[-1] = func(*args)
+        return
+    except TypeError as err:
+        # If we have a deprecated function,
+        # try to replace and try again.
+
+        msg = "_reconstruct: First argument must be a sub-type of ndarray"
+
+        if msg in str(err):
+            try:
+                cls = args[0]
+                stack[-1] = object.__new__(cls)
+                return
+            except TypeError:
+                pass
+        elif args and isinstance(args[0], type) and issubclass(args[0], BaseOffset):
+            # TypeError: object.__new__(Day) is not safe, use Day.__new__()
+            cls = args[0]
+            stack[-1] = cls.__new__(*args)
+            return
+        elif args and issubclass(args[0], PeriodArray):
+            cls = args[0]
+            stack[-1] = NDArrayBacked.__new__(*args)
+            return
+
+        raise
+
+
+# If classes are moved, provide compat here.
+_class_locations_map = {
+    ("pandas.core.sparse.array", "SparseArray"): ("pandas.core.arrays", "SparseArray"),
+    # 15477
+    ("pandas.core.base", "FrozenNDArray"): ("numpy", "ndarray"),
+    # Re-routing unpickle block logic to go through _unpickle_block instead
+    # for pandas <= 1.3.5
+    ("pandas.core.internals.blocks", "new_block"): (
+        "pandas._libs.internals",
+        "_unpickle_block",
+    ),
+    ("pandas.core.indexes.frozen", "FrozenNDArray"): ("numpy", "ndarray"),
+    ("pandas.core.base", "FrozenList"): ("pandas.core.indexes.frozen", "FrozenList"),
+    # 10890
+    ("pandas.core.series", "TimeSeries"): ("pandas.core.series", "Series"),
+    ("pandas.sparse.series", "SparseTimeSeries"): (
+        "pandas.core.sparse.series",
+        "SparseSeries",
+    ),
+    # 12588, extensions moving
+    ("pandas._sparse", "BlockIndex"): ("pandas._libs.sparse", "BlockIndex"),
+    ("pandas.tslib", "Timestamp"): ("pandas._libs.tslib", "Timestamp"),
+    # 18543 moving period
+    ("pandas._period", "Period"): ("pandas._libs.tslibs.period", "Period"),
+    ("pandas._libs.period", "Period"): ("pandas._libs.tslibs.period", "Period"),
+    # 18014 moved __nat_unpickle from _libs.tslib-->_libs.tslibs.nattype
+    ("pandas.tslib", "__nat_unpickle"): (
+        "pandas._libs.tslibs.nattype",
+        "__nat_unpickle",
+    ),
+    ("pandas._libs.tslib", "__nat_unpickle"): (
+        "pandas._libs.tslibs.nattype",
+        "__nat_unpickle",
+    ),
+    # 15998 top-level dirs moving
+    ("pandas.sparse.array", "SparseArray"): (
+        "pandas.core.arrays.sparse",
+        "SparseArray",
+    ),
+    ("pandas.indexes.base", "_new_Index"): ("pandas.core.indexes.base", "_new_Index"),
+    ("pandas.indexes.base", "Index"): ("pandas.core.indexes.base", "Index"),
+    ("pandas.indexes.numeric", "Int64Index"): (
+        "pandas.core.indexes.base",
+        "Index",  # updated in 50775
+    ),
+    ("pandas.indexes.range", "RangeIndex"): ("pandas.core.indexes.range", "RangeIndex"),
+    ("pandas.indexes.multi", "MultiIndex"): ("pandas.core.indexes.multi", "MultiIndex"),
+    ("pandas.tseries.index", "_new_DatetimeIndex"): (
+        "pandas.core.indexes.datetimes",
+        "_new_DatetimeIndex",
+    ),
+    ("pandas.tseries.index", "DatetimeIndex"): (
+        "pandas.core.indexes.datetimes",
+        "DatetimeIndex",
+    ),
+    ("pandas.tseries.period", "PeriodIndex"): (
+        "pandas.core.indexes.period",
+        "PeriodIndex",
+    ),
+    # 19269, arrays moving
+    ("pandas.core.categorical", "Categorical"): ("pandas.core.arrays", "Categorical"),
+    # 19939, add timedeltaindex, float64index compat from 15998 move
+    ("pandas.tseries.tdi", "TimedeltaIndex"): (
+        "pandas.core.indexes.timedeltas",
+        "TimedeltaIndex",
+    ),
+    ("pandas.indexes.numeric", "Float64Index"): (
+        "pandas.core.indexes.base",
+        "Index",  # updated in 50775
+    ),
+    # 50775, remove Int64Index, UInt64Index & Float64Index from codabase
+    ("pandas.core.indexes.numeric", "Int64Index"): (
+        "pandas.core.indexes.base",
+        "Index",
+    ),
+    ("pandas.core.indexes.numeric", "UInt64Index"): (
+        "pandas.core.indexes.base",
+        "Index",
+    ),
+    ("pandas.core.indexes.numeric", "Float64Index"): (
+        "pandas.core.indexes.base",
+        "Index",
+    ),
+    ("pandas.core.arrays.sparse.dtype", "SparseDtype"): (
+        "pandas.core.dtypes.dtypes",
+        "SparseDtype",
+    ),
+}
+
+
+# our Unpickler sub-class to override methods and some dispatcher
+# functions for compat and uses a non-public class of the pickle module.
+
+
+class Unpickler(pkl._Unpickler):
+    def find_class(self, module, name):
+        # override superclass
+        key = (module, name)
+        module, name = _class_locations_map.get(key, key)
+        return super().find_class(module, name)
+
+
+Unpickler.dispatch = copy.copy(Unpickler.dispatch)
+Unpickler.dispatch[pkl.REDUCE[0]] = load_reduce
+
+
+def load_newobj(self) -> None:
+    args = self.stack.pop()
+    cls = self.stack[-1]
+
+    # compat
+    if issubclass(cls, Index):
+        obj = object.__new__(cls)
+    elif issubclass(cls, DatetimeArray) and not args:
+        arr = np.array([], dtype="M8[ns]")
+        obj = cls.__new__(cls, arr, arr.dtype)
+    elif issubclass(cls, TimedeltaArray) and not args:
+        arr = np.array([], dtype="m8[ns]")
+        obj = cls.__new__(cls, arr, arr.dtype)
+    elif cls is BlockManager and not args:
+        obj = cls.__new__(cls, (), [], False)
+    else:
+        obj = cls.__new__(cls, *args)
+
+    self.stack[-1] = obj
+
+
+Unpickler.dispatch[pkl.NEWOBJ[0]] = load_newobj
+
+
+def load_newobj_ex(self) -> None:
+    kwargs = self.stack.pop()
+    args = self.stack.pop()
+    cls = self.stack.pop()
+
+    # compat
+    if issubclass(cls, Index):
+        obj = object.__new__(cls)
+    else:
+        obj = cls.__new__(cls, *args, **kwargs)
+    self.append(obj)
+
+
+try:
+    Unpickler.dispatch[pkl.NEWOBJ_EX[0]] = load_newobj_ex
+except (AttributeError, KeyError):
+    pass
+
+
+def load(fh, encoding: str | None = None, is_verbose: bool = False):
+    """
+    Load a pickle, with a provided encoding,
+
+    Parameters
+    ----------
+    fh : a filelike object
+    encoding : an optional encoding
+    is_verbose : show exception output
+    """
+    try:
+        fh.seek(0)
+        if encoding is not None:
+            up = Unpickler(fh, encoding=encoding)
+        else:
+            up = Unpickler(fh)
+        # "Unpickler" has no attribute "is_verbose"  [attr-defined]
+        up.is_verbose = is_verbose  # type: ignore[attr-defined]
+
+        return up.load()
+    except (ValueError, TypeError):
+        raise
+
+
+def loads(
+    bytes_object: bytes,
+    *,
+    fix_imports: bool = True,
+    encoding: str = "ASCII",
+    errors: str = "strict",
+):
+    """
+    Analogous to pickle._loads.
+    """
+    fd = io.BytesIO(bytes_object)
+    return Unpickler(
+        fd, fix_imports=fix_imports, encoding=encoding, errors=errors
+    ).load()
+
+
+@contextlib.contextmanager
+def patch_pickle() -> Generator[None, None, None]:
+    """
+    Temporarily patch pickle to use our unpickler.
+    """
+    orig_loads = pkl.loads
+    try:
+        setattr(pkl, "loads", loads)
+        yield
+    finally:
+        setattr(pkl, "loads", orig_loads)
diff --git a/.venv/lib/python3.13/site-packages/pandas/compat/pyarrow.py b/.venv/lib/python3.13/site-packages/pandas/compat/pyarrow.py
new file mode 100644
index 0000000000000000000000000000000000000000..aacf2cd85c8ca3a9c1604d5314a7c247998e00c8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/compat/pyarrow.py
@@ -0,0 +1,39 @@
+""" support pyarrow compatibility across versions """
+
+from __future__ import annotations
+
+from pandas.util.version import Version
+
+try:
+    import pyarrow as pa
+
+    _palv = Version(Version(pa.__version__).base_version)
+    pa_version_under10p1 = _palv < Version("10.0.1")
+    pa_version_under11p0 = _palv < Version("11.0.0")
+    pa_version_under12p0 = _palv < Version("12.0.0")
+    pa_version_under13p0 = _palv < Version("13.0.0")
+    pa_version_under14p0 = _palv < Version("14.0.0")
+    pa_version_under14p1 = _palv < Version("14.0.1")
+    pa_version_under15p0 = _palv < Version("15.0.0")
+    pa_version_under16p0 = _palv < Version("16.0.0")
+    pa_version_under17p0 = _palv < Version("17.0.0")
+    pa_version_under18p0 = _palv < Version("18.0.0")
+    pa_version_under19p0 = _palv < Version("19.0.0")
+    pa_version_under20p0 = _palv < Version("20.0.0")
+    pa_version_under21p0 = _palv < Version("21.0.0")
+    HAS_PYARROW = True
+except ImportError:
+    pa_version_under10p1 = True
+    pa_version_under11p0 = True
+    pa_version_under12p0 = True
+    pa_version_under13p0 = True
+    pa_version_under14p0 = True
+    pa_version_under14p1 = True
+    pa_version_under15p0 = True
+    pa_version_under16p0 = True
+    pa_version_under17p0 = True
+    pa_version_under18p0 = True
+    pa_version_under19p0 = True
+    pa_version_under20p0 = True
+    pa_version_under21p0 = True
+    HAS_PYARROW = False
diff --git a/.venv/lib/python3.13/site-packages/pandas/conftest.py b/.venv/lib/python3.13/site-packages/pandas/conftest.py
new file mode 100644
index 0000000000000000000000000000000000000000..35fe5cb475cde0e6ea6c181c6326b06cadc763ea
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/conftest.py
@@ -0,0 +1,2065 @@
+"""
+This file is very long and growing, but it was decided to not split it yet, as
+it's still manageable (2020-03-17, ~1.1k LoC). See gh-31989
+
+Instead of splitting it was decided to define sections here:
+- Configuration / Settings
+- Autouse fixtures
+- Common arguments
+- Missing values & co.
+- Classes
+- Indices
+- Series'
+- DataFrames
+- Operators & Operations
+- Data sets/files
+- Time zones
+- Dtypes
+- Misc
+"""
+from __future__ import annotations
+
+from collections import abc
+from datetime import (
+    date,
+    datetime,
+    time,
+    timedelta,
+    timezone,
+)
+from decimal import Decimal
+import operator
+import os
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+
+from dateutil.tz import (
+    tzlocal,
+    tzutc,
+)
+import hypothesis
+from hypothesis import strategies as st
+import numpy as np
+import pytest
+from pytz import (
+    FixedOffset,
+    utc,
+)
+
+from pandas._config.config import _get_option
+
+import pandas.util._test_decorators as td
+
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    IntervalDtype,
+)
+
+import pandas as pd
+from pandas import (
+    CategoricalIndex,
+    DataFrame,
+    Interval,
+    IntervalIndex,
+    Period,
+    RangeIndex,
+    Series,
+    Timedelta,
+    Timestamp,
+    date_range,
+    period_range,
+    timedelta_range,
+)
+import pandas._testing as tm
+from pandas.core import ops
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+)
+from pandas.util.version import Version
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+    )
+
+try:
+    import pyarrow as pa
+except ImportError:
+    has_pyarrow = False
+else:
+    del pa
+    has_pyarrow = True
+
+import zoneinfo
+
+try:
+    zoneinfo.ZoneInfo("UTC")
+except zoneinfo.ZoneInfoNotFoundError:
+    zoneinfo = None  # type: ignore[assignment]
+
+
+# ----------------------------------------------------------------
+# Configuration / Settings
+# ----------------------------------------------------------------
+# pytest
+
+
+def pytest_addoption(parser) -> None:
+    parser.addoption(
+        "--no-strict-data-files",
+        action="store_false",
+        help="Don't fail if a test is skipped for missing data file.",
+    )
+
+
+def ignore_doctest_warning(item: pytest.Item, path: str, message: str) -> None:
+    """Ignore doctest warning.
+
+    Parameters
+    ----------
+    item : pytest.Item
+        pytest test item.
+    path : str
+        Module path to Python object, e.g. "pandas.core.frame.DataFrame.append". A
+        warning will be filtered when item.name ends with in given path. So it is
+        sufficient to specify e.g. "DataFrame.append".
+    message : str
+        Message to be filtered.
+    """
+    if item.name.endswith(path):
+        item.add_marker(pytest.mark.filterwarnings(f"ignore:{message}"))
+
+
+def pytest_collection_modifyitems(items, config) -> None:
+    is_doctest = config.getoption("--doctest-modules") or config.getoption(
+        "--doctest-cython", default=False
+    )
+
+    # Warnings from doctests that can be ignored; place reason in comment above.
+    # Each entry specifies (path, message) - see the ignore_doctest_warning function
+    ignored_doctest_warnings = [
+        ("is_int64_dtype", "is_int64_dtype is deprecated"),
+        ("is_interval_dtype", "is_interval_dtype is deprecated"),
+        ("is_period_dtype", "is_period_dtype is deprecated"),
+        ("is_datetime64tz_dtype", "is_datetime64tz_dtype is deprecated"),
+        ("is_categorical_dtype", "is_categorical_dtype is deprecated"),
+        ("is_sparse", "is_sparse is deprecated"),
+        ("DataFrameGroupBy.fillna", "DataFrameGroupBy.fillna is deprecated"),
+        ("NDFrame.replace", "The 'method' keyword"),
+        ("NDFrame.replace", "Series.replace without 'value'"),
+        ("NDFrame.clip", "Downcasting behavior in Series and DataFrame methods"),
+        ("Series.idxmin", "The behavior of Series.idxmin"),
+        ("Series.idxmax", "The behavior of Series.idxmax"),
+        ("SeriesGroupBy.fillna", "SeriesGroupBy.fillna is deprecated"),
+        ("SeriesGroupBy.idxmin", "The behavior of Series.idxmin"),
+        ("SeriesGroupBy.idxmax", "The behavior of Series.idxmax"),
+        # Docstring divides by zero to show behavior difference
+        ("missing.mask_zero_div_zero", "divide by zero encountered"),
+        (
+            "to_pydatetime",
+            "The behavior of DatetimeProperties.to_pydatetime is deprecated",
+        ),
+        (
+            "pandas.core.generic.NDFrame.bool",
+            "(Series|DataFrame).bool is now deprecated and will be removed "
+            "in future version of pandas",
+        ),
+        (
+            "pandas.core.generic.NDFrame.first",
+            "first is deprecated and will be removed in a future version. "
+            "Please create a mask and filter using `.loc` instead",
+        ),
+        (
+            "Resampler.fillna",
+            "DatetimeIndexResampler.fillna is deprecated",
+        ),
+        (
+            "DataFrameGroupBy.fillna",
+            "DataFrameGroupBy.fillna with 'method' is deprecated",
+        ),
+        (
+            "DataFrameGroupBy.fillna",
+            "DataFrame.fillna with 'method' is deprecated",
+        ),
+        ("read_parquet", "Passing a BlockManager to DataFrame is deprecated"),
+    ]
+
+    if is_doctest:
+        for item in items:
+            for path, message in ignored_doctest_warnings:
+                ignore_doctest_warning(item, path, message)
+
+
+hypothesis_health_checks = [hypothesis.HealthCheck.too_slow]
+if Version(hypothesis.__version__) >= Version("6.83.2"):
+    hypothesis_health_checks.append(hypothesis.HealthCheck.differing_executors)
+
+# Hypothesis
+hypothesis.settings.register_profile(
+    "ci",
+    # Hypothesis timing checks are tuned for scalars by default, so we bump
+    # them from 200ms to 500ms per test case as the global default.  If this
+    # is too short for a specific test, (a) try to make it faster, and (b)
+    # if it really is slow add `@settings(deadline=...)` with a working value,
+    # or `deadline=None` to entirely disable timeouts for that test.
+    # 2022-02-09: Changed deadline from 500 -> None. Deadline leads to
+    # non-actionable, flaky CI failures (# GH 24641, 44969, 45118, 44969)
+    deadline=None,
+    suppress_health_check=tuple(hypothesis_health_checks),
+)
+hypothesis.settings.load_profile("ci")
+
+# Registering these strategies makes them globally available via st.from_type,
+# which is use for offsets in tests/tseries/offsets/test_offsets_properties.py
+for name in "MonthBegin MonthEnd BMonthBegin BMonthEnd".split():
+    cls = getattr(pd.tseries.offsets, name)
+    st.register_type_strategy(
+        cls, st.builds(cls, n=st.integers(-99, 99), normalize=st.booleans())
+    )
+
+for name in "YearBegin YearEnd BYearBegin BYearEnd".split():
+    cls = getattr(pd.tseries.offsets, name)
+    st.register_type_strategy(
+        cls,
+        st.builds(
+            cls,
+            n=st.integers(-5, 5),
+            normalize=st.booleans(),
+            month=st.integers(min_value=1, max_value=12),
+        ),
+    )
+
+for name in "QuarterBegin QuarterEnd BQuarterBegin BQuarterEnd".split():
+    cls = getattr(pd.tseries.offsets, name)
+    st.register_type_strategy(
+        cls,
+        st.builds(
+            cls,
+            n=st.integers(-24, 24),
+            normalize=st.booleans(),
+            startingMonth=st.integers(min_value=1, max_value=12),
+        ),
+    )
+
+
+# ----------------------------------------------------------------
+# Autouse fixtures
+# ----------------------------------------------------------------
+
+
+# https://github.com/pytest-dev/pytest/issues/11873
+# Would like to avoid autouse=True, but cannot as of pytest 8.0.0
+@pytest.fixture(autouse=True)
+def add_doctest_imports(doctest_namespace) -> None:
+    """
+    Make `np` and `pd` names available for doctests.
+    """
+    doctest_namespace["np"] = np
+    doctest_namespace["pd"] = pd
+
+
+@pytest.fixture(autouse=True)
+def configure_tests() -> None:
+    """
+    Configure settings for all tests and test modules.
+    """
+    pd.set_option("chained_assignment", "raise")
+
+
+# ----------------------------------------------------------------
+# Common arguments
+# ----------------------------------------------------------------
+@pytest.fixture(params=[0, 1, "index", "columns"], ids=lambda x: f"axis={repr(x)}")
+def axis(request):
+    """
+    Fixture for returning the axis numbers of a DataFrame.
+    """
+    return request.param
+
+
+axis_frame = axis
+
+
+@pytest.fixture(params=[1, "columns"], ids=lambda x: f"axis={repr(x)}")
+def axis_1(request):
+    """
+    Fixture for returning aliases of axis 1 of a DataFrame.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[True, False, None])
+def observed(request):
+    """
+    Pass in the observed keyword to groupby for [True, False]
+    This indicates whether categoricals should return values for
+    values which are not in the grouper [False / None], or only values which
+    appear in the grouper [True]. [None] is supported for future compatibility
+    if we decide to change the default (and would need to warn if this
+    parameter is not passed).
+    """
+    return request.param
+
+
+@pytest.fixture(params=[True, False, None])
+def ordered(request):
+    """
+    Boolean 'ordered' parameter for Categorical.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[True, False])
+def skipna(request):
+    """
+    Boolean 'skipna' parameter.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["first", "last", False])
+def keep(request):
+    """
+    Valid values for the 'keep' parameter used in
+    .duplicated or .drop_duplicates
+    """
+    return request.param
+
+
+@pytest.fixture(params=["both", "neither", "left", "right"])
+def inclusive_endpoints_fixture(request):
+    """
+    Fixture for trying all interval 'inclusive' parameters.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["left", "right", "both", "neither"])
+def closed(request):
+    """
+    Fixture for trying all interval closed parameters.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["left", "right", "both", "neither"])
+def other_closed(request):
+    """
+    Secondary closed fixture to allow parametrizing over all pairs of closed.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        None,
+        "gzip",
+        "bz2",
+        "zip",
+        "xz",
+        "tar",
+        pytest.param("zstd", marks=td.skip_if_no("zstandard")),
+    ]
+)
+def compression(request):
+    """
+    Fixture for trying common compression types in compression tests.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        "gzip",
+        "bz2",
+        "zip",
+        "xz",
+        "tar",
+        pytest.param("zstd", marks=td.skip_if_no("zstandard")),
+    ]
+)
+def compression_only(request):
+    """
+    Fixture for trying common compression types in compression tests excluding
+    uncompressed case.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[True, False])
+def writable(request):
+    """
+    Fixture that an array is writable.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["inner", "outer", "left", "right"])
+def join_type(request):
+    """
+    Fixture for trying all types of join operations.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["nlargest", "nsmallest"])
+def nselect_method(request):
+    """
+    Fixture for trying all nselect methods.
+    """
+    return request.param
+
+
+# ----------------------------------------------------------------
+# Missing values & co.
+# ----------------------------------------------------------------
+@pytest.fixture(params=tm.NULL_OBJECTS, ids=lambda x: type(x).__name__)
+def nulls_fixture(request):
+    """
+    Fixture for each null type in pandas.
+    """
+    return request.param
+
+
+nulls_fixture2 = nulls_fixture  # Generate cartesian product of nulls_fixture
+
+
+@pytest.fixture(params=[None, np.nan, pd.NaT])
+def unique_nulls_fixture(request):
+    """
+    Fixture for each null type in pandas, each null type exactly once.
+    """
+    return request.param
+
+
+# Generate cartesian product of unique_nulls_fixture:
+unique_nulls_fixture2 = unique_nulls_fixture
+
+
+@pytest.fixture(params=tm.NP_NAT_OBJECTS, ids=lambda x: type(x).__name__)
+def np_nat_fixture(request):
+    """
+    Fixture for each NaT type in numpy.
+    """
+    return request.param
+
+
+# Generate cartesian product of np_nat_fixture:
+np_nat_fixture2 = np_nat_fixture
+
+
+# ----------------------------------------------------------------
+# Classes
+# ----------------------------------------------------------------
+
+
+@pytest.fixture(params=[DataFrame, Series])
+def frame_or_series(request):
+    """
+    Fixture to parametrize over DataFrame and Series.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[Index, Series], ids=["index", "series"])
+def index_or_series(request):
+    """
+    Fixture to parametrize over Index and Series, made necessary by a mypy
+    bug, giving an error:
+
+    List item 0 has incompatible type "Type[Series]"; expected "Type[PandasObject]"
+
+    See GH#29725
+    """
+    return request.param
+
+
+# Generate cartesian product of index_or_series fixture:
+index_or_series2 = index_or_series
+
+
+@pytest.fixture(params=[Index, Series, pd.array], ids=["index", "series", "array"])
+def index_or_series_or_array(request):
+    """
+    Fixture to parametrize over Index, Series, and ExtensionArray
+    """
+    return request.param
+
+
+@pytest.fixture(params=[Index, Series, DataFrame, pd.array], ids=lambda x: x.__name__)
+def box_with_array(request):
+    """
+    Fixture to test behavior for Index, Series, DataFrame, and pandas Array
+    classes
+    """
+    return request.param
+
+
+box_with_array2 = box_with_array
+
+
+@pytest.fixture
+def dict_subclass() -> type[dict]:
+    """
+    Fixture for a dictionary subclass.
+    """
+
+    class TestSubDict(dict):
+        def __init__(self, *args, **kwargs) -> None:
+            dict.__init__(self, *args, **kwargs)
+
+    return TestSubDict
+
+
+@pytest.fixture
+def non_dict_mapping_subclass() -> type[abc.Mapping]:
+    """
+    Fixture for a non-mapping dictionary subclass.
+    """
+
+    class TestNonDictMapping(abc.Mapping):
+        def __init__(self, underlying_dict) -> None:
+            self._data = underlying_dict
+
+        def __getitem__(self, key):
+            return self._data.__getitem__(key)
+
+        def __iter__(self) -> Iterator:
+            return self._data.__iter__()
+
+        def __len__(self) -> int:
+            return self._data.__len__()
+
+    return TestNonDictMapping
+
+
+# ----------------------------------------------------------------
+# Indices
+# ----------------------------------------------------------------
+@pytest.fixture
+def multiindex_year_month_day_dataframe_random_data():
+    """
+    DataFrame with 3 level MultiIndex (year, month, day) covering
+    first 100 business days from 2000-01-01 with random data
+    """
+    tdf = DataFrame(
+        np.random.default_rng(2).standard_normal((100, 4)),
+        columns=Index(list("ABCD")),
+        index=date_range("2000-01-01", periods=100, freq="B"),
+    )
+    ymd = tdf.groupby([lambda x: x.year, lambda x: x.month, lambda x: x.day]).sum()
+    # use int64 Index, to make sure things work
+    ymd.index = ymd.index.set_levels([lev.astype("i8") for lev in ymd.index.levels])
+    ymd.index.set_names(["year", "month", "day"], inplace=True)
+    return ymd
+
+
+@pytest.fixture
+def lexsorted_two_level_string_multiindex() -> MultiIndex:
+    """
+    2-level MultiIndex, lexsorted, with string names.
+    """
+    return MultiIndex(
+        levels=[["foo", "bar", "baz", "qux"], ["one", "two", "three"]],
+        codes=[[0, 0, 0, 1, 1, 2, 2, 3, 3, 3], [0, 1, 2, 0, 1, 1, 2, 0, 1, 2]],
+        names=["first", "second"],
+    )
+
+
+@pytest.fixture
+def multiindex_dataframe_random_data(
+    lexsorted_two_level_string_multiindex,
+) -> DataFrame:
+    """DataFrame with 2 level MultiIndex with random data"""
+    index = lexsorted_two_level_string_multiindex
+    return DataFrame(
+        np.random.default_rng(2).standard_normal((10, 3)),
+        index=index,
+        columns=Index(["A", "B", "C"], name="exp"),
+    )
+
+
+def _create_multiindex():
+    """
+    MultiIndex used to test the general functionality of this object
+    """
+
+    # See Also: tests.multi.conftest.idx
+    major_axis = Index(["foo", "bar", "baz", "qux"])
+    minor_axis = Index(["one", "two"])
+
+    major_codes = np.array([0, 0, 1, 2, 3, 3])
+    minor_codes = np.array([0, 1, 0, 1, 0, 1])
+    index_names = ["first", "second"]
+    return MultiIndex(
+        levels=[major_axis, minor_axis],
+        codes=[major_codes, minor_codes],
+        names=index_names,
+        verify_integrity=False,
+    )
+
+
+def _create_mi_with_dt64tz_level():
+    """
+    MultiIndex with a level that is a tzaware DatetimeIndex.
+    """
+    # GH#8367 round trip with pickle
+    return MultiIndex.from_product(
+        [[1, 2], ["a", "b"], date_range("20130101", periods=3, tz="US/Eastern")],
+        names=["one", "two", "three"],
+    )
+
+
+indices_dict = {
+    "object": Index([f"pandas_{i}" for i in range(100)], dtype=object),
+    "string": Index([f"pandas_{i}" for i in range(100)], dtype="str"),
+    "datetime": date_range("2020-01-01", periods=100),
+    "datetime-tz": date_range("2020-01-01", periods=100, tz="US/Pacific"),
+    "period": period_range("2020-01-01", periods=100, freq="D"),
+    "timedelta": timedelta_range(start="1 day", periods=100, freq="D"),
+    "range": RangeIndex(100),
+    "int8": Index(np.arange(100), dtype="int8"),
+    "int16": Index(np.arange(100), dtype="int16"),
+    "int32": Index(np.arange(100), dtype="int32"),
+    "int64": Index(np.arange(100), dtype="int64"),
+    "uint8": Index(np.arange(100), dtype="uint8"),
+    "uint16": Index(np.arange(100), dtype="uint16"),
+    "uint32": Index(np.arange(100), dtype="uint32"),
+    "uint64": Index(np.arange(100), dtype="uint64"),
+    "float32": Index(np.arange(100), dtype="float32"),
+    "float64": Index(np.arange(100), dtype="float64"),
+    "bool-object": Index([True, False] * 5, dtype=object),
+    "bool-dtype": Index([True, False] * 5, dtype=bool),
+    "complex64": Index(
+        np.arange(100, dtype="complex64") + 1.0j * np.arange(100, dtype="complex64")
+    ),
+    "complex128": Index(
+        np.arange(100, dtype="complex128") + 1.0j * np.arange(100, dtype="complex128")
+    ),
+    "categorical": CategoricalIndex(list("abcd") * 25),
+    "interval": IntervalIndex.from_breaks(np.linspace(0, 100, num=101)),
+    "empty": Index([]),
+    "tuples": MultiIndex.from_tuples(zip(["foo", "bar", "baz"], [1, 2, 3])),
+    "mi-with-dt64tz-level": _create_mi_with_dt64tz_level(),
+    "multi": _create_multiindex(),
+    "repeats": Index([0, 0, 1, 1, 2, 2]),
+    "nullable_int": Index(np.arange(100), dtype="Int64"),
+    "nullable_uint": Index(np.arange(100), dtype="UInt16"),
+    "nullable_float": Index(np.arange(100), dtype="Float32"),
+    "nullable_bool": Index(np.arange(100).astype(bool), dtype="boolean"),
+    "string-python": Index(
+        pd.array([f"pandas_{i}" for i in range(100)], dtype="string[python]")
+    ),
+}
+if has_pyarrow:
+    idx = Index(pd.array([f"pandas_{i}" for i in range(100)], dtype="string[pyarrow]"))
+    indices_dict["string-pyarrow"] = idx
+
+
+@pytest.fixture(params=indices_dict.keys())
+def index(request):
+    """
+    Fixture for many "simple" kinds of indices.
+
+    These indices are unlikely to cover corner cases, e.g.
+        - no names
+        - no NaTs/NaNs
+        - no values near implementation bounds
+        - ...
+    """
+    # copy to avoid mutation, e.g. setting .name
+    return indices_dict[request.param].copy()
+
+
+# Needed to generate cartesian product of indices
+index_fixture2 = index
+
+
+@pytest.fixture(
+    params=[
+        key for key, value in indices_dict.items() if not isinstance(value, MultiIndex)
+    ]
+)
+def index_flat(request):
+    """
+    index fixture, but excluding MultiIndex cases.
+    """
+    key = request.param
+    return indices_dict[key].copy()
+
+
+# Alias so we can test with cartesian product of index_flat
+index_flat2 = index_flat
+
+
+@pytest.fixture(
+    params=[
+        key
+        for key, value in indices_dict.items()
+        if not (
+            key.startswith(("int", "uint", "float"))
+            or key in ["range", "empty", "repeats", "bool-dtype"]
+        )
+        and not isinstance(value, MultiIndex)
+    ]
+)
+def index_with_missing(request):
+    """
+    Fixture for indices with missing values.
+
+    Integer-dtype and empty cases are excluded because they cannot hold missing
+    values.
+
+    MultiIndex is excluded because isna() is not defined for MultiIndex.
+    """
+
+    # GH 35538. Use deep copy to avoid illusive bug on np-dev
+    # GHA pipeline that writes into indices_dict despite copy
+    ind = indices_dict[request.param].copy(deep=True)
+    vals = ind.values.copy()
+    if request.param in ["tuples", "mi-with-dt64tz-level", "multi"]:
+        # For setting missing values in the top level of MultiIndex
+        vals = ind.tolist()
+        vals[0] = (None,) + vals[0][1:]
+        vals[-1] = (None,) + vals[-1][1:]
+        return MultiIndex.from_tuples(vals)
+    else:
+        vals[0] = None
+        vals[-1] = None
+        return type(ind)(vals)
+
+
+# ----------------------------------------------------------------
+# Series'
+# ----------------------------------------------------------------
+@pytest.fixture
+def string_series() -> Series:
+    """
+    Fixture for Series of floats with Index of unique strings
+    """
+    return Series(
+        np.arange(30, dtype=np.float64) * 1.1,
+        index=Index([f"i_{i}" for i in range(30)]),
+        name="series",
+    )
+
+
+@pytest.fixture
+def object_series() -> Series:
+    """
+    Fixture for Series of dtype object with Index of unique strings
+    """
+    data = [f"foo_{i}" for i in range(30)]
+    index = Index([f"bar_{i}" for i in range(30)])
+    return Series(data, index=index, name="objects", dtype=object)
+
+
+@pytest.fixture
+def datetime_series() -> Series:
+    """
+    Fixture for Series of floats with DatetimeIndex
+    """
+    return Series(
+        np.random.default_rng(2).standard_normal(30),
+        index=date_range("2000-01-01", periods=30, freq="B"),
+        name="ts",
+    )
+
+
+def _create_series(index):
+    """Helper for the _series dict"""
+    size = len(index)
+    data = np.random.default_rng(2).standard_normal(size)
+    return Series(data, index=index, name="a", copy=False)
+
+
+_series = {
+    f"series-with-{index_id}-index": _create_series(index)
+    for index_id, index in indices_dict.items()
+}
+
+
+@pytest.fixture
+def series_with_simple_index(index) -> Series:
+    """
+    Fixture for tests on series with changing types of indices.
+    """
+    return _create_series(index)
+
+
+_narrow_series = {
+    f"{dtype.__name__}-series": Series(
+        range(30), index=[f"i-{i}" for i in range(30)], name="a", dtype=dtype
+    )
+    for dtype in tm.NARROW_NP_DTYPES
+}
+
+
+_index_or_series_objs = {**indices_dict, **_series, **_narrow_series}
+
+
+@pytest.fixture(params=_index_or_series_objs.keys())
+def index_or_series_obj(request):
+    """
+    Fixture for tests on indexes, series and series with a narrow dtype
+    copy to avoid mutation, e.g. setting .name
+    """
+    return _index_or_series_objs[request.param].copy(deep=True)
+
+
+_typ_objects_series = {
+    f"{dtype.__name__}-series": Series(dtype) for dtype in tm.PYTHON_DATA_TYPES
+}
+
+
+_index_or_series_memory_objs = {
+    **indices_dict,
+    **_series,
+    **_narrow_series,
+    **_typ_objects_series,
+}
+
+
+@pytest.fixture(params=_index_or_series_memory_objs.keys())
+def index_or_series_memory_obj(request):
+    """
+    Fixture for tests on indexes, series, series with a narrow dtype and
+    series with empty objects type
+    copy to avoid mutation, e.g. setting .name
+    """
+    return _index_or_series_memory_objs[request.param].copy(deep=True)
+
+
+# ----------------------------------------------------------------
+# DataFrames
+# ----------------------------------------------------------------
+@pytest.fixture
+def int_frame() -> DataFrame:
+    """
+    Fixture for DataFrame of ints with index of unique strings
+
+    Columns are ['A', 'B', 'C', 'D']
+    """
+    return DataFrame(
+        np.ones((30, 4), dtype=np.int64),
+        index=Index([f"foo_{i}" for i in range(30)]),
+        columns=Index(list("ABCD")),
+    )
+
+
+@pytest.fixture
+def float_frame() -> DataFrame:
+    """
+    Fixture for DataFrame of floats with index of unique strings
+
+    Columns are ['A', 'B', 'C', 'D'].
+    """
+    return DataFrame(
+        np.random.default_rng(2).standard_normal((30, 4)),
+        index=Index([f"foo_{i}" for i in range(30)]),
+        columns=Index(list("ABCD")),
+    )
+
+
+@pytest.fixture
+def rand_series_with_duplicate_datetimeindex() -> Series:
+    """
+    Fixture for Series with a DatetimeIndex that has duplicates.
+    """
+    dates = [
+        datetime(2000, 1, 2),
+        datetime(2000, 1, 2),
+        datetime(2000, 1, 2),
+        datetime(2000, 1, 3),
+        datetime(2000, 1, 3),
+        datetime(2000, 1, 3),
+        datetime(2000, 1, 4),
+        datetime(2000, 1, 4),
+        datetime(2000, 1, 4),
+        datetime(2000, 1, 5),
+    ]
+
+    return Series(np.random.default_rng(2).standard_normal(len(dates)), index=dates)
+
+
+# ----------------------------------------------------------------
+# Scalars
+# ----------------------------------------------------------------
+@pytest.fixture(
+    params=[
+        (Interval(left=0, right=5), IntervalDtype("int64", "right")),
+        (Interval(left=0.1, right=0.5), IntervalDtype("float64", "right")),
+        (Period("2012-01", freq="M"), "period[M]"),
+        (Period("2012-02-01", freq="D"), "period[D]"),
+        (
+            Timestamp("2011-01-01", tz="US/Eastern"),
+            DatetimeTZDtype(unit="s", tz="US/Eastern"),
+        ),
+        (Timedelta(seconds=500), "timedelta64[ns]"),
+    ]
+)
+def ea_scalar_and_dtype(request):
+    return request.param
+
+
+# ----------------------------------------------------------------
+# Operators & Operations
+# ----------------------------------------------------------------
+
+
+@pytest.fixture(params=tm.arithmetic_dunder_methods)
+def all_arithmetic_operators(request):
+    """
+    Fixture for dunder names for common arithmetic operations.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        operator.add,
+        ops.radd,
+        operator.sub,
+        ops.rsub,
+        operator.mul,
+        ops.rmul,
+        operator.truediv,
+        ops.rtruediv,
+        operator.floordiv,
+        ops.rfloordiv,
+        operator.mod,
+        ops.rmod,
+        operator.pow,
+        ops.rpow,
+        operator.eq,
+        operator.ne,
+        operator.lt,
+        operator.le,
+        operator.gt,
+        operator.ge,
+        operator.and_,
+        ops.rand_,
+        operator.xor,
+        ops.rxor,
+        operator.or_,
+        ops.ror_,
+    ]
+)
+def all_binary_operators(request):
+    """
+    Fixture for operator and roperator arithmetic, comparison, and logical ops.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        operator.add,
+        ops.radd,
+        operator.sub,
+        ops.rsub,
+        operator.mul,
+        ops.rmul,
+        operator.truediv,
+        ops.rtruediv,
+        operator.floordiv,
+        ops.rfloordiv,
+        operator.mod,
+        ops.rmod,
+        operator.pow,
+        ops.rpow,
+    ]
+)
+def all_arithmetic_functions(request):
+    """
+    Fixture for operator and roperator arithmetic functions.
+
+    Notes
+    -----
+    This includes divmod and rdivmod, whereas all_arithmetic_operators
+    does not.
+    """
+    return request.param
+
+
+_all_numeric_reductions = [
+    "count",
+    "sum",
+    "max",
+    "min",
+    "mean",
+    "prod",
+    "std",
+    "var",
+    "median",
+    "kurt",
+    "skew",
+    "sem",
+]
+
+
+@pytest.fixture(params=_all_numeric_reductions)
+def all_numeric_reductions(request):
+    """
+    Fixture for numeric reduction names.
+    """
+    return request.param
+
+
+_all_boolean_reductions = ["all", "any"]
+
+
+@pytest.fixture(params=_all_boolean_reductions)
+def all_boolean_reductions(request):
+    """
+    Fixture for boolean reduction names.
+    """
+    return request.param
+
+
+_all_reductions = _all_numeric_reductions + _all_boolean_reductions
+
+
+@pytest.fixture(params=_all_reductions)
+def all_reductions(request):
+    """
+    Fixture for all (boolean + numeric) reduction names.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        operator.eq,
+        operator.ne,
+        operator.gt,
+        operator.ge,
+        operator.lt,
+        operator.le,
+    ]
+)
+def comparison_op(request):
+    """
+    Fixture for operator module comparison functions.
+    """
+    return request.param
+
+
+@pytest.fixture(params=["__le__", "__lt__", "__ge__", "__gt__"])
+def compare_operators_no_eq_ne(request):
+    """
+    Fixture for dunder names for compare operations except == and !=
+
+    * >=
+    * >
+    * <
+    * <=
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=["__and__", "__rand__", "__or__", "__ror__", "__xor__", "__rxor__"]
+)
+def all_logical_operators(request):
+    """
+    Fixture for dunder names for common logical operations
+
+    * |
+    * &
+    * ^
+    """
+    return request.param
+
+
+_all_numeric_accumulations = ["cumsum", "cumprod", "cummin", "cummax"]
+
+
+@pytest.fixture(params=_all_numeric_accumulations)
+def all_numeric_accumulations(request):
+    """
+    Fixture for numeric accumulation names
+    """
+    return request.param
+
+
+# ----------------------------------------------------------------
+# Data sets/files
+# ----------------------------------------------------------------
+@pytest.fixture
+def strict_data_files(pytestconfig):
+    """
+    Returns the configuration for the test setting `--no-strict-data-files`.
+    """
+    return pytestconfig.getoption("--no-strict-data-files")
+
+
+@pytest.fixture
+def datapath(strict_data_files: str) -> Callable[..., str]:
+    """
+    Get the path to a data file.
+
+    Parameters
+    ----------
+    path : str
+        Path to the file, relative to ``pandas/tests/``
+
+    Returns
+    -------
+    path including ``pandas/tests``.
+
+    Raises
+    ------
+    ValueError
+        If the path doesn't exist and the --no-strict-data-files option is not set.
+    """
+    BASE_PATH = os.path.join(os.path.dirname(__file__), "tests")
+
+    def deco(*args):
+        path = os.path.join(BASE_PATH, *args)
+        if not os.path.exists(path):
+            if strict_data_files:
+                raise ValueError(
+                    f"Could not find file {path} and --no-strict-data-files is not set."
+                )
+            pytest.skip(f"Could not find {path}.")
+        return path
+
+    return deco
+
+
+# ----------------------------------------------------------------
+# Time zones
+# ----------------------------------------------------------------
+TIMEZONES = [
+    None,
+    "UTC",
+    "US/Eastern",
+    "Asia/Tokyo",
+    "dateutil/US/Pacific",
+    "dateutil/Asia/Singapore",
+    "+01:15",
+    "-02:15",
+    "UTC+01:15",
+    "UTC-02:15",
+    tzutc(),
+    tzlocal(),
+    FixedOffset(300),
+    FixedOffset(0),
+    FixedOffset(-300),
+    timezone.utc,
+    timezone(timedelta(hours=1)),
+    timezone(timedelta(hours=-1), name="foo"),
+]
+if zoneinfo is not None:
+    TIMEZONES.extend(
+        [
+            zoneinfo.ZoneInfo("US/Pacific"),  # type: ignore[list-item]
+            zoneinfo.ZoneInfo("UTC"),  # type: ignore[list-item]
+        ]
+    )
+TIMEZONE_IDS = [repr(i) for i in TIMEZONES]
+
+
+@td.parametrize_fixture_doc(str(TIMEZONE_IDS))
+@pytest.fixture(params=TIMEZONES, ids=TIMEZONE_IDS)
+def tz_naive_fixture(request):
+    """
+    Fixture for trying timezones including default (None): {0}
+    """
+    return request.param
+
+
+@td.parametrize_fixture_doc(str(TIMEZONE_IDS[1:]))
+@pytest.fixture(params=TIMEZONES[1:], ids=TIMEZONE_IDS[1:])
+def tz_aware_fixture(request):
+    """
+    Fixture for trying explicit timezones: {0}
+    """
+    return request.param
+
+
+# Generate cartesian product of tz_aware_fixture:
+tz_aware_fixture2 = tz_aware_fixture
+
+
+_UTCS = ["utc", "dateutil/UTC", utc, tzutc(), timezone.utc]
+if zoneinfo is not None:
+    _UTCS.append(zoneinfo.ZoneInfo("UTC"))
+
+
+@pytest.fixture(params=_UTCS)
+def utc_fixture(request):
+    """
+    Fixture to provide variants of UTC timezone strings and tzinfo objects.
+    """
+    return request.param
+
+
+utc_fixture2 = utc_fixture
+
+
+@pytest.fixture(params=["s", "ms", "us", "ns"])
+def unit(request):
+    """
+    datetime64 units we support.
+    """
+    return request.param
+
+
+unit2 = unit
+
+
+# ----------------------------------------------------------------
+# Dtypes
+# ----------------------------------------------------------------
+@pytest.fixture(params=tm.STRING_DTYPES)
+def string_dtype(request):
+    """
+    Parametrized fixture for string dtypes.
+
+    * str
+    * 'str'
+    * 'U'
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        ("python", pd.NA),
+        pytest.param(("pyarrow", pd.NA), marks=td.skip_if_no("pyarrow")),
+        pytest.param(("pyarrow", np.nan), marks=td.skip_if_no("pyarrow")),
+        ("python", np.nan),
+    ],
+    ids=[
+        "string=string[python]",
+        "string=string[pyarrow]",
+        "string=str[pyarrow]",
+        "string=str[python]",
+    ],
+)
+def string_dtype_no_object(request):
+    """
+    Parametrized fixture for string dtypes.
+    * 'string[python]' (NA variant)
+    * 'string[pyarrow]' (NA variant)
+    * 'str' (NaN variant, with pyarrow)
+    * 'str' (NaN variant, without pyarrow)
+    """
+    # need to instantiate the StringDtype here instead of in the params
+    # to avoid importing pyarrow during test collection
+    storage, na_value = request.param
+    return pd.StringDtype(storage, na_value)
+
+
+@pytest.fixture(
+    params=[
+        "string[python]",
+        pytest.param("string[pyarrow]", marks=td.skip_if_no("pyarrow")),
+    ]
+)
+def nullable_string_dtype(request):
+    """
+    Parametrized fixture for string dtypes.
+
+    * 'string[python]'
+    * 'string[pyarrow]'
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        pytest.param(("pyarrow", np.nan), marks=td.skip_if_no("pyarrow")),
+        pytest.param(("pyarrow", pd.NA), marks=td.skip_if_no("pyarrow")),
+    ]
+)
+def pyarrow_string_dtype(request):
+    """
+    Parametrized fixture for string dtypes backed by Pyarrow.
+
+    * 'str[pyarrow]'
+    * 'string[pyarrow]'
+    """
+    return pd.StringDtype(*request.param)
+
+
+@pytest.fixture(
+    params=[
+        "python",
+        pytest.param("pyarrow", marks=td.skip_if_no("pyarrow")),
+    ]
+)
+def string_storage(request):
+    """
+    Parametrized fixture for pd.options.mode.string_storage.
+
+    * 'python'
+    * 'pyarrow'
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        ("python", pd.NA),
+        pytest.param(("pyarrow", pd.NA), marks=td.skip_if_no("pyarrow")),
+        pytest.param(("pyarrow", np.nan), marks=td.skip_if_no("pyarrow")),
+        ("python", np.nan),
+    ],
+    ids=[
+        "string=string[python]",
+        "string=string[pyarrow]",
+        "string=str[pyarrow]",
+        "string=str[python]",
+    ],
+)
+def string_dtype_arguments(request):
+    """
+    Parametrized fixture for StringDtype storage and na_value.
+
+    * 'python' + pd.NA
+    * 'pyarrow' + pd.NA
+    * 'pyarrow' + np.nan
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        "numpy_nullable",
+        pytest.param("pyarrow", marks=td.skip_if_no("pyarrow")),
+    ]
+)
+def dtype_backend(request):
+    """
+    Parametrized fixture for pd.options.mode.string_storage.
+
+    * 'python'
+    * 'pyarrow'
+    """
+    return request.param
+
+
+# Alias so we can test with cartesian product of string_storage
+string_storage2 = string_storage
+string_dtype_arguments2 = string_dtype_arguments
+
+
+@pytest.fixture(params=tm.BYTES_DTYPES)
+def bytes_dtype(request):
+    """
+    Parametrized fixture for bytes dtypes.
+
+    * bytes
+    * 'bytes'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.OBJECT_DTYPES)
+def object_dtype(request):
+    """
+    Parametrized fixture for object dtypes.
+
+    * object
+    * 'object'
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        np.dtype("object"),
+        ("python", pd.NA),
+        pytest.param(("pyarrow", pd.NA), marks=td.skip_if_no("pyarrow")),
+        pytest.param(("pyarrow", np.nan), marks=td.skip_if_no("pyarrow")),
+        ("python", np.nan),
+    ],
+    ids=[
+        "string=object",
+        "string=string[python]",
+        "string=string[pyarrow]",
+        "string=str[pyarrow]",
+        "string=str[python]",
+    ],
+)
+def any_string_dtype(request):
+    """
+    Parametrized fixture for string dtypes.
+    * 'object'
+    * 'string[python]' (NA variant)
+    * 'string[pyarrow]' (NA variant)
+    * 'str' (NaN variant, with pyarrow)
+    * 'str' (NaN variant, without pyarrow)
+    """
+    if isinstance(request.param, np.dtype):
+        return request.param
+    else:
+        # need to instantiate the StringDtype here instead of in the params
+        # to avoid importing pyarrow during test collection
+        storage, na_value = request.param
+        return pd.StringDtype(storage, na_value)
+
+
+@pytest.fixture(params=tm.DATETIME64_DTYPES)
+def datetime64_dtype(request):
+    """
+    Parametrized fixture for datetime64 dtypes.
+
+    * 'datetime64[ns]'
+    * 'M8[ns]'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.TIMEDELTA64_DTYPES)
+def timedelta64_dtype(request):
+    """
+    Parametrized fixture for timedelta64 dtypes.
+
+    * 'timedelta64[ns]'
+    * 'm8[ns]'
+    """
+    return request.param
+
+
+@pytest.fixture
+def fixed_now_ts() -> Timestamp:
+    """
+    Fixture emits fixed Timestamp.now()
+    """
+    return Timestamp(  # pyright: ignore[reportGeneralTypeIssues]
+        year=2021, month=1, day=1, hour=12, minute=4, second=13, microsecond=22
+    )
+
+
+@pytest.fixture(params=tm.FLOAT_NUMPY_DTYPES)
+def float_numpy_dtype(request):
+    """
+    Parameterized fixture for float dtypes.
+
+    * float
+    * 'float32'
+    * 'float64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.FLOAT_EA_DTYPES)
+def float_ea_dtype(request):
+    """
+    Parameterized fixture for float dtypes.
+
+    * 'Float32'
+    * 'Float64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_FLOAT_DTYPES)
+def any_float_dtype(request):
+    """
+    Parameterized fixture for float dtypes.
+
+    * float
+    * 'float32'
+    * 'float64'
+    * 'Float32'
+    * 'Float64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.COMPLEX_DTYPES)
+def complex_dtype(request):
+    """
+    Parameterized fixture for complex dtypes.
+
+    * complex
+    * 'complex64'
+    * 'complex128'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.COMPLEX_FLOAT_DTYPES)
+def complex_or_float_dtype(request):
+    """
+    Parameterized fixture for complex and numpy float dtypes.
+
+    * complex
+    * 'complex64'
+    * 'complex128'
+    * float
+    * 'float32'
+    * 'float64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.SIGNED_INT_NUMPY_DTYPES)
+def any_signed_int_numpy_dtype(request):
+    """
+    Parameterized fixture for signed integer dtypes.
+
+    * int
+    * 'int8'
+    * 'int16'
+    * 'int32'
+    * 'int64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.UNSIGNED_INT_NUMPY_DTYPES)
+def any_unsigned_int_numpy_dtype(request):
+    """
+    Parameterized fixture for unsigned integer dtypes.
+
+    * 'uint8'
+    * 'uint16'
+    * 'uint32'
+    * 'uint64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_INT_NUMPY_DTYPES)
+def any_int_numpy_dtype(request):
+    """
+    Parameterized fixture for any integer dtype.
+
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_INT_EA_DTYPES)
+def any_int_ea_dtype(request):
+    """
+    Parameterized fixture for any nullable integer dtype.
+
+    * 'UInt8'
+    * 'Int8'
+    * 'UInt16'
+    * 'Int16'
+    * 'UInt32'
+    * 'Int32'
+    * 'UInt64'
+    * 'Int64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_INT_DTYPES)
+def any_int_dtype(request):
+    """
+    Parameterized fixture for any nullable integer dtype.
+
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    * 'UInt8'
+    * 'Int8'
+    * 'UInt16'
+    * 'Int16'
+    * 'UInt32'
+    * 'Int32'
+    * 'UInt64'
+    * 'Int64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_INT_EA_DTYPES + tm.FLOAT_EA_DTYPES)
+def any_numeric_ea_dtype(request):
+    """
+    Parameterized fixture for any nullable integer dtype and
+    any float ea dtypes.
+
+    * 'UInt8'
+    * 'Int8'
+    * 'UInt16'
+    * 'Int16'
+    * 'UInt32'
+    * 'Int32'
+    * 'UInt64'
+    * 'Int64'
+    * 'Float32'
+    * 'Float64'
+    """
+    return request.param
+
+
+#  Unsupported operand types for + ("List[Union[str, ExtensionDtype, dtype[Any],
+#  Type[object]]]" and "List[str]")
+@pytest.fixture(
+    params=tm.ALL_INT_EA_DTYPES
+    + tm.FLOAT_EA_DTYPES
+    + tm.ALL_INT_PYARROW_DTYPES_STR_REPR
+    + tm.FLOAT_PYARROW_DTYPES_STR_REPR  # type: ignore[operator]
+)
+def any_numeric_ea_and_arrow_dtype(request):
+    """
+    Parameterized fixture for any nullable integer dtype and
+    any float ea dtypes.
+
+    * 'UInt8'
+    * 'Int8'
+    * 'UInt16'
+    * 'Int16'
+    * 'UInt32'
+    * 'Int32'
+    * 'UInt64'
+    * 'Int64'
+    * 'Float32'
+    * 'Float64'
+    * 'uint8[pyarrow]'
+    * 'int8[pyarrow]'
+    * 'uint16[pyarrow]'
+    * 'int16[pyarrow]'
+    * 'uint32[pyarrow]'
+    * 'int32[pyarrow]'
+    * 'uint64[pyarrow]'
+    * 'int64[pyarrow]'
+    * 'float32[pyarrow]'
+    * 'float64[pyarrow]'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.SIGNED_INT_EA_DTYPES)
+def any_signed_int_ea_dtype(request):
+    """
+    Parameterized fixture for any signed nullable integer dtype.
+
+    * 'Int8'
+    * 'Int16'
+    * 'Int32'
+    * 'Int64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_REAL_NUMPY_DTYPES)
+def any_real_numpy_dtype(request):
+    """
+    Parameterized fixture for any (purely) real numeric dtype.
+
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    * float
+    * 'float32'
+    * 'float64'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_REAL_DTYPES)
+def any_real_numeric_dtype(request):
+    """
+    Parameterized fixture for any (purely) real numeric dtype.
+
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    * float
+    * 'float32'
+    * 'float64'
+
+    and associated ea dtypes.
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_NUMPY_DTYPES)
+def any_numpy_dtype(request):
+    """
+    Parameterized fixture for all numpy dtypes.
+
+    * bool
+    * 'bool'
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    * float
+    * 'float32'
+    * 'float64'
+    * complex
+    * 'complex64'
+    * 'complex128'
+    * str
+    * 'str'
+    * 'U'
+    * bytes
+    * 'bytes'
+    * 'datetime64[ns]'
+    * 'M8[ns]'
+    * 'timedelta64[ns]'
+    * 'm8[ns]'
+    * object
+    * 'object'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_REAL_NULLABLE_DTYPES)
+def any_real_nullable_dtype(request):
+    """
+    Parameterized fixture for all real dtypes that can hold NA.
+
+    * float
+    * 'float32'
+    * 'float64'
+    * 'Float32'
+    * 'Float64'
+    * 'UInt8'
+    * 'UInt16'
+    * 'UInt32'
+    * 'UInt64'
+    * 'Int8'
+    * 'Int16'
+    * 'Int32'
+    * 'Int64'
+    * 'uint8[pyarrow]'
+    * 'uint16[pyarrow]'
+    * 'uint32[pyarrow]'
+    * 'uint64[pyarrow]'
+    * 'int8[pyarrow]'
+    * 'int16[pyarrow]'
+    * 'int32[pyarrow]'
+    * 'int64[pyarrow]'
+    * 'float[pyarrow]'
+    * 'double[pyarrow]'
+    """
+    return request.param
+
+
+@pytest.fixture(params=tm.ALL_NUMERIC_DTYPES)
+def any_numeric_dtype(request):
+    """
+    Parameterized fixture for all numeric dtypes.
+
+    * int
+    * 'int8'
+    * 'uint8'
+    * 'int16'
+    * 'uint16'
+    * 'int32'
+    * 'uint32'
+    * 'int64'
+    * 'uint64'
+    * float
+    * 'float32'
+    * 'float64'
+    * complex
+    * 'complex64'
+    * 'complex128'
+    * 'UInt8'
+    * 'Int8'
+    * 'UInt16'
+    * 'Int16'
+    * 'UInt32'
+    * 'Int32'
+    * 'UInt64'
+    * 'Int64'
+    * 'Float32'
+    * 'Float64'
+    """
+    return request.param
+
+
+# categoricals are handled separately
+_any_skipna_inferred_dtype = [
+    ("string", ["a", np.nan, "c"]),
+    ("string", ["a", pd.NA, "c"]),
+    ("mixed", ["a", pd.NaT, "c"]),  # pd.NaT not considered valid by is_string_array
+    ("bytes", [b"a", np.nan, b"c"]),
+    ("empty", [np.nan, np.nan, np.nan]),
+    ("empty", []),
+    ("mixed-integer", ["a", np.nan, 2]),
+    ("mixed", ["a", np.nan, 2.0]),
+    ("floating", [1.0, np.nan, 2.0]),
+    ("integer", [1, np.nan, 2]),
+    ("mixed-integer-float", [1, np.nan, 2.0]),
+    ("decimal", [Decimal(1), np.nan, Decimal(2)]),
+    ("boolean", [True, np.nan, False]),
+    ("boolean", [True, pd.NA, False]),
+    ("datetime64", [np.datetime64("2013-01-01"), np.nan, np.datetime64("2018-01-01")]),
+    ("datetime", [Timestamp("20130101"), np.nan, Timestamp("20180101")]),
+    ("date", [date(2013, 1, 1), np.nan, date(2018, 1, 1)]),
+    ("complex", [1 + 1j, np.nan, 2 + 2j]),
+    # The following dtype is commented out due to GH 23554
+    # ('timedelta64', [np.timedelta64(1, 'D'),
+    #                  np.nan, np.timedelta64(2, 'D')]),
+    ("timedelta", [timedelta(1), np.nan, timedelta(2)]),
+    ("time", [time(1), np.nan, time(2)]),
+    ("period", [Period(2013), pd.NaT, Period(2018)]),
+    ("interval", [Interval(0, 1), np.nan, Interval(0, 2)]),
+]
+ids, _ = zip(*_any_skipna_inferred_dtype)  # use inferred type as fixture-id
+
+
+@pytest.fixture(params=_any_skipna_inferred_dtype, ids=ids)
+def any_skipna_inferred_dtype(request):
+    """
+    Fixture for all inferred dtypes from _libs.lib.infer_dtype
+
+    The covered (inferred) types are:
+    * 'string'
+    * 'empty'
+    * 'bytes'
+    * 'mixed'
+    * 'mixed-integer'
+    * 'mixed-integer-float'
+    * 'floating'
+    * 'integer'
+    * 'decimal'
+    * 'boolean'
+    * 'datetime64'
+    * 'datetime'
+    * 'date'
+    * 'timedelta'
+    * 'time'
+    * 'period'
+    * 'interval'
+
+    Returns
+    -------
+    inferred_dtype : str
+        The string for the inferred dtype from _libs.lib.infer_dtype
+    values : np.ndarray
+        An array of object dtype that will be inferred to have
+        `inferred_dtype`
+
+    Examples
+    --------
+    >>> from pandas._libs import lib
+    >>>
+    >>> def test_something(any_skipna_inferred_dtype):
+    ...     inferred_dtype, values = any_skipna_inferred_dtype
+    ...     # will pass
+    ...     assert lib.infer_dtype(values, skipna=True) == inferred_dtype
+    """
+    inferred_dtype, values = request.param
+    values = np.array(values, dtype=object)  # object dtype to avoid casting
+
+    # correctness of inference tested in tests/dtypes/test_inference.py
+    return inferred_dtype, values
+
+
+# ----------------------------------------------------------------
+# Misc
+# ----------------------------------------------------------------
+@pytest.fixture
+def ip():
+    """
+    Get an instance of IPython.InteractiveShell.
+
+    Will raise a skip if IPython is not installed.
+    """
+    pytest.importorskip("IPython", minversion="6.0.0")
+    from IPython.core.interactiveshell import InteractiveShell
+
+    # GH#35711 make sure sqlite history file handle is not leaked
+    from traitlets.config import Config  # isort:skip
+
+    c = Config()
+    c.HistoryManager.hist_file = ":memory:"
+
+    return InteractiveShell(config=c)
+
+
+@pytest.fixture(params=["bsr", "coo", "csc", "csr", "dia", "dok", "lil"])
+def spmatrix(request):
+    """
+    Yields scipy sparse matrix classes.
+    """
+    sparse = pytest.importorskip("scipy.sparse")
+
+    return getattr(sparse, request.param + "_matrix")
+
+
+@pytest.fixture(
+    params=[
+        getattr(pd.offsets, o)
+        for o in pd.offsets.__all__
+        if issubclass(getattr(pd.offsets, o), pd.offsets.Tick) and o != "Tick"
+    ]
+)
+def tick_classes(request):
+    """
+    Fixture for Tick based datetime offsets available for a time series.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[None, lambda x: x])
+def sort_by_key(request):
+    """
+    Simple fixture for testing keys in sorting methods.
+    Tests None (no key) and the identity key.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        ("foo", None, None),
+        ("Egon", "Venkman", None),
+        ("NCC1701D", "NCC1701D", "NCC1701D"),
+        # possibly-matching NAs
+        (np.nan, np.nan, np.nan),
+        (np.nan, pd.NaT, None),
+        (np.nan, pd.NA, None),
+        (pd.NA, pd.NA, pd.NA),
+    ]
+)
+def names(request) -> tuple[Hashable, Hashable, Hashable]:
+    """
+    A 3-tuple of names, the first two for operands, the last for a result.
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.setitem, tm.loc, tm.iloc])
+def indexer_sli(request):
+    """
+    Parametrize over __setitem__, loc.__setitem__, iloc.__setitem__
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.loc, tm.iloc])
+def indexer_li(request):
+    """
+    Parametrize over loc.__getitem__, iloc.__getitem__
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.setitem, tm.iloc])
+def indexer_si(request):
+    """
+    Parametrize over __setitem__, iloc.__setitem__
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.setitem, tm.loc])
+def indexer_sl(request):
+    """
+    Parametrize over __setitem__, loc.__setitem__
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.at, tm.loc])
+def indexer_al(request):
+    """
+    Parametrize over at.__setitem__, loc.__setitem__
+    """
+    return request.param
+
+
+@pytest.fixture(params=[tm.iat, tm.iloc])
+def indexer_ial(request):
+    """
+    Parametrize over iat.__setitem__, iloc.__setitem__
+    """
+    return request.param
+
+
+@pytest.fixture
+def using_array_manager() -> bool:
+    """
+    Fixture to check if the array manager is being used.
+    """
+    return _get_option("mode.data_manager", silent=True) == "array"
+
+
+@pytest.fixture
+def using_copy_on_write() -> bool:
+    """
+    Fixture to check if Copy-on-Write is enabled.
+    """
+    return (
+        pd.options.mode.copy_on_write is True
+        and _get_option("mode.data_manager", silent=True) == "block"
+    )
+
+
+@pytest.fixture
+def warn_copy_on_write() -> bool:
+    """
+    Fixture to check if Copy-on-Write is in warning mode.
+    """
+    return (
+        pd.options.mode.copy_on_write == "warn"
+        and _get_option("mode.data_manager", silent=True) == "block"
+    )
+
+
+@pytest.fixture
+def using_infer_string() -> bool:
+    """
+    Fixture to check if infer string option is enabled.
+    """
+    return pd.options.future.infer_string is True
+
+
+warsaws = ["Europe/Warsaw", "dateutil/Europe/Warsaw"]
+if zoneinfo is not None:
+    warsaws.append(zoneinfo.ZoneInfo("Europe/Warsaw"))  # type: ignore[arg-type]
+
+
+@pytest.fixture(params=warsaws)
+def warsaw(request) -> str:
+    """
+    tzinfo for Europe/Warsaw using pytz, dateutil, or zoneinfo.
+    """
+    return request.param
+
+
+@pytest.fixture()
+def arrow_string_storage():
+    return ("pyarrow", "pyarrow_numpy")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/executor.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/executor.py
new file mode 100644
index 0000000000000000000000000000000000000000..0a26acb7df60a20a253ca3b864568c984bb86e3d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/executor.py
@@ -0,0 +1,239 @@
+from __future__ import annotations
+
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import Scalar
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+
+
+@functools.cache
+def generate_apply_looper(func, nopython=True, nogil=True, parallel=False):
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+    nb_compat_func = numba.extending.register_jitable(func)
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def nb_looper(values, axis):
+        # Operate on the first row/col in order to get
+        # the output shape
+        if axis == 0:
+            first_elem = values[:, 0]
+            dim0 = values.shape[1]
+        else:
+            first_elem = values[0]
+            dim0 = values.shape[0]
+        res0 = nb_compat_func(first_elem)
+        # Use np.asarray to get shape for
+        # https://github.com/numba/numba/issues/4202#issuecomment-1185981507
+        buf_shape = (dim0,) + np.atleast_1d(np.asarray(res0)).shape
+        if axis == 0:
+            buf_shape = buf_shape[::-1]
+        buff = np.empty(buf_shape)
+
+        if axis == 1:
+            buff[0] = res0
+            for i in numba.prange(1, values.shape[0]):
+                buff[i] = nb_compat_func(values[i])
+        else:
+            buff[:, 0] = res0
+            for j in numba.prange(1, values.shape[1]):
+                buff[:, j] = nb_compat_func(values[:, j])
+        return buff
+
+    return nb_looper
+
+
+@functools.cache
+def make_looper(func, result_dtype, is_grouped_kernel, nopython, nogil, parallel):
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    if is_grouped_kernel:
+
+        @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+        def column_looper(
+            values: np.ndarray,
+            labels: np.ndarray,
+            ngroups: int,
+            min_periods: int,
+            *args,
+        ):
+            result = np.empty((values.shape[0], ngroups), dtype=result_dtype)
+            na_positions = {}
+            for i in numba.prange(values.shape[0]):
+                output, na_pos = func(
+                    values[i], result_dtype, labels, ngroups, min_periods, *args
+                )
+                result[i] = output
+                if len(na_pos) > 0:
+                    na_positions[i] = np.array(na_pos)
+            return result, na_positions
+
+    else:
+
+        @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+        def column_looper(
+            values: np.ndarray,
+            start: np.ndarray,
+            end: np.ndarray,
+            min_periods: int,
+            *args,
+        ):
+            result = np.empty((values.shape[0], len(start)), dtype=result_dtype)
+            na_positions = {}
+            for i in numba.prange(values.shape[0]):
+                output, na_pos = func(
+                    values[i], result_dtype, start, end, min_periods, *args
+                )
+                result[i] = output
+                if len(na_pos) > 0:
+                    na_positions[i] = np.array(na_pos)
+            return result, na_positions
+
+    return column_looper
+
+
+default_dtype_mapping: dict[np.dtype, Any] = {
+    np.dtype("int8"): np.int64,
+    np.dtype("int16"): np.int64,
+    np.dtype("int32"): np.int64,
+    np.dtype("int64"): np.int64,
+    np.dtype("uint8"): np.uint64,
+    np.dtype("uint16"): np.uint64,
+    np.dtype("uint32"): np.uint64,
+    np.dtype("uint64"): np.uint64,
+    np.dtype("float32"): np.float64,
+    np.dtype("float64"): np.float64,
+    np.dtype("complex64"): np.complex128,
+    np.dtype("complex128"): np.complex128,
+}
+
+
+# TODO: Preserve complex dtypes
+
+float_dtype_mapping: dict[np.dtype, Any] = {
+    np.dtype("int8"): np.float64,
+    np.dtype("int16"): np.float64,
+    np.dtype("int32"): np.float64,
+    np.dtype("int64"): np.float64,
+    np.dtype("uint8"): np.float64,
+    np.dtype("uint16"): np.float64,
+    np.dtype("uint32"): np.float64,
+    np.dtype("uint64"): np.float64,
+    np.dtype("float32"): np.float64,
+    np.dtype("float64"): np.float64,
+    np.dtype("complex64"): np.float64,
+    np.dtype("complex128"): np.float64,
+}
+
+identity_dtype_mapping: dict[np.dtype, Any] = {
+    np.dtype("int8"): np.int8,
+    np.dtype("int16"): np.int16,
+    np.dtype("int32"): np.int32,
+    np.dtype("int64"): np.int64,
+    np.dtype("uint8"): np.uint8,
+    np.dtype("uint16"): np.uint16,
+    np.dtype("uint32"): np.uint32,
+    np.dtype("uint64"): np.uint64,
+    np.dtype("float32"): np.float32,
+    np.dtype("float64"): np.float64,
+    np.dtype("complex64"): np.complex64,
+    np.dtype("complex128"): np.complex128,
+}
+
+
+def generate_shared_aggregator(
+    func: Callable[..., Scalar],
+    dtype_mapping: dict[np.dtype, np.dtype],
+    is_grouped_kernel: bool,
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+):
+    """
+    Generate a Numba function that loops over the columns 2D object and applies
+    a 1D numba kernel over each column.
+
+    Parameters
+    ----------
+    func : function
+        aggregation function to be applied to each column
+    dtype_mapping: dict or None
+        If not None, maps a dtype to a result dtype.
+        Otherwise, will fall back to default mapping.
+    is_grouped_kernel: bool, default False
+        Whether func operates using the group labels (True)
+        or using starts/ends arrays
+
+        If true, you also need to pass the number of groups to this function
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+
+    # A wrapper around the looper function,
+    # to dispatch based on dtype since numba is unable to do that in nopython mode
+
+    # It also post-processes the values by inserting nans where number of observations
+    # is less than min_periods
+    # Cannot do this in numba nopython mode
+    # (you'll run into type-unification error when you cast int -> float)
+    def looper_wrapper(
+        values,
+        start=None,
+        end=None,
+        labels=None,
+        ngroups=None,
+        min_periods: int = 0,
+        **kwargs,
+    ):
+        result_dtype = dtype_mapping[values.dtype]
+        column_looper = make_looper(
+            func, result_dtype, is_grouped_kernel, nopython, nogil, parallel
+        )
+        # Need to unpack kwargs since numba only supports *args
+        if is_grouped_kernel:
+            result, na_positions = column_looper(
+                values, labels, ngroups, min_periods, *kwargs.values()
+            )
+        else:
+            result, na_positions = column_looper(
+                values, start, end, min_periods, *kwargs.values()
+            )
+        if result.dtype.kind == "i":
+            # Look if na_positions is not empty
+            # If so, convert the whole block
+            # This is OK since int dtype cannot hold nan,
+            # so if min_periods not satisfied for 1 col, it is not satisfied for
+            # all columns at that index
+            for na_pos in na_positions.values():
+                if len(na_pos) > 0:
+                    result = result.astype("float64")
+                    break
+        # TODO: Optimize this
+        for i, na_pos in na_positions.items():
+            if len(na_pos) > 0:
+                result[i, na_pos] = np.nan
+        return result
+
+    return looper_wrapper
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/extensions.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/extensions.py
new file mode 100644
index 0000000000000000000000000000000000000000..b05f12295a729176aadae19bb1d17f3191f98806
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/extensions.py
@@ -0,0 +1,585 @@
+# Disable type checking for this module since numba's internals
+# are not typed, and we use numba's internals via its extension API
+# mypy: ignore-errors
+"""
+Utility classes/functions to let numba recognize
+pandas Index/Series/DataFrame
+
+Mostly vendored from https://github.com/numba/numba/blob/main/numba/tests/pdlike_usecase.py
+"""
+
+from __future__ import annotations
+
+from contextlib import contextmanager
+import operator
+
+import numba
+from numba import types
+from numba.core import cgutils
+from numba.core.datamodel import models
+from numba.core.extending import (
+    NativeValue,
+    box,
+    lower_builtin,
+    make_attribute_wrapper,
+    overload,
+    overload_attribute,
+    overload_method,
+    register_model,
+    type_callable,
+    typeof_impl,
+    unbox,
+)
+from numba.core.imputils import impl_ret_borrowed
+import numpy as np
+
+from pandas._libs import lib
+
+from pandas.core.indexes.base import Index
+from pandas.core.indexing import _iLocIndexer
+from pandas.core.internals import SingleBlockManager
+from pandas.core.series import Series
+
+
+# Helper function to hack around fact that Index casts numpy string dtype to object
+#
+# Idea is to set an attribute on a Index called _numba_data
+# that is the original data, or the object data casted to numpy string dtype,
+# with a context manager that is unset afterwards
+@contextmanager
+def set_numba_data(index: Index):
+    numba_data = index._data
+    if numba_data.dtype in (object, "string"):
+        numba_data = np.asarray(numba_data)
+        if not lib.is_string_array(numba_data):
+            raise ValueError(
+                "The numba engine only supports using string or numeric column names"
+            )
+        numba_data = numba_data.astype("U")
+    try:
+        index._numba_data = numba_data
+        yield index
+    finally:
+        del index._numba_data
+
+
+# TODO: Range index support
+# (this currently lowers OK, but does not round-trip)
+class IndexType(types.Type):
+    """
+    The type class for Index objects.
+    """
+
+    def __init__(self, dtype, layout, pyclass: any) -> None:
+        self.pyclass = pyclass
+        name = f"index({dtype}, {layout})"
+        self.dtype = dtype
+        self.layout = layout
+        super().__init__(name)
+
+    @property
+    def key(self):
+        return self.pyclass, self.dtype, self.layout
+
+    @property
+    def as_array(self):
+        return types.Array(self.dtype, 1, self.layout)
+
+    def copy(self, dtype=None, ndim: int = 1, layout=None):
+        assert ndim == 1
+        if dtype is None:
+            dtype = self.dtype
+        layout = layout or self.layout
+        return type(self)(dtype, layout, self.pyclass)
+
+
+class SeriesType(types.Type):
+    """
+    The type class for Series objects.
+    """
+
+    def __init__(self, dtype, index, namety) -> None:
+        assert isinstance(index, IndexType)
+        self.dtype = dtype
+        self.index = index
+        self.values = types.Array(self.dtype, 1, "C")
+        self.namety = namety
+        name = f"series({dtype}, {index}, {namety})"
+        super().__init__(name)
+
+    @property
+    def key(self):
+        return self.dtype, self.index, self.namety
+
+    @property
+    def as_array(self):
+        return self.values
+
+    def copy(self, dtype=None, ndim: int = 1, layout: str = "C"):
+        assert ndim == 1
+        assert layout == "C"
+        if dtype is None:
+            dtype = self.dtype
+        return type(self)(dtype, self.index, self.namety)
+
+
+@typeof_impl.register(Index)
+def typeof_index(val, c):
+    """
+    This will assume that only strings are in object dtype
+    index.
+    (you should check this before this gets lowered down to numba)
+    """
+    # arrty = typeof_impl(val._data, c)
+    arrty = typeof_impl(val._numba_data, c)
+    assert arrty.ndim == 1
+    return IndexType(arrty.dtype, arrty.layout, type(val))
+
+
+@typeof_impl.register(Series)
+def typeof_series(val, c):
+    index = typeof_impl(val.index, c)
+    arrty = typeof_impl(val.values, c)
+    namety = typeof_impl(val.name, c)
+    assert arrty.ndim == 1
+    assert arrty.layout == "C"
+    return SeriesType(arrty.dtype, index, namety)
+
+
+@type_callable(Series)
+def type_series_constructor(context):
+    def typer(data, index, name=None):
+        if isinstance(index, IndexType) and isinstance(data, types.Array):
+            assert data.ndim == 1
+            if name is None:
+                name = types.intp
+            return SeriesType(data.dtype, index, name)
+
+    return typer
+
+
+@type_callable(Index)
+def type_index_constructor(context):
+    def typer(data, hashmap=None):
+        if isinstance(data, types.Array):
+            assert data.layout == "C"
+            assert data.ndim == 1
+            assert hashmap is None or isinstance(hashmap, types.DictType)
+            return IndexType(data.dtype, layout=data.layout, pyclass=Index)
+
+    return typer
+
+
+# Backend extensions for Index and Series and Frame
+@register_model(IndexType)
+class IndexModel(models.StructModel):
+    def __init__(self, dmm, fe_type) -> None:
+        # We don't want the numpy string scalar type in our hashmap
+        members = [
+            ("data", fe_type.as_array),
+            # This is an attempt to emulate our hashtable code with a numba
+            # typed dict
+            # It maps from values in the index to their integer positions in the array
+            ("hashmap", types.DictType(fe_type.dtype, types.intp)),
+            # Pointer to the Index object this was created from, or that it
+            # boxes to
+            # https://numba.discourse.group/t/qst-how-to-cache-the-boxing-of-an-object/2128/2?u=lithomas1
+            ("parent", types.pyobject),
+        ]
+        models.StructModel.__init__(self, dmm, fe_type, members)
+
+
+@register_model(SeriesType)
+class SeriesModel(models.StructModel):
+    def __init__(self, dmm, fe_type) -> None:
+        members = [
+            ("index", fe_type.index),
+            ("values", fe_type.as_array),
+            ("name", fe_type.namety),
+        ]
+        models.StructModel.__init__(self, dmm, fe_type, members)
+
+
+make_attribute_wrapper(IndexType, "data", "_data")
+make_attribute_wrapper(IndexType, "hashmap", "hashmap")
+
+make_attribute_wrapper(SeriesType, "index", "index")
+make_attribute_wrapper(SeriesType, "values", "values")
+make_attribute_wrapper(SeriesType, "name", "name")
+
+
+@lower_builtin(Series, types.Array, IndexType)
+def pdseries_constructor(context, builder, sig, args):
+    data, index = args
+    series = cgutils.create_struct_proxy(sig.return_type)(context, builder)
+    series.index = index
+    series.values = data
+    series.name = context.get_constant(types.intp, 0)
+    return impl_ret_borrowed(context, builder, sig.return_type, series._getvalue())
+
+
+@lower_builtin(Series, types.Array, IndexType, types.intp)
+@lower_builtin(Series, types.Array, IndexType, types.float64)
+@lower_builtin(Series, types.Array, IndexType, types.unicode_type)
+def pdseries_constructor_with_name(context, builder, sig, args):
+    data, index, name = args
+    series = cgutils.create_struct_proxy(sig.return_type)(context, builder)
+    series.index = index
+    series.values = data
+    series.name = name
+    return impl_ret_borrowed(context, builder, sig.return_type, series._getvalue())
+
+
+@lower_builtin(Index, types.Array, types.DictType, types.pyobject)
+def index_constructor_2arg(context, builder, sig, args):
+    (data, hashmap, parent) = args
+    index = cgutils.create_struct_proxy(sig.return_type)(context, builder)
+
+    index.data = data
+    index.hashmap = hashmap
+    index.parent = parent
+    return impl_ret_borrowed(context, builder, sig.return_type, index._getvalue())
+
+
+@lower_builtin(Index, types.Array, types.DictType)
+def index_constructor_2arg_parent(context, builder, sig, args):
+    # Basically same as index_constructor_1arg, but also lets you specify the
+    # parent object
+    (data, hashmap) = args
+    index = cgutils.create_struct_proxy(sig.return_type)(context, builder)
+
+    index.data = data
+    index.hashmap = hashmap
+    return impl_ret_borrowed(context, builder, sig.return_type, index._getvalue())
+
+
+@lower_builtin(Index, types.Array)
+def index_constructor_1arg(context, builder, sig, args):
+    from numba.typed import Dict
+
+    key_type = sig.return_type.dtype
+    value_type = types.intp
+
+    def index_impl(data):
+        return Index(data, Dict.empty(key_type, value_type))
+
+    return context.compile_internal(builder, index_impl, sig, args)
+
+
+# Helper to convert the unicodecharseq (numpy string scalar) into a unicode_type
+# (regular string)
+def maybe_cast_str(x):
+    # Dummy function that numba can overload
+    pass
+
+
+@overload(maybe_cast_str)
+def maybe_cast_str_impl(x):
+    """Converts numba UnicodeCharSeq (numpy string scalar) -> unicode type (string).
+    Is a no-op for other types."""
+    if isinstance(x, types.UnicodeCharSeq):
+        return lambda x: str(x)
+    else:
+        return lambda x: x
+
+
+@unbox(IndexType)
+def unbox_index(typ, obj, c):
+    """
+    Convert a Index object to a native structure.
+
+    Note: Object dtype is not allowed here
+    """
+    data_obj = c.pyapi.object_getattr_string(obj, "_numba_data")
+    index = cgutils.create_struct_proxy(typ)(c.context, c.builder)
+    # If we see an object array, assume its been validated as only containing strings
+    # We still need to do the conversion though
+    index.data = c.unbox(typ.as_array, data_obj).value
+    typed_dict_obj = c.pyapi.unserialize(c.pyapi.serialize_object(numba.typed.Dict))
+    # Create an empty typed dict in numba for the hashmap for indexing
+    # equiv of numba.typed.Dict.empty(typ.dtype, types.intp)
+    arr_type_obj = c.pyapi.unserialize(c.pyapi.serialize_object(typ.dtype))
+    intp_type_obj = c.pyapi.unserialize(c.pyapi.serialize_object(types.intp))
+    hashmap_obj = c.pyapi.call_method(
+        typed_dict_obj, "empty", (arr_type_obj, intp_type_obj)
+    )
+    index.hashmap = c.unbox(types.DictType(typ.dtype, types.intp), hashmap_obj).value
+    # Set the parent for speedy boxing.
+    index.parent = obj
+
+    # Decrefs
+    c.pyapi.decref(data_obj)
+    c.pyapi.decref(arr_type_obj)
+    c.pyapi.decref(intp_type_obj)
+    c.pyapi.decref(typed_dict_obj)
+
+    return NativeValue(index._getvalue())
+
+
+@unbox(SeriesType)
+def unbox_series(typ, obj, c):
+    """
+    Convert a Series object to a native structure.
+    """
+    index_obj = c.pyapi.object_getattr_string(obj, "index")
+    values_obj = c.pyapi.object_getattr_string(obj, "values")
+    name_obj = c.pyapi.object_getattr_string(obj, "name")
+
+    series = cgutils.create_struct_proxy(typ)(c.context, c.builder)
+    series.index = c.unbox(typ.index, index_obj).value
+    series.values = c.unbox(typ.values, values_obj).value
+    series.name = c.unbox(typ.namety, name_obj).value
+
+    # Decrefs
+    c.pyapi.decref(index_obj)
+    c.pyapi.decref(values_obj)
+    c.pyapi.decref(name_obj)
+
+    return NativeValue(series._getvalue())
+
+
+@box(IndexType)
+def box_index(typ, val, c):
+    """
+    Convert a native index structure to a Index object.
+
+    If our native index is of a numpy string dtype, we'll cast it to
+    object.
+    """
+    # First build a Numpy array object, then wrap it in a Index
+    index = cgutils.create_struct_proxy(typ)(c.context, c.builder, value=val)
+
+    res = cgutils.alloca_once_value(c.builder, index.parent)
+
+    # Does parent exist?
+    # (it means already boxed once, or Index same as original df.index or df.columns)
+    # xref https://github.com/numba/numba/blob/596e8a55334cc46854e3192766e643767bd7c934/numba/core/boxing.py#L593C17-L593C17
+    with c.builder.if_else(cgutils.is_not_null(c.builder, index.parent)) as (
+        has_parent,
+        otherwise,
+    ):
+        with has_parent:
+            c.pyapi.incref(index.parent)
+        with otherwise:
+            # TODO: preserve the original class for the index
+            # Also need preserve the name of the Index
+            # class_obj = c.pyapi.unserialize(c.pyapi.serialize_object(typ.pyclass))
+            class_obj = c.pyapi.unserialize(c.pyapi.serialize_object(Index))
+            array_obj = c.box(typ.as_array, index.data)
+            if isinstance(typ.dtype, types.UnicodeCharSeq):
+                # We converted to numpy string dtype, convert back
+                # to object since _simple_new won't do that for uss
+                object_str_obj = c.pyapi.unserialize(c.pyapi.serialize_object("object"))
+                array_obj = c.pyapi.call_method(array_obj, "astype", (object_str_obj,))
+                c.pyapi.decref(object_str_obj)
+            # this is basically Index._simple_new(array_obj, name_obj) in python
+            index_obj = c.pyapi.call_method(class_obj, "_simple_new", (array_obj,))
+            index.parent = index_obj
+            c.builder.store(index_obj, res)
+
+            # Decrefs
+            c.pyapi.decref(class_obj)
+            c.pyapi.decref(array_obj)
+    return c.builder.load(res)
+
+
+@box(SeriesType)
+def box_series(typ, val, c):
+    """
+    Convert a native series structure to a Series object.
+    """
+    series = cgutils.create_struct_proxy(typ)(c.context, c.builder, value=val)
+    series_const_obj = c.pyapi.unserialize(c.pyapi.serialize_object(Series._from_mgr))
+    mgr_const_obj = c.pyapi.unserialize(
+        c.pyapi.serialize_object(SingleBlockManager.from_array)
+    )
+    index_obj = c.box(typ.index, series.index)
+    array_obj = c.box(typ.as_array, series.values)
+    name_obj = c.box(typ.namety, series.name)
+    # This is basically equivalent of
+    # pd.Series(data=array_obj, index=index_obj)
+    # To improve perf, we will construct the Series from a manager
+    # object to avoid checks.
+    # We'll also set the name attribute manually to avoid validation
+    mgr_obj = c.pyapi.call_function_objargs(
+        mgr_const_obj,
+        (
+            array_obj,
+            index_obj,
+        ),
+    )
+    mgr_axes_obj = c.pyapi.object_getattr_string(mgr_obj, "axes")
+    # Series._constructor_from_mgr(mgr, axes)
+    series_obj = c.pyapi.call_function_objargs(
+        series_const_obj, (mgr_obj, mgr_axes_obj)
+    )
+    c.pyapi.object_setattr_string(series_obj, "_name", name_obj)
+
+    # Decrefs
+    c.pyapi.decref(series_const_obj)
+    c.pyapi.decref(mgr_axes_obj)
+    c.pyapi.decref(mgr_obj)
+    c.pyapi.decref(mgr_const_obj)
+    c.pyapi.decref(index_obj)
+    c.pyapi.decref(array_obj)
+    c.pyapi.decref(name_obj)
+
+    return series_obj
+
+
+# Add common series reductions (e.g. mean, sum),
+# and also add common binops (e.g. add, sub, mul, div)
+def generate_series_reduction(ser_reduction, ser_method):
+    @overload_method(SeriesType, ser_reduction)
+    def series_reduction(series):
+        def series_reduction_impl(series):
+            return ser_method(series.values)
+
+        return series_reduction_impl
+
+    return series_reduction
+
+
+def generate_series_binop(binop):
+    @overload(binop)
+    def series_binop(series1, value):
+        if isinstance(series1, SeriesType):
+            if isinstance(value, SeriesType):
+
+                def series_binop_impl(series1, series2):
+                    # TODO: Check index matching?
+                    return Series(
+                        binop(series1.values, series2.values),
+                        series1.index,
+                        series1.name,
+                    )
+
+                return series_binop_impl
+            else:
+
+                def series_binop_impl(series1, value):
+                    return Series(
+                        binop(series1.values, value), series1.index, series1.name
+                    )
+
+                return series_binop_impl
+
+    return series_binop
+
+
+series_reductions = [
+    ("sum", np.sum),
+    ("mean", np.mean),
+    # Disabled due to discrepancies between numba std. dev
+    # and pandas std. dev (no way to specify dof)
+    # ("std", np.std),
+    # ("var", np.var),
+    ("min", np.min),
+    ("max", np.max),
+]
+for reduction, reduction_method in series_reductions:
+    generate_series_reduction(reduction, reduction_method)
+
+series_binops = [operator.add, operator.sub, operator.mul, operator.truediv]
+
+for ser_binop in series_binops:
+    generate_series_binop(ser_binop)
+
+
+# get_loc on Index
+@overload_method(IndexType, "get_loc")
+def index_get_loc(index, item):
+    def index_get_loc_impl(index, item):
+        # Initialize the hash table if not initialized
+        if len(index.hashmap) == 0:
+            for i, val in enumerate(index._data):
+                index.hashmap[val] = i
+        return index.hashmap[item]
+
+    return index_get_loc_impl
+
+
+# Indexing for Series/Index
+@overload(operator.getitem)
+def series_indexing(series, item):
+    if isinstance(series, SeriesType):
+
+        def series_getitem(series, item):
+            loc = series.index.get_loc(item)
+            return series.iloc[loc]
+
+        return series_getitem
+
+
+@overload(operator.getitem)
+def index_indexing(index, idx):
+    if isinstance(index, IndexType):
+
+        def index_getitem(index, idx):
+            return index._data[idx]
+
+        return index_getitem
+
+
+class IlocType(types.Type):
+    def __init__(self, obj_type) -> None:
+        self.obj_type = obj_type
+        name = f"iLocIndexer({obj_type})"
+        super().__init__(name=name)
+
+    @property
+    def key(self):
+        return self.obj_type
+
+
+@typeof_impl.register(_iLocIndexer)
+def typeof_iloc(val, c):
+    objtype = typeof_impl(val.obj, c)
+    return IlocType(objtype)
+
+
+@type_callable(_iLocIndexer)
+def type_iloc_constructor(context):
+    def typer(obj):
+        if isinstance(obj, SeriesType):
+            return IlocType(obj)
+
+    return typer
+
+
+@lower_builtin(_iLocIndexer, SeriesType)
+def iloc_constructor(context, builder, sig, args):
+    (obj,) = args
+    iloc_indexer = cgutils.create_struct_proxy(sig.return_type)(context, builder)
+    iloc_indexer.obj = obj
+    return impl_ret_borrowed(
+        context, builder, sig.return_type, iloc_indexer._getvalue()
+    )
+
+
+@register_model(IlocType)
+class ILocModel(models.StructModel):
+    def __init__(self, dmm, fe_type) -> None:
+        members = [("obj", fe_type.obj_type)]
+        models.StructModel.__init__(self, dmm, fe_type, members)
+
+
+make_attribute_wrapper(IlocType, "obj", "obj")
+
+
+@overload_attribute(SeriesType, "iloc")
+def series_iloc(series):
+    def get(series):
+        return _iLocIndexer(series)
+
+    return get
+
+
+@overload(operator.getitem)
+def iloc_getitem(iloc_indexer, i):
+    if isinstance(iloc_indexer, IlocType):
+
+        def getitem_impl(iloc_indexer, i):
+            return iloc_indexer.obj.values[i]
+
+        return getitem_impl
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..1116c61c4ca8e48d94a6c9c6222aaf545d989e86
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/__init__.py
@@ -0,0 +1,27 @@
+from pandas.core._numba.kernels.mean_ import (
+    grouped_mean,
+    sliding_mean,
+)
+from pandas.core._numba.kernels.min_max_ import (
+    grouped_min_max,
+    sliding_min_max,
+)
+from pandas.core._numba.kernels.sum_ import (
+    grouped_sum,
+    sliding_sum,
+)
+from pandas.core._numba.kernels.var_ import (
+    grouped_var,
+    sliding_var,
+)
+
+__all__ = [
+    "sliding_mean",
+    "grouped_mean",
+    "sliding_sum",
+    "grouped_sum",
+    "sliding_var",
+    "grouped_var",
+    "sliding_min_max",
+    "grouped_min_max",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/mean_.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/mean_.py
new file mode 100644
index 0000000000000000000000000000000000000000..f415804781753372a5715b6ffee6a7ab8cc70b64
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/mean_.py
@@ -0,0 +1,196 @@
+"""
+Numba 1D mean kernels that can be shared by
+* Dataframe / Series
+* groupby
+* rolling / expanding
+
+Mirrors pandas/_libs/window/aggregation.pyx
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numba
+import numpy as np
+
+from pandas.core._numba.kernels.shared import is_monotonic_increasing
+from pandas.core._numba.kernels.sum_ import grouped_kahan_sum
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def add_mean(
+    val: float,
+    nobs: int,
+    sum_x: float,
+    neg_ct: int,
+    compensation: float,
+    num_consecutive_same_value: int,
+    prev_value: float,
+) -> tuple[int, float, int, float, int, float]:
+    if not np.isnan(val):
+        nobs += 1
+        y = val - compensation
+        t = sum_x + y
+        compensation = t - sum_x - y
+        sum_x = t
+        if val < 0:
+            neg_ct += 1
+
+        if val == prev_value:
+            num_consecutive_same_value += 1
+        else:
+            num_consecutive_same_value = 1
+        prev_value = val
+
+    return nobs, sum_x, neg_ct, compensation, num_consecutive_same_value, prev_value
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def remove_mean(
+    val: float, nobs: int, sum_x: float, neg_ct: int, compensation: float
+) -> tuple[int, float, int, float]:
+    if not np.isnan(val):
+        nobs -= 1
+        y = -val - compensation
+        t = sum_x + y
+        compensation = t - sum_x - y
+        sum_x = t
+        if val < 0:
+            neg_ct -= 1
+    return nobs, sum_x, neg_ct, compensation
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def sliding_mean(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    start: np.ndarray,
+    end: np.ndarray,
+    min_periods: int,
+) -> tuple[np.ndarray, list[int]]:
+    N = len(start)
+    nobs = 0
+    sum_x = 0.0
+    neg_ct = 0
+    compensation_add = 0.0
+    compensation_remove = 0.0
+
+    is_monotonic_increasing_bounds = is_monotonic_increasing(
+        start
+    ) and is_monotonic_increasing(end)
+
+    output = np.empty(N, dtype=result_dtype)
+
+    for i in range(N):
+        s = start[i]
+        e = end[i]
+        if i == 0 or not is_monotonic_increasing_bounds:
+            prev_value = values[s]
+            num_consecutive_same_value = 0
+
+            for j in range(s, e):
+                val = values[j]
+                (
+                    nobs,
+                    sum_x,
+                    neg_ct,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_mean(
+                    val,
+                    nobs,
+                    sum_x,
+                    neg_ct,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,  # pyright: ignore[reportGeneralTypeIssues]
+                )
+        else:
+            for j in range(start[i - 1], s):
+                val = values[j]
+                nobs, sum_x, neg_ct, compensation_remove = remove_mean(
+                    val, nobs, sum_x, neg_ct, compensation_remove
+                )
+
+            for j in range(end[i - 1], e):
+                val = values[j]
+                (
+                    nobs,
+                    sum_x,
+                    neg_ct,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_mean(
+                    val,
+                    nobs,
+                    sum_x,
+                    neg_ct,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,  # pyright: ignore[reportGeneralTypeIssues]
+                )
+
+        if nobs >= min_periods and nobs > 0:
+            result = sum_x / nobs
+            if num_consecutive_same_value >= nobs:
+                result = prev_value
+            elif neg_ct == 0 and result < 0:
+                result = 0
+            elif neg_ct == nobs and result > 0:
+                result = 0
+        else:
+            result = np.nan
+
+        output[i] = result
+
+        if not is_monotonic_increasing_bounds:
+            nobs = 0
+            sum_x = 0.0
+            neg_ct = 0
+            compensation_remove = 0.0
+
+    # na_position is empty list since float64 can already hold nans
+    # Do list comprehension, since numba cannot figure out that na_pos is
+    # empty list of ints on its own
+    na_pos = [0 for i in range(0)]
+    return output, na_pos
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def grouped_mean(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+    min_periods: int,
+) -> tuple[np.ndarray, list[int]]:
+    output, nobs_arr, comp_arr, consecutive_counts, prev_vals = grouped_kahan_sum(
+        values, result_dtype, labels, ngroups
+    )
+
+    # Post-processing, replace sums that don't satisfy min_periods
+    for lab in range(ngroups):
+        nobs = nobs_arr[lab]
+        num_consecutive_same_value = consecutive_counts[lab]
+        prev_value = prev_vals[lab]
+        sum_x = output[lab]
+        if nobs >= min_periods:
+            if num_consecutive_same_value >= nobs:
+                result = prev_value * nobs
+            else:
+                result = sum_x
+        else:
+            result = np.nan
+        result /= nobs
+        output[lab] = result
+
+    # na_position is empty list since float64 can already hold nans
+    # Do list comprehension, since numba cannot figure out that na_pos is
+    # empty list of ints on its own
+    na_pos = [0 for i in range(0)]
+    return output, na_pos
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/min_max_.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/min_max_.py
new file mode 100644
index 0000000000000000000000000000000000000000..c9803980e64a6bf2ec5b274acd582850e3a07420
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/min_max_.py
@@ -0,0 +1,125 @@
+"""
+Numba 1D min/max kernels that can be shared by
+* Dataframe / Series
+* groupby
+* rolling / expanding
+
+Mirrors pandas/_libs/window/aggregation.pyx
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numba
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def sliding_min_max(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    start: np.ndarray,
+    end: np.ndarray,
+    min_periods: int,
+    is_max: bool,
+) -> tuple[np.ndarray, list[int]]:
+    N = len(start)
+    nobs = 0
+    output = np.empty(N, dtype=result_dtype)
+    na_pos = []
+    # Use deque once numba supports it
+    # https://github.com/numba/numba/issues/7417
+    Q: list = []
+    W: list = []
+    for i in range(N):
+        curr_win_size = end[i] - start[i]
+        if i == 0:
+            st = start[i]
+        else:
+            st = end[i - 1]
+
+        for k in range(st, end[i]):
+            ai = values[k]
+            if not np.isnan(ai):
+                nobs += 1
+            elif is_max:
+                ai = -np.inf
+            else:
+                ai = np.inf
+            # Discard previous entries if we find new min or max
+            if is_max:
+                while Q and ((ai >= values[Q[-1]]) or values[Q[-1]] != values[Q[-1]]):
+                    Q.pop()
+            else:
+                while Q and ((ai <= values[Q[-1]]) or values[Q[-1]] != values[Q[-1]]):
+                    Q.pop()
+            Q.append(k)
+            W.append(k)
+
+        # Discard entries outside and left of current window
+        while Q and Q[0] <= start[i] - 1:
+            Q.pop(0)
+        while W and W[0] <= start[i] - 1:
+            if not np.isnan(values[W[0]]):
+                nobs -= 1
+            W.pop(0)
+
+        # Save output based on index in input value array
+        if Q and curr_win_size > 0 and nobs >= min_periods:
+            output[i] = values[Q[0]]
+        else:
+            if values.dtype.kind != "i":
+                output[i] = np.nan
+            else:
+                na_pos.append(i)
+
+    return output, na_pos
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def grouped_min_max(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+    min_periods: int,
+    is_max: bool,
+) -> tuple[np.ndarray, list[int]]:
+    N = len(labels)
+    nobs = np.zeros(ngroups, dtype=np.int64)
+    na_pos = []
+    output = np.empty(ngroups, dtype=result_dtype)
+
+    for i in range(N):
+        lab = labels[i]
+        val = values[i]
+        if lab < 0:
+            continue
+
+        if values.dtype.kind == "i" or not np.isnan(val):
+            nobs[lab] += 1
+        else:
+            # NaN value cannot be a min/max value
+            continue
+
+        if nobs[lab] == 1:
+            # First element in group, set output equal to this
+            output[lab] = val
+            continue
+
+        if is_max:
+            if val > output[lab]:
+                output[lab] = val
+        else:
+            if val < output[lab]:
+                output[lab] = val
+
+    # Set labels that don't satisfy min_periods as np.nan
+    for lab, count in enumerate(nobs):
+        if count < min_periods:
+            na_pos.append(lab)
+
+    return output, na_pos
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/shared.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/shared.py
new file mode 100644
index 0000000000000000000000000000000000000000..c52372fe6b08f3ec9ec6e836341e08ac804d50f3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/shared.py
@@ -0,0 +1,29 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numba
+
+if TYPE_CHECKING:
+    import numpy as np
+
+
+@numba.jit(
+    # error: Any? not callable
+    numba.boolean(numba.int64[:]),  # type: ignore[misc]
+    nopython=True,
+    nogil=True,
+    parallel=False,
+)
+def is_monotonic_increasing(bounds: np.ndarray) -> bool:
+    """Check if int64 values are monotonically increasing."""
+    n = len(bounds)
+    if n < 2:
+        return True
+    prev = bounds[0]
+    for i in range(1, n):
+        cur = bounds[i]
+        if cur < prev:
+            return False
+        prev = cur
+    return True
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/sum_.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/sum_.py
new file mode 100644
index 0000000000000000000000000000000000000000..94db84267ceecb83234fc2e0b231566a2fdffd66
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/sum_.py
@@ -0,0 +1,244 @@
+"""
+Numba 1D sum kernels that can be shared by
+* Dataframe / Series
+* groupby
+* rolling / expanding
+
+Mirrors pandas/_libs/window/aggregation.pyx
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numba
+from numba.extending import register_jitable
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+from pandas.core._numba.kernels.shared import is_monotonic_increasing
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def add_sum(
+    val: Any,
+    nobs: int,
+    sum_x: Any,
+    compensation: Any,
+    num_consecutive_same_value: int,
+    prev_value: Any,
+) -> tuple[int, Any, Any, int, Any]:
+    if not np.isnan(val):
+        nobs += 1
+        y = val - compensation
+        t = sum_x + y
+        compensation = t - sum_x - y
+        sum_x = t
+
+        if val == prev_value:
+            num_consecutive_same_value += 1
+        else:
+            num_consecutive_same_value = 1
+        prev_value = val
+
+    return nobs, sum_x, compensation, num_consecutive_same_value, prev_value
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def remove_sum(
+    val: Any, nobs: int, sum_x: Any, compensation: Any
+) -> tuple[int, Any, Any]:
+    if not np.isnan(val):
+        nobs -= 1
+        y = -val - compensation
+        t = sum_x + y
+        compensation = t - sum_x - y
+        sum_x = t
+    return nobs, sum_x, compensation
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def sliding_sum(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    start: np.ndarray,
+    end: np.ndarray,
+    min_periods: int,
+) -> tuple[np.ndarray, list[int]]:
+    dtype = values.dtype
+
+    na_val: object = np.nan
+    if dtype.kind == "i":
+        na_val = 0
+
+    N = len(start)
+    nobs = 0
+    sum_x = 0
+    compensation_add = 0
+    compensation_remove = 0
+    na_pos = []
+
+    is_monotonic_increasing_bounds = is_monotonic_increasing(
+        start
+    ) and is_monotonic_increasing(end)
+
+    output = np.empty(N, dtype=result_dtype)
+
+    for i in range(N):
+        s = start[i]
+        e = end[i]
+        if i == 0 or not is_monotonic_increasing_bounds:
+            prev_value = values[s]
+            num_consecutive_same_value = 0
+
+            for j in range(s, e):
+                val = values[j]
+                (
+                    nobs,
+                    sum_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_sum(
+                    val,
+                    nobs,
+                    sum_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                )
+        else:
+            for j in range(start[i - 1], s):
+                val = values[j]
+                nobs, sum_x, compensation_remove = remove_sum(
+                    val, nobs, sum_x, compensation_remove
+                )
+
+            for j in range(end[i - 1], e):
+                val = values[j]
+                (
+                    nobs,
+                    sum_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_sum(
+                    val,
+                    nobs,
+                    sum_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                )
+
+        if nobs == 0 == min_periods:
+            result: object = 0
+        elif nobs >= min_periods:
+            if num_consecutive_same_value >= nobs:
+                result = prev_value * nobs
+            else:
+                result = sum_x
+        else:
+            result = na_val
+            if dtype.kind == "i":
+                na_pos.append(i)
+
+        output[i] = result
+
+        if not is_monotonic_increasing_bounds:
+            nobs = 0
+            sum_x = 0
+            compensation_remove = 0
+
+    return output, na_pos
+
+
+# Mypy/pyright don't like the fact that the decorator is untyped
+@register_jitable  # type: ignore[misc]
+def grouped_kahan_sum(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+) -> tuple[
+    np.ndarray, npt.NDArray[np.int64], np.ndarray, npt.NDArray[np.int64], np.ndarray
+]:
+    N = len(labels)
+
+    nobs_arr = np.zeros(ngroups, dtype=np.int64)
+    comp_arr = np.zeros(ngroups, dtype=values.dtype)
+    consecutive_counts = np.zeros(ngroups, dtype=np.int64)
+    prev_vals = np.zeros(ngroups, dtype=values.dtype)
+    output = np.zeros(ngroups, dtype=result_dtype)
+
+    for i in range(N):
+        lab = labels[i]
+        val = values[i]
+
+        if lab < 0:
+            continue
+
+        sum_x = output[lab]
+        nobs = nobs_arr[lab]
+        compensation_add = comp_arr[lab]
+        num_consecutive_same_value = consecutive_counts[lab]
+        prev_value = prev_vals[lab]
+
+        (
+            nobs,
+            sum_x,
+            compensation_add,
+            num_consecutive_same_value,
+            prev_value,
+        ) = add_sum(
+            val,
+            nobs,
+            sum_x,
+            compensation_add,
+            num_consecutive_same_value,
+            prev_value,
+        )
+
+        output[lab] = sum_x
+        consecutive_counts[lab] = num_consecutive_same_value
+        prev_vals[lab] = prev_value
+        comp_arr[lab] = compensation_add
+        nobs_arr[lab] = nobs
+    return output, nobs_arr, comp_arr, consecutive_counts, prev_vals
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def grouped_sum(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+    min_periods: int,
+) -> tuple[np.ndarray, list[int]]:
+    na_pos = []
+
+    output, nobs_arr, comp_arr, consecutive_counts, prev_vals = grouped_kahan_sum(
+        values, result_dtype, labels, ngroups
+    )
+
+    # Post-processing, replace sums that don't satisfy min_periods
+    for lab in range(ngroups):
+        nobs = nobs_arr[lab]
+        num_consecutive_same_value = consecutive_counts[lab]
+        prev_value = prev_vals[lab]
+        sum_x = output[lab]
+        if nobs >= min_periods:
+            if num_consecutive_same_value >= nobs:
+                result = prev_value * nobs
+            else:
+                result = sum_x
+        else:
+            result = sum_x  # Don't change val, will be replaced by nan later
+            na_pos.append(lab)
+        output[lab] = result
+
+    return output, na_pos
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/var_.py b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/var_.py
new file mode 100644
index 0000000000000000000000000000000000000000..c63d0b90b0fc3f4a4a532b9ce85e57d8bd823fb1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/_numba/kernels/var_.py
@@ -0,0 +1,245 @@
+"""
+Numba 1D var kernels that can be shared by
+* Dataframe / Series
+* groupby
+* rolling / expanding
+
+Mirrors pandas/_libs/window/aggregation.pyx
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numba
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+from pandas.core._numba.kernels.shared import is_monotonic_increasing
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def add_var(
+    val: float,
+    nobs: int,
+    mean_x: float,
+    ssqdm_x: float,
+    compensation: float,
+    num_consecutive_same_value: int,
+    prev_value: float,
+) -> tuple[int, float, float, float, int, float]:
+    if not np.isnan(val):
+        if val == prev_value:
+            num_consecutive_same_value += 1
+        else:
+            num_consecutive_same_value = 1
+        prev_value = val
+
+        nobs += 1
+        prev_mean = mean_x - compensation
+        y = val - compensation
+        t = y - mean_x
+        compensation = t + mean_x - y
+        delta = t
+        if nobs:
+            mean_x += delta / nobs
+        else:
+            mean_x = 0
+        ssqdm_x += (val - prev_mean) * (val - mean_x)
+    return nobs, mean_x, ssqdm_x, compensation, num_consecutive_same_value, prev_value
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def remove_var(
+    val: float, nobs: int, mean_x: float, ssqdm_x: float, compensation: float
+) -> tuple[int, float, float, float]:
+    if not np.isnan(val):
+        nobs -= 1
+        if nobs:
+            prev_mean = mean_x - compensation
+            y = val - compensation
+            t = y - mean_x
+            compensation = t + mean_x - y
+            delta = t
+            mean_x -= delta / nobs
+            ssqdm_x -= (val - prev_mean) * (val - mean_x)
+        else:
+            mean_x = 0
+            ssqdm_x = 0
+    return nobs, mean_x, ssqdm_x, compensation
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def sliding_var(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    start: np.ndarray,
+    end: np.ndarray,
+    min_periods: int,
+    ddof: int = 1,
+) -> tuple[np.ndarray, list[int]]:
+    N = len(start)
+    nobs = 0
+    mean_x = 0.0
+    ssqdm_x = 0.0
+    compensation_add = 0.0
+    compensation_remove = 0.0
+
+    min_periods = max(min_periods, 1)
+    is_monotonic_increasing_bounds = is_monotonic_increasing(
+        start
+    ) and is_monotonic_increasing(end)
+
+    output = np.empty(N, dtype=result_dtype)
+
+    for i in range(N):
+        s = start[i]
+        e = end[i]
+        if i == 0 or not is_monotonic_increasing_bounds:
+            prev_value = values[s]
+            num_consecutive_same_value = 0
+
+            for j in range(s, e):
+                val = values[j]
+                (
+                    nobs,
+                    mean_x,
+                    ssqdm_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_var(
+                    val,
+                    nobs,
+                    mean_x,
+                    ssqdm_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                )
+        else:
+            for j in range(start[i - 1], s):
+                val = values[j]
+                nobs, mean_x, ssqdm_x, compensation_remove = remove_var(
+                    val, nobs, mean_x, ssqdm_x, compensation_remove
+                )
+
+            for j in range(end[i - 1], e):
+                val = values[j]
+                (
+                    nobs,
+                    mean_x,
+                    ssqdm_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                ) = add_var(
+                    val,
+                    nobs,
+                    mean_x,
+                    ssqdm_x,
+                    compensation_add,
+                    num_consecutive_same_value,
+                    prev_value,
+                )
+
+        if nobs >= min_periods and nobs > ddof:
+            if nobs == 1 or num_consecutive_same_value >= nobs:
+                result = 0.0
+            else:
+                result = ssqdm_x / (nobs - ddof)
+        else:
+            result = np.nan
+
+        output[i] = result
+
+        if not is_monotonic_increasing_bounds:
+            nobs = 0
+            mean_x = 0.0
+            ssqdm_x = 0.0
+            compensation_remove = 0.0
+
+    # na_position is empty list since float64 can already hold nans
+    # Do list comprehension, since numba cannot figure out that na_pos is
+    # empty list of ints on its own
+    na_pos = [0 for i in range(0)]
+    return output, na_pos
+
+
+@numba.jit(nopython=True, nogil=True, parallel=False)
+def grouped_var(
+    values: np.ndarray,
+    result_dtype: np.dtype,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+    min_periods: int,
+    ddof: int = 1,
+) -> tuple[np.ndarray, list[int]]:
+    N = len(labels)
+
+    nobs_arr = np.zeros(ngroups, dtype=np.int64)
+    comp_arr = np.zeros(ngroups, dtype=values.dtype)
+    consecutive_counts = np.zeros(ngroups, dtype=np.int64)
+    prev_vals = np.zeros(ngroups, dtype=values.dtype)
+    output = np.zeros(ngroups, dtype=result_dtype)
+    means = np.zeros(ngroups, dtype=result_dtype)
+
+    for i in range(N):
+        lab = labels[i]
+        val = values[i]
+
+        if lab < 0:
+            continue
+
+        mean_x = means[lab]
+        ssqdm_x = output[lab]
+        nobs = nobs_arr[lab]
+        compensation_add = comp_arr[lab]
+        num_consecutive_same_value = consecutive_counts[lab]
+        prev_value = prev_vals[lab]
+
+        (
+            nobs,
+            mean_x,
+            ssqdm_x,
+            compensation_add,
+            num_consecutive_same_value,
+            prev_value,
+        ) = add_var(
+            val,
+            nobs,
+            mean_x,
+            ssqdm_x,
+            compensation_add,
+            num_consecutive_same_value,
+            prev_value,
+        )
+
+        output[lab] = ssqdm_x
+        means[lab] = mean_x
+        consecutive_counts[lab] = num_consecutive_same_value
+        prev_vals[lab] = prev_value
+        comp_arr[lab] = compensation_add
+        nobs_arr[lab] = nobs
+
+    # Post-processing, replace vars that don't satisfy min_periods
+    for lab in range(ngroups):
+        nobs = nobs_arr[lab]
+        num_consecutive_same_value = consecutive_counts[lab]
+        ssqdm_x = output[lab]
+        if nobs >= min_periods and nobs > ddof:
+            if nobs == 1 or num_consecutive_same_value >= nobs:
+                result = 0.0
+            else:
+                result = ssqdm_x / (nobs - ddof)
+        else:
+            result = np.nan
+        output[lab] = result
+
+    # Second pass to get the std.dev
+    # na_position is empty list since float64 can already hold nans
+    # Do list comprehension, since numba cannot figure out that na_pos is
+    # empty list of ints on its own
+    na_pos = [0 for i in range(0)]
+    return output, na_pos
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/accessor.py b/.venv/lib/python3.13/site-packages/pandas/core/accessor.py
new file mode 100644
index 0000000000000000000000000000000000000000..698abb2ec4989b2f95f6b2c012f03873bba328cb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/accessor.py
@@ -0,0 +1,340 @@
+"""
+
+accessor.py contains base classes for implementing accessor properties
+that can be mixed into or pinned onto other pandas classes.
+
+"""
+from __future__ import annotations
+
+from typing import (
+    Callable,
+    final,
+)
+import warnings
+
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+
+class DirNamesMixin:
+    _accessors: set[str] = set()
+    _hidden_attrs: frozenset[str] = frozenset()
+
+    @final
+    def _dir_deletions(self) -> set[str]:
+        """
+        Delete unwanted __dir__ for this object.
+        """
+        return self._accessors | self._hidden_attrs
+
+    def _dir_additions(self) -> set[str]:
+        """
+        Add additional __dir__ for this object.
+        """
+        return {accessor for accessor in self._accessors if hasattr(self, accessor)}
+
+    def __dir__(self) -> list[str]:
+        """
+        Provide method name lookup and completion.
+
+        Notes
+        -----
+        Only provide 'public' methods.
+        """
+        rv = set(super().__dir__())
+        rv = (rv - self._dir_deletions()) | self._dir_additions()
+        return sorted(rv)
+
+
+class PandasDelegate:
+    """
+    Abstract base class for delegating methods/properties.
+    """
+
+    def _delegate_property_get(self, name: str, *args, **kwargs):
+        raise TypeError(f"You cannot access the property {name}")
+
+    def _delegate_property_set(self, name: str, value, *args, **kwargs):
+        raise TypeError(f"The property {name} cannot be set")
+
+    def _delegate_method(self, name: str, *args, **kwargs):
+        raise TypeError(f"You cannot call method {name}")
+
+    @classmethod
+    def _add_delegate_accessors(
+        cls,
+        delegate,
+        accessors: list[str],
+        typ: str,
+        overwrite: bool = False,
+        accessor_mapping: Callable[[str], str] = lambda x: x,
+        raise_on_missing: bool = True,
+    ) -> None:
+        """
+        Add accessors to cls from the delegate class.
+
+        Parameters
+        ----------
+        cls
+            Class to add the methods/properties to.
+        delegate
+            Class to get methods/properties and doc-strings.
+        accessors : list of str
+            List of accessors to add.
+        typ : {'property', 'method'}
+        overwrite : bool, default False
+            Overwrite the method/property in the target class if it exists.
+        accessor_mapping: Callable, default lambda x: x
+            Callable to map the delegate's function to the cls' function.
+        raise_on_missing: bool, default True
+            Raise if an accessor does not exist on delegate.
+            False skips the missing accessor.
+        """
+
+        def _create_delegator_property(name: str):
+            def _getter(self):
+                return self._delegate_property_get(name)
+
+            def _setter(self, new_values):
+                return self._delegate_property_set(name, new_values)
+
+            _getter.__name__ = name
+            _setter.__name__ = name
+
+            return property(
+                fget=_getter,
+                fset=_setter,
+                doc=getattr(delegate, accessor_mapping(name)).__doc__,
+            )
+
+        def _create_delegator_method(name: str):
+            def f(self, *args, **kwargs):
+                return self._delegate_method(name, *args, **kwargs)
+
+            f.__name__ = name
+            f.__doc__ = getattr(delegate, accessor_mapping(name)).__doc__
+
+            return f
+
+        for name in accessors:
+            if (
+                not raise_on_missing
+                and getattr(delegate, accessor_mapping(name), None) is None
+            ):
+                continue
+
+            if typ == "property":
+                f = _create_delegator_property(name)
+            else:
+                f = _create_delegator_method(name)
+
+            # don't overwrite existing methods/properties
+            if overwrite or not hasattr(cls, name):
+                setattr(cls, name, f)
+
+
+def delegate_names(
+    delegate,
+    accessors: list[str],
+    typ: str,
+    overwrite: bool = False,
+    accessor_mapping: Callable[[str], str] = lambda x: x,
+    raise_on_missing: bool = True,
+):
+    """
+    Add delegated names to a class using a class decorator.  This provides
+    an alternative usage to directly calling `_add_delegate_accessors`
+    below a class definition.
+
+    Parameters
+    ----------
+    delegate : object
+        The class to get methods/properties & doc-strings.
+    accessors : Sequence[str]
+        List of accessor to add.
+    typ : {'property', 'method'}
+    overwrite : bool, default False
+       Overwrite the method/property in the target class if it exists.
+    accessor_mapping: Callable, default lambda x: x
+        Callable to map the delegate's function to the cls' function.
+    raise_on_missing: bool, default True
+        Raise if an accessor does not exist on delegate.
+        False skips the missing accessor.
+
+    Returns
+    -------
+    callable
+        A class decorator.
+
+    Examples
+    --------
+    @delegate_names(Categorical, ["categories", "ordered"], "property")
+    class CategoricalAccessor(PandasDelegate):
+        [...]
+    """
+
+    def add_delegate_accessors(cls):
+        cls._add_delegate_accessors(
+            delegate,
+            accessors,
+            typ,
+            overwrite=overwrite,
+            accessor_mapping=accessor_mapping,
+            raise_on_missing=raise_on_missing,
+        )
+        return cls
+
+    return add_delegate_accessors
+
+
+# Ported with modifications from xarray; licence at LICENSES/XARRAY_LICENSE
+# https://github.com/pydata/xarray/blob/master/xarray/core/extensions.py
+# 1. We don't need to catch and re-raise AttributeErrors as RuntimeErrors
+# 2. We use a UserWarning instead of a custom Warning
+
+
+class CachedAccessor:
+    """
+    Custom property-like object.
+
+    A descriptor for caching accessors.
+
+    Parameters
+    ----------
+    name : str
+        Namespace that will be accessed under, e.g. ``df.foo``.
+    accessor : cls
+        Class with the extension methods.
+
+    Notes
+    -----
+    For accessor, The class's __init__ method assumes that one of
+    ``Series``, ``DataFrame`` or ``Index`` as the
+    single argument ``data``.
+    """
+
+    def __init__(self, name: str, accessor) -> None:
+        self._name = name
+        self._accessor = accessor
+
+    def __get__(self, obj, cls):
+        if obj is None:
+            # we're accessing the attribute of the class, i.e., Dataset.geo
+            return self._accessor
+        accessor_obj = self._accessor(obj)
+        # Replace the property with the accessor object. Inspired by:
+        # https://www.pydanny.com/cached-property.html
+        # We need to use object.__setattr__ because we overwrite __setattr__ on
+        # NDFrame
+        object.__setattr__(obj, self._name, accessor_obj)
+        return accessor_obj
+
+
+@doc(klass="", others="")
+def _register_accessor(name: str, cls):
+    """
+    Register a custom accessor on {klass} objects.
+
+    Parameters
+    ----------
+    name : str
+        Name under which the accessor should be registered. A warning is issued
+        if this name conflicts with a preexisting attribute.
+
+    Returns
+    -------
+    callable
+        A class decorator.
+
+    See Also
+    --------
+    register_dataframe_accessor : Register a custom accessor on DataFrame objects.
+    register_series_accessor : Register a custom accessor on Series objects.
+    register_index_accessor : Register a custom accessor on Index objects.
+
+    Notes
+    -----
+    When accessed, your accessor will be initialized with the pandas object
+    the user is interacting with. So the signature must be
+
+    .. code-block:: python
+
+        def __init__(self, pandas_object):  # noqa: E999
+            ...
+
+    For consistency with pandas methods, you should raise an ``AttributeError``
+    if the data passed to your accessor has an incorrect dtype.
+
+    >>> pd.Series(['a', 'b']).dt
+    Traceback (most recent call last):
+    ...
+    AttributeError: Can only use .dt accessor with datetimelike values
+
+    Examples
+    --------
+    In your library code::
+
+        import pandas as pd
+
+        @pd.api.extensions.register_dataframe_accessor("geo")
+        class GeoAccessor:
+            def __init__(self, pandas_obj):
+                self._obj = pandas_obj
+
+            @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
+
+    Back in an interactive IPython session:
+
+        .. code-block:: ipython
+
+            In [1]: ds = pd.DataFrame({{"longitude": np.linspace(0, 10),
+               ...:                    "latitude": np.linspace(0, 20)}})
+            In [2]: ds.geo.center
+            Out[2]: (5.0, 10.0)
+            In [3]: ds.geo.plot()  # plots data on a map
+    """
+
+    def decorator(accessor):
+        if hasattr(cls, name):
+            warnings.warn(
+                f"registration of accessor {repr(accessor)} under name "
+                f"{repr(name)} for type {repr(cls)} is overriding a preexisting "
+                f"attribute with the same name.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+        setattr(cls, name, CachedAccessor(name, accessor))
+        cls._accessors.add(name)
+        return accessor
+
+    return decorator
+
+
+@doc(_register_accessor, klass="DataFrame")
+def register_dataframe_accessor(name: str):
+    from pandas import DataFrame
+
+    return _register_accessor(name, DataFrame)
+
+
+@doc(_register_accessor, klass="Series")
+def register_series_accessor(name: str):
+    from pandas import Series
+
+    return _register_accessor(name, Series)
+
+
+@doc(_register_accessor, klass="Index")
+def register_index_accessor(name: str):
+    from pandas import Index
+
+    return _register_accessor(name, Index)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/algorithms.py b/.venv/lib/python3.13/site-packages/pandas/core/algorithms.py
new file mode 100644
index 0000000000000000000000000000000000000000..c6084880bea5d0b8771bf31be1f1e6f5fecdc094
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/algorithms.py
@@ -0,0 +1,1747 @@
+"""
+Generic data algorithms. This module is experimental at the moment and not
+intended for public consumption
+"""
+from __future__ import annotations
+
+import decimal
+import operator
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    algos,
+    hashtable as htable,
+    iNaT,
+    lib,
+)
+from pandas._typing import (
+    AnyArrayLike,
+    ArrayLike,
+    AxisInt,
+    DtypeObj,
+    TakeIndexer,
+    npt,
+)
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    construct_1d_object_array_from_listlike,
+    np_find_common_type,
+)
+from pandas.core.dtypes.common import (
+    ensure_float64,
+    ensure_object,
+    ensure_platform_int,
+    is_array_like,
+    is_bool_dtype,
+    is_complex_dtype,
+    is_dict_like,
+    is_extension_array_dtype,
+    is_float_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_object_dtype,
+    is_signed_integer_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import (
+    BaseMaskedDtype,
+    CategoricalDtype,
+    ExtensionDtype,
+    NumpyEADtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDatetimeArray,
+    ABCExtensionArray,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+    ABCTimedeltaArray,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+)
+
+from pandas.core.array_algos.take import take_nd
+from pandas.core.construction import (
+    array as pd_array,
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import validate_indices
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ListLike,
+        NumpySorter,
+        NumpyValueArrayLike,
+    )
+
+    from pandas import (
+        Categorical,
+        Index,
+        Series,
+    )
+    from pandas.core.arrays import (
+        BaseMaskedArray,
+        ExtensionArray,
+    )
+
+
+# --------------- #
+# dtype access    #
+# --------------- #
+def _ensure_data(values: ArrayLike) -> np.ndarray:
+    """
+    routine to ensure that our data is of the correct
+    input dtype for lower-level routines
+
+    This will coerce:
+    - ints -> int64
+    - uint -> uint64
+    - bool -> uint8
+    - datetimelike -> i8
+    - datetime64tz -> i8 (in local tz)
+    - categorical -> codes
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+
+    Returns
+    -------
+    np.ndarray
+    """
+
+    if not isinstance(values, ABCMultiIndex):
+        # extract_array would raise
+        values = extract_array(values, extract_numpy=True)
+
+    if is_object_dtype(values.dtype):
+        return ensure_object(np.asarray(values))
+
+    elif isinstance(values.dtype, BaseMaskedDtype):
+        # i.e. BooleanArray, FloatingArray, IntegerArray
+        values = cast("BaseMaskedArray", values)
+        if not values._hasna:
+            # No pd.NAs -> We can avoid an object-dtype cast (and copy) GH#41816
+            #  recurse to avoid re-implementing logic for eg bool->uint8
+            return _ensure_data(values._data)
+        return np.asarray(values)
+
+    elif isinstance(values.dtype, CategoricalDtype):
+        # NB: cases that go through here should NOT be using _reconstruct_data
+        #  on the back-end.
+        values = cast("Categorical", values)
+        return values.codes
+
+    elif is_bool_dtype(values.dtype):
+        if isinstance(values, np.ndarray):
+            # i.e. actually dtype == np.dtype("bool")
+            return np.asarray(values).view("uint8")
+        else:
+            # e.g. Sparse[bool, False]  # TODO: no test cases get here
+            return np.asarray(values).astype("uint8", copy=False)
+
+    elif is_integer_dtype(values.dtype):
+        return np.asarray(values)
+
+    elif is_float_dtype(values.dtype):
+        # Note: checking `values.dtype == "float128"` raises on Windows and 32bit
+        # error: Item "ExtensionDtype" of "Union[Any, ExtensionDtype, dtype[Any]]"
+        # has no attribute "itemsize"
+        if values.dtype.itemsize in [2, 12, 16]:  # type: ignore[union-attr]
+            # we dont (yet) have float128 hashtable support
+            return ensure_float64(values)
+        return np.asarray(values)
+
+    elif is_complex_dtype(values.dtype):
+        return cast(np.ndarray, values)
+
+    # datetimelike
+    elif needs_i8_conversion(values.dtype):
+        npvalues = values.view("i8")
+        npvalues = cast(np.ndarray, npvalues)
+        return npvalues
+
+    # we have failed, return object
+    values = np.asarray(values, dtype=object)
+    return ensure_object(values)
+
+
+def _reconstruct_data(
+    values: ArrayLike, dtype: DtypeObj, original: AnyArrayLike
+) -> ArrayLike:
+    """
+    reverse of _ensure_data
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+    dtype : np.dtype or ExtensionDtype
+    original : AnyArrayLike
+
+    Returns
+    -------
+    ExtensionArray or np.ndarray
+    """
+    if isinstance(values, ABCExtensionArray) and values.dtype == dtype:
+        # Catch DatetimeArray/TimedeltaArray
+        return values
+
+    if not isinstance(dtype, np.dtype):
+        # i.e. ExtensionDtype; note we have ruled out above the possibility
+        #  that values.dtype == dtype
+        cls = dtype.construct_array_type()
+
+        values = cls._from_sequence(values, dtype=dtype)
+
+    else:
+        values = values.astype(dtype, copy=False)
+
+    return values
+
+
+def _ensure_arraylike(values, func_name: str) -> ArrayLike:
+    """
+    ensure that we are arraylike if not already
+    """
+    if not isinstance(values, (ABCIndex, ABCSeries, ABCExtensionArray, np.ndarray)):
+        # GH#52986
+        if func_name != "isin-targets":
+            # Make an exception for the comps argument in isin.
+            warnings.warn(
+                f"{func_name} with argument that is not not a Series, Index, "
+                "ExtensionArray, or np.ndarray is deprecated and will raise in a "
+                "future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        inferred = lib.infer_dtype(values, skipna=False)
+        if inferred in ["mixed", "string", "mixed-integer"]:
+            # "mixed-integer" to ensure we do not cast ["ss", 42] to str GH#22160
+            if isinstance(values, tuple):
+                values = list(values)
+            values = construct_1d_object_array_from_listlike(values)
+        else:
+            values = np.asarray(values)
+    return values
+
+
+_hashtables = {
+    "complex128": htable.Complex128HashTable,
+    "complex64": htable.Complex64HashTable,
+    "float64": htable.Float64HashTable,
+    "float32": htable.Float32HashTable,
+    "uint64": htable.UInt64HashTable,
+    "uint32": htable.UInt32HashTable,
+    "uint16": htable.UInt16HashTable,
+    "uint8": htable.UInt8HashTable,
+    "int64": htable.Int64HashTable,
+    "int32": htable.Int32HashTable,
+    "int16": htable.Int16HashTable,
+    "int8": htable.Int8HashTable,
+    "string": htable.StringHashTable,
+    "object": htable.PyObjectHashTable,
+}
+
+
+def _get_hashtable_algo(values: np.ndarray):
+    """
+    Parameters
+    ----------
+    values : np.ndarray
+
+    Returns
+    -------
+    htable : HashTable subclass
+    values : ndarray
+    """
+    values = _ensure_data(values)
+
+    ndtype = _check_object_for_strings(values)
+    hashtable = _hashtables[ndtype]
+    return hashtable, values
+
+
+def _check_object_for_strings(values: np.ndarray) -> str:
+    """
+    Check if we can use string hashtable instead of object hashtable.
+
+    Parameters
+    ----------
+    values : ndarray
+
+    Returns
+    -------
+    str
+    """
+    ndtype = values.dtype.name
+    if ndtype == "object":
+        # it's cheaper to use a String Hash Table than Object; we infer
+        # including nulls because that is the only difference between
+        # StringHashTable and ObjectHashtable
+        if lib.is_string_array(values, skipna=False):
+            ndtype = "string"
+    return ndtype
+
+
+# --------------- #
+# top-level algos #
+# --------------- #
+
+
+def unique(values):
+    """
+    Return unique values based on a hash table.
+
+    Uniques are returned in order of appearance. This does NOT sort.
+
+    Significantly faster than numpy.unique for long enough sequences.
+    Includes NA values.
+
+    Parameters
+    ----------
+    values : 1d array-like
+
+    Returns
+    -------
+    numpy.ndarray or ExtensionArray
+
+        The return can be:
+
+        * Index : when the input is an Index
+        * Categorical : when the input is a Categorical dtype
+        * ndarray : when the input is a Series/ndarray
+
+        Return numpy.ndarray or ExtensionArray.
+
+    See Also
+    --------
+    Index.unique : Return unique values from an Index.
+    Series.unique : Return unique values of Series object.
+
+    Examples
+    --------
+    >>> pd.unique(pd.Series([2, 1, 3, 3]))
+    array([2, 1, 3])
+
+    >>> pd.unique(pd.Series([2] + [1] * 5))
+    array([2, 1])
+
+    >>> pd.unique(pd.Series([pd.Timestamp("20160101"), pd.Timestamp("20160101")]))
+    array(['2016-01-01T00:00:00.000000000'], dtype='datetime64[ns]')
+
+    >>> pd.unique(
+    ...     pd.Series(
+    ...         [
+    ...             pd.Timestamp("20160101", tz="US/Eastern"),
+    ...             pd.Timestamp("20160101", tz="US/Eastern"),
+    ...         ]
+    ...     )
+    ... )
+    
+    ['2016-01-01 00:00:00-05:00']
+    Length: 1, dtype: datetime64[ns, US/Eastern]
+
+    >>> pd.unique(
+    ...     pd.Index(
+    ...         [
+    ...             pd.Timestamp("20160101", tz="US/Eastern"),
+    ...             pd.Timestamp("20160101", tz="US/Eastern"),
+    ...         ]
+    ...     )
+    ... )
+    DatetimeIndex(['2016-01-01 00:00:00-05:00'],
+            dtype='datetime64[ns, US/Eastern]',
+            freq=None)
+
+    >>> pd.unique(np.array(list("baabc"), dtype="O"))
+    array(['b', 'a', 'c'], dtype=object)
+
+    An unordered Categorical will return categories in the
+    order of appearance.
+
+    >>> pd.unique(pd.Series(pd.Categorical(list("baabc"))))
+    ['b', 'a', 'c']
+    Categories (3, object): ['a', 'b', 'c']
+
+    >>> pd.unique(pd.Series(pd.Categorical(list("baabc"), categories=list("abc"))))
+    ['b', 'a', 'c']
+    Categories (3, object): ['a', 'b', 'c']
+
+    An ordered Categorical preserves the category ordering.
+
+    >>> pd.unique(
+    ...     pd.Series(
+    ...         pd.Categorical(list("baabc"), categories=list("abc"), ordered=True)
+    ...     )
+    ... )
+    ['b', 'a', 'c']
+    Categories (3, object): ['a' < 'b' < 'c']
+
+    An array of tuples
+
+    >>> pd.unique(pd.Series([("a", "b"), ("b", "a"), ("a", "c"), ("b", "a")]).values)
+    array([('a', 'b'), ('b', 'a'), ('a', 'c')], dtype=object)
+    """
+    return unique_with_mask(values)
+
+
+def nunique_ints(values: ArrayLike) -> int:
+    """
+    Return the number of unique values for integer array-likes.
+
+    Significantly faster than pandas.unique for long enough sequences.
+    No checks are done to ensure input is integral.
+
+    Parameters
+    ----------
+    values : 1d array-like
+
+    Returns
+    -------
+    int : The number of unique values in ``values``
+    """
+    if len(values) == 0:
+        return 0
+    values = _ensure_data(values)
+    # bincount requires intp
+    result = (np.bincount(values.ravel().astype("intp")) != 0).sum()
+    return result
+
+
+def unique_with_mask(values, mask: npt.NDArray[np.bool_] | None = None):
+    """See algorithms.unique for docs. Takes a mask for masked arrays."""
+    values = _ensure_arraylike(values, func_name="unique")
+
+    if isinstance(values.dtype, ExtensionDtype):
+        # Dispatch to extension dtype's unique.
+        return values.unique()
+
+    original = values
+    hashtable, values = _get_hashtable_algo(values)
+
+    table = hashtable(len(values))
+    if mask is None:
+        uniques = table.unique(values)
+        uniques = _reconstruct_data(uniques, original.dtype, original)
+        return uniques
+
+    else:
+        uniques, mask = table.unique(values, mask=mask)
+        uniques = _reconstruct_data(uniques, original.dtype, original)
+        assert mask is not None  # for mypy
+        return uniques, mask.astype("bool")
+
+
+unique1d = unique
+
+
+_MINIMUM_COMP_ARR_LEN = 1_000_000
+
+
+def isin(comps: ListLike, values: ListLike) -> npt.NDArray[np.bool_]:
+    """
+    Compute the isin boolean array.
+
+    Parameters
+    ----------
+    comps : list-like
+    values : list-like
+
+    Returns
+    -------
+    ndarray[bool]
+        Same length as `comps`.
+    """
+    if not is_list_like(comps):
+        raise TypeError(
+            "only list-like objects are allowed to be passed "
+            f"to isin(), you passed a `{type(comps).__name__}`"
+        )
+    if not is_list_like(values):
+        raise TypeError(
+            "only list-like objects are allowed to be passed "
+            f"to isin(), you passed a `{type(values).__name__}`"
+        )
+
+    if not isinstance(values, (ABCIndex, ABCSeries, ABCExtensionArray, np.ndarray)):
+        orig_values = list(values)
+        values = _ensure_arraylike(orig_values, func_name="isin-targets")
+
+        if (
+            len(values) > 0
+            and values.dtype.kind in "iufcb"
+            and not is_signed_integer_dtype(comps)
+        ):
+            # GH#46485 Use object to avoid upcast to float64 later
+            # TODO: Share with _find_common_type_compat
+            values = construct_1d_object_array_from_listlike(orig_values)
+
+    elif isinstance(values, ABCMultiIndex):
+        # Avoid raising in extract_array
+        values = np.array(values)
+    else:
+        values = extract_array(values, extract_numpy=True, extract_range=True)
+
+    comps_array = _ensure_arraylike(comps, func_name="isin")
+    comps_array = extract_array(comps_array, extract_numpy=True)
+    if not isinstance(comps_array, np.ndarray):
+        # i.e. Extension Array
+        return comps_array.isin(values)
+
+    elif needs_i8_conversion(comps_array.dtype):
+        # Dispatch to DatetimeLikeArrayMixin.isin
+        return pd_array(comps_array).isin(values)
+    elif needs_i8_conversion(values.dtype) and not is_object_dtype(comps_array.dtype):
+        # e.g. comps_array are integers and values are datetime64s
+        return np.zeros(comps_array.shape, dtype=bool)
+        # TODO: not quite right ... Sparse/Categorical
+    elif needs_i8_conversion(values.dtype):
+        return isin(comps_array, values.astype(object))
+
+    elif isinstance(values.dtype, ExtensionDtype):
+        return isin(np.asarray(comps_array), np.asarray(values))
+
+    # GH16012
+    # Ensure np.isin doesn't get object types or it *may* throw an exception
+    # Albeit hashmap has O(1) look-up (vs. O(logn) in sorted array),
+    # isin is faster for small sizes
+    if (
+        len(comps_array) > _MINIMUM_COMP_ARR_LEN
+        and len(values) <= 26
+        and comps_array.dtype != object
+    ):
+        # If the values include nan we need to check for nan explicitly
+        # since np.nan it not equal to np.nan
+        if isna(values).any():
+
+            def f(c, v):
+                return np.logical_or(np.isin(c, v).ravel(), np.isnan(c))
+
+        else:
+            f = lambda a, b: np.isin(a, b).ravel()
+
+    else:
+        common = np_find_common_type(values.dtype, comps_array.dtype)
+        values = values.astype(common, copy=False)
+        comps_array = comps_array.astype(common, copy=False)
+        f = htable.ismember
+
+    return f(comps_array, values)
+
+
+def factorize_array(
+    values: np.ndarray,
+    use_na_sentinel: bool = True,
+    size_hint: int | None = None,
+    na_value: object = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> tuple[npt.NDArray[np.intp], np.ndarray]:
+    """
+    Factorize a numpy array to codes and uniques.
+
+    This doesn't do any coercion of types or unboxing before factorization.
+
+    Parameters
+    ----------
+    values : ndarray
+    use_na_sentinel : bool, default True
+        If True, the sentinel -1 will be used for NaN values. If False,
+        NaN values will be encoded as non-negative integers and will not drop the
+        NaN from the uniques of the values.
+    size_hint : int, optional
+        Passed through to the hashtable's 'get_labels' method
+    na_value : object, optional
+        A value in `values` to consider missing. Note: only use this
+        parameter when you know that you don't have any values pandas would
+        consider missing in the array (NaN for float data, iNaT for
+        datetimes, etc.).
+    mask : ndarray[bool], optional
+        If not None, the mask is used as indicator for missing values
+        (True = missing, False = valid) instead of `na_value` or
+        condition "val != val".
+
+    Returns
+    -------
+    codes : ndarray[np.intp]
+    uniques : ndarray
+    """
+    original = values
+    if values.dtype.kind in "mM":
+        # _get_hashtable_algo will cast dt64/td64 to i8 via _ensure_data, so we
+        #  need to do the same to na_value. We are assuming here that the passed
+        #  na_value is an appropriately-typed NaT.
+        # e.g. test_where_datetimelike_categorical
+        na_value = iNaT
+
+    hash_klass, values = _get_hashtable_algo(values)
+
+    table = hash_klass(size_hint or len(values))
+    uniques, codes = table.factorize(
+        values,
+        na_sentinel=-1,
+        na_value=na_value,
+        mask=mask,
+        ignore_na=use_na_sentinel,
+    )
+
+    # re-cast e.g. i8->dt64/td64, uint8->bool
+    uniques = _reconstruct_data(uniques, original.dtype, original)
+
+    codes = ensure_platform_int(codes)
+    return codes, uniques
+
+
+@doc(
+    values=dedent(
+        """\
+    values : sequence
+        A 1-D sequence. Sequences that aren't pandas objects are
+        coerced to ndarrays before factorization.
+    """
+    ),
+    sort=dedent(
+        """\
+    sort : bool, default False
+        Sort `uniques` and shuffle `codes` to maintain the
+        relationship.
+    """
+    ),
+    size_hint=dedent(
+        """\
+    size_hint : int, optional
+        Hint to the hashtable sizer.
+    """
+    ),
+)
+def factorize(
+    values,
+    sort: bool = False,
+    use_na_sentinel: bool = True,
+    size_hint: int | None = None,
+) -> tuple[np.ndarray, np.ndarray | Index]:
+    """
+    Encode the object as an enumerated type or categorical variable.
+
+    This method is useful for obtaining a numeric representation of an
+    array when all that matters is identifying distinct values. `factorize`
+    is available as both a top-level function :func:`pandas.factorize`,
+    and as a method :meth:`Series.factorize` and :meth:`Index.factorize`.
+
+    Parameters
+    ----------
+    {values}{sort}
+    use_na_sentinel : bool, default True
+        If True, the sentinel -1 will be used for NaN values. If False,
+        NaN values will be encoded as non-negative integers and will not drop the
+        NaN from the uniques of the values.
+
+        .. versionadded:: 1.5.0
+    {size_hint}\
+
+    Returns
+    -------
+    codes : ndarray
+        An integer ndarray that's an indexer into `uniques`.
+        ``uniques.take(codes)`` will have the same values as `values`.
+    uniques : ndarray, Index, or Categorical
+        The unique valid values. When `values` is Categorical, `uniques`
+        is a Categorical. When `values` is some other pandas object, an
+        `Index` is returned. Otherwise, a 1-D ndarray is returned.
+
+        .. note::
+
+           Even if there's a missing value in `values`, `uniques` will
+           *not* contain an entry for it.
+
+    See Also
+    --------
+    cut : Discretize continuous-valued array.
+    unique : Find the unique value in an array.
+
+    Notes
+    -----
+    Reference :ref:`the user guide ` for more examples.
+
+    Examples
+    --------
+    These examples all show factorize as a top-level method like
+    ``pd.factorize(values)``. The results are identical for methods like
+    :meth:`Series.factorize`.
+
+    >>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"))
+    >>> codes
+    array([0, 0, 1, 2, 0])
+    >>> uniques
+    array(['b', 'a', 'c'], dtype=object)
+
+    With ``sort=True``, the `uniques` will be sorted, and `codes` will be
+    shuffled so that the relationship is the maintained.
+
+    >>> codes, uniques = pd.factorize(np.array(['b', 'b', 'a', 'c', 'b'], dtype="O"),
+    ...                               sort=True)
+    >>> codes
+    array([1, 1, 0, 2, 1])
+    >>> uniques
+    array(['a', 'b', 'c'], dtype=object)
+
+    When ``use_na_sentinel=True`` (the default), missing values are indicated in
+    the `codes` with the sentinel value ``-1`` and missing values are not
+    included in `uniques`.
+
+    >>> codes, uniques = pd.factorize(np.array(['b', None, 'a', 'c', 'b'], dtype="O"))
+    >>> codes
+    array([ 0, -1,  1,  2,  0])
+    >>> uniques
+    array(['b', 'a', 'c'], dtype=object)
+
+    Thus far, we've only factorized lists (which are internally coerced to
+    NumPy arrays). When factorizing pandas objects, the type of `uniques`
+    will differ. For Categoricals, a `Categorical` is returned.
+
+    >>> cat = pd.Categorical(['a', 'a', 'c'], categories=['a', 'b', 'c'])
+    >>> codes, uniques = pd.factorize(cat)
+    >>> codes
+    array([0, 0, 1])
+    >>> uniques
+    ['a', 'c']
+    Categories (3, object): ['a', 'b', 'c']
+
+    Notice that ``'b'`` is in ``uniques.categories``, despite not being
+    present in ``cat.values``.
+
+    For all other pandas objects, an Index of the appropriate type is
+    returned.
+
+    >>> cat = pd.Series(['a', 'a', 'c'])
+    >>> codes, uniques = pd.factorize(cat)
+    >>> codes
+    array([0, 0, 1])
+    >>> uniques
+    Index(['a', 'c'], dtype='object')
+
+    If NaN is in the values, and we want to include NaN in the uniques of the
+    values, it can be achieved by setting ``use_na_sentinel=False``.
+
+    >>> values = np.array([1, 2, 1, np.nan])
+    >>> codes, uniques = pd.factorize(values)  # default: use_na_sentinel=True
+    >>> codes
+    array([ 0,  1,  0, -1])
+    >>> uniques
+    array([1., 2.])
+
+    >>> codes, uniques = pd.factorize(values, use_na_sentinel=False)
+    >>> codes
+    array([0, 1, 0, 2])
+    >>> uniques
+    array([ 1.,  2., nan])
+    """
+    # Implementation notes: This method is responsible for 3 things
+    # 1.) coercing data to array-like (ndarray, Index, extension array)
+    # 2.) factorizing codes and uniques
+    # 3.) Maybe boxing the uniques in an Index
+    #
+    # Step 2 is dispatched to extension types (like Categorical). They are
+    # responsible only for factorization. All data coercion, sorting and boxing
+    # should happen here.
+    if isinstance(values, (ABCIndex, ABCSeries)):
+        return values.factorize(sort=sort, use_na_sentinel=use_na_sentinel)
+
+    values = _ensure_arraylike(values, func_name="factorize")
+    original = values
+
+    if (
+        isinstance(values, (ABCDatetimeArray, ABCTimedeltaArray))
+        and values.freq is not None
+    ):
+        # The presence of 'freq' means we can fast-path sorting and know there
+        #  aren't NAs
+        codes, uniques = values.factorize(sort=sort)
+        return codes, uniques
+
+    elif not isinstance(values, np.ndarray):
+        # i.e. ExtensionArray
+        codes, uniques = values.factorize(use_na_sentinel=use_na_sentinel)
+
+    else:
+        values = np.asarray(values)  # convert DTA/TDA/MultiIndex
+
+        if not use_na_sentinel and values.dtype == object:
+            # factorize can now handle differentiating various types of null values.
+            # These can only occur when the array has object dtype.
+            # However, for backwards compatibility we only use the null for the
+            # provided dtype. This may be revisited in the future, see GH#48476.
+            null_mask = isna(values)
+            if null_mask.any():
+                na_value = na_value_for_dtype(values.dtype, compat=False)
+                # Don't modify (potentially user-provided) array
+                values = np.where(null_mask, na_value, values)
+
+        codes, uniques = factorize_array(
+            values,
+            use_na_sentinel=use_na_sentinel,
+            size_hint=size_hint,
+        )
+
+    if sort and len(uniques) > 0:
+        uniques, codes = safe_sort(
+            uniques,
+            codes,
+            use_na_sentinel=use_na_sentinel,
+            assume_unique=True,
+            verify=False,
+        )
+
+    uniques = _reconstruct_data(uniques, original.dtype, original)
+
+    return codes, uniques
+
+
+def value_counts(
+    values,
+    sort: bool = True,
+    ascending: bool = False,
+    normalize: bool = False,
+    bins=None,
+    dropna: bool = True,
+) -> Series:
+    """
+    Compute a histogram of the counts of non-null values.
+
+    Parameters
+    ----------
+    values : ndarray (1-d)
+    sort : bool, default True
+        Sort by values
+    ascending : bool, default False
+        Sort in ascending order
+    normalize: bool, default False
+        If True then compute a relative histogram
+    bins : integer, optional
+        Rather than count values, group them into half-open bins,
+        convenience for pd.cut, only works with numeric data
+    dropna : bool, default True
+        Don't include counts of NaN
+
+    Returns
+    -------
+    Series
+    """
+    warnings.warn(
+        # GH#53493
+        "pandas.value_counts is deprecated and will be removed in a "
+        "future version. Use pd.Series(obj).value_counts() instead.",
+        FutureWarning,
+        stacklevel=find_stack_level(),
+    )
+    return value_counts_internal(
+        values,
+        sort=sort,
+        ascending=ascending,
+        normalize=normalize,
+        bins=bins,
+        dropna=dropna,
+    )
+
+
+def value_counts_internal(
+    values,
+    sort: bool = True,
+    ascending: bool = False,
+    normalize: bool = False,
+    bins=None,
+    dropna: bool = True,
+) -> Series:
+    from pandas import (
+        Index,
+        Series,
+    )
+
+    index_name = getattr(values, "name", None)
+    name = "proportion" if normalize else "count"
+
+    if bins is not None:
+        from pandas.core.reshape.tile import cut
+
+        if isinstance(values, Series):
+            values = values._values
+
+        try:
+            ii = cut(values, bins, include_lowest=True)
+        except TypeError as err:
+            raise TypeError("bins argument only works with numeric data.") from err
+
+        # count, remove nulls (from the index), and but the bins
+        result = ii.value_counts(dropna=dropna)
+        result.name = name
+        result = result[result.index.notna()]
+        result.index = result.index.astype("interval")
+        result = result.sort_index()
+
+        # if we are dropna and we have NO values
+        if dropna and (result._values == 0).all():
+            result = result.iloc[0:0]
+
+        # normalizing is by len of all (regardless of dropna)
+        counts = np.array([len(ii)])
+
+    else:
+        if is_extension_array_dtype(values):
+            # handle Categorical and sparse,
+            result = Series(values, copy=False)._values.value_counts(dropna=dropna)
+            result.name = name
+            result.index.name = index_name
+            counts = result._values
+            if not isinstance(counts, np.ndarray):
+                # e.g. ArrowExtensionArray
+                counts = np.asarray(counts)
+
+        elif isinstance(values, ABCMultiIndex):
+            # GH49558
+            levels = list(range(values.nlevels))
+            result = (
+                Series(index=values, name=name)
+                .groupby(level=levels, dropna=dropna)
+                .size()
+            )
+            result.index.names = values.names
+            counts = result._values
+
+        else:
+            values = _ensure_arraylike(values, func_name="value_counts")
+            keys, counts, _ = value_counts_arraylike(values, dropna)
+            if keys.dtype == np.float16:
+                keys = keys.astype(np.float32)
+
+            # For backwards compatibility, we let Index do its normal type
+            #  inference, _except_ for if if infers from object to bool.
+            idx = Index(keys)
+            if idx.dtype in [bool, "string"] and keys.dtype == object:
+                idx = idx.astype(object)
+            elif (
+                idx.dtype != keys.dtype  # noqa: PLR1714  # # pylint: disable=R1714
+                and idx.dtype != "string"
+            ):
+                warnings.warn(
+                    # GH#56161
+                    "The behavior of value_counts with object-dtype is deprecated. "
+                    "In a future version, this will *not* perform dtype inference "
+                    "on the resulting index. To retain the old behavior, use "
+                    "`result.index = result.index.infer_objects()`",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            idx.name = index_name
+
+            result = Series(counts, index=idx, name=name, copy=False)
+
+    if sort:
+        result = result.sort_values(ascending=ascending)
+
+    if normalize:
+        result = result / counts.sum()
+
+    return result
+
+
+# Called once from SparseArray, otherwise could be private
+def value_counts_arraylike(
+    values: np.ndarray, dropna: bool, mask: npt.NDArray[np.bool_] | None = None
+) -> tuple[ArrayLike, npt.NDArray[np.int64], int]:
+    """
+    Parameters
+    ----------
+    values : np.ndarray
+    dropna : bool
+    mask : np.ndarray[bool] or None, default None
+
+    Returns
+    -------
+    uniques : np.ndarray
+    counts : np.ndarray[np.int64]
+    """
+    original = values
+    values = _ensure_data(values)
+
+    keys, counts, na_counter = htable.value_count(values, dropna, mask=mask)
+
+    if needs_i8_conversion(original.dtype):
+        # datetime, timedelta, or period
+
+        if dropna:
+            mask = keys != iNaT
+            keys, counts = keys[mask], counts[mask]
+
+    res_keys = _reconstruct_data(keys, original.dtype, original)
+    return res_keys, counts, na_counter
+
+
+def duplicated(
+    values: ArrayLike,
+    keep: Literal["first", "last", False] = "first",
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> npt.NDArray[np.bool_]:
+    """
+    Return boolean ndarray denoting duplicate values.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+        Array over which to check for duplicate values.
+    keep : {'first', 'last', False}, default 'first'
+        - ``first`` : Mark duplicates as ``True`` except for the first
+          occurrence.
+        - ``last`` : Mark duplicates as ``True`` except for the last
+          occurrence.
+        - False : Mark all duplicates as ``True``.
+    mask : ndarray[bool], optional
+        array indicating which elements to exclude from checking
+
+    Returns
+    -------
+    duplicated : ndarray[bool]
+    """
+    values = _ensure_data(values)
+    return htable.duplicated(values, keep=keep, mask=mask)
+
+
+def mode(
+    values: ArrayLike, dropna: bool = True, mask: npt.NDArray[np.bool_] | None = None
+) -> ArrayLike:
+    """
+    Returns the mode(s) of an array.
+
+    Parameters
+    ----------
+    values : array-like
+        Array over which to check for duplicate values.
+    dropna : bool, default True
+        Don't consider counts of NaN/NaT.
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    values = _ensure_arraylike(values, func_name="mode")
+    original = values
+
+    if needs_i8_conversion(values.dtype):
+        # Got here with ndarray; dispatch to DatetimeArray/TimedeltaArray.
+        values = ensure_wrapped_if_datetimelike(values)
+        values = cast("ExtensionArray", values)
+        return values._mode(dropna=dropna)
+
+    values = _ensure_data(values)
+
+    npresult, res_mask = htable.mode(values, dropna=dropna, mask=mask)
+    if res_mask is not None:
+        return npresult, res_mask  # type: ignore[return-value]
+
+    try:
+        npresult = safe_sort(npresult)
+    except TypeError as err:
+        warnings.warn(
+            f"Unable to sort modes: {err}",
+            stacklevel=find_stack_level(),
+        )
+
+    result = _reconstruct_data(npresult, original.dtype, original)
+    return result
+
+
+def rank(
+    values: ArrayLike,
+    axis: AxisInt = 0,
+    method: str = "average",
+    na_option: str = "keep",
+    ascending: bool = True,
+    pct: bool = False,
+) -> npt.NDArray[np.float64]:
+    """
+    Rank the values along a given axis.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+        Array whose values will be ranked. The number of dimensions in this
+        array must not exceed 2.
+    axis : int, default 0
+        Axis over which to perform rankings.
+    method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
+        The method by which tiebreaks are broken during the ranking.
+    na_option : {'keep', 'top'}, default 'keep'
+        The method by which NaNs are placed in the ranking.
+        - ``keep``: rank each NaN value with a NaN ranking
+        - ``top``: replace each NaN with either +/- inf so that they
+                   there are ranked at the top
+    ascending : bool, default True
+        Whether or not the elements should be ranked in ascending order.
+    pct : bool, default False
+        Whether or not to the display the returned rankings in integer form
+        (e.g. 1, 2, 3) or in percentile form (e.g. 0.333..., 0.666..., 1).
+    """
+    is_datetimelike = needs_i8_conversion(values.dtype)
+    values = _ensure_data(values)
+
+    if values.ndim == 1:
+        ranks = algos.rank_1d(
+            values,
+            is_datetimelike=is_datetimelike,
+            ties_method=method,
+            ascending=ascending,
+            na_option=na_option,
+            pct=pct,
+        )
+    elif values.ndim == 2:
+        ranks = algos.rank_2d(
+            values,
+            axis=axis,
+            is_datetimelike=is_datetimelike,
+            ties_method=method,
+            ascending=ascending,
+            na_option=na_option,
+            pct=pct,
+        )
+    else:
+        raise TypeError("Array with ndim > 2 are not supported.")
+
+    return ranks
+
+
+# ---- #
+# take #
+# ---- #
+
+
+def take(
+    arr,
+    indices: TakeIndexer,
+    axis: AxisInt = 0,
+    allow_fill: bool = False,
+    fill_value=None,
+):
+    """
+    Take elements from an array.
+
+    Parameters
+    ----------
+    arr : array-like or scalar value
+        Non array-likes (sequences/scalars without a dtype) are coerced
+        to an ndarray.
+
+        .. deprecated:: 2.1.0
+            Passing an argument other than a numpy.ndarray, ExtensionArray,
+            Index, or Series is deprecated.
+
+    indices : sequence of int or one-dimensional np.ndarray of int
+        Indices to be taken.
+    axis : int, default 0
+        The axis over which to select values.
+    allow_fill : bool, default False
+        How to handle negative values in `indices`.
+
+        * False: negative values in `indices` indicate positional indices
+          from the right (the default). This is similar to :func:`numpy.take`.
+
+        * True: negative values in `indices` indicate
+          missing values. These values are set to `fill_value`. Any other
+          negative values raise a ``ValueError``.
+
+    fill_value : any, optional
+        Fill value to use for NA-indices when `allow_fill` is True.
+        This may be ``None``, in which case the default NA value for
+        the type (``self.dtype.na_value``) is used.
+
+        For multi-dimensional `arr`, each *element* is filled with
+        `fill_value`.
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+        Same type as the input.
+
+    Raises
+    ------
+    IndexError
+        When `indices` is out of bounds for the array.
+    ValueError
+        When the indexer contains negative values other than ``-1``
+        and `allow_fill` is True.
+
+    Notes
+    -----
+    When `allow_fill` is False, `indices` may be whatever dimensionality
+    is accepted by NumPy for `arr`.
+
+    When `allow_fill` is True, `indices` should be 1-D.
+
+    See Also
+    --------
+    numpy.take : Take elements from an array along an axis.
+
+    Examples
+    --------
+    >>> import pandas as pd
+
+    With the default ``allow_fill=False``, negative numbers indicate
+    positional indices from the right.
+
+    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1])
+    array([10, 10, 30])
+
+    Setting ``allow_fill=True`` will place `fill_value` in those positions.
+
+    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True)
+    array([10., 10., nan])
+
+    >>> pd.api.extensions.take(np.array([10, 20, 30]), [0, 0, -1], allow_fill=True,
+    ...      fill_value=-10)
+    array([ 10,  10, -10])
+    """
+    if not isinstance(arr, (np.ndarray, ABCExtensionArray, ABCIndex, ABCSeries)):
+        # GH#52981
+        warnings.warn(
+            "pd.api.extensions.take accepting non-standard inputs is deprecated "
+            "and will raise in a future version. Pass either a numpy.ndarray, "
+            "ExtensionArray, Index, or Series instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if not is_array_like(arr):
+        arr = np.asarray(arr)
+
+    indices = ensure_platform_int(indices)
+
+    if allow_fill:
+        # Pandas style, -1 means NA
+        validate_indices(indices, arr.shape[axis])
+        result = take_nd(
+            arr, indices, axis=axis, allow_fill=True, fill_value=fill_value
+        )
+    else:
+        # NumPy style
+        result = arr.take(indices, axis=axis)
+    return result
+
+
+# ------------ #
+# searchsorted #
+# ------------ #
+
+
+def searchsorted(
+    arr: ArrayLike,
+    value: NumpyValueArrayLike | ExtensionArray,
+    side: Literal["left", "right"] = "left",
+    sorter: NumpySorter | None = None,
+) -> npt.NDArray[np.intp] | np.intp:
+    """
+    Find indices where elements should be inserted to maintain order.
+
+    Find the indices into a sorted array `arr` (a) such that, if the
+    corresponding elements in `value` were inserted before the indices,
+    the order of `arr` would be preserved.
+
+    Assuming that `arr` is sorted:
+
+    ======  ================================
+    `side`  returned index `i` satisfies
+    ======  ================================
+    left    ``arr[i-1] < value <= self[i]``
+    right   ``arr[i-1] <= value < self[i]``
+    ======  ================================
+
+    Parameters
+    ----------
+    arr: np.ndarray, ExtensionArray, Series
+        Input array. If `sorter` is None, then it must be sorted in
+        ascending order, otherwise `sorter` must be an array of indices
+        that sort it.
+    value : array-like or scalar
+        Values to insert into `arr`.
+    side : {'left', 'right'}, optional
+        If 'left', the index of the first suitable location found is given.
+        If 'right', return the last such index.  If there is no suitable
+        index, return either 0 or N (where N is the length of `self`).
+    sorter : 1-D array-like, optional
+        Optional array of integer indices that sort array a into ascending
+        order. They are typically the result of argsort.
+
+    Returns
+    -------
+    array of ints or int
+        If value is array-like, array of insertion points.
+        If value is scalar, a single integer.
+
+    See Also
+    --------
+    numpy.searchsorted : Similar method from NumPy.
+    """
+    if sorter is not None:
+        sorter = ensure_platform_int(sorter)
+
+    if (
+        isinstance(arr, np.ndarray)
+        and arr.dtype.kind in "iu"
+        and (is_integer(value) or is_integer_dtype(value))
+    ):
+        # if `arr` and `value` have different dtypes, `arr` would be
+        # recast by numpy, causing a slow search.
+        # Before searching below, we therefore try to give `value` the
+        # same dtype as `arr`, while guarding against integer overflows.
+        iinfo = np.iinfo(arr.dtype.type)
+        value_arr = np.array([value]) if is_integer(value) else np.array(value)
+        if (value_arr >= iinfo.min).all() and (value_arr <= iinfo.max).all():
+            # value within bounds, so no overflow, so can convert value dtype
+            # to dtype of arr
+            dtype = arr.dtype
+        else:
+            dtype = value_arr.dtype
+
+        if is_integer(value):
+            # We know that value is int
+            value = cast(int, dtype.type(value))
+        else:
+            value = pd_array(cast(ArrayLike, value), dtype=dtype)
+    else:
+        # E.g. if `arr` is an array with dtype='datetime64[ns]'
+        # and `value` is a pd.Timestamp, we may need to convert value
+        arr = ensure_wrapped_if_datetimelike(arr)
+
+    # Argument 1 to "searchsorted" of "ndarray" has incompatible type
+    # "Union[NumpyValueArrayLike, ExtensionArray]"; expected "NumpyValueArrayLike"
+    return arr.searchsorted(value, side=side, sorter=sorter)  # type: ignore[arg-type]
+
+
+# ---- #
+# diff #
+# ---- #
+
+_diff_special = {"float64", "float32", "int64", "int32", "int16", "int8"}
+
+
+def diff(arr, n: int, axis: AxisInt = 0):
+    """
+    difference of n between self,
+    analogous to s-s.shift(n)
+
+    Parameters
+    ----------
+    arr : ndarray or ExtensionArray
+    n : int
+        number of periods
+    axis : {0, 1}
+        axis to shift on
+    stacklevel : int, default 3
+        The stacklevel for the lost dtype warning.
+
+    Returns
+    -------
+    shifted
+    """
+
+    n = int(n)
+    na = np.nan
+    dtype = arr.dtype
+
+    is_bool = is_bool_dtype(dtype)
+    if is_bool:
+        op = operator.xor
+    else:
+        op = operator.sub
+
+    if isinstance(dtype, NumpyEADtype):
+        # NumpyExtensionArray cannot necessarily hold shifted versions of itself.
+        arr = arr.to_numpy()
+        dtype = arr.dtype
+
+    if not isinstance(arr, np.ndarray):
+        # i.e ExtensionArray
+        if hasattr(arr, f"__{op.__name__}__"):
+            if axis != 0:
+                raise ValueError(f"cannot diff {type(arr).__name__} on axis={axis}")
+            return op(arr, arr.shift(n))
+        else:
+            raise TypeError(
+                f"{type(arr).__name__} has no 'diff' method. "
+                "Convert to a suitable dtype prior to calling 'diff'."
+            )
+
+    is_timedelta = False
+    if arr.dtype.kind in "mM":
+        dtype = np.int64
+        arr = arr.view("i8")
+        na = iNaT
+        is_timedelta = True
+
+    elif is_bool:
+        # We have to cast in order to be able to hold np.nan
+        dtype = np.object_
+
+    elif dtype.kind in "iu":
+        # We have to cast in order to be able to hold np.nan
+
+        # int8, int16 are incompatible with float64,
+        # see https://github.com/cython/cython/issues/2646
+        if arr.dtype.name in ["int8", "int16"]:
+            dtype = np.float32
+        else:
+            dtype = np.float64
+
+    orig_ndim = arr.ndim
+    if orig_ndim == 1:
+        # reshape so we can always use algos.diff_2d
+        arr = arr.reshape(-1, 1)
+        # TODO: require axis == 0
+
+    dtype = np.dtype(dtype)
+    out_arr = np.empty(arr.shape, dtype=dtype)
+
+    na_indexer = [slice(None)] * 2
+    na_indexer[axis] = slice(None, n) if n >= 0 else slice(n, None)
+    out_arr[tuple(na_indexer)] = na
+
+    if arr.dtype.name in _diff_special:
+        # TODO: can diff_2d dtype specialization troubles be fixed by defining
+        #  out_arr inside diff_2d?
+        algos.diff_2d(arr, out_arr, n, axis, datetimelike=is_timedelta)
+    else:
+        # To keep mypy happy, _res_indexer is a list while res_indexer is
+        #  a tuple, ditto for lag_indexer.
+        _res_indexer = [slice(None)] * 2
+        _res_indexer[axis] = slice(n, None) if n >= 0 else slice(None, n)
+        res_indexer = tuple(_res_indexer)
+
+        _lag_indexer = [slice(None)] * 2
+        _lag_indexer[axis] = slice(None, -n) if n > 0 else slice(-n, None)
+        lag_indexer = tuple(_lag_indexer)
+
+        out_arr[res_indexer] = op(arr[res_indexer], arr[lag_indexer])
+
+    if is_timedelta:
+        out_arr = out_arr.view("timedelta64[ns]")
+
+    if orig_ndim == 1:
+        out_arr = out_arr[:, 0]
+    return out_arr
+
+
+# --------------------------------------------------------------------
+# Helper functions
+
+
+# Note: safe_sort is in algorithms.py instead of sorting.py because it is
+#  low-dependency, is used in this module, and used private methods from
+#  this module.
+def safe_sort(
+    values: Index | ArrayLike,
+    codes: npt.NDArray[np.intp] | None = None,
+    use_na_sentinel: bool = True,
+    assume_unique: bool = False,
+    verify: bool = True,
+) -> AnyArrayLike | tuple[AnyArrayLike, np.ndarray]:
+    """
+    Sort ``values`` and reorder corresponding ``codes``.
+
+    ``values`` should be unique if ``codes`` is not None.
+    Safe for use with mixed types (int, str), orders ints before strs.
+
+    Parameters
+    ----------
+    values : list-like
+        Sequence; must be unique if ``codes`` is not None.
+    codes : np.ndarray[intp] or None, default None
+        Indices to ``values``. All out of bound indices are treated as
+        "not found" and will be masked with ``-1``.
+    use_na_sentinel : bool, default True
+        If True, the sentinel -1 will be used for NaN values. If False,
+        NaN values will be encoded as non-negative integers and will not drop the
+        NaN from the uniques of the values.
+    assume_unique : bool, default False
+        When True, ``values`` are assumed to be unique, which can speed up
+        the calculation. Ignored when ``codes`` is None.
+    verify : bool, default True
+        Check if codes are out of bound for the values and put out of bound
+        codes equal to ``-1``. If ``verify=False``, it is assumed there
+        are no out of bound codes. Ignored when ``codes`` is None.
+
+    Returns
+    -------
+    ordered : AnyArrayLike
+        Sorted ``values``
+    new_codes : ndarray
+        Reordered ``codes``; returned when ``codes`` is not None.
+
+    Raises
+    ------
+    TypeError
+        * If ``values`` is not list-like or if ``codes`` is neither None
+        nor list-like
+        * If ``values`` cannot be sorted
+    ValueError
+        * If ``codes`` is not None and ``values`` contain duplicates.
+    """
+    if not isinstance(values, (np.ndarray, ABCExtensionArray, ABCIndex)):
+        raise TypeError(
+            "Only np.ndarray, ExtensionArray, and Index objects are allowed to "
+            "be passed to safe_sort as values"
+        )
+
+    sorter = None
+    ordered: AnyArrayLike
+
+    if (
+        not isinstance(values.dtype, ExtensionDtype)
+        and lib.infer_dtype(values, skipna=False) == "mixed-integer"
+    ):
+        ordered = _sort_mixed(values)
+    else:
+        try:
+            sorter = values.argsort()
+            ordered = values.take(sorter)
+        except (TypeError, decimal.InvalidOperation):
+            # Previous sorters failed or were not applicable, try `_sort_mixed`
+            # which would work, but which fails for special case of 1d arrays
+            # with tuples.
+            if values.size and isinstance(values[0], tuple):
+                # error: Argument 1 to "_sort_tuples" has incompatible type
+                # "Union[Index, ExtensionArray, ndarray[Any, Any]]"; expected
+                # "ndarray[Any, Any]"
+                ordered = _sort_tuples(values)  # type: ignore[arg-type]
+            else:
+                ordered = _sort_mixed(values)
+
+    # codes:
+
+    if codes is None:
+        return ordered
+
+    if not is_list_like(codes):
+        raise TypeError(
+            "Only list-like objects or None are allowed to "
+            "be passed to safe_sort as codes"
+        )
+    codes = ensure_platform_int(np.asarray(codes))
+
+    if not assume_unique and not len(unique(values)) == len(values):
+        raise ValueError("values should be unique if codes is not None")
+
+    if sorter is None:
+        # mixed types
+        # error: Argument 1 to "_get_hashtable_algo" has incompatible type
+        # "Union[Index, ExtensionArray, ndarray[Any, Any]]"; expected
+        # "ndarray[Any, Any]"
+        hash_klass, values = _get_hashtable_algo(values)  # type: ignore[arg-type]
+        t = hash_klass(len(values))
+        t.map_locations(values)
+        sorter = ensure_platform_int(t.lookup(ordered))
+
+    if use_na_sentinel:
+        # take_nd is faster, but only works for na_sentinels of -1
+        order2 = sorter.argsort()
+        if verify:
+            mask = (codes < -len(values)) | (codes >= len(values))
+            codes[mask] = 0
+        else:
+            mask = None
+        new_codes = take_nd(order2, codes, fill_value=-1)
+    else:
+        reverse_indexer = np.empty(len(sorter), dtype=int)
+        reverse_indexer.put(sorter, np.arange(len(sorter)))
+        # Out of bound indices will be masked with `-1` next, so we
+        # may deal with them here without performance loss using `mode='wrap'`
+        new_codes = reverse_indexer.take(codes, mode="wrap")
+
+        if use_na_sentinel:
+            mask = codes == -1
+            if verify:
+                mask = mask | (codes < -len(values)) | (codes >= len(values))
+
+    if use_na_sentinel and mask is not None:
+        np.putmask(new_codes, mask, -1)
+
+    return ordered, ensure_platform_int(new_codes)
+
+
+def _sort_mixed(values) -> AnyArrayLike:
+    """order ints before strings before nulls in 1d arrays"""
+    str_pos = np.array([isinstance(x, str) for x in values], dtype=bool)
+    null_pos = np.array([isna(x) for x in values], dtype=bool)
+    num_pos = ~str_pos & ~null_pos
+    str_argsort = np.argsort(values[str_pos])
+    num_argsort = np.argsort(values[num_pos])
+    # convert boolean arrays to positional indices, then order by underlying values
+    str_locs = str_pos.nonzero()[0].take(str_argsort)
+    num_locs = num_pos.nonzero()[0].take(num_argsort)
+    null_locs = null_pos.nonzero()[0]
+    locs = np.concatenate([num_locs, str_locs, null_locs])
+    return values.take(locs)
+
+
+def _sort_tuples(values: np.ndarray) -> np.ndarray:
+    """
+    Convert array of tuples (1d) to array of arrays (2d).
+    We need to keep the columns separately as they contain different types and
+    nans (can't use `np.sort` as it may fail when str and nan are mixed in a
+    column as types cannot be compared).
+    """
+    from pandas.core.internals.construction import to_arrays
+    from pandas.core.sorting import lexsort_indexer
+
+    arrays, _ = to_arrays(values, None)
+    indexer = lexsort_indexer(arrays, orders=True)
+    return values[indexer]
+
+
+def union_with_duplicates(
+    lvals: ArrayLike | Index, rvals: ArrayLike | Index
+) -> ArrayLike | Index:
+    """
+    Extracts the union from lvals and rvals with respect to duplicates and nans in
+    both arrays.
+
+    Parameters
+    ----------
+    lvals: np.ndarray or ExtensionArray
+        left values which is ordered in front.
+    rvals: np.ndarray or ExtensionArray
+        right values ordered after lvals.
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+        Containing the unsorted union of both arrays.
+
+    Notes
+    -----
+    Caller is responsible for ensuring lvals.dtype == rvals.dtype.
+    """
+    from pandas import Series
+
+    with warnings.catch_warnings():
+        # filter warning from object dtype inference; we will end up discarding
+        # the index here, so the deprecation does not affect the end result here.
+        warnings.filterwarnings(
+            "ignore",
+            "The behavior of value_counts with object-dtype is deprecated",
+            category=FutureWarning,
+        )
+        l_count = value_counts_internal(lvals, dropna=False)
+        r_count = value_counts_internal(rvals, dropna=False)
+    l_count, r_count = l_count.align(r_count, fill_value=0)
+    final_count = np.maximum(l_count.values, r_count.values)
+    final_count = Series(final_count, index=l_count.index, dtype="int", copy=False)
+    if isinstance(lvals, ABCMultiIndex) and isinstance(rvals, ABCMultiIndex):
+        unique_vals = lvals.append(rvals).unique()
+    else:
+        if isinstance(lvals, ABCIndex):
+            lvals = lvals._values
+        if isinstance(rvals, ABCIndex):
+            rvals = rvals._values
+        # error: List item 0 has incompatible type "Union[ExtensionArray,
+        # ndarray[Any, Any], Index]"; expected "Union[ExtensionArray,
+        # ndarray[Any, Any]]"
+        combined = concat_compat([lvals, rvals])  # type: ignore[list-item]
+        unique_vals = unique(combined)
+        unique_vals = ensure_wrapped_if_datetimelike(unique_vals)
+    repeats = final_count.reindex(unique_vals).values
+    return np.repeat(unique_vals, repeats)
+
+
+def map_array(
+    arr: ArrayLike,
+    mapper,
+    na_action: Literal["ignore"] | None = None,
+    convert: bool = True,
+) -> np.ndarray | ExtensionArray | Index:
+    """
+    Map values using an input mapping or function.
+
+    Parameters
+    ----------
+    mapper : function, dict, or Series
+        Mapping correspondence.
+    na_action : {None, 'ignore'}, default None
+        If 'ignore', propagate NA values, without passing them to the
+        mapping correspondence.
+    convert : bool, default True
+        Try to find better dtype for elementwise function results. If
+        False, leave as dtype=object.
+
+    Returns
+    -------
+    Union[ndarray, Index, ExtensionArray]
+        The output of the mapping function applied to the array.
+        If the function returns a tuple with more than one element
+        a MultiIndex will be returned.
+    """
+    if na_action not in (None, "ignore"):
+        msg = f"na_action must either be 'ignore' or None, {na_action} was passed"
+        raise ValueError(msg)
+
+    # we can fastpath dict/Series to an efficient map
+    # as we know that we are not going to have to yield
+    # python types
+    if is_dict_like(mapper):
+        if isinstance(mapper, dict) and hasattr(mapper, "__missing__"):
+            # If a dictionary subclass defines a default value method,
+            # convert mapper to a lookup function (GH #15999).
+            dict_with_default = mapper
+            mapper = lambda x: dict_with_default[
+                np.nan if isinstance(x, float) and np.isnan(x) else x
+            ]
+        else:
+            # Dictionary does not have a default. Thus it's safe to
+            # convert to an Series for efficiency.
+            # we specify the keys here to handle the
+            # possibility that they are tuples
+
+            # The return value of mapping with an empty mapper is
+            # expected to be pd.Series(np.nan, ...). As np.nan is
+            # of dtype float64 the return value of this method should
+            # be float64 as well
+            from pandas import Series
+
+            if len(mapper) == 0:
+                mapper = Series(mapper, dtype=np.float64)
+            else:
+                mapper = Series(mapper)
+
+    if isinstance(mapper, ABCSeries):
+        if na_action == "ignore":
+            mapper = mapper[mapper.index.notna()]
+
+        # Since values were input this means we came from either
+        # a dict or a series and mapper should be an index
+        indexer = mapper.index.get_indexer(arr)
+        new_values = take_nd(mapper._values, indexer)
+
+        return new_values
+
+    if not len(arr):
+        return arr.copy()
+
+    # we must convert to python types
+    values = arr.astype(object, copy=False)
+    if na_action is None:
+        return lib.map_infer(values, mapper, convert=convert)
+    else:
+        return lib.map_infer_mask(
+            values, mapper, mask=isna(values).view(np.uint8), convert=convert
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/api.py b/.venv/lib/python3.13/site-packages/pandas/core/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..2cfe5ffc0170d61bca248bca43dda7c2f082496f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/api.py
@@ -0,0 +1,140 @@
+from pandas._libs import (
+    NaT,
+    Period,
+    Timedelta,
+    Timestamp,
+)
+from pandas._libs.missing import NA
+
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+    IntervalDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    isnull,
+    notna,
+    notnull,
+)
+
+from pandas.core.algorithms import (
+    factorize,
+    unique,
+    value_counts,
+)
+from pandas.core.arrays import Categorical
+from pandas.core.arrays.boolean import BooleanDtype
+from pandas.core.arrays.floating import (
+    Float32Dtype,
+    Float64Dtype,
+)
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    Int16Dtype,
+    Int32Dtype,
+    Int64Dtype,
+    UInt8Dtype,
+    UInt16Dtype,
+    UInt32Dtype,
+    UInt64Dtype,
+)
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.construction import array
+from pandas.core.flags import Flags
+from pandas.core.groupby import (
+    Grouper,
+    NamedAgg,
+)
+from pandas.core.indexes.api import (
+    CategoricalIndex,
+    DatetimeIndex,
+    Index,
+    IntervalIndex,
+    MultiIndex,
+    PeriodIndex,
+    RangeIndex,
+    TimedeltaIndex,
+)
+from pandas.core.indexes.datetimes import (
+    bdate_range,
+    date_range,
+)
+from pandas.core.indexes.interval import (
+    Interval,
+    interval_range,
+)
+from pandas.core.indexes.period import period_range
+from pandas.core.indexes.timedeltas import timedelta_range
+from pandas.core.indexing import IndexSlice
+from pandas.core.series import Series
+from pandas.core.tools.datetimes import to_datetime
+from pandas.core.tools.numeric import to_numeric
+from pandas.core.tools.timedeltas import to_timedelta
+
+from pandas.io.formats.format import set_eng_float_format
+from pandas.tseries.offsets import DateOffset
+
+# DataFrame needs to be imported after NamedAgg to avoid a circular import
+from pandas.core.frame import DataFrame  # isort:skip
+
+__all__ = [
+    "array",
+    "ArrowDtype",
+    "bdate_range",
+    "BooleanDtype",
+    "Categorical",
+    "CategoricalDtype",
+    "CategoricalIndex",
+    "DataFrame",
+    "DateOffset",
+    "date_range",
+    "DatetimeIndex",
+    "DatetimeTZDtype",
+    "factorize",
+    "Flags",
+    "Float32Dtype",
+    "Float64Dtype",
+    "Grouper",
+    "Index",
+    "IndexSlice",
+    "Int16Dtype",
+    "Int32Dtype",
+    "Int64Dtype",
+    "Int8Dtype",
+    "Interval",
+    "IntervalDtype",
+    "IntervalIndex",
+    "interval_range",
+    "isna",
+    "isnull",
+    "MultiIndex",
+    "NA",
+    "NamedAgg",
+    "NaT",
+    "notna",
+    "notnull",
+    "Period",
+    "PeriodDtype",
+    "PeriodIndex",
+    "period_range",
+    "RangeIndex",
+    "Series",
+    "set_eng_float_format",
+    "StringDtype",
+    "Timedelta",
+    "TimedeltaIndex",
+    "timedelta_range",
+    "Timestamp",
+    "to_datetime",
+    "to_numeric",
+    "to_timedelta",
+    "UInt16Dtype",
+    "UInt32Dtype",
+    "UInt64Dtype",
+    "UInt8Dtype",
+    "unique",
+    "value_counts",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/apply.py b/.venv/lib/python3.13/site-packages/pandas/core/apply.py
new file mode 100644
index 0000000000000000000000000000000000000000..fafc9ee1b69283f75c9aa4b72768d1fd92f5a70a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/apply.py
@@ -0,0 +1,2057 @@
+from __future__ import annotations
+
+import abc
+from collections import defaultdict
+import functools
+from functools import partial
+import inspect
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import option_context
+
+from pandas._libs import lib
+from pandas._libs.internals import BlockValuesRefs
+from pandas._typing import (
+    AggFuncType,
+    AggFuncTypeBase,
+    AggFuncTypeDict,
+    AggObjType,
+    Axis,
+    AxisInt,
+    NDFrameT,
+    npt,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import SpecificationError
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import is_nested_object
+from pandas.core.dtypes.common import (
+    is_dict_like,
+    is_extension_array_dtype,
+    is_list_like,
+    is_numeric_dtype,
+    is_sequence,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCNDFrame,
+    ABCSeries,
+)
+
+from pandas.core._numba.executor import generate_apply_looper
+import pandas.core.common as com
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Hashable,
+        Iterable,
+        MutableMapping,
+        Sequence,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+    from pandas.core.groupby import GroupBy
+    from pandas.core.resample import Resampler
+    from pandas.core.window.rolling import BaseWindow
+
+
+ResType = dict[int, Any]
+
+
+def frame_apply(
+    obj: DataFrame,
+    func: AggFuncType,
+    axis: Axis = 0,
+    raw: bool = False,
+    result_type: str | None = None,
+    by_row: Literal[False, "compat"] = "compat",
+    engine: str = "python",
+    engine_kwargs: dict[str, bool] | None = None,
+    args=None,
+    kwargs=None,
+) -> FrameApply:
+    """construct and return a row or column based frame apply object"""
+    axis = obj._get_axis_number(axis)
+    klass: type[FrameApply]
+    if axis == 0:
+        klass = FrameRowApply
+    elif axis == 1:
+        klass = FrameColumnApply
+
+    _, func, _, _ = reconstruct_func(func, **kwargs)
+    assert func is not None
+
+    return klass(
+        obj,
+        func,
+        raw=raw,
+        result_type=result_type,
+        by_row=by_row,
+        engine=engine,
+        engine_kwargs=engine_kwargs,
+        args=args,
+        kwargs=kwargs,
+    )
+
+
+class Apply(metaclass=abc.ABCMeta):
+    axis: AxisInt
+
+    def __init__(
+        self,
+        obj: AggObjType,
+        func: AggFuncType,
+        raw: bool,
+        result_type: str | None,
+        *,
+        by_row: Literal[False, "compat", "_compat"] = "compat",
+        engine: str = "python",
+        engine_kwargs: dict[str, bool] | None = None,
+        args,
+        kwargs,
+    ) -> None:
+        self.obj = obj
+        self.raw = raw
+
+        assert by_row is False or by_row in ["compat", "_compat"]
+        self.by_row = by_row
+
+        self.args = args or ()
+        self.kwargs = kwargs or {}
+
+        self.engine = engine
+        self.engine_kwargs = {} if engine_kwargs is None else engine_kwargs
+
+        if result_type not in [None, "reduce", "broadcast", "expand"]:
+            raise ValueError(
+                "invalid value for result_type, must be one "
+                "of {None, 'reduce', 'broadcast', 'expand'}"
+            )
+
+        self.result_type = result_type
+
+        self.func = func
+
+    @abc.abstractmethod
+    def apply(self) -> DataFrame | Series:
+        pass
+
+    @abc.abstractmethod
+    def agg_or_apply_list_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        pass
+
+    @abc.abstractmethod
+    def agg_or_apply_dict_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        pass
+
+    def agg(self) -> DataFrame | Series | None:
+        """
+        Provide an implementation for the aggregators.
+
+        Returns
+        -------
+        Result of aggregation, or None if agg cannot be performed by
+        this method.
+        """
+        obj = self.obj
+        func = self.func
+        args = self.args
+        kwargs = self.kwargs
+
+        if isinstance(func, str):
+            return self.apply_str()
+
+        if is_dict_like(func):
+            return self.agg_dict_like()
+        elif is_list_like(func):
+            # we require a list, but not a 'str'
+            return self.agg_list_like()
+
+        if callable(func):
+            f = com.get_cython_func(func)
+            if f and not args and not kwargs:
+                warn_alias_replacement(obj, func, f)
+                return getattr(obj, f)()
+
+        # caller can react
+        return None
+
+    def transform(self) -> DataFrame | Series:
+        """
+        Transform a DataFrame or Series.
+
+        Returns
+        -------
+        DataFrame or Series
+            Result of applying ``func`` along the given axis of the
+            Series or DataFrame.
+
+        Raises
+        ------
+        ValueError
+            If the transform function fails or does not transform.
+        """
+        obj = self.obj
+        func = self.func
+        axis = self.axis
+        args = self.args
+        kwargs = self.kwargs
+
+        is_series = obj.ndim == 1
+
+        if obj._get_axis_number(axis) == 1:
+            assert not is_series
+            return obj.T.transform(func, 0, *args, **kwargs).T
+
+        if is_list_like(func) and not is_dict_like(func):
+            func = cast(list[AggFuncTypeBase], func)
+            # Convert func equivalent dict
+            if is_series:
+                func = {com.get_callable_name(v) or v: v for v in func}
+            else:
+                func = {col: func for col in obj}
+
+        if is_dict_like(func):
+            func = cast(AggFuncTypeDict, func)
+            return self.transform_dict_like(func)
+
+        # func is either str or callable
+        func = cast(AggFuncTypeBase, func)
+        try:
+            result = self.transform_str_or_callable(func)
+        except TypeError:
+            raise
+        except Exception as err:
+            raise ValueError("Transform function failed") from err
+
+        # Functions that transform may return empty Series/DataFrame
+        # when the dtype is not appropriate
+        if (
+            isinstance(result, (ABCSeries, ABCDataFrame))
+            and result.empty
+            and not obj.empty
+        ):
+            raise ValueError("Transform function failed")
+        # error: Argument 1 to "__get__" of "AxisProperty" has incompatible type
+        # "Union[Series, DataFrame, GroupBy[Any], SeriesGroupBy,
+        # DataFrameGroupBy, BaseWindow, Resampler]"; expected "Union[DataFrame,
+        # Series]"
+        if not isinstance(result, (ABCSeries, ABCDataFrame)) or not result.index.equals(
+            obj.index  # type: ignore[arg-type]
+        ):
+            raise ValueError("Function did not transform")
+
+        return result
+
+    def transform_dict_like(self, func) -> DataFrame:
+        """
+        Compute transform in the case of a dict-like func
+        """
+        from pandas.core.reshape.concat import concat
+
+        obj = self.obj
+        args = self.args
+        kwargs = self.kwargs
+
+        # transform is currently only for Series/DataFrame
+        assert isinstance(obj, ABCNDFrame)
+
+        if len(func) == 0:
+            raise ValueError("No transform functions were provided")
+
+        func = self.normalize_dictlike_arg("transform", obj, func)
+
+        results: dict[Hashable, DataFrame | Series] = {}
+        for name, how in func.items():
+            colg = obj._gotitem(name, ndim=1)
+            results[name] = colg.transform(how, 0, *args, **kwargs)
+        return concat(results, axis=1)
+
+    def transform_str_or_callable(self, func) -> DataFrame | Series:
+        """
+        Compute transform in the case of a string or callable func
+        """
+        obj = self.obj
+        args = self.args
+        kwargs = self.kwargs
+
+        if isinstance(func, str):
+            return self._apply_str(obj, func, *args, **kwargs)
+
+        if not args and not kwargs:
+            f = com.get_cython_func(func)
+            if f:
+                warn_alias_replacement(obj, func, f)
+                return getattr(obj, f)()
+
+        # Two possible ways to use a UDF - apply or call directly
+        try:
+            return obj.apply(func, args=args, **kwargs)
+        except Exception:
+            return func(obj, *args, **kwargs)
+
+    def agg_list_like(self) -> DataFrame | Series:
+        """
+        Compute aggregation in the case of a list-like argument.
+
+        Returns
+        -------
+        Result of aggregation.
+        """
+        return self.agg_or_apply_list_like(op_name="agg")
+
+    def compute_list_like(
+        self,
+        op_name: Literal["agg", "apply"],
+        selected_obj: Series | DataFrame,
+        kwargs: dict[str, Any],
+    ) -> tuple[list[Hashable] | Index, list[Any]]:
+        """
+        Compute agg/apply results for like-like input.
+
+        Parameters
+        ----------
+        op_name : {"agg", "apply"}
+            Operation being performed.
+        selected_obj : Series or DataFrame
+            Data to perform operation on.
+        kwargs : dict
+            Keyword arguments to pass to the functions.
+
+        Returns
+        -------
+        keys : list[Hashable] or Index
+            Index labels for result.
+        results : list
+            Data for result. When aggregating with a Series, this can contain any
+            Python objects.
+        """
+        func = cast(list[AggFuncTypeBase], self.func)
+        obj = self.obj
+
+        results = []
+        keys = []
+
+        # degenerate case
+        if selected_obj.ndim == 1:
+            for a in func:
+                colg = obj._gotitem(selected_obj.name, ndim=1, subset=selected_obj)
+                args = (
+                    [self.axis, *self.args]
+                    if include_axis(op_name, colg)
+                    else self.args
+                )
+                new_res = getattr(colg, op_name)(a, *args, **kwargs)
+                results.append(new_res)
+
+                # make sure we find a good name
+                name = com.get_callable_name(a) or a
+                keys.append(name)
+
+        else:
+            indices = []
+            for index, col in enumerate(selected_obj):
+                colg = obj._gotitem(col, ndim=1, subset=selected_obj.iloc[:, index])
+                args = (
+                    [self.axis, *self.args]
+                    if include_axis(op_name, colg)
+                    else self.args
+                )
+                new_res = getattr(colg, op_name)(func, *args, **kwargs)
+                results.append(new_res)
+                indices.append(index)
+            # error: Incompatible types in assignment (expression has type "Any |
+            # Index", variable has type "list[Any | Callable[..., Any] | str]")
+            keys = selected_obj.columns.take(indices)  # type: ignore[assignment]
+
+        return keys, results
+
+    def wrap_results_list_like(
+        self, keys: Iterable[Hashable], results: list[Series | DataFrame]
+    ):
+        from pandas.core.reshape.concat import concat
+
+        obj = self.obj
+
+        try:
+            return concat(results, keys=keys, axis=1, sort=False)
+        except TypeError as err:
+            # we are concatting non-NDFrame objects,
+            # e.g. a list of scalars
+            from pandas import Series
+
+            result = Series(results, index=keys, name=obj.name)
+            if is_nested_object(result):
+                raise ValueError(
+                    "cannot combine transform and aggregation operations"
+                ) from err
+            return result
+
+    def agg_dict_like(self) -> DataFrame | Series:
+        """
+        Compute aggregation in the case of a dict-like argument.
+
+        Returns
+        -------
+        Result of aggregation.
+        """
+        return self.agg_or_apply_dict_like(op_name="agg")
+
+    def compute_dict_like(
+        self,
+        op_name: Literal["agg", "apply"],
+        selected_obj: Series | DataFrame,
+        selection: Hashable | Sequence[Hashable],
+        kwargs: dict[str, Any],
+    ) -> tuple[list[Hashable], list[Any]]:
+        """
+        Compute agg/apply results for dict-like input.
+
+        Parameters
+        ----------
+        op_name : {"agg", "apply"}
+            Operation being performed.
+        selected_obj : Series or DataFrame
+            Data to perform operation on.
+        selection : hashable or sequence of hashables
+            Used by GroupBy, Window, and Resample if selection is applied to the object.
+        kwargs : dict
+            Keyword arguments to pass to the functions.
+
+        Returns
+        -------
+        keys : list[hashable]
+            Index labels for result.
+        results : list
+            Data for result. When aggregating with a Series, this can contain any
+            Python object.
+        """
+        from pandas.core.groupby.generic import (
+            DataFrameGroupBy,
+            SeriesGroupBy,
+        )
+
+        obj = self.obj
+        is_groupby = isinstance(obj, (DataFrameGroupBy, SeriesGroupBy))
+        func = cast(AggFuncTypeDict, self.func)
+        func = self.normalize_dictlike_arg(op_name, selected_obj, func)
+
+        is_non_unique_col = (
+            selected_obj.ndim == 2
+            and selected_obj.columns.nunique() < len(selected_obj.columns)
+        )
+
+        if selected_obj.ndim == 1:
+            # key only used for output
+            colg = obj._gotitem(selection, ndim=1)
+            results = [getattr(colg, op_name)(how, **kwargs) for _, how in func.items()]
+            keys = list(func.keys())
+        elif not is_groupby and is_non_unique_col:
+            # key used for column selection and output
+            # GH#51099
+            results = []
+            keys = []
+            for key, how in func.items():
+                indices = selected_obj.columns.get_indexer_for([key])
+                labels = selected_obj.columns.take(indices)
+                label_to_indices = defaultdict(list)
+                for index, label in zip(indices, labels):
+                    label_to_indices[label].append(index)
+
+                key_data = [
+                    getattr(selected_obj._ixs(indice, axis=1), op_name)(how, **kwargs)
+                    for label, indices in label_to_indices.items()
+                    for indice in indices
+                ]
+
+                keys += [key] * len(key_data)
+                results += key_data
+        else:
+            # key used for column selection and output
+            results = [
+                getattr(obj._gotitem(key, ndim=1), op_name)(how, **kwargs)
+                for key, how in func.items()
+            ]
+            keys = list(func.keys())
+
+        return keys, results
+
+    def wrap_results_dict_like(
+        self,
+        selected_obj: Series | DataFrame,
+        result_index: list[Hashable],
+        result_data: list,
+    ):
+        from pandas import Index
+        from pandas.core.reshape.concat import concat
+
+        obj = self.obj
+
+        # Avoid making two isinstance calls in all and any below
+        is_ndframe = [isinstance(r, ABCNDFrame) for r in result_data]
+
+        if all(is_ndframe):
+            results = dict(zip(result_index, result_data))
+            keys_to_use: Iterable[Hashable]
+            keys_to_use = [k for k in result_index if not results[k].empty]
+            # Have to check, if at least one DataFrame is not empty.
+            keys_to_use = keys_to_use if keys_to_use != [] else result_index
+            if selected_obj.ndim == 2:
+                # keys are columns, so we can preserve names
+                ktu = Index(keys_to_use)
+                ktu._set_names(selected_obj.columns.names)
+                keys_to_use = ktu
+
+            axis: AxisInt = 0 if isinstance(obj, ABCSeries) else 1
+            result = concat(
+                {k: results[k] for k in keys_to_use},
+                axis=axis,
+                keys=keys_to_use,
+            )
+        elif any(is_ndframe):
+            # There is a mix of NDFrames and scalars
+            raise ValueError(
+                "cannot perform both aggregation "
+                "and transformation operations "
+                "simultaneously"
+            )
+        else:
+            from pandas import Series
+
+            # we have a list of scalars
+            # GH 36212 use name only if obj is a series
+            if obj.ndim == 1:
+                obj = cast("Series", obj)
+                name = obj.name
+            else:
+                name = None
+
+            result = Series(result_data, index=result_index, name=name)
+
+        return result
+
+    def apply_str(self) -> DataFrame | Series:
+        """
+        Compute apply in case of a string.
+
+        Returns
+        -------
+        result: Series or DataFrame
+        """
+        # Caller is responsible for checking isinstance(self.f, str)
+        func = cast(str, self.func)
+
+        obj = self.obj
+
+        from pandas.core.groupby.generic import (
+            DataFrameGroupBy,
+            SeriesGroupBy,
+        )
+
+        # Support for `frame.transform('method')`
+        # Some methods (shift, etc.) require the axis argument, others
+        # don't, so inspect and insert if necessary.
+        method = getattr(obj, func, None)
+        if callable(method):
+            sig = inspect.getfullargspec(method)
+            arg_names = (*sig.args, *sig.kwonlyargs)
+            if self.axis != 0 and (
+                "axis" not in arg_names or func in ("corrwith", "skew")
+            ):
+                raise ValueError(f"Operation {func} does not support axis=1")
+            if "axis" in arg_names:
+                if isinstance(obj, (SeriesGroupBy, DataFrameGroupBy)):
+                    # Try to avoid FutureWarning for deprecated axis keyword;
+                    # If self.axis matches the axis we would get by not passing
+                    #  axis, we safely exclude the keyword.
+
+                    default_axis = 0
+                    if func in ["idxmax", "idxmin"]:
+                        # DataFrameGroupBy.idxmax, idxmin axis defaults to self.axis,
+                        # whereas other axis keywords default to 0
+                        default_axis = self.obj.axis
+
+                    if default_axis != self.axis:
+                        self.kwargs["axis"] = self.axis
+                else:
+                    self.kwargs["axis"] = self.axis
+        return self._apply_str(obj, func, *self.args, **self.kwargs)
+
+    def apply_list_or_dict_like(self) -> DataFrame | Series:
+        """
+        Compute apply in case of a list-like or dict-like.
+
+        Returns
+        -------
+        result: Series, DataFrame, or None
+            Result when self.func is a list-like or dict-like, None otherwise.
+        """
+
+        if self.engine == "numba":
+            raise NotImplementedError(
+                "The 'numba' engine doesn't support list-like/"
+                "dict likes of callables yet."
+            )
+
+        if self.axis == 1 and isinstance(self.obj, ABCDataFrame):
+            return self.obj.T.apply(self.func, 0, args=self.args, **self.kwargs).T
+
+        func = self.func
+        kwargs = self.kwargs
+
+        if is_dict_like(func):
+            result = self.agg_or_apply_dict_like(op_name="apply")
+        else:
+            result = self.agg_or_apply_list_like(op_name="apply")
+
+        result = reconstruct_and_relabel_result(result, func, **kwargs)
+
+        return result
+
+    def normalize_dictlike_arg(
+        self, how: str, obj: DataFrame | Series, func: AggFuncTypeDict
+    ) -> AggFuncTypeDict:
+        """
+        Handler for dict-like argument.
+
+        Ensures that necessary columns exist if obj is a DataFrame, and
+        that a nested renamer is not passed. Also normalizes to all lists
+        when values consists of a mix of list and non-lists.
+        """
+        assert how in ("apply", "agg", "transform")
+
+        # Can't use func.values(); wouldn't work for a Series
+        if (
+            how == "agg"
+            and isinstance(obj, ABCSeries)
+            and any(is_list_like(v) for _, v in func.items())
+        ) or (any(is_dict_like(v) for _, v in func.items())):
+            # GH 15931 - deprecation of renaming keys
+            raise SpecificationError("nested renamer is not supported")
+
+        if obj.ndim != 1:
+            # Check for missing columns on a frame
+            from pandas import Index
+
+            cols = Index(list(func.keys())).difference(obj.columns, sort=True)
+            if len(cols) > 0:
+                raise KeyError(f"Column(s) {list(cols)} do not exist")
+
+        aggregator_types = (list, tuple, dict)
+
+        # if we have a dict of any non-scalars
+        # eg. {'A' : ['mean']}, normalize all to
+        # be list-likes
+        # Cannot use func.values() because arg may be a Series
+        if any(isinstance(x, aggregator_types) for _, x in func.items()):
+            new_func: AggFuncTypeDict = {}
+            for k, v in func.items():
+                if not isinstance(v, aggregator_types):
+                    new_func[k] = [v]
+                else:
+                    new_func[k] = v
+            func = new_func
+        return func
+
+    def _apply_str(self, obj, func: str, *args, **kwargs):
+        """
+        if arg is a string, then try to operate on it:
+        - try to find a function (or attribute) on obj
+        - try to find a numpy function
+        - raise
+        """
+        assert isinstance(func, str)
+
+        if hasattr(obj, func):
+            f = getattr(obj, func)
+            if callable(f):
+                return f(*args, **kwargs)
+
+            # people may aggregate on a non-callable attribute
+            # but don't let them think they can pass args to it
+            assert len(args) == 0
+            assert len([kwarg for kwarg in kwargs if kwarg not in ["axis"]]) == 0
+            return f
+        elif hasattr(np, func) and hasattr(obj, "__array__"):
+            # in particular exclude Window
+            f = getattr(np, func)
+            return f(obj, *args, **kwargs)
+        else:
+            msg = f"'{func}' is not a valid function for '{type(obj).__name__}' object"
+            raise AttributeError(msg)
+
+
+class NDFrameApply(Apply):
+    """
+    Methods shared by FrameApply and SeriesApply but
+    not GroupByApply or ResamplerWindowApply
+    """
+
+    obj: DataFrame | Series
+
+    @property
+    def index(self) -> Index:
+        return self.obj.index
+
+    @property
+    def agg_axis(self) -> Index:
+        return self.obj._get_agg_axis(self.axis)
+
+    def agg_or_apply_list_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        obj = self.obj
+        kwargs = self.kwargs
+
+        if op_name == "apply":
+            if isinstance(self, FrameApply):
+                by_row = self.by_row
+
+            elif isinstance(self, SeriesApply):
+                by_row = "_compat" if self.by_row else False
+            else:
+                by_row = False
+            kwargs = {**kwargs, "by_row": by_row}
+
+        if getattr(obj, "axis", 0) == 1:
+            raise NotImplementedError("axis other than 0 is not supported")
+
+        keys, results = self.compute_list_like(op_name, obj, kwargs)
+        result = self.wrap_results_list_like(keys, results)
+        return result
+
+    def agg_or_apply_dict_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        assert op_name in ["agg", "apply"]
+        obj = self.obj
+
+        kwargs = {}
+        if op_name == "apply":
+            by_row = "_compat" if self.by_row else False
+            kwargs.update({"by_row": by_row})
+
+        if getattr(obj, "axis", 0) == 1:
+            raise NotImplementedError("axis other than 0 is not supported")
+
+        selection = None
+        result_index, result_data = self.compute_dict_like(
+            op_name, obj, selection, kwargs
+        )
+        result = self.wrap_results_dict_like(obj, result_index, result_data)
+        return result
+
+
+class FrameApply(NDFrameApply):
+    obj: DataFrame
+
+    def __init__(
+        self,
+        obj: AggObjType,
+        func: AggFuncType,
+        raw: bool,
+        result_type: str | None,
+        *,
+        by_row: Literal[False, "compat"] = False,
+        engine: str = "python",
+        engine_kwargs: dict[str, bool] | None = None,
+        args,
+        kwargs,
+    ) -> None:
+        if by_row is not False and by_row != "compat":
+            raise ValueError(f"by_row={by_row} not allowed")
+        super().__init__(
+            obj,
+            func,
+            raw,
+            result_type,
+            by_row=by_row,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    # ---------------------------------------------------------------
+    # Abstract Methods
+
+    @property
+    @abc.abstractmethod
+    def result_index(self) -> Index:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def result_columns(self) -> Index:
+        pass
+
+    @property
+    @abc.abstractmethod
+    def series_generator(self) -> Generator[Series, None, None]:
+        pass
+
+    @staticmethod
+    @functools.cache
+    @abc.abstractmethod
+    def generate_numba_apply_func(
+        func, nogil=True, nopython=True, parallel=False
+    ) -> Callable[[npt.NDArray, Index, Index], dict[int, Any]]:
+        pass
+
+    @abc.abstractmethod
+    def apply_with_numba(self):
+        pass
+
+    def validate_values_for_numba(self):
+        # Validate column dtyps all OK
+        for colname, dtype in self.obj.dtypes.items():
+            if not is_numeric_dtype(dtype):
+                raise ValueError(
+                    f"Column {colname} must have a numeric dtype. "
+                    f"Found '{dtype}' instead"
+                )
+            if is_extension_array_dtype(dtype):
+                raise ValueError(
+                    f"Column {colname} is backed by an extension array, "
+                    f"which is not supported by the numba engine."
+                )
+
+    @abc.abstractmethod
+    def wrap_results_for_axis(
+        self, results: ResType, res_index: Index
+    ) -> DataFrame | Series:
+        pass
+
+    # ---------------------------------------------------------------
+
+    @property
+    def res_columns(self) -> Index:
+        return self.result_columns
+
+    @property
+    def columns(self) -> Index:
+        return self.obj.columns
+
+    @cache_readonly
+    def values(self):
+        return self.obj.values
+
+    def apply(self) -> DataFrame | Series:
+        """compute the results"""
+
+        # dispatch to handle list-like or dict-like
+        if is_list_like(self.func):
+            if self.engine == "numba":
+                raise NotImplementedError(
+                    "the 'numba' engine doesn't support lists of callables yet"
+                )
+            return self.apply_list_or_dict_like()
+
+        # all empty
+        if len(self.columns) == 0 and len(self.index) == 0:
+            return self.apply_empty_result()
+
+        # string dispatch
+        if isinstance(self.func, str):
+            if self.engine == "numba":
+                raise NotImplementedError(
+                    "the 'numba' engine doesn't support using "
+                    "a string as the callable function"
+                )
+            return self.apply_str()
+
+        # ufunc
+        elif isinstance(self.func, np.ufunc):
+            if self.engine == "numba":
+                raise NotImplementedError(
+                    "the 'numba' engine doesn't support "
+                    "using a numpy ufunc as the callable function"
+                )
+            with np.errstate(all="ignore"):
+                results = self.obj._mgr.apply("apply", func=self.func)
+            # _constructor will retain self.index and self.columns
+            return self.obj._constructor_from_mgr(results, axes=results.axes)
+
+        # broadcasting
+        if self.result_type == "broadcast":
+            if self.engine == "numba":
+                raise NotImplementedError(
+                    "the 'numba' engine doesn't support result_type='broadcast'"
+                )
+            return self.apply_broadcast(self.obj)
+
+        # one axis empty
+        elif not all(self.obj.shape):
+            return self.apply_empty_result()
+
+        # raw
+        elif self.raw:
+            return self.apply_raw(engine=self.engine, engine_kwargs=self.engine_kwargs)
+
+        return self.apply_standard()
+
+    def agg(self):
+        obj = self.obj
+        axis = self.axis
+
+        # TODO: Avoid having to change state
+        self.obj = self.obj if self.axis == 0 else self.obj.T
+        self.axis = 0
+
+        result = None
+        try:
+            result = super().agg()
+        finally:
+            self.obj = obj
+            self.axis = axis
+
+        if axis == 1:
+            result = result.T if result is not None else result
+
+        if result is None:
+            result = self.obj.apply(self.func, axis, args=self.args, **self.kwargs)
+
+        return result
+
+    def apply_empty_result(self):
+        """
+        we have an empty result; at least 1 axis is 0
+
+        we will try to apply the function to an empty
+        series in order to see if this is a reduction function
+        """
+        assert callable(self.func)
+
+        # we are not asked to reduce or infer reduction
+        # so just return a copy of the existing object
+        if self.result_type not in ["reduce", None]:
+            return self.obj.copy()
+
+        # we may need to infer
+        should_reduce = self.result_type == "reduce"
+
+        from pandas import Series
+
+        if not should_reduce:
+            try:
+                if self.axis == 0:
+                    r = self.func(
+                        Series([], dtype=np.float64), *self.args, **self.kwargs
+                    )
+                else:
+                    r = self.func(
+                        Series(index=self.columns, dtype=np.float64),
+                        *self.args,
+                        **self.kwargs,
+                    )
+            except Exception:
+                pass
+            else:
+                should_reduce = not isinstance(r, Series)
+
+        if should_reduce:
+            if len(self.agg_axis):
+                r = self.func(Series([], dtype=np.float64), *self.args, **self.kwargs)
+            else:
+                r = np.nan
+
+            return self.obj._constructor_sliced(r, index=self.agg_axis)
+        else:
+            return self.obj.copy()
+
+    def apply_raw(self, engine="python", engine_kwargs=None):
+        """apply to the values as a numpy array"""
+
+        def wrap_function(func):
+            """
+            Wrap user supplied function to work around numpy issue.
+
+            see https://github.com/numpy/numpy/issues/8352
+            """
+
+            def wrapper(*args, **kwargs):
+                result = func(*args, **kwargs)
+                if isinstance(result, str):
+                    result = np.array(result, dtype=object)
+                return result
+
+            return wrapper
+
+        if engine == "numba":
+            engine_kwargs = {} if engine_kwargs is None else engine_kwargs
+
+            # error: Argument 1 to "__call__" of "_lru_cache_wrapper" has
+            # incompatible type "Callable[..., Any] | str | list[Callable
+            # [..., Any] | str] | dict[Hashable,Callable[..., Any] | str |
+            # list[Callable[..., Any] | str]]"; expected "Hashable"
+            nb_looper = generate_apply_looper(
+                self.func, **engine_kwargs  # type: ignore[arg-type]
+            )
+            result = nb_looper(self.values, self.axis)
+            # If we made the result 2-D, squeeze it back to 1-D
+            result = np.squeeze(result)
+        else:
+            result = np.apply_along_axis(
+                wrap_function(self.func),
+                self.axis,
+                self.values,
+                *self.args,
+                **self.kwargs,
+            )
+
+        # TODO: mixed type case
+        if result.ndim == 2:
+            return self.obj._constructor(result, index=self.index, columns=self.columns)
+        else:
+            return self.obj._constructor_sliced(result, index=self.agg_axis)
+
+    def apply_broadcast(self, target: DataFrame) -> DataFrame:
+        assert callable(self.func)
+
+        result_values = np.empty_like(target.values)
+
+        # axis which we want to compare compliance
+        result_compare = target.shape[0]
+
+        for i, col in enumerate(target.columns):
+            res = self.func(target[col], *self.args, **self.kwargs)
+            ares = np.asarray(res).ndim
+
+            # must be a scalar or 1d
+            if ares > 1:
+                raise ValueError("too many dims to broadcast")
+            if ares == 1:
+                # must match return dim
+                if result_compare != len(res):
+                    raise ValueError("cannot broadcast result")
+
+            result_values[:, i] = res
+
+        # we *always* preserve the original index / columns
+        result = self.obj._constructor(
+            result_values, index=target.index, columns=target.columns
+        )
+        return result
+
+    def apply_standard(self):
+        if self.engine == "python":
+            results, res_index = self.apply_series_generator()
+        else:
+            results, res_index = self.apply_series_numba()
+
+        # wrap results
+        return self.wrap_results(results, res_index)
+
+    def apply_series_generator(self) -> tuple[ResType, Index]:
+        assert callable(self.func)
+
+        series_gen = self.series_generator
+        res_index = self.result_index
+
+        results = {}
+
+        with option_context("mode.chained_assignment", None):
+            for i, v in enumerate(series_gen):
+                # ignore SettingWithCopy here in case the user mutates
+                results[i] = self.func(v, *self.args, **self.kwargs)
+                if isinstance(results[i], ABCSeries):
+                    # If we have a view on v, we need to make a copy because
+                    #  series_generator will swap out the underlying data
+                    results[i] = results[i].copy(deep=False)
+
+        return results, res_index
+
+    def apply_series_numba(self):
+        if self.engine_kwargs.get("parallel", False):
+            raise NotImplementedError(
+                "Parallel apply is not supported when raw=False and engine='numba'"
+            )
+        if not self.obj.index.is_unique or not self.columns.is_unique:
+            raise NotImplementedError(
+                "The index/columns must be unique when raw=False and engine='numba'"
+            )
+        self.validate_values_for_numba()
+        results = self.apply_with_numba()
+        return results, self.result_index
+
+    def wrap_results(self, results: ResType, res_index: Index) -> DataFrame | Series:
+        from pandas import Series
+
+        # see if we can infer the results
+        if len(results) > 0 and 0 in results and is_sequence(results[0]):
+            return self.wrap_results_for_axis(results, res_index)
+
+        # dict of scalars
+
+        # the default dtype of an empty Series is `object`, but this
+        # code can be hit by df.mean() where the result should have dtype
+        # float64 even if it's an empty Series.
+        constructor_sliced = self.obj._constructor_sliced
+        if len(results) == 0 and constructor_sliced is Series:
+            result = constructor_sliced(results, dtype=np.float64)
+        else:
+            result = constructor_sliced(results)
+        result.index = res_index
+
+        return result
+
+    def apply_str(self) -> DataFrame | Series:
+        # Caller is responsible for checking isinstance(self.func, str)
+        # TODO: GH#39993 - Avoid special-casing by replacing with lambda
+        if self.func == "size":
+            # Special-cased because DataFrame.size returns a single scalar
+            obj = self.obj
+            value = obj.shape[self.axis]
+            return obj._constructor_sliced(value, index=self.agg_axis)
+        return super().apply_str()
+
+
+class FrameRowApply(FrameApply):
+    axis: AxisInt = 0
+
+    @property
+    def series_generator(self) -> Generator[Series, None, None]:
+        return (self.obj._ixs(i, axis=1) for i in range(len(self.columns)))
+
+    @staticmethod
+    @functools.cache
+    def generate_numba_apply_func(
+        func, nogil=True, nopython=True, parallel=False
+    ) -> Callable[[npt.NDArray, Index, Index], dict[int, Any]]:
+        numba = import_optional_dependency("numba")
+        from pandas import Series
+
+        # Import helper from extensions to cast string object -> np strings
+        # Note: This also has the side effect of loading our numba extensions
+        from pandas.core._numba.extensions import maybe_cast_str
+
+        jitted_udf = numba.extending.register_jitable(func)
+
+        # Currently the parallel argument doesn't get passed through here
+        # (it's disabled) since the dicts in numba aren't thread-safe.
+        @numba.jit(nogil=nogil, nopython=nopython, parallel=parallel)
+        def numba_func(values, col_names, df_index):
+            results = {}
+            for j in range(values.shape[1]):
+                # Create the series
+                ser = Series(
+                    values[:, j], index=df_index, name=maybe_cast_str(col_names[j])
+                )
+                results[j] = jitted_udf(ser)
+            return results
+
+        return numba_func
+
+    def apply_with_numba(self) -> dict[int, Any]:
+        nb_func = self.generate_numba_apply_func(
+            cast(Callable, self.func), **self.engine_kwargs
+        )
+        from pandas.core._numba.extensions import set_numba_data
+
+        index = self.obj.index
+        columns = self.obj.columns
+
+        # Convert from numba dict to regular dict
+        # Our isinstance checks in the df constructor don't pass for numbas typed dict
+        with set_numba_data(index) as index, set_numba_data(columns) as columns:
+            res = dict(nb_func(self.values, columns, index))
+        return res
+
+    @property
+    def result_index(self) -> Index:
+        return self.columns
+
+    @property
+    def result_columns(self) -> Index:
+        return self.index
+
+    def wrap_results_for_axis(
+        self, results: ResType, res_index: Index
+    ) -> DataFrame | Series:
+        """return the results for the rows"""
+
+        if self.result_type == "reduce":
+            # e.g. test_apply_dict GH#8735
+            res = self.obj._constructor_sliced(results)
+            res.index = res_index
+            return res
+
+        elif self.result_type is None and all(
+            isinstance(x, dict) for x in results.values()
+        ):
+            # Our operation was a to_dict op e.g.
+            #  test_apply_dict GH#8735, test_apply_reduce_to_dict GH#25196 #37544
+            res = self.obj._constructor_sliced(results)
+            res.index = res_index
+            return res
+
+        try:
+            result = self.obj._constructor(data=results)
+        except ValueError as err:
+            if "All arrays must be of the same length" in str(err):
+                # e.g. result = [[2, 3], [1.5], ['foo', 'bar']]
+                #  see test_agg_listlike_result GH#29587
+                res = self.obj._constructor_sliced(results)
+                res.index = res_index
+                return res
+            else:
+                raise
+
+        if not isinstance(results[0], ABCSeries):
+            if len(result.index) == len(self.res_columns):
+                result.index = self.res_columns
+
+        if len(result.columns) == len(res_index):
+            result.columns = res_index
+
+        return result
+
+
+class FrameColumnApply(FrameApply):
+    axis: AxisInt = 1
+
+    def apply_broadcast(self, target: DataFrame) -> DataFrame:
+        result = super().apply_broadcast(target.T)
+        return result.T
+
+    @property
+    def series_generator(self) -> Generator[Series, None, None]:
+        values = self.values
+        values = ensure_wrapped_if_datetimelike(values)
+        assert len(values) > 0
+
+        # We create one Series object, and will swap out the data inside
+        #  of it.  Kids: don't do this at home.
+        ser = self.obj._ixs(0, axis=0)
+        mgr = ser._mgr
+
+        is_view = mgr.blocks[0].refs.has_reference()  # type: ignore[union-attr]
+
+        if isinstance(ser.dtype, ExtensionDtype):
+            # values will be incorrect for this block
+            # TODO(EA2D): special case would be unnecessary with 2D EAs
+            obj = self.obj
+            for i in range(len(obj)):
+                yield obj._ixs(i, axis=0)
+
+        else:
+            for arr, name in zip(values, self.index):
+                # GH#35462 re-pin mgr in case setitem changed it
+                ser._mgr = mgr
+                mgr.set_values(arr)
+                object.__setattr__(ser, "_name", name)
+                if not is_view:
+                    # In apply_series_generator we store the a shallow copy of the
+                    # result, which potentially increases the ref count of this reused
+                    # `ser` object (depending on the result of the applied function)
+                    # -> if that happened and `ser` is already a copy, then we reset
+                    # the refs here to avoid triggering a unnecessary CoW inside the
+                    # applied function (https://github.com/pandas-dev/pandas/pull/56212)
+                    mgr.blocks[0].refs = BlockValuesRefs(mgr.blocks[0])  # type: ignore[union-attr]
+                yield ser
+
+    @staticmethod
+    @functools.cache
+    def generate_numba_apply_func(
+        func, nogil=True, nopython=True, parallel=False
+    ) -> Callable[[npt.NDArray, Index, Index], dict[int, Any]]:
+        numba = import_optional_dependency("numba")
+        from pandas import Series
+        from pandas.core._numba.extensions import maybe_cast_str
+
+        jitted_udf = numba.extending.register_jitable(func)
+
+        @numba.jit(nogil=nogil, nopython=nopython, parallel=parallel)
+        def numba_func(values, col_names_index, index):
+            results = {}
+            # Currently the parallel argument doesn't get passed through here
+            # (it's disabled) since the dicts in numba aren't thread-safe.
+            for i in range(values.shape[0]):
+                # Create the series
+                # TODO: values corrupted without the copy
+                ser = Series(
+                    values[i].copy(),
+                    index=col_names_index,
+                    name=maybe_cast_str(index[i]),
+                )
+                results[i] = jitted_udf(ser)
+
+            return results
+
+        return numba_func
+
+    def apply_with_numba(self) -> dict[int, Any]:
+        nb_func = self.generate_numba_apply_func(
+            cast(Callable, self.func), **self.engine_kwargs
+        )
+
+        from pandas.core._numba.extensions import set_numba_data
+
+        # Convert from numba dict to regular dict
+        # Our isinstance checks in the df constructor don't pass for numbas typed dict
+        with set_numba_data(self.obj.index) as index, set_numba_data(
+            self.columns
+        ) as columns:
+            res = dict(nb_func(self.values, columns, index))
+
+        return res
+
+    @property
+    def result_index(self) -> Index:
+        return self.index
+
+    @property
+    def result_columns(self) -> Index:
+        return self.columns
+
+    def wrap_results_for_axis(
+        self, results: ResType, res_index: Index
+    ) -> DataFrame | Series:
+        """return the results for the columns"""
+        result: DataFrame | Series
+
+        # we have requested to expand
+        if self.result_type == "expand":
+            result = self.infer_to_same_shape(results, res_index)
+
+        # we have a non-series and don't want inference
+        elif not isinstance(results[0], ABCSeries):
+            result = self.obj._constructor_sliced(results)
+            result.index = res_index
+
+        # we may want to infer results
+        else:
+            result = self.infer_to_same_shape(results, res_index)
+
+        return result
+
+    def infer_to_same_shape(self, results: ResType, res_index: Index) -> DataFrame:
+        """infer the results to the same shape as the input object"""
+        result = self.obj._constructor(data=results)
+        result = result.T
+
+        # set the index
+        result.index = res_index
+
+        # infer dtypes
+        result = result.infer_objects(copy=False)
+
+        return result
+
+
+class SeriesApply(NDFrameApply):
+    obj: Series
+    axis: AxisInt = 0
+    by_row: Literal[False, "compat", "_compat"]  # only relevant for apply()
+
+    def __init__(
+        self,
+        obj: Series,
+        func: AggFuncType,
+        *,
+        convert_dtype: bool | lib.NoDefault = lib.no_default,
+        by_row: Literal[False, "compat", "_compat"] = "compat",
+        args,
+        kwargs,
+    ) -> None:
+        if convert_dtype is lib.no_default:
+            convert_dtype = True
+        else:
+            warnings.warn(
+                "the convert_dtype parameter is deprecated and will be removed in a "
+                "future version.  Do ``ser.astype(object).apply()`` "
+                "instead if you want ``convert_dtype=False``.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        self.convert_dtype = convert_dtype
+
+        super().__init__(
+            obj,
+            func,
+            raw=False,
+            result_type=None,
+            by_row=by_row,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    def apply(self) -> DataFrame | Series:
+        obj = self.obj
+
+        if len(obj) == 0:
+            return self.apply_empty_result()
+
+        # dispatch to handle list-like or dict-like
+        if is_list_like(self.func):
+            return self.apply_list_or_dict_like()
+
+        if isinstance(self.func, str):
+            # if we are a string, try to dispatch
+            return self.apply_str()
+
+        if self.by_row == "_compat":
+            return self.apply_compat()
+
+        # self.func is Callable
+        return self.apply_standard()
+
+    def agg(self):
+        result = super().agg()
+        if result is None:
+            obj = self.obj
+            func = self.func
+            # string, list-like, and dict-like are entirely handled in super
+            assert callable(func)
+
+            # GH53325: The setup below is just to keep current behavior while emitting a
+            # deprecation message. In the future this will all be replaced with a simple
+            # `result = f(self.obj, *self.args, **self.kwargs)`.
+            try:
+                result = obj.apply(func, args=self.args, **self.kwargs)
+            except (ValueError, AttributeError, TypeError):
+                result = func(obj, *self.args, **self.kwargs)
+            else:
+                msg = (
+                    f"using {func} in {type(obj).__name__}.agg cannot aggregate and "
+                    f"has been deprecated. Use {type(obj).__name__}.transform to "
+                    f"keep behavior unchanged."
+                )
+                warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+
+        return result
+
+    def apply_empty_result(self) -> Series:
+        obj = self.obj
+        return obj._constructor(dtype=obj.dtype, index=obj.index).__finalize__(
+            obj, method="apply"
+        )
+
+    def apply_compat(self):
+        """compat apply method for funcs in listlikes and dictlikes.
+
+         Used for each callable when giving listlikes and dictlikes of callables to
+         apply. Needed for compatibility with Pandas < v2.1.
+
+        .. versionadded:: 2.1.0
+        """
+        obj = self.obj
+        func = self.func
+
+        if callable(func):
+            f = com.get_cython_func(func)
+            if f and not self.args and not self.kwargs:
+                return obj.apply(func, by_row=False)
+
+        try:
+            result = obj.apply(func, by_row="compat")
+        except (ValueError, AttributeError, TypeError):
+            result = obj.apply(func, by_row=False)
+        return result
+
+    def apply_standard(self) -> DataFrame | Series:
+        # caller is responsible for ensuring that f is Callable
+        func = cast(Callable, self.func)
+        obj = self.obj
+
+        if isinstance(func, np.ufunc):
+            with np.errstate(all="ignore"):
+                return func(obj, *self.args, **self.kwargs)
+        elif not self.by_row:
+            return func(obj, *self.args, **self.kwargs)
+
+        if self.args or self.kwargs:
+            # _map_values does not support args/kwargs
+            def curried(x):
+                return func(x, *self.args, **self.kwargs)
+
+        else:
+            curried = func
+
+        # row-wise access
+        # apply doesn't have a `na_action` keyword and for backward compat reasons
+        # we need to give `na_action="ignore"` for categorical data.
+        # TODO: remove the `na_action="ignore"` when that default has been changed in
+        #  Categorical (GH51645).
+        action = "ignore" if isinstance(obj.dtype, CategoricalDtype) else None
+        mapped = obj._map_values(
+            mapper=curried, na_action=action, convert=self.convert_dtype
+        )
+
+        if len(mapped) and isinstance(mapped[0], ABCSeries):
+            # GH#43986 Need to do list(mapped) in order to get treated as nested
+            #  See also GH#25959 regarding EA support
+            return obj._constructor_expanddim(list(mapped), index=obj.index)
+        else:
+            return obj._constructor(mapped, index=obj.index).__finalize__(
+                obj, method="apply"
+            )
+
+
+class GroupByApply(Apply):
+    obj: GroupBy | Resampler | BaseWindow
+
+    def __init__(
+        self,
+        obj: GroupBy[NDFrameT],
+        func: AggFuncType,
+        *,
+        args,
+        kwargs,
+    ) -> None:
+        kwargs = kwargs.copy()
+        self.axis = obj.obj._get_axis_number(kwargs.get("axis", 0))
+        super().__init__(
+            obj,
+            func,
+            raw=False,
+            result_type=None,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    def apply(self):
+        raise NotImplementedError
+
+    def transform(self):
+        raise NotImplementedError
+
+    def agg_or_apply_list_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        obj = self.obj
+        kwargs = self.kwargs
+        if op_name == "apply":
+            kwargs = {**kwargs, "by_row": False}
+
+        if getattr(obj, "axis", 0) == 1:
+            raise NotImplementedError("axis other than 0 is not supported")
+
+        if obj._selected_obj.ndim == 1:
+            # For SeriesGroupBy this matches _obj_with_exclusions
+            selected_obj = obj._selected_obj
+        else:
+            selected_obj = obj._obj_with_exclusions
+
+        # Only set as_index=True on groupby objects, not Window or Resample
+        # that inherit from this class.
+        with com.temp_setattr(
+            obj, "as_index", True, condition=hasattr(obj, "as_index")
+        ):
+            keys, results = self.compute_list_like(op_name, selected_obj, kwargs)
+        result = self.wrap_results_list_like(keys, results)
+        return result
+
+    def agg_or_apply_dict_like(
+        self, op_name: Literal["agg", "apply"]
+    ) -> DataFrame | Series:
+        from pandas.core.groupby.generic import (
+            DataFrameGroupBy,
+            SeriesGroupBy,
+        )
+
+        assert op_name in ["agg", "apply"]
+
+        obj = self.obj
+        kwargs = {}
+        if op_name == "apply":
+            by_row = "_compat" if self.by_row else False
+            kwargs.update({"by_row": by_row})
+
+        if getattr(obj, "axis", 0) == 1:
+            raise NotImplementedError("axis other than 0 is not supported")
+
+        selected_obj = obj._selected_obj
+        selection = obj._selection
+
+        is_groupby = isinstance(obj, (DataFrameGroupBy, SeriesGroupBy))
+
+        # Numba Groupby engine/engine-kwargs passthrough
+        if is_groupby:
+            engine = self.kwargs.get("engine", None)
+            engine_kwargs = self.kwargs.get("engine_kwargs", None)
+            kwargs.update({"engine": engine, "engine_kwargs": engine_kwargs})
+
+        with com.temp_setattr(
+            obj, "as_index", True, condition=hasattr(obj, "as_index")
+        ):
+            result_index, result_data = self.compute_dict_like(
+                op_name, selected_obj, selection, kwargs
+            )
+        result = self.wrap_results_dict_like(selected_obj, result_index, result_data)
+        return result
+
+
+class ResamplerWindowApply(GroupByApply):
+    axis: AxisInt = 0
+    obj: Resampler | BaseWindow
+
+    def __init__(
+        self,
+        obj: Resampler | BaseWindow,
+        func: AggFuncType,
+        *,
+        args,
+        kwargs,
+    ) -> None:
+        super(GroupByApply, self).__init__(
+            obj,
+            func,
+            raw=False,
+            result_type=None,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    def apply(self):
+        raise NotImplementedError
+
+    def transform(self):
+        raise NotImplementedError
+
+
+def reconstruct_func(
+    func: AggFuncType | None, **kwargs
+) -> tuple[bool, AggFuncType, tuple[str, ...] | None, npt.NDArray[np.intp] | None]:
+    """
+    This is the internal function to reconstruct func given if there is relabeling
+    or not and also normalize the keyword to get new order of columns.
+
+    If named aggregation is applied, `func` will be None, and kwargs contains the
+    column and aggregation function information to be parsed;
+    If named aggregation is not applied, `func` is either string (e.g. 'min') or
+    Callable, or list of them (e.g. ['min', np.max]), or the dictionary of column name
+    and str/Callable/list of them (e.g. {'A': 'min'}, or {'A': [np.min, lambda x: x]})
+
+    If relabeling is True, will return relabeling, reconstructed func, column
+    names, and the reconstructed order of columns.
+    If relabeling is False, the columns and order will be None.
+
+    Parameters
+    ----------
+    func: agg function (e.g. 'min' or Callable) or list of agg functions
+        (e.g. ['min', np.max]) or dictionary (e.g. {'A': ['min', np.max]}).
+    **kwargs: dict, kwargs used in is_multi_agg_with_relabel and
+        normalize_keyword_aggregation function for relabelling
+
+    Returns
+    -------
+    relabelling: bool, if there is relabelling or not
+    func: normalized and mangled func
+    columns: tuple of column names
+    order: array of columns indices
+
+    Examples
+    --------
+    >>> reconstruct_func(None, **{"foo": ("col", "min")})
+    (True, defaultdict(, {'col': ['min']}), ('foo',), array([0]))
+
+    >>> reconstruct_func("min")
+    (False, 'min', None, None)
+    """
+    relabeling = func is None and is_multi_agg_with_relabel(**kwargs)
+    columns: tuple[str, ...] | None = None
+    order: npt.NDArray[np.intp] | None = None
+
+    if not relabeling:
+        if isinstance(func, list) and len(func) > len(set(func)):
+            # GH 28426 will raise error if duplicated function names are used and
+            # there is no reassigned name
+            raise SpecificationError(
+                "Function names must be unique if there is no new column names "
+                "assigned"
+            )
+        if func is None:
+            # nicer error message
+            raise TypeError("Must provide 'func' or tuples of '(column, aggfunc).")
+
+    if relabeling:
+        # error: Incompatible types in assignment (expression has type
+        # "MutableMapping[Hashable, list[Callable[..., Any] | str]]", variable has type
+        # "Callable[..., Any] | str | list[Callable[..., Any] | str] |
+        # MutableMapping[Hashable, Callable[..., Any] | str | list[Callable[..., Any] |
+        # str]] | None")
+        func, columns, order = normalize_keyword_aggregation(  # type: ignore[assignment]
+            kwargs
+        )
+    assert func is not None
+
+    return relabeling, func, columns, order
+
+
+def is_multi_agg_with_relabel(**kwargs) -> bool:
+    """
+    Check whether kwargs passed to .agg look like multi-agg with relabeling.
+
+    Parameters
+    ----------
+    **kwargs : dict
+
+    Returns
+    -------
+    bool
+
+    Examples
+    --------
+    >>> is_multi_agg_with_relabel(a="max")
+    False
+    >>> is_multi_agg_with_relabel(a_max=("a", "max"), a_min=("a", "min"))
+    True
+    >>> is_multi_agg_with_relabel()
+    False
+    """
+    return all(isinstance(v, tuple) and len(v) == 2 for v in kwargs.values()) and (
+        len(kwargs) > 0
+    )
+
+
+def normalize_keyword_aggregation(
+    kwargs: dict,
+) -> tuple[
+    MutableMapping[Hashable, list[AggFuncTypeBase]],
+    tuple[str, ...],
+    npt.NDArray[np.intp],
+]:
+    """
+    Normalize user-provided "named aggregation" kwargs.
+    Transforms from the new ``Mapping[str, NamedAgg]`` style kwargs
+    to the old Dict[str, List[scalar]]].
+
+    Parameters
+    ----------
+    kwargs : dict
+
+    Returns
+    -------
+    aggspec : dict
+        The transformed kwargs.
+    columns : tuple[str, ...]
+        The user-provided keys.
+    col_idx_order : List[int]
+        List of columns indices.
+
+    Examples
+    --------
+    >>> normalize_keyword_aggregation({"output": ("input", "sum")})
+    (defaultdict(, {'input': ['sum']}), ('output',), array([0]))
+    """
+    from pandas.core.indexes.base import Index
+
+    # Normalize the aggregation functions as Mapping[column, List[func]],
+    # process normally, then fixup the names.
+    # TODO: aggspec type: typing.Dict[str, List[AggScalar]]
+    aggspec = defaultdict(list)
+    order = []
+    columns, pairs = list(zip(*kwargs.items()))
+
+    for column, aggfunc in pairs:
+        aggspec[column].append(aggfunc)
+        order.append((column, com.get_callable_name(aggfunc) or aggfunc))
+
+    # uniquify aggfunc name if duplicated in order list
+    uniquified_order = _make_unique_kwarg_list(order)
+
+    # GH 25719, due to aggspec will change the order of assigned columns in aggregation
+    # uniquified_aggspec will store uniquified order list and will compare it with order
+    # based on index
+    aggspec_order = [
+        (column, com.get_callable_name(aggfunc) or aggfunc)
+        for column, aggfuncs in aggspec.items()
+        for aggfunc in aggfuncs
+    ]
+    uniquified_aggspec = _make_unique_kwarg_list(aggspec_order)
+
+    # get the new index of columns by comparison
+    col_idx_order = Index(uniquified_aggspec).get_indexer(uniquified_order)
+    return aggspec, columns, col_idx_order
+
+
+def _make_unique_kwarg_list(
+    seq: Sequence[tuple[Any, Any]]
+) -> Sequence[tuple[Any, Any]]:
+    """
+    Uniquify aggfunc name of the pairs in the order list
+
+    Examples:
+    --------
+    >>> kwarg_list = [('a', ''), ('a', ''), ('b', '')]
+    >>> _make_unique_kwarg_list(kwarg_list)
+    [('a', '_0'), ('a', '_1'), ('b', '')]
+    """
+    return [
+        (pair[0], f"{pair[1]}_{seq[:i].count(pair)}") if seq.count(pair) > 1 else pair
+        for i, pair in enumerate(seq)
+    ]
+
+
+def relabel_result(
+    result: DataFrame | Series,
+    func: dict[str, list[Callable | str]],
+    columns: Iterable[Hashable],
+    order: Iterable[int],
+) -> dict[Hashable, Series]:
+    """
+    Internal function to reorder result if relabelling is True for
+    dataframe.agg, and return the reordered result in dict.
+
+    Parameters:
+    ----------
+    result: Result from aggregation
+    func: Dict of (column name, funcs)
+    columns: New columns name for relabelling
+    order: New order for relabelling
+
+    Examples
+    --------
+    >>> from pandas.core.apply import relabel_result
+    >>> result = pd.DataFrame(
+    ...     {"A": [np.nan, 2, np.nan], "C": [6, np.nan, np.nan], "B": [np.nan, 4, 2.5]},
+    ...     index=["max", "mean", "min"]
+    ... )
+    >>> funcs = {"A": ["max"], "C": ["max"], "B": ["mean", "min"]}
+    >>> columns = ("foo", "aab", "bar", "dat")
+    >>> order = [0, 1, 2, 3]
+    >>> result_in_dict = relabel_result(result, funcs, columns, order)
+    >>> pd.DataFrame(result_in_dict, index=columns)
+           A    C    B
+    foo  2.0  NaN  NaN
+    aab  NaN  6.0  NaN
+    bar  NaN  NaN  4.0
+    dat  NaN  NaN  2.5
+    """
+    from pandas.core.indexes.base import Index
+
+    reordered_indexes = [
+        pair[0] for pair in sorted(zip(columns, order), key=lambda t: t[1])
+    ]
+    reordered_result_in_dict: dict[Hashable, Series] = {}
+    idx = 0
+
+    reorder_mask = not isinstance(result, ABCSeries) and len(result.columns) > 1
+    for col, fun in func.items():
+        s = result[col].dropna()
+
+        # In the `_aggregate`, the callable names are obtained and used in `result`, and
+        # these names are ordered alphabetically. e.g.
+        #           C2   C1
+        #    1  NaN
+        # amax     NaN  4.0
+        # max      NaN  4.0
+        # sum     18.0  6.0
+        # Therefore, the order of functions for each column could be shuffled
+        # accordingly so need to get the callable name if it is not parsed names, and
+        # reorder the aggregated result for each column.
+        # e.g. if df.agg(c1=("C2", sum), c2=("C2", lambda x: min(x))), correct order is
+        # [sum, ], but in `result`, it will be [, sum], and we need to
+        # reorder so that aggregated values map to their functions regarding the order.
+
+        # However there is only one column being used for aggregation, not need to
+        # reorder since the index is not sorted, and keep as is in `funcs`, e.g.
+        #         A
+        # min   1.0
+        # mean  1.5
+        # mean  1.5
+        if reorder_mask:
+            fun = [
+                com.get_callable_name(f) if not isinstance(f, str) else f for f in fun
+            ]
+            col_idx_order = Index(s.index).get_indexer(fun)
+            s = s.iloc[col_idx_order]
+
+        # assign the new user-provided "named aggregation" as index names, and reindex
+        # it based on the whole user-provided names.
+        s.index = reordered_indexes[idx : idx + len(fun)]
+        reordered_result_in_dict[col] = s.reindex(columns, copy=False)
+        idx = idx + len(fun)
+    return reordered_result_in_dict
+
+
+def reconstruct_and_relabel_result(result, func, **kwargs) -> DataFrame | Series:
+    from pandas import DataFrame
+
+    relabeling, func, columns, order = reconstruct_func(func, **kwargs)
+
+    if relabeling:
+        # This is to keep the order to columns occurrence unchanged, and also
+        # keep the order of new columns occurrence unchanged
+
+        # For the return values of reconstruct_func, if relabeling is
+        # False, columns and order will be None.
+        assert columns is not None
+        assert order is not None
+
+        result_in_dict = relabel_result(result, func, columns, order)
+        result = DataFrame(result_in_dict, index=columns)
+
+    return result
+
+
+# TODO: Can't use, because mypy doesn't like us setting __name__
+#   error: "partial[Any]" has no attribute "__name__"
+# the type is:
+#   typing.Sequence[Callable[..., ScalarResult]]
+#     -> typing.Sequence[Callable[..., ScalarResult]]:
+
+
+def _managle_lambda_list(aggfuncs: Sequence[Any]) -> Sequence[Any]:
+    """
+    Possibly mangle a list of aggfuncs.
+
+    Parameters
+    ----------
+    aggfuncs : Sequence
+
+    Returns
+    -------
+    mangled: list-like
+        A new AggSpec sequence, where lambdas have been converted
+        to have unique names.
+
+    Notes
+    -----
+    If just one aggfunc is passed, the name will not be mangled.
+    """
+    if len(aggfuncs) <= 1:
+        # don't mangle for .agg([lambda x: .])
+        return aggfuncs
+    i = 0
+    mangled_aggfuncs = []
+    for aggfunc in aggfuncs:
+        if com.get_callable_name(aggfunc) == "":
+            aggfunc = partial(aggfunc)
+            aggfunc.__name__ = f""
+            i += 1
+        mangled_aggfuncs.append(aggfunc)
+
+    return mangled_aggfuncs
+
+
+def maybe_mangle_lambdas(agg_spec: Any) -> Any:
+    """
+    Make new lambdas with unique names.
+
+    Parameters
+    ----------
+    agg_spec : Any
+        An argument to GroupBy.agg.
+        Non-dict-like `agg_spec` are pass through as is.
+        For dict-like `agg_spec` a new spec is returned
+        with name-mangled lambdas.
+
+    Returns
+    -------
+    mangled : Any
+        Same type as the input.
+
+    Examples
+    --------
+    >>> maybe_mangle_lambdas('sum')
+    'sum'
+    >>> maybe_mangle_lambdas([lambda: 1, lambda: 2])  # doctest: +SKIP
+    [,
+     .f(*args, **kwargs)>]
+    """
+    is_dict = is_dict_like(agg_spec)
+    if not (is_dict or is_list_like(agg_spec)):
+        return agg_spec
+    mangled_aggspec = type(agg_spec)()  # dict or OrderedDict
+
+    if is_dict:
+        for key, aggfuncs in agg_spec.items():
+            if is_list_like(aggfuncs) and not is_dict_like(aggfuncs):
+                mangled_aggfuncs = _managle_lambda_list(aggfuncs)
+            else:
+                mangled_aggfuncs = aggfuncs
+
+            mangled_aggspec[key] = mangled_aggfuncs
+    else:
+        mangled_aggspec = _managle_lambda_list(agg_spec)
+
+    return mangled_aggspec
+
+
+def validate_func_kwargs(
+    kwargs: dict,
+) -> tuple[list[str], list[str | Callable[..., Any]]]:
+    """
+    Validates types of user-provided "named aggregation" kwargs.
+    `TypeError` is raised if aggfunc is not `str` or callable.
+
+    Parameters
+    ----------
+    kwargs : dict
+
+    Returns
+    -------
+    columns : List[str]
+        List of user-provided keys.
+    func : List[Union[str, callable[...,Any]]]
+        List of user-provided aggfuncs
+
+    Examples
+    --------
+    >>> validate_func_kwargs({'one': 'min', 'two': 'max'})
+    (['one', 'two'], ['min', 'max'])
+    """
+    tuple_given_message = "func is expected but received {} in **kwargs."
+    columns = list(kwargs)
+    func = []
+    for col_func in kwargs.values():
+        if not (isinstance(col_func, str) or callable(col_func)):
+            raise TypeError(tuple_given_message.format(type(col_func).__name__))
+        func.append(col_func)
+    if not columns:
+        no_arg_message = "Must provide 'func' or named aggregation **kwargs."
+        raise TypeError(no_arg_message)
+    return columns, func
+
+
+def include_axis(op_name: Literal["agg", "apply"], colg: Series | DataFrame) -> bool:
+    return isinstance(colg, ABCDataFrame) or (
+        isinstance(colg, ABCSeries) and op_name == "agg"
+    )
+
+
+def warn_alias_replacement(
+    obj: AggObjType,
+    func: Callable,
+    alias: str,
+) -> None:
+    if alias.startswith("np."):
+        full_alias = alias
+    else:
+        full_alias = f"{type(obj).__name__}.{alias}"
+        alias = f'"{alias}"'
+    warnings.warn(
+        f"The provided callable {func} is currently using "
+        f"{full_alias}. In a future version of pandas, "
+        f"the provided callable will be used directly. To keep current "
+        f"behavior pass the string {alias} instead.",
+        category=FutureWarning,
+        stacklevel=find_stack_level(),
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..a7655a013c6cf3fca754086fdeb29b806220d5e4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/__init__.py
@@ -0,0 +1,9 @@
+"""
+core.array_algos is for algorithms that operate on ndarray and ExtensionArray.
+These should:
+
+- Assume that any Index, Series, or DataFrame objects have already been unwrapped.
+- Assume that any list arguments have already been cast to ndarray/EA.
+- Not depend on Index, Series, or DataFrame, nor import any of these.
+- May dispatch to ExtensionArray methods, but should not import from core.arrays.
+"""
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/datetimelike_accumulations.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/datetimelike_accumulations.py
new file mode 100644
index 0000000000000000000000000000000000000000..825fe60ee6cf88a2186a5f501c8696cecaf2657d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/datetimelike_accumulations.py
@@ -0,0 +1,67 @@
+"""
+datetimelke_accumulations.py is for accumulations of datetimelike extension arrays
+"""
+
+from __future__ import annotations
+
+from typing import Callable
+
+import numpy as np
+
+from pandas._libs import iNaT
+
+from pandas.core.dtypes.missing import isna
+
+
+def _cum_func(
+    func: Callable,
+    values: np.ndarray,
+    *,
+    skipna: bool = True,
+):
+    """
+    Accumulations for 1D datetimelike arrays.
+
+    Parameters
+    ----------
+    func : np.cumsum, np.maximum.accumulate, np.minimum.accumulate
+    values : np.ndarray
+        Numpy array with the values (can be of any dtype that support the
+        operation). Values is changed is modified inplace.
+    skipna : bool, default True
+        Whether to skip NA.
+    """
+    try:
+        fill_value = {
+            np.maximum.accumulate: np.iinfo(np.int64).min,
+            np.cumsum: 0,
+            np.minimum.accumulate: np.iinfo(np.int64).max,
+        }[func]
+    except KeyError:
+        raise ValueError(f"No accumulation for {func} implemented on BaseMaskedArray")
+
+    mask = isna(values)
+    y = values.view("i8")
+    y[mask] = fill_value
+
+    if not skipna:
+        mask = np.maximum.accumulate(mask)
+
+    result = func(y)
+    result[mask] = iNaT
+
+    if values.dtype.kind in "mM":
+        return result.view(values.dtype.base)
+    return result
+
+
+def cumsum(values: np.ndarray, *, skipna: bool = True) -> np.ndarray:
+    return _cum_func(np.cumsum, values, skipna=skipna)
+
+
+def cummin(values: np.ndarray, *, skipna: bool = True):
+    return _cum_func(np.minimum.accumulate, values, skipna=skipna)
+
+
+def cummax(values: np.ndarray, *, skipna: bool = True):
+    return _cum_func(np.maximum.accumulate, values, skipna=skipna)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_accumulations.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_accumulations.py
new file mode 100644
index 0000000000000000000000000000000000000000..ad9e96d398a242dc64de2018b749fd2dbca7ed78
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_accumulations.py
@@ -0,0 +1,90 @@
+"""
+masked_accumulations.py is for accumulation algorithms using a mask-based approach
+for missing values.
+"""
+
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+
+def _cum_func(
+    func: Callable,
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+):
+    """
+    Accumulations for 1D masked array.
+
+    We will modify values in place to replace NAs with the appropriate fill value.
+
+    Parameters
+    ----------
+    func : np.cumsum, np.cumprod, np.maximum.accumulate, np.minimum.accumulate
+    values : np.ndarray
+        Numpy array with the values (can be of any dtype that support the
+        operation).
+    mask : np.ndarray
+        Boolean numpy array (True values indicate missing values).
+    skipna : bool, default True
+        Whether to skip NA.
+    """
+    dtype_info: np.iinfo | np.finfo
+    if values.dtype.kind == "f":
+        dtype_info = np.finfo(values.dtype.type)
+    elif values.dtype.kind in "iu":
+        dtype_info = np.iinfo(values.dtype.type)
+    elif values.dtype.kind == "b":
+        # Max value of bool is 1, but since we are setting into a boolean
+        # array, 255 is fine as well. Min value has to be 0 when setting
+        # into the boolean array.
+        dtype_info = np.iinfo(np.uint8)
+    else:
+        raise NotImplementedError(
+            f"No masked accumulation defined for dtype {values.dtype.type}"
+        )
+    try:
+        fill_value = {
+            np.cumprod: 1,
+            np.maximum.accumulate: dtype_info.min,
+            np.cumsum: 0,
+            np.minimum.accumulate: dtype_info.max,
+        }[func]
+    except KeyError:
+        raise NotImplementedError(
+            f"No accumulation for {func} implemented on BaseMaskedArray"
+        )
+
+    values[mask] = fill_value
+
+    if not skipna:
+        mask = np.maximum.accumulate(mask)
+
+    values = func(values)
+    return values, mask
+
+
+def cumsum(values: np.ndarray, mask: npt.NDArray[np.bool_], *, skipna: bool = True):
+    return _cum_func(np.cumsum, values, mask, skipna=skipna)
+
+
+def cumprod(values: np.ndarray, mask: npt.NDArray[np.bool_], *, skipna: bool = True):
+    return _cum_func(np.cumprod, values, mask, skipna=skipna)
+
+
+def cummin(values: np.ndarray, mask: npt.NDArray[np.bool_], *, skipna: bool = True):
+    return _cum_func(np.minimum.accumulate, values, mask, skipna=skipna)
+
+
+def cummax(values: np.ndarray, mask: npt.NDArray[np.bool_], *, skipna: bool = True):
+    return _cum_func(np.maximum.accumulate, values, mask, skipna=skipna)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_reductions.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_reductions.py
new file mode 100644
index 0000000000000000000000000000000000000000..6bf97729a79b1436fdf466eade06e0049984c1d0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/masked_reductions.py
@@ -0,0 +1,201 @@
+"""
+masked_reductions.py is for reduction algorithms using a mask-based approach
+for missing values.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import missing as libmissing
+
+from pandas.core.nanops import check_below_min_count
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        AxisInt,
+        npt,
+    )
+
+
+def _reductions(
+    func: Callable,
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    min_count: int = 0,
+    axis: AxisInt | None = None,
+    **kwargs,
+):
+    """
+    Sum, mean or product for 1D masked array.
+
+    Parameters
+    ----------
+    func : np.sum or np.prod
+    values : np.ndarray
+        Numpy array with the values (can be of any dtype that support the
+        operation).
+    mask : np.ndarray[bool]
+        Boolean numpy array (True values indicate missing values).
+    skipna : bool, default True
+        Whether to skip NA.
+    min_count : int, default 0
+        The required number of valid values to perform the operation. If fewer than
+        ``min_count`` non-NA values are present the result will be NA.
+    axis : int, optional, default None
+    """
+    if not skipna:
+        if mask.any() or check_below_min_count(values.shape, None, min_count):
+            return libmissing.NA
+        else:
+            return func(values, axis=axis, **kwargs)
+    else:
+        if check_below_min_count(values.shape, mask, min_count) and (
+            axis is None or values.ndim == 1
+        ):
+            return libmissing.NA
+
+        if values.dtype == np.dtype(object):
+            # object dtype does not support `where` without passing an initial
+            values = values[~mask]
+            return func(values, axis=axis, **kwargs)
+        return func(values, where=~mask, axis=axis, **kwargs)
+
+
+def sum(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    min_count: int = 0,
+    axis: AxisInt | None = None,
+):
+    return _reductions(
+        np.sum, values=values, mask=mask, skipna=skipna, min_count=min_count, axis=axis
+    )
+
+
+def prod(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    min_count: int = 0,
+    axis: AxisInt | None = None,
+):
+    return _reductions(
+        np.prod, values=values, mask=mask, skipna=skipna, min_count=min_count, axis=axis
+    )
+
+
+def _minmax(
+    func: Callable,
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+):
+    """
+    Reduction for 1D masked array.
+
+    Parameters
+    ----------
+    func : np.min or np.max
+    values : np.ndarray
+        Numpy array with the values (can be of any dtype that support the
+        operation).
+    mask : np.ndarray[bool]
+        Boolean numpy array (True values indicate missing values).
+    skipna : bool, default True
+        Whether to skip NA.
+    axis : int, optional, default None
+    """
+    if not skipna:
+        if mask.any() or not values.size:
+            # min/max with empty array raise in numpy, pandas returns NA
+            return libmissing.NA
+        else:
+            return func(values, axis=axis)
+    else:
+        subset = values[~mask]
+        if subset.size:
+            return func(subset, axis=axis)
+        else:
+            # min/max with empty array raise in numpy, pandas returns NA
+            return libmissing.NA
+
+
+def min(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+):
+    return _minmax(np.min, values=values, mask=mask, skipna=skipna, axis=axis)
+
+
+def max(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+):
+    return _minmax(np.max, values=values, mask=mask, skipna=skipna, axis=axis)
+
+
+def mean(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+):
+    if not values.size or mask.all():
+        return libmissing.NA
+    return _reductions(np.mean, values=values, mask=mask, skipna=skipna, axis=axis)
+
+
+def var(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+    ddof: int = 1,
+):
+    if not values.size or mask.all():
+        return libmissing.NA
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        return _reductions(
+            np.var, values=values, mask=mask, skipna=skipna, axis=axis, ddof=ddof
+        )
+
+
+def std(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    *,
+    skipna: bool = True,
+    axis: AxisInt | None = None,
+    ddof: int = 1,
+):
+    if not values.size or mask.all():
+        return libmissing.NA
+
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", RuntimeWarning)
+        return _reductions(
+            np.std, values=values, mask=mask, skipna=skipna, axis=axis, ddof=ddof
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/putmask.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/putmask.py
new file mode 100644
index 0000000000000000000000000000000000000000..f65d2d20e028e36b35a397d8ac973f184ce1412c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/putmask.py
@@ -0,0 +1,149 @@
+"""
+EA-compatible analogue to np.putmask
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.cast import infer_dtype_from
+from pandas.core.dtypes.common import is_list_like
+
+from pandas.core.arrays import ExtensionArray
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        npt,
+    )
+
+    from pandas import MultiIndex
+
+
+def putmask_inplace(values: ArrayLike, mask: npt.NDArray[np.bool_], value: Any) -> None:
+    """
+    ExtensionArray-compatible implementation of np.putmask.  The main
+    difference is we do not handle repeating or truncating like numpy.
+
+    Parameters
+    ----------
+    values: np.ndarray or ExtensionArray
+    mask : np.ndarray[bool]
+        We assume extract_bool_array has already been called.
+    value : Any
+    """
+
+    if (
+        not isinstance(values, np.ndarray)
+        or (values.dtype == object and not lib.is_scalar(value))
+        # GH#43424: np.putmask raises TypeError if we cannot cast between types with
+        # rule = "safe", a stricter guarantee we may not have here
+        or (
+            isinstance(value, np.ndarray) and not np.can_cast(value.dtype, values.dtype)
+        )
+    ):
+        # GH#19266 using np.putmask gives unexpected results with listlike value
+        #  along with object dtype
+        if is_list_like(value) and len(value) == len(values):
+            values[mask] = value[mask]
+        else:
+            values[mask] = value
+    else:
+        # GH#37833 np.putmask is more performant than __setitem__
+        np.putmask(values, mask, value)
+
+
+def putmask_without_repeat(
+    values: np.ndarray, mask: npt.NDArray[np.bool_], new: Any
+) -> None:
+    """
+    np.putmask will truncate or repeat if `new` is a listlike with
+    len(new) != len(values).  We require an exact match.
+
+    Parameters
+    ----------
+    values : np.ndarray
+    mask : np.ndarray[bool]
+    new : Any
+    """
+    if getattr(new, "ndim", 0) >= 1:
+        new = new.astype(values.dtype, copy=False)
+
+    # TODO: this prob needs some better checking for 2D cases
+    nlocs = mask.sum()
+    if nlocs > 0 and is_list_like(new) and getattr(new, "ndim", 1) == 1:
+        shape = np.shape(new)
+        # np.shape compat for if setitem_datetimelike_compat
+        #  changed arraylike to list e.g. test_where_dt64_2d
+        if nlocs == shape[-1]:
+            # GH#30567
+            # If length of ``new`` is less than the length of ``values``,
+            # `np.putmask` would first repeat the ``new`` array and then
+            # assign the masked values hence produces incorrect result.
+            # `np.place` on the other hand uses the ``new`` values at it is
+            # to place in the masked locations of ``values``
+            np.place(values, mask, new)
+            # i.e. values[mask] = new
+        elif mask.shape[-1] == shape[-1] or shape[-1] == 1:
+            np.putmask(values, mask, new)
+        else:
+            raise ValueError("cannot assign mismatch length to masked array")
+    else:
+        np.putmask(values, mask, new)
+
+
+def validate_putmask(
+    values: ArrayLike | MultiIndex, mask: np.ndarray
+) -> tuple[npt.NDArray[np.bool_], bool]:
+    """
+    Validate mask and check if this putmask operation is a no-op.
+    """
+    mask = extract_bool_array(mask)
+    if mask.shape != values.shape:
+        raise ValueError("putmask: mask and data must be the same size")
+
+    noop = not mask.any()
+    return mask, noop
+
+
+def extract_bool_array(mask: ArrayLike) -> npt.NDArray[np.bool_]:
+    """
+    If we have a SparseArray or BooleanArray, convert it to ndarray[bool].
+    """
+    if isinstance(mask, ExtensionArray):
+        # We could have BooleanArray, Sparse[bool], ...
+        #  Except for BooleanArray, this is equivalent to just
+        #  np.asarray(mask, dtype=bool)
+        mask = mask.to_numpy(dtype=bool, na_value=False)
+
+    mask = np.asarray(mask, dtype=bool)
+    return mask
+
+
+def setitem_datetimelike_compat(values: np.ndarray, num_set: int, other):
+    """
+    Parameters
+    ----------
+    values : np.ndarray
+    num_set : int
+        For putmask, this is mask.sum()
+    other : Any
+    """
+    if values.dtype == object:
+        dtype, _ = infer_dtype_from(other)
+
+        if lib.is_np_dtype(dtype, "mM"):
+            # https://github.com/numpy/numpy/issues/12550
+            #  timedelta64 will incorrectly cast to int
+            if not is_list_like(other):
+                other = [other] * num_set
+            else:
+                other = list(other)
+
+    return other
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/quantile.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/quantile.py
new file mode 100644
index 0000000000000000000000000000000000000000..5c933294fb944f04dd3e9a64e4731ea4349254f9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/quantile.py
@@ -0,0 +1,226 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        Scalar,
+        npt,
+    )
+
+
+def quantile_compat(
+    values: ArrayLike, qs: npt.NDArray[np.float64], interpolation: str
+) -> ArrayLike:
+    """
+    Compute the quantiles of the given values for each quantile in `qs`.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+    qs : np.ndarray[float64]
+    interpolation : str
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    if isinstance(values, np.ndarray):
+        fill_value = na_value_for_dtype(values.dtype, compat=False)
+        mask = isna(values)
+        return quantile_with_mask(values, mask, fill_value, qs, interpolation)
+    else:
+        return values._quantile(qs, interpolation)
+
+
+def quantile_with_mask(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    fill_value,
+    qs: npt.NDArray[np.float64],
+    interpolation: str,
+) -> np.ndarray:
+    """
+    Compute the quantiles of the given values for each quantile in `qs`.
+
+    Parameters
+    ----------
+    values : np.ndarray
+        For ExtensionArray, this is _values_for_factorize()[0]
+    mask : np.ndarray[bool]
+        mask = isna(values)
+        For ExtensionArray, this is computed before calling _value_for_factorize
+    fill_value : Scalar
+        The value to interpret fill NA entries with
+        For ExtensionArray, this is _values_for_factorize()[1]
+    qs : np.ndarray[float64]
+    interpolation : str
+        Type of interpolation
+
+    Returns
+    -------
+    np.ndarray
+
+    Notes
+    -----
+    Assumes values is already 2D.  For ExtensionArray this means np.atleast_2d
+    has been called on _values_for_factorize()[0]
+
+    Quantile is computed along axis=1.
+    """
+    assert values.shape == mask.shape
+    if values.ndim == 1:
+        # unsqueeze, operate, re-squeeze
+        values = np.atleast_2d(values)
+        mask = np.atleast_2d(mask)
+        res_values = quantile_with_mask(values, mask, fill_value, qs, interpolation)
+        return res_values[0]
+
+    assert values.ndim == 2
+
+    is_empty = values.shape[1] == 0
+
+    if is_empty:
+        # create the array of na_values
+        # 2d len(values) * len(qs)
+        flat = np.array([fill_value] * len(qs))
+        result = np.repeat(flat, len(values)).reshape(len(values), len(qs))
+    else:
+        result = _nanpercentile(
+            values,
+            qs * 100.0,
+            na_value=fill_value,
+            mask=mask,
+            interpolation=interpolation,
+        )
+
+        result = np.asarray(result)
+        result = result.T
+
+    return result
+
+
+def _nanpercentile_1d(
+    values: np.ndarray,
+    mask: npt.NDArray[np.bool_],
+    qs: npt.NDArray[np.float64],
+    na_value: Scalar,
+    interpolation: str,
+) -> Scalar | np.ndarray:
+    """
+    Wrapper for np.percentile that skips missing values, specialized to
+    1-dimensional case.
+
+    Parameters
+    ----------
+    values : array over which to find quantiles
+    mask : ndarray[bool]
+        locations in values that should be considered missing
+    qs : np.ndarray[float64] of quantile indices to find
+    na_value : scalar
+        value to return for empty or all-null values
+    interpolation : str
+
+    Returns
+    -------
+    quantiles : scalar or array
+    """
+    # mask is Union[ExtensionArray, ndarray]
+    values = values[~mask]
+
+    if len(values) == 0:
+        # Can't pass dtype=values.dtype here bc we might have na_value=np.nan
+        #  with values.dtype=int64 see test_quantile_empty
+        # equiv: 'np.array([na_value] * len(qs))' but much faster
+        return np.full(len(qs), na_value)
+
+    return np.percentile(
+        values,
+        qs,
+        # error: No overload variant of "percentile" matches argument
+        # types "ndarray[Any, Any]", "ndarray[Any, dtype[floating[_64Bit]]]"
+        # , "Dict[str, str]"  [call-overload]
+        method=interpolation,  # type: ignore[call-overload]
+    )
+
+
+def _nanpercentile(
+    values: np.ndarray,
+    qs: npt.NDArray[np.float64],
+    *,
+    na_value,
+    mask: npt.NDArray[np.bool_],
+    interpolation: str,
+):
+    """
+    Wrapper for np.percentile that skips missing values.
+
+    Parameters
+    ----------
+    values : np.ndarray[ndim=2]  over which to find quantiles
+    qs : np.ndarray[float64] of quantile indices to find
+    na_value : scalar
+        value to return for empty or all-null values
+    mask : np.ndarray[bool]
+        locations in values that should be considered missing
+    interpolation : str
+
+    Returns
+    -------
+    quantiles : scalar or array
+    """
+
+    if values.dtype.kind in "mM":
+        # need to cast to integer to avoid rounding errors in numpy
+        result = _nanpercentile(
+            values.view("i8"),
+            qs=qs,
+            na_value=na_value.view("i8"),
+            mask=mask,
+            interpolation=interpolation,
+        )
+
+        # Note: we have to do `astype` and not view because in general we
+        #  have float result at this point, not i8
+        return result.astype(values.dtype)
+
+    if mask.any():
+        # Caller is responsible for ensuring mask shape match
+        assert mask.shape == values.shape
+        result = [
+            _nanpercentile_1d(val, m, qs, na_value, interpolation=interpolation)
+            for (val, m) in zip(list(values), list(mask))
+        ]
+        if values.dtype.kind == "f":
+            # preserve itemsize
+            result = np.asarray(result, dtype=values.dtype).T
+        else:
+            result = np.asarray(result).T
+            if (
+                result.dtype != values.dtype
+                and not mask.all()
+                and (result == result.astype(values.dtype, copy=False)).all()
+            ):
+                # mask.all() will never get cast back to int
+                # e.g. values id integer dtype and result is floating dtype,
+                #  only cast back to integer dtype if result values are all-integer.
+                result = result.astype(values.dtype, copy=False)
+        return result
+    else:
+        return np.percentile(
+            values,
+            qs,
+            axis=1,
+            # error: No overload variant of "percentile" matches argument types
+            # "ndarray[Any, Any]", "ndarray[Any, dtype[floating[_64Bit]]]",
+            # "int", "Dict[str, str]"  [call-overload]
+            method=interpolation,  # type: ignore[call-overload]
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/replace.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/replace.py
new file mode 100644
index 0000000000000000000000000000000000000000..16239ed8c46970f38159ae12bc9a45da31ffd617
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/replace.py
@@ -0,0 +1,155 @@
+"""
+Methods used by Block.replace and related methods.
+"""
+from __future__ import annotations
+
+import operator
+import re
+from re import Pattern
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_re,
+    is_re_compilable,
+)
+from pandas.core.dtypes.missing import isna
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        Scalar,
+        npt,
+    )
+
+
+def should_use_regex(regex: bool, to_replace: Any) -> bool:
+    """
+    Decide whether to treat `to_replace` as a regular expression.
+    """
+    if is_re(to_replace):
+        regex = True
+
+    regex = regex and is_re_compilable(to_replace)
+
+    # Don't use regex if the pattern is empty.
+    regex = regex and re.compile(to_replace).pattern != ""
+    return regex
+
+
+def compare_or_regex_search(
+    a: ArrayLike, b: Scalar | Pattern, regex: bool, mask: npt.NDArray[np.bool_]
+) -> ArrayLike:
+    """
+    Compare two array-like inputs of the same shape or two scalar values
+
+    Calls operator.eq or re.search, depending on regex argument. If regex is
+    True, perform an element-wise regex matching.
+
+    Parameters
+    ----------
+    a : array-like
+    b : scalar or regex pattern
+    regex : bool
+    mask : np.ndarray[bool]
+
+    Returns
+    -------
+    mask : array-like of bool
+    """
+    if isna(b):
+        return ~mask
+
+    def _check_comparison_types(
+        result: ArrayLike | bool, a: ArrayLike, b: Scalar | Pattern
+    ):
+        """
+        Raises an error if the two arrays (a,b) cannot be compared.
+        Otherwise, returns the comparison result as expected.
+        """
+        if is_bool(result) and isinstance(a, np.ndarray):
+            type_names = [type(a).__name__, type(b).__name__]
+
+            type_names[0] = f"ndarray(dtype={a.dtype})"
+
+            raise TypeError(
+                f"Cannot compare types {repr(type_names[0])} and {repr(type_names[1])}"
+            )
+
+    if not regex or not should_use_regex(regex, b):
+        # TODO: should use missing.mask_missing?
+        op = lambda x: operator.eq(x, b)
+    else:
+        op = np.vectorize(
+            lambda x: bool(re.search(b, x))
+            if isinstance(x, str) and isinstance(b, (str, Pattern))
+            else False
+        )
+
+    # GH#32621 use mask to avoid comparing to NAs
+    if isinstance(a, np.ndarray) and mask is not None:
+        a = a[mask]
+        result = op(a)
+
+        if isinstance(result, np.ndarray):
+            # The shape of the mask can differ to that of the result
+            # since we may compare only a subset of a's or b's elements
+            tmp = np.zeros(mask.shape, dtype=np.bool_)
+            np.place(tmp, mask, result)
+            result = tmp
+    else:
+        result = op(a)
+
+    _check_comparison_types(result, a, b)
+    return result
+
+
+def replace_regex(
+    values: ArrayLike, rx: re.Pattern, value, mask: npt.NDArray[np.bool_] | None
+) -> None:
+    """
+    Parameters
+    ----------
+    values : ArrayLike
+        Object dtype.
+    rx : re.Pattern
+    value : Any
+    mask : np.ndarray[bool], optional
+
+    Notes
+    -----
+    Alters values in-place.
+    """
+
+    # deal with replacing values with objects (strings) that match but
+    # whose replacement is not a string (numeric, nan, object)
+    if isna(value) or not isinstance(value, str):
+
+        def re_replacer(s):
+            if is_re(rx) and isinstance(s, str):
+                return value if rx.search(s) is not None else s
+            else:
+                return s
+
+    else:
+        # value is guaranteed to be a string here, s can be either a string
+        # or null if it's null it gets returned
+        def re_replacer(s):
+            if is_re(rx) and isinstance(s, str):
+                return rx.sub(value, s)
+            else:
+                return s
+
+    f = np.vectorize(re_replacer, otypes=[np.object_])
+
+    if mask is None:
+        values[:] = f(values)
+    else:
+        if values.ndim != mask.ndim:
+            mask = np.broadcast_to(mask, values.shape)
+        values[mask] = f(values[mask])
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/take.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/take.py
new file mode 100644
index 0000000000000000000000000000000000000000..ac674e31586e72040a8e1313f232a00299b961ee
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/take.py
@@ -0,0 +1,594 @@
+from __future__ import annotations
+
+import functools
+from typing import (
+    TYPE_CHECKING,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    algos as libalgos,
+    lib,
+)
+
+from pandas.core.dtypes.cast import maybe_promote
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_1d_only_ea_dtype,
+)
+from pandas.core.dtypes.missing import na_value_for_dtype
+
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        npt,
+    )
+
+    from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+    from pandas.core.arrays.base import ExtensionArray
+
+
+@overload
+def take_nd(
+    arr: np.ndarray,
+    indexer,
+    axis: AxisInt = ...,
+    fill_value=...,
+    allow_fill: bool = ...,
+) -> np.ndarray:
+    ...
+
+
+@overload
+def take_nd(
+    arr: ExtensionArray,
+    indexer,
+    axis: AxisInt = ...,
+    fill_value=...,
+    allow_fill: bool = ...,
+) -> ArrayLike:
+    ...
+
+
+def take_nd(
+    arr: ArrayLike,
+    indexer,
+    axis: AxisInt = 0,
+    fill_value=lib.no_default,
+    allow_fill: bool = True,
+) -> ArrayLike:
+    """
+    Specialized Cython take which sets NaN values in one pass
+
+    This dispatches to ``take`` defined on ExtensionArrays.
+
+    Note: this function assumes that the indexer is a valid(ated) indexer with
+    no out of bound indices.
+
+    Parameters
+    ----------
+    arr : np.ndarray or ExtensionArray
+        Input array.
+    indexer : ndarray
+        1-D array of indices to take, subarrays corresponding to -1 value
+        indices are filed with fill_value
+    axis : int, default 0
+        Axis to take from
+    fill_value : any, default np.nan
+        Fill value to replace -1 values with
+    allow_fill : bool, default True
+        If False, indexer is assumed to contain no -1 values so no filling
+        will be done.  This short-circuits computation of a mask.  Result is
+        undefined if allow_fill == False and -1 is present in indexer.
+
+    Returns
+    -------
+    subarray : np.ndarray or ExtensionArray
+        May be the same type as the input, or cast to an ndarray.
+    """
+    if fill_value is lib.no_default:
+        fill_value = na_value_for_dtype(arr.dtype, compat=False)
+    elif lib.is_np_dtype(arr.dtype, "mM"):
+        dtype, fill_value = maybe_promote(arr.dtype, fill_value)
+        if arr.dtype != dtype:
+            # EA.take is strict about returning a new object of the same type
+            # so for that case cast upfront
+            arr = arr.astype(dtype)
+
+    if not isinstance(arr, np.ndarray):
+        # i.e. ExtensionArray,
+        # includes for EA to catch DatetimeArray, TimedeltaArray
+        if not is_1d_only_ea_dtype(arr.dtype):
+            # i.e. DatetimeArray, TimedeltaArray
+            arr = cast("NDArrayBackedExtensionArray", arr)
+            return arr.take(
+                indexer, fill_value=fill_value, allow_fill=allow_fill, axis=axis
+            )
+
+        return arr.take(indexer, fill_value=fill_value, allow_fill=allow_fill)
+
+    arr = np.asarray(arr)
+    return _take_nd_ndarray(arr, indexer, axis, fill_value, allow_fill)
+
+
+def _take_nd_ndarray(
+    arr: np.ndarray,
+    indexer: npt.NDArray[np.intp] | None,
+    axis: AxisInt,
+    fill_value,
+    allow_fill: bool,
+) -> np.ndarray:
+    if indexer is None:
+        indexer = np.arange(arr.shape[axis], dtype=np.intp)
+        dtype, fill_value = arr.dtype, arr.dtype.type()
+    else:
+        indexer = ensure_platform_int(indexer)
+
+    dtype, fill_value, mask_info = _take_preprocess_indexer_and_fill_value(
+        arr, indexer, fill_value, allow_fill
+    )
+
+    flip_order = False
+    if arr.ndim == 2 and arr.flags.f_contiguous:
+        flip_order = True
+
+    if flip_order:
+        arr = arr.T
+        axis = arr.ndim - axis - 1
+
+    # at this point, it's guaranteed that dtype can hold both the arr values
+    # and the fill_value
+    out_shape_ = list(arr.shape)
+    out_shape_[axis] = len(indexer)
+    out_shape = tuple(out_shape_)
+    if arr.flags.f_contiguous and axis == arr.ndim - 1:
+        # minor tweak that can make an order-of-magnitude difference
+        # for dataframes initialized directly from 2-d ndarrays
+        # (s.t. df.values is c-contiguous and df._mgr.blocks[0] is its
+        # f-contiguous transpose)
+        out = np.empty(out_shape, dtype=dtype, order="F")
+    else:
+        out = np.empty(out_shape, dtype=dtype)
+
+    func = _get_take_nd_function(
+        arr.ndim, arr.dtype, out.dtype, axis=axis, mask_info=mask_info
+    )
+    func(arr, indexer, out, fill_value)
+
+    if flip_order:
+        out = out.T
+    return out
+
+
+def take_1d(
+    arr: ArrayLike,
+    indexer: npt.NDArray[np.intp],
+    fill_value=None,
+    allow_fill: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> ArrayLike:
+    """
+    Specialized version for 1D arrays. Differences compared to `take_nd`:
+
+    - Assumes input array has already been converted to numpy array / EA
+    - Assumes indexer is already guaranteed to be intp dtype ndarray
+    - Only works for 1D arrays
+
+    To ensure the lowest possible overhead.
+
+    Note: similarly to `take_nd`, this function assumes that the indexer is
+    a valid(ated) indexer with no out of bound indices.
+
+    Parameters
+    ----------
+    arr : np.ndarray or ExtensionArray
+        Input array.
+    indexer : ndarray
+        1-D array of indices to take (validated indices, intp dtype).
+    fill_value : any, default np.nan
+        Fill value to replace -1 values with
+    allow_fill : bool, default True
+        If False, indexer is assumed to contain no -1 values so no filling
+        will be done.  This short-circuits computation of a mask. Result is
+        undefined if allow_fill == False and -1 is present in indexer.
+    mask : np.ndarray, optional, default None
+        If `allow_fill` is True, and the mask (where indexer == -1) is already
+        known, it can be passed to avoid recomputation.
+    """
+    if not isinstance(arr, np.ndarray):
+        # ExtensionArray -> dispatch to their method
+        return arr.take(indexer, fill_value=fill_value, allow_fill=allow_fill)
+
+    if not allow_fill:
+        return arr.take(indexer)
+
+    dtype, fill_value, mask_info = _take_preprocess_indexer_and_fill_value(
+        arr, indexer, fill_value, True, mask
+    )
+
+    # at this point, it's guaranteed that dtype can hold both the arr values
+    # and the fill_value
+    out = np.empty(indexer.shape, dtype=dtype)
+
+    func = _get_take_nd_function(
+        arr.ndim, arr.dtype, out.dtype, axis=0, mask_info=mask_info
+    )
+    func(arr, indexer, out, fill_value)
+
+    return out
+
+
+def take_2d_multi(
+    arr: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    fill_value=np.nan,
+) -> np.ndarray:
+    """
+    Specialized Cython take which sets NaN values in one pass.
+    """
+    # This is only called from one place in DataFrame._reindex_multi,
+    #  so we know indexer is well-behaved.
+    assert indexer is not None
+    assert indexer[0] is not None
+    assert indexer[1] is not None
+
+    row_idx, col_idx = indexer
+
+    row_idx = ensure_platform_int(row_idx)
+    col_idx = ensure_platform_int(col_idx)
+    indexer = row_idx, col_idx
+    mask_info = None
+
+    # check for promotion based on types only (do this first because
+    # it's faster than computing a mask)
+    dtype, fill_value = maybe_promote(arr.dtype, fill_value)
+    if dtype != arr.dtype:
+        # check if promotion is actually required based on indexer
+        row_mask = row_idx == -1
+        col_mask = col_idx == -1
+        row_needs = row_mask.any()
+        col_needs = col_mask.any()
+        mask_info = (row_mask, col_mask), (row_needs, col_needs)
+
+        if not (row_needs or col_needs):
+            # if not, then depromote, set fill_value to dummy
+            # (it won't be used but we don't want the cython code
+            # to crash when trying to cast it to dtype)
+            dtype, fill_value = arr.dtype, arr.dtype.type()
+
+    # at this point, it's guaranteed that dtype can hold both the arr values
+    # and the fill_value
+    out_shape = len(row_idx), len(col_idx)
+    out = np.empty(out_shape, dtype=dtype)
+
+    func = _take_2d_multi_dict.get((arr.dtype.name, out.dtype.name), None)
+    if func is None and arr.dtype != out.dtype:
+        func = _take_2d_multi_dict.get((out.dtype.name, out.dtype.name), None)
+        if func is not None:
+            func = _convert_wrapper(func, out.dtype)
+
+    if func is not None:
+        func(arr, indexer, out=out, fill_value=fill_value)
+    else:
+        # test_reindex_multi
+        _take_2d_multi_object(
+            arr, indexer, out, fill_value=fill_value, mask_info=mask_info
+        )
+
+    return out
+
+
+@functools.lru_cache
+def _get_take_nd_function_cached(
+    ndim: int, arr_dtype: np.dtype, out_dtype: np.dtype, axis: AxisInt
+):
+    """
+    Part of _get_take_nd_function below that doesn't need `mask_info` and thus
+    can be cached (mask_info potentially contains a numpy ndarray which is not
+    hashable and thus cannot be used as argument for cached function).
+    """
+    tup = (arr_dtype.name, out_dtype.name)
+    if ndim == 1:
+        func = _take_1d_dict.get(tup, None)
+    elif ndim == 2:
+        if axis == 0:
+            func = _take_2d_axis0_dict.get(tup, None)
+        else:
+            func = _take_2d_axis1_dict.get(tup, None)
+    if func is not None:
+        return func
+
+    # We get here with string, uint, float16, and complex dtypes that could
+    #  potentially be handled in algos_take_helper.
+    #  Also a couple with (M8[ns], object) and (m8[ns], object)
+    tup = (out_dtype.name, out_dtype.name)
+    if ndim == 1:
+        func = _take_1d_dict.get(tup, None)
+    elif ndim == 2:
+        if axis == 0:
+            func = _take_2d_axis0_dict.get(tup, None)
+        else:
+            func = _take_2d_axis1_dict.get(tup, None)
+    if func is not None:
+        func = _convert_wrapper(func, out_dtype)
+        return func
+
+    return None
+
+
+def _get_take_nd_function(
+    ndim: int,
+    arr_dtype: np.dtype,
+    out_dtype: np.dtype,
+    axis: AxisInt = 0,
+    mask_info=None,
+):
+    """
+    Get the appropriate "take" implementation for the given dimension, axis
+    and dtypes.
+    """
+    func = None
+    if ndim <= 2:
+        # for this part we don't need `mask_info` -> use the cached algo lookup
+        func = _get_take_nd_function_cached(ndim, arr_dtype, out_dtype, axis)
+
+    if func is None:
+
+        def func(arr, indexer, out, fill_value=np.nan) -> None:
+            indexer = ensure_platform_int(indexer)
+            _take_nd_object(
+                arr, indexer, out, axis=axis, fill_value=fill_value, mask_info=mask_info
+            )
+
+    return func
+
+
+def _view_wrapper(f, arr_dtype=None, out_dtype=None, fill_wrap=None):
+    def wrapper(
+        arr: np.ndarray, indexer: np.ndarray, out: np.ndarray, fill_value=np.nan
+    ) -> None:
+        if arr_dtype is not None:
+            arr = arr.view(arr_dtype)
+        if out_dtype is not None:
+            out = out.view(out_dtype)
+        if fill_wrap is not None:
+            # FIXME: if we get here with dt64/td64 we need to be sure we have
+            #  matching resos
+            if fill_value.dtype.kind == "m":
+                fill_value = fill_value.astype("m8[ns]")
+            else:
+                fill_value = fill_value.astype("M8[ns]")
+            fill_value = fill_wrap(fill_value)
+
+        f(arr, indexer, out, fill_value=fill_value)
+
+    return wrapper
+
+
+def _convert_wrapper(f, conv_dtype):
+    def wrapper(
+        arr: np.ndarray, indexer: np.ndarray, out: np.ndarray, fill_value=np.nan
+    ) -> None:
+        if conv_dtype == object:
+            # GH#39755 avoid casting dt64/td64 to integers
+            arr = ensure_wrapped_if_datetimelike(arr)
+        arr = arr.astype(conv_dtype)
+        f(arr, indexer, out, fill_value=fill_value)
+
+    return wrapper
+
+
+_take_1d_dict = {
+    ("int8", "int8"): libalgos.take_1d_int8_int8,
+    ("int8", "int32"): libalgos.take_1d_int8_int32,
+    ("int8", "int64"): libalgos.take_1d_int8_int64,
+    ("int8", "float64"): libalgos.take_1d_int8_float64,
+    ("int16", "int16"): libalgos.take_1d_int16_int16,
+    ("int16", "int32"): libalgos.take_1d_int16_int32,
+    ("int16", "int64"): libalgos.take_1d_int16_int64,
+    ("int16", "float64"): libalgos.take_1d_int16_float64,
+    ("int32", "int32"): libalgos.take_1d_int32_int32,
+    ("int32", "int64"): libalgos.take_1d_int32_int64,
+    ("int32", "float64"): libalgos.take_1d_int32_float64,
+    ("int64", "int64"): libalgos.take_1d_int64_int64,
+    ("int64", "float64"): libalgos.take_1d_int64_float64,
+    ("float32", "float32"): libalgos.take_1d_float32_float32,
+    ("float32", "float64"): libalgos.take_1d_float32_float64,
+    ("float64", "float64"): libalgos.take_1d_float64_float64,
+    ("object", "object"): libalgos.take_1d_object_object,
+    ("bool", "bool"): _view_wrapper(libalgos.take_1d_bool_bool, np.uint8, np.uint8),
+    ("bool", "object"): _view_wrapper(libalgos.take_1d_bool_object, np.uint8, None),
+    ("datetime64[ns]", "datetime64[ns]"): _view_wrapper(
+        libalgos.take_1d_int64_int64, np.int64, np.int64, np.int64
+    ),
+    ("timedelta64[ns]", "timedelta64[ns]"): _view_wrapper(
+        libalgos.take_1d_int64_int64, np.int64, np.int64, np.int64
+    ),
+}
+
+_take_2d_axis0_dict = {
+    ("int8", "int8"): libalgos.take_2d_axis0_int8_int8,
+    ("int8", "int32"): libalgos.take_2d_axis0_int8_int32,
+    ("int8", "int64"): libalgos.take_2d_axis0_int8_int64,
+    ("int8", "float64"): libalgos.take_2d_axis0_int8_float64,
+    ("int16", "int16"): libalgos.take_2d_axis0_int16_int16,
+    ("int16", "int32"): libalgos.take_2d_axis0_int16_int32,
+    ("int16", "int64"): libalgos.take_2d_axis0_int16_int64,
+    ("int16", "float64"): libalgos.take_2d_axis0_int16_float64,
+    ("int32", "int32"): libalgos.take_2d_axis0_int32_int32,
+    ("int32", "int64"): libalgos.take_2d_axis0_int32_int64,
+    ("int32", "float64"): libalgos.take_2d_axis0_int32_float64,
+    ("int64", "int64"): libalgos.take_2d_axis0_int64_int64,
+    ("int64", "float64"): libalgos.take_2d_axis0_int64_float64,
+    ("float32", "float32"): libalgos.take_2d_axis0_float32_float32,
+    ("float32", "float64"): libalgos.take_2d_axis0_float32_float64,
+    ("float64", "float64"): libalgos.take_2d_axis0_float64_float64,
+    ("object", "object"): libalgos.take_2d_axis0_object_object,
+    ("bool", "bool"): _view_wrapper(
+        libalgos.take_2d_axis0_bool_bool, np.uint8, np.uint8
+    ),
+    ("bool", "object"): _view_wrapper(
+        libalgos.take_2d_axis0_bool_object, np.uint8, None
+    ),
+    ("datetime64[ns]", "datetime64[ns]"): _view_wrapper(
+        libalgos.take_2d_axis0_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+    ("timedelta64[ns]", "timedelta64[ns]"): _view_wrapper(
+        libalgos.take_2d_axis0_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+}
+
+_take_2d_axis1_dict = {
+    ("int8", "int8"): libalgos.take_2d_axis1_int8_int8,
+    ("int8", "int32"): libalgos.take_2d_axis1_int8_int32,
+    ("int8", "int64"): libalgos.take_2d_axis1_int8_int64,
+    ("int8", "float64"): libalgos.take_2d_axis1_int8_float64,
+    ("int16", "int16"): libalgos.take_2d_axis1_int16_int16,
+    ("int16", "int32"): libalgos.take_2d_axis1_int16_int32,
+    ("int16", "int64"): libalgos.take_2d_axis1_int16_int64,
+    ("int16", "float64"): libalgos.take_2d_axis1_int16_float64,
+    ("int32", "int32"): libalgos.take_2d_axis1_int32_int32,
+    ("int32", "int64"): libalgos.take_2d_axis1_int32_int64,
+    ("int32", "float64"): libalgos.take_2d_axis1_int32_float64,
+    ("int64", "int64"): libalgos.take_2d_axis1_int64_int64,
+    ("int64", "float64"): libalgos.take_2d_axis1_int64_float64,
+    ("float32", "float32"): libalgos.take_2d_axis1_float32_float32,
+    ("float32", "float64"): libalgos.take_2d_axis1_float32_float64,
+    ("float64", "float64"): libalgos.take_2d_axis1_float64_float64,
+    ("object", "object"): libalgos.take_2d_axis1_object_object,
+    ("bool", "bool"): _view_wrapper(
+        libalgos.take_2d_axis1_bool_bool, np.uint8, np.uint8
+    ),
+    ("bool", "object"): _view_wrapper(
+        libalgos.take_2d_axis1_bool_object, np.uint8, None
+    ),
+    ("datetime64[ns]", "datetime64[ns]"): _view_wrapper(
+        libalgos.take_2d_axis1_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+    ("timedelta64[ns]", "timedelta64[ns]"): _view_wrapper(
+        libalgos.take_2d_axis1_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+}
+
+_take_2d_multi_dict = {
+    ("int8", "int8"): libalgos.take_2d_multi_int8_int8,
+    ("int8", "int32"): libalgos.take_2d_multi_int8_int32,
+    ("int8", "int64"): libalgos.take_2d_multi_int8_int64,
+    ("int8", "float64"): libalgos.take_2d_multi_int8_float64,
+    ("int16", "int16"): libalgos.take_2d_multi_int16_int16,
+    ("int16", "int32"): libalgos.take_2d_multi_int16_int32,
+    ("int16", "int64"): libalgos.take_2d_multi_int16_int64,
+    ("int16", "float64"): libalgos.take_2d_multi_int16_float64,
+    ("int32", "int32"): libalgos.take_2d_multi_int32_int32,
+    ("int32", "int64"): libalgos.take_2d_multi_int32_int64,
+    ("int32", "float64"): libalgos.take_2d_multi_int32_float64,
+    ("int64", "int64"): libalgos.take_2d_multi_int64_int64,
+    ("int64", "float64"): libalgos.take_2d_multi_int64_float64,
+    ("float32", "float32"): libalgos.take_2d_multi_float32_float32,
+    ("float32", "float64"): libalgos.take_2d_multi_float32_float64,
+    ("float64", "float64"): libalgos.take_2d_multi_float64_float64,
+    ("object", "object"): libalgos.take_2d_multi_object_object,
+    ("bool", "bool"): _view_wrapper(
+        libalgos.take_2d_multi_bool_bool, np.uint8, np.uint8
+    ),
+    ("bool", "object"): _view_wrapper(
+        libalgos.take_2d_multi_bool_object, np.uint8, None
+    ),
+    ("datetime64[ns]", "datetime64[ns]"): _view_wrapper(
+        libalgos.take_2d_multi_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+    ("timedelta64[ns]", "timedelta64[ns]"): _view_wrapper(
+        libalgos.take_2d_multi_int64_int64, np.int64, np.int64, fill_wrap=np.int64
+    ),
+}
+
+
+def _take_nd_object(
+    arr: np.ndarray,
+    indexer: npt.NDArray[np.intp],
+    out: np.ndarray,
+    axis: AxisInt,
+    fill_value,
+    mask_info,
+) -> None:
+    if mask_info is not None:
+        mask, needs_masking = mask_info
+    else:
+        mask = indexer == -1
+        needs_masking = mask.any()
+    if arr.dtype != out.dtype:
+        arr = arr.astype(out.dtype)
+    if arr.shape[axis] > 0:
+        arr.take(indexer, axis=axis, out=out)
+    if needs_masking:
+        outindexer = [slice(None)] * arr.ndim
+        outindexer[axis] = mask
+        out[tuple(outindexer)] = fill_value
+
+
+def _take_2d_multi_object(
+    arr: np.ndarray,
+    indexer: tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]],
+    out: np.ndarray,
+    fill_value,
+    mask_info,
+) -> None:
+    # this is not ideal, performance-wise, but it's better than raising
+    # an exception (best to optimize in Cython to avoid getting here)
+    row_idx, col_idx = indexer  # both np.intp
+    if mask_info is not None:
+        (row_mask, col_mask), (row_needs, col_needs) = mask_info
+    else:
+        row_mask = row_idx == -1
+        col_mask = col_idx == -1
+        row_needs = row_mask.any()
+        col_needs = col_mask.any()
+    if fill_value is not None:
+        if row_needs:
+            out[row_mask, :] = fill_value
+        if col_needs:
+            out[:, col_mask] = fill_value
+    for i, u_ in enumerate(row_idx):
+        if u_ != -1:
+            for j, v in enumerate(col_idx):
+                if v != -1:
+                    out[i, j] = arr[u_, v]
+
+
+def _take_preprocess_indexer_and_fill_value(
+    arr: np.ndarray,
+    indexer: npt.NDArray[np.intp],
+    fill_value,
+    allow_fill: bool,
+    mask: npt.NDArray[np.bool_] | None = None,
+):
+    mask_info: tuple[np.ndarray | None, bool] | None = None
+
+    if not allow_fill:
+        dtype, fill_value = arr.dtype, arr.dtype.type()
+        mask_info = None, False
+    else:
+        # check for promotion based on types only (do this first because
+        # it's faster than computing a mask)
+        dtype, fill_value = maybe_promote(arr.dtype, fill_value)
+        if dtype != arr.dtype:
+            # check if promotion is actually required based on indexer
+            if mask is not None:
+                needs_masking = True
+            else:
+                mask = indexer == -1
+                needs_masking = bool(mask.any())
+            mask_info = mask, needs_masking
+            if not needs_masking:
+                # if not, then depromote, set fill_value to dummy
+                # (it won't be used but we don't want the cython code
+                # to crash when trying to cast it to dtype)
+                dtype, fill_value = arr.dtype, arr.dtype.type()
+
+    return dtype, fill_value, mask_info
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/array_algos/transforms.py b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/transforms.py
new file mode 100644
index 0000000000000000000000000000000000000000..ec67244949e3db92cc811b19cdfcd5d1dd2b4de8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/array_algos/transforms.py
@@ -0,0 +1,50 @@
+"""
+transforms.py is for shape-preserving functions.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        AxisInt,
+        Scalar,
+    )
+
+
+def shift(
+    values: np.ndarray, periods: int, axis: AxisInt, fill_value: Scalar
+) -> np.ndarray:
+    new_values = values
+
+    if periods == 0 or values.size == 0:
+        return new_values.copy()
+
+    # make sure array sent to np.roll is c_contiguous
+    f_ordered = values.flags.f_contiguous
+    if f_ordered:
+        new_values = new_values.T
+        axis = new_values.ndim - axis - 1
+
+    if new_values.size:
+        new_values = np.roll(
+            new_values,
+            np.intp(periods),
+            axis=axis,
+        )
+
+    axis_indexer = [slice(None)] * values.ndim
+    if periods > 0:
+        axis_indexer[axis] = slice(None, periods)
+    else:
+        axis_indexer[axis] = slice(periods, None)
+    new_values[tuple(axis_indexer)] = fill_value
+
+    # restore original order
+    if f_ordered:
+        new_values = new_values.T
+
+    return new_values
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arraylike.py b/.venv/lib/python3.13/site-packages/pandas/core/arraylike.py
new file mode 100644
index 0000000000000000000000000000000000000000..fd585b3e1946880ca79f97b0b6d4a2990bdd32d1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arraylike.py
@@ -0,0 +1,530 @@
+"""
+Methods that can be shared by many array-like classes or subclasses:
+    Series
+    Index
+    ExtensionArray
+"""
+from __future__ import annotations
+
+import operator
+from typing import Any
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.ops_dispatch import maybe_dispatch_ufunc_to_dunder_op
+
+from pandas.core.dtypes.generic import ABCNDFrame
+
+from pandas.core import roperator
+from pandas.core.construction import extract_array
+from pandas.core.ops.common import unpack_zerodim_and_defer
+
+REDUCTION_ALIASES = {
+    "maximum": "max",
+    "minimum": "min",
+    "add": "sum",
+    "multiply": "prod",
+}
+
+
+class OpsMixin:
+    # -------------------------------------------------------------
+    # Comparisons
+
+    def _cmp_method(self, other, op):
+        return NotImplemented
+
+    @unpack_zerodim_and_defer("__eq__")
+    def __eq__(self, other):
+        return self._cmp_method(other, operator.eq)
+
+    @unpack_zerodim_and_defer("__ne__")
+    def __ne__(self, other):
+        return self._cmp_method(other, operator.ne)
+
+    @unpack_zerodim_and_defer("__lt__")
+    def __lt__(self, other):
+        return self._cmp_method(other, operator.lt)
+
+    @unpack_zerodim_and_defer("__le__")
+    def __le__(self, other):
+        return self._cmp_method(other, operator.le)
+
+    @unpack_zerodim_and_defer("__gt__")
+    def __gt__(self, other):
+        return self._cmp_method(other, operator.gt)
+
+    @unpack_zerodim_and_defer("__ge__")
+    def __ge__(self, other):
+        return self._cmp_method(other, operator.ge)
+
+    # -------------------------------------------------------------
+    # Logical Methods
+
+    def _logical_method(self, other, op):
+        return NotImplemented
+
+    @unpack_zerodim_and_defer("__and__")
+    def __and__(self, other):
+        return self._logical_method(other, operator.and_)
+
+    @unpack_zerodim_and_defer("__rand__")
+    def __rand__(self, other):
+        return self._logical_method(other, roperator.rand_)
+
+    @unpack_zerodim_and_defer("__or__")
+    def __or__(self, other):
+        return self._logical_method(other, operator.or_)
+
+    @unpack_zerodim_and_defer("__ror__")
+    def __ror__(self, other):
+        return self._logical_method(other, roperator.ror_)
+
+    @unpack_zerodim_and_defer("__xor__")
+    def __xor__(self, other):
+        return self._logical_method(other, operator.xor)
+
+    @unpack_zerodim_and_defer("__rxor__")
+    def __rxor__(self, other):
+        return self._logical_method(other, roperator.rxor)
+
+    # -------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _arith_method(self, other, op):
+        return NotImplemented
+
+    @unpack_zerodim_and_defer("__add__")
+    def __add__(self, other):
+        """
+        Get Addition of DataFrame and other, column-wise.
+
+        Equivalent to ``DataFrame.add(other)``.
+
+        Parameters
+        ----------
+        other : scalar, sequence, Series, dict or DataFrame
+            Object to be added to the DataFrame.
+
+        Returns
+        -------
+        DataFrame
+            The result of adding ``other`` to DataFrame.
+
+        See Also
+        --------
+        DataFrame.add : Add a DataFrame and another object, with option for index-
+            or column-oriented addition.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'height': [1.5, 2.6], 'weight': [500, 800]},
+        ...                   index=['elk', 'moose'])
+        >>> df
+               height  weight
+        elk       1.5     500
+        moose     2.6     800
+
+        Adding a scalar affects all rows and columns.
+
+        >>> df[['height', 'weight']] + 1.5
+               height  weight
+        elk       3.0   501.5
+        moose     4.1   801.5
+
+        Each element of a list is added to a column of the DataFrame, in order.
+
+        >>> df[['height', 'weight']] + [0.5, 1.5]
+               height  weight
+        elk       2.0   501.5
+        moose     3.1   801.5
+
+        Keys of a dictionary are aligned to the DataFrame, based on column names;
+        each value in the dictionary is added to the corresponding column.
+
+        >>> df[['height', 'weight']] + {'height': 0.5, 'weight': 1.5}
+               height  weight
+        elk       2.0   501.5
+        moose     3.1   801.5
+
+        When `other` is a :class:`Series`, the index of `other` is aligned with the
+        columns of the DataFrame.
+
+        >>> s1 = pd.Series([0.5, 1.5], index=['weight', 'height'])
+        >>> df[['height', 'weight']] + s1
+               height  weight
+        elk       3.0   500.5
+        moose     4.1   800.5
+
+        Even when the index of `other` is the same as the index of the DataFrame,
+        the :class:`Series` will not be reoriented. If index-wise alignment is desired,
+        :meth:`DataFrame.add` should be used with `axis='index'`.
+
+        >>> s2 = pd.Series([0.5, 1.5], index=['elk', 'moose'])
+        >>> df[['height', 'weight']] + s2
+               elk  height  moose  weight
+        elk    NaN     NaN    NaN     NaN
+        moose  NaN     NaN    NaN     NaN
+
+        >>> df[['height', 'weight']].add(s2, axis='index')
+               height  weight
+        elk       2.0   500.5
+        moose     4.1   801.5
+
+        When `other` is a :class:`DataFrame`, both columns names and the
+        index are aligned.
+
+        >>> other = pd.DataFrame({'height': [0.2, 0.4, 0.6]},
+        ...                      index=['elk', 'moose', 'deer'])
+        >>> df[['height', 'weight']] + other
+               height  weight
+        deer      NaN     NaN
+        elk       1.7     NaN
+        moose     3.0     NaN
+        """
+        return self._arith_method(other, operator.add)
+
+    @unpack_zerodim_and_defer("__radd__")
+    def __radd__(self, other):
+        return self._arith_method(other, roperator.radd)
+
+    @unpack_zerodim_and_defer("__sub__")
+    def __sub__(self, other):
+        return self._arith_method(other, operator.sub)
+
+    @unpack_zerodim_and_defer("__rsub__")
+    def __rsub__(self, other):
+        return self._arith_method(other, roperator.rsub)
+
+    @unpack_zerodim_and_defer("__mul__")
+    def __mul__(self, other):
+        return self._arith_method(other, operator.mul)
+
+    @unpack_zerodim_and_defer("__rmul__")
+    def __rmul__(self, other):
+        return self._arith_method(other, roperator.rmul)
+
+    @unpack_zerodim_and_defer("__truediv__")
+    def __truediv__(self, other):
+        return self._arith_method(other, operator.truediv)
+
+    @unpack_zerodim_and_defer("__rtruediv__")
+    def __rtruediv__(self, other):
+        return self._arith_method(other, roperator.rtruediv)
+
+    @unpack_zerodim_and_defer("__floordiv__")
+    def __floordiv__(self, other):
+        return self._arith_method(other, operator.floordiv)
+
+    @unpack_zerodim_and_defer("__rfloordiv")
+    def __rfloordiv__(self, other):
+        return self._arith_method(other, roperator.rfloordiv)
+
+    @unpack_zerodim_and_defer("__mod__")
+    def __mod__(self, other):
+        return self._arith_method(other, operator.mod)
+
+    @unpack_zerodim_and_defer("__rmod__")
+    def __rmod__(self, other):
+        return self._arith_method(other, roperator.rmod)
+
+    @unpack_zerodim_and_defer("__divmod__")
+    def __divmod__(self, other):
+        return self._arith_method(other, divmod)
+
+    @unpack_zerodim_and_defer("__rdivmod__")
+    def __rdivmod__(self, other):
+        return self._arith_method(other, roperator.rdivmod)
+
+    @unpack_zerodim_and_defer("__pow__")
+    def __pow__(self, other):
+        return self._arith_method(other, operator.pow)
+
+    @unpack_zerodim_and_defer("__rpow__")
+    def __rpow__(self, other):
+        return self._arith_method(other, roperator.rpow)
+
+
+# -----------------------------------------------------------------------------
+# Helpers to implement __array_ufunc__
+
+
+def array_ufunc(self, ufunc: np.ufunc, method: str, *inputs: Any, **kwargs: Any):
+    """
+    Compatibility with numpy ufuncs.
+
+    See also
+    --------
+    numpy.org/doc/stable/reference/arrays.classes.html#numpy.class.__array_ufunc__
+    """
+    from pandas.core.frame import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.generic import NDFrame
+    from pandas.core.internals import (
+        ArrayManager,
+        BlockManager,
+    )
+
+    cls = type(self)
+
+    kwargs = _standardize_out_kwarg(**kwargs)
+
+    # for binary ops, use our custom dunder methods
+    result = maybe_dispatch_ufunc_to_dunder_op(self, ufunc, method, *inputs, **kwargs)
+    if result is not NotImplemented:
+        return result
+
+    # Determine if we should defer.
+    no_defer = (
+        np.ndarray.__array_ufunc__,
+        cls.__array_ufunc__,
+    )
+
+    for item in inputs:
+        higher_priority = (
+            hasattr(item, "__array_priority__")
+            and item.__array_priority__ > self.__array_priority__
+        )
+        has_array_ufunc = (
+            hasattr(item, "__array_ufunc__")
+            and type(item).__array_ufunc__ not in no_defer
+            and not isinstance(item, self._HANDLED_TYPES)
+        )
+        if higher_priority or has_array_ufunc:
+            return NotImplemented
+
+    # align all the inputs.
+    types = tuple(type(x) for x in inputs)
+    alignable = [x for x, t in zip(inputs, types) if issubclass(t, NDFrame)]
+
+    if len(alignable) > 1:
+        # This triggers alignment.
+        # At the moment, there aren't any ufuncs with more than two inputs
+        # so this ends up just being x1.index | x2.index, but we write
+        # it to handle *args.
+        set_types = set(types)
+        if len(set_types) > 1 and {DataFrame, Series}.issubset(set_types):
+            # We currently don't handle ufunc(DataFrame, Series)
+            # well. Previously this raised an internal ValueError. We might
+            # support it someday, so raise a NotImplementedError.
+            raise NotImplementedError(
+                f"Cannot apply ufunc {ufunc} to mixed DataFrame and Series inputs."
+            )
+        axes = self.axes
+        for obj in alignable[1:]:
+            # this relies on the fact that we aren't handling mixed
+            # series / frame ufuncs.
+            for i, (ax1, ax2) in enumerate(zip(axes, obj.axes)):
+                axes[i] = ax1.union(ax2)
+
+        reconstruct_axes = dict(zip(self._AXIS_ORDERS, axes))
+        inputs = tuple(
+            x.reindex(**reconstruct_axes) if issubclass(t, NDFrame) else x
+            for x, t in zip(inputs, types)
+        )
+    else:
+        reconstruct_axes = dict(zip(self._AXIS_ORDERS, self.axes))
+
+    if self.ndim == 1:
+        names = [getattr(x, "name") for x in inputs if hasattr(x, "name")]
+        name = names[0] if len(set(names)) == 1 else None
+        reconstruct_kwargs = {"name": name}
+    else:
+        reconstruct_kwargs = {}
+
+    def reconstruct(result):
+        if ufunc.nout > 1:
+            # np.modf, np.frexp, np.divmod
+            return tuple(_reconstruct(x) for x in result)
+
+        return _reconstruct(result)
+
+    def _reconstruct(result):
+        if lib.is_scalar(result):
+            return result
+
+        if result.ndim != self.ndim:
+            if method == "outer":
+                raise NotImplementedError
+            return result
+        if isinstance(result, (BlockManager, ArrayManager)):
+            # we went through BlockManager.apply e.g. np.sqrt
+            result = self._constructor_from_mgr(result, axes=result.axes)
+        else:
+            # we converted an array, lost our axes
+            result = self._constructor(
+                result, **reconstruct_axes, **reconstruct_kwargs, copy=False
+            )
+        # TODO: When we support multiple values in __finalize__, this
+        # should pass alignable to `__finalize__` instead of self.
+        # Then `np.add(a, b)` would consider attrs from both a and b
+        # when a and b are NDFrames.
+        if len(alignable) == 1:
+            result = result.__finalize__(self)
+        return result
+
+    if "out" in kwargs:
+        # e.g. test_multiindex_get_loc
+        result = dispatch_ufunc_with_out(self, ufunc, method, *inputs, **kwargs)
+        return reconstruct(result)
+
+    if method == "reduce":
+        # e.g. test.series.test_ufunc.test_reduce
+        result = dispatch_reduction_ufunc(self, ufunc, method, *inputs, **kwargs)
+        if result is not NotImplemented:
+            return result
+
+    # We still get here with kwargs `axis` for e.g. np.maximum.accumulate
+    #  and `dtype` and `keepdims` for np.ptp
+
+    if self.ndim > 1 and (len(inputs) > 1 or ufunc.nout > 1):
+        # Just give up on preserving types in the complex case.
+        # In theory we could preserve them for them.
+        # * nout>1 is doable if BlockManager.apply took nout and
+        #   returned a Tuple[BlockManager].
+        # * len(inputs) > 1 is doable when we know that we have
+        #   aligned blocks / dtypes.
+
+        # e.g. my_ufunc, modf, logaddexp, heaviside, subtract, add
+        inputs = tuple(np.asarray(x) for x in inputs)
+        # Note: we can't use default_array_ufunc here bc reindexing means
+        #  that `self` may not be among `inputs`
+        result = getattr(ufunc, method)(*inputs, **kwargs)
+    elif self.ndim == 1:
+        # ufunc(series, ...)
+        inputs = tuple(extract_array(x, extract_numpy=True) for x in inputs)
+        result = getattr(ufunc, method)(*inputs, **kwargs)
+    else:
+        # ufunc(dataframe)
+        if method == "__call__" and not kwargs:
+            # for np.(..) calls
+            # kwargs cannot necessarily be handled block-by-block, so only
+            # take this path if there are no kwargs
+            mgr = inputs[0]._mgr
+            result = mgr.apply(getattr(ufunc, method))
+        else:
+            # otherwise specific ufunc methods (eg np..accumulate(..))
+            # Those can have an axis keyword and thus can't be called block-by-block
+            result = default_array_ufunc(inputs[0], ufunc, method, *inputs, **kwargs)
+            # e.g. np.negative (only one reached), with "where" and "out" in kwargs
+
+    result = reconstruct(result)
+    return result
+
+
+def _standardize_out_kwarg(**kwargs) -> dict:
+    """
+    If kwargs contain "out1" and "out2", replace that with a tuple "out"
+
+    np.divmod, np.modf, np.frexp can have either `out=(out1, out2)` or
+    `out1=out1, out2=out2)`
+    """
+    if "out" not in kwargs and "out1" in kwargs and "out2" in kwargs:
+        out1 = kwargs.pop("out1")
+        out2 = kwargs.pop("out2")
+        out = (out1, out2)
+        kwargs["out"] = out
+    return kwargs
+
+
+def dispatch_ufunc_with_out(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+    """
+    If we have an `out` keyword, then call the ufunc without `out` and then
+    set the result into the given `out`.
+    """
+
+    # Note: we assume _standardize_out_kwarg has already been called.
+    out = kwargs.pop("out")
+    where = kwargs.pop("where", None)
+
+    result = getattr(ufunc, method)(*inputs, **kwargs)
+
+    if result is NotImplemented:
+        return NotImplemented
+
+    if isinstance(result, tuple):
+        # i.e. np.divmod, np.modf, np.frexp
+        if not isinstance(out, tuple) or len(out) != len(result):
+            raise NotImplementedError
+
+        for arr, res in zip(out, result):
+            _assign_where(arr, res, where)
+
+        return out
+
+    if isinstance(out, tuple):
+        if len(out) == 1:
+            out = out[0]
+        else:
+            raise NotImplementedError
+
+    _assign_where(out, result, where)
+    return out
+
+
+def _assign_where(out, result, where) -> None:
+    """
+    Set a ufunc result into 'out', masking with a 'where' argument if necessary.
+    """
+    if where is None:
+        # no 'where' arg passed to ufunc
+        out[:] = result
+    else:
+        np.putmask(out, where, result)
+
+
+def default_array_ufunc(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+    """
+    Fallback to the behavior we would get if we did not define __array_ufunc__.
+
+    Notes
+    -----
+    We are assuming that `self` is among `inputs`.
+    """
+    if not any(x is self for x in inputs):
+        raise NotImplementedError
+
+    new_inputs = [x if x is not self else np.asarray(x) for x in inputs]
+
+    return getattr(ufunc, method)(*new_inputs, **kwargs)
+
+
+def dispatch_reduction_ufunc(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+    """
+    Dispatch ufunc reductions to self's reduction methods.
+    """
+    assert method == "reduce"
+
+    if len(inputs) != 1 or inputs[0] is not self:
+        return NotImplemented
+
+    if ufunc.__name__ not in REDUCTION_ALIASES:
+        return NotImplemented
+
+    method_name = REDUCTION_ALIASES[ufunc.__name__]
+
+    # NB: we are assuming that min/max represent minimum/maximum methods,
+    #  which would not be accurate for e.g. Timestamp.min
+    if not hasattr(self, method_name):
+        return NotImplemented
+
+    if self.ndim > 1:
+        if isinstance(self, ABCNDFrame):
+            # TODO: test cases where this doesn't hold, i.e. 2D DTA/TDA
+            kwargs["numeric_only"] = False
+
+        if "axis" not in kwargs:
+            # For DataFrame reductions we don't want the default axis=0
+            # Note: np.min is not a ufunc, but uses array_function_dispatch,
+            #  so calls DataFrame.min (without ever getting here) with the np.min
+            #  default of axis=None, which DataFrame.min catches and changes to axis=0.
+            # np.minimum.reduce(df) gets here bc axis is not in kwargs,
+            #  so we set axis=0 to match the behaviorof np.minimum.reduce(df.values)
+            kwargs["axis"] = 0
+
+    # By default, numpy's reductions do not skip NaNs, so we have to
+    #  pass skipna=False
+    return getattr(self, method_name)(skipna=False, **kwargs)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..245a171fea74bc9409a315b64d157a37b3da6eaa
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/__init__.py
@@ -0,0 +1,43 @@
+from pandas.core.arrays.arrow import ArrowExtensionArray
+from pandas.core.arrays.base import (
+    ExtensionArray,
+    ExtensionOpsMixin,
+    ExtensionScalarOpsMixin,
+)
+from pandas.core.arrays.boolean import BooleanArray
+from pandas.core.arrays.categorical import Categorical
+from pandas.core.arrays.datetimes import DatetimeArray
+from pandas.core.arrays.floating import FloatingArray
+from pandas.core.arrays.integer import IntegerArray
+from pandas.core.arrays.interval import IntervalArray
+from pandas.core.arrays.masked import BaseMaskedArray
+from pandas.core.arrays.numpy_ import NumpyExtensionArray
+from pandas.core.arrays.period import (
+    PeriodArray,
+    period_array,
+)
+from pandas.core.arrays.sparse import SparseArray
+from pandas.core.arrays.string_ import StringArray
+from pandas.core.arrays.string_arrow import ArrowStringArray
+from pandas.core.arrays.timedeltas import TimedeltaArray
+
+__all__ = [
+    "ArrowExtensionArray",
+    "ExtensionArray",
+    "ExtensionOpsMixin",
+    "ExtensionScalarOpsMixin",
+    "ArrowStringArray",
+    "BaseMaskedArray",
+    "BooleanArray",
+    "Categorical",
+    "DatetimeArray",
+    "FloatingArray",
+    "IntegerArray",
+    "IntervalArray",
+    "NumpyExtensionArray",
+    "PeriodArray",
+    "period_array",
+    "SparseArray",
+    "StringArray",
+    "TimedeltaArray",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/_arrow_string_mixins.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_arrow_string_mixins.py
new file mode 100644
index 0000000000000000000000000000000000000000..c99ee7d02a2260fb48b40d2bf5048fc960d47b2e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_arrow_string_mixins.py
@@ -0,0 +1,377 @@
+from __future__ import annotations
+
+from functools import partial
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.compat import (
+    pa_version_under10p1,
+    pa_version_under11p0,
+    pa_version_under13p0,
+    pa_version_under17p0,
+    pa_version_under21p0,
+)
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+    import pyarrow.compute as pc
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from pandas._typing import (
+        Scalar,
+        Self,
+    )
+
+
+class ArrowStringArrayMixin:
+    _pa_array: pa.ChunkedArray
+
+    def __init__(self, *args, **kwargs) -> None:
+        raise NotImplementedError
+
+    def _convert_bool_result(self, result, na=lib.no_default, method_name=None):
+        # Convert a bool-dtype result to the appropriate result type
+        raise NotImplementedError
+
+    def _convert_int_result(self, result):
+        # Convert an integer-dtype result to the appropriate result type
+        raise NotImplementedError
+
+    def _apply_elementwise(self, func: Callable) -> list[list[Any]]:
+        raise NotImplementedError
+
+    def _str_len(self):
+        result = pc.utf8_length(self._pa_array)
+        return self._convert_int_result(result)
+
+    def _str_lower(self) -> Self:
+        return type(self)(pc.utf8_lower(self._pa_array))
+
+    def _str_upper(self) -> Self:
+        return type(self)(pc.utf8_upper(self._pa_array))
+
+    def _str_strip(self, to_strip=None) -> Self:
+        if to_strip is None:
+            result = pc.utf8_trim_whitespace(self._pa_array)
+        else:
+            result = pc.utf8_trim(self._pa_array, characters=to_strip)
+        return type(self)(result)
+
+    def _str_lstrip(self, to_strip=None) -> Self:
+        if to_strip is None:
+            result = pc.utf8_ltrim_whitespace(self._pa_array)
+        else:
+            result = pc.utf8_ltrim(self._pa_array, characters=to_strip)
+        return type(self)(result)
+
+    def _str_rstrip(self, to_strip=None) -> Self:
+        if to_strip is None:
+            result = pc.utf8_rtrim_whitespace(self._pa_array)
+        else:
+            result = pc.utf8_rtrim(self._pa_array, characters=to_strip)
+        return type(self)(result)
+
+    def _str_pad(
+        self,
+        width: int,
+        side: Literal["left", "right", "both"] = "left",
+        fillchar: str = " ",
+    ):
+        if side == "left":
+            pa_pad = pc.utf8_lpad
+        elif side == "right":
+            pa_pad = pc.utf8_rpad
+        elif side == "both":
+            if pa_version_under17p0:
+                # GH#59624 fall back to object dtype
+                from pandas import array as pd_array
+
+                obj_arr = self.astype(object, copy=False)  # type: ignore[attr-defined]
+                obj = pd_array(obj_arr, dtype=object)
+                result = obj._str_pad(width, side, fillchar)  # type: ignore[attr-defined]
+                return type(self)._from_sequence(result, dtype=self.dtype)  # type: ignore[attr-defined]
+            else:
+                # GH#54792
+                # https://github.com/apache/arrow/issues/15053#issuecomment-2317032347
+                lean_left = (width % 2) == 0
+                pa_pad = partial(pc.utf8_center, lean_left_on_odd_padding=lean_left)
+        else:
+            raise ValueError(
+                f"Invalid side: {side}. Side must be one of 'left', 'right', 'both'"
+            )
+        return type(self)(pa_pad(self._pa_array, width=width, padding=fillchar))
+
+    def _str_get(self, i: int):
+        lengths = pc.utf8_length(self._pa_array)
+        if i >= 0:
+            out_of_bounds = pc.greater_equal(i, lengths)
+            start = i
+            stop = i + 1
+            step = 1
+        else:
+            out_of_bounds = pc.greater(-i, lengths)
+            start = i
+            stop = i - 1
+            step = -1
+        not_out_of_bounds = pc.invert(out_of_bounds.fill_null(True))
+        selected = pc.utf8_slice_codeunits(
+            self._pa_array, start=start, stop=stop, step=step
+        )
+        null_value = pa.scalar(None, type=self._pa_array.type)
+        result = pc.if_else(not_out_of_bounds, selected, null_value)
+        return type(self)(result)
+
+    def _str_slice(
+        self, start: int | None = None, stop: int | None = None, step: int | None = None
+    ):
+        if pa_version_under11p0:
+            # GH#59724
+            result = self._apply_elementwise(lambda val: val[start:stop:step])
+            return type(self)(pa.chunked_array(result, type=self._pa_array.type))
+        if start is None:
+            if step is not None and step < 0:
+                # GH#59710
+                start = -1
+            else:
+                start = 0
+        if step is None:
+            step = 1
+        return type(self)(
+            pc.utf8_slice_codeunits(self._pa_array, start=start, stop=stop, step=step)
+        )
+
+    def _str_slice_replace(
+        self, start: int | None = None, stop: int | None = None, repl: str | None = None
+    ):
+        if repl is None:
+            repl = ""
+        if start is None:
+            start = 0
+        if stop is None:
+            stop = np.iinfo(np.int64).max
+        return type(self)(pc.utf8_replace_slice(self._pa_array, start, stop, repl))
+
+    def _str_replace(
+        self,
+        pat: str | re.Pattern,
+        repl: str | Callable,
+        n: int = -1,
+        case: bool = True,
+        flags: int = 0,
+        regex: bool = True,
+    ) -> Self:
+        if (
+            isinstance(pat, re.Pattern)
+            or callable(repl)
+            or not case
+            or flags
+            or (
+                isinstance(repl, str)
+                and (r"\g<" in repl or re.search(r"\\\d", repl) is not None)
+            )
+        ):
+            raise NotImplementedError(
+                "replace is not supported with a re.Pattern, callable repl, "
+                "case=False, flags!=0, or when the replacement string contains "
+                "named group references (\\g<...>, \\d+)"
+            )
+
+        func = pc.replace_substring_regex if regex else pc.replace_substring
+        # https://github.com/apache/arrow/issues/39149
+        # GH 56404, unexpected behavior with negative max_replacements with pyarrow.
+        pa_max_replacements = None if n < 0 else n
+        result = func(
+            self._pa_array,
+            pattern=pat,
+            replacement=repl,
+            max_replacements=pa_max_replacements,
+        )
+        return type(self)(result)
+
+    def _str_capitalize(self) -> Self:
+        return type(self)(pc.utf8_capitalize(self._pa_array))
+
+    def _str_title(self):
+        return type(self)(pc.utf8_title(self._pa_array))
+
+    def _str_swapcase(self):
+        return type(self)(pc.utf8_swapcase(self._pa_array))
+
+    def _str_removeprefix(self, prefix: str):
+        if not pa_version_under13p0:
+            starts_with = pc.starts_with(self._pa_array, pattern=prefix)
+            removed = pc.utf8_slice_codeunits(self._pa_array, len(prefix))
+            result = pc.if_else(starts_with, removed, self._pa_array)
+            return type(self)(result)
+        predicate = lambda val: val.removeprefix(prefix)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_removesuffix(self, suffix: str):
+        ends_with = pc.ends_with(self._pa_array, pattern=suffix)
+        removed = pc.utf8_slice_codeunits(self._pa_array, 0, stop=-len(suffix))
+        result = pc.if_else(ends_with, removed, self._pa_array)
+        return type(self)(result)
+
+    def _str_startswith(
+        self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default
+    ):
+        if isinstance(pat, str):
+            result = pc.starts_with(self._pa_array, pattern=pat)
+        else:
+            if len(pat) == 0:
+                # For empty tuple we return null for missing values and False
+                #  for valid values.
+                result = pc.if_else(pc.is_null(self._pa_array), None, False)
+            else:
+                result = pc.starts_with(self._pa_array, pattern=pat[0])
+
+                for p in pat[1:]:
+                    result = pc.or_(result, pc.starts_with(self._pa_array, pattern=p))
+        return self._convert_bool_result(result, na=na, method_name="startswith")
+
+    def _str_endswith(
+        self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default
+    ):
+        if isinstance(pat, str):
+            result = pc.ends_with(self._pa_array, pattern=pat)
+        else:
+            if len(pat) == 0:
+                # For empty tuple we return null for missing values and False
+                #  for valid values.
+                result = pc.if_else(pc.is_null(self._pa_array), None, False)
+            else:
+                result = pc.ends_with(self._pa_array, pattern=pat[0])
+
+                for p in pat[1:]:
+                    result = pc.or_(result, pc.ends_with(self._pa_array, pattern=p))
+        return self._convert_bool_result(result, na=na, method_name="endswith")
+
+    def _str_isalnum(self):
+        result = pc.utf8_is_alnum(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isalpha(self):
+        result = pc.utf8_is_alpha(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isdecimal(self):
+        result = pc.utf8_is_decimal(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isdigit(self):
+        if pa_version_under21p0:
+            # https://github.com/pandas-dev/pandas/issues/61466
+            res_list = self._apply_elementwise(str.isdigit)
+            return self._convert_bool_result(
+                pa.chunked_array(res_list, type=pa.bool_())
+            )
+        result = pc.utf8_is_digit(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_islower(self):
+        result = pc.utf8_is_lower(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isnumeric(self):
+        result = pc.utf8_is_numeric(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isspace(self):
+        result = pc.utf8_is_space(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_istitle(self):
+        result = pc.utf8_is_title(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_isupper(self):
+        result = pc.utf8_is_upper(self._pa_array)
+        return self._convert_bool_result(result)
+
+    def _str_contains(
+        self,
+        pat,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+        regex: bool = True,
+    ):
+        if flags:
+            raise NotImplementedError(f"contains not implemented with {flags=}")
+
+        if regex:
+            pa_contains = pc.match_substring_regex
+        else:
+            pa_contains = pc.match_substring
+        result = pa_contains(self._pa_array, pat, ignore_case=not case)
+        return self._convert_bool_result(result, na=na, method_name="contains")
+
+    def _str_match(
+        self,
+        pat: str,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if not pat.startswith("^"):
+            pat = f"^({pat})"
+        return self._str_contains(pat, case, flags, na, regex=True)
+
+    def _str_fullmatch(
+        self,
+        pat: str,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if (not pat.endswith("$") or pat.endswith("\\$")) and not pat.startswith("^"):
+            pat = f"^({pat})$"
+        elif not pat.endswith("$") or pat.endswith("\\$"):
+            pat = f"^({pat[1:]})$"
+        elif not pat.startswith("^"):
+            pat = f"^({pat[0:-1]})$"
+        return self._str_match(pat, case, flags, na)
+
+    def _str_find(self, sub: str, start: int = 0, end: int | None = None):
+        if (
+            pa_version_under13p0
+            and not (start != 0 and end is not None)
+            and not (start == 0 and end is None)
+        ):
+            # GH#59562
+            res_list = self._apply_elementwise(lambda val: val.find(sub, start, end))
+            return self._convert_int_result(pa.chunked_array(res_list))
+
+        if (start == 0 or start is None) and end is None:
+            result = pc.find_substring(self._pa_array, sub)
+        else:
+            if sub == "":
+                # GH#56792
+                res_list = self._apply_elementwise(
+                    lambda val: val.find(sub, start, end)
+                )
+                return self._convert_int_result(pa.chunked_array(res_list))
+            if start is None:
+                start_offset = 0
+                start = 0
+            elif start < 0:
+                start_offset = pc.add(start, pc.utf8_length(self._pa_array))
+                start_offset = pc.if_else(pc.less(start_offset, 0), 0, start_offset)
+            else:
+                start_offset = start
+            slices = pc.utf8_slice_codeunits(self._pa_array, start, stop=end)
+            result = pc.find_substring(slices, sub)
+            found = pc.not_equal(result, pa.scalar(-1, type=result.type))
+            offset_result = pc.add(result, start_offset)
+            result = pc.if_else(found, offset_result, -1)
+        return self._convert_int_result(result)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/_mixins.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_mixins.py
new file mode 100644
index 0000000000000000000000000000000000000000..cb6861a8dd00ff29edb398f0a8cc6ca73205c78d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_mixins.py
@@ -0,0 +1,544 @@
+from __future__ import annotations
+
+from functools import wraps
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.arrays import NDArrayBacked
+from pandas._libs.tslibs import is_supported_dtype
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    Dtype,
+    F,
+    FillnaOptions,
+    PositionalIndexer2D,
+    PositionalIndexerTuple,
+    ScalarIndexer,
+    Self,
+    SequenceIndexer,
+    Shape,
+    TakeIndexer,
+    npt,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import doc
+from pandas.util._validators import (
+    validate_bool_kwarg,
+    validate_fillna_kwargs,
+    validate_insert_loc,
+)
+
+from pandas.core.dtypes.common import pandas_dtype
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    ExtensionDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.missing import array_equivalent
+
+from pandas.core import missing
+from pandas.core.algorithms import (
+    take,
+    unique,
+    value_counts_internal as value_counts,
+)
+from pandas.core.array_algos.quantile import quantile_with_mask
+from pandas.core.array_algos.transforms import shift
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.construction import extract_array
+from pandas.core.indexers import check_array_indexer
+from pandas.core.sorting import nargminmax
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        NumpySorter,
+        NumpyValueArrayLike,
+    )
+
+    from pandas import Series
+
+
+def ravel_compat(meth: F) -> F:
+    """
+    Decorator to ravel a 2D array before passing it to a cython operation,
+    then reshape the result to our own shape.
+    """
+
+    @wraps(meth)
+    def method(self, *args, **kwargs):
+        if self.ndim == 1:
+            return meth(self, *args, **kwargs)
+
+        flags = self._ndarray.flags
+        flat = self.ravel("K")
+        result = meth(flat, *args, **kwargs)
+        order = "F" if flags.f_contiguous else "C"
+        return result.reshape(self.shape, order=order)
+
+    return cast(F, method)
+
+
+class NDArrayBackedExtensionArray(NDArrayBacked, ExtensionArray):
+    """
+    ExtensionArray that is backed by a single NumPy ndarray.
+    """
+
+    _ndarray: np.ndarray
+
+    # scalar used to denote NA value inside our self._ndarray, e.g. -1
+    #  for Categorical, iNaT for Period. Outside of object dtype,
+    #  self.isna() should be exactly locations in self._ndarray with
+    #  _internal_fill_value.
+    _internal_fill_value: Any
+
+    def _box_func(self, x):
+        """
+        Wrap numpy type in our dtype.type if necessary.
+        """
+        return x
+
+    def _validate_scalar(self, value):
+        # used by NDArrayBackedExtensionIndex.insert
+        raise AbstractMethodError(self)
+
+    # ------------------------------------------------------------------------
+
+    def view(self, dtype: Dtype | None = None) -> ArrayLike:
+        # We handle datetime64, datetime64tz, timedelta64, and period
+        #  dtypes here. Everything else we pass through to the underlying
+        #  ndarray.
+        if dtype is None or dtype is self.dtype:
+            return self._from_backing_data(self._ndarray)
+
+        if isinstance(dtype, type):
+            # we sometimes pass non-dtype objects, e.g np.ndarray;
+            #  pass those through to the underlying ndarray
+            return self._ndarray.view(dtype)
+
+        dtype = pandas_dtype(dtype)
+        arr = self._ndarray
+
+        if isinstance(dtype, PeriodDtype):
+            cls = dtype.construct_array_type()
+            return cls(arr.view("i8"), dtype=dtype)
+        elif isinstance(dtype, DatetimeTZDtype):
+            dt_cls = dtype.construct_array_type()
+            dt64_values = arr.view(f"M8[{dtype.unit}]")
+            return dt_cls._simple_new(dt64_values, dtype=dtype)
+        elif lib.is_np_dtype(dtype, "M") and is_supported_dtype(dtype):
+            from pandas.core.arrays import DatetimeArray
+
+            dt64_values = arr.view(dtype)
+            return DatetimeArray._simple_new(dt64_values, dtype=dtype)
+
+        elif lib.is_np_dtype(dtype, "m") and is_supported_dtype(dtype):
+            from pandas.core.arrays import TimedeltaArray
+
+            td64_values = arr.view(dtype)
+            return TimedeltaArray._simple_new(td64_values, dtype=dtype)
+
+        # error: Argument "dtype" to "view" of "_ArrayOrScalarCommon" has incompatible
+        # type "Union[ExtensionDtype, dtype[Any]]"; expected "Union[dtype[Any], None,
+        # type, _SupportsDType, str, Union[Tuple[Any, int], Tuple[Any, Union[int,
+        # Sequence[int]]], List[Any], _DTypeDict, Tuple[Any, Any]]]"
+        return arr.view(dtype=dtype)  # type: ignore[arg-type]
+
+    def take(
+        self,
+        indices: TakeIndexer,
+        *,
+        allow_fill: bool = False,
+        fill_value: Any = None,
+        axis: AxisInt = 0,
+    ) -> Self:
+        if allow_fill:
+            fill_value = self._validate_scalar(fill_value)
+
+        new_data = take(
+            self._ndarray,
+            indices,
+            allow_fill=allow_fill,
+            fill_value=fill_value,
+            axis=axis,
+        )
+        return self._from_backing_data(new_data)
+
+    # ------------------------------------------------------------------------
+
+    def equals(self, other) -> bool:
+        if type(self) is not type(other):
+            return False
+        if self.dtype != other.dtype:
+            return False
+        return bool(array_equivalent(self._ndarray, other._ndarray, dtype_equal=True))
+
+    @classmethod
+    def _from_factorized(cls, values, original):
+        assert values.dtype == original._ndarray.dtype
+        return original._from_backing_data(values)
+
+    def _values_for_argsort(self) -> np.ndarray:
+        return self._ndarray
+
+    def _values_for_factorize(self):
+        return self._ndarray, self._internal_fill_value
+
+    def _hash_pandas_object(
+        self, *, encoding: str, hash_key: str, categorize: bool
+    ) -> npt.NDArray[np.uint64]:
+        from pandas.core.util.hashing import hash_array
+
+        values = self._ndarray
+        return hash_array(
+            values, encoding=encoding, hash_key=hash_key, categorize=categorize
+        )
+
+    # Signature of "argmin" incompatible with supertype "ExtensionArray"
+    def argmin(self, axis: AxisInt = 0, skipna: bool = True):  # type: ignore[override]
+        # override base class by adding axis keyword
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return nargminmax(self, "argmin", axis=axis)
+
+    # Signature of "argmax" incompatible with supertype "ExtensionArray"
+    def argmax(self, axis: AxisInt = 0, skipna: bool = True):  # type: ignore[override]
+        # override base class by adding axis keyword
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return nargminmax(self, "argmax", axis=axis)
+
+    def unique(self) -> Self:
+        new_data = unique(self._ndarray)
+        return self._from_backing_data(new_data)
+
+    @classmethod
+    @doc(ExtensionArray._concat_same_type)
+    def _concat_same_type(
+        cls,
+        to_concat: Sequence[Self],
+        axis: AxisInt = 0,
+    ) -> Self:
+        if not lib.dtypes_all_equal([x.dtype for x in to_concat]):
+            dtypes = {str(x.dtype) for x in to_concat}
+            raise ValueError("to_concat must have the same dtype", dtypes)
+
+        return super()._concat_same_type(to_concat, axis=axis)
+
+    @doc(ExtensionArray.searchsorted)
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        npvalue = self._validate_setitem_value(value)
+        return self._ndarray.searchsorted(npvalue, side=side, sorter=sorter)
+
+    @doc(ExtensionArray.shift)
+    def shift(self, periods: int = 1, fill_value=None):
+        # NB: shift is always along axis=0
+        axis = 0
+        fill_value = self._validate_scalar(fill_value)
+        new_values = shift(self._ndarray, periods, axis, fill_value)
+
+        return self._from_backing_data(new_values)
+
+    def __setitem__(self, key, value) -> None:
+        key = check_array_indexer(self, key)
+        value = self._validate_setitem_value(value)
+        self._ndarray[key] = value
+
+    def _validate_setitem_value(self, value):
+        return value
+
+    @overload
+    def __getitem__(self, key: ScalarIndexer) -> Any:
+        ...
+
+    @overload
+    def __getitem__(
+        self,
+        key: SequenceIndexer | PositionalIndexerTuple,
+    ) -> Self:
+        ...
+
+    def __getitem__(
+        self,
+        key: PositionalIndexer2D,
+    ) -> Self | Any:
+        if lib.is_integer(key):
+            # fast-path
+            result = self._ndarray[key]
+            if self.ndim == 1:
+                return self._box_func(result)
+            return self._from_backing_data(result)
+
+        # error: Incompatible types in assignment (expression has type "ExtensionArray",
+        # variable has type "Union[int, slice, ndarray]")
+        key = extract_array(key, extract_numpy=True)  # type: ignore[assignment]
+        key = check_array_indexer(self, key)
+        result = self._ndarray[key]
+        if lib.is_scalar(result):
+            return self._box_func(result)
+
+        result = self._from_backing_data(result)
+        return result
+
+    def _fill_mask_inplace(
+        self, method: str, limit: int | None, mask: npt.NDArray[np.bool_]
+    ) -> None:
+        # (for now) when self.ndim == 2, we assume axis=0
+        func = missing.get_fill_func(method, ndim=self.ndim)
+        func(self._ndarray.T, limit=limit, mask=mask.T)
+
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        mask = self.isna()
+        if mask.any():
+            # (for now) when self.ndim == 2, we assume axis=0
+            func = missing.get_fill_func(method, ndim=self.ndim)
+
+            npvalues = self._ndarray.T
+            if copy:
+                npvalues = npvalues.copy()
+            func(npvalues, limit=limit, limit_area=limit_area, mask=mask.T)
+            npvalues = npvalues.T
+
+            if copy:
+                new_values = self._from_backing_data(npvalues)
+            else:
+                new_values = self
+
+        else:
+            if copy:
+                new_values = self.copy()
+            else:
+                new_values = self
+        return new_values
+
+    @doc(ExtensionArray.fillna)
+    def fillna(
+        self, value=None, method=None, limit: int | None = None, copy: bool = True
+    ) -> Self:
+        value, method = validate_fillna_kwargs(
+            value, method, validate_scalar_dict_value=False
+        )
+
+        mask = self.isna()
+        # error: Argument 2 to "check_value_size" has incompatible type
+        # "ExtensionArray"; expected "ndarray"
+        value = missing.check_value_size(
+            value, mask, len(self)  # type: ignore[arg-type]
+        )
+
+        if mask.any():
+            if method is not None:
+                # (for now) when self.ndim == 2, we assume axis=0
+                func = missing.get_fill_func(method, ndim=self.ndim)
+                npvalues = self._ndarray.T
+                if copy:
+                    npvalues = npvalues.copy()
+                func(npvalues, limit=limit, mask=mask.T)
+                npvalues = npvalues.T
+
+                # TODO: NumpyExtensionArray didn't used to copy, need tests
+                #  for this
+                new_values = self._from_backing_data(npvalues)
+            else:
+                # fill with value
+                if copy:
+                    new_values = self.copy()
+                else:
+                    new_values = self[:]
+                new_values[mask] = value
+        else:
+            # We validate the fill_value even if there is nothing to fill
+            if value is not None:
+                self._validate_setitem_value(value)
+
+            if not copy:
+                new_values = self[:]
+            else:
+                new_values = self.copy()
+        return new_values
+
+    # ------------------------------------------------------------------------
+    # Reductions
+
+    def _wrap_reduction_result(self, axis: AxisInt | None, result):
+        if axis is None or self.ndim == 1:
+            return self._box_func(result)
+        return self._from_backing_data(result)
+
+    # ------------------------------------------------------------------------
+    # __array_function__ methods
+
+    def _putmask(self, mask: npt.NDArray[np.bool_], value) -> None:
+        """
+        Analogue to np.putmask(self, mask, value)
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool]
+        value : scalar or listlike
+
+        Raises
+        ------
+        TypeError
+            If value cannot be cast to self.dtype.
+        """
+        value = self._validate_setitem_value(value)
+
+        np.putmask(self._ndarray, mask, value)
+
+    def _where(self: Self, mask: npt.NDArray[np.bool_], value) -> Self:
+        """
+        Analogue to np.where(mask, self, value)
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool]
+        value : scalar or listlike
+
+        Raises
+        ------
+        TypeError
+            If value cannot be cast to self.dtype.
+        """
+        value = self._validate_setitem_value(value)
+
+        res_values = np.where(mask, self._ndarray, value)
+        if res_values.dtype != self._ndarray.dtype:
+            raise AssertionError(
+                # GH#56410
+                "Something has gone wrong, please report a bug at "
+                "github.com/pandas-dev/pandas/"
+            )
+        return self._from_backing_data(res_values)
+
+    # ------------------------------------------------------------------------
+    # Index compat methods
+
+    def insert(self, loc: int, item) -> Self:
+        """
+        Make new ExtensionArray inserting new item at location. Follows
+        Python list.append semantics for negative values.
+
+        Parameters
+        ----------
+        loc : int
+        item : object
+
+        Returns
+        -------
+        type(self)
+        """
+        loc = validate_insert_loc(loc, len(self))
+
+        code = self._validate_scalar(item)
+
+        new_vals = np.concatenate(
+            (
+                self._ndarray[:loc],
+                np.asarray([code], dtype=self._ndarray.dtype),
+                self._ndarray[loc:],
+            )
+        )
+        return self._from_backing_data(new_vals)
+
+    # ------------------------------------------------------------------------
+    # Additional array methods
+    #  These are not part of the EA API, but we implement them because
+    #  pandas assumes they're there.
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Return a Series containing counts of unique values.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of NA values.
+
+        Returns
+        -------
+        Series
+        """
+        if self.ndim != 1:
+            raise NotImplementedError
+
+        from pandas import (
+            Index,
+            Series,
+        )
+
+        if dropna:
+            # error: Unsupported operand type for ~ ("ExtensionArray")
+            values = self[~self.isna()]._ndarray  # type: ignore[operator]
+        else:
+            values = self._ndarray
+
+        result = value_counts(values, sort=False, dropna=dropna)
+
+        index_arr = self._from_backing_data(np.asarray(result.index._data))
+        index = Index(index_arr, name=result.index.name)
+        return Series(result._values, index=index, name=result.name, copy=False)
+
+    def _quantile(
+        self,
+        qs: npt.NDArray[np.float64],
+        interpolation: str,
+    ) -> Self:
+        # TODO: disable for Categorical if not ordered?
+
+        mask = np.asarray(self.isna())
+        arr = self._ndarray
+        fill_value = self._internal_fill_value
+
+        res_values = quantile_with_mask(arr, mask, fill_value, qs, interpolation)
+        if res_values.dtype == self._ndarray.dtype:
+            return self._from_backing_data(res_values)
+        else:
+            # e.g. test_quantile_empty we are empty integer dtype and res_values
+            #  has floating dtype
+            # TODO: technically __init__ isn't defined here.
+            #  Should we raise NotImplementedError and handle this on NumpyEA?
+            return type(self)(res_values)  # type: ignore[call-arg]
+
+    # ------------------------------------------------------------------------
+    # numpy-like methods
+
+    @classmethod
+    def _empty(cls, shape: Shape, dtype: ExtensionDtype) -> Self:
+        """
+        Analogous to np.empty(shape, dtype=dtype)
+
+        Parameters
+        ----------
+        shape : tuple[int]
+        dtype : ExtensionDtype
+        """
+        # The base implementation uses a naive approach to find the dtype
+        #  for the backing ndarray
+        arr = cls._from_sequence([], dtype=dtype)
+        backing = np.empty(shape, dtype=arr._ndarray.dtype)
+        return arr._from_backing_data(backing)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/_ranges.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_ranges.py
new file mode 100644
index 0000000000000000000000000000000000000000..3e89391324ad4a90235da230250758662822678f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_ranges.py
@@ -0,0 +1,207 @@
+"""
+Helper functions to generate range-like data for DatetimeArray
+(and possibly TimedeltaArray/PeriodArray)
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs.lib import i8max
+from pandas._libs.tslibs import (
+    BaseOffset,
+    OutOfBoundsDatetime,
+    Timedelta,
+    Timestamp,
+    iNaT,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+
+def generate_regular_range(
+    start: Timestamp | Timedelta | None,
+    end: Timestamp | Timedelta | None,
+    periods: int | None,
+    freq: BaseOffset,
+    unit: str = "ns",
+) -> npt.NDArray[np.intp]:
+    """
+    Generate a range of dates or timestamps with the spans between dates
+    described by the given `freq` DateOffset.
+
+    Parameters
+    ----------
+    start : Timedelta, Timestamp or None
+        First point of produced date range.
+    end : Timedelta, Timestamp or None
+        Last point of produced date range.
+    periods : int or None
+        Number of periods in produced date range.
+    freq : Tick
+        Describes space between dates in produced date range.
+    unit : str, default "ns"
+        The resolution the output is meant to represent.
+
+    Returns
+    -------
+    ndarray[np.int64]
+        Representing the given resolution.
+    """
+    istart = start._value if start is not None else None
+    iend = end._value if end is not None else None
+    freq.nanos  # raises if non-fixed frequency
+    td = Timedelta(freq)
+    b: int
+    e: int
+    try:
+        td = td.as_unit(unit, round_ok=False)
+    except ValueError as err:
+        raise ValueError(
+            f"freq={freq} is incompatible with unit={unit}. "
+            "Use a lower freq or a higher unit instead."
+        ) from err
+    stride = int(td._value)
+
+    if periods is None and istart is not None and iend is not None:
+        b = istart
+        # cannot just use e = Timestamp(end) + 1 because arange breaks when
+        # stride is too large, see GH10887
+        e = b + (iend - b) // stride * stride + stride // 2 + 1
+    elif istart is not None and periods is not None:
+        b = istart
+        e = _generate_range_overflow_safe(b, periods, stride, side="start")
+    elif iend is not None and periods is not None:
+        e = iend + stride
+        b = _generate_range_overflow_safe(e, periods, stride, side="end")
+    else:
+        raise ValueError(
+            "at least 'start' or 'end' should be specified if a 'period' is given."
+        )
+
+    with np.errstate(over="raise"):
+        # If the range is sufficiently large, np.arange may overflow
+        #  and incorrectly return an empty array if not caught.
+        try:
+            values = np.arange(b, e, stride, dtype=np.int64)
+        except FloatingPointError:
+            xdr = [b]
+            while xdr[-1] != e:
+                xdr.append(xdr[-1] + stride)
+            values = np.array(xdr[:-1], dtype=np.int64)
+    return values
+
+
+def _generate_range_overflow_safe(
+    endpoint: int, periods: int, stride: int, side: str = "start"
+) -> int:
+    """
+    Calculate the second endpoint for passing to np.arange, checking
+    to avoid an integer overflow.  Catch OverflowError and re-raise
+    as OutOfBoundsDatetime.
+
+    Parameters
+    ----------
+    endpoint : int
+        nanosecond timestamp of the known endpoint of the desired range
+    periods : int
+        number of periods in the desired range
+    stride : int
+        nanoseconds between periods in the desired range
+    side : {'start', 'end'}
+        which end of the range `endpoint` refers to
+
+    Returns
+    -------
+    other_end : int
+
+    Raises
+    ------
+    OutOfBoundsDatetime
+    """
+    # GH#14187 raise instead of incorrectly wrapping around
+    assert side in ["start", "end"]
+
+    i64max = np.uint64(i8max)
+    msg = f"Cannot generate range with {side}={endpoint} and periods={periods}"
+
+    with np.errstate(over="raise"):
+        # if periods * strides cannot be multiplied within the *uint64* bounds,
+        #  we cannot salvage the operation by recursing, so raise
+        try:
+            addend = np.uint64(periods) * np.uint64(np.abs(stride))
+        except FloatingPointError as err:
+            raise OutOfBoundsDatetime(msg) from err
+
+    if np.abs(addend) <= i64max:
+        # relatively easy case without casting concerns
+        return _generate_range_overflow_safe_signed(endpoint, periods, stride, side)
+
+    elif (endpoint > 0 and side == "start" and stride > 0) or (
+        endpoint < 0 < stride and side == "end"
+    ):
+        # no chance of not-overflowing
+        raise OutOfBoundsDatetime(msg)
+
+    elif side == "end" and endpoint - stride <= i64max < endpoint:
+        # in _generate_regular_range we added `stride` thereby overflowing
+        #  the bounds.  Adjust to fix this.
+        return _generate_range_overflow_safe(
+            endpoint - stride, periods - 1, stride, side
+        )
+
+    # split into smaller pieces
+    mid_periods = periods // 2
+    remaining = periods - mid_periods
+    assert 0 < remaining < periods, (remaining, periods, endpoint, stride)
+
+    midpoint = int(_generate_range_overflow_safe(endpoint, mid_periods, stride, side))
+    return _generate_range_overflow_safe(midpoint, remaining, stride, side)
+
+
+def _generate_range_overflow_safe_signed(
+    endpoint: int, periods: int, stride: int, side: str
+) -> int:
+    """
+    A special case for _generate_range_overflow_safe where `periods * stride`
+    can be calculated without overflowing int64 bounds.
+    """
+    assert side in ["start", "end"]
+    if side == "end":
+        stride *= -1
+
+    with np.errstate(over="raise"):
+        addend = np.int64(periods) * np.int64(stride)
+        try:
+            # easy case with no overflows
+            result = np.int64(endpoint) + addend
+            if result == iNaT:
+                # Putting this into a DatetimeArray/TimedeltaArray
+                #  would incorrectly be interpreted as NaT
+                raise OverflowError
+            return int(result)
+        except (FloatingPointError, OverflowError):
+            # with endpoint negative and addend positive we risk
+            #  FloatingPointError; with reversed signed we risk OverflowError
+            pass
+
+        # if stride and endpoint had opposite signs, then endpoint + addend
+        #  should never overflow.  so they must have the same signs
+        assert (stride > 0 and endpoint >= 0) or (stride < 0 and endpoint <= 0)
+
+        if stride > 0:
+            # watch out for very special case in which we just slightly
+            #  exceed implementation bounds, but when passing the result to
+            #  np.arange will get a result slightly within the bounds
+
+            uresult = np.uint64(endpoint) + np.uint64(addend)
+            i64max = np.uint64(i8max)
+            assert uresult > i64max
+            if uresult <= i64max + np.uint64(stride):
+                return int(uresult)
+
+    raise OutOfBoundsDatetime(
+        f"Cannot generate range with {side}={endpoint} and periods={periods}"
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/_utils.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..6b46396d5efdfa4301a5362c8a5a71678345479b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/_utils.py
@@ -0,0 +1,63 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.errors import LossySetitemError
+
+from pandas.core.dtypes.cast import np_can_hold_element
+from pandas.core.dtypes.common import is_numeric_dtype
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        npt,
+    )
+
+
+def to_numpy_dtype_inference(
+    arr: ArrayLike, dtype: npt.DTypeLike | None, na_value, hasna: bool
+) -> tuple[npt.DTypeLike, Any]:
+    if dtype is None and is_numeric_dtype(arr.dtype):
+        dtype_given = False
+        if hasna:
+            if arr.dtype.kind == "b":
+                dtype = np.dtype(np.object_)
+            else:
+                if arr.dtype.kind in "iu":
+                    dtype = np.dtype(np.float64)
+                else:
+                    dtype = arr.dtype.numpy_dtype  # type: ignore[union-attr]
+                if na_value is lib.no_default:
+                    na_value = np.nan
+        else:
+            dtype = arr.dtype.numpy_dtype  # type: ignore[union-attr]
+    elif dtype is not None:
+        dtype = np.dtype(dtype)
+        dtype_given = True
+    else:
+        dtype_given = True
+
+    if na_value is lib.no_default:
+        if dtype is None or not hasna:
+            na_value = arr.dtype.na_value
+        elif dtype.kind == "f":  # type: ignore[union-attr]
+            na_value = np.nan
+        elif dtype.kind == "M":  # type: ignore[union-attr]
+            na_value = np.datetime64("nat")
+        elif dtype.kind == "m":  # type: ignore[union-attr]
+            na_value = np.timedelta64("nat")
+        else:
+            na_value = arr.dtype.na_value
+
+    if not dtype_given and hasna:
+        try:
+            np_can_hold_element(dtype, na_value)  # type: ignore[arg-type]
+        except LossySetitemError:
+            dtype = np.dtype(np.object_)
+    return dtype, na_value
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..5fc50f786fc6a6c51f78ef9ebd4ee6ed26a2bab3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/__init__.py
@@ -0,0 +1,7 @@
+from pandas.core.arrays.arrow.accessors import (
+    ListAccessor,
+    StructAccessor,
+)
+from pandas.core.arrays.arrow.array import ArrowExtensionArray
+
+__all__ = ["ArrowExtensionArray", "StructAccessor", "ListAccessor"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/_arrow_utils.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/_arrow_utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..285c3fd465ffcb9f507ebd1b3a0e3e6f55b76987
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/_arrow_utils.py
@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+import numpy as np
+import pyarrow
+
+
+def pyarrow_array_to_numpy_and_mask(
+    arr, dtype: np.dtype
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Convert a primitive pyarrow.Array to a numpy array and boolean mask based
+    on the buffers of the Array.
+
+    At the moment pyarrow.BooleanArray is not supported.
+
+    Parameters
+    ----------
+    arr : pyarrow.Array
+    dtype : numpy.dtype
+
+    Returns
+    -------
+    (data, mask)
+        Tuple of two numpy arrays with the raw data (with specified dtype) and
+        a boolean mask (validity mask, so False means missing)
+    """
+    dtype = np.dtype(dtype)
+
+    if pyarrow.types.is_null(arr.type):
+        # No initialization of data is needed since everything is null
+        data = np.empty(len(arr), dtype=dtype)
+        mask = np.zeros(len(arr), dtype=bool)
+        return data, mask
+    buflist = arr.buffers()
+    # Since Arrow buffers might contain padding and the data might be offset,
+    # the buffer gets sliced here before handing it to numpy.
+    # See also https://github.com/pandas-dev/pandas/issues/40896
+    offset = arr.offset * dtype.itemsize
+    length = len(arr) * dtype.itemsize
+    data_buf = buflist[1][offset : offset + length]
+    data = np.frombuffer(data_buf, dtype=dtype)
+    bitmask = buflist[0]
+    if bitmask is not None:
+        mask = pyarrow.BooleanArray.from_buffers(
+            pyarrow.bool_(), len(arr), [None, bitmask], offset=arr.offset
+        )
+        mask = np.asarray(mask)
+    else:
+        mask = np.ones(len(arr), dtype=bool)
+    return data, mask
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/accessors.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/accessors.py
new file mode 100644
index 0000000000000000000000000000000000000000..65f0784eaa3fd45e278cef083c3a606023827da0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/accessors.py
@@ -0,0 +1,473 @@
+"""Accessors for arrow-backed data."""
+
+from __future__ import annotations
+
+from abc import (
+    ABCMeta,
+    abstractmethod,
+)
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+from pandas.compat import (
+    pa_version_under10p1,
+    pa_version_under11p0,
+)
+
+from pandas.core.dtypes.common import is_list_like
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+    import pyarrow.compute as pc
+
+    from pandas.core.dtypes.dtypes import ArrowDtype
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+class ArrowAccessor(metaclass=ABCMeta):
+    @abstractmethod
+    def __init__(self, data, validation_msg: str) -> None:
+        self._data = data
+        self._validation_msg = validation_msg
+        self._validate(data)
+
+    @abstractmethod
+    def _is_valid_pyarrow_dtype(self, pyarrow_dtype) -> bool:
+        pass
+
+    def _validate(self, data):
+        dtype = data.dtype
+        if pa_version_under10p1 or not isinstance(dtype, ArrowDtype):
+            # Raise AttributeError so that inspect can handle non-struct Series.
+            raise AttributeError(self._validation_msg.format(dtype=dtype))
+
+        if not self._is_valid_pyarrow_dtype(dtype.pyarrow_dtype):
+            # Raise AttributeError so that inspect can handle invalid Series.
+            raise AttributeError(self._validation_msg.format(dtype=dtype))
+
+    @property
+    def _pa_array(self):
+        return self._data.array._pa_array
+
+
+class ListAccessor(ArrowAccessor):
+    """
+    Accessor object for list data properties of the Series values.
+
+    Parameters
+    ----------
+    data : Series
+        Series containing Arrow list data.
+    """
+
+    def __init__(self, data=None) -> None:
+        super().__init__(
+            data,
+            validation_msg="Can only use the '.list' accessor with "
+            "'list[pyarrow]' dtype, not {dtype}.",
+        )
+
+    def _is_valid_pyarrow_dtype(self, pyarrow_dtype) -> bool:
+        return (
+            pa.types.is_list(pyarrow_dtype)
+            or pa.types.is_fixed_size_list(pyarrow_dtype)
+            or pa.types.is_large_list(pyarrow_dtype)
+        )
+
+    def len(self) -> Series:
+        """
+        Return the length of each list in the Series.
+
+        Returns
+        -------
+        pandas.Series
+            The length of each list.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         [1, 2, 3],
+        ...         [3],
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.list_(
+        ...         pa.int64()
+        ...     ))
+        ... )
+        >>> s.list.len()
+        0    3
+        1    1
+        dtype: int32[pyarrow]
+        """
+        from pandas import Series
+
+        value_lengths = pc.list_value_length(self._pa_array)
+        return Series(value_lengths, dtype=ArrowDtype(value_lengths.type))
+
+    def __getitem__(self, key: int | slice) -> Series:
+        """
+        Index or slice lists in the Series.
+
+        Parameters
+        ----------
+        key : int | slice
+            Index or slice of indices to access from each list.
+
+        Returns
+        -------
+        pandas.Series
+            The list at requested index.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         [1, 2, 3],
+        ...         [3],
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.list_(
+        ...         pa.int64()
+        ...     ))
+        ... )
+        >>> s.list[0]
+        0    1
+        1    3
+        dtype: int64[pyarrow]
+        """
+        from pandas import Series
+
+        if isinstance(key, int):
+            # TODO: Support negative key but pyarrow does not allow
+            # element index to be an array.
+            # if key < 0:
+            #     key = pc.add(key, pc.list_value_length(self._pa_array))
+            element = pc.list_element(self._pa_array, key)
+            return Series(element, dtype=ArrowDtype(element.type))
+        elif isinstance(key, slice):
+            if pa_version_under11p0:
+                raise NotImplementedError(
+                    f"List slice not supported by pyarrow {pa.__version__}."
+                )
+
+            # TODO: Support negative start/stop/step, ideally this would be added
+            # upstream in pyarrow.
+            start, stop, step = key.start, key.stop, key.step
+            if start is None:
+                # TODO: When adding negative step support
+                #  this should be setto last element of array
+                # when step is negative.
+                start = 0
+            if step is None:
+                step = 1
+            sliced = pc.list_slice(self._pa_array, start, stop, step)
+            return Series(sliced, dtype=ArrowDtype(sliced.type))
+        else:
+            raise ValueError(f"key must be an int or slice, got {type(key).__name__}")
+
+    def __iter__(self) -> Iterator:
+        raise TypeError(f"'{type(self).__name__}' object is not iterable")
+
+    def flatten(self) -> Series:
+        """
+        Flatten list values.
+
+        Returns
+        -------
+        pandas.Series
+            The data from all lists in the series flattened.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         [1, 2, 3],
+        ...         [3],
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.list_(
+        ...         pa.int64()
+        ...     ))
+        ... )
+        >>> s.list.flatten()
+        0    1
+        1    2
+        2    3
+        3    3
+        dtype: int64[pyarrow]
+        """
+        from pandas import Series
+
+        flattened = pc.list_flatten(self._pa_array)
+        return Series(flattened, dtype=ArrowDtype(flattened.type))
+
+
+class StructAccessor(ArrowAccessor):
+    """
+    Accessor object for structured data properties of the Series values.
+
+    Parameters
+    ----------
+    data : Series
+        Series containing Arrow struct data.
+    """
+
+    def __init__(self, data=None) -> None:
+        super().__init__(
+            data,
+            validation_msg=(
+                "Can only use the '.struct' accessor with 'struct[pyarrow]' "
+                "dtype, not {dtype}."
+            ),
+        )
+
+    def _is_valid_pyarrow_dtype(self, pyarrow_dtype) -> bool:
+        return pa.types.is_struct(pyarrow_dtype)
+
+    @property
+    def dtypes(self) -> Series:
+        """
+        Return the dtype object of each child field of the struct.
+
+        Returns
+        -------
+        pandas.Series
+            The data type of each child field.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         {"version": 1, "project": "pandas"},
+        ...         {"version": 2, "project": "pandas"},
+        ...         {"version": 1, "project": "numpy"},
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.struct(
+        ...         [("version", pa.int64()), ("project", pa.string())]
+        ...     ))
+        ... )
+        >>> s.struct.dtypes
+        version     int64[pyarrow]
+        project    string[pyarrow]
+        dtype: object
+        """
+        from pandas import (
+            Index,
+            Series,
+        )
+
+        pa_type = self._data.dtype.pyarrow_dtype
+        types = [ArrowDtype(struct.type) for struct in pa_type]
+        names = [struct.name for struct in pa_type]
+        return Series(types, index=Index(names))
+
+    def field(
+        self,
+        name_or_index: list[str]
+        | list[bytes]
+        | list[int]
+        | pc.Expression
+        | bytes
+        | str
+        | int,
+    ) -> Series:
+        """
+        Extract a child field of a struct as a Series.
+
+        Parameters
+        ----------
+        name_or_index : str | bytes | int | expression | list
+            Name or index of the child field to extract.
+
+            For list-like inputs, this will index into a nested
+            struct.
+
+        Returns
+        -------
+        pandas.Series
+            The data corresponding to the selected child field.
+
+        See Also
+        --------
+        Series.struct.explode : Return all child fields as a DataFrame.
+
+        Notes
+        -----
+        The name of the resulting Series will be set using the following
+        rules:
+
+        - For string, bytes, or integer `name_or_index` (or a list of these, for
+          a nested selection), the Series name is set to the selected
+          field's name.
+        - For a :class:`pyarrow.compute.Expression`, this is set to
+          the string form of the expression.
+        - For list-like `name_or_index`, the name will be set to the
+          name of the final field selected.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         {"version": 1, "project": "pandas"},
+        ...         {"version": 2, "project": "pandas"},
+        ...         {"version": 1, "project": "numpy"},
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.struct(
+        ...         [("version", pa.int64()), ("project", pa.string())]
+        ...     ))
+        ... )
+
+        Extract by field name.
+
+        >>> s.struct.field("project")
+        0    pandas
+        1    pandas
+        2     numpy
+        Name: project, dtype: string[pyarrow]
+
+        Extract by field index.
+
+        >>> s.struct.field(0)
+        0    1
+        1    2
+        2    1
+        Name: version, dtype: int64[pyarrow]
+
+        Or an expression
+
+        >>> import pyarrow.compute as pc
+        >>> s.struct.field(pc.field("project"))
+        0    pandas
+        1    pandas
+        2     numpy
+        Name: project, dtype: string[pyarrow]
+
+        For nested struct types, you can pass a list of values to index
+        multiple levels:
+
+        >>> version_type = pa.struct([
+        ...     ("major", pa.int64()),
+        ...     ("minor", pa.int64()),
+        ... ])
+        >>> s = pd.Series(
+        ...     [
+        ...         {"version": {"major": 1, "minor": 5}, "project": "pandas"},
+        ...         {"version": {"major": 2, "minor": 1}, "project": "pandas"},
+        ...         {"version": {"major": 1, "minor": 26}, "project": "numpy"},
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.struct(
+        ...         [("version", version_type), ("project", pa.string())]
+        ...     ))
+        ... )
+        >>> s.struct.field(["version", "minor"])
+        0     5
+        1     1
+        2    26
+        Name: minor, dtype: int64[pyarrow]
+        >>> s.struct.field([0, 0])
+        0    1
+        1    2
+        2    1
+        Name: major, dtype: int64[pyarrow]
+        """
+        from pandas import Series
+
+        def get_name(
+            level_name_or_index: list[str]
+            | list[bytes]
+            | list[int]
+            | pc.Expression
+            | bytes
+            | str
+            | int,
+            data: pa.ChunkedArray,
+        ):
+            if isinstance(level_name_or_index, int):
+                name = data.type.field(level_name_or_index).name
+            elif isinstance(level_name_or_index, (str, bytes)):
+                name = level_name_or_index
+            elif isinstance(level_name_or_index, pc.Expression):
+                name = str(level_name_or_index)
+            elif is_list_like(level_name_or_index):
+                # For nested input like [2, 1, 2]
+                # iteratively get the struct and field name. The last
+                # one is used for the name of the index.
+                level_name_or_index = list(reversed(level_name_or_index))
+                selected = data
+                while level_name_or_index:
+                    # we need the cast, otherwise mypy complains about
+                    # getting ints, bytes, or str here, which isn't possible.
+                    level_name_or_index = cast(list, level_name_or_index)
+                    name_or_index = level_name_or_index.pop()
+                    name = get_name(name_or_index, selected)
+                    selected = selected.type.field(selected.type.get_field_index(name))
+                    name = selected.name
+            else:
+                raise ValueError(
+                    "name_or_index must be an int, str, bytes, "
+                    "pyarrow.compute.Expression, or list of those"
+                )
+            return name
+
+        pa_arr = self._data.array._pa_array
+        name = get_name(name_or_index, pa_arr)
+        field_arr = pc.struct_field(pa_arr, name_or_index)
+
+        return Series(
+            field_arr,
+            dtype=ArrowDtype(field_arr.type),
+            index=self._data.index,
+            name=name,
+        )
+
+    def explode(self) -> DataFrame:
+        """
+        Extract all child fields of a struct as a DataFrame.
+
+        Returns
+        -------
+        pandas.DataFrame
+            The data corresponding to all child fields.
+
+        See Also
+        --------
+        Series.struct.field : Return a single child field as a Series.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> s = pd.Series(
+        ...     [
+        ...         {"version": 1, "project": "pandas"},
+        ...         {"version": 2, "project": "pandas"},
+        ...         {"version": 1, "project": "numpy"},
+        ...     ],
+        ...     dtype=pd.ArrowDtype(pa.struct(
+        ...         [("version", pa.int64()), ("project", pa.string())]
+        ...     ))
+        ... )
+
+        >>> s.struct.explode()
+           version project
+        0        1  pandas
+        1        2  pandas
+        2        1   numpy
+        """
+        from pandas import concat
+
+        pa_type = self._pa_array.type
+        return concat(
+            [self.field(i) for i in range(pa_type.num_fields)], axis="columns"
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/array.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/array.py
new file mode 100644
index 0000000000000000000000000000000000000000..e16a126ac10ee3ee3a00d8d967ad2a038e37ff5c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/array.py
@@ -0,0 +1,2969 @@
+from __future__ import annotations
+
+import functools
+import operator
+from pathlib import Path
+import re
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+)
+import unicodedata
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs import (
+    NaT,
+    Timedelta,
+    Timestamp,
+    timezones,
+)
+from pandas.compat import (
+    pa_version_under10p1,
+    pa_version_under11p0,
+    pa_version_under13p0,
+)
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_fillna_kwargs
+
+from pandas.core.dtypes.cast import (
+    can_hold_element,
+    infer_dtype_from_scalar,
+)
+from pandas.core.dtypes.common import (
+    is_array_like,
+    is_bool_dtype,
+    is_float_dtype,
+    is_integer,
+    is_list_like,
+    is_numeric_dtype,
+    is_scalar,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import (
+    algorithms as algos,
+    missing,
+    ops,
+    roperator,
+)
+from pandas.core.algorithms import map_array
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays._arrow_string_mixins import ArrowStringArrayMixin
+from pandas.core.arrays._utils import to_numpy_dtype_inference
+from pandas.core.arrays.base import (
+    ExtensionArray,
+    ExtensionArraySupportsAnyAll,
+)
+from pandas.core.arrays.masked import BaseMaskedArray
+from pandas.core.arrays.string_ import StringDtype
+import pandas.core.common as com
+from pandas.core.indexers import (
+    check_array_indexer,
+    unpack_tuple_and_ellipses,
+    validate_indices,
+)
+from pandas.core.nanops import check_below_min_count
+from pandas.core.strings.base import BaseStringArrayMethods
+
+from pandas.io._util import _arrow_dtype_mapping
+from pandas.tseries.frequencies import to_offset
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+    import pyarrow.compute as pc
+
+    from pandas.core.dtypes.dtypes import ArrowDtype
+
+    ARROW_CMP_FUNCS = {
+        "eq": pc.equal,
+        "ne": pc.not_equal,
+        "lt": pc.less,
+        "gt": pc.greater,
+        "le": pc.less_equal,
+        "ge": pc.greater_equal,
+    }
+
+    ARROW_LOGICAL_FUNCS = {
+        "and_": pc.and_kleene,
+        "rand_": lambda x, y: pc.and_kleene(y, x),
+        "or_": pc.or_kleene,
+        "ror_": lambda x, y: pc.or_kleene(y, x),
+        "xor": pc.xor,
+        "rxor": lambda x, y: pc.xor(y, x),
+    }
+
+    ARROW_BIT_WISE_FUNCS = {
+        "and_": pc.bit_wise_and,
+        "rand_": lambda x, y: pc.bit_wise_and(y, x),
+        "or_": pc.bit_wise_or,
+        "ror_": lambda x, y: pc.bit_wise_or(y, x),
+        "xor": pc.bit_wise_xor,
+        "rxor": lambda x, y: pc.bit_wise_xor(y, x),
+    }
+
+    def cast_for_truediv(
+        arrow_array: pa.ChunkedArray, pa_object: pa.Array | pa.Scalar
+    ) -> tuple[pa.ChunkedArray, pa.Array | pa.Scalar]:
+        # Ensure int / int -> float mirroring Python/Numpy behavior
+        # as pc.divide_checked(int, int) -> int
+        if pa.types.is_integer(arrow_array.type) and pa.types.is_integer(
+            pa_object.type
+        ):
+            # GH: 56645.
+            # https://github.com/apache/arrow/issues/35563
+            return pc.cast(arrow_array, pa.float64(), safe=False), pc.cast(
+                pa_object, pa.float64(), safe=False
+            )
+
+        return arrow_array, pa_object
+
+    def floordiv_compat(
+        left: pa.ChunkedArray | pa.Array | pa.Scalar,
+        right: pa.ChunkedArray | pa.Array | pa.Scalar,
+    ) -> pa.ChunkedArray:
+        # TODO: Replace with pyarrow floordiv kernel.
+        # https://github.com/apache/arrow/issues/39386
+        if pa.types.is_integer(left.type) and pa.types.is_integer(right.type):
+            divided = pc.divide_checked(left, right)
+            if pa.types.is_signed_integer(divided.type):
+                # GH 56676
+                has_remainder = pc.not_equal(pc.multiply(divided, right), left)
+                has_one_negative_operand = pc.less(
+                    pc.bit_wise_xor(left, right),
+                    pa.scalar(0, type=divided.type),
+                )
+                result = pc.if_else(
+                    pc.and_(
+                        has_remainder,
+                        has_one_negative_operand,
+                    ),
+                    # GH: 55561
+                    pc.subtract(divided, pa.scalar(1, type=divided.type)),
+                    divided,
+                )
+            else:
+                result = divided
+            result = result.cast(left.type)
+        else:
+            divided = pc.divide(left, right)
+            result = pc.floor(divided)
+        return result
+
+    ARROW_ARITHMETIC_FUNCS = {
+        "add": pc.add_checked,
+        "radd": lambda x, y: pc.add_checked(y, x),
+        "sub": pc.subtract_checked,
+        "rsub": lambda x, y: pc.subtract_checked(y, x),
+        "mul": pc.multiply_checked,
+        "rmul": lambda x, y: pc.multiply_checked(y, x),
+        "truediv": lambda x, y: pc.divide(*cast_for_truediv(x, y)),
+        "rtruediv": lambda x, y: pc.divide(*cast_for_truediv(y, x)),
+        "floordiv": lambda x, y: floordiv_compat(x, y),
+        "rfloordiv": lambda x, y: floordiv_compat(y, x),
+        "mod": NotImplemented,
+        "rmod": NotImplemented,
+        "divmod": NotImplemented,
+        "rdivmod": NotImplemented,
+        "pow": pc.power_checked,
+        "rpow": lambda x, y: pc.power_checked(y, x),
+    }
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        Dtype,
+        FillnaOptions,
+        InterpolateOptions,
+        Iterator,
+        NpDtype,
+        NumpySorter,
+        NumpyValueArrayLike,
+        PositionalIndexer,
+        Scalar,
+        Self,
+        SortKind,
+        TakeIndexer,
+        TimeAmbiguous,
+        TimeNonexistent,
+        npt,
+    )
+
+    from pandas import Series
+    from pandas.core.arrays.datetimes import DatetimeArray
+    from pandas.core.arrays.timedeltas import TimedeltaArray
+
+
+def get_unit_from_pa_dtype(pa_dtype):
+    # https://github.com/pandas-dev/pandas/pull/50998#discussion_r1100344804
+    if pa_version_under11p0:
+        unit = str(pa_dtype).split("[", 1)[-1][:-1]
+        if unit not in ["s", "ms", "us", "ns"]:
+            raise ValueError(pa_dtype)
+        return unit
+    return pa_dtype.unit
+
+
+def to_pyarrow_type(
+    dtype: ArrowDtype | pa.DataType | Dtype | None,
+) -> pa.DataType | None:
+    """
+    Convert dtype to a pyarrow type instance.
+    """
+    if isinstance(dtype, ArrowDtype):
+        return dtype.pyarrow_dtype
+    elif isinstance(dtype, pa.DataType):
+        return dtype
+    elif isinstance(dtype, DatetimeTZDtype):
+        return pa.timestamp(dtype.unit, dtype.tz)
+    elif dtype:
+        try:
+            # Accepts python types too
+            # Doesn't handle all numpy types
+            return pa.from_numpy_dtype(dtype)
+        except pa.ArrowNotImplementedError:
+            pass
+    return None
+
+
+class ArrowExtensionArray(  # type: ignore[misc]
+    OpsMixin,
+    ExtensionArraySupportsAnyAll,
+    ArrowStringArrayMixin,
+    BaseStringArrayMethods,
+):
+    """
+    Pandas ExtensionArray backed by a PyArrow ChunkedArray.
+
+    .. warning::
+
+       ArrowExtensionArray is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Parameters
+    ----------
+    values : pyarrow.Array or pyarrow.ChunkedArray
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Returns
+    -------
+    ArrowExtensionArray
+
+    Notes
+    -----
+    Most methods are implemented using `pyarrow compute functions. `__
+    Some methods may either raise an exception or raise a ``PerformanceWarning`` if an
+    associated compute function is not available based on the installed version of PyArrow.
+
+    Please install the latest version of PyArrow to enable the best functionality and avoid
+    potential bugs in prior versions of PyArrow.
+
+    Examples
+    --------
+    Create an ArrowExtensionArray with :func:`pandas.array`:
+
+    >>> pd.array([1, 1, None], dtype="int64[pyarrow]")
+    
+    [1, 1, ]
+    Length: 3, dtype: int64[pyarrow]
+    """  # noqa: E501 (http link too long)
+
+    _pa_array: pa.ChunkedArray
+    _dtype: ArrowDtype
+
+    def __init__(self, values: pa.Array | pa.ChunkedArray) -> None:
+        if pa_version_under10p1:
+            msg = "pyarrow>=10.0.1 is required for PyArrow backed ArrowExtensionArray."
+            raise ImportError(msg)
+        if isinstance(values, pa.Array):
+            self._pa_array = pa.chunked_array([values])
+        elif isinstance(values, pa.ChunkedArray):
+            self._pa_array = values
+        else:
+            raise ValueError(
+                f"Unsupported type '{type(values)}' for ArrowExtensionArray"
+            )
+        self._dtype = ArrowDtype(self._pa_array.type)
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy: bool = False):
+        """
+        Construct a new ExtensionArray from a sequence of scalars.
+        """
+        pa_type = to_pyarrow_type(dtype)
+        pa_array = cls._box_pa_array(scalars, pa_type=pa_type, copy=copy)
+        arr = cls(pa_array)
+        return arr
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, *, dtype: Dtype | None = None, copy: bool = False
+    ):
+        """
+        Construct a new ExtensionArray from a sequence of strings.
+        """
+        pa_type = to_pyarrow_type(dtype)
+        if (
+            pa_type is None
+            or pa.types.is_binary(pa_type)
+            or pa.types.is_string(pa_type)
+            or pa.types.is_large_string(pa_type)
+        ):
+            # pa_type is None: Let pa.array infer
+            # pa_type is string/binary: scalars already correct type
+            scalars = strings
+        elif pa.types.is_timestamp(pa_type):
+            from pandas.core.tools.datetimes import to_datetime
+
+            scalars = to_datetime(strings, errors="raise")
+        elif pa.types.is_date(pa_type):
+            from pandas.core.tools.datetimes import to_datetime
+
+            scalars = to_datetime(strings, errors="raise").date
+        elif pa.types.is_duration(pa_type):
+            from pandas.core.tools.timedeltas import to_timedelta
+
+            scalars = to_timedelta(strings, errors="raise")
+            if pa_type.unit != "ns":
+                # GH51175: test_from_sequence_of_strings_pa_array
+                # attempt to parse as int64 reflecting pyarrow's
+                # duration to string casting behavior
+                mask = isna(scalars)
+                if not isinstance(strings, (pa.Array, pa.ChunkedArray)):
+                    strings = pa.array(strings, type=pa.string(), from_pandas=True)
+                strings = pc.if_else(mask, None, strings)
+                try:
+                    scalars = strings.cast(pa.int64())
+                except pa.ArrowInvalid:
+                    pass
+        elif pa.types.is_time(pa_type):
+            from pandas.core.tools.times import to_time
+
+            # "coerce" to allow "null times" (None) to not raise
+            scalars = to_time(strings, errors="coerce")
+        elif pa.types.is_boolean(pa_type):
+            # pyarrow string->bool casting is case-insensitive:
+            #   "true" or "1" -> True
+            #   "false" or "0" -> False
+            # Note: BooleanArray was previously used to parse these strings
+            #   and allows "1.0" and "0.0". Pyarrow casting does not support
+            #   this, but we allow it here.
+            if isinstance(strings, (pa.Array, pa.ChunkedArray)):
+                scalars = strings
+            else:
+                scalars = pa.array(strings, type=pa.string(), from_pandas=True)
+            scalars = pc.if_else(pc.equal(scalars, "1.0"), "1", scalars)
+            scalars = pc.if_else(pc.equal(scalars, "0.0"), "0", scalars)
+            scalars = scalars.cast(pa.bool_())
+        elif (
+            pa.types.is_integer(pa_type)
+            or pa.types.is_floating(pa_type)
+            or pa.types.is_decimal(pa_type)
+        ):
+            from pandas.core.tools.numeric import to_numeric
+
+            scalars = to_numeric(strings, errors="raise")
+        else:
+            raise NotImplementedError(
+                f"Converting strings to {pa_type} is not implemented."
+            )
+        return cls._from_sequence(scalars, dtype=pa_type, copy=copy)
+
+    @classmethod
+    def _box_pa(
+        cls, value, pa_type: pa.DataType | None = None
+    ) -> pa.Array | pa.ChunkedArray | pa.Scalar:
+        """
+        Box value into a pyarrow Array, ChunkedArray or Scalar.
+
+        Parameters
+        ----------
+        value : any
+        pa_type : pa.DataType | None
+
+        Returns
+        -------
+        pa.Array or pa.ChunkedArray or pa.Scalar
+        """
+        if isinstance(value, pa.Scalar) or not is_list_like(value):
+            return cls._box_pa_scalar(value, pa_type)
+        return cls._box_pa_array(value, pa_type)
+
+    @classmethod
+    def _box_pa_scalar(cls, value, pa_type: pa.DataType | None = None) -> pa.Scalar:
+        """
+        Box value into a pyarrow Scalar.
+
+        Parameters
+        ----------
+        value : any
+        pa_type : pa.DataType | None
+
+        Returns
+        -------
+        pa.Scalar
+        """
+        if isinstance(value, pa.Scalar):
+            pa_scalar = value
+        elif isna(value):
+            pa_scalar = pa.scalar(None, type=pa_type)
+        else:
+            # Workaround https://github.com/apache/arrow/issues/37291
+            if isinstance(value, Timedelta):
+                if pa_type is None:
+                    pa_type = pa.duration(value.unit)
+                elif value.unit != pa_type.unit:
+                    value = value.as_unit(pa_type.unit)
+                value = value._value
+            elif isinstance(value, Timestamp):
+                if pa_type is None:
+                    pa_type = pa.timestamp(value.unit, tz=value.tz)
+                elif value.unit != pa_type.unit:
+                    value = value.as_unit(pa_type.unit)
+                value = value._value
+
+            pa_scalar = pa.scalar(value, type=pa_type, from_pandas=True)
+
+        if pa_type is not None and pa_scalar.type != pa_type:
+            pa_scalar = pa_scalar.cast(pa_type)
+
+        return pa_scalar
+
+    @classmethod
+    def _box_pa_array(
+        cls, value, pa_type: pa.DataType | None = None, copy: bool = False
+    ) -> pa.Array | pa.ChunkedArray:
+        """
+        Box value into a pyarrow Array or ChunkedArray.
+
+        Parameters
+        ----------
+        value : Sequence
+        pa_type : pa.DataType | None
+
+        Returns
+        -------
+        pa.Array or pa.ChunkedArray
+        """
+        if isinstance(value, cls):
+            pa_array = value._pa_array
+        elif isinstance(value, (pa.Array, pa.ChunkedArray)):
+            pa_array = value
+        elif isinstance(value, BaseMaskedArray):
+            # GH 52625
+            if copy:
+                value = value.copy()
+            pa_array = value.__arrow_array__()
+        else:
+            if (
+                isinstance(value, np.ndarray)
+                and pa_type is not None
+                and (
+                    pa.types.is_large_binary(pa_type)
+                    or pa.types.is_large_string(pa_type)
+                )
+            ):
+                # See https://github.com/apache/arrow/issues/35289
+                value = value.tolist()
+            elif copy and is_array_like(value):
+                # pa array should not get updated when numpy array is updated
+                value = value.copy()
+
+            if (
+                pa_type is not None
+                and pa.types.is_duration(pa_type)
+                and (not isinstance(value, np.ndarray) or value.dtype.kind not in "mi")
+            ):
+                # Workaround https://github.com/apache/arrow/issues/37291
+                from pandas.core.tools.timedeltas import to_timedelta
+
+                value = to_timedelta(value, unit=pa_type.unit).as_unit(pa_type.unit)
+                value = value.to_numpy()
+
+            try:
+                pa_array = pa.array(value, type=pa_type, from_pandas=True)
+            except (pa.ArrowInvalid, pa.ArrowTypeError):
+                # GH50430: let pyarrow infer type, then cast
+                pa_array = pa.array(value, from_pandas=True)
+
+            if pa_type is None and pa.types.is_duration(pa_array.type):
+                # Workaround https://github.com/apache/arrow/issues/37291
+                from pandas.core.tools.timedeltas import to_timedelta
+
+                value = to_timedelta(value)
+                value = value.to_numpy()
+                pa_array = pa.array(value, type=pa_type, from_pandas=True)
+
+            if pa.types.is_duration(pa_array.type) and pa_array.null_count > 0:
+                # GH52843: upstream bug for duration types when originally
+                # constructed with data containing numpy NaT.
+                # https://github.com/apache/arrow/issues/35088
+                arr = cls(pa_array)
+                arr = arr.fillna(arr.dtype.na_value)
+                pa_array = arr._pa_array
+
+        if pa_type is not None and pa_array.type != pa_type:
+            if pa.types.is_dictionary(pa_type):
+                pa_array = pa_array.dictionary_encode()
+            else:
+                try:
+                    pa_array = pa_array.cast(pa_type)
+                except (
+                    pa.ArrowInvalid,
+                    pa.ArrowTypeError,
+                    pa.ArrowNotImplementedError,
+                ):
+                    if pa.types.is_string(pa_array.type) or pa.types.is_large_string(
+                        pa_array.type
+                    ):
+                        # TODO: Move logic in _from_sequence_of_strings into
+                        # _box_pa_array
+                        return cls._from_sequence_of_strings(
+                            value, dtype=pa_type
+                        )._pa_array
+                    else:
+                        raise
+
+        return pa_array
+
+    def __getitem__(self, item: PositionalIndexer):
+        """Select a subset of self.
+
+        Parameters
+        ----------
+        item : int, slice, or ndarray
+            * int: The position in 'self' to get.
+            * slice: A slice object, where 'start', 'stop', and 'step' are
+              integers or None
+            * ndarray: A 1-d boolean NumPy ndarray the same length as 'self'
+
+        Returns
+        -------
+        item : scalar or ExtensionArray
+
+        Notes
+        -----
+        For scalar ``item``, return a scalar value suitable for the array's
+        type. This should be an instance of ``self.dtype.type``.
+        For slice ``key``, return an instance of ``ExtensionArray``, even
+        if the slice is length 0 or 1.
+        For a boolean mask, return an instance of ``ExtensionArray``, filtered
+        to the values where ``item`` is True.
+        """
+        item = check_array_indexer(self, item)
+
+        if isinstance(item, np.ndarray):
+            if not len(item):
+                # Removable once we migrate StringDtype[pyarrow] to ArrowDtype[string]
+                if (
+                    isinstance(self._dtype, StringDtype)
+                    and self._dtype.storage == "pyarrow"
+                ):
+                    # TODO(infer_string) should this be large_string?
+                    pa_dtype = pa.string()
+                else:
+                    pa_dtype = self._dtype.pyarrow_dtype
+                return type(self)(pa.chunked_array([], type=pa_dtype))
+            elif item.dtype.kind in "iu":
+                return self.take(item)
+            elif item.dtype.kind == "b":
+                return type(self)(self._pa_array.filter(item))
+            else:
+                raise IndexError(
+                    "Only integers, slices and integer or "
+                    "boolean arrays are valid indices."
+                )
+        elif isinstance(item, tuple):
+            item = unpack_tuple_and_ellipses(item)
+
+        if item is Ellipsis:
+            # TODO: should be handled by pyarrow?
+            item = slice(None)
+
+        if is_scalar(item) and not is_integer(item):
+            # e.g. "foo" or 2.5
+            # exception message copied from numpy
+            raise IndexError(
+                r"only integers, slices (`:`), ellipsis (`...`), numpy.newaxis "
+                r"(`None`) and integer or boolean arrays are valid indices"
+            )
+        # We are not an array indexer, so maybe e.g. a slice or integer
+        # indexer. We dispatch to pyarrow.
+        if isinstance(item, slice):
+            # Arrow bug https://github.com/apache/arrow/issues/38768
+            if item.start == item.stop:
+                pass
+            elif (
+                item.stop is not None
+                and item.stop < -len(self)
+                and item.step is not None
+                and item.step < 0
+            ):
+                item = slice(item.start, None, item.step)
+
+        value = self._pa_array[item]
+        if isinstance(value, pa.ChunkedArray):
+            return type(self)(value)
+        else:
+            pa_type = self._pa_array.type
+            scalar = value.as_py()
+            if scalar is None:
+                return self._dtype.na_value
+            elif pa.types.is_timestamp(pa_type) and pa_type.unit != "ns":
+                # GH 53326
+                return Timestamp(scalar).as_unit(pa_type.unit)
+            elif pa.types.is_duration(pa_type) and pa_type.unit != "ns":
+                # GH 53326
+                return Timedelta(scalar).as_unit(pa_type.unit)
+            else:
+                return scalar
+
+    def __iter__(self) -> Iterator[Any]:
+        """
+        Iterate over elements of the array.
+        """
+        na_value = self._dtype.na_value
+        # GH 53326
+        pa_type = self._pa_array.type
+        box_timestamp = pa.types.is_timestamp(pa_type) and pa_type.unit != "ns"
+        box_timedelta = pa.types.is_duration(pa_type) and pa_type.unit != "ns"
+        for value in self._pa_array:
+            val = value.as_py()
+            if val is None:
+                yield na_value
+            elif box_timestamp:
+                yield Timestamp(val).as_unit(pa_type.unit)
+            elif box_timedelta:
+                yield Timedelta(val).as_unit(pa_type.unit)
+            else:
+                yield val
+
+    def __arrow_array__(self, type=None):
+        """Convert myself to a pyarrow ChunkedArray."""
+        return self._pa_array
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        """Correctly construct numpy arrays when passed to `np.asarray()`."""
+        if copy is False:
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        elif copy is None:
+            # `to_numpy(copy=False)` has the meaning of NumPy `copy=None`.
+            copy = False
+
+        return self.to_numpy(dtype=dtype, copy=copy)
+
+    def __invert__(self) -> Self:
+        # This is a bit wise op for integer types
+        if pa.types.is_integer(self._pa_array.type):
+            return type(self)(pc.bit_wise_not(self._pa_array))
+        elif pa.types.is_string(self._pa_array.type) or pa.types.is_large_string(
+            self._pa_array.type
+        ):
+            # Raise TypeError instead of pa.ArrowNotImplementedError
+            raise TypeError("__invert__ is not supported for string dtypes")
+        else:
+            return type(self)(pc.invert(self._pa_array))
+
+    def __neg__(self) -> Self:
+        try:
+            return type(self)(pc.negate_checked(self._pa_array))
+        except pa.ArrowNotImplementedError as err:
+            raise TypeError(
+                f"unary '-' not supported for dtype '{self.dtype}'"
+            ) from err
+
+    def __pos__(self) -> Self:
+        return type(self)(self._pa_array)
+
+    def __abs__(self) -> Self:
+        return type(self)(pc.abs_checked(self._pa_array))
+
+    # GH 42600: __getstate__/__setstate__ not necessary once
+    # https://issues.apache.org/jira/browse/ARROW-10739 is addressed
+    def __getstate__(self):
+        state = self.__dict__.copy()
+        state["_pa_array"] = self._pa_array.combine_chunks()
+        return state
+
+    def __setstate__(self, state) -> None:
+        if "_data" in state:
+            data = state.pop("_data")
+        else:
+            data = state["_pa_array"]
+        state["_pa_array"] = pa.chunked_array(data)
+        self.__dict__.update(state)
+
+    def _cmp_method(self, other, op):
+        pc_func = ARROW_CMP_FUNCS[op.__name__]
+        if isinstance(other, (ExtensionArray, np.ndarray, list)):
+            try:
+                boxed = self._box_pa(other)
+            except pa.lib.ArrowInvalid:
+                # e.g. GH#60228 [1, "b"] we have to operate pointwise
+                res_values = [op(x, y) for x, y in zip(self, other)]
+                result = pa.array(res_values, type=pa.bool_(), from_pandas=True)
+            else:
+                try:
+                    result = pc_func(self._pa_array, boxed)
+                except pa.ArrowNotImplementedError:
+                    result = ops.invalid_comparison(self, other, op)
+                    result = pa.array(result, type=pa.bool_())
+
+        elif is_scalar(other):
+            try:
+                result = pc_func(self._pa_array, self._box_pa(other))
+            except (pa.lib.ArrowNotImplementedError, pa.lib.ArrowInvalid):
+                mask = isna(self) | isna(other)
+                valid = ~mask
+                result = np.zeros(len(self), dtype="bool")
+                np_array = np.array(self)
+                try:
+                    result[valid] = op(np_array[valid], other)
+                except TypeError:
+                    result = ops.invalid_comparison(self, other, op)
+                result = pa.array(result, type=pa.bool_())
+                result = pc.if_else(valid, result, None)
+        else:
+            raise NotImplementedError(
+                f"{op.__name__} not implemented for {type(other)}"
+            )
+        return ArrowExtensionArray(result)
+
+    def _op_method_error_message(self, other, op) -> str:
+        if hasattr(other, "dtype"):
+            other_type = f"dtype '{other.dtype}'"
+        else:
+            other_type = f"object of type {type(other)}"
+        return (
+            f"operation '{op.__name__}' not supported for "
+            f"dtype '{self.dtype}' with {other_type}"
+        )
+
+    def _evaluate_op_method(self, other, op, arrow_funcs) -> Self:
+        pa_type = self._pa_array.type
+        other_original = other
+        other = self._box_pa(other)
+
+        if (
+            pa.types.is_string(pa_type)
+            or pa.types.is_large_string(pa_type)
+            or pa.types.is_binary(pa_type)
+        ):
+            if op in [operator.add, roperator.radd]:
+                sep = pa.scalar("", type=pa_type)
+                try:
+                    if op is operator.add:
+                        result = pc.binary_join_element_wise(self._pa_array, other, sep)
+                    elif op is roperator.radd:
+                        result = pc.binary_join_element_wise(other, self._pa_array, sep)
+                except pa.ArrowNotImplementedError as err:
+                    raise TypeError(
+                        self._op_method_error_message(other_original, op)
+                    ) from err
+                return type(self)(result)
+            elif op in [operator.mul, roperator.rmul]:
+                binary = self._pa_array
+                integral = other
+                if not pa.types.is_integer(integral.type):
+                    raise TypeError("Can only string multiply by an integer.")
+                pa_integral = pc.if_else(pc.less(integral, 0), 0, integral)
+                result = pc.binary_repeat(binary, pa_integral)
+                return type(self)(result)
+        elif (
+            pa.types.is_string(other.type)
+            or pa.types.is_binary(other.type)
+            or pa.types.is_large_string(other.type)
+        ) and op in [operator.mul, roperator.rmul]:
+            binary = other
+            integral = self._pa_array
+            if not pa.types.is_integer(integral.type):
+                raise TypeError("Can only string multiply by an integer.")
+            pa_integral = pc.if_else(pc.less(integral, 0), 0, integral)
+            result = pc.binary_repeat(binary, pa_integral)
+            return type(self)(result)
+        if (
+            isinstance(other, pa.Scalar)
+            and pc.is_null(other).as_py()
+            and op.__name__ in ARROW_LOGICAL_FUNCS
+        ):
+            # pyarrow kleene ops require null to be typed
+            other = other.cast(pa_type)
+
+        pc_func = arrow_funcs[op.__name__]
+        if pc_func is NotImplemented:
+            if pa.types.is_string(pa_type) or pa.types.is_large_string(pa_type):
+                raise TypeError(self._op_method_error_message(other_original, op))
+            raise NotImplementedError(f"{op.__name__} not implemented.")
+
+        try:
+            result = pc_func(self._pa_array, other)
+        except pa.ArrowNotImplementedError as err:
+            raise TypeError(self._op_method_error_message(other_original, op)) from err
+        return type(self)(result)
+
+    def _logical_method(self, other, op):
+        # For integer types `^`, `|`, `&` are bitwise operators and return
+        # integer types. Otherwise these are boolean ops.
+        if pa.types.is_integer(self._pa_array.type):
+            return self._evaluate_op_method(other, op, ARROW_BIT_WISE_FUNCS)
+        elif (
+            (
+                pa.types.is_string(self._pa_array.type)
+                or pa.types.is_large_string(self._pa_array.type)
+            )
+            and op in (roperator.ror_, roperator.rand_, roperator.rxor)
+            and isinstance(other, np.ndarray)
+            and other.dtype == bool
+        ):
+            # GH#60234 backward compatibility for the move to StringDtype in 3.0
+            op_name = op.__name__[1:].strip("_")
+            warnings.warn(
+                f"'{op_name}' operations between boolean dtype and {self.dtype} are "
+                "deprecated and will raise in a future version. Explicitly "
+                "cast the strings to a boolean dtype before operating instead.",
+                DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+            return op(other, self.astype(bool))
+        else:
+            return self._evaluate_op_method(other, op, ARROW_LOGICAL_FUNCS)
+
+    def _arith_method(self, other, op) -> Self | npt.NDArray[np.object_]:
+        if (
+            op in [operator.truediv, roperator.rtruediv]
+            and isinstance(other, Path)
+            and (
+                pa.types.is_string(self._pa_array.type)
+                or pa.types.is_large_string(self._pa_array.type)
+            )
+        ):
+            # GH#61940
+            return np.array(
+                [
+                    op(x, other) if isinstance(x, str) else self.dtype.na_value
+                    for x in self
+                ],
+                dtype=object,
+            )
+        return self._evaluate_op_method(other, op, ARROW_ARITHMETIC_FUNCS)
+
+    def equals(self, other) -> bool:
+        if not isinstance(other, ArrowExtensionArray):
+            return False
+        # I'm told that pyarrow makes __eq__ behave like pandas' equals;
+        #  TODO: is this documented somewhere?
+        return self._pa_array == other._pa_array
+
+    @property
+    def dtype(self) -> ArrowDtype:
+        """
+        An instance of 'ExtensionDtype'.
+        """
+        return self._dtype
+
+    @property
+    def nbytes(self) -> int:
+        """
+        The number of bytes needed to store this object in memory.
+        """
+        return self._pa_array.nbytes
+
+    def __len__(self) -> int:
+        """
+        Length of this array.
+
+        Returns
+        -------
+        length : int
+        """
+        return len(self._pa_array)
+
+    def __contains__(self, key) -> bool:
+        # https://github.com/pandas-dev/pandas/pull/51307#issuecomment-1426372604
+        if isna(key) and key is not self.dtype.na_value:
+            if self.dtype.kind == "f" and lib.is_float(key):
+                return pc.any(pc.is_nan(self._pa_array)).as_py()
+
+            # e.g. date or timestamp types we do not allow None here to match pd.NA
+            return False
+            # TODO: maybe complex? object?
+
+        return bool(super().__contains__(key))
+
+    @property
+    def _hasna(self) -> bool:
+        return self._pa_array.null_count > 0
+
+    def isna(self) -> npt.NDArray[np.bool_]:
+        """
+        Boolean NumPy array indicating if each value is missing.
+
+        This should return a 1-D array the same length as 'self'.
+        """
+        # GH51630: fast paths
+        null_count = self._pa_array.null_count
+        if null_count == 0:
+            return np.zeros(len(self), dtype=np.bool_)
+        elif null_count == len(self):
+            return np.ones(len(self), dtype=np.bool_)
+
+        return self._pa_array.is_null().to_numpy()
+
+    def any(self, *, skipna: bool = True, **kwargs):
+        """
+        Return whether any element is truthy.
+
+        Returns False unless there is at least one element that is truthy.
+        By default, NAs are skipped. If ``skipna=False`` is specified and
+        missing values are present, similar :ref:`Kleene logic `
+        is used as for logical operations.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Exclude NA values. If the entire array is NA and `skipna` is
+            True, then the result will be False, as for an empty array.
+            If `skipna` is False, the result will still be True if there is
+            at least one element that is truthy, otherwise NA will be returned
+            if there are NA's present.
+
+        Returns
+        -------
+        bool or :attr:`pandas.NA`
+
+        See Also
+        --------
+        ArrowExtensionArray.all : Return whether all elements are truthy.
+
+        Examples
+        --------
+        The result indicates whether any element is truthy (and by default
+        skips NAs):
+
+        >>> pd.array([True, False, True], dtype="boolean[pyarrow]").any()
+        True
+        >>> pd.array([True, False, pd.NA], dtype="boolean[pyarrow]").any()
+        True
+        >>> pd.array([False, False, pd.NA], dtype="boolean[pyarrow]").any()
+        False
+        >>> pd.array([], dtype="boolean[pyarrow]").any()
+        False
+        >>> pd.array([pd.NA], dtype="boolean[pyarrow]").any()
+        False
+        >>> pd.array([pd.NA], dtype="float64[pyarrow]").any()
+        False
+
+        With ``skipna=False``, the result can be NA if this is logically
+        required (whether ``pd.NA`` is True or False influences the result):
+
+        >>> pd.array([True, False, pd.NA], dtype="boolean[pyarrow]").any(skipna=False)
+        True
+        >>> pd.array([1, 0, pd.NA], dtype="boolean[pyarrow]").any(skipna=False)
+        True
+        >>> pd.array([False, False, pd.NA], dtype="boolean[pyarrow]").any(skipna=False)
+        
+        >>> pd.array([0, 0, pd.NA], dtype="boolean[pyarrow]").any(skipna=False)
+        
+        """
+        return self._reduce("any", skipna=skipna, **kwargs)
+
+    def all(self, *, skipna: bool = True, **kwargs):
+        """
+        Return whether all elements are truthy.
+
+        Returns True unless there is at least one element that is falsey.
+        By default, NAs are skipped. If ``skipna=False`` is specified and
+        missing values are present, similar :ref:`Kleene logic `
+        is used as for logical operations.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Exclude NA values. If the entire array is NA and `skipna` is
+            True, then the result will be True, as for an empty array.
+            If `skipna` is False, the result will still be False if there is
+            at least one element that is falsey, otherwise NA will be returned
+            if there are NA's present.
+
+        Returns
+        -------
+        bool or :attr:`pandas.NA`
+
+        See Also
+        --------
+        ArrowExtensionArray.any : Return whether any element is truthy.
+
+        Examples
+        --------
+        The result indicates whether all elements are truthy (and by default
+        skips NAs):
+
+        >>> pd.array([True, True, pd.NA], dtype="boolean[pyarrow]").all()
+        True
+        >>> pd.array([1, 1, pd.NA], dtype="boolean[pyarrow]").all()
+        True
+        >>> pd.array([True, False, pd.NA], dtype="boolean[pyarrow]").all()
+        False
+        >>> pd.array([], dtype="boolean[pyarrow]").all()
+        True
+        >>> pd.array([pd.NA], dtype="boolean[pyarrow]").all()
+        True
+        >>> pd.array([pd.NA], dtype="float64[pyarrow]").all()
+        True
+
+        With ``skipna=False``, the result can be NA if this is logically
+        required (whether ``pd.NA`` is True or False influences the result):
+
+        >>> pd.array([True, True, pd.NA], dtype="boolean[pyarrow]").all(skipna=False)
+        
+        >>> pd.array([1, 1, pd.NA], dtype="boolean[pyarrow]").all(skipna=False)
+        
+        >>> pd.array([True, False, pd.NA], dtype="boolean[pyarrow]").all(skipna=False)
+        False
+        >>> pd.array([1, 0, pd.NA], dtype="boolean[pyarrow]").all(skipna=False)
+        False
+        """
+        return self._reduce("all", skipna=skipna, **kwargs)
+
+    def argsort(
+        self,
+        *,
+        ascending: bool = True,
+        kind: SortKind = "quicksort",
+        na_position: str = "last",
+        **kwargs,
+    ) -> np.ndarray:
+        order = "ascending" if ascending else "descending"
+        null_placement = {"last": "at_end", "first": "at_start"}.get(na_position, None)
+        if null_placement is None:
+            raise ValueError(f"invalid na_position: {na_position}")
+
+        result = pc.array_sort_indices(
+            self._pa_array, order=order, null_placement=null_placement
+        )
+        np_result = result.to_numpy()
+        return np_result.astype(np.intp, copy=False)
+
+    def _argmin_max(self, skipna: bool, method: str) -> int:
+        if self._pa_array.length() in (0, self._pa_array.null_count) or (
+            self._hasna and not skipna
+        ):
+            # For empty or all null, pyarrow returns -1 but pandas expects TypeError
+            # For skipna=False and data w/ null, pandas expects NotImplementedError
+            # let ExtensionArray.arg{max|min} raise
+            return getattr(super(), f"arg{method}")(skipna=skipna)
+
+        data = self._pa_array
+        if pa.types.is_duration(data.type):
+            data = data.cast(pa.int64())
+
+        value = getattr(pc, method)(data, skip_nulls=skipna)
+        return pc.index(data, value).as_py()
+
+    def argmin(self, skipna: bool = True) -> int:
+        return self._argmin_max(skipna, "min")
+
+    def argmax(self, skipna: bool = True) -> int:
+        return self._argmin_max(skipna, "max")
+
+    def copy(self) -> Self:
+        """
+        Return a shallow copy of the array.
+
+        Underlying ChunkedArray is immutable, so a deep copy is unnecessary.
+
+        Returns
+        -------
+        type(self)
+        """
+        return type(self)(self._pa_array)
+
+    def dropna(self) -> Self:
+        """
+        Return ArrowExtensionArray without NA values.
+
+        Returns
+        -------
+        ArrowExtensionArray
+        """
+        return type(self)(pc.drop_null(self._pa_array))
+
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        if not self._hasna:
+            # TODO(CoW): Not necessary anymore when CoW is the default
+            return self.copy()
+
+        if limit is None and limit_area is None:
+            method = missing.clean_fill_method(method)
+            try:
+                if method == "pad":
+                    return type(self)(pc.fill_null_forward(self._pa_array))
+                elif method == "backfill":
+                    return type(self)(pc.fill_null_backward(self._pa_array))
+            except pa.ArrowNotImplementedError:
+                # ArrowNotImplementedError: Function 'coalesce' has no kernel
+                #   matching input types (duration[ns], duration[ns])
+                # TODO: remove try/except wrapper if/when pyarrow implements
+                #   a kernel for duration types.
+                pass
+
+        # TODO(3.0): after EA.fillna 'method' deprecation is enforced, we can remove
+        #  this method entirely.
+        return super()._pad_or_backfill(
+            method=method, limit=limit, limit_area=limit_area, copy=copy
+        )
+
+    @doc(ExtensionArray.fillna)
+    def fillna(
+        self,
+        value: object | ArrayLike | None = None,
+        method: FillnaOptions | None = None,
+        limit: int | None = None,
+        copy: bool = True,
+    ) -> Self:
+        value, method = validate_fillna_kwargs(value, method)
+
+        if not self._hasna:
+            # TODO(CoW): Not necessary anymore when CoW is the default
+            return self.copy()
+
+        if limit is not None:
+            return super().fillna(value=value, method=method, limit=limit, copy=copy)
+
+        if method is not None:
+            return super().fillna(method=method, limit=limit, copy=copy)
+
+        if isinstance(value, (np.ndarray, ExtensionArray)):
+            # Similar to check_value_size, but we do not mask here since we may
+            #  end up passing it to the super() method.
+            if len(value) != len(self):
+                raise ValueError(
+                    f"Length of 'value' does not match. Got ({len(value)}) "
+                    f" expected {len(self)}"
+                )
+
+        try:
+            fill_value = self._box_pa(value, pa_type=self._pa_array.type)
+        except pa.ArrowTypeError as err:
+            msg = f"Invalid value '{value!s}' for dtype '{self.dtype}'"
+            raise TypeError(msg) from err
+
+        try:
+            return type(self)(pc.fill_null(self._pa_array, fill_value=fill_value))
+        except pa.ArrowNotImplementedError:
+            # ArrowNotImplementedError: Function 'coalesce' has no kernel
+            #   matching input types (duration[ns], duration[ns])
+            # TODO: remove try/except wrapper if/when pyarrow implements
+            #   a kernel for duration types.
+            pass
+
+        return super().fillna(value=value, method=method, limit=limit, copy=copy)
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        # short-circuit to return all False array.
+        if not len(values):
+            return np.zeros(len(self), dtype=bool)
+
+        result = pc.is_in(self._pa_array, value_set=pa.array(values, from_pandas=True))
+        # pyarrow 2.0.0 returned nulls, so we explicitly specify dtype to convert nulls
+        # to False
+        return np.array(result, dtype=np.bool_)
+
+    def _values_for_factorize(self) -> tuple[np.ndarray, Any]:
+        """
+        Return an array and missing value suitable for factorization.
+
+        Returns
+        -------
+        values : ndarray
+        na_value : pd.NA
+
+        Notes
+        -----
+        The values returned by this method are also used in
+        :func:`pandas.util.hash_pandas_object`.
+        """
+        values = self._pa_array.to_numpy()
+        return values, self.dtype.na_value
+
+    @doc(ExtensionArray.factorize)
+    def factorize(
+        self,
+        use_na_sentinel: bool = True,
+    ) -> tuple[np.ndarray, ExtensionArray]:
+        null_encoding = "mask" if use_na_sentinel else "encode"
+
+        data = self._pa_array
+        pa_type = data.type
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            # https://github.com/apache/arrow/issues/15226#issuecomment-1376578323
+            data = data.cast(pa.int64())
+
+        if pa.types.is_dictionary(data.type):
+            encoded = data
+        else:
+            encoded = data.dictionary_encode(null_encoding=null_encoding)
+        if encoded.length() == 0:
+            indices = np.array([], dtype=np.intp)
+            uniques = type(self)(pa.chunked_array([], type=encoded.type.value_type))
+        else:
+            # GH 54844
+            combined = encoded.combine_chunks()
+            pa_indices = combined.indices
+            if pa_indices.null_count > 0:
+                pa_indices = pc.fill_null(pa_indices, -1)
+            indices = pa_indices.to_numpy(zero_copy_only=False, writable=True).astype(
+                np.intp, copy=False
+            )
+            uniques = type(self)(combined.dictionary)
+
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            uniques = cast(ArrowExtensionArray, uniques.astype(self.dtype))
+        return indices, uniques
+
+    def reshape(self, *args, **kwargs):
+        raise NotImplementedError(
+            f"{type(self)} does not support reshape "
+            f"as backed by a 1D pyarrow.ChunkedArray."
+        )
+
+    def round(self, decimals: int = 0, *args, **kwargs) -> Self:
+        """
+        Round each value in the array a to the given number of decimals.
+
+        Parameters
+        ----------
+        decimals : int, default 0
+            Number of decimal places to round to. If decimals is negative,
+            it specifies the number of positions to the left of the decimal point.
+        *args, **kwargs
+            Additional arguments and keywords have no effect.
+
+        Returns
+        -------
+        ArrowExtensionArray
+            Rounded values of the ArrowExtensionArray.
+
+        See Also
+        --------
+        DataFrame.round : Round values of a DataFrame.
+        Series.round : Round values of a Series.
+        """
+        return type(self)(pc.round(self._pa_array, ndigits=decimals))
+
+    @doc(ExtensionArray.searchsorted)
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        if self._hasna:
+            raise ValueError(
+                "searchsorted requires array to be sorted, which is impossible "
+                "with NAs present."
+            )
+        if isinstance(value, ExtensionArray):
+            value = value.astype(object)
+        # Base class searchsorted would cast to object, which is *much* slower.
+        dtype = None
+        if isinstance(self.dtype, ArrowDtype):
+            pa_dtype = self.dtype.pyarrow_dtype
+            if (
+                pa.types.is_timestamp(pa_dtype) or pa.types.is_duration(pa_dtype)
+            ) and pa_dtype.unit == "ns":
+                # np.array[datetime/timedelta].searchsorted(datetime/timedelta)
+                # erroneously fails when numpy type resolution is nanoseconds
+                dtype = object
+        return self.to_numpy(dtype=dtype).searchsorted(value, side=side, sorter=sorter)
+
+    def take(
+        self,
+        indices: TakeIndexer,
+        allow_fill: bool = False,
+        fill_value: Any = None,
+    ) -> ArrowExtensionArray:
+        """
+        Take elements from an array.
+
+        Parameters
+        ----------
+        indices : sequence of int or one-dimensional np.ndarray of int
+            Indices to be taken.
+        allow_fill : bool, default False
+            How to handle negative values in `indices`.
+
+            * False: negative values in `indices` indicate positional indices
+              from the right (the default). This is similar to
+              :func:`numpy.take`.
+
+            * True: negative values in `indices` indicate
+              missing values. These values are set to `fill_value`. Any other
+              other negative values raise a ``ValueError``.
+
+        fill_value : any, optional
+            Fill value to use for NA-indices when `allow_fill` is True.
+            This may be ``None``, in which case the default NA value for
+            the type, ``self.dtype.na_value``, is used.
+
+            For many ExtensionArrays, there will be two representations of
+            `fill_value`: a user-facing "boxed" scalar, and a low-level
+            physical NA value. `fill_value` should be the user-facing version,
+            and the implementation should handle translating that to the
+            physical version for processing the take if necessary.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Raises
+        ------
+        IndexError
+            When the indices are out of bounds for the array.
+        ValueError
+            When `indices` contains negative values other than ``-1``
+            and `allow_fill` is True.
+
+        See Also
+        --------
+        numpy.take
+        api.extensions.take
+
+        Notes
+        -----
+        ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``,
+        ``iloc``, when `indices` is a sequence of values. Additionally,
+        it's called by :meth:`Series.reindex`, or any other method
+        that causes realignment, with a `fill_value`.
+        """
+        indices_array = np.asanyarray(indices)
+
+        if len(self._pa_array) == 0 and (indices_array >= 0).any():
+            raise IndexError("cannot do a non-empty take")
+        if indices_array.size > 0 and indices_array.max() >= len(self._pa_array):
+            raise IndexError("out of bounds value in 'indices'.")
+
+        if allow_fill:
+            fill_mask = indices_array < 0
+            if fill_mask.any():
+                validate_indices(indices_array, len(self._pa_array))
+                # TODO(ARROW-9433): Treat negative indices as NULL
+                indices_array = pa.array(indices_array, mask=fill_mask)
+                result = self._pa_array.take(indices_array)
+                if isna(fill_value):
+                    return type(self)(result)
+                # TODO: ArrowNotImplementedError: Function fill_null has no
+                # kernel matching input types (array[string], scalar[string])
+                result = type(self)(result)
+                result[fill_mask] = fill_value
+                return result
+                # return type(self)(pc.fill_null(result, pa.scalar(fill_value)))
+            else:
+                # Nothing to fill
+                return type(self)(self._pa_array.take(indices))
+        else:  # allow_fill=False
+            # TODO(ARROW-9432): Treat negative indices as indices from the right.
+            if (indices_array < 0).any():
+                # Don't modify in-place
+                indices_array = np.copy(indices_array)
+                indices_array[indices_array < 0] += len(self._pa_array)
+            return type(self)(self._pa_array.take(indices_array))
+
+    def _maybe_convert_datelike_array(self):
+        """Maybe convert to a datelike array."""
+        pa_type = self._pa_array.type
+        if pa.types.is_timestamp(pa_type):
+            return self._to_datetimearray()
+        elif pa.types.is_duration(pa_type):
+            return self._to_timedeltaarray()
+        return self
+
+    def _to_datetimearray(self) -> DatetimeArray:
+        """Convert a pyarrow timestamp typed array to a DatetimeArray."""
+        from pandas.core.arrays.datetimes import (
+            DatetimeArray,
+            tz_to_dtype,
+        )
+
+        pa_type = self._pa_array.type
+        assert pa.types.is_timestamp(pa_type)
+        np_dtype = np.dtype(f"M8[{pa_type.unit}]")
+        dtype = tz_to_dtype(pa_type.tz, pa_type.unit)
+        np_array = self._pa_array.to_numpy()
+        np_array = np_array.astype(np_dtype)
+        return DatetimeArray._simple_new(np_array, dtype=dtype)
+
+    def _to_timedeltaarray(self) -> TimedeltaArray:
+        """Convert a pyarrow duration typed array to a TimedeltaArray."""
+        from pandas.core.arrays.timedeltas import TimedeltaArray
+
+        pa_type = self._pa_array.type
+        assert pa.types.is_duration(pa_type)
+        np_dtype = np.dtype(f"m8[{pa_type.unit}]")
+        np_array = self._pa_array.to_numpy()
+        np_array = np_array.astype(np_dtype)
+        return TimedeltaArray._simple_new(np_array, dtype=np_dtype)
+
+    def _values_for_json(self) -> np.ndarray:
+        if is_numeric_dtype(self.dtype):
+            return np.asarray(self, dtype=object)
+        return super()._values_for_json()
+
+    @doc(ExtensionArray.to_numpy)
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        original_na_value = na_value
+        dtype, na_value = to_numpy_dtype_inference(self, dtype, na_value, self._hasna)
+        pa_type = self._pa_array.type
+        if not self._hasna or isna(na_value) or pa.types.is_null(pa_type):
+            data = self
+        else:
+            data = self.fillna(na_value)
+            copy = False
+
+        if pa.types.is_timestamp(pa_type) or pa.types.is_duration(pa_type):
+            # GH 55997
+            if dtype != object and na_value is self.dtype.na_value:
+                na_value = lib.no_default
+            result = data._maybe_convert_datelike_array().to_numpy(
+                dtype=dtype, na_value=na_value
+            )
+        elif pa.types.is_time(pa_type) or pa.types.is_date(pa_type):
+            # convert to list of python datetime.time objects before
+            # wrapping in ndarray
+            result = np.array(list(data), dtype=dtype)
+            if data._hasna:
+                result[data.isna()] = na_value
+        elif pa.types.is_null(pa_type):
+            if dtype is not None and isna(na_value):
+                na_value = None
+            result = np.full(len(data), fill_value=na_value, dtype=dtype)
+        elif not data._hasna or (
+            pa.types.is_floating(pa_type)
+            and (
+                na_value is np.nan
+                or original_na_value is lib.no_default
+                and is_float_dtype(dtype)
+            )
+        ):
+            result = data._pa_array.to_numpy()
+            if dtype is not None:
+                result = result.astype(dtype, copy=False)
+            if copy:
+                result = result.copy()
+        else:
+            if dtype is None:
+                empty = pa.array([], type=pa_type).to_numpy(zero_copy_only=False)
+                if can_hold_element(empty, na_value):
+                    dtype = empty.dtype
+                else:
+                    dtype = np.object_
+            result = np.empty(len(data), dtype=dtype)
+            mask = data.isna()
+            result[mask] = na_value
+            result[~mask] = data[~mask]._pa_array.to_numpy()
+        return result
+
+    def map(self, mapper, na_action=None):
+        if is_numeric_dtype(self.dtype):
+            return map_array(self.to_numpy(), mapper, na_action=na_action)
+        else:
+            return super().map(mapper, na_action)
+
+    @doc(ExtensionArray.duplicated)
+    def duplicated(
+        self, keep: Literal["first", "last", False] = "first"
+    ) -> npt.NDArray[np.bool_]:
+        pa_type = self._pa_array.type
+        if pa.types.is_floating(pa_type) or pa.types.is_integer(pa_type):
+            values = self.to_numpy(na_value=0)
+        elif pa.types.is_boolean(pa_type):
+            values = self.to_numpy(na_value=False)
+        elif pa.types.is_temporal(pa_type):
+            if pa_type.bit_width == 32:
+                pa_type = pa.int32()
+            else:
+                pa_type = pa.int64()
+            arr = self.astype(ArrowDtype(pa_type))
+            values = arr.to_numpy(na_value=0)
+        else:
+            # factorize the values to avoid the performance penalty of
+            # converting to object dtype
+            values = self.factorize()[0]
+
+        mask = self.isna() if self._hasna else None
+        return algos.duplicated(values, keep=keep, mask=mask)
+
+    def unique(self) -> Self:
+        """
+        Compute the ArrowExtensionArray of unique values.
+
+        Returns
+        -------
+        ArrowExtensionArray
+        """
+        pa_type = self._pa_array.type
+
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            # https://github.com/apache/arrow/issues/15226#issuecomment-1376578323
+            data = self._pa_array.cast(pa.int64())
+        else:
+            data = self._pa_array
+
+        pa_result = pc.unique(data)
+
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            pa_result = pa_result.cast(pa_type)
+
+        return type(self)(pa_result)
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Return a Series containing counts of each unique value.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of missing values.
+
+        Returns
+        -------
+        counts : Series
+
+        See Also
+        --------
+        Series.value_counts
+        """
+        pa_type = self._pa_array.type
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            # https://github.com/apache/arrow/issues/15226#issuecomment-1376578323
+            data = self._pa_array.cast(pa.int64())
+        else:
+            data = self._pa_array
+
+        from pandas import (
+            Index,
+            Series,
+        )
+
+        vc = data.value_counts()
+
+        values = vc.field(0)
+        counts = vc.field(1)
+        if dropna and data.null_count > 0:
+            mask = values.is_valid()
+            values = values.filter(mask)
+            counts = counts.filter(mask)
+
+        if pa_version_under11p0 and pa.types.is_duration(pa_type):
+            values = values.cast(pa_type)
+
+        counts = ArrowExtensionArray(counts)
+
+        index = Index(type(self)(values))
+
+        return Series(counts, index=index, name="count", copy=False)
+
+    @classmethod
+    def _concat_same_type(cls, to_concat) -> Self:
+        """
+        Concatenate multiple ArrowExtensionArrays.
+
+        Parameters
+        ----------
+        to_concat : sequence of ArrowExtensionArrays
+
+        Returns
+        -------
+        ArrowExtensionArray
+        """
+        chunks = [array for ea in to_concat for array in ea._pa_array.iterchunks()]
+        if to_concat[0].dtype == "string":
+            # StringDtype has no attribute pyarrow_dtype
+            pa_dtype = pa.large_string()
+        else:
+            pa_dtype = to_concat[0].dtype.pyarrow_dtype
+        arr = pa.chunked_array(chunks, type=pa_dtype)
+        return cls(arr)
+
+    def _accumulate(
+        self, name: str, *, skipna: bool = True, **kwargs
+    ) -> ArrowExtensionArray | ExtensionArray:
+        """
+        Return an ExtensionArray performing an accumulation operation.
+
+        The underlying data type might change.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            - cummin
+            - cummax
+            - cumsum
+            - cumprod
+        skipna : bool, default True
+            If True, skip NA values.
+        **kwargs
+            Additional keyword arguments passed to the accumulation function.
+            Currently, there is no supported kwarg.
+
+        Returns
+        -------
+        array
+
+        Raises
+        ------
+        NotImplementedError : subclass does not define accumulations
+        """
+        if is_string_dtype(self):
+            return self._str_accumulate(name=name, skipna=skipna, **kwargs)
+
+        pyarrow_name = {
+            "cummax": "cumulative_max",
+            "cummin": "cumulative_min",
+            "cumprod": "cumulative_prod_checked",
+            "cumsum": "cumulative_sum_checked",
+        }.get(name, name)
+        pyarrow_meth = getattr(pc, pyarrow_name, None)
+        if pyarrow_meth is None:
+            return super()._accumulate(name, skipna=skipna, **kwargs)
+
+        data_to_accum = self._pa_array
+
+        pa_dtype = data_to_accum.type
+
+        convert_to_int = (
+            pa.types.is_temporal(pa_dtype) and name in ["cummax", "cummin"]
+        ) or (pa.types.is_duration(pa_dtype) and name == "cumsum")
+
+        if convert_to_int:
+            if pa_dtype.bit_width == 32:
+                data_to_accum = data_to_accum.cast(pa.int32())
+            else:
+                data_to_accum = data_to_accum.cast(pa.int64())
+
+        try:
+            result = pyarrow_meth(data_to_accum, skip_nulls=skipna, **kwargs)
+        except pa.ArrowNotImplementedError as err:
+            msg = f"operation '{name}' not supported for dtype '{self.dtype}'"
+            raise TypeError(msg) from err
+
+        if convert_to_int:
+            result = result.cast(pa_dtype)
+
+        return type(self)(result)
+
+    def _str_accumulate(
+        self, name: str, *, skipna: bool = True, **kwargs
+    ) -> ArrowExtensionArray | ExtensionArray:
+        """
+        Accumulate implementation for strings, see `_accumulate` docstring for details.
+
+        pyarrow.compute does not implement these methods for strings.
+        """
+        if name == "cumprod":
+            msg = f"operation '{name}' not supported for dtype '{self.dtype}'"
+            raise TypeError(msg)
+
+        # We may need to strip out trailing NA values
+        tail: pa.array | None = None
+        na_mask: pa.array | None = None
+        pa_array = self._pa_array
+        np_func = {
+            "cumsum": np.cumsum,
+            "cummin": np.minimum.accumulate,
+            "cummax": np.maximum.accumulate,
+        }[name]
+
+        if self._hasna:
+            na_mask = pc.is_null(pa_array)
+            if pc.all(na_mask) == pa.scalar(True):
+                return type(self)(pa_array)
+            if skipna:
+                if name == "cumsum":
+                    pa_array = pc.fill_null(pa_array, "")
+                else:
+                    # We can retain the running min/max by forward/backward filling.
+                    pa_array = pc.fill_null_forward(pa_array)
+                    pa_array = pc.fill_null_backward(pa_array)
+            else:
+                # When not skipping NA values, the result should be null from
+                # the first NA value onward.
+                idx = pc.index(na_mask, True).as_py()
+                tail = pa.nulls(len(pa_array) - idx, type=pa_array.type)
+                pa_array = pa_array[:idx]
+
+        # error: Cannot call function of unknown type
+        pa_result = pa.array(np_func(pa_array), type=pa_array.type)  # type: ignore[operator]
+
+        if tail is not None:
+            pa_result = pa.concat_arrays([pa_result, tail])
+        elif na_mask is not None:
+            pa_result = pc.if_else(na_mask, None, pa_result)
+
+        result = type(self)(pa_result)
+        return result
+
+    def _reduce_pyarrow(self, name: str, *, skipna: bool = True, **kwargs) -> pa.Scalar:
+        """
+        Return a pyarrow scalar result of performing the reduction operation.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            { any, all, min, max, sum, mean, median, prod,
+            std, var, sem, kurt, skew }.
+        skipna : bool, default True
+            If True, skip NaN values.
+        **kwargs
+            Additional keyword arguments passed to the reduction function.
+            Currently, `ddof` is the only supported kwarg.
+
+        Returns
+        -------
+        pyarrow scalar
+
+        Raises
+        ------
+        TypeError : subclass does not define reductions
+        """
+        pa_type = self._pa_array.type
+
+        data_to_reduce = self._pa_array
+
+        cast_kwargs = {} if pa_version_under13p0 else {"safe": False}
+
+        if name in ["any", "all"] and (
+            pa.types.is_integer(pa_type)
+            or pa.types.is_floating(pa_type)
+            or pa.types.is_duration(pa_type)
+            or pa.types.is_decimal(pa_type)
+        ):
+            # pyarrow only supports any/all for boolean dtype, we allow
+            #  for other dtypes, matching our non-pyarrow behavior
+
+            if pa.types.is_duration(pa_type):
+                data_to_cmp = self._pa_array.cast(pa.int64())
+            else:
+                data_to_cmp = self._pa_array
+
+            not_eq = pc.not_equal(data_to_cmp, 0)
+            data_to_reduce = not_eq
+
+        elif name in ["min", "max", "sum"] and pa.types.is_duration(pa_type):
+            data_to_reduce = self._pa_array.cast(pa.int64())
+
+        elif name in ["median", "mean", "std", "sem"] and pa.types.is_temporal(pa_type):
+            nbits = pa_type.bit_width
+            if nbits == 32:
+                data_to_reduce = self._pa_array.cast(pa.int32())
+            else:
+                data_to_reduce = self._pa_array.cast(pa.int64())
+
+        if name == "sem":
+
+            def pyarrow_meth(data, skip_nulls, **kwargs):
+                numerator = pc.stddev(data, skip_nulls=skip_nulls, **kwargs)
+                denominator = pc.sqrt_checked(pc.count(self._pa_array))
+                return pc.divide_checked(numerator, denominator)
+
+        elif name == "sum" and (
+            pa.types.is_string(pa_type) or pa.types.is_large_string(pa_type)
+        ):
+
+            def pyarrow_meth(data, skip_nulls, min_count=0):  # type: ignore[misc]
+                mask = pc.is_null(data) if data.null_count > 0 else None
+                if skip_nulls:
+                    if min_count > 0 and check_below_min_count(
+                        (len(data),),
+                        None if mask is None else mask.to_numpy(),
+                        min_count,
+                    ):
+                        return pa.scalar(None, type=data.type)
+                    if data.null_count > 0:
+                        # binary_join returns null if there is any null ->
+                        # have to filter out any nulls
+                        data = data.filter(pc.invert(mask))
+                else:
+                    if mask is not None or check_below_min_count(
+                        (len(data),), None, min_count
+                    ):
+                        return pa.scalar(None, type=data.type)
+
+                if pa.types.is_large_string(data.type):
+                    # binary_join only supports string, not large_string
+                    data = data.cast(pa.string())
+                data_list = pa.ListArray.from_arrays(
+                    [0, len(data)], data.combine_chunks()
+                )[0]
+                return pc.binary_join(data_list, "")
+
+        else:
+            pyarrow_name = {
+                "median": "quantile",
+                "prod": "product",
+                "std": "stddev",
+                "var": "variance",
+            }.get(name, name)
+            # error: Incompatible types in assignment
+            # (expression has type "Optional[Any]", variable has type
+            # "Callable[[Any, Any, KwArg(Any)], Any]")
+            pyarrow_meth = getattr(pc, pyarrow_name, None)  # type: ignore[assignment]
+            if pyarrow_meth is None:
+                # Let ExtensionArray._reduce raise the TypeError
+                return super()._reduce(name, skipna=skipna, **kwargs)
+
+        # GH51624: pyarrow defaults to min_count=1, pandas behavior is min_count=0
+        if name in ["any", "all"] and "min_count" not in kwargs:
+            kwargs["min_count"] = 0
+        elif name == "median":
+            # GH 52679: Use quantile instead of approximate_median
+            kwargs["q"] = 0.5
+
+        try:
+            result = pyarrow_meth(data_to_reduce, skip_nulls=skipna, **kwargs)
+        except (AttributeError, NotImplementedError, TypeError) as err:
+            msg = (
+                f"'{type(self).__name__}' with dtype {self.dtype} "
+                f"does not support reduction '{name}' with pyarrow "
+                f"version {pa.__version__}. '{name}' may be supported by "
+                f"upgrading pyarrow."
+            )
+            raise TypeError(msg) from err
+        if name == "median":
+            # GH 52679: Use quantile instead of approximate_median; returns array
+            result = result[0]
+        if pc.is_null(result).as_py():
+            return result
+
+        if name in ["min", "max", "sum"] and pa.types.is_duration(pa_type):
+            result = result.cast(pa_type)
+        if name in ["median", "mean"] and pa.types.is_temporal(pa_type):
+            if not pa_version_under13p0:
+                nbits = pa_type.bit_width
+                if nbits == 32:
+                    result = result.cast(pa.int32(), **cast_kwargs)
+                else:
+                    result = result.cast(pa.int64(), **cast_kwargs)
+            result = result.cast(pa_type)
+        if name in ["std", "sem"] and pa.types.is_temporal(pa_type):
+            result = result.cast(pa.int64(), **cast_kwargs)
+            if pa.types.is_duration(pa_type):
+                result = result.cast(pa_type)
+            elif pa.types.is_time(pa_type):
+                unit = get_unit_from_pa_dtype(pa_type)
+                result = result.cast(pa.duration(unit))
+            elif pa.types.is_date(pa_type):
+                # go with closest available unit, i.e. "s"
+                result = result.cast(pa.duration("s"))
+            else:
+                # i.e. timestamp
+                result = result.cast(pa.duration(pa_type.unit))
+
+        return result
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        """
+        Return a scalar result of performing the reduction operation.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            { any, all, min, max, sum, mean, median, prod,
+            std, var, sem, kurt, skew }.
+        skipna : bool, default True
+            If True, skip NaN values.
+        **kwargs
+            Additional keyword arguments passed to the reduction function.
+            Currently, `ddof` is the only supported kwarg.
+
+        Returns
+        -------
+        scalar
+
+        Raises
+        ------
+        TypeError : subclass does not define reductions
+        """
+        result = self._reduce_calc(name, skipna=skipna, keepdims=keepdims, **kwargs)
+        if isinstance(result, pa.Array):
+            return type(self)(result)
+        else:
+            return result
+
+    def _reduce_calc(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        pa_result = self._reduce_pyarrow(name, skipna=skipna, **kwargs)
+
+        if keepdims:
+            if isinstance(pa_result, pa.Scalar):
+                result = pa.array([pa_result.as_py()], type=pa_result.type)
+            else:
+                result = pa.array(
+                    [pa_result],
+                    type=to_pyarrow_type(infer_dtype_from_scalar(pa_result)[0]),
+                )
+            return result
+
+        if pc.is_null(pa_result).as_py():
+            return self.dtype.na_value
+        elif isinstance(pa_result, pa.Scalar):
+            return pa_result.as_py()
+        else:
+            return pa_result
+
+    def _explode(self):
+        """
+        See Series.explode.__doc__.
+        """
+        # child class explode method supports only list types; return
+        # default implementation for non list types.
+        if not hasattr(self.dtype, "pyarrow_dtype") or (
+            not pa.types.is_list(self.dtype.pyarrow_dtype)
+        ):
+            return super()._explode()
+        values = self
+        counts = pa.compute.list_value_length(values._pa_array)
+        counts = counts.fill_null(1).to_numpy()
+        fill_value = pa.scalar([None], type=self._pa_array.type)
+        mask = counts == 0
+        if mask.any():
+            values = values.copy()
+            values[mask] = fill_value
+            counts = counts.copy()
+            counts[mask] = 1
+        values = values.fillna(fill_value)
+        values = type(self)(pa.compute.list_flatten(values._pa_array))
+        return values, counts
+
+    def __setitem__(self, key, value) -> None:
+        """Set one or more values inplace.
+
+        Parameters
+        ----------
+        key : int, ndarray, or slice
+            When called from, e.g. ``Series.__setitem__``, ``key`` will be
+            one of
+
+            * scalar int
+            * ndarray of integers.
+            * boolean ndarray
+            * slice object
+
+        value : ExtensionDtype.type, Sequence[ExtensionDtype.type], or object
+            value or values to be set of ``key``.
+
+        Returns
+        -------
+        None
+        """
+        # GH50085: unwrap 1D indexers
+        if isinstance(key, tuple) and len(key) == 1:
+            key = key[0]
+
+        key = check_array_indexer(self, key)
+        value = self._maybe_convert_setitem_value(value)
+
+        if com.is_null_slice(key):
+            # fast path (GH50248)
+            data = self._if_else(True, value, self._pa_array)
+
+        elif is_integer(key):
+            # fast path
+            key = cast(int, key)
+            n = len(self)
+            if key < 0:
+                key += n
+            if not 0 <= key < n:
+                raise IndexError(
+                    f"index {key} is out of bounds for axis 0 with size {n}"
+                )
+            if isinstance(value, pa.Scalar):
+                value = value.as_py()
+            elif is_list_like(value):
+                raise ValueError("Length of indexer and values mismatch")
+            chunks = [
+                *self._pa_array[:key].chunks,
+                pa.array([value], type=self._pa_array.type, from_pandas=True),
+                *self._pa_array[key + 1 :].chunks,
+            ]
+            data = pa.chunked_array(chunks).combine_chunks()
+
+        elif is_bool_dtype(key):
+            key = np.asarray(key, dtype=np.bool_)
+            data = self._replace_with_mask(self._pa_array, key, value)
+
+        elif is_scalar(value) or isinstance(value, pa.Scalar):
+            mask = np.zeros(len(self), dtype=np.bool_)
+            mask[key] = True
+            data = self._if_else(mask, value, self._pa_array)
+
+        else:
+            indices = np.arange(len(self))[key]
+            if len(indices) != len(value):
+                raise ValueError("Length of indexer and values mismatch")
+            if len(indices) == 0:
+                return
+            argsort = np.argsort(indices)
+            indices = indices[argsort]
+            value = value.take(argsort)
+            mask = np.zeros(len(self), dtype=np.bool_)
+            mask[indices] = True
+            data = self._replace_with_mask(self._pa_array, mask, value)
+
+        if isinstance(data, pa.Array):
+            data = pa.chunked_array([data])
+        self._pa_array = data
+
+    def _rank_calc(
+        self,
+        *,
+        axis: AxisInt = 0,
+        method: str = "average",
+        na_option: str = "keep",
+        ascending: bool = True,
+        pct: bool = False,
+    ):
+        if axis != 0:
+            ranked = super()._rank(
+                axis=axis,
+                method=method,
+                na_option=na_option,
+                ascending=ascending,
+                pct=pct,
+            )
+            # keep dtypes consistent with the implementation below
+            if method == "average" or pct:
+                pa_type = pa.float64()
+            else:
+                pa_type = pa.uint64()
+            result = pa.array(ranked, type=pa_type, from_pandas=True)
+            return result
+
+        data = self._pa_array.combine_chunks()
+        sort_keys = "ascending" if ascending else "descending"
+        null_placement = "at_start" if na_option == "top" else "at_end"
+        tiebreaker = "min" if method == "average" else method
+
+        result = pc.rank(
+            data,
+            sort_keys=sort_keys,
+            null_placement=null_placement,
+            tiebreaker=tiebreaker,
+        )
+
+        if na_option == "keep":
+            mask = pc.is_null(self._pa_array)
+            null = pa.scalar(None, type=result.type)
+            result = pc.if_else(mask, null, result)
+
+        if method == "average":
+            result_max = pc.rank(
+                data,
+                sort_keys=sort_keys,
+                null_placement=null_placement,
+                tiebreaker="max",
+            )
+            result_max = result_max.cast(pa.float64())
+            result_min = result.cast(pa.float64())
+            result = pc.divide(pc.add(result_min, result_max), 2)
+
+        if pct:
+            if not pa.types.is_floating(result.type):
+                result = result.cast(pa.float64())
+            if method == "dense":
+                divisor = pc.max(result)
+            else:
+                divisor = pc.count(result)
+            result = pc.divide(result, divisor)
+
+        return result
+
+    def _rank(
+        self,
+        *,
+        axis: AxisInt = 0,
+        method: str = "average",
+        na_option: str = "keep",
+        ascending: bool = True,
+        pct: bool = False,
+    ):
+        """
+        See Series.rank.__doc__.
+        """
+        return self._convert_rank_result(
+            self._rank_calc(
+                axis=axis,
+                method=method,
+                na_option=na_option,
+                ascending=ascending,
+                pct=pct,
+            )
+        )
+
+    def _quantile(self, qs: npt.NDArray[np.float64], interpolation: str) -> Self:
+        """
+        Compute the quantiles of self for each quantile in `qs`.
+
+        Parameters
+        ----------
+        qs : np.ndarray[float64]
+        interpolation: str
+
+        Returns
+        -------
+        same type as self
+        """
+        pa_dtype = self._pa_array.type
+
+        data = self._pa_array
+        if pa.types.is_temporal(pa_dtype):
+            # https://github.com/apache/arrow/issues/33769 in these cases
+            #  we can cast to ints and back
+            nbits = pa_dtype.bit_width
+            if nbits == 32:
+                data = data.cast(pa.int32())
+            else:
+                data = data.cast(pa.int64())
+
+        result = pc.quantile(data, q=qs, interpolation=interpolation)
+
+        if pa.types.is_temporal(pa_dtype):
+            if pa.types.is_floating(result.type):
+                result = pc.floor(result)
+            nbits = pa_dtype.bit_width
+            if nbits == 32:
+                result = result.cast(pa.int32())
+            else:
+                result = result.cast(pa.int64())
+            result = result.cast(pa_dtype)
+
+        return type(self)(result)
+
+    def _mode(self, dropna: bool = True) -> Self:
+        """
+        Returns the mode(s) of the ExtensionArray.
+
+        Always returns `ExtensionArray` even if only one value.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't consider counts of NA values.
+
+        Returns
+        -------
+        same type as self
+            Sorted, if possible.
+        """
+        pa_type = self._pa_array.type
+        if pa.types.is_temporal(pa_type):
+            nbits = pa_type.bit_width
+            if nbits == 32:
+                data = self._pa_array.cast(pa.int32())
+            elif nbits == 64:
+                data = self._pa_array.cast(pa.int64())
+            else:
+                raise NotImplementedError(pa_type)
+        else:
+            data = self._pa_array
+
+        if dropna:
+            data = data.drop_null()
+
+        res = pc.value_counts(data)
+        most_common = res.field("values").filter(
+            pc.equal(res.field("counts"), pc.max(res.field("counts")))
+        )
+
+        if pa.types.is_temporal(pa_type):
+            most_common = most_common.cast(pa_type)
+
+        most_common = most_common.take(pc.array_sort_indices(most_common))
+        return type(self)(most_common)
+
+    def _maybe_convert_setitem_value(self, value):
+        """Maybe convert value to be pyarrow compatible."""
+        try:
+            value = self._box_pa(value, self._pa_array.type)
+        except pa.ArrowTypeError as err:
+            msg = f"Invalid value '{value!s}' for dtype '{self.dtype}'"
+            raise TypeError(msg) from err
+        return value
+
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        axis: int,
+        index,
+        limit,
+        limit_direction,
+        limit_area,
+        copy: bool,
+        **kwargs,
+    ) -> Self:
+        """
+        See NDFrame.interpolate.__doc__.
+        """
+        # NB: we return type(self) even if copy=False
+        if not self.dtype._is_numeric:
+            raise TypeError(f"Cannot interpolate with {self.dtype} dtype")
+
+        mask = self.isna()
+        if self.dtype.kind == "f":
+            data = self._pa_array.to_numpy()
+        elif self.dtype.kind in "iu":
+            data = self.to_numpy(dtype="f8", na_value=0.0)
+        else:
+            raise NotImplementedError(
+                f"interpolate is not implemented for dtype={self.dtype}"
+            )
+
+        missing.interpolate_2d_inplace(
+            data,
+            method=method,
+            axis=0,
+            index=index,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            mask=mask,
+            **kwargs,
+        )
+        return type(self)(self._box_pa_array(pa.array(data, mask=mask)))
+
+    @classmethod
+    def _if_else(
+        cls,
+        cond: npt.NDArray[np.bool_] | bool,
+        left: ArrayLike | Scalar,
+        right: ArrayLike | Scalar,
+    ):
+        """
+        Choose values based on a condition.
+
+        Analogous to pyarrow.compute.if_else, with logic
+        to fallback to numpy for unsupported types.
+
+        Parameters
+        ----------
+        cond : npt.NDArray[np.bool_] or bool
+        left : ArrayLike | Scalar
+        right : ArrayLike | Scalar
+
+        Returns
+        -------
+        pa.Array
+        """
+        try:
+            return pc.if_else(cond, left, right)
+        except pa.ArrowNotImplementedError:
+            pass
+
+        def _to_numpy_and_type(value) -> tuple[np.ndarray, pa.DataType | None]:
+            if isinstance(value, (pa.Array, pa.ChunkedArray)):
+                pa_type = value.type
+            elif isinstance(value, pa.Scalar):
+                pa_type = value.type
+                value = value.as_py()
+            else:
+                pa_type = None
+            return np.array(value, dtype=object), pa_type
+
+        left, left_type = _to_numpy_and_type(left)
+        right, right_type = _to_numpy_and_type(right)
+        pa_type = left_type or right_type
+        result = np.where(cond, left, right)
+        return pa.array(result, type=pa_type, from_pandas=True)
+
+    @classmethod
+    def _replace_with_mask(
+        cls,
+        values: pa.Array | pa.ChunkedArray,
+        mask: npt.NDArray[np.bool_] | bool,
+        replacements: ArrayLike | Scalar,
+    ):
+        """
+        Replace items selected with a mask.
+
+        Analogous to pyarrow.compute.replace_with_mask, with logic
+        to fallback to numpy for unsupported types.
+
+        Parameters
+        ----------
+        values : pa.Array or pa.ChunkedArray
+        mask : npt.NDArray[np.bool_] or bool
+        replacements : ArrayLike or Scalar
+            Replacement value(s)
+
+        Returns
+        -------
+        pa.Array or pa.ChunkedArray
+        """
+        if isinstance(replacements, pa.ChunkedArray):
+            # replacements must be array or scalar, not ChunkedArray
+            replacements = replacements.combine_chunks()
+        if isinstance(values, pa.ChunkedArray) and pa.types.is_boolean(values.type):
+            # GH#52059 replace_with_mask segfaults for chunked array
+            # https://github.com/apache/arrow/issues/34634
+            values = values.combine_chunks()
+        try:
+            return pc.replace_with_mask(values, mask, replacements)
+        except pa.ArrowNotImplementedError:
+            pass
+        if isinstance(replacements, pa.Array):
+            replacements = np.array(replacements, dtype=object)
+        elif isinstance(replacements, pa.Scalar):
+            replacements = replacements.as_py()
+        result = np.array(values, dtype=object)
+        result[mask] = replacements
+        return pa.array(result, type=values.type, from_pandas=True)
+
+    # ------------------------------------------------------------------
+    # GroupBy Methods
+
+    def _to_masked(self):
+        pa_dtype = self._pa_array.type
+
+        if pa.types.is_floating(pa_dtype) or pa.types.is_integer(pa_dtype):
+            na_value = 1
+        elif pa.types.is_boolean(pa_dtype):
+            na_value = True
+        else:
+            raise NotImplementedError
+
+        dtype = _arrow_dtype_mapping()[pa_dtype]
+        mask = self.isna()
+        arr = self.to_numpy(dtype=dtype.numpy_dtype, na_value=na_value)
+        return dtype.construct_array_type()(arr, mask)
+
+    def _groupby_op(
+        self,
+        *,
+        how: str,
+        has_dropped_na: bool,
+        min_count: int,
+        ngroups: int,
+        ids: npt.NDArray[np.intp],
+        **kwargs,
+    ):
+        if isinstance(self.dtype, StringDtype):
+            if how in [
+                "prod",
+                "mean",
+                "median",
+                "cumsum",
+                "cumprod",
+                "std",
+                "sem",
+                "var",
+                "skew",
+            ]:
+                raise TypeError(
+                    f"dtype '{self.dtype}' does not support operation '{how}'"
+                )
+            return super()._groupby_op(
+                how=how,
+                has_dropped_na=has_dropped_na,
+                min_count=min_count,
+                ngroups=ngroups,
+                ids=ids,
+                **kwargs,
+            )
+
+        # maybe convert to a compatible dtype optimized for groupby
+        values: ExtensionArray
+        pa_type = self._pa_array.type
+        if pa.types.is_timestamp(pa_type):
+            values = self._to_datetimearray()
+        elif pa.types.is_duration(pa_type):
+            values = self._to_timedeltaarray()
+        else:
+            values = self._to_masked()
+
+        result = values._groupby_op(
+            how=how,
+            has_dropped_na=has_dropped_na,
+            min_count=min_count,
+            ngroups=ngroups,
+            ids=ids,
+            **kwargs,
+        )
+        if isinstance(result, np.ndarray):
+            return result
+        return type(self)._from_sequence(result, copy=False)
+
+    def _apply_elementwise(self, func: Callable) -> list[list[Any]]:
+        """Apply a callable to each element while maintaining the chunking structure."""
+        return [
+            [
+                None if val is None else func(val)
+                for val in chunk.to_numpy(zero_copy_only=False)
+            ]
+            for chunk in self._pa_array.iterchunks()
+        ]
+
+    def _convert_bool_result(self, result, na=lib.no_default, method_name=None):
+        if na is not lib.no_default and not isna(
+            na
+        ):  # pyright: ignore [reportGeneralTypeIssues]
+            result = result.fill_null(na)
+        return type(self)(result)
+
+    def _convert_int_result(self, result):
+        return type(self)(result)
+
+    def _convert_rank_result(self, result):
+        return type(self)(result)
+
+    def _str_count(self, pat: str, flags: int = 0):
+        if flags:
+            raise NotImplementedError(f"count not implemented with {flags=}")
+        return type(self)(pc.count_substring_regex(self._pa_array, pat))
+
+    def _str_repeat(self, repeats: int | Sequence[int]):
+        if not isinstance(repeats, int):
+            raise NotImplementedError(
+                f"repeat is not implemented when repeats is {type(repeats).__name__}"
+            )
+        else:
+            return type(self)(pc.binary_repeat(self._pa_array, repeats))
+
+    def _str_join(self, sep: str):
+        if pa.types.is_string(self._pa_array.type) or pa.types.is_large_string(
+            self._pa_array.type
+        ):
+            result = self._apply_elementwise(list)
+            result = pa.chunked_array(result, type=pa.list_(pa.string()))
+        else:
+            result = self._pa_array
+        return type(self)(pc.binary_join(result, sep))
+
+    def _str_partition(self, sep: str, expand: bool):
+        predicate = lambda val: val.partition(sep)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_rpartition(self, sep: str, expand: bool):
+        predicate = lambda val: val.rpartition(sep)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_casefold(self):
+        predicate = lambda val: val.casefold()
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_encode(self, encoding: str, errors: str = "strict"):
+        predicate = lambda val: val.encode(encoding, errors)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_extract(self, pat: str, flags: int = 0, expand: bool = True):
+        if flags:
+            raise NotImplementedError("Only flags=0 is implemented.")
+        groups = re.compile(pat).groupindex.keys()
+        if len(groups) == 0:
+            raise ValueError(f"{pat=} must contain a symbolic group name.")
+        result = pc.extract_regex(self._pa_array, pat)
+        if expand:
+            return {
+                col: type(self)(pc.struct_field(result, [i]))
+                for col, i in zip(groups, range(result.type.num_fields))
+            }
+        else:
+            return type(self)(pc.struct_field(result, [0]))
+
+    def _str_findall(self, pat: str, flags: int = 0):
+        regex = re.compile(pat, flags=flags)
+        predicate = lambda val: regex.findall(val)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_get_dummies(self, sep: str = "|"):
+        split = pc.split_pattern(self._pa_array, sep)
+        flattened_values = pc.list_flatten(split)
+        uniques = flattened_values.unique()
+        uniques_sorted = uniques.take(pa.compute.array_sort_indices(uniques))
+        lengths = pc.list_value_length(split).fill_null(0).to_numpy()
+        n_rows = len(self)
+        n_cols = len(uniques)
+        indices = pc.index_in(flattened_values, uniques_sorted).to_numpy()
+        indices = indices + np.arange(n_rows).repeat(lengths) * n_cols
+        dummies = np.zeros(n_rows * n_cols, dtype=np.bool_)
+        dummies[indices] = True
+        dummies = dummies.reshape((n_rows, n_cols))
+        result = type(self)(pa.array(list(dummies)))
+        return result, uniques_sorted.to_pylist()
+
+    def _str_index(self, sub: str, start: int = 0, end: int | None = None):
+        predicate = lambda val: val.index(sub, start, end)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_rindex(self, sub: str, start: int = 0, end: int | None = None):
+        predicate = lambda val: val.rindex(sub, start, end)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_normalize(self, form: str):
+        predicate = lambda val: unicodedata.normalize(form, val)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_rfind(self, sub: str, start: int = 0, end=None):
+        predicate = lambda val: val.rfind(sub, start, end)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_split(
+        self,
+        pat: str | None = None,
+        n: int | None = -1,
+        expand: bool = False,
+        regex: bool | None = None,
+    ):
+        if n in {-1, 0}:
+            n = None
+        if pat is None:
+            split_func = pc.utf8_split_whitespace
+        elif regex:
+            split_func = functools.partial(pc.split_pattern_regex, pattern=pat)
+        else:
+            split_func = functools.partial(pc.split_pattern, pattern=pat)
+        return type(self)(split_func(self._pa_array, max_splits=n))
+
+    def _str_rsplit(self, pat: str | None = None, n: int | None = -1):
+        if n in {-1, 0}:
+            n = None
+        if pat is None:
+            return type(self)(
+                pc.utf8_split_whitespace(self._pa_array, max_splits=n, reverse=True)
+            )
+        else:
+            return type(self)(
+                pc.split_pattern(self._pa_array, pat, max_splits=n, reverse=True)
+            )
+
+    def _str_translate(self, table: dict[int, str]):
+        predicate = lambda val: val.translate(table)
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    def _str_wrap(self, width: int, **kwargs):
+        kwargs["width"] = width
+        tw = textwrap.TextWrapper(**kwargs)
+        predicate = lambda val: "\n".join(tw.wrap(val))
+        result = self._apply_elementwise(predicate)
+        return type(self)(pa.chunked_array(result))
+
+    @property
+    def _dt_days(self):
+        return type(self)(
+            pa.array(self._to_timedeltaarray().days, from_pandas=True, type=pa.int32())
+        )
+
+    @property
+    def _dt_hours(self):
+        return type(self)(
+            pa.array(
+                [
+                    td.components.hours if td is not NaT else None
+                    for td in self._to_timedeltaarray()
+                ],
+                type=pa.int32(),
+            )
+        )
+
+    @property
+    def _dt_minutes(self):
+        return type(self)(
+            pa.array(
+                [
+                    td.components.minutes if td is not NaT else None
+                    for td in self._to_timedeltaarray()
+                ],
+                type=pa.int32(),
+            )
+        )
+
+    @property
+    def _dt_seconds(self):
+        return type(self)(
+            pa.array(
+                self._to_timedeltaarray().seconds, from_pandas=True, type=pa.int32()
+            )
+        )
+
+    @property
+    def _dt_milliseconds(self):
+        return type(self)(
+            pa.array(
+                [
+                    td.components.milliseconds if td is not NaT else None
+                    for td in self._to_timedeltaarray()
+                ],
+                type=pa.int32(),
+            )
+        )
+
+    @property
+    def _dt_microseconds(self):
+        return type(self)(
+            pa.array(
+                self._to_timedeltaarray().microseconds,
+                from_pandas=True,
+                type=pa.int32(),
+            )
+        )
+
+    @property
+    def _dt_nanoseconds(self):
+        return type(self)(
+            pa.array(
+                self._to_timedeltaarray().nanoseconds, from_pandas=True, type=pa.int32()
+            )
+        )
+
+    def _dt_to_pytimedelta(self):
+        data = self._pa_array.to_pylist()
+        if self._dtype.pyarrow_dtype.unit == "ns":
+            data = [None if ts is None else ts.to_pytimedelta() for ts in data]
+        return np.array(data, dtype=object)
+
+    def _dt_total_seconds(self):
+        return type(self)(
+            pa.array(self._to_timedeltaarray().total_seconds(), from_pandas=True)
+        )
+
+    def _dt_as_unit(self, unit: str):
+        if pa.types.is_date(self.dtype.pyarrow_dtype):
+            raise NotImplementedError("as_unit not implemented for date types")
+        pd_array = self._maybe_convert_datelike_array()
+        # Don't just cast _pa_array in order to follow pandas unit conversion rules
+        return type(self)(pa.array(pd_array.as_unit(unit), from_pandas=True))
+
+    @property
+    def _dt_year(self):
+        return type(self)(pc.year(self._pa_array))
+
+    @property
+    def _dt_day(self):
+        return type(self)(pc.day(self._pa_array))
+
+    @property
+    def _dt_day_of_week(self):
+        return type(self)(pc.day_of_week(self._pa_array))
+
+    _dt_dayofweek = _dt_day_of_week
+    _dt_weekday = _dt_day_of_week
+
+    @property
+    def _dt_day_of_year(self):
+        return type(self)(pc.day_of_year(self._pa_array))
+
+    _dt_dayofyear = _dt_day_of_year
+
+    @property
+    def _dt_hour(self):
+        return type(self)(pc.hour(self._pa_array))
+
+    def _dt_isocalendar(self):
+        return type(self)(pc.iso_calendar(self._pa_array))
+
+    @property
+    def _dt_is_leap_year(self):
+        return type(self)(pc.is_leap_year(self._pa_array))
+
+    @property
+    def _dt_is_month_start(self):
+        return type(self)(pc.equal(pc.day(self._pa_array), 1))
+
+    @property
+    def _dt_is_month_end(self):
+        result = pc.equal(
+            pc.days_between(
+                pc.floor_temporal(self._pa_array, unit="day"),
+                pc.ceil_temporal(self._pa_array, unit="month"),
+            ),
+            1,
+        )
+        return type(self)(result)
+
+    @property
+    def _dt_is_year_start(self):
+        return type(self)(
+            pc.and_(
+                pc.equal(pc.month(self._pa_array), 1),
+                pc.equal(pc.day(self._pa_array), 1),
+            )
+        )
+
+    @property
+    def _dt_is_year_end(self):
+        return type(self)(
+            pc.and_(
+                pc.equal(pc.month(self._pa_array), 12),
+                pc.equal(pc.day(self._pa_array), 31),
+            )
+        )
+
+    @property
+    def _dt_is_quarter_start(self):
+        result = pc.equal(
+            pc.floor_temporal(self._pa_array, unit="quarter"),
+            pc.floor_temporal(self._pa_array, unit="day"),
+        )
+        return type(self)(result)
+
+    @property
+    def _dt_is_quarter_end(self):
+        result = pc.equal(
+            pc.days_between(
+                pc.floor_temporal(self._pa_array, unit="day"),
+                pc.ceil_temporal(self._pa_array, unit="quarter"),
+            ),
+            1,
+        )
+        return type(self)(result)
+
+    @property
+    def _dt_days_in_month(self):
+        result = pc.days_between(
+            pc.floor_temporal(self._pa_array, unit="month"),
+            pc.ceil_temporal(self._pa_array, unit="month"),
+        )
+        return type(self)(result)
+
+    _dt_daysinmonth = _dt_days_in_month
+
+    @property
+    def _dt_microsecond(self):
+        return type(self)(pc.microsecond(self._pa_array))
+
+    @property
+    def _dt_minute(self):
+        return type(self)(pc.minute(self._pa_array))
+
+    @property
+    def _dt_month(self):
+        return type(self)(pc.month(self._pa_array))
+
+    @property
+    def _dt_nanosecond(self):
+        return type(self)(pc.nanosecond(self._pa_array))
+
+    @property
+    def _dt_quarter(self):
+        return type(self)(pc.quarter(self._pa_array))
+
+    @property
+    def _dt_second(self):
+        return type(self)(pc.second(self._pa_array))
+
+    @property
+    def _dt_date(self):
+        return type(self)(self._pa_array.cast(pa.date32()))
+
+    @property
+    def _dt_time(self):
+        unit = (
+            self.dtype.pyarrow_dtype.unit
+            if self.dtype.pyarrow_dtype.unit in {"us", "ns"}
+            else "ns"
+        )
+        return type(self)(self._pa_array.cast(pa.time64(unit)))
+
+    @property
+    def _dt_tz(self):
+        return timezones.maybe_get_tz(self.dtype.pyarrow_dtype.tz)
+
+    @property
+    def _dt_unit(self):
+        return self.dtype.pyarrow_dtype.unit
+
+    def _dt_normalize(self):
+        return type(self)(pc.floor_temporal(self._pa_array, 1, "day"))
+
+    def _dt_strftime(self, format: str):
+        return type(self)(pc.strftime(self._pa_array, format=format))
+
+    def _round_temporally(
+        self,
+        method: Literal["ceil", "floor", "round"],
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ):
+        if ambiguous != "raise":
+            raise NotImplementedError("ambiguous is not supported.")
+        if nonexistent != "raise":
+            raise NotImplementedError("nonexistent is not supported.")
+        offset = to_offset(freq)
+        if offset is None:
+            raise ValueError(f"Must specify a valid frequency: {freq}")
+        pa_supported_unit = {
+            "Y": "year",
+            "YS": "year",
+            "Q": "quarter",
+            "QS": "quarter",
+            "M": "month",
+            "MS": "month",
+            "W": "week",
+            "D": "day",
+            "h": "hour",
+            "min": "minute",
+            "s": "second",
+            "ms": "millisecond",
+            "us": "microsecond",
+            "ns": "nanosecond",
+        }
+        unit = pa_supported_unit.get(offset._prefix, None)
+        if unit is None:
+            raise ValueError(f"{freq=} is not supported")
+        multiple = offset.n
+        rounding_method = getattr(pc, f"{method}_temporal")
+        return type(self)(rounding_method(self._pa_array, multiple=multiple, unit=unit))
+
+    def _dt_ceil(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ):
+        return self._round_temporally("ceil", freq, ambiguous, nonexistent)
+
+    def _dt_floor(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ):
+        return self._round_temporally("floor", freq, ambiguous, nonexistent)
+
+    def _dt_round(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ):
+        return self._round_temporally("round", freq, ambiguous, nonexistent)
+
+    def _dt_day_name(self, locale: str | None = None):
+        if locale is None:
+            locale = "C"
+        return type(self)(pc.strftime(self._pa_array, format="%A", locale=locale))
+
+    def _dt_month_name(self, locale: str | None = None):
+        if locale is None:
+            locale = "C"
+        return type(self)(pc.strftime(self._pa_array, format="%B", locale=locale))
+
+    def _dt_to_pydatetime(self):
+        if pa.types.is_date(self.dtype.pyarrow_dtype):
+            raise ValueError(
+                f"to_pydatetime cannot be called with {self.dtype.pyarrow_dtype} type. "
+                "Convert to pyarrow timestamp type."
+            )
+        data = self._pa_array.to_pylist()
+        if self._dtype.pyarrow_dtype.unit == "ns":
+            data = [None if ts is None else ts.to_pydatetime(warn=False) for ts in data]
+        return np.array(data, dtype=object)
+
+    def _dt_tz_localize(
+        self,
+        tz,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ):
+        if ambiguous != "raise":
+            raise NotImplementedError(f"{ambiguous=} is not supported")
+        nonexistent_pa = {
+            "raise": "raise",
+            "shift_backward": "earliest",
+            "shift_forward": "latest",
+        }.get(
+            nonexistent, None  # type: ignore[arg-type]
+        )
+        if nonexistent_pa is None:
+            raise NotImplementedError(f"{nonexistent=} is not supported")
+        if tz is None:
+            result = self._pa_array.cast(pa.timestamp(self.dtype.pyarrow_dtype.unit))
+        else:
+            result = pc.assume_timezone(
+                self._pa_array, str(tz), ambiguous=ambiguous, nonexistent=nonexistent_pa
+            )
+        return type(self)(result)
+
+    def _dt_tz_convert(self, tz):
+        if self.dtype.pyarrow_dtype.tz is None:
+            raise TypeError(
+                "Cannot convert tz-naive timestamps, use tz_localize to localize"
+            )
+        current_unit = self.dtype.pyarrow_dtype.unit
+        result = self._pa_array.cast(pa.timestamp(current_unit, tz))
+        return type(self)(result)
+
+
+def transpose_homogeneous_pyarrow(
+    arrays: Sequence[ArrowExtensionArray],
+) -> list[ArrowExtensionArray]:
+    """Transpose arrow extension arrays in a list, but faster.
+
+    Input should be a list of arrays of equal length and all have the same
+    dtype. The caller is responsible for ensuring validity of input data.
+    """
+    arrays = list(arrays)
+    nrows, ncols = len(arrays[0]), len(arrays)
+    indices = np.arange(nrows * ncols).reshape(ncols, nrows).T.flatten()
+    arr = pa.chunked_array([chunk for arr in arrays for chunk in arr._pa_array.chunks])
+    arr = arr.take(indices)
+    return [ArrowExtensionArray(arr.slice(i * ncols, ncols)) for i in range(nrows)]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/extension_types.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/extension_types.py
new file mode 100644
index 0000000000000000000000000000000000000000..72bfd6f2212f8fae6ea7786599de44beaeb3f902
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/arrow/extension_types.py
@@ -0,0 +1,174 @@
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+import pyarrow
+
+from pandas.compat import pa_version_under14p1
+
+from pandas.core.dtypes.dtypes import (
+    IntervalDtype,
+    PeriodDtype,
+)
+
+from pandas.core.arrays.interval import VALID_CLOSED
+
+if TYPE_CHECKING:
+    from pandas._typing import IntervalClosedType
+
+
+class ArrowPeriodType(pyarrow.ExtensionType):
+    def __init__(self, freq) -> None:
+        # attributes need to be set first before calling
+        # super init (as that calls serialize)
+        self._freq = freq
+        pyarrow.ExtensionType.__init__(self, pyarrow.int64(), "pandas.period")
+
+    @property
+    def freq(self):
+        return self._freq
+
+    def __arrow_ext_serialize__(self) -> bytes:
+        metadata = {"freq": self.freq}
+        return json.dumps(metadata).encode()
+
+    @classmethod
+    def __arrow_ext_deserialize__(cls, storage_type, serialized) -> ArrowPeriodType:
+        metadata = json.loads(serialized.decode())
+        return ArrowPeriodType(metadata["freq"])
+
+    def __eq__(self, other):
+        if isinstance(other, pyarrow.BaseExtensionType):
+            return type(self) == type(other) and self.freq == other.freq
+        else:
+            return NotImplemented
+
+    def __ne__(self, other) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        return hash((str(self), self.freq))
+
+    def to_pandas_dtype(self) -> PeriodDtype:
+        return PeriodDtype(freq=self.freq)
+
+
+# register the type with a dummy instance
+_period_type = ArrowPeriodType("D")
+pyarrow.register_extension_type(_period_type)
+
+
+class ArrowIntervalType(pyarrow.ExtensionType):
+    def __init__(self, subtype, closed: IntervalClosedType) -> None:
+        # attributes need to be set first before calling
+        # super init (as that calls serialize)
+        assert closed in VALID_CLOSED
+        self._closed: IntervalClosedType = closed
+        if not isinstance(subtype, pyarrow.DataType):
+            subtype = pyarrow.type_for_alias(str(subtype))
+        self._subtype = subtype
+
+        storage_type = pyarrow.struct([("left", subtype), ("right", subtype)])
+        pyarrow.ExtensionType.__init__(self, storage_type, "pandas.interval")
+
+    @property
+    def subtype(self):
+        return self._subtype
+
+    @property
+    def closed(self) -> IntervalClosedType:
+        return self._closed
+
+    def __arrow_ext_serialize__(self) -> bytes:
+        metadata = {"subtype": str(self.subtype), "closed": self.closed}
+        return json.dumps(metadata).encode()
+
+    @classmethod
+    def __arrow_ext_deserialize__(cls, storage_type, serialized) -> ArrowIntervalType:
+        metadata = json.loads(serialized.decode())
+        subtype = pyarrow.type_for_alias(metadata["subtype"])
+        closed = metadata["closed"]
+        return ArrowIntervalType(subtype, closed)
+
+    def __eq__(self, other):
+        if isinstance(other, pyarrow.BaseExtensionType):
+            return (
+                type(self) == type(other)
+                and self.subtype == other.subtype
+                and self.closed == other.closed
+            )
+        else:
+            return NotImplemented
+
+    def __ne__(self, other) -> bool:
+        return not self == other
+
+    def __hash__(self) -> int:
+        return hash((str(self), str(self.subtype), self.closed))
+
+    def to_pandas_dtype(self) -> IntervalDtype:
+        return IntervalDtype(self.subtype.to_pandas_dtype(), self.closed)
+
+
+# register the type with a dummy instance
+_interval_type = ArrowIntervalType(pyarrow.int64(), "left")
+pyarrow.register_extension_type(_interval_type)
+
+
+_ERROR_MSG = """\
+Disallowed deserialization of 'arrow.py_extension_type':
+storage_type = {storage_type}
+serialized = {serialized}
+pickle disassembly:\n{pickle_disassembly}
+
+Reading of untrusted Parquet or Feather files with a PyExtensionType column
+allows arbitrary code execution.
+If you trust this file, you can enable reading the extension type by one of:
+
+- upgrading to pyarrow >= 14.0.1, and call `pa.PyExtensionType.set_auto_load(True)`
+- install pyarrow-hotfix (`pip install pyarrow-hotfix`) and disable it by running
+  `import pyarrow_hotfix; pyarrow_hotfix.uninstall()`
+
+We strongly recommend updating your Parquet/Feather files to use extension types
+derived from `pyarrow.ExtensionType` instead, and register this type explicitly.
+"""
+
+
+def patch_pyarrow():
+    # starting from pyarrow 14.0.1, it has its own mechanism
+    if not pa_version_under14p1:
+        return
+
+    # if https://github.com/pitrou/pyarrow-hotfix was installed and enabled
+    if getattr(pyarrow, "_hotfix_installed", False):
+        return
+
+    class ForbiddenExtensionType(pyarrow.ExtensionType):
+        def __arrow_ext_serialize__(self):
+            return b""
+
+        @classmethod
+        def __arrow_ext_deserialize__(cls, storage_type, serialized):
+            import io
+            import pickletools
+
+            out = io.StringIO()
+            pickletools.dis(serialized, out)
+            raise RuntimeError(
+                _ERROR_MSG.format(
+                    storage_type=storage_type,
+                    serialized=serialized,
+                    pickle_disassembly=out.getvalue(),
+                )
+            )
+
+    pyarrow.unregister_extension_type("arrow.py_extension_type")
+    pyarrow.register_extension_type(
+        ForbiddenExtensionType(pyarrow.null(), "arrow.py_extension_type")
+    )
+
+    pyarrow._hotfix_installed = True
+
+
+patch_pyarrow()
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/base.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..62458b89f9c089fb663c2524b4dd585000336712
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/base.py
@@ -0,0 +1,2612 @@
+"""
+An interface for extending pandas with custom arrays.
+
+.. warning::
+
+   This is an experimental API and subject to breaking changes
+   without warning.
+"""
+from __future__ import annotations
+
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ClassVar,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    algos as libalgos,
+    lib,
+)
+from pandas.compat import set_function_name
+from pandas.compat.numpy import function as nv
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    cache_readonly,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import (
+    validate_bool_kwarg,
+    validate_fillna_kwargs,
+    validate_insert_loc,
+)
+
+from pandas.core.dtypes.cast import maybe_cast_pointwise_result
+from pandas.core.dtypes.common import (
+    is_list_like,
+    is_scalar,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import (
+    arraylike,
+    missing,
+    roperator,
+)
+from pandas.core.algorithms import (
+    duplicated,
+    factorize_array,
+    isin,
+    map_array,
+    mode,
+    rank,
+    unique,
+)
+from pandas.core.array_algos.quantile import quantile_with_mask
+from pandas.core.missing import _fill_limit_area_1d
+from pandas.core.sorting import (
+    nargminmax,
+    nargsort,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterator,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        AstypeArg,
+        AxisInt,
+        Dtype,
+        DtypeObj,
+        FillnaOptions,
+        InterpolateOptions,
+        NumpySorter,
+        NumpyValueArrayLike,
+        PositionalIndexer,
+        ScalarIndexer,
+        Self,
+        SequenceIndexer,
+        Shape,
+        SortKind,
+        TakeIndexer,
+        npt,
+    )
+
+    from pandas import Index
+
+_extension_array_shared_docs: dict[str, str] = {}
+
+
+class ExtensionArray:
+    """
+    Abstract base class for custom 1-D array types.
+
+    pandas will recognize instances of this class as proper arrays
+    with a custom type and will not attempt to coerce them to objects. They
+    may be stored directly inside a :class:`DataFrame` or :class:`Series`.
+
+    Attributes
+    ----------
+    dtype
+    nbytes
+    ndim
+    shape
+
+    Methods
+    -------
+    argsort
+    astype
+    copy
+    dropna
+    duplicated
+    factorize
+    fillna
+    equals
+    insert
+    interpolate
+    isin
+    isna
+    ravel
+    repeat
+    searchsorted
+    shift
+    take
+    tolist
+    unique
+    view
+    _accumulate
+    _concat_same_type
+    _explode
+    _formatter
+    _from_factorized
+    _from_sequence
+    _from_sequence_of_strings
+    _hash_pandas_object
+    _pad_or_backfill
+    _reduce
+    _values_for_argsort
+    _values_for_factorize
+
+    Notes
+    -----
+    The interface includes the following abstract methods that must be
+    implemented by subclasses:
+
+    * _from_sequence
+    * _from_factorized
+    * __getitem__
+    * __len__
+    * __eq__
+    * dtype
+    * nbytes
+    * isna
+    * take
+    * copy
+    * _concat_same_type
+    * interpolate
+
+    A default repr displaying the type, (truncated) data, length,
+    and dtype is provided. It can be customized or replaced by
+    by overriding:
+
+    * __repr__ : A default repr for the ExtensionArray.
+    * _formatter : Print scalars inside a Series or DataFrame.
+
+    Some methods require casting the ExtensionArray to an ndarray of Python
+    objects with ``self.astype(object)``, which may be expensive. When
+    performance is a concern, we highly recommend overriding the following
+    methods:
+
+    * fillna
+    * _pad_or_backfill
+    * dropna
+    * unique
+    * factorize / _values_for_factorize
+    * argsort, argmax, argmin / _values_for_argsort
+    * searchsorted
+    * map
+
+    The remaining methods implemented on this class should be performant,
+    as they only compose abstract methods. Still, a more efficient
+    implementation may be available, and these methods can be overridden.
+
+    One can implement methods to handle array accumulations or reductions.
+
+    * _accumulate
+    * _reduce
+
+    One can implement methods to handle parsing from strings that will be used
+    in methods such as ``pandas.io.parsers.read_csv``.
+
+    * _from_sequence_of_strings
+
+    This class does not inherit from 'abc.ABCMeta' for performance reasons.
+    Methods and properties required by the interface raise
+    ``pandas.errors.AbstractMethodError`` and no ``register`` method is
+    provided for registering virtual subclasses.
+
+    ExtensionArrays are limited to 1 dimension.
+
+    They may be backed by none, one, or many NumPy arrays. For example,
+    ``pandas.Categorical`` is an extension array backed by two arrays,
+    one for codes and one for categories. An array of IPv6 address 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. Pandas makes no
+    assumptions on how the data are stored, just that it can be converted
+    to a NumPy array.
+    The ExtensionArray interface does not impose any rules on how this data
+    is stored. However, currently, the backing data cannot be stored in
+    attributes called ``.values`` or ``._values`` to ensure full compatibility
+    with pandas internals. But other names as ``.data``, ``._data``,
+    ``._items``, ... can be freely used.
+
+    If implementing NumPy's ``__array_ufunc__`` interface, pandas expects
+    that
+
+    1. You defer by returning ``NotImplemented`` when any Series are present
+       in `inputs`. Pandas will extract the arrays and call the ufunc again.
+    2. You define a ``_HANDLED_TYPES`` tuple as an attribute on the class.
+       Pandas inspect this to determine whether the ufunc is valid for the
+       types present.
+
+    See :ref:`extending.extension.ufunc` for more.
+
+    By default, ExtensionArrays are not hashable.  Immutable subclasses may
+    override this behavior.
+
+    Examples
+    --------
+    Please see the following:
+
+    https://github.com/pandas-dev/pandas/blob/main/pandas/tests/extension/list/array.py
+    """
+
+    # '_typ' is for pandas.core.dtypes.generic.ABCExtensionArray.
+    # Don't override this.
+    _typ = "extension"
+
+    # similar to __array_priority__, positions ExtensionArray after Index,
+    #  Series, and DataFrame.  EA subclasses may override to choose which EA
+    #  subclass takes priority. If overriding, the value should always be
+    #  strictly less than 2000 to be below Index.__pandas_priority__.
+    __pandas_priority__ = 1000
+
+    # ------------------------------------------------------------------------
+    # Constructors
+    # ------------------------------------------------------------------------
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy: bool = False):
+        """
+        Construct a new ExtensionArray from a sequence of scalars.
+
+        Parameters
+        ----------
+        scalars : Sequence
+            Each element will be an instance of the scalar type for this
+            array, ``cls.dtype.type`` or be converted into this type in this method.
+        dtype : dtype, optional
+            Construct for this particular dtype. This should be a Dtype
+            compatible with the ExtensionArray.
+        copy : bool, default False
+            If True, copy the underlying data.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Examples
+        --------
+        >>> pd.arrays.IntegerArray._from_sequence([4, 5])
+        
+        [4, 5]
+        Length: 2, dtype: Int64
+        """
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _from_scalars(cls, scalars, *, dtype: DtypeObj) -> Self:
+        """
+        Strict analogue to _from_sequence, allowing only sequences of scalars
+        that should be specifically inferred to the given dtype.
+
+        Parameters
+        ----------
+        scalars : sequence
+        dtype : ExtensionDtype
+
+        Raises
+        ------
+        TypeError or ValueError
+
+        Notes
+        -----
+        This is called in a try/except block when casting the result of a
+        pointwise operation.
+        """
+        try:
+            return cls._from_sequence(scalars, dtype=dtype, copy=False)
+        except (ValueError, TypeError):
+            raise
+        except Exception:
+            warnings.warn(
+                "_from_scalars should only raise ValueError or TypeError. "
+                "Consider overriding _from_scalars where appropriate.",
+                stacklevel=find_stack_level(),
+            )
+            raise
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, *, dtype: Dtype | None = None, copy: bool = False
+    ):
+        """
+        Construct a new ExtensionArray from a sequence of strings.
+
+        Parameters
+        ----------
+        strings : Sequence
+            Each element will be an instance of the scalar type for this
+            array, ``cls.dtype.type``.
+        dtype : dtype, optional
+            Construct for this particular dtype. This should be a Dtype
+            compatible with the ExtensionArray.
+        copy : bool, default False
+            If True, copy the underlying data.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Examples
+        --------
+        >>> pd.arrays.IntegerArray._from_sequence_of_strings(["1", "2", "3"])
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _from_factorized(cls, values, original):
+        """
+        Reconstruct an ExtensionArray after factorization.
+
+        Parameters
+        ----------
+        values : ndarray
+            An integer ndarray with the factorized values.
+        original : ExtensionArray
+            The original ExtensionArray that factorize was called on.
+
+        See Also
+        --------
+        factorize : Top-level factorize method that dispatches here.
+        ExtensionArray.factorize : Encode the extension array as an enumerated type.
+
+        Examples
+        --------
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1),
+        ...                                      pd.Interval(1, 5), pd.Interval(1, 5)])
+        >>> codes, uniques = pd.factorize(interv_arr)
+        >>> pd.arrays.IntervalArray._from_factorized(uniques, interv_arr)
+        
+        [(0, 1], (1, 5]]
+        Length: 2, dtype: interval[int64, right]
+        """
+        raise AbstractMethodError(cls)
+
+    # ------------------------------------------------------------------------
+    # Must be a Sequence
+    # ------------------------------------------------------------------------
+    @overload
+    def __getitem__(self, item: ScalarIndexer) -> Any:
+        ...
+
+    @overload
+    def __getitem__(self, item: SequenceIndexer) -> Self:
+        ...
+
+    def __getitem__(self, item: PositionalIndexer) -> Self | Any:
+        """
+        Select a subset of self.
+
+        Parameters
+        ----------
+        item : int, slice, or ndarray
+            * int: The position in 'self' to get.
+
+            * slice: A slice object, where 'start', 'stop', and 'step' are
+              integers or None
+
+            * ndarray: A 1-d boolean NumPy ndarray the same length as 'self'
+
+            * list[int]:  A list of int
+
+        Returns
+        -------
+        item : scalar or ExtensionArray
+
+        Notes
+        -----
+        For scalar ``item``, return a scalar value suitable for the array's
+        type. This should be an instance of ``self.dtype.type``.
+
+        For slice ``key``, return an instance of ``ExtensionArray``, even
+        if the slice is length 0 or 1.
+
+        For a boolean mask, return an instance of ``ExtensionArray``, filtered
+        to the values where ``item`` is True.
+        """
+        raise AbstractMethodError(self)
+
+    def __setitem__(self, key, value) -> None:
+        """
+        Set one or more values inplace.
+
+        This method is not required to satisfy the pandas extension array
+        interface.
+
+        Parameters
+        ----------
+        key : int, ndarray, or slice
+            When called from, e.g. ``Series.__setitem__``, ``key`` will be
+            one of
+
+            * scalar int
+            * ndarray of integers.
+            * boolean ndarray
+            * slice object
+
+        value : ExtensionDtype.type, Sequence[ExtensionDtype.type], or object
+            value or values to be set of ``key``.
+
+        Returns
+        -------
+        None
+        """
+        # Some notes to the ExtensionArray implementer who may have ended up
+        # here. While this method is not required for the interface, if you
+        # *do* choose to implement __setitem__, then some semantics should be
+        # observed:
+        #
+        # * Setting multiple values : ExtensionArrays should support setting
+        #   multiple values at once, 'key' will be a sequence of integers and
+        #  'value' will be a same-length sequence.
+        #
+        # * Broadcasting : For a sequence 'key' and a scalar 'value',
+        #   each position in 'key' should be set to 'value'.
+        #
+        # * Coercion : Most users will expect basic coercion to work. For
+        #   example, a string like '2018-01-01' is coerced to a datetime
+        #   when setting on a datetime64ns array. In general, if the
+        #   __init__ method coerces that value, then so should __setitem__
+        # Note, also, that Series/DataFrame.where internally use __setitem__
+        # on a copy of the data.
+        raise NotImplementedError(f"{type(self)} does not implement __setitem__.")
+
+    def __len__(self) -> int:
+        """
+        Length of this array
+
+        Returns
+        -------
+        length : int
+        """
+        raise AbstractMethodError(self)
+
+    def __iter__(self) -> Iterator[Any]:
+        """
+        Iterate over elements of the array.
+        """
+        # This needs to be implemented so that pandas recognizes extension
+        # arrays as list-like. The default implementation makes successive
+        # calls to ``__getitem__``, which may be slower than necessary.
+        for i in range(len(self)):
+            yield self[i]
+
+    def __contains__(self, item: object) -> bool | np.bool_:
+        """
+        Return for `item in self`.
+        """
+        # GH37867
+        # comparisons of any item to pd.NA always return pd.NA, so e.g. "a" in [pd.NA]
+        # would raise a TypeError. The implementation below works around that.
+        if is_scalar(item) and isna(item):
+            if not self._can_hold_na:
+                return False
+            elif item is self.dtype.na_value or isinstance(item, self.dtype.type):
+                return self._hasna
+            else:
+                return False
+        else:
+            # error: Item "ExtensionArray" of "Union[ExtensionArray, ndarray]" has no
+            # attribute "any"
+            return (item == self).any()  # type: ignore[union-attr]
+
+    # error: Signature of "__eq__" incompatible with supertype "object"
+    def __eq__(self, other: object) -> ArrayLike:  # type: ignore[override]
+        """
+        Return for `self == other` (element-wise equality).
+        """
+        # Implementer note: this should return a boolean numpy ndarray or
+        # a boolean ExtensionArray.
+        # When `other` is one of Series, Index, or DataFrame, this method should
+        # return NotImplemented (to ensure that those objects are responsible for
+        # first unpacking the arrays, and then dispatch the operation to the
+        # underlying arrays)
+        raise AbstractMethodError(self)
+
+    # error: Signature of "__ne__" incompatible with supertype "object"
+    def __ne__(self, other: object) -> ArrayLike:  # type: ignore[override]
+        """
+        Return for `self != other` (element-wise in-equality).
+        """
+        # error: Unsupported operand type for ~ ("ExtensionArray")
+        return ~(self == other)  # type: ignore[operator]
+
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Convert to a NumPy ndarray.
+
+        This is similar to :meth:`numpy.asarray`, but may provide additional control
+        over how the conversion is done.
+
+        Parameters
+        ----------
+        dtype : str or numpy.dtype, optional
+            The dtype to pass to :meth:`numpy.asarray`.
+        copy : bool, default False
+            Whether to ensure that the returned value is a not a view on
+            another array. Note that ``copy=False`` does not *ensure* that
+            ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that
+            a copy is made, even if not strictly necessary.
+        na_value : Any, optional
+            The value to use for missing values. The default value depends
+            on `dtype` and the type of the array.
+
+        Returns
+        -------
+        numpy.ndarray
+        """
+        result = np.asarray(self, dtype=dtype)
+        if copy or na_value is not lib.no_default:
+            result = result.copy()
+        if na_value is not lib.no_default:
+            result[self.isna()] = na_value
+        return result
+
+    # ------------------------------------------------------------------------
+    # Required attributes
+    # ------------------------------------------------------------------------
+
+    @property
+    def dtype(self) -> ExtensionDtype:
+        """
+        An instance of ExtensionDtype.
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3]).dtype
+        Int64Dtype()
+        """
+        raise AbstractMethodError(self)
+
+    @property
+    def shape(self) -> Shape:
+        """
+        Return a tuple of the array dimensions.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.shape
+        (3,)
+        """
+        return (len(self),)
+
+    @property
+    def size(self) -> int:
+        """
+        The number of elements in the array.
+        """
+        # error: Incompatible return value type (got "signedinteger[_64Bit]",
+        # expected "int")  [return-value]
+        return np.prod(self.shape)  # type: ignore[return-value]
+
+    @property
+    def ndim(self) -> int:
+        """
+        Extension Arrays are only allowed to be 1-dimensional.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.ndim
+        1
+        """
+        return 1
+
+    @property
+    def nbytes(self) -> int:
+        """
+        The number of bytes needed to store this object in memory.
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3]).nbytes
+        27
+        """
+        # If this is expensive to compute, return an approximate lower bound
+        # on the number of bytes needed.
+        raise AbstractMethodError(self)
+
+    # ------------------------------------------------------------------------
+    # Additional Methods
+    # ------------------------------------------------------------------------
+
+    @overload
+    def astype(self, dtype: npt.DTypeLike, copy: bool = ...) -> np.ndarray:
+        ...
+
+    @overload
+    def astype(self, dtype: ExtensionDtype, copy: bool = ...) -> ExtensionArray:
+        ...
+
+    @overload
+    def astype(self, dtype: AstypeArg, copy: bool = ...) -> ArrayLike:
+        ...
+
+    def astype(self, dtype: AstypeArg, copy: bool = True) -> ArrayLike:
+        """
+        Cast to a NumPy array or ExtensionArray with 'dtype'.
+
+        Parameters
+        ----------
+        dtype : str or dtype
+            Typecode or data-type to which the array is cast.
+        copy : bool, default True
+            Whether to copy the data, even if not necessary. If False,
+            a copy is made only if the old dtype does not match the
+            new dtype.
+
+        Returns
+        -------
+        np.ndarray or pandas.api.extensions.ExtensionArray
+            An ``ExtensionArray`` if ``dtype`` is ``ExtensionDtype``,
+            otherwise a Numpy ndarray with ``dtype`` for its dtype.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+
+        Casting to another ``ExtensionDtype`` returns an ``ExtensionArray``:
+
+        >>> arr1 = arr.astype('Float64')
+        >>> arr1
+        
+        [1.0, 2.0, 3.0]
+        Length: 3, dtype: Float64
+        >>> arr1.dtype
+        Float64Dtype()
+
+        Otherwise, we will get a Numpy ndarray:
+
+        >>> arr2 = arr.astype('float64')
+        >>> arr2
+        array([1., 2., 3.])
+        >>> arr2.dtype
+        dtype('float64')
+        """
+        dtype = pandas_dtype(dtype)
+        if dtype == self.dtype:
+            if not copy:
+                return self
+            else:
+                return self.copy()
+
+        if isinstance(dtype, ExtensionDtype):
+            cls = dtype.construct_array_type()
+            return cls._from_sequence(self, dtype=dtype, copy=copy)
+
+        elif lib.is_np_dtype(dtype, "M"):
+            from pandas.core.arrays import DatetimeArray
+
+            return DatetimeArray._from_sequence(self, dtype=dtype, copy=copy)
+
+        elif lib.is_np_dtype(dtype, "m"):
+            from pandas.core.arrays import TimedeltaArray
+
+            return TimedeltaArray._from_sequence(self, dtype=dtype, copy=copy)
+
+        if not copy:
+            return np.asarray(self, dtype=dtype)
+        else:
+            return np.array(self, dtype=dtype, copy=copy)
+
+    def isna(self) -> np.ndarray | ExtensionArraySupportsAnyAll:
+        """
+        A 1-D array indicating if each value is missing.
+
+        Returns
+        -------
+        numpy.ndarray or pandas.api.extensions.ExtensionArray
+            In most cases, this should return a NumPy ndarray. For
+            exceptional cases like ``SparseArray``, where returning
+            an ndarray would be expensive, an ExtensionArray may be
+            returned.
+
+        Notes
+        -----
+        If returning an ExtensionArray, then
+
+        * ``na_values._is_boolean`` should be True
+        * `na_values` should implement :func:`ExtensionArray._reduce`
+        * ``na_values.any`` and ``na_values.all`` should be implemented
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, np.nan, np.nan])
+        >>> arr.isna()
+        array([False, False,  True,  True])
+        """
+        raise AbstractMethodError(self)
+
+    @property
+    def _hasna(self) -> bool:
+        # GH#22680
+        """
+        Equivalent to `self.isna().any()`.
+
+        Some ExtensionArray subclasses may be able to optimize this check.
+        """
+        return bool(self.isna().any())
+
+    def _values_for_argsort(self) -> np.ndarray:
+        """
+        Return values for sorting.
+
+        Returns
+        -------
+        ndarray
+            The transformed values should maintain the ordering between values
+            within the array.
+
+        See Also
+        --------
+        ExtensionArray.argsort : Return the indices that would sort this array.
+
+        Notes
+        -----
+        The caller is responsible for *not* modifying these values in-place, so
+        it is safe for implementers to give views on ``self``.
+
+        Functions that use this (e.g. ``ExtensionArray.argsort``) should ignore
+        entries with missing values in the original array (according to
+        ``self.isna()``). This means that the corresponding entries in the returned
+        array don't need to be modified to sort correctly.
+
+        Examples
+        --------
+        In most cases, this is the underlying Numpy array of the ``ExtensionArray``:
+
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr._values_for_argsort()
+        array([1, 2, 3])
+        """
+        # Note: this is used in `ExtensionArray.argsort/argmin/argmax`.
+        return np.array(self)
+
+    def argsort(
+        self,
+        *,
+        ascending: bool = True,
+        kind: SortKind = "quicksort",
+        na_position: str = "last",
+        **kwargs,
+    ) -> np.ndarray:
+        """
+        Return the indices that would sort this array.
+
+        Parameters
+        ----------
+        ascending : bool, default True
+            Whether the indices should result in an ascending
+            or descending sort.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
+            Sorting algorithm.
+        na_position : {'first', 'last'}, default 'last'
+            If ``'first'``, put ``NaN`` values at the beginning.
+            If ``'last'``, put ``NaN`` values at the end.
+        *args, **kwargs:
+            Passed through to :func:`numpy.argsort`.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            Array of indices that sort ``self``. If NaN values are contained,
+            NaN values are placed at the end.
+
+        See Also
+        --------
+        numpy.argsort : Sorting implementation used internally.
+
+        Examples
+        --------
+        >>> arr = pd.array([3, 1, 2, 5, 4])
+        >>> arr.argsort()
+        array([1, 2, 0, 4, 3])
+        """
+        # Implementer note: You have two places to override the behavior of
+        # argsort.
+        # 1. _values_for_argsort : construct the values passed to np.argsort
+        # 2. argsort : total control over sorting. In case of overriding this,
+        #    it is recommended to also override argmax/argmin
+        ascending = nv.validate_argsort_with_ascending(ascending, (), kwargs)
+
+        values = self._values_for_argsort()
+        return nargsort(
+            values,
+            kind=kind,
+            ascending=ascending,
+            na_position=na_position,
+            mask=np.asarray(self.isna()),
+        )
+
+    def argmin(self, skipna: bool = True) -> int:
+        """
+        Return the index of minimum value.
+
+        In case of multiple occurrences of the minimum value, the index
+        corresponding to the first occurrence is returned.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        ExtensionArray.argmax : Return the index of the maximum value.
+
+        Examples
+        --------
+        >>> arr = pd.array([3, 1, 2, 5, 4])
+        >>> arr.argmin()
+        1
+        """
+        # Implementer note: You have two places to override the behavior of
+        # argmin.
+        # 1. _values_for_argsort : construct the values used in nargminmax
+        # 2. argmin itself : total control over sorting.
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return nargminmax(self, "argmin")
+
+    def argmax(self, skipna: bool = True) -> int:
+        """
+        Return the index of maximum value.
+
+        In case of multiple occurrences of the maximum value, the index
+        corresponding to the first occurrence is returned.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        ExtensionArray.argmin : Return the index of the minimum value.
+
+        Examples
+        --------
+        >>> arr = pd.array([3, 1, 2, 5, 4])
+        >>> arr.argmax()
+        3
+        """
+        # Implementer note: You have two places to override the behavior of
+        # argmax.
+        # 1. _values_for_argsort : construct the values used in nargminmax
+        # 2. argmax itself : total control over sorting.
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return nargminmax(self, "argmax")
+
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        axis: int,
+        index: Index,
+        limit,
+        limit_direction,
+        limit_area,
+        copy: bool,
+        **kwargs,
+    ) -> Self:
+        """
+        See DataFrame.interpolate.__doc__.
+
+        Examples
+        --------
+        >>> arr = pd.arrays.NumpyExtensionArray(np.array([0, 1, np.nan, 3]))
+        >>> arr.interpolate(method="linear",
+        ...                 limit=3,
+        ...                 limit_direction="forward",
+        ...                 index=pd.Index([1, 2, 3, 4]),
+        ...                 fill_value=1,
+        ...                 copy=False,
+        ...                 axis=0,
+        ...                 limit_area="inside"
+        ...                 )
+        
+        [0.0, 1.0, 2.0, 3.0]
+        Length: 4, dtype: float64
+        """
+        # NB: we return type(self) even if copy=False
+        raise NotImplementedError(
+            f"{type(self).__name__} does not implement interpolate"
+        )
+
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        """
+        Pad or backfill values, used by Series/DataFrame ffill and bfill.
+
+        Parameters
+        ----------
+        method : {'backfill', 'bfill', 'pad', 'ffill'}
+            Method to use for filling holes in reindexed Series:
+
+            * pad / ffill: propagate last valid observation forward to next valid.
+            * backfill / bfill: use NEXT valid observation to fill gap.
+
+        limit : int, default None
+            This is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled.
+
+        copy : bool, default True
+            Whether to make a copy of the data before filling. If False, then
+            the original should be modified and no new memory should be allocated.
+            For ExtensionArray subclasses that cannot do this, it is at the
+            author's discretion whether to ignore "copy=False" or to raise.
+            The base class implementation ignores the keyword if any NAs are
+            present.
+
+        Returns
+        -------
+        Same type as self
+
+        Examples
+        --------
+        >>> arr = pd.array([np.nan, np.nan, 2, 3, np.nan, np.nan])
+        >>> arr._pad_or_backfill(method="backfill", limit=1)
+        
+        [, 2, 2, 3, , ]
+        Length: 6, dtype: Int64
+        """
+
+        # If a 3rd-party EA has implemented this functionality in fillna,
+        #  we warn that they need to implement _pad_or_backfill instead.
+        if (
+            type(self).fillna is not ExtensionArray.fillna
+            and type(self)._pad_or_backfill is ExtensionArray._pad_or_backfill
+        ):
+            # Check for _pad_or_backfill here allows us to call
+            #  super()._pad_or_backfill without getting this warning
+            warnings.warn(
+                "ExtensionArray.fillna 'method' keyword is deprecated. "
+                "In a future version. arr._pad_or_backfill will be called "
+                "instead. 3rd-party ExtensionArray authors need to implement "
+                "_pad_or_backfill.",
+                DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+            if limit_area is not None:
+                raise NotImplementedError(
+                    f"{type(self).__name__} does not implement limit_area "
+                    "(added in pandas 2.2). 3rd-party ExtnsionArray authors "
+                    "need to add this argument to _pad_or_backfill."
+                )
+            return self.fillna(method=method, limit=limit)
+
+        mask = self.isna()
+
+        if mask.any():
+            # NB: the base class does not respect the "copy" keyword
+            meth = missing.clean_fill_method(method)
+
+            npmask = np.asarray(mask)
+            if limit_area is not None and not npmask.all():
+                _fill_limit_area_1d(npmask, limit_area)
+            if meth == "pad":
+                indexer = libalgos.get_fill_indexer(npmask, limit=limit)
+                return self.take(indexer, allow_fill=True)
+            else:
+                # i.e. meth == "backfill"
+                indexer = libalgos.get_fill_indexer(npmask[::-1], limit=limit)[::-1]
+                return self[::-1].take(indexer, allow_fill=True)
+
+        else:
+            if not copy:
+                return self
+            new_values = self.copy()
+        return new_values
+
+    def fillna(
+        self,
+        value: object | ArrayLike | None = None,
+        method: FillnaOptions | None = None,
+        limit: int | None = None,
+        copy: bool = True,
+    ) -> Self:
+        """
+        Fill NA/NaN values using the specified method.
+
+        Parameters
+        ----------
+        value : scalar, array-like
+            If a scalar value is passed it is used to fill all missing values.
+            Alternatively, an array-like "value" can be given. It's expected
+            that the array-like have the same length as 'self'.
+        method : {'backfill', 'bfill', 'pad', 'ffill', None}, default None
+            Method to use for filling holes in reindexed Series:
+
+            * pad / ffill: propagate last valid observation forward to next valid.
+            * backfill / bfill: use NEXT valid observation to fill gap.
+
+            .. deprecated:: 2.1.0
+
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled.
+
+            .. deprecated:: 2.1.0
+
+        copy : bool, default True
+            Whether to make a copy of the data before filling. If False, then
+            the original should be modified and no new memory should be allocated.
+            For ExtensionArray subclasses that cannot do this, it is at the
+            author's discretion whether to ignore "copy=False" or to raise.
+            The base class implementation ignores the keyword in pad/backfill
+            cases.
+
+        Returns
+        -------
+        ExtensionArray
+            With NA/NaN filled.
+
+        Examples
+        --------
+        >>> arr = pd.array([np.nan, np.nan, 2, 3, np.nan, np.nan])
+        >>> arr.fillna(0)
+        
+        [0, 0, 2, 3, 0, 0]
+        Length: 6, dtype: Int64
+        """
+        if method is not None:
+            warnings.warn(
+                f"The 'method' keyword in {type(self).__name__}.fillna is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        value, method = validate_fillna_kwargs(value, method)
+
+        mask = self.isna()
+        # error: Argument 2 to "check_value_size" has incompatible type
+        # "ExtensionArray"; expected "ndarray"
+        value = missing.check_value_size(
+            value, mask, len(self)  # type: ignore[arg-type]
+        )
+
+        if mask.any():
+            if method is not None:
+                meth = missing.clean_fill_method(method)
+
+                npmask = np.asarray(mask)
+                if meth == "pad":
+                    indexer = libalgos.get_fill_indexer(npmask, limit=limit)
+                    return self.take(indexer, allow_fill=True)
+                else:
+                    # i.e. meth == "backfill"
+                    indexer = libalgos.get_fill_indexer(npmask[::-1], limit=limit)[::-1]
+                    return self[::-1].take(indexer, allow_fill=True)
+            else:
+                # fill with value
+                if not copy:
+                    new_values = self[:]
+                else:
+                    new_values = self.copy()
+                new_values[mask] = value
+        else:
+            if not copy:
+                new_values = self[:]
+            else:
+                new_values = self.copy()
+        return new_values
+
+    def dropna(self) -> Self:
+        """
+        Return ExtensionArray without NA values.
+
+        Returns
+        -------
+
+        Examples
+        --------
+        >>> pd.array([1, 2, np.nan]).dropna()
+        
+        [1, 2]
+        Length: 2, dtype: Int64
+        """
+        # error: Unsupported operand type for ~ ("ExtensionArray")
+        return self[~self.isna()]  # type: ignore[operator]
+
+    def duplicated(
+        self, keep: Literal["first", "last", False] = "first"
+    ) -> npt.NDArray[np.bool_]:
+        """
+        Return boolean ndarray denoting duplicate values.
+
+        Parameters
+        ----------
+        keep : {'first', 'last', False}, default 'first'
+            - ``first`` : Mark duplicates as ``True`` except for the first occurrence.
+            - ``last`` : Mark duplicates as ``True`` except for the last occurrence.
+            - False : Mark all duplicates as ``True``.
+
+        Returns
+        -------
+        ndarray[bool]
+
+        Examples
+        --------
+        >>> pd.array([1, 1, 2, 3, 3], dtype="Int64").duplicated()
+        array([False,  True, False, False,  True])
+        """
+        mask = self.isna().astype(np.bool_, copy=False)
+        return duplicated(values=self, keep=keep, mask=mask)
+
+    def shift(self, periods: int = 1, fill_value: object = None) -> ExtensionArray:
+        """
+        Shift values by desired number.
+
+        Newly introduced missing values are filled with
+        ``self.dtype.na_value``.
+
+        Parameters
+        ----------
+        periods : int, default 1
+            The number of periods to shift. Negative values are allowed
+            for shifting backwards.
+
+        fill_value : object, optional
+            The scalar value to use for newly introduced missing values.
+            The default is ``self.dtype.na_value``.
+
+        Returns
+        -------
+        ExtensionArray
+            Shifted.
+
+        Notes
+        -----
+        If ``self`` is empty or ``periods`` is 0, a copy of ``self`` is
+        returned.
+
+        If ``periods > len(self)``, then an array of size
+        len(self) is returned, with all values filled with
+        ``self.dtype.na_value``.
+
+        For 2-dimensional ExtensionArrays, we are always shifting along axis=0.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.shift(2)
+        
+        [, , 1]
+        Length: 3, dtype: Int64
+        """
+        # Note: this implementation assumes that `self.dtype.na_value` can be
+        # stored in an instance of your ExtensionArray with `self.dtype`.
+        if not len(self) or periods == 0:
+            return self.copy()
+
+        if isna(fill_value):
+            fill_value = self.dtype.na_value
+
+        empty = self._from_sequence(
+            [fill_value] * min(abs(periods), len(self)), dtype=self.dtype
+        )
+        if periods > 0:
+            a = empty
+            b = self[:-periods]
+        else:
+            a = self[abs(periods) :]
+            b = empty
+        return self._concat_same_type([a, b])
+
+    def unique(self) -> Self:
+        """
+        Compute the ExtensionArray of unique values.
+
+        Returns
+        -------
+        pandas.api.extensions.ExtensionArray
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3, 1, 2, 3])
+        >>> arr.unique()
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        uniques = unique(self.astype(object))
+        return self._from_sequence(uniques, dtype=self.dtype)
+
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        """
+        Find indices where elements should be inserted to maintain order.
+
+        Find the indices into a sorted array `self` (a) such that, if the
+        corresponding elements in `value` were inserted before the indices,
+        the order of `self` would be preserved.
+
+        Assuming that `self` is sorted:
+
+        ======  ================================
+        `side`  returned index `i` satisfies
+        ======  ================================
+        left    ``self[i-1] < value <= self[i]``
+        right   ``self[i-1] <= value < self[i]``
+        ======  ================================
+
+        Parameters
+        ----------
+        value : array-like, list or scalar
+            Value(s) to insert into `self`.
+        side : {'left', 'right'}, optional
+            If 'left', the index of the first suitable location found is given.
+            If 'right', return the last such index.  If there is no suitable
+            index, return either 0 or N (where N is the length of `self`).
+        sorter : 1-D array-like, optional
+            Optional array of integer indices that sort array a into ascending
+            order. They are typically the result of argsort.
+
+        Returns
+        -------
+        array of ints or int
+            If value is array-like, array of insertion points.
+            If value is scalar, a single integer.
+
+        See Also
+        --------
+        numpy.searchsorted : Similar method from NumPy.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3, 5])
+        >>> arr.searchsorted([4])
+        array([3])
+        """
+        # Note: the base tests provided by pandas only test the basics.
+        # We do not test
+        # 1. Values outside the range of the `data_for_sorting` fixture
+        # 2. Values between the values in the `data_for_sorting` fixture
+        # 3. Missing values.
+        arr = self.astype(object)
+        if isinstance(value, ExtensionArray):
+            value = value.astype(object)
+        return arr.searchsorted(value, side=side, sorter=sorter)
+
+    def equals(self, other: object) -> bool:
+        """
+        Return if another array is equivalent to this array.
+
+        Equivalent means that both arrays have the same shape and dtype, and
+        all values compare equal. Missing values in the same location are
+        considered equal (in contrast with normal equality).
+
+        Parameters
+        ----------
+        other : ExtensionArray
+            Array to compare to this Array.
+
+        Returns
+        -------
+        boolean
+            Whether the arrays are equivalent.
+
+        Examples
+        --------
+        >>> arr1 = pd.array([1, 2, np.nan])
+        >>> arr2 = pd.array([1, 2, np.nan])
+        >>> arr1.equals(arr2)
+        True
+        """
+        if type(self) != type(other):
+            return False
+        other = cast(ExtensionArray, other)
+        if self.dtype != other.dtype:
+            return False
+        elif len(self) != len(other):
+            return False
+        else:
+            equal_values = self == other
+            if isinstance(equal_values, ExtensionArray):
+                # boolean array with NA -> fill with False
+                equal_values = equal_values.fillna(False)
+            # error: Unsupported left operand type for & ("ExtensionArray")
+            equal_na = self.isna() & other.isna()  # type: ignore[operator]
+            return bool((equal_values | equal_na).all())
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        """
+        Pointwise comparison for set containment in the given values.
+
+        Roughly equivalent to `np.array([x in values for x in self])`
+
+        Parameters
+        ----------
+        values : np.ndarray or ExtensionArray
+
+        Returns
+        -------
+        np.ndarray[bool]
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.isin([1])
+        
+        [True, False, False]
+        Length: 3, dtype: boolean
+        """
+        return isin(np.asarray(self), values)
+
+    def _values_for_factorize(self) -> tuple[np.ndarray, Any]:
+        """
+        Return an array and missing value suitable for factorization.
+
+        Returns
+        -------
+        values : ndarray
+            An array suitable for factorization. This should maintain order
+            and be a supported dtype (Float64, Int64, UInt64, String, Object).
+            By default, the extension array is cast to object dtype.
+        na_value : object
+            The value in `values` to consider missing. This will be treated
+            as NA in the factorization routines, so it will be coded as
+            `-1` and not included in `uniques`. By default,
+            ``np.nan`` is used.
+
+        Notes
+        -----
+        The values returned by this method are also used in
+        :func:`pandas.util.hash_pandas_object`. If needed, this can be
+        overridden in the ``self._hash_pandas_object()`` method.
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3])._values_for_factorize()
+        (array([1, 2, 3], dtype=object), nan)
+        """
+        return self.astype(object), np.nan
+
+    def factorize(
+        self,
+        use_na_sentinel: bool = True,
+    ) -> tuple[np.ndarray, ExtensionArray]:
+        """
+        Encode the extension array as an enumerated type.
+
+        Parameters
+        ----------
+        use_na_sentinel : bool, default True
+            If True, the sentinel -1 will be used for NaN values. If False,
+            NaN values will be encoded as non-negative integers and will not drop the
+            NaN from the uniques of the values.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        codes : ndarray
+            An integer NumPy array that's an indexer into the original
+            ExtensionArray.
+        uniques : ExtensionArray
+            An ExtensionArray containing the unique values of `self`.
+
+            .. note::
+
+               uniques will *not* contain an entry for the NA value of
+               the ExtensionArray if there are any missing values present
+               in `self`.
+
+        See Also
+        --------
+        factorize : Top-level factorize method that dispatches here.
+
+        Notes
+        -----
+        :meth:`pandas.factorize` offers a `sort` keyword as well.
+
+        Examples
+        --------
+        >>> idx1 = pd.PeriodIndex(["2014-01", "2014-01", "2014-02", "2014-02",
+        ...                       "2014-03", "2014-03"], freq="M")
+        >>> arr, idx = idx1.factorize()
+        >>> arr
+        array([0, 0, 1, 1, 2, 2])
+        >>> idx
+        PeriodIndex(['2014-01', '2014-02', '2014-03'], dtype='period[M]')
+        """
+        # Implementer note: There are two ways to override the behavior of
+        # pandas.factorize
+        # 1. _values_for_factorize and _from_factorize.
+        #    Specify the values passed to pandas' internal factorization
+        #    routines, and how to convert from those values back to the
+        #    original ExtensionArray.
+        # 2. ExtensionArray.factorize.
+        #    Complete control over factorization.
+        arr, na_value = self._values_for_factorize()
+
+        codes, uniques = factorize_array(
+            arr, use_na_sentinel=use_na_sentinel, na_value=na_value
+        )
+
+        uniques_ea = self._from_factorized(uniques, self)
+        return codes, uniques_ea
+
+    _extension_array_shared_docs[
+        "repeat"
+    ] = """
+        Repeat elements of a %(klass)s.
+
+        Returns a new %(klass)s where each element of the current %(klass)s
+        is repeated consecutively a given number of times.
+
+        Parameters
+        ----------
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            %(klass)s.
+        axis : None
+            Must be ``None``. Has no effect but is accepted for compatibility
+            with numpy.
+
+        Returns
+        -------
+        %(klass)s
+            Newly created %(klass)s with repeated elements.
+
+        See Also
+        --------
+        Series.repeat : Equivalent function for Series.
+        Index.repeat : Equivalent function for Index.
+        numpy.repeat : Similar method for :class:`numpy.ndarray`.
+        ExtensionArray.take : Take arbitrary positions.
+
+        Examples
+        --------
+        >>> cat = pd.Categorical(['a', 'b', 'c'])
+        >>> cat
+        ['a', 'b', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> cat.repeat(2)
+        ['a', 'a', 'b', 'b', 'c', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> cat.repeat([1, 2, 3])
+        ['a', 'b', 'b', 'c', 'c', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        """
+
+    @Substitution(klass="ExtensionArray")
+    @Appender(_extension_array_shared_docs["repeat"])
+    def repeat(self, repeats: int | Sequence[int], axis: AxisInt | None = None) -> Self:
+        nv.validate_repeat((), {"axis": axis})
+        ind = np.arange(len(self)).repeat(repeats)
+        return self.take(ind)
+
+    # ------------------------------------------------------------------------
+    # Indexing methods
+    # ------------------------------------------------------------------------
+
+    def take(
+        self,
+        indices: TakeIndexer,
+        *,
+        allow_fill: bool = False,
+        fill_value: Any = None,
+    ) -> Self:
+        """
+        Take elements from an array.
+
+        Parameters
+        ----------
+        indices : sequence of int or one-dimensional np.ndarray of int
+            Indices to be taken.
+        allow_fill : bool, default False
+            How to handle negative values in `indices`.
+
+            * False: negative values in `indices` indicate positional indices
+              from the right (the default). This is similar to
+              :func:`numpy.take`.
+
+            * True: negative values in `indices` indicate
+              missing values. These values are set to `fill_value`. Any other
+              other negative values raise a ``ValueError``.
+
+        fill_value : any, optional
+            Fill value to use for NA-indices when `allow_fill` is True.
+            This may be ``None``, in which case the default NA value for
+            the type, ``self.dtype.na_value``, is used.
+
+            For many ExtensionArrays, there will be two representations of
+            `fill_value`: a user-facing "boxed" scalar, and a low-level
+            physical NA value. `fill_value` should be the user-facing version,
+            and the implementation should handle translating that to the
+            physical version for processing the take if necessary.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Raises
+        ------
+        IndexError
+            When the indices are out of bounds for the array.
+        ValueError
+            When `indices` contains negative values other than ``-1``
+            and `allow_fill` is True.
+
+        See Also
+        --------
+        numpy.take : Take elements from an array along an axis.
+        api.extensions.take : Take elements from an array.
+
+        Notes
+        -----
+        ExtensionArray.take is called by ``Series.__getitem__``, ``.loc``,
+        ``iloc``, when `indices` is a sequence of values. Additionally,
+        it's called by :meth:`Series.reindex`, or any other method
+        that causes realignment, with a `fill_value`.
+
+        Examples
+        --------
+        Here's an example implementation, which relies on casting the
+        extension array to object dtype. This uses the helper method
+        :func:`pandas.api.extensions.take`.
+
+        .. code-block:: python
+
+           def take(self, indices, allow_fill=False, fill_value=None):
+               from pandas.core.algorithms import take
+
+               # If the ExtensionArray is backed by an ndarray, then
+               # just pass that here instead of coercing to object.
+               data = self.astype(object)
+
+               if allow_fill and fill_value is None:
+                   fill_value = self.dtype.na_value
+
+               # fill value should always be translated from the scalar
+               # type for the array, to the physical storage type for
+               # the data, before passing to take.
+
+               result = take(data, indices, fill_value=fill_value,
+                             allow_fill=allow_fill)
+               return self._from_sequence(result, dtype=self.dtype)
+        """
+        # Implementer note: The `fill_value` parameter should be a user-facing
+        # value, an instance of self.dtype.type. When passed `fill_value=None`,
+        # the default of `self.dtype.na_value` should be used.
+        # This may differ from the physical storage type your ExtensionArray
+        # uses. In this case, your implementation is responsible for casting
+        # the user-facing type to the storage type, before using
+        # pandas.api.extensions.take
+        raise AbstractMethodError(self)
+
+    def copy(self) -> Self:
+        """
+        Return a copy of the array.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr2 = arr.copy()
+        >>> arr[0] = 2
+        >>> arr2
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        raise AbstractMethodError(self)
+
+    def view(self, dtype: Dtype | None = None) -> ArrayLike:
+        """
+        Return a view on the array.
+
+        Parameters
+        ----------
+        dtype : str, np.dtype, or ExtensionDtype, optional
+            Default None.
+
+        Returns
+        -------
+        ExtensionArray or np.ndarray
+            A view on the :class:`ExtensionArray`'s data.
+
+        Examples
+        --------
+        This gives view on the underlying data of an ``ExtensionArray`` and is not a
+        copy. Modifications on either the view or the original ``ExtensionArray``
+        will be reflectd on the underlying data:
+
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr2 = arr.view()
+        >>> arr[0] = 2
+        >>> arr2
+        
+        [2, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        # NB:
+        # - This must return a *new* object referencing the same data, not self.
+        # - The only case that *must* be implemented is with dtype=None,
+        #   giving a view with the same dtype as self.
+        if dtype is not None:
+            raise NotImplementedError(dtype)
+        return self[:]
+
+    # ------------------------------------------------------------------------
+    # Printing
+    # ------------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        if self.ndim > 1:
+            return self._repr_2d()
+
+        from pandas.io.formats.printing import format_object_summary
+
+        # the short repr has no trailing newline, while the truncated
+        # repr does. So we include a newline in our template, and strip
+        # any trailing newlines from format_object_summary
+        data = format_object_summary(
+            self, self._formatter(), indent_for_name=False
+        ).rstrip(", \n")
+        class_name = f"<{type(self).__name__}>\n"
+        footer = self._get_repr_footer()
+        return f"{class_name}{data}\n{footer}"
+
+    def _get_repr_footer(self) -> str:
+        # GH#24278
+        if self.ndim > 1:
+            return f"Shape: {self.shape}, dtype: {self.dtype}"
+        return f"Length: {len(self)}, dtype: {self.dtype}"
+
+    def _repr_2d(self) -> str:
+        from pandas.io.formats.printing import format_object_summary
+
+        # the short repr has no trailing newline, while the truncated
+        # repr does. So we include a newline in our template, and strip
+        # any trailing newlines from format_object_summary
+        lines = [
+            format_object_summary(x, self._formatter(), indent_for_name=False).rstrip(
+                ", \n"
+            )
+            for x in self
+        ]
+        data = ",\n".join(lines)
+        class_name = f"<{type(self).__name__}>"
+        footer = self._get_repr_footer()
+        return f"{class_name}\n[\n{data}\n]\n{footer}"
+
+    def _formatter(self, boxed: bool = False) -> Callable[[Any], str | None]:
+        """
+        Formatting function for scalar values.
+
+        This is used in the default '__repr__'. The returned formatting
+        function receives instances of your scalar type.
+
+        Parameters
+        ----------
+        boxed : bool, default False
+            An indicated for whether or not your array is being printed
+            within a Series, DataFrame, or Index (True), or just by
+            itself (False). This may be useful if you want scalar values
+            to appear differently within a Series versus on its own (e.g.
+            quoted or not).
+
+        Returns
+        -------
+        Callable[[Any], str]
+            A callable that gets instances of the scalar type and
+            returns a string. By default, :func:`repr` is used
+            when ``boxed=False`` and :func:`str` is used when
+            ``boxed=True``.
+
+        Examples
+        --------
+        >>> class MyExtensionArray(pd.arrays.NumpyExtensionArray):
+        ...     def _formatter(self, boxed=False):
+        ...         return lambda x: '*' + str(x) + '*' if boxed else repr(x) + '*'
+        >>> MyExtensionArray(np.array([1, 2, 3, 4]))
+        
+        [1*, 2*, 3*, 4*]
+        Length: 4, dtype: int64
+        """
+        if boxed:
+            return str
+        return repr
+
+    # ------------------------------------------------------------------------
+    # Reshaping
+    # ------------------------------------------------------------------------
+
+    def transpose(self, *axes: int) -> ExtensionArray:
+        """
+        Return a transposed view on this array.
+
+        Because ExtensionArrays are always 1D, this is a no-op.  It is included
+        for compatibility with np.ndarray.
+
+        Returns
+        -------
+        ExtensionArray
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3]).transpose()
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        return self[:]
+
+    @property
+    def T(self) -> ExtensionArray:
+        return self.transpose()
+
+    def ravel(self, order: Literal["C", "F", "A", "K"] | None = "C") -> ExtensionArray:
+        """
+        Return a flattened view on this array.
+
+        Parameters
+        ----------
+        order : {None, 'C', 'F', 'A', 'K'}, default 'C'
+
+        Returns
+        -------
+        ExtensionArray
+
+        Notes
+        -----
+        - Because ExtensionArrays are 1D-only, this is a no-op.
+        - The "order" argument is ignored, is for compatibility with NumPy.
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3]).ravel()
+        
+        [1, 2, 3]
+        Length: 3, dtype: Int64
+        """
+        return self
+
+    @classmethod
+    def _concat_same_type(cls, to_concat: Sequence[Self]) -> Self:
+        """
+        Concatenate multiple array of this dtype.
+
+        Parameters
+        ----------
+        to_concat : sequence of this type
+
+        Returns
+        -------
+        ExtensionArray
+
+        Examples
+        --------
+        >>> arr1 = pd.array([1, 2, 3])
+        >>> arr2 = pd.array([4, 5, 6])
+        >>> pd.arrays.IntegerArray._concat_same_type([arr1, arr2])
+        
+        [1, 2, 3, 4, 5, 6]
+        Length: 6, dtype: Int64
+        """
+        # Implementer note: this method will only be called with a sequence of
+        # ExtensionArrays of this class and with the same dtype as self. This
+        # should allow "easy" concatenation (no upcasting needed), and result
+        # in a new ExtensionArray of the same dtype.
+        # Note: this strict behaviour is only guaranteed starting with pandas 1.1
+        raise AbstractMethodError(cls)
+
+    # The _can_hold_na attribute is set to True so that pandas internals
+    # will use the ExtensionDtype.na_value as the NA value in operations
+    # such as take(), reindex(), shift(), etc.  In addition, those results
+    # will then be of the ExtensionArray subclass rather than an array
+    # of objects
+    @cache_readonly
+    def _can_hold_na(self) -> bool:
+        return self.dtype._can_hold_na
+
+    def _accumulate(
+        self, name: str, *, skipna: bool = True, **kwargs
+    ) -> ExtensionArray:
+        """
+        Return an ExtensionArray performing an accumulation operation.
+
+        The underlying data type might change.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            - cummin
+            - cummax
+            - cumsum
+            - cumprod
+        skipna : bool, default True
+            If True, skip NA values.
+        **kwargs
+            Additional keyword arguments passed to the accumulation function.
+            Currently, there is no supported kwarg.
+
+        Returns
+        -------
+        array
+
+        Raises
+        ------
+        NotImplementedError : subclass does not define accumulations
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr._accumulate(name='cumsum')
+        
+        [1, 3, 6]
+        Length: 3, dtype: Int64
+        """
+        raise NotImplementedError(f"cannot perform {name} with type {self.dtype}")
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        """
+        Return a scalar result of performing the reduction operation.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            { any, all, min, max, sum, mean, median, prod,
+            std, var, sem, kurt, skew }.
+        skipna : bool, default True
+            If True, skip NaN values.
+        keepdims : bool, default False
+            If False, a scalar is returned.
+            If True, the result has dimension with size one along the reduced axis.
+
+            .. versionadded:: 2.1
+
+               This parameter is not required in the _reduce signature to keep backward
+               compatibility, but will become required in the future. If the parameter
+               is not found in the method signature, a FutureWarning will be emitted.
+        **kwargs
+            Additional keyword arguments passed to the reduction function.
+            Currently, `ddof` is the only supported kwarg.
+
+        Returns
+        -------
+        scalar
+
+        Raises
+        ------
+        TypeError : subclass does not define reductions
+
+        Examples
+        --------
+        >>> pd.array([1, 2, 3])._reduce("min")
+        1
+        """
+        meth = getattr(self, name, None)
+        if meth is None:
+            raise TypeError(
+                f"'{type(self).__name__}' with dtype {self.dtype} "
+                f"does not support reduction '{name}'"
+            )
+        result = meth(skipna=skipna, **kwargs)
+        if keepdims:
+            result = np.array([result])
+
+        return result
+
+    # https://github.com/python/typeshed/issues/2148#issuecomment-520783318
+    # Incompatible types in assignment (expression has type "None", base class
+    # "object" defined the type as "Callable[[object], int]")
+    __hash__: ClassVar[None]  # type: ignore[assignment]
+
+    # ------------------------------------------------------------------------
+    # Non-Optimized Default Methods; in the case of the private methods here,
+    #  these are not guaranteed to be stable across pandas versions.
+
+    def _values_for_json(self) -> np.ndarray:
+        """
+        Specify how to render our entries in to_json.
+
+        Notes
+        -----
+        The dtype on the returned ndarray is not restricted, but for non-native
+        types that are not specifically handled in objToJSON.c, to_json is
+        liable to raise. In these cases, it may be safer to return an ndarray
+        of strings.
+        """
+        return np.asarray(self)
+
+    def _hash_pandas_object(
+        self, *, encoding: str, hash_key: str, categorize: bool
+    ) -> npt.NDArray[np.uint64]:
+        """
+        Hook for hash_pandas_object.
+
+        Default is to use the values returned by _values_for_factorize.
+
+        Parameters
+        ----------
+        encoding : str
+            Encoding for data & key when strings.
+        hash_key : str
+            Hash_key for string key to encode.
+        categorize : bool
+            Whether to first categorize object arrays before hashing. This is more
+            efficient when the array contains duplicate values.
+
+        Returns
+        -------
+        np.ndarray[uint64]
+
+        Examples
+        --------
+        >>> pd.array([1, 2])._hash_pandas_object(encoding='utf-8',
+        ...                                      hash_key="1000000000000000",
+        ...                                      categorize=False
+        ...                                      )
+        array([ 6238072747940578789, 15839785061582574730], dtype=uint64)
+        """
+        from pandas.core.util.hashing import hash_array
+
+        values, _ = self._values_for_factorize()
+        return hash_array(
+            values, encoding=encoding, hash_key=hash_key, categorize=categorize
+        )
+
+    def _explode(self) -> tuple[Self, npt.NDArray[np.uint64]]:
+        """
+        Transform each element of list-like to a row.
+
+        For arrays that do not contain list-like elements the default
+        implementation of this method just returns a copy and an array
+        of ones (unchanged index).
+
+        Returns
+        -------
+        ExtensionArray
+            Array with the exploded values.
+        np.ndarray[uint64]
+            The original lengths of each list-like for determining the
+            resulting index.
+
+        See Also
+        --------
+        Series.explode : The method on the ``Series`` object that this
+            extension array method is meant to support.
+
+        Examples
+        --------
+        >>> import pyarrow as pa
+        >>> a = pd.array([[1, 2, 3], [4], [5, 6]],
+        ...              dtype=pd.ArrowDtype(pa.list_(pa.int64())))
+        >>> a._explode()
+        (
+        [1, 2, 3, 4, 5, 6]
+        Length: 6, dtype: int64[pyarrow], array([3, 1, 2], dtype=int32))
+        """
+        values = self.copy()
+        counts = np.ones(shape=(len(self),), dtype=np.uint64)
+        return values, counts
+
+    def tolist(self) -> list:
+        """
+        Return a list of the values.
+
+        These are each a scalar type, which is a Python scalar
+        (for str, int, float) or a pandas scalar
+        (for Timestamp/Timedelta/Interval/Period)
+
+        Returns
+        -------
+        list
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.tolist()
+        [1, 2, 3]
+        """
+        if self.ndim > 1:
+            return [x.tolist() for x in self]
+        return list(self)
+
+    def delete(self, loc: PositionalIndexer) -> Self:
+        indexer = np.delete(np.arange(len(self)), loc)
+        return self.take(indexer)
+
+    def insert(self, loc: int, item) -> Self:
+        """
+        Insert an item at the given position.
+
+        Parameters
+        ----------
+        loc : int
+        item : scalar-like
+
+        Returns
+        -------
+        same type as self
+
+        Notes
+        -----
+        This method should be both type and dtype-preserving.  If the item
+        cannot be held in an array of this type/dtype, either ValueError or
+        TypeError should be raised.
+
+        The default implementation relies on _from_sequence to raise on invalid
+        items.
+
+        Examples
+        --------
+        >>> arr = pd.array([1, 2, 3])
+        >>> arr.insert(2, -1)
+        
+        [1, 2, -1, 3]
+        Length: 4, dtype: Int64
+        """
+        loc = validate_insert_loc(loc, len(self))
+
+        item_arr = type(self)._from_sequence([item], dtype=self.dtype)
+
+        return type(self)._concat_same_type([self[:loc], item_arr, self[loc:]])
+
+    def _putmask(self, mask: npt.NDArray[np.bool_], value) -> None:
+        """
+        Analogue to np.putmask(self, mask, value)
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool]
+        value : scalar or listlike
+            If listlike, must be arraylike with same length as self.
+
+        Returns
+        -------
+        None
+
+        Notes
+        -----
+        Unlike np.putmask, we do not repeat listlike values with mismatched length.
+        'value' should either be a scalar or an arraylike with the same length
+        as self.
+        """
+        if is_list_like(value):
+            val = value[mask]
+        else:
+            val = value
+
+        self[mask] = val
+
+    def _where(self, mask: npt.NDArray[np.bool_], value) -> Self:
+        """
+        Analogue to np.where(mask, self, value)
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool]
+        value : scalar or listlike
+
+        Returns
+        -------
+        same type as self
+        """
+        result = self.copy()
+
+        if is_list_like(value):
+            val = value[~mask]
+        else:
+            val = value
+
+        result[~mask] = val
+        return result
+
+    # TODO(3.0): this can be removed once GH#33302 deprecation is enforced
+    def _fill_mask_inplace(
+        self, method: str, limit: int | None, mask: npt.NDArray[np.bool_]
+    ) -> None:
+        """
+        Replace values in locations specified by 'mask' using pad or backfill.
+
+        See also
+        --------
+        ExtensionArray.fillna
+        """
+        func = missing.get_fill_func(method)
+        npvalues = self.astype(object)
+        # NB: if we don't copy mask here, it may be altered inplace, which
+        #  would mess up the `self[mask] = ...` below.
+        func(npvalues, limit=limit, mask=mask.copy())
+        new_values = self._from_sequence(npvalues, dtype=self.dtype)
+        self[mask] = new_values[mask]
+
+    def _rank(
+        self,
+        *,
+        axis: AxisInt = 0,
+        method: str = "average",
+        na_option: str = "keep",
+        ascending: bool = True,
+        pct: bool = False,
+    ):
+        """
+        See Series.rank.__doc__.
+        """
+        if axis != 0:
+            raise NotImplementedError
+
+        return rank(
+            self._values_for_argsort(),
+            axis=axis,
+            method=method,
+            na_option=na_option,
+            ascending=ascending,
+            pct=pct,
+        )
+
+    @classmethod
+    def _empty(cls, shape: Shape, dtype: ExtensionDtype):
+        """
+        Create an ExtensionArray with the given shape and dtype.
+
+        See also
+        --------
+        ExtensionDtype.empty
+            ExtensionDtype.empty is the 'official' public version of this API.
+        """
+        # Implementer note: while ExtensionDtype.empty is the public way to
+        # call this method, it is still required to implement this `_empty`
+        # method as well (it is called internally in pandas)
+        obj = cls._from_sequence([], dtype=dtype)
+
+        taker = np.broadcast_to(np.intp(-1), shape)
+        result = obj.take(taker, allow_fill=True)
+        if not isinstance(result, cls) or dtype != result.dtype:
+            raise NotImplementedError(
+                f"Default 'empty' implementation is invalid for dtype='{dtype}'"
+            )
+        return result
+
+    def _quantile(self, qs: npt.NDArray[np.float64], interpolation: str) -> Self:
+        """
+        Compute the quantiles of self for each quantile in `qs`.
+
+        Parameters
+        ----------
+        qs : np.ndarray[float64]
+        interpolation: str
+
+        Returns
+        -------
+        same type as self
+        """
+        mask = np.asarray(self.isna())
+        arr = np.asarray(self)
+        fill_value = np.nan
+
+        res_values = quantile_with_mask(arr, mask, fill_value, qs, interpolation)
+        return type(self)._from_sequence(res_values)
+
+    def _mode(self, dropna: bool = True) -> Self:
+        """
+        Returns the mode(s) of the ExtensionArray.
+
+        Always returns `ExtensionArray` even if only one value.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't consider counts of NA values.
+
+        Returns
+        -------
+        same type as self
+            Sorted, if possible.
+        """
+        # error: Incompatible return value type (got "Union[ExtensionArray,
+        # ndarray[Any, Any]]", expected "Self")
+        return mode(self, dropna=dropna)  # type: ignore[return-value]
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        if any(
+            isinstance(other, (ABCSeries, ABCIndex, ABCDataFrame)) for other in inputs
+        ):
+            return NotImplemented
+
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            return arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+
+        if method == "reduce":
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                return result
+
+        return arraylike.default_array_ufunc(self, ufunc, method, *inputs, **kwargs)
+
+    def map(self, mapper, na_action=None):
+        """
+        Map values using an input mapping or function.
+
+        Parameters
+        ----------
+        mapper : function, dict, or Series
+            Mapping correspondence.
+        na_action : {None, 'ignore'}, default None
+            If 'ignore', propagate NA values, without passing them to the
+            mapping correspondence. If 'ignore' is not supported, a
+            ``NotImplementedError`` should be raised.
+
+        Returns
+        -------
+        Union[ndarray, Index, ExtensionArray]
+            The output of the mapping function applied to the array.
+            If the function returns a tuple with more than one element
+            a MultiIndex will be returned.
+        """
+        return map_array(self, mapper, na_action=na_action)
+
+    # ------------------------------------------------------------------------
+    # GroupBy Methods
+
+    def _groupby_op(
+        self,
+        *,
+        how: str,
+        has_dropped_na: bool,
+        min_count: int,
+        ngroups: int,
+        ids: npt.NDArray[np.intp],
+        **kwargs,
+    ) -> ArrayLike:
+        """
+        Dispatch GroupBy reduction or transformation operation.
+
+        This is an *experimental* API to allow ExtensionArray authors to implement
+        reductions and transformations. The API is subject to change.
+
+        Parameters
+        ----------
+        how : {'any', 'all', 'sum', 'prod', 'min', 'max', 'mean', 'median',
+               'median', 'var', 'std', 'sem', 'nth', 'last', 'ohlc',
+               'cumprod', 'cumsum', 'cummin', 'cummax', 'rank'}
+        has_dropped_na : bool
+        min_count : int
+        ngroups : int
+        ids : np.ndarray[np.intp]
+            ids[i] gives the integer label for the group that self[i] belongs to.
+        **kwargs : operation-specific
+            'any', 'all' -> ['skipna']
+            'var', 'std', 'sem' -> ['ddof']
+            'cumprod', 'cumsum', 'cummin', 'cummax' -> ['skipna']
+            'rank' -> ['ties_method', 'ascending', 'na_option', 'pct']
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+        """
+        from pandas.core.arrays.string_ import StringDtype
+        from pandas.core.groupby.ops import WrappedCythonOp
+
+        kind = WrappedCythonOp.get_kind_from_how(how)
+        op = WrappedCythonOp(how=how, kind=kind, has_dropped_na=has_dropped_na)
+
+        initial: Any = 0
+        # GH#43682
+        if isinstance(self.dtype, StringDtype):
+            # StringArray
+            if op.how in [
+                "prod",
+                "mean",
+                "median",
+                "cumsum",
+                "cumprod",
+                "std",
+                "sem",
+                "var",
+                "skew",
+            ]:
+                raise TypeError(
+                    f"dtype '{self.dtype}' does not support operation '{how}'"
+                )
+            if op.how not in ["any", "all"]:
+                # Fail early to avoid conversion to object
+                op._get_cython_function(op.kind, op.how, np.dtype(object), False)
+
+            arr = self
+            if op.how == "sum":
+                initial = ""
+                # https://github.com/pandas-dev/pandas/issues/60229
+                # All NA should result in the empty string.
+                if min_count == 0:
+                    arr = arr.fillna("")
+            npvalues = arr.to_numpy(object, na_value=np.nan)
+        else:
+            raise NotImplementedError(
+                f"function is not implemented for this dtype: {self.dtype}"
+            )
+
+        res_values = op._cython_op_ndim_compat(
+            npvalues,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=ids,
+            mask=None,
+            initial=initial,
+            **kwargs,
+        )
+
+        if op.how in op.cast_blocklist:
+            # i.e. how in ["rank"], since other cast_blocklist methods don't go
+            #  through cython_operation
+            return res_values
+
+        if isinstance(self.dtype, StringDtype):
+            dtype = self.dtype
+            string_array_cls = dtype.construct_array_type()
+            return string_array_cls._from_sequence(res_values, dtype=dtype)
+
+        else:
+            raise NotImplementedError
+
+
+class ExtensionArraySupportsAnyAll(ExtensionArray):
+    def any(self, *, skipna: bool = True) -> bool:
+        raise AbstractMethodError(self)
+
+    def all(self, *, skipna: bool = True) -> bool:
+        raise AbstractMethodError(self)
+
+
+class ExtensionOpsMixin:
+    """
+    A base class for linking the operators to their dunder names.
+
+    .. note::
+
+       You may want to set ``__array_priority__`` if you want your
+       implementation to be called when involved in binary operations
+       with NumPy arrays.
+    """
+
+    @classmethod
+    def _create_arithmetic_method(cls, op):
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _add_arithmetic_ops(cls) -> None:
+        setattr(cls, "__add__", cls._create_arithmetic_method(operator.add))
+        setattr(cls, "__radd__", cls._create_arithmetic_method(roperator.radd))
+        setattr(cls, "__sub__", cls._create_arithmetic_method(operator.sub))
+        setattr(cls, "__rsub__", cls._create_arithmetic_method(roperator.rsub))
+        setattr(cls, "__mul__", cls._create_arithmetic_method(operator.mul))
+        setattr(cls, "__rmul__", cls._create_arithmetic_method(roperator.rmul))
+        setattr(cls, "__pow__", cls._create_arithmetic_method(operator.pow))
+        setattr(cls, "__rpow__", cls._create_arithmetic_method(roperator.rpow))
+        setattr(cls, "__mod__", cls._create_arithmetic_method(operator.mod))
+        setattr(cls, "__rmod__", cls._create_arithmetic_method(roperator.rmod))
+        setattr(cls, "__floordiv__", cls._create_arithmetic_method(operator.floordiv))
+        setattr(
+            cls, "__rfloordiv__", cls._create_arithmetic_method(roperator.rfloordiv)
+        )
+        setattr(cls, "__truediv__", cls._create_arithmetic_method(operator.truediv))
+        setattr(cls, "__rtruediv__", cls._create_arithmetic_method(roperator.rtruediv))
+        setattr(cls, "__divmod__", cls._create_arithmetic_method(divmod))
+        setattr(cls, "__rdivmod__", cls._create_arithmetic_method(roperator.rdivmod))
+
+    @classmethod
+    def _create_comparison_method(cls, op):
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _add_comparison_ops(cls) -> None:
+        setattr(cls, "__eq__", cls._create_comparison_method(operator.eq))
+        setattr(cls, "__ne__", cls._create_comparison_method(operator.ne))
+        setattr(cls, "__lt__", cls._create_comparison_method(operator.lt))
+        setattr(cls, "__gt__", cls._create_comparison_method(operator.gt))
+        setattr(cls, "__le__", cls._create_comparison_method(operator.le))
+        setattr(cls, "__ge__", cls._create_comparison_method(operator.ge))
+
+    @classmethod
+    def _create_logical_method(cls, op):
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _add_logical_ops(cls) -> None:
+        setattr(cls, "__and__", cls._create_logical_method(operator.and_))
+        setattr(cls, "__rand__", cls._create_logical_method(roperator.rand_))
+        setattr(cls, "__or__", cls._create_logical_method(operator.or_))
+        setattr(cls, "__ror__", cls._create_logical_method(roperator.ror_))
+        setattr(cls, "__xor__", cls._create_logical_method(operator.xor))
+        setattr(cls, "__rxor__", cls._create_logical_method(roperator.rxor))
+
+
+class ExtensionScalarOpsMixin(ExtensionOpsMixin):
+    """
+    A mixin for defining ops on an ExtensionArray.
+
+    It is assumed that the underlying scalar objects have the operators
+    already defined.
+
+    Notes
+    -----
+    If you have defined a subclass MyExtensionArray(ExtensionArray), then
+    use MyExtensionArray(ExtensionArray, ExtensionScalarOpsMixin) to
+    get the arithmetic operators.  After the definition of MyExtensionArray,
+    insert the lines
+
+    MyExtensionArray._add_arithmetic_ops()
+    MyExtensionArray._add_comparison_ops()
+
+    to link the operators to your class.
+
+    .. note::
+
+       You may want to set ``__array_priority__`` if you want your
+       implementation to be called when involved in binary operations
+       with NumPy arrays.
+    """
+
+    @classmethod
+    def _create_method(cls, op, coerce_to_dtype: bool = True, result_dtype=None):
+        """
+        A class method that returns a method that will correspond to an
+        operator for an ExtensionArray subclass, by dispatching to the
+        relevant operator defined on the individual elements of the
+        ExtensionArray.
+
+        Parameters
+        ----------
+        op : function
+            An operator that takes arguments op(a, b)
+        coerce_to_dtype : bool, default True
+            boolean indicating whether to attempt to convert
+            the result to the underlying ExtensionArray dtype.
+            If it's not possible to create a new ExtensionArray with the
+            values, an ndarray is returned instead.
+
+        Returns
+        -------
+        Callable[[Any, Any], Union[ndarray, ExtensionArray]]
+            A method that can be bound to a class. When used, the method
+            receives the two arguments, one of which is the instance of
+            this class, and should return an ExtensionArray or an ndarray.
+
+            Returning an ndarray may be necessary when the result of the
+            `op` cannot be stored in the ExtensionArray. The dtype of the
+            ndarray uses NumPy's normal inference rules.
+
+        Examples
+        --------
+        Given an ExtensionArray subclass called MyExtensionArray, use
+
+            __add__ = cls._create_method(operator.add)
+
+        in the class definition of MyExtensionArray to create the operator
+        for addition, that will be based on the operator implementation
+        of the underlying elements of the ExtensionArray
+        """
+
+        def _binop(self, other):
+            def convert_values(param):
+                if isinstance(param, ExtensionArray) or is_list_like(param):
+                    ovalues = param
+                else:  # Assume its an object
+                    ovalues = [param] * len(self)
+                return ovalues
+
+            if isinstance(other, (ABCSeries, ABCIndex, ABCDataFrame)):
+                # rely on pandas to unbox and dispatch to us
+                return NotImplemented
+
+            lvalues = self
+            rvalues = convert_values(other)
+
+            # If the operator is not defined for the underlying objects,
+            # a TypeError should be raised
+            res = [op(a, b) for (a, b) in zip(lvalues, rvalues)]
+
+            def _maybe_convert(arr):
+                if coerce_to_dtype:
+                    # https://github.com/pandas-dev/pandas/issues/22850
+                    # We catch all regular exceptions here, and fall back
+                    # to an ndarray.
+                    res = maybe_cast_pointwise_result(arr, self.dtype, same_dtype=False)
+                    if not isinstance(res, type(self)):
+                        # exception raised in _from_sequence; ensure we have ndarray
+                        res = np.asarray(arr)
+                else:
+                    res = np.asarray(arr, dtype=result_dtype)
+                return res
+
+            if op.__name__ in {"divmod", "rdivmod"}:
+                a, b = zip(*res)
+                return _maybe_convert(a), _maybe_convert(b)
+
+            return _maybe_convert(res)
+
+        op_name = f"__{op.__name__}__"
+        return set_function_name(_binop, op_name, cls)
+
+    @classmethod
+    def _create_arithmetic_method(cls, op):
+        return cls._create_method(op)
+
+    @classmethod
+    def _create_comparison_method(cls, op):
+        return cls._create_method(op, coerce_to_dtype=False, result_dtype=bool)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/boolean.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/boolean.py
new file mode 100644
index 0000000000000000000000000000000000000000..04e6f0a0bcdde9a11550fcec8274e09fe8429430
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/boolean.py
@@ -0,0 +1,407 @@
+from __future__ import annotations
+
+import numbers
+from typing import (
+    TYPE_CHECKING,
+    ClassVar,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.dtypes import register_extension_dtype
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import ops
+from pandas.core.array_algos import masked_accumulations
+from pandas.core.arrays.masked import (
+    BaseMaskedArray,
+    BaseMaskedDtype,
+)
+
+if TYPE_CHECKING:
+    import pyarrow
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        Self,
+        npt,
+        type_t,
+    )
+
+
+@register_extension_dtype
+class BooleanDtype(BaseMaskedDtype):
+    """
+    Extension dtype for boolean data.
+
+    .. warning::
+
+       BooleanDtype is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.BooleanDtype()
+    BooleanDtype
+    """
+
+    name: ClassVar[str] = "boolean"
+
+    # https://github.com/python/mypy/issues/4125
+    # error: Signature of "type" incompatible with supertype "BaseMaskedDtype"
+    @property
+    def type(self) -> type:  # type: ignore[override]
+        return np.bool_
+
+    @property
+    def kind(self) -> str:
+        return "b"
+
+    @property
+    def numpy_dtype(self) -> np.dtype:
+        return np.dtype("bool")
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[BooleanArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        return BooleanArray
+
+    def __repr__(self) -> str:
+        return "BooleanDtype"
+
+    @property
+    def _is_boolean(self) -> bool:
+        return True
+
+    @property
+    def _is_numeric(self) -> bool:
+        return True
+
+    def __from_arrow__(
+        self, array: pyarrow.Array | pyarrow.ChunkedArray
+    ) -> BooleanArray:
+        """
+        Construct BooleanArray from pyarrow Array/ChunkedArray.
+        """
+        import pyarrow
+
+        if array.type != pyarrow.bool_() and not pyarrow.types.is_null(array.type):
+            raise TypeError(f"Expected array of boolean type, got {array.type} instead")
+
+        if isinstance(array, pyarrow.Array):
+            chunks = [array]
+            length = len(array)
+        else:
+            # pyarrow.ChunkedArray
+            chunks = array.chunks
+            length = array.length()
+
+        if pyarrow.types.is_null(array.type):
+            mask = np.ones(length, dtype=bool)
+            # No need to init data, since all null
+            data = np.empty(length, dtype=bool)
+            return BooleanArray(data, mask)
+
+        results = []
+        for arr in chunks:
+            buflist = arr.buffers()
+            data = pyarrow.BooleanArray.from_buffers(
+                arr.type, len(arr), [None, buflist[1]], offset=arr.offset
+            ).to_numpy(zero_copy_only=False)
+            if arr.null_count != 0:
+                mask = pyarrow.BooleanArray.from_buffers(
+                    arr.type, len(arr), [None, buflist[0]], offset=arr.offset
+                ).to_numpy(zero_copy_only=False)
+                mask = ~mask
+            else:
+                mask = np.zeros(len(arr), dtype=bool)
+
+            bool_arr = BooleanArray(data, mask)
+            results.append(bool_arr)
+
+        if not results:
+            return BooleanArray(
+                np.array([], dtype=np.bool_), np.array([], dtype=np.bool_)
+            )
+        else:
+            return BooleanArray._concat_same_type(results)
+
+
+def coerce_to_array(
+    values, mask=None, copy: bool = False
+) -> tuple[np.ndarray, np.ndarray]:
+    """
+    Coerce the input values array to numpy arrays with a mask.
+
+    Parameters
+    ----------
+    values : 1D list-like
+    mask : bool 1D array, optional
+    copy : bool, default False
+        if True, copy the input
+
+    Returns
+    -------
+    tuple of (values, mask)
+    """
+    if isinstance(values, BooleanArray):
+        if mask is not None:
+            raise ValueError("cannot pass mask for BooleanArray input")
+        values, mask = values._data, values._mask
+        if copy:
+            values = values.copy()
+            mask = mask.copy()
+        return values, mask
+
+    mask_values = None
+    if isinstance(values, np.ndarray) and values.dtype == np.bool_:
+        if copy:
+            values = values.copy()
+    elif isinstance(values, np.ndarray) and values.dtype.kind in "iufcb":
+        mask_values = isna(values)
+
+        values_bool = np.zeros(len(values), dtype=bool)
+        values_bool[~mask_values] = values[~mask_values].astype(bool)
+
+        if not np.all(
+            values_bool[~mask_values].astype(values.dtype) == values[~mask_values]
+        ):
+            raise TypeError("Need to pass bool-like values")
+
+        values = values_bool
+    else:
+        values_object = np.asarray(values, dtype=object)
+
+        inferred_dtype = lib.infer_dtype(values_object, skipna=True)
+        integer_like = ("floating", "integer", "mixed-integer-float")
+        if inferred_dtype not in ("boolean", "empty") + integer_like:
+            raise TypeError("Need to pass bool-like values")
+
+        # mypy does not narrow the type of mask_values to npt.NDArray[np.bool_]
+        # within this branch, it assumes it can also be None
+        mask_values = cast("npt.NDArray[np.bool_]", isna(values_object))
+        values = np.zeros(len(values), dtype=bool)
+        values[~mask_values] = values_object[~mask_values].astype(bool)
+
+        # if the values were integer-like, validate it were actually 0/1's
+        if (inferred_dtype in integer_like) and not (
+            np.all(
+                values[~mask_values].astype(float)
+                == values_object[~mask_values].astype(float)
+            )
+        ):
+            raise TypeError("Need to pass bool-like values")
+
+    if mask is None and mask_values is None:
+        mask = np.zeros(values.shape, dtype=bool)
+    elif mask is None:
+        mask = mask_values
+    else:
+        if isinstance(mask, np.ndarray) and mask.dtype == np.bool_:
+            if mask_values is not None:
+                mask = mask | mask_values
+            else:
+                if copy:
+                    mask = mask.copy()
+        else:
+            mask = np.array(mask, dtype=bool)
+            if mask_values is not None:
+                mask = mask | mask_values
+
+    if values.shape != mask.shape:
+        raise ValueError("values.shape and mask.shape must match")
+
+    return values, mask
+
+
+class BooleanArray(BaseMaskedArray):
+    """
+    Array of boolean (True/False) data with missing values.
+
+    This is a pandas Extension array for boolean data, under the hood
+    represented by 2 numpy arrays: a boolean array with the data and
+    a boolean array with the mask (True indicating missing).
+
+    BooleanArray implements Kleene logic (sometimes called three-value
+    logic) for logical operations. See :ref:`boolean.kleene` for more.
+
+    To construct an BooleanArray from generic array-like input, use
+    :func:`pandas.array` specifying ``dtype="boolean"`` (see examples
+    below).
+
+    .. warning::
+
+       BooleanArray is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Parameters
+    ----------
+    values : numpy.ndarray
+        A 1-d boolean-dtype array with the data.
+    mask : numpy.ndarray
+        A 1-d boolean-dtype array indicating missing values (True
+        indicates missing).
+    copy : bool, default False
+        Whether to copy the `values` and `mask` arrays.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Returns
+    -------
+    BooleanArray
+
+    Examples
+    --------
+    Create an BooleanArray with :func:`pandas.array`:
+
+    >>> pd.array([True, False, None], dtype="boolean")
+    
+    [True, False, ]
+    Length: 3, dtype: boolean
+    """
+
+    # The value used to fill '_data' to avoid upcasting
+    _internal_fill_value = False
+    # Fill values used for any/all
+    # Incompatible types in assignment (expression has type "bool", base class
+    # "BaseMaskedArray" defined the type as "")
+    _truthy_value = True  # type: ignore[assignment]
+    _falsey_value = False  # type: ignore[assignment]
+    _TRUE_VALUES = {"True", "TRUE", "true", "1", "1.0"}
+    _FALSE_VALUES = {"False", "FALSE", "false", "0", "0.0"}
+
+    @classmethod
+    def _simple_new(cls, values: np.ndarray, mask: npt.NDArray[np.bool_]) -> Self:
+        result = super()._simple_new(values, mask)
+        result._dtype = BooleanDtype()
+        return result
+
+    def __init__(
+        self, values: np.ndarray, mask: np.ndarray, copy: bool = False
+    ) -> None:
+        if not (isinstance(values, np.ndarray) and values.dtype == np.bool_):
+            raise TypeError(
+                "values should be boolean numpy array. Use "
+                "the 'pd.array' function instead"
+            )
+        self._dtype = BooleanDtype()
+        super().__init__(values, mask, copy=copy)
+
+    @property
+    def dtype(self) -> BooleanDtype:
+        return self._dtype
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls,
+        strings: list[str],
+        *,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        true_values: list[str] | None = None,
+        false_values: list[str] | None = None,
+    ) -> BooleanArray:
+        true_values_union = cls._TRUE_VALUES.union(true_values or [])
+        false_values_union = cls._FALSE_VALUES.union(false_values or [])
+
+        def map_string(s) -> bool:
+            if s in true_values_union:
+                return True
+            elif s in false_values_union:
+                return False
+            else:
+                raise ValueError(f"{s} cannot be cast to bool")
+
+        scalars = np.array(strings, dtype=object)
+        mask = isna(scalars)
+        scalars[~mask] = list(map(map_string, scalars[~mask]))
+        return cls._from_sequence(scalars, dtype=dtype, copy=copy)
+
+    _HANDLED_TYPES = (np.ndarray, numbers.Number, bool, np.bool_)
+
+    @classmethod
+    def _coerce_to_array(
+        cls, value, *, dtype: DtypeObj, copy: bool = False
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if dtype:
+            assert dtype == "boolean"
+        return coerce_to_array(value, copy=copy)
+
+    def _logical_method(self, other, op):
+        assert op.__name__ in {"or_", "ror_", "and_", "rand_", "xor", "rxor"}
+        other_is_scalar = lib.is_scalar(other)
+        mask = None
+
+        if isinstance(other, BooleanArray):
+            other, mask = other._data, other._mask
+        elif is_list_like(other):
+            other = np.asarray(other, dtype="bool")
+            if other.ndim > 1:
+                raise NotImplementedError("can only perform ops with 1-d structures")
+            other, mask = coerce_to_array(other, copy=False)
+        elif isinstance(other, np.bool_):
+            other = other.item()
+
+        if other_is_scalar and other is not libmissing.NA and not lib.is_bool(other):
+            raise TypeError(
+                "'other' should be pandas.NA or a bool. "
+                f"Got {type(other).__name__} instead."
+            )
+
+        if not other_is_scalar and len(self) != len(other):
+            raise ValueError("Lengths must match")
+
+        if op.__name__ in {"or_", "ror_"}:
+            result, mask = ops.kleene_or(self._data, other, self._mask, mask)
+        elif op.__name__ in {"and_", "rand_"}:
+            result, mask = ops.kleene_and(self._data, other, self._mask, mask)
+        else:
+            # i.e. xor, rxor
+            result, mask = ops.kleene_xor(self._data, other, self._mask, mask)
+
+        # i.e. BooleanArray
+        return self._maybe_mask_result(result, mask)
+
+    def _accumulate(
+        self, name: str, *, skipna: bool = True, **kwargs
+    ) -> BaseMaskedArray:
+        data = self._data
+        mask = self._mask
+        if name in ("cummin", "cummax"):
+            op = getattr(masked_accumulations, name)
+            data, mask = op(data, mask, skipna=skipna, **kwargs)
+            return self._simple_new(data, mask)
+        else:
+            from pandas.core.arrays import IntegerArray
+
+            return IntegerArray(data.astype(int), mask)._accumulate(
+                name, skipna=skipna, **kwargs
+            )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/categorical.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/categorical.py
new file mode 100644
index 0000000000000000000000000000000000000000..8bee4740b39510bf049aadc348d9e911915fe239
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/categorical.py
@@ -0,0 +1,3111 @@
+from __future__ import annotations
+
+from csv import QUOTE_NONNUMERIC
+from functools import partial
+import operator
+from shutil import get_terminal_size
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs import (
+    NaT,
+    algos as libalgos,
+    lib,
+)
+from pandas._libs.arrays import NDArrayBacked
+from pandas.compat.numpy import function as nv
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_bool_kwarg
+
+from pandas.core.dtypes.cast import (
+    coerce_indexer_dtype,
+    find_common_type,
+)
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    ensure_platform_int,
+    is_any_real_numeric_dtype,
+    is_bool_dtype,
+    is_dict_like,
+    is_hashable,
+    is_integer_dtype,
+    is_list_like,
+    is_scalar,
+    needs_i8_conversion,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    CategoricalDtypeType,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+)
+
+from pandas.core import (
+    algorithms,
+    arraylike,
+    ops,
+)
+from pandas.core.accessor import (
+    PandasDelegate,
+    delegate_names,
+)
+from pandas.core.algorithms import (
+    factorize,
+    take_nd,
+)
+from pandas.core.arrays._mixins import (
+    NDArrayBackedExtensionArray,
+    ravel_compat,
+)
+from pandas.core.base import (
+    ExtensionArray,
+    NoNewAttributesMixin,
+    PandasObject,
+)
+import pandas.core.common as com
+from pandas.core.construction import (
+    extract_array,
+    sanitize_array,
+)
+from pandas.core.ops.common import unpack_zerodim_and_defer
+from pandas.core.sorting import nargsort
+from pandas.core.strings.object_array import ObjectStringArrayMixin
+
+from pandas.io.formats import console
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        AstypeArg,
+        AxisInt,
+        Dtype,
+        DtypeObj,
+        NpDtype,
+        Ordered,
+        Self,
+        Shape,
+        SortKind,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+
+
+def _cat_compare_op(op):
+    opname = f"__{op.__name__}__"
+    fill_value = op is operator.ne
+
+    @unpack_zerodim_and_defer(opname)
+    def func(self, other):
+        hashable = is_hashable(other)
+        if is_list_like(other) and len(other) != len(self) and not hashable:
+            # in hashable case we may have a tuple that is itself a category
+            raise ValueError("Lengths must match.")
+
+        if not self.ordered:
+            if opname in ["__lt__", "__gt__", "__le__", "__ge__"]:
+                raise TypeError(
+                    "Unordered Categoricals can only compare equality or not"
+                )
+        if isinstance(other, Categorical):
+            # Two Categoricals can only be compared if the categories are
+            # the same (maybe up to ordering, depending on ordered)
+
+            msg = "Categoricals can only be compared if 'categories' are the same."
+            if not self._categories_match_up_to_permutation(other):
+                raise TypeError(msg)
+
+            if not self.ordered and not self.categories.equals(other.categories):
+                # both unordered and different order
+                other_codes = recode_for_categories(
+                    other.codes, other.categories, self.categories, copy=False
+                )
+            else:
+                other_codes = other._codes
+
+            ret = op(self._codes, other_codes)
+            mask = (self._codes == -1) | (other_codes == -1)
+            if mask.any():
+                ret[mask] = fill_value
+            return ret
+
+        if hashable:
+            if other in self.categories:
+                i = self._unbox_scalar(other)
+                ret = op(self._codes, i)
+
+                if opname not in {"__eq__", "__ge__", "__gt__"}:
+                    # GH#29820 performance trick; get_loc will always give i>=0,
+                    #  so in the cases (__ne__, __le__, __lt__) the setting
+                    #  here is a no-op, so can be skipped.
+                    mask = self._codes == -1
+                    ret[mask] = fill_value
+                return ret
+            else:
+                return ops.invalid_comparison(self, other, op)
+        else:
+            # allow categorical vs object dtype array comparisons for equality
+            # these are only positional comparisons
+            if opname not in ["__eq__", "__ne__"]:
+                raise TypeError(
+                    f"Cannot compare a Categorical for op {opname} with "
+                    f"type {type(other)}.\nIf you want to compare values, "
+                    "use 'np.asarray(cat)  other'."
+                )
+
+            if isinstance(other, ExtensionArray) and needs_i8_conversion(other.dtype):
+                # We would return NotImplemented here, but that messes up
+                #  ExtensionIndex's wrapped methods
+                return op(other, self)
+            return getattr(np.array(self), opname)(np.array(other))
+
+    func.__name__ = opname
+
+    return func
+
+
+def contains(cat, key, container) -> bool:
+    """
+    Helper for membership check for ``key`` in ``cat``.
+
+    This is a helper method for :method:`__contains__`
+    and :class:`CategoricalIndex.__contains__`.
+
+    Returns True if ``key`` is in ``cat.categories`` and the
+    location of ``key`` in ``categories`` is in ``container``.
+
+    Parameters
+    ----------
+    cat : :class:`Categorical`or :class:`categoricalIndex`
+    key : a hashable object
+        The key to check membership for.
+    container : Container (e.g. list-like or mapping)
+        The container to check for membership in.
+
+    Returns
+    -------
+    is_in : bool
+        True if ``key`` is in ``self.categories`` and location of
+        ``key`` in ``categories`` is in ``container``, else False.
+
+    Notes
+    -----
+    This method does not check for NaN values. Do that separately
+    before calling this method.
+    """
+    hash(key)
+
+    # get location of key in categories.
+    # If a KeyError, the key isn't in categories, so logically
+    #  can't be in container either.
+    try:
+        loc = cat.categories.get_loc(key)
+    except (KeyError, TypeError):
+        return False
+
+    # loc is the location of key in categories, but also the *value*
+    # for key in container. So, `key` may be in categories,
+    # but still not in `container`. Example ('b' in categories,
+    # but not in values):
+    # 'b' in Categorical(['a'], categories=['a', 'b'])  # False
+    if is_scalar(loc):
+        return loc in container
+    else:
+        # if categories is an IntervalIndex, loc is an array.
+        return any(loc_ in container for loc_ in loc)
+
+
+class Categorical(NDArrayBackedExtensionArray, PandasObject, ObjectStringArrayMixin):
+    """
+    Represent a categorical variable in classic R / S-plus fashion.
+
+    `Categoricals` can only take on a limited, and usually fixed, number
+    of possible values (`categories`). In contrast to statistical categorical
+    variables, a `Categorical` might have an order, but numerical operations
+    (additions, divisions, ...) are not possible.
+
+    All values of the `Categorical` are either in `categories` or `np.nan`.
+    Assigning values outside of `categories` will raise a `ValueError`. Order
+    is defined by the order of the `categories`, not lexical order of the
+    values.
+
+    Parameters
+    ----------
+    values : list-like
+        The values of the categorical. If categories are given, values not in
+        categories will be replaced with NaN.
+    categories : Index-like (unique), optional
+        The unique categories for this categorical. If not given, the
+        categories are assumed to be the unique values of `values` (sorted, if
+        possible, otherwise in the order in which they appear).
+    ordered : bool, default False
+        Whether or not this categorical is treated as a ordered categorical.
+        If True, the resulting categorical will be ordered.
+        An ordered categorical respects, when sorted, the order of its
+        `categories` attribute (which in turn is the `categories` argument, if
+        provided).
+    dtype : CategoricalDtype
+        An instance of ``CategoricalDtype`` to use for this categorical.
+
+    Attributes
+    ----------
+    categories : Index
+        The categories of this categorical.
+    codes : ndarray
+        The codes (integer positions, which point to the categories) of this
+        categorical, read only.
+    ordered : bool
+        Whether or not this Categorical is ordered.
+    dtype : CategoricalDtype
+        The instance of ``CategoricalDtype`` storing the ``categories``
+        and ``ordered``.
+
+    Methods
+    -------
+    from_codes
+    __array__
+
+    Raises
+    ------
+    ValueError
+        If the categories do not validate.
+    TypeError
+        If an explicit ``ordered=True`` is given but no `categories` and the
+        `values` are not sortable.
+
+    See Also
+    --------
+    CategoricalDtype : Type for categorical data.
+    CategoricalIndex : An Index with an underlying ``Categorical``.
+
+    Notes
+    -----
+    See the `user guide
+    `__
+    for more.
+
+    Examples
+    --------
+    >>> pd.Categorical([1, 2, 3, 1, 2, 3])
+    [1, 2, 3, 1, 2, 3]
+    Categories (3, int64): [1, 2, 3]
+
+    >>> pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'])
+    ['a', 'b', 'c', 'a', 'b', 'c']
+    Categories (3, object): ['a', 'b', 'c']
+
+    Missing values are not included as a category.
+
+    >>> c = pd.Categorical([1, 2, 3, 1, 2, 3, np.nan])
+    >>> c
+    [1, 2, 3, 1, 2, 3, NaN]
+    Categories (3, int64): [1, 2, 3]
+
+    However, their presence is indicated in the `codes` attribute
+    by code `-1`.
+
+    >>> c.codes
+    array([ 0,  1,  2,  0,  1,  2, -1], dtype=int8)
+
+    Ordered `Categoricals` can be sorted according to the custom order
+    of the categories and can have a min and max value.
+
+    >>> c = pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c'], ordered=True,
+    ...                    categories=['c', 'b', 'a'])
+    >>> c
+    ['a', 'b', 'c', 'a', 'b', 'c']
+    Categories (3, object): ['c' < 'b' < 'a']
+    >>> c.min()
+    'c'
+    """
+
+    # For comparisons, so that numpy uses our implementation if the compare
+    # ops, which raise
+    __array_priority__ = 1000
+    # tolist is not actually deprecated, just suppressed in the __dir__
+    _hidden_attrs = PandasObject._hidden_attrs | frozenset(["tolist"])
+    _typ = "categorical"
+
+    _dtype: CategoricalDtype
+
+    @classmethod
+    # error: Argument 2 of "_simple_new" is incompatible with supertype
+    # "NDArrayBacked"; supertype defines the argument type as
+    # "Union[dtype[Any], ExtensionDtype]"
+    def _simple_new(  # type: ignore[override]
+        cls, codes: np.ndarray, dtype: CategoricalDtype
+    ) -> Self:
+        # NB: This is not _quite_ as simple as the "usual" _simple_new
+        codes = coerce_indexer_dtype(codes, dtype.categories)
+        dtype = CategoricalDtype(ordered=False).update_dtype(dtype)
+        return super()._simple_new(codes, dtype)
+
+    def __init__(
+        self,
+        values,
+        categories=None,
+        ordered=None,
+        dtype: Dtype | None = None,
+        fastpath: bool | lib.NoDefault = lib.no_default,
+        copy: bool = True,
+    ) -> None:
+        if fastpath is not lib.no_default:
+            # GH#20110
+            warnings.warn(
+                "The 'fastpath' keyword in Categorical is deprecated and will "
+                "be removed in a future version. Use Categorical.from_codes instead",
+                DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            fastpath = False
+
+        dtype = CategoricalDtype._from_values_or_dtype(
+            values, categories, ordered, dtype
+        )
+        # At this point, dtype is always a CategoricalDtype, but
+        # we may have dtype.categories be None, and we need to
+        # infer categories in a factorization step further below
+
+        if fastpath:
+            codes = coerce_indexer_dtype(values, dtype.categories)
+            dtype = CategoricalDtype(ordered=False).update_dtype(dtype)
+            super().__init__(codes, dtype)
+            return
+
+        if not is_list_like(values):
+            # GH#38433
+            raise TypeError("Categorical input must be list-like")
+
+        # null_mask indicates missing values we want to exclude from inference.
+        # This means: only missing values in list-likes (not arrays/ndframes).
+        null_mask = np.array(False)
+
+        # sanitize input
+        vdtype = getattr(values, "dtype", None)
+        if isinstance(vdtype, CategoricalDtype):
+            if dtype.categories is None:
+                dtype = CategoricalDtype(values.categories, dtype.ordered)
+        elif not isinstance(values, (ABCIndex, ABCSeries, ExtensionArray)):
+            values = com.convert_to_list_like(values)
+            if isinstance(values, list) and len(values) == 0:
+                # By convention, empty lists result in object dtype:
+                values = np.array([], dtype=object)
+            elif isinstance(values, np.ndarray):
+                if values.ndim > 1:
+                    # preempt sanitize_array from raising ValueError
+                    raise NotImplementedError(
+                        "> 1 ndim Categorical are not supported at this time"
+                    )
+                values = sanitize_array(values, None)
+            else:
+                # i.e. must be a list
+                arr = sanitize_array(values, None)
+                null_mask = isna(arr)
+                if null_mask.any():
+                    # We remove null values here, then below will re-insert
+                    #  them, grep "full_codes"
+                    arr_list = [values[idx] for idx in np.where(~null_mask)[0]]
+
+                    # GH#44900 Do not cast to float if we have only missing values
+                    if arr_list or arr.dtype == "object":
+                        sanitize_dtype = None
+                    else:
+                        sanitize_dtype = arr.dtype
+
+                    arr = sanitize_array(arr_list, None, dtype=sanitize_dtype)
+                values = arr
+
+        if dtype.categories is None:
+            if isinstance(values.dtype, ArrowDtype) and issubclass(
+                values.dtype.type, CategoricalDtypeType
+            ):
+                arr = values._pa_array.combine_chunks()
+                categories = arr.dictionary.to_pandas(types_mapper=ArrowDtype)
+                codes = arr.indices.to_numpy()
+                dtype = CategoricalDtype(categories, values.dtype.pyarrow_dtype.ordered)
+            else:
+                if not isinstance(values, ABCIndex):
+                    # in particular RangeIndex xref test_index_equal_range_categories
+                    values = sanitize_array(values, None)
+                try:
+                    codes, categories = factorize(values, sort=True)
+                except TypeError as err:
+                    codes, categories = factorize(values, sort=False)
+                    if dtype.ordered:
+                        # raise, as we don't have a sortable data structure and so
+                        # the user should give us one by specifying categories
+                        raise TypeError(
+                            "'values' is not ordered, please "
+                            "explicitly specify the categories order "
+                            "by passing in a categories argument."
+                        ) from err
+
+                # we're inferring from values
+                dtype = CategoricalDtype(categories, dtype.ordered)
+
+        elif isinstance(values.dtype, CategoricalDtype):
+            old_codes = extract_array(values)._codes
+            codes = recode_for_categories(
+                old_codes, values.dtype.categories, dtype.categories, copy=copy
+            )
+
+        else:
+            codes = _get_codes_for_values(values, dtype.categories)
+
+        if null_mask.any():
+            # Reinsert -1 placeholders for previously removed missing values
+            full_codes = -np.ones(null_mask.shape, dtype=codes.dtype)
+            full_codes[~null_mask] = codes
+            codes = full_codes
+
+        dtype = CategoricalDtype(ordered=False).update_dtype(dtype)
+        arr = coerce_indexer_dtype(codes, dtype.categories)
+        super().__init__(arr, dtype)
+
+    @property
+    def dtype(self) -> CategoricalDtype:
+        """
+        The :class:`~pandas.api.types.CategoricalDtype` for this instance.
+
+        Examples
+        --------
+        >>> cat = pd.Categorical(['a', 'b'], ordered=True)
+        >>> cat
+        ['a', 'b']
+        Categories (2, object): ['a' < 'b']
+        >>> cat.dtype
+        CategoricalDtype(categories=['a', 'b'], ordered=True, categories_dtype=object)
+        """
+        return self._dtype
+
+    @property
+    def _internal_fill_value(self) -> int:
+        # using the specific numpy integer instead of python int to get
+        #  the correct dtype back from _quantile in the all-NA case
+        dtype = self._ndarray.dtype
+        return dtype.type(-1)
+
+    @classmethod
+    def _from_sequence(
+        cls, scalars, *, dtype: Dtype | None = None, copy: bool = False
+    ) -> Self:
+        return cls(scalars, dtype=dtype, copy=copy)
+
+    @classmethod
+    def _from_scalars(cls, scalars, *, dtype: DtypeObj) -> Self:
+        if dtype is None:
+            # The _from_scalars strictness doesn't make much sense in this case.
+            raise NotImplementedError
+
+        res = cls._from_sequence(scalars, dtype=dtype)
+
+        # if there are any non-category elements in scalars, these will be
+        #  converted to NAs in res.
+        mask = isna(scalars)
+        if not (mask == res.isna()).all():
+            # Some non-category element in scalars got converted to NA in res.
+            raise ValueError
+        return res
+
+    @overload
+    def astype(self, dtype: npt.DTypeLike, copy: bool = ...) -> np.ndarray:
+        ...
+
+    @overload
+    def astype(self, dtype: ExtensionDtype, copy: bool = ...) -> ExtensionArray:
+        ...
+
+    @overload
+    def astype(self, dtype: AstypeArg, copy: bool = ...) -> ArrayLike:
+        ...
+
+    def astype(self, dtype: AstypeArg, copy: bool = True) -> ArrayLike:
+        """
+        Coerce this type to another dtype
+
+        Parameters
+        ----------
+        dtype : numpy dtype or pandas type
+        copy : bool, default True
+            By default, astype always returns a newly allocated object.
+            If copy is set to False and dtype is categorical, the original
+            object is returned.
+        """
+        dtype = pandas_dtype(dtype)
+        if self.dtype is dtype:
+            result = self.copy() if copy else self
+
+        elif isinstance(dtype, CategoricalDtype):
+            # GH 10696/18593/18630
+            dtype = self.dtype.update_dtype(dtype)
+            self = self.copy() if copy else self
+            result = self._set_dtype(dtype)
+
+        elif isinstance(dtype, ExtensionDtype):
+            return super().astype(dtype, copy=copy)
+
+        elif dtype.kind in "iu" and self.isna().any():
+            raise ValueError("Cannot convert float NaN to integer")
+
+        elif len(self.codes) == 0 or len(self.categories) == 0:
+            # For NumPy 1.x compatibility we cannot use copy=None.  And
+            # `copy=False` has the meaning of `copy=None` here:
+            if not copy:
+                result = np.asarray(self, dtype=dtype)
+            else:
+                result = np.array(self, dtype=dtype)
+
+        else:
+            # GH8628 (PERF): astype category codes instead of astyping array
+            new_cats = self.categories._values
+
+            try:
+                new_cats = new_cats.astype(dtype=dtype, copy=copy)
+                fill_value = self.categories._na_value
+                if not is_valid_na_for_dtype(fill_value, dtype):
+                    fill_value = lib.item_from_zerodim(
+                        np.array(self.categories._na_value).astype(dtype)
+                    )
+            except (
+                TypeError,  # downstream error msg for CategoricalIndex is misleading
+                ValueError,
+            ):
+                msg = f"Cannot cast {self.categories.dtype} dtype to {dtype}"
+                raise ValueError(msg)
+
+            result = take_nd(
+                new_cats, ensure_platform_int(self._codes), fill_value=fill_value
+            )
+
+        return result
+
+    def to_list(self):
+        """
+        Alias for tolist.
+        """
+        # GH#51254
+        warnings.warn(
+            "Categorical.to_list is deprecated and will be removed in a future "
+            "version. Use obj.tolist() instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.tolist()
+
+    @classmethod
+    def _from_inferred_categories(
+        cls, inferred_categories, inferred_codes, dtype, true_values=None
+    ) -> Self:
+        """
+        Construct a Categorical from inferred values.
+
+        For inferred categories (`dtype` is None) the categories are sorted.
+        For explicit `dtype`, the `inferred_categories` are cast to the
+        appropriate type.
+
+        Parameters
+        ----------
+        inferred_categories : Index
+        inferred_codes : Index
+        dtype : CategoricalDtype or 'category'
+        true_values : list, optional
+            If none are provided, the default ones are
+            "True", "TRUE", and "true."
+
+        Returns
+        -------
+        Categorical
+        """
+        from pandas import (
+            Index,
+            to_datetime,
+            to_numeric,
+            to_timedelta,
+        )
+
+        cats = Index(inferred_categories)
+        known_categories = (
+            isinstance(dtype, CategoricalDtype) and dtype.categories is not None
+        )
+
+        if known_categories:
+            # Convert to a specialized type with `dtype` if specified.
+            if is_any_real_numeric_dtype(dtype.categories.dtype):
+                cats = to_numeric(inferred_categories, errors="coerce")
+            elif lib.is_np_dtype(dtype.categories.dtype, "M"):
+                cats = to_datetime(inferred_categories, errors="coerce")
+            elif lib.is_np_dtype(dtype.categories.dtype, "m"):
+                cats = to_timedelta(inferred_categories, errors="coerce")
+            elif is_bool_dtype(dtype.categories.dtype):
+                if true_values is None:
+                    true_values = ["True", "TRUE", "true"]
+
+                # error: Incompatible types in assignment (expression has type
+                # "ndarray", variable has type "Index")
+                cats = cats.isin(true_values)  # type: ignore[assignment]
+
+        if known_categories:
+            # Recode from observation order to dtype.categories order.
+            categories = dtype.categories
+            codes = recode_for_categories(inferred_codes, cats, categories)
+        elif not cats.is_monotonic_increasing:
+            # Sort categories and recode for unknown categories.
+            unsorted = cats.copy()
+            categories = cats.sort_values()
+
+            codes = recode_for_categories(inferred_codes, unsorted, categories)
+            dtype = CategoricalDtype(categories, ordered=False)
+        else:
+            dtype = CategoricalDtype(cats, ordered=False)
+            codes = inferred_codes
+
+        return cls._simple_new(codes, dtype=dtype)
+
+    @classmethod
+    def from_codes(
+        cls,
+        codes,
+        categories=None,
+        ordered=None,
+        dtype: Dtype | None = None,
+        validate: bool = True,
+    ) -> Self:
+        """
+        Make a Categorical type from codes and categories or dtype.
+
+        This constructor is useful if you already have codes and
+        categories/dtype and so do not need the (computation intensive)
+        factorization step, which is usually done on the constructor.
+
+        If your data does not follow this convention, please use the normal
+        constructor.
+
+        Parameters
+        ----------
+        codes : array-like of int
+            An integer array, where each integer points to a category in
+            categories or dtype.categories, or else is -1 for NaN.
+        categories : index-like, optional
+            The categories for the categorical. Items need to be unique.
+            If the categories are not given here, then they must be provided
+            in `dtype`.
+        ordered : bool, optional
+            Whether or not this categorical is treated as an ordered
+            categorical. If not given here or in `dtype`, the resulting
+            categorical will be unordered.
+        dtype : CategoricalDtype or "category", optional
+            If :class:`CategoricalDtype`, cannot be used together with
+            `categories` or `ordered`.
+        validate : bool, default True
+            If True, validate that the codes are valid for the dtype.
+            If False, don't validate that the codes are valid. Be careful about skipping
+            validation, as invalid codes can lead to severe problems, such as segfaults.
+
+            .. versionadded:: 2.1.0
+
+        Returns
+        -------
+        Categorical
+
+        Examples
+        --------
+        >>> dtype = pd.CategoricalDtype(['a', 'b'], ordered=True)
+        >>> pd.Categorical.from_codes(codes=[0, 1, 0, 1], dtype=dtype)
+        ['a', 'b', 'a', 'b']
+        Categories (2, object): ['a' < 'b']
+        """
+        dtype = CategoricalDtype._from_values_or_dtype(
+            categories=categories, ordered=ordered, dtype=dtype
+        )
+        if dtype.categories is None:
+            msg = (
+                "The categories must be provided in 'categories' or "
+                "'dtype'. Both were None."
+            )
+            raise ValueError(msg)
+
+        if validate:
+            # beware: non-valid codes may segfault
+            codes = cls._validate_codes_for_dtype(codes, dtype=dtype)
+
+        return cls._simple_new(codes, dtype=dtype)
+
+    # ------------------------------------------------------------------
+    # Categories/Codes/Ordered
+
+    @property
+    def categories(self) -> Index:
+        """
+        The categories of this categorical.
+
+        Setting assigns new values to each category (effectively a rename of
+        each individual category).
+
+        The assigned value has to be a list-like object. All items must be
+        unique and the number of items in the new categories must be the same
+        as the number of items in the old categories.
+
+        Raises
+        ------
+        ValueError
+            If the new categories do not validate as categories or if the
+            number of new categories is unequal the number of old categories
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
+        >>> ser.cat.categories
+        Index(['a', 'b', 'c'], dtype='object')
+
+        >>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], categories=['b', 'c', 'd'])
+        >>> ser = pd.Series(raw_cat)
+        >>> ser.cat.categories
+        Index(['b', 'c', 'd'], dtype='object')
+
+        For :class:`pandas.Categorical`:
+
+        >>> cat = pd.Categorical(['a', 'b'], ordered=True)
+        >>> cat.categories
+        Index(['a', 'b'], dtype='object')
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'c', 'b', 'a', 'c', 'b'])
+        >>> ci.categories
+        Index(['a', 'b', 'c'], dtype='object')
+
+        >>> ci = pd.CategoricalIndex(['a', 'c'], categories=['c', 'b', 'a'])
+        >>> ci.categories
+        Index(['c', 'b', 'a'], dtype='object')
+        """
+        return self.dtype.categories
+
+    @property
+    def ordered(self) -> Ordered:
+        """
+        Whether the categories have an ordered relationship.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
+        >>> ser.cat.ordered
+        False
+
+        >>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], ordered=True)
+        >>> ser = pd.Series(raw_cat)
+        >>> ser.cat.ordered
+        True
+
+        For :class:`pandas.Categorical`:
+
+        >>> cat = pd.Categorical(['a', 'b'], ordered=True)
+        >>> cat.ordered
+        True
+
+        >>> cat = pd.Categorical(['a', 'b'], ordered=False)
+        >>> cat.ordered
+        False
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b'], ordered=True)
+        >>> ci.ordered
+        True
+
+        >>> ci = pd.CategoricalIndex(['a', 'b'], ordered=False)
+        >>> ci.ordered
+        False
+        """
+        return self.dtype.ordered
+
+    @property
+    def codes(self) -> np.ndarray:
+        """
+        The category codes of this categorical index.
+
+        Codes are an array of integers which are the positions of the actual
+        values in the categories array.
+
+        There is no setter, use the other categorical methods and the normal item
+        setter to change values in the categorical.
+
+        Returns
+        -------
+        ndarray[int]
+            A non-writable view of the ``codes`` array.
+
+        Examples
+        --------
+        For :class:`pandas.Categorical`:
+
+        >>> cat = pd.Categorical(['a', 'b'], ordered=True)
+        >>> cat.codes
+        array([0, 1], dtype=int8)
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
+        >>> ci.codes
+        array([0, 1, 2, 0, 1, 2], dtype=int8)
+
+        >>> ci = pd.CategoricalIndex(['a', 'c'], categories=['c', 'b', 'a'])
+        >>> ci.codes
+        array([2, 0], dtype=int8)
+        """
+        v = self._codes.view()
+        v.flags.writeable = False
+        return v
+
+    def _set_categories(self, categories, fastpath: bool = False) -> None:
+        """
+        Sets new categories inplace
+
+        Parameters
+        ----------
+        fastpath : bool, default False
+           Don't perform validation of the categories for uniqueness or nulls
+
+        Examples
+        --------
+        >>> c = pd.Categorical(['a', 'b'])
+        >>> c
+        ['a', 'b']
+        Categories (2, object): ['a', 'b']
+
+        >>> c._set_categories(pd.Index(['a', 'c']))
+        >>> c
+        ['a', 'c']
+        Categories (2, object): ['a', 'c']
+        """
+        if fastpath:
+            new_dtype = CategoricalDtype._from_fastpath(categories, self.ordered)
+        else:
+            new_dtype = CategoricalDtype(categories, ordered=self.ordered)
+        if (
+            not fastpath
+            and self.dtype.categories is not None
+            and len(new_dtype.categories) != len(self.dtype.categories)
+        ):
+            raise ValueError(
+                "new categories need to have the same number of "
+                "items as the old categories!"
+            )
+
+        super().__init__(self._ndarray, new_dtype)
+
+    def _set_dtype(self, dtype: CategoricalDtype) -> Self:
+        """
+        Internal method for directly updating the CategoricalDtype
+
+        Parameters
+        ----------
+        dtype : CategoricalDtype
+
+        Notes
+        -----
+        We don't do any validation here. It's assumed that the dtype is
+        a (valid) instance of `CategoricalDtype`.
+        """
+        codes = recode_for_categories(self.codes, self.categories, dtype.categories)
+        return type(self)._simple_new(codes, dtype=dtype)
+
+    def set_ordered(self, value: bool) -> Self:
+        """
+        Set the ordered attribute to the boolean value.
+
+        Parameters
+        ----------
+        value : bool
+           Set whether this categorical is ordered (True) or not (False).
+        """
+        new_dtype = CategoricalDtype(self.categories, ordered=value)
+        cat = self.copy()
+        NDArrayBacked.__init__(cat, cat._ndarray, new_dtype)
+        return cat
+
+    def as_ordered(self) -> Self:
+        """
+        Set the Categorical to be ordered.
+
+        Returns
+        -------
+        Categorical
+            Ordered Categorical.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
+        >>> ser.cat.ordered
+        False
+        >>> ser = ser.cat.as_ordered()
+        >>> ser.cat.ordered
+        True
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'])
+        >>> ci.ordered
+        False
+        >>> ci = ci.as_ordered()
+        >>> ci.ordered
+        True
+        """
+        return self.set_ordered(True)
+
+    def as_unordered(self) -> Self:
+        """
+        Set the Categorical to be unordered.
+
+        Returns
+        -------
+        Categorical
+            Unordered Categorical.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> raw_cat = pd.Categorical(['a', 'b', 'c', 'a'], ordered=True)
+        >>> ser = pd.Series(raw_cat)
+        >>> ser.cat.ordered
+        True
+        >>> ser = ser.cat.as_unordered()
+        >>> ser.cat.ordered
+        False
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'], ordered=True)
+        >>> ci.ordered
+        True
+        >>> ci = ci.as_unordered()
+        >>> ci.ordered
+        False
+        """
+        return self.set_ordered(False)
+
+    def set_categories(self, new_categories, ordered=None, rename: bool = False):
+        """
+        Set the categories to the specified new categories.
+
+        ``new_categories`` can include new categories (which will result in
+        unused categories) or remove old categories (which results in values
+        set to ``NaN``). If ``rename=True``, the categories will simply be renamed
+        (less or more items than in old categories will result in values set to
+        ``NaN`` or in unused categories respectively).
+
+        This method can be used to perform more than one action of adding,
+        removing, and reordering simultaneously and is therefore faster than
+        performing the individual steps via the more specialised methods.
+
+        On the other hand this methods does not do checks (e.g., whether the
+        old categories are included in the new categories on a reorder), which
+        can result in surprising changes, for example when using special string
+        dtypes, which does not considers a S1 string equal to a single char
+        python string.
+
+        Parameters
+        ----------
+        new_categories : Index-like
+           The categories in new order.
+        ordered : bool, default False
+           Whether or not the categorical is treated as a ordered categorical.
+           If not given, do not change the ordered information.
+        rename : bool, default False
+           Whether or not the new_categories should be considered as a rename
+           of the old categories or as reordered categories.
+
+        Returns
+        -------
+        Categorical with reordered categories.
+
+        Raises
+        ------
+        ValueError
+            If new_categories does not validate as categories
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> raw_cat = pd.Categorical(['a', 'b', 'c', 'A'],
+        ...                           categories=['a', 'b', 'c'], ordered=True)
+        >>> ser = pd.Series(raw_cat)
+        >>> ser
+        0   a
+        1   b
+        2   c
+        3   NaN
+        dtype: category
+        Categories (3, object): ['a' < 'b' < 'c']
+
+        >>> ser.cat.set_categories(['A', 'B', 'C'], rename=True)
+        0   A
+        1   B
+        2   C
+        3   NaN
+        dtype: category
+        Categories (3, object): ['A' < 'B' < 'C']
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'A'],
+        ...                          categories=['a', 'b', 'c'], ordered=True)
+        >>> ci
+        CategoricalIndex(['a', 'b', 'c', nan], categories=['a', 'b', 'c'],
+                         ordered=True, dtype='category')
+
+        >>> ci.set_categories(['A', 'b', 'c'])
+        CategoricalIndex([nan, 'b', 'c', nan], categories=['A', 'b', 'c'],
+                         ordered=True, dtype='category')
+        >>> ci.set_categories(['A', 'b', 'c'], rename=True)
+        CategoricalIndex(['A', 'b', 'c', nan], categories=['A', 'b', 'c'],
+                         ordered=True, dtype='category')
+        """
+
+        if ordered is None:
+            ordered = self.dtype.ordered
+        new_dtype = CategoricalDtype(new_categories, ordered=ordered)
+
+        cat = self.copy()
+        if rename:
+            if cat.dtype.categories is not None and len(new_dtype.categories) < len(
+                cat.dtype.categories
+            ):
+                # remove all _codes which are larger and set to -1/NaN
+                cat._codes[cat._codes >= len(new_dtype.categories)] = -1
+            codes = cat._codes
+        else:
+            codes = recode_for_categories(
+                cat.codes, cat.categories, new_dtype.categories
+            )
+        NDArrayBacked.__init__(cat, codes, new_dtype)
+        return cat
+
+    def rename_categories(self, new_categories) -> Self:
+        """
+        Rename categories.
+
+        Parameters
+        ----------
+        new_categories : list-like, dict-like or callable
+
+            New categories which will replace old categories.
+
+            * list-like: all items must be unique and the number of items in
+              the new categories must match the existing number of categories.
+
+            * dict-like: specifies a mapping from
+              old categories to new. Categories not contained in the mapping
+              are passed through and extra categories in the mapping are
+              ignored.
+
+            * callable : a callable that is called on all items in the old
+              categories and whose return values comprise the new categories.
+
+        Returns
+        -------
+        Categorical
+            Categorical with renamed categories.
+
+        Raises
+        ------
+        ValueError
+            If new categories are list-like and do not have the same number of
+            items than the current categories or do not validate as categories
+
+        See Also
+        --------
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        >>> c = pd.Categorical(['a', 'a', 'b'])
+        >>> c.rename_categories([0, 1])
+        [0, 0, 1]
+        Categories (2, int64): [0, 1]
+
+        For dict-like ``new_categories``, extra keys are ignored and
+        categories not in the dictionary are passed through
+
+        >>> c.rename_categories({'a': 'A', 'c': 'C'})
+        ['A', 'A', 'b']
+        Categories (2, object): ['A', 'b']
+
+        You may also provide a callable to create the new categories
+
+        >>> c.rename_categories(lambda x: x.upper())
+        ['A', 'A', 'B']
+        Categories (2, object): ['A', 'B']
+        """
+
+        if is_dict_like(new_categories):
+            new_categories = [
+                new_categories.get(item, item) for item in self.categories
+            ]
+        elif callable(new_categories):
+            new_categories = [new_categories(item) for item in self.categories]
+
+        cat = self.copy()
+        cat._set_categories(new_categories)
+        return cat
+
+    def reorder_categories(self, new_categories, ordered=None) -> Self:
+        """
+        Reorder categories as specified in new_categories.
+
+        ``new_categories`` need to include all old categories and no new category
+        items.
+
+        Parameters
+        ----------
+        new_categories : Index-like
+           The categories in new order.
+        ordered : bool, optional
+           Whether or not the categorical is treated as a ordered categorical.
+           If not given, do not change the ordered information.
+
+        Returns
+        -------
+        Categorical
+            Categorical with reordered categories.
+
+        Raises
+        ------
+        ValueError
+            If the new categories do not contain all old category items or any
+            new ones
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        For :class:`pandas.Series`:
+
+        >>> ser = pd.Series(['a', 'b', 'c', 'a'], dtype='category')
+        >>> ser = ser.cat.reorder_categories(['c', 'b', 'a'], ordered=True)
+        >>> ser
+        0   a
+        1   b
+        2   c
+        3   a
+        dtype: category
+        Categories (3, object): ['c' < 'b' < 'a']
+
+        >>> ser.sort_values()
+        2   c
+        1   b
+        0   a
+        3   a
+        dtype: category
+        Categories (3, object): ['c' < 'b' < 'a']
+
+        For :class:`pandas.CategoricalIndex`:
+
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a'])
+        >>> ci
+        CategoricalIndex(['a', 'b', 'c', 'a'], categories=['a', 'b', 'c'],
+                         ordered=False, dtype='category')
+        >>> ci.reorder_categories(['c', 'b', 'a'], ordered=True)
+        CategoricalIndex(['a', 'b', 'c', 'a'], categories=['c', 'b', 'a'],
+                         ordered=True, dtype='category')
+        """
+        if (
+            len(self.categories) != len(new_categories)
+            or not self.categories.difference(new_categories).empty
+        ):
+            raise ValueError(
+                "items in new_categories are not the same as in old categories"
+            )
+        return self.set_categories(new_categories, ordered=ordered)
+
+    def add_categories(self, new_categories) -> Self:
+        """
+        Add new categories.
+
+        `new_categories` will be included at the last/highest place in the
+        categories and will be unused directly after this call.
+
+        Parameters
+        ----------
+        new_categories : category or list-like of category
+           The new categories to be included.
+
+        Returns
+        -------
+        Categorical
+            Categorical with new categories added.
+
+        Raises
+        ------
+        ValueError
+            If the new categories include old categories or do not validate as
+            categories
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        remove_categories : Remove the specified categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        >>> c = pd.Categorical(['c', 'b', 'c'])
+        >>> c
+        ['c', 'b', 'c']
+        Categories (2, object): ['b', 'c']
+
+        >>> c.add_categories(['d', 'a'])
+        ['c', 'b', 'c']
+        Categories (4, object): ['b', 'c', 'd', 'a']
+        """
+
+        if not is_list_like(new_categories):
+            new_categories = [new_categories]
+        already_included = set(new_categories) & set(self.dtype.categories)
+        if len(already_included) != 0:
+            raise ValueError(
+                f"new categories must not include old categories: {already_included}"
+            )
+
+        if hasattr(new_categories, "dtype"):
+            from pandas import Series
+
+            dtype = find_common_type(
+                [self.dtype.categories.dtype, new_categories.dtype]
+            )
+            new_categories = Series(
+                list(self.dtype.categories) + list(new_categories), dtype=dtype
+            )
+        else:
+            new_categories = list(self.dtype.categories) + list(new_categories)
+
+        new_dtype = CategoricalDtype(new_categories, self.ordered)
+        cat = self.copy()
+        codes = coerce_indexer_dtype(cat._ndarray, new_dtype.categories)
+        NDArrayBacked.__init__(cat, codes, new_dtype)
+        return cat
+
+    def remove_categories(self, removals) -> Self:
+        """
+        Remove the specified categories.
+
+        `removals` must be included in the old categories. Values which were in
+        the removed categories will be set to NaN
+
+        Parameters
+        ----------
+        removals : category or list of categories
+           The categories which should be removed.
+
+        Returns
+        -------
+        Categorical
+            Categorical with removed categories.
+
+        Raises
+        ------
+        ValueError
+            If the removals are not contained in the categories
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_unused_categories : Remove categories which are not used.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        >>> c = pd.Categorical(['a', 'c', 'b', 'c', 'd'])
+        >>> c
+        ['a', 'c', 'b', 'c', 'd']
+        Categories (4, object): ['a', 'b', 'c', 'd']
+
+        >>> c.remove_categories(['d', 'a'])
+        [NaN, 'c', 'b', 'c', NaN]
+        Categories (2, object): ['b', 'c']
+        """
+        from pandas import Index
+
+        if not is_list_like(removals):
+            removals = [removals]
+
+        removals = Index(removals).unique().dropna()
+        new_categories = (
+            self.dtype.categories.difference(removals, sort=False)
+            if self.dtype.ordered is True
+            else self.dtype.categories.difference(removals)
+        )
+        not_included = removals.difference(self.dtype.categories)
+
+        if len(not_included) != 0:
+            not_included = set(not_included)
+            raise ValueError(f"removals must all be in old categories: {not_included}")
+
+        return self.set_categories(new_categories, ordered=self.ordered, rename=False)
+
+    def remove_unused_categories(self) -> Self:
+        """
+        Remove categories which are not used.
+
+        Returns
+        -------
+        Categorical
+            Categorical with unused categories dropped.
+
+        See Also
+        --------
+        rename_categories : Rename categories.
+        reorder_categories : Reorder categories.
+        add_categories : Add new categories.
+        remove_categories : Remove the specified categories.
+        set_categories : Set the categories to the specified ones.
+
+        Examples
+        --------
+        >>> c = pd.Categorical(['a', 'c', 'b', 'c', 'd'])
+        >>> c
+        ['a', 'c', 'b', 'c', 'd']
+        Categories (4, object): ['a', 'b', 'c', 'd']
+
+        >>> c[2] = 'a'
+        >>> c[4] = 'c'
+        >>> c
+        ['a', 'c', 'a', 'c', 'c']
+        Categories (4, object): ['a', 'b', 'c', 'd']
+
+        >>> c.remove_unused_categories()
+        ['a', 'c', 'a', 'c', 'c']
+        Categories (2, object): ['a', 'c']
+        """
+        idx, inv = np.unique(self._codes, return_inverse=True)
+
+        if idx.size != 0 and idx[0] == -1:  # na sentinel
+            idx, inv = idx[1:], inv - 1
+
+        new_categories = self.dtype.categories.take(idx)
+        new_dtype = CategoricalDtype._from_fastpath(
+            new_categories, ordered=self.ordered
+        )
+        new_codes = coerce_indexer_dtype(inv, new_dtype.categories)
+
+        cat = self.copy()
+        NDArrayBacked.__init__(cat, new_codes, new_dtype)
+        return cat
+
+    # ------------------------------------------------------------------
+
+    def map(
+        self,
+        mapper,
+        na_action: Literal["ignore"] | None | lib.NoDefault = lib.no_default,
+    ):
+        """
+        Map categories using an input mapping or function.
+
+        Maps the categories to new categories. If the mapping correspondence is
+        one-to-one the result is a :class:`~pandas.Categorical` which has the
+        same order property as the original, otherwise a :class:`~pandas.Index`
+        is returned. NaN values are unaffected.
+
+        If a `dict` or :class:`~pandas.Series` is used any unmapped category is
+        mapped to `NaN`. Note that if this happens an :class:`~pandas.Index`
+        will be returned.
+
+        Parameters
+        ----------
+        mapper : function, dict, or Series
+            Mapping correspondence.
+        na_action : {None, 'ignore'}, default 'ignore'
+            If 'ignore', propagate NaN values, without passing them to the
+            mapping correspondence.
+
+            .. deprecated:: 2.1.0
+
+               The default value of 'ignore' has been deprecated and will be changed to
+               None in the future.
+
+        Returns
+        -------
+        pandas.Categorical or pandas.Index
+            Mapped categorical.
+
+        See Also
+        --------
+        CategoricalIndex.map : Apply a mapping correspondence on a
+            :class:`~pandas.CategoricalIndex`.
+        Index.map : Apply a mapping correspondence on an
+            :class:`~pandas.Index`.
+        Series.map : Apply a mapping correspondence on a
+            :class:`~pandas.Series`.
+        Series.apply : Apply more complex functions on a
+            :class:`~pandas.Series`.
+
+        Examples
+        --------
+        >>> cat = pd.Categorical(['a', 'b', 'c'])
+        >>> cat
+        ['a', 'b', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> cat.map(lambda x: x.upper(), na_action=None)
+        ['A', 'B', 'C']
+        Categories (3, object): ['A', 'B', 'C']
+        >>> cat.map({'a': 'first', 'b': 'second', 'c': 'third'}, na_action=None)
+        ['first', 'second', 'third']
+        Categories (3, object): ['first', 'second', 'third']
+
+        If the mapping is one-to-one the ordering of the categories is
+        preserved:
+
+        >>> cat = pd.Categorical(['a', 'b', 'c'], ordered=True)
+        >>> cat
+        ['a', 'b', 'c']
+        Categories (3, object): ['a' < 'b' < 'c']
+        >>> cat.map({'a': 3, 'b': 2, 'c': 1}, na_action=None)
+        [3, 2, 1]
+        Categories (3, int64): [3 < 2 < 1]
+
+        If the mapping is not one-to-one an :class:`~pandas.Index` is returned:
+
+        >>> cat.map({'a': 'first', 'b': 'second', 'c': 'first'}, na_action=None)
+        Index(['first', 'second', 'first'], dtype='object')
+
+        If a `dict` is used, all unmapped categories are mapped to `NaN` and
+        the result is an :class:`~pandas.Index`:
+
+        >>> cat.map({'a': 'first', 'b': 'second'}, na_action=None)
+        Index(['first', 'second', nan], dtype='object')
+        """
+        if na_action is lib.no_default:
+            warnings.warn(
+                "The default value of 'ignore' for the `na_action` parameter in "
+                "pandas.Categorical.map is deprecated and will be "
+                "changed to 'None' in a future version. Please set na_action to the "
+                "desired value to avoid seeing this warning",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            na_action = "ignore"
+
+        assert callable(mapper) or is_dict_like(mapper)
+
+        new_categories = self.categories.map(mapper)
+
+        has_nans = np.any(self._codes == -1)
+
+        na_val = np.nan
+        if na_action is None and has_nans:
+            na_val = mapper(np.nan) if callable(mapper) else mapper.get(np.nan, np.nan)
+
+        if new_categories.is_unique and not new_categories.hasnans and na_val is np.nan:
+            new_dtype = CategoricalDtype(new_categories, ordered=self.ordered)
+            return self.from_codes(self._codes.copy(), dtype=new_dtype, validate=False)
+
+        if has_nans:
+            new_categories = new_categories.insert(len(new_categories), na_val)
+
+        return np.take(new_categories, self._codes)
+
+    __eq__ = _cat_compare_op(operator.eq)
+    __ne__ = _cat_compare_op(operator.ne)
+    __lt__ = _cat_compare_op(operator.lt)
+    __gt__ = _cat_compare_op(operator.gt)
+    __le__ = _cat_compare_op(operator.le)
+    __ge__ = _cat_compare_op(operator.ge)
+
+    # -------------------------------------------------------------
+    # Validators; ideally these can be de-duplicated
+
+    def _validate_setitem_value(self, value):
+        if not is_hashable(value):
+            # wrap scalars and hashable-listlikes in list
+            return self._validate_listlike(value)
+        else:
+            return self._validate_scalar(value)
+
+    def _validate_scalar(self, fill_value):
+        """
+        Convert a user-facing fill_value to a representation to use with our
+        underlying ndarray, raising TypeError if this is not possible.
+
+        Parameters
+        ----------
+        fill_value : object
+
+        Returns
+        -------
+        fill_value : int
+
+        Raises
+        ------
+        TypeError
+        """
+
+        if is_valid_na_for_dtype(fill_value, self.categories.dtype):
+            fill_value = -1
+        elif fill_value in self.categories:
+            fill_value = self._unbox_scalar(fill_value)
+        else:
+            raise TypeError(
+                "Cannot setitem on a Categorical with a new "
+                f"category ({fill_value}), set the categories first"
+            ) from None
+        return fill_value
+
+    @classmethod
+    def _validate_codes_for_dtype(cls, codes, *, dtype: CategoricalDtype) -> np.ndarray:
+        if isinstance(codes, ExtensionArray) and is_integer_dtype(codes.dtype):
+            # Avoid the implicit conversion of Int to object
+            if isna(codes).any():
+                raise ValueError("codes cannot contain NA values")
+            codes = codes.to_numpy(dtype=np.int64)
+        else:
+            codes = np.asarray(codes)
+        if len(codes) and codes.dtype.kind not in "iu":
+            raise ValueError("codes need to be array-like integers")
+
+        if len(codes) and (codes.max() >= len(dtype.categories) or codes.min() < -1):
+            raise ValueError("codes need to be between -1 and len(categories)-1")
+        return codes
+
+    # -------------------------------------------------------------
+
+    @ravel_compat
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        """
+        The numpy array interface.
+
+        Users should not call this directly. Rather, it is invoked by
+        :func:`numpy.array` and :func:`numpy.asarray`.
+
+        Parameters
+        ----------
+        dtype : np.dtype or None
+            Specifies the the dtype for the array.
+
+        copy : bool or None, optional
+            See :func:`numpy.asarray`.
+
+        Returns
+        -------
+        numpy.array
+            A numpy array of either the specified dtype or,
+            if dtype==None (default), the same dtype as
+            categorical.categories.dtype.
+
+        Examples
+        --------
+
+        >>> cat = pd.Categorical(['a', 'b'], ordered=True)
+
+        The following calls ``cat.__array__``
+
+        >>> np.asarray(cat)
+        array(['a', 'b'], dtype=object)
+        """
+        if copy is False:
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        ret = take_nd(self.categories._values, self._codes)
+        # When we're a Categorical[ExtensionArray], like Interval,
+        # we need to ensure __array__ gets all the way to an
+        # ndarray.
+
+        # `take_nd` should already make a copy, so don't force again.
+        return np.asarray(ret, dtype=dtype)
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        # for binary ops, use our custom dunder methods
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            # e.g. test_numpy_ufuncs_out
+            return arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+
+        if method == "reduce":
+            # e.g. TestCategoricalAnalytics::test_min_max_ordered
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                return result
+
+        # for all other cases, raise for now (similarly as what happens in
+        # Series.__array_prepare__)
+        raise TypeError(
+            f"Object with dtype {self.dtype} cannot perform "
+            f"the numpy op {ufunc.__name__}"
+        )
+
+    def __setstate__(self, state) -> None:
+        """Necessary for making this object picklable"""
+        if not isinstance(state, dict):
+            return super().__setstate__(state)
+
+        if "_dtype" not in state:
+            state["_dtype"] = CategoricalDtype(state["_categories"], state["_ordered"])
+
+        if "_codes" in state and "_ndarray" not in state:
+            # backward compat, changed what is property vs attribute
+            state["_ndarray"] = state.pop("_codes")
+
+        super().__setstate__(state)
+
+    @property
+    def nbytes(self) -> int:
+        return self._codes.nbytes + self.dtype.categories.values.nbytes
+
+    def memory_usage(self, deep: bool = False) -> int:
+        """
+        Memory usage of my values
+
+        Parameters
+        ----------
+        deep : bool
+            Introspect the data deeply, interrogate
+            `object` dtypes for system-level memory consumption
+
+        Returns
+        -------
+        bytes used
+
+        Notes
+        -----
+        Memory usage does not include memory consumed by elements that
+        are not components of the array if deep=False
+
+        See Also
+        --------
+        numpy.ndarray.nbytes
+        """
+        return self._codes.nbytes + self.dtype.categories.memory_usage(deep=deep)
+
+    def isna(self) -> npt.NDArray[np.bool_]:
+        """
+        Detect missing values
+
+        Missing values (-1 in .codes) are detected.
+
+        Returns
+        -------
+        np.ndarray[bool] of whether my values are null
+
+        See Also
+        --------
+        isna : Top-level isna.
+        isnull : Alias of isna.
+        Categorical.notna : Boolean inverse of Categorical.isna.
+
+        """
+        return self._codes == -1
+
+    isnull = isna
+
+    def notna(self) -> npt.NDArray[np.bool_]:
+        """
+        Inverse of isna
+
+        Both missing values (-1 in .codes) and NA as a category are detected as
+        null.
+
+        Returns
+        -------
+        np.ndarray[bool] of whether my values are not null
+
+        See Also
+        --------
+        notna : Top-level notna.
+        notnull : Alias of notna.
+        Categorical.isna : Boolean inverse of Categorical.notna.
+
+        """
+        return ~self.isna()
+
+    notnull = notna
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Return a Series containing counts of each category.
+
+        Every category will have an entry, even those with a count of 0.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of NaN.
+
+        Returns
+        -------
+        counts : Series
+
+        See Also
+        --------
+        Series.value_counts
+        """
+        from pandas import (
+            CategoricalIndex,
+            Series,
+        )
+
+        code, cat = self._codes, self.categories
+        ncat, mask = (len(cat), code >= 0)
+        ix, clean = np.arange(ncat), mask.all()
+
+        if dropna or clean:
+            obs = code if clean else code[mask]
+            count = np.bincount(obs, minlength=ncat or 0)
+        else:
+            count = np.bincount(np.where(mask, code, ncat))
+            ix = np.append(ix, -1)
+
+        ix = coerce_indexer_dtype(ix, self.dtype.categories)
+        ix = self._from_backing_data(ix)
+
+        return Series(
+            count, index=CategoricalIndex(ix), dtype="int64", name="count", copy=False
+        )
+
+    # error: Argument 2 of "_empty" is incompatible with supertype
+    # "NDArrayBackedExtensionArray"; supertype defines the argument type as
+    # "ExtensionDtype"
+    @classmethod
+    def _empty(  # type: ignore[override]
+        cls, shape: Shape, dtype: CategoricalDtype
+    ) -> Self:
+        """
+        Analogous to np.empty(shape, dtype=dtype)
+
+        Parameters
+        ----------
+        shape : tuple[int]
+        dtype : CategoricalDtype
+        """
+        arr = cls._from_sequence([], dtype=dtype)
+
+        # We have to use np.zeros instead of np.empty otherwise the resulting
+        #  ndarray may contain codes not supported by this dtype, in which
+        #  case repr(result) could segfault.
+        backing = np.zeros(shape, dtype=arr._ndarray.dtype)
+
+        return arr._from_backing_data(backing)
+
+    def _internal_get_values(self) -> ArrayLike:
+        """
+        Return the values.
+
+        For internal compatibility with pandas formatting.
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+            A numpy array or ExtensionArray of the same dtype as
+            categorical.categories.dtype.
+        """
+        # if we are a datetime and period index, return Index to keep metadata
+        if needs_i8_conversion(self.categories.dtype):
+            return self.categories.take(self._codes, fill_value=NaT)._values
+        elif is_integer_dtype(self.categories.dtype) and -1 in self._codes:
+            return (
+                self.categories.astype("object")
+                .take(self._codes, fill_value=np.nan)
+                ._values
+            )
+        return np.array(self)
+
+    def check_for_ordered(self, op) -> None:
+        """assert that we are ordered"""
+        if not self.ordered:
+            raise TypeError(
+                f"Categorical is not ordered for operation {op}\n"
+                "you can use .as_ordered() to change the "
+                "Categorical to an ordered one\n"
+            )
+
+    def argsort(
+        self, *, ascending: bool = True, kind: SortKind = "quicksort", **kwargs
+    ):
+        """
+        Return the indices that would sort the Categorical.
+
+        Missing values are sorted at the end.
+
+        Parameters
+        ----------
+        ascending : bool, default True
+            Whether the indices should result in an ascending
+            or descending sort.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, optional
+            Sorting algorithm.
+        **kwargs:
+            passed through to :func:`numpy.argsort`.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+
+        See Also
+        --------
+        numpy.ndarray.argsort
+
+        Notes
+        -----
+        While an ordering is applied to the category values, arg-sorting
+        in this context refers more to organizing and grouping together
+        based on matching category values. Thus, this function can be
+        called on an unordered Categorical instance unlike the functions
+        'Categorical.min' and 'Categorical.max'.
+
+        Examples
+        --------
+        >>> pd.Categorical(['b', 'b', 'a', 'c']).argsort()
+        array([2, 0, 1, 3])
+
+        >>> cat = pd.Categorical(['b', 'b', 'a', 'c'],
+        ...                      categories=['c', 'b', 'a'],
+        ...                      ordered=True)
+        >>> cat.argsort()
+        array([3, 0, 1, 2])
+
+        Missing values are placed at the end
+
+        >>> cat = pd.Categorical([2, None, 1])
+        >>> cat.argsort()
+        array([2, 0, 1])
+        """
+        return super().argsort(ascending=ascending, kind=kind, **kwargs)
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        inplace: Literal[False] = ...,
+        ascending: bool = ...,
+        na_position: str = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def sort_values(
+        self, *, inplace: Literal[True], ascending: bool = ..., na_position: str = ...
+    ) -> None:
+        ...
+
+    def sort_values(
+        self,
+        *,
+        inplace: bool = False,
+        ascending: bool = True,
+        na_position: str = "last",
+    ) -> Self | None:
+        """
+        Sort the Categorical by category value returning a new
+        Categorical by default.
+
+        While an ordering is applied to the category values, sorting in this
+        context refers more to organizing and grouping together based on
+        matching category values. Thus, this function can be called on an
+        unordered Categorical instance unlike the functions 'Categorical.min'
+        and 'Categorical.max'.
+
+        Parameters
+        ----------
+        inplace : bool, default False
+            Do operation in place.
+        ascending : bool, default True
+            Order ascending. Passing False orders descending. The
+            ordering parameter provides the method by which the
+            category values are organized.
+        na_position : {'first', 'last'} (optional, default='last')
+            'first' puts NaNs at the beginning
+            'last' puts NaNs at the end
+
+        Returns
+        -------
+        Categorical or None
+
+        See Also
+        --------
+        Categorical.sort
+        Series.sort_values
+
+        Examples
+        --------
+        >>> c = pd.Categorical([1, 2, 2, 1, 5])
+        >>> c
+        [1, 2, 2, 1, 5]
+        Categories (3, int64): [1, 2, 5]
+        >>> c.sort_values()
+        [1, 1, 2, 2, 5]
+        Categories (3, int64): [1, 2, 5]
+        >>> c.sort_values(ascending=False)
+        [5, 2, 2, 1, 1]
+        Categories (3, int64): [1, 2, 5]
+
+        >>> c = pd.Categorical([1, 2, 2, 1, 5])
+
+        'sort_values' behaviour with NaNs. Note that 'na_position'
+        is independent of the 'ascending' parameter:
+
+        >>> c = pd.Categorical([np.nan, 2, 2, np.nan, 5])
+        >>> c
+        [NaN, 2, 2, NaN, 5]
+        Categories (2, int64): [2, 5]
+        >>> c.sort_values()
+        [2, 2, 5, NaN, NaN]
+        Categories (2, int64): [2, 5]
+        >>> c.sort_values(ascending=False)
+        [5, 2, 2, NaN, NaN]
+        Categories (2, int64): [2, 5]
+        >>> c.sort_values(na_position='first')
+        [NaN, NaN, 2, 2, 5]
+        Categories (2, int64): [2, 5]
+        >>> c.sort_values(ascending=False, na_position='first')
+        [NaN, NaN, 5, 2, 2]
+        Categories (2, int64): [2, 5]
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if na_position not in ["last", "first"]:
+            raise ValueError(f"invalid na_position: {repr(na_position)}")
+
+        sorted_idx = nargsort(self, ascending=ascending, na_position=na_position)
+
+        if not inplace:
+            codes = self._codes[sorted_idx]
+            return self._from_backing_data(codes)
+        self._codes[:] = self._codes[sorted_idx]
+        return None
+
+    def _rank(
+        self,
+        *,
+        axis: AxisInt = 0,
+        method: str = "average",
+        na_option: str = "keep",
+        ascending: bool = True,
+        pct: bool = False,
+    ):
+        """
+        See Series.rank.__doc__.
+        """
+        if axis != 0:
+            raise NotImplementedError
+        vff = self._values_for_rank()
+        return algorithms.rank(
+            vff,
+            axis=axis,
+            method=method,
+            na_option=na_option,
+            ascending=ascending,
+            pct=pct,
+        )
+
+    def _values_for_rank(self) -> np.ndarray:
+        """
+        For correctly ranking ordered categorical data. See GH#15420
+
+        Ordered categorical data should be ranked on the basis of
+        codes with -1 translated to NaN.
+
+        Returns
+        -------
+        numpy.array
+
+        """
+        from pandas import Series
+
+        if self.ordered:
+            values = self.codes
+            mask = values == -1
+            if mask.any():
+                values = values.astype("float64")
+                values[mask] = np.nan
+        elif is_any_real_numeric_dtype(self.categories.dtype):
+            values = np.array(self)
+        else:
+            #  reorder the categories (so rank can use the float codes)
+            #  instead of passing an object array to rank
+            values = np.array(
+                self.rename_categories(
+                    Series(self.categories, copy=False).rank().values
+                )
+            )
+        return values
+
+    def _hash_pandas_object(
+        self, *, encoding: str, hash_key: str, categorize: bool
+    ) -> npt.NDArray[np.uint64]:
+        """
+        Hash a Categorical by hashing its categories, and then mapping the codes
+        to the hashes.
+
+        Parameters
+        ----------
+        encoding : str
+        hash_key : str
+        categorize : bool
+            Ignored for Categorical.
+
+        Returns
+        -------
+        np.ndarray[uint64]
+        """
+        # Note we ignore categorize, as we are already Categorical.
+        from pandas.core.util.hashing import hash_array
+
+        # Convert ExtensionArrays to ndarrays
+        values = np.asarray(self.categories._values)
+        hashed = hash_array(values, encoding, hash_key, categorize=False)
+
+        # we have uint64, as we don't directly support missing values
+        # we don't want to use take_nd which will coerce to float
+        # instead, directly construct the result with a
+        # max(np.uint64) as the missing value indicator
+        #
+        # TODO: GH#15362
+
+        mask = self.isna()
+        if len(hashed):
+            result = hashed.take(self._codes)
+        else:
+            result = np.zeros(len(mask), dtype="uint64")
+
+        if mask.any():
+            result[mask] = lib.u8max
+
+        return result
+
+    # ------------------------------------------------------------------
+    # NDArrayBackedExtensionArray compat
+
+    @property
+    def _codes(self) -> np.ndarray:
+        return self._ndarray
+
+    def _box_func(self, i: int):
+        if i == -1:
+            return np.nan
+        return self.categories[i]
+
+    def _unbox_scalar(self, key) -> int:
+        # searchsorted is very performance sensitive. By converting codes
+        # to same dtype as self.codes, we get much faster performance.
+        code = self.categories.get_loc(key)
+        code = self._ndarray.dtype.type(code)
+        return code
+
+    # ------------------------------------------------------------------
+
+    def __iter__(self) -> Iterator:
+        """
+        Returns an Iterator over the values of this Categorical.
+        """
+        if self.ndim == 1:
+            return iter(self._internal_get_values().tolist())
+        else:
+            return (self[n] for n in range(len(self)))
+
+    def __contains__(self, key) -> bool:
+        """
+        Returns True if `key` is in this Categorical.
+        """
+        # if key is a NaN, check if any NaN is in self.
+        if is_valid_na_for_dtype(key, self.categories.dtype):
+            return bool(self.isna().any())
+
+        return contains(self, key, container=self._codes)
+
+    # ------------------------------------------------------------------
+    # Rendering Methods
+
+    def _formatter(self, boxed: bool = False):
+        # Returning None here will cause format_array to do inference.
+        return None
+
+    def _repr_categories(self) -> list[str]:
+        """
+        return the base repr for the categories
+        """
+        max_categories = (
+            10
+            if get_option("display.max_categories") == 0
+            else get_option("display.max_categories")
+        )
+        from pandas.io.formats import format as fmt
+
+        formatter = None
+        if self.categories.dtype == "str":
+            # the extension array formatter defaults to boxed=True in format_array
+            # override here to boxed=False to be consistent with QUOTE_NONNUMERIC
+            formatter = cast(ExtensionArray, self.categories._values)._formatter(
+                boxed=False
+            )
+
+        format_array = partial(
+            fmt.format_array, formatter=formatter, quoting=QUOTE_NONNUMERIC
+        )
+        if len(self.categories) > max_categories:
+            num = max_categories // 2
+            head = format_array(self.categories[:num]._values)
+            tail = format_array(self.categories[-num:]._values)
+            category_strs = head + ["..."] + tail
+        else:
+            category_strs = format_array(self.categories._values)
+
+        # Strip all leading spaces, which format_array adds for columns...
+        category_strs = [x.strip() for x in category_strs]
+        return category_strs
+
+    def _get_repr_footer(self) -> str:
+        """
+        Returns a string representation of the footer.
+        """
+        category_strs = self._repr_categories()
+        dtype = str(self.categories.dtype)
+        levheader = f"Categories ({len(self.categories)}, {dtype}): "
+        width, _ = get_terminal_size()
+        max_width = get_option("display.width") or width
+        if console.in_ipython_frontend():
+            # 0 = no breaks
+            max_width = 0
+        levstring = ""
+        start = True
+        cur_col_len = len(levheader)  # header
+        sep_len, sep = (3, " < ") if self.ordered else (2, ", ")
+        linesep = f"{sep.rstrip()}\n"  # remove whitespace
+        for val in category_strs:
+            if max_width != 0 and cur_col_len + sep_len + len(val) > max_width:
+                levstring += linesep + (" " * (len(levheader) + 1))
+                cur_col_len = len(levheader) + 1  # header + a whitespace
+            elif not start:
+                levstring += sep
+                cur_col_len += len(val)
+            levstring += val
+            start = False
+        # replace to simple save space by
+        return f"{levheader}[{levstring.replace(' < ... < ', ' ... ')}]"
+
+    def _get_values_repr(self) -> str:
+        from pandas.io.formats import format as fmt
+
+        assert len(self) > 0
+
+        vals = self._internal_get_values()
+        fmt_values = fmt.format_array(
+            vals,
+            None,
+            float_format=None,
+            na_rep="NaN",
+            quoting=QUOTE_NONNUMERIC,
+        )
+
+        fmt_values = [i.strip() for i in fmt_values]
+        joined = ", ".join(fmt_values)
+        result = "[" + joined + "]"
+        return result
+
+    def __repr__(self) -> str:
+        """
+        String representation.
+        """
+        footer = self._get_repr_footer()
+        length = len(self)
+        max_len = 10
+        if length > max_len:
+            # In long cases we do not display all entries, so we add Length
+            #  information to the __repr__.
+            num = max_len // 2
+            head = self[:num]._get_values_repr()
+            tail = self[-(max_len - num) :]._get_values_repr()
+            body = f"{head[:-1]}, ..., {tail[1:]}"
+            length_info = f"Length: {len(self)}"
+            result = f"{body}\n{length_info}\n{footer}"
+        elif length > 0:
+            body = self._get_values_repr()
+            result = f"{body}\n{footer}"
+        else:
+            # In the empty case we use a comma instead of newline to get
+            #  a more compact __repr__
+            body = "[]"
+            result = f"{body}, {footer}"
+
+        return result
+
+    # ------------------------------------------------------------------
+
+    def _validate_listlike(self, value):
+        # NB: here we assume scalar-like tuples have already been excluded
+        value = extract_array(value, extract_numpy=True)
+
+        # require identical categories set
+        if isinstance(value, Categorical):
+            if self.dtype != value.dtype:
+                raise TypeError(
+                    "Cannot set a Categorical with another, "
+                    "without identical categories"
+                )
+            # dtype equality implies categories_match_up_to_permutation
+            value = self._encode_with_my_categories(value)
+            return value._codes
+
+        from pandas import Index
+
+        # tupleize_cols=False for e.g. test_fillna_iterable_category GH#41914
+        to_add = Index._with_infer(value, tupleize_cols=False).difference(
+            self.categories
+        )
+
+        # no assignments of values not in categories, but it's always ok to set
+        # something to np.nan
+        if len(to_add) and not isna(to_add).all():
+            raise TypeError(
+                "Cannot setitem on a Categorical with a new "
+                "category, set the categories first"
+            )
+
+        codes = self.categories.get_indexer(value)
+        return codes.astype(self._ndarray.dtype, copy=False)
+
+    def _reverse_indexer(self) -> dict[Hashable, npt.NDArray[np.intp]]:
+        """
+        Compute the inverse of a categorical, returning
+        a dict of categories -> indexers.
+
+        *This is an internal function*
+
+        Returns
+        -------
+        Dict[Hashable, np.ndarray[np.intp]]
+            dict of categories -> indexers
+
+        Examples
+        --------
+        >>> c = pd.Categorical(list('aabca'))
+        >>> c
+        ['a', 'a', 'b', 'c', 'a']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> c.categories
+        Index(['a', 'b', 'c'], dtype='object')
+        >>> c.codes
+        array([0, 0, 1, 2, 0], dtype=int8)
+        >>> c._reverse_indexer()
+        {'a': array([0, 1, 4]), 'b': array([2]), 'c': array([3])}
+
+        """
+        categories = self.categories
+        r, counts = libalgos.groupsort_indexer(
+            ensure_platform_int(self.codes), categories.size
+        )
+        counts = ensure_int64(counts).cumsum()
+        _result = (r[start:end] for start, end in zip(counts, counts[1:]))
+        return dict(zip(categories, _result))
+
+    # ------------------------------------------------------------------
+    # Reductions
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        result = super()._reduce(name, skipna=skipna, keepdims=keepdims, **kwargs)
+        if name in ["argmax", "argmin"]:
+            # don't wrap in Categorical!
+            return result
+        if keepdims:
+            return type(self)(result, dtype=self.dtype)
+        else:
+            return result
+
+    def min(self, *, skipna: bool = True, **kwargs):
+        """
+        The minimum value of the object.
+
+        Only ordered `Categoricals` have a minimum!
+
+        Raises
+        ------
+        TypeError
+            If the `Categorical` is not `ordered`.
+
+        Returns
+        -------
+        min : the minimum of this `Categorical`, NA value if empty
+        """
+        nv.validate_minmax_axis(kwargs.get("axis", 0))
+        nv.validate_min((), kwargs)
+        self.check_for_ordered("min")
+
+        if not len(self._codes):
+            return self.dtype.na_value
+
+        good = self._codes != -1
+        if not good.all():
+            if skipna and good.any():
+                pointer = self._codes[good].min()
+            else:
+                return np.nan
+        else:
+            pointer = self._codes.min()
+        return self._wrap_reduction_result(None, pointer)
+
+    def max(self, *, skipna: bool = True, **kwargs):
+        """
+        The maximum value of the object.
+
+        Only ordered `Categoricals` have a maximum!
+
+        Raises
+        ------
+        TypeError
+            If the `Categorical` is not `ordered`.
+
+        Returns
+        -------
+        max : the maximum of this `Categorical`, NA if array is empty
+        """
+        nv.validate_minmax_axis(kwargs.get("axis", 0))
+        nv.validate_max((), kwargs)
+        self.check_for_ordered("max")
+
+        if not len(self._codes):
+            return self.dtype.na_value
+
+        good = self._codes != -1
+        if not good.all():
+            if skipna and good.any():
+                pointer = self._codes[good].max()
+            else:
+                return np.nan
+        else:
+            pointer = self._codes.max()
+        return self._wrap_reduction_result(None, pointer)
+
+    def _mode(self, dropna: bool = True) -> Categorical:
+        codes = self._codes
+        mask = None
+        if dropna:
+            mask = self.isna()
+
+        res_codes = algorithms.mode(codes, mask=mask)
+        res_codes = cast(np.ndarray, res_codes)
+        assert res_codes.dtype == codes.dtype
+        res = self._from_backing_data(res_codes)
+        return res
+
+    # ------------------------------------------------------------------
+    # ExtensionArray Interface
+
+    def unique(self) -> Self:
+        """
+        Return the ``Categorical`` which ``categories`` and ``codes`` are
+        unique.
+
+        .. versionchanged:: 1.3.0
+
+            Previously, unused categories were dropped from the new categories.
+
+        Returns
+        -------
+        Categorical
+
+        See Also
+        --------
+        pandas.unique
+        CategoricalIndex.unique
+        Series.unique : Return unique values of Series object.
+
+        Examples
+        --------
+        >>> pd.Categorical(list("baabc")).unique()
+        ['b', 'a', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> pd.Categorical(list("baab"), categories=list("abc"), ordered=True).unique()
+        ['b', 'a']
+        Categories (3, object): ['a' < 'b' < 'c']
+        """
+        # pylint: disable=useless-parent-delegation
+        return super().unique()
+
+    def equals(self, other: object) -> bool:
+        """
+        Returns True if categorical arrays are equal.
+
+        Parameters
+        ----------
+        other : `Categorical`
+
+        Returns
+        -------
+        bool
+        """
+        if not isinstance(other, Categorical):
+            return False
+        elif self._categories_match_up_to_permutation(other):
+            other = self._encode_with_my_categories(other)
+            return np.array_equal(self._codes, other._codes)
+        return False
+
+    @classmethod
+    def _concat_same_type(cls, to_concat: Sequence[Self], axis: AxisInt = 0) -> Self:
+        from pandas.core.dtypes.concat import union_categoricals
+
+        first = to_concat[0]
+        if axis >= first.ndim:
+            raise ValueError(
+                f"axis {axis} is out of bounds for array of dimension {first.ndim}"
+            )
+
+        if axis == 1:
+            # Flatten, concatenate then reshape
+            if not all(x.ndim == 2 for x in to_concat):
+                raise ValueError
+
+            # pass correctly-shaped to union_categoricals
+            tc_flat = []
+            for obj in to_concat:
+                tc_flat.extend([obj[:, i] for i in range(obj.shape[1])])
+
+            res_flat = cls._concat_same_type(tc_flat, axis=0)
+
+            result = res_flat.reshape(len(first), -1, order="F")
+            return result
+
+        result = union_categoricals(to_concat)
+        return result
+
+    # ------------------------------------------------------------------
+
+    def _encode_with_my_categories(self, other: Categorical) -> Categorical:
+        """
+        Re-encode another categorical using this Categorical's categories.
+
+        Notes
+        -----
+        This assumes we have already checked
+        self._categories_match_up_to_permutation(other).
+        """
+        # Indexing on codes is more efficient if categories are the same,
+        #  so we can apply some optimizations based on the degree of
+        #  dtype-matching.
+        codes = recode_for_categories(
+            other.codes, other.categories, self.categories, copy=False
+        )
+        return self._from_backing_data(codes)
+
+    def _categories_match_up_to_permutation(self, other: Categorical) -> bool:
+        """
+        Returns True if categoricals are the same dtype
+          same categories, and same ordered
+
+        Parameters
+        ----------
+        other : Categorical
+
+        Returns
+        -------
+        bool
+        """
+        return hash(self.dtype) == hash(other.dtype)
+
+    def describe(self) -> DataFrame:
+        """
+        Describes this Categorical
+
+        Returns
+        -------
+        description: `DataFrame`
+            A dataframe with frequency and counts by category.
+        """
+        counts = self.value_counts(dropna=False)
+        freqs = counts / counts.sum()
+
+        from pandas import Index
+        from pandas.core.reshape.concat import concat
+
+        result = concat([counts, freqs], axis=1)
+        result.columns = Index(["counts", "freqs"])
+        result.index.name = "categories"
+
+        return result
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        """
+        Check whether `values` are contained in Categorical.
+
+        Return a boolean NumPy Array showing whether each element in
+        the Categorical matches an element in the passed sequence of
+        `values` exactly.
+
+        Parameters
+        ----------
+        values : np.ndarray or ExtensionArray
+            The sequence of values to test. Passing in a single string will
+            raise a ``TypeError``. Instead, turn a single string into a
+            list of one element.
+
+        Returns
+        -------
+        np.ndarray[bool]
+
+        Raises
+        ------
+        TypeError
+          * If `values` is not a set or list-like
+
+        See Also
+        --------
+        pandas.Series.isin : Equivalent method on Series.
+
+        Examples
+        --------
+        >>> s = pd.Categorical(['lama', 'cow', 'lama', 'beetle', 'lama',
+        ...                'hippo'])
+        >>> s.isin(['cow', 'lama'])
+        array([ True,  True,  True, False,  True, False])
+
+        Passing a single string as ``s.isin('lama')`` will raise an error. Use
+        a list of one element instead:
+
+        >>> s.isin(['lama'])
+        array([ True, False,  True, False,  True, False])
+        """
+        null_mask = np.asarray(isna(values))
+        code_values = self.categories.get_indexer_for(values)
+        code_values = code_values[null_mask | (code_values >= 0)]
+        return algorithms.isin(self.codes, code_values)
+
+    def _replace(self, *, to_replace, value, inplace: bool = False):
+        from pandas import Index
+
+        orig_dtype = self.dtype
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        cat = self if inplace else self.copy()
+
+        mask = isna(np.asarray(value))
+        if mask.any():
+            removals = np.asarray(to_replace)[mask]
+            removals = cat.categories[cat.categories.isin(removals)]
+            new_cat = cat.remove_categories(removals)
+            NDArrayBacked.__init__(cat, new_cat.codes, new_cat.dtype)
+
+        ser = cat.categories.to_series()
+        ser = ser.replace(to_replace=to_replace, value=value)
+
+        all_values = Index(ser)
+
+        # GH51016: maintain order of existing categories
+        idxr = cat.categories.get_indexer_for(all_values)
+        locs = np.arange(len(ser))
+        locs = np.where(idxr == -1, locs, idxr)
+        locs = locs.argsort()
+
+        new_categories = ser.take(locs)
+        new_categories = new_categories.drop_duplicates(keep="first")
+        new_categories = Index(new_categories)
+        new_codes = recode_for_categories(
+            cat._codes, all_values, new_categories, copy=False
+        )
+        new_dtype = CategoricalDtype(new_categories, ordered=self.dtype.ordered)
+        NDArrayBacked.__init__(cat, new_codes, new_dtype)
+
+        if new_dtype != orig_dtype:
+            warnings.warn(
+                # GH#55147
+                "The behavior of Series.replace (and DataFrame.replace) with "
+                "CategoricalDtype is deprecated. In a future version, replace "
+                "will only be used for cases that preserve the categories. "
+                "To change the categories, use ser.cat.rename_categories "
+                "instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if not inplace:
+            return cat
+
+    # ------------------------------------------------------------------------
+    # String methods interface
+    def _str_map(
+        self, f, na_value=lib.no_default, dtype=np.dtype("object"), convert: bool = True
+    ):
+        # Optimization to apply the callable `f` to the categories once
+        # and rebuild the result by `take`ing from the result with the codes.
+        # Returns the same type as the object-dtype implementation though.
+        categories = self.categories
+        codes = self.codes
+        if categories.dtype == "string":
+            result = categories.array._str_map(f, na_value, dtype)  # type: ignore[attr-defined]
+            if (
+                categories.dtype.na_value is np.nan  # type: ignore[union-attr]
+                and is_bool_dtype(dtype)
+                and (na_value is lib.no_default or isna(na_value))
+            ):
+                # NaN propagates as False for functions with boolean return type
+                na_value = False
+        else:
+            from pandas.core.arrays import NumpyExtensionArray
+
+            result = NumpyExtensionArray(categories.to_numpy())._str_map(
+                f, na_value, dtype
+            )
+        return take_nd(result, codes, fill_value=na_value)
+
+    def _str_get_dummies(self, sep: str = "|"):
+        # sep may not be in categories. Just bail on this.
+        from pandas.core.arrays import NumpyExtensionArray
+
+        return NumpyExtensionArray(self.to_numpy(str, na_value="NaN"))._str_get_dummies(
+            sep
+        )
+
+    # ------------------------------------------------------------------------
+    # GroupBy Methods
+
+    def _groupby_op(
+        self,
+        *,
+        how: str,
+        has_dropped_na: bool,
+        min_count: int,
+        ngroups: int,
+        ids: npt.NDArray[np.intp],
+        **kwargs,
+    ):
+        from pandas.core.groupby.ops import WrappedCythonOp
+
+        kind = WrappedCythonOp.get_kind_from_how(how)
+        op = WrappedCythonOp(how=how, kind=kind, has_dropped_na=has_dropped_na)
+
+        dtype = self.dtype
+        if how in ["sum", "prod", "cumsum", "cumprod", "skew"]:
+            raise TypeError(f"{dtype} type does not support {how} operations")
+        if how in ["min", "max", "rank", "idxmin", "idxmax"] and not dtype.ordered:
+            # raise TypeError instead of NotImplementedError to ensure we
+            #  don't go down a group-by-group path, since in the empty-groups
+            #  case that would fail to raise
+            raise TypeError(f"Cannot perform {how} with non-ordered Categorical")
+        if how not in [
+            "rank",
+            "any",
+            "all",
+            "first",
+            "last",
+            "min",
+            "max",
+            "idxmin",
+            "idxmax",
+        ]:
+            if kind == "transform":
+                raise TypeError(f"{dtype} type does not support {how} operations")
+            raise TypeError(f"{dtype} dtype does not support aggregation '{how}'")
+
+        result_mask = None
+        mask = self.isna()
+        if how == "rank":
+            assert self.ordered  # checked earlier
+            npvalues = self._ndarray
+        elif how in ["first", "last", "min", "max", "idxmin", "idxmax"]:
+            npvalues = self._ndarray
+            result_mask = np.zeros(ngroups, dtype=bool)
+        else:
+            # any/all
+            npvalues = self.astype(bool)
+
+        res_values = op._cython_op_ndim_compat(
+            npvalues,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=ids,
+            mask=mask,
+            result_mask=result_mask,
+            **kwargs,
+        )
+
+        if how in op.cast_blocklist:
+            return res_values
+        elif how in ["first", "last", "min", "max"]:
+            res_values[result_mask == 1] = -1
+        return self._from_backing_data(res_values)
+
+
+# The Series.cat accessor
+
+
+@delegate_names(
+    delegate=Categorical, accessors=["categories", "ordered"], typ="property"
+)
+@delegate_names(
+    delegate=Categorical,
+    accessors=[
+        "rename_categories",
+        "reorder_categories",
+        "add_categories",
+        "remove_categories",
+        "remove_unused_categories",
+        "set_categories",
+        "as_ordered",
+        "as_unordered",
+    ],
+    typ="method",
+)
+class CategoricalAccessor(PandasDelegate, PandasObject, NoNewAttributesMixin):
+    """
+    Accessor object for categorical properties of the Series values.
+
+    Parameters
+    ----------
+    data : Series or CategoricalIndex
+
+    Examples
+    --------
+    >>> s = pd.Series(list("abbccc")).astype("category")
+    >>> s
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (3, object): ['a', 'b', 'c']
+
+    >>> s.cat.categories
+    Index(['a', 'b', 'c'], dtype='object')
+
+    >>> s.cat.rename_categories(list("cba"))
+    0    c
+    1    b
+    2    b
+    3    a
+    4    a
+    5    a
+    dtype: category
+    Categories (3, object): ['c', 'b', 'a']
+
+    >>> s.cat.reorder_categories(list("cba"))
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (3, object): ['c', 'b', 'a']
+
+    >>> s.cat.add_categories(["d", "e"])
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (5, object): ['a', 'b', 'c', 'd', 'e']
+
+    >>> s.cat.remove_categories(["a", "c"])
+    0    NaN
+    1      b
+    2      b
+    3    NaN
+    4    NaN
+    5    NaN
+    dtype: category
+    Categories (1, object): ['b']
+
+    >>> s1 = s.cat.add_categories(["d", "e"])
+    >>> s1.cat.remove_unused_categories()
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (3, object): ['a', 'b', 'c']
+
+    >>> s.cat.set_categories(list("abcde"))
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (5, object): ['a', 'b', 'c', 'd', 'e']
+
+    >>> s.cat.as_ordered()
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (3, object): ['a' < 'b' < 'c']
+
+    >>> s.cat.as_unordered()
+    0    a
+    1    b
+    2    b
+    3    c
+    4    c
+    5    c
+    dtype: category
+    Categories (3, object): ['a', 'b', 'c']
+    """
+
+    def __init__(self, data) -> None:
+        self._validate(data)
+        self._parent = data.values
+        self._index = data.index
+        self._name = data.name
+        self._freeze()
+
+    @staticmethod
+    def _validate(data):
+        if not isinstance(data.dtype, CategoricalDtype):
+            raise AttributeError("Can only use .cat accessor with a 'category' dtype")
+
+    def _delegate_property_get(self, name: str):
+        return getattr(self._parent, name)
+
+    # error: Signature of "_delegate_property_set" incompatible with supertype
+    # "PandasDelegate"
+    def _delegate_property_set(self, name: str, new_values):  # type: ignore[override]
+        return setattr(self._parent, name, new_values)
+
+    @property
+    def codes(self) -> Series:
+        """
+        Return Series of codes as well as the index.
+
+        Examples
+        --------
+        >>> raw_cate = pd.Categorical(["a", "b", "c", "a"], categories=["a", "b"])
+        >>> ser = pd.Series(raw_cate)
+        >>> ser.cat.codes
+        0   0
+        1   1
+        2  -1
+        3   0
+        dtype: int8
+        """
+        from pandas import Series
+
+        return Series(self._parent.codes, index=self._index)
+
+    def _delegate_method(self, name: str, *args, **kwargs):
+        from pandas import Series
+
+        method = getattr(self._parent, name)
+        res = method(*args, **kwargs)
+        if res is not None:
+            return Series(res, index=self._index, name=self._name)
+
+
+# utility routines
+
+
+def _get_codes_for_values(
+    values: Index | Series | ExtensionArray | np.ndarray,
+    categories: Index,
+) -> np.ndarray:
+    """
+    utility routine to turn values into codes given the specified categories
+
+    If `values` is known to be a Categorical, use recode_for_categories instead.
+    """
+    codes = categories.get_indexer_for(values)
+    return coerce_indexer_dtype(codes, categories)
+
+
+def recode_for_categories(
+    codes: np.ndarray, old_categories, new_categories, copy: bool = True
+) -> np.ndarray:
+    """
+    Convert a set of codes for to a new set of categories
+
+    Parameters
+    ----------
+    codes : np.ndarray
+    old_categories, new_categories : Index
+    copy: bool, default True
+        Whether to copy if the codes are unchanged.
+
+    Returns
+    -------
+    new_codes : np.ndarray[np.int64]
+
+    Examples
+    --------
+    >>> old_cat = pd.Index(['b', 'a', 'c'])
+    >>> new_cat = pd.Index(['a', 'b'])
+    >>> codes = np.array([0, 1, 1, 2])
+    >>> recode_for_categories(codes, old_cat, new_cat)
+    array([ 1,  0,  0, -1], dtype=int8)
+    """
+    if len(old_categories) == 0:
+        # All null anyway, so just retain the nulls
+        if copy:
+            return codes.copy()
+        return codes
+    elif new_categories.equals(old_categories):
+        # Same categories, so no need to actually recode
+        if copy:
+            return codes.copy()
+        return codes
+
+    indexer = coerce_indexer_dtype(
+        new_categories.get_indexer_for(old_categories), new_categories
+    )
+    new_codes = take_nd(indexer, codes, fill_value=-1)
+    return new_codes
+
+
+def factorize_from_iterable(values) -> tuple[np.ndarray, Index]:
+    """
+    Factorize an input `values` into `categories` and `codes`. Preserves
+    categorical dtype in `categories`.
+
+    Parameters
+    ----------
+    values : list-like
+
+    Returns
+    -------
+    codes : ndarray
+    categories : Index
+        If `values` has a categorical dtype, then `categories` is
+        a CategoricalIndex keeping the categories and order of `values`.
+    """
+    from pandas import CategoricalIndex
+
+    if not is_list_like(values):
+        raise TypeError("Input must be list-like")
+
+    categories: Index
+
+    vdtype = getattr(values, "dtype", None)
+    if isinstance(vdtype, CategoricalDtype):
+        values = extract_array(values)
+        # The Categorical we want to build has the same categories
+        # as values but its codes are by def [0, ..., len(n_categories) - 1]
+        cat_codes = np.arange(len(values.categories), dtype=values.codes.dtype)
+        cat = Categorical.from_codes(cat_codes, dtype=values.dtype, validate=False)
+
+        categories = CategoricalIndex(cat)
+        codes = values.codes
+    else:
+        # The value of ordered is irrelevant since we don't use cat as such,
+        # but only the resulting categories, the order of which is independent
+        # from ordered. Set ordered to False as default. See GH #15457
+        cat = Categorical(values, ordered=False)
+        categories = cat.categories
+        codes = cat.codes
+    return codes, categories
+
+
+def factorize_from_iterables(iterables) -> tuple[list[np.ndarray], list[Index]]:
+    """
+    A higher-level wrapper over `factorize_from_iterable`.
+
+    Parameters
+    ----------
+    iterables : list-like of list-likes
+
+    Returns
+    -------
+    codes : list of ndarrays
+    categories : list of Indexes
+
+    Notes
+    -----
+    See `factorize_from_iterable` for more info.
+    """
+    if len(iterables) == 0:
+        # For consistency, it should return two empty lists.
+        return [], []
+
+    codes, categories = zip(*(factorize_from_iterable(it) for it in iterables))
+    return list(codes), list(categories)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimelike.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimelike.py
new file mode 100644
index 0000000000000000000000000000000000000000..cfe1f3acd914344d5ec161b40a8cd494f03353dc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimelike.py
@@ -0,0 +1,2583 @@
+from __future__ import annotations
+
+from datetime import (
+    datetime,
+    timedelta,
+)
+from functools import wraps
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    Union,
+    cast,
+    final,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import (
+    algos,
+    lib,
+)
+from pandas._libs.arrays import NDArrayBacked
+from pandas._libs.tslibs import (
+    BaseOffset,
+    IncompatibleFrequency,
+    NaT,
+    NaTType,
+    Period,
+    Resolution,
+    Tick,
+    Timedelta,
+    Timestamp,
+    add_overflowsafe,
+    astype_overflowsafe,
+    get_unit_from_dtype,
+    iNaT,
+    ints_to_pydatetime,
+    ints_to_pytimedelta,
+    periods_per_day,
+    to_offset,
+)
+from pandas._libs.tslibs.fields import (
+    RoundTo,
+    round_nsint64,
+)
+from pandas._libs.tslibs.np_datetime import compare_mismatched_resolutions
+from pandas._libs.tslibs.timedeltas import get_unit_for_round
+from pandas._libs.tslibs.timestamps import integer_op_not_supported
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    DatetimeLikeScalar,
+    Dtype,
+    DtypeObj,
+    F,
+    InterpolateOptions,
+    NpDtype,
+    PositionalIndexer2D,
+    PositionalIndexerTuple,
+    ScalarIndexer,
+    Self,
+    SequenceIndexer,
+    TimeAmbiguous,
+    TimeNonexistent,
+    npt,
+)
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    AbstractMethodError,
+    InvalidComparison,
+    PerformanceWarning,
+)
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    cache_readonly,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
+from pandas.core.dtypes.common import (
+    is_all_strings,
+    is_integer_dtype,
+    is_list_like,
+    is_object_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCCategorical,
+    ABCMultiIndex,
+)
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+)
+
+from pandas.core import (
+    algorithms,
+    missing,
+    nanops,
+    ops,
+)
+from pandas.core.algorithms import (
+    isin,
+    map_array,
+    unique1d,
+)
+from pandas.core.array_algos import datetimelike_accumulations
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays._mixins import (
+    NDArrayBackedExtensionArray,
+    ravel_compat,
+)
+from pandas.core.arrays.arrow.array import ArrowExtensionArray
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.arrays.integer import IntegerArray
+import pandas.core.common as com
+from pandas.core.construction import (
+    array as pd_array,
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import (
+    check_array_indexer,
+    check_setitem_lengths,
+)
+from pandas.core.ops.common import unpack_zerodim_and_defer
+from pandas.core.ops.invalid import (
+    invalid_comparison,
+    make_invalid_op,
+)
+
+from pandas.tseries import frequencies
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterator,
+        Sequence,
+    )
+
+    from pandas import Index
+    from pandas.core.arrays import (
+        DatetimeArray,
+        PeriodArray,
+        TimedeltaArray,
+    )
+
+DTScalarOrNaT = Union[DatetimeLikeScalar, NaTType]
+
+
+def _make_unpacked_invalid_op(op_name: str):
+    op = make_invalid_op(op_name)
+    return unpack_zerodim_and_defer(op_name)(op)
+
+
+def _period_dispatch(meth: F) -> F:
+    """
+    For PeriodArray methods, dispatch to DatetimeArray and re-wrap the results
+    in PeriodArray.  We cannot use ._ndarray directly for the affected
+    methods because the i8 data has different semantics on NaT values.
+    """
+
+    @wraps(meth)
+    def new_meth(self, *args, **kwargs):
+        if not isinstance(self.dtype, PeriodDtype):
+            return meth(self, *args, **kwargs)
+
+        arr = self.view("M8[ns]")
+        result = meth(arr, *args, **kwargs)
+        if result is NaT:
+            return NaT
+        elif isinstance(result, Timestamp):
+            return self._box_func(result._value)
+
+        res_i8 = result.view("i8")
+        return self._from_backing_data(res_i8)
+
+    return cast(F, new_meth)
+
+
+# error: Definition of "_concat_same_type" in base class "NDArrayBacked" is
+# incompatible with definition in base class "ExtensionArray"
+class DatetimeLikeArrayMixin(  # type: ignore[misc]
+    OpsMixin, NDArrayBackedExtensionArray
+):
+    """
+    Shared Base/Mixin class for DatetimeArray, TimedeltaArray, PeriodArray
+
+    Assumes that __new__/__init__ defines:
+        _ndarray
+
+    and that inheriting subclass implements:
+        freq
+    """
+
+    # _infer_matches -> which infer_dtype strings are close enough to our own
+    _infer_matches: tuple[str, ...]
+    _is_recognized_dtype: Callable[[DtypeObj], bool]
+    _recognized_scalars: tuple[type, ...]
+    _ndarray: np.ndarray
+    freq: BaseOffset | None
+
+    @cache_readonly
+    def _can_hold_na(self) -> bool:
+        return True
+
+    def __init__(
+        self, data, dtype: Dtype | None = None, freq=None, copy: bool = False
+    ) -> None:
+        raise AbstractMethodError(self)
+
+    @property
+    def _scalar_type(self) -> type[DatetimeLikeScalar]:
+        """
+        The scalar associated with this datelike
+
+        * PeriodArray : Period
+        * DatetimeArray : Timestamp
+        * TimedeltaArray : Timedelta
+        """
+        raise AbstractMethodError(self)
+
+    def _scalar_from_string(self, value: str) -> DTScalarOrNaT:
+        """
+        Construct a scalar type from a string.
+
+        Parameters
+        ----------
+        value : str
+
+        Returns
+        -------
+        Period, Timestamp, or Timedelta, or NaT
+            Whatever the type of ``self._scalar_type`` is.
+
+        Notes
+        -----
+        This should call ``self._check_compatible_with`` before
+        unboxing the result.
+        """
+        raise AbstractMethodError(self)
+
+    def _unbox_scalar(
+        self, value: DTScalarOrNaT
+    ) -> np.int64 | np.datetime64 | np.timedelta64:
+        """
+        Unbox the integer value of a scalar `value`.
+
+        Parameters
+        ----------
+        value : Period, Timestamp, Timedelta, or NaT
+            Depending on subclass.
+
+        Returns
+        -------
+        int
+
+        Examples
+        --------
+        >>> arr = pd.array(np.array(['1970-01-01'], 'datetime64[ns]'))
+        >>> arr._unbox_scalar(arr[0])
+        numpy.datetime64('1970-01-01T00:00:00.000000000')
+        """
+        raise AbstractMethodError(self)
+
+    def _check_compatible_with(self, other: DTScalarOrNaT) -> None:
+        """
+        Verify that `self` and `other` are compatible.
+
+        * DatetimeArray verifies that the timezones (if any) match
+        * PeriodArray verifies that the freq matches
+        * Timedelta has no verification
+
+        In each case, NaT is considered compatible.
+
+        Parameters
+        ----------
+        other
+
+        Raises
+        ------
+        Exception
+        """
+        raise AbstractMethodError(self)
+
+    # ------------------------------------------------------------------
+
+    def _box_func(self, x):
+        """
+        box function to get object from internal representation
+        """
+        raise AbstractMethodError(self)
+
+    def _box_values(self, values) -> np.ndarray:
+        """
+        apply box func to passed values
+        """
+        return lib.map_infer(values, self._box_func, convert=False)
+
+    def __iter__(self) -> Iterator:
+        if self.ndim > 1:
+            return (self[n] for n in range(len(self)))
+        else:
+            return (self._box_func(v) for v in self.asi8)
+
+    @property
+    def asi8(self) -> npt.NDArray[np.int64]:
+        """
+        Integer representation of the values.
+
+        Returns
+        -------
+        ndarray
+            An ndarray with int64 dtype.
+        """
+        # do not cache or you'll create a memory leak
+        return self._ndarray.view("i8")
+
+    # ----------------------------------------------------------------
+    # Rendering Methods
+
+    def _format_native_types(
+        self, *, na_rep: str | float = "NaT", date_format=None
+    ) -> npt.NDArray[np.object_]:
+        """
+        Helper method for astype when converting to strings.
+
+        Returns
+        -------
+        ndarray[str]
+        """
+        raise AbstractMethodError(self)
+
+    def _formatter(self, boxed: bool = False):
+        # TODO: Remove Datetime & DatetimeTZ formatters.
+        return "'{}'".format
+
+    # ----------------------------------------------------------------
+    # Array-Like / EA-Interface Methods
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        # used for Timedelta/DatetimeArray, overwritten by PeriodArray
+        if is_object_dtype(dtype):
+            if copy is False:
+                warnings.warn(
+                    "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                    "changed and passing 'copy=False' raises an error when returning "
+                    "a zero-copy NumPy array is not possible. pandas will follow this "
+                    "behavior starting with pandas 3.0.\nThis conversion to NumPy "
+                    "requires a copy, but 'copy=False' was passed. Consider using "
+                    "'np.asarray(..)' instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+            return np.array(list(self), dtype=object)
+
+        if copy is True:
+            return np.array(self._ndarray, dtype=dtype)
+        return self._ndarray
+
+    @overload
+    def __getitem__(self, item: ScalarIndexer) -> DTScalarOrNaT:
+        ...
+
+    @overload
+    def __getitem__(
+        self,
+        item: SequenceIndexer | PositionalIndexerTuple,
+    ) -> Self:
+        ...
+
+    def __getitem__(self, key: PositionalIndexer2D) -> Self | DTScalarOrNaT:
+        """
+        This getitem defers to the underlying array, which by-definition can
+        only handle list-likes, slices, and integer scalars
+        """
+        # Use cast as we know we will get back a DatetimeLikeArray or DTScalar,
+        # but skip evaluating the Union at runtime for performance
+        # (see https://github.com/pandas-dev/pandas/pull/44624)
+        result = cast("Union[Self, DTScalarOrNaT]", super().__getitem__(key))
+        if lib.is_scalar(result):
+            return result
+        else:
+            # At this point we know the result is an array.
+            result = cast(Self, result)
+        result._freq = self._get_getitem_freq(key)
+        return result
+
+    def _get_getitem_freq(self, key) -> BaseOffset | None:
+        """
+        Find the `freq` attribute to assign to the result of a __getitem__ lookup.
+        """
+        is_period = isinstance(self.dtype, PeriodDtype)
+        if is_period:
+            freq = self.freq
+        elif self.ndim != 1:
+            freq = None
+        else:
+            key = check_array_indexer(self, key)  # maybe ndarray[bool] -> slice
+            freq = None
+            if isinstance(key, slice):
+                if self.freq is not None and key.step is not None:
+                    freq = key.step * self.freq
+                else:
+                    freq = self.freq
+            elif key is Ellipsis:
+                # GH#21282 indexing with Ellipsis is similar to a full slice,
+                #  should preserve `freq` attribute
+                freq = self.freq
+            elif com.is_bool_indexer(key):
+                new_key = lib.maybe_booleans_to_slice(key.view(np.uint8))
+                if isinstance(new_key, slice):
+                    return self._get_getitem_freq(new_key)
+        return freq
+
+    # error: Argument 1 of "__setitem__" is incompatible with supertype
+    # "ExtensionArray"; supertype defines the argument type as "Union[int,
+    # ndarray]"
+    def __setitem__(
+        self,
+        key: int | Sequence[int] | Sequence[bool] | slice,
+        value: NaTType | Any | Sequence[Any],
+    ) -> None:
+        # I'm fudging the types a bit here. "Any" above really depends
+        # on type(self). For PeriodArray, it's Period (or stuff coercible
+        # to a period in from_sequence). For DatetimeArray, it's Timestamp...
+        # I don't know if mypy can do that, possibly with Generics.
+        # https://mypy.readthedocs.io/en/latest/generics.html
+
+        no_op = check_setitem_lengths(key, value, self)
+
+        # Calling super() before the no_op short-circuit means that we raise
+        #  on invalid 'value' even if this is a no-op, e.g. wrong-dtype empty array.
+        super().__setitem__(key, value)
+
+        if no_op:
+            return
+
+        self._maybe_clear_freq()
+
+    def _maybe_clear_freq(self) -> None:
+        # inplace operations like __setitem__ may invalidate the freq of
+        # DatetimeArray and TimedeltaArray
+        pass
+
+    def astype(self, dtype, copy: bool = True):
+        # Some notes on cases we don't have to handle here in the base class:
+        #   1. PeriodArray.astype handles period -> period
+        #   2. DatetimeArray.astype handles conversion between tz.
+        #   3. DatetimeArray.astype handles datetime -> period
+        dtype = pandas_dtype(dtype)
+
+        if dtype == object:
+            if self.dtype.kind == "M":
+                self = cast("DatetimeArray", self)
+                # *much* faster than self._box_values
+                #  for e.g. test_get_loc_tuple_monotonic_above_size_cutoff
+                i8data = self.asi8
+                converted = ints_to_pydatetime(
+                    i8data,
+                    tz=self.tz,
+                    box="timestamp",
+                    reso=self._creso,
+                )
+                return converted
+
+            elif self.dtype.kind == "m":
+                return ints_to_pytimedelta(self._ndarray, box=True)
+
+            return self._box_values(self.asi8.ravel()).reshape(self.shape)
+
+        elif is_string_dtype(dtype):
+            if isinstance(dtype, ExtensionDtype):
+                arr_object = self._format_native_types(na_rep=dtype.na_value)  # type: ignore[arg-type]
+                cls = dtype.construct_array_type()
+                return cls._from_sequence(arr_object, dtype=dtype, copy=False)
+            else:
+                return self._format_native_types()
+
+        elif isinstance(dtype, ExtensionDtype):
+            return super().astype(dtype, copy=copy)
+        elif dtype.kind in "iu":
+            # we deliberately ignore int32 vs. int64 here.
+            # See https://github.com/pandas-dev/pandas/issues/24381 for more.
+            values = self.asi8
+            if dtype != np.int64:
+                raise TypeError(
+                    f"Converting from {self.dtype} to {dtype} is not supported. "
+                    "Do obj.astype('int64').astype(dtype) instead"
+                )
+
+            if copy:
+                values = values.copy()
+            return values
+        elif (dtype.kind in "mM" and self.dtype != dtype) or dtype.kind == "f":
+            # disallow conversion between datetime/timedelta,
+            # and conversions for any datetimelike to float
+            msg = f"Cannot cast {type(self).__name__} to dtype {dtype}"
+            raise TypeError(msg)
+        else:
+            return np.asarray(self, dtype=dtype)
+
+    @overload
+    def view(self) -> Self:
+        ...
+
+    @overload
+    def view(self, dtype: Literal["M8[ns]"]) -> DatetimeArray:
+        ...
+
+    @overload
+    def view(self, dtype: Literal["m8[ns]"]) -> TimedeltaArray:
+        ...
+
+    @overload
+    def view(self, dtype: Dtype | None = ...) -> ArrayLike:
+        ...
+
+    # pylint: disable-next=useless-parent-delegation
+    def view(self, dtype: Dtype | None = None) -> ArrayLike:
+        # we need to explicitly call super() method as long as the `@overload`s
+        #  are present in this file.
+        return super().view(dtype)
+
+    # ------------------------------------------------------------------
+    # Validation Methods
+    # TODO: try to de-duplicate these, ensure identical behavior
+
+    def _validate_comparison_value(self, other):
+        if isinstance(other, str):
+            try:
+                # GH#18435 strings get a pass from tzawareness compat
+                other = self._scalar_from_string(other)
+            except (ValueError, IncompatibleFrequency):
+                # failed to parse as Timestamp/Timedelta/Period
+                raise InvalidComparison(other)
+
+        if isinstance(other, self._recognized_scalars) or other is NaT:
+            other = self._scalar_type(other)
+            try:
+                self._check_compatible_with(other)
+            except (TypeError, IncompatibleFrequency) as err:
+                # e.g. tzawareness mismatch
+                raise InvalidComparison(other) from err
+
+        elif not is_list_like(other):
+            raise InvalidComparison(other)
+
+        elif len(other) != len(self):
+            raise ValueError("Lengths must match")
+
+        else:
+            try:
+                other = self._validate_listlike(other, allow_object=True)
+                self._check_compatible_with(other)
+            except (TypeError, IncompatibleFrequency) as err:
+                if is_object_dtype(getattr(other, "dtype", None)):
+                    # We will have to operate element-wise
+                    pass
+                else:
+                    raise InvalidComparison(other) from err
+
+        return other
+
+    def _validate_scalar(
+        self,
+        value,
+        *,
+        allow_listlike: bool = False,
+        unbox: bool = True,
+    ):
+        """
+        Validate that the input value can be cast to our scalar_type.
+
+        Parameters
+        ----------
+        value : object
+        allow_listlike: bool, default False
+            When raising an exception, whether the message should say
+            listlike inputs are allowed.
+        unbox : bool, default True
+            Whether to unbox the result before returning.  Note: unbox=False
+            skips the setitem compatibility check.
+
+        Returns
+        -------
+        self._scalar_type or NaT
+        """
+        if isinstance(value, self._scalar_type):
+            pass
+
+        elif isinstance(value, str):
+            # NB: Careful about tzawareness
+            try:
+                value = self._scalar_from_string(value)
+            except ValueError as err:
+                msg = self._validation_error_message(value, allow_listlike)
+                raise TypeError(msg) from err
+
+        elif is_valid_na_for_dtype(value, self.dtype):
+            # GH#18295
+            value = NaT
+
+        elif isna(value):
+            # if we are dt64tz and value is dt64("NaT"), dont cast to NaT,
+            #  or else we'll fail to raise in _unbox_scalar
+            msg = self._validation_error_message(value, allow_listlike)
+            raise TypeError(msg)
+
+        elif isinstance(value, self._recognized_scalars):
+            # error: Argument 1 to "Timestamp" has incompatible type "object"; expected
+            # "integer[Any] | float | str | date | datetime | datetime64"
+            value = self._scalar_type(value)  # type: ignore[arg-type]
+
+        else:
+            msg = self._validation_error_message(value, allow_listlike)
+            raise TypeError(msg)
+
+        if not unbox:
+            # NB: In general NDArrayBackedExtensionArray will unbox here;
+            #  this option exists to prevent a performance hit in
+            #  TimedeltaIndex.get_loc
+            return value
+        return self._unbox_scalar(value)
+
+    def _validation_error_message(self, value, allow_listlike: bool = False) -> str:
+        """
+        Construct an exception message on validation error.
+
+        Some methods allow only scalar inputs, while others allow either scalar
+        or listlike.
+
+        Parameters
+        ----------
+        allow_listlike: bool, default False
+
+        Returns
+        -------
+        str
+        """
+        if hasattr(value, "dtype") and getattr(value, "ndim", 0) > 0:
+            msg_got = f"{value.dtype} array"
+        else:
+            msg_got = f"'{type(value).__name__}'"
+        if allow_listlike:
+            msg = (
+                f"value should be a '{self._scalar_type.__name__}', 'NaT', "
+                f"or array of those. Got {msg_got} instead."
+            )
+        else:
+            msg = (
+                f"value should be a '{self._scalar_type.__name__}' or 'NaT'. "
+                f"Got {msg_got} instead."
+            )
+        return msg
+
+    def _validate_listlike(self, value, allow_object: bool = False):
+        if isinstance(value, type(self)):
+            if self.dtype.kind in "mM" and not allow_object:
+                # error: "DatetimeLikeArrayMixin" has no attribute "as_unit"
+                value = value.as_unit(self.unit, round_ok=False)  # type: ignore[attr-defined]
+            return value
+
+        if isinstance(value, list) and len(value) == 0:
+            # We treat empty list as our own dtype.
+            return type(self)._from_sequence([], dtype=self.dtype)
+
+        if hasattr(value, "dtype") and value.dtype == object:
+            # `array` below won't do inference if value is an Index or Series.
+            #  so do so here.  in the Index case, inferred_type may be cached.
+            if lib.infer_dtype(value) in self._infer_matches:
+                try:
+                    value = type(self)._from_sequence(value)
+                except (ValueError, TypeError):
+                    if allow_object:
+                        return value
+                    msg = self._validation_error_message(value, True)
+                    raise TypeError(msg)
+
+        # Do type inference if necessary up front (after unpacking
+        # NumpyExtensionArray)
+        # e.g. we passed PeriodIndex.values and got an ndarray of Periods
+        value = extract_array(value, extract_numpy=True)
+        value = pd_array(value)
+        value = extract_array(value, extract_numpy=True)
+
+        if is_all_strings(value):
+            # We got a StringArray
+            try:
+                # TODO: Could use from_sequence_of_strings if implemented
+                # Note: passing dtype is necessary for PeriodArray tests
+                value = type(self)._from_sequence(value, dtype=self.dtype)
+            except ValueError:
+                pass
+
+        if isinstance(value.dtype, CategoricalDtype):
+            # e.g. we have a Categorical holding self.dtype
+            if value.categories.dtype == self.dtype:
+                # TODO: do we need equal dtype or just comparable?
+                value = value._internal_get_values()
+                value = extract_array(value, extract_numpy=True)
+
+        if allow_object and is_object_dtype(value.dtype):
+            pass
+
+        elif not type(self)._is_recognized_dtype(value.dtype):
+            msg = self._validation_error_message(value, True)
+            raise TypeError(msg)
+
+        if self.dtype.kind in "mM" and not allow_object:
+            # error: "DatetimeLikeArrayMixin" has no attribute "as_unit"
+            value = value.as_unit(self.unit, round_ok=False)  # type: ignore[attr-defined]
+        return value
+
+    def _validate_setitem_value(self, value):
+        if is_list_like(value):
+            value = self._validate_listlike(value)
+        else:
+            return self._validate_scalar(value, allow_listlike=True)
+
+        return self._unbox(value)
+
+    @final
+    def _unbox(self, other) -> np.int64 | np.datetime64 | np.timedelta64 | np.ndarray:
+        """
+        Unbox either a scalar with _unbox_scalar or an instance of our own type.
+        """
+        if lib.is_scalar(other):
+            other = self._unbox_scalar(other)
+        else:
+            # same type as self
+            self._check_compatible_with(other)
+            other = other._ndarray
+        return other
+
+    # ------------------------------------------------------------------
+    # Additional array methods
+    #  These are not part of the EA API, but we implement them because
+    #  pandas assumes they're there.
+
+    @ravel_compat
+    def map(self, mapper, na_action=None):
+        from pandas import Index
+
+        result = map_array(self, mapper, na_action=na_action)
+        result = Index(result)
+
+        if isinstance(result, ABCMultiIndex):
+            return result.to_numpy()
+        else:
+            return result.array
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        """
+        Compute boolean array of whether each value is found in the
+        passed set of values.
+
+        Parameters
+        ----------
+        values : np.ndarray or ExtensionArray
+
+        Returns
+        -------
+        ndarray[bool]
+        """
+        if values.dtype.kind in "fiuc":
+            # TODO: de-duplicate with equals, validate_comparison_value
+            return np.zeros(self.shape, dtype=bool)
+
+        values = ensure_wrapped_if_datetimelike(values)
+
+        if not isinstance(values, type(self)):
+            inferable = [
+                "timedelta",
+                "timedelta64",
+                "datetime",
+                "datetime64",
+                "date",
+                "period",
+            ]
+            if values.dtype == object:
+                values = lib.maybe_convert_objects(
+                    values,  # type: ignore[arg-type]
+                    convert_non_numeric=True,
+                    dtype_if_all_nat=self.dtype,
+                )
+                if values.dtype != object:
+                    return self.isin(values)
+
+                inferred = lib.infer_dtype(values, skipna=False)
+                if inferred not in inferable:
+                    if inferred == "string":
+                        pass
+
+                    elif "mixed" in inferred:
+                        return isin(self.astype(object), values)
+                    else:
+                        return np.zeros(self.shape, dtype=bool)
+
+            try:
+                values = type(self)._from_sequence(values)
+            except ValueError:
+                return isin(self.astype(object), values)
+            else:
+                warnings.warn(
+                    # GH#53111
+                    f"The behavior of 'isin' with dtype={self.dtype} and "
+                    "castable values (e.g. strings) is deprecated. In a "
+                    "future version, these will not be considered matching "
+                    "by isin. Explicitly cast to the appropriate dtype before "
+                    "calling isin instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        if self.dtype.kind in "mM":
+            self = cast("DatetimeArray | TimedeltaArray", self)
+            # error: Item "ExtensionArray" of "ExtensionArray | ndarray[Any, Any]"
+            # has no attribute "as_unit"
+            values = values.as_unit(self.unit)  # type: ignore[union-attr]
+
+        try:
+            # error: Argument 1 to "_check_compatible_with" of "DatetimeLikeArrayMixin"
+            # has incompatible type "ExtensionArray | ndarray[Any, Any]"; expected
+            # "Period | Timestamp | Timedelta | NaTType"
+            self._check_compatible_with(values)  # type: ignore[arg-type]
+        except (TypeError, ValueError):
+            # Includes tzawareness mismatch and IncompatibleFrequencyError
+            return np.zeros(self.shape, dtype=bool)
+
+        # error: Item "ExtensionArray" of "ExtensionArray | ndarray[Any, Any]"
+        # has no attribute "asi8"
+        return isin(self.asi8, values.asi8)  # type: ignore[union-attr]
+
+    # ------------------------------------------------------------------
+    # Null Handling
+
+    def isna(self) -> npt.NDArray[np.bool_]:
+        return self._isnan
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def _isnan(self) -> npt.NDArray[np.bool_]:
+        """
+        return if each value is nan
+        """
+        return self.asi8 == iNaT
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def _hasna(self) -> bool:
+        """
+        return if I have any nans; enables various perf speedups
+        """
+        return bool(self._isnan.any())
+
+    def _maybe_mask_results(
+        self, result: np.ndarray, fill_value=iNaT, convert=None
+    ) -> np.ndarray:
+        """
+        Parameters
+        ----------
+        result : np.ndarray
+        fill_value : object, default iNaT
+        convert : str, dtype or None
+
+        Returns
+        -------
+        result : ndarray with values replace by the fill_value
+
+        mask the result if needed, convert to the provided dtype if its not
+        None
+
+        This is an internal routine.
+        """
+        if self._hasna:
+            if convert:
+                result = result.astype(convert)
+            if fill_value is None:
+                fill_value = np.nan
+            np.putmask(result, self._isnan, fill_value)
+        return result
+
+    # ------------------------------------------------------------------
+    # Frequency Properties/Methods
+
+    @property
+    def freqstr(self) -> str | None:
+        """
+        Return the frequency object as a string if it's set, otherwise None.
+
+        Examples
+        --------
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00"], freq="D")
+        >>> idx.freqstr
+        'D'
+
+        The frequency can be inferred if there are more than 2 points:
+
+        >>> idx = pd.DatetimeIndex(["2018-01-01", "2018-01-03", "2018-01-05"],
+        ...                        freq="infer")
+        >>> idx.freqstr
+        '2D'
+
+        For PeriodIndex:
+
+        >>> idx = pd.PeriodIndex(["2023-1", "2023-2", "2023-3"], freq="M")
+        >>> idx.freqstr
+        'M'
+        """
+        if self.freq is None:
+            return None
+        return self.freq.freqstr
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def inferred_freq(self) -> str | None:
+        """
+        Tries to return a string representing a frequency generated by infer_freq.
+
+        Returns None if it can't autodetect the frequency.
+
+        Examples
+        --------
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["2018-01-01", "2018-01-03", "2018-01-05"])
+        >>> idx.inferred_freq
+        '2D'
+
+        For TimedeltaIndex:
+
+        >>> tdelta_idx = pd.to_timedelta(["0 days", "10 days", "20 days"])
+        >>> tdelta_idx
+        TimedeltaIndex(['0 days', '10 days', '20 days'],
+                       dtype='timedelta64[ns]', freq=None)
+        >>> tdelta_idx.inferred_freq
+        '10D'
+        """
+        if self.ndim != 1:
+            return None
+        try:
+            return frequencies.infer_freq(self)
+        except ValueError:
+            return None
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def _resolution_obj(self) -> Resolution | None:
+        freqstr = self.freqstr
+        if freqstr is None:
+            return None
+        try:
+            return Resolution.get_reso_from_freqstr(freqstr)
+        except KeyError:
+            return None
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def resolution(self) -> str:
+        """
+        Returns day, hour, minute, second, millisecond or microsecond
+        """
+        # error: Item "None" of "Optional[Any]" has no attribute "attrname"
+        return self._resolution_obj.attrname  # type: ignore[union-attr]
+
+    # monotonicity/uniqueness properties are called via frequencies.infer_freq,
+    #  see GH#23789
+
+    @property
+    def _is_monotonic_increasing(self) -> bool:
+        return algos.is_monotonic(self.asi8, timelike=True)[0]
+
+    @property
+    def _is_monotonic_decreasing(self) -> bool:
+        return algos.is_monotonic(self.asi8, timelike=True)[1]
+
+    @property
+    def _is_unique(self) -> bool:
+        return len(unique1d(self.asi8.ravel("K"))) == self.size
+
+    # ------------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _cmp_method(self, other, op):
+        if self.ndim > 1 and getattr(other, "shape", None) == self.shape:
+            # TODO: handle 2D-like listlikes
+            return op(self.ravel(), other.ravel()).reshape(self.shape)
+
+        try:
+            other = self._validate_comparison_value(other)
+        except InvalidComparison:
+            return invalid_comparison(self, other, op)
+
+        dtype = getattr(other, "dtype", None)
+        if is_object_dtype(dtype):
+            # We have to use comp_method_OBJECT_ARRAY instead of numpy
+            #  comparison otherwise it would raise when comparing to None
+            result = ops.comp_method_OBJECT_ARRAY(
+                op, np.asarray(self.astype(object)), other
+            )
+            return result
+        if other is NaT:
+            if op is operator.ne:
+                result = np.ones(self.shape, dtype=bool)
+            else:
+                result = np.zeros(self.shape, dtype=bool)
+            return result
+
+        if not isinstance(self.dtype, PeriodDtype):
+            self = cast(TimelikeOps, self)
+            if self._creso != other._creso:
+                if not isinstance(other, type(self)):
+                    # i.e. Timedelta/Timestamp, cast to ndarray and let
+                    #  compare_mismatched_resolutions handle broadcasting
+                    try:
+                        # GH#52080 see if we can losslessly cast to shared unit
+                        other = other.as_unit(self.unit, round_ok=False)
+                    except ValueError:
+                        other_arr = np.array(other.asm8)
+                        return compare_mismatched_resolutions(
+                            self._ndarray, other_arr, op
+                        )
+                else:
+                    other_arr = other._ndarray
+                    return compare_mismatched_resolutions(self._ndarray, other_arr, op)
+
+        other_vals = self._unbox(other)
+        # GH#37462 comparison on i8 values is almost 2x faster than M8/m8
+        result = op(self._ndarray.view("i8"), other_vals.view("i8"))
+
+        o_mask = isna(other)
+        mask = self._isnan | o_mask
+        if mask.any():
+            nat_result = op is operator.ne
+            np.putmask(result, mask, nat_result)
+
+        return result
+
+    # pow is invalid for all three subclasses; TimedeltaArray will override
+    #  the multiplication and division ops
+    __pow__ = _make_unpacked_invalid_op("__pow__")
+    __rpow__ = _make_unpacked_invalid_op("__rpow__")
+    __mul__ = _make_unpacked_invalid_op("__mul__")
+    __rmul__ = _make_unpacked_invalid_op("__rmul__")
+    __truediv__ = _make_unpacked_invalid_op("__truediv__")
+    __rtruediv__ = _make_unpacked_invalid_op("__rtruediv__")
+    __floordiv__ = _make_unpacked_invalid_op("__floordiv__")
+    __rfloordiv__ = _make_unpacked_invalid_op("__rfloordiv__")
+    __mod__ = _make_unpacked_invalid_op("__mod__")
+    __rmod__ = _make_unpacked_invalid_op("__rmod__")
+    __divmod__ = _make_unpacked_invalid_op("__divmod__")
+    __rdivmod__ = _make_unpacked_invalid_op("__rdivmod__")
+
+    @final
+    def _get_i8_values_and_mask(
+        self, other
+    ) -> tuple[int | npt.NDArray[np.int64], None | npt.NDArray[np.bool_]]:
+        """
+        Get the int64 values and b_mask to pass to add_overflowsafe.
+        """
+        if isinstance(other, Period):
+            i8values = other.ordinal
+            mask = None
+        elif isinstance(other, (Timestamp, Timedelta)):
+            i8values = other._value
+            mask = None
+        else:
+            # PeriodArray, DatetimeArray, TimedeltaArray
+            mask = other._isnan
+            i8values = other.asi8
+        return i8values, mask
+
+    @final
+    def _get_arithmetic_result_freq(self, other) -> BaseOffset | None:
+        """
+        Check if we can preserve self.freq in addition or subtraction.
+        """
+        # Adding or subtracting a Timedelta/Timestamp scalar is freq-preserving
+        #  whenever self.freq is a Tick
+        if isinstance(self.dtype, PeriodDtype):
+            return self.freq
+        elif not lib.is_scalar(other):
+            return None
+        elif isinstance(self.freq, Tick):
+            # In these cases
+            return self.freq
+        return None
+
+    @final
+    def _add_datetimelike_scalar(self, other) -> DatetimeArray:
+        if not lib.is_np_dtype(self.dtype, "m"):
+            raise TypeError(
+                f"cannot add {type(self).__name__} and {type(other).__name__}"
+            )
+
+        self = cast("TimedeltaArray", self)
+
+        from pandas.core.arrays import DatetimeArray
+        from pandas.core.arrays.datetimes import tz_to_dtype
+
+        assert other is not NaT
+        if isna(other):
+            # i.e. np.datetime64("NaT")
+            # In this case we specifically interpret NaT as a datetime, not
+            # the timedelta interpretation we would get by returning self + NaT
+            result = self._ndarray + NaT.to_datetime64().astype(f"M8[{self.unit}]")
+            # Preserve our resolution
+            return DatetimeArray._simple_new(result, dtype=result.dtype)
+
+        other = Timestamp(other)
+        self, other = self._ensure_matching_resos(other)
+        self = cast("TimedeltaArray", self)
+
+        other_i8, o_mask = self._get_i8_values_and_mask(other)
+        result = add_overflowsafe(self.asi8, np.asarray(other_i8, dtype="i8"))
+        res_values = result.view(f"M8[{self.unit}]")
+
+        dtype = tz_to_dtype(tz=other.tz, unit=self.unit)
+        res_values = result.view(f"M8[{self.unit}]")
+        new_freq = self._get_arithmetic_result_freq(other)
+        return DatetimeArray._simple_new(res_values, dtype=dtype, freq=new_freq)
+
+    @final
+    def _add_datetime_arraylike(self, other: DatetimeArray) -> DatetimeArray:
+        if not lib.is_np_dtype(self.dtype, "m"):
+            raise TypeError(
+                f"cannot add {type(self).__name__} and {type(other).__name__}"
+            )
+
+        # defer to DatetimeArray.__add__
+        return other + self
+
+    @final
+    def _sub_datetimelike_scalar(
+        self, other: datetime | np.datetime64
+    ) -> TimedeltaArray:
+        if self.dtype.kind != "M":
+            raise TypeError(f"cannot subtract a datelike from a {type(self).__name__}")
+
+        self = cast("DatetimeArray", self)
+        # subtract a datetime from myself, yielding a ndarray[timedelta64[ns]]
+
+        if isna(other):
+            # i.e. np.datetime64("NaT")
+            return self - NaT
+
+        ts = Timestamp(other)
+
+        self, ts = self._ensure_matching_resos(ts)
+        return self._sub_datetimelike(ts)
+
+    @final
+    def _sub_datetime_arraylike(self, other: DatetimeArray) -> TimedeltaArray:
+        if self.dtype.kind != "M":
+            raise TypeError(f"cannot subtract a datelike from a {type(self).__name__}")
+
+        if len(self) != len(other):
+            raise ValueError("cannot add indices of unequal length")
+
+        self = cast("DatetimeArray", self)
+
+        self, other = self._ensure_matching_resos(other)
+        return self._sub_datetimelike(other)
+
+    @final
+    def _sub_datetimelike(self, other: Timestamp | DatetimeArray) -> TimedeltaArray:
+        self = cast("DatetimeArray", self)
+
+        from pandas.core.arrays import TimedeltaArray
+
+        try:
+            self._assert_tzawareness_compat(other)
+        except TypeError as err:
+            new_message = str(err).replace("compare", "subtract")
+            raise type(err)(new_message) from err
+
+        other_i8, o_mask = self._get_i8_values_and_mask(other)
+        res_values = add_overflowsafe(self.asi8, np.asarray(-other_i8, dtype="i8"))
+        res_m8 = res_values.view(f"timedelta64[{self.unit}]")
+
+        new_freq = self._get_arithmetic_result_freq(other)
+        new_freq = cast("Tick | None", new_freq)
+        return TimedeltaArray._simple_new(res_m8, dtype=res_m8.dtype, freq=new_freq)
+
+    @final
+    def _add_period(self, other: Period) -> PeriodArray:
+        if not lib.is_np_dtype(self.dtype, "m"):
+            raise TypeError(f"cannot add Period to a {type(self).__name__}")
+
+        # We will wrap in a PeriodArray and defer to the reversed operation
+        from pandas.core.arrays.period import PeriodArray
+
+        i8vals = np.broadcast_to(other.ordinal, self.shape)
+        dtype = PeriodDtype(other.freq)
+        parr = PeriodArray(i8vals, dtype=dtype)
+        return parr + self
+
+    def _add_offset(self, offset):
+        raise AbstractMethodError(self)
+
+    def _add_timedeltalike_scalar(self, other):
+        """
+        Add a delta of a timedeltalike
+
+        Returns
+        -------
+        Same type as self
+        """
+        if isna(other):
+            # i.e np.timedelta64("NaT")
+            new_values = np.empty(self.shape, dtype="i8").view(self._ndarray.dtype)
+            new_values.fill(iNaT)
+            return type(self)._simple_new(new_values, dtype=self.dtype)
+
+        # PeriodArray overrides, so we only get here with DTA/TDA
+        self = cast("DatetimeArray | TimedeltaArray", self)
+        other = Timedelta(other)
+        self, other = self._ensure_matching_resos(other)
+        return self._add_timedeltalike(other)
+
+    def _add_timedelta_arraylike(self, other: TimedeltaArray):
+        """
+        Add a delta of a TimedeltaIndex
+
+        Returns
+        -------
+        Same type as self
+        """
+        # overridden by PeriodArray
+
+        if len(self) != len(other):
+            raise ValueError("cannot add indices of unequal length")
+
+        self = cast("DatetimeArray | TimedeltaArray", self)
+
+        self, other = self._ensure_matching_resos(other)
+        return self._add_timedeltalike(other)
+
+    @final
+    def _add_timedeltalike(self, other: Timedelta | TimedeltaArray):
+        self = cast("DatetimeArray | TimedeltaArray", self)
+
+        other_i8, o_mask = self._get_i8_values_and_mask(other)
+        new_values = add_overflowsafe(self.asi8, np.asarray(other_i8, dtype="i8"))
+        res_values = new_values.view(self._ndarray.dtype)
+
+        new_freq = self._get_arithmetic_result_freq(other)
+
+        # error: Argument "dtype" to "_simple_new" of "DatetimeArray" has
+        # incompatible type "Union[dtype[datetime64], DatetimeTZDtype,
+        # dtype[timedelta64]]"; expected "Union[dtype[datetime64], DatetimeTZDtype]"
+        return type(self)._simple_new(
+            res_values, dtype=self.dtype, freq=new_freq  # type: ignore[arg-type]
+        )
+
+    @final
+    def _add_nat(self):
+        """
+        Add pd.NaT to self
+        """
+        if isinstance(self.dtype, PeriodDtype):
+            raise TypeError(
+                f"Cannot add {type(self).__name__} and {type(NaT).__name__}"
+            )
+        self = cast("TimedeltaArray | DatetimeArray", self)
+
+        # GH#19124 pd.NaT is treated like a timedelta for both timedelta
+        # and datetime dtypes
+        result = np.empty(self.shape, dtype=np.int64)
+        result.fill(iNaT)
+        result = result.view(self._ndarray.dtype)  # preserve reso
+        # error: Argument "dtype" to "_simple_new" of "DatetimeArray" has
+        # incompatible type "Union[dtype[timedelta64], dtype[datetime64],
+        # DatetimeTZDtype]"; expected "Union[dtype[datetime64], DatetimeTZDtype]"
+        return type(self)._simple_new(
+            result, dtype=self.dtype, freq=None  # type: ignore[arg-type]
+        )
+
+    @final
+    def _sub_nat(self):
+        """
+        Subtract pd.NaT from self
+        """
+        # GH#19124 Timedelta - datetime is not in general well-defined.
+        # We make an exception for pd.NaT, which in this case quacks
+        # like a timedelta.
+        # For datetime64 dtypes by convention we treat NaT as a datetime, so
+        # this subtraction returns a timedelta64 dtype.
+        # For period dtype, timedelta64 is a close-enough return dtype.
+        result = np.empty(self.shape, dtype=np.int64)
+        result.fill(iNaT)
+        if self.dtype.kind in "mM":
+            # We can retain unit in dtype
+            self = cast("DatetimeArray| TimedeltaArray", self)
+            return result.view(f"timedelta64[{self.unit}]")
+        else:
+            return result.view("timedelta64[ns]")
+
+    @final
+    def _sub_periodlike(self, other: Period | PeriodArray) -> npt.NDArray[np.object_]:
+        # If the operation is well-defined, we return an object-dtype ndarray
+        # of DateOffsets.  Null entries are filled with pd.NaT
+        if not isinstance(self.dtype, PeriodDtype):
+            raise TypeError(
+                f"cannot subtract {type(other).__name__} from {type(self).__name__}"
+            )
+
+        self = cast("PeriodArray", self)
+        self._check_compatible_with(other)
+
+        other_i8, o_mask = self._get_i8_values_and_mask(other)
+        new_i8_data = add_overflowsafe(self.asi8, np.asarray(-other_i8, dtype="i8"))
+        new_data = np.array([self.freq.base * x for x in new_i8_data])
+
+        if o_mask is None:
+            # i.e. Period scalar
+            mask = self._isnan
+        else:
+            # i.e. PeriodArray
+            mask = self._isnan | o_mask
+        new_data[mask] = NaT
+        return new_data
+
+    @final
+    def _addsub_object_array(self, other: npt.NDArray[np.object_], op):
+        """
+        Add or subtract array-like of DateOffset objects
+
+        Parameters
+        ----------
+        other : np.ndarray[object]
+        op : {operator.add, operator.sub}
+
+        Returns
+        -------
+        np.ndarray[object]
+            Except in fastpath case with length 1 where we operate on the
+            contained scalar.
+        """
+        assert op in [operator.add, operator.sub]
+        if len(other) == 1 and self.ndim == 1:
+            # Note: without this special case, we could annotate return type
+            #  as ndarray[object]
+            # If both 1D then broadcasting is unambiguous
+            return op(self, other[0])
+
+        warnings.warn(
+            "Adding/subtracting object-dtype array to "
+            f"{type(self).__name__} not vectorized.",
+            PerformanceWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        # Caller is responsible for broadcasting if necessary
+        assert self.shape == other.shape, (self.shape, other.shape)
+
+        res_values = op(self.astype("O"), np.asarray(other))
+        return res_values
+
+    def _accumulate(self, name: str, *, skipna: bool = True, **kwargs) -> Self:
+        if name not in {"cummin", "cummax"}:
+            raise TypeError(f"Accumulation {name} not supported for {type(self)}")
+
+        op = getattr(datetimelike_accumulations, name)
+        result = op(self.copy(), skipna=skipna, **kwargs)
+
+        return type(self)._simple_new(result, dtype=self.dtype)
+
+    @unpack_zerodim_and_defer("__add__")
+    def __add__(self, other):
+        other_dtype = getattr(other, "dtype", None)
+        other = ensure_wrapped_if_datetimelike(other)
+
+        # scalar others
+        if other is NaT:
+            result = self._add_nat()
+        elif isinstance(other, (Tick, timedelta, np.timedelta64)):
+            result = self._add_timedeltalike_scalar(other)
+        elif isinstance(other, BaseOffset):
+            # specifically _not_ a Tick
+            result = self._add_offset(other)
+        elif isinstance(other, (datetime, np.datetime64)):
+            result = self._add_datetimelike_scalar(other)
+        elif isinstance(other, Period) and lib.is_np_dtype(self.dtype, "m"):
+            result = self._add_period(other)
+        elif lib.is_integer(other):
+            # This check must come after the check for np.timedelta64
+            # as is_integer returns True for these
+            if not isinstance(self.dtype, PeriodDtype):
+                raise integer_op_not_supported(self)
+            obj = cast("PeriodArray", self)
+            result = obj._addsub_int_array_or_scalar(other * obj.dtype._n, operator.add)
+
+        # array-like others
+        elif lib.is_np_dtype(other_dtype, "m"):
+            # TimedeltaIndex, ndarray[timedelta64]
+            result = self._add_timedelta_arraylike(other)
+        elif is_object_dtype(other_dtype):
+            # e.g. Array/Index of DateOffset objects
+            result = self._addsub_object_array(other, operator.add)
+        elif lib.is_np_dtype(other_dtype, "M") or isinstance(
+            other_dtype, DatetimeTZDtype
+        ):
+            # DatetimeIndex, ndarray[datetime64]
+            return self._add_datetime_arraylike(other)
+        elif is_integer_dtype(other_dtype):
+            if not isinstance(self.dtype, PeriodDtype):
+                raise integer_op_not_supported(self)
+            obj = cast("PeriodArray", self)
+            result = obj._addsub_int_array_or_scalar(other * obj.dtype._n, operator.add)
+        else:
+            # Includes Categorical, other ExtensionArrays
+            # For PeriodDtype, if self is a TimedeltaArray and other is a
+            #  PeriodArray with  a timedelta-like (i.e. Tick) freq, this
+            #  operation is valid.  Defer to the PeriodArray implementation.
+            #  In remaining cases, this will end up raising TypeError.
+            return NotImplemented
+
+        if isinstance(result, np.ndarray) and lib.is_np_dtype(result.dtype, "m"):
+            from pandas.core.arrays import TimedeltaArray
+
+            return TimedeltaArray._from_sequence(result)
+        return result
+
+    def __radd__(self, other):
+        # alias for __add__
+        return self.__add__(other)
+
+    @unpack_zerodim_and_defer("__sub__")
+    def __sub__(self, other):
+        other_dtype = getattr(other, "dtype", None)
+        other = ensure_wrapped_if_datetimelike(other)
+
+        # scalar others
+        if other is NaT:
+            result = self._sub_nat()
+        elif isinstance(other, (Tick, timedelta, np.timedelta64)):
+            result = self._add_timedeltalike_scalar(-other)
+        elif isinstance(other, BaseOffset):
+            # specifically _not_ a Tick
+            result = self._add_offset(-other)
+        elif isinstance(other, (datetime, np.datetime64)):
+            result = self._sub_datetimelike_scalar(other)
+        elif lib.is_integer(other):
+            # This check must come after the check for np.timedelta64
+            # as is_integer returns True for these
+            if not isinstance(self.dtype, PeriodDtype):
+                raise integer_op_not_supported(self)
+            obj = cast("PeriodArray", self)
+            result = obj._addsub_int_array_or_scalar(other * obj.dtype._n, operator.sub)
+
+        elif isinstance(other, Period):
+            result = self._sub_periodlike(other)
+
+        # array-like others
+        elif lib.is_np_dtype(other_dtype, "m"):
+            # TimedeltaIndex, ndarray[timedelta64]
+            result = self._add_timedelta_arraylike(-other)
+        elif is_object_dtype(other_dtype):
+            # e.g. Array/Index of DateOffset objects
+            result = self._addsub_object_array(other, operator.sub)
+        elif lib.is_np_dtype(other_dtype, "M") or isinstance(
+            other_dtype, DatetimeTZDtype
+        ):
+            # DatetimeIndex, ndarray[datetime64]
+            result = self._sub_datetime_arraylike(other)
+        elif isinstance(other_dtype, PeriodDtype):
+            # PeriodIndex
+            result = self._sub_periodlike(other)
+        elif is_integer_dtype(other_dtype):
+            if not isinstance(self.dtype, PeriodDtype):
+                raise integer_op_not_supported(self)
+            obj = cast("PeriodArray", self)
+            result = obj._addsub_int_array_or_scalar(other * obj.dtype._n, operator.sub)
+        else:
+            # Includes ExtensionArrays, float_dtype
+            return NotImplemented
+
+        if isinstance(result, np.ndarray) and lib.is_np_dtype(result.dtype, "m"):
+            from pandas.core.arrays import TimedeltaArray
+
+            return TimedeltaArray._from_sequence(result)
+        return result
+
+    def __rsub__(self, other):
+        other_dtype = getattr(other, "dtype", None)
+        other_is_dt64 = lib.is_np_dtype(other_dtype, "M") or isinstance(
+            other_dtype, DatetimeTZDtype
+        )
+
+        if other_is_dt64 and lib.is_np_dtype(self.dtype, "m"):
+            # ndarray[datetime64] cannot be subtracted from self, so
+            # we need to wrap in DatetimeArray/Index and flip the operation
+            if lib.is_scalar(other):
+                # i.e. np.datetime64 object
+                return Timestamp(other) - self
+            if not isinstance(other, DatetimeLikeArrayMixin):
+                # Avoid down-casting DatetimeIndex
+                from pandas.core.arrays import DatetimeArray
+
+                other = DatetimeArray._from_sequence(other)
+            return other - self
+        elif self.dtype.kind == "M" and hasattr(other, "dtype") and not other_is_dt64:
+            # GH#19959 datetime - datetime is well-defined as timedelta,
+            # but any other type - datetime is not well-defined.
+            raise TypeError(
+                f"cannot subtract {type(self).__name__} from {type(other).__name__}"
+            )
+        elif isinstance(self.dtype, PeriodDtype) and lib.is_np_dtype(other_dtype, "m"):
+            # TODO: Can we simplify/generalize these cases at all?
+            raise TypeError(f"cannot subtract {type(self).__name__} from {other.dtype}")
+        elif lib.is_np_dtype(self.dtype, "m"):
+            self = cast("TimedeltaArray", self)
+            return (-self) + other
+
+        # We get here with e.g. datetime objects
+        return -(self - other)
+
+    def __iadd__(self, other) -> Self:
+        result = self + other
+        self[:] = result[:]
+
+        if not isinstance(self.dtype, PeriodDtype):
+            # restore freq, which is invalidated by setitem
+            self._freq = result.freq
+        return self
+
+    def __isub__(self, other) -> Self:
+        result = self - other
+        self[:] = result[:]
+
+        if not isinstance(self.dtype, PeriodDtype):
+            # restore freq, which is invalidated by setitem
+            self._freq = result.freq
+        return self
+
+    # --------------------------------------------------------------
+    # Reductions
+
+    @_period_dispatch
+    def _quantile(
+        self,
+        qs: npt.NDArray[np.float64],
+        interpolation: str,
+    ) -> Self:
+        return super()._quantile(qs=qs, interpolation=interpolation)
+
+    @_period_dispatch
+    def min(self, *, axis: AxisInt | None = None, skipna: bool = True, **kwargs):
+        """
+        Return the minimum value of the Array or minimum along
+        an axis.
+
+        See Also
+        --------
+        numpy.ndarray.min
+        Index.min : Return the minimum value in an Index.
+        Series.min : Return the minimum value in a Series.
+        """
+        nv.validate_min((), kwargs)
+        nv.validate_minmax_axis(axis, self.ndim)
+
+        result = nanops.nanmin(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    @_period_dispatch
+    def max(self, *, axis: AxisInt | None = None, skipna: bool = True, **kwargs):
+        """
+        Return the maximum value of the Array or maximum along
+        an axis.
+
+        See Also
+        --------
+        numpy.ndarray.max
+        Index.max : Return the maximum value in an Index.
+        Series.max : Return the maximum value in a Series.
+        """
+        nv.validate_max((), kwargs)
+        nv.validate_minmax_axis(axis, self.ndim)
+
+        result = nanops.nanmax(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def mean(self, *, skipna: bool = True, axis: AxisInt | None = 0):
+        """
+        Return the mean value of the Array.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Whether to ignore any NaT elements.
+        axis : int, optional, default 0
+
+        Returns
+        -------
+        scalar
+            Timestamp or Timedelta.
+
+        See Also
+        --------
+        numpy.ndarray.mean : Returns the average of array elements along a given axis.
+        Series.mean : Return the mean value in a Series.
+
+        Notes
+        -----
+        mean is only defined for Datetime and Timedelta dtypes, not for Period.
+
+        Examples
+        --------
+        For :class:`pandas.DatetimeIndex`:
+
+        >>> idx = pd.date_range('2001-01-01 00:00', periods=3)
+        >>> idx
+        DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'],
+                      dtype='datetime64[ns]', freq='D')
+        >>> idx.mean()
+        Timestamp('2001-01-02 00:00:00')
+
+        For :class:`pandas.TimedeltaIndex`:
+
+        >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='D')
+        >>> tdelta_idx
+        TimedeltaIndex(['1 days', '2 days', '3 days'],
+                        dtype='timedelta64[ns]', freq=None)
+        >>> tdelta_idx.mean()
+        Timedelta('2 days 00:00:00')
+        """
+        if isinstance(self.dtype, PeriodDtype):
+            # See discussion in GH#24757
+            raise TypeError(
+                f"mean is not implemented for {type(self).__name__} since the "
+                "meaning is ambiguous.  An alternative is "
+                "obj.to_timestamp(how='start').mean()"
+            )
+
+        result = nanops.nanmean(
+            self._ndarray, axis=axis, skipna=skipna, mask=self.isna()
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    @_period_dispatch
+    def median(self, *, axis: AxisInt | None = None, skipna: bool = True, **kwargs):
+        nv.validate_median((), kwargs)
+
+        if axis is not None and abs(axis) >= self.ndim:
+            raise ValueError("abs(axis) must be less than ndim")
+
+        result = nanops.nanmedian(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def _mode(self, dropna: bool = True):
+        mask = None
+        if dropna:
+            mask = self.isna()
+
+        i8modes = algorithms.mode(self.view("i8"), mask=mask)
+        npmodes = i8modes.view(self._ndarray.dtype)
+        npmodes = cast(np.ndarray, npmodes)
+        return self._from_backing_data(npmodes)
+
+    # ------------------------------------------------------------------
+    # GroupBy Methods
+
+    def _groupby_op(
+        self,
+        *,
+        how: str,
+        has_dropped_na: bool,
+        min_count: int,
+        ngroups: int,
+        ids: npt.NDArray[np.intp],
+        **kwargs,
+    ):
+        dtype = self.dtype
+        if dtype.kind == "M":
+            # Adding/multiplying datetimes is not valid
+            if how in ["sum", "prod", "cumsum", "cumprod", "var", "skew"]:
+                raise TypeError(f"datetime64 type does not support {how} operations")
+            if how in ["any", "all"]:
+                # GH#34479
+                warnings.warn(
+                    f"'{how}' with datetime64 dtypes is deprecated and will raise in a "
+                    f"future version. Use (obj != pd.Timestamp(0)).{how}() instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        elif isinstance(dtype, PeriodDtype):
+            # Adding/multiplying Periods is not valid
+            if how in ["sum", "prod", "cumsum", "cumprod", "var", "skew"]:
+                raise TypeError(f"Period type does not support {how} operations")
+            if how in ["any", "all"]:
+                # GH#34479
+                warnings.warn(
+                    f"'{how}' with PeriodDtype is deprecated and will raise in a "
+                    f"future version. Use (obj != pd.Period(0, freq)).{how}() instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            # timedeltas we can add but not multiply
+            if how in ["prod", "cumprod", "skew", "var"]:
+                raise TypeError(f"timedelta64 type does not support {how} operations")
+
+        # All of the functions implemented here are ordinal, so we can
+        #  operate on the tz-naive equivalents
+        npvalues = self._ndarray.view("M8[ns]")
+
+        from pandas.core.groupby.ops import WrappedCythonOp
+
+        kind = WrappedCythonOp.get_kind_from_how(how)
+        op = WrappedCythonOp(how=how, kind=kind, has_dropped_na=has_dropped_na)
+
+        res_values = op._cython_op_ndim_compat(
+            npvalues,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=ids,
+            mask=None,
+            **kwargs,
+        )
+
+        if op.how in op.cast_blocklist:
+            # i.e. how in ["rank"], since other cast_blocklist methods don't go
+            #  through cython_operation
+            return res_values
+
+        # We did a view to M8[ns] above, now we go the other direction
+        assert res_values.dtype == "M8[ns]"
+        if how in ["std", "sem"]:
+            from pandas.core.arrays import TimedeltaArray
+
+            if isinstance(self.dtype, PeriodDtype):
+                raise TypeError("'std' and 'sem' are not valid for PeriodDtype")
+            self = cast("DatetimeArray | TimedeltaArray", self)
+            new_dtype = f"m8[{self.unit}]"
+            res_values = res_values.view(new_dtype)
+            return TimedeltaArray._simple_new(res_values, dtype=res_values.dtype)
+
+        res_values = res_values.view(self._ndarray.dtype)
+        return self._from_backing_data(res_values)
+
+
+class DatelikeOps(DatetimeLikeArrayMixin):
+    """
+    Common ops for DatetimeIndex/PeriodIndex, but not TimedeltaIndex.
+    """
+
+    @Substitution(
+        URL="https://docs.python.org/3/library/datetime.html"
+        "#strftime-and-strptime-behavior"
+    )
+    def strftime(self, date_format: str) -> npt.NDArray[np.object_]:
+        """
+        Convert to Index using specified date_format.
+
+        Return an Index of formatted strings specified by date_format, which
+        supports the same string format as the python standard library. Details
+        of the string format can be found in `python string format
+        doc <%(URL)s>`__.
+
+        Formats supported by the C `strftime` API but not by the python string format
+        doc (such as `"%%R"`, `"%%r"`) are not officially supported and should be
+        preferably replaced with their supported equivalents (such as `"%%H:%%M"`,
+        `"%%I:%%M:%%S %%p"`).
+
+        Note that `PeriodIndex` support additional directives, detailed in
+        `Period.strftime`.
+
+        Parameters
+        ----------
+        date_format : str
+            Date format string (e.g. "%%Y-%%m-%%d").
+
+        Returns
+        -------
+        ndarray[object]
+            NumPy ndarray of formatted strings.
+
+        See Also
+        --------
+        to_datetime : Convert the given argument to datetime.
+        DatetimeIndex.normalize : Return DatetimeIndex with times to midnight.
+        DatetimeIndex.round : Round the DatetimeIndex to the specified freq.
+        DatetimeIndex.floor : Floor the DatetimeIndex to the specified freq.
+        Timestamp.strftime : Format a single Timestamp.
+        Period.strftime : Format a single Period.
+
+        Examples
+        --------
+        >>> rng = pd.date_range(pd.Timestamp("2018-03-10 09:00"),
+        ...                     periods=3, freq='s')
+        >>> rng.strftime('%%B %%d, %%Y, %%r')
+        Index(['March 10, 2018, 09:00:00 AM', 'March 10, 2018, 09:00:01 AM',
+               'March 10, 2018, 09:00:02 AM'],
+              dtype='object')
+        """
+        result = self._format_native_types(date_format=date_format, na_rep=np.nan)
+        if using_string_dtype():
+            from pandas import StringDtype
+
+            return pd_array(result, dtype=StringDtype(na_value=np.nan))  # type: ignore[return-value]
+        return result.astype(object, copy=False)
+
+
+_round_doc = """
+    Perform {op} operation on the data to the specified `freq`.
+
+    Parameters
+    ----------
+    freq : str or Offset
+        The frequency level to {op} the index to. Must be a fixed
+        frequency like 'S' (second) not 'ME' (month end). See
+        :ref:`frequency aliases ` for
+        a list of possible `freq` values.
+    ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
+        Only relevant for DatetimeIndex:
+
+        - 'infer' will attempt to infer fall dst-transition hours based on
+          order
+        - bool-ndarray where True signifies a DST time, False designates
+          a non-DST time (note that this flag is only applicable for
+          ambiguous times)
+        - 'NaT' will return NaT where there are ambiguous times
+        - 'raise' will raise an AmbiguousTimeError if there are ambiguous
+          times.
+
+    nonexistent : 'shift_forward', 'shift_backward', 'NaT', timedelta, default 'raise'
+        A nonexistent time does not exist in a particular timezone
+        where clocks moved forward due to DST.
+
+        - 'shift_forward' will shift the nonexistent time forward to the
+          closest existing time
+        - 'shift_backward' will shift the nonexistent time backward to the
+          closest existing time
+        - 'NaT' will return NaT where there are nonexistent times
+        - timedelta objects will shift nonexistent times by the timedelta
+        - 'raise' will raise an NonExistentTimeError if there are
+          nonexistent times.
+
+    Returns
+    -------
+    DatetimeIndex, TimedeltaIndex, or Series
+        Index of the same type for a DatetimeIndex or TimedeltaIndex,
+        or a Series with the same index for a Series.
+
+    Raises
+    ------
+    ValueError if the `freq` cannot be converted.
+
+    Notes
+    -----
+    If the timestamps have a timezone, {op}ing will take place relative to the
+    local ("wall") time and re-localized to the same timezone. When {op}ing
+    near daylight savings time, use ``nonexistent`` and ``ambiguous`` to
+    control the re-localization behavior.
+
+    Examples
+    --------
+    **DatetimeIndex**
+
+    >>> rng = pd.date_range('1/1/2018 11:59:00', periods=3, freq='min')
+    >>> rng
+    DatetimeIndex(['2018-01-01 11:59:00', '2018-01-01 12:00:00',
+                   '2018-01-01 12:01:00'],
+                  dtype='datetime64[ns]', freq='min')
+    """
+
+_round_example = """>>> rng.round('h')
+    DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
+                   '2018-01-01 12:00:00'],
+                  dtype='datetime64[ns]', freq=None)
+
+    **Series**
+
+    >>> pd.Series(rng).dt.round("h")
+    0   2018-01-01 12:00:00
+    1   2018-01-01 12:00:00
+    2   2018-01-01 12:00:00
+    dtype: datetime64[ns]
+
+    When rounding near a daylight savings time transition, use ``ambiguous`` or
+    ``nonexistent`` to control how the timestamp should be re-localized.
+
+    >>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
+
+    >>> rng_tz.floor("2h", ambiguous=False)
+    DatetimeIndex(['2021-10-31 02:00:00+01:00'],
+                  dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+
+    >>> rng_tz.floor("2h", ambiguous=True)
+    DatetimeIndex(['2021-10-31 02:00:00+02:00'],
+                  dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+    """
+
+_floor_example = """>>> rng.floor('h')
+    DatetimeIndex(['2018-01-01 11:00:00', '2018-01-01 12:00:00',
+                   '2018-01-01 12:00:00'],
+                  dtype='datetime64[ns]', freq=None)
+
+    **Series**
+
+    >>> pd.Series(rng).dt.floor("h")
+    0   2018-01-01 11:00:00
+    1   2018-01-01 12:00:00
+    2   2018-01-01 12:00:00
+    dtype: datetime64[ns]
+
+    When rounding near a daylight savings time transition, use ``ambiguous`` or
+    ``nonexistent`` to control how the timestamp should be re-localized.
+
+    >>> rng_tz = pd.DatetimeIndex(["2021-10-31 03:30:00"], tz="Europe/Amsterdam")
+
+    >>> rng_tz.floor("2h", ambiguous=False)
+    DatetimeIndex(['2021-10-31 02:00:00+01:00'],
+                 dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+
+    >>> rng_tz.floor("2h", ambiguous=True)
+    DatetimeIndex(['2021-10-31 02:00:00+02:00'],
+                  dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+    """
+
+_ceil_example = """>>> rng.ceil('h')
+    DatetimeIndex(['2018-01-01 12:00:00', '2018-01-01 12:00:00',
+                   '2018-01-01 13:00:00'],
+                  dtype='datetime64[ns]', freq=None)
+
+    **Series**
+
+    >>> pd.Series(rng).dt.ceil("h")
+    0   2018-01-01 12:00:00
+    1   2018-01-01 12:00:00
+    2   2018-01-01 13:00:00
+    dtype: datetime64[ns]
+
+    When rounding near a daylight savings time transition, use ``ambiguous`` or
+    ``nonexistent`` to control how the timestamp should be re-localized.
+
+    >>> rng_tz = pd.DatetimeIndex(["2021-10-31 01:30:00"], tz="Europe/Amsterdam")
+
+    >>> rng_tz.ceil("h", ambiguous=False)
+    DatetimeIndex(['2021-10-31 02:00:00+01:00'],
+                  dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+
+    >>> rng_tz.ceil("h", ambiguous=True)
+    DatetimeIndex(['2021-10-31 02:00:00+02:00'],
+                  dtype='datetime64[ns, Europe/Amsterdam]', freq=None)
+    """
+
+
+class TimelikeOps(DatetimeLikeArrayMixin):
+    """
+    Common ops for TimedeltaIndex/DatetimeIndex, but not PeriodIndex.
+    """
+
+    _default_dtype: np.dtype
+
+    def __init__(
+        self, values, dtype=None, freq=lib.no_default, copy: bool = False
+    ) -> None:
+        warnings.warn(
+            # GH#55623
+            f"{type(self).__name__}.__init__ is deprecated and will be "
+            "removed in a future version. Use pd.array instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        values = extract_array(values, extract_numpy=True)
+        if isinstance(values, IntegerArray):
+            values = values.to_numpy("int64", na_value=iNaT)
+
+        inferred_freq = getattr(values, "_freq", None)
+        explicit_none = freq is None
+        freq = freq if freq is not lib.no_default else None
+
+        if isinstance(values, type(self)):
+            if explicit_none:
+                # don't inherit from values
+                pass
+            elif freq is None:
+                freq = values.freq
+            elif freq and values.freq:
+                freq = to_offset(freq)
+                freq = _validate_inferred_freq(freq, values.freq)
+
+            if dtype is not None and dtype != values.dtype:
+                # TODO: we only have tests for this for DTA, not TDA (2022-07-01)
+                raise TypeError(
+                    f"dtype={dtype} does not match data dtype {values.dtype}"
+                )
+
+            dtype = values.dtype
+            values = values._ndarray
+
+        elif dtype is None:
+            if isinstance(values, np.ndarray) and values.dtype.kind in "Mm":
+                dtype = values.dtype
+            else:
+                dtype = self._default_dtype
+                if isinstance(values, np.ndarray) and values.dtype == "i8":
+                    values = values.view(dtype)
+
+        if not isinstance(values, np.ndarray):
+            raise ValueError(
+                f"Unexpected type '{type(values).__name__}'. 'values' must be a "
+                f"{type(self).__name__}, ndarray, or Series or Index "
+                "containing one of those."
+            )
+        if values.ndim not in [1, 2]:
+            raise ValueError("Only 1-dimensional input arrays are supported.")
+
+        if values.dtype == "i8":
+            # for compat with datetime/timedelta/period shared methods,
+            #  we can sometimes get here with int64 values.  These represent
+            #  nanosecond UTC (or tz-naive) unix timestamps
+            if dtype is None:
+                dtype = self._default_dtype
+                values = values.view(self._default_dtype)
+            elif lib.is_np_dtype(dtype, "mM"):
+                values = values.view(dtype)
+            elif isinstance(dtype, DatetimeTZDtype):
+                kind = self._default_dtype.kind
+                new_dtype = f"{kind}8[{dtype.unit}]"
+                values = values.view(new_dtype)
+
+        dtype = self._validate_dtype(values, dtype)
+
+        if freq == "infer":
+            raise ValueError(
+                f"Frequency inference not allowed in {type(self).__name__}.__init__. "
+                "Use 'pd.array()' instead."
+            )
+
+        if copy:
+            values = values.copy()
+        if freq:
+            freq = to_offset(freq)
+            if values.dtype.kind == "m" and not isinstance(freq, Tick):
+                raise TypeError("TimedeltaArray/Index freq must be a Tick")
+
+        NDArrayBacked.__init__(self, values=values, dtype=dtype)
+        self._freq = freq
+
+        if inferred_freq is None and freq is not None:
+            type(self)._validate_frequency(self, freq)
+
+    @classmethod
+    def _validate_dtype(cls, values, dtype):
+        raise AbstractMethodError(cls)
+
+    @property
+    def freq(self):
+        """
+        Return the frequency object if it is set, otherwise None.
+        """
+        return self._freq
+
+    @freq.setter
+    def freq(self, value) -> None:
+        if value is not None:
+            value = to_offset(value)
+            self._validate_frequency(self, value)
+            if self.dtype.kind == "m" and not isinstance(value, Tick):
+                raise TypeError("TimedeltaArray/Index freq must be a Tick")
+
+            if self.ndim > 1:
+                raise ValueError("Cannot set freq with ndim > 1")
+
+        self._freq = value
+
+    @final
+    def _maybe_pin_freq(self, freq, validate_kwds: dict):
+        """
+        Constructor helper to pin the appropriate `freq` attribute.  Assumes
+        that self._freq is currently set to any freq inferred in
+        _from_sequence_not_strict.
+        """
+        if freq is None:
+            # user explicitly passed None -> override any inferred_freq
+            self._freq = None
+        elif freq == "infer":
+            # if self._freq is *not* None then we already inferred a freq
+            #  and there is nothing left to do
+            if self._freq is None:
+                # Set _freq directly to bypass duplicative _validate_frequency
+                # check.
+                self._freq = to_offset(self.inferred_freq)
+        elif freq is lib.no_default:
+            # user did not specify anything, keep inferred freq if the original
+            #  data had one, otherwise do nothing
+            pass
+        elif self._freq is None:
+            # We cannot inherit a freq from the data, so we need to validate
+            #  the user-passed freq
+            freq = to_offset(freq)
+            type(self)._validate_frequency(self, freq, **validate_kwds)
+            self._freq = freq
+        else:
+            # Otherwise we just need to check that the user-passed freq
+            #  doesn't conflict with the one we already have.
+            freq = to_offset(freq)
+            _validate_inferred_freq(freq, self._freq)
+
+    @final
+    @classmethod
+    def _validate_frequency(cls, index, freq: BaseOffset, **kwargs):
+        """
+        Validate that a frequency is compatible with the values of a given
+        Datetime Array/Index or Timedelta Array/Index
+
+        Parameters
+        ----------
+        index : DatetimeIndex or TimedeltaIndex
+            The index on which to determine if the given frequency is valid
+        freq : DateOffset
+            The frequency to validate
+        """
+        inferred = index.inferred_freq
+        if index.size == 0 or inferred == freq.freqstr:
+            return None
+
+        try:
+            on_freq = cls._generate_range(
+                start=index[0],
+                end=None,
+                periods=len(index),
+                freq=freq,
+                unit=index.unit,
+                **kwargs,
+            )
+            if not np.array_equal(index.asi8, on_freq.asi8):
+                raise ValueError
+        except ValueError as err:
+            if "non-fixed" in str(err):
+                # non-fixed frequencies are not meaningful for timedelta64;
+                #  we retain that error message
+                raise err
+            # GH#11587 the main way this is reached is if the `np.array_equal`
+            #  check above is False.  This can also be reached if index[0]
+            #  is `NaT`, in which case the call to `cls._generate_range` will
+            #  raise a ValueError, which we re-raise with a more targeted
+            #  message.
+            raise ValueError(
+                f"Inferred frequency {inferred} from passed values "
+                f"does not conform to passed frequency {freq.freqstr}"
+            ) from err
+
+    @classmethod
+    def _generate_range(
+        cls, start, end, periods: int | None, freq, *args, **kwargs
+    ) -> Self:
+        raise AbstractMethodError(cls)
+
+    # --------------------------------------------------------------
+
+    @cache_readonly
+    def _creso(self) -> int:
+        return get_unit_from_dtype(self._ndarray.dtype)
+
+    @cache_readonly
+    def unit(self) -> str:
+        # e.g. "ns", "us", "ms"
+        # error: Argument 1 to "dtype_to_unit" has incompatible type
+        # "ExtensionDtype"; expected "Union[DatetimeTZDtype, dtype[Any]]"
+        return dtype_to_unit(self.dtype)  # type: ignore[arg-type]
+
+    def as_unit(self, unit: str, round_ok: bool = True) -> Self:
+        if unit not in ["s", "ms", "us", "ns"]:
+            raise ValueError("Supported units are 's', 'ms', 'us', 'ns'")
+
+        dtype = np.dtype(f"{self.dtype.kind}8[{unit}]")
+        new_values = astype_overflowsafe(self._ndarray, dtype, round_ok=round_ok)
+
+        if isinstance(self.dtype, np.dtype):
+            new_dtype = new_values.dtype
+        else:
+            tz = cast("DatetimeArray", self).tz
+            new_dtype = DatetimeTZDtype(tz=tz, unit=unit)
+
+        # error: Unexpected keyword argument "freq" for "_simple_new" of
+        # "NDArrayBacked"  [call-arg]
+        return type(self)._simple_new(
+            new_values, dtype=new_dtype, freq=self.freq  # type: ignore[call-arg]
+        )
+
+    # TODO: annotate other as DatetimeArray | TimedeltaArray | Timestamp | Timedelta
+    #  with the return type matching input type.  TypeVar?
+    def _ensure_matching_resos(self, other):
+        if self._creso != other._creso:
+            # Just as with Timestamp/Timedelta, we cast to the higher resolution
+            if self._creso < other._creso:
+                self = self.as_unit(other.unit)
+            else:
+                other = other.as_unit(self.unit)
+        return self, other
+
+    # --------------------------------------------------------------
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        if (
+            ufunc in [np.isnan, np.isinf, np.isfinite]
+            and len(inputs) == 1
+            and inputs[0] is self
+        ):
+            # numpy 1.18 changed isinf and isnan to not raise on dt64/td64
+            return getattr(ufunc, method)(self._ndarray, **kwargs)
+
+        return super().__array_ufunc__(ufunc, method, *inputs, **kwargs)
+
+    def _round(self, freq, mode, ambiguous, nonexistent):
+        # round the local times
+        if isinstance(self.dtype, DatetimeTZDtype):
+            # operate on naive timestamps, then convert back to aware
+            self = cast("DatetimeArray", self)
+            naive = self.tz_localize(None)
+            result = naive._round(freq, mode, ambiguous, nonexistent)
+            return result.tz_localize(
+                self.tz, ambiguous=ambiguous, nonexistent=nonexistent
+            )
+
+        values = self.view("i8")
+        values = cast(np.ndarray, values)
+        nanos = get_unit_for_round(freq, self._creso)
+        if nanos == 0:
+            # GH 52761
+            return self.copy()
+        result_i8 = round_nsint64(values, mode, nanos)
+        result = self._maybe_mask_results(result_i8, fill_value=iNaT)
+        result = result.view(self._ndarray.dtype)
+        return self._simple_new(result, dtype=self.dtype)
+
+    @Appender((_round_doc + _round_example).format(op="round"))
+    def round(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        return self._round(freq, RoundTo.NEAREST_HALF_EVEN, ambiguous, nonexistent)
+
+    @Appender((_round_doc + _floor_example).format(op="floor"))
+    def floor(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        return self._round(freq, RoundTo.MINUS_INFTY, ambiguous, nonexistent)
+
+    @Appender((_round_doc + _ceil_example).format(op="ceil"))
+    def ceil(
+        self,
+        freq,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        return self._round(freq, RoundTo.PLUS_INFTY, ambiguous, nonexistent)
+
+    # --------------------------------------------------------------
+    # Reductions
+
+    def any(self, *, axis: AxisInt | None = None, skipna: bool = True) -> bool:
+        # GH#34479 the nanops call will issue a FutureWarning for non-td64 dtype
+        return nanops.nanany(self._ndarray, axis=axis, skipna=skipna, mask=self.isna())
+
+    def all(self, *, axis: AxisInt | None = None, skipna: bool = True) -> bool:
+        # GH#34479 the nanops call will issue a FutureWarning for non-td64 dtype
+
+        return nanops.nanall(self._ndarray, axis=axis, skipna=skipna, mask=self.isna())
+
+    # --------------------------------------------------------------
+    # Frequency Methods
+
+    def _maybe_clear_freq(self) -> None:
+        self._freq = None
+
+    def _with_freq(self, freq) -> Self:
+        """
+        Helper to get a view on the same data, with a new freq.
+
+        Parameters
+        ----------
+        freq : DateOffset, None, or "infer"
+
+        Returns
+        -------
+        Same type as self
+        """
+        # GH#29843
+        if freq is None:
+            # Always valid
+            pass
+        elif len(self) == 0 and isinstance(freq, BaseOffset):
+            # Always valid.  In the TimedeltaArray case, we require a Tick offset
+            if self.dtype.kind == "m" and not isinstance(freq, Tick):
+                raise TypeError("TimedeltaArray/Index freq must be a Tick")
+        else:
+            # As an internal method, we can ensure this assertion always holds
+            assert freq == "infer"
+            freq = to_offset(self.inferred_freq)
+
+        arr = self.view()
+        arr._freq = freq
+        return arr
+
+    # --------------------------------------------------------------
+    # ExtensionArray Interface
+
+    def _values_for_json(self) -> np.ndarray:
+        # Small performance bump vs the base class which calls np.asarray(self)
+        if isinstance(self.dtype, np.dtype):
+            return self._ndarray
+        return super()._values_for_json()
+
+    def factorize(
+        self,
+        use_na_sentinel: bool = True,
+        sort: bool = False,
+    ):
+        if self.freq is not None:
+            # We must be unique, so can short-circuit (and retain freq)
+            codes = np.arange(len(self), dtype=np.intp)
+            uniques = self.copy()  # TODO: copy or view?
+            if sort and self.freq.n < 0:
+                codes = codes[::-1]
+                uniques = uniques[::-1]
+            return codes, uniques
+
+        if sort:
+            # algorithms.factorize only passes sort=True here when freq is
+            #  not None, so this should not be reached.
+            raise NotImplementedError(
+                f"The 'sort' keyword in {type(self).__name__}.factorize is "
+                "ignored unless arr.freq is not None. To factorize with sort, "
+                "call pd.factorize(obj, sort=True) instead."
+            )
+        return super().factorize(use_na_sentinel=use_na_sentinel)
+
+    @classmethod
+    def _concat_same_type(
+        cls,
+        to_concat: Sequence[Self],
+        axis: AxisInt = 0,
+    ) -> Self:
+        new_obj = super()._concat_same_type(to_concat, axis)
+
+        obj = to_concat[0]
+
+        if axis == 0:
+            # GH 3232: If the concat result is evenly spaced, we can retain the
+            # original frequency
+            to_concat = [x for x in to_concat if len(x)]
+
+            if obj.freq is not None and all(x.freq == obj.freq for x in to_concat):
+                pairs = zip(to_concat[:-1], to_concat[1:])
+                if all(pair[0][-1] + obj.freq == pair[1][0] for pair in pairs):
+                    new_freq = obj.freq
+                    new_obj._freq = new_freq
+        return new_obj
+
+    def copy(self, order: str = "C") -> Self:
+        new_obj = super().copy(order=order)
+        new_obj._freq = self.freq
+        return new_obj
+
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        axis: int,
+        index: Index,
+        limit,
+        limit_direction,
+        limit_area,
+        copy: bool,
+        **kwargs,
+    ) -> Self:
+        """
+        See NDFrame.interpolate.__doc__.
+        """
+        # NB: we return type(self) even if copy=False
+        if method != "linear":
+            raise NotImplementedError
+
+        if not copy:
+            out_data = self._ndarray
+        else:
+            out_data = self._ndarray.copy()
+
+        missing.interpolate_2d_inplace(
+            out_data,
+            method=method,
+            axis=axis,
+            index=index,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            **kwargs,
+        )
+        if not copy:
+            return self
+        return type(self)._simple_new(out_data, dtype=self.dtype)
+
+    # --------------------------------------------------------------
+    # Unsorted
+
+    @property
+    def _is_dates_only(self) -> bool:
+        """
+        Check if we are round times at midnight (and no timezone), which will
+        be given a more compact __repr__ than other cases. For TimedeltaArray
+        we are checking for multiples of 24H.
+        """
+        if not lib.is_np_dtype(self.dtype):
+            # i.e. we have a timezone
+            return False
+
+        values_int = self.asi8
+        consider_values = values_int != iNaT
+        reso = get_unit_from_dtype(self.dtype)
+        ppd = periods_per_day(reso)
+
+        # TODO: can we reuse is_date_array_normalized?  would need a skipna kwd
+        #  (first attempt at this was less performant than this implementation)
+        even_days = np.logical_and(consider_values, values_int % ppd != 0).sum() == 0
+        return even_days
+
+
+# -------------------------------------------------------------------
+# Shared Constructor Helpers
+
+
+def ensure_arraylike_for_datetimelike(
+    data, copy: bool, cls_name: str
+) -> tuple[ArrayLike, bool]:
+    if not hasattr(data, "dtype"):
+        # e.g. list, tuple
+        if not isinstance(data, (list, tuple)) and np.ndim(data) == 0:
+            # i.e. generator
+            data = list(data)
+
+        data = construct_1d_object_array_from_listlike(data)
+        copy = False
+    elif isinstance(data, ABCMultiIndex):
+        raise TypeError(f"Cannot create a {cls_name} from a MultiIndex.")
+    else:
+        data = extract_array(data, extract_numpy=True)
+
+    if isinstance(data, IntegerArray) or (
+        isinstance(data, ArrowExtensionArray) and data.dtype.kind in "iu"
+    ):
+        data = data.to_numpy("int64", na_value=iNaT)
+        copy = False
+    elif isinstance(data, ArrowExtensionArray):
+        data = data._maybe_convert_datelike_array()
+        data = data.to_numpy()
+        copy = False
+    elif not isinstance(data, (np.ndarray, ExtensionArray)):
+        # GH#24539 e.g. xarray, dask object
+        data = np.asarray(data)
+
+    elif isinstance(data, ABCCategorical):
+        # GH#18664 preserve tz in going DTI->Categorical->DTI
+        # TODO: cases where we need to do another pass through maybe_convert_dtype,
+        #  e.g. the categories are timedelta64s
+        data = data.categories.take(data.codes, fill_value=NaT)._values
+        copy = False
+
+    return data, copy
+
+
+@overload
+def validate_periods(periods: None) -> None:
+    ...
+
+
+@overload
+def validate_periods(periods: int | float) -> int:
+    ...
+
+
+def validate_periods(periods: int | float | None) -> int | None:
+    """
+    If a `periods` argument is passed to the Datetime/Timedelta Array/Index
+    constructor, cast it to an integer.
+
+    Parameters
+    ----------
+    periods : None, float, int
+
+    Returns
+    -------
+    periods : None or int
+
+    Raises
+    ------
+    TypeError
+        if periods is None, float, or int
+    """
+    if periods is not None:
+        if lib.is_float(periods):
+            warnings.warn(
+                # GH#56036
+                "Non-integer 'periods' in pd.date_range, pd.timedelta_range, "
+                "pd.period_range, and pd.interval_range are deprecated and "
+                "will raise in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            periods = int(periods)
+        elif not lib.is_integer(periods):
+            raise TypeError(f"periods must be a number, got {periods}")
+    return periods
+
+
+def _validate_inferred_freq(
+    freq: BaseOffset | None, inferred_freq: BaseOffset | None
+) -> BaseOffset | None:
+    """
+    If the user passes a freq and another freq is inferred from passed data,
+    require that they match.
+
+    Parameters
+    ----------
+    freq : DateOffset or None
+    inferred_freq : DateOffset or None
+
+    Returns
+    -------
+    freq : DateOffset or None
+    """
+    if inferred_freq is not None:
+        if freq is not None and freq != inferred_freq:
+            raise ValueError(
+                f"Inferred frequency {inferred_freq} from passed "
+                "values does not conform to passed frequency "
+                f"{freq.freqstr}"
+            )
+        if freq is None:
+            freq = inferred_freq
+
+    return freq
+
+
+def dtype_to_unit(dtype: DatetimeTZDtype | np.dtype | ArrowDtype) -> str:
+    """
+    Return the unit str corresponding to the dtype's resolution.
+
+    Parameters
+    ----------
+    dtype : DatetimeTZDtype or np.dtype
+        If np.dtype, we assume it is a datetime64 dtype.
+
+    Returns
+    -------
+    str
+    """
+    if isinstance(dtype, DatetimeTZDtype):
+        return dtype.unit
+    elif isinstance(dtype, ArrowDtype):
+        if dtype.kind not in "mM":
+            raise ValueError(f"{dtype=} does not have a resolution.")
+        return dtype.pyarrow_dtype.unit
+    return np.datetime_data(dtype)[0]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimes.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimes.py
new file mode 100644
index 0000000000000000000000000000000000000000..0db25db02e75ad201e11ab0f6a6d10205060ea9a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/datetimes.py
@@ -0,0 +1,2837 @@
+from __future__ import annotations
+
+from datetime import (
+    datetime,
+    timedelta,
+    tzinfo,
+)
+from typing import (
+    TYPE_CHECKING,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import (
+    lib,
+    tslib,
+)
+from pandas._libs.tslibs import (
+    BaseOffset,
+    NaT,
+    NaTType,
+    Resolution,
+    Timestamp,
+    astype_overflowsafe,
+    fields,
+    get_resolution,
+    get_supported_dtype,
+    get_unit_from_dtype,
+    ints_to_pydatetime,
+    is_date_array_normalized,
+    is_supported_dtype,
+    is_unitless,
+    normalize_i8_timestamps,
+    timezones,
+    to_offset,
+    tz_convert_from_utc,
+    tzconversion,
+)
+from pandas._libs.tslibs.dtypes import abbrev_to_npy_unit
+from pandas.errors import PerformanceWarning
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_inclusive
+
+from pandas.core.dtypes.common import (
+    DT64NS_DTYPE,
+    INT64_DTYPE,
+    is_bool_dtype,
+    is_float_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    ExtensionDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.arrays import datetimelike as dtl
+from pandas.core.arrays._ranges import generate_regular_range
+import pandas.core.common as com
+
+from pandas.tseries.frequencies import get_period_alias
+from pandas.tseries.offsets import (
+    Day,
+    Tick,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pandas._typing import (
+        ArrayLike,
+        DateTimeErrorChoices,
+        DtypeObj,
+        IntervalClosedType,
+        Self,
+        TimeAmbiguous,
+        TimeNonexistent,
+        npt,
+    )
+
+    from pandas import DataFrame
+    from pandas.core.arrays import PeriodArray
+
+
+_ITER_CHUNKSIZE = 10_000
+
+
+@overload
+def tz_to_dtype(tz: tzinfo, unit: str = ...) -> DatetimeTZDtype:
+    ...
+
+
+@overload
+def tz_to_dtype(tz: None, unit: str = ...) -> np.dtype[np.datetime64]:
+    ...
+
+
+def tz_to_dtype(
+    tz: tzinfo | None, unit: str = "ns"
+) -> np.dtype[np.datetime64] | DatetimeTZDtype:
+    """
+    Return a datetime64[ns] dtype appropriate for the given timezone.
+
+    Parameters
+    ----------
+    tz : tzinfo or None
+    unit : str, default "ns"
+
+    Returns
+    -------
+    np.dtype or Datetime64TZDType
+    """
+    if tz is None:
+        return np.dtype(f"M8[{unit}]")
+    else:
+        return DatetimeTZDtype(tz=tz, unit=unit)
+
+
+def _field_accessor(name: str, field: str, docstring: str | None = None):
+    def f(self):
+        values = self._local_timestamps()
+
+        if field in self._bool_ops:
+            result: np.ndarray
+
+            if field.endswith(("start", "end")):
+                freq = self.freq
+                month_kw = 12
+                if freq:
+                    kwds = freq.kwds
+                    month_kw = kwds.get("startingMonth", kwds.get("month", 12))
+
+                result = fields.get_start_end_field(
+                    values, field, self.freqstr, month_kw, reso=self._creso
+                )
+            else:
+                result = fields.get_date_field(values, field, reso=self._creso)
+
+            # these return a boolean by-definition
+            return result
+
+        if field in self._object_ops:
+            result = fields.get_date_name_field(values, field, reso=self._creso)
+            result = self._maybe_mask_results(result, fill_value=None)
+
+        else:
+            result = fields.get_date_field(values, field, reso=self._creso)
+            result = self._maybe_mask_results(
+                result, fill_value=None, convert="float64"
+            )
+
+        return result
+
+    f.__name__ = name
+    f.__doc__ = docstring
+    return property(f)
+
+
+# error: Definition of "_concat_same_type" in base class "NDArrayBacked" is
+# incompatible with definition in base class "ExtensionArray"
+class DatetimeArray(dtl.TimelikeOps, dtl.DatelikeOps):  # type: ignore[misc]
+    """
+    Pandas ExtensionArray for tz-naive or tz-aware datetime data.
+
+    .. warning::
+
+       DatetimeArray is currently experimental, and its API may change
+       without warning. In particular, :attr:`DatetimeArray.dtype` is
+       expected to change to always be an instance of an ``ExtensionDtype``
+       subclass.
+
+    Parameters
+    ----------
+    values : Series, Index, DatetimeArray, ndarray
+        The datetime data.
+
+        For DatetimeArray `values` (or a Series or Index boxing one),
+        `dtype` and `freq` will be extracted from `values`.
+
+    dtype : numpy.dtype or DatetimeTZDtype
+        Note that the only NumPy dtype allowed is 'datetime64[ns]'.
+    freq : str or Offset, optional
+        The frequency.
+    copy : bool, default False
+        Whether to copy the underlying array of values.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.arrays.DatetimeArray._from_sequence(
+    ...    pd.DatetimeIndex(['2023-01-01', '2023-01-02'], freq='D'))
+    
+    ['2023-01-01 00:00:00', '2023-01-02 00:00:00']
+    Length: 2, dtype: datetime64[ns]
+    """
+
+    _typ = "datetimearray"
+    _internal_fill_value = np.datetime64("NaT", "ns")
+    _recognized_scalars = (datetime, np.datetime64)
+    _is_recognized_dtype = lambda x: lib.is_np_dtype(x, "M") or isinstance(
+        x, DatetimeTZDtype
+    )
+    _infer_matches = ("datetime", "datetime64", "date")
+
+    @property
+    def _scalar_type(self) -> type[Timestamp]:
+        return Timestamp
+
+    # define my properties & methods for delegation
+    _bool_ops: list[str] = [
+        "is_month_start",
+        "is_month_end",
+        "is_quarter_start",
+        "is_quarter_end",
+        "is_year_start",
+        "is_year_end",
+        "is_leap_year",
+    ]
+    _object_ops: list[str] = ["freq", "tz"]
+    _field_ops: list[str] = [
+        "year",
+        "month",
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "weekday",
+        "dayofweek",
+        "day_of_week",
+        "dayofyear",
+        "day_of_year",
+        "quarter",
+        "days_in_month",
+        "daysinmonth",
+        "microsecond",
+        "nanosecond",
+    ]
+    _other_ops: list[str] = ["date", "time", "timetz"]
+    _datetimelike_ops: list[str] = (
+        _field_ops + _object_ops + _bool_ops + _other_ops + ["unit"]
+    )
+    _datetimelike_methods: list[str] = [
+        "to_period",
+        "tz_localize",
+        "tz_convert",
+        "normalize",
+        "strftime",
+        "round",
+        "floor",
+        "ceil",
+        "month_name",
+        "day_name",
+        "as_unit",
+    ]
+
+    # ndim is inherited from ExtensionArray, must exist to ensure
+    #  Timestamp.__richcmp__(DateTimeArray) operates pointwise
+
+    # ensure that operations with numpy arrays defer to our implementation
+    __array_priority__ = 1000
+
+    # -----------------------------------------------------------------
+    # Constructors
+
+    _dtype: np.dtype[np.datetime64] | DatetimeTZDtype
+    _freq: BaseOffset | None = None
+    _default_dtype = DT64NS_DTYPE  # used in TimeLikeOps.__init__
+
+    @classmethod
+    def _from_scalars(cls, scalars, *, dtype: DtypeObj) -> Self:
+        if lib.infer_dtype(scalars, skipna=True) not in ["datetime", "datetime64"]:
+            # TODO: require any NAs be valid-for-DTA
+            # TODO: if dtype is passed, check for tzawareness compat?
+            raise ValueError
+        return cls._from_sequence(scalars, dtype=dtype)
+
+    @classmethod
+    def _validate_dtype(cls, values, dtype):
+        # used in TimeLikeOps.__init__
+        dtype = _validate_dt64_dtype(dtype)
+        _validate_dt64_dtype(values.dtype)
+        if isinstance(dtype, np.dtype):
+            if values.dtype != dtype:
+                raise ValueError("Values resolution does not match dtype.")
+        else:
+            vunit = np.datetime_data(values.dtype)[0]
+            if vunit != dtype.unit:
+                raise ValueError("Values resolution does not match dtype.")
+        return dtype
+
+    # error: Signature of "_simple_new" incompatible with supertype "NDArrayBacked"
+    @classmethod
+    def _simple_new(  # type: ignore[override]
+        cls,
+        values: npt.NDArray[np.datetime64],
+        freq: BaseOffset | None = None,
+        dtype: np.dtype[np.datetime64] | DatetimeTZDtype = DT64NS_DTYPE,
+    ) -> Self:
+        assert isinstance(values, np.ndarray)
+        assert dtype.kind == "M"
+        if isinstance(dtype, np.dtype):
+            assert dtype == values.dtype
+            assert not is_unitless(dtype)
+        else:
+            # DatetimeTZDtype. If we have e.g. DatetimeTZDtype[us, UTC],
+            #  then values.dtype should be M8[us].
+            assert dtype._creso == get_unit_from_dtype(values.dtype)
+
+        result = super()._simple_new(values, dtype)
+        result._freq = freq
+        return result
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype=None, copy: bool = False):
+        return cls._from_sequence_not_strict(scalars, dtype=dtype, copy=copy)
+
+    @classmethod
+    def _from_sequence_not_strict(
+        cls,
+        data,
+        *,
+        dtype=None,
+        copy: bool = False,
+        tz=lib.no_default,
+        freq: str | BaseOffset | lib.NoDefault | None = lib.no_default,
+        dayfirst: bool = False,
+        yearfirst: bool = False,
+        ambiguous: TimeAmbiguous = "raise",
+    ) -> Self:
+        """
+        A non-strict version of _from_sequence, called from DatetimeIndex.__new__.
+        """
+
+        # if the user either explicitly passes tz=None or a tz-naive dtype, we
+        #  disallows inferring a tz.
+        explicit_tz_none = tz is None
+        if tz is lib.no_default:
+            tz = None
+        else:
+            tz = timezones.maybe_get_tz(tz)
+
+        dtype = _validate_dt64_dtype(dtype)
+        # if dtype has an embedded tz, capture it
+        tz = _validate_tz_from_dtype(dtype, tz, explicit_tz_none)
+
+        unit = None
+        if dtype is not None:
+            unit = dtl.dtype_to_unit(dtype)
+
+        data, copy = dtl.ensure_arraylike_for_datetimelike(
+            data, copy, cls_name="DatetimeArray"
+        )
+        inferred_freq = None
+        if isinstance(data, DatetimeArray):
+            inferred_freq = data.freq
+
+        subarr, tz = _sequence_to_dt64(
+            data,
+            copy=copy,
+            tz=tz,
+            dayfirst=dayfirst,
+            yearfirst=yearfirst,
+            ambiguous=ambiguous,
+            out_unit=unit,
+        )
+        # We have to call this again after possibly inferring a tz above
+        _validate_tz_from_dtype(dtype, tz, explicit_tz_none)
+        if tz is not None and explicit_tz_none:
+            raise ValueError(
+                "Passed data is timezone-aware, incompatible with 'tz=None'. "
+                "Use obj.tz_localize(None) instead."
+            )
+
+        data_unit = np.datetime_data(subarr.dtype)[0]
+        data_dtype = tz_to_dtype(tz, data_unit)
+        result = cls._simple_new(subarr, freq=inferred_freq, dtype=data_dtype)
+        if unit is not None and unit != result.unit:
+            # If unit was specified in user-passed dtype, cast to it here
+            result = result.as_unit(unit)
+
+        validate_kwds = {"ambiguous": ambiguous}
+        result._maybe_pin_freq(freq, validate_kwds)
+        return result
+
+    @classmethod
+    def _generate_range(
+        cls,
+        start,
+        end,
+        periods: int | None,
+        freq,
+        tz=None,
+        normalize: bool = False,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+        inclusive: IntervalClosedType = "both",
+        *,
+        unit: str | None = None,
+    ) -> Self:
+        periods = dtl.validate_periods(periods)
+        if freq is None and any(x is None for x in [periods, start, end]):
+            raise ValueError("Must provide freq argument if no data is supplied")
+
+        if com.count_not_none(start, end, periods, freq) != 3:
+            raise ValueError(
+                "Of the four parameters: start, end, periods, "
+                "and freq, exactly three must be specified"
+            )
+        freq = to_offset(freq)
+
+        if start is not None:
+            start = Timestamp(start)
+
+        if end is not None:
+            end = Timestamp(end)
+
+        if start is NaT or end is NaT:
+            raise ValueError("Neither `start` nor `end` can be NaT")
+
+        if unit is not None:
+            if unit not in ["s", "ms", "us", "ns"]:
+                raise ValueError("'unit' must be one of 's', 'ms', 'us', 'ns'")
+        else:
+            unit = "ns"
+
+        if start is not None:
+            start = start.as_unit(unit, round_ok=False)
+        if end is not None:
+            end = end.as_unit(unit, round_ok=False)
+
+        left_inclusive, right_inclusive = validate_inclusive(inclusive)
+        start, end = _maybe_normalize_endpoints(start, end, normalize)
+        tz = _infer_tz_from_endpoints(start, end, tz)
+
+        if tz is not None:
+            # Localize the start and end arguments
+            start = _maybe_localize_point(start, freq, tz, ambiguous, nonexistent)
+            end = _maybe_localize_point(end, freq, tz, ambiguous, nonexistent)
+
+        if freq is not None:
+            # We break Day arithmetic (fixed 24 hour) here and opt for
+            # Day to mean calendar day (23/24/25 hour). Therefore, strip
+            # tz info from start and day to avoid DST arithmetic
+            if isinstance(freq, Day):
+                if start is not None:
+                    start = start.tz_localize(None)
+                if end is not None:
+                    end = end.tz_localize(None)
+
+            if isinstance(freq, Tick):
+                i8values = generate_regular_range(start, end, periods, freq, unit=unit)
+            else:
+                xdr = _generate_range(
+                    start=start, end=end, periods=periods, offset=freq, unit=unit
+                )
+                i8values = np.array([x._value for x in xdr], dtype=np.int64)
+
+            endpoint_tz = start.tz if start is not None else end.tz
+
+            if tz is not None and endpoint_tz is None:
+                if not timezones.is_utc(tz):
+                    # short-circuit tz_localize_to_utc which would make
+                    #  an unnecessary copy with UTC but be a no-op.
+                    creso = abbrev_to_npy_unit(unit)
+                    i8values = tzconversion.tz_localize_to_utc(
+                        i8values,
+                        tz,
+                        ambiguous=ambiguous,
+                        nonexistent=nonexistent,
+                        creso=creso,
+                    )
+
+                # i8values is localized datetime64 array -> have to convert
+                # start/end as well to compare
+                if start is not None:
+                    start = start.tz_localize(tz, ambiguous, nonexistent)
+                if end is not None:
+                    end = end.tz_localize(tz, ambiguous, nonexistent)
+        else:
+            # Create a linearly spaced date_range in local time
+            # Nanosecond-granularity timestamps aren't always correctly
+            # representable with doubles, so we limit the range that we
+            # pass to np.linspace as much as possible
+            periods = cast(int, periods)
+            i8values = (
+                np.linspace(0, end._value - start._value, periods, dtype="int64")
+                + start._value
+            )
+            if i8values.dtype != "i8":
+                # 2022-01-09 I (brock) am not sure if it is possible for this
+                #  to overflow and cast to e.g. f8, but if it does we need to cast
+                i8values = i8values.astype("i8")
+
+        if start == end:
+            if not left_inclusive and not right_inclusive:
+                i8values = i8values[1:-1]
+        else:
+            start_i8 = Timestamp(start)._value
+            end_i8 = Timestamp(end)._value
+            if not left_inclusive or not right_inclusive:
+                if not left_inclusive and len(i8values) and i8values[0] == start_i8:
+                    i8values = i8values[1:]
+                if not right_inclusive and len(i8values) and i8values[-1] == end_i8:
+                    i8values = i8values[:-1]
+
+        dt64_values = i8values.view(f"datetime64[{unit}]")
+        dtype = tz_to_dtype(tz, unit=unit)
+        return cls._simple_new(dt64_values, freq=freq, dtype=dtype)
+
+    # -----------------------------------------------------------------
+    # DatetimeLike Interface
+
+    def _unbox_scalar(self, value) -> np.datetime64:
+        if not isinstance(value, self._scalar_type) and value is not NaT:
+            raise ValueError("'value' should be a Timestamp.")
+        self._check_compatible_with(value)
+        if value is NaT:
+            return np.datetime64(value._value, self.unit)
+        else:
+            return value.as_unit(self.unit).asm8
+
+    def _scalar_from_string(self, value) -> Timestamp | NaTType:
+        return Timestamp(value, tz=self.tz)
+
+    def _check_compatible_with(self, other) -> None:
+        if other is NaT:
+            return
+        self._assert_tzawareness_compat(other)
+
+    # -----------------------------------------------------------------
+    # Descriptive Properties
+
+    def _box_func(self, x: np.datetime64) -> Timestamp | NaTType:
+        # GH#42228
+        value = x.view("i8")
+        ts = Timestamp._from_value_and_reso(value, reso=self._creso, tz=self.tz)
+        return ts
+
+    @property
+    # error: Return type "Union[dtype, DatetimeTZDtype]" of "dtype"
+    # incompatible with return type "ExtensionDtype" in supertype
+    # "ExtensionArray"
+    def dtype(self) -> np.dtype[np.datetime64] | DatetimeTZDtype:  # type: ignore[override]
+        """
+        The dtype for the DatetimeArray.
+
+        .. warning::
+
+           A future version of pandas will change dtype to never be a
+           ``numpy.dtype``. Instead, :attr:`DatetimeArray.dtype` will
+           always be an instance of an ``ExtensionDtype`` subclass.
+
+        Returns
+        -------
+        numpy.dtype or DatetimeTZDtype
+            If the values are tz-naive, then ``np.dtype('datetime64[ns]')``
+            is returned.
+
+            If the values are tz-aware, then the ``DatetimeTZDtype``
+            is returned.
+        """
+        return self._dtype
+
+    @property
+    def tz(self) -> tzinfo | None:
+        """
+        Return the timezone.
+
+        Returns
+        -------
+        datetime.tzinfo, pytz.tzinfo.BaseTZInfo, dateutil.tz.tz.tzfile, or None
+            Returns None when the array is tz-naive.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.tz
+        datetime.timezone.utc
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.tz
+        datetime.timezone.utc
+        """
+        # GH 18595
+        return getattr(self.dtype, "tz", None)
+
+    @tz.setter
+    def tz(self, value):
+        # GH 3746: Prevent localizing or converting the index by setting tz
+        raise AttributeError(
+            "Cannot directly set timezone. Use tz_localize() "
+            "or tz_convert() as appropriate"
+        )
+
+    @property
+    def tzinfo(self) -> tzinfo | None:
+        """
+        Alias for tz attribute
+        """
+        return self.tz
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def is_normalized(self) -> bool:
+        """
+        Returns True if all of the dates are at midnight ("no time")
+        """
+        return is_date_array_normalized(self.asi8, self.tz, reso=self._creso)
+
+    @property  # NB: override with cache_readonly in immutable subclasses
+    def _resolution_obj(self) -> Resolution:
+        return get_resolution(self.asi8, self.tz, reso=self._creso)
+
+    # ----------------------------------------------------------------
+    # Array-Like / EA-Interface Methods
+
+    def __array__(self, dtype=None, copy=None) -> np.ndarray:
+        if dtype is None and self.tz:
+            # The default for tz-aware is object, to preserve tz info
+            dtype = object
+
+        return super().__array__(dtype=dtype, copy=copy)
+
+    def __iter__(self) -> Iterator:
+        """
+        Return an iterator over the boxed values
+
+        Yields
+        ------
+        tstamp : Timestamp
+        """
+        if self.ndim > 1:
+            for i in range(len(self)):
+                yield self[i]
+        else:
+            # convert in chunks of 10k for efficiency
+            data = self.asi8
+            length = len(self)
+            chunksize = _ITER_CHUNKSIZE
+            chunks = (length // chunksize) + 1
+
+            for i in range(chunks):
+                start_i = i * chunksize
+                end_i = min((i + 1) * chunksize, length)
+                converted = ints_to_pydatetime(
+                    data[start_i:end_i],
+                    tz=self.tz,
+                    box="timestamp",
+                    reso=self._creso,
+                )
+                yield from converted
+
+    def astype(self, dtype, copy: bool = True):
+        # We handle
+        #   --> datetime
+        #   --> period
+        # DatetimeLikeArrayMixin Super handles the rest.
+        dtype = pandas_dtype(dtype)
+
+        if dtype == self.dtype:
+            if copy:
+                return self.copy()
+            return self
+
+        elif isinstance(dtype, ExtensionDtype):
+            if not isinstance(dtype, DatetimeTZDtype):
+                # e.g. Sparse[datetime64[ns]]
+                return super().astype(dtype, copy=copy)
+            elif self.tz is None:
+                # pre-2.0 this did self.tz_localize(dtype.tz), which did not match
+                #  the Series behavior which did
+                #  values.tz_localize("UTC").tz_convert(dtype.tz)
+                raise TypeError(
+                    "Cannot use .astype to convert from timezone-naive dtype to "
+                    "timezone-aware dtype. Use obj.tz_localize instead or "
+                    "series.dt.tz_localize instead"
+                )
+            else:
+                # tzaware unit conversion e.g. datetime64[s, UTC]
+                np_dtype = np.dtype(dtype.str)
+                res_values = astype_overflowsafe(self._ndarray, np_dtype, copy=copy)
+                return type(self)._simple_new(res_values, dtype=dtype, freq=self.freq)
+
+        elif (
+            self.tz is None
+            and lib.is_np_dtype(dtype, "M")
+            and not is_unitless(dtype)
+            and is_supported_dtype(dtype)
+        ):
+            # unit conversion e.g. datetime64[s]
+            res_values = astype_overflowsafe(self._ndarray, dtype, copy=True)
+            return type(self)._simple_new(res_values, dtype=res_values.dtype)
+            # TODO: preserve freq?
+
+        elif self.tz is not None and lib.is_np_dtype(dtype, "M"):
+            # pre-2.0 behavior for DTA/DTI was
+            #  values.tz_convert("UTC").tz_localize(None), which did not match
+            #  the Series behavior
+            raise TypeError(
+                "Cannot use .astype to convert from timezone-aware dtype to "
+                "timezone-naive dtype. Use obj.tz_localize(None) or "
+                "obj.tz_convert('UTC').tz_localize(None) instead."
+            )
+
+        elif (
+            self.tz is None
+            and lib.is_np_dtype(dtype, "M")
+            and dtype != self.dtype
+            and is_unitless(dtype)
+        ):
+            raise TypeError(
+                "Casting to unit-less dtype 'datetime64' is not supported. "
+                "Pass e.g. 'datetime64[ns]' instead."
+            )
+
+        elif isinstance(dtype, PeriodDtype):
+            return self.to_period(freq=dtype.freq)
+        return dtl.DatetimeLikeArrayMixin.astype(self, dtype, copy)
+
+    # -----------------------------------------------------------------
+    # Rendering Methods
+
+    def _format_native_types(
+        self, *, na_rep: str | float = "NaT", date_format=None, **kwargs
+    ) -> npt.NDArray[np.object_]:
+        if date_format is None and self._is_dates_only:
+            # Only dates and no timezone: provide a default format
+            date_format = "%Y-%m-%d"
+
+        return tslib.format_array_from_datetime(
+            self.asi8, tz=self.tz, format=date_format, na_rep=na_rep, reso=self._creso
+        )
+
+    # -----------------------------------------------------------------
+    # Comparison Methods
+
+    def _has_same_tz(self, other) -> bool:
+        # vzone shouldn't be None if value is non-datetime like
+        if isinstance(other, np.datetime64):
+            # convert to Timestamp as np.datetime64 doesn't have tz attr
+            other = Timestamp(other)
+
+        if not hasattr(other, "tzinfo"):
+            return False
+        other_tz = other.tzinfo
+        return timezones.tz_compare(self.tzinfo, other_tz)
+
+    def _assert_tzawareness_compat(self, other) -> None:
+        # adapted from _Timestamp._assert_tzawareness_compat
+        other_tz = getattr(other, "tzinfo", None)
+        other_dtype = getattr(other, "dtype", None)
+
+        if isinstance(other_dtype, DatetimeTZDtype):
+            # Get tzinfo from Series dtype
+            other_tz = other.dtype.tz
+        if other is NaT:
+            # pd.NaT quacks both aware and naive
+            pass
+        elif self.tz is None:
+            if other_tz is not None:
+                raise TypeError(
+                    "Cannot compare tz-naive and tz-aware datetime-like objects."
+                )
+        elif other_tz is None:
+            raise TypeError(
+                "Cannot compare tz-naive and tz-aware datetime-like objects"
+            )
+
+    # -----------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _add_offset(self, offset: BaseOffset) -> Self:
+        assert not isinstance(offset, Tick)
+
+        if self.tz is not None:
+            values = self.tz_localize(None)
+        else:
+            values = self
+
+        try:
+            res_values = offset._apply_array(values._ndarray)
+            if res_values.dtype.kind == "i":
+                # error: Argument 1 to "view" of "ndarray" has incompatible type
+                # "dtype[datetime64] | DatetimeTZDtype"; expected
+                # "dtype[Any] | type[Any] | _SupportsDType[dtype[Any]]"
+                res_values = res_values.view(values.dtype)  # type: ignore[arg-type]
+        except NotImplementedError:
+            warnings.warn(
+                "Non-vectorized DateOffset being applied to Series or DatetimeIndex.",
+                PerformanceWarning,
+                stacklevel=find_stack_level(),
+            )
+            res_values = self.astype("O") + offset
+            # TODO(GH#55564): as_unit will be unnecessary
+            result = type(self)._from_sequence(res_values).as_unit(self.unit)
+            if not len(self):
+                # GH#30336 _from_sequence won't be able to infer self.tz
+                return result.tz_localize(self.tz)
+
+        else:
+            result = type(self)._simple_new(res_values, dtype=res_values.dtype)
+            if offset.normalize:
+                result = result.normalize()
+                result._freq = None
+
+            if self.tz is not None:
+                result = result.tz_localize(self.tz)
+
+        return result
+
+    # -----------------------------------------------------------------
+    # Timezone Conversion and Localization Methods
+
+    def _local_timestamps(self) -> npt.NDArray[np.int64]:
+        """
+        Convert to an i8 (unix-like nanosecond timestamp) representation
+        while keeping the local timezone and not using UTC.
+        This is used to calculate time-of-day information as if the timestamps
+        were timezone-naive.
+        """
+        if self.tz is None or timezones.is_utc(self.tz):
+            # Avoid the copy that would be made in tzconversion
+            return self.asi8
+        return tz_convert_from_utc(self.asi8, self.tz, reso=self._creso)
+
+    def tz_convert(self, tz) -> Self:
+        """
+        Convert tz-aware Datetime Array/Index from one time zone to another.
+
+        Parameters
+        ----------
+        tz : str, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or None
+            Time zone for time. Corresponding timestamps would be converted
+            to this time zone of the Datetime Array/Index. A `tz` of None will
+            convert to UTC and remove the timezone information.
+
+        Returns
+        -------
+        Array or Index
+
+        Raises
+        ------
+        TypeError
+            If Datetime Array/Index is tz-naive.
+
+        See Also
+        --------
+        DatetimeIndex.tz : A timezone that has a variable offset from UTC.
+        DatetimeIndex.tz_localize : Localize tz-naive DatetimeIndex to a
+            given time zone, or remove timezone from a tz-aware DatetimeIndex.
+
+        Examples
+        --------
+        With the `tz` parameter, we can change the DatetimeIndex
+        to other time zones:
+
+        >>> dti = pd.date_range(start='2014-08-01 09:00',
+        ...                     freq='h', periods=3, tz='Europe/Berlin')
+
+        >>> dti
+        DatetimeIndex(['2014-08-01 09:00:00+02:00',
+                       '2014-08-01 10:00:00+02:00',
+                       '2014-08-01 11:00:00+02:00'],
+                      dtype='datetime64[ns, Europe/Berlin]', freq='h')
+
+        >>> dti.tz_convert('US/Central')
+        DatetimeIndex(['2014-08-01 02:00:00-05:00',
+                       '2014-08-01 03:00:00-05:00',
+                       '2014-08-01 04:00:00-05:00'],
+                      dtype='datetime64[ns, US/Central]', freq='h')
+
+        With the ``tz=None``, we can remove the timezone (after converting
+        to UTC if necessary):
+
+        >>> dti = pd.date_range(start='2014-08-01 09:00', freq='h',
+        ...                     periods=3, tz='Europe/Berlin')
+
+        >>> dti
+        DatetimeIndex(['2014-08-01 09:00:00+02:00',
+                       '2014-08-01 10:00:00+02:00',
+                       '2014-08-01 11:00:00+02:00'],
+                        dtype='datetime64[ns, Europe/Berlin]', freq='h')
+
+        >>> dti.tz_convert(None)
+        DatetimeIndex(['2014-08-01 07:00:00',
+                       '2014-08-01 08:00:00',
+                       '2014-08-01 09:00:00'],
+                        dtype='datetime64[ns]', freq='h')
+        """
+        tz = timezones.maybe_get_tz(tz)
+
+        if self.tz is None:
+            # tz naive, use tz_localize
+            raise TypeError(
+                "Cannot convert tz-naive timestamps, use tz_localize to localize"
+            )
+
+        # No conversion since timestamps are all UTC to begin with
+        dtype = tz_to_dtype(tz, unit=self.unit)
+        return self._simple_new(self._ndarray, dtype=dtype, freq=self.freq)
+
+    @dtl.ravel_compat
+    def tz_localize(
+        self,
+        tz,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        """
+        Localize tz-naive Datetime Array/Index to tz-aware Datetime Array/Index.
+
+        This method takes a time zone (tz) naive Datetime Array/Index object
+        and makes this time zone aware. It does not move the time to another
+        time zone.
+
+        This method can also be used to do the inverse -- to create a time
+        zone unaware object from an aware object. To that end, pass `tz=None`.
+
+        Parameters
+        ----------
+        tz : str, pytz.timezone, dateutil.tz.tzfile, datetime.tzinfo or None
+            Time zone to convert timestamps to. Passing ``None`` will
+            remove the time zone information preserving local time.
+        ambiguous : 'infer', 'NaT', bool array, default 'raise'
+            When clocks moved backward due to DST, ambiguous times may arise.
+            For example in Central European Time (UTC+01), when going from
+            03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at
+            00:30:00 UTC and at 01:30:00 UTC. In such a situation, the
+            `ambiguous` parameter dictates how ambiguous times should be
+            handled.
+
+            - 'infer' will attempt to infer fall dst-transition hours based on
+              order
+            - bool-ndarray where True signifies a DST time, False signifies a
+              non-DST time (note that this flag is only applicable for
+              ambiguous times)
+            - 'NaT' will return NaT where there are ambiguous times
+            - 'raise' will raise an AmbiguousTimeError if there are ambiguous
+              times.
+
+        nonexistent : 'shift_forward', 'shift_backward, 'NaT', timedelta, \
+default 'raise'
+            A nonexistent time does not exist in a particular timezone
+            where clocks moved forward due to DST.
+
+            - 'shift_forward' will shift the nonexistent time forward to the
+              closest existing time
+            - 'shift_backward' will shift the nonexistent time backward to the
+              closest existing time
+            - 'NaT' will return NaT where there are nonexistent times
+            - timedelta objects will shift nonexistent times by the timedelta
+            - 'raise' will raise an NonExistentTimeError if there are
+              nonexistent times.
+
+        Returns
+        -------
+        Same type as self
+            Array/Index converted to the specified time zone.
+
+        Raises
+        ------
+        TypeError
+            If the Datetime Array/Index is tz-aware and tz is not None.
+
+        See Also
+        --------
+        DatetimeIndex.tz_convert : Convert tz-aware DatetimeIndex from
+            one time zone to another.
+
+        Examples
+        --------
+        >>> tz_naive = pd.date_range('2018-03-01 09:00', periods=3)
+        >>> tz_naive
+        DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',
+                       '2018-03-03 09:00:00'],
+                      dtype='datetime64[ns]', freq='D')
+
+        Localize DatetimeIndex in US/Eastern time zone:
+
+        >>> tz_aware = tz_naive.tz_localize(tz='US/Eastern')
+        >>> tz_aware
+        DatetimeIndex(['2018-03-01 09:00:00-05:00',
+                       '2018-03-02 09:00:00-05:00',
+                       '2018-03-03 09:00:00-05:00'],
+                      dtype='datetime64[ns, US/Eastern]', freq=None)
+
+        With the ``tz=None``, we can remove the time zone information
+        while keeping the local time (not converted to UTC):
+
+        >>> tz_aware.tz_localize(None)
+        DatetimeIndex(['2018-03-01 09:00:00', '2018-03-02 09:00:00',
+                       '2018-03-03 09:00:00'],
+                      dtype='datetime64[ns]', freq=None)
+
+        Be careful with DST changes. When there is sequential data, pandas can
+        infer the DST time:
+
+        >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:30:00',
+        ...                               '2018-10-28 02:00:00',
+        ...                               '2018-10-28 02:30:00',
+        ...                               '2018-10-28 02:00:00',
+        ...                               '2018-10-28 02:30:00',
+        ...                               '2018-10-28 03:00:00',
+        ...                               '2018-10-28 03:30:00']))
+        >>> s.dt.tz_localize('CET', ambiguous='infer')
+        0   2018-10-28 01:30:00+02:00
+        1   2018-10-28 02:00:00+02:00
+        2   2018-10-28 02:30:00+02:00
+        3   2018-10-28 02:00:00+01:00
+        4   2018-10-28 02:30:00+01:00
+        5   2018-10-28 03:00:00+01:00
+        6   2018-10-28 03:30:00+01:00
+        dtype: datetime64[ns, CET]
+
+        In some cases, inferring the DST is impossible. In such cases, you can
+        pass an ndarray to the ambiguous parameter to set the DST explicitly
+
+        >>> s = pd.to_datetime(pd.Series(['2018-10-28 01:20:00',
+        ...                               '2018-10-28 02:36:00',
+        ...                               '2018-10-28 03:46:00']))
+        >>> s.dt.tz_localize('CET', ambiguous=np.array([True, True, False]))
+        0   2018-10-28 01:20:00+02:00
+        1   2018-10-28 02:36:00+02:00
+        2   2018-10-28 03:46:00+01:00
+        dtype: datetime64[ns, CET]
+
+        If the DST transition causes nonexistent times, you can shift these
+        dates forward or backwards with a timedelta object or `'shift_forward'`
+        or `'shift_backwards'`.
+
+        >>> s = pd.to_datetime(pd.Series(['2015-03-29 02:30:00',
+        ...                               '2015-03-29 03:30:00']))
+        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_forward')
+        0   2015-03-29 03:00:00+02:00
+        1   2015-03-29 03:30:00+02:00
+        dtype: datetime64[ns, Europe/Warsaw]
+
+        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent='shift_backward')
+        0   2015-03-29 01:59:59.999999999+01:00
+        1   2015-03-29 03:30:00+02:00
+        dtype: datetime64[ns, Europe/Warsaw]
+
+        >>> s.dt.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('1h'))
+        0   2015-03-29 03:30:00+02:00
+        1   2015-03-29 03:30:00+02:00
+        dtype: datetime64[ns, Europe/Warsaw]
+        """
+        nonexistent_options = ("raise", "NaT", "shift_forward", "shift_backward")
+        if nonexistent not in nonexistent_options and not isinstance(
+            nonexistent, timedelta
+        ):
+            raise ValueError(
+                "The nonexistent argument must be one of 'raise', "
+                "'NaT', 'shift_forward', 'shift_backward' or "
+                "a timedelta object"
+            )
+
+        if self.tz is not None:
+            if tz is None:
+                new_dates = tz_convert_from_utc(self.asi8, self.tz, reso=self._creso)
+            else:
+                raise TypeError("Already tz-aware, use tz_convert to convert.")
+        else:
+            tz = timezones.maybe_get_tz(tz)
+            # Convert to UTC
+
+            new_dates = tzconversion.tz_localize_to_utc(
+                self.asi8,
+                tz,
+                ambiguous=ambiguous,
+                nonexistent=nonexistent,
+                creso=self._creso,
+            )
+        new_dates_dt64 = new_dates.view(f"M8[{self.unit}]")
+        dtype = tz_to_dtype(tz, unit=self.unit)
+
+        freq = None
+        if timezones.is_utc(tz) or (len(self) == 1 and not isna(new_dates_dt64[0])):
+            # we can preserve freq
+            # TODO: Also for fixed-offsets
+            freq = self.freq
+        elif tz is None and self.tz is None:
+            # no-op
+            freq = self.freq
+        return self._simple_new(new_dates_dt64, dtype=dtype, freq=freq)
+
+    # ----------------------------------------------------------------
+    # Conversion Methods - Vectorized analogues of Timestamp methods
+
+    def to_pydatetime(self) -> npt.NDArray[np.object_]:
+        """
+        Return an ndarray of ``datetime.datetime`` objects.
+
+        Returns
+        -------
+        numpy.ndarray
+
+        Examples
+        --------
+        >>> idx = pd.date_range('2018-02-27', periods=3)
+        >>> idx.to_pydatetime()
+        array([datetime.datetime(2018, 2, 27, 0, 0),
+               datetime.datetime(2018, 2, 28, 0, 0),
+               datetime.datetime(2018, 3, 1, 0, 0)], dtype=object)
+        """
+        return ints_to_pydatetime(self.asi8, tz=self.tz, reso=self._creso)
+
+    def normalize(self) -> Self:
+        """
+        Convert times to midnight.
+
+        The time component of the date-time is converted to midnight i.e.
+        00:00:00. This is useful in cases, when the time does not matter.
+        Length is unaltered. The timezones are unaffected.
+
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on Datetime Array/Index.
+
+        Returns
+        -------
+        DatetimeArray, DatetimeIndex or Series
+            The same type as the original data. Series will have the same
+            name and index. DatetimeIndex will have the same name.
+
+        See Also
+        --------
+        floor : Floor the datetimes to the specified freq.
+        ceil : Ceil the datetimes to the specified freq.
+        round : Round the datetimes to the specified freq.
+
+        Examples
+        --------
+        >>> idx = pd.date_range(start='2014-08-01 10:00', freq='h',
+        ...                     periods=3, tz='Asia/Calcutta')
+        >>> idx
+        DatetimeIndex(['2014-08-01 10:00:00+05:30',
+                       '2014-08-01 11:00:00+05:30',
+                       '2014-08-01 12:00:00+05:30'],
+                        dtype='datetime64[ns, Asia/Calcutta]', freq='h')
+        >>> idx.normalize()
+        DatetimeIndex(['2014-08-01 00:00:00+05:30',
+                       '2014-08-01 00:00:00+05:30',
+                       '2014-08-01 00:00:00+05:30'],
+                       dtype='datetime64[ns, Asia/Calcutta]', freq=None)
+        """
+        new_values = normalize_i8_timestamps(self.asi8, self.tz, reso=self._creso)
+        dt64_values = new_values.view(self._ndarray.dtype)
+
+        dta = type(self)._simple_new(dt64_values, dtype=dt64_values.dtype)
+        dta = dta._with_freq("infer")
+        if self.tz is not None:
+            dta = dta.tz_localize(self.tz)
+        return dta
+
+    def to_period(self, freq=None) -> PeriodArray:
+        """
+        Cast to PeriodArray/PeriodIndex at a particular frequency.
+
+        Converts DatetimeArray/Index to PeriodArray/PeriodIndex.
+
+        Parameters
+        ----------
+        freq : str or Period, optional
+            One of pandas' :ref:`period aliases `
+            or an Period object. Will be inferred by default.
+
+        Returns
+        -------
+        PeriodArray/PeriodIndex
+
+        Raises
+        ------
+        ValueError
+            When converting a DatetimeArray/Index with non-regular values,
+            so that a frequency cannot be inferred.
+
+        See Also
+        --------
+        PeriodIndex: Immutable ndarray holding ordinal values.
+        DatetimeIndex.to_pydatetime: Return DatetimeIndex as object.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"y": [1, 2, 3]},
+        ...                   index=pd.to_datetime(["2000-03-31 00:00:00",
+        ...                                         "2000-05-31 00:00:00",
+        ...                                         "2000-08-31 00:00:00"]))
+        >>> df.index.to_period("M")
+        PeriodIndex(['2000-03', '2000-05', '2000-08'],
+                    dtype='period[M]')
+
+        Infer the daily frequency
+
+        >>> idx = pd.date_range("2017-01-01", periods=2)
+        >>> idx.to_period()
+        PeriodIndex(['2017-01-01', '2017-01-02'],
+                    dtype='period[D]')
+        """
+        from pandas.core.arrays import PeriodArray
+
+        if self.tz is not None:
+            warnings.warn(
+                "Converting to PeriodArray/Index representation "
+                "will drop timezone information.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if freq is None:
+            freq = self.freqstr or self.inferred_freq
+            if isinstance(self.freq, BaseOffset) and hasattr(
+                self.freq, "_period_dtype_code"
+            ):
+                freq = PeriodDtype(self.freq)._freqstr
+
+            if freq is None:
+                raise ValueError(
+                    "You must pass a freq argument as current index has none."
+                )
+
+            res = get_period_alias(freq)
+
+            #  https://github.com/pandas-dev/pandas/issues/33358
+            if res is None:
+                res = freq
+
+            freq = res
+        return PeriodArray._from_datetime64(self._ndarray, freq, tz=self.tz)
+
+    # -----------------------------------------------------------------
+    # Properties - Vectorized Timestamp Properties/Methods
+
+    def month_name(self, locale=None) -> npt.NDArray[np.object_]:
+        """
+        Return the month names with specified locale.
+
+        Parameters
+        ----------
+        locale : str, optional
+            Locale determining the language in which to return the month name.
+            Default is English locale (``'en_US.utf8'``). Use the command
+            ``locale -a`` on your terminal on Unix systems to find your locale
+            language code.
+
+        Returns
+        -------
+        Series or Index
+            Series or Index of month names.
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.date_range(start='2018-01', freq='ME', periods=3))
+        >>> s
+        0   2018-01-31
+        1   2018-02-28
+        2   2018-03-31
+        dtype: datetime64[ns]
+        >>> s.dt.month_name()
+        0     January
+        1    February
+        2       March
+        dtype: object
+
+        >>> idx = pd.date_range(start='2018-01', freq='ME', periods=3)
+        >>> idx
+        DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'],
+                      dtype='datetime64[ns]', freq='ME')
+        >>> idx.month_name()
+        Index(['January', 'February', 'March'], dtype='object')
+
+        Using the ``locale`` parameter you can set a different locale language,
+        for example: ``idx.month_name(locale='pt_BR.utf8')`` will return month
+        names in Brazilian Portuguese language.
+
+        >>> idx = pd.date_range(start='2018-01', freq='ME', periods=3)
+        >>> idx
+        DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31'],
+                      dtype='datetime64[ns]', freq='ME')
+        >>> idx.month_name(locale='pt_BR.utf8')  # doctest: +SKIP
+        Index(['Janeiro', 'Fevereiro', 'Março'], dtype='object')
+        """
+        values = self._local_timestamps()
+
+        result = fields.get_date_name_field(
+            values, "month_name", locale=locale, reso=self._creso
+        )
+        result = self._maybe_mask_results(result, fill_value=None)
+        if using_string_dtype():
+            from pandas import (
+                StringDtype,
+                array as pd_array,
+            )
+
+            return pd_array(result, dtype=StringDtype(na_value=np.nan))  # type: ignore[return-value]
+        return result
+
+    def day_name(self, locale=None) -> npt.NDArray[np.object_]:
+        """
+        Return the day names with specified locale.
+
+        Parameters
+        ----------
+        locale : str, optional
+            Locale determining the language in which to return the day name.
+            Default is English locale (``'en_US.utf8'``). Use the command
+            ``locale -a`` on your terminal on Unix systems to find your locale
+            language code.
+
+        Returns
+        -------
+        Series or Index
+            Series or Index of day names.
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.date_range(start='2018-01-01', freq='D', periods=3))
+        >>> s
+        0   2018-01-01
+        1   2018-01-02
+        2   2018-01-03
+        dtype: datetime64[ns]
+        >>> s.dt.day_name()
+        0       Monday
+        1      Tuesday
+        2    Wednesday
+        dtype: object
+
+        >>> idx = pd.date_range(start='2018-01-01', freq='D', periods=3)
+        >>> idx
+        DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'],
+                      dtype='datetime64[ns]', freq='D')
+        >>> idx.day_name()
+        Index(['Monday', 'Tuesday', 'Wednesday'], dtype='object')
+
+        Using the ``locale`` parameter you can set a different locale language,
+        for example: ``idx.day_name(locale='pt_BR.utf8')`` will return day
+        names in Brazilian Portuguese language.
+
+        >>> idx = pd.date_range(start='2018-01-01', freq='D', periods=3)
+        >>> idx
+        DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03'],
+                      dtype='datetime64[ns]', freq='D')
+        >>> idx.day_name(locale='pt_BR.utf8') # doctest: +SKIP
+        Index(['Segunda', 'Terça', 'Quarta'], dtype='object')
+        """
+        values = self._local_timestamps()
+
+        result = fields.get_date_name_field(
+            values, "day_name", locale=locale, reso=self._creso
+        )
+        result = self._maybe_mask_results(result, fill_value=None)
+        if using_string_dtype():
+            # TODO: no tests that check for dtype of result as of 2024-08-15
+            from pandas import (
+                StringDtype,
+                array as pd_array,
+            )
+
+            return pd_array(result, dtype=StringDtype(na_value=np.nan))  # type: ignore[return-value]
+        return result
+
+    @property
+    def time(self) -> npt.NDArray[np.object_]:
+        """
+        Returns numpy array of :class:`datetime.time` objects.
+
+        The time part of the Timestamps.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.time
+        0    10:00:00
+        1    11:00:00
+        dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.time
+        array([datetime.time(10, 0), datetime.time(11, 0)], dtype=object)
+        """
+        # If the Timestamps have a timezone that is not UTC,
+        # convert them into their i8 representation while
+        # keeping their timezone and not using UTC
+        timestamps = self._local_timestamps()
+
+        return ints_to_pydatetime(timestamps, box="time", reso=self._creso)
+
+    @property
+    def timetz(self) -> npt.NDArray[np.object_]:
+        """
+        Returns numpy array of :class:`datetime.time` objects with timezones.
+
+        The time part of the Timestamps.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.timetz
+        0    10:00:00+00:00
+        1    11:00:00+00:00
+        dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.timetz
+        array([datetime.time(10, 0, tzinfo=datetime.timezone.utc),
+        datetime.time(11, 0, tzinfo=datetime.timezone.utc)], dtype=object)
+        """
+        return ints_to_pydatetime(self.asi8, self.tz, box="time", reso=self._creso)
+
+    @property
+    def date(self) -> npt.NDArray[np.object_]:
+        """
+        Returns numpy array of python :class:`datetime.date` objects.
+
+        Namely, the date part of Timestamps without time and
+        timezone information.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.date
+        0    2020-01-01
+        1    2020-02-01
+        dtype: object
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.date
+        array([datetime.date(2020, 1, 1), datetime.date(2020, 2, 1)], dtype=object)
+        """
+        # If the Timestamps have a timezone that is not UTC,
+        # convert them into their i8 representation while
+        # keeping their timezone and not using UTC
+        timestamps = self._local_timestamps()
+
+        return ints_to_pydatetime(timestamps, box="date", reso=self._creso)
+
+    def isocalendar(self) -> DataFrame:
+        """
+        Calculate year, week, and day according to the ISO 8601 standard.
+
+        Returns
+        -------
+        DataFrame
+            With columns year, week and day.
+
+        See Also
+        --------
+        Timestamp.isocalendar : Function return a 3-tuple containing ISO year,
+            week number, and weekday for the given Timestamp object.
+        datetime.date.isocalendar : Return a named tuple object with
+            three components: year, week and weekday.
+
+        Examples
+        --------
+        >>> idx = pd.date_range(start='2019-12-29', freq='D', periods=4)
+        >>> idx.isocalendar()
+                    year  week  day
+        2019-12-29  2019    52    7
+        2019-12-30  2020     1    1
+        2019-12-31  2020     1    2
+        2020-01-01  2020     1    3
+        >>> idx.isocalendar().week
+        2019-12-29    52
+        2019-12-30     1
+        2019-12-31     1
+        2020-01-01     1
+        Freq: D, Name: week, dtype: UInt32
+        """
+        from pandas import DataFrame
+
+        values = self._local_timestamps()
+        sarray = fields.build_isocalendar_sarray(values, reso=self._creso)
+        iso_calendar_df = DataFrame(
+            sarray, columns=["year", "week", "day"], dtype="UInt32"
+        )
+        if self._hasna:
+            iso_calendar_df.iloc[self._isnan] = None
+        return iso_calendar_df
+
+    year = _field_accessor(
+        "year",
+        "Y",
+        """
+        The year of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="YE")
+        ... )
+        >>> datetime_series
+        0   2000-12-31
+        1   2001-12-31
+        2   2002-12-31
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.year
+        0    2000
+        1    2001
+        2    2002
+        dtype: int32
+        """,
+    )
+    month = _field_accessor(
+        "month",
+        "M",
+        """
+        The month as January=1, December=12.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="ME")
+        ... )
+        >>> datetime_series
+        0   2000-01-31
+        1   2000-02-29
+        2   2000-03-31
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.month
+        0    1
+        1    2
+        2    3
+        dtype: int32
+        """,
+    )
+    day = _field_accessor(
+        "day",
+        "D",
+        """
+        The day of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="D")
+        ... )
+        >>> datetime_series
+        0   2000-01-01
+        1   2000-01-02
+        2   2000-01-03
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.day
+        0    1
+        1    2
+        2    3
+        dtype: int32
+        """,
+    )
+    hour = _field_accessor(
+        "hour",
+        "h",
+        """
+        The hours of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="h")
+        ... )
+        >>> datetime_series
+        0   2000-01-01 00:00:00
+        1   2000-01-01 01:00:00
+        2   2000-01-01 02:00:00
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.hour
+        0    0
+        1    1
+        2    2
+        dtype: int32
+        """,
+    )
+    minute = _field_accessor(
+        "minute",
+        "m",
+        """
+        The minutes of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="min")
+        ... )
+        >>> datetime_series
+        0   2000-01-01 00:00:00
+        1   2000-01-01 00:01:00
+        2   2000-01-01 00:02:00
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.minute
+        0    0
+        1    1
+        2    2
+        dtype: int32
+        """,
+    )
+    second = _field_accessor(
+        "second",
+        "s",
+        """
+        The seconds of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="s")
+        ... )
+        >>> datetime_series
+        0   2000-01-01 00:00:00
+        1   2000-01-01 00:00:01
+        2   2000-01-01 00:00:02
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.second
+        0    0
+        1    1
+        2    2
+        dtype: int32
+        """,
+    )
+    microsecond = _field_accessor(
+        "microsecond",
+        "us",
+        """
+        The microseconds of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="us")
+        ... )
+        >>> datetime_series
+        0   2000-01-01 00:00:00.000000
+        1   2000-01-01 00:00:00.000001
+        2   2000-01-01 00:00:00.000002
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.microsecond
+        0       0
+        1       1
+        2       2
+        dtype: int32
+        """,
+    )
+    nanosecond = _field_accessor(
+        "nanosecond",
+        "ns",
+        """
+        The nanoseconds of the datetime.
+
+        Examples
+        --------
+        >>> datetime_series = pd.Series(
+        ...     pd.date_range("2000-01-01", periods=3, freq="ns")
+        ... )
+        >>> datetime_series
+        0   2000-01-01 00:00:00.000000000
+        1   2000-01-01 00:00:00.000000001
+        2   2000-01-01 00:00:00.000000002
+        dtype: datetime64[ns]
+        >>> datetime_series.dt.nanosecond
+        0       0
+        1       1
+        2       2
+        dtype: int32
+        """,
+    )
+    _dayofweek_doc = """
+    The day of the week with Monday=0, Sunday=6.
+
+    Return the day of the week. It is assumed the week starts on
+    Monday, which is denoted by 0 and ends on Sunday which is denoted
+    by 6. This method is available on both Series with datetime
+    values (using the `dt` accessor) or DatetimeIndex.
+
+    Returns
+    -------
+    Series or Index
+        Containing integers indicating the day number.
+
+    See Also
+    --------
+    Series.dt.dayofweek : Alias.
+    Series.dt.weekday : Alias.
+    Series.dt.day_name : Returns the name of the day of the week.
+
+    Examples
+    --------
+    >>> s = pd.date_range('2016-12-31', '2017-01-08', freq='D').to_series()
+    >>> s.dt.dayofweek
+    2016-12-31    5
+    2017-01-01    6
+    2017-01-02    0
+    2017-01-03    1
+    2017-01-04    2
+    2017-01-05    3
+    2017-01-06    4
+    2017-01-07    5
+    2017-01-08    6
+    Freq: D, dtype: int32
+    """
+    day_of_week = _field_accessor("day_of_week", "dow", _dayofweek_doc)
+    dayofweek = day_of_week
+    weekday = day_of_week
+
+    day_of_year = _field_accessor(
+        "dayofyear",
+        "doy",
+        """
+        The ordinal day of the year.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.dayofyear
+        0    1
+        1   32
+        dtype: int32
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.dayofyear
+        Index([1, 32], dtype='int32')
+        """,
+    )
+    dayofyear = day_of_year
+    quarter = _field_accessor(
+        "quarter",
+        "q",
+        """
+        The quarter of the date.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "4/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-04-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.quarter
+        0    1
+        1    2
+        dtype: int32
+
+        For DatetimeIndex:
+
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00",
+        ...                         "2/1/2020 11:00:00+00:00"])
+        >>> idx.quarter
+        Index([1, 1], dtype='int32')
+        """,
+    )
+    days_in_month = _field_accessor(
+        "days_in_month",
+        "dim",
+        """
+        The number of days in the month.
+
+        Examples
+        --------
+        >>> s = pd.Series(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+        >>> s = pd.to_datetime(s)
+        >>> s
+        0   2020-01-01 10:00:00+00:00
+        1   2020-02-01 11:00:00+00:00
+        dtype: datetime64[ns, UTC]
+        >>> s.dt.daysinmonth
+        0    31
+        1    29
+        dtype: int32
+        """,
+    )
+    daysinmonth = days_in_month
+    _is_month_doc = """
+        Indicates whether the date is the {first_or_last} day of the month.
+
+        Returns
+        -------
+        Series or array
+            For Series, returns a Series with boolean values.
+            For DatetimeIndex, returns a boolean array.
+
+        See Also
+        --------
+        is_month_start : Return a boolean indicating whether the date
+            is the first day of the month.
+        is_month_end : Return a boolean indicating whether the date
+            is the last day of the month.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> s = pd.Series(pd.date_range("2018-02-27", periods=3))
+        >>> s
+        0   2018-02-27
+        1   2018-02-28
+        2   2018-03-01
+        dtype: datetime64[ns]
+        >>> s.dt.is_month_start
+        0    False
+        1    False
+        2    True
+        dtype: bool
+        >>> s.dt.is_month_end
+        0    False
+        1    True
+        2    False
+        dtype: bool
+
+        >>> idx = pd.date_range("2018-02-27", periods=3)
+        >>> idx.is_month_start
+        array([False, False, True])
+        >>> idx.is_month_end
+        array([False, True, False])
+    """
+    is_month_start = _field_accessor(
+        "is_month_start", "is_month_start", _is_month_doc.format(first_or_last="first")
+    )
+
+    is_month_end = _field_accessor(
+        "is_month_end", "is_month_end", _is_month_doc.format(first_or_last="last")
+    )
+
+    is_quarter_start = _field_accessor(
+        "is_quarter_start",
+        "is_quarter_start",
+        """
+        Indicator for whether the date is the first day of a quarter.
+
+        Returns
+        -------
+        is_quarter_start : Series or DatetimeIndex
+            The same type as the original data with boolean values. Series will
+            have the same name and index. DatetimeIndex will have the same
+            name.
+
+        See Also
+        --------
+        quarter : Return the quarter of the date.
+        is_quarter_end : Similar property for indicating the quarter end.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> df = pd.DataFrame({'dates': pd.date_range("2017-03-30",
+        ...                   periods=4)})
+        >>> df.assign(quarter=df.dates.dt.quarter,
+        ...           is_quarter_start=df.dates.dt.is_quarter_start)
+               dates  quarter  is_quarter_start
+        0 2017-03-30        1             False
+        1 2017-03-31        1             False
+        2 2017-04-01        2              True
+        3 2017-04-02        2             False
+
+        >>> idx = pd.date_range('2017-03-30', periods=4)
+        >>> idx
+        DatetimeIndex(['2017-03-30', '2017-03-31', '2017-04-01', '2017-04-02'],
+                      dtype='datetime64[ns]', freq='D')
+
+        >>> idx.is_quarter_start
+        array([False, False,  True, False])
+        """,
+    )
+    is_quarter_end = _field_accessor(
+        "is_quarter_end",
+        "is_quarter_end",
+        """
+        Indicator for whether the date is the last day of a quarter.
+
+        Returns
+        -------
+        is_quarter_end : Series or DatetimeIndex
+            The same type as the original data with boolean values. Series will
+            have the same name and index. DatetimeIndex will have the same
+            name.
+
+        See Also
+        --------
+        quarter : Return the quarter of the date.
+        is_quarter_start : Similar property indicating the quarter start.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> df = pd.DataFrame({'dates': pd.date_range("2017-03-30",
+        ...                    periods=4)})
+        >>> df.assign(quarter=df.dates.dt.quarter,
+        ...           is_quarter_end=df.dates.dt.is_quarter_end)
+               dates  quarter    is_quarter_end
+        0 2017-03-30        1             False
+        1 2017-03-31        1              True
+        2 2017-04-01        2             False
+        3 2017-04-02        2             False
+
+        >>> idx = pd.date_range('2017-03-30', periods=4)
+        >>> idx
+        DatetimeIndex(['2017-03-30', '2017-03-31', '2017-04-01', '2017-04-02'],
+                      dtype='datetime64[ns]', freq='D')
+
+        >>> idx.is_quarter_end
+        array([False,  True, False, False])
+        """,
+    )
+    is_year_start = _field_accessor(
+        "is_year_start",
+        "is_year_start",
+        """
+        Indicate whether the date is the first day of a year.
+
+        Returns
+        -------
+        Series or DatetimeIndex
+            The same type as the original data with boolean values. Series will
+            have the same name and index. DatetimeIndex will have the same
+            name.
+
+        See Also
+        --------
+        is_year_end : Similar property indicating the last day of the year.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> dates = pd.Series(pd.date_range("2017-12-30", periods=3))
+        >>> dates
+        0   2017-12-30
+        1   2017-12-31
+        2   2018-01-01
+        dtype: datetime64[ns]
+
+        >>> dates.dt.is_year_start
+        0    False
+        1    False
+        2    True
+        dtype: bool
+
+        >>> idx = pd.date_range("2017-12-30", periods=3)
+        >>> idx
+        DatetimeIndex(['2017-12-30', '2017-12-31', '2018-01-01'],
+                      dtype='datetime64[ns]', freq='D')
+
+        >>> idx.is_year_start
+        array([False, False,  True])
+        """,
+    )
+    is_year_end = _field_accessor(
+        "is_year_end",
+        "is_year_end",
+        """
+        Indicate whether the date is the last day of the year.
+
+        Returns
+        -------
+        Series or DatetimeIndex
+            The same type as the original data with boolean values. Series will
+            have the same name and index. DatetimeIndex will have the same
+            name.
+
+        See Also
+        --------
+        is_year_start : Similar property indicating the start of the year.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> dates = pd.Series(pd.date_range("2017-12-30", periods=3))
+        >>> dates
+        0   2017-12-30
+        1   2017-12-31
+        2   2018-01-01
+        dtype: datetime64[ns]
+
+        >>> dates.dt.is_year_end
+        0    False
+        1     True
+        2    False
+        dtype: bool
+
+        >>> idx = pd.date_range("2017-12-30", periods=3)
+        >>> idx
+        DatetimeIndex(['2017-12-30', '2017-12-31', '2018-01-01'],
+                      dtype='datetime64[ns]', freq='D')
+
+        >>> idx.is_year_end
+        array([False,  True, False])
+        """,
+    )
+    is_leap_year = _field_accessor(
+        "is_leap_year",
+        "is_leap_year",
+        """
+        Boolean indicator if the date belongs to a leap year.
+
+        A leap year is a year, which has 366 days (instead of 365) including
+        29th of February as an intercalary day.
+        Leap years are years which are multiples of four with the exception
+        of years divisible by 100 but not by 400.
+
+        Returns
+        -------
+        Series or ndarray
+             Booleans indicating if dates belong to a leap year.
+
+        Examples
+        --------
+        This method is available on Series with datetime values under
+        the ``.dt`` accessor, and directly on DatetimeIndex.
+
+        >>> idx = pd.date_range("2012-01-01", "2015-01-01", freq="YE")
+        >>> idx
+        DatetimeIndex(['2012-12-31', '2013-12-31', '2014-12-31'],
+                      dtype='datetime64[ns]', freq='YE-DEC')
+        >>> idx.is_leap_year
+        array([ True, False, False])
+
+        >>> dates_series = pd.Series(idx)
+        >>> dates_series
+        0   2012-12-31
+        1   2013-12-31
+        2   2014-12-31
+        dtype: datetime64[ns]
+        >>> dates_series.dt.is_leap_year
+        0     True
+        1    False
+        2    False
+        dtype: bool
+        """,
+    )
+
+    def to_julian_date(self) -> npt.NDArray[np.float64]:
+        """
+        Convert Datetime Array to float64 ndarray of Julian Dates.
+        0 Julian date is noon January 1, 4713 BC.
+        https://en.wikipedia.org/wiki/Julian_day
+        """
+
+        # http://mysite.verizon.net/aesir_research/date/jdalg2.htm
+        year = np.asarray(self.year)
+        month = np.asarray(self.month)
+        day = np.asarray(self.day)
+        testarr = month < 3
+        year[testarr] -= 1
+        month[testarr] += 12
+        return (
+            day
+            + np.fix((153 * month - 457) / 5)
+            + 365 * year
+            + np.floor(year / 4)
+            - np.floor(year / 100)
+            + np.floor(year / 400)
+            + 1_721_118.5
+            + (
+                self.hour
+                + self.minute / 60
+                + self.second / 3600
+                + self.microsecond / 3600 / 10**6
+                + self.nanosecond / 3600 / 10**9
+            )
+            / 24
+        )
+
+    # -----------------------------------------------------------------
+    # Reductions
+
+    def std(
+        self,
+        axis=None,
+        dtype=None,
+        out=None,
+        ddof: int = 1,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        """
+        Return sample standard deviation over requested axis.
+
+        Normalized by `N-1` by default. This can be changed using ``ddof``.
+
+        Parameters
+        ----------
+        axis : int, optional
+            Axis for the function to be applied on. For :class:`pandas.Series`
+            this parameter is unused and defaults to ``None``.
+        ddof : int, default 1
+            Degrees of Freedom. The divisor used in calculations is `N - ddof`,
+            where `N` represents the number of elements.
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is ``NA``, the result
+            will be ``NA``.
+
+        Returns
+        -------
+        Timedelta
+
+        See Also
+        --------
+        numpy.ndarray.std : Returns the standard deviation of the array elements
+            along given axis.
+        Series.std : Return sample standard deviation over requested axis.
+
+        Examples
+        --------
+        For :class:`pandas.DatetimeIndex`:
+
+        >>> idx = pd.date_range('2001-01-01 00:00', periods=3)
+        >>> idx
+        DatetimeIndex(['2001-01-01', '2001-01-02', '2001-01-03'],
+                      dtype='datetime64[ns]', freq='D')
+        >>> idx.std()
+        Timedelta('1 days 00:00:00')
+        """
+        # Because std is translation-invariant, we can get self.std
+        #  by calculating (self - Timestamp(0)).std, and we can do it
+        #  without creating a copy by using a view on self._ndarray
+        from pandas.core.arrays import TimedeltaArray
+
+        # Find the td64 dtype with the same resolution as our dt64 dtype
+        dtype_str = self._ndarray.dtype.name.replace("datetime64", "timedelta64")
+        dtype = np.dtype(dtype_str)
+
+        tda = TimedeltaArray._simple_new(self._ndarray.view(dtype), dtype=dtype)
+
+        return tda.std(axis=axis, out=out, ddof=ddof, keepdims=keepdims, skipna=skipna)
+
+
+# -------------------------------------------------------------------
+# Constructor Helpers
+
+
+def _sequence_to_dt64(
+    data: ArrayLike,
+    *,
+    copy: bool = False,
+    tz: tzinfo | None = None,
+    dayfirst: bool = False,
+    yearfirst: bool = False,
+    ambiguous: TimeAmbiguous = "raise",
+    out_unit: str | None = None,
+):
+    """
+    Parameters
+    ----------
+    data : np.ndarray or ExtensionArray
+        dtl.ensure_arraylike_for_datetimelike has already been called.
+    copy : bool, default False
+    tz : tzinfo or None, default None
+    dayfirst : bool, default False
+    yearfirst : bool, default False
+    ambiguous : str, bool, or arraylike, default 'raise'
+        See pandas._libs.tslibs.tzconversion.tz_localize_to_utc.
+    out_unit : str or None, default None
+        Desired output resolution.
+
+    Returns
+    -------
+    result : numpy.ndarray
+        The sequence converted to a numpy array with dtype ``datetime64[unit]``.
+        Where `unit` is "ns" unless specified otherwise by `out_unit`.
+    tz : tzinfo or None
+        Either the user-provided tzinfo or one inferred from the data.
+
+    Raises
+    ------
+    TypeError : PeriodDType data is passed
+    """
+
+    # By this point we are assured to have either a numpy array or Index
+    data, copy = maybe_convert_dtype(data, copy, tz=tz)
+    data_dtype = getattr(data, "dtype", None)
+
+    if out_unit is None:
+        out_unit = "ns"
+    out_dtype = np.dtype(f"M8[{out_unit}]")
+
+    if data_dtype == object or is_string_dtype(data_dtype):
+        # TODO: We do not have tests specific to string-dtypes,
+        #  also complex or categorical or other extension
+        data = cast(np.ndarray, data)
+        copy = False
+        if lib.infer_dtype(data, skipna=False) == "integer":
+            # Much more performant than going through array_to_datetime
+            data = data.astype(np.int64)
+        elif tz is not None and ambiguous == "raise":
+            obj_data = np.asarray(data, dtype=object)
+            result = tslib.array_to_datetime_with_tz(
+                obj_data,
+                tz=tz,
+                dayfirst=dayfirst,
+                yearfirst=yearfirst,
+                creso=abbrev_to_npy_unit(out_unit),
+            )
+            return result, tz
+        else:
+            converted, inferred_tz = objects_to_datetime64(
+                data,
+                dayfirst=dayfirst,
+                yearfirst=yearfirst,
+                allow_object=False,
+                out_unit=out_unit or "ns",
+            )
+            copy = False
+            if tz and inferred_tz:
+                #  two timezones: convert to intended from base UTC repr
+                # GH#42505 by convention, these are _already_ UTC
+                result = converted
+
+            elif inferred_tz:
+                tz = inferred_tz
+                result = converted
+
+            else:
+                result, _ = _construct_from_dt64_naive(
+                    converted, tz=tz, copy=copy, ambiguous=ambiguous
+                )
+            return result, tz
+
+        data_dtype = data.dtype
+
+    # `data` may have originally been a Categorical[datetime64[ns, tz]],
+    # so we need to handle these types.
+    if isinstance(data_dtype, DatetimeTZDtype):
+        # DatetimeArray -> ndarray
+        data = cast(DatetimeArray, data)
+        tz = _maybe_infer_tz(tz, data.tz)
+        result = data._ndarray
+
+    elif lib.is_np_dtype(data_dtype, "M"):
+        # tz-naive DatetimeArray or ndarray[datetime64]
+        if isinstance(data, DatetimeArray):
+            data = data._ndarray
+
+        data = cast(np.ndarray, data)
+        result, copy = _construct_from_dt64_naive(
+            data, tz=tz, copy=copy, ambiguous=ambiguous
+        )
+
+    else:
+        # must be integer dtype otherwise
+        # assume this data are epoch timestamps
+        if data.dtype != INT64_DTYPE:
+            data = data.astype(np.int64, copy=False)
+            copy = False
+        data = cast(np.ndarray, data)
+        result = data.view(out_dtype)
+
+    if copy:
+        result = result.copy()
+
+    assert isinstance(result, np.ndarray), type(result)
+    assert result.dtype.kind == "M"
+    assert result.dtype != "M8"
+    assert is_supported_dtype(result.dtype)
+    return result, tz
+
+
+def _construct_from_dt64_naive(
+    data: np.ndarray, *, tz: tzinfo | None, copy: bool, ambiguous: TimeAmbiguous
+) -> tuple[np.ndarray, bool]:
+    """
+    Convert datetime64 data to a supported dtype, localizing if necessary.
+    """
+    # Caller is responsible for ensuring
+    #  lib.is_np_dtype(data.dtype)
+
+    new_dtype = data.dtype
+    if not is_supported_dtype(new_dtype):
+        # Cast to the nearest supported unit, generally "s"
+        new_dtype = get_supported_dtype(new_dtype)
+        data = astype_overflowsafe(data, dtype=new_dtype, copy=False)
+        copy = False
+
+    if data.dtype.byteorder == ">":
+        # TODO: better way to handle this?  non-copying alternative?
+        #  without this, test_constructor_datetime64_bigendian fails
+        data = data.astype(data.dtype.newbyteorder("<"))
+        new_dtype = data.dtype
+        copy = False
+
+    if tz is not None:
+        # Convert tz-naive to UTC
+        # TODO: if tz is UTC, are there situations where we *don't* want a
+        #  copy?  tz_localize_to_utc always makes one.
+        shape = data.shape
+        if data.ndim > 1:
+            data = data.ravel()
+
+        data_unit = get_unit_from_dtype(new_dtype)
+        data = tzconversion.tz_localize_to_utc(
+            data.view("i8"), tz, ambiguous=ambiguous, creso=data_unit
+        )
+        data = data.view(new_dtype)
+        data = data.reshape(shape)
+
+    assert data.dtype == new_dtype, data.dtype
+    result = data
+
+    return result, copy
+
+
+def objects_to_datetime64(
+    data: np.ndarray,
+    dayfirst,
+    yearfirst,
+    utc: bool = False,
+    errors: DateTimeErrorChoices = "raise",
+    allow_object: bool = False,
+    out_unit: str = "ns",
+):
+    """
+    Convert data to array of timestamps.
+
+    Parameters
+    ----------
+    data : np.ndarray[object]
+    dayfirst : bool
+    yearfirst : bool
+    utc : bool, default False
+        Whether to convert/localize timestamps to UTC.
+    errors : {'raise', 'ignore', 'coerce'}
+    allow_object : bool
+        Whether to return an object-dtype ndarray instead of raising if the
+        data contains more than one timezone.
+    out_unit : str, default "ns"
+
+    Returns
+    -------
+    result : ndarray
+        np.datetime64[out_unit] if returned values represent wall times or UTC
+        timestamps.
+        object if mixed timezones
+    inferred_tz : tzinfo or None
+        If not None, then the datetime64 values in `result` denote UTC timestamps.
+
+    Raises
+    ------
+    ValueError : if data cannot be converted to datetimes
+    TypeError  : When a type cannot be converted to datetime
+    """
+    assert errors in ["raise", "ignore", "coerce"]
+
+    # if str-dtype, convert
+    data = np.asarray(data, dtype=np.object_)
+
+    result, tz_parsed = tslib.array_to_datetime(
+        data,
+        errors=errors,
+        utc=utc,
+        dayfirst=dayfirst,
+        yearfirst=yearfirst,
+        creso=abbrev_to_npy_unit(out_unit),
+    )
+
+    if tz_parsed is not None:
+        # We can take a shortcut since the datetime64 numpy array
+        #  is in UTC
+        return result, tz_parsed
+    elif result.dtype.kind == "M":
+        return result, tz_parsed
+    elif result.dtype == object:
+        # GH#23675 when called via `pd.to_datetime`, returning an object-dtype
+        #  array is allowed.  When called via `pd.DatetimeIndex`, we can
+        #  only accept datetime64 dtype, so raise TypeError if object-dtype
+        #  is returned, as that indicates the values can be recognized as
+        #  datetimes but they have conflicting timezones/awareness
+        if allow_object:
+            return result, tz_parsed
+        raise TypeError("DatetimeIndex has mixed timezones")
+    else:  # pragma: no cover
+        # GH#23675 this TypeError should never be hit, whereas the TypeError
+        #  in the object-dtype branch above is reachable.
+        raise TypeError(result)
+
+
+def maybe_convert_dtype(data, copy: bool, tz: tzinfo | None = None):
+    """
+    Convert data based on dtype conventions, issuing
+    errors where appropriate.
+
+    Parameters
+    ----------
+    data : np.ndarray or pd.Index
+    copy : bool
+    tz : tzinfo or None, default None
+
+    Returns
+    -------
+    data : np.ndarray or pd.Index
+    copy : bool
+
+    Raises
+    ------
+    TypeError : PeriodDType data is passed
+    """
+    if not hasattr(data, "dtype"):
+        # e.g. collections.deque
+        return data, copy
+
+    if is_float_dtype(data.dtype):
+        # pre-2.0 we treated these as wall-times, inconsistent with ints
+        # GH#23675, GH#45573 deprecated to treat symmetrically with integer dtypes.
+        # Note: data.astype(np.int64) fails ARM tests, see
+        # https://github.com/pandas-dev/pandas/issues/49468.
+        data = data.astype(DT64NS_DTYPE).view("i8")
+        copy = False
+
+    elif lib.is_np_dtype(data.dtype, "m") or is_bool_dtype(data.dtype):
+        # GH#29794 enforcing deprecation introduced in GH#23539
+        raise TypeError(f"dtype {data.dtype} cannot be converted to datetime64[ns]")
+    elif isinstance(data.dtype, PeriodDtype):
+        # Note: without explicitly raising here, PeriodIndex
+        #  test_setops.test_join_does_not_recur fails
+        raise TypeError(
+            "Passing PeriodDtype data is invalid. Use `data.to_timestamp()` instead"
+        )
+
+    elif isinstance(data.dtype, ExtensionDtype) and not isinstance(
+        data.dtype, DatetimeTZDtype
+    ):
+        # TODO: We have no tests for these
+        data = np.array(data, dtype=np.object_)
+        copy = False
+
+    return data, copy
+
+
+# -------------------------------------------------------------------
+# Validation and Inference
+
+
+def _maybe_infer_tz(tz: tzinfo | None, inferred_tz: tzinfo | None) -> tzinfo | None:
+    """
+    If a timezone is inferred from data, check that it is compatible with
+    the user-provided timezone, if any.
+
+    Parameters
+    ----------
+    tz : tzinfo or None
+    inferred_tz : tzinfo or None
+
+    Returns
+    -------
+    tz : tzinfo or None
+
+    Raises
+    ------
+    TypeError : if both timezones are present but do not match
+    """
+    if tz is None:
+        tz = inferred_tz
+    elif inferred_tz is None:
+        pass
+    elif not timezones.tz_compare(tz, inferred_tz):
+        raise TypeError(
+            f"data is already tz-aware {inferred_tz}, unable to "
+            f"set specified tz: {tz}"
+        )
+    return tz
+
+
+def _validate_dt64_dtype(dtype):
+    """
+    Check that a dtype, if passed, represents either a numpy datetime64[ns]
+    dtype or a pandas DatetimeTZDtype.
+
+    Parameters
+    ----------
+    dtype : object
+
+    Returns
+    -------
+    dtype : None, numpy.dtype, or DatetimeTZDtype
+
+    Raises
+    ------
+    ValueError : invalid dtype
+
+    Notes
+    -----
+    Unlike _validate_tz_from_dtype, this does _not_ allow non-existent
+    tz errors to go through
+    """
+    if dtype is not None:
+        dtype = pandas_dtype(dtype)
+        if dtype == np.dtype("M8"):
+            # no precision, disallowed GH#24806
+            msg = (
+                "Passing in 'datetime64' dtype with no precision is not allowed. "
+                "Please pass in 'datetime64[ns]' instead."
+            )
+            raise ValueError(msg)
+
+        if (
+            isinstance(dtype, np.dtype)
+            and (dtype.kind != "M" or not is_supported_dtype(dtype))
+        ) or not isinstance(dtype, (np.dtype, DatetimeTZDtype)):
+            raise ValueError(
+                f"Unexpected value for 'dtype': '{dtype}'. "
+                "Must be 'datetime64[s]', 'datetime64[ms]', 'datetime64[us]', "
+                "'datetime64[ns]' or DatetimeTZDtype'."
+            )
+
+        if getattr(dtype, "tz", None):
+            # https://github.com/pandas-dev/pandas/issues/18595
+            # Ensure that we have a standard timezone for pytz objects.
+            # Without this, things like adding an array of timedeltas and
+            # a  tz-aware Timestamp (with a tz specific to its datetime) will
+            # be incorrect(ish?) for the array as a whole
+            dtype = cast(DatetimeTZDtype, dtype)
+            dtype = DatetimeTZDtype(
+                unit=dtype.unit, tz=timezones.tz_standardize(dtype.tz)
+            )
+
+    return dtype
+
+
+def _validate_tz_from_dtype(
+    dtype, tz: tzinfo | None, explicit_tz_none: bool = False
+) -> tzinfo | None:
+    """
+    If the given dtype is a DatetimeTZDtype, extract the implied
+    tzinfo object from it and check that it does not conflict with the given
+    tz.
+
+    Parameters
+    ----------
+    dtype : dtype, str
+    tz : None, tzinfo
+    explicit_tz_none : bool, default False
+        Whether tz=None was passed explicitly, as opposed to lib.no_default.
+
+    Returns
+    -------
+    tz : consensus tzinfo
+
+    Raises
+    ------
+    ValueError : on tzinfo mismatch
+    """
+    if dtype is not None:
+        if isinstance(dtype, str):
+            try:
+                dtype = DatetimeTZDtype.construct_from_string(dtype)
+            except TypeError:
+                # Things like `datetime64[ns]`, which is OK for the
+                # constructors, but also nonsense, which should be validated
+                # but not by us. We *do* allow non-existent tz errors to
+                # go through
+                pass
+        dtz = getattr(dtype, "tz", None)
+        if dtz is not None:
+            if tz is not None and not timezones.tz_compare(tz, dtz):
+                raise ValueError("cannot supply both a tz and a dtype with a tz")
+            if explicit_tz_none:
+                raise ValueError("Cannot pass both a timezone-aware dtype and tz=None")
+            tz = dtz
+
+        if tz is not None and lib.is_np_dtype(dtype, "M"):
+            # We also need to check for the case where the user passed a
+            #  tz-naive dtype (i.e. datetime64[ns])
+            if tz is not None and not timezones.tz_compare(tz, dtz):
+                raise ValueError(
+                    "cannot supply both a tz and a "
+                    "timezone-naive dtype (i.e. datetime64[ns])"
+                )
+
+    return tz
+
+
+def _infer_tz_from_endpoints(
+    start: Timestamp, end: Timestamp, tz: tzinfo | None
+) -> tzinfo | None:
+    """
+    If a timezone is not explicitly given via `tz`, see if one can
+    be inferred from the `start` and `end` endpoints.  If more than one
+    of these inputs provides a timezone, require that they all agree.
+
+    Parameters
+    ----------
+    start : Timestamp
+    end : Timestamp
+    tz : tzinfo or None
+
+    Returns
+    -------
+    tz : tzinfo or None
+
+    Raises
+    ------
+    TypeError : if start and end timezones do not agree
+    """
+    try:
+        inferred_tz = timezones.infer_tzinfo(start, end)
+    except AssertionError as err:
+        # infer_tzinfo raises AssertionError if passed mismatched timezones
+        raise TypeError(
+            "Start and end cannot both be tz-aware with different timezones"
+        ) from err
+
+    inferred_tz = timezones.maybe_get_tz(inferred_tz)
+    tz = timezones.maybe_get_tz(tz)
+
+    if tz is not None and inferred_tz is not None:
+        if not timezones.tz_compare(inferred_tz, tz):
+            raise AssertionError("Inferred time zone not equal to passed time zone")
+
+    elif inferred_tz is not None:
+        tz = inferred_tz
+
+    return tz
+
+
+def _maybe_normalize_endpoints(
+    start: Timestamp | None, end: Timestamp | None, normalize: bool
+):
+    if normalize:
+        if start is not None:
+            start = start.normalize()
+
+        if end is not None:
+            end = end.normalize()
+
+    return start, end
+
+
+def _maybe_localize_point(
+    ts: Timestamp | None, freq, tz, ambiguous, nonexistent
+) -> Timestamp | None:
+    """
+    Localize a start or end Timestamp to the timezone of the corresponding
+    start or end Timestamp
+
+    Parameters
+    ----------
+    ts : start or end Timestamp to potentially localize
+    freq : Tick, DateOffset, or None
+    tz : str, timezone object or None
+    ambiguous: str, localization behavior for ambiguous times
+    nonexistent: str, localization behavior for nonexistent times
+
+    Returns
+    -------
+    ts : Timestamp
+    """
+    # Make sure start and end are timezone localized if:
+    # 1) freq = a Timedelta-like frequency (Tick)
+    # 2) freq = None i.e. generating a linspaced range
+    if ts is not None and ts.tzinfo is None:
+        # Note: We can't ambiguous='infer' a singular ambiguous time; however,
+        # we have historically defaulted ambiguous=False
+        ambiguous = ambiguous if ambiguous != "infer" else False
+        localize_args = {"ambiguous": ambiguous, "nonexistent": nonexistent, "tz": None}
+        if isinstance(freq, Tick) or freq is None:
+            localize_args["tz"] = tz
+        ts = ts.tz_localize(**localize_args)
+    return ts
+
+
+def _generate_range(
+    start: Timestamp | None,
+    end: Timestamp | None,
+    periods: int | None,
+    offset: BaseOffset,
+    *,
+    unit: str,
+):
+    """
+    Generates a sequence of dates corresponding to the specified time
+    offset. Similar to dateutil.rrule except uses pandas DateOffset
+    objects to represent time increments.
+
+    Parameters
+    ----------
+    start : Timestamp or None
+    end : Timestamp or None
+    periods : int or None
+    offset : DateOffset
+    unit : str
+
+    Notes
+    -----
+    * This method is faster for generating weekdays than dateutil.rrule
+    * At least two of (start, end, periods) must be specified.
+    * If both start and end are specified, the returned dates will
+    satisfy start <= date <= end.
+
+    Returns
+    -------
+    dates : generator object
+    """
+    offset = to_offset(offset)
+
+    # Argument 1 to "Timestamp" has incompatible type "Optional[Timestamp]";
+    # expected "Union[integer[Any], float, str, date, datetime64]"
+    start = Timestamp(start)  # type: ignore[arg-type]
+    if start is not NaT:
+        start = start.as_unit(unit)
+    else:
+        start = None
+
+    # Argument 1 to "Timestamp" has incompatible type "Optional[Timestamp]";
+    # expected "Union[integer[Any], float, str, date, datetime64]"
+    end = Timestamp(end)  # type: ignore[arg-type]
+    if end is not NaT:
+        end = end.as_unit(unit)
+    else:
+        end = None
+
+    if start and not offset.is_on_offset(start):
+        # Incompatible types in assignment (expression has type "datetime",
+        # variable has type "Optional[Timestamp]")
+        start = offset.rollforward(start)  # type: ignore[assignment]
+
+    elif end and not offset.is_on_offset(end):
+        # Incompatible types in assignment (expression has type "datetime",
+        # variable has type "Optional[Timestamp]")
+        end = offset.rollback(end)  # type: ignore[assignment]
+
+    # Unsupported operand types for < ("Timestamp" and "None")
+    if periods is None and end < start and offset.n >= 0:  # type: ignore[operator]
+        end = None
+        periods = 0
+
+    if end is None:
+        # error: No overload variant of "__radd__" of "BaseOffset" matches
+        # argument type "None"
+        end = start + (periods - 1) * offset  # type: ignore[operator]
+
+    if start is None:
+        # error: No overload variant of "__radd__" of "BaseOffset" matches
+        # argument type "None"
+        start = end - (periods - 1) * offset  # type: ignore[operator]
+
+    start = cast(Timestamp, start)
+    end = cast(Timestamp, end)
+
+    cur = start
+    if offset.n >= 0:
+        while cur <= end:
+            yield cur
+
+            if cur == end:
+                # GH#24252 avoid overflows by not performing the addition
+                # in offset.apply unless we have to
+                break
+
+            # faster than cur + offset
+            next_date = offset._apply(cur)
+            next_date = next_date.as_unit(unit)
+            if next_date <= cur:
+                raise ValueError(f"Offset {offset} did not increment date")
+            cur = next_date
+    else:
+        while cur >= end:
+            yield cur
+
+            if cur == end:
+                # GH#24252 avoid overflows by not performing the addition
+                # in offset.apply unless we have to
+                break
+
+            # faster than cur + offset
+            next_date = offset._apply(cur)
+            next_date = next_date.as_unit(unit)
+            if next_date >= cur:
+                raise ValueError(f"Offset {offset} did not decrement date")
+            cur = next_date
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/floating.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/floating.py
new file mode 100644
index 0000000000000000000000000000000000000000..74b8cfb65cbc7887b7d2a164121c90eda0833121
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/floating.py
@@ -0,0 +1,173 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+import numpy as np
+
+from pandas.core.dtypes.base import register_extension_dtype
+from pandas.core.dtypes.common import is_float_dtype
+
+from pandas.core.arrays.numeric import (
+    NumericArray,
+    NumericDtype,
+)
+
+
+class FloatingDtype(NumericDtype):
+    """
+    An ExtensionDtype to hold a single size of floating dtype.
+
+    These specific implementations are subclasses of the non-public
+    FloatingDtype. For example we have Float32Dtype to represent float32.
+
+    The attributes name & type are set when these subclasses are created.
+    """
+
+    _default_np_dtype = np.dtype(np.float64)
+    _checker = is_float_dtype
+
+    @classmethod
+    def construct_array_type(cls) -> type[FloatingArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        return FloatingArray
+
+    @classmethod
+    def _get_dtype_mapping(cls) -> dict[np.dtype, FloatingDtype]:
+        return NUMPY_FLOAT_TO_DTYPE
+
+    @classmethod
+    def _safe_cast(cls, values: np.ndarray, dtype: np.dtype, copy: bool) -> np.ndarray:
+        """
+        Safely cast the values to the given dtype.
+
+        "safe" in this context means the casting is lossless.
+        """
+        # This is really only here for compatibility with IntegerDtype
+        # Here for compat with IntegerDtype
+        return values.astype(dtype, copy=copy)
+
+
+class FloatingArray(NumericArray):
+    """
+    Array of floating (optional missing) values.
+
+    .. warning::
+
+       FloatingArray is currently experimental, and its API or internal
+       implementation may change without warning. Especially the behaviour
+       regarding NaN (distinct from NA missing values) is subject to change.
+
+    We represent a FloatingArray with 2 numpy arrays:
+
+    - data: contains a numpy float array of the appropriate dtype
+    - mask: a boolean array holding a mask on the data, True is missing
+
+    To construct an FloatingArray from generic array-like input, use
+    :func:`pandas.array` with one of the float dtypes (see examples).
+
+    See :ref:`integer_na` for more.
+
+    Parameters
+    ----------
+    values : numpy.ndarray
+        A 1-d float-dtype array.
+    mask : numpy.ndarray
+        A 1-d boolean-dtype array indicating missing values.
+    copy : bool, default False
+        Whether to copy the `values` and `mask`.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Returns
+    -------
+    FloatingArray
+
+    Examples
+    --------
+    Create an FloatingArray with :func:`pandas.array`:
+
+    >>> pd.array([0.1, None, 0.3], dtype=pd.Float32Dtype())
+    
+    [0.1, , 0.3]
+    Length: 3, dtype: Float32
+
+    String aliases for the dtypes are also available. They are capitalized.
+
+    >>> pd.array([0.1, None, 0.3], dtype="Float32")
+    
+    [0.1, , 0.3]
+    Length: 3, dtype: Float32
+    """
+
+    _dtype_cls = FloatingDtype
+
+    # The value used to fill '_data' to avoid upcasting
+    _internal_fill_value = np.nan
+    # Fill values used for any/all
+    # Incompatible types in assignment (expression has type "float", base class
+    # "BaseMaskedArray" defined the type as "")
+    _truthy_value = 1.0  # type: ignore[assignment]
+    _falsey_value = 0.0  # type: ignore[assignment]
+
+
+_dtype_docstring = """
+An ExtensionDtype for {dtype} data.
+
+This dtype uses ``pd.NA`` as missing value indicator.
+
+Attributes
+----------
+None
+
+Methods
+-------
+None
+
+Examples
+--------
+For Float32Dtype:
+
+>>> ser = pd.Series([2.25, pd.NA], dtype=pd.Float32Dtype())
+>>> ser.dtype
+Float32Dtype()
+
+For Float64Dtype:
+
+>>> ser = pd.Series([2.25, pd.NA], dtype=pd.Float64Dtype())
+>>> ser.dtype
+Float64Dtype()
+"""
+
+# create the Dtype
+
+
+@register_extension_dtype
+class Float32Dtype(FloatingDtype):
+    type = np.float32
+    name: ClassVar[str] = "Float32"
+    __doc__ = _dtype_docstring.format(dtype="float32")
+
+
+@register_extension_dtype
+class Float64Dtype(FloatingDtype):
+    type = np.float64
+    name: ClassVar[str] = "Float64"
+    __doc__ = _dtype_docstring.format(dtype="float64")
+
+
+NUMPY_FLOAT_TO_DTYPE: dict[np.dtype, FloatingDtype] = {
+    np.dtype(np.float32): Float32Dtype(),
+    np.dtype(np.float64): Float64Dtype(),
+}
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/integer.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/integer.py
new file mode 100644
index 0000000000000000000000000000000000000000..f9384e25ba9d9f32caf826efc01b4eb58a454d65
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/integer.py
@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from typing import ClassVar
+
+import numpy as np
+
+from pandas.core.dtypes.base import register_extension_dtype
+from pandas.core.dtypes.common import is_integer_dtype
+
+from pandas.core.arrays.numeric import (
+    NumericArray,
+    NumericDtype,
+)
+
+
+class IntegerDtype(NumericDtype):
+    """
+    An ExtensionDtype to hold a single size & kind of integer dtype.
+
+    These specific implementations are subclasses of the non-public
+    IntegerDtype. For example, we have Int8Dtype to represent signed int 8s.
+
+    The attributes name & type are set when these subclasses are created.
+    """
+
+    _default_np_dtype = np.dtype(np.int64)
+    _checker = is_integer_dtype
+
+    @classmethod
+    def construct_array_type(cls) -> type[IntegerArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        return IntegerArray
+
+    @classmethod
+    def _get_dtype_mapping(cls) -> dict[np.dtype, IntegerDtype]:
+        return NUMPY_INT_TO_DTYPE
+
+    @classmethod
+    def _safe_cast(cls, values: np.ndarray, dtype: np.dtype, copy: bool) -> np.ndarray:
+        """
+        Safely cast the values to the given dtype.
+
+        "safe" in this context means the casting is lossless. e.g. if 'values'
+        has a floating dtype, each value must be an integer.
+        """
+        try:
+            return values.astype(dtype, casting="safe", copy=copy)
+        except TypeError as err:
+            casted = values.astype(dtype, copy=copy)
+            if (casted == values).all():
+                return casted
+
+            raise TypeError(
+                f"cannot safely cast non-equivalent {values.dtype} to {np.dtype(dtype)}"
+            ) from err
+
+
+class IntegerArray(NumericArray):
+    """
+    Array of integer (optional missing) values.
+
+    Uses :attr:`pandas.NA` as the missing value.
+
+    .. warning::
+
+       IntegerArray is currently experimental, and its API or internal
+       implementation may change without warning.
+
+    We represent an IntegerArray with 2 numpy arrays:
+
+    - data: contains a numpy integer array of the appropriate dtype
+    - mask: a boolean array holding a mask on the data, True is missing
+
+    To construct an IntegerArray from generic array-like input, use
+    :func:`pandas.array` with one of the integer dtypes (see examples).
+
+    See :ref:`integer_na` for more.
+
+    Parameters
+    ----------
+    values : numpy.ndarray
+        A 1-d integer-dtype array.
+    mask : numpy.ndarray
+        A 1-d boolean-dtype array indicating missing values.
+    copy : bool, default False
+        Whether to copy the `values` and `mask`.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Returns
+    -------
+    IntegerArray
+
+    Examples
+    --------
+    Create an IntegerArray with :func:`pandas.array`.
+
+    >>> int_array = pd.array([1, None, 3], dtype=pd.Int32Dtype())
+    >>> int_array
+    
+    [1, , 3]
+    Length: 3, dtype: Int32
+
+    String aliases for the dtypes are also available. They are capitalized.
+
+    >>> pd.array([1, None, 3], dtype='Int32')
+    
+    [1, , 3]
+    Length: 3, dtype: Int32
+
+    >>> pd.array([1, None, 3], dtype='UInt16')
+    
+    [1, , 3]
+    Length: 3, dtype: UInt16
+    """
+
+    _dtype_cls = IntegerDtype
+
+    # The value used to fill '_data' to avoid upcasting
+    _internal_fill_value = 1
+    # Fill values used for any/all
+    # Incompatible types in assignment (expression has type "int", base class
+    # "BaseMaskedArray" defined the type as "")
+    _truthy_value = 1  # type: ignore[assignment]
+    _falsey_value = 0  # type: ignore[assignment]
+
+
+_dtype_docstring = """
+An ExtensionDtype for {dtype} integer data.
+
+Uses :attr:`pandas.NA` as its missing value, rather than :attr:`numpy.nan`.
+
+Attributes
+----------
+None
+
+Methods
+-------
+None
+
+Examples
+--------
+For Int8Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.Int8Dtype())
+>>> ser.dtype
+Int8Dtype()
+
+For Int16Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.Int16Dtype())
+>>> ser.dtype
+Int16Dtype()
+
+For Int32Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.Int32Dtype())
+>>> ser.dtype
+Int32Dtype()
+
+For Int64Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.Int64Dtype())
+>>> ser.dtype
+Int64Dtype()
+
+For UInt8Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.UInt8Dtype())
+>>> ser.dtype
+UInt8Dtype()
+
+For UInt16Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.UInt16Dtype())
+>>> ser.dtype
+UInt16Dtype()
+
+For UInt32Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.UInt32Dtype())
+>>> ser.dtype
+UInt32Dtype()
+
+For UInt64Dtype:
+
+>>> ser = pd.Series([2, pd.NA], dtype=pd.UInt64Dtype())
+>>> ser.dtype
+UInt64Dtype()
+"""
+
+# create the Dtype
+
+
+@register_extension_dtype
+class Int8Dtype(IntegerDtype):
+    type = np.int8
+    name: ClassVar[str] = "Int8"
+    __doc__ = _dtype_docstring.format(dtype="int8")
+
+
+@register_extension_dtype
+class Int16Dtype(IntegerDtype):
+    type = np.int16
+    name: ClassVar[str] = "Int16"
+    __doc__ = _dtype_docstring.format(dtype="int16")
+
+
+@register_extension_dtype
+class Int32Dtype(IntegerDtype):
+    type = np.int32
+    name: ClassVar[str] = "Int32"
+    __doc__ = _dtype_docstring.format(dtype="int32")
+
+
+@register_extension_dtype
+class Int64Dtype(IntegerDtype):
+    type = np.int64
+    name: ClassVar[str] = "Int64"
+    __doc__ = _dtype_docstring.format(dtype="int64")
+
+
+@register_extension_dtype
+class UInt8Dtype(IntegerDtype):
+    type = np.uint8
+    name: ClassVar[str] = "UInt8"
+    __doc__ = _dtype_docstring.format(dtype="uint8")
+
+
+@register_extension_dtype
+class UInt16Dtype(IntegerDtype):
+    type = np.uint16
+    name: ClassVar[str] = "UInt16"
+    __doc__ = _dtype_docstring.format(dtype="uint16")
+
+
+@register_extension_dtype
+class UInt32Dtype(IntegerDtype):
+    type = np.uint32
+    name: ClassVar[str] = "UInt32"
+    __doc__ = _dtype_docstring.format(dtype="uint32")
+
+
+@register_extension_dtype
+class UInt64Dtype(IntegerDtype):
+    type = np.uint64
+    name: ClassVar[str] = "UInt64"
+    __doc__ = _dtype_docstring.format(dtype="uint64")
+
+
+NUMPY_INT_TO_DTYPE: dict[np.dtype, IntegerDtype] = {
+    np.dtype(np.int8): Int8Dtype(),
+    np.dtype(np.int16): Int16Dtype(),
+    np.dtype(np.int32): Int32Dtype(),
+    np.dtype(np.int64): Int64Dtype(),
+    np.dtype(np.uint8): UInt8Dtype(),
+    np.dtype(np.uint16): UInt16Dtype(),
+    np.dtype(np.uint32): UInt32Dtype(),
+    np.dtype(np.uint64): UInt64Dtype(),
+}
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/interval.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/interval.py
new file mode 100644
index 0000000000000000000000000000000000000000..da57e4ceed87e3a63e63e5ac7172c807a5e5b683
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/interval.py
@@ -0,0 +1,1930 @@
+from __future__ import annotations
+
+import operator
+from operator import (
+    le,
+    lt,
+)
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    Union,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.interval import (
+    VALID_CLOSED,
+    Interval,
+    IntervalMixin,
+    intervals_to_interval_bounds,
+)
+from pandas._libs.missing import NA
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    Dtype,
+    FillnaOptions,
+    IntervalClosedType,
+    NpDtype,
+    PositionalIndexer,
+    ScalarIndexer,
+    Self,
+    SequenceIndexer,
+    SortKind,
+    TimeArrayLike,
+    npt,
+)
+from pandas.compat.numpy import function as nv
+from pandas.errors import IntCastingNaNError
+from pandas.util._decorators import Appender
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    LossySetitemError,
+    maybe_upcast_numeric_to_64bit,
+)
+from pandas.core.dtypes.common import (
+    is_float_dtype,
+    is_integer_dtype,
+    is_list_like,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    needs_i8_conversion,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    IntervalDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCDatetimeIndex,
+    ABCIntervalIndex,
+    ABCPeriodIndex,
+)
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+    notna,
+)
+
+from pandas.core.algorithms import (
+    isin,
+    take,
+    unique,
+    value_counts_internal as value_counts,
+)
+from pandas.core.arrays import ArrowExtensionArray
+from pandas.core.arrays.base import (
+    ExtensionArray,
+    _extension_array_shared_docs,
+)
+from pandas.core.arrays.datetimes import DatetimeArray
+from pandas.core.arrays.timedeltas import TimedeltaArray
+import pandas.core.common as com
+from pandas.core.construction import (
+    array as pd_array,
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import check_array_indexer
+from pandas.core.ops import (
+    invalid_comparison,
+    unpack_zerodim_and_defer,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterator,
+        Sequence,
+    )
+
+    from pandas import (
+        Index,
+        Series,
+    )
+
+
+IntervalSide = Union[TimeArrayLike, np.ndarray]
+IntervalOrNA = Union[Interval, float]
+
+_interval_shared_docs: dict[str, str] = {}
+
+_shared_docs_kwargs = {
+    "klass": "IntervalArray",
+    "qualname": "arrays.IntervalArray",
+    "name": "",
+}
+
+
+_interval_shared_docs[
+    "class"
+] = """
+%(summary)s
+
+Parameters
+----------
+data : array-like (1-dimensional)
+    Array-like (ndarray, :class:`DateTimeArray`, :class:`TimeDeltaArray`) containing
+    Interval objects from which to build the %(klass)s.
+closed : {'left', 'right', 'both', 'neither'}, default 'right'
+    Whether the intervals are closed on the left-side, right-side, both or
+    neither.
+dtype : dtype or None, default None
+    If None, dtype will be inferred.
+copy : bool, default False
+    Copy the input data.
+%(name)s\
+verify_integrity : bool, default True
+    Verify that the %(klass)s is valid.
+
+Attributes
+----------
+left
+right
+closed
+mid
+length
+is_empty
+is_non_overlapping_monotonic
+%(extra_attributes)s\
+
+Methods
+-------
+from_arrays
+from_tuples
+from_breaks
+contains
+overlaps
+set_closed
+to_tuples
+%(extra_methods)s\
+
+See Also
+--------
+Index : The base pandas Index type.
+Interval : A bounded slice-like interval; the elements of an %(klass)s.
+interval_range : Function to create a fixed frequency IntervalIndex.
+cut : Bin values into discrete Intervals.
+qcut : Bin values into equal-sized Intervals based on rank or sample quantiles.
+
+Notes
+-----
+See the `user guide
+`__
+for more.
+
+%(examples)s\
+"""
+
+
+@Appender(
+    _interval_shared_docs["class"]
+    % {
+        "klass": "IntervalArray",
+        "summary": "Pandas array for interval data that are closed on the same side.",
+        "name": "",
+        "extra_attributes": "",
+        "extra_methods": "",
+        "examples": textwrap.dedent(
+            """\
+    Examples
+    --------
+    A new ``IntervalArray`` can be constructed directly from an array-like of
+    ``Interval`` objects:
+
+    >>> pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
+    
+    [(0, 1], (1, 5]]
+    Length: 2, dtype: interval[int64, right]
+
+    It may also be constructed using one of the constructor
+    methods: :meth:`IntervalArray.from_arrays`,
+    :meth:`IntervalArray.from_breaks`, and :meth:`IntervalArray.from_tuples`.
+    """
+        ),
+    }
+)
+class IntervalArray(IntervalMixin, ExtensionArray):
+    can_hold_na = True
+    _na_value = _fill_value = np.nan
+
+    @property
+    def ndim(self) -> Literal[1]:
+        return 1
+
+    # To make mypy recognize the fields
+    _left: IntervalSide
+    _right: IntervalSide
+    _dtype: IntervalDtype
+
+    # ---------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data,
+        closed: IntervalClosedType | None = None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        verify_integrity: bool = True,
+    ):
+        data = extract_array(data, extract_numpy=True)
+
+        if isinstance(data, cls):
+            left: IntervalSide = data._left
+            right: IntervalSide = data._right
+            closed = closed or data.closed
+            dtype = IntervalDtype(left.dtype, closed=closed)
+        else:
+            # don't allow scalars
+            if is_scalar(data):
+                msg = (
+                    f"{cls.__name__}(...) must be called with a collection "
+                    f"of some kind, {data} was passed"
+                )
+                raise TypeError(msg)
+
+            # might need to convert empty or purely na data
+            data = _maybe_convert_platform_interval(data)
+            left, right, infer_closed = intervals_to_interval_bounds(
+                data, validate_closed=closed is None
+            )
+            if left.dtype == object:
+                left = lib.maybe_convert_objects(left)
+                right = lib.maybe_convert_objects(right)
+            closed = closed or infer_closed
+
+            left, right, dtype = cls._ensure_simple_new_inputs(
+                left,
+                right,
+                closed=closed,
+                copy=copy,
+                dtype=dtype,
+            )
+
+        if verify_integrity:
+            cls._validate(left, right, dtype=dtype)
+
+        return cls._simple_new(
+            left,
+            right,
+            dtype=dtype,
+        )
+
+    @classmethod
+    def _simple_new(
+        cls,
+        left: IntervalSide,
+        right: IntervalSide,
+        dtype: IntervalDtype,
+    ) -> Self:
+        result = IntervalMixin.__new__(cls)
+        result._left = left
+        result._right = right
+        result._dtype = dtype
+
+        return result
+
+    @classmethod
+    def _ensure_simple_new_inputs(
+        cls,
+        left,
+        right,
+        closed: IntervalClosedType | None = None,
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> tuple[IntervalSide, IntervalSide, IntervalDtype]:
+        """Ensure correctness of input parameters for cls._simple_new."""
+        from pandas.core.indexes.base import ensure_index
+
+        left = ensure_index(left, copy=copy)
+        left = maybe_upcast_numeric_to_64bit(left)
+
+        right = ensure_index(right, copy=copy)
+        right = maybe_upcast_numeric_to_64bit(right)
+
+        if closed is None and isinstance(dtype, IntervalDtype):
+            closed = dtype.closed
+
+        closed = closed or "right"
+
+        if dtype is not None:
+            # GH 19262: dtype must be an IntervalDtype to override inferred
+            dtype = pandas_dtype(dtype)
+            if isinstance(dtype, IntervalDtype):
+                if dtype.subtype is not None:
+                    left = left.astype(dtype.subtype)
+                    right = right.astype(dtype.subtype)
+            else:
+                msg = f"dtype must be an IntervalDtype, got {dtype}"
+                raise TypeError(msg)
+
+            if dtype.closed is None:
+                # possibly loading an old pickle
+                dtype = IntervalDtype(dtype.subtype, closed)
+            elif closed != dtype.closed:
+                raise ValueError("closed keyword does not match dtype.closed")
+
+        # coerce dtypes to match if needed
+        if is_float_dtype(left.dtype) and is_integer_dtype(right.dtype):
+            right = right.astype(left.dtype)
+        elif is_float_dtype(right.dtype) and is_integer_dtype(left.dtype):
+            left = left.astype(right.dtype)
+
+        if type(left) != type(right):
+            msg = (
+                f"must not have differing left [{type(left).__name__}] and "
+                f"right [{type(right).__name__}] types"
+            )
+            raise ValueError(msg)
+        if isinstance(left.dtype, CategoricalDtype) or is_string_dtype(left.dtype):
+            # GH 19016
+            msg = (
+                "category, object, and string subtypes are not supported "
+                "for IntervalArray"
+            )
+            raise TypeError(msg)
+        if isinstance(left, ABCPeriodIndex):
+            msg = "Period dtypes are not supported, use a PeriodIndex instead"
+            raise ValueError(msg)
+        if isinstance(left, ABCDatetimeIndex) and str(left.tz) != str(right.tz):
+            msg = (
+                "left and right must have the same time zone, got "
+                f"'{left.tz}' and '{right.tz}'"
+            )
+            raise ValueError(msg)
+        elif needs_i8_conversion(left.dtype) and left.unit != right.unit:
+            # e.g. m8[s] vs m8[ms], try to cast to a common dtype GH#55714
+            left_arr, right_arr = left._data._ensure_matching_resos(right._data)
+            left = ensure_index(left_arr)
+            right = ensure_index(right_arr)
+
+        # For dt64/td64 we want DatetimeArray/TimedeltaArray instead of ndarray
+        left = ensure_wrapped_if_datetimelike(left)
+        left = extract_array(left, extract_numpy=True)
+        right = ensure_wrapped_if_datetimelike(right)
+        right = extract_array(right, extract_numpy=True)
+
+        if isinstance(left, ArrowExtensionArray) or isinstance(
+            right, ArrowExtensionArray
+        ):
+            pass
+        else:
+            lbase = getattr(left, "_ndarray", left)
+            lbase = getattr(lbase, "_data", lbase).base
+            rbase = getattr(right, "_ndarray", right)
+            rbase = getattr(rbase, "_data", rbase).base
+            if lbase is not None and lbase is rbase:
+                # If these share data, then setitem could corrupt our IA
+                right = right.copy()
+
+        dtype = IntervalDtype(left.dtype, closed=closed)
+
+        return left, right, dtype
+
+    @classmethod
+    def _from_sequence(
+        cls,
+        scalars,
+        *,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+    ) -> Self:
+        return cls(scalars, dtype=dtype, copy=copy)
+
+    @classmethod
+    def _from_factorized(cls, values: np.ndarray, original: IntervalArray) -> Self:
+        return cls._from_sequence(values, dtype=original.dtype)
+
+    _interval_shared_docs["from_breaks"] = textwrap.dedent(
+        """
+        Construct an %(klass)s from an array of splits.
+
+        Parameters
+        ----------
+        breaks : array-like (1-dimensional)
+            Left and right bounds for each interval.
+        closed : {'left', 'right', 'both', 'neither'}, default 'right'
+            Whether the intervals are closed on the left-side, right-side, both
+            or neither.\
+        %(name)s
+        copy : bool, default False
+            Copy the data.
+        dtype : dtype or None, default None
+            If None, dtype will be inferred.
+
+        Returns
+        -------
+        %(klass)s
+
+        See Also
+        --------
+        interval_range : Function to create a fixed frequency IntervalIndex.
+        %(klass)s.from_arrays : Construct from a left and right array.
+        %(klass)s.from_tuples : Construct from a sequence of tuples.
+
+        %(examples)s\
+        """
+    )
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_breaks"]
+        % {
+            "klass": "IntervalArray",
+            "name": "",
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.arrays.IntervalArray.from_breaks([0, 1, 2, 3])
+        
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, dtype: interval[int64, right]
+        """
+            ),
+        }
+    )
+    def from_breaks(
+        cls,
+        breaks,
+        closed: IntervalClosedType | None = "right",
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> Self:
+        breaks = _maybe_convert_platform_interval(breaks)
+
+        return cls.from_arrays(breaks[:-1], breaks[1:], closed, copy=copy, dtype=dtype)
+
+    _interval_shared_docs["from_arrays"] = textwrap.dedent(
+        """
+        Construct from two arrays defining the left and right bounds.
+
+        Parameters
+        ----------
+        left : array-like (1-dimensional)
+            Left bounds for each interval.
+        right : array-like (1-dimensional)
+            Right bounds for each interval.
+        closed : {'left', 'right', 'both', 'neither'}, default 'right'
+            Whether the intervals are closed on the left-side, right-side, both
+            or neither.\
+        %(name)s
+        copy : bool, default False
+            Copy the data.
+        dtype : dtype, optional
+            If None, dtype will be inferred.
+
+        Returns
+        -------
+        %(klass)s
+
+        Raises
+        ------
+        ValueError
+            When a value is missing in only one of `left` or `right`.
+            When a value in `left` is greater than the corresponding value
+            in `right`.
+
+        See Also
+        --------
+        interval_range : Function to create a fixed frequency IntervalIndex.
+        %(klass)s.from_breaks : Construct an %(klass)s from an array of
+            splits.
+        %(klass)s.from_tuples : Construct an %(klass)s from an
+            array-like of tuples.
+
+        Notes
+        -----
+        Each element of `left` must be less than or equal to the `right`
+        element at the same position. If an element is missing, it must be
+        missing in both `left` and `right`. A TypeError is raised when
+        using an unsupported type for `left` or `right`. At the moment,
+        'category', 'object', and 'string' subtypes are not supported.
+
+        %(examples)s\
+        """
+    )
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_arrays"]
+        % {
+            "klass": "IntervalArray",
+            "name": "",
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.arrays.IntervalArray.from_arrays([0, 1, 2], [1, 2, 3])
+        
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, dtype: interval[int64, right]
+        """
+            ),
+        }
+    )
+    def from_arrays(
+        cls,
+        left,
+        right,
+        closed: IntervalClosedType | None = "right",
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> Self:
+        left = _maybe_convert_platform_interval(left)
+        right = _maybe_convert_platform_interval(right)
+
+        left, right, dtype = cls._ensure_simple_new_inputs(
+            left,
+            right,
+            closed=closed,
+            copy=copy,
+            dtype=dtype,
+        )
+        cls._validate(left, right, dtype=dtype)
+
+        return cls._simple_new(left, right, dtype=dtype)
+
+    _interval_shared_docs["from_tuples"] = textwrap.dedent(
+        """
+        Construct an %(klass)s from an array-like of tuples.
+
+        Parameters
+        ----------
+        data : array-like (1-dimensional)
+            Array of tuples.
+        closed : {'left', 'right', 'both', 'neither'}, default 'right'
+            Whether the intervals are closed on the left-side, right-side, both
+            or neither.\
+        %(name)s
+        copy : bool, default False
+            By-default copy the data, this is compat only and ignored.
+        dtype : dtype or None, default None
+            If None, dtype will be inferred.
+
+        Returns
+        -------
+        %(klass)s
+
+        See Also
+        --------
+        interval_range : Function to create a fixed frequency IntervalIndex.
+        %(klass)s.from_arrays : Construct an %(klass)s from a left and
+                                    right array.
+        %(klass)s.from_breaks : Construct an %(klass)s from an array of
+                                    splits.
+
+        %(examples)s\
+        """
+    )
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_tuples"]
+        % {
+            "klass": "IntervalArray",
+            "name": "",
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 2)])
+        
+        [(0, 1], (1, 2]]
+        Length: 2, dtype: interval[int64, right]
+        """
+            ),
+        }
+    )
+    def from_tuples(
+        cls,
+        data,
+        closed: IntervalClosedType | None = "right",
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> Self:
+        if len(data):
+            left, right = [], []
+        else:
+            # ensure that empty data keeps input dtype
+            left = right = data
+
+        for d in data:
+            if not isinstance(d, tuple) and isna(d):
+                lhs = rhs = np.nan
+            else:
+                name = cls.__name__
+                try:
+                    # need list of length 2 tuples, e.g. [(0, 1), (1, 2), ...]
+                    lhs, rhs = d
+                except ValueError as err:
+                    msg = f"{name}.from_tuples requires tuples of length 2, got {d}"
+                    raise ValueError(msg) from err
+                except TypeError as err:
+                    msg = f"{name}.from_tuples received an invalid item, {d}"
+                    raise TypeError(msg) from err
+            left.append(lhs)
+            right.append(rhs)
+
+        return cls.from_arrays(left, right, closed, copy=False, dtype=dtype)
+
+    @classmethod
+    def _validate(cls, left, right, dtype: IntervalDtype) -> None:
+        """
+        Verify that the IntervalArray is valid.
+
+        Checks that
+
+        * dtype is correct
+        * left and right match lengths
+        * left and right have the same missing values
+        * left is always below right
+        """
+        if not isinstance(dtype, IntervalDtype):
+            msg = f"invalid dtype: {dtype}"
+            raise ValueError(msg)
+        if len(left) != len(right):
+            msg = "left and right must have the same length"
+            raise ValueError(msg)
+        left_mask = notna(left)
+        right_mask = notna(right)
+        if not (left_mask == right_mask).all():
+            msg = (
+                "missing values must be missing in the same "
+                "location both left and right sides"
+            )
+            raise ValueError(msg)
+        if not (left[left_mask] <= right[left_mask]).all():
+            msg = "left side of interval must be <= right side"
+            raise ValueError(msg)
+
+    def _shallow_copy(self, left, right) -> Self:
+        """
+        Return a new IntervalArray with the replacement attributes
+
+        Parameters
+        ----------
+        left : Index
+            Values to be used for the left-side of the intervals.
+        right : Index
+            Values to be used for the right-side of the intervals.
+        """
+        dtype = IntervalDtype(left.dtype, closed=self.closed)
+        left, right, dtype = self._ensure_simple_new_inputs(left, right, dtype=dtype)
+
+        return self._simple_new(left, right, dtype=dtype)
+
+    # ---------------------------------------------------------------------
+    # Descriptive
+
+    @property
+    def dtype(self) -> IntervalDtype:
+        return self._dtype
+
+    @property
+    def nbytes(self) -> int:
+        return self.left.nbytes + self.right.nbytes
+
+    @property
+    def size(self) -> int:
+        # Avoid materializing self.values
+        return self.left.size
+
+    # ---------------------------------------------------------------------
+    # EA Interface
+
+    def __iter__(self) -> Iterator:
+        return iter(np.asarray(self))
+
+    def __len__(self) -> int:
+        return len(self._left)
+
+    @overload
+    def __getitem__(self, key: ScalarIndexer) -> IntervalOrNA:
+        ...
+
+    @overload
+    def __getitem__(self, key: SequenceIndexer) -> Self:
+        ...
+
+    def __getitem__(self, key: PositionalIndexer) -> Self | IntervalOrNA:
+        key = check_array_indexer(self, key)
+        left = self._left[key]
+        right = self._right[key]
+
+        if not isinstance(left, (np.ndarray, ExtensionArray)):
+            # scalar
+            if is_scalar(left) and isna(left):
+                return self._fill_value
+            return Interval(left, right, self.closed)
+        if np.ndim(left) > 1:
+            # GH#30588 multi-dimensional indexer disallowed
+            raise ValueError("multi-dimensional indexing not allowed")
+        # Argument 2 to "_simple_new" of "IntervalArray" has incompatible type
+        # "Union[Period, Timestamp, Timedelta, NaTType, DatetimeArray, TimedeltaArray,
+        # ndarray[Any, Any]]"; expected "Union[Union[DatetimeArray, TimedeltaArray],
+        # ndarray[Any, Any]]"
+        return self._simple_new(left, right, dtype=self.dtype)  # type: ignore[arg-type]
+
+    def __setitem__(self, key, value) -> None:
+        value_left, value_right = self._validate_setitem_value(value)
+        key = check_array_indexer(self, key)
+
+        self._left[key] = value_left
+        self._right[key] = value_right
+
+    def _cmp_method(self, other, op):
+        # ensure pandas array for list-like and eliminate non-interval scalars
+        if is_list_like(other):
+            if len(self) != len(other):
+                raise ValueError("Lengths must match to compare")
+            other = pd_array(other)
+        elif not isinstance(other, Interval):
+            # non-interval scalar -> no matches
+            if other is NA:
+                # GH#31882
+                from pandas.core.arrays import BooleanArray
+
+                arr = np.empty(self.shape, dtype=bool)
+                mask = np.ones(self.shape, dtype=bool)
+                return BooleanArray(arr, mask)
+            return invalid_comparison(self, other, op)
+
+        # determine the dtype of the elements we want to compare
+        if isinstance(other, Interval):
+            other_dtype = pandas_dtype("interval")
+        elif not isinstance(other.dtype, CategoricalDtype):
+            other_dtype = other.dtype
+        else:
+            # for categorical defer to categories for dtype
+            other_dtype = other.categories.dtype
+
+            # extract intervals if we have interval categories with matching closed
+            if isinstance(other_dtype, IntervalDtype):
+                if self.closed != other.categories.closed:
+                    return invalid_comparison(self, other, op)
+
+                other = other.categories._values.take(
+                    other.codes, allow_fill=True, fill_value=other.categories._na_value
+                )
+
+        # interval-like -> need same closed and matching endpoints
+        if isinstance(other_dtype, IntervalDtype):
+            if self.closed != other.closed:
+                return invalid_comparison(self, other, op)
+            elif not isinstance(other, Interval):
+                other = type(self)(other)
+
+            if op is operator.eq:
+                return (self._left == other.left) & (self._right == other.right)
+            elif op is operator.ne:
+                return (self._left != other.left) | (self._right != other.right)
+            elif op is operator.gt:
+                return (self._left > other.left) | (
+                    (self._left == other.left) & (self._right > other.right)
+                )
+            elif op is operator.ge:
+                return (self == other) | (self > other)
+            elif op is operator.lt:
+                return (self._left < other.left) | (
+                    (self._left == other.left) & (self._right < other.right)
+                )
+            else:
+                # operator.lt
+                return (self == other) | (self < other)
+
+        # non-interval/non-object dtype -> no matches
+        if not is_object_dtype(other_dtype):
+            return invalid_comparison(self, other, op)
+
+        # object dtype -> iteratively check for intervals
+        result = np.zeros(len(self), dtype=bool)
+        for i, obj in enumerate(other):
+            try:
+                result[i] = op(self[i], obj)
+            except TypeError:
+                if obj is NA:
+                    # comparison with np.nan returns NA
+                    # github.com/pandas-dev/pandas/pull/37124#discussion_r509095092
+                    result = result.astype(object)
+                    result[i] = NA
+                else:
+                    raise
+        return result
+
+    @unpack_zerodim_and_defer("__eq__")
+    def __eq__(self, other):
+        return self._cmp_method(other, operator.eq)
+
+    @unpack_zerodim_and_defer("__ne__")
+    def __ne__(self, other):
+        return self._cmp_method(other, operator.ne)
+
+    @unpack_zerodim_and_defer("__gt__")
+    def __gt__(self, other):
+        return self._cmp_method(other, operator.gt)
+
+    @unpack_zerodim_and_defer("__ge__")
+    def __ge__(self, other):
+        return self._cmp_method(other, operator.ge)
+
+    @unpack_zerodim_and_defer("__lt__")
+    def __lt__(self, other):
+        return self._cmp_method(other, operator.lt)
+
+    @unpack_zerodim_and_defer("__le__")
+    def __le__(self, other):
+        return self._cmp_method(other, operator.le)
+
+    def argsort(
+        self,
+        *,
+        ascending: bool = True,
+        kind: SortKind = "quicksort",
+        na_position: str = "last",
+        **kwargs,
+    ) -> np.ndarray:
+        ascending = nv.validate_argsort_with_ascending(ascending, (), kwargs)
+
+        if ascending and kind == "quicksort" and na_position == "last":
+            # TODO: in an IntervalIndex we can reuse the cached
+            #  IntervalTree.left_sorter
+            return np.lexsort((self.right, self.left))
+
+        # TODO: other cases we can use lexsort for?  much more performant.
+        return super().argsort(
+            ascending=ascending, kind=kind, na_position=na_position, **kwargs
+        )
+
+    def min(self, *, axis: AxisInt | None = None, skipna: bool = True) -> IntervalOrNA:
+        nv.validate_minmax_axis(axis, self.ndim)
+
+        if not len(self):
+            return self._na_value
+
+        mask = self.isna()
+        if mask.any():
+            if not skipna:
+                return self._na_value
+            obj = self[~mask]
+        else:
+            obj = self
+
+        indexer = obj.argsort()[0]
+        return obj[indexer]
+
+    def max(self, *, axis: AxisInt | None = None, skipna: bool = True) -> IntervalOrNA:
+        nv.validate_minmax_axis(axis, self.ndim)
+
+        if not len(self):
+            return self._na_value
+
+        mask = self.isna()
+        if mask.any():
+            if not skipna:
+                return self._na_value
+            obj = self[~mask]
+        else:
+            obj = self
+
+        indexer = obj.argsort()[-1]
+        return obj[indexer]
+
+    def _pad_or_backfill(  # pylint: disable=useless-parent-delegation
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        # TODO(3.0): after EA.fillna 'method' deprecation is enforced, we can remove
+        #  this method entirely.
+        return super()._pad_or_backfill(
+            method=method, limit=limit, limit_area=limit_area, copy=copy
+        )
+
+    def fillna(
+        self, value=None, method=None, limit: int | None = None, copy: bool = True
+    ) -> Self:
+        """
+        Fill NA/NaN values using the specified method.
+
+        Parameters
+        ----------
+        value : scalar, dict, Series
+            If a scalar value is passed it is used to fill all missing values.
+            Alternatively, a Series or dict can be used to fill in different
+            values for each index. The value should not be a list. The
+            value(s) passed should be either Interval objects or NA/NaN.
+        method : {'backfill', 'bfill', 'pad', 'ffill', None}, default None
+            (Not implemented yet for IntervalArray)
+            Method to use for filling holes in reindexed Series
+        limit : int, default None
+            (Not implemented yet for IntervalArray)
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled.
+        copy : bool, default True
+            Whether to make a copy of the data before filling. If False, then
+            the original should be modified and no new memory should be allocated.
+            For ExtensionArray subclasses that cannot do this, it is at the
+            author's discretion whether to ignore "copy=False" or to raise.
+
+        Returns
+        -------
+        filled : IntervalArray with NA/NaN filled
+        """
+        if copy is False:
+            raise NotImplementedError
+        if method is not None:
+            return super().fillna(value=value, method=method, limit=limit)
+
+        value_left, value_right = self._validate_scalar(value)
+
+        left = self.left.fillna(value=value_left)
+        right = self.right.fillna(value=value_right)
+        return self._shallow_copy(left, right)
+
+    def astype(self, dtype, copy: bool = True):
+        """
+        Cast to an ExtensionArray or NumPy array with dtype 'dtype'.
+
+        Parameters
+        ----------
+        dtype : str or dtype
+            Typecode or data-type to which the array is cast.
+
+        copy : bool, default True
+            Whether to copy the data, even if not necessary. If False,
+            a copy is made only if the old dtype does not match the
+            new dtype.
+
+        Returns
+        -------
+        array : ExtensionArray or ndarray
+            ExtensionArray or NumPy ndarray with 'dtype' for its dtype.
+        """
+        from pandas import Index
+
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        if isinstance(dtype, IntervalDtype):
+            if dtype == self.dtype:
+                return self.copy() if copy else self
+
+            if is_float_dtype(self.dtype.subtype) and needs_i8_conversion(
+                dtype.subtype
+            ):
+                # This is allowed on the Index.astype but we disallow it here
+                msg = (
+                    f"Cannot convert {self.dtype} to {dtype}; subtypes are incompatible"
+                )
+                raise TypeError(msg)
+
+            # need to cast to different subtype
+            try:
+                # We need to use Index rules for astype to prevent casting
+                #  np.nan entries to int subtypes
+                new_left = Index(self._left, copy=False).astype(dtype.subtype)
+                new_right = Index(self._right, copy=False).astype(dtype.subtype)
+            except IntCastingNaNError:
+                # e.g test_subtype_integer
+                raise
+            except (TypeError, ValueError) as err:
+                # e.g. test_subtype_integer_errors f8->u8 can be lossy
+                #  and raises ValueError
+                msg = (
+                    f"Cannot convert {self.dtype} to {dtype}; subtypes are incompatible"
+                )
+                raise TypeError(msg) from err
+            return self._shallow_copy(new_left, new_right)
+        else:
+            try:
+                return super().astype(dtype, copy=copy)
+            except (TypeError, ValueError) as err:
+                msg = f"Cannot cast {type(self).__name__} to dtype {dtype}"
+                raise TypeError(msg) from err
+
+    def equals(self, other) -> bool:
+        if type(self) != type(other):
+            return False
+
+        return bool(
+            self.closed == other.closed
+            and self.left.equals(other.left)
+            and self.right.equals(other.right)
+        )
+
+    @classmethod
+    def _concat_same_type(cls, to_concat: Sequence[IntervalArray]) -> Self:
+        """
+        Concatenate multiple IntervalArray
+
+        Parameters
+        ----------
+        to_concat : sequence of IntervalArray
+
+        Returns
+        -------
+        IntervalArray
+        """
+        closed_set = {interval.closed for interval in to_concat}
+        if len(closed_set) != 1:
+            raise ValueError("Intervals must all be closed on the same side.")
+        closed = closed_set.pop()
+
+        left: IntervalSide = np.concatenate([interval.left for interval in to_concat])
+        right: IntervalSide = np.concatenate([interval.right for interval in to_concat])
+
+        left, right, dtype = cls._ensure_simple_new_inputs(left, right, closed=closed)
+
+        return cls._simple_new(left, right, dtype=dtype)
+
+    def copy(self) -> Self:
+        """
+        Return a copy of the array.
+
+        Returns
+        -------
+        IntervalArray
+        """
+        left = self._left.copy()
+        right = self._right.copy()
+        dtype = self.dtype
+        return self._simple_new(left, right, dtype=dtype)
+
+    def isna(self) -> np.ndarray:
+        return isna(self._left)
+
+    def shift(self, periods: int = 1, fill_value: object = None) -> IntervalArray:
+        if not len(self) or periods == 0:
+            return self.copy()
+
+        self._validate_scalar(fill_value)
+
+        # ExtensionArray.shift doesn't work for two reasons
+        # 1. IntervalArray.dtype.na_value may not be correct for the dtype.
+        # 2. IntervalArray._from_sequence only accepts NaN for missing values,
+        #    not other values like NaT
+
+        empty_len = min(abs(periods), len(self))
+        if isna(fill_value):
+            from pandas import Index
+
+            fill_value = Index(self._left, copy=False)._na_value
+            empty = IntervalArray.from_breaks([fill_value] * (empty_len + 1))
+        else:
+            empty = self._from_sequence([fill_value] * empty_len, dtype=self.dtype)
+
+        if periods > 0:
+            a = empty
+            b = self[:-periods]
+        else:
+            a = self[abs(periods) :]
+            b = empty
+        return self._concat_same_type([a, b])
+
+    def take(
+        self,
+        indices,
+        *,
+        allow_fill: bool = False,
+        fill_value=None,
+        axis=None,
+        **kwargs,
+    ) -> Self:
+        """
+        Take elements from the IntervalArray.
+
+        Parameters
+        ----------
+        indices : sequence of integers
+            Indices to be taken.
+
+        allow_fill : bool, default False
+            How to handle negative values in `indices`.
+
+            * False: negative values in `indices` indicate positional indices
+              from the right (the default). This is similar to
+              :func:`numpy.take`.
+
+            * True: negative values in `indices` indicate
+              missing values. These values are set to `fill_value`. Any other
+              other negative values raise a ``ValueError``.
+
+        fill_value : Interval or NA, optional
+            Fill value to use for NA-indices when `allow_fill` is True.
+            This may be ``None``, in which case the default NA value for
+            the type, ``self.dtype.na_value``, is used.
+
+            For many ExtensionArrays, there will be two representations of
+            `fill_value`: a user-facing "boxed" scalar, and a low-level
+            physical NA value. `fill_value` should be the user-facing version,
+            and the implementation should handle translating that to the
+            physical version for processing the take if necessary.
+
+        axis : any, default None
+            Present for compat with IntervalIndex; does nothing.
+
+        Returns
+        -------
+        IntervalArray
+
+        Raises
+        ------
+        IndexError
+            When the indices are out of bounds for the array.
+        ValueError
+            When `indices` contains negative values other than ``-1``
+            and `allow_fill` is True.
+        """
+        nv.validate_take((), kwargs)
+
+        fill_left = fill_right = fill_value
+        if allow_fill:
+            fill_left, fill_right = self._validate_scalar(fill_value)
+
+        left_take = take(
+            self._left, indices, allow_fill=allow_fill, fill_value=fill_left
+        )
+        right_take = take(
+            self._right, indices, allow_fill=allow_fill, fill_value=fill_right
+        )
+
+        return self._shallow_copy(left_take, right_take)
+
+    def _validate_listlike(self, value):
+        # list-like of intervals
+        try:
+            array = IntervalArray(value)
+            self._check_closed_matches(array, name="value")
+            value_left, value_right = array.left, array.right
+        except TypeError as err:
+            # wrong type: not interval or NA
+            msg = f"'value' should be an interval type, got {type(value)} instead."
+            raise TypeError(msg) from err
+
+        try:
+            self.left._validate_fill_value(value_left)
+        except (LossySetitemError, TypeError) as err:
+            msg = (
+                "'value' should be a compatible interval type, "
+                f"got {type(value)} instead."
+            )
+            raise TypeError(msg) from err
+
+        return value_left, value_right
+
+    def _validate_scalar(self, value):
+        if isinstance(value, Interval):
+            self._check_closed_matches(value, name="value")
+            left, right = value.left, value.right
+            # TODO: check subdtype match like _validate_setitem_value?
+        elif is_valid_na_for_dtype(value, self.left.dtype):
+            # GH#18295
+            left = right = self.left._na_value
+        else:
+            raise TypeError(
+                "can only insert Interval objects and NA into an IntervalArray"
+            )
+        return left, right
+
+    def _validate_setitem_value(self, value):
+        if is_valid_na_for_dtype(value, self.left.dtype):
+            # na value: need special casing to set directly on numpy arrays
+            value = self.left._na_value
+            if is_integer_dtype(self.dtype.subtype):
+                # can't set NaN on a numpy integer array
+                # GH#45484 TypeError, not ValueError, matches what we get with
+                #  non-NA un-holdable value.
+                raise TypeError("Cannot set float NaN to integer-backed IntervalArray")
+            value_left, value_right = value, value
+
+        elif isinstance(value, Interval):
+            # scalar interval
+            self._check_closed_matches(value, name="value")
+            value_left, value_right = value.left, value.right
+            self.left._validate_fill_value(value_left)
+            self.left._validate_fill_value(value_right)
+
+        else:
+            return self._validate_listlike(value)
+
+        return value_left, value_right
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Returns a Series containing counts of each interval.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of NaN.
+
+        Returns
+        -------
+        counts : Series
+
+        See Also
+        --------
+        Series.value_counts
+        """
+        # TODO: implement this is a non-naive way!
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                "The behavior of value_counts with object-dtype is deprecated",
+                category=FutureWarning,
+            )
+            result = value_counts(np.asarray(self), dropna=dropna)
+            # Once the deprecation is enforced, we will need to do
+            #  `result.index = result.index.astype(self.dtype)`
+        return result
+
+    # ---------------------------------------------------------------------
+    # Rendering Methods
+
+    def _formatter(self, boxed: bool = False):
+        # returning 'str' here causes us to render as e.g. "(0, 1]" instead of
+        #  "Interval(0, 1, closed='right')"
+        return str
+
+    # ---------------------------------------------------------------------
+    # Vectorized Interval Properties/Attributes
+
+    @property
+    def left(self) -> Index:
+        """
+        Return the left endpoints of each Interval in the IntervalArray as an Index.
+
+        Examples
+        --------
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(2, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (2, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.left
+        Index([0, 2], dtype='int64')
+        """
+        from pandas import Index
+
+        return Index(self._left, copy=False)
+
+    @property
+    def right(self) -> Index:
+        """
+        Return the right endpoints of each Interval in the IntervalArray as an Index.
+
+        Examples
+        --------
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(2, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (2, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.right
+        Index([1, 5], dtype='int64')
+        """
+        from pandas import Index
+
+        return Index(self._right, copy=False)
+
+    @property
+    def length(self) -> Index:
+        """
+        Return an Index with entries denoting the length of each Interval.
+
+        Examples
+        --------
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (1, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.length
+        Index([1, 4], dtype='int64')
+        """
+        return self.right - self.left
+
+    @property
+    def mid(self) -> Index:
+        """
+        Return the midpoint of each Interval in the IntervalArray as an Index.
+
+        Examples
+        --------
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (1, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.mid
+        Index([0.5, 3.0], dtype='float64')
+        """
+        try:
+            return 0.5 * (self.left + self.right)
+        except TypeError:
+            # datetime safe version
+            return self.left + 0.5 * self.length
+
+    _interval_shared_docs["overlaps"] = textwrap.dedent(
+        """
+        Check elementwise if an Interval overlaps the values in the %(klass)s.
+
+        Two intervals overlap if they share a common point, including closed
+        endpoints. Intervals that only have an open endpoint in common do not
+        overlap.
+
+        Parameters
+        ----------
+        other : %(klass)s
+            Interval to check against for an overlap.
+
+        Returns
+        -------
+        ndarray
+            Boolean array positionally indicating where an overlap occurs.
+
+        See Also
+        --------
+        Interval.overlaps : Check whether two Interval objects overlap.
+
+        Examples
+        --------
+        %(examples)s
+        >>> intervals.overlaps(pd.Interval(0.5, 1.5))
+        array([ True,  True, False])
+
+        Intervals that share closed endpoints overlap:
+
+        >>> intervals.overlaps(pd.Interval(1, 3, closed='left'))
+        array([ True,  True, True])
+
+        Intervals that only have an open endpoint in common do not overlap:
+
+        >>> intervals.overlaps(pd.Interval(1, 2, closed='right'))
+        array([False,  True, False])
+        """
+    )
+
+    @Appender(
+        _interval_shared_docs["overlaps"]
+        % {
+            "klass": "IntervalArray",
+            "examples": textwrap.dedent(
+                """\
+        >>> data = [(0, 1), (1, 3), (2, 4)]
+        >>> intervals = pd.arrays.IntervalArray.from_tuples(data)
+        >>> intervals
+        
+        [(0, 1], (1, 3], (2, 4]]
+        Length: 3, dtype: interval[int64, right]
+        """
+            ),
+        }
+    )
+    def overlaps(self, other):
+        if isinstance(other, (IntervalArray, ABCIntervalIndex)):
+            raise NotImplementedError
+        if not isinstance(other, Interval):
+            msg = f"`other` must be Interval-like, got {type(other).__name__}"
+            raise TypeError(msg)
+
+        # equality is okay if both endpoints are closed (overlap at a point)
+        op1 = le if (self.closed_left and other.closed_right) else lt
+        op2 = le if (other.closed_left and self.closed_right) else lt
+
+        # overlaps is equivalent negation of two interval being disjoint:
+        # disjoint = (A.left > B.right) or (B.left > A.right)
+        # (simplifying the negation allows this to be done in less operations)
+        return op1(self.left, other.right) & op2(other.left, self.right)
+
+    # ---------------------------------------------------------------------
+
+    @property
+    def closed(self) -> IntervalClosedType:
+        """
+        String describing the inclusive side the intervals.
+
+        Either ``left``, ``right``, ``both`` or ``neither``.
+
+        Examples
+        --------
+
+        For arrays:
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (1, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.closed
+        'right'
+
+        For Interval Index:
+
+        >>> interv_idx = pd.interval_range(start=0, end=2)
+        >>> interv_idx
+        IntervalIndex([(0, 1], (1, 2]], dtype='interval[int64, right]')
+        >>> interv_idx.closed
+        'right'
+        """
+        return self.dtype.closed
+
+    _interval_shared_docs["set_closed"] = textwrap.dedent(
+        """
+        Return an identical %(klass)s closed on the specified side.
+
+        Parameters
+        ----------
+        closed : {'left', 'right', 'both', 'neither'}
+            Whether the intervals are closed on the left-side, right-side, both
+            or neither.
+
+        Returns
+        -------
+        %(klass)s
+
+        %(examples)s\
+        """
+    )
+
+    @Appender(
+        _interval_shared_docs["set_closed"]
+        % {
+            "klass": "IntervalArray",
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> index = pd.arrays.IntervalArray.from_breaks(range(4))
+        >>> index
+        
+        [(0, 1], (1, 2], (2, 3]]
+        Length: 3, dtype: interval[int64, right]
+        >>> index.set_closed('both')
+        
+        [[0, 1], [1, 2], [2, 3]]
+        Length: 3, dtype: interval[int64, both]
+        """
+            ),
+        }
+    )
+    def set_closed(self, closed: IntervalClosedType) -> Self:
+        if closed not in VALID_CLOSED:
+            msg = f"invalid option for 'closed': {closed}"
+            raise ValueError(msg)
+
+        left, right = self._left, self._right
+        dtype = IntervalDtype(left.dtype, closed=closed)
+        return self._simple_new(left, right, dtype=dtype)
+
+    _interval_shared_docs[
+        "is_non_overlapping_monotonic"
+    ] = """
+        Return a boolean whether the %(klass)s is non-overlapping and monotonic.
+
+        Non-overlapping means (no Intervals share points), and monotonic means
+        either monotonic increasing or monotonic decreasing.
+
+        Examples
+        --------
+        For arrays:
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1), pd.Interval(1, 5)])
+        >>> interv_arr
+        
+        [(0, 1], (1, 5]]
+        Length: 2, dtype: interval[int64, right]
+        >>> interv_arr.is_non_overlapping_monotonic
+        True
+
+        >>> interv_arr = pd.arrays.IntervalArray([pd.Interval(0, 1),
+        ...                                       pd.Interval(-1, 0.1)])
+        >>> interv_arr
+        
+        [(0.0, 1.0], (-1.0, 0.1]]
+        Length: 2, dtype: interval[float64, right]
+        >>> interv_arr.is_non_overlapping_monotonic
+        False
+
+        For Interval Index:
+
+        >>> interv_idx = pd.interval_range(start=0, end=2)
+        >>> interv_idx
+        IntervalIndex([(0, 1], (1, 2]], dtype='interval[int64, right]')
+        >>> interv_idx.is_non_overlapping_monotonic
+        True
+
+        >>> interv_idx = pd.interval_range(start=0, end=2, closed='both')
+        >>> interv_idx
+        IntervalIndex([[0, 1], [1, 2]], dtype='interval[int64, both]')
+        >>> interv_idx.is_non_overlapping_monotonic
+        False
+        """
+
+    @property
+    @Appender(
+        _interval_shared_docs["is_non_overlapping_monotonic"] % _shared_docs_kwargs
+    )
+    def is_non_overlapping_monotonic(self) -> bool:
+        # must be increasing  (e.g., [0, 1), [1, 2), [2, 3), ... )
+        # or decreasing (e.g., [-1, 0), [-2, -1), [-3, -2), ...)
+        # we already require left <= right
+
+        # strict inequality for closed == 'both'; equality implies overlapping
+        # at a point when both sides of intervals are included
+        if self.closed == "both":
+            return bool(
+                (self._right[:-1] < self._left[1:]).all()
+                or (self._left[:-1] > self._right[1:]).all()
+            )
+
+        # non-strict inequality when closed != 'both'; at least one side is
+        # not included in the intervals, so equality does not imply overlapping
+        return bool(
+            (self._right[:-1] <= self._left[1:]).all()
+            or (self._left[:-1] >= self._right[1:]).all()
+        )
+
+    # ---------------------------------------------------------------------
+    # Conversion
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        """
+        Return the IntervalArray's data as a numpy array of Interval
+        objects (with dtype='object')
+        """
+        if copy is False:
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        left = self._left
+        right = self._right
+        mask = self.isna()
+        closed = self.closed
+
+        result = np.empty(len(left), dtype=object)
+        for i, left_value in enumerate(left):
+            if mask[i]:
+                result[i] = np.nan
+            else:
+                result[i] = Interval(left_value, right[i], closed)
+        return result
+
+    def __arrow_array__(self, type=None):
+        """
+        Convert myself into a pyarrow Array.
+        """
+        import pyarrow
+
+        from pandas.core.arrays.arrow.extension_types import ArrowIntervalType
+
+        try:
+            subtype = pyarrow.from_numpy_dtype(self.dtype.subtype)
+        except TypeError as err:
+            raise TypeError(
+                f"Conversion to arrow with subtype '{self.dtype.subtype}' "
+                "is not supported"
+            ) from err
+        interval_type = ArrowIntervalType(subtype, self.closed)
+        storage_array = pyarrow.StructArray.from_arrays(
+            [
+                pyarrow.array(self._left, type=subtype, from_pandas=True),
+                pyarrow.array(self._right, type=subtype, from_pandas=True),
+            ],
+            names=["left", "right"],
+        )
+        mask = self.isna()
+        if mask.any():
+            # if there are missing values, set validity bitmap also on the array level
+            null_bitmap = pyarrow.array(~mask).buffers()[1]
+            storage_array = pyarrow.StructArray.from_buffers(
+                storage_array.type,
+                len(storage_array),
+                [null_bitmap],
+                children=[storage_array.field(0), storage_array.field(1)],
+            )
+
+        if type is not None:
+            if type.equals(interval_type.storage_type):
+                return storage_array
+            elif isinstance(type, ArrowIntervalType):
+                # ensure we have the same subtype and closed attributes
+                if not type.equals(interval_type):
+                    raise TypeError(
+                        "Not supported to convert IntervalArray to type with "
+                        f"different 'subtype' ({self.dtype.subtype} vs {type.subtype}) "
+                        f"and 'closed' ({self.closed} vs {type.closed}) attributes"
+                    )
+            else:
+                raise TypeError(
+                    f"Not supported to convert IntervalArray to '{type}' type"
+                )
+
+        return pyarrow.ExtensionArray.from_storage(interval_type, storage_array)
+
+    _interval_shared_docs["to_tuples"] = textwrap.dedent(
+        """
+        Return an %(return_type)s of tuples of the form (left, right).
+
+        Parameters
+        ----------
+        na_tuple : bool, default True
+            If ``True``, return ``NA`` as a tuple ``(nan, nan)``. If ``False``,
+            just return ``NA`` as ``nan``.
+
+        Returns
+        -------
+        tuples: %(return_type)s
+        %(examples)s\
+        """
+    )
+
+    @Appender(
+        _interval_shared_docs["to_tuples"]
+        % {
+            "return_type": (
+                "ndarray (if self is IntervalArray) or Index (if self is IntervalIndex)"
+            ),
+            "examples": textwrap.dedent(
+                """\
+
+         Examples
+         --------
+         For :class:`pandas.IntervalArray`:
+
+         >>> idx = pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 2)])
+         >>> idx
+         
+         [(0, 1], (1, 2]]
+         Length: 2, dtype: interval[int64, right]
+         >>> idx.to_tuples()
+         array([(0, 1), (1, 2)], dtype=object)
+
+         For :class:`pandas.IntervalIndex`:
+
+         >>> idx = pd.interval_range(start=0, end=2)
+         >>> idx
+         IntervalIndex([(0, 1], (1, 2]], dtype='interval[int64, right]')
+         >>> idx.to_tuples()
+         Index([(0, 1), (1, 2)], dtype='object')
+         """
+            ),
+        }
+    )
+    def to_tuples(self, na_tuple: bool = True) -> np.ndarray:
+        tuples = com.asarray_tuplesafe(zip(self._left, self._right))
+        if not na_tuple:
+            # GH 18756
+            tuples = np.where(~self.isna(), tuples, np.nan)
+        return tuples
+
+    # ---------------------------------------------------------------------
+
+    def _putmask(self, mask: npt.NDArray[np.bool_], value) -> None:
+        value_left, value_right = self._validate_setitem_value(value)
+
+        if isinstance(self._left, np.ndarray):
+            np.putmask(self._left, mask, value_left)
+            assert isinstance(self._right, np.ndarray)
+            np.putmask(self._right, mask, value_right)
+        else:
+            self._left._putmask(mask, value_left)
+            assert not isinstance(self._right, np.ndarray)
+            self._right._putmask(mask, value_right)
+
+    def insert(self, loc: int, item: Interval) -> Self:
+        """
+        Return a new IntervalArray inserting new item at location. Follows
+        Python numpy.insert semantics for negative values.  Only Interval
+        objects and NA can be inserted into an IntervalIndex
+
+        Parameters
+        ----------
+        loc : int
+        item : Interval
+
+        Returns
+        -------
+        IntervalArray
+        """
+        left_insert, right_insert = self._validate_scalar(item)
+
+        new_left = self.left.insert(loc, left_insert)
+        new_right = self.right.insert(loc, right_insert)
+
+        return self._shallow_copy(new_left, new_right)
+
+    def delete(self, loc) -> Self:
+        if isinstance(self._left, np.ndarray):
+            new_left = np.delete(self._left, loc)
+            assert isinstance(self._right, np.ndarray)
+            new_right = np.delete(self._right, loc)
+        else:
+            new_left = self._left.delete(loc)
+            assert not isinstance(self._right, np.ndarray)
+            new_right = self._right.delete(loc)
+        return self._shallow_copy(left=new_left, right=new_right)
+
+    @Appender(_extension_array_shared_docs["repeat"] % _shared_docs_kwargs)
+    def repeat(
+        self,
+        repeats: int | Sequence[int],
+        axis: AxisInt | None = None,
+    ) -> Self:
+        nv.validate_repeat((), {"axis": axis})
+        left_repeat = self.left.repeat(repeats)
+        right_repeat = self.right.repeat(repeats)
+        return self._shallow_copy(left=left_repeat, right=right_repeat)
+
+    _interval_shared_docs["contains"] = textwrap.dedent(
+        """
+        Check elementwise if the Intervals contain the value.
+
+        Return a boolean mask whether the value is contained in the Intervals
+        of the %(klass)s.
+
+        Parameters
+        ----------
+        other : scalar
+            The value to check whether it is contained in the Intervals.
+
+        Returns
+        -------
+        boolean array
+
+        See Also
+        --------
+        Interval.contains : Check whether Interval object contains value.
+        %(klass)s.overlaps : Check if an Interval overlaps the values in the
+            %(klass)s.
+
+        Examples
+        --------
+        %(examples)s
+        >>> intervals.contains(0.5)
+        array([ True, False, False])
+    """
+    )
+
+    @Appender(
+        _interval_shared_docs["contains"]
+        % {
+            "klass": "IntervalArray",
+            "examples": textwrap.dedent(
+                """\
+        >>> intervals = pd.arrays.IntervalArray.from_tuples([(0, 1), (1, 3), (2, 4)])
+        >>> intervals
+        
+        [(0, 1], (1, 3], (2, 4]]
+        Length: 3, dtype: interval[int64, right]
+        """
+            ),
+        }
+    )
+    def contains(self, other):
+        if isinstance(other, Interval):
+            raise NotImplementedError("contains not implemented for two intervals")
+
+        return (self._left < other if self.open_left else self._left <= other) & (
+            other < self._right if self.open_right else other <= self._right
+        )
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        if isinstance(values, IntervalArray):
+            if self.closed != values.closed:
+                # not comparable -> no overlap
+                return np.zeros(self.shape, dtype=bool)
+
+            if self.dtype == values.dtype:
+                # GH#38353 instead of casting to object, operating on a
+                #  complex128 ndarray is much more performant.
+                left = self._combined.view("complex128")
+                right = values._combined.view("complex128")
+                # error: Argument 1 to "isin" has incompatible type
+                # "Union[ExtensionArray, ndarray[Any, Any],
+                # ndarray[Any, dtype[Any]]]"; expected
+                # "Union[_SupportsArray[dtype[Any]],
+                # _NestedSequence[_SupportsArray[dtype[Any]]], bool,
+                # int, float, complex, str, bytes, _NestedSequence[
+                # Union[bool, int, float, complex, str, bytes]]]"
+                return np.isin(left, right).ravel()  # type: ignore[arg-type]
+
+            elif needs_i8_conversion(self.left.dtype) ^ needs_i8_conversion(
+                values.left.dtype
+            ):
+                # not comparable -> no overlap
+                return np.zeros(self.shape, dtype=bool)
+
+        return isin(self.astype(object), values.astype(object))
+
+    @property
+    def _combined(self) -> IntervalSide:
+        # error: Item "ExtensionArray" of "ExtensionArray | ndarray[Any, Any]"
+        # has no attribute "reshape"  [union-attr]
+        left = self.left._values.reshape(-1, 1)  # type: ignore[union-attr]
+        right = self.right._values.reshape(-1, 1)  # type: ignore[union-attr]
+        if needs_i8_conversion(left.dtype):
+            # error: Item "ndarray[Any, Any]" of "Any | ndarray[Any, Any]" has
+            # no attribute "_concat_same_type"
+            comb = left._concat_same_type(  # type: ignore[union-attr]
+                [left, right], axis=1
+            )
+        else:
+            comb = np.concatenate([left, right], axis=1)
+        return comb
+
+    def _from_combined(self, combined: np.ndarray) -> IntervalArray:
+        """
+        Create a new IntervalArray with our dtype from a 1D complex128 ndarray.
+        """
+        nc = combined.view("i8").reshape(-1, 2)
+
+        dtype = self._left.dtype
+        if needs_i8_conversion(dtype):
+            assert isinstance(self._left, (DatetimeArray, TimedeltaArray))
+            new_left = type(self._left)._from_sequence(nc[:, 0], dtype=dtype)
+            assert isinstance(self._right, (DatetimeArray, TimedeltaArray))
+            new_right = type(self._right)._from_sequence(nc[:, 1], dtype=dtype)
+        else:
+            assert isinstance(dtype, np.dtype)
+            new_left = nc[:, 0].view(dtype)
+            new_right = nc[:, 1].view(dtype)
+        return self._shallow_copy(left=new_left, right=new_right)
+
+    def unique(self) -> IntervalArray:
+        # No overload variant of "__getitem__" of "ExtensionArray" matches argument
+        # type "Tuple[slice, int]"
+        nc = unique(
+            self._combined.view("complex128")[:, 0]  # type: ignore[call-overload]
+        )
+        nc = nc[:, None]
+        return self._from_combined(nc)
+
+
+def _maybe_convert_platform_interval(values) -> ArrayLike:
+    """
+    Try to do platform conversion, with special casing for IntervalArray.
+    Wrapper around maybe_convert_platform that alters the default return
+    dtype in certain cases to be compatible with IntervalArray.  For example,
+    empty lists return with integer dtype instead of object dtype, which is
+    prohibited for IntervalArray.
+
+    Parameters
+    ----------
+    values : array-like
+
+    Returns
+    -------
+    array
+    """
+    if isinstance(values, (list, tuple)) and len(values) == 0:
+        # GH 19016
+        # empty lists/tuples get object dtype by default, but this is
+        # prohibited for IntervalArray, so coerce to integer instead
+        return np.array([], dtype=np.int64)
+    elif not is_list_like(values) or isinstance(values, ABCDataFrame):
+        # This will raise later, but we avoid passing to maybe_convert_platform
+        return values
+    elif isinstance(getattr(values, "dtype", None), CategoricalDtype):
+        values = np.asarray(values)
+    elif not hasattr(values, "dtype") and not isinstance(values, (list, tuple, range)):
+        # TODO: should we just cast these to list?
+        return values
+    else:
+        values = extract_array(values, extract_numpy=True)
+
+    if not hasattr(values, "dtype"):
+        values = np.asarray(values)
+        if values.dtype.kind in "iu" and values.dtype != np.int64:
+            values = values.astype(np.int64)
+    return values
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/masked.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/masked.py
new file mode 100644
index 0000000000000000000000000000000000000000..da656a2768901b572abd8b43810f0f496a293e1c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/masked.py
@@ -0,0 +1,1669 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas._libs.tslibs import is_supported_dtype
+from pandas._typing import (
+    ArrayLike,
+    AstypeArg,
+    AxisInt,
+    DtypeObj,
+    FillnaOptions,
+    InterpolateOptions,
+    NpDtype,
+    PositionalIndexer,
+    Scalar,
+    ScalarIndexer,
+    Self,
+    SequenceIndexer,
+    Shape,
+    npt,
+)
+from pandas.compat import (
+    IS64,
+    is_platform_windows,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_fillna_kwargs
+
+from pandas.core.dtypes.base import ExtensionDtype
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_integer_dtype,
+    is_list_like,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import BaseMaskedDtype
+from pandas.core.dtypes.missing import (
+    array_equivalent,
+    is_valid_na_for_dtype,
+    isna,
+    notna,
+)
+
+from pandas.core import (
+    algorithms as algos,
+    arraylike,
+    missing,
+    nanops,
+    ops,
+)
+from pandas.core.algorithms import (
+    factorize_array,
+    isin,
+    map_array,
+    mode,
+    take,
+)
+from pandas.core.array_algos import (
+    masked_accumulations,
+    masked_reductions,
+)
+from pandas.core.array_algos.quantile import quantile_with_mask
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays._utils import to_numpy_dtype_inference
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.construction import (
+    array as pd_array,
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import check_array_indexer
+from pandas.core.ops import invalid_comparison
+from pandas.core.util.hashing import hash_array
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterator,
+        Sequence,
+    )
+    from pandas import Series
+    from pandas.core.arrays import BooleanArray
+    from pandas._typing import (
+        NumpySorter,
+        NumpyValueArrayLike,
+    )
+    from pandas.core.arrays import FloatingArray
+
+from pandas.compat.numpy import function as nv
+
+
+class BaseMaskedArray(OpsMixin, ExtensionArray):
+    """
+    Base class for masked arrays (which use _data and _mask to store the data).
+
+    numpy based
+    """
+
+    # The value used to fill '_data' to avoid upcasting
+    _internal_fill_value: Scalar
+    # our underlying data and mask are each ndarrays
+    _data: np.ndarray
+    _mask: npt.NDArray[np.bool_]
+
+    # Fill values used for any/all
+    _truthy_value = Scalar  # bool(_truthy_value) = True
+    _falsey_value = Scalar  # bool(_falsey_value) = False
+
+    @classmethod
+    def _simple_new(cls, values: np.ndarray, mask: npt.NDArray[np.bool_]) -> Self:
+        result = BaseMaskedArray.__new__(cls)
+        result._data = values
+        result._mask = mask
+        return result
+
+    def __init__(
+        self, values: np.ndarray, mask: npt.NDArray[np.bool_], copy: bool = False
+    ) -> None:
+        # values is supposed to already be validated in the subclass
+        if not (isinstance(mask, np.ndarray) and mask.dtype == np.bool_):
+            raise TypeError(
+                "mask should be boolean numpy array. Use "
+                "the 'pd.array' function instead"
+            )
+        if values.shape != mask.shape:
+            raise ValueError("values.shape must match mask.shape")
+
+        if copy:
+            values = values.copy()
+            mask = mask.copy()
+
+        self._data = values
+        self._mask = mask
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype=None, copy: bool = False) -> Self:
+        values, mask = cls._coerce_to_array(scalars, dtype=dtype, copy=copy)
+        return cls(values, mask)
+
+    @classmethod
+    @doc(ExtensionArray._empty)
+    def _empty(cls, shape: Shape, dtype: ExtensionDtype):
+        values = np.empty(shape, dtype=dtype.type)
+        values.fill(cls._internal_fill_value)
+        mask = np.ones(shape, dtype=bool)
+        result = cls(values, mask)
+        if not isinstance(result, cls) or dtype != result.dtype:
+            raise NotImplementedError(
+                f"Default 'empty' implementation is invalid for dtype='{dtype}'"
+            )
+        return result
+
+    def _formatter(self, boxed: bool = False) -> Callable[[Any], str | None]:
+        # NEP 51: https://github.com/numpy/numpy/pull/22449
+        return str
+
+    @property
+    def dtype(self) -> BaseMaskedDtype:
+        raise AbstractMethodError(self)
+
+    @overload
+    def __getitem__(self, item: ScalarIndexer) -> Any:
+        ...
+
+    @overload
+    def __getitem__(self, item: SequenceIndexer) -> Self:
+        ...
+
+    def __getitem__(self, item: PositionalIndexer) -> Self | Any:
+        item = check_array_indexer(self, item)
+
+        newmask = self._mask[item]
+        if is_bool(newmask):
+            # This is a scalar indexing
+            if newmask:
+                return self.dtype.na_value
+            return self._data[item]
+
+        return self._simple_new(self._data[item], newmask)
+
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        mask = self._mask
+
+        if mask.any():
+            func = missing.get_fill_func(method, ndim=self.ndim)
+
+            npvalues = self._data.T
+            new_mask = mask.T
+            if copy:
+                npvalues = npvalues.copy()
+                new_mask = new_mask.copy()
+            elif limit_area is not None:
+                mask = mask.copy()
+            func(npvalues, limit=limit, mask=new_mask)
+
+            if limit_area is not None and not mask.all():
+                mask = mask.T
+                neg_mask = ~mask
+                first = neg_mask.argmax()
+                last = len(neg_mask) - neg_mask[::-1].argmax() - 1
+                if limit_area == "inside":
+                    new_mask[:first] |= mask[:first]
+                    new_mask[last + 1 :] |= mask[last + 1 :]
+                elif limit_area == "outside":
+                    new_mask[first + 1 : last] |= mask[first + 1 : last]
+
+            if copy:
+                return self._simple_new(npvalues.T, new_mask.T)
+            else:
+                return self
+        else:
+            if copy:
+                new_values = self.copy()
+            else:
+                new_values = self
+        return new_values
+
+    @doc(ExtensionArray.fillna)
+    def fillna(
+        self, value=None, method=None, limit: int | None = None, copy: bool = True
+    ) -> Self:
+        value, method = validate_fillna_kwargs(value, method)
+
+        mask = self._mask
+
+        value = missing.check_value_size(value, mask, len(self))
+
+        if mask.any():
+            if method is not None:
+                func = missing.get_fill_func(method, ndim=self.ndim)
+                npvalues = self._data.T
+                new_mask = mask.T
+                if copy:
+                    npvalues = npvalues.copy()
+                    new_mask = new_mask.copy()
+                func(npvalues, limit=limit, mask=new_mask)
+                return self._simple_new(npvalues.T, new_mask.T)
+            else:
+                # fill with value
+                if copy:
+                    new_values = self.copy()
+                else:
+                    new_values = self[:]
+                new_values[mask] = value
+        else:
+            if copy:
+                new_values = self.copy()
+            else:
+                new_values = self[:]
+        return new_values
+
+    @classmethod
+    def _coerce_to_array(
+        cls, values, *, dtype: DtypeObj, copy: bool = False
+    ) -> tuple[np.ndarray, np.ndarray]:
+        raise AbstractMethodError(cls)
+
+    def _validate_setitem_value(self, value):
+        """
+        Check if we have a scalar that we can cast losslessly.
+
+        Raises
+        ------
+        TypeError
+        """
+        kind = self.dtype.kind
+        # TODO: get this all from np_can_hold_element?
+        if kind == "b":
+            if lib.is_bool(value):
+                return value
+
+        elif kind == "f":
+            if lib.is_integer(value) or lib.is_float(value):
+                return value
+
+        else:
+            if lib.is_integer(value) or (lib.is_float(value) and value.is_integer()):
+                return value
+            # TODO: unsigned checks
+
+        # Note: without the "str" here, the f-string rendering raises in
+        #  py38 builds.
+        raise TypeError(f"Invalid value '{value!s}' for dtype '{self.dtype}'")
+
+    def __setitem__(self, key, value) -> None:
+        key = check_array_indexer(self, key)
+
+        if is_scalar(value):
+            if is_valid_na_for_dtype(value, self.dtype):
+                self._mask[key] = True
+            else:
+                value = self._validate_setitem_value(value)
+                self._data[key] = value
+                self._mask[key] = False
+            return
+
+        value, mask = self._coerce_to_array(value, dtype=self.dtype)
+
+        self._data[key] = value
+        self._mask[key] = mask
+
+    def __contains__(self, key) -> bool:
+        if isna(key) and key is not self.dtype.na_value:
+            # GH#52840
+            if self._data.dtype.kind == "f" and lib.is_float(key):
+                return bool((np.isnan(self._data) & ~self._mask).any())
+
+        return bool(super().__contains__(key))
+
+    def __iter__(self) -> Iterator:
+        if self.ndim == 1:
+            if not self._hasna:
+                for val in self._data:
+                    yield val
+            else:
+                na_value = self.dtype.na_value
+                for isna_, val in zip(self._mask, self._data):
+                    if isna_:
+                        yield na_value
+                    else:
+                        yield val
+        else:
+            for i in range(len(self)):
+                yield self[i]
+
+    def __len__(self) -> int:
+        return len(self._data)
+
+    @property
+    def shape(self) -> Shape:
+        return self._data.shape
+
+    @property
+    def ndim(self) -> int:
+        return self._data.ndim
+
+    def swapaxes(self, axis1, axis2) -> Self:
+        data = self._data.swapaxes(axis1, axis2)
+        mask = self._mask.swapaxes(axis1, axis2)
+        return self._simple_new(data, mask)
+
+    def delete(self, loc, axis: AxisInt = 0) -> Self:
+        data = np.delete(self._data, loc, axis=axis)
+        mask = np.delete(self._mask, loc, axis=axis)
+        return self._simple_new(data, mask)
+
+    def reshape(self, *args, **kwargs) -> Self:
+        data = self._data.reshape(*args, **kwargs)
+        mask = self._mask.reshape(*args, **kwargs)
+        return self._simple_new(data, mask)
+
+    def ravel(self, *args, **kwargs) -> Self:
+        # TODO: need to make sure we have the same order for data/mask
+        data = self._data.ravel(*args, **kwargs)
+        mask = self._mask.ravel(*args, **kwargs)
+        return type(self)(data, mask)
+
+    @property
+    def T(self) -> Self:
+        return self._simple_new(self._data.T, self._mask.T)
+
+    def round(self, decimals: int = 0, *args, **kwargs):
+        """
+        Round each value in the array a to the given number of decimals.
+
+        Parameters
+        ----------
+        decimals : int, default 0
+            Number of decimal places to round to. If decimals is negative,
+            it specifies the number of positions to the left of the decimal point.
+        *args, **kwargs
+            Additional arguments and keywords have no effect but might be
+            accepted for compatibility with NumPy.
+
+        Returns
+        -------
+        NumericArray
+            Rounded values of the NumericArray.
+
+        See Also
+        --------
+        numpy.around : Round values of an np.array.
+        DataFrame.round : Round values of a DataFrame.
+        Series.round : Round values of a Series.
+        """
+        if self.dtype.kind == "b":
+            return self
+        nv.validate_round(args, kwargs)
+        values = np.round(self._data, decimals=decimals, **kwargs)
+
+        # Usually we'll get same type as self, but ndarray[bool] casts to float
+        return self._maybe_mask_result(values, self._mask.copy())
+
+    # ------------------------------------------------------------------
+    # Unary Methods
+
+    def __invert__(self) -> Self:
+        return self._simple_new(~self._data, self._mask.copy())
+
+    def __neg__(self) -> Self:
+        return self._simple_new(-self._data, self._mask.copy())
+
+    def __pos__(self) -> Self:
+        return self.copy()
+
+    def __abs__(self) -> Self:
+        return self._simple_new(abs(self._data), self._mask.copy())
+
+    # ------------------------------------------------------------------
+
+    def _values_for_json(self) -> np.ndarray:
+        return np.asarray(self, dtype=object)
+
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Convert to a NumPy Array.
+
+        By default converts to an object-dtype NumPy array. Specify the `dtype` and
+        `na_value` keywords to customize the conversion.
+
+        Parameters
+        ----------
+        dtype : dtype, default object
+            The numpy dtype to convert to.
+        copy : bool, default False
+            Whether to ensure that the returned value is a not a view on
+            the array. Note that ``copy=False`` does not *ensure* that
+            ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that
+            a copy is made, even if not strictly necessary. This is typically
+            only possible when no missing values are present and `dtype`
+            is the equivalent numpy dtype.
+        na_value : scalar, optional
+             Scalar missing value indicator to use in numpy array. Defaults
+             to the native missing value indicator of this array (pd.NA).
+
+        Returns
+        -------
+        numpy.ndarray
+
+        Examples
+        --------
+        An object-dtype is the default result
+
+        >>> a = pd.array([True, False, pd.NA], dtype="boolean")
+        >>> a.to_numpy()
+        array([True, False, ], dtype=object)
+
+        When no missing values are present, an equivalent dtype can be used.
+
+        >>> pd.array([True, False], dtype="boolean").to_numpy(dtype="bool")
+        array([ True, False])
+        >>> pd.array([1, 2], dtype="Int64").to_numpy("int64")
+        array([1, 2])
+
+        However, requesting such dtype will raise a ValueError if
+        missing values are present and the default missing value :attr:`NA`
+        is used.
+
+        >>> a = pd.array([True, False, pd.NA], dtype="boolean")
+        >>> a
+        
+        [True, False, ]
+        Length: 3, dtype: boolean
+
+        >>> a.to_numpy(dtype="bool")
+        Traceback (most recent call last):
+        ...
+        ValueError: cannot convert to bool numpy array in presence of missing values
+
+        Specify a valid `na_value` instead
+
+        >>> a.to_numpy(dtype="bool", na_value=False)
+        array([ True, False, False])
+        """
+        hasna = self._hasna
+        dtype, na_value = to_numpy_dtype_inference(self, dtype, na_value, hasna)
+        if dtype is None:
+            dtype = object
+
+        if hasna:
+            if (
+                dtype != object
+                and not is_string_dtype(dtype)
+                and na_value is libmissing.NA
+            ):
+                raise ValueError(
+                    f"cannot convert to '{dtype}'-dtype NumPy array "
+                    "with missing values. Specify an appropriate 'na_value' "
+                    "for this dtype."
+                )
+            # don't pass copy to astype -> always need a copy since we are mutating
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=RuntimeWarning)
+                data = self._data.astype(dtype)
+            data[self._mask] = na_value
+        else:
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=RuntimeWarning)
+                data = self._data.astype(dtype, copy=copy)
+        return data
+
+    @doc(ExtensionArray.tolist)
+    def tolist(self):
+        if self.ndim > 1:
+            return [x.tolist() for x in self]
+        dtype = None if self._hasna else self._data.dtype
+        return self.to_numpy(dtype=dtype, na_value=libmissing.NA).tolist()
+
+    @overload
+    def astype(self, dtype: npt.DTypeLike, copy: bool = ...) -> np.ndarray:
+        ...
+
+    @overload
+    def astype(self, dtype: ExtensionDtype, copy: bool = ...) -> ExtensionArray:
+        ...
+
+    @overload
+    def astype(self, dtype: AstypeArg, copy: bool = ...) -> ArrayLike:
+        ...
+
+    def astype(self, dtype: AstypeArg, copy: bool = True) -> ArrayLike:
+        dtype = pandas_dtype(dtype)
+
+        if dtype == self.dtype:
+            if copy:
+                return self.copy()
+            return self
+
+        # if we are astyping to another nullable masked dtype, we can fastpath
+        if isinstance(dtype, BaseMaskedDtype):
+            # TODO deal with NaNs for FloatingArray case
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=RuntimeWarning)
+                # TODO: Is rounding what we want long term?
+                data = self._data.astype(dtype.numpy_dtype, copy=copy)
+            # mask is copied depending on whether the data was copied, and
+            # not directly depending on the `copy` keyword
+            mask = self._mask if data is self._data else self._mask.copy()
+            cls = dtype.construct_array_type()
+            return cls(data, mask, copy=False)
+
+        if isinstance(dtype, ExtensionDtype):
+            eacls = dtype.construct_array_type()
+            return eacls._from_sequence(self, dtype=dtype, copy=copy)
+
+        na_value: float | np.datetime64 | lib.NoDefault
+
+        # coerce
+        if dtype.kind == "f":
+            # In astype, we consider dtype=float to also mean na_value=np.nan
+            na_value = np.nan
+        elif dtype.kind == "M":
+            na_value = np.datetime64("NaT")
+        else:
+            na_value = lib.no_default
+
+        # to_numpy will also raise, but we get somewhat nicer exception messages here
+        if dtype.kind in "iu" and self._hasna:
+            raise ValueError("cannot convert NA to integer")
+        if dtype.kind == "b" and self._hasna:
+            # careful: astype_nansafe converts np.nan to True
+            raise ValueError("cannot convert float NaN to bool")
+
+        data = self.to_numpy(dtype=dtype, na_value=na_value, copy=copy)
+        return data
+
+    __array_priority__ = 1000  # higher than ndarray so ops dispatch to us
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        """
+        the array interface, return my values
+        We return an object array here to preserve our scalar values
+        """
+        if copy is False:
+            if not self._hasna:
+                # special case, here we can simply return the underlying data
+                return np.array(self._data, dtype=dtype, copy=copy)
+
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if copy is None:
+            copy = False  # The NumPy copy=False meaning is different here.
+        return self.to_numpy(dtype=dtype, copy=copy)
+
+    _HANDLED_TYPES: tuple[type, ...]
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        # For MaskedArray inputs, we apply the ufunc to ._data
+        # and mask the result.
+
+        out = kwargs.get("out", ())
+
+        for x in inputs + out:
+            if not isinstance(x, self._HANDLED_TYPES + (BaseMaskedArray,)):
+                return NotImplemented
+
+        # for binary ops, use our custom dunder methods
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            # e.g. test_ufunc_with_out
+            return arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+
+        if method == "reduce":
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                return result
+
+        mask = np.zeros(len(self), dtype=bool)
+        inputs2 = []
+        for x in inputs:
+            if isinstance(x, BaseMaskedArray):
+                mask |= x._mask
+                inputs2.append(x._data)
+            else:
+                inputs2.append(x)
+
+        def reconstruct(x: np.ndarray):
+            # we don't worry about scalar `x` here, since we
+            # raise for reduce up above.
+            from pandas.core.arrays import (
+                BooleanArray,
+                FloatingArray,
+                IntegerArray,
+            )
+
+            if x.dtype.kind == "b":
+                m = mask.copy()
+                return BooleanArray(x, m)
+            elif x.dtype.kind in "iu":
+                m = mask.copy()
+                return IntegerArray(x, m)
+            elif x.dtype.kind == "f":
+                m = mask.copy()
+                if x.dtype == np.float16:
+                    # reached in e.g. np.sqrt on BooleanArray
+                    # we don't support float16
+                    x = x.astype(np.float32)
+                return FloatingArray(x, m)
+            else:
+                x[mask] = np.nan
+            return x
+
+        result = getattr(ufunc, method)(*inputs2, **kwargs)
+        if ufunc.nout > 1:
+            # e.g. np.divmod
+            return tuple(reconstruct(x) for x in result)
+        elif method == "reduce":
+            # e.g. np.add.reduce; test_ufunc_reduce_raises
+            if self._mask.any():
+                return self._na_value
+            return result
+        else:
+            return reconstruct(result)
+
+    def __arrow_array__(self, type=None):
+        """
+        Convert myself into a pyarrow Array.
+        """
+        import pyarrow as pa
+
+        return pa.array(self._data, mask=self._mask, type=type)
+
+    @property
+    def _hasna(self) -> bool:
+        # Note: this is expensive right now! The hope is that we can
+        # make this faster by having an optional mask, but not have to change
+        # source code using it..
+
+        # error: Incompatible return value type (got "bool_", expected "bool")
+        return self._mask.any()  # type: ignore[return-value]
+
+    def _propagate_mask(
+        self, mask: npt.NDArray[np.bool_] | None, other
+    ) -> npt.NDArray[np.bool_]:
+        if mask is None:
+            mask = self._mask.copy()  # TODO: need test for BooleanArray needing a copy
+            if other is libmissing.NA:
+                # GH#45421 don't alter inplace
+                mask = mask | True
+            elif is_list_like(other) and len(other) == len(mask):
+                mask = mask | isna(other)
+        else:
+            mask = self._mask | mask
+        # Incompatible return value type (got "Optional[ndarray[Any, dtype[bool_]]]",
+        # expected "ndarray[Any, dtype[bool_]]")
+        return mask  # type: ignore[return-value]
+
+    def _arith_method(self, other, op):
+        op_name = op.__name__
+        omask = None
+
+        if (
+            not hasattr(other, "dtype")
+            and is_list_like(other)
+            and len(other) == len(self)
+        ):
+            # Try inferring masked dtype instead of casting to object
+            other = pd_array(other)
+            other = extract_array(other, extract_numpy=True)
+
+        if isinstance(other, BaseMaskedArray):
+            other, omask = other._data, other._mask
+
+        elif is_list_like(other):
+            if not isinstance(other, ExtensionArray):
+                other = np.asarray(other)
+            if other.ndim > 1:
+                raise NotImplementedError("can only perform ops with 1-d structures")
+
+        # We wrap the non-masked arithmetic logic used for numpy dtypes
+        #  in Series/Index arithmetic ops.
+        other = ops.maybe_prepare_scalar_for_op(other, (len(self),))
+        pd_op = ops.get_array_op(op)
+        other = ensure_wrapped_if_datetimelike(other)
+
+        if op_name in {"pow", "rpow"} and isinstance(other, np.bool_):
+            # Avoid DeprecationWarning: In future, it will be an error
+            #  for 'np.bool_' scalars to be interpreted as an index
+            #  e.g. test_array_scalar_like_equivalence
+            other = bool(other)
+
+        mask = self._propagate_mask(omask, other)
+
+        if other is libmissing.NA:
+            result = np.ones_like(self._data)
+            if self.dtype.kind == "b":
+                if op_name in {
+                    "floordiv",
+                    "rfloordiv",
+                    "pow",
+                    "rpow",
+                    "truediv",
+                    "rtruediv",
+                }:
+                    # GH#41165 Try to match non-masked Series behavior
+                    #  This is still imperfect GH#46043
+                    raise NotImplementedError(
+                        f"operator '{op_name}' not implemented for bool dtypes"
+                    )
+                if op_name in {"mod", "rmod"}:
+                    dtype = "int8"
+                else:
+                    dtype = "bool"
+                result = result.astype(dtype)
+            elif "truediv" in op_name and self.dtype.kind != "f":
+                # The actual data here doesn't matter since the mask
+                #  will be all-True, but since this is division, we want
+                #  to end up with floating dtype.
+                result = result.astype(np.float64)
+        else:
+            # Make sure we do this before the "pow" mask checks
+            #  to get an expected exception message on shape mismatch.
+            if self.dtype.kind in "iu" and op_name in ["floordiv", "mod"]:
+                # TODO(GH#30188) ATM we don't match the behavior of non-masked
+                #  types with respect to floordiv-by-zero
+                pd_op = op
+
+            with np.errstate(all="ignore"):
+                result = pd_op(self._data, other)
+
+        if op_name == "pow":
+            # 1 ** x is 1.
+            mask = np.where((self._data == 1) & ~self._mask, False, mask)
+            # x ** 0 is 1.
+            if omask is not None:
+                mask = np.where((other == 0) & ~omask, False, mask)
+            elif other is not libmissing.NA:
+                mask = np.where(other == 0, False, mask)
+
+        elif op_name == "rpow":
+            # 1 ** x is 1.
+            if omask is not None:
+                mask = np.where((other == 1) & ~omask, False, mask)
+            elif other is not libmissing.NA:
+                mask = np.where(other == 1, False, mask)
+            # x ** 0 is 1.
+            mask = np.where((self._data == 0) & ~self._mask, False, mask)
+
+        return self._maybe_mask_result(result, mask)
+
+    _logical_method = _arith_method
+
+    def _cmp_method(self, other, op) -> BooleanArray:
+        from pandas.core.arrays import BooleanArray
+
+        mask = None
+
+        if isinstance(other, BaseMaskedArray):
+            other, mask = other._data, other._mask
+
+        elif is_list_like(other):
+            other = np.asarray(other)
+            if other.ndim > 1:
+                raise NotImplementedError("can only perform ops with 1-d structures")
+            if len(self) != len(other):
+                raise ValueError("Lengths must match to compare")
+
+        if other is libmissing.NA:
+            # numpy does not handle pd.NA well as "other" scalar (it returns
+            # a scalar False instead of an array)
+            # This may be fixed by NA.__array_ufunc__. Revisit this check
+            # once that's implemented.
+            result = np.zeros(self._data.shape, dtype="bool")
+            mask = np.ones(self._data.shape, dtype="bool")
+        else:
+            with warnings.catch_warnings():
+                # numpy may show a FutureWarning or DeprecationWarning:
+                #     elementwise comparison failed; returning scalar instead,
+                #     but in the future will perform elementwise comparison
+                # before returning NotImplemented. We fall back to the correct
+                # behavior today, so that should be fine to ignore.
+                warnings.filterwarnings("ignore", "elementwise", FutureWarning)
+                warnings.filterwarnings("ignore", "elementwise", DeprecationWarning)
+                method = getattr(self._data, f"__{op.__name__}__")
+                result = method(other)
+
+                if result is NotImplemented:
+                    result = invalid_comparison(self._data, other, op)
+
+        mask = self._propagate_mask(mask, other)
+        return BooleanArray(result, mask, copy=False)
+
+    def _maybe_mask_result(
+        self, result: np.ndarray | tuple[np.ndarray, np.ndarray], mask: np.ndarray
+    ):
+        """
+        Parameters
+        ----------
+        result : array-like or tuple[array-like]
+        mask : array-like bool
+        """
+        if isinstance(result, tuple):
+            # i.e. divmod
+            div, mod = result
+            return (
+                self._maybe_mask_result(div, mask),
+                self._maybe_mask_result(mod, mask),
+            )
+
+        if result.dtype.kind == "f":
+            from pandas.core.arrays import FloatingArray
+
+            return FloatingArray(result, mask, copy=False)
+
+        elif result.dtype.kind == "b":
+            from pandas.core.arrays import BooleanArray
+
+            return BooleanArray(result, mask, copy=False)
+
+        elif lib.is_np_dtype(result.dtype, "m") and is_supported_dtype(result.dtype):
+            # e.g. test_numeric_arr_mul_tdscalar_numexpr_path
+            from pandas.core.arrays import TimedeltaArray
+
+            result[mask] = result.dtype.type("NaT")
+
+            if not isinstance(result, TimedeltaArray):
+                return TimedeltaArray._simple_new(result, dtype=result.dtype)
+
+            return result
+
+        elif result.dtype.kind in "iu":
+            from pandas.core.arrays import IntegerArray
+
+            return IntegerArray(result, mask, copy=False)
+
+        else:
+            result[mask] = np.nan
+            return result
+
+    def isna(self) -> np.ndarray:
+        return self._mask.copy()
+
+    @property
+    def _na_value(self):
+        return self.dtype.na_value
+
+    @property
+    def nbytes(self) -> int:
+        return self._data.nbytes + self._mask.nbytes
+
+    @classmethod
+    def _concat_same_type(
+        cls,
+        to_concat: Sequence[Self],
+        axis: AxisInt = 0,
+    ) -> Self:
+        data = np.concatenate([x._data for x in to_concat], axis=axis)
+        mask = np.concatenate([x._mask for x in to_concat], axis=axis)
+        return cls(data, mask)
+
+    def _hash_pandas_object(
+        self, *, encoding: str, hash_key: str, categorize: bool
+    ) -> npt.NDArray[np.uint64]:
+        hashed_array = hash_array(
+            self._data, encoding=encoding, hash_key=hash_key, categorize=categorize
+        )
+        hashed_array[self.isna()] = hash(self.dtype.na_value)
+        return hashed_array
+
+    def take(
+        self,
+        indexer,
+        *,
+        allow_fill: bool = False,
+        fill_value: Scalar | None = None,
+        axis: AxisInt = 0,
+    ) -> Self:
+        # we always fill with 1 internally
+        # to avoid upcasting
+        data_fill_value = self._internal_fill_value if isna(fill_value) else fill_value
+        result = take(
+            self._data,
+            indexer,
+            fill_value=data_fill_value,
+            allow_fill=allow_fill,
+            axis=axis,
+        )
+
+        mask = take(
+            self._mask, indexer, fill_value=True, allow_fill=allow_fill, axis=axis
+        )
+
+        # if we are filling
+        # we only fill where the indexer is null
+        # not existing missing values
+        # TODO(jreback) what if we have a non-na float as a fill value?
+        if allow_fill and notna(fill_value):
+            fill_mask = np.asarray(indexer) == -1
+            result[fill_mask] = fill_value
+            mask = mask ^ fill_mask
+
+        return self._simple_new(result, mask)
+
+    # error: Return type "BooleanArray" of "isin" incompatible with return type
+    # "ndarray" in supertype "ExtensionArray"
+    def isin(self, values: ArrayLike) -> BooleanArray:  # type: ignore[override]
+        from pandas.core.arrays import BooleanArray
+
+        # algorithms.isin will eventually convert values to an ndarray, so no extra
+        # cost to doing it here first
+        values_arr = np.asarray(values)
+        result = isin(self._data, values_arr)
+
+        if self._hasna:
+            values_have_NA = values_arr.dtype == object and any(
+                val is self.dtype.na_value for val in values_arr
+            )
+
+            # For now, NA does not propagate so set result according to presence of NA,
+            # see https://github.com/pandas-dev/pandas/pull/38379 for some discussion
+            result[self._mask] = values_have_NA
+
+        mask = np.zeros(self._data.shape, dtype=bool)
+        return BooleanArray(result, mask, copy=False)
+
+    def copy(self) -> Self:
+        data = self._data.copy()
+        mask = self._mask.copy()
+        return self._simple_new(data, mask)
+
+    @doc(ExtensionArray.duplicated)
+    def duplicated(
+        self, keep: Literal["first", "last", False] = "first"
+    ) -> npt.NDArray[np.bool_]:
+        values = self._data
+        mask = self._mask
+        return algos.duplicated(values, keep=keep, mask=mask)
+
+    def unique(self) -> Self:
+        """
+        Compute the BaseMaskedArray of unique values.
+
+        Returns
+        -------
+        uniques : BaseMaskedArray
+        """
+        uniques, mask = algos.unique_with_mask(self._data, self._mask)
+        return self._simple_new(uniques, mask)
+
+    @doc(ExtensionArray.searchsorted)
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        if self._hasna:
+            raise ValueError(
+                "searchsorted requires array to be sorted, which is impossible "
+                "with NAs present."
+            )
+        if isinstance(value, ExtensionArray):
+            value = value.astype(object)
+        # Base class searchsorted would cast to object, which is *much* slower.
+        return self._data.searchsorted(value, side=side, sorter=sorter)
+
+    @doc(ExtensionArray.factorize)
+    def factorize(
+        self,
+        use_na_sentinel: bool = True,
+    ) -> tuple[np.ndarray, ExtensionArray]:
+        arr = self._data
+        mask = self._mask
+
+        # Use a sentinel for na; recode and add NA to uniques if necessary below
+        codes, uniques = factorize_array(arr, use_na_sentinel=True, mask=mask)
+
+        # check that factorize_array correctly preserves dtype.
+        assert uniques.dtype == self.dtype.numpy_dtype, (uniques.dtype, self.dtype)
+
+        has_na = mask.any()
+        if use_na_sentinel or not has_na:
+            size = len(uniques)
+        else:
+            # Make room for an NA value
+            size = len(uniques) + 1
+        uniques_mask = np.zeros(size, dtype=bool)
+        if not use_na_sentinel and has_na:
+            na_index = mask.argmax()
+            # Insert na with the proper code
+            if na_index == 0:
+                na_code = np.intp(0)
+            else:
+                na_code = codes[:na_index].max() + 1
+            codes[codes >= na_code] += 1
+            codes[codes == -1] = na_code
+            # dummy value for uniques; not used since uniques_mask will be True
+            uniques = np.insert(uniques, na_code, 0)
+            uniques_mask[na_code] = True
+        uniques_ea = self._simple_new(uniques, uniques_mask)
+
+        return codes, uniques_ea
+
+    @doc(ExtensionArray._values_for_argsort)
+    def _values_for_argsort(self) -> np.ndarray:
+        return self._data
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Returns a Series containing counts of each unique value.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of missing values.
+
+        Returns
+        -------
+        counts : Series
+
+        See Also
+        --------
+        Series.value_counts
+        """
+        from pandas import (
+            Index,
+            Series,
+        )
+        from pandas.arrays import IntegerArray
+
+        keys, value_counts, na_counter = algos.value_counts_arraylike(
+            self._data, dropna=dropna, mask=self._mask
+        )
+        mask_index = np.zeros((len(value_counts),), dtype=np.bool_)
+        mask = mask_index.copy()
+
+        if na_counter > 0:
+            mask_index[-1] = True
+
+        arr = IntegerArray(value_counts, mask)
+        index = Index(
+            self.dtype.construct_array_type()(
+                keys, mask_index  # type: ignore[arg-type]
+            )
+        )
+        return Series(arr, index=index, name="count", copy=False)
+
+    def _mode(self, dropna: bool = True) -> Self:
+        if dropna:
+            result = mode(self._data, dropna=dropna, mask=self._mask)
+            res_mask = np.zeros(result.shape, dtype=np.bool_)
+        else:
+            result, res_mask = mode(self._data, dropna=dropna, mask=self._mask)
+        result = type(self)(result, res_mask)  # type: ignore[arg-type]
+        return result[result.argsort()]
+
+    @doc(ExtensionArray.equals)
+    def equals(self, other) -> bool:
+        if type(self) != type(other):
+            return False
+        if other.dtype != self.dtype:
+            return False
+
+        # GH#44382 if e.g. self[1] is np.nan and other[1] is pd.NA, we are NOT
+        #  equal.
+        if not np.array_equal(self._mask, other._mask):
+            return False
+
+        left = self._data[~self._mask]
+        right = other._data[~other._mask]
+        return array_equivalent(left, right, strict_nan=True, dtype_equal=True)
+
+    def _quantile(
+        self, qs: npt.NDArray[np.float64], interpolation: str
+    ) -> BaseMaskedArray:
+        """
+        Dispatch to quantile_with_mask, needed because we do not have
+        _from_factorized.
+
+        Notes
+        -----
+        We assume that all impacted cases are 1D-only.
+        """
+        res = quantile_with_mask(
+            self._data,
+            mask=self._mask,
+            # TODO(GH#40932): na_value_for_dtype(self.dtype.numpy_dtype)
+            #  instead of np.nan
+            fill_value=np.nan,
+            qs=qs,
+            interpolation=interpolation,
+        )
+
+        if self._hasna:
+            # Our result mask is all-False unless we are all-NA, in which
+            #  case it is all-True.
+            if self.ndim == 2:
+                # I think this should be out_mask=self.isna().all(axis=1)
+                #  but am holding off until we have tests
+                raise NotImplementedError
+            if self.isna().all():
+                out_mask = np.ones(res.shape, dtype=bool)
+
+                if is_integer_dtype(self.dtype):
+                    # We try to maintain int dtype if possible for not all-na case
+                    # as well
+                    res = np.zeros(res.shape, dtype=self.dtype.numpy_dtype)
+            else:
+                out_mask = np.zeros(res.shape, dtype=bool)
+        else:
+            out_mask = np.zeros(res.shape, dtype=bool)
+        return self._maybe_mask_result(res, mask=out_mask)
+
+    # ------------------------------------------------------------------
+    # Reductions
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        if name in {"any", "all", "min", "max", "sum", "prod", "mean", "var", "std"}:
+            result = getattr(self, name)(skipna=skipna, **kwargs)
+        else:
+            # median, skew, kurt, sem
+            data = self._data
+            mask = self._mask
+            op = getattr(nanops, f"nan{name}")
+            axis = kwargs.pop("axis", None)
+            result = op(data, axis=axis, skipna=skipna, mask=mask, **kwargs)
+
+        if keepdims:
+            if isna(result):
+                return self._wrap_na_result(name=name, axis=0, mask_size=(1,))
+            else:
+                result = result.reshape(1)
+                mask = np.zeros(1, dtype=bool)
+                return self._maybe_mask_result(result, mask)
+
+        if isna(result):
+            return libmissing.NA
+        else:
+            return result
+
+    def _wrap_reduction_result(self, name: str, result, *, skipna, axis):
+        if isinstance(result, np.ndarray):
+            if skipna:
+                # we only retain mask for all-NA rows/columns
+                mask = self._mask.all(axis=axis)
+            else:
+                mask = self._mask.any(axis=axis)
+
+            return self._maybe_mask_result(result, mask)
+        return result
+
+    def _wrap_na_result(self, *, name, axis, mask_size):
+        mask = np.ones(mask_size, dtype=bool)
+
+        float_dtyp = "float32" if self.dtype == "Float32" else "float64"
+        if name in ["mean", "median", "var", "std", "skew", "kurt"]:
+            np_dtype = float_dtyp
+        elif name in ["min", "max"] or self.dtype.itemsize == 8:
+            np_dtype = self.dtype.numpy_dtype.name
+        else:
+            is_windows_or_32bit = is_platform_windows() or not IS64
+            int_dtyp = "int32" if is_windows_or_32bit else "int64"
+            uint_dtyp = "uint32" if is_windows_or_32bit else "uint64"
+            np_dtype = {"b": int_dtyp, "i": int_dtyp, "u": uint_dtyp, "f": float_dtyp}[
+                self.dtype.kind
+            ]
+
+        value = np.array([1], dtype=np_dtype)
+        return self._maybe_mask_result(value, mask=mask)
+
+    def _wrap_min_count_reduction_result(
+        self, name: str, result, *, skipna, min_count, axis
+    ):
+        if min_count == 0 and isinstance(result, np.ndarray):
+            return self._maybe_mask_result(result, np.zeros(result.shape, dtype=bool))
+        return self._wrap_reduction_result(name, result, skipna=skipna, axis=axis)
+
+    def sum(
+        self,
+        *,
+        skipna: bool = True,
+        min_count: int = 0,
+        axis: AxisInt | None = 0,
+        **kwargs,
+    ):
+        nv.validate_sum((), kwargs)
+
+        result = masked_reductions.sum(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            min_count=min_count,
+            axis=axis,
+        )
+        return self._wrap_min_count_reduction_result(
+            "sum", result, skipna=skipna, min_count=min_count, axis=axis
+        )
+
+    def prod(
+        self,
+        *,
+        skipna: bool = True,
+        min_count: int = 0,
+        axis: AxisInt | None = 0,
+        **kwargs,
+    ):
+        nv.validate_prod((), kwargs)
+
+        result = masked_reductions.prod(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            min_count=min_count,
+            axis=axis,
+        )
+        return self._wrap_min_count_reduction_result(
+            "prod", result, skipna=skipna, min_count=min_count, axis=axis
+        )
+
+    def mean(self, *, skipna: bool = True, axis: AxisInt | None = 0, **kwargs):
+        nv.validate_mean((), kwargs)
+        result = masked_reductions.mean(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            axis=axis,
+        )
+        return self._wrap_reduction_result("mean", result, skipna=skipna, axis=axis)
+
+    def var(
+        self, *, skipna: bool = True, axis: AxisInt | None = 0, ddof: int = 1, **kwargs
+    ):
+        nv.validate_stat_ddof_func((), kwargs, fname="var")
+        result = masked_reductions.var(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            axis=axis,
+            ddof=ddof,
+        )
+        return self._wrap_reduction_result("var", result, skipna=skipna, axis=axis)
+
+    def std(
+        self, *, skipna: bool = True, axis: AxisInt | None = 0, ddof: int = 1, **kwargs
+    ):
+        nv.validate_stat_ddof_func((), kwargs, fname="std")
+        result = masked_reductions.std(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            axis=axis,
+            ddof=ddof,
+        )
+        return self._wrap_reduction_result("std", result, skipna=skipna, axis=axis)
+
+    def min(self, *, skipna: bool = True, axis: AxisInt | None = 0, **kwargs):
+        nv.validate_min((), kwargs)
+        result = masked_reductions.min(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            axis=axis,
+        )
+        return self._wrap_reduction_result("min", result, skipna=skipna, axis=axis)
+
+    def max(self, *, skipna: bool = True, axis: AxisInt | None = 0, **kwargs):
+        nv.validate_max((), kwargs)
+        result = masked_reductions.max(
+            self._data,
+            self._mask,
+            skipna=skipna,
+            axis=axis,
+        )
+        return self._wrap_reduction_result("max", result, skipna=skipna, axis=axis)
+
+    def map(self, mapper, na_action=None):
+        return map_array(self.to_numpy(), mapper, na_action=na_action)
+
+    def any(self, *, skipna: bool = True, axis: AxisInt | None = 0, **kwargs):
+        """
+        Return whether any element is truthy.
+
+        Returns False unless there is at least one element that is truthy.
+        By default, NAs are skipped. If ``skipna=False`` is specified and
+        missing values are present, similar :ref:`Kleene logic `
+        is used as for logical operations.
+
+        .. versionchanged:: 1.4.0
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Exclude NA values. If the entire array is NA and `skipna` is
+            True, then the result will be False, as for an empty array.
+            If `skipna` is False, the result will still be True if there is
+            at least one element that is truthy, otherwise NA will be returned
+            if there are NA's present.
+        axis : int, optional, default 0
+        **kwargs : any, default None
+            Additional keywords have no effect but might be accepted for
+            compatibility with NumPy.
+
+        Returns
+        -------
+        bool or :attr:`pandas.NA`
+
+        See Also
+        --------
+        numpy.any : Numpy version of this method.
+        BaseMaskedArray.all : Return whether all elements are truthy.
+
+        Examples
+        --------
+        The result indicates whether any element is truthy (and by default
+        skips NAs):
+
+        >>> pd.array([True, False, True]).any()
+        True
+        >>> pd.array([True, False, pd.NA]).any()
+        True
+        >>> pd.array([False, False, pd.NA]).any()
+        False
+        >>> pd.array([], dtype="boolean").any()
+        False
+        >>> pd.array([pd.NA], dtype="boolean").any()
+        False
+        >>> pd.array([pd.NA], dtype="Float64").any()
+        False
+
+        With ``skipna=False``, the result can be NA if this is logically
+        required (whether ``pd.NA`` is True or False influences the result):
+
+        >>> pd.array([True, False, pd.NA]).any(skipna=False)
+        True
+        >>> pd.array([1, 0, pd.NA]).any(skipna=False)
+        True
+        >>> pd.array([False, False, pd.NA]).any(skipna=False)
+        
+        >>> pd.array([0, 0, pd.NA]).any(skipna=False)
+        
+        """
+        nv.validate_any((), kwargs)
+
+        values = self._data.copy()
+        # error: Argument 3 to "putmask" has incompatible type "object";
+        # expected "Union[_SupportsArray[dtype[Any]],
+        # _NestedSequence[_SupportsArray[dtype[Any]]],
+        # bool, int, float, complex, str, bytes,
+        # _NestedSequence[Union[bool, int, float, complex, str, bytes]]]"
+        np.putmask(values, self._mask, self._falsey_value)  # type: ignore[arg-type]
+        result = values.any()
+        if skipna:
+            return result
+        else:
+            if result or len(self) == 0 or not self._mask.any():
+                return result
+            else:
+                return self.dtype.na_value
+
+    def all(self, *, skipna: bool = True, axis: AxisInt | None = 0, **kwargs):
+        """
+        Return whether all elements are truthy.
+
+        Returns True unless there is at least one element that is falsey.
+        By default, NAs are skipped. If ``skipna=False`` is specified and
+        missing values are present, similar :ref:`Kleene logic `
+        is used as for logical operations.
+
+        .. versionchanged:: 1.4.0
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Exclude NA values. If the entire array is NA and `skipna` is
+            True, then the result will be True, as for an empty array.
+            If `skipna` is False, the result will still be False if there is
+            at least one element that is falsey, otherwise NA will be returned
+            if there are NA's present.
+        axis : int, optional, default 0
+        **kwargs : any, default None
+            Additional keywords have no effect but might be accepted for
+            compatibility with NumPy.
+
+        Returns
+        -------
+        bool or :attr:`pandas.NA`
+
+        See Also
+        --------
+        numpy.all : Numpy version of this method.
+        BooleanArray.any : Return whether any element is truthy.
+
+        Examples
+        --------
+        The result indicates whether all elements are truthy (and by default
+        skips NAs):
+
+        >>> pd.array([True, True, pd.NA]).all()
+        True
+        >>> pd.array([1, 1, pd.NA]).all()
+        True
+        >>> pd.array([True, False, pd.NA]).all()
+        False
+        >>> pd.array([], dtype="boolean").all()
+        True
+        >>> pd.array([pd.NA], dtype="boolean").all()
+        True
+        >>> pd.array([pd.NA], dtype="Float64").all()
+        True
+
+        With ``skipna=False``, the result can be NA if this is logically
+        required (whether ``pd.NA`` is True or False influences the result):
+
+        >>> pd.array([True, True, pd.NA]).all(skipna=False)
+        
+        >>> pd.array([1, 1, pd.NA]).all(skipna=False)
+        
+        >>> pd.array([True, False, pd.NA]).all(skipna=False)
+        False
+        >>> pd.array([1, 0, pd.NA]).all(skipna=False)
+        False
+        """
+        nv.validate_all((), kwargs)
+
+        values = self._data.copy()
+        # error: Argument 3 to "putmask" has incompatible type "object";
+        # expected "Union[_SupportsArray[dtype[Any]],
+        # _NestedSequence[_SupportsArray[dtype[Any]]],
+        # bool, int, float, complex, str, bytes,
+        # _NestedSequence[Union[bool, int, float, complex, str, bytes]]]"
+        np.putmask(values, self._mask, self._truthy_value)  # type: ignore[arg-type]
+        result = values.all(axis=axis)
+
+        if skipna:
+            return result
+        else:
+            if not result or len(self) == 0 or not self._mask.any():
+                return result
+            else:
+                return self.dtype.na_value
+
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        axis: int,
+        index,
+        limit,
+        limit_direction,
+        limit_area,
+        copy: bool,
+        **kwargs,
+    ) -> FloatingArray:
+        """
+        See NDFrame.interpolate.__doc__.
+        """
+        # NB: we return type(self) even if copy=False
+        if self.dtype.kind == "f":
+            if copy:
+                data = self._data.copy()
+                mask = self._mask.copy()
+            else:
+                data = self._data
+                mask = self._mask
+        elif self.dtype.kind in "iu":
+            copy = True
+            data = self._data.astype("f8")
+            mask = self._mask.copy()
+        else:
+            raise NotImplementedError(
+                f"interpolate is not implemented for dtype={self.dtype}"
+            )
+
+        missing.interpolate_2d_inplace(
+            data,
+            method=method,
+            axis=0,
+            index=index,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            mask=mask,
+            **kwargs,
+        )
+        if not copy:
+            return self  # type: ignore[return-value]
+        if self.dtype.kind == "f":
+            return type(self)._simple_new(data, mask)  # type: ignore[return-value]
+        else:
+            from pandas.core.arrays import FloatingArray
+
+            return FloatingArray._simple_new(data, mask)
+
+    def _accumulate(
+        self, name: str, *, skipna: bool = True, **kwargs
+    ) -> BaseMaskedArray:
+        data = self._data
+        mask = self._mask
+
+        op = getattr(masked_accumulations, name)
+        data, mask = op(data, mask, skipna=skipna, **kwargs)
+
+        return self._simple_new(data, mask)
+
+    # ------------------------------------------------------------------
+    # GroupBy Methods
+
+    def _groupby_op(
+        self,
+        *,
+        how: str,
+        has_dropped_na: bool,
+        min_count: int,
+        ngroups: int,
+        ids: npt.NDArray[np.intp],
+        **kwargs,
+    ):
+        from pandas.core.groupby.ops import WrappedCythonOp
+
+        kind = WrappedCythonOp.get_kind_from_how(how)
+        op = WrappedCythonOp(how=how, kind=kind, has_dropped_na=has_dropped_na)
+
+        # libgroupby functions are responsible for NOT altering mask
+        mask = self._mask
+        if op.kind != "aggregate":
+            result_mask = mask.copy()
+        else:
+            result_mask = np.zeros(ngroups, dtype=bool)
+
+        if how == "rank" and kwargs.get("na_option") in ["top", "bottom"]:
+            result_mask[:] = False
+
+        res_values = op._cython_op_ndim_compat(
+            self._data,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=ids,
+            mask=mask,
+            result_mask=result_mask,
+            **kwargs,
+        )
+
+        if op.how == "ohlc":
+            arity = op._cython_arity.get(op.how, 1)
+            result_mask = np.tile(result_mask, (arity, 1)).T
+
+        if op.how in ["idxmin", "idxmax"]:
+            # Result values are indexes to take, keep as ndarray
+            return res_values
+        else:
+            # res_values should already have the correct dtype, we just need to
+            #  wrap in a MaskedArray
+            return self._maybe_mask_result(res_values, result_mask)
+
+
+def transpose_homogeneous_masked_arrays(
+    masked_arrays: Sequence[BaseMaskedArray],
+) -> list[BaseMaskedArray]:
+    """Transpose masked arrays in a list, but faster.
+
+    Input should be a list of 1-dim masked arrays of equal length and all have the
+    same dtype. The caller is responsible for ensuring validity of input data.
+    """
+    masked_arrays = list(masked_arrays)
+    dtype = masked_arrays[0].dtype
+
+    values = [arr._data.reshape(1, -1) for arr in masked_arrays]
+    transposed_values = np.concatenate(
+        values,
+        axis=0,
+        out=np.empty(
+            (len(masked_arrays), len(masked_arrays[0])),
+            order="F",
+            dtype=dtype.numpy_dtype,
+        ),
+    )
+
+    masks = [arr._mask.reshape(1, -1) for arr in masked_arrays]
+    transposed_masks = np.concatenate(
+        masks, axis=0, out=np.empty_like(transposed_values, dtype=bool)
+    )
+
+    arr_type = dtype.construct_array_type()
+    transposed_arrays: list[BaseMaskedArray] = []
+    for i in range(transposed_values.shape[1]):
+        transposed_arr = arr_type(transposed_values[:, i], mask=transposed_masks[:, i])
+        transposed_arrays.append(transposed_arr)
+
+    return transposed_arrays
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/numeric.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/numeric.py
new file mode 100644
index 0000000000000000000000000000000000000000..68fa7fcb6573c6b5ec754ca65263f8ddd6a6ba74
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/numeric.py
@@ -0,0 +1,286 @@
+from __future__ import annotations
+
+import numbers
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import cache_readonly
+
+from pandas.core.dtypes.common import (
+    is_integer_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+
+from pandas.core.arrays.masked import (
+    BaseMaskedArray,
+    BaseMaskedDtype,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+    import pyarrow
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        Self,
+        npt,
+    )
+
+
+class NumericDtype(BaseMaskedDtype):
+    _default_np_dtype: np.dtype
+    _checker: Callable[[Any], bool]  # is_foo_dtype
+
+    def __repr__(self) -> str:
+        return f"{self.name}Dtype()"
+
+    @cache_readonly
+    def is_signed_integer(self) -> bool:
+        return self.kind == "i"
+
+    @cache_readonly
+    def is_unsigned_integer(self) -> bool:
+        return self.kind == "u"
+
+    @property
+    def _is_numeric(self) -> bool:
+        return True
+
+    def __from_arrow__(
+        self, array: pyarrow.Array | pyarrow.ChunkedArray
+    ) -> BaseMaskedArray:
+        """
+        Construct IntegerArray/FloatingArray from pyarrow Array/ChunkedArray.
+        """
+        import pyarrow
+
+        from pandas.core.arrays.arrow._arrow_utils import (
+            pyarrow_array_to_numpy_and_mask,
+        )
+
+        array_class = self.construct_array_type()
+
+        pyarrow_type = pyarrow.from_numpy_dtype(self.type)
+        if not array.type.equals(pyarrow_type) and not pyarrow.types.is_null(
+            array.type
+        ):
+            # test_from_arrow_type_error raise for string, but allow
+            #  through itemsize conversion GH#31896
+            rt_dtype = pandas_dtype(array.type.to_pandas_dtype())
+            if rt_dtype.kind not in "iuf":
+                # Could allow "c" or potentially disallow float<->int conversion,
+                #  but at the moment we specifically test that uint<->int works
+                raise TypeError(
+                    f"Expected array of {self} type, got {array.type} instead"
+                )
+
+            array = array.cast(pyarrow_type)
+
+        if isinstance(array, pyarrow.ChunkedArray):
+            # TODO this "if" can be removed when requiring pyarrow >= 10.0, which fixed
+            # combine_chunks for empty arrays https://github.com/apache/arrow/pull/13757
+            if array.num_chunks == 0:
+                array = pyarrow.array([], type=array.type)
+            else:
+                array = array.combine_chunks()
+
+        data, mask = pyarrow_array_to_numpy_and_mask(array, dtype=self.numpy_dtype)
+        return array_class(data.copy(), ~mask, copy=False)
+
+    @classmethod
+    def _get_dtype_mapping(cls) -> Mapping[np.dtype, NumericDtype]:
+        raise AbstractMethodError(cls)
+
+    @classmethod
+    def _standardize_dtype(cls, dtype: NumericDtype | str | np.dtype) -> NumericDtype:
+        """
+        Convert a string representation or a numpy dtype to NumericDtype.
+        """
+        if isinstance(dtype, str) and (dtype.startswith(("Int", "UInt", "Float"))):
+            # Avoid DeprecationWarning from NumPy about np.dtype("Int64")
+            # https://github.com/numpy/numpy/pull/7476
+            dtype = dtype.lower()
+
+        if not isinstance(dtype, NumericDtype):
+            mapping = cls._get_dtype_mapping()
+            try:
+                dtype = mapping[np.dtype(dtype)]
+            except KeyError as err:
+                raise ValueError(f"invalid dtype specified {dtype}") from err
+        return dtype
+
+    @classmethod
+    def _safe_cast(cls, values: np.ndarray, dtype: np.dtype, copy: bool) -> np.ndarray:
+        """
+        Safely cast the values to the given dtype.
+
+        "safe" in this context means the casting is lossless.
+        """
+        raise AbstractMethodError(cls)
+
+
+def _coerce_to_data_and_mask(
+    values, dtype, copy: bool, dtype_cls: type[NumericDtype], default_dtype: np.dtype
+):
+    checker = dtype_cls._checker
+
+    mask = None
+    inferred_type = None
+
+    if dtype is None and hasattr(values, "dtype"):
+        if checker(values.dtype):
+            dtype = values.dtype
+
+    if dtype is not None:
+        dtype = dtype_cls._standardize_dtype(dtype)
+
+    cls = dtype_cls.construct_array_type()
+    if isinstance(values, cls):
+        values, mask = values._data, values._mask
+        if dtype is not None:
+            values = values.astype(dtype.numpy_dtype, copy=False)
+
+        if copy:
+            values = values.copy()
+            mask = mask.copy()
+        return values, mask, dtype, inferred_type
+
+    original = values
+    if not copy:
+        values = np.asarray(values)
+    else:
+        values = np.array(values, copy=copy)
+    inferred_type = None
+    if values.dtype == object or is_string_dtype(values.dtype):
+        inferred_type = lib.infer_dtype(values, skipna=True)
+        if inferred_type == "boolean" and dtype is None:
+            name = dtype_cls.__name__.strip("_")
+            raise TypeError(f"{values.dtype} cannot be converted to {name}")
+
+    elif values.dtype.kind == "b" and checker(dtype):
+        if not copy:
+            values = np.asarray(values, dtype=default_dtype)
+        else:
+            values = np.array(values, dtype=default_dtype, copy=copy)
+
+    elif values.dtype.kind not in "iuf":
+        name = dtype_cls.__name__.strip("_")
+        raise TypeError(f"{values.dtype} cannot be converted to {name}")
+
+    if values.ndim != 1:
+        raise TypeError("values must be a 1D list-like")
+
+    if mask is None:
+        if values.dtype.kind in "iu":
+            # fastpath
+            mask = np.zeros(len(values), dtype=np.bool_)
+        else:
+            mask = libmissing.is_numeric_na(values)
+    else:
+        assert len(mask) == len(values)
+
+    if mask.ndim != 1:
+        raise TypeError("mask must be a 1D list-like")
+
+    # infer dtype if needed
+    if dtype is None:
+        dtype = default_dtype
+    else:
+        dtype = dtype.numpy_dtype
+
+    if is_integer_dtype(dtype) and values.dtype.kind == "f" and len(values) > 0:
+        if mask.all():
+            values = np.ones(values.shape, dtype=dtype)
+        else:
+            idx = np.nanargmax(values)
+            if int(values[idx]) != original[idx]:
+                # We have ints that lost precision during the cast.
+                inferred_type = lib.infer_dtype(original, skipna=True)
+                if (
+                    inferred_type not in ["floating", "mixed-integer-float"]
+                    and not mask.any()
+                ):
+                    values = np.asarray(original, dtype=dtype)
+                else:
+                    values = np.asarray(original, dtype="object")
+
+    # we copy as need to coerce here
+    if mask.any():
+        values = values.copy()
+        values[mask] = cls._internal_fill_value
+    if inferred_type in ("string", "unicode"):
+        # casts from str are always safe since they raise
+        # a ValueError if the str cannot be parsed into a float
+        values = values.astype(dtype, copy=copy)
+    else:
+        values = dtype_cls._safe_cast(values, dtype, copy=False)
+
+    return values, mask, dtype, inferred_type
+
+
+class NumericArray(BaseMaskedArray):
+    """
+    Base class for IntegerArray and FloatingArray.
+    """
+
+    _dtype_cls: type[NumericDtype]
+
+    def __init__(
+        self, values: np.ndarray, mask: npt.NDArray[np.bool_], copy: bool = False
+    ) -> None:
+        checker = self._dtype_cls._checker
+        if not (isinstance(values, np.ndarray) and checker(values.dtype)):
+            descr = (
+                "floating"
+                if self._dtype_cls.kind == "f"  # type: ignore[comparison-overlap]
+                else "integer"
+            )
+            raise TypeError(
+                f"values should be {descr} numpy array. Use "
+                "the 'pd.array' function instead"
+            )
+        if values.dtype == np.float16:
+            # If we don't raise here, then accessing self.dtype would raise
+            raise TypeError("FloatingArray does not support np.float16 dtype.")
+
+        super().__init__(values, mask, copy=copy)
+
+    @cache_readonly
+    def dtype(self) -> NumericDtype:
+        mapping = self._dtype_cls._get_dtype_mapping()
+        return mapping[self._data.dtype]
+
+    @classmethod
+    def _coerce_to_array(
+        cls, value, *, dtype: DtypeObj, copy: bool = False
+    ) -> tuple[np.ndarray, np.ndarray]:
+        dtype_cls = cls._dtype_cls
+        default_dtype = dtype_cls._default_np_dtype
+        values, mask, _, _ = _coerce_to_data_and_mask(
+            value, dtype, copy, dtype_cls, default_dtype
+        )
+        return values, mask
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, *, dtype: Dtype | None = None, copy: bool = False
+    ) -> Self:
+        from pandas.core.tools.numeric import to_numeric
+
+        scalars = to_numeric(strings, errors="raise", dtype_backend="numpy_nullable")
+        return cls._from_sequence(scalars, dtype=dtype, copy=copy)
+
+    _HANDLED_TYPES = (np.ndarray, numbers.Number)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/numpy_.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/numpy_.py
new file mode 100644
index 0000000000000000000000000000000000000000..07fd207933fc15bc26d0b001fff434f45bf0c3f6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/numpy_.py
@@ -0,0 +1,582 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs import is_supported_dtype
+from pandas.compat.numpy import function as nv
+
+from pandas.core.dtypes.astype import astype_array
+from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
+from pandas.core.dtypes.common import pandas_dtype
+from pandas.core.dtypes.dtypes import NumpyEADtype
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import (
+    arraylike,
+    missing,
+    nanops,
+    ops,
+)
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+from pandas.core.strings.object_array import ObjectStringArrayMixin
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    from pandas._typing import (
+        AxisInt,
+        Dtype,
+        FillnaOptions,
+        InterpolateOptions,
+        NpDtype,
+        Scalar,
+        Self,
+        npt,
+    )
+
+    from pandas import Index
+
+
+# error: Definition of "_concat_same_type" in base class "NDArrayBacked" is
+# incompatible with definition in base class "ExtensionArray"
+class NumpyExtensionArray(  # type: ignore[misc]
+    OpsMixin,
+    NDArrayBackedExtensionArray,
+    ObjectStringArrayMixin,
+):
+    """
+    A pandas ExtensionArray for NumPy data.
+
+    This is mostly for internal compatibility, and is not especially
+    useful on its own.
+
+    Parameters
+    ----------
+    values : ndarray
+        The NumPy ndarray to wrap. Must be 1-dimensional.
+    copy : bool, default False
+        Whether to copy `values`.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.arrays.NumpyExtensionArray(np.array([0, 1, 2, 3]))
+    
+    [0, 1, 2, 3]
+    Length: 4, dtype: int64
+    """
+
+    # If you're wondering why pd.Series(cls) doesn't put the array in an
+    # ExtensionBlock, search for `ABCNumpyExtensionArray`. We check for
+    # that _typ to ensure that users don't unnecessarily use EAs inside
+    # pandas internals, which turns off things like block consolidation.
+    _typ = "npy_extension"
+    __array_priority__ = 1000
+    _ndarray: np.ndarray
+    _dtype: NumpyEADtype
+    _internal_fill_value = np.nan
+
+    # ------------------------------------------------------------------------
+    # Constructors
+
+    def __init__(
+        self, values: np.ndarray | NumpyExtensionArray, copy: bool = False
+    ) -> None:
+        if isinstance(values, type(self)):
+            values = values._ndarray
+        if not isinstance(values, np.ndarray):
+            raise ValueError(
+                f"'values' must be a NumPy array, not {type(values).__name__}"
+            )
+
+        if values.ndim == 0:
+            # Technically we support 2, but do not advertise that fact.
+            raise ValueError("NumpyExtensionArray must be 1-dimensional.")
+
+        if copy:
+            values = values.copy()
+
+        dtype = NumpyEADtype(values.dtype)
+        super().__init__(values, dtype)
+
+    @classmethod
+    def _from_sequence(
+        cls, scalars, *, dtype: Dtype | None = None, copy: bool = False
+    ) -> NumpyExtensionArray:
+        if isinstance(dtype, NumpyEADtype):
+            dtype = dtype._dtype
+
+        # error: Argument "dtype" to "asarray" has incompatible type
+        # "Union[ExtensionDtype, str, dtype[Any], dtype[floating[_64Bit]], Type[object],
+        # None]"; expected "Union[dtype[Any], None, type, _SupportsDType, str,
+        # Union[Tuple[Any, int], Tuple[Any, Union[int, Sequence[int]]], List[Any],
+        # _DTypeDict, Tuple[Any, Any]]]"
+        result = np.asarray(scalars, dtype=dtype)  # type: ignore[arg-type]
+        if (
+            result.ndim > 1
+            and not hasattr(scalars, "dtype")
+            and (dtype is None or dtype == object)
+        ):
+            # e.g. list-of-tuples
+            result = construct_1d_object_array_from_listlike(scalars)
+
+        if copy and result is scalars:
+            result = result.copy()
+        return cls(result)
+
+    # ------------------------------------------------------------------------
+    # Data
+
+    @property
+    def dtype(self) -> NumpyEADtype:
+        return self._dtype
+
+    # ------------------------------------------------------------------------
+    # NumPy Array Interface
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        if copy is not None:
+            # Note: branch avoids `copy=None` for NumPy 1.x support
+            return np.array(self._ndarray, dtype=dtype, copy=copy)
+        return np.asarray(self._ndarray, dtype=dtype)
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        # Lightly modified version of
+        # https://numpy.org/doc/stable/reference/generated/numpy.lib.mixins.NDArrayOperatorsMixin.html
+        # The primary modification is not boxing scalar return values
+        # in NumpyExtensionArray, since pandas' ExtensionArrays are 1-d.
+        out = kwargs.get("out", ())
+
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            # e.g. test_ufunc_unary
+            return arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+
+        if method == "reduce":
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                # e.g. tests.series.test_ufunc.TestNumpyReductions
+                return result
+
+        # Defer to the implementation of the ufunc on unwrapped values.
+        inputs = tuple(
+            x._ndarray if isinstance(x, NumpyExtensionArray) else x for x in inputs
+        )
+        if out:
+            kwargs["out"] = tuple(
+                x._ndarray if isinstance(x, NumpyExtensionArray) else x for x in out
+            )
+        result = getattr(ufunc, method)(*inputs, **kwargs)
+
+        if ufunc.nout > 1:
+            # multiple return values; re-box array-like results
+            return tuple(type(self)(x) for x in result)
+        elif method == "at":
+            # no return value
+            return None
+        elif method == "reduce":
+            if isinstance(result, np.ndarray):
+                # e.g. test_np_reduce_2d
+                return type(self)(result)
+
+            # e.g. test_np_max_nested_tuples
+            return result
+        else:
+            if self.dtype.type is str:  # type: ignore[comparison-overlap]
+                # StringDtype
+                try:
+                    return type(self)(result)
+                except ValueError:
+                    # if validation of input fails (no strings)
+                    # -> fallback to returning raw numpy array
+                    return result
+            # one return value; re-box array-like results
+            return type(self)(result)
+
+    # ------------------------------------------------------------------------
+    # Pandas ExtensionArray Interface
+
+    def astype(self, dtype, copy: bool = True):
+        dtype = pandas_dtype(dtype)
+
+        if dtype == self.dtype:
+            if copy:
+                return self.copy()
+            return self
+
+        result = astype_array(self._ndarray, dtype=dtype, copy=copy)
+        return result
+
+    def isna(self) -> np.ndarray:
+        return isna(self._ndarray)
+
+    def _validate_scalar(self, fill_value):
+        if fill_value is None:
+            # Primarily for subclasses
+            fill_value = self.dtype.na_value
+        return fill_value
+
+    def _values_for_factorize(self) -> tuple[np.ndarray, float | None]:
+        if self.dtype.kind in "iub":
+            fv = None
+        else:
+            fv = np.nan
+        return self._ndarray, fv
+
+    # Base EA class (and all other EA classes) don't have limit_area keyword
+    # This can be removed here as well when the interpolate ffill/bfill method
+    # deprecation is enforced
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        """
+        ffill or bfill along axis=0.
+        """
+        if copy:
+            out_data = self._ndarray.copy()
+        else:
+            out_data = self._ndarray
+
+        meth = missing.clean_fill_method(method)
+        missing.pad_or_backfill_inplace(
+            out_data.T,
+            method=meth,
+            axis=0,
+            limit=limit,
+            limit_area=limit_area,
+        )
+
+        if not copy:
+            return self
+        return type(self)._simple_new(out_data, dtype=self.dtype)
+
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        axis: int,
+        index: Index,
+        limit,
+        limit_direction,
+        limit_area,
+        copy: bool,
+        **kwargs,
+    ) -> Self:
+        """
+        See NDFrame.interpolate.__doc__.
+        """
+        # NB: we return type(self) even if copy=False
+        if not self.dtype._is_numeric:
+            raise TypeError(f"Cannot interpolate with {self.dtype} dtype")
+
+        if not copy:
+            out_data = self._ndarray
+        else:
+            out_data = self._ndarray.copy()
+
+        # TODO: assert we have floating dtype?
+        missing.interpolate_2d_inplace(
+            out_data,
+            method=method,
+            axis=axis,
+            index=index,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            **kwargs,
+        )
+        if not copy:
+            return self
+        return type(self)._simple_new(out_data, dtype=self.dtype)
+
+    # ------------------------------------------------------------------------
+    # Reductions
+
+    def any(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        out=None,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_any((), {"out": out, "keepdims": keepdims})
+        result = nanops.nanany(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def all(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        out=None,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_all((), {"out": out, "keepdims": keepdims})
+        result = nanops.nanall(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def min(
+        self, *, axis: AxisInt | None = None, skipna: bool = True, **kwargs
+    ) -> Scalar:
+        nv.validate_min((), kwargs)
+        result = nanops.nanmin(
+            values=self._ndarray, axis=axis, mask=self.isna(), skipna=skipna
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def max(
+        self, *, axis: AxisInt | None = None, skipna: bool = True, **kwargs
+    ) -> Scalar:
+        nv.validate_max((), kwargs)
+        result = nanops.nanmax(
+            values=self._ndarray, axis=axis, mask=self.isna(), skipna=skipna
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def sum(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        skipna: bool = True,
+        min_count: int = 0,
+        **kwargs,
+    ) -> Scalar:
+        nv.validate_sum((), kwargs)
+        result = nanops.nansum(
+            self._ndarray, axis=axis, skipna=skipna, min_count=min_count
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def prod(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        skipna: bool = True,
+        min_count: int = 0,
+        **kwargs,
+    ) -> Scalar:
+        nv.validate_prod((), kwargs)
+        result = nanops.nanprod(
+            self._ndarray, axis=axis, skipna=skipna, min_count=min_count
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def mean(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_mean((), {"dtype": dtype, "out": out, "keepdims": keepdims})
+        result = nanops.nanmean(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def median(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        out=None,
+        overwrite_input: bool = False,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_median(
+            (), {"out": out, "overwrite_input": overwrite_input, "keepdims": keepdims}
+        )
+        result = nanops.nanmedian(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def std(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        ddof: int = 1,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="std"
+        )
+        result = nanops.nanstd(self._ndarray, axis=axis, skipna=skipna, ddof=ddof)
+        return self._wrap_reduction_result(axis, result)
+
+    def var(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        ddof: int = 1,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="var"
+        )
+        result = nanops.nanvar(self._ndarray, axis=axis, skipna=skipna, ddof=ddof)
+        return self._wrap_reduction_result(axis, result)
+
+    def sem(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        ddof: int = 1,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="sem"
+        )
+        result = nanops.nansem(self._ndarray, axis=axis, skipna=skipna, ddof=ddof)
+        return self._wrap_reduction_result(axis, result)
+
+    def kurt(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="kurt"
+        )
+        result = nanops.nankurt(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    def skew(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="skew"
+        )
+        result = nanops.nanskew(self._ndarray, axis=axis, skipna=skipna)
+        return self._wrap_reduction_result(axis, result)
+
+    # ------------------------------------------------------------------------
+    # Additional Methods
+
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        mask = self.isna()
+        if na_value is not lib.no_default and mask.any():
+            result = self._ndarray.copy()
+            result[mask] = na_value
+        else:
+            result = self._ndarray
+
+        result = np.asarray(result, dtype=dtype)
+
+        if copy and result is self._ndarray:
+            result = result.copy()
+
+        return result
+
+    # ------------------------------------------------------------------------
+    # Ops
+
+    def __invert__(self) -> NumpyExtensionArray:
+        return type(self)(~self._ndarray)
+
+    def __neg__(self) -> NumpyExtensionArray:
+        return type(self)(-self._ndarray)
+
+    def __pos__(self) -> NumpyExtensionArray:
+        return type(self)(+self._ndarray)
+
+    def __abs__(self) -> NumpyExtensionArray:
+        return type(self)(abs(self._ndarray))
+
+    def _cmp_method(self, other, op):
+        if isinstance(other, NumpyExtensionArray):
+            other = other._ndarray
+
+        other = ops.maybe_prepare_scalar_for_op(other, (len(self),))
+        pd_op = ops.get_array_op(op)
+        other = ensure_wrapped_if_datetimelike(other)
+        result = pd_op(self._ndarray, other)
+
+        if op is divmod or op is ops.rdivmod:
+            a, b = result
+            if isinstance(a, np.ndarray):
+                # for e.g. op vs TimedeltaArray, we may already
+                #  have an ExtensionArray, in which case we do not wrap
+                return self._wrap_ndarray_result(a), self._wrap_ndarray_result(b)
+            return a, b
+
+        if isinstance(result, np.ndarray):
+            # for e.g. multiplication vs TimedeltaArray, we may already
+            #  have an ExtensionArray, in which case we do not wrap
+            return self._wrap_ndarray_result(result)
+        return result
+
+    _arith_method = _cmp_method
+
+    def _wrap_ndarray_result(self, result: np.ndarray):
+        # If we have timedelta64[ns] result, return a TimedeltaArray instead
+        #  of a NumpyExtensionArray
+        if result.dtype.kind == "m" and is_supported_dtype(result.dtype):
+            from pandas.core.arrays import TimedeltaArray
+
+            return TimedeltaArray._simple_new(result, dtype=result.dtype)
+        return type(self)(result)
+
+    def _formatter(self, boxed: bool = False) -> Callable[[Any], str | None]:
+        # NEP 51: https://github.com/numpy/numpy/pull/22449
+        if self.dtype.kind in "SU":
+            return "'{}'".format
+        elif self.dtype == "object":
+            return repr
+        else:
+            return str
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/period.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/period.py
new file mode 100644
index 0000000000000000000000000000000000000000..2947ba7b8c72ac09497f796aaaec8edfb133a948
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/period.py
@@ -0,0 +1,1331 @@
+from __future__ import annotations
+
+from datetime import timedelta
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    TypeVar,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    algos as libalgos,
+    lib,
+)
+from pandas._libs.arrays import NDArrayBacked
+from pandas._libs.tslibs import (
+    BaseOffset,
+    NaT,
+    NaTType,
+    Timedelta,
+    add_overflowsafe,
+    astype_overflowsafe,
+    dt64arr_to_periodarr as c_dt64arr_to_periodarr,
+    get_unit_from_dtype,
+    iNaT,
+    parsing,
+    period as libperiod,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import (
+    FreqGroup,
+    PeriodDtypeBase,
+    freq_to_period_freqstr,
+)
+from pandas._libs.tslibs.fields import isleapyear_arr
+from pandas._libs.tslibs.offsets import (
+    Tick,
+    delta_to_tick,
+)
+from pandas._libs.tslibs.period import (
+    DIFFERENT_FREQ,
+    IncompatibleFrequency,
+    Period,
+    get_period_field_arr,
+    period_asfreq_arr,
+)
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    ensure_object,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCPeriodIndex,
+    ABCSeries,
+    ABCTimedeltaArray,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.arrays import datetimelike as dtl
+import pandas.core.common as com
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        AnyArrayLike,
+        Dtype,
+        FillnaOptions,
+        NpDtype,
+        NumpySorter,
+        NumpyValueArrayLike,
+        Self,
+        npt,
+    )
+
+    from pandas.core.arrays import (
+        DatetimeArray,
+        TimedeltaArray,
+    )
+    from pandas.core.arrays.base import ExtensionArray
+
+
+BaseOffsetT = TypeVar("BaseOffsetT", bound=BaseOffset)
+
+
+_shared_doc_kwargs = {
+    "klass": "PeriodArray",
+}
+
+
+def _field_accessor(name: str, docstring: str | None = None):
+    def f(self):
+        base = self.dtype._dtype_code
+        result = get_period_field_arr(name, self.asi8, base)
+        return result
+
+    f.__name__ = name
+    f.__doc__ = docstring
+    return property(f)
+
+
+# error: Definition of "_concat_same_type" in base class "NDArrayBacked" is
+# incompatible with definition in base class "ExtensionArray"
+class PeriodArray(dtl.DatelikeOps, libperiod.PeriodMixin):  # type: ignore[misc]
+    """
+    Pandas ExtensionArray for storing Period data.
+
+    Users should use :func:`~pandas.array` to create new instances.
+
+    Parameters
+    ----------
+    values : Union[PeriodArray, Series[period], ndarray[int], PeriodIndex]
+        The data to store. These should be arrays that can be directly
+        converted to ordinals without inference or copy (PeriodArray,
+        ndarray[int64]), or a box around such an array (Series[period],
+        PeriodIndex).
+    dtype : PeriodDtype, optional
+        A PeriodDtype instance from which to extract a `freq`. If both
+        `freq` and `dtype` are specified, then the frequencies must match.
+    freq : str or DateOffset
+        The `freq` to use for the array. Mostly applicable when `values`
+        is an ndarray of integers, when `freq` is required. When `values`
+        is a PeriodArray (or box around), it's checked that ``values.freq``
+        matches `freq`.
+    copy : bool, default False
+        Whether to copy the ordinals before storing.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    See Also
+    --------
+    Period: Represents a period of time.
+    PeriodIndex : Immutable Index for period data.
+    period_range: Create a fixed-frequency PeriodArray.
+    array: Construct a pandas array.
+
+    Notes
+    -----
+    There are two components to a PeriodArray
+
+    - ordinals : integer ndarray
+    - freq : pd.tseries.offsets.Offset
+
+    The values are physically stored as a 1-D ndarray of integers. These are
+    called "ordinals" and represent some kind of offset from a base.
+
+    The `freq` indicates the span covered by each element of the array.
+    All elements in the PeriodArray have the same `freq`.
+
+    Examples
+    --------
+    >>> pd.arrays.PeriodArray(pd.PeriodIndex(['2023-01-01',
+    ...                                       '2023-01-02'], freq='D'))
+    
+    ['2023-01-01', '2023-01-02']
+    Length: 2, dtype: period[D]
+    """
+
+    # array priority higher than numpy scalars
+    __array_priority__ = 1000
+    _typ = "periodarray"  # ABCPeriodArray
+    _internal_fill_value = np.int64(iNaT)
+    _recognized_scalars = (Period,)
+    _is_recognized_dtype = lambda x: isinstance(
+        x, PeriodDtype
+    )  # check_compatible_with checks freq match
+    _infer_matches = ("period",)
+
+    @property
+    def _scalar_type(self) -> type[Period]:
+        return Period
+
+    # Names others delegate to us
+    _other_ops: list[str] = []
+    _bool_ops: list[str] = ["is_leap_year"]
+    _object_ops: list[str] = ["start_time", "end_time", "freq"]
+    _field_ops: list[str] = [
+        "year",
+        "month",
+        "day",
+        "hour",
+        "minute",
+        "second",
+        "weekofyear",
+        "weekday",
+        "week",
+        "dayofweek",
+        "day_of_week",
+        "dayofyear",
+        "day_of_year",
+        "quarter",
+        "qyear",
+        "days_in_month",
+        "daysinmonth",
+    ]
+    _datetimelike_ops: list[str] = _field_ops + _object_ops + _bool_ops
+    _datetimelike_methods: list[str] = ["strftime", "to_timestamp", "asfreq"]
+
+    _dtype: PeriodDtype
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __init__(
+        self, values, dtype: Dtype | None = None, freq=None, copy: bool = False
+    ) -> None:
+        if freq is not None:
+            # GH#52462
+            warnings.warn(
+                "The 'freq' keyword in the PeriodArray constructor is deprecated "
+                "and will be removed in a future version. Pass 'dtype' instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            freq = validate_dtype_freq(dtype, freq)
+            dtype = PeriodDtype(freq)
+
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+            if not isinstance(dtype, PeriodDtype):
+                raise ValueError(f"Invalid dtype {dtype} for PeriodArray")
+
+        if isinstance(values, ABCSeries):
+            values = values._values
+            if not isinstance(values, type(self)):
+                raise TypeError("Incorrect dtype")
+
+        elif isinstance(values, ABCPeriodIndex):
+            values = values._values
+
+        if isinstance(values, type(self)):
+            if dtype is not None and dtype != values.dtype:
+                raise raise_on_incompatible(values, dtype.freq)
+            values, dtype = values._ndarray, values.dtype
+
+        if not copy:
+            values = np.asarray(values, dtype="int64")
+        else:
+            values = np.array(values, dtype="int64", copy=copy)
+        if dtype is None:
+            raise ValueError("dtype is not specified and cannot be inferred")
+        dtype = cast(PeriodDtype, dtype)
+        NDArrayBacked.__init__(self, values, dtype)
+
+    # error: Signature of "_simple_new" incompatible with supertype "NDArrayBacked"
+    @classmethod
+    def _simple_new(  # type: ignore[override]
+        cls,
+        values: npt.NDArray[np.int64],
+        dtype: PeriodDtype,
+    ) -> Self:
+        # alias for PeriodArray.__init__
+        assertion_msg = "Should be numpy array of type i8"
+        assert isinstance(values, np.ndarray) and values.dtype == "i8", assertion_msg
+        return cls(values, dtype=dtype)
+
+    @classmethod
+    def _from_sequence(
+        cls,
+        scalars,
+        *,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+    ) -> Self:
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+        if dtype and isinstance(dtype, PeriodDtype):
+            freq = dtype.freq
+        else:
+            freq = None
+
+        if isinstance(scalars, cls):
+            validate_dtype_freq(scalars.dtype, freq)
+            if copy:
+                scalars = scalars.copy()
+            return scalars
+
+        periods = np.asarray(scalars, dtype=object)
+
+        freq = freq or libperiod.extract_freq(periods)
+        ordinals = libperiod.extract_ordinals(periods, freq)
+        dtype = PeriodDtype(freq)
+        return cls(ordinals, dtype=dtype)
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, *, dtype: Dtype | None = None, copy: bool = False
+    ) -> Self:
+        return cls._from_sequence(strings, dtype=dtype, copy=copy)
+
+    @classmethod
+    def _from_datetime64(cls, data, freq, tz=None) -> Self:
+        """
+        Construct a PeriodArray from a datetime64 array
+
+        Parameters
+        ----------
+        data : ndarray[datetime64[ns], datetime64[ns, tz]]
+        freq : str or Tick
+        tz : tzinfo, optional
+
+        Returns
+        -------
+        PeriodArray[freq]
+        """
+        if isinstance(freq, BaseOffset):
+            freq = freq_to_period_freqstr(freq.n, freq.name)
+        data, freq = dt64arr_to_periodarr(data, freq, tz)
+        dtype = PeriodDtype(freq)
+        return cls(data, dtype=dtype)
+
+    @classmethod
+    def _generate_range(cls, start, end, periods, freq):
+        periods = dtl.validate_periods(periods)
+
+        if freq is not None:
+            freq = Period._maybe_convert_freq(freq)
+
+        if start is not None or end is not None:
+            subarr, freq = _get_ordinal_range(start, end, periods, freq)
+        else:
+            raise ValueError("Not enough parameters to construct Period range")
+
+        return subarr, freq
+
+    @classmethod
+    def _from_fields(cls, *, fields: dict, freq) -> Self:
+        subarr, freq = _range_from_fields(freq=freq, **fields)
+        dtype = PeriodDtype(freq)
+        return cls._simple_new(subarr, dtype=dtype)
+
+    # -----------------------------------------------------------------
+    # DatetimeLike Interface
+
+    # error: Argument 1 of "_unbox_scalar" is incompatible with supertype
+    # "DatetimeLikeArrayMixin"; supertype defines the argument type as
+    # "Union[Union[Period, Any, Timedelta], NaTType]"
+    def _unbox_scalar(  # type: ignore[override]
+        self,
+        value: Period | NaTType,
+    ) -> np.int64:
+        if value is NaT:
+            # error: Item "Period" of "Union[Period, NaTType]" has no attribute "value"
+            return np.int64(value._value)  # type: ignore[union-attr]
+        elif isinstance(value, self._scalar_type):
+            self._check_compatible_with(value)
+            return np.int64(value.ordinal)
+        else:
+            raise ValueError(f"'value' should be a Period. Got '{value}' instead.")
+
+    def _scalar_from_string(self, value: str) -> Period:
+        return Period(value, freq=self.freq)
+
+    # error: Argument 1 of "_check_compatible_with" is incompatible with
+    # supertype "DatetimeLikeArrayMixin"; supertype defines the argument type
+    # as "Period | Timestamp | Timedelta | NaTType"
+    def _check_compatible_with(self, other: Period | NaTType | PeriodArray) -> None:  # type: ignore[override]
+        if other is NaT:
+            return
+        # error: Item "NaTType" of "Period | NaTType | PeriodArray" has no
+        # attribute "freq"
+        self._require_matching_freq(other.freq)  # type: ignore[union-attr]
+
+    # --------------------------------------------------------------------
+    # Data / Attributes
+
+    @cache_readonly
+    def dtype(self) -> PeriodDtype:
+        return self._dtype
+
+    # error: Cannot override writeable attribute with read-only property
+    @property  # type: ignore[override]
+    def freq(self) -> BaseOffset:
+        """
+        Return the frequency object for this PeriodArray.
+        """
+        return self.dtype.freq
+
+    @property
+    def freqstr(self) -> str:
+        return freq_to_period_freqstr(self.freq.n, self.freq.name)
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        if dtype == "i8":
+            # For NumPy 1.x compatibility we cannot use copy=None.  And
+            # `copy=False` has the meaning of `copy=None` here:
+            if not copy:
+                return np.asarray(self.asi8, dtype=dtype)
+            else:
+                return np.array(self.asi8, dtype=dtype)
+
+        if copy is False:
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if dtype == bool:
+            return ~self._isnan
+
+        # This will raise TypeError for non-object dtypes
+        return np.array(list(self), dtype=object)
+
+    def __arrow_array__(self, type=None):
+        """
+        Convert myself into a pyarrow Array.
+        """
+        import pyarrow
+
+        from pandas.core.arrays.arrow.extension_types import ArrowPeriodType
+
+        if type is not None:
+            if pyarrow.types.is_integer(type):
+                return pyarrow.array(self._ndarray, mask=self.isna(), type=type)
+            elif isinstance(type, ArrowPeriodType):
+                # ensure we have the same freq
+                if self.freqstr != type.freq:
+                    raise TypeError(
+                        "Not supported to convert PeriodArray to array with different "
+                        f"'freq' ({self.freqstr} vs {type.freq})"
+                    )
+            else:
+                raise TypeError(
+                    f"Not supported to convert PeriodArray to '{type}' type"
+                )
+
+        period_type = ArrowPeriodType(self.freqstr)
+        storage_array = pyarrow.array(self._ndarray, mask=self.isna(), type="int64")
+        return pyarrow.ExtensionArray.from_storage(period_type, storage_array)
+
+    # --------------------------------------------------------------------
+    # Vectorized analogues of Period properties
+
+    year = _field_accessor(
+        "year",
+        """
+        The year of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
+        >>> idx.year
+        Index([2023, 2024, 2025], dtype='int64')
+        """,
+    )
+    month = _field_accessor(
+        "month",
+        """
+        The month as January=1, December=12.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
+        >>> idx.month
+        Index([1, 2, 3], dtype='int64')
+        """,
+    )
+    day = _field_accessor(
+        "day",
+        """
+        The days of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(['2020-01-31', '2020-02-28'], freq='D')
+        >>> idx.day
+        Index([31, 28], dtype='int64')
+        """,
+    )
+    hour = _field_accessor(
+        "hour",
+        """
+        The hour of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01-01 10:00", "2023-01-01 11:00"], freq='h')
+        >>> idx.hour
+        Index([10, 11], dtype='int64')
+        """,
+    )
+    minute = _field_accessor(
+        "minute",
+        """
+        The minute of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01-01 10:30:00",
+        ...                       "2023-01-01 11:50:00"], freq='min')
+        >>> idx.minute
+        Index([30, 50], dtype='int64')
+        """,
+    )
+    second = _field_accessor(
+        "second",
+        """
+        The second of the period.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01-01 10:00:30",
+        ...                       "2023-01-01 10:00:31"], freq='s')
+        >>> idx.second
+        Index([30, 31], dtype='int64')
+        """,
+    )
+    weekofyear = _field_accessor(
+        "week",
+        """
+        The week ordinal of the year.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
+        >>> idx.week  # It can be written `weekofyear`
+        Index([5, 9, 13], dtype='int64')
+        """,
+    )
+    week = weekofyear
+    day_of_week = _field_accessor(
+        "day_of_week",
+        """
+        The day of the week with Monday=0, Sunday=6.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01-01", "2023-01-02", "2023-01-03"], freq="D")
+        >>> idx.weekday
+        Index([6, 0, 1], dtype='int64')
+        """,
+    )
+    dayofweek = day_of_week
+    weekday = dayofweek
+    dayofyear = day_of_year = _field_accessor(
+        "day_of_year",
+        """
+        The ordinal day of the year.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01-10", "2023-02-01", "2023-03-01"], freq="D")
+        >>> idx.dayofyear
+        Index([10, 32, 60], dtype='int64')
+
+        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
+        >>> idx
+        PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
+        >>> idx.dayofyear
+        Index([365, 366, 365], dtype='int64')
+        """,
+    )
+    quarter = _field_accessor(
+        "quarter",
+        """
+        The quarter of the date.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
+        >>> idx.quarter
+        Index([1, 1, 1], dtype='int64')
+        """,
+    )
+    qyear = _field_accessor("qyear")
+    days_in_month = _field_accessor(
+        "days_in_month",
+        """
+        The number of days in the month.
+
+        Examples
+        --------
+        For Series:
+
+        >>> period = pd.period_range('2020-1-1 00:00', '2020-3-1 00:00', freq='M')
+        >>> s = pd.Series(period)
+        >>> s
+        0   2020-01
+        1   2020-02
+        2   2020-03
+        dtype: period[M]
+        >>> s.dt.days_in_month
+        0    31
+        1    29
+        2    31
+        dtype: int64
+
+        For PeriodIndex:
+
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
+        >>> idx.days_in_month   # It can be also entered as `daysinmonth`
+        Index([31, 28, 31], dtype='int64')
+        """,
+    )
+    daysinmonth = days_in_month
+
+    @property
+    def is_leap_year(self) -> npt.NDArray[np.bool_]:
+        """
+        Logical indicating if the date belongs to a leap year.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023", "2024", "2025"], freq="Y")
+        >>> idx.is_leap_year
+        array([False,  True, False])
+        """
+        return isleapyear_arr(np.asarray(self.year))
+
+    def to_timestamp(self, freq=None, how: str = "start") -> DatetimeArray:
+        """
+        Cast to DatetimeArray/Index.
+
+        Parameters
+        ----------
+        freq : str or DateOffset, optional
+            Target frequency. The default is 'D' for week or longer,
+            's' otherwise.
+        how : {'s', 'e', 'start', 'end'}
+            Whether to use the start or end of the time period being converted.
+
+        Returns
+        -------
+        DatetimeArray/Index
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(["2023-01", "2023-02", "2023-03"], freq="M")
+        >>> idx.to_timestamp()
+        DatetimeIndex(['2023-01-01', '2023-02-01', '2023-03-01'],
+        dtype='datetime64[ns]', freq='MS')
+        """
+        from pandas.core.arrays import DatetimeArray
+
+        how = libperiod.validate_end_alias(how)
+
+        end = how == "E"
+        if end:
+            if freq == "B" or self.freq == "B":
+                # roll forward to ensure we land on B date
+                adjust = Timedelta(1, "D") - Timedelta(1, "ns")
+                return self.to_timestamp(how="start") + adjust
+            else:
+                adjust = Timedelta(1, "ns")
+                return (self + self.freq).to_timestamp(how="start") - adjust
+
+        if freq is None:
+            freq_code = self._dtype._get_to_timestamp_base()
+            dtype = PeriodDtypeBase(freq_code, 1)
+            freq = dtype._freqstr
+            base = freq_code
+        else:
+            freq = Period._maybe_convert_freq(freq)
+            base = freq._period_dtype_code
+
+        new_parr = self.asfreq(freq, how=how)
+
+        new_data = libperiod.periodarr_to_dt64arr(new_parr.asi8, base)
+        dta = DatetimeArray._from_sequence(new_data)
+
+        if self.freq.name == "B":
+            # See if we can retain BDay instead of Day in cases where
+            #  len(self) is too small for infer_freq to distinguish between them
+            diffs = libalgos.unique_deltas(self.asi8)
+            if len(diffs) == 1:
+                diff = diffs[0]
+                if diff == self.dtype._n:
+                    dta._freq = self.freq
+                elif diff == 1:
+                    dta._freq = self.freq.base
+                # TODO: other cases?
+            return dta
+        else:
+            return dta._with_freq("infer")
+
+    # --------------------------------------------------------------------
+
+    def _box_func(self, x) -> Period | NaTType:
+        return Period._from_ordinal(ordinal=x, freq=self.freq)
+
+    @doc(**_shared_doc_kwargs, other="PeriodIndex", other_name="PeriodIndex")
+    def asfreq(self, freq=None, how: str = "E") -> Self:
+        """
+        Convert the {klass} to the specified frequency `freq`.
+
+        Equivalent to applying :meth:`pandas.Period.asfreq` with the given arguments
+        to each :class:`~pandas.Period` in this {klass}.
+
+        Parameters
+        ----------
+        freq : str
+            A frequency.
+        how : str {{'E', 'S'}}, default 'E'
+            Whether the elements should be aligned to the end
+            or start within pa period.
+
+            * 'E', 'END', or 'FINISH' for end,
+            * 'S', 'START', or 'BEGIN' for start.
+
+            January 31st ('END') vs. January 1st ('START') for example.
+
+        Returns
+        -------
+        {klass}
+            The transformed {klass} with the new frequency.
+
+        See Also
+        --------
+        {other}.asfreq: Convert each Period in a {other_name} to the given frequency.
+        Period.asfreq : Convert a :class:`~pandas.Period` object to the given frequency.
+
+        Examples
+        --------
+        >>> pidx = pd.period_range('2010-01-01', '2015-01-01', freq='Y')
+        >>> pidx
+        PeriodIndex(['2010', '2011', '2012', '2013', '2014', '2015'],
+        dtype='period[Y-DEC]')
+
+        >>> pidx.asfreq('M')
+        PeriodIndex(['2010-12', '2011-12', '2012-12', '2013-12', '2014-12',
+        '2015-12'], dtype='period[M]')
+
+        >>> pidx.asfreq('M', how='S')
+        PeriodIndex(['2010-01', '2011-01', '2012-01', '2013-01', '2014-01',
+        '2015-01'], dtype='period[M]')
+        """
+        how = libperiod.validate_end_alias(how)
+        if isinstance(freq, BaseOffset) and hasattr(freq, "_period_dtype_code"):
+            freq = PeriodDtype(freq)._freqstr
+        freq = Period._maybe_convert_freq(freq)
+
+        base1 = self._dtype._dtype_code
+        base2 = freq._period_dtype_code
+
+        asi8 = self.asi8
+        # self.freq.n can't be negative or 0
+        end = how == "E"
+        if end:
+            ordinal = asi8 + self.dtype._n - 1
+        else:
+            ordinal = asi8
+
+        new_data = period_asfreq_arr(ordinal, base1, base2, end)
+
+        if self._hasna:
+            new_data[self._isnan] = iNaT
+
+        dtype = PeriodDtype(freq)
+        return type(self)(new_data, dtype=dtype)
+
+    # ------------------------------------------------------------------
+    # Rendering Methods
+
+    def _formatter(self, boxed: bool = False):
+        if boxed:
+            return str
+        return "'{}'".format
+
+    def _format_native_types(
+        self, *, na_rep: str | float = "NaT", date_format=None, **kwargs
+    ) -> npt.NDArray[np.object_]:
+        """
+        actually format my specific types
+        """
+        return libperiod.period_array_strftime(
+            self.asi8, self.dtype._dtype_code, na_rep, date_format
+        )
+
+    # ------------------------------------------------------------------
+
+    def astype(self, dtype, copy: bool = True):
+        # We handle Period[T] -> Period[U]
+        # Our parent handles everything else.
+        dtype = pandas_dtype(dtype)
+        if dtype == self._dtype:
+            if not copy:
+                return self
+            else:
+                return self.copy()
+        if isinstance(dtype, PeriodDtype):
+            return self.asfreq(dtype.freq)
+
+        if lib.is_np_dtype(dtype, "M") or isinstance(dtype, DatetimeTZDtype):
+            # GH#45038 match PeriodIndex behavior.
+            tz = getattr(dtype, "tz", None)
+            unit = dtl.dtype_to_unit(dtype)
+            return self.to_timestamp().tz_localize(tz).as_unit(unit)
+
+        return super().astype(dtype, copy=copy)
+
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        npvalue = self._validate_setitem_value(value).view("M8[ns]")
+
+        # Cast to M8 to get datetime-like NaT placement,
+        #  similar to dtl._period_dispatch
+        m8arr = self._ndarray.view("M8[ns]")
+        return m8arr.searchsorted(npvalue, side=side, sorter=sorter)
+
+    def _pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        # view as dt64 so we get treated as timelike in core.missing,
+        #  similar to dtl._period_dispatch
+        dta = self.view("M8[ns]")
+        result = dta._pad_or_backfill(
+            method=method, limit=limit, limit_area=limit_area, copy=copy
+        )
+        if copy:
+            return cast("Self", result.view(self.dtype))
+        else:
+            return self
+
+    def fillna(
+        self, value=None, method=None, limit: int | None = None, copy: bool = True
+    ) -> Self:
+        if method is not None:
+            # view as dt64 so we get treated as timelike in core.missing,
+            #  similar to dtl._period_dispatch
+            dta = self.view("M8[ns]")
+            result = dta.fillna(value=value, method=method, limit=limit, copy=copy)
+            # error: Incompatible return value type (got "Union[ExtensionArray,
+            # ndarray[Any, Any]]", expected "PeriodArray")
+            return result.view(self.dtype)  # type: ignore[return-value]
+        return super().fillna(value=value, method=method, limit=limit, copy=copy)
+
+    # ------------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _addsub_int_array_or_scalar(
+        self, other: np.ndarray | int, op: Callable[[Any, Any], Any]
+    ) -> Self:
+        """
+        Add or subtract array of integers.
+
+        Parameters
+        ----------
+        other : np.ndarray[int64] or int
+        op : {operator.add, operator.sub}
+
+        Returns
+        -------
+        result : PeriodArray
+        """
+        assert op in [operator.add, operator.sub]
+        if op is operator.sub:
+            other = -other
+        res_values = add_overflowsafe(self.asi8, np.asarray(other, dtype="i8"))
+        return type(self)(res_values, dtype=self.dtype)
+
+    def _add_offset(self, other: BaseOffset):
+        assert not isinstance(other, Tick)
+
+        self._require_matching_freq(other, base=True)
+        return self._addsub_int_array_or_scalar(other.n, operator.add)
+
+    # TODO: can we de-duplicate with Period._add_timedeltalike_scalar?
+    def _add_timedeltalike_scalar(self, other):
+        """
+        Parameters
+        ----------
+        other : timedelta, Tick, np.timedelta64
+
+        Returns
+        -------
+        PeriodArray
+        """
+        if not isinstance(self.freq, Tick):
+            # We cannot add timedelta-like to non-tick PeriodArray
+            raise raise_on_incompatible(self, other)
+
+        if isna(other):
+            # i.e. np.timedelta64("NaT")
+            return super()._add_timedeltalike_scalar(other)
+
+        td = np.asarray(Timedelta(other).asm8)
+        return self._add_timedelta_arraylike(td)
+
+    def _add_timedelta_arraylike(
+        self, other: TimedeltaArray | npt.NDArray[np.timedelta64]
+    ) -> Self:
+        """
+        Parameters
+        ----------
+        other : TimedeltaArray or ndarray[timedelta64]
+
+        Returns
+        -------
+        PeriodArray
+        """
+        if not self.dtype._is_tick_like():
+            # We cannot add timedelta-like to non-tick PeriodArray
+            raise TypeError(
+                f"Cannot add or subtract timedelta64[ns] dtype from {self.dtype}"
+            )
+
+        dtype = np.dtype(f"m8[{self.dtype._td64_unit}]")
+
+        # Similar to _check_timedeltalike_freq_compat, but we raise with a
+        #  more specific exception message if necessary.
+        try:
+            delta = astype_overflowsafe(
+                np.asarray(other), dtype=dtype, copy=False, round_ok=False
+            )
+        except ValueError as err:
+            # e.g. if we have minutes freq and try to add 30s
+            # "Cannot losslessly convert units"
+            raise IncompatibleFrequency(
+                "Cannot add/subtract timedelta-like from PeriodArray that is "
+                "not an integer multiple of the PeriodArray's freq."
+            ) from err
+
+        res_values = add_overflowsafe(self.asi8, np.asarray(delta.view("i8")))
+        return type(self)(res_values, dtype=self.dtype)
+
+    def _check_timedeltalike_freq_compat(self, other):
+        """
+        Arithmetic operations with timedelta-like scalars or array `other`
+        are only valid if `other` is an integer multiple of `self.freq`.
+        If the operation is valid, find that integer multiple.  Otherwise,
+        raise because the operation is invalid.
+
+        Parameters
+        ----------
+        other : timedelta, np.timedelta64, Tick,
+                ndarray[timedelta64], TimedeltaArray, TimedeltaIndex
+
+        Returns
+        -------
+        multiple : int or ndarray[int64]
+
+        Raises
+        ------
+        IncompatibleFrequency
+        """
+        assert self.dtype._is_tick_like()  # checked by calling function
+
+        dtype = np.dtype(f"m8[{self.dtype._td64_unit}]")
+
+        if isinstance(other, (timedelta, np.timedelta64, Tick)):
+            td = np.asarray(Timedelta(other).asm8)
+        else:
+            td = np.asarray(other)
+
+        try:
+            delta = astype_overflowsafe(td, dtype=dtype, copy=False, round_ok=False)
+        except ValueError as err:
+            raise raise_on_incompatible(self, other) from err
+
+        delta = delta.view("i8")
+        return lib.item_from_zerodim(delta)
+
+
+def raise_on_incompatible(left, right) -> IncompatibleFrequency:
+    """
+    Helper function to render a consistent error message when raising
+    IncompatibleFrequency.
+
+    Parameters
+    ----------
+    left : PeriodArray
+    right : None, DateOffset, Period, ndarray, or timedelta-like
+
+    Returns
+    -------
+    IncompatibleFrequency
+        Exception to be raised by the caller.
+    """
+    # GH#24283 error message format depends on whether right is scalar
+    if isinstance(right, (np.ndarray, ABCTimedeltaArray)) or right is None:
+        other_freq = None
+    elif isinstance(right, BaseOffset):
+        other_freq = freq_to_period_freqstr(right.n, right.name)
+    elif isinstance(right, (ABCPeriodIndex, PeriodArray, Period)):
+        other_freq = right.freqstr
+    else:
+        other_freq = delta_to_tick(Timedelta(right)).freqstr
+
+    own_freq = freq_to_period_freqstr(left.freq.n, left.freq.name)
+    msg = DIFFERENT_FREQ.format(
+        cls=type(left).__name__, own_freq=own_freq, other_freq=other_freq
+    )
+    return IncompatibleFrequency(msg)
+
+
+# -------------------------------------------------------------------
+# Constructor Helpers
+
+
+def period_array(
+    data: Sequence[Period | str | None] | AnyArrayLike,
+    freq: str | Tick | BaseOffset | None = None,
+    copy: bool = False,
+) -> PeriodArray:
+    """
+    Construct a new PeriodArray from a sequence of Period scalars.
+
+    Parameters
+    ----------
+    data : Sequence of Period objects
+        A sequence of Period objects. These are required to all have
+        the same ``freq.`` Missing values can be indicated by ``None``
+        or ``pandas.NaT``.
+    freq : str, Tick, or Offset
+        The frequency of every element of the array. This can be specified
+        to avoid inferring the `freq` from `data`.
+    copy : bool, default False
+        Whether to ensure a copy of the data is made.
+
+    Returns
+    -------
+    PeriodArray
+
+    See Also
+    --------
+    PeriodArray
+    pandas.PeriodIndex
+
+    Examples
+    --------
+    >>> period_array([pd.Period('2017', freq='Y'),
+    ...               pd.Period('2018', freq='Y')])
+    
+    ['2017', '2018']
+    Length: 2, dtype: period[Y-DEC]
+
+    >>> period_array([pd.Period('2017', freq='Y'),
+    ...               pd.Period('2018', freq='Y'),
+    ...               pd.NaT])
+    
+    ['2017', '2018', 'NaT']
+    Length: 3, dtype: period[Y-DEC]
+
+    Integers that look like years are handled
+
+    >>> period_array([2000, 2001, 2002], freq='D')
+    
+    ['2000-01-01', '2001-01-01', '2002-01-01']
+    Length: 3, dtype: period[D]
+
+    Datetime-like strings may also be passed
+
+    >>> period_array(['2000-Q1', '2000-Q2', '2000-Q3', '2000-Q4'], freq='Q')
+    
+    ['2000Q1', '2000Q2', '2000Q3', '2000Q4']
+    Length: 4, dtype: period[Q-DEC]
+    """
+    data_dtype = getattr(data, "dtype", None)
+
+    if lib.is_np_dtype(data_dtype, "M"):
+        return PeriodArray._from_datetime64(data, freq)
+    if isinstance(data_dtype, PeriodDtype):
+        out = PeriodArray(data)
+        if freq is not None:
+            if freq == data_dtype.freq:
+                return out
+            return out.asfreq(freq)
+        return out
+
+    # other iterable of some kind
+    if not isinstance(data, (np.ndarray, list, tuple, ABCSeries)):
+        data = list(data)
+
+    arrdata = np.asarray(data)
+
+    dtype: PeriodDtype | None
+    if freq:
+        dtype = PeriodDtype(freq)
+    else:
+        dtype = None
+
+    if arrdata.dtype.kind == "f" and len(arrdata) > 0:
+        raise TypeError("PeriodIndex does not allow floating point in construction")
+
+    if arrdata.dtype.kind in "iu":
+        arr = arrdata.astype(np.int64, copy=False)
+        # error: Argument 2 to "from_ordinals" has incompatible type "Union[str,
+        # Tick, None]"; expected "Union[timedelta, BaseOffset, str]"
+        ordinals = libperiod.from_ordinals(arr, freq)  # type: ignore[arg-type]
+        return PeriodArray(ordinals, dtype=dtype)
+
+    data = ensure_object(arrdata)
+    if freq is None:
+        freq = libperiod.extract_freq(data)
+    dtype = PeriodDtype(freq)
+    return PeriodArray._from_sequence(data, dtype=dtype)
+
+
+@overload
+def validate_dtype_freq(dtype, freq: BaseOffsetT) -> BaseOffsetT:
+    ...
+
+
+@overload
+def validate_dtype_freq(dtype, freq: timedelta | str | None) -> BaseOffset:
+    ...
+
+
+def validate_dtype_freq(
+    dtype, freq: BaseOffsetT | BaseOffset | timedelta | str | None
+) -> BaseOffsetT:
+    """
+    If both a dtype and a freq are available, ensure they match.  If only
+    dtype is available, extract the implied freq.
+
+    Parameters
+    ----------
+    dtype : dtype
+    freq : DateOffset or None
+
+    Returns
+    -------
+    freq : DateOffset
+
+    Raises
+    ------
+    ValueError : non-period dtype
+    IncompatibleFrequency : mismatch between dtype and freq
+    """
+    if freq is not None:
+        freq = to_offset(freq, is_period=True)
+
+    if dtype is not None:
+        dtype = pandas_dtype(dtype)
+        if not isinstance(dtype, PeriodDtype):
+            raise ValueError("dtype must be PeriodDtype")
+        if freq is None:
+            freq = dtype.freq
+        elif freq != dtype.freq:
+            raise IncompatibleFrequency("specified freq and dtype are different")
+    # error: Incompatible return value type (got "Union[BaseOffset, Any, None]",
+    # expected "BaseOffset")
+    return freq  # type: ignore[return-value]
+
+
+def dt64arr_to_periodarr(
+    data, freq, tz=None
+) -> tuple[npt.NDArray[np.int64], BaseOffset]:
+    """
+    Convert an datetime-like array to values Period ordinals.
+
+    Parameters
+    ----------
+    data : Union[Series[datetime64[ns]], DatetimeIndex, ndarray[datetime64ns]]
+    freq : Optional[Union[str, Tick]]
+        Must match the `freq` on the `data` if `data` is a DatetimeIndex
+        or Series.
+    tz : Optional[tzinfo]
+
+    Returns
+    -------
+    ordinals : ndarray[int64]
+    freq : Tick
+        The frequency extracted from the Series or DatetimeIndex if that's
+        used.
+
+    """
+    if not isinstance(data.dtype, np.dtype) or data.dtype.kind != "M":
+        raise ValueError(f"Wrong dtype: {data.dtype}")
+
+    if freq is None:
+        if isinstance(data, ABCIndex):
+            data, freq = data._values, data.freq
+        elif isinstance(data, ABCSeries):
+            data, freq = data._values, data.dt.freq
+
+    elif isinstance(data, (ABCIndex, ABCSeries)):
+        data = data._values
+
+    reso = get_unit_from_dtype(data.dtype)
+    freq = Period._maybe_convert_freq(freq)
+    base = freq._period_dtype_code
+    return c_dt64arr_to_periodarr(data.view("i8"), base, tz, reso=reso), freq
+
+
+def _get_ordinal_range(start, end, periods, freq, mult: int = 1):
+    if com.count_not_none(start, end, periods) != 2:
+        raise ValueError(
+            "Of the three parameters: start, end, and periods, "
+            "exactly two must be specified"
+        )
+
+    if freq is not None:
+        freq = to_offset(freq, is_period=True)
+        mult = freq.n
+
+    if start is not None:
+        start = Period(start, freq)
+    if end is not None:
+        end = Period(end, freq)
+
+    is_start_per = isinstance(start, Period)
+    is_end_per = isinstance(end, Period)
+
+    if is_start_per and is_end_per and start.freq != end.freq:
+        raise ValueError("start and end must have same freq")
+    if start is NaT or end is NaT:
+        raise ValueError("start and end must not be NaT")
+
+    if freq is None:
+        if is_start_per:
+            freq = start.freq
+        elif is_end_per:
+            freq = end.freq
+        else:  # pragma: no cover
+            raise ValueError("Could not infer freq from start/end")
+        mult = freq.n
+
+    if periods is not None:
+        periods = periods * mult
+        if start is None:
+            data = np.arange(
+                end.ordinal - periods + mult, end.ordinal + 1, mult, dtype=np.int64
+            )
+        else:
+            data = np.arange(
+                start.ordinal, start.ordinal + periods, mult, dtype=np.int64
+            )
+    else:
+        data = np.arange(start.ordinal, end.ordinal + 1, mult, dtype=np.int64)
+
+    return data, freq
+
+
+def _range_from_fields(
+    year=None,
+    month=None,
+    quarter=None,
+    day=None,
+    hour=None,
+    minute=None,
+    second=None,
+    freq=None,
+) -> tuple[np.ndarray, BaseOffset]:
+    if hour is None:
+        hour = 0
+    if minute is None:
+        minute = 0
+    if second is None:
+        second = 0
+    if day is None:
+        day = 1
+
+    ordinals = []
+
+    if quarter is not None:
+        if freq is None:
+            freq = to_offset("Q", is_period=True)
+            base = FreqGroup.FR_QTR.value
+        else:
+            freq = to_offset(freq, is_period=True)
+            base = libperiod.freq_to_dtype_code(freq)
+            if base != FreqGroup.FR_QTR.value:
+                raise AssertionError("base must equal FR_QTR")
+
+        freqstr = freq.freqstr
+        year, quarter = _make_field_arrays(year, quarter)
+        for y, q in zip(year, quarter):
+            calendar_year, calendar_month = parsing.quarter_to_myear(y, q, freqstr)
+            val = libperiod.period_ordinal(
+                calendar_year, calendar_month, 1, 1, 1, 1, 0, 0, base
+            )
+            ordinals.append(val)
+    else:
+        freq = to_offset(freq, is_period=True)
+        base = libperiod.freq_to_dtype_code(freq)
+        arrays = _make_field_arrays(year, month, day, hour, minute, second)
+        for y, mth, d, h, mn, s in zip(*arrays):
+            ordinals.append(libperiod.period_ordinal(y, mth, d, h, mn, s, 0, 0, base))
+
+    return np.array(ordinals, dtype=np.int64), freq
+
+
+def _make_field_arrays(*fields) -> list[np.ndarray]:
+    length = None
+    for x in fields:
+        if isinstance(x, (list, np.ndarray, ABCSeries)):
+            if length is not None and len(x) != length:
+                raise ValueError("Mismatched Period array lengths")
+            if length is None:
+                length = len(x)
+
+    # error: Argument 2 to "repeat" has incompatible type "Optional[int]"; expected
+    # "Union[Union[int, integer[Any]], Union[bool, bool_], ndarray, Sequence[Union[int,
+    # integer[Any]]], Sequence[Union[bool, bool_]], Sequence[Sequence[Any]]]"
+    return [
+        np.asarray(x)
+        if isinstance(x, (np.ndarray, list, ABCSeries))
+        else np.repeat(x, length)  # type: ignore[arg-type]
+        for x in fields
+    ]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..adf83963aca39e7d2ec2da55d21fc69aaca48977
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/__init__.py
@@ -0,0 +1,19 @@
+from pandas.core.arrays.sparse.accessor import (
+    SparseAccessor,
+    SparseFrameAccessor,
+)
+from pandas.core.arrays.sparse.array import (
+    BlockIndex,
+    IntIndex,
+    SparseArray,
+    make_sparse_index,
+)
+
+__all__ = [
+    "BlockIndex",
+    "IntIndex",
+    "make_sparse_index",
+    "SparseAccessor",
+    "SparseArray",
+    "SparseFrameAccessor",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/accessor.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/accessor.py
new file mode 100644
index 0000000000000000000000000000000000000000..67bb41786547501c0cd7187e5ca6be8393b85ced
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/accessor.py
@@ -0,0 +1,414 @@
+"""Sparse accessor"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+
+from pandas.core.dtypes.cast import find_common_type
+from pandas.core.dtypes.dtypes import SparseDtype
+
+from pandas.core.accessor import (
+    PandasDelegate,
+    delegate_names,
+)
+from pandas.core.arrays.sparse.array import SparseArray
+
+if TYPE_CHECKING:
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+class BaseAccessor:
+    _validation_msg = "Can only use the '.sparse' accessor with Sparse data."
+
+    def __init__(self, data=None) -> None:
+        self._parent = data
+        self._validate(data)
+
+    def _validate(self, data):
+        raise NotImplementedError
+
+
+@delegate_names(
+    SparseArray, ["npoints", "density", "fill_value", "sp_values"], typ="property"
+)
+class SparseAccessor(BaseAccessor, PandasDelegate):
+    """
+    Accessor for SparseSparse from other sparse matrix data types.
+
+    Examples
+    --------
+    >>> ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]")
+    >>> ser.sparse.density
+    0.6
+    >>> ser.sparse.sp_values
+    array([2, 2, 2])
+    """
+
+    def _validate(self, data):
+        if not isinstance(data.dtype, SparseDtype):
+            raise AttributeError(self._validation_msg)
+
+    def _delegate_property_get(self, name: str, *args, **kwargs):
+        return getattr(self._parent.array, name)
+
+    def _delegate_method(self, name: str, *args, **kwargs):
+        if name == "from_coo":
+            return self.from_coo(*args, **kwargs)
+        elif name == "to_coo":
+            return self.to_coo(*args, **kwargs)
+        else:
+            raise ValueError
+
+    @classmethod
+    def from_coo(cls, A, dense_index: bool = False) -> Series:
+        """
+        Create a Series with sparse values from a scipy.sparse.coo_matrix.
+
+        Parameters
+        ----------
+        A : scipy.sparse.coo_matrix
+        dense_index : bool, default False
+            If False (default), the index consists of only the
+            coords of the non-null entries of the original coo_matrix.
+            If True, the index consists of the full sorted
+            (row, col) coordinates of the coo_matrix.
+
+        Returns
+        -------
+        s : Series
+            A Series with sparse values.
+
+        Examples
+        --------
+        >>> from scipy import sparse
+
+        >>> A = sparse.coo_matrix(
+        ...     ([3.0, 1.0, 2.0], ([1, 0, 0], [0, 2, 3])), shape=(3, 4)
+        ... )
+        >>> A
+        
+
+        >>> A.todense()
+        matrix([[0., 0., 1., 2.],
+        [3., 0., 0., 0.],
+        [0., 0., 0., 0.]])
+
+        >>> ss = pd.Series.sparse.from_coo(A)
+        >>> ss
+        0  2    1.0
+           3    2.0
+        1  0    3.0
+        dtype: Sparse[float64, nan]
+        """
+        from pandas import Series
+        from pandas.core.arrays.sparse.scipy_sparse import coo_to_sparse_series
+
+        result = coo_to_sparse_series(A, dense_index=dense_index)
+        result = Series(result.array, index=result.index, copy=False)
+
+        return result
+
+    def to_coo(self, row_levels=(0,), column_levels=(1,), sort_labels: bool = False):
+        """
+        Create a scipy.sparse.coo_matrix from a Series with MultiIndex.
+
+        Use row_levels and column_levels to determine the row and column
+        coordinates respectively. row_levels and column_levels are the names
+        (labels) or numbers of the levels. {row_levels, column_levels} must be
+        a partition of the MultiIndex level names (or numbers).
+
+        Parameters
+        ----------
+        row_levels : tuple/list
+        column_levels : tuple/list
+        sort_labels : bool, default False
+            Sort the row and column labels before forming the sparse matrix.
+            When `row_levels` and/or `column_levels` refer to a single level,
+            set to `True` for a faster execution.
+
+        Returns
+        -------
+        y : scipy.sparse.coo_matrix
+        rows : list (row labels)
+        columns : list (column labels)
+
+        Examples
+        --------
+        >>> s = pd.Series([3.0, np.nan, 1.0, 3.0, np.nan, np.nan])
+        >>> s.index = pd.MultiIndex.from_tuples(
+        ...     [
+        ...         (1, 2, "a", 0),
+        ...         (1, 2, "a", 1),
+        ...         (1, 1, "b", 0),
+        ...         (1, 1, "b", 1),
+        ...         (2, 1, "b", 0),
+        ...         (2, 1, "b", 1)
+        ...     ],
+        ...     names=["A", "B", "C", "D"],
+        ... )
+        >>> s
+        A  B  C  D
+        1  2  a  0    3.0
+                 1    NaN
+           1  b  0    1.0
+                 1    3.0
+        2  1  b  0    NaN
+                 1    NaN
+        dtype: float64
+
+        >>> ss = s.astype("Sparse")
+        >>> ss
+        A  B  C  D
+        1  2  a  0    3.0
+                 1    NaN
+           1  b  0    1.0
+                 1    3.0
+        2  1  b  0    NaN
+                 1    NaN
+        dtype: Sparse[float64, nan]
+
+        >>> A, rows, columns = ss.sparse.to_coo(
+        ...     row_levels=["A", "B"], column_levels=["C", "D"], sort_labels=True
+        ... )
+        >>> A
+        
+        >>> A.todense()
+        matrix([[0., 0., 1., 3.],
+        [3., 0., 0., 0.],
+        [0., 0., 0., 0.]])
+
+        >>> rows
+        [(1, 1), (1, 2), (2, 1)]
+        >>> columns
+        [('a', 0), ('a', 1), ('b', 0), ('b', 1)]
+        """
+        from pandas.core.arrays.sparse.scipy_sparse import sparse_series_to_coo
+
+        A, rows, columns = sparse_series_to_coo(
+            self._parent, row_levels, column_levels, sort_labels=sort_labels
+        )
+        return A, rows, columns
+
+    def to_dense(self) -> Series:
+        """
+        Convert a Series from sparse values to dense.
+
+        Returns
+        -------
+        Series:
+            A Series with the same values, stored as a dense array.
+
+        Examples
+        --------
+        >>> series = pd.Series(pd.arrays.SparseArray([0, 1, 0]))
+        >>> series
+        0    0
+        1    1
+        2    0
+        dtype: Sparse[int64, 0]
+
+        >>> series.sparse.to_dense()
+        0    0
+        1    1
+        2    0
+        dtype: int64
+        """
+        from pandas import Series
+
+        return Series(
+            self._parent.array.to_dense(),
+            index=self._parent.index,
+            name=self._parent.name,
+            copy=False,
+        )
+
+
+class SparseFrameAccessor(BaseAccessor, PandasDelegate):
+    """
+    DataFrame accessor for sparse data.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"a": [1, 2, 0, 0],
+    ...                   "b": [3, 0, 0, 4]}, dtype="Sparse[int]")
+    >>> df.sparse.density
+    0.5
+    """
+
+    def _validate(self, data):
+        dtypes = data.dtypes
+        if not all(isinstance(t, SparseDtype) for t in dtypes):
+            raise AttributeError(self._validation_msg)
+
+    @classmethod
+    def from_spmatrix(cls, data, index=None, columns=None) -> DataFrame:
+        """
+        Create a new DataFrame from a scipy sparse matrix.
+
+        Parameters
+        ----------
+        data : scipy.sparse.spmatrix
+            Must be convertible to csc format.
+        index, columns : Index, optional
+            Row and column labels to use for the resulting DataFrame.
+            Defaults to a RangeIndex.
+
+        Returns
+        -------
+        DataFrame
+            Each column of the DataFrame is stored as a
+            :class:`arrays.SparseArray`.
+
+        Examples
+        --------
+        >>> import scipy.sparse
+        >>> mat = scipy.sparse.eye(3, dtype=float)
+        >>> pd.DataFrame.sparse.from_spmatrix(mat)
+             0    1    2
+        0  1.0    0    0
+        1    0  1.0    0
+        2    0    0  1.0
+        """
+        from pandas._libs.sparse import IntIndex
+
+        from pandas import DataFrame
+
+        data = data.tocsc()
+        index, columns = cls._prep_index(data, index, columns)
+        n_rows, n_columns = data.shape
+        # We need to make sure indices are sorted, as we create
+        # IntIndex with no input validation (i.e. check_integrity=False ).
+        # Indices may already be sorted in scipy in which case this adds
+        # a small overhead.
+        data.sort_indices()
+        indices = data.indices
+        indptr = data.indptr
+        array_data = data.data
+        dtype = SparseDtype(array_data.dtype, 0)
+        arrays = []
+        for i in range(n_columns):
+            sl = slice(indptr[i], indptr[i + 1])
+            idx = IntIndex(n_rows, indices[sl], check_integrity=False)
+            arr = SparseArray._simple_new(array_data[sl], idx, dtype)
+            arrays.append(arr)
+        return DataFrame._from_arrays(
+            arrays, columns=columns, index=index, verify_integrity=False
+        )
+
+    def to_dense(self) -> DataFrame:
+        """
+        Convert a DataFrame with sparse values to dense.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with the same values stored as dense arrays.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": pd.arrays.SparseArray([0, 1, 0])})
+        >>> df.sparse.to_dense()
+           A
+        0  0
+        1  1
+        2  0
+        """
+        from pandas import DataFrame
+
+        data = {k: v.array.to_dense() for k, v in self._parent.items()}
+        return DataFrame(data, index=self._parent.index, columns=self._parent.columns)
+
+    def to_coo(self):
+        """
+        Return the contents of the frame as a sparse SciPy COO matrix.
+
+        Returns
+        -------
+        scipy.sparse.spmatrix
+            If the caller is heterogeneous and contains booleans or objects,
+            the result will be of dtype=object. See Notes.
+
+        Notes
+        -----
+        The dtype will be the lowest-common-denominator type (implicit
+        upcasting); that is to say if the dtypes (even of numeric types)
+        are mixed, the one that accommodates all will be chosen.
+
+        e.g. If the dtypes are float16 and float32, dtype will be upcast to
+        float32. By numpy.find_common_type convention, mixing int64 and
+        and uint64 will result in a float64 dtype.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": pd.arrays.SparseArray([0, 1, 0, 1])})
+        >>> df.sparse.to_coo()
+        
+        """
+        import_optional_dependency("scipy")
+        from scipy.sparse import coo_matrix
+
+        dtype = find_common_type(self._parent.dtypes.to_list())
+        if isinstance(dtype, SparseDtype):
+            dtype = dtype.subtype
+
+        cols, rows, data = [], [], []
+        for col, (_, ser) in enumerate(self._parent.items()):
+            sp_arr = ser.array
+            if sp_arr.fill_value != 0:
+                raise ValueError("fill value must be 0 when converting to COO matrix")
+
+            row = sp_arr.sp_index.indices
+            cols.append(np.repeat(col, len(row)))
+            rows.append(row)
+            data.append(sp_arr.sp_values.astype(dtype, copy=False))
+
+        cols = np.concatenate(cols)
+        rows = np.concatenate(rows)
+        data = np.concatenate(data)
+        return coo_matrix((data, (rows, cols)), shape=self._parent.shape)
+
+    @property
+    def density(self) -> float:
+        """
+        Ratio of non-sparse points to total (dense) data points.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": pd.arrays.SparseArray([0, 1, 0, 1])})
+        >>> df.sparse.density
+        0.5
+        """
+        tmp = np.mean([column.array.density for _, column in self._parent.items()])
+        return tmp
+
+    @staticmethod
+    def _prep_index(data, index, columns):
+        from pandas.core.indexes.api import (
+            default_index,
+            ensure_index,
+        )
+
+        N, K = data.shape
+        if index is None:
+            index = default_index(N)
+        else:
+            index = ensure_index(index)
+        if columns is None:
+            columns = default_index(K)
+        else:
+            columns = ensure_index(columns)
+
+        if len(columns) != K:
+            raise ValueError(f"Column length mismatch: {len(columns)} vs. {K}")
+        if len(index) != N:
+            raise ValueError(f"Index length mismatch: {len(index)} vs. {N}")
+        return index, columns
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/array.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/array.py
new file mode 100644
index 0000000000000000000000000000000000000000..07ff592f491a82bebef7b158ec00aaee6c8df419
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/array.py
@@ -0,0 +1,1945 @@
+"""
+SparseArray data structure
+"""
+from __future__ import annotations
+
+from collections import abc
+import numbers
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+import pandas._libs.sparse as splib
+from pandas._libs.sparse import (
+    BlockIndex,
+    IntIndex,
+    SparseIndex,
+)
+from pandas._libs.tslibs import NaT
+from pandas.compat.numpy import function as nv
+from pandas.errors import PerformanceWarning
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import (
+    validate_bool_kwarg,
+    validate_insert_loc,
+)
+
+from pandas.core.dtypes.astype import astype_array
+from pandas.core.dtypes.cast import (
+    construct_1d_arraylike_from_scalar,
+    find_common_type,
+    maybe_box_datetimelike,
+)
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_integer,
+    is_list_like,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    SparseDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+    notna,
+)
+
+from pandas.core import arraylike
+import pandas.core.algorithms as algos
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays import ExtensionArray
+from pandas.core.base import PandasObject
+import pandas.core.common as com
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+    sanitize_array,
+)
+from pandas.core.indexers import (
+    check_array_indexer,
+    unpack_tuple_and_ellipses,
+)
+from pandas.core.nanops import check_below_min_count
+
+from pandas.io.formats import printing
+
+# See https://github.com/python/typing/issues/684
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from enum import Enum
+
+    class ellipsis(Enum):
+        Ellipsis = "..."
+
+    Ellipsis = ellipsis.Ellipsis
+
+    from scipy.sparse import spmatrix
+
+    from pandas._typing import (
+        FillnaOptions,
+        NumpySorter,
+    )
+
+    SparseIndexKind = Literal["integer", "block"]
+
+    from pandas._typing import (
+        ArrayLike,
+        AstypeArg,
+        Axis,
+        AxisInt,
+        Dtype,
+        NpDtype,
+        PositionalIndexer,
+        Scalar,
+        ScalarIndexer,
+        Self,
+        SequenceIndexer,
+        npt,
+    )
+
+    from pandas import Series
+
+else:
+    ellipsis = type(Ellipsis)
+
+
+# ----------------------------------------------------------------------------
+# Array
+
+_sparray_doc_kwargs = {"klass": "SparseArray"}
+
+
+def _get_fill(arr: SparseArray) -> np.ndarray:
+    """
+    Create a 0-dim ndarray containing the fill value
+
+    Parameters
+    ----------
+    arr : SparseArray
+
+    Returns
+    -------
+    fill_value : ndarray
+        0-dim ndarray with just the fill value.
+
+    Notes
+    -----
+    coerce fill_value to arr dtype if possible
+    int64 SparseArray can have NaN as fill_value if there is no missing
+    """
+    try:
+        return np.asarray(arr.fill_value, dtype=arr.dtype.subtype)
+    except ValueError:
+        return np.asarray(arr.fill_value)
+
+
+def _sparse_array_op(
+    left: SparseArray, right: SparseArray, op: Callable, name: str
+) -> SparseArray:
+    """
+    Perform a binary operation between two arrays.
+
+    Parameters
+    ----------
+    left : Union[SparseArray, ndarray]
+    right : Union[SparseArray, ndarray]
+    op : Callable
+        The binary operation to perform
+    name str
+        Name of the callable.
+
+    Returns
+    -------
+    SparseArray
+    """
+    if name.startswith("__"):
+        # For lookups in _libs.sparse we need non-dunder op name
+        name = name[2:-2]
+
+    # dtype used to find corresponding sparse method
+    ltype = left.dtype.subtype
+    rtype = right.dtype.subtype
+
+    if ltype != rtype:
+        subtype = find_common_type([ltype, rtype])
+        ltype = SparseDtype(subtype, left.fill_value)
+        rtype = SparseDtype(subtype, right.fill_value)
+
+        left = left.astype(ltype, copy=False)
+        right = right.astype(rtype, copy=False)
+        dtype = ltype.subtype
+    else:
+        dtype = ltype
+
+    # dtype the result must have
+    result_dtype = None
+
+    if left.sp_index.ngaps == 0 or right.sp_index.ngaps == 0:
+        with np.errstate(all="ignore"):
+            result = op(left.to_dense(), right.to_dense())
+            fill = op(_get_fill(left), _get_fill(right))
+
+        if left.sp_index.ngaps == 0:
+            index = left.sp_index
+        else:
+            index = right.sp_index
+    elif left.sp_index.equals(right.sp_index):
+        with np.errstate(all="ignore"):
+            result = op(left.sp_values, right.sp_values)
+            fill = op(_get_fill(left), _get_fill(right))
+        index = left.sp_index
+    else:
+        if name[0] == "r":
+            left, right = right, left
+            name = name[1:]
+
+        if name in ("and", "or", "xor") and dtype == "bool":
+            opname = f"sparse_{name}_uint8"
+            # to make template simple, cast here
+            left_sp_values = left.sp_values.view(np.uint8)
+            right_sp_values = right.sp_values.view(np.uint8)
+            result_dtype = bool
+        else:
+            opname = f"sparse_{name}_{dtype}"
+            left_sp_values = left.sp_values
+            right_sp_values = right.sp_values
+
+        if (
+            name in ["floordiv", "mod"]
+            and (right == 0).any()
+            and left.dtype.kind in "iu"
+        ):
+            # Match the non-Sparse Series behavior
+            opname = f"sparse_{name}_float64"
+            left_sp_values = left_sp_values.astype("float64")
+            right_sp_values = right_sp_values.astype("float64")
+
+        sparse_op = getattr(splib, opname)
+
+        with np.errstate(all="ignore"):
+            result, index, fill = sparse_op(
+                left_sp_values,
+                left.sp_index,
+                left.fill_value,
+                right_sp_values,
+                right.sp_index,
+                right.fill_value,
+            )
+
+    if name == "divmod":
+        # result is a 2-tuple
+        # error: Incompatible return value type (got "Tuple[SparseArray,
+        # SparseArray]", expected "SparseArray")
+        return (  # type: ignore[return-value]
+            _wrap_result(name, result[0], index, fill[0], dtype=result_dtype),
+            _wrap_result(name, result[1], index, fill[1], dtype=result_dtype),
+        )
+
+    if result_dtype is None:
+        result_dtype = result.dtype
+
+    return _wrap_result(name, result, index, fill, dtype=result_dtype)
+
+
+def _wrap_result(
+    name: str, data, sparse_index, fill_value, dtype: Dtype | None = None
+) -> SparseArray:
+    """
+    wrap op result to have correct dtype
+    """
+    if name.startswith("__"):
+        # e.g. __eq__ --> eq
+        name = name[2:-2]
+
+    if name in ("eq", "ne", "lt", "gt", "le", "ge"):
+        dtype = bool
+
+    fill_value = lib.item_from_zerodim(fill_value)
+
+    if is_bool_dtype(dtype):
+        # fill_value may be np.bool_
+        fill_value = bool(fill_value)
+    return SparseArray(
+        data, sparse_index=sparse_index, fill_value=fill_value, dtype=dtype
+    )
+
+
+class SparseArray(OpsMixin, PandasObject, ExtensionArray):
+    """
+    An ExtensionArray for storing sparse data.
+
+    Parameters
+    ----------
+    data : array-like or scalar
+        A dense array of values to store in the SparseArray. This may contain
+        `fill_value`.
+    sparse_index : SparseIndex, optional
+    fill_value : scalar, optional
+        Elements in data that are ``fill_value`` are not stored in the
+        SparseArray. For memory savings, this should be the most common value
+        in `data`. By default, `fill_value` depends on the dtype of `data`:
+
+        =========== ==========
+        data.dtype  na_value
+        =========== ==========
+        float       ``np.nan``
+        int         ``0``
+        bool        False
+        datetime64  ``pd.NaT``
+        timedelta64 ``pd.NaT``
+        =========== ==========
+
+        The fill value is potentially specified in three ways. In order of
+        precedence, these are
+
+        1. The `fill_value` argument
+        2. ``dtype.fill_value`` if `fill_value` is None and `dtype` is
+           a ``SparseDtype``
+        3. ``data.dtype.fill_value`` if `fill_value` is None and `dtype`
+           is not a ``SparseDtype`` and `data` is a ``SparseArray``.
+
+    kind : str
+        Can be 'integer' or 'block', default is 'integer'.
+        The type of storage for sparse locations.
+
+        * 'block': Stores a `block` and `block_length` for each
+          contiguous *span* of sparse values. This is best when
+          sparse data tends to be clumped together, with large
+          regions of ``fill-value`` values between sparse values.
+        * 'integer': uses an integer to store the location of
+          each sparse value.
+
+    dtype : np.dtype or SparseDtype, optional
+        The dtype to use for the SparseArray. For numpy dtypes, this
+        determines the dtype of ``self.sp_values``. For SparseDtype,
+        this determines ``self.sp_values`` and ``self.fill_value``.
+    copy : bool, default False
+        Whether to explicitly copy the incoming `data` array.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> from pandas.arrays import SparseArray
+    >>> arr = SparseArray([0, 0, 1, 2])
+    >>> arr
+    [0, 0, 1, 2]
+    Fill: 0
+    IntIndex
+    Indices: array([2, 3], dtype=int32)
+    """
+
+    _subtyp = "sparse_array"  # register ABCSparseArray
+    _hidden_attrs = PandasObject._hidden_attrs | frozenset([])
+    _sparse_index: SparseIndex
+    _sparse_values: np.ndarray
+    _dtype: SparseDtype
+
+    def __init__(
+        self,
+        data,
+        sparse_index=None,
+        fill_value=None,
+        kind: SparseIndexKind = "integer",
+        dtype: Dtype | None = None,
+        copy: bool = False,
+    ) -> None:
+        if fill_value is None and isinstance(dtype, SparseDtype):
+            fill_value = dtype.fill_value
+
+        if isinstance(data, type(self)):
+            # disable normal inference on dtype, sparse_index, & fill_value
+            if sparse_index is None:
+                sparse_index = data.sp_index
+            if fill_value is None:
+                fill_value = data.fill_value
+            if dtype is None:
+                dtype = data.dtype
+            # TODO: make kind=None, and use data.kind?
+            data = data.sp_values
+
+        # Handle use-provided dtype
+        if isinstance(dtype, str):
+            # Two options: dtype='int', regular numpy dtype
+            # or dtype='Sparse[int]', a sparse dtype
+            try:
+                dtype = SparseDtype.construct_from_string(dtype)
+            except TypeError:
+                dtype = pandas_dtype(dtype)
+
+        if isinstance(dtype, SparseDtype):
+            if fill_value is None:
+                fill_value = dtype.fill_value
+            dtype = dtype.subtype
+
+        if is_scalar(data):
+            warnings.warn(
+                f"Constructing {type(self).__name__} with scalar data is deprecated "
+                "and will raise in a future version. Pass a sequence instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            if sparse_index is None:
+                npoints = 1
+            else:
+                npoints = sparse_index.length
+
+            data = construct_1d_arraylike_from_scalar(data, npoints, dtype=None)
+            dtype = data.dtype
+
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        # TODO: disentangle the fill_value dtype inference from
+        # dtype inference
+        if data is None:
+            # TODO: What should the empty dtype be? Object or float?
+
+            # error: Argument "dtype" to "array" has incompatible type
+            # "Union[ExtensionDtype, dtype[Any], None]"; expected "Union[dtype[Any],
+            # None, type, _SupportsDType, str, Union[Tuple[Any, int], Tuple[Any,
+            # Union[int, Sequence[int]]], List[Any], _DTypeDict, Tuple[Any, Any]]]"
+            data = np.array([], dtype=dtype)  # type: ignore[arg-type]
+
+        try:
+            data = sanitize_array(data, index=None)
+        except ValueError:
+            # NumPy may raise a ValueError on data like [1, []]
+            # we retry with object dtype here.
+            if dtype is None:
+                dtype = np.dtype(object)
+                data = np.atleast_1d(np.asarray(data, dtype=dtype))
+            else:
+                raise
+
+        if copy:
+            # TODO: avoid double copy when dtype forces cast.
+            data = data.copy()
+
+        if fill_value is None:
+            fill_value_dtype = data.dtype if dtype is None else dtype
+            if fill_value_dtype is None:
+                fill_value = np.nan
+            else:
+                fill_value = na_value_for_dtype(fill_value_dtype)
+
+        if isinstance(data, type(self)) and sparse_index is None:
+            sparse_index = data._sparse_index
+            # error: Argument "dtype" to "asarray" has incompatible type
+            # "Union[ExtensionDtype, dtype[Any], None]"; expected "None"
+            sparse_values = np.asarray(
+                data.sp_values, dtype=dtype  # type: ignore[arg-type]
+            )
+        elif sparse_index is None:
+            data = extract_array(data, extract_numpy=True)
+            if not isinstance(data, np.ndarray):
+                # EA
+                if isinstance(data.dtype, DatetimeTZDtype):
+                    warnings.warn(
+                        f"Creating SparseArray from {data.dtype} data "
+                        "loses timezone information. Cast to object before "
+                        "sparse to retain timezone information.",
+                        UserWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    data = np.asarray(data, dtype="datetime64[ns]")
+                    if fill_value is NaT:
+                        fill_value = np.datetime64("NaT", "ns")
+                data = np.asarray(data)
+            sparse_values, sparse_index, fill_value = _make_sparse(
+                # error: Argument "dtype" to "_make_sparse" has incompatible type
+                # "Union[ExtensionDtype, dtype[Any], None]"; expected
+                # "Optional[dtype[Any]]"
+                data,
+                kind=kind,
+                fill_value=fill_value,
+                dtype=dtype,  # type: ignore[arg-type]
+            )
+        else:
+            # error: Argument "dtype" to "asarray" has incompatible type
+            # "Union[ExtensionDtype, dtype[Any], None]"; expected "None"
+            sparse_values = np.asarray(data, dtype=dtype)  # type: ignore[arg-type]
+            if len(sparse_values) != sparse_index.npoints:
+                raise AssertionError(
+                    f"Non array-like type {type(sparse_values)} must "
+                    "have the same length as the index"
+                )
+        self._sparse_index = sparse_index
+        self._sparse_values = sparse_values
+        self._dtype = SparseDtype(sparse_values.dtype, fill_value)
+
+    @classmethod
+    def _simple_new(
+        cls,
+        sparse_array: np.ndarray,
+        sparse_index: SparseIndex,
+        dtype: SparseDtype,
+    ) -> Self:
+        new = object.__new__(cls)
+        new._sparse_index = sparse_index
+        new._sparse_values = sparse_array
+        new._dtype = dtype
+        return new
+
+    @classmethod
+    def from_spmatrix(cls, data: spmatrix) -> Self:
+        """
+        Create a SparseArray from a scipy.sparse matrix.
+
+        Parameters
+        ----------
+        data : scipy.sparse.sp_matrix
+            This should be a SciPy sparse matrix where the size
+            of the second dimension is 1. In other words, a
+            sparse matrix with a single column.
+
+        Returns
+        -------
+        SparseArray
+
+        Examples
+        --------
+        >>> import scipy.sparse
+        >>> mat = scipy.sparse.coo_matrix((4, 1))
+        >>> pd.arrays.SparseArray.from_spmatrix(mat)
+        [0.0, 0.0, 0.0, 0.0]
+        Fill: 0.0
+        IntIndex
+        Indices: array([], dtype=int32)
+        """
+        length, ncol = data.shape
+
+        if ncol != 1:
+            raise ValueError(f"'data' must have a single column, not '{ncol}'")
+
+        # our sparse index classes require that the positions be strictly
+        # increasing. So we need to sort loc, and arr accordingly.
+        data = data.tocsc()
+        data.sort_indices()
+        arr = data.data
+        idx = data.indices
+
+        zero = np.array(0, dtype=arr.dtype).item()
+        dtype = SparseDtype(arr.dtype, zero)
+        index = IntIndex(length, idx)
+
+        return cls._simple_new(arr, index, dtype)
+
+    def __array__(
+        self, dtype: NpDtype | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        if self.sp_index.ngaps == 0:
+            # Compat for na dtype and int values.
+            if copy is True:
+                return np.array(self.sp_values)
+            else:
+                return self.sp_values
+
+        if copy is False:
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        fill_value = self.fill_value
+
+        if dtype is None:
+            # Can NumPy represent this type?
+            # If not, `np.result_type` will raise. We catch that
+            # and return object.
+            if self.sp_values.dtype.kind == "M":
+                # However, we *do* special-case the common case of
+                # a datetime64 with pandas NaT.
+                if fill_value is NaT:
+                    # Can't put pd.NaT in a datetime64[ns]
+                    fill_value = np.datetime64("NaT")
+            try:
+                dtype = np.result_type(self.sp_values.dtype, type(fill_value))
+            except TypeError:
+                dtype = object
+
+        out = np.full(self.shape, fill_value, dtype=dtype)
+        out[self.sp_index.indices] = self.sp_values
+        return out
+
+    def __setitem__(self, key, value) -> None:
+        # I suppose we could allow setting of non-fill_value elements.
+        # TODO(SparseArray.__setitem__): remove special cases in
+        # ExtensionBlock.where
+        msg = "SparseArray does not support item assignment via setitem"
+        raise TypeError(msg)
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy: bool = False):
+        return cls(scalars, dtype=dtype)
+
+    @classmethod
+    def _from_factorized(cls, values, original):
+        return cls(values, dtype=original.dtype)
+
+    # ------------------------------------------------------------------------
+    # Data
+    # ------------------------------------------------------------------------
+    @property
+    def sp_index(self) -> SparseIndex:
+        """
+        The SparseIndex containing the location of non- ``fill_value`` points.
+        """
+        return self._sparse_index
+
+    @property
+    def sp_values(self) -> np.ndarray:
+        """
+        An ndarray containing the non- ``fill_value`` values.
+
+        Examples
+        --------
+        >>> from pandas.arrays import SparseArray
+        >>> s = SparseArray([0, 0, 1, 0, 2], fill_value=0)
+        >>> s.sp_values
+        array([1, 2])
+        """
+        return self._sparse_values
+
+    @property
+    def dtype(self) -> SparseDtype:
+        return self._dtype
+
+    @property
+    def fill_value(self):
+        """
+        Elements in `data` that are `fill_value` are not stored.
+
+        For memory savings, this should be the most common value in the array.
+
+        Examples
+        --------
+        >>> ser = pd.Series([0, 0, 2, 2, 2], dtype="Sparse[int]")
+        >>> ser.sparse.fill_value
+        0
+        >>> spa_dtype = pd.SparseDtype(dtype=np.int32, fill_value=2)
+        >>> ser = pd.Series([0, 0, 2, 2, 2], dtype=spa_dtype)
+        >>> ser.sparse.fill_value
+        2
+        """
+        return self.dtype.fill_value
+
+    @fill_value.setter
+    def fill_value(self, value) -> None:
+        self._dtype = SparseDtype(self.dtype.subtype, value)
+
+    @property
+    def kind(self) -> SparseIndexKind:
+        """
+        The kind of sparse index for this array. One of {'integer', 'block'}.
+        """
+        if isinstance(self.sp_index, IntIndex):
+            return "integer"
+        else:
+            return "block"
+
+    @property
+    def _valid_sp_values(self) -> np.ndarray:
+        sp_vals = self.sp_values
+        mask = notna(sp_vals)
+        return sp_vals[mask]
+
+    def __len__(self) -> int:
+        return self.sp_index.length
+
+    @property
+    def _null_fill_value(self) -> bool:
+        return self._dtype._is_na_fill_value
+
+    def _fill_value_matches(self, fill_value) -> bool:
+        if self._null_fill_value:
+            return isna(fill_value)
+        else:
+            return self.fill_value == fill_value
+
+    @property
+    def nbytes(self) -> int:
+        return self.sp_values.nbytes + self.sp_index.nbytes
+
+    @property
+    def density(self) -> float:
+        """
+        The percent of non- ``fill_value`` points, as decimal.
+
+        Examples
+        --------
+        >>> from pandas.arrays import SparseArray
+        >>> s = SparseArray([0, 0, 1, 1, 1], fill_value=0)
+        >>> s.density
+        0.6
+        """
+        return self.sp_index.npoints / self.sp_index.length
+
+    @property
+    def npoints(self) -> int:
+        """
+        The number of non- ``fill_value`` points.
+
+        Examples
+        --------
+        >>> from pandas.arrays import SparseArray
+        >>> s = SparseArray([0, 0, 1, 1, 1], fill_value=0)
+        >>> s.npoints
+        3
+        """
+        return self.sp_index.npoints
+
+    # error: Return type "SparseArray" of "isna" incompatible with return type
+    # "ndarray[Any, Any] | ExtensionArraySupportsAnyAll" in supertype "ExtensionArray"
+    def isna(self) -> Self:  # type: ignore[override]
+        # If null fill value, we want SparseDtype[bool, true]
+        # to preserve the same memory usage.
+        dtype = SparseDtype(bool, self._null_fill_value)
+        if self._null_fill_value:
+            return type(self)._simple_new(isna(self.sp_values), self.sp_index, dtype)
+        mask = np.full(len(self), False, dtype=np.bool_)
+        mask[self.sp_index.indices] = isna(self.sp_values)
+        return type(self)(mask, fill_value=False, dtype=dtype)
+
+    def _pad_or_backfill(  # pylint: disable=useless-parent-delegation
+        self,
+        *,
+        method: FillnaOptions,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        copy: bool = True,
+    ) -> Self:
+        # TODO(3.0): We can remove this method once deprecation for fillna method
+        #  keyword is enforced.
+        return super()._pad_or_backfill(
+            method=method, limit=limit, limit_area=limit_area, copy=copy
+        )
+
+    def fillna(
+        self,
+        value=None,
+        method: FillnaOptions | None = None,
+        limit: int | None = None,
+        copy: bool = True,
+    ) -> Self:
+        """
+        Fill missing values with `value`.
+
+        Parameters
+        ----------
+        value : scalar, optional
+        method : str, optional
+
+            .. warning::
+
+               Using 'method' will result in high memory use,
+               as all `fill_value` methods will be converted to
+               an in-memory ndarray
+
+        limit : int, optional
+
+        copy: bool, default True
+            Ignored for SparseArray.
+
+        Returns
+        -------
+        SparseArray
+
+        Notes
+        -----
+        When `value` is specified, the result's ``fill_value`` depends on
+        ``self.fill_value``. The goal is to maintain low-memory use.
+
+        If ``self.fill_value`` is NA, the result dtype will be
+        ``SparseDtype(self.dtype, fill_value=value)``. This will preserve
+        amount of memory used before and after filling.
+
+        When ``self.fill_value`` is not NA, the result dtype will be
+        ``self.dtype``. Again, this preserves the amount of memory used.
+        """
+        if (method is None and value is None) or (
+            method is not None and value is not None
+        ):
+            raise ValueError("Must specify one of 'method' or 'value'.")
+
+        if method is not None:
+            return super().fillna(method=method, limit=limit)
+
+        else:
+            new_values = np.where(isna(self.sp_values), value, self.sp_values)
+
+            if self._null_fill_value:
+                # This is essentially just updating the dtype.
+                new_dtype = SparseDtype(self.dtype.subtype, fill_value=value)
+            else:
+                new_dtype = self.dtype
+
+        return self._simple_new(new_values, self._sparse_index, new_dtype)
+
+    def shift(self, periods: int = 1, fill_value=None) -> Self:
+        if not len(self) or periods == 0:
+            return self.copy()
+
+        if isna(fill_value):
+            fill_value = self.dtype.na_value
+
+        subtype = np.result_type(fill_value, self.dtype.subtype)
+
+        if subtype != self.dtype.subtype:
+            # just coerce up front
+            arr = self.astype(SparseDtype(subtype, self.fill_value))
+        else:
+            arr = self
+
+        empty = self._from_sequence(
+            [fill_value] * min(abs(periods), len(self)), dtype=arr.dtype
+        )
+
+        if periods > 0:
+            a = empty
+            b = arr[:-periods]
+        else:
+            a = arr[abs(periods) :]
+            b = empty
+        return arr._concat_same_type([a, b])
+
+    def _first_fill_value_loc(self):
+        """
+        Get the location of the first fill value.
+
+        Returns
+        -------
+        int
+        """
+        if len(self) == 0 or self.sp_index.npoints == len(self):
+            return -1
+
+        indices = self.sp_index.indices
+        if not len(indices) or indices[0] > 0:
+            return 0
+
+        # a number larger than 1 should be appended to
+        # the last in case of fill value only appears
+        # in the tail of array
+        diff = np.r_[np.diff(indices), 2]
+        return indices[(diff > 1).argmax()] + 1
+
+    @doc(ExtensionArray.duplicated)
+    def duplicated(
+        self, keep: Literal["first", "last", False] = "first"
+    ) -> npt.NDArray[np.bool_]:
+        values = np.asarray(self)
+        mask = np.asarray(self.isna())
+        return algos.duplicated(values, keep=keep, mask=mask)
+
+    def unique(self) -> Self:
+        uniques = algos.unique(self.sp_values)
+        if len(self.sp_values) != len(self):
+            fill_loc = self._first_fill_value_loc()
+            # Inorder to align the behavior of pd.unique or
+            # pd.Series.unique, we should keep the original
+            # order, here we use unique again to find the
+            # insertion place. Since the length of sp_values
+            # is not large, maybe minor performance hurt
+            # is worthwhile to the correctness.
+            insert_loc = len(algos.unique(self.sp_values[:fill_loc]))
+            uniques = np.insert(uniques, insert_loc, self.fill_value)
+        return type(self)._from_sequence(uniques, dtype=self.dtype)
+
+    def _values_for_factorize(self):
+        # Still override this for hash_pandas_object
+        return np.asarray(self), self.fill_value
+
+    def factorize(
+        self,
+        use_na_sentinel: bool = True,
+    ) -> tuple[np.ndarray, SparseArray]:
+        # Currently, ExtensionArray.factorize -> Tuple[ndarray, EA]
+        # The sparsity on this is backwards from what Sparse would want. Want
+        # ExtensionArray.factorize -> Tuple[EA, EA]
+        # Given that we have to return a dense array of codes, why bother
+        # implementing an efficient factorize?
+        codes, uniques = algos.factorize(
+            np.asarray(self), use_na_sentinel=use_na_sentinel
+        )
+        uniques_sp = SparseArray(uniques, dtype=self.dtype)
+        return codes, uniques_sp
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        """
+        Returns a Series containing counts of unique values.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include counts of NaN, even if NaN is in sp_values.
+
+        Returns
+        -------
+        counts : Series
+        """
+        from pandas import (
+            Index,
+            Series,
+        )
+
+        keys, counts, _ = algos.value_counts_arraylike(self.sp_values, dropna=dropna)
+        fcounts = self.sp_index.ngaps
+        if fcounts > 0 and (not self._null_fill_value or not dropna):
+            mask = isna(keys) if self._null_fill_value else keys == self.fill_value
+            if mask.any():
+                counts[mask] += fcounts
+            else:
+                # error: Argument 1 to "insert" has incompatible type "Union[
+                # ExtensionArray,ndarray[Any, Any]]"; expected "Union[
+                # _SupportsArray[dtype[Any]], Sequence[_SupportsArray[dtype
+                # [Any]]], Sequence[Sequence[_SupportsArray[dtype[Any]]]],
+                # Sequence[Sequence[Sequence[_SupportsArray[dtype[Any]]]]], Sequence
+                # [Sequence[Sequence[Sequence[_SupportsArray[dtype[Any]]]]]]]"
+                keys = np.insert(keys, 0, self.fill_value)  # type: ignore[arg-type]
+                counts = np.insert(counts, 0, fcounts)
+
+        if not isinstance(keys, ABCIndex):
+            index = Index(keys)
+        else:
+            index = keys
+        return Series(counts, index=index, copy=False)
+
+    # --------
+    # Indexing
+    # --------
+    @overload
+    def __getitem__(self, key: ScalarIndexer) -> Any:
+        ...
+
+    @overload
+    def __getitem__(
+        self,
+        key: SequenceIndexer | tuple[int | ellipsis, ...],
+    ) -> Self:
+        ...
+
+    def __getitem__(
+        self,
+        key: PositionalIndexer | tuple[int | ellipsis, ...],
+    ) -> Self | Any:
+        if isinstance(key, tuple):
+            key = unpack_tuple_and_ellipses(key)
+            if key is Ellipsis:
+                raise ValueError("Cannot slice with Ellipsis")
+
+        if is_integer(key):
+            return self._get_val_at(key)
+        elif isinstance(key, tuple):
+            # error: Invalid index type "Tuple[Union[int, ellipsis], ...]"
+            # for "ndarray[Any, Any]"; expected type
+            # "Union[SupportsIndex, _SupportsArray[dtype[Union[bool_,
+            # integer[Any]]]], _NestedSequence[_SupportsArray[dtype[
+            # Union[bool_, integer[Any]]]]], _NestedSequence[Union[
+            # bool, int]], Tuple[Union[SupportsIndex, _SupportsArray[
+            # dtype[Union[bool_, integer[Any]]]], _NestedSequence[
+            # _SupportsArray[dtype[Union[bool_, integer[Any]]]]],
+            # _NestedSequence[Union[bool, int]]], ...]]"
+            data_slice = self.to_dense()[key]  # type: ignore[index]
+        elif isinstance(key, slice):
+            # Avoid densifying when handling contiguous slices
+            if key.step is None or key.step == 1:
+                start = 0 if key.start is None else key.start
+                if start < 0:
+                    start += len(self)
+
+                end = len(self) if key.stop is None else key.stop
+                if end < 0:
+                    end += len(self)
+
+                indices = self.sp_index.indices
+                keep_inds = np.flatnonzero((indices >= start) & (indices < end))
+                sp_vals = self.sp_values[keep_inds]
+
+                sp_index = indices[keep_inds].copy()
+
+                # If we've sliced to not include the start of the array, all our indices
+                # should be shifted. NB: here we are careful to also not shift by a
+                # negative value for a case like [0, 1][-100:] where the start index
+                # should be treated like 0
+                if start > 0:
+                    sp_index -= start
+
+                # Length of our result should match applying this slice to a range
+                # of the length of our original array
+                new_len = len(range(len(self))[key])
+                new_sp_index = make_sparse_index(new_len, sp_index, self.kind)
+                return type(self)._simple_new(sp_vals, new_sp_index, self.dtype)
+            else:
+                indices = np.arange(len(self), dtype=np.int32)[key]
+                return self.take(indices)
+
+        elif not is_list_like(key):
+            # e.g. "foo" or 2.5
+            # exception message copied from numpy
+            raise IndexError(
+                r"only integers, slices (`:`), ellipsis (`...`), numpy.newaxis "
+                r"(`None`) and integer or boolean arrays are valid indices"
+            )
+
+        else:
+            if isinstance(key, SparseArray):
+                # NOTE: If we guarantee that SparseDType(bool)
+                # has only fill_value - true, false or nan
+                # (see GH PR 44955)
+                # we can apply mask very fast:
+                if is_bool_dtype(key):
+                    if isna(key.fill_value):
+                        return self.take(key.sp_index.indices[key.sp_values])
+                    if not key.fill_value:
+                        return self.take(key.sp_index.indices)
+                    n = len(self)
+                    mask = np.full(n, True, dtype=np.bool_)
+                    mask[key.sp_index.indices] = False
+                    return self.take(np.arange(n)[mask])
+                else:
+                    key = np.asarray(key)
+
+            key = check_array_indexer(self, key)
+
+            if com.is_bool_indexer(key):
+                # mypy doesn't know we have an array here
+                key = cast(np.ndarray, key)
+                return self.take(np.arange(len(key), dtype=np.int32)[key])
+            elif hasattr(key, "__len__"):
+                return self.take(key)
+            else:
+                raise ValueError(f"Cannot slice with '{key}'")
+
+        return type(self)(data_slice, kind=self.kind)
+
+    def _get_val_at(self, loc):
+        loc = validate_insert_loc(loc, len(self))
+
+        sp_loc = self.sp_index.lookup(loc)
+        if sp_loc == -1:
+            return self.fill_value
+        else:
+            val = self.sp_values[sp_loc]
+            val = maybe_box_datetimelike(val, self.sp_values.dtype)
+            return val
+
+    def take(self, indices, *, allow_fill: bool = False, fill_value=None) -> Self:
+        if is_scalar(indices):
+            raise ValueError(f"'indices' must be an array, not a scalar '{indices}'.")
+        indices = np.asarray(indices, dtype=np.int32)
+
+        dtype = None
+        if indices.size == 0:
+            result = np.array([], dtype="object")
+            dtype = self.dtype
+        elif allow_fill:
+            result = self._take_with_fill(indices, fill_value=fill_value)
+        else:
+            return self._take_without_fill(indices)
+
+        return type(self)(
+            result, fill_value=self.fill_value, kind=self.kind, dtype=dtype
+        )
+
+    def _take_with_fill(self, indices, fill_value=None) -> np.ndarray:
+        if fill_value is None:
+            fill_value = self.dtype.na_value
+
+        if indices.min() < -1:
+            raise ValueError(
+                "Invalid value in 'indices'. Must be between -1 "
+                "and the length of the array."
+            )
+
+        if indices.max() >= len(self):
+            raise IndexError("out of bounds value in 'indices'.")
+
+        if len(self) == 0:
+            # Empty... Allow taking only if all empty
+            if (indices == -1).all():
+                dtype = np.result_type(self.sp_values, type(fill_value))
+                taken = np.empty_like(indices, dtype=dtype)
+                taken.fill(fill_value)
+                return taken
+            else:
+                raise IndexError("cannot do a non-empty take from an empty axes.")
+
+        # sp_indexer may be -1 for two reasons
+        # 1.) we took for an index of -1 (new)
+        # 2.) we took a value that was self.fill_value (old)
+        sp_indexer = self.sp_index.lookup_array(indices)
+        new_fill_indices = indices == -1
+        old_fill_indices = (sp_indexer == -1) & ~new_fill_indices
+
+        if self.sp_index.npoints == 0 and old_fill_indices.all():
+            # We've looked up all valid points on an all-sparse array.
+            taken = np.full(
+                sp_indexer.shape, fill_value=self.fill_value, dtype=self.dtype.subtype
+            )
+
+        elif self.sp_index.npoints == 0:
+            # Use the old fill_value unless we took for an index of -1
+            _dtype = np.result_type(self.dtype.subtype, type(fill_value))
+            taken = np.full(sp_indexer.shape, fill_value=fill_value, dtype=_dtype)
+            taken[old_fill_indices] = self.fill_value
+        else:
+            taken = self.sp_values.take(sp_indexer)
+
+            # Fill in two steps.
+            # Old fill values
+            # New fill values
+            # potentially coercing to a new dtype at each stage.
+
+            m0 = sp_indexer[old_fill_indices] < 0
+            m1 = sp_indexer[new_fill_indices] < 0
+
+            result_type = taken.dtype
+
+            if m0.any():
+                result_type = np.result_type(result_type, type(self.fill_value))
+                taken = taken.astype(result_type)
+                taken[old_fill_indices] = self.fill_value
+
+            if m1.any():
+                result_type = np.result_type(result_type, type(fill_value))
+                taken = taken.astype(result_type)
+                taken[new_fill_indices] = fill_value
+
+        return taken
+
+    def _take_without_fill(self, indices) -> Self:
+        to_shift = indices < 0
+
+        n = len(self)
+
+        if (indices.max() >= n) or (indices.min() < -n):
+            if n == 0:
+                raise IndexError("cannot do a non-empty take from an empty axes.")
+            raise IndexError("out of bounds value in 'indices'.")
+
+        if to_shift.any():
+            indices = indices.copy()
+            indices[to_shift] += n
+
+        sp_indexer = self.sp_index.lookup_array(indices)
+        value_mask = sp_indexer != -1
+        new_sp_values = self.sp_values[sp_indexer[value_mask]]
+
+        value_indices = np.flatnonzero(value_mask).astype(np.int32, copy=False)
+
+        new_sp_index = make_sparse_index(len(indices), value_indices, kind=self.kind)
+        return type(self)._simple_new(new_sp_values, new_sp_index, dtype=self.dtype)
+
+    def searchsorted(
+        self,
+        v: ArrayLike | object,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        msg = "searchsorted requires high memory usage."
+        warnings.warn(msg, PerformanceWarning, stacklevel=find_stack_level())
+        v = np.asarray(v)
+        return np.asarray(self, dtype=self.dtype.subtype).searchsorted(v, side, sorter)
+
+    def copy(self) -> Self:
+        values = self.sp_values.copy()
+        return self._simple_new(values, self.sp_index, self.dtype)
+
+    @classmethod
+    def _concat_same_type(cls, to_concat: Sequence[Self]) -> Self:
+        fill_value = to_concat[0].fill_value
+
+        values = []
+        length = 0
+
+        if to_concat:
+            sp_kind = to_concat[0].kind
+        else:
+            sp_kind = "integer"
+
+        sp_index: SparseIndex
+        if sp_kind == "integer":
+            indices = []
+
+            for arr in to_concat:
+                int_idx = arr.sp_index.indices.copy()
+                int_idx += length  # TODO: wraparound
+                length += arr.sp_index.length
+
+                values.append(arr.sp_values)
+                indices.append(int_idx)
+
+            data = np.concatenate(values)
+            indices_arr = np.concatenate(indices)
+            # error: Argument 2 to "IntIndex" has incompatible type
+            # "ndarray[Any, dtype[signedinteger[_32Bit]]]";
+            # expected "Sequence[int]"
+            sp_index = IntIndex(length, indices_arr)  # type: ignore[arg-type]
+
+        else:
+            # when concatenating block indices, we don't claim that you'll
+            # get an identical index as concatenating the values and then
+            # creating a new index. We don't want to spend the time trying
+            # to merge blocks across arrays in `to_concat`, so the resulting
+            # BlockIndex may have more blocks.
+            blengths = []
+            blocs = []
+
+            for arr in to_concat:
+                block_idx = arr.sp_index.to_block_index()
+
+                values.append(arr.sp_values)
+                blocs.append(block_idx.blocs.copy() + length)
+                blengths.append(block_idx.blengths)
+                length += arr.sp_index.length
+
+            data = np.concatenate(values)
+            blocs_arr = np.concatenate(blocs)
+            blengths_arr = np.concatenate(blengths)
+
+            sp_index = BlockIndex(length, blocs_arr, blengths_arr)
+
+        return cls(data, sparse_index=sp_index, fill_value=fill_value)
+
+    def astype(self, dtype: AstypeArg | None = None, copy: bool = True):
+        """
+        Change the dtype of a SparseArray.
+
+        The output will always be a SparseArray. To convert to a dense
+        ndarray with a certain dtype, use :meth:`numpy.asarray`.
+
+        Parameters
+        ----------
+        dtype : np.dtype or ExtensionDtype
+            For SparseDtype, this changes the dtype of
+            ``self.sp_values`` and the ``self.fill_value``.
+
+            For other dtypes, this only changes the dtype of
+            ``self.sp_values``.
+
+        copy : bool, default True
+            Whether to ensure a copy is made, even if not necessary.
+
+        Returns
+        -------
+        SparseArray
+
+        Examples
+        --------
+        >>> arr = pd.arrays.SparseArray([0, 0, 1, 2])
+        >>> arr
+        [0, 0, 1, 2]
+        Fill: 0
+        IntIndex
+        Indices: array([2, 3], dtype=int32)
+
+        >>> arr.astype(SparseDtype(np.dtype('int32')))
+        [0, 0, 1, 2]
+        Fill: 0
+        IntIndex
+        Indices: array([2, 3], dtype=int32)
+
+        Using a NumPy dtype with a different kind (e.g. float) will coerce
+        just ``self.sp_values``.
+
+        >>> arr.astype(SparseDtype(np.dtype('float64')))
+        ... # doctest: +NORMALIZE_WHITESPACE
+        [nan, nan, 1.0, 2.0]
+        Fill: nan
+        IntIndex
+        Indices: array([2, 3], dtype=int32)
+
+        Using a SparseDtype, you can also change the fill value as well.
+
+        >>> arr.astype(SparseDtype("float64", fill_value=0.0))
+        ... # doctest: +NORMALIZE_WHITESPACE
+        [0.0, 0.0, 1.0, 2.0]
+        Fill: 0.0
+        IntIndex
+        Indices: array([2, 3], dtype=int32)
+        """
+        if dtype == self._dtype:
+            if not copy:
+                return self
+            else:
+                return self.copy()
+
+        future_dtype = pandas_dtype(dtype)
+        if not isinstance(future_dtype, SparseDtype):
+            # GH#34457
+            values = np.asarray(self)
+            values = ensure_wrapped_if_datetimelike(values)
+            return astype_array(values, dtype=future_dtype, copy=False)
+
+        dtype = self.dtype.update_dtype(dtype)
+        subtype = pandas_dtype(dtype._subtype_with_str)
+        subtype = cast(np.dtype, subtype)  # ensured by update_dtype
+        values = ensure_wrapped_if_datetimelike(self.sp_values)
+        sp_values = astype_array(values, subtype, copy=copy)
+        sp_values = np.asarray(sp_values)
+
+        return self._simple_new(sp_values, self.sp_index, dtype)
+
+    def map(self, mapper, na_action=None) -> Self:
+        """
+        Map categories using an input mapping or function.
+
+        Parameters
+        ----------
+        mapper : dict, Series, callable
+            The correspondence from old values to new.
+        na_action : {None, 'ignore'}, default None
+            If 'ignore', propagate NA values, without passing them to the
+            mapping correspondence.
+
+        Returns
+        -------
+        SparseArray
+            The output array will have the same density as the input.
+            The output fill value will be the result of applying the
+            mapping to ``self.fill_value``
+
+        Examples
+        --------
+        >>> arr = pd.arrays.SparseArray([0, 1, 2])
+        >>> arr.map(lambda x: x + 10)
+        [10, 11, 12]
+        Fill: 10
+        IntIndex
+        Indices: array([1, 2], dtype=int32)
+
+        >>> arr.map({0: 10, 1: 11, 2: 12})
+        [10, 11, 12]
+        Fill: 10
+        IntIndex
+        Indices: array([1, 2], dtype=int32)
+
+        >>> arr.map(pd.Series([10, 11, 12], index=[0, 1, 2]))
+        [10, 11, 12]
+        Fill: 10
+        IntIndex
+        Indices: array([1, 2], dtype=int32)
+        """
+        is_map = isinstance(mapper, (abc.Mapping, ABCSeries))
+
+        fill_val = self.fill_value
+
+        if na_action is None or notna(fill_val):
+            fill_val = mapper.get(fill_val, fill_val) if is_map else mapper(fill_val)
+
+        def func(sp_val):
+            new_sp_val = mapper.get(sp_val, None) if is_map else mapper(sp_val)
+            # check identity and equality because nans are not equal to each other
+            if new_sp_val is fill_val or new_sp_val == fill_val:
+                msg = "fill value in the sparse values not supported"
+                raise ValueError(msg)
+            return new_sp_val
+
+        sp_values = [func(x) for x in self.sp_values]
+
+        return type(self)(sp_values, sparse_index=self.sp_index, fill_value=fill_val)
+
+    def to_dense(self) -> np.ndarray:
+        """
+        Convert SparseArray to a NumPy array.
+
+        Returns
+        -------
+        arr : NumPy array
+        """
+        return np.asarray(self, dtype=self.sp_values.dtype)
+
+    def _where(self, mask, value):
+        # NB: may not preserve dtype, e.g. result may be Sparse[float64]
+        #  while self is Sparse[int64]
+        naive_implementation = np.where(mask, self, value)
+        dtype = SparseDtype(naive_implementation.dtype, fill_value=self.fill_value)
+        result = type(self)._from_sequence(naive_implementation, dtype=dtype)
+        return result
+
+    # ------------------------------------------------------------------------
+    # IO
+    # ------------------------------------------------------------------------
+    def __setstate__(self, state) -> None:
+        """Necessary for making this object picklable"""
+        if isinstance(state, tuple):
+            # Compat for pandas < 0.24.0
+            nd_state, (fill_value, sp_index) = state
+            sparse_values = np.array([])
+            sparse_values.__setstate__(nd_state)
+
+            self._sparse_values = sparse_values
+            self._sparse_index = sp_index
+            self._dtype = SparseDtype(sparse_values.dtype, fill_value)
+        else:
+            self.__dict__.update(state)
+
+    def nonzero(self) -> tuple[npt.NDArray[np.int32]]:
+        if self.fill_value == 0:
+            return (self.sp_index.indices,)
+        else:
+            return (self.sp_index.indices[self.sp_values != 0],)
+
+    # ------------------------------------------------------------------------
+    # Reductions
+    # ------------------------------------------------------------------------
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        method = getattr(self, name, None)
+
+        if method is None:
+            raise TypeError(f"cannot perform {name} with type {self.dtype}")
+
+        if skipna:
+            arr = self
+        else:
+            arr = self.dropna()
+
+        result = getattr(arr, name)(**kwargs)
+
+        if keepdims:
+            return type(self)([result], dtype=self.dtype)
+        else:
+            return result
+
+    def all(self, axis=None, *args, **kwargs):
+        """
+        Tests whether all elements evaluate True
+
+        Returns
+        -------
+        all : bool
+
+        See Also
+        --------
+        numpy.all
+        """
+        nv.validate_all(args, kwargs)
+
+        values = self.sp_values
+
+        if len(values) != len(self) and not np.all(self.fill_value):
+            return False
+
+        return values.all()
+
+    def any(self, axis: AxisInt = 0, *args, **kwargs) -> bool:
+        """
+        Tests whether at least one of elements evaluate True
+
+        Returns
+        -------
+        any : bool
+
+        See Also
+        --------
+        numpy.any
+        """
+        nv.validate_any(args, kwargs)
+
+        values = self.sp_values
+
+        if len(values) != len(self) and np.any(self.fill_value):
+            return True
+
+        return values.any().item()
+
+    def sum(
+        self,
+        axis: AxisInt = 0,
+        min_count: int = 0,
+        skipna: bool = True,
+        *args,
+        **kwargs,
+    ) -> Scalar:
+        """
+        Sum of non-NA/null values
+
+        Parameters
+        ----------
+        axis : int, default 0
+            Not Used. NumPy compatibility.
+        min_count : int, default 0
+            The required number of valid values to perform the summation. If fewer
+            than ``min_count`` valid values are present, the result will be the missing
+            value indicator for subarray type.
+        *args, **kwargs
+            Not Used. NumPy compatibility.
+
+        Returns
+        -------
+        scalar
+        """
+        nv.validate_sum(args, kwargs)
+        valid_vals = self._valid_sp_values
+        sp_sum = valid_vals.sum()
+        has_na = self.sp_index.ngaps > 0 and not self._null_fill_value
+
+        if has_na and not skipna:
+            return na_value_for_dtype(self.dtype.subtype, compat=False)
+
+        if self._null_fill_value:
+            if check_below_min_count(valid_vals.shape, None, min_count):
+                return na_value_for_dtype(self.dtype.subtype, compat=False)
+            return sp_sum
+        else:
+            nsparse = self.sp_index.ngaps
+            if check_below_min_count(valid_vals.shape, None, min_count - nsparse):
+                return na_value_for_dtype(self.dtype.subtype, compat=False)
+            return sp_sum + self.fill_value * nsparse
+
+    def cumsum(self, axis: AxisInt = 0, *args, **kwargs) -> SparseArray:
+        """
+        Cumulative sum of non-NA/null values.
+
+        When performing the cumulative summation, any non-NA/null values will
+        be skipped. The resulting SparseArray will preserve the locations of
+        NaN values, but the fill value will be `np.nan` regardless.
+
+        Parameters
+        ----------
+        axis : int or None
+            Axis over which to perform the cumulative summation. If None,
+            perform cumulative summation over flattened array.
+
+        Returns
+        -------
+        cumsum : SparseArray
+        """
+        nv.validate_cumsum(args, kwargs)
+
+        if axis is not None and axis >= self.ndim:  # Mimic ndarray behaviour.
+            raise ValueError(f"axis(={axis}) out of bounds")
+
+        if not self._null_fill_value:
+            return SparseArray(self.to_dense()).cumsum()
+
+        return SparseArray(
+            self.sp_values.cumsum(),
+            sparse_index=self.sp_index,
+            fill_value=self.fill_value,
+        )
+
+    def mean(self, axis: Axis = 0, *args, **kwargs):
+        """
+        Mean of non-NA/null values
+
+        Returns
+        -------
+        mean : float
+        """
+        nv.validate_mean(args, kwargs)
+        valid_vals = self._valid_sp_values
+        sp_sum = valid_vals.sum()
+        ct = len(valid_vals)
+
+        if self._null_fill_value:
+            return sp_sum / ct
+        else:
+            nsparse = self.sp_index.ngaps
+            return (sp_sum + self.fill_value * nsparse) / (ct + nsparse)
+
+    def max(self, *, axis: AxisInt | None = None, skipna: bool = True):
+        """
+        Max of array values, ignoring NA values if specified.
+
+        Parameters
+        ----------
+        axis : int, default 0
+            Not Used. NumPy compatibility.
+        skipna : bool, default True
+            Whether to ignore NA values.
+
+        Returns
+        -------
+        scalar
+        """
+        nv.validate_minmax_axis(axis, self.ndim)
+        return self._min_max("max", skipna=skipna)
+
+    def min(self, *, axis: AxisInt | None = None, skipna: bool = True):
+        """
+        Min of array values, ignoring NA values if specified.
+
+        Parameters
+        ----------
+        axis : int, default 0
+            Not Used. NumPy compatibility.
+        skipna : bool, default True
+            Whether to ignore NA values.
+
+        Returns
+        -------
+        scalar
+        """
+        nv.validate_minmax_axis(axis, self.ndim)
+        return self._min_max("min", skipna=skipna)
+
+    def _min_max(self, kind: Literal["min", "max"], skipna: bool) -> Scalar:
+        """
+        Min/max of non-NA/null values
+
+        Parameters
+        ----------
+        kind : {"min", "max"}
+        skipna : bool
+
+        Returns
+        -------
+        scalar
+        """
+        valid_vals = self._valid_sp_values
+        has_nonnull_fill_vals = not self._null_fill_value and self.sp_index.ngaps > 0
+
+        if len(valid_vals) > 0:
+            sp_min_max = getattr(valid_vals, kind)()
+
+            # If a non-null fill value is currently present, it might be the min/max
+            if has_nonnull_fill_vals:
+                func = max if kind == "max" else min
+                return func(sp_min_max, self.fill_value)
+            elif skipna:
+                return sp_min_max
+            elif self.sp_index.ngaps == 0:
+                # No NAs present
+                return sp_min_max
+            else:
+                return na_value_for_dtype(self.dtype.subtype, compat=False)
+        elif has_nonnull_fill_vals:
+            return self.fill_value
+        else:
+            return na_value_for_dtype(self.dtype.subtype, compat=False)
+
+    def _argmin_argmax(self, kind: Literal["argmin", "argmax"]) -> int:
+        values = self._sparse_values
+        index = self._sparse_index.indices
+        mask = np.asarray(isna(values))
+        func = np.argmax if kind == "argmax" else np.argmin
+
+        idx = np.arange(values.shape[0])
+        non_nans = values[~mask]
+        non_nan_idx = idx[~mask]
+
+        _candidate = non_nan_idx[func(non_nans)]
+        candidate = index[_candidate]
+
+        if isna(self.fill_value):
+            return candidate
+        if kind == "argmin" and self[candidate] < self.fill_value:
+            return candidate
+        if kind == "argmax" and self[candidate] > self.fill_value:
+            return candidate
+        _loc = self._first_fill_value_loc()
+        if _loc == -1:
+            # fill_value doesn't exist
+            return candidate
+        else:
+            return _loc
+
+    def argmax(self, skipna: bool = True) -> int:
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return self._argmin_argmax("argmax")
+
+    def argmin(self, skipna: bool = True) -> int:
+        validate_bool_kwarg(skipna, "skipna")
+        if not skipna and self._hasna:
+            raise NotImplementedError
+        return self._argmin_argmax("argmin")
+
+    # ------------------------------------------------------------------------
+    # Ufuncs
+    # ------------------------------------------------------------------------
+
+    _HANDLED_TYPES = (np.ndarray, numbers.Number)
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str, *inputs, **kwargs):
+        out = kwargs.get("out", ())
+
+        for x in inputs + out:
+            if not isinstance(x, self._HANDLED_TYPES + (SparseArray,)):
+                return NotImplemented
+
+        # for binary ops, use our custom dunder methods
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            # e.g. tests.arrays.sparse.test_arithmetics.test_ndarray_inplace
+            res = arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            return res
+
+        if method == "reduce":
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                # e.g. tests.series.test_ufunc.TestNumpyReductions
+                return result
+
+        if len(inputs) == 1:
+            # No alignment necessary.
+            sp_values = getattr(ufunc, method)(self.sp_values, **kwargs)
+            fill_value = getattr(ufunc, method)(self.fill_value, **kwargs)
+
+            if ufunc.nout > 1:
+                # multiple outputs. e.g. modf
+                arrays = tuple(
+                    self._simple_new(
+                        sp_value, self.sp_index, SparseDtype(sp_value.dtype, fv)
+                    )
+                    for sp_value, fv in zip(sp_values, fill_value)
+                )
+                return arrays
+            elif method == "reduce":
+                # e.g. reductions
+                return sp_values
+
+            return self._simple_new(
+                sp_values, self.sp_index, SparseDtype(sp_values.dtype, fill_value)
+            )
+
+        new_inputs = tuple(np.asarray(x) for x in inputs)
+        result = getattr(ufunc, method)(*new_inputs, **kwargs)
+        if out:
+            if len(out) == 1:
+                out = out[0]
+            return out
+
+        if ufunc.nout > 1:
+            return tuple(type(self)(x) for x in result)
+        elif method == "at":
+            # no return value
+            return None
+        else:
+            return type(self)(result)
+
+    # ------------------------------------------------------------------------
+    # Ops
+    # ------------------------------------------------------------------------
+
+    def _arith_method(self, other, op):
+        op_name = op.__name__
+
+        if isinstance(other, SparseArray):
+            return _sparse_array_op(self, other, op, op_name)
+
+        elif is_scalar(other):
+            with np.errstate(all="ignore"):
+                fill = op(_get_fill(self), np.asarray(other))
+                result = op(self.sp_values, other)
+
+            if op_name == "divmod":
+                left, right = result
+                lfill, rfill = fill
+                return (
+                    _wrap_result(op_name, left, self.sp_index, lfill),
+                    _wrap_result(op_name, right, self.sp_index, rfill),
+                )
+
+            return _wrap_result(op_name, result, self.sp_index, fill)
+
+        else:
+            other = np.asarray(other)
+            with np.errstate(all="ignore"):
+                if len(self) != len(other):
+                    raise AssertionError(
+                        f"length mismatch: {len(self)} vs. {len(other)}"
+                    )
+                if not isinstance(other, SparseArray):
+                    dtype = getattr(other, "dtype", None)
+                    other = SparseArray(other, fill_value=self.fill_value, dtype=dtype)
+                return _sparse_array_op(self, other, op, op_name)
+
+    def _cmp_method(self, other, op) -> SparseArray:
+        if not is_scalar(other) and not isinstance(other, type(self)):
+            # convert list-like to ndarray
+            other = np.asarray(other)
+
+        if isinstance(other, np.ndarray):
+            # TODO: make this more flexible than just ndarray...
+            other = SparseArray(other, fill_value=self.fill_value)
+
+        if isinstance(other, SparseArray):
+            if len(self) != len(other):
+                raise ValueError(
+                    f"operands have mismatched length {len(self)} and {len(other)}"
+                )
+
+            op_name = op.__name__.strip("_")
+            return _sparse_array_op(self, other, op, op_name)
+        else:
+            # scalar
+            fill_value = op(self.fill_value, other)
+            result = np.full(len(self), fill_value, dtype=np.bool_)
+            result[self.sp_index.indices] = op(self.sp_values, other)
+
+            return type(self)(
+                result,
+                fill_value=fill_value,
+                dtype=np.bool_,
+            )
+
+    _logical_method = _cmp_method
+
+    def _unary_method(self, op) -> SparseArray:
+        fill_value = op(np.array(self.fill_value)).item()
+        dtype = SparseDtype(self.dtype.subtype, fill_value)
+        # NOTE: if fill_value doesn't change
+        # we just have to apply op to sp_values
+        if isna(self.fill_value) or fill_value == self.fill_value:
+            values = op(self.sp_values)
+            return type(self)._simple_new(values, self.sp_index, self.dtype)
+        # In the other case we have to recalc indexes
+        return type(self)(op(self.to_dense()), dtype=dtype)
+
+    def __pos__(self) -> SparseArray:
+        return self._unary_method(operator.pos)
+
+    def __neg__(self) -> SparseArray:
+        return self._unary_method(operator.neg)
+
+    def __invert__(self) -> SparseArray:
+        return self._unary_method(operator.invert)
+
+    def __abs__(self) -> SparseArray:
+        return self._unary_method(operator.abs)
+
+    # ----------
+    # Formatting
+    # -----------
+    def __repr__(self) -> str:
+        pp_str = printing.pprint_thing(self)
+        pp_fill = printing.pprint_thing(self.fill_value)
+        pp_index = printing.pprint_thing(self.sp_index)
+        return f"{pp_str}\nFill: {pp_fill}\n{pp_index}"
+
+    def _formatter(self, boxed: bool = False):
+        # Defer to the formatter from the GenericArrayFormatter calling us.
+        # This will infer the correct formatter from the dtype of the values.
+        return None
+
+
+def _make_sparse(
+    arr: np.ndarray,
+    kind: SparseIndexKind = "block",
+    fill_value=None,
+    dtype: np.dtype | None = None,
+):
+    """
+    Convert ndarray to sparse format
+
+    Parameters
+    ----------
+    arr : ndarray
+    kind : {'block', 'integer'}
+    fill_value : NaN or another value
+    dtype : np.dtype, optional
+    copy : bool, default False
+
+    Returns
+    -------
+    (sparse_values, index, fill_value) : (ndarray, SparseIndex, Scalar)
+    """
+    assert isinstance(arr, np.ndarray)
+
+    if arr.ndim > 1:
+        raise TypeError("expected dimension <= 1 data")
+
+    if fill_value is None:
+        fill_value = na_value_for_dtype(arr.dtype)
+
+    if isna(fill_value):
+        mask = notna(arr)
+    else:
+        # cast to object comparison to be safe
+        if is_string_dtype(arr.dtype):
+            arr = arr.astype(object)
+
+        if is_object_dtype(arr.dtype):
+            # element-wise equality check method in numpy doesn't treat
+            # each element type, eg. 0, 0.0, and False are treated as
+            # same. So we have to check the both of its type and value.
+            mask = splib.make_mask_object_ndarray(arr, fill_value)
+        else:
+            mask = arr != fill_value
+
+    length = len(arr)
+    if length != len(mask):
+        # the arr is a SparseArray
+        indices = mask.sp_index.indices
+    else:
+        indices = mask.nonzero()[0].astype(np.int32)
+
+    index = make_sparse_index(length, indices, kind)
+    sparsified_values = arr[mask]
+    if dtype is not None:
+        sparsified_values = ensure_wrapped_if_datetimelike(sparsified_values)
+        sparsified_values = astype_array(sparsified_values, dtype=dtype)
+        sparsified_values = np.asarray(sparsified_values)
+
+    # TODO: copy
+    return sparsified_values, index, fill_value
+
+
+@overload
+def make_sparse_index(length: int, indices, kind: Literal["block"]) -> BlockIndex:
+    ...
+
+
+@overload
+def make_sparse_index(length: int, indices, kind: Literal["integer"]) -> IntIndex:
+    ...
+
+
+def make_sparse_index(length: int, indices, kind: SparseIndexKind) -> SparseIndex:
+    index: SparseIndex
+    if kind == "block":
+        locs, lens = splib.get_blocks(indices)
+        index = BlockIndex(length, locs, lens)
+    elif kind == "integer":
+        index = IntIndex(length, indices)
+    else:  # pragma: no cover
+        raise ValueError("must be block or integer type")
+    return index
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/scipy_sparse.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/scipy_sparse.py
new file mode 100644
index 0000000000000000000000000000000000000000..71b71a9779da5c1a584e0ef98bc8320d81bc2a35
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/sparse/scipy_sparse.py
@@ -0,0 +1,207 @@
+"""
+Interaction with scipy.sparse matrices.
+
+Currently only includes to_coo helpers.
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.missing import notna
+
+from pandas.core.algorithms import factorize
+from pandas.core.indexes.api import MultiIndex
+from pandas.core.series import Series
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    import numpy as np
+    import scipy.sparse
+
+    from pandas._typing import (
+        IndexLabel,
+        npt,
+    )
+
+
+def _check_is_partition(parts: Iterable, whole: Iterable):
+    whole = set(whole)
+    parts = [set(x) for x in parts]
+    if set.intersection(*parts) != set():
+        raise ValueError("Is not a partition because intersection is not null.")
+    if set.union(*parts) != whole:
+        raise ValueError("Is not a partition because union is not the whole.")
+
+
+def _levels_to_axis(
+    ss,
+    levels: tuple[int] | list[int],
+    valid_ilocs: npt.NDArray[np.intp],
+    sort_labels: bool = False,
+) -> tuple[npt.NDArray[np.intp], list[IndexLabel]]:
+    """
+    For a MultiIndexed sparse Series `ss`, return `ax_coords` and `ax_labels`,
+    where `ax_coords` are the coordinates along one of the two axes of the
+    destination sparse matrix, and `ax_labels` are the labels from `ss`' Index
+    which correspond to these coordinates.
+
+    Parameters
+    ----------
+    ss : Series
+    levels : tuple/list
+    valid_ilocs : numpy.ndarray
+        Array of integer positions of valid values for the sparse matrix in ss.
+    sort_labels : bool, default False
+        Sort the axis labels before forming the sparse matrix. When `levels`
+        refers to a single level, set to True for a faster execution.
+
+    Returns
+    -------
+    ax_coords : numpy.ndarray (axis coordinates)
+    ax_labels : list (axis labels)
+    """
+    # Since the labels are sorted in `Index.levels`, when we wish to sort and
+    # there is only one level of the MultiIndex for this axis, the desired
+    # output can be obtained in the following simpler, more efficient way.
+    if sort_labels and len(levels) == 1:
+        ax_coords = ss.index.codes[levels[0]][valid_ilocs]
+        ax_labels = ss.index.levels[levels[0]]
+
+    else:
+        levels_values = lib.fast_zip(
+            [ss.index.get_level_values(lvl).to_numpy() for lvl in levels]
+        )
+        codes, ax_labels = factorize(levels_values, sort=sort_labels)
+        ax_coords = codes[valid_ilocs]
+
+    ax_labels = ax_labels.tolist()
+    return ax_coords, ax_labels
+
+
+def _to_ijv(
+    ss,
+    row_levels: tuple[int] | list[int] = (0,),
+    column_levels: tuple[int] | list[int] = (1,),
+    sort_labels: bool = False,
+) -> tuple[
+    np.ndarray,
+    npt.NDArray[np.intp],
+    npt.NDArray[np.intp],
+    list[IndexLabel],
+    list[IndexLabel],
+]:
+    """
+    For an arbitrary MultiIndexed sparse Series return (v, i, j, ilabels,
+    jlabels) where (v, (i, j)) is suitable for passing to scipy.sparse.coo
+    constructor, and ilabels and jlabels are the row and column labels
+    respectively.
+
+    Parameters
+    ----------
+    ss : Series
+    row_levels : tuple/list
+    column_levels : tuple/list
+    sort_labels : bool, default False
+        Sort the row and column labels before forming the sparse matrix.
+        When `row_levels` and/or `column_levels` refer to a single level,
+        set to `True` for a faster execution.
+
+    Returns
+    -------
+    values : numpy.ndarray
+        Valid values to populate a sparse matrix, extracted from
+        ss.
+    i_coords : numpy.ndarray (row coordinates of the values)
+    j_coords : numpy.ndarray (column coordinates of the values)
+    i_labels : list (row labels)
+    j_labels : list (column labels)
+    """
+    # index and column levels must be a partition of the index
+    _check_is_partition([row_levels, column_levels], range(ss.index.nlevels))
+    # From the sparse Series, get the integer indices and data for valid sparse
+    # entries.
+    sp_vals = ss.array.sp_values
+    na_mask = notna(sp_vals)
+    values = sp_vals[na_mask]
+    valid_ilocs = ss.array.sp_index.indices[na_mask]
+
+    i_coords, i_labels = _levels_to_axis(
+        ss, row_levels, valid_ilocs, sort_labels=sort_labels
+    )
+
+    j_coords, j_labels = _levels_to_axis(
+        ss, column_levels, valid_ilocs, sort_labels=sort_labels
+    )
+
+    return values, i_coords, j_coords, i_labels, j_labels
+
+
+def sparse_series_to_coo(
+    ss: Series,
+    row_levels: Iterable[int] = (0,),
+    column_levels: Iterable[int] = (1,),
+    sort_labels: bool = False,
+) -> tuple[scipy.sparse.coo_matrix, list[IndexLabel], list[IndexLabel]]:
+    """
+    Convert a sparse Series to a scipy.sparse.coo_matrix using index
+    levels row_levels, column_levels as the row and column
+    labels respectively. Returns the sparse_matrix, row and column labels.
+    """
+    import scipy.sparse
+
+    if ss.index.nlevels < 2:
+        raise ValueError("to_coo requires MultiIndex with nlevels >= 2.")
+    if not ss.index.is_unique:
+        raise ValueError(
+            "Duplicate index entries are not allowed in to_coo transformation."
+        )
+
+    # to keep things simple, only rely on integer indexing (not labels)
+    row_levels = [ss.index._get_level_number(x) for x in row_levels]
+    column_levels = [ss.index._get_level_number(x) for x in column_levels]
+
+    v, i, j, rows, columns = _to_ijv(
+        ss, row_levels=row_levels, column_levels=column_levels, sort_labels=sort_labels
+    )
+    sparse_matrix = scipy.sparse.coo_matrix(
+        (v, (i, j)), shape=(len(rows), len(columns))
+    )
+    return sparse_matrix, rows, columns
+
+
+def coo_to_sparse_series(
+    A: scipy.sparse.coo_matrix, dense_index: bool = False
+) -> Series:
+    """
+    Convert a scipy.sparse.coo_matrix to a Series with type sparse.
+
+    Parameters
+    ----------
+    A : scipy.sparse.coo_matrix
+    dense_index : bool, default False
+
+    Returns
+    -------
+    Series
+
+    Raises
+    ------
+    TypeError if A is not a coo_matrix
+    """
+    from pandas import SparseDtype
+
+    try:
+        ser = Series(A.data, MultiIndex.from_arrays((A.row, A.col)), copy=False)
+    except AttributeError as err:
+        raise TypeError(
+            f"Expected coo_matrix. Got {type(A).__name__} instead."
+        ) from err
+    ser = ser.sort_index()
+    ser = ser.astype(SparseDtype(ser.dtype))
+    if dense_index:
+        ind = MultiIndex.from_product([A.row, A.col])
+        ser = ser.reindex(ind)
+    return ser
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_.py
new file mode 100644
index 0000000000000000000000000000000000000000..edc5529d0d78c78b4981ec953c4f202c23988914
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_.py
@@ -0,0 +1,1135 @@
+from __future__ import annotations
+
+from functools import partial
+import operator
+from pathlib import Path
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import (
+    get_option,
+    using_string_dtype,
+)
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas._libs.arrays import NDArrayBacked
+from pandas._libs.lib import ensure_string_array
+from pandas.compat import (
+    HAS_PYARROW,
+    pa_version_under10p1,
+)
+from pandas.compat.numpy import function as nv
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import (
+    ExtensionDtype,
+    StorageExtensionDtype,
+    register_extension_dtype,
+)
+from pandas.core.dtypes.common import (
+    is_array_like,
+    is_bool_dtype,
+    is_integer_dtype,
+    is_object_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+
+from pandas.core import (
+    missing,
+    nanops,
+    ops,
+    roperator,
+)
+from pandas.core.algorithms import isin
+from pandas.core.array_algos import masked_reductions
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.arrays.floating import (
+    FloatingArray,
+    FloatingDtype,
+)
+from pandas.core.arrays.integer import (
+    IntegerArray,
+    IntegerDtype,
+)
+from pandas.core.arrays.numpy_ import NumpyExtensionArray
+from pandas.core.construction import extract_array
+from pandas.core.indexers import check_array_indexer
+from pandas.core.missing import isna
+
+from pandas.io.formats import printing
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+
+    import pyarrow
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        Dtype,
+        DtypeObj,
+        NumpySorter,
+        NumpyValueArrayLike,
+        Scalar,
+        Self,
+        npt,
+        type_t,
+    )
+
+    from pandas import Series
+
+
+@register_extension_dtype
+class StringDtype(StorageExtensionDtype):
+    """
+    Extension dtype for string data.
+
+    .. warning::
+
+       StringDtype is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Parameters
+    ----------
+    storage : {"python", "pyarrow"}, optional
+        If not given, the value of ``pd.options.mode.string_storage``.
+    na_value : {np.nan, pd.NA}, default pd.NA
+        Whether the dtype follows NaN or NA missing value semantics.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.StringDtype()
+    string[python]
+
+    >>> pd.StringDtype(storage="pyarrow")
+    string[pyarrow]
+    """
+
+    @property
+    def name(self) -> str:  # type: ignore[override]
+        if self._na_value is libmissing.NA:
+            return "string"
+        else:
+            return "str"
+
+    #: StringDtype().na_value uses pandas.NA except the implementation that
+    # follows NumPy semantics, which uses nan.
+    @property
+    def na_value(self) -> libmissing.NAType | float:  # type: ignore[override]
+        return self._na_value
+
+    _metadata = ("storage", "_na_value")  # type: ignore[assignment]
+
+    def __init__(
+        self,
+        storage: str | None = None,
+        na_value: libmissing.NAType | float = libmissing.NA,
+    ) -> None:
+        # infer defaults
+        if storage is None:
+            if na_value is not libmissing.NA:
+                storage = get_option("mode.string_storage")
+                if storage == "auto":
+                    if HAS_PYARROW:
+                        storage = "pyarrow"
+                    else:
+                        storage = "python"
+            else:
+                storage = get_option("mode.string_storage")
+                if storage == "auto":
+                    storage = "python"
+
+        if storage == "pyarrow_numpy":
+            warnings.warn(
+                "The 'pyarrow_numpy' storage option name is deprecated and will be "
+                'removed in pandas 3.0. Use \'pd.StringDtype(storage="pyarrow", '
+                "na_value-np.nan)' to construct the same dtype.\nOr enable the "
+                "'pd.options.future.infer_string = True' option globally and use "
+                'the "str" alias as a shorthand notation to specify a dtype '
+                '(instead of "string[pyarrow_numpy]").',
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            storage = "pyarrow"
+            na_value = np.nan
+
+        # validate options
+        if storage not in {"python", "pyarrow"}:
+            raise ValueError(
+                f"Storage must be 'python' or 'pyarrow'. Got {storage} instead."
+            )
+        if storage == "pyarrow" and pa_version_under10p1:
+            raise ImportError(
+                "pyarrow>=10.0.1 is required for PyArrow backed StringArray."
+            )
+
+        if isinstance(na_value, float) and np.isnan(na_value):
+            # when passed a NaN value, always set to np.nan to ensure we use
+            # a consistent NaN value (and we can use `dtype.na_value is np.nan`)
+            na_value = np.nan
+        elif na_value is not libmissing.NA:
+            raise ValueError(f"'na_value' must be np.nan or pd.NA, got {na_value}")
+
+        self.storage = cast(str, storage)
+        self._na_value = na_value
+
+    def __repr__(self) -> str:
+        if self._na_value is libmissing.NA:
+            return f"{self.name}[{self.storage}]"
+        else:
+            storage = "" if self.storage == "pyarrow" else "storage='python', "
+            return f""
+
+    def __eq__(self, other: object) -> bool:
+        # we need to override the base class __eq__ because na_value (NA or NaN)
+        # cannot be checked with normal `==`
+        if isinstance(other, str):
+            # TODO should dtype == "string" work for the NaN variant?
+            if other == "string" or other == self.name:  # noqa: PLR1714
+                return True
+            try:
+                other = self.construct_from_string(other)
+            except (TypeError, ImportError):
+                # TypeError if `other` is not a valid string for StringDtype
+                # ImportError if pyarrow is not installed for "string[pyarrow]"
+                return False
+        if isinstance(other, type(self)):
+            return self.storage == other.storage and self.na_value is other.na_value
+        return False
+
+    def __setstate__(self, state: MutableMapping[str, Any]) -> None:
+        # back-compat for pandas < 2.3, where na_value did not yet exist
+        self.storage = state.pop("storage", "python")
+        self._na_value = state.pop("_na_value", libmissing.NA)
+
+    def __hash__(self) -> int:
+        # need to override __hash__ as well because of overriding __eq__
+        return super().__hash__()
+
+    def __reduce__(self):
+        return StringDtype, (self.storage, self.na_value)
+
+    @property
+    def type(self) -> type[str]:
+        return str
+
+    @classmethod
+    def construct_from_string(cls, string) -> Self:
+        """
+        Construct a StringDtype from a string.
+
+        Parameters
+        ----------
+        string : str
+            The type of the name. The storage type will be taking from `string`.
+            Valid options and their storage types are
+
+            ========================== ==============================================
+            string                     result storage
+            ========================== ==============================================
+            ``'string'``               pd.options.mode.string_storage, default python
+            ``'string[python]'``       python
+            ``'string[pyarrow]'``      pyarrow
+            ========================== ==============================================
+
+        Returns
+        -------
+        StringDtype
+
+        Raise
+        -----
+        TypeError
+            If the string is not a valid option.
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+        if string == "string":
+            return cls()
+        elif string == "str" and using_string_dtype():
+            return cls(na_value=np.nan)
+        elif string == "string[python]":
+            return cls(storage="python")
+        elif string == "string[pyarrow]":
+            return cls(storage="pyarrow")
+        elif string == "string[pyarrow_numpy]":
+            # this is deprecated in the dtype __init__, remove this in pandas 3.0
+            return cls(storage="pyarrow_numpy")
+        else:
+            raise TypeError(f"Cannot construct a '{cls.__name__}' from '{string}'")
+
+    # https://github.com/pandas-dev/pandas/issues/36126
+    # error: Signature of "construct_array_type" incompatible with supertype
+    # "ExtensionDtype"
+    def construct_array_type(  # type: ignore[override]
+        self,
+    ) -> type_t[BaseStringArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays.string_arrow import (
+            ArrowStringArray,
+            ArrowStringArrayNumpySemantics,
+        )
+
+        if self.storage == "python" and self._na_value is libmissing.NA:
+            return StringArray
+        elif self.storage == "pyarrow" and self._na_value is libmissing.NA:
+            return ArrowStringArray
+        elif self.storage == "python":
+            return StringArrayNumpySemantics
+        else:
+            return ArrowStringArrayNumpySemantics
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        storages = set()
+        na_values = set()
+
+        for dtype in dtypes:
+            if isinstance(dtype, StringDtype):
+                storages.add(dtype.storage)
+                na_values.add(dtype.na_value)
+            elif isinstance(dtype, np.dtype) and dtype.kind in ("U", "T"):
+                continue
+            else:
+                return None
+
+        if len(storages) == 2:
+            # if both python and pyarrow storage -> priority to pyarrow
+            storage = "pyarrow"
+        else:
+            storage = next(iter(storages))  # type: ignore[assignment]
+
+        na_value: libmissing.NAType | float
+        if len(na_values) == 2:
+            # if both NaN and NA -> priority to NA
+            na_value = libmissing.NA
+        else:
+            na_value = next(iter(na_values))
+
+        return StringDtype(storage=storage, na_value=na_value)
+
+    def __from_arrow__(
+        self, array: pyarrow.Array | pyarrow.ChunkedArray
+    ) -> BaseStringArray:
+        """
+        Construct StringArray from pyarrow Array/ChunkedArray.
+        """
+        if self.storage == "pyarrow":
+            if self._na_value is libmissing.NA:
+                from pandas.core.arrays.string_arrow import ArrowStringArray
+
+                return ArrowStringArray(array)
+            else:
+                from pandas.core.arrays.string_arrow import (
+                    ArrowStringArrayNumpySemantics,
+                )
+
+                return ArrowStringArrayNumpySemantics(array)
+
+        else:
+            import pyarrow
+
+            if isinstance(array, pyarrow.Array):
+                chunks = [array]
+            else:
+                # pyarrow.ChunkedArray
+                chunks = array.chunks
+
+            results = []
+            for arr in chunks:
+                # convert chunk by chunk to numpy and concatenate then, to avoid
+                # overflow for large string data when concatenating the pyarrow arrays
+                arr = arr.to_numpy(zero_copy_only=False)
+                arr = ensure_string_array(arr, na_value=self.na_value)
+                results.append(arr)
+
+        if len(chunks) == 0:
+            arr = np.array([], dtype=object)
+        else:
+            arr = np.concatenate(results)
+
+        # Bypass validation inside StringArray constructor, see GH#47781
+        new_string_array = StringArray.__new__(StringArray)
+        NDArrayBacked.__init__(new_string_array, arr, self)
+        return new_string_array
+
+
+class BaseStringArray(ExtensionArray):
+    """
+    Mixin class for StringArray, ArrowStringArray.
+    """
+
+    dtype: StringDtype
+
+    # TODO(4.0): Once the deprecation here is enforced, this method can be
+    #  removed and we use the parent class method instead.
+    def _logical_method(self, other, op):
+        if (
+            op in (roperator.ror_, roperator.rand_, roperator.rxor)
+            and isinstance(other, np.ndarray)
+            and other.dtype == bool
+        ):
+            # GH#60234 backward compatibility for the move to StringDtype in 3.0
+            op_name = op.__name__[1:].strip("_")
+            warnings.warn(
+                f"'{op_name}' operations between boolean dtype and {self.dtype} are "
+                "deprecated and will raise in a future version. Explicitly "
+                "cast the strings to a boolean dtype before operating instead.",
+                DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+            return op(other, self.astype(bool))
+        return NotImplemented
+
+    @doc(ExtensionArray.tolist)
+    def tolist(self):
+        if self.ndim > 1:
+            return [x.tolist() for x in self]
+        return list(self.to_numpy())
+
+    @classmethod
+    def _from_scalars(cls, scalars, dtype: DtypeObj) -> Self:
+        if lib.infer_dtype(scalars, skipna=True) not in ["string", "empty"]:
+            # TODO: require any NAs be valid-for-string
+            raise ValueError
+        return cls._from_sequence(scalars, dtype=dtype)
+
+    def _formatter(self, boxed: bool = False):
+        formatter = partial(
+            printing.pprint_thing,
+            escape_chars=("\t", "\r", "\n"),
+            quote_strings=not boxed,
+        )
+        return formatter
+
+    def _str_map(
+        self,
+        f,
+        na_value=lib.no_default,
+        dtype: Dtype | None = None,
+        convert: bool = True,
+    ):
+        if self.dtype.na_value is np.nan:
+            return self._str_map_nan_semantics(
+                f, na_value=na_value, dtype=dtype, convert=convert
+            )
+
+        from pandas.arrays import BooleanArray
+
+        if dtype is None:
+            dtype = self.dtype
+        if na_value is lib.no_default:
+            na_value = self.dtype.na_value
+
+        mask = isna(self)
+        arr = np.asarray(self)
+
+        if is_integer_dtype(dtype) or is_bool_dtype(dtype):
+            constructor: type[IntegerArray | BooleanArray]
+            if is_integer_dtype(dtype):
+                constructor = IntegerArray
+            else:
+                constructor = BooleanArray
+
+            na_value_is_na = isna(na_value)
+            if na_value_is_na:
+                na_value = 1
+            elif dtype == np.dtype("bool"):
+                # GH#55736
+                na_value = bool(na_value)
+            result = lib.map_infer_mask(
+                arr,
+                f,
+                mask.view("uint8"),
+                convert=False,
+                na_value=na_value,
+                # error: Argument 1 to "dtype" has incompatible type
+                # "Union[ExtensionDtype, str, dtype[Any], Type[object]]"; expected
+                # "Type[object]"
+                dtype=np.dtype(cast(type, dtype)),
+            )
+
+            if not na_value_is_na:
+                mask[:] = False
+
+            return constructor(result, mask)
+
+        else:
+            return self._str_map_str_or_object(dtype, na_value, arr, f, mask)
+
+    def _str_map_str_or_object(
+        self,
+        dtype,
+        na_value,
+        arr: np.ndarray,
+        f,
+        mask: npt.NDArray[np.bool_],
+    ):
+        # _str_map helper for case where dtype is either string dtype or object
+        if is_string_dtype(dtype) and not is_object_dtype(dtype):
+            # i.e. StringDtype
+            result = lib.map_infer_mask(
+                arr, f, mask.view("uint8"), convert=False, na_value=na_value
+            )
+            if self.dtype.storage == "pyarrow":
+                import pyarrow as pa
+
+                result = pa.array(
+                    result, mask=mask, type=pa.large_string(), from_pandas=True
+                )
+            # error: Too many arguments for "BaseStringArray"
+            return type(self)(result)  # type: ignore[call-arg]
+
+        else:
+            # This is when the result type is object. We reach this when
+            # -> We know the result type is truly object (e.g. .encode returns bytes
+            #    or .findall returns a list).
+            # -> We don't know the result type. E.g. `.get` can return anything.
+            return lib.map_infer_mask(arr, f, mask.view("uint8"))
+
+    def _str_map_nan_semantics(
+        self,
+        f,
+        na_value=lib.no_default,
+        dtype: Dtype | None = None,
+        convert: bool = True,
+    ):
+        if dtype is None:
+            dtype = self.dtype
+        if na_value is lib.no_default:
+            if is_bool_dtype(dtype):
+                # NaN propagates as False
+                na_value = False
+            else:
+                na_value = self.dtype.na_value
+
+        mask = isna(self)
+        arr = np.asarray(self)
+
+        if is_integer_dtype(dtype) or is_bool_dtype(dtype):
+            na_value_is_na = isna(na_value)
+            if na_value_is_na:
+                if is_integer_dtype(dtype):
+                    na_value = 0
+                else:
+                    # NaN propagates as False
+                    na_value = False
+
+            result = lib.map_infer_mask(
+                arr,
+                f,
+                mask.view("uint8"),
+                convert=False,
+                na_value=na_value,
+                dtype=np.dtype(cast(type, dtype)),
+            )
+            if na_value_is_na and is_integer_dtype(dtype) and mask.any():
+                # TODO: we could alternatively do this check before map_infer_mask
+                #  and adjust the dtype/na_value we pass there. Which is more
+                #  performant?
+                result = result.astype("float64")
+                result[mask] = np.nan
+
+            return result
+
+        else:
+            return self._str_map_str_or_object(dtype, na_value, arr, f, mask)
+
+    def view(self, dtype: Dtype | None = None) -> ArrayLike:
+        if dtype is not None:
+            raise TypeError("Cannot change data-type for string array.")
+        return super().view(dtype=dtype)
+
+
+# error: Definition of "_concat_same_type" in base class "NDArrayBacked" is
+# incompatible with definition in base class "ExtensionArray"
+class StringArray(BaseStringArray, NumpyExtensionArray):  # type: ignore[misc]
+    """
+    Extension array for string data.
+
+    .. warning::
+
+       StringArray is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Parameters
+    ----------
+    values : array-like
+        The array of data.
+
+        .. warning::
+
+           Currently, this expects an object-dtype ndarray
+           where the elements are Python strings
+           or nan-likes (``None``, ``np.nan``, ``NA``).
+           This may change without warning in the future. Use
+           :meth:`pandas.array` with ``dtype="string"`` for a stable way of
+           creating a `StringArray` from any sequence.
+
+        .. versionchanged:: 1.5.0
+
+           StringArray now accepts array-likes containing
+           nan-likes(``None``, ``np.nan``) for the ``values`` parameter
+           in addition to strings and :attr:`pandas.NA`
+
+    copy : bool, default False
+        Whether to copy the array of data.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    See Also
+    --------
+    :func:`pandas.array`
+        The recommended function for creating a StringArray.
+    Series.str
+        The string methods are available on Series backed by
+        a StringArray.
+
+    Notes
+    -----
+    StringArray returns a BooleanArray for comparison methods.
+
+    Examples
+    --------
+    >>> pd.array(['This is', 'some text', None, 'data.'], dtype="string")
+    
+    ['This is', 'some text', , 'data.']
+    Length: 4, dtype: string
+
+    Unlike arrays instantiated with ``dtype="object"``, ``StringArray``
+    will convert the values to strings.
+
+    >>> pd.array(['1', 1], dtype="object")
+    
+    ['1', 1]
+    Length: 2, dtype: object
+    >>> pd.array(['1', 1], dtype="string")
+    
+    ['1', '1']
+    Length: 2, dtype: string
+
+    However, instantiating StringArrays directly with non-strings will raise an error.
+
+    For comparison methods, `StringArray` returns a :class:`pandas.BooleanArray`:
+
+    >>> pd.array(["a", None, "c"], dtype="string") == "a"
+    
+    [True, , False]
+    Length: 3, dtype: boolean
+    """
+
+    # undo the NumpyExtensionArray hack
+    _typ = "extension"
+    _storage = "python"
+    _na_value: libmissing.NAType | float = libmissing.NA
+
+    def __init__(self, values, copy: bool = False) -> None:
+        values = extract_array(values)
+
+        super().__init__(values, copy=copy)
+        if not isinstance(values, type(self)):
+            self._validate()
+        NDArrayBacked.__init__(
+            self,
+            self._ndarray,
+            StringDtype(storage=self._storage, na_value=self._na_value),
+        )
+
+    def _validate(self):
+        """Validate that we only store NA or strings."""
+        if len(self._ndarray) and not lib.is_string_array(self._ndarray, skipna=True):
+            raise ValueError("StringArray requires a sequence of strings or pandas.NA")
+        if self._ndarray.dtype != "object":
+            raise ValueError(
+                "StringArray requires a sequence of strings or pandas.NA. Got "
+                f"'{self._ndarray.dtype}' dtype instead."
+            )
+        # Check to see if need to convert Na values to pd.NA
+        if self._ndarray.ndim > 2:
+            # Ravel if ndims > 2 b/c no cythonized version available
+            lib.convert_nans_to_NA(self._ndarray.ravel("K"))
+        else:
+            lib.convert_nans_to_NA(self._ndarray)
+
+    def _validate_scalar(self, value):
+        # used by NDArrayBackedExtensionIndex.insert
+        if isna(value):
+            return self.dtype.na_value
+        elif not isinstance(value, str):
+            raise TypeError(
+                f"Invalid value '{value}' for dtype '{self.dtype}'. Value should be a "
+                f"string or missing value, got '{type(value).__name__}' instead."
+            )
+        return value
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy: bool = False):
+        if dtype and not (isinstance(dtype, str) and dtype == "string"):
+            dtype = pandas_dtype(dtype)
+            assert isinstance(dtype, StringDtype) and dtype.storage == "python"
+        else:
+            if using_string_dtype():
+                dtype = StringDtype(storage="python", na_value=np.nan)
+            else:
+                dtype = StringDtype(storage="python")
+
+        from pandas.core.arrays.masked import BaseMaskedArray
+
+        na_value = dtype.na_value
+        if isinstance(scalars, BaseMaskedArray):
+            # avoid costly conversion to object dtype
+            na_values = scalars._mask
+            result = scalars._data
+            result = lib.ensure_string_array(result, copy=copy, convert_na_value=False)
+            result[na_values] = na_value
+
+        else:
+            if lib.is_pyarrow_array(scalars):
+                # pyarrow array; we cannot rely on the "to_numpy" check in
+                #  ensure_string_array because calling scalars.to_numpy would set
+                #  zero_copy_only to True which caused problems see GH#52076
+                scalars = np.array(scalars)
+            # convert non-na-likes to str, and nan-likes to StringDtype().na_value
+            result = lib.ensure_string_array(scalars, na_value=na_value, copy=copy)
+
+        # Manually creating new array avoids the validation step in the __init__, so is
+        # faster. Refactor need for validation?
+        new_string_array = cls.__new__(cls)
+        NDArrayBacked.__init__(new_string_array, result, dtype)
+
+        return new_string_array
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, *, dtype: Dtype | None = None, copy: bool = False
+    ):
+        return cls._from_sequence(strings, dtype=dtype, copy=copy)
+
+    @classmethod
+    def _empty(cls, shape, dtype) -> StringArray:
+        values = np.empty(shape, dtype=object)
+        values[:] = libmissing.NA
+        return cls(values).astype(dtype, copy=False)
+
+    def __arrow_array__(self, type=None):
+        """
+        Convert myself into a pyarrow Array.
+        """
+        import pyarrow as pa
+
+        if type is None:
+            type = pa.string()
+
+        values = self._ndarray.copy()
+        values[self.isna()] = None
+        return pa.array(values, type=type, from_pandas=True)
+
+    def _values_for_factorize(self) -> tuple[np.ndarray, libmissing.NAType | float]:  # type: ignore[override]
+        arr = self._ndarray.copy()
+
+        return arr, self.dtype.na_value
+
+    def _maybe_convert_setitem_value(self, value):
+        """Maybe convert value to be pyarrow compatible."""
+        if lib.is_scalar(value):
+            if isna(value):
+                value = self.dtype.na_value
+            elif not isinstance(value, str):
+                raise TypeError(
+                    f"Invalid value '{value}' for dtype '{self.dtype}'. Value should "
+                    f"be a string or missing value, got '{type(value).__name__}' "
+                    "instead."
+                )
+        else:
+            value = extract_array(value, extract_numpy=True)
+            if not is_array_like(value):
+                value = np.asarray(value, dtype=object)
+            elif isinstance(value.dtype, type(self.dtype)):
+                return value
+            else:
+                # cast categories and friends to arrays to see if values are
+                # compatible, compatibility with arrow backed strings
+                value = np.asarray(value)
+            if len(value) and not lib.is_string_array(value, skipna=True):
+                raise TypeError(
+                    "Invalid value for dtype 'str'. Value should be a "
+                    "string or missing value (or array of those)."
+                )
+        return value
+
+    def __setitem__(self, key, value) -> None:
+        value = self._maybe_convert_setitem_value(value)
+
+        key = check_array_indexer(self, key)
+        scalar_key = lib.is_scalar(key)
+        scalar_value = lib.is_scalar(value)
+        if scalar_key and not scalar_value:
+            raise ValueError("setting an array element with a sequence.")
+
+        if not scalar_value:
+            if value.dtype == self.dtype:
+                value = value._ndarray
+            else:
+                value = np.asarray(value)
+                mask = isna(value)
+                if mask.any():
+                    value = value.copy()
+                    value[isna(value)] = self.dtype.na_value
+
+        super().__setitem__(key, value)
+
+    def _putmask(self, mask: npt.NDArray[np.bool_], value) -> None:
+        # the super() method NDArrayBackedExtensionArray._putmask uses
+        # np.putmask which doesn't properly handle None/pd.NA, so using the
+        # base class implementation that uses __setitem__
+        ExtensionArray._putmask(self, mask, value)
+
+    def _where(self, mask: npt.NDArray[np.bool_], value) -> Self:
+        # the super() method NDArrayBackedExtensionArray._where uses
+        # np.putmask which doesn't properly handle None/pd.NA, so using the
+        # base class implementation that uses __setitem__
+        return ExtensionArray._where(self, mask, value)
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        if isinstance(values, BaseStringArray) or (
+            isinstance(values, ExtensionArray) and is_string_dtype(values.dtype)
+        ):
+            values = values.astype(self.dtype, copy=False)
+        else:
+            if not lib.is_string_array(np.asarray(values), skipna=True):
+                values = np.array(
+                    [val for val in values if isinstance(val, str) or isna(val)],
+                    dtype=object,
+                )
+                if not len(values):
+                    return np.zeros(self.shape, dtype=bool)
+
+            values = self._from_sequence(values, dtype=self.dtype)
+
+        return isin(np.asarray(self), np.asarray(values))
+
+    def astype(self, dtype, copy: bool = True):
+        dtype = pandas_dtype(dtype)
+
+        if dtype == self.dtype:
+            if copy:
+                return self.copy()
+            return self
+
+        elif isinstance(dtype, IntegerDtype):
+            arr = self._ndarray.copy()
+            mask = self.isna()
+            arr[mask] = 0
+            values = arr.astype(dtype.numpy_dtype)
+            return IntegerArray(values, mask, copy=False)
+        elif isinstance(dtype, FloatingDtype):
+            arr = self.copy()
+            mask = self.isna()
+            arr[mask] = "0"
+            values = arr.astype(dtype.numpy_dtype)
+            return FloatingArray(values, mask, copy=False)
+        elif isinstance(dtype, ExtensionDtype):
+            # Skip the NumpyExtensionArray.astype method
+            return ExtensionArray.astype(self, dtype, copy)
+        elif np.issubdtype(dtype, np.floating):
+            arr = self._ndarray.copy()
+            mask = self.isna()
+            arr[mask] = 0
+            values = arr.astype(dtype)
+            values[mask] = np.nan
+            return values
+
+        return super().astype(dtype, copy)
+
+    def _reduce(
+        self,
+        name: str,
+        *,
+        skipna: bool = True,
+        keepdims: bool = False,
+        axis: AxisInt | None = 0,
+        **kwargs,
+    ):
+        if self.dtype.na_value is np.nan and name in ["any", "all"]:
+            if name == "any":
+                return nanops.nanany(self._ndarray, skipna=skipna)
+            else:
+                return nanops.nanall(self._ndarray, skipna=skipna)
+
+        if name in ["min", "max", "argmin", "argmax", "sum"]:
+            result = getattr(self, name)(skipna=skipna, axis=axis, **kwargs)
+            if keepdims:
+                return self._from_sequence([result], dtype=self.dtype)
+            return result
+        raise TypeError(f"Cannot perform reduction '{name}' with string dtype")
+
+    def _accumulate(self, name: str, *, skipna: bool = True, **kwargs) -> StringArray:
+        """
+        Return an ExtensionArray performing an accumulation operation.
+
+        The underlying data type might change.
+
+        Parameters
+        ----------
+        name : str
+            Name of the function, supported values are:
+            - cummin
+            - cummax
+            - cumsum
+            - cumprod
+        skipna : bool, default True
+            If True, skip NA values.
+        **kwargs
+            Additional keyword arguments passed to the accumulation function.
+            Currently, there is no supported kwarg.
+
+        Returns
+        -------
+        array
+
+        Raises
+        ------
+        NotImplementedError : subclass does not define accumulations
+        """
+        if name == "cumprod":
+            msg = f"operation '{name}' not supported for dtype '{self.dtype}'"
+            raise TypeError(msg)
+
+        # We may need to strip out trailing NA values
+        tail: np.ndarray | None = None
+        na_mask: np.ndarray | None = None
+        ndarray = self._ndarray
+        np_func = {
+            "cumsum": np.cumsum,
+            "cummin": np.minimum.accumulate,
+            "cummax": np.maximum.accumulate,
+        }[name]
+
+        if self._hasna:
+            na_mask = cast("npt.NDArray[np.bool_]", isna(ndarray))
+            if np.all(na_mask):
+                return type(self)(ndarray)
+            if skipna:
+                if name == "cumsum":
+                    ndarray = np.where(na_mask, "", ndarray)
+                else:
+                    # We can retain the running min/max by forward/backward filling.
+                    ndarray = ndarray.copy()
+                    missing.pad_or_backfill_inplace(
+                        ndarray,
+                        method="pad",
+                        axis=0,
+                    )
+                    missing.pad_or_backfill_inplace(
+                        ndarray,
+                        method="backfill",
+                        axis=0,
+                    )
+            else:
+                # When not skipping NA values, the result should be null from
+                # the first NA value onward.
+                idx = np.argmax(na_mask)
+                tail = np.empty(len(ndarray) - idx, dtype="object")
+                tail[:] = self.dtype.na_value
+                ndarray = ndarray[:idx]
+
+        # mypy: Cannot call function of unknown type
+        np_result = np_func(ndarray)  # type: ignore[operator]
+
+        if tail is not None:
+            np_result = np.hstack((np_result, tail))
+        elif na_mask is not None:
+            # Argument 2 to "where" has incompatible type "NAType | float"
+            np_result = np.where(na_mask, self.dtype.na_value, np_result)  # type: ignore[arg-type]
+
+        result = type(self)(np_result)
+        return result
+
+    def _wrap_reduction_result(self, axis: AxisInt | None, result) -> Any:
+        if self.dtype.na_value is np.nan and result is libmissing.NA:
+            # the masked_reductions use pd.NA -> convert to np.nan
+            return np.nan
+        return super()._wrap_reduction_result(axis, result)
+
+    def min(self, axis=None, skipna: bool = True, **kwargs) -> Scalar:
+        nv.validate_min((), kwargs)
+        result = masked_reductions.min(
+            values=self.to_numpy(), mask=self.isna(), skipna=skipna
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def max(self, axis=None, skipna: bool = True, **kwargs) -> Scalar:
+        nv.validate_max((), kwargs)
+        result = masked_reductions.max(
+            values=self.to_numpy(), mask=self.isna(), skipna=skipna
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def sum(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        skipna: bool = True,
+        min_count: int = 0,
+        **kwargs,
+    ) -> Scalar:
+        nv.validate_sum((), kwargs)
+        result = masked_reductions.sum(
+            values=self._ndarray, mask=self.isna(), skipna=skipna
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        from pandas.core.algorithms import value_counts_internal as value_counts
+
+        result = value_counts(self._ndarray, dropna=dropna).astype("Int64")
+        result = value_counts(self._ndarray, sort=False, dropna=dropna)
+        result.index = result.index.astype(self.dtype)
+
+        if self.dtype.na_value is libmissing.NA:
+            result = result.astype("Int64")
+        return result
+
+    def memory_usage(self, deep: bool = False) -> int:
+        result = self._ndarray.nbytes
+        if deep:
+            return result + lib.memory_usage_of_objects(self._ndarray)
+        return result
+
+    @doc(ExtensionArray.searchsorted)
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        if self._hasna:
+            raise ValueError(
+                "searchsorted requires array to be sorted, which is impossible "
+                "with NAs present."
+            )
+        return super().searchsorted(value=value, side=side, sorter=sorter)
+
+    def _cmp_method(self, other, op):
+        from pandas.arrays import (
+            ArrowExtensionArray,
+            BooleanArray,
+        )
+
+        if (
+            isinstance(other, BaseStringArray)
+            and self.dtype.na_value is not libmissing.NA
+            and other.dtype.na_value is libmissing.NA
+        ):
+            # NA has priority of NaN semantics
+            return NotImplemented
+
+        if isinstance(other, ArrowExtensionArray):
+            if isinstance(other, BaseStringArray):
+                # pyarrow storage has priority over python storage
+                # (except if we have NA semantics and other not)
+                if not (
+                    self.dtype.na_value is libmissing.NA
+                    and other.dtype.na_value is not libmissing.NA
+                ):
+                    return NotImplemented
+            else:
+                return NotImplemented
+
+        if isinstance(other, StringArray):
+            other = other._ndarray
+
+        mask = isna(self) | isna(other)
+        valid = ~mask
+
+        if lib.is_list_like(other):
+            if len(other) != len(self):
+                # prevent improper broadcasting when other is 2D
+                raise ValueError(
+                    f"Lengths of operands do not match: {len(self)} != {len(other)}"
+                )
+
+            # for array-likes, first filter out NAs before converting to numpy
+            if not is_array_like(other):
+                other = np.asarray(other)
+            other = other[valid]
+
+        if op.__name__ in ops.ARITHMETIC_BINOPS:
+            result = np.empty_like(self._ndarray, dtype="object")
+            result[mask] = self.dtype.na_value
+            result[valid] = op(self._ndarray[valid], other)
+            if isinstance(other, Path):
+                # GH#61940
+                return result
+            return self._from_backing_data(result)
+        else:
+            # logical
+            result = np.zeros(len(self._ndarray), dtype="bool")
+            result[valid] = op(self._ndarray[valid], other)
+            res_arr = BooleanArray(result, mask)
+            if self.dtype.na_value is np.nan:
+                if op == operator.ne:
+                    return res_arr.to_numpy(np.bool_, na_value=True)
+                else:
+                    return res_arr.to_numpy(np.bool_, na_value=False)
+            return res_arr
+
+    _arith_method = _cmp_method
+
+
+class StringArrayNumpySemantics(StringArray):
+    _storage = "python"
+    _na_value = np.nan
+
+    def _validate(self) -> None:
+        """Validate that we only store NaN or strings."""
+        if len(self._ndarray) and not lib.is_string_array(self._ndarray, skipna=True):
+            raise ValueError(
+                "StringArrayNumpySemantics requires a sequence of strings or NaN"
+            )
+        if self._ndarray.dtype != "object":
+            raise ValueError(
+                "StringArrayNumpySemantics requires a sequence of strings or NaN. Got "
+                f"'{self._ndarray.dtype}' dtype instead."
+            )
+        # TODO validate or force NA/None to NaN
+
+    @classmethod
+    def _from_sequence(
+        cls, scalars, *, dtype: Dtype | None = None, copy: bool = False
+    ) -> Self:
+        if dtype is None:
+            dtype = StringDtype(storage="python", na_value=np.nan)
+        return super()._from_sequence(scalars, dtype=dtype, copy=copy)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_arrow.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_arrow.py
new file mode 100644
index 0000000000000000000000000000000000000000..f9fd74cbd76b1262f6cc13f04486ba89026ab959
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/string_arrow.py
@@ -0,0 +1,555 @@
+from __future__ import annotations
+
+import operator
+import re
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Union,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas.compat import (
+    pa_version_under10p1,
+    pa_version_under13p0,
+    pa_version_under16p0,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_scalar,
+    pandas_dtype,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.arrays._arrow_string_mixins import ArrowStringArrayMixin
+from pandas.core.arrays.arrow import ArrowExtensionArray
+from pandas.core.arrays.boolean import BooleanDtype
+from pandas.core.arrays.floating import Float64Dtype
+from pandas.core.arrays.integer import Int64Dtype
+from pandas.core.arrays.numeric import NumericDtype
+from pandas.core.arrays.string_ import (
+    BaseStringArray,
+    StringDtype,
+)
+from pandas.core.strings.object_array import ObjectStringArrayMixin
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+    import pyarrow.compute as pc
+
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        ArrayLike,
+        Dtype,
+        Scalar,
+        Self,
+        npt,
+    )
+
+    from pandas import Series
+
+
+ArrowStringScalarOrNAT = Union[str, libmissing.NAType]
+
+
+def _chk_pyarrow_available() -> None:
+    if pa_version_under10p1:
+        msg = "pyarrow>=10.0.1 is required for PyArrow backed ArrowExtensionArray."
+        raise ImportError(msg)
+
+
+def _is_string_view(typ):
+    return not pa_version_under16p0 and pa.types.is_string_view(typ)
+
+
+# TODO: Inherit directly from BaseStringArrayMethods. Currently we inherit from
+# ObjectStringArrayMixin because we want to have the object-dtype based methods as
+# fallback for the ones that pyarrow doesn't yet support
+
+
+class ArrowStringArray(ObjectStringArrayMixin, ArrowExtensionArray, BaseStringArray):
+    """
+    Extension array for string data in a ``pyarrow.ChunkedArray``.
+
+    .. warning::
+
+       ArrowStringArray is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    Parameters
+    ----------
+    values : pyarrow.Array or pyarrow.ChunkedArray
+        The array of data.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    See Also
+    --------
+    :func:`pandas.array`
+        The recommended function for creating a ArrowStringArray.
+    Series.str
+        The string methods are available on Series backed by
+        a ArrowStringArray.
+
+    Notes
+    -----
+    ArrowStringArray returns a BooleanArray for comparison methods.
+
+    Examples
+    --------
+    >>> pd.array(['This is', 'some text', None, 'data.'], dtype="string[pyarrow]")
+    
+    ['This is', 'some text', , 'data.']
+    Length: 4, dtype: string
+    """
+
+    # error: Incompatible types in assignment (expression has type "StringDtype",
+    # base class "ArrowExtensionArray" defined the type as "ArrowDtype")
+    _dtype: StringDtype  # type: ignore[assignment]
+    _storage = "pyarrow"
+    _na_value: libmissing.NAType | float = libmissing.NA
+
+    def __init__(self, values) -> None:
+        _chk_pyarrow_available()
+        if isinstance(values, (pa.Array, pa.ChunkedArray)) and (
+            pa.types.is_string(values.type)
+            or _is_string_view(values.type)
+            or (
+                pa.types.is_dictionary(values.type)
+                and (
+                    pa.types.is_string(values.type.value_type)
+                    or pa.types.is_large_string(values.type.value_type)
+                    or _is_string_view(values.type.value_type)
+                )
+            )
+        ):
+            values = pc.cast(values, pa.large_string())
+
+        super().__init__(values)
+        self._dtype = StringDtype(storage=self._storage, na_value=self._na_value)
+
+        if not pa.types.is_large_string(self._pa_array.type):
+            raise ValueError(
+                "ArrowStringArray requires a PyArrow (chunked) array of "
+                "large_string type"
+            )
+
+    @classmethod
+    def _box_pa_scalar(cls, value, pa_type: pa.DataType | None = None) -> pa.Scalar:
+        pa_scalar = super()._box_pa_scalar(value, pa_type)
+        if pa.types.is_string(pa_scalar.type) and pa_type is None:
+            pa_scalar = pc.cast(pa_scalar, pa.large_string())
+        return pa_scalar
+
+    @classmethod
+    def _box_pa_array(
+        cls, value, pa_type: pa.DataType | None = None, copy: bool = False
+    ) -> pa.Array | pa.ChunkedArray:
+        pa_array = super()._box_pa_array(value, pa_type)
+        if pa.types.is_string(pa_array.type) and pa_type is None:
+            pa_array = pc.cast(pa_array, pa.large_string())
+        return pa_array
+
+    def __len__(self) -> int:
+        """
+        Length of this array.
+
+        Returns
+        -------
+        length : int
+        """
+        return len(self._pa_array)
+
+    @classmethod
+    def _from_sequence(cls, scalars, *, dtype: Dtype | None = None, copy: bool = False):
+        from pandas.core.arrays.masked import BaseMaskedArray
+
+        _chk_pyarrow_available()
+
+        if dtype and not (isinstance(dtype, str) and dtype == "string"):
+            dtype = pandas_dtype(dtype)
+            assert isinstance(dtype, StringDtype) and dtype.storage == "pyarrow"
+
+        if isinstance(scalars, BaseMaskedArray):
+            # avoid costly conversion to object dtype in ensure_string_array and
+            # numerical issues with Float32Dtype
+            na_values = scalars._mask
+            result = scalars._data
+            result = lib.ensure_string_array(result, copy=copy, convert_na_value=False)
+            return cls(pa.array(result, mask=na_values, type=pa.large_string()))
+        elif isinstance(scalars, (pa.Array, pa.ChunkedArray)):
+            return cls(pc.cast(scalars, pa.large_string()))
+
+        # convert non-na-likes to str
+        result = lib.ensure_string_array(scalars, copy=copy)
+        return cls(pa.array(result, type=pa.large_string(), from_pandas=True))
+
+    @classmethod
+    def _from_sequence_of_strings(
+        cls, strings, dtype: Dtype | None = None, copy: bool = False
+    ):
+        return cls._from_sequence(strings, dtype=dtype, copy=copy)
+
+    @property
+    def dtype(self) -> StringDtype:  # type: ignore[override]
+        """
+        An instance of 'string[pyarrow]'.
+        """
+        return self._dtype
+
+    def insert(self, loc: int, item) -> ArrowStringArray:
+        if self.dtype.na_value is np.nan and item is np.nan:
+            item = libmissing.NA
+        if not isinstance(item, str) and item is not libmissing.NA:
+            raise TypeError(
+                f"Invalid value '{item}' for dtype 'str'. Value should be a "
+                f"string or missing value, got '{type(item).__name__}' instead."
+            )
+        return super().insert(loc, item)
+
+    def _convert_bool_result(self, values, na=lib.no_default, method_name=None):
+        if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # GH#59561
+            warnings.warn(
+                f"Allowing a non-bool 'na' in obj.str.{method_name} is deprecated "
+                "and will raise in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            na = bool(na)
+
+        if self.dtype.na_value is np.nan:
+            if na is lib.no_default or isna(na):
+                # NaN propagates as False
+                values = values.fill_null(False)
+            else:
+                values = values.fill_null(na)
+            return values.to_numpy()
+        else:
+            if na is not lib.no_default and not isna(
+                na
+            ):  # pyright: ignore [reportGeneralTypeIssues]
+                values = values.fill_null(na)
+        return BooleanDtype().__from_arrow__(values)
+
+    def _maybe_convert_setitem_value(self, value):
+        """Maybe convert value to be pyarrow compatible."""
+        if is_scalar(value):
+            if isna(value):
+                value = None
+            elif not isinstance(value, str):
+                raise TypeError(
+                    f"Invalid value '{value}' for dtype 'str'. Value should be a "
+                    f"string or missing value, got '{type(value).__name__}' instead."
+                )
+        else:
+            value = np.array(value, dtype=object, copy=True)
+            value[isna(value)] = None
+            for v in value:
+                if not (v is None or isinstance(v, str)):
+                    raise TypeError(
+                        "Invalid value for dtype 'str'. Value should be a "
+                        "string or missing value (or array of those)."
+                    )
+        return super()._maybe_convert_setitem_value(value)
+
+    def isin(self, values: ArrayLike) -> npt.NDArray[np.bool_]:
+        value_set = [
+            pa_scalar.as_py()
+            for pa_scalar in [pa.scalar(value, from_pandas=True) for value in values]
+            if pa_scalar.type in (pa.string(), pa.null(), pa.large_string())
+        ]
+
+        # short-circuit to return all False array.
+        if not len(value_set):
+            return np.zeros(len(self), dtype=bool)
+
+        result = pc.is_in(
+            self._pa_array, value_set=pa.array(value_set, type=self._pa_array.type)
+        )
+        # pyarrow 2.0.0 returned nulls, so we explicily specify dtype to convert nulls
+        # to False
+        return np.array(result, dtype=np.bool_)
+
+    def astype(self, dtype, copy: bool = True):
+        dtype = pandas_dtype(dtype)
+
+        if dtype == self.dtype:
+            if copy:
+                return self.copy()
+            return self
+        elif isinstance(dtype, NumericDtype):
+            data = self._pa_array.cast(pa.from_numpy_dtype(dtype.numpy_dtype))
+            return dtype.__from_arrow__(data)
+        elif isinstance(dtype, np.dtype) and np.issubdtype(dtype, np.floating):
+            return self.to_numpy(dtype=dtype, na_value=np.nan)
+
+        return super().astype(dtype, copy=copy)
+
+    @property
+    def _data(self):
+        # dask accesses ._data directlys
+        warnings.warn(
+            f"{type(self).__name__}._data is a deprecated and will be removed "
+            "in a future version, use ._pa_array instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._pa_array
+
+    # ------------------------------------------------------------------------
+    # String methods interface
+
+    _str_isalnum = ArrowStringArrayMixin._str_isalnum
+    _str_isalpha = ArrowStringArrayMixin._str_isalpha
+    _str_isdecimal = ArrowStringArrayMixin._str_isdecimal
+    _str_isdigit = ArrowStringArrayMixin._str_isdigit
+    _str_islower = ArrowStringArrayMixin._str_islower
+    _str_isnumeric = ArrowStringArrayMixin._str_isnumeric
+    _str_isspace = ArrowStringArrayMixin._str_isspace
+    _str_istitle = ArrowStringArrayMixin._str_istitle
+    _str_isupper = ArrowStringArrayMixin._str_isupper
+
+    _str_map = BaseStringArray._str_map
+    _str_startswith = ArrowStringArrayMixin._str_startswith
+    _str_endswith = ArrowStringArrayMixin._str_endswith
+    _str_pad = ArrowStringArrayMixin._str_pad
+    _str_lower = ArrowStringArrayMixin._str_lower
+    _str_upper = ArrowStringArrayMixin._str_upper
+    _str_strip = ArrowStringArrayMixin._str_strip
+    _str_lstrip = ArrowStringArrayMixin._str_lstrip
+    _str_rstrip = ArrowStringArrayMixin._str_rstrip
+    _str_removesuffix = ArrowStringArrayMixin._str_removesuffix
+    _str_get = ArrowStringArrayMixin._str_get
+    _str_capitalize = ArrowStringArrayMixin._str_capitalize
+    _str_title = ArrowStringArrayMixin._str_title
+    _str_swapcase = ArrowStringArrayMixin._str_swapcase
+    _str_slice_replace = ArrowStringArrayMixin._str_slice_replace
+    _str_len = ArrowStringArrayMixin._str_len
+    _str_slice = ArrowStringArrayMixin._str_slice
+
+    @staticmethod
+    def _is_re_pattern_with_flags(pat: str | re.Pattern) -> bool:
+        # check if `pat` is a compiled regex pattern with flags that are not
+        # supported by pyarrow
+        return (
+            isinstance(pat, re.Pattern)
+            and (pat.flags & ~(re.IGNORECASE | re.UNICODE)) != 0
+        )
+
+    @staticmethod
+    def _preprocess_re_pattern(pat: re.Pattern, case: bool) -> tuple[str, bool, int]:
+        pattern = pat.pattern
+        flags = pat.flags
+        # flags is not supported by pyarrow, but `case` is -> extract and remove
+        if flags & re.IGNORECASE:
+            case = False
+            flags = flags & ~re.IGNORECASE
+        # when creating a pattern with re.compile and a string, it automatically
+        # gets a UNICODE flag, while pyarrow assumes unicode for strings anyway
+        flags = flags & ~re.UNICODE
+        return pattern, case, flags
+
+    def _str_contains(
+        self,
+        pat,
+        case: bool = True,
+        flags: int = 0,
+        na=lib.no_default,
+        regex: bool = True,
+    ):
+        if flags or self._is_re_pattern_with_flags(pat):
+            return super()._str_contains(pat, case, flags, na, regex)
+        if isinstance(pat, re.Pattern):
+            # TODO flags passed separately by user are ignored
+            pat, case, flags = self._preprocess_re_pattern(pat, case)
+
+        return ArrowStringArrayMixin._str_contains(self, pat, case, flags, na, regex)
+
+    def _str_match(
+        self,
+        pat: str | re.Pattern,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if flags or self._is_re_pattern_with_flags(pat):
+            return super()._str_match(pat, case, flags, na)
+        if isinstance(pat, re.Pattern):
+            pat, case, flags = self._preprocess_re_pattern(pat, case)
+
+        return ArrowStringArrayMixin._str_match(self, pat, case, flags, na)
+
+    def _str_fullmatch(
+        self,
+        pat: str | re.Pattern,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if flags or self._is_re_pattern_with_flags(pat):
+            return super()._str_fullmatch(pat, case, flags, na)
+        if isinstance(pat, re.Pattern):
+            pat, case, flags = self._preprocess_re_pattern(pat, case)
+
+        return ArrowStringArrayMixin._str_fullmatch(self, pat, case, flags, na)
+
+    def _str_replace(
+        self,
+        pat: str | re.Pattern,
+        repl: str | Callable,
+        n: int = -1,
+        case: bool = True,
+        flags: int = 0,
+        regex: bool = True,
+    ):
+        if (
+            isinstance(pat, re.Pattern)
+            or callable(repl)
+            or not case
+            or flags
+            or (  # substitution contains a named group pattern
+                # https://docs.python.org/3/library/re.html
+                isinstance(repl, str)
+                and (r"\g<" in repl or re.search(r"\\\d", repl) is not None)
+            )
+        ):
+            return super()._str_replace(pat, repl, n, case, flags, regex)
+
+        return ArrowStringArrayMixin._str_replace(
+            self, pat, repl, n, case, flags, regex
+        )
+
+    def _str_repeat(self, repeats: int | Sequence[int]):
+        if not isinstance(repeats, int):
+            return super()._str_repeat(repeats)
+        else:
+            return ArrowExtensionArray._str_repeat(self, repeats=repeats)
+
+    def _str_removeprefix(self, prefix: str):
+        if not pa_version_under13p0:
+            return ArrowStringArrayMixin._str_removeprefix(self, prefix)
+        return super()._str_removeprefix(prefix)
+
+    def _str_count(self, pat: str, flags: int = 0):
+        if flags:
+            return super()._str_count(pat, flags)
+        result = pc.count_substring_regex(self._pa_array, pat)
+        return self._convert_int_result(result)
+
+    def _str_find(self, sub: str, start: int = 0, end: int | None = None):
+        if (
+            pa_version_under13p0
+            and not (start != 0 and end is not None)
+            and not (start == 0 and end is None)
+        ):
+            # GH#59562
+            return super()._str_find(sub, start, end)
+        return ArrowStringArrayMixin._str_find(self, sub, start, end)
+
+    def _str_get_dummies(self, sep: str = "|"):
+        dummies_pa, labels = ArrowExtensionArray(self._pa_array)._str_get_dummies(sep)
+        if len(labels) == 0:
+            return np.empty(shape=(0, 0), dtype=np.int64), labels
+        dummies = np.vstack(dummies_pa.to_numpy())
+        return dummies.astype(np.int64, copy=False), labels
+
+    def _convert_int_result(self, result):
+        if self.dtype.na_value is np.nan:
+            if isinstance(result, pa.Array):
+                result = result.to_numpy(zero_copy_only=False)
+            else:
+                result = result.to_numpy()
+            if result.dtype == np.int32:
+                result = result.astype(np.int64)
+            return result
+
+        return Int64Dtype().__from_arrow__(result)
+
+    def _convert_rank_result(self, result):
+        if self.dtype.na_value is np.nan:
+            if isinstance(result, pa.Array):
+                result = result.to_numpy(zero_copy_only=False)
+            else:
+                result = result.to_numpy()
+            return result.astype("float64", copy=False)
+
+        return Float64Dtype().__from_arrow__(result)
+
+    def _reduce(
+        self, name: str, *, skipna: bool = True, keepdims: bool = False, **kwargs
+    ):
+        if self.dtype.na_value is np.nan and name in ["any", "all"]:
+            if not skipna:
+                nas = pc.is_null(self._pa_array)
+                arr = pc.or_kleene(nas, pc.not_equal(self._pa_array, ""))
+            else:
+                arr = pc.not_equal(self._pa_array, "")
+            result = ArrowExtensionArray(arr)._reduce(
+                name, skipna=skipna, keepdims=keepdims, **kwargs
+            )
+            if keepdims:
+                # ArrowExtensionArray will return a length-1 bool[pyarrow] array
+                return result.astype(np.bool_)
+            return result
+
+        if name in ("min", "max", "sum", "argmin", "argmax"):
+            result = self._reduce_calc(name, skipna=skipna, keepdims=keepdims, **kwargs)
+        else:
+            raise TypeError(f"Cannot perform reduction '{name}' with string dtype")
+
+        if name in ("argmin", "argmax") and isinstance(result, pa.Array):
+            return self._convert_int_result(result)
+        elif isinstance(result, pa.Array):
+            return type(self)(result)
+        else:
+            return result
+
+    def value_counts(self, dropna: bool = True) -> Series:
+        result = super().value_counts(dropna=dropna)
+        if self.dtype.na_value is np.nan:
+            res_values = result._values.to_numpy()
+            return result._constructor(
+                res_values, index=result.index, name=result.name, copy=False
+            )
+        return result
+
+    def _cmp_method(self, other, op):
+        if (
+            isinstance(other, (BaseStringArray, ArrowExtensionArray))
+            and self.dtype.na_value is not libmissing.NA
+            and other.dtype.na_value is libmissing.NA
+        ):
+            # NA has priority of NaN semantics
+            return NotImplemented
+
+        result = super()._cmp_method(other, op)
+        if self.dtype.na_value is np.nan:
+            if op == operator.ne:
+                return result.to_numpy(np.bool_, na_value=True)
+            else:
+                return result.to_numpy(np.bool_, na_value=False)
+        return result
+
+    def __pos__(self) -> Self:
+        raise TypeError(f"bad operand type for unary +: '{self.dtype}'")
+
+
+class ArrowStringArrayNumpySemantics(ArrowStringArray):
+    _na_value = np.nan
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/arrays/timedeltas.py b/.venv/lib/python3.13/site-packages/pandas/core/arrays/timedeltas.py
new file mode 100644
index 0000000000000000000000000000000000000000..d4caec4bfd58a653c3d4af9e550dbda3dc50264a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/arrays/timedeltas.py
@@ -0,0 +1,1185 @@
+from __future__ import annotations
+
+from datetime import timedelta
+import operator
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    tslibs,
+)
+from pandas._libs.tslibs import (
+    NaT,
+    NaTType,
+    Tick,
+    Timedelta,
+    astype_overflowsafe,
+    get_supported_dtype,
+    iNaT,
+    is_supported_dtype,
+    periods_per_second,
+)
+from pandas._libs.tslibs.conversion import cast_from_unit_vectorized
+from pandas._libs.tslibs.fields import (
+    get_timedelta_days,
+    get_timedelta_field,
+)
+from pandas._libs.tslibs.timedeltas import (
+    array_to_timedelta64,
+    floordiv_object_array,
+    ints_to_pytimedelta,
+    parse_timedelta_unit,
+    truediv_object_array,
+)
+from pandas.compat.numpy import function as nv
+from pandas.util._validators import validate_endpoints
+
+from pandas.core.dtypes.common import (
+    TD64NS_DTYPE,
+    is_float_dtype,
+    is_integer_dtype,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import (
+    nanops,
+    roperator,
+)
+from pandas.core.array_algos import datetimelike_accumulations
+from pandas.core.arrays import datetimelike as dtl
+from pandas.core.arrays._ranges import generate_regular_range
+import pandas.core.common as com
+from pandas.core.ops.common import unpack_zerodim_and_defer
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pandas._typing import (
+        AxisInt,
+        DateTimeErrorChoices,
+        DtypeObj,
+        NpDtype,
+        Self,
+        npt,
+    )
+
+    from pandas import DataFrame
+
+import textwrap
+
+
+def _field_accessor(name: str, alias: str, docstring: str):
+    def f(self) -> np.ndarray:
+        values = self.asi8
+        if alias == "days":
+            result = get_timedelta_days(values, reso=self._creso)
+        else:
+            # error: Incompatible types in assignment (
+            # expression has type "ndarray[Any, dtype[signedinteger[_32Bit]]]",
+            # variable has type "ndarray[Any, dtype[signedinteger[_64Bit]]]
+            result = get_timedelta_field(values, alias, reso=self._creso)  # type: ignore[assignment]
+        if self._hasna:
+            result = self._maybe_mask_results(
+                result, fill_value=None, convert="float64"
+            )
+
+        return result
+
+    f.__name__ = name
+    f.__doc__ = f"\n{docstring}\n"
+    return property(f)
+
+
+class TimedeltaArray(dtl.TimelikeOps):
+    """
+    Pandas ExtensionArray for timedelta data.
+
+    .. warning::
+
+       TimedeltaArray is currently experimental, and its API may change
+       without warning. In particular, :attr:`TimedeltaArray.dtype` is
+       expected to change to be an instance of an ``ExtensionDtype``
+       subclass.
+
+    Parameters
+    ----------
+    values : array-like
+        The timedelta data.
+
+    dtype : numpy.dtype
+        Currently, only ``numpy.dtype("timedelta64[ns]")`` is accepted.
+    freq : Offset, optional
+    copy : bool, default False
+        Whether to copy the underlying array of data.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.arrays.TimedeltaArray._from_sequence(pd.TimedeltaIndex(['1h', '2h']))
+    
+    ['0 days 01:00:00', '0 days 02:00:00']
+    Length: 2, dtype: timedelta64[ns]
+    """
+
+    _typ = "timedeltaarray"
+    _internal_fill_value = np.timedelta64("NaT", "ns")
+    _recognized_scalars = (timedelta, np.timedelta64, Tick)
+    _is_recognized_dtype = lambda x: lib.is_np_dtype(x, "m")
+    _infer_matches = ("timedelta", "timedelta64")
+
+    @property
+    def _scalar_type(self) -> type[Timedelta]:
+        return Timedelta
+
+    __array_priority__ = 1000
+    # define my properties & methods for delegation
+    _other_ops: list[str] = []
+    _bool_ops: list[str] = []
+    _object_ops: list[str] = ["freq"]
+    _field_ops: list[str] = ["days", "seconds", "microseconds", "nanoseconds"]
+    _datetimelike_ops: list[str] = _field_ops + _object_ops + _bool_ops + ["unit"]
+    _datetimelike_methods: list[str] = [
+        "to_pytimedelta",
+        "total_seconds",
+        "round",
+        "floor",
+        "ceil",
+        "as_unit",
+    ]
+
+    # Note: ndim must be defined to ensure NaT.__richcmp__(TimedeltaArray)
+    #  operates pointwise.
+
+    def _box_func(self, x: np.timedelta64) -> Timedelta | NaTType:
+        y = x.view("i8")
+        if y == NaT._value:
+            return NaT
+        return Timedelta._from_value_and_reso(y, reso=self._creso)
+
+    @property
+    # error: Return type "dtype" of "dtype" incompatible with return type
+    # "ExtensionDtype" in supertype "ExtensionArray"
+    def dtype(self) -> np.dtype[np.timedelta64]:  # type: ignore[override]
+        """
+        The dtype for the TimedeltaArray.
+
+        .. warning::
+
+           A future version of pandas will change dtype to be an instance
+           of a :class:`pandas.api.extensions.ExtensionDtype` subclass,
+           not a ``numpy.dtype``.
+
+        Returns
+        -------
+        numpy.dtype
+        """
+        return self._ndarray.dtype
+
+    # ----------------------------------------------------------------
+    # Constructors
+
+    _freq = None
+    _default_dtype = TD64NS_DTYPE  # used in TimeLikeOps.__init__
+
+    @classmethod
+    def _validate_dtype(cls, values, dtype):
+        # used in TimeLikeOps.__init__
+        dtype = _validate_td64_dtype(dtype)
+        _validate_td64_dtype(values.dtype)
+        if dtype != values.dtype:
+            raise ValueError("Values resolution does not match dtype.")
+        return dtype
+
+    # error: Signature of "_simple_new" incompatible with supertype "NDArrayBacked"
+    @classmethod
+    def _simple_new(  # type: ignore[override]
+        cls,
+        values: npt.NDArray[np.timedelta64],
+        freq: Tick | None = None,
+        dtype: np.dtype[np.timedelta64] = TD64NS_DTYPE,
+    ) -> Self:
+        # Require td64 dtype, not unit-less, matching values.dtype
+        assert lib.is_np_dtype(dtype, "m")
+        assert not tslibs.is_unitless(dtype)
+        assert isinstance(values, np.ndarray), type(values)
+        assert dtype == values.dtype
+        assert freq is None or isinstance(freq, Tick)
+
+        result = super()._simple_new(values=values, dtype=dtype)
+        result._freq = freq
+        return result
+
+    @classmethod
+    def _from_sequence(cls, data, *, dtype=None, copy: bool = False) -> Self:
+        if dtype:
+            dtype = _validate_td64_dtype(dtype)
+
+        data, freq = sequence_to_td64ns(data, copy=copy, unit=None)
+
+        if dtype is not None:
+            data = astype_overflowsafe(data, dtype=dtype, copy=False)
+
+        return cls._simple_new(data, dtype=data.dtype, freq=freq)
+
+    @classmethod
+    def _from_sequence_not_strict(
+        cls,
+        data,
+        *,
+        dtype=None,
+        copy: bool = False,
+        freq=lib.no_default,
+        unit=None,
+    ) -> Self:
+        """
+        _from_sequence_not_strict but without responsibility for finding the
+        result's `freq`.
+        """
+        if dtype:
+            dtype = _validate_td64_dtype(dtype)
+
+        assert unit not in ["Y", "y", "M"]  # caller is responsible for checking
+
+        data, inferred_freq = sequence_to_td64ns(data, copy=copy, unit=unit)
+
+        if dtype is not None:
+            data = astype_overflowsafe(data, dtype=dtype, copy=False)
+
+        result = cls._simple_new(data, dtype=data.dtype, freq=inferred_freq)
+
+        result._maybe_pin_freq(freq, {})
+        return result
+
+    @classmethod
+    def _generate_range(
+        cls, start, end, periods, freq, closed=None, *, unit: str | None = None
+    ) -> Self:
+        periods = dtl.validate_periods(periods)
+        if freq is None and any(x is None for x in [periods, start, end]):
+            raise ValueError("Must provide freq argument if no data is supplied")
+
+        if com.count_not_none(start, end, periods, freq) != 3:
+            raise ValueError(
+                "Of the four parameters: start, end, periods, "
+                "and freq, exactly three must be specified"
+            )
+
+        if start is not None:
+            start = Timedelta(start).as_unit("ns")
+
+        if end is not None:
+            end = Timedelta(end).as_unit("ns")
+
+        if unit is not None:
+            if unit not in ["s", "ms", "us", "ns"]:
+                raise ValueError("'unit' must be one of 's', 'ms', 'us', 'ns'")
+        else:
+            unit = "ns"
+
+        if start is not None and unit is not None:
+            start = start.as_unit(unit, round_ok=False)
+        if end is not None and unit is not None:
+            end = end.as_unit(unit, round_ok=False)
+
+        left_closed, right_closed = validate_endpoints(closed)
+
+        if freq is not None:
+            index = generate_regular_range(start, end, periods, freq, unit=unit)
+        else:
+            index = np.linspace(start._value, end._value, periods).astype("i8")
+
+        if not left_closed:
+            index = index[1:]
+        if not right_closed:
+            index = index[:-1]
+
+        td64values = index.view(f"m8[{unit}]")
+        return cls._simple_new(td64values, dtype=td64values.dtype, freq=freq)
+
+    # ----------------------------------------------------------------
+    # DatetimeLike Interface
+
+    def _unbox_scalar(self, value) -> np.timedelta64:
+        if not isinstance(value, self._scalar_type) and value is not NaT:
+            raise ValueError("'value' should be a Timedelta.")
+        self._check_compatible_with(value)
+        if value is NaT:
+            return np.timedelta64(value._value, self.unit)
+        else:
+            return value.as_unit(self.unit).asm8
+
+    def _scalar_from_string(self, value) -> Timedelta | NaTType:
+        return Timedelta(value)
+
+    def _check_compatible_with(self, other) -> None:
+        # we don't have anything to validate.
+        pass
+
+    # ----------------------------------------------------------------
+    # Array-Like / EA-Interface Methods
+
+    def astype(self, dtype, copy: bool = True):
+        # We handle
+        #   --> timedelta64[ns]
+        #   --> timedelta64
+        # DatetimeLikeArrayMixin super call handles other cases
+        dtype = pandas_dtype(dtype)
+
+        if lib.is_np_dtype(dtype, "m"):
+            if dtype == self.dtype:
+                if copy:
+                    return self.copy()
+                return self
+
+            if is_supported_dtype(dtype):
+                # unit conversion e.g. timedelta64[s]
+                res_values = astype_overflowsafe(self._ndarray, dtype, copy=False)
+                return type(self)._simple_new(
+                    res_values, dtype=res_values.dtype, freq=self.freq
+                )
+            else:
+                raise ValueError(
+                    f"Cannot convert from {self.dtype} to {dtype}. "
+                    "Supported resolutions are 's', 'ms', 'us', 'ns'"
+                )
+
+        return dtl.DatetimeLikeArrayMixin.astype(self, dtype, copy=copy)
+
+    def __iter__(self) -> Iterator:
+        if self.ndim > 1:
+            for i in range(len(self)):
+                yield self[i]
+        else:
+            # convert in chunks of 10k for efficiency
+            data = self._ndarray
+            length = len(self)
+            chunksize = 10000
+            chunks = (length // chunksize) + 1
+            for i in range(chunks):
+                start_i = i * chunksize
+                end_i = min((i + 1) * chunksize, length)
+                converted = ints_to_pytimedelta(data[start_i:end_i], box=True)
+                yield from converted
+
+    # ----------------------------------------------------------------
+    # Reductions
+
+    def sum(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        keepdims: bool = False,
+        initial=None,
+        skipna: bool = True,
+        min_count: int = 0,
+    ):
+        nv.validate_sum(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims, "initial": initial}
+        )
+
+        result = nanops.nansum(
+            self._ndarray, axis=axis, skipna=skipna, min_count=min_count
+        )
+        return self._wrap_reduction_result(axis, result)
+
+    def std(
+        self,
+        *,
+        axis: AxisInt | None = None,
+        dtype: NpDtype | None = None,
+        out=None,
+        ddof: int = 1,
+        keepdims: bool = False,
+        skipna: bool = True,
+    ):
+        nv.validate_stat_ddof_func(
+            (), {"dtype": dtype, "out": out, "keepdims": keepdims}, fname="std"
+        )
+
+        result = nanops.nanstd(self._ndarray, axis=axis, skipna=skipna, ddof=ddof)
+        if axis is None or self.ndim == 1:
+            return self._box_func(result)
+        return self._from_backing_data(result)
+
+    # ----------------------------------------------------------------
+    # Accumulations
+
+    def _accumulate(self, name: str, *, skipna: bool = True, **kwargs):
+        if name == "cumsum":
+            op = getattr(datetimelike_accumulations, name)
+            result = op(self._ndarray.copy(), skipna=skipna, **kwargs)
+
+            return type(self)._simple_new(result, freq=None, dtype=self.dtype)
+        elif name == "cumprod":
+            raise TypeError("cumprod not supported for Timedelta.")
+
+        else:
+            return super()._accumulate(name, skipna=skipna, **kwargs)
+
+    # ----------------------------------------------------------------
+    # Rendering Methods
+
+    def _formatter(self, boxed: bool = False):
+        from pandas.io.formats.format import get_format_timedelta64
+
+        return get_format_timedelta64(self, box=True)
+
+    def _format_native_types(
+        self, *, na_rep: str | float = "NaT", date_format=None, **kwargs
+    ) -> npt.NDArray[np.object_]:
+        from pandas.io.formats.format import get_format_timedelta64
+
+        # Relies on TimeDelta._repr_base
+        formatter = get_format_timedelta64(self, na_rep)
+        # equiv: np.array([formatter(x) for x in self._ndarray])
+        #  but independent of dimension
+        return np.frompyfunc(formatter, 1, 1)(self._ndarray)
+
+    # ----------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _add_offset(self, other):
+        assert not isinstance(other, Tick)
+        raise TypeError(
+            f"cannot add the type {type(other).__name__} to a {type(self).__name__}"
+        )
+
+    @unpack_zerodim_and_defer("__mul__")
+    def __mul__(self, other) -> Self:
+        if is_scalar(other):
+            # numpy will accept float and int, raise TypeError for others
+            result = self._ndarray * other
+            if result.dtype.kind != "m":
+                # numpy >= 2.1 may not raise a TypeError
+                # and seems to dispatch to others.__rmul__?
+                raise TypeError(f"Cannot multiply with {type(other).__name__}")
+            freq = None
+            if self.freq is not None and not isna(other):
+                freq = self.freq * other
+                if freq.n == 0:
+                    # GH#51575 Better to have no freq than an incorrect one
+                    freq = None
+            return type(self)._simple_new(result, dtype=result.dtype, freq=freq)
+
+        if not hasattr(other, "dtype"):
+            # list, tuple
+            other = np.array(other)
+        if len(other) != len(self) and not lib.is_np_dtype(other.dtype, "m"):
+            # Exclude timedelta64 here so we correctly raise TypeError
+            #  for that instead of ValueError
+            raise ValueError("Cannot multiply with unequal lengths")
+
+        if is_object_dtype(other.dtype):
+            # this multiplication will succeed only if all elements of other
+            #  are int or float scalars, so we will end up with
+            #  timedelta64[ns]-dtyped result
+            arr = self._ndarray
+            result = [arr[n] * other[n] for n in range(len(self))]
+            result = np.array(result)
+            return type(self)._simple_new(result, dtype=result.dtype)
+
+        # numpy will accept float or int dtype, raise TypeError for others
+        result = self._ndarray * other
+        if result.dtype.kind != "m":
+            # numpy >= 2.1 may not raise a TypeError
+            # and seems to dispatch to others.__rmul__?
+            raise TypeError(f"Cannot multiply with {type(other).__name__}")
+        return type(self)._simple_new(result, dtype=result.dtype)
+
+    __rmul__ = __mul__
+
+    def _scalar_divlike_op(self, other, op):
+        """
+        Shared logic for __truediv__, __rtruediv__, __floordiv__, __rfloordiv__
+        with scalar 'other'.
+        """
+        if isinstance(other, self._recognized_scalars):
+            other = Timedelta(other)
+            # mypy assumes that __new__ returns an instance of the class
+            # github.com/python/mypy/issues/1020
+            if cast("Timedelta | NaTType", other) is NaT:
+                # specifically timedelta64-NaT
+                res = np.empty(self.shape, dtype=np.float64)
+                res.fill(np.nan)
+                return res
+
+            # otherwise, dispatch to Timedelta implementation
+            return op(self._ndarray, other)
+
+        else:
+            # caller is responsible for checking lib.is_scalar(other)
+            # assume other is numeric, otherwise numpy will raise
+
+            if op in [roperator.rtruediv, roperator.rfloordiv]:
+                raise TypeError(
+                    f"Cannot divide {type(other).__name__} by {type(self).__name__}"
+                )
+
+            result = op(self._ndarray, other)
+            freq = None
+
+            if self.freq is not None:
+                # Note: freq gets division, not floor-division, even if op
+                #  is floordiv.
+                freq = self.freq / other
+                if freq.nanos == 0 and self.freq.nanos != 0:
+                    # e.g. if self.freq is Nano(1) then dividing by 2
+                    #  rounds down to zero
+                    freq = None
+
+            return type(self)._simple_new(result, dtype=result.dtype, freq=freq)
+
+    def _cast_divlike_op(self, other):
+        if not hasattr(other, "dtype"):
+            # e.g. list, tuple
+            other = np.array(other)
+
+        if len(other) != len(self):
+            raise ValueError("Cannot divide vectors with unequal lengths")
+        return other
+
+    def _vector_divlike_op(self, other, op) -> np.ndarray | Self:
+        """
+        Shared logic for __truediv__, __floordiv__, and their reversed versions
+        with timedelta64-dtype ndarray other.
+        """
+        # Let numpy handle it
+        result = op(self._ndarray, np.asarray(other))
+
+        if (is_integer_dtype(other.dtype) or is_float_dtype(other.dtype)) and op in [
+            operator.truediv,
+            operator.floordiv,
+        ]:
+            return type(self)._simple_new(result, dtype=result.dtype)
+
+        if op in [operator.floordiv, roperator.rfloordiv]:
+            mask = self.isna() | isna(other)
+            if mask.any():
+                result = result.astype(np.float64)
+                np.putmask(result, mask, np.nan)
+
+        return result
+
+    @unpack_zerodim_and_defer("__truediv__")
+    def __truediv__(self, other):
+        # timedelta / X is well-defined for timedelta-like or numeric X
+        op = operator.truediv
+        if is_scalar(other):
+            return self._scalar_divlike_op(other, op)
+
+        other = self._cast_divlike_op(other)
+        if (
+            lib.is_np_dtype(other.dtype, "m")
+            or is_integer_dtype(other.dtype)
+            or is_float_dtype(other.dtype)
+        ):
+            return self._vector_divlike_op(other, op)
+
+        if is_object_dtype(other.dtype):
+            other = np.asarray(other)
+            if self.ndim > 1:
+                res_cols = [left / right for left, right in zip(self, other)]
+                res_cols2 = [x.reshape(1, -1) for x in res_cols]
+                result = np.concatenate(res_cols2, axis=0)
+            else:
+                result = truediv_object_array(self._ndarray, other)
+
+            return result
+
+        else:
+            return NotImplemented
+
+    @unpack_zerodim_and_defer("__rtruediv__")
+    def __rtruediv__(self, other):
+        # X / timedelta is defined only for timedelta-like X
+        op = roperator.rtruediv
+        if is_scalar(other):
+            return self._scalar_divlike_op(other, op)
+
+        other = self._cast_divlike_op(other)
+        if lib.is_np_dtype(other.dtype, "m"):
+            return self._vector_divlike_op(other, op)
+
+        elif is_object_dtype(other.dtype):
+            # Note: unlike in __truediv__, we do not _need_ to do type
+            #  inference on the result.  It does not raise, a numeric array
+            #  is returned.  GH#23829
+            result_list = [other[n] / self[n] for n in range(len(self))]
+            return np.array(result_list)
+
+        else:
+            return NotImplemented
+
+    @unpack_zerodim_and_defer("__floordiv__")
+    def __floordiv__(self, other):
+        op = operator.floordiv
+        if is_scalar(other):
+            return self._scalar_divlike_op(other, op)
+
+        other = self._cast_divlike_op(other)
+        if (
+            lib.is_np_dtype(other.dtype, "m")
+            or is_integer_dtype(other.dtype)
+            or is_float_dtype(other.dtype)
+        ):
+            return self._vector_divlike_op(other, op)
+
+        elif is_object_dtype(other.dtype):
+            other = np.asarray(other)
+            if self.ndim > 1:
+                res_cols = [left // right for left, right in zip(self, other)]
+                res_cols2 = [x.reshape(1, -1) for x in res_cols]
+                result = np.concatenate(res_cols2, axis=0)
+            else:
+                result = floordiv_object_array(self._ndarray, other)
+
+            assert result.dtype == object
+            return result
+
+        else:
+            return NotImplemented
+
+    @unpack_zerodim_and_defer("__rfloordiv__")
+    def __rfloordiv__(self, other):
+        op = roperator.rfloordiv
+        if is_scalar(other):
+            return self._scalar_divlike_op(other, op)
+
+        other = self._cast_divlike_op(other)
+        if lib.is_np_dtype(other.dtype, "m"):
+            return self._vector_divlike_op(other, op)
+
+        elif is_object_dtype(other.dtype):
+            result_list = [other[n] // self[n] for n in range(len(self))]
+            result = np.array(result_list)
+            return result
+
+        else:
+            return NotImplemented
+
+    @unpack_zerodim_and_defer("__mod__")
+    def __mod__(self, other):
+        # Note: This is a naive implementation, can likely be optimized
+        if isinstance(other, self._recognized_scalars):
+            other = Timedelta(other)
+        return self - (self // other) * other
+
+    @unpack_zerodim_and_defer("__rmod__")
+    def __rmod__(self, other):
+        # Note: This is a naive implementation, can likely be optimized
+        if isinstance(other, self._recognized_scalars):
+            other = Timedelta(other)
+        return other - (other // self) * self
+
+    @unpack_zerodim_and_defer("__divmod__")
+    def __divmod__(self, other):
+        # Note: This is a naive implementation, can likely be optimized
+        if isinstance(other, self._recognized_scalars):
+            other = Timedelta(other)
+
+        res1 = self // other
+        res2 = self - res1 * other
+        return res1, res2
+
+    @unpack_zerodim_and_defer("__rdivmod__")
+    def __rdivmod__(self, other):
+        # Note: This is a naive implementation, can likely be optimized
+        if isinstance(other, self._recognized_scalars):
+            other = Timedelta(other)
+
+        res1 = other // self
+        res2 = other - res1 * self
+        return res1, res2
+
+    def __neg__(self) -> TimedeltaArray:
+        freq = None
+        if self.freq is not None:
+            freq = -self.freq
+        return type(self)._simple_new(-self._ndarray, dtype=self.dtype, freq=freq)
+
+    def __pos__(self) -> TimedeltaArray:
+        return type(self)._simple_new(
+            self._ndarray.copy(), dtype=self.dtype, freq=self.freq
+        )
+
+    def __abs__(self) -> TimedeltaArray:
+        # Note: freq is not preserved
+        return type(self)._simple_new(np.abs(self._ndarray), dtype=self.dtype)
+
+    # ----------------------------------------------------------------
+    # Conversion Methods - Vectorized analogues of Timedelta methods
+
+    def total_seconds(self) -> npt.NDArray[np.float64]:
+        """
+        Return total duration of each element expressed in seconds.
+
+        This method is available directly on TimedeltaArray, TimedeltaIndex
+        and on Series containing timedelta values under the ``.dt`` namespace.
+
+        Returns
+        -------
+        ndarray, Index or Series
+            When the calling object is a TimedeltaArray, the return type
+            is ndarray.  When the calling object is a TimedeltaIndex,
+            the return type is an Index with a float64 dtype. When the calling object
+            is a Series, the return type is Series of type `float64` whose
+            index is the same as the original.
+
+        See Also
+        --------
+        datetime.timedelta.total_seconds : Standard library version
+            of this method.
+        TimedeltaIndex.components : Return a DataFrame with components of
+            each Timedelta.
+
+        Examples
+        --------
+        **Series**
+
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit='d'))
+        >>> s
+        0   0 days
+        1   1 days
+        2   2 days
+        3   3 days
+        4   4 days
+        dtype: timedelta64[ns]
+
+        >>> s.dt.total_seconds()
+        0         0.0
+        1     86400.0
+        2    172800.0
+        3    259200.0
+        4    345600.0
+        dtype: float64
+
+        **TimedeltaIndex**
+
+        >>> idx = pd.to_timedelta(np.arange(5), unit='d')
+        >>> idx
+        TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
+                       dtype='timedelta64[ns]', freq=None)
+
+        >>> idx.total_seconds()
+        Index([0.0, 86400.0, 172800.0, 259200.0, 345600.0], dtype='float64')
+        """
+        pps = periods_per_second(self._creso)
+        return self._maybe_mask_results(self.asi8 / pps, fill_value=None)
+
+    def to_pytimedelta(self) -> npt.NDArray[np.object_]:
+        """
+        Return an ndarray of datetime.timedelta objects.
+
+        Returns
+        -------
+        numpy.ndarray
+
+        Examples
+        --------
+        >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='D')
+        >>> tdelta_idx
+        TimedeltaIndex(['1 days', '2 days', '3 days'],
+                        dtype='timedelta64[ns]', freq=None)
+        >>> tdelta_idx.to_pytimedelta()
+        array([datetime.timedelta(days=1), datetime.timedelta(days=2),
+               datetime.timedelta(days=3)], dtype=object)
+        """
+        return ints_to_pytimedelta(self._ndarray)
+
+    days_docstring = textwrap.dedent(
+        """Number of days for each element.
+
+    Examples
+    --------
+    For Series:
+
+    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='d'))
+    >>> ser
+    0   1 days
+    1   2 days
+    2   3 days
+    dtype: timedelta64[ns]
+    >>> ser.dt.days
+    0    1
+    1    2
+    2    3
+    dtype: int64
+
+    For TimedeltaIndex:
+
+    >>> tdelta_idx = pd.to_timedelta(["0 days", "10 days", "20 days"])
+    >>> tdelta_idx
+    TimedeltaIndex(['0 days', '10 days', '20 days'],
+                    dtype='timedelta64[ns]', freq=None)
+    >>> tdelta_idx.days
+    Index([0, 10, 20], dtype='int64')"""
+    )
+    days = _field_accessor("days", "days", days_docstring)
+
+    seconds_docstring = textwrap.dedent(
+        """Number of seconds (>= 0 and less than 1 day) for each element.
+
+    Examples
+    --------
+    For Series:
+
+    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='s'))
+    >>> ser
+    0   0 days 00:00:01
+    1   0 days 00:00:02
+    2   0 days 00:00:03
+    dtype: timedelta64[ns]
+    >>> ser.dt.seconds
+    0    1
+    1    2
+    2    3
+    dtype: int32
+
+    For TimedeltaIndex:
+
+    >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='s')
+    >>> tdelta_idx
+    TimedeltaIndex(['0 days 00:00:01', '0 days 00:00:02', '0 days 00:00:03'],
+                   dtype='timedelta64[ns]', freq=None)
+    >>> tdelta_idx.seconds
+    Index([1, 2, 3], dtype='int32')"""
+    )
+    seconds = _field_accessor(
+        "seconds",
+        "seconds",
+        seconds_docstring,
+    )
+
+    microseconds_docstring = textwrap.dedent(
+        """Number of microseconds (>= 0 and less than 1 second) for each element.
+
+    Examples
+    --------
+    For Series:
+
+    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='us'))
+    >>> ser
+    0   0 days 00:00:00.000001
+    1   0 days 00:00:00.000002
+    2   0 days 00:00:00.000003
+    dtype: timedelta64[ns]
+    >>> ser.dt.microseconds
+    0    1
+    1    2
+    2    3
+    dtype: int32
+
+    For TimedeltaIndex:
+
+    >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='us')
+    >>> tdelta_idx
+    TimedeltaIndex(['0 days 00:00:00.000001', '0 days 00:00:00.000002',
+                    '0 days 00:00:00.000003'],
+                   dtype='timedelta64[ns]', freq=None)
+    >>> tdelta_idx.microseconds
+    Index([1, 2, 3], dtype='int32')"""
+    )
+    microseconds = _field_accessor(
+        "microseconds",
+        "microseconds",
+        microseconds_docstring,
+    )
+
+    nanoseconds_docstring = textwrap.dedent(
+        """Number of nanoseconds (>= 0 and less than 1 microsecond) for each element.
+
+    Examples
+    --------
+    For Series:
+
+    >>> ser = pd.Series(pd.to_timedelta([1, 2, 3], unit='ns'))
+    >>> ser
+    0   0 days 00:00:00.000000001
+    1   0 days 00:00:00.000000002
+    2   0 days 00:00:00.000000003
+    dtype: timedelta64[ns]
+    >>> ser.dt.nanoseconds
+    0    1
+    1    2
+    2    3
+    dtype: int32
+
+    For TimedeltaIndex:
+
+    >>> tdelta_idx = pd.to_timedelta([1, 2, 3], unit='ns')
+    >>> tdelta_idx
+    TimedeltaIndex(['0 days 00:00:00.000000001', '0 days 00:00:00.000000002',
+                    '0 days 00:00:00.000000003'],
+                   dtype='timedelta64[ns]', freq=None)
+    >>> tdelta_idx.nanoseconds
+    Index([1, 2, 3], dtype='int32')"""
+    )
+    nanoseconds = _field_accessor(
+        "nanoseconds",
+        "nanoseconds",
+        nanoseconds_docstring,
+    )
+
+    @property
+    def components(self) -> DataFrame:
+        """
+        Return a DataFrame of the individual resolution components of the Timedeltas.
+
+        The components (days, hours, minutes seconds, milliseconds, microseconds,
+        nanoseconds) are returned as columns in a DataFrame.
+
+        Returns
+        -------
+        DataFrame
+
+        Examples
+        --------
+        >>> tdelta_idx = pd.to_timedelta(['1 day 3 min 2 us 42 ns'])
+        >>> tdelta_idx
+        TimedeltaIndex(['1 days 00:03:00.000002042'],
+                       dtype='timedelta64[ns]', freq=None)
+        >>> tdelta_idx.components
+           days  hours  minutes  seconds  milliseconds  microseconds  nanoseconds
+        0     1      0        3        0             0             2           42
+        """
+        from pandas import DataFrame
+
+        columns = [
+            "days",
+            "hours",
+            "minutes",
+            "seconds",
+            "milliseconds",
+            "microseconds",
+            "nanoseconds",
+        ]
+        hasnans = self._hasna
+        if hasnans:
+
+            def f(x):
+                if isna(x):
+                    return [np.nan] * len(columns)
+                return x.components
+
+        else:
+
+            def f(x):
+                return x.components
+
+        result = DataFrame([f(x) for x in self], columns=columns)
+        if not hasnans:
+            result = result.astype("int64")
+        return result
+
+
+# ---------------------------------------------------------------------
+# Constructor Helpers
+
+
+def sequence_to_td64ns(
+    data,
+    copy: bool = False,
+    unit=None,
+    errors: DateTimeErrorChoices = "raise",
+) -> tuple[np.ndarray, Tick | None]:
+    """
+    Parameters
+    ----------
+    data : list-like
+    copy : bool, default False
+    unit : str, optional
+        The timedelta unit to treat integers as multiples of. For numeric
+        data this defaults to ``'ns'``.
+        Must be un-specified if the data contains a str and ``errors=="raise"``.
+    errors : {"raise", "coerce", "ignore"}, default "raise"
+        How to handle elements that cannot be converted to timedelta64[ns].
+        See ``pandas.to_timedelta`` for details.
+
+    Returns
+    -------
+    converted : numpy.ndarray
+        The sequence converted to a numpy array with dtype ``timedelta64[ns]``.
+    inferred_freq : Tick or None
+        The inferred frequency of the sequence.
+
+    Raises
+    ------
+    ValueError : Data cannot be converted to timedelta64[ns].
+
+    Notes
+    -----
+    Unlike `pandas.to_timedelta`, if setting ``errors=ignore`` will not cause
+    errors to be ignored; they are caught and subsequently ignored at a
+    higher level.
+    """
+    assert unit not in ["Y", "y", "M"]  # caller is responsible for checking
+
+    inferred_freq = None
+    if unit is not None:
+        unit = parse_timedelta_unit(unit)
+
+    data, copy = dtl.ensure_arraylike_for_datetimelike(
+        data, copy, cls_name="TimedeltaArray"
+    )
+
+    if isinstance(data, TimedeltaArray):
+        inferred_freq = data.freq
+
+    # Convert whatever we have into timedelta64[ns] dtype
+    if data.dtype == object or is_string_dtype(data.dtype):
+        # no need to make a copy, need to convert if string-dtyped
+        data = _objects_to_td64ns(data, unit=unit, errors=errors)
+        copy = False
+
+    elif is_integer_dtype(data.dtype):
+        # treat as multiples of the given unit
+        data, copy_made = _ints_to_td64ns(data, unit=unit)
+        copy = copy and not copy_made
+
+    elif is_float_dtype(data.dtype):
+        # cast the unit, multiply base/frac separately
+        # to avoid precision issues from float -> int
+        if isinstance(data.dtype, ExtensionDtype):
+            mask = data._mask
+            data = data._data
+        else:
+            mask = np.isnan(data)
+
+        data = cast_from_unit_vectorized(data, unit or "ns")
+        data[mask] = iNaT
+        data = data.view("m8[ns]")
+        copy = False
+
+    elif lib.is_np_dtype(data.dtype, "m"):
+        if not is_supported_dtype(data.dtype):
+            # cast to closest supported unit, i.e. s or ns
+            new_dtype = get_supported_dtype(data.dtype)
+            data = astype_overflowsafe(data, dtype=new_dtype, copy=False)
+            copy = False
+
+    else:
+        # This includes datetime64-dtype, see GH#23539, GH#29794
+        raise TypeError(f"dtype {data.dtype} cannot be converted to timedelta64[ns]")
+
+    if not copy:
+        data = np.asarray(data)
+    else:
+        data = np.array(data, copy=copy)
+
+    assert data.dtype.kind == "m"
+    assert data.dtype != "m8"  # i.e. not unit-less
+
+    return data, inferred_freq
+
+
+def _ints_to_td64ns(data, unit: str = "ns"):
+    """
+    Convert an ndarray with integer-dtype to timedelta64[ns] dtype, treating
+    the integers as multiples of the given timedelta unit.
+
+    Parameters
+    ----------
+    data : numpy.ndarray with integer-dtype
+    unit : str, default "ns"
+        The timedelta unit to treat integers as multiples of.
+
+    Returns
+    -------
+    numpy.ndarray : timedelta64[ns] array converted from data
+    bool : whether a copy was made
+    """
+    copy_made = False
+    unit = unit if unit is not None else "ns"
+
+    if data.dtype != np.int64:
+        # converting to int64 makes a copy, so we can avoid
+        # re-copying later
+        data = data.astype(np.int64)
+        copy_made = True
+
+    if unit != "ns":
+        dtype_str = f"timedelta64[{unit}]"
+        data = data.view(dtype_str)
+
+        data = astype_overflowsafe(data, dtype=TD64NS_DTYPE)
+
+        # the astype conversion makes a copy, so we can avoid re-copying later
+        copy_made = True
+
+    else:
+        data = data.view("timedelta64[ns]")
+
+    return data, copy_made
+
+
+def _objects_to_td64ns(data, unit=None, errors: DateTimeErrorChoices = "raise"):
+    """
+    Convert a object-dtyped or string-dtyped array into an
+    timedelta64[ns]-dtyped array.
+
+    Parameters
+    ----------
+    data : ndarray or Index
+    unit : str, default "ns"
+        The timedelta unit to treat integers as multiples of.
+        Must not be specified if the data contains a str.
+    errors : {"raise", "coerce", "ignore"}, default "raise"
+        How to handle elements that cannot be converted to timedelta64[ns].
+        See ``pandas.to_timedelta`` for details.
+
+    Returns
+    -------
+    numpy.ndarray : timedelta64[ns] array converted from data
+
+    Raises
+    ------
+    ValueError : Data cannot be converted to timedelta64[ns].
+
+    Notes
+    -----
+    Unlike `pandas.to_timedelta`, if setting `errors=ignore` will not cause
+    errors to be ignored; they are caught and subsequently ignored at a
+    higher level.
+    """
+    # coerce Index to np.ndarray, converting string-dtype if necessary
+    values = np.asarray(data, dtype=np.object_)
+
+    result = array_to_timedelta64(values, unit=unit, errors=errors)
+    return result.view("timedelta64[ns]")
+
+
+def _validate_td64_dtype(dtype) -> DtypeObj:
+    dtype = pandas_dtype(dtype)
+    if dtype == np.dtype("m8"):
+        # no precision disallowed GH#24806
+        msg = (
+            "Passing in 'timedelta' dtype with no precision is not allowed. "
+            "Please pass in 'timedelta64[ns]' instead."
+        )
+        raise ValueError(msg)
+
+    if not lib.is_np_dtype(dtype, "m"):
+        raise ValueError(f"dtype '{dtype}' is invalid, should be np.timedelta64 dtype")
+    elif not is_supported_dtype(dtype):
+        raise ValueError("Supported timedelta64 resolutions are 's', 'ms', 'us', 'ns'")
+
+    return dtype
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/base.py b/.venv/lib/python3.13/site-packages/pandas/core/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..af8f80db6a34741b761991a4256e395100080171
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/base.py
@@ -0,0 +1,1400 @@
+"""
+Base and utility classes for pandas objects.
+"""
+
+from __future__ import annotations
+
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Generic,
+    Literal,
+    cast,
+    final,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_copy_on_write
+
+from pandas._libs import lib
+from pandas._typing import (
+    AxisInt,
+    DtypeObj,
+    IndexLabel,
+    NDFrameT,
+    Self,
+    Shape,
+    npt,
+)
+from pandas.compat import PYPY
+from pandas.compat.numpy import function as nv
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import can_hold_element
+from pandas.core.dtypes.common import (
+    is_object_dtype,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    remove_na_arraylike,
+)
+
+from pandas.core import (
+    algorithms,
+    nanops,
+    ops,
+)
+from pandas.core.accessor import DirNamesMixin
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays import ExtensionArray
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+    )
+
+    from pandas._typing import (
+        DropKeep,
+        NumpySorter,
+        NumpyValueArrayLike,
+        ScalarLike_co,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+
+
+_shared_docs: dict[str, str] = {}
+_indexops_doc_kwargs = {
+    "klass": "IndexOpsMixin",
+    "inplace": "",
+    "unique": "IndexOpsMixin",
+    "duplicated": "IndexOpsMixin",
+}
+
+
+class PandasObject(DirNamesMixin):
+    """
+    Baseclass for various pandas objects.
+    """
+
+    # results from calls to methods decorated with cache_readonly get added to _cache
+    _cache: dict[str, Any]
+
+    @property
+    def _constructor(self):
+        """
+        Class constructor (for this class it's just `__class__`).
+        """
+        return type(self)
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation for a particular object.
+        """
+        # Should be overwritten by base classes
+        return object.__repr__(self)
+
+    def _reset_cache(self, key: str | None = None) -> None:
+        """
+        Reset cached properties. If ``key`` is passed, only clears that key.
+        """
+        if not hasattr(self, "_cache"):
+            return
+        if key is None:
+            self._cache.clear()
+        else:
+            self._cache.pop(key, None)
+
+    def __sizeof__(self) -> int:
+        """
+        Generates the total memory usage for an object that returns
+        either a value or Series of values
+        """
+        memory_usage = getattr(self, "memory_usage", None)
+        if memory_usage:
+            mem = memory_usage(deep=True)  # pylint: disable=not-callable
+            return int(mem if is_scalar(mem) else mem.sum())
+
+        # no memory_usage attribute, so fall back to object's 'sizeof'
+        return super().__sizeof__()
+
+
+class NoNewAttributesMixin:
+    """
+    Mixin which prevents adding new attributes.
+
+    Prevents additional attributes via xxx.attribute = "something" after a
+    call to `self.__freeze()`. Mainly used to prevent the user from using
+    wrong attributes on an accessor (`Series.cat/.str/.dt`).
+
+    If you really want to add a new attribute at a later time, you need to use
+    `object.__setattr__(self, key, value)`.
+    """
+
+    def _freeze(self) -> None:
+        """
+        Prevents setting additional attributes.
+        """
+        object.__setattr__(self, "__frozen", True)
+
+    # prevent adding any attribute via s.xxx.new_attribute = ...
+    def __setattr__(self, key: str, value) -> None:
+        # _cache is used by a decorator
+        # We need to check both 1.) cls.__dict__ and 2.) getattr(self, key)
+        # because
+        # 1.) getattr is false for attributes that raise errors
+        # 2.) cls.__dict__ doesn't traverse into base classes
+        if getattr(self, "__frozen", False) and not (
+            key == "_cache"
+            or key in type(self).__dict__
+            or getattr(self, key, None) is not None
+        ):
+            raise AttributeError(f"You cannot add any new attribute '{key}'")
+        object.__setattr__(self, key, value)
+
+
+class SelectionMixin(Generic[NDFrameT]):
+    """
+    mixin implementing the selection & aggregation interface on a group-like
+    object sub-classes need to define: obj, exclusions
+    """
+
+    obj: NDFrameT
+    _selection: IndexLabel | None = None
+    exclusions: frozenset[Hashable]
+    _internal_names = ["_cache", "__setstate__"]
+    _internal_names_set = set(_internal_names)
+
+    @final
+    @property
+    def _selection_list(self):
+        if not isinstance(
+            self._selection, (list, tuple, ABCSeries, ABCIndex, np.ndarray)
+        ):
+            return [self._selection]
+        return self._selection
+
+    @cache_readonly
+    def _selected_obj(self):
+        if self._selection is None or isinstance(self.obj, ABCSeries):
+            return self.obj
+        else:
+            return self.obj[self._selection]
+
+    @final
+    @cache_readonly
+    def ndim(self) -> int:
+        return self._selected_obj.ndim
+
+    @final
+    @cache_readonly
+    def _obj_with_exclusions(self):
+        if isinstance(self.obj, ABCSeries):
+            return self.obj
+
+        if self._selection is not None:
+            return self.obj._getitem_nocopy(self._selection_list)
+
+        if len(self.exclusions) > 0:
+            # equivalent to `self.obj.drop(self.exclusions, axis=1)
+            #  but this avoids consolidating and making a copy
+            # TODO: following GH#45287 can we now use .drop directly without
+            #  making a copy?
+            return self.obj._drop_axis(self.exclusions, axis=1, only_slice=True)
+        else:
+            return self.obj
+
+    def __getitem__(self, key):
+        if self._selection is not None:
+            raise IndexError(f"Column(s) {self._selection} already selected")
+
+        if isinstance(key, (list, tuple, ABCSeries, ABCIndex, np.ndarray)):
+            if len(self.obj.columns.intersection(key)) != len(set(key)):
+                bad_keys = list(set(key).difference(self.obj.columns))
+                raise KeyError(f"Columns not found: {str(bad_keys)[1:-1]}")
+            return self._gotitem(list(key), ndim=2)
+
+        else:
+            if key not in self.obj:
+                raise KeyError(f"Column not found: {key}")
+            ndim = self.obj[key].ndim
+            return self._gotitem(key, ndim=ndim)
+
+    def _gotitem(self, key, ndim: int, subset=None):
+        """
+        sub-classes to define
+        return a sliced object
+
+        Parameters
+        ----------
+        key : str / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        raise AbstractMethodError(self)
+
+    @final
+    def _infer_selection(self, key, subset: Series | DataFrame):
+        """
+        Infer the `selection` to pass to our constructor in _gotitem.
+        """
+        # Shared by Rolling and Resample
+        selection = None
+        if subset.ndim == 2 and (
+            (lib.is_scalar(key) and key in subset) or lib.is_list_like(key)
+        ):
+            selection = key
+        elif subset.ndim == 1 and lib.is_scalar(key) and key == subset.name:
+            selection = key
+        return selection
+
+    def aggregate(self, func, *args, **kwargs):
+        raise AbstractMethodError(self)
+
+    agg = aggregate
+
+
+class IndexOpsMixin(OpsMixin):
+    """
+    Common ops mixin to support a unified interface / docs for Series / Index
+    """
+
+    # ndarray compatibility
+    __array_priority__ = 1000
+    _hidden_attrs: frozenset[str] = frozenset(
+        ["tolist"]  # tolist is not deprecated, just suppressed in the __dir__
+    )
+
+    @property
+    def dtype(self) -> DtypeObj:
+        # must be defined here as a property for mypy
+        raise AbstractMethodError(self)
+
+    @property
+    def _values(self) -> ExtensionArray | np.ndarray:
+        # must be defined here as a property for mypy
+        raise AbstractMethodError(self)
+
+    @final
+    def transpose(self, *args, **kwargs) -> Self:
+        """
+        Return the transpose, which is by definition self.
+
+        Returns
+        -------
+        %(klass)s
+        """
+        nv.validate_transpose(args, kwargs)
+        return self
+
+    T = property(
+        transpose,
+        doc="""
+        Return the transpose, which is by definition self.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(['Ant', 'Bear', 'Cow'])
+        >>> s
+        0     Ant
+        1    Bear
+        2     Cow
+        dtype: object
+        >>> s.T
+        0     Ant
+        1    Bear
+        2     Cow
+        dtype: object
+
+        For Index:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx.T
+        Index([1, 2, 3], dtype='int64')
+        """,
+    )
+
+    @property
+    def shape(self) -> Shape:
+        """
+        Return a tuple of the shape of the underlying data.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.shape
+        (3,)
+        """
+        return self._values.shape
+
+    def __len__(self) -> int:
+        # We need this defined here for mypy
+        raise AbstractMethodError(self)
+
+    # Temporarily avoid using `-> Literal[1]:` because of an IPython (jedi) bug
+    # https://github.com/ipython/ipython/issues/14412
+    # https://github.com/davidhalter/jedi/issues/1990
+    @property
+    def ndim(self) -> int:
+        """
+        Number of dimensions of the underlying data, by definition 1.
+
+        Examples
+        --------
+        >>> s = pd.Series(['Ant', 'Bear', 'Cow'])
+        >>> s
+        0     Ant
+        1    Bear
+        2     Cow
+        dtype: object
+        >>> s.ndim
+        1
+
+        For Index:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.ndim
+        1
+        """
+        return 1
+
+    @final
+    def item(self):
+        """
+        Return the first element of the underlying data as a Python scalar.
+
+        Returns
+        -------
+        scalar
+            The first element of Series or Index.
+
+        Raises
+        ------
+        ValueError
+            If the data is not length = 1.
+
+        Examples
+        --------
+        >>> s = pd.Series([1])
+        >>> s.item()
+        1
+
+        For an index:
+
+        >>> s = pd.Series([1], index=['a'])
+        >>> s.index.item()
+        'a'
+        """
+        if len(self) == 1:
+            return next(iter(self))
+        raise ValueError("can only convert an array of size 1 to a Python scalar")
+
+    @property
+    def nbytes(self) -> int:
+        """
+        Return the number of bytes in the underlying data.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(['Ant', 'Bear', 'Cow'])
+        >>> s
+        0     Ant
+        1    Bear
+        2     Cow
+        dtype: object
+        >>> s.nbytes
+        24
+
+        For Index:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.nbytes
+        24
+        """
+        return self._values.nbytes
+
+    @property
+    def size(self) -> int:
+        """
+        Return the number of elements in the underlying data.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series(['Ant', 'Bear', 'Cow'])
+        >>> s
+        0     Ant
+        1    Bear
+        2     Cow
+        dtype: object
+        >>> s.size
+        3
+
+        For Index:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.size
+        3
+        """
+        return len(self._values)
+
+    @property
+    def array(self) -> ExtensionArray:
+        """
+        The ExtensionArray of the data backing this Series or Index.
+
+        Returns
+        -------
+        ExtensionArray
+            An ExtensionArray of the values stored within. For extension
+            types, this is the actual array. For NumPy native types, this
+            is a thin (no copy) wrapper around :class:`numpy.ndarray`.
+
+            ``.array`` differs from ``.values``, which may require converting
+            the data to a different form.
+
+        See Also
+        --------
+        Index.to_numpy : Similar method that always returns a NumPy array.
+        Series.to_numpy : Similar method that always returns a NumPy array.
+
+        Notes
+        -----
+        This table lays out the different array types for each extension
+        dtype within pandas.
+
+        ================== =============================
+        dtype              array type
+        ================== =============================
+        category           Categorical
+        period             PeriodArray
+        interval           IntervalArray
+        IntegerNA          IntegerArray
+        string             StringArray
+        boolean            BooleanArray
+        datetime64[ns, tz] DatetimeArray
+        ================== =============================
+
+        For any 3rd-party extension types, the array type will be an
+        ExtensionArray.
+
+        For all remaining dtypes ``.array`` will be a
+        :class:`arrays.NumpyExtensionArray` wrapping the actual ndarray
+        stored within. If you absolutely need a NumPy array (possibly with
+        copying / coercing data), then use :meth:`Series.to_numpy` instead.
+
+        Examples
+        --------
+        For regular NumPy types like int, and float, a NumpyExtensionArray
+        is returned.
+
+        >>> pd.Series([1, 2, 3]).array
+        
+        [1, 2, 3]
+        Length: 3, dtype: int64
+
+        For extension types, like Categorical, the actual ExtensionArray
+        is returned
+
+        >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a']))
+        >>> ser.array
+        ['a', 'b', 'a']
+        Categories (2, object): ['a', 'b']
+        """
+        raise AbstractMethodError(self)
+
+    @final
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+        **kwargs,
+    ) -> np.ndarray:
+        """
+        A NumPy ndarray representing the values in this Series or Index.
+
+        Parameters
+        ----------
+        dtype : str or numpy.dtype, optional
+            The dtype to pass to :meth:`numpy.asarray`.
+        copy : bool, default False
+            Whether to ensure that the returned value is not a view on
+            another array. Note that ``copy=False`` does not *ensure* that
+            ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that
+            a copy is made, even if not strictly necessary.
+        na_value : Any, optional
+            The value to use for missing values. The default value depends
+            on `dtype` and the type of the array.
+        **kwargs
+            Additional keywords passed through to the ``to_numpy`` method
+            of the underlying array (for extension arrays).
+
+        Returns
+        -------
+        numpy.ndarray
+
+        See Also
+        --------
+        Series.array : Get the actual data stored within.
+        Index.array : Get the actual data stored within.
+        DataFrame.to_numpy : Similar method for DataFrame.
+
+        Notes
+        -----
+        The returned array will be the same up to equality (values equal
+        in `self` will be equal in the returned array; likewise for values
+        that are not equal). When `self` contains an ExtensionArray, the
+        dtype may be different. For example, for a category-dtype Series,
+        ``to_numpy()`` will return a NumPy array and the categorical dtype
+        will be lost.
+
+        For NumPy dtypes, this will be a reference to the actual data stored
+        in this Series or Index (assuming ``copy=False``). Modifying the result
+        in place will modify the data stored in the Series or Index (not that
+        we recommend doing that).
+
+        For extension types, ``to_numpy()`` *may* require copying data and
+        coercing the result to a NumPy type (possibly object), which may be
+        expensive. When you need a no-copy reference to the underlying data,
+        :attr:`Series.array` should be used instead.
+
+        This table lays out the different dtypes and default return types of
+        ``to_numpy()`` for various dtypes within pandas.
+
+        ================== ================================
+        dtype              array type
+        ================== ================================
+        category[T]        ndarray[T] (same dtype as input)
+        period             ndarray[object] (Periods)
+        interval           ndarray[object] (Intervals)
+        IntegerNA          ndarray[object]
+        datetime64[ns]     datetime64[ns]
+        datetime64[ns, tz] ndarray[object] (Timestamps)
+        ================== ================================
+
+        Examples
+        --------
+        >>> ser = pd.Series(pd.Categorical(['a', 'b', 'a']))
+        >>> ser.to_numpy()
+        array(['a', 'b', 'a'], dtype=object)
+
+        Specify the `dtype` to control how datetime-aware data is represented.
+        Use ``dtype=object`` to return an ndarray of pandas :class:`Timestamp`
+        objects, each with the correct ``tz``.
+
+        >>> ser = pd.Series(pd.date_range('2000', periods=2, tz="CET"))
+        >>> ser.to_numpy(dtype=object)
+        array([Timestamp('2000-01-01 00:00:00+0100', tz='CET'),
+               Timestamp('2000-01-02 00:00:00+0100', tz='CET')],
+              dtype=object)
+
+        Or ``dtype='datetime64[ns]'`` to return an ndarray of native
+        datetime64 values. The values are converted to UTC and the timezone
+        info is dropped.
+
+        >>> ser.to_numpy(dtype="datetime64[ns]")
+        ... # doctest: +ELLIPSIS
+        array(['1999-12-31T23:00:00.000000000', '2000-01-01T23:00:00...'],
+              dtype='datetime64[ns]')
+        """
+        if isinstance(self.dtype, ExtensionDtype):
+            return self.array.to_numpy(dtype, copy=copy, na_value=na_value, **kwargs)
+        elif kwargs:
+            bad_keys = next(iter(kwargs.keys()))
+            raise TypeError(
+                f"to_numpy() got an unexpected keyword argument '{bad_keys}'"
+            )
+
+        fillna = (
+            na_value is not lib.no_default
+            # no need to fillna with np.nan if we already have a float dtype
+            and not (na_value is np.nan and np.issubdtype(self.dtype, np.floating))
+        )
+
+        values = self._values
+        if fillna:
+            if not can_hold_element(values, na_value):
+                # if we can't hold the na_value asarray either makes a copy or we
+                # error before modifying values. The asarray later on thus won't make
+                # another copy
+                values = np.asarray(values, dtype=dtype)
+            else:
+                values = values.copy()
+
+            values[np.asanyarray(isna(self))] = na_value
+
+        result = np.asarray(values, dtype=dtype)
+
+        if (copy and not fillna) or (not copy and using_copy_on_write()):
+            if np.shares_memory(self._values[:2], result[:2]):
+                # Take slices to improve performance of check
+                if using_copy_on_write() and not copy:
+                    result = result.view()
+                    result.flags.writeable = False
+                else:
+                    result = result.copy()
+
+        return result
+
+    @final
+    @property
+    def empty(self) -> bool:
+        return not self.size
+
+    @doc(op="max", oppose="min", value="largest")
+    def argmax(
+        self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs
+    ) -> int:
+        """
+        Return int position of the {value} value in the Series.
+
+        If the {op}imum is achieved in multiple locations,
+        the first row position is returned.
+
+        Parameters
+        ----------
+        axis : {{None}}
+            Unused. Parameter needed for compatibility with DataFrame.
+        skipna : bool, default True
+            Exclude NA/null values when showing the result.
+        *args, **kwargs
+            Additional arguments and keywords for compatibility with NumPy.
+
+        Returns
+        -------
+        int
+            Row position of the {op}imum value.
+
+        See Also
+        --------
+        Series.arg{op} : Return position of the {op}imum value.
+        Series.arg{oppose} : Return position of the {oppose}imum value.
+        numpy.ndarray.arg{op} : Equivalent method for numpy arrays.
+        Series.idxmax : Return index label of the maximum values.
+        Series.idxmin : Return index label of the minimum values.
+
+        Examples
+        --------
+        Consider dataset containing cereal calories
+
+        >>> s = pd.Series({{'Corn Flakes': 100.0, 'Almond Delight': 110.0,
+        ...                'Cinnamon Toast Crunch': 120.0, 'Cocoa Puff': 110.0}})
+        >>> s
+        Corn Flakes              100.0
+        Almond Delight           110.0
+        Cinnamon Toast Crunch    120.0
+        Cocoa Puff               110.0
+        dtype: float64
+
+        >>> s.argmax()
+        2
+        >>> s.argmin()
+        0
+
+        The maximum cereal calories is the third element and
+        the minimum cereal calories is the first element,
+        since series is zero-indexed.
+        """
+        delegate = self._values
+        nv.validate_minmax_axis(axis)
+        skipna = nv.validate_argmax_with_skipna(skipna, args, kwargs)
+
+        if isinstance(delegate, ExtensionArray):
+            if not skipna and delegate.isna().any():
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return -1
+            else:
+                return delegate.argmax()
+        else:
+            result = nanops.nanargmax(delegate, skipna=skipna)
+            if result == -1:
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            # error: Incompatible return value type (got "Union[int, ndarray]", expected
+            # "int")
+            return result  # type: ignore[return-value]
+
+    @doc(argmax, op="min", oppose="max", value="smallest")
+    def argmin(
+        self, axis: AxisInt | None = None, skipna: bool = True, *args, **kwargs
+    ) -> int:
+        delegate = self._values
+        nv.validate_minmax_axis(axis)
+        skipna = nv.validate_argmin_with_skipna(skipna, args, kwargs)
+
+        if isinstance(delegate, ExtensionArray):
+            if not skipna and delegate.isna().any():
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return -1
+            else:
+                return delegate.argmin()
+        else:
+            result = nanops.nanargmin(delegate, skipna=skipna)
+            if result == -1:
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            # error: Incompatible return value type (got "Union[int, ndarray]", expected
+            # "int")
+            return result  # type: ignore[return-value]
+
+    def tolist(self):
+        """
+        Return a list of the values.
+
+        These are each a scalar type, which is a Python scalar
+        (for str, int, float) or a pandas scalar
+        (for Timestamp/Timedelta/Interval/Period)
+
+        Returns
+        -------
+        list
+
+        See Also
+        --------
+        numpy.ndarray.tolist : Return the array as an a.ndim-levels deep
+            nested list of Python scalars.
+
+        Examples
+        --------
+        For Series
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.to_list()
+        [1, 2, 3]
+
+        For Index:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+
+        >>> idx.to_list()
+        [1, 2, 3]
+        """
+        return self._values.tolist()
+
+    to_list = tolist
+
+    def __iter__(self) -> Iterator:
+        """
+        Return an iterator of the values.
+
+        These are each a scalar type, which is a Python scalar
+        (for str, int, float) or a pandas scalar
+        (for Timestamp/Timedelta/Interval/Period)
+
+        Returns
+        -------
+        iterator
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> for x in s:
+        ...     print(x)
+        1
+        2
+        3
+        """
+        # We are explicitly making element iterators.
+        if not isinstance(self._values, np.ndarray):
+            # Check type instead of dtype to catch DTA/TDA
+            return iter(self._values)
+        else:
+            return map(self._values.item, range(self._values.size))
+
+    @cache_readonly
+    def hasnans(self) -> bool:
+        """
+        Return True if there are any NaNs.
+
+        Enables various performance speedups.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, None])
+        >>> s
+        0    1.0
+        1    2.0
+        2    3.0
+        3    NaN
+        dtype: float64
+        >>> s.hasnans
+        True
+        """
+        # error: Item "bool" of "Union[bool, ndarray[Any, dtype[bool_]], NDFrame]"
+        # has no attribute "any"
+        return bool(isna(self).any())  # type: ignore[union-attr]
+
+    @final
+    def _map_values(self, mapper, na_action=None, convert: bool = True):
+        """
+        An internal function that maps values using the input
+        correspondence (which can be a dict, Series, or function).
+
+        Parameters
+        ----------
+        mapper : function, dict, or Series
+            The input correspondence object
+        na_action : {None, 'ignore'}
+            If 'ignore', propagate NA values, without passing them to the
+            mapping function
+        convert : bool, default True
+            Try to find better dtype for elementwise function results. If
+            False, leave as dtype=object. Note that the dtype is always
+            preserved for some extension array dtypes, such as Categorical.
+
+        Returns
+        -------
+        Union[Index, MultiIndex], inferred
+            The output of the mapping function applied to the index.
+            If the function returns a tuple with more than one element
+            a MultiIndex will be returned.
+        """
+        arr = self._values
+
+        if isinstance(arr, ExtensionArray):
+            return arr.map(mapper, na_action=na_action)
+
+        return algorithms.map_array(arr, mapper, na_action=na_action, convert=convert)
+
+    @final
+    def value_counts(
+        self,
+        normalize: bool = False,
+        sort: bool = True,
+        ascending: bool = False,
+        bins=None,
+        dropna: bool = True,
+    ) -> Series:
+        """
+        Return a Series containing counts of unique values.
+
+        The resulting object will be in descending order so that the
+        first element is the most frequently-occurring element.
+        Excludes NA values by default.
+
+        Parameters
+        ----------
+        normalize : bool, default False
+            If True then the object returned will contain the relative
+            frequencies of the unique values.
+        sort : bool, default True
+            Sort by frequencies when True. Preserve the order of the data when False.
+        ascending : bool, default False
+            Sort in ascending order.
+        bins : int, optional
+            Rather than count values, group them into half-open bins,
+            a convenience for ``pd.cut``, only works with numeric data.
+        dropna : bool, default True
+            Don't include counts of NaN.
+
+        Returns
+        -------
+        Series
+
+        See Also
+        --------
+        Series.count: Number of non-NA elements in a Series.
+        DataFrame.count: Number of non-NA elements in a DataFrame.
+        DataFrame.value_counts: Equivalent method on DataFrames.
+
+        Examples
+        --------
+        >>> index = pd.Index([3, 1, 2, 3, 4, np.nan])
+        >>> index.value_counts()
+        3.0    2
+        1.0    1
+        2.0    1
+        4.0    1
+        Name: count, dtype: int64
+
+        With `normalize` set to `True`, returns the relative frequency by
+        dividing all values by the sum of values.
+
+        >>> s = pd.Series([3, 1, 2, 3, 4, np.nan])
+        >>> s.value_counts(normalize=True)
+        3.0    0.4
+        1.0    0.2
+        2.0    0.2
+        4.0    0.2
+        Name: proportion, dtype: float64
+
+        **bins**
+
+        Bins can be useful for going from a continuous variable to a
+        categorical variable; instead of counting unique
+        apparitions of values, divide the index in the specified
+        number of half-open bins.
+
+        >>> s.value_counts(bins=3)
+        (0.996, 2.0]    2
+        (2.0, 3.0]      2
+        (3.0, 4.0]      1
+        Name: count, dtype: int64
+
+        **dropna**
+
+        With `dropna` set to `False` we can also see NaN index values.
+
+        >>> s.value_counts(dropna=False)
+        3.0    2
+        1.0    1
+        2.0    1
+        4.0    1
+        NaN    1
+        Name: count, dtype: int64
+        """
+        return algorithms.value_counts_internal(
+            self,
+            sort=sort,
+            ascending=ascending,
+            normalize=normalize,
+            bins=bins,
+            dropna=dropna,
+        )
+
+    def unique(self):
+        values = self._values
+        if not isinstance(values, np.ndarray):
+            # i.e. ExtensionArray
+            result = values.unique()
+        else:
+            result = algorithms.unique1d(values)
+        return result
+
+    @final
+    def nunique(self, dropna: bool = True) -> int:
+        """
+        Return number of unique elements in the object.
+
+        Excludes NA values by default.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include NaN in the count.
+
+        Returns
+        -------
+        int
+
+        See Also
+        --------
+        DataFrame.nunique: Method nunique for DataFrame.
+        Series.count: Count non-NA/null observations in the Series.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 3, 5, 7, 7])
+        >>> s
+        0    1
+        1    3
+        2    5
+        3    7
+        4    7
+        dtype: int64
+
+        >>> s.nunique()
+        4
+        """
+        uniqs = self.unique()
+        if dropna:
+            uniqs = remove_na_arraylike(uniqs)
+        return len(uniqs)
+
+    @property
+    def is_unique(self) -> bool:
+        """
+        Return boolean if values in the object are unique.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.is_unique
+        True
+
+        >>> s = pd.Series([1, 2, 3, 1])
+        >>> s.is_unique
+        False
+        """
+        return self.nunique(dropna=False) == len(self)
+
+    @property
+    def is_monotonic_increasing(self) -> bool:
+        """
+        Return boolean if values in the object are monotonically increasing.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 2])
+        >>> s.is_monotonic_increasing
+        True
+
+        >>> s = pd.Series([3, 2, 1])
+        >>> s.is_monotonic_increasing
+        False
+        """
+        from pandas import Index
+
+        return Index(self).is_monotonic_increasing
+
+    @property
+    def is_monotonic_decreasing(self) -> bool:
+        """
+        Return boolean if values in the object are monotonically decreasing.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> s = pd.Series([3, 2, 2, 1])
+        >>> s.is_monotonic_decreasing
+        True
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.is_monotonic_decreasing
+        False
+        """
+        from pandas import Index
+
+        return Index(self).is_monotonic_decreasing
+
+    @final
+    def _memory_usage(self, deep: bool = False) -> int:
+        """
+        Memory usage of the values.
+
+        Parameters
+        ----------
+        deep : bool, default False
+            Introspect the data deeply, interrogate
+            `object` dtypes for system-level memory consumption.
+
+        Returns
+        -------
+        bytes used
+
+        See Also
+        --------
+        numpy.ndarray.nbytes : Total bytes consumed by the elements of the
+            array.
+
+        Notes
+        -----
+        Memory usage does not include memory consumed by elements that
+        are not components of the array if deep=False or if used on PyPy
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx.memory_usage()
+        24
+        """
+        if hasattr(self.array, "memory_usage"):
+            return self.array.memory_usage(  # pyright: ignore[reportGeneralTypeIssues]
+                deep=deep,
+            )
+
+        v = self.array.nbytes
+        if deep and is_object_dtype(self.dtype) and not PYPY:
+            values = cast(np.ndarray, self._values)
+            v += lib.memory_usage_of_objects(values)
+        return v
+
+    @doc(
+        algorithms.factorize,
+        values="",
+        order="",
+        size_hint="",
+        sort=textwrap.dedent(
+            """\
+            sort : bool, default False
+                Sort `uniques` and shuffle `codes` to maintain the
+                relationship.
+            """
+        ),
+    )
+    def factorize(
+        self,
+        sort: bool = False,
+        use_na_sentinel: bool = True,
+    ) -> tuple[npt.NDArray[np.intp], Index]:
+        codes, uniques = algorithms.factorize(
+            self._values, sort=sort, use_na_sentinel=use_na_sentinel
+        )
+        if uniques.dtype == np.float16:
+            uniques = uniques.astype(np.float32)
+
+        if isinstance(self, ABCMultiIndex):
+            # preserve MultiIndex
+            uniques = self._constructor(uniques)
+        else:
+            from pandas import Index
+
+            try:
+                uniques = Index(uniques, dtype=self.dtype)
+            except NotImplementedError:
+                # not all dtypes are supported in Index that are allowed for Series
+                # e.g. float16 or bytes
+                uniques = Index(uniques)
+        return codes, uniques
+
+    _shared_docs[
+        "searchsorted"
+    ] = """
+        Find indices where elements should be inserted to maintain order.
+
+        Find the indices into a sorted {klass} `self` such that, if the
+        corresponding elements in `value` were inserted before the indices,
+        the order of `self` would be preserved.
+
+        .. note::
+
+            The {klass} *must* be monotonically sorted, otherwise
+            wrong locations will likely be returned. Pandas does *not*
+            check this for you.
+
+        Parameters
+        ----------
+        value : array-like or scalar
+            Values to insert into `self`.
+        side : {{'left', 'right'}}, optional
+            If 'left', the index of the first suitable location found is given.
+            If 'right', return the last such index.  If there is no suitable
+            index, return either 0 or N (where N is the length of `self`).
+        sorter : 1-D array-like, optional
+            Optional array of integer indices that sort `self` into ascending
+            order. They are typically the result of ``np.argsort``.
+
+        Returns
+        -------
+        int or array of int
+            A scalar or array of insertion points with the
+            same shape as `value`.
+
+        See Also
+        --------
+        sort_values : Sort by the values along either axis.
+        numpy.searchsorted : Similar method from NumPy.
+
+        Notes
+        -----
+        Binary search is used to find the required insertion points.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3])
+        >>> ser
+        0    1
+        1    2
+        2    3
+        dtype: int64
+
+        >>> ser.searchsorted(4)
+        3
+
+        >>> ser.searchsorted([0, 4])
+        array([0, 3])
+
+        >>> ser.searchsorted([1, 3], side='left')
+        array([0, 2])
+
+        >>> ser.searchsorted([1, 3], side='right')
+        array([1, 3])
+
+        >>> ser = pd.Series(pd.to_datetime(['3/11/2000', '3/12/2000', '3/13/2000']))
+        >>> ser
+        0   2000-03-11
+        1   2000-03-12
+        2   2000-03-13
+        dtype: datetime64[ns]
+
+        >>> ser.searchsorted('3/14/2000')
+        3
+
+        >>> ser = pd.Categorical(
+        ...     ['apple', 'bread', 'bread', 'cheese', 'milk'], ordered=True
+        ... )
+        >>> ser
+        ['apple', 'bread', 'bread', 'cheese', 'milk']
+        Categories (4, object): ['apple' < 'bread' < 'cheese' < 'milk']
+
+        >>> ser.searchsorted('bread')
+        1
+
+        >>> ser.searchsorted(['bread'], side='right')
+        array([3])
+
+        If the values are not monotonically sorted, wrong locations
+        may be returned:
+
+        >>> ser = pd.Series([2, 1, 3])
+        >>> ser
+        0    2
+        1    1
+        2    3
+        dtype: int64
+
+        >>> ser.searchsorted(1)  # doctest: +SKIP
+        0  # wrong result, correct would be 1
+        """
+
+    # This overload is needed so that the call to searchsorted in
+    # pandas.core.resample.TimeGrouper._get_period_bins picks the correct result
+
+    # error: Overloaded function signatures 1 and 2 overlap with incompatible
+    # return types
+    @overload
+    def searchsorted(  # type: ignore[overload-overlap]
+        self,
+        value: ScalarLike_co,
+        side: Literal["left", "right"] = ...,
+        sorter: NumpySorter = ...,
+    ) -> np.intp:
+        ...
+
+    @overload
+    def searchsorted(
+        self,
+        value: npt.ArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = ...,
+        sorter: NumpySorter = ...,
+    ) -> npt.NDArray[np.intp]:
+        ...
+
+    @doc(_shared_docs["searchsorted"], klass="Index")
+    def searchsorted(
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        if isinstance(value, ABCDataFrame):
+            msg = (
+                "Value must be 1-D array-like or scalar, "
+                f"{type(value).__name__} is not supported"
+            )
+            raise ValueError(msg)
+
+        values = self._values
+        if not isinstance(values, np.ndarray):
+            # Going through EA.searchsorted directly improves performance GH#38083
+            return values.searchsorted(value, side=side, sorter=sorter)
+
+        return algorithms.searchsorted(
+            values,
+            value,
+            side=side,
+            sorter=sorter,
+        )
+
+    def drop_duplicates(self, *, keep: DropKeep = "first"):
+        duplicated = self._duplicated(keep=keep)
+        # error: Value of type "IndexOpsMixin" is not indexable
+        return self[~duplicated]  # type: ignore[index]
+
+    @final
+    def _duplicated(self, keep: DropKeep = "first") -> npt.NDArray[np.bool_]:
+        arr = self._values
+        if isinstance(arr, ExtensionArray):
+            return arr.duplicated(keep=keep)
+        return algorithms.duplicated(arr, keep=keep)
+
+    def _arith_method(self, other, op):
+        res_name = ops.get_op_result_name(self, other)
+
+        lvalues = self._values
+        rvalues = extract_array(other, extract_numpy=True, extract_range=True)
+        rvalues = ops.maybe_prepare_scalar_for_op(rvalues, lvalues.shape)
+        rvalues = ensure_wrapped_if_datetimelike(rvalues)
+        if isinstance(rvalues, range):
+            rvalues = np.arange(rvalues.start, rvalues.stop, rvalues.step)
+
+        with np.errstate(all="ignore"):
+            result = ops.arithmetic_op(lvalues, rvalues, op)
+
+        return self._construct_result(result, name=res_name)
+
+    def _construct_result(self, result, name):
+        """
+        Construct an appropriately-wrapped result from the ArrayLike result
+        of an arithmetic-like operation.
+        """
+        raise AbstractMethodError(self)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/common.py b/.venv/lib/python3.13/site-packages/pandas/core/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..9f024498d66edfe9cab7b6fb2e0802da79163786
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/common.py
@@ -0,0 +1,657 @@
+"""
+Misc tools for implementing data structures
+
+Note: pandas.core.common is *not* part of the public API.
+"""
+from __future__ import annotations
+
+import builtins
+from collections import (
+    abc,
+    defaultdict,
+)
+from collections.abc import (
+    Collection,
+    Generator,
+    Hashable,
+    Iterable,
+    Sequence,
+)
+import contextlib
+from functools import partial
+import inspect
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.compat.numpy import np_version_gte1p24
+
+from pandas.core.dtypes.cast import construct_1d_object_array_from_listlike
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_integer,
+)
+from pandas.core.dtypes.generic import (
+    ABCExtensionArray,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import iterable_not_string
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        AnyArrayLike,
+        ArrayLike,
+        NpDtype,
+        RandomState,
+        T,
+    )
+
+    from pandas import Index
+
+
+def flatten(line):
+    """
+    Flatten an arbitrarily nested sequence.
+
+    Parameters
+    ----------
+    line : sequence
+        The non string sequence to flatten
+
+    Notes
+    -----
+    This doesn't consider strings sequences.
+
+    Returns
+    -------
+    flattened : generator
+    """
+    for element in line:
+        if iterable_not_string(element):
+            yield from flatten(element)
+        else:
+            yield element
+
+
+def consensus_name_attr(objs):
+    name = objs[0].name
+    for obj in objs[1:]:
+        try:
+            if obj.name != name:
+                name = None
+        except ValueError:
+            name = None
+    return name
+
+
+def is_bool_indexer(key: Any) -> bool:
+    """
+    Check whether `key` is a valid boolean indexer.
+
+    Parameters
+    ----------
+    key : Any
+        Only list-likes may be considered boolean indexers.
+        All other types are not considered a boolean indexer.
+        For array-like input, boolean ndarrays or ExtensionArrays
+        with ``_is_boolean`` set are considered boolean indexers.
+
+    Returns
+    -------
+    bool
+        Whether `key` is a valid boolean indexer.
+
+    Raises
+    ------
+    ValueError
+        When the array is an object-dtype ndarray or ExtensionArray
+        and contains missing values.
+
+    See Also
+    --------
+    check_array_indexer : Check that `key` is a valid array to index,
+        and convert to an ndarray.
+    """
+    if isinstance(
+        key, (ABCSeries, np.ndarray, ABCIndex, ABCExtensionArray)
+    ) and not isinstance(key, ABCMultiIndex):
+        if key.dtype == np.object_:
+            key_array = np.asarray(key)
+
+            if not lib.is_bool_array(key_array):
+                na_msg = "Cannot mask with non-boolean array containing NA / NaN values"
+                if lib.is_bool_array(key_array, skipna=True):
+                    # Don't raise on e.g. ["A", "B", np.nan], see
+                    #  test_loc_getitem_list_of_labels_categoricalindex_with_na
+                    raise ValueError(na_msg)
+                return False
+            return True
+        elif is_bool_dtype(key.dtype):
+            return True
+    elif isinstance(key, list):
+        # check if np.array(key).dtype would be bool
+        if len(key) > 0:
+            if type(key) is not list:  # noqa: E721
+                # GH#42461 cython will raise TypeError if we pass a subclass
+                key = list(key)
+            return lib.is_bool_list(key)
+
+    return False
+
+
+def cast_scalar_indexer(val):
+    """
+    Disallow indexing with a float key, even if that key is a round number.
+
+    Parameters
+    ----------
+    val : scalar
+
+    Returns
+    -------
+    outval : scalar
+    """
+    # assumes lib.is_scalar(val)
+    if lib.is_float(val) and val.is_integer():
+        raise IndexError(
+            # GH#34193
+            "Indexing with a float is no longer supported. Manually convert "
+            "to an integer key instead."
+        )
+    return val
+
+
+def not_none(*args):
+    """
+    Returns a generator consisting of the arguments that are not None.
+    """
+    return (arg for arg in args if arg is not None)
+
+
+def any_none(*args) -> bool:
+    """
+    Returns a boolean indicating if any argument is None.
+    """
+    return any(arg is None for arg in args)
+
+
+def all_none(*args) -> bool:
+    """
+    Returns a boolean indicating if all arguments are None.
+    """
+    return all(arg is None for arg in args)
+
+
+def any_not_none(*args) -> bool:
+    """
+    Returns a boolean indicating if any argument is not None.
+    """
+    return any(arg is not None for arg in args)
+
+
+def all_not_none(*args) -> bool:
+    """
+    Returns a boolean indicating if all arguments are not None.
+    """
+    return all(arg is not None for arg in args)
+
+
+def count_not_none(*args) -> int:
+    """
+    Returns the count of arguments that are not None.
+    """
+    return sum(x is not None for x in args)
+
+
+@overload
+def asarray_tuplesafe(
+    values: ArrayLike | list | tuple | zip, dtype: NpDtype | None = ...
+) -> np.ndarray:
+    # ExtensionArray can only be returned when values is an Index, all other iterables
+    # will return np.ndarray. Unfortunately "all other" cannot be encoded in a type
+    # signature, so instead we special-case some common types.
+    ...
+
+
+@overload
+def asarray_tuplesafe(values: Iterable, dtype: NpDtype | None = ...) -> ArrayLike:
+    ...
+
+
+def asarray_tuplesafe(values: Iterable, dtype: NpDtype | None = None) -> ArrayLike:
+    if not (isinstance(values, (list, tuple)) or hasattr(values, "__array__")):
+        values = list(values)
+    elif isinstance(values, ABCIndex):
+        return values._values
+    elif isinstance(values, ABCSeries):
+        return values._values
+
+    if isinstance(values, list) and dtype in [np.object_, object]:
+        return construct_1d_object_array_from_listlike(values)
+
+    try:
+        with warnings.catch_warnings():
+            # Can remove warning filter once NumPy 1.24 is min version
+            if not np_version_gte1p24:
+                warnings.simplefilter("ignore", np.VisibleDeprecationWarning)
+            result = np.asarray(values, dtype=dtype)
+    except ValueError:
+        # Using try/except since it's more performant than checking is_list_like
+        # over each element
+        # error: Argument 1 to "construct_1d_object_array_from_listlike"
+        # has incompatible type "Iterable[Any]"; expected "Sized"
+        return construct_1d_object_array_from_listlike(values)  # type: ignore[arg-type]
+
+    if issubclass(result.dtype.type, str):
+        result = np.asarray(values, dtype=object)
+
+    if result.ndim == 2:
+        # Avoid building an array of arrays:
+        values = [tuple(x) for x in values]
+        result = construct_1d_object_array_from_listlike(values)
+
+    return result
+
+
+def index_labels_to_array(
+    labels: np.ndarray | Iterable, dtype: NpDtype | None = None
+) -> np.ndarray:
+    """
+    Transform label or iterable of labels to array, for use in Index.
+
+    Parameters
+    ----------
+    dtype : dtype
+        If specified, use as dtype of the resulting array, otherwise infer.
+
+    Returns
+    -------
+    array
+    """
+    if isinstance(labels, (str, tuple)):
+        labels = [labels]
+
+    if not isinstance(labels, (list, np.ndarray)):
+        try:
+            labels = list(labels)
+        except TypeError:  # non-iterable
+            labels = [labels]
+
+    labels = asarray_tuplesafe(labels, dtype=dtype)
+
+    return labels
+
+
+def maybe_make_list(obj):
+    if obj is not None and not isinstance(obj, (tuple, list)):
+        return [obj]
+    return obj
+
+
+def maybe_iterable_to_list(obj: Iterable[T] | T) -> Collection[T] | T:
+    """
+    If obj is Iterable but not list-like, consume into list.
+    """
+    if isinstance(obj, abc.Iterable) and not isinstance(obj, abc.Sized):
+        return list(obj)
+    obj = cast(Collection, obj)
+    return obj
+
+
+def is_null_slice(obj) -> bool:
+    """
+    We have a null slice.
+    """
+    return (
+        isinstance(obj, slice)
+        and obj.start is None
+        and obj.stop is None
+        and obj.step is None
+    )
+
+
+def is_empty_slice(obj) -> bool:
+    """
+    We have an empty slice, e.g. no values are selected.
+    """
+    return (
+        isinstance(obj, slice)
+        and obj.start is not None
+        and obj.stop is not None
+        and obj.start == obj.stop
+    )
+
+
+def is_true_slices(line) -> list[bool]:
+    """
+    Find non-trivial slices in "line": return a list of booleans with same length.
+    """
+    return [isinstance(k, slice) and not is_null_slice(k) for k in line]
+
+
+# TODO: used only once in indexing; belongs elsewhere?
+def is_full_slice(obj, line: int) -> bool:
+    """
+    We have a full length slice.
+    """
+    return (
+        isinstance(obj, slice)
+        and obj.start == 0
+        and obj.stop == line
+        and obj.step is None
+    )
+
+
+def get_callable_name(obj):
+    # typical case has name
+    if hasattr(obj, "__name__"):
+        return getattr(obj, "__name__")
+    # some objects don't; could recurse
+    if isinstance(obj, partial):
+        return get_callable_name(obj.func)
+    # fall back to class name
+    if callable(obj):
+        return type(obj).__name__
+    # everything failed (probably because the argument
+    # wasn't actually callable); we return None
+    # instead of the empty string in this case to allow
+    # distinguishing between no name and a name of ''
+    return None
+
+
+def apply_if_callable(maybe_callable, obj, **kwargs):
+    """
+    Evaluate possibly callable input using obj and kwargs if it is callable,
+    otherwise return as it is.
+
+    Parameters
+    ----------
+    maybe_callable : possibly a callable
+    obj : NDFrame
+    **kwargs
+    """
+    if callable(maybe_callable):
+        return maybe_callable(obj, **kwargs)
+
+    return maybe_callable
+
+
+def standardize_mapping(into):
+    """
+    Helper function to standardize a supplied mapping.
+
+    Parameters
+    ----------
+    into : instance or subclass of collections.abc.Mapping
+        Must be a class, an initialized collections.defaultdict,
+        or an instance of a collections.abc.Mapping subclass.
+
+    Returns
+    -------
+    mapping : a collections.abc.Mapping subclass or other constructor
+        a callable object that can accept an iterator to create
+        the desired Mapping.
+
+    See Also
+    --------
+    DataFrame.to_dict
+    Series.to_dict
+    """
+    if not inspect.isclass(into):
+        if isinstance(into, defaultdict):
+            return partial(defaultdict, into.default_factory)
+        into = type(into)
+    if not issubclass(into, abc.Mapping):
+        raise TypeError(f"unsupported type: {into}")
+    if into == defaultdict:
+        raise TypeError("to_dict() only accepts initialized defaultdicts")
+    return into
+
+
+@overload
+def random_state(state: np.random.Generator) -> np.random.Generator:
+    ...
+
+
+@overload
+def random_state(
+    state: int | np.ndarray | np.random.BitGenerator | np.random.RandomState | None,
+) -> np.random.RandomState:
+    ...
+
+
+def random_state(state: RandomState | None = None):
+    """
+    Helper function for processing random_state arguments.
+
+    Parameters
+    ----------
+    state : int, array-like, BitGenerator, Generator, np.random.RandomState, None.
+        If receives an int, array-like, or BitGenerator, passes to
+        np.random.RandomState() as seed.
+        If receives an np.random RandomState or Generator, just returns that unchanged.
+        If receives `None`, returns np.random.
+        If receives anything else, raises an informative ValueError.
+
+        Default None.
+
+    Returns
+    -------
+    np.random.RandomState or np.random.Generator. If state is None, returns np.random
+
+    """
+    if is_integer(state) or isinstance(state, (np.ndarray, np.random.BitGenerator)):
+        return np.random.RandomState(state)
+    elif isinstance(state, np.random.RandomState):
+        return state
+    elif isinstance(state, np.random.Generator):
+        return state
+    elif state is None:
+        return np.random
+    else:
+        raise ValueError(
+            "random_state must be an integer, array-like, a BitGenerator, Generator, "
+            "a numpy RandomState, or None"
+        )
+
+
+def pipe(
+    obj, func: Callable[..., T] | tuple[Callable[..., T], str], *args, **kwargs
+) -> T:
+    """
+    Apply a function ``func`` to object ``obj`` either by passing obj as the
+    first argument to the function or, in the case that the func is a tuple,
+    interpret the first element of the tuple as a function and pass the obj to
+    that function as a keyword argument whose key is the value of the second
+    element of the tuple.
+
+    Parameters
+    ----------
+    func : callable or tuple of (callable, str)
+        Function to apply to this object or, alternatively, a
+        ``(callable, data_keyword)`` tuple where ``data_keyword`` is a
+        string indicating the keyword of ``callable`` that expects the
+        object.
+    *args : iterable, optional
+        Positional arguments passed into ``func``.
+    **kwargs : dict, optional
+        A dictionary of keyword arguments passed into ``func``.
+
+    Returns
+    -------
+    object : the return type of ``func``.
+    """
+    if isinstance(func, tuple):
+        func, target = func
+        if target in kwargs:
+            msg = f"{target} is both the pipe target and a keyword argument"
+            raise ValueError(msg)
+        kwargs[target] = obj
+        return func(*args, **kwargs)
+    else:
+        return func(obj, *args, **kwargs)
+
+
+def get_rename_function(mapper):
+    """
+    Returns a function that will map names/labels, dependent if mapper
+    is a dict, Series or just a function.
+    """
+
+    def f(x):
+        if x in mapper:
+            return mapper[x]
+        else:
+            return x
+
+    return f if isinstance(mapper, (abc.Mapping, ABCSeries)) else mapper
+
+
+def convert_to_list_like(
+    values: Hashable | Iterable | AnyArrayLike,
+) -> list | AnyArrayLike:
+    """
+    Convert list-like or scalar input to list-like. List, numpy and pandas array-like
+    inputs are returned unmodified whereas others are converted to list.
+    """
+    if isinstance(values, (list, np.ndarray, ABCIndex, ABCSeries, ABCExtensionArray)):
+        return values
+    elif isinstance(values, abc.Iterable) and not isinstance(values, str):
+        return list(values)
+
+    return [values]
+
+
+@contextlib.contextmanager
+def temp_setattr(
+    obj, attr: str, value, condition: bool = True
+) -> Generator[None, None, None]:
+    """
+    Temporarily set attribute on an object.
+
+    Parameters
+    ----------
+    obj : object
+        Object whose attribute will be modified.
+    attr : str
+        Attribute to modify.
+    value : Any
+        Value to temporarily set attribute to.
+    condition : bool, default True
+        Whether to set the attribute. Provided in order to not have to
+        conditionally use this context manager.
+
+    Yields
+    ------
+    object : obj with modified attribute.
+    """
+    if condition:
+        old_value = getattr(obj, attr)
+        setattr(obj, attr, value)
+    try:
+        yield obj
+    finally:
+        if condition:
+            setattr(obj, attr, old_value)
+
+
+def require_length_match(data, index: Index) -> None:
+    """
+    Check the length of data matches the length of the index.
+    """
+    if len(data) != len(index):
+        raise ValueError(
+            "Length of values "
+            f"({len(data)}) "
+            "does not match length of index "
+            f"({len(index)})"
+        )
+
+
+# the ufuncs np.maximum.reduce and np.minimum.reduce default to axis=0,
+#  whereas np.min and np.max (which directly call obj.min and obj.max)
+#  default to axis=None.
+_builtin_table = {
+    builtins.sum: np.sum,
+    builtins.max: np.maximum.reduce,
+    builtins.min: np.minimum.reduce,
+}
+
+# GH#53425: Only for deprecation
+_builtin_table_alias = {
+    builtins.sum: "np.sum",
+    builtins.max: "np.maximum.reduce",
+    builtins.min: "np.minimum.reduce",
+}
+
+_cython_table = {
+    builtins.sum: "sum",
+    builtins.max: "max",
+    builtins.min: "min",
+    np.all: "all",
+    np.any: "any",
+    np.sum: "sum",
+    np.nansum: "sum",
+    np.mean: "mean",
+    np.nanmean: "mean",
+    np.prod: "prod",
+    np.nanprod: "prod",
+    np.std: "std",
+    np.nanstd: "std",
+    np.var: "var",
+    np.nanvar: "var",
+    np.median: "median",
+    np.nanmedian: "median",
+    np.max: "max",
+    np.nanmax: "max",
+    np.min: "min",
+    np.nanmin: "min",
+    np.cumprod: "cumprod",
+    np.nancumprod: "cumprod",
+    np.cumsum: "cumsum",
+    np.nancumsum: "cumsum",
+}
+
+
+def get_cython_func(arg: Callable) -> str | None:
+    """
+    if we define an internal function for this argument, return it
+    """
+    return _cython_table.get(arg)
+
+
+def is_builtin_func(arg):
+    """
+    if we define a builtin function for this argument, return it,
+    otherwise return the arg
+    """
+    return _builtin_table.get(arg, arg)
+
+
+def fill_missing_names(names: Sequence[Hashable | None]) -> list[Hashable]:
+    """
+    If a name is missing then replace it by level_n, where n is the count
+
+    .. versionadded:: 1.4.0
+
+    Parameters
+    ----------
+    names : list-like
+        list of column names or None values.
+
+    Returns
+    -------
+    list
+        list of column names with the None values replaced.
+    """
+    return [f"level_{i}" if name is None else name for i, name in enumerate(names)]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/align.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/align.py
new file mode 100644
index 0000000000000000000000000000000000000000..cd852ba9249cf26ea39b7e51bbfa754ffe9c10ce
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/align.py
@@ -0,0 +1,213 @@
+"""
+Core eval alignment algorithms.
+"""
+from __future__ import annotations
+
+from functools import (
+    partial,
+    wraps,
+)
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+import warnings
+
+import numpy as np
+
+from pandas.errors import PerformanceWarning
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+from pandas.core.base import PandasObject
+import pandas.core.common as com
+from pandas.core.computation.common import result_type_many
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import F
+
+    from pandas.core.generic import NDFrame
+    from pandas.core.indexes.api import Index
+
+
+def _align_core_single_unary_op(
+    term,
+) -> tuple[partial | type[NDFrame], dict[str, Index] | None]:
+    typ: partial | type[NDFrame]
+    axes: dict[str, Index] | None = None
+
+    if isinstance(term.value, np.ndarray):
+        typ = partial(np.asanyarray, dtype=term.value.dtype)
+    else:
+        typ = type(term.value)
+        if hasattr(term.value, "axes"):
+            axes = _zip_axes_from_type(typ, term.value.axes)
+
+    return typ, axes
+
+
+def _zip_axes_from_type(
+    typ: type[NDFrame], new_axes: Sequence[Index]
+) -> dict[str, Index]:
+    return {name: new_axes[i] for i, name in enumerate(typ._AXIS_ORDERS)}
+
+
+def _any_pandas_objects(terms) -> bool:
+    """
+    Check a sequence of terms for instances of PandasObject.
+    """
+    return any(isinstance(term.value, PandasObject) for term in terms)
+
+
+def _filter_special_cases(f) -> Callable[[F], F]:
+    @wraps(f)
+    def wrapper(terms):
+        # single unary operand
+        if len(terms) == 1:
+            return _align_core_single_unary_op(terms[0])
+
+        term_values = (term.value for term in terms)
+
+        # we don't have any pandas objects
+        if not _any_pandas_objects(terms):
+            return result_type_many(*term_values), None
+
+        return f(terms)
+
+    return wrapper
+
+
+@_filter_special_cases
+def _align_core(terms):
+    term_index = [i for i, term in enumerate(terms) if hasattr(term.value, "axes")]
+    term_dims = [terms[i].value.ndim for i in term_index]
+
+    from pandas import Series
+
+    ndims = Series(dict(zip(term_index, term_dims)))
+
+    # initial axes are the axes of the largest-axis'd term
+    biggest = terms[ndims.idxmax()].value
+    typ = biggest._constructor
+    axes = biggest.axes
+    naxes = len(axes)
+    gt_than_one_axis = naxes > 1
+
+    for value in (terms[i].value for i in term_index):
+        is_series = isinstance(value, ABCSeries)
+        is_series_and_gt_one_axis = is_series and gt_than_one_axis
+
+        for axis, items in enumerate(value.axes):
+            if is_series_and_gt_one_axis:
+                ax, itm = naxes - 1, value.index
+            else:
+                ax, itm = axis, items
+
+            if not axes[ax].is_(itm):
+                axes[ax] = axes[ax].union(itm)
+
+    for i, ndim in ndims.items():
+        for axis, items in zip(range(ndim), axes):
+            ti = terms[i].value
+
+            if hasattr(ti, "reindex"):
+                transpose = isinstance(ti, ABCSeries) and naxes > 1
+                reindexer = axes[naxes - 1] if transpose else items
+
+                term_axis_size = len(ti.axes[axis])
+                reindexer_size = len(reindexer)
+
+                ordm = np.log10(max(1, abs(reindexer_size - term_axis_size)))
+                if ordm >= 1 and reindexer_size >= 10000:
+                    w = (
+                        f"Alignment difference on axis {axis} is larger "
+                        f"than an order of magnitude on term {repr(terms[i].name)}, "
+                        f"by more than {ordm:.4g}; performance may suffer."
+                    )
+                    warnings.warn(
+                        w, category=PerformanceWarning, stacklevel=find_stack_level()
+                    )
+
+                obj = ti.reindex(reindexer, axis=axis, copy=False)
+                terms[i].update(obj)
+
+        terms[i].update(terms[i].value.values)
+
+    return typ, _zip_axes_from_type(typ, axes)
+
+
+def align_terms(terms):
+    """
+    Align a set of terms.
+    """
+    try:
+        # flatten the parse tree (a nested list, really)
+        terms = list(com.flatten(terms))
+    except TypeError:
+        # can't iterate so it must just be a constant or single variable
+        if isinstance(terms.value, (ABCSeries, ABCDataFrame)):
+            typ = type(terms.value)
+            return typ, _zip_axes_from_type(typ, terms.value.axes)
+        return np.result_type(terms.type), None
+
+    # if all resolved variables are numeric scalars
+    if all(term.is_scalar for term in terms):
+        return result_type_many(*(term.value for term in terms)).type, None
+
+    # perform the main alignment
+    typ, axes = _align_core(terms)
+    return typ, axes
+
+
+def reconstruct_object(typ, obj, axes, dtype):
+    """
+    Reconstruct an object given its type, raw value, and possibly empty
+    (None) axes.
+
+    Parameters
+    ----------
+    typ : object
+        A type
+    obj : object
+        The value to use in the type constructor
+    axes : dict
+        The axes to use to construct the resulting pandas object
+
+    Returns
+    -------
+    ret : typ
+        An object of type ``typ`` with the value `obj` and possible axes
+        `axes`.
+    """
+    try:
+        typ = typ.type
+    except AttributeError:
+        pass
+
+    res_t = np.result_type(obj.dtype, dtype)
+
+    if not isinstance(typ, partial) and issubclass(typ, PandasObject):
+        return typ(obj, dtype=res_t, **axes)
+
+    # special case for pathological things like ~True/~False
+    if hasattr(res_t, "type") and typ == np.bool_ and res_t != np.bool_:
+        ret_value = res_t.type(obj)
+    else:
+        ret_value = typ(obj).astype(res_t)
+        # The condition is to distinguish 0-dim array (returned in case of
+        # scalar) and 1 element array
+        # e.g. np.array(0) and np.array([0])
+        if (
+            len(obj.shape) == 1
+            and len(obj) == 1
+            and not isinstance(ret_value, np.ndarray)
+        ):
+            ret_value = np.array([ret_value]).astype(res_t)
+
+    return ret_value
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/api.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..bd3be5b3f8c42267c8a61421b7f0877a01b33d34
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/api.py
@@ -0,0 +1,2 @@
+__all__ = ["eval"]
+from pandas.core.computation.eval import eval
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/check.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/check.py
new file mode 100644
index 0000000000000000000000000000000000000000..caccf34f811112abbe04d965d6f6be1e21527e8b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/check.py
@@ -0,0 +1,8 @@
+from __future__ import annotations
+
+from pandas.compat._optional import import_optional_dependency
+
+ne = import_optional_dependency("numexpr", errors="warn")
+NUMEXPR_INSTALLED = ne is not None
+
+__all__ = ["NUMEXPR_INSTALLED"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/common.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..115191829f044a7d6d7f17c279025ccc26d44d04
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/common.py
@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from functools import reduce
+
+import numpy as np
+
+from pandas._config import get_option
+
+
+def ensure_decoded(s) -> str:
+    """
+    If we have bytes, decode them to unicode.
+    """
+    if isinstance(s, (np.bytes_, bytes)):
+        s = s.decode(get_option("display.encoding"))
+    return s
+
+
+def result_type_many(*arrays_and_dtypes):
+    """
+    Wrapper around numpy.result_type which overcomes the NPY_MAXARGS (32)
+    argument limit.
+    """
+    try:
+        return np.result_type(*arrays_and_dtypes)
+    except ValueError:
+        # we have > NPY_MAXARGS terms in our expression
+        return reduce(np.result_type, arrays_and_dtypes)
+    except TypeError:
+        from pandas.core.dtypes.cast import find_common_type
+        from pandas.core.dtypes.common import is_extension_array_dtype
+
+        arr_and_dtypes = list(arrays_and_dtypes)
+        ea_dtypes, non_ea_dtypes = [], []
+        for arr_or_dtype in arr_and_dtypes:
+            if is_extension_array_dtype(arr_or_dtype):
+                ea_dtypes.append(arr_or_dtype)
+            else:
+                non_ea_dtypes.append(arr_or_dtype)
+
+        if non_ea_dtypes:
+            try:
+                np_dtype = np.result_type(*non_ea_dtypes)
+            except ValueError:
+                np_dtype = reduce(np.result_type, arrays_and_dtypes)
+            return find_common_type(ea_dtypes + [np_dtype])
+
+        return find_common_type(ea_dtypes)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/engines.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/engines.py
new file mode 100644
index 0000000000000000000000000000000000000000..a3a05a9d75c6ed6b80564a69ff5b6cf5a648c1b3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/engines.py
@@ -0,0 +1,143 @@
+"""
+Engine classes for :func:`~pandas.eval`
+"""
+from __future__ import annotations
+
+import abc
+from typing import TYPE_CHECKING
+
+from pandas.errors import NumExprClobberingError
+
+from pandas.core.computation.align import (
+    align_terms,
+    reconstruct_object,
+)
+from pandas.core.computation.ops import (
+    MATHOPS,
+    REDUCTIONS,
+)
+
+from pandas.io.formats import printing
+
+if TYPE_CHECKING:
+    from pandas.core.computation.expr import Expr
+
+_ne_builtins = frozenset(MATHOPS + REDUCTIONS)
+
+
+def _check_ne_builtin_clash(expr: Expr) -> None:
+    """
+    Attempt to prevent foot-shooting in a helpful way.
+
+    Parameters
+    ----------
+    expr : Expr
+        Terms can contain
+    """
+    names = expr.names
+    overlap = names & _ne_builtins
+
+    if overlap:
+        s = ", ".join([repr(x) for x in overlap])
+        raise NumExprClobberingError(
+            f'Variables in expression "{expr}" overlap with builtins: ({s})'
+        )
+
+
+class AbstractEngine(metaclass=abc.ABCMeta):
+    """Object serving as a base class for all engines."""
+
+    has_neg_frac = False
+
+    def __init__(self, expr) -> None:
+        self.expr = expr
+        self.aligned_axes = None
+        self.result_type = None
+
+    def convert(self) -> str:
+        """
+        Convert an expression for evaluation.
+
+        Defaults to return the expression as a string.
+        """
+        return printing.pprint_thing(self.expr)
+
+    def evaluate(self) -> object:
+        """
+        Run the engine on the expression.
+
+        This method performs alignment which is necessary no matter what engine
+        is being used, thus its implementation is in the base class.
+
+        Returns
+        -------
+        object
+            The result of the passed expression.
+        """
+        if not self._is_aligned:
+            self.result_type, self.aligned_axes = align_terms(self.expr.terms)
+
+        # make sure no names in resolvers and locals/globals clash
+        res = self._evaluate()
+        return reconstruct_object(
+            self.result_type, res, self.aligned_axes, self.expr.terms.return_type
+        )
+
+    @property
+    def _is_aligned(self) -> bool:
+        return self.aligned_axes is not None and self.result_type is not None
+
+    @abc.abstractmethod
+    def _evaluate(self):
+        """
+        Return an evaluated expression.
+
+        Parameters
+        ----------
+        env : Scope
+            The local and global environment in which to evaluate an
+            expression.
+
+        Notes
+        -----
+        Must be implemented by subclasses.
+        """
+
+
+class NumExprEngine(AbstractEngine):
+    """NumExpr engine class"""
+
+    has_neg_frac = True
+
+    def _evaluate(self):
+        import numexpr as ne
+
+        # convert the expression to a valid numexpr expression
+        s = self.convert()
+
+        env = self.expr.env
+        scope = env.full_scope
+        _check_ne_builtin_clash(self.expr)
+        return ne.evaluate(s, local_dict=scope)
+
+
+class PythonEngine(AbstractEngine):
+    """
+    Evaluate an expression in Python space.
+
+    Mostly for testing purposes.
+    """
+
+    has_neg_frac = False
+
+    def evaluate(self):
+        return self.expr()
+
+    def _evaluate(self) -> None:
+        pass
+
+
+ENGINES: dict[str, type[AbstractEngine]] = {
+    "numexpr": NumExprEngine,
+    "python": PythonEngine,
+}
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/eval.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/eval.py
new file mode 100644
index 0000000000000000000000000000000000000000..7bb623cba375539072e462cb1180f4ac85221ee1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/eval.py
@@ -0,0 +1,421 @@
+"""
+Top level ``eval`` module.
+"""
+from __future__ import annotations
+
+import tokenize
+from typing import TYPE_CHECKING
+import warnings
+
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_bool_kwarg
+
+from pandas.core.dtypes.common import (
+    is_extension_array_dtype,
+    is_string_dtype,
+)
+
+from pandas.core.computation.engines import ENGINES
+from pandas.core.computation.expr import (
+    PARSERS,
+    Expr,
+)
+from pandas.core.computation.parsing import tokenize_string
+from pandas.core.computation.scope import ensure_scope
+from pandas.core.generic import NDFrame
+
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from pandas.core.computation.ops import BinOp
+
+
+def _check_engine(engine: str | None) -> str:
+    """
+    Make sure a valid engine is passed.
+
+    Parameters
+    ----------
+    engine : str
+        String to validate.
+
+    Raises
+    ------
+    KeyError
+      * If an invalid engine is passed.
+    ImportError
+      * If numexpr was requested but doesn't exist.
+
+    Returns
+    -------
+    str
+        Engine name.
+    """
+    from pandas.core.computation.check import NUMEXPR_INSTALLED
+    from pandas.core.computation.expressions import USE_NUMEXPR
+
+    if engine is None:
+        engine = "numexpr" if USE_NUMEXPR else "python"
+
+    if engine not in ENGINES:
+        valid_engines = list(ENGINES.keys())
+        raise KeyError(
+            f"Invalid engine '{engine}' passed, valid engines are {valid_engines}"
+        )
+
+    # TODO: validate this in a more general way (thinking of future engines
+    # that won't necessarily be import-able)
+    # Could potentially be done on engine instantiation
+    if engine == "numexpr" and not NUMEXPR_INSTALLED:
+        raise ImportError(
+            "'numexpr' is not installed or an unsupported version. Cannot use "
+            "engine='numexpr' for query/eval if 'numexpr' is not installed"
+        )
+
+    return engine
+
+
+def _check_parser(parser: str):
+    """
+    Make sure a valid parser is passed.
+
+    Parameters
+    ----------
+    parser : str
+
+    Raises
+    ------
+    KeyError
+      * If an invalid parser is passed
+    """
+    if parser not in PARSERS:
+        raise KeyError(
+            f"Invalid parser '{parser}' passed, valid parsers are {PARSERS.keys()}"
+        )
+
+
+def _check_resolvers(resolvers):
+    if resolvers is not None:
+        for resolver in resolvers:
+            if not hasattr(resolver, "__getitem__"):
+                name = type(resolver).__name__
+                raise TypeError(
+                    f"Resolver of type '{name}' does not "
+                    "implement the __getitem__ method"
+                )
+
+
+def _check_expression(expr):
+    """
+    Make sure an expression is not an empty string
+
+    Parameters
+    ----------
+    expr : object
+        An object that can be converted to a string
+
+    Raises
+    ------
+    ValueError
+      * If expr is an empty string
+    """
+    if not expr:
+        raise ValueError("expr cannot be an empty string")
+
+
+def _convert_expression(expr) -> str:
+    """
+    Convert an object to an expression.
+
+    This function converts an object to an expression (a unicode string) and
+    checks to make sure it isn't empty after conversion. This is used to
+    convert operators to their string representation for recursive calls to
+    :func:`~pandas.eval`.
+
+    Parameters
+    ----------
+    expr : object
+        The object to be converted to a string.
+
+    Returns
+    -------
+    str
+        The string representation of an object.
+
+    Raises
+    ------
+    ValueError
+      * If the expression is empty.
+    """
+    s = pprint_thing(expr)
+    _check_expression(s)
+    return s
+
+
+def _check_for_locals(expr: str, stack_level: int, parser: str):
+    at_top_of_stack = stack_level == 0
+    not_pandas_parser = parser != "pandas"
+
+    if not_pandas_parser:
+        msg = "The '@' prefix is only supported by the pandas parser"
+    elif at_top_of_stack:
+        msg = (
+            "The '@' prefix is not allowed in top-level eval calls.\n"
+            "please refer to your variables by name without the '@' prefix."
+        )
+
+    if at_top_of_stack or not_pandas_parser:
+        for toknum, tokval in tokenize_string(expr):
+            if toknum == tokenize.OP and tokval == "@":
+                raise SyntaxError(msg)
+
+
+def eval(
+    expr: str | BinOp,  # we leave BinOp out of the docstr bc it isn't for users
+    parser: str = "pandas",
+    engine: str | None = None,
+    local_dict=None,
+    global_dict=None,
+    resolvers=(),
+    level: int = 0,
+    target=None,
+    inplace: bool = False,
+):
+    """
+    Evaluate a Python expression as a string using various backends.
+
+    The following arithmetic operations are supported: ``+``, ``-``, ``*``,
+    ``/``, ``**``, ``%``, ``//`` (python engine only) along with the following
+    boolean operations: ``|`` (or), ``&`` (and), and ``~`` (not).
+    Additionally, the ``'pandas'`` parser allows the use of :keyword:`and`,
+    :keyword:`or`, and :keyword:`not` with the same semantics as the
+    corresponding bitwise operators.  :class:`~pandas.Series` and
+    :class:`~pandas.DataFrame` objects are supported and behave as they would
+    with plain ol' Python evaluation.
+
+    Parameters
+    ----------
+    expr : str
+        The expression to evaluate. This string cannot contain any Python
+        `statements
+        `__,
+        only Python `expressions
+        `__.
+    parser : {'pandas', 'python'}, default 'pandas'
+        The parser to use to construct the syntax tree from the expression. The
+        default of ``'pandas'`` parses code slightly different than standard
+        Python. Alternatively, you can parse an expression using the
+        ``'python'`` parser to retain strict Python semantics.  See the
+        :ref:`enhancing performance ` documentation for
+        more details.
+    engine : {'python', 'numexpr'}, default 'numexpr'
+
+        The engine used to evaluate the expression. Supported engines are
+
+        - None : tries to use ``numexpr``, falls back to ``python``
+        - ``'numexpr'`` : This default engine evaluates pandas objects using
+          numexpr for large speed ups in complex expressions with large frames.
+        - ``'python'`` : Performs operations as if you had ``eval``'d in top
+          level python. This engine is generally not that useful.
+
+        More backends may be available in the future.
+    local_dict : dict or None, optional
+        A dictionary of local variables, taken from locals() by default.
+    global_dict : dict or None, optional
+        A dictionary of global variables, taken from globals() by default.
+    resolvers : list of dict-like or None, optional
+        A list of objects implementing the ``__getitem__`` special method that
+        you can use to inject an additional collection of namespaces to use for
+        variable lookup. For example, this is used in the
+        :meth:`~DataFrame.query` method to inject the
+        ``DataFrame.index`` and ``DataFrame.columns``
+        variables that refer to their respective :class:`~pandas.DataFrame`
+        instance attributes.
+    level : int, optional
+        The number of prior stack frames to traverse and add to the current
+        scope. Most users will **not** need to change this parameter.
+    target : object, optional, default None
+        This is the target object for assignment. It is used when there is
+        variable assignment in the expression. If so, then `target` must
+        support item assignment with string keys, and if a copy is being
+        returned, it must also support `.copy()`.
+    inplace : bool, default False
+        If `target` is provided, and the expression mutates `target`, whether
+        to modify `target` inplace. Otherwise, return a copy of `target` with
+        the mutation.
+
+    Returns
+    -------
+    ndarray, numeric scalar, DataFrame, Series, or None
+        The completion value of evaluating the given code or None if ``inplace=True``.
+
+    Raises
+    ------
+    ValueError
+        There are many instances where such an error can be raised:
+
+        - `target=None`, but the expression is multiline.
+        - The expression is multiline, but not all them have item assignment.
+          An example of such an arrangement is this:
+
+          a = b + 1
+          a + 2
+
+          Here, there are expressions on different lines, making it multiline,
+          but the last line has no variable assigned to the output of `a + 2`.
+        - `inplace=True`, but the expression is missing item assignment.
+        - Item assignment is provided, but the `target` does not support
+          string item assignment.
+        - Item assignment is provided and `inplace=False`, but the `target`
+          does not support the `.copy()` method
+
+    See Also
+    --------
+    DataFrame.query : Evaluates a boolean expression to query the columns
+            of a frame.
+    DataFrame.eval : Evaluate a string describing operations on
+            DataFrame columns.
+
+    Notes
+    -----
+    The ``dtype`` of any objects involved in an arithmetic ``%`` operation are
+    recursively cast to ``float64``.
+
+    See the :ref:`enhancing performance ` documentation for
+    more details.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"animal": ["dog", "pig"], "age": [10, 20]})
+    >>> df
+      animal  age
+    0    dog   10
+    1    pig   20
+
+    We can add a new column using ``pd.eval``:
+
+    >>> pd.eval("double_age = df.age * 2", target=df)
+      animal  age  double_age
+    0    dog   10          20
+    1    pig   20          40
+    """
+    inplace = validate_bool_kwarg(inplace, "inplace")
+
+    exprs: list[str | BinOp]
+    if isinstance(expr, str):
+        _check_expression(expr)
+        exprs = [e.strip() for e in expr.splitlines() if e.strip() != ""]
+    else:
+        # ops.BinOp; for internal compat, not intended to be passed by users
+        exprs = [expr]
+    multi_line = len(exprs) > 1
+
+    if multi_line and target is None:
+        raise ValueError(
+            "multi-line expressions are only valid in the "
+            "context of data, use DataFrame.eval"
+        )
+    engine = _check_engine(engine)
+    _check_parser(parser)
+    _check_resolvers(resolvers)
+
+    ret = None
+    first_expr = True
+    target_modified = False
+
+    for expr in exprs:
+        expr = _convert_expression(expr)
+        _check_for_locals(expr, level, parser)
+
+        # get our (possibly passed-in) scope
+        env = ensure_scope(
+            level + 1,
+            global_dict=global_dict,
+            local_dict=local_dict,
+            resolvers=resolvers,
+            target=target,
+        )
+
+        parsed_expr = Expr(expr, engine=engine, parser=parser, env=env)
+
+        if engine == "numexpr" and (
+            (
+                is_extension_array_dtype(parsed_expr.terms.return_type)
+                and not is_string_dtype(parsed_expr.terms.return_type)
+            )
+            or getattr(parsed_expr.terms, "operand_types", None) is not None
+            and any(
+                (is_extension_array_dtype(elem) and not is_string_dtype(elem))
+                for elem in parsed_expr.terms.operand_types
+            )
+        ):
+            warnings.warn(
+                "Engine has switched to 'python' because numexpr does not support "
+                "extension array dtypes. Please set your engine to python manually.",
+                RuntimeWarning,
+                stacklevel=find_stack_level(),
+            )
+            engine = "python"
+
+        # construct the engine and evaluate the parsed expression
+        eng = ENGINES[engine]
+        eng_inst = eng(parsed_expr)
+        ret = eng_inst.evaluate()
+
+        if parsed_expr.assigner is None:
+            if multi_line:
+                raise ValueError(
+                    "Multi-line expressions are only valid "
+                    "if all expressions contain an assignment"
+                )
+            if inplace:
+                raise ValueError("Cannot operate inplace if there is no assignment")
+
+        # assign if needed
+        assigner = parsed_expr.assigner
+        if env.target is not None and assigner is not None:
+            target_modified = True
+
+            # if returning a copy, copy only on the first assignment
+            if not inplace and first_expr:
+                try:
+                    target = env.target
+                    if isinstance(target, NDFrame):
+                        target = target.copy(deep=None)
+                    else:
+                        target = target.copy()
+                except AttributeError as err:
+                    raise ValueError("Cannot return a copy of the target") from err
+            else:
+                target = env.target
+
+            # TypeError is most commonly raised (e.g. int, list), but you
+            # get IndexError if you try to do this assignment on np.ndarray.
+            # we will ignore numpy warnings here; e.g. if trying
+            # to use a non-numeric indexer
+            try:
+                if inplace and isinstance(target, NDFrame):
+                    target.loc[:, assigner] = ret
+                else:
+                    target[assigner] = ret  # pyright: ignore[reportGeneralTypeIssues]
+            except (TypeError, IndexError) as err:
+                raise ValueError("Cannot assign expression output to target") from err
+
+            if not resolvers:
+                resolvers = ({assigner: ret},)
+            else:
+                # existing resolver needs updated to handle
+                # case of mutating existing column in copy
+                for resolver in resolvers:
+                    if assigner in resolver:
+                        resolver[assigner] = ret
+                        break
+                else:
+                    resolvers += ({assigner: ret},)
+
+            ret = None
+            first_expr = False
+
+    # We want to exclude `inplace=None` as being False.
+    if inplace is False:
+        return target if target_modified else ret
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/expr.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/expr.py
new file mode 100644
index 0000000000000000000000000000000000000000..34055d2177626dad7415c2109dedbe6a205b626b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/expr.py
@@ -0,0 +1,840 @@
+"""
+:func:`~pandas.eval` parsers.
+"""
+from __future__ import annotations
+
+import ast
+from functools import (
+    partial,
+    reduce,
+)
+from keyword import iskeyword
+import tokenize
+from typing import (
+    Callable,
+    ClassVar,
+    TypeVar,
+)
+
+import numpy as np
+
+from pandas.errors import UndefinedVariableError
+
+from pandas.core.dtypes.common import is_string_dtype
+
+import pandas.core.common as com
+from pandas.core.computation.ops import (
+    ARITH_OPS_SYMS,
+    BOOL_OPS_SYMS,
+    CMP_OPS_SYMS,
+    LOCAL_TAG,
+    MATHOPS,
+    REDUCTIONS,
+    UNARY_OPS_SYMS,
+    BinOp,
+    Constant,
+    FuncNode,
+    Op,
+    Term,
+    UnaryOp,
+    is_term,
+)
+from pandas.core.computation.parsing import (
+    clean_backtick_quoted_toks,
+    tokenize_string,
+)
+from pandas.core.computation.scope import Scope
+
+from pandas.io.formats import printing
+
+
+def _rewrite_assign(tok: tuple[int, str]) -> tuple[int, str]:
+    """
+    Rewrite the assignment operator for PyTables expressions that use ``=``
+    as a substitute for ``==``.
+
+    Parameters
+    ----------
+    tok : tuple of int, str
+        ints correspond to the all caps constants in the tokenize module
+
+    Returns
+    -------
+    tuple of int, str
+        Either the input or token or the replacement values
+    """
+    toknum, tokval = tok
+    return toknum, "==" if tokval == "=" else tokval
+
+
+def _replace_booleans(tok: tuple[int, str]) -> tuple[int, str]:
+    """
+    Replace ``&`` with ``and`` and ``|`` with ``or`` so that bitwise
+    precedence is changed to boolean precedence.
+
+    Parameters
+    ----------
+    tok : tuple of int, str
+        ints correspond to the all caps constants in the tokenize module
+
+    Returns
+    -------
+    tuple of int, str
+        Either the input or token or the replacement values
+    """
+    toknum, tokval = tok
+    if toknum == tokenize.OP:
+        if tokval == "&":
+            return tokenize.NAME, "and"
+        elif tokval == "|":
+            return tokenize.NAME, "or"
+        return toknum, tokval
+    return toknum, tokval
+
+
+def _replace_locals(tok: tuple[int, str]) -> tuple[int, str]:
+    """
+    Replace local variables with a syntactically valid name.
+
+    Parameters
+    ----------
+    tok : tuple of int, str
+        ints correspond to the all caps constants in the tokenize module
+
+    Returns
+    -------
+    tuple of int, str
+        Either the input or token or the replacement values
+
+    Notes
+    -----
+    This is somewhat of a hack in that we rewrite a string such as ``'@a'`` as
+    ``'__pd_eval_local_a'`` by telling the tokenizer that ``__pd_eval_local_``
+    is a ``tokenize.OP`` and to replace the ``'@'`` symbol with it.
+    """
+    toknum, tokval = tok
+    if toknum == tokenize.OP and tokval == "@":
+        return tokenize.OP, LOCAL_TAG
+    return toknum, tokval
+
+
+def _compose2(f, g):
+    """
+    Compose 2 callables.
+    """
+    return lambda *args, **kwargs: f(g(*args, **kwargs))
+
+
+def _compose(*funcs):
+    """
+    Compose 2 or more callables.
+    """
+    assert len(funcs) > 1, "At least 2 callables must be passed to compose"
+    return reduce(_compose2, funcs)
+
+
+def _preparse(
+    source: str,
+    f=_compose(
+        _replace_locals, _replace_booleans, _rewrite_assign, clean_backtick_quoted_toks
+    ),
+) -> str:
+    """
+    Compose a collection of tokenization functions.
+
+    Parameters
+    ----------
+    source : str
+        A Python source code string
+    f : callable
+        This takes a tuple of (toknum, tokval) as its argument and returns a
+        tuple with the same structure but possibly different elements. Defaults
+        to the composition of ``_rewrite_assign``, ``_replace_booleans``, and
+        ``_replace_locals``.
+
+    Returns
+    -------
+    str
+        Valid Python source code
+
+    Notes
+    -----
+    The `f` parameter can be any callable that takes *and* returns input of the
+    form ``(toknum, tokval)``, where ``toknum`` is one of the constants from
+    the ``tokenize`` module and ``tokval`` is a string.
+    """
+    assert callable(f), "f must be callable"
+    return tokenize.untokenize(f(x) for x in tokenize_string(source))
+
+
+def _is_type(t):
+    """
+    Factory for a type checking function of type ``t`` or tuple of types.
+    """
+    return lambda x: isinstance(x.value, t)
+
+
+_is_list = _is_type(list)
+_is_str = _is_type(str)
+
+
+# partition all AST nodes
+_all_nodes = frozenset(
+    node
+    for node in (getattr(ast, name) for name in dir(ast))
+    if isinstance(node, type) and issubclass(node, ast.AST)
+)
+
+
+def _filter_nodes(superclass, all_nodes=_all_nodes):
+    """
+    Filter out AST nodes that are subclasses of ``superclass``.
+    """
+    node_names = (node.__name__ for node in all_nodes if issubclass(node, superclass))
+    return frozenset(node_names)
+
+
+_all_node_names = frozenset(x.__name__ for x in _all_nodes)
+_mod_nodes = _filter_nodes(ast.mod)
+_stmt_nodes = _filter_nodes(ast.stmt)
+_expr_nodes = _filter_nodes(ast.expr)
+_expr_context_nodes = _filter_nodes(ast.expr_context)
+_boolop_nodes = _filter_nodes(ast.boolop)
+_operator_nodes = _filter_nodes(ast.operator)
+_unary_op_nodes = _filter_nodes(ast.unaryop)
+_cmp_op_nodes = _filter_nodes(ast.cmpop)
+_comprehension_nodes = _filter_nodes(ast.comprehension)
+_handler_nodes = _filter_nodes(ast.excepthandler)
+_arguments_nodes = _filter_nodes(ast.arguments)
+_keyword_nodes = _filter_nodes(ast.keyword)
+_alias_nodes = _filter_nodes(ast.alias)
+
+
+# nodes that we don't support directly but are needed for parsing
+_hacked_nodes = frozenset(["Assign", "Module", "Expr"])
+
+
+_unsupported_expr_nodes = frozenset(
+    [
+        "Yield",
+        "GeneratorExp",
+        "IfExp",
+        "DictComp",
+        "SetComp",
+        "Repr",
+        "Lambda",
+        "Set",
+        "AST",
+        "Is",
+        "IsNot",
+    ]
+)
+
+# these nodes are low priority or won't ever be supported (e.g., AST)
+_unsupported_nodes = (
+    _stmt_nodes
+    | _mod_nodes
+    | _handler_nodes
+    | _arguments_nodes
+    | _keyword_nodes
+    | _alias_nodes
+    | _expr_context_nodes
+    | _unsupported_expr_nodes
+) - _hacked_nodes
+
+# we're adding a different assignment in some cases to be equality comparison
+# and we don't want `stmt` and friends in their so get only the class whose
+# names are capitalized
+_base_supported_nodes = (_all_node_names - _unsupported_nodes) | _hacked_nodes
+intersection = _unsupported_nodes & _base_supported_nodes
+_msg = f"cannot both support and not support {intersection}"
+assert not intersection, _msg
+
+
+def _node_not_implemented(node_name: str) -> Callable[..., None]:
+    """
+    Return a function that raises a NotImplementedError with a passed node name.
+    """
+
+    def f(self, *args, **kwargs):
+        raise NotImplementedError(f"'{node_name}' nodes are not implemented")
+
+    return f
+
+
+# should be bound by BaseExprVisitor but that creates a circular dependency:
+# _T is used in disallow, but disallow is used to define BaseExprVisitor
+# https://github.com/microsoft/pyright/issues/2315
+_T = TypeVar("_T")
+
+
+def disallow(nodes: set[str]) -> Callable[[type[_T]], type[_T]]:
+    """
+    Decorator to disallow certain nodes from parsing. Raises a
+    NotImplementedError instead.
+
+    Returns
+    -------
+    callable
+    """
+
+    def disallowed(cls: type[_T]) -> type[_T]:
+        # error: "Type[_T]" has no attribute "unsupported_nodes"
+        cls.unsupported_nodes = ()  # type: ignore[attr-defined]
+        for node in nodes:
+            new_method = _node_not_implemented(node)
+            name = f"visit_{node}"
+            # error: "Type[_T]" has no attribute "unsupported_nodes"
+            cls.unsupported_nodes += (name,)  # type: ignore[attr-defined]
+            setattr(cls, name, new_method)
+        return cls
+
+    return disallowed
+
+
+def _op_maker(op_class, op_symbol):
+    """
+    Return a function to create an op class with its symbol already passed.
+
+    Returns
+    -------
+    callable
+    """
+
+    def f(self, node, *args, **kwargs):
+        """
+        Return a partial function with an Op subclass with an operator already passed.
+
+        Returns
+        -------
+        callable
+        """
+        return partial(op_class, op_symbol, *args, **kwargs)
+
+    return f
+
+
+_op_classes = {"binary": BinOp, "unary": UnaryOp}
+
+
+def add_ops(op_classes):
+    """
+    Decorator to add default implementation of ops.
+    """
+
+    def f(cls):
+        for op_attr_name, op_class in op_classes.items():
+            ops = getattr(cls, f"{op_attr_name}_ops")
+            ops_map = getattr(cls, f"{op_attr_name}_op_nodes_map")
+            for op in ops:
+                op_node = ops_map[op]
+                if op_node is not None:
+                    made_op = _op_maker(op_class, op)
+                    setattr(cls, f"visit_{op_node}", made_op)
+        return cls
+
+    return f
+
+
+@disallow(_unsupported_nodes)
+@add_ops(_op_classes)
+class BaseExprVisitor(ast.NodeVisitor):
+    """
+    Custom ast walker. Parsers of other engines should subclass this class
+    if necessary.
+
+    Parameters
+    ----------
+    env : Scope
+    engine : str
+    parser : str
+    preparser : callable
+    """
+
+    const_type: ClassVar[type[Term]] = Constant
+    term_type: ClassVar[type[Term]] = Term
+
+    binary_ops = CMP_OPS_SYMS + BOOL_OPS_SYMS + ARITH_OPS_SYMS
+    binary_op_nodes = (
+        "Gt",
+        "Lt",
+        "GtE",
+        "LtE",
+        "Eq",
+        "NotEq",
+        "In",
+        "NotIn",
+        "BitAnd",
+        "BitOr",
+        "And",
+        "Or",
+        "Add",
+        "Sub",
+        "Mult",
+        "Div",
+        "Pow",
+        "FloorDiv",
+        "Mod",
+    )
+    binary_op_nodes_map = dict(zip(binary_ops, binary_op_nodes))
+
+    unary_ops = UNARY_OPS_SYMS
+    unary_op_nodes = "UAdd", "USub", "Invert", "Not"
+    unary_op_nodes_map = dict(zip(unary_ops, unary_op_nodes))
+
+    rewrite_map = {
+        ast.Eq: ast.In,
+        ast.NotEq: ast.NotIn,
+        ast.In: ast.In,
+        ast.NotIn: ast.NotIn,
+    }
+
+    unsupported_nodes: tuple[str, ...]
+
+    def __init__(self, env, engine, parser, preparser=_preparse) -> None:
+        self.env = env
+        self.engine = engine
+        self.parser = parser
+        self.preparser = preparser
+        self.assigner = None
+
+    def visit(self, node, **kwargs):
+        if isinstance(node, str):
+            clean = self.preparser(node)
+            try:
+                node = ast.fix_missing_locations(ast.parse(clean))
+            except SyntaxError as e:
+                if any(iskeyword(x) for x in clean.split()):
+                    e.msg = "Python keyword not valid identifier in numexpr query"
+                raise e
+
+        method = f"visit_{type(node).__name__}"
+        visitor = getattr(self, method)
+        return visitor(node, **kwargs)
+
+    def visit_Module(self, node, **kwargs):
+        if len(node.body) != 1:
+            raise SyntaxError("only a single expression is allowed")
+        expr = node.body[0]
+        return self.visit(expr, **kwargs)
+
+    def visit_Expr(self, node, **kwargs):
+        return self.visit(node.value, **kwargs)
+
+    def _rewrite_membership_op(self, node, left, right):
+        # the kind of the operator (is actually an instance)
+        op_instance = node.op
+        op_type = type(op_instance)
+
+        # must be two terms and the comparison operator must be ==/!=/in/not in
+        if is_term(left) and is_term(right) and op_type in self.rewrite_map:
+            left_list, right_list = map(_is_list, (left, right))
+            left_str, right_str = map(_is_str, (left, right))
+
+            # if there are any strings or lists in the expression
+            if left_list or right_list or left_str or right_str:
+                op_instance = self.rewrite_map[op_type]()
+
+            # pop the string variable out of locals and replace it with a list
+            # of one string, kind of a hack
+            if right_str:
+                name = self.env.add_tmp([right.value])
+                right = self.term_type(name, self.env)
+
+            if left_str:
+                name = self.env.add_tmp([left.value])
+                left = self.term_type(name, self.env)
+
+        op = self.visit(op_instance)
+        return op, op_instance, left, right
+
+    def _maybe_transform_eq_ne(self, node, left=None, right=None):
+        if left is None:
+            left = self.visit(node.left, side="left")
+        if right is None:
+            right = self.visit(node.right, side="right")
+        op, op_class, left, right = self._rewrite_membership_op(node, left, right)
+        return op, op_class, left, right
+
+    def _maybe_downcast_constants(self, left, right):
+        f32 = np.dtype(np.float32)
+        if (
+            left.is_scalar
+            and hasattr(left, "value")
+            and not right.is_scalar
+            and right.return_type == f32
+        ):
+            # right is a float32 array, left is a scalar
+            name = self.env.add_tmp(np.float32(left.value))
+            left = self.term_type(name, self.env)
+        if (
+            right.is_scalar
+            and hasattr(right, "value")
+            and not left.is_scalar
+            and left.return_type == f32
+        ):
+            # left is a float32 array, right is a scalar
+            name = self.env.add_tmp(np.float32(right.value))
+            right = self.term_type(name, self.env)
+
+        return left, right
+
+    def _maybe_eval(self, binop, eval_in_python):
+        # eval `in` and `not in` (for now) in "partial" python space
+        # things that can be evaluated in "eval" space will be turned into
+        # temporary variables. for example,
+        # [1,2] in a + 2 * b
+        # in that case a + 2 * b will be evaluated using numexpr, and the "in"
+        # call will be evaluated using isin (in python space)
+        return binop.evaluate(
+            self.env, self.engine, self.parser, self.term_type, eval_in_python
+        )
+
+    def _maybe_evaluate_binop(
+        self,
+        op,
+        op_class,
+        lhs,
+        rhs,
+        eval_in_python=("in", "not in"),
+        maybe_eval_in_python=("==", "!=", "<", ">", "<=", ">="),
+    ):
+        res = op(lhs, rhs)
+
+        if res.has_invalid_return_type:
+            raise TypeError(
+                f"unsupported operand type(s) for {res.op}: "
+                f"'{lhs.type}' and '{rhs.type}'"
+            )
+
+        if self.engine != "pytables" and (
+            res.op in CMP_OPS_SYMS
+            and getattr(lhs, "is_datetime", False)
+            or getattr(rhs, "is_datetime", False)
+        ):
+            # all date ops must be done in python bc numexpr doesn't work
+            # well with NaT
+            return self._maybe_eval(res, self.binary_ops)
+
+        if res.op in eval_in_python:
+            # "in"/"not in" ops are always evaluated in python
+            return self._maybe_eval(res, eval_in_python)
+        elif self.engine != "pytables":
+            if (
+                getattr(lhs, "return_type", None) == object
+                or is_string_dtype(getattr(lhs, "return_type", None))
+                or getattr(rhs, "return_type", None) == object
+                or is_string_dtype(getattr(rhs, "return_type", None))
+            ):
+                # evaluate "==" and "!=" in python if either of our operands
+                # has an object or string return type
+                return self._maybe_eval(res, eval_in_python + maybe_eval_in_python)
+        return res
+
+    def visit_BinOp(self, node, **kwargs):
+        op, op_class, left, right = self._maybe_transform_eq_ne(node)
+        left, right = self._maybe_downcast_constants(left, right)
+        return self._maybe_evaluate_binop(op, op_class, left, right)
+
+    def visit_UnaryOp(self, node, **kwargs):
+        op = self.visit(node.op)
+        operand = self.visit(node.operand)
+        return op(operand)
+
+    def visit_Name(self, node, **kwargs) -> Term:
+        return self.term_type(node.id, self.env, **kwargs)
+
+    # TODO(py314): deprecated since Python 3.8. Remove after Python 3.14 is min
+    def visit_NameConstant(self, node, **kwargs) -> Term:
+        return self.const_type(node.value, self.env)
+
+    # TODO(py314): deprecated since Python 3.8. Remove after Python 3.14 is min
+    def visit_Num(self, node, **kwargs) -> Term:
+        return self.const_type(node.value, self.env)
+
+    def visit_Constant(self, node, **kwargs) -> Term:
+        return self.const_type(node.value, self.env)
+
+    # TODO(py314): deprecated since Python 3.8. Remove after Python 3.14 is min
+    def visit_Str(self, node, **kwargs) -> Term:
+        name = self.env.add_tmp(node.s)
+        return self.term_type(name, self.env)
+
+    def visit_List(self, node, **kwargs) -> Term:
+        name = self.env.add_tmp([self.visit(e)(self.env) for e in node.elts])
+        return self.term_type(name, self.env)
+
+    visit_Tuple = visit_List
+
+    def visit_Index(self, node, **kwargs):
+        """df.index[4]"""
+        return self.visit(node.value)
+
+    def visit_Subscript(self, node, **kwargs) -> Term:
+        from pandas import eval as pd_eval
+
+        value = self.visit(node.value)
+        slobj = self.visit(node.slice)
+        result = pd_eval(
+            slobj, local_dict=self.env, engine=self.engine, parser=self.parser
+        )
+        try:
+            # a Term instance
+            v = value.value[result]
+        except AttributeError:
+            # an Op instance
+            lhs = pd_eval(
+                value, local_dict=self.env, engine=self.engine, parser=self.parser
+            )
+            v = lhs[result]
+        name = self.env.add_tmp(v)
+        return self.term_type(name, env=self.env)
+
+    def visit_Slice(self, node, **kwargs) -> slice:
+        """df.index[slice(4,6)]"""
+        lower = node.lower
+        if lower is not None:
+            lower = self.visit(lower).value
+        upper = node.upper
+        if upper is not None:
+            upper = self.visit(upper).value
+        step = node.step
+        if step is not None:
+            step = self.visit(step).value
+
+        return slice(lower, upper, step)
+
+    def visit_Assign(self, node, **kwargs):
+        """
+        support a single assignment node, like
+
+        c = a + b
+
+        set the assigner at the top level, must be a Name node which
+        might or might not exist in the resolvers
+
+        """
+        if len(node.targets) != 1:
+            raise SyntaxError("can only assign a single expression")
+        if not isinstance(node.targets[0], ast.Name):
+            raise SyntaxError("left hand side of an assignment must be a single name")
+        if self.env.target is None:
+            raise ValueError("cannot assign without a target object")
+
+        try:
+            assigner = self.visit(node.targets[0], **kwargs)
+        except UndefinedVariableError:
+            assigner = node.targets[0].id
+
+        self.assigner = getattr(assigner, "name", assigner)
+        if self.assigner is None:
+            raise SyntaxError(
+                "left hand side of an assignment must be a single resolvable name"
+            )
+
+        return self.visit(node.value, **kwargs)
+
+    def visit_Attribute(self, node, **kwargs):
+        attr = node.attr
+        value = node.value
+
+        ctx = node.ctx
+        if isinstance(ctx, ast.Load):
+            # resolve the value
+            resolved = self.visit(value).value
+            try:
+                v = getattr(resolved, attr)
+                name = self.env.add_tmp(v)
+                return self.term_type(name, self.env)
+            except AttributeError:
+                # something like datetime.datetime where scope is overridden
+                if isinstance(value, ast.Name) and value.id == attr:
+                    return resolved
+                raise
+
+        raise ValueError(f"Invalid Attribute context {type(ctx).__name__}")
+
+    def visit_Call(self, node, side=None, **kwargs):
+        if isinstance(node.func, ast.Attribute) and node.func.attr != "__call__":
+            res = self.visit_Attribute(node.func)
+        elif not isinstance(node.func, ast.Name):
+            raise TypeError("Only named functions are supported")
+        else:
+            try:
+                res = self.visit(node.func)
+            except UndefinedVariableError:
+                # Check if this is a supported function name
+                try:
+                    res = FuncNode(node.func.id)
+                except ValueError:
+                    # Raise original error
+                    raise
+
+        if res is None:
+            # error: "expr" has no attribute "id"
+            raise ValueError(
+                f"Invalid function call {node.func.id}"  # type: ignore[attr-defined]
+            )
+        if hasattr(res, "value"):
+            res = res.value
+
+        if isinstance(res, FuncNode):
+            new_args = [self.visit(arg) for arg in node.args]
+
+            if node.keywords:
+                raise TypeError(
+                    f'Function "{res.name}" does not support keyword arguments'
+                )
+
+            return res(*new_args)
+
+        else:
+            new_args = [self.visit(arg)(self.env) for arg in node.args]
+
+            for key in node.keywords:
+                if not isinstance(key, ast.keyword):
+                    # error: "expr" has no attribute "id"
+                    raise ValueError(
+                        "keyword error in function call "
+                        f"'{node.func.id}'"  # type: ignore[attr-defined]
+                    )
+
+                if key.arg:
+                    kwargs[key.arg] = self.visit(key.value)(self.env)
+
+            name = self.env.add_tmp(res(*new_args, **kwargs))
+            return self.term_type(name=name, env=self.env)
+
+    def translate_In(self, op):
+        return op
+
+    def visit_Compare(self, node, **kwargs):
+        ops = node.ops
+        comps = node.comparators
+
+        # base case: we have something like a CMP b
+        if len(comps) == 1:
+            op = self.translate_In(ops[0])
+            binop = ast.BinOp(op=op, left=node.left, right=comps[0])
+            return self.visit(binop)
+
+        # recursive case: we have a chained comparison, a CMP b CMP c, etc.
+        left = node.left
+        values = []
+        for op, comp in zip(ops, comps):
+            new_node = self.visit(
+                ast.Compare(comparators=[comp], left=left, ops=[self.translate_In(op)])
+            )
+            left = comp
+            values.append(new_node)
+        return self.visit(ast.BoolOp(op=ast.And(), values=values))
+
+    def _try_visit_binop(self, bop):
+        if isinstance(bop, (Op, Term)):
+            return bop
+        return self.visit(bop)
+
+    def visit_BoolOp(self, node, **kwargs):
+        def visitor(x, y):
+            lhs = self._try_visit_binop(x)
+            rhs = self._try_visit_binop(y)
+
+            op, op_class, lhs, rhs = self._maybe_transform_eq_ne(node, lhs, rhs)
+            return self._maybe_evaluate_binop(op, node.op, lhs, rhs)
+
+        operands = node.values
+        return reduce(visitor, operands)
+
+
+_python_not_supported = frozenset(["Dict", "BoolOp", "In", "NotIn"])
+_numexpr_supported_calls = frozenset(REDUCTIONS + MATHOPS)
+
+
+@disallow(
+    (_unsupported_nodes | _python_not_supported)
+    - (_boolop_nodes | frozenset(["BoolOp", "Attribute", "In", "NotIn", "Tuple"]))
+)
+class PandasExprVisitor(BaseExprVisitor):
+    def __init__(
+        self,
+        env,
+        engine,
+        parser,
+        preparser=partial(
+            _preparse,
+            f=_compose(_replace_locals, _replace_booleans, clean_backtick_quoted_toks),
+        ),
+    ) -> None:
+        super().__init__(env, engine, parser, preparser)
+
+
+@disallow(_unsupported_nodes | _python_not_supported | frozenset(["Not"]))
+class PythonExprVisitor(BaseExprVisitor):
+    def __init__(
+        self, env, engine, parser, preparser=lambda source, f=None: source
+    ) -> None:
+        super().__init__(env, engine, parser, preparser=preparser)
+
+
+class Expr:
+    """
+    Object encapsulating an expression.
+
+    Parameters
+    ----------
+    expr : str
+    engine : str, optional, default 'numexpr'
+    parser : str, optional, default 'pandas'
+    env : Scope, optional, default None
+    level : int, optional, default 2
+    """
+
+    env: Scope
+    engine: str
+    parser: str
+
+    def __init__(
+        self,
+        expr,
+        engine: str = "numexpr",
+        parser: str = "pandas",
+        env: Scope | None = None,
+        level: int = 0,
+    ) -> None:
+        self.expr = expr
+        self.env = env or Scope(level=level + 1)
+        self.engine = engine
+        self.parser = parser
+        self._visitor = PARSERS[parser](self.env, self.engine, self.parser)
+        self.terms = self.parse()
+
+    @property
+    def assigner(self):
+        return getattr(self._visitor, "assigner", None)
+
+    def __call__(self):
+        return self.terms(self.env)
+
+    def __repr__(self) -> str:
+        return printing.pprint_thing(self.terms)
+
+    def __len__(self) -> int:
+        return len(self.expr)
+
+    def parse(self):
+        """
+        Parse an expression.
+        """
+        return self._visitor.visit(self.expr)
+
+    @property
+    def names(self):
+        """
+        Get the names in an expression.
+        """
+        if is_term(self.terms):
+            return frozenset([self.terms.name])
+        return frozenset(term.name for term in com.flatten(self.terms))
+
+
+PARSERS = {"python": PythonExprVisitor, "pandas": PandasExprVisitor}
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/expressions.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/expressions.py
new file mode 100644
index 0000000000000000000000000000000000000000..6219cac4aeb16ee019551f95a03af59da44c9d06
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/expressions.py
@@ -0,0 +1,286 @@
+"""
+Expressions
+-----------
+
+Offer fast expression evaluation through numexpr
+
+"""
+from __future__ import annotations
+
+import operator
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core import roperator
+from pandas.core.computation.check import NUMEXPR_INSTALLED
+
+if NUMEXPR_INSTALLED:
+    import numexpr as ne
+
+if TYPE_CHECKING:
+    from pandas._typing import FuncType
+
+_TEST_MODE: bool | None = None
+_TEST_RESULT: list[bool] = []
+USE_NUMEXPR = NUMEXPR_INSTALLED
+_evaluate: FuncType | None = None
+_where: FuncType | None = None
+
+# the set of dtypes that we will allow pass to numexpr
+_ALLOWED_DTYPES = {
+    "evaluate": {"int64", "int32", "float64", "float32", "bool"},
+    "where": {"int64", "float64", "bool"},
+}
+
+# the minimum prod shape that we will use numexpr
+_MIN_ELEMENTS = 1_000_000
+
+
+def set_use_numexpr(v: bool = True) -> None:
+    # set/unset to use numexpr
+    global USE_NUMEXPR
+    if NUMEXPR_INSTALLED:
+        USE_NUMEXPR = v
+
+    # choose what we are going to do
+    global _evaluate, _where
+
+    _evaluate = _evaluate_numexpr if USE_NUMEXPR else _evaluate_standard
+    _where = _where_numexpr if USE_NUMEXPR else _where_standard
+
+
+def set_numexpr_threads(n=None) -> None:
+    # if we are using numexpr, set the threads to n
+    # otherwise reset
+    if NUMEXPR_INSTALLED and USE_NUMEXPR:
+        if n is None:
+            n = ne.detect_number_of_cores()
+        ne.set_num_threads(n)
+
+
+def _evaluate_standard(op, op_str, a, b):
+    """
+    Standard evaluation.
+    """
+    if _TEST_MODE:
+        _store_test_result(False)
+    return op(a, b)
+
+
+def _can_use_numexpr(op, op_str, a, b, dtype_check) -> bool:
+    """return a boolean if we WILL be using numexpr"""
+    if op_str is not None:
+        # required min elements (otherwise we are adding overhead)
+        if a.size > _MIN_ELEMENTS:
+            # check for dtype compatibility
+            dtypes: set[str] = set()
+            for o in [a, b]:
+                # ndarray and Series Case
+                if hasattr(o, "dtype"):
+                    dtypes |= {o.dtype.name}
+
+            # allowed are a superset
+            if not len(dtypes) or _ALLOWED_DTYPES[dtype_check] >= dtypes:
+                return True
+
+    return False
+
+
+def _evaluate_numexpr(op, op_str, a, b):
+    result = None
+
+    if _can_use_numexpr(op, op_str, a, b, "evaluate"):
+        is_reversed = op.__name__.strip("_").startswith("r")
+        if is_reversed:
+            # we were originally called by a reversed op method
+            a, b = b, a
+
+        a_value = a
+        b_value = b
+
+        try:
+            result = ne.evaluate(
+                f"a_value {op_str} b_value",
+                local_dict={"a_value": a_value, "b_value": b_value},
+                casting="safe",
+            )
+        except TypeError:
+            # numexpr raises eg for array ** array with integers
+            # (https://github.com/pydata/numexpr/issues/379)
+            pass
+        except NotImplementedError:
+            if _bool_arith_fallback(op_str, a, b):
+                pass
+            else:
+                raise
+
+        if is_reversed:
+            # reverse order to original for fallback
+            a, b = b, a
+
+    if _TEST_MODE:
+        _store_test_result(result is not None)
+
+    if result is None:
+        result = _evaluate_standard(op, op_str, a, b)
+
+    return result
+
+
+_op_str_mapping = {
+    operator.add: "+",
+    roperator.radd: "+",
+    operator.mul: "*",
+    roperator.rmul: "*",
+    operator.sub: "-",
+    roperator.rsub: "-",
+    operator.truediv: "/",
+    roperator.rtruediv: "/",
+    # floordiv not supported by numexpr 2.x
+    operator.floordiv: None,
+    roperator.rfloordiv: None,
+    # we require Python semantics for mod of negative for backwards compatibility
+    # see https://github.com/pydata/numexpr/issues/365
+    # so sticking with unaccelerated for now GH#36552
+    operator.mod: None,
+    roperator.rmod: None,
+    operator.pow: "**",
+    roperator.rpow: "**",
+    operator.eq: "==",
+    operator.ne: "!=",
+    operator.le: "<=",
+    operator.lt: "<",
+    operator.ge: ">=",
+    operator.gt: ">",
+    operator.and_: "&",
+    roperator.rand_: "&",
+    operator.or_: "|",
+    roperator.ror_: "|",
+    operator.xor: "^",
+    roperator.rxor: "^",
+    divmod: None,
+    roperator.rdivmod: None,
+}
+
+
+def _where_standard(cond, a, b):
+    # Caller is responsible for extracting ndarray if necessary
+    return np.where(cond, a, b)
+
+
+def _where_numexpr(cond, a, b):
+    # Caller is responsible for extracting ndarray if necessary
+    result = None
+
+    if _can_use_numexpr(None, "where", a, b, "where"):
+        result = ne.evaluate(
+            "where(cond_value, a_value, b_value)",
+            local_dict={"cond_value": cond, "a_value": a, "b_value": b},
+            casting="safe",
+        )
+
+    if result is None:
+        result = _where_standard(cond, a, b)
+
+    return result
+
+
+# turn myself on
+set_use_numexpr(get_option("compute.use_numexpr"))
+
+
+def _has_bool_dtype(x):
+    try:
+        return x.dtype == bool
+    except AttributeError:
+        return isinstance(x, (bool, np.bool_))
+
+
+_BOOL_OP_UNSUPPORTED = {"+": "|", "*": "&", "-": "^"}
+
+
+def _bool_arith_fallback(op_str, a, b) -> bool:
+    """
+    Check if we should fallback to the python `_evaluate_standard` in case
+    of an unsupported operation by numexpr, which is the case for some
+    boolean ops.
+    """
+    if _has_bool_dtype(a) and _has_bool_dtype(b):
+        if op_str in _BOOL_OP_UNSUPPORTED:
+            warnings.warn(
+                f"evaluating in Python space because the {repr(op_str)} "
+                "operator is not supported by numexpr for the bool dtype, "
+                f"use {repr(_BOOL_OP_UNSUPPORTED[op_str])} instead.",
+                stacklevel=find_stack_level(),
+            )
+            return True
+    return False
+
+
+def evaluate(op, a, b, use_numexpr: bool = True):
+    """
+    Evaluate and return the expression of the op on a and b.
+
+    Parameters
+    ----------
+    op : the actual operand
+    a : left operand
+    b : right operand
+    use_numexpr : bool, default True
+        Whether to try to use numexpr.
+    """
+    op_str = _op_str_mapping[op]
+    if op_str is not None:
+        if use_numexpr:
+            # error: "None" not callable
+            return _evaluate(op, op_str, a, b)  # type: ignore[misc]
+    return _evaluate_standard(op, op_str, a, b)
+
+
+def where(cond, a, b, use_numexpr: bool = True):
+    """
+    Evaluate the where condition cond on a and b.
+
+    Parameters
+    ----------
+    cond : np.ndarray[bool]
+    a : return if cond is True
+    b : return if cond is False
+    use_numexpr : bool, default True
+        Whether to try to use numexpr.
+    """
+    assert _where is not None
+    return _where(cond, a, b) if use_numexpr else _where_standard(cond, a, b)
+
+
+def set_test_mode(v: bool = True) -> None:
+    """
+    Keeps track of whether numexpr was used.
+
+    Stores an additional ``True`` for every successful use of evaluate with
+    numexpr since the last ``get_test_result``.
+    """
+    global _TEST_MODE, _TEST_RESULT
+    _TEST_MODE = v
+    _TEST_RESULT = []
+
+
+def _store_test_result(used_numexpr: bool) -> None:
+    if used_numexpr:
+        _TEST_RESULT.append(used_numexpr)
+
+
+def get_test_result() -> list[bool]:
+    """
+    Get test result and reset test_results.
+    """
+    global _TEST_RESULT
+    res = _TEST_RESULT
+    _TEST_RESULT = []
+    return res
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/ops.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..d8265456dfcedb5eb398cbf0517d78a1d976cd2a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/ops.py
@@ -0,0 +1,572 @@
+"""
+Operator classes for eval.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from functools import partial
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import Timestamp
+
+from pandas.core.dtypes.common import (
+    is_list_like,
+    is_scalar,
+)
+
+import pandas.core.common as com
+from pandas.core.computation.common import (
+    ensure_decoded,
+    result_type_many,
+)
+from pandas.core.computation.scope import DEFAULT_GLOBALS
+
+from pandas.io.formats.printing import (
+    pprint_thing,
+    pprint_thing_encoded,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Iterator,
+    )
+
+REDUCTIONS = ("sum", "prod", "min", "max")
+
+_unary_math_ops = (
+    "sin",
+    "cos",
+    "exp",
+    "log",
+    "expm1",
+    "log1p",
+    "sqrt",
+    "sinh",
+    "cosh",
+    "tanh",
+    "arcsin",
+    "arccos",
+    "arctan",
+    "arccosh",
+    "arcsinh",
+    "arctanh",
+    "abs",
+    "log10",
+    "floor",
+    "ceil",
+)
+_binary_math_ops = ("arctan2",)
+
+MATHOPS = _unary_math_ops + _binary_math_ops
+
+
+LOCAL_TAG = "__pd_eval_local_"
+
+
+class Term:
+    def __new__(cls, name, env, side=None, encoding=None):
+        klass = Constant if not isinstance(name, str) else cls
+        # error: Argument 2 for "super" not an instance of argument 1
+        supr_new = super(Term, klass).__new__  # type: ignore[misc]
+        return supr_new(klass)
+
+    is_local: bool
+
+    def __init__(self, name, env, side=None, encoding=None) -> None:
+        # name is a str for Term, but may be something else for subclasses
+        self._name = name
+        self.env = env
+        self.side = side
+        tname = str(name)
+        self.is_local = tname.startswith(LOCAL_TAG) or tname in DEFAULT_GLOBALS
+        self._value = self._resolve_name()
+        self.encoding = encoding
+
+    @property
+    def local_name(self) -> str:
+        return self.name.replace(LOCAL_TAG, "")
+
+    def __repr__(self) -> str:
+        return pprint_thing(self.name)
+
+    def __call__(self, *args, **kwargs):
+        return self.value
+
+    def evaluate(self, *args, **kwargs) -> Term:
+        return self
+
+    def _resolve_name(self):
+        local_name = str(self.local_name)
+        is_local = self.is_local
+        if local_name in self.env.scope and isinstance(
+            self.env.scope[local_name], type
+        ):
+            is_local = False
+
+        res = self.env.resolve(local_name, is_local=is_local)
+        self.update(res)
+
+        if hasattr(res, "ndim") and res.ndim > 2:
+            raise NotImplementedError(
+                "N-dimensional objects, where N > 2, are not supported with eval"
+            )
+        return res
+
+    def update(self, value) -> None:
+        """
+        search order for local (i.e., @variable) variables:
+
+        scope, key_variable
+        [('locals', 'local_name'),
+         ('globals', 'local_name'),
+         ('locals', 'key'),
+         ('globals', 'key')]
+        """
+        key = self.name
+
+        # if it's a variable name (otherwise a constant)
+        if isinstance(key, str):
+            self.env.swapkey(self.local_name, key, new_value=value)
+
+        self.value = value
+
+    @property
+    def is_scalar(self) -> bool:
+        return is_scalar(self._value)
+
+    @property
+    def type(self):
+        try:
+            # potentially very slow for large, mixed dtype frames
+            return self._value.values.dtype
+        except AttributeError:
+            try:
+                # ndarray
+                return self._value.dtype
+            except AttributeError:
+                # scalar
+                return type(self._value)
+
+    return_type = type
+
+    @property
+    def raw(self) -> str:
+        return f"{type(self).__name__}(name={repr(self.name)}, type={self.type})"
+
+    @property
+    def is_datetime(self) -> bool:
+        try:
+            t = self.type.type
+        except AttributeError:
+            t = self.type
+
+        return issubclass(t, (datetime, np.datetime64))
+
+    @property
+    def value(self):
+        return self._value
+
+    @value.setter
+    def value(self, new_value) -> None:
+        self._value = new_value
+
+    @property
+    def name(self):
+        return self._name
+
+    @property
+    def ndim(self) -> int:
+        return self._value.ndim
+
+
+class Constant(Term):
+    def _resolve_name(self):
+        return self._name
+
+    @property
+    def name(self):
+        return self.value
+
+    def __repr__(self) -> str:
+        # in python 2 str() of float
+        # can truncate shorter than repr()
+        return repr(self.name)
+
+
+_bool_op_map = {"not": "~", "and": "&", "or": "|"}
+
+
+class Op:
+    """
+    Hold an operator of arbitrary arity.
+    """
+
+    op: str
+
+    def __init__(self, op: str, operands: Iterable[Term | Op], encoding=None) -> None:
+        self.op = _bool_op_map.get(op, op)
+        self.operands = operands
+        self.encoding = encoding
+
+    def __iter__(self) -> Iterator:
+        return iter(self.operands)
+
+    def __repr__(self) -> str:
+        """
+        Print a generic n-ary operator and its operands using infix notation.
+        """
+        # recurse over the operands
+        parened = (f"({pprint_thing(opr)})" for opr in self.operands)
+        return pprint_thing(f" {self.op} ".join(parened))
+
+    @property
+    def return_type(self):
+        # clobber types to bool if the op is a boolean operator
+        if self.op in (CMP_OPS_SYMS + BOOL_OPS_SYMS):
+            return np.bool_
+        return result_type_many(*(term.type for term in com.flatten(self)))
+
+    @property
+    def has_invalid_return_type(self) -> bool:
+        types = self.operand_types
+        obj_dtype_set = frozenset([np.dtype("object")])
+        return self.return_type == object and types - obj_dtype_set
+
+    @property
+    def operand_types(self):
+        return frozenset(term.type for term in com.flatten(self))
+
+    @property
+    def is_scalar(self) -> bool:
+        return all(operand.is_scalar for operand in self.operands)
+
+    @property
+    def is_datetime(self) -> bool:
+        try:
+            t = self.return_type.type
+        except AttributeError:
+            t = self.return_type
+
+        return issubclass(t, (datetime, np.datetime64))
+
+
+def _in(x, y):
+    """
+    Compute the vectorized membership of ``x in y`` if possible, otherwise
+    use Python.
+    """
+    try:
+        return x.isin(y)
+    except AttributeError:
+        if is_list_like(x):
+            try:
+                return y.isin(x)
+            except AttributeError:
+                pass
+        return x in y
+
+
+def _not_in(x, y):
+    """
+    Compute the vectorized membership of ``x not in y`` if possible,
+    otherwise use Python.
+    """
+    try:
+        return ~x.isin(y)
+    except AttributeError:
+        if is_list_like(x):
+            try:
+                return ~y.isin(x)
+            except AttributeError:
+                pass
+        return x not in y
+
+
+CMP_OPS_SYMS = (">", "<", ">=", "<=", "==", "!=", "in", "not in")
+_cmp_ops_funcs = (
+    operator.gt,
+    operator.lt,
+    operator.ge,
+    operator.le,
+    operator.eq,
+    operator.ne,
+    _in,
+    _not_in,
+)
+_cmp_ops_dict = dict(zip(CMP_OPS_SYMS, _cmp_ops_funcs))
+
+BOOL_OPS_SYMS = ("&", "|", "and", "or")
+_bool_ops_funcs = (operator.and_, operator.or_, operator.and_, operator.or_)
+_bool_ops_dict = dict(zip(BOOL_OPS_SYMS, _bool_ops_funcs))
+
+ARITH_OPS_SYMS = ("+", "-", "*", "/", "**", "//", "%")
+_arith_ops_funcs = (
+    operator.add,
+    operator.sub,
+    operator.mul,
+    operator.truediv,
+    operator.pow,
+    operator.floordiv,
+    operator.mod,
+)
+_arith_ops_dict = dict(zip(ARITH_OPS_SYMS, _arith_ops_funcs))
+
+SPECIAL_CASE_ARITH_OPS_SYMS = ("**", "//", "%")
+_special_case_arith_ops_funcs = (operator.pow, operator.floordiv, operator.mod)
+_special_case_arith_ops_dict = dict(
+    zip(SPECIAL_CASE_ARITH_OPS_SYMS, _special_case_arith_ops_funcs)
+)
+
+_binary_ops_dict = {}
+
+for d in (_cmp_ops_dict, _bool_ops_dict, _arith_ops_dict):
+    _binary_ops_dict.update(d)
+
+
+def is_term(obj) -> bool:
+    return isinstance(obj, Term)
+
+
+class BinOp(Op):
+    """
+    Hold a binary operator and its operands.
+
+    Parameters
+    ----------
+    op : str
+    lhs : Term or Op
+    rhs : Term or Op
+    """
+
+    def __init__(self, op: str, lhs, rhs) -> None:
+        super().__init__(op, (lhs, rhs))
+        self.lhs = lhs
+        self.rhs = rhs
+
+        self._disallow_scalar_only_bool_ops()
+
+        self.convert_values()
+
+        try:
+            self.func = _binary_ops_dict[op]
+        except KeyError as err:
+            # has to be made a list for python3
+            keys = list(_binary_ops_dict.keys())
+            raise ValueError(
+                f"Invalid binary operator {repr(op)}, valid operators are {keys}"
+            ) from err
+
+    def __call__(self, env):
+        """
+        Recursively evaluate an expression in Python space.
+
+        Parameters
+        ----------
+        env : Scope
+
+        Returns
+        -------
+        object
+            The result of an evaluated expression.
+        """
+        # recurse over the left/right nodes
+        left = self.lhs(env)
+        right = self.rhs(env)
+
+        return self.func(left, right)
+
+    def evaluate(self, env, engine: str, parser, term_type, eval_in_python):
+        """
+        Evaluate a binary operation *before* being passed to the engine.
+
+        Parameters
+        ----------
+        env : Scope
+        engine : str
+        parser : str
+        term_type : type
+        eval_in_python : list
+
+        Returns
+        -------
+        term_type
+            The "pre-evaluated" expression as an instance of ``term_type``
+        """
+        if engine == "python":
+            res = self(env)
+        else:
+            # recurse over the left/right nodes
+
+            left = self.lhs.evaluate(
+                env,
+                engine=engine,
+                parser=parser,
+                term_type=term_type,
+                eval_in_python=eval_in_python,
+            )
+
+            right = self.rhs.evaluate(
+                env,
+                engine=engine,
+                parser=parser,
+                term_type=term_type,
+                eval_in_python=eval_in_python,
+            )
+
+            # base cases
+            if self.op in eval_in_python:
+                res = self.func(left.value, right.value)
+            else:
+                from pandas.core.computation.eval import eval
+
+                res = eval(self, local_dict=env, engine=engine, parser=parser)
+
+        name = env.add_tmp(res)
+        return term_type(name, env=env)
+
+    def convert_values(self) -> None:
+        """
+        Convert datetimes to a comparable value in an expression.
+        """
+
+        def stringify(value):
+            encoder: Callable
+            if self.encoding is not None:
+                encoder = partial(pprint_thing_encoded, encoding=self.encoding)
+            else:
+                encoder = pprint_thing
+            return encoder(value)
+
+        lhs, rhs = self.lhs, self.rhs
+
+        if is_term(lhs) and lhs.is_datetime and is_term(rhs) and rhs.is_scalar:
+            v = rhs.value
+            if isinstance(v, (int, float)):
+                v = stringify(v)
+            v = Timestamp(ensure_decoded(v))
+            if v.tz is not None:
+                v = v.tz_convert("UTC")
+            self.rhs.update(v)
+
+        if is_term(rhs) and rhs.is_datetime and is_term(lhs) and lhs.is_scalar:
+            v = lhs.value
+            if isinstance(v, (int, float)):
+                v = stringify(v)
+            v = Timestamp(ensure_decoded(v))
+            if v.tz is not None:
+                v = v.tz_convert("UTC")
+            self.lhs.update(v)
+
+    def _disallow_scalar_only_bool_ops(self):
+        rhs = self.rhs
+        lhs = self.lhs
+
+        # GH#24883 unwrap dtype if necessary to ensure we have a type object
+        rhs_rt = rhs.return_type
+        rhs_rt = getattr(rhs_rt, "type", rhs_rt)
+        lhs_rt = lhs.return_type
+        lhs_rt = getattr(lhs_rt, "type", lhs_rt)
+        if (
+            (lhs.is_scalar or rhs.is_scalar)
+            and self.op in _bool_ops_dict
+            and (
+                not (
+                    issubclass(rhs_rt, (bool, np.bool_))
+                    and issubclass(lhs_rt, (bool, np.bool_))
+                )
+            )
+        ):
+            raise NotImplementedError("cannot evaluate scalar only bool ops")
+
+
+def isnumeric(dtype) -> bool:
+    return issubclass(np.dtype(dtype).type, np.number)
+
+
+UNARY_OPS_SYMS = ("+", "-", "~", "not")
+_unary_ops_funcs = (operator.pos, operator.neg, operator.invert, operator.invert)
+_unary_ops_dict = dict(zip(UNARY_OPS_SYMS, _unary_ops_funcs))
+
+
+class UnaryOp(Op):
+    """
+    Hold a unary operator and its operands.
+
+    Parameters
+    ----------
+    op : str
+        The token used to represent the operator.
+    operand : Term or Op
+        The Term or Op operand to the operator.
+
+    Raises
+    ------
+    ValueError
+        * If no function associated with the passed operator token is found.
+    """
+
+    def __init__(self, op: Literal["+", "-", "~", "not"], operand) -> None:
+        super().__init__(op, (operand,))
+        self.operand = operand
+
+        try:
+            self.func = _unary_ops_dict[op]
+        except KeyError as err:
+            raise ValueError(
+                f"Invalid unary operator {repr(op)}, "
+                f"valid operators are {UNARY_OPS_SYMS}"
+            ) from err
+
+    def __call__(self, env) -> MathCall:
+        operand = self.operand(env)
+        # error: Cannot call function of unknown type
+        return self.func(operand)  # type: ignore[operator]
+
+    def __repr__(self) -> str:
+        return pprint_thing(f"{self.op}({self.operand})")
+
+    @property
+    def return_type(self) -> np.dtype:
+        operand = self.operand
+        if operand.return_type == np.dtype("bool"):
+            return np.dtype("bool")
+        if isinstance(operand, Op) and (
+            operand.op in _cmp_ops_dict or operand.op in _bool_ops_dict
+        ):
+            return np.dtype("bool")
+        return np.dtype("int")
+
+
+class MathCall(Op):
+    def __init__(self, func, args) -> None:
+        super().__init__(func.name, args)
+        self.func = func
+
+    def __call__(self, env):
+        # error: "Op" not callable
+        operands = [op(env) for op in self.operands]  # type: ignore[operator]
+        return self.func.func(*operands)
+
+    def __repr__(self) -> str:
+        operands = map(str, self.operands)
+        return pprint_thing(f"{self.op}({','.join(operands)})")
+
+
+class FuncNode:
+    def __init__(self, name: str) -> None:
+        if name not in MATHOPS:
+            raise ValueError(f'"{name}" is not a supported function')
+        self.name = name
+        self.func = getattr(np, name)
+
+    def __call__(self, *args) -> MathCall:
+        return MathCall(self, args)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/parsing.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/parsing.py
new file mode 100644
index 0000000000000000000000000000000000000000..4cfa0f2baffd5ed45db19242c2afd00b6e5e23dc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/parsing.py
@@ -0,0 +1,198 @@
+"""
+:func:`~pandas.eval` source string parsing functions
+"""
+from __future__ import annotations
+
+from io import StringIO
+from keyword import iskeyword
+import token
+import tokenize
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+    )
+
+# A token value Python's tokenizer probably will never use.
+BACKTICK_QUOTED_STRING = 100
+
+
+def create_valid_python_identifier(name: str) -> str:
+    """
+    Create valid Python identifiers from any string.
+
+    Check if name contains any special characters. If it contains any
+    special characters, the special characters will be replaced by
+    a special string and a prefix is added.
+
+    Raises
+    ------
+    SyntaxError
+        If the returned name is not a Python valid identifier, raise an exception.
+        This can happen if there is a hashtag in the name, as the tokenizer will
+        than terminate and not find the backtick.
+        But also for characters that fall out of the range of (U+0001..U+007F).
+    """
+    if name.isidentifier() and not iskeyword(name):
+        return name
+
+    # Create a dict with the special characters and their replacement string.
+    # EXACT_TOKEN_TYPES contains these special characters
+    # token.tok_name contains a readable description of the replacement string.
+    special_characters_replacements = {
+        char: f"_{token.tok_name[tokval]}_"
+        for char, tokval in (tokenize.EXACT_TOKEN_TYPES.items())
+    }
+    special_characters_replacements.update(
+        {
+            " ": "_",
+            "?": "_QUESTIONMARK_",
+            "!": "_EXCLAMATIONMARK_",
+            "$": "_DOLLARSIGN_",
+            "€": "_EUROSIGN_",
+            "°": "_DEGREESIGN_",
+            # Including quotes works, but there are exceptions.
+            "'": "_SINGLEQUOTE_",
+            '"': "_DOUBLEQUOTE_",
+            # Currently not possible. Terminates parser and won't find backtick.
+            # "#": "_HASH_",
+        }
+    )
+
+    name = "".join([special_characters_replacements.get(char, char) for char in name])
+    name = f"BACKTICK_QUOTED_STRING_{name}"
+
+    if not name.isidentifier():
+        raise SyntaxError(f"Could not convert '{name}' to a valid Python identifier.")
+
+    return name
+
+
+def clean_backtick_quoted_toks(tok: tuple[int, str]) -> tuple[int, str]:
+    """
+    Clean up a column name if surrounded by backticks.
+
+    Backtick quoted string are indicated by a certain tokval value. If a string
+    is a backtick quoted token it will processed by
+    :func:`_create_valid_python_identifier` so that the parser can find this
+    string when the query is executed.
+    In this case the tok will get the NAME tokval.
+
+    Parameters
+    ----------
+    tok : tuple of int, str
+        ints correspond to the all caps constants in the tokenize module
+
+    Returns
+    -------
+    tok : Tuple[int, str]
+        Either the input or token or the replacement values
+    """
+    toknum, tokval = tok
+    if toknum == BACKTICK_QUOTED_STRING:
+        return tokenize.NAME, create_valid_python_identifier(tokval)
+    return toknum, tokval
+
+
+def clean_column_name(name: Hashable) -> Hashable:
+    """
+    Function to emulate the cleaning of a backtick quoted name.
+
+    The purpose for this function is to see what happens to the name of
+    identifier if it goes to the process of being parsed a Python code
+    inside a backtick quoted string and than being cleaned
+    (removed of any special characters).
+
+    Parameters
+    ----------
+    name : hashable
+        Name to be cleaned.
+
+    Returns
+    -------
+    name : hashable
+        Returns the name after tokenizing and cleaning.
+
+    Notes
+    -----
+        For some cases, a name cannot be converted to a valid Python identifier.
+        In that case :func:`tokenize_string` raises a SyntaxError.
+        In that case, we just return the name unmodified.
+
+        If this name was used in the query string (this makes the query call impossible)
+        an error will be raised by :func:`tokenize_backtick_quoted_string` instead,
+        which is not caught and propagates to the user level.
+    """
+    try:
+        tokenized = tokenize_string(f"`{name}`")
+        tokval = next(tokenized)[1]
+        return create_valid_python_identifier(tokval)
+    except SyntaxError:
+        return name
+
+
+def tokenize_backtick_quoted_string(
+    token_generator: Iterator[tokenize.TokenInfo], source: str, string_start: int
+) -> tuple[int, str]:
+    """
+    Creates a token from a backtick quoted string.
+
+    Moves the token_generator forwards till right after the next backtick.
+
+    Parameters
+    ----------
+    token_generator : Iterator[tokenize.TokenInfo]
+        The generator that yields the tokens of the source string (Tuple[int, str]).
+        The generator is at the first token after the backtick (`)
+
+    source : str
+        The Python source code string.
+
+    string_start : int
+        This is the start of backtick quoted string inside the source string.
+
+    Returns
+    -------
+    tok: Tuple[int, str]
+        The token that represents the backtick quoted string.
+        The integer is equal to BACKTICK_QUOTED_STRING (100).
+    """
+    for _, tokval, start, _, _ in token_generator:
+        if tokval == "`":
+            string_end = start[1]
+            break
+
+    return BACKTICK_QUOTED_STRING, source[string_start:string_end]
+
+
+def tokenize_string(source: str) -> Iterator[tuple[int, str]]:
+    """
+    Tokenize a Python source code string.
+
+    Parameters
+    ----------
+    source : str
+        The Python source code string.
+
+    Returns
+    -------
+    tok_generator : Iterator[Tuple[int, str]]
+        An iterator yielding all tokens with only toknum and tokval (Tuple[ing, str]).
+    """
+    line_reader = StringIO(source).readline
+    token_generator = tokenize.generate_tokens(line_reader)
+
+    # Loop over all tokens till a backtick (`) is found.
+    # Then, take all tokens till the next backtick to form a backtick quoted string
+    for toknum, tokval, start, _, _ in token_generator:
+        if tokval == "`":
+            try:
+                yield tokenize_backtick_quoted_string(
+                    token_generator, source, string_start=start[1] + 1
+                )
+            except Exception as err:
+                raise SyntaxError(f"Failed to parse backticks in '{source}'.") from err
+        else:
+            yield toknum, tokval
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/pytables.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/pytables.py
new file mode 100644
index 0000000000000000000000000000000000000000..04a8ad7ef0be6b044baf65b80cbf4161d45f8cac
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/pytables.py
@@ -0,0 +1,666 @@
+""" manage PyTables query interface via Expressions """
+from __future__ import annotations
+
+import ast
+from decimal import (
+    Decimal,
+    InvalidOperation,
+)
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import (
+    Timedelta,
+    Timestamp,
+)
+from pandas.errors import UndefinedVariableError
+
+from pandas.core.dtypes.common import is_list_like
+
+import pandas.core.common as com
+from pandas.core.computation import (
+    expr,
+    ops,
+    scope as _scope,
+)
+from pandas.core.computation.common import ensure_decoded
+from pandas.core.computation.expr import BaseExprVisitor
+from pandas.core.computation.ops import is_term
+from pandas.core.construction import extract_array
+from pandas.core.indexes.base import Index
+
+from pandas.io.formats.printing import (
+    pprint_thing,
+    pprint_thing_encoded,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Self,
+        npt,
+    )
+
+
+class PyTablesScope(_scope.Scope):
+    __slots__ = ("queryables",)
+
+    queryables: dict[str, Any]
+
+    def __init__(
+        self,
+        level: int,
+        global_dict=None,
+        local_dict=None,
+        queryables: dict[str, Any] | None = None,
+    ) -> None:
+        super().__init__(level + 1, global_dict=global_dict, local_dict=local_dict)
+        self.queryables = queryables or {}
+
+
+class Term(ops.Term):
+    env: PyTablesScope
+
+    def __new__(cls, name, env, side=None, encoding=None):
+        if isinstance(name, str):
+            klass = cls
+        else:
+            klass = Constant
+        return object.__new__(klass)
+
+    def __init__(self, name, env: PyTablesScope, side=None, encoding=None) -> None:
+        super().__init__(name, env, side=side, encoding=encoding)
+
+    def _resolve_name(self):
+        # must be a queryables
+        if self.side == "left":
+            # Note: The behavior of __new__ ensures that self.name is a str here
+            if self.name not in self.env.queryables:
+                raise NameError(f"name {repr(self.name)} is not defined")
+            return self.name
+
+        # resolve the rhs (and allow it to be None)
+        try:
+            return self.env.resolve(self.name, is_local=False)
+        except UndefinedVariableError:
+            return self.name
+
+    # read-only property overwriting read/write property
+    @property  # type: ignore[misc]
+    def value(self):
+        return self._value
+
+
+class Constant(Term):
+    def __init__(self, name, env: PyTablesScope, side=None, encoding=None) -> None:
+        assert isinstance(env, PyTablesScope), type(env)
+        super().__init__(name, env, side=side, encoding=encoding)
+
+    def _resolve_name(self):
+        return self._name
+
+
+class BinOp(ops.BinOp):
+    _max_selectors = 31
+
+    op: str
+    queryables: dict[str, Any]
+    condition: str | None
+
+    def __init__(self, op: str, lhs, rhs, queryables: dict[str, Any], encoding) -> None:
+        super().__init__(op, lhs, rhs)
+        self.queryables = queryables
+        self.encoding = encoding
+        self.condition = None
+
+    def _disallow_scalar_only_bool_ops(self) -> None:
+        pass
+
+    def prune(self, klass):
+        def pr(left, right):
+            """create and return a new specialized BinOp from myself"""
+            if left is None:
+                return right
+            elif right is None:
+                return left
+
+            k = klass
+            if isinstance(left, ConditionBinOp):
+                if isinstance(right, ConditionBinOp):
+                    k = JointConditionBinOp
+                elif isinstance(left, k):
+                    return left
+                elif isinstance(right, k):
+                    return right
+
+            elif isinstance(left, FilterBinOp):
+                if isinstance(right, FilterBinOp):
+                    k = JointFilterBinOp
+                elif isinstance(left, k):
+                    return left
+                elif isinstance(right, k):
+                    return right
+
+            return k(
+                self.op, left, right, queryables=self.queryables, encoding=self.encoding
+            ).evaluate()
+
+        left, right = self.lhs, self.rhs
+
+        if is_term(left) and is_term(right):
+            res = pr(left.value, right.value)
+        elif not is_term(left) and is_term(right):
+            res = pr(left.prune(klass), right.value)
+        elif is_term(left) and not is_term(right):
+            res = pr(left.value, right.prune(klass))
+        elif not (is_term(left) or is_term(right)):
+            res = pr(left.prune(klass), right.prune(klass))
+
+        return res
+
+    def conform(self, rhs):
+        """inplace conform rhs"""
+        if not is_list_like(rhs):
+            rhs = [rhs]
+        if isinstance(rhs, np.ndarray):
+            rhs = rhs.ravel()
+        return rhs
+
+    @property
+    def is_valid(self) -> bool:
+        """return True if this is a valid field"""
+        return self.lhs in self.queryables
+
+    @property
+    def is_in_table(self) -> bool:
+        """
+        return True if this is a valid column name for generation (e.g. an
+        actual column in the table)
+        """
+        return self.queryables.get(self.lhs) is not None
+
+    @property
+    def kind(self):
+        """the kind of my field"""
+        return getattr(self.queryables.get(self.lhs), "kind", None)
+
+    @property
+    def meta(self):
+        """the meta of my field"""
+        return getattr(self.queryables.get(self.lhs), "meta", None)
+
+    @property
+    def metadata(self):
+        """the metadata of my field"""
+        return getattr(self.queryables.get(self.lhs), "metadata", None)
+
+    def generate(self, v) -> str:
+        """create and return the op string for this TermValue"""
+        val = v.tostring(self.encoding)
+        return f"({self.lhs} {self.op} {val})"
+
+    def convert_value(self, v) -> TermValue:
+        """
+        convert the expression that is in the term to something that is
+        accepted by pytables
+        """
+
+        def stringify(value):
+            if self.encoding is not None:
+                return pprint_thing_encoded(value, encoding=self.encoding)
+            return pprint_thing(value)
+
+        kind = ensure_decoded(self.kind)
+        meta = ensure_decoded(self.meta)
+        if kind == "datetime" or (kind and kind.startswith("datetime64")):
+            if isinstance(v, (int, float)):
+                v = stringify(v)
+            v = ensure_decoded(v)
+            v = Timestamp(v).as_unit("ns")
+            if v.tz is not None:
+                v = v.tz_convert("UTC")
+            return TermValue(v, v._value, kind)
+        elif kind in ("timedelta64", "timedelta"):
+            if isinstance(v, str):
+                v = Timedelta(v)
+            else:
+                v = Timedelta(v, unit="s")
+            v = v.as_unit("ns")._value
+            return TermValue(int(v), v, kind)
+        elif meta == "category":
+            metadata = extract_array(self.metadata, extract_numpy=True)
+            result: npt.NDArray[np.intp] | np.intp | int
+            if v not in metadata:
+                result = -1
+            else:
+                result = metadata.searchsorted(v, side="left")
+            return TermValue(result, result, "integer")
+        elif kind == "integer":
+            try:
+                v_dec = Decimal(v)
+            except InvalidOperation:
+                # GH 54186
+                # convert v to float to raise float's ValueError
+                float(v)
+            else:
+                v = int(v_dec.to_integral_exact(rounding="ROUND_HALF_EVEN"))
+            return TermValue(v, v, kind)
+        elif kind == "float":
+            v = float(v)
+            return TermValue(v, v, kind)
+        elif kind == "bool":
+            if isinstance(v, str):
+                v = v.strip().lower() not in [
+                    "false",
+                    "f",
+                    "no",
+                    "n",
+                    "none",
+                    "0",
+                    "[]",
+                    "{}",
+                    "",
+                ]
+            else:
+                v = bool(v)
+            return TermValue(v, v, kind)
+        elif isinstance(v, str):
+            # string quoting
+            return TermValue(v, stringify(v), "string")
+        else:
+            raise TypeError(f"Cannot compare {v} of type {type(v)} to {kind} column")
+
+    def convert_values(self) -> None:
+        pass
+
+
+class FilterBinOp(BinOp):
+    filter: tuple[Any, Any, Index] | None = None
+
+    def __repr__(self) -> str:
+        if self.filter is None:
+            return "Filter: Not Initialized"
+        return pprint_thing(f"[Filter : [{self.filter[0]}] -> [{self.filter[1]}]")
+
+    def invert(self) -> Self:
+        """invert the filter"""
+        if self.filter is not None:
+            self.filter = (
+                self.filter[0],
+                self.generate_filter_op(invert=True),
+                self.filter[2],
+            )
+        return self
+
+    def format(self):
+        """return the actual filter format"""
+        return [self.filter]
+
+    # error: Signature of "evaluate" incompatible with supertype "BinOp"
+    def evaluate(self) -> Self | None:  # type: ignore[override]
+        if not self.is_valid:
+            raise ValueError(f"query term is not valid [{self}]")
+
+        rhs = self.conform(self.rhs)
+        values = list(rhs)
+
+        if self.is_in_table:
+            # if too many values to create the expression, use a filter instead
+            if self.op in ["==", "!="] and len(values) > self._max_selectors:
+                filter_op = self.generate_filter_op()
+                self.filter = (self.lhs, filter_op, Index(values))
+
+                return self
+            return None
+
+        # equality conditions
+        if self.op in ["==", "!="]:
+            filter_op = self.generate_filter_op()
+            self.filter = (self.lhs, filter_op, Index(values))
+
+        else:
+            raise TypeError(
+                f"passing a filterable condition to a non-table indexer [{self}]"
+            )
+
+        return self
+
+    def generate_filter_op(self, invert: bool = False):
+        if (self.op == "!=" and not invert) or (self.op == "==" and invert):
+            return lambda axis, vals: ~axis.isin(vals)
+        else:
+            return lambda axis, vals: axis.isin(vals)
+
+
+class JointFilterBinOp(FilterBinOp):
+    def format(self):
+        raise NotImplementedError("unable to collapse Joint Filters")
+
+    # error: Signature of "evaluate" incompatible with supertype "BinOp"
+    def evaluate(self) -> Self:  # type: ignore[override]
+        return self
+
+
+class ConditionBinOp(BinOp):
+    def __repr__(self) -> str:
+        return pprint_thing(f"[Condition : [{self.condition}]]")
+
+    def invert(self):
+        """invert the condition"""
+        # if self.condition is not None:
+        #    self.condition = "~(%s)" % self.condition
+        # return self
+        raise NotImplementedError(
+            "cannot use an invert condition when passing to numexpr"
+        )
+
+    def format(self):
+        """return the actual ne format"""
+        return self.condition
+
+    # error: Signature of "evaluate" incompatible with supertype "BinOp"
+    def evaluate(self) -> Self | None:  # type: ignore[override]
+        if not self.is_valid:
+            raise ValueError(f"query term is not valid [{self}]")
+
+        # convert values if we are in the table
+        if not self.is_in_table:
+            return None
+
+        rhs = self.conform(self.rhs)
+        values = [self.convert_value(v) for v in rhs]
+
+        # equality conditions
+        if self.op in ["==", "!="]:
+            # too many values to create the expression?
+            if len(values) <= self._max_selectors:
+                vs = [self.generate(v) for v in values]
+                self.condition = f"({' | '.join(vs)})"
+
+            # use a filter after reading
+            else:
+                return None
+        else:
+            self.condition = self.generate(values[0])
+
+        return self
+
+
+class JointConditionBinOp(ConditionBinOp):
+    # error: Signature of "evaluate" incompatible with supertype "BinOp"
+    def evaluate(self) -> Self:  # type: ignore[override]
+        self.condition = f"({self.lhs.condition} {self.op} {self.rhs.condition})"
+        return self
+
+
+class UnaryOp(ops.UnaryOp):
+    def prune(self, klass):
+        if self.op != "~":
+            raise NotImplementedError("UnaryOp only support invert type ops")
+
+        operand = self.operand
+        operand = operand.prune(klass)
+
+        if operand is not None and (
+            issubclass(klass, ConditionBinOp)
+            and operand.condition is not None
+            or not issubclass(klass, ConditionBinOp)
+            and issubclass(klass, FilterBinOp)
+            and operand.filter is not None
+        ):
+            return operand.invert()
+        return None
+
+
+class PyTablesExprVisitor(BaseExprVisitor):
+    const_type: ClassVar[type[ops.Term]] = Constant
+    term_type: ClassVar[type[Term]] = Term
+
+    def __init__(self, env, engine, parser, **kwargs) -> None:
+        super().__init__(env, engine, parser)
+        for bin_op in self.binary_ops:
+            bin_node = self.binary_op_nodes_map[bin_op]
+            setattr(
+                self,
+                f"visit_{bin_node}",
+                lambda node, bin_op=bin_op: partial(BinOp, bin_op, **kwargs),
+            )
+
+    def visit_UnaryOp(self, node, **kwargs) -> ops.Term | UnaryOp | None:
+        if isinstance(node.op, (ast.Not, ast.Invert)):
+            return UnaryOp("~", self.visit(node.operand))
+        elif isinstance(node.op, ast.USub):
+            return self.const_type(-self.visit(node.operand).value, self.env)
+        elif isinstance(node.op, ast.UAdd):
+            raise NotImplementedError("Unary addition not supported")
+        # TODO: return None might never be reached
+        return None
+
+    def visit_Index(self, node, **kwargs):
+        return self.visit(node.value).value
+
+    def visit_Assign(self, node, **kwargs):
+        cmpr = ast.Compare(
+            ops=[ast.Eq()], left=node.targets[0], comparators=[node.value]
+        )
+        return self.visit(cmpr)
+
+    def visit_Subscript(self, node, **kwargs) -> ops.Term:
+        # only allow simple subscripts
+
+        value = self.visit(node.value)
+        slobj = self.visit(node.slice)
+        try:
+            value = value.value
+        except AttributeError:
+            pass
+
+        if isinstance(slobj, Term):
+            # In py39 np.ndarray lookups with Term containing int raise
+            slobj = slobj.value
+
+        try:
+            return self.const_type(value[slobj], self.env)
+        except TypeError as err:
+            raise ValueError(
+                f"cannot subscript {repr(value)} with {repr(slobj)}"
+            ) from err
+
+    def visit_Attribute(self, node, **kwargs):
+        attr = node.attr
+        value = node.value
+
+        ctx = type(node.ctx)
+        if ctx == ast.Load:
+            # resolve the value
+            resolved = self.visit(value)
+
+            # try to get the value to see if we are another expression
+            try:
+                resolved = resolved.value
+            except AttributeError:
+                pass
+
+            try:
+                return self.term_type(getattr(resolved, attr), self.env)
+            except AttributeError:
+                # something like datetime.datetime where scope is overridden
+                if isinstance(value, ast.Name) and value.id == attr:
+                    return resolved
+
+        raise ValueError(f"Invalid Attribute context {ctx.__name__}")
+
+    def translate_In(self, op):
+        return ast.Eq() if isinstance(op, ast.In) else op
+
+    def _rewrite_membership_op(self, node, left, right):
+        return self.visit(node.op), node.op, left, right
+
+
+def _validate_where(w):
+    """
+    Validate that the where statement is of the right type.
+
+    The type may either be String, Expr, or list-like of Exprs.
+
+    Parameters
+    ----------
+    w : String term expression, Expr, or list-like of Exprs.
+
+    Returns
+    -------
+    where : The original where clause if the check was successful.
+
+    Raises
+    ------
+    TypeError : An invalid data type was passed in for w (e.g. dict).
+    """
+    if not (isinstance(w, (PyTablesExpr, str)) or is_list_like(w)):
+        raise TypeError(
+            "where must be passed as a string, PyTablesExpr, "
+            "or list-like of PyTablesExpr"
+        )
+
+    return w
+
+
+class PyTablesExpr(expr.Expr):
+    """
+    Hold a pytables-like expression, comprised of possibly multiple 'terms'.
+
+    Parameters
+    ----------
+    where : string term expression, PyTablesExpr, or list-like of PyTablesExprs
+    queryables : a "kinds" map (dict of column name -> kind), or None if column
+        is non-indexable
+    encoding : an encoding that will encode the query terms
+
+    Returns
+    -------
+    a PyTablesExpr object
+
+    Examples
+    --------
+    'index>=date'
+    "columns=['A', 'D']"
+    'columns=A'
+    'columns==A'
+    "~(columns=['A','B'])"
+    'index>df.index[3] & string="bar"'
+    '(index>df.index[3] & index<=df.index[6]) | string="bar"'
+    "ts>=Timestamp('2012-02-01')"
+    "major_axis>=20130101"
+    """
+
+    _visitor: PyTablesExprVisitor | None
+    env: PyTablesScope
+    expr: str
+
+    def __init__(
+        self,
+        where,
+        queryables: dict[str, Any] | None = None,
+        encoding=None,
+        scope_level: int = 0,
+    ) -> None:
+        where = _validate_where(where)
+
+        self.encoding = encoding
+        self.condition = None
+        self.filter = None
+        self.terms = None
+        self._visitor = None
+
+        # capture the environment if needed
+        local_dict: _scope.DeepChainMap[Any, Any] | None = None
+
+        if isinstance(where, PyTablesExpr):
+            local_dict = where.env.scope
+            _where = where.expr
+
+        elif is_list_like(where):
+            where = list(where)
+            for idx, w in enumerate(where):
+                if isinstance(w, PyTablesExpr):
+                    local_dict = w.env.scope
+                else:
+                    where[idx] = _validate_where(w)
+            _where = " & ".join([f"({w})" for w in com.flatten(where)])
+        else:
+            # _validate_where ensures we otherwise have a string
+            _where = where
+
+        self.expr = _where
+        self.env = PyTablesScope(scope_level + 1, local_dict=local_dict)
+
+        if queryables is not None and isinstance(self.expr, str):
+            self.env.queryables.update(queryables)
+            self._visitor = PyTablesExprVisitor(
+                self.env,
+                queryables=queryables,
+                parser="pytables",
+                engine="pytables",
+                encoding=encoding,
+            )
+            self.terms = self.parse()
+
+    def __repr__(self) -> str:
+        if self.terms is not None:
+            return pprint_thing(self.terms)
+        return pprint_thing(self.expr)
+
+    def evaluate(self):
+        """create and return the numexpr condition and filter"""
+        try:
+            self.condition = self.terms.prune(ConditionBinOp)
+        except AttributeError as err:
+            raise ValueError(
+                f"cannot process expression [{self.expr}], [{self}] "
+                "is not a valid condition"
+            ) from err
+        try:
+            self.filter = self.terms.prune(FilterBinOp)
+        except AttributeError as err:
+            raise ValueError(
+                f"cannot process expression [{self.expr}], [{self}] "
+                "is not a valid filter"
+            ) from err
+
+        return self.condition, self.filter
+
+
+class TermValue:
+    """hold a term value the we use to construct a condition/filter"""
+
+    def __init__(self, value, converted, kind: str) -> None:
+        assert isinstance(kind, str), kind
+        self.value = value
+        self.converted = converted
+        self.kind = kind
+
+    def tostring(self, encoding) -> str:
+        """quote the string if not encoded else encode and return"""
+        if self.kind == "string":
+            if encoding is not None:
+                return str(self.converted)
+            return f'"{self.converted}"'
+        elif self.kind == "float":
+            # python 2 str(float) is not always
+            # round-trippable so use repr()
+            return repr(self.converted)
+        return str(self.converted)
+
+
+def maybe_expression(s) -> bool:
+    """loose checking if s is a pytables-acceptable expression"""
+    if not isinstance(s, str):
+        return False
+    operations = PyTablesExprVisitor.binary_ops + PyTablesExprVisitor.unary_ops + ("=",)
+
+    # make sure we have an op at least
+    return any(op in s for op in operations)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/computation/scope.py b/.venv/lib/python3.13/site-packages/pandas/core/computation/scope.py
new file mode 100644
index 0000000000000000000000000000000000000000..7e553ca448218435eafe1fd7ca97dce6f739e2a3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/computation/scope.py
@@ -0,0 +1,355 @@
+"""
+Module for scope operations
+"""
+from __future__ import annotations
+
+from collections import ChainMap
+import datetime
+import inspect
+from io import StringIO
+import itertools
+import pprint
+import struct
+import sys
+from typing import TypeVar
+
+import numpy as np
+
+from pandas._libs.tslibs import Timestamp
+from pandas.errors import UndefinedVariableError
+
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+
+
+# https://docs.python.org/3/library/collections.html#chainmap-examples-and-recipes
+class DeepChainMap(ChainMap[_KT, _VT]):
+    """
+    Variant of ChainMap that allows direct updates to inner scopes.
+
+    Only works when all passed mapping are mutable.
+    """
+
+    def __setitem__(self, key: _KT, value: _VT) -> None:
+        for mapping in self.maps:
+            if key in mapping:
+                mapping[key] = value
+                return
+        self.maps[0][key] = value
+
+    def __delitem__(self, key: _KT) -> None:
+        """
+        Raises
+        ------
+        KeyError
+            If `key` doesn't exist.
+        """
+        for mapping in self.maps:
+            if key in mapping:
+                del mapping[key]
+                return
+        raise KeyError(key)
+
+
+def ensure_scope(
+    level: int, global_dict=None, local_dict=None, resolvers=(), target=None
+) -> Scope:
+    """Ensure that we are grabbing the correct scope."""
+    return Scope(
+        level + 1,
+        global_dict=global_dict,
+        local_dict=local_dict,
+        resolvers=resolvers,
+        target=target,
+    )
+
+
+def _replacer(x) -> str:
+    """
+    Replace a number with its hexadecimal representation. Used to tag
+    temporary variables with their calling scope's id.
+    """
+    # get the hex repr of the binary char and remove 0x and pad by pad_size
+    # zeros
+    try:
+        hexin = ord(x)
+    except TypeError:
+        # bytes literals masquerade as ints when iterating in py3
+        hexin = x
+
+    return hex(hexin)
+
+
+def _raw_hex_id(obj) -> str:
+    """Return the padded hexadecimal id of ``obj``."""
+    # interpret as a pointer since that's what really what id returns
+    packed = struct.pack("@P", id(obj))
+    return "".join([_replacer(x) for x in packed])
+
+
+DEFAULT_GLOBALS = {
+    "Timestamp": Timestamp,
+    "datetime": datetime.datetime,
+    "True": True,
+    "False": False,
+    "list": list,
+    "tuple": tuple,
+    "inf": np.inf,
+    "Inf": np.inf,
+}
+
+
+def _get_pretty_string(obj) -> str:
+    """
+    Return a prettier version of obj.
+
+    Parameters
+    ----------
+    obj : object
+        Object to pretty print
+
+    Returns
+    -------
+    str
+        Pretty print object repr
+    """
+    sio = StringIO()
+    pprint.pprint(obj, stream=sio)
+    return sio.getvalue()
+
+
+class Scope:
+    """
+    Object to hold scope, with a few bells to deal with some custom syntax
+    and contexts added by pandas.
+
+    Parameters
+    ----------
+    level : int
+    global_dict : dict or None, optional, default None
+    local_dict : dict or Scope or None, optional, default None
+    resolvers : list-like or None, optional, default None
+    target : object
+
+    Attributes
+    ----------
+    level : int
+    scope : DeepChainMap
+    target : object
+    temps : dict
+    """
+
+    __slots__ = ["level", "scope", "target", "resolvers", "temps"]
+    level: int
+    scope: DeepChainMap
+    resolvers: DeepChainMap
+    temps: dict
+
+    def __init__(
+        self, level: int, global_dict=None, local_dict=None, resolvers=(), target=None
+    ) -> None:
+        self.level = level + 1
+
+        # shallow copy because we don't want to keep filling this up with what
+        # was there before if there are multiple calls to Scope/_ensure_scope
+        self.scope = DeepChainMap(DEFAULT_GLOBALS.copy())
+        self.target = target
+
+        if isinstance(local_dict, Scope):
+            self.scope.update(local_dict.scope)
+            if local_dict.target is not None:
+                self.target = local_dict.target
+            self._update(local_dict.level)
+
+        frame = sys._getframe(self.level)
+
+        try:
+            # shallow copy here because we don't want to replace what's in
+            # scope when we align terms (alignment accesses the underlying
+            # numpy array of pandas objects)
+            scope_global = self.scope.new_child(
+                (global_dict if global_dict is not None else frame.f_globals).copy()
+            )
+            self.scope = DeepChainMap(scope_global)
+            if not isinstance(local_dict, Scope):
+                scope_local = self.scope.new_child(
+                    (local_dict if local_dict is not None else frame.f_locals).copy()
+                )
+                self.scope = DeepChainMap(scope_local)
+        finally:
+            del frame
+
+        # assumes that resolvers are going from outermost scope to inner
+        if isinstance(local_dict, Scope):
+            resolvers += tuple(local_dict.resolvers.maps)
+        self.resolvers = DeepChainMap(*resolvers)
+        self.temps = {}
+
+    def __repr__(self) -> str:
+        scope_keys = _get_pretty_string(list(self.scope.keys()))
+        res_keys = _get_pretty_string(list(self.resolvers.keys()))
+        return f"{type(self).__name__}(scope={scope_keys}, resolvers={res_keys})"
+
+    @property
+    def has_resolvers(self) -> bool:
+        """
+        Return whether we have any extra scope.
+
+        For example, DataFrames pass Their columns as resolvers during calls to
+        ``DataFrame.eval()`` and ``DataFrame.query()``.
+
+        Returns
+        -------
+        hr : bool
+        """
+        return bool(len(self.resolvers))
+
+    def resolve(self, key: str, is_local: bool):
+        """
+        Resolve a variable name in a possibly local context.
+
+        Parameters
+        ----------
+        key : str
+            A variable name
+        is_local : bool
+            Flag indicating whether the variable is local or not (prefixed with
+            the '@' symbol)
+
+        Returns
+        -------
+        value : object
+            The value of a particular variable
+        """
+        try:
+            # only look for locals in outer scope
+            if is_local:
+                return self.scope[key]
+
+            # not a local variable so check in resolvers if we have them
+            if self.has_resolvers:
+                return self.resolvers[key]
+
+            # if we're here that means that we have no locals and we also have
+            # no resolvers
+            assert not is_local and not self.has_resolvers
+            return self.scope[key]
+        except KeyError:
+            try:
+                # last ditch effort we look in temporaries
+                # these are created when parsing indexing expressions
+                # e.g., df[df > 0]
+                return self.temps[key]
+            except KeyError as err:
+                raise UndefinedVariableError(key, is_local) from err
+
+    def swapkey(self, old_key: str, new_key: str, new_value=None) -> None:
+        """
+        Replace a variable name, with a potentially new value.
+
+        Parameters
+        ----------
+        old_key : str
+            Current variable name to replace
+        new_key : str
+            New variable name to replace `old_key` with
+        new_value : object
+            Value to be replaced along with the possible renaming
+        """
+        if self.has_resolvers:
+            maps = self.resolvers.maps + self.scope.maps
+        else:
+            maps = self.scope.maps
+
+        maps.append(self.temps)
+
+        for mapping in maps:
+            if old_key in mapping:
+                mapping[new_key] = new_value
+                return
+
+    def _get_vars(self, stack, scopes: list[str]) -> None:
+        """
+        Get specifically scoped variables from a list of stack frames.
+
+        Parameters
+        ----------
+        stack : list
+            A list of stack frames as returned by ``inspect.stack()``
+        scopes : sequence of strings
+            A sequence containing valid stack frame attribute names that
+            evaluate to a dictionary. For example, ('locals', 'globals')
+        """
+        variables = itertools.product(scopes, stack)
+        for scope, (frame, _, _, _, _, _) in variables:
+            try:
+                d = getattr(frame, f"f_{scope}")
+                self.scope = DeepChainMap(self.scope.new_child(d))
+            finally:
+                # won't remove it, but DECREF it
+                # in Py3 this probably isn't necessary since frame won't be
+                # scope after the loop
+                del frame
+
+    def _update(self, level: int) -> None:
+        """
+        Update the current scope by going back `level` levels.
+
+        Parameters
+        ----------
+        level : int
+        """
+        sl = level + 1
+
+        # add sl frames to the scope starting with the
+        # most distant and overwriting with more current
+        # makes sure that we can capture variable scope
+        stack = inspect.stack()
+
+        try:
+            self._get_vars(stack[:sl], scopes=["locals"])
+        finally:
+            del stack[:], stack
+
+    def add_tmp(self, value) -> str:
+        """
+        Add a temporary variable to the scope.
+
+        Parameters
+        ----------
+        value : object
+            An arbitrary object to be assigned to a temporary variable.
+
+        Returns
+        -------
+        str
+            The name of the temporary variable created.
+        """
+        name = f"{type(value).__name__}_{self.ntemps}_{_raw_hex_id(self)}"
+
+        # add to inner most scope
+        assert name not in self.temps
+        self.temps[name] = value
+        assert name in self.temps
+
+        # only increment if the variable gets put in the scope
+        return name
+
+    @property
+    def ntemps(self) -> int:
+        """The number of temporary variables in this scope"""
+        return len(self.temps)
+
+    @property
+    def full_scope(self) -> DeepChainMap:
+        """
+        Return the full scope for use with passing to engines transparently
+        as a mapping.
+
+        Returns
+        -------
+        vars : DeepChainMap
+            All variables in this scope.
+        """
+        maps = [self.temps] + self.resolvers.maps + self.scope.maps
+        return DeepChainMap(*maps)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/config_init.py b/.venv/lib/python3.13/site-packages/pandas/core/config_init.py
new file mode 100644
index 0000000000000000000000000000000000000000..a1df455eebacf8868384ad383ee34c934d059df3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/config_init.py
@@ -0,0 +1,941 @@
+"""
+This module is imported from the pandas package __init__.py file
+in order to ensure that the core.config options registered here will
+be available as soon as the user loads the package. if register_option
+is invoked inside specific modules, they will not be registered until that
+module is imported, which may or may not be a problem.
+
+If you need to make sure options are available even before a certain
+module is imported, register them here rather than in the module.
+
+"""
+from __future__ import annotations
+
+import os
+from typing import (
+    Any,
+    Callable,
+)
+
+import pandas._config.config as cf
+from pandas._config.config import (
+    is_bool,
+    is_callable,
+    is_instance_factory,
+    is_int,
+    is_nonnegative_int,
+    is_one_of_factory,
+    is_str,
+    is_text,
+)
+
+# compute
+
+use_bottleneck_doc = """
+: bool
+    Use the bottleneck library to accelerate if it is installed,
+    the default is True
+    Valid values: False,True
+"""
+
+
+def use_bottleneck_cb(key) -> None:
+    from pandas.core import nanops
+
+    nanops.set_use_bottleneck(cf.get_option(key))
+
+
+use_numexpr_doc = """
+: bool
+    Use the numexpr library to accelerate computation if it is installed,
+    the default is True
+    Valid values: False,True
+"""
+
+
+def use_numexpr_cb(key) -> None:
+    from pandas.core.computation import expressions
+
+    expressions.set_use_numexpr(cf.get_option(key))
+
+
+use_numba_doc = """
+: bool
+    Use the numba engine option for select operations if it is installed,
+    the default is False
+    Valid values: False,True
+"""
+
+
+def use_numba_cb(key) -> None:
+    from pandas.core.util import numba_
+
+    numba_.set_use_numba(cf.get_option(key))
+
+
+with cf.config_prefix("compute"):
+    cf.register_option(
+        "use_bottleneck",
+        True,
+        use_bottleneck_doc,
+        validator=is_bool,
+        cb=use_bottleneck_cb,
+    )
+    cf.register_option(
+        "use_numexpr", True, use_numexpr_doc, validator=is_bool, cb=use_numexpr_cb
+    )
+    cf.register_option(
+        "use_numba", False, use_numba_doc, validator=is_bool, cb=use_numba_cb
+    )
+#
+# options from the "display" namespace
+
+pc_precision_doc = """
+: int
+    Floating point output precision in terms of number of places after the
+    decimal, for regular formatting as well as scientific notation. Similar
+    to ``precision`` in :meth:`numpy.set_printoptions`.
+"""
+
+pc_colspace_doc = """
+: int
+    Default space for DataFrame columns.
+"""
+
+pc_max_rows_doc = """
+: int
+    If max_rows is exceeded, switch to truncate view. Depending on
+    `large_repr`, objects are either centrally truncated or printed as
+    a summary view. 'None' value means unlimited.
+
+    In case python/IPython is running in a terminal and `large_repr`
+    equals 'truncate' this can be set to 0 and pandas will auto-detect
+    the height of the terminal and print a truncated object which fits
+    the screen height. The IPython notebook, IPython qtconsole, or
+    IDLE do not run in a terminal and hence it is not possible to do
+    correct auto-detection.
+"""
+
+pc_min_rows_doc = """
+: int
+    The numbers of rows to show in a truncated view (when `max_rows` is
+    exceeded). Ignored when `max_rows` is set to None or 0. When set to
+    None, follows the value of `max_rows`.
+"""
+
+pc_max_cols_doc = """
+: int
+    If max_cols is exceeded, switch to truncate view. Depending on
+    `large_repr`, objects are either centrally truncated or printed as
+    a summary view. 'None' value means unlimited.
+
+    In case python/IPython is running in a terminal and `large_repr`
+    equals 'truncate' this can be set to 0 or None and pandas will auto-detect
+    the width of the terminal and print a truncated object which fits
+    the screen width. The IPython notebook, IPython qtconsole, or IDLE
+    do not run in a terminal and hence it is not possible to do
+    correct auto-detection and defaults to 20.
+"""
+
+pc_max_categories_doc = """
+: int
+    This sets the maximum number of categories pandas should output when
+    printing out a `Categorical` or a Series of dtype "category".
+"""
+
+pc_max_info_cols_doc = """
+: int
+    max_info_columns is used in DataFrame.info method to decide if
+    per column information will be printed.
+"""
+
+pc_nb_repr_h_doc = """
+: boolean
+    When True, IPython notebook will use html representation for
+    pandas objects (if it is available).
+"""
+
+pc_pprint_nest_depth = """
+: int
+    Controls the number of nested levels to process when pretty-printing
+"""
+
+pc_multi_sparse_doc = """
+: boolean
+    "sparsify" MultiIndex display (don't display repeated
+    elements in outer levels within groups)
+"""
+
+float_format_doc = """
+: callable
+    The callable should accept a floating point number and return
+    a string with the desired format of the number. This is used
+    in some places like SeriesFormatter.
+    See formats.format.EngFormatter for an example.
+"""
+
+max_colwidth_doc = """
+: int or None
+    The maximum width in characters of a column in the repr of
+    a pandas data structure. When the column overflows, a "..."
+    placeholder is embedded in the output. A 'None' value means unlimited.
+"""
+
+colheader_justify_doc = """
+: 'left'/'right'
+    Controls the justification of column headers. used by DataFrameFormatter.
+"""
+
+pc_expand_repr_doc = """
+: boolean
+    Whether to print out the full DataFrame repr for wide DataFrames across
+    multiple lines, `max_columns` is still respected, but the output will
+    wrap-around across multiple "pages" if its width exceeds `display.width`.
+"""
+
+pc_show_dimensions_doc = """
+: boolean or 'truncate'
+    Whether to print out dimensions at the end of DataFrame repr.
+    If 'truncate' is specified, only print out the dimensions if the
+    frame is truncated (e.g. not display all rows and/or columns)
+"""
+
+pc_east_asian_width_doc = """
+: boolean
+    Whether to use the Unicode East Asian Width to calculate the display text
+    width.
+    Enabling this may affect to the performance (default: False)
+"""
+
+pc_ambiguous_as_wide_doc = """
+: boolean
+    Whether to handle Unicode characters belong to Ambiguous as Wide (width=2)
+    (default: False)
+"""
+
+pc_table_schema_doc = """
+: boolean
+    Whether to publish a Table Schema representation for frontends
+    that support it.
+    (default: False)
+"""
+
+pc_html_border_doc = """
+: int
+    A ``border=value`` attribute is inserted in the ```` tag
+    for the DataFrame HTML repr.
+"""
+
+pc_html_use_mathjax_doc = """\
+: boolean
+    When True, Jupyter notebook will process table contents using MathJax,
+    rendering mathematical expressions enclosed by the dollar symbol.
+    (default: True)
+"""
+
+pc_max_dir_items = """\
+: int
+    The number of items that will be added to `dir(...)`. 'None' value means
+    unlimited. Because dir is cached, changing this option will not immediately
+    affect already existing dataframes until a column is deleted or added.
+
+    This is for instance used to suggest columns from a dataframe to tab
+    completion.
+"""
+
+pc_width_doc = """
+: int
+    Width of the display in characters. In case python/IPython is running in
+    a terminal this can be set to None and pandas will correctly auto-detect
+    the width.
+    Note that the IPython notebook, IPython qtconsole, or IDLE do not run in a
+    terminal and hence it is not possible to correctly detect the width.
+"""
+
+pc_chop_threshold_doc = """
+: float or None
+    if set to a float value, all float values smaller than the given threshold
+    will be displayed as exactly 0 by repr and friends.
+"""
+
+pc_max_seq_items = """
+: int or None
+    When pretty-printing a long sequence, no more then `max_seq_items`
+    will be printed. If items are omitted, they will be denoted by the
+    addition of "..." to the resulting string.
+
+    If set to None, the number of items to be printed is unlimited.
+"""
+
+pc_max_info_rows_doc = """
+: int
+    df.info() will usually show null-counts for each column.
+    For large frames this can be quite slow. max_info_rows and max_info_cols
+    limit this null check only to frames with smaller dimensions than
+    specified.
+"""
+
+pc_large_repr_doc = """
+: 'truncate'/'info'
+    For DataFrames exceeding max_rows/max_cols, the repr (and HTML repr) can
+    show a truncated table, or switch to the view from
+    df.info() (the behaviour in earlier versions of pandas).
+"""
+
+pc_memory_usage_doc = """
+: bool, string or None
+    This specifies if the memory usage of a DataFrame should be displayed when
+    df.info() is called. Valid values True,False,'deep'
+"""
+
+
+def table_schema_cb(key) -> None:
+    from pandas.io.formats.printing import enable_data_resource_formatter
+
+    enable_data_resource_formatter(cf.get_option(key))
+
+
+def is_terminal() -> bool:
+    """
+    Detect if Python is running in a terminal.
+
+    Returns True if Python is running in a terminal or False if not.
+    """
+    try:
+        # error: Name 'get_ipython' is not defined
+        ip = get_ipython()  # type: ignore[name-defined]
+    except NameError:  # assume standard Python interpreter in a terminal
+        return True
+    else:
+        if hasattr(ip, "kernel"):  # IPython as a Jupyter kernel
+            return False
+        else:  # IPython in a terminal
+            return True
+
+
+with cf.config_prefix("display"):
+    cf.register_option("precision", 6, pc_precision_doc, validator=is_nonnegative_int)
+    cf.register_option(
+        "float_format",
+        None,
+        float_format_doc,
+        validator=is_one_of_factory([None, is_callable]),
+    )
+    cf.register_option(
+        "max_info_rows",
+        1690785,
+        pc_max_info_rows_doc,
+        validator=is_int,
+    )
+    cf.register_option("max_rows", 60, pc_max_rows_doc, validator=is_nonnegative_int)
+    cf.register_option(
+        "min_rows",
+        10,
+        pc_min_rows_doc,
+        validator=is_instance_factory([type(None), int]),
+    )
+    cf.register_option("max_categories", 8, pc_max_categories_doc, validator=is_int)
+
+    cf.register_option(
+        "max_colwidth",
+        50,
+        max_colwidth_doc,
+        validator=is_nonnegative_int,
+    )
+    if is_terminal():
+        max_cols = 0  # automatically determine optimal number of columns
+    else:
+        max_cols = 20  # cannot determine optimal number of columns
+    cf.register_option(
+        "max_columns", max_cols, pc_max_cols_doc, validator=is_nonnegative_int
+    )
+    cf.register_option(
+        "large_repr",
+        "truncate",
+        pc_large_repr_doc,
+        validator=is_one_of_factory(["truncate", "info"]),
+    )
+    cf.register_option("max_info_columns", 100, pc_max_info_cols_doc, validator=is_int)
+    cf.register_option(
+        "colheader_justify", "right", colheader_justify_doc, validator=is_text
+    )
+    cf.register_option("notebook_repr_html", True, pc_nb_repr_h_doc, validator=is_bool)
+    cf.register_option("pprint_nest_depth", 3, pc_pprint_nest_depth, validator=is_int)
+    cf.register_option("multi_sparse", True, pc_multi_sparse_doc, validator=is_bool)
+    cf.register_option("expand_frame_repr", True, pc_expand_repr_doc)
+    cf.register_option(
+        "show_dimensions",
+        "truncate",
+        pc_show_dimensions_doc,
+        validator=is_one_of_factory([True, False, "truncate"]),
+    )
+    cf.register_option("chop_threshold", None, pc_chop_threshold_doc)
+    cf.register_option("max_seq_items", 100, pc_max_seq_items)
+    cf.register_option(
+        "width", 80, pc_width_doc, validator=is_instance_factory([type(None), int])
+    )
+    cf.register_option(
+        "memory_usage",
+        True,
+        pc_memory_usage_doc,
+        validator=is_one_of_factory([None, True, False, "deep"]),
+    )
+    cf.register_option(
+        "unicode.east_asian_width", False, pc_east_asian_width_doc, validator=is_bool
+    )
+    cf.register_option(
+        "unicode.ambiguous_as_wide", False, pc_east_asian_width_doc, validator=is_bool
+    )
+    cf.register_option(
+        "html.table_schema",
+        False,
+        pc_table_schema_doc,
+        validator=is_bool,
+        cb=table_schema_cb,
+    )
+    cf.register_option("html.border", 1, pc_html_border_doc, validator=is_int)
+    cf.register_option(
+        "html.use_mathjax", True, pc_html_use_mathjax_doc, validator=is_bool
+    )
+    cf.register_option(
+        "max_dir_items", 100, pc_max_dir_items, validator=is_nonnegative_int
+    )
+
+tc_sim_interactive_doc = """
+: boolean
+    Whether to simulate interactive mode for purposes of testing
+"""
+
+with cf.config_prefix("mode"):
+    cf.register_option("sim_interactive", False, tc_sim_interactive_doc)
+
+use_inf_as_na_doc = """
+: boolean
+    True means treat None, NaN, INF, -INF as NA (old way),
+    False means None and NaN are null, but INF, -INF are not NA
+    (new way).
+
+    This option is deprecated in pandas 2.1.0 and will be removed in 3.0.
+"""
+
+# We don't want to start importing everything at the global context level
+# or we'll hit circular deps.
+
+
+def use_inf_as_na_cb(key) -> None:
+    # TODO(3.0): enforcing this deprecation will close GH#52501
+    from pandas.core.dtypes.missing import _use_inf_as_na
+
+    _use_inf_as_na(key)
+
+
+with cf.config_prefix("mode"):
+    cf.register_option("use_inf_as_na", False, use_inf_as_na_doc, cb=use_inf_as_na_cb)
+
+cf.deprecate_option(
+    # GH#51684
+    "mode.use_inf_as_na",
+    "use_inf_as_na option is deprecated and will be removed in a future "
+    "version. Convert inf values to NaN before operating instead.",
+)
+
+data_manager_doc = """
+: string
+    Internal data manager type; can be "block" or "array". Defaults to "block",
+    unless overridden by the 'PANDAS_DATA_MANAGER' environment variable (needs
+    to be set before pandas is imported).
+"""
+
+
+with cf.config_prefix("mode"):
+    cf.register_option(
+        "data_manager",
+        # Get the default from an environment variable, if set, otherwise defaults
+        # to "block". This environment variable can be set for testing.
+        os.environ.get("PANDAS_DATA_MANAGER", "block"),
+        data_manager_doc,
+        validator=is_one_of_factory(["block", "array"]),
+    )
+
+cf.deprecate_option(
+    # GH#55043
+    "mode.data_manager",
+    "data_manager option is deprecated and will be removed in a future "
+    "version. Only the BlockManager will be available.",
+)
+
+
+# TODO better name?
+copy_on_write_doc = """
+: bool
+    Use new copy-view behaviour using Copy-on-Write. Defaults to False,
+    unless overridden by the 'PANDAS_COPY_ON_WRITE' environment variable
+    (if set to "1" for True, needs to be set before pandas is imported).
+"""
+
+
+with cf.config_prefix("mode"):
+    cf.register_option(
+        "copy_on_write",
+        # Get the default from an environment variable, if set, otherwise defaults
+        # to False. This environment variable can be set for testing.
+        "warn"
+        if os.environ.get("PANDAS_COPY_ON_WRITE", "0") == "warn"
+        else os.environ.get("PANDAS_COPY_ON_WRITE", "0") == "1",
+        copy_on_write_doc,
+        validator=is_one_of_factory([True, False, "warn"]),
+    )
+
+
+# user warnings
+chained_assignment = """
+: string
+    Raise an exception, warn, or no action if trying to use chained assignment,
+    The default is warn
+"""
+
+with cf.config_prefix("mode"):
+    cf.register_option(
+        "chained_assignment",
+        "warn",
+        chained_assignment,
+        validator=is_one_of_factory([None, "warn", "raise"]),
+    )
+
+
+string_storage_doc = """
+: string
+    The default storage for StringDtype.
+"""
+
+
+def is_valid_string_storage(value: Any) -> None:
+    legal_values = ["auto", "python", "pyarrow"]
+    if value not in legal_values:
+        msg = "Value must be one of python|pyarrow"
+        if value == "pyarrow_numpy":
+            # TODO: we can remove extra message after 3.0
+            msg += (
+                ". 'pyarrow_numpy' was specified, but this option should be "
+                "enabled using pandas.options.future.infer_string instead"
+            )
+        raise ValueError(msg)
+
+
+with cf.config_prefix("mode"):
+    cf.register_option(
+        "string_storage",
+        "auto",
+        string_storage_doc,
+        # validator=is_one_of_factory(["python", "pyarrow"]),
+        validator=is_valid_string_storage,
+    )
+
+
+# Set up the io.excel specific reader configuration.
+reader_engine_doc = """
+: string
+    The default Excel reader engine for '{ext}' files. Available options:
+    auto, {others}.
+"""
+
+_xls_options = ["xlrd", "calamine"]
+_xlsm_options = ["xlrd", "openpyxl", "calamine"]
+_xlsx_options = ["xlrd", "openpyxl", "calamine"]
+_ods_options = ["odf", "calamine"]
+_xlsb_options = ["pyxlsb", "calamine"]
+
+
+with cf.config_prefix("io.excel.xls"):
+    cf.register_option(
+        "reader",
+        "auto",
+        reader_engine_doc.format(ext="xls", others=", ".join(_xls_options)),
+        validator=is_one_of_factory(_xls_options + ["auto"]),
+    )
+
+with cf.config_prefix("io.excel.xlsm"):
+    cf.register_option(
+        "reader",
+        "auto",
+        reader_engine_doc.format(ext="xlsm", others=", ".join(_xlsm_options)),
+        validator=is_one_of_factory(_xlsm_options + ["auto"]),
+    )
+
+
+with cf.config_prefix("io.excel.xlsx"):
+    cf.register_option(
+        "reader",
+        "auto",
+        reader_engine_doc.format(ext="xlsx", others=", ".join(_xlsx_options)),
+        validator=is_one_of_factory(_xlsx_options + ["auto"]),
+    )
+
+
+with cf.config_prefix("io.excel.ods"):
+    cf.register_option(
+        "reader",
+        "auto",
+        reader_engine_doc.format(ext="ods", others=", ".join(_ods_options)),
+        validator=is_one_of_factory(_ods_options + ["auto"]),
+    )
+
+with cf.config_prefix("io.excel.xlsb"):
+    cf.register_option(
+        "reader",
+        "auto",
+        reader_engine_doc.format(ext="xlsb", others=", ".join(_xlsb_options)),
+        validator=is_one_of_factory(_xlsb_options + ["auto"]),
+    )
+
+# Set up the io.excel specific writer configuration.
+writer_engine_doc = """
+: string
+    The default Excel writer engine for '{ext}' files. Available options:
+    auto, {others}.
+"""
+
+_xlsm_options = ["openpyxl"]
+_xlsx_options = ["openpyxl", "xlsxwriter"]
+_ods_options = ["odf"]
+
+
+with cf.config_prefix("io.excel.xlsm"):
+    cf.register_option(
+        "writer",
+        "auto",
+        writer_engine_doc.format(ext="xlsm", others=", ".join(_xlsm_options)),
+        validator=str,
+    )
+
+
+with cf.config_prefix("io.excel.xlsx"):
+    cf.register_option(
+        "writer",
+        "auto",
+        writer_engine_doc.format(ext="xlsx", others=", ".join(_xlsx_options)),
+        validator=str,
+    )
+
+
+with cf.config_prefix("io.excel.ods"):
+    cf.register_option(
+        "writer",
+        "auto",
+        writer_engine_doc.format(ext="ods", others=", ".join(_ods_options)),
+        validator=str,
+    )
+
+
+# Set up the io.parquet specific configuration.
+parquet_engine_doc = """
+: string
+    The default parquet reader/writer engine. Available options:
+    'auto', 'pyarrow', 'fastparquet', the default is 'auto'
+"""
+
+with cf.config_prefix("io.parquet"):
+    cf.register_option(
+        "engine",
+        "auto",
+        parquet_engine_doc,
+        validator=is_one_of_factory(["auto", "pyarrow", "fastparquet"]),
+    )
+
+
+# Set up the io.sql specific configuration.
+sql_engine_doc = """
+: string
+    The default sql reader/writer engine. Available options:
+    'auto', 'sqlalchemy', the default is 'auto'
+"""
+
+with cf.config_prefix("io.sql"):
+    cf.register_option(
+        "engine",
+        "auto",
+        sql_engine_doc,
+        validator=is_one_of_factory(["auto", "sqlalchemy"]),
+    )
+
+# --------
+# Plotting
+# ---------
+
+plotting_backend_doc = """
+: str
+    The plotting backend to use. The default value is "matplotlib", the
+    backend provided with pandas. Other backends can be specified by
+    providing the name of the module that implements the backend.
+"""
+
+
+def register_plotting_backend_cb(key) -> None:
+    if key == "matplotlib":
+        # We defer matplotlib validation, since it's the default
+        return
+    from pandas.plotting._core import _get_plot_backend
+
+    _get_plot_backend(key)
+
+
+with cf.config_prefix("plotting"):
+    cf.register_option(
+        "backend",
+        defval="matplotlib",
+        doc=plotting_backend_doc,
+        validator=register_plotting_backend_cb,
+    )
+
+
+register_converter_doc = """
+: bool or 'auto'.
+    Whether to register converters with matplotlib's units registry for
+    dates, times, datetimes, and Periods. Toggling to False will remove
+    the converters, restoring any converters that pandas overwrote.
+"""
+
+
+def register_converter_cb(key) -> None:
+    from pandas.plotting import (
+        deregister_matplotlib_converters,
+        register_matplotlib_converters,
+    )
+
+    if cf.get_option(key):
+        register_matplotlib_converters()
+    else:
+        deregister_matplotlib_converters()
+
+
+with cf.config_prefix("plotting.matplotlib"):
+    cf.register_option(
+        "register_converters",
+        "auto",
+        register_converter_doc,
+        validator=is_one_of_factory(["auto", True, False]),
+        cb=register_converter_cb,
+    )
+
+# ------
+# Styler
+# ------
+
+styler_sparse_index_doc = """
+: bool
+    Whether to sparsify the display of a hierarchical index. Setting to False will
+    display each explicit level element in a hierarchical key for each row.
+"""
+
+styler_sparse_columns_doc = """
+: bool
+    Whether to sparsify the display of hierarchical columns. Setting to False will
+    display each explicit level element in a hierarchical key for each column.
+"""
+
+styler_render_repr = """
+: str
+    Determine which output to use in Jupyter Notebook in {"html", "latex"}.
+"""
+
+styler_max_elements = """
+: int
+    The maximum number of data-cell (", indent)
+
+        if self.fmt.header:
+            self._write_col_header(indent + self.indent_delta)
+
+        if self.show_row_idx_names:
+            self._write_row_header(indent + self.indent_delta)
+
+        self.write("", indent)
+
+    def _get_formatted_values(self) -> dict[int, list[str]]:
+        with option_context("display.max_colwidth", None):
+            fmt_values = {i: self.fmt.format_col(i) for i in range(self.ncols)}
+        return fmt_values
+
+    def _write_body(self, indent: int) -> None:
+        self.write("", indent)
+        fmt_values = self._get_formatted_values()
+
+        # write values
+        if self.fmt.index and isinstance(self.frame.index, MultiIndex):
+            self._write_hierarchical_rows(fmt_values, indent + self.indent_delta)
+        else:
+            self._write_regular_rows(fmt_values, indent + self.indent_delta)
+
+        self.write("", indent)
+
+    def _write_regular_rows(
+        self, fmt_values: Mapping[int, list[str]], indent: int
+    ) -> None:
+        is_truncated_horizontally = self.fmt.is_truncated_horizontally
+        is_truncated_vertically = self.fmt.is_truncated_vertically
+
+        nrows = len(self.fmt.tr_frame)
+
+        if self.fmt.index:
+            fmt = self.fmt._get_formatter("__index__")
+            if fmt is not None:
+                index_values = self.fmt.tr_frame.index.map(fmt)
+            else:
+                # only reached with non-Multi index
+                index_values = self.fmt.tr_frame.index._format_flat(include_name=False)
+
+        row: list[str] = []
+        for i in range(nrows):
+            if is_truncated_vertically and i == (self.fmt.tr_row_num):
+                str_sep_row = ["..."] * len(row)
+                self.write_tr(
+                    str_sep_row,
+                    indent,
+                    self.indent_delta,
+                    tags=None,
+                    nindex_levels=self.row_levels,
+                )
+
+            row = []
+            if self.fmt.index:
+                row.append(index_values[i])
+            # see gh-22579
+            # Column misalignment also occurs for
+            # a standard index when the columns index is named.
+            # Add blank cell before data cells.
+            elif self.show_col_idx_names:
+                row.append("")
+            row.extend(fmt_values[j][i] for j in range(self.ncols))
+
+            if is_truncated_horizontally:
+                dot_col_ix = self.fmt.tr_col_num + self.row_levels
+                row.insert(dot_col_ix, "...")
+            self.write_tr(
+                row, indent, self.indent_delta, tags=None, nindex_levels=self.row_levels
+            )
+
+    def _write_hierarchical_rows(
+        self, fmt_values: Mapping[int, list[str]], indent: int
+    ) -> None:
+        template = 'rowspan="{span}" valign="top"'
+
+        is_truncated_horizontally = self.fmt.is_truncated_horizontally
+        is_truncated_vertically = self.fmt.is_truncated_vertically
+        frame = self.fmt.tr_frame
+        nrows = len(frame)
+
+        assert isinstance(frame.index, MultiIndex)
+        idx_values = frame.index._format_multi(sparsify=False, include_names=False)
+        idx_values = list(zip(*idx_values))
+
+        if self.fmt.sparsify:
+            # GH3547
+            sentinel = lib.no_default
+            levels = frame.index._format_multi(sparsify=sentinel, include_names=False)
+
+            level_lengths = get_level_lengths(levels, sentinel)
+            inner_lvl = len(level_lengths) - 1
+            if is_truncated_vertically:
+                # Insert ... row and adjust idx_values and
+                # level_lengths to take this into account.
+                ins_row = self.fmt.tr_row_num
+                inserted = False
+                for lnum, records in enumerate(level_lengths):
+                    rec_new = {}
+                    for tag, span in list(records.items()):
+                        if tag >= ins_row:
+                            rec_new[tag + 1] = span
+                        elif tag + span > ins_row:
+                            rec_new[tag] = span + 1
+
+                            # GH 14882 - Make sure insertion done once
+                            if not inserted:
+                                dot_row = list(idx_values[ins_row - 1])
+                                dot_row[-1] = "..."
+                                idx_values.insert(ins_row, tuple(dot_row))
+                                inserted = True
+                            else:
+                                dot_row = list(idx_values[ins_row])
+                                dot_row[inner_lvl - lnum] = "..."
+                                idx_values[ins_row] = tuple(dot_row)
+                        else:
+                            rec_new[tag] = span
+                        # If ins_row lies between tags, all cols idx cols
+                        # receive ...
+                        if tag + span == ins_row:
+                            rec_new[ins_row] = 1
+                            if lnum == 0:
+                                idx_values.insert(
+                                    ins_row, tuple(["..."] * len(level_lengths))
+                                )
+
+                            # GH 14882 - Place ... in correct level
+                            elif inserted:
+                                dot_row = list(idx_values[ins_row])
+                                dot_row[inner_lvl - lnum] = "..."
+                                idx_values[ins_row] = tuple(dot_row)
+                    level_lengths[lnum] = rec_new
+
+                level_lengths[inner_lvl][ins_row] = 1
+                for ix_col in fmt_values:
+                    fmt_values[ix_col].insert(ins_row, "...")
+                nrows += 1
+
+            for i in range(nrows):
+                row = []
+                tags = {}
+
+                sparse_offset = 0
+                j = 0
+                for records, v in zip(level_lengths, idx_values[i]):
+                    if i in records:
+                        if records[i] > 1:
+                            tags[j] = template.format(span=records[i])
+                    else:
+                        sparse_offset += 1
+                        continue
+
+                    j += 1
+                    row.append(v)
+
+                row.extend(fmt_values[j][i] for j in range(self.ncols))
+                if is_truncated_horizontally:
+                    row.insert(
+                        self.row_levels - sparse_offset + self.fmt.tr_col_num, "..."
+                    )
+                self.write_tr(
+                    row,
+                    indent,
+                    self.indent_delta,
+                    tags=tags,
+                    nindex_levels=len(levels) - sparse_offset,
+                )
+        else:
+            row = []
+            for i in range(len(frame)):
+                if is_truncated_vertically and i == (self.fmt.tr_row_num):
+                    str_sep_row = ["..."] * len(row)
+                    self.write_tr(
+                        str_sep_row,
+                        indent,
+                        self.indent_delta,
+                        tags=None,
+                        nindex_levels=self.row_levels,
+                    )
+
+                idx_values = list(
+                    zip(*frame.index._format_multi(sparsify=False, include_names=False))
+                )
+                row = []
+                row.extend(idx_values[i])
+                row.extend(fmt_values[j][i] for j in range(self.ncols))
+                if is_truncated_horizontally:
+                    row.insert(self.row_levels + self.fmt.tr_col_num, "...")
+                self.write_tr(
+                    row,
+                    indent,
+                    self.indent_delta,
+                    tags=None,
+                    nindex_levels=frame.index.nlevels,
+                )
+
+
+class NotebookFormatter(HTMLFormatter):
+    """
+    Internal class for formatting output data in html for display in Jupyter
+    Notebooks. This class is intended for functionality specific to
+    DataFrame._repr_html_() and DataFrame.to_html(notebook=True)
+    """
+
+    def _get_formatted_values(self) -> dict[int, list[str]]:
+        return {i: self.fmt.format_col(i) for i in range(self.ncols)}
+
+    def _get_columns_formatted_values(self) -> list[str]:
+        # only reached with non-Multi Index
+        return self.columns._format_flat(include_name=False)
+
+    def write_style(self) -> None:
+        # We use the "scoped" attribute here so that the desired
+        # style properties for the data frame are not then applied
+        # throughout the entire notebook.
+        template_first = """\
+            """
+        template_select = """\
+                .dataframe %s {
+                    %s: %s;
+                }"""
+        element_props = [
+            ("tbody tr th:only-of-type", "vertical-align", "middle"),
+            ("tbody tr th", "vertical-align", "top"),
+        ]
+        if isinstance(self.columns, MultiIndex):
+            element_props.append(("thead tr th", "text-align", "left"))
+            if self.show_row_idx_names:
+                element_props.append(
+                    ("thead tr:last-of-type th", "text-align", "right")
+                )
+        else:
+            element_props.append(("thead th", "text-align", "right"))
+        template_mid = "\n\n".join(template_select % t for t in element_props)
+        template = dedent(f"{template_first}\n{template_mid}\n{template_last}")
+        self.write(template)
+
+    def render(self) -> list[str]:
+        self.write("
")
+        self.write_style()
+        super().render()
+        self.write("
")
+        return self.elements
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/info.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/info.py
new file mode 100644
index 0000000000000000000000000000000000000000..552affbd053f2bed3f4d5f678ddf8eb293f65b01
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/info.py
@@ -0,0 +1,1101 @@
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+import sys
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+from pandas._config import get_option
+
+from pandas.io.formats import format as fmt
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Iterator,
+        Mapping,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        Dtype,
+        WriteBuffer,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+
+
+frame_max_cols_sub = dedent(
+    """\
+    max_cols : int, optional
+        When to switch from the verbose to the truncated output. If the
+        DataFrame has more than `max_cols` columns, the truncated output
+        is used. By default, the setting in
+        ``pandas.options.display.max_info_columns`` is used."""
+)
+
+
+show_counts_sub = dedent(
+    """\
+    show_counts : bool, optional
+        Whether to show the non-null counts. By default, this is shown
+        only if the DataFrame is smaller than
+        ``pandas.options.display.max_info_rows`` and
+        ``pandas.options.display.max_info_columns``. A value of True always
+        shows the counts, and False never shows the counts."""
+)
+
+
+frame_examples_sub = dedent(
+    """\
+    >>> int_values = [1, 2, 3, 4, 5]
+    >>> text_values = ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+    >>> float_values = [0.0, 0.25, 0.5, 0.75, 1.0]
+    >>> df = pd.DataFrame({"int_col": int_values, "text_col": text_values,
+    ...                   "float_col": float_values})
+    >>> df
+        int_col text_col  float_col
+    0        1    alpha       0.00
+    1        2     beta       0.25
+    2        3    gamma       0.50
+    3        4    delta       0.75
+    4        5  epsilon       1.00
+
+    Prints information of all columns:
+
+    >>> df.info(verbose=True)
+    
+    RangeIndex: 5 entries, 0 to 4
+    Data columns (total 3 columns):
+     #   Column     Non-Null Count  Dtype
+    ---  ------     --------------  -----
+     0   int_col    5 non-null      int64
+     1   text_col   5 non-null      object
+     2   float_col  5 non-null      float64
+    dtypes: float64(1), int64(1), object(1)
+    memory usage: 248.0+ bytes
+
+    Prints a summary of columns count and its dtypes but not per column
+    information:
+
+    >>> df.info(verbose=False)
+    
+    RangeIndex: 5 entries, 0 to 4
+    Columns: 3 entries, int_col to float_col
+    dtypes: float64(1), int64(1), object(1)
+    memory usage: 248.0+ bytes
+
+    Pipe output of DataFrame.info to buffer instead of sys.stdout, get
+    buffer content and writes to a text file:
+
+    >>> import io
+    >>> buffer = io.StringIO()
+    >>> df.info(buf=buffer)
+    >>> s = buffer.getvalue()
+    >>> with open("df_info.txt", "w",
+    ...           encoding="utf-8") as f:  # doctest: +SKIP
+    ...     f.write(s)
+    260
+
+    The `memory_usage` parameter allows deep introspection mode, specially
+    useful for big DataFrames and fine-tune memory optimization:
+
+    >>> random_strings_array = np.random.choice(['a', 'b', 'c'], 10 ** 6)
+    >>> df = pd.DataFrame({
+    ...     'column_1': np.random.choice(['a', 'b', 'c'], 10 ** 6),
+    ...     'column_2': np.random.choice(['a', 'b', 'c'], 10 ** 6),
+    ...     'column_3': np.random.choice(['a', 'b', 'c'], 10 ** 6)
+    ... })
+    >>> df.info()
+    
+    RangeIndex: 1000000 entries, 0 to 999999
+    Data columns (total 3 columns):
+     #   Column    Non-Null Count    Dtype
+    ---  ------    --------------    -----
+     0   column_1  1000000 non-null  object
+     1   column_2  1000000 non-null  object
+     2   column_3  1000000 non-null  object
+    dtypes: object(3)
+    memory usage: 22.9+ MB
+
+    >>> df.info(memory_usage='deep')
+    
+    RangeIndex: 1000000 entries, 0 to 999999
+    Data columns (total 3 columns):
+     #   Column    Non-Null Count    Dtype
+    ---  ------    --------------    -----
+     0   column_1  1000000 non-null  object
+     1   column_2  1000000 non-null  object
+     2   column_3  1000000 non-null  object
+    dtypes: object(3)
+    memory usage: 165.9 MB"""
+)
+
+
+frame_see_also_sub = dedent(
+    """\
+    DataFrame.describe: Generate descriptive statistics of DataFrame
+        columns.
+    DataFrame.memory_usage: Memory usage of DataFrame columns."""
+)
+
+
+frame_sub_kwargs = {
+    "klass": "DataFrame",
+    "type_sub": " and columns",
+    "max_cols_sub": frame_max_cols_sub,
+    "show_counts_sub": show_counts_sub,
+    "examples_sub": frame_examples_sub,
+    "see_also_sub": frame_see_also_sub,
+    "version_added_sub": "",
+}
+
+
+series_examples_sub = dedent(
+    """\
+    >>> int_values = [1, 2, 3, 4, 5]
+    >>> text_values = ['alpha', 'beta', 'gamma', 'delta', 'epsilon']
+    >>> s = pd.Series(text_values, index=int_values)
+    >>> s.info()
+    
+    Index: 5 entries, 1 to 5
+    Series name: None
+    Non-Null Count  Dtype
+    --------------  -----
+    5 non-null      object
+    dtypes: object(1)
+    memory usage: 80.0+ bytes
+
+    Prints a summary excluding information about its values:
+
+    >>> s.info(verbose=False)
+    
+    Index: 5 entries, 1 to 5
+    dtypes: object(1)
+    memory usage: 80.0+ bytes
+
+    Pipe output of Series.info to buffer instead of sys.stdout, get
+    buffer content and writes to a text file:
+
+    >>> import io
+    >>> buffer = io.StringIO()
+    >>> s.info(buf=buffer)
+    >>> s = buffer.getvalue()
+    >>> with open("df_info.txt", "w",
+    ...           encoding="utf-8") as f:  # doctest: +SKIP
+    ...     f.write(s)
+    260
+
+    The `memory_usage` parameter allows deep introspection mode, specially
+    useful for big Series and fine-tune memory optimization:
+
+    >>> random_strings_array = np.random.choice(['a', 'b', 'c'], 10 ** 6)
+    >>> s = pd.Series(np.random.choice(['a', 'b', 'c'], 10 ** 6))
+    >>> s.info()
+    
+    RangeIndex: 1000000 entries, 0 to 999999
+    Series name: None
+    Non-Null Count    Dtype
+    --------------    -----
+    1000000 non-null  object
+    dtypes: object(1)
+    memory usage: 7.6+ MB
+
+    >>> s.info(memory_usage='deep')
+    
+    RangeIndex: 1000000 entries, 0 to 999999
+    Series name: None
+    Non-Null Count    Dtype
+    --------------    -----
+    1000000 non-null  object
+    dtypes: object(1)
+    memory usage: 55.3 MB"""
+)
+
+
+series_see_also_sub = dedent(
+    """\
+    Series.describe: Generate descriptive statistics of Series.
+    Series.memory_usage: Memory usage of Series."""
+)
+
+
+series_sub_kwargs = {
+    "klass": "Series",
+    "type_sub": "",
+    "max_cols_sub": "",
+    "show_counts_sub": show_counts_sub,
+    "examples_sub": series_examples_sub,
+    "see_also_sub": series_see_also_sub,
+    "version_added_sub": "\n.. versionadded:: 1.4.0\n",
+}
+
+
+INFO_DOCSTRING = dedent(
+    """
+    Print a concise summary of a {klass}.
+
+    This method prints information about a {klass} including
+    the index dtype{type_sub}, non-null values and memory usage.
+    {version_added_sub}\
+
+    Parameters
+    ----------
+    verbose : bool, optional
+        Whether to print the full summary. By default, the setting in
+        ``pandas.options.display.max_info_columns`` is followed.
+    buf : writable buffer, defaults to sys.stdout
+        Where to send the output. By default, the output is printed to
+        sys.stdout. Pass a writable buffer if you need to further process
+        the output.
+    {max_cols_sub}
+    memory_usage : bool, str, optional
+        Specifies whether total memory usage of the {klass}
+        elements (including the index) should be displayed. By default,
+        this follows the ``pandas.options.display.memory_usage`` setting.
+
+        True always show memory usage. False never shows memory usage.
+        A value of 'deep' is equivalent to "True with deep introspection".
+        Memory usage is shown in human-readable units (base-2
+        representation). Without deep introspection a memory estimation is
+        made based in column dtype and number of rows assuming values
+        consume the same memory amount for corresponding dtypes. With deep
+        memory introspection, a real memory usage calculation is performed
+        at the cost of computational resources. See the
+        :ref:`Frequently Asked Questions ` for more
+        details.
+    {show_counts_sub}
+
+    Returns
+    -------
+    None
+        This method prints a summary of a {klass} and returns None.
+
+    See Also
+    --------
+    {see_also_sub}
+
+    Examples
+    --------
+    {examples_sub}
+    """
+)
+
+
+def _put_str(s: str | Dtype, space: int) -> str:
+    """
+    Make string of specified length, padding to the right if necessary.
+
+    Parameters
+    ----------
+    s : Union[str, Dtype]
+        String to be formatted.
+    space : int
+        Length to force string to be of.
+
+    Returns
+    -------
+    str
+        String coerced to given length.
+
+    Examples
+    --------
+    >>> pd.io.formats.info._put_str("panda", 6)
+    'panda '
+    >>> pd.io.formats.info._put_str("panda", 4)
+    'pand'
+    """
+    return str(s)[:space].ljust(space)
+
+
+def _sizeof_fmt(num: float, size_qualifier: str) -> str:
+    """
+    Return size in human readable format.
+
+    Parameters
+    ----------
+    num : int
+        Size in bytes.
+    size_qualifier : str
+        Either empty, or '+' (if lower bound).
+
+    Returns
+    -------
+    str
+        Size in human readable format.
+
+    Examples
+    --------
+    >>> _sizeof_fmt(23028, '')
+    '22.5 KB'
+
+    >>> _sizeof_fmt(23028, '+')
+    '22.5+ KB'
+    """
+    for x in ["bytes", "KB", "MB", "GB", "TB"]:
+        if num < 1024.0:
+            return f"{num:3.1f}{size_qualifier} {x}"
+        num /= 1024.0
+    return f"{num:3.1f}{size_qualifier} PB"
+
+
+def _initialize_memory_usage(
+    memory_usage: bool | str | None = None,
+) -> bool | str:
+    """Get memory usage based on inputs and display options."""
+    if memory_usage is None:
+        memory_usage = get_option("display.memory_usage")
+    return memory_usage
+
+
+class _BaseInfo(ABC):
+    """
+    Base class for DataFrameInfo and SeriesInfo.
+
+    Parameters
+    ----------
+    data : DataFrame or Series
+        Either dataframe or series.
+    memory_usage : bool or str, optional
+        If "deep", introspect the data deeply by interrogating object dtypes
+        for system-level memory consumption, and include it in the returned
+        values.
+    """
+
+    data: DataFrame | Series
+    memory_usage: bool | str
+
+    @property
+    @abstractmethod
+    def dtypes(self) -> Iterable[Dtype]:
+        """
+        Dtypes.
+
+        Returns
+        -------
+        dtypes : sequence
+            Dtype of each of the DataFrame's columns (or one series column).
+        """
+
+    @property
+    @abstractmethod
+    def dtype_counts(self) -> Mapping[str, int]:
+        """Mapping dtype - number of counts."""
+
+    @property
+    @abstractmethod
+    def non_null_counts(self) -> Sequence[int]:
+        """Sequence of non-null counts for all columns or column (if series)."""
+
+    @property
+    @abstractmethod
+    def memory_usage_bytes(self) -> int:
+        """
+        Memory usage in bytes.
+
+        Returns
+        -------
+        memory_usage_bytes : int
+            Object's total memory usage in bytes.
+        """
+
+    @property
+    def memory_usage_string(self) -> str:
+        """Memory usage in a form of human readable string."""
+        return f"{_sizeof_fmt(self.memory_usage_bytes, self.size_qualifier)}\n"
+
+    @property
+    def size_qualifier(self) -> str:
+        size_qualifier = ""
+        if self.memory_usage:
+            if self.memory_usage != "deep":
+                # size_qualifier is just a best effort; not guaranteed to catch
+                # all cases (e.g., it misses categorical data even with object
+                # categories)
+                if (
+                    "object" in self.dtype_counts
+                    or self.data.index._is_memory_usage_qualified()
+                ):
+                    size_qualifier = "+"
+        return size_qualifier
+
+    @abstractmethod
+    def render(
+        self,
+        *,
+        buf: WriteBuffer[str] | None,
+        max_cols: int | None,
+        verbose: bool | None,
+        show_counts: bool | None,
+    ) -> None:
+        pass
+
+
+class DataFrameInfo(_BaseInfo):
+    """
+    Class storing dataframe-specific info.
+    """
+
+    def __init__(
+        self,
+        data: DataFrame,
+        memory_usage: bool | str | None = None,
+    ) -> None:
+        self.data: DataFrame = data
+        self.memory_usage = _initialize_memory_usage(memory_usage)
+
+    @property
+    def dtype_counts(self) -> Mapping[str, int]:
+        return _get_dataframe_dtype_counts(self.data)
+
+    @property
+    def dtypes(self) -> Iterable[Dtype]:
+        """
+        Dtypes.
+
+        Returns
+        -------
+        dtypes
+            Dtype of each of the DataFrame's columns.
+        """
+        return self.data.dtypes
+
+    @property
+    def ids(self) -> Index:
+        """
+        Column names.
+
+        Returns
+        -------
+        ids : Index
+            DataFrame's column names.
+        """
+        return self.data.columns
+
+    @property
+    def col_count(self) -> int:
+        """Number of columns to be summarized."""
+        return len(self.ids)
+
+    @property
+    def non_null_counts(self) -> Sequence[int]:
+        """Sequence of non-null counts for all columns or column (if series)."""
+        return self.data.count()
+
+    @property
+    def memory_usage_bytes(self) -> int:
+        deep = self.memory_usage == "deep"
+        return self.data.memory_usage(index=True, deep=deep).sum()
+
+    def render(
+        self,
+        *,
+        buf: WriteBuffer[str] | None,
+        max_cols: int | None,
+        verbose: bool | None,
+        show_counts: bool | None,
+    ) -> None:
+        printer = _DataFrameInfoPrinter(
+            info=self,
+            max_cols=max_cols,
+            verbose=verbose,
+            show_counts=show_counts,
+        )
+        printer.to_buffer(buf)
+
+
+class SeriesInfo(_BaseInfo):
+    """
+    Class storing series-specific info.
+    """
+
+    def __init__(
+        self,
+        data: Series,
+        memory_usage: bool | str | None = None,
+    ) -> None:
+        self.data: Series = data
+        self.memory_usage = _initialize_memory_usage(memory_usage)
+
+    def render(
+        self,
+        *,
+        buf: WriteBuffer[str] | None = None,
+        max_cols: int | None = None,
+        verbose: bool | None = None,
+        show_counts: bool | None = None,
+    ) -> None:
+        if max_cols is not None:
+            raise ValueError(
+                "Argument `max_cols` can only be passed "
+                "in DataFrame.info, not Series.info"
+            )
+        printer = _SeriesInfoPrinter(
+            info=self,
+            verbose=verbose,
+            show_counts=show_counts,
+        )
+        printer.to_buffer(buf)
+
+    @property
+    def non_null_counts(self) -> Sequence[int]:
+        return [self.data.count()]
+
+    @property
+    def dtypes(self) -> Iterable[Dtype]:
+        return [self.data.dtypes]
+
+    @property
+    def dtype_counts(self) -> Mapping[str, int]:
+        from pandas.core.frame import DataFrame
+
+        return _get_dataframe_dtype_counts(DataFrame(self.data))
+
+    @property
+    def memory_usage_bytes(self) -> int:
+        """Memory usage in bytes.
+
+        Returns
+        -------
+        memory_usage_bytes : int
+            Object's total memory usage in bytes.
+        """
+        deep = self.memory_usage == "deep"
+        return self.data.memory_usage(index=True, deep=deep)
+
+
+class _InfoPrinterAbstract:
+    """
+    Class for printing dataframe or series info.
+    """
+
+    def to_buffer(self, buf: WriteBuffer[str] | None = None) -> None:
+        """Save dataframe info into buffer."""
+        table_builder = self._create_table_builder()
+        lines = table_builder.get_lines()
+        if buf is None:  # pragma: no cover
+            buf = sys.stdout
+        fmt.buffer_put_lines(buf, lines)
+
+    @abstractmethod
+    def _create_table_builder(self) -> _TableBuilderAbstract:
+        """Create instance of table builder."""
+
+
+class _DataFrameInfoPrinter(_InfoPrinterAbstract):
+    """
+    Class for printing dataframe info.
+
+    Parameters
+    ----------
+    info : DataFrameInfo
+        Instance of DataFrameInfo.
+    max_cols : int, optional
+        When to switch from the verbose to the truncated output.
+    verbose : bool, optional
+        Whether to print the full summary.
+    show_counts : bool, optional
+        Whether to show the non-null counts.
+    """
+
+    def __init__(
+        self,
+        info: DataFrameInfo,
+        max_cols: int | None = None,
+        verbose: bool | None = None,
+        show_counts: bool | None = None,
+    ) -> None:
+        self.info = info
+        self.data = info.data
+        self.verbose = verbose
+        self.max_cols = self._initialize_max_cols(max_cols)
+        self.show_counts = self._initialize_show_counts(show_counts)
+
+    @property
+    def max_rows(self) -> int:
+        """Maximum info rows to be displayed."""
+        return get_option("display.max_info_rows", len(self.data) + 1)
+
+    @property
+    def exceeds_info_cols(self) -> bool:
+        """Check if number of columns to be summarized does not exceed maximum."""
+        return bool(self.col_count > self.max_cols)
+
+    @property
+    def exceeds_info_rows(self) -> bool:
+        """Check if number of rows to be summarized does not exceed maximum."""
+        return bool(len(self.data) > self.max_rows)
+
+    @property
+    def col_count(self) -> int:
+        """Number of columns to be summarized."""
+        return self.info.col_count
+
+    def _initialize_max_cols(self, max_cols: int | None) -> int:
+        if max_cols is None:
+            return get_option("display.max_info_columns", self.col_count + 1)
+        return max_cols
+
+    def _initialize_show_counts(self, show_counts: bool | None) -> bool:
+        if show_counts is None:
+            return bool(not self.exceeds_info_cols and not self.exceeds_info_rows)
+        else:
+            return show_counts
+
+    def _create_table_builder(self) -> _DataFrameTableBuilder:
+        """
+        Create instance of table builder based on verbosity and display settings.
+        """
+        if self.verbose:
+            return _DataFrameTableBuilderVerbose(
+                info=self.info,
+                with_counts=self.show_counts,
+            )
+        elif self.verbose is False:  # specifically set to False, not necessarily None
+            return _DataFrameTableBuilderNonVerbose(info=self.info)
+        elif self.exceeds_info_cols:
+            return _DataFrameTableBuilderNonVerbose(info=self.info)
+        else:
+            return _DataFrameTableBuilderVerbose(
+                info=self.info,
+                with_counts=self.show_counts,
+            )
+
+
+class _SeriesInfoPrinter(_InfoPrinterAbstract):
+    """Class for printing series info.
+
+    Parameters
+    ----------
+    info : SeriesInfo
+        Instance of SeriesInfo.
+    verbose : bool, optional
+        Whether to print the full summary.
+    show_counts : bool, optional
+        Whether to show the non-null counts.
+    """
+
+    def __init__(
+        self,
+        info: SeriesInfo,
+        verbose: bool | None = None,
+        show_counts: bool | None = None,
+    ) -> None:
+        self.info = info
+        self.data = info.data
+        self.verbose = verbose
+        self.show_counts = self._initialize_show_counts(show_counts)
+
+    def _create_table_builder(self) -> _SeriesTableBuilder:
+        """
+        Create instance of table builder based on verbosity.
+        """
+        if self.verbose or self.verbose is None:
+            return _SeriesTableBuilderVerbose(
+                info=self.info,
+                with_counts=self.show_counts,
+            )
+        else:
+            return _SeriesTableBuilderNonVerbose(info=self.info)
+
+    def _initialize_show_counts(self, show_counts: bool | None) -> bool:
+        if show_counts is None:
+            return True
+        else:
+            return show_counts
+
+
+class _TableBuilderAbstract(ABC):
+    """
+    Abstract builder for info table.
+    """
+
+    _lines: list[str]
+    info: _BaseInfo
+
+    @abstractmethod
+    def get_lines(self) -> list[str]:
+        """Product in a form of list of lines (strings)."""
+
+    @property
+    def data(self) -> DataFrame | Series:
+        return self.info.data
+
+    @property
+    def dtypes(self) -> Iterable[Dtype]:
+        """Dtypes of each of the DataFrame's columns."""
+        return self.info.dtypes
+
+    @property
+    def dtype_counts(self) -> Mapping[str, int]:
+        """Mapping dtype - number of counts."""
+        return self.info.dtype_counts
+
+    @property
+    def display_memory_usage(self) -> bool:
+        """Whether to display memory usage."""
+        return bool(self.info.memory_usage)
+
+    @property
+    def memory_usage_string(self) -> str:
+        """Memory usage string with proper size qualifier."""
+        return self.info.memory_usage_string
+
+    @property
+    def non_null_counts(self) -> Sequence[int]:
+        return self.info.non_null_counts
+
+    def add_object_type_line(self) -> None:
+        """Add line with string representation of dataframe to the table."""
+        self._lines.append(str(type(self.data)))
+
+    def add_index_range_line(self) -> None:
+        """Add line with range of indices to the table."""
+        self._lines.append(self.data.index._summary())
+
+    def add_dtypes_line(self) -> None:
+        """Add summary line with dtypes present in dataframe."""
+        collected_dtypes = [
+            f"{key}({val:d})" for key, val in sorted(self.dtype_counts.items())
+        ]
+        self._lines.append(f"dtypes: {', '.join(collected_dtypes)}")
+
+
+class _DataFrameTableBuilder(_TableBuilderAbstract):
+    """
+    Abstract builder for dataframe info table.
+
+    Parameters
+    ----------
+    info : DataFrameInfo.
+        Instance of DataFrameInfo.
+    """
+
+    def __init__(self, *, info: DataFrameInfo) -> None:
+        self.info: DataFrameInfo = info
+
+    def get_lines(self) -> list[str]:
+        self._lines = []
+        if self.col_count == 0:
+            self._fill_empty_info()
+        else:
+            self._fill_non_empty_info()
+        return self._lines
+
+    def _fill_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to empty dataframe."""
+        self.add_object_type_line()
+        self.add_index_range_line()
+        self._lines.append(f"Empty {type(self.data).__name__}\n")
+
+    @abstractmethod
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty dataframe."""
+
+    @property
+    def data(self) -> DataFrame:
+        """DataFrame."""
+        return self.info.data
+
+    @property
+    def ids(self) -> Index:
+        """Dataframe columns."""
+        return self.info.ids
+
+    @property
+    def col_count(self) -> int:
+        """Number of dataframe columns to be summarized."""
+        return self.info.col_count
+
+    def add_memory_usage_line(self) -> None:
+        """Add line containing memory usage."""
+        self._lines.append(f"memory usage: {self.memory_usage_string}")
+
+
+class _DataFrameTableBuilderNonVerbose(_DataFrameTableBuilder):
+    """
+    Dataframe info table builder for non-verbose output.
+    """
+
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty dataframe."""
+        self.add_object_type_line()
+        self.add_index_range_line()
+        self.add_columns_summary_line()
+        self.add_dtypes_line()
+        if self.display_memory_usage:
+            self.add_memory_usage_line()
+
+    def add_columns_summary_line(self) -> None:
+        self._lines.append(self.ids._summary(name="Columns"))
+
+
+class _TableBuilderVerboseMixin(_TableBuilderAbstract):
+    """
+    Mixin for verbose info output.
+    """
+
+    SPACING: str = " " * 2
+    strrows: Sequence[Sequence[str]]
+    gross_column_widths: Sequence[int]
+    with_counts: bool
+
+    @property
+    @abstractmethod
+    def headers(self) -> Sequence[str]:
+        """Headers names of the columns in verbose table."""
+
+    @property
+    def header_column_widths(self) -> Sequence[int]:
+        """Widths of header columns (only titles)."""
+        return [len(col) for col in self.headers]
+
+    def _get_gross_column_widths(self) -> Sequence[int]:
+        """Get widths of columns containing both headers and actual content."""
+        body_column_widths = self._get_body_column_widths()
+        return [
+            max(*widths)
+            for widths in zip(self.header_column_widths, body_column_widths)
+        ]
+
+    def _get_body_column_widths(self) -> Sequence[int]:
+        """Get widths of table content columns."""
+        strcols: Sequence[Sequence[str]] = list(zip(*self.strrows))
+        return [max(len(x) for x in col) for col in strcols]
+
+    def _gen_rows(self) -> Iterator[Sequence[str]]:
+        """
+        Generator function yielding rows content.
+
+        Each element represents a row comprising a sequence of strings.
+        """
+        if self.with_counts:
+            return self._gen_rows_with_counts()
+        else:
+            return self._gen_rows_without_counts()
+
+    @abstractmethod
+    def _gen_rows_with_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data with counts."""
+
+    @abstractmethod
+    def _gen_rows_without_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data without counts."""
+
+    def add_header_line(self) -> None:
+        header_line = self.SPACING.join(
+            [
+                _put_str(header, col_width)
+                for header, col_width in zip(self.headers, self.gross_column_widths)
+            ]
+        )
+        self._lines.append(header_line)
+
+    def add_separator_line(self) -> None:
+        separator_line = self.SPACING.join(
+            [
+                _put_str("-" * header_colwidth, gross_colwidth)
+                for header_colwidth, gross_colwidth in zip(
+                    self.header_column_widths, self.gross_column_widths
+                )
+            ]
+        )
+        self._lines.append(separator_line)
+
+    def add_body_lines(self) -> None:
+        for row in self.strrows:
+            body_line = self.SPACING.join(
+                [
+                    _put_str(col, gross_colwidth)
+                    for col, gross_colwidth in zip(row, self.gross_column_widths)
+                ]
+            )
+            self._lines.append(body_line)
+
+    def _gen_non_null_counts(self) -> Iterator[str]:
+        """Iterator with string representation of non-null counts."""
+        for count in self.non_null_counts:
+            yield f"{count} non-null"
+
+    def _gen_dtypes(self) -> Iterator[str]:
+        """Iterator with string representation of column dtypes."""
+        for dtype in self.dtypes:
+            yield pprint_thing(dtype)
+
+
+class _DataFrameTableBuilderVerbose(_DataFrameTableBuilder, _TableBuilderVerboseMixin):
+    """
+    Dataframe info table builder for verbose output.
+    """
+
+    def __init__(
+        self,
+        *,
+        info: DataFrameInfo,
+        with_counts: bool,
+    ) -> None:
+        self.info = info
+        self.with_counts = with_counts
+        self.strrows: Sequence[Sequence[str]] = list(self._gen_rows())
+        self.gross_column_widths: Sequence[int] = self._get_gross_column_widths()
+
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty dataframe."""
+        self.add_object_type_line()
+        self.add_index_range_line()
+        self.add_columns_summary_line()
+        self.add_header_line()
+        self.add_separator_line()
+        self.add_body_lines()
+        self.add_dtypes_line()
+        if self.display_memory_usage:
+            self.add_memory_usage_line()
+
+    @property
+    def headers(self) -> Sequence[str]:
+        """Headers names of the columns in verbose table."""
+        if self.with_counts:
+            return [" # ", "Column", "Non-Null Count", "Dtype"]
+        return [" # ", "Column", "Dtype"]
+
+    def add_columns_summary_line(self) -> None:
+        self._lines.append(f"Data columns (total {self.col_count} columns):")
+
+    def _gen_rows_without_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data without counts."""
+        yield from zip(
+            self._gen_line_numbers(),
+            self._gen_columns(),
+            self._gen_dtypes(),
+        )
+
+    def _gen_rows_with_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data with counts."""
+        yield from zip(
+            self._gen_line_numbers(),
+            self._gen_columns(),
+            self._gen_non_null_counts(),
+            self._gen_dtypes(),
+        )
+
+    def _gen_line_numbers(self) -> Iterator[str]:
+        """Iterator with string representation of column numbers."""
+        for i, _ in enumerate(self.ids):
+            yield f" {i}"
+
+    def _gen_columns(self) -> Iterator[str]:
+        """Iterator with string representation of column names."""
+        for col in self.ids:
+            yield pprint_thing(col)
+
+
+class _SeriesTableBuilder(_TableBuilderAbstract):
+    """
+    Abstract builder for series info table.
+
+    Parameters
+    ----------
+    info : SeriesInfo.
+        Instance of SeriesInfo.
+    """
+
+    def __init__(self, *, info: SeriesInfo) -> None:
+        self.info: SeriesInfo = info
+
+    def get_lines(self) -> list[str]:
+        self._lines = []
+        self._fill_non_empty_info()
+        return self._lines
+
+    @property
+    def data(self) -> Series:
+        """Series."""
+        return self.info.data
+
+    def add_memory_usage_line(self) -> None:
+        """Add line containing memory usage."""
+        self._lines.append(f"memory usage: {self.memory_usage_string}")
+
+    @abstractmethod
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty series."""
+
+
+class _SeriesTableBuilderNonVerbose(_SeriesTableBuilder):
+    """
+    Series info table builder for non-verbose output.
+    """
+
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty series."""
+        self.add_object_type_line()
+        self.add_index_range_line()
+        self.add_dtypes_line()
+        if self.display_memory_usage:
+            self.add_memory_usage_line()
+
+
+class _SeriesTableBuilderVerbose(_SeriesTableBuilder, _TableBuilderVerboseMixin):
+    """
+    Series info table builder for verbose output.
+    """
+
+    def __init__(
+        self,
+        *,
+        info: SeriesInfo,
+        with_counts: bool,
+    ) -> None:
+        self.info = info
+        self.with_counts = with_counts
+        self.strrows: Sequence[Sequence[str]] = list(self._gen_rows())
+        self.gross_column_widths: Sequence[int] = self._get_gross_column_widths()
+
+    def _fill_non_empty_info(self) -> None:
+        """Add lines to the info table, pertaining to non-empty series."""
+        self.add_object_type_line()
+        self.add_index_range_line()
+        self.add_series_name_line()
+        self.add_header_line()
+        self.add_separator_line()
+        self.add_body_lines()
+        self.add_dtypes_line()
+        if self.display_memory_usage:
+            self.add_memory_usage_line()
+
+    def add_series_name_line(self) -> None:
+        self._lines.append(f"Series name: {self.data.name}")
+
+    @property
+    def headers(self) -> Sequence[str]:
+        """Headers names of the columns in verbose table."""
+        if self.with_counts:
+            return ["Non-Null Count", "Dtype"]
+        return ["Dtype"]
+
+    def _gen_rows_without_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data without counts."""
+        yield from self._gen_dtypes()
+
+    def _gen_rows_with_counts(self) -> Iterator[Sequence[str]]:
+        """Iterator with string representation of body data with counts."""
+        yield from zip(
+            self._gen_non_null_counts(),
+            self._gen_dtypes(),
+        )
+
+
+def _get_dataframe_dtype_counts(df: DataFrame) -> Mapping[str, int]:
+    """
+    Create mapping between datatypes and their number of occurrences.
+    """
+    # groupby dtype.name to collect e.g. Categorical columns
+    return df.dtypes.value_counts().groupby(lambda x: x.name).sum()
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/printing.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/printing.py
new file mode 100644
index 0000000000000000000000000000000000000000..2cc9368f8846a6423655040673df283d111efeda
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/printing.py
@@ -0,0 +1,572 @@
+"""
+Printing tools.
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Iterable,
+    Mapping,
+    Sequence,
+)
+import sys
+from typing import (
+    Any,
+    Callable,
+    TypeVar,
+    Union,
+)
+from unicodedata import east_asian_width
+
+from pandas._config import get_option
+
+from pandas.core.dtypes.inference import is_sequence
+
+from pandas.io.formats.console import get_console_size
+
+EscapeChars = Union[Mapping[str, str], Iterable[str]]
+_KT = TypeVar("_KT")
+_VT = TypeVar("_VT")
+
+
+def adjoin(space: int, *lists: list[str], **kwargs) -> str:
+    """
+    Glues together two sets of strings using the amount of space requested.
+    The idea is to prettify.
+
+    ----------
+    space : int
+        number of spaces for padding
+    lists : str
+        list of str which being joined
+    strlen : callable
+        function used to calculate the length of each str. Needed for unicode
+        handling.
+    justfunc : callable
+        function used to justify str. Needed for unicode handling.
+    """
+    strlen = kwargs.pop("strlen", len)
+    justfunc = kwargs.pop("justfunc", _adj_justify)
+
+    newLists = []
+    lengths = [max(map(strlen, x)) + space for x in lists[:-1]]
+    # not the last one
+    lengths.append(max(map(len, lists[-1])))
+    maxLen = max(map(len, lists))
+    for i, lst in enumerate(lists):
+        nl = justfunc(lst, lengths[i], mode="left")
+        nl = ([" " * lengths[i]] * (maxLen - len(lst))) + nl
+        newLists.append(nl)
+    toJoin = zip(*newLists)
+    return "\n".join("".join(lines) for lines in toJoin)
+
+
+def _adj_justify(texts: Iterable[str], max_len: int, mode: str = "right") -> list[str]:
+    """
+    Perform ljust, center, rjust against string or list-like
+    """
+    if mode == "left":
+        return [x.ljust(max_len) for x in texts]
+    elif mode == "center":
+        return [x.center(max_len) for x in texts]
+    else:
+        return [x.rjust(max_len) for x in texts]
+
+
+# Unicode consolidation
+# ---------------------
+#
+# pprinting utility functions for generating Unicode text or
+# bytes(3.x)/str(2.x) representations of objects.
+# Try to use these as much as possible rather than rolling your own.
+#
+# When to use
+# -----------
+#
+# 1) If you're writing code internal to pandas (no I/O directly involved),
+#    use pprint_thing().
+#
+#    It will always return unicode text which can handled by other
+#    parts of the package without breakage.
+#
+# 2) if you need to write something out to file, use
+#    pprint_thing_encoded(encoding).
+#
+#    If no encoding is specified, it defaults to utf-8. Since encoding pure
+#    ascii with utf-8 is a no-op you can safely use the default utf-8 if you're
+#    working with straight ascii.
+
+
+def _pprint_seq(
+    seq: Sequence, _nest_lvl: int = 0, max_seq_items: int | None = None, **kwds
+) -> str:
+    """
+    internal. pprinter for iterables. you should probably use pprint_thing()
+    rather than calling this directly.
+
+    bounds length of printed sequence, depending on options
+    """
+    if isinstance(seq, set):
+        fmt = "{{{body}}}"
+    else:
+        fmt = "[{body}]" if hasattr(seq, "__setitem__") else "({body})"
+
+    if max_seq_items is False:
+        nitems = len(seq)
+    else:
+        nitems = max_seq_items or get_option("max_seq_items") or len(seq)
+
+    s = iter(seq)
+    # handle sets, no slicing
+    r = [
+        pprint_thing(next(s), _nest_lvl + 1, max_seq_items=max_seq_items, **kwds)
+        for i in range(min(nitems, len(seq)))
+    ]
+    body = ", ".join(r)
+
+    if nitems < len(seq):
+        body += ", ..."
+    elif isinstance(seq, tuple) and len(seq) == 1:
+        body += ","
+
+    return fmt.format(body=body)
+
+
+def _pprint_dict(
+    seq: Mapping, _nest_lvl: int = 0, max_seq_items: int | None = None, **kwds
+) -> str:
+    """
+    internal. pprinter for iterables. you should probably use pprint_thing()
+    rather than calling this directly.
+    """
+    fmt = "{{{things}}}"
+    pairs = []
+
+    pfmt = "{key}: {val}"
+
+    if max_seq_items is False:
+        nitems = len(seq)
+    else:
+        nitems = max_seq_items or get_option("max_seq_items") or len(seq)
+
+    for k, v in list(seq.items())[:nitems]:
+        pairs.append(
+            pfmt.format(
+                key=pprint_thing(k, _nest_lvl + 1, max_seq_items=max_seq_items, **kwds),
+                val=pprint_thing(v, _nest_lvl + 1, max_seq_items=max_seq_items, **kwds),
+            )
+        )
+
+    if nitems < len(seq):
+        return fmt.format(things=", ".join(pairs) + ", ...")
+    else:
+        return fmt.format(things=", ".join(pairs))
+
+
+def pprint_thing(
+    thing: Any,
+    _nest_lvl: int = 0,
+    escape_chars: EscapeChars | None = None,
+    default_escapes: bool = False,
+    quote_strings: bool = False,
+    max_seq_items: int | None = None,
+) -> str:
+    """
+    This function is the sanctioned way of converting objects
+    to a string representation and properly handles nested sequences.
+
+    Parameters
+    ----------
+    thing : anything to be formatted
+    _nest_lvl : internal use only. pprint_thing() is mutually-recursive
+        with pprint_sequence, this argument is used to keep track of the
+        current nesting level, and limit it.
+    escape_chars : list or dict, optional
+        Characters to escape. If a dict is passed the values are the
+        replacements
+    default_escapes : bool, default False
+        Whether the input escape characters replaces or adds to the defaults
+    max_seq_items : int or None, default None
+        Pass through to other pretty printers to limit sequence printing
+
+    Returns
+    -------
+    str
+    """
+
+    def as_escaped_string(
+        thing: Any, escape_chars: EscapeChars | None = escape_chars
+    ) -> str:
+        translate = {"\t": r"\t", "\n": r"\n", "\r": r"\r"}
+        if isinstance(escape_chars, dict):
+            if default_escapes:
+                translate.update(escape_chars)
+            else:
+                translate = escape_chars
+            escape_chars = list(escape_chars.keys())
+        else:
+            escape_chars = escape_chars or ()
+
+        result = str(thing)
+        for c in escape_chars:
+            result = result.replace(c, translate[c])
+        return result
+
+    if hasattr(thing, "__next__"):
+        return str(thing)
+    elif isinstance(thing, dict) and _nest_lvl < get_option(
+        "display.pprint_nest_depth"
+    ):
+        result = _pprint_dict(
+            thing, _nest_lvl, quote_strings=True, max_seq_items=max_seq_items
+        )
+    elif is_sequence(thing) and _nest_lvl < get_option("display.pprint_nest_depth"):
+        result = _pprint_seq(
+            thing,
+            _nest_lvl,
+            escape_chars=escape_chars,
+            quote_strings=quote_strings,
+            max_seq_items=max_seq_items,
+        )
+    elif isinstance(thing, str) and quote_strings:
+        result = f"'{as_escaped_string(thing)}'"
+    else:
+        result = as_escaped_string(thing)
+
+    return result
+
+
+def pprint_thing_encoded(
+    object, encoding: str = "utf-8", errors: str = "replace"
+) -> bytes:
+    value = pprint_thing(object)  # get unicode representation of object
+    return value.encode(encoding, errors)
+
+
+def enable_data_resource_formatter(enable: bool) -> None:
+    if "IPython" not in sys.modules:
+        # definitely not in IPython
+        return
+    from IPython import get_ipython
+
+    ip = get_ipython()
+    if ip is None:
+        # still not in IPython
+        return
+
+    formatters = ip.display_formatter.formatters
+    mimetype = "application/vnd.dataresource+json"
+
+    if enable:
+        if mimetype not in formatters:
+            # define tableschema formatter
+            from IPython.core.formatters import BaseFormatter
+            from traitlets import ObjectName
+
+            class TableSchemaFormatter(BaseFormatter):
+                print_method = ObjectName("_repr_data_resource_")
+                _return_type = (dict,)
+
+            # register it:
+            formatters[mimetype] = TableSchemaFormatter()
+        # enable it if it's been disabled:
+        formatters[mimetype].enabled = True
+    # unregister tableschema mime-type
+    elif mimetype in formatters:
+        formatters[mimetype].enabled = False
+
+
+def default_pprint(thing: Any, max_seq_items: int | None = None) -> str:
+    return pprint_thing(
+        thing,
+        escape_chars=("\t", "\r", "\n"),
+        quote_strings=True,
+        max_seq_items=max_seq_items,
+    )
+
+
+def format_object_summary(
+    obj,
+    formatter: Callable,
+    is_justify: bool = True,
+    name: str | None = None,
+    indent_for_name: bool = True,
+    line_break_each_value: bool = False,
+) -> str:
+    """
+    Return the formatted obj as a unicode string
+
+    Parameters
+    ----------
+    obj : object
+        must be iterable and support __getitem__
+    formatter : callable
+        string formatter for an element
+    is_justify : bool
+        should justify the display
+    name : name, optional
+        defaults to the class name of the obj
+    indent_for_name : bool, default True
+        Whether subsequent lines should be indented to
+        align with the name.
+    line_break_each_value : bool, default False
+        If True, inserts a line break for each value of ``obj``.
+        If False, only break lines when the a line of values gets wider
+        than the display width.
+
+    Returns
+    -------
+    summary string
+    """
+    display_width, _ = get_console_size()
+    if display_width is None:
+        display_width = get_option("display.width") or 80
+    if name is None:
+        name = type(obj).__name__
+
+    if indent_for_name:
+        name_len = len(name)
+        space1 = f'\n{(" " * (name_len + 1))}'
+        space2 = f'\n{(" " * (name_len + 2))}'
+    else:
+        space1 = "\n"
+        space2 = "\n "  # space for the opening '['
+
+    n = len(obj)
+    if line_break_each_value:
+        # If we want to vertically align on each value of obj, we need to
+        # separate values by a line break and indent the values
+        sep = ",\n " + " " * len(name)
+    else:
+        sep = ","
+    max_seq_items = get_option("display.max_seq_items") or n
+
+    # are we a truncated display
+    is_truncated = n > max_seq_items
+
+    # adj can optionally handle unicode eastern asian width
+    adj = get_adjustment()
+
+    def _extend_line(
+        s: str, line: str, value: str, display_width: int, next_line_prefix: str
+    ) -> tuple[str, str]:
+        if adj.len(line.rstrip()) + adj.len(value.rstrip()) >= display_width:
+            s += line.rstrip()
+            line = next_line_prefix
+        line += value
+        return s, line
+
+    def best_len(values: list[str]) -> int:
+        if values:
+            return max(adj.len(x) for x in values)
+        else:
+            return 0
+
+    close = ", "
+
+    if n == 0:
+        summary = f"[]{close}"
+    elif n == 1 and not line_break_each_value:
+        first = formatter(obj[0])
+        summary = f"[{first}]{close}"
+    elif n == 2 and not line_break_each_value:
+        first = formatter(obj[0])
+        last = formatter(obj[-1])
+        summary = f"[{first}, {last}]{close}"
+    else:
+        if max_seq_items == 1:
+            # If max_seq_items=1 show only last element
+            head = []
+            tail = [formatter(x) for x in obj[-1:]]
+        elif n > max_seq_items:
+            n = min(max_seq_items // 2, 10)
+            head = [formatter(x) for x in obj[:n]]
+            tail = [formatter(x) for x in obj[-n:]]
+        else:
+            head = []
+            tail = [formatter(x) for x in obj]
+
+        # adjust all values to max length if needed
+        if is_justify:
+            if line_break_each_value:
+                # Justify each string in the values of head and tail, so the
+                # strings will right align when head and tail are stacked
+                # vertically.
+                head, tail = _justify(head, tail)
+            elif is_truncated or not (
+                len(", ".join(head)) < display_width
+                and len(", ".join(tail)) < display_width
+            ):
+                # Each string in head and tail should align with each other
+                max_length = max(best_len(head), best_len(tail))
+                head = [x.rjust(max_length) for x in head]
+                tail = [x.rjust(max_length) for x in tail]
+            # If we are not truncated and we are only a single
+            # line, then don't justify
+
+        if line_break_each_value:
+            # Now head and tail are of type List[Tuple[str]]. Below we
+            # convert them into List[str], so there will be one string per
+            # value. Also truncate items horizontally if wider than
+            # max_space
+            max_space = display_width - len(space2)
+            value = tail[0]
+            max_items = 1
+            for num_items in reversed(range(1, len(value) + 1)):
+                pprinted_seq = _pprint_seq(value, max_seq_items=num_items)
+                if len(pprinted_seq) < max_space:
+                    max_items = num_items
+                    break
+            head = [_pprint_seq(x, max_seq_items=max_items) for x in head]
+            tail = [_pprint_seq(x, max_seq_items=max_items) for x in tail]
+
+        summary = ""
+        line = space2
+
+        for head_value in head:
+            word = head_value + sep + " "
+            summary, line = _extend_line(summary, line, word, display_width, space2)
+
+        if is_truncated:
+            # remove trailing space of last line
+            summary += line.rstrip() + space2 + "..."
+            line = space2
+
+        for tail_item in tail[:-1]:
+            word = tail_item + sep + " "
+            summary, line = _extend_line(summary, line, word, display_width, space2)
+
+        # last value: no sep added + 1 space of width used for trailing ','
+        summary, line = _extend_line(summary, line, tail[-1], display_width - 2, space2)
+        summary += line
+
+        # right now close is either '' or ', '
+        # Now we want to include the ']', but not the maybe space.
+        close = "]" + close.rstrip(" ")
+        summary += close
+
+        if len(summary) > (display_width) or line_break_each_value:
+            summary += space1
+        else:  # one row
+            summary += " "
+
+        # remove initial space
+        summary = "[" + summary[len(space2) :]
+
+    return summary
+
+
+def _justify(
+    head: list[Sequence[str]], tail: list[Sequence[str]]
+) -> tuple[list[tuple[str, ...]], list[tuple[str, ...]]]:
+    """
+    Justify items in head and tail, so they are right-aligned when stacked.
+
+    Parameters
+    ----------
+    head : list-like of list-likes of strings
+    tail : list-like of list-likes of strings
+
+    Returns
+    -------
+    tuple of list of tuples of strings
+        Same as head and tail, but items are right aligned when stacked
+        vertically.
+
+    Examples
+    --------
+    >>> _justify([['a', 'b']], [['abc', 'abcd']])
+    ([('  a', '   b')], [('abc', 'abcd')])
+    """
+    combined = head + tail
+
+    # For each position for the sequences in ``combined``,
+    # find the length of the largest string.
+    max_length = [0] * len(combined[0])
+    for inner_seq in combined:
+        length = [len(item) for item in inner_seq]
+        max_length = [max(x, y) for x, y in zip(max_length, length)]
+
+    # justify each item in each list-like in head and tail using max_length
+    head_tuples = [
+        tuple(x.rjust(max_len) for x, max_len in zip(seq, max_length)) for seq in head
+    ]
+    tail_tuples = [
+        tuple(x.rjust(max_len) for x, max_len in zip(seq, max_length)) for seq in tail
+    ]
+    return head_tuples, tail_tuples
+
+
+class PrettyDict(dict[_KT, _VT]):
+    """Dict extension to support abbreviated __repr__"""
+
+    def __repr__(self) -> str:
+        return pprint_thing(self)
+
+
+class _TextAdjustment:
+    def __init__(self) -> None:
+        self.encoding = get_option("display.encoding")
+
+    def len(self, text: str) -> int:
+        return len(text)
+
+    def justify(self, texts: Any, max_len: int, mode: str = "right") -> list[str]:
+        """
+        Perform ljust, center, rjust against string or list-like
+        """
+        if mode == "left":
+            return [x.ljust(max_len) for x in texts]
+        elif mode == "center":
+            return [x.center(max_len) for x in texts]
+        else:
+            return [x.rjust(max_len) for x in texts]
+
+    def adjoin(self, space: int, *lists, **kwargs) -> str:
+        return adjoin(space, *lists, strlen=self.len, justfunc=self.justify, **kwargs)
+
+
+class _EastAsianTextAdjustment(_TextAdjustment):
+    def __init__(self) -> None:
+        super().__init__()
+        if get_option("display.unicode.ambiguous_as_wide"):
+            self.ambiguous_width = 2
+        else:
+            self.ambiguous_width = 1
+
+        # Definition of East Asian Width
+        # https://unicode.org/reports/tr11/
+        # Ambiguous width can be changed by option
+        self._EAW_MAP = {"Na": 1, "N": 1, "W": 2, "F": 2, "H": 1}
+
+    def len(self, text: str) -> int:
+        """
+        Calculate display width considering unicode East Asian Width
+        """
+        if not isinstance(text, str):
+            return len(text)
+
+        return sum(
+            self._EAW_MAP.get(east_asian_width(c), self.ambiguous_width) for c in text
+        )
+
+    def justify(
+        self, texts: Iterable[str], max_len: int, mode: str = "right"
+    ) -> list[str]:
+        # re-calculate padding space per str considering East Asian Width
+        def _get_pad(t):
+            return max_len - self.len(t) + len(t)
+
+        if mode == "left":
+            return [x.ljust(_get_pad(x)) for x in texts]
+        elif mode == "center":
+            return [x.center(_get_pad(x)) for x in texts]
+        else:
+            return [x.rjust(_get_pad(x)) for x in texts]
+
+
+def get_adjustment() -> _TextAdjustment:
+    use_east_asian_width = get_option("display.unicode.east_asian_width")
+    if use_east_asian_width:
+        return _EastAsianTextAdjustment()
+    else:
+        return _TextAdjustment()
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/string.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/string.py
new file mode 100644
index 0000000000000000000000000000000000000000..cdad388592717dff79fde61bf35a12c0635034c1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/string.py
@@ -0,0 +1,206 @@
+"""
+Module for formatting output data in console (to string).
+"""
+from __future__ import annotations
+
+from shutil import get_terminal_size
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from pandas.io.formats.format import DataFrameFormatter
+
+
+class StringFormatter:
+    """Formatter for string representation of a dataframe."""
+
+    def __init__(self, fmt: DataFrameFormatter, line_width: int | None = None) -> None:
+        self.fmt = fmt
+        self.adj = fmt.adj
+        self.frame = fmt.frame
+        self.line_width = line_width
+
+    def to_string(self) -> str:
+        text = self._get_string_representation()
+        if self.fmt.should_show_dimensions:
+            text = f"{text}{self.fmt.dimensions_info}"
+        return text
+
+    def _get_strcols(self) -> list[list[str]]:
+        strcols = self.fmt.get_strcols()
+        if self.fmt.is_truncated:
+            strcols = self._insert_dot_separators(strcols)
+        return strcols
+
+    def _get_string_representation(self) -> str:
+        if self.fmt.frame.empty:
+            return self._empty_info_line
+
+        strcols = self._get_strcols()
+
+        if self.line_width is None:
+            # no need to wrap around just print the whole frame
+            return self.adj.adjoin(1, *strcols)
+
+        if self._need_to_wrap_around:
+            return self._join_multiline(strcols)
+
+        return self._fit_strcols_to_terminal_width(strcols)
+
+    @property
+    def _empty_info_line(self) -> str:
+        return (
+            f"Empty {type(self.frame).__name__}\n"
+            f"Columns: {pprint_thing(self.frame.columns)}\n"
+            f"Index: {pprint_thing(self.frame.index)}"
+        )
+
+    @property
+    def _need_to_wrap_around(self) -> bool:
+        return bool(self.fmt.max_cols is None or self.fmt.max_cols > 0)
+
+    def _insert_dot_separators(self, strcols: list[list[str]]) -> list[list[str]]:
+        str_index = self.fmt._get_formatted_index(self.fmt.tr_frame)
+        index_length = len(str_index)
+
+        if self.fmt.is_truncated_horizontally:
+            strcols = self._insert_dot_separator_horizontal(strcols, index_length)
+
+        if self.fmt.is_truncated_vertically:
+            strcols = self._insert_dot_separator_vertical(strcols, index_length)
+
+        return strcols
+
+    @property
+    def _adjusted_tr_col_num(self) -> int:
+        return self.fmt.tr_col_num + 1 if self.fmt.index else self.fmt.tr_col_num
+
+    def _insert_dot_separator_horizontal(
+        self, strcols: list[list[str]], index_length: int
+    ) -> list[list[str]]:
+        strcols.insert(self._adjusted_tr_col_num, [" ..."] * index_length)
+        return strcols
+
+    def _insert_dot_separator_vertical(
+        self, strcols: list[list[str]], index_length: int
+    ) -> list[list[str]]:
+        n_header_rows = index_length - len(self.fmt.tr_frame)
+        row_num = self.fmt.tr_row_num
+        for ix, col in enumerate(strcols):
+            cwidth = self.adj.len(col[row_num])
+
+            if self.fmt.is_truncated_horizontally:
+                is_dot_col = ix == self._adjusted_tr_col_num
+            else:
+                is_dot_col = False
+
+            if cwidth > 3 or is_dot_col:
+                dots = "..."
+            else:
+                dots = ".."
+
+            if ix == 0 and self.fmt.index:
+                dot_mode = "left"
+            elif is_dot_col:
+                cwidth = 4
+                dot_mode = "right"
+            else:
+                dot_mode = "right"
+
+            dot_str = self.adj.justify([dots], cwidth, mode=dot_mode)[0]
+            col.insert(row_num + n_header_rows, dot_str)
+        return strcols
+
+    def _join_multiline(self, strcols_input: Iterable[list[str]]) -> str:
+        lwidth = self.line_width
+        adjoin_width = 1
+        strcols = list(strcols_input)
+
+        if self.fmt.index:
+            idx = strcols.pop(0)
+            lwidth -= np.array([self.adj.len(x) for x in idx]).max() + adjoin_width
+
+        col_widths = [
+            np.array([self.adj.len(x) for x in col]).max() if len(col) > 0 else 0
+            for col in strcols
+        ]
+
+        assert lwidth is not None
+        col_bins = _binify(col_widths, lwidth)
+        nbins = len(col_bins)
+
+        str_lst = []
+        start = 0
+        for i, end in enumerate(col_bins):
+            row = strcols[start:end]
+            if self.fmt.index:
+                row.insert(0, idx)
+            if nbins > 1:
+                nrows = len(row[-1])
+                if end <= len(strcols) and i < nbins - 1:
+                    row.append([" \\"] + ["  "] * (nrows - 1))
+                else:
+                    row.append([" "] * nrows)
+            str_lst.append(self.adj.adjoin(adjoin_width, *row))
+            start = end
+        return "\n\n".join(str_lst)
+
+    def _fit_strcols_to_terminal_width(self, strcols: list[list[str]]) -> str:
+        from pandas import Series
+
+        lines = self.adj.adjoin(1, *strcols).split("\n")
+        max_len = Series(lines).str.len().max()
+        # plus truncate dot col
+        width, _ = get_terminal_size()
+        dif = max_len - width
+        # '+ 1' to avoid too wide repr (GH PR #17023)
+        adj_dif = dif + 1
+        col_lens = Series([Series(ele).str.len().max() for ele in strcols])
+        n_cols = len(col_lens)
+        counter = 0
+        while adj_dif > 0 and n_cols > 1:
+            counter += 1
+            mid = round(n_cols / 2)
+            mid_ix = col_lens.index[mid]
+            col_len = col_lens[mid_ix]
+            # adjoin adds one
+            adj_dif -= col_len + 1
+            col_lens = col_lens.drop(mid_ix)
+            n_cols = len(col_lens)
+
+        # subtract index column
+        max_cols_fitted = n_cols - self.fmt.index
+        # GH-21180. Ensure that we print at least two.
+        max_cols_fitted = max(max_cols_fitted, 2)
+        self.fmt.max_cols_fitted = max_cols_fitted
+
+        # Call again _truncate to cut frame appropriately
+        # and then generate string representation
+        self.fmt.truncate()
+        strcols = self._get_strcols()
+        return self.adj.adjoin(1, *strcols)
+
+
+def _binify(cols: list[int], line_width: int) -> list[int]:
+    adjoin_width = 1
+    bins = []
+    curr_width = 0
+    i_last_column = len(cols) - 1
+    for i, w in enumerate(cols):
+        w_adjoined = w + adjoin_width
+        curr_width += w_adjoined
+        if i_last_column == i:
+            wrap = curr_width + 1 > line_width and i > 0
+        else:
+            wrap = curr_width + 2 > line_width and i > 0
+        if wrap:
+            bins.append(i)
+            curr_width = w_adjoined
+
+    bins.append(len(cols))
+    return bins
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/style.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/style.py
new file mode 100644
index 0000000000000000000000000000000000000000..987577057e058e7dcc5f37ebdd0a8f6f4a302c20
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/style.py
@@ -0,0 +1,4136 @@
+"""
+Module for applying conditional formatting to DataFrames and Series.
+"""
+from __future__ import annotations
+
+from contextlib import contextmanager
+import copy
+from functools import partial
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import (
+    Substitution,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+import pandas as pd
+from pandas import (
+    IndexSlice,
+    RangeIndex,
+)
+import pandas.core.common as com
+from pandas.core.frame import (
+    DataFrame,
+    Series,
+)
+from pandas.core.generic import NDFrame
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.formats.format import save_to_buffer
+
+jinja2 = import_optional_dependency("jinja2", extra="DataFrame.style requires jinja2.")
+
+from pandas.io.formats.style_render import (
+    CSSProperties,
+    CSSStyles,
+    ExtFormatter,
+    StylerRenderer,
+    Subset,
+    Tooltips,
+    format_table_styles,
+    maybe_convert_css_to_tuples,
+    non_reducing_slice,
+    refactor_levels,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Hashable,
+        Sequence,
+    )
+
+    from matplotlib.colors import Colormap
+
+    from pandas._typing import (
+        Axis,
+        AxisInt,
+        FilePath,
+        IndexLabel,
+        IntervalClosedType,
+        Level,
+        QuantileInterpolation,
+        Scalar,
+        StorageOptions,
+        WriteBuffer,
+        WriteExcelBuffer,
+    )
+
+    from pandas import ExcelWriter
+
+try:
+    import matplotlib as mpl
+    import matplotlib.pyplot as plt
+
+    has_mpl = True
+except ImportError:
+    has_mpl = False
+
+
+@contextmanager
+def _mpl(func: Callable) -> Generator[tuple[Any, Any], None, None]:
+    if has_mpl:
+        yield plt, mpl
+    else:
+        raise ImportError(f"{func.__name__} requires matplotlib.")
+
+
+####
+# Shared Doc Strings
+
+subset_args = """subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, ]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function."""
+
+properties_args = """props : str, default None
+           CSS properties to use for highlighting. If ``props`` is given, ``color``
+           is not used."""
+
+coloring_args = """color : str, default '{default}'
+           Background color to use for highlighting."""
+
+buffering_args = """buf : str, path object, file-like object, optional
+         String, path object (implementing ``os.PathLike[str]``), or file-like
+         object implementing a string ``write()`` function. If ``None``, the result is
+         returned as a string."""
+
+encoding_args = """encoding : str, optional
+              Character encoding setting for file output (and meta tags if available).
+              Defaults to ``pandas.options.styler.render.encoding`` value of "utf-8"."""
+
+#
+###
+
+
+class Styler(StylerRenderer):
+    r"""
+    Helps style a DataFrame or Series according to the data with HTML and CSS.
+
+    Parameters
+    ----------
+    data : Series or DataFrame
+        Data to be styled - either a Series or DataFrame.
+    precision : int, optional
+        Precision to round floats to. If not given defaults to
+        ``pandas.options.styler.format.precision``.
+
+        .. versionchanged:: 1.4.0
+    table_styles : list-like, default None
+        List of {selector: (attr, value)} dicts; see Notes.
+    uuid : str, default None
+        A unique identifier to avoid CSS collisions; generated automatically.
+    caption : str, tuple, default None
+        String caption to attach to the table. Tuple only used for LaTeX dual captions.
+    table_attributes : str, default None
+        Items that show up in the opening ``
) elements that will be rendered before
+    trimming will occur over columns, rows or both if needed.
+"""
+
+styler_max_rows = """
+: int, optional
+    The maximum number of rows that will be rendered. May still be reduced to
+    satisfy ``max_elements``, which takes precedence.
+"""
+
+styler_max_columns = """
+: int, optional
+    The maximum number of columns that will be rendered. May still be reduced to
+    satisfy ``max_elements``, which takes precedence.
+"""
+
+styler_precision = """
+: int
+    The precision for floats and complex numbers.
+"""
+
+styler_decimal = """
+: str
+    The character representation for the decimal separator for floats and complex.
+"""
+
+styler_thousands = """
+: str, optional
+    The character representation for thousands separator for floats, int and complex.
+"""
+
+styler_na_rep = """
+: str, optional
+    The string representation for values identified as missing.
+"""
+
+styler_escape = """
+: str, optional
+    Whether to escape certain characters according to the given context; html or latex.
+"""
+
+styler_formatter = """
+: str, callable, dict, optional
+    A formatter object to be used as default within ``Styler.format``.
+"""
+
+styler_multirow_align = """
+: {"c", "t", "b"}
+    The specifier for vertical alignment of sparsified LaTeX multirows.
+"""
+
+styler_multicol_align = r"""
+: {"r", "c", "l", "naive-l", "naive-r"}
+    The specifier for horizontal alignment of sparsified LaTeX multicolumns. Pipe
+    decorators can also be added to non-naive values to draw vertical
+    rules, e.g. "\|r" will draw a rule on the left side of right aligned merged cells.
+"""
+
+styler_hrules = """
+: bool
+    Whether to add horizontal rules on top and bottom and below the headers.
+"""
+
+styler_environment = """
+: str
+    The environment to replace ``\\begin{table}``. If "longtable" is used results
+    in a specific longtable environment format.
+"""
+
+styler_encoding = """
+: str
+    The encoding used for output HTML and LaTeX files.
+"""
+
+styler_mathjax = """
+: bool
+    If False will render special CSS classes to table attributes that indicate Mathjax
+    will not be used in Jupyter Notebook.
+"""
+
+with cf.config_prefix("styler"):
+    cf.register_option("sparse.index", True, styler_sparse_index_doc, validator=is_bool)
+
+    cf.register_option(
+        "sparse.columns", True, styler_sparse_columns_doc, validator=is_bool
+    )
+
+    cf.register_option(
+        "render.repr",
+        "html",
+        styler_render_repr,
+        validator=is_one_of_factory(["html", "latex"]),
+    )
+
+    cf.register_option(
+        "render.max_elements",
+        2**18,
+        styler_max_elements,
+        validator=is_nonnegative_int,
+    )
+
+    cf.register_option(
+        "render.max_rows",
+        None,
+        styler_max_rows,
+        validator=is_nonnegative_int,
+    )
+
+    cf.register_option(
+        "render.max_columns",
+        None,
+        styler_max_columns,
+        validator=is_nonnegative_int,
+    )
+
+    cf.register_option("render.encoding", "utf-8", styler_encoding, validator=is_str)
+
+    cf.register_option("format.decimal", ".", styler_decimal, validator=is_str)
+
+    cf.register_option(
+        "format.precision", 6, styler_precision, validator=is_nonnegative_int
+    )
+
+    cf.register_option(
+        "format.thousands",
+        None,
+        styler_thousands,
+        validator=is_instance_factory([type(None), str]),
+    )
+
+    cf.register_option(
+        "format.na_rep",
+        None,
+        styler_na_rep,
+        validator=is_instance_factory([type(None), str]),
+    )
+
+    cf.register_option(
+        "format.escape",
+        None,
+        styler_escape,
+        validator=is_one_of_factory([None, "html", "latex", "latex-math"]),
+    )
+
+    cf.register_option(
+        "format.formatter",
+        None,
+        styler_formatter,
+        validator=is_instance_factory([type(None), dict, Callable, str]),
+    )
+
+    cf.register_option("html.mathjax", True, styler_mathjax, validator=is_bool)
+
+    cf.register_option(
+        "latex.multirow_align",
+        "c",
+        styler_multirow_align,
+        validator=is_one_of_factory(["c", "t", "b", "naive"]),
+    )
+
+    val_mca = ["r", "|r|", "|r", "r|", "c", "|c|", "|c", "c|", "l", "|l|", "|l", "l|"]
+    val_mca += ["naive-l", "naive-r"]
+    cf.register_option(
+        "latex.multicol_align",
+        "r",
+        styler_multicol_align,
+        validator=is_one_of_factory(val_mca),
+    )
+
+    cf.register_option("latex.hrules", False, styler_hrules, validator=is_bool)
+
+    cf.register_option(
+        "latex.environment",
+        None,
+        styler_environment,
+        validator=is_instance_factory([type(None), str]),
+    )
+
+
+with cf.config_prefix("future"):
+    cf.register_option(
+        "infer_string",
+        True if os.environ.get("PANDAS_FUTURE_INFER_STRING", "0") == "1" else False,
+        "Whether to infer sequence of str objects as pyarrow string "
+        "dtype, which will be the default in pandas 3.0 "
+        "(at which point this option will be deprecated).",
+        validator=is_one_of_factory([True, False]),
+    )
+
+    cf.register_option(
+        "no_silent_downcasting",
+        False,
+        "Whether to opt-in to the future behavior which will *not* silently "
+        "downcast results from Series and DataFrame `where`, `mask`, and `clip` "
+        "methods. "
+        "Silent downcasting will be removed in pandas 3.0 "
+        "(at which point this option will be deprecated).",
+        validator=is_one_of_factory([True, False]),
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/construction.py b/.venv/lib/python3.13/site-packages/pandas/core/construction.py
new file mode 100644
index 0000000000000000000000000000000000000000..59e87f28a3dce82395abc16d3bb3ef63d155c820
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/construction.py
@@ -0,0 +1,821 @@
+"""
+Constructor functions intended to be shared by pd.array, Series.__init__,
+and Index.__new__.
+
+These should not depend on core.internals.
+"""
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import (
+    TYPE_CHECKING,
+    Optional,
+    Union,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+from numpy import ma
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import lib
+from pandas._libs.tslibs import (
+    Period,
+    get_supported_dtype,
+    is_supported_dtype,
+)
+from pandas._typing import (
+    AnyArrayLike,
+    ArrayLike,
+    Dtype,
+    DtypeObj,
+    T,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import ExtensionDtype
+from pandas.core.dtypes.cast import (
+    construct_1d_arraylike_from_scalar,
+    construct_1d_object_array_from_listlike,
+    maybe_cast_to_datetime,
+    maybe_cast_to_integer_array,
+    maybe_convert_platform,
+    maybe_infer_to_datetimelike,
+    maybe_promote,
+)
+from pandas.core.dtypes.common import (
+    is_list_like,
+    is_object_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import NumpyEADtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCExtensionArray,
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import isna
+
+import pandas.core.common as com
+
+if TYPE_CHECKING:
+    from pandas import (
+        Index,
+        Series,
+    )
+    from pandas.core.arrays.base import ExtensionArray
+
+
+def array(
+    data: Sequence[object] | AnyArrayLike,
+    dtype: Dtype | None = None,
+    copy: bool = True,
+) -> ExtensionArray:
+    """
+    Create an array.
+
+    Parameters
+    ----------
+    data : Sequence of objects
+        The scalars inside `data` should be instances of the
+        scalar type for `dtype`. It's expected that `data`
+        represents a 1-dimensional array of data.
+
+        When `data` is an Index or Series, the underlying array
+        will be extracted from `data`.
+
+    dtype : str, np.dtype, or ExtensionDtype, optional
+        The dtype to use for the array. This may be a NumPy
+        dtype or an extension type registered with pandas using
+        :meth:`pandas.api.extensions.register_extension_dtype`.
+
+        If not specified, there are two possibilities:
+
+        1. When `data` is a :class:`Series`, :class:`Index`, or
+           :class:`ExtensionArray`, the `dtype` will be taken
+           from the data.
+        2. Otherwise, pandas will attempt to infer the `dtype`
+           from the data.
+
+        Note that when `data` is a NumPy array, ``data.dtype`` is
+        *not* used for inferring the array type. This is because
+        NumPy cannot represent all the types of data that can be
+        held in extension arrays.
+
+        Currently, pandas will infer an extension dtype for sequences of
+
+        ============================== =======================================
+        Scalar Type                    Array Type
+        ============================== =======================================
+        :class:`pandas.Interval`       :class:`pandas.arrays.IntervalArray`
+        :class:`pandas.Period`         :class:`pandas.arrays.PeriodArray`
+        :class:`datetime.datetime`     :class:`pandas.arrays.DatetimeArray`
+        :class:`datetime.timedelta`    :class:`pandas.arrays.TimedeltaArray`
+        :class:`int`                   :class:`pandas.arrays.IntegerArray`
+        :class:`float`                 :class:`pandas.arrays.FloatingArray`
+        :class:`str`                   :class:`pandas.arrays.StringArray` or
+                                       :class:`pandas.arrays.ArrowStringArray`
+        :class:`bool`                  :class:`pandas.arrays.BooleanArray`
+        ============================== =======================================
+
+        The ExtensionArray created when the scalar type is :class:`str` is determined by
+        ``pd.options.mode.string_storage`` if the dtype is not explicitly given.
+
+        For all other cases, NumPy's usual inference rules will be used.
+    copy : bool, default True
+        Whether to copy the data, even if not necessary. Depending
+        on the type of `data`, creating the new array may require
+        copying data, even if ``copy=False``.
+
+    Returns
+    -------
+    ExtensionArray
+        The newly created array.
+
+    Raises
+    ------
+    ValueError
+        When `data` is not 1-dimensional.
+
+    See Also
+    --------
+    numpy.array : Construct a NumPy array.
+    Series : Construct a pandas Series.
+    Index : Construct a pandas Index.
+    arrays.NumpyExtensionArray : ExtensionArray wrapping a NumPy array.
+    Series.array : Extract the array stored within a Series.
+
+    Notes
+    -----
+    Omitting the `dtype` argument means pandas will attempt to infer the
+    best array type from the values in the data. As new array types are
+    added by pandas and 3rd party libraries, the "best" array type may
+    change. We recommend specifying `dtype` to ensure that
+
+    1. the correct array type for the data is returned
+    2. the returned array type doesn't change as new extension types
+       are added by pandas and third-party libraries
+
+    Additionally, if the underlying memory representation of the returned
+    array matters, we recommend specifying the `dtype` as a concrete object
+    rather than a string alias or allowing it to be inferred. For example,
+    a future version of pandas or a 3rd-party library may include a
+    dedicated ExtensionArray for string data. In this event, the following
+    would no longer return a :class:`arrays.NumpyExtensionArray` backed by a
+    NumPy array.
+
+    >>> pd.array(['a', 'b'], dtype=str)
+    
+    ['a', 'b']
+    Length: 2, dtype: str32
+
+    This would instead return the new ExtensionArray dedicated for string
+    data. If you really need the new array to be backed by a  NumPy array,
+    specify that in the dtype.
+
+    >>> pd.array(['a', 'b'], dtype=np.dtype("
+    ['a', 'b']
+    Length: 2, dtype: str32
+
+    Finally, Pandas has arrays that mostly overlap with NumPy
+
+      * :class:`arrays.DatetimeArray`
+      * :class:`arrays.TimedeltaArray`
+
+    When data with a ``datetime64[ns]`` or ``timedelta64[ns]`` dtype is
+    passed, pandas will always return a ``DatetimeArray`` or ``TimedeltaArray``
+    rather than a ``NumpyExtensionArray``. This is for symmetry with the case of
+    timezone-aware data, which NumPy does not natively support.
+
+    >>> pd.array(['2015', '2016'], dtype='datetime64[ns]')
+    
+    ['2015-01-01 00:00:00', '2016-01-01 00:00:00']
+    Length: 2, dtype: datetime64[ns]
+
+    >>> pd.array(["1h", "2h"], dtype='timedelta64[ns]')
+    
+    ['0 days 01:00:00', '0 days 02:00:00']
+    Length: 2, dtype: timedelta64[ns]
+
+    Examples
+    --------
+    If a dtype is not specified, pandas will infer the best dtype from the values.
+    See the description of `dtype` for the types pandas infers for.
+
+    >>> pd.array([1, 2])
+    
+    [1, 2]
+    Length: 2, dtype: Int64
+
+    >>> pd.array([1, 2, np.nan])
+    
+    [1, 2, ]
+    Length: 3, dtype: Int64
+
+    >>> pd.array([1.1, 2.2])
+    
+    [1.1, 2.2]
+    Length: 2, dtype: Float64
+
+    >>> pd.array(["a", None, "c"])
+    
+    ['a', , 'c']
+    Length: 3, dtype: string
+
+    >>> with pd.option_context("string_storage", "pyarrow"):
+    ...     arr = pd.array(["a", None, "c"])
+    ...
+    >>> arr
+    
+    ['a', , 'c']
+    Length: 3, dtype: string
+
+    >>> pd.array([pd.Period('2000', freq="D"), pd.Period("2000", freq="D")])
+    
+    ['2000-01-01', '2000-01-01']
+    Length: 2, dtype: period[D]
+
+    You can use the string alias for `dtype`
+
+    >>> pd.array(['a', 'b', 'a'], dtype='category')
+    ['a', 'b', 'a']
+    Categories (2, object): ['a', 'b']
+
+    Or specify the actual dtype
+
+    >>> pd.array(['a', 'b', 'a'],
+    ...          dtype=pd.CategoricalDtype(['a', 'b', 'c'], ordered=True))
+    ['a', 'b', 'a']
+    Categories (3, object): ['a' < 'b' < 'c']
+
+    If pandas does not infer a dedicated extension type a
+    :class:`arrays.NumpyExtensionArray` is returned.
+
+    >>> pd.array([1 + 1j, 3 + 2j])
+    
+    [(1+1j), (3+2j)]
+    Length: 2, dtype: complex128
+
+    As mentioned in the "Notes" section, new extension types may be added
+    in the future (by pandas or 3rd party libraries), causing the return
+    value to no longer be a :class:`arrays.NumpyExtensionArray`. Specify the
+    `dtype` as a NumPy dtype if you need to ensure there's no future change in
+    behavior.
+
+    >>> pd.array([1, 2], dtype=np.dtype("int32"))
+    
+    [1, 2]
+    Length: 2, dtype: int32
+
+    `data` must be 1-dimensional. A ValueError is raised when the input
+    has the wrong dimensionality.
+
+    >>> pd.array(1)
+    Traceback (most recent call last):
+      ...
+    ValueError: Cannot pass scalar '1' to 'pandas.array'.
+    """
+    from pandas.core.arrays import (
+        BooleanArray,
+        DatetimeArray,
+        ExtensionArray,
+        FloatingArray,
+        IntegerArray,
+        IntervalArray,
+        NumpyExtensionArray,
+        PeriodArray,
+        TimedeltaArray,
+    )
+    from pandas.core.arrays.string_ import StringDtype
+
+    if lib.is_scalar(data):
+        msg = f"Cannot pass scalar '{data}' to 'pandas.array'."
+        raise ValueError(msg)
+    elif isinstance(data, ABCDataFrame):
+        raise TypeError("Cannot pass DataFrame to 'pandas.array'")
+
+    if dtype is None and isinstance(data, (ABCSeries, ABCIndex, ExtensionArray)):
+        # Note: we exclude np.ndarray here, will do type inference on it
+        dtype = data.dtype
+
+    data = extract_array(data, extract_numpy=True)
+
+    # this returns None for not-found dtypes.
+    if dtype is not None:
+        dtype = pandas_dtype(dtype)
+
+    if isinstance(data, ExtensionArray) and (dtype is None or data.dtype == dtype):
+        # e.g. TimedeltaArray[s], avoid casting to NumpyExtensionArray
+        if copy:
+            return data.copy()
+        return data
+
+    if isinstance(dtype, ExtensionDtype):
+        cls = dtype.construct_array_type()
+        return cls._from_sequence(data, dtype=dtype, copy=copy)
+
+    if dtype is None:
+        inferred_dtype = lib.infer_dtype(data, skipna=True)
+        if inferred_dtype == "period":
+            period_data = cast(Union[Sequence[Optional[Period]], AnyArrayLike], data)
+            return PeriodArray._from_sequence(period_data, copy=copy)
+
+        elif inferred_dtype == "interval":
+            return IntervalArray(data, copy=copy)
+
+        elif inferred_dtype.startswith("datetime"):
+            # datetime, datetime64
+            try:
+                return DatetimeArray._from_sequence(data, copy=copy)
+            except ValueError:
+                # Mixture of timezones, fall back to NumpyExtensionArray
+                pass
+
+        elif inferred_dtype.startswith("timedelta"):
+            # timedelta, timedelta64
+            return TimedeltaArray._from_sequence(data, copy=copy)
+
+        elif inferred_dtype == "string":
+            # StringArray/ArrowStringArray depending on pd.options.mode.string_storage
+            dtype = StringDtype()
+            cls = dtype.construct_array_type()
+            return cls._from_sequence(data, dtype=dtype, copy=copy)
+
+        elif inferred_dtype == "integer":
+            return IntegerArray._from_sequence(data, copy=copy)
+        elif inferred_dtype == "empty" and not hasattr(data, "dtype") and not len(data):
+            return FloatingArray._from_sequence(data, copy=copy)
+        elif (
+            inferred_dtype in ("floating", "mixed-integer-float")
+            and getattr(data, "dtype", None) != np.float16
+        ):
+            # GH#44715 Exclude np.float16 bc FloatingArray does not support it;
+            #  we will fall back to NumpyExtensionArray.
+            return FloatingArray._from_sequence(data, copy=copy)
+
+        elif inferred_dtype == "boolean":
+            return BooleanArray._from_sequence(data, dtype="boolean", copy=copy)
+
+    # Pandas overrides NumPy for
+    #   1. datetime64[ns,us,ms,s]
+    #   2. timedelta64[ns,us,ms,s]
+    # so that a DatetimeArray is returned.
+    if lib.is_np_dtype(dtype, "M") and is_supported_dtype(dtype):
+        return DatetimeArray._from_sequence(data, dtype=dtype, copy=copy)
+    if lib.is_np_dtype(dtype, "m") and is_supported_dtype(dtype):
+        return TimedeltaArray._from_sequence(data, dtype=dtype, copy=copy)
+
+    elif lib.is_np_dtype(dtype, "mM"):
+        warnings.warn(
+            r"datetime64 and timedelta64 dtype resolutions other than "
+            r"'s', 'ms', 'us', and 'ns' are deprecated. "
+            r"In future releases passing unsupported resolutions will "
+            r"raise an exception.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    return NumpyExtensionArray._from_sequence(data, dtype=dtype, copy=copy)
+
+
+_typs = frozenset(
+    {
+        "index",
+        "rangeindex",
+        "multiindex",
+        "datetimeindex",
+        "timedeltaindex",
+        "periodindex",
+        "categoricalindex",
+        "intervalindex",
+        "series",
+    }
+)
+
+
+@overload
+def extract_array(
+    obj: Series | Index, extract_numpy: bool = ..., extract_range: bool = ...
+) -> ArrayLike:
+    ...
+
+
+@overload
+def extract_array(
+    obj: T, extract_numpy: bool = ..., extract_range: bool = ...
+) -> T | ArrayLike:
+    ...
+
+
+def extract_array(
+    obj: T, extract_numpy: bool = False, extract_range: bool = False
+) -> T | ArrayLike:
+    """
+    Extract the ndarray or ExtensionArray from a Series or Index.
+
+    For all other types, `obj` is just returned as is.
+
+    Parameters
+    ----------
+    obj : object
+        For Series / Index, the underlying ExtensionArray is unboxed.
+
+    extract_numpy : bool, default False
+        Whether to extract the ndarray from a NumpyExtensionArray.
+
+    extract_range : bool, default False
+        If we have a RangeIndex, return range._values if True
+        (which is a materialized integer ndarray), otherwise return unchanged.
+
+    Returns
+    -------
+    arr : object
+
+    Examples
+    --------
+    >>> extract_array(pd.Series(['a', 'b', 'c'], dtype='category'))
+    ['a', 'b', 'c']
+    Categories (3, object): ['a', 'b', 'c']
+
+    Other objects like lists, arrays, and DataFrames are just passed through.
+
+    >>> extract_array([1, 2, 3])
+    [1, 2, 3]
+
+    For an ndarray-backed Series / Index the ndarray is returned.
+
+    >>> extract_array(pd.Series([1, 2, 3]))
+    array([1, 2, 3])
+
+    To extract all the way down to the ndarray, pass ``extract_numpy=True``.
+
+    >>> extract_array(pd.Series([1, 2, 3]), extract_numpy=True)
+    array([1, 2, 3])
+    """
+    typ = getattr(obj, "_typ", None)
+    if typ in _typs:
+        # i.e. isinstance(obj, (ABCIndex, ABCSeries))
+        if typ == "rangeindex":
+            if extract_range:
+                # error: "T" has no attribute "_values"
+                return obj._values  # type: ignore[attr-defined]
+            return obj
+
+        # error: "T" has no attribute "_values"
+        return obj._values  # type: ignore[attr-defined]
+
+    elif extract_numpy and typ == "npy_extension":
+        # i.e. isinstance(obj, ABCNumpyExtensionArray)
+        # error: "T" has no attribute "to_numpy"
+        return obj.to_numpy()  # type: ignore[attr-defined]
+
+    return obj
+
+
+def ensure_wrapped_if_datetimelike(arr):
+    """
+    Wrap datetime64 and timedelta64 ndarrays in DatetimeArray/TimedeltaArray.
+    """
+    if isinstance(arr, np.ndarray):
+        if arr.dtype.kind == "M":
+            from pandas.core.arrays import DatetimeArray
+
+            dtype = get_supported_dtype(arr.dtype)
+            return DatetimeArray._from_sequence(arr, dtype=dtype)
+
+        elif arr.dtype.kind == "m":
+            from pandas.core.arrays import TimedeltaArray
+
+            dtype = get_supported_dtype(arr.dtype)
+            return TimedeltaArray._from_sequence(arr, dtype=dtype)
+
+    return arr
+
+
+def sanitize_masked_array(data: ma.MaskedArray) -> np.ndarray:
+    """
+    Convert numpy MaskedArray to ensure mask is softened.
+    """
+    mask = ma.getmaskarray(data)
+    if mask.any():
+        dtype, fill_value = maybe_promote(data.dtype, np.nan)
+        dtype = cast(np.dtype, dtype)
+        data = ma.asarray(data.astype(dtype, copy=True))
+        data.soften_mask()  # set hardmask False if it was True
+        data[mask] = fill_value
+    else:
+        data = data.copy()
+    return data
+
+
+def sanitize_array(
+    data,
+    index: Index | None,
+    dtype: DtypeObj | None = None,
+    copy: bool = False,
+    *,
+    allow_2d: bool = False,
+) -> ArrayLike:
+    """
+    Sanitize input data to an ndarray or ExtensionArray, copy if specified,
+    coerce to the dtype if specified.
+
+    Parameters
+    ----------
+    data : Any
+    index : Index or None, default None
+    dtype : np.dtype, ExtensionDtype, or None, default None
+    copy : bool, default False
+    allow_2d : bool, default False
+        If False, raise if we have a 2D Arraylike.
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    original_dtype = dtype
+    if isinstance(data, ma.MaskedArray):
+        data = sanitize_masked_array(data)
+
+    if isinstance(dtype, NumpyEADtype):
+        # Avoid ending up with a NumpyExtensionArray
+        dtype = dtype.numpy_dtype
+
+    object_index = False
+    if isinstance(data, ABCIndex) and data.dtype == object and dtype is None:
+        object_index = True
+
+    # extract ndarray or ExtensionArray, ensure we have no NumpyExtensionArray
+    data = extract_array(data, extract_numpy=True, extract_range=True)
+
+    if isinstance(data, np.ndarray) and data.ndim == 0:
+        if dtype is None:
+            dtype = data.dtype
+        data = lib.item_from_zerodim(data)
+    elif isinstance(data, range):
+        # GH#16804
+        data = range_to_ndarray(data)
+        copy = False
+
+    if not is_list_like(data):
+        if index is None:
+            raise ValueError("index must be specified when data is not list-like")
+        if isinstance(data, str) and using_string_dtype() and original_dtype is None:
+            from pandas.core.arrays.string_ import StringDtype
+
+            dtype = StringDtype(na_value=np.nan)
+        data = construct_1d_arraylike_from_scalar(data, len(index), dtype)
+
+        return data
+
+    elif isinstance(data, ABCExtensionArray):
+        # it is already ensured above this is not a NumpyExtensionArray
+        # Until GH#49309 is fixed this check needs to come before the
+        #  ExtensionDtype check
+        if dtype is not None:
+            subarr = data.astype(dtype, copy=copy)
+        elif copy:
+            subarr = data.copy()
+        else:
+            subarr = data
+
+    elif isinstance(dtype, ExtensionDtype):
+        # create an extension array from its dtype
+        _sanitize_non_ordered(data)
+        cls = dtype.construct_array_type()
+        if not hasattr(data, "__array__"):
+            data = list(data)
+        subarr = cls._from_sequence(data, dtype=dtype, copy=copy)
+
+    # GH#846
+    elif isinstance(data, np.ndarray):
+        if isinstance(data, np.matrix):
+            data = data.A
+
+        if dtype is None:
+            subarr = data
+            if data.dtype == object:
+                subarr = maybe_infer_to_datetimelike(data)
+                if object_index and using_string_dtype() and is_string_dtype(subarr):
+                    # Avoid inference when string option is set
+                    subarr = data
+            elif data.dtype.kind == "U" and using_string_dtype():
+                from pandas.core.arrays.string_ import StringDtype
+
+                dtype = StringDtype(na_value=np.nan)
+                subarr = dtype.construct_array_type()._from_sequence(data, dtype=dtype)
+
+            if (
+                subarr is data
+                or (subarr.dtype == "str" and subarr.dtype.storage == "python")  # type: ignore[union-attr]
+            ) and copy:
+                subarr = subarr.copy()
+
+        else:
+            # we will try to copy by-definition here
+            subarr = _try_cast(data, dtype, copy)
+
+    elif hasattr(data, "__array__"):
+        # e.g. dask array GH#38645
+        if not copy:
+            data = np.asarray(data)
+        else:
+            data = np.array(data, copy=copy)
+        return sanitize_array(
+            data,
+            index=index,
+            dtype=dtype,
+            copy=False,
+            allow_2d=allow_2d,
+        )
+
+    else:
+        _sanitize_non_ordered(data)
+        # materialize e.g. generators, convert e.g. tuples, abc.ValueView
+        data = list(data)
+
+        if len(data) == 0 and dtype is None:
+            # We default to float64, matching numpy
+            subarr = np.array([], dtype=np.float64)
+
+        elif dtype is not None:
+            subarr = _try_cast(data, dtype, copy)
+
+        else:
+            subarr = maybe_convert_platform(data)
+            if subarr.dtype == object:
+                subarr = cast(np.ndarray, subarr)
+                subarr = maybe_infer_to_datetimelike(subarr)
+
+    subarr = _sanitize_ndim(subarr, data, dtype, index, allow_2d=allow_2d)
+
+    if isinstance(subarr, np.ndarray):
+        # at this point we should have dtype be None or subarr.dtype == dtype
+        dtype = cast(np.dtype, dtype)
+        subarr = _sanitize_str_dtypes(subarr, data, dtype, copy)
+
+    return subarr
+
+
+def range_to_ndarray(rng: range) -> np.ndarray:
+    """
+    Cast a range object to ndarray.
+    """
+    # GH#30171 perf avoid realizing range as a list in np.array
+    try:
+        arr = np.arange(rng.start, rng.stop, rng.step, dtype="int64")
+    except OverflowError:
+        # GH#30173 handling for ranges that overflow int64
+        if (rng.start >= 0 and rng.step > 0) or (rng.step < 0 <= rng.stop):
+            try:
+                arr = np.arange(rng.start, rng.stop, rng.step, dtype="uint64")
+            except OverflowError:
+                arr = construct_1d_object_array_from_listlike(list(rng))
+        else:
+            arr = construct_1d_object_array_from_listlike(list(rng))
+    return arr
+
+
+def _sanitize_non_ordered(data) -> None:
+    """
+    Raise only for unordered sets, e.g., not for dict_keys
+    """
+    if isinstance(data, (set, frozenset)):
+        raise TypeError(f"'{type(data).__name__}' type is unordered")
+
+
+def _sanitize_ndim(
+    result: ArrayLike,
+    data,
+    dtype: DtypeObj | None,
+    index: Index | None,
+    *,
+    allow_2d: bool = False,
+) -> ArrayLike:
+    """
+    Ensure we have a 1-dimensional result array.
+    """
+    if getattr(result, "ndim", 0) == 0:
+        raise ValueError("result should be arraylike with ndim > 0")
+
+    if result.ndim == 1:
+        # the result that we want
+        result = _maybe_repeat(result, index)
+
+    elif result.ndim > 1:
+        if isinstance(data, np.ndarray):
+            if allow_2d:
+                return result
+            raise ValueError(
+                f"Data must be 1-dimensional, got ndarray of shape {data.shape} instead"
+            )
+        if is_object_dtype(dtype) and isinstance(dtype, ExtensionDtype):
+            # i.e. NumpyEADtype("O")
+
+            result = com.asarray_tuplesafe(data, dtype=np.dtype("object"))
+            cls = dtype.construct_array_type()
+            result = cls._from_sequence(result, dtype=dtype)
+        else:
+            # error: Argument "dtype" to "asarray_tuplesafe" has incompatible type
+            # "Union[dtype[Any], ExtensionDtype, None]"; expected "Union[str,
+            # dtype[Any], None]"
+            result = com.asarray_tuplesafe(data, dtype=dtype)  # type: ignore[arg-type]
+    return result
+
+
+def _sanitize_str_dtypes(
+    result: np.ndarray, data, dtype: np.dtype | None, copy: bool
+) -> np.ndarray:
+    """
+    Ensure we have a dtype that is supported by pandas.
+    """
+
+    # This is to prevent mixed-type Series getting all casted to
+    # NumPy string type, e.g. NaN --> '-1#IND'.
+    if issubclass(result.dtype.type, str):
+        # GH#16605
+        # If not empty convert the data to dtype
+        # GH#19853: If data is a scalar, result has already the result
+        if not lib.is_scalar(data):
+            if not np.all(isna(data)):
+                data = np.asarray(data, dtype=dtype)
+            if not copy:
+                result = np.asarray(data, dtype=object)
+            else:
+                result = np.array(data, dtype=object, copy=copy)
+    return result
+
+
+def _maybe_repeat(arr: ArrayLike, index: Index | None) -> ArrayLike:
+    """
+    If we have a length-1 array and an index describing how long we expect
+    the result to be, repeat the array.
+    """
+    if index is not None:
+        if 1 == len(arr) != len(index):
+            arr = arr.repeat(len(index))
+    return arr
+
+
+def _try_cast(
+    arr: list | np.ndarray,
+    dtype: np.dtype,
+    copy: bool,
+) -> ArrayLike:
+    """
+    Convert input to numpy ndarray and optionally cast to a given dtype.
+
+    Parameters
+    ----------
+    arr : ndarray or list
+        Excludes: ExtensionArray, Series, Index.
+    dtype : np.dtype
+    copy : bool
+        If False, don't copy the data if not needed.
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    is_ndarray = isinstance(arr, np.ndarray)
+
+    if dtype == object:
+        if not is_ndarray:
+            subarr = construct_1d_object_array_from_listlike(arr)
+            return subarr
+        return ensure_wrapped_if_datetimelike(arr).astype(dtype, copy=copy)
+
+    elif dtype.kind == "U":
+        # TODO: test cases with arr.dtype.kind in "mM"
+        if is_ndarray:
+            arr = cast(np.ndarray, arr)
+            shape = arr.shape
+            if arr.ndim > 1:
+                arr = arr.ravel()
+        else:
+            shape = (len(arr),)
+        return lib.ensure_string_array(arr, convert_na_value=False, copy=copy).reshape(
+            shape
+        )
+
+    elif dtype.kind in "mM":
+        return maybe_cast_to_datetime(arr, dtype)
+
+    # GH#15832: Check if we are requesting a numeric dtype and
+    # that we can convert the data to the requested dtype.
+    elif dtype.kind in "iu":
+        # this will raise if we have e.g. floats
+
+        subarr = maybe_cast_to_integer_array(arr, dtype)
+    elif not copy:
+        subarr = np.asarray(arr, dtype=dtype)
+    else:
+        subarr = np.array(arr, dtype=dtype, copy=copy)
+
+    return subarr
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/api.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..254abe330b8e7229d0c2a27519e82efbe902c537
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/api.py
@@ -0,0 +1,85 @@
+from pandas.core.dtypes.common import (
+    is_any_real_numeric_dtype,
+    is_array_like,
+    is_bool,
+    is_bool_dtype,
+    is_categorical_dtype,
+    is_complex,
+    is_complex_dtype,
+    is_datetime64_any_dtype,
+    is_datetime64_dtype,
+    is_datetime64_ns_dtype,
+    is_datetime64tz_dtype,
+    is_dict_like,
+    is_dtype_equal,
+    is_extension_array_dtype,
+    is_file_like,
+    is_float,
+    is_float_dtype,
+    is_hashable,
+    is_int64_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_interval,
+    is_interval_dtype,
+    is_iterator,
+    is_list_like,
+    is_named_tuple,
+    is_number,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_period_dtype,
+    is_re,
+    is_re_compilable,
+    is_scalar,
+    is_signed_integer_dtype,
+    is_sparse,
+    is_string_dtype,
+    is_timedelta64_dtype,
+    is_timedelta64_ns_dtype,
+    is_unsigned_integer_dtype,
+    pandas_dtype,
+)
+
+__all__ = [
+    "is_any_real_numeric_dtype",
+    "is_array_like",
+    "is_bool",
+    "is_bool_dtype",
+    "is_categorical_dtype",
+    "is_complex",
+    "is_complex_dtype",
+    "is_datetime64_any_dtype",
+    "is_datetime64_dtype",
+    "is_datetime64_ns_dtype",
+    "is_datetime64tz_dtype",
+    "is_dict_like",
+    "is_dtype_equal",
+    "is_extension_array_dtype",
+    "is_file_like",
+    "is_float",
+    "is_float_dtype",
+    "is_hashable",
+    "is_int64_dtype",
+    "is_integer",
+    "is_integer_dtype",
+    "is_interval",
+    "is_interval_dtype",
+    "is_iterator",
+    "is_list_like",
+    "is_named_tuple",
+    "is_number",
+    "is_numeric_dtype",
+    "is_object_dtype",
+    "is_period_dtype",
+    "is_re",
+    "is_re_compilable",
+    "is_scalar",
+    "is_signed_integer_dtype",
+    "is_sparse",
+    "is_string_dtype",
+    "is_timedelta64_dtype",
+    "is_timedelta64_ns_dtype",
+    "is_unsigned_integer_dtype",
+    "pandas_dtype",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/astype.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/astype.py
new file mode 100644
index 0000000000000000000000000000000000000000..f5579082c679bf131c056f3f2029b2485e88bd0d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/astype.py
@@ -0,0 +1,301 @@
+"""
+Functions for implementing 'astype' methods according to pandas conventions,
+particularly ones that differ from numpy.
+"""
+from __future__ import annotations
+
+import inspect
+from typing import (
+    TYPE_CHECKING,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs.timedeltas import array_to_timedelta64
+from pandas.errors import IntCastingNaNError
+
+from pandas.core.dtypes.common import (
+    is_object_dtype,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ExtensionDtype,
+    NumpyEADtype,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        DtypeObj,
+        IgnoreRaise,
+    )
+
+    from pandas.core.arrays import ExtensionArray
+
+_dtype_obj = np.dtype(object)
+
+
+@overload
+def _astype_nansafe(
+    arr: np.ndarray, dtype: np.dtype, copy: bool = ..., skipna: bool = ...
+) -> np.ndarray:
+    ...
+
+
+@overload
+def _astype_nansafe(
+    arr: np.ndarray, dtype: ExtensionDtype, copy: bool = ..., skipna: bool = ...
+) -> ExtensionArray:
+    ...
+
+
+def _astype_nansafe(
+    arr: np.ndarray, dtype: DtypeObj, copy: bool = True, skipna: bool = False
+) -> ArrayLike:
+    """
+    Cast the elements of an array to a given dtype a nan-safe manner.
+
+    Parameters
+    ----------
+    arr : ndarray
+    dtype : np.dtype or ExtensionDtype
+    copy : bool, default True
+        If False, a view will be attempted but may fail, if
+        e.g. the item sizes don't align.
+    skipna: bool, default False
+        Whether or not we should skip NaN when casting as a string-type.
+
+    Raises
+    ------
+    ValueError
+        The dtype was a datetime64/timedelta64 dtype, but it had no unit.
+    """
+
+    # dispatch on extension dtype if needed
+    if isinstance(dtype, ExtensionDtype):
+        return dtype.construct_array_type()._from_sequence(arr, dtype=dtype, copy=copy)
+
+    elif not isinstance(dtype, np.dtype):  # pragma: no cover
+        raise ValueError("dtype must be np.dtype or ExtensionDtype")
+
+    if arr.dtype.kind in "mM":
+        from pandas.core.construction import ensure_wrapped_if_datetimelike
+
+        arr = ensure_wrapped_if_datetimelike(arr)
+        res = arr.astype(dtype, copy=copy)
+        return np.asarray(res)
+
+    if issubclass(dtype.type, str):
+        shape = arr.shape
+        if arr.ndim > 1:
+            arr = arr.ravel()
+        return lib.ensure_string_array(
+            arr, skipna=skipna, convert_na_value=False
+        ).reshape(shape)
+
+    elif np.issubdtype(arr.dtype, np.floating) and dtype.kind in "iu":
+        return _astype_float_to_int_nansafe(arr, dtype, copy)
+
+    elif arr.dtype == object:
+        # if we have a datetime/timedelta array of objects
+        # then coerce to datetime64[ns] and use DatetimeArray.astype
+
+        if lib.is_np_dtype(dtype, "M"):
+            from pandas.core.arrays import DatetimeArray
+
+            dta = DatetimeArray._from_sequence(arr, dtype=dtype)
+            return dta._ndarray
+
+        elif lib.is_np_dtype(dtype, "m"):
+            from pandas.core.construction import ensure_wrapped_if_datetimelike
+
+            # bc we know arr.dtype == object, this is equivalent to
+            #  `np.asarray(to_timedelta(arr))`, but using a lower-level API that
+            #  does not require a circular import.
+            tdvals = array_to_timedelta64(arr).view("m8[ns]")
+
+            tda = ensure_wrapped_if_datetimelike(tdvals)
+            return tda.astype(dtype, copy=False)._ndarray
+
+    if dtype.name in ("datetime64", "timedelta64"):
+        msg = (
+            f"The '{dtype.name}' dtype has no unit. Please pass in "
+            f"'{dtype.name}[ns]' instead."
+        )
+        raise ValueError(msg)
+
+    if copy or arr.dtype == object or dtype == object:
+        # Explicit copy, or required since NumPy can't view from / to object.
+        return arr.astype(dtype, copy=True)
+
+    return arr.astype(dtype, copy=copy)
+
+
+def _astype_float_to_int_nansafe(
+    values: np.ndarray, dtype: np.dtype, copy: bool
+) -> np.ndarray:
+    """
+    astype with a check preventing converting NaN to an meaningless integer value.
+    """
+    if not np.isfinite(values).all():
+        raise IntCastingNaNError(
+            "Cannot convert non-finite values (NA or inf) to integer"
+        )
+    if dtype.kind == "u":
+        # GH#45151
+        if not (values >= 0).all():
+            raise ValueError(f"Cannot losslessly cast from {values.dtype} to {dtype}")
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning)
+        return values.astype(dtype, copy=copy)
+
+
+def astype_array(values: ArrayLike, dtype: DtypeObj, copy: bool = False) -> ArrayLike:
+    """
+    Cast array (ndarray or ExtensionArray) to the new dtype.
+
+    Parameters
+    ----------
+    values : ndarray or ExtensionArray
+    dtype : dtype object
+    copy : bool, default False
+        copy if indicated
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+    if values.dtype == dtype:
+        if copy:
+            return values.copy()
+        return values
+
+    if not isinstance(values, np.ndarray):
+        # i.e. ExtensionArray
+        values = values.astype(dtype, copy=copy)
+
+    else:
+        values = _astype_nansafe(values, dtype, copy=copy)
+
+    # in pandas we don't store numpy str dtypes, so convert to object
+    if isinstance(dtype, np.dtype) and issubclass(values.dtype.type, str):
+        values = np.array(values, dtype=object)
+
+    return values
+
+
+def astype_array_safe(
+    values: ArrayLike, dtype, copy: bool = False, errors: IgnoreRaise = "raise"
+) -> ArrayLike:
+    """
+    Cast array (ndarray or ExtensionArray) to the new dtype.
+
+    This basically is the implementation for DataFrame/Series.astype and
+    includes all custom logic for pandas (NaN-safety, converting str to object,
+    not allowing )
+
+    Parameters
+    ----------
+    values : ndarray or ExtensionArray
+    dtype : str, dtype convertible
+    copy : bool, default False
+        copy if indicated
+    errors : str, {'raise', 'ignore'}, default 'raise'
+        - ``raise`` : allow exceptions to be raised
+        - ``ignore`` : suppress exceptions. On error return original object
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+    errors_legal_values = ("raise", "ignore")
+
+    if errors not in errors_legal_values:
+        invalid_arg = (
+            "Expected value of kwarg 'errors' to be one of "
+            f"{list(errors_legal_values)}. Supplied value is '{errors}'"
+        )
+        raise ValueError(invalid_arg)
+
+    if inspect.isclass(dtype) and issubclass(dtype, ExtensionDtype):
+        msg = (
+            f"Expected an instance of {dtype.__name__}, "
+            "but got the class instead. Try instantiating 'dtype'."
+        )
+        raise TypeError(msg)
+
+    dtype = pandas_dtype(dtype)
+    if isinstance(dtype, NumpyEADtype):
+        # Ensure we don't end up with a NumpyExtensionArray
+        dtype = dtype.numpy_dtype
+
+    try:
+        new_values = astype_array(values, dtype, copy=copy)
+    except (ValueError, TypeError):
+        # e.g. _astype_nansafe can fail on object-dtype of strings
+        #  trying to convert to float
+        if errors == "ignore":
+            new_values = values
+        else:
+            raise
+
+    return new_values
+
+
+def astype_is_view(dtype: DtypeObj, new_dtype: DtypeObj) -> bool:
+    """Checks if astype avoided copying the data.
+
+    Parameters
+    ----------
+    dtype : Original dtype
+    new_dtype : target dtype
+
+    Returns
+    -------
+    True if new data is a view or not guaranteed to be a copy, False otherwise
+    """
+    if isinstance(dtype, np.dtype) and not isinstance(new_dtype, np.dtype):
+        new_dtype, dtype = dtype, new_dtype
+
+    if dtype == new_dtype:
+        return True
+
+    elif isinstance(dtype, np.dtype) and isinstance(new_dtype, np.dtype):
+        # Only equal numpy dtypes avoid a copy
+        return False
+
+    elif is_string_dtype(dtype) and is_string_dtype(new_dtype):
+        # Potentially! a view when converting from object to string
+        return True
+
+    elif is_object_dtype(dtype) and new_dtype.kind == "O":
+        # When the underlying array has dtype object, we don't have to make a copy
+        return True
+
+    elif dtype.kind in "mM" and new_dtype.kind in "mM":
+        dtype = getattr(dtype, "numpy_dtype", dtype)
+        new_dtype = getattr(new_dtype, "numpy_dtype", new_dtype)
+        return getattr(dtype, "unit", None) == getattr(new_dtype, "unit", None)
+
+    numpy_dtype = getattr(dtype, "numpy_dtype", None)
+    new_numpy_dtype = getattr(new_dtype, "numpy_dtype", None)
+
+    if numpy_dtype is None and isinstance(dtype, np.dtype):
+        numpy_dtype = dtype
+
+    if new_numpy_dtype is None and isinstance(new_dtype, np.dtype):
+        new_numpy_dtype = new_dtype
+
+    if numpy_dtype is not None and new_numpy_dtype is not None:
+        # if both have NumPy dtype or one of them is a numpy dtype
+        # they are only a view when the numpy dtypes are equal, e.g.
+        # int64 -> Int64 or int64[pyarrow]
+        # int64 -> Int32 copies
+        return numpy_dtype == new_numpy_dtype
+
+    # Assume this is a view since we don't know for sure if a copy was made
+    return True
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/base.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..6b00a5284ec5b18809e233e9ef89e31771ac651e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/base.py
@@ -0,0 +1,583 @@
+"""
+Extend pandas with custom array types.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs import missing as libmissing
+from pandas._libs.hashtable import object_hash
+from pandas._libs.properties import cache_readonly
+from pandas.errors import AbstractMethodError
+
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DtypeObj,
+        Self,
+        Shape,
+        npt,
+        type_t,
+    )
+
+    from pandas import Index
+    from pandas.core.arrays import ExtensionArray
+
+    # To parameterize on same ExtensionDtype
+    ExtensionDtypeT = TypeVar("ExtensionDtypeT", bound="ExtensionDtype")
+
+
+class ExtensionDtype:
+    """
+    A custom data type, to be paired with an ExtensionArray.
+
+    See Also
+    --------
+    extensions.register_extension_dtype: Register an ExtensionType
+        with pandas as class decorator.
+    extensions.ExtensionArray: Abstract base class for custom 1-D array types.
+
+    Notes
+    -----
+    The interface includes the following abstract methods that must
+    be implemented by subclasses:
+
+    * type
+    * name
+    * construct_array_type
+
+    The following attributes and methods influence the behavior of the dtype in
+    pandas operations
+
+    * _is_numeric
+    * _is_boolean
+    * _get_common_dtype
+
+    The `na_value` class attribute can be used to set the default NA value
+    for this type. :attr:`numpy.nan` is used by default.
+
+    ExtensionDtypes are required to be hashable. The base class provides
+    a default implementation, which relies on the ``_metadata`` class
+    attribute. ``_metadata`` should be a tuple containing the strings
+    that define your data type. For example, with ``PeriodDtype`` that's
+    the ``freq`` attribute.
+
+    **If you have a parametrized dtype you should set the ``_metadata``
+    class property**.
+
+    Ideally, the attributes in ``_metadata`` will match the
+    parameters to your ``ExtensionDtype.__init__`` (if any). If any of
+    the attributes in ``_metadata`` don't implement the standard
+    ``__eq__`` or ``__hash__``, the default implementations here will not
+    work.
+
+    Examples
+    --------
+
+    For interaction with Apache Arrow (pyarrow), a ``__from_arrow__`` method
+    can be implemented: 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:
+
+    >>> import pyarrow
+    >>> from pandas.api.extensions import ExtensionArray
+    >>> class ExtensionDtype:
+    ...     def __from_arrow__(
+    ...         self,
+    ...         array: pyarrow.Array | pyarrow.ChunkedArray
+    ...     ) -> ExtensionArray:
+    ...         ...
+
+    This class does not inherit from 'abc.ABCMeta' for performance reasons.
+    Methods and properties required by the interface raise
+    ``pandas.errors.AbstractMethodError`` and no ``register`` method is
+    provided for registering virtual subclasses.
+    """
+
+    _metadata: tuple[str, ...] = ()
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Check whether 'other' is equal to self.
+
+        By default, 'other' is considered equal if either
+
+        * it's a string matching 'self.name'.
+        * it's an instance of this type and all of the attributes
+          in ``self._metadata`` are equal between `self` and `other`.
+
+        Parameters
+        ----------
+        other : Any
+
+        Returns
+        -------
+        bool
+        """
+        if isinstance(other, str):
+            try:
+                other = self.construct_from_string(other)
+            except TypeError:
+                return False
+        if isinstance(other, type(self)):
+            return all(
+                getattr(self, attr) == getattr(other, attr) for attr in self._metadata
+            )
+        return False
+
+    def __hash__(self) -> int:
+        # for python>=3.10, different nan objects have different hashes
+        # we need to avoid that and thus use hash function with old behavior
+        return object_hash(tuple(getattr(self, attr) for attr in self._metadata))
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+    @property
+    def na_value(self) -> object:
+        """
+        Default NA value to use for this type.
+
+        This is used in e.g. ExtensionArray.take. This should be the
+        user-facing "boxed" version of the NA value, not the physical NA value
+        for storage.  e.g. for JSONArray, this is an empty dictionary.
+        """
+        return np.nan
+
+    @property
+    def type(self) -> type_t[Any]:
+        """
+        The scalar type for the array, e.g. ``int``
+
+        It's expected ``ExtensionArray[item]`` returns an instance
+        of ``ExtensionDtype.type`` for scalar ``item``, assuming
+        that value is valid (not NA). NA values do not need to be
+        instances of `type`.
+        """
+        raise AbstractMethodError(self)
+
+    @property
+    def kind(self) -> str:
+        """
+        A character code (one of 'biufcmMOSUV'), default 'O'
+
+        This should match the NumPy dtype used when the array is
+        converted to an ndarray, which is probably 'O' for object if
+        the extension type cannot be represented as a built-in NumPy
+        type.
+
+        See Also
+        --------
+        numpy.dtype.kind
+        """
+        return "O"
+
+    @property
+    def name(self) -> str:
+        """
+        A string identifying the data type.
+
+        Will be used for display in, e.g. ``Series.dtype``
+        """
+        raise AbstractMethodError(self)
+
+    @property
+    def names(self) -> list[str] | None:
+        """
+        Ordered list of field names, or None if there are no fields.
+
+        This is for compatibility with NumPy arrays, and may be removed in the
+        future.
+        """
+        return None
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[ExtensionArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        raise AbstractMethodError(cls)
+
+    def empty(self, shape: Shape) -> ExtensionArray:
+        """
+        Construct an ExtensionArray of this dtype with the given shape.
+
+        Analogous to numpy.empty.
+
+        Parameters
+        ----------
+        shape : int or tuple[int]
+
+        Returns
+        -------
+        ExtensionArray
+        """
+        cls = self.construct_array_type()
+        return cls._empty(shape, dtype=self)
+
+    @classmethod
+    def construct_from_string(cls, string: str) -> Self:
+        r"""
+        Construct this type from a string.
+
+        This is useful mainly for data types that accept parameters.
+        For example, a period dtype accepts a frequency parameter that
+        can be set as ``period[h]`` (where H means hourly frequency).
+
+        By default, in the abstract class, just the name of the type is
+        expected. But subclasses can overwrite this method to accept
+        parameters.
+
+        Parameters
+        ----------
+        string : str
+            The name of the type, for example ``category``.
+
+        Returns
+        -------
+        ExtensionDtype
+            Instance of the dtype.
+
+        Raises
+        ------
+        TypeError
+            If a class cannot be constructed from this 'string'.
+
+        Examples
+        --------
+        For extension dtypes with arguments the following may be an
+        adequate implementation.
+
+        >>> import re
+        >>> @classmethod
+        ... def construct_from_string(cls, string):
+        ...     pattern = re.compile(r"^my_type\[(?P.+)\]$")
+        ...     match = pattern.match(string)
+        ...     if match:
+        ...         return cls(**match.groupdict())
+        ...     else:
+        ...         raise TypeError(
+        ...             f"Cannot construct a '{cls.__name__}' from '{string}'"
+        ...         )
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+        # error: Non-overlapping equality check (left operand type: "str", right
+        #  operand type: "Callable[[ExtensionDtype], str]")  [comparison-overlap]
+        assert isinstance(cls.name, str), (cls, type(cls.name))
+        if string != cls.name:
+            raise TypeError(f"Cannot construct a '{cls.__name__}' from '{string}'")
+        return cls()
+
+    @classmethod
+    def is_dtype(cls, dtype: object) -> bool:
+        """
+        Check if we match 'dtype'.
+
+        Parameters
+        ----------
+        dtype : object
+            The object to check.
+
+        Returns
+        -------
+        bool
+
+        Notes
+        -----
+        The default implementation is True if
+
+        1. ``cls.construct_from_string(dtype)`` is an instance
+           of ``cls``.
+        2. ``dtype`` is an object and is an instance of ``cls``
+        3. ``dtype`` has a ``dtype`` attribute, and any of the above
+           conditions is true for ``dtype.dtype``.
+        """
+        dtype = getattr(dtype, "dtype", dtype)
+
+        if isinstance(dtype, (ABCSeries, ABCIndex, ABCDataFrame, np.dtype)):
+            # https://github.com/pandas-dev/pandas/issues/22960
+            # avoid passing data to `construct_from_string`. This could
+            # cause a FutureWarning from numpy about failing elementwise
+            # comparison from, e.g., comparing DataFrame == 'category'.
+            return False
+        elif dtype is None:
+            return False
+        elif isinstance(dtype, cls):
+            return True
+        if isinstance(dtype, str):
+            try:
+                return cls.construct_from_string(dtype) is not None
+            except TypeError:
+                return False
+        return False
+
+    @property
+    def _is_numeric(self) -> bool:
+        """
+        Whether columns with this dtype should be considered numeric.
+
+        By default ExtensionDtypes are assumed to be non-numeric.
+        They'll be excluded from operations that exclude non-numeric
+        columns, like (groupby) reductions, plotting, etc.
+        """
+        return False
+
+    @property
+    def _is_boolean(self) -> bool:
+        """
+        Whether this dtype should be considered boolean.
+
+        By default, ExtensionDtypes are assumed to be non-numeric.
+        Setting this to True will affect the behavior of several places,
+        e.g.
+
+        * is_bool
+        * boolean indexing
+
+        Returns
+        -------
+        bool
+        """
+        return False
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        """
+        Return the common dtype, if one exists.
+
+        Used in `find_common_type` implementation. This is for example used
+        to determine the resulting dtype in a concat operation.
+
+        If no common dtype exists, return None (which gives the other dtypes
+        the chance to determine a common dtype). If all dtypes in the list
+        return None, then the common dtype will be "object" dtype (this means
+        it is never needed to return "object" dtype from this method itself).
+
+        Parameters
+        ----------
+        dtypes : list of dtypes
+            The dtypes for which to determine a common dtype. This is a list
+            of np.dtype or ExtensionDtype instances.
+
+        Returns
+        -------
+        Common dtype (np.dtype or ExtensionDtype) or None
+        """
+        if len(set(dtypes)) == 1:
+            # only itself
+            return self
+        else:
+            return None
+
+    @property
+    def _can_hold_na(self) -> bool:
+        """
+        Can arrays of this dtype hold NA values?
+        """
+        return True
+
+    @property
+    def _is_immutable(self) -> bool:
+        """
+        Can arrays with this dtype be modified with __setitem__? If not, return
+        True.
+
+        Immutable arrays are expected to raise TypeError on __setitem__ calls.
+        """
+        return False
+
+    @cache_readonly
+    def index_class(self) -> type_t[Index]:
+        """
+        The Index subclass to return from Index.__new__ when this dtype is
+        encountered.
+        """
+        from pandas import Index
+
+        return Index
+
+    @property
+    def _supports_2d(self) -> bool:
+        """
+        Do ExtensionArrays with this dtype support 2D arrays?
+
+        Historically ExtensionArrays were limited to 1D. By returning True here,
+        authors can indicate that their arrays support 2D instances. This can
+        improve performance in some cases, particularly operations with `axis=1`.
+
+        Arrays that support 2D values should:
+
+            - implement Array.reshape
+            - subclass the Dim2CompatTests in tests.extension.base
+            - _concat_same_type should support `axis` keyword
+            - _reduce and reductions should support `axis` keyword
+        """
+        return False
+
+    @property
+    def _can_fast_transpose(self) -> bool:
+        """
+        Is transposing an array with this dtype zero-copy?
+
+        Only relevant for cases where _supports_2d is True.
+        """
+        return False
+
+
+class StorageExtensionDtype(ExtensionDtype):
+    """ExtensionDtype that may be backed by more than one implementation."""
+
+    name: str
+    _metadata = ("storage",)
+
+    def __init__(self, storage: str | None = None) -> None:
+        self.storage = storage
+
+    def __repr__(self) -> str:
+        return f"{self.name}[{self.storage}]"
+
+    def __str__(self) -> str:
+        return self.name
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str) and other == self.name:
+            return True
+        return super().__eq__(other)
+
+    def __hash__(self) -> int:
+        # custom __eq__ so have to override __hash__
+        return super().__hash__()
+
+    @property
+    def na_value(self) -> libmissing.NAType:
+        return libmissing.NA
+
+
+def register_extension_dtype(cls: type_t[ExtensionDtypeT]) -> type_t[ExtensionDtypeT]:
+    """
+    Register an ExtensionType with pandas as class decorator.
+
+    This enables operations like ``.astype(name)`` for the name
+    of the ExtensionDtype.
+
+    Returns
+    -------
+    callable
+        A class decorator.
+
+    Examples
+    --------
+    >>> from pandas.api.extensions import register_extension_dtype, ExtensionDtype
+    >>> @register_extension_dtype
+    ... class MyExtensionDtype(ExtensionDtype):
+    ...     name = "myextension"
+    """
+    _registry.register(cls)
+    return cls
+
+
+class Registry:
+    """
+    Registry for dtype inference.
+
+    The registry allows one to map a string repr of a extension
+    dtype to an extension dtype. The string alias can be used in several
+    places, including
+
+    * Series and Index constructors
+    * :meth:`pandas.array`
+    * :meth:`pandas.Series.astype`
+
+    Multiple extension types can be registered.
+    These are tried in order.
+    """
+
+    def __init__(self) -> None:
+        self.dtypes: list[type_t[ExtensionDtype]] = []
+
+    def register(self, dtype: type_t[ExtensionDtype]) -> None:
+        """
+        Parameters
+        ----------
+        dtype : ExtensionDtype class
+        """
+        if not issubclass(dtype, ExtensionDtype):
+            raise ValueError("can only register pandas extension dtypes")
+
+        self.dtypes.append(dtype)
+
+    @overload
+    def find(self, dtype: type_t[ExtensionDtypeT]) -> type_t[ExtensionDtypeT]:
+        ...
+
+    @overload
+    def find(self, dtype: ExtensionDtypeT) -> ExtensionDtypeT:
+        ...
+
+    @overload
+    def find(self, dtype: str) -> ExtensionDtype | None:
+        ...
+
+    @overload
+    def find(
+        self, dtype: npt.DTypeLike
+    ) -> type_t[ExtensionDtype] | ExtensionDtype | None:
+        ...
+
+    def find(
+        self, dtype: type_t[ExtensionDtype] | ExtensionDtype | npt.DTypeLike
+    ) -> type_t[ExtensionDtype] | ExtensionDtype | None:
+        """
+        Parameters
+        ----------
+        dtype : ExtensionDtype class or instance or str or numpy dtype or python type
+
+        Returns
+        -------
+        return the first matching dtype, otherwise return None
+        """
+        if not isinstance(dtype, str):
+            dtype_type: type_t
+            if not isinstance(dtype, type):
+                dtype_type = type(dtype)
+            else:
+                dtype_type = dtype
+            if issubclass(dtype_type, ExtensionDtype):
+                # cast needed here as mypy doesn't know we have figured
+                # out it is an ExtensionDtype or type_t[ExtensionDtype]
+                return cast("ExtensionDtype | type_t[ExtensionDtype]", dtype)
+
+            return None
+
+        for dtype_type in self.dtypes:
+            try:
+                return dtype_type.construct_from_string(dtype)
+            except TypeError:
+                pass
+
+        return None
+
+
+_registry = Registry()
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/cast.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/cast.py
new file mode 100644
index 0000000000000000000000000000000000000000..9a7cfc0dec84ee09e1948ee5af885ae6170aae31
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/cast.py
@@ -0,0 +1,1990 @@
+"""
+Routines for casting.
+"""
+
+from __future__ import annotations
+
+import datetime as dt
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    TypeVar,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import (
+    Interval,
+    Period,
+    lib,
+)
+from pandas._libs.missing import (
+    NA,
+    NAType,
+    checknull,
+)
+from pandas._libs.tslibs import (
+    NaT,
+    OutOfBoundsDatetime,
+    OutOfBoundsTimedelta,
+    Timedelta,
+    Timestamp,
+    is_supported_dtype,
+)
+from pandas._libs.tslibs.timedeltas import array_to_timedelta64
+from pandas.errors import (
+    IntCastingNaNError,
+    LossySetitemError,
+)
+
+from pandas.core.dtypes.common import (
+    ensure_int8,
+    ensure_int16,
+    ensure_int32,
+    ensure_int64,
+    ensure_object,
+    ensure_str,
+    is_bool,
+    is_complex,
+    is_float,
+    is_integer,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype as pandas_dtype_func,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    BaseMaskedDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    IntervalDtype,
+    PandasExtensionDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCExtensionArray,
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import is_list_like
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+    na_value_for_dtype,
+    notna,
+)
+
+from pandas.io._util import _arrow_dtype_mapping
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Collection,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        Dtype,
+        DtypeObj,
+        NumpyIndexT,
+        Scalar,
+        npt,
+    )
+
+    from pandas import Index
+    from pandas.core.arrays import (
+        Categorical,
+        DatetimeArray,
+        ExtensionArray,
+        IntervalArray,
+        PeriodArray,
+        TimedeltaArray,
+    )
+
+
+_int8_max = np.iinfo(np.int8).max
+_int16_max = np.iinfo(np.int16).max
+_int32_max = np.iinfo(np.int32).max
+
+_dtype_obj = np.dtype(object)
+
+NumpyArrayT = TypeVar("NumpyArrayT", bound=np.ndarray)
+
+
+def maybe_convert_platform(
+    values: list | tuple | range | np.ndarray | ExtensionArray,
+) -> ArrayLike:
+    """try to do platform conversion, allow ndarray or list here"""
+    arr: ArrayLike
+
+    if isinstance(values, (list, tuple, range)):
+        arr = construct_1d_object_array_from_listlike(values)
+    else:
+        # The caller is responsible for ensuring that we have np.ndarray
+        #  or ExtensionArray here.
+        arr = values
+
+    if arr.dtype == _dtype_obj:
+        arr = cast(np.ndarray, arr)
+        arr = lib.maybe_convert_objects(arr)
+
+    return arr
+
+
+def is_nested_object(obj) -> bool:
+    """
+    return a boolean if we have a nested object, e.g. a Series with 1 or
+    more Series elements
+
+    This may not be necessarily be performant.
+
+    """
+    return bool(
+        isinstance(obj, ABCSeries)
+        and is_object_dtype(obj.dtype)
+        and any(isinstance(v, ABCSeries) for v in obj._values)
+    )
+
+
+def maybe_box_datetimelike(value: Scalar, dtype: Dtype | None = None) -> Scalar:
+    """
+    Cast scalar to Timestamp or Timedelta if scalar is datetime-like
+    and dtype is not object.
+
+    Parameters
+    ----------
+    value : scalar
+    dtype : Dtype, optional
+
+    Returns
+    -------
+    scalar
+    """
+    if dtype == _dtype_obj:
+        pass
+    elif isinstance(value, (np.datetime64, dt.datetime)):
+        value = Timestamp(value)
+    elif isinstance(value, (np.timedelta64, dt.timedelta)):
+        value = Timedelta(value)
+
+    return value
+
+
+def maybe_box_native(value: Scalar | None | NAType) -> Scalar | None | NAType:
+    """
+    If passed a scalar cast the scalar to a python native type.
+
+    Parameters
+    ----------
+    value : scalar or Series
+
+    Returns
+    -------
+    scalar or Series
+    """
+    if is_float(value):
+        value = float(value)
+    elif is_integer(value):
+        value = int(value)
+    elif is_bool(value):
+        value = bool(value)
+    elif isinstance(value, (np.datetime64, np.timedelta64)):
+        value = maybe_box_datetimelike(value)
+    elif value is NA:
+        value = None
+    return value
+
+
+def _maybe_unbox_datetimelike(value: Scalar, dtype: DtypeObj) -> Scalar:
+    """
+    Convert a Timedelta or Timestamp to timedelta64 or datetime64 for setting
+    into a numpy array.  Failing to unbox would risk dropping nanoseconds.
+
+    Notes
+    -----
+    Caller is responsible for checking dtype.kind in "mM"
+    """
+    if is_valid_na_for_dtype(value, dtype):
+        # GH#36541: can't fill array directly with pd.NaT
+        # > np.empty(10, dtype="datetime64[ns]").fill(pd.NaT)
+        # ValueError: cannot convert float NaN to integer
+        value = dtype.type("NaT", "ns")
+    elif isinstance(value, Timestamp):
+        if value.tz is None:
+            value = value.to_datetime64()
+        elif not isinstance(dtype, DatetimeTZDtype):
+            raise TypeError("Cannot unbox tzaware Timestamp to tznaive dtype")
+    elif isinstance(value, Timedelta):
+        value = value.to_timedelta64()
+
+    _disallow_mismatched_datetimelike(value, dtype)
+    return value
+
+
+def _disallow_mismatched_datetimelike(value, dtype: DtypeObj):
+    """
+    numpy allows np.array(dt64values, dtype="timedelta64[ns]") and
+    vice-versa, but we do not want to allow this, so we need to
+    check explicitly
+    """
+    vdtype = getattr(value, "dtype", None)
+    if vdtype is None:
+        return
+    elif (vdtype.kind == "m" and dtype.kind == "M") or (
+        vdtype.kind == "M" and dtype.kind == "m"
+    ):
+        raise TypeError(f"Cannot cast {repr(value)} to {dtype}")
+
+
+@overload
+def maybe_downcast_to_dtype(result: np.ndarray, dtype: str | np.dtype) -> np.ndarray:
+    ...
+
+
+@overload
+def maybe_downcast_to_dtype(result: ExtensionArray, dtype: str | np.dtype) -> ArrayLike:
+    ...
+
+
+def maybe_downcast_to_dtype(result: ArrayLike, dtype: str | np.dtype) -> ArrayLike:
+    """
+    try to cast to the specified dtype (e.g. convert back to bool/int
+    or could be an astype of float64->float32
+    """
+    if isinstance(result, ABCSeries):
+        result = result._values
+    do_round = False
+
+    if isinstance(dtype, str):
+        if dtype == "infer":
+            inferred_type = lib.infer_dtype(result, skipna=False)
+            if inferred_type == "boolean":
+                dtype = "bool"
+            elif inferred_type == "integer":
+                dtype = "int64"
+            elif inferred_type == "datetime64":
+                dtype = "datetime64[ns]"
+            elif inferred_type in ["timedelta", "timedelta64"]:
+                dtype = "timedelta64[ns]"
+
+            # try to upcast here
+            elif inferred_type == "floating":
+                dtype = "int64"
+                if issubclass(result.dtype.type, np.number):
+                    do_round = True
+
+            else:
+                # TODO: complex?  what if result is already non-object?
+                dtype = "object"
+
+        dtype = np.dtype(dtype)
+
+    if not isinstance(dtype, np.dtype):
+        # enforce our signature annotation
+        raise TypeError(dtype)  # pragma: no cover
+
+    converted = maybe_downcast_numeric(result, dtype, do_round)
+    if converted is not result:
+        return converted
+
+    # a datetimelike
+    # GH12821, iNaT is cast to float
+    if dtype.kind in "mM" and result.dtype.kind in "if":
+        result = result.astype(dtype)
+
+    elif dtype.kind == "m" and result.dtype == _dtype_obj:
+        # test_where_downcast_to_td64
+        result = cast(np.ndarray, result)
+        result = array_to_timedelta64(result)
+
+    elif dtype == np.dtype("M8[ns]") and result.dtype == _dtype_obj:
+        result = cast(np.ndarray, result)
+        return np.asarray(maybe_cast_to_datetime(result, dtype=dtype))
+
+    return result
+
+
+@overload
+def maybe_downcast_numeric(
+    result: np.ndarray, dtype: np.dtype, do_round: bool = False
+) -> np.ndarray:
+    ...
+
+
+@overload
+def maybe_downcast_numeric(
+    result: ExtensionArray, dtype: DtypeObj, do_round: bool = False
+) -> ArrayLike:
+    ...
+
+
+def maybe_downcast_numeric(
+    result: ArrayLike, dtype: DtypeObj, do_round: bool = False
+) -> ArrayLike:
+    """
+    Subset of maybe_downcast_to_dtype restricted to numeric dtypes.
+
+    Parameters
+    ----------
+    result : ndarray or ExtensionArray
+    dtype : np.dtype or ExtensionDtype
+    do_round : bool
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+    if not isinstance(dtype, np.dtype) or not isinstance(result.dtype, np.dtype):
+        # e.g. SparseDtype has no itemsize attr
+        return result
+
+    def trans(x):
+        if do_round:
+            return x.round()
+        return x
+
+    if dtype.kind == result.dtype.kind:
+        # don't allow upcasts here (except if empty)
+        if result.dtype.itemsize <= dtype.itemsize and result.size:
+            return result
+
+    if dtype.kind in "biu":
+        if not result.size:
+            # if we don't have any elements, just astype it
+            return trans(result).astype(dtype)
+
+        if isinstance(result, np.ndarray):
+            element = result.item(0)
+        else:
+            element = result.iloc[0]
+        if not isinstance(element, (np.integer, np.floating, int, float, bool)):
+            # a comparable, e.g. a Decimal may slip in here
+            return result
+
+        if (
+            issubclass(result.dtype.type, (np.object_, np.number))
+            and notna(result).all()
+        ):
+            new_result = trans(result).astype(dtype)
+            if new_result.dtype.kind == "O" or result.dtype.kind == "O":
+                # np.allclose may raise TypeError on object-dtype
+                if (new_result == result).all():
+                    return new_result
+            else:
+                if np.allclose(new_result, result, rtol=0):
+                    return new_result
+
+    elif (
+        issubclass(dtype.type, np.floating)
+        and result.dtype.kind != "b"
+        and not is_string_dtype(result.dtype)
+    ):
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore", "overflow encountered in cast", RuntimeWarning
+            )
+            new_result = result.astype(dtype)
+
+        # Adjust tolerances based on floating point size
+        size_tols = {4: 5e-4, 8: 5e-8, 16: 5e-16}
+
+        atol = size_tols.get(new_result.dtype.itemsize, 0.0)
+
+        # Check downcast float values are still equal within 7 digits when
+        # converting from float64 to float32
+        if np.allclose(new_result, result, equal_nan=True, rtol=0.0, atol=atol):
+            return new_result
+
+    elif dtype.kind == result.dtype.kind == "c":
+        new_result = result.astype(dtype)
+
+        if np.array_equal(new_result, result, equal_nan=True):
+            # TODO: use tolerance like we do for float?
+            return new_result
+
+    return result
+
+
+def maybe_upcast_numeric_to_64bit(arr: NumpyIndexT) -> NumpyIndexT:
+    """
+    If array is a int/uint/float bit size lower than 64 bit, upcast it to 64 bit.
+
+    Parameters
+    ----------
+    arr : ndarray or ExtensionArray
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+    dtype = arr.dtype
+    if dtype.kind == "i" and dtype != np.int64:
+        return arr.astype(np.int64)
+    elif dtype.kind == "u" and dtype != np.uint64:
+        return arr.astype(np.uint64)
+    elif dtype.kind == "f" and dtype != np.float64:
+        return arr.astype(np.float64)
+    else:
+        return arr
+
+
+def maybe_cast_pointwise_result(
+    result: ArrayLike,
+    dtype: DtypeObj,
+    numeric_only: bool = False,
+    same_dtype: bool = True,
+) -> ArrayLike:
+    """
+    Try casting result of a pointwise operation back to the original dtype if
+    appropriate.
+
+    Parameters
+    ----------
+    result : array-like
+        Result to cast.
+    dtype : np.dtype or ExtensionDtype
+        Input Series from which result was calculated.
+    numeric_only : bool, default False
+        Whether to cast only numerics or datetimes as well.
+    same_dtype : bool, default True
+        Specify dtype when calling _from_sequence
+
+    Returns
+    -------
+    result : array-like
+        result maybe casted to the dtype.
+    """
+
+    if isinstance(dtype, ExtensionDtype):
+        cls = dtype.construct_array_type()
+        if same_dtype:
+            result = _maybe_cast_to_extension_array(cls, result, dtype=dtype)
+        else:
+            result = _maybe_cast_to_extension_array(cls, result)
+
+    elif (numeric_only and dtype.kind in "iufcb") or not numeric_only:
+        result = maybe_downcast_to_dtype(result, dtype)
+
+    return result
+
+
+def _maybe_cast_to_extension_array(
+    cls: type[ExtensionArray], obj: ArrayLike, dtype: ExtensionDtype | None = None
+) -> ArrayLike:
+    """
+    Call to `_from_sequence` that returns the object unchanged on Exception.
+
+    Parameters
+    ----------
+    cls : class, subclass of ExtensionArray
+    obj : arraylike
+        Values to pass to cls._from_sequence
+    dtype : ExtensionDtype, optional
+
+    Returns
+    -------
+    ExtensionArray or obj
+    """
+    result: ArrayLike
+
+    if dtype is not None:
+        try:
+            result = cls._from_scalars(obj, dtype=dtype)
+        except (TypeError, ValueError):
+            return obj
+        return result
+
+    try:
+        result = cls._from_sequence(obj, dtype=dtype)
+    except Exception:
+        # We can't predict what downstream EA constructors may raise
+        result = obj
+    return result
+
+
+@overload
+def ensure_dtype_can_hold_na(dtype: np.dtype) -> np.dtype:
+    ...
+
+
+@overload
+def ensure_dtype_can_hold_na(dtype: ExtensionDtype) -> ExtensionDtype:
+    ...
+
+
+def ensure_dtype_can_hold_na(dtype: DtypeObj) -> DtypeObj:
+    """
+    If we have a dtype that cannot hold NA values, find the best match that can.
+    """
+    if isinstance(dtype, ExtensionDtype):
+        if dtype._can_hold_na:
+            return dtype
+        elif isinstance(dtype, IntervalDtype):
+            # TODO(GH#45349): don't special-case IntervalDtype, allow
+            #  overriding instead of returning object below.
+            return IntervalDtype(np.float64, closed=dtype.closed)
+        return _dtype_obj
+    elif dtype.kind == "b":
+        return _dtype_obj
+    elif dtype.kind in "iu":
+        return np.dtype(np.float64)
+    return dtype
+
+
+_canonical_nans = {
+    np.datetime64: np.datetime64("NaT", "ns"),
+    np.timedelta64: np.timedelta64("NaT", "ns"),
+    type(np.nan): np.nan,
+}
+
+
+def maybe_promote(dtype: np.dtype, fill_value=np.nan):
+    """
+    Find the minimal dtype that can hold both the given dtype and fill_value.
+
+    Parameters
+    ----------
+    dtype : np.dtype
+    fill_value : scalar, default np.nan
+
+    Returns
+    -------
+    dtype
+        Upcasted from dtype argument if necessary.
+    fill_value
+        Upcasted from fill_value argument if necessary.
+
+    Raises
+    ------
+    ValueError
+        If fill_value is a non-scalar and dtype is not object.
+    """
+    orig = fill_value
+    orig_is_nat = False
+    if checknull(fill_value):
+        # https://github.com/pandas-dev/pandas/pull/39692#issuecomment-1441051740
+        #  avoid cache misses with NaN/NaT values that are not singletons
+        if fill_value is not NA:
+            try:
+                orig_is_nat = np.isnat(fill_value)
+            except TypeError:
+                pass
+
+        fill_value = _canonical_nans.get(type(fill_value), fill_value)
+
+    # for performance, we are using a cached version of the actual implementation
+    # of the function in _maybe_promote. However, this doesn't always work (in case
+    # of non-hashable arguments), so we fallback to the actual implementation if needed
+    try:
+        # error: Argument 3 to "__call__" of "_lru_cache_wrapper" has incompatible type
+        # "Type[Any]"; expected "Hashable"  [arg-type]
+        dtype, fill_value = _maybe_promote_cached(
+            dtype, fill_value, type(fill_value)  # type: ignore[arg-type]
+        )
+    except TypeError:
+        # if fill_value is not hashable (required for caching)
+        dtype, fill_value = _maybe_promote(dtype, fill_value)
+
+    if (dtype == _dtype_obj and orig is not None) or (
+        orig_is_nat and np.datetime_data(orig)[0] != "ns"
+    ):
+        # GH#51592,53497 restore our potentially non-canonical fill_value
+        fill_value = orig
+    return dtype, fill_value
+
+
+@functools.lru_cache
+def _maybe_promote_cached(dtype, fill_value, fill_value_type):
+    # The cached version of _maybe_promote below
+    # This also use fill_value_type as (unused) argument to use this in the
+    # cache lookup -> to differentiate 1 and True
+    return _maybe_promote(dtype, fill_value)
+
+
+def _maybe_promote(dtype: np.dtype, fill_value=np.nan):
+    # The actual implementation of the function, use `maybe_promote` above for
+    # a cached version.
+    if not is_scalar(fill_value):
+        # with object dtype there is nothing to promote, and the user can
+        #  pass pretty much any weird fill_value they like
+        if dtype != object:
+            # with object dtype there is nothing to promote, and the user can
+            #  pass pretty much any weird fill_value they like
+            raise ValueError("fill_value must be a scalar")
+        dtype = _dtype_obj
+        return dtype, fill_value
+
+    if is_valid_na_for_dtype(fill_value, dtype) and dtype.kind in "iufcmM":
+        dtype = ensure_dtype_can_hold_na(dtype)
+        fv = na_value_for_dtype(dtype)
+        return dtype, fv
+
+    elif isinstance(dtype, CategoricalDtype):
+        if fill_value in dtype.categories or isna(fill_value):
+            return dtype, fill_value
+        else:
+            return object, ensure_object(fill_value)
+
+    elif isna(fill_value):
+        dtype = _dtype_obj
+        if fill_value is None:
+            # but we retain e.g. pd.NA
+            fill_value = np.nan
+        return dtype, fill_value
+
+    # returns tuple of (dtype, fill_value)
+    if issubclass(dtype.type, np.datetime64):
+        inferred, fv = infer_dtype_from_scalar(fill_value)
+        if inferred == dtype:
+            return dtype, fv
+
+        from pandas.core.arrays import DatetimeArray
+
+        dta = DatetimeArray._from_sequence([], dtype="M8[ns]")
+        try:
+            fv = dta._validate_setitem_value(fill_value)
+            return dta.dtype, fv
+        except (ValueError, TypeError):
+            return _dtype_obj, fill_value
+
+    elif issubclass(dtype.type, np.timedelta64):
+        inferred, fv = infer_dtype_from_scalar(fill_value)
+        if inferred == dtype:
+            return dtype, fv
+
+        elif inferred.kind == "m":
+            # different unit, e.g. passed np.timedelta64(24, "h") with dtype=m8[ns]
+            # see if we can losslessly cast it to our dtype
+            unit = np.datetime_data(dtype)[0]
+            try:
+                td = Timedelta(fill_value).as_unit(unit, round_ok=False)
+            except OutOfBoundsTimedelta:
+                return _dtype_obj, fill_value
+            else:
+                return dtype, td.asm8
+
+        return _dtype_obj, fill_value
+
+    elif is_float(fill_value):
+        if issubclass(dtype.type, np.bool_):
+            dtype = np.dtype(np.object_)
+
+        elif issubclass(dtype.type, np.integer):
+            dtype = np.dtype(np.float64)
+
+        elif dtype.kind == "f":
+            mst = np.min_scalar_type(fill_value)
+            if mst > dtype:
+                # e.g. mst is np.float64 and dtype is np.float32
+                dtype = mst
+
+        elif dtype.kind == "c":
+            mst = np.min_scalar_type(fill_value)
+            dtype = np.promote_types(dtype, mst)
+
+    elif is_bool(fill_value):
+        if not issubclass(dtype.type, np.bool_):
+            dtype = np.dtype(np.object_)
+
+    elif is_integer(fill_value):
+        if issubclass(dtype.type, np.bool_):
+            dtype = np.dtype(np.object_)
+
+        elif issubclass(dtype.type, np.integer):
+            if not np_can_cast_scalar(fill_value, dtype):  # type: ignore[arg-type]
+                # upcast to prevent overflow
+                mst = np.min_scalar_type(fill_value)
+                dtype = np.promote_types(dtype, mst)
+                if dtype.kind == "f":
+                    # Case where we disagree with numpy
+                    dtype = np.dtype(np.object_)
+
+    elif is_complex(fill_value):
+        if issubclass(dtype.type, np.bool_):
+            dtype = np.dtype(np.object_)
+
+        elif issubclass(dtype.type, (np.integer, np.floating)):
+            mst = np.min_scalar_type(fill_value)
+            dtype = np.promote_types(dtype, mst)
+
+        elif dtype.kind == "c":
+            mst = np.min_scalar_type(fill_value)
+            if mst > dtype:
+                # e.g. mst is np.complex128 and dtype is np.complex64
+                dtype = mst
+
+    else:
+        dtype = np.dtype(np.object_)
+
+    # in case we have a string that looked like a number
+    if issubclass(dtype.type, (bytes, str)):
+        dtype = np.dtype(np.object_)
+
+    fill_value = _ensure_dtype_type(fill_value, dtype)
+    return dtype, fill_value
+
+
+def _ensure_dtype_type(value, dtype: np.dtype):
+    """
+    Ensure that the given value is an instance of the given dtype.
+
+    e.g. if out dtype is np.complex64_, we should have an instance of that
+    as opposed to a python complex object.
+
+    Parameters
+    ----------
+    value : object
+    dtype : np.dtype
+
+    Returns
+    -------
+    object
+    """
+    # Start with exceptions in which we do _not_ cast to numpy types
+
+    if dtype == _dtype_obj:
+        return value
+
+    # Note: before we get here we have already excluded isna(value)
+    return dtype.type(value)
+
+
+def infer_dtype_from(val) -> tuple[DtypeObj, Any]:
+    """
+    Interpret the dtype from a scalar or array.
+
+    Parameters
+    ----------
+    val : object
+    """
+    if not is_list_like(val):
+        return infer_dtype_from_scalar(val)
+    return infer_dtype_from_array(val)
+
+
+def infer_dtype_from_scalar(val) -> tuple[DtypeObj, Any]:
+    """
+    Interpret the dtype from a scalar.
+
+    Parameters
+    ----------
+    val : object
+    """
+    dtype: DtypeObj = _dtype_obj
+
+    # a 1-element ndarray
+    if isinstance(val, np.ndarray):
+        if val.ndim != 0:
+            msg = "invalid ndarray passed to infer_dtype_from_scalar"
+            raise ValueError(msg)
+
+        dtype = val.dtype
+        val = lib.item_from_zerodim(val)
+
+    elif isinstance(val, str):
+        # If we create an empty array using a string to infer
+        # the dtype, NumPy will only allocate one character per entry
+        # so this is kind of bad. Alternately we could use np.repeat
+        # instead of np.empty (but then you still don't want things
+        # coming out as np.str_!
+
+        dtype = _dtype_obj
+        if using_string_dtype():
+            from pandas.core.arrays.string_ import StringDtype
+
+            dtype = StringDtype(na_value=np.nan)
+
+    elif isinstance(val, (np.datetime64, dt.datetime)):
+        try:
+            val = Timestamp(val)
+        except OutOfBoundsDatetime:
+            return _dtype_obj, val
+
+        if val is NaT or val.tz is None:
+            val = val.to_datetime64()
+            dtype = val.dtype
+            # TODO: test with datetime(2920, 10, 1) based on test_replace_dtypes
+        else:
+            dtype = DatetimeTZDtype(unit=val.unit, tz=val.tz)
+
+    elif isinstance(val, (np.timedelta64, dt.timedelta)):
+        try:
+            val = Timedelta(val)
+        except (OutOfBoundsTimedelta, OverflowError):
+            dtype = _dtype_obj
+        else:
+            if val is NaT:
+                val = np.timedelta64("NaT", "ns")
+            else:
+                val = val.asm8
+            dtype = val.dtype
+
+    elif is_bool(val):
+        dtype = np.dtype(np.bool_)
+
+    elif is_integer(val):
+        if isinstance(val, np.integer):
+            dtype = np.dtype(type(val))
+        else:
+            dtype = np.dtype(np.int64)
+
+        try:
+            np.array(val, dtype=dtype)
+        except OverflowError:
+            dtype = np.array(val).dtype
+
+    elif is_float(val):
+        if isinstance(val, np.floating):
+            dtype = np.dtype(type(val))
+        else:
+            dtype = np.dtype(np.float64)
+
+    elif is_complex(val):
+        dtype = np.dtype(np.complex128)
+
+    if isinstance(val, Period):
+        dtype = PeriodDtype(freq=val.freq)
+    elif isinstance(val, Interval):
+        subtype = infer_dtype_from_scalar(val.left)[0]
+        dtype = IntervalDtype(subtype=subtype, closed=val.closed)
+
+    return dtype, val
+
+
+def dict_compat(d: dict[Scalar, Scalar]) -> dict[Scalar, Scalar]:
+    """
+    Convert datetimelike-keyed dicts to a Timestamp-keyed dict.
+
+    Parameters
+    ----------
+    d: dict-like object
+
+    Returns
+    -------
+    dict
+    """
+    return {maybe_box_datetimelike(key): value for key, value in d.items()}
+
+
+def infer_dtype_from_array(arr) -> tuple[DtypeObj, ArrayLike]:
+    """
+    Infer the dtype from an array.
+
+    Parameters
+    ----------
+    arr : array
+
+    Returns
+    -------
+    tuple (pandas-compat dtype, array)
+
+
+    Examples
+    --------
+    >>> np.asarray([1, '1'])
+    array(['1', '1'], dtype='>> infer_dtype_from_array([1, '1'])
+    (dtype('O'), [1, '1'])
+    """
+    if isinstance(arr, np.ndarray):
+        return arr.dtype, arr
+
+    if not is_list_like(arr):
+        raise TypeError("'arr' must be list-like")
+
+    arr_dtype = getattr(arr, "dtype", None)
+    if isinstance(arr_dtype, ExtensionDtype):
+        return arr.dtype, arr
+
+    elif isinstance(arr, ABCSeries):
+        return arr.dtype, np.asarray(arr)
+
+    # don't force numpy coerce with nan's
+    inferred = lib.infer_dtype(arr, skipna=False)
+    if inferred in ["string", "bytes", "mixed", "mixed-integer"]:
+        return (np.dtype(np.object_), arr)
+
+    arr = np.asarray(arr)
+    return arr.dtype, arr
+
+
+def _maybe_infer_dtype_type(element):
+    """
+    Try to infer an object's dtype, for use in arithmetic ops.
+
+    Uses `element.dtype` if that's available.
+    Objects implementing the iterator protocol are cast to a NumPy array,
+    and from there the array's type is used.
+
+    Parameters
+    ----------
+    element : object
+        Possibly has a `.dtype` attribute, and possibly the iterator
+        protocol.
+
+    Returns
+    -------
+    tipo : type
+
+    Examples
+    --------
+    >>> from collections import namedtuple
+    >>> Foo = namedtuple("Foo", "dtype")
+    >>> _maybe_infer_dtype_type(Foo(np.dtype("i8")))
+    dtype('int64')
+    """
+    tipo = None
+    if hasattr(element, "dtype"):
+        tipo = element.dtype
+    elif is_list_like(element):
+        element = np.asarray(element)
+        tipo = element.dtype
+    return tipo
+
+
+def invalidate_string_dtypes(dtype_set: set[DtypeObj]) -> None:
+    """
+    Change string like dtypes to object for
+    ``DataFrame.select_dtypes()``.
+    """
+    # error: Argument 1 to  has incompatible type "Type[generic]"; expected
+    # "Union[dtype[Any], ExtensionDtype, None]"
+    # error: Argument 2 to  has incompatible type "Type[generic]"; expected
+    # "Union[dtype[Any], ExtensionDtype, None]"
+    non_string_dtypes = dtype_set - {
+        np.dtype("S").type,  # type: ignore[arg-type]
+        np.dtype(" np.ndarray:
+    """coerce the indexer input array to the smallest dtype possible"""
+    length = len(categories)
+    if length < _int8_max:
+        return ensure_int8(indexer)
+    elif length < _int16_max:
+        return ensure_int16(indexer)
+    elif length < _int32_max:
+        return ensure_int32(indexer)
+    return ensure_int64(indexer)
+
+
+def convert_dtypes(
+    input_array: ArrayLike,
+    convert_string: bool = True,
+    convert_integer: bool = True,
+    convert_boolean: bool = True,
+    convert_floating: bool = True,
+    infer_objects: bool = False,
+    dtype_backend: Literal["numpy_nullable", "pyarrow"] = "numpy_nullable",
+) -> DtypeObj:
+    """
+    Convert objects to best possible type, and optionally,
+    to types supporting ``pd.NA``.
+
+    Parameters
+    ----------
+    input_array : ExtensionArray or np.ndarray
+    convert_string : bool, default True
+        Whether object dtypes should be converted to ``StringDtype()``.
+    convert_integer : bool, default True
+        Whether, if possible, conversion can be done to integer extension types.
+    convert_boolean : bool, defaults True
+        Whether object dtypes should be converted to ``BooleanDtypes()``.
+    convert_floating : bool, defaults True
+        Whether, if possible, conversion can be done to floating extension types.
+        If `convert_integer` is also True, preference will be give to integer
+        dtypes if the floats can be faithfully casted to integers.
+    infer_objects : bool, defaults False
+        Whether to also infer objects to float/int if possible. Is only hit if the
+        object array contains pd.NA.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    np.dtype, or ExtensionDtype
+    """
+    from pandas.core.arrays.string_ import StringDtype
+
+    inferred_dtype: str | DtypeObj
+
+    if (
+        convert_string or convert_integer or convert_boolean or convert_floating
+    ) and isinstance(input_array, np.ndarray):
+        if input_array.dtype == object:
+            inferred_dtype = lib.infer_dtype(input_array)
+        else:
+            inferred_dtype = input_array.dtype
+
+        if is_string_dtype(inferred_dtype):
+            if not convert_string or inferred_dtype == "bytes":
+                inferred_dtype = input_array.dtype
+            else:
+                inferred_dtype = pandas_dtype_func("string")
+
+        if convert_integer:
+            target_int_dtype = pandas_dtype_func("Int64")
+
+            if input_array.dtype.kind in "iu":
+                from pandas.core.arrays.integer import NUMPY_INT_TO_DTYPE
+
+                inferred_dtype = NUMPY_INT_TO_DTYPE.get(
+                    input_array.dtype, target_int_dtype
+                )
+            elif input_array.dtype.kind in "fcb":
+                # TODO: de-dup with maybe_cast_to_integer_array?
+                arr = input_array[notna(input_array)]
+                if (arr.astype(int) == arr).all():
+                    inferred_dtype = target_int_dtype
+                else:
+                    inferred_dtype = input_array.dtype
+            elif (
+                infer_objects
+                and input_array.dtype == object
+                and (isinstance(inferred_dtype, str) and inferred_dtype == "integer")
+            ):
+                inferred_dtype = target_int_dtype
+
+        if convert_floating:
+            if input_array.dtype.kind in "fcb":
+                # i.e. numeric but not integer
+                from pandas.core.arrays.floating import NUMPY_FLOAT_TO_DTYPE
+
+                inferred_float_dtype: DtypeObj = NUMPY_FLOAT_TO_DTYPE.get(
+                    input_array.dtype, pandas_dtype_func("Float64")
+                )
+                # if we could also convert to integer, check if all floats
+                # are actually integers
+                if convert_integer:
+                    # TODO: de-dup with maybe_cast_to_integer_array?
+                    arr = input_array[notna(input_array)]
+                    if (arr.astype(int) == arr).all():
+                        inferred_dtype = pandas_dtype_func("Int64")
+                    else:
+                        inferred_dtype = inferred_float_dtype
+                else:
+                    inferred_dtype = inferred_float_dtype
+            elif (
+                infer_objects
+                and input_array.dtype == object
+                and (
+                    isinstance(inferred_dtype, str)
+                    and inferred_dtype == "mixed-integer-float"
+                )
+            ):
+                inferred_dtype = pandas_dtype_func("Float64")
+
+        if convert_boolean:
+            if input_array.dtype.kind == "b":
+                inferred_dtype = pandas_dtype_func("boolean")
+            elif isinstance(inferred_dtype, str) and inferred_dtype == "boolean":
+                inferred_dtype = pandas_dtype_func("boolean")
+
+        if isinstance(inferred_dtype, str):
+            # If we couldn't do anything else, then we retain the dtype
+            inferred_dtype = input_array.dtype
+
+    elif (
+        convert_string
+        and isinstance(input_array.dtype, StringDtype)
+        and input_array.dtype.na_value is np.nan
+    ):
+        inferred_dtype = pandas_dtype_func("string")
+
+    else:
+        inferred_dtype = input_array.dtype
+
+    if dtype_backend == "pyarrow":
+        from pandas.core.arrays.arrow.array import to_pyarrow_type
+
+        assert not isinstance(inferred_dtype, str)
+
+        if (
+            (convert_integer and inferred_dtype.kind in "iu")
+            or (convert_floating and inferred_dtype.kind in "fc")
+            or (convert_boolean and inferred_dtype.kind == "b")
+            or (convert_string and isinstance(inferred_dtype, StringDtype))
+            or (
+                inferred_dtype.kind not in "iufcb"
+                and not isinstance(inferred_dtype, StringDtype)
+            )
+        ):
+            if isinstance(inferred_dtype, PandasExtensionDtype) and not isinstance(
+                inferred_dtype, DatetimeTZDtype
+            ):
+                base_dtype = inferred_dtype.base
+            elif isinstance(inferred_dtype, (BaseMaskedDtype, ArrowDtype)):
+                base_dtype = inferred_dtype.numpy_dtype
+            elif isinstance(inferred_dtype, StringDtype):
+                base_dtype = np.dtype(str)
+            else:
+                base_dtype = inferred_dtype
+            if (
+                base_dtype.kind == "O"  # type: ignore[union-attr]
+                and input_array.size > 0
+                and isna(input_array).all()
+            ):
+                import pyarrow as pa
+
+                pa_type = pa.null()
+            else:
+                pa_type = to_pyarrow_type(base_dtype)
+            if pa_type is not None:
+                inferred_dtype = ArrowDtype(pa_type)
+    elif dtype_backend == "numpy_nullable" and isinstance(inferred_dtype, ArrowDtype):
+        # GH 53648
+        inferred_dtype = _arrow_dtype_mapping()[inferred_dtype.pyarrow_dtype]
+
+    # error: Incompatible return value type (got "Union[str, Union[dtype[Any],
+    # ExtensionDtype]]", expected "Union[dtype[Any], ExtensionDtype]")
+    return inferred_dtype  # type: ignore[return-value]
+
+
+def maybe_infer_to_datetimelike(
+    value: npt.NDArray[np.object_],
+    convert_to_nullable_dtype: bool = False,
+) -> np.ndarray | DatetimeArray | TimedeltaArray | PeriodArray | IntervalArray:
+    """
+    we might have a array (or single object) that is datetime like,
+    and no dtype is passed don't change the value unless we find a
+    datetime/timedelta set
+
+    this is pretty strict in that a datetime/timedelta is REQUIRED
+    in addition to possible nulls/string likes
+
+    Parameters
+    ----------
+    value : np.ndarray[object]
+
+    Returns
+    -------
+    np.ndarray, DatetimeArray, TimedeltaArray, PeriodArray, or IntervalArray
+
+    """
+    if not isinstance(value, np.ndarray) or value.dtype != object:
+        # Caller is responsible for passing only ndarray[object]
+        raise TypeError(type(value))  # pragma: no cover
+    if value.ndim != 1:
+        # Caller is responsible
+        raise ValueError(value.ndim)  # pragma: no cover
+
+    if not len(value):
+        return value
+
+    # error: Incompatible return value type (got "Union[ExtensionArray,
+    # ndarray[Any, Any]]", expected "Union[ndarray[Any, Any], DatetimeArray,
+    # TimedeltaArray, PeriodArray, IntervalArray]")
+    return lib.maybe_convert_objects(  # type: ignore[return-value]
+        value,
+        # Here we do not convert numeric dtypes, as if we wanted that,
+        #  numpy would have done it for us.
+        convert_numeric=False,
+        convert_non_numeric=True,
+        convert_to_nullable_dtype=convert_to_nullable_dtype,
+        dtype_if_all_nat=np.dtype("M8[ns]"),
+    )
+
+
+def maybe_cast_to_datetime(
+    value: np.ndarray | list, dtype: np.dtype
+) -> ExtensionArray | np.ndarray:
+    """
+    try to cast the array/value to a datetimelike dtype, converting float
+    nan to iNaT
+
+    Caller is responsible for handling ExtensionDtype cases and non dt64/td64
+    cases.
+    """
+    from pandas.core.arrays.datetimes import DatetimeArray
+    from pandas.core.arrays.timedeltas import TimedeltaArray
+
+    assert dtype.kind in "mM"
+    if not is_list_like(value):
+        raise TypeError("value must be listlike")
+
+    # TODO: _from_sequence would raise ValueError in cases where
+    #  _ensure_nanosecond_dtype raises TypeError
+    _ensure_nanosecond_dtype(dtype)
+
+    if lib.is_np_dtype(dtype, "m"):
+        res = TimedeltaArray._from_sequence(value, dtype=dtype)
+        return res
+    else:
+        try:
+            dta = DatetimeArray._from_sequence(value, dtype=dtype)
+        except ValueError as err:
+            # We can give a Series-specific exception message.
+            if "cannot supply both a tz and a timezone-naive dtype" in str(err):
+                raise ValueError(
+                    "Cannot convert timezone-aware data to "
+                    "timezone-naive dtype. Use "
+                    "pd.Series(values).dt.tz_localize(None) instead."
+                ) from err
+            raise
+
+        return dta
+
+
+def _ensure_nanosecond_dtype(dtype: DtypeObj) -> None:
+    """
+    Convert dtypes with granularity less than nanosecond to nanosecond
+
+    >>> _ensure_nanosecond_dtype(np.dtype("M8[us]"))
+
+    >>> _ensure_nanosecond_dtype(np.dtype("M8[D]"))
+    Traceback (most recent call last):
+        ...
+    TypeError: dtype=datetime64[D] is not supported. Supported resolutions are 's', 'ms', 'us', and 'ns'
+
+    >>> _ensure_nanosecond_dtype(np.dtype("m8[ps]"))
+    Traceback (most recent call last):
+        ...
+    TypeError: dtype=timedelta64[ps] is not supported. Supported resolutions are 's', 'ms', 'us', and 'ns'
+    """  # noqa: E501
+    msg = (
+        f"The '{dtype.name}' dtype has no unit. "
+        f"Please pass in '{dtype.name}[ns]' instead."
+    )
+
+    # unpack e.g. SparseDtype
+    dtype = getattr(dtype, "subtype", dtype)
+
+    if not isinstance(dtype, np.dtype):
+        # i.e. datetime64tz
+        pass
+
+    elif dtype.kind in "mM":
+        if not is_supported_dtype(dtype):
+            # pre-2.0 we would silently swap in nanos for lower-resolutions,
+            #  raise for above-nano resolutions
+            if dtype.name in ["datetime64", "timedelta64"]:
+                raise ValueError(msg)
+            # TODO: ValueError or TypeError? existing test
+            #  test_constructor_generic_timestamp_bad_frequency expects TypeError
+            raise TypeError(
+                f"dtype={dtype} is not supported. Supported resolutions are 's', "
+                "'ms', 'us', and 'ns'"
+            )
+
+
+# TODO: other value-dependent functions to standardize here include
+#  Index._find_common_type_compat
+def find_result_type(left_dtype: DtypeObj, right: Any) -> DtypeObj:
+    """
+    Find the type/dtype for the result of an operation between objects.
+
+    This is similar to find_common_type, but looks at the right object instead
+    of just its dtype. This can be useful in particular when the right
+    object does not have a `dtype`.
+
+    Parameters
+    ----------
+    left_dtype : np.dtype or ExtensionDtype
+    right : Any
+
+    Returns
+    -------
+    np.dtype or ExtensionDtype
+
+    See also
+    --------
+    find_common_type
+    numpy.result_type
+    """
+    new_dtype: DtypeObj
+
+    if (
+        isinstance(left_dtype, np.dtype)
+        and left_dtype.kind in "iuc"
+        and (lib.is_integer(right) or lib.is_float(right))
+    ):
+        # e.g. with int8 dtype and right=512, we want to end up with
+        # np.int16, whereas infer_dtype_from(512) gives np.int64,
+        #  which will make us upcast too far.
+        if lib.is_float(right) and right.is_integer() and left_dtype.kind != "f":
+            right = int(right)
+        # After NEP 50, numpy won't inspect Python scalars
+        # TODO: do we need to recreate numpy's inspection logic for floats too
+        # (this breaks some tests)
+        if isinstance(right, int) and not isinstance(right, np.integer):
+            # This gives an unsigned type by default
+            # (if our number is positive)
+
+            # If our left dtype is signed, we might not want this since
+            # this might give us 1 dtype too big
+            # We should check if the corresponding int dtype (e.g. int64 for uint64)
+            # can hold the number
+            right_dtype = np.min_scalar_type(right)
+            if right == 0:
+                # Special case 0
+                right = left_dtype
+            elif (
+                not np.issubdtype(left_dtype, np.unsignedinteger)
+                and 0 < right <= np.iinfo(right_dtype).max
+            ):
+                # If left dtype isn't unsigned, check if it fits in the signed dtype
+                right = np.dtype(f"i{right_dtype.itemsize}")
+            else:
+                right = right_dtype
+
+        new_dtype = np.result_type(left_dtype, right)
+
+    elif is_valid_na_for_dtype(right, left_dtype):
+        # e.g. IntervalDtype[int] and None/np.nan
+        new_dtype = ensure_dtype_can_hold_na(left_dtype)
+
+    else:
+        dtype, _ = infer_dtype_from(right)
+        new_dtype = find_common_type([left_dtype, dtype])
+
+    return new_dtype
+
+
+def common_dtype_categorical_compat(
+    objs: Sequence[Index | ArrayLike], dtype: DtypeObj
+) -> DtypeObj:
+    """
+    Update the result of find_common_type to account for NAs in a Categorical.
+
+    Parameters
+    ----------
+    objs : list[np.ndarray | ExtensionArray | Index]
+    dtype : np.dtype or ExtensionDtype
+
+    Returns
+    -------
+    np.dtype or ExtensionDtype
+    """
+    # GH#38240
+
+    # TODO: more generally, could do `not can_hold_na(dtype)`
+    if lib.is_np_dtype(dtype, "iu"):
+        for obj in objs:
+            # We don't want to accientally allow e.g. "categorical" str here
+            obj_dtype = getattr(obj, "dtype", None)
+            if isinstance(obj_dtype, CategoricalDtype):
+                if isinstance(obj, ABCIndex):
+                    # This check may already be cached
+                    hasnas = obj.hasnans
+                else:
+                    # Categorical
+                    hasnas = cast("Categorical", obj)._hasna
+
+                if hasnas:
+                    # see test_union_int_categorical_with_nan
+                    dtype = np.dtype(np.float64)
+                    break
+    return dtype
+
+
+def np_find_common_type(*dtypes: np.dtype) -> np.dtype:
+    """
+    np.find_common_type implementation pre-1.25 deprecation using np.result_type
+    https://github.com/pandas-dev/pandas/pull/49569#issuecomment-1308300065
+
+    Parameters
+    ----------
+    dtypes : np.dtypes
+
+    Returns
+    -------
+    np.dtype
+    """
+    try:
+        common_dtype = np.result_type(*dtypes)
+        if common_dtype.kind in "mMSU":
+            # NumPy promotion currently (1.25) misbehaves for for times and strings,
+            # so fall back to object (find_common_dtype did unless there
+            # was only one dtype)
+            common_dtype = np.dtype("O")
+
+    except TypeError:
+        common_dtype = np.dtype("O")
+    return common_dtype
+
+
+@overload
+def find_common_type(types: list[np.dtype]) -> np.dtype:
+    ...
+
+
+@overload
+def find_common_type(types: list[ExtensionDtype]) -> DtypeObj:
+    ...
+
+
+@overload
+def find_common_type(types: list[DtypeObj]) -> DtypeObj:
+    ...
+
+
+def find_common_type(types):
+    """
+    Find a common data type among the given dtypes.
+
+    Parameters
+    ----------
+    types : list of dtypes
+
+    Returns
+    -------
+    pandas extension or numpy dtype
+
+    See Also
+    --------
+    numpy.find_common_type
+
+    """
+    if not types:
+        raise ValueError("no types given")
+
+    first = types[0]
+
+    # workaround for find_common_type([np.dtype('datetime64[ns]')] * 2)
+    # => object
+    if lib.dtypes_all_equal(list(types)):
+        return first
+
+    # get unique types (dict.fromkeys is used as order-preserving set())
+    types = list(dict.fromkeys(types).keys())
+
+    if any(isinstance(t, ExtensionDtype) for t in types):
+        for t in types:
+            if isinstance(t, ExtensionDtype):
+                res = t._get_common_dtype(types)
+                if res is not None:
+                    return res
+        return np.dtype("object")
+
+    # take lowest unit
+    if all(lib.is_np_dtype(t, "M") for t in types):
+        return np.dtype(max(types))
+    if all(lib.is_np_dtype(t, "m") for t in types):
+        return np.dtype(max(types))
+
+    # don't mix bool / int or float or complex
+    # this is different from numpy, which casts bool with float/int as int
+    has_bools = any(t.kind == "b" for t in types)
+    if has_bools:
+        for t in types:
+            if t.kind in "iufc":
+                return np.dtype("object")
+
+    return np_find_common_type(*types)
+
+
+def construct_2d_arraylike_from_scalar(
+    value: Scalar, length: int, width: int, dtype: np.dtype, copy: bool
+) -> np.ndarray:
+    shape = (length, width)
+
+    if dtype.kind in "mM":
+        value = _maybe_box_and_unbox_datetimelike(value, dtype)
+    elif dtype == _dtype_obj:
+        if isinstance(value, (np.timedelta64, np.datetime64)):
+            # calling np.array below would cast to pytimedelta/pydatetime
+            out = np.empty(shape, dtype=object)
+            out.fill(value)
+            return out
+
+    # Attempt to coerce to a numpy array
+    try:
+        if not copy:
+            arr = np.asarray(value, dtype=dtype)
+        else:
+            arr = np.array(value, dtype=dtype, copy=copy)
+    except (ValueError, TypeError) as err:
+        raise TypeError(
+            f"DataFrame constructor called with incompatible data and dtype: {err}"
+        ) from err
+
+    if arr.ndim != 0:
+        raise ValueError("DataFrame constructor not properly called!")
+
+    return np.full(shape, arr)
+
+
+def construct_1d_arraylike_from_scalar(
+    value: Scalar, length: int, dtype: DtypeObj | None
+) -> ArrayLike:
+    """
+    create a np.ndarray / pandas type of specified shape and dtype
+    filled with values
+
+    Parameters
+    ----------
+    value : scalar value
+    length : int
+    dtype : pandas_dtype or np.dtype
+
+    Returns
+    -------
+    np.ndarray / pandas type of length, filled with value
+
+    """
+
+    if dtype is None:
+        try:
+            dtype, value = infer_dtype_from_scalar(value)
+        except OutOfBoundsDatetime:
+            dtype = _dtype_obj
+
+    if isinstance(dtype, ExtensionDtype):
+        cls = dtype.construct_array_type()
+        seq = [] if length == 0 else [value]
+        subarr = cls._from_sequence(seq, dtype=dtype).repeat(length)
+
+    else:
+        if length and dtype.kind in "iu" and isna(value):
+            # coerce if we have nan for an integer dtype
+            dtype = np.dtype("float64")
+        elif lib.is_np_dtype(dtype, "US"):
+            # we need to coerce to object dtype to avoid
+            # to allow numpy to take our string as a scalar value
+            dtype = np.dtype("object")
+            if not isna(value):
+                value = ensure_str(value)
+        elif dtype.kind in "mM":
+            value = _maybe_box_and_unbox_datetimelike(value, dtype)
+
+        subarr = np.empty(length, dtype=dtype)
+        if length:
+            # GH 47391: numpy > 1.24 will raise filling np.nan into int dtypes
+            subarr.fill(value)
+
+    return subarr
+
+
+def _maybe_box_and_unbox_datetimelike(value: Scalar, dtype: DtypeObj):
+    # Caller is responsible for checking dtype.kind in "mM"
+
+    if isinstance(value, dt.datetime):
+        # we dont want to box dt64, in particular datetime64("NaT")
+        value = maybe_box_datetimelike(value, dtype)
+
+    return _maybe_unbox_datetimelike(value, dtype)
+
+
+def construct_1d_object_array_from_listlike(values: Collection) -> np.ndarray:
+    """
+    Transform any list-like object in a 1-dimensional numpy array of object
+    dtype.
+
+    Parameters
+    ----------
+    values : any iterable which has a len()
+
+    Raises
+    ------
+    TypeError
+        * If `values` does not have a len()
+
+    Returns
+    -------
+    1-dimensional numpy array of dtype object
+    """
+    # numpy will try to interpret nested lists as further dimensions in np.array(),
+    # hence explicitly making a 1D array using np.fromiter
+    result = np.empty(len(values), dtype="object")
+    for i, obj in enumerate(values):
+        result[i] = obj
+    return result
+
+
+def maybe_cast_to_integer_array(arr: list | np.ndarray, dtype: np.dtype) -> np.ndarray:
+    """
+    Takes any dtype and returns the casted version, raising for when data is
+    incompatible with integer/unsigned integer dtypes.
+
+    Parameters
+    ----------
+    arr : np.ndarray or list
+        The array to cast.
+    dtype : np.dtype
+        The integer dtype to cast the array to.
+
+    Returns
+    -------
+    ndarray
+        Array of integer or unsigned integer dtype.
+
+    Raises
+    ------
+    OverflowError : the dtype is incompatible with the data
+    ValueError : loss of precision has occurred during casting
+
+    Examples
+    --------
+    If you try to coerce negative values to unsigned integers, it raises:
+
+    >>> pd.Series([-1], dtype="uint64")
+    Traceback (most recent call last):
+        ...
+    OverflowError: Trying to coerce negative values to unsigned integers
+
+    Also, if you try to coerce float values to integers, it raises:
+
+    >>> maybe_cast_to_integer_array([1, 2, 3.5], dtype=np.dtype("int64"))
+    Traceback (most recent call last):
+        ...
+    ValueError: Trying to coerce float values to integers
+    """
+    assert dtype.kind in "iu"
+
+    try:
+        if not isinstance(arr, np.ndarray):
+            with warnings.catch_warnings():
+                # We already disallow dtype=uint w/ negative numbers
+                # (test_constructor_coercion_signed_to_unsigned) so safe to ignore.
+                warnings.filterwarnings(
+                    "ignore",
+                    "NumPy will stop allowing conversion of out-of-bound Python int",
+                    DeprecationWarning,
+                )
+                casted = np.asarray(arr, dtype=dtype)
+        else:
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore", category=RuntimeWarning)
+                casted = arr.astype(dtype, copy=False)
+    except OverflowError as err:
+        raise OverflowError(
+            "The elements provided in the data cannot all be "
+            f"casted to the dtype {dtype}"
+        ) from err
+
+    if isinstance(arr, np.ndarray) and arr.dtype == dtype:
+        # avoid expensive array_equal check
+        return casted
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings("ignore", category=RuntimeWarning)
+        warnings.filterwarnings(
+            "ignore", "elementwise comparison failed", FutureWarning
+        )
+        if np.array_equal(arr, casted):
+            return casted
+
+    # We do this casting to allow for proper
+    # data and dtype checking.
+    #
+    # We didn't do this earlier because NumPy
+    # doesn't handle `uint64` correctly.
+    arr = np.asarray(arr)
+
+    if np.issubdtype(arr.dtype, str):
+        # TODO(numpy-2.0 min): This case will raise an OverflowError above
+        if (casted.astype(str) == arr).all():
+            return casted
+        raise ValueError(f"string values cannot be losslessly cast to {dtype}")
+
+    if dtype.kind == "u" and (arr < 0).any():
+        # TODO: can this be hit anymore after numpy 2.0?
+        raise OverflowError("Trying to coerce negative values to unsigned integers")
+
+    if arr.dtype.kind == "f":
+        if not np.isfinite(arr).all():
+            raise IntCastingNaNError(
+                "Cannot convert non-finite values (NA or inf) to integer"
+            )
+        raise ValueError("Trying to coerce float values to integers")
+    if arr.dtype == object:
+        raise ValueError("Trying to coerce float values to integers")
+
+    if casted.dtype < arr.dtype:
+        # TODO: Can this path be hit anymore with numpy > 2
+        # GH#41734 e.g. [1, 200, 923442] and dtype="int8" -> overflows
+        raise ValueError(
+            f"Values are too large to be losslessly converted to {dtype}. "
+            f"To cast anyway, use pd.Series(values).astype({dtype})"
+        )
+
+    if arr.dtype.kind in "mM":
+        # test_constructor_maskedarray_nonfloat
+        raise TypeError(
+            f"Constructing a Series or DataFrame from {arr.dtype} values and "
+            f"dtype={dtype} is not supported. Use values.view({dtype}) instead."
+        )
+
+    # No known cases that get here, but raising explicitly to cover our bases.
+    raise ValueError(f"values cannot be losslessly cast to {dtype}")
+
+
+def can_hold_element(arr: ArrayLike, element: Any) -> bool:
+    """
+    Can we do an inplace setitem with this element in an array with this dtype?
+
+    Parameters
+    ----------
+    arr : np.ndarray or ExtensionArray
+    element : Any
+
+    Returns
+    -------
+    bool
+    """
+    dtype = arr.dtype
+    if not isinstance(dtype, np.dtype) or dtype.kind in "mM":
+        if isinstance(dtype, (PeriodDtype, IntervalDtype, DatetimeTZDtype, np.dtype)):
+            # np.dtype here catches datetime64ns and timedelta64ns; we assume
+            #  in this case that we have DatetimeArray/TimedeltaArray
+            arr = cast(
+                "PeriodArray | DatetimeArray | TimedeltaArray | IntervalArray", arr
+            )
+            try:
+                arr._validate_setitem_value(element)
+                return True
+            except (ValueError, TypeError):
+                return False
+
+        if dtype == "string":
+            try:
+                arr._maybe_convert_setitem_value(element)  # type: ignore[union-attr]
+                return True
+            except (ValueError, TypeError):
+                return False
+
+        # This is technically incorrect, but maintains the behavior of
+        # ExtensionBlock._can_hold_element
+        return True
+
+    try:
+        np_can_hold_element(dtype, element)
+        return True
+    except (TypeError, LossySetitemError):
+        return False
+
+
+def np_can_hold_element(dtype: np.dtype, element: Any) -> Any:
+    """
+    Raise if we cannot losslessly set this element into an ndarray with this dtype.
+
+    Specifically about places where we disagree with numpy.  i.e. there are
+    cases where numpy will raise in doing the setitem that we do not check
+    for here, e.g. setting str "X" into a numeric ndarray.
+
+    Returns
+    -------
+    Any
+        The element, potentially cast to the dtype.
+
+    Raises
+    ------
+    ValueError : If we cannot losslessly store this element with this dtype.
+    """
+    if dtype == _dtype_obj:
+        return element
+
+    tipo = _maybe_infer_dtype_type(element)
+
+    if dtype.kind in "iu":
+        if isinstance(element, range):
+            if _dtype_can_hold_range(element, dtype):
+                return element
+            raise LossySetitemError
+
+        if is_integer(element) or (is_float(element) and element.is_integer()):
+            # e.g. test_setitem_series_int8 if we have a python int 1
+            #  tipo may be np.int32, despite the fact that it will fit
+            #  in smaller int dtypes.
+            info = np.iinfo(dtype)
+            if info.min <= element <= info.max:
+                return dtype.type(element)
+            raise LossySetitemError
+
+        if tipo is not None:
+            if tipo.kind not in "iu":
+                if isinstance(element, np.ndarray) and element.dtype.kind == "f":
+                    # If all can be losslessly cast to integers, then we can hold them
+                    with np.errstate(invalid="ignore"):
+                        # We check afterwards if cast was losslessly, so no need to show
+                        # the warning
+                        casted = element.astype(dtype)
+                    comp = casted == element
+                    if comp.all():
+                        # Return the casted values bc they can be passed to
+                        #  np.putmask, whereas the raw values cannot.
+                        #  see TestSetitemFloatNDarrayIntoIntegerSeries
+                        return casted
+                    raise LossySetitemError
+
+                elif isinstance(element, ABCExtensionArray) and isinstance(
+                    element.dtype, CategoricalDtype
+                ):
+                    # GH#52927 setting Categorical value into non-EA frame
+                    # TODO: general-case for EAs?
+                    try:
+                        casted = element.astype(dtype)
+                    except (ValueError, TypeError):
+                        raise LossySetitemError
+                    # Check for cases of either
+                    #  a) lossy overflow/rounding or
+                    #  b) semantic changes like dt64->int64
+                    comp = casted == element
+                    if not comp.all():
+                        raise LossySetitemError
+                    return casted
+
+                # Anything other than integer we cannot hold
+                raise LossySetitemError
+            if (
+                dtype.kind == "u"
+                and isinstance(element, np.ndarray)
+                and element.dtype.kind == "i"
+            ):
+                # see test_where_uint64
+                casted = element.astype(dtype)
+                if (casted == element).all():
+                    # TODO: faster to check (element >=0).all()?  potential
+                    #  itemsize issues there?
+                    return casted
+                raise LossySetitemError
+            if dtype.itemsize < tipo.itemsize:
+                raise LossySetitemError
+            if not isinstance(tipo, np.dtype):
+                # i.e. nullable IntegerDtype; we can put this into an ndarray
+                #  losslessly iff it has no NAs
+                arr = element._values if isinstance(element, ABCSeries) else element
+                if arr._hasna:
+                    raise LossySetitemError
+                return element
+
+            return element
+
+        raise LossySetitemError
+
+    if dtype.kind == "f":
+        if lib.is_integer(element) or lib.is_float(element):
+            casted = dtype.type(element)
+            if np.isnan(casted) or casted == element:
+                return casted
+            # otherwise e.g. overflow see TestCoercionFloat32
+            raise LossySetitemError
+
+        if tipo is not None:
+            # TODO: itemsize check?
+            if tipo.kind not in "iuf":
+                # Anything other than float/integer we cannot hold
+                raise LossySetitemError
+            if not isinstance(tipo, np.dtype):
+                # i.e. nullable IntegerDtype or FloatingDtype;
+                #  we can put this into an ndarray losslessly iff it has no NAs
+                if element._hasna:
+                    raise LossySetitemError
+                return element
+            elif tipo.itemsize > dtype.itemsize or tipo.kind != dtype.kind:
+                if isinstance(element, np.ndarray):
+                    # e.g. TestDataFrameIndexingWhere::test_where_alignment
+                    casted = element.astype(dtype)
+                    if np.array_equal(casted, element, equal_nan=True):
+                        return casted
+                    raise LossySetitemError
+
+            return element
+
+        raise LossySetitemError
+
+    if dtype.kind == "c":
+        if lib.is_integer(element) or lib.is_complex(element) or lib.is_float(element):
+            if np.isnan(element):
+                # see test_where_complex GH#6345
+                return dtype.type(element)
+
+            with warnings.catch_warnings():
+                warnings.filterwarnings("ignore")
+                casted = dtype.type(element)
+            if casted == element:
+                return casted
+            # otherwise e.g. overflow see test_32878_complex_itemsize
+            raise LossySetitemError
+
+        if tipo is not None:
+            if tipo.kind in "iufc":
+                return element
+            raise LossySetitemError
+        raise LossySetitemError
+
+    if dtype.kind == "b":
+        if tipo is not None:
+            if tipo.kind == "b":
+                if not isinstance(tipo, np.dtype):
+                    # i.e. we have a BooleanArray
+                    if element._hasna:
+                        # i.e. there are pd.NA elements
+                        raise LossySetitemError
+                return element
+            raise LossySetitemError
+        if lib.is_bool(element):
+            return element
+        raise LossySetitemError
+
+    if dtype.kind == "S":
+        # TODO: test tests.frame.methods.test_replace tests get here,
+        #  need more targeted tests.  xref phofl has a PR about this
+        if tipo is not None:
+            if tipo.kind == "S" and tipo.itemsize <= dtype.itemsize:
+                return element
+            raise LossySetitemError
+        if isinstance(element, bytes) and len(element) <= dtype.itemsize:
+            return element
+        raise LossySetitemError
+
+    if dtype.kind == "V":
+        # i.e. np.void, which cannot hold _anything_
+        raise LossySetitemError
+
+    raise NotImplementedError(dtype)
+
+
+def _dtype_can_hold_range(rng: range, dtype: np.dtype) -> bool:
+    """
+    _maybe_infer_dtype_type infers to int64 (and float64 for very large endpoints),
+    but in many cases a range can be held by a smaller integer dtype.
+    Check if this is one of those cases.
+    """
+    if not len(rng):
+        return True
+    return np_can_cast_scalar(rng.start, dtype) and np_can_cast_scalar(rng.stop, dtype)
+
+
+def np_can_cast_scalar(element: Scalar, dtype: np.dtype) -> bool:
+    """
+    np.can_cast pandas-equivalent for pre 2-0 behavior that allowed scalar
+    inference
+
+    Parameters
+    ----------
+    element : Scalar
+    dtype : np.dtype
+
+    Returns
+    -------
+    bool
+    """
+    try:
+        np_can_hold_element(dtype, element)
+        return True
+    except (LossySetitemError, NotImplementedError):
+        return False
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/common.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..6dea15ac0bc2474b222762505b50efc0dbe680e5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/common.py
@@ -0,0 +1,1766 @@
+"""
+Common type operations.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import (
+    Interval,
+    Period,
+    algos,
+    lib,
+)
+from pandas._libs.tslibs import conversion
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import _registry as registry
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    IntervalDtype,
+    PeriodDtype,
+    SparseDtype,
+)
+from pandas.core.dtypes.generic import ABCIndex
+from pandas.core.dtypes.inference import (
+    is_array_like,
+    is_bool,
+    is_complex,
+    is_dataclass,
+    is_decimal,
+    is_dict_like,
+    is_file_like,
+    is_float,
+    is_hashable,
+    is_integer,
+    is_interval,
+    is_iterator,
+    is_list_like,
+    is_named_tuple,
+    is_nested_list_like,
+    is_number,
+    is_re,
+    is_re_compilable,
+    is_scalar,
+    is_sequence,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        DtypeObj,
+    )
+
+DT64NS_DTYPE = conversion.DT64NS_DTYPE
+TD64NS_DTYPE = conversion.TD64NS_DTYPE
+INT64_DTYPE = np.dtype(np.int64)
+
+# oh the troubles to reduce import time
+_is_scipy_sparse = None
+
+ensure_float64 = algos.ensure_float64
+ensure_int64 = algos.ensure_int64
+ensure_int32 = algos.ensure_int32
+ensure_int16 = algos.ensure_int16
+ensure_int8 = algos.ensure_int8
+ensure_platform_int = algos.ensure_platform_int
+ensure_object = algos.ensure_object
+ensure_uint64 = algos.ensure_uint64
+
+
+def ensure_str(value: bytes | Any) -> str:
+    """
+    Ensure that bytes and non-strings get converted into ``str`` objects.
+    """
+    if isinstance(value, bytes):
+        value = value.decode("utf-8")
+    elif not isinstance(value, str):
+        value = str(value)
+    return value
+
+
+def ensure_python_int(value: int | np.integer) -> int:
+    """
+    Ensure that a value is a python int.
+
+    Parameters
+    ----------
+    value: int or numpy.integer
+
+    Returns
+    -------
+    int
+
+    Raises
+    ------
+    TypeError: if the value isn't an int or can't be converted to one.
+    """
+    if not (is_integer(value) or is_float(value)):
+        if not is_scalar(value):
+            raise TypeError(
+                f"Value needs to be a scalar value, was type {type(value).__name__}"
+            )
+        raise TypeError(f"Wrong type {type(value)} for value {value}")
+    try:
+        new_value = int(value)
+        assert new_value == value
+    except (TypeError, ValueError, AssertionError) as err:
+        raise TypeError(f"Wrong type {type(value)} for value {value}") from err
+    return new_value
+
+
+def classes(*klasses) -> Callable:
+    """Evaluate if the tipo is a subclass of the klasses."""
+    return lambda tipo: issubclass(tipo, klasses)
+
+
+def _classes_and_not_datetimelike(*klasses) -> Callable:
+    """
+    Evaluate if the tipo is a subclass of the klasses
+    and not a datetimelike.
+    """
+    return lambda tipo: (
+        issubclass(tipo, klasses)
+        and not issubclass(tipo, (np.datetime64, np.timedelta64))
+    )
+
+
+def is_object_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the object dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the object dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_object_dtype
+    >>> is_object_dtype(object)
+    True
+    >>> is_object_dtype(int)
+    False
+    >>> is_object_dtype(np.array([], dtype=object))
+    True
+    >>> is_object_dtype(np.array([], dtype=int))
+    False
+    >>> is_object_dtype([1, 2, 3])
+    False
+    """
+    return _is_dtype_type(arr_or_dtype, classes(np.object_))
+
+
+def is_sparse(arr) -> bool:
+    """
+    Check whether an array-like is a 1-D pandas sparse array.
+
+    .. deprecated:: 2.1.0
+        Use isinstance(dtype, pd.SparseDtype) instead.
+
+    Check that the one-dimensional array-like is a pandas sparse array.
+    Returns True if it is a pandas sparse array, not another type of
+    sparse array.
+
+    Parameters
+    ----------
+    arr : array-like
+        Array-like to check.
+
+    Returns
+    -------
+    bool
+        Whether or not the array-like is a pandas sparse array.
+
+    Examples
+    --------
+    Returns `True` if the parameter is a 1-D pandas sparse array.
+
+    >>> from pandas.api.types import is_sparse
+    >>> is_sparse(pd.arrays.SparseArray([0, 0, 1, 0]))
+    True
+    >>> is_sparse(pd.Series(pd.arrays.SparseArray([0, 0, 1, 0])))
+    True
+
+    Returns `False` if the parameter is not sparse.
+
+    >>> is_sparse(np.array([0, 0, 1, 0]))
+    False
+    >>> is_sparse(pd.Series([0, 1, 0, 0]))
+    False
+
+    Returns `False` if the parameter is not a pandas sparse array.
+
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_sparse(bsr_matrix([0, 1, 0, 0]))
+    False
+
+    Returns `False` if the parameter has more than one dimension.
+    """
+    warnings.warn(
+        "is_sparse is deprecated and will be removed in a future "
+        "version. Check `isinstance(dtype, pd.SparseDtype)` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+
+    dtype = getattr(arr, "dtype", arr)
+    return isinstance(dtype, SparseDtype)
+
+
+def is_scipy_sparse(arr) -> bool:
+    """
+    Check whether an array-like is a scipy.sparse.spmatrix instance.
+
+    Parameters
+    ----------
+    arr : array-like
+        The array-like to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like is a scipy.sparse.spmatrix instance.
+
+    Notes
+    -----
+    If scipy is not installed, this function will always return False.
+
+    Examples
+    --------
+    >>> from scipy.sparse import bsr_matrix
+    >>> is_scipy_sparse(bsr_matrix([1, 2, 3]))
+    True
+    >>> is_scipy_sparse(pd.arrays.SparseArray([1, 2, 3]))
+    False
+    """
+    global _is_scipy_sparse
+
+    if _is_scipy_sparse is None:  # pylint: disable=used-before-assignment
+        try:
+            from scipy.sparse import issparse as _is_scipy_sparse
+        except ImportError:
+            _is_scipy_sparse = lambda _: False
+
+    assert _is_scipy_sparse is not None
+    return _is_scipy_sparse(arr)
+
+
+def is_datetime64_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the datetime64 dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the datetime64 dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_datetime64_dtype
+    >>> is_datetime64_dtype(object)
+    False
+    >>> is_datetime64_dtype(np.datetime64)
+    True
+    >>> is_datetime64_dtype(np.array([], dtype=int))
+    False
+    >>> is_datetime64_dtype(np.array([], dtype=np.datetime64))
+    True
+    >>> is_datetime64_dtype([1, 2, 3])
+    False
+    """
+    if isinstance(arr_or_dtype, np.dtype):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.kind == "M"
+    return _is_dtype_type(arr_or_dtype, classes(np.datetime64))
+
+
+def is_datetime64tz_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of a DatetimeTZDtype dtype.
+
+    .. deprecated:: 2.1.0
+        Use isinstance(dtype, pd.DatetimeTZDtype) instead.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of a DatetimeTZDtype dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_datetime64tz_dtype
+    >>> is_datetime64tz_dtype(object)
+    False
+    >>> is_datetime64tz_dtype([1, 2, 3])
+    False
+    >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3]))  # tz-naive
+    False
+    >>> is_datetime64tz_dtype(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
+    True
+
+    >>> from pandas.core.dtypes.dtypes import DatetimeTZDtype
+    >>> dtype = DatetimeTZDtype("ns", tz="US/Eastern")
+    >>> s = pd.Series([], dtype=dtype)
+    >>> is_datetime64tz_dtype(dtype)
+    True
+    >>> is_datetime64tz_dtype(s)
+    True
+    """
+    # GH#52607
+    warnings.warn(
+        "is_datetime64tz_dtype is deprecated and will be removed in a future "
+        "version. Check `isinstance(dtype, pd.DatetimeTZDtype)` instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if isinstance(arr_or_dtype, DatetimeTZDtype):
+        # GH#33400 fastpath for dtype object
+        # GH 34986
+        return True
+
+    if arr_or_dtype is None:
+        return False
+    return DatetimeTZDtype.is_dtype(arr_or_dtype)
+
+
+def is_timedelta64_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the timedelta64 dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the timedelta64 dtype.
+
+    Examples
+    --------
+    >>> from pandas.core.dtypes.common import is_timedelta64_dtype
+    >>> is_timedelta64_dtype(object)
+    False
+    >>> is_timedelta64_dtype(np.timedelta64)
+    True
+    >>> is_timedelta64_dtype([1, 2, 3])
+    False
+    >>> is_timedelta64_dtype(pd.Series([], dtype="timedelta64[ns]"))
+    True
+    >>> is_timedelta64_dtype('0 days')
+    False
+    """
+    if isinstance(arr_or_dtype, np.dtype):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.kind == "m"
+
+    return _is_dtype_type(arr_or_dtype, classes(np.timedelta64))
+
+
+def is_period_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the Period dtype.
+
+    .. deprecated:: 2.2.0
+        Use isinstance(dtype, pd.Period) instead.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the Period dtype.
+
+    Examples
+    --------
+    >>> from pandas.core.dtypes.common import is_period_dtype
+    >>> is_period_dtype(object)
+    False
+    >>> is_period_dtype(pd.PeriodDtype(freq="D"))
+    True
+    >>> is_period_dtype([1, 2, 3])
+    False
+    >>> is_period_dtype(pd.Period("2017-01-01"))
+    False
+    >>> is_period_dtype(pd.PeriodIndex([], freq="Y"))
+    True
+    """
+    warnings.warn(
+        "is_period_dtype is deprecated and will be removed in a future version. "
+        "Use `isinstance(dtype, pd.PeriodDtype)` instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if isinstance(arr_or_dtype, ExtensionDtype):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.type is Period
+
+    if arr_or_dtype is None:
+        return False
+    return PeriodDtype.is_dtype(arr_or_dtype)
+
+
+def is_interval_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the Interval dtype.
+
+    .. deprecated:: 2.2.0
+        Use isinstance(dtype, pd.IntervalDtype) instead.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the Interval dtype.
+
+    Examples
+    --------
+    >>> from pandas.core.dtypes.common import is_interval_dtype
+    >>> is_interval_dtype(object)
+    False
+    >>> is_interval_dtype(pd.IntervalDtype())
+    True
+    >>> is_interval_dtype([1, 2, 3])
+    False
+    >>>
+    >>> interval = pd.Interval(1, 2, closed="right")
+    >>> is_interval_dtype(interval)
+    False
+    >>> is_interval_dtype(pd.IntervalIndex([interval]))
+    True
+    """
+    # GH#52607
+    warnings.warn(
+        "is_interval_dtype is deprecated and will be removed in a future version. "
+        "Use `isinstance(dtype, pd.IntervalDtype)` instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if isinstance(arr_or_dtype, ExtensionDtype):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.type is Interval
+
+    if arr_or_dtype is None:
+        return False
+    return IntervalDtype.is_dtype(arr_or_dtype)
+
+
+def is_categorical_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether an array-like or dtype is of the Categorical dtype.
+
+    .. deprecated:: 2.2.0
+        Use isinstance(dtype, pd.CategoricalDtype) instead.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array-like or dtype is of the Categorical dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_categorical_dtype
+    >>> from pandas import CategoricalDtype
+    >>> is_categorical_dtype(object)
+    False
+    >>> is_categorical_dtype(CategoricalDtype())
+    True
+    >>> is_categorical_dtype([1, 2, 3])
+    False
+    >>> is_categorical_dtype(pd.Categorical([1, 2, 3]))
+    True
+    >>> is_categorical_dtype(pd.CategoricalIndex([1, 2, 3]))
+    True
+    """
+    # GH#52527
+    warnings.warn(
+        "is_categorical_dtype is deprecated and will be removed in a future "
+        "version. Use isinstance(dtype, pd.CategoricalDtype) instead",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    if isinstance(arr_or_dtype, ExtensionDtype):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.name == "category"
+
+    if arr_or_dtype is None:
+        return False
+    return CategoricalDtype.is_dtype(arr_or_dtype)
+
+
+def is_string_or_object_np_dtype(dtype: np.dtype) -> bool:
+    """
+    Faster alternative to is_string_dtype, assumes we have a np.dtype object.
+    """
+    return dtype == object or dtype.kind in "SU"
+
+
+def is_string_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of the string dtype.
+
+    If an array is passed with an object dtype, the elements must be
+    inferred as strings.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of the string dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_string_dtype
+    >>> is_string_dtype(str)
+    True
+    >>> is_string_dtype(object)
+    True
+    >>> is_string_dtype(int)
+    False
+    >>> is_string_dtype(np.array(['a', 'b']))
+    True
+    >>> is_string_dtype(pd.Series([1, 2]))
+    False
+    >>> is_string_dtype(pd.Series([1, 2], dtype=object))
+    False
+    """
+    if hasattr(arr_or_dtype, "dtype") and _get_dtype(arr_or_dtype).kind == "O":
+        return is_all_strings(arr_or_dtype)
+
+    def condition(dtype) -> bool:
+        if is_string_or_object_np_dtype(dtype):
+            return True
+        try:
+            return dtype == "string"
+        except TypeError:
+            return False
+
+    return _is_dtype(arr_or_dtype, condition)
+
+
+def is_dtype_equal(source, target) -> bool:
+    """
+    Check if two dtypes are equal.
+
+    Parameters
+    ----------
+    source : The first dtype to compare
+    target : The second dtype to compare
+
+    Returns
+    -------
+    boolean
+        Whether or not the two dtypes are equal.
+
+    Examples
+    --------
+    >>> is_dtype_equal(int, float)
+    False
+    >>> is_dtype_equal("int", int)
+    True
+    >>> is_dtype_equal(object, "category")
+    False
+    >>> is_dtype_equal(CategoricalDtype(), "category")
+    True
+    >>> is_dtype_equal(DatetimeTZDtype(tz="UTC"), "datetime64")
+    False
+    """
+    if isinstance(target, str):
+        if not isinstance(source, str):
+            # GH#38516 ensure we get the same behavior from
+            #  is_dtype_equal(CDT, "category") and CDT == "category"
+            try:
+                src = _get_dtype(source)
+                if isinstance(src, ExtensionDtype):
+                    return src == target
+            except (TypeError, AttributeError, ImportError):
+                return False
+    elif isinstance(source, str):
+        return is_dtype_equal(target, source)
+
+    try:
+        source = _get_dtype(source)
+        target = _get_dtype(target)
+        return source == target
+    except (TypeError, AttributeError, ImportError):
+        # invalid comparison
+        # object == category will hit this
+        return False
+
+
+def is_integer_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of an integer dtype.
+
+    Unlike in `is_any_int_dtype`, timedelta64 instances will return False.
+
+    The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
+    as integer by this function.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of an integer dtype and
+        not an instance of timedelta64.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_integer_dtype
+    >>> is_integer_dtype(str)
+    False
+    >>> is_integer_dtype(int)
+    True
+    >>> is_integer_dtype(float)
+    False
+    >>> is_integer_dtype(np.uint64)
+    True
+    >>> is_integer_dtype('int8')
+    True
+    >>> is_integer_dtype('Int8')
+    True
+    >>> is_integer_dtype(pd.Int8Dtype)
+    True
+    >>> is_integer_dtype(np.datetime64)
+    False
+    >>> is_integer_dtype(np.timedelta64)
+    False
+    >>> is_integer_dtype(np.array(['a', 'b']))
+    False
+    >>> is_integer_dtype(pd.Series([1, 2]))
+    True
+    >>> is_integer_dtype(np.array([], dtype=np.timedelta64))
+    False
+    >>> is_integer_dtype(pd.Index([1, 2.]))  # float
+    False
+    """
+    return _is_dtype_type(
+        arr_or_dtype, _classes_and_not_datetimelike(np.integer)
+    ) or _is_dtype(
+        arr_or_dtype, lambda typ: isinstance(typ, ExtensionDtype) and typ.kind in "iu"
+    )
+
+
+def is_signed_integer_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a signed integer dtype.
+
+    Unlike in `is_any_int_dtype`, timedelta64 instances will return False.
+
+    The nullable Integer dtypes (e.g. pandas.Int64Dtype) are also considered
+    as integer by this function.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a signed integer dtype
+        and not an instance of timedelta64.
+
+    Examples
+    --------
+    >>> from pandas.core.dtypes.common import is_signed_integer_dtype
+    >>> is_signed_integer_dtype(str)
+    False
+    >>> is_signed_integer_dtype(int)
+    True
+    >>> is_signed_integer_dtype(float)
+    False
+    >>> is_signed_integer_dtype(np.uint64)  # unsigned
+    False
+    >>> is_signed_integer_dtype('int8')
+    True
+    >>> is_signed_integer_dtype('Int8')
+    True
+    >>> is_signed_integer_dtype(pd.Int8Dtype)
+    True
+    >>> is_signed_integer_dtype(np.datetime64)
+    False
+    >>> is_signed_integer_dtype(np.timedelta64)
+    False
+    >>> is_signed_integer_dtype(np.array(['a', 'b']))
+    False
+    >>> is_signed_integer_dtype(pd.Series([1, 2]))
+    True
+    >>> is_signed_integer_dtype(np.array([], dtype=np.timedelta64))
+    False
+    >>> is_signed_integer_dtype(pd.Index([1, 2.]))  # float
+    False
+    >>> is_signed_integer_dtype(np.array([1, 2], dtype=np.uint32))  # unsigned
+    False
+    """
+    return _is_dtype_type(
+        arr_or_dtype, _classes_and_not_datetimelike(np.signedinteger)
+    ) or _is_dtype(
+        arr_or_dtype, lambda typ: isinstance(typ, ExtensionDtype) and typ.kind == "i"
+    )
+
+
+def is_unsigned_integer_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of an unsigned integer dtype.
+
+    The nullable Integer dtypes (e.g. pandas.UInt64Dtype) are also
+    considered as integer by this function.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of an unsigned integer dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_unsigned_integer_dtype
+    >>> is_unsigned_integer_dtype(str)
+    False
+    >>> is_unsigned_integer_dtype(int)  # signed
+    False
+    >>> is_unsigned_integer_dtype(float)
+    False
+    >>> is_unsigned_integer_dtype(np.uint64)
+    True
+    >>> is_unsigned_integer_dtype('uint8')
+    True
+    >>> is_unsigned_integer_dtype('UInt8')
+    True
+    >>> is_unsigned_integer_dtype(pd.UInt8Dtype)
+    True
+    >>> is_unsigned_integer_dtype(np.array(['a', 'b']))
+    False
+    >>> is_unsigned_integer_dtype(pd.Series([1, 2]))  # signed
+    False
+    >>> is_unsigned_integer_dtype(pd.Index([1, 2.]))  # float
+    False
+    >>> is_unsigned_integer_dtype(np.array([1, 2], dtype=np.uint32))
+    True
+    """
+    return _is_dtype_type(
+        arr_or_dtype, _classes_and_not_datetimelike(np.unsignedinteger)
+    ) or _is_dtype(
+        arr_or_dtype, lambda typ: isinstance(typ, ExtensionDtype) and typ.kind == "u"
+    )
+
+
+def is_int64_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of the int64 dtype.
+
+    .. deprecated:: 2.1.0
+
+       is_int64_dtype is deprecated and will be removed in a future
+       version. Use dtype == np.int64 instead.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of the int64 dtype.
+
+    Notes
+    -----
+    Depending on system architecture, the return value of `is_int64_dtype(
+    int)` will be True if the OS uses 64-bit integers and False if the OS
+    uses 32-bit integers.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_int64_dtype
+    >>> is_int64_dtype(str)  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.int32)  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.int64)  # doctest: +SKIP
+    True
+    >>> is_int64_dtype('int8')  # doctest: +SKIP
+    False
+    >>> is_int64_dtype('Int8')  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(pd.Int64Dtype)  # doctest: +SKIP
+    True
+    >>> is_int64_dtype(float)  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.uint64)  # unsigned  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.array(['a', 'b']))  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.array([1, 2], dtype=np.int64))  # doctest: +SKIP
+    True
+    >>> is_int64_dtype(pd.Index([1, 2.]))  # float  # doctest: +SKIP
+    False
+    >>> is_int64_dtype(np.array([1, 2], dtype=np.uint32))  # unsigned  # doctest: +SKIP
+    False
+    """
+    # GH#52564
+    warnings.warn(
+        "is_int64_dtype is deprecated and will be removed in a future "
+        "version. Use dtype == np.int64 instead.",
+        DeprecationWarning,
+        stacklevel=2,
+    )
+    return _is_dtype_type(arr_or_dtype, classes(np.int64))
+
+
+def is_datetime64_any_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of the datetime64 dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    bool
+        Whether or not the array or dtype is of the datetime64 dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_datetime64_any_dtype
+    >>> from pandas.core.dtypes.dtypes import DatetimeTZDtype
+    >>> is_datetime64_any_dtype(str)
+    False
+    >>> is_datetime64_any_dtype(int)
+    False
+    >>> is_datetime64_any_dtype(np.datetime64)  # can be tz-naive
+    True
+    >>> is_datetime64_any_dtype(DatetimeTZDtype("ns", "US/Eastern"))
+    True
+    >>> is_datetime64_any_dtype(np.array(['a', 'b']))
+    False
+    >>> is_datetime64_any_dtype(np.array([1, 2]))
+    False
+    >>> is_datetime64_any_dtype(np.array([], dtype="datetime64[ns]"))
+    True
+    >>> is_datetime64_any_dtype(pd.DatetimeIndex([1, 2, 3], dtype="datetime64[ns]"))
+    True
+    """
+    if isinstance(arr_or_dtype, (np.dtype, ExtensionDtype)):
+        # GH#33400 fastpath for dtype object
+        return arr_or_dtype.kind == "M"
+
+    if arr_or_dtype is None:
+        return False
+
+    try:
+        tipo = _get_dtype(arr_or_dtype)
+    except TypeError:
+        return False
+    return lib.is_np_dtype(tipo, "M") or isinstance(tipo, DatetimeTZDtype)
+
+
+def is_datetime64_ns_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of the datetime64[ns] dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    bool
+        Whether or not the array or dtype is of the datetime64[ns] dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_datetime64_ns_dtype
+    >>> from pandas.core.dtypes.dtypes import DatetimeTZDtype
+    >>> is_datetime64_ns_dtype(str)
+    False
+    >>> is_datetime64_ns_dtype(int)
+    False
+    >>> is_datetime64_ns_dtype(np.datetime64)  # no unit
+    False
+    >>> is_datetime64_ns_dtype(DatetimeTZDtype("ns", "US/Eastern"))
+    True
+    >>> is_datetime64_ns_dtype(np.array(['a', 'b']))
+    False
+    >>> is_datetime64_ns_dtype(np.array([1, 2]))
+    False
+    >>> is_datetime64_ns_dtype(np.array([], dtype="datetime64"))  # no unit
+    False
+    >>> is_datetime64_ns_dtype(np.array([], dtype="datetime64[ps]"))  # wrong unit
+    False
+    >>> is_datetime64_ns_dtype(pd.DatetimeIndex([1, 2, 3], dtype="datetime64[ns]"))
+    True
+    """
+    if arr_or_dtype is None:
+        return False
+    try:
+        tipo = _get_dtype(arr_or_dtype)
+    except TypeError:
+        return False
+    return tipo == DT64NS_DTYPE or (
+        isinstance(tipo, DatetimeTZDtype) and tipo.unit == "ns"
+    )
+
+
+def is_timedelta64_ns_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of the timedelta64[ns] dtype.
+
+    This is a very specific dtype, so generic ones like `np.timedelta64`
+    will return False if passed into this function.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of the timedelta64[ns] dtype.
+
+    Examples
+    --------
+    >>> from pandas.core.dtypes.common import is_timedelta64_ns_dtype
+    >>> is_timedelta64_ns_dtype(np.dtype('m8[ns]'))
+    True
+    >>> is_timedelta64_ns_dtype(np.dtype('m8[ps]'))  # Wrong frequency
+    False
+    >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype='m8[ns]'))
+    True
+    >>> is_timedelta64_ns_dtype(np.array([1, 2], dtype=np.timedelta64))
+    False
+    """
+    return _is_dtype(arr_or_dtype, lambda dtype: dtype == TD64NS_DTYPE)
+
+
+# This exists to silence numpy deprecation warnings, see GH#29553
+def is_numeric_v_string_like(a: ArrayLike, b) -> bool:
+    """
+    Check if we are comparing a string-like object to a numeric ndarray.
+    NumPy doesn't like to compare such objects, especially numeric arrays
+    and scalar string-likes.
+
+    Parameters
+    ----------
+    a : array-like, scalar
+        The first object to check.
+    b : array-like, scalar
+        The second object to check.
+
+    Returns
+    -------
+    boolean
+        Whether we return a comparing a string-like object to a numeric array.
+
+    Examples
+    --------
+    >>> is_numeric_v_string_like(np.array([1]), "foo")
+    True
+    >>> is_numeric_v_string_like(np.array([1, 2]), np.array(["foo"]))
+    True
+    >>> is_numeric_v_string_like(np.array(["foo"]), np.array([1, 2]))
+    True
+    >>> is_numeric_v_string_like(np.array([1]), np.array([2]))
+    False
+    >>> is_numeric_v_string_like(np.array(["foo"]), np.array(["foo"]))
+    False
+    """
+    is_a_array = isinstance(a, np.ndarray)
+    is_b_array = isinstance(b, np.ndarray)
+
+    is_a_numeric_array = is_a_array and a.dtype.kind in ("u", "i", "f", "c", "b")
+    is_b_numeric_array = is_b_array and b.dtype.kind in ("u", "i", "f", "c", "b")
+    is_a_string_array = is_a_array and a.dtype.kind in ("S", "U")
+    is_b_string_array = is_b_array and b.dtype.kind in ("S", "U")
+
+    is_b_scalar_string_like = not is_b_array and isinstance(b, str)
+
+    return (
+        (is_a_numeric_array and is_b_scalar_string_like)
+        or (is_a_numeric_array and is_b_string_array)
+        or (is_b_numeric_array and is_a_string_array)
+    )
+
+
+def needs_i8_conversion(dtype: DtypeObj | None) -> bool:
+    """
+    Check whether the dtype should be converted to int64.
+
+    Dtype "needs" such a conversion if the dtype is of a datetime-like dtype
+
+    Parameters
+    ----------
+    dtype : np.dtype, ExtensionDtype, or None
+
+    Returns
+    -------
+    boolean
+        Whether or not the dtype should be converted to int64.
+
+    Examples
+    --------
+    >>> needs_i8_conversion(str)
+    False
+    >>> needs_i8_conversion(np.int64)
+    False
+    >>> needs_i8_conversion(np.datetime64)
+    False
+    >>> needs_i8_conversion(np.dtype(np.datetime64))
+    True
+    >>> needs_i8_conversion(np.array(['a', 'b']))
+    False
+    >>> needs_i8_conversion(pd.Series([1, 2]))
+    False
+    >>> needs_i8_conversion(pd.Series([], dtype="timedelta64[ns]"))
+    False
+    >>> needs_i8_conversion(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern"))
+    False
+    >>> needs_i8_conversion(pd.DatetimeIndex([1, 2, 3], tz="US/Eastern").dtype)
+    True
+    """
+    if isinstance(dtype, np.dtype):
+        return dtype.kind in "mM"
+    return isinstance(dtype, (PeriodDtype, DatetimeTZDtype))
+
+
+def is_numeric_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a numeric dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a numeric dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_numeric_dtype
+    >>> is_numeric_dtype(str)
+    False
+    >>> is_numeric_dtype(int)
+    True
+    >>> is_numeric_dtype(float)
+    True
+    >>> is_numeric_dtype(np.uint64)
+    True
+    >>> is_numeric_dtype(np.datetime64)
+    False
+    >>> is_numeric_dtype(np.timedelta64)
+    False
+    >>> is_numeric_dtype(np.array(['a', 'b']))
+    False
+    >>> is_numeric_dtype(pd.Series([1, 2]))
+    True
+    >>> is_numeric_dtype(pd.Index([1, 2.]))
+    True
+    >>> is_numeric_dtype(np.array([], dtype=np.timedelta64))
+    False
+    """
+    return _is_dtype_type(
+        arr_or_dtype, _classes_and_not_datetimelike(np.number, np.bool_)
+    ) or _is_dtype(
+        arr_or_dtype, lambda typ: isinstance(typ, ExtensionDtype) and typ._is_numeric
+    )
+
+
+def is_any_real_numeric_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a real number dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a real number dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_any_real_numeric_dtype
+    >>> is_any_real_numeric_dtype(int)
+    True
+    >>> is_any_real_numeric_dtype(float)
+    True
+    >>> is_any_real_numeric_dtype(object)
+    False
+    >>> is_any_real_numeric_dtype(str)
+    False
+    >>> is_any_real_numeric_dtype(complex(1, 2))
+    False
+    >>> is_any_real_numeric_dtype(bool)
+    False
+    """
+    return (
+        is_numeric_dtype(arr_or_dtype)
+        and not is_complex_dtype(arr_or_dtype)
+        and not is_bool_dtype(arr_or_dtype)
+    )
+
+
+def is_float_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a float dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a float dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_float_dtype
+    >>> is_float_dtype(str)
+    False
+    >>> is_float_dtype(int)
+    False
+    >>> is_float_dtype(float)
+    True
+    >>> is_float_dtype(np.array(['a', 'b']))
+    False
+    >>> is_float_dtype(pd.Series([1, 2]))
+    False
+    >>> is_float_dtype(pd.Index([1, 2.]))
+    True
+    """
+    return _is_dtype_type(arr_or_dtype, classes(np.floating)) or _is_dtype(
+        arr_or_dtype, lambda typ: isinstance(typ, ExtensionDtype) and typ.kind in "f"
+    )
+
+
+def is_bool_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a boolean dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a boolean dtype.
+
+    Notes
+    -----
+    An ExtensionArray is considered boolean when the ``_is_boolean``
+    attribute is set to True.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_bool_dtype
+    >>> is_bool_dtype(str)
+    False
+    >>> is_bool_dtype(int)
+    False
+    >>> is_bool_dtype(bool)
+    True
+    >>> is_bool_dtype(np.bool_)
+    True
+    >>> is_bool_dtype(np.array(['a', 'b']))
+    False
+    >>> is_bool_dtype(pd.Series([1, 2]))
+    False
+    >>> is_bool_dtype(np.array([True, False]))
+    True
+    >>> is_bool_dtype(pd.Categorical([True, False]))
+    True
+    >>> is_bool_dtype(pd.arrays.SparseArray([True, False]))
+    True
+    """
+    if arr_or_dtype is None:
+        return False
+    try:
+        dtype = _get_dtype(arr_or_dtype)
+    except (TypeError, ValueError):
+        return False
+
+    if isinstance(dtype, CategoricalDtype):
+        arr_or_dtype = dtype.categories
+        # now we use the special definition for Index
+
+    if isinstance(arr_or_dtype, ABCIndex):
+        # Allow Index[object] that is all-bools or Index["boolean"]
+        if arr_or_dtype.inferred_type == "boolean":
+            if not is_bool_dtype(arr_or_dtype.dtype):
+                # GH#52680
+                warnings.warn(
+                    "The behavior of is_bool_dtype with an object-dtype Index "
+                    "of bool objects is deprecated. In a future version, "
+                    "this will return False. Cast the Index to a bool dtype instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            return True
+        return False
+    elif isinstance(dtype, ExtensionDtype):
+        return getattr(dtype, "_is_boolean", False)
+
+    return issubclass(dtype.type, np.bool_)
+
+
+def is_1d_only_ea_dtype(dtype: DtypeObj | None) -> bool:
+    """
+    Analogue to is_extension_array_dtype but excluding DatetimeTZDtype.
+    """
+    return isinstance(dtype, ExtensionDtype) and not dtype._supports_2d
+
+
+def is_extension_array_dtype(arr_or_dtype) -> bool:
+    """
+    Check if an object is a pandas extension array type.
+
+    See the :ref:`Use Guide ` for more.
+
+    Parameters
+    ----------
+    arr_or_dtype : object
+        For array-like input, the ``.dtype`` attribute will
+        be extracted.
+
+    Returns
+    -------
+    bool
+        Whether the `arr_or_dtype` is an extension array type.
+
+    Notes
+    -----
+    This checks whether an object implements the pandas extension
+    array interface. In pandas, this includes:
+
+    * Categorical
+    * Sparse
+    * Interval
+    * Period
+    * DatetimeArray
+    * TimedeltaArray
+
+    Third-party libraries may implement arrays or types satisfying
+    this interface as well.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_extension_array_dtype
+    >>> arr = pd.Categorical(['a', 'b'])
+    >>> is_extension_array_dtype(arr)
+    True
+    >>> is_extension_array_dtype(arr.dtype)
+    True
+
+    >>> arr = np.array(['a', 'b'])
+    >>> is_extension_array_dtype(arr.dtype)
+    False
+    """
+    dtype = getattr(arr_or_dtype, "dtype", arr_or_dtype)
+    if isinstance(dtype, ExtensionDtype):
+        return True
+    elif isinstance(dtype, np.dtype):
+        return False
+    else:
+        try:
+            with warnings.catch_warnings():
+                # pandas_dtype(..) can raise UserWarning for class input
+                warnings.simplefilter("ignore", UserWarning)
+                dtype = pandas_dtype(dtype)
+        except (TypeError, ValueError):
+            # np.dtype(..) can raise ValueError
+            return False
+        return isinstance(dtype, ExtensionDtype)
+
+
+def is_ea_or_datetimelike_dtype(dtype: DtypeObj | None) -> bool:
+    """
+    Check for ExtensionDtype, datetime64 dtype, or timedelta64 dtype.
+
+    Notes
+    -----
+    Checks only for dtype objects, not dtype-castable strings or types.
+    """
+    return isinstance(dtype, ExtensionDtype) or (lib.is_np_dtype(dtype, "mM"))
+
+
+def is_complex_dtype(arr_or_dtype) -> bool:
+    """
+    Check whether the provided array or dtype is of a complex dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array or dtype to check.
+
+    Returns
+    -------
+    boolean
+        Whether or not the array or dtype is of a complex dtype.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_complex_dtype
+    >>> is_complex_dtype(str)
+    False
+    >>> is_complex_dtype(int)
+    False
+    >>> is_complex_dtype(np.complex128)
+    True
+    >>> is_complex_dtype(np.array(['a', 'b']))
+    False
+    >>> is_complex_dtype(pd.Series([1, 2]))
+    False
+    >>> is_complex_dtype(np.array([1 + 1j, 5]))
+    True
+    """
+    return _is_dtype_type(arr_or_dtype, classes(np.complexfloating))
+
+
+def _is_dtype(arr_or_dtype, condition) -> bool:
+    """
+    Return true if the condition is satisfied for the arr_or_dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like, str, np.dtype, or ExtensionArrayType
+        The array-like or dtype object whose dtype we want to extract.
+    condition : callable[Union[np.dtype, ExtensionDtype]]
+
+    Returns
+    -------
+    bool
+
+    """
+    if arr_or_dtype is None:
+        return False
+    try:
+        dtype = _get_dtype(arr_or_dtype)
+    except (TypeError, ValueError):
+        return False
+    return condition(dtype)
+
+
+def _get_dtype(arr_or_dtype) -> DtypeObj:
+    """
+    Get the dtype instance associated with an array
+    or dtype object.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype object whose dtype we want to extract.
+
+    Returns
+    -------
+    obj_dtype : The extract dtype instance from the
+                passed in array or dtype object.
+
+    Raises
+    ------
+    TypeError : The passed in object is None.
+    """
+    if arr_or_dtype is None:
+        raise TypeError("Cannot deduce dtype from null object")
+
+    # fastpath
+    if isinstance(arr_or_dtype, np.dtype):
+        return arr_or_dtype
+    elif isinstance(arr_or_dtype, type):
+        return np.dtype(arr_or_dtype)
+
+    # if we have an array-like
+    elif hasattr(arr_or_dtype, "dtype"):
+        arr_or_dtype = arr_or_dtype.dtype
+
+    return pandas_dtype(arr_or_dtype)
+
+
+def _is_dtype_type(arr_or_dtype, condition) -> bool:
+    """
+    Return true if the condition is satisfied for the arr_or_dtype.
+
+    Parameters
+    ----------
+    arr_or_dtype : array-like or dtype
+        The array-like or dtype object whose dtype we want to extract.
+    condition : callable[Union[np.dtype, ExtensionDtypeType]]
+
+    Returns
+    -------
+    bool : if the condition is satisfied for the arr_or_dtype
+    """
+    if arr_or_dtype is None:
+        return condition(type(None))
+
+    # fastpath
+    if isinstance(arr_or_dtype, np.dtype):
+        return condition(arr_or_dtype.type)
+    elif isinstance(arr_or_dtype, type):
+        if issubclass(arr_or_dtype, ExtensionDtype):
+            arr_or_dtype = arr_or_dtype.type
+        return condition(np.dtype(arr_or_dtype).type)
+
+    # if we have an array-like
+    if hasattr(arr_or_dtype, "dtype"):
+        arr_or_dtype = arr_or_dtype.dtype
+
+    # we are not possibly a dtype
+    elif is_list_like(arr_or_dtype):
+        return condition(type(None))
+
+    try:
+        tipo = pandas_dtype(arr_or_dtype).type
+    except (TypeError, ValueError):
+        if is_scalar(arr_or_dtype):
+            return condition(type(None))
+
+        return False
+
+    return condition(tipo)
+
+
+def infer_dtype_from_object(dtype) -> type:
+    """
+    Get a numpy dtype.type-style object for a dtype object.
+
+    This methods also includes handling of the datetime64[ns] and
+    datetime64[ns, TZ] objects.
+
+    If no dtype can be found, we return ``object``.
+
+    Parameters
+    ----------
+    dtype : dtype, type
+        The dtype object whose numpy dtype.type-style
+        object we want to extract.
+
+    Returns
+    -------
+    type
+    """
+    if isinstance(dtype, type) and issubclass(dtype, np.generic):
+        # Type object from a dtype
+
+        return dtype
+    elif isinstance(dtype, (np.dtype, ExtensionDtype)):
+        # dtype object
+        try:
+            _validate_date_like_dtype(dtype)
+        except TypeError:
+            # Should still pass if we don't have a date-like
+            pass
+        if hasattr(dtype, "numpy_dtype"):
+            # TODO: Implement this properly
+            # https://github.com/pandas-dev/pandas/issues/52576
+            return dtype.numpy_dtype.type
+        return dtype.type
+
+    try:
+        dtype = pandas_dtype(dtype)
+    except TypeError:
+        pass
+
+    if isinstance(dtype, ExtensionDtype):
+        return dtype.type
+    elif isinstance(dtype, str):
+        # TODO(jreback)
+        # should deprecate these
+        if dtype in ["datetimetz", "datetime64tz"]:
+            return DatetimeTZDtype.type
+        elif dtype in ["period"]:
+            raise NotImplementedError
+
+        if dtype in ["datetime", "timedelta"]:
+            dtype += "64"
+        try:
+            return infer_dtype_from_object(getattr(np, dtype))
+        except (AttributeError, TypeError):
+            # Handles cases like _get_dtype(int) i.e.,
+            # Python objects that are valid dtypes
+            # (unlike user-defined types, in general)
+            #
+            # TypeError handles the float16 type code of 'e'
+            # further handle internal types
+            pass
+
+    return infer_dtype_from_object(np.dtype(dtype))
+
+
+def _validate_date_like_dtype(dtype) -> None:
+    """
+    Check whether the dtype is a date-like dtype. Raises an error if invalid.
+
+    Parameters
+    ----------
+    dtype : dtype, type
+        The dtype to check.
+
+    Raises
+    ------
+    TypeError : The dtype could not be casted to a date-like dtype.
+    ValueError : The dtype is an illegal date-like dtype (e.g. the
+                 frequency provided is too specific)
+    """
+    try:
+        typ = np.datetime_data(dtype)[0]
+    except ValueError as e:
+        raise TypeError(e) from e
+    if typ not in ["generic", "ns"]:
+        raise ValueError(
+            f"{repr(dtype.name)} is too specific of a frequency, "
+            f"try passing {repr(dtype.type.__name__)}"
+        )
+
+
+def validate_all_hashable(*args, error_name: str | None = None) -> None:
+    """
+    Return None if all args are hashable, else raise a TypeError.
+
+    Parameters
+    ----------
+    *args
+        Arguments to validate.
+    error_name : str, optional
+        The name to use if error
+
+    Raises
+    ------
+    TypeError : If an argument is not hashable
+
+    Returns
+    -------
+    None
+    """
+    if not all(is_hashable(arg) for arg in args):
+        if error_name:
+            raise TypeError(f"{error_name} must be a hashable type")
+        raise TypeError("All elements must be hashable")
+
+
+def pandas_dtype(dtype) -> DtypeObj:
+    """
+    Convert input into a pandas only dtype object or a numpy dtype object.
+
+    Parameters
+    ----------
+    dtype : object to be converted
+
+    Returns
+    -------
+    np.dtype or a pandas dtype
+
+    Raises
+    ------
+    TypeError if not a dtype
+
+    Examples
+    --------
+    >>> pd.api.types.pandas_dtype(int)
+    dtype('int64')
+    """
+    # short-circuit
+    if isinstance(dtype, np.ndarray):
+        return dtype.dtype
+    elif isinstance(dtype, (np.dtype, ExtensionDtype)):
+        return dtype
+
+    # builtin aliases
+    if dtype is str and using_string_dtype():
+        from pandas.core.arrays.string_ import StringDtype
+
+        return StringDtype(na_value=np.nan)
+
+    # registered extension types
+    result = registry.find(dtype)
+    if result is not None:
+        if isinstance(result, type):
+            # GH 31356, GH 54592
+            warnings.warn(
+                f"Instantiating {result.__name__} without any arguments."
+                f"Pass a {result.__name__} instance to silence this warning.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+            result = result()
+        return result
+
+    # try a numpy dtype
+    # raise a consistent TypeError if failed
+    try:
+        with warnings.catch_warnings():
+            # TODO: warnings.catch_warnings can be removed when numpy>2.3.0
+            # is the minimum version
+            # GH#51523 - Series.astype(np.integer) doesn't show
+            # numpy deprecation warning of np.integer
+            # Hence enabling DeprecationWarning
+            warnings.simplefilter("always", DeprecationWarning)
+            npdtype = np.dtype(dtype)
+    except SyntaxError as err:
+        # np.dtype uses `eval` which can raise SyntaxError
+        raise TypeError(f"data type '{dtype}' not understood") from err
+
+    # Any invalid dtype (such as pd.Timestamp) should raise an error.
+    # np.dtype(invalid_type).kind = 0 for such objects. However, this will
+    # also catch some valid dtypes such as object, np.object_ and 'object'
+    # which we safeguard against by catching them earlier and returning
+    # np.dtype(valid_dtype) before this condition is evaluated.
+    if is_hashable(dtype) and dtype in [
+        object,
+        np.object_,
+        "object",
+        "O",
+        "object_",
+    ]:
+        # check hashability to avoid errors/DeprecationWarning when we get
+        # here and `dtype` is an array
+        return npdtype
+    elif npdtype.kind == "O":
+        raise TypeError(f"dtype '{dtype}' not understood")
+
+    return npdtype
+
+
+def is_all_strings(value: ArrayLike) -> bool:
+    """
+    Check if this is an array of strings that we should try parsing.
+
+    Includes object-dtype ndarray containing all-strings, StringArray,
+    and Categorical with all-string categories.
+    Does not include numpy string dtypes.
+    """
+    dtype = value.dtype
+
+    if isinstance(dtype, np.dtype):
+        if len(value) == 0:
+            return dtype == np.dtype("object")
+        else:
+            return dtype == np.dtype("object") and lib.is_string_array(
+                np.asarray(value), skipna=False
+            )
+    elif isinstance(dtype, CategoricalDtype):
+        return dtype.categories.inferred_type == "string"
+    return dtype == "string"
+
+
+__all__ = [
+    "classes",
+    "DT64NS_DTYPE",
+    "ensure_float64",
+    "ensure_python_int",
+    "ensure_str",
+    "infer_dtype_from_object",
+    "INT64_DTYPE",
+    "is_1d_only_ea_dtype",
+    "is_all_strings",
+    "is_any_real_numeric_dtype",
+    "is_array_like",
+    "is_bool",
+    "is_bool_dtype",
+    "is_categorical_dtype",
+    "is_complex",
+    "is_complex_dtype",
+    "is_dataclass",
+    "is_datetime64_any_dtype",
+    "is_datetime64_dtype",
+    "is_datetime64_ns_dtype",
+    "is_datetime64tz_dtype",
+    "is_decimal",
+    "is_dict_like",
+    "is_dtype_equal",
+    "is_ea_or_datetimelike_dtype",
+    "is_extension_array_dtype",
+    "is_file_like",
+    "is_float_dtype",
+    "is_int64_dtype",
+    "is_integer_dtype",
+    "is_interval",
+    "is_interval_dtype",
+    "is_iterator",
+    "is_named_tuple",
+    "is_nested_list_like",
+    "is_number",
+    "is_numeric_dtype",
+    "is_object_dtype",
+    "is_period_dtype",
+    "is_re",
+    "is_re_compilable",
+    "is_scipy_sparse",
+    "is_sequence",
+    "is_signed_integer_dtype",
+    "is_sparse",
+    "is_string_dtype",
+    "is_string_or_object_np_dtype",
+    "is_timedelta64_dtype",
+    "is_timedelta64_ns_dtype",
+    "is_unsigned_integer_dtype",
+    "needs_i8_conversion",
+    "pandas_dtype",
+    "TD64NS_DTYPE",
+    "validate_all_hashable",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/concat.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/concat.py
new file mode 100644
index 0000000000000000000000000000000000000000..9ec662a6cd3520aaa49fdc96142ad1b02bb518d8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/concat.py
@@ -0,0 +1,348 @@
+"""
+Utility functions related to concat.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.astype import astype_array
+from pandas.core.dtypes.cast import (
+    common_dtype_categorical_compat,
+    find_common_type,
+    np_find_common_type,
+)
+from pandas.core.dtypes.dtypes import CategoricalDtype
+from pandas.core.dtypes.generic import (
+    ABCCategoricalIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        DtypeObj,
+    )
+
+    from pandas.core.arrays import (
+        Categorical,
+        ExtensionArray,
+    )
+
+
+def _is_nonempty(x, axis) -> bool:
+    # filter empty arrays
+    # 1-d dtypes always are included here
+    if x.ndim <= axis:
+        return True
+    return x.shape[axis] > 0
+
+
+def concat_compat(
+    to_concat: Sequence[ArrayLike], axis: AxisInt = 0, ea_compat_axis: bool = False
+) -> ArrayLike:
+    """
+    provide concatenation of an array of arrays each of which is a single
+    'normalized' dtypes (in that for example, if it's object, then it is a
+    non-datetimelike and provide a combined dtype for the resulting array that
+    preserves the overall dtype if possible)
+
+    Parameters
+    ----------
+    to_concat : sequence of arrays
+    axis : axis to provide concatenation
+    ea_compat_axis : bool, default False
+        For ExtensionArray compat, behave as if axis == 1 when determining
+        whether to drop empty arrays.
+
+    Returns
+    -------
+    a single array, preserving the combined dtypes
+    """
+    if len(to_concat) and lib.dtypes_all_equal([obj.dtype for obj in to_concat]):
+        # fastpath!
+        obj = to_concat[0]
+        if isinstance(obj, np.ndarray):
+            to_concat_arrs = cast("Sequence[np.ndarray]", to_concat)
+            return np.concatenate(to_concat_arrs, axis=axis)
+
+        to_concat_eas = cast("Sequence[ExtensionArray]", to_concat)
+        if ea_compat_axis:
+            # We have 1D objects, that don't support axis keyword
+            return obj._concat_same_type(to_concat_eas)
+        elif axis == 0:
+            return obj._concat_same_type(to_concat_eas)
+        else:
+            # e.g. DatetimeArray
+            # NB: We are assuming here that ensure_wrapped_if_arraylike has
+            #  been called where relevant.
+            return obj._concat_same_type(
+                # error: Unexpected keyword argument "axis" for "_concat_same_type"
+                # of "ExtensionArray"
+                to_concat_eas,
+                axis=axis,  # type: ignore[call-arg]
+            )
+
+    # If all arrays are empty, there's nothing to convert, just short-cut to
+    # the concatenation, #3121.
+    #
+    # Creating an empty array directly is tempting, but the winnings would be
+    # marginal given that it would still require shape & dtype calculation and
+    # np.concatenate which has them both implemented is compiled.
+    orig = to_concat
+    non_empties = [x for x in to_concat if _is_nonempty(x, axis)]
+    if non_empties and axis == 0 and not ea_compat_axis:
+        # ea_compat_axis see GH#39574
+        to_concat = non_empties
+
+    any_ea, kinds, target_dtype = _get_result_dtype(to_concat, non_empties)
+
+    if len(to_concat) < len(orig):
+        _, _, alt_dtype = _get_result_dtype(orig, non_empties)
+        if alt_dtype != target_dtype:
+            # GH#39122
+            warnings.warn(
+                "The behavior of array concatenation with empty entries is "
+                "deprecated. In a future version, this will no longer exclude "
+                "empty items when determining the result dtype. "
+                "To retain the old behavior, exclude the empty entries before "
+                "the concat operation.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    if target_dtype is not None:
+        to_concat = [astype_array(arr, target_dtype, copy=False) for arr in to_concat]
+
+    if not isinstance(to_concat[0], np.ndarray):
+        # i.e. isinstance(to_concat[0], ExtensionArray)
+        to_concat_eas = cast("Sequence[ExtensionArray]", to_concat)
+        cls = type(to_concat[0])
+        # GH#53640: eg. for datetime array, axis=1 but 0 is default
+        # However, class method `_concat_same_type()` for some classes
+        # may not support the `axis` keyword
+        if ea_compat_axis or axis == 0:
+            return cls._concat_same_type(to_concat_eas)
+        else:
+            return cls._concat_same_type(
+                to_concat_eas,
+                axis=axis,  # type: ignore[call-arg]
+            )
+    else:
+        to_concat_arrs = cast("Sequence[np.ndarray]", to_concat)
+        result = np.concatenate(to_concat_arrs, axis=axis)
+
+        if not any_ea and "b" in kinds and result.dtype.kind in "iuf":
+            # GH#39817 cast to object instead of casting bools to numeric
+            result = result.astype(object, copy=False)
+    return result
+
+
+def _get_result_dtype(
+    to_concat: Sequence[ArrayLike], non_empties: Sequence[ArrayLike]
+) -> tuple[bool, set[str], DtypeObj | None]:
+    target_dtype = None
+
+    dtypes = {obj.dtype for obj in to_concat}
+    kinds = {obj.dtype.kind for obj in to_concat}
+
+    any_ea = any(not isinstance(x, np.ndarray) for x in to_concat)
+    if any_ea:
+        # i.e. any ExtensionArrays
+
+        # we ignore axis here, as internally concatting with EAs is always
+        # for axis=0
+        if len(dtypes) != 1:
+            target_dtype = find_common_type([x.dtype for x in to_concat])
+            target_dtype = common_dtype_categorical_compat(to_concat, target_dtype)
+
+    elif not len(non_empties):
+        # we have all empties, but may need to coerce the result dtype to
+        # object if we have non-numeric type operands (numpy would otherwise
+        # cast this to float)
+        if len(kinds) != 1:
+            if not len(kinds - {"i", "u", "f"}) or not len(kinds - {"b", "i", "u"}):
+                # let numpy coerce
+                pass
+            else:
+                # coerce to object
+                target_dtype = np.dtype(object)
+                kinds = {"o"}
+    else:
+        # error: Argument 1 to "np_find_common_type" has incompatible type
+        # "*Set[Union[ExtensionDtype, Any]]"; expected "dtype[Any]"
+        target_dtype = np_find_common_type(*dtypes)  # type: ignore[arg-type]
+
+    return any_ea, kinds, target_dtype
+
+
+def union_categoricals(
+    to_union, sort_categories: bool = False, ignore_order: bool = False
+) -> Categorical:
+    """
+    Combine list-like of Categorical-like, unioning categories.
+
+    All categories must have the same dtype.
+
+    Parameters
+    ----------
+    to_union : list-like
+        Categorical, CategoricalIndex, or Series with dtype='category'.
+    sort_categories : bool, default False
+        If true, resulting categories will be lexsorted, otherwise
+        they will be ordered as they appear in the data.
+    ignore_order : bool, default False
+        If true, the ordered attribute of the Categoricals will be ignored.
+        Results in an unordered categorical.
+
+    Returns
+    -------
+    Categorical
+
+    Raises
+    ------
+    TypeError
+        - all inputs do not have the same dtype
+        - all inputs do not have the same ordered property
+        - all inputs are ordered and their categories are not identical
+        - sort_categories=True and Categoricals are ordered
+    ValueError
+        Empty list of categoricals passed
+
+    Notes
+    -----
+    To learn more about categories, see `link
+    `__
+
+    Examples
+    --------
+    If you want to combine categoricals that do not necessarily have
+    the same categories, `union_categoricals` will combine a list-like
+    of categoricals. The new categories will be the union of the
+    categories being combined.
+
+    >>> a = pd.Categorical(["b", "c"])
+    >>> b = pd.Categorical(["a", "b"])
+    >>> pd.api.types.union_categoricals([a, b])
+    ['b', 'c', 'a', 'b']
+    Categories (3, object): ['b', 'c', 'a']
+
+    By default, the resulting categories will be ordered as they appear
+    in the `categories` of the data. If you want the categories to be
+    lexsorted, use `sort_categories=True` argument.
+
+    >>> pd.api.types.union_categoricals([a, b], sort_categories=True)
+    ['b', 'c', 'a', 'b']
+    Categories (3, object): ['a', 'b', 'c']
+
+    `union_categoricals` also works with the case of combining two
+    categoricals of the same categories and order information (e.g. what
+    you could also `append` for).
+
+    >>> a = pd.Categorical(["a", "b"], ordered=True)
+    >>> b = pd.Categorical(["a", "b", "a"], ordered=True)
+    >>> pd.api.types.union_categoricals([a, b])
+    ['a', 'b', 'a', 'b', 'a']
+    Categories (2, object): ['a' < 'b']
+
+    Raises `TypeError` because the categories are ordered and not identical.
+
+    >>> a = pd.Categorical(["a", "b"], ordered=True)
+    >>> b = pd.Categorical(["a", "b", "c"], ordered=True)
+    >>> pd.api.types.union_categoricals([a, b])
+    Traceback (most recent call last):
+        ...
+    TypeError: to union ordered Categoricals, all categories must be the same
+
+    Ordered categoricals with different categories or orderings can be
+    combined by using the `ignore_ordered=True` argument.
+
+    >>> a = pd.Categorical(["a", "b", "c"], ordered=True)
+    >>> b = pd.Categorical(["c", "b", "a"], ordered=True)
+    >>> pd.api.types.union_categoricals([a, b], ignore_order=True)
+    ['a', 'b', 'c', 'c', 'b', 'a']
+    Categories (3, object): ['a', 'b', 'c']
+
+    `union_categoricals` also works with a `CategoricalIndex`, or `Series`
+    containing categorical data, but note that the resulting array will
+    always be a plain `Categorical`
+
+    >>> a = pd.Series(["b", "c"], dtype='category')
+    >>> b = pd.Series(["a", "b"], dtype='category')
+    >>> pd.api.types.union_categoricals([a, b])
+    ['b', 'c', 'a', 'b']
+    Categories (3, object): ['b', 'c', 'a']
+    """
+    from pandas import Categorical
+    from pandas.core.arrays.categorical import recode_for_categories
+
+    if len(to_union) == 0:
+        raise ValueError("No Categoricals to union")
+
+    def _maybe_unwrap(x):
+        if isinstance(x, (ABCCategoricalIndex, ABCSeries)):
+            return x._values
+        elif isinstance(x, Categorical):
+            return x
+        else:
+            raise TypeError("all components to combine must be Categorical")
+
+    to_union = [_maybe_unwrap(x) for x in to_union]
+    first = to_union[0]
+
+    if not lib.dtypes_all_equal([obj.categories.dtype for obj in to_union]):
+        raise TypeError("dtype of categories must be the same")
+
+    ordered = False
+    if all(first._categories_match_up_to_permutation(other) for other in to_union[1:]):
+        # identical categories - fastpath
+        categories = first.categories
+        ordered = first.ordered
+
+        all_codes = [first._encode_with_my_categories(x)._codes for x in to_union]
+        new_codes = np.concatenate(all_codes)
+
+        if sort_categories and not ignore_order and ordered:
+            raise TypeError("Cannot use sort_categories=True with ordered Categoricals")
+
+        if sort_categories and not categories.is_monotonic_increasing:
+            categories = categories.sort_values()
+            indexer = categories.get_indexer(first.categories)
+
+            from pandas.core.algorithms import take_nd
+
+            new_codes = take_nd(indexer, new_codes, fill_value=-1)
+    elif ignore_order or all(not c.ordered for c in to_union):
+        # different categories - union and recode
+        cats = first.categories.append([c.categories for c in to_union[1:]])
+        categories = cats.unique()
+        if sort_categories:
+            categories = categories.sort_values()
+
+        new_codes = [
+            recode_for_categories(c.codes, c.categories, categories) for c in to_union
+        ]
+        new_codes = np.concatenate(new_codes)
+    else:
+        # ordered - to show a proper error message
+        if all(c.ordered for c in to_union):
+            msg = "to union ordered Categoricals, all categories must be the same"
+            raise TypeError(msg)
+        raise TypeError("Categorical.ordered must be the same")
+
+    if ignore_order:
+        ordered = False
+
+    dtype = CategoricalDtype(categories=categories, ordered=ordered)
+    return Categorical._simple_new(new_codes, dtype=dtype)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/dtypes.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/dtypes.py
new file mode 100644
index 0000000000000000000000000000000000000000..542bc85110cadfc777f82a6859899c129ef1d47f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/dtypes.py
@@ -0,0 +1,2348 @@
+"""
+Define extension dtypes.
+"""
+from __future__ import annotations
+
+from datetime import (
+    date,
+    datetime,
+    time,
+    timedelta,
+)
+from decimal import Decimal
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+import warnings
+
+import numpy as np
+import pytz
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas._libs.interval import Interval
+from pandas._libs.properties import cache_readonly
+from pandas._libs.tslibs import (
+    BaseOffset,
+    NaT,
+    NaTType,
+    Period,
+    Timedelta,
+    Timestamp,
+    timezones,
+    to_offset,
+    tz_compare,
+)
+from pandas._libs.tslibs.dtypes import (
+    PeriodDtypeBase,
+    abbrev_to_npy_unit,
+)
+from pandas._libs.tslibs.offsets import BDay
+from pandas.compat import pa_version_under10p1
+from pandas.errors import PerformanceWarning
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import (
+    ExtensionDtype,
+    StorageExtensionDtype,
+    register_extension_dtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCCategoricalIndex,
+    ABCIndex,
+    ABCRangeIndex,
+)
+from pandas.core.dtypes.inference import (
+    is_bool,
+    is_list_like,
+)
+
+from pandas.util import capitalize_first_letter
+
+if not pa_version_under10p1:
+    import pyarrow as pa
+
+if TYPE_CHECKING:
+    from collections.abc import MutableMapping
+    from datetime import tzinfo
+
+    import pyarrow as pa  # noqa: TCH004
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        IntervalClosedType,
+        Ordered,
+        Self,
+        npt,
+        type_t,
+    )
+
+    from pandas import (
+        Categorical,
+        CategoricalIndex,
+        DatetimeIndex,
+        Index,
+        IntervalIndex,
+        PeriodIndex,
+    )
+    from pandas.core.arrays import (
+        BaseMaskedArray,
+        DatetimeArray,
+        IntervalArray,
+        NumpyExtensionArray,
+        PeriodArray,
+        SparseArray,
+    )
+    from pandas.core.arrays.arrow import ArrowExtensionArray
+
+str_type = str
+
+
+class PandasExtensionDtype(ExtensionDtype):
+    """
+    A np.dtype duck-typed class, suitable for holding a custom dtype.
+
+    THIS IS NOT A REAL NUMPY DTYPE
+    """
+
+    type: Any
+    kind: Any
+    # The Any type annotations above are here only because mypy seems to have a
+    # problem dealing with multiple inheritance from PandasExtensionDtype
+    # and ExtensionDtype's @properties in the subclasses below. The kind and
+    # type variables in those subclasses are explicitly typed below.
+    subdtype = None
+    str: str_type
+    num = 100
+    shape: tuple[int, ...] = ()
+    itemsize = 8
+    base: DtypeObj | None = None
+    isbuiltin = 0
+    isnative = 0
+    _cache_dtypes: dict[str_type, PandasExtensionDtype] = {}
+
+    def __repr__(self) -> str_type:
+        """
+        Return a string representation for a particular object.
+        """
+        return str(self)
+
+    def __hash__(self) -> int:
+        raise NotImplementedError("sub-classes should implement an __hash__ method")
+
+    def __getstate__(self) -> dict[str_type, Any]:
+        # pickle support; we don't want to pickle the cache
+        return {k: getattr(self, k, None) for k in self._metadata}
+
+    @classmethod
+    def reset_cache(cls) -> None:
+        """clear the cache"""
+        cls._cache_dtypes = {}
+
+
+class CategoricalDtypeType(type):
+    """
+    the type of CategoricalDtype, this metaclass determines subclass ability
+    """
+
+
+@register_extension_dtype
+class CategoricalDtype(PandasExtensionDtype, ExtensionDtype):
+    """
+    Type for categorical data with the categories and orderedness.
+
+    Parameters
+    ----------
+    categories : sequence, optional
+        Must be unique, and must not contain any nulls.
+        The categories are stored in an Index,
+        and if an index is provided the dtype of that index will be used.
+    ordered : bool or None, default False
+        Whether or not this categorical is treated as a ordered categorical.
+        None can be used to maintain the ordered value of existing categoricals when
+        used in operations that combine categoricals, e.g. astype, and will resolve to
+        False if there is no existing ordered to maintain.
+
+    Attributes
+    ----------
+    categories
+    ordered
+
+    Methods
+    -------
+    None
+
+    See Also
+    --------
+    Categorical : Represent a categorical variable in classic R / S-plus fashion.
+
+    Notes
+    -----
+    This class is useful for specifying the type of a ``Categorical``
+    independent of the values. See :ref:`categorical.categoricaldtype`
+    for more.
+
+    Examples
+    --------
+    >>> t = pd.CategoricalDtype(categories=['b', 'a'], ordered=True)
+    >>> pd.Series(['a', 'b', 'a', 'c'], dtype=t)
+    0      a
+    1      b
+    2      a
+    3    NaN
+    dtype: category
+    Categories (2, object): ['b' < 'a']
+
+    An empty CategoricalDtype with a specific dtype can be created
+    by providing an empty index. As follows,
+
+    >>> pd.CategoricalDtype(pd.DatetimeIndex([])).categories.dtype
+    dtype(' None:
+        self._finalize(categories, ordered, fastpath=False)
+
+    @classmethod
+    def _from_fastpath(
+        cls, categories=None, ordered: bool | None = None
+    ) -> CategoricalDtype:
+        self = cls.__new__(cls)
+        self._finalize(categories, ordered, fastpath=True)
+        return self
+
+    @classmethod
+    def _from_categorical_dtype(
+        cls, dtype: CategoricalDtype, categories=None, ordered: Ordered | None = None
+    ) -> CategoricalDtype:
+        if categories is ordered is None:
+            return dtype
+        if categories is None:
+            categories = dtype.categories
+        if ordered is None:
+            ordered = dtype.ordered
+        return cls(categories, ordered)
+
+    @classmethod
+    def _from_values_or_dtype(
+        cls,
+        values=None,
+        categories=None,
+        ordered: bool | None = None,
+        dtype: Dtype | None = None,
+    ) -> CategoricalDtype:
+        """
+        Construct dtype from the input parameters used in :class:`Categorical`.
+
+        This constructor method specifically does not do the factorization
+        step, if that is needed to find the categories. This constructor may
+        therefore return ``CategoricalDtype(categories=None, ordered=None)``,
+        which may not be useful. Additional steps may therefore have to be
+        taken to create the final dtype.
+
+        The return dtype is specified from the inputs in this prioritized
+        order:
+        1. if dtype is a CategoricalDtype, return dtype
+        2. if dtype is the string 'category', create a CategoricalDtype from
+           the supplied categories and ordered parameters, and return that.
+        3. if values is a categorical, use value.dtype, but override it with
+           categories and ordered if either/both of those are not None.
+        4. if dtype is None and values is not a categorical, construct the
+           dtype from categories and ordered, even if either of those is None.
+
+        Parameters
+        ----------
+        values : list-like, optional
+            The list-like must be 1-dimensional.
+        categories : list-like, optional
+            Categories for the CategoricalDtype.
+        ordered : bool, optional
+            Designating if the categories are ordered.
+        dtype : CategoricalDtype or the string "category", optional
+            If ``CategoricalDtype``, cannot be used together with
+            `categories` or `ordered`.
+
+        Returns
+        -------
+        CategoricalDtype
+
+        Examples
+        --------
+        >>> pd.CategoricalDtype._from_values_or_dtype()
+        CategoricalDtype(categories=None, ordered=None, categories_dtype=None)
+        >>> pd.CategoricalDtype._from_values_or_dtype(
+        ...     categories=['a', 'b'], ordered=True
+        ... )
+        CategoricalDtype(categories=['a', 'b'], ordered=True, categories_dtype=object)
+        >>> dtype1 = pd.CategoricalDtype(['a', 'b'], ordered=True)
+        >>> dtype2 = pd.CategoricalDtype(['x', 'y'], ordered=False)
+        >>> c = pd.Categorical([0, 1], dtype=dtype1)
+        >>> pd.CategoricalDtype._from_values_or_dtype(
+        ...     c, ['x', 'y'], ordered=True, dtype=dtype2
+        ... )
+        Traceback (most recent call last):
+            ...
+        ValueError: Cannot specify `categories` or `ordered` together with
+        `dtype`.
+
+        The supplied dtype takes precedence over values' dtype:
+
+        >>> pd.CategoricalDtype._from_values_or_dtype(c, dtype=dtype2)
+        CategoricalDtype(categories=['x', 'y'], ordered=False, categories_dtype=object)
+        """
+
+        if dtype is not None:
+            # The dtype argument takes precedence over values.dtype (if any)
+            if isinstance(dtype, str):
+                if dtype == "category":
+                    if ordered is None and cls.is_dtype(values):
+                        # GH#49309 preserve orderedness
+                        ordered = values.dtype.ordered
+
+                    dtype = CategoricalDtype(categories, ordered)
+                else:
+                    raise ValueError(f"Unknown dtype {repr(dtype)}")
+            elif categories is not None or ordered is not None:
+                raise ValueError(
+                    "Cannot specify `categories` or `ordered` together with `dtype`."
+                )
+            elif not isinstance(dtype, CategoricalDtype):
+                raise ValueError(f"Cannot not construct CategoricalDtype from {dtype}")
+        elif cls.is_dtype(values):
+            # If no "dtype" was passed, use the one from "values", but honor
+            # the "ordered" and "categories" arguments
+            dtype = values.dtype._from_categorical_dtype(
+                values.dtype, categories, ordered
+            )
+        else:
+            # If dtype=None and values is not categorical, create a new dtype.
+            # Note: This could potentially have categories=None and
+            # ordered=None.
+            dtype = CategoricalDtype(categories, ordered)
+
+        return cast(CategoricalDtype, dtype)
+
+    @classmethod
+    def construct_from_string(cls, string: str_type) -> CategoricalDtype:
+        """
+        Construct a CategoricalDtype from a string.
+
+        Parameters
+        ----------
+        string : str
+            Must be the string "category" in order to be successfully constructed.
+
+        Returns
+        -------
+        CategoricalDtype
+            Instance of the dtype.
+
+        Raises
+        ------
+        TypeError
+            If a CategoricalDtype cannot be constructed from the input.
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+        if string != cls.name:
+            raise TypeError(f"Cannot construct a 'CategoricalDtype' from '{string}'")
+
+        # need ordered=None to ensure that operations specifying dtype="category" don't
+        # override the ordered value for existing categoricals
+        return cls(ordered=None)
+
+    def _finalize(self, categories, ordered: Ordered, fastpath: bool = False) -> None:
+        if ordered is not None:
+            self.validate_ordered(ordered)
+
+        if categories is not None:
+            categories = self.validate_categories(categories, fastpath=fastpath)
+
+        self._categories = categories
+        self._ordered = ordered
+
+    def __setstate__(self, state: MutableMapping[str_type, Any]) -> None:
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
+        self._categories = state.pop("categories", None)
+        self._ordered = state.pop("ordered", False)
+
+    def __hash__(self) -> int:
+        # _hash_categories returns a uint64, so use the negative
+        # space for when we have unknown categories to avoid a conflict
+        if self.categories is None:
+            if self.ordered:
+                return -1
+            else:
+                return -2
+        # We *do* want to include the real self.ordered here
+        return int(self._hash_categories)
+
+    def __eq__(self, other: object) -> bool:
+        """
+        Rules for CDT equality:
+        1) Any CDT is equal to the string 'category'
+        2) Any CDT is equal to itself
+        3) Any CDT is equal to a CDT with categories=None regardless of ordered
+        4) A CDT with ordered=True is only equal to another CDT with
+           ordered=True and identical categories in the same order
+        5) A CDT with ordered={False, None} is only equal to another CDT with
+           ordered={False, None} and identical categories, but same order is
+           not required. There is no distinction between False/None.
+        6) Any other comparison returns False
+        """
+        if isinstance(other, str):
+            return other == self.name
+        elif other is self:
+            return True
+        elif not (hasattr(other, "ordered") and hasattr(other, "categories")):
+            return False
+        elif self.categories is None or other.categories is None:
+            # For non-fully-initialized dtypes, these are only equal to
+            #  - the string "category" (handled above)
+            #  - other CategoricalDtype with categories=None
+            return self.categories is other.categories
+        elif self.ordered or other.ordered:
+            # At least one has ordered=True; equal if both have ordered=True
+            # and the same values for categories in the same order.
+            return (self.ordered == other.ordered) and self.categories.equals(
+                other.categories
+            )
+        else:
+            # Neither has ordered=True; equal if both have the same categories,
+            # but same order is not necessary.  There is no distinction between
+            # ordered=False and ordered=None: CDT(., False) and CDT(., None)
+            # will be equal if they have the same categories.
+            left = self.categories
+            right = other.categories
+
+            # GH#36280 the ordering of checks here is for performance
+            if not left.dtype == right.dtype:
+                return False
+
+            if len(left) != len(right):
+                return False
+
+            if self.categories.equals(other.categories):
+                # Check and see if they happen to be identical categories
+                return True
+
+            if left.dtype != object:
+                # Faster than calculating hash
+                indexer = left.get_indexer(right)
+                # Because left and right have the same length and are unique,
+                #  `indexer` not having any -1s implies that there is a
+                #  bijection between `left` and `right`.
+                return bool((indexer != -1).all())
+
+            # With object-dtype we need a comparison that identifies
+            #  e.g. int(2) as distinct from float(2)
+            return set(left) == set(right)
+
+    def __repr__(self) -> str_type:
+        if self.categories is None:
+            data = "None"
+            dtype = "None"
+        else:
+            data = self.categories._format_data(name=type(self).__name__)
+            if isinstance(self.categories, ABCRangeIndex):
+                data = str(self.categories._range)
+            data = data.rstrip(", ")
+            dtype = self.categories.dtype
+
+        return (
+            f"CategoricalDtype(categories={data}, ordered={self.ordered}, "
+            f"categories_dtype={dtype})"
+        )
+
+    @cache_readonly
+    def _hash_categories(self) -> int:
+        from pandas.core.util.hashing import (
+            combine_hash_arrays,
+            hash_array,
+            hash_tuples,
+        )
+
+        categories = self.categories
+        ordered = self.ordered
+
+        if len(categories) and isinstance(categories[0], tuple):
+            # assumes if any individual category is a tuple, then all our. ATM
+            # I don't really want to support just some of the categories being
+            # tuples.
+            cat_list = list(categories)  # breaks if a np.array of categories
+            cat_array = hash_tuples(cat_list)
+        else:
+            if categories.dtype == "O" and len({type(x) for x in categories}) != 1:
+                # TODO: hash_array doesn't handle mixed types. It casts
+                # everything to a str first, which means we treat
+                # {'1', '2'} the same as {'1', 2}
+                # find a better solution
+                hashed = hash((tuple(categories), ordered))
+                return hashed
+
+            if DatetimeTZDtype.is_dtype(categories.dtype):
+                # Avoid future warning.
+                categories = categories.view("datetime64[ns]")
+
+            cat_array = hash_array(np.asarray(categories), categorize=False)
+        if ordered:
+            cat_array = np.vstack(
+                [cat_array, np.arange(len(cat_array), dtype=cat_array.dtype)]
+            )
+        else:
+            cat_array = np.array([cat_array])
+        combined_hashed = combine_hash_arrays(iter(cat_array), num_items=len(cat_array))
+        return np.bitwise_xor.reduce(combined_hashed)
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[Categorical]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas import Categorical
+
+        return Categorical
+
+    @staticmethod
+    def validate_ordered(ordered: Ordered) -> None:
+        """
+        Validates that we have a valid ordered parameter. If
+        it is not a boolean, a TypeError will be raised.
+
+        Parameters
+        ----------
+        ordered : object
+            The parameter to be verified.
+
+        Raises
+        ------
+        TypeError
+            If 'ordered' is not a boolean.
+        """
+        if not is_bool(ordered):
+            raise TypeError("'ordered' must either be 'True' or 'False'")
+
+    @staticmethod
+    def validate_categories(categories, fastpath: bool = False) -> Index:
+        """
+        Validates that we have good categories
+
+        Parameters
+        ----------
+        categories : array-like
+        fastpath : bool
+            Whether to skip nan and uniqueness checks
+
+        Returns
+        -------
+        categories : Index
+        """
+        from pandas.core.indexes.base import Index
+
+        if not fastpath and not is_list_like(categories):
+            raise TypeError(
+                f"Parameter 'categories' must be list-like, was {repr(categories)}"
+            )
+        if not isinstance(categories, ABCIndex):
+            categories = Index._with_infer(categories, tupleize_cols=False)
+
+        if not fastpath:
+            if categories.hasnans:
+                raise ValueError("Categorical categories cannot be null")
+
+            if not categories.is_unique:
+                raise ValueError("Categorical categories must be unique")
+
+        if isinstance(categories, ABCCategoricalIndex):
+            categories = categories.categories
+
+        return categories
+
+    def update_dtype(self, dtype: str_type | CategoricalDtype) -> CategoricalDtype:
+        """
+        Returns a CategoricalDtype with categories and ordered taken from dtype
+        if specified, otherwise falling back to self if unspecified
+
+        Parameters
+        ----------
+        dtype : CategoricalDtype
+
+        Returns
+        -------
+        new_dtype : CategoricalDtype
+        """
+        if isinstance(dtype, str) and dtype == "category":
+            # dtype='category' should not change anything
+            return self
+        elif not self.is_dtype(dtype):
+            raise ValueError(
+                f"a CategoricalDtype must be passed to perform an update, "
+                f"got {repr(dtype)}"
+            )
+        else:
+            # from here on, dtype is a CategoricalDtype
+            dtype = cast(CategoricalDtype, dtype)
+
+        # update categories/ordered unless they've been explicitly passed as None
+        new_categories = (
+            dtype.categories if dtype.categories is not None else self.categories
+        )
+        new_ordered = dtype.ordered if dtype.ordered is not None else self.ordered
+
+        return CategoricalDtype(new_categories, new_ordered)
+
+    @property
+    def categories(self) -> Index:
+        """
+        An ``Index`` containing the unique categories allowed.
+
+        Examples
+        --------
+        >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=True)
+        >>> cat_type.categories
+        Index(['a', 'b'], dtype='object')
+        """
+        return self._categories
+
+    @property
+    def ordered(self) -> Ordered:
+        """
+        Whether the categories have an ordered relationship.
+
+        Examples
+        --------
+        >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=True)
+        >>> cat_type.ordered
+        True
+
+        >>> cat_type = pd.CategoricalDtype(categories=['a', 'b'], ordered=False)
+        >>> cat_type.ordered
+        False
+        """
+        return self._ordered
+
+    @property
+    def _is_boolean(self) -> bool:
+        from pandas.core.dtypes.common import is_bool_dtype
+
+        return is_bool_dtype(self.categories)
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        # check if we have all categorical dtype with identical categories
+        if all(isinstance(x, CategoricalDtype) for x in dtypes):
+            first = dtypes[0]
+            if all(first == other for other in dtypes[1:]):
+                return first
+
+        # special case non-initialized categorical
+        # TODO we should figure out the expected return value in general
+        non_init_cats = [
+            isinstance(x, CategoricalDtype) and x.categories is None for x in dtypes
+        ]
+        if all(non_init_cats):
+            return self
+        elif any(non_init_cats):
+            return None
+
+        # categorical is aware of Sparse -> extract sparse subdtypes
+        dtypes = [x.subtype if isinstance(x, SparseDtype) else x for x in dtypes]
+        # extract the categories' dtype
+        non_cat_dtypes = [
+            x.categories.dtype if isinstance(x, CategoricalDtype) else x for x in dtypes
+        ]
+        # TODO should categorical always give an answer?
+        from pandas.core.dtypes.cast import find_common_type
+
+        return find_common_type(non_cat_dtypes)
+
+    @cache_readonly
+    def index_class(self) -> type_t[CategoricalIndex]:
+        from pandas import CategoricalIndex
+
+        return CategoricalIndex
+
+
+@register_extension_dtype
+class DatetimeTZDtype(PandasExtensionDtype):
+    """
+    An ExtensionDtype for timezone-aware datetime data.
+
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    unit : str, default "ns"
+        The precision of the datetime data. Currently limited
+        to ``"ns"``.
+    tz : str, int, or datetime.tzinfo
+        The timezone.
+
+    Attributes
+    ----------
+    unit
+    tz
+
+    Methods
+    -------
+    None
+
+    Raises
+    ------
+    ZoneInfoNotFoundError
+        When the requested timezone cannot be found.
+
+    Examples
+    --------
+    >>> from zoneinfo import ZoneInfo
+    >>> pd.DatetimeTZDtype(tz=ZoneInfo('UTC'))
+    datetime64[ns, UTC]
+
+    >>> pd.DatetimeTZDtype(tz=ZoneInfo('Europe/Paris'))
+    datetime64[ns, Europe/Paris]
+    """
+
+    type: type[Timestamp] = Timestamp
+    kind: str_type = "M"
+    num = 101
+    _metadata = ("unit", "tz")
+    _match = re.compile(r"(datetime64|M8)\[(?P.+), (?P.+)\]")
+    _cache_dtypes: dict[str_type, PandasExtensionDtype] = {}
+    _supports_2d = True
+    _can_fast_transpose = True
+
+    @property
+    def na_value(self) -> NaTType:
+        return NaT
+
+    @cache_readonly
+    def base(self) -> DtypeObj:  # type: ignore[override]
+        return np.dtype(f"M8[{self.unit}]")
+
+    # error: Signature of "str" incompatible with supertype "PandasExtensionDtype"
+    @cache_readonly
+    def str(self) -> str:  # type: ignore[override]
+        return f"|M8[{self.unit}]"
+
+    def __init__(self, unit: str_type | DatetimeTZDtype = "ns", tz=None) -> None:
+        if isinstance(unit, DatetimeTZDtype):
+            # error: "str" has no attribute "tz"
+            unit, tz = unit.unit, unit.tz  # type: ignore[attr-defined]
+
+        if unit != "ns":
+            if isinstance(unit, str) and tz is None:
+                # maybe a string like datetime64[ns, tz], which we support for
+                # now.
+                result = type(self).construct_from_string(unit)
+                unit = result.unit
+                tz = result.tz
+                msg = (
+                    f"Passing a dtype alias like 'datetime64[ns, {tz}]' "
+                    "to DatetimeTZDtype is no longer supported. Use "
+                    "'DatetimeTZDtype.construct_from_string()' instead."
+                )
+                raise ValueError(msg)
+            if unit not in ["s", "ms", "us", "ns"]:
+                raise ValueError("DatetimeTZDtype only supports s, ms, us, ns units")
+
+        if tz:
+            tz = timezones.maybe_get_tz(tz)
+            tz = timezones.tz_standardize(tz)
+        elif tz is not None:
+            raise pytz.UnknownTimeZoneError(tz)
+        if tz is None:
+            raise TypeError("A 'tz' is required.")
+
+        self._unit = unit
+        self._tz = tz
+
+    @cache_readonly
+    def _creso(self) -> int:
+        """
+        The NPY_DATETIMEUNIT corresponding to this dtype's resolution.
+        """
+        return abbrev_to_npy_unit(self.unit)
+
+    @property
+    def unit(self) -> str_type:
+        """
+        The precision of the datetime data.
+
+        Examples
+        --------
+        >>> from zoneinfo import ZoneInfo
+        >>> dtype = pd.DatetimeTZDtype(tz=ZoneInfo('America/Los_Angeles'))
+        >>> dtype.unit
+        'ns'
+        """
+        return self._unit
+
+    @property
+    def tz(self) -> tzinfo:
+        """
+        The timezone.
+
+        Examples
+        --------
+        >>> from zoneinfo import ZoneInfo
+        >>> dtype = pd.DatetimeTZDtype(tz=ZoneInfo('America/Los_Angeles'))
+        >>> dtype.tz
+        zoneinfo.ZoneInfo(key='America/Los_Angeles')
+        """
+        return self._tz
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[DatetimeArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays import DatetimeArray
+
+        return DatetimeArray
+
+    @classmethod
+    def construct_from_string(cls, string: str_type) -> DatetimeTZDtype:
+        """
+        Construct a DatetimeTZDtype from a string.
+
+        Parameters
+        ----------
+        string : str
+            The string alias for this DatetimeTZDtype.
+            Should be formatted like ``datetime64[ns, ]``,
+            where ```` is the timezone name.
+
+        Examples
+        --------
+        >>> DatetimeTZDtype.construct_from_string('datetime64[ns, UTC]')
+        datetime64[ns, UTC]
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+
+        msg = f"Cannot construct a 'DatetimeTZDtype' from '{string}'"
+        match = cls._match.match(string)
+        if match:
+            d = match.groupdict()
+            try:
+                return cls(unit=d["unit"], tz=d["tz"])
+            except (KeyError, TypeError, ValueError) as err:
+                # KeyError if maybe_get_tz tries and fails to get a
+                #  pytz timezone (actually pytz.UnknownTimeZoneError).
+                # TypeError if we pass a nonsense tz;
+                # ValueError if we pass a unit other than "ns"
+                raise TypeError(msg) from err
+        raise TypeError(msg)
+
+    def __str__(self) -> str_type:
+        return f"datetime64[{self.unit}, {self.tz}]"
+
+    @property
+    def name(self) -> str_type:
+        """A string representation of the dtype."""
+        return str(self)
+
+    def __hash__(self) -> int:
+        # make myself hashable
+        # TODO: update this.
+        return hash(str(self))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str):
+            if other.startswith("M8["):
+                other = f"datetime64[{other[3:]}"
+            return other == self.name
+
+        return (
+            isinstance(other, DatetimeTZDtype)
+            and self.unit == other.unit
+            and tz_compare(self.tz, other.tz)
+        )
+
+    def __from_arrow__(self, array: pa.Array | pa.ChunkedArray) -> DatetimeArray:
+        """
+        Construct DatetimeArray from pyarrow Array/ChunkedArray.
+
+        Note: If the units in the pyarrow Array are the same as this
+        DatetimeDtype, then values corresponding to the integer representation
+        of ``NaT`` (e.g. one nanosecond before :attr:`pandas.Timestamp.min`)
+        are converted to ``NaT``, regardless of the null indicator in the
+        pyarrow array.
+
+        Parameters
+        ----------
+        array : pyarrow.Array or pyarrow.ChunkedArray
+            The Arrow array to convert to DatetimeArray.
+
+        Returns
+        -------
+        extension array : DatetimeArray
+        """
+        import pyarrow
+
+        from pandas.core.arrays import DatetimeArray
+
+        array = array.cast(pyarrow.timestamp(unit=self._unit), safe=True)
+
+        if isinstance(array, pyarrow.Array):
+            np_arr = array.to_numpy(zero_copy_only=False)
+        else:
+            np_arr = array.to_numpy()
+
+        return DatetimeArray._simple_new(np_arr, dtype=self)
+
+    def __setstate__(self, state) -> None:
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
+        self._tz = state["tz"]
+        self._unit = state["unit"]
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        if all(isinstance(t, DatetimeTZDtype) and t.tz == self.tz for t in dtypes):
+            np_dtype = np.max([cast(DatetimeTZDtype, t).base for t in [self, *dtypes]])
+            unit = np.datetime_data(np_dtype)[0]
+            return type(self)(unit=unit, tz=self.tz)
+        return super()._get_common_dtype(dtypes)
+
+    @cache_readonly
+    def index_class(self) -> type_t[DatetimeIndex]:
+        from pandas import DatetimeIndex
+
+        return DatetimeIndex
+
+
+@register_extension_dtype
+class PeriodDtype(PeriodDtypeBase, PandasExtensionDtype):
+    """
+    An ExtensionDtype for Period data.
+
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    freq : str or DateOffset
+        The frequency of this PeriodDtype.
+
+    Attributes
+    ----------
+    freq
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.PeriodDtype(freq='D')
+    period[D]
+
+    >>> pd.PeriodDtype(freq=pd.offsets.MonthEnd())
+    period[M]
+    """
+
+    type: type[Period] = Period
+    kind: str_type = "O"
+    str = "|O08"
+    base = np.dtype("O")
+    num = 102
+    _metadata = ("freq",)
+    _match = re.compile(r"(P|p)eriod\[(?P.+)\]")
+    # error: Incompatible types in assignment (expression has type
+    # "Dict[int, PandasExtensionDtype]", base class "PandasExtensionDtype"
+    # defined the type as "Dict[str, PandasExtensionDtype]")  [assignment]
+    _cache_dtypes: dict[BaseOffset, int] = {}  # type: ignore[assignment]
+    __hash__ = PeriodDtypeBase.__hash__
+    _freq: BaseOffset
+    _supports_2d = True
+    _can_fast_transpose = True
+
+    def __new__(cls, freq) -> PeriodDtype:  # noqa: PYI034
+        """
+        Parameters
+        ----------
+        freq : PeriodDtype, BaseOffset, or string
+        """
+        if isinstance(freq, PeriodDtype):
+            return freq
+
+        if not isinstance(freq, BaseOffset):
+            freq = cls._parse_dtype_strict(freq)
+
+        if isinstance(freq, BDay):
+            # GH#53446
+            # TODO(3.0): enforcing this will close GH#10575
+            warnings.warn(
+                "PeriodDtype[B] is deprecated and will be removed in a future "
+                "version. Use a DatetimeIndex with freq='B' instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        try:
+            dtype_code = cls._cache_dtypes[freq]
+        except KeyError:
+            dtype_code = freq._period_dtype_code
+            cls._cache_dtypes[freq] = dtype_code
+        u = PeriodDtypeBase.__new__(cls, dtype_code, freq.n)
+        u._freq = freq
+        return u
+
+    def __reduce__(self) -> tuple[type_t[Self], tuple[str_type]]:
+        return type(self), (self.name,)
+
+    @property
+    def freq(self) -> BaseOffset:
+        """
+        The frequency object of this PeriodDtype.
+
+        Examples
+        --------
+        >>> dtype = pd.PeriodDtype(freq='D')
+        >>> dtype.freq
+        
+        """
+        return self._freq
+
+    @classmethod
+    def _parse_dtype_strict(cls, freq: str_type) -> BaseOffset:
+        if isinstance(freq, str):  # note: freq is already of type str!
+            if freq.startswith(("Period[", "period[")):
+                m = cls._match.search(freq)
+                if m is not None:
+                    freq = m.group("freq")
+
+            freq_offset = to_offset(freq, is_period=True)
+            if freq_offset is not None:
+                return freq_offset
+
+        raise TypeError(
+            "PeriodDtype argument should be string or BaseOffset, "
+            f"got {type(freq).__name__}"
+        )
+
+    @classmethod
+    def construct_from_string(cls, string: str_type) -> PeriodDtype:
+        """
+        Strict construction from a string, raise a TypeError if not
+        possible
+        """
+        if (
+            isinstance(string, str)
+            and (string.startswith(("period[", "Period[")))
+            or isinstance(string, BaseOffset)
+        ):
+            # do not parse string like U as period[U]
+            # avoid tuple to be regarded as freq
+            try:
+                return cls(freq=string)
+            except ValueError:
+                pass
+        if isinstance(string, str):
+            msg = f"Cannot construct a 'PeriodDtype' from '{string}'"
+        else:
+            msg = f"'construct_from_string' expects a string, got {type(string)}"
+        raise TypeError(msg)
+
+    def __str__(self) -> str_type:
+        return self.name
+
+    @property
+    def name(self) -> str_type:
+        return f"period[{self._freqstr}]"
+
+    @property
+    def na_value(self) -> NaTType:
+        return NaT
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str):
+            return other in [self.name, capitalize_first_letter(self.name)]
+
+        return super().__eq__(other)
+
+    def __ne__(self, other: object) -> bool:
+        return not self.__eq__(other)
+
+    @classmethod
+    def is_dtype(cls, dtype: object) -> bool:
+        """
+        Return a boolean if we if the passed type is an actual dtype that we
+        can match (via string or type)
+        """
+        if isinstance(dtype, str):
+            # PeriodDtype can be instantiated from freq string like "U",
+            # but doesn't regard freq str like "U" as dtype.
+            if dtype.startswith(("period[", "Period[")):
+                try:
+                    return cls._parse_dtype_strict(dtype) is not None
+                except ValueError:
+                    return False
+            else:
+                return False
+        return super().is_dtype(dtype)
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[PeriodArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays import PeriodArray
+
+        return PeriodArray
+
+    def __from_arrow__(self, array: pa.Array | pa.ChunkedArray) -> PeriodArray:
+        """
+        Construct PeriodArray from pyarrow Array/ChunkedArray.
+        """
+        import pyarrow
+
+        from pandas.core.arrays import PeriodArray
+        from pandas.core.arrays.arrow._arrow_utils import (
+            pyarrow_array_to_numpy_and_mask,
+        )
+
+        if isinstance(array, pyarrow.Array):
+            chunks = [array]
+        else:
+            chunks = array.chunks
+
+        results = []
+        for arr in chunks:
+            data, mask = pyarrow_array_to_numpy_and_mask(arr, dtype=np.dtype(np.int64))
+            parr = PeriodArray(data.copy(), dtype=self, copy=False)
+            # error: Invalid index type "ndarray[Any, dtype[bool_]]" for "PeriodArray";
+            # expected type "Union[int, Sequence[int], Sequence[bool], slice]"
+            parr[~mask] = NaT  # type: ignore[index]
+            results.append(parr)
+
+        if not results:
+            return PeriodArray(np.array([], dtype="int64"), dtype=self, copy=False)
+        return PeriodArray._concat_same_type(results)
+
+    @cache_readonly
+    def index_class(self) -> type_t[PeriodIndex]:
+        from pandas import PeriodIndex
+
+        return PeriodIndex
+
+
+@register_extension_dtype
+class IntervalDtype(PandasExtensionDtype):
+    """
+    An ExtensionDtype for Interval data.
+
+    **This is not an actual numpy dtype**, but a duck type.
+
+    Parameters
+    ----------
+    subtype : str, np.dtype
+        The dtype of the Interval bounds.
+
+    Attributes
+    ----------
+    subtype
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> pd.IntervalDtype(subtype='int64', closed='both')
+    interval[int64, both]
+    """
+
+    name = "interval"
+    kind: str_type = "O"
+    str = "|O08"
+    base = np.dtype("O")
+    num = 103
+    _metadata = (
+        "subtype",
+        "closed",
+    )
+
+    _match = re.compile(
+        r"(I|i)nterval\[(?P[^,]+(\[.+\])?)"
+        r"(, (?P(right|left|both|neither)))?\]"
+    )
+
+    _cache_dtypes: dict[str_type, PandasExtensionDtype] = {}
+    _subtype: None | np.dtype
+    _closed: IntervalClosedType | None
+
+    def __init__(self, subtype=None, closed: IntervalClosedType | None = None) -> None:
+        from pandas.core.dtypes.common import (
+            is_string_dtype,
+            pandas_dtype,
+        )
+
+        if closed is not None and closed not in {"right", "left", "both", "neither"}:
+            raise ValueError("closed must be one of 'right', 'left', 'both', 'neither'")
+
+        if isinstance(subtype, IntervalDtype):
+            if closed is not None and closed != subtype.closed:
+                raise ValueError(
+                    "dtype.closed and 'closed' do not match. "
+                    "Try IntervalDtype(dtype.subtype, closed) instead."
+                )
+            self._subtype = subtype._subtype
+            self._closed = subtype._closed
+        elif subtype is None:
+            # we are called as an empty constructor
+            # generally for pickle compat
+            self._subtype = None
+            self._closed = closed
+        elif isinstance(subtype, str) and subtype.lower() == "interval":
+            self._subtype = None
+            self._closed = closed
+        else:
+            if isinstance(subtype, str):
+                m = IntervalDtype._match.search(subtype)
+                if m is not None:
+                    gd = m.groupdict()
+                    subtype = gd["subtype"]
+                    if gd.get("closed", None) is not None:
+                        if closed is not None:
+                            if closed != gd["closed"]:
+                                raise ValueError(
+                                    "'closed' keyword does not match value "
+                                    "specified in dtype string"
+                                )
+                        closed = gd["closed"]  # type: ignore[assignment]
+
+            try:
+                subtype = pandas_dtype(subtype)
+            except TypeError as err:
+                raise TypeError("could not construct IntervalDtype") from err
+            if CategoricalDtype.is_dtype(subtype) or is_string_dtype(subtype):
+                # GH 19016
+                msg = (
+                    "category, object, and string subtypes are not supported "
+                    "for IntervalDtype"
+                )
+                raise TypeError(msg)
+            self._subtype = subtype
+            self._closed = closed
+
+    @cache_readonly
+    def _can_hold_na(self) -> bool:
+        subtype = self._subtype
+        if subtype is None:
+            # partially-initialized
+            raise NotImplementedError(
+                "_can_hold_na is not defined for partially-initialized IntervalDtype"
+            )
+        if subtype.kind in "iu":
+            return False
+        return True
+
+    @property
+    def closed(self) -> IntervalClosedType:
+        return self._closed  # type: ignore[return-value]
+
+    @property
+    def subtype(self):
+        """
+        The dtype of the Interval bounds.
+
+        Examples
+        --------
+        >>> dtype = pd.IntervalDtype(subtype='int64', closed='both')
+        >>> dtype.subtype
+        dtype('int64')
+        """
+        return self._subtype
+
+    @classmethod
+    def construct_array_type(cls) -> type[IntervalArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays import IntervalArray
+
+        return IntervalArray
+
+    @classmethod
+    def construct_from_string(cls, string: str_type) -> IntervalDtype:
+        """
+        attempt to construct this type from a string, raise a TypeError
+        if its not possible
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+
+        if string.lower() == "interval" or cls._match.search(string) is not None:
+            return cls(string)
+
+        msg = (
+            f"Cannot construct a 'IntervalDtype' from '{string}'.\n\n"
+            "Incorrectly formatted string passed to constructor. "
+            "Valid formats include Interval or Interval[dtype] "
+            "where dtype is numeric, datetime, or timedelta"
+        )
+        raise TypeError(msg)
+
+    @property
+    def type(self) -> type[Interval]:
+        return Interval
+
+    def __str__(self) -> str_type:
+        if self.subtype is None:
+            return "interval"
+        if self.closed is None:
+            # Only partially initialized GH#38394
+            return f"interval[{self.subtype}]"
+        return f"interval[{self.subtype}, {self.closed}]"
+
+    def __hash__(self) -> int:
+        # make myself hashable
+        return hash(str(self))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, str):
+            return other.lower() in (self.name.lower(), str(self).lower())
+        elif not isinstance(other, IntervalDtype):
+            return False
+        elif self.subtype is None or other.subtype is None:
+            # None should match any subtype
+            return True
+        elif self.closed != other.closed:
+            return False
+        else:
+            return self.subtype == other.subtype
+
+    def __setstate__(self, state) -> None:
+        # for pickle compat. __get_state__ is defined in the
+        # PandasExtensionDtype superclass and uses the public properties to
+        # pickle -> need to set the settable private ones here (see GH26067)
+        self._subtype = state["subtype"]
+
+        # backward-compat older pickles won't have "closed" key
+        self._closed = state.pop("closed", None)
+
+    @classmethod
+    def is_dtype(cls, dtype: object) -> bool:
+        """
+        Return a boolean if we if the passed type is an actual dtype that we
+        can match (via string or type)
+        """
+        if isinstance(dtype, str):
+            if dtype.lower().startswith("interval"):
+                try:
+                    return cls.construct_from_string(dtype) is not None
+                except (ValueError, TypeError):
+                    return False
+            else:
+                return False
+        return super().is_dtype(dtype)
+
+    def __from_arrow__(self, array: pa.Array | pa.ChunkedArray) -> IntervalArray:
+        """
+        Construct IntervalArray from pyarrow Array/ChunkedArray.
+        """
+        import pyarrow
+
+        from pandas.core.arrays import IntervalArray
+
+        if isinstance(array, pyarrow.Array):
+            chunks = [array]
+        else:
+            chunks = array.chunks
+
+        results = []
+        for arr in chunks:
+            if isinstance(arr, pyarrow.ExtensionArray):
+                arr = arr.storage
+            left = np.asarray(arr.field("left"), dtype=self.subtype)
+            right = np.asarray(arr.field("right"), dtype=self.subtype)
+            iarr = IntervalArray.from_arrays(left, right, closed=self.closed)
+            results.append(iarr)
+
+        if not results:
+            return IntervalArray.from_arrays(
+                np.array([], dtype=self.subtype),
+                np.array([], dtype=self.subtype),
+                closed=self.closed,
+            )
+        return IntervalArray._concat_same_type(results)
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        if not all(isinstance(x, IntervalDtype) for x in dtypes):
+            return None
+
+        closed = cast("IntervalDtype", dtypes[0]).closed
+        if not all(cast("IntervalDtype", x).closed == closed for x in dtypes):
+            return np.dtype(object)
+
+        from pandas.core.dtypes.cast import find_common_type
+
+        common = find_common_type([cast("IntervalDtype", x).subtype for x in dtypes])
+        if common == object:
+            return np.dtype(object)
+        return IntervalDtype(common, closed=closed)
+
+    @cache_readonly
+    def index_class(self) -> type_t[IntervalIndex]:
+        from pandas import IntervalIndex
+
+        return IntervalIndex
+
+
+class NumpyEADtype(ExtensionDtype):
+    """
+    A Pandas ExtensionDtype for NumPy dtypes.
+
+    This is mostly for internal compatibility, and is not especially
+    useful on its own.
+
+    Parameters
+    ----------
+    dtype : object
+        Object to be converted to a NumPy data type object.
+
+    See Also
+    --------
+    numpy.dtype
+    """
+
+    _metadata = ("_dtype",)
+    _supports_2d = False
+    _can_fast_transpose = False
+
+    def __init__(self, dtype: npt.DTypeLike | NumpyEADtype | None) -> None:
+        if isinstance(dtype, NumpyEADtype):
+            # make constructor idempotent
+            dtype = dtype.numpy_dtype
+        self._dtype = np.dtype(dtype)
+
+    def __repr__(self) -> str:
+        return f"NumpyEADtype({repr(self.name)})"
+
+    @property
+    def numpy_dtype(self) -> np.dtype:
+        """
+        The NumPy dtype this NumpyEADtype wraps.
+        """
+        return self._dtype
+
+    @property
+    def name(self) -> str:
+        """
+        A bit-width name for this data-type.
+        """
+        return self._dtype.name
+
+    @property
+    def type(self) -> type[np.generic]:
+        """
+        The type object used to instantiate a scalar of this NumPy data-type.
+        """
+        return self._dtype.type
+
+    @property
+    def _is_numeric(self) -> bool:
+        # exclude object, str, unicode, void.
+        return self.kind in set("biufc")
+
+    @property
+    def _is_boolean(self) -> bool:
+        return self.kind == "b"
+
+    @classmethod
+    def construct_from_string(cls, string: str) -> NumpyEADtype:
+        try:
+            dtype = np.dtype(string)
+        except TypeError as err:
+            if not isinstance(string, str):
+                msg = f"'construct_from_string' expects a string, got {type(string)}"
+            else:
+                msg = f"Cannot construct a 'NumpyEADtype' from '{string}'"
+            raise TypeError(msg) from err
+        return cls(dtype)
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[NumpyExtensionArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays import NumpyExtensionArray
+
+        return NumpyExtensionArray
+
+    @property
+    def kind(self) -> str:
+        """
+        A character code (one of 'biufcmMOSUV') identifying the general kind of data.
+        """
+        return self._dtype.kind
+
+    @property
+    def itemsize(self) -> int:
+        """
+        The element size of this data-type object.
+        """
+        return self._dtype.itemsize
+
+
+class BaseMaskedDtype(ExtensionDtype):
+    """
+    Base class for dtypes for BaseMaskedArray subclasses.
+    """
+
+    base = None
+    type: type
+
+    @property
+    def na_value(self) -> libmissing.NAType:
+        return libmissing.NA
+
+    @cache_readonly
+    def numpy_dtype(self) -> np.dtype:
+        """Return an instance of our numpy dtype"""
+        return np.dtype(self.type)
+
+    @cache_readonly
+    def kind(self) -> str:
+        return self.numpy_dtype.kind
+
+    @cache_readonly
+    def itemsize(self) -> int:
+        """Return the number of bytes in this dtype"""
+        return self.numpy_dtype.itemsize
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[BaseMaskedArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        raise NotImplementedError
+
+    @classmethod
+    def from_numpy_dtype(cls, dtype: np.dtype) -> BaseMaskedDtype:
+        """
+        Construct the MaskedDtype corresponding to the given numpy dtype.
+        """
+        if dtype.kind == "b":
+            from pandas.core.arrays.boolean import BooleanDtype
+
+            return BooleanDtype()
+        elif dtype.kind in "iu":
+            from pandas.core.arrays.integer import NUMPY_INT_TO_DTYPE
+
+            return NUMPY_INT_TO_DTYPE[dtype]
+        elif dtype.kind == "f":
+            from pandas.core.arrays.floating import NUMPY_FLOAT_TO_DTYPE
+
+            return NUMPY_FLOAT_TO_DTYPE[dtype]
+        else:
+            raise NotImplementedError(dtype)
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        # We unwrap any masked dtypes, find the common dtype we would use
+        #  for that, then re-mask the result.
+        from pandas.core.dtypes.cast import find_common_type
+
+        new_dtype = find_common_type(
+            [
+                dtype.numpy_dtype if isinstance(dtype, BaseMaskedDtype) else dtype
+                for dtype in dtypes
+            ]
+        )
+        if not isinstance(new_dtype, np.dtype):
+            # If we ever support e.g. Masked[DatetimeArray] then this will change
+            return None
+        try:
+            return type(self).from_numpy_dtype(new_dtype)
+        except (KeyError, NotImplementedError):
+            return None
+
+
+@register_extension_dtype
+class SparseDtype(ExtensionDtype):
+    """
+    Dtype for data stored in :class:`SparseArray`.
+
+    This dtype implements the pandas ExtensionDtype interface.
+
+    Parameters
+    ----------
+    dtype : str, ExtensionDtype, numpy.dtype, type, default numpy.float64
+        The dtype of the underlying array storing the non-fill value values.
+    fill_value : scalar, optional
+        The scalar value not stored in the SparseArray. By default, this
+        depends on `dtype`.
+
+        =========== ==========
+        dtype       na_value
+        =========== ==========
+        float       ``np.nan``
+        int         ``0``
+        bool        ``False``
+        datetime64  ``pd.NaT``
+        timedelta64 ``pd.NaT``
+        =========== ==========
+
+        The default value may be overridden by specifying a `fill_value`.
+
+    Attributes
+    ----------
+    None
+
+    Methods
+    -------
+    None
+
+    Examples
+    --------
+    >>> ser = pd.Series([1, 0, 0], dtype=pd.SparseDtype(dtype=int, fill_value=0))
+    >>> ser
+    0    1
+    1    0
+    2    0
+    dtype: Sparse[int64, 0]
+    >>> ser.sparse.density
+    0.3333333333333333
+    """
+
+    _is_immutable = True
+
+    # We include `_is_na_fill_value` in the metadata to avoid hash collisions
+    # between SparseDtype(float, 0.0) and SparseDtype(float, nan).
+    # Without is_na_fill_value in the comparison, those would be equal since
+    # hash(nan) is (sometimes?) 0.
+    _metadata = ("_dtype", "_fill_value", "_is_na_fill_value")
+
+    def __init__(self, dtype: Dtype = np.float64, fill_value: Any = None) -> None:
+        if isinstance(dtype, type(self)):
+            if fill_value is None:
+                fill_value = dtype.fill_value
+            dtype = dtype.subtype
+
+        from pandas.core.dtypes.common import (
+            is_string_dtype,
+            pandas_dtype,
+        )
+        from pandas.core.dtypes.missing import na_value_for_dtype
+
+        dtype = pandas_dtype(dtype)
+        if is_string_dtype(dtype):
+            dtype = np.dtype("object")
+        if not isinstance(dtype, np.dtype):
+            # GH#53160
+            raise TypeError("SparseDtype subtype must be a numpy dtype")
+
+        if fill_value is None:
+            fill_value = na_value_for_dtype(dtype)
+
+        self._dtype = dtype
+        self._fill_value = fill_value
+        self._check_fill_value()
+
+    def __hash__(self) -> int:
+        # Python3 doesn't inherit __hash__ when a base class overrides
+        # __eq__, so we explicitly do it here.
+        return super().__hash__()
+
+    def __eq__(self, other: object) -> bool:
+        # We have to override __eq__ to handle NA values in _metadata.
+        # The base class does simple == checks, which fail for NA.
+        if isinstance(other, str):
+            try:
+                other = self.construct_from_string(other)
+            except TypeError:
+                return False
+
+        if isinstance(other, type(self)):
+            subtype = self.subtype == other.subtype
+            if self._is_na_fill_value:
+                # this case is complicated by two things:
+                # SparseDtype(float, float(nan)) == SparseDtype(float, np.nan)
+                # SparseDtype(float, np.nan)     != SparseDtype(float, pd.NaT)
+                # i.e. we want to treat any floating-point NaN as equal, but
+                # not a floating-point NaN and a datetime NaT.
+                fill_value = (
+                    other._is_na_fill_value
+                    and isinstance(self.fill_value, type(other.fill_value))
+                    or isinstance(other.fill_value, type(self.fill_value))
+                )
+            else:
+                with warnings.catch_warnings():
+                    # Ignore spurious numpy warning
+                    warnings.filterwarnings(
+                        "ignore",
+                        "elementwise comparison failed",
+                        category=DeprecationWarning,
+                    )
+
+                    fill_value = self.fill_value == other.fill_value
+
+            return subtype and fill_value
+        return False
+
+    @property
+    def fill_value(self):
+        """
+        The fill value of the array.
+
+        Converting the SparseArray to a dense ndarray will fill the
+        array with this value.
+
+        .. warning::
+
+           It's possible to end up with a SparseArray that has ``fill_value``
+           values in ``sp_values``. This can occur, for example, when setting
+           ``SparseArray.fill_value`` directly.
+        """
+        return self._fill_value
+
+    def _check_fill_value(self) -> None:
+        if not lib.is_scalar(self._fill_value):
+            raise ValueError(
+                f"fill_value must be a scalar. Got {self._fill_value} instead"
+            )
+
+        from pandas.core.dtypes.cast import can_hold_element
+        from pandas.core.dtypes.missing import (
+            is_valid_na_for_dtype,
+            isna,
+        )
+
+        from pandas.core.construction import ensure_wrapped_if_datetimelike
+
+        # GH#23124 require fill_value and subtype to match
+        val = self._fill_value
+        if isna(val):
+            if not is_valid_na_for_dtype(val, self.subtype):
+                warnings.warn(
+                    "Allowing arbitrary scalar fill_value in SparseDtype is "
+                    "deprecated. In a future version, the fill_value must be "
+                    "a valid value for the SparseDtype.subtype.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            dummy = np.empty(0, dtype=self.subtype)
+            dummy = ensure_wrapped_if_datetimelike(dummy)
+
+            if not can_hold_element(dummy, val):
+                warnings.warn(
+                    "Allowing arbitrary scalar fill_value in SparseDtype is "
+                    "deprecated. In a future version, the fill_value must be "
+                    "a valid value for the SparseDtype.subtype.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+    @property
+    def _is_na_fill_value(self) -> bool:
+        from pandas import isna
+
+        return isna(self.fill_value)
+
+    @property
+    def _is_numeric(self) -> bool:
+        return self.subtype != object
+
+    @property
+    def _is_boolean(self) -> bool:
+        return self.subtype.kind == "b"
+
+    @property
+    def kind(self) -> str:
+        """
+        The sparse kind. Either 'integer', or 'block'.
+        """
+        return self.subtype.kind
+
+    @property
+    def type(self):
+        return self.subtype.type
+
+    @property
+    def subtype(self):
+        return self._dtype
+
+    @property
+    def name(self) -> str:
+        return f"Sparse[{self.subtype.name}, {repr(self.fill_value)}]"
+
+    def __repr__(self) -> str:
+        return self.name
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[SparseArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays.sparse.array import SparseArray
+
+        return SparseArray
+
+    @classmethod
+    def construct_from_string(cls, string: str) -> SparseDtype:
+        """
+        Construct a SparseDtype from a string form.
+
+        Parameters
+        ----------
+        string : str
+            Can take the following forms.
+
+            string           dtype
+            ================ ============================
+            'int'            SparseDtype[np.int64, 0]
+            'Sparse'         SparseDtype[np.float64, nan]
+            'Sparse[int]'    SparseDtype[np.int64, 0]
+            'Sparse[int, 0]' SparseDtype[np.int64, 0]
+            ================ ============================
+
+            It is not possible to specify non-default fill values
+            with a string. An argument like ``'Sparse[int, 1]'``
+            will raise a ``TypeError`` because the default fill value
+            for integers is 0.
+
+        Returns
+        -------
+        SparseDtype
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+        msg = f"Cannot construct a 'SparseDtype' from '{string}'"
+        if string.startswith("Sparse"):
+            try:
+                sub_type, has_fill_value = cls._parse_subtype(string)
+            except ValueError as err:
+                raise TypeError(msg) from err
+            else:
+                result = SparseDtype(sub_type)
+                msg = (
+                    f"Cannot construct a 'SparseDtype' from '{string}'.\n\nIt "
+                    "looks like the fill_value in the string is not "
+                    "the default for the dtype. Non-default fill_values "
+                    "are not supported. Use the 'SparseDtype()' "
+                    "constructor instead."
+                )
+                if has_fill_value and str(result) != string:
+                    raise TypeError(msg)
+                return result
+        else:
+            raise TypeError(msg)
+
+    @staticmethod
+    def _parse_subtype(dtype: str) -> tuple[str, bool]:
+        """
+        Parse a string to get the subtype
+
+        Parameters
+        ----------
+        dtype : str
+            A string like
+
+            * Sparse[subtype]
+            * Sparse[subtype, fill_value]
+
+        Returns
+        -------
+        subtype : str
+
+        Raises
+        ------
+        ValueError
+            When the subtype cannot be extracted.
+        """
+        xpr = re.compile(r"Sparse\[(?P[^,]*)(, )?(?P.*?)?\]$")
+        m = xpr.match(dtype)
+        has_fill_value = False
+        if m:
+            subtype = m.groupdict()["subtype"]
+            has_fill_value = bool(m.groupdict()["fill_value"])
+        elif dtype == "Sparse":
+            subtype = "float64"
+        else:
+            raise ValueError(f"Cannot parse {dtype}")
+        return subtype, has_fill_value
+
+    @classmethod
+    def is_dtype(cls, dtype: object) -> bool:
+        dtype = getattr(dtype, "dtype", dtype)
+        if isinstance(dtype, str) and dtype.startswith("Sparse"):
+            sub_type, _ = cls._parse_subtype(dtype)
+            dtype = np.dtype(sub_type)
+        elif isinstance(dtype, cls):
+            return True
+        return isinstance(dtype, np.dtype) or dtype == "Sparse"
+
+    def update_dtype(self, dtype) -> SparseDtype:
+        """
+        Convert the SparseDtype to a new dtype.
+
+        This takes care of converting the ``fill_value``.
+
+        Parameters
+        ----------
+        dtype : Union[str, numpy.dtype, SparseDtype]
+            The new dtype to use.
+
+            * For a SparseDtype, it is simply returned
+            * For a NumPy dtype (or str), the current fill value
+              is converted to the new dtype, and a SparseDtype
+              with `dtype` and the new fill value is returned.
+
+        Returns
+        -------
+        SparseDtype
+            A new SparseDtype with the correct `dtype` and fill value
+            for that `dtype`.
+
+        Raises
+        ------
+        ValueError
+            When the current fill value cannot be converted to the
+            new `dtype` (e.g. trying to convert ``np.nan`` to an
+            integer dtype).
+
+
+        Examples
+        --------
+        >>> SparseDtype(int, 0).update_dtype(float)
+        Sparse[float64, 0.0]
+
+        >>> SparseDtype(int, 1).update_dtype(SparseDtype(float, np.nan))
+        Sparse[float64, nan]
+        """
+        from pandas.core.dtypes.astype import astype_array
+        from pandas.core.dtypes.common import pandas_dtype
+
+        cls = type(self)
+        dtype = pandas_dtype(dtype)
+
+        if not isinstance(dtype, cls):
+            if not isinstance(dtype, np.dtype):
+                raise TypeError("sparse arrays of extension dtypes not supported")
+
+            fv_asarray = np.atleast_1d(np.array(self.fill_value))
+            fvarr = astype_array(fv_asarray, dtype)
+            # NB: not fv_0d.item(), as that casts dt64->int
+            fill_value = fvarr[0]
+            dtype = cls(dtype, fill_value=fill_value)
+
+        return dtype
+
+    @property
+    def _subtype_with_str(self):
+        """
+        Whether the SparseDtype's subtype should be considered ``str``.
+
+        Typically, pandas will store string data in an object-dtype array.
+        When converting values to a dtype, e.g. in ``.astype``, we need to
+        be more specific, we need the actual underlying type.
+
+        Returns
+        -------
+        >>> SparseDtype(int, 1)._subtype_with_str
+        dtype('int64')
+
+        >>> SparseDtype(object, 1)._subtype_with_str
+        dtype('O')
+
+        >>> dtype = SparseDtype(str, '')
+        >>> dtype.subtype
+        dtype('O')
+
+        >>> dtype._subtype_with_str
+        
+        """
+        if isinstance(self.fill_value, str):
+            return type(self.fill_value)
+        return self.subtype
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        # TODO for now only handle SparseDtypes and numpy dtypes => extend
+        # with other compatible extension dtypes
+        from pandas.core.dtypes.cast import np_find_common_type
+
+        if any(
+            isinstance(x, ExtensionDtype) and not isinstance(x, SparseDtype)
+            for x in dtypes
+        ):
+            return None
+
+        fill_values = [x.fill_value for x in dtypes if isinstance(x, SparseDtype)]
+        fill_value = fill_values[0]
+
+        from pandas import isna
+
+        # np.nan isn't a singleton, so we may end up with multiple
+        # NaNs here, so we ignore the all NA case too.
+        if not (len(set(fill_values)) == 1 or isna(fill_values).all()):
+            warnings.warn(
+                "Concatenating sparse arrays with multiple fill "
+                f"values: '{fill_values}'. Picking the first and "
+                "converting the rest.",
+                PerformanceWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        np_dtypes = (x.subtype if isinstance(x, SparseDtype) else x for x in dtypes)
+        return SparseDtype(np_find_common_type(*np_dtypes), fill_value=fill_value)
+
+
+@register_extension_dtype
+class ArrowDtype(StorageExtensionDtype):
+    """
+    An ExtensionDtype for PyArrow data types.
+
+    .. warning::
+
+       ArrowDtype is considered experimental. The implementation and
+       parts of the API may change without warning.
+
+    While most ``dtype`` arguments can accept the "string"
+    constructor, e.g. ``"int64[pyarrow]"``, ArrowDtype is useful
+    if the data type contains parameters like ``pyarrow.timestamp``.
+
+    Parameters
+    ----------
+    pyarrow_dtype : pa.DataType
+        An instance of a `pyarrow.DataType `__.
+
+    Attributes
+    ----------
+    pyarrow_dtype
+
+    Methods
+    -------
+    None
+
+    Returns
+    -------
+    ArrowDtype
+
+    Examples
+    --------
+    >>> import pyarrow as pa
+    >>> pd.ArrowDtype(pa.int64())
+    int64[pyarrow]
+
+    Types with parameters must be constructed with ArrowDtype.
+
+    >>> pd.ArrowDtype(pa.timestamp("s", tz="America/New_York"))
+    timestamp[s, tz=America/New_York][pyarrow]
+    >>> pd.ArrowDtype(pa.list_(pa.int64()))
+    list[pyarrow]
+    """
+
+    _metadata = ("storage", "pyarrow_dtype")  # type: ignore[assignment]
+
+    def __init__(self, pyarrow_dtype: pa.DataType) -> None:
+        super().__init__("pyarrow")
+        if pa_version_under10p1:
+            raise ImportError("pyarrow>=10.0.1 is required for ArrowDtype")
+        if not isinstance(pyarrow_dtype, pa.DataType):
+            raise ValueError(
+                f"pyarrow_dtype ({pyarrow_dtype}) must be an instance "
+                f"of a pyarrow.DataType. Got {type(pyarrow_dtype)} instead."
+            )
+        self.pyarrow_dtype = pyarrow_dtype
+
+    def __repr__(self) -> str:
+        return self.name
+
+    def __hash__(self) -> int:
+        # make myself hashable
+        return hash(str(self))
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, type(self)):
+            return super().__eq__(other)
+        return self.pyarrow_dtype == other.pyarrow_dtype
+
+    @property
+    def type(self):
+        """
+        Returns associated scalar type.
+        """
+        pa_type = self.pyarrow_dtype
+        if pa.types.is_integer(pa_type):
+            return int
+        elif pa.types.is_floating(pa_type):
+            return float
+        elif pa.types.is_string(pa_type) or pa.types.is_large_string(pa_type):
+            return str
+        elif (
+            pa.types.is_binary(pa_type)
+            or pa.types.is_fixed_size_binary(pa_type)
+            or pa.types.is_large_binary(pa_type)
+        ):
+            return bytes
+        elif pa.types.is_boolean(pa_type):
+            return bool
+        elif pa.types.is_duration(pa_type):
+            if pa_type.unit == "ns":
+                return Timedelta
+            else:
+                return timedelta
+        elif pa.types.is_timestamp(pa_type):
+            if pa_type.unit == "ns":
+                return Timestamp
+            else:
+                return datetime
+        elif pa.types.is_date(pa_type):
+            return date
+        elif pa.types.is_time(pa_type):
+            return time
+        elif pa.types.is_decimal(pa_type):
+            return Decimal
+        elif pa.types.is_dictionary(pa_type):
+            # TODO: Potentially change this & CategoricalDtype.type to
+            #  something more representative of the scalar
+            return CategoricalDtypeType
+        elif pa.types.is_list(pa_type) or pa.types.is_large_list(pa_type):
+            return list
+        elif pa.types.is_fixed_size_list(pa_type):
+            return list
+        elif pa.types.is_map(pa_type):
+            return list
+        elif pa.types.is_struct(pa_type):
+            return dict
+        elif pa.types.is_null(pa_type):
+            # TODO: None? pd.NA? pa.null?
+            return type(pa_type)
+        elif isinstance(pa_type, pa.ExtensionType):
+            return type(self)(pa_type.storage_type).type
+        raise NotImplementedError(pa_type)
+
+    @property
+    def name(self) -> str:  # type: ignore[override]
+        """
+        A string identifying the data type.
+        """
+        return f"{str(self.pyarrow_dtype)}[{self.storage}]"
+
+    @cache_readonly
+    def numpy_dtype(self) -> np.dtype:
+        """Return an instance of the related numpy dtype"""
+        if pa.types.is_timestamp(self.pyarrow_dtype):
+            # pa.timestamp(unit).to_pandas_dtype() returns ns units
+            # regardless of the pyarrow timestamp units.
+            # This can be removed if/when pyarrow addresses it:
+            # https://github.com/apache/arrow/issues/34462
+            return np.dtype(f"datetime64[{self.pyarrow_dtype.unit}]")
+        if pa.types.is_duration(self.pyarrow_dtype):
+            # pa.duration(unit).to_pandas_dtype() returns ns units
+            # regardless of the pyarrow duration units
+            # This can be removed if/when pyarrow addresses it:
+            # https://github.com/apache/arrow/issues/34462
+            return np.dtype(f"timedelta64[{self.pyarrow_dtype.unit}]")
+        if pa.types.is_string(self.pyarrow_dtype) or pa.types.is_large_string(
+            self.pyarrow_dtype
+        ):
+            # pa.string().to_pandas_dtype() = object which we don't want
+            return np.dtype(str)
+        try:
+            return np.dtype(self.pyarrow_dtype.to_pandas_dtype())
+        except (NotImplementedError, TypeError):
+            return np.dtype(object)
+
+    @cache_readonly
+    def kind(self) -> str:
+        if pa.types.is_timestamp(self.pyarrow_dtype):
+            # To mirror DatetimeTZDtype
+            return "M"
+        return self.numpy_dtype.kind
+
+    @cache_readonly
+    def itemsize(self) -> int:
+        """Return the number of bytes in this dtype"""
+        return self.numpy_dtype.itemsize
+
+    @classmethod
+    def construct_array_type(cls) -> type_t[ArrowExtensionArray]:
+        """
+        Return the array type associated with this dtype.
+
+        Returns
+        -------
+        type
+        """
+        from pandas.core.arrays.arrow import ArrowExtensionArray
+
+        return ArrowExtensionArray
+
+    @classmethod
+    def construct_from_string(cls, string: str) -> ArrowDtype:
+        """
+        Construct this type from a string.
+
+        Parameters
+        ----------
+        string : str
+            string should follow the format f"{pyarrow_type}[pyarrow]"
+            e.g. int64[pyarrow]
+        """
+        if not isinstance(string, str):
+            raise TypeError(
+                f"'construct_from_string' expects a string, got {type(string)}"
+            )
+        if not string.endswith("[pyarrow]"):
+            raise TypeError(f"'{string}' must end with '[pyarrow]'")
+        if string in ("string[pyarrow]", "str[pyarrow]"):
+            # Ensure Registry.find skips ArrowDtype to use StringDtype instead
+            raise TypeError("string[pyarrow] should be constructed by StringDtype")
+
+        base_type = string[:-9]  # get rid of "[pyarrow]"
+        try:
+            pa_dtype = pa.type_for_alias(base_type)
+        except ValueError as err:
+            has_parameters = re.search(r"[\[\(].*[\]\)]", base_type)
+            if has_parameters:
+                # Fallback to try common temporal types
+                try:
+                    return cls._parse_temporal_dtype_string(base_type)
+                except (NotImplementedError, ValueError):
+                    # Fall through to raise with nice exception message below
+                    pass
+
+                raise NotImplementedError(
+                    "Passing pyarrow type specific parameters "
+                    f"({has_parameters.group()}) in the string is not supported. "
+                    "Please construct an ArrowDtype object with a pyarrow_dtype "
+                    "instance with specific parameters."
+                ) from err
+            raise TypeError(f"'{base_type}' is not a valid pyarrow data type.") from err
+        return cls(pa_dtype)
+
+    # TODO(arrow#33642): This can be removed once supported by pyarrow
+    @classmethod
+    def _parse_temporal_dtype_string(cls, string: str) -> ArrowDtype:
+        """
+        Construct a temporal ArrowDtype from string.
+        """
+        # we assume
+        #  1) "[pyarrow]" has already been stripped from the end of our string.
+        #  2) we know "[" is present
+        head, tail = string.split("[", 1)
+
+        if not tail.endswith("]"):
+            raise ValueError
+        tail = tail[:-1]
+
+        if head == "timestamp":
+            assert "," in tail  # otherwise type_for_alias should work
+            unit, tz = tail.split(",", 1)
+            unit = unit.strip()
+            tz = tz.strip()
+            if tz.startswith("tz="):
+                tz = tz[3:]
+
+            pa_type = pa.timestamp(unit, tz=tz)
+            dtype = cls(pa_type)
+            return dtype
+
+        raise NotImplementedError(string)
+
+    @property
+    def _is_numeric(self) -> bool:
+        """
+        Whether columns with this dtype should be considered numeric.
+        """
+        # TODO: pa.types.is_boolean?
+        return (
+            pa.types.is_integer(self.pyarrow_dtype)
+            or pa.types.is_floating(self.pyarrow_dtype)
+            or pa.types.is_decimal(self.pyarrow_dtype)
+        )
+
+    @property
+    def _is_boolean(self) -> bool:
+        """
+        Whether this dtype should be considered boolean.
+        """
+        return pa.types.is_boolean(self.pyarrow_dtype)
+
+    def _get_common_dtype(self, dtypes: list[DtypeObj]) -> DtypeObj | None:
+        # We unwrap any masked dtypes, find the common dtype we would use
+        #  for that, then re-mask the result.
+        # Mirrors BaseMaskedDtype
+        from pandas.core.dtypes.cast import find_common_type
+
+        null_dtype = type(self)(pa.null())
+
+        new_dtype = find_common_type(
+            [
+                dtype.numpy_dtype if isinstance(dtype, ArrowDtype) else dtype
+                for dtype in dtypes
+                if dtype != null_dtype
+            ]
+        )
+        if not isinstance(new_dtype, np.dtype):
+            return None
+        try:
+            pa_dtype = pa.from_numpy_dtype(new_dtype)
+            return type(self)(pa_dtype)
+        except NotImplementedError:
+            return None
+
+    def __from_arrow__(self, array: pa.Array | pa.ChunkedArray):
+        """
+        Construct IntegerArray/FloatingArray from pyarrow Array/ChunkedArray.
+        """
+        array_class = self.construct_array_type()
+        arr = array.cast(self.pyarrow_dtype, safe=True)
+        return array_class(arr)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/generic.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/generic.py
new file mode 100644
index 0000000000000000000000000000000000000000..9718ad600cb80b6e38f069a83aaf35ddb376fb00
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/generic.py
@@ -0,0 +1,147 @@
+""" define generic base classes for pandas objects """
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Type,
+    cast,
+)
+
+if TYPE_CHECKING:
+    from pandas import (
+        Categorical,
+        CategoricalIndex,
+        DataFrame,
+        DatetimeIndex,
+        Index,
+        IntervalIndex,
+        MultiIndex,
+        PeriodIndex,
+        RangeIndex,
+        Series,
+        TimedeltaIndex,
+    )
+    from pandas.core.arrays import (
+        DatetimeArray,
+        ExtensionArray,
+        NumpyExtensionArray,
+        PeriodArray,
+        TimedeltaArray,
+    )
+    from pandas.core.generic import NDFrame
+
+
+# define abstract base classes to enable isinstance type checking on our
+# objects
+def create_pandas_abc_type(name, attr, comp):
+    def _check(inst) -> bool:
+        return getattr(inst, attr, "_typ") in comp
+
+    # https://github.com/python/mypy/issues/1006
+    # error: 'classmethod' used with a non-method
+    @classmethod  # type: ignore[misc]
+    def _instancecheck(cls, inst) -> bool:
+        return _check(inst) and not isinstance(inst, type)
+
+    @classmethod  # type: ignore[misc]
+    def _subclasscheck(cls, inst) -> bool:
+        # Raise instead of returning False
+        # This is consistent with default __subclasscheck__ behavior
+        if not isinstance(inst, type):
+            raise TypeError("issubclass() arg 1 must be a class")
+
+        return _check(inst)
+
+    dct = {"__instancecheck__": _instancecheck, "__subclasscheck__": _subclasscheck}
+    meta = type("ABCBase", (type,), dct)
+    return meta(name, (), dct)
+
+
+ABCRangeIndex = cast(
+    "Type[RangeIndex]",
+    create_pandas_abc_type("ABCRangeIndex", "_typ", ("rangeindex",)),
+)
+ABCMultiIndex = cast(
+    "Type[MultiIndex]",
+    create_pandas_abc_type("ABCMultiIndex", "_typ", ("multiindex",)),
+)
+ABCDatetimeIndex = cast(
+    "Type[DatetimeIndex]",
+    create_pandas_abc_type("ABCDatetimeIndex", "_typ", ("datetimeindex",)),
+)
+ABCTimedeltaIndex = cast(
+    "Type[TimedeltaIndex]",
+    create_pandas_abc_type("ABCTimedeltaIndex", "_typ", ("timedeltaindex",)),
+)
+ABCPeriodIndex = cast(
+    "Type[PeriodIndex]",
+    create_pandas_abc_type("ABCPeriodIndex", "_typ", ("periodindex",)),
+)
+ABCCategoricalIndex = cast(
+    "Type[CategoricalIndex]",
+    create_pandas_abc_type("ABCCategoricalIndex", "_typ", ("categoricalindex",)),
+)
+ABCIntervalIndex = cast(
+    "Type[IntervalIndex]",
+    create_pandas_abc_type("ABCIntervalIndex", "_typ", ("intervalindex",)),
+)
+ABCIndex = cast(
+    "Type[Index]",
+    create_pandas_abc_type(
+        "ABCIndex",
+        "_typ",
+        {
+            "index",
+            "rangeindex",
+            "multiindex",
+            "datetimeindex",
+            "timedeltaindex",
+            "periodindex",
+            "categoricalindex",
+            "intervalindex",
+        },
+    ),
+)
+
+
+ABCNDFrame = cast(
+    "Type[NDFrame]",
+    create_pandas_abc_type("ABCNDFrame", "_typ", ("series", "dataframe")),
+)
+ABCSeries = cast(
+    "Type[Series]",
+    create_pandas_abc_type("ABCSeries", "_typ", ("series",)),
+)
+ABCDataFrame = cast(
+    "Type[DataFrame]", create_pandas_abc_type("ABCDataFrame", "_typ", ("dataframe",))
+)
+
+ABCCategorical = cast(
+    "Type[Categorical]",
+    create_pandas_abc_type("ABCCategorical", "_typ", ("categorical")),
+)
+ABCDatetimeArray = cast(
+    "Type[DatetimeArray]",
+    create_pandas_abc_type("ABCDatetimeArray", "_typ", ("datetimearray")),
+)
+ABCTimedeltaArray = cast(
+    "Type[TimedeltaArray]",
+    create_pandas_abc_type("ABCTimedeltaArray", "_typ", ("timedeltaarray")),
+)
+ABCPeriodArray = cast(
+    "Type[PeriodArray]",
+    create_pandas_abc_type("ABCPeriodArray", "_typ", ("periodarray",)),
+)
+ABCExtensionArray = cast(
+    "Type[ExtensionArray]",
+    create_pandas_abc_type(
+        "ABCExtensionArray",
+        "_typ",
+        # Note: IntervalArray and SparseArray are included bc they have _typ="extension"
+        {"extension", "categorical", "periodarray", "datetimearray", "timedeltaarray"},
+    ),
+)
+ABCNumpyExtensionArray = cast(
+    "Type[NumpyExtensionArray]",
+    create_pandas_abc_type("ABCNumpyExtensionArray", "_typ", ("npy_extension",)),
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/inference.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/inference.py
new file mode 100644
index 0000000000000000000000000000000000000000..f551716772f61455a330bdb308cee830bd54fb03
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/inference.py
@@ -0,0 +1,437 @@
+""" basic inference routines """
+
+from __future__ import annotations
+
+from collections import abc
+from numbers import Number
+import re
+from re import Pattern
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs import lib
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import TypeGuard
+
+is_bool = lib.is_bool
+
+is_integer = lib.is_integer
+
+is_float = lib.is_float
+
+is_complex = lib.is_complex
+
+is_scalar = lib.is_scalar
+
+is_decimal = lib.is_decimal
+
+is_interval = lib.is_interval
+
+is_list_like = lib.is_list_like
+
+is_iterator = lib.is_iterator
+
+
+def is_number(obj) -> TypeGuard[Number | np.number]:
+    """
+    Check if the object is a number.
+
+    Returns True when the object is a number, and False if is not.
+
+    Parameters
+    ----------
+    obj : any type
+        The object to check if is a number.
+
+    Returns
+    -------
+    bool
+        Whether `obj` is a number or not.
+
+    See Also
+    --------
+    api.types.is_integer: Checks a subgroup of numbers.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_number
+    >>> is_number(1)
+    True
+    >>> is_number(7.15)
+    True
+
+    Booleans are valid because they are int subclass.
+
+    >>> is_number(False)
+    True
+
+    >>> is_number("foo")
+    False
+    >>> is_number("5")
+    False
+    """
+    return isinstance(obj, (Number, np.number))
+
+
+def iterable_not_string(obj) -> bool:
+    """
+    Check if the object is an iterable but not a string.
+
+    Parameters
+    ----------
+    obj : The object to check.
+
+    Returns
+    -------
+    is_iter_not_string : bool
+        Whether `obj` is a non-string iterable.
+
+    Examples
+    --------
+    >>> iterable_not_string([1, 2, 3])
+    True
+    >>> iterable_not_string("foo")
+    False
+    >>> iterable_not_string(1)
+    False
+    """
+    return isinstance(obj, abc.Iterable) and not isinstance(obj, str)
+
+
+def is_file_like(obj) -> bool:
+    """
+    Check if the object is a file-like object.
+
+    For objects to be considered file-like, they must
+    be an iterator AND have either a `read` and/or `write`
+    method as an attribute.
+
+    Note: file-like objects must be iterable, but
+    iterable objects need not be file-like.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    bool
+        Whether `obj` has file-like properties.
+
+    Examples
+    --------
+    >>> import io
+    >>> from pandas.api.types import is_file_like
+    >>> buffer = io.StringIO("data")
+    >>> is_file_like(buffer)
+    True
+    >>> is_file_like([1, 2, 3])
+    False
+    """
+    if not (hasattr(obj, "read") or hasattr(obj, "write")):
+        return False
+
+    return bool(hasattr(obj, "__iter__"))
+
+
+def is_re(obj) -> TypeGuard[Pattern]:
+    """
+    Check if the object is a regex pattern instance.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    bool
+        Whether `obj` is a regex pattern.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_re
+    >>> import re
+    >>> is_re(re.compile(".*"))
+    True
+    >>> is_re("foo")
+    False
+    """
+    return isinstance(obj, Pattern)
+
+
+def is_re_compilable(obj) -> bool:
+    """
+    Check if the object can be compiled into a regex pattern instance.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    bool
+        Whether `obj` can be compiled as a regex pattern.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_re_compilable
+    >>> is_re_compilable(".*")
+    True
+    >>> is_re_compilable(1)
+    False
+    """
+    try:
+        re.compile(obj)
+    except TypeError:
+        return False
+    else:
+        return True
+
+
+def is_array_like(obj) -> bool:
+    """
+    Check if the object is array-like.
+
+    For an object to be considered array-like, it must be list-like and
+    have a `dtype` attribute.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    is_array_like : bool
+        Whether `obj` has array-like properties.
+
+    Examples
+    --------
+    >>> is_array_like(np.array([1, 2, 3]))
+    True
+    >>> is_array_like(pd.Series(["a", "b"]))
+    True
+    >>> is_array_like(pd.Index(["2016-01-01"]))
+    True
+    >>> is_array_like([1, 2, 3])
+    False
+    >>> is_array_like(("a", "b"))
+    False
+    """
+    return is_list_like(obj) and hasattr(obj, "dtype")
+
+
+def is_nested_list_like(obj) -> bool:
+    """
+    Check if the object is list-like, and that all of its elements
+    are also list-like.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    is_list_like : bool
+        Whether `obj` has list-like properties.
+
+    Examples
+    --------
+    >>> is_nested_list_like([[1, 2, 3]])
+    True
+    >>> is_nested_list_like([{1, 2, 3}, {1, 2, 3}])
+    True
+    >>> is_nested_list_like(["foo"])
+    False
+    >>> is_nested_list_like([])
+    False
+    >>> is_nested_list_like([[1, 2, 3], 1])
+    False
+
+    Notes
+    -----
+    This won't reliably detect whether a consumable iterator (e. g.
+    a generator) is a nested-list-like without consuming the iterator.
+    To avoid consuming it, we always return False if the outer container
+    doesn't define `__len__`.
+
+    See Also
+    --------
+    is_list_like
+    """
+    return (
+        is_list_like(obj)
+        and hasattr(obj, "__len__")
+        and len(obj) > 0
+        and all(is_list_like(item) for item in obj)
+    )
+
+
+def is_dict_like(obj) -> bool:
+    """
+    Check if the object is dict-like.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    bool
+        Whether `obj` has dict-like properties.
+
+    Examples
+    --------
+    >>> from pandas.api.types import is_dict_like
+    >>> is_dict_like({1: 2})
+    True
+    >>> is_dict_like([1, 2, 3])
+    False
+    >>> is_dict_like(dict)
+    False
+    >>> is_dict_like(dict())
+    True
+    """
+    dict_like_attrs = ("__getitem__", "keys", "__contains__")
+    return (
+        all(hasattr(obj, attr) for attr in dict_like_attrs)
+        # [GH 25196] exclude classes
+        and not isinstance(obj, type)
+    )
+
+
+def is_named_tuple(obj) -> bool:
+    """
+    Check if the object is a named tuple.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    bool
+        Whether `obj` is a named tuple.
+
+    Examples
+    --------
+    >>> from collections import namedtuple
+    >>> from pandas.api.types import is_named_tuple
+    >>> Point = namedtuple("Point", ["x", "y"])
+    >>> p = Point(1, 2)
+    >>>
+    >>> is_named_tuple(p)
+    True
+    >>> is_named_tuple((1, 2))
+    False
+    """
+    return isinstance(obj, abc.Sequence) and hasattr(obj, "_fields")
+
+
+def is_hashable(obj) -> TypeGuard[Hashable]:
+    """
+    Return True if hash(obj) will succeed, False otherwise.
+
+    Some types will pass a test against collections.abc.Hashable but fail when
+    they are actually hashed with hash().
+
+    Distinguish between these and other types by trying the call to hash() and
+    seeing if they raise TypeError.
+
+    Returns
+    -------
+    bool
+
+    Examples
+    --------
+    >>> import collections
+    >>> from pandas.api.types import is_hashable
+    >>> a = ([],)
+    >>> isinstance(a, collections.abc.Hashable)
+    True
+    >>> is_hashable(a)
+    False
+    """
+    # Unfortunately, we can't use isinstance(obj, collections.abc.Hashable),
+    # which can be faster than calling hash. That is because numpy scalars
+    # fail this test.
+
+    # Reconsider this decision once this numpy bug is fixed:
+    # https://github.com/numpy/numpy/issues/5562
+
+    try:
+        hash(obj)
+    except TypeError:
+        return False
+    else:
+        return True
+
+
+def is_sequence(obj) -> bool:
+    """
+    Check if the object is a sequence of objects.
+    String types are not included as sequences here.
+
+    Parameters
+    ----------
+    obj : The object to check
+
+    Returns
+    -------
+    is_sequence : bool
+        Whether `obj` is a sequence of objects.
+
+    Examples
+    --------
+    >>> l = [1, 2, 3]
+    >>>
+    >>> is_sequence(l)
+    True
+    >>> is_sequence(iter(l))
+    False
+    """
+    try:
+        iter(obj)  # Can iterate over it.
+        len(obj)  # Has a length associated with it.
+        return not isinstance(obj, (str, bytes))
+    except (TypeError, AttributeError):
+        return False
+
+
+def is_dataclass(item) -> bool:
+    """
+    Checks if the object is a data-class instance
+
+    Parameters
+    ----------
+    item : object
+
+    Returns
+    --------
+    is_dataclass : bool
+        True if the item is an instance of a data-class,
+        will return false if you pass the data class itself
+
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> @dataclass
+    ... class Point:
+    ...     x: int
+    ...     y: int
+
+    >>> is_dataclass(Point)
+    False
+    >>> is_dataclass(Point(0,2))
+    True
+
+    """
+    try:
+        import dataclasses
+
+        return dataclasses.is_dataclass(item) and not isinstance(item, type)
+    except ImportError:
+        return False
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/dtypes/missing.py b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/missing.py
new file mode 100644
index 0000000000000000000000000000000000000000..c341ff9dff7e613d8db2209efb5c10f170a9cd47
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/dtypes/missing.py
@@ -0,0 +1,810 @@
+"""
+missing types & inference
+"""
+from __future__ import annotations
+
+from decimal import Decimal
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs import lib
+import pandas._libs.missing as libmissing
+from pandas._libs.tslibs import (
+    NaT,
+    iNaT,
+)
+
+from pandas.core.dtypes.common import (
+    DT64NS_DTYPE,
+    TD64NS_DTYPE,
+    ensure_object,
+    is_scalar,
+    is_string_or_object_np_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    IntervalDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCExtensionArray,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import is_list_like
+
+if TYPE_CHECKING:
+    from re import Pattern
+
+    from pandas._typing import (
+        ArrayLike,
+        DtypeObj,
+        NDFrame,
+        NDFrameT,
+        Scalar,
+        npt,
+    )
+
+    from pandas import Series
+    from pandas.core.indexes.base import Index
+
+
+isposinf_scalar = libmissing.isposinf_scalar
+isneginf_scalar = libmissing.isneginf_scalar
+
+nan_checker = np.isnan
+INF_AS_NA = False
+_dtype_object = np.dtype("object")
+_dtype_str = np.dtype(str)
+
+
+@overload
+def isna(obj: Scalar | Pattern) -> bool:
+    ...
+
+
+@overload
+def isna(
+    obj: ArrayLike | Index | list,
+) -> npt.NDArray[np.bool_]:
+    ...
+
+
+@overload
+def isna(obj: NDFrameT) -> NDFrameT:
+    ...
+
+
+# handle unions
+@overload
+def isna(obj: NDFrameT | ArrayLike | Index | list) -> NDFrameT | npt.NDArray[np.bool_]:
+    ...
+
+
+@overload
+def isna(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
+    ...
+
+
+def isna(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
+    """
+    Detect missing values for an array-like object.
+
+    This function takes a scalar or array-like object and indicates
+    whether values are missing (``NaN`` in numeric arrays, ``None`` or ``NaN``
+    in object arrays, ``NaT`` in datetimelike).
+
+    Parameters
+    ----------
+    obj : scalar or array-like
+        Object to check for null or missing values.
+
+    Returns
+    -------
+    bool or array-like of bool
+        For scalar input, returns a scalar boolean.
+        For array input, returns an array of boolean indicating whether each
+        corresponding element is missing.
+
+    See Also
+    --------
+    notna : Boolean inverse of pandas.isna.
+    Series.isna : Detect missing values in a Series.
+    DataFrame.isna : Detect missing values in a DataFrame.
+    Index.isna : Detect missing values in an Index.
+
+    Examples
+    --------
+    Scalar arguments (including strings) result in a scalar boolean.
+
+    >>> pd.isna('dog')
+    False
+
+    >>> pd.isna(pd.NA)
+    True
+
+    >>> pd.isna(np.nan)
+    True
+
+    ndarrays result in an ndarray of booleans.
+
+    >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
+    >>> array
+    array([[ 1., nan,  3.],
+           [ 4.,  5., nan]])
+    >>> pd.isna(array)
+    array([[False,  True, False],
+           [False, False,  True]])
+
+    For indexes, an ndarray of booleans is returned.
+
+    >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
+    ...                           "2017-07-08"])
+    >>> index
+    DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
+                  dtype='datetime64[ns]', freq=None)
+    >>> pd.isna(index)
+    array([False, False,  True, False])
+
+    For Series and DataFrame, the same type is returned, containing booleans.
+
+    >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
+    >>> df
+         0     1    2
+    0  ant   bee  cat
+    1  dog  None  fly
+    >>> pd.isna(df)
+           0      1      2
+    0  False  False  False
+    1  False   True  False
+
+    >>> pd.isna(df[1])
+    0    False
+    1     True
+    Name: 1, dtype: bool
+    """
+    return _isna(obj)
+
+
+isnull = isna
+
+
+def _isna(obj, inf_as_na: bool = False):
+    """
+    Detect missing values, treating None, NaN or NA as null. Infinite
+    values will also be treated as null if inf_as_na is True.
+
+    Parameters
+    ----------
+    obj: ndarray or object value
+        Input array or scalar value.
+    inf_as_na: bool
+        Whether to treat infinity as null.
+
+    Returns
+    -------
+    boolean ndarray or boolean
+    """
+    if is_scalar(obj):
+        return libmissing.checknull(obj, inf_as_na=inf_as_na)
+    elif isinstance(obj, ABCMultiIndex):
+        raise NotImplementedError("isna is not defined for MultiIndex")
+    elif isinstance(obj, type):
+        return False
+    elif isinstance(obj, (np.ndarray, ABCExtensionArray)):
+        return _isna_array(obj, inf_as_na=inf_as_na)
+    elif isinstance(obj, ABCIndex):
+        # Try to use cached isna, which also short-circuits for integer dtypes
+        #  and avoids materializing RangeIndex._values
+        if not obj._can_hold_na:
+            return obj.isna()
+        return _isna_array(obj._values, inf_as_na=inf_as_na)
+
+    elif isinstance(obj, ABCSeries):
+        result = _isna_array(obj._values, inf_as_na=inf_as_na)
+        # box
+        result = obj._constructor(result, index=obj.index, name=obj.name, copy=False)
+        return result
+    elif isinstance(obj, ABCDataFrame):
+        return obj.isna()
+    elif isinstance(obj, list):
+        return _isna_array(np.asarray(obj, dtype=object), inf_as_na=inf_as_na)
+    elif hasattr(obj, "__array__"):
+        return _isna_array(np.asarray(obj), inf_as_na=inf_as_na)
+    else:
+        return False
+
+
+def _use_inf_as_na(key) -> None:
+    """
+    Option change callback for na/inf behaviour.
+
+    Choose which replacement for numpy.isnan / -numpy.isfinite is used.
+
+    Parameters
+    ----------
+    flag: bool
+        True means treat None, NaN, INF, -INF as null (old way),
+        False means None and NaN are null, but INF, -INF are not null
+        (new way).
+
+    Notes
+    -----
+    This approach to setting global module values is discussed and
+    approved here:
+
+    * https://stackoverflow.com/questions/4859217/
+      programmatically-creating-variables-in-python/4859312#4859312
+    """
+    inf_as_na = get_option(key)
+    globals()["_isna"] = partial(_isna, inf_as_na=inf_as_na)
+    if inf_as_na:
+        globals()["nan_checker"] = lambda x: ~np.isfinite(x)
+        globals()["INF_AS_NA"] = True
+    else:
+        globals()["nan_checker"] = np.isnan
+        globals()["INF_AS_NA"] = False
+
+
+def _isna_array(values: ArrayLike, inf_as_na: bool = False):
+    """
+    Return an array indicating which values of the input array are NaN / NA.
+
+    Parameters
+    ----------
+    obj: ndarray or ExtensionArray
+        The input array whose elements are to be checked.
+    inf_as_na: bool
+        Whether or not to treat infinite values as NA.
+
+    Returns
+    -------
+    array-like
+        Array of boolean values denoting the NA status of each element.
+    """
+    dtype = values.dtype
+
+    if not isinstance(values, np.ndarray):
+        # i.e. ExtensionArray
+        if inf_as_na and isinstance(dtype, CategoricalDtype):
+            result = libmissing.isnaobj(values.to_numpy(), inf_as_na=inf_as_na)
+        else:
+            # error: Incompatible types in assignment (expression has type
+            # "Union[ndarray[Any, Any], ExtensionArraySupportsAnyAll]", variable has
+            # type "ndarray[Any, dtype[bool_]]")
+            result = values.isna()  # type: ignore[assignment]
+    elif isinstance(values, np.rec.recarray):
+        # GH 48526
+        result = _isna_recarray_dtype(values, inf_as_na=inf_as_na)
+    elif is_string_or_object_np_dtype(values.dtype):
+        result = _isna_string_dtype(values, inf_as_na=inf_as_na)
+    elif dtype.kind in "mM":
+        # this is the NaT pattern
+        result = values.view("i8") == iNaT
+    else:
+        if inf_as_na:
+            result = ~np.isfinite(values)
+        else:
+            result = np.isnan(values)
+
+    return result
+
+
+def _isna_string_dtype(values: np.ndarray, inf_as_na: bool) -> npt.NDArray[np.bool_]:
+    # Working around NumPy ticket 1542
+    dtype = values.dtype
+
+    if dtype.kind in ("S", "U"):
+        result = np.zeros(values.shape, dtype=bool)
+    else:
+        if values.ndim in {1, 2}:
+            result = libmissing.isnaobj(values, inf_as_na=inf_as_na)
+        else:
+            # 0-D, reached via e.g. mask_missing
+            result = libmissing.isnaobj(values.ravel(), inf_as_na=inf_as_na)
+            result = result.reshape(values.shape)
+
+    return result
+
+
+def _has_record_inf_value(record_as_array: np.ndarray) -> np.bool_:
+    is_inf_in_record = np.zeros(len(record_as_array), dtype=bool)
+    for i, value in enumerate(record_as_array):
+        is_element_inf = False
+        try:
+            is_element_inf = np.isinf(value)
+        except TypeError:
+            is_element_inf = False
+        is_inf_in_record[i] = is_element_inf
+
+    return np.any(is_inf_in_record)
+
+
+def _isna_recarray_dtype(
+    values: np.rec.recarray, inf_as_na: bool
+) -> npt.NDArray[np.bool_]:
+    result = np.zeros(values.shape, dtype=bool)
+    for i, record in enumerate(values):
+        record_as_array = np.array(record.tolist())
+        does_record_contain_nan = isna_all(record_as_array)
+        does_record_contain_inf = False
+        if inf_as_na:
+            does_record_contain_inf = bool(_has_record_inf_value(record_as_array))
+        result[i] = np.any(
+            np.logical_or(does_record_contain_nan, does_record_contain_inf)
+        )
+
+    return result
+
+
+@overload
+def notna(obj: Scalar) -> bool:
+    ...
+
+
+@overload
+def notna(
+    obj: ArrayLike | Index | list,
+) -> npt.NDArray[np.bool_]:
+    ...
+
+
+@overload
+def notna(obj: NDFrameT) -> NDFrameT:
+    ...
+
+
+# handle unions
+@overload
+def notna(obj: NDFrameT | ArrayLike | Index | list) -> NDFrameT | npt.NDArray[np.bool_]:
+    ...
+
+
+@overload
+def notna(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
+    ...
+
+
+def notna(obj: object) -> bool | npt.NDArray[np.bool_] | NDFrame:
+    """
+    Detect non-missing values for an array-like object.
+
+    This function takes a scalar or array-like object and indicates
+    whether values are valid (not missing, which is ``NaN`` in numeric
+    arrays, ``None`` or ``NaN`` in object arrays, ``NaT`` in datetimelike).
+
+    Parameters
+    ----------
+    obj : array-like or object value
+        Object to check for *not* null or *non*-missing values.
+
+    Returns
+    -------
+    bool or array-like of bool
+        For scalar input, returns a scalar boolean.
+        For array input, returns an array of boolean indicating whether each
+        corresponding element is valid.
+
+    See Also
+    --------
+    isna : Boolean inverse of pandas.notna.
+    Series.notna : Detect valid values in a Series.
+    DataFrame.notna : Detect valid values in a DataFrame.
+    Index.notna : Detect valid values in an Index.
+
+    Examples
+    --------
+    Scalar arguments (including strings) result in a scalar boolean.
+
+    >>> pd.notna('dog')
+    True
+
+    >>> pd.notna(pd.NA)
+    False
+
+    >>> pd.notna(np.nan)
+    False
+
+    ndarrays result in an ndarray of booleans.
+
+    >>> array = np.array([[1, np.nan, 3], [4, 5, np.nan]])
+    >>> array
+    array([[ 1., nan,  3.],
+           [ 4.,  5., nan]])
+    >>> pd.notna(array)
+    array([[ True, False,  True],
+           [ True,  True, False]])
+
+    For indexes, an ndarray of booleans is returned.
+
+    >>> index = pd.DatetimeIndex(["2017-07-05", "2017-07-06", None,
+    ...                          "2017-07-08"])
+    >>> index
+    DatetimeIndex(['2017-07-05', '2017-07-06', 'NaT', '2017-07-08'],
+                  dtype='datetime64[ns]', freq=None)
+    >>> pd.notna(index)
+    array([ True,  True, False,  True])
+
+    For Series and DataFrame, the same type is returned, containing booleans.
+
+    >>> df = pd.DataFrame([['ant', 'bee', 'cat'], ['dog', None, 'fly']])
+    >>> df
+         0     1    2
+    0  ant   bee  cat
+    1  dog  None  fly
+    >>> pd.notna(df)
+          0      1     2
+    0  True   True  True
+    1  True  False  True
+
+    >>> pd.notna(df[1])
+    0     True
+    1    False
+    Name: 1, dtype: bool
+    """
+    res = isna(obj)
+    if isinstance(res, bool):
+        return not res
+    return ~res
+
+
+notnull = notna
+
+
+def array_equivalent(
+    left,
+    right,
+    strict_nan: bool = False,
+    dtype_equal: bool = False,
+) -> bool:
+    """
+    True if two arrays, left and right, have equal non-NaN elements, and NaNs
+    in corresponding locations.  False otherwise. It is assumed that left and
+    right are NumPy arrays of the same dtype. The behavior of this function
+    (particularly with respect to NaNs) is not defined if the dtypes are
+    different.
+
+    Parameters
+    ----------
+    left, right : ndarrays
+    strict_nan : bool, default False
+        If True, consider NaN and None to be different.
+    dtype_equal : bool, default False
+        Whether `left` and `right` are known to have the same dtype
+        according to `is_dtype_equal`. Some methods like `BlockManager.equals`.
+        require that the dtypes match. Setting this to ``True`` can improve
+        performance, but will give different results for arrays that are
+        equal but different dtypes.
+
+    Returns
+    -------
+    b : bool
+        Returns True if the arrays are equivalent.
+
+    Examples
+    --------
+    >>> array_equivalent(
+    ...     np.array([1, 2, np.nan]),
+    ...     np.array([1, 2, np.nan]))
+    True
+    >>> array_equivalent(
+    ...     np.array([1, np.nan, 2]),
+    ...     np.array([1, 2, np.nan]))
+    False
+    """
+    left, right = np.asarray(left), np.asarray(right)
+
+    # shape compat
+    if left.shape != right.shape:
+        return False
+
+    if dtype_equal:
+        # fastpath when we require that the dtypes match (Block.equals)
+        if left.dtype.kind in "fc":
+            return _array_equivalent_float(left, right)
+        elif left.dtype.kind in "mM":
+            return _array_equivalent_datetimelike(left, right)
+        elif is_string_or_object_np_dtype(left.dtype):
+            # TODO: fastpath for pandas' StringDtype
+            return _array_equivalent_object(left, right, strict_nan)
+        else:
+            return np.array_equal(left, right)
+
+    # Slow path when we allow comparing different dtypes.
+    # Object arrays can contain None, NaN and NaT.
+    # string dtypes must be come to this path for NumPy 1.7.1 compat
+    if left.dtype.kind in "OSU" or right.dtype.kind in "OSU":
+        # Note: `in "OSU"` is non-trivially faster than `in ["O", "S", "U"]`
+        #  or `in ("O", "S", "U")`
+        return _array_equivalent_object(left, right, strict_nan)
+
+    # NaNs can occur in float and complex arrays.
+    if left.dtype.kind in "fc":
+        if not (left.size and right.size):
+            return True
+        return ((left == right) | (isna(left) & isna(right))).all()
+
+    elif left.dtype.kind in "mM" or right.dtype.kind in "mM":
+        # datetime64, timedelta64, Period
+        if left.dtype != right.dtype:
+            return False
+
+        left = left.view("i8")
+        right = right.view("i8")
+
+    # if we have structured dtypes, compare first
+    if (
+        left.dtype.type is np.void or right.dtype.type is np.void
+    ) and left.dtype != right.dtype:
+        return False
+
+    return np.array_equal(left, right)
+
+
+def _array_equivalent_float(left: np.ndarray, right: np.ndarray) -> bool:
+    return bool(((left == right) | (np.isnan(left) & np.isnan(right))).all())
+
+
+def _array_equivalent_datetimelike(left: np.ndarray, right: np.ndarray):
+    return np.array_equal(left.view("i8"), right.view("i8"))
+
+
+def _array_equivalent_object(left: np.ndarray, right: np.ndarray, strict_nan: bool):
+    left = ensure_object(left)
+    right = ensure_object(right)
+
+    mask: npt.NDArray[np.bool_] | None = None
+    if strict_nan:
+        mask = isna(left) & isna(right)
+        if not mask.any():
+            mask = None
+
+    try:
+        if mask is None:
+            return lib.array_equivalent_object(left, right)
+        if not lib.array_equivalent_object(left[~mask], right[~mask]):
+            return False
+        left_remaining = left[mask]
+        right_remaining = right[mask]
+    except ValueError:
+        # can raise a ValueError if left and right cannot be
+        # compared (e.g. nested arrays)
+        left_remaining = left
+        right_remaining = right
+
+    for left_value, right_value in zip(left_remaining, right_remaining):
+        if left_value is NaT and right_value is not NaT:
+            return False
+
+        elif left_value is libmissing.NA and right_value is not libmissing.NA:
+            return False
+
+        elif isinstance(left_value, float) and np.isnan(left_value):
+            if not isinstance(right_value, float) or not np.isnan(right_value):
+                return False
+        else:
+            with warnings.catch_warnings():
+                # suppress numpy's "elementwise comparison failed"
+                warnings.simplefilter("ignore", DeprecationWarning)
+                try:
+                    if np.any(np.asarray(left_value != right_value)):
+                        return False
+                except TypeError as err:
+                    if "boolean value of NA is ambiguous" in str(err):
+                        return False
+                    raise
+                except ValueError:
+                    # numpy can raise a ValueError if left and right cannot be
+                    # compared (e.g. nested arrays)
+                    return False
+    return True
+
+
+def array_equals(left: ArrayLike, right: ArrayLike) -> bool:
+    """
+    ExtensionArray-compatible implementation of array_equivalent.
+    """
+    if left.dtype != right.dtype:
+        return False
+    elif isinstance(left, ABCExtensionArray):
+        return left.equals(right)
+    else:
+        return array_equivalent(left, right, dtype_equal=True)
+
+
+def infer_fill_value(val):
+    """
+    infer the fill value for the nan/NaT from the provided
+    scalar/ndarray/list-like if we are a NaT, return the correct dtyped
+    element to provide proper block construction
+    """
+    if not is_list_like(val):
+        val = [val]
+    val = np.asarray(val)
+    if val.dtype.kind in "mM":
+        return np.array("NaT", dtype=val.dtype)
+    elif val.dtype == object:
+        dtype = lib.infer_dtype(ensure_object(val), skipna=False)
+        if dtype in ["datetime", "datetime64"]:
+            return np.array("NaT", dtype=DT64NS_DTYPE)
+        elif dtype in ["timedelta", "timedelta64"]:
+            return np.array("NaT", dtype=TD64NS_DTYPE)
+        return np.array(np.nan, dtype=object)
+    elif val.dtype.kind == "U":
+        return np.array(np.nan, dtype=val.dtype)
+    return np.nan
+
+
+def construct_1d_array_from_inferred_fill_value(
+    value: object, length: int
+) -> ArrayLike:
+    # Find our empty_value dtype by constructing an array
+    #  from our value and doing a .take on it
+    from pandas.core.algorithms import take_nd
+    from pandas.core.construction import sanitize_array
+    from pandas.core.indexes.base import Index
+
+    arr = sanitize_array(value, Index(range(1)), copy=False)
+    taker = -1 * np.ones(length, dtype=np.intp)
+    return take_nd(arr, taker)
+
+
+def maybe_fill(arr: np.ndarray) -> np.ndarray:
+    """
+    Fill numpy.ndarray with NaN, unless we have a integer or boolean dtype.
+    """
+    if arr.dtype.kind not in "iub":
+        arr.fill(np.nan)
+    return arr
+
+
+def na_value_for_dtype(dtype: DtypeObj, compat: bool = True):
+    """
+    Return a dtype compat na value
+
+    Parameters
+    ----------
+    dtype : string / dtype
+    compat : bool, default True
+
+    Returns
+    -------
+    np.dtype or a pandas dtype
+
+    Examples
+    --------
+    >>> na_value_for_dtype(np.dtype('int64'))
+    0
+    >>> na_value_for_dtype(np.dtype('int64'), compat=False)
+    nan
+    >>> na_value_for_dtype(np.dtype('float64'))
+    nan
+    >>> na_value_for_dtype(np.dtype('bool'))
+    False
+    >>> na_value_for_dtype(np.dtype('datetime64[ns]'))
+    numpy.datetime64('NaT')
+    """
+
+    if isinstance(dtype, ExtensionDtype):
+        return dtype.na_value
+    elif dtype.kind in "mM":
+        unit = np.datetime_data(dtype)[0]
+        return dtype.type("NaT", unit)
+    elif dtype.kind == "f":
+        return np.nan
+    elif dtype.kind in "iu":
+        if compat:
+            return 0
+        return np.nan
+    elif dtype.kind == "b":
+        if compat:
+            return False
+        return np.nan
+    return np.nan
+
+
+def remove_na_arraylike(arr: Series | Index | np.ndarray):
+    """
+    Return array-like containing only true/non-NaN values, possibly empty.
+    """
+    if isinstance(arr.dtype, ExtensionDtype):
+        return arr[notna(arr)]
+    else:
+        return arr[notna(np.asarray(arr))]
+
+
+def is_valid_na_for_dtype(obj, dtype: DtypeObj) -> bool:
+    """
+    isna check that excludes incompatible dtypes
+
+    Parameters
+    ----------
+    obj : object
+    dtype : np.datetime64, np.timedelta64, DatetimeTZDtype, or PeriodDtype
+
+    Returns
+    -------
+    bool
+    """
+    if not lib.is_scalar(obj) or not isna(obj):
+        return False
+    elif dtype.kind == "M":
+        if isinstance(dtype, np.dtype):
+            # i.e. not tzaware
+            return not isinstance(obj, (np.timedelta64, Decimal))
+        # we have to rule out tznaive dt64("NaT")
+        return not isinstance(obj, (np.timedelta64, np.datetime64, Decimal))
+    elif dtype.kind == "m":
+        return not isinstance(obj, (np.datetime64, Decimal))
+    elif dtype.kind in "iufc":
+        # Numeric
+        return obj is not NaT and not isinstance(obj, (np.datetime64, np.timedelta64))
+    elif dtype.kind == "b":
+        # We allow pd.NA, None, np.nan in BooleanArray (same as IntervalDtype)
+        return lib.is_float(obj) or obj is None or obj is libmissing.NA
+
+    elif dtype == _dtype_str:
+        # numpy string dtypes to avoid float np.nan
+        return not isinstance(obj, (np.datetime64, np.timedelta64, Decimal, float))
+
+    elif dtype == _dtype_object:
+        # This is needed for Categorical, but is kind of weird
+        return True
+
+    elif isinstance(dtype, PeriodDtype):
+        return not isinstance(obj, (np.datetime64, np.timedelta64, Decimal))
+
+    elif isinstance(dtype, IntervalDtype):
+        return lib.is_float(obj) or obj is None or obj is libmissing.NA
+
+    elif isinstance(dtype, CategoricalDtype):
+        return is_valid_na_for_dtype(obj, dtype.categories.dtype)
+
+    # fallback, default to allowing NaN, None, NA, NaT
+    return not isinstance(obj, (np.datetime64, np.timedelta64, Decimal))
+
+
+def isna_all(arr: ArrayLike) -> bool:
+    """
+    Optimized equivalent to isna(arr).all()
+    """
+    total_len = len(arr)
+
+    # Usually it's enough to check but a small fraction of values to see if
+    #  a block is NOT null, chunks should help in such cases.
+    #  parameters 1000 and 40 were chosen arbitrarily
+    chunk_len = max(total_len // 40, 1000)
+
+    dtype = arr.dtype
+    if lib.is_np_dtype(dtype, "f"):
+        checker = nan_checker
+
+    elif (lib.is_np_dtype(dtype, "mM")) or isinstance(
+        dtype, (DatetimeTZDtype, PeriodDtype)
+    ):
+        # error: Incompatible types in assignment (expression has type
+        # "Callable[[Any], Any]", variable has type "ufunc")
+        checker = lambda x: np.asarray(x.view("i8")) == iNaT  # type: ignore[assignment]
+
+    else:
+        # error: Incompatible types in assignment (expression has type "Callable[[Any],
+        # Any]", variable has type "ufunc")
+        checker = lambda x: _isna_array(  # type: ignore[assignment]
+            x, inf_as_na=INF_AS_NA
+        )
+
+    return all(
+        checker(arr[i : i + chunk_len]).all() for i in range(0, total_len, chunk_len)
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/flags.py b/.venv/lib/python3.13/site-packages/pandas/core/flags.py
new file mode 100644
index 0000000000000000000000000000000000000000..aff7a15f283bafe1459173070e64df4caef0d45d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/flags.py
@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+import weakref
+
+if TYPE_CHECKING:
+    from pandas.core.generic import NDFrame
+
+
+class Flags:
+    """
+    Flags that apply to pandas objects.
+
+    Parameters
+    ----------
+    obj : Series or DataFrame
+        The object these flags are associated with.
+    allows_duplicate_labels : bool, default True
+        Whether to allow duplicate labels in this object. By default,
+        duplicate labels are permitted. Setting this to ``False`` will
+        cause an :class:`errors.DuplicateLabelError` to be raised when
+        `index` (or columns for DataFrame) is not unique, or any
+        subsequent operation on introduces duplicates.
+        See :ref:`duplicates.disallow` for more.
+
+        .. warning::
+
+           This is an experimental feature. Currently, many methods fail to
+           propagate the ``allows_duplicate_labels`` value. In future versions
+           it is expected that every method taking or returning one or more
+           DataFrame or Series objects will propagate ``allows_duplicate_labels``.
+
+    Examples
+    --------
+    Attributes can be set in two ways:
+
+    >>> df = pd.DataFrame()
+    >>> df.flags
+    
+    >>> df.flags.allows_duplicate_labels = False
+    >>> df.flags
+    
+
+    >>> df.flags['allows_duplicate_labels'] = True
+    >>> df.flags
+    
+    """
+
+    _keys: set[str] = {"allows_duplicate_labels"}
+
+    def __init__(self, obj: NDFrame, *, allows_duplicate_labels: bool) -> None:
+        self._allows_duplicate_labels = allows_duplicate_labels
+        self._obj = weakref.ref(obj)
+
+    @property
+    def allows_duplicate_labels(self) -> bool:
+        """
+        Whether this object allows duplicate labels.
+
+        Setting ``allows_duplicate_labels=False`` ensures that the
+        index (and columns of a DataFrame) are unique. Most methods
+        that accept and return a Series or DataFrame will propagate
+        the value of ``allows_duplicate_labels``.
+
+        See :ref:`duplicates` for more.
+
+        See Also
+        --------
+        DataFrame.attrs : Set global metadata on this object.
+        DataFrame.set_flags : Set global flags on this object.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": [1, 2]}, index=['a', 'a'])
+        >>> df.flags.allows_duplicate_labels
+        True
+        >>> df.flags.allows_duplicate_labels = False
+        Traceback (most recent call last):
+            ...
+        pandas.errors.DuplicateLabelError: Index has duplicates.
+              positions
+        label
+        a        [0, 1]
+        """
+        return self._allows_duplicate_labels
+
+    @allows_duplicate_labels.setter
+    def allows_duplicate_labels(self, value: bool) -> None:
+        value = bool(value)
+        obj = self._obj()
+        if obj is None:
+            raise ValueError("This flag's object has been deleted.")
+
+        if not value:
+            for ax in obj.axes:
+                ax._maybe_check_unique()
+
+        self._allows_duplicate_labels = value
+
+    def __getitem__(self, key: str):
+        if key not in self._keys:
+            raise KeyError(key)
+
+        return getattr(self, key)
+
+    def __setitem__(self, key: str, value) -> None:
+        if key not in self._keys:
+            raise ValueError(f"Unknown flag {key}. Must be one of {self._keys}")
+        setattr(self, key, value)
+
+    def __repr__(self) -> str:
+        return f""
+
+    def __eq__(self, other) -> bool:
+        if isinstance(other, type(self)):
+            return self.allows_duplicate_labels == other.allows_duplicate_labels
+        return False
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/frame.py b/.venv/lib/python3.13/site-packages/pandas/core/frame.py
new file mode 100644
index 0000000000000000000000000000000000000000..cc260770cbd78ffc0bf46d7d004cde56409df300
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/frame.py
@@ -0,0 +1,12724 @@
+"""
+DataFrame
+---------
+An efficient 2D container for potentially mixed-type time series or other
+labeled data series.
+
+Similar to its R counterpart, data.frame, except providing automatic data
+alignment and a host of useful data manipulation methods having to do with the
+labeling information
+"""
+from __future__ import annotations
+
+import collections
+from collections import abc
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Iterator,
+    Mapping,
+    Sequence,
+)
+import functools
+from inspect import signature
+from io import StringIO
+import itertools
+import operator
+import sys
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+from numpy import ma
+
+from pandas._config import (
+    get_option,
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+from pandas._config.config import _get_option
+
+from pandas._libs import (
+    algos as libalgos,
+    lib,
+    properties,
+)
+from pandas._libs.hashtable import duplicated
+from pandas._libs.lib import is_range_indexer
+from pandas.compat import PYPY
+from pandas.compat._constants import (
+    REF_COUNT,
+    WARNING_CHECK_DISABLED,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    ChainedAssignmentError,
+    InvalidIndexError,
+    _chained_assignment_method_msg,
+    _chained_assignment_msg,
+    _chained_assignment_warning_method_msg,
+    _chained_assignment_warning_msg,
+)
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    deprecate_nonkeyword_arguments,
+    doc,
+)
+from pandas.util._exceptions import (
+    find_stack_level,
+    rewrite_warning,
+)
+from pandas.util._validators import (
+    validate_ascending,
+    validate_bool_kwarg,
+    validate_percentile,
+)
+
+from pandas.core.dtypes.cast import (
+    LossySetitemError,
+    can_hold_element,
+    construct_1d_arraylike_from_scalar,
+    construct_2d_arraylike_from_scalar,
+    find_common_type,
+    infer_dtype_from_scalar,
+    invalidate_string_dtypes,
+    maybe_box_native,
+    maybe_downcast_to_dtype,
+)
+from pandas.core.dtypes.common import (
+    infer_dtype_from_object,
+    is_1d_only_ea_dtype,
+    is_array_like,
+    is_bool_dtype,
+    is_dataclass,
+    is_dict_like,
+    is_float,
+    is_float_dtype,
+    is_hashable,
+    is_integer,
+    is_integer_dtype,
+    is_iterator,
+    is_list_like,
+    is_scalar,
+    is_sequence,
+    needs_i8_conversion,
+    pandas_dtype,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    BaseMaskedDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    notna,
+)
+
+from pandas.core import (
+    algorithms,
+    common as com,
+    nanops,
+    ops,
+    roperator,
+)
+from pandas.core.accessor import CachedAccessor
+from pandas.core.apply import reconstruct_and_relabel_result
+from pandas.core.array_algos.take import take_2d_multi
+from pandas.core.arraylike import OpsMixin
+from pandas.core.arrays import (
+    BaseMaskedArray,
+    DatetimeArray,
+    ExtensionArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.sparse import SparseFrameAccessor
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    sanitize_array,
+    sanitize_masked_array,
+)
+from pandas.core.generic import (
+    NDFrame,
+    make_doc,
+)
+from pandas.core.indexers import check_key_length
+from pandas.core.indexes.api import (
+    DatetimeIndex,
+    Index,
+    PeriodIndex,
+    default_index,
+    ensure_index,
+    ensure_index_from_sequences,
+)
+from pandas.core.indexes.multi import (
+    MultiIndex,
+    maybe_droplevels,
+)
+from pandas.core.indexing import (
+    check_bool_indexer,
+    check_dict_or_set_indexers,
+)
+from pandas.core.internals import (
+    ArrayManager,
+    BlockManager,
+)
+from pandas.core.internals.construction import (
+    arrays_to_mgr,
+    dataclasses_to_dicts,
+    dict_to_mgr,
+    mgr_to_mgr,
+    ndarray_to_mgr,
+    nested_data_to_arrays,
+    rec_array_to_mgr,
+    reorder_arrays,
+    to_arrays,
+    treat_as_nested,
+)
+from pandas.core.methods import selectn
+from pandas.core.reshape.melt import melt
+from pandas.core.series import Series
+from pandas.core.shared_docs import _shared_docs
+from pandas.core.sorting import (
+    get_group_index,
+    lexsort_indexer,
+    nargsort,
+)
+
+from pandas.io.common import get_handle
+from pandas.io.formats import (
+    console,
+    format as fmt,
+)
+from pandas.io.formats.info import (
+    INFO_DOCSTRING,
+    DataFrameInfo,
+    frame_sub_kwargs,
+)
+import pandas.plotting
+
+if TYPE_CHECKING:
+    import datetime
+
+    from pandas._libs.internals import BlockValuesRefs
+    from pandas._typing import (
+        AggFuncType,
+        AnyAll,
+        AnyArrayLike,
+        ArrayLike,
+        Axes,
+        Axis,
+        AxisInt,
+        ColspaceArgType,
+        CompressionOptions,
+        CorrelationMethod,
+        DropKeep,
+        Dtype,
+        DtypeObj,
+        FilePath,
+        FloatFormatType,
+        FormattersType,
+        Frequency,
+        FromDictOrient,
+        IgnoreRaise,
+        IndexKeyFunc,
+        IndexLabel,
+        JoinValidate,
+        Level,
+        MergeHow,
+        MergeValidate,
+        MutableMappingT,
+        NaAction,
+        NaPosition,
+        NsmallestNlargestKeep,
+        PythonFuncType,
+        QuantileInterpolation,
+        ReadBuffer,
+        ReindexMethod,
+        Renamer,
+        Scalar,
+        Self,
+        SequenceNotStr,
+        SortKind,
+        StorageOptions,
+        Suffixes,
+        ToGbqIfexist,
+        ToStataByteorder,
+        ToTimestampHow,
+        UpdateJoin,
+        ValueKeyFunc,
+        WriteBuffer,
+        XMLParsers,
+        npt,
+    )
+
+    from pandas.core.groupby.generic import DataFrameGroupBy
+    from pandas.core.interchange.dataframe_protocol import DataFrame as DataFrameXchg
+    from pandas.core.internals import SingleDataManager
+
+    from pandas.io.formats.style import Styler
+
+# ---------------------------------------------------------------------
+# Docstring templates
+
+_shared_doc_kwargs = {
+    "axes": "index, columns",
+    "klass": "DataFrame",
+    "axes_single_arg": "{0 or 'index', 1 or 'columns'}",
+    "axis": """axis : {0 or 'index', 1 or 'columns'}, default 0
+        If 0 or 'index': apply function to each column.
+        If 1 or 'columns': apply function to each row.""",
+    "inplace": """
+    inplace : bool, default False
+        Whether to modify the DataFrame rather than creating a new one.""",
+    "optional_by": """
+by : str or list of str
+    Name or list of names to sort by.
+
+    - if `axis` is 0 or `'index'` then `by` may contain index
+      levels and/or column labels.
+    - if `axis` is 1 or `'columns'` then `by` may contain column
+      levels and/or index labels.""",
+    "optional_reindex": """
+labels : array-like, optional
+    New labels / index to conform the axis specified by 'axis' to.
+index : array-like, optional
+    New labels for the index. Preferably an Index object to avoid
+    duplicating data.
+columns : array-like, optional
+    New labels for the columns. Preferably an Index object to avoid
+    duplicating data.
+axis : int or str, optional
+    Axis to target. Can be either the axis name ('index', 'columns')
+    or number (0, 1).""",
+}
+
+_merge_doc = """
+Merge DataFrame or named Series objects with a database-style join.
+
+A named Series object is treated as a DataFrame with a single named column.
+
+The join is done on columns or indexes. If joining columns on
+columns, the DataFrame indexes *will be ignored*. Otherwise if joining indexes
+on indexes or indexes on a column or columns, the index will be passed on.
+When performing a cross merge, no column specifications to merge on are
+allowed.
+
+.. warning::
+
+    If both key columns contain rows where the key is a null value, those
+    rows will be matched against each other. This is different from usual SQL
+    join behaviour and can lead to unexpected results.
+
+Parameters
+----------%s
+right : DataFrame or named Series
+    Object to merge with.
+how : {'left', 'right', 'outer', 'inner', 'cross'}, default 'inner'
+    Type of merge to be performed.
+
+    * left: use only keys from left frame, similar to a SQL left outer join;
+      preserve key order.
+    * right: use only keys from right frame, similar to a SQL right outer join;
+      preserve key order.
+    * outer: use union of keys from both frames, similar to a SQL full outer
+      join; sort keys lexicographically.
+    * inner: use intersection of keys from both frames, similar to a SQL inner
+      join; preserve the order of the left keys.
+    * cross: creates the cartesian product from both frames, preserves the order
+      of the left keys.
+on : label or list
+    Column or index level names to join on. These must be found in both
+    DataFrames. If `on` is None and not merging on indexes then this defaults
+    to the intersection of the columns in both DataFrames.
+left_on : label or list, or array-like
+    Column or index level names to join on in the left DataFrame. Can also
+    be an array or list of arrays of the length of the left DataFrame.
+    These arrays are treated as if they are columns.
+right_on : label or list, or array-like
+    Column or index level names to join on in the right DataFrame. Can also
+    be an array or list of arrays of the length of the right DataFrame.
+    These arrays are treated as if they are columns.
+left_index : bool, default False
+    Use the index from the left DataFrame as the join key(s). If it is a
+    MultiIndex, the number of keys in the other DataFrame (either the index
+    or a number of columns) must match the number of levels.
+right_index : bool, default False
+    Use the index from the right DataFrame as the join key. Same caveats as
+    left_index.
+sort : bool, default False
+    Sort the join keys lexicographically in the result DataFrame. If False,
+    the order of the join keys depends on the join type (how keyword).
+suffixes : list-like, default is ("_x", "_y")
+    A length-2 sequence where each element is optionally a string
+    indicating the suffix to add to overlapping column names in
+    `left` and `right` respectively. Pass a value of `None` instead
+    of a string to indicate that the column name from `left` or
+    `right` should be left as-is, with no suffix. At least one of the
+    values must not be None.
+copy : bool, default True
+    If False, avoid copy if possible.
+
+    .. note::
+        The `copy` keyword will change behavior in pandas 3.0.
+        `Copy-on-Write
+        `__
+        will be enabled by default, which means that all methods with a
+        `copy` keyword will use a lazy copy mechanism to defer the copy and
+        ignore the `copy` keyword. The `copy` keyword will be removed in a
+        future version of pandas.
+
+        You can already get the future behavior and improvements through
+        enabling copy on write ``pd.options.mode.copy_on_write = True``
+indicator : bool or str, default False
+    If True, adds a column to the output DataFrame called "_merge" with
+    information on the source of each row. The column can be given a different
+    name by providing a string argument. The column will have a Categorical
+    type with the value of "left_only" for observations whose merge key only
+    appears in the left DataFrame, "right_only" for observations
+    whose merge key only appears in the right DataFrame, and "both"
+    if the observation's merge key is found in both DataFrames.
+
+validate : str, optional
+    If specified, checks if merge is of specified type.
+
+    * "one_to_one" or "1:1": check if merge keys are unique in both
+      left and right datasets.
+    * "one_to_many" or "1:m": check if merge keys are unique in left
+      dataset.
+    * "many_to_one" or "m:1": check if merge keys are unique in right
+      dataset.
+    * "many_to_many" or "m:m": allowed, but does not result in checks.
+
+Returns
+-------
+DataFrame
+    A DataFrame of the two merged objects.
+
+See Also
+--------
+merge_ordered : Merge with optional filling/interpolation.
+merge_asof : Merge on nearest keys.
+DataFrame.join : Similar method using indices.
+
+Examples
+--------
+>>> df1 = pd.DataFrame({'lkey': ['foo', 'bar', 'baz', 'foo'],
+...                     'value': [1, 2, 3, 5]})
+>>> df2 = pd.DataFrame({'rkey': ['foo', 'bar', 'baz', 'foo'],
+...                     'value': [5, 6, 7, 8]})
+>>> df1
+    lkey value
+0   foo      1
+1   bar      2
+2   baz      3
+3   foo      5
+>>> df2
+    rkey value
+0   foo      5
+1   bar      6
+2   baz      7
+3   foo      8
+
+Merge df1 and df2 on the lkey and rkey columns. The value columns have
+the default suffixes, _x and _y, appended.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey')
+  lkey  value_x rkey  value_y
+0  foo        1  foo        5
+1  foo        1  foo        8
+2  bar        2  bar        6
+3  baz        3  baz        7
+4  foo        5  foo        5
+5  foo        5  foo        8
+
+Merge DataFrames df1 and df2 with specified left and right suffixes
+appended to any overlapping columns.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey',
+...           suffixes=('_left', '_right'))
+  lkey  value_left rkey  value_right
+0  foo           1  foo            5
+1  foo           1  foo            8
+2  bar           2  bar            6
+3  baz           3  baz            7
+4  foo           5  foo            5
+5  foo           5  foo            8
+
+Merge DataFrames df1 and df2, but raise an exception if the DataFrames have
+any overlapping columns.
+
+>>> df1.merge(df2, left_on='lkey', right_on='rkey', suffixes=(False, False))
+Traceback (most recent call last):
+...
+ValueError: columns overlap but no suffix specified:
+    Index(['value'], dtype='object')
+
+>>> df1 = pd.DataFrame({'a': ['foo', 'bar'], 'b': [1, 2]})
+>>> df2 = pd.DataFrame({'a': ['foo', 'baz'], 'c': [3, 4]})
+>>> df1
+      a  b
+0   foo  1
+1   bar  2
+>>> df2
+      a  c
+0   foo  3
+1   baz  4
+
+>>> df1.merge(df2, how='inner', on='a')
+      a  b  c
+0   foo  1  3
+
+>>> df1.merge(df2, how='left', on='a')
+      a  b  c
+0   foo  1  3.0
+1   bar  2  NaN
+
+>>> df1 = pd.DataFrame({'left': ['foo', 'bar']})
+>>> df2 = pd.DataFrame({'right': [7, 8]})
+>>> df1
+    left
+0   foo
+1   bar
+>>> df2
+    right
+0   7
+1   8
+
+>>> df1.merge(df2, how='cross')
+   left  right
+0   foo      7
+1   foo      8
+2   bar      7
+3   bar      8
+"""
+
+
+# -----------------------------------------------------------------------
+# DataFrame class
+
+
+class DataFrame(NDFrame, OpsMixin):
+    """
+    Two-dimensional, size-mutable, potentially heterogeneous tabular data.
+
+    Data structure also contains labeled axes (rows and columns).
+    Arithmetic operations align on both row and column labels. Can be
+    thought of as a dict-like container for Series objects. The primary
+    pandas data structure.
+
+    Parameters
+    ----------
+    data : ndarray (structured or homogeneous), Iterable, dict, or DataFrame
+        Dict can contain Series, arrays, constants, dataclass or list-like objects. If
+        data is a dict, column order follows insertion-order. If a dict contains Series
+        which have an index defined, it is aligned by its index. This alignment also
+        occurs if data is a Series or a DataFrame itself. Alignment is done on
+        Series/DataFrame inputs.
+
+        If data is a list of dicts, column order follows insertion-order.
+
+    index : Index or array-like
+        Index to use for resulting frame. Will default to RangeIndex if
+        no indexing information part of input data and no index provided.
+    columns : Index or array-like
+        Column labels to use for resulting frame when data does not have them,
+        defaulting to RangeIndex(0, 1, 2, ..., n). If data contains column labels,
+        will perform column selection instead.
+    dtype : dtype, default None
+        Data type to force. Only a single dtype is allowed. If None, infer.
+    copy : bool or None, default None
+        Copy data from inputs.
+        For dict data, the default of None behaves like ``copy=True``.  For DataFrame
+        or 2d ndarray input, the default of None behaves like ``copy=False``.
+        If data is a dict containing one or more Series (possibly of different dtypes),
+        ``copy=False`` will ensure that these inputs are not copied.
+
+        .. versionchanged:: 1.3.0
+
+    See Also
+    --------
+    DataFrame.from_records : Constructor from tuples, also record arrays.
+    DataFrame.from_dict : From dicts of Series, arrays, or dicts.
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
+    read_table : Read general delimited file into DataFrame.
+    read_clipboard : Read text from clipboard into DataFrame.
+
+    Notes
+    -----
+    Please reference the :ref:`User Guide ` for more information.
+
+    Examples
+    --------
+    Constructing DataFrame from a dictionary.
+
+    >>> d = {'col1': [1, 2], 'col2': [3, 4]}
+    >>> df = pd.DataFrame(data=d)
+    >>> df
+       col1  col2
+    0     1     3
+    1     2     4
+
+    Notice that the inferred dtype is int64.
+
+    >>> df.dtypes
+    col1    int64
+    col2    int64
+    dtype: object
+
+    To enforce a single dtype:
+
+    >>> df = pd.DataFrame(data=d, dtype=np.int8)
+    >>> df.dtypes
+    col1    int8
+    col2    int8
+    dtype: object
+
+    Constructing DataFrame from a dictionary including Series:
+
+    >>> d = {'col1': [0, 1, 2, 3], 'col2': pd.Series([2, 3], index=[2, 3])}
+    >>> pd.DataFrame(data=d, index=[0, 1, 2, 3])
+       col1  col2
+    0     0   NaN
+    1     1   NaN
+    2     2   2.0
+    3     3   3.0
+
+    Constructing DataFrame from numpy ndarray:
+
+    >>> df2 = pd.DataFrame(np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]]),
+    ...                    columns=['a', 'b', 'c'])
+    >>> df2
+       a  b  c
+    0  1  2  3
+    1  4  5  6
+    2  7  8  9
+
+    Constructing DataFrame from a numpy ndarray that has labeled columns:
+
+    >>> data = np.array([(1, 2, 3), (4, 5, 6), (7, 8, 9)],
+    ...                 dtype=[("a", "i4"), ("b", "i4"), ("c", "i4")])
+    >>> df3 = pd.DataFrame(data, columns=['c', 'a'])
+    ...
+    >>> df3
+       c  a
+    0  3  1
+    1  6  4
+    2  9  7
+
+    Constructing DataFrame from dataclass:
+
+    >>> from dataclasses import make_dataclass
+    >>> Point = make_dataclass("Point", [("x", int), ("y", int)])
+    >>> pd.DataFrame([Point(0, 0), Point(0, 3), Point(2, 3)])
+       x  y
+    0  0  0
+    1  0  3
+    2  2  3
+
+    Constructing DataFrame from Series/DataFrame:
+
+    >>> ser = pd.Series([1, 2, 3], index=["a", "b", "c"])
+    >>> df = pd.DataFrame(data=ser, index=["a", "c"])
+    >>> df
+       0
+    a  1
+    c  3
+
+    >>> df1 = pd.DataFrame([1, 2, 3], index=["a", "b", "c"], columns=["x"])
+    >>> df2 = pd.DataFrame(data=df1, index=["a", "c"])
+    >>> df2
+       x
+    a  1
+    c  3
+    """
+
+    _internal_names_set = {"columns", "index"} | NDFrame._internal_names_set
+    _typ = "dataframe"
+    _HANDLED_TYPES = (Series, Index, ExtensionArray, np.ndarray)
+    _accessors: set[str] = {"sparse"}
+    _hidden_attrs: frozenset[str] = NDFrame._hidden_attrs | frozenset([])
+    _mgr: BlockManager | ArrayManager
+
+    # similar to __array_priority__, positions DataFrame before Series, Index,
+    #  and ExtensionArray.  Should NOT be overridden by subclasses.
+    __pandas_priority__ = 4000
+
+    @property
+    def _constructor(self) -> Callable[..., DataFrame]:
+        return DataFrame
+
+    def _constructor_from_mgr(self, mgr, axes) -> DataFrame:
+        df = DataFrame._from_mgr(mgr, axes=axes)
+
+        if type(self) is DataFrame:
+            # This would also work `if self._constructor is DataFrame`, but
+            #  this check is slightly faster, benefiting the most-common case.
+            return df
+
+        elif type(self).__name__ == "GeoDataFrame":
+            # Shim until geopandas can override their _constructor_from_mgr
+            #  bc they have different behavior for Managers than for DataFrames
+            return self._constructor(mgr)
+
+        # We assume that the subclass __init__ knows how to handle a
+        #  pd.DataFrame object.
+        return self._constructor(df)
+
+    _constructor_sliced: Callable[..., Series] = Series
+
+    def _constructor_sliced_from_mgr(self, mgr, axes) -> Series:
+        ser = Series._from_mgr(mgr, axes)
+        ser._name = None  # caller is responsible for setting real name
+
+        if type(self) is DataFrame:
+            # This would also work `if self._constructor_sliced is Series`, but
+            #  this check is slightly faster, benefiting the most-common case.
+            return ser
+
+        # We assume that the subclass __init__ knows how to handle a
+        #  pd.Series object.
+        return self._constructor_sliced(ser)
+
+    # ----------------------------------------------------------------------
+    # Constructors
+
+    def __init__(
+        self,
+        data=None,
+        index: Axes | None = None,
+        columns: Axes | None = None,
+        dtype: Dtype | None = None,
+        copy: bool | None = None,
+    ) -> None:
+        allow_mgr = False
+        if dtype is not None:
+            dtype = self._validate_dtype(dtype)
+
+        if isinstance(data, DataFrame):
+            data = data._mgr
+            allow_mgr = True
+            if not copy:
+                # if not copying data, ensure to still return a shallow copy
+                # to avoid the result sharing the same Manager
+                data = data.copy(deep=False)
+
+        if isinstance(data, (BlockManager, ArrayManager)):
+            if not allow_mgr:
+                # GH#52419
+                warnings.warn(
+                    f"Passing a {type(data).__name__} to {type(self).__name__} "
+                    "is deprecated and will raise in a future version. "
+                    "Use public APIs instead.",
+                    DeprecationWarning,
+                    stacklevel=1,  # bump to 2 once pyarrow 15.0 is released with fix
+                )
+
+            if using_copy_on_write():
+                data = data.copy(deep=False)
+            # first check if a Manager is passed without any other arguments
+            # -> use fastpath (without checking Manager type)
+            if index is None and columns is None and dtype is None and not copy:
+                # GH#33357 fastpath
+                NDFrame.__init__(self, data)
+                return
+
+        manager = _get_option("mode.data_manager", silent=True)
+
+        is_pandas_object = isinstance(data, (Series, Index, ExtensionArray))
+        data_dtype = getattr(data, "dtype", None)
+        original_dtype = dtype
+
+        # GH47215
+        if isinstance(index, set):
+            raise ValueError("index cannot be a set")
+        if isinstance(columns, set):
+            raise ValueError("columns cannot be a set")
+
+        if copy is None:
+            if isinstance(data, dict):
+                # retain pre-GH#38939 default behavior
+                copy = True
+            elif (
+                manager == "array"
+                and isinstance(data, (np.ndarray, ExtensionArray))
+                and data.ndim == 2
+            ):
+                # INFO(ArrayManager) by default copy the 2D input array to get
+                # contiguous 1D arrays
+                copy = True
+            elif using_copy_on_write() and not isinstance(
+                data, (Index, DataFrame, Series)
+            ):
+                copy = True
+            else:
+                copy = False
+
+        if data is None:
+            index = index if index is not None else default_index(0)
+            columns = columns if columns is not None else default_index(0)
+            dtype = dtype if dtype is not None else pandas_dtype(object)
+            data = []
+
+        if isinstance(data, (BlockManager, ArrayManager)):
+            mgr = self._init_mgr(
+                data, axes={"index": index, "columns": columns}, dtype=dtype, copy=copy
+            )
+
+        elif isinstance(data, dict):
+            # GH#38939 de facto copy defaults to False only in non-dict cases
+            mgr = dict_to_mgr(data, index, columns, dtype=dtype, copy=copy, typ=manager)
+        elif isinstance(data, ma.MaskedArray):
+            from numpy.ma import mrecords
+
+            # masked recarray
+            if isinstance(data, mrecords.MaskedRecords):
+                raise TypeError(
+                    "MaskedRecords are not supported. Pass "
+                    "{name: data[name] for name in data.dtype.names} "
+                    "instead"
+                )
+
+            # a masked array
+            data = sanitize_masked_array(data)
+            mgr = ndarray_to_mgr(
+                data,
+                index,
+                columns,
+                dtype=dtype,
+                copy=copy,
+                typ=manager,
+            )
+
+        elif isinstance(data, (np.ndarray, Series, Index, ExtensionArray)):
+            if data.dtype.names:
+                # i.e. numpy structured array
+                data = cast(np.ndarray, data)
+                mgr = rec_array_to_mgr(
+                    data,
+                    index,
+                    columns,
+                    dtype,
+                    copy,
+                    typ=manager,
+                )
+            elif getattr(data, "name", None) is not None:
+                # i.e. Series/Index with non-None name
+                _copy = copy if using_copy_on_write() else True
+                mgr = dict_to_mgr(
+                    # error: Item "ndarray" of "Union[ndarray, Series, Index]" has no
+                    # attribute "name"
+                    {data.name: data},  # type: ignore[union-attr]
+                    index,
+                    columns,
+                    dtype=dtype,
+                    typ=manager,
+                    copy=_copy,
+                )
+            else:
+                mgr = ndarray_to_mgr(
+                    data,
+                    index,
+                    columns,
+                    dtype=dtype,
+                    copy=copy,
+                    typ=manager,
+                )
+
+        # For data is list-like, or Iterable (will consume into list)
+        elif is_list_like(data):
+            if not isinstance(data, abc.Sequence):
+                if hasattr(data, "__array__"):
+                    # GH#44616 big perf improvement for e.g. pytorch tensor
+                    data = np.asarray(data)
+                else:
+                    data = list(data)
+            if len(data) > 0:
+                if is_dataclass(data[0]):
+                    data = dataclasses_to_dicts(data)
+                if not isinstance(data, np.ndarray) and treat_as_nested(data):
+                    # exclude ndarray as we may have cast it a few lines above
+                    if columns is not None:
+                        columns = ensure_index(columns)
+                    arrays, columns, index = nested_data_to_arrays(
+                        # error: Argument 3 to "nested_data_to_arrays" has incompatible
+                        # type "Optional[Collection[Any]]"; expected "Optional[Index]"
+                        data,
+                        columns,
+                        index,  # type: ignore[arg-type]
+                        dtype,
+                    )
+                    mgr = arrays_to_mgr(
+                        arrays,
+                        columns,
+                        index,
+                        dtype=dtype,
+                        typ=manager,
+                    )
+                else:
+                    mgr = ndarray_to_mgr(
+                        data,
+                        index,
+                        columns,
+                        dtype=dtype,
+                        copy=copy,
+                        typ=manager,
+                    )
+            else:
+                mgr = dict_to_mgr(
+                    {},
+                    index,
+                    columns if columns is not None else default_index(0),
+                    dtype=dtype,
+                    typ=manager,
+                )
+        # For data is scalar
+        else:
+            if index is None or columns is None:
+                raise ValueError("DataFrame constructor not properly called!")
+
+            index = ensure_index(index)
+            columns = ensure_index(columns)
+
+            if not dtype:
+                dtype, _ = infer_dtype_from_scalar(data)
+
+            # For data is a scalar extension dtype
+            if isinstance(dtype, ExtensionDtype):
+                # TODO(EA2D): special case not needed with 2D EAs
+
+                values = [
+                    construct_1d_arraylike_from_scalar(data, len(index), dtype)
+                    for _ in range(len(columns))
+                ]
+                mgr = arrays_to_mgr(values, columns, index, dtype=None, typ=manager)
+            else:
+                arr2d = construct_2d_arraylike_from_scalar(
+                    data,
+                    len(index),
+                    len(columns),
+                    dtype,
+                    copy,
+                )
+
+                mgr = ndarray_to_mgr(
+                    arr2d,
+                    index,
+                    columns,
+                    dtype=arr2d.dtype,
+                    copy=False,
+                    typ=manager,
+                )
+
+        # ensure correct Manager type according to settings
+        mgr = mgr_to_mgr(mgr, typ=manager)
+
+        NDFrame.__init__(self, mgr)
+
+        if original_dtype is None and is_pandas_object and data_dtype == np.object_:
+            if self.dtypes.iloc[0] != data_dtype:
+                warnings.warn(
+                    "Dtype inference on a pandas object "
+                    "(Series, Index, ExtensionArray) is deprecated. The DataFrame "
+                    "constructor will keep the original dtype in the future. "
+                    "Call `infer_objects` on the result to get the old "
+                    "behavior.",
+                    FutureWarning,
+                    stacklevel=2,
+                )
+
+    # ----------------------------------------------------------------------
+
+    def __dataframe__(
+        self, nan_as_null: bool = False, allow_copy: bool = True
+    ) -> DataFrameXchg:
+        """
+        Return the dataframe interchange object implementing the interchange protocol.
+
+        Parameters
+        ----------
+        nan_as_null : bool, default False
+            `nan_as_null` is DEPRECATED and has no effect. Please avoid using
+            it; it will be removed in a future release.
+        allow_copy : bool, default True
+            Whether to allow memory copying when exporting. If set to False
+            it would cause non-zero-copy exports to fail.
+
+        Returns
+        -------
+        DataFrame interchange object
+            The object which consuming library can use to ingress the dataframe.
+
+        Notes
+        -----
+        Details on the interchange protocol:
+        https://data-apis.org/dataframe-protocol/latest/index.html
+
+        Examples
+        --------
+        >>> df_not_necessarily_pandas = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+        >>> interchange_object = df_not_necessarily_pandas.__dataframe__()
+        >>> interchange_object.column_names()
+        Index(['A', 'B'], dtype='object')
+        >>> df_pandas = (pd.api.interchange.from_dataframe
+        ...              (interchange_object.select_columns_by_name(['A'])))
+        >>> df_pandas
+             A
+        0    1
+        1    2
+
+        These methods (``column_names``, ``select_columns_by_name``) should work
+        for any dataframe library which implements the interchange protocol.
+        """
+
+        from pandas.core.interchange.dataframe import PandasDataFrameXchg
+
+        return PandasDataFrameXchg(self, allow_copy=allow_copy)
+
+    def __dataframe_consortium_standard__(
+        self, *, api_version: str | None = None
+    ) -> Any:
+        """
+        Provide entry point to the Consortium DataFrame Standard API.
+
+        This is developed and maintained outside of pandas.
+        Please report any issues to https://github.com/data-apis/dataframe-api-compat.
+        """
+        dataframe_api_compat = import_optional_dependency("dataframe_api_compat")
+        convert_to_standard_compliant_dataframe = (
+            dataframe_api_compat.pandas_standard.convert_to_standard_compliant_dataframe
+        )
+        return convert_to_standard_compliant_dataframe(self, api_version=api_version)
+
+    def __arrow_c_stream__(self, requested_schema=None):
+        """
+        Export the pandas DataFrame as an Arrow C stream PyCapsule.
+
+        This relies on pyarrow to convert the pandas DataFrame to the Arrow
+        format (and follows the default behaviour of ``pyarrow.Table.from_pandas``
+        in its handling of the index, i.e. store the index as a column except
+        for RangeIndex).
+        This conversion is not necessarily zero-copy.
+
+        Parameters
+        ----------
+        requested_schema : PyCapsule, default None
+            The schema to which the dataframe should be casted, passed as a
+            PyCapsule containing a C ArrowSchema representation of the
+            requested schema.
+
+        Returns
+        -------
+        PyCapsule
+        """
+        pa = import_optional_dependency("pyarrow", min_version="14.0.0")
+        if requested_schema is not None:
+            requested_schema = pa.Schema._import_from_c_capsule(requested_schema)
+        table = pa.Table.from_pandas(self, schema=requested_schema)
+        return table.__arrow_c_stream__()
+
+    # ----------------------------------------------------------------------
+
+    @property
+    def axes(self) -> list[Index]:
+        """
+        Return a list representing the axes of the DataFrame.
+
+        It has the row axis labels and column axis labels as the only members.
+        They are returned in that order.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df.axes
+        [RangeIndex(start=0, stop=2, step=1), Index(['col1', 'col2'],
+        dtype='object')]
+        """
+        return [self.index, self.columns]
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        """
+        Return a tuple representing the dimensionality of the DataFrame.
+
+        See Also
+        --------
+        ndarray.shape : Tuple of array dimensions.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df.shape
+        (2, 2)
+
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4],
+        ...                    'col3': [5, 6]})
+        >>> df.shape
+        (2, 3)
+        """
+        return len(self.index), len(self.columns)
+
+    @property
+    def _is_homogeneous_type(self) -> bool:
+        """
+        Whether all the columns in a DataFrame have the same type.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> DataFrame({"A": [1, 2], "B": [3, 4]})._is_homogeneous_type
+        True
+        >>> DataFrame({"A": [1, 2], "B": [3.0, 4.0]})._is_homogeneous_type
+        False
+
+        Items with the same type but different sizes are considered
+        different types.
+
+        >>> DataFrame({
+        ...    "A": np.array([1, 2], dtype=np.int32),
+        ...    "B": np.array([1, 2], dtype=np.int64)})._is_homogeneous_type
+        False
+        """
+        # The "<" part of "<=" here is for empty DataFrame cases
+        return len({arr.dtype for arr in self._mgr.arrays}) <= 1
+
+    @property
+    def _can_fast_transpose(self) -> bool:
+        """
+        Can we transpose this DataFrame without creating any new array objects.
+        """
+        if isinstance(self._mgr, ArrayManager):
+            return False
+        blocks = self._mgr.blocks
+        if len(blocks) != 1:
+            return False
+
+        dtype = blocks[0].dtype
+        # TODO(EA2D) special case would be unnecessary with 2D EAs
+        return not is_1d_only_ea_dtype(dtype)
+
+    @property
+    def _values(self) -> np.ndarray | DatetimeArray | TimedeltaArray | PeriodArray:
+        """
+        Analogue to ._values that may return a 2D ExtensionArray.
+        """
+        mgr = self._mgr
+
+        if isinstance(mgr, ArrayManager):
+            if len(mgr.arrays) == 1 and not is_1d_only_ea_dtype(mgr.arrays[0].dtype):
+                # error: Item "ExtensionArray" of "Union[ndarray, ExtensionArray]"
+                # has no attribute "reshape"
+                return mgr.arrays[0].reshape(-1, 1)  # type: ignore[union-attr]
+            return ensure_wrapped_if_datetimelike(self.values)
+
+        blocks = mgr.blocks
+        if len(blocks) != 1:
+            return ensure_wrapped_if_datetimelike(self.values)
+
+        arr = blocks[0].values
+        if arr.ndim == 1:
+            # non-2D ExtensionArray
+            return self.values
+
+        # more generally, whatever we allow in NDArrayBackedExtensionBlock
+        arr = cast("np.ndarray | DatetimeArray | TimedeltaArray | PeriodArray", arr)
+        return arr.T
+
+    # ----------------------------------------------------------------------
+    # Rendering Methods
+
+    def _repr_fits_vertical_(self) -> bool:
+        """
+        Check length against max_rows.
+        """
+        max_rows = get_option("display.max_rows")
+        return len(self) <= max_rows
+
+    def _repr_fits_horizontal_(self) -> bool:
+        """
+        Check if full repr fits in horizontal boundaries imposed by the display
+        options width and max_columns.
+        """
+        width, height = console.get_console_size()
+        max_columns = get_option("display.max_columns")
+        nb_columns = len(self.columns)
+
+        # exceed max columns
+        if (max_columns and nb_columns > max_columns) or (
+            width and nb_columns > (width // 2)
+        ):
+            return False
+
+        # used by repr_html under IPython notebook or scripts ignore terminal
+        # dims
+        if width is None or not console.in_interactive_session():
+            return True
+
+        if get_option("display.width") is not None or console.in_ipython_frontend():
+            # check at least the column row for excessive width
+            max_rows = 1
+        else:
+            max_rows = get_option("display.max_rows")
+
+        # when auto-detecting, so width=None and not in ipython front end
+        # check whether repr fits horizontal by actually checking
+        # the width of the rendered repr
+        buf = StringIO()
+
+        # only care about the stuff we'll actually print out
+        # and to_string on entire frame may be expensive
+        d = self
+
+        if max_rows is not None:  # unlimited rows
+            # min of two, where one may be None
+            d = d.iloc[: min(max_rows, len(d))]
+        else:
+            return True
+
+        d.to_string(buf=buf)
+        value = buf.getvalue()
+        repr_width = max(len(line) for line in value.split("\n"))
+
+        return repr_width < width
+
+    def _info_repr(self) -> bool:
+        """
+        True if the repr should show the info view.
+        """
+        info_repr_option = get_option("display.large_repr") == "info"
+        return info_repr_option and not (
+            self._repr_fits_horizontal_() and self._repr_fits_vertical_()
+        )
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation for a particular DataFrame.
+        """
+        if self._info_repr():
+            buf = StringIO()
+            self.info(buf=buf)
+            return buf.getvalue()
+
+        repr_params = fmt.get_dataframe_repr_params()
+        return self.to_string(**repr_params)
+
+    def _repr_html_(self) -> str | None:
+        """
+        Return a html representation for a particular DataFrame.
+
+        Mainly for IPython notebook.
+        """
+        if self._info_repr():
+            buf = StringIO()
+            self.info(buf=buf)
+            # need to escape the , should be the first line.
+            val = buf.getvalue().replace("<", r"<", 1)
+            val = val.replace(">", r">", 1)
+            return f"
{val}
"
+
+        if get_option("display.notebook_repr_html"):
+            max_rows = get_option("display.max_rows")
+            min_rows = get_option("display.min_rows")
+            max_cols = get_option("display.max_columns")
+            show_dimensions = get_option("display.show_dimensions")
+
+            formatter = fmt.DataFrameFormatter(
+                self,
+                columns=None,
+                col_space=None,
+                na_rep="NaN",
+                formatters=None,
+                float_format=None,
+                sparsify=None,
+                justify=None,
+                index_names=True,
+                header=True,
+                index=True,
+                bold_rows=True,
+                escape=True,
+                max_rows=max_rows,
+                min_rows=min_rows,
+                max_cols=max_cols,
+                show_dimensions=show_dimensions,
+                decimal=".",
+            )
+            return fmt.DataFrameRenderer(formatter).to_html(notebook=True)
+        else:
+            return None
+
+    @overload
+    def to_string(
+        self,
+        buf: None = ...,
+        columns: Axes | None = ...,
+        col_space: int | list[int] | dict[Hashable, int] | None = ...,
+        header: bool | SequenceNotStr[str] = ...,
+        index: bool = ...,
+        na_rep: str = ...,
+        formatters: fmt.FormattersType | None = ...,
+        float_format: fmt.FloatFormatType | None = ...,
+        sparsify: bool | None = ...,
+        index_names: bool = ...,
+        justify: str | None = ...,
+        max_rows: int | None = ...,
+        max_cols: int | None = ...,
+        show_dimensions: bool = ...,
+        decimal: str = ...,
+        line_width: int | None = ...,
+        min_rows: int | None = ...,
+        max_colwidth: int | None = ...,
+        encoding: str | None = ...,
+    ) -> str:
+        ...
+
+    @overload
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        columns: Axes | None = ...,
+        col_space: int | list[int] | dict[Hashable, int] | None = ...,
+        header: bool | SequenceNotStr[str] = ...,
+        index: bool = ...,
+        na_rep: str = ...,
+        formatters: fmt.FormattersType | None = ...,
+        float_format: fmt.FloatFormatType | None = ...,
+        sparsify: bool | None = ...,
+        index_names: bool = ...,
+        justify: str | None = ...,
+        max_rows: int | None = ...,
+        max_cols: int | None = ...,
+        show_dimensions: bool = ...,
+        decimal: str = ...,
+        line_width: int | None = ...,
+        min_rows: int | None = ...,
+        max_colwidth: int | None = ...,
+        encoding: str | None = ...,
+    ) -> None:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "buf"], name="to_string"
+    )
+    @Substitution(
+        header_type="bool or list of str",
+        header="Write out the column names. If a list of columns "
+        "is given, it is assumed to be aliases for the "
+        "column names",
+        col_space_type="int, list or dict of int",
+        col_space="The minimum width of each column. If a list of ints is given "
+        "every integers corresponds with one column. If a dict is given, the key "
+        "references the column, while the value defines the space to use.",
+    )
+    @Substitution(shared_params=fmt.common_docstring, returns=fmt.return_docstring)
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        columns: Axes | None = None,
+        col_space: int | list[int] | dict[Hashable, int] | None = None,
+        header: bool | SequenceNotStr[str] = True,
+        index: bool = True,
+        na_rep: str = "NaN",
+        formatters: fmt.FormattersType | None = None,
+        float_format: fmt.FloatFormatType | None = None,
+        sparsify: bool | None = None,
+        index_names: bool = True,
+        justify: str | None = None,
+        max_rows: int | None = None,
+        max_cols: int | None = None,
+        show_dimensions: bool = False,
+        decimal: str = ".",
+        line_width: int | None = None,
+        min_rows: int | None = None,
+        max_colwidth: int | None = None,
+        encoding: str | None = None,
+    ) -> str | None:
+        """
+        Render a DataFrame to a console-friendly tabular output.
+        %(shared_params)s
+        line_width : int, optional
+            Width to wrap a line in characters.
+        min_rows : int, optional
+            The number of rows to display in the console in a truncated repr
+            (when number of rows is above `max_rows`).
+        max_colwidth : int, optional
+            Max width to truncate each column in characters. By default, no limit.
+        encoding : str, default "utf-8"
+            Set character encoding.
+        %(returns)s
+        See Also
+        --------
+        to_html : Convert DataFrame to HTML.
+
+        Examples
+        --------
+        >>> d = {'col1': [1, 2, 3], 'col2': [4, 5, 6]}
+        >>> df = pd.DataFrame(d)
+        >>> print(df.to_string())
+           col1  col2
+        0     1     4
+        1     2     5
+        2     3     6
+        """
+        from pandas import option_context
+
+        with option_context("display.max_colwidth", max_colwidth):
+            formatter = fmt.DataFrameFormatter(
+                self,
+                columns=columns,
+                col_space=col_space,
+                na_rep=na_rep,
+                formatters=formatters,
+                float_format=float_format,
+                sparsify=sparsify,
+                justify=justify,
+                index_names=index_names,
+                header=header,
+                index=index,
+                min_rows=min_rows,
+                max_rows=max_rows,
+                max_cols=max_cols,
+                show_dimensions=show_dimensions,
+                decimal=decimal,
+            )
+            return fmt.DataFrameRenderer(formatter).to_string(
+                buf=buf,
+                encoding=encoding,
+                line_width=line_width,
+            )
+
+    def _get_values_for_csv(
+        self,
+        *,
+        float_format: FloatFormatType | None,
+        date_format: str | None,
+        decimal: str,
+        na_rep: str,
+        quoting,  # int csv.QUOTE_FOO from stdlib
+    ) -> Self:
+        # helper used by to_csv
+        mgr = self._mgr.get_values_for_csv(
+            float_format=float_format,
+            date_format=date_format,
+            decimal=decimal,
+            na_rep=na_rep,
+            quoting=quoting,
+        )
+        # error: Incompatible return value type (got "DataFrame", expected "Self")
+        return self._constructor_from_mgr(mgr, axes=mgr.axes)  # type: ignore[return-value]
+
+    # ----------------------------------------------------------------------
+
+    @property
+    def style(self) -> Styler:
+        """
+        Returns a Styler object.
+
+        Contains methods for building a styled HTML representation of the DataFrame.
+
+        See Also
+        --------
+        io.formats.style.Styler : Helps style a DataFrame or Series according to the
+            data with HTML and CSS.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2, 3]})
+        >>> df.style  # doctest: +SKIP
+
+        Please see
+        `Table Visualization <../../user_guide/style.ipynb>`_ for more examples.
+        """
+        # Raise AttributeError so that inspect works even if jinja2 is not installed.
+        has_jinja2 = import_optional_dependency("jinja2", errors="ignore")
+        if not has_jinja2:
+            raise AttributeError("The '.style' accessor requires jinja2")
+
+        from pandas.io.formats.style import Styler
+
+        return Styler(self)
+
+    _shared_docs[
+        "items"
+    ] = r"""
+        Iterate over (column name, Series) pairs.
+
+        Iterates over the DataFrame columns, returning a tuple with
+        the column name and the content as a Series.
+
+        Yields
+        ------
+        label : object
+            The column names for the DataFrame being iterated over.
+        content : Series
+            The column entries belonging to each label, as a Series.
+
+        See Also
+        --------
+        DataFrame.iterrows : Iterate over DataFrame rows as
+            (index, Series) pairs.
+        DataFrame.itertuples : Iterate over DataFrame rows as namedtuples
+            of the values.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'species': ['bear', 'bear', 'marsupial'],
+        ...                   'population': [1864, 22000, 80000]},
+        ...                   index=['panda', 'polar', 'koala'])
+        >>> df
+                species   population
+        panda   bear      1864
+        polar   bear      22000
+        koala   marsupial 80000
+        >>> for label, content in df.items():
+        ...     print(f'label: {label}')
+        ...     print(f'content: {content}', sep='\n')
+        ...
+        label: species
+        content:
+        panda         bear
+        polar         bear
+        koala    marsupial
+        Name: species, dtype: object
+        label: population
+        content:
+        panda     1864
+        polar    22000
+        koala    80000
+        Name: population, dtype: int64
+        """
+
+    @Appender(_shared_docs["items"])
+    def items(self) -> Iterable[tuple[Hashable, Series]]:
+        if self.columns.is_unique and hasattr(self, "_item_cache"):
+            for k in self.columns:
+                yield k, self._get_item_cache(k)
+        else:
+            for i, k in enumerate(self.columns):
+                yield k, self._ixs(i, axis=1)
+
+    def iterrows(self) -> Iterable[tuple[Hashable, Series]]:
+        """
+        Iterate over DataFrame rows as (index, Series) pairs.
+
+        Yields
+        ------
+        index : label or tuple of label
+            The index of the row. A tuple for a `MultiIndex`.
+        data : Series
+            The data of the row as a Series.
+
+        See Also
+        --------
+        DataFrame.itertuples : Iterate over DataFrame rows as namedtuples of the values.
+        DataFrame.items : Iterate over (column name, Series) pairs.
+
+        Notes
+        -----
+        1. Because ``iterrows`` returns a Series for each row,
+           it does **not** preserve dtypes across the rows (dtypes are
+           preserved across columns for DataFrames).
+
+           To preserve dtypes while iterating over the rows, it is better
+           to use :meth:`itertuples` which returns namedtuples of the values
+           and which is generally faster than ``iterrows``.
+
+        2. You should **never modify** something you are iterating over.
+           This is not guaranteed to work in all cases. Depending on the
+           data types, the iterator returns a copy and not a view, and writing
+           to it will have no effect.
+
+        Examples
+        --------
+
+        >>> df = pd.DataFrame([[1, 1.5]], columns=['int', 'float'])
+        >>> row = next(df.iterrows())[1]
+        >>> row
+        int      1.0
+        float    1.5
+        Name: 0, dtype: float64
+        >>> print(row['int'].dtype)
+        float64
+        >>> print(df['int'].dtype)
+        int64
+        """
+        columns = self.columns
+        klass = self._constructor_sliced
+        using_cow = using_copy_on_write()
+        for k, v in zip(self.index, self.values):
+            s = klass(v, index=columns, name=k).__finalize__(self)
+            if using_cow and self._mgr.is_single_block:
+                s._mgr.add_references(self._mgr)  # type: ignore[arg-type]
+            yield k, s
+
+    def itertuples(
+        self, index: bool = True, name: str | None = "Pandas"
+    ) -> Iterable[tuple[Any, ...]]:
+        """
+        Iterate over DataFrame rows as namedtuples.
+
+        Parameters
+        ----------
+        index : bool, default True
+            If True, return the index as the first element of the tuple.
+        name : str or None, default "Pandas"
+            The name of the returned namedtuples or None to return regular
+            tuples.
+
+        Returns
+        -------
+        iterator
+            An object to iterate over namedtuples for each row in the
+            DataFrame with the first field possibly being the index and
+            following fields being the column values.
+
+        See Also
+        --------
+        DataFrame.iterrows : Iterate over DataFrame rows as (index, Series)
+            pairs.
+        DataFrame.items : Iterate over (column name, Series) pairs.
+
+        Notes
+        -----
+        The column names will be renamed to positional names if they are
+        invalid Python identifiers, repeated, or start with an underscore.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'num_legs': [4, 2], 'num_wings': [0, 2]},
+        ...                   index=['dog', 'hawk'])
+        >>> df
+              num_legs  num_wings
+        dog          4          0
+        hawk         2          2
+        >>> for row in df.itertuples():
+        ...     print(row)
+        ...
+        Pandas(Index='dog', num_legs=4, num_wings=0)
+        Pandas(Index='hawk', num_legs=2, num_wings=2)
+
+        By setting the `index` parameter to False we can remove the index
+        as the first element of the tuple:
+
+        >>> for row in df.itertuples(index=False):
+        ...     print(row)
+        ...
+        Pandas(num_legs=4, num_wings=0)
+        Pandas(num_legs=2, num_wings=2)
+
+        With the `name` parameter set we set a custom name for the yielded
+        namedtuples:
+
+        >>> for row in df.itertuples(name='Animal'):
+        ...     print(row)
+        ...
+        Animal(Index='dog', num_legs=4, num_wings=0)
+        Animal(Index='hawk', num_legs=2, num_wings=2)
+        """
+        arrays = []
+        fields = list(self.columns)
+        if index:
+            arrays.append(self.index)
+            fields.insert(0, "Index")
+
+        # use integer indexing because of possible duplicate column names
+        arrays.extend(self.iloc[:, k] for k in range(len(self.columns)))
+
+        if name is not None:
+            # https://github.com/python/mypy/issues/9046
+            # error: namedtuple() expects a string literal as the first argument
+            itertuple = collections.namedtuple(  # type: ignore[misc]
+                name, fields, rename=True
+            )
+            return map(itertuple._make, zip(*arrays))
+
+        # fallback to regular tuples
+        return zip(*arrays)
+
+    def __len__(self) -> int:
+        """
+        Returns length of info axis, but here we use the index.
+        """
+        return len(self.index)
+
+    @overload
+    def dot(self, other: Series) -> Series:
+        ...
+
+    @overload
+    def dot(self, other: DataFrame | Index | ArrayLike) -> DataFrame:
+        ...
+
+    def dot(self, other: AnyArrayLike | DataFrame) -> DataFrame | Series:
+        """
+        Compute the matrix multiplication between the DataFrame and other.
+
+        This method computes the matrix product between the DataFrame and the
+        values of an other Series, DataFrame or a numpy array.
+
+        It can also be called using ``self @ other``.
+
+        Parameters
+        ----------
+        other : Series, DataFrame or array-like
+            The other object to compute the matrix product with.
+
+        Returns
+        -------
+        Series or DataFrame
+            If other is a Series, return the matrix product between self and
+            other as a Series. If other is a DataFrame or a numpy.array, return
+            the matrix product of self and other in a DataFrame of a np.array.
+
+        See Also
+        --------
+        Series.dot: Similar method for Series.
+
+        Notes
+        -----
+        The dimensions of DataFrame and other must be compatible in order to
+        compute the matrix multiplication. In addition, the column names of
+        DataFrame and the index of other must contain the same values, as they
+        will be aligned prior to the multiplication.
+
+        The dot method for Series computes the inner product, instead of the
+        matrix product here.
+
+        Examples
+        --------
+        Here we multiply a DataFrame with a Series.
+
+        >>> df = pd.DataFrame([[0, 1, -2, -1], [1, 1, 1, 1]])
+        >>> s = pd.Series([1, 1, 2, 1])
+        >>> df.dot(s)
+        0    -4
+        1     5
+        dtype: int64
+
+        Here we multiply a DataFrame with another DataFrame.
+
+        >>> other = pd.DataFrame([[0, 1], [1, 2], [-1, -1], [2, 0]])
+        >>> df.dot(other)
+            0   1
+        0   1   4
+        1   2   2
+
+        Note that the dot method give the same result as @
+
+        >>> df @ other
+            0   1
+        0   1   4
+        1   2   2
+
+        The dot method works also if other is an np.array.
+
+        >>> arr = np.array([[0, 1], [1, 2], [-1, -1], [2, 0]])
+        >>> df.dot(arr)
+            0   1
+        0   1   4
+        1   2   2
+
+        Note how shuffling of the objects does not change the result.
+
+        >>> s2 = s.reindex([1, 0, 2, 3])
+        >>> df.dot(s2)
+        0    -4
+        1     5
+        dtype: int64
+        """
+        if isinstance(other, (Series, DataFrame)):
+            common = self.columns.union(other.index)
+            if len(common) > len(self.columns) or len(common) > len(other.index):
+                raise ValueError("matrices are not aligned")
+
+            left = self.reindex(columns=common, copy=False)
+            right = other.reindex(index=common, copy=False)
+            lvals = left.values
+            rvals = right._values
+        else:
+            left = self
+            lvals = self.values
+            rvals = np.asarray(other)
+            if lvals.shape[1] != rvals.shape[0]:
+                raise ValueError(
+                    f"Dot product shape mismatch, {lvals.shape} vs {rvals.shape}"
+                )
+
+        if isinstance(other, DataFrame):
+            common_type = find_common_type(list(self.dtypes) + list(other.dtypes))
+            return self._constructor(
+                np.dot(lvals, rvals),
+                index=left.index,
+                columns=other.columns,
+                copy=False,
+                dtype=common_type,
+            )
+        elif isinstance(other, Series):
+            common_type = find_common_type(list(self.dtypes) + [other.dtypes])
+            return self._constructor_sliced(
+                np.dot(lvals, rvals), index=left.index, copy=False, dtype=common_type
+            )
+        elif isinstance(rvals, (np.ndarray, Index)):
+            result = np.dot(lvals, rvals)
+            if result.ndim == 2:
+                return self._constructor(result, index=left.index, copy=False)
+            else:
+                return self._constructor_sliced(result, index=left.index, copy=False)
+        else:  # pragma: no cover
+            raise TypeError(f"unsupported type: {type(other)}")
+
+    @overload
+    def __matmul__(self, other: Series) -> Series:
+        ...
+
+    @overload
+    def __matmul__(self, other: AnyArrayLike | DataFrame) -> DataFrame | Series:
+        ...
+
+    def __matmul__(self, other: AnyArrayLike | DataFrame) -> DataFrame | Series:
+        """
+        Matrix multiplication using binary `@` operator.
+        """
+        return self.dot(other)
+
+    def __rmatmul__(self, other) -> DataFrame:
+        """
+        Matrix multiplication using binary `@` operator.
+        """
+        try:
+            return self.T.dot(np.transpose(other)).T
+        except ValueError as err:
+            if "shape mismatch" not in str(err):
+                raise
+            # GH#21581 give exception message for original shapes
+            msg = f"shapes {np.shape(other)} and {self.shape} not aligned"
+            raise ValueError(msg) from err
+
+    # ----------------------------------------------------------------------
+    # IO methods (to / from other formats)
+
+    @classmethod
+    def from_dict(
+        cls,
+        data: dict,
+        orient: FromDictOrient = "columns",
+        dtype: Dtype | None = None,
+        columns: Axes | None = None,
+    ) -> DataFrame:
+        """
+        Construct DataFrame from dict of array-like or dicts.
+
+        Creates DataFrame object from dictionary by columns or by index
+        allowing dtype specification.
+
+        Parameters
+        ----------
+        data : dict
+            Of the form {field : array-like} or {field : dict}.
+        orient : {'columns', 'index', 'tight'}, default 'columns'
+            The "orientation" of the data. If the keys of the passed dict
+            should be the columns of the resulting DataFrame, pass 'columns'
+            (default). Otherwise if the keys should be rows, pass 'index'.
+            If 'tight', assume a dict with keys ['index', 'columns', 'data',
+            'index_names', 'column_names'].
+
+            .. versionadded:: 1.4.0
+               'tight' as an allowed value for the ``orient`` argument
+
+        dtype : dtype, default None
+            Data type to force after DataFrame construction, otherwise infer.
+        columns : list, default None
+            Column labels to use when ``orient='index'``. Raises a ValueError
+            if used with ``orient='columns'`` or ``orient='tight'``.
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        DataFrame.from_records : DataFrame from structured ndarray, sequence
+            of tuples or dicts, or DataFrame.
+        DataFrame : DataFrame object creation using constructor.
+        DataFrame.to_dict : Convert the DataFrame to a dictionary.
+
+        Examples
+        --------
+        By default the keys of the dict become the DataFrame columns:
+
+        >>> data = {'col_1': [3, 2, 1, 0], 'col_2': ['a', 'b', 'c', 'd']}
+        >>> pd.DataFrame.from_dict(data)
+           col_1 col_2
+        0      3     a
+        1      2     b
+        2      1     c
+        3      0     d
+
+        Specify ``orient='index'`` to create the DataFrame using dictionary
+        keys as rows:
+
+        >>> data = {'row_1': [3, 2, 1, 0], 'row_2': ['a', 'b', 'c', 'd']}
+        >>> pd.DataFrame.from_dict(data, orient='index')
+               0  1  2  3
+        row_1  3  2  1  0
+        row_2  a  b  c  d
+
+        When using the 'index' orientation, the column names can be
+        specified manually:
+
+        >>> pd.DataFrame.from_dict(data, orient='index',
+        ...                        columns=['A', 'B', 'C', 'D'])
+               A  B  C  D
+        row_1  3  2  1  0
+        row_2  a  b  c  d
+
+        Specify ``orient='tight'`` to create the DataFrame using a 'tight'
+        format:
+
+        >>> data = {'index': [('a', 'b'), ('a', 'c')],
+        ...         'columns': [('x', 1), ('y', 2)],
+        ...         'data': [[1, 3], [2, 4]],
+        ...         'index_names': ['n1', 'n2'],
+        ...         'column_names': ['z1', 'z2']}
+        >>> pd.DataFrame.from_dict(data, orient='tight')
+        z1     x  y
+        z2     1  2
+        n1 n2
+        a  b   1  3
+           c   2  4
+        """
+        index = None
+        orient = orient.lower()  # type: ignore[assignment]
+        if orient == "index":
+            if len(data) > 0:
+                # TODO speed up Series case
+                if isinstance(next(iter(data.values())), (Series, dict)):
+                    data = _from_nested_dict(data)
+                else:
+                    index = list(data.keys())
+                    # error: Incompatible types in assignment (expression has type
+                    # "List[Any]", variable has type "Dict[Any, Any]")
+                    data = list(data.values())  # type: ignore[assignment]
+        elif orient in ("columns", "tight"):
+            if columns is not None:
+                raise ValueError(f"cannot use columns parameter with orient='{orient}'")
+        else:  # pragma: no cover
+            raise ValueError(
+                f"Expected 'index', 'columns' or 'tight' for orient parameter. "
+                f"Got '{orient}' instead"
+            )
+
+        if orient != "tight":
+            return cls(data, index=index, columns=columns, dtype=dtype)
+        else:
+            realdata = data["data"]
+
+            def create_index(indexlist, namelist):
+                index: Index
+                if len(namelist) > 1:
+                    index = MultiIndex.from_tuples(indexlist, names=namelist)
+                else:
+                    index = Index(indexlist, name=namelist[0])
+                return index
+
+            index = create_index(data["index"], data["index_names"])
+            columns = create_index(data["columns"], data["column_names"])
+            return cls(realdata, index=index, columns=columns, dtype=dtype)
+
+    def to_numpy(
+        self,
+        dtype: npt.DTypeLike | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Convert the DataFrame to a NumPy array.
+
+        By default, the dtype of the returned array will be the common NumPy
+        dtype of all types in the DataFrame. For example, if the dtypes are
+        ``float16`` and ``float32``, the results dtype will be ``float32``.
+        This may require copying data and coercing values, which may be
+        expensive.
+
+        Parameters
+        ----------
+        dtype : str or numpy.dtype, optional
+            The dtype to pass to :meth:`numpy.asarray`.
+        copy : bool, default False
+            Whether to ensure that the returned value is not a view on
+            another array. Note that ``copy=False`` does not *ensure* that
+            ``to_numpy()`` is no-copy. Rather, ``copy=True`` ensure that
+            a copy is made, even if not strictly necessary.
+        na_value : Any, optional
+            The value to use for missing values. The default value depends
+            on `dtype` and the dtypes of the DataFrame columns.
+
+        Returns
+        -------
+        numpy.ndarray
+
+        See Also
+        --------
+        Series.to_numpy : Similar method for Series.
+
+        Examples
+        --------
+        >>> pd.DataFrame({"A": [1, 2], "B": [3, 4]}).to_numpy()
+        array([[1, 3],
+               [2, 4]])
+
+        With heterogeneous data, the lowest common type will have to
+        be used.
+
+        >>> df = pd.DataFrame({"A": [1, 2], "B": [3.0, 4.5]})
+        >>> df.to_numpy()
+        array([[1. , 3. ],
+               [2. , 4.5]])
+
+        For a mix of numeric and non-numeric types, the output array will
+        have object dtype.
+
+        >>> df['C'] = pd.date_range('2000', periods=2)
+        >>> df.to_numpy()
+        array([[1, 3.0, Timestamp('2000-01-01 00:00:00')],
+               [2, 4.5, Timestamp('2000-01-02 00:00:00')]], dtype=object)
+        """
+        if dtype is not None:
+            dtype = np.dtype(dtype)
+        result = self._mgr.as_array(dtype=dtype, copy=copy, na_value=na_value)
+        if result.dtype is not dtype:
+            result = np.asarray(result, dtype=dtype)
+
+        return result
+
+    def _create_data_for_split_and_tight_to_dict(
+        self, are_all_object_dtype_cols: bool, object_dtype_indices: list[int]
+    ) -> list:
+        """
+        Simple helper method to create data for to ``to_dict(orient="split")`` and
+        ``to_dict(orient="tight")`` to create the main output data
+        """
+        if are_all_object_dtype_cols:
+            data = [
+                list(map(maybe_box_native, t))
+                for t in self.itertuples(index=False, name=None)
+            ]
+        else:
+            data = [list(t) for t in self.itertuples(index=False, name=None)]
+            if object_dtype_indices:
+                # If we have object_dtype_cols, apply maybe_box_naive after list
+                # comprehension for perf
+                for row in data:
+                    for i in object_dtype_indices:
+                        row[i] = maybe_box_native(row[i])
+        return data
+
+    @overload
+    def to_dict(
+        self,
+        orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
+        *,
+        into: type[MutableMappingT] | MutableMappingT,
+        index: bool = ...,
+    ) -> MutableMappingT:
+        ...
+
+    @overload
+    def to_dict(
+        self,
+        orient: Literal["records"],
+        *,
+        into: type[MutableMappingT] | MutableMappingT,
+        index: bool = ...,
+    ) -> list[MutableMappingT]:
+        ...
+
+    @overload
+    def to_dict(
+        self,
+        orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
+        *,
+        into: type[dict] = ...,
+        index: bool = ...,
+    ) -> dict:
+        ...
+
+    @overload
+    def to_dict(
+        self,
+        orient: Literal["records"],
+        *,
+        into: type[dict] = ...,
+        index: bool = ...,
+    ) -> list[dict]:
+        ...
+
+    # error: Incompatible default for argument "into" (default has type "type
+    # [dict[Any, Any]]", argument has type "type[MutableMappingT] | MutableMappingT")
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "orient"], name="to_dict"
+    )
+    def to_dict(
+        self,
+        orient: Literal[
+            "dict", "list", "series", "split", "tight", "records", "index"
+        ] = "dict",
+        into: type[MutableMappingT]
+        | MutableMappingT = dict,  # type: ignore[assignment]
+        index: bool = True,
+    ) -> MutableMappingT | list[MutableMappingT]:
+        """
+        Convert the DataFrame to a dictionary.
+
+        The type of the key-value pairs can be customized with the parameters
+        (see below).
+
+        Parameters
+        ----------
+        orient : str {'dict', 'list', 'series', 'split', 'tight', 'records', 'index'}
+            Determines the type of the values of the dictionary.
+
+            - 'dict' (default) : dict like {column -> {index -> value}}
+            - 'list' : dict like {column -> [values]}
+            - 'series' : dict like {column -> Series(values)}
+            - 'split' : dict like
+              {'index' -> [index], 'columns' -> [columns], 'data' -> [values]}
+            - 'tight' : dict like
+              {'index' -> [index], 'columns' -> [columns], 'data' -> [values],
+              'index_names' -> [index.names], 'column_names' -> [column.names]}
+            - 'records' : list like
+              [{column -> value}, ... , {column -> value}]
+            - 'index' : dict like {index -> {column -> value}}
+
+            .. versionadded:: 1.4.0
+                'tight' as an allowed value for the ``orient`` argument
+
+        into : class, default dict
+            The collections.abc.MutableMapping subclass used for all Mappings
+            in the return value.  Can be the actual class or an empty
+            instance of the mapping type you want.  If you want a
+            collections.defaultdict, you must pass it initialized.
+
+        index : bool, default True
+            Whether to include the index item (and index_names item if `orient`
+            is 'tight') in the returned dictionary. Can only be ``False``
+            when `orient` is 'split' or 'tight'.
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        dict, list or collections.abc.MutableMapping
+            Return a collections.abc.MutableMapping object representing the
+            DataFrame. The resulting transformation depends on the `orient`
+            parameter.
+
+        See Also
+        --------
+        DataFrame.from_dict: Create a DataFrame from a dictionary.
+        DataFrame.to_json: Convert a DataFrame to JSON format.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'col1': [1, 2],
+        ...                    'col2': [0.5, 0.75]},
+        ...                   index=['row1', 'row2'])
+        >>> df
+              col1  col2
+        row1     1  0.50
+        row2     2  0.75
+        >>> df.to_dict()
+        {'col1': {'row1': 1, 'row2': 2}, 'col2': {'row1': 0.5, 'row2': 0.75}}
+
+        You can specify the return orientation.
+
+        >>> df.to_dict('series')
+        {'col1': row1    1
+                 row2    2
+        Name: col1, dtype: int64,
+        'col2': row1    0.50
+                row2    0.75
+        Name: col2, dtype: float64}
+
+        >>> df.to_dict('split')
+        {'index': ['row1', 'row2'], 'columns': ['col1', 'col2'],
+         'data': [[1, 0.5], [2, 0.75]]}
+
+        >>> df.to_dict('records')
+        [{'col1': 1, 'col2': 0.5}, {'col1': 2, 'col2': 0.75}]
+
+        >>> df.to_dict('index')
+        {'row1': {'col1': 1, 'col2': 0.5}, 'row2': {'col1': 2, 'col2': 0.75}}
+
+        >>> df.to_dict('tight')
+        {'index': ['row1', 'row2'], 'columns': ['col1', 'col2'],
+         'data': [[1, 0.5], [2, 0.75]], 'index_names': [None], 'column_names': [None]}
+
+        You can also specify the mapping type.
+
+        >>> from collections import OrderedDict, defaultdict
+        >>> df.to_dict(into=OrderedDict)
+        OrderedDict([('col1', OrderedDict([('row1', 1), ('row2', 2)])),
+                     ('col2', OrderedDict([('row1', 0.5), ('row2', 0.75)]))])
+
+        If you want a `defaultdict`, you need to initialize it:
+
+        >>> dd = defaultdict(list)
+        >>> df.to_dict('records', into=dd)
+        [defaultdict(, {'col1': 1, 'col2': 0.5}),
+         defaultdict(, {'col1': 2, 'col2': 0.75})]
+        """
+        from pandas.core.methods.to_dict import to_dict
+
+        return to_dict(self, orient, into=into, index=index)
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "destination_table"], name="to_gbq"
+    )
+    def to_gbq(
+        self,
+        destination_table: str,
+        project_id: str | None = None,
+        chunksize: int | None = None,
+        reauth: bool = False,
+        if_exists: ToGbqIfexist = "fail",
+        auth_local_webserver: bool = True,
+        table_schema: list[dict[str, str]] | None = None,
+        location: str | None = None,
+        progress_bar: bool = True,
+        credentials=None,
+    ) -> None:
+        """
+        Write a DataFrame to a Google BigQuery table.
+
+        .. deprecated:: 2.2.0
+
+           Please use ``pandas_gbq.to_gbq`` instead.
+
+        This function requires the `pandas-gbq package
+        `__.
+
+        See the `How to authenticate with Google BigQuery
+        `__
+        guide for authentication instructions.
+
+        Parameters
+        ----------
+        destination_table : str
+            Name of table to be written, in the form ``dataset.tablename``.
+        project_id : str, optional
+            Google BigQuery Account project ID. Optional when available from
+            the environment.
+        chunksize : int, optional
+            Number of rows to be inserted in each chunk from the dataframe.
+            Set to ``None`` to load the whole dataframe at once.
+        reauth : bool, default False
+            Force Google BigQuery to re-authenticate the user. This is useful
+            if multiple accounts are used.
+        if_exists : str, default 'fail'
+            Behavior when the destination table exists. Value can be one of:
+
+            ``'fail'``
+                If table exists raise pandas_gbq.gbq.TableCreationError.
+            ``'replace'``
+                If table exists, drop it, recreate it, and insert data.
+            ``'append'``
+                If table exists, insert data. Create if does not exist.
+        auth_local_webserver : bool, default True
+            Use the `local webserver flow`_ instead of the `console flow`_
+            when getting user credentials.
+
+            .. _local webserver flow:
+                https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+            .. _console flow:
+                https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console
+
+            *New in version 0.2.0 of pandas-gbq*.
+
+            .. versionchanged:: 1.5.0
+               Default value is changed to ``True``. Google has deprecated the
+               ``auth_local_webserver = False`` `"out of band" (copy-paste)
+               flow
+               `_.
+        table_schema : list of dicts, optional
+            List of BigQuery table fields to which according DataFrame
+            columns conform to, e.g. ``[{'name': 'col1', 'type':
+            'STRING'},...]``. If schema is not provided, it will be
+            generated according to dtypes of DataFrame columns. See
+            BigQuery API documentation on available names of a field.
+
+            *New in version 0.3.1 of pandas-gbq*.
+        location : str, optional
+            Location where the load job should run. See the `BigQuery locations
+            documentation
+            `__ for a
+            list of available locations. The location must match that of the
+            target dataset.
+
+            *New in version 0.5.0 of pandas-gbq*.
+        progress_bar : bool, default True
+            Use the library `tqdm` to show the progress bar for the upload,
+            chunk by chunk.
+
+            *New in version 0.5.0 of pandas-gbq*.
+        credentials : google.auth.credentials.Credentials, optional
+            Credentials for accessing Google APIs. Use this parameter to
+            override default credentials, such as to use Compute Engine
+            :class:`google.auth.compute_engine.Credentials` or Service
+            Account :class:`google.oauth2.service_account.Credentials`
+            directly.
+
+            *New in version 0.8.0 of pandas-gbq*.
+
+        See Also
+        --------
+        pandas_gbq.to_gbq : This function in the pandas-gbq library.
+        read_gbq : Read a DataFrame from Google BigQuery.
+
+        Examples
+        --------
+        Example taken from `Google BigQuery documentation
+        `_
+
+        >>> project_id = "my-project"
+        >>> table_id = 'my_dataset.my_table'
+        >>> df = pd.DataFrame({
+        ...                   "my_string": ["a", "b", "c"],
+        ...                   "my_int64": [1, 2, 3],
+        ...                   "my_float64": [4.0, 5.0, 6.0],
+        ...                   "my_bool1": [True, False, True],
+        ...                   "my_bool2": [False, True, False],
+        ...                   "my_dates": pd.date_range("now", periods=3),
+        ...                   }
+        ...                   )
+
+        >>> df.to_gbq(table_id, project_id=project_id)  # doctest: +SKIP
+        """
+        from pandas.io import gbq
+
+        gbq.to_gbq(
+            self,
+            destination_table,
+            project_id=project_id,
+            chunksize=chunksize,
+            reauth=reauth,
+            if_exists=if_exists,
+            auth_local_webserver=auth_local_webserver,
+            table_schema=table_schema,
+            location=location,
+            progress_bar=progress_bar,
+            credentials=credentials,
+        )
+
+    @classmethod
+    def from_records(
+        cls,
+        data,
+        index=None,
+        exclude=None,
+        columns=None,
+        coerce_float: bool = False,
+        nrows: int | None = None,
+    ) -> DataFrame:
+        """
+        Convert structured or record ndarray to DataFrame.
+
+        Creates a DataFrame object from a structured ndarray, sequence of
+        tuples or dicts, or DataFrame.
+
+        Parameters
+        ----------
+        data : structured ndarray, sequence of tuples or dicts, or DataFrame
+            Structured input data.
+
+            .. deprecated:: 2.1.0
+                Passing a DataFrame is deprecated.
+        index : str, list of fields, array-like
+            Field of array to use as the index, alternately a specific set of
+            input labels to use.
+        exclude : sequence, default None
+            Columns or fields to exclude.
+        columns : sequence, default None
+            Column names to use. If the passed data do not have names
+            associated with them, this argument provides names for the
+            columns. Otherwise this argument indicates the order of the columns
+            in the result (any names not found in the data will become all-NA
+            columns).
+        coerce_float : bool, default False
+            Attempt to convert values of non-string, non-numeric objects (like
+            decimal.Decimal) to floating point, useful for SQL result sets.
+        nrows : int, default None
+            Number of rows to read if data is an iterator.
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        DataFrame.from_dict : DataFrame from dict of array-like or dicts.
+        DataFrame : DataFrame object creation using constructor.
+
+        Examples
+        --------
+        Data can be provided as a structured ndarray:
+
+        >>> data = np.array([(3, 'a'), (2, 'b'), (1, 'c'), (0, 'd')],
+        ...                 dtype=[('col_1', 'i4'), ('col_2', 'U1')])
+        >>> pd.DataFrame.from_records(data)
+           col_1 col_2
+        0      3     a
+        1      2     b
+        2      1     c
+        3      0     d
+
+        Data can be provided as a list of dicts:
+
+        >>> data = [{'col_1': 3, 'col_2': 'a'},
+        ...         {'col_1': 2, 'col_2': 'b'},
+        ...         {'col_1': 1, 'col_2': 'c'},
+        ...         {'col_1': 0, 'col_2': 'd'}]
+        >>> pd.DataFrame.from_records(data)
+           col_1 col_2
+        0      3     a
+        1      2     b
+        2      1     c
+        3      0     d
+
+        Data can be provided as a list of tuples with corresponding columns:
+
+        >>> data = [(3, 'a'), (2, 'b'), (1, 'c'), (0, 'd')]
+        >>> pd.DataFrame.from_records(data, columns=['col_1', 'col_2'])
+           col_1 col_2
+        0      3     a
+        1      2     b
+        2      1     c
+        3      0     d
+        """
+        if isinstance(data, DataFrame):
+            warnings.warn(
+                "Passing a DataFrame to DataFrame.from_records is deprecated. Use "
+                "set_index and/or drop to modify the DataFrame instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            if columns is not None:
+                if is_scalar(columns):
+                    columns = [columns]
+                data = data[columns]
+            if index is not None:
+                data = data.set_index(index)
+            if exclude is not None:
+                data = data.drop(columns=exclude)
+            return data.copy(deep=False)
+
+        result_index = None
+
+        # Make a copy of the input columns so we can modify it
+        if columns is not None:
+            columns = ensure_index(columns)
+
+        def maybe_reorder(
+            arrays: list[ArrayLike], arr_columns: Index, columns: Index, index
+        ) -> tuple[list[ArrayLike], Index, Index | None]:
+            """
+            If our desired 'columns' do not match the data's pre-existing 'arr_columns',
+            we re-order our arrays.  This is like a pre-emptive (cheap) reindex.
+            """
+            if len(arrays):
+                length = len(arrays[0])
+            else:
+                length = 0
+
+            result_index = None
+            if len(arrays) == 0 and index is None and length == 0:
+                result_index = default_index(0)
+
+            arrays, arr_columns = reorder_arrays(arrays, arr_columns, columns, length)
+            return arrays, arr_columns, result_index
+
+        if is_iterator(data):
+            if nrows == 0:
+                return cls()
+
+            try:
+                first_row = next(data)
+            except StopIteration:
+                return cls(index=index, columns=columns)
+
+            dtype = None
+            if hasattr(first_row, "dtype") and first_row.dtype.names:
+                dtype = first_row.dtype
+
+            values = [first_row]
+
+            if nrows is None:
+                values += data
+            else:
+                values.extend(itertools.islice(data, nrows - 1))
+
+            if dtype is not None:
+                data = np.array(values, dtype=dtype)
+            else:
+                data = values
+
+        if isinstance(data, dict):
+            if columns is None:
+                columns = arr_columns = ensure_index(sorted(data))
+                arrays = [data[k] for k in columns]
+            else:
+                arrays = []
+                arr_columns_list = []
+                for k, v in data.items():
+                    if k in columns:
+                        arr_columns_list.append(k)
+                        arrays.append(v)
+
+                arr_columns = Index(arr_columns_list)
+                arrays, arr_columns, result_index = maybe_reorder(
+                    arrays, arr_columns, columns, index
+                )
+
+        elif isinstance(data, np.ndarray):
+            arrays, columns = to_arrays(data, columns)
+            arr_columns = columns
+        else:
+            arrays, arr_columns = to_arrays(data, columns)
+            if coerce_float:
+                for i, arr in enumerate(arrays):
+                    if arr.dtype == object:
+                        # error: Argument 1 to "maybe_convert_objects" has
+                        # incompatible type "Union[ExtensionArray, ndarray]";
+                        # expected "ndarray"
+                        arrays[i] = lib.maybe_convert_objects(
+                            arr,  # type: ignore[arg-type]
+                            try_float=True,
+                        )
+
+            arr_columns = ensure_index(arr_columns)
+            if columns is None:
+                columns = arr_columns
+            else:
+                arrays, arr_columns, result_index = maybe_reorder(
+                    arrays, arr_columns, columns, index
+                )
+
+        if exclude is None:
+            exclude = set()
+        else:
+            exclude = set(exclude)
+
+        if index is not None:
+            if isinstance(index, str) or not hasattr(index, "__iter__"):
+                i = columns.get_loc(index)
+                exclude.add(index)
+                if len(arrays) > 0:
+                    result_index = Index(arrays[i], name=index)
+                else:
+                    result_index = Index([], name=index)
+            else:
+                try:
+                    index_data = [arrays[arr_columns.get_loc(field)] for field in index]
+                except (KeyError, TypeError):
+                    # raised by get_loc, see GH#29258
+                    result_index = index
+                else:
+                    result_index = ensure_index_from_sequences(index_data, names=index)
+                    exclude.update(index)
+
+        if any(exclude):
+            arr_exclude = [x for x in exclude if x in arr_columns]
+            to_remove = [arr_columns.get_loc(col) for col in arr_exclude]
+            arrays = [v for i, v in enumerate(arrays) if i not in to_remove]
+
+            columns = columns.drop(exclude)
+
+        manager = _get_option("mode.data_manager", silent=True)
+        mgr = arrays_to_mgr(arrays, columns, result_index, typ=manager)
+        df = DataFrame._from_mgr(mgr, axes=mgr.axes)
+        if cls is not DataFrame:
+            return cls(df, copy=False)
+        return df
+
+    def to_records(
+        self, index: bool = True, column_dtypes=None, index_dtypes=None
+    ) -> np.rec.recarray:
+        """
+        Convert DataFrame to a NumPy record array.
+
+        Index will be included as the first field of the record array if
+        requested.
+
+        Parameters
+        ----------
+        index : bool, default True
+            Include index in resulting record array, stored in 'index'
+            field or using the index label, if set.
+        column_dtypes : str, type, dict, default None
+            If a string or type, the data type to store all columns. If
+            a dictionary, a mapping of column names and indices (zero-indexed)
+            to specific data types.
+        index_dtypes : str, type, dict, default None
+            If a string or type, the data type to store all index levels. If
+            a dictionary, a mapping of index level names and indices
+            (zero-indexed) to specific data types.
+
+            This mapping is applied only if `index=True`.
+
+        Returns
+        -------
+        numpy.rec.recarray
+            NumPy ndarray with the DataFrame labels as fields and each row
+            of the DataFrame as entries.
+
+        See Also
+        --------
+        DataFrame.from_records: Convert structured or record ndarray
+            to DataFrame.
+        numpy.rec.recarray: An ndarray that allows field access using
+            attributes, analogous to typed columns in a
+            spreadsheet.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [0.5, 0.75]},
+        ...                   index=['a', 'b'])
+        >>> df
+           A     B
+        a  1  0.50
+        b  2  0.75
+        >>> df.to_records()
+        rec.array([('a', 1, 0.5 ), ('b', 2, 0.75)],
+                  dtype=[('index', 'O'), ('A', '>> df.index = df.index.rename("I")
+        >>> df.to_records()
+        rec.array([('a', 1, 0.5 ), ('b', 2, 0.75)],
+                  dtype=[('I', 'O'), ('A', '>> df.to_records(index=False)
+        rec.array([(1, 0.5 ), (2, 0.75)],
+                  dtype=[('A', '>> df.to_records(column_dtypes={"A": "int32"})
+        rec.array([('a', 1, 0.5 ), ('b', 2, 0.75)],
+                  dtype=[('I', 'O'), ('A', '>> df.to_records(index_dtypes=">> index_dtypes = f">> df.to_records(index_dtypes=index_dtypes)
+        rec.array([(b'a', 1, 0.5 ), (b'b', 2, 0.75)],
+                  dtype=[('I', 'S1'), ('A', ' Self:
+        """
+        Create DataFrame from a list of arrays corresponding to the columns.
+
+        Parameters
+        ----------
+        arrays : list-like of arrays
+            Each array in the list corresponds to one column, in order.
+        columns : list-like, Index
+            The column names for the resulting DataFrame.
+        index : list-like, Index
+            The rows labels for the resulting DataFrame.
+        dtype : dtype, optional
+            Optional dtype to enforce for all arrays.
+        verify_integrity : bool, default True
+            Validate and homogenize all input. If set to False, it is assumed
+            that all elements of `arrays` are actual arrays how they will be
+            stored in a block (numpy ndarray or ExtensionArray), have the same
+            length as and are aligned with the index, and that `columns` and
+            `index` are ensured to be an Index object.
+
+        Returns
+        -------
+        DataFrame
+        """
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        manager = _get_option("mode.data_manager", silent=True)
+        columns = ensure_index(columns)
+        if len(columns) != len(arrays):
+            raise ValueError("len(columns) must match len(arrays)")
+        mgr = arrays_to_mgr(
+            arrays,
+            columns,
+            index,
+            dtype=dtype,
+            verify_integrity=verify_integrity,
+            typ=manager,
+        )
+        return cls._from_mgr(mgr, axes=mgr.axes)
+
+    @doc(
+        storage_options=_shared_docs["storage_options"],
+        compression_options=_shared_docs["compression_options"] % "path",
+    )
+    def to_stata(
+        self,
+        path: FilePath | WriteBuffer[bytes],
+        *,
+        convert_dates: dict[Hashable, str] | None = None,
+        write_index: bool = True,
+        byteorder: ToStataByteorder | None = None,
+        time_stamp: datetime.datetime | None = None,
+        data_label: str | None = None,
+        variable_labels: dict[Hashable, str] | None = None,
+        version: int | None = 114,
+        convert_strl: Sequence[Hashable] | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+        value_labels: dict[Hashable, dict[float, str]] | None = None,
+    ) -> None:
+        """
+        Export DataFrame object to Stata dta format.
+
+        Writes the DataFrame to a Stata dataset file.
+        "dta" files contain a Stata dataset.
+
+        Parameters
+        ----------
+        path : str, path object, or buffer
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a binary ``write()`` function.
+
+        convert_dates : dict
+            Dictionary mapping columns containing datetime types to stata
+            internal format to use when writing the dates. Options are 'tc',
+            'td', 'tm', 'tw', 'th', 'tq', 'ty'. Column can be either an integer
+            or a name. Datetime columns that do not have a conversion type
+            specified will be converted to 'tc'. Raises NotImplementedError if
+            a datetime column has timezone information.
+        write_index : bool
+            Write the index to Stata dataset.
+        byteorder : str
+            Can be ">", "<", "little", or "big". default is `sys.byteorder`.
+        time_stamp : datetime
+            A datetime to use as file creation date.  Default is the current
+            time.
+        data_label : str, optional
+            A label for the data set.  Must be 80 characters or smaller.
+        variable_labels : dict
+            Dictionary containing columns as keys and variable labels as
+            values. Each label must be 80 characters or smaller.
+        version : {{114, 117, 118, 119, None}}, default 114
+            Version to use in the output dta file. Set to None to let pandas
+            decide between 118 or 119 formats depending on the number of
+            columns in the frame. Version 114 can be read by Stata 10 and
+            later. Version 117 can be read by Stata 13 or later. Version 118
+            is supported in Stata 14 and later. Version 119 is supported in
+            Stata 15 and later. Version 114 limits string variables to 244
+            characters or fewer while versions 117 and later allow strings
+            with lengths up to 2,000,000 characters. Versions 118 and 119
+            support Unicode characters, and version 119 supports more than
+            32,767 variables.
+
+            Version 119 should usually only be used when the number of
+            variables exceeds the capacity of dta format 118. Exporting
+            smaller datasets in format 119 may have unintended consequences,
+            and, as of November 2020, Stata SE cannot read version 119 files.
+
+        convert_strl : list, optional
+            List of column names to convert to string columns to Stata StrL
+            format. Only available if version is 117.  Storing strings in the
+            StrL format can produce smaller dta files if strings have more than
+            8 characters and values are repeated.
+        {compression_options}
+
+            .. versionchanged:: 1.4.0 Zstandard support.
+
+        {storage_options}
+
+        value_labels : dict of dicts
+            Dictionary containing columns as keys and dictionaries of column value
+            to labels as values. Labels for a single variable must be 32,000
+            characters or smaller.
+
+            .. versionadded:: 1.4.0
+
+        Raises
+        ------
+        NotImplementedError
+            * If datetimes contain timezone information
+            * Column dtype is not representable in Stata
+        ValueError
+            * Columns listed in convert_dates are neither datetime64[ns]
+              or datetime.datetime
+            * Column listed in convert_dates is not in DataFrame
+            * Categorical label contains more than 32,000 characters
+
+        See Also
+        --------
+        read_stata : Import Stata data files.
+        io.stata.StataWriter : Low-level writer for Stata data files.
+        io.stata.StataWriter117 : Low-level writer for version 117 files.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({{'animal': ['falcon', 'parrot', 'falcon',
+        ...                               'parrot'],
+        ...                    'speed': [350, 18, 361, 15]}})
+        >>> df.to_stata('animals.dta')  # doctest: +SKIP
+        """
+        if version not in (114, 117, 118, 119, None):
+            raise ValueError("Only formats 114, 117, 118 and 119 are supported.")
+        if version == 114:
+            if convert_strl is not None:
+                raise ValueError("strl is not supported in format 114")
+            from pandas.io.stata import StataWriter as statawriter
+        elif version == 117:
+            # Incompatible import of "statawriter" (imported name has type
+            # "Type[StataWriter117]", local name has type "Type[StataWriter]")
+            from pandas.io.stata import (  # type: ignore[assignment]
+                StataWriter117 as statawriter,
+            )
+        else:  # versions 118 and 119
+            # Incompatible import of "statawriter" (imported name has type
+            # "Type[StataWriter117]", local name has type "Type[StataWriter]")
+            from pandas.io.stata import (  # type: ignore[assignment]
+                StataWriterUTF8 as statawriter,
+            )
+
+        kwargs: dict[str, Any] = {}
+        if version is None or version >= 117:
+            # strl conversion is only supported >= 117
+            kwargs["convert_strl"] = convert_strl
+        if version is None or version >= 118:
+            # Specifying the version is only supported for UTF8 (118 or 119)
+            kwargs["version"] = version
+
+        writer = statawriter(
+            path,
+            self,
+            convert_dates=convert_dates,
+            byteorder=byteorder,
+            time_stamp=time_stamp,
+            data_label=data_label,
+            write_index=write_index,
+            variable_labels=variable_labels,
+            compression=compression,
+            storage_options=storage_options,
+            value_labels=value_labels,
+            **kwargs,
+        )
+        writer.write_file()
+
+    def to_feather(self, path: FilePath | WriteBuffer[bytes], **kwargs) -> None:
+        """
+        Write a DataFrame to the binary Feather format.
+
+        Parameters
+        ----------
+        path : str, path object, file-like object
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a binary ``write()`` function. If a string or a path,
+            it will be used as Root Directory path when writing a partitioned dataset.
+        **kwargs :
+            Additional keywords passed to :func:`pyarrow.feather.write_feather`.
+            This includes the `compression`, `compression_level`, `chunksize`
+            and `version` keywords.
+
+        Notes
+        -----
+        This function writes the dataframe as a `feather file
+        `_. Requires a default
+        index. For saving the DataFrame with your custom index use a method that
+        supports custom indices e.g. `to_parquet`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]])
+        >>> df.to_feather("file.feather")  # doctest: +SKIP
+        """
+        from pandas.io.feather_format import to_feather
+
+        to_feather(self, path, **kwargs)
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "buf"], name="to_markdown"
+    )
+    @doc(
+        Series.to_markdown,
+        klass=_shared_doc_kwargs["klass"],
+        storage_options=_shared_docs["storage_options"],
+        examples="""Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     data={"animal_1": ["elk", "pig"], "animal_2": ["dog", "quetzal"]}
+        ... )
+        >>> print(df.to_markdown())
+        |    | animal_1   | animal_2   |
+        |---:|:-----------|:-----------|
+        |  0 | elk        | dog        |
+        |  1 | pig        | quetzal    |
+
+        Output markdown with a tabulate option.
+
+        >>> print(df.to_markdown(tablefmt="grid"))
+        +----+------------+------------+
+        |    | animal_1   | animal_2   |
+        +====+============+============+
+        |  0 | elk        | dog        |
+        +----+------------+------------+
+        |  1 | pig        | quetzal    |
+        +----+------------+------------+""",
+    )
+    def to_markdown(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        mode: str = "wt",
+        index: bool = True,
+        storage_options: StorageOptions | None = None,
+        **kwargs,
+    ) -> str | None:
+        if "showindex" in kwargs:
+            raise ValueError("Pass 'index' instead of 'showindex")
+
+        kwargs.setdefault("headers", "keys")
+        kwargs.setdefault("tablefmt", "pipe")
+        kwargs.setdefault("showindex", index)
+        tabulate = import_optional_dependency("tabulate")
+        result = tabulate.tabulate(self, **kwargs)
+        if buf is None:
+            return result
+
+        with get_handle(buf, mode, storage_options=storage_options) as handles:
+            handles.handle.write(result)
+        return None
+
+    @overload
+    def to_parquet(
+        self,
+        path: None = ...,
+        engine: Literal["auto", "pyarrow", "fastparquet"] = ...,
+        compression: str | None = ...,
+        index: bool | None = ...,
+        partition_cols: list[str] | None = ...,
+        storage_options: StorageOptions = ...,
+        **kwargs,
+    ) -> bytes:
+        ...
+
+    @overload
+    def to_parquet(
+        self,
+        path: FilePath | WriteBuffer[bytes],
+        engine: Literal["auto", "pyarrow", "fastparquet"] = ...,
+        compression: str | None = ...,
+        index: bool | None = ...,
+        partition_cols: list[str] | None = ...,
+        storage_options: StorageOptions = ...,
+        **kwargs,
+    ) -> None:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path"], name="to_parquet"
+    )
+    @doc(storage_options=_shared_docs["storage_options"])
+    def to_parquet(
+        self,
+        path: FilePath | WriteBuffer[bytes] | None = None,
+        engine: Literal["auto", "pyarrow", "fastparquet"] = "auto",
+        compression: str | None = "snappy",
+        index: bool | None = None,
+        partition_cols: list[str] | None = None,
+        storage_options: StorageOptions | None = None,
+        **kwargs,
+    ) -> bytes | None:
+        """
+        Write a DataFrame to the binary parquet format.
+
+        This function writes the dataframe as a `parquet file
+        `_. You can choose different parquet
+        backends, and have the option of compression. See
+        :ref:`the user guide ` for more details.
+
+        Parameters
+        ----------
+        path : str, path object, file-like object, or None, default None
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a binary ``write()`` function. If None, the result is
+            returned as bytes. If a string or path, it will be used as Root Directory
+            path when writing a partitioned dataset.
+        engine : {{'auto', 'pyarrow', 'fastparquet'}}, default 'auto'
+            Parquet library to use. If 'auto', then the option
+            ``io.parquet.engine`` is used. The default ``io.parquet.engine``
+            behavior is to try 'pyarrow', falling back to 'fastparquet' if
+            'pyarrow' is unavailable.
+        compression : str or None, default 'snappy'
+            Name of the compression to use. Use ``None`` for no compression.
+            Supported options: 'snappy', 'gzip', 'brotli', 'lz4', 'zstd'.
+        index : bool, default None
+            If ``True``, include the dataframe's index(es) in the file output.
+            If ``False``, they will not be written to the file.
+            If ``None``, similar to ``True`` the dataframe's index(es)
+            will be saved. However, instead of being saved as values,
+            the RangeIndex will be stored as a range in the metadata so it
+            doesn't require much space and is faster. Other indexes will
+            be included as columns in the file output.
+        partition_cols : list, optional, default None
+            Column names by which to partition the dataset.
+            Columns are partitioned in the order they are given.
+            Must be None if path is not a string.
+        {storage_options}
+
+        **kwargs
+            Additional arguments passed to the parquet library. See
+            :ref:`pandas io ` for more details.
+
+        Returns
+        -------
+        bytes if no path argument is provided else None
+
+        See Also
+        --------
+        read_parquet : Read a parquet file.
+        DataFrame.to_orc : Write an orc file.
+        DataFrame.to_csv : Write a csv file.
+        DataFrame.to_sql : Write to a sql table.
+        DataFrame.to_hdf : Write to hdf.
+
+        Notes
+        -----
+        This function requires either the `fastparquet
+        `_ or `pyarrow
+        `_ library.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(data={{'col1': [1, 2], 'col2': [3, 4]}})
+        >>> df.to_parquet('df.parquet.gzip',
+        ...               compression='gzip')  # doctest: +SKIP
+        >>> pd.read_parquet('df.parquet.gzip')  # doctest: +SKIP
+           col1  col2
+        0     1     3
+        1     2     4
+
+        If you want to get a buffer to the parquet content you can use a io.BytesIO
+        object, as long as you don't use partition_cols, which creates multiple files.
+
+        >>> import io
+        >>> f = io.BytesIO()
+        >>> df.to_parquet(f)
+        >>> f.seek(0)
+        0
+        >>> content = f.read()
+        """
+        from pandas.io.parquet import to_parquet
+
+        return to_parquet(
+            self,
+            path,
+            engine,
+            compression=compression,
+            index=index,
+            partition_cols=partition_cols,
+            storage_options=storage_options,
+            **kwargs,
+        )
+
+    def to_orc(
+        self,
+        path: FilePath | WriteBuffer[bytes] | None = None,
+        *,
+        engine: Literal["pyarrow"] = "pyarrow",
+        index: bool | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+    ) -> bytes | None:
+        """
+        Write a DataFrame to the ORC format.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        path : str, file-like object or None, default None
+            If a string, it will be used as Root Directory path
+            when writing a partitioned dataset. By file-like object,
+            we refer to objects with a write() method, such as a file handle
+            (e.g. via builtin open function). If path is None,
+            a bytes object is returned.
+        engine : {'pyarrow'}, default 'pyarrow'
+            ORC library to use.
+        index : bool, optional
+            If ``True``, include the dataframe's index(es) in the file output.
+            If ``False``, they will not be written to the file.
+            If ``None``, similar to ``infer`` the dataframe's index(es)
+            will be saved. However, instead of being saved as values,
+            the RangeIndex will be stored as a range in the metadata so it
+            doesn't require much space and is faster. Other indexes will
+            be included as columns in the file output.
+        engine_kwargs : dict[str, Any] or None, default None
+            Additional keyword arguments passed to :func:`pyarrow.orc.write_table`.
+
+        Returns
+        -------
+        bytes if no path argument is provided else None
+
+        Raises
+        ------
+        NotImplementedError
+            Dtype of one or more columns is category, unsigned integers, interval,
+            period or sparse.
+        ValueError
+            engine is not pyarrow.
+
+        See Also
+        --------
+        read_orc : Read a ORC file.
+        DataFrame.to_parquet : Write a parquet file.
+        DataFrame.to_csv : Write a csv file.
+        DataFrame.to_sql : Write to a sql table.
+        DataFrame.to_hdf : Write to hdf.
+
+        Notes
+        -----
+        * Before using this function you should read the :ref:`user guide about
+          ORC ` and :ref:`install optional dependencies `.
+        * This function requires `pyarrow `_
+          library.
+        * For supported dtypes please refer to `supported ORC features in Arrow
+          `__.
+        * Currently timezones in datetime columns are not preserved when a
+          dataframe is converted into ORC files.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [4, 3]})
+        >>> df.to_orc('df.orc')  # doctest: +SKIP
+        >>> pd.read_orc('df.orc')  # doctest: +SKIP
+           col1  col2
+        0     1     4
+        1     2     3
+
+        If you want to get a buffer to the orc content you can write it to io.BytesIO
+
+        >>> import io
+        >>> b = io.BytesIO(df.to_orc())  # doctest: +SKIP
+        >>> b.seek(0)  # doctest: +SKIP
+        0
+        >>> content = b.read()  # doctest: +SKIP
+        """
+        from pandas.io.orc import to_orc
+
+        return to_orc(
+            self, path, engine=engine, index=index, engine_kwargs=engine_kwargs
+        )
+
+    @overload
+    def to_html(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        columns: Axes | None = ...,
+        col_space: ColspaceArgType | None = ...,
+        header: bool = ...,
+        index: bool = ...,
+        na_rep: str = ...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
+        sparsify: bool | None = ...,
+        index_names: bool = ...,
+        justify: str | None = ...,
+        max_rows: int | None = ...,
+        max_cols: int | None = ...,
+        show_dimensions: bool | str = ...,
+        decimal: str = ...,
+        bold_rows: bool = ...,
+        classes: str | list | tuple | None = ...,
+        escape: bool = ...,
+        notebook: bool = ...,
+        border: int | bool | None = ...,
+        table_id: str | None = ...,
+        render_links: bool = ...,
+        encoding: str | None = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def to_html(
+        self,
+        buf: None = ...,
+        columns: Axes | None = ...,
+        col_space: ColspaceArgType | None = ...,
+        header: bool = ...,
+        index: bool = ...,
+        na_rep: str = ...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
+        sparsify: bool | None = ...,
+        index_names: bool = ...,
+        justify: str | None = ...,
+        max_rows: int | None = ...,
+        max_cols: int | None = ...,
+        show_dimensions: bool | str = ...,
+        decimal: str = ...,
+        bold_rows: bool = ...,
+        classes: str | list | tuple | None = ...,
+        escape: bool = ...,
+        notebook: bool = ...,
+        border: int | bool | None = ...,
+        table_id: str | None = ...,
+        render_links: bool = ...,
+        encoding: str | None = ...,
+    ) -> str:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "buf"], name="to_html"
+    )
+    @Substitution(
+        header_type="bool",
+        header="Whether to print column labels, default True",
+        col_space_type="str or int, list or dict of int or str",
+        col_space="The minimum width of each column in CSS length "
+        "units.  An int is assumed to be px units.",
+    )
+    @Substitution(shared_params=fmt.common_docstring, returns=fmt.return_docstring)
+    def to_html(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        columns: Axes | None = None,
+        col_space: ColspaceArgType | None = None,
+        header: bool = True,
+        index: bool = True,
+        na_rep: str = "NaN",
+        formatters: FormattersType | None = None,
+        float_format: FloatFormatType | None = None,
+        sparsify: bool | None = None,
+        index_names: bool = True,
+        justify: str | None = None,
+        max_rows: int | None = None,
+        max_cols: int | None = None,
+        show_dimensions: bool | str = False,
+        decimal: str = ".",
+        bold_rows: bool = True,
+        classes: str | list | tuple | None = None,
+        escape: bool = True,
+        notebook: bool = False,
+        border: int | bool | None = None,
+        table_id: str | None = None,
+        render_links: bool = False,
+        encoding: str | None = None,
+    ) -> str | None:
+        """
+        Render a DataFrame as an HTML table.
+        %(shared_params)s
+        bold_rows : bool, default True
+            Make the row labels bold in the output.
+        classes : str or list or tuple, default None
+            CSS class(es) to apply to the resulting html table.
+        escape : bool, default True
+            Convert the characters <, >, and & to HTML-safe sequences.
+        notebook : {True, False}, default False
+            Whether the generated HTML is for IPython Notebook.
+        border : int
+            A ``border=border`` attribute is included in the opening
+            `` tag. Default ``pd.options.display.html.border``.
+        table_id : str, optional
+            A css id is included in the opening `
` tag if specified.
+        render_links : bool, default False
+            Convert URLs to HTML links.
+        encoding : str, default "utf-8"
+            Set character encoding.
+        %(returns)s
+        See Also
+        --------
+        to_string : Convert DataFrame to a string.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(data={'col1': [1, 2], 'col2': [4, 3]})
+        >>> html_string = '''

+        ...   
+        ...     
+        ...       
+        ...       
+        ...       
+        ...     
+        ...   
+        ...   
+        ...     
+        ...       
+        ...       
+        ...       
+        ...     
+        ...     
+        ...       
+        ...       
+        ...       
+        ...     
+        ...   
+        ... 
col1col2
014
123
'''
+        >>> assert html_string == df.to_html()
+        """
+        if justify is not None and justify not in fmt.VALID_JUSTIFY_PARAMETERS:
+            raise ValueError("Invalid value for justify parameter")
+
+        formatter = fmt.DataFrameFormatter(
+            self,
+            columns=columns,
+            col_space=col_space,
+            na_rep=na_rep,
+            header=header,
+            index=index,
+            formatters=formatters,
+            float_format=float_format,
+            bold_rows=bold_rows,
+            sparsify=sparsify,
+            justify=justify,
+            index_names=index_names,
+            escape=escape,
+            decimal=decimal,
+            max_rows=max_rows,
+            max_cols=max_cols,
+            show_dimensions=show_dimensions,
+        )
+        # TODO: a generic formatter wld b in DataFrameFormatter
+        return fmt.DataFrameRenderer(formatter).to_html(
+            buf=buf,
+            classes=classes,
+            notebook=notebook,
+            border=border,
+            encoding=encoding,
+            table_id=table_id,
+            render_links=render_links,
+        )
+
+    @overload
+    def to_xml(
+        self,
+        path_or_buffer: None = ...,
+        *,
+        index: bool = ...,
+        root_name: str | None = ...,
+        row_name: str | None = ...,
+        na_rep: str | None = ...,
+        attr_cols: list[str] | None = ...,
+        elem_cols: list[str] | None = ...,
+        namespaces: dict[str | None, str] | None = ...,
+        prefix: str | None = ...,
+        encoding: str = ...,
+        xml_declaration: bool | None = ...,
+        pretty_print: bool | None = ...,
+        parser: XMLParsers | None = ...,
+        stylesheet: FilePath | ReadBuffer[str] | ReadBuffer[bytes] | None = ...,
+        compression: CompressionOptions = ...,
+        storage_options: StorageOptions | None = ...,
+    ) -> str:
+        ...
+
+    @overload
+    def to_xml(
+        self,
+        path_or_buffer: FilePath | WriteBuffer[bytes] | WriteBuffer[str],
+        *,
+        index: bool = ...,
+        root_name: str | None = ...,
+        row_name: str | None = ...,
+        na_rep: str | None = ...,
+        attr_cols: list[str] | None = ...,
+        elem_cols: list[str] | None = ...,
+        namespaces: dict[str | None, str] | None = ...,
+        prefix: str | None = ...,
+        encoding: str = ...,
+        xml_declaration: bool | None = ...,
+        pretty_print: bool | None = ...,
+        parser: XMLParsers | None = ...,
+        stylesheet: FilePath | ReadBuffer[str] | ReadBuffer[bytes] | None = ...,
+        compression: CompressionOptions = ...,
+        storage_options: StorageOptions | None = ...,
+    ) -> None:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path_or_buffer"], name="to_xml"
+    )
+    @doc(
+        storage_options=_shared_docs["storage_options"],
+        compression_options=_shared_docs["compression_options"] % "path_or_buffer",
+    )
+    def to_xml(
+        self,
+        path_or_buffer: FilePath | WriteBuffer[bytes] | WriteBuffer[str] | None = None,
+        index: bool = True,
+        root_name: str | None = "data",
+        row_name: str | None = "row",
+        na_rep: str | None = None,
+        attr_cols: list[str] | None = None,
+        elem_cols: list[str] | None = None,
+        namespaces: dict[str | None, str] | None = None,
+        prefix: str | None = None,
+        encoding: str = "utf-8",
+        xml_declaration: bool | None = True,
+        pretty_print: bool | None = True,
+        parser: XMLParsers | None = "lxml",
+        stylesheet: FilePath | ReadBuffer[str] | ReadBuffer[bytes] | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+    ) -> str | None:
+        """
+        Render a DataFrame to an XML document.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        path_or_buffer : str, path object, file-like object, or None, default None
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a ``write()`` function. If None, the result is returned
+            as a string.
+        index : bool, default True
+            Whether to include index in XML document.
+        root_name : str, default 'data'
+            The name of root element in XML document.
+        row_name : str, default 'row'
+            The name of row element in XML document.
+        na_rep : str, optional
+            Missing data representation.
+        attr_cols : list-like, optional
+            List of columns to write as attributes in row element.
+            Hierarchical columns will be flattened with underscore
+            delimiting the different levels.
+        elem_cols : list-like, optional
+            List of columns to write as children in row element. By default,
+            all columns output as children of row element. Hierarchical
+            columns will be flattened with underscore delimiting the
+            different levels.
+        namespaces : dict, optional
+            All namespaces to be defined in root element. Keys of dict
+            should be prefix names and values of dict corresponding URIs.
+            Default namespaces should be given empty string key. For
+            example, ::
+
+                namespaces = {{"": "https://example.com"}}
+
+        prefix : str, optional
+            Namespace prefix to be used for every element and/or attribute
+            in document. This should be one of the keys in ``namespaces``
+            dict.
+        encoding : str, default 'utf-8'
+            Encoding of the resulting document.
+        xml_declaration : bool, default True
+            Whether to include the XML declaration at start of document.
+        pretty_print : bool, default True
+            Whether output should be pretty printed with indentation and
+            line breaks.
+        parser : {{'lxml','etree'}}, default 'lxml'
+            Parser module to use for building of tree. Only 'lxml' and
+            'etree' are supported. With 'lxml', the ability to use XSLT
+            stylesheet is supported.
+        stylesheet : str, path object or file-like object, optional
+            A URL, file-like object, or a raw string containing an XSLT
+            script used to transform the raw XML output. Script should use
+            layout of elements and attributes from original output. This
+            argument requires ``lxml`` to be installed. Only XSLT 1.0
+            scripts and not later versions is currently supported.
+        {compression_options}
+
+            .. versionchanged:: 1.4.0 Zstandard support.
+
+        {storage_options}
+
+        Returns
+        -------
+        None or str
+            If ``io`` is None, returns the resulting XML format as a
+            string. Otherwise returns None.
+
+        See Also
+        --------
+        to_json : Convert the pandas object to a JSON string.
+        to_html : Convert DataFrame to a html.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({{'shape': ['square', 'circle', 'triangle'],
+        ...                    'degrees': [360, 360, 180],
+        ...                    'sides': [4, np.nan, 3]}})
+
+        >>> df.to_xml()  # doctest: +SKIP
+        
+        
+          
+            0
+            square
+            360
+            4.0
+          
+          
+            1
+            circle
+            360
+            
+          
+          
+            2
+            triangle
+            180
+            3.0
+          
+        
+
+        >>> df.to_xml(attr_cols=[
+        ...           'index', 'shape', 'degrees', 'sides'
+        ...           ])  # doctest: +SKIP
+        
+        
+          
+          
+          
+        
+
+        >>> df.to_xml(namespaces={{"doc": "https://example.com"}},
+        ...           prefix="doc")  # doctest: +SKIP
+        
+        
+          
+            0
+            square
+            360
+            4.0
+          
+          
+            1
+            circle
+            360
+            
+          
+          
+            2
+            triangle
+            180
+            3.0
+          
+        
+        """
+
+        from pandas.io.formats.xml import (
+            EtreeXMLFormatter,
+            LxmlXMLFormatter,
+        )
+
+        lxml = import_optional_dependency("lxml.etree", errors="ignore")
+
+        TreeBuilder: type[EtreeXMLFormatter | LxmlXMLFormatter]
+
+        if parser == "lxml":
+            if lxml is not None:
+                TreeBuilder = LxmlXMLFormatter
+            else:
+                raise ImportError(
+                    "lxml not found, please install or use the etree parser."
+                )
+
+        elif parser == "etree":
+            TreeBuilder = EtreeXMLFormatter
+
+        else:
+            raise ValueError("Values for parser can only be lxml or etree.")
+
+        xml_formatter = TreeBuilder(
+            self,
+            path_or_buffer=path_or_buffer,
+            index=index,
+            root_name=root_name,
+            row_name=row_name,
+            na_rep=na_rep,
+            attr_cols=attr_cols,
+            elem_cols=elem_cols,
+            namespaces=namespaces,
+            prefix=prefix,
+            encoding=encoding,
+            xml_declaration=xml_declaration,
+            pretty_print=pretty_print,
+            stylesheet=stylesheet,
+            compression=compression,
+            storage_options=storage_options,
+        )
+
+        return xml_formatter.write_output()
+
+    # ----------------------------------------------------------------------
+    @doc(INFO_DOCSTRING, **frame_sub_kwargs)
+    def info(
+        self,
+        verbose: bool | None = None,
+        buf: WriteBuffer[str] | None = None,
+        max_cols: int | None = None,
+        memory_usage: bool | str | None = None,
+        show_counts: bool | None = None,
+    ) -> None:
+        info = DataFrameInfo(
+            data=self,
+            memory_usage=memory_usage,
+        )
+        info.render(
+            buf=buf,
+            max_cols=max_cols,
+            verbose=verbose,
+            show_counts=show_counts,
+        )
+
+    def memory_usage(self, index: bool = True, deep: bool = False) -> Series:
+        """
+        Return the memory usage of each column in bytes.
+
+        The memory usage can optionally include the contribution of
+        the index and elements of `object` dtype.
+
+        This value is displayed in `DataFrame.info` by default. This can be
+        suppressed by setting ``pandas.options.display.memory_usage`` to False.
+
+        Parameters
+        ----------
+        index : bool, default True
+            Specifies whether to include the memory usage of the DataFrame's
+            index in returned Series. If ``index=True``, the memory usage of
+            the index is the first item in the output.
+        deep : bool, default False
+            If True, introspect the data deeply by interrogating
+            `object` dtypes for system-level memory consumption, and include
+            it in the returned values.
+
+        Returns
+        -------
+        Series
+            A Series whose index is the original column names and whose values
+            is the memory usage of each column in bytes.
+
+        See Also
+        --------
+        numpy.ndarray.nbytes : Total bytes consumed by the elements of an
+            ndarray.
+        Series.memory_usage : Bytes consumed by a Series.
+        Categorical : Memory-efficient array for string values with
+            many repeated values.
+        DataFrame.info : Concise summary of a DataFrame.
+
+        Notes
+        -----
+        See the :ref:`Frequently Asked Questions ` for more
+        details.
+
+        Examples
+        --------
+        >>> dtypes = ['int64', 'float64', 'complex128', 'object', 'bool']
+        >>> data = dict([(t, np.ones(shape=5000, dtype=int).astype(t))
+        ...              for t in dtypes])
+        >>> df = pd.DataFrame(data)
+        >>> df.head()
+           int64  float64            complex128  object  bool
+        0      1      1.0              1.0+0.0j       1  True
+        1      1      1.0              1.0+0.0j       1  True
+        2      1      1.0              1.0+0.0j       1  True
+        3      1      1.0              1.0+0.0j       1  True
+        4      1      1.0              1.0+0.0j       1  True
+
+        >>> df.memory_usage()
+        Index           128
+        int64         40000
+        float64       40000
+        complex128    80000
+        object        40000
+        bool           5000
+        dtype: int64
+
+        >>> df.memory_usage(index=False)
+        int64         40000
+        float64       40000
+        complex128    80000
+        object        40000
+        bool           5000
+        dtype: int64
+
+        The memory footprint of `object` dtype columns is ignored by default:
+
+        >>> df.memory_usage(deep=True)
+        Index            128
+        int64          40000
+        float64        40000
+        complex128     80000
+        object        180000
+        bool            5000
+        dtype: int64
+
+        Use a Categorical for efficient storage of an object-dtype column with
+        many repeated values.
+
+        >>> df['object'].astype('category').memory_usage(deep=True)
+        5244
+        """
+        result = self._constructor_sliced(
+            [c.memory_usage(index=False, deep=deep) for col, c in self.items()],
+            index=self.columns,
+            dtype=np.intp,
+        )
+        if index:
+            index_memory_usage = self._constructor_sliced(
+                self.index.memory_usage(deep=deep), index=["Index"]
+            )
+            result = index_memory_usage._append(result)
+        return result
+
+    def transpose(self, *args, copy: bool = False) -> DataFrame:
+        """
+        Transpose index and columns.
+
+        Reflect the DataFrame over its main diagonal by writing rows as columns
+        and vice-versa. The property :attr:`.T` is an accessor to the method
+        :meth:`transpose`.
+
+        Parameters
+        ----------
+        *args : tuple, optional
+            Accepted for compatibility with NumPy.
+        copy : bool, default False
+            Whether to copy the data after transposing, even for DataFrames
+            with a single dtype.
+
+            Note that a copy is always required for mixed dtype DataFrames,
+            or for DataFrames with any extension types.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        DataFrame
+            The transposed DataFrame.
+
+        See Also
+        --------
+        numpy.transpose : Permute the dimensions of a given array.
+
+        Notes
+        -----
+        Transposing a DataFrame with mixed dtypes will result in a homogeneous
+        DataFrame with the `object` dtype. In such a case, a copy of the data
+        is always made.
+
+        Examples
+        --------
+        **Square DataFrame with homogeneous dtype**
+
+        >>> d1 = {'col1': [1, 2], 'col2': [3, 4]}
+        >>> df1 = pd.DataFrame(data=d1)
+        >>> df1
+           col1  col2
+        0     1     3
+        1     2     4
+
+        >>> df1_transposed = df1.T  # or df1.transpose()
+        >>> df1_transposed
+              0  1
+        col1  1  2
+        col2  3  4
+
+        When the dtype is homogeneous in the original DataFrame, we get a
+        transposed DataFrame with the same dtype:
+
+        >>> df1.dtypes
+        col1    int64
+        col2    int64
+        dtype: object
+        >>> df1_transposed.dtypes
+        0    int64
+        1    int64
+        dtype: object
+
+        **Non-square DataFrame with mixed dtypes**
+
+        >>> d2 = {'name': ['Alice', 'Bob'],
+        ...       'score': [9.5, 8],
+        ...       'employed': [False, True],
+        ...       'kids': [0, 0]}
+        >>> df2 = pd.DataFrame(data=d2)
+        >>> df2
+            name  score  employed  kids
+        0  Alice    9.5     False     0
+        1    Bob    8.0      True     0
+
+        >>> df2_transposed = df2.T  # or df2.transpose()
+        >>> df2_transposed
+                      0     1
+        name      Alice   Bob
+        score       9.5   8.0
+        employed  False  True
+        kids          0     0
+
+        When the DataFrame has mixed dtypes, we get a transposed DataFrame with
+        the `object` dtype:
+
+        >>> df2.dtypes
+        name         object
+        score       float64
+        employed       bool
+        kids          int64
+        dtype: object
+        >>> df2_transposed.dtypes
+        0    object
+        1    object
+        dtype: object
+        """
+        nv.validate_transpose(args, {})
+        # construct the args
+
+        dtypes = list(self.dtypes)
+
+        if self._can_fast_transpose:
+            # Note: tests pass without this, but this improves perf quite a bit.
+            new_vals = self._values.T
+            if copy and not using_copy_on_write():
+                new_vals = new_vals.copy()
+
+            result = self._constructor(
+                new_vals,
+                index=self.columns,
+                columns=self.index,
+                copy=False,
+                dtype=new_vals.dtype,
+            )
+            if using_copy_on_write() and len(self) > 0:
+                result._mgr.add_references(self._mgr)  # type: ignore[arg-type]
+
+        elif (
+            self._is_homogeneous_type
+            and dtypes
+            and isinstance(dtypes[0], ExtensionDtype)
+        ):
+            new_values: list
+            if isinstance(dtypes[0], BaseMaskedDtype):
+                # We have masked arrays with the same dtype. We can transpose faster.
+                from pandas.core.arrays.masked import (
+                    transpose_homogeneous_masked_arrays,
+                )
+
+                new_values = transpose_homogeneous_masked_arrays(
+                    cast(Sequence[BaseMaskedArray], self._iter_column_arrays())
+                )
+            elif isinstance(dtypes[0], ArrowDtype):
+                # We have arrow EAs with the same dtype. We can transpose faster.
+                from pandas.core.arrays.arrow.array import (
+                    ArrowExtensionArray,
+                    transpose_homogeneous_pyarrow,
+                )
+
+                new_values = transpose_homogeneous_pyarrow(
+                    cast(Sequence[ArrowExtensionArray], self._iter_column_arrays())
+                )
+            else:
+                # We have other EAs with the same dtype. We preserve dtype in transpose.
+                dtyp = dtypes[0]
+                arr_typ = dtyp.construct_array_type()
+                values = self.values
+                new_values = [arr_typ._from_sequence(row, dtype=dtyp) for row in values]
+
+            result = type(self)._from_arrays(
+                new_values,
+                index=self.columns,
+                columns=self.index,
+                verify_integrity=False,
+            )
+
+        else:
+            new_arr = self.values.T
+            if copy and not using_copy_on_write():
+                new_arr = new_arr.copy()
+            result = self._constructor(
+                new_arr,
+                index=self.columns,
+                columns=self.index,
+                dtype=new_arr.dtype,
+                # We already made a copy (more than one block)
+                copy=False,
+            )
+
+        return result.__finalize__(self, method="transpose")
+
+    @property
+    def T(self) -> DataFrame:
+        """
+        The transpose of the DataFrame.
+
+        Returns
+        -------
+        DataFrame
+            The transposed DataFrame.
+
+        See Also
+        --------
+        DataFrame.transpose : Transpose index and columns.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df
+           col1  col2
+        0     1     3
+        1     2     4
+
+        >>> df.T
+              0  1
+        col1  1  2
+        col2  3  4
+        """
+        return self.transpose()
+
+    # ----------------------------------------------------------------------
+    # Indexing Methods
+
+    def _ixs(self, i: int, axis: AxisInt = 0) -> Series:
+        """
+        Parameters
+        ----------
+        i : int
+        axis : int
+
+        Returns
+        -------
+        Series
+        """
+        # irow
+        if axis == 0:
+            new_mgr = self._mgr.fast_xs(i)
+
+            # if we are a copy, mark as such
+            copy = isinstance(new_mgr.array, np.ndarray) and new_mgr.array.base is None
+            result = self._constructor_sliced_from_mgr(new_mgr, axes=new_mgr.axes)
+            result._name = self.index[i]
+            result = result.__finalize__(self)
+            result._set_is_copy(self, copy=copy)
+            return result
+
+        # icol
+        else:
+            label = self.columns[i]
+
+            col_mgr = self._mgr.iget(i)
+            result = self._box_col_values(col_mgr, i)
+
+            # this is a cached value, mark it so
+            result._set_as_cached(label, self)
+            return result
+
+    def _get_column_array(self, i: int) -> ArrayLike:
+        """
+        Get the values of the i'th column (ndarray or ExtensionArray, as stored
+        in the Block)
+
+        Warning! The returned array is a view but doesn't handle Copy-on-Write,
+        so this should be used with caution (for read-only purposes).
+        """
+        return self._mgr.iget_values(i)
+
+    def _iter_column_arrays(self) -> Iterator[ArrayLike]:
+        """
+        Iterate over the arrays of all columns in order.
+        This returns the values as stored in the Block (ndarray or ExtensionArray).
+
+        Warning! The returned array is a view but doesn't handle Copy-on-Write,
+        so this should be used with caution (for read-only purposes).
+        """
+        if isinstance(self._mgr, ArrayManager):
+            yield from self._mgr.arrays
+        else:
+            for i in range(len(self.columns)):
+                yield self._get_column_array(i)
+
+    def _getitem_nocopy(self, key: list):
+        """
+        Behaves like __getitem__, but returns a view in cases where __getitem__
+        would make a copy.
+        """
+        # TODO(CoW): can be removed if/when we are always Copy-on-Write
+        indexer = self.columns._get_indexer_strict(key, "columns")[1]
+        new_axis = self.columns[indexer]
+
+        new_mgr = self._mgr.reindex_indexer(
+            new_axis,
+            indexer,
+            axis=0,
+            allow_dups=True,
+            copy=False,
+            only_slice=True,
+        )
+        result = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        result = result.__finalize__(self)
+        return result
+
+    def __getitem__(self, key):
+        check_dict_or_set_indexers(key)
+        key = lib.item_from_zerodim(key)
+        key = com.apply_if_callable(key, self)
+
+        if is_hashable(key) and not is_iterator(key):
+            # is_iterator to exclude generator e.g. test_getitem_listlike
+            # shortcut if the key is in columns
+            is_mi = isinstance(self.columns, MultiIndex)
+            # GH#45316 Return view if key is not duplicated
+            # Only use drop_duplicates with duplicates for performance
+            if not is_mi and (
+                self.columns.is_unique
+                and key in self.columns
+                or key in self.columns.drop_duplicates(keep=False)
+            ):
+                return self._get_item_cache(key)
+
+            elif is_mi and self.columns.is_unique and key in self.columns:
+                return self._getitem_multilevel(key)
+
+        # Do we have a slicer (on rows)?
+        if isinstance(key, slice):
+            return self._getitem_slice(key)
+
+        # Do we have a (boolean) DataFrame?
+        if isinstance(key, DataFrame):
+            return self.where(key)
+
+        # Do we have a (boolean) 1d indexer?
+        if com.is_bool_indexer(key):
+            return self._getitem_bool_array(key)
+
+        # We are left with two options: a single key, and a collection of keys,
+        # We interpret tuples as collections only for non-MultiIndex
+        is_single_key = isinstance(key, tuple) or not is_list_like(key)
+
+        if is_single_key:
+            if self.columns.nlevels > 1:
+                return self._getitem_multilevel(key)
+            indexer = self.columns.get_loc(key)
+            if is_integer(indexer):
+                indexer = [indexer]
+        else:
+            if is_iterator(key):
+                key = list(key)
+            indexer = self.columns._get_indexer_strict(key, "columns")[1]
+
+        # take() does not accept boolean indexers
+        if getattr(indexer, "dtype", None) == bool:
+            indexer = np.where(indexer)[0]
+
+        if isinstance(indexer, slice):
+            return self._slice(indexer, axis=1)
+
+        data = self._take_with_is_copy(indexer, axis=1)
+
+        if is_single_key:
+            # What does looking for a single key in a non-unique index return?
+            # The behavior is inconsistent. It returns a Series, except when
+            # - the key itself is repeated (test on data.shape, #9519), or
+            # - we have a MultiIndex on columns (test on self.columns, #21309)
+            if data.shape[1] == 1 and not isinstance(self.columns, MultiIndex):
+                # GH#26490 using data[key] can cause RecursionError
+                return data._get_item_cache(key)
+
+        return data
+
+    def _getitem_bool_array(self, key):
+        # also raises Exception if object array with NA values
+        # warning here just in case -- previously __setitem__ was
+        # reindexing but __getitem__ was not; it seems more reasonable to
+        # go with the __setitem__ behavior since that is more consistent
+        # with all other indexing behavior
+        if isinstance(key, Series) and not key.index.equals(self.index):
+            warnings.warn(
+                "Boolean Series key will be reindexed to match DataFrame index.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+        elif len(key) != len(self.index):
+            raise ValueError(
+                f"Item wrong length {len(key)} instead of {len(self.index)}."
+            )
+
+        # check_bool_indexer will throw exception if Series key cannot
+        # be reindexed to match DataFrame rows
+        key = check_bool_indexer(self.index, key)
+
+        if key.all():
+            return self.copy(deep=None)
+
+        indexer = key.nonzero()[0]
+        return self._take_with_is_copy(indexer, axis=0)
+
+    def _getitem_multilevel(self, key):
+        # self.columns is a MultiIndex
+        loc = self.columns.get_loc(key)
+        if isinstance(loc, (slice, np.ndarray)):
+            new_columns = self.columns[loc]
+            result_columns = maybe_droplevels(new_columns, key)
+            result = self.iloc[:, loc]
+            result.columns = result_columns
+
+            # If there is only one column being returned, and its name is
+            # either an empty string, or a tuple with an empty string as its
+            # first element, then treat the empty string as a placeholder
+            # and return the column as if the user had provided that empty
+            # string in the key. If the result is a Series, exclude the
+            # implied empty string from its name.
+            if len(result.columns) == 1:
+                # e.g. test_frame_getitem_multicolumn_empty_level,
+                #  test_frame_mixed_depth_get, test_loc_setitem_single_column_slice
+                top = result.columns[0]
+                if isinstance(top, tuple):
+                    top = top[0]
+                if top == "":
+                    result = result[""]
+                    if isinstance(result, Series):
+                        result = self._constructor_sliced(
+                            result, index=self.index, name=key
+                        )
+
+            result._set_is_copy(self)
+            return result
+        else:
+            # loc is neither a slice nor ndarray, so must be an int
+            return self._ixs(loc, axis=1)
+
+    def _get_value(self, index, col, takeable: bool = False) -> Scalar:
+        """
+        Quickly retrieve single value at passed column and index.
+
+        Parameters
+        ----------
+        index : row label
+        col : column label
+        takeable : interpret the index/col as indexers, default False
+
+        Returns
+        -------
+        scalar
+
+        Notes
+        -----
+        Assumes that both `self.index._index_as_unique` and
+        `self.columns._index_as_unique`; Caller is responsible for checking.
+        """
+        if takeable:
+            series = self._ixs(col, axis=1)
+            return series._values[index]
+
+        series = self._get_item_cache(col)
+        engine = self.index._engine
+
+        if not isinstance(self.index, MultiIndex):
+            # CategoricalIndex: Trying to use the engine fastpath may give incorrect
+            #  results if our categories are integers that dont match our codes
+            # IntervalIndex: IntervalTree has no get_loc
+            row = self.index.get_loc(index)
+            return series._values[row]
+
+        # For MultiIndex going through engine effectively restricts us to
+        #  same-length tuples; see test_get_set_value_no_partial_indexing
+        loc = engine.get_loc(index)
+        return series._values[loc]
+
+    def isetitem(self, loc, value) -> None:
+        """
+        Set the given value in the column with position `loc`.
+
+        This is a positional analogue to ``__setitem__``.
+
+        Parameters
+        ----------
+        loc : int or sequence of ints
+            Index position for the column.
+        value : scalar or arraylike
+            Value(s) for the column.
+
+        Notes
+        -----
+        ``frame.isetitem(loc, value)`` is an in-place method as it will
+        modify the DataFrame in place (not returning a new object). In contrast to
+        ``frame.iloc[:, i] = value`` which will try to update the existing values in
+        place, ``frame.isetitem(loc, value)`` will not update the values of the column
+        itself in place, it will instead insert a new array.
+
+        In cases where ``frame.columns`` is unique, this is equivalent to
+        ``frame[frame.columns[i]] = value``.
+        """
+        if isinstance(value, DataFrame):
+            if is_integer(loc):
+                loc = [loc]
+
+            if len(loc) != len(value.columns):
+                raise ValueError(
+                    f"Got {len(loc)} positions but value has {len(value.columns)} "
+                    f"columns."
+                )
+
+            for i, idx in enumerate(loc):
+                arraylike, refs = self._sanitize_column(value.iloc[:, i])
+                self._iset_item_mgr(idx, arraylike, inplace=False, refs=refs)
+            return
+
+        arraylike, refs = self._sanitize_column(value)
+        self._iset_item_mgr(loc, arraylike, inplace=False, refs=refs)
+
+    def __setitem__(self, key, value) -> None:
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self) <= 3:
+                warnings.warn(
+                    _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
+                )
+        elif not PYPY and not WARNING_CHECK_DISABLED and not using_copy_on_write():
+            if sys.getrefcount(self) <= 3 and (
+                warn_copy_on_write()
+                or (
+                    not warn_copy_on_write()
+                    and any(b.refs.has_reference() for b in self._mgr.blocks)  # type: ignore[union-attr]
+                )
+            ):
+                warnings.warn(
+                    _chained_assignment_warning_msg, FutureWarning, stacklevel=2
+                )
+
+        key = com.apply_if_callable(key, self)
+
+        # see if we can slice the rows
+        if isinstance(key, slice):
+            slc = self.index._convert_slice_indexer(key, kind="getitem")
+            return self._setitem_slice(slc, value)
+
+        if isinstance(key, DataFrame) or getattr(key, "ndim", None) == 2:
+            self._setitem_frame(key, value)
+        elif isinstance(key, (Series, np.ndarray, list, Index)):
+            self._setitem_array(key, value)
+        elif isinstance(value, DataFrame):
+            self._set_item_frame_value(key, value)
+        elif (
+            is_list_like(value)
+            and not self.columns.is_unique
+            and 1 < len(self.columns.get_indexer_for([key])) == len(value)
+        ):
+            # Column to set is duplicated
+            self._setitem_array([key], value)
+        else:
+            # set column
+            self._set_item(key, value)
+
+    def _setitem_slice(self, key: slice, value) -> None:
+        # NB: we can't just use self.loc[key] = value because that
+        #  operates on labels and we need to operate positional for
+        #  backwards-compat, xref GH#31469
+        self._check_setitem_copy()
+        self.iloc[key] = value
+
+    def _setitem_array(self, key, value):
+        # also raises Exception if object array with NA values
+        if com.is_bool_indexer(key):
+            # bool indexer is indexing along rows
+            if len(key) != len(self.index):
+                raise ValueError(
+                    f"Item wrong length {len(key)} instead of {len(self.index)}!"
+                )
+            key = check_bool_indexer(self.index, key)
+            indexer = key.nonzero()[0]
+            self._check_setitem_copy()
+            if isinstance(value, DataFrame):
+                # GH#39931 reindex since iloc does not align
+                value = value.reindex(self.index.take(indexer))
+            self.iloc[indexer] = value
+
+        else:
+            # Note: unlike self.iloc[:, indexer] = value, this will
+            #  never try to overwrite values inplace
+
+            if isinstance(value, DataFrame):
+                check_key_length(self.columns, key, value)
+                for k1, k2 in zip(key, value.columns):
+                    self[k1] = value[k2]
+
+            elif not is_list_like(value):
+                for col in key:
+                    self[col] = value
+
+            elif isinstance(value, np.ndarray) and value.ndim == 2:
+                self._iset_not_inplace(key, value)
+
+            elif np.ndim(value) > 1:
+                # list of lists
+                value = DataFrame(value).values
+                return self._setitem_array(key, value)
+
+            else:
+                self._iset_not_inplace(key, value)
+
+    def _iset_not_inplace(self, key, value):
+        # GH#39510 when setting with df[key] = obj with a list-like key and
+        #  list-like value, we iterate over those listlikes and set columns
+        #  one at a time.  This is different from dispatching to
+        #  `self.loc[:, key]= value`  because loc.__setitem__ may overwrite
+        #  data inplace, whereas this will insert new arrays.
+
+        def igetitem(obj, i: int):
+            # Note: we catch DataFrame obj before getting here, but
+            #  hypothetically would return obj.iloc[:, i]
+            if isinstance(obj, np.ndarray):
+                return obj[..., i]
+            else:
+                return obj[i]
+
+        if self.columns.is_unique:
+            if np.shape(value)[-1] != len(key):
+                raise ValueError("Columns must be same length as key")
+
+            for i, col in enumerate(key):
+                self[col] = igetitem(value, i)
+
+        else:
+            ilocs = self.columns.get_indexer_non_unique(key)[0]
+            if (ilocs < 0).any():
+                # key entries not in self.columns
+                raise NotImplementedError
+
+            if np.shape(value)[-1] != len(ilocs):
+                raise ValueError("Columns must be same length as key")
+
+            assert np.ndim(value) <= 2
+
+            orig_columns = self.columns
+
+            # Using self.iloc[:, i] = ... may set values inplace, which
+            #  by convention we do not do in __setitem__
+            try:
+                self.columns = Index(range(len(self.columns)))
+                for i, iloc in enumerate(ilocs):
+                    self[iloc] = igetitem(value, i)
+            finally:
+                self.columns = orig_columns
+
+    def _setitem_frame(self, key, value):
+        # support boolean setting with DataFrame input, e.g.
+        # df[df > df2] = 0
+        if isinstance(key, np.ndarray):
+            if key.shape != self.shape:
+                raise ValueError("Array conditional must be same shape as self")
+            key = self._constructor(key, **self._construct_axes_dict(), copy=False)
+
+        if key.size and not all(is_bool_dtype(dtype) for dtype in key.dtypes):
+            raise TypeError(
+                "Must pass DataFrame or 2-d ndarray with boolean values only"
+            )
+
+        self._check_setitem_copy()
+        self._where(-key, value, inplace=True)
+
+    def _set_item_frame_value(self, key, value: DataFrame) -> None:
+        self._ensure_valid_index(value)
+
+        # align columns
+        if key in self.columns:
+            loc = self.columns.get_loc(key)
+            cols = self.columns[loc]
+            len_cols = 1 if is_scalar(cols) or isinstance(cols, tuple) else len(cols)
+            if len_cols != len(value.columns):
+                raise ValueError("Columns must be same length as key")
+
+            # align right-hand-side columns if self.columns
+            # is multi-index and self[key] is a sub-frame
+            if isinstance(self.columns, MultiIndex) and isinstance(
+                loc, (slice, Series, np.ndarray, Index)
+            ):
+                cols_droplevel = maybe_droplevels(cols, key)
+                if len(cols_droplevel) and not cols_droplevel.equals(value.columns):
+                    value = value.reindex(cols_droplevel, axis=1)
+
+                for col, col_droplevel in zip(cols, cols_droplevel):
+                    self[col] = value[col_droplevel]
+                return
+
+            if is_scalar(cols):
+                self[cols] = value[value.columns[0]]
+                return
+
+            locs: np.ndarray | list
+            if isinstance(loc, slice):
+                locs = np.arange(loc.start, loc.stop, loc.step)
+            elif is_scalar(loc):
+                locs = [loc]
+            else:
+                locs = loc.nonzero()[0]
+
+            return self.isetitem(locs, value)
+
+        if len(value.columns) > 1:
+            raise ValueError(
+                "Cannot set a DataFrame with multiple columns to the single "
+                f"column {key}"
+            )
+        elif len(value.columns) == 0:
+            raise ValueError(
+                f"Cannot set a DataFrame without columns to the column {key}"
+            )
+
+        self[key] = value[value.columns[0]]
+
+    def _iset_item_mgr(
+        self,
+        loc: int | slice | np.ndarray,
+        value,
+        inplace: bool = False,
+        refs: BlockValuesRefs | None = None,
+    ) -> None:
+        # when called from _set_item_mgr loc can be anything returned from get_loc
+        self._mgr.iset(loc, value, inplace=inplace, refs=refs)
+        self._clear_item_cache()
+
+    def _set_item_mgr(
+        self, key, value: ArrayLike, refs: BlockValuesRefs | None = None
+    ) -> None:
+        try:
+            loc = self._info_axis.get_loc(key)
+        except KeyError:
+            # This item wasn't present, just insert at end
+            self._mgr.insert(len(self._info_axis), key, value, refs)
+        else:
+            self._iset_item_mgr(loc, value, refs=refs)
+
+        # check if we are modifying a copy
+        # try to set first as we want an invalid
+        # value exception to occur first
+        if len(self):
+            self._check_setitem_copy()
+
+    def _iset_item(self, loc: int, value: Series, inplace: bool = True) -> None:
+        # We are only called from _replace_columnwise which guarantees that
+        # no reindex is necessary
+        if using_copy_on_write():
+            self._iset_item_mgr(
+                loc, value._values, inplace=inplace, refs=value._references
+            )
+        else:
+            self._iset_item_mgr(loc, value._values.copy(), inplace=True)
+
+        # check if we are modifying a copy
+        # try to set first as we want an invalid
+        # value exception to occur first
+        if len(self):
+            self._check_setitem_copy()
+
+    def _set_item(self, key, value) -> None:
+        """
+        Add series to DataFrame in specified column.
+
+        If series is a numpy-array (not a Series/TimeSeries), it must be the
+        same length as the DataFrames index or an error will be thrown.
+
+        Series/TimeSeries will be conformed to the DataFrames index to
+        ensure homogeneity.
+        """
+        value, refs = self._sanitize_column(value)
+
+        if (
+            key in self.columns
+            and value.ndim == 1
+            and not isinstance(value.dtype, ExtensionDtype)
+        ):
+            # broadcast across multiple columns if necessary
+            if not self.columns.is_unique or isinstance(self.columns, MultiIndex):
+                existing_piece = self[key]
+                if isinstance(existing_piece, DataFrame):
+                    value = np.tile(value, (len(existing_piece.columns), 1)).T
+                    refs = None
+
+        self._set_item_mgr(key, value, refs)
+
+    def _set_value(
+        self, index: IndexLabel, col, value: Scalar, takeable: bool = False
+    ) -> None:
+        """
+        Put single value at passed column and index.
+
+        Parameters
+        ----------
+        index : Label
+            row label
+        col : Label
+            column label
+        value : scalar
+        takeable : bool, default False
+            Sets whether or not index/col interpreted as indexers
+        """
+        try:
+            if takeable:
+                icol = col
+                iindex = cast(int, index)
+            else:
+                icol = self.columns.get_loc(col)
+                iindex = self.index.get_loc(index)
+            self._mgr.column_setitem(icol, iindex, value, inplace_only=True)
+            self._clear_item_cache()
+
+        except (KeyError, TypeError, ValueError, LossySetitemError):
+            # get_loc might raise a KeyError for missing labels (falling back
+            #  to (i)loc will do expansion of the index)
+            # column_setitem will do validation that may raise TypeError,
+            #  ValueError, or LossySetitemError
+            # set using a non-recursive method & reset the cache
+            if takeable:
+                self.iloc[index, col] = value
+            else:
+                self.loc[index, col] = value
+            self._item_cache.pop(col, None)
+
+        except InvalidIndexError as ii_err:
+            # GH48729: Seems like you are trying to assign a value to a
+            # row when only scalar options are permitted
+            raise InvalidIndexError(
+                f"You can only assign a scalar value not a {type(value)}"
+            ) from ii_err
+
+    def _ensure_valid_index(self, value) -> None:
+        """
+        Ensure that if we don't have an index, that we can create one from the
+        passed value.
+        """
+        # GH5632, make sure that we are a Series convertible
+        if not len(self.index) and is_list_like(value) and len(value):
+            if not isinstance(value, DataFrame):
+                try:
+                    value = Series(value)
+                except (ValueError, NotImplementedError, TypeError) as err:
+                    raise ValueError(
+                        "Cannot set a frame with no defined index "
+                        "and a value that cannot be converted to a Series"
+                    ) from err
+
+            # GH31368 preserve name of index
+            index_copy = value.index.copy()
+            if self.index.name is not None:
+                index_copy.name = self.index.name
+
+            self._mgr = self._mgr.reindex_axis(index_copy, axis=1, fill_value=np.nan)
+
+    def _box_col_values(self, values: SingleDataManager, loc: int) -> Series:
+        """
+        Provide boxed values for a column.
+        """
+        # Lookup in columns so that if e.g. a str datetime was passed
+        #  we attach the Timestamp object as the name.
+        name = self.columns[loc]
+        # We get index=self.index bc values is a SingleDataManager
+        obj = self._constructor_sliced_from_mgr(values, axes=values.axes)
+        obj._name = name
+        return obj.__finalize__(self)
+
+    # ----------------------------------------------------------------------
+    # Lookup Caching
+
+    def _clear_item_cache(self) -> None:
+        self._item_cache.clear()
+
+    def _get_item_cache(self, item: Hashable) -> Series:
+        """Return the cached item, item represents a label indexer."""
+        if using_copy_on_write() or warn_copy_on_write():
+            loc = self.columns.get_loc(item)
+            return self._ixs(loc, axis=1)
+
+        cache = self._item_cache
+        res = cache.get(item)
+        if res is None:
+            # All places that call _get_item_cache have unique columns,
+            #  pending resolution of GH#33047
+
+            loc = self.columns.get_loc(item)
+            res = self._ixs(loc, axis=1)
+
+            cache[item] = res
+
+            # for a chain
+            res._is_copy = self._is_copy
+        return res
+
+    def _reset_cacher(self) -> None:
+        # no-op for DataFrame
+        pass
+
+    def _maybe_cache_changed(self, item, value: Series, inplace: bool) -> None:
+        """
+        The object has called back to us saying maybe it has changed.
+        """
+        loc = self._info_axis.get_loc(item)
+        arraylike = value._values
+
+        old = self._ixs(loc, axis=1)
+        if old._values is value._values and inplace:
+            # GH#46149 avoid making unnecessary copies/block-splitting
+            return
+
+        self._mgr.iset(loc, arraylike, inplace=inplace)
+
+    # ----------------------------------------------------------------------
+    # Unsorted
+
+    @overload
+    def query(self, expr: str, *, inplace: Literal[False] = ..., **kwargs) -> DataFrame:
+        ...
+
+    @overload
+    def query(self, expr: str, *, inplace: Literal[True], **kwargs) -> None:
+        ...
+
+    @overload
+    def query(self, expr: str, *, inplace: bool = ..., **kwargs) -> DataFrame | None:
+        ...
+
+    def query(self, expr: str, *, inplace: bool = False, **kwargs) -> DataFrame | None:
+        """
+        Query the columns of a DataFrame with a boolean expression.
+
+        Parameters
+        ----------
+        expr : str
+            The query string to evaluate.
+
+            You can refer to variables
+            in the environment by prefixing them with an '@' character like
+            ``@a + b``.
+
+            You can refer to column names that are not valid Python variable names
+            by surrounding them in backticks. Thus, column names containing spaces
+            or punctuations (besides underscores) or starting with digits must be
+            surrounded by backticks. (For example, a column named "Area (cm^2)" would
+            be referenced as ```Area (cm^2)```). Column names which are Python keywords
+            (like "list", "for", "import", etc) cannot be used.
+
+            For example, if one of your columns is called ``a a`` and you want
+            to sum it with ``b``, your query should be ```a a` + b``.
+
+        inplace : bool
+            Whether to modify the DataFrame rather than creating a new one.
+        **kwargs
+            See the documentation for :func:`eval` for complete details
+            on the keyword arguments accepted by :meth:`DataFrame.query`.
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame resulting from the provided query expression or
+            None if ``inplace=True``.
+
+        See Also
+        --------
+        eval : Evaluate a string describing operations on
+            DataFrame columns.
+        DataFrame.eval : Evaluate a string describing operations on
+            DataFrame columns.
+
+        Notes
+        -----
+        The result of the evaluation of this expression is first passed to
+        :attr:`DataFrame.loc` and if that fails because of a
+        multidimensional key (e.g., a DataFrame) then the result will be passed
+        to :meth:`DataFrame.__getitem__`.
+
+        This method uses the top-level :func:`eval` function to
+        evaluate the passed query.
+
+        The :meth:`~pandas.DataFrame.query` method uses a slightly
+        modified Python syntax by default. For example, the ``&`` and ``|``
+        (bitwise) operators have the precedence of their boolean cousins,
+        :keyword:`and` and :keyword:`or`. This *is* syntactically valid Python,
+        however the semantics are different.
+
+        You can change the semantics of the expression by passing the keyword
+        argument ``parser='python'``. This enforces the same semantics as
+        evaluation in Python space. Likewise, you can pass ``engine='python'``
+        to evaluate an expression using Python itself as a backend. This is not
+        recommended as it is inefficient compared to using ``numexpr`` as the
+        engine.
+
+        The :attr:`DataFrame.index` and
+        :attr:`DataFrame.columns` attributes of the
+        :class:`~pandas.DataFrame` instance are placed in the query namespace
+        by default, which allows you to treat both the index and columns of the
+        frame as a column in the frame.
+        The identifier ``index`` is used for the frame index; you can also
+        use the name of the index to identify it in a query. Please note that
+        Python keywords may not be used as identifiers.
+
+        For further details and examples see the ``query`` documentation in
+        :ref:`indexing `.
+
+        *Backtick quoted variables*
+
+        Backtick quoted variables are parsed as literal Python code and
+        are converted internally to a Python valid identifier.
+        This can lead to the following problems.
+
+        During parsing a number of disallowed characters inside the backtick
+        quoted string are replaced by strings that are allowed as a Python identifier.
+        These characters include all operators in Python, the space character, the
+        question mark, the exclamation mark, the dollar sign, and the euro sign.
+        For other characters that fall outside the ASCII range (U+0001..U+007F)
+        and those that are not further specified in PEP 3131,
+        the query parser will raise an error.
+        This excludes whitespace different than the space character,
+        but also the hashtag (as it is used for comments) and the backtick
+        itself (backtick can also not be escaped).
+
+        In a special case, quotes that make a pair around a backtick can
+        confuse the parser.
+        For example, ```it's` > `that's``` will raise an error,
+        as it forms a quoted string (``'s > `that'``) with a backtick inside.
+
+        See also the Python documentation about lexical analysis
+        (https://docs.python.org/3/reference/lexical_analysis.html)
+        in combination with the source code in :mod:`pandas.core.computation.parsing`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': range(1, 6),
+        ...                    'B': range(10, 0, -2),
+        ...                    'C C': range(10, 5, -1)})
+        >>> df
+           A   B  C C
+        0  1  10   10
+        1  2   8    9
+        2  3   6    8
+        3  4   4    7
+        4  5   2    6
+        >>> df.query('A > B')
+           A  B  C C
+        4  5  2    6
+
+        The previous expression is equivalent to
+
+        >>> df[df.A > df.B]
+           A  B  C C
+        4  5  2    6
+
+        For columns with spaces in their name, you can use backtick quoting.
+
+        >>> df.query('B == `C C`')
+           A   B  C C
+        0  1  10   10
+
+        The previous expression is equivalent to
+
+        >>> df[df.B == df['C C']]
+           A   B  C C
+        0  1  10   10
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if not isinstance(expr, str):
+            msg = f"expr must be a string to be evaluated, {type(expr)} given"
+            raise ValueError(msg)
+        kwargs["level"] = kwargs.pop("level", 0) + 1
+        kwargs["target"] = None
+        res = self.eval(expr, **kwargs)
+
+        try:
+            result = self.loc[res]
+        except ValueError:
+            # when res is multi-dimensional loc raises, but this is sometimes a
+            # valid query
+            result = self[res]
+
+        if inplace:
+            self._update_inplace(result)
+            return None
+        else:
+            return result
+
+    @overload
+    def eval(self, expr: str, *, inplace: Literal[False] = ..., **kwargs) -> Any:
+        ...
+
+    @overload
+    def eval(self, expr: str, *, inplace: Literal[True], **kwargs) -> None:
+        ...
+
+    def eval(self, expr: str, *, inplace: bool = False, **kwargs) -> Any | None:
+        """
+        Evaluate a string describing operations on DataFrame columns.
+
+        Operates on columns only, not specific rows or elements.  This allows
+        `eval` to run arbitrary code, which can make you vulnerable to code
+        injection if you pass user input to this function.
+
+        Parameters
+        ----------
+        expr : str
+            The expression string to evaluate.
+        inplace : bool, default False
+            If the expression contains an assignment, whether to perform the
+            operation inplace and mutate the existing DataFrame. Otherwise,
+            a new DataFrame is returned.
+        **kwargs
+            See the documentation for :func:`eval` for complete details
+            on the keyword arguments accepted by
+            :meth:`~pandas.DataFrame.query`.
+
+        Returns
+        -------
+        ndarray, scalar, pandas object, or None
+            The result of the evaluation or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.query : Evaluates a boolean expression to query the columns
+            of a frame.
+        DataFrame.assign : Can evaluate an expression or function to create new
+            values for a column.
+        eval : Evaluate a Python expression as a string using various
+            backends.
+
+        Notes
+        -----
+        For more details see the API documentation for :func:`~eval`.
+        For detailed examples see :ref:`enhancing performance with eval
+        `.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': range(1, 6), 'B': range(10, 0, -2)})
+        >>> df
+           A   B
+        0  1  10
+        1  2   8
+        2  3   6
+        3  4   4
+        4  5   2
+        >>> df.eval('A + B')
+        0    11
+        1    10
+        2     9
+        3     8
+        4     7
+        dtype: int64
+
+        Assignment is allowed though by default the original DataFrame is not
+        modified.
+
+        >>> df.eval('C = A + B')
+           A   B   C
+        0  1  10  11
+        1  2   8  10
+        2  3   6   9
+        3  4   4   8
+        4  5   2   7
+        >>> df
+           A   B
+        0  1  10
+        1  2   8
+        2  3   6
+        3  4   4
+        4  5   2
+
+        Multiple columns can be assigned to using multi-line expressions:
+
+        >>> df.eval(
+        ...     '''
+        ... C = A + B
+        ... D = A - B
+        ... '''
+        ... )
+           A   B   C  D
+        0  1  10  11 -9
+        1  2   8  10 -6
+        2  3   6   9 -3
+        3  4   4   8  0
+        4  5   2   7  3
+        """
+        from pandas.core.computation.eval import eval as _eval
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        kwargs["level"] = kwargs.pop("level", 0) + 1
+        index_resolvers = self._get_index_resolvers()
+        column_resolvers = self._get_cleaned_column_resolvers()
+        resolvers = column_resolvers, index_resolvers
+        if "target" not in kwargs:
+            kwargs["target"] = self
+        kwargs["resolvers"] = tuple(kwargs.get("resolvers", ())) + resolvers
+
+        return _eval(expr, inplace=inplace, **kwargs)
+
+    def select_dtypes(self, include=None, exclude=None) -> Self:
+        """
+        Return a subset of the DataFrame's columns based on the column dtypes.
+
+        Parameters
+        ----------
+        include, exclude : scalar or list-like
+            A selection of dtypes or strings to be included/excluded. At least
+            one of these parameters must be supplied.
+
+        Returns
+        -------
+        DataFrame
+            The subset of the frame including the dtypes in ``include`` and
+            excluding the dtypes in ``exclude``.
+
+        Raises
+        ------
+        ValueError
+            * If both of ``include`` and ``exclude`` are empty
+            * If ``include`` and ``exclude`` have overlapping elements
+            * If any kind of string dtype is passed in.
+
+        See Also
+        --------
+        DataFrame.dtypes: Return Series with the data type of each column.
+
+        Notes
+        -----
+        * To select all *numeric* types, use ``np.number`` or ``'number'``
+        * To select strings you must use the ``object`` dtype, but note that
+          this will return *all* object dtype columns. With
+          ``pd.options.future.infer_string`` enabled, using ``"str"`` will
+          work to select all string columns.
+        * See the `numpy dtype hierarchy
+          `__
+        * To select datetimes, use ``np.datetime64``, ``'datetime'`` or
+          ``'datetime64'``
+        * To select timedeltas, use ``np.timedelta64``, ``'timedelta'`` or
+          ``'timedelta64'``
+        * To select Pandas categorical dtypes, use ``'category'``
+        * To select Pandas datetimetz dtypes, use ``'datetimetz'``
+          or ``'datetime64[ns, tz]'``
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'a': [1, 2] * 3,
+        ...                    'b': [True, False] * 3,
+        ...                    'c': [1.0, 2.0] * 3})
+        >>> df
+                a      b  c
+        0       1   True  1.0
+        1       2  False  2.0
+        2       1   True  1.0
+        3       2  False  2.0
+        4       1   True  1.0
+        5       2  False  2.0
+
+        >>> df.select_dtypes(include='bool')
+           b
+        0  True
+        1  False
+        2  True
+        3  False
+        4  True
+        5  False
+
+        >>> df.select_dtypes(include=['float64'])
+           c
+        0  1.0
+        1  2.0
+        2  1.0
+        3  2.0
+        4  1.0
+        5  2.0
+
+        >>> df.select_dtypes(exclude=['int64'])
+               b    c
+        0   True  1.0
+        1  False  2.0
+        2   True  1.0
+        3  False  2.0
+        4   True  1.0
+        5  False  2.0
+        """
+        if not is_list_like(include):
+            include = (include,) if include is not None else ()
+        if not is_list_like(exclude):
+            exclude = (exclude,) if exclude is not None else ()
+
+        selection = (frozenset(include), frozenset(exclude))
+
+        if not any(selection):
+            raise ValueError("at least one of include or exclude must be nonempty")
+
+        # convert the myriad valid dtypes object to a single representation
+        def check_int_infer_dtype(dtypes):
+            converted_dtypes: list[type] = []
+            for dtype in dtypes:
+                # Numpy maps int to different types (int32, in64) on Windows and Linux
+                # see https://github.com/numpy/numpy/issues/9464
+                if (isinstance(dtype, str) and dtype == "int") or (dtype is int):
+                    converted_dtypes.append(np.int32)
+                    converted_dtypes.append(np.int64)
+                elif dtype == "float" or dtype is float:
+                    # GH#42452 : np.dtype("float") coerces to np.float64 from Numpy 1.20
+                    converted_dtypes.extend([np.float64, np.float32])
+                else:
+                    converted_dtypes.append(infer_dtype_from_object(dtype))
+            return frozenset(converted_dtypes)
+
+        include = check_int_infer_dtype(include)
+        exclude = check_int_infer_dtype(exclude)
+
+        for dtypes in (include, exclude):
+            invalidate_string_dtypes(dtypes)
+
+        # can't both include AND exclude!
+        if not include.isdisjoint(exclude):
+            raise ValueError(f"include and exclude overlap on {(include & exclude)}")
+
+        def dtype_predicate(dtype: DtypeObj, dtypes_set) -> bool:
+            # GH 46870: BooleanDtype._is_numeric == True but should be excluded
+            dtype = dtype if not isinstance(dtype, ArrowDtype) else dtype.numpy_dtype
+            return (
+                issubclass(dtype.type, tuple(dtypes_set))
+                or (
+                    np.number in dtypes_set
+                    and getattr(dtype, "_is_numeric", False)
+                    and not is_bool_dtype(dtype)
+                )
+                # backwards compat for the default `str` dtype being selected by object
+                or (
+                    isinstance(dtype, StringDtype)
+                    and dtype.na_value is np.nan
+                    and np.object_ in dtypes_set
+                )
+            )
+
+        def predicate(arr: ArrayLike) -> bool:
+            dtype = arr.dtype
+            if include:
+                if not dtype_predicate(dtype, include):
+                    return False
+
+            if exclude:
+                if dtype_predicate(dtype, exclude):
+                    return False
+
+            return True
+
+        mgr = self._mgr._get_data_subset(predicate).copy(deep=None)
+        # error: Incompatible return value type (got "DataFrame", expected "Self")
+        return self._constructor_from_mgr(mgr, axes=mgr.axes).__finalize__(self)  # type: ignore[return-value]
+
+    def insert(
+        self,
+        loc: int,
+        column: Hashable,
+        value: Scalar | AnyArrayLike,
+        allow_duplicates: bool | lib.NoDefault = lib.no_default,
+    ) -> None:
+        """
+        Insert column into DataFrame at specified location.
+
+        Raises a ValueError if `column` is already contained in the DataFrame,
+        unless `allow_duplicates` is set to True.
+
+        Parameters
+        ----------
+        loc : int
+            Insertion index. Must verify 0 <= loc <= len(columns).
+        column : str, number, or hashable object
+            Label of the inserted column.
+        value : Scalar, Series, or array-like
+            Content of the inserted column.
+        allow_duplicates : bool, optional, default lib.no_default
+            Allow duplicate column labels to be created.
+
+        See Also
+        --------
+        Index.insert : Insert new item by index.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df
+           col1  col2
+        0     1     3
+        1     2     4
+        >>> df.insert(1, "newcol", [99, 99])
+        >>> df
+           col1  newcol  col2
+        0     1      99     3
+        1     2      99     4
+        >>> df.insert(0, "col1", [100, 100], allow_duplicates=True)
+        >>> df
+           col1  col1  newcol  col2
+        0   100     1      99     3
+        1   100     2      99     4
+
+        Notice that pandas uses index alignment in case of `value` from type `Series`:
+
+        >>> df.insert(0, "col0", pd.Series([5, 6], index=[1, 2]))
+        >>> df
+           col0  col1  col1  newcol  col2
+        0   NaN   100     1      99     3
+        1   5.0   100     2      99     4
+        """
+        if allow_duplicates is lib.no_default:
+            allow_duplicates = False
+        if allow_duplicates and not self.flags.allows_duplicate_labels:
+            raise ValueError(
+                "Cannot specify 'allow_duplicates=True' when "
+                "'self.flags.allows_duplicate_labels' is False."
+            )
+        if not allow_duplicates and column in self.columns:
+            # Should this be a different kind of error??
+            raise ValueError(f"cannot insert {column}, already exists")
+        if not is_integer(loc):
+            raise TypeError("loc must be int")
+        # convert non stdlib ints to satisfy typing checks
+        loc = int(loc)
+        if isinstance(value, DataFrame) and len(value.columns) > 1:
+            raise ValueError(
+                f"Expected a one-dimensional object, got a DataFrame with "
+                f"{len(value.columns)} columns instead."
+            )
+        elif isinstance(value, DataFrame):
+            value = value.iloc[:, 0]
+
+        value, refs = self._sanitize_column(value)
+        self._mgr.insert(loc, column, value, refs=refs)
+
+    def assign(self, **kwargs) -> DataFrame:
+        r"""
+        Assign new columns to a DataFrame.
+
+        Returns a new object with all original columns in addition to new ones.
+        Existing columns that are re-assigned will be overwritten.
+
+        Parameters
+        ----------
+        **kwargs : dict of {str: callable or Series}
+            The column names are keywords. If the values are
+            callable, they are computed on the DataFrame and
+            assigned to the new columns. The callable must not
+            change input DataFrame (though pandas doesn't check it).
+            If the values are not callable, (e.g. a Series, scalar, or array),
+            they are simply assigned.
+
+        Returns
+        -------
+        DataFrame
+            A new DataFrame with the new columns in addition to
+            all the existing columns.
+
+        Notes
+        -----
+        Assigning multiple columns within the same ``assign`` is possible.
+        Later items in '\*\*kwargs' may refer to newly created or modified
+        columns in 'df'; items are computed and assigned into 'df' in order.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'temp_c': [17.0, 25.0]},
+        ...                   index=['Portland', 'Berkeley'])
+        >>> df
+                  temp_c
+        Portland    17.0
+        Berkeley    25.0
+
+        Where the value is a callable, evaluated on `df`:
+
+        >>> df.assign(temp_f=lambda x: x.temp_c * 9 / 5 + 32)
+                  temp_c  temp_f
+        Portland    17.0    62.6
+        Berkeley    25.0    77.0
+
+        Alternatively, the same behavior can be achieved by directly
+        referencing an existing Series or sequence:
+
+        >>> df.assign(temp_f=df['temp_c'] * 9 / 5 + 32)
+                  temp_c  temp_f
+        Portland    17.0    62.6
+        Berkeley    25.0    77.0
+
+        You can create multiple columns within the same assign where one
+        of the columns depends on another one defined within the same assign:
+
+        >>> df.assign(temp_f=lambda x: x['temp_c'] * 9 / 5 + 32,
+        ...           temp_k=lambda x: (x['temp_f'] + 459.67) * 5 / 9)
+                  temp_c  temp_f  temp_k
+        Portland    17.0    62.6  290.15
+        Berkeley    25.0    77.0  298.15
+        """
+        data = self.copy(deep=None)
+
+        for k, v in kwargs.items():
+            data[k] = com.apply_if_callable(v, data)
+        return data
+
+    def _sanitize_column(self, value) -> tuple[ArrayLike, BlockValuesRefs | None]:
+        """
+        Ensures new columns (which go into the BlockManager as new blocks) are
+        always copied (or a reference is being tracked to them under CoW)
+        and converted into an array.
+
+        Parameters
+        ----------
+        value : scalar, Series, or array-like
+
+        Returns
+        -------
+        tuple of numpy.ndarray or ExtensionArray and optional BlockValuesRefs
+        """
+        self._ensure_valid_index(value)
+
+        # Using a DataFrame would mean coercing values to one dtype
+        assert not isinstance(value, DataFrame)
+        if is_dict_like(value):
+            if not isinstance(value, Series):
+                value = Series(value)
+            return _reindex_for_setitem(value, self.index)
+
+        if is_list_like(value):
+            com.require_length_match(value, self.index)
+        arr = sanitize_array(value, self.index, copy=True, allow_2d=True)
+        if (
+            isinstance(value, Index)
+            and value.dtype == "object"
+            and arr.dtype != value.dtype
+        ):  #
+            # TODO: Remove kludge in sanitize_array for string mode when enforcing
+            # this deprecation
+            warnings.warn(
+                "Setting an Index with object dtype into a DataFrame will stop "
+                "inferring another dtype in a future version. Cast the Index "
+                "explicitly before setting it into the DataFrame.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return arr, None
+
+    @property
+    def _series(self):
+        return {item: self._ixs(idx, axis=1) for idx, item in enumerate(self.columns)}
+
+    # ----------------------------------------------------------------------
+    # Reindexing and alignment
+
+    def _reindex_multi(
+        self, axes: dict[str, Index], copy: bool, fill_value
+    ) -> DataFrame:
+        """
+        We are guaranteed non-Nones in the axes.
+        """
+
+        new_index, row_indexer = self.index.reindex(axes["index"])
+        new_columns, col_indexer = self.columns.reindex(axes["columns"])
+
+        if row_indexer is not None and col_indexer is not None:
+            # Fastpath. By doing two 'take's at once we avoid making an
+            #  unnecessary copy.
+            # We only get here with `self._can_fast_transpose`, which (almost)
+            #  ensures that self.values is cheap. It may be worth making this
+            #  condition more specific.
+            indexer = row_indexer, col_indexer
+            new_values = take_2d_multi(self.values, indexer, fill_value=fill_value)
+            return self._constructor(
+                new_values, index=new_index, columns=new_columns, copy=False
+            )
+        else:
+            return self._reindex_with_indexers(
+                {0: [new_index, row_indexer], 1: [new_columns, col_indexer]},
+                copy=copy,
+                fill_value=fill_value,
+            )
+
+    @Appender(
+        """
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+
+        Change the row labels.
+
+        >>> df.set_axis(['a', 'b', 'c'], axis='index')
+           A  B
+        a  1  4
+        b  2  5
+        c  3  6
+
+        Change the column labels.
+
+        >>> df.set_axis(['I', 'II'], axis='columns')
+           I  II
+        0  1   4
+        1  2   5
+        2  3   6
+        """
+    )
+    @Substitution(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+        extended_summary_sub=" column or",
+        axis_description_sub=", and 1 identifies the columns",
+        see_also_sub=" or columns",
+    )
+    @Appender(NDFrame.set_axis.__doc__)
+    def set_axis(
+        self,
+        labels,
+        *,
+        axis: Axis = 0,
+        copy: bool | None = None,
+    ) -> DataFrame:
+        return super().set_axis(labels, axis=axis, copy=copy)
+
+    @doc(
+        NDFrame.reindex,
+        klass=_shared_doc_kwargs["klass"],
+        optional_reindex=_shared_doc_kwargs["optional_reindex"],
+    )
+    def reindex(
+        self,
+        labels=None,
+        *,
+        index=None,
+        columns=None,
+        axis: Axis | None = None,
+        method: ReindexMethod | None = None,
+        copy: bool | None = None,
+        level: Level | None = None,
+        fill_value: Scalar | None = np.nan,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> DataFrame:
+        return super().reindex(
+            labels=labels,
+            index=index,
+            columns=columns,
+            axis=axis,
+            method=method,
+            copy=copy,
+            level=level,
+            fill_value=fill_value,
+            limit=limit,
+            tolerance=tolerance,
+        )
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level = ...,
+        inplace: Literal[True],
+        errors: IgnoreRaise = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level = ...,
+        inplace: Literal[False] = ...,
+        errors: IgnoreRaise = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level = ...,
+        inplace: bool = ...,
+        errors: IgnoreRaise = ...,
+    ) -> DataFrame | None:
+        ...
+
+    def drop(
+        self,
+        labels: IndexLabel | None = None,
+        *,
+        axis: Axis = 0,
+        index: IndexLabel | None = None,
+        columns: IndexLabel | None = None,
+        level: Level | None = None,
+        inplace: bool = False,
+        errors: IgnoreRaise = "raise",
+    ) -> DataFrame | None:
+        """
+        Drop specified labels from rows or columns.
+
+        Remove rows or columns by specifying label names and corresponding
+        axis, or by directly specifying index or column names. When using a
+        multi-index, labels on different levels can be removed by specifying
+        the level. See the :ref:`user guide `
+        for more information about the now unused levels.
+
+        Parameters
+        ----------
+        labels : single label or list-like
+            Index or column labels to drop. A tuple will be used as a single
+            label and not treated as a list-like.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Whether to drop labels from the index (0 or 'index') or
+            columns (1 or 'columns').
+        index : single label or list-like
+            Alternative to specifying axis (``labels, axis=0``
+            is equivalent to ``index=labels``).
+        columns : single label or list-like
+            Alternative to specifying axis (``labels, axis=1``
+            is equivalent to ``columns=labels``).
+        level : int or level name, optional
+            For MultiIndex, level from which the labels will be removed.
+        inplace : bool, default False
+            If False, return a copy. Otherwise, do operation
+            in place and return None.
+        errors : {'ignore', 'raise'}, default 'raise'
+            If 'ignore', suppress error and only existing labels are
+            dropped.
+
+        Returns
+        -------
+        DataFrame or None
+            Returns DataFrame or None DataFrame with the specified
+            index or column labels removed or None if inplace=True.
+
+        Raises
+        ------
+        KeyError
+            If any of the labels is not found in the selected axis.
+
+        See Also
+        --------
+        DataFrame.loc : Label-location based indexer for selection by label.
+        DataFrame.dropna : Return DataFrame with labels on given axis omitted
+            where (all or any) data are missing.
+        DataFrame.drop_duplicates : Return DataFrame with duplicate rows
+            removed, optionally only considering certain columns.
+        Series.drop : Return Series with specified index labels removed.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.arange(12).reshape(3, 4),
+        ...                   columns=['A', 'B', 'C', 'D'])
+        >>> df
+           A  B   C   D
+        0  0  1   2   3
+        1  4  5   6   7
+        2  8  9  10  11
+
+        Drop columns
+
+        >>> df.drop(['B', 'C'], axis=1)
+           A   D
+        0  0   3
+        1  4   7
+        2  8  11
+
+        >>> df.drop(columns=['B', 'C'])
+           A   D
+        0  0   3
+        1  4   7
+        2  8  11
+
+        Drop a row by index
+
+        >>> df.drop([0, 1])
+           A  B   C   D
+        2  8  9  10  11
+
+        Drop columns and/or rows of MultiIndex DataFrame
+
+        >>> midx = pd.MultiIndex(levels=[['llama', 'cow', 'falcon'],
+        ...                              ['speed', 'weight', 'length']],
+        ...                      codes=[[0, 0, 0, 1, 1, 1, 2, 2, 2],
+        ...                             [0, 1, 2, 0, 1, 2, 0, 1, 2]])
+        >>> df = pd.DataFrame(index=midx, columns=['big', 'small'],
+        ...                   data=[[45, 30], [200, 100], [1.5, 1], [30, 20],
+        ...                         [250, 150], [1.5, 0.8], [320, 250],
+        ...                         [1, 0.8], [0.3, 0.2]])
+        >>> df
+                        big     small
+        llama   speed   45.0    30.0
+                weight  200.0   100.0
+                length  1.5     1.0
+        cow     speed   30.0    20.0
+                weight  250.0   150.0
+                length  1.5     0.8
+        falcon  speed   320.0   250.0
+                weight  1.0     0.8
+                length  0.3     0.2
+
+        Drop a specific index combination from the MultiIndex
+        DataFrame, i.e., drop the combination ``'falcon'`` and
+        ``'weight'``, which deletes only the corresponding row
+
+        >>> df.drop(index=('falcon', 'weight'))
+                        big     small
+        llama   speed   45.0    30.0
+                weight  200.0   100.0
+                length  1.5     1.0
+        cow     speed   30.0    20.0
+                weight  250.0   150.0
+                length  1.5     0.8
+        falcon  speed   320.0   250.0
+                length  0.3     0.2
+
+        >>> df.drop(index='cow', columns='small')
+                        big
+        llama   speed   45.0
+                weight  200.0
+                length  1.5
+        falcon  speed   320.0
+                weight  1.0
+                length  0.3
+
+        >>> df.drop(index='length', level=1)
+                        big     small
+        llama   speed   45.0    30.0
+                weight  200.0   100.0
+        cow     speed   30.0    20.0
+                weight  250.0   150.0
+        falcon  speed   320.0   250.0
+                weight  1.0     0.8
+        """
+        return super().drop(
+            labels=labels,
+            axis=axis,
+            index=index,
+            columns=columns,
+            level=level,
+            inplace=inplace,
+            errors=errors,
+        )
+
+    @overload
+    def rename(
+        self,
+        mapper: Renamer | None = ...,
+        *,
+        index: Renamer | None = ...,
+        columns: Renamer | None = ...,
+        axis: Axis | None = ...,
+        copy: bool | None = ...,
+        inplace: Literal[True],
+        level: Level = ...,
+        errors: IgnoreRaise = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def rename(
+        self,
+        mapper: Renamer | None = ...,
+        *,
+        index: Renamer | None = ...,
+        columns: Renamer | None = ...,
+        axis: Axis | None = ...,
+        copy: bool | None = ...,
+        inplace: Literal[False] = ...,
+        level: Level = ...,
+        errors: IgnoreRaise = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def rename(
+        self,
+        mapper: Renamer | None = ...,
+        *,
+        index: Renamer | None = ...,
+        columns: Renamer | None = ...,
+        axis: Axis | None = ...,
+        copy: bool | None = ...,
+        inplace: bool = ...,
+        level: Level = ...,
+        errors: IgnoreRaise = ...,
+    ) -> DataFrame | None:
+        ...
+
+    def rename(
+        self,
+        mapper: Renamer | None = None,
+        *,
+        index: Renamer | None = None,
+        columns: Renamer | None = None,
+        axis: Axis | None = None,
+        copy: bool | None = None,
+        inplace: bool = False,
+        level: Level | None = None,
+        errors: IgnoreRaise = "ignore",
+    ) -> DataFrame | None:
+        """
+        Rename columns or index labels.
+
+        Function / dict values must be unique (1-to-1). Labels not contained in
+        a dict / Series will be left as-is. Extra labels listed don't throw an
+        error.
+
+        See the :ref:`user guide ` for more.
+
+        Parameters
+        ----------
+        mapper : dict-like or function
+            Dict-like or function transformations to apply to
+            that axis' values. Use either ``mapper`` and ``axis`` to
+            specify the axis to target with ``mapper``, or ``index`` and
+            ``columns``.
+        index : dict-like or function
+            Alternative to specifying axis (``mapper, axis=0``
+            is equivalent to ``index=mapper``).
+        columns : dict-like or function
+            Alternative to specifying axis (``mapper, axis=1``
+            is equivalent to ``columns=mapper``).
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Axis to target with ``mapper``. Can be either the axis name
+            ('index', 'columns') or number (0, 1). The default is 'index'.
+        copy : bool, default True
+            Also copy underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        inplace : bool, default False
+            Whether to modify the DataFrame rather than creating a new one.
+            If True then value of copy is ignored.
+        level : int or level name, default None
+            In case of a MultiIndex, only rename labels in the specified
+            level.
+        errors : {'ignore', 'raise'}, default 'ignore'
+            If 'raise', raise a `KeyError` when a dict-like `mapper`, `index`,
+            or `columns` contains labels that are not present in the Index
+            being transformed.
+            If 'ignore', existing keys will be renamed and extra keys will be
+            ignored.
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with the renamed axis labels or None if ``inplace=True``.
+
+        Raises
+        ------
+        KeyError
+            If any of the labels is not found in the selected axis and
+            "errors='raise'".
+
+        See Also
+        --------
+        DataFrame.rename_axis : Set the name of the axis.
+
+        Examples
+        --------
+        ``DataFrame.rename`` supports two calling conventions
+
+        * ``(index=index_mapper, columns=columns_mapper, ...)``
+        * ``(mapper, axis={'index', 'columns'}, ...)``
+
+        We *highly* recommend using keyword arguments to clarify your
+        intent.
+
+        Rename columns using a mapping:
+
+        >>> df = pd.DataFrame({"A": [1, 2, 3], "B": [4, 5, 6]})
+        >>> df.rename(columns={"A": "a", "B": "c"})
+           a  c
+        0  1  4
+        1  2  5
+        2  3  6
+
+        Rename index using a mapping:
+
+        >>> df.rename(index={0: "x", 1: "y", 2: "z"})
+           A  B
+        x  1  4
+        y  2  5
+        z  3  6
+
+        Cast index labels to a different type:
+
+        >>> df.index
+        RangeIndex(start=0, stop=3, step=1)
+        >>> df.rename(index=str).index
+        Index(['0', '1', '2'], dtype='object')
+
+        >>> df.rename(columns={"A": "a", "B": "b", "C": "c"}, errors="raise")
+        Traceback (most recent call last):
+        KeyError: ['C'] not found in axis
+
+        Using axis-style parameters:
+
+        >>> df.rename(str.lower, axis='columns')
+           a  b
+        0  1  4
+        1  2  5
+        2  3  6
+
+        >>> df.rename({1: 2, 2: 4}, axis='index')
+           A  B
+        0  1  4
+        2  2  5
+        4  3  6
+        """
+        return super()._rename(
+            mapper=mapper,
+            index=index,
+            columns=columns,
+            axis=axis,
+            copy=copy,
+            inplace=inplace,
+            level=level,
+            errors=errors,
+        )
+
+    def pop(self, item: Hashable) -> Series:
+        """
+        Return item and drop from frame. Raise KeyError if not found.
+
+        Parameters
+        ----------
+        item : label
+            Label of column to be popped.
+
+        Returns
+        -------
+        Series
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('falcon', 'bird', 389.0),
+        ...                    ('parrot', 'bird', 24.0),
+        ...                    ('lion', 'mammal', 80.5),
+        ...                    ('monkey', 'mammal', np.nan)],
+        ...                   columns=('name', 'class', 'max_speed'))
+        >>> df
+             name   class  max_speed
+        0  falcon    bird      389.0
+        1  parrot    bird       24.0
+        2    lion  mammal       80.5
+        3  monkey  mammal        NaN
+
+        >>> df.pop('class')
+        0      bird
+        1      bird
+        2    mammal
+        3    mammal
+        Name: class, dtype: object
+
+        >>> df
+             name  max_speed
+        0  falcon      389.0
+        1  parrot       24.0
+        2    lion       80.5
+        3  monkey        NaN
+        """
+        return super().pop(item=item)
+
+    def _replace_columnwise(
+        self, mapping: dict[Hashable, tuple[Any, Any]], inplace: bool, regex
+    ):
+        """
+        Dispatch to Series.replace column-wise.
+
+        Parameters
+        ----------
+        mapping : dict
+            of the form {col: (target, value)}
+        inplace : bool
+        regex : bool or same types as `to_replace` in DataFrame.replace
+
+        Returns
+        -------
+        DataFrame or None
+        """
+        # Operate column-wise
+        res = self if inplace else self.copy(deep=None)
+        ax = self.columns
+
+        for i, ax_value in enumerate(ax):
+            if ax_value in mapping:
+                ser = self.iloc[:, i]
+
+                target, value = mapping[ax_value]
+                newobj = ser.replace(target, value, regex=regex)
+
+                res._iset_item(i, newobj, inplace=inplace)
+
+        if inplace:
+            return
+        return res.__finalize__(self)
+
+    @doc(NDFrame.shift, klass=_shared_doc_kwargs["klass"])
+    def shift(
+        self,
+        periods: int | Sequence[int] = 1,
+        freq: Frequency | None = None,
+        axis: Axis = 0,
+        fill_value: Hashable = lib.no_default,
+        suffix: str | None = None,
+    ) -> DataFrame:
+        if freq is not None and fill_value is not lib.no_default:
+            # GH#53832
+            warnings.warn(
+                "Passing a 'freq' together with a 'fill_value' silently ignores "
+                "the fill_value and is deprecated. This will raise in a future "
+                "version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            fill_value = lib.no_default
+
+        if self.empty:
+            return self.copy()
+
+        axis = self._get_axis_number(axis)
+
+        if is_list_like(periods):
+            periods = cast(Sequence, periods)
+            if axis == 1:
+                raise ValueError(
+                    "If `periods` contains multiple shifts, `axis` cannot be 1."
+                )
+            if len(periods) == 0:
+                raise ValueError("If `periods` is an iterable, it cannot be empty.")
+            from pandas.core.reshape.concat import concat
+
+            shifted_dataframes = []
+            for period in periods:
+                if not is_integer(period):
+                    raise TypeError(
+                        f"Periods must be integer, but {period} is {type(period)}."
+                    )
+                period = cast(int, period)
+                shifted_dataframes.append(
+                    super()
+                    .shift(periods=period, freq=freq, axis=axis, fill_value=fill_value)
+                    .add_suffix(f"{suffix}_{period}" if suffix else f"_{period}")
+                )
+            return concat(shifted_dataframes, axis=1)
+        elif suffix:
+            raise ValueError("Cannot specify `suffix` if `periods` is an int.")
+        periods = cast(int, periods)
+
+        ncols = len(self.columns)
+        arrays = self._mgr.arrays
+        if axis == 1 and periods != 0 and ncols > 0 and freq is None:
+            if fill_value is lib.no_default:
+                # We will infer fill_value to match the closest column
+
+                # Use a column that we know is valid for our column's dtype GH#38434
+                label = self.columns[0]
+
+                if periods > 0:
+                    result = self.iloc[:, :-periods]
+                    for col in range(min(ncols, abs(periods))):
+                        # TODO(EA2D): doing this in a loop unnecessary with 2D EAs
+                        # Define filler inside loop so we get a copy
+                        filler = self.iloc[:, 0].shift(len(self))
+                        result.insert(0, label, filler, allow_duplicates=True)
+                else:
+                    result = self.iloc[:, -periods:]
+                    for col in range(min(ncols, abs(periods))):
+                        # Define filler inside loop so we get a copy
+                        filler = self.iloc[:, -1].shift(len(self))
+                        result.insert(
+                            len(result.columns), label, filler, allow_duplicates=True
+                        )
+
+                result.columns = self.columns.copy()
+                return result
+            elif len(arrays) > 1 or (
+                # If we only have one block and we know that we can't
+                #  keep the same dtype (i.e. the _can_hold_element check)
+                #  then we can go through the reindex_indexer path
+                #  (and avoid casting logic in the Block method).
+                not can_hold_element(arrays[0], fill_value)
+            ):
+                # GH#35488 we need to watch out for multi-block cases
+                # We only get here with fill_value not-lib.no_default
+                nper = abs(periods)
+                nper = min(nper, ncols)
+                if periods > 0:
+                    indexer = np.array(
+                        [-1] * nper + list(range(ncols - periods)), dtype=np.intp
+                    )
+                else:
+                    indexer = np.array(
+                        list(range(nper, ncols)) + [-1] * nper, dtype=np.intp
+                    )
+                mgr = self._mgr.reindex_indexer(
+                    self.columns,
+                    indexer,
+                    axis=0,
+                    fill_value=fill_value,
+                    allow_dups=True,
+                )
+                res_df = self._constructor_from_mgr(mgr, axes=mgr.axes)
+                return res_df.__finalize__(self, method="shift")
+            else:
+                return self.T.shift(periods=periods, fill_value=fill_value).T
+
+        return super().shift(
+            periods=periods, freq=freq, axis=axis, fill_value=fill_value
+        )
+
+    @overload
+    def set_index(
+        self,
+        keys,
+        *,
+        drop: bool = ...,
+        append: bool = ...,
+        inplace: Literal[False] = ...,
+        verify_integrity: bool = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def set_index(
+        self,
+        keys,
+        *,
+        drop: bool = ...,
+        append: bool = ...,
+        inplace: Literal[True],
+        verify_integrity: bool = ...,
+    ) -> None:
+        ...
+
+    def set_index(
+        self,
+        keys,
+        *,
+        drop: bool = True,
+        append: bool = False,
+        inplace: bool = False,
+        verify_integrity: bool = False,
+    ) -> DataFrame | None:
+        """
+        Set the DataFrame index using existing columns.
+
+        Set the DataFrame index (row labels) using one or more existing
+        columns or arrays (of the correct length). The index can replace the
+        existing index or expand on it.
+
+        Parameters
+        ----------
+        keys : label or array-like or list of labels/arrays
+            This parameter can be either a single column key, a single array of
+            the same length as the calling DataFrame, or a list containing an
+            arbitrary combination of column keys and arrays. Here, "array"
+            encompasses :class:`Series`, :class:`Index`, ``np.ndarray``, and
+            instances of :class:`~collections.abc.Iterator`.
+        drop : bool, default True
+            Delete columns to be used as the new index.
+        append : bool, default False
+            Whether to append columns to existing index.
+        inplace : bool, default False
+            Whether to modify the DataFrame rather than creating a new one.
+        verify_integrity : bool, default False
+            Check the new index for duplicates. Otherwise defer the check until
+            necessary. Setting to False will improve the performance of this
+            method.
+
+        Returns
+        -------
+        DataFrame or None
+            Changed row labels or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.reset_index : Opposite of set_index.
+        DataFrame.reindex : Change to new indices or expand indices.
+        DataFrame.reindex_like : Change to same indices as other DataFrame.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'month': [1, 4, 7, 10],
+        ...                    'year': [2012, 2014, 2013, 2014],
+        ...                    'sale': [55, 40, 84, 31]})
+        >>> df
+           month  year  sale
+        0      1  2012    55
+        1      4  2014    40
+        2      7  2013    84
+        3     10  2014    31
+
+        Set the index to become the 'month' column:
+
+        >>> df.set_index('month')
+               year  sale
+        month
+        1      2012    55
+        4      2014    40
+        7      2013    84
+        10     2014    31
+
+        Create a MultiIndex using columns 'year' and 'month':
+
+        >>> df.set_index(['year', 'month'])
+                    sale
+        year  month
+        2012  1     55
+        2014  4     40
+        2013  7     84
+        2014  10    31
+
+        Create a MultiIndex using an Index and a column:
+
+        >>> df.set_index([pd.Index([1, 2, 3, 4]), 'year'])
+                 month  sale
+           year
+        1  2012  1      55
+        2  2014  4      40
+        3  2013  7      84
+        4  2014  10     31
+
+        Create a MultiIndex using two Series:
+
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> df.set_index([s, s**2])
+              month  year  sale
+        1 1       1  2012    55
+        2 4       4  2014    40
+        3 9       7  2013    84
+        4 16     10  2014    31
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        self._check_inplace_and_allows_duplicate_labels(inplace)
+        if not isinstance(keys, list):
+            keys = [keys]
+
+        err_msg = (
+            'The parameter "keys" may be a column key, one-dimensional '
+            "array, or a list containing only valid column keys and "
+            "one-dimensional arrays."
+        )
+
+        missing: list[Hashable] = []
+        for col in keys:
+            if isinstance(col, (Index, Series, np.ndarray, list, abc.Iterator)):
+                # arrays are fine as long as they are one-dimensional
+                # iterators get converted to list below
+                if getattr(col, "ndim", 1) != 1:
+                    raise ValueError(err_msg)
+            else:
+                # everything else gets tried as a key; see GH 24969
+                try:
+                    found = col in self.columns
+                except TypeError as err:
+                    raise TypeError(
+                        f"{err_msg}. Received column of type {type(col)}"
+                    ) from err
+                else:
+                    if not found:
+                        missing.append(col)
+
+        if missing:
+            raise KeyError(f"None of {missing} are in the columns")
+
+        if inplace:
+            frame = self
+        else:
+            # GH 49473 Use "lazy copy" with Copy-on-Write
+            frame = self.copy(deep=None)
+
+        arrays: list[Index] = []
+        names: list[Hashable] = []
+        if append:
+            names = list(self.index.names)
+            if isinstance(self.index, MultiIndex):
+                arrays.extend(
+                    self.index._get_level_values(i) for i in range(self.index.nlevels)
+                )
+            else:
+                arrays.append(self.index)
+
+        to_remove: list[Hashable] = []
+        for col in keys:
+            if isinstance(col, MultiIndex):
+                arrays.extend(col._get_level_values(n) for n in range(col.nlevels))
+                names.extend(col.names)
+            elif isinstance(col, (Index, Series)):
+                # if Index then not MultiIndex (treated above)
+
+                # error: Argument 1 to "append" of "list" has incompatible type
+                #  "Union[Index, Series]"; expected "Index"
+                arrays.append(col)  # type: ignore[arg-type]
+                names.append(col.name)
+            elif isinstance(col, (list, np.ndarray)):
+                # error: Argument 1 to "append" of "list" has incompatible type
+                # "Union[List[Any], ndarray]"; expected "Index"
+                arrays.append(col)  # type: ignore[arg-type]
+                names.append(None)
+            elif isinstance(col, abc.Iterator):
+                # error: Argument 1 to "append" of "list" has incompatible type
+                # "List[Any]"; expected "Index"
+                arrays.append(list(col))  # type: ignore[arg-type]
+                names.append(None)
+            # from here, col can only be a column label
+            else:
+                arrays.append(frame[col])
+                names.append(col)
+                if drop:
+                    to_remove.append(col)
+
+            if len(arrays[-1]) != len(self):
+                # check newest element against length of calling frame, since
+                # ensure_index_from_sequences would not raise for append=False.
+                raise ValueError(
+                    f"Length mismatch: Expected {len(self)} rows, "
+                    f"received array of length {len(arrays[-1])}"
+                )
+
+        index = ensure_index_from_sequences(arrays, names)
+
+        if verify_integrity and not index.is_unique:
+            duplicates = index[index.duplicated()].unique()
+            raise ValueError(f"Index has duplicate keys: {duplicates}")
+
+        # use set to handle duplicate column names gracefully in case of drop
+        for c in set(to_remove):
+            del frame[c]
+
+        # clear up memory usage
+        index._cleanup()
+
+        frame.index = index
+
+        if not inplace:
+            return frame
+        return None
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: bool = ...,
+        inplace: Literal[False] = ...,
+        col_level: Hashable = ...,
+        col_fill: Hashable = ...,
+        allow_duplicates: bool | lib.NoDefault = ...,
+        names: Hashable | Sequence[Hashable] | None = None,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: bool = ...,
+        inplace: Literal[True],
+        col_level: Hashable = ...,
+        col_fill: Hashable = ...,
+        allow_duplicates: bool | lib.NoDefault = ...,
+        names: Hashable | Sequence[Hashable] | None = None,
+    ) -> None:
+        ...
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: bool = ...,
+        inplace: bool = ...,
+        col_level: Hashable = ...,
+        col_fill: Hashable = ...,
+        allow_duplicates: bool | lib.NoDefault = ...,
+        names: Hashable | Sequence[Hashable] | None = None,
+    ) -> DataFrame | None:
+        ...
+
+    def reset_index(
+        self,
+        level: IndexLabel | None = None,
+        *,
+        drop: bool = False,
+        inplace: bool = False,
+        col_level: Hashable = 0,
+        col_fill: Hashable = "",
+        allow_duplicates: bool | lib.NoDefault = lib.no_default,
+        names: Hashable | Sequence[Hashable] | None = None,
+    ) -> DataFrame | None:
+        """
+        Reset the index, or a level of it.
+
+        Reset the index of the DataFrame, and use the default one instead.
+        If the DataFrame has a MultiIndex, this method can remove one or more
+        levels.
+
+        Parameters
+        ----------
+        level : int, str, tuple, or list, default None
+            Only remove the given levels from the index. Removes all levels by
+            default.
+        drop : bool, default False
+            Do not try to insert index into dataframe columns. This resets
+            the index to the default integer index.
+        inplace : bool, default False
+            Whether to modify the DataFrame rather than creating a new one.
+        col_level : int or str, default 0
+            If the columns have multiple levels, determines which level the
+            labels are inserted into. By default it is inserted into the first
+            level.
+        col_fill : object, default ''
+            If the columns have multiple levels, determines how the other
+            levels are named. If None then the index name is repeated.
+        allow_duplicates : bool, optional, default lib.no_default
+            Allow duplicate column labels to be created.
+
+            .. versionadded:: 1.5.0
+
+        names : int, str or 1-dimensional list, default None
+            Using the given string, rename the DataFrame column which contains the
+            index data. If the DataFrame has a MultiIndex, this has to be a list or
+            tuple with length equal to the number of levels.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with the new index or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.set_index : Opposite of reset_index.
+        DataFrame.reindex : Change to new indices or expand indices.
+        DataFrame.reindex_like : Change to same indices as other DataFrame.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('bird', 389.0),
+        ...                    ('bird', 24.0),
+        ...                    ('mammal', 80.5),
+        ...                    ('mammal', np.nan)],
+        ...                   index=['falcon', 'parrot', 'lion', 'monkey'],
+        ...                   columns=('class', 'max_speed'))
+        >>> df
+                 class  max_speed
+        falcon    bird      389.0
+        parrot    bird       24.0
+        lion    mammal       80.5
+        monkey  mammal        NaN
+
+        When we reset the index, the old index is added as a column, and a
+        new sequential index is used:
+
+        >>> df.reset_index()
+            index   class  max_speed
+        0  falcon    bird      389.0
+        1  parrot    bird       24.0
+        2    lion  mammal       80.5
+        3  monkey  mammal        NaN
+
+        We can use the `drop` parameter to avoid the old index being added as
+        a column:
+
+        >>> df.reset_index(drop=True)
+            class  max_speed
+        0    bird      389.0
+        1    bird       24.0
+        2  mammal       80.5
+        3  mammal        NaN
+
+        You can also use `reset_index` with `MultiIndex`.
+
+        >>> index = pd.MultiIndex.from_tuples([('bird', 'falcon'),
+        ...                                    ('bird', 'parrot'),
+        ...                                    ('mammal', 'lion'),
+        ...                                    ('mammal', 'monkey')],
+        ...                                   names=['class', 'name'])
+        >>> columns = pd.MultiIndex.from_tuples([('speed', 'max'),
+        ...                                      ('species', 'type')])
+        >>> df = pd.DataFrame([(389.0, 'fly'),
+        ...                    (24.0, 'fly'),
+        ...                    (80.5, 'run'),
+        ...                    (np.nan, 'jump')],
+        ...                   index=index,
+        ...                   columns=columns)
+        >>> df
+                       speed species
+                         max    type
+        class  name
+        bird   falcon  389.0     fly
+               parrot   24.0     fly
+        mammal lion     80.5     run
+               monkey    NaN    jump
+
+        Using the `names` parameter, choose a name for the index column:
+
+        >>> df.reset_index(names=['classes', 'names'])
+          classes   names  speed species
+                             max    type
+        0    bird  falcon  389.0     fly
+        1    bird  parrot   24.0     fly
+        2  mammal    lion   80.5     run
+        3  mammal  monkey    NaN    jump
+
+        If the index has multiple levels, we can reset a subset of them:
+
+        >>> df.reset_index(level='class')
+                 class  speed species
+                          max    type
+        name
+        falcon    bird  389.0     fly
+        parrot    bird   24.0     fly
+        lion    mammal   80.5     run
+        monkey  mammal    NaN    jump
+
+        If we are not dropping the index, by default, it is placed in the top
+        level. We can place it in another level:
+
+        >>> df.reset_index(level='class', col_level=1)
+                        speed species
+                 class    max    type
+        name
+        falcon    bird  389.0     fly
+        parrot    bird   24.0     fly
+        lion    mammal   80.5     run
+        monkey  mammal    NaN    jump
+
+        When the index is inserted under another level, we can specify under
+        which one with the parameter `col_fill`:
+
+        >>> df.reset_index(level='class', col_level=1, col_fill='species')
+                      species  speed species
+                        class    max    type
+        name
+        falcon           bird  389.0     fly
+        parrot           bird   24.0     fly
+        lion           mammal   80.5     run
+        monkey         mammal    NaN    jump
+
+        If we specify a nonexistent level for `col_fill`, it is created:
+
+        >>> df.reset_index(level='class', col_level=1, col_fill='genus')
+                        genus  speed species
+                        class    max    type
+        name
+        falcon           bird  389.0     fly
+        parrot           bird   24.0     fly
+        lion           mammal   80.5     run
+        monkey         mammal    NaN    jump
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        self._check_inplace_and_allows_duplicate_labels(inplace)
+        if inplace:
+            new_obj = self
+        else:
+            new_obj = self.copy(deep=None)
+        if allow_duplicates is not lib.no_default:
+            allow_duplicates = validate_bool_kwarg(allow_duplicates, "allow_duplicates")
+
+        new_index = default_index(len(new_obj))
+        if level is not None:
+            if not isinstance(level, (tuple, list)):
+                level = [level]
+            level = [self.index._get_level_number(lev) for lev in level]
+            if len(level) < self.index.nlevels:
+                new_index = self.index.droplevel(level)
+
+        if not drop:
+            to_insert: Iterable[tuple[Any, Any | None]]
+
+            default = "index" if "index" not in self else "level_0"
+            names = self.index._get_default_index_names(names, default)
+
+            if isinstance(self.index, MultiIndex):
+                to_insert = zip(self.index.levels, self.index.codes)
+            else:
+                to_insert = ((self.index, None),)
+
+            multi_col = isinstance(self.columns, MultiIndex)
+            for i, (lev, lab) in reversed(list(enumerate(to_insert))):
+                if level is not None and i not in level:
+                    continue
+                name = names[i]
+                if multi_col:
+                    col_name = list(name) if isinstance(name, tuple) else [name]
+                    if col_fill is None:
+                        if len(col_name) not in (1, self.columns.nlevels):
+                            raise ValueError(
+                                "col_fill=None is incompatible "
+                                f"with incomplete column name {name}"
+                            )
+                        col_fill = col_name[0]
+
+                    lev_num = self.columns._get_level_number(col_level)
+                    name_lst = [col_fill] * lev_num + col_name
+                    missing = self.columns.nlevels - len(name_lst)
+                    name_lst += [col_fill] * missing
+                    name = tuple(name_lst)
+
+                # to ndarray and maybe infer different dtype
+                level_values = lev._values
+                if level_values.dtype == np.object_:
+                    level_values = lib.maybe_convert_objects(level_values)
+
+                if lab is not None:
+                    # if we have the codes, extract the values with a mask
+                    level_values = algorithms.take(
+                        level_values, lab, allow_fill=True, fill_value=lev._na_value
+                    )
+
+                new_obj.insert(
+                    0,
+                    name,
+                    level_values,
+                    allow_duplicates=allow_duplicates,
+                )
+
+        new_obj.index = new_index
+        if not inplace:
+            return new_obj
+
+        return None
+
+    # ----------------------------------------------------------------------
+    # Reindex-based selection methods
+
+    @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])
+    def isna(self) -> DataFrame:
+        res_mgr = self._mgr.isna(func=isna)
+        result = self._constructor_from_mgr(res_mgr, axes=res_mgr.axes)
+        return result.__finalize__(self, method="isna")
+
+    @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])
+    def isnull(self) -> DataFrame:
+        """
+        DataFrame.isnull is an alias for DataFrame.isna.
+        """
+        return self.isna()
+
+    @doc(NDFrame.notna, klass=_shared_doc_kwargs["klass"])
+    def notna(self) -> DataFrame:
+        return ~self.isna()
+
+    @doc(NDFrame.notna, klass=_shared_doc_kwargs["klass"])
+    def notnull(self) -> DataFrame:
+        """
+        DataFrame.notnull is an alias for DataFrame.notna.
+        """
+        return ~self.isna()
+
+    @overload
+    def dropna(
+        self,
+        *,
+        axis: Axis = ...,
+        how: AnyAll | lib.NoDefault = ...,
+        thresh: int | lib.NoDefault = ...,
+        subset: IndexLabel = ...,
+        inplace: Literal[False] = ...,
+        ignore_index: bool = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def dropna(
+        self,
+        *,
+        axis: Axis = ...,
+        how: AnyAll | lib.NoDefault = ...,
+        thresh: int | lib.NoDefault = ...,
+        subset: IndexLabel = ...,
+        inplace: Literal[True],
+        ignore_index: bool = ...,
+    ) -> None:
+        ...
+
+    def dropna(
+        self,
+        *,
+        axis: Axis = 0,
+        how: AnyAll | lib.NoDefault = lib.no_default,
+        thresh: int | lib.NoDefault = lib.no_default,
+        subset: IndexLabel | None = None,
+        inplace: bool = False,
+        ignore_index: bool = False,
+    ) -> DataFrame | None:
+        """
+        Remove missing values.
+
+        See the :ref:`User Guide ` for more on which values are
+        considered missing, and how to work with missing data.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Determine if rows or columns which contain missing values are
+            removed.
+
+            * 0, or 'index' : Drop rows which contain missing values.
+            * 1, or 'columns' : Drop columns which contain missing value.
+
+            Only a single axis is allowed.
+
+        how : {'any', 'all'}, default 'any'
+            Determine if row or column is removed from DataFrame, when we have
+            at least one NA or all NA.
+
+            * 'any' : If any NA values are present, drop that row or column.
+            * 'all' : If all values are NA, drop that row or column.
+
+        thresh : int, optional
+            Require that many non-NA values. Cannot be combined with how.
+        subset : column label or sequence of labels, optional
+            Labels along other axis to consider, e.g. if you are dropping rows
+            these would be a list of columns to include.
+        inplace : bool, default False
+            Whether to modify the DataFrame rather than creating a new one.
+        ignore_index : bool, default ``False``
+            If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with NA entries dropped from it or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.isna: Indicate missing values.
+        DataFrame.notna : Indicate existing (non-missing) values.
+        DataFrame.fillna : Replace missing values.
+        Series.dropna : Drop missing values.
+        Index.dropna : Drop missing indices.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"name": ['Alfred', 'Batman', 'Catwoman'],
+        ...                    "toy": [np.nan, 'Batmobile', 'Bullwhip'],
+        ...                    "born": [pd.NaT, pd.Timestamp("1940-04-25"),
+        ...                             pd.NaT]})
+        >>> df
+               name        toy       born
+        0    Alfred        NaN        NaT
+        1    Batman  Batmobile 1940-04-25
+        2  Catwoman   Bullwhip        NaT
+
+        Drop the rows where at least one element is missing.
+
+        >>> df.dropna()
+             name        toy       born
+        1  Batman  Batmobile 1940-04-25
+
+        Drop the columns where at least one element is missing.
+
+        >>> df.dropna(axis='columns')
+               name
+        0    Alfred
+        1    Batman
+        2  Catwoman
+
+        Drop the rows where all elements are missing.
+
+        >>> df.dropna(how='all')
+               name        toy       born
+        0    Alfred        NaN        NaT
+        1    Batman  Batmobile 1940-04-25
+        2  Catwoman   Bullwhip        NaT
+
+        Keep only the rows with at least 2 non-NA values.
+
+        >>> df.dropna(thresh=2)
+               name        toy       born
+        1    Batman  Batmobile 1940-04-25
+        2  Catwoman   Bullwhip        NaT
+
+        Define in which columns to look for missing values.
+
+        >>> df.dropna(subset=['name', 'toy'])
+               name        toy       born
+        1    Batman  Batmobile 1940-04-25
+        2  Catwoman   Bullwhip        NaT
+        """
+        if (how is not lib.no_default) and (thresh is not lib.no_default):
+            raise TypeError(
+                "You cannot set both the how and thresh arguments at the same time."
+            )
+
+        if how is lib.no_default:
+            how = "any"
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if isinstance(axis, (tuple, list)):
+            # GH20987
+            raise TypeError("supplying multiple axes to axis is no longer supported.")
+
+        axis = self._get_axis_number(axis)
+        agg_axis = 1 - axis
+
+        agg_obj = self
+        if subset is not None:
+            # subset needs to be list
+            if not is_list_like(subset):
+                subset = [subset]
+            ax = self._get_axis(agg_axis)
+            indices = ax.get_indexer_for(subset)
+            check = indices == -1
+            if check.any():
+                raise KeyError(np.array(subset)[check].tolist())
+            agg_obj = self.take(indices, axis=agg_axis)
+
+        if thresh is not lib.no_default:
+            count = agg_obj.count(axis=agg_axis)
+            mask = count >= thresh
+        elif how == "any":
+            # faster equivalent to 'agg_obj.count(agg_axis) == self.shape[agg_axis]'
+            mask = notna(agg_obj).all(axis=agg_axis, bool_only=False)
+        elif how == "all":
+            # faster equivalent to 'agg_obj.count(agg_axis) > 0'
+            mask = notna(agg_obj).any(axis=agg_axis, bool_only=False)
+        else:
+            raise ValueError(f"invalid how option: {how}")
+
+        if np.all(mask):
+            result = self.copy(deep=None)
+        else:
+            result = self.loc(axis=axis)[mask]
+
+        if ignore_index:
+            result.index = default_index(len(result))
+
+        if not inplace:
+            return result
+        self._update_inplace(result)
+        return None
+
+    @overload
+    def drop_duplicates(
+        self,
+        subset: Hashable | Sequence[Hashable] | None = ...,
+        *,
+        keep: DropKeep = ...,
+        inplace: Literal[True],
+        ignore_index: bool = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def drop_duplicates(
+        self,
+        subset: Hashable | Sequence[Hashable] | None = ...,
+        *,
+        keep: DropKeep = ...,
+        inplace: Literal[False] = ...,
+        ignore_index: bool = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def drop_duplicates(
+        self,
+        subset: Hashable | Sequence[Hashable] | None = ...,
+        *,
+        keep: DropKeep = ...,
+        inplace: bool = ...,
+        ignore_index: bool = ...,
+    ) -> DataFrame | None:
+        ...
+
+    def drop_duplicates(
+        self,
+        subset: Hashable | Sequence[Hashable] | None = None,
+        *,
+        keep: DropKeep = "first",
+        inplace: bool = False,
+        ignore_index: bool = False,
+    ) -> DataFrame | None:
+        """
+        Return DataFrame with duplicate rows removed.
+
+        Considering certain columns is optional. Indexes, including time indexes
+        are ignored.
+
+        Parameters
+        ----------
+        subset : column label or sequence of labels, optional
+            Only consider certain columns for identifying duplicates, by
+            default use all of the columns.
+        keep : {'first', 'last', ``False``}, default 'first'
+            Determines which duplicates (if any) to keep.
+
+            - 'first' : Drop duplicates except for the first occurrence.
+            - 'last' : Drop duplicates except for the last occurrence.
+            - ``False`` : Drop all duplicates.
+
+        inplace : bool, default ``False``
+            Whether to modify the DataFrame rather than creating a new one.
+        ignore_index : bool, default ``False``
+            If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with duplicates removed or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.value_counts: Count unique combinations of columns.
+
+        Examples
+        --------
+        Consider dataset containing ramen rating.
+
+        >>> df = pd.DataFrame({
+        ...     'brand': ['Yum Yum', 'Yum Yum', 'Indomie', 'Indomie', 'Indomie'],
+        ...     'style': ['cup', 'cup', 'cup', 'pack', 'pack'],
+        ...     'rating': [4, 4, 3.5, 15, 5]
+        ... })
+        >>> df
+            brand style  rating
+        0  Yum Yum   cup     4.0
+        1  Yum Yum   cup     4.0
+        2  Indomie   cup     3.5
+        3  Indomie  pack    15.0
+        4  Indomie  pack     5.0
+
+        By default, it removes duplicate rows based on all columns.
+
+        >>> df.drop_duplicates()
+            brand style  rating
+        0  Yum Yum   cup     4.0
+        2  Indomie   cup     3.5
+        3  Indomie  pack    15.0
+        4  Indomie  pack     5.0
+
+        To remove duplicates on specific column(s), use ``subset``.
+
+        >>> df.drop_duplicates(subset=['brand'])
+            brand style  rating
+        0  Yum Yum   cup     4.0
+        2  Indomie   cup     3.5
+
+        To remove duplicates and keep last occurrences, use ``keep``.
+
+        >>> df.drop_duplicates(subset=['brand', 'style'], keep='last')
+            brand style  rating
+        1  Yum Yum   cup     4.0
+        2  Indomie   cup     3.5
+        4  Indomie  pack     5.0
+        """
+        if self.empty:
+            return self.copy(deep=None)
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        ignore_index = validate_bool_kwarg(ignore_index, "ignore_index")
+
+        result = self[-self.duplicated(subset, keep=keep)]
+        if ignore_index:
+            result.index = default_index(len(result))
+
+        if inplace:
+            self._update_inplace(result)
+            return None
+        else:
+            return result
+
+    def duplicated(
+        self,
+        subset: Hashable | Sequence[Hashable] | None = None,
+        keep: DropKeep = "first",
+    ) -> Series:
+        """
+        Return boolean Series denoting duplicate rows.
+
+        Considering certain columns is optional.
+
+        Parameters
+        ----------
+        subset : column label or sequence of labels, optional
+            Only consider certain columns for identifying duplicates, by
+            default use all of the columns.
+        keep : {'first', 'last', False}, default 'first'
+            Determines which duplicates (if any) to mark.
+
+            - ``first`` : Mark duplicates as ``True`` except for the first occurrence.
+            - ``last`` : Mark duplicates as ``True`` except for the last occurrence.
+            - False : Mark all duplicates as ``True``.
+
+        Returns
+        -------
+        Series
+            Boolean series for each duplicated rows.
+
+        See Also
+        --------
+        Index.duplicated : Equivalent method on index.
+        Series.duplicated : Equivalent method on Series.
+        Series.drop_duplicates : Remove duplicate values from Series.
+        DataFrame.drop_duplicates : Remove duplicate values from DataFrame.
+
+        Examples
+        --------
+        Consider dataset containing ramen rating.
+
+        >>> df = pd.DataFrame({
+        ...     'brand': ['Yum Yum', 'Yum Yum', 'Indomie', 'Indomie', 'Indomie'],
+        ...     'style': ['cup', 'cup', 'cup', 'pack', 'pack'],
+        ...     'rating': [4, 4, 3.5, 15, 5]
+        ... })
+        >>> df
+            brand style  rating
+        0  Yum Yum   cup     4.0
+        1  Yum Yum   cup     4.0
+        2  Indomie   cup     3.5
+        3  Indomie  pack    15.0
+        4  Indomie  pack     5.0
+
+        By default, for each set of duplicated values, the first occurrence
+        is set on False and all others on True.
+
+        >>> df.duplicated()
+        0    False
+        1     True
+        2    False
+        3    False
+        4    False
+        dtype: bool
+
+        By using 'last', the last occurrence of each set of duplicated values
+        is set on False and all others on True.
+
+        >>> df.duplicated(keep='last')
+        0     True
+        1    False
+        2    False
+        3    False
+        4    False
+        dtype: bool
+
+        By setting ``keep`` on False, all duplicates are True.
+
+        >>> df.duplicated(keep=False)
+        0     True
+        1     True
+        2    False
+        3    False
+        4    False
+        dtype: bool
+
+        To find duplicates on specific column(s), use ``subset``.
+
+        >>> df.duplicated(subset=['brand'])
+        0    False
+        1     True
+        2    False
+        3     True
+        4     True
+        dtype: bool
+        """
+
+        if self.empty:
+            return self._constructor_sliced(dtype=bool)
+
+        def f(vals) -> tuple[np.ndarray, int]:
+            labels, shape = algorithms.factorize(vals, size_hint=len(self))
+            return labels.astype("i8", copy=False), len(shape)
+
+        if subset is None:
+            # https://github.com/pandas-dev/pandas/issues/28770
+            # Incompatible types in assignment (expression has type "Index", variable
+            # has type "Sequence[Any]")
+            subset = self.columns  # type: ignore[assignment]
+        elif (
+            not np.iterable(subset)
+            or isinstance(subset, str)
+            or isinstance(subset, tuple)
+            and subset in self.columns
+        ):
+            subset = (subset,)
+
+        #  needed for mypy since can't narrow types using np.iterable
+        subset = cast(Sequence, subset)
+
+        # Verify all columns in subset exist in the queried dataframe
+        # Otherwise, raise a KeyError, same as if you try to __getitem__ with a
+        # key that doesn't exist.
+        diff = set(subset) - set(self.columns)
+        if diff:
+            raise KeyError(Index(diff))
+
+        if len(subset) == 1 and self.columns.is_unique:
+            # GH#45236 This is faster than get_group_index below
+            result = self[subset[0]].duplicated(keep)
+            result.name = None
+        else:
+            vals = (col.values for name, col in self.items() if name in subset)
+            labels, shape = map(list, zip(*map(f, vals)))
+
+            ids = get_group_index(labels, tuple(shape), sort=False, xnull=False)
+            result = self._constructor_sliced(duplicated(ids, keep), index=self.index)
+        return result.__finalize__(self, method="duplicated")
+
+    # ----------------------------------------------------------------------
+    # Sorting
+    # error: Signature of "sort_values" incompatible with supertype "NDFrame"
+    @overload  # type: ignore[override]
+    def sort_values(
+        self,
+        by: IndexLabel,
+        *,
+        axis: Axis = ...,
+        ascending=...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool = ...,
+        key: ValueKeyFunc = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        by: IndexLabel,
+        *,
+        axis: Axis = ...,
+        ascending=...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: str = ...,
+        ignore_index: bool = ...,
+        key: ValueKeyFunc = ...,
+    ) -> None:
+        ...
+
+    def sort_values(
+        self,
+        by: IndexLabel,
+        *,
+        axis: Axis = 0,
+        ascending: bool | list[bool] | tuple[bool, ...] = True,
+        inplace: bool = False,
+        kind: SortKind = "quicksort",
+        na_position: str = "last",
+        ignore_index: bool = False,
+        key: ValueKeyFunc | None = None,
+    ) -> DataFrame | None:
+        """
+        Sort by the values along either axis.
+
+        Parameters
+        ----------
+        by : str or list of str
+            Name or list of names to sort by.
+
+            - if `axis` is 0 or `'index'` then `by` may contain index
+              levels and/or column labels.
+            - if `axis` is 1 or `'columns'` then `by` may contain column
+              levels and/or index labels.
+        axis : "{0 or 'index', 1 or 'columns'}", default 0
+             Axis to be sorted.
+        ascending : bool or list of bool, default True
+             Sort ascending vs. descending. Specify list for multiple sort
+             orders.  If this is a list of bools, must match the length of
+             the by.
+        inplace : bool, default False
+             If True, perform operation in-place.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+             Choice of sorting algorithm. See also :func:`numpy.sort` for more
+             information. `mergesort` and `stable` are the only stable algorithms. For
+             DataFrames, this option is only applied when sorting on a single
+             column or label.
+        na_position : {'first', 'last'}, default 'last'
+             Puts NaNs at the beginning if `first`; `last` puts NaNs at the
+             end.
+        ignore_index : bool, default False
+             If True, the resulting axis will be labeled 0, 1, …, n - 1.
+        key : callable, optional
+            Apply the key function to the values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect a
+            ``Series`` and return a Series with the same shape as the input.
+            It will be applied to each column in `by` independently.
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with sorted values or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.sort_index : Sort a DataFrame by the index.
+        Series.sort_values : Similar method for a Series.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({
+        ...     'col1': ['A', 'A', 'B', np.nan, 'D', 'C'],
+        ...     'col2': [2, 1, 9, 8, 7, 4],
+        ...     'col3': [0, 1, 9, 4, 2, 3],
+        ...     'col4': ['a', 'B', 'c', 'D', 'e', 'F']
+        ... })
+        >>> df
+          col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+
+        Sort by col1
+
+        >>> df.sort_values(by=['col1'])
+          col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        5    C     4     3    F
+        4    D     7     2    e
+        3  NaN     8     4    D
+
+        Sort by multiple columns
+
+        >>> df.sort_values(by=['col1', 'col2'])
+          col1  col2  col3 col4
+        1    A     1     1    B
+        0    A     2     0    a
+        2    B     9     9    c
+        5    C     4     3    F
+        4    D     7     2    e
+        3  NaN     8     4    D
+
+        Sort Descending
+
+        >>> df.sort_values(by='col1', ascending=False)
+          col1  col2  col3 col4
+        4    D     7     2    e
+        5    C     4     3    F
+        2    B     9     9    c
+        0    A     2     0    a
+        1    A     1     1    B
+        3  NaN     8     4    D
+
+        Putting NAs first
+
+        >>> df.sort_values(by='col1', ascending=False, na_position='first')
+          col1  col2  col3 col4
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+        2    B     9     9    c
+        0    A     2     0    a
+        1    A     1     1    B
+
+        Sorting with a key function
+
+        >>> df.sort_values(by='col4', key=lambda col: col.str.lower())
+           col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+
+        Natural sort with the key argument,
+        using the `natsort ` package.
+
+        >>> df = pd.DataFrame({
+        ...    "time": ['0hr', '128hr', '72hr', '48hr', '96hr'],
+        ...    "value": [10, 20, 30, 40, 50]
+        ... })
+        >>> df
+            time  value
+        0    0hr     10
+        1  128hr     20
+        2   72hr     30
+        3   48hr     40
+        4   96hr     50
+        >>> from natsort import index_natsorted
+        >>> df.sort_values(
+        ...     by="time",
+        ...     key=lambda x: np.argsort(index_natsorted(df["time"]))
+        ... )
+            time  value
+        0    0hr     10
+        3   48hr     40
+        2   72hr     30
+        4   96hr     50
+        1  128hr     20
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        axis = self._get_axis_number(axis)
+        ascending = validate_ascending(ascending)
+        if not isinstance(by, list):
+            by = [by]
+        # error: Argument 1 to "len" has incompatible type "Union[bool, List[bool]]";
+        # expected "Sized"
+        if is_sequence(ascending) and (
+            len(by) != len(ascending)  # type: ignore[arg-type]
+        ):
+            # error: Argument 1 to "len" has incompatible type "Union[bool,
+            # List[bool]]"; expected "Sized"
+            raise ValueError(
+                f"Length of ascending ({len(ascending)})"  # type: ignore[arg-type]
+                f" != length of by ({len(by)})"
+            )
+        if len(by) > 1:
+            keys = [self._get_label_or_level_values(x, axis=axis) for x in by]
+
+            # need to rewrap columns in Series to apply key function
+            if key is not None:
+                # error: List comprehension has incompatible type List[Series];
+                # expected List[ndarray]
+                keys = [
+                    Series(k, name=name)  # type: ignore[misc]
+                    for (k, name) in zip(keys, by)
+                ]
+
+            indexer = lexsort_indexer(
+                keys, orders=ascending, na_position=na_position, key=key
+            )
+        elif len(by):
+            # len(by) == 1
+
+            k = self._get_label_or_level_values(by[0], axis=axis)
+
+            # need to rewrap column in Series to apply key function
+            if key is not None:
+                # error: Incompatible types in assignment (expression has type
+                # "Series", variable has type "ndarray")
+                k = Series(k, name=by[0])  # type: ignore[assignment]
+
+            if isinstance(ascending, (tuple, list)):
+                ascending = ascending[0]
+
+            indexer = nargsort(
+                k, kind=kind, ascending=ascending, na_position=na_position, key=key
+            )
+        else:
+            if inplace:
+                return self._update_inplace(self)
+            else:
+                return self.copy(deep=None)
+
+        if is_range_indexer(indexer, len(indexer)):
+            result = self.copy(deep=(not inplace and not using_copy_on_write()))
+            if ignore_index:
+                result.index = default_index(len(result))
+
+            if inplace:
+                return self._update_inplace(result)
+            else:
+                return result
+
+        new_data = self._mgr.take(
+            indexer, axis=self._get_block_manager_axis(axis), verify=False
+        )
+
+        if ignore_index:
+            new_data.set_axis(
+                self._get_block_manager_axis(axis), default_index(len(indexer))
+            )
+
+        result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="sort_values")
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: bool = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> DataFrame | None:
+        ...
+
+    def sort_index(
+        self,
+        *,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        ascending: bool | Sequence[bool] = True,
+        inplace: bool = False,
+        kind: SortKind = "quicksort",
+        na_position: NaPosition = "last",
+        sort_remaining: bool = True,
+        ignore_index: bool = False,
+        key: IndexKeyFunc | None = None,
+    ) -> DataFrame | None:
+        """
+        Sort object by labels (along an axis).
+
+        Returns a new DataFrame sorted by label if `inplace` argument is
+        ``False``, otherwise updates the original DataFrame and returns None.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis along which to sort.  The value 0 identifies the rows,
+            and 1 identifies the columns.
+        level : int or level name or list of ints or list of level names
+            If not None, sort on values in specified index level(s).
+        ascending : bool or list-like of bools, default True
+            Sort ascending vs. descending. When the index is a MultiIndex the
+            sort direction can be controlled for each level individually.
+        inplace : bool, default False
+            Whether to modify the DataFrame rather than creating a new one.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+            Choice of sorting algorithm. See also :func:`numpy.sort` for more
+            information. `mergesort` and `stable` are the only stable algorithms. For
+            DataFrames, this option is only applied when sorting on a single
+            column or label.
+        na_position : {'first', 'last'}, default 'last'
+            Puts NaNs at the beginning if `first`; `last` puts NaNs at the end.
+            Not implemented for MultiIndex.
+        sort_remaining : bool, default True
+            If True and sorting by level and index is multilevel, sort by other
+            levels too (in order) after sorting by specified level.
+        ignore_index : bool, default False
+            If True, the resulting axis will be labeled 0, 1, …, n - 1.
+        key : callable, optional
+            If not None, apply the key function to the index values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect an
+            ``Index`` and return an ``Index`` of the same shape. For MultiIndex
+            inputs, the key is applied *per level*.
+
+        Returns
+        -------
+        DataFrame or None
+            The original DataFrame sorted by the labels or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.sort_index : Sort Series by the index.
+        DataFrame.sort_values : Sort DataFrame by the value.
+        Series.sort_values : Sort Series by the value.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([1, 2, 3, 4, 5], index=[100, 29, 234, 1, 150],
+        ...                   columns=['A'])
+        >>> df.sort_index()
+             A
+        1    4
+        29   2
+        100  1
+        150  5
+        234  3
+
+        By default, it sorts in ascending order, to sort in descending order,
+        use ``ascending=False``
+
+        >>> df.sort_index(ascending=False)
+             A
+        234  3
+        150  5
+        100  1
+        29   2
+        1    4
+
+        A key function can be specified which is applied to the index before
+        sorting. For a ``MultiIndex`` this is applied to each level separately.
+
+        >>> df = pd.DataFrame({"a": [1, 2, 3, 4]}, index=['A', 'b', 'C', 'd'])
+        >>> df.sort_index(key=lambda x: x.str.lower())
+           a
+        A  1
+        b  2
+        C  3
+        d  4
+        """
+        return super().sort_index(
+            axis=axis,
+            level=level,
+            ascending=ascending,
+            inplace=inplace,
+            kind=kind,
+            na_position=na_position,
+            sort_remaining=sort_remaining,
+            ignore_index=ignore_index,
+            key=key,
+        )
+
+    def value_counts(
+        self,
+        subset: IndexLabel | None = None,
+        normalize: bool = False,
+        sort: bool = True,
+        ascending: bool = False,
+        dropna: bool = True,
+    ) -> Series:
+        """
+        Return a Series containing the frequency of each distinct row in the Dataframe.
+
+        Parameters
+        ----------
+        subset : label or list of labels, optional
+            Columns to use when counting unique combinations.
+        normalize : bool, default False
+            Return proportions rather than frequencies.
+        sort : bool, default True
+            Sort by frequencies when True. Sort by DataFrame column values when False.
+        ascending : bool, default False
+            Sort in ascending order.
+        dropna : bool, default True
+            Don't include counts of rows that contain NA values.
+
+            .. versionadded:: 1.3.0
+
+        Returns
+        -------
+        Series
+
+        See Also
+        --------
+        Series.value_counts: Equivalent method on Series.
+
+        Notes
+        -----
+        The returned Series will have a MultiIndex with one level per input
+        column but an Index (non-multi) for a single label. By default, rows
+        that contain any NA values are omitted from the result. By default,
+        the resulting Series will be in descending order so that the first
+        element is the most frequently-occurring row.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'num_legs': [2, 4, 4, 6],
+        ...                    'num_wings': [2, 0, 0, 0]},
+        ...                   index=['falcon', 'dog', 'cat', 'ant'])
+        >>> df
+                num_legs  num_wings
+        falcon         2          2
+        dog            4          0
+        cat            4          0
+        ant            6          0
+
+        >>> df.value_counts()
+        num_legs  num_wings
+        4         0            2
+        2         2            1
+        6         0            1
+        Name: count, dtype: int64
+
+        >>> df.value_counts(sort=False)
+        num_legs  num_wings
+        2         2            1
+        4         0            2
+        6         0            1
+        Name: count, dtype: int64
+
+        >>> df.value_counts(ascending=True)
+        num_legs  num_wings
+        2         2            1
+        6         0            1
+        4         0            2
+        Name: count, dtype: int64
+
+        >>> df.value_counts(normalize=True)
+        num_legs  num_wings
+        4         0            0.50
+        2         2            0.25
+        6         0            0.25
+        Name: proportion, dtype: float64
+
+        With `dropna` set to `False` we can also count rows with NA values.
+
+        >>> df = pd.DataFrame({'first_name': ['John', 'Anne', 'John', 'Beth'],
+        ...                    'middle_name': ['Smith', pd.NA, pd.NA, 'Louise']})
+        >>> df
+          first_name middle_name
+        0       John       Smith
+        1       Anne        
+        2       John        
+        3       Beth      Louise
+
+        >>> df.value_counts()
+        first_name  middle_name
+        Beth        Louise         1
+        John        Smith          1
+        Name: count, dtype: int64
+
+        >>> df.value_counts(dropna=False)
+        first_name  middle_name
+        Anne        NaN            1
+        Beth        Louise         1
+        John        Smith          1
+                    NaN            1
+        Name: count, dtype: int64
+
+        >>> df.value_counts("first_name")
+        first_name
+        John    2
+        Anne    1
+        Beth    1
+        Name: count, dtype: int64
+        """
+        if subset is None:
+            subset = self.columns.tolist()
+
+        name = "proportion" if normalize else "count"
+        counts = self.groupby(subset, dropna=dropna, observed=False)._grouper.size()
+        counts.name = name
+
+        if sort:
+            counts = counts.sort_values(ascending=ascending)
+        if normalize:
+            counts /= counts.sum()
+
+        # Force MultiIndex for a list_like subset with a single column
+        if is_list_like(subset) and len(subset) == 1:  # type: ignore[arg-type]
+            counts.index = MultiIndex.from_arrays(
+                [counts.index], names=[counts.index.name]
+            )
+
+        return counts
+
+    def nlargest(
+        self, n: int, columns: IndexLabel, keep: NsmallestNlargestKeep = "first"
+    ) -> DataFrame:
+        """
+        Return the first `n` rows ordered by `columns` in descending order.
+
+        Return the first `n` rows with the largest values in `columns`, in
+        descending order. The columns that are not specified are returned as
+        well, but not used for ordering.
+
+        This method is equivalent to
+        ``df.sort_values(columns, ascending=False).head(n)``, but more
+        performant.
+
+        Parameters
+        ----------
+        n : int
+            Number of rows to return.
+        columns : label or list of labels
+            Column label(s) to order by.
+        keep : {'first', 'last', 'all'}, default 'first'
+            Where there are duplicate values:
+
+            - ``first`` : prioritize the first occurrence(s)
+            - ``last`` : prioritize the last occurrence(s)
+            - ``all`` : keep all the ties of the smallest item even if it means
+              selecting more than ``n`` items.
+
+        Returns
+        -------
+        DataFrame
+            The first `n` rows ordered by the given columns in descending
+            order.
+
+        See Also
+        --------
+        DataFrame.nsmallest : Return the first `n` rows ordered by `columns` in
+            ascending order.
+        DataFrame.sort_values : Sort DataFrame by the values.
+        DataFrame.head : Return the first `n` rows without re-ordering.
+
+        Notes
+        -----
+        This function cannot be used with all column types. For example, when
+        specifying columns with `object` or `category` dtypes, ``TypeError`` is
+        raised.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'population': [59000000, 65000000, 434000,
+        ...                                   434000, 434000, 337000, 11300,
+        ...                                   11300, 11300],
+        ...                    'GDP': [1937894, 2583560 , 12011, 4520, 12128,
+        ...                            17036, 182, 38, 311],
+        ...                    'alpha-2': ["IT", "FR", "MT", "MV", "BN",
+        ...                                "IS", "NR", "TV", "AI"]},
+        ...                   index=["Italy", "France", "Malta",
+        ...                          "Maldives", "Brunei", "Iceland",
+        ...                          "Nauru", "Tuvalu", "Anguilla"])
+        >>> df
+                  population      GDP alpha-2
+        Italy       59000000  1937894      IT
+        France      65000000  2583560      FR
+        Malta         434000    12011      MT
+        Maldives      434000     4520      MV
+        Brunei        434000    12128      BN
+        Iceland       337000    17036      IS
+        Nauru          11300      182      NR
+        Tuvalu         11300       38      TV
+        Anguilla       11300      311      AI
+
+        In the following example, we will use ``nlargest`` to select the three
+        rows having the largest values in column "population".
+
+        >>> df.nlargest(3, 'population')
+                population      GDP alpha-2
+        France    65000000  2583560      FR
+        Italy     59000000  1937894      IT
+        Malta       434000    12011      MT
+
+        When using ``keep='last'``, ties are resolved in reverse order:
+
+        >>> df.nlargest(3, 'population', keep='last')
+                population      GDP alpha-2
+        France    65000000  2583560      FR
+        Italy     59000000  1937894      IT
+        Brunei      434000    12128      BN
+
+        When using ``keep='all'``, the number of element kept can go beyond ``n``
+        if there are duplicate values for the smallest element, all the
+        ties are kept:
+
+        >>> df.nlargest(3, 'population', keep='all')
+                  population      GDP alpha-2
+        France      65000000  2583560      FR
+        Italy       59000000  1937894      IT
+        Malta         434000    12011      MT
+        Maldives      434000     4520      MV
+        Brunei        434000    12128      BN
+
+        However, ``nlargest`` does not keep ``n`` distinct largest elements:
+
+        >>> df.nlargest(5, 'population', keep='all')
+                  population      GDP alpha-2
+        France      65000000  2583560      FR
+        Italy       59000000  1937894      IT
+        Malta         434000    12011      MT
+        Maldives      434000     4520      MV
+        Brunei        434000    12128      BN
+
+        To order by the largest values in column "population" and then "GDP",
+        we can specify multiple columns like in the next example.
+
+        >>> df.nlargest(3, ['population', 'GDP'])
+                population      GDP alpha-2
+        France    65000000  2583560      FR
+        Italy     59000000  1937894      IT
+        Brunei      434000    12128      BN
+        """
+        return selectn.SelectNFrame(self, n=n, keep=keep, columns=columns).nlargest()
+
+    def nsmallest(
+        self, n: int, columns: IndexLabel, keep: NsmallestNlargestKeep = "first"
+    ) -> DataFrame:
+        """
+        Return the first `n` rows ordered by `columns` in ascending order.
+
+        Return the first `n` rows with the smallest values in `columns`, in
+        ascending order. The columns that are not specified are returned as
+        well, but not used for ordering.
+
+        This method is equivalent to
+        ``df.sort_values(columns, ascending=True).head(n)``, but more
+        performant.
+
+        Parameters
+        ----------
+        n : int
+            Number of items to retrieve.
+        columns : list or str
+            Column name or names to order by.
+        keep : {'first', 'last', 'all'}, default 'first'
+            Where there are duplicate values:
+
+            - ``first`` : take the first occurrence.
+            - ``last`` : take the last occurrence.
+            - ``all`` : keep all the ties of the largest item even if it means
+              selecting more than ``n`` items.
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        DataFrame.nlargest : Return the first `n` rows ordered by `columns` in
+            descending order.
+        DataFrame.sort_values : Sort DataFrame by the values.
+        DataFrame.head : Return the first `n` rows without re-ordering.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'population': [59000000, 65000000, 434000,
+        ...                                   434000, 434000, 337000, 337000,
+        ...                                   11300, 11300],
+        ...                    'GDP': [1937894, 2583560 , 12011, 4520, 12128,
+        ...                            17036, 182, 38, 311],
+        ...                    'alpha-2': ["IT", "FR", "MT", "MV", "BN",
+        ...                                "IS", "NR", "TV", "AI"]},
+        ...                   index=["Italy", "France", "Malta",
+        ...                          "Maldives", "Brunei", "Iceland",
+        ...                          "Nauru", "Tuvalu", "Anguilla"])
+        >>> df
+                  population      GDP alpha-2
+        Italy       59000000  1937894      IT
+        France      65000000  2583560      FR
+        Malta         434000    12011      MT
+        Maldives      434000     4520      MV
+        Brunei        434000    12128      BN
+        Iceland       337000    17036      IS
+        Nauru         337000      182      NR
+        Tuvalu         11300       38      TV
+        Anguilla       11300      311      AI
+
+        In the following example, we will use ``nsmallest`` to select the
+        three rows having the smallest values in column "population".
+
+        >>> df.nsmallest(3, 'population')
+                  population    GDP alpha-2
+        Tuvalu         11300     38      TV
+        Anguilla       11300    311      AI
+        Iceland       337000  17036      IS
+
+        When using ``keep='last'``, ties are resolved in reverse order:
+
+        >>> df.nsmallest(3, 'population', keep='last')
+                  population  GDP alpha-2
+        Anguilla       11300  311      AI
+        Tuvalu         11300   38      TV
+        Nauru         337000  182      NR
+
+        When using ``keep='all'``, the number of element kept can go beyond ``n``
+        if there are duplicate values for the largest element, all the
+        ties are kept.
+
+        >>> df.nsmallest(3, 'population', keep='all')
+                  population    GDP alpha-2
+        Tuvalu         11300     38      TV
+        Anguilla       11300    311      AI
+        Iceland       337000  17036      IS
+        Nauru         337000    182      NR
+
+        However, ``nsmallest`` does not keep ``n`` distinct
+        smallest elements:
+
+        >>> df.nsmallest(4, 'population', keep='all')
+                  population    GDP alpha-2
+        Tuvalu         11300     38      TV
+        Anguilla       11300    311      AI
+        Iceland       337000  17036      IS
+        Nauru         337000    182      NR
+
+        To order by the smallest values in column "population" and then "GDP", we can
+        specify multiple columns like in the next example.
+
+        >>> df.nsmallest(3, ['population', 'GDP'])
+                  population  GDP alpha-2
+        Tuvalu         11300   38      TV
+        Anguilla       11300  311      AI
+        Nauru         337000  182      NR
+        """
+        return selectn.SelectNFrame(self, n=n, keep=keep, columns=columns).nsmallest()
+
+    @doc(
+        Series.swaplevel,
+        klass=_shared_doc_kwargs["klass"],
+        extra_params=dedent(
+            """axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to swap levels on. 0 or 'index' for row-wise, 1 or
+            'columns' for column-wise."""
+        ),
+        examples=dedent(
+            """\
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {"Grade": ["A", "B", "A", "C"]},
+        ...     index=[
+        ...         ["Final exam", "Final exam", "Coursework", "Coursework"],
+        ...         ["History", "Geography", "History", "Geography"],
+        ...         ["January", "February", "March", "April"],
+        ...     ],
+        ... )
+        >>> df
+                                            Grade
+        Final exam  History     January      A
+                    Geography   February     B
+        Coursework  History     March        A
+                    Geography   April        C
+
+        In the following example, we will swap the levels of the indices.
+        Here, we will swap the levels column-wise, but levels can be swapped row-wise
+        in a similar manner. Note that column-wise is the default behaviour.
+        By not supplying any arguments for i and j, we swap the last and second to
+        last indices.
+
+        >>> df.swaplevel()
+                                            Grade
+        Final exam  January     History         A
+                    February    Geography       B
+        Coursework  March       History         A
+                    April       Geography       C
+
+        By supplying one argument, we can choose which index to swap the last
+        index with. We can for example swap the first index with the last one as
+        follows.
+
+        >>> df.swaplevel(0)
+                                            Grade
+        January     History     Final exam      A
+        February    Geography   Final exam      B
+        March       History     Coursework      A
+        April       Geography   Coursework      C
+
+        We can also define explicitly which indices we want to swap by supplying values
+        for both i and j. Here, we for example swap the first and second indices.
+
+        >>> df.swaplevel(0, 1)
+                                            Grade
+        History     Final exam  January         A
+        Geography   Final exam  February        B
+        History     Coursework  March           A
+        Geography   Coursework  April           C"""
+        ),
+    )
+    def swaplevel(self, i: Axis = -2, j: Axis = -1, axis: Axis = 0) -> DataFrame:
+        result = self.copy(deep=None)
+
+        axis = self._get_axis_number(axis)
+
+        if not isinstance(result._get_axis(axis), MultiIndex):  # pragma: no cover
+            raise TypeError("Can only swap levels on a hierarchical axis.")
+
+        if axis == 0:
+            assert isinstance(result.index, MultiIndex)
+            result.index = result.index.swaplevel(i, j)
+        else:
+            assert isinstance(result.columns, MultiIndex)
+            result.columns = result.columns.swaplevel(i, j)
+        return result
+
+    def reorder_levels(self, order: Sequence[int | str], axis: Axis = 0) -> DataFrame:
+        """
+        Rearrange index levels using input order. May not drop or duplicate levels.
+
+        Parameters
+        ----------
+        order : list of int or list of str
+            List representing new level order. Reference level by number
+            (position) or by key (label).
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Where to reorder levels.
+
+        Returns
+        -------
+        DataFrame
+
+        Examples
+        --------
+        >>> data = {
+        ...     "class": ["Mammals", "Mammals", "Reptiles"],
+        ...     "diet": ["Omnivore", "Carnivore", "Carnivore"],
+        ...     "species": ["Humans", "Dogs", "Snakes"],
+        ... }
+        >>> df = pd.DataFrame(data, columns=["class", "diet", "species"])
+        >>> df = df.set_index(["class", "diet"])
+        >>> df
+                                          species
+        class      diet
+        Mammals    Omnivore                Humans
+                   Carnivore                 Dogs
+        Reptiles   Carnivore               Snakes
+
+        Let's reorder the levels of the index:
+
+        >>> df.reorder_levels(["diet", "class"])
+                                          species
+        diet      class
+        Omnivore  Mammals                  Humans
+        Carnivore Mammals                    Dogs
+                  Reptiles                 Snakes
+        """
+        axis = self._get_axis_number(axis)
+        if not isinstance(self._get_axis(axis), MultiIndex):  # pragma: no cover
+            raise TypeError("Can only reorder levels on a hierarchical axis.")
+
+        result = self.copy(deep=None)
+
+        if axis == 0:
+            assert isinstance(result.index, MultiIndex)
+            result.index = result.index.reorder_levels(order)
+        else:
+            assert isinstance(result.columns, MultiIndex)
+            result.columns = result.columns.reorder_levels(order)
+        return result
+
+    # ----------------------------------------------------------------------
+    # Arithmetic Methods
+
+    def _cmp_method(self, other, op):
+        axis: Literal[1] = 1  # only relevant for Series other case
+
+        self, other = self._align_for_op(other, axis, flex=False, level=None)
+
+        # See GH#4537 for discussion of scalar op behavior
+        new_data = self._dispatch_frame_op(other, op, axis=axis)
+        return self._construct_result(new_data)
+
+    def _arith_method(self, other, op):
+        if self._should_reindex_frame_op(other, op, 1, None, None):
+            return self._arith_method_with_reindex(other, op)
+
+        axis: Literal[1] = 1  # only relevant for Series other case
+        other = ops.maybe_prepare_scalar_for_op(other, (self.shape[axis],))
+
+        self, other = self._align_for_op(other, axis, flex=True, level=None)
+
+        with np.errstate(all="ignore"):
+            new_data = self._dispatch_frame_op(other, op, axis=axis)
+        return self._construct_result(new_data)
+
+    _logical_method = _arith_method
+
+    def _dispatch_frame_op(
+        self, right, func: Callable, axis: AxisInt | None = None
+    ) -> DataFrame:
+        """
+        Evaluate the frame operation func(left, right) by evaluating
+        column-by-column, dispatching to the Series implementation.
+
+        Parameters
+        ----------
+        right : scalar, Series, or DataFrame
+        func : arithmetic or comparison operator
+        axis : {None, 0, 1}
+
+        Returns
+        -------
+        DataFrame
+
+        Notes
+        -----
+        Caller is responsible for setting np.errstate where relevant.
+        """
+        # Get the appropriate array-op to apply to each column/block's values.
+        array_op = ops.get_array_op(func)
+
+        right = lib.item_from_zerodim(right)
+        if not is_list_like(right):
+            # i.e. scalar, faster than checking np.ndim(right) == 0
+            bm = self._mgr.apply(array_op, right=right)
+            return self._constructor_from_mgr(bm, axes=bm.axes)
+
+        elif isinstance(right, DataFrame):
+            assert self.index.equals(right.index)
+            assert self.columns.equals(right.columns)
+            # TODO: The previous assertion `assert right._indexed_same(self)`
+            #  fails in cases with empty columns reached via
+            #  _frame_arith_method_with_reindex
+
+            # TODO operate_blockwise expects a manager of the same type
+            bm = self._mgr.operate_blockwise(
+                # error: Argument 1 to "operate_blockwise" of "ArrayManager" has
+                # incompatible type "Union[ArrayManager, BlockManager]"; expected
+                # "ArrayManager"
+                # error: Argument 1 to "operate_blockwise" of "BlockManager" has
+                # incompatible type "Union[ArrayManager, BlockManager]"; expected
+                # "BlockManager"
+                right._mgr,  # type: ignore[arg-type]
+                array_op,
+            )
+            return self._constructor_from_mgr(bm, axes=bm.axes)
+
+        elif isinstance(right, Series) and axis == 1:
+            # axis=1 means we want to operate row-by-row
+            assert right.index.equals(self.columns)
+
+            right = right._values
+            # maybe_align_as_frame ensures we do not have an ndarray here
+            assert not isinstance(right, np.ndarray)
+
+            arrays = [
+                array_op(_left, _right)
+                for _left, _right in zip(self._iter_column_arrays(), right)
+            ]
+
+        elif isinstance(right, Series):
+            assert right.index.equals(self.index)
+            right = right._values
+
+            arrays = [array_op(left, right) for left in self._iter_column_arrays()]
+
+        else:
+            raise NotImplementedError(right)
+
+        return type(self)._from_arrays(
+            arrays, self.columns, self.index, verify_integrity=False
+        )
+
+    def _combine_frame(self, other: DataFrame, func, fill_value=None):
+        # at this point we have `self._indexed_same(other)`
+
+        if fill_value is None:
+            # since _arith_op may be called in a loop, avoid function call
+            #  overhead if possible by doing this check once
+            _arith_op = func
+
+        else:
+
+            def _arith_op(left, right):
+                # for the mixed_type case where we iterate over columns,
+                # _arith_op(left, right) is equivalent to
+                # left._binop(right, func, fill_value=fill_value)
+                left, right = ops.fill_binop(left, right, fill_value)
+                return func(left, right)
+
+        new_data = self._dispatch_frame_op(other, _arith_op)
+        return new_data
+
+    def _arith_method_with_reindex(self, right: DataFrame, op) -> DataFrame:
+        """
+        For DataFrame-with-DataFrame operations that require reindexing,
+        operate only on shared columns, then reindex.
+
+        Parameters
+        ----------
+        right : DataFrame
+        op : binary operator
+
+        Returns
+        -------
+        DataFrame
+        """
+        left = self
+
+        # GH#31623, only operate on shared columns
+        cols, lcols, rcols = left.columns.join(
+            right.columns, how="inner", level=None, return_indexers=True
+        )
+
+        new_left = left.iloc[:, lcols]
+        new_right = right.iloc[:, rcols]
+        result = op(new_left, new_right)
+
+        # Do the join on the columns instead of using left._align_for_op
+        #  to avoid constructing two potentially large/sparse DataFrames
+        join_columns, _, _ = left.columns.join(
+            right.columns, how="outer", level=None, return_indexers=True
+        )
+
+        if result.columns.has_duplicates:
+            # Avoid reindexing with a duplicate axis.
+            # https://github.com/pandas-dev/pandas/issues/35194
+            indexer, _ = result.columns.get_indexer_non_unique(join_columns)
+            indexer = algorithms.unique1d(indexer)
+            result = result._reindex_with_indexers(
+                {1: [join_columns, indexer]}, allow_dups=True
+            )
+        else:
+            result = result.reindex(join_columns, axis=1)
+
+        return result
+
+    def _should_reindex_frame_op(self, right, op, axis: int, fill_value, level) -> bool:
+        """
+        Check if this is an operation between DataFrames that will need to reindex.
+        """
+        if op is operator.pow or op is roperator.rpow:
+            # GH#32685 pow has special semantics for operating with null values
+            return False
+
+        if not isinstance(right, DataFrame):
+            return False
+
+        if fill_value is None and level is None and axis == 1:
+            # TODO: any other cases we should handle here?
+
+            # Intersection is always unique so we have to check the unique columns
+            left_uniques = self.columns.unique()
+            right_uniques = right.columns.unique()
+            cols = left_uniques.intersection(right_uniques)
+            if len(cols) and not (
+                len(cols) == len(left_uniques) and len(cols) == len(right_uniques)
+            ):
+                # TODO: is there a shortcut available when len(cols) == 0?
+                return True
+
+        return False
+
+    def _align_for_op(
+        self,
+        other,
+        axis: AxisInt,
+        flex: bool | None = False,
+        level: Level | None = None,
+    ):
+        """
+        Convert rhs to meet lhs dims if input is list, tuple or np.ndarray.
+
+        Parameters
+        ----------
+        left : DataFrame
+        right : Any
+        axis : int
+        flex : bool or None, default False
+            Whether this is a flex op, in which case we reindex.
+            None indicates not to check for alignment.
+        level : int or level name, default None
+
+        Returns
+        -------
+        left : DataFrame
+        right : Any
+        """
+        left, right = self, other
+
+        def to_series(right):
+            msg = (
+                "Unable to coerce to Series, "
+                "length must be {req_len}: given {given_len}"
+            )
+
+            # pass dtype to avoid doing inference, which would break consistency
+            #  with Index/Series ops
+            dtype = None
+            if getattr(right, "dtype", None) == object:
+                # can't pass right.dtype unconditionally as that would break on e.g.
+                #  datetime64[h] ndarray
+                dtype = object
+
+            if axis == 0:
+                if len(left.index) != len(right):
+                    raise ValueError(
+                        msg.format(req_len=len(left.index), given_len=len(right))
+                    )
+                right = left._constructor_sliced(right, index=left.index, dtype=dtype)
+            else:
+                if len(left.columns) != len(right):
+                    raise ValueError(
+                        msg.format(req_len=len(left.columns), given_len=len(right))
+                    )
+                right = left._constructor_sliced(right, index=left.columns, dtype=dtype)
+            return right
+
+        if isinstance(right, np.ndarray):
+            if right.ndim == 1:
+                right = to_series(right)
+
+            elif right.ndim == 2:
+                # We need to pass dtype=right.dtype to retain object dtype
+                #  otherwise we lose consistency with Index and array ops
+                dtype = None
+                if right.dtype == object:
+                    # can't pass right.dtype unconditionally as that would break on e.g.
+                    #  datetime64[h] ndarray
+                    dtype = object
+
+                if right.shape == left.shape:
+                    right = left._constructor(
+                        right, index=left.index, columns=left.columns, dtype=dtype
+                    )
+
+                elif right.shape[0] == left.shape[0] and right.shape[1] == 1:
+                    # Broadcast across columns
+                    right = np.broadcast_to(right, left.shape)
+                    right = left._constructor(
+                        right, index=left.index, columns=left.columns, dtype=dtype
+                    )
+
+                elif right.shape[1] == left.shape[1] and right.shape[0] == 1:
+                    # Broadcast along rows
+                    right = to_series(right[0, :])
+
+                else:
+                    raise ValueError(
+                        "Unable to coerce to DataFrame, shape "
+                        f"must be {left.shape}: given {right.shape}"
+                    )
+
+            elif right.ndim > 2:
+                raise ValueError(
+                    "Unable to coerce to Series/DataFrame, "
+                    f"dimension must be <= 2: {right.shape}"
+                )
+
+        elif is_list_like(right) and not isinstance(right, (Series, DataFrame)):
+            # GH#36702. Raise when attempting arithmetic with list of array-like.
+            if any(is_array_like(el) for el in right):
+                raise ValueError(
+                    f"Unable to coerce list of {type(right[0])} to Series/DataFrame"
+                )
+            # GH#17901
+            right = to_series(right)
+
+        if flex is not None and isinstance(right, DataFrame):
+            if not left._indexed_same(right):
+                if flex:
+                    left, right = left.align(
+                        right, join="outer", level=level, copy=False
+                    )
+                else:
+                    raise ValueError(
+                        "Can only compare identically-labeled (both index and columns) "
+                        "DataFrame objects"
+                    )
+        elif isinstance(right, Series):
+            # axis=1 is default for DataFrame-with-Series op
+            axis = axis if axis is not None else 1
+            if not flex:
+                if not left.axes[axis].equals(right.index):
+                    raise ValueError(
+                        "Operands are not aligned. Do "
+                        "`left, right = left.align(right, axis=1, copy=False)` "
+                        "before operating."
+                    )
+
+            left, right = left.align(
+                right,
+                join="outer",
+                axis=axis,
+                level=level,
+                copy=False,
+            )
+            right = left._maybe_align_series_as_frame(right, axis)
+
+        return left, right
+
+    def _maybe_align_series_as_frame(self, series: Series, axis: AxisInt):
+        """
+        If the Series operand is not EA-dtype, we can broadcast to 2D and operate
+        blockwise.
+        """
+        rvalues = series._values
+        if not isinstance(rvalues, np.ndarray):
+            # TODO(EA2D): no need to special-case with 2D EAs
+            if rvalues.dtype in ("datetime64[ns]", "timedelta64[ns]"):
+                # We can losslessly+cheaply cast to ndarray
+                rvalues = np.asarray(rvalues)
+            else:
+                return series
+
+        if axis == 0:
+            rvalues = rvalues.reshape(-1, 1)
+        else:
+            rvalues = rvalues.reshape(1, -1)
+
+        rvalues = np.broadcast_to(rvalues, self.shape)
+        # pass dtype to avoid doing inference
+        return self._constructor(
+            rvalues,
+            index=self.index,
+            columns=self.columns,
+            dtype=rvalues.dtype,
+        )
+
+    def _flex_arith_method(
+        self, other, op, *, axis: Axis = "columns", level=None, fill_value=None
+    ):
+        axis = self._get_axis_number(axis) if axis is not None else 1
+
+        if self._should_reindex_frame_op(other, op, axis, fill_value, level):
+            return self._arith_method_with_reindex(other, op)
+
+        if isinstance(other, Series) and fill_value is not None:
+            # TODO: We could allow this in cases where we end up going
+            #  through the DataFrame path
+            raise NotImplementedError(f"fill_value {fill_value} not supported.")
+
+        other = ops.maybe_prepare_scalar_for_op(other, self.shape)
+        self, other = self._align_for_op(other, axis, flex=True, level=level)
+
+        with np.errstate(all="ignore"):
+            if isinstance(other, DataFrame):
+                # Another DataFrame
+                new_data = self._combine_frame(other, op, fill_value)
+
+            elif isinstance(other, Series):
+                new_data = self._dispatch_frame_op(other, op, axis=axis)
+            else:
+                # in this case we always have `np.ndim(other) == 0`
+                if fill_value is not None:
+                    self = self.fillna(fill_value)
+
+                new_data = self._dispatch_frame_op(other, op)
+
+        return self._construct_result(new_data)
+
+    def _construct_result(self, result) -> DataFrame:
+        """
+        Wrap the result of an arithmetic, comparison, or logical operation.
+
+        Parameters
+        ----------
+        result : DataFrame
+
+        Returns
+        -------
+        DataFrame
+        """
+        out = self._constructor(result, copy=False).__finalize__(self)
+        # Pin columns instead of passing to constructor for compat with
+        #  non-unique columns case
+        out.columns = self.columns
+        out.index = self.index
+        return out
+
+    def __divmod__(self, other) -> tuple[DataFrame, DataFrame]:
+        # Naive implementation, room for optimization
+        div = self // other
+        mod = self - div * other
+        return div, mod
+
+    def __rdivmod__(self, other) -> tuple[DataFrame, DataFrame]:
+        # Naive implementation, room for optimization
+        div = other // self
+        mod = other - div * self
+        return div, mod
+
+    def _flex_cmp_method(self, other, op, *, axis: Axis = "columns", level=None):
+        axis = self._get_axis_number(axis) if axis is not None else 1
+
+        self, other = self._align_for_op(other, axis, flex=True, level=level)
+
+        new_data = self._dispatch_frame_op(other, op, axis=axis)
+        return self._construct_result(new_data)
+
+    @Appender(ops.make_flex_doc("eq", "dataframe"))
+    def eq(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.eq, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("ne", "dataframe"))
+    def ne(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.ne, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("le", "dataframe"))
+    def le(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.le, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("lt", "dataframe"))
+    def lt(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.lt, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("ge", "dataframe"))
+    def ge(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.ge, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("gt", "dataframe"))
+    def gt(self, other, axis: Axis = "columns", level=None) -> DataFrame:
+        return self._flex_cmp_method(other, operator.gt, axis=axis, level=level)
+
+    @Appender(ops.make_flex_doc("add", "dataframe"))
+    def add(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.add, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("radd", "dataframe"))
+    def radd(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.radd, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("sub", "dataframe"))
+    def sub(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.sub, level=level, fill_value=fill_value, axis=axis
+        )
+
+    subtract = sub
+
+    @Appender(ops.make_flex_doc("rsub", "dataframe"))
+    def rsub(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rsub, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("mul", "dataframe"))
+    def mul(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.mul, level=level, fill_value=fill_value, axis=axis
+        )
+
+    multiply = mul
+
+    @Appender(ops.make_flex_doc("rmul", "dataframe"))
+    def rmul(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rmul, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("truediv", "dataframe"))
+    def truediv(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.truediv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    div = truediv
+    divide = truediv
+
+    @Appender(ops.make_flex_doc("rtruediv", "dataframe"))
+    def rtruediv(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rtruediv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    rdiv = rtruediv
+
+    @Appender(ops.make_flex_doc("floordiv", "dataframe"))
+    def floordiv(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.floordiv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rfloordiv", "dataframe"))
+    def rfloordiv(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rfloordiv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("mod", "dataframe"))
+    def mod(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.mod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rmod", "dataframe"))
+    def rmod(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rmod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("pow", "dataframe"))
+    def pow(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, operator.pow, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rpow", "dataframe"))
+    def rpow(
+        self, other, axis: Axis = "columns", level=None, fill_value=None
+    ) -> DataFrame:
+        return self._flex_arith_method(
+            other, roperator.rpow, level=level, fill_value=fill_value, axis=axis
+        )
+
+    # ----------------------------------------------------------------------
+    # Combination-Related
+
+    @doc(
+        _shared_docs["compare"],
+        dedent(
+            """
+        Returns
+        -------
+        DataFrame
+            DataFrame that shows the differences stacked side by side.
+
+            The resulting index will be a MultiIndex with 'self' and 'other'
+            stacked alternately at the inner level.
+
+        Raises
+        ------
+        ValueError
+            When the two DataFrames don't have identical labels or shape.
+
+        See Also
+        --------
+        Series.compare : Compare with another Series and show differences.
+        DataFrame.equals : Test whether two objects contain the same elements.
+
+        Notes
+        -----
+        Matching NaNs will not appear as a difference.
+
+        Can only compare identically-labeled
+        (i.e. same shape, identical row and column labels) DataFrames
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {{
+        ...         "col1": ["a", "a", "b", "b", "a"],
+        ...         "col2": [1.0, 2.0, 3.0, np.nan, 5.0],
+        ...         "col3": [1.0, 2.0, 3.0, 4.0, 5.0]
+        ...     }},
+        ...     columns=["col1", "col2", "col3"],
+        ... )
+        >>> df
+          col1  col2  col3
+        0    a   1.0   1.0
+        1    a   2.0   2.0
+        2    b   3.0   3.0
+        3    b   NaN   4.0
+        4    a   5.0   5.0
+
+        >>> df2 = df.copy()
+        >>> df2.loc[0, 'col1'] = 'c'
+        >>> df2.loc[2, 'col3'] = 4.0
+        >>> df2
+          col1  col2  col3
+        0    c   1.0   1.0
+        1    a   2.0   2.0
+        2    b   3.0   4.0
+        3    b   NaN   4.0
+        4    a   5.0   5.0
+
+        Align the differences on columns
+
+        >>> df.compare(df2)
+          col1       col3
+          self other self other
+        0    a     c  NaN   NaN
+        2  NaN   NaN  3.0   4.0
+
+        Assign result_names
+
+        >>> df.compare(df2, result_names=("left", "right"))
+          col1       col3
+          left right left right
+        0    a     c  NaN   NaN
+        2  NaN   NaN  3.0   4.0
+
+        Stack the differences on rows
+
+        >>> df.compare(df2, align_axis=0)
+                col1  col3
+        0 self     a   NaN
+          other    c   NaN
+        2 self   NaN   3.0
+          other  NaN   4.0
+
+        Keep the equal values
+
+        >>> df.compare(df2, keep_equal=True)
+          col1       col3
+          self other self other
+        0    a     c  1.0   1.0
+        2    b     b  3.0   4.0
+
+        Keep all original rows and columns
+
+        >>> df.compare(df2, keep_shape=True)
+          col1       col2       col3
+          self other self other self other
+        0    a     c  NaN   NaN  NaN   NaN
+        1  NaN   NaN  NaN   NaN  NaN   NaN
+        2  NaN   NaN  NaN   NaN  3.0   4.0
+        3  NaN   NaN  NaN   NaN  NaN   NaN
+        4  NaN   NaN  NaN   NaN  NaN   NaN
+
+        Keep all original rows and columns and also all original values
+
+        >>> df.compare(df2, keep_shape=True, keep_equal=True)
+          col1       col2       col3
+          self other self other self other
+        0    a     c  1.0   1.0  1.0   1.0
+        1    a     a  2.0   2.0  2.0   2.0
+        2    b     b  3.0   3.0  3.0   4.0
+        3    b     b  NaN   NaN  4.0   4.0
+        4    a     a  5.0   5.0  5.0   5.0
+        """
+        ),
+        klass=_shared_doc_kwargs["klass"],
+    )
+    def compare(
+        self,
+        other: DataFrame,
+        align_axis: Axis = 1,
+        keep_shape: bool = False,
+        keep_equal: bool = False,
+        result_names: Suffixes = ("self", "other"),
+    ) -> DataFrame:
+        return super().compare(
+            other=other,
+            align_axis=align_axis,
+            keep_shape=keep_shape,
+            keep_equal=keep_equal,
+            result_names=result_names,
+        )
+
+    def combine(
+        self,
+        other: DataFrame,
+        func: Callable[[Series, Series], Series | Hashable],
+        fill_value=None,
+        overwrite: bool = True,
+    ) -> DataFrame:
+        """
+        Perform column-wise combine with another DataFrame.
+
+        Combines a DataFrame with `other` DataFrame using `func`
+        to element-wise combine columns. The row and column indexes of the
+        resulting DataFrame will be the union of the two.
+
+        Parameters
+        ----------
+        other : DataFrame
+            The DataFrame to merge column-wise.
+        func : function
+            Function that takes two series as inputs and return a Series or a
+            scalar. Used to merge the two dataframes column by columns.
+        fill_value : scalar value, default None
+            The value to fill NaNs with prior to passing any column to the
+            merge func.
+        overwrite : bool, default True
+            If True, columns in `self` that do not exist in `other` will be
+            overwritten with NaNs.
+
+        Returns
+        -------
+        DataFrame
+            Combination of the provided DataFrames.
+
+        See Also
+        --------
+        DataFrame.combine_first : Combine two DataFrame objects and default to
+            non-null values in frame calling the method.
+
+        Examples
+        --------
+        Combine using a simple function that chooses the smaller column.
+
+        >>> df1 = pd.DataFrame({'A': [0, 0], 'B': [4, 4]})
+        >>> df2 = pd.DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> take_smaller = lambda s1, s2: s1 if s1.sum() < s2.sum() else s2
+        >>> df1.combine(df2, take_smaller)
+           A  B
+        0  0  3
+        1  0  3
+
+        Example using a true element-wise combine function.
+
+        >>> df1 = pd.DataFrame({'A': [5, 0], 'B': [2, 4]})
+        >>> df2 = pd.DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> df1.combine(df2, np.minimum)
+           A  B
+        0  1  2
+        1  0  3
+
+        Using `fill_value` fills Nones prior to passing the column to the
+        merge function.
+
+        >>> df1 = pd.DataFrame({'A': [0, 0], 'B': [None, 4]})
+        >>> df2 = pd.DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> df1.combine(df2, take_smaller, fill_value=-5)
+           A    B
+        0  0 -5.0
+        1  0  4.0
+
+        However, if the same element in both dataframes is None, that None
+        is preserved
+
+        >>> df1 = pd.DataFrame({'A': [0, 0], 'B': [None, 4]})
+        >>> df2 = pd.DataFrame({'A': [1, 1], 'B': [None, 3]})
+        >>> df1.combine(df2, take_smaller, fill_value=-5)
+            A    B
+        0  0 -5.0
+        1  0  3.0
+
+        Example that demonstrates the use of `overwrite` and behavior when
+        the axis differ between the dataframes.
+
+        >>> df1 = pd.DataFrame({'A': [0, 0], 'B': [4, 4]})
+        >>> df2 = pd.DataFrame({'B': [3, 3], 'C': [-10, 1], }, index=[1, 2])
+        >>> df1.combine(df2, take_smaller)
+             A    B     C
+        0  NaN  NaN   NaN
+        1  NaN  3.0 -10.0
+        2  NaN  3.0   1.0
+
+        >>> df1.combine(df2, take_smaller, overwrite=False)
+             A    B     C
+        0  0.0  NaN   NaN
+        1  0.0  3.0 -10.0
+        2  NaN  3.0   1.0
+
+        Demonstrating the preference of the passed in dataframe.
+
+        >>> df2 = pd.DataFrame({'B': [3, 3], 'C': [1, 1], }, index=[1, 2])
+        >>> df2.combine(df1, take_smaller)
+           A    B   C
+        0  0.0  NaN NaN
+        1  0.0  3.0 NaN
+        2  NaN  3.0 NaN
+
+        >>> df2.combine(df1, take_smaller, overwrite=False)
+             A    B   C
+        0  0.0  NaN NaN
+        1  0.0  3.0 1.0
+        2  NaN  3.0 1.0
+        """
+        other_idxlen = len(other.index)  # save for compare
+
+        this, other = self.align(other, copy=False)
+        new_index = this.index
+
+        if other.empty and len(new_index) == len(self.index):
+            return self.copy()
+
+        if self.empty and len(other) == other_idxlen:
+            return other.copy()
+
+        # sorts if possible; otherwise align above ensures that these are set-equal
+        new_columns = this.columns.union(other.columns)
+        do_fill = fill_value is not None
+        result = {}
+        for col in new_columns:
+            series = this[col]
+            other_series = other[col]
+
+            this_dtype = series.dtype
+            other_dtype = other_series.dtype
+
+            this_mask = isna(series)
+            other_mask = isna(other_series)
+
+            # don't overwrite columns unnecessarily
+            # DO propagate if this column is not in the intersection
+            if not overwrite and other_mask.all():
+                result[col] = this[col].copy()
+                continue
+
+            if do_fill:
+                series = series.copy()
+                other_series = other_series.copy()
+                series[this_mask] = fill_value
+                other_series[other_mask] = fill_value
+
+            if col not in self.columns:
+                # If self DataFrame does not have col in other DataFrame,
+                # try to promote series, which is all NaN, as other_dtype.
+                new_dtype = other_dtype
+                try:
+                    series = series.astype(new_dtype, copy=False)
+                except ValueError:
+                    # e.g. new_dtype is integer types
+                    pass
+            else:
+                # if we have different dtypes, possibly promote
+                new_dtype = find_common_type([this_dtype, other_dtype])
+                series = series.astype(new_dtype, copy=False)
+                other_series = other_series.astype(new_dtype, copy=False)
+
+            arr = func(series, other_series)
+            if isinstance(new_dtype, np.dtype):
+                # if new_dtype is an EA Dtype, then `func` is expected to return
+                # the correct dtype without any additional casting
+                # error: No overload variant of "maybe_downcast_to_dtype" matches
+                # argument types "Union[Series, Hashable]", "dtype[Any]"
+                arr = maybe_downcast_to_dtype(  # type: ignore[call-overload]
+                    arr, new_dtype
+                )
+
+            result[col] = arr
+
+        # convert_objects just in case
+        frame_result = self._constructor(result, index=new_index, columns=new_columns)
+        return frame_result.__finalize__(self, method="combine")
+
+    def combine_first(self, other: DataFrame) -> DataFrame:
+        """
+        Update null elements with value in the same location in `other`.
+
+        Combine two DataFrame objects by filling null values in one DataFrame
+        with non-null values from other DataFrame. The row and column indexes
+        of the resulting DataFrame will be the union of the two. The resulting
+        dataframe contains the 'first' dataframe values and overrides the
+        second one values where both first.loc[index, col] and
+        second.loc[index, col] are not missing values, upon calling
+        first.combine_first(second).
+
+        Parameters
+        ----------
+        other : DataFrame
+            Provided DataFrame to use to fill null values.
+
+        Returns
+        -------
+        DataFrame
+            The result of combining the provided DataFrame with the other object.
+
+        See Also
+        --------
+        DataFrame.combine : Perform series-wise operation on two DataFrames
+            using a given function.
+
+        Examples
+        --------
+        >>> df1 = pd.DataFrame({'A': [None, 0], 'B': [None, 4]})
+        >>> df2 = pd.DataFrame({'A': [1, 1], 'B': [3, 3]})
+        >>> df1.combine_first(df2)
+             A    B
+        0  1.0  3.0
+        1  0.0  4.0
+
+        Null values still persist if the location of that null value
+        does not exist in `other`
+
+        >>> df1 = pd.DataFrame({'A': [None, 0], 'B': [4, None]})
+        >>> df2 = pd.DataFrame({'B': [3, 3], 'C': [1, 1]}, index=[1, 2])
+        >>> df1.combine_first(df2)
+             A    B    C
+        0  NaN  4.0  NaN
+        1  0.0  3.0  1.0
+        2  NaN  3.0  1.0
+        """
+        from pandas.core.computation import expressions
+
+        def combiner(x: Series, y: Series):
+            mask = x.isna()._values
+
+            x_values = x._values
+            y_values = y._values
+
+            # If the column y in other DataFrame is not in first DataFrame,
+            # just return y_values.
+            if y.name not in self.columns:
+                return y_values
+
+            return expressions.where(mask, y_values, x_values)
+
+        if len(other) == 0:
+            combined = self.reindex(
+                self.columns.append(other.columns.difference(self.columns)), axis=1
+            )
+            combined = combined.astype(other.dtypes)
+        else:
+            combined = self.combine(other, combiner, overwrite=False)
+
+        dtypes = {
+            col: find_common_type([self.dtypes[col], other.dtypes[col]])
+            for col in self.columns.intersection(other.columns)
+            if combined.dtypes[col] != self.dtypes[col]
+        }
+
+        if dtypes:
+            combined = combined.astype(dtypes)
+
+        return combined.__finalize__(self, method="combine_first")
+
+    def update(
+        self,
+        other,
+        join: UpdateJoin = "left",
+        overwrite: bool = True,
+        filter_func=None,
+        errors: IgnoreRaise = "ignore",
+    ) -> None:
+        """
+        Modify in place using non-NA values from another DataFrame.
+
+        Aligns on indices. There is no return value.
+
+        Parameters
+        ----------
+        other : DataFrame, or object coercible into a DataFrame
+            Should have at least one matching index/column label
+            with the original DataFrame. If a Series is passed,
+            its name attribute must be set, and that will be
+            used as the column name to align with the original DataFrame.
+        join : {'left'}, default 'left'
+            Only left join is implemented, keeping the index and columns of the
+            original object.
+        overwrite : bool, default True
+            How to handle non-NA values for overlapping keys:
+
+            * True: overwrite original DataFrame's values
+              with values from `other`.
+            * False: only update values that are NA in
+              the original DataFrame.
+
+        filter_func : callable(1d-array) -> bool 1d-array, optional
+            Can choose to replace values other than NA. Return True for values
+            that should be updated.
+        errors : {'raise', 'ignore'}, default 'ignore'
+            If 'raise', will raise a ValueError if the DataFrame and `other`
+            both contain non-NA data in the same place.
+
+        Returns
+        -------
+        None
+            This method directly changes calling object.
+
+        Raises
+        ------
+        ValueError
+            * When `errors='raise'` and there's overlapping non-NA data.
+            * When `errors` is not either `'ignore'` or `'raise'`
+        NotImplementedError
+            * If `join != 'left'`
+
+        See Also
+        --------
+        dict.update : Similar method for dictionaries.
+        DataFrame.merge : For column(s)-on-column(s) operations.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2, 3],
+        ...                    'B': [400, 500, 600]})
+        >>> new_df = pd.DataFrame({'B': [4, 5, 6],
+        ...                        'C': [7, 8, 9]})
+        >>> df.update(new_df)
+        >>> df
+           A  B
+        0  1  4
+        1  2  5
+        2  3  6
+
+        The DataFrame's length does not increase as a result of the update,
+        only values at matching index/column labels are updated.
+
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+        ...                    'B': ['x', 'y', 'z']})
+        >>> new_df = pd.DataFrame({'B': ['d', 'e', 'f', 'g', 'h', 'i']})
+        >>> df.update(new_df)
+        >>> df
+           A  B
+        0  a  d
+        1  b  e
+        2  c  f
+
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+        ...                    'B': ['x', 'y', 'z']})
+        >>> new_df = pd.DataFrame({'B': ['d', 'f']}, index=[0, 2])
+        >>> df.update(new_df)
+        >>> df
+           A  B
+        0  a  d
+        1  b  y
+        2  c  f
+
+        For Series, its name attribute must be set.
+
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c'],
+        ...                    'B': ['x', 'y', 'z']})
+        >>> new_column = pd.Series(['d', 'e', 'f'], name='B')
+        >>> df.update(new_column)
+        >>> df
+           A  B
+        0  a  d
+        1  b  e
+        2  c  f
+
+        If `other` contains NaNs the corresponding values are not updated
+        in the original dataframe.
+
+        >>> df = pd.DataFrame({'A': [1, 2, 3],
+        ...                    'B': [400., 500., 600.]})
+        >>> new_df = pd.DataFrame({'B': [4, np.nan, 6]})
+        >>> df.update(new_df)
+        >>> df
+           A      B
+        0  1    4.0
+        1  2  500.0
+        2  3    6.0
+        """
+
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self) <= REF_COUNT:
+                warnings.warn(
+                    _chained_assignment_method_msg,
+                    ChainedAssignmentError,
+                    stacklevel=2,
+                )
+        elif (
+            not PYPY
+            and not WARNING_CHECK_DISABLED
+            and not using_copy_on_write()
+            and self._is_view_after_cow_rules()
+        ):
+            if sys.getrefcount(self) <= REF_COUNT:
+                warnings.warn(
+                    _chained_assignment_warning_method_msg,
+                    FutureWarning,
+                    stacklevel=2,
+                )
+
+        # TODO: Support other joins
+        if join != "left":  # pragma: no cover
+            raise NotImplementedError("Only left join is supported")
+        if errors not in ["ignore", "raise"]:
+            raise ValueError("The parameter errors must be either 'ignore' or 'raise'")
+
+        if not isinstance(other, DataFrame):
+            other = DataFrame(other)
+
+        other = other.reindex(self.index)
+
+        for col in self.columns.intersection(other.columns):
+            this = self[col]._values
+            that = other[col]._values
+
+            if filter_func is not None:
+                mask = ~filter_func(this) | isna(that)
+            else:
+                if errors == "raise":
+                    mask_this = notna(that)
+                    mask_that = notna(this)
+                    if any(mask_this & mask_that):
+                        raise ValueError("Data overlaps.")
+
+                if overwrite:
+                    mask = isna(that)
+                else:
+                    mask = notna(this)
+
+            # don't overwrite columns unnecessarily
+            if mask.all():
+                continue
+
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore",
+                    message="Downcasting behavior",
+                    category=FutureWarning,
+                )
+                # GH#57124 - `that` might get upcasted because of NA values, and then
+                # downcasted in where because of the mask. Ignoring the warning
+                # is a stopgap, will replace with a new implementation of update
+                # in 3.0.
+                self.loc[:, col] = self[col].where(mask, that)
+
+    # ----------------------------------------------------------------------
+    # Data reshaping
+    @Appender(
+        dedent(
+            """
+        Examples
+        --------
+        >>> df = pd.DataFrame({'Animal': ['Falcon', 'Falcon',
+        ...                               'Parrot', 'Parrot'],
+        ...                    'Max Speed': [380., 370., 24., 26.]})
+        >>> df
+           Animal  Max Speed
+        0  Falcon      380.0
+        1  Falcon      370.0
+        2  Parrot       24.0
+        3  Parrot       26.0
+        >>> df.groupby(['Animal']).mean()
+                Max Speed
+        Animal
+        Falcon      375.0
+        Parrot       25.0
+
+        **Hierarchical Indexes**
+
+        We can groupby different levels of a hierarchical index
+        using the `level` parameter:
+
+        >>> arrays = [['Falcon', 'Falcon', 'Parrot', 'Parrot'],
+        ...           ['Captive', 'Wild', 'Captive', 'Wild']]
+        >>> index = pd.MultiIndex.from_arrays(arrays, names=('Animal', 'Type'))
+        >>> df = pd.DataFrame({'Max Speed': [390., 350., 30., 20.]},
+        ...                   index=index)
+        >>> df
+                        Max Speed
+        Animal Type
+        Falcon Captive      390.0
+               Wild         350.0
+        Parrot Captive       30.0
+               Wild          20.0
+        >>> df.groupby(level=0).mean()
+                Max Speed
+        Animal
+        Falcon      370.0
+        Parrot       25.0
+        >>> df.groupby(level="Type").mean()
+                 Max Speed
+        Type
+        Captive      210.0
+        Wild         185.0
+
+        We can also choose to include NA in group keys or not by setting
+        `dropna` parameter, the default setting is `True`.
+
+        >>> l = [[1, 2, 3], [1, None, 4], [2, 1, 3], [1, 2, 2]]
+        >>> df = pd.DataFrame(l, columns=["a", "b", "c"])
+
+        >>> df.groupby(by=["b"]).sum()
+            a   c
+        b
+        1.0 2   3
+        2.0 2   5
+
+        >>> df.groupby(by=["b"], dropna=False).sum()
+            a   c
+        b
+        1.0 2   3
+        2.0 2   5
+        NaN 1   4
+
+        >>> l = [["a", 12, 12], [None, 12.3, 33.], ["b", 12.3, 123], ["a", 1, 1]]
+        >>> df = pd.DataFrame(l, columns=["a", "b", "c"])
+
+        >>> df.groupby(by="a").sum()
+            b     c
+        a
+        a   13.0   13.0
+        b   12.3  123.0
+
+        >>> df.groupby(by="a", dropna=False).sum()
+            b     c
+        a
+        a   13.0   13.0
+        b   12.3  123.0
+        NaN 12.3   33.0
+
+        When using ``.apply()``, use ``group_keys`` to include or exclude the
+        group keys. The ``group_keys`` argument defaults to ``True`` (include).
+
+        >>> df = pd.DataFrame({'Animal': ['Falcon', 'Falcon',
+        ...                               'Parrot', 'Parrot'],
+        ...                    'Max Speed': [380., 370., 24., 26.]})
+        >>> df.groupby("Animal", group_keys=True)[['Max Speed']].apply(lambda x: x)
+                  Max Speed
+        Animal
+        Falcon 0      380.0
+               1      370.0
+        Parrot 2       24.0
+               3       26.0
+
+        >>> df.groupby("Animal", group_keys=False)[['Max Speed']].apply(lambda x: x)
+           Max Speed
+        0      380.0
+        1      370.0
+        2       24.0
+        3       26.0
+        """
+        )
+    )
+    @Appender(_shared_docs["groupby"] % _shared_doc_kwargs)
+    def groupby(
+        self,
+        by=None,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        level: IndexLabel | None = None,
+        as_index: bool = True,
+        sort: bool = True,
+        group_keys: bool = True,
+        observed: bool | lib.NoDefault = lib.no_default,
+        dropna: bool = True,
+    ) -> DataFrameGroupBy:
+        if axis is not lib.no_default:
+            axis = self._get_axis_number(axis)
+            if axis == 1:
+                warnings.warn(
+                    "DataFrame.groupby with axis=1 is deprecated. Do "
+                    "`frame.T.groupby(...)` without axis instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                warnings.warn(
+                    "The 'axis' keyword in DataFrame.groupby is deprecated and "
+                    "will be removed in a future version.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            axis = 0
+
+        from pandas.core.groupby.generic import DataFrameGroupBy
+
+        if level is None and by is None:
+            raise TypeError("You have to supply one of 'by' and 'level'")
+
+        return DataFrameGroupBy(
+            obj=self,
+            keys=by,
+            axis=axis,
+            level=level,
+            as_index=as_index,
+            sort=sort,
+            group_keys=group_keys,
+            observed=observed,
+            dropna=dropna,
+        )
+
+    _shared_docs[
+        "pivot"
+    ] = """
+        Return reshaped DataFrame organized by given index / column values.
+
+        Reshape data (produce a "pivot" table) based on column values. Uses
+        unique values from specified `index` / `columns` to form axes of the
+        resulting DataFrame. This function does not support data
+        aggregation, multiple values will result in a MultiIndex in the
+        columns. See the :ref:`User Guide ` for more on reshaping.
+
+        Parameters
+        ----------%s
+        columns : str or object or a list of str
+            Column to use to make new frame's columns.
+        index : str or object or a list of str, optional
+            Column to use to make new frame's index. If not given, uses existing index.
+        values : str, object or a list of the previous, optional
+            Column(s) to use for populating new frame's values. If not
+            specified, all remaining columns will be used and the result will
+            have hierarchically indexed columns.
+
+        Returns
+        -------
+        DataFrame
+            Returns reshaped DataFrame.
+
+        Raises
+        ------
+        ValueError:
+            When there are any `index`, `columns` combinations with multiple
+            values. `DataFrame.pivot_table` when you need to aggregate.
+
+        See Also
+        --------
+        DataFrame.pivot_table : Generalization of pivot that can handle
+            duplicate values for one index/column pair.
+        DataFrame.unstack : Pivot based on the index values instead of a
+            column.
+        wide_to_long : Wide panel to long format. Less flexible but more
+            user-friendly than melt.
+
+        Notes
+        -----
+        For finer-tuned control, see hierarchical indexing documentation along
+        with the related stack/unstack methods.
+
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'foo': ['one', 'one', 'one', 'two', 'two',
+        ...                            'two'],
+        ...                    'bar': ['A', 'B', 'C', 'A', 'B', 'C'],
+        ...                    'baz': [1, 2, 3, 4, 5, 6],
+        ...                    'zoo': ['x', 'y', 'z', 'q', 'w', 't']})
+        >>> df
+            foo   bar  baz  zoo
+        0   one   A    1    x
+        1   one   B    2    y
+        2   one   C    3    z
+        3   two   A    4    q
+        4   two   B    5    w
+        5   two   C    6    t
+
+        >>> df.pivot(index='foo', columns='bar', values='baz')
+        bar  A   B   C
+        foo
+        one  1   2   3
+        two  4   5   6
+
+        >>> df.pivot(index='foo', columns='bar')['baz']
+        bar  A   B   C
+        foo
+        one  1   2   3
+        two  4   5   6
+
+        >>> df.pivot(index='foo', columns='bar', values=['baz', 'zoo'])
+              baz       zoo
+        bar   A  B  C   A  B  C
+        foo
+        one   1  2  3   x  y  z
+        two   4  5  6   q  w  t
+
+        You could also assign a list of column names or a list of index names.
+
+        >>> df = pd.DataFrame({
+        ...        "lev1": [1, 1, 1, 2, 2, 2],
+        ...        "lev2": [1, 1, 2, 1, 1, 2],
+        ...        "lev3": [1, 2, 1, 2, 1, 2],
+        ...        "lev4": [1, 2, 3, 4, 5, 6],
+        ...        "values": [0, 1, 2, 3, 4, 5]})
+        >>> df
+            lev1 lev2 lev3 lev4 values
+        0   1    1    1    1    0
+        1   1    1    2    2    1
+        2   1    2    1    3    2
+        3   2    1    2    4    3
+        4   2    1    1    5    4
+        5   2    2    2    6    5
+
+        >>> df.pivot(index="lev1", columns=["lev2", "lev3"], values="values")
+        lev2    1         2
+        lev3    1    2    1    2
+        lev1
+        1     0.0  1.0  2.0  NaN
+        2     4.0  3.0  NaN  5.0
+
+        >>> df.pivot(index=["lev1", "lev2"], columns=["lev3"], values="values")
+              lev3    1    2
+        lev1  lev2
+           1     1  0.0  1.0
+                 2  2.0  NaN
+           2     1  4.0  3.0
+                 2  NaN  5.0
+
+        A ValueError is raised if there are any duplicates.
+
+        >>> df = pd.DataFrame({"foo": ['one', 'one', 'two', 'two'],
+        ...                    "bar": ['A', 'A', 'B', 'C'],
+        ...                    "baz": [1, 2, 3, 4]})
+        >>> df
+           foo bar  baz
+        0  one   A    1
+        1  one   A    2
+        2  two   B    3
+        3  two   C    4
+
+        Notice that the first two rows are the same for our `index`
+        and `columns` arguments.
+
+        >>> df.pivot(index='foo', columns='bar', values='baz')
+        Traceback (most recent call last):
+           ...
+        ValueError: Index contains duplicate entries, cannot reshape
+        """
+
+    @Substitution("")
+    @Appender(_shared_docs["pivot"])
+    def pivot(
+        self, *, columns, index=lib.no_default, values=lib.no_default
+    ) -> DataFrame:
+        from pandas.core.reshape.pivot import pivot
+
+        return pivot(self, index=index, columns=columns, values=values)
+
+    _shared_docs[
+        "pivot_table"
+    ] = """
+        Create a spreadsheet-style pivot table as a DataFrame.
+
+        The levels in the pivot table will be stored in MultiIndex objects
+        (hierarchical indexes) on the index and columns of the result DataFrame.
+
+        Parameters
+        ----------%s
+        values : list-like or scalar, optional
+            Column or columns to aggregate.
+        index : column, Grouper, array, or list of the previous
+            Keys to group by on the pivot table index. If a list is passed,
+            it can contain any of the other types (except list). If an array is
+            passed, it must be the same length as the data and will be used in
+            the same manner as column values.
+        columns : column, Grouper, array, or list of the previous
+            Keys to group by on the pivot table column. If a list is passed,
+            it can contain any of the other types (except list). If an array is
+            passed, it must be the same length as the data and will be used in
+            the same manner as column values.
+        aggfunc : function, list of functions, dict, default "mean"
+            If a list of functions is passed, the resulting pivot table will have
+            hierarchical columns whose top level are the function names
+            (inferred from the function objects themselves).
+            If a dict is passed, the key is column to aggregate and the value is
+            function or list of functions. If ``margin=True``, aggfunc will be
+            used to calculate the partial aggregates.
+        fill_value : scalar, default None
+            Value to replace missing values with (in the resulting pivot table,
+            after aggregation).
+        margins : bool, default False
+            If ``margins=True``, special ``All`` columns and rows
+            will be added with partial group aggregates across the categories
+            on the rows and columns.
+        dropna : bool, default True
+            Do not include columns whose entries are all NaN. If True,
+            rows with a NaN value in any column will be omitted before
+            computing margins.
+        margins_name : str, default 'All'
+            Name of the row / column that will contain the totals
+            when margins is True.
+        observed : bool, default False
+            This only applies if any of the groupers are Categoricals.
+            If True: only show observed values for categorical groupers.
+            If False: show all values for categorical groupers.
+
+            .. deprecated:: 2.2.0
+
+                The default value of ``False`` is deprecated and will change to
+                ``True`` in a future version of pandas.
+
+        sort : bool, default True
+            Specifies if the result should be sorted.
+
+            .. versionadded:: 1.3.0
+
+        Returns
+        -------
+        DataFrame
+            An Excel style pivot table.
+
+        See Also
+        --------
+        DataFrame.pivot : Pivot without aggregation that can handle
+            non-numeric data.
+        DataFrame.melt: Unpivot a DataFrame from wide to long format,
+            optionally leaving identifiers set.
+        wide_to_long : Wide panel to long format. Less flexible but more
+            user-friendly than melt.
+
+        Notes
+        -----
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": ["foo", "foo", "foo", "foo", "foo",
+        ...                          "bar", "bar", "bar", "bar"],
+        ...                    "B": ["one", "one", "one", "two", "two",
+        ...                          "one", "one", "two", "two"],
+        ...                    "C": ["small", "large", "large", "small",
+        ...                          "small", "large", "small", "small",
+        ...                          "large"],
+        ...                    "D": [1, 2, 2, 3, 3, 4, 5, 6, 7],
+        ...                    "E": [2, 4, 5, 5, 6, 6, 8, 9, 9]})
+        >>> df
+             A    B      C  D  E
+        0  foo  one  small  1  2
+        1  foo  one  large  2  4
+        2  foo  one  large  2  5
+        3  foo  two  small  3  5
+        4  foo  two  small  3  6
+        5  bar  one  large  4  6
+        6  bar  one  small  5  8
+        7  bar  two  small  6  9
+        8  bar  two  large  7  9
+
+        This first example aggregates values by taking the sum.
+
+        >>> table = pd.pivot_table(df, values='D', index=['A', 'B'],
+        ...                        columns=['C'], aggfunc="sum")
+        >>> table
+        C        large  small
+        A   B
+        bar one    4.0    5.0
+            two    7.0    6.0
+        foo one    4.0    1.0
+            two    NaN    6.0
+
+        We can also fill missing values using the `fill_value` parameter.
+
+        >>> table = pd.pivot_table(df, values='D', index=['A', 'B'],
+        ...                        columns=['C'], aggfunc="sum", fill_value=0)
+        >>> table
+        C        large  small
+        A   B
+        bar one      4      5
+            two      7      6
+        foo one      4      1
+            two      0      6
+
+        The next example aggregates by taking the mean across multiple columns.
+
+        >>> table = pd.pivot_table(df, values=['D', 'E'], index=['A', 'C'],
+        ...                        aggfunc={'D': "mean", 'E': "mean"})
+        >>> table
+                        D         E
+        A   C
+        bar large  5.500000  7.500000
+            small  5.500000  8.500000
+        foo large  2.000000  4.500000
+            small  2.333333  4.333333
+
+        We can also calculate multiple types of aggregations for any given
+        value column.
+
+        >>> table = pd.pivot_table(df, values=['D', 'E'], index=['A', 'C'],
+        ...                        aggfunc={'D': "mean",
+        ...                                 'E': ["min", "max", "mean"]})
+        >>> table
+                          D   E
+                       mean max      mean  min
+        A   C
+        bar large  5.500000   9  7.500000    6
+            small  5.500000   9  8.500000    8
+        foo large  2.000000   5  4.500000    4
+            small  2.333333   6  4.333333    2
+        """
+
+    @Substitution("")
+    @Appender(_shared_docs["pivot_table"])
+    def pivot_table(
+        self,
+        values=None,
+        index=None,
+        columns=None,
+        aggfunc: AggFuncType = "mean",
+        fill_value=None,
+        margins: bool = False,
+        dropna: bool = True,
+        margins_name: Level = "All",
+        observed: bool | lib.NoDefault = lib.no_default,
+        sort: bool = True,
+    ) -> DataFrame:
+        from pandas.core.reshape.pivot import pivot_table
+
+        return pivot_table(
+            self,
+            values=values,
+            index=index,
+            columns=columns,
+            aggfunc=aggfunc,
+            fill_value=fill_value,
+            margins=margins,
+            dropna=dropna,
+            margins_name=margins_name,
+            observed=observed,
+            sort=sort,
+        )
+
+    def stack(
+        self,
+        level: IndexLabel = -1,
+        dropna: bool | lib.NoDefault = lib.no_default,
+        sort: bool | lib.NoDefault = lib.no_default,
+        future_stack: bool = False,
+    ):
+        """
+        Stack the prescribed level(s) from columns to index.
+
+        Return a reshaped DataFrame or Series having a multi-level
+        index with one or more new inner-most levels compared to the current
+        DataFrame. The new inner-most levels are created by pivoting the
+        columns of the current dataframe:
+
+          - if the columns have a single level, the output is a Series;
+          - if the columns have multiple levels, the new index
+            level(s) is (are) taken from the prescribed level(s) and
+            the output is a DataFrame.
+
+        Parameters
+        ----------
+        level : int, str, list, default -1
+            Level(s) to stack from the column axis onto the index
+            axis, defined as one index or label, or a list of indices
+            or labels.
+        dropna : bool, default True
+            Whether to drop rows in the resulting Frame/Series with
+            missing values. Stacking a column level onto the index
+            axis can create combinations of index and column values
+            that are missing from the original dataframe. See Examples
+            section.
+        sort : bool, default True
+            Whether to sort the levels of the resulting MultiIndex.
+        future_stack : bool, default False
+            Whether to use the new implementation that will replace the current
+            implementation in pandas 3.0. When True, dropna and sort have no impact
+            on the result and must remain unspecified. See :ref:`pandas 2.1.0 Release
+            notes ` for more details.
+
+        Returns
+        -------
+        DataFrame or Series
+            Stacked dataframe or series.
+
+        See Also
+        --------
+        DataFrame.unstack : Unstack prescribed level(s) from index axis
+             onto column axis.
+        DataFrame.pivot : Reshape dataframe from long format to wide
+             format.
+        DataFrame.pivot_table : Create a spreadsheet-style pivot table
+             as a DataFrame.
+
+        Notes
+        -----
+        The function is named by analogy with a collection of books
+        being reorganized from being side by side on a horizontal
+        position (the columns of the dataframe) to being stacked
+        vertically on top of each other (in the index of the
+        dataframe).
+
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        **Single level columns**
+
+        >>> df_single_level_cols = pd.DataFrame([[0, 1], [2, 3]],
+        ...                                     index=['cat', 'dog'],
+        ...                                     columns=['weight', 'height'])
+
+        Stacking a dataframe with a single level column axis returns a Series:
+
+        >>> df_single_level_cols
+             weight height
+        cat       0      1
+        dog       2      3
+        >>> df_single_level_cols.stack(future_stack=True)
+        cat  weight    0
+             height    1
+        dog  weight    2
+             height    3
+        dtype: int64
+
+        **Multi level columns: simple case**
+
+        >>> multicol1 = pd.MultiIndex.from_tuples([('weight', 'kg'),
+        ...                                        ('weight', 'pounds')])
+        >>> df_multi_level_cols1 = pd.DataFrame([[1, 2], [2, 4]],
+        ...                                     index=['cat', 'dog'],
+        ...                                     columns=multicol1)
+
+        Stacking a dataframe with a multi-level column axis:
+
+        >>> df_multi_level_cols1
+             weight
+                 kg    pounds
+        cat       1        2
+        dog       2        4
+        >>> df_multi_level_cols1.stack(future_stack=True)
+                    weight
+        cat kg           1
+            pounds       2
+        dog kg           2
+            pounds       4
+
+        **Missing values**
+
+        >>> multicol2 = pd.MultiIndex.from_tuples([('weight', 'kg'),
+        ...                                        ('height', 'm')])
+        >>> df_multi_level_cols2 = pd.DataFrame([[1.0, 2.0], [3.0, 4.0]],
+        ...                                     index=['cat', 'dog'],
+        ...                                     columns=multicol2)
+
+        It is common to have missing values when stacking a dataframe
+        with multi-level columns, as the stacked dataframe typically
+        has more values than the original dataframe. Missing values
+        are filled with NaNs:
+
+        >>> df_multi_level_cols2
+            weight height
+                kg      m
+        cat    1.0    2.0
+        dog    3.0    4.0
+        >>> df_multi_level_cols2.stack(future_stack=True)
+                weight  height
+        cat kg     1.0     NaN
+            m      NaN     2.0
+        dog kg     3.0     NaN
+            m      NaN     4.0
+
+        **Prescribing the level(s) to be stacked**
+
+        The first parameter controls which level or levels are stacked:
+
+        >>> df_multi_level_cols2.stack(0, future_stack=True)
+                     kg    m
+        cat weight  1.0  NaN
+            height  NaN  2.0
+        dog weight  3.0  NaN
+            height  NaN  4.0
+        >>> df_multi_level_cols2.stack([0, 1], future_stack=True)
+        cat  weight  kg    1.0
+             height  m     2.0
+        dog  weight  kg    3.0
+             height  m     4.0
+        dtype: float64
+        """
+        if not future_stack:
+            from pandas.core.reshape.reshape import (
+                stack,
+                stack_multiple,
+            )
+
+            if (
+                dropna is not lib.no_default
+                or sort is not lib.no_default
+                or self.columns.nlevels > 1
+            ):
+                warnings.warn(
+                    "The previous implementation of stack is deprecated and will be "
+                    "removed in a future version of pandas. See the What's New notes "
+                    "for pandas 2.1.0 for details. Specify future_stack=True to adopt "
+                    "the new implementation and silence this warning.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+            if dropna is lib.no_default:
+                dropna = True
+            if sort is lib.no_default:
+                sort = True
+
+            if isinstance(level, (tuple, list)):
+                result = stack_multiple(self, level, dropna=dropna, sort=sort)
+            else:
+                result = stack(self, level, dropna=dropna, sort=sort)
+        else:
+            from pandas.core.reshape.reshape import stack_v3
+
+            if dropna is not lib.no_default:
+                raise ValueError(
+                    "dropna must be unspecified with future_stack=True as the new "
+                    "implementation does not introduce rows of NA values. This "
+                    "argument will be removed in a future version of pandas."
+                )
+
+            if sort is not lib.no_default:
+                raise ValueError(
+                    "Cannot specify sort with future_stack=True, this argument will be "
+                    "removed in a future version of pandas. Sort the result using "
+                    ".sort_index instead."
+                )
+
+            if (
+                isinstance(level, (tuple, list))
+                and not all(lev in self.columns.names for lev in level)
+                and not all(isinstance(lev, int) for lev in level)
+            ):
+                raise ValueError(
+                    "level should contain all level names or all level "
+                    "numbers, not a mixture of the two."
+                )
+
+            if not isinstance(level, (tuple, list)):
+                level = [level]
+            level = [self.columns._get_level_number(lev) for lev in level]
+            result = stack_v3(self, level)
+
+        return result.__finalize__(self, method="stack")
+
+    def explode(
+        self,
+        column: IndexLabel,
+        ignore_index: bool = False,
+    ) -> DataFrame:
+        """
+        Transform each element of a list-like to a row, replicating index values.
+
+        Parameters
+        ----------
+        column : IndexLabel
+            Column(s) to explode.
+            For multiple columns, specify a non-empty list with each element
+            be str or tuple, and all specified columns their list-like data
+            on same row of the frame must have matching length.
+
+            .. versionadded:: 1.3.0
+                Multi-column explode
+
+        ignore_index : bool, default False
+            If True, the resulting index will be labeled 0, 1, …, n - 1.
+
+        Returns
+        -------
+        DataFrame
+            Exploded lists to rows of the subset columns;
+            index will be duplicated for these rows.
+
+        Raises
+        ------
+        ValueError :
+            * If columns of the frame are not unique.
+            * If specified columns to explode is empty list.
+            * If specified columns to explode have not matching count of
+              elements rowwise in the frame.
+
+        See Also
+        --------
+        DataFrame.unstack : Pivot a level of the (necessarily hierarchical)
+            index labels.
+        DataFrame.melt : Unpivot a DataFrame from wide format to long format.
+        Series.explode : Explode a DataFrame from list-like columns to long format.
+
+        Notes
+        -----
+        This routine will explode list-likes including lists, tuples, sets,
+        Series, and np.ndarray. The result dtype of the subset rows will
+        be object. Scalars will be returned unchanged, and empty list-likes will
+        result in a np.nan for that row. In addition, the ordering of rows in the
+        output will be non-deterministic when exploding sets.
+
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [[0, 1, 2], 'foo', [], [3, 4]],
+        ...                    'B': 1,
+        ...                    'C': [['a', 'b', 'c'], np.nan, [], ['d', 'e']]})
+        >>> df
+                   A  B          C
+        0  [0, 1, 2]  1  [a, b, c]
+        1        foo  1        NaN
+        2         []  1         []
+        3     [3, 4]  1     [d, e]
+
+        Single-column explode.
+
+        >>> df.explode('A')
+             A  B          C
+        0    0  1  [a, b, c]
+        0    1  1  [a, b, c]
+        0    2  1  [a, b, c]
+        1  foo  1        NaN
+        2  NaN  1         []
+        3    3  1     [d, e]
+        3    4  1     [d, e]
+
+        Multi-column explode.
+
+        >>> df.explode(list('AC'))
+             A  B    C
+        0    0  1    a
+        0    1  1    b
+        0    2  1    c
+        1  foo  1  NaN
+        2  NaN  1  NaN
+        3    3  1    d
+        3    4  1    e
+        """
+        if not self.columns.is_unique:
+            duplicate_cols = self.columns[self.columns.duplicated()].tolist()
+            raise ValueError(
+                f"DataFrame columns must be unique. Duplicate columns: {duplicate_cols}"
+            )
+
+        columns: list[Hashable]
+        if is_scalar(column) or isinstance(column, tuple):
+            columns = [column]
+        elif isinstance(column, list) and all(
+            is_scalar(c) or isinstance(c, tuple) for c in column
+        ):
+            if not column:
+                raise ValueError("column must be nonempty")
+            if len(column) > len(set(column)):
+                raise ValueError("column must be unique")
+            columns = column
+        else:
+            raise ValueError("column must be a scalar, tuple, or list thereof")
+
+        df = self.reset_index(drop=True)
+        if len(columns) == 1:
+            result = df[columns[0]].explode()
+        else:
+            mylen = lambda x: len(x) if (is_list_like(x) and len(x) > 0) else 1
+            counts0 = self[columns[0]].apply(mylen)
+            for c in columns[1:]:
+                if not all(counts0 == self[c].apply(mylen)):
+                    raise ValueError("columns must have matching element counts")
+            result = DataFrame({c: df[c].explode() for c in columns})
+        result = df.drop(columns, axis=1).join(result)
+        if ignore_index:
+            result.index = default_index(len(result))
+        else:
+            result.index = self.index.take(result.index)
+        result = result.reindex(columns=self.columns, copy=False)
+
+        return result.__finalize__(self, method="explode")
+
+    def unstack(self, level: IndexLabel = -1, fill_value=None, sort: bool = True):
+        """
+        Pivot a level of the (necessarily hierarchical) index labels.
+
+        Returns a DataFrame having a new level of column labels whose inner-most level
+        consists of the pivoted index labels.
+
+        If the index is not a MultiIndex, the output will be a Series
+        (the analogue of stack when the columns are not a MultiIndex).
+
+        Parameters
+        ----------
+        level : int, str, or list of these, default -1 (last level)
+            Level(s) of index to unstack, can pass level name.
+        fill_value : int, str or dict
+            Replace NaN with this value if the unstack produces missing values.
+        sort : bool, default True
+            Sort the level(s) in the resulting MultiIndex columns.
+
+        Returns
+        -------
+        Series or DataFrame
+
+        See Also
+        --------
+        DataFrame.pivot : Pivot a table based on column values.
+        DataFrame.stack : Pivot a level of the column labels (inverse operation
+            from `unstack`).
+
+        Notes
+        -----
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> index = pd.MultiIndex.from_tuples([('one', 'a'), ('one', 'b'),
+        ...                                    ('two', 'a'), ('two', 'b')])
+        >>> s = pd.Series(np.arange(1.0, 5.0), index=index)
+        >>> s
+        one  a   1.0
+             b   2.0
+        two  a   3.0
+             b   4.0
+        dtype: float64
+
+        >>> s.unstack(level=-1)
+             a   b
+        one  1.0  2.0
+        two  3.0  4.0
+
+        >>> s.unstack(level=0)
+           one  two
+        a  1.0   3.0
+        b  2.0   4.0
+
+        >>> df = s.unstack(level=0)
+        >>> df.unstack()
+        one  a  1.0
+             b  2.0
+        two  a  3.0
+             b  4.0
+        dtype: float64
+        """
+        from pandas.core.reshape.reshape import unstack
+
+        result = unstack(self, level, fill_value, sort)
+
+        return result.__finalize__(self, method="unstack")
+
+    @Appender(_shared_docs["melt"] % {"caller": "df.melt(", "other": "melt"})
+    def melt(
+        self,
+        id_vars=None,
+        value_vars=None,
+        var_name=None,
+        value_name: Hashable = "value",
+        col_level: Level | None = None,
+        ignore_index: bool = True,
+    ) -> DataFrame:
+        return melt(
+            self,
+            id_vars=id_vars,
+            value_vars=value_vars,
+            var_name=var_name,
+            value_name=value_name,
+            col_level=col_level,
+            ignore_index=ignore_index,
+        ).__finalize__(self, method="melt")
+
+    # ----------------------------------------------------------------------
+    # Time series-related
+
+    @doc(
+        Series.diff,
+        klass="DataFrame",
+        extra_params="axis : {0 or 'index', 1 or 'columns'}, default 0\n    "
+        "Take difference over rows (0) or columns (1).\n",
+        other_klass="Series",
+        examples=dedent(
+            """
+        Difference with previous row
+
+        >>> df = pd.DataFrame({'a': [1, 2, 3, 4, 5, 6],
+        ...                    'b': [1, 1, 2, 3, 5, 8],
+        ...                    'c': [1, 4, 9, 16, 25, 36]})
+        >>> df
+           a  b   c
+        0  1  1   1
+        1  2  1   4
+        2  3  2   9
+        3  4  3  16
+        4  5  5  25
+        5  6  8  36
+
+        >>> df.diff()
+             a    b     c
+        0  NaN  NaN   NaN
+        1  1.0  0.0   3.0
+        2  1.0  1.0   5.0
+        3  1.0  1.0   7.0
+        4  1.0  2.0   9.0
+        5  1.0  3.0  11.0
+
+        Difference with previous column
+
+        >>> df.diff(axis=1)
+            a  b   c
+        0 NaN  0   0
+        1 NaN -1   3
+        2 NaN -1   7
+        3 NaN -1  13
+        4 NaN  0  20
+        5 NaN  2  28
+
+        Difference with 3rd previous row
+
+        >>> df.diff(periods=3)
+             a    b     c
+        0  NaN  NaN   NaN
+        1  NaN  NaN   NaN
+        2  NaN  NaN   NaN
+        3  3.0  2.0  15.0
+        4  3.0  4.0  21.0
+        5  3.0  6.0  27.0
+
+        Difference with following row
+
+        >>> df.diff(periods=-1)
+             a    b     c
+        0 -1.0  0.0  -3.0
+        1 -1.0 -1.0  -5.0
+        2 -1.0 -1.0  -7.0
+        3 -1.0 -2.0  -9.0
+        4 -1.0 -3.0 -11.0
+        5  NaN  NaN   NaN
+
+        Overflow in input dtype
+
+        >>> df = pd.DataFrame({'a': [1, 0]}, dtype=np.uint8)
+        >>> df.diff()
+               a
+        0    NaN
+        1  255.0"""
+        ),
+    )
+    def diff(self, periods: int = 1, axis: Axis = 0) -> DataFrame:
+        if not lib.is_integer(periods):
+            if not (is_float(periods) and periods.is_integer()):
+                raise ValueError("periods must be an integer")
+            periods = int(periods)
+
+        axis = self._get_axis_number(axis)
+        if axis == 1:
+            if periods != 0:
+                # in the periods == 0 case, this is equivalent diff of 0 periods
+                #  along axis=0, and the Manager method may be somewhat more
+                #  performant, so we dispatch in that case.
+                return self - self.shift(periods, axis=axis)
+            # With periods=0 this is equivalent to a diff with axis=0
+            axis = 0
+
+        new_data = self._mgr.diff(n=periods)
+        res_df = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        return res_df.__finalize__(self, "diff")
+
+    # ----------------------------------------------------------------------
+    # Function application
+
+    def _gotitem(
+        self,
+        key: IndexLabel,
+        ndim: int,
+        subset: DataFrame | Series | None = None,
+    ) -> DataFrame | Series:
+        """
+        Sub-classes to define. Return a sliced object.
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        if subset is None:
+            subset = self
+        elif subset.ndim == 1:  # is Series
+            return subset
+
+        # TODO: _shallow_copy(subset)?
+        return subset[key]
+
+    _agg_see_also_doc = dedent(
+        """
+    See Also
+    --------
+    DataFrame.apply : Perform any type of operations.
+    DataFrame.transform : Perform transformation type operations.
+    pandas.DataFrame.groupby : Perform operations over groups.
+    pandas.DataFrame.resample : Perform operations over resampled bins.
+    pandas.DataFrame.rolling : Perform operations over rolling window.
+    pandas.DataFrame.expanding : Perform operations over expanding window.
+    pandas.core.window.ewm.ExponentialMovingWindow : Perform operation over exponential
+        weighted window.
+    """
+    )
+
+    _agg_examples_doc = dedent(
+        """
+    Examples
+    --------
+    >>> df = pd.DataFrame([[1, 2, 3],
+    ...                    [4, 5, 6],
+    ...                    [7, 8, 9],
+    ...                    [np.nan, np.nan, np.nan]],
+    ...                   columns=['A', 'B', 'C'])
+
+    Aggregate these functions over the rows.
+
+    >>> df.agg(['sum', 'min'])
+            A     B     C
+    sum  12.0  15.0  18.0
+    min   1.0   2.0   3.0
+
+    Different aggregations per column.
+
+    >>> df.agg({'A' : ['sum', 'min'], 'B' : ['min', 'max']})
+            A    B
+    sum  12.0  NaN
+    min   1.0  2.0
+    max   NaN  8.0
+
+    Aggregate different functions over the columns and rename the index of the resulting
+    DataFrame.
+
+    >>> df.agg(x=('A', 'max'), y=('B', 'min'), z=('C', 'mean'))
+         A    B    C
+    x  7.0  NaN  NaN
+    y  NaN  2.0  NaN
+    z  NaN  NaN  6.0
+
+    Aggregate over the columns.
+
+    >>> df.agg("mean", axis="columns")
+    0    2.0
+    1    5.0
+    2    8.0
+    3    NaN
+    dtype: float64
+    """
+    )
+
+    @doc(
+        _shared_docs["aggregate"],
+        klass=_shared_doc_kwargs["klass"],
+        axis=_shared_doc_kwargs["axis"],
+        see_also=_agg_see_also_doc,
+        examples=_agg_examples_doc,
+    )
+    def aggregate(self, func=None, axis: Axis = 0, *args, **kwargs):
+        from pandas.core.apply import frame_apply
+
+        axis = self._get_axis_number(axis)
+
+        op = frame_apply(self, func=func, axis=axis, args=args, kwargs=kwargs)
+        result = op.agg()
+        result = reconstruct_and_relabel_result(result, func, **kwargs)
+        return result
+
+    agg = aggregate
+
+    @doc(
+        _shared_docs["transform"],
+        klass=_shared_doc_kwargs["klass"],
+        axis=_shared_doc_kwargs["axis"],
+    )
+    def transform(
+        self, func: AggFuncType, axis: Axis = 0, *args, **kwargs
+    ) -> DataFrame:
+        from pandas.core.apply import frame_apply
+
+        op = frame_apply(self, func=func, axis=axis, args=args, kwargs=kwargs)
+        result = op.transform()
+        assert isinstance(result, DataFrame)
+        return result
+
+    def apply(
+        self,
+        func: AggFuncType,
+        axis: Axis = 0,
+        raw: bool = False,
+        result_type: Literal["expand", "reduce", "broadcast"] | None = None,
+        args=(),
+        by_row: Literal[False, "compat"] = "compat",
+        engine: Literal["python", "numba"] = "python",
+        engine_kwargs: dict[str, bool] | None = None,
+        **kwargs,
+    ):
+        """
+        Apply a function along an axis of the DataFrame.
+
+        Objects passed to the function are Series objects whose index is
+        either the DataFrame's index (``axis=0``) or the DataFrame's columns
+        (``axis=1``). By default (``result_type=None``), the final return type
+        is inferred from the return type of the applied function. Otherwise,
+        it depends on the `result_type` argument.
+
+        Parameters
+        ----------
+        func : function
+            Function to apply to each column or row.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Axis along which the function is applied:
+
+            * 0 or 'index': apply function to each column.
+            * 1 or 'columns': apply function to each row.
+
+        raw : bool, default False
+            Determines if row or column is passed as a Series or ndarray object:
+
+            * ``False`` : passes each row or column as a Series to the
+              function.
+            * ``True`` : the passed function will receive ndarray objects
+              instead.
+              If you are just applying a NumPy reduction function this will
+              achieve much better performance.
+
+        result_type : {'expand', 'reduce', 'broadcast', None}, default None
+            These only act when ``axis=1`` (columns):
+
+            * 'expand' : list-like results will be turned into columns.
+            * 'reduce' : returns a Series if possible rather than expanding
+              list-like results. This is the opposite of 'expand'.
+            * 'broadcast' : results will be broadcast to the original shape
+              of the DataFrame, the original index and columns will be
+              retained.
+
+            The default behaviour (None) depends on the return value of the
+            applied function: list-like results will be returned as a Series
+            of those. However if the apply function returns a Series these
+            are expanded to columns.
+        args : tuple
+            Positional arguments to pass to `func` in addition to the
+            array/series.
+        by_row : False or "compat", default "compat"
+            Only has an effect when ``func`` is a listlike or dictlike of funcs
+            and the func isn't a string.
+            If "compat", will if possible first translate the func into pandas
+            methods (e.g. ``Series().apply(np.sum)`` will be translated to
+            ``Series().sum()``). If that doesn't work, will try call to apply again with
+            ``by_row=True`` and if that fails, will call apply again with
+            ``by_row=False`` (backward compatible).
+            If False, the funcs will be passed the whole Series at once.
+
+            .. versionadded:: 2.1.0
+
+        engine : {'python', 'numba'}, default 'python'
+            Choose between the python (default) engine or the numba engine in apply.
+
+            The numba engine will attempt to JIT compile the passed function,
+            which may result in speedups for large DataFrames.
+            It also supports the following engine_kwargs :
+
+            - nopython (compile the function in nopython mode)
+            - nogil (release the GIL inside the JIT compiled function)
+            - parallel (try to apply the function in parallel over the DataFrame)
+
+              Note: Due to limitations within numba/how pandas interfaces with numba,
+              you should only use this if raw=True
+
+            Note: The numba compiler only supports a subset of
+            valid Python/numpy operations.
+
+            Please read more about the `supported python features
+            `_
+            and `supported numpy features
+            `_
+            in numba to learn what you can or cannot use in the passed function.
+
+            .. versionadded:: 2.2.0
+
+        engine_kwargs : dict
+            Pass keyword arguments to the engine.
+            This is currently only used by the numba engine,
+            see the documentation for the engine argument for more information.
+        **kwargs
+            Additional keyword arguments to pass as keywords arguments to
+            `func`.
+
+        Returns
+        -------
+        Series or DataFrame
+            Result of applying ``func`` along the given axis of the
+            DataFrame.
+
+        See Also
+        --------
+        DataFrame.map: For elementwise operations.
+        DataFrame.aggregate: Only perform aggregating type operations.
+        DataFrame.transform: Only perform transforming type operations.
+
+        Notes
+        -----
+        Functions that mutate the passed object can produce unexpected
+        behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+        for more details.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[4, 9]] * 3, columns=['A', 'B'])
+        >>> df
+           A  B
+        0  4  9
+        1  4  9
+        2  4  9
+
+        Using a numpy universal function (in this case the same as
+        ``np.sqrt(df)``):
+
+        >>> df.apply(np.sqrt)
+             A    B
+        0  2.0  3.0
+        1  2.0  3.0
+        2  2.0  3.0
+
+        Using a reducing function on either axis
+
+        >>> df.apply(np.sum, axis=0)
+        A    12
+        B    27
+        dtype: int64
+
+        >>> df.apply(np.sum, axis=1)
+        0    13
+        1    13
+        2    13
+        dtype: int64
+
+        Returning a list-like will result in a Series
+
+        >>> df.apply(lambda x: [1, 2], axis=1)
+        0    [1, 2]
+        1    [1, 2]
+        2    [1, 2]
+        dtype: object
+
+        Passing ``result_type='expand'`` will expand list-like results
+        to columns of a Dataframe
+
+        >>> df.apply(lambda x: [1, 2], axis=1, result_type='expand')
+           0  1
+        0  1  2
+        1  1  2
+        2  1  2
+
+        Returning a Series inside the function is similar to passing
+        ``result_type='expand'``. The resulting column names
+        will be the Series index.
+
+        >>> df.apply(lambda x: pd.Series([1, 2], index=['foo', 'bar']), axis=1)
+           foo  bar
+        0    1    2
+        1    1    2
+        2    1    2
+
+        Passing ``result_type='broadcast'`` will ensure the same shape
+        result, whether list-like or scalar is returned by the function,
+        and broadcast it along the axis. The resulting column names will
+        be the originals.
+
+        >>> df.apply(lambda x: [1, 2], axis=1, result_type='broadcast')
+           A  B
+        0  1  2
+        1  1  2
+        2  1  2
+        """
+        from pandas.core.apply import frame_apply
+
+        op = frame_apply(
+            self,
+            func=func,
+            axis=axis,
+            raw=raw,
+            result_type=result_type,
+            by_row=by_row,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+            args=args,
+            kwargs=kwargs,
+        )
+        return op.apply().__finalize__(self, method="apply")
+
+    def map(
+        self, func: PythonFuncType, na_action: str | None = None, **kwargs
+    ) -> DataFrame:
+        """
+        Apply a function to a Dataframe elementwise.
+
+        .. versionadded:: 2.1.0
+
+           DataFrame.applymap was deprecated and renamed to DataFrame.map.
+
+        This method applies a function that accepts and returns a scalar
+        to every element of a DataFrame.
+
+        Parameters
+        ----------
+        func : callable
+            Python function, returns a single value from a single value.
+        na_action : {None, 'ignore'}, default None
+            If 'ignore', propagate NaN values, without passing them to func.
+        **kwargs
+            Additional keyword arguments to pass as keywords arguments to
+            `func`.
+
+        Returns
+        -------
+        DataFrame
+            Transformed DataFrame.
+
+        See Also
+        --------
+        DataFrame.apply : Apply a function along input axis of DataFrame.
+        DataFrame.replace: Replace values given in `to_replace` with `value`.
+        Series.map : Apply a function elementwise on a Series.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2.12], [3.356, 4.567]])
+        >>> df
+               0      1
+        0  1.000  2.120
+        1  3.356  4.567
+
+        >>> df.map(lambda x: len(str(x)))
+           0  1
+        0  3  4
+        1  5  5
+
+        Like Series.map, NA values can be ignored:
+
+        >>> df_copy = df.copy()
+        >>> df_copy.iloc[0, 0] = pd.NA
+        >>> df_copy.map(lambda x: len(str(x)), na_action='ignore')
+             0  1
+        0  NaN  4
+        1  5.0  5
+
+        It is also possible to use `map` with functions that are not
+        `lambda` functions:
+
+        >>> df.map(round, ndigits=1)
+             0    1
+        0  1.0  2.1
+        1  3.4  4.6
+
+        Note that a vectorized version of `func` often exists, which will
+        be much faster. You could square each number elementwise.
+
+        >>> df.map(lambda x: x**2)
+                   0          1
+        0   1.000000   4.494400
+        1  11.262736  20.857489
+
+        But it's better to avoid map in that case.
+
+        >>> df ** 2
+                   0          1
+        0   1.000000   4.494400
+        1  11.262736  20.857489
+        """
+        if na_action not in {"ignore", None}:
+            raise ValueError(
+                f"na_action must be 'ignore' or None. Got {repr(na_action)}"
+            )
+
+        if self.empty:
+            return self.copy()
+
+        func = functools.partial(func, **kwargs)
+
+        def infer(x):
+            return x._map_values(func, na_action=na_action)
+
+        return self.apply(infer).__finalize__(self, "map")
+
+    def applymap(
+        self, func: PythonFuncType, na_action: NaAction | None = None, **kwargs
+    ) -> DataFrame:
+        """
+        Apply a function to a Dataframe elementwise.
+
+        .. deprecated:: 2.1.0
+
+           DataFrame.applymap has been deprecated. Use DataFrame.map instead.
+
+        This method applies a function that accepts and returns a scalar
+        to every element of a DataFrame.
+
+        Parameters
+        ----------
+        func : callable
+            Python function, returns a single value from a single value.
+        na_action : {None, 'ignore'}, default None
+            If 'ignore', propagate NaN values, without passing them to func.
+        **kwargs
+            Additional keyword arguments to pass as keywords arguments to
+            `func`.
+
+        Returns
+        -------
+        DataFrame
+            Transformed DataFrame.
+
+        See Also
+        --------
+        DataFrame.apply : Apply a function along input axis of DataFrame.
+        DataFrame.map : Apply a function along input axis of DataFrame.
+        DataFrame.replace: Replace values given in `to_replace` with `value`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2.12], [3.356, 4.567]])
+        >>> df
+               0      1
+        0  1.000  2.120
+        1  3.356  4.567
+
+        >>> df.map(lambda x: len(str(x)))
+           0  1
+        0  3  4
+        1  5  5
+        """
+        warnings.warn(
+            "DataFrame.applymap has been deprecated. Use DataFrame.map instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.map(func, na_action=na_action, **kwargs)
+
+    # ----------------------------------------------------------------------
+    # Merging / joining methods
+
+    def _append(
+        self,
+        other,
+        ignore_index: bool = False,
+        verify_integrity: bool = False,
+        sort: bool = False,
+    ) -> DataFrame:
+        if isinstance(other, (Series, dict)):
+            if isinstance(other, dict):
+                if not ignore_index:
+                    raise TypeError("Can only append a dict if ignore_index=True")
+                other = Series(other)
+            if other.name is None and not ignore_index:
+                raise TypeError(
+                    "Can only append a Series if ignore_index=True "
+                    "or if the Series has a name"
+                )
+
+            index = Index(
+                [other.name],
+                name=self.index.names
+                if isinstance(self.index, MultiIndex)
+                else self.index.name,
+            )
+            row_df = other.to_frame().T
+            # infer_objects is needed for
+            #  test_append_empty_frame_to_series_with_dateutil_tz
+            other = row_df.infer_objects(copy=False).rename_axis(
+                index.names, copy=False
+            )
+        elif isinstance(other, list):
+            if not other:
+                pass
+            elif not isinstance(other[0], DataFrame):
+                other = DataFrame(other)
+                if self.index.name is not None and not ignore_index:
+                    other.index.name = self.index.name
+
+        from pandas.core.reshape.concat import concat
+
+        if isinstance(other, (list, tuple)):
+            to_concat = [self, *other]
+        else:
+            to_concat = [self, other]
+
+        result = concat(
+            to_concat,
+            ignore_index=ignore_index,
+            verify_integrity=verify_integrity,
+            sort=sort,
+        )
+        return result.__finalize__(self, method="append")
+
+    def join(
+        self,
+        other: DataFrame | Series | Iterable[DataFrame | Series],
+        on: IndexLabel | None = None,
+        how: MergeHow = "left",
+        lsuffix: str = "",
+        rsuffix: str = "",
+        sort: bool = False,
+        validate: JoinValidate | None = None,
+    ) -> DataFrame:
+        """
+        Join columns of another DataFrame.
+
+        Join columns with `other` DataFrame either on index or on a key
+        column. Efficiently join multiple DataFrame objects by index at once by
+        passing a list.
+
+        Parameters
+        ----------
+        other : DataFrame, Series, or a list containing any combination of them
+            Index should be similar to one of the columns in this one. If a
+            Series is passed, its name attribute must be set, and that will be
+            used as the column name in the resulting joined DataFrame.
+        on : str, list of str, or array-like, optional
+            Column or index level name(s) in the caller to join on the index
+            in `other`, otherwise joins index-on-index. If multiple
+            values given, the `other` DataFrame must have a MultiIndex. Can
+            pass an array as the join key if it is not already contained in
+            the calling DataFrame. Like an Excel VLOOKUP operation.
+        how : {'left', 'right', 'outer', 'inner', 'cross'}, default 'left'
+            How to handle the operation of the two objects.
+
+            * left: use calling frame's index (or column if on is specified)
+            * right: use `other`'s index.
+            * outer: form union of calling frame's index (or column if on is
+              specified) with `other`'s index, and sort it lexicographically.
+            * inner: form intersection of calling frame's index (or column if
+              on is specified) with `other`'s index, preserving the order
+              of the calling's one.
+            * cross: creates the cartesian product from both frames, preserves the order
+              of the left keys.
+        lsuffix : str, default ''
+            Suffix to use from left frame's overlapping columns.
+        rsuffix : str, default ''
+            Suffix to use from right frame's overlapping columns.
+        sort : bool, default False
+            Order result DataFrame lexicographically by the join key. If False,
+            the order of the join key depends on the join type (how keyword).
+        validate : str, optional
+            If specified, checks if join is of specified type.
+
+            * "one_to_one" or "1:1": check if join keys are unique in both left
+              and right datasets.
+            * "one_to_many" or "1:m": check if join keys are unique in left dataset.
+            * "many_to_one" or "m:1": check if join keys are unique in right dataset.
+            * "many_to_many" or "m:m": allowed, but does not result in checks.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        DataFrame
+            A dataframe containing columns from both the caller and `other`.
+
+        See Also
+        --------
+        DataFrame.merge : For column(s)-on-column(s) operations.
+
+        Notes
+        -----
+        Parameters `on`, `lsuffix`, and `rsuffix` are not supported when
+        passing a list of `DataFrame` objects.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'key': ['K0', 'K1', 'K2', 'K3', 'K4', 'K5'],
+        ...                    'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5']})
+
+        >>> df
+          key   A
+        0  K0  A0
+        1  K1  A1
+        2  K2  A2
+        3  K3  A3
+        4  K4  A4
+        5  K5  A5
+
+        >>> other = pd.DataFrame({'key': ['K0', 'K1', 'K2'],
+        ...                       'B': ['B0', 'B1', 'B2']})
+
+        >>> other
+          key   B
+        0  K0  B0
+        1  K1  B1
+        2  K2  B2
+
+        Join DataFrames using their indexes.
+
+        >>> df.join(other, lsuffix='_caller', rsuffix='_other')
+          key_caller   A key_other    B
+        0         K0  A0        K0   B0
+        1         K1  A1        K1   B1
+        2         K2  A2        K2   B2
+        3         K3  A3       NaN  NaN
+        4         K4  A4       NaN  NaN
+        5         K5  A5       NaN  NaN
+
+        If we want to join using the key columns, we need to set key to be
+        the index in both `df` and `other`. The joined DataFrame will have
+        key as its index.
+
+        >>> df.set_index('key').join(other.set_index('key'))
+              A    B
+        key
+        K0   A0   B0
+        K1   A1   B1
+        K2   A2   B2
+        K3   A3  NaN
+        K4   A4  NaN
+        K5   A5  NaN
+
+        Another option to join using the key columns is to use the `on`
+        parameter. DataFrame.join always uses `other`'s index but we can use
+        any column in `df`. This method preserves the original DataFrame's
+        index in the result.
+
+        >>> df.join(other.set_index('key'), on='key')
+          key   A    B
+        0  K0  A0   B0
+        1  K1  A1   B1
+        2  K2  A2   B2
+        3  K3  A3  NaN
+        4  K4  A4  NaN
+        5  K5  A5  NaN
+
+        Using non-unique key values shows how they are matched.
+
+        >>> df = pd.DataFrame({'key': ['K0', 'K1', 'K1', 'K3', 'K0', 'K1'],
+        ...                    'A': ['A0', 'A1', 'A2', 'A3', 'A4', 'A5']})
+
+        >>> df
+          key   A
+        0  K0  A0
+        1  K1  A1
+        2  K1  A2
+        3  K3  A3
+        4  K0  A4
+        5  K1  A5
+
+        >>> df.join(other.set_index('key'), on='key', validate='m:1')
+          key   A    B
+        0  K0  A0   B0
+        1  K1  A1   B1
+        2  K1  A2   B1
+        3  K3  A3  NaN
+        4  K0  A4   B0
+        5  K1  A5   B1
+        """
+        from pandas.core.reshape.concat import concat
+        from pandas.core.reshape.merge import merge
+
+        if isinstance(other, Series):
+            if other.name is None:
+                raise ValueError("Other Series must have a name")
+            other = DataFrame({other.name: other})
+
+        if isinstance(other, DataFrame):
+            if how == "cross":
+                return merge(
+                    self,
+                    other,
+                    how=how,
+                    on=on,
+                    suffixes=(lsuffix, rsuffix),
+                    sort=sort,
+                    validate=validate,
+                )
+            return merge(
+                self,
+                other,
+                left_on=on,
+                how=how,
+                left_index=on is None,
+                right_index=True,
+                suffixes=(lsuffix, rsuffix),
+                sort=sort,
+                validate=validate,
+            )
+        else:
+            if on is not None:
+                raise ValueError(
+                    "Joining multiple DataFrames only supported for joining on index"
+                )
+
+            if rsuffix or lsuffix:
+                raise ValueError(
+                    "Suffixes not supported when joining multiple DataFrames"
+                )
+
+            # Mypy thinks the RHS is a
+            # "Union[DataFrame, Series, Iterable[Union[DataFrame, Series]]]" whereas
+            # the LHS is an "Iterable[DataFrame]", but in reality both types are
+            # "Iterable[Union[DataFrame, Series]]" due to the if statements
+            frames = [cast("DataFrame | Series", self)] + list(other)
+
+            can_concat = all(df.index.is_unique for df in frames)
+
+            # join indexes only using concat
+            if can_concat:
+                if how == "left":
+                    res = concat(
+                        frames, axis=1, join="outer", verify_integrity=True, sort=sort
+                    )
+                    return res.reindex(self.index, copy=False)
+                else:
+                    return concat(
+                        frames, axis=1, join=how, verify_integrity=True, sort=sort
+                    )
+
+            joined = frames[0]
+
+            for frame in frames[1:]:
+                joined = merge(
+                    joined,
+                    frame,
+                    how=how,
+                    left_index=True,
+                    right_index=True,
+                    validate=validate,
+                )
+
+            return joined
+
+    @Substitution("")
+    @Appender(_merge_doc, indents=2)
+    def merge(
+        self,
+        right: DataFrame | Series,
+        how: MergeHow = "inner",
+        on: IndexLabel | AnyArrayLike | None = None,
+        left_on: IndexLabel | AnyArrayLike | None = None,
+        right_on: IndexLabel | AnyArrayLike | None = None,
+        left_index: bool = False,
+        right_index: bool = False,
+        sort: bool = False,
+        suffixes: Suffixes = ("_x", "_y"),
+        copy: bool | None = None,
+        indicator: str | bool = False,
+        validate: MergeValidate | None = None,
+    ) -> DataFrame:
+        from pandas.core.reshape.merge import merge
+
+        return merge(
+            self,
+            right,
+            how=how,
+            on=on,
+            left_on=left_on,
+            right_on=right_on,
+            left_index=left_index,
+            right_index=right_index,
+            sort=sort,
+            suffixes=suffixes,
+            copy=copy,
+            indicator=indicator,
+            validate=validate,
+        )
+
+    def round(
+        self, decimals: int | dict[IndexLabel, int] | Series = 0, *args, **kwargs
+    ) -> DataFrame:
+        """
+        Round a DataFrame to a variable number of decimal places.
+
+        Parameters
+        ----------
+        decimals : int, dict, Series
+            Number of decimal places to round each column to. If an int is
+            given, round each column to the same number of places.
+            Otherwise dict and Series round to variable numbers of places.
+            Column names should be in the keys if `decimals` is a
+            dict-like, or in the index if `decimals` is a Series. Any
+            columns not included in `decimals` will be left as is. Elements
+            of `decimals` which are not columns of the input will be
+            ignored.
+        *args
+            Additional keywords have no effect but might be accepted for
+            compatibility with numpy.
+        **kwargs
+            Additional keywords have no effect but might be accepted for
+            compatibility with numpy.
+
+        Returns
+        -------
+        DataFrame
+            A DataFrame with the affected columns rounded to the specified
+            number of decimal places.
+
+        See Also
+        --------
+        numpy.around : Round a numpy array to the given number of decimals.
+        Series.round : Round a Series to the given number of decimals.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([(.21, .32), (.01, .67), (.66, .03), (.21, .18)],
+        ...                   columns=['dogs', 'cats'])
+        >>> df
+            dogs  cats
+        0  0.21  0.32
+        1  0.01  0.67
+        2  0.66  0.03
+        3  0.21  0.18
+
+        By providing an integer each column is rounded to the same number
+        of decimal places
+
+        >>> df.round(1)
+            dogs  cats
+        0   0.2   0.3
+        1   0.0   0.7
+        2   0.7   0.0
+        3   0.2   0.2
+
+        With a dict, the number of places for specific columns can be
+        specified with the column names as key and the number of decimal
+        places as value
+
+        >>> df.round({'dogs': 1, 'cats': 0})
+            dogs  cats
+        0   0.2   0.0
+        1   0.0   1.0
+        2   0.7   0.0
+        3   0.2   0.0
+
+        Using a Series, the number of places for specific columns can be
+        specified with the column names as index and the number of
+        decimal places as value
+
+        >>> decimals = pd.Series([0, 1], index=['cats', 'dogs'])
+        >>> df.round(decimals)
+            dogs  cats
+        0   0.2   0.0
+        1   0.0   1.0
+        2   0.7   0.0
+        3   0.2   0.0
+        """
+        from pandas.core.reshape.concat import concat
+
+        def _dict_round(df: DataFrame, decimals):
+            for col, vals in df.items():
+                try:
+                    yield _series_round(vals, decimals[col])
+                except KeyError:
+                    yield vals
+
+        def _series_round(ser: Series, decimals: int) -> Series:
+            if is_integer_dtype(ser.dtype) or is_float_dtype(ser.dtype):
+                return ser.round(decimals)
+            return ser
+
+        nv.validate_round(args, kwargs)
+
+        if isinstance(decimals, (dict, Series)):
+            if isinstance(decimals, Series) and not decimals.index.is_unique:
+                raise ValueError("Index of decimals must be unique")
+            if is_dict_like(decimals) and not all(
+                is_integer(value) for _, value in decimals.items()
+            ):
+                raise TypeError("Values in decimals must be integers")
+            new_cols = list(_dict_round(self, decimals))
+        elif is_integer(decimals):
+            # Dispatch to Block.round
+            # Argument "decimals" to "round" of "BaseBlockManager" has incompatible
+            # type "Union[int, integer[Any]]"; expected "int"
+            new_mgr = self._mgr.round(
+                decimals=decimals,  # type: ignore[arg-type]
+                using_cow=using_copy_on_write(),
+            )
+            return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(
+                self, method="round"
+            )
+        else:
+            raise TypeError("decimals must be an integer, a dict-like or a Series")
+
+        if new_cols is not None and len(new_cols) > 0:
+            return self._constructor(
+                concat(new_cols, axis=1), index=self.index, columns=self.columns
+            ).__finalize__(self, method="round")
+        else:
+            return self.copy(deep=False)
+
+    # ----------------------------------------------------------------------
+    # Statistical methods, etc.
+
+    def corr(
+        self,
+        method: CorrelationMethod = "pearson",
+        min_periods: int = 1,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        """
+        Compute pairwise correlation of columns, excluding NA/null values.
+
+        Parameters
+        ----------
+        method : {'pearson', 'kendall', 'spearman'} or callable
+            Method of correlation:
+
+            * pearson : standard correlation coefficient
+            * kendall : Kendall Tau correlation coefficient
+            * spearman : Spearman rank correlation
+            * callable: callable with input two 1d ndarrays
+                and returning a float. Note that the returned matrix from corr
+                will have 1 along the diagonals and will be symmetric
+                regardless of the callable's behavior.
+        min_periods : int, optional
+            Minimum number of observations required per pair of columns
+            to have a valid result. Currently only available for Pearson
+            and Spearman correlation.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+                The default value of ``numeric_only`` is now ``False``.
+
+        Returns
+        -------
+        DataFrame
+            Correlation matrix.
+
+        See Also
+        --------
+        DataFrame.corrwith : Compute pairwise correlation with another
+            DataFrame or Series.
+        Series.corr : Compute the correlation between two Series.
+
+        Notes
+        -----
+        Pearson, Kendall and Spearman correlation are currently computed using pairwise complete observations.
+
+        * `Pearson correlation coefficient `_
+        * `Kendall rank correlation coefficient `_
+        * `Spearman's rank correlation coefficient `_
+
+        Examples
+        --------
+        >>> def histogram_intersection(a, b):
+        ...     v = np.minimum(a, b).sum().round(decimals=1)
+        ...     return v
+        >>> df = pd.DataFrame([(.2, .3), (.0, .6), (.6, .0), (.2, .1)],
+        ...                   columns=['dogs', 'cats'])
+        >>> df.corr(method=histogram_intersection)
+              dogs  cats
+        dogs   1.0   0.3
+        cats   0.3   1.0
+
+        >>> df = pd.DataFrame([(1, 1), (2, np.nan), (np.nan, 3), (4, 4)],
+        ...                   columns=['dogs', 'cats'])
+        >>> df.corr(min_periods=3)
+              dogs  cats
+        dogs   1.0   NaN
+        cats   NaN   1.0
+        """  # noqa: E501
+        data = self._get_numeric_data() if numeric_only else self
+        cols = data.columns
+        idx = cols.copy()
+        mat = data.to_numpy(dtype=float, na_value=np.nan, copy=False)
+
+        if method == "pearson":
+            correl = libalgos.nancorr(mat, minp=min_periods)
+        elif method == "spearman":
+            correl = libalgos.nancorr_spearman(mat, minp=min_periods)
+        elif method == "kendall" or callable(method):
+            if min_periods is None:
+                min_periods = 1
+            mat = mat.T
+            corrf = nanops.get_corr_func(method)
+            K = len(cols)
+            correl = np.empty((K, K), dtype=float)
+            mask = np.isfinite(mat)
+            for i, ac in enumerate(mat):
+                for j, bc in enumerate(mat):
+                    if i > j:
+                        continue
+
+                    valid = mask[i] & mask[j]
+                    if valid.sum() < min_periods:
+                        c = np.nan
+                    elif i == j:
+                        c = 1.0
+                    elif not valid.all():
+                        c = corrf(ac[valid], bc[valid])
+                    else:
+                        c = corrf(ac, bc)
+                    correl[i, j] = c
+                    correl[j, i] = c
+        else:
+            raise ValueError(
+                "method must be either 'pearson', "
+                "'spearman', 'kendall', or a callable, "
+                f"'{method}' was supplied"
+            )
+
+        result = self._constructor(correl, index=idx, columns=cols, copy=False)
+        return result.__finalize__(self, method="corr")
+
+    def cov(
+        self,
+        min_periods: int | None = None,
+        ddof: int | None = 1,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        """
+        Compute pairwise covariance of columns, excluding NA/null values.
+
+        Compute the pairwise covariance among the series of a DataFrame.
+        The returned data frame is the `covariance matrix
+        `__ of the columns
+        of the DataFrame.
+
+        Both NA and null values are automatically excluded from the
+        calculation. (See the note below about bias from missing values.)
+        A threshold can be set for the minimum number of
+        observations for each value created. Comparisons with observations
+        below this threshold will be returned as ``NaN``.
+
+        This method is generally used for the analysis of time series data to
+        understand the relationship between different measures
+        across time.
+
+        Parameters
+        ----------
+        min_periods : int, optional
+            Minimum number of observations required per pair of columns
+            to have a valid result.
+
+        ddof : int, default 1
+            Delta degrees of freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+            This argument is applicable only when no ``nan`` is in the dataframe.
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+                The default value of ``numeric_only`` is now ``False``.
+
+        Returns
+        -------
+        DataFrame
+            The covariance matrix of the series of the DataFrame.
+
+        See Also
+        --------
+        Series.cov : Compute covariance with another Series.
+        core.window.ewm.ExponentialMovingWindow.cov : Exponential weighted sample
+            covariance.
+        core.window.expanding.Expanding.cov : Expanding sample covariance.
+        core.window.rolling.Rolling.cov : Rolling sample covariance.
+
+        Notes
+        -----
+        Returns the covariance matrix of the DataFrame's time series.
+        The covariance is normalized by N-ddof.
+
+        For DataFrames that have Series that are missing data (assuming that
+        data is `missing at random
+        `__)
+        the returned covariance matrix will be an unbiased estimate
+        of the variance and covariance between the member Series.
+
+        However, for many applications this estimate may not be acceptable
+        because the estimate covariance matrix is not guaranteed to be positive
+        semi-definite. This could lead to estimate correlations having
+        absolute values which are greater than one, and/or a non-invertible
+        covariance matrix. See `Estimation of covariance matrices
+        `__ for more details.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([(1, 2), (0, 3), (2, 0), (1, 1)],
+        ...                   columns=['dogs', 'cats'])
+        >>> df.cov()
+                  dogs      cats
+        dogs  0.666667 -1.000000
+        cats -1.000000  1.666667
+
+        >>> np.random.seed(42)
+        >>> df = pd.DataFrame(np.random.randn(1000, 5),
+        ...                   columns=['a', 'b', 'c', 'd', 'e'])
+        >>> df.cov()
+                  a         b         c         d         e
+        a  0.998438 -0.020161  0.059277 -0.008943  0.014144
+        b -0.020161  1.059352 -0.008543 -0.024738  0.009826
+        c  0.059277 -0.008543  1.010670 -0.001486 -0.000271
+        d -0.008943 -0.024738 -0.001486  0.921297 -0.013692
+        e  0.014144  0.009826 -0.000271 -0.013692  0.977795
+
+        **Minimum number of periods**
+
+        This method also supports an optional ``min_periods`` keyword
+        that specifies the required minimum number of non-NA observations for
+        each column pair in order to have a valid result:
+
+        >>> np.random.seed(42)
+        >>> df = pd.DataFrame(np.random.randn(20, 3),
+        ...                   columns=['a', 'b', 'c'])
+        >>> df.loc[df.index[:5], 'a'] = np.nan
+        >>> df.loc[df.index[5:10], 'b'] = np.nan
+        >>> df.cov(min_periods=12)
+                  a         b         c
+        a  0.316741       NaN -0.150812
+        b       NaN  1.248003  0.191417
+        c -0.150812  0.191417  0.895202
+        """
+        data = self._get_numeric_data() if numeric_only else self
+        cols = data.columns
+        idx = cols.copy()
+        mat = data.to_numpy(dtype=float, na_value=np.nan, copy=False)
+
+        if notna(mat).all():
+            if min_periods is not None and min_periods > len(mat):
+                base_cov = np.empty((mat.shape[1], mat.shape[1]))
+                base_cov.fill(np.nan)
+            else:
+                base_cov = np.cov(mat.T, ddof=ddof)
+            base_cov = base_cov.reshape((len(cols), len(cols)))
+        else:
+            base_cov = libalgos.nancorr(mat, cov=True, minp=min_periods)
+
+        result = self._constructor(base_cov, index=idx, columns=cols, copy=False)
+        return result.__finalize__(self, method="cov")
+
+    def corrwith(
+        self,
+        other: DataFrame | Series,
+        axis: Axis = 0,
+        drop: bool = False,
+        method: CorrelationMethod = "pearson",
+        numeric_only: bool = False,
+    ) -> Series:
+        """
+        Compute pairwise correlation.
+
+        Pairwise correlation is computed between rows or columns of
+        DataFrame with rows or columns of Series or DataFrame. DataFrames
+        are first aligned along both axes before computing the
+        correlations.
+
+        Parameters
+        ----------
+        other : DataFrame, Series
+            Object with which to compute correlations.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to use. 0 or 'index' to compute row-wise, 1 or 'columns' for
+            column-wise.
+        drop : bool, default False
+            Drop missing indices from result.
+        method : {'pearson', 'kendall', 'spearman'} or callable
+            Method of correlation:
+
+            * pearson : standard correlation coefficient
+            * kendall : Kendall Tau correlation coefficient
+            * spearman : Spearman rank correlation
+            * callable: callable with input two 1d ndarrays
+                and returning a float.
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+                The default value of ``numeric_only`` is now ``False``.
+
+        Returns
+        -------
+        Series
+            Pairwise correlations.
+
+        See Also
+        --------
+        DataFrame.corr : Compute pairwise correlation of columns.
+
+        Examples
+        --------
+        >>> index = ["a", "b", "c", "d", "e"]
+        >>> columns = ["one", "two", "three", "four"]
+        >>> df1 = pd.DataFrame(np.arange(20).reshape(5, 4), index=index, columns=columns)
+        >>> df2 = pd.DataFrame(np.arange(16).reshape(4, 4), index=index[:4], columns=columns)
+        >>> df1.corrwith(df2)
+        one      1.0
+        two      1.0
+        three    1.0
+        four     1.0
+        dtype: float64
+
+        >>> df2.corrwith(df1, axis=1)
+        a    1.0
+        b    1.0
+        c    1.0
+        d    1.0
+        e    NaN
+        dtype: float64
+        """  # noqa: E501
+        axis = self._get_axis_number(axis)
+        this = self._get_numeric_data() if numeric_only else self
+
+        if isinstance(other, Series):
+            return this.apply(lambda x: other.corr(x, method=method), axis=axis)
+
+        if numeric_only:
+            other = other._get_numeric_data()
+        left, right = this.align(other, join="inner", copy=False)
+
+        if axis == 1:
+            left = left.T
+            right = right.T
+
+        if method == "pearson":
+            # mask missing values
+            left = left + right * 0
+            right = right + left * 0
+
+            # demeaned data
+            ldem = left - left.mean(numeric_only=numeric_only)
+            rdem = right - right.mean(numeric_only=numeric_only)
+
+            num = (ldem * rdem).sum()
+            dom = (
+                (left.count() - 1)
+                * left.std(numeric_only=numeric_only)
+                * right.std(numeric_only=numeric_only)
+            )
+
+            correl = num / dom
+
+        elif method in ["kendall", "spearman"] or callable(method):
+
+            def c(x):
+                return nanops.nancorr(x[0], x[1], method=method)
+
+            correl = self._constructor_sliced(
+                map(c, zip(left.values.T, right.values.T)),
+                index=left.columns,
+                copy=False,
+            )
+
+        else:
+            raise ValueError(
+                f"Invalid method {method} was passed, "
+                "valid methods are: 'pearson', 'kendall', "
+                "'spearman', or callable"
+            )
+
+        if not drop:
+            # Find non-matching labels along the given axis
+            # and append missing correlations (GH 22375)
+            raxis: AxisInt = 1 if axis == 0 else 0
+            result_index = this._get_axis(raxis).union(other._get_axis(raxis))
+            idx_diff = result_index.difference(correl.index)
+
+            if len(idx_diff) > 0:
+                correl = correl._append(
+                    Series([np.nan] * len(idx_diff), index=idx_diff)
+                )
+
+        return correl
+
+    # ----------------------------------------------------------------------
+    # ndarray-like stats methods
+
+    def count(self, axis: Axis = 0, numeric_only: bool = False):
+        """
+        Count non-NA cells for each column or row.
+
+        The values `None`, `NaN`, `NaT`, ``pandas.NA`` are considered NA.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            If 0 or 'index' counts are generated for each column.
+            If 1 or 'columns' counts are generated for each row.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+        Returns
+        -------
+        Series
+            For each column/row the number of non-NA/null entries.
+
+        See Also
+        --------
+        Series.count: Number of non-NA elements in a Series.
+        DataFrame.value_counts: Count unique combinations of columns.
+        DataFrame.shape: Number of DataFrame rows and columns (including NA
+            elements).
+        DataFrame.isna: Boolean same-sized DataFrame showing places of NA
+            elements.
+
+        Examples
+        --------
+        Constructing DataFrame from a dictionary:
+
+        >>> df = pd.DataFrame({"Person":
+        ...                    ["John", "Myla", "Lewis", "John", "Myla"],
+        ...                    "Age": [24., np.nan, 21., 33, 26],
+        ...                    "Single": [False, True, True, True, False]})
+        >>> df
+           Person   Age  Single
+        0    John  24.0   False
+        1    Myla   NaN    True
+        2   Lewis  21.0    True
+        3    John  33.0    True
+        4    Myla  26.0   False
+
+        Notice the uncounted NA values:
+
+        >>> df.count()
+        Person    5
+        Age       4
+        Single    5
+        dtype: int64
+
+        Counts for each **row**:
+
+        >>> df.count(axis='columns')
+        0    3
+        1    2
+        2    3
+        3    3
+        4    3
+        dtype: int64
+        """
+        axis = self._get_axis_number(axis)
+
+        if numeric_only:
+            frame = self._get_numeric_data()
+        else:
+            frame = self
+
+        # GH #423
+        if len(frame._get_axis(axis)) == 0:
+            result = self._constructor_sliced(0, index=frame._get_agg_axis(axis))
+        else:
+            result = notna(frame).sum(axis=axis)
+
+        return result.astype("int64", copy=False).__finalize__(self, method="count")
+
+    def _reduce(
+        self,
+        op,
+        name: str,
+        *,
+        axis: Axis = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        filter_type=None,
+        **kwds,
+    ):
+        assert filter_type is None or filter_type == "bool", filter_type
+        out_dtype = "bool" if filter_type == "bool" else None
+
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+
+        def func(values: np.ndarray):
+            # We only use this in the case that operates on self.values
+            return op(values, axis=axis, skipna=skipna, **kwds)
+
+        dtype_has_keepdims: dict[ExtensionDtype, bool] = {}
+
+        def blk_func(values, axis: Axis = 1):
+            if isinstance(values, ExtensionArray):
+                if not is_1d_only_ea_dtype(values.dtype) and not isinstance(
+                    self._mgr, ArrayManager
+                ):
+                    return values._reduce(name, axis=1, skipna=skipna, **kwds)
+                has_keepdims = dtype_has_keepdims.get(values.dtype)
+                if has_keepdims is None:
+                    sign = signature(values._reduce)
+                    has_keepdims = "keepdims" in sign.parameters
+                    dtype_has_keepdims[values.dtype] = has_keepdims
+                if has_keepdims:
+                    return values._reduce(name, skipna=skipna, keepdims=True, **kwds)
+                else:
+                    warnings.warn(
+                        f"{type(values)}._reduce will require a `keepdims` parameter "
+                        "in the future",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    result = values._reduce(name, skipna=skipna, **kwds)
+                    return np.array([result])
+            else:
+                return op(values, axis=axis, skipna=skipna, **kwds)
+
+        def _get_data() -> DataFrame:
+            if filter_type is None:
+                data = self._get_numeric_data()
+            else:
+                # GH#25101, GH#24434
+                assert filter_type == "bool"
+                data = self._get_bool_data()
+            return data
+
+        # Case with EAs see GH#35881
+        df = self
+        if numeric_only:
+            df = _get_data()
+        if axis is None:
+            dtype = find_common_type([arr.dtype for arr in df._mgr.arrays])
+            if isinstance(dtype, ExtensionDtype):
+                df = df.astype(dtype, copy=False)
+                arr = concat_compat(list(df._iter_column_arrays()))
+                return arr._reduce(name, skipna=skipna, keepdims=False, **kwds)
+            return func(df.values)
+        elif axis == 1:
+            if len(df.index) == 0:
+                # Taking a transpose would result in no columns, losing the dtype.
+                # In the empty case, reducing along axis 0 or 1 gives the same
+                # result dtype, so reduce with axis=0 and ignore values
+                result = df._reduce(
+                    op,
+                    name,
+                    axis=0,
+                    skipna=skipna,
+                    numeric_only=False,
+                    filter_type=filter_type,
+                    **kwds,
+                ).iloc[:0]
+                result.index = df.index
+                return result
+
+            # kurtosis excluded since groupby does not implement it
+            if df.shape[1] and name != "kurt":
+                dtype = find_common_type([arr.dtype for arr in df._mgr.arrays])
+                if isinstance(dtype, ExtensionDtype):
+                    # GH 54341: fastpath for EA-backed axis=1 reductions
+                    # This flattens the frame into a single 1D array while keeping
+                    # track of the row and column indices of the original frame. Once
+                    # flattened, grouping by the row indices and aggregating should
+                    # be equivalent to transposing the original frame and aggregating
+                    # with axis=0.
+                    name = {"argmax": "idxmax", "argmin": "idxmin"}.get(name, name)
+                    df = df.astype(dtype, copy=False)
+                    arr = concat_compat(list(df._iter_column_arrays()))
+                    nrows, ncols = df.shape
+                    row_index = np.tile(np.arange(nrows), ncols)
+                    col_index = np.repeat(np.arange(ncols), nrows)
+                    ser = Series(arr, index=col_index, copy=False)
+                    # GroupBy will raise a warning with SeriesGroupBy as the object,
+                    # likely confusing users
+                    with rewrite_warning(
+                        target_message=(
+                            f"The behavior of SeriesGroupBy.{name} with all-NA values"
+                        ),
+                        target_category=FutureWarning,
+                        new_message=(
+                            f"The behavior of {type(self).__name__}.{name} with all-NA "
+                            "values, or any-NA and skipna=False, is deprecated. In "
+                            "a future version this will raise ValueError"
+                        ),
+                    ):
+                        result = ser.groupby(row_index).agg(name, **kwds)
+                    result.index = df.index
+                    if not skipna and name not in ("any", "all"):
+                        mask = df.isna().to_numpy(dtype=np.bool_).any(axis=1)
+                        other = -1 if name in ("idxmax", "idxmin") else lib.no_default
+                        result = result.mask(mask, other)
+                    return result
+
+            df = df.T
+
+        # After possibly _get_data and transposing, we are now in the
+        #  simple case where we can use BlockManager.reduce
+        res = df._mgr.reduce(blk_func)
+        out = df._constructor_from_mgr(res, axes=res.axes).iloc[0]
+        if out_dtype is not None and out.dtype != "boolean":
+            out = out.astype(out_dtype)
+        elif (df._mgr.get_dtypes() == object).any() and name not in ["any", "all"]:
+            out = out.astype(object)
+        elif len(self) == 0 and out.dtype == object and name in ("sum", "prod"):
+            # Even if we are object dtype, follow numpy and return
+            #  float64, see test_apply_funcs_over_empty
+            out = out.astype(np.float64)
+
+        return out
+
+    def _reduce_axis1(self, name: str, func, skipna: bool) -> Series:
+        """
+        Special case for _reduce to try to avoid a potentially-expensive transpose.
+
+        Apply the reduction block-wise along axis=1 and then reduce the resulting
+        1D arrays.
+        """
+        if name == "all":
+            result = np.ones(len(self), dtype=bool)
+            ufunc = np.logical_and
+        elif name == "any":
+            result = np.zeros(len(self), dtype=bool)
+            # error: Incompatible types in assignment
+            # (expression has type "_UFunc_Nin2_Nout1[Literal['logical_or'],
+            # Literal[20], Literal[False]]", variable has type
+            # "_UFunc_Nin2_Nout1[Literal['logical_and'], Literal[20],
+            # Literal[True]]")
+            ufunc = np.logical_or  # type: ignore[assignment]
+        else:
+            raise NotImplementedError(name)
+
+        for arr in self._mgr.arrays:
+            middle = func(arr, axis=0, skipna=skipna)
+            result = ufunc(result, middle)
+
+        res_ser = self._constructor_sliced(result, index=self.index, copy=False)
+        return res_ser
+
+    @doc(make_doc("any", ndim=2))
+    # error: Signature of "any" incompatible with supertype "NDFrame"
+    def any(  # type: ignore[override]
+        self,
+        *,
+        axis: Axis | None = 0,
+        bool_only: bool = False,
+        skipna: bool = True,
+        **kwargs,
+    ) -> Series | bool:
+        result = self._logical_func(
+            "any", nanops.nanany, axis, bool_only, skipna, **kwargs
+        )
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="any")
+        return result
+
+    @doc(make_doc("all", ndim=2))
+    def all(
+        self,
+        axis: Axis | None = 0,
+        bool_only: bool = False,
+        skipna: bool = True,
+        **kwargs,
+    ) -> Series | bool:
+        result = self._logical_func(
+            "all", nanops.nanall, axis, bool_only, skipna, **kwargs
+        )
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="all")
+        return result
+
+    @doc(make_doc("min", ndim=2))
+    def min(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().min(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="min")
+        return result
+
+    @doc(make_doc("max", ndim=2))
+    def max(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().max(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="max")
+        return result
+
+    @doc(make_doc("sum", ndim=2))
+    def sum(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        result = super().sum(axis, skipna, numeric_only, min_count, **kwargs)
+        return result.__finalize__(self, method="sum")
+
+    @doc(make_doc("prod", ndim=2))
+    def prod(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        result = super().prod(axis, skipna, numeric_only, min_count, **kwargs)
+        return result.__finalize__(self, method="prod")
+
+    @doc(make_doc("mean", ndim=2))
+    def mean(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().mean(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="mean")
+        return result
+
+    @doc(make_doc("median", ndim=2))
+    def median(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().median(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="median")
+        return result
+
+    @doc(make_doc("sem", ndim=2))
+    def sem(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().sem(axis, skipna, ddof, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="sem")
+        return result
+
+    @doc(make_doc("var", ndim=2))
+    def var(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().var(axis, skipna, ddof, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="var")
+        return result
+
+    @doc(make_doc("std", ndim=2))
+    def std(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().std(axis, skipna, ddof, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="std")
+        return result
+
+    @doc(make_doc("skew", ndim=2))
+    def skew(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().skew(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="skew")
+        return result
+
+    @doc(make_doc("kurt", ndim=2))
+    def kurt(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        result = super().kurt(axis, skipna, numeric_only, **kwargs)
+        if isinstance(result, Series):
+            result = result.__finalize__(self, method="kurt")
+        return result
+
+    kurtosis = kurt
+    product = prod
+
+    @doc(make_doc("cummin", ndim=2))
+    def cummin(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cummin(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cummax", ndim=2))
+    def cummax(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cummax(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cumsum", ndim=2))
+    def cumsum(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cumsum(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cumprod", 2))
+    def cumprod(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cumprod(self, axis, skipna, *args, **kwargs)
+
+    def nunique(self, axis: Axis = 0, dropna: bool = True) -> Series:
+        """
+        Count number of distinct elements in specified axis.
+
+        Return Series with number of distinct elements. Can ignore NaN
+        values.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for
+            column-wise.
+        dropna : bool, default True
+            Don't include NaN in the counts.
+
+        Returns
+        -------
+        Series
+
+        See Also
+        --------
+        Series.nunique: Method nunique for Series.
+        DataFrame.count: Count non-NA cells for each column or row.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [4, 5, 6], 'B': [4, 1, 1]})
+        >>> df.nunique()
+        A    3
+        B    2
+        dtype: int64
+
+        >>> df.nunique(axis=1)
+        0    1
+        1    2
+        2    2
+        dtype: int64
+        """
+        return self.apply(Series.nunique, axis=axis, dropna=dropna)
+
+    @doc(_shared_docs["idxmin"], numeric_only_default="False")
+    def idxmin(
+        self, axis: Axis = 0, skipna: bool = True, numeric_only: bool = False
+    ) -> Series:
+        axis = self._get_axis_number(axis)
+
+        if self.empty and len(self.axes[axis]):
+            axis_dtype = self.axes[axis].dtype
+            return self._constructor_sliced(dtype=axis_dtype)
+
+        if numeric_only:
+            data = self._get_numeric_data()
+        else:
+            data = self
+
+        res = data._reduce(
+            nanops.nanargmin, "argmin", axis=axis, skipna=skipna, numeric_only=False
+        )
+        indices = res._values
+        # indices will always be np.ndarray since axis is not N
+
+        if (indices == -1).any():
+            warnings.warn(
+                f"The behavior of {type(self).__name__}.idxmin with all-NA "
+                "values, or any-NA and skipna=False, is deprecated. In a future "
+                "version this will raise ValueError",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        index = data._get_axis(axis)
+        result = algorithms.take(
+            index._values, indices, allow_fill=True, fill_value=index._na_value
+        )
+        final_result = data._constructor_sliced(result, index=data._get_agg_axis(axis))
+        return final_result.__finalize__(self, method="idxmin")
+
+    @doc(_shared_docs["idxmax"], numeric_only_default="False")
+    def idxmax(
+        self, axis: Axis = 0, skipna: bool = True, numeric_only: bool = False
+    ) -> Series:
+        axis = self._get_axis_number(axis)
+
+        if self.empty and len(self.axes[axis]):
+            axis_dtype = self.axes[axis].dtype
+            return self._constructor_sliced(dtype=axis_dtype)
+
+        if numeric_only:
+            data = self._get_numeric_data()
+        else:
+            data = self
+
+        res = data._reduce(
+            nanops.nanargmax, "argmax", axis=axis, skipna=skipna, numeric_only=False
+        )
+        indices = res._values
+        # indices will always be 1d array since axis is not None
+
+        if (indices == -1).any():
+            warnings.warn(
+                f"The behavior of {type(self).__name__}.idxmax with all-NA "
+                "values, or any-NA and skipna=False, is deprecated. In a future "
+                "version this will raise ValueError",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        index = data._get_axis(axis)
+        result = algorithms.take(
+            index._values, indices, allow_fill=True, fill_value=index._na_value
+        )
+        final_result = data._constructor_sliced(result, index=data._get_agg_axis(axis))
+        return final_result.__finalize__(self, method="idxmax")
+
+    def _get_agg_axis(self, axis_num: int) -> Index:
+        """
+        Let's be explicit about this.
+        """
+        if axis_num == 0:
+            return self.columns
+        elif axis_num == 1:
+            return self.index
+        else:
+            raise ValueError(f"Axis must be 0 or 1 (got {repr(axis_num)})")
+
+    def mode(
+        self, axis: Axis = 0, numeric_only: bool = False, dropna: bool = True
+    ) -> DataFrame:
+        """
+        Get the mode(s) of each element along the selected axis.
+
+        The mode of a set of values is the value that appears most often.
+        It can be multiple values.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to iterate over while searching for the mode:
+
+            * 0 or 'index' : get mode of each column
+            * 1 or 'columns' : get mode of each row.
+
+        numeric_only : bool, default False
+            If True, only apply to numeric columns.
+        dropna : bool, default True
+            Don't consider counts of NaN/NaT.
+
+        Returns
+        -------
+        DataFrame
+            The modes of each column or row.
+
+        See Also
+        --------
+        Series.mode : Return the highest frequency value in a Series.
+        Series.value_counts : Return the counts of values in a Series.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('bird', 2, 2),
+        ...                    ('mammal', 4, np.nan),
+        ...                    ('arthropod', 8, 0),
+        ...                    ('bird', 2, np.nan)],
+        ...                   index=('falcon', 'horse', 'spider', 'ostrich'),
+        ...                   columns=('species', 'legs', 'wings'))
+        >>> df
+                   species  legs  wings
+        falcon        bird     2    2.0
+        horse       mammal     4    NaN
+        spider   arthropod     8    0.0
+        ostrich       bird     2    NaN
+
+        By default, missing values are not considered, and the mode of wings
+        are both 0 and 2. Because the resulting DataFrame has two rows,
+        the second row of ``species`` and ``legs`` contains ``NaN``.
+
+        >>> df.mode()
+          species  legs  wings
+        0    bird   2.0    0.0
+        1     NaN   NaN    2.0
+
+        Setting ``dropna=False`` ``NaN`` values are considered and they can be
+        the mode (like for wings).
+
+        >>> df.mode(dropna=False)
+          species  legs  wings
+        0    bird     2    NaN
+
+        Setting ``numeric_only=True``, only the mode of numeric columns is
+        computed, and columns of other types are ignored.
+
+        >>> df.mode(numeric_only=True)
+           legs  wings
+        0   2.0    0.0
+        1   NaN    2.0
+
+        To compute the mode over columns and not rows, use the axis parameter:
+
+        >>> df.mode(axis='columns', numeric_only=True)
+                   0    1
+        falcon   2.0  NaN
+        horse    4.0  NaN
+        spider   0.0  8.0
+        ostrich  2.0  NaN
+        """
+        data = self if not numeric_only else self._get_numeric_data()
+
+        def f(s):
+            return s.mode(dropna=dropna)
+
+        data = data.apply(f, axis=axis)
+        # Ensure index is type stable (should always use int index)
+        if data.empty:
+            data.index = default_index(0)
+
+        return data
+
+    @overload
+    def quantile(
+        self,
+        q: float = ...,
+        axis: Axis = ...,
+        numeric_only: bool = ...,
+        interpolation: QuantileInterpolation = ...,
+        method: Literal["single", "table"] = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def quantile(
+        self,
+        q: AnyArrayLike | Sequence[float],
+        axis: Axis = ...,
+        numeric_only: bool = ...,
+        interpolation: QuantileInterpolation = ...,
+        method: Literal["single", "table"] = ...,
+    ) -> Series | DataFrame:
+        ...
+
+    @overload
+    def quantile(
+        self,
+        q: float | AnyArrayLike | Sequence[float] = ...,
+        axis: Axis = ...,
+        numeric_only: bool = ...,
+        interpolation: QuantileInterpolation = ...,
+        method: Literal["single", "table"] = ...,
+    ) -> Series | DataFrame:
+        ...
+
+    def quantile(
+        self,
+        q: float | AnyArrayLike | Sequence[float] = 0.5,
+        axis: Axis = 0,
+        numeric_only: bool = False,
+        interpolation: QuantileInterpolation = "linear",
+        method: Literal["single", "table"] = "single",
+    ) -> Series | DataFrame:
+        """
+        Return values at the given quantile over requested axis.
+
+        Parameters
+        ----------
+        q : float or array-like, default 0.5 (50% quantile)
+            Value between 0 <= q <= 1, the quantile(s) to compute.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Equals 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionchanged:: 2.0.0
+                The default value of ``numeric_only`` is now ``False``.
+
+        interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
+            This optional parameter specifies the interpolation method to use,
+            when the desired quantile lies between two data points `i` and `j`:
+
+            * linear: `i + (j - i) * fraction`, where `fraction` is the
+              fractional part of the index surrounded by `i` and `j`.
+            * lower: `i`.
+            * higher: `j`.
+            * nearest: `i` or `j` whichever is nearest.
+            * midpoint: (`i` + `j`) / 2.
+        method : {'single', 'table'}, default 'single'
+            Whether to compute quantiles per-column ('single') or over all columns
+            ('table'). When 'table', the only allowed interpolation methods are
+            'nearest', 'lower', and 'higher'.
+
+        Returns
+        -------
+        Series or DataFrame
+
+            If ``q`` is an array, a DataFrame will be returned where the
+              index is ``q``, the columns are the columns of self, and the
+              values are the quantiles.
+            If ``q`` is a float, a Series will be returned where the
+              index is the columns of self and the values are the quantiles.
+
+        See Also
+        --------
+        core.window.rolling.Rolling.quantile: Rolling quantile.
+        numpy.percentile: Numpy function to compute the percentile.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.array([[1, 1], [2, 10], [3, 100], [4, 100]]),
+        ...                   columns=['a', 'b'])
+        >>> df.quantile(.1)
+        a    1.3
+        b    3.7
+        Name: 0.1, dtype: float64
+        >>> df.quantile([.1, .5])
+               a     b
+        0.1  1.3   3.7
+        0.5  2.5  55.0
+
+        Specifying `method='table'` will compute the quantile over all columns.
+
+        >>> df.quantile(.1, method="table", interpolation="nearest")
+        a    1
+        b    1
+        Name: 0.1, dtype: int64
+        >>> df.quantile([.1, .5], method="table", interpolation="nearest")
+             a    b
+        0.1  1    1
+        0.5  3  100
+
+        Specifying `numeric_only=False` will also compute the quantile of
+        datetime and timedelta data.
+
+        >>> df = pd.DataFrame({'A': [1, 2],
+        ...                    'B': [pd.Timestamp('2010'),
+        ...                          pd.Timestamp('2011')],
+        ...                    'C': [pd.Timedelta('1 days'),
+        ...                          pd.Timedelta('2 days')]})
+        >>> df.quantile(0.5, numeric_only=False)
+        A                    1.5
+        B    2010-07-02 12:00:00
+        C        1 days 12:00:00
+        Name: 0.5, dtype: object
+        """
+        validate_percentile(q)
+        axis = self._get_axis_number(axis)
+
+        if not is_list_like(q):
+            # BlockManager.quantile expects listlike, so we wrap and unwrap here
+            # error: List item 0 has incompatible type "float | ExtensionArray |
+            # ndarray[Any, Any] | Index | Series | Sequence[float]"; expected "float"
+            res_df = self.quantile(
+                [q],  # type: ignore[list-item]
+                axis=axis,
+                numeric_only=numeric_only,
+                interpolation=interpolation,
+                method=method,
+            )
+            if method == "single":
+                res = res_df.iloc[0]
+            else:
+                # cannot directly iloc over sparse arrays
+                res = res_df.T.iloc[:, 0]
+            if axis == 1 and len(self) == 0:
+                # GH#41544 try to get an appropriate dtype
+                dtype = find_common_type(list(self.dtypes))
+                if needs_i8_conversion(dtype):
+                    return res.astype(dtype)
+            return res
+
+        q = Index(q, dtype=np.float64)
+        data = self._get_numeric_data() if numeric_only else self
+
+        if axis == 1:
+            data = data.T
+
+        if len(data.columns) == 0:
+            # GH#23925 _get_numeric_data may have dropped all columns
+            cols = Index([], name=self.columns.name)
+
+            dtype = np.float64
+            if axis == 1:
+                # GH#41544 try to get an appropriate dtype
+                cdtype = find_common_type(list(self.dtypes))
+                if needs_i8_conversion(cdtype):
+                    dtype = cdtype
+
+            res = self._constructor([], index=q, columns=cols, dtype=dtype)
+            return res.__finalize__(self, method="quantile")
+
+        valid_method = {"single", "table"}
+        if method not in valid_method:
+            raise ValueError(
+                f"Invalid method: {method}. Method must be in {valid_method}."
+            )
+        if method == "single":
+            res = data._mgr.quantile(qs=q, interpolation=interpolation)
+        elif method == "table":
+            valid_interpolation = {"nearest", "lower", "higher"}
+            if interpolation not in valid_interpolation:
+                raise ValueError(
+                    f"Invalid interpolation: {interpolation}. "
+                    f"Interpolation must be in {valid_interpolation}"
+                )
+            # handle degenerate case
+            if len(data) == 0:
+                if data.ndim == 2:
+                    dtype = find_common_type(list(self.dtypes))
+                else:
+                    dtype = self.dtype
+                return self._constructor([], index=q, columns=data.columns, dtype=dtype)
+
+            q_idx = np.quantile(np.arange(len(data)), q, method=interpolation)
+
+            by = data.columns
+            if len(by) > 1:
+                keys = [data._get_label_or_level_values(x) for x in by]
+                indexer = lexsort_indexer(keys)
+            else:
+                k = data._get_label_or_level_values(by[0])
+                indexer = nargsort(k)
+
+            res = data._mgr.take(indexer[q_idx], verify=False)
+            res.axes[1] = q
+
+        result = self._constructor_from_mgr(res, axes=res.axes)
+        return result.__finalize__(self, method="quantile")
+
+    def to_timestamp(
+        self,
+        freq: Frequency | None = None,
+        how: ToTimestampHow = "start",
+        axis: Axis = 0,
+        copy: bool | None = None,
+    ) -> DataFrame:
+        """
+        Cast to DatetimeIndex of timestamps, at *beginning* of period.
+
+        Parameters
+        ----------
+        freq : str, default frequency of PeriodIndex
+            Desired frequency.
+        how : {'s', 'e', 'start', 'end'}
+            Convention for converting period to timestamp; start of period
+            vs. end.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to convert (the index by default).
+        copy : bool, default True
+            If False then underlying input data is not copied.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        DataFrame
+            The DataFrame has a DatetimeIndex.
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(['2023', '2024'], freq='Y')
+        >>> d = {'col1': [1, 2], 'col2': [3, 4]}
+        >>> df1 = pd.DataFrame(data=d, index=idx)
+        >>> df1
+              col1   col2
+        2023     1      3
+        2024	 2      4
+
+        The resulting timestamps will be at the beginning of the year in this case
+
+        >>> df1 = df1.to_timestamp()
+        >>> df1
+                    col1   col2
+        2023-01-01     1      3
+        2024-01-01     2      4
+        >>> df1.index
+        DatetimeIndex(['2023-01-01', '2024-01-01'], dtype='datetime64[ns]', freq=None)
+
+        Using `freq` which is the offset that the Timestamps will have
+
+        >>> df2 = pd.DataFrame(data=d, index=idx)
+        >>> df2 = df2.to_timestamp(freq='M')
+        >>> df2
+                    col1   col2
+        2023-01-31     1      3
+        2024-01-31     2      4
+        >>> df2.index
+        DatetimeIndex(['2023-01-31', '2024-01-31'], dtype='datetime64[ns]', freq=None)
+        """
+        new_obj = self.copy(deep=copy and not using_copy_on_write())
+
+        axis_name = self._get_axis_name(axis)
+        old_ax = getattr(self, axis_name)
+        if not isinstance(old_ax, PeriodIndex):
+            raise TypeError(f"unsupported Type {type(old_ax).__name__}")
+
+        new_ax = old_ax.to_timestamp(freq=freq, how=how)
+
+        setattr(new_obj, axis_name, new_ax)
+        return new_obj
+
+    def to_period(
+        self, freq: Frequency | None = None, axis: Axis = 0, copy: bool | None = None
+    ) -> DataFrame:
+        """
+        Convert DataFrame from DatetimeIndex to PeriodIndex.
+
+        Convert DataFrame from DatetimeIndex to PeriodIndex with desired
+        frequency (inferred from index if not passed).
+
+        Parameters
+        ----------
+        freq : str, default
+            Frequency of the PeriodIndex.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to convert (the index by default).
+        copy : bool, default True
+            If False then underlying input data is not copied.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        DataFrame
+            The DataFrame has a PeriodIndex.
+
+        Examples
+        --------
+        >>> idx = pd.to_datetime(
+        ...     [
+        ...         "2001-03-31 00:00:00",
+        ...         "2002-05-31 00:00:00",
+        ...         "2003-08-31 00:00:00",
+        ...     ]
+        ... )
+
+        >>> idx
+        DatetimeIndex(['2001-03-31', '2002-05-31', '2003-08-31'],
+        dtype='datetime64[ns]', freq=None)
+
+        >>> idx.to_period("M")
+        PeriodIndex(['2001-03', '2002-05', '2003-08'], dtype='period[M]')
+
+        For the yearly frequency
+
+        >>> idx.to_period("Y")
+        PeriodIndex(['2001', '2002', '2003'], dtype='period[Y-DEC]')
+        """
+        new_obj = self.copy(deep=copy and not using_copy_on_write())
+
+        axis_name = self._get_axis_name(axis)
+        old_ax = getattr(self, axis_name)
+        if not isinstance(old_ax, DatetimeIndex):
+            raise TypeError(f"unsupported Type {type(old_ax).__name__}")
+
+        new_ax = old_ax.to_period(freq=freq)
+
+        setattr(new_obj, axis_name, new_ax)
+        return new_obj
+
+    def isin(self, values: Series | DataFrame | Sequence | Mapping) -> DataFrame:
+        """
+        Whether each element in the DataFrame is contained in values.
+
+        Parameters
+        ----------
+        values : iterable, Series, DataFrame or dict
+            The result will only be true at a location if all the
+            labels match. If `values` is a Series, that's the index. If
+            `values` is a dict, the keys must be the column names,
+            which must match. If `values` is a DataFrame,
+            then both the index and column labels must match.
+
+        Returns
+        -------
+        DataFrame
+            DataFrame of booleans showing whether each element in the DataFrame
+            is contained in values.
+
+        See Also
+        --------
+        DataFrame.eq: Equality test for DataFrame.
+        Series.isin: Equivalent method on Series.
+        Series.str.contains: Test if pattern or regex is contained within a
+            string of a Series or Index.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'num_legs': [2, 4], 'num_wings': [2, 0]},
+        ...                   index=['falcon', 'dog'])
+        >>> df
+                num_legs  num_wings
+        falcon         2          2
+        dog            4          0
+
+        When ``values`` is a list check whether every value in the DataFrame
+        is present in the list (which animals have 0 or 2 legs or wings)
+
+        >>> df.isin([0, 2])
+                num_legs  num_wings
+        falcon      True       True
+        dog        False       True
+
+        To check if ``values`` is *not* in the DataFrame, use the ``~`` operator:
+
+        >>> ~df.isin([0, 2])
+                num_legs  num_wings
+        falcon     False      False
+        dog         True      False
+
+        When ``values`` is a dict, we can pass values to check for each
+        column separately:
+
+        >>> df.isin({'num_wings': [0, 3]})
+                num_legs  num_wings
+        falcon     False      False
+        dog        False       True
+
+        When ``values`` is a Series or DataFrame the index and column must
+        match. Note that 'falcon' does not match based on the number of legs
+        in other.
+
+        >>> other = pd.DataFrame({'num_legs': [8, 3], 'num_wings': [0, 2]},
+        ...                      index=['spider', 'falcon'])
+        >>> df.isin(other)
+                num_legs  num_wings
+        falcon     False       True
+        dog        False      False
+        """
+        if isinstance(values, dict):
+            from pandas.core.reshape.concat import concat
+
+            values = collections.defaultdict(list, values)
+            result = concat(
+                (
+                    self.iloc[:, [i]].isin(values[col])
+                    for i, col in enumerate(self.columns)
+                ),
+                axis=1,
+            )
+        elif isinstance(values, Series):
+            if not values.index.is_unique:
+                raise ValueError("cannot compute isin with a duplicate axis.")
+            result = self.eq(values.reindex_like(self), axis="index")
+        elif isinstance(values, DataFrame):
+            if not (values.columns.is_unique and values.index.is_unique):
+                raise ValueError("cannot compute isin with a duplicate axis.")
+            result = self.eq(values.reindex_like(self))
+        else:
+            if not is_list_like(values):
+                raise TypeError(
+                    "only list-like or dict-like objects are allowed "
+                    "to be passed to DataFrame.isin(), "
+                    f"you passed a '{type(values).__name__}'"
+                )
+
+            def isin_(x):
+                # error: Argument 2 to "isin" has incompatible type "Union[Series,
+                # DataFrame, Sequence[Any], Mapping[Any, Any]]"; expected
+                # "Union[Union[Union[ExtensionArray, ndarray[Any, Any]], Index,
+                # Series], List[Any], range]"
+                result = algorithms.isin(
+                    x.ravel(),
+                    values,  # type: ignore[arg-type]
+                )
+                return result.reshape(x.shape)
+
+            res_mgr = self._mgr.apply(isin_)
+            result = self._constructor_from_mgr(
+                res_mgr,
+                axes=res_mgr.axes,
+            )
+        return result.__finalize__(self, method="isin")
+
+    # ----------------------------------------------------------------------
+    # Add index and columns
+    _AXIS_ORDERS: list[Literal["index", "columns"]] = ["index", "columns"]
+    _AXIS_TO_AXIS_NUMBER: dict[Axis, int] = {
+        **NDFrame._AXIS_TO_AXIS_NUMBER,
+        1: 1,
+        "columns": 1,
+    }
+    _AXIS_LEN = len(_AXIS_ORDERS)
+    _info_axis_number: Literal[1] = 1
+    _info_axis_name: Literal["columns"] = "columns"
+
+    index = properties.AxisProperty(
+        axis=1,
+        doc="""
+        The index (row labels) of the DataFrame.
+
+        The index of a DataFrame is a series of labels that identify each row.
+        The labels can be integers, strings, or any other hashable type. The index
+        is used for label-based access and alignment, and can be accessed or
+        modified using this attribute.
+
+        Returns
+        -------
+        pandas.Index
+            The index labels of the DataFrame.
+
+        See Also
+        --------
+        DataFrame.columns : The column labels of the DataFrame.
+        DataFrame.to_numpy : Convert the DataFrame to a NumPy array.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'Name': ['Alice', 'Bob', 'Aritra'],
+        ...                    'Age': [25, 30, 35],
+        ...                    'Location': ['Seattle', 'New York', 'Kona']},
+        ...                   index=([10, 20, 30]))
+        >>> df.index
+        Index([10, 20, 30], dtype='int64')
+
+        In this example, we create a DataFrame with 3 rows and 3 columns,
+        including Name, Age, and Location information. We set the index labels to
+        be the integers 10, 20, and 30. We then access the `index` attribute of the
+        DataFrame, which returns an `Index` object containing the index labels.
+
+        >>> df.index = [100, 200, 300]
+        >>> df
+            Name  Age Location
+        100  Alice   25  Seattle
+        200    Bob   30 New York
+        300  Aritra  35    Kona
+
+        In this example, we modify the index labels of the DataFrame by assigning
+        a new list of labels to the `index` attribute. The DataFrame is then
+        updated with the new labels, and the output shows the modified DataFrame.
+        """,
+    )
+    columns = properties.AxisProperty(
+        axis=0,
+        doc=dedent(
+            """
+                The column labels of the DataFrame.
+
+                Examples
+                --------
+                >>> df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+                >>> df
+                     A  B
+                0    1  3
+                1    2  4
+                >>> df.columns
+                Index(['A', 'B'], dtype='object')
+                """
+        ),
+    )
+
+    # ----------------------------------------------------------------------
+    # Add plotting methods to DataFrame
+    plot = CachedAccessor("plot", pandas.plotting.PlotAccessor)
+    hist = pandas.plotting.hist_frame
+    boxplot = pandas.plotting.boxplot_frame
+    sparse = CachedAccessor("sparse", SparseFrameAccessor)
+
+    # ----------------------------------------------------------------------
+    # Internal Interface Methods
+
+    def _to_dict_of_blocks(self):
+        """
+        Return a dict of dtype -> Constructor Types that
+        each is a homogeneous dtype.
+
+        Internal ONLY - only works for BlockManager
+        """
+        mgr = self._mgr
+        # convert to BlockManager if needed -> this way support ArrayManager as well
+        mgr = cast(BlockManager, mgr_to_mgr(mgr, "block"))
+        return {
+            k: self._constructor_from_mgr(v, axes=v.axes).__finalize__(self)
+            for k, v, in mgr.to_dict().items()
+        }
+
+    @property
+    def values(self) -> np.ndarray:
+        """
+        Return a Numpy representation of the DataFrame.
+
+        .. warning::
+
+           We recommend using :meth:`DataFrame.to_numpy` instead.
+
+        Only the values in the DataFrame will be returned, the axes labels
+        will be removed.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values of the DataFrame.
+
+        See Also
+        --------
+        DataFrame.to_numpy : Recommended alternative to this method.
+        DataFrame.index : Retrieve the index labels.
+        DataFrame.columns : Retrieving the column names.
+
+        Notes
+        -----
+        The dtype will be a lower-common-denominator dtype (implicit
+        upcasting); that is to say if the dtypes (even of numeric types)
+        are mixed, the one that accommodates all will be chosen. Use this
+        with care if you are not dealing with the blocks.
+
+        e.g. If the dtypes are float16 and float32, dtype will be upcast to
+        float32.  If dtypes are int32 and uint8, dtype will be upcast to
+        int32. By :func:`numpy.find_common_type` convention, mixing int64
+        and uint64 will result in a float64 dtype.
+
+        Examples
+        --------
+        A DataFrame where all columns are the same type (e.g., int64) results
+        in an array of the same type.
+
+        >>> df = pd.DataFrame({'age':    [ 3,  29],
+        ...                    'height': [94, 170],
+        ...                    'weight': [31, 115]})
+        >>> df
+           age  height  weight
+        0    3      94      31
+        1   29     170     115
+        >>> df.dtypes
+        age       int64
+        height    int64
+        weight    int64
+        dtype: object
+        >>> df.values
+        array([[  3,  94,  31],
+               [ 29, 170, 115]])
+
+        A DataFrame with mixed type columns(e.g., str/object, int64, float32)
+        results in an ndarray of the broadest type that accommodates these
+        mixed types (e.g., object).
+
+        >>> df2 = pd.DataFrame([('parrot',   24.0, 'second'),
+        ...                     ('lion',     80.5, 1),
+        ...                     ('monkey', np.nan, None)],
+        ...                   columns=('name', 'max_speed', 'rank'))
+        >>> df2.dtypes
+        name          object
+        max_speed    float64
+        rank          object
+        dtype: object
+        >>> df2.values
+        array([['parrot', 24.0, 'second'],
+               ['lion', 80.5, 1],
+               ['monkey', nan, None]], dtype=object)
+        """
+        return self._mgr.as_array()
+
+
+def _from_nested_dict(data) -> collections.defaultdict:
+    new_data: collections.defaultdict = collections.defaultdict(dict)
+    for index, s in data.items():
+        for col, v in s.items():
+            new_data[col][index] = v
+    return new_data
+
+
+def _reindex_for_setitem(
+    value: DataFrame | Series, index: Index
+) -> tuple[ArrayLike, BlockValuesRefs | None]:
+    # reindex if necessary
+
+    if value.index.equals(index) or not len(index):
+        if using_copy_on_write() and isinstance(value, Series):
+            return value._values, value._references
+        return value._values.copy(), None
+
+    # GH#4107
+    try:
+        reindexed_value = value.reindex(index)._values
+    except ValueError as err:
+        # raised in MultiIndex.from_tuples, see test_insert_error_msmgs
+        if not value.index.is_unique:
+            # duplicate axis
+            raise err
+
+        raise TypeError(
+            "incompatible index of inserted column with frame index"
+        ) from err
+    return reindexed_value, None
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/generic.py b/.venv/lib/python3.13/site-packages/pandas/core/generic.py
new file mode 100644
index 0000000000000000000000000000000000000000..dd8c1723be54a91bf87f72c72e20607452ad65db
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/generic.py
@@ -0,0 +1,14025 @@
+# pyright: reportPropertyTypeMismatch=false
+from __future__ import annotations
+
+import collections
+from copy import deepcopy
+import datetime as dt
+from functools import partial
+import gc
+from json import loads
+import operator
+import pickle
+import re
+import sys
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ClassVar,
+    Literal,
+    NoReturn,
+    cast,
+    final,
+    overload,
+)
+import warnings
+import weakref
+
+import numpy as np
+
+from pandas._config import (
+    config,
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs import lib
+from pandas._libs.lib import is_range_indexer
+from pandas._libs.tslibs import (
+    Period,
+    Tick,
+    Timestamp,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import freq_to_period_freqstr
+from pandas._typing import (
+    AlignJoin,
+    AnyArrayLike,
+    ArrayLike,
+    Axes,
+    Axis,
+    AxisInt,
+    CompressionOptions,
+    DtypeArg,
+    DtypeBackend,
+    DtypeObj,
+    FilePath,
+    FillnaOptions,
+    FloatFormatType,
+    FormattersType,
+    Frequency,
+    IgnoreRaise,
+    IndexKeyFunc,
+    IndexLabel,
+    InterpolateOptions,
+    IntervalClosedType,
+    JSONSerializable,
+    Level,
+    Manager,
+    NaPosition,
+    NDFrameT,
+    OpenFileErrors,
+    RandomState,
+    ReindexMethod,
+    Renamer,
+    Scalar,
+    Self,
+    SequenceNotStr,
+    SortKind,
+    StorageOptions,
+    Suffixes,
+    T,
+    TimeAmbiguous,
+    TimedeltaConvertibleTypes,
+    TimeNonexistent,
+    TimestampConvertibleTypes,
+    TimeUnit,
+    ValueKeyFunc,
+    WriteBuffer,
+    WriteExcelBuffer,
+    npt,
+)
+from pandas.compat import PYPY
+from pandas.compat._constants import (
+    REF_COUNT,
+    WARNING_CHECK_DISABLED,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    AbstractMethodError,
+    ChainedAssignmentError,
+    InvalidIndexError,
+    SettingWithCopyError,
+    SettingWithCopyWarning,
+    _chained_assignment_method_msg,
+    _chained_assignment_warning_method_msg,
+    _check_cacher,
+)
+from pandas.util._decorators import (
+    deprecate_nonkeyword_arguments,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import (
+    check_dtype_backend,
+    validate_ascending,
+    validate_bool_kwarg,
+    validate_fillna_kwargs,
+    validate_inclusive,
+)
+
+from pandas.core.dtypes.astype import astype_is_view
+from pandas.core.dtypes.common import (
+    ensure_object,
+    ensure_platform_int,
+    ensure_str,
+    is_bool,
+    is_bool_dtype,
+    is_dict_like,
+    is_extension_array_dtype,
+    is_list_like,
+    is_number,
+    is_numeric_dtype,
+    is_re_compilable,
+    is_scalar,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import (
+    is_hashable,
+    is_nested_list_like,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    notna,
+)
+
+from pandas.core import (
+    algorithms as algos,
+    arraylike,
+    common,
+    indexing,
+    missing,
+    nanops,
+    sample,
+)
+from pandas.core.array_algos.replace import should_use_regex
+from pandas.core.arrays import ExtensionArray
+from pandas.core.base import PandasObject
+from pandas.core.construction import extract_array
+from pandas.core.flags import Flags
+from pandas.core.indexes.api import (
+    DatetimeIndex,
+    Index,
+    MultiIndex,
+    PeriodIndex,
+    RangeIndex,
+    default_index,
+    ensure_index,
+)
+from pandas.core.internals import (
+    ArrayManager,
+    BlockManager,
+    SingleArrayManager,
+)
+from pandas.core.internals.construction import (
+    mgr_to_mgr,
+    ndarray_to_mgr,
+)
+from pandas.core.methods.describe import describe_ndframe
+from pandas.core.missing import (
+    clean_fill_method,
+    clean_reindex_fill_method,
+    find_valid_index,
+)
+from pandas.core.reshape.concat import concat
+from pandas.core.shared_docs import _shared_docs
+from pandas.core.sorting import get_indexer_indexer
+from pandas.core.window import (
+    Expanding,
+    ExponentialMovingWindow,
+    Rolling,
+    Window,
+)
+
+from pandas.io.formats.format import (
+    DataFrameFormatter,
+    DataFrameRenderer,
+)
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+        Mapping,
+        Sequence,
+    )
+
+    from pandas._libs.tslibs import BaseOffset
+
+    from pandas import (
+        DataFrame,
+        ExcelWriter,
+        HDFStore,
+        Series,
+    )
+    from pandas.core.indexers.objects import BaseIndexer
+    from pandas.core.resample import Resampler
+
+# goal is to be able to define the docs close to function, while still being
+# able to share
+_shared_docs = {**_shared_docs}
+_shared_doc_kwargs = {
+    "axes": "keywords for axes",
+    "klass": "Series/DataFrame",
+    "axes_single_arg": "{0 or 'index'} for Series, {0 or 'index', 1 or 'columns'} for DataFrame",  # noqa: E501
+    "inplace": """
+    inplace : bool, default False
+        If True, performs operation inplace and returns None.""",
+    "optional_by": """
+        by : str or list of str
+            Name or list of names to sort by""",
+}
+
+
+bool_t = bool  # Need alias because NDFrame has def bool:
+
+
+class NDFrame(PandasObject, indexing.IndexingMixin):
+    """
+    N-dimensional analogue of DataFrame. Store multi-dimensional in a
+    size-mutable, labeled data structure
+
+    Parameters
+    ----------
+    data : BlockManager
+    axes : list
+    copy : bool, default False
+    """
+
+    _internal_names: list[str] = [
+        "_mgr",
+        "_cacher",
+        "_item_cache",
+        "_cache",
+        "_is_copy",
+        "_name",
+        "_metadata",
+        "_flags",
+    ]
+    _internal_names_set: set[str] = set(_internal_names)
+    _accessors: set[str] = set()
+    _hidden_attrs: frozenset[str] = frozenset([])
+    _metadata: list[str] = []
+    _is_copy: weakref.ReferenceType[NDFrame] | str | None = None
+    _mgr: Manager
+    _attrs: dict[Hashable, Any]
+    _typ: str
+
+    # ----------------------------------------------------------------------
+    # Constructors
+
+    def __init__(self, data: Manager) -> None:
+        object.__setattr__(self, "_is_copy", None)
+        object.__setattr__(self, "_mgr", data)
+        object.__setattr__(self, "_item_cache", {})
+        object.__setattr__(self, "_attrs", {})
+        object.__setattr__(self, "_flags", Flags(self, allows_duplicate_labels=True))
+
+    @final
+    @classmethod
+    def _init_mgr(
+        cls,
+        mgr: Manager,
+        axes: dict[Literal["index", "columns"], Axes | None],
+        dtype: DtypeObj | None = None,
+        copy: bool_t = False,
+    ) -> Manager:
+        """passed a manager and a axes dict"""
+        for a, axe in axes.items():
+            if axe is not None:
+                axe = ensure_index(axe)
+                bm_axis = cls._get_block_manager_axis(a)
+                mgr = mgr.reindex_axis(axe, axis=bm_axis)
+
+        # make a copy if explicitly requested
+        if copy:
+            mgr = mgr.copy()
+        if dtype is not None:
+            # avoid further copies if we can
+            if (
+                isinstance(mgr, BlockManager)
+                and len(mgr.blocks) == 1
+                and mgr.blocks[0].values.dtype == dtype
+            ):
+                pass
+            else:
+                mgr = mgr.astype(dtype=dtype)
+        return mgr
+
+    @final
+    def _as_manager(self, typ: str, copy: bool_t = True) -> Self:
+        """
+        Private helper function to create a DataFrame with specific manager.
+
+        Parameters
+        ----------
+        typ : {"block", "array"}
+        copy : bool, default True
+            Only controls whether the conversion from Block->ArrayManager
+            copies the 1D arrays (to ensure proper/contiguous memory layout).
+
+        Returns
+        -------
+        DataFrame
+            New DataFrame using specified manager type. Is not guaranteed
+            to be a copy or not.
+        """
+        new_mgr: Manager
+        new_mgr = mgr_to_mgr(self._mgr, typ=typ, copy=copy)
+        # fastpath of passing a manager doesn't check the option/manager class
+        return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(self)
+
+    @final
+    @classmethod
+    def _from_mgr(cls, mgr: Manager, axes: list[Index]) -> Self:
+        """
+        Construct a new object of this type from a Manager object and axes.
+
+        Parameters
+        ----------
+        mgr : Manager
+            Must have the same ndim as cls.
+        axes : list[Index]
+
+        Notes
+        -----
+        The axes must match mgr.axes, but are required for future-proofing
+        in the event that axes are refactored out of the Manager objects.
+        """
+        obj = cls.__new__(cls)
+        NDFrame.__init__(obj, mgr)
+        return obj
+
+    # ----------------------------------------------------------------------
+    # attrs and flags
+
+    @property
+    def attrs(self) -> dict[Hashable, Any]:
+        """
+        Dictionary of global attributes of this dataset.
+
+        .. warning::
+
+           attrs is experimental and may change without warning.
+
+        See Also
+        --------
+        DataFrame.flags : Global flags applying to this object.
+
+        Notes
+        -----
+        Many operations that create new datasets will copy ``attrs``. Copies
+        are always deep so that changing ``attrs`` will only affect the
+        present dataset. ``pandas.concat`` copies ``attrs`` only if all input
+        datasets have the same ``attrs``.
+
+        Examples
+        --------
+        For Series:
+
+        >>> ser = pd.Series([1, 2, 3])
+        >>> ser.attrs = {"A": [10, 20, 30]}
+        >>> ser.attrs
+        {'A': [10, 20, 30]}
+
+        For DataFrame:
+
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+        >>> df.attrs = {"A": [10, 20, 30]}
+        >>> df.attrs
+        {'A': [10, 20, 30]}
+        """
+        return self._attrs
+
+    @attrs.setter
+    def attrs(self, value: Mapping[Hashable, Any]) -> None:
+        self._attrs = dict(value)
+
+    @final
+    @property
+    def flags(self) -> Flags:
+        """
+        Get the properties associated with this pandas object.
+
+        The available flags are
+
+        * :attr:`Flags.allows_duplicate_labels`
+
+        See Also
+        --------
+        Flags : Flags that apply to pandas objects.
+        DataFrame.attrs : Global metadata applying to this dataset.
+
+        Notes
+        -----
+        "Flags" differ from "metadata". Flags reflect properties of the
+        pandas object (the Series or DataFrame). Metadata refer to properties
+        of the dataset, and should be stored in :attr:`DataFrame.attrs`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": [1, 2]})
+        >>> df.flags
+        
+
+        Flags can be get or set using ``.``
+
+        >>> df.flags.allows_duplicate_labels
+        True
+        >>> df.flags.allows_duplicate_labels = False
+
+        Or by slicing with a key
+
+        >>> df.flags["allows_duplicate_labels"]
+        False
+        >>> df.flags["allows_duplicate_labels"] = True
+        """
+        return self._flags
+
+    @final
+    def set_flags(
+        self,
+        *,
+        copy: bool_t = False,
+        allows_duplicate_labels: bool_t | None = None,
+    ) -> Self:
+        """
+        Return a new object with updated flags.
+
+        Parameters
+        ----------
+        copy : bool, default False
+            Specify if a copy of the object should be made.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        allows_duplicate_labels : bool, optional
+            Whether the returned object allows duplicate labels.
+
+        Returns
+        -------
+        Series or DataFrame
+            The same type as the caller.
+
+        See Also
+        --------
+        DataFrame.attrs : Global metadata applying to this dataset.
+        DataFrame.flags : Global flags applying to this object.
+
+        Notes
+        -----
+        This method returns a new object that's a view on the same data
+        as the input. Mutating the input or the output values will be reflected
+        in the other.
+
+        This method is intended to be used in method chains.
+
+        "Flags" differ from "metadata". Flags reflect properties of the
+        pandas object (the Series or DataFrame). Metadata refer to properties
+        of the dataset, and should be stored in :attr:`DataFrame.attrs`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": [1, 2]})
+        >>> df.flags.allows_duplicate_labels
+        True
+        >>> df2 = df.set_flags(allows_duplicate_labels=False)
+        >>> df2.flags.allows_duplicate_labels
+        False
+        """
+        df = self.copy(deep=copy and not using_copy_on_write())
+        if allows_duplicate_labels is not None:
+            df.flags["allows_duplicate_labels"] = allows_duplicate_labels
+        return df
+
+    @final
+    @classmethod
+    def _validate_dtype(cls, dtype) -> DtypeObj | None:
+        """validate the passed dtype"""
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+            # a compound dtype
+            if dtype.kind == "V":
+                raise NotImplementedError(
+                    "compound dtypes are not implemented "
+                    f"in the {cls.__name__} constructor"
+                )
+
+        return dtype
+
+    # ----------------------------------------------------------------------
+    # Construction
+
+    @property
+    def _constructor(self) -> Callable[..., Self]:
+        """
+        Used when a manipulation result has the same dimensions as the
+        original.
+        """
+        raise AbstractMethodError(self)
+
+    # ----------------------------------------------------------------------
+    # Internals
+
+    @final
+    @property
+    def _data(self):
+        # GH#33054 retained because some downstream packages uses this,
+        #  e.g. fastparquet
+        # GH#33333
+        warnings.warn(
+            f"{type(self).__name__}._data is deprecated and will be removed in "
+            "a future version. Use public APIs instead.",
+            DeprecationWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._mgr
+
+    # ----------------------------------------------------------------------
+    # Axis
+    _AXIS_ORDERS: list[Literal["index", "columns"]]
+    _AXIS_TO_AXIS_NUMBER: dict[Axis, AxisInt] = {0: 0, "index": 0, "rows": 0}
+    _info_axis_number: int
+    _info_axis_name: Literal["index", "columns"]
+    _AXIS_LEN: int
+
+    @final
+    def _construct_axes_dict(self, axes: Sequence[Axis] | None = None, **kwargs):
+        """Return an axes dictionary for myself."""
+        d = {a: self._get_axis(a) for a in (axes or self._AXIS_ORDERS)}
+        # error: Argument 1 to "update" of "MutableMapping" has incompatible type
+        # "Dict[str, Any]"; expected "SupportsKeysAndGetItem[Union[int, str], Any]"
+        d.update(kwargs)  # type: ignore[arg-type]
+        return d
+
+    @final
+    @classmethod
+    def _get_axis_number(cls, axis: Axis) -> AxisInt:
+        try:
+            return cls._AXIS_TO_AXIS_NUMBER[axis]
+        except KeyError:
+            raise ValueError(f"No axis named {axis} for object type {cls.__name__}")
+
+    @final
+    @classmethod
+    def _get_axis_name(cls, axis: Axis) -> Literal["index", "columns"]:
+        axis_number = cls._get_axis_number(axis)
+        return cls._AXIS_ORDERS[axis_number]
+
+    @final
+    def _get_axis(self, axis: Axis) -> Index:
+        axis_number = self._get_axis_number(axis)
+        assert axis_number in {0, 1}
+        return self.index if axis_number == 0 else self.columns
+
+    @final
+    @classmethod
+    def _get_block_manager_axis(cls, axis: Axis) -> AxisInt:
+        """Map the axis to the block_manager axis."""
+        axis = cls._get_axis_number(axis)
+        ndim = cls._AXIS_LEN
+        if ndim == 2:
+            # i.e. DataFrame
+            return 1 - axis
+        return axis
+
+    @final
+    def _get_axis_resolvers(self, axis: str) -> dict[str, Series | MultiIndex]:
+        # index or columns
+        axis_index = getattr(self, axis)
+        d = {}
+        prefix = axis[0]
+
+        for i, name in enumerate(axis_index.names):
+            if name is not None:
+                key = level = name
+            else:
+                # prefix with 'i' or 'c' depending on the input axis
+                # e.g., you must do ilevel_0 for the 0th level of an unnamed
+                # multiiindex
+                key = f"{prefix}level_{i}"
+                level = i
+
+            level_values = axis_index.get_level_values(level)
+            s = level_values.to_series()
+            s.index = axis_index
+            d[key] = s
+
+        # put the index/columns itself in the dict
+        if isinstance(axis_index, MultiIndex):
+            dindex = axis_index
+        else:
+            dindex = axis_index.to_series()
+
+        d[axis] = dindex
+        return d
+
+    @final
+    def _get_index_resolvers(self) -> dict[Hashable, Series | MultiIndex]:
+        from pandas.core.computation.parsing import clean_column_name
+
+        d: dict[str, Series | MultiIndex] = {}
+        for axis_name in self._AXIS_ORDERS:
+            d.update(self._get_axis_resolvers(axis_name))
+
+        return {clean_column_name(k): v for k, v in d.items() if not isinstance(k, int)}
+
+    @final
+    def _get_cleaned_column_resolvers(self) -> dict[Hashable, Series]:
+        """
+        Return the special character free column resolvers of a dataframe.
+
+        Column names with special characters are 'cleaned up' so that they can
+        be referred to by backtick quoting.
+        Used in :meth:`DataFrame.eval`.
+        """
+        from pandas.core.computation.parsing import clean_column_name
+        from pandas.core.series import Series
+
+        if isinstance(self, ABCSeries):
+            return {clean_column_name(self.name): self}
+
+        return {
+            clean_column_name(k): Series(
+                v, copy=False, index=self.index, name=k, dtype=self.dtypes[k]
+            ).__finalize__(self)
+            for k, v in zip(self.columns, self._iter_column_arrays())
+            if not isinstance(k, int)
+        }
+
+    @final
+    @property
+    def _info_axis(self) -> Index:
+        return getattr(self, self._info_axis_name)
+
+    def _is_view_after_cow_rules(self):
+        # Only to be used in cases of chained assignment checks, this is a
+        # simplified check that assumes that either the whole object is a view
+        # or a copy
+        if len(self._mgr.blocks) == 0:  # type: ignore[union-attr]
+            return False
+        return self._mgr.blocks[0].refs.has_reference()  # type: ignore[union-attr]
+
+    @property
+    def shape(self) -> tuple[int, ...]:
+        """
+        Return a tuple of axis dimensions
+        """
+        return tuple(len(self._get_axis(a)) for a in self._AXIS_ORDERS)
+
+    @property
+    def axes(self) -> list[Index]:
+        """
+        Return index label(s) of the internal NDFrame
+        """
+        # we do it this way because if we have reversed axes, then
+        # the block manager shows then reversed
+        return [self._get_axis(a) for a in self._AXIS_ORDERS]
+
+    @final
+    @property
+    def ndim(self) -> int:
+        """
+        Return an int representing the number of axes / array dimensions.
+
+        Return 1 if Series. Otherwise return 2 if DataFrame.
+
+        See Also
+        --------
+        ndarray.ndim : Number of array dimensions.
+
+        Examples
+        --------
+        >>> s = pd.Series({'a': 1, 'b': 2, 'c': 3})
+        >>> s.ndim
+        1
+
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df.ndim
+        2
+        """
+        return self._mgr.ndim
+
+    @final
+    @property
+    def size(self) -> int:
+        """
+        Return an int representing the number of elements in this object.
+
+        Return the number of rows if Series. Otherwise return the number of
+        rows times number of columns if DataFrame.
+
+        See Also
+        --------
+        ndarray.size : Number of elements in the array.
+
+        Examples
+        --------
+        >>> s = pd.Series({'a': 1, 'b': 2, 'c': 3})
+        >>> s.size
+        3
+
+        >>> df = pd.DataFrame({'col1': [1, 2], 'col2': [3, 4]})
+        >>> df.size
+        4
+        """
+
+        return int(np.prod(self.shape))
+
+    def set_axis(
+        self,
+        labels,
+        *,
+        axis: Axis = 0,
+        copy: bool_t | None = None,
+    ) -> Self:
+        """
+        Assign desired index to given axis.
+
+        Indexes for%(extended_summary_sub)s row labels can be changed by assigning
+        a list-like or Index.
+
+        Parameters
+        ----------
+        labels : list-like, Index
+            The values for the new index.
+
+        axis : %(axes_single_arg)s, default 0
+            The axis to update. The value 0 identifies the rows. For `Series`
+            this parameter is unused and defaults to 0.
+
+        copy : bool, default True
+            Whether to make a copy of the underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        %(klass)s
+            An object of type %(klass)s.
+
+        See Also
+        --------
+        %(klass)s.rename_axis : Alter the name of the index%(see_also_sub)s.
+        """
+        return self._set_axis_nocheck(labels, axis, inplace=False, copy=copy)
+
+    @final
+    def _set_axis_nocheck(
+        self, labels, axis: Axis, inplace: bool_t, copy: bool_t | None
+    ):
+        if inplace:
+            setattr(self, self._get_axis_name(axis), labels)
+        else:
+            # With copy=False, we create a new object but don't copy the
+            #  underlying data.
+            obj = self.copy(deep=copy and not using_copy_on_write())
+            setattr(obj, obj._get_axis_name(axis), labels)
+            return obj
+
+    @final
+    def _set_axis(self, axis: AxisInt, labels: AnyArrayLike | list) -> None:
+        """
+        This is called from the cython code when we set the `index` attribute
+        directly, e.g. `series.index = [1, 2, 3]`.
+        """
+        labels = ensure_index(labels)
+        self._mgr.set_axis(axis, labels)
+        self._clear_item_cache()
+
+    @final
+    def swapaxes(self, axis1: Axis, axis2: Axis, copy: bool_t | None = None) -> Self:
+        """
+        Interchange axes and swap values axes appropriately.
+
+        .. deprecated:: 2.1.0
+            ``swapaxes`` is deprecated and will be removed.
+            Please use ``transpose`` instead.
+
+        Returns
+        -------
+        same as input
+
+        Examples
+        --------
+        Please see examples for :meth:`DataFrame.transpose`.
+        """
+        warnings.warn(
+            # GH#51946
+            f"'{type(self).__name__}.swapaxes' is deprecated and "
+            "will be removed in a future version. "
+            f"Please use '{type(self).__name__}.transpose' instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        i = self._get_axis_number(axis1)
+        j = self._get_axis_number(axis2)
+
+        if i == j:
+            return self.copy(deep=copy and not using_copy_on_write())
+
+        mapping = {i: j, j: i}
+
+        new_axes = [self._get_axis(mapping.get(k, k)) for k in range(self._AXIS_LEN)]
+        new_values = self._values.swapaxes(i, j)  # type: ignore[union-attr]
+        if self._mgr.is_single_block and isinstance(self._mgr, BlockManager):
+            # This should only get hit in case of having a single block, otherwise a
+            # copy is made, we don't have to set up references.
+            new_mgr = ndarray_to_mgr(
+                new_values,
+                new_axes[0],
+                new_axes[1],
+                dtype=None,
+                copy=False,
+                typ="block",
+            )
+            assert isinstance(new_mgr, BlockManager)
+            assert isinstance(self._mgr, BlockManager)
+            new_mgr.blocks[0].refs = self._mgr.blocks[0].refs
+            new_mgr.blocks[0].refs.add_reference(new_mgr.blocks[0])
+            if not using_copy_on_write() and copy is not False:
+                new_mgr = new_mgr.copy(deep=True)
+
+            out = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+            return out.__finalize__(self, method="swapaxes")
+
+        return self._constructor(
+            new_values,
+            *new_axes,
+            # The no-copy case for CoW is handled above
+            copy=False,
+        ).__finalize__(self, method="swapaxes")
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def droplevel(self, level: IndexLabel, axis: Axis = 0) -> Self:
+        """
+        Return {klass} with requested index / column level(s) removed.
+
+        Parameters
+        ----------
+        level : int, str, or list-like
+            If a string is given, must be the name of a level
+            If list-like, elements must be names or positional indexes
+            of levels.
+
+        axis : {{0 or 'index', 1 or 'columns'}}, default 0
+            Axis along which the level(s) is removed:
+
+            * 0 or 'index': remove level(s) in column.
+            * 1 or 'columns': remove level(s) in row.
+
+            For `Series` this parameter is unused and defaults to 0.
+
+        Returns
+        -------
+        {klass}
+            {klass} with requested index / column level(s) removed.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([
+        ...     [1, 2, 3, 4],
+        ...     [5, 6, 7, 8],
+        ...     [9, 10, 11, 12]
+        ... ]).set_index([0, 1]).rename_axis(['a', 'b'])
+
+        >>> df.columns = pd.MultiIndex.from_tuples([
+        ...     ('c', 'e'), ('d', 'f')
+        ... ], names=['level_1', 'level_2'])
+
+        >>> df
+        level_1   c   d
+        level_2   e   f
+        a b
+        1 2      3   4
+        5 6      7   8
+        9 10    11  12
+
+        >>> df.droplevel('a')
+        level_1   c   d
+        level_2   e   f
+        b
+        2        3   4
+        6        7   8
+        10      11  12
+
+        >>> df.droplevel('level_2', axis=1)
+        level_1   c   d
+        a b
+        1 2      3   4
+        5 6      7   8
+        9 10    11  12
+        """
+        labels = self._get_axis(axis)
+        new_labels = labels.droplevel(level)
+        return self.set_axis(new_labels, axis=axis, copy=None)
+
+    def pop(self, item: Hashable) -> Series | Any:
+        result = self[item]
+        del self[item]
+
+        return result
+
+    @final
+    def squeeze(self, axis: Axis | None = None):
+        """
+        Squeeze 1 dimensional axis objects into scalars.
+
+        Series or DataFrames with a single element are squeezed to a scalar.
+        DataFrames with a single column or a single row are squeezed to a
+        Series. Otherwise the object is unchanged.
+
+        This method is most useful when you don't know if your
+        object is a Series or DataFrame, but you do know it has just a single
+        column. In that case you can safely call `squeeze` to ensure you have a
+        Series.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns', None}, default None
+            A specific axis to squeeze. By default, all length-1 axes are
+            squeezed. For `Series` this parameter is unused and defaults to `None`.
+
+        Returns
+        -------
+        DataFrame, Series, or scalar
+            The projection after squeezing `axis` or all the axes.
+
+        See Also
+        --------
+        Series.iloc : Integer-location based indexing for selecting scalars.
+        DataFrame.iloc : Integer-location based indexing for selecting Series.
+        Series.to_frame : Inverse of DataFrame.squeeze for a
+            single-column DataFrame.
+
+        Examples
+        --------
+        >>> primes = pd.Series([2, 3, 5, 7])
+
+        Slicing might produce a Series with a single value:
+
+        >>> even_primes = primes[primes % 2 == 0]
+        >>> even_primes
+        0    2
+        dtype: int64
+
+        >>> even_primes.squeeze()
+        2
+
+        Squeezing objects with more than one value in every axis does nothing:
+
+        >>> odd_primes = primes[primes % 2 == 1]
+        >>> odd_primes
+        1    3
+        2    5
+        3    7
+        dtype: int64
+
+        >>> odd_primes.squeeze()
+        1    3
+        2    5
+        3    7
+        dtype: int64
+
+        Squeezing is even more effective when used with DataFrames.
+
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['a', 'b'])
+        >>> df
+           a  b
+        0  1  2
+        1  3  4
+
+        Slicing a single column will produce a DataFrame with the columns
+        having only one value:
+
+        >>> df_a = df[['a']]
+        >>> df_a
+           a
+        0  1
+        1  3
+
+        So the columns can be squeezed down, resulting in a Series:
+
+        >>> df_a.squeeze('columns')
+        0    1
+        1    3
+        Name: a, dtype: int64
+
+        Slicing a single row from a single column will produce a single
+        scalar DataFrame:
+
+        >>> df_0a = df.loc[df.index < 1, ['a']]
+        >>> df_0a
+           a
+        0  1
+
+        Squeezing the rows produces a single scalar Series:
+
+        >>> df_0a.squeeze('rows')
+        a    1
+        Name: 0, dtype: int64
+
+        Squeezing all axes will project directly into a scalar:
+
+        >>> df_0a.squeeze()
+        1
+        """
+        axes = range(self._AXIS_LEN) if axis is None else (self._get_axis_number(axis),)
+        result = self.iloc[
+            tuple(
+                0 if i in axes and len(a) == 1 else slice(None)
+                for i, a in enumerate(self.axes)
+            )
+        ]
+        if isinstance(result, NDFrame):
+            result = result.__finalize__(self, method="squeeze")
+        return result
+
+    # ----------------------------------------------------------------------
+    # Rename
+
+    @final
+    def _rename(
+        self,
+        mapper: Renamer | None = None,
+        *,
+        index: Renamer | None = None,
+        columns: Renamer | None = None,
+        axis: Axis | None = None,
+        copy: bool_t | None = None,
+        inplace: bool_t = False,
+        level: Level | None = None,
+        errors: str = "ignore",
+    ) -> Self | None:
+        # called by Series.rename and DataFrame.rename
+
+        if mapper is None and index is None and columns is None:
+            raise TypeError("must pass an index to rename")
+
+        if index is not None or columns is not None:
+            if axis is not None:
+                raise TypeError(
+                    "Cannot specify both 'axis' and any of 'index' or 'columns'"
+                )
+            if mapper is not None:
+                raise TypeError(
+                    "Cannot specify both 'mapper' and any of 'index' or 'columns'"
+                )
+        else:
+            # use the mapper argument
+            if axis and self._get_axis_number(axis) == 1:
+                columns = mapper
+            else:
+                index = mapper
+
+        self._check_inplace_and_allows_duplicate_labels(inplace)
+        result = self if inplace else self.copy(deep=copy and not using_copy_on_write())
+
+        for axis_no, replacements in enumerate((index, columns)):
+            if replacements is None:
+                continue
+
+            ax = self._get_axis(axis_no)
+            f = common.get_rename_function(replacements)
+
+            if level is not None:
+                level = ax._get_level_number(level)
+
+            # GH 13473
+            if not callable(replacements):
+                if ax._is_multi and level is not None:
+                    indexer = ax.get_level_values(level).get_indexer_for(replacements)
+                else:
+                    indexer = ax.get_indexer_for(replacements)
+
+                if errors == "raise" and len(indexer[indexer == -1]):
+                    missing_labels = [
+                        label
+                        for index, label in enumerate(replacements)
+                        if indexer[index] == -1
+                    ]
+                    raise KeyError(f"{missing_labels} not found in axis")
+
+            new_index = ax._transform_index(f, level=level)
+            result._set_axis_nocheck(new_index, axis=axis_no, inplace=True, copy=False)
+            result._clear_item_cache()
+
+        if inplace:
+            self._update_inplace(result)
+            return None
+        else:
+            return result.__finalize__(self, method="rename")
+
+    @overload
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        columns=...,
+        axis: Axis = ...,
+        copy: bool_t | None = ...,
+        inplace: Literal[False] = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        columns=...,
+        axis: Axis = ...,
+        copy: bool_t | None = ...,
+        inplace: Literal[True],
+    ) -> None:
+        ...
+
+    @overload
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        columns=...,
+        axis: Axis = ...,
+        copy: bool_t | None = ...,
+        inplace: bool_t = ...,
+    ) -> Self | None:
+        ...
+
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = lib.no_default,
+        *,
+        index=lib.no_default,
+        columns=lib.no_default,
+        axis: Axis = 0,
+        copy: bool_t | None = None,
+        inplace: bool_t = False,
+    ) -> Self | None:
+        """
+        Set the name of the axis for the index or columns.
+
+        Parameters
+        ----------
+        mapper : scalar, list-like, optional
+            Value to set the axis name attribute.
+        index, columns : scalar, list-like, dict-like or function, optional
+            A scalar, list-like, dict-like or functions transformations to
+            apply to that axis' values.
+            Note that the ``columns`` parameter is not allowed if the
+            object is a Series. This parameter only apply for DataFrame
+            type objects.
+
+            Use either ``mapper`` and ``axis`` to
+            specify the axis to target with ``mapper``, or ``index``
+            and/or ``columns``.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to rename. For `Series` this parameter is unused and defaults to 0.
+        copy : bool, default None
+            Also copy underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        inplace : bool, default False
+            Modifies the object directly, instead of creating a new Series
+            or DataFrame.
+
+        Returns
+        -------
+        Series, DataFrame, or None
+            The same type as the caller or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.rename : Alter Series index labels or name.
+        DataFrame.rename : Alter DataFrame index labels or name.
+        Index.rename : Set new names on index.
+
+        Notes
+        -----
+        ``DataFrame.rename_axis`` supports two calling conventions
+
+        * ``(index=index_mapper, columns=columns_mapper, ...)``
+        * ``(mapper, axis={'index', 'columns'}, ...)``
+
+        The first calling convention will only modify the names of
+        the index and/or the names of the Index object that is the columns.
+        In this case, the parameter ``copy`` is ignored.
+
+        The second calling convention will modify the names of the
+        corresponding index if mapper is a list or a scalar.
+        However, if mapper is dict-like or a function, it will use the
+        deprecated behavior of modifying the axis *labels*.
+
+        We *highly* recommend using keyword arguments to clarify your
+        intent.
+
+        Examples
+        --------
+        **Series**
+
+        >>> s = pd.Series(["dog", "cat", "monkey"])
+        >>> s
+        0       dog
+        1       cat
+        2    monkey
+        dtype: object
+        >>> s.rename_axis("animal")
+        animal
+        0    dog
+        1    cat
+        2    monkey
+        dtype: object
+
+        **DataFrame**
+
+        >>> df = pd.DataFrame({"num_legs": [4, 4, 2],
+        ...                    "num_arms": [0, 0, 2]},
+        ...                   ["dog", "cat", "monkey"])
+        >>> df
+                num_legs  num_arms
+        dog            4         0
+        cat            4         0
+        monkey         2         2
+        >>> df = df.rename_axis("animal")
+        >>> df
+                num_legs  num_arms
+        animal
+        dog            4         0
+        cat            4         0
+        monkey         2         2
+        >>> df = df.rename_axis("limbs", axis="columns")
+        >>> df
+        limbs   num_legs  num_arms
+        animal
+        dog            4         0
+        cat            4         0
+        monkey         2         2
+
+        **MultiIndex**
+
+        >>> df.index = pd.MultiIndex.from_product([['mammal'],
+        ...                                        ['dog', 'cat', 'monkey']],
+        ...                                       names=['type', 'name'])
+        >>> df
+        limbs          num_legs  num_arms
+        type   name
+        mammal dog            4         0
+               cat            4         0
+               monkey         2         2
+
+        >>> df.rename_axis(index={'type': 'class'})
+        limbs          num_legs  num_arms
+        class  name
+        mammal dog            4         0
+               cat            4         0
+               monkey         2         2
+
+        >>> df.rename_axis(columns=str.upper)
+        LIMBS          num_legs  num_arms
+        type   name
+        mammal dog            4         0
+               cat            4         0
+               monkey         2         2
+        """
+        axes = {"index": index, "columns": columns}
+
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if copy and using_copy_on_write():
+            copy = False
+
+        if mapper is not lib.no_default:
+            # Use v0.23 behavior if a scalar or list
+            non_mapper = is_scalar(mapper) or (
+                is_list_like(mapper) and not is_dict_like(mapper)
+            )
+            if non_mapper:
+                return self._set_axis_name(
+                    mapper, axis=axis, inplace=inplace, copy=copy
+                )
+            else:
+                raise ValueError("Use `.rename` to alter labels with a mapper.")
+        else:
+            # Use new behavior.  Means that index and/or columns
+            # is specified
+            result = self if inplace else self.copy(deep=copy)
+
+            for axis in range(self._AXIS_LEN):
+                v = axes.get(self._get_axis_name(axis))
+                if v is lib.no_default:
+                    continue
+                non_mapper = is_scalar(v) or (is_list_like(v) and not is_dict_like(v))
+                if non_mapper:
+                    newnames = v
+                else:
+                    f = common.get_rename_function(v)
+                    curnames = self._get_axis(axis).names
+                    newnames = [f(name) for name in curnames]
+                result._set_axis_name(newnames, axis=axis, inplace=True, copy=copy)
+            if not inplace:
+                return result
+            return None
+
+    @final
+    def _set_axis_name(
+        self, name, axis: Axis = 0, inplace: bool_t = False, copy: bool_t | None = True
+    ):
+        """
+        Set the name(s) of the axis.
+
+        Parameters
+        ----------
+        name : str or list of str
+            Name(s) to set.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            The axis to set the label. The value 0 or 'index' specifies index,
+            and the value 1 or 'columns' specifies columns.
+        inplace : bool, default False
+            If `True`, do operation inplace and return None.
+        copy:
+            Whether to make a copy of the result.
+
+        Returns
+        -------
+        Series, DataFrame, or None
+            The same type as the caller or `None` if `inplace` is `True`.
+
+        See Also
+        --------
+        DataFrame.rename : Alter the axis labels of :class:`DataFrame`.
+        Series.rename : Alter the index labels or set the index name
+            of :class:`Series`.
+        Index.rename : Set the name of :class:`Index` or :class:`MultiIndex`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"num_legs": [4, 4, 2]},
+        ...                   ["dog", "cat", "monkey"])
+        >>> df
+                num_legs
+        dog            4
+        cat            4
+        monkey         2
+        >>> df._set_axis_name("animal")
+                num_legs
+        animal
+        dog            4
+        cat            4
+        monkey         2
+        >>> df.index = pd.MultiIndex.from_product(
+        ...                [["mammal"], ['dog', 'cat', 'monkey']])
+        >>> df._set_axis_name(["type", "name"])
+                       num_legs
+        type   name
+        mammal dog        4
+               cat        4
+               monkey     2
+        """
+        axis = self._get_axis_number(axis)
+        idx = self._get_axis(axis).set_names(name)
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        renamed = self if inplace else self.copy(deep=copy)
+        if axis == 0:
+            renamed.index = idx
+        else:
+            renamed.columns = idx
+
+        if not inplace:
+            return renamed
+
+    # ----------------------------------------------------------------------
+    # Comparison Methods
+
+    @final
+    def _indexed_same(self, other) -> bool_t:
+        return all(
+            self._get_axis(a).equals(other._get_axis(a)) for a in self._AXIS_ORDERS
+        )
+
+    @final
+    def equals(self, other: object) -> bool_t:
+        """
+        Test whether two objects contain the same elements.
+
+        This function allows two Series or DataFrames to be compared against
+        each other to see if they have the same shape and elements. NaNs in
+        the same location are considered equal.
+
+        The row/column index do not need to have the same type, as long
+        as the values are considered equal. Corresponding columns and
+        index must be of the same dtype.
+
+        Parameters
+        ----------
+        other : Series or DataFrame
+            The other Series or DataFrame to be compared with the first.
+
+        Returns
+        -------
+        bool
+            True if all elements are the same in both objects, False
+            otherwise.
+
+        See Also
+        --------
+        Series.eq : Compare two Series objects of the same length
+            and return a Series where each element is True if the element
+            in each Series is equal, False otherwise.
+        DataFrame.eq : Compare two DataFrame objects of the same shape and
+            return a DataFrame where each element is True if the respective
+            element in each DataFrame is equal, False otherwise.
+        testing.assert_series_equal : Raises an AssertionError if left and
+            right are not equal. Provides an easy interface to ignore
+            inequality in dtypes, indexes and precision among others.
+        testing.assert_frame_equal : Like assert_series_equal, but targets
+            DataFrames.
+        numpy.array_equal : Return True if two arrays have the same shape
+            and elements, False otherwise.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({1: [10], 2: [20]})
+        >>> df
+            1   2
+        0  10  20
+
+        DataFrames df and exactly_equal have the same types and values for
+        their elements and column labels, which will return True.
+
+        >>> exactly_equal = pd.DataFrame({1: [10], 2: [20]})
+        >>> exactly_equal
+            1   2
+        0  10  20
+        >>> df.equals(exactly_equal)
+        True
+
+        DataFrames df and different_column_type have the same element
+        types and values, but have different types for the column labels,
+        which will still return True.
+
+        >>> different_column_type = pd.DataFrame({1.0: [10], 2.0: [20]})
+        >>> different_column_type
+           1.0  2.0
+        0   10   20
+        >>> df.equals(different_column_type)
+        True
+
+        DataFrames df and different_data_type have different types for the
+        same values for their elements, and will return False even though
+        their column labels are the same values and types.
+
+        >>> different_data_type = pd.DataFrame({1: [10.0], 2: [20.0]})
+        >>> different_data_type
+              1     2
+        0  10.0  20.0
+        >>> df.equals(different_data_type)
+        False
+        """
+        if not (isinstance(other, type(self)) or isinstance(self, type(other))):
+            return False
+        other = cast(NDFrame, other)
+        return self._mgr.equals(other._mgr)
+
+    # -------------------------------------------------------------------------
+    # Unary Methods
+
+    @final
+    def __neg__(self) -> Self:
+        def blk_func(values: ArrayLike):
+            if is_bool_dtype(values.dtype):
+                # error: Argument 1 to "inv" has incompatible type "Union
+                # [ExtensionArray, ndarray[Any, Any]]"; expected
+                # "_SupportsInversion[ndarray[Any, dtype[bool_]]]"
+                return operator.inv(values)  # type: ignore[arg-type]
+            else:
+                # error: Argument 1 to "neg" has incompatible type "Union
+                # [ExtensionArray, ndarray[Any, Any]]"; expected
+                # "_SupportsNeg[ndarray[Any, dtype[Any]]]"
+                return operator.neg(values)  # type: ignore[arg-type]
+
+        new_data = self._mgr.apply(blk_func)
+        res = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        return res.__finalize__(self, method="__neg__")
+
+    @final
+    def __pos__(self) -> Self:
+        def blk_func(values: ArrayLike):
+            if is_bool_dtype(values.dtype):
+                return values.copy()
+            else:
+                # error: Argument 1 to "pos" has incompatible type "Union
+                # [ExtensionArray, ndarray[Any, Any]]"; expected
+                # "_SupportsPos[ndarray[Any, dtype[Any]]]"
+                return operator.pos(values)  # type: ignore[arg-type]
+
+        new_data = self._mgr.apply(blk_func)
+        res = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        return res.__finalize__(self, method="__pos__")
+
+    @final
+    def __invert__(self) -> Self:
+        if not self.size:
+            # inv fails with 0 len
+            return self.copy(deep=False)
+
+        new_data = self._mgr.apply(operator.invert)
+        res = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        return res.__finalize__(self, method="__invert__")
+
+    @final
+    def __nonzero__(self) -> NoReturn:
+        raise ValueError(
+            f"The truth value of a {type(self).__name__} is ambiguous. "
+            "Use a.empty, a.bool(), a.item(), a.any() or a.all()."
+        )
+
+    __bool__ = __nonzero__
+
+    @final
+    def bool(self) -> bool_t:
+        """
+        Return the bool of a single element Series or DataFrame.
+
+        .. deprecated:: 2.1.0
+
+           bool is deprecated and will be removed in future version of pandas.
+           For ``Series`` use ``pandas.Series.item``.
+
+        This must be a boolean scalar value, either True or False. It will raise a
+        ValueError if the Series or DataFrame does not have exactly 1 element, or that
+        element is not boolean (integer values 0 and 1 will also raise an exception).
+
+        Returns
+        -------
+        bool
+            The value in the Series or DataFrame.
+
+        See Also
+        --------
+        Series.astype : Change the data type of a Series, including to boolean.
+        DataFrame.astype : Change the data type of a DataFrame, including to boolean.
+        numpy.bool_ : NumPy boolean data type, used by pandas for boolean values.
+
+        Examples
+        --------
+        The method will only work for single element objects with a boolean value:
+
+        >>> pd.Series([True]).bool()  # doctest: +SKIP
+        True
+        >>> pd.Series([False]).bool()  # doctest: +SKIP
+        False
+
+        >>> pd.DataFrame({'col': [True]}).bool()  # doctest: +SKIP
+        True
+        >>> pd.DataFrame({'col': [False]}).bool()  # doctest: +SKIP
+        False
+
+        This is an alternative method and will only work
+        for single element objects with a boolean value:
+
+        >>> pd.Series([True]).item()  # doctest: +SKIP
+        True
+        >>> pd.Series([False]).item()  # doctest: +SKIP
+        False
+        """
+
+        warnings.warn(
+            f"{type(self).__name__}.bool is now deprecated and will be removed "
+            "in future version of pandas",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        v = self.squeeze()
+        if isinstance(v, (bool, np.bool_)):
+            return bool(v)
+        elif is_scalar(v):
+            raise ValueError(
+                "bool cannot act on a non-boolean single element "
+                f"{type(self).__name__}"
+            )
+
+        self.__nonzero__()
+        # for mypy (__nonzero__ raises)
+        return True
+
+    @final
+    def abs(self) -> Self:
+        """
+        Return a Series/DataFrame with absolute numeric value of each element.
+
+        This function only applies to elements that are all numeric.
+
+        Returns
+        -------
+        abs
+            Series/DataFrame containing the absolute value of each element.
+
+        See Also
+        --------
+        numpy.absolute : Calculate the absolute value element-wise.
+
+        Notes
+        -----
+        For ``complex`` inputs, ``1.2 + 1j``, the absolute value is
+        :math:`\\sqrt{ a^2 + b^2 }`.
+
+        Examples
+        --------
+        Absolute numeric values in a Series.
+
+        >>> s = pd.Series([-1.10, 2, -3.33, 4])
+        >>> s.abs()
+        0    1.10
+        1    2.00
+        2    3.33
+        3    4.00
+        dtype: float64
+
+        Absolute numeric values in a Series with complex numbers.
+
+        >>> s = pd.Series([1.2 + 1j])
+        >>> s.abs()
+        0    1.56205
+        dtype: float64
+
+        Absolute numeric values in a Series with a Timedelta element.
+
+        >>> s = pd.Series([pd.Timedelta('1 days')])
+        >>> s.abs()
+        0   1 days
+        dtype: timedelta64[ns]
+
+        Select rows with data closest to certain value using argsort (from
+        `StackOverflow `__).
+
+        >>> df = pd.DataFrame({
+        ...     'a': [4, 5, 6, 7],
+        ...     'b': [10, 20, 30, 40],
+        ...     'c': [100, 50, -30, -50]
+        ... })
+        >>> df
+             a    b    c
+        0    4   10  100
+        1    5   20   50
+        2    6   30  -30
+        3    7   40  -50
+        >>> df.loc[(df.c - 43).abs().argsort()]
+             a    b    c
+        1    5   20   50
+        0    4   10  100
+        2    6   30  -30
+        3    7   40  -50
+        """
+        res_mgr = self._mgr.apply(np.abs)
+        return self._constructor_from_mgr(res_mgr, axes=res_mgr.axes).__finalize__(
+            self, name="abs"
+        )
+
+    @final
+    def __abs__(self) -> Self:
+        return self.abs()
+
+    @final
+    def __round__(self, decimals: int = 0) -> Self:
+        return self.round(decimals).__finalize__(self, method="__round__")
+
+    # -------------------------------------------------------------------------
+    # Label or Level Combination Helpers
+    #
+    # A collection of helper methods for DataFrame/Series operations that
+    # accept a combination of column/index labels and levels.  All such
+    # operations should utilize/extend these methods when possible so that we
+    # have consistent precedence and validation logic throughout the library.
+
+    @final
+    def _is_level_reference(self, key: Level, axis: Axis = 0) -> bool_t:
+        """
+        Test whether a key is a level reference for a given axis.
+
+        To be considered a level reference, `key` must be a string that:
+          - (axis=0): Matches the name of an index level and does NOT match
+            a column label.
+          - (axis=1): Matches the name of a column level and does NOT match
+            an index label.
+
+        Parameters
+        ----------
+        key : Hashable
+            Potential level name for the given axis
+        axis : int, default 0
+            Axis that levels are associated with (0 for index, 1 for columns)
+
+        Returns
+        -------
+        is_level : bool
+        """
+        axis_int = self._get_axis_number(axis)
+
+        return (
+            key is not None
+            and is_hashable(key)
+            and key in self.axes[axis_int].names
+            and not self._is_label_reference(key, axis=axis_int)
+        )
+
+    @final
+    def _is_label_reference(self, key: Level, axis: Axis = 0) -> bool_t:
+        """
+        Test whether a key is a label reference for a given axis.
+
+        To be considered a label reference, `key` must be a string that:
+          - (axis=0): Matches a column label
+          - (axis=1): Matches an index label
+
+        Parameters
+        ----------
+        key : Hashable
+            Potential label name, i.e. Index entry.
+        axis : int, default 0
+            Axis perpendicular to the axis that labels are associated with
+            (0 means search for column labels, 1 means search for index labels)
+
+        Returns
+        -------
+        is_label: bool
+        """
+        axis_int = self._get_axis_number(axis)
+        other_axes = (ax for ax in range(self._AXIS_LEN) if ax != axis_int)
+
+        return (
+            key is not None
+            and is_hashable(key)
+            and any(key in self.axes[ax] for ax in other_axes)
+        )
+
+    @final
+    def _is_label_or_level_reference(self, key: Level, axis: AxisInt = 0) -> bool_t:
+        """
+        Test whether a key is a label or level reference for a given axis.
+
+        To be considered either a label or a level reference, `key` must be a
+        string that:
+          - (axis=0): Matches a column label or an index level
+          - (axis=1): Matches an index label or a column level
+
+        Parameters
+        ----------
+        key : Hashable
+            Potential label or level name
+        axis : int, default 0
+            Axis that levels are associated with (0 for index, 1 for columns)
+
+        Returns
+        -------
+        bool
+        """
+        return self._is_level_reference(key, axis=axis) or self._is_label_reference(
+            key, axis=axis
+        )
+
+    @final
+    def _check_label_or_level_ambiguity(self, key: Level, axis: Axis = 0) -> None:
+        """
+        Check whether `key` is ambiguous.
+
+        By ambiguous, we mean that it matches both a level of the input
+        `axis` and a label of the other axis.
+
+        Parameters
+        ----------
+        key : Hashable
+            Label or level name.
+        axis : int, default 0
+            Axis that levels are associated with (0 for index, 1 for columns).
+
+        Raises
+        ------
+        ValueError: `key` is ambiguous
+        """
+
+        axis_int = self._get_axis_number(axis)
+        other_axes = (ax for ax in range(self._AXIS_LEN) if ax != axis_int)
+
+        if (
+            key is not None
+            and is_hashable(key)
+            and key in self.axes[axis_int].names
+            and any(key in self.axes[ax] for ax in other_axes)
+        ):
+            # Build an informative and grammatical warning
+            level_article, level_type = (
+                ("an", "index") if axis_int == 0 else ("a", "column")
+            )
+
+            label_article, label_type = (
+                ("a", "column") if axis_int == 0 else ("an", "index")
+            )
+
+            msg = (
+                f"'{key}' is both {level_article} {level_type} level and "
+                f"{label_article} {label_type} label, which is ambiguous."
+            )
+            raise ValueError(msg)
+
+    @final
+    def _get_label_or_level_values(self, key: Level, axis: AxisInt = 0) -> ArrayLike:
+        """
+        Return a 1-D array of values associated with `key`, a label or level
+        from the given `axis`.
+
+        Retrieval logic:
+          - (axis=0): Return column values if `key` matches a column label.
+            Otherwise return index level values if `key` matches an index
+            level.
+          - (axis=1): Return row values if `key` matches an index label.
+            Otherwise return column level values if 'key' matches a column
+            level
+
+        Parameters
+        ----------
+        key : Hashable
+            Label or level name.
+        axis : int, default 0
+            Axis that levels are associated with (0 for index, 1 for columns)
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+
+        Raises
+        ------
+        KeyError
+            if `key` matches neither a label nor a level
+        ValueError
+            if `key` matches multiple labels
+        """
+        axis = self._get_axis_number(axis)
+        other_axes = [ax for ax in range(self._AXIS_LEN) if ax != axis]
+
+        if self._is_label_reference(key, axis=axis):
+            self._check_label_or_level_ambiguity(key, axis=axis)
+            values = self.xs(key, axis=other_axes[0])._values
+        elif self._is_level_reference(key, axis=axis):
+            values = self.axes[axis].get_level_values(key)._values
+        else:
+            raise KeyError(key)
+
+        # Check for duplicates
+        if values.ndim > 1:
+            if other_axes and isinstance(self._get_axis(other_axes[0]), MultiIndex):
+                multi_message = (
+                    "\n"
+                    "For a multi-index, the label must be a "
+                    "tuple with elements corresponding to each level."
+                )
+            else:
+                multi_message = ""
+
+            label_axis_name = "column" if axis == 0 else "index"
+            raise ValueError(
+                f"The {label_axis_name} label '{key}' is not unique.{multi_message}"
+            )
+
+        return values
+
+    @final
+    def _drop_labels_or_levels(self, keys, axis: AxisInt = 0):
+        """
+        Drop labels and/or levels for the given `axis`.
+
+        For each key in `keys`:
+          - (axis=0): If key matches a column label then drop the column.
+            Otherwise if key matches an index level then drop the level.
+          - (axis=1): If key matches an index label then drop the row.
+            Otherwise if key matches a column level then drop the level.
+
+        Parameters
+        ----------
+        keys : str or list of str
+            labels or levels to drop
+        axis : int, default 0
+            Axis that levels are associated with (0 for index, 1 for columns)
+
+        Returns
+        -------
+        dropped: DataFrame
+
+        Raises
+        ------
+        ValueError
+            if any `keys` match neither a label nor a level
+        """
+        axis = self._get_axis_number(axis)
+
+        # Validate keys
+        keys = common.maybe_make_list(keys)
+        invalid_keys = [
+            k for k in keys if not self._is_label_or_level_reference(k, axis=axis)
+        ]
+
+        if invalid_keys:
+            raise ValueError(
+                "The following keys are not valid labels or "
+                f"levels for axis {axis}: {invalid_keys}"
+            )
+
+        # Compute levels and labels to drop
+        levels_to_drop = [k for k in keys if self._is_level_reference(k, axis=axis)]
+
+        labels_to_drop = [k for k in keys if not self._is_level_reference(k, axis=axis)]
+
+        # Perform copy upfront and then use inplace operations below.
+        # This ensures that we always perform exactly one copy.
+        # ``copy`` and/or ``inplace`` options could be added in the future.
+        dropped = self.copy(deep=False)
+
+        if axis == 0:
+            # Handle dropping index levels
+            if levels_to_drop:
+                dropped.reset_index(levels_to_drop, drop=True, inplace=True)
+
+            # Handle dropping columns labels
+            if labels_to_drop:
+                dropped.drop(labels_to_drop, axis=1, inplace=True)
+        else:
+            # Handle dropping column levels
+            if levels_to_drop:
+                if isinstance(dropped.columns, MultiIndex):
+                    # Drop the specified levels from the MultiIndex
+                    dropped.columns = dropped.columns.droplevel(levels_to_drop)
+                else:
+                    # Drop the last level of Index by replacing with
+                    # a RangeIndex
+                    dropped.columns = RangeIndex(dropped.columns.size)
+
+            # Handle dropping index labels
+            if labels_to_drop:
+                dropped.drop(labels_to_drop, axis=0, inplace=True)
+
+        return dropped
+
+    # ----------------------------------------------------------------------
+    # Iteration
+
+    # https://github.com/python/typeshed/issues/2148#issuecomment-520783318
+    # Incompatible types in assignment (expression has type "None", base class
+    # "object" defined the type as "Callable[[object], int]")
+    __hash__: ClassVar[None]  # type: ignore[assignment]
+
+    def __iter__(self) -> Iterator:
+        """
+        Iterate over info axis.
+
+        Returns
+        -------
+        iterator
+            Info axis as iterator.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]})
+        >>> for x in df:
+        ...     print(x)
+        A
+        B
+        """
+        return iter(self._info_axis)
+
+    # can we get a better explanation of this?
+    def keys(self) -> Index:
+        """
+        Get the 'info axis' (see Indexing for more).
+
+        This is index for Series, columns for DataFrame.
+
+        Returns
+        -------
+        Index
+            Info axis.
+
+        Examples
+        --------
+        >>> d = pd.DataFrame(data={'A': [1, 2, 3], 'B': [0, 4, 8]},
+        ...                  index=['a', 'b', 'c'])
+        >>> d
+           A  B
+        a  1  0
+        b  2  4
+        c  3  8
+        >>> d.keys()
+        Index(['A', 'B'], dtype='object')
+        """
+        return self._info_axis
+
+    def items(self):
+        """
+        Iterate over (label, values) on info axis
+
+        This is index for Series and columns for DataFrame.
+
+        Returns
+        -------
+        Generator
+        """
+        for h in self._info_axis:
+            yield h, self[h]
+
+    def __len__(self) -> int:
+        """Returns length of info axis"""
+        return len(self._info_axis)
+
+    @final
+    def __contains__(self, key) -> bool_t:
+        """True if the key is in the info axis"""
+        return key in self._info_axis
+
+    @property
+    def empty(self) -> bool_t:
+        """
+        Indicator whether Series/DataFrame is empty.
+
+        True if Series/DataFrame is entirely empty (no items), meaning any of the
+        axes are of length 0.
+
+        Returns
+        -------
+        bool
+            If Series/DataFrame is empty, return True, if not return False.
+
+        See Also
+        --------
+        Series.dropna : Return series without null values.
+        DataFrame.dropna : Return DataFrame with labels on given axis omitted
+            where (all or any) data are missing.
+
+        Notes
+        -----
+        If Series/DataFrame contains only NaNs, it is still not considered empty. See
+        the example below.
+
+        Examples
+        --------
+        An example of an actual empty DataFrame. Notice the index is empty:
+
+        >>> df_empty = pd.DataFrame({'A' : []})
+        >>> df_empty
+        Empty DataFrame
+        Columns: [A]
+        Index: []
+        >>> df_empty.empty
+        True
+
+        If we only have NaNs in our DataFrame, it is not considered empty! We
+        will need to drop the NaNs to make the DataFrame empty:
+
+        >>> df = pd.DataFrame({'A' : [np.nan]})
+        >>> df
+            A
+        0 NaN
+        >>> df.empty
+        False
+        >>> df.dropna().empty
+        True
+
+        >>> ser_empty = pd.Series({'A' : []})
+        >>> ser_empty
+        A    []
+        dtype: object
+        >>> ser_empty.empty
+        False
+        >>> ser_empty = pd.Series()
+        >>> ser_empty.empty
+        True
+        """
+        return any(len(self._get_axis(a)) == 0 for a in self._AXIS_ORDERS)
+
+    # ----------------------------------------------------------------------
+    # Array Interface
+
+    # This is also set in IndexOpsMixin
+    # GH#23114 Ensure ndarray.__op__(DataFrame) returns NotImplemented
+    __array_priority__: int = 1000
+
+    def __array__(
+        self, dtype: npt.DTypeLike | None = None, copy: bool_t | None = None
+    ) -> np.ndarray:
+        if copy is False and not self._mgr.is_single_block and not self.empty:
+            # check this manually, otherwise ._values will already return a copy
+            # and np.array(values, copy=False) will not raise a warning
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        values = self._values
+        if copy is None:
+            # Note: branch avoids `copy=None` for NumPy 1.x support
+            arr = np.asarray(values, dtype=dtype)
+        else:
+            arr = np.array(values, dtype=dtype, copy=copy)
+
+        if (
+            copy is not True
+            and astype_is_view(values.dtype, arr.dtype)
+            and using_copy_on_write()
+            and self._mgr.is_single_block
+        ):
+            # Check if both conversions can be done without a copy
+            if astype_is_view(self.dtypes.iloc[0], values.dtype) and astype_is_view(
+                values.dtype, arr.dtype
+            ):
+                arr = arr.view()
+                arr.flags.writeable = False
+        return arr
+
+    @final
+    def __array_ufunc__(
+        self, ufunc: np.ufunc, method: str, *inputs: Any, **kwargs: Any
+    ):
+        return arraylike.array_ufunc(self, ufunc, method, *inputs, **kwargs)
+
+    # ----------------------------------------------------------------------
+    # Picklability
+
+    @final
+    def __getstate__(self) -> dict[str, Any]:
+        meta = {k: getattr(self, k, None) for k in self._metadata}
+        return {
+            "_mgr": self._mgr,
+            "_typ": self._typ,
+            "_metadata": self._metadata,
+            "attrs": self.attrs,
+            "_flags": {k: self.flags[k] for k in self.flags._keys},
+            **meta,
+        }
+
+    @final
+    def __setstate__(self, state) -> None:
+        if isinstance(state, BlockManager):
+            self._mgr = state
+        elif isinstance(state, dict):
+            if "_data" in state and "_mgr" not in state:
+                # compat for older pickles
+                state["_mgr"] = state.pop("_data")
+            typ = state.get("_typ")
+            if typ is not None:
+                attrs = state.get("_attrs", {})
+                if attrs is None:  # should not happen, but better be on the safe side
+                    attrs = {}
+                object.__setattr__(self, "_attrs", attrs)
+                flags = state.get("_flags", {"allows_duplicate_labels": True})
+                object.__setattr__(self, "_flags", Flags(self, **flags))
+
+                # set in the order of internal names
+                # to avoid definitional recursion
+                # e.g. say fill_value needing _mgr to be
+                # defined
+                meta = set(self._internal_names + self._metadata)
+                for k in list(meta):
+                    if k in state and k != "_flags":
+                        v = state[k]
+                        object.__setattr__(self, k, v)
+
+                for k, v in state.items():
+                    if k not in meta:
+                        object.__setattr__(self, k, v)
+
+            else:
+                raise NotImplementedError("Pre-0.12 pickles are no longer supported")
+        elif len(state) == 2:
+            raise NotImplementedError("Pre-0.12 pickles are no longer supported")
+
+        self._item_cache: dict[Hashable, Series] = {}
+
+    # ----------------------------------------------------------------------
+    # Rendering Methods
+
+    def __repr__(self) -> str:
+        # string representation based upon iterating over self
+        # (since, by definition, `PandasContainers` are iterable)
+        prepr = f"[{','.join(map(pprint_thing, self))}]"
+        return f"{type(self).__name__}({prepr})"
+
+    @final
+    def _repr_latex_(self):
+        """
+        Returns a LaTeX representation for a particular object.
+        Mainly for use with nbconvert (jupyter notebook conversion to pdf).
+        """
+        if config.get_option("styler.render.repr") == "latex":
+            return self.to_latex()
+        else:
+            return None
+
+    @final
+    def _repr_data_resource_(self):
+        """
+        Not a real Jupyter special repr method, but we use the same
+        naming convention.
+        """
+        if config.get_option("display.html.table_schema"):
+            data = self.head(config.get_option("display.max_rows"))
+
+            as_json = data.to_json(orient="table")
+            as_json = cast(str, as_json)
+            return loads(as_json, object_pairs_hook=collections.OrderedDict)
+
+    # ----------------------------------------------------------------------
+    # I/O Methods
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "excel_writer"], name="to_excel"
+    )
+    @doc(
+        klass="object",
+        storage_options=_shared_docs["storage_options"],
+        storage_options_versionadded="1.2.0",
+    )
+    def to_excel(
+        self,
+        excel_writer: FilePath | WriteExcelBuffer | ExcelWriter,
+        sheet_name: str = "Sheet1",
+        na_rep: str = "",
+        float_format: str | None = None,
+        columns: Sequence[Hashable] | None = None,
+        header: Sequence[Hashable] | bool_t = True,
+        index: bool_t = True,
+        index_label: IndexLabel | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        engine: Literal["openpyxl", "xlsxwriter"] | None = None,
+        merge_cells: bool_t = True,
+        inf_rep: str = "inf",
+        freeze_panes: tuple[int, int] | None = None,
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        """
+        Write {klass} to an Excel sheet.
+
+        To write a single {klass} to an Excel .xlsx file it is only necessary to
+        specify a target file name. To write to multiple sheets it is necessary to
+        create an `ExcelWriter` object with a target file name, and specify a sheet
+        in the file to write to.
+
+        Multiple sheets may be written to by specifying unique `sheet_name`.
+        With all data written to the file it is necessary to save the changes.
+        Note that creating an `ExcelWriter` object with a file name that already
+        exists will result in the contents of the existing file being erased.
+
+        Parameters
+        ----------
+        excel_writer : path-like, file-like, or ExcelWriter object
+            File path or existing ExcelWriter.
+        sheet_name : str, default 'Sheet1'
+            Name of sheet which will contain DataFrame.
+        na_rep : str, default ''
+            Missing data representation.
+        float_format : str, optional
+            Format string for floating point numbers. For example
+            ``float_format="%.2f"`` will format 0.1234 to 0.12.
+        columns : sequence or list of str, optional
+            Columns to write.
+        header : bool or list of str, default True
+            Write out the column names. If a list of string is given it is
+            assumed to be aliases for the column names.
+        index : bool, default True
+            Write row names (index).
+        index_label : str or sequence, optional
+            Column label for index column(s) if desired. If not specified, and
+            `header` and `index` are True, then the index names are used. A
+            sequence should be given if the DataFrame uses MultiIndex.
+        startrow : int, default 0
+            Upper left cell row to dump data frame.
+        startcol : int, default 0
+            Upper left cell column to dump data frame.
+        engine : str, optional
+            Write engine to use, 'openpyxl' or 'xlsxwriter'. You can also set this
+            via the options ``io.excel.xlsx.writer`` or
+            ``io.excel.xlsm.writer``.
+
+        merge_cells : bool, default True
+            Write MultiIndex and Hierarchical Rows as merged cells.
+        inf_rep : str, default 'inf'
+            Representation for infinity (there is no native representation for
+            infinity in Excel).
+        freeze_panes : tuple of int (length 2), optional
+            Specifies the one-based bottommost row and rightmost column that
+            is to be frozen.
+        {storage_options}
+
+            .. versionadded:: {storage_options_versionadded}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+
+        See Also
+        --------
+        to_csv : Write DataFrame to a comma-separated values (csv) file.
+        ExcelWriter : Class for writing DataFrame objects into excel sheets.
+        read_excel : Read an Excel file into a pandas DataFrame.
+        read_csv : Read a comma-separated values (csv) file into DataFrame.
+        io.formats.style.Styler.to_excel : Add styles to Excel sheet.
+
+        Notes
+        -----
+        For compatibility with :meth:`~DataFrame.to_csv`,
+        to_excel serializes lists and dicts to strings before writing.
+
+        Once a workbook has been saved it is not possible to write further
+        data without rewriting the whole workbook.
+
+        Examples
+        --------
+
+        Create, write to and save a workbook:
+
+        >>> df1 = pd.DataFrame([['a', 'b'], ['c', 'd']],
+        ...                    index=['row 1', 'row 2'],
+        ...                    columns=['col 1', 'col 2'])
+        >>> df1.to_excel("output.xlsx")  # doctest: +SKIP
+
+        To specify the sheet name:
+
+        >>> df1.to_excel("output.xlsx",
+        ...              sheet_name='Sheet_name_1')  # doctest: +SKIP
+
+        If you wish to write to more than one sheet in the workbook, it is
+        necessary to specify an ExcelWriter object:
+
+        >>> df2 = df1.copy()
+        >>> with pd.ExcelWriter('output.xlsx') as writer:  # doctest: +SKIP
+        ...     df1.to_excel(writer, sheet_name='Sheet_name_1')
+        ...     df2.to_excel(writer, sheet_name='Sheet_name_2')
+
+        ExcelWriter can also be used to append to an existing Excel file:
+
+        >>> with pd.ExcelWriter('output.xlsx',
+        ...                     mode='a') as writer:  # doctest: +SKIP
+        ...     df1.to_excel(writer, sheet_name='Sheet_name_3')
+
+        To set the library that is used to write the Excel file,
+        you can pass the `engine` keyword (the default engine is
+        automatically chosen depending on the file extension):
+
+        >>> df1.to_excel('output1.xlsx', engine='xlsxwriter')  # doctest: +SKIP
+        """
+        if engine_kwargs is None:
+            engine_kwargs = {}
+
+        df = self if isinstance(self, ABCDataFrame) else self.to_frame()
+
+        from pandas.io.formats.excel import ExcelFormatter
+
+        formatter = ExcelFormatter(
+            df,
+            na_rep=na_rep,
+            cols=columns,
+            header=header,
+            float_format=float_format,
+            index=index,
+            index_label=index_label,
+            merge_cells=merge_cells,
+            inf_rep=inf_rep,
+        )
+        formatter.write(
+            excel_writer,
+            sheet_name=sheet_name,
+            startrow=startrow,
+            startcol=startcol,
+            freeze_panes=freeze_panes,
+            engine=engine,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path_or_buf"], name="to_json"
+    )
+    @doc(
+        storage_options=_shared_docs["storage_options"],
+        compression_options=_shared_docs["compression_options"] % "path_or_buf",
+    )
+    def to_json(
+        self,
+        path_or_buf: FilePath | WriteBuffer[bytes] | WriteBuffer[str] | None = None,
+        orient: Literal["split", "records", "index", "table", "columns", "values"]
+        | None = None,
+        date_format: str | None = None,
+        double_precision: int = 10,
+        force_ascii: bool_t = True,
+        date_unit: TimeUnit = "ms",
+        default_handler: Callable[[Any], JSONSerializable] | None = None,
+        lines: bool_t = False,
+        compression: CompressionOptions = "infer",
+        index: bool_t | None = None,
+        indent: int | None = None,
+        storage_options: StorageOptions | None = None,
+        mode: Literal["a", "w"] = "w",
+    ) -> str | None:
+        """
+        Convert the object to a JSON string.
+
+        Note NaN's and None will be converted to null and datetime objects
+        will be converted to UNIX timestamps.
+
+        Parameters
+        ----------
+        path_or_buf : str, path object, file-like object, or None, default None
+            String, path object (implementing os.PathLike[str]), or file-like
+            object implementing a write() function. If None, the result is
+            returned as a string.
+        orient : str
+            Indication of expected JSON string format.
+
+            * Series:
+
+                - default is 'index'
+                - allowed values are: {{'split', 'records', 'index', 'table'}}.
+
+            * DataFrame:
+
+                - default is 'columns'
+                - allowed values are: {{'split', 'records', 'index', 'columns',
+                  'values', 'table'}}.
+
+            * The format of the JSON string:
+
+                - 'split' : dict like {{'index' -> [index], 'columns' -> [columns],
+                  'data' -> [values]}}
+                - 'records' : list like [{{column -> value}}, ... , {{column -> value}}]
+                - 'index' : dict like {{index -> {{column -> value}}}}
+                - 'columns' : dict like {{column -> {{index -> value}}}}
+                - 'values' : just the values array
+                - 'table' : dict like {{'schema': {{schema}}, 'data': {{data}}}}
+
+                Describing the data, where data component is like ``orient='records'``.
+
+        date_format : {{None, 'epoch', 'iso'}}
+            Type of date conversion. 'epoch' = epoch milliseconds,
+            'iso' = ISO8601. The default depends on the `orient`. For
+            ``orient='table'``, the default is 'iso'. For all other orients,
+            the default is 'epoch'.
+        double_precision : int, default 10
+            The number of decimal places to use when encoding
+            floating point values. The possible maximal value is 15.
+            Passing double_precision greater than 15 will raise a ValueError.
+        force_ascii : bool, default True
+            Force encoded string to be ASCII.
+        date_unit : str, default 'ms' (milliseconds)
+            The time unit to encode to, governs timestamp and ISO8601
+            precision.  One of 's', 'ms', 'us', 'ns' for second, millisecond,
+            microsecond, and nanosecond respectively.
+        default_handler : callable, default None
+            Handler to call if object cannot otherwise be converted to a
+            suitable format for JSON. Should receive a single argument which is
+            the object to convert and return a serialisable object.
+        lines : bool, default False
+            If 'orient' is 'records' write out line-delimited json format. Will
+            throw ValueError if incorrect 'orient' since others are not
+            list-like.
+        {compression_options}
+
+            .. versionchanged:: 1.4.0 Zstandard support.
+
+        index : bool or None, default None
+            The index is only used when 'orient' is 'split', 'index', 'column',
+            or 'table'. Of these, 'index' and 'column' do not support
+            `index=False`.
+
+        indent : int, optional
+           Length of whitespace used to indent each record.
+
+        {storage_options}
+
+        mode : str, default 'w' (writing)
+            Specify the IO mode for output when supplying a path_or_buf.
+            Accepted args are 'w' (writing) and 'a' (append) only.
+            mode='a' is only supported when lines is True and orient is 'records'.
+
+        Returns
+        -------
+        None or str
+            If path_or_buf is None, returns the resulting json format as a
+            string. Otherwise returns None.
+
+        See Also
+        --------
+        read_json : Convert a JSON string to pandas object.
+
+        Notes
+        -----
+        The behavior of ``indent=0`` varies from the stdlib, which does not
+        indent the output but does insert newlines. Currently, ``indent=0``
+        and the default ``indent=None`` are equivalent in pandas, though this
+        may change in a future release.
+
+        ``orient='table'`` contains a 'pandas_version' field under 'schema'.
+        This stores the version of `pandas` used in the latest revision of the
+        schema.
+
+        Examples
+        --------
+        >>> from json import loads, dumps
+        >>> df = pd.DataFrame(
+        ...     [["a", "b"], ["c", "d"]],
+        ...     index=["row 1", "row 2"],
+        ...     columns=["col 1", "col 2"],
+        ... )
+
+        >>> result = df.to_json(orient="split")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        {{
+            "columns": [
+                "col 1",
+                "col 2"
+            ],
+            "index": [
+                "row 1",
+                "row 2"
+            ],
+            "data": [
+                [
+                    "a",
+                    "b"
+                ],
+                [
+                    "c",
+                    "d"
+                ]
+            ]
+        }}
+
+        Encoding/decoding a Dataframe using ``'records'`` formatted JSON.
+        Note that index labels are not preserved with this encoding.
+
+        >>> result = df.to_json(orient="records")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        [
+            {{
+                "col 1": "a",
+                "col 2": "b"
+            }},
+            {{
+                "col 1": "c",
+                "col 2": "d"
+            }}
+        ]
+
+        Encoding/decoding a Dataframe using ``'index'`` formatted JSON:
+
+        >>> result = df.to_json(orient="index")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        {{
+            "row 1": {{
+                "col 1": "a",
+                "col 2": "b"
+            }},
+            "row 2": {{
+                "col 1": "c",
+                "col 2": "d"
+            }}
+        }}
+
+        Encoding/decoding a Dataframe using ``'columns'`` formatted JSON:
+
+        >>> result = df.to_json(orient="columns")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        {{
+            "col 1": {{
+                "row 1": "a",
+                "row 2": "c"
+            }},
+            "col 2": {{
+                "row 1": "b",
+                "row 2": "d"
+            }}
+        }}
+
+        Encoding/decoding a Dataframe using ``'values'`` formatted JSON:
+
+        >>> result = df.to_json(orient="values")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        [
+            [
+                "a",
+                "b"
+            ],
+            [
+                "c",
+                "d"
+            ]
+        ]
+
+        Encoding with Table Schema:
+
+        >>> result = df.to_json(orient="table")
+        >>> parsed = loads(result)
+        >>> dumps(parsed, indent=4)  # doctest: +SKIP
+        {{
+            "schema": {{
+                "fields": [
+                    {{
+                        "name": "index",
+                        "type": "string"
+                    }},
+                    {{
+                        "name": "col 1",
+                        "type": "string"
+                    }},
+                    {{
+                        "name": "col 2",
+                        "type": "string"
+                    }}
+                ],
+                "primaryKey": [
+                    "index"
+                ],
+                "pandas_version": "1.4.0"
+            }},
+            "data": [
+                {{
+                    "index": "row 1",
+                    "col 1": "a",
+                    "col 2": "b"
+                }},
+                {{
+                    "index": "row 2",
+                    "col 1": "c",
+                    "col 2": "d"
+                }}
+            ]
+        }}
+        """
+        from pandas.io import json
+
+        if date_format is None and orient == "table":
+            date_format = "iso"
+        elif date_format is None:
+            date_format = "epoch"
+
+        config.is_nonnegative_int(indent)
+        indent = indent or 0
+
+        return json.to_json(
+            path_or_buf=path_or_buf,
+            obj=self,
+            orient=orient,
+            date_format=date_format,
+            double_precision=double_precision,
+            force_ascii=force_ascii,
+            date_unit=date_unit,
+            default_handler=default_handler,
+            lines=lines,
+            compression=compression,
+            index=index,
+            indent=indent,
+            storage_options=storage_options,
+            mode=mode,
+        )
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path_or_buf"], name="to_hdf"
+    )
+    def to_hdf(
+        self,
+        path_or_buf: FilePath | HDFStore,
+        key: str,
+        mode: Literal["a", "w", "r+"] = "a",
+        complevel: int | None = None,
+        complib: Literal["zlib", "lzo", "bzip2", "blosc"] | None = None,
+        append: bool_t = False,
+        format: Literal["fixed", "table"] | None = None,
+        index: bool_t = True,
+        min_itemsize: int | dict[str, int] | None = None,
+        nan_rep=None,
+        dropna: bool_t | None = None,
+        data_columns: Literal[True] | list[str] | None = None,
+        errors: OpenFileErrors = "strict",
+        encoding: str = "UTF-8",
+    ) -> None:
+        """
+        Write the contained data to an HDF5 file using HDFStore.
+
+        Hierarchical Data Format (HDF) is self-describing, allowing an
+        application to interpret the structure and contents of a file with
+        no outside information. One HDF file can hold a mix of related objects
+        which can be accessed as a group or as individual objects.
+
+        In order to add another DataFrame or Series to an existing HDF file
+        please use append mode and a different a key.
+
+        .. warning::
+
+           One can store a subclass of ``DataFrame`` or ``Series`` to HDF5,
+           but the type of the subclass is lost upon storing.
+
+        For more information see the :ref:`user guide `.
+
+        Parameters
+        ----------
+        path_or_buf : str or pandas.HDFStore
+            File path or HDFStore object.
+        key : str
+            Identifier for the group in the store.
+        mode : {'a', 'w', 'r+'}, default 'a'
+            Mode to open file:
+
+            - 'w': write, a new file is created (an existing file with
+              the same name would be deleted).
+            - 'a': append, an existing file is opened for reading and
+              writing, and if the file does not exist it is created.
+            - 'r+': similar to 'a', but the file must already exist.
+        complevel : {0-9}, default None
+            Specifies a compression level for data.
+            A value of 0 or None disables compression.
+        complib : {'zlib', 'lzo', 'bzip2', 'blosc'}, default 'zlib'
+            Specifies the compression library to be used.
+            These additional compressors for Blosc are supported
+            (default if no compressor specified: 'blosc:blosclz'):
+            {'blosc:blosclz', 'blosc:lz4', 'blosc:lz4hc', 'blosc:snappy',
+            'blosc:zlib', 'blosc:zstd'}.
+            Specifying a compression library which is not available issues
+            a ValueError.
+        append : bool, default False
+            For Table formats, append the input data to the existing.
+        format : {'fixed', 'table', None}, default 'fixed'
+            Possible values:
+
+            - 'fixed': Fixed format. Fast writing/reading. Not-appendable,
+              nor searchable.
+            - 'table': Table format. Write as a PyTables Table structure
+              which may perform worse but allow more flexible operations
+              like searching / selecting subsets of the data.
+            - If None, pd.get_option('io.hdf.default_format') is checked,
+              followed by fallback to "fixed".
+        index : bool, default True
+            Write DataFrame index as a column.
+        min_itemsize : dict or int, optional
+            Map column names to minimum string sizes for columns.
+        nan_rep : Any, optional
+            How to represent null values as str.
+            Not allowed with append=True.
+        dropna : bool, default False, optional
+            Remove missing values.
+        data_columns : list of columns or True, optional
+            List of columns to create as indexed data columns for on-disk
+            queries, or True to use all columns. By default only the axes
+            of the object are indexed. See
+            :ref:`Query via data columns`. for
+            more information.
+            Applicable only to format='table'.
+        errors : str, default 'strict'
+            Specifies how encoding and decoding errors are to be handled.
+            See the errors argument for :func:`open` for a full list
+            of options.
+        encoding : str, default "UTF-8"
+
+        See Also
+        --------
+        read_hdf : Read from HDF file.
+        DataFrame.to_orc : Write a DataFrame to the binary orc format.
+        DataFrame.to_parquet : Write a DataFrame to the binary parquet format.
+        DataFrame.to_sql : Write to a SQL table.
+        DataFrame.to_feather : Write out feather-format for DataFrames.
+        DataFrame.to_csv : Write out to a csv file.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]},
+        ...                   index=['a', 'b', 'c'])  # doctest: +SKIP
+        >>> df.to_hdf('data.h5', key='df', mode='w')  # doctest: +SKIP
+
+        We can add another object to the same file:
+
+        >>> s = pd.Series([1, 2, 3, 4])  # doctest: +SKIP
+        >>> s.to_hdf('data.h5', key='s')  # doctest: +SKIP
+
+        Reading from HDF file:
+
+        >>> pd.read_hdf('data.h5', 'df')  # doctest: +SKIP
+        A  B
+        a  1  4
+        b  2  5
+        c  3  6
+        >>> pd.read_hdf('data.h5', 's')  # doctest: +SKIP
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: int64
+        """
+        from pandas.io import pytables
+
+        # Argument 3 to "to_hdf" has incompatible type "NDFrame"; expected
+        # "Union[DataFrame, Series]" [arg-type]
+        pytables.to_hdf(
+            path_or_buf,
+            key,
+            self,  # type: ignore[arg-type]
+            mode=mode,
+            complevel=complevel,
+            complib=complib,
+            append=append,
+            format=format,
+            index=index,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            dropna=dropna,
+            data_columns=data_columns,
+            errors=errors,
+            encoding=encoding,
+        )
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "name", "con"], name="to_sql"
+    )
+    def to_sql(
+        self,
+        name: str,
+        con,
+        schema: str | None = None,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        index: bool_t = True,
+        index_label: IndexLabel | None = None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        method: Literal["multi"] | Callable | None = None,
+    ) -> int | None:
+        """
+        Write records stored in a DataFrame to a SQL database.
+
+        Databases supported by SQLAlchemy [1]_ are supported. Tables can be
+        newly created, appended to, or overwritten.
+
+        Parameters
+        ----------
+        name : str
+            Name of SQL table.
+        con : sqlalchemy.engine.(Engine or Connection) or sqlite3.Connection
+            Using SQLAlchemy makes it possible to use any DB supported by that
+            library. Legacy support is provided for sqlite3.Connection objects. The user
+            is responsible for engine disposal and connection closure for the SQLAlchemy
+            connectable. See `here \
+                `_.
+            If passing a sqlalchemy.engine.Connection which is already in a transaction,
+            the transaction will not be committed.  If passing a sqlite3.Connection,
+            it will not be possible to roll back the record insertion.
+
+        schema : str, optional
+            Specify the schema (if database flavor supports this). If None, use
+            default schema.
+        if_exists : {'fail', 'replace', 'append'}, default 'fail'
+            How to behave if the table already exists.
+
+            * fail: Raise a ValueError.
+            * replace: Drop the table before inserting new values.
+            * append: Insert new values to the existing table.
+
+        index : bool, default True
+            Write DataFrame index as a column. Uses `index_label` as the column
+            name in the table. Creates a table index for this column.
+        index_label : str or sequence, default None
+            Column label for index column(s). If None is given (default) and
+            `index` is True, then the index names are used.
+            A sequence should be given if the DataFrame uses MultiIndex.
+        chunksize : int, optional
+            Specify the number of rows in each batch to be written at a time.
+            By default, all rows will be written at once.
+        dtype : dict or scalar, optional
+            Specifying the datatype for columns. If a dictionary is used, the
+            keys should be the column names and the values should be the
+            SQLAlchemy types or strings for the sqlite3 legacy mode. If a
+            scalar is provided, it will be applied to all columns.
+        method : {None, 'multi', callable}, optional
+            Controls the SQL insertion clause used:
+
+            * None : Uses standard SQL ``INSERT`` clause (one per row).
+            * 'multi': Pass multiple values in a single ``INSERT`` clause.
+            * callable with signature ``(pd_table, conn, keys, data_iter)``.
+
+            Details and a sample callable implementation can be found in the
+            section :ref:`insert method `.
+
+        Returns
+        -------
+        None or int
+            Number of rows affected by to_sql. None is returned if the callable
+            passed into ``method`` does not return an integer number of rows.
+
+            The number of returned rows affected is the sum of the ``rowcount``
+            attribute of ``sqlite3.Cursor`` or SQLAlchemy connectable which may not
+            reflect the exact number of written rows as stipulated in the
+            `sqlite3 `__ or
+            `SQLAlchemy `__.
+
+            .. versionadded:: 1.4.0
+
+        Raises
+        ------
+        ValueError
+            When the table already exists and `if_exists` is 'fail' (the
+            default).
+
+        See Also
+        --------
+        read_sql : Read a DataFrame from a table.
+
+        Notes
+        -----
+        Timezone aware datetime columns will be written as
+        ``Timestamp with timezone`` type with SQLAlchemy if supported by the
+        database. Otherwise, the datetimes will be stored as timezone unaware
+        timestamps local to the original timezone.
+
+        Not all datastores support ``method="multi"``. Oracle, for example,
+        does not support multi-value insert.
+
+        References
+        ----------
+        .. [1] https://docs.sqlalchemy.org
+        .. [2] https://www.python.org/dev/peps/pep-0249/
+
+        Examples
+        --------
+        Create an in-memory SQLite database.
+
+        >>> from sqlalchemy import create_engine
+        >>> engine = create_engine('sqlite://', echo=False)
+
+        Create a table from scratch with 3 rows.
+
+        >>> df = pd.DataFrame({'name' : ['User 1', 'User 2', 'User 3']})
+        >>> df
+             name
+        0  User 1
+        1  User 2
+        2  User 3
+
+        >>> df.to_sql(name='users', con=engine)
+        3
+        >>> from sqlalchemy import text
+        >>> with engine.connect() as conn:
+        ...    conn.execute(text("SELECT * FROM users")).fetchall()
+        [(0, 'User 1'), (1, 'User 2'), (2, 'User 3')]
+
+        An `sqlalchemy.engine.Connection` can also be passed to `con`:
+
+        >>> with engine.begin() as connection:
+        ...     df1 = pd.DataFrame({'name' : ['User 4', 'User 5']})
+        ...     df1.to_sql(name='users', con=connection, if_exists='append')
+        2
+
+        This is allowed to support operations that require that the same
+        DBAPI connection is used for the entire operation.
+
+        >>> df2 = pd.DataFrame({'name' : ['User 6', 'User 7']})
+        >>> df2.to_sql(name='users', con=engine, if_exists='append')
+        2
+        >>> with engine.connect() as conn:
+        ...    conn.execute(text("SELECT * FROM users")).fetchall()
+        [(0, 'User 1'), (1, 'User 2'), (2, 'User 3'),
+         (0, 'User 4'), (1, 'User 5'), (0, 'User 6'),
+         (1, 'User 7')]
+
+        Overwrite the table with just ``df2``.
+
+        >>> df2.to_sql(name='users', con=engine, if_exists='replace',
+        ...            index_label='id')
+        2
+        >>> with engine.connect() as conn:
+        ...    conn.execute(text("SELECT * FROM users")).fetchall()
+        [(0, 'User 6'), (1, 'User 7')]
+
+        Use ``method`` to define a callable insertion method to do nothing
+        if there's a primary key conflict on a table in a PostgreSQL database.
+
+        >>> from sqlalchemy.dialects.postgresql import insert
+        >>> def insert_on_conflict_nothing(table, conn, keys, data_iter):
+        ...     # "a" is the primary key in "conflict_table"
+        ...     data = [dict(zip(keys, row)) for row in data_iter]
+        ...     stmt = insert(table.table).values(data).on_conflict_do_nothing(index_elements=["a"])
+        ...     result = conn.execute(stmt)
+        ...     return result.rowcount
+        >>> df_conflict.to_sql(name="conflict_table", con=conn, if_exists="append", method=insert_on_conflict_nothing)  # doctest: +SKIP
+        0
+
+        For MySQL, a callable to update columns ``b`` and ``c`` if there's a conflict
+        on a primary key.
+
+        >>> from sqlalchemy.dialects.mysql import insert
+        >>> def insert_on_conflict_update(table, conn, keys, data_iter):
+        ...     # update columns "b" and "c" on primary key conflict
+        ...     data = [dict(zip(keys, row)) for row in data_iter]
+        ...     stmt = (
+        ...         insert(table.table)
+        ...         .values(data)
+        ...     )
+        ...     stmt = stmt.on_duplicate_key_update(b=stmt.inserted.b, c=stmt.inserted.c)
+        ...     result = conn.execute(stmt)
+        ...     return result.rowcount
+        >>> df_conflict.to_sql(name="conflict_table", con=conn, if_exists="append", method=insert_on_conflict_update)  # doctest: +SKIP
+        2
+
+        Specify the dtype (especially useful for integers with missing values).
+        Notice that while pandas is forced to store the data as floating point,
+        the database supports nullable integers. When fetching the data with
+        Python, we get back integer scalars.
+
+        >>> df = pd.DataFrame({"A": [1, None, 2]})
+        >>> df
+             A
+        0  1.0
+        1  NaN
+        2  2.0
+
+        >>> from sqlalchemy.types import Integer
+        >>> df.to_sql(name='integers', con=engine, index=False,
+        ...           dtype={"A": Integer()})
+        3
+
+        >>> with engine.connect() as conn:
+        ...   conn.execute(text("SELECT * FROM integers")).fetchall()
+        [(1,), (None,), (2,)]
+        """  # noqa: E501
+        from pandas.io import sql
+
+        return sql.to_sql(
+            self,
+            name,
+            con,
+            schema=schema,
+            if_exists=if_exists,
+            index=index,
+            index_label=index_label,
+            chunksize=chunksize,
+            dtype=dtype,
+            method=method,
+        )
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path"], name="to_pickle"
+    )
+    @doc(
+        storage_options=_shared_docs["storage_options"],
+        compression_options=_shared_docs["compression_options"] % "path",
+    )
+    def to_pickle(
+        self,
+        path: FilePath | WriteBuffer[bytes],
+        compression: CompressionOptions = "infer",
+        protocol: int = pickle.HIGHEST_PROTOCOL,
+        storage_options: StorageOptions | None = None,
+    ) -> None:
+        """
+        Pickle (serialize) object to file.
+
+        Parameters
+        ----------
+        path : str, path object, or file-like object
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a binary ``write()`` function. File path where
+            the pickled object will be stored.
+        {compression_options}
+        protocol : int
+            Int which indicates which protocol should be used by the pickler,
+            default HIGHEST_PROTOCOL (see [1]_ paragraph 12.1.2). The possible
+            values are 0, 1, 2, 3, 4, 5. A negative value for the protocol
+            parameter is equivalent to setting its value to HIGHEST_PROTOCOL.
+
+            .. [1] https://docs.python.org/3/library/pickle.html.
+
+        {storage_options}
+
+        See Also
+        --------
+        read_pickle : Load pickled pandas object (or any object) from file.
+        DataFrame.to_hdf : Write DataFrame to an HDF5 file.
+        DataFrame.to_sql : Write DataFrame to a SQL database.
+        DataFrame.to_parquet : Write a DataFrame to the binary parquet format.
+
+        Examples
+        --------
+        >>> original_df = pd.DataFrame({{"foo": range(5), "bar": range(5, 10)}})  # doctest: +SKIP
+        >>> original_df  # doctest: +SKIP
+           foo  bar
+        0    0    5
+        1    1    6
+        2    2    7
+        3    3    8
+        4    4    9
+        >>> original_df.to_pickle("./dummy.pkl")  # doctest: +SKIP
+
+        >>> unpickled_df = pd.read_pickle("./dummy.pkl")  # doctest: +SKIP
+        >>> unpickled_df  # doctest: +SKIP
+           foo  bar
+        0    0    5
+        1    1    6
+        2    2    7
+        3    3    8
+        4    4    9
+        """  # noqa: E501
+        from pandas.io.pickle import to_pickle
+
+        to_pickle(
+            self,
+            path,
+            compression=compression,
+            protocol=protocol,
+            storage_options=storage_options,
+        )
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self"], name="to_clipboard"
+    )
+    def to_clipboard(
+        self, excel: bool_t = True, sep: str | None = None, **kwargs
+    ) -> None:
+        r"""
+        Copy object to the system clipboard.
+
+        Write a text representation of object to the system clipboard.
+        This can be pasted into Excel, for example.
+
+        Parameters
+        ----------
+        excel : bool, default True
+            Produce output in a csv format for easy pasting into excel.
+
+            - True, use the provided separator for csv pasting.
+            - False, write a string representation of the object to the clipboard.
+
+        sep : str, default ``'\t'``
+            Field delimiter.
+        **kwargs
+            These parameters will be passed to DataFrame.to_csv.
+
+        See Also
+        --------
+        DataFrame.to_csv : Write a DataFrame to a comma-separated values
+            (csv) file.
+        read_clipboard : Read text from clipboard and pass to read_csv.
+
+        Notes
+        -----
+        Requirements for your platform.
+
+          - Linux : `xclip`, or `xsel` (with `PyQt4` modules)
+          - Windows : none
+          - macOS : none
+
+        This method uses the processes developed for the package `pyperclip`. A
+        solution to render any output string format is given in the examples.
+
+        Examples
+        --------
+        Copy the contents of a DataFrame to the clipboard.
+
+        >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], columns=['A', 'B', 'C'])
+
+        >>> df.to_clipboard(sep=',')  # doctest: +SKIP
+        ... # Wrote the following to the system clipboard:
+        ... # ,A,B,C
+        ... # 0,1,2,3
+        ... # 1,4,5,6
+
+        We can omit the index by passing the keyword `index` and setting
+        it to false.
+
+        >>> df.to_clipboard(sep=',', index=False)  # doctest: +SKIP
+        ... # Wrote the following to the system clipboard:
+        ... # A,B,C
+        ... # 1,2,3
+        ... # 4,5,6
+
+        Using the original `pyperclip` package for any string output format.
+
+        .. code-block:: python
+
+           import pyperclip
+           html = df.style.to_html()
+           pyperclip.copy(html)
+        """
+        from pandas.io import clipboards
+
+        clipboards.to_clipboard(self, excel=excel, sep=sep, **kwargs)
+
+    @final
+    def to_xarray(self):
+        """
+        Return an xarray object from the pandas object.
+
+        Returns
+        -------
+        xarray.DataArray or xarray.Dataset
+            Data in the pandas structure converted to Dataset if the object is
+            a DataFrame, or a DataArray if the object is a Series.
+
+        See Also
+        --------
+        DataFrame.to_hdf : Write DataFrame to an HDF5 file.
+        DataFrame.to_parquet : Write a DataFrame to the binary parquet format.
+
+        Notes
+        -----
+        See the `xarray docs `__
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('falcon', 'bird', 389.0, 2),
+        ...                    ('parrot', 'bird', 24.0, 2),
+        ...                    ('lion', 'mammal', 80.5, 4),
+        ...                    ('monkey', 'mammal', np.nan, 4)],
+        ...                   columns=['name', 'class', 'max_speed',
+        ...                            'num_legs'])
+        >>> df
+             name   class  max_speed  num_legs
+        0  falcon    bird      389.0         2
+        1  parrot    bird       24.0         2
+        2    lion  mammal       80.5         4
+        3  monkey  mammal        NaN         4
+
+        >>> df.to_xarray()  # doctest: +SKIP
+        
+        Dimensions:    (index: 4)
+        Coordinates:
+          * index      (index) int64 32B 0 1 2 3
+        Data variables:
+            name       (index) object 32B 'falcon' 'parrot' 'lion' 'monkey'
+            class      (index) object 32B 'bird' 'bird' 'mammal' 'mammal'
+            max_speed  (index) float64 32B 389.0 24.0 80.5 nan
+            num_legs   (index) int64 32B 2 2 4 4
+
+        >>> df['max_speed'].to_xarray()  # doctest: +SKIP
+        
+        array([389. ,  24. ,  80.5,   nan])
+        Coordinates:
+          * index    (index) int64 0 1 2 3
+
+        >>> dates = pd.to_datetime(['2018-01-01', '2018-01-01',
+        ...                         '2018-01-02', '2018-01-02'])
+        >>> df_multiindex = pd.DataFrame({'date': dates,
+        ...                               'animal': ['falcon', 'parrot',
+        ...                                          'falcon', 'parrot'],
+        ...                               'speed': [350, 18, 361, 15]})
+        >>> df_multiindex = df_multiindex.set_index(['date', 'animal'])
+
+        >>> df_multiindex
+                           speed
+        date       animal
+        2018-01-01 falcon    350
+                   parrot     18
+        2018-01-02 falcon    361
+                   parrot     15
+
+        >>> df_multiindex.to_xarray()  # doctest: +SKIP
+        
+        Dimensions:  (date: 2, animal: 2)
+        Coordinates:
+          * date     (date) datetime64[ns] 2018-01-01 2018-01-02
+          * animal   (animal) object 'falcon' 'parrot'
+        Data variables:
+            speed    (date, animal) int64 350 18 361 15
+        """
+        xarray = import_optional_dependency("xarray")
+
+        if self.ndim == 1:
+            return xarray.DataArray.from_series(self)
+        else:
+            return xarray.Dataset.from_dataframe(self)
+
+    @overload
+    def to_latex(
+        self,
+        buf: None = ...,
+        columns: Sequence[Hashable] | None = ...,
+        header: bool_t | SequenceNotStr[str] = ...,
+        index: bool_t = ...,
+        na_rep: str = ...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
+        sparsify: bool_t | None = ...,
+        index_names: bool_t = ...,
+        bold_rows: bool_t = ...,
+        column_format: str | None = ...,
+        longtable: bool_t | None = ...,
+        escape: bool_t | None = ...,
+        encoding: str | None = ...,
+        decimal: str = ...,
+        multicolumn: bool_t | None = ...,
+        multicolumn_format: str | None = ...,
+        multirow: bool_t | None = ...,
+        caption: str | tuple[str, str] | None = ...,
+        label: str | None = ...,
+        position: str | None = ...,
+    ) -> str:
+        ...
+
+    @overload
+    def to_latex(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        columns: Sequence[Hashable] | None = ...,
+        header: bool_t | SequenceNotStr[str] = ...,
+        index: bool_t = ...,
+        na_rep: str = ...,
+        formatters: FormattersType | None = ...,
+        float_format: FloatFormatType | None = ...,
+        sparsify: bool_t | None = ...,
+        index_names: bool_t = ...,
+        bold_rows: bool_t = ...,
+        column_format: str | None = ...,
+        longtable: bool_t | None = ...,
+        escape: bool_t | None = ...,
+        encoding: str | None = ...,
+        decimal: str = ...,
+        multicolumn: bool_t | None = ...,
+        multicolumn_format: str | None = ...,
+        multirow: bool_t | None = ...,
+        caption: str | tuple[str, str] | None = ...,
+        label: str | None = ...,
+        position: str | None = ...,
+    ) -> None:
+        ...
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "buf"], name="to_latex"
+    )
+    def to_latex(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        columns: Sequence[Hashable] | None = None,
+        header: bool_t | SequenceNotStr[str] = True,
+        index: bool_t = True,
+        na_rep: str = "NaN",
+        formatters: FormattersType | None = None,
+        float_format: FloatFormatType | None = None,
+        sparsify: bool_t | None = None,
+        index_names: bool_t = True,
+        bold_rows: bool_t = False,
+        column_format: str | None = None,
+        longtable: bool_t | None = None,
+        escape: bool_t | None = None,
+        encoding: str | None = None,
+        decimal: str = ".",
+        multicolumn: bool_t | None = None,
+        multicolumn_format: str | None = None,
+        multirow: bool_t | None = None,
+        caption: str | tuple[str, str] | None = None,
+        label: str | None = None,
+        position: str | None = None,
+    ) -> str | None:
+        r"""
+        Render object to a LaTeX tabular, longtable, or nested table.
+
+        Requires ``\usepackage{{booktabs}}``.  The output can be copy/pasted
+        into a main LaTeX document or read from an external file
+        with ``\input{{table.tex}}``.
+
+        .. versionchanged:: 2.0.0
+           Refactored to use the Styler implementation via jinja2 templating.
+
+        Parameters
+        ----------
+        buf : str, Path or StringIO-like, optional, default None
+            Buffer to write to. If None, the output is returned as a string.
+        columns : list of label, optional
+            The subset of columns to write. Writes all columns by default.
+        header : bool or list of str, default True
+            Write out the column names. If a list of strings is given,
+            it is assumed to be aliases for the column names.
+        index : bool, default True
+            Write row names (index).
+        na_rep : str, default 'NaN'
+            Missing data representation.
+        formatters : list of functions or dict of {{str: function}}, optional
+            Formatter functions to apply to columns' elements by position or
+            name. The result of each function must be a unicode string.
+            List must be of length equal to the number of columns.
+        float_format : one-parameter function or str, optional, default None
+            Formatter for floating point numbers. For example
+            ``float_format="%.2f"`` and ``float_format="{{:0.2f}}".format`` will
+            both result in 0.1234 being formatted as 0.12.
+        sparsify : bool, optional
+            Set to False for a DataFrame with a hierarchical index to print
+            every multiindex key at each row. By default, the value will be
+            read from the config module.
+        index_names : bool, default True
+            Prints the names of the indexes.
+        bold_rows : bool, default False
+            Make the row labels bold in the output.
+        column_format : str, optional
+            The columns format as specified in `LaTeX table format
+            `__ e.g. 'rcl' for 3
+            columns. By default, 'l' will be used for all columns except
+            columns of numbers, which default to 'r'.
+        longtable : bool, optional
+            Use a longtable environment instead of tabular. Requires
+            adding a \usepackage{{longtable}} to your LaTeX preamble.
+            By default, the value will be read from the pandas config
+            module, and set to `True` if the option ``styler.latex.environment`` is
+            `"longtable"`.
+
+            .. versionchanged:: 2.0.0
+               The pandas option affecting this argument has changed.
+        escape : bool, optional
+            By default, the value will be read from the pandas config
+            module and set to `True` if the option ``styler.format.escape`` is
+            `"latex"`. When set to False prevents from escaping latex special
+            characters in column names.
+
+            .. versionchanged:: 2.0.0
+               The pandas option affecting this argument has changed, as has the
+               default value to `False`.
+        encoding : str, optional
+            A string representing the encoding to use in the output file,
+            defaults to 'utf-8'.
+        decimal : str, default '.'
+            Character recognized as decimal separator, e.g. ',' in Europe.
+        multicolumn : bool, default True
+            Use \multicolumn to enhance MultiIndex columns.
+            The default will be read from the config module, and is set
+            as the option ``styler.sparse.columns``.
+
+            .. versionchanged:: 2.0.0
+               The pandas option affecting this argument has changed.
+        multicolumn_format : str, default 'r'
+            The alignment for multicolumns, similar to `column_format`
+            The default will be read from the config module, and is set as the option
+            ``styler.latex.multicol_align``.
+
+            .. versionchanged:: 2.0.0
+               The pandas option affecting this argument has changed, as has the
+               default value to "r".
+        multirow : bool, default True
+            Use \multirow to enhance MultiIndex rows. Requires adding a
+            \usepackage{{multirow}} to your LaTeX preamble. Will print
+            centered labels (instead of top-aligned) across the contained
+            rows, separating groups via clines. The default will be read
+            from the pandas config module, and is set as the option
+            ``styler.sparse.index``.
+
+            .. versionchanged:: 2.0.0
+               The pandas option affecting this argument has changed, as has the
+               default value to `True`.
+        caption : str or tuple, optional
+            Tuple (full_caption, short_caption),
+            which results in ``\caption[short_caption]{{full_caption}}``;
+            if a single string is passed, no short caption will be set.
+        label : str, optional
+            The LaTeX label to be placed inside ``\label{{}}`` in the output.
+            This is used with ``\ref{{}}`` in the main ``.tex`` file.
+
+        position : str, optional
+            The LaTeX positional argument for tables, to be placed after
+            ``\begin{{}}`` in the output.
+
+        Returns
+        -------
+        str or None
+            If buf is None, returns the result as a string. Otherwise returns None.
+
+        See Also
+        --------
+        io.formats.style.Styler.to_latex : Render a DataFrame to LaTeX
+            with conditional formatting.
+        DataFrame.to_string : Render a DataFrame to a console-friendly
+            tabular output.
+        DataFrame.to_html : Render a DataFrame as an HTML table.
+
+        Notes
+        -----
+        As of v2.0.0 this method has changed to use the Styler implementation as
+        part of :meth:`.Styler.to_latex` via ``jinja2`` templating. This means
+        that ``jinja2`` is a requirement, and needs to be installed, for this method
+        to function. It is advised that users switch to using Styler, since that
+        implementation is more frequently updated and contains much more
+        flexibility with the output.
+
+        Examples
+        --------
+        Convert a general DataFrame to LaTeX with formatting:
+
+        >>> df = pd.DataFrame(dict(name=['Raphael', 'Donatello'],
+        ...                        age=[26, 45],
+        ...                        height=[181.23, 177.65]))
+        >>> print(df.to_latex(index=False,
+        ...                   formatters={"name": str.upper},
+        ...                   float_format="{:.1f}".format,
+        ... ))  # doctest: +SKIP
+        \begin{tabular}{lrr}
+        \toprule
+        name & age & height \\
+        \midrule
+        RAPHAEL & 26 & 181.2 \\
+        DONATELLO & 45 & 177.7 \\
+        \bottomrule
+        \end{tabular}
+        """
+        # Get defaults from the pandas config
+        if self.ndim == 1:
+            self = self.to_frame()
+        if longtable is None:
+            longtable = config.get_option("styler.latex.environment") == "longtable"
+        if escape is None:
+            escape = config.get_option("styler.format.escape") == "latex"
+        if multicolumn is None:
+            multicolumn = config.get_option("styler.sparse.columns")
+        if multicolumn_format is None:
+            multicolumn_format = config.get_option("styler.latex.multicol_align")
+        if multirow is None:
+            multirow = config.get_option("styler.sparse.index")
+
+        if column_format is not None and not isinstance(column_format, str):
+            raise ValueError("`column_format` must be str or unicode")
+        length = len(self.columns) if columns is None else len(columns)
+        if isinstance(header, (list, tuple)) and len(header) != length:
+            raise ValueError(f"Writing {length} cols but got {len(header)} aliases")
+
+        # Refactor formatters/float_format/decimal/na_rep/escape to Styler structure
+        base_format_ = {
+            "na_rep": na_rep,
+            "escape": "latex" if escape else None,
+            "decimal": decimal,
+        }
+        index_format_: dict[str, Any] = {"axis": 0, **base_format_}
+        column_format_: dict[str, Any] = {"axis": 1, **base_format_}
+
+        if isinstance(float_format, str):
+            float_format_: Callable | None = lambda x: float_format % x
+        else:
+            float_format_ = float_format
+
+        def _wrap(x, alt_format_):
+            if isinstance(x, (float, complex)) and float_format_ is not None:
+                return float_format_(x)
+            else:
+                return alt_format_(x)
+
+        formatters_: list | tuple | dict | Callable | None = None
+        if isinstance(formatters, list):
+            formatters_ = {
+                c: partial(_wrap, alt_format_=formatters[i])
+                for i, c in enumerate(self.columns)
+            }
+        elif isinstance(formatters, dict):
+            index_formatter = formatters.pop("__index__", None)
+            column_formatter = formatters.pop("__columns__", None)
+            if index_formatter is not None:
+                index_format_.update({"formatter": index_formatter})
+            if column_formatter is not None:
+                column_format_.update({"formatter": column_formatter})
+
+            formatters_ = formatters
+            float_columns = self.select_dtypes(include="float").columns
+            for col in float_columns:
+                if col not in formatters.keys():
+                    formatters_.update({col: float_format_})
+        elif formatters is None and float_format is not None:
+            formatters_ = partial(_wrap, alt_format_=lambda v: v)
+        format_index_ = [index_format_, column_format_]
+
+        # Deal with hiding indexes and relabelling column names
+        hide_: list[dict] = []
+        relabel_index_: list[dict] = []
+        if columns:
+            hide_.append(
+                {
+                    "subset": [c for c in self.columns if c not in columns],
+                    "axis": "columns",
+                }
+            )
+        if header is False:
+            hide_.append({"axis": "columns"})
+        elif isinstance(header, (list, tuple)):
+            relabel_index_.append({"labels": header, "axis": "columns"})
+            format_index_ = [index_format_]  # column_format is overwritten
+
+        if index is False:
+            hide_.append({"axis": "index"})
+        if index_names is False:
+            hide_.append({"names": True, "axis": "index"})
+
+        render_kwargs_ = {
+            "hrules": True,
+            "sparse_index": sparsify,
+            "sparse_columns": sparsify,
+            "environment": "longtable" if longtable else None,
+            "multicol_align": multicolumn_format
+            if multicolumn
+            else f"naive-{multicolumn_format}",
+            "multirow_align": "t" if multirow else "naive",
+            "encoding": encoding,
+            "caption": caption,
+            "label": label,
+            "position": position,
+            "column_format": column_format,
+            "clines": "skip-last;data"
+            if (multirow and isinstance(self.index, MultiIndex))
+            else None,
+            "bold_rows": bold_rows,
+        }
+
+        return self._to_latex_via_styler(
+            buf,
+            hide=hide_,
+            relabel_index=relabel_index_,
+            format={"formatter": formatters_, **base_format_},
+            format_index=format_index_,
+            render_kwargs=render_kwargs_,
+        )
+
+    @final
+    def _to_latex_via_styler(
+        self,
+        buf=None,
+        *,
+        hide: dict | list[dict] | None = None,
+        relabel_index: dict | list[dict] | None = None,
+        format: dict | list[dict] | None = None,
+        format_index: dict | list[dict] | None = None,
+        render_kwargs: dict | None = None,
+    ):
+        """
+        Render object to a LaTeX tabular, longtable, or nested table.
+
+        Uses the ``Styler`` implementation with the following, ordered, method chaining:
+
+        .. code-block:: python
+           styler = Styler(DataFrame)
+           styler.hide(**hide)
+           styler.relabel_index(**relabel_index)
+           styler.format(**format)
+           styler.format_index(**format_index)
+           styler.to_latex(buf=buf, **render_kwargs)
+
+        Parameters
+        ----------
+        buf : str, Path or StringIO-like, optional, default None
+            Buffer to write to. If None, the output is returned as a string.
+        hide : dict, list of dict
+            Keyword args to pass to the method call of ``Styler.hide``. If a list will
+            call the method numerous times.
+        relabel_index : dict, list of dict
+            Keyword args to pass to the method of ``Styler.relabel_index``. If a list
+            will call the method numerous times.
+        format : dict, list of dict
+            Keyword args to pass to the method call of ``Styler.format``. If a list will
+            call the method numerous times.
+        format_index : dict, list of dict
+            Keyword args to pass to the method call of ``Styler.format_index``. If a
+            list will call the method numerous times.
+        render_kwargs : dict
+            Keyword args to pass to the method call of ``Styler.to_latex``.
+
+        Returns
+        -------
+        str or None
+            If buf is None, returns the result as a string. Otherwise returns None.
+        """
+        from pandas.io.formats.style import Styler
+
+        self = cast("DataFrame", self)
+        styler = Styler(self, uuid="")
+
+        for kw_name in ["hide", "relabel_index", "format", "format_index"]:
+            kw = vars()[kw_name]
+            if isinstance(kw, dict):
+                getattr(styler, kw_name)(**kw)
+            elif isinstance(kw, list):
+                for sub_kw in kw:
+                    getattr(styler, kw_name)(**sub_kw)
+
+        # bold_rows is not a direct kwarg of Styler.to_latex
+        render_kwargs = {} if render_kwargs is None else render_kwargs
+        if render_kwargs.pop("bold_rows"):
+            styler.map_index(lambda v: "textbf:--rwrap;")
+
+        return styler.to_latex(buf=buf, **render_kwargs)
+
+    @overload
+    def to_csv(
+        self,
+        path_or_buf: None = ...,
+        sep: str = ...,
+        na_rep: str = ...,
+        float_format: str | Callable | None = ...,
+        columns: Sequence[Hashable] | None = ...,
+        header: bool_t | list[str] = ...,
+        index: bool_t = ...,
+        index_label: IndexLabel | None = ...,
+        mode: str = ...,
+        encoding: str | None = ...,
+        compression: CompressionOptions = ...,
+        quoting: int | None = ...,
+        quotechar: str = ...,
+        lineterminator: str | None = ...,
+        chunksize: int | None = ...,
+        date_format: str | None = ...,
+        doublequote: bool_t = ...,
+        escapechar: str | None = ...,
+        decimal: str = ...,
+        errors: OpenFileErrors = ...,
+        storage_options: StorageOptions = ...,
+    ) -> str:
+        ...
+
+    @overload
+    def to_csv(
+        self,
+        path_or_buf: FilePath | WriteBuffer[bytes] | WriteBuffer[str],
+        sep: str = ...,
+        na_rep: str = ...,
+        float_format: str | Callable | None = ...,
+        columns: Sequence[Hashable] | None = ...,
+        header: bool_t | list[str] = ...,
+        index: bool_t = ...,
+        index_label: IndexLabel | None = ...,
+        mode: str = ...,
+        encoding: str | None = ...,
+        compression: CompressionOptions = ...,
+        quoting: int | None = ...,
+        quotechar: str = ...,
+        lineterminator: str | None = ...,
+        chunksize: int | None = ...,
+        date_format: str | None = ...,
+        doublequote: bool_t = ...,
+        escapechar: str | None = ...,
+        decimal: str = ...,
+        errors: OpenFileErrors = ...,
+        storage_options: StorageOptions = ...,
+    ) -> None:
+        ...
+
+    @final
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "path_or_buf"], name="to_csv"
+    )
+    @doc(
+        storage_options=_shared_docs["storage_options"],
+        compression_options=_shared_docs["compression_options"] % "path_or_buf",
+    )
+    def to_csv(
+        self,
+        path_or_buf: FilePath | WriteBuffer[bytes] | WriteBuffer[str] | None = None,
+        sep: str = ",",
+        na_rep: str = "",
+        float_format: str | Callable | None = None,
+        columns: Sequence[Hashable] | None = None,
+        header: bool_t | list[str] = True,
+        index: bool_t = True,
+        index_label: IndexLabel | None = None,
+        mode: str = "w",
+        encoding: str | None = None,
+        compression: CompressionOptions = "infer",
+        quoting: int | None = None,
+        quotechar: str = '"',
+        lineterminator: str | None = None,
+        chunksize: int | None = None,
+        date_format: str | None = None,
+        doublequote: bool_t = True,
+        escapechar: str | None = None,
+        decimal: str = ".",
+        errors: OpenFileErrors = "strict",
+        storage_options: StorageOptions | None = None,
+    ) -> str | None:
+        r"""
+        Write object to a comma-separated values (csv) file.
+
+        Parameters
+        ----------
+        path_or_buf : str, path object, file-like object, or None, default None
+            String, path object (implementing os.PathLike[str]), or file-like
+            object implementing a write() function. If None, the result is
+            returned as a string. If a non-binary file object is passed, it should
+            be opened with `newline=''`, disabling universal newlines. If a binary
+            file object is passed, `mode` might need to contain a `'b'`.
+        sep : str, default ','
+            String of length 1. Field delimiter for the output file.
+        na_rep : str, default ''
+            Missing data representation.
+        float_format : str, Callable, default None
+            Format string for floating point numbers. If a Callable is given, it takes
+            precedence over other numeric formatting parameters, like decimal.
+        columns : sequence, optional
+            Columns to write.
+        header : bool or list of str, default True
+            Write out the column names. If a list of strings is given it is
+            assumed to be aliases for the column names.
+        index : bool, default True
+            Write row names (index).
+        index_label : str or sequence, or False, default None
+            Column label for index column(s) if desired. If None is given, and
+            `header` and `index` are True, then the index names are used. A
+            sequence should be given if the object uses MultiIndex. If
+            False do not print fields for index names. Use index_label=False
+            for easier importing in R.
+        mode : {{'w', 'x', 'a'}}, default 'w'
+            Forwarded to either `open(mode=)` or `fsspec.open(mode=)` to control
+            the file opening. Typical values include:
+
+            - 'w', truncate the file first.
+            - 'x', exclusive creation, failing if the file already exists.
+            - 'a', append to the end of file if it exists.
+
+        encoding : str, optional
+            A string representing the encoding to use in the output file,
+            defaults to 'utf-8'. `encoding` is not supported if `path_or_buf`
+            is a non-binary file object.
+        {compression_options}
+
+               May be a dict with key 'method' as compression mode
+               and other entries as additional compression options if
+               compression mode is 'zip'.
+
+               Passing compression options as keys in dict is
+               supported for compression modes 'gzip', 'bz2', 'zstd', and 'zip'.
+        quoting : optional constant from csv module
+            Defaults to csv.QUOTE_MINIMAL. If you have set a `float_format`
+            then floats are converted to strings and thus csv.QUOTE_NONNUMERIC
+            will treat them as non-numeric.
+        quotechar : str, default '\"'
+            String of length 1. Character used to quote fields.
+        lineterminator : str, optional
+            The newline character or character sequence to use in the output
+            file. Defaults to `os.linesep`, which depends on the OS in which
+            this method is called ('\\n' for linux, '\\r\\n' for Windows, i.e.).
+
+            .. versionchanged:: 1.5.0
+
+                Previously was line_terminator, changed for consistency with
+                read_csv and the standard library 'csv' module.
+
+        chunksize : int or None
+            Rows to write at a time.
+        date_format : str, default None
+            Format string for datetime objects.
+        doublequote : bool, default True
+            Control quoting of `quotechar` inside a field.
+        escapechar : str, default None
+            String of length 1. Character used to escape `sep` and `quotechar`
+            when appropriate.
+        decimal : str, default '.'
+            Character recognized as decimal separator. E.g. use ',' for
+            European data.
+        errors : str, default 'strict'
+            Specifies how encoding and decoding errors are to be handled.
+            See the errors argument for :func:`open` for a full list
+            of options.
+
+        {storage_options}
+
+        Returns
+        -------
+        None or str
+            If path_or_buf is None, returns the resulting csv format as a
+            string. Otherwise returns None.
+
+        See Also
+        --------
+        read_csv : Load a CSV file into a DataFrame.
+        to_excel : Write DataFrame to an Excel file.
+
+        Examples
+        --------
+        Create 'out.csv' containing 'df' without indices
+
+        >>> df = pd.DataFrame({{'name': ['Raphael', 'Donatello'],
+        ...                    'mask': ['red', 'purple'],
+        ...                    'weapon': ['sai', 'bo staff']}})
+        >>> df.to_csv('out.csv', index=False)  # doctest: +SKIP
+
+        Create 'out.zip' containing 'out.csv'
+
+        >>> df.to_csv(index=False)
+        'name,mask,weapon\nRaphael,red,sai\nDonatello,purple,bo staff\n'
+        >>> compression_opts = dict(method='zip',
+        ...                         archive_name='out.csv')  # doctest: +SKIP
+        >>> df.to_csv('out.zip', index=False,
+        ...           compression=compression_opts)  # doctest: +SKIP
+
+        To write a csv file to a new folder or nested folder you will first
+        need to create it using either Pathlib or os:
+
+        >>> from pathlib import Path  # doctest: +SKIP
+        >>> filepath = Path('folder/subfolder/out.csv')  # doctest: +SKIP
+        >>> filepath.parent.mkdir(parents=True, exist_ok=True)  # doctest: +SKIP
+        >>> df.to_csv(filepath)  # doctest: +SKIP
+
+        >>> import os  # doctest: +SKIP
+        >>> os.makedirs('folder/subfolder', exist_ok=True)  # doctest: +SKIP
+        >>> df.to_csv('folder/subfolder/out.csv')  # doctest: +SKIP
+        """
+        df = self if isinstance(self, ABCDataFrame) else self.to_frame()
+
+        formatter = DataFrameFormatter(
+            frame=df,
+            header=header,
+            index=index,
+            na_rep=na_rep,
+            float_format=float_format,
+            decimal=decimal,
+        )
+
+        return DataFrameRenderer(formatter).to_csv(
+            path_or_buf,
+            lineterminator=lineterminator,
+            sep=sep,
+            encoding=encoding,
+            errors=errors,
+            compression=compression,
+            quoting=quoting,
+            columns=columns,
+            index_label=index_label,
+            mode=mode,
+            chunksize=chunksize,
+            quotechar=quotechar,
+            date_format=date_format,
+            doublequote=doublequote,
+            escapechar=escapechar,
+            storage_options=storage_options,
+        )
+
+    # ----------------------------------------------------------------------
+    # Lookup Caching
+
+    def _reset_cacher(self) -> None:
+        """
+        Reset the cacher.
+        """
+        raise AbstractMethodError(self)
+
+    def _maybe_update_cacher(
+        self,
+        clear: bool_t = False,
+        verify_is_copy: bool_t = True,
+        inplace: bool_t = False,
+    ) -> None:
+        """
+        See if we need to update our parent cacher if clear, then clear our
+        cache.
+
+        Parameters
+        ----------
+        clear : bool, default False
+            Clear the item cache.
+        verify_is_copy : bool, default True
+            Provide is_copy checks.
+        """
+        if using_copy_on_write():
+            return
+
+        if verify_is_copy:
+            self._check_setitem_copy(t="referent")
+
+        if clear:
+            self._clear_item_cache()
+
+    def _clear_item_cache(self) -> None:
+        raise AbstractMethodError(self)
+
+    # ----------------------------------------------------------------------
+    # Indexing Methods
+
+    @final
+    def take(self, indices, axis: Axis = 0, **kwargs) -> Self:
+        """
+        Return the elements in the given *positional* indices along an axis.
+
+        This means that we are not indexing according to actual values in
+        the index attribute of the object. We are indexing according to the
+        actual position of the element in the object.
+
+        Parameters
+        ----------
+        indices : array-like
+            An array of ints indicating which positions to take.
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            The axis on which to select elements. ``0`` means that we are
+            selecting rows, ``1`` means that we are selecting columns.
+            For `Series` this parameter is unused and defaults to 0.
+        **kwargs
+            For compatibility with :meth:`numpy.take`. Has no effect on the
+            output.
+
+        Returns
+        -------
+        same type as caller
+            An array-like containing the elements taken from the object.
+
+        See Also
+        --------
+        DataFrame.loc : Select a subset of a DataFrame by labels.
+        DataFrame.iloc : Select a subset of a DataFrame by positions.
+        numpy.take : Take elements from an array along an axis.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('falcon', 'bird', 389.0),
+        ...                    ('parrot', 'bird', 24.0),
+        ...                    ('lion', 'mammal', 80.5),
+        ...                    ('monkey', 'mammal', np.nan)],
+        ...                   columns=['name', 'class', 'max_speed'],
+        ...                   index=[0, 2, 3, 1])
+        >>> df
+             name   class  max_speed
+        0  falcon    bird      389.0
+        2  parrot    bird       24.0
+        3    lion  mammal       80.5
+        1  monkey  mammal        NaN
+
+        Take elements at positions 0 and 3 along the axis 0 (default).
+
+        Note how the actual indices selected (0 and 1) do not correspond to
+        our selected indices 0 and 3. That's because we are selecting the 0th
+        and 3rd rows, not rows whose indices equal 0 and 3.
+
+        >>> df.take([0, 3])
+             name   class  max_speed
+        0  falcon    bird      389.0
+        1  monkey  mammal        NaN
+
+        Take elements at indices 1 and 2 along the axis 1 (column selection).
+
+        >>> df.take([1, 2], axis=1)
+            class  max_speed
+        0    bird      389.0
+        2    bird       24.0
+        3  mammal       80.5
+        1  mammal        NaN
+
+        We may take elements using negative integers for positive indices,
+        starting from the end of the object, just like with Python lists.
+
+        >>> df.take([-1, -2])
+             name   class  max_speed
+        1  monkey  mammal        NaN
+        3    lion  mammal       80.5
+        """
+
+        nv.validate_take((), kwargs)
+
+        if not isinstance(indices, slice):
+            indices = np.asarray(indices, dtype=np.intp)
+            if (
+                axis == 0
+                and indices.ndim == 1
+                and using_copy_on_write()
+                and is_range_indexer(indices, len(self))
+            ):
+                return self.copy(deep=None)
+        elif self.ndim == 1:
+            raise TypeError(
+                f"{type(self).__name__}.take requires a sequence of integers, "
+                "not slice."
+            )
+        else:
+            warnings.warn(
+                # GH#51539
+                f"Passing a slice to {type(self).__name__}.take is deprecated "
+                "and will raise in a future version. Use `obj[slicer]` or pass "
+                "a sequence of integers instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            # We can get here with a slice via DataFrame.__getitem__
+            indices = np.arange(
+                indices.start, indices.stop, indices.step, dtype=np.intp
+            )
+
+        new_data = self._mgr.take(
+            indices,
+            axis=self._get_block_manager_axis(axis),
+            verify=True,
+        )
+        return self._constructor_from_mgr(new_data, axes=new_data.axes).__finalize__(
+            self, method="take"
+        )
+
+    @final
+    def _take_with_is_copy(self, indices, axis: Axis = 0) -> Self:
+        """
+        Internal version of the `take` method that sets the `_is_copy`
+        attribute to keep track of the parent dataframe (using in indexing
+        for the SettingWithCopyWarning).
+
+        For Series this does the same as the public take (it never sets `_is_copy`).
+
+        See the docstring of `take` for full explanation of the parameters.
+        """
+        result = self.take(indices=indices, axis=axis)
+        # Maybe set copy if we didn't actually change the index.
+        if self.ndim == 2 and not result._get_axis(axis).equals(self._get_axis(axis)):
+            result._set_is_copy(self)
+        return result
+
+    @final
+    def xs(
+        self,
+        key: IndexLabel,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        drop_level: bool_t = True,
+    ) -> Self:
+        """
+        Return cross-section from the Series/DataFrame.
+
+        This method takes a `key` argument to select data at a particular
+        level of a MultiIndex.
+
+        Parameters
+        ----------
+        key : label or tuple of label
+            Label contained in the index, or partially in a MultiIndex.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Axis to retrieve cross-section on.
+        level : object, defaults to first n levels (n=1 or len(key))
+            In case of a key partially contained in a MultiIndex, indicate
+            which levels are used. Levels can be referred by label or position.
+        drop_level : bool, default True
+            If False, returns object with same levels as self.
+
+        Returns
+        -------
+        Series or DataFrame
+            Cross-section from the original Series or DataFrame
+            corresponding to the selected index levels.
+
+        See Also
+        --------
+        DataFrame.loc : Access a group of rows and columns
+            by label(s) or a boolean array.
+        DataFrame.iloc : Purely integer-location based indexing
+            for selection by position.
+
+        Notes
+        -----
+        `xs` can not be used to set values.
+
+        MultiIndex Slicers is a generic way to get/set values on
+        any level or levels.
+        It is a superset of `xs` functionality, see
+        :ref:`MultiIndex Slicers `.
+
+        Examples
+        --------
+        >>> d = {'num_legs': [4, 4, 2, 2],
+        ...      'num_wings': [0, 0, 2, 2],
+        ...      'class': ['mammal', 'mammal', 'mammal', 'bird'],
+        ...      'animal': ['cat', 'dog', 'bat', 'penguin'],
+        ...      'locomotion': ['walks', 'walks', 'flies', 'walks']}
+        >>> df = pd.DataFrame(data=d)
+        >>> df = df.set_index(['class', 'animal', 'locomotion'])
+        >>> df
+                                   num_legs  num_wings
+        class  animal  locomotion
+        mammal cat     walks              4          0
+               dog     walks              4          0
+               bat     flies              2          2
+        bird   penguin walks              2          2
+
+        Get values at specified index
+
+        >>> df.xs('mammal')
+                           num_legs  num_wings
+        animal locomotion
+        cat    walks              4          0
+        dog    walks              4          0
+        bat    flies              2          2
+
+        Get values at several indexes
+
+        >>> df.xs(('mammal', 'dog', 'walks'))
+        num_legs     4
+        num_wings    0
+        Name: (mammal, dog, walks), dtype: int64
+
+        Get values at specified index and level
+
+        >>> df.xs('cat', level=1)
+                           num_legs  num_wings
+        class  locomotion
+        mammal walks              4          0
+
+        Get values at several indexes and levels
+
+        >>> df.xs(('bird', 'walks'),
+        ...       level=[0, 'locomotion'])
+                 num_legs  num_wings
+        animal
+        penguin         2          2
+
+        Get values at specified column and axis
+
+        >>> df.xs('num_wings', axis=1)
+        class   animal   locomotion
+        mammal  cat      walks         0
+                dog      walks         0
+                bat      flies         2
+        bird    penguin  walks         2
+        Name: num_wings, dtype: int64
+        """
+        axis = self._get_axis_number(axis)
+        labels = self._get_axis(axis)
+
+        if isinstance(key, list):
+            raise TypeError("list keys are not supported in xs, pass a tuple instead")
+
+        if level is not None:
+            if not isinstance(labels, MultiIndex):
+                raise TypeError("Index must be a MultiIndex")
+            loc, new_ax = labels.get_loc_level(key, level=level, drop_level=drop_level)
+
+            # create the tuple of the indexer
+            _indexer = [slice(None)] * self.ndim
+            _indexer[axis] = loc
+            indexer = tuple(_indexer)
+
+            result = self.iloc[indexer]
+            setattr(result, result._get_axis_name(axis), new_ax)
+            return result
+
+        if axis == 1:
+            if drop_level:
+                return self[key]
+            index = self.columns
+        else:
+            index = self.index
+
+        if isinstance(index, MultiIndex):
+            loc, new_index = index._get_loc_level(key, level=0)
+            if not drop_level:
+                if lib.is_integer(loc):
+                    # Slice index must be an integer or None
+                    new_index = index[loc : loc + 1]
+                else:
+                    new_index = index[loc]
+        else:
+            loc = index.get_loc(key)
+
+            if isinstance(loc, np.ndarray):
+                if loc.dtype == np.bool_:
+                    (inds,) = loc.nonzero()
+                    return self._take_with_is_copy(inds, axis=axis)
+                else:
+                    return self._take_with_is_copy(loc, axis=axis)
+
+            if not is_scalar(loc):
+                new_index = index[loc]
+
+        if is_scalar(loc) and axis == 0:
+            # In this case loc should be an integer
+            if self.ndim == 1:
+                # if we encounter an array-like and we only have 1 dim
+                # that means that their are list/ndarrays inside the Series!
+                # so just return them (GH 6394)
+                return self._values[loc]
+
+            new_mgr = self._mgr.fast_xs(loc)
+
+            result = self._constructor_sliced_from_mgr(new_mgr, axes=new_mgr.axes)
+            result._name = self.index[loc]
+            result = result.__finalize__(self)
+        elif is_scalar(loc):
+            result = self.iloc[:, slice(loc, loc + 1)]
+        elif axis == 1:
+            result = self.iloc[:, loc]
+        else:
+            result = self.iloc[loc]
+            result.index = new_index
+
+        # this could be a view
+        # but only in a single-dtyped view sliceable case
+        result._set_is_copy(self, copy=not result._is_view)
+        return result
+
+    def __getitem__(self, item):
+        raise AbstractMethodError(self)
+
+    @final
+    def _getitem_slice(self, key: slice) -> Self:
+        """
+        __getitem__ for the case where the key is a slice object.
+        """
+        # _convert_slice_indexer to determine if this slice is positional
+        #  or label based, and if the latter, convert to positional
+        slobj = self.index._convert_slice_indexer(key, kind="getitem")
+        if isinstance(slobj, np.ndarray):
+            # reachable with DatetimeIndex
+            indexer = lib.maybe_indices_to_slice(
+                slobj.astype(np.intp, copy=False), len(self)
+            )
+            if isinstance(indexer, np.ndarray):
+                # GH#43223 If we can not convert, use take
+                return self.take(indexer, axis=0)
+            slobj = indexer
+        return self._slice(slobj)
+
+    def _slice(self, slobj: slice, axis: AxisInt = 0) -> Self:
+        """
+        Construct a slice of this container.
+
+        Slicing with this method is *always* positional.
+        """
+        assert isinstance(slobj, slice), type(slobj)
+        axis = self._get_block_manager_axis(axis)
+        new_mgr = self._mgr.get_slice(slobj, axis=axis)
+        result = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        result = result.__finalize__(self)
+
+        # this could be a view
+        # but only in a single-dtyped view sliceable case
+        is_copy = axis != 0 or result._is_view
+        result._set_is_copy(self, copy=is_copy)
+        return result
+
+    @final
+    def _set_is_copy(self, ref: NDFrame, copy: bool_t = True) -> None:
+        if not copy:
+            self._is_copy = None
+        else:
+            assert ref is not None
+            self._is_copy = weakref.ref(ref)
+
+    def _check_is_chained_assignment_possible(self) -> bool_t:
+        """
+        Check if we are a view, have a cacher, and are of mixed type.
+        If so, then force a setitem_copy check.
+
+        Should be called just near setting a value
+
+        Will return a boolean if it we are a view and are cached, but a
+        single-dtype meaning that the cacher should be updated following
+        setting.
+        """
+        if self._is_copy:
+            self._check_setitem_copy(t="referent")
+        return False
+
+    @final
+    def _check_setitem_copy(self, t: str = "setting", force: bool_t = False):
+        """
+
+        Parameters
+        ----------
+        t : str, the type of setting error
+        force : bool, default False
+           If True, then force showing an error.
+
+        validate if we are doing a setitem on a chained copy.
+
+        It is technically possible to figure out that we are setting on
+        a copy even WITH a multi-dtyped pandas object. In other words, some
+        blocks may be views while other are not. Currently _is_view will ALWAYS
+        return False for multi-blocks to avoid having to handle this case.
+
+        df = DataFrame(np.arange(0,9), columns=['count'])
+        df['group'] = 'b'
+
+        # This technically need not raise SettingWithCopy if both are view
+        # (which is not generally guaranteed but is usually True.  However,
+        # this is in general not a good practice and we recommend using .loc.
+        df.iloc[0:5]['group'] = 'a'
+
+        """
+        if using_copy_on_write() or warn_copy_on_write():
+            return
+
+        # return early if the check is not needed
+        if not (force or self._is_copy):
+            return
+
+        value = config.get_option("mode.chained_assignment")
+        if value is None:
+            return
+
+        # see if the copy is not actually referred; if so, then dissolve
+        # the copy weakref
+        if self._is_copy is not None and not isinstance(self._is_copy, str):
+            r = self._is_copy()
+            if not gc.get_referents(r) or (r is not None and r.shape == self.shape):
+                self._is_copy = None
+                return
+
+        # a custom message
+        if isinstance(self._is_copy, str):
+            t = self._is_copy
+
+        elif t == "referent":
+            t = (
+                "\n"
+                "A value is trying to be set on a copy of a slice from a "
+                "DataFrame\n\n"
+                "See the caveats in the documentation: "
+                "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
+                "indexing.html#returning-a-view-versus-a-copy"
+            )
+
+        else:
+            t = (
+                "\n"
+                "A value is trying to be set on a copy of a slice from a "
+                "DataFrame.\n"
+                "Try using .loc[row_indexer,col_indexer] = value "
+                "instead\n\nSee the caveats in the documentation: "
+                "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
+                "indexing.html#returning-a-view-versus-a-copy"
+            )
+
+        if value == "raise":
+            raise SettingWithCopyError(t)
+        if value == "warn":
+            warnings.warn(t, SettingWithCopyWarning, stacklevel=find_stack_level())
+
+    @final
+    def __delitem__(self, key) -> None:
+        """
+        Delete item
+        """
+        deleted = False
+
+        maybe_shortcut = False
+        if self.ndim == 2 and isinstance(self.columns, MultiIndex):
+            try:
+                # By using engine's __contains__ we effectively
+                # restrict to same-length tuples
+                maybe_shortcut = key not in self.columns._engine
+            except TypeError:
+                pass
+
+        if maybe_shortcut:
+            # Allow shorthand to delete all columns whose first len(key)
+            # elements match key:
+            if not isinstance(key, tuple):
+                key = (key,)
+            for col in self.columns:
+                if isinstance(col, tuple) and col[: len(key)] == key:
+                    del self[col]
+                    deleted = True
+        if not deleted:
+            # If the above loop ran and didn't delete anything because
+            # there was no match, this call should raise the appropriate
+            # exception:
+            loc = self.axes[-1].get_loc(key)
+            self._mgr = self._mgr.idelete(loc)
+
+        # delete from the caches
+        try:
+            del self._item_cache[key]
+        except KeyError:
+            pass
+
+    # ----------------------------------------------------------------------
+    # Unsorted
+
+    @final
+    def _check_inplace_and_allows_duplicate_labels(self, inplace: bool_t):
+        if inplace and not self.flags.allows_duplicate_labels:
+            raise ValueError(
+                "Cannot specify 'inplace=True' when "
+                "'self.flags.allows_duplicate_labels' is False."
+            )
+
+    @final
+    def get(self, key, default=None):
+        """
+        Get item from object for given key (ex: DataFrame column).
+
+        Returns default value if not found.
+
+        Parameters
+        ----------
+        key : object
+
+        Returns
+        -------
+        same type as items contained in object
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     [
+        ...         [24.3, 75.7, "high"],
+        ...         [31, 87.8, "high"],
+        ...         [22, 71.6, "medium"],
+        ...         [35, 95, "medium"],
+        ...     ],
+        ...     columns=["temp_celsius", "temp_fahrenheit", "windspeed"],
+        ...     index=pd.date_range(start="2014-02-12", end="2014-02-15", freq="D"),
+        ... )
+
+        >>> df
+                    temp_celsius  temp_fahrenheit windspeed
+        2014-02-12          24.3             75.7      high
+        2014-02-13          31.0             87.8      high
+        2014-02-14          22.0             71.6    medium
+        2014-02-15          35.0             95.0    medium
+
+        >>> df.get(["temp_celsius", "windspeed"])
+                    temp_celsius windspeed
+        2014-02-12          24.3      high
+        2014-02-13          31.0      high
+        2014-02-14          22.0    medium
+        2014-02-15          35.0    medium
+
+        >>> ser = df['windspeed']
+        >>> ser.get('2014-02-13')
+        'high'
+
+        If the key isn't found, the default value will be used.
+
+        >>> df.get(["temp_celsius", "temp_kelvin"], default="default_value")
+        'default_value'
+
+        >>> ser.get('2014-02-10', '[unknown]')
+        '[unknown]'
+        """
+        try:
+            return self[key]
+        except (KeyError, ValueError, IndexError):
+            return default
+
+    @final
+    @property
+    def _is_view(self) -> bool_t:
+        """Return boolean indicating if self is view of another array"""
+        return self._mgr.is_view
+
+    @final
+    def reindex_like(
+        self,
+        other,
+        method: Literal["backfill", "bfill", "pad", "ffill", "nearest"] | None = None,
+        copy: bool_t | None = None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> Self:
+        """
+        Return an object with matching indices as other object.
+
+        Conform the object to the same index on all axes. Optional
+        filling logic, placing NaN in locations having no value
+        in the previous index. A new object is produced unless the
+        new index is equivalent to the current one and copy=False.
+
+        Parameters
+        ----------
+        other : Object of the same data type
+            Its row and column indices are used to define the new indices
+            of this object.
+        method : {None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}
+            Method to use for filling holes in reindexed DataFrame.
+            Please note: this is only applicable to DataFrames/Series with a
+            monotonically increasing/decreasing index.
+
+            * None (default): don't fill gaps
+            * pad / ffill: propagate last valid observation forward to next
+              valid
+            * backfill / bfill: use next valid observation to fill gap
+            * nearest: use nearest valid observations to fill gap.
+
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        limit : int, default None
+            Maximum number of consecutive labels to fill for inexact matches.
+        tolerance : optional
+            Maximum distance between original and new labels for inexact
+            matches. The values of the index at the matching locations must
+            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
+
+            Tolerance may be a scalar value, which applies the same tolerance
+            to all values, or list-like, which applies variable tolerance per
+            element. List-like includes list, tuple, array, Series, and must be
+            the same size as the index and its dtype must exactly match the
+            index's type.
+
+        Returns
+        -------
+        Series or DataFrame
+            Same type as caller, but with changed indices on each axis.
+
+        See Also
+        --------
+        DataFrame.set_index : Set row labels.
+        DataFrame.reset_index : Remove row labels or move them to new columns.
+        DataFrame.reindex : Change to new indices or expand indices.
+
+        Notes
+        -----
+        Same as calling
+        ``.reindex(index=other.index, columns=other.columns,...)``.
+
+        Examples
+        --------
+        >>> df1 = pd.DataFrame([[24.3, 75.7, 'high'],
+        ...                     [31, 87.8, 'high'],
+        ...                     [22, 71.6, 'medium'],
+        ...                     [35, 95, 'medium']],
+        ...                    columns=['temp_celsius', 'temp_fahrenheit',
+        ...                             'windspeed'],
+        ...                    index=pd.date_range(start='2014-02-12',
+        ...                                        end='2014-02-15', freq='D'))
+
+        >>> df1
+                    temp_celsius  temp_fahrenheit windspeed
+        2014-02-12          24.3             75.7      high
+        2014-02-13          31.0             87.8      high
+        2014-02-14          22.0             71.6    medium
+        2014-02-15          35.0             95.0    medium
+
+        >>> df2 = pd.DataFrame([[28, 'low'],
+        ...                     [30, 'low'],
+        ...                     [35.1, 'medium']],
+        ...                    columns=['temp_celsius', 'windspeed'],
+        ...                    index=pd.DatetimeIndex(['2014-02-12', '2014-02-13',
+        ...                                            '2014-02-15']))
+
+        >>> df2
+                    temp_celsius windspeed
+        2014-02-12          28.0       low
+        2014-02-13          30.0       low
+        2014-02-15          35.1    medium
+
+        >>> df2.reindex_like(df1)
+                    temp_celsius  temp_fahrenheit windspeed
+        2014-02-12          28.0              NaN       low
+        2014-02-13          30.0              NaN       low
+        2014-02-14           NaN              NaN       NaN
+        2014-02-15          35.1              NaN    medium
+        """
+        d = other._construct_axes_dict(
+            axes=self._AXIS_ORDERS,
+            method=method,
+            copy=copy,
+            limit=limit,
+            tolerance=tolerance,
+        )
+
+        return self.reindex(**d)
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: Literal[True],
+        errors: IgnoreRaise = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: Literal[False] = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: bool_t = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Self | None:
+        ...
+
+    def drop(
+        self,
+        labels: IndexLabel | None = None,
+        *,
+        axis: Axis = 0,
+        index: IndexLabel | None = None,
+        columns: IndexLabel | None = None,
+        level: Level | None = None,
+        inplace: bool_t = False,
+        errors: IgnoreRaise = "raise",
+    ) -> Self | None:
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if labels is not None:
+            if index is not None or columns is not None:
+                raise ValueError("Cannot specify both 'labels' and 'index'/'columns'")
+            axis_name = self._get_axis_name(axis)
+            axes = {axis_name: labels}
+        elif index is not None or columns is not None:
+            axes = {"index": index}
+            if self.ndim == 2:
+                axes["columns"] = columns
+        else:
+            raise ValueError(
+                "Need to specify at least one of 'labels', 'index' or 'columns'"
+            )
+
+        obj = self
+
+        for axis, labels in axes.items():
+            if labels is not None:
+                obj = obj._drop_axis(labels, axis, level=level, errors=errors)
+
+        if inplace:
+            self._update_inplace(obj)
+            return None
+        else:
+            return obj
+
+    @final
+    def _drop_axis(
+        self,
+        labels,
+        axis,
+        level=None,
+        errors: IgnoreRaise = "raise",
+        only_slice: bool_t = False,
+    ) -> Self:
+        """
+        Drop labels from specified axis. Used in the ``drop`` method
+        internally.
+
+        Parameters
+        ----------
+        labels : single label or list-like
+        axis : int or axis name
+        level : int or level name, default None
+            For MultiIndex
+        errors : {'ignore', 'raise'}, default 'raise'
+            If 'ignore', suppress error and existing labels are dropped.
+        only_slice : bool, default False
+            Whether indexing along columns should be view-only.
+
+        """
+        axis_num = self._get_axis_number(axis)
+        axis = self._get_axis(axis)
+
+        if axis.is_unique:
+            if level is not None:
+                if not isinstance(axis, MultiIndex):
+                    raise AssertionError("axis must be a MultiIndex")
+                new_axis = axis.drop(labels, level=level, errors=errors)
+            else:
+                new_axis = axis.drop(labels, errors=errors)
+            indexer = axis.get_indexer(new_axis)
+
+        # Case for non-unique axis
+        else:
+            is_tuple_labels = is_nested_list_like(labels) or isinstance(labels, tuple)
+            labels = ensure_object(common.index_labels_to_array(labels))
+            if level is not None:
+                if not isinstance(axis, MultiIndex):
+                    raise AssertionError("axis must be a MultiIndex")
+                mask = ~axis.get_level_values(level).isin(labels)
+
+                # GH 18561 MultiIndex.drop should raise if label is absent
+                if errors == "raise" and mask.all():
+                    raise KeyError(f"{labels} not found in axis")
+            elif (
+                isinstance(axis, MultiIndex)
+                and labels.dtype == "object"
+                and not is_tuple_labels
+            ):
+                # Set level to zero in case of MultiIndex and label is string,
+                #  because isin can't handle strings for MultiIndexes GH#36293
+                # In case of tuples we get dtype object but have to use isin GH#42771
+                mask = ~axis.get_level_values(0).isin(labels)
+            else:
+                mask = ~axis.isin(labels)
+                # Check if label doesn't exist along axis
+                labels_missing = (axis.get_indexer_for(labels) == -1).any()
+                if errors == "raise" and labels_missing:
+                    raise KeyError(f"{labels} not found in axis")
+
+            if isinstance(mask.dtype, ExtensionDtype):
+                # GH#45860
+                mask = mask.to_numpy(dtype=bool)
+
+            indexer = mask.nonzero()[0]
+            new_axis = axis.take(indexer)
+
+        bm_axis = self.ndim - axis_num - 1
+        new_mgr = self._mgr.reindex_indexer(
+            new_axis,
+            indexer,
+            axis=bm_axis,
+            allow_dups=True,
+            copy=None,
+            only_slice=only_slice,
+        )
+        result = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        if self.ndim == 1:
+            result._name = self.name
+
+        return result.__finalize__(self)
+
+    @final
+    def _update_inplace(self, result, verify_is_copy: bool_t = True) -> None:
+        """
+        Replace self internals with result.
+
+        Parameters
+        ----------
+        result : same type as self
+        verify_is_copy : bool, default True
+            Provide is_copy checks.
+        """
+        # NOTE: This does *not* call __finalize__ and that's an explicit
+        # decision that we may revisit in the future.
+        self._reset_cache()
+        self._clear_item_cache()
+        self._mgr = result._mgr
+        self._maybe_update_cacher(verify_is_copy=verify_is_copy, inplace=True)
+
+    @final
+    def add_prefix(self, prefix: str, axis: Axis | None = None) -> Self:
+        """
+        Prefix labels with string `prefix`.
+
+        For Series, the row labels are prefixed.
+        For DataFrame, the column labels are prefixed.
+
+        Parameters
+        ----------
+        prefix : str
+            The string to add before each label.
+        axis : {0 or 'index', 1 or 'columns', None}, default None
+            Axis to add prefix on
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        Series or DataFrame
+            New Series or DataFrame with updated labels.
+
+        See Also
+        --------
+        Series.add_suffix: Suffix row labels with string `suffix`.
+        DataFrame.add_suffix: Suffix column labels with string `suffix`.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: int64
+
+        >>> s.add_prefix('item_')
+        item_0    1
+        item_1    2
+        item_2    3
+        item_3    4
+        dtype: int64
+
+        >>> df = pd.DataFrame({'A': [1, 2, 3, 4], 'B': [3, 4, 5, 6]})
+        >>> df
+           A  B
+        0  1  3
+        1  2  4
+        2  3  5
+        3  4  6
+
+        >>> df.add_prefix('col_')
+             col_A  col_B
+        0       1       3
+        1       2       4
+        2       3       5
+        3       4       6
+        """
+        f = lambda x: f"{prefix}{x}"
+
+        axis_name = self._info_axis_name
+        if axis is not None:
+            axis_name = self._get_axis_name(axis)
+
+        mapper = {axis_name: f}
+
+        # error: Incompatible return value type (got "Optional[Self]",
+        # expected "Self")
+        # error: Argument 1 to "rename" of "NDFrame" has incompatible type
+        # "**Dict[str, partial[str]]"; expected "Union[str, int, None]"
+        # error: Keywords must be strings
+        return self._rename(**mapper)  # type: ignore[return-value, arg-type, misc]
+
+    @final
+    def add_suffix(self, suffix: str, axis: Axis | None = None) -> Self:
+        """
+        Suffix labels with string `suffix`.
+
+        For Series, the row labels are suffixed.
+        For DataFrame, the column labels are suffixed.
+
+        Parameters
+        ----------
+        suffix : str
+            The string to add after each label.
+        axis : {0 or 'index', 1 or 'columns', None}, default None
+            Axis to add suffix on
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        Series or DataFrame
+            New Series or DataFrame with updated labels.
+
+        See Also
+        --------
+        Series.add_prefix: Prefix row labels with string `prefix`.
+        DataFrame.add_prefix: Prefix column labels with string `prefix`.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s
+        0    1
+        1    2
+        2    3
+        3    4
+        dtype: int64
+
+        >>> s.add_suffix('_item')
+        0_item    1
+        1_item    2
+        2_item    3
+        3_item    4
+        dtype: int64
+
+        >>> df = pd.DataFrame({'A': [1, 2, 3, 4], 'B': [3, 4, 5, 6]})
+        >>> df
+           A  B
+        0  1  3
+        1  2  4
+        2  3  5
+        3  4  6
+
+        >>> df.add_suffix('_col')
+             A_col  B_col
+        0       1       3
+        1       2       4
+        2       3       5
+        3       4       6
+        """
+        f = lambda x: f"{x}{suffix}"
+
+        axis_name = self._info_axis_name
+        if axis is not None:
+            axis_name = self._get_axis_name(axis)
+
+        mapper = {axis_name: f}
+        # error: Incompatible return value type (got "Optional[Self]",
+        # expected "Self")
+        # error: Argument 1 to "rename" of "NDFrame" has incompatible type
+        # "**Dict[str, partial[str]]"; expected "Union[str, int, None]"
+        # error: Keywords must be strings
+        return self._rename(**mapper)  # type: ignore[return-value, arg-type, misc]
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool_t = ...,
+        key: ValueKeyFunc = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool_t = ...,
+        key: ValueKeyFunc = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: bool_t = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool_t = ...,
+        key: ValueKeyFunc = ...,
+    ) -> Self | None:
+        ...
+
+    def sort_values(
+        self,
+        *,
+        axis: Axis = 0,
+        ascending: bool_t | Sequence[bool_t] = True,
+        inplace: bool_t = False,
+        kind: SortKind = "quicksort",
+        na_position: NaPosition = "last",
+        ignore_index: bool_t = False,
+        key: ValueKeyFunc | None = None,
+    ) -> Self | None:
+        """
+        Sort by the values along either axis.
+
+        Parameters
+        ----------%(optional_by)s
+        axis : %(axes_single_arg)s, default 0
+             Axis to be sorted.
+        ascending : bool or list of bool, default True
+             Sort ascending vs. descending. Specify list for multiple sort
+             orders.  If this is a list of bools, must match the length of
+             the by.
+        inplace : bool, default False
+             If True, perform operation in-place.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+             Choice of sorting algorithm. See also :func:`numpy.sort` for more
+             information. `mergesort` and `stable` are the only stable algorithms. For
+             DataFrames, this option is only applied when sorting on a single
+             column or label.
+        na_position : {'first', 'last'}, default 'last'
+             Puts NaNs at the beginning if `first`; `last` puts NaNs at the
+             end.
+        ignore_index : bool, default False
+             If True, the resulting axis will be labeled 0, 1, …, n - 1.
+        key : callable, optional
+            Apply the key function to the values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect a
+            ``Series`` and return a Series with the same shape as the input.
+            It will be applied to each column in `by` independently.
+
+        Returns
+        -------
+        DataFrame or None
+            DataFrame with sorted values or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.sort_index : Sort a DataFrame by the index.
+        Series.sort_values : Similar method for a Series.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({
+        ...     'col1': ['A', 'A', 'B', np.nan, 'D', 'C'],
+        ...     'col2': [2, 1, 9, 8, 7, 4],
+        ...     'col3': [0, 1, 9, 4, 2, 3],
+        ...     'col4': ['a', 'B', 'c', 'D', 'e', 'F']
+        ... })
+        >>> df
+          col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+
+        Sort by col1
+
+        >>> df.sort_values(by=['col1'])
+          col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        5    C     4     3    F
+        4    D     7     2    e
+        3  NaN     8     4    D
+
+        Sort by multiple columns
+
+        >>> df.sort_values(by=['col1', 'col2'])
+          col1  col2  col3 col4
+        1    A     1     1    B
+        0    A     2     0    a
+        2    B     9     9    c
+        5    C     4     3    F
+        4    D     7     2    e
+        3  NaN     8     4    D
+
+        Sort Descending
+
+        >>> df.sort_values(by='col1', ascending=False)
+          col1  col2  col3 col4
+        4    D     7     2    e
+        5    C     4     3    F
+        2    B     9     9    c
+        0    A     2     0    a
+        1    A     1     1    B
+        3  NaN     8     4    D
+
+        Putting NAs first
+
+        >>> df.sort_values(by='col1', ascending=False, na_position='first')
+          col1  col2  col3 col4
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+        2    B     9     9    c
+        0    A     2     0    a
+        1    A     1     1    B
+
+        Sorting with a key function
+
+        >>> df.sort_values(by='col4', key=lambda col: col.str.lower())
+           col1  col2  col3 col4
+        0    A     2     0    a
+        1    A     1     1    B
+        2    B     9     9    c
+        3  NaN     8     4    D
+        4    D     7     2    e
+        5    C     4     3    F
+
+        Natural sort with the key argument,
+        using the `natsort ` package.
+
+        >>> df = pd.DataFrame({
+        ...    "time": ['0hr', '128hr', '72hr', '48hr', '96hr'],
+        ...    "value": [10, 20, 30, 40, 50]
+        ... })
+        >>> df
+            time  value
+        0    0hr     10
+        1  128hr     20
+        2   72hr     30
+        3   48hr     40
+        4   96hr     50
+        >>> from natsort import index_natsorted
+        >>> df.sort_values(
+        ...     by="time",
+        ...     key=lambda x: np.argsort(index_natsorted(df["time"]))
+        ... )
+            time  value
+        0    0hr     10
+        3   48hr     40
+        2   72hr     30
+        4   96hr     50
+        1  128hr     20
+        """
+        raise AbstractMethodError(self)
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool_t = ...,
+        ignore_index: bool_t = ...,
+        key: IndexKeyFunc = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool_t = ...,
+        ignore_index: bool_t = ...,
+        key: IndexKeyFunc = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool_t | Sequence[bool_t] = ...,
+        inplace: bool_t = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool_t = ...,
+        ignore_index: bool_t = ...,
+        key: IndexKeyFunc = ...,
+    ) -> Self | None:
+        ...
+
+    def sort_index(
+        self,
+        *,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        ascending: bool_t | Sequence[bool_t] = True,
+        inplace: bool_t = False,
+        kind: SortKind = "quicksort",
+        na_position: NaPosition = "last",
+        sort_remaining: bool_t = True,
+        ignore_index: bool_t = False,
+        key: IndexKeyFunc | None = None,
+    ) -> Self | None:
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        axis = self._get_axis_number(axis)
+        ascending = validate_ascending(ascending)
+
+        target = self._get_axis(axis)
+
+        indexer = get_indexer_indexer(
+            target, level, ascending, kind, na_position, sort_remaining, key
+        )
+
+        if indexer is None:
+            if inplace:
+                result = self
+            else:
+                result = self.copy(deep=None)
+
+            if ignore_index:
+                result.index = default_index(len(self))
+            if inplace:
+                return None
+            else:
+                return result
+
+        baxis = self._get_block_manager_axis(axis)
+        new_data = self._mgr.take(indexer, axis=baxis, verify=False)
+
+        # reconstruct axis if needed
+        if not ignore_index:
+            new_axis = new_data.axes[baxis]._sort_levels_monotonic()
+        else:
+            new_axis = default_index(len(indexer))
+        new_data.set_axis(baxis, new_axis)
+
+        result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="sort_index")
+
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        optional_reindex="",
+    )
+    def reindex(
+        self,
+        labels=None,
+        *,
+        index=None,
+        columns=None,
+        axis: Axis | None = None,
+        method: ReindexMethod | None = None,
+        copy: bool_t | None = None,
+        level: Level | None = None,
+        fill_value: Scalar | None = np.nan,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> Self:
+        """
+        Conform {klass} to new index with optional filling logic.
+
+        Places NA/NaN in locations having no value in the previous index. A new object
+        is produced unless the new index is equivalent to the current one and
+        ``copy=False``.
+
+        Parameters
+        ----------
+        {optional_reindex}
+        method : {{None, 'backfill'/'bfill', 'pad'/'ffill', 'nearest'}}
+            Method to use for filling holes in reindexed DataFrame.
+            Please note: this is only applicable to DataFrames/Series with a
+            monotonically increasing/decreasing index.
+
+            * None (default): don't fill gaps
+            * pad / ffill: Propagate last valid observation forward to next
+              valid.
+            * backfill / bfill: Use next valid observation to fill gap.
+            * nearest: Use nearest valid observations to fill gap.
+
+        copy : bool, default True
+            Return a new object, even if the passed indexes are the same.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        level : int or name
+            Broadcast across a level, matching Index values on the
+            passed MultiIndex level.
+        fill_value : scalar, default np.nan
+            Value to use for missing values. Defaults to NaN, but can be any
+            "compatible" value.
+        limit : int, default None
+            Maximum number of consecutive elements to forward or backward fill.
+        tolerance : optional
+            Maximum distance between original and new labels for inexact
+            matches. The values of the index at the matching locations most
+            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
+
+            Tolerance may be a scalar value, which applies the same tolerance
+            to all values, or list-like, which applies variable tolerance per
+            element. List-like includes list, tuple, array, Series, and must be
+            the same size as the index and its dtype must exactly match the
+            index's type.
+
+        Returns
+        -------
+        {klass} with changed index.
+
+        See Also
+        --------
+        DataFrame.set_index : Set row labels.
+        DataFrame.reset_index : Remove row labels or move them to new columns.
+        DataFrame.reindex_like : Change to same indices as other DataFrame.
+
+        Examples
+        --------
+        ``DataFrame.reindex`` supports two calling conventions
+
+        * ``(index=index_labels, columns=column_labels, ...)``
+        * ``(labels, axis={{'index', 'columns'}}, ...)``
+
+        We *highly* recommend using keyword arguments to clarify your
+        intent.
+
+        Create a dataframe with some fictional data.
+
+        >>> index = ['Firefox', 'Chrome', 'Safari', 'IE10', 'Konqueror']
+        >>> df = pd.DataFrame({{'http_status': [200, 200, 404, 404, 301],
+        ...                   'response_time': [0.04, 0.02, 0.07, 0.08, 1.0]}},
+        ...                   index=index)
+        >>> df
+                   http_status  response_time
+        Firefox            200           0.04
+        Chrome             200           0.02
+        Safari             404           0.07
+        IE10               404           0.08
+        Konqueror          301           1.00
+
+        Create a new index and reindex the dataframe. By default
+        values in the new index that do not have corresponding
+        records in the dataframe are assigned ``NaN``.
+
+        >>> new_index = ['Safari', 'Iceweasel', 'Comodo Dragon', 'IE10',
+        ...              'Chrome']
+        >>> df.reindex(new_index)
+                       http_status  response_time
+        Safari               404.0           0.07
+        Iceweasel              NaN            NaN
+        Comodo Dragon          NaN            NaN
+        IE10                 404.0           0.08
+        Chrome               200.0           0.02
+
+        We can fill in the missing values by passing a value to
+        the keyword ``fill_value``. Because the index is not monotonically
+        increasing or decreasing, we cannot use arguments to the keyword
+        ``method`` to fill the ``NaN`` values.
+
+        >>> df.reindex(new_index, fill_value=0)
+                       http_status  response_time
+        Safari                 404           0.07
+        Iceweasel                0           0.00
+        Comodo Dragon            0           0.00
+        IE10                   404           0.08
+        Chrome                 200           0.02
+
+        >>> df.reindex(new_index, fill_value='missing')
+                      http_status response_time
+        Safari                404          0.07
+        Iceweasel         missing       missing
+        Comodo Dragon     missing       missing
+        IE10                  404          0.08
+        Chrome                200          0.02
+
+        We can also reindex the columns.
+
+        >>> df.reindex(columns=['http_status', 'user_agent'])
+                   http_status  user_agent
+        Firefox            200         NaN
+        Chrome             200         NaN
+        Safari             404         NaN
+        IE10               404         NaN
+        Konqueror          301         NaN
+
+        Or we can use "axis-style" keyword arguments
+
+        >>> df.reindex(['http_status', 'user_agent'], axis="columns")
+                   http_status  user_agent
+        Firefox            200         NaN
+        Chrome             200         NaN
+        Safari             404         NaN
+        IE10               404         NaN
+        Konqueror          301         NaN
+
+        To further illustrate the filling functionality in
+        ``reindex``, we will create a dataframe with a
+        monotonically increasing index (for example, a sequence
+        of dates).
+
+        >>> date_index = pd.date_range('1/1/2010', periods=6, freq='D')
+        >>> df2 = pd.DataFrame({{"prices": [100, 101, np.nan, 100, 89, 88]}},
+        ...                    index=date_index)
+        >>> df2
+                    prices
+        2010-01-01   100.0
+        2010-01-02   101.0
+        2010-01-03     NaN
+        2010-01-04   100.0
+        2010-01-05    89.0
+        2010-01-06    88.0
+
+        Suppose we decide to expand the dataframe to cover a wider
+        date range.
+
+        >>> date_index2 = pd.date_range('12/29/2009', periods=10, freq='D')
+        >>> df2.reindex(date_index2)
+                    prices
+        2009-12-29     NaN
+        2009-12-30     NaN
+        2009-12-31     NaN
+        2010-01-01   100.0
+        2010-01-02   101.0
+        2010-01-03     NaN
+        2010-01-04   100.0
+        2010-01-05    89.0
+        2010-01-06    88.0
+        2010-01-07     NaN
+
+        The index entries that did not have a value in the original data frame
+        (for example, '2009-12-29') are by default filled with ``NaN``.
+        If desired, we can fill in the missing values using one of several
+        options.
+
+        For example, to back-propagate the last valid value to fill the ``NaN``
+        values, pass ``bfill`` as an argument to the ``method`` keyword.
+
+        >>> df2.reindex(date_index2, method='bfill')
+                    prices
+        2009-12-29   100.0
+        2009-12-30   100.0
+        2009-12-31   100.0
+        2010-01-01   100.0
+        2010-01-02   101.0
+        2010-01-03     NaN
+        2010-01-04   100.0
+        2010-01-05    89.0
+        2010-01-06    88.0
+        2010-01-07     NaN
+
+        Please note that the ``NaN`` value present in the original dataframe
+        (at index value 2010-01-03) will not be filled by any of the
+        value propagation schemes. This is because filling while reindexing
+        does not look at dataframe values, but only compares the original and
+        desired indexes. If you do want to fill in the ``NaN`` values present
+        in the original dataframe, use the ``fillna()`` method.
+
+        See the :ref:`user guide ` for more.
+        """
+        # TODO: Decide if we care about having different examples for different
+        # kinds
+
+        if index is not None and columns is not None and labels is not None:
+            raise TypeError("Cannot specify all of 'labels', 'index', 'columns'.")
+        elif index is not None or columns is not None:
+            if axis is not None:
+                raise TypeError(
+                    "Cannot specify both 'axis' and any of 'index' or 'columns'"
+                )
+            if labels is not None:
+                if index is not None:
+                    columns = labels
+                else:
+                    index = labels
+        else:
+            if axis and self._get_axis_number(axis) == 1:
+                columns = labels
+            else:
+                index = labels
+        axes: dict[Literal["index", "columns"], Any] = {
+            "index": index,
+            "columns": columns,
+        }
+        method = clean_reindex_fill_method(method)
+
+        # if all axes that are requested to reindex are equal, then only copy
+        # if indicated must have index names equal here as well as values
+        if copy and using_copy_on_write():
+            copy = False
+        if all(
+            self._get_axis(axis_name).identical(ax)
+            for axis_name, ax in axes.items()
+            if ax is not None
+        ):
+            return self.copy(deep=copy)
+
+        # check if we are a multi reindex
+        if self._needs_reindex_multi(axes, method, level):
+            return self._reindex_multi(axes, copy, fill_value)
+
+        # perform the reindex on the axes
+        return self._reindex_axes(
+            axes, level, limit, tolerance, method, fill_value, copy
+        ).__finalize__(self, method="reindex")
+
+    @final
+    def _reindex_axes(
+        self,
+        axes,
+        level: Level | None,
+        limit: int | None,
+        tolerance,
+        method,
+        fill_value: Scalar | None,
+        copy: bool_t | None,
+    ) -> Self:
+        """Perform the reindex for all the axes."""
+        obj = self
+        for a in self._AXIS_ORDERS:
+            labels = axes[a]
+            if labels is None:
+                continue
+
+            ax = self._get_axis(a)
+            new_index, indexer = ax.reindex(
+                labels, level=level, limit=limit, tolerance=tolerance, method=method
+            )
+
+            axis = self._get_axis_number(a)
+            obj = obj._reindex_with_indexers(
+                {axis: [new_index, indexer]},
+                fill_value=fill_value,
+                copy=copy,
+                allow_dups=False,
+            )
+            # If we've made a copy once, no need to make another one
+            copy = False
+
+        return obj
+
+    def _needs_reindex_multi(self, axes, method, level: Level | None) -> bool_t:
+        """Check if we do need a multi reindex."""
+        return (
+            (common.count_not_none(*axes.values()) == self._AXIS_LEN)
+            and method is None
+            and level is None
+            # reindex_multi calls self.values, so we only want to go
+            #  down that path when doing so is cheap.
+            and self._can_fast_transpose
+        )
+
+    def _reindex_multi(self, axes, copy, fill_value):
+        raise AbstractMethodError(self)
+
+    @final
+    def _reindex_with_indexers(
+        self,
+        reindexers,
+        fill_value=None,
+        copy: bool_t | None = False,
+        allow_dups: bool_t = False,
+    ) -> Self:
+        """allow_dups indicates an internal call here"""
+        # reindex doing multiple operations on different axes if indicated
+        new_data = self._mgr
+        for axis in sorted(reindexers.keys()):
+            index, indexer = reindexers[axis]
+            baxis = self._get_block_manager_axis(axis)
+
+            if index is None:
+                continue
+
+            index = ensure_index(index)
+            if indexer is not None:
+                indexer = ensure_platform_int(indexer)
+
+            # TODO: speed up on homogeneous DataFrame objects (see _reindex_multi)
+            new_data = new_data.reindex_indexer(
+                index,
+                indexer,
+                axis=baxis,
+                fill_value=fill_value,
+                allow_dups=allow_dups,
+                copy=copy,
+            )
+            # If we've made a copy once, no need to make another one
+            copy = False
+
+        if (
+            (copy or copy is None)
+            and new_data is self._mgr
+            and not using_copy_on_write()
+        ):
+            new_data = new_data.copy(deep=copy)
+        elif using_copy_on_write() and new_data is self._mgr:
+            new_data = new_data.copy(deep=False)
+
+        return self._constructor_from_mgr(new_data, axes=new_data.axes).__finalize__(
+            self
+        )
+
+    def filter(
+        self,
+        items=None,
+        like: str | None = None,
+        regex: str | None = None,
+        axis: Axis | None = None,
+    ) -> Self:
+        """
+        Subset the dataframe rows or columns according to the specified index labels.
+
+        Note that this routine does not filter a dataframe on its
+        contents. The filter is applied to the labels of the index.
+
+        Parameters
+        ----------
+        items : list-like
+            Keep labels from axis which are in items.
+        like : str
+            Keep labels from axis for which "like in label == True".
+        regex : str (regular expression)
+            Keep labels from axis for which re.search(regex, label) == True.
+        axis : {0 or 'index', 1 or 'columns', None}, default None
+            The axis to filter on, expressed either as an index (int)
+            or axis name (str). By default this is the info axis, 'columns' for
+            DataFrame. For `Series` this parameter is unused and defaults to `None`.
+
+        Returns
+        -------
+        same type as input object
+
+        See Also
+        --------
+        DataFrame.loc : Access a group of rows and columns
+            by label(s) or a boolean array.
+
+        Notes
+        -----
+        The ``items``, ``like``, and ``regex`` parameters are
+        enforced to be mutually exclusive.
+
+        ``axis`` defaults to the info axis that is used when indexing
+        with ``[]``.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(np.array(([1, 2, 3], [4, 5, 6])),
+        ...                   index=['mouse', 'rabbit'],
+        ...                   columns=['one', 'two', 'three'])
+        >>> df
+                one  two  three
+        mouse     1    2      3
+        rabbit    4    5      6
+
+        >>> # select columns by name
+        >>> df.filter(items=['one', 'three'])
+                 one  three
+        mouse     1      3
+        rabbit    4      6
+
+        >>> # select columns by regular expression
+        >>> df.filter(regex='e$', axis=1)
+                 one  three
+        mouse     1      3
+        rabbit    4      6
+
+        >>> # select rows containing 'bbi'
+        >>> df.filter(like='bbi', axis=0)
+                 one  two  three
+        rabbit    4    5      6
+        """
+        nkw = common.count_not_none(items, like, regex)
+        if nkw > 1:
+            raise TypeError(
+                "Keyword arguments `items`, `like`, or `regex` "
+                "are mutually exclusive"
+            )
+
+        if axis is None:
+            axis = self._info_axis_name
+        labels = self._get_axis(axis)
+
+        if items is not None:
+            name = self._get_axis_name(axis)
+            items = Index(items).intersection(labels)
+            if len(items) == 0:
+                # Keep the dtype of labels when we are empty
+                items = items.astype(labels.dtype)
+            # error: Keywords must be strings
+            return self.reindex(**{name: items})  # type: ignore[misc]
+        elif like:
+
+            def f(x) -> bool_t:
+                assert like is not None  # needed for mypy
+                return like in ensure_str(x)
+
+            values = labels.map(f)
+            return self.loc(axis=axis)[values]
+        elif regex:
+
+            def f(x) -> bool_t:
+                return matcher.search(ensure_str(x)) is not None
+
+            matcher = re.compile(regex)
+            values = labels.map(f)
+            return self.loc(axis=axis)[values]
+        else:
+            raise TypeError("Must pass either `items`, `like`, or `regex`")
+
+    @final
+    def head(self, n: int = 5) -> Self:
+        """
+        Return the first `n` rows.
+
+        This function returns the first `n` rows for the object based
+        on position. It is useful for quickly testing if your object
+        has the right type of data in it.
+
+        For negative values of `n`, this function returns all rows except
+        the last `|n|` rows, equivalent to ``df[:n]``.
+
+        If n is larger than the number of rows, this function returns all rows.
+
+        Parameters
+        ----------
+        n : int, default 5
+            Number of rows to select.
+
+        Returns
+        -------
+        same type as caller
+            The first `n` rows of the caller object.
+
+        See Also
+        --------
+        DataFrame.tail: Returns the last `n` rows.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'animal': ['alligator', 'bee', 'falcon', 'lion',
+        ...                    'monkey', 'parrot', 'shark', 'whale', 'zebra']})
+        >>> df
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+        3       lion
+        4     monkey
+        5     parrot
+        6      shark
+        7      whale
+        8      zebra
+
+        Viewing the first 5 lines
+
+        >>> df.head()
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+        3       lion
+        4     monkey
+
+        Viewing the first `n` lines (three in this case)
+
+        >>> df.head(3)
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+
+        For negative values of `n`
+
+        >>> df.head(-3)
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+        3       lion
+        4     monkey
+        5     parrot
+        """
+        if using_copy_on_write():
+            return self.iloc[:n].copy()
+        return self.iloc[:n]
+
+    @final
+    def tail(self, n: int = 5) -> Self:
+        """
+        Return the last `n` rows.
+
+        This function returns last `n` rows from the object based on
+        position. It is useful for quickly verifying data, for example,
+        after sorting or appending rows.
+
+        For negative values of `n`, this function returns all rows except
+        the first `|n|` rows, equivalent to ``df[|n|:]``.
+
+        If n is larger than the number of rows, this function returns all rows.
+
+        Parameters
+        ----------
+        n : int, default 5
+            Number of rows to select.
+
+        Returns
+        -------
+        type of caller
+            The last `n` rows of the caller object.
+
+        See Also
+        --------
+        DataFrame.head : The first `n` rows of the caller object.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'animal': ['alligator', 'bee', 'falcon', 'lion',
+        ...                    'monkey', 'parrot', 'shark', 'whale', 'zebra']})
+        >>> df
+              animal
+        0  alligator
+        1        bee
+        2     falcon
+        3       lion
+        4     monkey
+        5     parrot
+        6      shark
+        7      whale
+        8      zebra
+
+        Viewing the last 5 lines
+
+        >>> df.tail()
+           animal
+        4  monkey
+        5  parrot
+        6   shark
+        7   whale
+        8   zebra
+
+        Viewing the last `n` lines (three in this case)
+
+        >>> df.tail(3)
+          animal
+        6  shark
+        7  whale
+        8  zebra
+
+        For negative values of `n`
+
+        >>> df.tail(-3)
+           animal
+        3    lion
+        4  monkey
+        5  parrot
+        6   shark
+        7   whale
+        8   zebra
+        """
+        if using_copy_on_write():
+            if n == 0:
+                return self.iloc[0:0].copy()
+            return self.iloc[-n:].copy()
+        if n == 0:
+            return self.iloc[0:0]
+        return self.iloc[-n:]
+
+    @final
+    def sample(
+        self,
+        n: int | None = None,
+        frac: float | None = None,
+        replace: bool_t = False,
+        weights=None,
+        random_state: RandomState | None = None,
+        axis: Axis | None = None,
+        ignore_index: bool_t = False,
+    ) -> Self:
+        """
+        Return a random sample of items from an axis of object.
+
+        You can use `random_state` for reproducibility.
+
+        Parameters
+        ----------
+        n : int, optional
+            Number of items from axis to return. Cannot be used with `frac`.
+            Default = 1 if `frac` = None.
+        frac : float, optional
+            Fraction of axis items to return. Cannot be used with `n`.
+        replace : bool, default False
+            Allow or disallow sampling of the same row more than once.
+        weights : str or ndarray-like, optional
+            Default 'None' results in equal probability weighting.
+            If passed a Series, will align with target object on index. Index
+            values in weights not found in sampled object will be ignored and
+            index values in sampled object not in weights will be assigned
+            weights of zero.
+            If called on a DataFrame, will accept the name of a column
+            when axis = 0.
+            Unless weights are a Series, weights must be same length as axis
+            being sampled.
+            If weights do not sum to 1, they will be normalized to sum to 1.
+            Missing values in the weights column will be treated as zero.
+            Infinite values not allowed.
+        random_state : int, array-like, BitGenerator, np.random.RandomState, np.random.Generator, optional
+            If int, array-like, or BitGenerator, seed for random number generator.
+            If np.random.RandomState or np.random.Generator, use as given.
+
+            .. versionchanged:: 1.4.0
+
+                np.random.Generator objects now accepted
+
+        axis : {0 or 'index', 1 or 'columns', None}, default None
+            Axis to sample. Accepts axis number or name. Default is stat axis
+            for given data type. For `Series` this parameter is unused and defaults to `None`.
+        ignore_index : bool, default False
+            If True, the resulting index will be labeled 0, 1, …, n - 1.
+
+            .. versionadded:: 1.3.0
+
+        Returns
+        -------
+        Series or DataFrame
+            A new object of same type as caller containing `n` items randomly
+            sampled from the caller object.
+
+        See Also
+        --------
+        DataFrameGroupBy.sample: Generates random samples from each group of a
+            DataFrame object.
+        SeriesGroupBy.sample: Generates random samples from each group of a
+            Series object.
+        numpy.random.choice: Generates a random sample from a given 1-D numpy
+            array.
+
+        Notes
+        -----
+        If `frac` > 1, `replacement` should be set to `True`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'num_legs': [2, 4, 8, 0],
+        ...                    'num_wings': [2, 0, 0, 0],
+        ...                    'num_specimen_seen': [10, 2, 1, 8]},
+        ...                   index=['falcon', 'dog', 'spider', 'fish'])
+        >>> df
+                num_legs  num_wings  num_specimen_seen
+        falcon         2          2                 10
+        dog            4          0                  2
+        spider         8          0                  1
+        fish           0          0                  8
+
+        Extract 3 random elements from the ``Series`` ``df['num_legs']``:
+        Note that we use `random_state` to ensure the reproducibility of
+        the examples.
+
+        >>> df['num_legs'].sample(n=3, random_state=1)
+        fish      0
+        spider    8
+        falcon    2
+        Name: num_legs, dtype: int64
+
+        A random 50% sample of the ``DataFrame`` with replacement:
+
+        >>> df.sample(frac=0.5, replace=True, random_state=1)
+              num_legs  num_wings  num_specimen_seen
+        dog          4          0                  2
+        fish         0          0                  8
+
+        An upsample sample of the ``DataFrame`` with replacement:
+        Note that `replace` parameter has to be `True` for `frac` parameter > 1.
+
+        >>> df.sample(frac=2, replace=True, random_state=1)
+                num_legs  num_wings  num_specimen_seen
+        dog            4          0                  2
+        fish           0          0                  8
+        falcon         2          2                 10
+        falcon         2          2                 10
+        fish           0          0                  8
+        dog            4          0                  2
+        fish           0          0                  8
+        dog            4          0                  2
+
+        Using a DataFrame column as weights. Rows with larger value in the
+        `num_specimen_seen` column are more likely to be sampled.
+
+        >>> df.sample(n=2, weights='num_specimen_seen', random_state=1)
+                num_legs  num_wings  num_specimen_seen
+        falcon         2          2                 10
+        fish           0          0                  8
+        """  # noqa: E501
+        if axis is None:
+            axis = 0
+
+        axis = self._get_axis_number(axis)
+        obj_len = self.shape[axis]
+
+        # Process random_state argument
+        rs = common.random_state(random_state)
+
+        size = sample.process_sampling_size(n, frac, replace)
+        if size is None:
+            assert frac is not None
+            size = round(frac * obj_len)
+
+        if weights is not None:
+            weights = sample.preprocess_weights(self, weights, axis)
+
+        sampled_indices = sample.sample(obj_len, size, replace, weights, rs)
+        result = self.take(sampled_indices, axis=axis)
+
+        if ignore_index:
+            result.index = default_index(len(result))
+
+        return result
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def pipe(
+        self,
+        func: Callable[..., T] | tuple[Callable[..., T], str],
+        *args,
+        **kwargs,
+    ) -> T:
+        r"""
+        Apply chainable functions that expect Series or DataFrames.
+
+        Parameters
+        ----------
+        func : function
+            Function to apply to the {klass}.
+            ``args``, and ``kwargs`` are passed into ``func``.
+            Alternatively a ``(callable, data_keyword)`` tuple where
+            ``data_keyword`` is a string indicating the keyword of
+            ``callable`` that expects the {klass}.
+        *args : iterable, optional
+            Positional arguments passed into ``func``.
+        **kwargs : mapping, optional
+            A dictionary of keyword arguments passed into ``func``.
+
+        Returns
+        -------
+        the return type of ``func``.
+
+        See Also
+        --------
+        DataFrame.apply : Apply a function along input axis of DataFrame.
+        DataFrame.map : Apply a function elementwise on a whole DataFrame.
+        Series.map : Apply a mapping correspondence on a
+            :class:`~pandas.Series`.
+
+        Notes
+        -----
+        Use ``.pipe`` when chaining together functions that expect
+        Series, DataFrames or GroupBy objects.
+
+        Examples
+        --------
+        Constructing a income DataFrame from a dictionary.
+
+        >>> data = [[8000, 1000], [9500, np.nan], [5000, 2000]]
+        >>> df = pd.DataFrame(data, columns=['Salary', 'Others'])
+        >>> df
+           Salary  Others
+        0    8000  1000.0
+        1    9500     NaN
+        2    5000  2000.0
+
+        Functions that perform tax reductions on an income DataFrame.
+
+        >>> def subtract_federal_tax(df):
+        ...     return df * 0.9
+        >>> def subtract_state_tax(df, rate):
+        ...     return df * (1 - rate)
+        >>> def subtract_national_insurance(df, rate, rate_increase):
+        ...     new_rate = rate + rate_increase
+        ...     return df * (1 - new_rate)
+
+        Instead of writing
+
+        >>> subtract_national_insurance(
+        ...     subtract_state_tax(subtract_federal_tax(df), rate=0.12),
+        ...     rate=0.05,
+        ...     rate_increase=0.02)  # doctest: +SKIP
+
+        You can write
+
+        >>> (
+        ...     df.pipe(subtract_federal_tax)
+        ...     .pipe(subtract_state_tax, rate=0.12)
+        ...     .pipe(subtract_national_insurance, rate=0.05, rate_increase=0.02)
+        ... )
+            Salary   Others
+        0  5892.48   736.56
+        1  6997.32      NaN
+        2  3682.80  1473.12
+
+        If you have a function that takes the data as (say) the second
+        argument, pass a tuple indicating which keyword expects the
+        data. For example, suppose ``national_insurance`` takes its data as ``df``
+        in the second argument:
+
+        >>> def subtract_national_insurance(rate, df, rate_increase):
+        ...     new_rate = rate + rate_increase
+        ...     return df * (1 - new_rate)
+        >>> (
+        ...     df.pipe(subtract_federal_tax)
+        ...     .pipe(subtract_state_tax, rate=0.12)
+        ...     .pipe(
+        ...         (subtract_national_insurance, 'df'),
+        ...         rate=0.05,
+        ...         rate_increase=0.02
+        ...     )
+        ... )
+            Salary   Others
+        0  5892.48   736.56
+        1  6997.32      NaN
+        2  3682.80  1473.12
+        """
+        if using_copy_on_write():
+            return common.pipe(self.copy(deep=None), func, *args, **kwargs)
+        return common.pipe(self, func, *args, **kwargs)
+
+    # ----------------------------------------------------------------------
+    # Attribute access
+
+    @final
+    def __finalize__(self, other, method: str | None = None, **kwargs) -> Self:
+        """
+        Propagate metadata from other to self.
+
+        Parameters
+        ----------
+        other : the object from which to get the attributes that we are going
+            to propagate
+        method : str, optional
+            A passed method name providing context on where ``__finalize__``
+            was called.
+
+            .. warning::
+
+               The value passed as `method` are not currently considered
+               stable across pandas releases.
+        """
+        if isinstance(other, NDFrame):
+            if other.attrs:
+                # We want attrs propagation to have minimal performance
+                # impact if attrs are not used; i.e. attrs is an empty dict.
+                # One could make the deepcopy unconditionally, but a deepcopy
+                # of an empty dict is 50x more expensive than the empty check.
+                self.attrs = deepcopy(other.attrs)
+
+            self.flags.allows_duplicate_labels = other.flags.allows_duplicate_labels
+            # For subclasses using _metadata.
+            for name in set(self._metadata) & set(other._metadata):
+                assert isinstance(name, str)
+                object.__setattr__(self, name, getattr(other, name, None))
+
+        if method == "concat":
+            # propagate attrs only if all concat arguments have the same attrs
+            if all(bool(obj.attrs) for obj in other.objs):
+                # all concatenate arguments have non-empty attrs
+                attrs = other.objs[0].attrs
+                have_same_attrs = all(obj.attrs == attrs for obj in other.objs[1:])
+                if have_same_attrs:
+                    self.attrs = deepcopy(attrs)
+
+            allows_duplicate_labels = all(
+                x.flags.allows_duplicate_labels for x in other.objs
+            )
+            self.flags.allows_duplicate_labels = allows_duplicate_labels
+
+        return self
+
+    @final
+    def __getattr__(self, name: str):
+        """
+        After regular attribute access, try looking up the name
+        This allows simpler access to columns for interactive use.
+        """
+        # Note: obj.x will always call obj.__getattribute__('x') prior to
+        # calling obj.__getattr__('x').
+        if (
+            name not in self._internal_names_set
+            and name not in self._metadata
+            and name not in self._accessors
+            and self._info_axis._can_hold_identifiers_and_holds_name(name)
+        ):
+            return self[name]
+        return object.__getattribute__(self, name)
+
+    @final
+    def __setattr__(self, name: str, value) -> None:
+        """
+        After regular attribute access, try setting the name
+        This allows simpler access to columns for interactive use.
+        """
+        # first try regular attribute access via __getattribute__, so that
+        # e.g. ``obj.x`` and ``obj.x = 4`` will always reference/modify
+        # the same attribute.
+
+        try:
+            object.__getattribute__(self, name)
+            return object.__setattr__(self, name, value)
+        except AttributeError:
+            pass
+
+        # if this fails, go on to more involved attribute setting
+        # (note that this matches __getattr__, above).
+        if name in self._internal_names_set:
+            object.__setattr__(self, name, value)
+        elif name in self._metadata:
+            object.__setattr__(self, name, value)
+        else:
+            try:
+                existing = getattr(self, name)
+                if isinstance(existing, Index):
+                    object.__setattr__(self, name, value)
+                elif name in self._info_axis:
+                    self[name] = value
+                else:
+                    object.__setattr__(self, name, value)
+            except (AttributeError, TypeError):
+                if isinstance(self, ABCDataFrame) and (is_list_like(value)):
+                    warnings.warn(
+                        "Pandas doesn't allow columns to be "
+                        "created via a new attribute name - see "
+                        "https://pandas.pydata.org/pandas-docs/"
+                        "stable/indexing.html#attribute-access",
+                        stacklevel=find_stack_level(),
+                    )
+                object.__setattr__(self, name, value)
+
+    @final
+    def _dir_additions(self) -> set[str]:
+        """
+        add the string-like attributes from the info_axis.
+        If info_axis is a MultiIndex, its first level values are used.
+        """
+        additions = super()._dir_additions()
+        if self._info_axis._can_hold_strings:
+            additions.update(self._info_axis._dir_additions_for_owner)
+        return additions
+
+    # ----------------------------------------------------------------------
+    # Consolidation of internals
+
+    @final
+    def _protect_consolidate(self, f):
+        """
+        Consolidate _mgr -- if the blocks have changed, then clear the
+        cache
+        """
+        if isinstance(self._mgr, (ArrayManager, SingleArrayManager)):
+            return f()
+        blocks_before = len(self._mgr.blocks)
+        result = f()
+        if len(self._mgr.blocks) != blocks_before:
+            self._clear_item_cache()
+        return result
+
+    @final
+    def _consolidate_inplace(self) -> None:
+        """Consolidate data in place and return None"""
+
+        def f() -> None:
+            self._mgr = self._mgr.consolidate()
+
+        self._protect_consolidate(f)
+
+    @final
+    def _consolidate(self):
+        """
+        Compute NDFrame with "consolidated" internals (data of each dtype
+        grouped together in a single ndarray).
+
+        Returns
+        -------
+        consolidated : same type as caller
+        """
+        f = lambda: self._mgr.consolidate()
+        cons_data = self._protect_consolidate(f)
+        return self._constructor_from_mgr(cons_data, axes=cons_data.axes).__finalize__(
+            self
+        )
+
+    @final
+    @property
+    def _is_mixed_type(self) -> bool_t:
+        if self._mgr.is_single_block:
+            # Includes all Series cases
+            return False
+
+        if self._mgr.any_extension_types:
+            # Even if they have the same dtype, we can't consolidate them,
+            #  so we pretend this is "mixed'"
+            return True
+
+        return self.dtypes.nunique() > 1
+
+    @final
+    def _get_numeric_data(self) -> Self:
+        new_mgr = self._mgr.get_numeric_data()
+        return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(self)
+
+    @final
+    def _get_bool_data(self):
+        new_mgr = self._mgr.get_bool_data()
+        return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(self)
+
+    # ----------------------------------------------------------------------
+    # Internal Interface Methods
+
+    @property
+    def values(self):
+        raise AbstractMethodError(self)
+
+    @property
+    def _values(self) -> ArrayLike:
+        """internal implementation"""
+        raise AbstractMethodError(self)
+
+    @property
+    def dtypes(self):
+        """
+        Return the dtypes in the DataFrame.
+
+        This returns a Series with the data type of each column.
+        The result's index is the original DataFrame's columns. Columns
+        with mixed types are stored with the ``object`` dtype. See
+        :ref:`the User Guide ` for more.
+
+        Returns
+        -------
+        pandas.Series
+            The data type of each column.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'float': [1.0],
+        ...                    'int': [1],
+        ...                    'datetime': [pd.Timestamp('20180310')],
+        ...                    'string': ['foo']})
+        >>> df.dtypes
+        float              float64
+        int                  int64
+        datetime    datetime64[ns]
+        string              object
+        dtype: object
+        """
+        data = self._mgr.get_dtypes()
+        return self._constructor_sliced(data, index=self._info_axis, dtype=np.object_)
+
+    @final
+    def astype(
+        self, dtype, copy: bool_t | None = None, errors: IgnoreRaise = "raise"
+    ) -> Self:
+        """
+        Cast a pandas object to a specified dtype ``dtype``.
+
+        Parameters
+        ----------
+        dtype : str, data type, Series or Mapping of column name -> data type
+            Use a str, numpy.dtype, pandas.ExtensionDtype or Python type to
+            cast entire pandas object to the same type. Alternatively, use a
+            mapping, e.g. {col: dtype, ...}, where col is a column label and dtype is
+            a numpy.dtype or Python type to cast one or more of the DataFrame's
+            columns to column-specific types.
+        copy : bool, default True
+            Return a copy when ``copy=True`` (be very careful setting
+            ``copy=False`` as changes to values then may propagate to other
+            pandas objects).
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        errors : {'raise', 'ignore'}, default 'raise'
+            Control raising of exceptions on invalid data for provided dtype.
+
+            - ``raise`` : allow exceptions to be raised
+            - ``ignore`` : suppress exceptions. On error return original object.
+
+        Returns
+        -------
+        same type as caller
+
+        See Also
+        --------
+        to_datetime : Convert argument to datetime.
+        to_timedelta : Convert argument to timedelta.
+        to_numeric : Convert argument to a numeric type.
+        numpy.ndarray.astype : Cast a numpy array to a specified type.
+
+        Notes
+        -----
+        .. versionchanged:: 2.0.0
+
+            Using ``astype`` to convert from timezone-naive dtype to
+            timezone-aware dtype will raise an exception.
+            Use :meth:`Series.dt.tz_localize` instead.
+
+        Examples
+        --------
+        Create a DataFrame:
+
+        >>> d = {'col1': [1, 2], 'col2': [3, 4]}
+        >>> df = pd.DataFrame(data=d)
+        >>> df.dtypes
+        col1    int64
+        col2    int64
+        dtype: object
+
+        Cast all columns to int32:
+
+        >>> df.astype('int32').dtypes
+        col1    int32
+        col2    int32
+        dtype: object
+
+        Cast col1 to int32 using a dictionary:
+
+        >>> df.astype({'col1': 'int32'}).dtypes
+        col1    int32
+        col2    int64
+        dtype: object
+
+        Create a series:
+
+        >>> ser = pd.Series([1, 2], dtype='int32')
+        >>> ser
+        0    1
+        1    2
+        dtype: int32
+        >>> ser.astype('int64')
+        0    1
+        1    2
+        dtype: int64
+
+        Convert to categorical type:
+
+        >>> ser.astype('category')
+        0    1
+        1    2
+        dtype: category
+        Categories (2, int32): [1, 2]
+
+        Convert to ordered categorical type with custom ordering:
+
+        >>> from pandas.api.types import CategoricalDtype
+        >>> cat_dtype = CategoricalDtype(
+        ...     categories=[2, 1], ordered=True)
+        >>> ser.astype(cat_dtype)
+        0    1
+        1    2
+        dtype: category
+        Categories (2, int64): [2 < 1]
+
+        Create a series of dates:
+
+        >>> ser_date = pd.Series(pd.date_range('20200101', periods=3))
+        >>> ser_date
+        0   2020-01-01
+        1   2020-01-02
+        2   2020-01-03
+        dtype: datetime64[ns]
+        """
+        if copy and using_copy_on_write():
+            copy = False
+
+        if is_dict_like(dtype):
+            if self.ndim == 1:  # i.e. Series
+                if len(dtype) > 1 or self.name not in dtype:
+                    raise KeyError(
+                        "Only the Series name can be used for "
+                        "the key in Series dtype mappings."
+                    )
+                new_type = dtype[self.name]
+                return self.astype(new_type, copy, errors)
+
+            # GH#44417 cast to Series so we can use .iat below, which will be
+            #  robust in case we
+            from pandas import Series
+
+            dtype_ser = Series(dtype, dtype=object)
+
+            for col_name in dtype_ser.index:
+                if col_name not in self:
+                    raise KeyError(
+                        "Only a column name can be used for the "
+                        "key in a dtype mappings argument. "
+                        f"'{col_name}' not found in columns."
+                    )
+
+            dtype_ser = dtype_ser.reindex(self.columns, fill_value=None, copy=False)
+
+            results = []
+            for i, (col_name, col) in enumerate(self.items()):
+                cdt = dtype_ser.iat[i]
+                if isna(cdt):
+                    res_col = col.copy(deep=copy)
+                else:
+                    try:
+                        res_col = col.astype(dtype=cdt, copy=copy, errors=errors)
+                    except ValueError as ex:
+                        ex.args = (
+                            f"{ex}: Error while type casting for column '{col_name}'",
+                        )
+                        raise
+                results.append(res_col)
+
+        elif is_extension_array_dtype(dtype) and self.ndim > 1:
+            # TODO(EA2D): special case not needed with 2D EAs
+            dtype = pandas_dtype(dtype)
+            if isinstance(dtype, ExtensionDtype) and all(
+                arr.dtype == dtype for arr in self._mgr.arrays
+            ):
+                return self.copy(deep=copy)
+            # GH 18099/22869: columnwise conversion to extension dtype
+            # GH 24704: self.items handles duplicate column names
+            results = [
+                ser.astype(dtype, copy=copy, errors=errors) for _, ser in self.items()
+            ]
+
+        else:
+            # else, only a single dtype is given
+            new_data = self._mgr.astype(dtype=dtype, copy=copy, errors=errors)
+            res = self._constructor_from_mgr(new_data, axes=new_data.axes)
+            return res.__finalize__(self, method="astype")
+
+        # GH 33113: handle empty frame or series
+        if not results:
+            return self.copy(deep=None)
+
+        # GH 19920: retain column metadata after concat
+        result = concat(results, axis=1, copy=False)
+        # GH#40810 retain subclass
+        # error: Incompatible types in assignment
+        # (expression has type "Self", variable has type "DataFrame")
+        result = self._constructor(result)  # type: ignore[assignment]
+        result.columns = self.columns
+        result = result.__finalize__(self, method="astype")
+        # https://github.com/python/mypy/issues/8354
+        return cast(Self, result)
+
+    @final
+    def copy(self, deep: bool_t | None = True) -> Self:
+        """
+        Make a copy of this object's indices and data.
+
+        When ``deep=True`` (default), a new object will be created with a
+        copy of the calling object's data and indices. Modifications to
+        the data or indices of the copy will not be reflected in the
+        original object (see notes below).
+
+        When ``deep=False``, a new object will be created without copying
+        the calling object's data or index (only references to the data
+        and index are copied). Any changes to the data of the original
+        will be reflected in the shallow copy (and vice versa).
+
+        .. note::
+            The ``deep=False`` behaviour as described above will change
+            in pandas 3.0. `Copy-on-Write
+            `__
+            will be enabled by default, which means that the "shallow" copy
+            is that is returned with ``deep=False`` will still avoid making
+            an eager copy, but changes to the data of the original will *no*
+            longer be reflected in the shallow copy (or vice versa). Instead,
+            it makes use of a lazy (deferred) copy mechanism that will copy
+            the data only when any changes to the original or shallow copy is
+            made.
+
+            You can already get the future behavior and improvements through
+            enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Parameters
+        ----------
+        deep : bool, default True
+            Make a deep copy, including a copy of the data and the indices.
+            With ``deep=False`` neither the indices nor the data are copied.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object type matches caller.
+
+        Notes
+        -----
+        When ``deep=True``, data is copied but actual Python objects
+        will not be copied recursively, only the reference to the object.
+        This is in contrast to `copy.deepcopy` in the Standard Library,
+        which recursively copies object data (see examples below).
+
+        While ``Index`` objects are copied when ``deep=True``, the underlying
+        numpy array is not copied for performance reasons. Since ``Index`` is
+        immutable, the underlying data can be safely shared and a copy
+        is not needed.
+
+        Since pandas is not thread safe, see the
+        :ref:`gotchas ` when copying in a threading
+        environment.
+
+        When ``copy_on_write`` in pandas config is set to ``True``, the
+        ``copy_on_write`` config takes effect even when ``deep=False``.
+        This means that any changes to the copied data would make a new copy
+        of the data upon write (and vice versa). Changes made to either the
+        original or copied variable would not be reflected in the counterpart.
+        See :ref:`Copy_on_Write ` for more information.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2], index=["a", "b"])
+        >>> s
+        a    1
+        b    2
+        dtype: int64
+
+        >>> s_copy = s.copy()
+        >>> s_copy
+        a    1
+        b    2
+        dtype: int64
+
+        **Shallow copy versus default (deep) copy:**
+
+        >>> s = pd.Series([1, 2], index=["a", "b"])
+        >>> deep = s.copy()
+        >>> shallow = s.copy(deep=False)
+
+        Shallow copy shares data and index with original.
+
+        >>> s is shallow
+        False
+        >>> s.values is shallow.values and s.index is shallow.index
+        True
+
+        Deep copy has own copy of data and index.
+
+        >>> s is deep
+        False
+        >>> s.values is deep.values or s.index is deep.index
+        False
+
+        Updates to the data shared by shallow copy and original is reflected
+        in both (NOTE: this will no longer be true for pandas >= 3.0);
+        deep copy remains unchanged.
+
+        >>> s.iloc[0] = 3
+        >>> shallow.iloc[1] = 4
+        >>> s
+        a    3
+        b    4
+        dtype: int64
+        >>> shallow
+        a    3
+        b    4
+        dtype: int64
+        >>> deep
+        a    1
+        b    2
+        dtype: int64
+
+        Note that when copying an object containing Python objects, a deep copy
+        will copy the data, but will not do so recursively. Updating a nested
+        data object will be reflected in the deep copy.
+
+        >>> s = pd.Series([[1, 2], [3, 4]])
+        >>> deep = s.copy()
+        >>> s[0][0] = 10
+        >>> s
+        0    [10, 2]
+        1     [3, 4]
+        dtype: object
+        >>> deep
+        0    [10, 2]
+        1     [3, 4]
+        dtype: object
+
+        **Copy-on-Write is set to true**, the shallow copy is not modified
+        when the original data is changed:
+
+        >>> with pd.option_context("mode.copy_on_write", True):
+        ...     s = pd.Series([1, 2], index=["a", "b"])
+        ...     copy = s.copy(deep=False)
+        ...     s.iloc[0] = 100
+        ...     s
+        a    100
+        b      2
+        dtype: int64
+        >>> copy
+        a    1
+        b    2
+        dtype: int64
+        """
+        data = self._mgr.copy(deep=deep)
+        self._clear_item_cache()
+        return self._constructor_from_mgr(data, axes=data.axes).__finalize__(
+            self, method="copy"
+        )
+
+    @final
+    def __copy__(self, deep: bool_t = True) -> Self:
+        return self.copy(deep=deep)
+
+    @final
+    def __deepcopy__(self, memo=None) -> Self:
+        """
+        Parameters
+        ----------
+        memo, default None
+            Standard signature. Unused
+        """
+        return self.copy(deep=True)
+
+    @final
+    def infer_objects(self, copy: bool_t | None = None) -> Self:
+        """
+        Attempt to infer better dtypes for object columns.
+
+        Attempts soft conversion of object-dtyped
+        columns, leaving non-object and unconvertible
+        columns unchanged. The inference rules are the
+        same as during normal Series/DataFrame construction.
+
+        Parameters
+        ----------
+        copy : bool, default True
+            Whether to make a copy for non-object or non-inferable columns
+            or Series.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        same type as input object
+
+        See Also
+        --------
+        to_datetime : Convert argument to datetime.
+        to_timedelta : Convert argument to timedelta.
+        to_numeric : Convert argument to numeric type.
+        convert_dtypes : Convert argument to best possible dtype.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"A": ["a", 1, 2, 3]})
+        >>> df = df.iloc[1:]
+        >>> df
+           A
+        1  1
+        2  2
+        3  3
+
+        >>> df.dtypes
+        A    object
+        dtype: object
+
+        >>> df.infer_objects().dtypes
+        A    int64
+        dtype: object
+        """
+        new_mgr = self._mgr.convert(copy=copy)
+        res = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        return res.__finalize__(self, method="infer_objects")
+
+    @final
+    def convert_dtypes(
+        self,
+        infer_objects: bool_t = True,
+        convert_string: bool_t = True,
+        convert_integer: bool_t = True,
+        convert_boolean: bool_t = True,
+        convert_floating: bool_t = True,
+        dtype_backend: DtypeBackend = "numpy_nullable",
+    ) -> Self:
+        """
+        Convert columns to the best possible dtypes using dtypes supporting ``pd.NA``.
+
+        Parameters
+        ----------
+        infer_objects : bool, default True
+            Whether object dtypes should be converted to the best possible types.
+        convert_string : bool, default True
+            Whether object dtypes should be converted to ``StringDtype()``.
+        convert_integer : bool, default True
+            Whether, if possible, conversion can be done to integer extension types.
+        convert_boolean : bool, defaults True
+            Whether object dtypes should be converted to ``BooleanDtypes()``.
+        convert_floating : bool, defaults True
+            Whether, if possible, conversion can be done to floating extension types.
+            If `convert_integer` is also True, preference will be give to integer
+            dtypes if the floats can be faithfully casted to integers.
+        dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+            Back-end data type applied to the resultant :class:`DataFrame`
+            (still experimental). Behaviour is as follows:
+
+            * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+              (default).
+            * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+              DataFrame.
+
+            .. versionadded:: 2.0
+
+        Returns
+        -------
+        Series or DataFrame
+            Copy of input object with new dtype.
+
+        See Also
+        --------
+        infer_objects : Infer dtypes of objects.
+        to_datetime : Convert argument to datetime.
+        to_timedelta : Convert argument to timedelta.
+        to_numeric : Convert argument to a numeric type.
+
+        Notes
+        -----
+        By default, ``convert_dtypes`` will attempt to convert a Series (or each
+        Series in a DataFrame) to dtypes that support ``pd.NA``. By using the options
+        ``convert_string``, ``convert_integer``, ``convert_boolean`` and
+        ``convert_floating``, it is possible to turn off individual conversions
+        to ``StringDtype``, the integer extension types, ``BooleanDtype``
+        or floating extension types, respectively.
+
+        For object-dtyped columns, if ``infer_objects`` is ``True``, use the inference
+        rules as during normal Series/DataFrame construction.  Then, if possible,
+        convert to ``StringDtype``, ``BooleanDtype`` or an appropriate integer
+        or floating extension type, otherwise leave as ``object``.
+
+        If the dtype is integer, convert to an appropriate integer extension type.
+
+        If the dtype is numeric, and consists of all integers, convert to an
+        appropriate integer extension type. Otherwise, convert to an
+        appropriate floating extension type.
+
+        In the future, as new dtypes are added that support ``pd.NA``, the results
+        of this method will change to support those new dtypes.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         "a": pd.Series([1, 2, 3], dtype=np.dtype("int32")),
+        ...         "b": pd.Series(["x", "y", "z"], dtype=np.dtype("O")),
+        ...         "c": pd.Series([True, False, np.nan], dtype=np.dtype("O")),
+        ...         "d": pd.Series(["h", "i", np.nan], dtype=np.dtype("O")),
+        ...         "e": pd.Series([10, np.nan, 20], dtype=np.dtype("float")),
+        ...         "f": pd.Series([np.nan, 100.5, 200], dtype=np.dtype("float")),
+        ...     }
+        ... )
+
+        Start with a DataFrame with default dtypes.
+
+        >>> df
+           a  b      c    d     e      f
+        0  1  x   True    h  10.0    NaN
+        1  2  y  False    i   NaN  100.5
+        2  3  z    NaN  NaN  20.0  200.0
+
+        >>> df.dtypes
+        a      int32
+        b     object
+        c     object
+        d     object
+        e    float64
+        f    float64
+        dtype: object
+
+        Convert the DataFrame to use best possible dtypes.
+
+        >>> dfn = df.convert_dtypes()
+        >>> dfn
+           a  b      c     d     e      f
+        0  1  x   True     h    10   
+        1  2  y  False     i    100.5
+        2  3  z         20  200.0
+
+        >>> dfn.dtypes
+        a             Int32
+        b    string[python]
+        c           boolean
+        d    string[python]
+        e             Int64
+        f           Float64
+        dtype: object
+
+        Start with a Series of strings and missing data represented by ``np.nan``.
+
+        >>> s = pd.Series(["a", "b", np.nan])
+        >>> s
+        0      a
+        1      b
+        2    NaN
+        dtype: object
+
+        Obtain a Series with dtype ``StringDtype``.
+
+        >>> s.convert_dtypes()
+        0       a
+        1       b
+        2    
+        dtype: string
+        """
+        check_dtype_backend(dtype_backend)
+        new_mgr = self._mgr.convert_dtypes(  # type: ignore[union-attr]
+            infer_objects=infer_objects,
+            convert_string=convert_string,
+            convert_integer=convert_integer,
+            convert_boolean=convert_boolean,
+            convert_floating=convert_floating,
+            dtype_backend=dtype_backend,
+        )
+        res = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        return res.__finalize__(self, method="convert_dtypes")
+
+    # ----------------------------------------------------------------------
+    # Filling NA's
+
+    def _deprecate_downcast(self, downcast, method_name: str):
+        # GH#40988
+        if downcast is not lib.no_default:
+            warnings.warn(
+                f"The 'downcast' keyword in {method_name} is deprecated and "
+                "will be removed in a future version. Use "
+                "res.infer_objects(copy=False) to infer non-object dtype, or "
+                "pd.to_numeric with the 'downcast' keyword to downcast numeric "
+                "results.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            downcast = None
+        return downcast
+
+    @final
+    def _pad_or_backfill(
+        self,
+        method: Literal["ffill", "bfill", "pad", "backfill"],
+        *,
+        axis: None | Axis = None,
+        inplace: bool_t = False,
+        limit: None | int = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: dict | None = None,
+    ):
+        if axis is None:
+            axis = 0
+        axis = self._get_axis_number(axis)
+        method = clean_fill_method(method)
+
+        if not self._mgr.is_single_block and axis == 1:
+            # e.g. test_align_fill_method
+            # TODO(3.0): once downcast is removed, we can do the .T
+            #  in all axis=1 cases, and remove axis kward from mgr.pad_or_backfill.
+            if inplace:
+                raise NotImplementedError()
+            result = self.T._pad_or_backfill(
+                method=method, limit=limit, limit_area=limit_area
+            ).T
+
+            return result
+
+        new_mgr = self._mgr.pad_or_backfill(
+            method=method,
+            axis=self._get_block_manager_axis(axis),
+            limit=limit,
+            limit_area=limit_area,
+            inplace=inplace,
+            downcast=downcast,
+        )
+        result = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="fillna")
+
+    @overload
+    def fillna(
+        self,
+        value: Hashable | Mapping | Series | DataFrame = ...,
+        *,
+        method: FillnaOptions | None = ...,
+        axis: Axis | None = ...,
+        inplace: Literal[False] = ...,
+        limit: int | None = ...,
+        downcast: dict | None = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def fillna(
+        self,
+        value: Hashable | Mapping | Series | DataFrame = ...,
+        *,
+        method: FillnaOptions | None = ...,
+        axis: Axis | None = ...,
+        inplace: Literal[True],
+        limit: int | None = ...,
+        downcast: dict | None = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def fillna(
+        self,
+        value: Hashable | Mapping | Series | DataFrame = ...,
+        *,
+        method: FillnaOptions | None = ...,
+        axis: Axis | None = ...,
+        inplace: bool_t = ...,
+        limit: int | None = ...,
+        downcast: dict | None = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+    )
+    def fillna(
+        self,
+        value: Hashable | Mapping | Series | DataFrame | None = None,
+        *,
+        method: FillnaOptions | None = None,
+        axis: Axis | None = None,
+        inplace: bool_t = False,
+        limit: int | None = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        """
+        Fill NA/NaN values using the specified method.
+
+        Parameters
+        ----------
+        value : scalar, dict, Series, or DataFrame
+            Value to use to fill holes (e.g. 0), alternately a
+            dict/Series/DataFrame of values specifying which value to use for
+            each index (for a Series) or column (for a DataFrame).  Values not
+            in the dict/Series/DataFrame will not be filled. This value cannot
+            be a list.
+        method : {{'backfill', 'bfill', 'ffill', None}}, default None
+            Method to use for filling holes in reindexed Series:
+
+            * ffill: propagate last valid observation forward to next valid.
+            * backfill / bfill: use next valid observation to fill gap.
+
+            .. deprecated:: 2.1.0
+                Use ffill or bfill instead.
+
+        axis : {axes_single_arg}
+            Axis along which to fill missing values. For `Series`
+            this parameter is unused and defaults to 0.
+        inplace : bool, default False
+            If True, fill in-place. Note: this will modify any
+            other views on this object (e.g., a no-copy slice for a column in a
+            DataFrame).
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+            .. deprecated:: 2.2.0
+
+        Returns
+        -------
+        {klass} or None
+            Object with missing values filled or None if ``inplace=True``.
+
+        See Also
+        --------
+        ffill : Fill values by propagating the last valid observation to next valid.
+        bfill : Fill values by using the next valid observation to fill the gap.
+        interpolate : Fill NaN values using interpolation.
+        reindex : Conform object to new index.
+        asfreq : Convert TimeSeries to specified frequency.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[np.nan, 2, np.nan, 0],
+        ...                    [3, 4, np.nan, 1],
+        ...                    [np.nan, np.nan, np.nan, np.nan],
+        ...                    [np.nan, 3, np.nan, 4]],
+        ...                   columns=list("ABCD"))
+        >>> df
+             A    B   C    D
+        0  NaN  2.0 NaN  0.0
+        1  3.0  4.0 NaN  1.0
+        2  NaN  NaN NaN  NaN
+        3  NaN  3.0 NaN  4.0
+
+        Replace all NaN elements with 0s.
+
+        >>> df.fillna(0)
+             A    B    C    D
+        0  0.0  2.0  0.0  0.0
+        1  3.0  4.0  0.0  1.0
+        2  0.0  0.0  0.0  0.0
+        3  0.0  3.0  0.0  4.0
+
+        Replace all NaN elements in column 'A', 'B', 'C', and 'D', with 0, 1,
+        2, and 3 respectively.
+
+        >>> values = {{"A": 0, "B": 1, "C": 2, "D": 3}}
+        >>> df.fillna(value=values)
+             A    B    C    D
+        0  0.0  2.0  2.0  0.0
+        1  3.0  4.0  2.0  1.0
+        2  0.0  1.0  2.0  3.0
+        3  0.0  3.0  2.0  4.0
+
+        Only replace the first NaN element.
+
+        >>> df.fillna(value=values, limit=1)
+             A    B    C    D
+        0  0.0  2.0  2.0  0.0
+        1  3.0  4.0  NaN  1.0
+        2  NaN  1.0  NaN  3.0
+        3  NaN  3.0  NaN  4.0
+
+        When filling using a DataFrame, replacement happens along
+        the same column names and same indices
+
+        >>> df2 = pd.DataFrame(np.zeros((4, 4)), columns=list("ABCE"))
+        >>> df.fillna(df2)
+             A    B    C    D
+        0  0.0  2.0  0.0  0.0
+        1  3.0  4.0  0.0  1.0
+        2  0.0  0.0  0.0  NaN
+        3  0.0  3.0  0.0  4.0
+
+        Note that column D is not affected since it is not present in df2.
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and _check_cacher(self):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        value, method = validate_fillna_kwargs(value, method)
+        if method is not None:
+            warnings.warn(
+                f"{type(self).__name__}.fillna with 'method' is deprecated and "
+                "will raise in a future version. Use obj.ffill() or obj.bfill() "
+                "instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        was_no_default = downcast is lib.no_default
+        downcast = self._deprecate_downcast(downcast, "fillna")
+
+        # set the default here, so functions examining the signaure
+        # can detect if something was set (e.g. in groupby) (GH9221)
+        if axis is None:
+            axis = 0
+        axis = self._get_axis_number(axis)
+
+        if value is None:
+            return self._pad_or_backfill(
+                # error: Argument 1 to "_pad_or_backfill" of "NDFrame" has
+                # incompatible type "Optional[Literal['backfill', 'bfill', 'ffill',
+                # 'pad']]"; expected "Literal['ffill', 'bfill', 'pad', 'backfill']"
+                method,  # type: ignore[arg-type]
+                axis=axis,
+                limit=limit,
+                inplace=inplace,
+                # error: Argument "downcast" to "_fillna_with_method" of "NDFrame"
+                # has incompatible type "Union[Dict[Any, Any], None,
+                # Literal[_NoDefault.no_default]]"; expected
+                # "Optional[Dict[Any, Any]]"
+                downcast=downcast,  # type: ignore[arg-type]
+            )
+        else:
+            if self.ndim == 1:
+                if isinstance(value, (dict, ABCSeries)):
+                    if not len(value):
+                        # test_fillna_nonscalar
+                        if inplace:
+                            return None
+                        return self.copy(deep=None)
+                    from pandas import Series
+
+                    value = Series(value)
+                    value = value.reindex(self.index, copy=False)
+                    value = value._values
+                elif not is_list_like(value):
+                    pass
+                else:
+                    raise TypeError(
+                        '"value" parameter must be a scalar, dict '
+                        "or Series, but you passed a "
+                        f'"{type(value).__name__}"'
+                    )
+
+                new_data = self._mgr.fillna(
+                    value=value, limit=limit, inplace=inplace, downcast=downcast
+                )
+
+            elif isinstance(value, (dict, ABCSeries)):
+                if axis == 1:
+                    raise NotImplementedError(
+                        "Currently only can fill "
+                        "with dict/Series column "
+                        "by column"
+                    )
+                if using_copy_on_write():
+                    result = self.copy(deep=None)
+                else:
+                    result = self if inplace else self.copy()
+                is_dict = isinstance(downcast, dict)
+                for k, v in value.items():
+                    if k not in result:
+                        continue
+
+                    if was_no_default:
+                        downcast_k = lib.no_default
+                    else:
+                        downcast_k = (
+                            # error: Incompatible types in assignment (expression
+                            # has type "Union[Dict[Any, Any], None,
+                            # Literal[_NoDefault.no_default], Any]", variable has
+                            # type "_NoDefault")
+                            downcast  # type: ignore[assignment]
+                            if not is_dict
+                            # error: Item "None" of "Optional[Dict[Any, Any]]" has
+                            # no attribute "get"
+                            else downcast.get(k)  # type: ignore[union-attr]
+                        )
+
+                    res_k = result[k].fillna(v, limit=limit, downcast=downcast_k)
+
+                    if not inplace:
+                        result[k] = res_k
+                    else:
+                        # We can write into our existing column(s) iff dtype
+                        #  was preserved.
+                        if isinstance(res_k, ABCSeries):
+                            # i.e. 'k' only shows up once in self.columns
+                            if res_k.dtype == result[k].dtype:
+                                result.loc[:, k] = res_k
+                            else:
+                                # Different dtype -> no way to do inplace.
+                                result[k] = res_k
+                        else:
+                            # see test_fillna_dict_inplace_nonunique_columns
+                            locs = result.columns.get_loc(k)
+                            if isinstance(locs, slice):
+                                locs = np.arange(self.shape[1])[locs]
+                            elif (
+                                isinstance(locs, np.ndarray) and locs.dtype.kind == "b"
+                            ):
+                                locs = locs.nonzero()[0]
+                            elif not (
+                                isinstance(locs, np.ndarray) and locs.dtype.kind == "i"
+                            ):
+                                # Should never be reached, but let's cover our bases
+                                raise NotImplementedError(
+                                    "Unexpected get_loc result, please report a bug at "
+                                    "https://github.com/pandas-dev/pandas"
+                                )
+
+                            for i, loc in enumerate(locs):
+                                res_loc = res_k.iloc[:, i]
+                                target = self.iloc[:, loc]
+
+                                if res_loc.dtype == target.dtype:
+                                    result.iloc[:, loc] = res_loc
+                                else:
+                                    result.isetitem(loc, res_loc)
+                if inplace:
+                    return self._update_inplace(result)
+                else:
+                    return result
+
+            elif not is_list_like(value):
+                if axis == 1:
+                    result = self.T.fillna(value=value, limit=limit).T
+                    new_data = result._mgr
+                else:
+                    new_data = self._mgr.fillna(
+                        value=value, limit=limit, inplace=inplace, downcast=downcast
+                    )
+            elif isinstance(value, ABCDataFrame) and self.ndim == 2:
+                new_data = self.where(self.notna(), value)._mgr
+            else:
+                raise ValueError(f"invalid fill value with a {type(value)}")
+
+        result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="fillna")
+
+    @overload
+    def ffill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: Literal[False] = ...,
+        limit: None | int = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def ffill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: Literal[True],
+        limit: None | int = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def ffill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: bool_t = ...,
+        limit: None | int = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+    )
+    def ffill(
+        self,
+        *,
+        axis: None | Axis = None,
+        inplace: bool_t = False,
+        limit: None | int = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        """
+        Fill NA/NaN values by propagating the last valid observation to next valid.
+
+        Parameters
+        ----------
+        axis : {axes_single_arg}
+            Axis along which to fill missing values. For `Series`
+            this parameter is unused and defaults to 0.
+        inplace : bool, default False
+            If True, fill in-place. Note: this will modify any
+            other views on this object (e.g., a no-copy slice for a column in a
+            DataFrame).
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+        limit_area : {{`None`, 'inside', 'outside'}}, default None
+            If limit is specified, consecutive NaNs will be filled with this
+            restriction.
+
+            * ``None``: No fill restriction.
+            * 'inside': Only fill NaNs surrounded by valid values
+              (interpolate).
+            * 'outside': Only fill NaNs outside valid values (extrapolate).
+
+            .. versionadded:: 2.2.0
+
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+            .. deprecated:: 2.2.0
+
+        Returns
+        -------
+        {klass} or None
+            Object with missing values filled or None if ``inplace=True``.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[np.nan, 2, np.nan, 0],
+        ...                    [3, 4, np.nan, 1],
+        ...                    [np.nan, np.nan, np.nan, np.nan],
+        ...                    [np.nan, 3, np.nan, 4]],
+        ...                   columns=list("ABCD"))
+        >>> df
+             A    B   C    D
+        0  NaN  2.0 NaN  0.0
+        1  3.0  4.0 NaN  1.0
+        2  NaN  NaN NaN  NaN
+        3  NaN  3.0 NaN  4.0
+
+        >>> df.ffill()
+             A    B   C    D
+        0  NaN  2.0 NaN  0.0
+        1  3.0  4.0 NaN  1.0
+        2  3.0  4.0 NaN  1.0
+        3  3.0  3.0 NaN  4.0
+
+        >>> ser = pd.Series([1, np.nan, 2, 3])
+        >>> ser.ffill()
+        0   1.0
+        1   1.0
+        2   2.0
+        3   3.0
+        dtype: float64
+        """
+        downcast = self._deprecate_downcast(downcast, "ffill")
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and _check_cacher(self):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        return self._pad_or_backfill(
+            "ffill",
+            axis=axis,
+            inplace=inplace,
+            limit=limit,
+            limit_area=limit_area,
+            # error: Argument "downcast" to "_fillna_with_method" of "NDFrame"
+            # has incompatible type "Union[Dict[Any, Any], None,
+            # Literal[_NoDefault.no_default]]"; expected "Optional[Dict[Any, Any]]"
+            downcast=downcast,  # type: ignore[arg-type]
+        )
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def pad(
+        self,
+        *,
+        axis: None | Axis = None,
+        inplace: bool_t = False,
+        limit: None | int = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        """
+        Fill NA/NaN values by propagating the last valid observation to next valid.
+
+        .. deprecated:: 2.0
+
+            {klass}.pad is deprecated. Use {klass}.ffill instead.
+
+        Returns
+        -------
+        {klass} or None
+            Object with missing values filled or None if ``inplace=True``.
+
+        Examples
+        --------
+        Please see examples for :meth:`DataFrame.ffill` or :meth:`Series.ffill`.
+        """
+        warnings.warn(
+            "DataFrame.pad/Series.pad is deprecated. Use "
+            "DataFrame.ffill/Series.ffill instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.ffill(axis=axis, inplace=inplace, limit=limit, downcast=downcast)
+
+    @overload
+    def bfill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: Literal[False] = ...,
+        limit: None | int = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def bfill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: Literal[True],
+        limit: None | int = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def bfill(
+        self,
+        *,
+        axis: None | Axis = ...,
+        inplace: bool_t = ...,
+        limit: None | int = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: dict | None | lib.NoDefault = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+    )
+    def bfill(
+        self,
+        *,
+        axis: None | Axis = None,
+        inplace: bool_t = False,
+        limit: None | int = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        """
+        Fill NA/NaN values by using the next valid observation to fill the gap.
+
+        Parameters
+        ----------
+        axis : {axes_single_arg}
+            Axis along which to fill missing values. For `Series`
+            this parameter is unused and defaults to 0.
+        inplace : bool, default False
+            If True, fill in-place. Note: this will modify any
+            other views on this object (e.g., a no-copy slice for a column in a
+            DataFrame).
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+        limit_area : {{`None`, 'inside', 'outside'}}, default None
+            If limit is specified, consecutive NaNs will be filled with this
+            restriction.
+
+            * ``None``: No fill restriction.
+            * 'inside': Only fill NaNs surrounded by valid values
+              (interpolate).
+            * 'outside': Only fill NaNs outside valid values (extrapolate).
+
+            .. versionadded:: 2.2.0
+
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+            .. deprecated:: 2.2.0
+
+        Returns
+        -------
+        {klass} or None
+            Object with missing values filled or None if ``inplace=True``.
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series([1, None, None, 2])
+        >>> s.bfill()
+        0    1.0
+        1    2.0
+        2    2.0
+        3    2.0
+        dtype: float64
+        >>> s.bfill(limit=1)
+        0    1.0
+        1    NaN
+        2    2.0
+        3    2.0
+        dtype: float64
+
+        With DataFrame:
+
+        >>> df = pd.DataFrame({{'A': [1, None, None, 4], 'B': [None, 5, None, 7]}})
+        >>> df
+              A     B
+        0   1.0	  NaN
+        1   NaN	  5.0
+        2   NaN   NaN
+        3   4.0   7.0
+        >>> df.bfill()
+              A     B
+        0   1.0   5.0
+        1   4.0   5.0
+        2   4.0   7.0
+        3   4.0   7.0
+        >>> df.bfill(limit=1)
+              A     B
+        0   1.0   5.0
+        1   NaN   5.0
+        2   4.0   7.0
+        3   4.0   7.0
+        """
+        downcast = self._deprecate_downcast(downcast, "bfill")
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and _check_cacher(self):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        return self._pad_or_backfill(
+            "bfill",
+            axis=axis,
+            inplace=inplace,
+            limit=limit,
+            limit_area=limit_area,
+            # error: Argument "downcast" to "_fillna_with_method" of "NDFrame"
+            # has incompatible type "Union[Dict[Any, Any], None,
+            # Literal[_NoDefault.no_default]]"; expected "Optional[Dict[Any, Any]]"
+            downcast=downcast,  # type: ignore[arg-type]
+        )
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def backfill(
+        self,
+        *,
+        axis: None | Axis = None,
+        inplace: bool_t = False,
+        limit: None | int = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        """
+        Fill NA/NaN values by using the next valid observation to fill the gap.
+
+        .. deprecated:: 2.0
+
+            {klass}.backfill is deprecated. Use {klass}.bfill instead.
+
+        Returns
+        -------
+        {klass} or None
+            Object with missing values filled or None if ``inplace=True``.
+
+        Examples
+        --------
+        Please see examples for :meth:`DataFrame.bfill` or :meth:`Series.bfill`.
+        """
+        warnings.warn(
+            "DataFrame.backfill/Series.backfill is deprecated. Use "
+            "DataFrame.bfill/Series.bfill instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.bfill(axis=axis, inplace=inplace, limit=limit, downcast=downcast)
+
+    @overload
+    def replace(
+        self,
+        to_replace=...,
+        value=...,
+        *,
+        inplace: Literal[False] = ...,
+        limit: int | None = ...,
+        regex: bool_t = ...,
+        method: Literal["pad", "ffill", "bfill"] | lib.NoDefault = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def replace(
+        self,
+        to_replace=...,
+        value=...,
+        *,
+        inplace: Literal[True],
+        limit: int | None = ...,
+        regex: bool_t = ...,
+        method: Literal["pad", "ffill", "bfill"] | lib.NoDefault = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def replace(
+        self,
+        to_replace=...,
+        value=...,
+        *,
+        inplace: bool_t = ...,
+        limit: int | None = ...,
+        regex: bool_t = ...,
+        method: Literal["pad", "ffill", "bfill"] | lib.NoDefault = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        _shared_docs["replace"],
+        klass=_shared_doc_kwargs["klass"],
+        inplace=_shared_doc_kwargs["inplace"],
+    )
+    def replace(
+        self,
+        to_replace=None,
+        value=lib.no_default,
+        *,
+        inplace: bool_t = False,
+        limit: int | None = None,
+        regex: bool_t = False,
+        method: Literal["pad", "ffill", "bfill"] | lib.NoDefault = lib.no_default,
+    ) -> Self | None:
+        if method is not lib.no_default:
+            warnings.warn(
+                # GH#33302
+                f"The 'method' keyword in {type(self).__name__}.replace is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        elif limit is not None:
+            warnings.warn(
+                # GH#33302
+                f"The 'limit' keyword in {type(self).__name__}.replace is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if (
+            value is lib.no_default
+            and method is lib.no_default
+            and not is_dict_like(to_replace)
+            and regex is False
+        ):
+            # case that goes through _replace_single and defaults to method="pad"
+            warnings.warn(
+                # GH#33302
+                f"{type(self).__name__}.replace without 'value' and with "
+                "non-dict-like 'to_replace' is deprecated "
+                "and will raise in a future version. "
+                "Explicitly specify the new values instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if not (
+            is_scalar(to_replace)
+            or is_re_compilable(to_replace)
+            or is_list_like(to_replace)
+        ):
+            raise TypeError(
+                "Expecting 'to_replace' to be either a scalar, array-like, "
+                "dict or None, got invalid type "
+                f"{repr(type(to_replace).__name__)}"
+            )
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and _check_cacher(self):
+                    # in non-CoW mode, chained Series access will populate the
+                    # `_item_cache` which results in an increased ref count not below
+                    # the threshold, while we still need to warn. We detect this case
+                    # of a Series derived from a DataFrame through the presence of
+                    # checking the `_cacher`
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        if not is_bool(regex) and to_replace is not None:
+            raise ValueError("'to_replace' must be 'None' if 'regex' is not a bool")
+
+        if value is lib.no_default or method is not lib.no_default:
+            # GH#36984 if the user explicitly passes value=None we want to
+            #  respect that. We have the corner case where the user explicitly
+            #  passes value=None *and* a method, which we interpret as meaning
+            #  they want the (documented) default behavior.
+            if method is lib.no_default:
+                # TODO: get this to show up as the default in the docs?
+                method = "pad"
+
+            # passing a single value that is scalar like
+            # when value is None (GH5319), for compat
+            if not is_dict_like(to_replace) and not is_dict_like(regex):
+                to_replace = [to_replace]
+
+            if isinstance(to_replace, (tuple, list)):
+                # TODO: Consider copy-on-write for non-replaced columns's here
+                if isinstance(self, ABCDataFrame):
+                    from pandas import Series
+
+                    result = self.apply(
+                        Series._replace_single,
+                        args=(to_replace, method, inplace, limit),
+                    )
+                    if inplace:
+                        return None
+                    return result
+                return self._replace_single(to_replace, method, inplace, limit)
+
+            if not is_dict_like(to_replace):
+                if not is_dict_like(regex):
+                    raise TypeError(
+                        'If "to_replace" and "value" are both None '
+                        'and "to_replace" is not a list, then '
+                        "regex must be a mapping"
+                    )
+                to_replace = regex
+                regex = True
+
+            items = list(to_replace.items())
+            if items:
+                keys, values = zip(*items)
+            else:
+                # error: Incompatible types in assignment (expression has type
+                # "list[Never]", variable has type "tuple[Any, ...]")
+                keys, values = ([], [])  # type: ignore[assignment]
+
+            are_mappings = [is_dict_like(v) for v in values]
+
+            if any(are_mappings):
+                if not all(are_mappings):
+                    raise TypeError(
+                        "If a nested mapping is passed, all values "
+                        "of the top level mapping must be mappings"
+                    )
+                # passed a nested dict/Series
+                to_rep_dict = {}
+                value_dict = {}
+
+                for k, v in items:
+                    # error: Incompatible types in assignment (expression has type
+                    # "list[Never]", variable has type "tuple[Any, ...]")
+                    keys, values = list(zip(*v.items())) or (  # type: ignore[assignment]
+                        [],
+                        [],
+                    )
+
+                    to_rep_dict[k] = list(keys)
+                    value_dict[k] = list(values)
+
+                to_replace, value = to_rep_dict, value_dict
+            else:
+                to_replace, value = keys, values
+
+            return self.replace(
+                to_replace, value, inplace=inplace, limit=limit, regex=regex
+            )
+        else:
+            # need a non-zero len on all axes
+            if not self.size:
+                if inplace:
+                    return None
+                return self.copy(deep=None)
+
+            if is_dict_like(to_replace):
+                if is_dict_like(value):  # {'A' : NA} -> {'A' : 0}
+                    # Note: Checking below for `in foo.keys()` instead of
+                    #  `in foo` is needed for when we have a Series and not dict
+                    mapping = {
+                        col: (to_replace[col], value[col])
+                        for col in to_replace.keys()
+                        if col in value.keys() and col in self
+                    }
+                    return self._replace_columnwise(mapping, inplace, regex)
+
+                # {'A': NA} -> 0
+                elif not is_list_like(value):
+                    # Operate column-wise
+                    if self.ndim == 1:
+                        raise ValueError(
+                            "Series.replace cannot use dict-like to_replace "
+                            "and non-None value"
+                        )
+                    mapping = {
+                        col: (to_rep, value) for col, to_rep in to_replace.items()
+                    }
+                    return self._replace_columnwise(mapping, inplace, regex)
+                else:
+                    raise TypeError("value argument must be scalar, dict, or Series")
+
+            elif is_list_like(to_replace):
+                if not is_list_like(value):
+                    # e.g. to_replace = [NA, ''] and value is 0,
+                    #  so we replace NA with 0 and then replace '' with 0
+                    value = [value] * len(to_replace)
+
+                # e.g. we have to_replace = [NA, ''] and value = [0, 'missing']
+                if len(to_replace) != len(value):
+                    raise ValueError(
+                        f"Replacement lists must match in length. "
+                        f"Expecting {len(to_replace)} got {len(value)} "
+                    )
+                new_data = self._mgr.replace_list(
+                    src_list=to_replace,
+                    dest_list=value,
+                    inplace=inplace,
+                    regex=regex,
+                )
+
+            elif to_replace is None:
+                if not (
+                    is_re_compilable(regex)
+                    or is_list_like(regex)
+                    or is_dict_like(regex)
+                ):
+                    raise TypeError(
+                        f"'regex' must be a string or a compiled regular expression "
+                        f"or a list or dict of strings or regular expressions, "
+                        f"you passed a {repr(type(regex).__name__)}"
+                    )
+                return self.replace(
+                    regex, value, inplace=inplace, limit=limit, regex=True
+                )
+            else:
+                # dest iterable dict-like
+                if is_dict_like(value):  # NA -> {'A' : 0, 'B' : -1}
+                    # Operate column-wise
+                    if self.ndim == 1:
+                        raise ValueError(
+                            "Series.replace cannot use dict-value and "
+                            "non-None to_replace"
+                        )
+                    mapping = {col: (to_replace, val) for col, val in value.items()}
+                    return self._replace_columnwise(mapping, inplace, regex)
+
+                elif not is_list_like(value):  # NA -> 0
+                    regex = should_use_regex(regex, to_replace)
+                    if regex:
+                        new_data = self._mgr.replace_regex(
+                            to_replace=to_replace,
+                            value=value,
+                            inplace=inplace,
+                        )
+                    else:
+                        new_data = self._mgr.replace(
+                            to_replace=to_replace, value=value, inplace=inplace
+                        )
+                else:
+                    raise TypeError(
+                        f'Invalid "to_replace" type: {repr(type(to_replace).__name__)}'
+                    )
+
+        result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="replace")
+
+    @overload
+    def interpolate(
+        self,
+        method: InterpolateOptions = ...,
+        *,
+        axis: Axis = ...,
+        limit: int | None = ...,
+        inplace: Literal[False] = ...,
+        limit_direction: Literal["forward", "backward", "both"] | None = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: Literal["infer"] | None | lib.NoDefault = ...,
+        **kwargs,
+    ) -> Self:
+        ...
+
+    @overload
+    def interpolate(
+        self,
+        method: InterpolateOptions = ...,
+        *,
+        axis: Axis = ...,
+        limit: int | None = ...,
+        inplace: Literal[True],
+        limit_direction: Literal["forward", "backward", "both"] | None = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: Literal["infer"] | None | lib.NoDefault = ...,
+        **kwargs,
+    ) -> None:
+        ...
+
+    @overload
+    def interpolate(
+        self,
+        method: InterpolateOptions = ...,
+        *,
+        axis: Axis = ...,
+        limit: int | None = ...,
+        inplace: bool_t = ...,
+        limit_direction: Literal["forward", "backward", "both"] | None = ...,
+        limit_area: Literal["inside", "outside"] | None = ...,
+        downcast: Literal["infer"] | None | lib.NoDefault = ...,
+        **kwargs,
+    ) -> Self | None:
+        ...
+
+    @final
+    def interpolate(
+        self,
+        method: InterpolateOptions = "linear",
+        *,
+        axis: Axis = 0,
+        limit: int | None = None,
+        inplace: bool_t = False,
+        limit_direction: Literal["forward", "backward", "both"] | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: Literal["infer"] | None | lib.NoDefault = lib.no_default,
+        **kwargs,
+    ) -> Self | None:
+        """
+        Fill NaN values using an interpolation method.
+
+        Please note that only ``method='linear'`` is supported for
+        DataFrame/Series with a MultiIndex.
+
+        Parameters
+        ----------
+        method : str, default 'linear'
+            Interpolation technique to use. One of:
+
+            * 'linear': Ignore the index and treat the values as equally
+              spaced. This is the only method supported on MultiIndexes.
+            * 'time': Works on daily and higher resolution data to interpolate
+              given length of interval.
+            * 'index', 'values': use the actual numerical values of the index.
+            * 'pad': Fill in NaNs using existing values.
+            * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic',
+              'barycentric', 'polynomial': Passed to
+              `scipy.interpolate.interp1d`, whereas 'spline' is passed to
+              `scipy.interpolate.UnivariateSpline`. These methods use the numerical
+              values of the index.  Both 'polynomial' and 'spline' require that
+              you also specify an `order` (int), e.g.
+              ``df.interpolate(method='polynomial', order=5)``. Note that,
+              `slinear` method in Pandas refers to the Scipy first order `spline`
+              instead of Pandas first order `spline`.
+            * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima',
+              'cubicspline': Wrappers around the SciPy interpolation methods of
+              similar names. See `Notes`.
+            * 'from_derivatives': Refers to
+              `scipy.interpolate.BPoly.from_derivatives`.
+
+        axis : {{0 or 'index', 1 or 'columns', None}}, default None
+            Axis to interpolate along. For `Series` this parameter is unused
+            and defaults to 0.
+        limit : int, optional
+            Maximum number of consecutive NaNs to fill. Must be greater than
+            0.
+        inplace : bool, default False
+            Update the data in place if possible.
+        limit_direction : {{'forward', 'backward', 'both'}}, Optional
+            Consecutive NaNs will be filled in this direction.
+
+            If limit is specified:
+                * If 'method' is 'pad' or 'ffill', 'limit_direction' must be 'forward'.
+                * If 'method' is 'backfill' or 'bfill', 'limit_direction' must be
+                  'backwards'.
+
+            If 'limit' is not specified:
+                * If 'method' is 'backfill' or 'bfill', the default is 'backward'
+                * else the default is 'forward'
+
+            raises ValueError if `limit_direction` is 'forward' or 'both' and
+                method is 'backfill' or 'bfill'.
+            raises ValueError if `limit_direction` is 'backward' or 'both' and
+                method is 'pad' or 'ffill'.
+
+        limit_area : {{`None`, 'inside', 'outside'}}, default None
+            If limit is specified, consecutive NaNs will be filled with this
+            restriction.
+
+            * ``None``: No fill restriction.
+            * 'inside': Only fill NaNs surrounded by valid values
+              (interpolate).
+            * 'outside': Only fill NaNs outside valid values (extrapolate).
+
+        downcast : optional, 'infer' or None, defaults to None
+            Downcast dtypes if possible.
+
+            .. deprecated:: 2.1.0
+
+        ``**kwargs`` : optional
+            Keyword arguments to pass on to the interpolating function.
+
+        Returns
+        -------
+        Series or DataFrame or None
+            Returns the same object type as the caller, interpolated at
+            some or all ``NaN`` values or None if ``inplace=True``.
+
+        See Also
+        --------
+        fillna : Fill missing values using different methods.
+        scipy.interpolate.Akima1DInterpolator : Piecewise cubic polynomials
+            (Akima interpolator).
+        scipy.interpolate.BPoly.from_derivatives : Piecewise polynomial in the
+            Bernstein basis.
+        scipy.interpolate.interp1d : Interpolate a 1-D function.
+        scipy.interpolate.KroghInterpolator : Interpolate polynomial (Krogh
+            interpolator).
+        scipy.interpolate.PchipInterpolator : PCHIP 1-d monotonic cubic
+            interpolation.
+        scipy.interpolate.CubicSpline : Cubic spline data interpolator.
+
+        Notes
+        -----
+        The 'krogh', 'piecewise_polynomial', 'spline', 'pchip' and 'akima'
+        methods are wrappers around the respective SciPy implementations of
+        similar names. These use the actual numerical values of the index.
+        For more information on their behavior, see the
+        `SciPy documentation
+        `__.
+
+        Examples
+        --------
+        Filling in ``NaN`` in a :class:`~pandas.Series` via linear
+        interpolation.
+
+        >>> s = pd.Series([0, 1, np.nan, 3])
+        >>> s
+        0    0.0
+        1    1.0
+        2    NaN
+        3    3.0
+        dtype: float64
+        >>> s.interpolate()
+        0    0.0
+        1    1.0
+        2    2.0
+        3    3.0
+        dtype: float64
+
+        Filling in ``NaN`` in a Series via polynomial interpolation or splines:
+        Both 'polynomial' and 'spline' methods require that you also specify
+        an ``order`` (int).
+
+        >>> s = pd.Series([0, 2, np.nan, 8])
+        >>> s.interpolate(method='polynomial', order=2)
+        0    0.000000
+        1    2.000000
+        2    4.666667
+        3    8.000000
+        dtype: float64
+
+        Fill the DataFrame forward (that is, going down) along each column
+        using linear interpolation.
+
+        Note how the last entry in column 'a' is interpolated differently,
+        because there is no entry after it to use for interpolation.
+        Note how the first entry in column 'b' remains ``NaN``, because there
+        is no entry before it to use for interpolation.
+
+        >>> df = pd.DataFrame([(0.0, np.nan, -1.0, 1.0),
+        ...                    (np.nan, 2.0, np.nan, np.nan),
+        ...                    (2.0, 3.0, np.nan, 9.0),
+        ...                    (np.nan, 4.0, -4.0, 16.0)],
+        ...                   columns=list('abcd'))
+        >>> df
+             a    b    c     d
+        0  0.0  NaN -1.0   1.0
+        1  NaN  2.0  NaN   NaN
+        2  2.0  3.0  NaN   9.0
+        3  NaN  4.0 -4.0  16.0
+        >>> df.interpolate(method='linear', limit_direction='forward', axis=0)
+             a    b    c     d
+        0  0.0  NaN -1.0   1.0
+        1  1.0  2.0 -2.0   5.0
+        2  2.0  3.0 -3.0   9.0
+        3  2.0  4.0 -4.0  16.0
+
+        Using polynomial interpolation.
+
+        >>> df['d'].interpolate(method='polynomial', order=2)
+        0     1.0
+        1     4.0
+        2     9.0
+        3    16.0
+        Name: d, dtype: float64
+        """
+        if downcast is not lib.no_default:
+            # GH#40988
+            warnings.warn(
+                f"The 'downcast' keyword in {type(self).__name__}.interpolate "
+                "is deprecated and will be removed in a future version. "
+                "Call result.infer_objects(copy=False) on the result instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            downcast = None
+        if downcast is not None and downcast != "infer":
+            raise ValueError("downcast must be either None or 'infer'")
+
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and _check_cacher(self):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        axis = self._get_axis_number(axis)
+
+        if self.empty:
+            if inplace:
+                return None
+            return self.copy()
+
+        if not isinstance(method, str):
+            raise ValueError("'method' should be a string, not None.")
+
+        fillna_methods = ["ffill", "bfill", "pad", "backfill"]
+        if method.lower() in fillna_methods:
+            # GH#53581
+            warnings.warn(
+                f"{type(self).__name__}.interpolate with method={method} is "
+                "deprecated and will raise in a future version. "
+                "Use obj.ffill() or obj.bfill() instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            obj, should_transpose = self, False
+        else:
+            obj, should_transpose = (self.T, True) if axis == 1 else (self, False)
+            if np.any(obj.dtypes == object):
+                # GH#53631
+                if not (obj.ndim == 2 and np.all(obj.dtypes == object)):
+                    # don't warn in cases that already raise
+                    warnings.warn(
+                        f"{type(self).__name__}.interpolate with object dtype is "
+                        "deprecated and will raise in a future version. Call "
+                        "obj.infer_objects(copy=False) before interpolating instead.",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+
+        if method in fillna_methods and "fill_value" in kwargs:
+            raise ValueError(
+                "'fill_value' is not a valid keyword for "
+                f"{type(self).__name__}.interpolate with method from "
+                f"{fillna_methods}"
+            )
+
+        if isinstance(obj.index, MultiIndex) and method != "linear":
+            raise ValueError(
+                "Only `method=linear` interpolation is supported on MultiIndexes."
+            )
+
+        limit_direction = missing.infer_limit_direction(limit_direction, method)
+
+        if obj.ndim == 2 and np.all(obj.dtypes == object):
+            raise TypeError(
+                "Cannot interpolate with all object-dtype columns "
+                "in the DataFrame. Try setting at least one "
+                "column to a numeric dtype."
+            )
+
+        if method.lower() in fillna_methods:
+            # TODO(3.0): remove this case
+            # TODO: warn/raise on limit_direction or kwargs which are ignored?
+            #  as of 2023-06-26 no tests get here with either
+            if not self._mgr.is_single_block and axis == 1:
+                # GH#53898
+                if inplace:
+                    raise NotImplementedError()
+                obj, axis, should_transpose = self.T, 1 - axis, True
+
+            new_data = obj._mgr.pad_or_backfill(
+                method=method,
+                axis=self._get_block_manager_axis(axis),
+                limit=limit,
+                limit_area=limit_area,
+                inplace=inplace,
+                downcast=downcast,
+            )
+        else:
+            index = missing.get_interp_index(method, obj.index)
+            new_data = obj._mgr.interpolate(
+                method=method,
+                index=index,
+                limit=limit,
+                limit_direction=limit_direction,
+                limit_area=limit_area,
+                inplace=inplace,
+                downcast=downcast,
+                **kwargs,
+            )
+
+        result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+        if should_transpose:
+            result = result.T
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result.__finalize__(self, method="interpolate")
+
+    # ----------------------------------------------------------------------
+    # Timeseries methods Methods
+
+    @final
+    def asof(self, where, subset=None):
+        """
+        Return the last row(s) without any NaNs before `where`.
+
+        The last row (for each element in `where`, if list) without any
+        NaN is taken.
+        In case of a :class:`~pandas.DataFrame`, the last row without NaN
+        considering only the subset of columns (if not `None`)
+
+        If there is no good value, NaN is returned for a Series or
+        a Series of NaN values for a DataFrame
+
+        Parameters
+        ----------
+        where : date or array-like of dates
+            Date(s) before which the last row(s) are returned.
+        subset : str or array-like of str, default `None`
+            For DataFrame, if not `None`, only use these columns to
+            check for NaNs.
+
+        Returns
+        -------
+        scalar, Series, or DataFrame
+
+            The return can be:
+
+            * scalar : when `self` is a Series and `where` is a scalar
+            * Series: when `self` is a Series and `where` is an array-like,
+              or when `self` is a DataFrame and `where` is a scalar
+            * DataFrame : when `self` is a DataFrame and `where` is an
+              array-like
+
+        See Also
+        --------
+        merge_asof : Perform an asof merge. Similar to left join.
+
+        Notes
+        -----
+        Dates are assumed to be sorted. Raises if this is not the case.
+
+        Examples
+        --------
+        A Series and a scalar `where`.
+
+        >>> s = pd.Series([1, 2, np.nan, 4], index=[10, 20, 30, 40])
+        >>> s
+        10    1.0
+        20    2.0
+        30    NaN
+        40    4.0
+        dtype: float64
+
+        >>> s.asof(20)
+        2.0
+
+        For a sequence `where`, a Series is returned. The first value is
+        NaN, because the first element of `where` is before the first
+        index value.
+
+        >>> s.asof([5, 20])
+        5     NaN
+        20    2.0
+        dtype: float64
+
+        Missing values are not considered. The following is ``2.0``, not
+        NaN, even though NaN is at the index location for ``30``.
+
+        >>> s.asof(30)
+        2.0
+
+        Take all columns into consideration
+
+        >>> df = pd.DataFrame({'a': [10., 20., 30., 40., 50.],
+        ...                    'b': [None, None, None, None, 500]},
+        ...                   index=pd.DatetimeIndex(['2018-02-27 09:01:00',
+        ...                                           '2018-02-27 09:02:00',
+        ...                                           '2018-02-27 09:03:00',
+        ...                                           '2018-02-27 09:04:00',
+        ...                                           '2018-02-27 09:05:00']))
+        >>> df.asof(pd.DatetimeIndex(['2018-02-27 09:03:30',
+        ...                           '2018-02-27 09:04:30']))
+                              a   b
+        2018-02-27 09:03:30 NaN NaN
+        2018-02-27 09:04:30 NaN NaN
+
+        Take a single column into consideration
+
+        >>> df.asof(pd.DatetimeIndex(['2018-02-27 09:03:30',
+        ...                           '2018-02-27 09:04:30']),
+        ...         subset=['a'])
+                                a   b
+        2018-02-27 09:03:30  30.0 NaN
+        2018-02-27 09:04:30  40.0 NaN
+        """
+        if isinstance(where, str):
+            where = Timestamp(where)
+
+        if not self.index.is_monotonic_increasing:
+            raise ValueError("asof requires a sorted index")
+
+        is_series = isinstance(self, ABCSeries)
+        if is_series:
+            if subset is not None:
+                raise ValueError("subset is not valid for Series")
+        else:
+            if subset is None:
+                subset = self.columns
+            if not is_list_like(subset):
+                subset = [subset]
+
+        is_list = is_list_like(where)
+        if not is_list:
+            start = self.index[0]
+            if isinstance(self.index, PeriodIndex):
+                where = Period(where, freq=self.index.freq)
+
+            if where < start:
+                if not is_series:
+                    return self._constructor_sliced(
+                        index=self.columns, name=where, dtype=np.float64
+                    )
+                return np.nan
+
+            # It's always much faster to use a *while* loop here for
+            # Series than pre-computing all the NAs. However a
+            # *while* loop is extremely expensive for DataFrame
+            # so we later pre-compute all the NAs and use the same
+            # code path whether *where* is a scalar or list.
+            # See PR: https://github.com/pandas-dev/pandas/pull/14476
+            if is_series:
+                loc = self.index.searchsorted(where, side="right")
+                if loc > 0:
+                    loc -= 1
+
+                values = self._values
+                while loc > 0 and isna(values[loc]):
+                    loc -= 1
+                return values[loc]
+
+        if not isinstance(where, Index):
+            where = Index(where) if is_list else Index([where])
+
+        nulls = self.isna() if is_series else self[subset].isna().any(axis=1)
+        if nulls.all():
+            if is_series:
+                self = cast("Series", self)
+                return self._constructor(np.nan, index=where, name=self.name)
+            elif is_list:
+                self = cast("DataFrame", self)
+                return self._constructor(np.nan, index=where, columns=self.columns)
+            else:
+                self = cast("DataFrame", self)
+                return self._constructor_sliced(
+                    np.nan, index=self.columns, name=where[0]
+                )
+
+        locs = self.index.asof_locs(where, ~(nulls._values))
+
+        # mask the missing
+        mask = locs == -1
+        data = self.take(locs)
+        data.index = where
+        if mask.any():
+            # GH#16063 only do this setting when necessary, otherwise
+            #  we'd cast e.g. bools to floats
+            data.loc[mask] = np.nan
+        return data if is_list else data.iloc[-1]
+
+    # ----------------------------------------------------------------------
+    # Action Methods
+
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def isna(self) -> Self:
+        """
+        Detect missing values.
+
+        Return a boolean same-sized object indicating if the values are NA.
+        NA values, such as None or :attr:`numpy.NaN`, gets mapped to True
+        values.
+        Everything else gets mapped to False values. Characters such as empty
+        strings ``''`` or :attr:`numpy.inf` are not considered NA values
+        (unless you set ``pandas.options.mode.use_inf_as_na = True``).
+
+        Returns
+        -------
+        {klass}
+            Mask of bool values for each element in {klass} that
+            indicates whether an element is an NA value.
+
+        See Also
+        --------
+        {klass}.isnull : Alias of isna.
+        {klass}.notna : Boolean inverse of isna.
+        {klass}.dropna : Omit axes labels with missing values.
+        isna : Top-level isna.
+
+        Examples
+        --------
+        Show which entries in a DataFrame are NA.
+
+        >>> df = pd.DataFrame(dict(age=[5, 6, np.nan],
+        ...                        born=[pd.NaT, pd.Timestamp('1939-05-27'),
+        ...                              pd.Timestamp('1940-04-25')],
+        ...                        name=['Alfred', 'Batman', ''],
+        ...                        toy=[None, 'Batmobile', 'Joker']))
+        >>> df
+           age       born    name        toy
+        0  5.0        NaT  Alfred       None
+        1  6.0 1939-05-27  Batman  Batmobile
+        2  NaN 1940-04-25              Joker
+
+        >>> df.isna()
+             age   born   name    toy
+        0  False   True  False   True
+        1  False  False  False  False
+        2   True  False  False  False
+
+        Show which entries in a Series are NA.
+
+        >>> ser = pd.Series([5, 6, np.nan])
+        >>> ser
+        0    5.0
+        1    6.0
+        2    NaN
+        dtype: float64
+
+        >>> ser.isna()
+        0    False
+        1    False
+        2     True
+        dtype: bool
+        """
+        return isna(self).__finalize__(self, method="isna")
+
+    @doc(isna, klass=_shared_doc_kwargs["klass"])
+    def isnull(self) -> Self:
+        return isna(self).__finalize__(self, method="isnull")
+
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def notna(self) -> Self:
+        """
+        Detect existing (non-missing) values.
+
+        Return a boolean same-sized object indicating if the values are not NA.
+        Non-missing values get mapped to True. Characters such as empty
+        strings ``''`` or :attr:`numpy.inf` are not considered NA values
+        (unless you set ``pandas.options.mode.use_inf_as_na = True``).
+        NA values, such as None or :attr:`numpy.NaN`, get mapped to False
+        values.
+
+        Returns
+        -------
+        {klass}
+            Mask of bool values for each element in {klass} that
+            indicates whether an element is not an NA value.
+
+        See Also
+        --------
+        {klass}.notnull : Alias of notna.
+        {klass}.isna : Boolean inverse of notna.
+        {klass}.dropna : Omit axes labels with missing values.
+        notna : Top-level notna.
+
+        Examples
+        --------
+        Show which entries in a DataFrame are not NA.
+
+        >>> df = pd.DataFrame(dict(age=[5, 6, np.nan],
+        ...                        born=[pd.NaT, pd.Timestamp('1939-05-27'),
+        ...                              pd.Timestamp('1940-04-25')],
+        ...                        name=['Alfred', 'Batman', ''],
+        ...                        toy=[None, 'Batmobile', 'Joker']))
+        >>> df
+           age       born    name        toy
+        0  5.0        NaT  Alfred       None
+        1  6.0 1939-05-27  Batman  Batmobile
+        2  NaN 1940-04-25              Joker
+
+        >>> df.notna()
+             age   born  name    toy
+        0   True  False  True  False
+        1   True   True  True   True
+        2  False   True  True   True
+
+        Show which entries in a Series are not NA.
+
+        >>> ser = pd.Series([5, 6, np.nan])
+        >>> ser
+        0    5.0
+        1    6.0
+        2    NaN
+        dtype: float64
+
+        >>> ser.notna()
+        0     True
+        1     True
+        2    False
+        dtype: bool
+        """
+        return notna(self).__finalize__(self, method="notna")
+
+    @doc(notna, klass=_shared_doc_kwargs["klass"])
+    def notnull(self) -> Self:
+        return notna(self).__finalize__(self, method="notnull")
+
+    @final
+    def _clip_with_scalar(self, lower, upper, inplace: bool_t = False):
+        if (lower is not None and np.any(isna(lower))) or (
+            upper is not None and np.any(isna(upper))
+        ):
+            raise ValueError("Cannot use an NA value as a clip threshold")
+
+        result = self
+        mask = self.isna()
+
+        if lower is not None:
+            cond = mask | (self >= lower)
+            result = result.where(
+                cond, lower, inplace=inplace
+            )  # type: ignore[assignment]
+        if upper is not None:
+            cond = mask | (self <= upper)
+            result = self if inplace else result
+            result = result.where(
+                cond, upper, inplace=inplace
+            )  # type: ignore[assignment]
+
+        return result
+
+    @final
+    def _clip_with_one_bound(self, threshold, method, axis, inplace):
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+
+        # method is self.le for upper bound and self.ge for lower bound
+        if is_scalar(threshold) and is_number(threshold):
+            if method.__name__ == "le":
+                return self._clip_with_scalar(None, threshold, inplace=inplace)
+            return self._clip_with_scalar(threshold, None, inplace=inplace)
+
+        # GH #15390
+        # In order for where method to work, the threshold must
+        # be transformed to NDFrame from other array like structure.
+        if (not isinstance(threshold, ABCSeries)) and is_list_like(threshold):
+            if isinstance(self, ABCSeries):
+                threshold = self._constructor(threshold, index=self.index)
+            else:
+                threshold = self._align_for_op(threshold, axis, flex=None)[1]
+
+        # GH 40420
+        # Treat missing thresholds as no bounds, not clipping the values
+        if is_list_like(threshold):
+            fill_value = np.inf if method.__name__ == "le" else -np.inf
+            threshold_inf = threshold.fillna(fill_value)
+        else:
+            threshold_inf = threshold
+
+        subset = method(threshold_inf, axis=axis) | isna(self)
+
+        # GH 40420
+        return self.where(subset, threshold, axis=axis, inplace=inplace)
+
+    @overload
+    def clip(
+        self,
+        lower=...,
+        upper=...,
+        *,
+        axis: Axis | None = ...,
+        inplace: Literal[False] = ...,
+        **kwargs,
+    ) -> Self:
+        ...
+
+    @overload
+    def clip(
+        self,
+        lower=...,
+        upper=...,
+        *,
+        axis: Axis | None = ...,
+        inplace: Literal[True],
+        **kwargs,
+    ) -> None:
+        ...
+
+    @overload
+    def clip(
+        self,
+        lower=...,
+        upper=...,
+        *,
+        axis: Axis | None = ...,
+        inplace: bool_t = ...,
+        **kwargs,
+    ) -> Self | None:
+        ...
+
+    @final
+    def clip(
+        self,
+        lower=None,
+        upper=None,
+        *,
+        axis: Axis | None = None,
+        inplace: bool_t = False,
+        **kwargs,
+    ) -> Self | None:
+        """
+        Trim values at input threshold(s).
+
+        Assigns values outside boundary to boundary values. Thresholds
+        can be singular values or array like, and in the latter case
+        the clipping is performed element-wise in the specified axis.
+
+        Parameters
+        ----------
+        lower : float or array-like, default None
+            Minimum threshold value. All values below this
+            threshold will be set to it. A missing
+            threshold (e.g `NA`) will not clip the value.
+        upper : float or array-like, default None
+            Maximum threshold value. All values above this
+            threshold will be set to it. A missing
+            threshold (e.g `NA`) will not clip the value.
+        axis : {{0 or 'index', 1 or 'columns', None}}, default None
+            Align object with lower and upper along the given axis.
+            For `Series` this parameter is unused and defaults to `None`.
+        inplace : bool, default False
+            Whether to perform the operation in place on the data.
+        *args, **kwargs
+            Additional keywords have no effect but might be accepted
+            for compatibility with numpy.
+
+        Returns
+        -------
+        Series or DataFrame or None
+            Same type as calling object with the values outside the
+            clip boundaries replaced or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.clip : Trim values at input threshold in series.
+        DataFrame.clip : Trim values at input threshold in dataframe.
+        numpy.clip : Clip (limit) the values in an array.
+
+        Examples
+        --------
+        >>> data = {'col_0': [9, -3, 0, -1, 5], 'col_1': [-2, -7, 6, 8, -5]}
+        >>> df = pd.DataFrame(data)
+        >>> df
+           col_0  col_1
+        0      9     -2
+        1     -3     -7
+        2      0      6
+        3     -1      8
+        4      5     -5
+
+        Clips per column using lower and upper thresholds:
+
+        >>> df.clip(-4, 6)
+           col_0  col_1
+        0      6     -2
+        1     -3     -4
+        2      0      6
+        3     -1      6
+        4      5     -4
+
+        Clips using specific lower and upper thresholds per column:
+
+        >>> df.clip([-2, -1], [4, 5])
+            col_0  col_1
+        0      4     -1
+        1     -2     -1
+        2      0      5
+        3     -1      5
+        4      4     -1
+
+        Clips using specific lower and upper thresholds per column element:
+
+        >>> t = pd.Series([2, -4, -1, 6, 3])
+        >>> t
+        0    2
+        1   -4
+        2   -1
+        3    6
+        4    3
+        dtype: int64
+
+        >>> df.clip(t, t + 4, axis=0)
+           col_0  col_1
+        0      6      2
+        1     -3     -4
+        2      0      3
+        3      6      8
+        4      5      3
+
+        Clips using specific lower threshold per column element, with missing values:
+
+        >>> t = pd.Series([2, -4, np.nan, 6, 3])
+        >>> t
+        0    2.0
+        1   -4.0
+        2    NaN
+        3    6.0
+        4    3.0
+        dtype: float64
+
+        >>> df.clip(t, axis=0)
+        col_0  col_1
+        0      9      2
+        1     -3     -4
+        2      0      6
+        3      6      8
+        4      5      3
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and hasattr(self, "_cacher"):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        axis = nv.validate_clip_with_axis(axis, (), kwargs)
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+
+        # GH 17276
+        # numpy doesn't like NaN as a clip value
+        # so ignore
+        # GH 19992
+        # numpy doesn't drop a list-like bound containing NaN
+        isna_lower = isna(lower)
+        if not is_list_like(lower):
+            if np.any(isna_lower):
+                lower = None
+        elif np.all(isna_lower):
+            lower = None
+        isna_upper = isna(upper)
+        if not is_list_like(upper):
+            if np.any(isna_upper):
+                upper = None
+        elif np.all(isna_upper):
+            upper = None
+
+        # GH 2747 (arguments were reversed)
+        if (
+            lower is not None
+            and upper is not None
+            and is_scalar(lower)
+            and is_scalar(upper)
+        ):
+            lower, upper = min(lower, upper), max(lower, upper)
+
+        # fast-path for scalars
+        if (lower is None or is_number(lower)) and (upper is None or is_number(upper)):
+            return self._clip_with_scalar(lower, upper, inplace=inplace)
+
+        result = self
+        if lower is not None:
+            result = result._clip_with_one_bound(
+                lower, method=self.ge, axis=axis, inplace=inplace
+            )
+        if upper is not None:
+            if inplace:
+                result = self
+            result = result._clip_with_one_bound(
+                upper, method=self.le, axis=axis, inplace=inplace
+            )
+
+        return result
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def asfreq(
+        self,
+        freq: Frequency,
+        method: FillnaOptions | None = None,
+        how: Literal["start", "end"] | None = None,
+        normalize: bool_t = False,
+        fill_value: Hashable | None = None,
+    ) -> Self:
+        """
+        Convert time series to specified frequency.
+
+        Returns the original data conformed to a new index with the specified
+        frequency.
+
+        If the index of this {klass} is a :class:`~pandas.PeriodIndex`, the new index
+        is the result of transforming the original index with
+        :meth:`PeriodIndex.asfreq ` (so the original index
+        will map one-to-one to the new index).
+
+        Otherwise, the new index will be equivalent to ``pd.date_range(start, end,
+        freq=freq)`` where ``start`` and ``end`` are, respectively, the first and
+        last entries in the original index (see :func:`pandas.date_range`). The
+        values corresponding to any timesteps in the new index which were not present
+        in the original index will be null (``NaN``), unless a method for filling
+        such unknowns is provided (see the ``method`` parameter below).
+
+        The :meth:`resample` method is more appropriate if an operation on each group of
+        timesteps (such as an aggregate) is necessary to represent the data at the new
+        frequency.
+
+        Parameters
+        ----------
+        freq : DateOffset or str
+            Frequency DateOffset or string.
+        method : {{'backfill'/'bfill', 'pad'/'ffill'}}, default None
+            Method to use for filling holes in reindexed Series (note this
+            does not fill NaNs that already were present):
+
+            * 'pad' / 'ffill': propagate last valid observation forward to next
+              valid
+            * 'backfill' / 'bfill': use NEXT valid observation to fill.
+        how : {{'start', 'end'}}, default end
+            For PeriodIndex only (see PeriodIndex.asfreq).
+        normalize : bool, default False
+            Whether to reset output index to midnight.
+        fill_value : scalar, optional
+            Value to use for missing values, applied during upsampling (note
+            this does not fill NaNs that already were present).
+
+        Returns
+        -------
+        {klass}
+            {klass} object reindexed to the specified frequency.
+
+        See Also
+        --------
+        reindex : Conform DataFrame to new index with optional filling logic.
+
+        Notes
+        -----
+        To learn more about the frequency strings, please see `this link
+        `__.
+
+        Examples
+        --------
+        Start by creating a series with 4 one minute timestamps.
+
+        >>> index = pd.date_range('1/1/2000', periods=4, freq='min')
+        >>> series = pd.Series([0.0, None, 2.0, 3.0], index=index)
+        >>> df = pd.DataFrame({{'s': series}})
+        >>> df
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:03:00    3.0
+
+        Upsample the series into 30 second bins.
+
+        >>> df.asfreq(freq='30s')
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    NaN
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    NaN
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    NaN
+        2000-01-01 00:03:00    3.0
+
+        Upsample again, providing a ``fill value``.
+
+        >>> df.asfreq(freq='30s', fill_value=9.0)
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    9.0
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    9.0
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    9.0
+        2000-01-01 00:03:00    3.0
+
+        Upsample again, providing a ``method``.
+
+        >>> df.asfreq(freq='30s', method='bfill')
+                               s
+        2000-01-01 00:00:00    0.0
+        2000-01-01 00:00:30    NaN
+        2000-01-01 00:01:00    NaN
+        2000-01-01 00:01:30    2.0
+        2000-01-01 00:02:00    2.0
+        2000-01-01 00:02:30    3.0
+        2000-01-01 00:03:00    3.0
+        """
+        from pandas.core.resample import asfreq
+
+        return asfreq(
+            self,
+            freq,
+            method=method,
+            how=how,
+            normalize=normalize,
+            fill_value=fill_value,
+        )
+
+    @final
+    def at_time(self, time, asof: bool_t = False, axis: Axis | None = None) -> Self:
+        """
+        Select values at particular time of day (e.g., 9:30AM).
+
+        Parameters
+        ----------
+        time : datetime.time or str
+            The values to select.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            For `Series` this parameter is unused and defaults to 0.
+
+        Returns
+        -------
+        Series or DataFrame
+
+        Raises
+        ------
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
+
+        See Also
+        --------
+        between_time : Select values between particular times of the day.
+        first : Select initial periods of time series based on a date offset.
+        last : Select final periods of time series based on a date offset.
+        DatetimeIndex.indexer_at_time : Get just the index locations for
+            values at particular time of the day.
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='12h')
+        >>> ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
+        >>> ts
+                             A
+        2018-04-09 00:00:00  1
+        2018-04-09 12:00:00  2
+        2018-04-10 00:00:00  3
+        2018-04-10 12:00:00  4
+
+        >>> ts.at_time('12:00')
+                             A
+        2018-04-09 12:00:00  2
+        2018-04-10 12:00:00  4
+        """
+        if axis is None:
+            axis = 0
+        axis = self._get_axis_number(axis)
+
+        index = self._get_axis(axis)
+
+        if not isinstance(index, DatetimeIndex):
+            raise TypeError("Index must be DatetimeIndex")
+
+        indexer = index.indexer_at_time(time, asof=asof)
+        return self._take_with_is_copy(indexer, axis=axis)
+
+    @final
+    def between_time(
+        self,
+        start_time,
+        end_time,
+        inclusive: IntervalClosedType = "both",
+        axis: Axis | None = None,
+    ) -> Self:
+        """
+        Select values between particular times of the day (e.g., 9:00-9:30 AM).
+
+        By setting ``start_time`` to be later than ``end_time``,
+        you can get the times that are *not* between the two times.
+
+        Parameters
+        ----------
+        start_time : datetime.time or str
+            Initial time as a time filter limit.
+        end_time : datetime.time or str
+            End time as a time filter limit.
+        inclusive : {"both", "neither", "left", "right"}, default "both"
+            Include boundaries; whether to set each bound as closed or open.
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Determine range time on index or columns value.
+            For `Series` this parameter is unused and defaults to 0.
+
+        Returns
+        -------
+        Series or DataFrame
+            Data from the original object filtered to the specified dates range.
+
+        Raises
+        ------
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
+
+        See Also
+        --------
+        at_time : Select values at a particular time of the day.
+        first : Select initial periods of time series based on a date offset.
+        last : Select final periods of time series based on a date offset.
+        DatetimeIndex.indexer_between_time : Get just the index locations for
+            values between particular times of the day.
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='1D20min')
+        >>> ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
+        >>> ts
+                             A
+        2018-04-09 00:00:00  1
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+        2018-04-12 01:00:00  4
+
+        >>> ts.between_time('0:15', '0:45')
+                             A
+        2018-04-10 00:20:00  2
+        2018-04-11 00:40:00  3
+
+        You get the times that are *not* between two times by setting
+        ``start_time`` later than ``end_time``:
+
+        >>> ts.between_time('0:45', '0:15')
+                             A
+        2018-04-09 00:00:00  1
+        2018-04-12 01:00:00  4
+        """
+        if axis is None:
+            axis = 0
+        axis = self._get_axis_number(axis)
+
+        index = self._get_axis(axis)
+        if not isinstance(index, DatetimeIndex):
+            raise TypeError("Index must be DatetimeIndex")
+
+        left_inclusive, right_inclusive = validate_inclusive(inclusive)
+        indexer = index.indexer_between_time(
+            start_time,
+            end_time,
+            include_start=left_inclusive,
+            include_end=right_inclusive,
+        )
+        return self._take_with_is_copy(indexer, axis=axis)
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def resample(
+        self,
+        rule,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        closed: Literal["right", "left"] | None = None,
+        label: Literal["right", "left"] | None = None,
+        convention: Literal["start", "end", "s", "e"] = "start",
+        kind: Literal["timestamp", "period"] | None | lib.NoDefault = lib.no_default,
+        on: Level | None = None,
+        level: Level | None = None,
+        origin: str | TimestampConvertibleTypes = "start_day",
+        offset: TimedeltaConvertibleTypes | None = None,
+        group_keys: bool_t = False,
+    ) -> Resampler:
+        """
+        Resample time-series data.
+
+        Convenience method for frequency conversion and resampling of time series.
+        The object must have a datetime-like index (`DatetimeIndex`, `PeriodIndex`,
+        or `TimedeltaIndex`), or the caller must pass the label of a datetime-like
+        series/index to the ``on``/``level`` keyword parameter.
+
+        Parameters
+        ----------
+        rule : DateOffset, Timedelta or str
+            The offset string or object representing target conversion.
+        axis : {{0 or 'index', 1 or 'columns'}}, default 0
+            Which axis to use for up- or down-sampling. For `Series` this parameter
+            is unused and defaults to 0. Must be
+            `DatetimeIndex`, `TimedeltaIndex` or `PeriodIndex`.
+
+            .. deprecated:: 2.0.0
+                Use frame.T.resample(...) instead.
+        closed : {{'right', 'left'}}, default None
+            Which side of bin interval is closed. The default is 'left'
+            for all frequency offsets except for 'ME', 'YE', 'QE', 'BME',
+            'BA', 'BQE', and 'W' which all have a default of 'right'.
+        label : {{'right', 'left'}}, default None
+            Which bin edge label to label bucket with. The default is 'left'
+            for all frequency offsets except for 'ME', 'YE', 'QE', 'BME',
+            'BA', 'BQE', and 'W' which all have a default of 'right'.
+        convention : {{'start', 'end', 's', 'e'}}, default 'start'
+            For `PeriodIndex` only, controls whether to use the start or
+            end of `rule`.
+
+        kind : {{'timestamp', 'period'}}, optional, default None
+            Pass 'timestamp' to convert the resulting index to a
+            `DateTimeIndex` or 'period' to convert it to a `PeriodIndex`.
+            By default the input representation is retained.
+
+            .. deprecated:: 2.2.0
+                Convert index to desired type explicitly instead.
+
+        on : str, optional
+            For a DataFrame, column to use instead of index for resampling.
+            Column must be datetime-like.
+        level : str or int, optional
+            For a MultiIndex, level (name or number) to use for
+            resampling. `level` must be datetime-like.
+        origin : Timestamp or str, default 'start_day'
+            The timestamp on which to adjust the grouping. The timezone of origin
+            must match the timezone of the index.
+            If string, must be one of the following:
+
+            - 'epoch': `origin` is 1970-01-01
+            - 'start': `origin` is the first value of the timeseries
+            - 'start_day': `origin` is the first day at midnight of the timeseries
+
+            - 'end': `origin` is the last value of the timeseries
+            - 'end_day': `origin` is the ceiling midnight of the last day
+
+            .. versionadded:: 1.3.0
+
+            .. note::
+
+                Only takes effect for Tick-frequencies (i.e. fixed frequencies like
+                days, hours, and minutes, rather than months or quarters).
+        offset : Timedelta or str, default is None
+            An offset timedelta added to the origin.
+
+        group_keys : bool, default False
+            Whether to include the group keys in the result index when using
+            ``.apply()`` on the resampled object.
+
+            .. versionadded:: 1.5.0
+
+                Not specifying ``group_keys`` will retain values-dependent behavior
+                from pandas 1.4 and earlier (see :ref:`pandas 1.5.0 Release notes
+                ` for examples).
+
+            .. versionchanged:: 2.0.0
+
+                ``group_keys`` now defaults to ``False``.
+
+        Returns
+        -------
+        pandas.api.typing.Resampler
+            :class:`~pandas.core.Resampler` object.
+
+        See Also
+        --------
+        Series.resample : Resample a Series.
+        DataFrame.resample : Resample a DataFrame.
+        groupby : Group {klass} by mapping, function, label, or list of labels.
+        asfreq : Reindex a {klass} with the given frequency without grouping.
+
+        Notes
+        -----
+        See the `user guide
+        `__
+        for more.
+
+        To learn more about the offset strings, please see `this link
+        `__.
+
+        Examples
+        --------
+        Start by creating a series with 9 one minute timestamps.
+
+        >>> index = pd.date_range('1/1/2000', periods=9, freq='min')
+        >>> series = pd.Series(range(9), index=index)
+        >>> series
+        2000-01-01 00:00:00    0
+        2000-01-01 00:01:00    1
+        2000-01-01 00:02:00    2
+        2000-01-01 00:03:00    3
+        2000-01-01 00:04:00    4
+        2000-01-01 00:05:00    5
+        2000-01-01 00:06:00    6
+        2000-01-01 00:07:00    7
+        2000-01-01 00:08:00    8
+        Freq: min, dtype: int64
+
+        Downsample the series into 3 minute bins and sum the values
+        of the timestamps falling into a bin.
+
+        >>> series.resample('3min').sum()
+        2000-01-01 00:00:00     3
+        2000-01-01 00:03:00    12
+        2000-01-01 00:06:00    21
+        Freq: 3min, dtype: int64
+
+        Downsample the series into 3 minute bins as above, but label each
+        bin using the right edge instead of the left. Please note that the
+        value in the bucket used as the label is not included in the bucket,
+        which it labels. For example, in the original series the
+        bucket ``2000-01-01 00:03:00`` contains the value 3, but the summed
+        value in the resampled bucket with the label ``2000-01-01 00:03:00``
+        does not include 3 (if it did, the summed value would be 6, not 3).
+
+        >>> series.resample('3min', label='right').sum()
+        2000-01-01 00:03:00     3
+        2000-01-01 00:06:00    12
+        2000-01-01 00:09:00    21
+        Freq: 3min, dtype: int64
+
+        To include this value close the right side of the bin interval,
+        as shown below.
+
+        >>> series.resample('3min', label='right', closed='right').sum()
+        2000-01-01 00:00:00     0
+        2000-01-01 00:03:00     6
+        2000-01-01 00:06:00    15
+        2000-01-01 00:09:00    15
+        Freq: 3min, dtype: int64
+
+        Upsample the series into 30 second bins.
+
+        >>> series.resample('30s').asfreq()[0:5]   # Select first 5 rows
+        2000-01-01 00:00:00   0.0
+        2000-01-01 00:00:30   NaN
+        2000-01-01 00:01:00   1.0
+        2000-01-01 00:01:30   NaN
+        2000-01-01 00:02:00   2.0
+        Freq: 30s, dtype: float64
+
+        Upsample the series into 30 second bins and fill the ``NaN``
+        values using the ``ffill`` method.
+
+        >>> series.resample('30s').ffill()[0:5]
+        2000-01-01 00:00:00    0
+        2000-01-01 00:00:30    0
+        2000-01-01 00:01:00    1
+        2000-01-01 00:01:30    1
+        2000-01-01 00:02:00    2
+        Freq: 30s, dtype: int64
+
+        Upsample the series into 30 second bins and fill the
+        ``NaN`` values using the ``bfill`` method.
+
+        >>> series.resample('30s').bfill()[0:5]
+        2000-01-01 00:00:00    0
+        2000-01-01 00:00:30    1
+        2000-01-01 00:01:00    1
+        2000-01-01 00:01:30    2
+        2000-01-01 00:02:00    2
+        Freq: 30s, dtype: int64
+
+        Pass a custom function via ``apply``
+
+        >>> def custom_resampler(arraylike):
+        ...     return np.sum(arraylike) + 5
+        ...
+        >>> series.resample('3min').apply(custom_resampler)
+        2000-01-01 00:00:00     8
+        2000-01-01 00:03:00    17
+        2000-01-01 00:06:00    26
+        Freq: 3min, dtype: int64
+
+        For a Series with a PeriodIndex, the keyword `convention` can be
+        used to control whether to use the start or end of `rule`.
+
+        Resample a year by quarter using 'start' `convention`. Values are
+        assigned to the first quarter of the period.
+
+        >>> s = pd.Series(
+        ...     [1, 2], index=pd.period_range("2012-01-01", freq="Y", periods=2)
+        ... )
+        >>> s
+        2012    1
+        2013    2
+        Freq: Y-DEC, dtype: int64
+        >>> s.resample("Q", convention="start").asfreq()
+        2012Q1    1.0
+        2012Q2    NaN
+        2012Q3    NaN
+        2012Q4    NaN
+        2013Q1    2.0
+        2013Q2    NaN
+        2013Q3    NaN
+        2013Q4    NaN
+        Freq: Q-DEC, dtype: float64
+
+        Resample quarters by month using 'end' `convention`. Values are
+        assigned to the last month of the period.
+
+        >>> q = pd.Series(
+        ...     [1, 2, 3, 4], index=pd.period_range("2018-01-01", freq="Q", periods=4)
+        ... )
+        >>> q
+        2018Q1    1
+        2018Q2    2
+        2018Q3    3
+        2018Q4    4
+        Freq: Q-DEC, dtype: int64
+        >>> q.resample("M", convention="end").asfreq()
+        2018-03    1.0
+        2018-04    NaN
+        2018-05    NaN
+        2018-06    2.0
+        2018-07    NaN
+        2018-08    NaN
+        2018-09    3.0
+        2018-10    NaN
+        2018-11    NaN
+        2018-12    4.0
+        Freq: M, dtype: float64
+
+        For DataFrame objects, the keyword `on` can be used to specify the
+        column instead of the index for resampling.
+
+        >>> d = {{'price': [10, 11, 9, 13, 14, 18, 17, 19],
+        ...      'volume': [50, 60, 40, 100, 50, 100, 40, 50]}}
+        >>> df = pd.DataFrame(d)
+        >>> df['week_starting'] = pd.date_range('01/01/2018',
+        ...                                     periods=8,
+        ...                                     freq='W')
+        >>> df
+           price  volume week_starting
+        0     10      50    2018-01-07
+        1     11      60    2018-01-14
+        2      9      40    2018-01-21
+        3     13     100    2018-01-28
+        4     14      50    2018-02-04
+        5     18     100    2018-02-11
+        6     17      40    2018-02-18
+        7     19      50    2018-02-25
+        >>> df.resample('ME', on='week_starting').mean()
+                       price  volume
+        week_starting
+        2018-01-31     10.75    62.5
+        2018-02-28     17.00    60.0
+
+        For a DataFrame with MultiIndex, the keyword `level` can be used to
+        specify on which level the resampling needs to take place.
+
+        >>> days = pd.date_range('1/1/2000', periods=4, freq='D')
+        >>> d2 = {{'price': [10, 11, 9, 13, 14, 18, 17, 19],
+        ...       'volume': [50, 60, 40, 100, 50, 100, 40, 50]}}
+        >>> df2 = pd.DataFrame(
+        ...     d2,
+        ...     index=pd.MultiIndex.from_product(
+        ...         [days, ['morning', 'afternoon']]
+        ...     )
+        ... )
+        >>> df2
+                              price  volume
+        2000-01-01 morning       10      50
+                   afternoon     11      60
+        2000-01-02 morning        9      40
+                   afternoon     13     100
+        2000-01-03 morning       14      50
+                   afternoon     18     100
+        2000-01-04 morning       17      40
+                   afternoon     19      50
+        >>> df2.resample('D', level=0).sum()
+                    price  volume
+        2000-01-01     21     110
+        2000-01-02     22     140
+        2000-01-03     32     150
+        2000-01-04     36      90
+
+        If you want to adjust the start of the bins based on a fixed timestamp:
+
+        >>> start, end = '2000-10-01 23:30:00', '2000-10-02 00:30:00'
+        >>> rng = pd.date_range(start, end, freq='7min')
+        >>> ts = pd.Series(np.arange(len(rng)) * 3, index=rng)
+        >>> ts
+        2000-10-01 23:30:00     0
+        2000-10-01 23:37:00     3
+        2000-10-01 23:44:00     6
+        2000-10-01 23:51:00     9
+        2000-10-01 23:58:00    12
+        2000-10-02 00:05:00    15
+        2000-10-02 00:12:00    18
+        2000-10-02 00:19:00    21
+        2000-10-02 00:26:00    24
+        Freq: 7min, dtype: int64
+
+        >>> ts.resample('17min').sum()
+        2000-10-01 23:14:00     0
+        2000-10-01 23:31:00     9
+        2000-10-01 23:48:00    21
+        2000-10-02 00:05:00    54
+        2000-10-02 00:22:00    24
+        Freq: 17min, dtype: int64
+
+        >>> ts.resample('17min', origin='epoch').sum()
+        2000-10-01 23:18:00     0
+        2000-10-01 23:35:00    18
+        2000-10-01 23:52:00    27
+        2000-10-02 00:09:00    39
+        2000-10-02 00:26:00    24
+        Freq: 17min, dtype: int64
+
+        >>> ts.resample('17min', origin='2000-01-01').sum()
+        2000-10-01 23:24:00     3
+        2000-10-01 23:41:00    15
+        2000-10-01 23:58:00    45
+        2000-10-02 00:15:00    45
+        Freq: 17min, dtype: int64
+
+        If you want to adjust the start of the bins with an `offset` Timedelta, the two
+        following lines are equivalent:
+
+        >>> ts.resample('17min', origin='start').sum()
+        2000-10-01 23:30:00     9
+        2000-10-01 23:47:00    21
+        2000-10-02 00:04:00    54
+        2000-10-02 00:21:00    24
+        Freq: 17min, dtype: int64
+
+        >>> ts.resample('17min', offset='23h30min').sum()
+        2000-10-01 23:30:00     9
+        2000-10-01 23:47:00    21
+        2000-10-02 00:04:00    54
+        2000-10-02 00:21:00    24
+        Freq: 17min, dtype: int64
+
+        If you want to take the largest Timestamp as the end of the bins:
+
+        >>> ts.resample('17min', origin='end').sum()
+        2000-10-01 23:35:00     0
+        2000-10-01 23:52:00    18
+        2000-10-02 00:09:00    27
+        2000-10-02 00:26:00    63
+        Freq: 17min, dtype: int64
+
+        In contrast with the `start_day`, you can use `end_day` to take the ceiling
+        midnight of the largest Timestamp as the end of the bins and drop the bins
+        not containing data:
+
+        >>> ts.resample('17min', origin='end_day').sum()
+        2000-10-01 23:38:00     3
+        2000-10-01 23:55:00    15
+        2000-10-02 00:12:00    45
+        2000-10-02 00:29:00    45
+        Freq: 17min, dtype: int64
+        """
+        from pandas.core.resample import get_resampler
+
+        if axis is not lib.no_default:
+            axis = self._get_axis_number(axis)
+            if axis == 1:
+                warnings.warn(
+                    "DataFrame.resample with axis=1 is deprecated. Do "
+                    "`frame.T.resample(...)` without axis instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                warnings.warn(
+                    f"The 'axis' keyword in {type(self).__name__}.resample is "
+                    "deprecated and will be removed in a future version.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            axis = 0
+
+        if kind is not lib.no_default:
+            # GH#55895
+            warnings.warn(
+                f"The 'kind' keyword in {type(self).__name__}.resample is "
+                "deprecated and will be removed in a future version. "
+                "Explicitly cast the index to the desired type instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            kind = None
+
+        return get_resampler(
+            cast("Series | DataFrame", self),
+            freq=rule,
+            label=label,
+            closed=closed,
+            axis=axis,
+            kind=kind,
+            convention=convention,
+            key=on,
+            level=level,
+            origin=origin,
+            offset=offset,
+            group_keys=group_keys,
+        )
+
+    @final
+    def first(self, offset) -> Self:
+        """
+        Select initial periods of time series data based on a date offset.
+
+        .. deprecated:: 2.1
+            :meth:`.first` is deprecated and will be removed in a future version.
+            Please create a mask and filter using `.loc` instead.
+
+        For a DataFrame with a sorted DatetimeIndex, this function can
+        select the first few rows based on a date offset.
+
+        Parameters
+        ----------
+        offset : str, DateOffset or dateutil.relativedelta
+            The offset length of the data that will be selected. For instance,
+            '1ME' will display all the rows having their index within the first month.
+
+        Returns
+        -------
+        Series or DataFrame
+            A subset of the caller.
+
+        Raises
+        ------
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
+
+        See Also
+        --------
+        last : Select final periods of time series based on a date offset.
+        at_time : Select values at a particular time of the day.
+        between_time : Select values between particular times of the day.
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
+        >>> ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
+        >>> ts
+                    A
+        2018-04-09  1
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the first 3 days:
+
+        >>> ts.first('3D')
+                    A
+        2018-04-09  1
+        2018-04-11  2
+
+        Notice the data for 3 first calendar days were returned, not the first
+        3 days observed in the dataset, and therefore data for 2018-04-13 was
+        not returned.
+        """
+        warnings.warn(
+            "first is deprecated and will be removed in a future version. "
+            "Please create a mask and filter using `.loc` instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        if not isinstance(self.index, DatetimeIndex):
+            raise TypeError("'first' only supports a DatetimeIndex index")
+
+        if len(self.index) == 0:
+            return self.copy(deep=False)
+
+        offset = to_offset(offset)
+        if not isinstance(offset, Tick) and offset.is_on_offset(self.index[0]):
+            # GH#29623 if first value is end of period, remove offset with n = 1
+            #  before adding the real offset
+            end_date = end = self.index[0] - offset.base + offset
+        else:
+            end_date = end = self.index[0] + offset
+
+        # Tick-like, e.g. 3 weeks
+        if isinstance(offset, Tick) and end_date in self.index:
+            end = self.index.searchsorted(end_date, side="left")
+            return self.iloc[:end]
+
+        return self.loc[:end]
+
+    @final
+    def last(self, offset) -> Self:
+        """
+        Select final periods of time series data based on a date offset.
+
+        .. deprecated:: 2.1
+            :meth:`.last` is deprecated and will be removed in a future version.
+            Please create a mask and filter using `.loc` instead.
+
+        For a DataFrame with a sorted DatetimeIndex, this function
+        selects the last few rows based on a date offset.
+
+        Parameters
+        ----------
+        offset : str, DateOffset, dateutil.relativedelta
+            The offset length of the data that will be selected. For instance,
+            '3D' will display all the rows having their index within the last 3 days.
+
+        Returns
+        -------
+        Series or DataFrame
+            A subset of the caller.
+
+        Raises
+        ------
+        TypeError
+            If the index is not  a :class:`DatetimeIndex`
+
+        See Also
+        --------
+        first : Select initial periods of time series based on a date offset.
+        at_time : Select values at a particular time of the day.
+        between_time : Select values between particular times of the day.
+
+        Notes
+        -----
+        .. deprecated:: 2.1.0
+            Please create a mask and filter using `.loc` instead
+
+        Examples
+        --------
+        >>> i = pd.date_range('2018-04-09', periods=4, freq='2D')
+        >>> ts = pd.DataFrame({'A': [1, 2, 3, 4]}, index=i)
+        >>> ts
+                    A
+        2018-04-09  1
+        2018-04-11  2
+        2018-04-13  3
+        2018-04-15  4
+
+        Get the rows for the last 3 days:
+
+        >>> ts.last('3D')  # doctest: +SKIP
+                    A
+        2018-04-13  3
+        2018-04-15  4
+
+        Notice the data for 3 last calendar days were returned, not the last
+        3 observed days in the dataset, and therefore data for 2018-04-11 was
+        not returned.
+        """
+        warnings.warn(
+            "last is deprecated and will be removed in a future version. "
+            "Please create a mask and filter using `.loc` instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        if not isinstance(self.index, DatetimeIndex):
+            raise TypeError("'last' only supports a DatetimeIndex index")
+
+        if len(self.index) == 0:
+            return self.copy(deep=False)
+
+        offset = to_offset(offset)
+
+        start_date = self.index[-1] - offset
+        start = self.index.searchsorted(start_date, side="right")
+        return self.iloc[start:]
+
+    @final
+    def rank(
+        self,
+        axis: Axis = 0,
+        method: Literal["average", "min", "max", "first", "dense"] = "average",
+        numeric_only: bool_t = False,
+        na_option: Literal["keep", "top", "bottom"] = "keep",
+        ascending: bool_t = True,
+        pct: bool_t = False,
+    ) -> Self:
+        """
+        Compute numerical data ranks (1 through n) along axis.
+
+        By default, equal values are assigned a rank that is the average of the
+        ranks of those values.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns'}, default 0
+            Index to direct ranking.
+            For `Series` this parameter is unused and defaults to 0.
+        method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
+            How to rank the group of records that have the same value (i.e. ties):
+
+            * average: average rank of the group
+            * min: lowest rank in the group
+            * max: highest rank in the group
+            * first: ranks assigned in order they appear in the array
+            * dense: like 'min', but rank always increases by 1 between groups.
+
+        numeric_only : bool, default False
+            For DataFrame objects, rank only numeric columns if set to True.
+
+            .. versionchanged:: 2.0.0
+                The default value of ``numeric_only`` is now ``False``.
+
+        na_option : {'keep', 'top', 'bottom'}, default 'keep'
+            How to rank NaN values:
+
+            * keep: assign NaN rank to NaN values
+            * top: assign lowest rank to NaN values
+            * bottom: assign highest rank to NaN values
+
+        ascending : bool, default True
+            Whether or not the elements should be ranked in ascending order.
+        pct : bool, default False
+            Whether or not to display the returned rankings in percentile
+            form.
+
+        Returns
+        -------
+        same type as caller
+            Return a Series or DataFrame with data ranks as values.
+
+        See Also
+        --------
+        core.groupby.DataFrameGroupBy.rank : Rank of values within each group.
+        core.groupby.SeriesGroupBy.rank : Rank of values within each group.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(data={'Animal': ['cat', 'penguin', 'dog',
+        ...                                    'spider', 'snake'],
+        ...                         'Number_legs': [4, 2, 4, 8, np.nan]})
+        >>> df
+            Animal  Number_legs
+        0      cat          4.0
+        1  penguin          2.0
+        2      dog          4.0
+        3   spider          8.0
+        4    snake          NaN
+
+        Ties are assigned the mean of the ranks (by default) for the group.
+
+        >>> s = pd.Series(range(5), index=list("abcde"))
+        >>> s["d"] = s["b"]
+        >>> s.rank()
+        a    1.0
+        b    2.5
+        c    4.0
+        d    2.5
+        e    5.0
+        dtype: float64
+
+        The following example shows how the method behaves with the above
+        parameters:
+
+        * default_rank: this is the default behaviour obtained without using
+          any parameter.
+        * max_rank: setting ``method = 'max'`` the records that have the
+          same values are ranked using the highest rank (e.g.: since 'cat'
+          and 'dog' are both in the 2nd and 3rd position, rank 3 is assigned.)
+        * NA_bottom: choosing ``na_option = 'bottom'``, if there are records
+          with NaN values they are placed at the bottom of the ranking.
+        * pct_rank: when setting ``pct = True``, the ranking is expressed as
+          percentile rank.
+
+        >>> df['default_rank'] = df['Number_legs'].rank()
+        >>> df['max_rank'] = df['Number_legs'].rank(method='max')
+        >>> df['NA_bottom'] = df['Number_legs'].rank(na_option='bottom')
+        >>> df['pct_rank'] = df['Number_legs'].rank(pct=True)
+        >>> df
+            Animal  Number_legs  default_rank  max_rank  NA_bottom  pct_rank
+        0      cat          4.0           2.5       3.0        2.5     0.625
+        1  penguin          2.0           1.0       1.0        1.0     0.250
+        2      dog          4.0           2.5       3.0        2.5     0.625
+        3   spider          8.0           4.0       4.0        4.0     1.000
+        4    snake          NaN           NaN       NaN        5.0       NaN
+        """
+        axis_int = self._get_axis_number(axis)
+
+        if na_option not in {"keep", "top", "bottom"}:
+            msg = "na_option must be one of 'keep', 'top', or 'bottom'"
+            raise ValueError(msg)
+
+        def ranker(data):
+            if data.ndim == 2:
+                # i.e. DataFrame, we cast to ndarray
+                values = data.values
+            else:
+                # i.e. Series, can dispatch to EA
+                values = data._values
+
+            if isinstance(values, ExtensionArray):
+                ranks = values._rank(
+                    axis=axis_int,
+                    method=method,
+                    ascending=ascending,
+                    na_option=na_option,
+                    pct=pct,
+                )
+            else:
+                ranks = algos.rank(
+                    values,
+                    axis=axis_int,
+                    method=method,
+                    ascending=ascending,
+                    na_option=na_option,
+                    pct=pct,
+                )
+
+            ranks_obj = self._constructor(ranks, **data._construct_axes_dict())
+            return ranks_obj.__finalize__(self, method="rank")
+
+        if numeric_only:
+            if self.ndim == 1 and not is_numeric_dtype(self.dtype):
+                # GH#47500
+                raise TypeError(
+                    "Series.rank does not allow numeric_only=True with "
+                    "non-numeric dtype."
+                )
+            data = self._get_numeric_data()
+        else:
+            data = self
+
+        return ranker(data)
+
+    @doc(_shared_docs["compare"], klass=_shared_doc_kwargs["klass"])
+    def compare(
+        self,
+        other,
+        align_axis: Axis = 1,
+        keep_shape: bool_t = False,
+        keep_equal: bool_t = False,
+        result_names: Suffixes = ("self", "other"),
+    ):
+        if type(self) is not type(other):
+            cls_self, cls_other = type(self).__name__, type(other).__name__
+            raise TypeError(
+                f"can only compare '{cls_self}' (not '{cls_other}') with '{cls_self}'"
+            )
+
+        mask = ~((self == other) | (self.isna() & other.isna()))
+        mask.fillna(True, inplace=True)
+
+        if not keep_equal:
+            self = self.where(mask)
+            other = other.where(mask)
+
+        if not keep_shape:
+            if isinstance(self, ABCDataFrame):
+                cmask = mask.any()
+                rmask = mask.any(axis=1)
+                self = self.loc[rmask, cmask]
+                other = other.loc[rmask, cmask]
+            else:
+                self = self[mask]
+                other = other[mask]
+        if not isinstance(result_names, tuple):
+            raise TypeError(
+                f"Passing 'result_names' as a {type(result_names)} is not "
+                "supported. Provide 'result_names' as a tuple instead."
+            )
+
+        if align_axis in (1, "columns"):  # This is needed for Series
+            axis = 1
+        else:
+            axis = self._get_axis_number(align_axis)
+
+        # error: List item 0 has incompatible type "NDFrame"; expected
+        #  "Union[Series, DataFrame]"
+        diff = concat(
+            [self, other],  # type: ignore[list-item]
+            axis=axis,
+            keys=result_names,
+        )
+
+        if axis >= self.ndim:
+            # No need to reorganize data if stacking on new axis
+            # This currently applies for stacking two Series on columns
+            return diff
+
+        ax = diff._get_axis(axis)
+        ax_names = np.array(ax.names)
+
+        # set index names to positions to avoid confusion
+        ax.names = np.arange(len(ax_names))
+
+        # bring self-other to inner level
+        order = list(range(1, ax.nlevels)) + [0]
+        if isinstance(diff, ABCDataFrame):
+            diff = diff.reorder_levels(order, axis=axis)
+        else:
+            diff = diff.reorder_levels(order)
+
+        # restore the index names in order
+        diff._get_axis(axis=axis).names = ax_names[order]
+
+        # reorder axis to keep things organized
+        indices = (
+            np.arange(diff.shape[axis]).reshape([2, diff.shape[axis] // 2]).T.flatten()
+        )
+        diff = diff.take(indices, axis=axis)
+
+        return diff
+
+    @final
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+    )
+    def align(
+        self,
+        other: NDFrameT,
+        join: AlignJoin = "outer",
+        axis: Axis | None = None,
+        level: Level | None = None,
+        copy: bool_t | None = None,
+        fill_value: Hashable | None = None,
+        method: FillnaOptions | None | lib.NoDefault = lib.no_default,
+        limit: int | None | lib.NoDefault = lib.no_default,
+        fill_axis: Axis | lib.NoDefault = lib.no_default,
+        broadcast_axis: Axis | None | lib.NoDefault = lib.no_default,
+    ) -> tuple[Self, NDFrameT]:
+        """
+        Align two objects on their axes with the specified join method.
+
+        Join method is specified for each axis Index.
+
+        Parameters
+        ----------
+        other : DataFrame or Series
+        join : {{'outer', 'inner', 'left', 'right'}}, default 'outer'
+            Type of alignment to be performed.
+
+            * left: use only keys from left frame, preserve key order.
+            * right: use only keys from right frame, preserve key order.
+            * outer: use union of keys from both frames, sort keys lexicographically.
+            * inner: use intersection of keys from both frames,
+              preserve the order of the left keys.
+
+        axis : allowed axis of the other object, default None
+            Align on index (0), columns (1), or both (None).
+        level : int or level name, default None
+            Broadcast across a level, matching Index values on the
+            passed MultiIndex level.
+        copy : bool, default True
+            Always returns new objects. If copy=False and no reindexing is
+            required then original objects are returned.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        fill_value : scalar, default np.nan
+            Value to use for missing values. Defaults to NaN, but can be any
+            "compatible" value.
+        method : {{'backfill', 'bfill', 'pad', 'ffill', None}}, default None
+            Method to use for filling holes in reindexed Series:
+
+            - pad / ffill: propagate last valid observation forward to next valid.
+            - backfill / bfill: use NEXT valid observation to fill gap.
+
+            .. deprecated:: 2.1
+
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill. In other words, if there is
+            a gap with more than this number of consecutive NaNs, it will only
+            be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+
+            .. deprecated:: 2.1
+
+        fill_axis : {axes_single_arg}, default 0
+            Filling axis, method and limit.
+
+            .. deprecated:: 2.1
+
+        broadcast_axis : {axes_single_arg}, default None
+            Broadcast values along this axis, if aligning two objects of
+            different dimensions.
+
+            .. deprecated:: 2.1
+
+        Returns
+        -------
+        tuple of ({klass}, type of other)
+            Aligned objects.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     [[1, 2, 3, 4], [6, 7, 8, 9]], columns=["D", "B", "E", "A"], index=[1, 2]
+        ... )
+        >>> other = pd.DataFrame(
+        ...     [[10, 20, 30, 40], [60, 70, 80, 90], [600, 700, 800, 900]],
+        ...     columns=["A", "B", "C", "D"],
+        ...     index=[2, 3, 4],
+        ... )
+        >>> df
+           D  B  E  A
+        1  1  2  3  4
+        2  6  7  8  9
+        >>> other
+            A    B    C    D
+        2   10   20   30   40
+        3   60   70   80   90
+        4  600  700  800  900
+
+        Align on columns:
+
+        >>> left, right = df.align(other, join="outer", axis=1)
+        >>> left
+           A  B   C  D  E
+        1  4  2 NaN  1  3
+        2  9  7 NaN  6  8
+        >>> right
+            A    B    C    D   E
+        2   10   20   30   40 NaN
+        3   60   70   80   90 NaN
+        4  600  700  800  900 NaN
+
+        We can also align on the index:
+
+        >>> left, right = df.align(other, join="outer", axis=0)
+        >>> left
+            D    B    E    A
+        1  1.0  2.0  3.0  4.0
+        2  6.0  7.0  8.0  9.0
+        3  NaN  NaN  NaN  NaN
+        4  NaN  NaN  NaN  NaN
+        >>> right
+            A      B      C      D
+        1    NaN    NaN    NaN    NaN
+        2   10.0   20.0   30.0   40.0
+        3   60.0   70.0   80.0   90.0
+        4  600.0  700.0  800.0  900.0
+
+        Finally, the default `axis=None` will align on both index and columns:
+
+        >>> left, right = df.align(other, join="outer", axis=None)
+        >>> left
+             A    B   C    D    E
+        1  4.0  2.0 NaN  1.0  3.0
+        2  9.0  7.0 NaN  6.0  8.0
+        3  NaN  NaN NaN  NaN  NaN
+        4  NaN  NaN NaN  NaN  NaN
+        >>> right
+               A      B      C      D   E
+        1    NaN    NaN    NaN    NaN NaN
+        2   10.0   20.0   30.0   40.0 NaN
+        3   60.0   70.0   80.0   90.0 NaN
+        4  600.0  700.0  800.0  900.0 NaN
+        """
+        if (
+            method is not lib.no_default
+            or limit is not lib.no_default
+            or fill_axis is not lib.no_default
+        ):
+            # GH#51856
+            warnings.warn(
+                "The 'method', 'limit', and 'fill_axis' keywords in "
+                f"{type(self).__name__}.align are deprecated and will be removed "
+                "in a future version. Call fillna directly on the returned objects "
+                "instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if fill_axis is lib.no_default:
+            fill_axis = 0
+        if method is lib.no_default:
+            method = None
+        if limit is lib.no_default:
+            limit = None
+
+        if method is not None:
+            method = clean_fill_method(method)
+
+        if broadcast_axis is not lib.no_default:
+            # GH#51856
+            # TODO(3.0): enforcing this deprecation will close GH#13194
+            msg = (
+                f"The 'broadcast_axis' keyword in {type(self).__name__}.align is "
+                "deprecated and will be removed in a future version."
+            )
+            if broadcast_axis is not None:
+                if self.ndim == 1 and other.ndim == 2:
+                    msg += (
+                        " Use left = DataFrame({col: left for col in right.columns}, "
+                        "index=right.index) before calling `left.align(right)` instead."
+                    )
+                elif self.ndim == 2 and other.ndim == 1:
+                    msg += (
+                        " Use right = DataFrame({col: right for col in left.columns}, "
+                        "index=left.index) before calling `left.align(right)` instead"
+                    )
+            warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+        else:
+            broadcast_axis = None
+
+        if broadcast_axis == 1 and self.ndim != other.ndim:
+            if isinstance(self, ABCSeries):
+                # this means other is a DataFrame, and we need to broadcast
+                # self
+                cons = self._constructor_expanddim
+                df = cons(
+                    {c: self for c in other.columns}, **other._construct_axes_dict()
+                )
+                # error: Incompatible return value type (got "Tuple[DataFrame,
+                # DataFrame]", expected "Tuple[Self, NDFrameT]")
+                return df._align_frame(  # type: ignore[return-value]
+                    other,  # type: ignore[arg-type]
+                    join=join,
+                    axis=axis,
+                    level=level,
+                    copy=copy,
+                    fill_value=fill_value,
+                    method=method,
+                    limit=limit,
+                    fill_axis=fill_axis,
+                )[:2]
+            elif isinstance(other, ABCSeries):
+                # this means self is a DataFrame, and we need to broadcast
+                # other
+                cons = other._constructor_expanddim
+                df = cons(
+                    {c: other for c in self.columns}, **self._construct_axes_dict()
+                )
+                # error: Incompatible return value type (got "Tuple[NDFrameT,
+                # DataFrame]", expected "Tuple[Self, NDFrameT]")
+                return self._align_frame(  # type: ignore[return-value]
+                    df,
+                    join=join,
+                    axis=axis,
+                    level=level,
+                    copy=copy,
+                    fill_value=fill_value,
+                    method=method,
+                    limit=limit,
+                    fill_axis=fill_axis,
+                )[:2]
+
+        _right: DataFrame | Series
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+        if isinstance(other, ABCDataFrame):
+            left, _right, join_index = self._align_frame(
+                other,
+                join=join,
+                axis=axis,
+                level=level,
+                copy=copy,
+                fill_value=fill_value,
+                method=method,
+                limit=limit,
+                fill_axis=fill_axis,
+            )
+
+        elif isinstance(other, ABCSeries):
+            left, _right, join_index = self._align_series(
+                other,
+                join=join,
+                axis=axis,
+                level=level,
+                copy=copy,
+                fill_value=fill_value,
+                method=method,
+                limit=limit,
+                fill_axis=fill_axis,
+            )
+        else:  # pragma: no cover
+            raise TypeError(f"unsupported type: {type(other)}")
+
+        right = cast(NDFrameT, _right)
+        if self.ndim == 1 or axis == 0:
+            # If we are aligning timezone-aware DatetimeIndexes and the timezones
+            #  do not match, convert both to UTC.
+            if isinstance(left.index.dtype, DatetimeTZDtype):
+                if left.index.tz != right.index.tz:
+                    if join_index is not None:
+                        # GH#33671 copy to ensure we don't change the index on
+                        #  our original Series
+                        left = left.copy(deep=False)
+                        right = right.copy(deep=False)
+                        left.index = join_index
+                        right.index = join_index
+
+        left = left.__finalize__(self)
+        right = right.__finalize__(other)
+        return left, right
+
+    @final
+    def _align_frame(
+        self,
+        other: DataFrame,
+        join: AlignJoin = "outer",
+        axis: Axis | None = None,
+        level=None,
+        copy: bool_t | None = None,
+        fill_value=None,
+        method=None,
+        limit: int | None = None,
+        fill_axis: Axis = 0,
+    ) -> tuple[Self, DataFrame, Index | None]:
+        # defaults
+        join_index, join_columns = None, None
+        ilidx, iridx = None, None
+        clidx, cridx = None, None
+
+        is_series = isinstance(self, ABCSeries)
+
+        if (axis is None or axis == 0) and not self.index.equals(other.index):
+            join_index, ilidx, iridx = self.index.join(
+                other.index, how=join, level=level, return_indexers=True
+            )
+
+        if (
+            (axis is None or axis == 1)
+            and not is_series
+            and not self.columns.equals(other.columns)
+        ):
+            join_columns, clidx, cridx = self.columns.join(
+                other.columns, how=join, level=level, return_indexers=True
+            )
+
+        if is_series:
+            reindexers = {0: [join_index, ilidx]}
+        else:
+            reindexers = {0: [join_index, ilidx], 1: [join_columns, clidx]}
+
+        left = self._reindex_with_indexers(
+            reindexers, copy=copy, fill_value=fill_value, allow_dups=True
+        )
+        # other must be always DataFrame
+        right = other._reindex_with_indexers(
+            {0: [join_index, iridx], 1: [join_columns, cridx]},
+            copy=copy,
+            fill_value=fill_value,
+            allow_dups=True,
+        )
+
+        if method is not None:
+            left = left._pad_or_backfill(method, axis=fill_axis, limit=limit)
+            right = right._pad_or_backfill(method, axis=fill_axis, limit=limit)
+
+        return left, right, join_index
+
+    @final
+    def _align_series(
+        self,
+        other: Series,
+        join: AlignJoin = "outer",
+        axis: Axis | None = None,
+        level=None,
+        copy: bool_t | None = None,
+        fill_value=None,
+        method=None,
+        limit: int | None = None,
+        fill_axis: Axis = 0,
+    ) -> tuple[Self, Series, Index | None]:
+        is_series = isinstance(self, ABCSeries)
+        if copy and using_copy_on_write():
+            copy = False
+
+        if (not is_series and axis is None) or axis not in [None, 0, 1]:
+            raise ValueError("Must specify axis=0 or 1")
+
+        if is_series and axis == 1:
+            raise ValueError("cannot align series to a series other than axis 0")
+
+        # series/series compat, other must always be a Series
+        if not axis:
+            # equal
+            if self.index.equals(other.index):
+                join_index, lidx, ridx = None, None, None
+            else:
+                join_index, lidx, ridx = self.index.join(
+                    other.index, how=join, level=level, return_indexers=True
+                )
+
+            if is_series:
+                left = self._reindex_indexer(join_index, lidx, copy)
+            elif lidx is None or join_index is None:
+                left = self.copy(deep=copy)
+            else:
+                new_mgr = self._mgr.reindex_indexer(join_index, lidx, axis=1, copy=copy)
+                left = self._constructor_from_mgr(new_mgr, axes=new_mgr.axes)
+
+            right = other._reindex_indexer(join_index, ridx, copy)
+
+        else:
+            # one has > 1 ndim
+            fdata = self._mgr
+            join_index = self.axes[1]
+            lidx, ridx = None, None
+            if not join_index.equals(other.index):
+                join_index, lidx, ridx = join_index.join(
+                    other.index, how=join, level=level, return_indexers=True
+                )
+
+            if lidx is not None:
+                bm_axis = self._get_block_manager_axis(1)
+                fdata = fdata.reindex_indexer(join_index, lidx, axis=bm_axis)
+
+            if copy and fdata is self._mgr:
+                fdata = fdata.copy()
+
+            left = self._constructor_from_mgr(fdata, axes=fdata.axes)
+
+            if ridx is None:
+                right = other.copy(deep=copy)
+            else:
+                right = other.reindex(join_index, level=level)
+
+        # fill
+        fill_na = notna(fill_value) or (method is not None)
+        if fill_na:
+            fill_value, method = validate_fillna_kwargs(fill_value, method)
+            if method is not None:
+                left = left._pad_or_backfill(method, limit=limit, axis=fill_axis)
+                right = right._pad_or_backfill(method, limit=limit)
+            else:
+                left = left.fillna(fill_value, limit=limit, axis=fill_axis)
+                right = right.fillna(fill_value, limit=limit)
+
+        return left, right, join_index
+
+    @final
+    def _where(
+        self,
+        cond,
+        other=lib.no_default,
+        inplace: bool_t = False,
+        axis: Axis | None = None,
+        level=None,
+        warn: bool_t = True,
+    ):
+        """
+        Equivalent to public method `where`, except that `other` is not
+        applied as a function even if callable. Used in __setitem__.
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if axis is not None:
+            axis = self._get_axis_number(axis)
+
+        # align the cond to same shape as myself
+        cond = common.apply_if_callable(cond, self)
+        if isinstance(cond, NDFrame):
+            # CoW: Make sure reference is not kept alive
+            if cond.ndim == 1 and self.ndim == 2:
+                cond = cond._constructor_expanddim(
+                    {i: cond for i in range(len(self.columns))},
+                    copy=False,
+                )
+                cond.columns = self.columns
+            cond = cond.align(self, join="right", copy=False)[0]
+        else:
+            if not hasattr(cond, "shape"):
+                cond = np.asanyarray(cond)
+            if cond.shape != self.shape:
+                raise ValueError("Array conditional must be same shape as self")
+            cond = self._constructor(cond, **self._construct_axes_dict(), copy=False)
+
+        # make sure we are boolean
+        fill_value = bool(inplace)
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                "Downcasting object dtype arrays",
+                category=FutureWarning,
+            )
+            cond = cond.fillna(fill_value)
+        cond = cond.infer_objects(copy=False)
+
+        msg = "Boolean array expected for the condition, not {dtype}"
+
+        if not cond.empty:
+            if not isinstance(cond, ABCDataFrame):
+                # This is a single-dimensional object.
+                if not is_bool_dtype(cond):
+                    raise ValueError(msg.format(dtype=cond.dtype))
+            else:
+                for _dt in cond.dtypes:
+                    if not is_bool_dtype(_dt):
+                        raise ValueError(msg.format(dtype=_dt))
+                if cond._mgr.any_extension_types:
+                    # GH51574: avoid object ndarray conversion later on
+                    cond = cond._constructor(
+                        cond.to_numpy(dtype=bool, na_value=fill_value),
+                        **cond._construct_axes_dict(),
+                    )
+        else:
+            # GH#21947 we have an empty DataFrame/Series, could be object-dtype
+            cond = cond.astype(bool)
+
+        cond = -cond if inplace else cond
+        cond = cond.reindex(self._info_axis, axis=self._info_axis_number, copy=False)
+
+        # try to align with other
+        if isinstance(other, NDFrame):
+            # align with me
+            if other.ndim <= self.ndim:
+                # CoW: Make sure reference is not kept alive
+                other = self.align(
+                    other,
+                    join="left",
+                    axis=axis,
+                    level=level,
+                    fill_value=None,
+                    copy=False,
+                )[1]
+
+                # if we are NOT aligned, raise as we cannot where index
+                if axis is None and not other._indexed_same(self):
+                    raise InvalidIndexError
+
+                if other.ndim < self.ndim:
+                    # TODO(EA2D): avoid object-dtype cast in EA case GH#38729
+                    other = other._values
+                    if axis == 0:
+                        other = np.reshape(other, (-1, 1))
+                    elif axis == 1:
+                        other = np.reshape(other, (1, -1))
+
+                    other = np.broadcast_to(other, self.shape)
+
+            # slice me out of the other
+            else:
+                raise NotImplementedError(
+                    "cannot align with a higher dimensional NDFrame"
+                )
+
+        elif not isinstance(other, (MultiIndex, NDFrame)):
+            # mainly just catching Index here
+            other = extract_array(other, extract_numpy=True)
+
+        if isinstance(other, (np.ndarray, ExtensionArray)):
+            if other.shape != self.shape:
+                if self.ndim != 1:
+                    # In the ndim == 1 case we may have
+                    #  other length 1, which we treat as scalar (GH#2745, GH#4192)
+                    #  or len(other) == icond.sum(), which we treat like
+                    #  __setitem__ (GH#3235)
+                    raise ValueError(
+                        "other must be the same shape as self when an ndarray"
+                    )
+
+            # we are the same shape, so create an actual object for alignment
+            else:
+                other = self._constructor(
+                    other, **self._construct_axes_dict(), copy=False
+                )
+
+        if axis is None:
+            axis = 0
+
+        if self.ndim == getattr(other, "ndim", 0):
+            align = True
+        else:
+            align = self._get_axis_number(axis) == 1
+
+        if inplace:
+            # we may have different type blocks come out of putmask, so
+            # reconstruct the block manager
+
+            new_data = self._mgr.putmask(mask=cond, new=other, align=align, warn=warn)
+            result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+            return self._update_inplace(result)
+
+        else:
+            new_data = self._mgr.where(
+                other=other,
+                cond=cond,
+                align=align,
+            )
+            result = self._constructor_from_mgr(new_data, axes=new_data.axes)
+            return result.__finalize__(self)
+
+    @overload
+    def where(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: Literal[False] = ...,
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def where(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: Literal[True],
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def where(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: bool_t = ...,
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        cond="True",
+        cond_rev="False",
+        name="where",
+        name_other="mask",
+    )
+    def where(
+        self,
+        cond,
+        other=np.nan,
+        *,
+        inplace: bool_t = False,
+        axis: Axis | None = None,
+        level: Level | None = None,
+    ) -> Self | None:
+        """
+        Replace values where the condition is {cond_rev}.
+
+        Parameters
+        ----------
+        cond : bool {klass}, array-like, or callable
+            Where `cond` is {cond}, keep the original value. Where
+            {cond_rev}, replace with corresponding value from `other`.
+            If `cond` is callable, it is computed on the {klass} and
+            should return boolean {klass} or array. The callable must
+            not change input {klass} (though pandas doesn't check it).
+        other : scalar, {klass}, or callable
+            Entries where `cond` is {cond_rev} are replaced with
+            corresponding value from `other`.
+            If other is callable, it is computed on the {klass} and
+            should return scalar or {klass}. The callable must not
+            change input {klass} (though pandas doesn't check it).
+            If not specified, entries will be filled with the corresponding
+            NULL value (``np.nan`` for numpy dtypes, ``pd.NA`` for extension
+            dtypes).
+        inplace : bool, default False
+            Whether to perform the operation in place on the data.
+        axis : int, default None
+            Alignment axis if needed. For `Series` this parameter is
+            unused and defaults to 0.
+        level : int, default None
+            Alignment level if needed.
+
+        Returns
+        -------
+        Same type as caller or None if ``inplace=True``.
+
+        See Also
+        --------
+        :func:`DataFrame.{name_other}` : Return an object of same shape as
+            self.
+
+        Notes
+        -----
+        The {name} method is an application of the if-then idiom. For each
+        element in the calling DataFrame, if ``cond`` is ``{cond}`` the
+        element is used; otherwise the corresponding element from the DataFrame
+        ``other`` is used. If the axis of ``other`` does not align with axis of
+        ``cond`` {klass}, the misaligned index positions will be filled with
+        {cond_rev}.
+
+        The signature for :func:`DataFrame.where` differs from
+        :func:`numpy.where`. Roughly ``df1.where(m, df2)`` is equivalent to
+        ``np.where(m, df1, df2)``.
+
+        For further details and examples see the ``{name}`` documentation in
+        :ref:`indexing `.
+
+        The dtype of the object takes precedence. The fill value is casted to
+        the object's dtype, if this can be done losslessly.
+
+        Examples
+        --------
+        >>> s = pd.Series(range(5))
+        >>> s.where(s > 0)
+        0    NaN
+        1    1.0
+        2    2.0
+        3    3.0
+        4    4.0
+        dtype: float64
+        >>> s.mask(s > 0)
+        0    0.0
+        1    NaN
+        2    NaN
+        3    NaN
+        4    NaN
+        dtype: float64
+
+        >>> s = pd.Series(range(5))
+        >>> t = pd.Series([True, False])
+        >>> s.where(t, 99)
+        0     0
+        1    99
+        2    99
+        3    99
+        4    99
+        dtype: int64
+        >>> s.mask(t, 99)
+        0    99
+        1     1
+        2    99
+        3    99
+        4    99
+        dtype: int64
+
+        >>> s.where(s > 1, 10)
+        0    10
+        1    10
+        2    2
+        3    3
+        4    4
+        dtype: int64
+        >>> s.mask(s > 1, 10)
+        0     0
+        1     1
+        2    10
+        3    10
+        4    10
+        dtype: int64
+
+        >>> df = pd.DataFrame(np.arange(10).reshape(-1, 2), columns=['A', 'B'])
+        >>> df
+           A  B
+        0  0  1
+        1  2  3
+        2  4  5
+        3  6  7
+        4  8  9
+        >>> m = df % 3 == 0
+        >>> df.where(m, -df)
+           A  B
+        0  0 -1
+        1 -2  3
+        2 -4 -5
+        3  6 -7
+        4 -8  9
+        >>> df.where(m, -df) == np.where(m, df, -df)
+              A     B
+        0  True  True
+        1  True  True
+        2  True  True
+        3  True  True
+        4  True  True
+        >>> df.where(m, -df) == df.mask(~m, -df)
+              A     B
+        0  True  True
+        1  True  True
+        2  True  True
+        3  True  True
+        4  True  True
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and hasattr(self, "_cacher"):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        other = common.apply_if_callable(other, self)
+        return self._where(cond, other, inplace, axis, level)
+
+    @overload
+    def mask(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: Literal[False] = ...,
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def mask(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: Literal[True],
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def mask(
+        self,
+        cond,
+        other=...,
+        *,
+        inplace: bool_t = ...,
+        axis: Axis | None = ...,
+        level: Level = ...,
+    ) -> Self | None:
+        ...
+
+    @final
+    @doc(
+        where,
+        klass=_shared_doc_kwargs["klass"],
+        cond="False",
+        cond_rev="True",
+        name="mask",
+        name_other="where",
+    )
+    def mask(
+        self,
+        cond,
+        other=lib.no_default,
+        *,
+        inplace: bool_t = False,
+        axis: Axis | None = None,
+        level: Level | None = None,
+    ) -> Self | None:
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if inplace:
+            if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+                if sys.getrefcount(self) <= REF_COUNT:
+                    warnings.warn(
+                        _chained_assignment_method_msg,
+                        ChainedAssignmentError,
+                        stacklevel=2,
+                    )
+            elif (
+                not PYPY
+                and not WARNING_CHECK_DISABLED
+                and not using_copy_on_write()
+                and self._is_view_after_cow_rules()
+            ):
+                ctr = sys.getrefcount(self)
+                ref_count = REF_COUNT
+                if isinstance(self, ABCSeries) and hasattr(self, "_cacher"):
+                    # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                    ref_count += 1
+                if ctr <= ref_count:
+                    warnings.warn(
+                        _chained_assignment_warning_method_msg,
+                        FutureWarning,
+                        stacklevel=2,
+                    )
+
+        cond = common.apply_if_callable(cond, self)
+        other = common.apply_if_callable(other, self)
+
+        # see gh-21891
+        if not hasattr(cond, "__invert__"):
+            cond = np.array(cond)
+
+        return self._where(
+            ~cond,
+            other=other,
+            inplace=inplace,
+            axis=axis,
+            level=level,
+        )
+
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def shift(
+        self,
+        periods: int | Sequence[int] = 1,
+        freq=None,
+        axis: Axis = 0,
+        fill_value: Hashable = lib.no_default,
+        suffix: str | None = None,
+    ) -> Self | DataFrame:
+        """
+        Shift index by desired number of periods with an optional time `freq`.
+
+        When `freq` is not passed, shift the index without realigning the data.
+        If `freq` is passed (in this case, the index must be date or datetime,
+        or it will raise a `NotImplementedError`), the index will be
+        increased using the periods and the `freq`. `freq` can be inferred
+        when specified as "infer" as long as either freq or inferred_freq
+        attribute is set in the index.
+
+        Parameters
+        ----------
+        periods : int or Sequence
+            Number of periods to shift. Can be positive or negative.
+            If an iterable of ints, the data will be shifted once by each int.
+            This is equivalent to shifting by one value at a time and
+            concatenating all resulting frames. The resulting columns will have
+            the shift suffixed to their column names. For multiple periods,
+            axis must not be 1.
+        freq : DateOffset, tseries.offsets, timedelta, or str, optional
+            Offset to use from the tseries module or time rule (e.g. 'EOM').
+            If `freq` is specified then the index values are shifted but the
+            data is not realigned. That is, use `freq` if you would like to
+            extend the index when shifting and preserve the original data.
+            If `freq` is specified as "infer" then it will be inferred from
+            the freq or inferred_freq attributes of the index. If neither of
+            those attributes exist, a ValueError is thrown.
+        axis : {{0 or 'index', 1 or 'columns', None}}, default None
+            Shift direction. For `Series` this parameter is unused and defaults to 0.
+        fill_value : object, optional
+            The scalar value to use for newly introduced missing values.
+            the default depends on the dtype of `self`.
+            For numeric data, ``np.nan`` is used.
+            For datetime, timedelta, or period data, etc. :attr:`NaT` is used.
+            For extension dtypes, ``self.dtype.na_value`` is used.
+        suffix : str, optional
+            If str and periods is an iterable, this is added after the column
+            name and before the shift value for each shifted column name.
+
+        Returns
+        -------
+        {klass}
+            Copy of input object, shifted.
+
+        See Also
+        --------
+        Index.shift : Shift values of Index.
+        DatetimeIndex.shift : Shift values of DatetimeIndex.
+        PeriodIndex.shift : Shift values of PeriodIndex.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({{"Col1": [10, 20, 15, 30, 45],
+        ...                    "Col2": [13, 23, 18, 33, 48],
+        ...                    "Col3": [17, 27, 22, 37, 52]}},
+        ...                   index=pd.date_range("2020-01-01", "2020-01-05"))
+        >>> df
+                    Col1  Col2  Col3
+        2020-01-01    10    13    17
+        2020-01-02    20    23    27
+        2020-01-03    15    18    22
+        2020-01-04    30    33    37
+        2020-01-05    45    48    52
+
+        >>> df.shift(periods=3)
+                    Col1  Col2  Col3
+        2020-01-01   NaN   NaN   NaN
+        2020-01-02   NaN   NaN   NaN
+        2020-01-03   NaN   NaN   NaN
+        2020-01-04  10.0  13.0  17.0
+        2020-01-05  20.0  23.0  27.0
+
+        >>> df.shift(periods=1, axis="columns")
+                    Col1  Col2  Col3
+        2020-01-01   NaN    10    13
+        2020-01-02   NaN    20    23
+        2020-01-03   NaN    15    18
+        2020-01-04   NaN    30    33
+        2020-01-05   NaN    45    48
+
+        >>> df.shift(periods=3, fill_value=0)
+                    Col1  Col2  Col3
+        2020-01-01     0     0     0
+        2020-01-02     0     0     0
+        2020-01-03     0     0     0
+        2020-01-04    10    13    17
+        2020-01-05    20    23    27
+
+        >>> df.shift(periods=3, freq="D")
+                    Col1  Col2  Col3
+        2020-01-04    10    13    17
+        2020-01-05    20    23    27
+        2020-01-06    15    18    22
+        2020-01-07    30    33    37
+        2020-01-08    45    48    52
+
+        >>> df.shift(periods=3, freq="infer")
+                    Col1  Col2  Col3
+        2020-01-04    10    13    17
+        2020-01-05    20    23    27
+        2020-01-06    15    18    22
+        2020-01-07    30    33    37
+        2020-01-08    45    48    52
+
+        >>> df['Col1'].shift(periods=[0, 1, 2])
+                    Col1_0  Col1_1  Col1_2
+        2020-01-01      10     NaN     NaN
+        2020-01-02      20    10.0     NaN
+        2020-01-03      15    20.0    10.0
+        2020-01-04      30    15.0    20.0
+        2020-01-05      45    30.0    15.0
+        """
+        axis = self._get_axis_number(axis)
+
+        if freq is not None and fill_value is not lib.no_default:
+            # GH#53832
+            warnings.warn(
+                "Passing a 'freq' together with a 'fill_value' silently ignores "
+                "the fill_value and is deprecated. This will raise in a future "
+                "version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            fill_value = lib.no_default
+
+        if periods == 0:
+            return self.copy(deep=None)
+
+        if is_list_like(periods) and isinstance(self, ABCSeries):
+            return self.to_frame().shift(
+                periods=periods, freq=freq, axis=axis, fill_value=fill_value
+            )
+        periods = cast(int, periods)
+
+        if freq is None:
+            # when freq is None, data is shifted, index is not
+            axis = self._get_axis_number(axis)
+            assert axis == 0  # axis == 1 cases handled in DataFrame.shift
+            new_data = self._mgr.shift(periods=periods, fill_value=fill_value)
+            return self._constructor_from_mgr(
+                new_data, axes=new_data.axes
+            ).__finalize__(self, method="shift")
+
+        return self._shift_with_freq(periods, axis, freq)
+
+    @final
+    def _shift_with_freq(self, periods: int, axis: int, freq) -> Self:
+        # see shift.__doc__
+        # when freq is given, index is shifted, data is not
+        index = self._get_axis(axis)
+
+        if freq == "infer":
+            freq = getattr(index, "freq", None)
+
+            if freq is None:
+                freq = getattr(index, "inferred_freq", None)
+
+            if freq is None:
+                msg = "Freq was not set in the index hence cannot be inferred"
+                raise ValueError(msg)
+
+        elif isinstance(freq, str):
+            is_period = isinstance(index, PeriodIndex)
+            freq = to_offset(freq, is_period=is_period)
+
+        if isinstance(index, PeriodIndex):
+            orig_freq = to_offset(index.freq)
+            if freq != orig_freq:
+                assert orig_freq is not None  # for mypy
+                raise ValueError(
+                    f"Given freq {freq_to_period_freqstr(freq.n, freq.name)} "
+                    f"does not match PeriodIndex freq "
+                    f"{freq_to_period_freqstr(orig_freq.n, orig_freq.name)}"
+                )
+            new_ax = index.shift(periods)
+        else:
+            new_ax = index.shift(periods, freq)
+
+        result = self.set_axis(new_ax, axis=axis)
+        return result.__finalize__(self, method="shift")
+
+    @final
+    def truncate(
+        self,
+        before=None,
+        after=None,
+        axis: Axis | None = None,
+        copy: bool_t | None = None,
+    ) -> Self:
+        """
+        Truncate a Series or DataFrame before and after some index value.
+
+        This is a useful shorthand for boolean indexing based on index
+        values above or below certain thresholds.
+
+        Parameters
+        ----------
+        before : date, str, int
+            Truncate all rows before this index value.
+        after : date, str, int
+            Truncate all rows after this index value.
+        axis : {0 or 'index', 1 or 'columns'}, optional
+            Axis to truncate. Truncates the index (rows) by default.
+            For `Series` this parameter is unused and defaults to 0.
+        copy : bool, default is True,
+            Return a copy of the truncated section.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        type of caller
+            The truncated Series or DataFrame.
+
+        See Also
+        --------
+        DataFrame.loc : Select a subset of a DataFrame by label.
+        DataFrame.iloc : Select a subset of a DataFrame by position.
+
+        Notes
+        -----
+        If the index being truncated contains only datetime values,
+        `before` and `after` may be specified as strings instead of
+        Timestamps.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': ['a', 'b', 'c', 'd', 'e'],
+        ...                    'B': ['f', 'g', 'h', 'i', 'j'],
+        ...                    'C': ['k', 'l', 'm', 'n', 'o']},
+        ...                   index=[1, 2, 3, 4, 5])
+        >>> df
+           A  B  C
+        1  a  f  k
+        2  b  g  l
+        3  c  h  m
+        4  d  i  n
+        5  e  j  o
+
+        >>> df.truncate(before=2, after=4)
+           A  B  C
+        2  b  g  l
+        3  c  h  m
+        4  d  i  n
+
+        The columns of a DataFrame can be truncated.
+
+        >>> df.truncate(before="A", after="B", axis="columns")
+           A  B
+        1  a  f
+        2  b  g
+        3  c  h
+        4  d  i
+        5  e  j
+
+        For Series, only rows can be truncated.
+
+        >>> df['A'].truncate(before=2, after=4)
+        2    b
+        3    c
+        4    d
+        Name: A, dtype: object
+
+        The index values in ``truncate`` can be datetimes or string
+        dates.
+
+        >>> dates = pd.date_range('2016-01-01', '2016-02-01', freq='s')
+        >>> df = pd.DataFrame(index=dates, data={'A': 1})
+        >>> df.tail()
+                             A
+        2016-01-31 23:59:56  1
+        2016-01-31 23:59:57  1
+        2016-01-31 23:59:58  1
+        2016-01-31 23:59:59  1
+        2016-02-01 00:00:00  1
+
+        >>> df.truncate(before=pd.Timestamp('2016-01-05'),
+        ...             after=pd.Timestamp('2016-01-10')).tail()
+                             A
+        2016-01-09 23:59:56  1
+        2016-01-09 23:59:57  1
+        2016-01-09 23:59:58  1
+        2016-01-09 23:59:59  1
+        2016-01-10 00:00:00  1
+
+        Because the index is a DatetimeIndex containing only dates, we can
+        specify `before` and `after` as strings. They will be coerced to
+        Timestamps before truncation.
+
+        >>> df.truncate('2016-01-05', '2016-01-10').tail()
+                             A
+        2016-01-09 23:59:56  1
+        2016-01-09 23:59:57  1
+        2016-01-09 23:59:58  1
+        2016-01-09 23:59:59  1
+        2016-01-10 00:00:00  1
+
+        Note that ``truncate`` assumes a 0 value for any unspecified time
+        component (midnight). This differs from partial string slicing, which
+        returns any partially matching dates.
+
+        >>> df.loc['2016-01-05':'2016-01-10', :].tail()
+                             A
+        2016-01-10 23:59:55  1
+        2016-01-10 23:59:56  1
+        2016-01-10 23:59:57  1
+        2016-01-10 23:59:58  1
+        2016-01-10 23:59:59  1
+        """
+        if axis is None:
+            axis = 0
+        axis = self._get_axis_number(axis)
+        ax = self._get_axis(axis)
+
+        # GH 17935
+        # Check that index is sorted
+        if not ax.is_monotonic_increasing and not ax.is_monotonic_decreasing:
+            raise ValueError("truncate requires a sorted index")
+
+        # if we have a date index, convert to dates, otherwise
+        # treat like a slice
+        if ax._is_all_dates:
+            from pandas.core.tools.datetimes import to_datetime
+
+            before = to_datetime(before)
+            after = to_datetime(after)
+
+        if before is not None and after is not None and before > after:
+            raise ValueError(f"Truncate: {after} must be after {before}")
+
+        if len(ax) > 1 and ax.is_monotonic_decreasing and ax.nunique() > 1:
+            before, after = after, before
+
+        slicer = [slice(None, None)] * self._AXIS_LEN
+        slicer[axis] = slice(before, after)
+        result = self.loc[tuple(slicer)]
+
+        if isinstance(ax, MultiIndex):
+            setattr(result, self._get_axis_name(axis), ax.truncate(before, after))
+
+        result = result.copy(deep=copy and not using_copy_on_write())
+
+        return result
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def tz_convert(
+        self, tz, axis: Axis = 0, level=None, copy: bool_t | None = None
+    ) -> Self:
+        """
+        Convert tz-aware axis to target time zone.
+
+        Parameters
+        ----------
+        tz : str or tzinfo object or None
+            Target time zone. Passing ``None`` will convert to
+            UTC and remove the timezone information.
+        axis : {{0 or 'index', 1 or 'columns'}}, default 0
+            The axis to convert
+        level : int, str, default None
+            If axis is a MultiIndex, convert a specific level. Otherwise
+            must be None.
+        copy : bool, default True
+            Also make a copy of the underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        {klass}
+            Object with time zone converted axis.
+
+        Raises
+        ------
+        TypeError
+            If the axis is tz-naive.
+
+        Examples
+        --------
+        Change to another time zone:
+
+        >>> s = pd.Series(
+        ...     [1],
+        ...     index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00']),
+        ... )
+        >>> s.tz_convert('Asia/Shanghai')
+        2018-09-15 07:30:00+08:00    1
+        dtype: int64
+
+        Pass None to convert to UTC and get a tz-naive index:
+
+        >>> s = pd.Series([1],
+        ...               index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00']))
+        >>> s.tz_convert(None)
+        2018-09-14 23:30:00    1
+        dtype: int64
+        """
+        axis = self._get_axis_number(axis)
+        ax = self._get_axis(axis)
+
+        def _tz_convert(ax, tz):
+            if not hasattr(ax, "tz_convert"):
+                if len(ax) > 0:
+                    ax_name = self._get_axis_name(axis)
+                    raise TypeError(
+                        f"{ax_name} is not a valid DatetimeIndex or PeriodIndex"
+                    )
+                ax = DatetimeIndex([], tz=tz)
+            else:
+                ax = ax.tz_convert(tz)
+            return ax
+
+        # if a level is given it must be a MultiIndex level or
+        # equivalent to the axis name
+        if isinstance(ax, MultiIndex):
+            level = ax._get_level_number(level)
+            new_level = _tz_convert(ax.levels[level], tz)
+            ax = ax.set_levels(new_level, level=level)
+        else:
+            if level not in (None, 0, ax.name):
+                raise ValueError(f"The level {level} is not valid")
+            ax = _tz_convert(ax, tz)
+
+        result = self.copy(deep=copy and not using_copy_on_write())
+        result = result.set_axis(ax, axis=axis, copy=False)
+        return result.__finalize__(self, method="tz_convert")
+
+    @final
+    @doc(klass=_shared_doc_kwargs["klass"])
+    def tz_localize(
+        self,
+        tz,
+        axis: Axis = 0,
+        level=None,
+        copy: bool_t | None = None,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        """
+        Localize tz-naive index of a Series or DataFrame to target time zone.
+
+        This operation localizes the Index. To localize the values in a
+        timezone-naive Series, use :meth:`Series.dt.tz_localize`.
+
+        Parameters
+        ----------
+        tz : str or tzinfo or None
+            Time zone to localize. Passing ``None`` will remove the
+            time zone information and preserve local time.
+        axis : {{0 or 'index', 1 or 'columns'}}, default 0
+            The axis to localize
+        level : int, str, default None
+            If axis ia a MultiIndex, localize a specific level. Otherwise
+            must be None.
+        copy : bool, default True
+            Also make a copy of the underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
+            When clocks moved backward due to DST, ambiguous times may arise.
+            For example in Central European Time (UTC+01), when going from
+            03:00 DST to 02:00 non-DST, 02:30:00 local time occurs both at
+            00:30:00 UTC and at 01:30:00 UTC. In such a situation, the
+            `ambiguous` parameter dictates how ambiguous times should be
+            handled.
+
+            - 'infer' will attempt to infer fall dst-transition hours based on
+              order
+            - bool-ndarray where True signifies a DST time, False designates
+              a non-DST time (note that this flag is only applicable for
+              ambiguous times)
+            - 'NaT' will return NaT where there are ambiguous times
+            - 'raise' will raise an AmbiguousTimeError if there are ambiguous
+              times.
+        nonexistent : str, default 'raise'
+            A nonexistent time does not exist in a particular timezone
+            where clocks moved forward due to DST. Valid values are:
+
+            - 'shift_forward' will shift the nonexistent time forward to the
+              closest existing time
+            - 'shift_backward' will shift the nonexistent time backward to the
+              closest existing time
+            - 'NaT' will return NaT where there are nonexistent times
+            - timedelta objects will shift nonexistent times by the timedelta
+            - 'raise' will raise an NonExistentTimeError if there are
+              nonexistent times.
+
+        Returns
+        -------
+        {klass}
+            Same type as the input.
+
+        Raises
+        ------
+        TypeError
+            If the TimeSeries is tz-aware and tz is not None.
+
+        Examples
+        --------
+        Localize local times:
+
+        >>> s = pd.Series(
+        ...     [1],
+        ...     index=pd.DatetimeIndex(['2018-09-15 01:30:00']),
+        ... )
+        >>> s.tz_localize('CET')
+        2018-09-15 01:30:00+02:00    1
+        dtype: int64
+
+        Pass None to convert to tz-naive index and preserve local time:
+
+        >>> s = pd.Series([1],
+        ...               index=pd.DatetimeIndex(['2018-09-15 01:30:00+02:00']))
+        >>> s.tz_localize(None)
+        2018-09-15 01:30:00    1
+        dtype: int64
+
+        Be careful with DST changes. When there is sequential data, pandas
+        can infer the DST time:
+
+        >>> s = pd.Series(range(7),
+        ...               index=pd.DatetimeIndex(['2018-10-28 01:30:00',
+        ...                                       '2018-10-28 02:00:00',
+        ...                                       '2018-10-28 02:30:00',
+        ...                                       '2018-10-28 02:00:00',
+        ...                                       '2018-10-28 02:30:00',
+        ...                                       '2018-10-28 03:00:00',
+        ...                                       '2018-10-28 03:30:00']))
+        >>> s.tz_localize('CET', ambiguous='infer')
+        2018-10-28 01:30:00+02:00    0
+        2018-10-28 02:00:00+02:00    1
+        2018-10-28 02:30:00+02:00    2
+        2018-10-28 02:00:00+01:00    3
+        2018-10-28 02:30:00+01:00    4
+        2018-10-28 03:00:00+01:00    5
+        2018-10-28 03:30:00+01:00    6
+        dtype: int64
+
+        In some cases, inferring the DST is impossible. In such cases, you can
+        pass an ndarray to the ambiguous parameter to set the DST explicitly
+
+        >>> s = pd.Series(range(3),
+        ...               index=pd.DatetimeIndex(['2018-10-28 01:20:00',
+        ...                                       '2018-10-28 02:36:00',
+        ...                                       '2018-10-28 03:46:00']))
+        >>> s.tz_localize('CET', ambiguous=np.array([True, True, False]))
+        2018-10-28 01:20:00+02:00    0
+        2018-10-28 02:36:00+02:00    1
+        2018-10-28 03:46:00+01:00    2
+        dtype: int64
+
+        If the DST transition causes nonexistent times, you can shift these
+        dates forward or backward with a timedelta object or `'shift_forward'`
+        or `'shift_backward'`.
+
+        >>> s = pd.Series(range(2),
+        ...               index=pd.DatetimeIndex(['2015-03-29 02:30:00',
+        ...                                       '2015-03-29 03:30:00']))
+        >>> s.tz_localize('Europe/Warsaw', nonexistent='shift_forward')
+        2015-03-29 03:00:00+02:00    0
+        2015-03-29 03:30:00+02:00    1
+        dtype: int64
+        >>> s.tz_localize('Europe/Warsaw', nonexistent='shift_backward')
+        2015-03-29 01:59:59.999999999+01:00    0
+        2015-03-29 03:30:00+02:00              1
+        dtype: int64
+        >>> s.tz_localize('Europe/Warsaw', nonexistent=pd.Timedelta('1h'))
+        2015-03-29 03:30:00+02:00    0
+        2015-03-29 03:30:00+02:00    1
+        dtype: int64
+        """
+        nonexistent_options = ("raise", "NaT", "shift_forward", "shift_backward")
+        if nonexistent not in nonexistent_options and not isinstance(
+            nonexistent, dt.timedelta
+        ):
+            raise ValueError(
+                "The nonexistent argument must be one of 'raise', "
+                "'NaT', 'shift_forward', 'shift_backward' or "
+                "a timedelta object"
+            )
+
+        axis = self._get_axis_number(axis)
+        ax = self._get_axis(axis)
+
+        def _tz_localize(ax, tz, ambiguous, nonexistent):
+            if not hasattr(ax, "tz_localize"):
+                if len(ax) > 0:
+                    ax_name = self._get_axis_name(axis)
+                    raise TypeError(
+                        f"{ax_name} is not a valid DatetimeIndex or PeriodIndex"
+                    )
+                ax = DatetimeIndex([], tz=tz)
+            else:
+                ax = ax.tz_localize(tz, ambiguous=ambiguous, nonexistent=nonexistent)
+            return ax
+
+        # if a level is given it must be a MultiIndex level or
+        # equivalent to the axis name
+        if isinstance(ax, MultiIndex):
+            level = ax._get_level_number(level)
+            new_level = _tz_localize(ax.levels[level], tz, ambiguous, nonexistent)
+            ax = ax.set_levels(new_level, level=level)
+        else:
+            if level not in (None, 0, ax.name):
+                raise ValueError(f"The level {level} is not valid")
+            ax = _tz_localize(ax, tz, ambiguous, nonexistent)
+
+        result = self.copy(deep=copy and not using_copy_on_write())
+        result = result.set_axis(ax, axis=axis, copy=False)
+        return result.__finalize__(self, method="tz_localize")
+
+    # ----------------------------------------------------------------------
+    # Numeric Methods
+
+    @final
+    def describe(
+        self,
+        percentiles=None,
+        include=None,
+        exclude=None,
+    ) -> Self:
+        """
+        Generate descriptive statistics.
+
+        Descriptive statistics include those that summarize the central
+        tendency, dispersion and shape of a
+        dataset's distribution, excluding ``NaN`` values.
+
+        Analyzes both numeric and object series, as well
+        as ``DataFrame`` column sets of mixed data types. The output
+        will vary depending on what is provided. Refer to the notes
+        below for more detail.
+
+        Parameters
+        ----------
+        percentiles : list-like of numbers, optional
+            The percentiles to include in the output. All should
+            fall between 0 and 1. The default is
+            ``[.25, .5, .75]``, which returns the 25th, 50th, and
+            75th percentiles.
+        include : 'all', list-like of dtypes or None (default), optional
+            A white list of data types to include in the result. Ignored
+            for ``Series``. Here are the options:
+
+            - 'all' : All columns of the input will be included in the output.
+            - A list-like of dtypes : Limits the results to the
+              provided data types.
+              To limit the result to numeric types submit
+              ``numpy.number``. To limit it instead to object columns submit
+              the ``numpy.object`` data type. Strings
+              can also be used in the style of
+              ``select_dtypes`` (e.g. ``df.describe(include=['O'])``). To
+              select pandas categorical columns, use ``'category'``
+            - None (default) : The result will include all numeric columns.
+        exclude : list-like of dtypes or None (default), optional,
+            A black list of data types to omit from the result. Ignored
+            for ``Series``. Here are the options:
+
+            - A list-like of dtypes : Excludes the provided data types
+              from the result. To exclude numeric types submit
+              ``numpy.number``. To exclude object columns submit the data
+              type ``numpy.object``. Strings can also be used in the style of
+              ``select_dtypes`` (e.g. ``df.describe(exclude=['O'])``). To
+              exclude pandas categorical columns, use ``'category'``
+            - None (default) : The result will exclude nothing.
+
+        Returns
+        -------
+        Series or DataFrame
+            Summary statistics of the Series or Dataframe provided.
+
+        See Also
+        --------
+        DataFrame.count: Count number of non-NA/null observations.
+        DataFrame.max: Maximum of the values in the object.
+        DataFrame.min: Minimum of the values in the object.
+        DataFrame.mean: Mean of the values.
+        DataFrame.std: Standard deviation of the observations.
+        DataFrame.select_dtypes: Subset of a DataFrame including/excluding
+            columns based on their dtype.
+
+        Notes
+        -----
+        For numeric data, the result's index will include ``count``,
+        ``mean``, ``std``, ``min``, ``max`` as well as lower, ``50`` and
+        upper percentiles. By default the lower percentile is ``25`` and the
+        upper percentile is ``75``. The ``50`` percentile is the
+        same as the median.
+
+        For object data (e.g. strings or timestamps), the result's index
+        will include ``count``, ``unique``, ``top``, and ``freq``. The ``top``
+        is the most common value. The ``freq`` is the most common value's
+        frequency. Timestamps also include the ``first`` and ``last`` items.
+
+        If multiple object values have the highest count, then the
+        ``count`` and ``top`` results will be arbitrarily chosen from
+        among those with the highest count.
+
+        For mixed data types provided via a ``DataFrame``, the default is to
+        return only an analysis of numeric columns. If the dataframe consists
+        only of object and categorical data without any numeric columns, the
+        default is to return an analysis of both the object and categorical
+        columns. If ``include='all'`` is provided as an option, the result
+        will include a union of attributes of each type.
+
+        The `include` and `exclude` parameters can be used to limit
+        which columns in a ``DataFrame`` are analyzed for the output.
+        The parameters are ignored when analyzing a ``Series``.
+
+        Examples
+        --------
+        Describing a numeric ``Series``.
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.describe()
+        count    3.0
+        mean     2.0
+        std      1.0
+        min      1.0
+        25%      1.5
+        50%      2.0
+        75%      2.5
+        max      3.0
+        dtype: float64
+
+        Describing a categorical ``Series``.
+
+        >>> s = pd.Series(['a', 'a', 'b', 'c'])
+        >>> s.describe()
+        count     4
+        unique    3
+        top       a
+        freq      2
+        dtype: object
+
+        Describing a timestamp ``Series``.
+
+        >>> s = pd.Series([
+        ...     np.datetime64("2000-01-01"),
+        ...     np.datetime64("2010-01-01"),
+        ...     np.datetime64("2010-01-01")
+        ... ])
+        >>> s.describe()
+        count                      3
+        mean     2006-09-01 08:00:00
+        min      2000-01-01 00:00:00
+        25%      2004-12-31 12:00:00
+        50%      2010-01-01 00:00:00
+        75%      2010-01-01 00:00:00
+        max      2010-01-01 00:00:00
+        dtype: object
+
+        Describing a ``DataFrame``. By default only numeric fields
+        are returned.
+
+        >>> df = pd.DataFrame({'categorical': pd.Categorical(['d', 'e', 'f']),
+        ...                    'numeric': [1, 2, 3],
+        ...                    'object': ['a', 'b', 'c']
+        ...                    })
+        >>> df.describe()
+               numeric
+        count      3.0
+        mean       2.0
+        std        1.0
+        min        1.0
+        25%        1.5
+        50%        2.0
+        75%        2.5
+        max        3.0
+
+        Describing all columns of a ``DataFrame`` regardless of data type.
+
+        >>> df.describe(include='all')  # doctest: +SKIP
+               categorical  numeric object
+        count            3      3.0      3
+        unique           3      NaN      3
+        top              f      NaN      a
+        freq             1      NaN      1
+        mean           NaN      2.0    NaN
+        std            NaN      1.0    NaN
+        min            NaN      1.0    NaN
+        25%            NaN      1.5    NaN
+        50%            NaN      2.0    NaN
+        75%            NaN      2.5    NaN
+        max            NaN      3.0    NaN
+
+        Describing a column from a ``DataFrame`` by accessing it as
+        an attribute.
+
+        >>> df.numeric.describe()
+        count    3.0
+        mean     2.0
+        std      1.0
+        min      1.0
+        25%      1.5
+        50%      2.0
+        75%      2.5
+        max      3.0
+        Name: numeric, dtype: float64
+
+        Including only numeric columns in a ``DataFrame`` description.
+
+        >>> df.describe(include=[np.number])
+               numeric
+        count      3.0
+        mean       2.0
+        std        1.0
+        min        1.0
+        25%        1.5
+        50%        2.0
+        75%        2.5
+        max        3.0
+
+        Including only string columns in a ``DataFrame`` description.
+
+        >>> df.describe(include=[object])  # doctest: +SKIP
+               object
+        count       3
+        unique      3
+        top         a
+        freq        1
+
+        Including only categorical columns from a ``DataFrame`` description.
+
+        >>> df.describe(include=['category'])
+               categorical
+        count            3
+        unique           3
+        top              d
+        freq             1
+
+        Excluding numeric columns from a ``DataFrame`` description.
+
+        >>> df.describe(exclude=[np.number])  # doctest: +SKIP
+               categorical object
+        count            3      3
+        unique           3      3
+        top              f      a
+        freq             1      1
+
+        Excluding object columns from a ``DataFrame`` description.
+
+        >>> df.describe(exclude=[object])  # doctest: +SKIP
+               categorical  numeric
+        count            3      3.0
+        unique           3      NaN
+        top              f      NaN
+        freq             1      NaN
+        mean           NaN      2.0
+        std            NaN      1.0
+        min            NaN      1.0
+        25%            NaN      1.5
+        50%            NaN      2.0
+        75%            NaN      2.5
+        max            NaN      3.0
+        """
+        return describe_ndframe(
+            obj=self,
+            include=include,
+            exclude=exclude,
+            percentiles=percentiles,
+        ).__finalize__(self, method="describe")
+
+    @final
+    def pct_change(
+        self,
+        periods: int = 1,
+        fill_method: FillnaOptions | None | lib.NoDefault = lib.no_default,
+        limit: int | None | lib.NoDefault = lib.no_default,
+        freq=None,
+        **kwargs,
+    ) -> Self:
+        """
+        Fractional change between the current and a prior element.
+
+        Computes the fractional change from the immediately previous row by
+        default. This is useful in comparing the fraction of change in a time
+        series of elements.
+
+        .. note::
+
+            Despite the name of this method, it calculates fractional change
+            (also known as per unit change or relative change) and not
+            percentage change. If you need the percentage change, multiply
+            these values by 100.
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Periods to shift for forming percent change.
+        fill_method : {'backfill', 'bfill', 'pad', 'ffill', None}, default 'pad'
+            How to handle NAs **before** computing percent changes.
+
+            .. deprecated:: 2.1
+                All options of `fill_method` are deprecated except `fill_method=None`.
+
+        limit : int, default None
+            The number of consecutive NAs to fill before stopping.
+
+            .. deprecated:: 2.1
+
+        freq : DateOffset, timedelta, or str, optional
+            Increment to use from time series API (e.g. 'ME' or BDay()).
+        **kwargs
+            Additional keyword arguments are passed into
+            `DataFrame.shift` or `Series.shift`.
+
+        Returns
+        -------
+        Series or DataFrame
+            The same type as the calling object.
+
+        See Also
+        --------
+        Series.diff : Compute the difference of two elements in a Series.
+        DataFrame.diff : Compute the difference of two elements in a DataFrame.
+        Series.shift : Shift the index by some number of periods.
+        DataFrame.shift : Shift the index by some number of periods.
+
+        Examples
+        --------
+        **Series**
+
+        >>> s = pd.Series([90, 91, 85])
+        >>> s
+        0    90
+        1    91
+        2    85
+        dtype: int64
+
+        >>> s.pct_change()
+        0         NaN
+        1    0.011111
+        2   -0.065934
+        dtype: float64
+
+        >>> s.pct_change(periods=2)
+        0         NaN
+        1         NaN
+        2   -0.055556
+        dtype: float64
+
+        See the percentage change in a Series where filling NAs with last
+        valid observation forward to next valid.
+
+        >>> s = pd.Series([90, 91, None, 85])
+        >>> s
+        0    90.0
+        1    91.0
+        2     NaN
+        3    85.0
+        dtype: float64
+
+        >>> s.ffill().pct_change()
+        0         NaN
+        1    0.011111
+        2    0.000000
+        3   -0.065934
+        dtype: float64
+
+        **DataFrame**
+
+        Percentage change in French franc, Deutsche Mark, and Italian lira from
+        1980-01-01 to 1980-03-01.
+
+        >>> df = pd.DataFrame({
+        ...     'FR': [4.0405, 4.0963, 4.3149],
+        ...     'GR': [1.7246, 1.7482, 1.8519],
+        ...     'IT': [804.74, 810.01, 860.13]},
+        ...     index=['1980-01-01', '1980-02-01', '1980-03-01'])
+        >>> df
+                        FR      GR      IT
+        1980-01-01  4.0405  1.7246  804.74
+        1980-02-01  4.0963  1.7482  810.01
+        1980-03-01  4.3149  1.8519  860.13
+
+        >>> df.pct_change()
+                          FR        GR        IT
+        1980-01-01       NaN       NaN       NaN
+        1980-02-01  0.013810  0.013684  0.006549
+        1980-03-01  0.053365  0.059318  0.061876
+
+        Percentage of change in GOOG and APPL stock volume. Shows computing
+        the percentage change between columns.
+
+        >>> df = pd.DataFrame({
+        ...     '2016': [1769950, 30586265],
+        ...     '2015': [1500923, 40912316],
+        ...     '2014': [1371819, 41403351]},
+        ...     index=['GOOG', 'APPL'])
+        >>> df
+                  2016      2015      2014
+        GOOG   1769950   1500923   1371819
+        APPL  30586265  40912316  41403351
+
+        >>> df.pct_change(axis='columns', periods=-1)
+                  2016      2015  2014
+        GOOG  0.179241  0.094112   NaN
+        APPL -0.252395 -0.011860   NaN
+        """
+        # GH#53491
+        if fill_method not in (lib.no_default, None) or limit is not lib.no_default:
+            warnings.warn(
+                "The 'fill_method' keyword being not None and the 'limit' keyword in "
+                f"{type(self).__name__}.pct_change are deprecated and will be removed "
+                "in a future version. Either fill in any non-leading NA values prior "
+                "to calling pct_change or specify 'fill_method=None' to not fill NA "
+                "values.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if fill_method is lib.no_default:
+            if limit is lib.no_default:
+                cols = self.items() if self.ndim == 2 else [(None, self)]
+                for _, col in cols:
+                    if len(col) > 0:
+                        mask = col.isna().values
+                        mask = mask[np.argmax(~mask) :]
+                        if mask.any():
+                            warnings.warn(
+                                "The default fill_method='pad' in "
+                                f"{type(self).__name__}.pct_change is deprecated and "
+                                "will be removed in a future version. Either fill in "
+                                "any non-leading NA values prior to calling pct_change "
+                                "or specify 'fill_method=None' to not fill NA values.",
+                                FutureWarning,
+                                stacklevel=find_stack_level(),
+                            )
+                            break
+            fill_method = "pad"
+        if limit is lib.no_default:
+            limit = None
+
+        axis = self._get_axis_number(kwargs.pop("axis", "index"))
+        if fill_method is None:
+            data = self
+        else:
+            data = self._pad_or_backfill(fill_method, axis=axis, limit=limit)
+
+        shifted = data.shift(periods=periods, freq=freq, axis=axis, **kwargs)
+        # Unsupported left operand type for / ("Self")
+        rs = data / shifted - 1  # type: ignore[operator]
+        if freq is not None:
+            # Shift method is implemented differently when freq is not None
+            # We want to restore the original index
+            rs = rs.loc[~rs.index.duplicated()]
+            rs = rs.reindex_like(data)
+        return rs.__finalize__(self, method="pct_change")
+
+    @final
+    def _logical_func(
+        self,
+        name: str,
+        func,
+        axis: Axis | None = 0,
+        bool_only: bool_t = False,
+        skipna: bool_t = True,
+        **kwargs,
+    ) -> Series | bool_t:
+        nv.validate_logical_func((), kwargs, fname=name)
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+
+        if self.ndim > 1 and axis is None:
+            # Reduce along one dimension then the other, to simplify DataFrame._reduce
+            res = self._logical_func(
+                name, func, axis=0, bool_only=bool_only, skipna=skipna, **kwargs
+            )
+            # error: Item "bool" of "Series | bool" has no attribute "_logical_func"
+            return res._logical_func(  # type: ignore[union-attr]
+                name, func, skipna=skipna, **kwargs
+            )
+        elif axis is None:
+            axis = 0
+
+        if (
+            self.ndim > 1
+            and axis == 1
+            and len(self._mgr.arrays) > 1
+            # TODO(EA2D): special-case not needed
+            and all(x.ndim == 2 for x in self._mgr.arrays)
+            and not kwargs
+        ):
+            # Fastpath avoiding potentially expensive transpose
+            obj = self
+            if bool_only:
+                obj = self._get_bool_data()
+            return obj._reduce_axis1(name, func, skipna=skipna)
+
+        return self._reduce(
+            func,
+            name=name,
+            axis=axis,
+            skipna=skipna,
+            numeric_only=bool_only,
+            filter_type="bool",
+        )
+
+    def any(
+        self,
+        axis: Axis | None = 0,
+        bool_only: bool_t = False,
+        skipna: bool_t = True,
+        **kwargs,
+    ) -> Series | bool_t:
+        return self._logical_func(
+            "any", nanops.nanany, axis, bool_only, skipna, **kwargs
+        )
+
+    def all(
+        self,
+        axis: Axis = 0,
+        bool_only: bool_t = False,
+        skipna: bool_t = True,
+        **kwargs,
+    ) -> Series | bool_t:
+        return self._logical_func(
+            "all", nanops.nanall, axis, bool_only, skipna, **kwargs
+        )
+
+    @final
+    def _accum_func(
+        self,
+        name: str,
+        func,
+        axis: Axis | None = None,
+        skipna: bool_t = True,
+        *args,
+        **kwargs,
+    ):
+        skipna = nv.validate_cum_func_with_skipna(skipna, args, kwargs, name)
+        if axis is None:
+            axis = 0
+        else:
+            axis = self._get_axis_number(axis)
+
+        if axis == 1:
+            return self.T._accum_func(
+                name, func, axis=0, skipna=skipna, *args, **kwargs  # noqa: B026
+            ).T
+
+        def block_accum_func(blk_values):
+            values = blk_values.T if hasattr(blk_values, "T") else blk_values
+
+            result: np.ndarray | ExtensionArray
+            if isinstance(values, ExtensionArray):
+                result = values._accumulate(name, skipna=skipna, **kwargs)
+            else:
+                result = nanops.na_accum_func(values, func, skipna=skipna)
+
+            result = result.T if hasattr(result, "T") else result
+            return result
+
+        result = self._mgr.apply(block_accum_func)
+
+        return self._constructor_from_mgr(result, axes=result.axes).__finalize__(
+            self, method=name
+        )
+
+    def cummax(self, axis: Axis | None = None, skipna: bool_t = True, *args, **kwargs):
+        return self._accum_func(
+            "cummax", np.maximum.accumulate, axis, skipna, *args, **kwargs
+        )
+
+    def cummin(self, axis: Axis | None = None, skipna: bool_t = True, *args, **kwargs):
+        return self._accum_func(
+            "cummin", np.minimum.accumulate, axis, skipna, *args, **kwargs
+        )
+
+    def cumsum(self, axis: Axis | None = None, skipna: bool_t = True, *args, **kwargs):
+        return self._accum_func("cumsum", np.cumsum, axis, skipna, *args, **kwargs)
+
+    def cumprod(self, axis: Axis | None = None, skipna: bool_t = True, *args, **kwargs):
+        return self._accum_func("cumprod", np.cumprod, axis, skipna, *args, **kwargs)
+
+    @final
+    def _stat_function_ddof(
+        self,
+        name: str,
+        func,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool_t = True,
+        ddof: int = 1,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        nv.validate_stat_ddof_func((), kwargs, fname=name)
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+
+        if axis is None:
+            if self.ndim > 1:
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.{name} with axis=None "
+                    "is deprecated, in a future version this will reduce over both "
+                    "axes and return a scalar. To retain the old behavior, pass "
+                    "axis=0 (or do not pass axis)",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            axis = 0
+        elif axis is lib.no_default:
+            axis = 0
+
+        return self._reduce(
+            func, name, axis=axis, numeric_only=numeric_only, skipna=skipna, ddof=ddof
+        )
+
+    def sem(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        ddof: int = 1,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function_ddof(
+            "sem", nanops.nansem, axis, skipna, ddof, numeric_only, **kwargs
+        )
+
+    def var(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        ddof: int = 1,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function_ddof(
+            "var", nanops.nanvar, axis, skipna, ddof, numeric_only, **kwargs
+        )
+
+    def std(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        ddof: int = 1,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function_ddof(
+            "std", nanops.nanstd, axis, skipna, ddof, numeric_only, **kwargs
+        )
+
+    @final
+    def _stat_function(
+        self,
+        name: str,
+        func,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ):
+        assert name in ["median", "mean", "min", "max", "kurt", "skew"], name
+        nv.validate_func(name, (), kwargs)
+
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+
+        return self._reduce(
+            func, name=name, axis=axis, skipna=skipna, numeric_only=numeric_only
+        )
+
+    def min(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ):
+        return self._stat_function(
+            "min",
+            nanops.nanmin,
+            axis,
+            skipna,
+            numeric_only,
+            **kwargs,
+        )
+
+    def max(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ):
+        return self._stat_function(
+            "max",
+            nanops.nanmax,
+            axis,
+            skipna,
+            numeric_only,
+            **kwargs,
+        )
+
+    def mean(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function(
+            "mean", nanops.nanmean, axis, skipna, numeric_only, **kwargs
+        )
+
+    def median(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function(
+            "median", nanops.nanmedian, axis, skipna, numeric_only, **kwargs
+        )
+
+    def skew(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function(
+            "skew", nanops.nanskew, axis, skipna, numeric_only, **kwargs
+        )
+
+    def kurt(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        **kwargs,
+    ) -> Series | float:
+        return self._stat_function(
+            "kurt", nanops.nankurt, axis, skipna, numeric_only, **kwargs
+        )
+
+    kurtosis = kurt
+
+    @final
+    def _min_count_stat_function(
+        self,
+        name: str,
+        func,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        assert name in ["sum", "prod"], name
+        nv.validate_func(name, (), kwargs)
+
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+
+        if axis is None:
+            if self.ndim > 1:
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.{name} with axis=None "
+                    "is deprecated, in a future version this will reduce over both "
+                    "axes and return a scalar. To retain the old behavior, pass "
+                    "axis=0 (or do not pass axis)",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            axis = 0
+        elif axis is lib.no_default:
+            axis = 0
+
+        return self._reduce(
+            func,
+            name=name,
+            axis=axis,
+            skipna=skipna,
+            numeric_only=numeric_only,
+            min_count=min_count,
+        )
+
+    def sum(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        return self._min_count_stat_function(
+            "sum", nanops.nansum, axis, skipna, numeric_only, min_count, **kwargs
+        )
+
+    def prod(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool_t = True,
+        numeric_only: bool_t = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        return self._min_count_stat_function(
+            "prod",
+            nanops.nanprod,
+            axis,
+            skipna,
+            numeric_only,
+            min_count,
+            **kwargs,
+        )
+
+    product = prod
+
+    @final
+    @doc(Rolling)
+    def rolling(
+        self,
+        window: int | dt.timedelta | str | BaseOffset | BaseIndexer,
+        min_periods: int | None = None,
+        center: bool_t = False,
+        win_type: str | None = None,
+        on: str | None = None,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        closed: IntervalClosedType | None = None,
+        step: int | None = None,
+        method: str = "single",
+    ) -> Window | Rolling:
+        if axis is not lib.no_default:
+            axis = self._get_axis_number(axis)
+            name = "rolling"
+            if axis == 1:
+                warnings.warn(
+                    f"Support for axis=1 in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    f"Use obj.T.{name}(...) instead",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                warnings.warn(
+                    f"The 'axis' keyword in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    "Call the method without the axis keyword instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            axis = 0
+
+        if win_type is not None:
+            return Window(
+                self,
+                window=window,
+                min_periods=min_periods,
+                center=center,
+                win_type=win_type,
+                on=on,
+                axis=axis,
+                closed=closed,
+                step=step,
+                method=method,
+            )
+
+        return Rolling(
+            self,
+            window=window,
+            min_periods=min_periods,
+            center=center,
+            win_type=win_type,
+            on=on,
+            axis=axis,
+            closed=closed,
+            step=step,
+            method=method,
+        )
+
+    @final
+    @doc(Expanding)
+    def expanding(
+        self,
+        min_periods: int = 1,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        method: Literal["single", "table"] = "single",
+    ) -> Expanding:
+        if axis is not lib.no_default:
+            axis = self._get_axis_number(axis)
+            name = "expanding"
+            if axis == 1:
+                warnings.warn(
+                    f"Support for axis=1 in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    f"Use obj.T.{name}(...) instead",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                warnings.warn(
+                    f"The 'axis' keyword in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    "Call the method without the axis keyword instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            axis = 0
+        return Expanding(self, min_periods=min_periods, axis=axis, method=method)
+
+    @final
+    @doc(ExponentialMovingWindow)
+    def ewm(
+        self,
+        com: float | None = None,
+        span: float | None = None,
+        halflife: float | TimedeltaConvertibleTypes | None = None,
+        alpha: float | None = None,
+        min_periods: int | None = 0,
+        adjust: bool_t = True,
+        ignore_na: bool_t = False,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        times: np.ndarray | DataFrame | Series | None = None,
+        method: Literal["single", "table"] = "single",
+    ) -> ExponentialMovingWindow:
+        if axis is not lib.no_default:
+            axis = self._get_axis_number(axis)
+            name = "ewm"
+            if axis == 1:
+                warnings.warn(
+                    f"Support for axis=1 in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    f"Use obj.T.{name}(...) instead",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                warnings.warn(
+                    f"The 'axis' keyword in {type(self).__name__}.{name} is "
+                    "deprecated and will be removed in a future version. "
+                    "Call the method without the axis keyword instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+        else:
+            axis = 0
+
+        return ExponentialMovingWindow(
+            self,
+            com=com,
+            span=span,
+            halflife=halflife,
+            alpha=alpha,
+            min_periods=min_periods,
+            adjust=adjust,
+            ignore_na=ignore_na,
+            axis=axis,
+            times=times,
+            method=method,
+        )
+
+    # ----------------------------------------------------------------------
+    # Arithmetic Methods
+
+    @final
+    def _inplace_method(self, other, op) -> Self:
+        """
+        Wrap arithmetic method to operate inplace.
+        """
+        warn = True
+        if not PYPY and warn_copy_on_write():
+            if sys.getrefcount(self) <= REF_COUNT + 2:
+                # we are probably in an inplace setitem context (e.g. df['a'] += 1)
+                warn = False
+
+        result = op(self, other)
+
+        if (
+            self.ndim == 1
+            and result._indexed_same(self)
+            and result.dtype == self.dtype
+            and not using_copy_on_write()
+            and not (warn_copy_on_write() and not warn)
+        ):
+            # GH#36498 this inplace op can _actually_ be inplace.
+            # Item "ArrayManager" of "Union[ArrayManager, SingleArrayManager,
+            # BlockManager, SingleBlockManager]" has no attribute "setitem_inplace"
+            self._mgr.setitem_inplace(  # type: ignore[union-attr]
+                slice(None), result._values, warn=warn
+            )
+            return self
+
+        # Delete cacher
+        self._reset_cacher()
+
+        # this makes sure that we are aligned like the input
+        # we are updating inplace so we want to ignore is_copy
+        self._update_inplace(
+            result.reindex_like(self, copy=False), verify_is_copy=False
+        )
+        return self
+
+    @final
+    def __iadd__(self, other) -> Self:
+        # error: Unsupported left operand type for + ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__add__)  # type: ignore[operator]
+
+    @final
+    def __isub__(self, other) -> Self:
+        # error: Unsupported left operand type for - ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__sub__)  # type: ignore[operator]
+
+    @final
+    def __imul__(self, other) -> Self:
+        # error: Unsupported left operand type for * ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__mul__)  # type: ignore[operator]
+
+    @final
+    def __itruediv__(self, other) -> Self:
+        # error: Unsupported left operand type for / ("Type[NDFrame]")
+        return self._inplace_method(
+            other, type(self).__truediv__  # type: ignore[operator]
+        )
+
+    @final
+    def __ifloordiv__(self, other) -> Self:
+        # error: Unsupported left operand type for // ("Type[NDFrame]")
+        return self._inplace_method(
+            other, type(self).__floordiv__  # type: ignore[operator]
+        )
+
+    @final
+    def __imod__(self, other) -> Self:
+        # error: Unsupported left operand type for % ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__mod__)  # type: ignore[operator]
+
+    @final
+    def __ipow__(self, other) -> Self:
+        # error: Unsupported left operand type for ** ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__pow__)  # type: ignore[operator]
+
+    @final
+    def __iand__(self, other) -> Self:
+        # error: Unsupported left operand type for & ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__and__)  # type: ignore[operator]
+
+    @final
+    def __ior__(self, other) -> Self:
+        return self._inplace_method(other, type(self).__or__)
+
+    @final
+    def __ixor__(self, other) -> Self:
+        # error: Unsupported left operand type for ^ ("Type[NDFrame]")
+        return self._inplace_method(other, type(self).__xor__)  # type: ignore[operator]
+
+    # ----------------------------------------------------------------------
+    # Misc methods
+
+    @final
+    def _find_valid_index(self, *, how: str) -> Hashable | None:
+        """
+        Retrieves the index of the first valid value.
+
+        Parameters
+        ----------
+        how : {'first', 'last'}
+            Use this parameter to change between the first or last valid index.
+
+        Returns
+        -------
+        idx_first_valid : type of index
+        """
+        is_valid = self.notna().values
+        idxpos = find_valid_index(how=how, is_valid=is_valid)
+        if idxpos is None:
+            return None
+        return self.index[idxpos]
+
+    @final
+    @doc(position="first", klass=_shared_doc_kwargs["klass"])
+    def first_valid_index(self) -> Hashable | None:
+        """
+        Return index for {position} non-NA value or None, if no non-NA value is found.
+
+        Returns
+        -------
+        type of index
+
+        Examples
+        --------
+        For Series:
+
+        >>> s = pd.Series([None, 3, 4])
+        >>> s.first_valid_index()
+        1
+        >>> s.last_valid_index()
+        2
+
+        >>> s = pd.Series([None, None])
+        >>> print(s.first_valid_index())
+        None
+        >>> print(s.last_valid_index())
+        None
+
+        If all elements in Series are NA/null, returns None.
+
+        >>> s = pd.Series()
+        >>> print(s.first_valid_index())
+        None
+        >>> print(s.last_valid_index())
+        None
+
+        If Series is empty, returns None.
+
+        For DataFrame:
+
+        >>> df = pd.DataFrame({{'A': [None, None, 2], 'B': [None, 3, 4]}})
+        >>> df
+             A      B
+        0  NaN    NaN
+        1  NaN    3.0
+        2  2.0    4.0
+        >>> df.first_valid_index()
+        1
+        >>> df.last_valid_index()
+        2
+
+        >>> df = pd.DataFrame({{'A': [None, None, None], 'B': [None, None, None]}})
+        >>> df
+             A      B
+        0  None   None
+        1  None   None
+        2  None   None
+        >>> print(df.first_valid_index())
+        None
+        >>> print(df.last_valid_index())
+        None
+
+        If all elements in DataFrame are NA/null, returns None.
+
+        >>> df = pd.DataFrame()
+        >>> df
+        Empty DataFrame
+        Columns: []
+        Index: []
+        >>> print(df.first_valid_index())
+        None
+        >>> print(df.last_valid_index())
+        None
+
+        If DataFrame is empty, returns None.
+        """
+        return self._find_valid_index(how="first")
+
+    @final
+    @doc(first_valid_index, position="last", klass=_shared_doc_kwargs["klass"])
+    def last_valid_index(self) -> Hashable | None:
+        return self._find_valid_index(how="last")
+
+
+_num_doc = """
+{desc}
+
+Parameters
+----------
+axis : {axis_descr}
+    Axis for the function to be applied on.
+    For `Series` this parameter is unused and defaults to 0.
+
+    For DataFrames, specifying ``axis=None`` will apply the aggregation
+    across both axes.
+
+    .. versionadded:: 2.0.0
+
+skipna : bool, default True
+    Exclude NA/null values when computing the result.
+numeric_only : bool, default False
+    Include only float, int, boolean columns. Not implemented for Series.
+
+{min_count}\
+**kwargs
+    Additional keyword arguments to be passed to the function.
+
+Returns
+-------
+{name1} or scalar\
+{see_also}\
+{examples}
+"""
+
+_sum_prod_doc = """
+{desc}
+
+Parameters
+----------
+axis : {axis_descr}
+    Axis for the function to be applied on.
+    For `Series` this parameter is unused and defaults to 0.
+
+    .. warning::
+
+        The behavior of DataFrame.{name} with ``axis=None`` is deprecated,
+        in a future version this will reduce over both axes and return a scalar
+        To retain the old behavior, pass axis=0 (or do not pass axis).
+
+    .. versionadded:: 2.0.0
+
+skipna : bool, default True
+    Exclude NA/null values when computing the result.
+numeric_only : bool, default False
+    Include only float, int, boolean columns. Not implemented for Series.
+
+{min_count}\
+**kwargs
+    Additional keyword arguments to be passed to the function.
+
+Returns
+-------
+{name1} or scalar\
+{see_also}\
+{examples}
+"""
+
+_num_ddof_doc = """
+{desc}
+
+Parameters
+----------
+axis : {axis_descr}
+    For `Series` this parameter is unused and defaults to 0.
+
+    .. warning::
+
+        The behavior of DataFrame.{name} with ``axis=None`` is deprecated,
+        in a future version this will reduce over both axes and return a scalar
+        To retain the old behavior, pass axis=0 (or do not pass axis).
+
+skipna : bool, default True
+    Exclude NA/null values. If an entire row/column is NA, the result
+    will be NA.
+ddof : int, default 1
+    Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
+    where N represents the number of elements.
+numeric_only : bool, default False
+    Include only float, int, boolean columns. Not implemented for Series.
+
+Returns
+-------
+{name1} or {name2} (if level specified) \
+{notes}\
+{examples}
+"""
+
+_std_notes = """
+
+Notes
+-----
+To have the same behaviour as `numpy.std`, use `ddof=0` (instead of the
+default `ddof=1`)"""
+
+_std_examples = """
+
+Examples
+--------
+>>> df = pd.DataFrame({'person_id': [0, 1, 2, 3],
+...                    'age': [21, 25, 62, 43],
+...                    'height': [1.61, 1.87, 1.49, 2.01]}
+...                   ).set_index('person_id')
+>>> df
+           age  height
+person_id
+0           21    1.61
+1           25    1.87
+2           62    1.49
+3           43    2.01
+
+The standard deviation of the columns can be found as follows:
+
+>>> df.std()
+age       18.786076
+height     0.237417
+dtype: float64
+
+Alternatively, `ddof=0` can be set to normalize by N instead of N-1:
+
+>>> df.std(ddof=0)
+age       16.269219
+height     0.205609
+dtype: float64"""
+
+_var_examples = """
+
+Examples
+--------
+>>> df = pd.DataFrame({'person_id': [0, 1, 2, 3],
+...                    'age': [21, 25, 62, 43],
+...                    'height': [1.61, 1.87, 1.49, 2.01]}
+...                   ).set_index('person_id')
+>>> df
+           age  height
+person_id
+0           21    1.61
+1           25    1.87
+2           62    1.49
+3           43    2.01
+
+>>> df.var()
+age       352.916667
+height      0.056367
+dtype: float64
+
+Alternatively, ``ddof=0`` can be set to normalize by N instead of N-1:
+
+>>> df.var(ddof=0)
+age       264.687500
+height      0.042275
+dtype: float64"""
+
+_bool_doc = """
+{desc}
+
+Parameters
+----------
+axis : {{0 or 'index', 1 or 'columns', None}}, default 0
+    Indicate which axis or axes should be reduced. For `Series` this parameter
+    is unused and defaults to 0.
+
+    * 0 / 'index' : reduce the index, return a Series whose index is the
+      original column labels.
+    * 1 / 'columns' : reduce the columns, return a Series whose index is the
+      original index.
+    * None : reduce all axes, return a scalar.
+
+bool_only : bool, default False
+    Include only boolean columns. Not implemented for Series.
+skipna : bool, default True
+    Exclude NA/null values. If the entire row/column is NA and skipna is
+    True, then the result will be {empty_value}, as for an empty row/column.
+    If skipna is False, then NA are treated as True, because these are not
+    equal to zero.
+**kwargs : any, default None
+    Additional keywords have no effect but might be accepted for
+    compatibility with NumPy.
+
+Returns
+-------
+{name1} or {name2}
+    If level is specified, then, {name2} is returned; otherwise, {name1}
+    is returned.
+
+{see_also}
+{examples}"""
+
+_all_desc = """\
+Return whether all elements are True, potentially over an axis.
+
+Returns True unless there at least one element within a series or
+along a Dataframe axis that is False or equivalent (e.g. zero or
+empty)."""
+
+_all_examples = """\
+Examples
+--------
+**Series**
+
+>>> pd.Series([True, True]).all()
+True
+>>> pd.Series([True, False]).all()
+False
+>>> pd.Series([], dtype="float64").all()
+True
+>>> pd.Series([np.nan]).all()
+True
+>>> pd.Series([np.nan]).all(skipna=False)
+True
+
+**DataFrames**
+
+Create a dataframe from a dictionary.
+
+>>> df = pd.DataFrame({'col1': [True, True], 'col2': [True, False]})
+>>> df
+   col1   col2
+0  True   True
+1  True  False
+
+Default behaviour checks if values in each column all return True.
+
+>>> df.all()
+col1     True
+col2    False
+dtype: bool
+
+Specify ``axis='columns'`` to check if values in each row all return True.
+
+>>> df.all(axis='columns')
+0     True
+1    False
+dtype: bool
+
+Or ``axis=None`` for whether every value is True.
+
+>>> df.all(axis=None)
+False
+"""
+
+_all_see_also = """\
+See Also
+--------
+Series.all : Return True if all elements are True.
+DataFrame.any : Return True if one (or more) elements are True.
+"""
+
+_cnum_doc = """
+Return cumulative {desc} over a DataFrame or Series axis.
+
+Returns a DataFrame or Series of the same size containing the cumulative
+{desc}.
+
+Parameters
+----------
+axis : {{0 or 'index', 1 or 'columns'}}, default 0
+    The index or the name of the axis. 0 is equivalent to None or 'index'.
+    For `Series` this parameter is unused and defaults to 0.
+skipna : bool, default True
+    Exclude NA/null values. If an entire row/column is NA, the result
+    will be NA.
+*args, **kwargs
+    Additional keywords have no effect but might be accepted for
+    compatibility with NumPy.
+
+Returns
+-------
+{name1} or {name2}
+    Return cumulative {desc} of {name1} or {name2}.
+
+See Also
+--------
+core.window.expanding.Expanding.{accum_func_name} : Similar functionality
+    but ignores ``NaN`` values.
+{name2}.{accum_func_name} : Return the {desc} over
+    {name2} axis.
+{name2}.cummax : Return cumulative maximum over {name2} axis.
+{name2}.cummin : Return cumulative minimum over {name2} axis.
+{name2}.cumsum : Return cumulative sum over {name2} axis.
+{name2}.cumprod : Return cumulative product over {name2} axis.
+
+{examples}"""
+
+_cummin_examples = """\
+Examples
+--------
+**Series**
+
+>>> s = pd.Series([2, np.nan, 5, -1, 0])
+>>> s
+0    2.0
+1    NaN
+2    5.0
+3   -1.0
+4    0.0
+dtype: float64
+
+By default, NA values are ignored.
+
+>>> s.cummin()
+0    2.0
+1    NaN
+2    2.0
+3   -1.0
+4   -1.0
+dtype: float64
+
+To include NA values in the operation, use ``skipna=False``
+
+>>> s.cummin(skipna=False)
+0    2.0
+1    NaN
+2    NaN
+3    NaN
+4    NaN
+dtype: float64
+
+**DataFrame**
+
+>>> df = pd.DataFrame([[2.0, 1.0],
+...                    [3.0, np.nan],
+...                    [1.0, 0.0]],
+...                   columns=list('AB'))
+>>> df
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  1.0  0.0
+
+By default, iterates over rows and finds the minimum
+in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
+
+>>> df.cummin()
+     A    B
+0  2.0  1.0
+1  2.0  NaN
+2  1.0  0.0
+
+To iterate over columns and find the minimum in each row,
+use ``axis=1``
+
+>>> df.cummin(axis=1)
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  1.0  0.0
+"""
+
+_cumsum_examples = """\
+Examples
+--------
+**Series**
+
+>>> s = pd.Series([2, np.nan, 5, -1, 0])
+>>> s
+0    2.0
+1    NaN
+2    5.0
+3   -1.0
+4    0.0
+dtype: float64
+
+By default, NA values are ignored.
+
+>>> s.cumsum()
+0    2.0
+1    NaN
+2    7.0
+3    6.0
+4    6.0
+dtype: float64
+
+To include NA values in the operation, use ``skipna=False``
+
+>>> s.cumsum(skipna=False)
+0    2.0
+1    NaN
+2    NaN
+3    NaN
+4    NaN
+dtype: float64
+
+**DataFrame**
+
+>>> df = pd.DataFrame([[2.0, 1.0],
+...                    [3.0, np.nan],
+...                    [1.0, 0.0]],
+...                   columns=list('AB'))
+>>> df
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  1.0  0.0
+
+By default, iterates over rows and finds the sum
+in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
+
+>>> df.cumsum()
+     A    B
+0  2.0  1.0
+1  5.0  NaN
+2  6.0  1.0
+
+To iterate over columns and find the sum in each row,
+use ``axis=1``
+
+>>> df.cumsum(axis=1)
+     A    B
+0  2.0  3.0
+1  3.0  NaN
+2  1.0  1.0
+"""
+
+_cumprod_examples = """\
+Examples
+--------
+**Series**
+
+>>> s = pd.Series([2, np.nan, 5, -1, 0])
+>>> s
+0    2.0
+1    NaN
+2    5.0
+3   -1.0
+4    0.0
+dtype: float64
+
+By default, NA values are ignored.
+
+>>> s.cumprod()
+0     2.0
+1     NaN
+2    10.0
+3   -10.0
+4    -0.0
+dtype: float64
+
+To include NA values in the operation, use ``skipna=False``
+
+>>> s.cumprod(skipna=False)
+0    2.0
+1    NaN
+2    NaN
+3    NaN
+4    NaN
+dtype: float64
+
+**DataFrame**
+
+>>> df = pd.DataFrame([[2.0, 1.0],
+...                    [3.0, np.nan],
+...                    [1.0, 0.0]],
+...                   columns=list('AB'))
+>>> df
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  1.0  0.0
+
+By default, iterates over rows and finds the product
+in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
+
+>>> df.cumprod()
+     A    B
+0  2.0  1.0
+1  6.0  NaN
+2  6.0  0.0
+
+To iterate over columns and find the product in each row,
+use ``axis=1``
+
+>>> df.cumprod(axis=1)
+     A    B
+0  2.0  2.0
+1  3.0  NaN
+2  1.0  0.0
+"""
+
+_cummax_examples = """\
+Examples
+--------
+**Series**
+
+>>> s = pd.Series([2, np.nan, 5, -1, 0])
+>>> s
+0    2.0
+1    NaN
+2    5.0
+3   -1.0
+4    0.0
+dtype: float64
+
+By default, NA values are ignored.
+
+>>> s.cummax()
+0    2.0
+1    NaN
+2    5.0
+3    5.0
+4    5.0
+dtype: float64
+
+To include NA values in the operation, use ``skipna=False``
+
+>>> s.cummax(skipna=False)
+0    2.0
+1    NaN
+2    NaN
+3    NaN
+4    NaN
+dtype: float64
+
+**DataFrame**
+
+>>> df = pd.DataFrame([[2.0, 1.0],
+...                    [3.0, np.nan],
+...                    [1.0, 0.0]],
+...                   columns=list('AB'))
+>>> df
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  1.0  0.0
+
+By default, iterates over rows and finds the maximum
+in each column. This is equivalent to ``axis=None`` or ``axis='index'``.
+
+>>> df.cummax()
+     A    B
+0  2.0  1.0
+1  3.0  NaN
+2  3.0  1.0
+
+To iterate over columns and find the maximum in each row,
+use ``axis=1``
+
+>>> df.cummax(axis=1)
+     A    B
+0  2.0  2.0
+1  3.0  NaN
+2  1.0  1.0
+"""
+
+_any_see_also = """\
+See Also
+--------
+numpy.any : Numpy version of this method.
+Series.any : Return whether any element is True.
+Series.all : Return whether all elements are True.
+DataFrame.any : Return whether any element is True over requested axis.
+DataFrame.all : Return whether all elements are True over requested axis.
+"""
+
+_any_desc = """\
+Return whether any element is True, potentially over an axis.
+
+Returns False unless there is at least one element within a series or
+along a Dataframe axis that is True or equivalent (e.g. non-zero or
+non-empty)."""
+
+_any_examples = """\
+Examples
+--------
+**Series**
+
+For Series input, the output is a scalar indicating whether any element
+is True.
+
+>>> pd.Series([False, False]).any()
+False
+>>> pd.Series([True, False]).any()
+True
+>>> pd.Series([], dtype="float64").any()
+False
+>>> pd.Series([np.nan]).any()
+False
+>>> pd.Series([np.nan]).any(skipna=False)
+True
+
+**DataFrame**
+
+Whether each column contains at least one True element (the default).
+
+>>> df = pd.DataFrame({"A": [1, 2], "B": [0, 2], "C": [0, 0]})
+>>> df
+   A  B  C
+0  1  0  0
+1  2  2  0
+
+>>> df.any()
+A     True
+B     True
+C    False
+dtype: bool
+
+Aggregating over the columns.
+
+>>> df = pd.DataFrame({"A": [True, False], "B": [1, 2]})
+>>> df
+       A  B
+0   True  1
+1  False  2
+
+>>> df.any(axis='columns')
+0    True
+1    True
+dtype: bool
+
+>>> df = pd.DataFrame({"A": [True, False], "B": [1, 0]})
+>>> df
+       A  B
+0   True  1
+1  False  0
+
+>>> df.any(axis='columns')
+0    True
+1    False
+dtype: bool
+
+Aggregating over the entire DataFrame with ``axis=None``.
+
+>>> df.any(axis=None)
+True
+
+`any` for an empty DataFrame is an empty Series.
+
+>>> pd.DataFrame([]).any()
+Series([], dtype: bool)
+"""
+
+_shared_docs[
+    "stat_func_example"
+] = """
+
+Examples
+--------
+>>> idx = pd.MultiIndex.from_arrays([
+...     ['warm', 'warm', 'cold', 'cold'],
+...     ['dog', 'falcon', 'fish', 'spider']],
+...     names=['blooded', 'animal'])
+>>> s = pd.Series([4, 2, 0, 8], name='legs', index=idx)
+>>> s
+blooded  animal
+warm     dog       4
+         falcon    2
+cold     fish      0
+         spider    8
+Name: legs, dtype: int64
+
+>>> s.{stat_func}()
+{default_output}"""
+
+_sum_examples = _shared_docs["stat_func_example"].format(
+    stat_func="sum", verb="Sum", default_output=14, level_output_0=6, level_output_1=8
+)
+
+_sum_examples += """
+
+By default, the sum of an empty or all-NA Series is ``0``.
+
+>>> pd.Series([], dtype="float64").sum()  # min_count=0 is the default
+0.0
+
+This can be controlled with the ``min_count`` parameter. For example, if
+you'd like the sum of an empty series to be NaN, pass ``min_count=1``.
+
+>>> pd.Series([], dtype="float64").sum(min_count=1)
+nan
+
+Thanks to the ``skipna`` parameter, ``min_count`` handles all-NA and
+empty series identically.
+
+>>> pd.Series([np.nan]).sum()
+0.0
+
+>>> pd.Series([np.nan]).sum(min_count=1)
+nan"""
+
+_max_examples: str = _shared_docs["stat_func_example"].format(
+    stat_func="max", verb="Max", default_output=8, level_output_0=4, level_output_1=8
+)
+
+_min_examples: str = _shared_docs["stat_func_example"].format(
+    stat_func="min", verb="Min", default_output=0, level_output_0=2, level_output_1=0
+)
+
+_stat_func_see_also = """
+
+See Also
+--------
+Series.sum : Return the sum.
+Series.min : Return the minimum.
+Series.max : Return the maximum.
+Series.idxmin : Return the index of the minimum.
+Series.idxmax : Return the index of the maximum.
+DataFrame.sum : Return the sum over the requested axis.
+DataFrame.min : Return the minimum over the requested axis.
+DataFrame.max : Return the maximum over the requested axis.
+DataFrame.idxmin : Return the index of the minimum over the requested axis.
+DataFrame.idxmax : Return the index of the maximum over the requested axis."""
+
+_prod_examples = """
+
+Examples
+--------
+By default, the product of an empty or all-NA Series is ``1``
+
+>>> pd.Series([], dtype="float64").prod()
+1.0
+
+This can be controlled with the ``min_count`` parameter
+
+>>> pd.Series([], dtype="float64").prod(min_count=1)
+nan
+
+Thanks to the ``skipna`` parameter, ``min_count`` handles all-NA and
+empty series identically.
+
+>>> pd.Series([np.nan]).prod()
+1.0
+
+>>> pd.Series([np.nan]).prod(min_count=1)
+nan"""
+
+_min_count_stub = """\
+min_count : int, default 0
+    The required number of valid values to perform the operation. If fewer than
+    ``min_count`` non-NA values are present the result will be NA.
+"""
+
+
+def make_doc(name: str, ndim: int) -> str:
+    """
+    Generate the docstring for a Series/DataFrame reduction.
+    """
+    if ndim == 1:
+        name1 = "scalar"
+        name2 = "Series"
+        axis_descr = "{index (0)}"
+    else:
+        name1 = "Series"
+        name2 = "DataFrame"
+        axis_descr = "{index (0), columns (1)}"
+
+    if name == "any":
+        base_doc = _bool_doc
+        desc = _any_desc
+        see_also = _any_see_also
+        examples = _any_examples
+        kwargs = {"empty_value": "False"}
+    elif name == "all":
+        base_doc = _bool_doc
+        desc = _all_desc
+        see_also = _all_see_also
+        examples = _all_examples
+        kwargs = {"empty_value": "True"}
+    elif name == "min":
+        base_doc = _num_doc
+        desc = (
+            "Return the minimum of the values over the requested axis.\n\n"
+            "If you want the *index* of the minimum, use ``idxmin``. This is "
+            "the equivalent of the ``numpy.ndarray`` method ``argmin``."
+        )
+        see_also = _stat_func_see_also
+        examples = _min_examples
+        kwargs = {"min_count": ""}
+    elif name == "max":
+        base_doc = _num_doc
+        desc = (
+            "Return the maximum of the values over the requested axis.\n\n"
+            "If you want the *index* of the maximum, use ``idxmax``. This is "
+            "the equivalent of the ``numpy.ndarray`` method ``argmax``."
+        )
+        see_also = _stat_func_see_also
+        examples = _max_examples
+        kwargs = {"min_count": ""}
+
+    elif name == "sum":
+        base_doc = _sum_prod_doc
+        desc = (
+            "Return the sum of the values over the requested axis.\n\n"
+            "This is equivalent to the method ``numpy.sum``."
+        )
+        see_also = _stat_func_see_also
+        examples = _sum_examples
+        kwargs = {"min_count": _min_count_stub}
+
+    elif name == "prod":
+        base_doc = _sum_prod_doc
+        desc = "Return the product of the values over the requested axis."
+        see_also = _stat_func_see_also
+        examples = _prod_examples
+        kwargs = {"min_count": _min_count_stub}
+
+    elif name == "median":
+        base_doc = _num_doc
+        desc = "Return the median of the values over the requested axis."
+        see_also = ""
+        examples = """
+
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.median()
+            2.0
+
+            With a DataFrame
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': [2, 3]}, index=['tiger', 'zebra'])
+            >>> df
+                   a   b
+            tiger  1   2
+            zebra  2   3
+            >>> df.median()
+            a   1.5
+            b   2.5
+            dtype: float64
+
+            Using axis=1
+
+            >>> df.median(axis=1)
+            tiger   1.5
+            zebra   2.5
+            dtype: float64
+
+            In this case, `numeric_only` should be set to `True`
+            to avoid getting an error.
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': ['T', 'Z']},
+            ...                   index=['tiger', 'zebra'])
+            >>> df.median(numeric_only=True)
+            a   1.5
+            dtype: float64"""
+        kwargs = {"min_count": ""}
+
+    elif name == "mean":
+        base_doc = _num_doc
+        desc = "Return the mean of the values over the requested axis."
+        see_also = ""
+        examples = """
+
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.mean()
+            2.0
+
+            With a DataFrame
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': [2, 3]}, index=['tiger', 'zebra'])
+            >>> df
+                   a   b
+            tiger  1   2
+            zebra  2   3
+            >>> df.mean()
+            a   1.5
+            b   2.5
+            dtype: float64
+
+            Using axis=1
+
+            >>> df.mean(axis=1)
+            tiger   1.5
+            zebra   2.5
+            dtype: float64
+
+            In this case, `numeric_only` should be set to `True` to avoid
+            getting an error.
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': ['T', 'Z']},
+            ...                   index=['tiger', 'zebra'])
+            >>> df.mean(numeric_only=True)
+            a   1.5
+            dtype: float64"""
+        kwargs = {"min_count": ""}
+
+    elif name == "var":
+        base_doc = _num_ddof_doc
+        desc = (
+            "Return unbiased variance over requested axis.\n\nNormalized by "
+            "N-1 by default. This can be changed using the ddof argument."
+        )
+        examples = _var_examples
+        see_also = ""
+        kwargs = {"notes": ""}
+
+    elif name == "std":
+        base_doc = _num_ddof_doc
+        desc = (
+            "Return sample standard deviation over requested axis."
+            "\n\nNormalized by N-1 by default. This can be changed using the "
+            "ddof argument."
+        )
+        examples = _std_examples
+        see_also = ""
+        kwargs = {"notes": _std_notes}
+
+    elif name == "sem":
+        base_doc = _num_ddof_doc
+        desc = (
+            "Return unbiased standard error of the mean over requested "
+            "axis.\n\nNormalized by N-1 by default. This can be changed "
+            "using the ddof argument"
+        )
+        examples = """
+
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.sem().round(6)
+            0.57735
+
+            With a DataFrame
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': [2, 3]}, index=['tiger', 'zebra'])
+            >>> df
+                   a   b
+            tiger  1   2
+            zebra  2   3
+            >>> df.sem()
+            a   0.5
+            b   0.5
+            dtype: float64
+
+            Using axis=1
+
+            >>> df.sem(axis=1)
+            tiger   0.5
+            zebra   0.5
+            dtype: float64
+
+            In this case, `numeric_only` should be set to `True`
+            to avoid getting an error.
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': ['T', 'Z']},
+            ...                   index=['tiger', 'zebra'])
+            >>> df.sem(numeric_only=True)
+            a   0.5
+            dtype: float64"""
+        see_also = ""
+        kwargs = {"notes": ""}
+
+    elif name == "skew":
+        base_doc = _num_doc
+        desc = "Return unbiased skew over requested axis.\n\nNormalized by N-1."
+        see_also = ""
+        examples = """
+
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 3])
+            >>> s.skew()
+            0.0
+
+            With a DataFrame
+
+            >>> df = pd.DataFrame({'a': [1, 2, 3], 'b': [2, 3, 4], 'c': [1, 3, 5]},
+            ...                   index=['tiger', 'zebra', 'cow'])
+            >>> df
+                    a   b   c
+            tiger   1   2   1
+            zebra   2   3   3
+            cow     3   4   5
+            >>> df.skew()
+            a   0.0
+            b   0.0
+            c   0.0
+            dtype: float64
+
+            Using axis=1
+
+            >>> df.skew(axis=1)
+            tiger   1.732051
+            zebra  -1.732051
+            cow     0.000000
+            dtype: float64
+
+            In this case, `numeric_only` should be set to `True` to avoid
+            getting an error.
+
+            >>> df = pd.DataFrame({'a': [1, 2, 3], 'b': ['T', 'Z', 'X']},
+            ...                   index=['tiger', 'zebra', 'cow'])
+            >>> df.skew(numeric_only=True)
+            a   0.0
+            dtype: float64"""
+        kwargs = {"min_count": ""}
+    elif name == "kurt":
+        base_doc = _num_doc
+        desc = (
+            "Return unbiased kurtosis over requested axis.\n\n"
+            "Kurtosis obtained using Fisher's definition of\n"
+            "kurtosis (kurtosis of normal == 0.0). Normalized "
+            "by N-1."
+        )
+        see_also = ""
+        examples = """
+
+            Examples
+            --------
+            >>> s = pd.Series([1, 2, 2, 3], index=['cat', 'dog', 'dog', 'mouse'])
+            >>> s
+            cat    1
+            dog    2
+            dog    2
+            mouse  3
+            dtype: int64
+            >>> s.kurt()
+            1.5
+
+            With a DataFrame
+
+            >>> df = pd.DataFrame({'a': [1, 2, 2, 3], 'b': [3, 4, 4, 4]},
+            ...                   index=['cat', 'dog', 'dog', 'mouse'])
+            >>> df
+                   a   b
+              cat  1   3
+              dog  2   4
+              dog  2   4
+            mouse  3   4
+            >>> df.kurt()
+            a   1.5
+            b   4.0
+            dtype: float64
+
+            With axis=None
+
+            >>> df.kurt(axis=None).round(6)
+            -0.988693
+
+            Using axis=1
+
+            >>> df = pd.DataFrame({'a': [1, 2], 'b': [3, 4], 'c': [3, 4], 'd': [1, 2]},
+            ...                   index=['cat', 'dog'])
+            >>> df.kurt(axis=1)
+            cat   -6.0
+            dog   -6.0
+            dtype: float64"""
+        kwargs = {"min_count": ""}
+
+    elif name == "cumsum":
+        base_doc = _cnum_doc
+        desc = "sum"
+        see_also = ""
+        examples = _cumsum_examples
+        kwargs = {"accum_func_name": "sum"}
+
+    elif name == "cumprod":
+        base_doc = _cnum_doc
+        desc = "product"
+        see_also = ""
+        examples = _cumprod_examples
+        kwargs = {"accum_func_name": "prod"}
+
+    elif name == "cummin":
+        base_doc = _cnum_doc
+        desc = "minimum"
+        see_also = ""
+        examples = _cummin_examples
+        kwargs = {"accum_func_name": "min"}
+
+    elif name == "cummax":
+        base_doc = _cnum_doc
+        desc = "maximum"
+        see_also = ""
+        examples = _cummax_examples
+        kwargs = {"accum_func_name": "max"}
+
+    else:
+        raise NotImplementedError
+
+    docstr = base_doc.format(
+        desc=desc,
+        name=name,
+        name1=name1,
+        name2=name2,
+        axis_descr=axis_descr,
+        see_also=see_also,
+        examples=examples,
+        **kwargs,
+    )
+    return docstr
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..8248f378e2c1acea37bdc2d41065c591360b902a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/__init__.py
@@ -0,0 +1,15 @@
+from pandas.core.groupby.generic import (
+    DataFrameGroupBy,
+    NamedAgg,
+    SeriesGroupBy,
+)
+from pandas.core.groupby.groupby import GroupBy
+from pandas.core.groupby.grouper import Grouper
+
+__all__ = [
+    "DataFrameGroupBy",
+    "NamedAgg",
+    "SeriesGroupBy",
+    "GroupBy",
+    "Grouper",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/base.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..a443597347283887deb9cbd3eafb5f6d3bb6d9a6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/base.py
@@ -0,0 +1,121 @@
+"""
+Provide basic components for groupby.
+"""
+from __future__ import annotations
+
+import dataclasses
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+
+@dataclasses.dataclass(order=True, frozen=True)
+class OutputKey:
+    label: Hashable
+    position: int
+
+
+# special case to prevent duplicate plots when catching exceptions when
+# forwarding methods from NDFrames
+plotting_methods = frozenset(["plot", "hist"])
+
+# cythonized transformations or canned "agg+broadcast", which do not
+# require postprocessing of the result by transform.
+cythonized_kernels = frozenset(["cumprod", "cumsum", "shift", "cummin", "cummax"])
+
+# List of aggregation/reduction functions.
+# These map each group to a single numeric value
+reduction_kernels = frozenset(
+    [
+        "all",
+        "any",
+        "corrwith",
+        "count",
+        "first",
+        "idxmax",
+        "idxmin",
+        "last",
+        "max",
+        "mean",
+        "median",
+        "min",
+        "nunique",
+        "prod",
+        # as long as `quantile`'s signature accepts only
+        # a single quantile value, it's a reduction.
+        # GH#27526 might change that.
+        "quantile",
+        "sem",
+        "size",
+        "skew",
+        "std",
+        "sum",
+        "var",
+    ]
+)
+
+# List of transformation functions.
+# a transformation is a function that, for each group,
+# produces a result that has the same shape as the group.
+
+
+transformation_kernels = frozenset(
+    [
+        "bfill",
+        "cumcount",
+        "cummax",
+        "cummin",
+        "cumprod",
+        "cumsum",
+        "diff",
+        "ffill",
+        "fillna",
+        "ngroup",
+        "pct_change",
+        "rank",
+        "shift",
+    ]
+)
+
+# these are all the public methods on Grouper which don't belong
+# in either of the above lists
+groupby_other_methods = frozenset(
+    [
+        "agg",
+        "aggregate",
+        "apply",
+        "boxplot",
+        # corr and cov return ngroups*ncolumns rows, so they
+        # are neither a transformation nor a reduction
+        "corr",
+        "cov",
+        "describe",
+        "dtypes",
+        "expanding",
+        "ewm",
+        "filter",
+        "get_group",
+        "groups",
+        "head",
+        "hist",
+        "indices",
+        "ndim",
+        "ngroups",
+        "nth",
+        "ohlc",
+        "pipe",
+        "plot",
+        "resample",
+        "rolling",
+        "tail",
+        "take",
+        "transform",
+        "sample",
+        "value_counts",
+    ]
+)
+# Valid values  of `name` for `groupby.transform(name)`
+# NOTE: do NOT edit this directly. New additions should be inserted
+# into the appropriate list above.
+transform_kernel_allowlist = reduction_kernels | transformation_kernels
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/categorical.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/categorical.py
new file mode 100644
index 0000000000000000000000000000000000000000..6ab98cf4fe55e9b064db99e61d1245cb83b63dc1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/categorical.py
@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import numpy as np
+
+from pandas.core.algorithms import unique1d
+from pandas.core.arrays.categorical import (
+    Categorical,
+    CategoricalDtype,
+    recode_for_categories,
+)
+
+
+def recode_for_groupby(
+    c: Categorical, sort: bool, observed: bool
+) -> tuple[Categorical, Categorical | None]:
+    """
+    Code the categories to ensure we can groupby for categoricals.
+
+    If observed=True, we return a new Categorical with the observed
+    categories only.
+
+    If sort=False, return a copy of self, coded with categories as
+    returned by .unique(), followed by any categories not appearing in
+    the data. If sort=True, return self.
+
+    This method is needed solely to ensure the categorical index of the
+    GroupBy result has categories in the order of appearance in the data
+    (GH-8868).
+
+    Parameters
+    ----------
+    c : Categorical
+    sort : bool
+        The value of the sort parameter groupby was called with.
+    observed : bool
+        Account only for the observed values
+
+    Returns
+    -------
+    Categorical
+        If sort=False, the new categories are set to the order of
+        appearance in codes (unless ordered=True, in which case the
+        original order is preserved), followed by any unrepresented
+        categories in the original order.
+    Categorical or None
+        If we are observed, return the original categorical, otherwise None
+    """
+    # we only care about observed values
+    if observed:
+        # In cases with c.ordered, this is equivalent to
+        #  return c.remove_unused_categories(), c
+
+        unique_codes = unique1d(c.codes)
+
+        take_codes = unique_codes[unique_codes != -1]
+        if sort:
+            take_codes = np.sort(take_codes)
+
+        # we recode according to the uniques
+        categories = c.categories.take(take_codes)
+        codes = recode_for_categories(c.codes, c.categories, categories)
+
+        # return a new categorical that maps our new codes
+        # and categories
+        dtype = CategoricalDtype(categories, ordered=c.ordered)
+        return Categorical._simple_new(codes, dtype=dtype), c
+
+    # Already sorted according to c.categories; all is fine
+    if sort:
+        return c, None
+
+    # sort=False should order groups in as-encountered order (GH-8868)
+
+    # xref GH:46909: Re-ordering codes faster than using (set|add|reorder)_categories
+    all_codes = np.arange(c.categories.nunique())
+    # GH 38140: exclude nan from indexer for categories
+    unique_notnan_codes = unique1d(c.codes[c.codes != -1])
+    if sort:
+        unique_notnan_codes = np.sort(unique_notnan_codes)
+    if len(all_codes) > len(unique_notnan_codes):
+        # GH 13179: All categories need to be present, even if missing from the data
+        missing_codes = np.setdiff1d(all_codes, unique_notnan_codes, assume_unique=True)
+        take_codes = np.concatenate((unique_notnan_codes, missing_codes))
+    else:
+        take_codes = unique_notnan_codes
+
+    return Categorical(c, c.unique().categories.take(take_codes)), None
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/generic.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/generic.py
new file mode 100644
index 0000000000000000000000000000000000000000..f2e314046fb749e7d32bf7fc76ca22eb1194a328
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/generic.py
@@ -0,0 +1,2852 @@
+"""
+Define the SeriesGroupBy and DataFrameGroupBy
+classes that hold the groupby interfaces (and some implementations).
+
+These are user facing as the result of the ``df.groupby(...)`` operations,
+which here returns a DataFrameGroupBy object.
+"""
+from __future__ import annotations
+
+from collections import abc
+from functools import partial
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    NamedTuple,
+    TypeVar,
+    Union,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    Interval,
+    lib,
+)
+from pandas._libs.hashtable import duplicated
+from pandas.errors import SpecificationError
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    is_bool,
+    is_dict_like,
+    is_integer_dtype,
+    is_list_like,
+    is_numeric_dtype,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    IntervalDtype,
+)
+from pandas.core.dtypes.inference import is_hashable
+from pandas.core.dtypes.missing import (
+    isna,
+    notna,
+)
+
+from pandas.core import algorithms
+from pandas.core.apply import (
+    GroupByApply,
+    maybe_mangle_lambdas,
+    reconstruct_func,
+    validate_func_kwargs,
+    warn_alias_replacement,
+)
+import pandas.core.common as com
+from pandas.core.frame import DataFrame
+from pandas.core.groupby import (
+    base,
+    ops,
+)
+from pandas.core.groupby.groupby import (
+    GroupBy,
+    GroupByPlot,
+    _agg_template_frame,
+    _agg_template_series,
+    _apply_docs,
+    _transform_template,
+)
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    all_indexes_same,
+    default_index,
+)
+from pandas.core.series import Series
+from pandas.core.sorting import get_group_index
+from pandas.core.util.numba_ import maybe_use_numba
+
+from pandas.plotting import boxplot_frame_groupby
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Mapping,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        Axis,
+        AxisInt,
+        CorrelationMethod,
+        FillnaOptions,
+        IndexLabel,
+        Manager,
+        Manager2D,
+        SingleManager,
+        TakeIndexer,
+    )
+
+    from pandas import Categorical
+    from pandas.core.generic import NDFrame
+
+# TODO(typing) the return value on this callable should be any *scalar*.
+AggScalar = Union[str, Callable[..., Any]]
+# TODO: validate types on ScalarResult and move to _typing
+# Blocked from using by https://github.com/python/mypy/issues/1484
+# See note at _mangle_lambda_list
+ScalarResult = TypeVar("ScalarResult")
+
+
+class NamedAgg(NamedTuple):
+    """
+    Helper for column specific aggregation with control over output column names.
+
+    Subclass of typing.NamedTuple.
+
+    Parameters
+    ----------
+    column : Hashable
+        Column label in the DataFrame to apply aggfunc.
+    aggfunc : function or str
+        Function to apply to the provided column. If string, the name of a built-in
+        pandas function.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"key": [1, 1, 2], "a": [-1, 0, 1], 1: [10, 11, 12]})
+    >>> agg_a = pd.NamedAgg(column="a", aggfunc="min")
+    >>> agg_1 = pd.NamedAgg(column=1, aggfunc=lambda x: np.mean(x))
+    >>> df.groupby("key").agg(result_a=agg_a, result_1=agg_1)
+         result_a  result_1
+    key
+    1          -1      10.5
+    2           1      12.0
+    """
+
+    column: Hashable
+    aggfunc: AggScalar
+
+
+class SeriesGroupBy(GroupBy[Series]):
+    def _wrap_agged_manager(self, mgr: Manager) -> Series:
+        out = self.obj._constructor_from_mgr(mgr, axes=mgr.axes)
+        out._name = self.obj.name
+        return out
+
+    def _get_data_to_aggregate(
+        self, *, numeric_only: bool = False, name: str | None = None
+    ) -> SingleManager:
+        ser = self._obj_with_exclusions
+        single = ser._mgr
+        if numeric_only and not is_numeric_dtype(ser.dtype):
+            # GH#41291 match Series behavior
+            kwd_name = "numeric_only"
+            raise TypeError(
+                f"Cannot use {kwd_name}=True with "
+                f"{type(self).__name__}.{name} and non-numeric dtypes."
+            )
+        return single
+
+    _agg_examples_doc = dedent(
+        """
+    Examples
+    --------
+    >>> s = pd.Series([1, 2, 3, 4])
+
+    >>> s
+    0    1
+    1    2
+    2    3
+    3    4
+    dtype: int64
+
+    >>> s.groupby([1, 1, 2, 2]).min()
+    1    1
+    2    3
+    dtype: int64
+
+    >>> s.groupby([1, 1, 2, 2]).agg('min')
+    1    1
+    2    3
+    dtype: int64
+
+    >>> s.groupby([1, 1, 2, 2]).agg(['min', 'max'])
+       min  max
+    1    1    2
+    2    3    4
+
+    The output column names can be controlled by passing
+    the desired column names and aggregations as keyword arguments.
+
+    >>> s.groupby([1, 1, 2, 2]).agg(
+    ...     minimum='min',
+    ...     maximum='max',
+    ... )
+       minimum  maximum
+    1        1        2
+    2        3        4
+
+    .. versionchanged:: 1.3.0
+
+        The resulting dtype will reflect the return value of the aggregating function.
+
+    >>> s.groupby([1, 1, 2, 2]).agg(lambda x: x.astype(float).min())
+    1    1.0
+    2    3.0
+    dtype: float64
+    """
+    )
+
+    @Appender(
+        _apply_docs["template"].format(
+            input="series", examples=_apply_docs["series_examples"]
+        )
+    )
+    def apply(self, func, *args, **kwargs) -> Series:
+        return super().apply(func, *args, **kwargs)
+
+    @doc(_agg_template_series, examples=_agg_examples_doc, klass="Series")
+    def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs):
+        relabeling = func is None
+        columns = None
+        if relabeling:
+            columns, func = validate_func_kwargs(kwargs)
+            kwargs = {}
+
+        if isinstance(func, str):
+            if maybe_use_numba(engine) and engine is not None:
+                # Not all agg functions support numba, only propagate numba kwargs
+                # if user asks for numba, and engine is not None
+                # (if engine is None, the called function will handle the case where
+                # numba is requested via the global option)
+                kwargs["engine"] = engine
+            if engine_kwargs is not None:
+                kwargs["engine_kwargs"] = engine_kwargs
+            return getattr(self, func)(*args, **kwargs)
+
+        elif isinstance(func, abc.Iterable):
+            # Catch instances of lists / tuples
+            # but not the class list / tuple itself.
+            func = maybe_mangle_lambdas(func)
+            kwargs["engine"] = engine
+            kwargs["engine_kwargs"] = engine_kwargs
+            ret = self._aggregate_multiple_funcs(func, *args, **kwargs)
+            if relabeling:
+                # columns is not narrowed by mypy from relabeling flag
+                assert columns is not None  # for mypy
+                ret.columns = columns
+            if not self.as_index:
+                ret = ret.reset_index()
+            return ret
+
+        else:
+            cyfunc = com.get_cython_func(func)
+            if cyfunc and not args and not kwargs:
+                warn_alias_replacement(self, func, cyfunc)
+                return getattr(self, cyfunc)()
+
+            if maybe_use_numba(engine):
+                return self._aggregate_with_numba(
+                    func, *args, engine_kwargs=engine_kwargs, **kwargs
+                )
+
+            if self.ngroups == 0:
+                # e.g. test_evaluate_with_empty_groups without any groups to
+                #  iterate over, we have no output on which to do dtype
+                #  inference. We default to using the existing dtype.
+                #  xref GH#51445
+                obj = self._obj_with_exclusions
+                return self.obj._constructor(
+                    [],
+                    name=self.obj.name,
+                    index=self._grouper.result_index,
+                    dtype=obj.dtype,
+                )
+
+            if self._grouper.nkeys > 1:
+                return self._python_agg_general(func, *args, **kwargs)
+
+            try:
+                return self._python_agg_general(func, *args, **kwargs)
+            except KeyError:
+                # KeyError raised in test_groupby.test_basic is bc the func does
+                #  a dictionary lookup on group.name, but group name is not
+                #  pinned in _python_agg_general, only in _aggregate_named
+                result = self._aggregate_named(func, *args, **kwargs)
+
+                warnings.warn(
+                    "Pinning the groupby key to each group in "
+                    f"{type(self).__name__}.agg is deprecated, and cases that "
+                    "relied on it will raise in a future version. "
+                    "If your operation requires utilizing the groupby keys, "
+                    "iterate over the groupby object instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+                # result is a dict whose keys are the elements of result_index
+                result = Series(result, index=self._grouper.result_index)
+                result = self._wrap_aggregated_output(result)
+                return result
+
+    agg = aggregate
+
+    def _python_agg_general(self, func, *args, **kwargs):
+        orig_func = func
+        func = com.is_builtin_func(func)
+        if orig_func != func:
+            alias = com._builtin_table_alias[func]
+            warn_alias_replacement(self, orig_func, alias)
+        f = lambda x: func(x, *args, **kwargs)
+
+        obj = self._obj_with_exclusions
+        result = self._grouper.agg_series(obj, f)
+        res = obj._constructor(result, name=obj.name)
+        return self._wrap_aggregated_output(res)
+
+    def _aggregate_multiple_funcs(self, arg, *args, **kwargs) -> DataFrame:
+        if isinstance(arg, dict):
+            if self.as_index:
+                # GH 15931
+                raise SpecificationError("nested renamer is not supported")
+            else:
+                # GH#50684 - This accidentally worked in 1.x
+                msg = (
+                    "Passing a dictionary to SeriesGroupBy.agg is deprecated "
+                    "and will raise in a future version of pandas. Pass a list "
+                    "of aggregations instead."
+                )
+                warnings.warn(
+                    message=msg,
+                    category=FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                arg = list(arg.items())
+        elif any(isinstance(x, (tuple, list)) for x in arg):
+            arg = [(x, x) if not isinstance(x, (tuple, list)) else x for x in arg]
+        else:
+            # list of functions / function names
+            columns = (com.get_callable_name(f) or f for f in arg)
+            arg = zip(columns, arg)
+
+        results: dict[base.OutputKey, DataFrame | Series] = {}
+        with com.temp_setattr(self, "as_index", True):
+            # Combine results using the index, need to adjust index after
+            # if as_index=False (GH#50724)
+            for idx, (name, func) in enumerate(arg):
+                key = base.OutputKey(label=name, position=idx)
+                results[key] = self.aggregate(func, *args, **kwargs)
+
+        if any(isinstance(x, DataFrame) for x in results.values()):
+            from pandas import concat
+
+            res_df = concat(
+                results.values(), axis=1, keys=[key.label for key in results]
+            )
+            return res_df
+
+        indexed_output = {key.position: val for key, val in results.items()}
+        output = self.obj._constructor_expanddim(indexed_output, index=None)
+        output.columns = Index(key.label for key in results)
+
+        return output
+
+    def _wrap_applied_output(
+        self,
+        data: Series,
+        values: list[Any],
+        not_indexed_same: bool = False,
+        is_transform: bool = False,
+    ) -> DataFrame | Series:
+        """
+        Wrap the output of SeriesGroupBy.apply into the expected result.
+
+        Parameters
+        ----------
+        data : Series
+            Input data for groupby operation.
+        values : List[Any]
+            Applied output for each group.
+        not_indexed_same : bool, default False
+            Whether the applied outputs are not indexed the same as the group axes.
+
+        Returns
+        -------
+        DataFrame or Series
+        """
+        if len(values) == 0:
+            # GH #6265
+            if is_transform:
+                # GH#47787 see test_group_on_empty_multiindex
+                res_index = data.index
+            else:
+                res_index = self._grouper.result_index
+
+            return self.obj._constructor(
+                [],
+                name=self.obj.name,
+                index=res_index,
+                dtype=data.dtype,
+            )
+        assert values is not None
+
+        if isinstance(values[0], dict):
+            # GH #823 #24880
+            index = self._grouper.result_index
+            res_df = self.obj._constructor_expanddim(values, index=index)
+            res_df = self._reindex_output(res_df)
+            # if self.observed is False,
+            # keep all-NaN rows created while re-indexing
+            res_ser = res_df.stack(future_stack=True)
+            res_ser.name = self.obj.name
+            return res_ser
+        elif isinstance(values[0], (Series, DataFrame)):
+            result = self._concat_objects(
+                values,
+                not_indexed_same=not_indexed_same,
+                is_transform=is_transform,
+            )
+            if isinstance(result, Series):
+                result.name = self.obj.name
+            if not self.as_index and not_indexed_same:
+                result = self._insert_inaxis_grouper(result)
+                result.index = default_index(len(result))
+            return result
+        else:
+            # GH #6265 #24880
+            result = self.obj._constructor(
+                data=values, index=self._grouper.result_index, name=self.obj.name
+            )
+            if not self.as_index:
+                result = self._insert_inaxis_grouper(result)
+                result.index = default_index(len(result))
+            return self._reindex_output(result)
+
+    def _aggregate_named(self, func, *args, **kwargs):
+        # Note: this is very similar to _aggregate_series_pure_python,
+        #  but that does not pin group.name
+        result = {}
+        initialized = False
+
+        for name, group in self._grouper.get_iterator(
+            self._obj_with_exclusions, axis=self.axis
+        ):
+            # needed for pandas/tests/groupby/test_groupby.py::test_basic_aggregations
+            object.__setattr__(group, "name", name)
+
+            output = func(group, *args, **kwargs)
+            output = ops.extract_result(output)
+            if not initialized:
+                # We only do this validation on the first iteration
+                ops.check_result_array(output, group.dtype)
+                initialized = True
+            result[name] = output
+
+        return result
+
+    __examples_series_doc = dedent(
+        """
+    >>> ser = pd.Series([390.0, 350.0, 30.0, 20.0],
+    ...                 index=["Falcon", "Falcon", "Parrot", "Parrot"],
+    ...                 name="Max Speed")
+    >>> grouped = ser.groupby([1, 1, 2, 2])
+    >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
+        Falcon    0.707107
+        Falcon   -0.707107
+        Parrot    0.707107
+        Parrot   -0.707107
+        Name: Max Speed, dtype: float64
+
+    Broadcast result of the transformation
+
+    >>> grouped.transform(lambda x: x.max() - x.min())
+    Falcon    40.0
+    Falcon    40.0
+    Parrot    10.0
+    Parrot    10.0
+    Name: Max Speed, dtype: float64
+
+    >>> grouped.transform("mean")
+    Falcon    370.0
+    Falcon    370.0
+    Parrot     25.0
+    Parrot     25.0
+    Name: Max Speed, dtype: float64
+
+    .. versionchanged:: 1.3.0
+
+    The resulting dtype will reflect the return value of the passed ``func``,
+    for example:
+
+    >>> grouped.transform(lambda x: x.astype(int).max())
+    Falcon    390
+    Falcon    390
+    Parrot     30
+    Parrot     30
+    Name: Max Speed, dtype: int64
+    """
+    )
+
+    @Substitution(klass="Series", example=__examples_series_doc)
+    @Appender(_transform_template)
+    def transform(self, func, *args, engine=None, engine_kwargs=None, **kwargs):
+        return self._transform(
+            func, *args, engine=engine, engine_kwargs=engine_kwargs, **kwargs
+        )
+
+    def _cython_transform(
+        self, how: str, numeric_only: bool = False, axis: AxisInt = 0, **kwargs
+    ):
+        assert axis == 0  # handled by caller
+
+        obj = self._obj_with_exclusions
+
+        try:
+            result = self._grouper._cython_operation(
+                "transform", obj._values, how, axis, **kwargs
+            )
+        except NotImplementedError as err:
+            # e.g. test_groupby_raises_string
+            raise TypeError(f"{how} is not supported for {obj.dtype} dtype") from err
+
+        return obj._constructor(result, index=self.obj.index, name=obj.name)
+
+    def _transform_general(
+        self, func: Callable, engine, engine_kwargs, *args, **kwargs
+    ) -> Series:
+        """
+        Transform with a callable `func`.
+        """
+        if maybe_use_numba(engine):
+            return self._transform_with_numba(
+                func, *args, engine_kwargs=engine_kwargs, **kwargs
+            )
+        assert callable(func)
+        klass = type(self.obj)
+
+        results = []
+        for name, group in self._grouper.get_iterator(
+            self._obj_with_exclusions, axis=self.axis
+        ):
+            # this setattr is needed for test_transform_lambda_with_datetimetz
+            object.__setattr__(group, "name", name)
+            res = func(group, *args, **kwargs)
+
+            results.append(klass(res, index=group.index))
+
+        # check for empty "results" to avoid concat ValueError
+        if results:
+            from pandas.core.reshape.concat import concat
+
+            concatenated = concat(results)
+            result = self._set_result_index_ordered(concatenated)
+        else:
+            result = self.obj._constructor(dtype=np.float64)
+
+        result.name = self.obj.name
+        return result
+
+    def filter(self, func, dropna: bool = True, *args, **kwargs):
+        """
+        Filter elements from groups that don't satisfy a criterion.
+
+        Elements from groups are filtered if they do not satisfy the
+        boolean criterion specified by func.
+
+        Parameters
+        ----------
+        func : function
+            Criterion to apply to each group. Should return True or False.
+        dropna : bool
+            Drop groups that do not pass the filter. True by default; if False,
+            groups that evaluate False are filled with NaNs.
+
+        Returns
+        -------
+        Series
+
+        Notes
+        -----
+        Functions that mutate the passed object can produce unexpected
+        behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+        for more details.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A' : ['foo', 'bar', 'foo', 'bar',
+        ...                           'foo', 'bar'],
+        ...                    'B' : [1, 2, 3, 4, 5, 6],
+        ...                    'C' : [2.0, 5., 8., 1., 2., 9.]})
+        >>> grouped = df.groupby('A')
+        >>> df.groupby('A').B.filter(lambda x: x.mean() > 3.)
+        1    2
+        3    4
+        5    6
+        Name: B, dtype: int64
+        """
+        if isinstance(func, str):
+            wrapper = lambda x: getattr(x, func)(*args, **kwargs)
+        else:
+            wrapper = lambda x: func(x, *args, **kwargs)
+
+        # Interpret np.nan as False.
+        def true_and_notna(x) -> bool:
+            b = wrapper(x)
+            return notna(b) and b
+
+        try:
+            indices = [
+                self._get_index(name)
+                for name, group in self._grouper.get_iterator(
+                    self._obj_with_exclusions, axis=self.axis
+                )
+                if true_and_notna(group)
+            ]
+        except (ValueError, TypeError) as err:
+            raise TypeError("the filter must return a boolean result") from err
+
+        filtered = self._apply_filter(indices, dropna)
+        return filtered
+
+    def nunique(self, dropna: bool = True) -> Series | DataFrame:
+        """
+        Return number of unique elements in the group.
+
+        Returns
+        -------
+        Series
+            Number of unique values within each group.
+
+        Examples
+        --------
+        For SeriesGroupby:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 3], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    3
+        dtype: int64
+        >>> ser.groupby(level=0).nunique()
+        a    2
+        b    1
+        dtype: int64
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 3], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    3
+        dtype: int64
+        >>> ser.resample('MS').nunique()
+        2023-01-01    2
+        2023-02-01    1
+        Freq: MS, dtype: int64
+        """
+        ids, _, ngroups = self._grouper.group_info
+        val = self.obj._values
+        codes, uniques = algorithms.factorize(val, use_na_sentinel=dropna, sort=False)
+
+        if self._grouper.has_dropped_na:
+            mask = ids >= 0
+            ids = ids[mask]
+            codes = codes[mask]
+
+        group_index = get_group_index(
+            labels=[ids, codes],
+            shape=(ngroups, len(uniques)),
+            sort=False,
+            xnull=dropna,
+        )
+
+        if dropna:
+            mask = group_index >= 0
+            if (~mask).any():
+                ids = ids[mask]
+                group_index = group_index[mask]
+
+        mask = duplicated(group_index, "first")
+        res = np.bincount(ids[~mask], minlength=ngroups)
+        res = ensure_int64(res)
+
+        ri = self._grouper.result_index
+        result: Series | DataFrame = self.obj._constructor(
+            res, index=ri, name=self.obj.name
+        )
+        if not self.as_index:
+            result = self._insert_inaxis_grouper(result)
+            result.index = default_index(len(result))
+        return self._reindex_output(result, fill_value=0)
+
+    @doc(Series.describe)
+    def describe(self, percentiles=None, include=None, exclude=None) -> Series:
+        return super().describe(
+            percentiles=percentiles, include=include, exclude=exclude
+        )
+
+    def value_counts(
+        self,
+        normalize: bool = False,
+        sort: bool = True,
+        ascending: bool = False,
+        bins=None,
+        dropna: bool = True,
+    ) -> Series | DataFrame:
+        name = "proportion" if normalize else "count"
+
+        if bins is None:
+            result = self._value_counts(
+                normalize=normalize, sort=sort, ascending=ascending, dropna=dropna
+            )
+            result.name = name
+            return result
+
+        from pandas.core.reshape.merge import get_join_indexers
+        from pandas.core.reshape.tile import cut
+
+        ids, _, _ = self._grouper.group_info
+        val = self.obj._values
+
+        index_names = self._grouper.names + [self.obj.name]
+
+        if isinstance(val.dtype, CategoricalDtype) or (
+            bins is not None and not np.iterable(bins)
+        ):
+            # scalar bins cannot be done at top level
+            # in a backward compatible way
+            # GH38672 relates to categorical dtype
+            ser = self.apply(
+                Series.value_counts,
+                normalize=normalize,
+                sort=sort,
+                ascending=ascending,
+                bins=bins,
+            )
+            ser.name = name
+            ser.index.names = index_names
+            return ser
+
+        # groupby removes null keys from groupings
+        mask = ids != -1
+        ids, val = ids[mask], val[mask]
+
+        lab: Index | np.ndarray
+        if bins is None:
+            lab, lev = algorithms.factorize(val, sort=True)
+            llab = lambda lab, inc: lab[inc]
+        else:
+            # lab is a Categorical with categories an IntervalIndex
+            cat_ser = cut(Series(val, copy=False), bins, include_lowest=True)
+            cat_obj = cast("Categorical", cat_ser._values)
+            lev = cat_obj.categories
+            lab = lev.take(
+                cat_obj.codes,
+                allow_fill=True,
+                fill_value=lev._na_value,
+            )
+            llab = lambda lab, inc: lab[inc]._multiindex.codes[-1]
+
+        if isinstance(lab.dtype, IntervalDtype):
+            # TODO: should we do this inside II?
+            lab_interval = cast(Interval, lab)
+
+            sorter = np.lexsort((lab_interval.left, lab_interval.right, ids))
+        else:
+            sorter = np.lexsort((lab, ids))
+
+        ids, lab = ids[sorter], lab[sorter]
+
+        # group boundaries are where group ids change
+        idchanges = 1 + np.nonzero(ids[1:] != ids[:-1])[0]
+        idx = np.r_[0, idchanges]
+        if not len(ids):
+            idx = idchanges
+
+        # new values are where sorted labels change
+        lchanges = llab(lab, slice(1, None)) != llab(lab, slice(None, -1))
+        inc = np.r_[True, lchanges]
+        if not len(val):
+            inc = lchanges
+        inc[idx] = True  # group boundaries are also new values
+        out = np.diff(np.nonzero(np.r_[inc, True])[0])  # value counts
+
+        # num. of times each group should be repeated
+        rep = partial(np.repeat, repeats=np.add.reduceat(inc, idx))
+
+        # multi-index components
+        codes = self._grouper.reconstructed_codes
+        codes = [rep(level_codes) for level_codes in codes] + [llab(lab, inc)]
+        levels = [ping._group_index for ping in self._grouper.groupings] + [lev]
+
+        if dropna:
+            mask = codes[-1] != -1
+            if mask.all():
+                dropna = False
+            else:
+                out, codes = out[mask], [level_codes[mask] for level_codes in codes]
+
+        if normalize:
+            out = out.astype("float")
+            d = np.diff(np.r_[idx, len(ids)])
+            if dropna:
+                m = ids[lab == -1]
+                np.add.at(d, m, -1)
+                acc = rep(d)[mask]
+            else:
+                acc = rep(d)
+            out /= acc
+
+        if sort and bins is None:
+            cat = ids[inc][mask] if dropna else ids[inc]
+            sorter = np.lexsort((out if ascending else -out, cat))
+            out, codes[-1] = out[sorter], codes[-1][sorter]
+
+        if bins is not None:
+            # for compat. with libgroupby.value_counts need to ensure every
+            # bin is present at every index level, null filled with zeros
+            diff = np.zeros(len(out), dtype="bool")
+            for level_codes in codes[:-1]:
+                diff |= np.r_[True, level_codes[1:] != level_codes[:-1]]
+
+            ncat, nbin = diff.sum(), len(levels[-1])
+
+            left = [np.repeat(np.arange(ncat), nbin), np.tile(np.arange(nbin), ncat)]
+
+            right = [diff.cumsum() - 1, codes[-1]]
+
+            # error: Argument 1 to "get_join_indexers" has incompatible type
+            # "List[ndarray[Any, Any]]"; expected "List[Union[Union[ExtensionArray,
+            # ndarray[Any, Any]], Index, Series]]
+            _, idx = get_join_indexers(
+                left, right, sort=False, how="left"  # type: ignore[arg-type]
+            )
+            if idx is not None:
+                out = np.where(idx != -1, out[idx], 0)
+
+            if sort:
+                sorter = np.lexsort((out if ascending else -out, left[0]))
+                out, left[-1] = out[sorter], left[-1][sorter]
+
+            # build the multi-index w/ full levels
+            def build_codes(lev_codes: np.ndarray) -> np.ndarray:
+                return np.repeat(lev_codes[diff], nbin)
+
+            codes = [build_codes(lev_codes) for lev_codes in codes[:-1]]
+            codes.append(left[-1])
+
+        mi = MultiIndex(
+            levels=levels, codes=codes, names=index_names, verify_integrity=False
+        )
+
+        if is_integer_dtype(out.dtype):
+            out = ensure_int64(out)
+        result = self.obj._constructor(out, index=mi, name=name)
+        if not self.as_index:
+            result = result.reset_index()
+        return result
+
+    def fillna(
+        self,
+        value: object | ArrayLike | None = None,
+        method: FillnaOptions | None = None,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        inplace: bool = False,
+        limit: int | None = None,
+        downcast: dict | None | lib.NoDefault = lib.no_default,
+    ) -> Series | None:
+        """
+        Fill NA/NaN values using the specified method within groups.
+
+        .. deprecated:: 2.2.0
+            This method is deprecated and will be removed in a future version.
+            Use the :meth:`.SeriesGroupBy.ffill` or :meth:`.SeriesGroupBy.bfill`
+            for forward or backward filling instead. If you want to fill with a
+            single value, use :meth:`Series.fillna` instead.
+
+        Parameters
+        ----------
+        value : scalar, dict, Series, or DataFrame
+            Value to use to fill holes (e.g. 0), alternately a
+            dict/Series/DataFrame of values specifying which value to use for
+            each index (for a Series) or column (for a DataFrame).  Values not
+            in the dict/Series/DataFrame will not be filled. This value cannot
+            be a list. Users wanting to use the ``value`` argument and not ``method``
+            should prefer :meth:`.Series.fillna` as this
+            will produce the same result and be more performant.
+        method : {{'bfill', 'ffill', None}}, default None
+            Method to use for filling holes. ``'ffill'`` will propagate
+            the last valid observation forward within a group.
+            ``'bfill'`` will use next valid observation to fill the gap.
+        axis : {0 or 'index', 1 or 'columns'}
+            Unused, only for compatibility with :meth:`DataFrameGroupBy.fillna`.
+        inplace : bool, default False
+            Broken. Do not set to True.
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill within a group. In other words,
+            if there is a gap with more than this number of consecutive NaNs,
+            it will only be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+        Returns
+        -------
+        Series
+            Object with missing values filled within groups.
+
+        See Also
+        --------
+        ffill : Forward fill values within a group.
+        bfill : Backward fill values within a group.
+
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['cat', 'cat', 'cat', 'mouse', 'mouse']
+        >>> ser = pd.Series([1, None, None, 2, None], index=lst)
+        >>> ser
+        cat    1.0
+        cat    NaN
+        cat    NaN
+        mouse  2.0
+        mouse  NaN
+        dtype: float64
+        >>> ser.groupby(level=0).fillna(0, limit=1)
+        cat    1.0
+        cat    0.0
+        cat    NaN
+        mouse  2.0
+        mouse  0.0
+        dtype: float64
+        """
+        warnings.warn(
+            f"{type(self).__name__}.fillna is deprecated and "
+            "will be removed in a future version. Use obj.ffill() or obj.bfill() "
+            "for forward or backward filling instead. If you want to fill with a "
+            f"single value, use {type(self.obj).__name__}.fillna instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        result = self._op_via_apply(
+            "fillna",
+            value=value,
+            method=method,
+            axis=axis,
+            inplace=inplace,
+            limit=limit,
+            downcast=downcast,
+        )
+        return result
+
+    def take(
+        self,
+        indices: TakeIndexer,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        **kwargs,
+    ) -> Series:
+        """
+        Return the elements in the given *positional* indices in each group.
+
+        This means that we are not indexing according to actual values in
+        the index attribute of the object. We are indexing according to the
+        actual position of the element in the object.
+
+        If a requested index does not exist for some group, this method will raise.
+        To get similar behavior that ignores indices that don't exist, see
+        :meth:`.SeriesGroupBy.nth`.
+
+        Parameters
+        ----------
+        indices : array-like
+            An array of ints indicating which positions to take in each group.
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            The axis on which to select elements. ``0`` means that we are
+            selecting rows, ``1`` means that we are selecting columns.
+            For `SeriesGroupBy` this parameter is unused and defaults to 0.
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        **kwargs
+            For compatibility with :meth:`numpy.take`. Has no effect on the
+            output.
+
+        Returns
+        -------
+        Series
+            A Series containing the elements taken from each group.
+
+        See Also
+        --------
+        Series.take : Take elements from a Series along an axis.
+        Series.loc : Select a subset of a DataFrame by labels.
+        Series.iloc : Select a subset of a DataFrame by positions.
+        numpy.take : Take elements from an array along an axis.
+        SeriesGroupBy.nth : Similar to take, won't raise if indices don't exist.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('falcon', 'bird', 389.0),
+        ...                    ('parrot', 'bird', 24.0),
+        ...                    ('lion', 'mammal', 80.5),
+        ...                    ('monkey', 'mammal', np.nan),
+        ...                    ('rabbit', 'mammal', 15.0)],
+        ...                   columns=['name', 'class', 'max_speed'],
+        ...                   index=[4, 3, 2, 1, 0])
+        >>> df
+             name   class  max_speed
+        4  falcon    bird      389.0
+        3  parrot    bird       24.0
+        2    lion  mammal       80.5
+        1  monkey  mammal        NaN
+        0  rabbit  mammal       15.0
+        >>> gb = df["name"].groupby([1, 1, 2, 2, 2])
+
+        Take elements at positions 0 and 1 along the axis 0 in each group (default).
+
+        >>> gb.take([0, 1])
+        1  4    falcon
+           3    parrot
+        2  2      lion
+           1    monkey
+        Name: name, dtype: object
+
+        We may take elements using negative integers for positive indices,
+        starting from the end of the object, just like with Python lists.
+
+        >>> gb.take([-1, -2])
+        1  3    parrot
+           4    falcon
+        2  0    rabbit
+           1    monkey
+        Name: name, dtype: object
+        """
+        result = self._op_via_apply("take", indices=indices, axis=axis, **kwargs)
+        return result
+
+    def skew(
+        self,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ) -> Series:
+        """
+        Return unbiased skew within groups.
+
+        Normalized by N-1.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            Axis for the function to be applied on.
+            This parameter is only for compatibility with DataFrame and is unused.
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        skipna : bool, default True
+            Exclude NA/null values when computing the result.
+
+        numeric_only : bool, default False
+            Include only float, int, boolean columns. Not implemented for Series.
+
+        **kwargs
+            Additional keyword arguments to be passed to the function.
+
+        Returns
+        -------
+        Series
+
+        See Also
+        --------
+        Series.skew : Return unbiased skew over requested axis.
+
+        Examples
+        --------
+        >>> ser = pd.Series([390., 350., 357., np.nan, 22., 20., 30.],
+        ...                 index=['Falcon', 'Falcon', 'Falcon', 'Falcon',
+        ...                        'Parrot', 'Parrot', 'Parrot'],
+        ...                 name="Max Speed")
+        >>> ser
+        Falcon    390.0
+        Falcon    350.0
+        Falcon    357.0
+        Falcon      NaN
+        Parrot     22.0
+        Parrot     20.0
+        Parrot     30.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(level=0).skew()
+        Falcon    1.525174
+        Parrot    1.457863
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(level=0).skew(skipna=False)
+        Falcon         NaN
+        Parrot    1.457863
+        Name: Max Speed, dtype: float64
+        """
+        if axis is lib.no_default:
+            axis = 0
+
+        if axis != 0:
+            result = self._op_via_apply(
+                "skew",
+                axis=axis,
+                skipna=skipna,
+                numeric_only=numeric_only,
+                **kwargs,
+            )
+            return result
+
+        def alt(obj):
+            # This should not be reached since the cython path should raise
+            #  TypeError and not NotImplementedError.
+            raise TypeError(f"'skew' is not supported for dtype={obj.dtype}")
+
+        return self._cython_agg_general(
+            "skew", alt=alt, skipna=skipna, numeric_only=numeric_only, **kwargs
+        )
+
+    @property
+    @doc(Series.plot.__doc__)
+    def plot(self) -> GroupByPlot:
+        result = GroupByPlot(self)
+        return result
+
+    @doc(Series.nlargest.__doc__)
+    def nlargest(
+        self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
+    ) -> Series:
+        f = partial(Series.nlargest, n=n, keep=keep)
+        data = self._obj_with_exclusions
+        # Don't change behavior if result index happens to be the same, i.e.
+        # already ordered and n >= all group sizes.
+        result = self._python_apply_general(f, data, not_indexed_same=True)
+        return result
+
+    @doc(Series.nsmallest.__doc__)
+    def nsmallest(
+        self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
+    ) -> Series:
+        f = partial(Series.nsmallest, n=n, keep=keep)
+        data = self._obj_with_exclusions
+        # Don't change behavior if result index happens to be the same, i.e.
+        # already ordered and n >= all group sizes.
+        result = self._python_apply_general(f, data, not_indexed_same=True)
+        return result
+
+    @doc(Series.idxmin.__doc__)
+    def idxmin(
+        self, axis: Axis | lib.NoDefault = lib.no_default, skipna: bool = True
+    ) -> Series:
+        return self._idxmax_idxmin("idxmin", axis=axis, skipna=skipna)
+
+    @doc(Series.idxmax.__doc__)
+    def idxmax(
+        self, axis: Axis | lib.NoDefault = lib.no_default, skipna: bool = True
+    ) -> Series:
+        return self._idxmax_idxmin("idxmax", axis=axis, skipna=skipna)
+
+    @doc(Series.corr.__doc__)
+    def corr(
+        self,
+        other: Series,
+        method: CorrelationMethod = "pearson",
+        min_periods: int | None = None,
+    ) -> Series:
+        result = self._op_via_apply(
+            "corr", other=other, method=method, min_periods=min_periods
+        )
+        return result
+
+    @doc(Series.cov.__doc__)
+    def cov(
+        self, other: Series, min_periods: int | None = None, ddof: int | None = 1
+    ) -> Series:
+        result = self._op_via_apply(
+            "cov", other=other, min_periods=min_periods, ddof=ddof
+        )
+        return result
+
+    @property
+    def is_monotonic_increasing(self) -> Series:
+        """
+        Return whether each group's values are monotonically increasing.
+
+        Returns
+        -------
+        Series
+
+        Examples
+        --------
+        >>> s = pd.Series([2, 1, 3, 4], index=['Falcon', 'Falcon', 'Parrot', 'Parrot'])
+        >>> s.groupby(level=0).is_monotonic_increasing
+        Falcon    False
+        Parrot     True
+        dtype: bool
+        """
+        return self.apply(lambda ser: ser.is_monotonic_increasing)
+
+    @property
+    def is_monotonic_decreasing(self) -> Series:
+        """
+        Return whether each group's values are monotonically decreasing.
+
+        Returns
+        -------
+        Series
+
+        Examples
+        --------
+        >>> s = pd.Series([2, 1, 3, 4], index=['Falcon', 'Falcon', 'Parrot', 'Parrot'])
+        >>> s.groupby(level=0).is_monotonic_decreasing
+        Falcon     True
+        Parrot    False
+        dtype: bool
+        """
+        return self.apply(lambda ser: ser.is_monotonic_decreasing)
+
+    @doc(Series.hist.__doc__)
+    def hist(
+        self,
+        by=None,
+        ax=None,
+        grid: bool = True,
+        xlabelsize: int | None = None,
+        xrot: float | None = None,
+        ylabelsize: int | None = None,
+        yrot: float | None = None,
+        figsize: tuple[int, int] | None = None,
+        bins: int | Sequence[int] = 10,
+        backend: str | None = None,
+        legend: bool = False,
+        **kwargs,
+    ):
+        result = self._op_via_apply(
+            "hist",
+            by=by,
+            ax=ax,
+            grid=grid,
+            xlabelsize=xlabelsize,
+            xrot=xrot,
+            ylabelsize=ylabelsize,
+            yrot=yrot,
+            figsize=figsize,
+            bins=bins,
+            backend=backend,
+            legend=legend,
+            **kwargs,
+        )
+        return result
+
+    @property
+    @doc(Series.dtype.__doc__)
+    def dtype(self) -> Series:
+        return self.apply(lambda ser: ser.dtype)
+
+    def unique(self) -> Series:
+        """
+        Return unique values for each group.
+
+        It returns unique values for each of the grouped values. Returned in
+        order of appearance. Hash table-based unique, therefore does NOT sort.
+
+        Returns
+        -------
+        Series
+            Unique values for each of the grouped values.
+
+        See Also
+        --------
+        Series.unique : Return unique values of Series object.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('Chihuahua', 'dog', 6.1),
+        ...                    ('Beagle', 'dog', 15.2),
+        ...                    ('Chihuahua', 'dog', 6.9),
+        ...                    ('Persian', 'cat', 9.2),
+        ...                    ('Chihuahua', 'dog', 7),
+        ...                    ('Persian', 'cat', 8.8)],
+        ...                   columns=['breed', 'animal', 'height_in'])
+        >>> df
+               breed     animal   height_in
+        0  Chihuahua        dog         6.1
+        1     Beagle        dog        15.2
+        2  Chihuahua        dog         6.9
+        3    Persian        cat         9.2
+        4  Chihuahua        dog         7.0
+        5    Persian        cat         8.8
+        >>> ser = df.groupby('animal')['breed'].unique()
+        >>> ser
+        animal
+        cat              [Persian]
+        dog    [Chihuahua, Beagle]
+        Name: breed, dtype: object
+        """
+        result = self._op_via_apply("unique")
+        return result
+
+
+class DataFrameGroupBy(GroupBy[DataFrame]):
+    _agg_examples_doc = dedent(
+        """
+    Examples
+    --------
+    >>> data = {"A": [1, 1, 2, 2],
+    ...         "B": [1, 2, 3, 4],
+    ...         "C": [0.362838, 0.227877, 1.267767, -0.562860]}
+    >>> df = pd.DataFrame(data)
+    >>> df
+       A  B         C
+    0  1  1  0.362838
+    1  1  2  0.227877
+    2  2  3  1.267767
+    3  2  4 -0.562860
+
+    The aggregation is for each column.
+
+    >>> df.groupby('A').agg('min')
+       B         C
+    A
+    1  1  0.227877
+    2  3 -0.562860
+
+    Multiple aggregations
+
+    >>> df.groupby('A').agg(['min', 'max'])
+        B             C
+      min max       min       max
+    A
+    1   1   2  0.227877  0.362838
+    2   3   4 -0.562860  1.267767
+
+    Select a column for aggregation
+
+    >>> df.groupby('A').B.agg(['min', 'max'])
+       min  max
+    A
+    1    1    2
+    2    3    4
+
+    User-defined function for aggregation
+
+    >>> df.groupby('A').agg(lambda x: sum(x) + 2)
+        B	       C
+    A
+    1	5	2.590715
+    2	9	2.704907
+
+    Different aggregations per column
+
+    >>> df.groupby('A').agg({'B': ['min', 'max'], 'C': 'sum'})
+        B             C
+      min max       sum
+    A
+    1   1   2  0.590715
+    2   3   4  0.704907
+
+    To control the output names with different aggregations per column,
+    pandas supports "named aggregation"
+
+    >>> df.groupby("A").agg(
+    ...     b_min=pd.NamedAgg(column="B", aggfunc="min"),
+    ...     c_sum=pd.NamedAgg(column="C", aggfunc="sum")
+    ... )
+       b_min     c_sum
+    A
+    1      1  0.590715
+    2      3  0.704907
+
+    - The keywords are the *output* column names
+    - The values are tuples whose first element is the column to select
+      and the second element is the aggregation to apply to that column.
+      Pandas provides the ``pandas.NamedAgg`` namedtuple with the fields
+      ``['column', 'aggfunc']`` to make it clearer what the arguments are.
+      As usual, the aggregation can be a callable or a string alias.
+
+    See :ref:`groupby.aggregate.named` for more.
+
+    .. versionchanged:: 1.3.0
+
+        The resulting dtype will reflect the return value of the aggregating function.
+
+    >>> df.groupby("A")[["B"]].agg(lambda x: x.astype(float).min())
+          B
+    A
+    1   1.0
+    2   3.0
+    """
+    )
+
+    @doc(_agg_template_frame, examples=_agg_examples_doc, klass="DataFrame")
+    def aggregate(self, func=None, *args, engine=None, engine_kwargs=None, **kwargs):
+        relabeling, func, columns, order = reconstruct_func(func, **kwargs)
+        func = maybe_mangle_lambdas(func)
+
+        if maybe_use_numba(engine):
+            # Not all agg functions support numba, only propagate numba kwargs
+            # if user asks for numba
+            kwargs["engine"] = engine
+            kwargs["engine_kwargs"] = engine_kwargs
+
+        op = GroupByApply(self, func, args=args, kwargs=kwargs)
+        result = op.agg()
+        if not is_dict_like(func) and result is not None:
+            # GH #52849
+            if not self.as_index and is_list_like(func):
+                return result.reset_index()
+            else:
+                return result
+        elif relabeling:
+            # this should be the only (non-raising) case with relabeling
+            # used reordered index of columns
+            result = cast(DataFrame, result)
+            result = result.iloc[:, order]
+            result = cast(DataFrame, result)
+            # error: Incompatible types in assignment (expression has type
+            # "Optional[List[str]]", variable has type
+            # "Union[Union[Union[ExtensionArray, ndarray[Any, Any]],
+            # Index, Series], Sequence[Any]]")
+            result.columns = columns  # type: ignore[assignment]
+
+        if result is None:
+            # Remove the kwargs we inserted
+            # (already stored in engine, engine_kwargs arguments)
+            if "engine" in kwargs:
+                del kwargs["engine"]
+                del kwargs["engine_kwargs"]
+            # at this point func is not a str, list-like, dict-like,
+            # or a known callable(e.g. sum)
+            if maybe_use_numba(engine):
+                return self._aggregate_with_numba(
+                    func, *args, engine_kwargs=engine_kwargs, **kwargs
+                )
+            # grouper specific aggregations
+            if self._grouper.nkeys > 1:
+                # test_groupby_as_index_series_scalar gets here with 'not self.as_index'
+                return self._python_agg_general(func, *args, **kwargs)
+            elif args or kwargs:
+                # test_pass_args_kwargs gets here (with and without as_index)
+                # can't return early
+                result = self._aggregate_frame(func, *args, **kwargs)
+
+            elif self.axis == 1:
+                # _aggregate_multiple_funcs does not allow self.axis == 1
+                # Note: axis == 1 precludes 'not self.as_index', see __init__
+                result = self._aggregate_frame(func)
+                return result
+
+            else:
+                # try to treat as if we are passing a list
+                gba = GroupByApply(self, [func], args=(), kwargs={})
+                try:
+                    result = gba.agg()
+
+                except ValueError as err:
+                    if "No objects to concatenate" not in str(err):
+                        raise
+                    # _aggregate_frame can fail with e.g. func=Series.mode,
+                    # where it expects 1D values but would be getting 2D values
+                    # In other tests, using aggregate_frame instead of GroupByApply
+                    #  would give correct values but incorrect dtypes
+                    #  object vs float64 in test_cython_agg_empty_buckets
+                    #  float64 vs int64 in test_category_order_apply
+                    result = self._aggregate_frame(func)
+
+                else:
+                    # GH#32040, GH#35246
+                    # e.g. test_groupby_as_index_select_column_sum_empty_df
+                    result = cast(DataFrame, result)
+                    result.columns = self._obj_with_exclusions.columns.copy()
+
+        if not self.as_index:
+            result = self._insert_inaxis_grouper(result)
+            result.index = default_index(len(result))
+
+        return result
+
+    agg = aggregate
+
+    def _python_agg_general(self, func, *args, **kwargs):
+        orig_func = func
+        func = com.is_builtin_func(func)
+        if orig_func != func:
+            alias = com._builtin_table_alias[func]
+            warn_alias_replacement(self, orig_func, alias)
+        f = lambda x: func(x, *args, **kwargs)
+
+        if self.ngroups == 0:
+            # e.g. test_evaluate_with_empty_groups different path gets different
+            #  result dtype in empty case.
+            return self._python_apply_general(f, self._selected_obj, is_agg=True)
+
+        obj = self._obj_with_exclusions
+        if self.axis == 1:
+            obj = obj.T
+
+        if not len(obj.columns):
+            # e.g. test_margins_no_values_no_cols
+            return self._python_apply_general(f, self._selected_obj)
+
+        output: dict[int, ArrayLike] = {}
+        for idx, (name, ser) in enumerate(obj.items()):
+            result = self._grouper.agg_series(ser, f)
+            output[idx] = result
+
+        res = self.obj._constructor(output)
+        res.columns = obj.columns.copy(deep=False)
+        return self._wrap_aggregated_output(res)
+
+    def _aggregate_frame(self, func, *args, **kwargs) -> DataFrame:
+        if self._grouper.nkeys != 1:
+            raise AssertionError("Number of keys must be 1")
+
+        obj = self._obj_with_exclusions
+
+        result: dict[Hashable, NDFrame | np.ndarray] = {}
+        for name, grp_df in self._grouper.get_iterator(obj, self.axis):
+            fres = func(grp_df, *args, **kwargs)
+            result[name] = fres
+
+        result_index = self._grouper.result_index
+        other_ax = obj.axes[1 - self.axis]
+        out = self.obj._constructor(result, index=other_ax, columns=result_index)
+        if self.axis == 0:
+            out = out.T
+
+        return out
+
+    def _wrap_applied_output(
+        self,
+        data: DataFrame,
+        values: list,
+        not_indexed_same: bool = False,
+        is_transform: bool = False,
+    ):
+        if len(values) == 0:
+            if is_transform:
+                # GH#47787 see test_group_on_empty_multiindex
+                res_index = data.index
+            else:
+                res_index = self._grouper.result_index
+
+            result = self.obj._constructor(index=res_index, columns=data.columns)
+            result = result.astype(data.dtypes, copy=False)
+            return result
+
+        # GH12824
+        # using values[0] here breaks test_groupby_apply_none_first
+        first_not_none = next(com.not_none(*values), None)
+
+        if first_not_none is None:
+            # GH9684 - All values are None, return an empty frame.
+            return self.obj._constructor()
+        elif isinstance(first_not_none, DataFrame):
+            return self._concat_objects(
+                values,
+                not_indexed_same=not_indexed_same,
+                is_transform=is_transform,
+            )
+
+        key_index = self._grouper.result_index if self.as_index else None
+
+        if isinstance(first_not_none, (np.ndarray, Index)):
+            # GH#1738: values is list of arrays of unequal lengths
+            #  fall through to the outer else clause
+            # TODO: sure this is right?  we used to do this
+            #  after raising AttributeError above
+            # GH 18930
+            if not is_hashable(self._selection):
+                # error: Need type annotation for "name"
+                name = tuple(self._selection)  # type: ignore[var-annotated, arg-type]
+            else:
+                # error: Incompatible types in assignment
+                # (expression has type "Hashable", variable
+                # has type "Tuple[Any, ...]")
+                name = self._selection  # type: ignore[assignment]
+            return self.obj._constructor_sliced(values, index=key_index, name=name)
+        elif not isinstance(first_not_none, Series):
+            # values are not series or array-like but scalars
+            # self._selection not passed through to Series as the
+            # result should not take the name of original selection
+            # of columns
+            if self.as_index:
+                return self.obj._constructor_sliced(values, index=key_index)
+            else:
+                result = self.obj._constructor(values, columns=[self._selection])
+                result = self._insert_inaxis_grouper(result)
+                return result
+        else:
+            # values are Series
+            return self._wrap_applied_output_series(
+                values,
+                not_indexed_same,
+                first_not_none,
+                key_index,
+                is_transform,
+            )
+
+    def _wrap_applied_output_series(
+        self,
+        values: list[Series],
+        not_indexed_same: bool,
+        first_not_none,
+        key_index: Index | None,
+        is_transform: bool,
+    ) -> DataFrame | Series:
+        kwargs = first_not_none._construct_axes_dict()
+        backup = Series(**kwargs)
+        values = [x if (x is not None) else backup for x in values]
+
+        all_indexed_same = all_indexes_same(x.index for x in values)
+
+        if not all_indexed_same:
+            # GH 8467
+            return self._concat_objects(
+                values,
+                not_indexed_same=True,
+                is_transform=is_transform,
+            )
+
+        # Combine values
+        # vstack+constructor is faster than concat and handles MI-columns
+        stacked_values = np.vstack([np.asarray(v) for v in values])
+
+        if self.axis == 0:
+            index = key_index
+            columns = first_not_none.index.copy()
+            if columns.name is None:
+                # GH6124 - propagate name of Series when it's consistent
+                names = {v.name for v in values}
+                if len(names) == 1:
+                    columns.name = next(iter(names))
+        else:
+            index = first_not_none.index
+            columns = key_index
+            stacked_values = stacked_values.T
+
+        if stacked_values.dtype == object:
+            # We'll have the DataFrame constructor do inference
+            stacked_values = stacked_values.tolist()
+        result = self.obj._constructor(stacked_values, index=index, columns=columns)
+
+        if not self.as_index:
+            result = self._insert_inaxis_grouper(result)
+
+        return self._reindex_output(result)
+
+    def _cython_transform(
+        self,
+        how: str,
+        numeric_only: bool = False,
+        axis: AxisInt = 0,
+        **kwargs,
+    ) -> DataFrame:
+        assert axis == 0  # handled by caller
+
+        # With self.axis == 0, we have multi-block tests
+        #  e.g. test_rank_min_int, test_cython_transform_frame
+        #  test_transform_numeric_ret
+        # With self.axis == 1, _get_data_to_aggregate does a transpose
+        #  so we always have a single block.
+        mgr: Manager2D = self._get_data_to_aggregate(
+            numeric_only=numeric_only, name=how
+        )
+
+        def arr_func(bvalues: ArrayLike) -> ArrayLike:
+            return self._grouper._cython_operation(
+                "transform", bvalues, how, 1, **kwargs
+            )
+
+        # We could use `mgr.apply` here and not have to set_axis, but
+        #  we would have to do shape gymnastics for ArrayManager compat
+        res_mgr = mgr.grouped_reduce(arr_func)
+        res_mgr.set_axis(1, mgr.axes[1])
+
+        res_df = self.obj._constructor_from_mgr(res_mgr, axes=res_mgr.axes)
+        res_df = self._maybe_transpose_result(res_df)
+        return res_df
+
+    def _transform_general(self, func, engine, engine_kwargs, *args, **kwargs):
+        if maybe_use_numba(engine):
+            return self._transform_with_numba(
+                func, *args, engine_kwargs=engine_kwargs, **kwargs
+            )
+        from pandas.core.reshape.concat import concat
+
+        applied = []
+        obj = self._obj_with_exclusions
+        gen = self._grouper.get_iterator(obj, axis=self.axis)
+        fast_path, slow_path = self._define_paths(func, *args, **kwargs)
+
+        # Determine whether to use slow or fast path by evaluating on the first group.
+        # Need to handle the case of an empty generator and process the result so that
+        # it does not need to be computed again.
+        try:
+            name, group = next(gen)
+        except StopIteration:
+            pass
+        else:
+            # 2023-02-27 No tests broken by disabling this pinning
+            object.__setattr__(group, "name", name)
+            try:
+                path, res = self._choose_path(fast_path, slow_path, group)
+            except ValueError as err:
+                # e.g. test_transform_with_non_scalar_group
+                msg = "transform must return a scalar value for each group"
+                raise ValueError(msg) from err
+            if group.size > 0:
+                res = _wrap_transform_general_frame(self.obj, group, res)
+                applied.append(res)
+
+        # Compute and process with the remaining groups
+        for name, group in gen:
+            if group.size == 0:
+                continue
+            # 2023-02-27 No tests broken by disabling this pinning
+            object.__setattr__(group, "name", name)
+            res = path(group)
+
+            res = _wrap_transform_general_frame(self.obj, group, res)
+            applied.append(res)
+
+        concat_index = obj.columns if self.axis == 0 else obj.index
+        other_axis = 1 if self.axis == 0 else 0  # switches between 0 & 1
+        concatenated = concat(applied, axis=self.axis, verify_integrity=False)
+        concatenated = concatenated.reindex(concat_index, axis=other_axis, copy=False)
+        return self._set_result_index_ordered(concatenated)
+
+    __examples_dataframe_doc = dedent(
+        """
+    >>> df = pd.DataFrame({'A' : ['foo', 'bar', 'foo', 'bar',
+    ...                           'foo', 'bar'],
+    ...                    'B' : ['one', 'one', 'two', 'three',
+    ...                           'two', 'two'],
+    ...                    'C' : [1, 5, 5, 2, 5, 5],
+    ...                    'D' : [2.0, 5., 8., 1., 2., 9.]})
+    >>> grouped = df.groupby('A')[['C', 'D']]
+    >>> grouped.transform(lambda x: (x - x.mean()) / x.std())
+            C         D
+    0 -1.154701 -0.577350
+    1  0.577350  0.000000
+    2  0.577350  1.154701
+    3 -1.154701 -1.000000
+    4  0.577350 -0.577350
+    5  0.577350  1.000000
+
+    Broadcast result of the transformation
+
+    >>> grouped.transform(lambda x: x.max() - x.min())
+        C    D
+    0  4.0  6.0
+    1  3.0  8.0
+    2  4.0  6.0
+    3  3.0  8.0
+    4  4.0  6.0
+    5  3.0  8.0
+
+    >>> grouped.transform("mean")
+        C    D
+    0  3.666667  4.0
+    1  4.000000  5.0
+    2  3.666667  4.0
+    3  4.000000  5.0
+    4  3.666667  4.0
+    5  4.000000  5.0
+
+    .. versionchanged:: 1.3.0
+
+    The resulting dtype will reflect the return value of the passed ``func``,
+    for example:
+
+    >>> grouped.transform(lambda x: x.astype(int).max())
+    C  D
+    0  5  8
+    1  5  9
+    2  5  8
+    3  5  9
+    4  5  8
+    5  5  9
+    """
+    )
+
+    @Substitution(klass="DataFrame", example=__examples_dataframe_doc)
+    @Appender(_transform_template)
+    def transform(self, func, *args, engine=None, engine_kwargs=None, **kwargs):
+        return self._transform(
+            func, *args, engine=engine, engine_kwargs=engine_kwargs, **kwargs
+        )
+
+    def _define_paths(self, func, *args, **kwargs):
+        if isinstance(func, str):
+            fast_path = lambda group: getattr(group, func)(*args, **kwargs)
+            slow_path = lambda group: group.apply(
+                lambda x: getattr(x, func)(*args, **kwargs), axis=self.axis
+            )
+        else:
+            fast_path = lambda group: func(group, *args, **kwargs)
+            slow_path = lambda group: group.apply(
+                lambda x: func(x, *args, **kwargs), axis=self.axis
+            )
+        return fast_path, slow_path
+
+    def _choose_path(self, fast_path: Callable, slow_path: Callable, group: DataFrame):
+        path = slow_path
+        res = slow_path(group)
+
+        if self.ngroups == 1:
+            # no need to evaluate multiple paths when only
+            # a single group exists
+            return path, res
+
+        # if we make it here, test if we can use the fast path
+        try:
+            res_fast = fast_path(group)
+        except AssertionError:
+            raise  # pragma: no cover
+        except Exception:
+            # GH#29631 For user-defined function, we can't predict what may be
+            #  raised; see test_transform.test_transform_fastpath_raises
+            return path, res
+
+        # verify fast path returns either:
+        # a DataFrame with columns equal to group.columns
+        # OR a Series with index equal to group.columns
+        if isinstance(res_fast, DataFrame):
+            if not res_fast.columns.equals(group.columns):
+                return path, res
+        elif isinstance(res_fast, Series):
+            if not res_fast.index.equals(group.columns):
+                return path, res
+        else:
+            return path, res
+
+        if res_fast.equals(res):
+            path = fast_path
+
+        return path, res
+
+    def filter(self, func, dropna: bool = True, *args, **kwargs):
+        """
+        Filter elements from groups that don't satisfy a criterion.
+
+        Elements from groups are filtered if they do not satisfy the
+        boolean criterion specified by func.
+
+        Parameters
+        ----------
+        func : function
+            Criterion to apply to each group. Should return True or False.
+        dropna : bool
+            Drop groups that do not pass the filter. True by default; if False,
+            groups that evaluate False are filled with NaNs.
+
+        Returns
+        -------
+        DataFrame
+
+        Notes
+        -----
+        Each subframe is endowed the attribute 'name' in case you need to know
+        which group you are working on.
+
+        Functions that mutate the passed object can produce unexpected
+        behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+        for more details.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A' : ['foo', 'bar', 'foo', 'bar',
+        ...                           'foo', 'bar'],
+        ...                    'B' : [1, 2, 3, 4, 5, 6],
+        ...                    'C' : [2.0, 5., 8., 1., 2., 9.]})
+        >>> grouped = df.groupby('A')
+        >>> grouped.filter(lambda x: x['B'].mean() > 3.)
+             A  B    C
+        1  bar  2  5.0
+        3  bar  4  1.0
+        5  bar  6  9.0
+        """
+        indices = []
+
+        obj = self._selected_obj
+        gen = self._grouper.get_iterator(obj, axis=self.axis)
+
+        for name, group in gen:
+            # 2023-02-27 no tests are broken this pinning, but it is documented in the
+            #  docstring above.
+            object.__setattr__(group, "name", name)
+
+            res = func(group, *args, **kwargs)
+
+            try:
+                res = res.squeeze()
+            except AttributeError:  # allow e.g., scalars and frames to pass
+                pass
+
+            # interpret the result of the filter
+            if is_bool(res) or (is_scalar(res) and isna(res)):
+                if notna(res) and res:
+                    indices.append(self._get_index(name))
+            else:
+                # non scalars aren't allowed
+                raise TypeError(
+                    f"filter function returned a {type(res).__name__}, "
+                    "but expected a scalar bool"
+                )
+
+        return self._apply_filter(indices, dropna)
+
+    def __getitem__(self, key) -> DataFrameGroupBy | SeriesGroupBy:
+        if self.axis == 1:
+            # GH 37725
+            raise ValueError("Cannot subset columns when using axis=1")
+        # per GH 23566
+        if isinstance(key, tuple) and len(key) > 1:
+            # if len == 1, then it becomes a SeriesGroupBy and this is actually
+            # valid syntax, so don't raise
+            raise ValueError(
+                "Cannot subset columns with a tuple with more than one element. "
+                "Use a list instead."
+            )
+        return super().__getitem__(key)
+
+    def _gotitem(self, key, ndim: int, subset=None):
+        """
+        sub-classes to define
+        return a sliced object
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        if ndim == 2:
+            if subset is None:
+                subset = self.obj
+            return DataFrameGroupBy(
+                subset,
+                self.keys,
+                axis=self.axis,
+                level=self.level,
+                grouper=self._grouper,
+                exclusions=self.exclusions,
+                selection=key,
+                as_index=self.as_index,
+                sort=self.sort,
+                group_keys=self.group_keys,
+                observed=self.observed,
+                dropna=self.dropna,
+            )
+        elif ndim == 1:
+            if subset is None:
+                subset = self.obj[key]
+            return SeriesGroupBy(
+                subset,
+                self.keys,
+                level=self.level,
+                grouper=self._grouper,
+                exclusions=self.exclusions,
+                selection=key,
+                as_index=self.as_index,
+                sort=self.sort,
+                group_keys=self.group_keys,
+                observed=self.observed,
+                dropna=self.dropna,
+            )
+
+        raise AssertionError("invalid ndim for _gotitem")
+
+    def _get_data_to_aggregate(
+        self, *, numeric_only: bool = False, name: str | None = None
+    ) -> Manager2D:
+        obj = self._obj_with_exclusions
+        if self.axis == 1:
+            mgr = obj.T._mgr
+        else:
+            mgr = obj._mgr
+
+        if numeric_only:
+            mgr = mgr.get_numeric_data()
+        return mgr
+
+    def _wrap_agged_manager(self, mgr: Manager2D) -> DataFrame:
+        return self.obj._constructor_from_mgr(mgr, axes=mgr.axes)
+
+    def _apply_to_column_groupbys(self, func) -> DataFrame:
+        from pandas.core.reshape.concat import concat
+
+        obj = self._obj_with_exclusions
+        columns = obj.columns
+        sgbs = [
+            SeriesGroupBy(
+                obj.iloc[:, i],
+                selection=colname,
+                grouper=self._grouper,
+                exclusions=self.exclusions,
+                observed=self.observed,
+            )
+            for i, colname in enumerate(obj.columns)
+        ]
+        results = [func(sgb) for sgb in sgbs]
+
+        if not len(results):
+            # concat would raise
+            res_df = DataFrame([], columns=columns, index=self._grouper.result_index)
+        else:
+            res_df = concat(results, keys=columns, axis=1)
+
+        if not self.as_index:
+            res_df.index = default_index(len(res_df))
+            res_df = self._insert_inaxis_grouper(res_df)
+        return res_df
+
+    def nunique(self, dropna: bool = True) -> DataFrame:
+        """
+        Return DataFrame with counts of unique elements in each position.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't include NaN in the counts.
+
+        Returns
+        -------
+        nunique: DataFrame
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'id': ['spam', 'egg', 'egg', 'spam',
+        ...                           'ham', 'ham'],
+        ...                    'value1': [1, 5, 5, 2, 5, 5],
+        ...                    'value2': list('abbaxy')})
+        >>> df
+             id  value1 value2
+        0  spam       1      a
+        1   egg       5      b
+        2   egg       5      b
+        3  spam       2      a
+        4   ham       5      x
+        5   ham       5      y
+
+        >>> df.groupby('id').nunique()
+              value1  value2
+        id
+        egg        1       1
+        ham        1       2
+        spam       2       1
+
+        Check for rows with the same id but conflicting values:
+
+        >>> df.groupby('id').filter(lambda g: (g.nunique() > 1).any())
+             id  value1 value2
+        0  spam       1      a
+        3  spam       2      a
+        4   ham       5      x
+        5   ham       5      y
+        """
+
+        if self.axis != 0:
+            # see test_groupby_crash_on_nunique
+            return self._python_apply_general(
+                lambda sgb: sgb.nunique(dropna), self._obj_with_exclusions, is_agg=True
+            )
+
+        return self._apply_to_column_groupbys(lambda sgb: sgb.nunique(dropna))
+
+    def idxmax(
+        self,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool = True,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        """
+        Return index of first occurrence of maximum over requested axis.
+
+        NA/null values are excluded.
+
+        Parameters
+        ----------
+        axis : {{0 or 'index', 1 or 'columns'}}, default None
+            The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+            If axis is not provided, grouper's axis is used.
+
+            .. versionchanged:: 2.0.0
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        Series
+            Indexes of maxima along the specified axis.
+
+        Raises
+        ------
+        ValueError
+            * If the row/column is empty
+
+        See Also
+        --------
+        Series.idxmax : Return index of the maximum element.
+
+        Notes
+        -----
+        This method is the DataFrame version of ``ndarray.argmax``.
+
+        Examples
+        --------
+        Consider a dataset containing food consumption in Argentina.
+
+        >>> df = pd.DataFrame({'consumption': [10.51, 103.11, 55.48],
+        ...                    'co2_emissions': [37.2, 19.66, 1712]},
+        ...                   index=['Pork', 'Wheat Products', 'Beef'])
+
+        >>> df
+                        consumption  co2_emissions
+        Pork                  10.51         37.20
+        Wheat Products       103.11         19.66
+        Beef                  55.48       1712.00
+
+        By default, it returns the index for the maximum value in each column.
+
+        >>> df.idxmax()
+        consumption     Wheat Products
+        co2_emissions             Beef
+        dtype: object
+
+        To return the index for the maximum value in each row, use ``axis="columns"``.
+
+        >>> df.idxmax(axis="columns")
+        Pork              co2_emissions
+        Wheat Products     consumption
+        Beef              co2_emissions
+        dtype: object
+        """
+        return self._idxmax_idxmin(
+            "idxmax", axis=axis, numeric_only=numeric_only, skipna=skipna
+        )
+
+    def idxmin(
+        self,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool = True,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        """
+        Return index of first occurrence of minimum over requested axis.
+
+        NA/null values are excluded.
+
+        Parameters
+        ----------
+        axis : {{0 or 'index', 1 or 'columns'}}, default None
+            The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+            If axis is not provided, grouper's axis is used.
+
+            .. versionchanged:: 2.0.0
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        Series
+            Indexes of minima along the specified axis.
+
+        Raises
+        ------
+        ValueError
+            * If the row/column is empty
+
+        See Also
+        --------
+        Series.idxmin : Return index of the minimum element.
+
+        Notes
+        -----
+        This method is the DataFrame version of ``ndarray.argmin``.
+
+        Examples
+        --------
+        Consider a dataset containing food consumption in Argentina.
+
+        >>> df = pd.DataFrame({'consumption': [10.51, 103.11, 55.48],
+        ...                    'co2_emissions': [37.2, 19.66, 1712]},
+        ...                   index=['Pork', 'Wheat Products', 'Beef'])
+
+        >>> df
+                        consumption  co2_emissions
+        Pork                  10.51         37.20
+        Wheat Products       103.11         19.66
+        Beef                  55.48       1712.00
+
+        By default, it returns the index for the minimum value in each column.
+
+        >>> df.idxmin()
+        consumption                Pork
+        co2_emissions    Wheat Products
+        dtype: object
+
+        To return the index for the minimum value in each row, use ``axis="columns"``.
+
+        >>> df.idxmin(axis="columns")
+        Pork                consumption
+        Wheat Products    co2_emissions
+        Beef                consumption
+        dtype: object
+        """
+        return self._idxmax_idxmin(
+            "idxmin", axis=axis, numeric_only=numeric_only, skipna=skipna
+        )
+
+    boxplot = boxplot_frame_groupby
+
+    def value_counts(
+        self,
+        subset: Sequence[Hashable] | None = None,
+        normalize: bool = False,
+        sort: bool = True,
+        ascending: bool = False,
+        dropna: bool = True,
+    ) -> DataFrame | Series:
+        """
+        Return a Series or DataFrame containing counts of unique rows.
+
+        .. versionadded:: 1.4.0
+
+        Parameters
+        ----------
+        subset : list-like, optional
+            Columns to use when counting unique combinations.
+        normalize : bool, default False
+            Return proportions rather than frequencies.
+        sort : bool, default True
+            Sort by frequencies.
+        ascending : bool, default False
+            Sort in ascending order.
+        dropna : bool, default True
+            Don't include counts of rows that contain NA values.
+
+        Returns
+        -------
+        Series or DataFrame
+            Series if the groupby as_index is True, otherwise DataFrame.
+
+        See Also
+        --------
+        Series.value_counts: Equivalent method on Series.
+        DataFrame.value_counts: Equivalent method on DataFrame.
+        SeriesGroupBy.value_counts: Equivalent method on SeriesGroupBy.
+
+        Notes
+        -----
+        - If the groupby as_index is True then the returned Series will have a
+          MultiIndex with one level per input column.
+        - If the groupby as_index is False then the returned DataFrame will have an
+          additional column with the value_counts. The column is labelled 'count' or
+          'proportion', depending on the ``normalize`` parameter.
+
+        By default, rows that contain any NA values are omitted from
+        the result.
+
+        By default, the result will be in descending order so that the
+        first element of each group is the most frequently-occurring row.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({
+        ...     'gender': ['male', 'male', 'female', 'male', 'female', 'male'],
+        ...     'education': ['low', 'medium', 'high', 'low', 'high', 'low'],
+        ...     'country': ['US', 'FR', 'US', 'FR', 'FR', 'FR']
+        ... })
+
+        >>> df
+                gender  education   country
+        0       male    low         US
+        1       male    medium      FR
+        2       female  high        US
+        3       male    low         FR
+        4       female  high        FR
+        5       male    low         FR
+
+        >>> df.groupby('gender').value_counts()
+        gender  education  country
+        female  high       FR         1
+                           US         1
+        male    low        FR         2
+                           US         1
+                medium     FR         1
+        Name: count, dtype: int64
+
+        >>> df.groupby('gender').value_counts(ascending=True)
+        gender  education  country
+        female  high       FR         1
+                           US         1
+        male    low        US         1
+                medium     FR         1
+                low        FR         2
+        Name: count, dtype: int64
+
+        >>> df.groupby('gender').value_counts(normalize=True)
+        gender  education  country
+        female  high       FR         0.50
+                           US         0.50
+        male    low        FR         0.50
+                           US         0.25
+                medium     FR         0.25
+        Name: proportion, dtype: float64
+
+        >>> df.groupby('gender', as_index=False).value_counts()
+           gender education country  count
+        0  female      high      FR      1
+        1  female      high      US      1
+        2    male       low      FR      2
+        3    male       low      US      1
+        4    male    medium      FR      1
+
+        >>> df.groupby('gender', as_index=False).value_counts(normalize=True)
+           gender education country  proportion
+        0  female      high      FR        0.50
+        1  female      high      US        0.50
+        2    male       low      FR        0.50
+        3    male       low      US        0.25
+        4    male    medium      FR        0.25
+        """
+        return self._value_counts(subset, normalize, sort, ascending, dropna)
+
+    def fillna(
+        self,
+        value: Hashable | Mapping | Series | DataFrame | None = None,
+        method: FillnaOptions | None = None,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        inplace: bool = False,
+        limit: int | None = None,
+        downcast=lib.no_default,
+    ) -> DataFrame | None:
+        """
+        Fill NA/NaN values using the specified method within groups.
+
+        .. deprecated:: 2.2.0
+            This method is deprecated and will be removed in a future version.
+            Use the :meth:`.DataFrameGroupBy.ffill` or :meth:`.DataFrameGroupBy.bfill`
+            for forward or backward filling instead. If you want to fill with a
+            single value, use :meth:`DataFrame.fillna` instead.
+
+        Parameters
+        ----------
+        value : scalar, dict, Series, or DataFrame
+            Value to use to fill holes (e.g. 0), alternately a
+            dict/Series/DataFrame of values specifying which value to use for
+            each index (for a Series) or column (for a DataFrame).  Values not
+            in the dict/Series/DataFrame will not be filled. This value cannot
+            be a list. Users wanting to use the ``value`` argument and not ``method``
+            should prefer :meth:`.DataFrame.fillna` as this
+            will produce the same result and be more performant.
+        method : {{'bfill', 'ffill', None}}, default None
+            Method to use for filling holes. ``'ffill'`` will propagate
+            the last valid observation forward within a group.
+            ``'bfill'`` will use next valid observation to fill the gap.
+        axis : {0 or 'index', 1 or 'columns'}
+            Axis along which to fill missing values. When the :class:`DataFrameGroupBy`
+            ``axis`` argument is ``0``, using ``axis=1`` here will produce
+            the same results as :meth:`.DataFrame.fillna`. When the
+            :class:`DataFrameGroupBy` ``axis`` argument is ``1``, using ``axis=0``
+            or ``axis=1`` here will produce the same results.
+        inplace : bool, default False
+            Broken. Do not set to True.
+        limit : int, default None
+            If method is specified, this is the maximum number of consecutive
+            NaN values to forward/backward fill within a group. In other words,
+            if there is a gap with more than this number of consecutive NaNs,
+            it will only be partially filled. If method is not specified, this is the
+            maximum number of entries along the entire axis where NaNs will be
+            filled. Must be greater than 0 if not None.
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+        Returns
+        -------
+        DataFrame
+            Object with missing values filled.
+
+        See Also
+        --------
+        ffill : Forward fill values within a group.
+        bfill : Backward fill values within a group.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         "key": [0, 0, 1, 1, 1],
+        ...         "A": [np.nan, 2, np.nan, 3, np.nan],
+        ...         "B": [2, 3, np.nan, np.nan, np.nan],
+        ...         "C": [np.nan, np.nan, 2, np.nan, np.nan],
+        ...     }
+        ... )
+        >>> df
+           key    A    B   C
+        0    0  NaN  2.0 NaN
+        1    0  2.0  3.0 NaN
+        2    1  NaN  NaN 2.0
+        3    1  3.0  NaN NaN
+        4    1  NaN  NaN NaN
+
+        Propagate non-null values forward or backward within each group along columns.
+
+        >>> df.groupby("key").fillna(method="ffill")
+             A    B   C
+        0  NaN  2.0 NaN
+        1  2.0  3.0 NaN
+        2  NaN  NaN 2.0
+        3  3.0  NaN 2.0
+        4  3.0  NaN 2.0
+
+        >>> df.groupby("key").fillna(method="bfill")
+             A    B   C
+        0  2.0  2.0 NaN
+        1  2.0  3.0 NaN
+        2  3.0  NaN 2.0
+        3  3.0  NaN NaN
+        4  NaN  NaN NaN
+
+        Propagate non-null values forward or backward within each group along rows.
+
+        >>> df.T.groupby(np.array([0, 0, 1, 1])).fillna(method="ffill").T
+           key    A    B    C
+        0  0.0  0.0  2.0  2.0
+        1  0.0  2.0  3.0  3.0
+        2  1.0  1.0  NaN  2.0
+        3  1.0  3.0  NaN  NaN
+        4  1.0  1.0  NaN  NaN
+
+        >>> df.T.groupby(np.array([0, 0, 1, 1])).fillna(method="bfill").T
+           key    A    B    C
+        0  0.0  NaN  2.0  NaN
+        1  0.0  2.0  3.0  NaN
+        2  1.0  NaN  2.0  2.0
+        3  1.0  3.0  NaN  NaN
+        4  1.0  NaN  NaN  NaN
+
+        Only replace the first NaN element within a group along rows.
+
+        >>> df.groupby("key").fillna(method="ffill", limit=1)
+             A    B    C
+        0  NaN  2.0  NaN
+        1  2.0  3.0  NaN
+        2  NaN  NaN  2.0
+        3  3.0  NaN  2.0
+        4  3.0  NaN  NaN
+        """
+        warnings.warn(
+            f"{type(self).__name__}.fillna is deprecated and "
+            "will be removed in a future version. Use obj.ffill() or obj.bfill() "
+            "for forward or backward filling instead. If you want to fill with a "
+            f"single value, use {type(self.obj).__name__}.fillna instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        result = self._op_via_apply(
+            "fillna",
+            value=value,
+            method=method,
+            axis=axis,
+            inplace=inplace,
+            limit=limit,
+            downcast=downcast,
+        )
+        return result
+
+    def take(
+        self,
+        indices: TakeIndexer,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        **kwargs,
+    ) -> DataFrame:
+        """
+        Return the elements in the given *positional* indices in each group.
+
+        This means that we are not indexing according to actual values in
+        the index attribute of the object. We are indexing according to the
+        actual position of the element in the object.
+
+        If a requested index does not exist for some group, this method will raise.
+        To get similar behavior that ignores indices that don't exist, see
+        :meth:`.DataFrameGroupBy.nth`.
+
+        Parameters
+        ----------
+        indices : array-like
+            An array of ints indicating which positions to take.
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            The axis on which to select elements. ``0`` means that we are
+            selecting rows, ``1`` means that we are selecting columns.
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        **kwargs
+            For compatibility with :meth:`numpy.take`. Has no effect on the
+            output.
+
+        Returns
+        -------
+        DataFrame
+            An DataFrame containing the elements taken from each group.
+
+        See Also
+        --------
+        DataFrame.take : Take elements from a Series along an axis.
+        DataFrame.loc : Select a subset of a DataFrame by labels.
+        DataFrame.iloc : Select a subset of a DataFrame by positions.
+        numpy.take : Take elements from an array along an axis.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([('falcon', 'bird', 389.0),
+        ...                    ('parrot', 'bird', 24.0),
+        ...                    ('lion', 'mammal', 80.5),
+        ...                    ('monkey', 'mammal', np.nan),
+        ...                    ('rabbit', 'mammal', 15.0)],
+        ...                   columns=['name', 'class', 'max_speed'],
+        ...                   index=[4, 3, 2, 1, 0])
+        >>> df
+             name   class  max_speed
+        4  falcon    bird      389.0
+        3  parrot    bird       24.0
+        2    lion  mammal       80.5
+        1  monkey  mammal        NaN
+        0  rabbit  mammal       15.0
+        >>> gb = df.groupby([1, 1, 2, 2, 2])
+
+        Take elements at positions 0 and 1 along the axis 0 (default).
+
+        Note how the indices selected in the result do not correspond to
+        our input indices 0 and 1. That's because we are selecting the 0th
+        and 1st rows, not rows whose indices equal 0 and 1.
+
+        >>> gb.take([0, 1])
+               name   class  max_speed
+        1 4  falcon    bird      389.0
+          3  parrot    bird       24.0
+        2 2    lion  mammal       80.5
+          1  monkey  mammal        NaN
+
+        The order of the specified indices influences the order in the result.
+        Here, the order is swapped from the previous example.
+
+        >>> gb.take([1, 0])
+               name   class  max_speed
+        1 3  parrot    bird       24.0
+          4  falcon    bird      389.0
+        2 1  monkey  mammal        NaN
+          2    lion  mammal       80.5
+
+        Take elements at indices 1 and 2 along the axis 1 (column selection).
+
+        We may take elements using negative integers for positive indices,
+        starting from the end of the object, just like with Python lists.
+
+        >>> gb.take([-1, -2])
+               name   class  max_speed
+        1 3  parrot    bird       24.0
+          4  falcon    bird      389.0
+        2 0  rabbit  mammal       15.0
+          1  monkey  mammal        NaN
+        """
+        result = self._op_via_apply("take", indices=indices, axis=axis, **kwargs)
+        return result
+
+    def skew(
+        self,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ) -> DataFrame:
+        """
+        Return unbiased skew within groups.
+
+        Normalized by N-1.
+
+        Parameters
+        ----------
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            Axis for the function to be applied on.
+
+            Specifying ``axis=None`` will apply the aggregation across both axes.
+
+            .. versionadded:: 2.0.0
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        skipna : bool, default True
+            Exclude NA/null values when computing the result.
+
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+
+        **kwargs
+            Additional keyword arguments to be passed to the function.
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        DataFrame.skew : Return unbiased skew over requested axis.
+
+        Examples
+        --------
+        >>> arrays = [['falcon', 'parrot', 'cockatoo', 'kiwi',
+        ...            'lion', 'monkey', 'rabbit'],
+        ...           ['bird', 'bird', 'bird', 'bird',
+        ...            'mammal', 'mammal', 'mammal']]
+        >>> index = pd.MultiIndex.from_arrays(arrays, names=('name', 'class'))
+        >>> df = pd.DataFrame({'max_speed': [389.0, 24.0, 70.0, np.nan,
+        ...                                  80.5, 21.5, 15.0]},
+        ...                   index=index)
+        >>> df
+                        max_speed
+        name     class
+        falcon   bird        389.0
+        parrot   bird         24.0
+        cockatoo bird         70.0
+        kiwi     bird          NaN
+        lion     mammal       80.5
+        monkey   mammal       21.5
+        rabbit   mammal       15.0
+        >>> gb = df.groupby(["class"])
+        >>> gb.skew()
+                max_speed
+        class
+        bird     1.628296
+        mammal   1.669046
+        >>> gb.skew(skipna=False)
+                max_speed
+        class
+        bird          NaN
+        mammal   1.669046
+        """
+        if axis is lib.no_default:
+            axis = 0
+
+        if axis != 0:
+            result = self._op_via_apply(
+                "skew",
+                axis=axis,
+                skipna=skipna,
+                numeric_only=numeric_only,
+                **kwargs,
+            )
+            return result
+
+        def alt(obj):
+            # This should not be reached since the cython path should raise
+            #  TypeError and not NotImplementedError.
+            raise TypeError(f"'skew' is not supported for dtype={obj.dtype}")
+
+        return self._cython_agg_general(
+            "skew", alt=alt, skipna=skipna, numeric_only=numeric_only, **kwargs
+        )
+
+    @property
+    @doc(DataFrame.plot.__doc__)
+    def plot(self) -> GroupByPlot:
+        result = GroupByPlot(self)
+        return result
+
+    @doc(DataFrame.corr.__doc__)
+    def corr(
+        self,
+        method: str | Callable[[np.ndarray, np.ndarray], float] = "pearson",
+        min_periods: int = 1,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        result = self._op_via_apply(
+            "corr", method=method, min_periods=min_periods, numeric_only=numeric_only
+        )
+        return result
+
+    @doc(DataFrame.cov.__doc__)
+    def cov(
+        self,
+        min_periods: int | None = None,
+        ddof: int | None = 1,
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        result = self._op_via_apply(
+            "cov", min_periods=min_periods, ddof=ddof, numeric_only=numeric_only
+        )
+        return result
+
+    @doc(DataFrame.hist.__doc__)
+    def hist(
+        self,
+        column: IndexLabel | None = None,
+        by=None,
+        grid: bool = True,
+        xlabelsize: int | None = None,
+        xrot: float | None = None,
+        ylabelsize: int | None = None,
+        yrot: float | None = None,
+        ax=None,
+        sharex: bool = False,
+        sharey: bool = False,
+        figsize: tuple[int, int] | None = None,
+        layout: tuple[int, int] | None = None,
+        bins: int | Sequence[int] = 10,
+        backend: str | None = None,
+        legend: bool = False,
+        **kwargs,
+    ):
+        result = self._op_via_apply(
+            "hist",
+            column=column,
+            by=by,
+            grid=grid,
+            xlabelsize=xlabelsize,
+            xrot=xrot,
+            ylabelsize=ylabelsize,
+            yrot=yrot,
+            ax=ax,
+            sharex=sharex,
+            sharey=sharey,
+            figsize=figsize,
+            layout=layout,
+            bins=bins,
+            backend=backend,
+            legend=legend,
+            **kwargs,
+        )
+        return result
+
+    @property
+    @doc(DataFrame.dtypes.__doc__)
+    def dtypes(self) -> Series:
+        # GH#51045
+        warnings.warn(
+            f"{type(self).__name__}.dtypes is deprecated and will be removed in "
+            "a future version. Check the dtypes on the base object instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        # error: Incompatible return value type (got "DataFrame", expected "Series")
+        return self._python_apply_general(  # type: ignore[return-value]
+            lambda df: df.dtypes, self._selected_obj
+        )
+
+    @doc(DataFrame.corrwith.__doc__)
+    def corrwith(
+        self,
+        other: DataFrame | Series,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        drop: bool = False,
+        method: CorrelationMethod = "pearson",
+        numeric_only: bool = False,
+    ) -> DataFrame:
+        result = self._op_via_apply(
+            "corrwith",
+            other=other,
+            axis=axis,
+            drop=drop,
+            method=method,
+            numeric_only=numeric_only,
+        )
+        return result
+
+
+def _wrap_transform_general_frame(
+    obj: DataFrame, group: DataFrame, res: DataFrame | Series
+) -> DataFrame:
+    from pandas import concat
+
+    if isinstance(res, Series):
+        # we need to broadcast across the
+        # other dimension; this will preserve dtypes
+        # GH14457
+        if res.index.is_(obj.index):
+            res_frame = concat([res] * len(group.columns), axis=1)
+            res_frame.columns = group.columns
+            res_frame.index = group.index
+        else:
+            res_frame = obj._constructor(
+                np.tile(res.values, (len(group.index), 1)),
+                columns=group.columns,
+                index=group.index,
+            )
+        assert isinstance(res_frame, DataFrame)
+        return res_frame
+    elif isinstance(res, DataFrame) and not res.index.is_(group.index):
+        return res._align_frame(group)[0]
+    else:
+        return res
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/groupby.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/groupby.py
new file mode 100644
index 0000000000000000000000000000000000000000..5baa2a9b703cc4100aa6a342b3b9f5a3d6775e64
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/groupby.py
@@ -0,0 +1,6023 @@
+"""
+Provide the groupby split-apply-combine paradigm. Define the GroupBy
+class providing the base-class of operations.
+
+The SeriesGroupBy and DataFrameGroupBy sub-class
+(defined in pandas.core.groupby.generic)
+expose these user-facing objects to provide specific functionality.
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterator,
+    Mapping,
+    Sequence,
+)
+import datetime
+from functools import (
+    partial,
+    wraps,
+)
+import inspect
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    TypeVar,
+    Union,
+    cast,
+    final,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+from pandas._config.config import option_context
+
+from pandas._libs import (
+    Timestamp,
+    lib,
+)
+from pandas._libs.algos import rank_1d
+import pandas._libs.groupby as libgroupby
+from pandas._libs.missing import NA
+from pandas._typing import (
+    AnyArrayLike,
+    ArrayLike,
+    Axis,
+    AxisInt,
+    DtypeObj,
+    FillnaOptions,
+    IndexLabel,
+    NDFrameT,
+    PositionalIndexer,
+    RandomState,
+    Scalar,
+    T,
+    npt,
+)
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    AbstractMethodError,
+    DataError,
+)
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    coerce_indexer_dtype,
+    ensure_dtype_can_hold_na,
+)
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_float_dtype,
+    is_hashable,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    needs_i8_conversion,
+    pandas_dtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+    notna,
+)
+
+from pandas.core import (
+    algorithms,
+    sample,
+)
+from pandas.core._numba import executor
+from pandas.core.apply import warn_alias_replacement
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    BaseMaskedArray,
+    Categorical,
+    ExtensionArray,
+    FloatingArray,
+    IntegerArray,
+    SparseArray,
+)
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.arrays.string_arrow import (
+    ArrowStringArray,
+    ArrowStringArrayNumpySemantics,
+)
+from pandas.core.base import (
+    PandasObject,
+    SelectionMixin,
+)
+import pandas.core.common as com
+from pandas.core.frame import DataFrame
+from pandas.core.generic import NDFrame
+from pandas.core.groupby import (
+    base,
+    numba_,
+    ops,
+)
+from pandas.core.groupby.grouper import get_grouper
+from pandas.core.groupby.indexing import (
+    GroupByIndexingMixin,
+    GroupByNthSelector,
+)
+from pandas.core.indexes.api import (
+    CategoricalIndex,
+    Index,
+    MultiIndex,
+    RangeIndex,
+    default_index,
+)
+from pandas.core.internals.blocks import ensure_block_shape
+from pandas.core.series import Series
+from pandas.core.sorting import get_group_index_sorter
+from pandas.core.util.numba_ import (
+    get_jit_arguments,
+    maybe_use_numba,
+)
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from pandas.core.resample import Resampler
+    from pandas.core.window import (
+        ExpandingGroupby,
+        ExponentialMovingWindowGroupby,
+        RollingGroupby,
+    )
+
+_common_see_also = """
+        See Also
+        --------
+        Series.%(name)s : Apply a function %(name)s to a Series.
+        DataFrame.%(name)s : Apply a function %(name)s
+            to each row or column of a DataFrame.
+"""
+
+_apply_docs = {
+    "template": """
+    Apply function ``func`` group-wise and combine the results together.
+
+    The function passed to ``apply`` must take a {input} as its first
+    argument and return a DataFrame, Series or scalar. ``apply`` will
+    then take care of combining the results back together into a single
+    dataframe or series. ``apply`` is therefore a highly flexible
+    grouping method.
+
+    While ``apply`` is a very flexible method, its downside is that
+    using it can be quite a bit slower than using more specific methods
+    like ``agg`` or ``transform``. Pandas offers a wide range of method that will
+    be much faster than using ``apply`` for their specific purposes, so try to
+    use them before reaching for ``apply``.
+
+    Parameters
+    ----------
+    func : callable
+        A callable that takes a {input} as its first argument, and
+        returns a dataframe, a series or a scalar. In addition the
+        callable may take positional and keyword arguments.
+    include_groups : bool, default True
+        When True, will attempt to apply ``func`` to the groupings in
+        the case that they are columns of the DataFrame. If this raises a
+        TypeError, the result will be computed with the groupings excluded.
+        When False, the groupings will be excluded when applying ``func``.
+
+        .. versionadded:: 2.2.0
+
+        .. deprecated:: 2.2.0
+
+           Setting include_groups to True is deprecated. Only the value
+           False will be allowed in a future version of pandas.
+
+    args, kwargs : tuple and dict
+        Optional positional and keyword arguments to pass to ``func``.
+
+    Returns
+    -------
+    Series or DataFrame
+
+    See Also
+    --------
+    pipe : Apply function to the full GroupBy object instead of to each
+        group.
+    aggregate : Apply aggregate function to the GroupBy object.
+    transform : Apply function column-by-column to the GroupBy object.
+    Series.apply : Apply a function to a Series.
+    DataFrame.apply : Apply a function to each row or column of a DataFrame.
+
+    Notes
+    -----
+
+    .. versionchanged:: 1.3.0
+
+        The resulting dtype will reflect the return value of the passed ``func``,
+        see the examples below.
+
+    Functions that mutate the passed object can produce unexpected
+    behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+    for more details.
+
+    Examples
+    --------
+    {examples}
+    """,
+    "dataframe_examples": """
+    >>> df = pd.DataFrame({'A': 'a a b'.split(),
+    ...                    'B': [1, 2, 3],
+    ...                    'C': [4, 6, 5]})
+    >>> g1 = df.groupby('A', group_keys=False)
+    >>> g2 = df.groupby('A', group_keys=True)
+
+    Notice that ``g1`` and ``g2`` have two groups, ``a`` and ``b``, and only
+    differ in their ``group_keys`` argument. Calling `apply` in various ways,
+    we can get different grouping results:
+
+    Example 1: below the function passed to `apply` takes a DataFrame as
+    its argument and returns a DataFrame. `apply` combines the result for
+    each group together into a new DataFrame:
+
+    >>> g1[['B', 'C']].apply(lambda x: x / x.sum())
+              B    C
+    0  0.333333  0.4
+    1  0.666667  0.6
+    2  1.000000  1.0
+
+    In the above, the groups are not part of the index. We can have them included
+    by using ``g2`` where ``group_keys=True``:
+
+    >>> g2[['B', 'C']].apply(lambda x: x / x.sum())
+                B    C
+    A
+    a 0  0.333333  0.4
+      1  0.666667  0.6
+    b 2  1.000000  1.0
+
+    Example 2: The function passed to `apply` takes a DataFrame as
+    its argument and returns a Series.  `apply` combines the result for
+    each group together into a new DataFrame.
+
+    .. versionchanged:: 1.3.0
+
+        The resulting dtype will reflect the return value of the passed ``func``.
+
+    >>> g1[['B', 'C']].apply(lambda x: x.astype(float).max() - x.min())
+         B    C
+    A
+    a  1.0  2.0
+    b  0.0  0.0
+
+    >>> g2[['B', 'C']].apply(lambda x: x.astype(float).max() - x.min())
+         B    C
+    A
+    a  1.0  2.0
+    b  0.0  0.0
+
+    The ``group_keys`` argument has no effect here because the result is not
+    like-indexed (i.e. :ref:`a transform `) when compared
+    to the input.
+
+    Example 3: The function passed to `apply` takes a DataFrame as
+    its argument and returns a scalar. `apply` combines the result for
+    each group together into a Series, including setting the index as
+    appropriate:
+
+    >>> g1.apply(lambda x: x.C.max() - x.B.min(), include_groups=False)
+    A
+    a    5
+    b    2
+    dtype: int64""",
+    "series_examples": """
+    >>> s = pd.Series([0, 1, 2], index='a a b'.split())
+    >>> g1 = s.groupby(s.index, group_keys=False)
+    >>> g2 = s.groupby(s.index, group_keys=True)
+
+    From ``s`` above we can see that ``g`` has two groups, ``a`` and ``b``.
+    Notice that ``g1`` have ``g2`` have two groups, ``a`` and ``b``, and only
+    differ in their ``group_keys`` argument. Calling `apply` in various ways,
+    we can get different grouping results:
+
+    Example 1: The function passed to `apply` takes a Series as
+    its argument and returns a Series.  `apply` combines the result for
+    each group together into a new Series.
+
+    .. versionchanged:: 1.3.0
+
+        The resulting dtype will reflect the return value of the passed ``func``.
+
+    >>> g1.apply(lambda x: x * 2 if x.name == 'a' else x / 2)
+    a    0.0
+    a    2.0
+    b    1.0
+    dtype: float64
+
+    In the above, the groups are not part of the index. We can have them included
+    by using ``g2`` where ``group_keys=True``:
+
+    >>> g2.apply(lambda x: x * 2 if x.name == 'a' else x / 2)
+    a  a    0.0
+       a    2.0
+    b  b    1.0
+    dtype: float64
+
+    Example 2: The function passed to `apply` takes a Series as
+    its argument and returns a scalar. `apply` combines the result for
+    each group together into a Series, including setting the index as
+    appropriate:
+
+    >>> g1.apply(lambda x: x.max() - x.min())
+    a    1
+    b    0
+    dtype: int64
+
+    The ``group_keys`` argument has no effect here because the result is not
+    like-indexed (i.e. :ref:`a transform `) when compared
+    to the input.
+
+    >>> g2.apply(lambda x: x.max() - x.min())
+    a    1
+    b    0
+    dtype: int64""",
+}
+
+_groupby_agg_method_template = """
+Compute {fname} of group values.
+
+Parameters
+----------
+numeric_only : bool, default {no}
+    Include only float, int, boolean columns.
+
+    .. versionchanged:: 2.0.0
+
+        numeric_only no longer accepts ``None``.
+
+min_count : int, default {mc}
+    The required number of valid values to perform the operation. If fewer
+    than ``min_count`` non-NA values are present the result will be NA.
+
+Returns
+-------
+Series or DataFrame
+    Computed {fname} of values within each group.
+
+Examples
+--------
+{example}
+"""
+
+_groupby_agg_method_engine_template = """
+Compute {fname} of group values.
+
+Parameters
+----------
+numeric_only : bool, default {no}
+    Include only float, int, boolean columns.
+
+    .. versionchanged:: 2.0.0
+
+        numeric_only no longer accepts ``None``.
+
+min_count : int, default {mc}
+    The required number of valid values to perform the operation. If fewer
+    than ``min_count`` non-NA values are present the result will be NA.
+
+engine : str, default None {e}
+    * ``'cython'`` : Runs rolling apply through C-extensions from cython.
+    * ``'numba'`` : Runs rolling apply through JIT compiled code from numba.
+        Only available when ``raw`` is set to ``True``.
+    * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
+
+engine_kwargs : dict, default None {ek}
+    * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+    * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+        and ``parallel`` dictionary keys. The values must either be ``True`` or
+        ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+        ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
+        applied to both the ``func`` and the ``apply`` groupby aggregation.
+
+Returns
+-------
+Series or DataFrame
+    Computed {fname} of values within each group.
+
+Examples
+--------
+{example}
+"""
+
+_pipe_template = """
+Apply a ``func`` with arguments to this %(klass)s object and return its result.
+
+Use `.pipe` when you want to improve readability by chaining together
+functions that expect Series, DataFrames, GroupBy or Resampler objects.
+Instead of writing
+
+>>> h = lambda x, arg2, arg3: x + 1 - arg2 * arg3
+>>> g = lambda x, arg1: x * 5 / arg1
+>>> f = lambda x: x ** 4
+>>> df = pd.DataFrame([["a", 4], ["b", 5]], columns=["group", "value"])
+>>> h(g(f(df.groupby('group')), arg1=1), arg2=2, arg3=3)  # doctest: +SKIP
+
+You can write
+
+>>> (df.groupby('group')
+...    .pipe(f)
+...    .pipe(g, arg1=1)
+...    .pipe(h, arg2=2, arg3=3))  # doctest: +SKIP
+
+which is much more readable.
+
+Parameters
+----------
+func : callable or tuple of (callable, str)
+    Function to apply to this %(klass)s object or, alternatively,
+    a `(callable, data_keyword)` tuple where `data_keyword` is a
+    string indicating the keyword of `callable` that expects the
+    %(klass)s object.
+args : iterable, optional
+       Positional arguments passed into `func`.
+kwargs : dict, optional
+         A dictionary of keyword arguments passed into `func`.
+
+Returns
+-------
+the return type of `func`.
+
+See Also
+--------
+Series.pipe : Apply a function with arguments to a series.
+DataFrame.pipe: Apply a function with arguments to a dataframe.
+apply : Apply function to each group instead of to the
+    full %(klass)s object.
+
+Notes
+-----
+See more `here
+`_
+
+Examples
+--------
+%(examples)s
+"""
+
+_transform_template = """
+Call function producing a same-indexed %(klass)s on each group.
+
+Returns a %(klass)s having the same indexes as the original object
+filled with the transformed values.
+
+Parameters
+----------
+f : function, str
+    Function to apply to each group. See the Notes section below for requirements.
+
+    Accepted inputs are:
+
+    - String
+    - Python function
+    - Numba JIT function with ``engine='numba'`` specified.
+
+    Only passing a single function is supported with this engine.
+    If the ``'numba'`` engine is chosen, the function must be
+    a user defined function with ``values`` and ``index`` as the
+    first and second arguments respectively in the function signature.
+    Each group's index will be passed to the user defined function
+    and optionally available for use.
+
+    If a string is chosen, then it needs to be the name
+    of the groupby method you want to use.
+*args
+    Positional arguments to pass to func.
+engine : str, default None
+    * ``'cython'`` : Runs the function through C-extensions from cython.
+    * ``'numba'`` : Runs the function through JIT compiled code from numba.
+    * ``None`` : Defaults to ``'cython'`` or the global setting ``compute.use_numba``
+
+engine_kwargs : dict, default None
+    * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+    * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+      and ``parallel`` dictionary keys. The values must either be ``True`` or
+      ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+      ``{'nopython': True, 'nogil': False, 'parallel': False}`` and will be
+      applied to the function
+
+**kwargs
+    Keyword arguments to be passed into func.
+
+Returns
+-------
+%(klass)s
+
+See Also
+--------
+%(klass)s.groupby.apply : Apply function ``func`` group-wise and combine
+    the results together.
+%(klass)s.groupby.aggregate : Aggregate using one or more
+    operations over the specified axis.
+%(klass)s.transform : Call ``func`` on self producing a %(klass)s with the
+    same axis shape as self.
+
+Notes
+-----
+Each group is endowed the attribute 'name' in case you need to know
+which group you are working on.
+
+The current implementation imposes three requirements on f:
+
+* f must return a value that either has the same shape as the input
+  subframe or can be broadcast to the shape of the input subframe.
+  For example, if `f` returns a scalar it will be broadcast to have the
+  same shape as the input subframe.
+* if this is a DataFrame, f must support application column-by-column
+  in the subframe. If f also supports application to the entire subframe,
+  then a fast path is used starting from the second chunk.
+* f must not mutate groups. Mutation is not supported and may
+  produce unexpected results. See :ref:`gotchas.udf-mutation` for more details.
+
+When using ``engine='numba'``, there will be no "fall back" behavior internally.
+The group data and group index will be passed as numpy arrays to the JITed
+user defined function, and no alternative execution attempts will be tried.
+
+.. versionchanged:: 1.3.0
+
+    The resulting dtype will reflect the return value of the passed ``func``,
+    see the examples below.
+
+.. versionchanged:: 2.0.0
+
+    When using ``.transform`` on a grouped DataFrame and the transformation function
+    returns a DataFrame, pandas now aligns the result's index
+    with the input's index. You can call ``.to_numpy()`` on the
+    result of the transformation function to avoid alignment.
+
+Examples
+--------
+%(example)s"""
+
+_agg_template_series = """
+Aggregate using one or more operations over the specified axis.
+
+Parameters
+----------
+func : function, str, list, dict or None
+    Function to use for aggregating the data. If a function, must either
+    work when passed a {klass} or when passed to {klass}.apply.
+
+    Accepted combinations are:
+
+    - function
+    - string function name
+    - list of functions and/or function names, e.g. ``[np.sum, 'mean']``
+    - None, in which case ``**kwargs`` are used with Named Aggregation. Here the
+      output has one column for each element in ``**kwargs``. The name of the
+      column is keyword, whereas the value determines the aggregation used to compute
+      the values in the column.
+
+      Can also accept a Numba JIT function with
+      ``engine='numba'`` specified. Only passing a single function is supported
+      with this engine.
+
+      If the ``'numba'`` engine is chosen, the function must be
+      a user defined function with ``values`` and ``index`` as the
+      first and second arguments respectively in the function signature.
+      Each group's index will be passed to the user defined function
+      and optionally available for use.
+
+    .. deprecated:: 2.1.0
+
+        Passing a dictionary is deprecated and will raise in a future version
+        of pandas. Pass a list of aggregations instead.
+*args
+    Positional arguments to pass to func.
+engine : str, default None
+    * ``'cython'`` : Runs the function through C-extensions from cython.
+    * ``'numba'`` : Runs the function through JIT compiled code from numba.
+    * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
+
+engine_kwargs : dict, default None
+    * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+    * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+      and ``parallel`` dictionary keys. The values must either be ``True`` or
+      ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+      ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
+      applied to the function
+
+**kwargs
+    * If ``func`` is None, ``**kwargs`` are used to define the output names and
+      aggregations via Named Aggregation. See ``func`` entry.
+    * Otherwise, keyword arguments to be passed into func.
+
+Returns
+-------
+{klass}
+
+See Also
+--------
+{klass}.groupby.apply : Apply function func group-wise
+    and combine the results together.
+{klass}.groupby.transform : Transforms the Series on each group
+    based on the given function.
+{klass}.aggregate : Aggregate using one or more
+    operations over the specified axis.
+
+Notes
+-----
+When using ``engine='numba'``, there will be no "fall back" behavior internally.
+The group data and group index will be passed as numpy arrays to the JITed
+user defined function, and no alternative execution attempts will be tried.
+
+Functions that mutate the passed object can produce unexpected
+behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+for more details.
+
+.. versionchanged:: 1.3.0
+
+    The resulting dtype will reflect the return value of the passed ``func``,
+    see the examples below.
+{examples}"""
+
+_agg_template_frame = """
+Aggregate using one or more operations over the specified axis.
+
+Parameters
+----------
+func : function, str, list, dict or None
+    Function to use for aggregating the data. If a function, must either
+    work when passed a {klass} or when passed to {klass}.apply.
+
+    Accepted combinations are:
+
+    - function
+    - string function name
+    - list of functions and/or function names, e.g. ``[np.sum, 'mean']``
+    - dict of axis labels -> functions, function names or list of such.
+    - None, in which case ``**kwargs`` are used with Named Aggregation. Here the
+      output has one column for each element in ``**kwargs``. The name of the
+      column is keyword, whereas the value determines the aggregation used to compute
+      the values in the column.
+
+      Can also accept a Numba JIT function with
+      ``engine='numba'`` specified. Only passing a single function is supported
+      with this engine.
+
+      If the ``'numba'`` engine is chosen, the function must be
+      a user defined function with ``values`` and ``index`` as the
+      first and second arguments respectively in the function signature.
+      Each group's index will be passed to the user defined function
+      and optionally available for use.
+
+*args
+    Positional arguments to pass to func.
+engine : str, default None
+    * ``'cython'`` : Runs the function through C-extensions from cython.
+    * ``'numba'`` : Runs the function through JIT compiled code from numba.
+    * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
+
+engine_kwargs : dict, default None
+    * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+    * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+      and ``parallel`` dictionary keys. The values must either be ``True`` or
+      ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+      ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
+      applied to the function
+
+**kwargs
+    * If ``func`` is None, ``**kwargs`` are used to define the output names and
+      aggregations via Named Aggregation. See ``func`` entry.
+    * Otherwise, keyword arguments to be passed into func.
+
+Returns
+-------
+{klass}
+
+See Also
+--------
+{klass}.groupby.apply : Apply function func group-wise
+    and combine the results together.
+{klass}.groupby.transform : Transforms the Series on each group
+    based on the given function.
+{klass}.aggregate : Aggregate using one or more
+    operations over the specified axis.
+
+Notes
+-----
+When using ``engine='numba'``, there will be no "fall back" behavior internally.
+The group data and group index will be passed as numpy arrays to the JITed
+user defined function, and no alternative execution attempts will be tried.
+
+Functions that mutate the passed object can produce unexpected
+behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+for more details.
+
+.. versionchanged:: 1.3.0
+
+    The resulting dtype will reflect the return value of the passed ``func``,
+    see the examples below.
+{examples}"""
+
+
+@final
+class GroupByPlot(PandasObject):
+    """
+    Class implementing the .plot attribute for groupby objects.
+    """
+
+    def __init__(self, groupby: GroupBy) -> None:
+        self._groupby = groupby
+
+    def __call__(self, *args, **kwargs):
+        def f(self):
+            return self.plot(*args, **kwargs)
+
+        f.__name__ = "plot"
+        return self._groupby._python_apply_general(f, self._groupby._selected_obj)
+
+    def __getattr__(self, name: str):
+        def attr(*args, **kwargs):
+            def f(self):
+                return getattr(self.plot, name)(*args, **kwargs)
+
+            return self._groupby._python_apply_general(f, self._groupby._selected_obj)
+
+        return attr
+
+
+_KeysArgType = Union[
+    Hashable,
+    list[Hashable],
+    Callable[[Hashable], Hashable],
+    list[Callable[[Hashable], Hashable]],
+    Mapping[Hashable, Hashable],
+]
+
+
+class BaseGroupBy(PandasObject, SelectionMixin[NDFrameT], GroupByIndexingMixin):
+    _hidden_attrs = PandasObject._hidden_attrs | {
+        "as_index",
+        "axis",
+        "dropna",
+        "exclusions",
+        "grouper",
+        "group_keys",
+        "keys",
+        "level",
+        "obj",
+        "observed",
+        "sort",
+    }
+
+    axis: AxisInt
+    _grouper: ops.BaseGrouper
+    keys: _KeysArgType | None = None
+    level: IndexLabel | None = None
+    group_keys: bool
+
+    @final
+    def __len__(self) -> int:
+        return len(self.groups)
+
+    @final
+    def __repr__(self) -> str:
+        # TODO: Better repr for GroupBy object
+        return object.__repr__(self)
+
+    @final
+    @property
+    def grouper(self) -> ops.BaseGrouper:
+        warnings.warn(
+            f"{type(self).__name__}.grouper is deprecated and will be removed in a "
+            "future version of pandas.",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._grouper
+
+    @final
+    @property
+    def groups(self) -> dict[Hashable, np.ndarray]:
+        """
+        Dict {group name -> group labels}.
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 3], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        dtype: int64
+        >>> ser.groupby(level=0).groups
+        {'a': ['a', 'a'], 'b': ['b']}
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"])
+        >>> df
+           a  b  c
+        0  1  2  3
+        1  1  5  6
+        2  7  8  9
+        >>> df.groupby(by=["a"]).groups
+        {1: [0, 1], 7: [2]}
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').groups
+        {Timestamp('2023-01-01 00:00:00'): 2, Timestamp('2023-02-01 00:00:00'): 4}
+        """
+        return self._grouper.groups
+
+    @final
+    @property
+    def ngroups(self) -> int:
+        return self._grouper.ngroups
+
+    @final
+    @property
+    def indices(self) -> dict[Hashable, npt.NDArray[np.intp]]:
+        """
+        Dict {group name -> group indices}.
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 3], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        dtype: int64
+        >>> ser.groupby(level=0).indices
+        {'a': array([0, 1]), 'b': array([2])}
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["owl", "toucan", "eagle"])
+        >>> df
+                a  b  c
+        owl     1  2  3
+        toucan  1  5  6
+        eagle   7  8  9
+        >>> df.groupby(by=["a"]).indices
+        {1: array([0, 1]), 7: array([2])}
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').indices
+        defaultdict(, {Timestamp('2023-01-01 00:00:00'): [0, 1],
+        Timestamp('2023-02-01 00:00:00'): [2, 3]})
+        """
+        return self._grouper.indices
+
+    @final
+    def _get_indices(self, names):
+        """
+        Safe get multiple indices, translate keys for
+        datelike to underlying repr.
+        """
+
+        def get_converter(s):
+            # possibly convert to the actual key types
+            # in the indices, could be a Timestamp or a np.datetime64
+            if isinstance(s, datetime.datetime):
+                return lambda key: Timestamp(key)
+            elif isinstance(s, np.datetime64):
+                return lambda key: Timestamp(key).asm8
+            else:
+                return lambda key: key
+
+        if len(names) == 0:
+            return []
+
+        if len(self.indices) > 0:
+            index_sample = next(iter(self.indices))
+        else:
+            index_sample = None  # Dummy sample
+
+        name_sample = names[0]
+        if isinstance(index_sample, tuple):
+            if not isinstance(name_sample, tuple):
+                msg = "must supply a tuple to get_group with multiple grouping keys"
+                raise ValueError(msg)
+            if not len(name_sample) == len(index_sample):
+                try:
+                    # If the original grouper was a tuple
+                    return [self.indices[name] for name in names]
+                except KeyError as err:
+                    # turns out it wasn't a tuple
+                    msg = (
+                        "must supply a same-length tuple to get_group "
+                        "with multiple grouping keys"
+                    )
+                    raise ValueError(msg) from err
+
+            converters = [get_converter(s) for s in index_sample]
+            names = (tuple(f(n) for f, n in zip(converters, name)) for name in names)
+
+        else:
+            converter = get_converter(index_sample)
+            names = (converter(name) for name in names)
+
+        return [self.indices.get(name, []) for name in names]
+
+    @final
+    def _get_index(self, name):
+        """
+        Safe get index, translate keys for datelike to underlying repr.
+        """
+        return self._get_indices([name])[0]
+
+    @final
+    @cache_readonly
+    def _selected_obj(self):
+        # Note: _selected_obj is always just `self.obj` for SeriesGroupBy
+        if isinstance(self.obj, Series):
+            return self.obj
+
+        if self._selection is not None:
+            if is_hashable(self._selection):
+                # i.e. a single key, so selecting it will return a Series.
+                #  In this case, _obj_with_exclusions would wrap the key
+                #  in a list and return a single-column DataFrame.
+                return self.obj[self._selection]
+
+            # Otherwise _selection is equivalent to _selection_list, so
+            #  _selected_obj matches _obj_with_exclusions, so we can reuse
+            #  that and avoid making a copy.
+            return self._obj_with_exclusions
+
+        return self.obj
+
+    @final
+    def _dir_additions(self) -> set[str]:
+        return self.obj._dir_additions()
+
+    @Substitution(
+        klass="GroupBy",
+        examples=dedent(
+            """\
+        >>> df = pd.DataFrame({'A': 'a b a b'.split(), 'B': [1, 2, 3, 4]})
+        >>> df
+           A  B
+        0  a  1
+        1  b  2
+        2  a  3
+        3  b  4
+
+        To get the difference between each groups maximum and minimum value in one
+        pass, you can do
+
+        >>> df.groupby('A').pipe(lambda x: x.max() - x.min())
+           B
+        A
+        a  2
+        b  2"""
+        ),
+    )
+    @Appender(_pipe_template)
+    def pipe(
+        self,
+        func: Callable[..., T] | tuple[Callable[..., T], str],
+        *args,
+        **kwargs,
+    ) -> T:
+        return com.pipe(self, func, *args, **kwargs)
+
+    @final
+    def get_group(self, name, obj=None) -> DataFrame | Series:
+        """
+        Construct DataFrame from group with provided name.
+
+        Parameters
+        ----------
+        name : object
+            The name of the group to get as a DataFrame.
+        obj : DataFrame, default None
+            The DataFrame to take the DataFrame out of.  If
+            it is None, the object groupby was called on will
+            be used.
+
+            .. deprecated:: 2.1.0
+                The obj is deprecated and will be removed in a future version.
+                Do ``df.iloc[gb.indices.get(name)]``
+                instead of ``gb.get_group(name, obj=df)``.
+
+        Returns
+        -------
+        same type as obj
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 3], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        dtype: int64
+        >>> ser.groupby(level=0).get_group("a")
+        a    1
+        a    2
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["owl", "toucan", "eagle"])
+        >>> df
+                a  b  c
+        owl     1  2  3
+        toucan  1  5  6
+        eagle   7  8  9
+        >>> df.groupby(by=["a"]).get_group((1,))
+                a  b  c
+        owl     1  2  3
+        toucan  1  5  6
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').get_group('2023-01-01')
+        2023-01-01    1
+        2023-01-15    2
+        dtype: int64
+        """
+        keys = self.keys
+        level = self.level
+        # mypy doesn't recognize level/keys as being sized when passed to len
+        if (is_list_like(level) and len(level) == 1) or (  # type: ignore[arg-type]
+            is_list_like(keys) and len(keys) == 1  # type: ignore[arg-type]
+        ):
+            # GH#25971
+            if isinstance(name, tuple) and len(name) == 1:
+                # Allow users to pass tuples of length 1 to silence warning
+                name = name[0]
+            elif not isinstance(name, tuple):
+                warnings.warn(
+                    "When grouping with a length-1 list-like, "
+                    "you will need to pass a length-1 tuple to get_group in a future "
+                    "version of pandas. Pass `(name,)` instead of `name` to silence "
+                    "this warning.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        inds = self._get_index(name)
+        if not len(inds):
+            raise KeyError(name)
+
+        if obj is None:
+            indexer = inds if self.axis == 0 else (slice(None), inds)
+            return self._selected_obj.iloc[indexer]
+        else:
+            warnings.warn(
+                "obj is deprecated and will be removed in a future version. "
+                "Do ``df.iloc[gb.indices.get(name)]`` "
+                "instead of ``gb.get_group(name, obj=df)``.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            return obj._take_with_is_copy(inds, axis=self.axis)
+
+    @final
+    def __iter__(self) -> Iterator[tuple[Hashable, NDFrameT]]:
+        """
+        Groupby iterator.
+
+        Returns
+        -------
+        Generator yielding sequence of (name, subsetted object)
+        for each group
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 3], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        dtype: int64
+        >>> for x, y in ser.groupby(level=0):
+        ...     print(f'{x}\\n{y}\\n')
+        a
+        a    1
+        a    2
+        dtype: int64
+        b
+        b    3
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"])
+        >>> df
+           a  b  c
+        0  1  2  3
+        1  1  5  6
+        2  7  8  9
+        >>> for x, y in df.groupby(by=["a"]):
+        ...     print(f'{x}\\n{y}\\n')
+        (1,)
+           a  b  c
+        0  1  2  3
+        1  1  5  6
+        (7,)
+           a  b  c
+        2  7  8  9
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> for x, y in ser.resample('MS'):
+        ...     print(f'{x}\\n{y}\\n')
+        2023-01-01 00:00:00
+        2023-01-01    1
+        2023-01-15    2
+        dtype: int64
+        2023-02-01 00:00:00
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        """
+        keys = self.keys
+        level = self.level
+        result = self._grouper.get_iterator(self._selected_obj, axis=self.axis)
+        # error: Argument 1 to "len" has incompatible type "Hashable"; expected "Sized"
+        if is_list_like(level) and len(level) == 1:  # type: ignore[arg-type]
+            # GH 51583
+            warnings.warn(
+                "Creating a Groupby object with a length-1 list-like "
+                "level parameter will yield indexes as tuples in a future version. "
+                "To keep indexes as scalars, create Groupby objects with "
+                "a scalar level parameter instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if isinstance(keys, list) and len(keys) == 1:
+            # GH#42795 - when keys is a list, return tuples even when length is 1
+            result = (((key,), group) for key, group in result)
+        return result
+
+
+# To track operations that expand dimensions, like ohlc
+OutputFrameOrSeries = TypeVar("OutputFrameOrSeries", bound=NDFrame)
+
+
+class GroupBy(BaseGroupBy[NDFrameT]):
+    """
+    Class for grouping and aggregating relational data.
+
+    See aggregate, transform, and apply functions on this object.
+
+    It's easiest to use obj.groupby(...) to use GroupBy, but you can also do:
+
+    ::
+
+        grouped = groupby(obj, ...)
+
+    Parameters
+    ----------
+    obj : pandas object
+    axis : int, default 0
+    level : int, default None
+        Level of MultiIndex
+    groupings : list of Grouping objects
+        Most users should ignore this
+    exclusions : array-like, optional
+        List of columns to exclude
+    name : str
+        Most users should ignore this
+
+    Returns
+    -------
+    **Attributes**
+    groups : dict
+        {group name -> group labels}
+    len(grouped) : int
+        Number of groups
+
+    Notes
+    -----
+    After grouping, see aggregate, apply, and transform functions. Here are
+    some other brief notes about usage. When grouping by multiple groups, the
+    result index will be a MultiIndex (hierarchical) by default.
+
+    Iteration produces (key, group) tuples, i.e. chunking the data by group. So
+    you can write code like:
+
+    ::
+
+        grouped = obj.groupby(keys, axis=axis)
+        for key, group in grouped:
+            # do something with the data
+
+    Function calls on GroupBy, if not specially implemented, "dispatch" to the
+    grouped data. So if you group a DataFrame and wish to invoke the std()
+    method on each group, you can simply do:
+
+    ::
+
+        df.groupby(mapper).std()
+
+    rather than
+
+    ::
+
+        df.groupby(mapper).aggregate(np.std)
+
+    You can pass arguments to these "wrapped" functions, too.
+
+    See the online documentation for full exposition on these topics and much
+    more
+    """
+
+    _grouper: ops.BaseGrouper
+    as_index: bool
+
+    @final
+    def __init__(
+        self,
+        obj: NDFrameT,
+        keys: _KeysArgType | None = None,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        grouper: ops.BaseGrouper | None = None,
+        exclusions: frozenset[Hashable] | None = None,
+        selection: IndexLabel | None = None,
+        as_index: bool = True,
+        sort: bool = True,
+        group_keys: bool = True,
+        observed: bool | lib.NoDefault = lib.no_default,
+        dropna: bool = True,
+    ) -> None:
+        self._selection = selection
+
+        assert isinstance(obj, NDFrame), type(obj)
+
+        self.level = level
+
+        if not as_index:
+            if axis != 0:
+                raise ValueError("as_index=False only valid for axis=0")
+
+        self.as_index = as_index
+        self.keys = keys
+        self.sort = sort
+        self.group_keys = group_keys
+        self.dropna = dropna
+
+        if grouper is None:
+            grouper, exclusions, obj = get_grouper(
+                obj,
+                keys,
+                axis=axis,
+                level=level,
+                sort=sort,
+                observed=False if observed is lib.no_default else observed,
+                dropna=self.dropna,
+            )
+
+        if observed is lib.no_default:
+            if any(ping._passed_categorical for ping in grouper.groupings):
+                warnings.warn(
+                    "The default of observed=False is deprecated and will be changed "
+                    "to True in a future version of pandas. Pass observed=False to "
+                    "retain current behavior or observed=True to adopt the future "
+                    "default and silence this warning.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            observed = False
+        self.observed = observed
+
+        self.obj = obj
+        self.axis = obj._get_axis_number(axis)
+        self._grouper = grouper
+        self.exclusions = frozenset(exclusions) if exclusions else frozenset()
+
+    def __getattr__(self, attr: str):
+        if attr in self._internal_names_set:
+            return object.__getattribute__(self, attr)
+        if attr in self.obj:
+            return self[attr]
+
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{attr}'"
+        )
+
+    @final
+    def _deprecate_axis(self, axis: int, name: str) -> None:
+        if axis == 1:
+            warnings.warn(
+                f"{type(self).__name__}.{name} with axis=1 is deprecated and "
+                "will be removed in a future version. Operate on the un-grouped "
+                "DataFrame instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            warnings.warn(
+                f"The 'axis' keyword in {type(self).__name__}.{name} is deprecated "
+                "and will be removed in a future version. "
+                "Call without passing 'axis' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    @final
+    def _op_via_apply(self, name: str, *args, **kwargs):
+        """Compute the result of an operation by using GroupBy's apply."""
+        f = getattr(type(self._obj_with_exclusions), name)
+        sig = inspect.signature(f)
+
+        if "axis" in kwargs and kwargs["axis"] is not lib.no_default:
+            axis = self.obj._get_axis_number(kwargs["axis"])
+            self._deprecate_axis(axis, name)
+        elif "axis" in kwargs:
+            # exclude skew here because that was already defaulting to lib.no_default
+            #  before this deprecation was instituted
+            if name == "skew":
+                pass
+            elif name == "fillna":
+                # maintain the behavior from before the deprecation
+                kwargs["axis"] = None
+            else:
+                kwargs["axis"] = 0
+
+        # a little trickery for aggregation functions that need an axis
+        # argument
+        if "axis" in sig.parameters:
+            if kwargs.get("axis", None) is None or kwargs.get("axis") is lib.no_default:
+                kwargs["axis"] = self.axis
+
+        def curried(x):
+            return f(x, *args, **kwargs)
+
+        # preserve the name so we can detect it when calling plot methods,
+        # to avoid duplicates
+        curried.__name__ = name
+
+        # special case otherwise extra plots are created when catching the
+        # exception below
+        if name in base.plotting_methods:
+            return self._python_apply_general(curried, self._selected_obj)
+
+        is_transform = name in base.transformation_kernels
+        result = self._python_apply_general(
+            curried,
+            self._obj_with_exclusions,
+            is_transform=is_transform,
+            not_indexed_same=not is_transform,
+        )
+
+        if self._grouper.has_dropped_na and is_transform:
+            # result will have dropped rows due to nans, fill with null
+            # and ensure index is ordered same as the input
+            result = self._set_result_index_ordered(result)
+        return result
+
+    # -----------------------------------------------------------------
+    # Dispatch/Wrapping
+
+    @final
+    def _concat_objects(
+        self,
+        values,
+        not_indexed_same: bool = False,
+        is_transform: bool = False,
+    ):
+        from pandas.core.reshape.concat import concat
+
+        if self.group_keys and not is_transform:
+            if self.as_index:
+                # possible MI return case
+                group_keys = self._grouper.result_index
+                group_levels = self._grouper.levels
+                group_names = self._grouper.names
+
+                result = concat(
+                    values,
+                    axis=self.axis,
+                    keys=group_keys,
+                    levels=group_levels,
+                    names=group_names,
+                    sort=False,
+                )
+            else:
+                # GH5610, returns a MI, with the first level being a
+                # range index
+                keys = list(range(len(values)))
+                result = concat(values, axis=self.axis, keys=keys)
+
+        elif not not_indexed_same:
+            result = concat(values, axis=self.axis)
+
+            ax = self._selected_obj._get_axis(self.axis)
+            if self.dropna:
+                labels = self._grouper.group_info[0]
+                mask = labels != -1
+                ax = ax[mask]
+
+            # this is a very unfortunate situation
+            # we can't use reindex to restore the original order
+            # when the ax has duplicates
+            # so we resort to this
+            # GH 14776, 30667
+            # TODO: can we reuse e.g. _reindex_non_unique?
+            if ax.has_duplicates and not result.axes[self.axis].equals(ax):
+                # e.g. test_category_order_transformer
+                target = algorithms.unique1d(ax._values)
+                indexer, _ = result.index.get_indexer_non_unique(target)
+                result = result.take(indexer, axis=self.axis)
+            else:
+                result = result.reindex(ax, axis=self.axis, copy=False)
+
+        else:
+            result = concat(values, axis=self.axis)
+
+        if self.obj.ndim == 1:
+            name = self.obj.name
+        elif is_hashable(self._selection):
+            name = self._selection
+        else:
+            name = None
+
+        if isinstance(result, Series) and name is not None:
+            result.name = name
+
+        return result
+
+    @final
+    def _set_result_index_ordered(
+        self, result: OutputFrameOrSeries
+    ) -> OutputFrameOrSeries:
+        # set the result index on the passed values object and
+        # return the new object, xref 8046
+
+        obj_axis = self.obj._get_axis(self.axis)
+
+        if self._grouper.is_monotonic and not self._grouper.has_dropped_na:
+            # shortcut if we have an already ordered grouper
+            result = result.set_axis(obj_axis, axis=self.axis, copy=False)
+            return result
+
+        # row order is scrambled => sort the rows by position in original index
+        original_positions = Index(self._grouper.result_ilocs())
+        result = result.set_axis(original_positions, axis=self.axis, copy=False)
+        result = result.sort_index(axis=self.axis)
+        if self._grouper.has_dropped_na:
+            # Add back in any missing rows due to dropna - index here is integral
+            # with values referring to the row of the input so can use RangeIndex
+            result = result.reindex(RangeIndex(len(obj_axis)), axis=self.axis)
+        result = result.set_axis(obj_axis, axis=self.axis, copy=False)
+
+        return result
+
+    @final
+    def _insert_inaxis_grouper(self, result: Series | DataFrame) -> DataFrame:
+        if isinstance(result, Series):
+            result = result.to_frame()
+
+        # zip in reverse so we can always insert at loc 0
+        columns = result.columns
+        for name, lev, in_axis in zip(
+            reversed(self._grouper.names),
+            reversed(self._grouper.get_group_levels()),
+            reversed([grp.in_axis for grp in self._grouper.groupings]),
+        ):
+            # GH #28549
+            # When using .apply(-), name will be in columns already
+            if name not in columns:
+                if in_axis:
+                    result.insert(0, name, lev)
+                else:
+                    msg = (
+                        "A grouping was used that is not in the columns of the "
+                        "DataFrame and so was excluded from the result. This grouping "
+                        "will be included in a future version of pandas. Add the "
+                        "grouping as a column of the DataFrame to silence this warning."
+                    )
+                    warnings.warn(
+                        message=msg,
+                        category=FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+
+        return result
+
+    @final
+    def _maybe_transpose_result(self, result: NDFrameT) -> NDFrameT:
+        if self.axis == 1:
+            # Only relevant for DataFrameGroupBy, no-op for SeriesGroupBy
+            result = result.T
+            if result.index.equals(self.obj.index):
+                # Retain e.g. DatetimeIndex/TimedeltaIndex freq
+                # e.g. test_groupby_crash_on_nunique
+                result.index = self.obj.index.copy()
+        return result
+
+    @final
+    def _wrap_aggregated_output(
+        self,
+        result: Series | DataFrame,
+        qs: npt.NDArray[np.float64] | None = None,
+    ):
+        """
+        Wraps the output of GroupBy aggregations into the expected result.
+
+        Parameters
+        ----------
+        result : Series, DataFrame
+
+        Returns
+        -------
+        Series or DataFrame
+        """
+        # ATM we do not get here for SeriesGroupBy; when we do, we will
+        #  need to require that result.name already match self.obj.name
+
+        if not self.as_index:
+            # `not self.as_index` is only relevant for DataFrameGroupBy,
+            #   enforced in __init__
+            result = self._insert_inaxis_grouper(result)
+            result = result._consolidate()
+            index = Index(range(self._grouper.ngroups))
+
+        else:
+            index = self._grouper.result_index
+
+        if qs is not None:
+            # We get here with len(qs) != 1 and not self.as_index
+            #  in test_pass_args_kwargs
+            index = _insert_quantile_level(index, qs)
+
+        result.index = index
+
+        # error: Argument 1 to "_maybe_transpose_result" of "GroupBy" has
+        # incompatible type "Union[Series, DataFrame]"; expected "NDFrameT"
+        res = self._maybe_transpose_result(result)  # type: ignore[arg-type]
+        return self._reindex_output(res, qs=qs)
+
+    def _wrap_applied_output(
+        self,
+        data,
+        values: list,
+        not_indexed_same: bool = False,
+        is_transform: bool = False,
+    ):
+        raise AbstractMethodError(self)
+
+    # -----------------------------------------------------------------
+    # numba
+
+    @final
+    def _numba_prep(self, data: DataFrame):
+        ids, _, ngroups = self._grouper.group_info
+        sorted_index = self._grouper._sort_idx
+        sorted_ids = self._grouper._sorted_ids
+
+        sorted_data = data.take(sorted_index, axis=self.axis).to_numpy()
+        # GH 46867
+        index_data = data.index
+        if isinstance(index_data, MultiIndex):
+            if len(self._grouper.groupings) > 1:
+                raise NotImplementedError(
+                    "Grouping with more than 1 grouping labels and "
+                    "a MultiIndex is not supported with engine='numba'"
+                )
+            group_key = self._grouper.groupings[0].name
+            index_data = index_data.get_level_values(group_key)
+        sorted_index_data = index_data.take(sorted_index).to_numpy()
+
+        starts, ends = lib.generate_slices(sorted_ids, ngroups)
+        return (
+            starts,
+            ends,
+            sorted_index_data,
+            sorted_data,
+        )
+
+    def _numba_agg_general(
+        self,
+        func: Callable,
+        dtype_mapping: dict[np.dtype, Any],
+        engine_kwargs: dict[str, bool] | None,
+        **aggregator_kwargs,
+    ):
+        """
+        Perform groupby with a standard numerical aggregation function (e.g. mean)
+        with Numba.
+        """
+        if not self.as_index:
+            raise NotImplementedError(
+                "as_index=False is not supported. Use .reset_index() instead."
+            )
+        if self.axis == 1:
+            raise NotImplementedError("axis=1 is not supported.")
+
+        data = self._obj_with_exclusions
+        df = data if data.ndim == 2 else data.to_frame()
+
+        aggregator = executor.generate_shared_aggregator(
+            func,
+            dtype_mapping,
+            True,  # is_grouped_kernel
+            **get_jit_arguments(engine_kwargs),
+        )
+        # Pass group ids to kernel directly if it can handle it
+        # (This is faster since it doesn't require a sort)
+        ids, _, _ = self._grouper.group_info
+        ngroups = self._grouper.ngroups
+
+        res_mgr = df._mgr.apply(
+            aggregator, labels=ids, ngroups=ngroups, **aggregator_kwargs
+        )
+        res_mgr.axes[1] = self._grouper.result_index
+        result = df._constructor_from_mgr(res_mgr, axes=res_mgr.axes)
+
+        if data.ndim == 1:
+            result = result.squeeze("columns")
+            result.name = data.name
+        else:
+            result.columns = data.columns
+        return result
+
+    @final
+    def _transform_with_numba(self, func, *args, engine_kwargs=None, **kwargs):
+        """
+        Perform groupby transform routine with the numba engine.
+
+        This routine mimics the data splitting routine of the DataSplitter class
+        to generate the indices of each group in the sorted data and then passes the
+        data and indices into a Numba jitted function.
+        """
+        data = self._obj_with_exclusions
+        df = data if data.ndim == 2 else data.to_frame()
+
+        starts, ends, sorted_index, sorted_data = self._numba_prep(df)
+        numba_.validate_udf(func)
+        numba_transform_func = numba_.generate_numba_transform_func(
+            func, **get_jit_arguments(engine_kwargs, kwargs)
+        )
+        result = numba_transform_func(
+            sorted_data,
+            sorted_index,
+            starts,
+            ends,
+            len(df.columns),
+            *args,
+        )
+        # result values needs to be resorted to their original positions since we
+        # evaluated the data sorted by group
+        result = result.take(np.argsort(sorted_index), axis=0)
+        index = data.index
+        if data.ndim == 1:
+            result_kwargs = {"name": data.name}
+            result = result.ravel()
+        else:
+            result_kwargs = {"columns": data.columns}
+        return data._constructor(result, index=index, **result_kwargs)
+
+    @final
+    def _aggregate_with_numba(self, func, *args, engine_kwargs=None, **kwargs):
+        """
+        Perform groupby aggregation routine with the numba engine.
+
+        This routine mimics the data splitting routine of the DataSplitter class
+        to generate the indices of each group in the sorted data and then passes the
+        data and indices into a Numba jitted function.
+        """
+        data = self._obj_with_exclusions
+        df = data if data.ndim == 2 else data.to_frame()
+
+        starts, ends, sorted_index, sorted_data = self._numba_prep(df)
+        numba_.validate_udf(func)
+        numba_agg_func = numba_.generate_numba_agg_func(
+            func, **get_jit_arguments(engine_kwargs, kwargs)
+        )
+        result = numba_agg_func(
+            sorted_data,
+            sorted_index,
+            starts,
+            ends,
+            len(df.columns),
+            *args,
+        )
+        index = self._grouper.result_index
+        if data.ndim == 1:
+            result_kwargs = {"name": data.name}
+            result = result.ravel()
+        else:
+            result_kwargs = {"columns": data.columns}
+        res = data._constructor(result, index=index, **result_kwargs)
+        if not self.as_index:
+            res = self._insert_inaxis_grouper(res)
+            res.index = default_index(len(res))
+        return res
+
+    # -----------------------------------------------------------------
+    # apply/agg/transform
+
+    @Appender(
+        _apply_docs["template"].format(
+            input="dataframe", examples=_apply_docs["dataframe_examples"]
+        )
+    )
+    def apply(self, func, *args, include_groups: bool = True, **kwargs) -> NDFrameT:
+        orig_func = func
+        func = com.is_builtin_func(func)
+        if orig_func != func:
+            alias = com._builtin_table_alias[orig_func]
+            warn_alias_replacement(self, orig_func, alias)
+
+        if isinstance(func, str):
+            if hasattr(self, func):
+                res = getattr(self, func)
+                if callable(res):
+                    return res(*args, **kwargs)
+                elif args or kwargs:
+                    raise ValueError(f"Cannot pass arguments to property {func}")
+                return res
+
+            else:
+                raise TypeError(f"apply func should be callable, not '{func}'")
+
+        elif args or kwargs:
+            if callable(func):
+
+                @wraps(func)
+                def f(g):
+                    return func(g, *args, **kwargs)
+
+            else:
+                raise ValueError(
+                    "func must be a callable if args or kwargs are supplied"
+                )
+        else:
+            f = func
+
+        if not include_groups:
+            return self._python_apply_general(f, self._obj_with_exclusions)
+
+        # ignore SettingWithCopy here in case the user mutates
+        with option_context("mode.chained_assignment", None):
+            try:
+                result = self._python_apply_general(f, self._selected_obj)
+                if (
+                    not isinstance(self.obj, Series)
+                    and self._selection is None
+                    and self._selected_obj.shape != self._obj_with_exclusions.shape
+                ):
+                    warnings.warn(
+                        message=_apply_groupings_depr.format(
+                            type(self).__name__, "apply"
+                        ),
+                        category=FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+            except TypeError:
+                # gh-20949
+                # try again, with .apply acting as a filtering
+                # operation, by excluding the grouping column
+                # This would normally not be triggered
+                # except if the udf is trying an operation that
+                # fails on *some* columns, e.g. a numeric operation
+                # on a string grouper column
+
+                return self._python_apply_general(f, self._obj_with_exclusions)
+
+        return result
+
+    @final
+    def _python_apply_general(
+        self,
+        f: Callable,
+        data: DataFrame | Series,
+        not_indexed_same: bool | None = None,
+        is_transform: bool = False,
+        is_agg: bool = False,
+    ) -> NDFrameT:
+        """
+        Apply function f in python space
+
+        Parameters
+        ----------
+        f : callable
+            Function to apply
+        data : Series or DataFrame
+            Data to apply f to
+        not_indexed_same: bool, optional
+            When specified, overrides the value of not_indexed_same. Apply behaves
+            differently when the result index is equal to the input index, but
+            this can be coincidental leading to value-dependent behavior.
+        is_transform : bool, default False
+            Indicator for whether the function is actually a transform
+            and should not have group keys prepended.
+        is_agg : bool, default False
+            Indicator for whether the function is an aggregation. When the
+            result is empty, we don't want to warn for this case.
+            See _GroupBy._python_agg_general.
+
+        Returns
+        -------
+        Series or DataFrame
+            data after applying f
+        """
+        values, mutated = self._grouper.apply_groupwise(f, data, self.axis)
+        if not_indexed_same is None:
+            not_indexed_same = mutated
+
+        return self._wrap_applied_output(
+            data,
+            values,
+            not_indexed_same,
+            is_transform,
+        )
+
+    @final
+    def _agg_general(
+        self,
+        numeric_only: bool = False,
+        min_count: int = -1,
+        *,
+        alias: str,
+        npfunc: Callable | None = None,
+        **kwargs,
+    ):
+        result = self._cython_agg_general(
+            how=alias,
+            alt=npfunc,
+            numeric_only=numeric_only,
+            min_count=min_count,
+            **kwargs,
+        )
+        return result.__finalize__(self.obj, method="groupby")
+
+    def _agg_py_fallback(
+        self, how: str, values: ArrayLike, ndim: int, alt: Callable
+    ) -> ArrayLike:
+        """
+        Fallback to pure-python aggregation if _cython_operation raises
+        NotImplementedError.
+        """
+        # We get here with a) EADtypes and b) object dtype
+        assert alt is not None
+
+        if values.ndim == 1:
+            # For DataFrameGroupBy we only get here with ExtensionArray
+            ser = Series(values, copy=False)
+        else:
+            # We only get here with values.dtype == object
+            df = DataFrame(values.T, dtype=values.dtype)
+            # bc we split object blocks in grouped_reduce, we have only 1 col
+            # otherwise we'd have to worry about block-splitting GH#39329
+            assert df.shape[1] == 1
+            # Avoid call to self.values that can occur in DataFrame
+            #  reductions; see GH#28949
+            ser = df.iloc[:, 0]
+
+        # We do not get here with UDFs, so we know that our dtype
+        #  should always be preserved by the implemented aggregations
+        # TODO: Is this exactly right; see WrappedCythonOp get_result_dtype?
+        try:
+            res_values = self._grouper.agg_series(ser, alt, preserve_dtype=True)
+        except Exception as err:
+            msg = f"agg function failed [how->{how},dtype->{ser.dtype}]"
+            # preserve the kind of exception that raised
+            raise type(err)(msg) from err
+
+        dtype = ser.dtype
+        if dtype == object:
+            res_values = res_values.astype(object, copy=False)
+        elif is_string_dtype(dtype):
+            # mypy doesn't infer dtype is an ExtensionDtype
+            string_array_cls = dtype.construct_array_type()  # type: ignore[union-attr]
+            res_values = string_array_cls._from_sequence(res_values, dtype=dtype)
+
+        # If we are DataFrameGroupBy and went through a SeriesGroupByPath
+        # then we need to reshape
+        # GH#32223 includes case with IntegerArray values, ndarray res_values
+        # test_groupby_duplicate_columns with object dtype values
+        return ensure_block_shape(res_values, ndim=ndim)
+
+    @final
+    def _cython_agg_general(
+        self,
+        how: str,
+        alt: Callable | None = None,
+        numeric_only: bool = False,
+        min_count: int = -1,
+        **kwargs,
+    ):
+        # Note: we never get here with how="ohlc" for DataFrameGroupBy;
+        #  that goes through SeriesGroupBy
+
+        data = self._get_data_to_aggregate(numeric_only=numeric_only, name=how)
+
+        def array_func(values: ArrayLike) -> ArrayLike:
+            try:
+                result = self._grouper._cython_operation(
+                    "aggregate",
+                    values,
+                    how,
+                    axis=data.ndim - 1,
+                    min_count=min_count,
+                    **kwargs,
+                )
+            except NotImplementedError:
+                # generally if we have numeric_only=False
+                # and non-applicable functions
+                # try to python agg
+                # TODO: shouldn't min_count matter?
+                # TODO: avoid special casing SparseArray here
+                if how in ["any", "all"] and isinstance(values, SparseArray):
+                    pass
+                elif alt is None or how in ["any", "all", "std", "sem"]:
+                    raise  # TODO: re-raise as TypeError?  should not be reached
+            else:
+                return result
+
+            assert alt is not None
+            result = self._agg_py_fallback(how, values, ndim=data.ndim, alt=alt)
+            return result
+
+        new_mgr = data.grouped_reduce(array_func)
+        res = self._wrap_agged_manager(new_mgr)
+        if how in ["idxmin", "idxmax"]:
+            res = self._wrap_idxmax_idxmin(res)
+        out = self._wrap_aggregated_output(res)
+        if self.axis == 1:
+            out = out.infer_objects(copy=False)
+        return out
+
+    def _cython_transform(
+        self, how: str, numeric_only: bool = False, axis: AxisInt = 0, **kwargs
+    ):
+        raise AbstractMethodError(self)
+
+    @final
+    def _transform(self, func, *args, engine=None, engine_kwargs=None, **kwargs):
+        # optimized transforms
+        orig_func = func
+        func = com.get_cython_func(func) or func
+        if orig_func != func:
+            warn_alias_replacement(self, orig_func, func)
+
+        if not isinstance(func, str):
+            return self._transform_general(func, engine, engine_kwargs, *args, **kwargs)
+
+        elif func not in base.transform_kernel_allowlist:
+            msg = f"'{func}' is not a valid function name for transform(name)"
+            raise ValueError(msg)
+        elif func in base.cythonized_kernels or func in base.transformation_kernels:
+            # cythonized transform or canned "agg+broadcast"
+            if engine is not None:
+                kwargs["engine"] = engine
+                kwargs["engine_kwargs"] = engine_kwargs
+            return getattr(self, func)(*args, **kwargs)
+
+        else:
+            # i.e. func in base.reduction_kernels
+
+            # GH#30918 Use _transform_fast only when we know func is an aggregation
+            # If func is a reduction, we need to broadcast the
+            # result to the whole group. Compute func result
+            # and deal with possible broadcasting below.
+            with com.temp_setattr(self, "as_index", True):
+                # GH#49834 - result needs groups in the index for
+                # _wrap_transform_fast_result
+                if func in ["idxmin", "idxmax"]:
+                    func = cast(Literal["idxmin", "idxmax"], func)
+                    result = self._idxmax_idxmin(func, True, *args, **kwargs)
+                else:
+                    if engine is not None:
+                        kwargs["engine"] = engine
+                        kwargs["engine_kwargs"] = engine_kwargs
+                    result = getattr(self, func)(*args, **kwargs)
+
+            return self._wrap_transform_fast_result(result)
+
+    @final
+    def _wrap_transform_fast_result(self, result: NDFrameT) -> NDFrameT:
+        """
+        Fast transform path for aggregations.
+        """
+        obj = self._obj_with_exclusions
+
+        # for each col, reshape to size of original frame by take operation
+        ids, _, _ = self._grouper.group_info
+        result = result.reindex(self._grouper.result_index, axis=self.axis, copy=False)
+
+        if self.obj.ndim == 1:
+            # i.e. SeriesGroupBy
+            out = algorithms.take_nd(result._values, ids)
+            output = obj._constructor(out, index=obj.index, name=obj.name)
+        else:
+            # `.size()` gives Series output on DataFrame input, need axis 0
+            axis = 0 if result.ndim == 1 else self.axis
+            # GH#46209
+            # Don't convert indices: negative indices need to give rise
+            # to null values in the result
+            new_ax = result.axes[axis].take(ids)
+            output = result._reindex_with_indexers(
+                {axis: (new_ax, ids)}, allow_dups=True, copy=False
+            )
+            output = output.set_axis(obj._get_axis(self.axis), axis=axis)
+        return output
+
+    # -----------------------------------------------------------------
+    # Utilities
+
+    @final
+    def _apply_filter(self, indices, dropna):
+        if len(indices) == 0:
+            indices = np.array([], dtype="int64")
+        else:
+            indices = np.sort(np.concatenate(indices))
+        if dropna:
+            filtered = self._selected_obj.take(indices, axis=self.axis)
+        else:
+            mask = np.empty(len(self._selected_obj.index), dtype=bool)
+            mask.fill(False)
+            mask[indices.astype(int)] = True
+            # mask fails to broadcast when passed to where; broadcast manually.
+            mask = np.tile(mask, list(self._selected_obj.shape[1:]) + [1]).T
+            filtered = self._selected_obj.where(mask)  # Fill with NaNs.
+        return filtered
+
+    @final
+    def _cumcount_array(self, ascending: bool = True) -> np.ndarray:
+        """
+        Parameters
+        ----------
+        ascending : bool, default True
+            If False, number in reverse, from length of group - 1 to 0.
+
+        Notes
+        -----
+        this is currently implementing sort=False
+        (though the default is sort=True) for groupby in general
+        """
+        ids, _, ngroups = self._grouper.group_info
+        sorter = get_group_index_sorter(ids, ngroups)
+        ids, count = ids[sorter], len(ids)
+
+        if count == 0:
+            return np.empty(0, dtype=np.int64)
+
+        run = np.r_[True, ids[:-1] != ids[1:]]
+        rep = np.diff(np.r_[np.nonzero(run)[0], count])
+        out = (~run).cumsum()
+
+        if ascending:
+            out -= np.repeat(out[run], rep)
+        else:
+            out = np.repeat(out[np.r_[run[1:], True]], rep) - out
+
+        if self._grouper.has_dropped_na:
+            out = np.where(ids == -1, np.nan, out.astype(np.float64, copy=False))
+        else:
+            out = out.astype(np.int64, copy=False)
+
+        rev = np.empty(count, dtype=np.intp)
+        rev[sorter] = np.arange(count, dtype=np.intp)
+        return out[rev]
+
+    # -----------------------------------------------------------------
+
+    @final
+    @property
+    def _obj_1d_constructor(self) -> Callable:
+        # GH28330 preserve subclassed Series/DataFrames
+        if isinstance(self.obj, DataFrame):
+            return self.obj._constructor_sliced
+        assert isinstance(self.obj, Series)
+        return self.obj._constructor
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def any(self, skipna: bool = True) -> NDFrameT:
+        """
+        Return True if any value in the group is truthful, else False.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Flag to ignore nan values during truth testing.
+
+        Returns
+        -------
+        Series or DataFrame
+            DataFrame or Series of boolean values, where a value is True if any element
+            is True within its respective group, False otherwise.
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 0], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    0
+        dtype: int64
+        >>> ser.groupby(level=0).any()
+        a     True
+        b    False
+        dtype: bool
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 0, 3], [1, 0, 6], [7, 1, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["ostrich", "penguin", "parrot"])
+        >>> df
+                 a  b  c
+        ostrich  1  0  3
+        penguin  1  0  6
+        parrot   7  1  9
+        >>> df.groupby(by=["a"]).any()
+               b      c
+        a
+        1  False   True
+        7   True   True
+        """
+        return self._cython_agg_general(
+            "any",
+            alt=lambda x: Series(x, copy=False).any(skipna=skipna),
+            skipna=skipna,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def all(self, skipna: bool = True) -> NDFrameT:
+        """
+        Return True if all values in the group are truthful, else False.
+
+        Parameters
+        ----------
+        skipna : bool, default True
+            Flag to ignore nan values during truth testing.
+
+        Returns
+        -------
+        Series or DataFrame
+            DataFrame or Series of boolean values, where a value is True if all elements
+            are True within its respective group, False otherwise.
+        %(see_also)s
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 0], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    0
+        dtype: int64
+        >>> ser.groupby(level=0).all()
+        a     True
+        b    False
+        dtype: bool
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 0, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["ostrich", "penguin", "parrot"])
+        >>> df
+                 a  b  c
+        ostrich  1  0  3
+        penguin  1  5  6
+        parrot   7  8  9
+        >>> df.groupby(by=["a"]).all()
+               b      c
+        a
+        1  False   True
+        7   True   True
+        """
+        return self._cython_agg_general(
+            "all",
+            alt=lambda x: Series(x, copy=False).all(skipna=skipna),
+            skipna=skipna,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def count(self) -> NDFrameT:
+        """
+        Compute count of group, excluding missing values.
+
+        Returns
+        -------
+        Series or DataFrame
+            Count of values within each group.
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, np.nan], index=lst)
+        >>> ser
+        a    1.0
+        a    2.0
+        b    NaN
+        dtype: float64
+        >>> ser.groupby(level=0).count()
+        a    2
+        b    0
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, np.nan, 3], [1, np.nan, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["cow", "horse", "bull"])
+        >>> df
+                a	  b	c
+        cow     1	NaN	3
+        horse	1	NaN	6
+        bull	7	8.0	9
+        >>> df.groupby("a").count()
+            b   c
+        a
+        1   0   2
+        7   1   1
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').count()
+        2023-01-01    2
+        2023-02-01    2
+        Freq: MS, dtype: int64
+        """
+        data = self._get_data_to_aggregate()
+        ids, _, ngroups = self._grouper.group_info
+        mask = ids != -1
+
+        is_series = data.ndim == 1
+
+        def hfunc(bvalues: ArrayLike) -> ArrayLike:
+            # TODO(EA2D): reshape would not be necessary with 2D EAs
+            if bvalues.ndim == 1:
+                # EA
+                masked = mask & ~isna(bvalues).reshape(1, -1)
+            else:
+                masked = mask & ~isna(bvalues)
+
+            counted = lib.count_level_2d(masked, labels=ids, max_bin=ngroups)
+            if isinstance(bvalues, BaseMaskedArray):
+                return IntegerArray(
+                    counted[0], mask=np.zeros(counted.shape[1], dtype=np.bool_)
+                )
+            elif isinstance(bvalues, ArrowExtensionArray) and not isinstance(
+                bvalues.dtype, StringDtype
+            ):
+                dtype = pandas_dtype("int64[pyarrow]")
+                return type(bvalues)._from_sequence(counted[0], dtype=dtype)
+            if is_series:
+                assert counted.ndim == 2
+                assert counted.shape[0] == 1
+                return counted[0]
+            return counted
+
+        new_mgr = data.grouped_reduce(hfunc)
+        new_obj = self._wrap_agged_manager(new_mgr)
+
+        # If we are grouping on categoricals we want unobserved categories to
+        # return zero, rather than the default of NaN which the reindexing in
+        # _wrap_aggregated_output() returns. GH 35028
+        # e.g. test_dataframe_groupby_on_2_categoricals_when_observed_is_false
+        with com.temp_setattr(self, "observed", True):
+            result = self._wrap_aggregated_output(new_obj)
+
+        return self._reindex_output(result, fill_value=0)
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def mean(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        """
+        Compute mean of groups, excluding missing values.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only no longer accepts ``None`` and defaults to ``False``.
+
+        engine : str, default None
+            * ``'cython'`` : Runs the operation through C-extensions from cython.
+            * ``'numba'`` : Runs the operation through JIT compiled code from numba.
+            * ``None`` : Defaults to ``'cython'`` or globally setting
+              ``compute.use_numba``
+
+            .. versionadded:: 1.4.0
+
+        engine_kwargs : dict, default None
+            * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+            * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+              and ``parallel`` dictionary keys. The values must either be ``True`` or
+              ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+              ``{{'nopython': True, 'nogil': False, 'parallel': False}}``
+
+            .. versionadded:: 1.4.0
+
+        Returns
+        -------
+        pandas.Series or pandas.DataFrame
+        %(see_also)s
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 1, 2, 1, 2],
+        ...                    'B': [np.nan, 2, 3, 4, 5],
+        ...                    'C': [1, 2, 1, 1, 2]}, columns=['A', 'B', 'C'])
+
+        Groupby one column and return the mean of the remaining columns in
+        each group.
+
+        >>> df.groupby('A').mean()
+             B         C
+        A
+        1  3.0  1.333333
+        2  4.0  1.500000
+
+        Groupby two columns and return the mean of the remaining column.
+
+        >>> df.groupby(['A', 'B']).mean()
+                 C
+        A B
+        1 2.0  2.0
+          4.0  1.0
+        2 3.0  1.0
+          5.0  2.0
+
+        Groupby one column and return the mean of only particular column in
+        the group.
+
+        >>> df.groupby('A')['B'].mean()
+        A
+        1    3.0
+        2    4.0
+        Name: B, dtype: float64
+        """
+
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_mean
+
+            return self._numba_agg_general(
+                grouped_mean,
+                executor.float_dtype_mapping,
+                engine_kwargs,
+                min_periods=0,
+            )
+        else:
+            result = self._cython_agg_general(
+                "mean",
+                alt=lambda x: Series(x, copy=False).mean(numeric_only=numeric_only),
+                numeric_only=numeric_only,
+            )
+            return result.__finalize__(self.obj, method="groupby")
+
+    @final
+    def median(self, numeric_only: bool = False) -> NDFrameT:
+        """
+        Compute median of groups, excluding missing values.
+
+        For multiple groupings, the result index will be a MultiIndex
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only no longer accepts ``None`` and defaults to False.
+
+        Returns
+        -------
+        Series or DataFrame
+            Median of values within each group.
+
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([7, 2, 8, 4, 3, 3], index=lst)
+        >>> ser
+        a     7
+        a     2
+        a     8
+        b     4
+        b     3
+        b     3
+        dtype: int64
+        >>> ser.groupby(level=0).median()
+        a    7.0
+        b    3.0
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = {'a': [1, 3, 5, 7, 7, 8, 3], 'b': [1, 4, 8, 4, 4, 2, 1]}
+        >>> df = pd.DataFrame(data, index=['dog', 'dog', 'dog',
+        ...                   'mouse', 'mouse', 'mouse', 'mouse'])
+        >>> df
+                 a  b
+          dog    1  1
+          dog    3  4
+          dog    5  8
+        mouse    7  4
+        mouse    7  4
+        mouse    8  2
+        mouse    3  1
+        >>> df.groupby(level=0).median()
+                 a    b
+        dog    3.0  4.0
+        mouse  7.0  3.0
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3, 3, 4, 5],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').median()
+        2023-01-01    2.0
+        2023-02-01    4.0
+        Freq: MS, dtype: float64
+        """
+        result = self._cython_agg_general(
+            "median",
+            alt=lambda x: Series(x, copy=False).median(numeric_only=numeric_only),
+            numeric_only=numeric_only,
+        )
+        return result.__finalize__(self.obj, method="groupby")
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def std(
+        self,
+        ddof: int = 1,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        numeric_only: bool = False,
+    ):
+        """
+        Compute standard deviation of groups, excluding missing values.
+
+        For multiple groupings, the result index will be a MultiIndex.
+
+        Parameters
+        ----------
+        ddof : int, default 1
+            Degrees of freedom.
+
+        engine : str, default None
+            * ``'cython'`` : Runs the operation through C-extensions from cython.
+            * ``'numba'`` : Runs the operation through JIT compiled code from numba.
+            * ``None`` : Defaults to ``'cython'`` or globally setting
+              ``compute.use_numba``
+
+            .. versionadded:: 1.4.0
+
+        engine_kwargs : dict, default None
+            * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+            * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+              and ``parallel`` dictionary keys. The values must either be ``True`` or
+              ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+              ``{{'nopython': True, 'nogil': False, 'parallel': False}}``
+
+            .. versionadded:: 1.4.0
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        Series or DataFrame
+            Standard deviation of values within each group.
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([7, 2, 8, 4, 3, 3], index=lst)
+        >>> ser
+        a     7
+        a     2
+        a     8
+        b     4
+        b     3
+        b     3
+        dtype: int64
+        >>> ser.groupby(level=0).std()
+        a    3.21455
+        b    0.57735
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = {'a': [1, 3, 5, 7, 7, 8, 3], 'b': [1, 4, 8, 4, 4, 2, 1]}
+        >>> df = pd.DataFrame(data, index=['dog', 'dog', 'dog',
+        ...                   'mouse', 'mouse', 'mouse', 'mouse'])
+        >>> df
+                 a  b
+          dog    1  1
+          dog    3  4
+          dog    5  8
+        mouse    7  4
+        mouse    7  4
+        mouse    8  2
+        mouse    3  1
+        >>> df.groupby(level=0).std()
+                      a         b
+        dog    2.000000  3.511885
+        mouse  2.217356  1.500000
+        """
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_var
+
+            return np.sqrt(
+                self._numba_agg_general(
+                    grouped_var,
+                    executor.float_dtype_mapping,
+                    engine_kwargs,
+                    min_periods=0,
+                    ddof=ddof,
+                )
+            )
+        else:
+            return self._cython_agg_general(
+                "std",
+                alt=lambda x: Series(x, copy=False).std(ddof=ddof),
+                numeric_only=numeric_only,
+                ddof=ddof,
+            )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def var(
+        self,
+        ddof: int = 1,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        numeric_only: bool = False,
+    ):
+        """
+        Compute variance of groups, excluding missing values.
+
+        For multiple groupings, the result index will be a MultiIndex.
+
+        Parameters
+        ----------
+        ddof : int, default 1
+            Degrees of freedom.
+
+        engine : str, default None
+            * ``'cython'`` : Runs the operation through C-extensions from cython.
+            * ``'numba'`` : Runs the operation through JIT compiled code from numba.
+            * ``None`` : Defaults to ``'cython'`` or globally setting
+              ``compute.use_numba``
+
+            .. versionadded:: 1.4.0
+
+        engine_kwargs : dict, default None
+            * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+            * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+              and ``parallel`` dictionary keys. The values must either be ``True`` or
+              ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+              ``{{'nopython': True, 'nogil': False, 'parallel': False}}``
+
+            .. versionadded:: 1.4.0
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        Series or DataFrame
+            Variance of values within each group.
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([7, 2, 8, 4, 3, 3], index=lst)
+        >>> ser
+        a     7
+        a     2
+        a     8
+        b     4
+        b     3
+        b     3
+        dtype: int64
+        >>> ser.groupby(level=0).var()
+        a    10.333333
+        b     0.333333
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = {'a': [1, 3, 5, 7, 7, 8, 3], 'b': [1, 4, 8, 4, 4, 2, 1]}
+        >>> df = pd.DataFrame(data, index=['dog', 'dog', 'dog',
+        ...                   'mouse', 'mouse', 'mouse', 'mouse'])
+        >>> df
+                 a  b
+          dog    1  1
+          dog    3  4
+          dog    5  8
+        mouse    7  4
+        mouse    7  4
+        mouse    8  2
+        mouse    3  1
+        >>> df.groupby(level=0).var()
+                      a          b
+        dog    4.000000  12.333333
+        mouse  4.916667   2.250000
+        """
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_var
+
+            return self._numba_agg_general(
+                grouped_var,
+                executor.float_dtype_mapping,
+                engine_kwargs,
+                min_periods=0,
+                ddof=ddof,
+            )
+        else:
+            return self._cython_agg_general(
+                "var",
+                alt=lambda x: Series(x, copy=False).var(ddof=ddof),
+                numeric_only=numeric_only,
+                ddof=ddof,
+            )
+
+    @final
+    def _value_counts(
+        self,
+        subset: Sequence[Hashable] | None = None,
+        normalize: bool = False,
+        sort: bool = True,
+        ascending: bool = False,
+        dropna: bool = True,
+    ) -> DataFrame | Series:
+        """
+        Shared implementation of value_counts for SeriesGroupBy and DataFrameGroupBy.
+
+        SeriesGroupBy additionally supports a bins argument. See the docstring of
+        DataFrameGroupBy.value_counts for a description of arguments.
+        """
+        if self.axis == 1:
+            raise NotImplementedError(
+                "DataFrameGroupBy.value_counts only handles axis=0"
+            )
+        name = "proportion" if normalize else "count"
+
+        df = self.obj
+        obj = self._obj_with_exclusions
+
+        in_axis_names = {
+            grouping.name for grouping in self._grouper.groupings if grouping.in_axis
+        }
+        if isinstance(obj, Series):
+            _name = obj.name
+            keys = [] if _name in in_axis_names else [obj]
+        else:
+            unique_cols = set(obj.columns)
+            if subset is not None:
+                subsetted = set(subset)
+                clashing = subsetted & set(in_axis_names)
+                if clashing:
+                    raise ValueError(
+                        f"Keys {clashing} in subset cannot be in "
+                        "the groupby column keys."
+                    )
+                doesnt_exist = subsetted - unique_cols
+                if doesnt_exist:
+                    raise ValueError(
+                        f"Keys {doesnt_exist} in subset do not "
+                        f"exist in the DataFrame."
+                    )
+            else:
+                subsetted = unique_cols
+
+            keys = [
+                # Can't use .values because the column label needs to be preserved
+                obj.iloc[:, idx]
+                for idx, _name in enumerate(obj.columns)
+                if _name not in in_axis_names and _name in subsetted
+            ]
+
+        groupings = list(self._grouper.groupings)
+        for key in keys:
+            grouper, _, _ = get_grouper(
+                df,
+                key=key,
+                axis=self.axis,
+                sort=self.sort,
+                observed=False,
+                dropna=dropna,
+            )
+            groupings += list(grouper.groupings)
+
+        # Take the size of the overall columns
+        gb = df.groupby(
+            groupings,
+            sort=self.sort,
+            observed=self.observed,
+            dropna=self.dropna,
+        )
+        result_series = cast(Series, gb.size())
+        result_series.name = name
+
+        # GH-46357 Include non-observed categories
+        # of non-grouping columns regardless of `observed`
+        if any(
+            isinstance(grouping.grouping_vector, (Categorical, CategoricalIndex))
+            and not grouping._observed
+            for grouping in groupings
+        ):
+            levels_list = [ping._result_index for ping in groupings]
+            multi_index = MultiIndex.from_product(
+                levels_list, names=[ping.name for ping in groupings]
+            )
+            result_series = result_series.reindex(multi_index, fill_value=0)
+
+        if sort:
+            # Sort by the values
+            result_series = result_series.sort_values(
+                ascending=ascending, kind="stable"
+            )
+        if self.sort:
+            # Sort by the groupings
+            names = result_series.index.names
+            # GH#55951 - Temporarily replace names in case they are integers
+            result_series.index.names = range(len(names))
+            index_level = list(range(len(self._grouper.groupings)))
+            result_series = result_series.sort_index(
+                level=index_level, sort_remaining=False
+            )
+            result_series.index.names = names
+
+        if normalize:
+            # Normalize the results by dividing by the original group sizes.
+            # We are guaranteed to have the first N levels be the
+            # user-requested grouping.
+            levels = list(
+                range(len(self._grouper.groupings), result_series.index.nlevels)
+            )
+            indexed_group_size = result_series.groupby(
+                result_series.index.droplevel(levels),
+                sort=self.sort,
+                dropna=self.dropna,
+                # GH#43999 - deprecation of observed=False
+                observed=False,
+            ).transform("sum")
+            result_series /= indexed_group_size
+
+            # Handle groups of non-observed categories
+            result_series = result_series.fillna(0.0)
+
+        result: Series | DataFrame
+        if self.as_index:
+            result = result_series
+        else:
+            # Convert to frame
+            index = result_series.index
+            columns = com.fill_missing_names(index.names)
+            if name in columns:
+                raise ValueError(f"Column label '{name}' is duplicate of result column")
+            result_series.name = name
+            result_series.index = index.set_names(range(len(columns)))
+            result_frame = result_series.reset_index()
+            orig_dtype = self._grouper.groupings[0].obj.columns.dtype  # type: ignore[union-attr]
+            cols = Index(columns, dtype=orig_dtype).insert(len(columns), name)
+            result_frame.columns = cols
+            result = result_frame
+        return result.__finalize__(self.obj, method="value_counts")
+
+    @final
+    def sem(self, ddof: int = 1, numeric_only: bool = False) -> NDFrameT:
+        """
+        Compute standard error of the mean of groups, excluding missing values.
+
+        For multiple groupings, the result index will be a MultiIndex.
+
+        Parameters
+        ----------
+        ddof : int, default 1
+            Degrees of freedom.
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        Series or DataFrame
+            Standard error of the mean of values within each group.
+
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([5, 10, 8, 14], index=lst)
+        >>> ser
+        a     5
+        a    10
+        b     8
+        b    14
+        dtype: int64
+        >>> ser.groupby(level=0).sem()
+        a    2.5
+        b    3.0
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 12, 11], [1, 15, 2], [2, 5, 8], [2, 6, 12]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tuna", "salmon", "catfish", "goldfish"])
+        >>> df
+                   a   b   c
+            tuna   1  12  11
+          salmon   1  15   2
+         catfish   2   5   8
+        goldfish   2   6  12
+        >>> df.groupby("a").sem()
+              b  c
+        a
+        1    1.5  4.5
+        2    0.5  2.0
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 3, 2, 4, 3, 8],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').sem()
+        2023-01-01    0.577350
+        2023-02-01    1.527525
+        Freq: MS, dtype: float64
+        """
+        if numeric_only and self.obj.ndim == 1 and not is_numeric_dtype(self.obj.dtype):
+            raise TypeError(
+                f"{type(self).__name__}.sem called with "
+                f"numeric_only={numeric_only} and dtype {self.obj.dtype}"
+            )
+        return self._cython_agg_general(
+            "sem",
+            alt=lambda x: Series(x, copy=False).sem(ddof=ddof),
+            numeric_only=numeric_only,
+            ddof=ddof,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def size(self) -> DataFrame | Series:
+        """
+        Compute group sizes.
+
+        Returns
+        -------
+        DataFrame or Series
+            Number of rows in each group as a Series if as_index is True
+            or a DataFrame if as_index is False.
+        %(see_also)s
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([1, 2, 3], index=lst)
+        >>> ser
+        a     1
+        a     2
+        b     3
+        dtype: int64
+        >>> ser.groupby(level=0).size()
+        a    2
+        b    1
+        dtype: int64
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [7, 8, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["owl", "toucan", "eagle"])
+        >>> df
+                a  b  c
+        owl     1  2  3
+        toucan  1  5  6
+        eagle   7  8  9
+        >>> df.groupby("a").size()
+        a
+        1    2
+        7    1
+        dtype: int64
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 2, 3], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        dtype: int64
+        >>> ser.resample('MS').size()
+        2023-01-01    2
+        2023-02-01    1
+        Freq: MS, dtype: int64
+        """
+        result = self._grouper.size()
+        dtype_backend: None | Literal["pyarrow", "numpy_nullable"] = None
+        if isinstance(self.obj, Series):
+            if isinstance(self.obj.array, ArrowExtensionArray):
+                if isinstance(self.obj.array, ArrowStringArrayNumpySemantics):
+                    dtype_backend = None
+                elif isinstance(self.obj.array, ArrowStringArray):
+                    dtype_backend = "numpy_nullable"
+                else:
+                    dtype_backend = "pyarrow"
+            elif isinstance(self.obj.array, BaseMaskedArray):
+                dtype_backend = "numpy_nullable"
+        # TODO: For DataFrames what if columns are mixed arrow/numpy/masked?
+
+        # GH28330 preserve subclassed Series/DataFrames through calls
+        if isinstance(self.obj, Series):
+            result = self._obj_1d_constructor(result, name=self.obj.name)
+        else:
+            result = self._obj_1d_constructor(result)
+
+        if dtype_backend is not None:
+            result = result.convert_dtypes(
+                infer_objects=False,
+                convert_string=False,
+                convert_boolean=False,
+                convert_floating=False,
+                dtype_backend=dtype_backend,
+            )
+
+        with com.temp_setattr(self, "as_index", True):
+            # size already has the desired behavior in GH#49519, but this makes the
+            # as_index=False path of _reindex_output fail on categorical groupers.
+            result = self._reindex_output(result, fill_value=0)
+        if not self.as_index:
+            # error: Incompatible types in assignment (expression has
+            # type "DataFrame", variable has type "Series")
+            result = result.rename("size").reset_index()  # type: ignore[assignment]
+        return result
+
+    @final
+    @doc(
+        _groupby_agg_method_engine_template,
+        fname="sum",
+        no=False,
+        mc=0,
+        e=None,
+        ek=None,
+        example=dedent(
+            """\
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).sum()
+        a    3
+        b    7
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tiger", "leopard", "cheetah", "lion"])
+        >>> df
+                  a  b  c
+          tiger   1  8  2
+        leopard   1  2  5
+        cheetah   2  5  8
+           lion   2  6  9
+        >>> df.groupby("a").sum()
+             b   c
+        a
+        1   10   7
+        2   11  17"""
+        ),
+    )
+    def sum(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_sum
+
+            return self._numba_agg_general(
+                grouped_sum,
+                executor.default_dtype_mapping,
+                engine_kwargs,
+                min_periods=min_count,
+            )
+        else:
+            # If we are grouping on categoricals we want unobserved categories to
+            # return zero, rather than the default of NaN which the reindexing in
+            # _agg_general() returns. GH #31422
+            with com.temp_setattr(self, "observed", True):
+                result = self._agg_general(
+                    numeric_only=numeric_only,
+                    min_count=min_count,
+                    alias="sum",
+                    npfunc=np.sum,
+                )
+
+            return self._reindex_output(result, fill_value=0, method="sum")
+
+    @final
+    @doc(
+        _groupby_agg_method_template,
+        fname="prod",
+        no=False,
+        mc=0,
+        example=dedent(
+            """\
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).prod()
+        a    2
+        b   12
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tiger", "leopard", "cheetah", "lion"])
+        >>> df
+                  a  b  c
+          tiger   1  8  2
+        leopard   1  2  5
+        cheetah   2  5  8
+           lion   2  6  9
+        >>> df.groupby("a").prod()
+             b    c
+        a
+        1   16   10
+        2   30   72"""
+        ),
+    )
+    def prod(self, numeric_only: bool = False, min_count: int = 0) -> NDFrameT:
+        return self._agg_general(
+            numeric_only=numeric_only, min_count=min_count, alias="prod", npfunc=np.prod
+        )
+
+    @final
+    @doc(
+        _groupby_agg_method_engine_template,
+        fname="min",
+        no=False,
+        mc=-1,
+        e=None,
+        ek=None,
+        example=dedent(
+            """\
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).min()
+        a    1
+        b    3
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tiger", "leopard", "cheetah", "lion"])
+        >>> df
+                  a  b  c
+          tiger   1  8  2
+        leopard   1  2  5
+        cheetah   2  5  8
+           lion   2  6  9
+        >>> df.groupby("a").min()
+            b  c
+        a
+        1   2  2
+        2   5  8"""
+        ),
+    )
+    def min(
+        self,
+        numeric_only: bool = False,
+        min_count: int = -1,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_min_max
+
+            return self._numba_agg_general(
+                grouped_min_max,
+                executor.identity_dtype_mapping,
+                engine_kwargs,
+                min_periods=min_count,
+                is_max=False,
+            )
+        else:
+            return self._agg_general(
+                numeric_only=numeric_only,
+                min_count=min_count,
+                alias="min",
+                npfunc=np.min,
+            )
+
+    @final
+    @doc(
+        _groupby_agg_method_engine_template,
+        fname="max",
+        no=False,
+        mc=-1,
+        e=None,
+        ek=None,
+        example=dedent(
+            """\
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).max()
+        a    2
+        b    4
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tiger", "leopard", "cheetah", "lion"])
+        >>> df
+                  a  b  c
+          tiger   1  8  2
+        leopard   1  2  5
+        cheetah   2  5  8
+           lion   2  6  9
+        >>> df.groupby("a").max()
+            b  c
+        a
+        1   8  5
+        2   6  9"""
+        ),
+    )
+    def max(
+        self,
+        numeric_only: bool = False,
+        min_count: int = -1,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            from pandas.core._numba.kernels import grouped_min_max
+
+            return self._numba_agg_general(
+                grouped_min_max,
+                executor.identity_dtype_mapping,
+                engine_kwargs,
+                min_periods=min_count,
+                is_max=True,
+            )
+        else:
+            return self._agg_general(
+                numeric_only=numeric_only,
+                min_count=min_count,
+                alias="max",
+                npfunc=np.max,
+            )
+
+    @final
+    def first(
+        self, numeric_only: bool = False, min_count: int = -1, skipna: bool = True
+    ) -> NDFrameT:
+        """
+        Compute the first entry of each column within each group.
+
+        Defaults to skipping NA elements.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+        min_count : int, default -1
+            The required number of valid values to perform the operation. If fewer
+            than ``min_count`` valid values are present the result will be NA.
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+
+            .. versionadded:: 2.2.1
+
+        Returns
+        -------
+        Series or DataFrame
+            First values within each group.
+
+        See Also
+        --------
+        DataFrame.groupby : Apply a function groupby to each row or column of a
+            DataFrame.
+        pandas.core.groupby.DataFrameGroupBy.last : Compute the last non-null entry
+            of each column.
+        pandas.core.groupby.DataFrameGroupBy.nth : Take the nth row from each group.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(dict(A=[1, 1, 3], B=[None, 5, 6], C=[1, 2, 3],
+        ...                        D=['3/11/2000', '3/12/2000', '3/13/2000']))
+        >>> df['D'] = pd.to_datetime(df['D'])
+        >>> df.groupby("A").first()
+             B  C          D
+        A
+        1  5.0  1 2000-03-11
+        3  6.0  3 2000-03-13
+        >>> df.groupby("A").first(min_count=2)
+            B    C          D
+        A
+        1 NaN  1.0 2000-03-11
+        3 NaN  NaN        NaT
+        >>> df.groupby("A").first(numeric_only=True)
+             B  C
+        A
+        1  5.0  1
+        3  6.0  3
+        """
+
+        def first_compat(obj: NDFrameT, axis: AxisInt = 0):
+            def first(x: Series):
+                """Helper function for first item that isn't NA."""
+                arr = x.array[notna(x.array)]
+                if not len(arr):
+                    return x.array.dtype.na_value
+                return arr[0]
+
+            if isinstance(obj, DataFrame):
+                return obj.apply(first, axis=axis)
+            elif isinstance(obj, Series):
+                return first(obj)
+            else:  # pragma: no cover
+                raise TypeError(type(obj))
+
+        return self._agg_general(
+            numeric_only=numeric_only,
+            min_count=min_count,
+            alias="first",
+            npfunc=first_compat,
+            skipna=skipna,
+        )
+
+    @final
+    def last(
+        self, numeric_only: bool = False, min_count: int = -1, skipna: bool = True
+    ) -> NDFrameT:
+        """
+        Compute the last entry of each column within each group.
+
+        Defaults to skipping NA elements.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns. If None, will attempt to use
+            everything, then use only numeric data.
+        min_count : int, default -1
+            The required number of valid values to perform the operation. If fewer
+            than ``min_count`` valid values are present the result will be NA.
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+
+            .. versionadded:: 2.2.1
+
+        Returns
+        -------
+        Series or DataFrame
+            Last of values within each group.
+
+        See Also
+        --------
+        DataFrame.groupby : Apply a function groupby to each row or column of a
+            DataFrame.
+        pandas.core.groupby.DataFrameGroupBy.first : Compute the first non-null entry
+            of each column.
+        pandas.core.groupby.DataFrameGroupBy.nth : Take the nth row from each group.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(dict(A=[1, 1, 3], B=[5, None, 6], C=[1, 2, 3]))
+        >>> df.groupby("A").last()
+             B  C
+        A
+        1  5.0  2
+        3  6.0  3
+        """
+
+        def last_compat(obj: NDFrameT, axis: AxisInt = 0):
+            def last(x: Series):
+                """Helper function for last item that isn't NA."""
+                arr = x.array[notna(x.array)]
+                if not len(arr):
+                    return x.array.dtype.na_value
+                return arr[-1]
+
+            if isinstance(obj, DataFrame):
+                return obj.apply(last, axis=axis)
+            elif isinstance(obj, Series):
+                return last(obj)
+            else:  # pragma: no cover
+                raise TypeError(type(obj))
+
+        return self._agg_general(
+            numeric_only=numeric_only,
+            min_count=min_count,
+            alias="last",
+            npfunc=last_compat,
+            skipna=skipna,
+        )
+
+    @final
+    def ohlc(self) -> DataFrame:
+        """
+        Compute open, high, low and close values of a group, excluding missing values.
+
+        For multiple groupings, the result index will be a MultiIndex
+
+        Returns
+        -------
+        DataFrame
+            Open, high, low and close values within each group.
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['SPX', 'CAC', 'SPX', 'CAC', 'SPX', 'CAC', 'SPX', 'CAC',]
+        >>> ser = pd.Series([3.4, 9.0, 7.2, 5.2, 8.8, 9.4, 0.1, 0.5], index=lst)
+        >>> ser
+        SPX     3.4
+        CAC     9.0
+        SPX     7.2
+        CAC     5.2
+        SPX     8.8
+        CAC     9.4
+        SPX     0.1
+        CAC     0.5
+        dtype: float64
+        >>> ser.groupby(level=0).ohlc()
+             open  high  low  close
+        CAC   9.0   9.4  0.5    0.5
+        SPX   3.4   8.8  0.1    0.1
+
+        For DataFrameGroupBy:
+
+        >>> data = {2022: [1.2, 2.3, 8.9, 4.5, 4.4, 3, 2 , 1],
+        ...         2023: [3.4, 9.0, 7.2, 5.2, 8.8, 9.4, 8.2, 1.0]}
+        >>> df = pd.DataFrame(data, index=['SPX', 'CAC', 'SPX', 'CAC',
+        ...                   'SPX', 'CAC', 'SPX', 'CAC'])
+        >>> df
+             2022  2023
+        SPX   1.2   3.4
+        CAC   2.3   9.0
+        SPX   8.9   7.2
+        CAC   4.5   5.2
+        SPX   4.4   8.8
+        CAC   3.0   9.4
+        SPX   2.0   8.2
+        CAC   1.0   1.0
+        >>> df.groupby(level=0).ohlc()
+            2022                 2023
+            open high  low close open high  low close
+        CAC  2.3  4.5  1.0   1.0  9.0  9.4  1.0   1.0
+        SPX  1.2  8.9  1.2   2.0  3.4  8.8  3.4   8.2
+
+        For Resampler:
+
+        >>> ser = pd.Series([1, 3, 2, 4, 3, 5],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').ohlc()
+                    open  high  low  close
+        2023-01-01     1     3    1      2
+        2023-02-01     4     5    3      5
+        """
+        if self.obj.ndim == 1:
+            obj = self._selected_obj
+
+            is_numeric = is_numeric_dtype(obj.dtype)
+            if not is_numeric:
+                raise DataError("No numeric types to aggregate")
+
+            res_values = self._grouper._cython_operation(
+                "aggregate", obj._values, "ohlc", axis=0, min_count=-1
+            )
+
+            agg_names = ["open", "high", "low", "close"]
+            result = self.obj._constructor_expanddim(
+                res_values, index=self._grouper.result_index, columns=agg_names
+            )
+            return self._reindex_output(result)
+
+        result = self._apply_to_column_groupbys(lambda sgb: sgb.ohlc())
+        return result
+
+    @doc(DataFrame.describe)
+    def describe(
+        self,
+        percentiles=None,
+        include=None,
+        exclude=None,
+    ) -> NDFrameT:
+        obj = self._obj_with_exclusions
+
+        if len(obj) == 0:
+            described = obj.describe(
+                percentiles=percentiles, include=include, exclude=exclude
+            )
+            if obj.ndim == 1:
+                result = described
+            else:
+                result = described.unstack()
+            return result.to_frame().T.iloc[:0]
+
+        with com.temp_setattr(self, "as_index", True):
+            result = self._python_apply_general(
+                lambda x: x.describe(
+                    percentiles=percentiles, include=include, exclude=exclude
+                ),
+                obj,
+                not_indexed_same=True,
+            )
+        if self.axis == 1:
+            return result.T
+
+        # GH#49256 - properly handle the grouping column(s)
+        result = result.unstack()
+        if not self.as_index:
+            result = self._insert_inaxis_grouper(result)
+            result.index = default_index(len(result))
+
+        return result
+
+    @final
+    def resample(self, rule, *args, include_groups: bool = True, **kwargs) -> Resampler:
+        """
+        Provide resampling when using a TimeGrouper.
+
+        Given a grouper, the function resamples it according to a string
+        "string" -> "frequency".
+
+        See the :ref:`frequency aliases `
+        documentation for more details.
+
+        Parameters
+        ----------
+        rule : str or DateOffset
+            The offset string or object representing target grouper conversion.
+        *args
+            Possible arguments are `how`, `fill_method`, `limit`, `kind` and
+            `on`, and other arguments of `TimeGrouper`.
+        include_groups : bool, default True
+            When True, will attempt to include the groupings in the operation in
+            the case that they are columns of the DataFrame. If this raises a
+            TypeError, the result will be computed with the groupings excluded.
+            When False, the groupings will be excluded when applying ``func``.
+
+            .. versionadded:: 2.2.0
+
+            .. deprecated:: 2.2.0
+
+               Setting include_groups to True is deprecated. Only the value
+               False will be allowed in a future version of pandas.
+
+        **kwargs
+            Possible arguments are `how`, `fill_method`, `limit`, `kind` and
+            `on`, and other arguments of `TimeGrouper`.
+
+        Returns
+        -------
+        pandas.api.typing.DatetimeIndexResamplerGroupby,
+        pandas.api.typing.PeriodIndexResamplerGroupby, or
+        pandas.api.typing.TimedeltaIndexResamplerGroupby
+            Return a new groupby object, with type depending on the data
+            being resampled.
+
+        See Also
+        --------
+        Grouper : Specify a frequency to resample with when
+            grouping by a key.
+        DatetimeIndex.resample : Frequency conversion and resampling of
+            time series.
+
+        Examples
+        --------
+        >>> idx = pd.date_range('1/1/2000', periods=4, freq='min')
+        >>> df = pd.DataFrame(data=4 * [range(2)],
+        ...                   index=idx,
+        ...                   columns=['a', 'b'])
+        >>> df.iloc[2, 0] = 5
+        >>> df
+                            a  b
+        2000-01-01 00:00:00  0  1
+        2000-01-01 00:01:00  0  1
+        2000-01-01 00:02:00  5  1
+        2000-01-01 00:03:00  0  1
+
+        Downsample the DataFrame into 3 minute bins and sum the values of
+        the timestamps falling into a bin.
+
+        >>> df.groupby('a').resample('3min', include_groups=False).sum()
+                                 b
+        a
+        0   2000-01-01 00:00:00  2
+            2000-01-01 00:03:00  1
+        5   2000-01-01 00:00:00  1
+
+        Upsample the series into 30 second bins.
+
+        >>> df.groupby('a').resample('30s', include_groups=False).sum()
+                            b
+        a
+        0   2000-01-01 00:00:00  1
+            2000-01-01 00:00:30  0
+            2000-01-01 00:01:00  1
+            2000-01-01 00:01:30  0
+            2000-01-01 00:02:00  0
+            2000-01-01 00:02:30  0
+            2000-01-01 00:03:00  1
+        5   2000-01-01 00:02:00  1
+
+        Resample by month. Values are assigned to the month of the period.
+
+        >>> df.groupby('a').resample('ME', include_groups=False).sum()
+                    b
+        a
+        0   2000-01-31  3
+        5   2000-01-31  1
+
+        Downsample the series into 3 minute bins as above, but close the right
+        side of the bin interval.
+
+        >>> (
+        ...     df.groupby('a')
+        ...     .resample('3min', closed='right', include_groups=False)
+        ...     .sum()
+        ... )
+                                 b
+        a
+        0   1999-12-31 23:57:00  1
+            2000-01-01 00:00:00  2
+        5   2000-01-01 00:00:00  1
+
+        Downsample the series into 3 minute bins and close the right side of
+        the bin interval, but label each bin using the right edge instead of
+        the left.
+
+        >>> (
+        ...     df.groupby('a')
+        ...     .resample('3min', closed='right', label='right', include_groups=False)
+        ...     .sum()
+        ... )
+                                 b
+        a
+        0   2000-01-01 00:00:00  1
+            2000-01-01 00:03:00  2
+        5   2000-01-01 00:03:00  1
+        """
+        from pandas.core.resample import get_resampler_for_grouping
+
+        # mypy flags that include_groups could be specified via `*args` or `**kwargs`
+        # GH#54961 would resolve.
+        return get_resampler_for_grouping(  # type: ignore[misc]
+            self, rule, *args, include_groups=include_groups, **kwargs
+        )
+
+    @final
+    def rolling(self, *args, **kwargs) -> RollingGroupby:
+        """
+        Return a rolling grouper, providing rolling functionality per group.
+
+        Parameters
+        ----------
+        window : int, timedelta, str, offset, or BaseIndexer subclass
+            Size of the moving window.
+
+            If an integer, the fixed number of observations used for
+            each window.
+
+            If a timedelta, str, or offset, the time period of each window. Each
+            window will be a variable sized based on the observations included in
+            the time-period. This is only valid for datetimelike indexes.
+            To learn more about the offsets & frequency strings, please see `this link
+            `__.
+
+            If a BaseIndexer subclass, the window boundaries
+            based on the defined ``get_window_bounds`` method. Additional rolling
+            keyword arguments, namely ``min_periods``, ``center``, ``closed`` and
+            ``step`` will be passed to ``get_window_bounds``.
+
+        min_periods : int, default None
+            Minimum number of observations in window required to have a value;
+            otherwise, result is ``np.nan``.
+
+            For a window that is specified by an offset,
+            ``min_periods`` will default to 1.
+
+            For a window that is specified by an integer, ``min_periods`` will default
+            to the size of the window.
+
+        center : bool, default False
+            If False, set the window labels as the right edge of the window index.
+
+            If True, set the window labels as the center of the window index.
+
+        win_type : str, default None
+            If ``None``, all points are evenly weighted.
+
+            If a string, it must be a valid `scipy.signal window function
+            `__.
+
+            Certain Scipy window types require additional parameters to be passed
+            in the aggregation function. The additional parameters must match
+            the keywords specified in the Scipy window type method signature.
+
+        on : str, optional
+            For a DataFrame, a column label or Index level on which
+            to calculate the rolling window, rather than the DataFrame's index.
+
+            Provided integer column is ignored and excluded from result since
+            an integer index is not used to calculate the rolling window.
+
+        axis : int or str, default 0
+            If ``0`` or ``'index'``, roll across the rows.
+
+            If ``1`` or ``'columns'``, roll across the columns.
+
+            For `Series` this parameter is unused and defaults to 0.
+
+        closed : str, default None
+            If ``'right'``, the first point in the window is excluded from calculations.
+
+            If ``'left'``, the last point in the window is excluded from calculations.
+
+            If ``'both'``, no points in the window are excluded from calculations.
+
+            If ``'neither'``, the first and last points in the window are excluded
+            from calculations.
+
+            Default ``None`` (``'right'``).
+
+        method : str {'single', 'table'}, default 'single'
+            Execute the rolling operation per single column or row (``'single'``)
+            or over the entire object (``'table'``).
+
+            This argument is only implemented when specifying ``engine='numba'``
+            in the method call.
+
+        Returns
+        -------
+        pandas.api.typing.RollingGroupby
+            Return a new grouper with our rolling appended.
+
+        See Also
+        --------
+        Series.rolling : Calling object with Series data.
+        DataFrame.rolling : Calling object with DataFrames.
+        Series.groupby : Apply a function groupby to a Series.
+        DataFrame.groupby : Apply a function groupby.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 1, 2, 2],
+        ...                    'B': [1, 2, 3, 4],
+        ...                    'C': [0.362, 0.227, 1.267, -0.562]})
+        >>> df
+              A  B      C
+        0     1  1  0.362
+        1     1  2  0.227
+        2     2  3  1.267
+        3     2  4 -0.562
+
+        >>> df.groupby('A').rolling(2).sum()
+            B      C
+        A
+        1 0  NaN    NaN
+          1  3.0  0.589
+        2 2  NaN    NaN
+          3  7.0  0.705
+
+        >>> df.groupby('A').rolling(2, min_periods=1).sum()
+            B      C
+        A
+        1 0  1.0  0.362
+          1  3.0  0.589
+        2 2  3.0  1.267
+          3  7.0  0.705
+
+        >>> df.groupby('A').rolling(2, on='B').sum()
+            B      C
+        A
+        1 0  1    NaN
+          1  2  0.589
+        2 2  3    NaN
+          3  4  0.705
+        """
+        from pandas.core.window import RollingGroupby
+
+        return RollingGroupby(
+            self._selected_obj,
+            *args,
+            _grouper=self._grouper,
+            _as_index=self.as_index,
+            **kwargs,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Appender(_common_see_also)
+    def expanding(self, *args, **kwargs) -> ExpandingGroupby:
+        """
+        Return an expanding grouper, providing expanding
+        functionality per group.
+
+        Returns
+        -------
+        pandas.api.typing.ExpandingGroupby
+        """
+        from pandas.core.window import ExpandingGroupby
+
+        return ExpandingGroupby(
+            self._selected_obj,
+            *args,
+            _grouper=self._grouper,
+            **kwargs,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Appender(_common_see_also)
+    def ewm(self, *args, **kwargs) -> ExponentialMovingWindowGroupby:
+        """
+        Return an ewm grouper, providing ewm functionality per group.
+
+        Returns
+        -------
+        pandas.api.typing.ExponentialMovingWindowGroupby
+        """
+        from pandas.core.window import ExponentialMovingWindowGroupby
+
+        return ExponentialMovingWindowGroupby(
+            self._selected_obj,
+            *args,
+            _grouper=self._grouper,
+            **kwargs,
+        )
+
+    @final
+    def _fill(self, direction: Literal["ffill", "bfill"], limit: int | None = None):
+        """
+        Shared function for `pad` and `backfill` to call Cython method.
+
+        Parameters
+        ----------
+        direction : {'ffill', 'bfill'}
+            Direction passed to underlying Cython function. `bfill` will cause
+            values to be filled backwards. `ffill` and any other values will
+            default to a forward fill
+        limit : int, default None
+            Maximum number of consecutive values to fill. If `None`, this
+            method will convert to -1 prior to passing to Cython
+
+        Returns
+        -------
+        `Series` or `DataFrame` with filled values
+
+        See Also
+        --------
+        pad : Returns Series with minimum number of char in object.
+        backfill : Backward fill the missing values in the dataset.
+        """
+        # Need int value for Cython
+        if limit is None:
+            limit = -1
+
+        ids, _, _ = self._grouper.group_info
+        sorted_labels = np.argsort(ids, kind="mergesort").astype(np.intp, copy=False)
+        if direction == "bfill":
+            sorted_labels = sorted_labels[::-1]
+
+        col_func = partial(
+            libgroupby.group_fillna_indexer,
+            labels=ids,
+            sorted_labels=sorted_labels,
+            limit=limit,
+            dropna=self.dropna,
+        )
+
+        def blk_func(values: ArrayLike) -> ArrayLike:
+            mask = isna(values)
+            if values.ndim == 1:
+                indexer = np.empty(values.shape, dtype=np.intp)
+                col_func(out=indexer, mask=mask)
+                return algorithms.take_nd(values, indexer)
+
+            else:
+                # We broadcast algorithms.take_nd analogous to
+                #  np.take_along_axis
+                if isinstance(values, np.ndarray):
+                    dtype = values.dtype
+                    if self._grouper.has_dropped_na:
+                        # dropped null groups give rise to nan in the result
+                        dtype = ensure_dtype_can_hold_na(values.dtype)
+                    out = np.empty(values.shape, dtype=dtype)
+                else:
+                    # Note: we only get here with backfill/pad,
+                    #  so if we have a dtype that cannot hold NAs,
+                    #  then there will be no -1s in indexer, so we can use
+                    #  the original dtype (no need to ensure_dtype_can_hold_na)
+                    out = type(values)._empty(values.shape, dtype=values.dtype)
+
+                for i, value_element in enumerate(values):
+                    # call group_fillna_indexer column-wise
+                    indexer = np.empty(values.shape[1], dtype=np.intp)
+                    col_func(out=indexer, mask=mask[i])
+                    out[i, :] = algorithms.take_nd(value_element, indexer)
+                return out
+
+        mgr = self._get_data_to_aggregate()
+        res_mgr = mgr.apply(blk_func)
+
+        new_obj = self._wrap_agged_manager(res_mgr)
+
+        if self.axis == 1:
+            # Only relevant for DataFrameGroupBy
+            new_obj = new_obj.T
+            new_obj.columns = self.obj.columns
+
+        new_obj.index = self.obj.index
+        return new_obj
+
+    @final
+    @Substitution(name="groupby")
+    def ffill(self, limit: int | None = None):
+        """
+        Forward fill the values.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object with missing values filled.
+
+        See Also
+        --------
+        Series.ffill: Returns Series with minimum number of char in object.
+        DataFrame.ffill: Object with missing values filled or None if inplace=True.
+        Series.fillna: Fill NaN values of a Series.
+        DataFrame.fillna: Fill NaN values of a DataFrame.
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> key = [0, 0, 1, 1]
+        >>> ser = pd.Series([np.nan, 2, 3, np.nan], index=key)
+        >>> ser
+        0    NaN
+        0    2.0
+        1    3.0
+        1    NaN
+        dtype: float64
+        >>> ser.groupby(level=0).ffill()
+        0    NaN
+        0    2.0
+        1    3.0
+        1    3.0
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         "key": [0, 0, 1, 1, 1],
+        ...         "A": [np.nan, 2, np.nan, 3, np.nan],
+        ...         "B": [2, 3, np.nan, np.nan, np.nan],
+        ...         "C": [np.nan, np.nan, 2, np.nan, np.nan],
+        ...     }
+        ... )
+        >>> df
+           key    A    B   C
+        0    0  NaN  2.0 NaN
+        1    0  2.0  3.0 NaN
+        2    1  NaN  NaN 2.0
+        3    1  3.0  NaN NaN
+        4    1  NaN  NaN NaN
+
+        Propagate non-null values forward or backward within each group along columns.
+
+        >>> df.groupby("key").ffill()
+             A    B   C
+        0  NaN  2.0 NaN
+        1  2.0  3.0 NaN
+        2  NaN  NaN 2.0
+        3  3.0  NaN 2.0
+        4  3.0  NaN 2.0
+
+        Propagate non-null values forward or backward within each group along rows.
+
+        >>> df.T.groupby(np.array([0, 0, 1, 1])).ffill().T
+           key    A    B    C
+        0  0.0  0.0  2.0  2.0
+        1  0.0  2.0  3.0  3.0
+        2  1.0  1.0  NaN  2.0
+        3  1.0  3.0  NaN  NaN
+        4  1.0  1.0  NaN  NaN
+
+        Only replace the first NaN element within a group along rows.
+
+        >>> df.groupby("key").ffill(limit=1)
+             A    B    C
+        0  NaN  2.0  NaN
+        1  2.0  3.0  NaN
+        2  NaN  NaN  2.0
+        3  3.0  NaN  2.0
+        4  3.0  NaN  NaN
+        """
+        return self._fill("ffill", limit=limit)
+
+    @final
+    @Substitution(name="groupby")
+    def bfill(self, limit: int | None = None):
+        """
+        Backward fill the values.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object with missing values filled.
+
+        See Also
+        --------
+        Series.bfill :  Backward fill the missing values in the dataset.
+        DataFrame.bfill:  Backward fill the missing values in the dataset.
+        Series.fillna: Fill NaN values of a Series.
+        DataFrame.fillna: Fill NaN values of a DataFrame.
+
+        Examples
+        --------
+
+        With Series:
+
+        >>> index = ['Falcon', 'Falcon', 'Parrot', 'Parrot', 'Parrot']
+        >>> s = pd.Series([None, 1, None, None, 3], index=index)
+        >>> s
+        Falcon    NaN
+        Falcon    1.0
+        Parrot    NaN
+        Parrot    NaN
+        Parrot    3.0
+        dtype: float64
+        >>> s.groupby(level=0).bfill()
+        Falcon    1.0
+        Falcon    1.0
+        Parrot    3.0
+        Parrot    3.0
+        Parrot    3.0
+        dtype: float64
+        >>> s.groupby(level=0).bfill(limit=1)
+        Falcon    1.0
+        Falcon    1.0
+        Parrot    NaN
+        Parrot    3.0
+        Parrot    3.0
+        dtype: float64
+
+        With DataFrame:
+
+        >>> df = pd.DataFrame({'A': [1, None, None, None, 4],
+        ...                    'B': [None, None, 5, None, 7]}, index=index)
+        >>> df
+                  A	    B
+        Falcon	1.0	  NaN
+        Falcon	NaN	  NaN
+        Parrot	NaN	  5.0
+        Parrot	NaN	  NaN
+        Parrot	4.0	  7.0
+        >>> df.groupby(level=0).bfill()
+                  A	    B
+        Falcon	1.0	  NaN
+        Falcon	NaN	  NaN
+        Parrot	4.0	  5.0
+        Parrot	4.0	  7.0
+        Parrot	4.0	  7.0
+        >>> df.groupby(level=0).bfill(limit=1)
+                  A	    B
+        Falcon	1.0	  NaN
+        Falcon	NaN	  NaN
+        Parrot	NaN	  5.0
+        Parrot	4.0	  7.0
+        Parrot	4.0	  7.0
+        """
+        return self._fill("bfill", limit=limit)
+
+    @final
+    @property
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def nth(self) -> GroupByNthSelector:
+        """
+        Take the nth row from each group if n is an int, otherwise a subset of rows.
+
+        Can be either a call or an index. dropna is not available with index notation.
+        Index notation accepts a comma separated list of integers and slices.
+
+        If dropna, will take the nth non-null row, dropna is either
+        'all' or 'any'; this is equivalent to calling dropna(how=dropna)
+        before the groupby.
+
+        Parameters
+        ----------
+        n : int, slice or list of ints and slices
+            A single nth value for the row or a list of nth values or slices.
+
+            .. versionchanged:: 1.4.0
+                Added slice and lists containing slices.
+                Added index notation.
+
+        dropna : {'any', 'all', None}, default None
+            Apply the specified dropna operation before counting which row is
+            the nth row. Only supported if n is an int.
+
+        Returns
+        -------
+        Series or DataFrame
+            N-th value within each group.
+        %(see_also)s
+        Examples
+        --------
+
+        >>> df = pd.DataFrame({'A': [1, 1, 2, 1, 2],
+        ...                    'B': [np.nan, 2, 3, 4, 5]}, columns=['A', 'B'])
+        >>> g = df.groupby('A')
+        >>> g.nth(0)
+           A   B
+        0  1 NaN
+        2  2 3.0
+        >>> g.nth(1)
+           A   B
+        1  1 2.0
+        4  2 5.0
+        >>> g.nth(-1)
+           A   B
+        3  1 4.0
+        4  2 5.0
+        >>> g.nth([0, 1])
+           A   B
+        0  1 NaN
+        1  1 2.0
+        2  2 3.0
+        4  2 5.0
+        >>> g.nth(slice(None, -1))
+           A   B
+        0  1 NaN
+        1  1 2.0
+        2  2 3.0
+
+        Index notation may also be used
+
+        >>> g.nth[0, 1]
+           A   B
+        0  1 NaN
+        1  1 2.0
+        2  2 3.0
+        4  2 5.0
+        >>> g.nth[:-1]
+           A   B
+        0  1 NaN
+        1  1 2.0
+        2  2 3.0
+
+        Specifying `dropna` allows ignoring ``NaN`` values
+
+        >>> g.nth(0, dropna='any')
+           A   B
+        1  1 2.0
+        2  2 3.0
+
+        When the specified ``n`` is larger than any of the groups, an
+        empty DataFrame is returned
+
+        >>> g.nth(3, dropna='any')
+        Empty DataFrame
+        Columns: [A, B]
+        Index: []
+        """
+        return GroupByNthSelector(self)
+
+    def _nth(
+        self,
+        n: PositionalIndexer | tuple,
+        dropna: Literal["any", "all", None] = None,
+    ) -> NDFrameT:
+        if not dropna:
+            mask = self._make_mask_from_positional_indexer(n)
+
+            ids, _, _ = self._grouper.group_info
+
+            # Drop NA values in grouping
+            mask = mask & (ids != -1)
+
+            out = self._mask_selected_obj(mask)
+            return out
+
+        # dropna is truthy
+        if not is_integer(n):
+            raise ValueError("dropna option only supported for an integer argument")
+
+        if dropna not in ["any", "all"]:
+            # Note: when agg-ing picker doesn't raise this, just returns NaN
+            raise ValueError(
+                "For a DataFrame or Series groupby.nth, dropna must be "
+                "either None, 'any' or 'all', "
+                f"(was passed {dropna})."
+            )
+
+        # old behaviour, but with all and any support for DataFrames.
+        # modified in GH 7559 to have better perf
+        n = cast(int, n)
+        dropped = self._selected_obj.dropna(how=dropna, axis=self.axis)
+
+        # get a new grouper for our dropped obj
+        grouper: np.ndarray | Index | ops.BaseGrouper
+        if len(dropped) == len(self._selected_obj):
+            # Nothing was dropped, can use the same grouper
+            grouper = self._grouper
+        else:
+            # we don't have the grouper info available
+            # (e.g. we have selected out
+            # a column that is not in the current object)
+            axis = self._grouper.axis
+            grouper = self._grouper.codes_info[axis.isin(dropped.index)]
+            if self._grouper.has_dropped_na:
+                # Null groups need to still be encoded as -1 when passed to groupby
+                nulls = grouper == -1
+                # error: No overload variant of "where" matches argument types
+                #        "Any", "NAType", "Any"
+                values = np.where(nulls, NA, grouper)  # type: ignore[call-overload]
+                grouper = Index(values, dtype="Int64")
+
+        if self.axis == 1:
+            grb = dropped.T.groupby(grouper, as_index=self.as_index, sort=self.sort)
+        else:
+            grb = dropped.groupby(grouper, as_index=self.as_index, sort=self.sort)
+        return grb.nth(n)
+
+    @final
+    def quantile(
+        self,
+        q: float | AnyArrayLike = 0.5,
+        interpolation: str = "linear",
+        numeric_only: bool = False,
+    ):
+        """
+        Return group values at the given quantile, a la numpy.percentile.
+
+        Parameters
+        ----------
+        q : float or array-like, default 0.5 (50% quantile)
+            Value(s) between 0 and 1 providing the quantile(s) to compute.
+        interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
+            Method to use when the desired quantile falls between two points.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        Series or DataFrame
+            Return type determined by caller of GroupBy object.
+
+        See Also
+        --------
+        Series.quantile : Similar method for Series.
+        DataFrame.quantile : Similar method for DataFrame.
+        numpy.percentile : NumPy method to compute qth percentile.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([
+        ...     ['a', 1], ['a', 2], ['a', 3],
+        ...     ['b', 1], ['b', 3], ['b', 5]
+        ... ], columns=['key', 'val'])
+        >>> df.groupby('key').quantile()
+            val
+        key
+        a    2.0
+        b    3.0
+        """
+        mgr = self._get_data_to_aggregate(numeric_only=numeric_only, name="quantile")
+        obj = self._wrap_agged_manager(mgr)
+        if self.axis == 1:
+            splitter = self._grouper._get_splitter(obj.T, axis=self.axis)
+            sdata = splitter._sorted_data.T
+        else:
+            splitter = self._grouper._get_splitter(obj, axis=self.axis)
+            sdata = splitter._sorted_data
+
+        starts, ends = lib.generate_slices(splitter._slabels, splitter.ngroups)
+
+        def pre_processor(vals: ArrayLike) -> tuple[np.ndarray, DtypeObj | None]:
+            if isinstance(vals.dtype, StringDtype) or is_object_dtype(vals.dtype):
+                raise TypeError(
+                    f"dtype '{vals.dtype}' does not support operation 'quantile'"
+                )
+
+            inference: DtypeObj | None = None
+            if isinstance(vals, BaseMaskedArray) and is_numeric_dtype(vals.dtype):
+                out = vals.to_numpy(dtype=float, na_value=np.nan)
+                inference = vals.dtype
+            elif is_integer_dtype(vals.dtype):
+                if isinstance(vals, ExtensionArray):
+                    out = vals.to_numpy(dtype=float, na_value=np.nan)
+                else:
+                    out = vals
+                inference = np.dtype(np.int64)
+            elif is_bool_dtype(vals.dtype) and isinstance(vals, ExtensionArray):
+                out = vals.to_numpy(dtype=float, na_value=np.nan)
+            elif is_bool_dtype(vals.dtype):
+                # GH#51424 deprecate to match Series/DataFrame behavior
+                warnings.warn(
+                    f"Allowing bool dtype in {type(self).__name__}.quantile is "
+                    "deprecated and will raise in a future version, matching "
+                    "the Series/DataFrame behavior. Cast to uint8 dtype before "
+                    "calling quantile instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                out = np.asarray(vals)
+            elif needs_i8_conversion(vals.dtype):
+                inference = vals.dtype
+                # In this case we need to delay the casting until after the
+                #  np.lexsort below.
+                # error: Incompatible return value type (got
+                # "Tuple[Union[ExtensionArray, ndarray[Any, Any]], Union[Any,
+                # ExtensionDtype]]", expected "Tuple[ndarray[Any, Any],
+                # Optional[Union[dtype[Any], ExtensionDtype]]]")
+                return vals, inference  # type: ignore[return-value]
+            elif isinstance(vals, ExtensionArray) and is_float_dtype(vals.dtype):
+                inference = np.dtype(np.float64)
+                out = vals.to_numpy(dtype=float, na_value=np.nan)
+            else:
+                out = np.asarray(vals)
+
+            return out, inference
+
+        def post_processor(
+            vals: np.ndarray,
+            inference: DtypeObj | None,
+            result_mask: np.ndarray | None,
+            orig_vals: ArrayLike,
+        ) -> ArrayLike:
+            if inference:
+                # Check for edge case
+                if isinstance(orig_vals, BaseMaskedArray):
+                    assert result_mask is not None  # for mypy
+
+                    if interpolation in {"linear", "midpoint"} and not is_float_dtype(
+                        orig_vals
+                    ):
+                        return FloatingArray(vals, result_mask)
+                    else:
+                        # Item "ExtensionDtype" of "Union[ExtensionDtype, str,
+                        # dtype[Any], Type[object]]" has no attribute "numpy_dtype"
+                        # [union-attr]
+                        with warnings.catch_warnings():
+                            # vals.astype with nan can warn with numpy >1.24
+                            warnings.filterwarnings("ignore", category=RuntimeWarning)
+                            return type(orig_vals)(
+                                vals.astype(
+                                    inference.numpy_dtype  # type: ignore[union-attr]
+                                ),
+                                result_mask,
+                            )
+
+                elif not (
+                    is_integer_dtype(inference)
+                    and interpolation in {"linear", "midpoint"}
+                ):
+                    if needs_i8_conversion(inference):
+                        # error: Item "ExtensionArray" of "Union[ExtensionArray,
+                        # ndarray[Any, Any]]" has no attribute "_ndarray"
+                        vals = vals.astype("i8").view(
+                            orig_vals._ndarray.dtype  # type: ignore[union-attr]
+                        )
+                        # error: Item "ExtensionArray" of "Union[ExtensionArray,
+                        # ndarray[Any, Any]]" has no attribute "_from_backing_data"
+                        return orig_vals._from_backing_data(  # type: ignore[union-attr]
+                            vals
+                        )
+
+                    assert isinstance(inference, np.dtype)  # for mypy
+                    return vals.astype(inference)
+
+            return vals
+
+        qs = np.array(q, dtype=np.float64)
+        pass_qs: np.ndarray | None = qs
+        if is_scalar(q):
+            qs = np.array([q], dtype=np.float64)
+            pass_qs = None
+
+        ids, _, ngroups = self._grouper.group_info
+        nqs = len(qs)
+
+        func = partial(
+            libgroupby.group_quantile,
+            labels=ids,
+            qs=qs,
+            interpolation=interpolation,
+            starts=starts,
+            ends=ends,
+        )
+
+        def blk_func(values: ArrayLike) -> ArrayLike:
+            orig_vals = values
+            if isinstance(values, BaseMaskedArray):
+                mask = values._mask
+                result_mask = np.zeros((ngroups, nqs), dtype=np.bool_)
+            else:
+                mask = isna(values)
+                result_mask = None
+
+            is_datetimelike = needs_i8_conversion(values.dtype)
+
+            vals, inference = pre_processor(values)
+
+            ncols = 1
+            if vals.ndim == 2:
+                ncols = vals.shape[0]
+
+            out = np.empty((ncols, ngroups, nqs), dtype=np.float64)
+
+            if is_datetimelike:
+                vals = vals.view("i8")
+
+            if vals.ndim == 1:
+                # EA is always 1d
+                func(
+                    out[0],
+                    values=vals,
+                    mask=mask,
+                    result_mask=result_mask,
+                    is_datetimelike=is_datetimelike,
+                )
+            else:
+                for i in range(ncols):
+                    func(
+                        out[i],
+                        values=vals[i],
+                        mask=mask[i],
+                        result_mask=None,
+                        is_datetimelike=is_datetimelike,
+                    )
+
+            if vals.ndim == 1:
+                out = out.ravel("K")
+                if result_mask is not None:
+                    result_mask = result_mask.ravel("K")
+            else:
+                out = out.reshape(ncols, ngroups * nqs)
+
+            return post_processor(out, inference, result_mask, orig_vals)
+
+        res_mgr = sdata._mgr.grouped_reduce(blk_func)
+
+        res = self._wrap_agged_manager(res_mgr)
+        return self._wrap_aggregated_output(res, qs=pass_qs)
+
+    @final
+    @Substitution(name="groupby")
+    def ngroup(self, ascending: bool = True):
+        """
+        Number each group from 0 to the number of groups - 1.
+
+        This is the enumerative complement of cumcount.  Note that the
+        numbers given to the groups match the order in which the groups
+        would be seen when iterating over the groupby object, not the
+        order they are first observed.
+
+        Groups with missing keys (where `pd.isna()` is True) will be labeled with `NaN`
+        and will be skipped from the count.
+
+        Parameters
+        ----------
+        ascending : bool, default True
+            If False, number in reverse, from number of group - 1 to 0.
+
+        Returns
+        -------
+        Series
+            Unique numbers for each group.
+
+        See Also
+        --------
+        .cumcount : Number the rows in each group.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"color": ["red", None, "red", "blue", "blue", "red"]})
+        >>> df
+           color
+        0    red
+        1   None
+        2    red
+        3   blue
+        4   blue
+        5    red
+        >>> df.groupby("color").ngroup()
+        0    1.0
+        1    NaN
+        2    1.0
+        3    0.0
+        4    0.0
+        5    1.0
+        dtype: float64
+        >>> df.groupby("color", dropna=False).ngroup()
+        0    1
+        1    2
+        2    1
+        3    0
+        4    0
+        5    1
+        dtype: int64
+        >>> df.groupby("color", dropna=False).ngroup(ascending=False)
+        0    1
+        1    0
+        2    1
+        3    2
+        4    2
+        5    1
+        dtype: int64
+        """
+        obj = self._obj_with_exclusions
+        index = obj._get_axis(self.axis)
+        comp_ids = self._grouper.group_info[0]
+
+        dtype: type
+        if self._grouper.has_dropped_na:
+            comp_ids = np.where(comp_ids == -1, np.nan, comp_ids)
+            dtype = np.float64
+        else:
+            dtype = np.int64
+
+        if any(ping._passed_categorical for ping in self._grouper.groupings):
+            # comp_ids reflect non-observed groups, we need only observed
+            comp_ids = rank_1d(comp_ids, ties_method="dense") - 1
+
+        result = self._obj_1d_constructor(comp_ids, index, dtype=dtype)
+        if not ascending:
+            result = self.ngroups - 1 - result
+        return result
+
+    @final
+    @Substitution(name="groupby")
+    def cumcount(self, ascending: bool = True):
+        """
+        Number each item in each group from 0 to the length of that group - 1.
+
+        Essentially this is equivalent to
+
+        .. code-block:: python
+
+            self.apply(lambda x: pd.Series(np.arange(len(x)), x.index))
+
+        Parameters
+        ----------
+        ascending : bool, default True
+            If False, number in reverse, from length of group - 1 to 0.
+
+        Returns
+        -------
+        Series
+            Sequence number of each element within each group.
+
+        See Also
+        --------
+        .ngroup : Number the groups themselves.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([['a'], ['a'], ['a'], ['b'], ['b'], ['a']],
+        ...                   columns=['A'])
+        >>> df
+           A
+        0  a
+        1  a
+        2  a
+        3  b
+        4  b
+        5  a
+        >>> df.groupby('A').cumcount()
+        0    0
+        1    1
+        2    2
+        3    0
+        4    1
+        5    3
+        dtype: int64
+        >>> df.groupby('A').cumcount(ascending=False)
+        0    3
+        1    2
+        2    1
+        3    1
+        4    0
+        5    0
+        dtype: int64
+        """
+        index = self._obj_with_exclusions._get_axis(self.axis)
+        cumcounts = self._cumcount_array(ascending=ascending)
+        return self._obj_1d_constructor(cumcounts, index)
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def rank(
+        self,
+        method: str = "average",
+        ascending: bool = True,
+        na_option: str = "keep",
+        pct: bool = False,
+        axis: AxisInt | lib.NoDefault = lib.no_default,
+    ) -> NDFrameT:
+        """
+        Provide the rank of values within each group.
+
+        Parameters
+        ----------
+        method : {'average', 'min', 'max', 'first', 'dense'}, default 'average'
+            * average: average rank of group.
+            * min: lowest rank in group.
+            * max: highest rank in group.
+            * first: ranks assigned in order they appear in the array.
+            * dense: like 'min', but rank always increases by 1 between groups.
+        ascending : bool, default True
+            False for ranks by high (1) to low (N).
+        na_option : {'keep', 'top', 'bottom'}, default 'keep'
+            * keep: leave NA values where they are.
+            * top: smallest rank if ascending.
+            * bottom: smallest rank if descending.
+        pct : bool, default False
+            Compute percentage rank of data within each group.
+        axis : int, default 0
+            The axis of the object over which to compute the rank.
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        Returns
+        -------
+        DataFrame with ranking of values within each group
+        %(see_also)s
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         "group": ["a", "a", "a", "a", "a", "b", "b", "b", "b", "b"],
+        ...         "value": [2, 4, 2, 3, 5, 1, 2, 4, 1, 5],
+        ...     }
+        ... )
+        >>> df
+          group  value
+        0     a      2
+        1     a      4
+        2     a      2
+        3     a      3
+        4     a      5
+        5     b      1
+        6     b      2
+        7     b      4
+        8     b      1
+        9     b      5
+        >>> for method in ['average', 'min', 'max', 'dense', 'first']:
+        ...     df[f'{method}_rank'] = df.groupby('group')['value'].rank(method)
+        >>> df
+          group  value  average_rank  min_rank  max_rank  dense_rank  first_rank
+        0     a      2           1.5       1.0       2.0         1.0         1.0
+        1     a      4           4.0       4.0       4.0         3.0         4.0
+        2     a      2           1.5       1.0       2.0         1.0         2.0
+        3     a      3           3.0       3.0       3.0         2.0         3.0
+        4     a      5           5.0       5.0       5.0         4.0         5.0
+        5     b      1           1.5       1.0       2.0         1.0         1.0
+        6     b      2           3.0       3.0       3.0         2.0         3.0
+        7     b      4           4.0       4.0       4.0         3.0         4.0
+        8     b      1           1.5       1.0       2.0         1.0         2.0
+        9     b      5           5.0       5.0       5.0         4.0         5.0
+        """
+        if na_option not in {"keep", "top", "bottom"}:
+            msg = "na_option must be one of 'keep', 'top', or 'bottom'"
+            raise ValueError(msg)
+
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "rank")
+        else:
+            axis = 0
+
+        kwargs = {
+            "ties_method": method,
+            "ascending": ascending,
+            "na_option": na_option,
+            "pct": pct,
+        }
+        if axis != 0:
+            # DataFrame uses different keyword name
+            kwargs["method"] = kwargs.pop("ties_method")
+            f = lambda x: x.rank(axis=axis, numeric_only=False, **kwargs)
+            result = self._python_apply_general(
+                f, self._selected_obj, is_transform=True
+            )
+            return result
+
+        return self._cython_transform(
+            "rank",
+            numeric_only=False,
+            axis=axis,
+            **kwargs,
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def cumprod(
+        self, axis: Axis | lib.NoDefault = lib.no_default, *args, **kwargs
+    ) -> NDFrameT:
+        """
+        Cumulative product for each group.
+
+        Returns
+        -------
+        Series or DataFrame
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([6, 2, 0], index=lst)
+        >>> ser
+        a    6
+        a    2
+        b    0
+        dtype: int64
+        >>> ser.groupby(level=0).cumprod()
+        a    6
+        a   12
+        b    0
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["cow", "horse", "bull"])
+        >>> df
+                a   b   c
+        cow     1   8   2
+        horse   1   2   5
+        bull    2   6   9
+        >>> df.groupby("a").groups
+        {1: ['cow', 'horse'], 2: ['bull']}
+        >>> df.groupby("a").cumprod()
+                b   c
+        cow     8   2
+        horse  16  10
+        bull    6   9
+        """
+        nv.validate_groupby_func("cumprod", args, kwargs, ["numeric_only", "skipna"])
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "cumprod")
+        else:
+            axis = 0
+
+        if axis != 0:
+            f = lambda x: x.cumprod(axis=axis, **kwargs)
+            return self._python_apply_general(f, self._selected_obj, is_transform=True)
+
+        return self._cython_transform("cumprod", **kwargs)
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def cumsum(
+        self, axis: Axis | lib.NoDefault = lib.no_default, *args, **kwargs
+    ) -> NDFrameT:
+        """
+        Cumulative sum for each group.
+
+        Returns
+        -------
+        Series or DataFrame
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b']
+        >>> ser = pd.Series([6, 2, 0], index=lst)
+        >>> ser
+        a    6
+        a    2
+        b    0
+        dtype: int64
+        >>> ser.groupby(level=0).cumsum()
+        a    6
+        a    8
+        b    0
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 2, 5], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["fox", "gorilla", "lion"])
+        >>> df
+                  a   b   c
+        fox       1   8   2
+        gorilla   1   2   5
+        lion      2   6   9
+        >>> df.groupby("a").groups
+        {1: ['fox', 'gorilla'], 2: ['lion']}
+        >>> df.groupby("a").cumsum()
+                  b   c
+        fox       8   2
+        gorilla  10   7
+        lion      6   9
+        """
+        nv.validate_groupby_func("cumsum", args, kwargs, ["numeric_only", "skipna"])
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "cumsum")
+        else:
+            axis = 0
+
+        if axis != 0:
+            f = lambda x: x.cumsum(axis=axis, **kwargs)
+            return self._python_apply_general(f, self._selected_obj, is_transform=True)
+
+        return self._cython_transform("cumsum", **kwargs)
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def cummin(
+        self,
+        axis: AxisInt | lib.NoDefault = lib.no_default,
+        numeric_only: bool = False,
+        **kwargs,
+    ) -> NDFrameT:
+        """
+        Cumulative min for each group.
+
+        Returns
+        -------
+        Series or DataFrame
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([1, 6, 2, 3, 0, 4], index=lst)
+        >>> ser
+        a    1
+        a    6
+        a    2
+        b    3
+        b    0
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).cummin()
+        a    1
+        a    1
+        a    1
+        b    3
+        b    0
+        b    0
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 0, 2], [1, 1, 5], [6, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["snake", "rabbit", "turtle"])
+        >>> df
+                a   b   c
+        snake   1   0   2
+        rabbit  1   1   5
+        turtle  6   6   9
+        >>> df.groupby("a").groups
+        {1: ['snake', 'rabbit'], 6: ['turtle']}
+        >>> df.groupby("a").cummin()
+                b   c
+        snake   0   2
+        rabbit  0   2
+        turtle  6   9
+        """
+        skipna = kwargs.get("skipna", True)
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "cummin")
+        else:
+            axis = 0
+
+        if axis != 0:
+            f = lambda x: np.minimum.accumulate(x, axis)
+            obj = self._selected_obj
+            if numeric_only:
+                obj = obj._get_numeric_data()
+            return self._python_apply_general(f, obj, is_transform=True)
+
+        return self._cython_transform(
+            "cummin", numeric_only=numeric_only, skipna=skipna
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def cummax(
+        self,
+        axis: AxisInt | lib.NoDefault = lib.no_default,
+        numeric_only: bool = False,
+        **kwargs,
+    ) -> NDFrameT:
+        """
+        Cumulative max for each group.
+
+        Returns
+        -------
+        Series or DataFrame
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([1, 6, 2, 3, 1, 4], index=lst)
+        >>> ser
+        a    1
+        a    6
+        a    2
+        b    3
+        b    1
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).cummax()
+        a    1
+        a    6
+        a    6
+        b    3
+        b    3
+        b    4
+        dtype: int64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 8, 2], [1, 1, 0], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["cow", "horse", "bull"])
+        >>> df
+                a   b   c
+        cow     1   8   2
+        horse   1   1   0
+        bull    2   6   9
+        >>> df.groupby("a").groups
+        {1: ['cow', 'horse'], 2: ['bull']}
+        >>> df.groupby("a").cummax()
+                b   c
+        cow     8   2
+        horse   8   2
+        bull    6   9
+        """
+        skipna = kwargs.get("skipna", True)
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "cummax")
+        else:
+            axis = 0
+
+        if axis != 0:
+            f = lambda x: np.maximum.accumulate(x, axis)
+            obj = self._selected_obj
+            if numeric_only:
+                obj = obj._get_numeric_data()
+            return self._python_apply_general(f, obj, is_transform=True)
+
+        return self._cython_transform(
+            "cummax", numeric_only=numeric_only, skipna=skipna
+        )
+
+    @final
+    @Substitution(name="groupby")
+    def shift(
+        self,
+        periods: int | Sequence[int] = 1,
+        freq=None,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        fill_value=lib.no_default,
+        suffix: str | None = None,
+    ):
+        """
+        Shift each group by periods observations.
+
+        If freq is passed, the index will be increased using the periods and the freq.
+
+        Parameters
+        ----------
+        periods : int | Sequence[int], default 1
+            Number of periods to shift. If a list of values, shift each group by
+            each period.
+        freq : str, optional
+            Frequency string.
+        axis : axis to shift, default 0
+            Shift direction.
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        fill_value : optional
+            The scalar value to use for newly introduced missing values.
+
+            .. versionchanged:: 2.1.0
+                Will raise a ``ValueError`` if ``freq`` is provided too.
+
+        suffix : str, optional
+            A string to add to each shifted column if there are multiple periods.
+            Ignored otherwise.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object shifted within each group.
+
+        See Also
+        --------
+        Index.shift : Shift values of Index.
+
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).shift(1)
+        a    NaN
+        a    1.0
+        b    NaN
+        b    3.0
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tuna", "salmon", "catfish", "goldfish"])
+        >>> df
+                   a  b  c
+            tuna   1  2  3
+          salmon   1  5  6
+         catfish   2  5  8
+        goldfish   2  6  9
+        >>> df.groupby("a").shift(1)
+                      b    c
+            tuna    NaN  NaN
+          salmon    2.0  3.0
+         catfish    NaN  NaN
+        goldfish    5.0  8.0
+        """
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "shift")
+        else:
+            axis = 0
+
+        if is_list_like(periods):
+            if axis == 1:
+                raise ValueError(
+                    "If `periods` contains multiple shifts, `axis` cannot be 1."
+                )
+            periods = cast(Sequence, periods)
+            if len(periods) == 0:
+                raise ValueError("If `periods` is an iterable, it cannot be empty.")
+            from pandas.core.reshape.concat import concat
+
+            add_suffix = True
+        else:
+            if not is_integer(periods):
+                raise TypeError(
+                    f"Periods must be integer, but {periods} is {type(periods)}."
+                )
+            if suffix:
+                raise ValueError("Cannot specify `suffix` if `periods` is an int.")
+            periods = [cast(int, periods)]
+            add_suffix = False
+
+        shifted_dataframes = []
+        for period in periods:
+            if not is_integer(period):
+                raise TypeError(
+                    f"Periods must be integer, but {period} is {type(period)}."
+                )
+            period = cast(int, period)
+            if freq is not None or axis != 0:
+                f = lambda x: x.shift(
+                    period, freq, axis, fill_value  # pylint: disable=cell-var-from-loop
+                )
+                shifted = self._python_apply_general(
+                    f, self._selected_obj, is_transform=True
+                )
+            else:
+                if fill_value is lib.no_default:
+                    fill_value = None
+                ids, _, ngroups = self._grouper.group_info
+                res_indexer = np.zeros(len(ids), dtype=np.int64)
+
+                libgroupby.group_shift_indexer(res_indexer, ids, ngroups, period)
+
+                obj = self._obj_with_exclusions
+
+                shifted = obj._reindex_with_indexers(
+                    {self.axis: (obj.axes[self.axis], res_indexer)},
+                    fill_value=fill_value,
+                    allow_dups=True,
+                )
+
+            if add_suffix:
+                if isinstance(shifted, Series):
+                    shifted = cast(NDFrameT, shifted.to_frame())
+                shifted = shifted.add_suffix(
+                    f"{suffix}_{period}" if suffix else f"_{period}"
+                )
+            shifted_dataframes.append(cast(Union[Series, DataFrame], shifted))
+
+        return (
+            shifted_dataframes[0]
+            if len(shifted_dataframes) == 1
+            else concat(shifted_dataframes, axis=1)
+        )
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def diff(
+        self, periods: int = 1, axis: AxisInt | lib.NoDefault = lib.no_default
+    ) -> NDFrameT:
+        """
+        First discrete difference of element.
+
+        Calculates the difference of each element compared with another
+        element in the group (default is element in previous row).
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Periods to shift for calculating difference, accepts negative values.
+        axis : axis to shift, default 0
+            Take difference over rows (0) or columns (1).
+
+            .. deprecated:: 2.1.0
+                For axis=1, operate on the underlying object instead. Otherwise
+                the axis keyword is not necessary.
+
+        Returns
+        -------
+        Series or DataFrame
+            First differences.
+        %(see_also)s
+        Examples
+        --------
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([7, 2, 8, 4, 3, 3], index=lst)
+        >>> ser
+        a     7
+        a     2
+        a     8
+        b     4
+        b     3
+        b     3
+        dtype: int64
+        >>> ser.groupby(level=0).diff()
+        a    NaN
+        a   -5.0
+        a    6.0
+        b    NaN
+        b   -1.0
+        b    0.0
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = {'a': [1, 3, 5, 7, 7, 8, 3], 'b': [1, 4, 8, 4, 4, 2, 1]}
+        >>> df = pd.DataFrame(data, index=['dog', 'dog', 'dog',
+        ...                   'mouse', 'mouse', 'mouse', 'mouse'])
+        >>> df
+                 a  b
+          dog    1  1
+          dog    3  4
+          dog    5  8
+        mouse    7  4
+        mouse    7  4
+        mouse    8  2
+        mouse    3  1
+        >>> df.groupby(level=0).diff()
+                 a    b
+          dog  NaN  NaN
+          dog  2.0  3.0
+          dog  2.0  4.0
+        mouse  NaN  NaN
+        mouse  0.0  0.0
+        mouse  1.0 -2.0
+        mouse -5.0 -1.0
+        """
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "diff")
+        else:
+            axis = 0
+
+        if axis != 0:
+            return self.apply(lambda x: x.diff(periods=periods, axis=axis))
+
+        obj = self._obj_with_exclusions
+        shifted = self.shift(periods=periods)
+
+        # GH45562 - to retain existing behavior and match behavior of Series.diff(),
+        # int8 and int16 are coerced to float32 rather than float64.
+        dtypes_to_f32 = ["int8", "int16"]
+        if obj.ndim == 1:
+            if obj.dtype in dtypes_to_f32:
+                shifted = shifted.astype("float32")
+        else:
+            to_coerce = [c for c, dtype in obj.dtypes.items() if dtype in dtypes_to_f32]
+            if len(to_coerce):
+                shifted = shifted.astype({c: "float32" for c in to_coerce})
+
+        return obj - shifted
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def pct_change(
+        self,
+        periods: int = 1,
+        fill_method: FillnaOptions | None | lib.NoDefault = lib.no_default,
+        limit: int | None | lib.NoDefault = lib.no_default,
+        freq=None,
+        axis: Axis | lib.NoDefault = lib.no_default,
+    ):
+        """
+        Calculate pct_change of each value to previous entry in group.
+
+        Returns
+        -------
+        Series or DataFrame
+            Percentage changes within each group.
+        %(see_also)s
+        Examples
+        --------
+
+        For SeriesGroupBy:
+
+        >>> lst = ['a', 'a', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 3, 4], index=lst)
+        >>> ser
+        a    1
+        a    2
+        b    3
+        b    4
+        dtype: int64
+        >>> ser.groupby(level=0).pct_change()
+        a         NaN
+        a    1.000000
+        b         NaN
+        b    0.333333
+        dtype: float64
+
+        For DataFrameGroupBy:
+
+        >>> data = [[1, 2, 3], [1, 5, 6], [2, 5, 8], [2, 6, 9]]
+        >>> df = pd.DataFrame(data, columns=["a", "b", "c"],
+        ...                   index=["tuna", "salmon", "catfish", "goldfish"])
+        >>> df
+                   a  b  c
+            tuna   1  2  3
+          salmon   1  5  6
+         catfish   2  5  8
+        goldfish   2  6  9
+        >>> df.groupby("a").pct_change()
+                    b  c
+            tuna    NaN    NaN
+          salmon    1.5  1.000
+         catfish    NaN    NaN
+        goldfish    0.2  0.125
+        """
+        # GH#53491
+        if fill_method not in (lib.no_default, None) or limit is not lib.no_default:
+            warnings.warn(
+                "The 'fill_method' keyword being not None and the 'limit' keyword in "
+                f"{type(self).__name__}.pct_change are deprecated and will be removed "
+                "in a future version. Either fill in any non-leading NA values prior "
+                "to calling pct_change or specify 'fill_method=None' to not fill NA "
+                "values.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if fill_method is lib.no_default:
+            if limit is lib.no_default and any(
+                grp.isna().values.any() for _, grp in self
+            ):
+                warnings.warn(
+                    "The default fill_method='ffill' in "
+                    f"{type(self).__name__}.pct_change is deprecated and will "
+                    "be removed in a future version. Either fill in any "
+                    "non-leading NA values prior to calling pct_change or "
+                    "specify 'fill_method=None' to not fill NA values.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            fill_method = "ffill"
+        if limit is lib.no_default:
+            limit = None
+
+        if axis is not lib.no_default:
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, "pct_change")
+        else:
+            axis = 0
+
+        # TODO(GH#23918): Remove this conditional for SeriesGroupBy when
+        #  GH#23918 is fixed
+        if freq is not None or axis != 0:
+            f = lambda x: x.pct_change(
+                periods=periods,
+                fill_method=fill_method,
+                limit=limit,
+                freq=freq,
+                axis=axis,
+            )
+            return self._python_apply_general(f, self._selected_obj, is_transform=True)
+
+        if fill_method is None:  # GH30463
+            fill_method = "ffill"
+            limit = 0
+        filled = getattr(self, fill_method)(limit=limit)
+        if self.axis == 0:
+            fill_grp = filled.groupby(self._grouper.codes, group_keys=self.group_keys)
+        else:
+            fill_grp = filled.T.groupby(self._grouper.codes, group_keys=self.group_keys)
+        shifted = fill_grp.shift(periods=periods, freq=freq)
+        if self.axis == 1:
+            shifted = shifted.T
+        return (filled / shifted) - 1
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def head(self, n: int = 5) -> NDFrameT:
+        """
+        Return first n rows of each group.
+
+        Similar to ``.apply(lambda x: x.head(n))``, but it returns a subset of rows
+        from the original DataFrame with original index and order preserved
+        (``as_index`` flag is ignored).
+
+        Parameters
+        ----------
+        n : int
+            If positive: number of entries to include from start of each group.
+            If negative: number of entries to exclude from end of each group.
+
+        Returns
+        -------
+        Series or DataFrame
+            Subset of original Series or DataFrame as determined by n.
+        %(see_also)s
+        Examples
+        --------
+
+        >>> df = pd.DataFrame([[1, 2], [1, 4], [5, 6]],
+        ...                   columns=['A', 'B'])
+        >>> df.groupby('A').head(1)
+           A  B
+        0  1  2
+        2  5  6
+        >>> df.groupby('A').head(-1)
+           A  B
+        0  1  2
+        """
+        mask = self._make_mask_from_positional_indexer(slice(None, n))
+        return self._mask_selected_obj(mask)
+
+    @final
+    @Substitution(name="groupby")
+    @Substitution(see_also=_common_see_also)
+    def tail(self, n: int = 5) -> NDFrameT:
+        """
+        Return last n rows of each group.
+
+        Similar to ``.apply(lambda x: x.tail(n))``, but it returns a subset of rows
+        from the original DataFrame with original index and order preserved
+        (``as_index`` flag is ignored).
+
+        Parameters
+        ----------
+        n : int
+            If positive: number of entries to include from end of each group.
+            If negative: number of entries to exclude from start of each group.
+
+        Returns
+        -------
+        Series or DataFrame
+            Subset of original Series or DataFrame as determined by n.
+        %(see_also)s
+        Examples
+        --------
+
+        >>> df = pd.DataFrame([['a', 1], ['a', 2], ['b', 1], ['b', 2]],
+        ...                   columns=['A', 'B'])
+        >>> df.groupby('A').tail(1)
+           A  B
+        1  a  2
+        3  b  2
+        >>> df.groupby('A').tail(-1)
+           A  B
+        1  a  2
+        3  b  2
+        """
+        if n:
+            mask = self._make_mask_from_positional_indexer(slice(-n, None))
+        else:
+            mask = self._make_mask_from_positional_indexer([])
+
+        return self._mask_selected_obj(mask)
+
+    @final
+    def _mask_selected_obj(self, mask: npt.NDArray[np.bool_]) -> NDFrameT:
+        """
+        Return _selected_obj with mask applied to the correct axis.
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool]
+            Boolean mask to apply.
+
+        Returns
+        -------
+        Series or DataFrame
+            Filtered _selected_obj.
+        """
+        ids = self._grouper.group_info[0]
+        mask = mask & (ids != -1)
+
+        if self.axis == 0:
+            return self._selected_obj[mask]
+        else:
+            return self._selected_obj.iloc[:, mask]
+
+    @final
+    def _reindex_output(
+        self,
+        output: OutputFrameOrSeries,
+        fill_value: Scalar = np.nan,
+        qs: npt.NDArray[np.float64] | None = None,
+        method: str | None = None,
+    ) -> OutputFrameOrSeries:
+        """
+        If we have categorical groupers, then we might want to make sure that
+        we have a fully re-indexed output to the levels. This means expanding
+        the output space to accommodate all values in the cartesian product of
+        our groups, regardless of whether they were observed in the data or
+        not. This will expand the output space if there are missing groups.
+
+        The method returns early without modifying the input if the number of
+        groupings is less than 2, self.observed == True or none of the groupers
+        are categorical.
+
+        Parameters
+        ----------
+        output : Series or DataFrame
+            Object resulting from grouping and applying an operation.
+        fill_value : scalar, default np.nan
+            Value to use for unobserved categories if self.observed is False.
+        qs : np.ndarray[float64] or None, default None
+            quantile values, only relevant for quantile.
+
+        Returns
+        -------
+        Series or DataFrame
+            Object (potentially) re-indexed to include all possible groups.
+        """
+        groupings = self._grouper.groupings
+        if len(groupings) == 1:
+            return output
+
+        # if we only care about the observed values
+        # we are done
+        elif self.observed:
+            return output
+
+        # reindexing only applies to a Categorical grouper
+        elif not any(
+            isinstance(ping.grouping_vector, (Categorical, CategoricalIndex))
+            for ping in groupings
+        ):
+            return output
+
+        levels_list = [ping._group_index for ping in groupings]
+        names = self._grouper.names
+        if qs is not None:
+            # error: Argument 1 to "append" of "list" has incompatible type
+            # "ndarray[Any, dtype[floating[_64Bit]]]"; expected "Index"
+            levels_list.append(qs)  # type: ignore[arg-type]
+            names = names + [None]
+        index = MultiIndex.from_product(levels_list, names=names)
+        if self.sort:
+            index = index.sort_values()
+
+        if self.as_index:
+            # Always holds for SeriesGroupBy unless GH#36507 is implemented
+            d = {
+                self.obj._get_axis_name(self.axis): index,
+                "copy": False,
+                "fill_value": fill_value,
+            }
+            if using_string_dtype() and method == "sum":
+                if isinstance(output, Series) and isinstance(output.dtype, StringDtype):
+                    d["fill_value"] = ""
+                    return output.reindex(**d)  # type: ignore[return-value, arg-type]
+                elif isinstance(output, DataFrame) and any(
+                    isinstance(dtype, StringDtype) for dtype in output.dtypes
+                ):
+                    orig_dtypes = output.dtypes
+                    indices = np.nonzero(output.dtypes == "string")[0]
+                    for idx in indices:
+                        output.isetitem(idx, output.iloc[:, idx].astype(object))
+                    output = output.reindex(**d)  # type: ignore[assignment, arg-type]
+                    for idx in indices:
+                        col = output.iloc[:, idx]
+                        output.isetitem(
+                            idx, col.mask(col == 0, "").astype(orig_dtypes.iloc[idx])
+                        )
+                    return output  # type: ignore[return-value]
+            return output.reindex(**d)  # type: ignore[arg-type]
+
+        # GH 13204
+        # Here, the categorical in-axis groupers, which need to be fully
+        # expanded, are columns in `output`. An idea is to do:
+        # output = output.set_index(self._grouper.names)
+        #                .reindex(index).reset_index()
+        # but special care has to be taken because of possible not-in-axis
+        # groupers.
+        # So, we manually select and drop the in-axis grouper columns,
+        # reindex `output`, and then reset the in-axis grouper columns.
+
+        # Select in-axis groupers
+        in_axis_grps = [
+            (i, ping.name) for (i, ping) in enumerate(groupings) if ping.in_axis
+        ]
+        if len(in_axis_grps) > 0:
+            g_nums, g_names = zip(*in_axis_grps)
+            output = output.drop(labels=list(g_names), axis=1)
+
+        # Set a temp index and reindex (possibly expanding)
+        output = output.set_index(self._grouper.result_index).reindex(
+            index, copy=False, fill_value=fill_value
+        )
+
+        # Reset in-axis grouper columns
+        # (using level numbers `g_nums` because level names may not be unique)
+        if len(in_axis_grps) > 0:
+            output = output.reset_index(level=g_nums)
+
+        return output.reset_index(drop=True)
+
+    @final
+    def sample(
+        self,
+        n: int | None = None,
+        frac: float | None = None,
+        replace: bool = False,
+        weights: Sequence | Series | None = None,
+        random_state: RandomState | None = None,
+    ):
+        """
+        Return a random sample of items from each group.
+
+        You can use `random_state` for reproducibility.
+
+        Parameters
+        ----------
+        n : int, optional
+            Number of items to return for each group. Cannot be used with
+            `frac` and must be no larger than the smallest group unless
+            `replace` is True. Default is one if `frac` is None.
+        frac : float, optional
+            Fraction of items to return. Cannot be used with `n`.
+        replace : bool, default False
+            Allow or disallow sampling of the same row more than once.
+        weights : list-like, optional
+            Default None results in equal probability weighting.
+            If passed a list-like then values must have the same length as
+            the underlying DataFrame or Series object and will be used as
+            sampling probabilities after normalization within each group.
+            Values must be non-negative with at least one positive element
+            within each group.
+        random_state : int, array-like, BitGenerator, np.random.RandomState, np.random.Generator, optional
+            If int, array-like, or BitGenerator, seed for random number generator.
+            If np.random.RandomState or np.random.Generator, use as given.
+
+            .. versionchanged:: 1.4.0
+
+                np.random.Generator objects now accepted
+
+        Returns
+        -------
+        Series or DataFrame
+            A new object of same type as caller containing items randomly
+            sampled within each group from the caller object.
+
+        See Also
+        --------
+        DataFrame.sample: Generate random samples from a DataFrame object.
+        numpy.random.choice: Generate a random sample from a given 1-D numpy
+            array.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame(
+        ...     {"a": ["red"] * 2 + ["blue"] * 2 + ["black"] * 2, "b": range(6)}
+        ... )
+        >>> df
+               a  b
+        0    red  0
+        1    red  1
+        2   blue  2
+        3   blue  3
+        4  black  4
+        5  black  5
+
+        Select one row at random for each distinct value in column a. The
+        `random_state` argument can be used to guarantee reproducibility:
+
+        >>> df.groupby("a").sample(n=1, random_state=1)
+               a  b
+        4  black  4
+        2   blue  2
+        1    red  1
+
+        Set `frac` to sample fixed proportions rather than counts:
+
+        >>> df.groupby("a")["b"].sample(frac=0.5, random_state=2)
+        5    5
+        2    2
+        0    0
+        Name: b, dtype: int64
+
+        Control sample probabilities within groups by setting weights:
+
+        >>> df.groupby("a").sample(
+        ...     n=1,
+        ...     weights=[1, 1, 1, 0, 0, 1],
+        ...     random_state=1,
+        ... )
+               a  b
+        5  black  5
+        2   blue  2
+        0    red  0
+        """  # noqa: E501
+        if self._selected_obj.empty:
+            # GH48459 prevent ValueError when object is empty
+            return self._selected_obj
+        size = sample.process_sampling_size(n, frac, replace)
+        if weights is not None:
+            weights_arr = sample.preprocess_weights(
+                self._selected_obj, weights, axis=self.axis
+            )
+
+        random_state = com.random_state(random_state)
+
+        group_iterator = self._grouper.get_iterator(self._selected_obj, self.axis)
+
+        sampled_indices = []
+        for labels, obj in group_iterator:
+            grp_indices = self.indices[labels]
+            group_size = len(grp_indices)
+            if size is not None:
+                sample_size = size
+            else:
+                assert frac is not None
+                sample_size = round(frac * group_size)
+
+            grp_sample = sample.sample(
+                group_size,
+                size=sample_size,
+                replace=replace,
+                weights=None if weights is None else weights_arr[grp_indices],
+                random_state=random_state,
+            )
+            sampled_indices.append(grp_indices[grp_sample])
+
+        sampled_indices = np.concatenate(sampled_indices)
+        return self._selected_obj.take(sampled_indices, axis=self.axis)
+
+    def _idxmax_idxmin(
+        self,
+        how: Literal["idxmax", "idxmin"],
+        ignore_unobserved: bool = False,
+        axis: Axis | None | lib.NoDefault = lib.no_default,
+        skipna: bool = True,
+        numeric_only: bool = False,
+    ) -> NDFrameT:
+        """Compute idxmax/idxmin.
+
+        Parameters
+        ----------
+        how : {'idxmin', 'idxmax'}
+            Whether to compute idxmin or idxmax.
+        axis : {{0 or 'index', 1 or 'columns'}}, default None
+            The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+            If axis is not provided, grouper's axis is used.
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+        skipna : bool, default True
+            Exclude NA/null values. If an entire row/column is NA, the result
+            will be NA.
+        ignore_unobserved : bool, default False
+            When True and an unobserved group is encountered, do not raise. This used
+            for transform where unobserved groups do not play an impact on the result.
+
+        Returns
+        -------
+        Series or DataFrame
+            idxmax or idxmin for the groupby operation.
+        """
+        if axis is not lib.no_default:
+            if axis is None:
+                axis = self.axis
+            axis = self.obj._get_axis_number(axis)
+            self._deprecate_axis(axis, how)
+        else:
+            axis = self.axis
+
+        if not self.observed and any(
+            ping._passed_categorical for ping in self._grouper.groupings
+        ):
+            expected_len = np.prod(
+                [len(ping._group_index) for ping in self._grouper.groupings]
+            )
+            if len(self._grouper.groupings) == 1:
+                result_len = len(self._grouper.groupings[0].grouping_vector.unique())
+            else:
+                # result_index only contains observed groups in this case
+                result_len = len(self._grouper.result_index)
+            assert result_len <= expected_len
+            has_unobserved = result_len < expected_len
+
+            raise_err: bool | np.bool_ = not ignore_unobserved and has_unobserved
+            # Only raise an error if there are columns to compute; otherwise we return
+            # an empty DataFrame with an index (possibly including unobserved) but no
+            # columns
+            data = self._obj_with_exclusions
+            if raise_err and isinstance(data, DataFrame):
+                if numeric_only:
+                    data = data._get_numeric_data()
+                raise_err = len(data.columns) > 0
+
+            if raise_err:
+                raise ValueError(
+                    f"Can't get {how} of an empty group due to unobserved categories. "
+                    "Specify observed=True in groupby instead."
+                )
+        elif not skipna:
+            if self._obj_with_exclusions.isna().any(axis=None):
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.{how} with all-NA "
+                    "values, or any-NA and skipna=False, is deprecated. In a future "
+                    "version this will raise ValueError",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        if axis == 1:
+            try:
+
+                def func(df):
+                    method = getattr(df, how)
+                    return method(axis=axis, skipna=skipna, numeric_only=numeric_only)
+
+                func.__name__ = how
+                result = self._python_apply_general(
+                    func, self._obj_with_exclusions, not_indexed_same=True
+                )
+            except ValueError as err:
+                name = "argmax" if how == "idxmax" else "argmin"
+                if f"attempt to get {name} of an empty sequence" in str(err):
+                    raise ValueError(
+                        f"Can't get {how} of an empty group due to unobserved "
+                        "categories. Specify observed=True in groupby instead."
+                    ) from None
+                raise
+            return result
+
+        result = self._agg_general(
+            numeric_only=numeric_only,
+            min_count=1,
+            alias=how,
+            skipna=skipna,
+        )
+        return result
+
+    def _wrap_idxmax_idxmin(self, res: NDFrameT) -> NDFrameT:
+        index = self.obj._get_axis(self.axis)
+        if res.size == 0:
+            result = res.astype(index.dtype)
+        else:
+            if isinstance(index, MultiIndex):
+                index = index.to_flat_index()
+            values = res._values
+            assert isinstance(values, np.ndarray)
+            na_value = na_value_for_dtype(index.dtype, compat=False)
+            if isinstance(res, Series):
+                # mypy: expression has type "Series", variable has type "NDFrameT"
+                result = res._constructor(  # type: ignore[assignment]
+                    index.array.take(values, allow_fill=True, fill_value=na_value),
+                    index=res.index,
+                    name=res.name,
+                )
+            else:
+                data = {}
+                for k, column_values in enumerate(values.T):
+                    data[k] = index.array.take(
+                        column_values, allow_fill=True, fill_value=na_value
+                    )
+                result = self.obj._constructor(data, index=res.index)
+                result.columns = res.columns
+        return result
+
+
+@doc(GroupBy)
+def get_groupby(
+    obj: NDFrame,
+    by: _KeysArgType | None = None,
+    axis: AxisInt = 0,
+    grouper: ops.BaseGrouper | None = None,
+    group_keys: bool = True,
+) -> GroupBy:
+    klass: type[GroupBy]
+    if isinstance(obj, Series):
+        from pandas.core.groupby.generic import SeriesGroupBy
+
+        klass = SeriesGroupBy
+    elif isinstance(obj, DataFrame):
+        from pandas.core.groupby.generic import DataFrameGroupBy
+
+        klass = DataFrameGroupBy
+    else:  # pragma: no cover
+        raise TypeError(f"invalid type: {obj}")
+
+    return klass(
+        obj=obj,
+        keys=by,
+        axis=axis,
+        grouper=grouper,
+        group_keys=group_keys,
+    )
+
+
+def _insert_quantile_level(idx: Index, qs: npt.NDArray[np.float64]) -> MultiIndex:
+    """
+    Insert the sequence 'qs' of quantiles as the inner-most level of a MultiIndex.
+
+    The quantile level in the MultiIndex is a repeated copy of 'qs'.
+
+    Parameters
+    ----------
+    idx : Index
+    qs : np.ndarray[float64]
+
+    Returns
+    -------
+    MultiIndex
+    """
+    nqs = len(qs)
+    lev_codes, lev = Index(qs).factorize()
+    lev_codes = coerce_indexer_dtype(lev_codes, lev)
+
+    if idx._is_multi:
+        idx = cast(MultiIndex, idx)
+        levels = list(idx.levels) + [lev]
+        codes = [np.repeat(x, nqs) for x in idx.codes] + [np.tile(lev_codes, len(idx))]
+        mi = MultiIndex(levels=levels, codes=codes, names=idx.names + [None])
+    else:
+        nidx = len(idx)
+        idx_codes = coerce_indexer_dtype(np.arange(nidx), idx)
+        levels = [idx, lev]
+        codes = [np.repeat(idx_codes, nqs), np.tile(lev_codes, nidx)]
+        mi = MultiIndex(levels=levels, codes=codes, names=[idx.name, None])
+
+    return mi
+
+
+# GH#7155
+_apply_groupings_depr = (
+    "{}.{} operated on the grouping columns. This behavior is deprecated, "
+    "and in a future version of pandas the grouping columns will be excluded "
+    "from the operation. Either pass `include_groups=False` to exclude the "
+    "groupings or explicitly select the grouping columns after groupby to silence "
+    "this warning."
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/grouper.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/grouper.py
new file mode 100644
index 0000000000000000000000000000000000000000..4bf2e8b90a0b09146f41975aa801929c77fd5fce
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/grouper.py
@@ -0,0 +1,1102 @@
+"""
+Provide user facing operators for doing the split part of the
+split-apply-combine paradigm.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    final,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import (
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs import lib
+from pandas._libs.tslibs import OutOfBoundsDatetime
+from pandas.errors import InvalidIndexError
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_list_like,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+from pandas.core import algorithms
+from pandas.core.arrays import (
+    Categorical,
+    ExtensionArray,
+)
+import pandas.core.common as com
+from pandas.core.frame import DataFrame
+from pandas.core.groupby import ops
+from pandas.core.groupby.categorical import recode_for_groupby
+from pandas.core.indexes.api import (
+    CategoricalIndex,
+    Index,
+    MultiIndex,
+)
+from pandas.core.series import Series
+
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        Axis,
+        NDFrameT,
+        npt,
+    )
+
+    from pandas.core.generic import NDFrame
+
+
+class Grouper:
+    """
+    A Grouper allows the user to specify a groupby instruction for an object.
+
+    This specification will select a column via the key parameter, or if the
+    level and/or axis parameters are given, a level of the index of the target
+    object.
+
+    If `axis` and/or `level` are passed as keywords to both `Grouper` and
+    `groupby`, the values passed to `Grouper` take precedence.
+
+    Parameters
+    ----------
+    key : str, defaults to None
+        Groupby key, which selects the grouping column of the target.
+    level : name/number, defaults to None
+        The level for the target index.
+    freq : str / frequency object, defaults to None
+        This will groupby the specified frequency if the target selection
+        (via key or level) is a datetime-like object. For full specification
+        of available frequencies, please see `here
+        `_.
+    axis : str, int, defaults to 0
+        Number/name of the axis.
+    sort : bool, default to False
+        Whether to sort the resulting labels.
+    closed : {'left' or 'right'}
+        Closed end of interval. Only when `freq` parameter is passed.
+    label : {'left' or 'right'}
+        Interval boundary to use for labeling.
+        Only when `freq` parameter is passed.
+    convention : {'start', 'end', 'e', 's'}
+        If grouper is PeriodIndex and `freq` parameter is passed.
+
+    origin : Timestamp or str, default 'start_day'
+        The timestamp on which to adjust the grouping. The timezone of origin must
+        match the timezone of the index.
+        If string, must be one of the following:
+
+        - 'epoch': `origin` is 1970-01-01
+        - 'start': `origin` is the first value of the timeseries
+        - 'start_day': `origin` is the first day at midnight of the timeseries
+
+        - 'end': `origin` is the last value of the timeseries
+        - 'end_day': `origin` is the ceiling midnight of the last day
+
+        .. versionadded:: 1.3.0
+
+    offset : Timedelta or str, default is None
+        An offset timedelta added to the origin.
+
+    dropna : bool, default True
+        If True, and if group keys contain NA values, NA values together with
+        row/column will be dropped. If False, NA values will also be treated as
+        the key in groups.
+
+    Returns
+    -------
+    Grouper or pandas.api.typing.TimeGrouper
+        A TimeGrouper is returned if ``freq`` is not ``None``. Otherwise, a Grouper
+        is returned.
+
+    Examples
+    --------
+    ``df.groupby(pd.Grouper(key="Animal"))`` is equivalent to ``df.groupby('Animal')``
+
+    >>> df = pd.DataFrame(
+    ...     {
+    ...         "Animal": ["Falcon", "Parrot", "Falcon", "Falcon", "Parrot"],
+    ...         "Speed": [100, 5, 200, 300, 15],
+    ...     }
+    ... )
+    >>> df
+       Animal  Speed
+    0  Falcon    100
+    1  Parrot      5
+    2  Falcon    200
+    3  Falcon    300
+    4  Parrot     15
+    >>> df.groupby(pd.Grouper(key="Animal")).mean()
+            Speed
+    Animal
+    Falcon  200.0
+    Parrot   10.0
+
+    Specify a resample operation on the column 'Publish date'
+
+    >>> df = pd.DataFrame(
+    ...    {
+    ...        "Publish date": [
+    ...             pd.Timestamp("2000-01-02"),
+    ...             pd.Timestamp("2000-01-02"),
+    ...             pd.Timestamp("2000-01-09"),
+    ...             pd.Timestamp("2000-01-16")
+    ...         ],
+    ...         "ID": [0, 1, 2, 3],
+    ...         "Price": [10, 20, 30, 40]
+    ...     }
+    ... )
+    >>> df
+      Publish date  ID  Price
+    0   2000-01-02   0     10
+    1   2000-01-02   1     20
+    2   2000-01-09   2     30
+    3   2000-01-16   3     40
+    >>> df.groupby(pd.Grouper(key="Publish date", freq="1W")).mean()
+                   ID  Price
+    Publish date
+    2000-01-02    0.5   15.0
+    2000-01-09    2.0   30.0
+    2000-01-16    3.0   40.0
+
+    If you want to adjust the start of the bins based on a fixed timestamp:
+
+    >>> start, end = '2000-10-01 23:30:00', '2000-10-02 00:30:00'
+    >>> rng = pd.date_range(start, end, freq='7min')
+    >>> ts = pd.Series(np.arange(len(rng)) * 3, index=rng)
+    >>> ts
+    2000-10-01 23:30:00     0
+    2000-10-01 23:37:00     3
+    2000-10-01 23:44:00     6
+    2000-10-01 23:51:00     9
+    2000-10-01 23:58:00    12
+    2000-10-02 00:05:00    15
+    2000-10-02 00:12:00    18
+    2000-10-02 00:19:00    21
+    2000-10-02 00:26:00    24
+    Freq: 7min, dtype: int64
+
+    >>> ts.groupby(pd.Grouper(freq='17min')).sum()
+    2000-10-01 23:14:00     0
+    2000-10-01 23:31:00     9
+    2000-10-01 23:48:00    21
+    2000-10-02 00:05:00    54
+    2000-10-02 00:22:00    24
+    Freq: 17min, dtype: int64
+
+    >>> ts.groupby(pd.Grouper(freq='17min', origin='epoch')).sum()
+    2000-10-01 23:18:00     0
+    2000-10-01 23:35:00    18
+    2000-10-01 23:52:00    27
+    2000-10-02 00:09:00    39
+    2000-10-02 00:26:00    24
+    Freq: 17min, dtype: int64
+
+    >>> ts.groupby(pd.Grouper(freq='17min', origin='2000-01-01')).sum()
+    2000-10-01 23:24:00     3
+    2000-10-01 23:41:00    15
+    2000-10-01 23:58:00    45
+    2000-10-02 00:15:00    45
+    Freq: 17min, dtype: int64
+
+    If you want to adjust the start of the bins with an `offset` Timedelta, the two
+    following lines are equivalent:
+
+    >>> ts.groupby(pd.Grouper(freq='17min', origin='start')).sum()
+    2000-10-01 23:30:00     9
+    2000-10-01 23:47:00    21
+    2000-10-02 00:04:00    54
+    2000-10-02 00:21:00    24
+    Freq: 17min, dtype: int64
+
+    >>> ts.groupby(pd.Grouper(freq='17min', offset='23h30min')).sum()
+    2000-10-01 23:30:00     9
+    2000-10-01 23:47:00    21
+    2000-10-02 00:04:00    54
+    2000-10-02 00:21:00    24
+    Freq: 17min, dtype: int64
+
+    To replace the use of the deprecated `base` argument, you can now use `offset`,
+    in this example it is equivalent to have `base=2`:
+
+    >>> ts.groupby(pd.Grouper(freq='17min', offset='2min')).sum()
+    2000-10-01 23:16:00     0
+    2000-10-01 23:33:00     9
+    2000-10-01 23:50:00    36
+    2000-10-02 00:07:00    39
+    2000-10-02 00:24:00    24
+    Freq: 17min, dtype: int64
+    """
+
+    sort: bool
+    dropna: bool
+    _gpr_index: Index | None
+    _grouper: Index | None
+
+    _attributes: tuple[str, ...] = ("key", "level", "freq", "axis", "sort", "dropna")
+
+    def __new__(cls, *args, **kwargs):
+        if kwargs.get("freq") is not None:
+            from pandas.core.resample import TimeGrouper
+
+            cls = TimeGrouper
+        return super().__new__(cls)
+
+    def __init__(
+        self,
+        key=None,
+        level=None,
+        freq=None,
+        axis: Axis | lib.NoDefault = lib.no_default,
+        sort: bool = False,
+        dropna: bool = True,
+    ) -> None:
+        if type(self) is Grouper:
+            # i.e. not TimeGrouper
+            if axis is not lib.no_default:
+                warnings.warn(
+                    "Grouper axis keyword is deprecated and will be removed in a "
+                    "future version. To group on axis=1, use obj.T.groupby(...) "
+                    "instead",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                axis = 0
+        if axis is lib.no_default:
+            axis = 0
+
+        self.key = key
+        self.level = level
+        self.freq = freq
+        self.axis = axis
+        self.sort = sort
+        self.dropna = dropna
+
+        self._grouper_deprecated = None
+        self._indexer_deprecated: npt.NDArray[np.intp] | None = None
+        self._obj_deprecated = None
+        self._gpr_index = None
+        self.binner = None
+        self._grouper = None
+        self._indexer: npt.NDArray[np.intp] | None = None
+
+    def _get_grouper(
+        self, obj: NDFrameT, validate: bool = True
+    ) -> tuple[ops.BaseGrouper, NDFrameT]:
+        """
+        Parameters
+        ----------
+        obj : Series or DataFrame
+        validate : bool, default True
+            if True, validate the grouper
+
+        Returns
+        -------
+        a tuple of grouper, obj (possibly sorted)
+        """
+        obj, _, _ = self._set_grouper(obj)
+        grouper, _, obj = get_grouper(
+            obj,
+            [self.key],
+            axis=self.axis,
+            level=self.level,
+            sort=self.sort,
+            validate=validate,
+            dropna=self.dropna,
+        )
+        # Without setting this, subsequent lookups to .groups raise
+        # error: Incompatible types in assignment (expression has type "BaseGrouper",
+        # variable has type "None")
+        self._grouper_deprecated = grouper  # type: ignore[assignment]
+
+        return grouper, obj
+
+    def _set_grouper(
+        self, obj: NDFrameT, sort: bool = False, *, gpr_index: Index | None = None
+    ) -> tuple[NDFrameT, Index, npt.NDArray[np.intp] | None]:
+        """
+        given an object and the specifications, setup the internal grouper
+        for this particular specification
+
+        Parameters
+        ----------
+        obj : Series or DataFrame
+        sort : bool, default False
+            whether the resulting grouper should be sorted
+        gpr_index : Index or None, default None
+
+        Returns
+        -------
+        NDFrame
+        Index
+        np.ndarray[np.intp] | None
+        """
+        assert obj is not None
+
+        if self.key is not None and self.level is not None:
+            raise ValueError("The Grouper cannot specify both a key and a level!")
+
+        # Keep self._grouper value before overriding
+        if self._grouper is None:
+            # TODO: What are we assuming about subsequent calls?
+            self._grouper = gpr_index
+            self._indexer = self._indexer_deprecated
+
+        # the key must be a valid info item
+        if self.key is not None:
+            key = self.key
+            # The 'on' is already defined
+            if getattr(gpr_index, "name", None) == key and isinstance(obj, Series):
+                # Sometimes self._grouper will have been resorted while
+                # obj has not. In this case there is a mismatch when we
+                # call self._grouper.take(obj.index) so we need to undo the sorting
+                # before we call _grouper.take.
+                assert self._grouper is not None
+                if self._indexer is not None:
+                    reverse_indexer = self._indexer.argsort()
+                    unsorted_ax = self._grouper.take(reverse_indexer)
+                    ax = unsorted_ax.take(obj.index)
+                else:
+                    ax = self._grouper.take(obj.index)
+            else:
+                if key not in obj._info_axis:
+                    raise KeyError(f"The grouper name {key} is not found")
+                ax = Index(obj[key], name=key)
+
+        else:
+            ax = obj._get_axis(self.axis)
+            if self.level is not None:
+                level = self.level
+
+                # if a level is given it must be a mi level or
+                # equivalent to the axis name
+                if isinstance(ax, MultiIndex):
+                    level = ax._get_level_number(level)
+                    ax = Index(ax._get_level_values(level), name=ax.names[level])
+
+                else:
+                    if level not in (0, ax.name):
+                        raise ValueError(f"The level {level} is not valid")
+
+        # possibly sort
+        indexer: npt.NDArray[np.intp] | None = None
+        if (self.sort or sort) and not ax.is_monotonic_increasing:
+            # use stable sort to support first, last, nth
+            # TODO: why does putting na_position="first" fix datetimelike cases?
+            indexer = self._indexer_deprecated = ax.array.argsort(
+                kind="mergesort", na_position="first"
+            )
+            ax = ax.take(indexer)
+            obj = obj.take(indexer, axis=self.axis)
+
+        # error: Incompatible types in assignment (expression has type
+        # "NDFrameT", variable has type "None")
+        self._obj_deprecated = obj  # type: ignore[assignment]
+        self._gpr_index = ax
+        return obj, ax, indexer
+
+    @final
+    @property
+    def ax(self) -> Index:
+        warnings.warn(
+            f"{type(self).__name__}.ax is deprecated and will be removed in a "
+            "future version. Use Resampler.ax instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        index = self._gpr_index
+        if index is None:
+            raise ValueError("_set_grouper must be called before ax is accessed")
+        return index
+
+    @final
+    @property
+    def indexer(self):
+        warnings.warn(
+            f"{type(self).__name__}.indexer is deprecated and will be removed "
+            "in a future version. Use Resampler.indexer instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._indexer_deprecated
+
+    @final
+    @property
+    def obj(self):
+        # TODO(3.0): enforcing these deprecations on Grouper should close
+        #  GH#25564, GH#41930
+        warnings.warn(
+            f"{type(self).__name__}.obj is deprecated and will be removed "
+            "in a future version. Use GroupBy.indexer instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._obj_deprecated
+
+    @final
+    @property
+    def grouper(self):
+        warnings.warn(
+            f"{type(self).__name__}.grouper is deprecated and will be removed "
+            "in a future version. Use GroupBy.grouper instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._grouper_deprecated
+
+    @final
+    @property
+    def groups(self):
+        warnings.warn(
+            f"{type(self).__name__}.groups is deprecated and will be removed "
+            "in a future version. Use GroupBy.groups instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        # error: "None" has no attribute "groups"
+        return self._grouper_deprecated.groups  # type: ignore[attr-defined]
+
+    @final
+    def __repr__(self) -> str:
+        attrs_list = (
+            f"{attr_name}={repr(getattr(self, attr_name))}"
+            for attr_name in self._attributes
+            if getattr(self, attr_name) is not None
+        )
+        attrs = ", ".join(attrs_list)
+        cls_name = type(self).__name__
+        return f"{cls_name}({attrs})"
+
+
+@final
+class Grouping:
+    """
+    Holds the grouping information for a single key
+
+    Parameters
+    ----------
+    index : Index
+    grouper :
+    obj : DataFrame or Series
+    name : Label
+    level :
+    observed : bool, default False
+        If we are a Categorical, use the observed values
+    in_axis : if the Grouping is a column in self.obj and hence among
+        Groupby.exclusions list
+    dropna : bool, default True
+        Whether to drop NA groups.
+    uniques : Array-like, optional
+        When specified, will be used for unique values. Enables including empty groups
+        in the result for a BinGrouper. Must not contain duplicates.
+
+    Attributes
+    -------
+    indices : dict
+        Mapping of {group -> index_list}
+    codes : ndarray
+        Group codes
+    group_index : Index or None
+        unique groups
+    groups : dict
+        Mapping of {group -> label_list}
+    """
+
+    _codes: npt.NDArray[np.signedinteger] | None = None
+    _all_grouper: Categorical | None
+    _orig_cats: Index | None
+    _index: Index
+
+    def __init__(
+        self,
+        index: Index,
+        grouper=None,
+        obj: NDFrame | None = None,
+        level=None,
+        sort: bool = True,
+        observed: bool = False,
+        in_axis: bool = False,
+        dropna: bool = True,
+        uniques: ArrayLike | None = None,
+    ) -> None:
+        self.level = level
+        self._orig_grouper = grouper
+        grouping_vector = _convert_grouper(index, grouper)
+        self._all_grouper = None
+        self._orig_cats = None
+        self._index = index
+        self._sort = sort
+        self.obj = obj
+        self._observed = observed
+        self.in_axis = in_axis
+        self._dropna = dropna
+        self._uniques = uniques
+
+        # we have a single grouper which may be a myriad of things,
+        # some of which are dependent on the passing in level
+
+        ilevel = self._ilevel
+        if ilevel is not None:
+            # In extant tests, the new self.grouping_vector matches
+            #  `index.get_level_values(ilevel)` whenever
+            #  mapper is None and isinstance(index, MultiIndex)
+            if isinstance(index, MultiIndex):
+                index_level = index.get_level_values(ilevel)
+            else:
+                index_level = index
+
+            if grouping_vector is None:
+                grouping_vector = index_level
+            else:
+                mapper = grouping_vector
+                grouping_vector = index_level.map(mapper)
+
+        # a passed Grouper like, directly get the grouper in the same way
+        # as single grouper groupby, use the group_info to get codes
+        elif isinstance(grouping_vector, Grouper):
+            # get the new grouper; we already have disambiguated
+            # what key/level refer to exactly, don't need to
+            # check again as we have by this point converted these
+            # to an actual value (rather than a pd.Grouper)
+            assert self.obj is not None  # for mypy
+            newgrouper, newobj = grouping_vector._get_grouper(self.obj, validate=False)
+            self.obj = newobj
+
+            if isinstance(newgrouper, ops.BinGrouper):
+                # TODO: can we unwrap this and get a tighter typing
+                #  for self.grouping_vector?
+                grouping_vector = newgrouper
+            else:
+                # ops.BaseGrouper
+                # TODO: 2023-02-03 no test cases with len(newgrouper.groupings) > 1.
+                #  If that were to occur, would we be throwing out information?
+                # error: Cannot determine type of "grouping_vector"  [has-type]
+                ng = newgrouper.groupings[0].grouping_vector  # type: ignore[has-type]
+                # use Index instead of ndarray so we can recover the name
+                grouping_vector = Index(ng, name=newgrouper.result_index.name)
+
+        elif not isinstance(
+            grouping_vector, (Series, Index, ExtensionArray, np.ndarray)
+        ):
+            # no level passed
+            if getattr(grouping_vector, "ndim", 1) != 1:
+                t = str(type(grouping_vector))
+                raise ValueError(f"Grouper for '{t}' not 1-dimensional")
+
+            grouping_vector = index.map(grouping_vector)
+
+            if not (
+                hasattr(grouping_vector, "__len__")
+                and len(grouping_vector) == len(index)
+            ):
+                grper = pprint_thing(grouping_vector)
+                errmsg = (
+                    "Grouper result violates len(labels) == "
+                    f"len(data)\nresult: {grper}"
+                )
+                raise AssertionError(errmsg)
+
+        if isinstance(grouping_vector, np.ndarray):
+            if grouping_vector.dtype.kind in "mM":
+                # if we have a date/time-like grouper, make sure that we have
+                # Timestamps like
+                # TODO 2022-10-08 we only have one test that gets here and
+                #  values are already in nanoseconds in that case.
+                grouping_vector = Series(grouping_vector).to_numpy()
+        elif isinstance(getattr(grouping_vector, "dtype", None), CategoricalDtype):
+            # a passed Categorical
+            self._orig_cats = grouping_vector.categories
+            grouping_vector, self._all_grouper = recode_for_groupby(
+                grouping_vector, sort, observed
+            )
+
+        self.grouping_vector = grouping_vector
+
+    def __repr__(self) -> str:
+        return f"Grouping({self.name})"
+
+    def __iter__(self) -> Iterator:
+        return iter(self.indices)
+
+    @cache_readonly
+    def _passed_categorical(self) -> bool:
+        dtype = getattr(self.grouping_vector, "dtype", None)
+        return isinstance(dtype, CategoricalDtype)
+
+    @cache_readonly
+    def name(self) -> Hashable:
+        ilevel = self._ilevel
+        if ilevel is not None:
+            return self._index.names[ilevel]
+
+        if isinstance(self._orig_grouper, (Index, Series)):
+            return self._orig_grouper.name
+
+        elif isinstance(self.grouping_vector, ops.BaseGrouper):
+            return self.grouping_vector.result_index.name
+
+        elif isinstance(self.grouping_vector, Index):
+            return self.grouping_vector.name
+
+        # otherwise we have ndarray or ExtensionArray -> no name
+        return None
+
+    @cache_readonly
+    def _ilevel(self) -> int | None:
+        """
+        If necessary, converted index level name to index level position.
+        """
+        level = self.level
+        if level is None:
+            return None
+        if not isinstance(level, int):
+            index = self._index
+            if level not in index.names:
+                raise AssertionError(f"Level {level} not in index")
+            return index.names.index(level)
+        return level
+
+    @property
+    def ngroups(self) -> int:
+        return len(self._group_index)
+
+    @cache_readonly
+    def indices(self) -> dict[Hashable, npt.NDArray[np.intp]]:
+        # we have a list of groupers
+        if isinstance(self.grouping_vector, ops.BaseGrouper):
+            return self.grouping_vector.indices
+
+        values = Categorical(self.grouping_vector)
+        return values._reverse_indexer()
+
+    @property
+    def codes(self) -> npt.NDArray[np.signedinteger]:
+        return self._codes_and_uniques[0]
+
+    @cache_readonly
+    def _group_arraylike(self) -> ArrayLike:
+        """
+        Analogous to result_index, but holding an ArrayLike to ensure
+        we can retain ExtensionDtypes.
+        """
+        if self._all_grouper is not None:
+            # retain dtype for categories, including unobserved ones
+            return self._result_index._values
+
+        elif self._passed_categorical:
+            return self._group_index._values
+
+        return self._codes_and_uniques[1]
+
+    @property
+    def group_arraylike(self) -> ArrayLike:
+        """
+        Analogous to result_index, but holding an ArrayLike to ensure
+        we can retain ExtensionDtypes.
+        """
+        warnings.warn(
+            "group_arraylike is deprecated and will be removed in a future "
+            "version of pandas",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._group_arraylike
+
+    @cache_readonly
+    def _result_index(self) -> Index:
+        # result_index retains dtype for categories, including unobserved ones,
+        #  which group_index does not
+        if self._all_grouper is not None:
+            group_idx = self._group_index
+            assert isinstance(group_idx, CategoricalIndex)
+            cats = self._orig_cats
+            # set_categories is dynamically added
+            return group_idx.set_categories(cats)  # type: ignore[attr-defined]
+        return self._group_index
+
+    @property
+    def result_index(self) -> Index:
+        warnings.warn(
+            "result_index is deprecated and will be removed in a future "
+            "version of pandas",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._result_index
+
+    @cache_readonly
+    def _group_index(self) -> Index:
+        codes, uniques = self._codes_and_uniques
+        if not self._dropna and self._passed_categorical:
+            assert isinstance(uniques, Categorical)
+            if self._sort and (codes == len(uniques)).any():
+                # Add NA value on the end when sorting
+                uniques = Categorical.from_codes(
+                    np.append(uniques.codes, [-1]), uniques.categories, validate=False
+                )
+            elif len(codes) > 0:
+                # Need to determine proper placement of NA value when not sorting
+                cat = self.grouping_vector
+                na_idx = (cat.codes < 0).argmax()
+                if cat.codes[na_idx] < 0:
+                    # count number of unique codes that comes before the nan value
+                    na_unique_idx = algorithms.nunique_ints(cat.codes[:na_idx])
+                    new_codes = np.insert(uniques.codes, na_unique_idx, -1)
+                    uniques = Categorical.from_codes(
+                        new_codes, uniques.categories, validate=False
+                    )
+        return Index._with_infer(uniques, name=self.name)
+
+    @property
+    def group_index(self) -> Index:
+        warnings.warn(
+            "group_index is deprecated and will be removed in a future "
+            "version of pandas",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._group_index
+
+    @cache_readonly
+    def _codes_and_uniques(self) -> tuple[npt.NDArray[np.signedinteger], ArrayLike]:
+        uniques: ArrayLike
+        if self._passed_categorical:
+            # we make a CategoricalIndex out of the cat grouper
+            # preserving the categories / ordered attributes;
+            # doesn't (yet - GH#46909) handle dropna=False
+            cat = self.grouping_vector
+            categories = cat.categories
+
+            if self._observed:
+                ucodes = algorithms.unique1d(cat.codes)
+                ucodes = ucodes[ucodes != -1]
+                if self._sort:
+                    ucodes = np.sort(ucodes)
+            else:
+                ucodes = np.arange(len(categories))
+
+            uniques = Categorical.from_codes(
+                codes=ucodes, categories=categories, ordered=cat.ordered, validate=False
+            )
+
+            codes = cat.codes
+            if not self._dropna:
+                na_mask = codes < 0
+                if np.any(na_mask):
+                    if self._sort:
+                        # Replace NA codes with `largest code + 1`
+                        na_code = len(categories)
+                        codes = np.where(na_mask, na_code, codes)
+                    else:
+                        # Insert NA code into the codes based on first appearance
+                        # A negative code must exist, no need to check codes[na_idx] < 0
+                        na_idx = na_mask.argmax()
+                        # count number of unique codes that comes before the nan value
+                        na_code = algorithms.nunique_ints(codes[:na_idx])
+                        codes = np.where(codes >= na_code, codes + 1, codes)
+                        codes = np.where(na_mask, na_code, codes)
+
+            if not self._observed:
+                uniques = uniques.reorder_categories(self._orig_cats)
+
+            return codes, uniques
+
+        elif isinstance(self.grouping_vector, ops.BaseGrouper):
+            # we have a list of groupers
+            codes = self.grouping_vector.codes_info
+            uniques = self.grouping_vector.result_index._values
+        elif self._uniques is not None:
+            # GH#50486 Code grouping_vector using _uniques; allows
+            # including uniques that are not present in grouping_vector.
+            cat = Categorical(self.grouping_vector, categories=self._uniques)
+            codes = cat.codes
+            uniques = self._uniques
+        else:
+            # GH35667, replace dropna=False with use_na_sentinel=False
+            # error: Incompatible types in assignment (expression has type "Union[
+            # ndarray[Any, Any], Index]", variable has type "Categorical")
+            codes, uniques = algorithms.factorize(  # type: ignore[assignment]
+                self.grouping_vector, sort=self._sort, use_na_sentinel=self._dropna
+            )
+        return codes, uniques
+
+    @cache_readonly
+    def groups(self) -> dict[Hashable, np.ndarray]:
+        cats = Categorical.from_codes(self.codes, self._group_index, validate=False)
+        return self._index.groupby(cats)
+
+
+def get_grouper(
+    obj: NDFrameT,
+    key=None,
+    axis: Axis = 0,
+    level=None,
+    sort: bool = True,
+    observed: bool = False,
+    validate: bool = True,
+    dropna: bool = True,
+) -> tuple[ops.BaseGrouper, frozenset[Hashable], NDFrameT]:
+    """
+    Create and return a BaseGrouper, which is an internal
+    mapping of how to create the grouper indexers.
+    This may be composed of multiple Grouping objects, indicating
+    multiple groupers
+
+    Groupers are ultimately index mappings. They can originate as:
+    index mappings, keys to columns, functions, or Groupers
+
+    Groupers enable local references to axis,level,sort, while
+    the passed in axis, level, and sort are 'global'.
+
+    This routine tries to figure out what the passing in references
+    are and then creates a Grouping for each one, combined into
+    a BaseGrouper.
+
+    If observed & we have a categorical grouper, only show the observed
+    values.
+
+    If validate, then check for key/level overlaps.
+
+    """
+    group_axis = obj._get_axis(axis)
+
+    # validate that the passed single level is compatible with the passed
+    # axis of the object
+    if level is not None:
+        # TODO: These if-block and else-block are almost same.
+        # MultiIndex instance check is removable, but it seems that there are
+        # some processes only for non-MultiIndex in else-block,
+        # eg. `obj.index.name != level`. We have to consider carefully whether
+        # these are applicable for MultiIndex. Even if these are applicable,
+        # we need to check if it makes no side effect to subsequent processes
+        # on the outside of this condition.
+        # (GH 17621)
+        if isinstance(group_axis, MultiIndex):
+            if is_list_like(level) and len(level) == 1:
+                level = level[0]
+
+            if key is None and is_scalar(level):
+                # Get the level values from group_axis
+                key = group_axis.get_level_values(level)
+                level = None
+
+        else:
+            # allow level to be a length-one list-like object
+            # (e.g., level=[0])
+            # GH 13901
+            if is_list_like(level):
+                nlevels = len(level)
+                if nlevels == 1:
+                    level = level[0]
+                elif nlevels == 0:
+                    raise ValueError("No group keys passed!")
+                else:
+                    raise ValueError("multiple levels only valid with MultiIndex")
+
+            if isinstance(level, str):
+                if obj._get_axis(axis).name != level:
+                    raise ValueError(
+                        f"level name {level} is not the name "
+                        f"of the {obj._get_axis_name(axis)}"
+                    )
+            elif level > 0 or level < -1:
+                raise ValueError("level > 0 or level < -1 only valid with MultiIndex")
+
+            # NOTE: `group_axis` and `group_axis.get_level_values(level)`
+            # are same in this section.
+            level = None
+            key = group_axis
+
+    # a passed-in Grouper, directly convert
+    if isinstance(key, Grouper):
+        grouper, obj = key._get_grouper(obj, validate=False)
+        if key.key is None:
+            return grouper, frozenset(), obj
+        else:
+            return grouper, frozenset({key.key}), obj
+
+    # already have a BaseGrouper, just return it
+    elif isinstance(key, ops.BaseGrouper):
+        return key, frozenset(), obj
+
+    if not isinstance(key, list):
+        keys = [key]
+        match_axis_length = False
+    else:
+        keys = key
+        match_axis_length = len(keys) == len(group_axis)
+
+    # what are we after, exactly?
+    any_callable = any(callable(g) or isinstance(g, dict) for g in keys)
+    any_groupers = any(isinstance(g, (Grouper, Grouping)) for g in keys)
+    any_arraylike = any(
+        isinstance(g, (list, tuple, Series, Index, np.ndarray)) for g in keys
+    )
+
+    # is this an index replacement?
+    if (
+        not any_callable
+        and not any_arraylike
+        and not any_groupers
+        and match_axis_length
+        and level is None
+    ):
+        if isinstance(obj, DataFrame):
+            all_in_columns_index = all(
+                g in obj.columns or g in obj.index.names for g in keys
+            )
+        else:
+            assert isinstance(obj, Series)
+            all_in_columns_index = all(g in obj.index.names for g in keys)
+
+        if not all_in_columns_index:
+            keys = [com.asarray_tuplesafe(keys)]
+
+    if isinstance(level, (tuple, list)):
+        if key is None:
+            keys = [None] * len(level)
+        levels = level
+    else:
+        levels = [level] * len(keys)
+
+    groupings: list[Grouping] = []
+    exclusions: set[Hashable] = set()
+
+    # if the actual grouper should be obj[key]
+    def is_in_axis(key) -> bool:
+        if not _is_label_like(key):
+            if obj.ndim == 1:
+                return False
+
+            # items -> .columns for DataFrame, .index for Series
+            items = obj.axes[-1]
+            try:
+                items.get_loc(key)
+            except (KeyError, TypeError, InvalidIndexError):
+                # TypeError shows up here if we pass e.g. an Index
+                return False
+
+        return True
+
+    # if the grouper is obj[name]
+    def is_in_obj(gpr) -> bool:
+        if not hasattr(gpr, "name"):
+            return False
+        if using_copy_on_write() or warn_copy_on_write():
+            # For the CoW case, we check the references to determine if the
+            # series is part of the object
+            try:
+                obj_gpr_column = obj[gpr.name]
+            except (KeyError, IndexError, InvalidIndexError, OutOfBoundsDatetime):
+                return False
+            if isinstance(gpr, Series) and isinstance(obj_gpr_column, Series):
+                return gpr._mgr.references_same_values(  # type: ignore[union-attr]
+                    obj_gpr_column._mgr, 0  # type: ignore[arg-type]
+                )
+            return False
+        try:
+            return gpr is obj[gpr.name]
+        except (KeyError, IndexError, InvalidIndexError, OutOfBoundsDatetime):
+            # IndexError reached in e.g. test_skip_group_keys when we pass
+            #  lambda here
+            # InvalidIndexError raised on key-types inappropriate for index,
+            #  e.g. DatetimeIndex.get_loc(tuple())
+            # OutOfBoundsDatetime raised when obj is a Series with DatetimeIndex
+            # and gpr.name is month str
+            return False
+
+    for gpr, level in zip(keys, levels):
+        if isinstance(obj, DataFrame) and is_in_obj(gpr):  # df.groupby(df['name'])
+            in_axis = True
+            exclusions.add(gpr.name)
+
+        elif is_in_axis(gpr):  # df.groupby('name')
+            if obj.ndim != 1 and gpr in obj:
+                if validate:
+                    obj._check_label_or_level_ambiguity(gpr, axis=axis)
+                in_axis, name, gpr = True, gpr, obj[gpr]
+                if gpr.ndim != 1:
+                    # non-unique columns; raise here to get the name in the
+                    # exception message
+                    raise ValueError(f"Grouper for '{name}' not 1-dimensional")
+                exclusions.add(name)
+            elif obj._is_level_reference(gpr, axis=axis):
+                in_axis, level, gpr = False, gpr, None
+            else:
+                raise KeyError(gpr)
+        elif isinstance(gpr, Grouper) and gpr.key is not None:
+            # Add key to exclusions
+            exclusions.add(gpr.key)
+            in_axis = True
+        else:
+            in_axis = False
+
+        # create the Grouping
+        # allow us to passing the actual Grouping as the gpr
+        ping = (
+            Grouping(
+                group_axis,
+                gpr,
+                obj=obj,
+                level=level,
+                sort=sort,
+                observed=observed,
+                in_axis=in_axis,
+                dropna=dropna,
+            )
+            if not isinstance(gpr, Grouping)
+            else gpr
+        )
+
+        groupings.append(ping)
+
+    if len(groupings) == 0 and len(obj):
+        raise ValueError("No group keys passed!")
+    if len(groupings) == 0:
+        groupings.append(Grouping(Index([], dtype="int"), np.array([], dtype=np.intp)))
+
+    # create the internals grouper
+    grouper = ops.BaseGrouper(group_axis, groupings, sort=sort, dropna=dropna)
+    return grouper, frozenset(exclusions), obj
+
+
+def _is_label_like(val) -> bool:
+    return isinstance(val, (str, tuple)) or (val is not None and is_scalar(val))
+
+
+def _convert_grouper(axis: Index, grouper):
+    if isinstance(grouper, dict):
+        return grouper.get
+    elif isinstance(grouper, Series):
+        if grouper.index.equals(axis):
+            return grouper._values
+        else:
+            return grouper.reindex(axis)._values
+    elif isinstance(grouper, MultiIndex):
+        return grouper._values
+    elif isinstance(grouper, (list, tuple, Index, Categorical, np.ndarray)):
+        if len(grouper) != len(axis):
+            raise ValueError("Grouper and axis must be same length")
+
+        if isinstance(grouper, (list, tuple)):
+            grouper = com.asarray_tuplesafe(grouper)
+        return grouper
+    else:
+        return grouper
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/indexing.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..a3c5ab8edc94e4f91175891282252d0e8cdfd3ec
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/indexing.py
@@ -0,0 +1,304 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+)
+
+import numpy as np
+
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+
+from pandas.core.dtypes.common import (
+    is_integer,
+    is_list_like,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import PositionalIndexer
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.groupby import groupby
+
+
+class GroupByIndexingMixin:
+    """
+    Mixin for adding ._positional_selector to GroupBy.
+    """
+
+    @cache_readonly
+    def _positional_selector(self) -> GroupByPositionalSelector:
+        """
+        Return positional selection for each group.
+
+        ``groupby._positional_selector[i:j]`` is similar to
+        ``groupby.apply(lambda x: x.iloc[i:j])``
+        but much faster and preserves the original index and order.
+
+        ``_positional_selector[]`` is compatible with and extends :meth:`~GroupBy.head`
+        and :meth:`~GroupBy.tail`. For example:
+
+        - ``head(5)``
+        - ``_positional_selector[5:-5]``
+        - ``tail(5)``
+
+        together return all the rows.
+
+        Allowed inputs for the index are:
+
+        - An integer valued iterable, e.g. ``range(2, 4)``.
+        - A comma separated list of integers and slices, e.g. ``5``, ``2, 4``, ``2:4``.
+
+        The output format is the same as :meth:`~GroupBy.head` and
+        :meth:`~GroupBy.tail`, namely
+        a subset of the ``DataFrame`` or ``Series`` with the index and order preserved.
+
+        Returns
+        -------
+        Series
+            The filtered subset of the original Series.
+        DataFrame
+            The filtered subset of the original DataFrame.
+
+        See Also
+        --------
+        DataFrame.iloc : Purely integer-location based indexing for selection by
+            position.
+        GroupBy.head : Return first n rows of each group.
+        GroupBy.tail : Return last n rows of each group.
+        GroupBy.nth : Take the nth row from each group if n is an int, or a
+            subset of rows, if n is a list of ints.
+
+        Notes
+        -----
+        - The slice step cannot be negative.
+        - If the index specification results in overlaps, the item is not duplicated.
+        - If the index specification changes the order of items, then
+          they are returned in their original order.
+          By contrast, ``DataFrame.iloc`` can change the row order.
+        - ``groupby()`` parameters such as as_index and dropna are ignored.
+
+        The differences between ``_positional_selector[]`` and :meth:`~GroupBy.nth`
+        with ``as_index=False`` are:
+
+        - Input to ``_positional_selector`` can include
+          one or more slices whereas ``nth``
+          just handles an integer or a list of integers.
+        - ``_positional_selector`` can  accept a slice relative to the
+          last row of each group.
+        - ``_positional_selector`` does not have an equivalent to the
+          ``nth()`` ``dropna`` parameter.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([["a", 1], ["a", 2], ["a", 3], ["b", 4], ["b", 5]],
+        ...                   columns=["A", "B"])
+        >>> df.groupby("A")._positional_selector[1:2]
+           A  B
+        1  a  2
+        4  b  5
+
+        >>> df.groupby("A")._positional_selector[1, -1]
+           A  B
+        1  a  2
+        2  a  3
+        4  b  5
+        """
+        if TYPE_CHECKING:
+            # pylint: disable-next=used-before-assignment
+            groupby_self = cast(groupby.GroupBy, self)
+        else:
+            groupby_self = self
+
+        return GroupByPositionalSelector(groupby_self)
+
+    def _make_mask_from_positional_indexer(
+        self,
+        arg: PositionalIndexer | tuple,
+    ) -> np.ndarray:
+        if is_list_like(arg):
+            if all(is_integer(i) for i in cast(Iterable, arg)):
+                mask = self._make_mask_from_list(cast(Iterable[int], arg))
+            else:
+                mask = self._make_mask_from_tuple(cast(tuple, arg))
+
+        elif isinstance(arg, slice):
+            mask = self._make_mask_from_slice(arg)
+        elif is_integer(arg):
+            mask = self._make_mask_from_int(cast(int, arg))
+        else:
+            raise TypeError(
+                f"Invalid index {type(arg)}. "
+                "Must be integer, list-like, slice or a tuple of "
+                "integers and slices"
+            )
+
+        if isinstance(mask, bool):
+            if mask:
+                mask = self._ascending_count >= 0
+            else:
+                mask = self._ascending_count < 0
+
+        return cast(np.ndarray, mask)
+
+    def _make_mask_from_int(self, arg: int) -> np.ndarray:
+        if arg >= 0:
+            return self._ascending_count == arg
+        else:
+            return self._descending_count == (-arg - 1)
+
+    def _make_mask_from_list(self, args: Iterable[int]) -> bool | np.ndarray:
+        positive = [arg for arg in args if arg >= 0]
+        negative = [-arg - 1 for arg in args if arg < 0]
+
+        mask: bool | np.ndarray = False
+
+        if positive:
+            mask |= np.isin(self._ascending_count, positive)
+
+        if negative:
+            mask |= np.isin(self._descending_count, negative)
+
+        return mask
+
+    def _make_mask_from_tuple(self, args: tuple) -> bool | np.ndarray:
+        mask: bool | np.ndarray = False
+
+        for arg in args:
+            if is_integer(arg):
+                mask |= self._make_mask_from_int(cast(int, arg))
+            elif isinstance(arg, slice):
+                mask |= self._make_mask_from_slice(arg)
+            else:
+                raise ValueError(
+                    f"Invalid argument {type(arg)}. Should be int or slice."
+                )
+
+        return mask
+
+    def _make_mask_from_slice(self, arg: slice) -> bool | np.ndarray:
+        start = arg.start
+        stop = arg.stop
+        step = arg.step
+
+        if step is not None and step < 0:
+            raise ValueError(f"Invalid step {step}. Must be non-negative")
+
+        mask: bool | np.ndarray = True
+
+        if step is None:
+            step = 1
+
+        if start is None:
+            if step > 1:
+                mask &= self._ascending_count % step == 0
+
+        elif start >= 0:
+            mask &= self._ascending_count >= start
+
+            if step > 1:
+                mask &= (self._ascending_count - start) % step == 0
+
+        else:
+            mask &= self._descending_count < -start
+
+            offset_array = self._descending_count + start + 1
+            limit_array = (
+                self._ascending_count + self._descending_count + (start + 1)
+            ) < 0
+            offset_array = np.where(limit_array, self._ascending_count, offset_array)
+
+            mask &= offset_array % step == 0
+
+        if stop is not None:
+            if stop >= 0:
+                mask &= self._ascending_count < stop
+            else:
+                mask &= self._descending_count >= -stop
+
+        return mask
+
+    @cache_readonly
+    def _ascending_count(self) -> np.ndarray:
+        if TYPE_CHECKING:
+            groupby_self = cast(groupby.GroupBy, self)
+        else:
+            groupby_self = self
+
+        return groupby_self._cumcount_array()
+
+    @cache_readonly
+    def _descending_count(self) -> np.ndarray:
+        if TYPE_CHECKING:
+            groupby_self = cast(groupby.GroupBy, self)
+        else:
+            groupby_self = self
+
+        return groupby_self._cumcount_array(ascending=False)
+
+
+@doc(GroupByIndexingMixin._positional_selector)
+class GroupByPositionalSelector:
+    def __init__(self, groupby_object: groupby.GroupBy) -> None:
+        self.groupby_object = groupby_object
+
+    def __getitem__(self, arg: PositionalIndexer | tuple) -> DataFrame | Series:
+        """
+        Select by positional index per group.
+
+        Implements GroupBy._positional_selector
+
+        Parameters
+        ----------
+        arg : PositionalIndexer | tuple
+            Allowed values are:
+            - int
+            - int valued iterable such as list or range
+            - slice with step either None or positive
+            - tuple of integers and slices
+
+        Returns
+        -------
+        Series
+            The filtered subset of the original groupby Series.
+        DataFrame
+            The filtered subset of the original groupby DataFrame.
+
+        See Also
+        --------
+        DataFrame.iloc : Integer-location based indexing for selection by position.
+        GroupBy.head : Return first n rows of each group.
+        GroupBy.tail : Return last n rows of each group.
+        GroupBy._positional_selector : Return positional selection for each group.
+        GroupBy.nth : Take the nth row from each group if n is an int, or a
+            subset of rows, if n is a list of ints.
+        """
+        mask = self.groupby_object._make_mask_from_positional_indexer(arg)
+        return self.groupby_object._mask_selected_obj(mask)
+
+
+class GroupByNthSelector:
+    """
+    Dynamically substituted for GroupBy.nth to enable both call and index
+    """
+
+    def __init__(self, groupby_object: groupby.GroupBy) -> None:
+        self.groupby_object = groupby_object
+
+    def __call__(
+        self,
+        n: PositionalIndexer | tuple,
+        dropna: Literal["any", "all", None] = None,
+    ) -> DataFrame | Series:
+        return self.groupby_object._nth(n, dropna)
+
+    def __getitem__(self, n: PositionalIndexer | tuple) -> DataFrame | Series:
+        return self.groupby_object._nth(n)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/numba_.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/numba_.py
new file mode 100644
index 0000000000000000000000000000000000000000..3b7a58e87603e578216c4c80e8c88e06828d5dfa
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/numba_.py
@@ -0,0 +1,181 @@
+"""Common utilities for Numba operations with groupby ops"""
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+
+from pandas.core.util.numba_ import (
+    NumbaUtilError,
+    jit_user_function,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import Scalar
+
+
+def validate_udf(func: Callable) -> None:
+    """
+    Validate user defined function for ops when using Numba with groupby ops.
+
+    The first signature arguments should include:
+
+    def f(values, index, ...):
+        ...
+
+    Parameters
+    ----------
+    func : function, default False
+        user defined function
+
+    Returns
+    -------
+    None
+
+    Raises
+    ------
+    NumbaUtilError
+    """
+    if not callable(func):
+        raise NotImplementedError(
+            "Numba engine can only be used with a single function."
+        )
+    udf_signature = list(inspect.signature(func).parameters.keys())
+    expected_args = ["values", "index"]
+    min_number_args = len(expected_args)
+    if (
+        len(udf_signature) < min_number_args
+        or udf_signature[:min_number_args] != expected_args
+    ):
+        raise NumbaUtilError(
+            f"The first {min_number_args} arguments to {func.__name__} must be "
+            f"{expected_args}"
+        )
+
+
+@functools.cache
+def generate_numba_agg_func(
+    func: Callable[..., Scalar],
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+) -> Callable[[np.ndarray, np.ndarray, np.ndarray, np.ndarray, int, Any], np.ndarray]:
+    """
+    Generate a numba jitted agg function specified by values from engine_kwargs.
+
+    1. jit the user's function
+    2. Return a groupby agg function with the jitted function inline
+
+    Configurations specified in engine_kwargs apply to both the user's
+    function _AND_ the groupby evaluation loop.
+
+    Parameters
+    ----------
+    func : function
+        function to be applied to each group and will be JITed
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+    numba_func = jit_user_function(func)
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def group_agg(
+        values: np.ndarray,
+        index: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        num_columns: int,
+        *args: Any,
+    ) -> np.ndarray:
+        assert len(begin) == len(end)
+        num_groups = len(begin)
+
+        result = np.empty((num_groups, num_columns))
+        for i in numba.prange(num_groups):
+            group_index = index[begin[i] : end[i]]
+            for j in numba.prange(num_columns):
+                group = values[begin[i] : end[i], j]
+                result[i, j] = numba_func(group, group_index, *args)
+        return result
+
+    return group_agg
+
+
+@functools.cache
+def generate_numba_transform_func(
+    func: Callable[..., np.ndarray],
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+) -> Callable[[np.ndarray, np.ndarray, np.ndarray, np.ndarray, int, Any], np.ndarray]:
+    """
+    Generate a numba jitted transform function specified by values from engine_kwargs.
+
+    1. jit the user's function
+    2. Return a groupby transform function with the jitted function inline
+
+    Configurations specified in engine_kwargs apply to both the user's
+    function _AND_ the groupby evaluation loop.
+
+    Parameters
+    ----------
+    func : function
+        function to be applied to each window and will be JITed
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+    numba_func = jit_user_function(func)
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def group_transform(
+        values: np.ndarray,
+        index: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        num_columns: int,
+        *args: Any,
+    ) -> np.ndarray:
+        assert len(begin) == len(end)
+        num_groups = len(begin)
+
+        result = np.empty((len(values), num_columns))
+        for i in numba.prange(num_groups):
+            group_index = index[begin[i] : end[i]]
+            for j in numba.prange(num_columns):
+                group = values[begin[i] : end[i], j]
+                result[begin[i] : end[i], j] = numba_func(group, group_index, *args)
+        return result
+
+    return group_transform
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/groupby/ops.py b/.venv/lib/python3.13/site-packages/pandas/core/groupby/ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..e44c28f656eccf5744e0db8aa70dfbc9ac076f15
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/groupby/ops.py
@@ -0,0 +1,1217 @@
+"""
+Provide classes to perform the groupby aggregate operations.
+
+These are not exposed to the user and provide implementations of the grouping
+operations, primarily in cython. These classes (BaseGrouper and BinGrouper)
+are contained *in* the SeriesGroupBy and DataFrameGroupBy objects.
+"""
+from __future__ import annotations
+
+import collections
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    final,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    lib,
+)
+import pandas._libs.groupby as libgroupby
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    NDFrameT,
+    Shape,
+    npt,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import cache_readonly
+
+from pandas.core.dtypes.cast import (
+    maybe_cast_pointwise_result,
+    maybe_downcast_to_dtype,
+)
+from pandas.core.dtypes.common import (
+    ensure_float64,
+    ensure_int64,
+    ensure_platform_int,
+    ensure_uint64,
+    is_1d_only_ea_dtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    maybe_fill,
+)
+
+from pandas.core.frame import DataFrame
+from pandas.core.groupby import grouper
+from pandas.core.indexes.api import (
+    CategoricalIndex,
+    Index,
+    MultiIndex,
+    ensure_index,
+)
+from pandas.core.series import Series
+from pandas.core.sorting import (
+    compress_group_index,
+    decons_obs_group_ids,
+    get_flattened_list,
+    get_group_index,
+    get_group_index_sorter,
+    get_indexer_dict,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+        Sequence,
+    )
+
+    from pandas.core.generic import NDFrame
+
+
+def check_result_array(obj, dtype) -> None:
+    # Our operation is supposed to be an aggregation/reduction. If
+    #  it returns an ndarray, this likely means an invalid operation has
+    #  been passed. See test_apply_without_aggregation, test_agg_must_agg
+    if isinstance(obj, np.ndarray):
+        if dtype != object:
+            # If it is object dtype, the function can be a reduction/aggregation
+            #  and still return an ndarray e.g. test_agg_over_numpy_arrays
+            raise ValueError("Must produce aggregated value")
+
+
+def extract_result(res):
+    """
+    Extract the result object, it might be a 0-dim ndarray
+    or a len-1 0-dim, or a scalar
+    """
+    if hasattr(res, "_values"):
+        # Preserve EA
+        res = res._values
+        if res.ndim == 1 and len(res) == 1:
+            # see test_agg_lambda_with_timezone, test_resampler_grouper.py::test_apply
+            res = res[0]
+    return res
+
+
+class WrappedCythonOp:
+    """
+    Dispatch logic for functions defined in _libs.groupby
+
+    Parameters
+    ----------
+    kind: str
+        Whether the operation is an aggregate or transform.
+    how: str
+        Operation name, e.g. "mean".
+    has_dropped_na: bool
+        True precisely when dropna=True and the grouper contains a null value.
+    """
+
+    # Functions for which we do _not_ attempt to cast the cython result
+    #  back to the original dtype.
+    cast_blocklist = frozenset(
+        ["any", "all", "rank", "count", "size", "idxmin", "idxmax"]
+    )
+
+    def __init__(self, kind: str, how: str, has_dropped_na: bool) -> None:
+        self.kind = kind
+        self.how = how
+        self.has_dropped_na = has_dropped_na
+
+    _CYTHON_FUNCTIONS: dict[str, dict] = {
+        "aggregate": {
+            "any": functools.partial(libgroupby.group_any_all, val_test="any"),
+            "all": functools.partial(libgroupby.group_any_all, val_test="all"),
+            "sum": "group_sum",
+            "prod": "group_prod",
+            "idxmin": functools.partial(libgroupby.group_idxmin_idxmax, name="idxmin"),
+            "idxmax": functools.partial(libgroupby.group_idxmin_idxmax, name="idxmax"),
+            "min": "group_min",
+            "max": "group_max",
+            "mean": "group_mean",
+            "median": "group_median_float64",
+            "var": "group_var",
+            "std": functools.partial(libgroupby.group_var, name="std"),
+            "sem": functools.partial(libgroupby.group_var, name="sem"),
+            "skew": "group_skew",
+            "first": "group_nth",
+            "last": "group_last",
+            "ohlc": "group_ohlc",
+        },
+        "transform": {
+            "cumprod": "group_cumprod",
+            "cumsum": "group_cumsum",
+            "cummin": "group_cummin",
+            "cummax": "group_cummax",
+            "rank": "group_rank",
+        },
+    }
+
+    _cython_arity = {"ohlc": 4}  # OHLC
+
+    @classmethod
+    def get_kind_from_how(cls, how: str) -> str:
+        if how in cls._CYTHON_FUNCTIONS["aggregate"]:
+            return "aggregate"
+        return "transform"
+
+    # Note: we make this a classmethod and pass kind+how so that caching
+    #  works at the class level and not the instance level
+    @classmethod
+    @functools.cache
+    def _get_cython_function(
+        cls, kind: str, how: str, dtype: np.dtype, is_numeric: bool
+    ):
+        dtype_str = dtype.name
+        ftype = cls._CYTHON_FUNCTIONS[kind][how]
+
+        # see if there is a fused-type version of function
+        # only valid for numeric
+        if callable(ftype):
+            f = ftype
+        else:
+            f = getattr(libgroupby, ftype)
+        if is_numeric:
+            return f
+        elif dtype == np.dtype(object):
+            if how in ["median", "cumprod"]:
+                # no fused types -> no __signatures__
+                raise NotImplementedError(
+                    f"function is not implemented for this dtype: "
+                    f"[how->{how},dtype->{dtype_str}]"
+                )
+            elif how in ["std", "sem", "idxmin", "idxmax"]:
+                # We have a partial object that does not have __signatures__
+                return f
+            elif how == "skew":
+                # _get_cython_vals will convert to float64
+                pass
+            elif "object" not in f.__signatures__:
+                # raise NotImplementedError here rather than TypeError later
+                raise NotImplementedError(
+                    f"function is not implemented for this dtype: "
+                    f"[how->{how},dtype->{dtype_str}]"
+                )
+            return f
+        else:
+            raise NotImplementedError(
+                "This should not be reached. Please report a bug at "
+                "github.com/pandas-dev/pandas/",
+                dtype,
+            )
+
+    def _get_cython_vals(self, values: np.ndarray) -> np.ndarray:
+        """
+        Cast numeric dtypes to float64 for functions that only support that.
+
+        Parameters
+        ----------
+        values : np.ndarray
+
+        Returns
+        -------
+        values : np.ndarray
+        """
+        how = self.how
+
+        if how in ["median", "std", "sem", "skew"]:
+            # median only has a float64 implementation
+            # We should only get here with is_numeric, as non-numeric cases
+            #  should raise in _get_cython_function
+            values = ensure_float64(values)
+
+        elif values.dtype.kind in "iu":
+            if how in ["var", "mean"] or (
+                self.kind == "transform" and self.has_dropped_na
+            ):
+                # has_dropped_na check need for test_null_group_str_transformer
+                # result may still include NaN, so we have to cast
+                values = ensure_float64(values)
+
+            elif how in ["sum", "ohlc", "prod", "cumsum", "cumprod"]:
+                # Avoid overflow during group op
+                if values.dtype.kind == "i":
+                    values = ensure_int64(values)
+                else:
+                    values = ensure_uint64(values)
+
+        return values
+
+    def _get_output_shape(self, ngroups: int, values: np.ndarray) -> Shape:
+        how = self.how
+        kind = self.kind
+
+        arity = self._cython_arity.get(how, 1)
+
+        out_shape: Shape
+        if how == "ohlc":
+            out_shape = (ngroups, arity)
+        elif arity > 1:
+            raise NotImplementedError(
+                "arity of more than 1 is not supported for the 'how' argument"
+            )
+        elif kind == "transform":
+            out_shape = values.shape
+        else:
+            out_shape = (ngroups,) + values.shape[1:]
+        return out_shape
+
+    def _get_out_dtype(self, dtype: np.dtype) -> np.dtype:
+        how = self.how
+
+        if how == "rank":
+            out_dtype = "float64"
+        elif how in ["idxmin", "idxmax"]:
+            # The Cython implementation only produces the row number; we'll take
+            # from the index using this in post processing
+            out_dtype = "intp"
+        else:
+            if dtype.kind in "iufcb":
+                out_dtype = f"{dtype.kind}{dtype.itemsize}"
+            else:
+                out_dtype = "object"
+        return np.dtype(out_dtype)
+
+    def _get_result_dtype(self, dtype: np.dtype) -> np.dtype:
+        """
+        Get the desired dtype of a result based on the
+        input dtype and how it was computed.
+
+        Parameters
+        ----------
+        dtype : np.dtype
+
+        Returns
+        -------
+        np.dtype
+            The desired dtype of the result.
+        """
+        how = self.how
+
+        if how in ["sum", "cumsum", "sum", "prod", "cumprod"]:
+            if dtype == np.dtype(bool):
+                return np.dtype(np.int64)
+        elif how in ["mean", "median", "var", "std", "sem"]:
+            if dtype.kind in "fc":
+                return dtype
+            elif dtype.kind in "iub":
+                return np.dtype(np.float64)
+        return dtype
+
+    @final
+    def _cython_op_ndim_compat(
+        self,
+        values: np.ndarray,
+        *,
+        min_count: int,
+        ngroups: int,
+        comp_ids: np.ndarray,
+        mask: npt.NDArray[np.bool_] | None = None,
+        result_mask: npt.NDArray[np.bool_] | None = None,
+        initial: Any = 0,
+        **kwargs,
+    ) -> np.ndarray:
+        if values.ndim == 1:
+            # expand to 2d, dispatch, then squeeze if appropriate
+            values2d = values[None, :]
+            if mask is not None:
+                mask = mask[None, :]
+            if result_mask is not None:
+                result_mask = result_mask[None, :]
+            res = self._call_cython_op(
+                values2d,
+                min_count=min_count,
+                ngroups=ngroups,
+                comp_ids=comp_ids,
+                mask=mask,
+                result_mask=result_mask,
+                initial=initial,
+                **kwargs,
+            )
+            if res.shape[0] == 1:
+                return res[0]
+
+            # otherwise we have OHLC
+            return res.T
+
+        return self._call_cython_op(
+            values,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=comp_ids,
+            mask=mask,
+            result_mask=result_mask,
+            initial=initial,
+            **kwargs,
+        )
+
+    @final
+    def _call_cython_op(
+        self,
+        values: np.ndarray,  # np.ndarray[ndim=2]
+        *,
+        min_count: int,
+        ngroups: int,
+        comp_ids: np.ndarray,
+        mask: npt.NDArray[np.bool_] | None,
+        result_mask: npt.NDArray[np.bool_] | None,
+        initial: Any = 0,
+        **kwargs,
+    ) -> np.ndarray:  # np.ndarray[ndim=2]
+        orig_values = values
+
+        dtype = values.dtype
+        is_numeric = dtype.kind in "iufcb"
+
+        is_datetimelike = dtype.kind in "mM"
+
+        if is_datetimelike:
+            values = values.view("int64")
+            is_numeric = True
+        elif dtype.kind == "b":
+            values = values.view("uint8")
+        if values.dtype == "float16":
+            values = values.astype(np.float32)
+
+        if self.how in ["any", "all"]:
+            if mask is None:
+                mask = isna(values)
+            if dtype == object:
+                if kwargs["skipna"]:
+                    # GH#37501: don't raise on pd.NA when skipna=True
+                    if mask.any():
+                        # mask on original values computed separately
+                        values = values.copy()
+                        values[mask] = True
+            values = values.astype(bool, copy=False).view(np.int8)
+            is_numeric = True
+
+        values = values.T
+        if mask is not None:
+            mask = mask.T
+            if result_mask is not None:
+                result_mask = result_mask.T
+
+        out_shape = self._get_output_shape(ngroups, values)
+        func = self._get_cython_function(self.kind, self.how, values.dtype, is_numeric)
+        values = self._get_cython_vals(values)
+        out_dtype = self._get_out_dtype(values.dtype)
+
+        result = maybe_fill(np.empty(out_shape, dtype=out_dtype))
+        if self.kind == "aggregate":
+            counts = np.zeros(ngroups, dtype=np.int64)
+            if self.how in [
+                "idxmin",
+                "idxmax",
+                "min",
+                "max",
+                "mean",
+                "last",
+                "first",
+                "sum",
+            ]:
+                if self.how == "sum":
+                    # pass in through kwargs only for sum (other functions don't have
+                    # the keyword)
+                    kwargs["initial"] = initial
+                func(
+                    out=result,
+                    counts=counts,
+                    values=values,
+                    labels=comp_ids,
+                    min_count=min_count,
+                    mask=mask,
+                    result_mask=result_mask,
+                    is_datetimelike=is_datetimelike,
+                    **kwargs,
+                )
+            elif self.how in ["sem", "std", "var", "ohlc", "prod", "median"]:
+                if self.how in ["std", "sem"]:
+                    kwargs["is_datetimelike"] = is_datetimelike
+                func(
+                    result,
+                    counts,
+                    values,
+                    comp_ids,
+                    min_count=min_count,
+                    mask=mask,
+                    result_mask=result_mask,
+                    **kwargs,
+                )
+            elif self.how in ["any", "all"]:
+                func(
+                    out=result,
+                    values=values,
+                    labels=comp_ids,
+                    mask=mask,
+                    result_mask=result_mask,
+                    **kwargs,
+                )
+                result = result.astype(bool, copy=False)
+            elif self.how in ["skew"]:
+                func(
+                    out=result,
+                    counts=counts,
+                    values=values,
+                    labels=comp_ids,
+                    mask=mask,
+                    result_mask=result_mask,
+                    **kwargs,
+                )
+                if dtype == object:
+                    result = result.astype(object)
+
+            else:
+                raise NotImplementedError(f"{self.how} is not implemented")
+        else:
+            # TODO: min_count
+            if self.how != "rank":
+                # TODO: should rank take result_mask?
+                kwargs["result_mask"] = result_mask
+            func(
+                out=result,
+                values=values,
+                labels=comp_ids,
+                ngroups=ngroups,
+                is_datetimelike=is_datetimelike,
+                mask=mask,
+                **kwargs,
+            )
+
+        if self.kind == "aggregate" and self.how not in ["idxmin", "idxmax"]:
+            # i.e. counts is defined.  Locations where count None:
+        if values.ndim > 2:
+            raise NotImplementedError("number of dimensions is currently limited to 2")
+        if values.ndim == 2:
+            assert axis == 1, axis
+        elif not is_1d_only_ea_dtype(values.dtype):
+            # Note: it is *not* the case that axis is always 0 for 1-dim values,
+            #  as we can have 1D ExtensionArrays that we need to treat as 2D
+            assert axis == 0
+
+    @final
+    def cython_operation(
+        self,
+        *,
+        values: ArrayLike,
+        axis: AxisInt,
+        min_count: int = -1,
+        comp_ids: np.ndarray,
+        ngroups: int,
+        **kwargs,
+    ) -> ArrayLike:
+        """
+        Call our cython function, with appropriate pre- and post- processing.
+        """
+        self._validate_axis(axis, values)
+
+        if not isinstance(values, np.ndarray):
+            # i.e. ExtensionArray
+            return values._groupby_op(
+                how=self.how,
+                has_dropped_na=self.has_dropped_na,
+                min_count=min_count,
+                ngroups=ngroups,
+                ids=comp_ids,
+                **kwargs,
+            )
+
+        return self._cython_op_ndim_compat(
+            values,
+            min_count=min_count,
+            ngroups=ngroups,
+            comp_ids=comp_ids,
+            mask=None,
+            **kwargs,
+        )
+
+
+class BaseGrouper:
+    """
+    This is an internal Grouper class, which actually holds
+    the generated groups
+
+    Parameters
+    ----------
+    axis : Index
+    groupings : Sequence[Grouping]
+        all the grouping instances to handle in this grouper
+        for example for grouper list to groupby, need to pass the list
+    sort : bool, default True
+        whether this grouper will give sorted result or not
+
+    """
+
+    axis: Index
+
+    def __init__(
+        self,
+        axis: Index,
+        groupings: Sequence[grouper.Grouping],
+        sort: bool = True,
+        dropna: bool = True,
+    ) -> None:
+        assert isinstance(axis, Index), axis
+
+        self.axis = axis
+        self._groupings: list[grouper.Grouping] = list(groupings)
+        self._sort = sort
+        self.dropna = dropna
+
+    @property
+    def groupings(self) -> list[grouper.Grouping]:
+        return self._groupings
+
+    @property
+    def shape(self) -> Shape:
+        return tuple(ping.ngroups for ping in self.groupings)
+
+    def __iter__(self) -> Iterator[Hashable]:
+        return iter(self.indices)
+
+    @property
+    def nkeys(self) -> int:
+        return len(self.groupings)
+
+    def get_iterator(
+        self, data: NDFrameT, axis: AxisInt = 0
+    ) -> Iterator[tuple[Hashable, NDFrameT]]:
+        """
+        Groupby iterator
+
+        Returns
+        -------
+        Generator yielding sequence of (name, subsetted object)
+        for each group
+        """
+        splitter = self._get_splitter(data, axis=axis)
+        keys = self.group_keys_seq
+        yield from zip(keys, splitter)
+
+    @final
+    def _get_splitter(self, data: NDFrame, axis: AxisInt = 0) -> DataSplitter:
+        """
+        Returns
+        -------
+        Generator yielding subsetted objects
+        """
+        ids, _, ngroups = self.group_info
+        return _get_splitter(
+            data,
+            ids,
+            ngroups,
+            sorted_ids=self._sorted_ids,
+            sort_idx=self._sort_idx,
+            axis=axis,
+        )
+
+    @final
+    @cache_readonly
+    def group_keys_seq(self):
+        if len(self.groupings) == 1:
+            return self.levels[0]
+        else:
+            ids, _, ngroups = self.group_info
+
+            # provide "flattened" iterator for multi-group setting
+            return get_flattened_list(ids, ngroups, self.levels, self.codes)
+
+    @cache_readonly
+    def indices(self) -> dict[Hashable, npt.NDArray[np.intp]]:
+        """dict {group name -> group indices}"""
+        if len(self.groupings) == 1 and isinstance(self.result_index, CategoricalIndex):
+            # This shows unused categories in indices GH#38642
+            return self.groupings[0].indices
+        codes_list = [ping.codes for ping in self.groupings]
+        keys = [ping._group_index for ping in self.groupings]
+        return get_indexer_dict(codes_list, keys)
+
+    @final
+    def result_ilocs(self) -> npt.NDArray[np.intp]:
+        """
+        Get the original integer locations of result_index in the input.
+        """
+        # Original indices are where group_index would go via sorting.
+        # But when dropna is true, we need to remove null values while accounting for
+        # any gaps that then occur because of them.
+        group_index = get_group_index(
+            self.codes, self.shape, sort=self._sort, xnull=True
+        )
+        group_index, _ = compress_group_index(group_index, sort=self._sort)
+
+        if self.has_dropped_na:
+            mask = np.where(group_index >= 0)
+            # Count how many gaps are caused by previous null values for each position
+            null_gaps = np.cumsum(group_index == -1)[mask]
+            group_index = group_index[mask]
+
+        result = get_group_index_sorter(group_index, self.ngroups)
+
+        if self.has_dropped_na:
+            # Shift by the number of prior null gaps
+            result += np.take(null_gaps, result)
+
+        return result
+
+    @final
+    @property
+    def codes(self) -> list[npt.NDArray[np.signedinteger]]:
+        return [ping.codes for ping in self.groupings]
+
+    @property
+    def levels(self) -> list[Index]:
+        return [ping._group_index for ping in self.groupings]
+
+    @property
+    def names(self) -> list[Hashable]:
+        return [ping.name for ping in self.groupings]
+
+    @final
+    def size(self) -> Series:
+        """
+        Compute group sizes.
+        """
+        ids, _, ngroups = self.group_info
+        out: np.ndarray | list
+        if ngroups:
+            out = np.bincount(ids[ids != -1], minlength=ngroups)
+        else:
+            out = []
+        return Series(out, index=self.result_index, dtype="int64", copy=False)
+
+    @cache_readonly
+    def groups(self) -> dict[Hashable, np.ndarray]:
+        """dict {group name -> group labels}"""
+        if len(self.groupings) == 1:
+            return self.groupings[0].groups
+        else:
+            to_groupby = []
+            for ping in self.groupings:
+                gv = ping.grouping_vector
+                if not isinstance(gv, BaseGrouper):
+                    to_groupby.append(gv)
+                else:
+                    to_groupby.append(gv.groupings[0].grouping_vector)
+            index = MultiIndex.from_arrays(to_groupby)
+            return self.axis.groupby(index)
+
+    @final
+    @cache_readonly
+    def is_monotonic(self) -> bool:
+        # return if my group orderings are monotonic
+        return Index(self.group_info[0]).is_monotonic_increasing
+
+    @final
+    @cache_readonly
+    def has_dropped_na(self) -> bool:
+        """
+        Whether grouper has null value(s) that are dropped.
+        """
+        return bool((self.group_info[0] < 0).any())
+
+    @cache_readonly
+    def group_info(self) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp], int]:
+        comp_ids, obs_group_ids = self._get_compressed_codes()
+
+        ngroups = len(obs_group_ids)
+        comp_ids = ensure_platform_int(comp_ids)
+
+        return comp_ids, obs_group_ids, ngroups
+
+    @cache_readonly
+    def codes_info(self) -> npt.NDArray[np.intp]:
+        # return the codes of items in original grouped axis
+        ids, _, _ = self.group_info
+        return ids
+
+    @final
+    def _get_compressed_codes(
+        self,
+    ) -> tuple[npt.NDArray[np.signedinteger], npt.NDArray[np.intp]]:
+        # The first returned ndarray may have any signed integer dtype
+        if len(self.groupings) > 1:
+            group_index = get_group_index(self.codes, self.shape, sort=True, xnull=True)
+            return compress_group_index(group_index, sort=self._sort)
+            # FIXME: compress_group_index's second return value is int64, not intp
+
+        ping = self.groupings[0]
+        return ping.codes, np.arange(len(ping._group_index), dtype=np.intp)
+
+    @final
+    @cache_readonly
+    def ngroups(self) -> int:
+        return len(self.result_index)
+
+    @property
+    def reconstructed_codes(self) -> list[npt.NDArray[np.intp]]:
+        codes = self.codes
+        ids, obs_ids, _ = self.group_info
+        return decons_obs_group_ids(ids, obs_ids, self.shape, codes, xnull=True)
+
+    @cache_readonly
+    def result_index(self) -> Index:
+        if len(self.groupings) == 1:
+            return self.groupings[0]._result_index.rename(self.names[0])
+
+        codes = self.reconstructed_codes
+        levels = [ping._result_index for ping in self.groupings]
+        return MultiIndex(
+            levels=levels, codes=codes, verify_integrity=False, names=self.names
+        )
+
+    @final
+    def get_group_levels(self) -> list[ArrayLike]:
+        # Note: only called from _insert_inaxis_grouper, which
+        #  is only called for BaseGrouper, never for BinGrouper
+        if len(self.groupings) == 1:
+            return [self.groupings[0]._group_arraylike]
+
+        name_list = []
+        for ping, codes in zip(self.groupings, self.reconstructed_codes):
+            codes = ensure_platform_int(codes)
+            levels = ping._group_arraylike.take(codes)
+
+            name_list.append(levels)
+
+        return name_list
+
+    # ------------------------------------------------------------
+    # Aggregation functions
+
+    @final
+    def _cython_operation(
+        self,
+        kind: str,
+        values,
+        how: str,
+        axis: AxisInt,
+        min_count: int = -1,
+        **kwargs,
+    ) -> ArrayLike:
+        """
+        Returns the values of a cython operation.
+        """
+        assert kind in ["transform", "aggregate"]
+
+        cy_op = WrappedCythonOp(kind=kind, how=how, has_dropped_na=self.has_dropped_na)
+
+        ids, _, _ = self.group_info
+        ngroups = self.ngroups
+        return cy_op.cython_operation(
+            values=values,
+            axis=axis,
+            min_count=min_count,
+            comp_ids=ids,
+            ngroups=ngroups,
+            **kwargs,
+        )
+
+    @final
+    def agg_series(
+        self, obj: Series, func: Callable, preserve_dtype: bool = False
+    ) -> ArrayLike:
+        """
+        Parameters
+        ----------
+        obj : Series
+        func : function taking a Series and returning a scalar-like
+        preserve_dtype : bool
+            Whether the aggregation is known to be dtype-preserving.
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+        """
+
+        if not isinstance(obj._values, np.ndarray):
+            # we can preserve a little bit more aggressively with EA dtype
+            #  because maybe_cast_pointwise_result will do a try/except
+            #  with _from_sequence.  NB we are assuming here that _from_sequence
+            #  is sufficiently strict that it casts appropriately.
+            preserve_dtype = True
+
+        result = self._aggregate_series_pure_python(obj, func)
+
+        npvalues = lib.maybe_convert_objects(result, try_float=False)
+        if preserve_dtype:
+            out = maybe_cast_pointwise_result(npvalues, obj.dtype, numeric_only=True)
+        else:
+            out = npvalues
+        return out
+
+    @final
+    def _aggregate_series_pure_python(
+        self, obj: Series, func: Callable
+    ) -> npt.NDArray[np.object_]:
+        _, _, ngroups = self.group_info
+
+        result = np.empty(ngroups, dtype="O")
+        initialized = False
+
+        splitter = self._get_splitter(obj, axis=0)
+
+        for i, group in enumerate(splitter):
+            res = func(group)
+            res = extract_result(res)
+
+            if not initialized:
+                # We only do this validation on the first iteration
+                check_result_array(res, group.dtype)
+                initialized = True
+
+            result[i] = res
+
+        return result
+
+    @final
+    def apply_groupwise(
+        self, f: Callable, data: DataFrame | Series, axis: AxisInt = 0
+    ) -> tuple[list, bool]:
+        mutated = False
+        splitter = self._get_splitter(data, axis=axis)
+        group_keys = self.group_keys_seq
+        result_values = []
+
+        # This calls DataSplitter.__iter__
+        zipped = zip(group_keys, splitter)
+
+        for key, group in zipped:
+            # Pinning name is needed for
+            #  test_group_apply_once_per_group,
+            #  test_inconsistent_return_type, test_set_group_name,
+            #  test_group_name_available_in_inference_pass,
+            #  test_groupby_multi_timezone
+            object.__setattr__(group, "name", key)
+
+            # group might be modified
+            group_axes = group.axes
+            res = f(group)
+            if not mutated and not _is_indexed_like(res, group_axes, axis):
+                mutated = True
+            result_values.append(res)
+        # getattr pattern for __name__ is needed for functools.partial objects
+        if len(group_keys) == 0 and getattr(f, "__name__", None) in [
+            "skew",
+            "sum",
+            "prod",
+        ]:
+            #  If group_keys is empty, then no function calls have been made,
+            #  so we will not have raised even if this is an invalid dtype.
+            #  So do one dummy call here to raise appropriate TypeError.
+            f(data.iloc[:0])
+
+        return result_values, mutated
+
+    # ------------------------------------------------------------
+    # Methods for sorting subsets of our GroupBy's object
+
+    @final
+    @cache_readonly
+    def _sort_idx(self) -> npt.NDArray[np.intp]:
+        # Counting sort indexer
+        ids, _, ngroups = self.group_info
+        return get_group_index_sorter(ids, ngroups)
+
+    @final
+    @cache_readonly
+    def _sorted_ids(self) -> npt.NDArray[np.intp]:
+        ids, _, _ = self.group_info
+        return ids.take(self._sort_idx)
+
+
+class BinGrouper(BaseGrouper):
+    """
+    This is an internal Grouper class
+
+    Parameters
+    ----------
+    bins : the split index of binlabels to group the item of axis
+    binlabels : the label list
+    indexer : np.ndarray[np.intp], optional
+        the indexer created by Grouper
+        some groupers (TimeGrouper) will sort its axis and its
+        group_info is also sorted, so need the indexer to reorder
+
+    Examples
+    --------
+    bins: [2, 4, 6, 8, 10]
+    binlabels: DatetimeIndex(['2005-01-01', '2005-01-03',
+        '2005-01-05', '2005-01-07', '2005-01-09'],
+        dtype='datetime64[ns]', freq='2D')
+
+    the group_info, which contains the label of each item in grouped
+    axis, the index of label in label list, group number, is
+
+    (array([0, 0, 1, 1, 2, 2, 3, 3, 4, 4]), array([0, 1, 2, 3, 4]), 5)
+
+    means that, the grouped axis has 10 items, can be grouped into 5
+    labels, the first and second items belong to the first label, the
+    third and forth items belong to the second label, and so on
+
+    """
+
+    bins: npt.NDArray[np.int64]
+    binlabels: Index
+
+    def __init__(
+        self,
+        bins,
+        binlabels,
+        indexer=None,
+    ) -> None:
+        self.bins = ensure_int64(bins)
+        self.binlabels = ensure_index(binlabels)
+        self.indexer = indexer
+
+        # These lengths must match, otherwise we could call agg_series
+        #  with empty self.bins, which would raise later.
+        assert len(self.binlabels) == len(self.bins)
+
+    @cache_readonly
+    def groups(self):
+        """dict {group name -> group labels}"""
+        # this is mainly for compat
+        # GH 3881
+        result = {
+            key: value
+            for key, value in zip(self.binlabels, self.bins)
+            if key is not NaT
+        }
+        return result
+
+    @property
+    def nkeys(self) -> int:
+        # still matches len(self.groupings), but we can hard-code
+        return 1
+
+    @cache_readonly
+    def codes_info(self) -> npt.NDArray[np.intp]:
+        # return the codes of items in original grouped axis
+        ids, _, _ = self.group_info
+        if self.indexer is not None:
+            sorter = np.lexsort((ids, self.indexer))
+            ids = ids[sorter]
+        return ids
+
+    def get_iterator(self, data: NDFrame, axis: AxisInt = 0):
+        """
+        Groupby iterator
+
+        Returns
+        -------
+        Generator yielding sequence of (name, subsetted object)
+        for each group
+        """
+        if axis == 0:
+            slicer = lambda start, edge: data.iloc[start:edge]
+        else:
+            slicer = lambda start, edge: data.iloc[:, start:edge]
+
+        length = len(data.axes[axis])
+
+        start = 0
+        for edge, label in zip(self.bins, self.binlabels):
+            if label is not NaT:
+                yield label, slicer(start, edge)
+            start = edge
+
+        if start < length:
+            yield self.binlabels[-1], slicer(start, None)
+
+    @cache_readonly
+    def indices(self):
+        indices = collections.defaultdict(list)
+
+        i = 0
+        for label, bin in zip(self.binlabels, self.bins):
+            if i < bin:
+                if label is not NaT:
+                    indices[label] = list(range(i, bin))
+                i = bin
+        return indices
+
+    @cache_readonly
+    def group_info(self) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp], int]:
+        ngroups = self.ngroups
+        obs_group_ids = np.arange(ngroups, dtype=np.intp)
+        rep = np.diff(np.r_[0, self.bins])
+
+        rep = ensure_platform_int(rep)
+        if ngroups == len(self.bins):
+            comp_ids = np.repeat(np.arange(ngroups), rep)
+        else:
+            comp_ids = np.repeat(np.r_[-1, np.arange(ngroups)], rep)
+
+        return (
+            ensure_platform_int(comp_ids),
+            obs_group_ids,
+            ngroups,
+        )
+
+    @cache_readonly
+    def reconstructed_codes(self) -> list[np.ndarray]:
+        # get unique result indices, and prepend 0 as groupby starts from the first
+        return [np.r_[0, np.flatnonzero(self.bins[1:] != self.bins[:-1]) + 1]]
+
+    @cache_readonly
+    def result_index(self) -> Index:
+        if len(self.binlabels) != 0 and isna(self.binlabels[0]):
+            return self.binlabels[1:]
+
+        return self.binlabels
+
+    @property
+    def levels(self) -> list[Index]:
+        return [self.binlabels]
+
+    @property
+    def names(self) -> list[Hashable]:
+        return [self.binlabels.name]
+
+    @property
+    def groupings(self) -> list[grouper.Grouping]:
+        lev = self.binlabels
+        codes = self.group_info[0]
+        labels = lev.take(codes)
+        ping = grouper.Grouping(
+            labels, labels, in_axis=False, level=None, uniques=lev._values
+        )
+        return [ping]
+
+
+def _is_indexed_like(obj, axes, axis: AxisInt) -> bool:
+    if isinstance(obj, Series):
+        if len(axes) > 1:
+            return False
+        return obj.axes[axis].equals(axes[axis])
+    elif isinstance(obj, DataFrame):
+        return obj.axes[axis].equals(axes[axis])
+
+    return False
+
+
+# ----------------------------------------------------------------------
+# Splitting / application
+
+
+class DataSplitter(Generic[NDFrameT]):
+    def __init__(
+        self,
+        data: NDFrameT,
+        labels: npt.NDArray[np.intp],
+        ngroups: int,
+        *,
+        sort_idx: npt.NDArray[np.intp],
+        sorted_ids: npt.NDArray[np.intp],
+        axis: AxisInt = 0,
+    ) -> None:
+        self.data = data
+        self.labels = ensure_platform_int(labels)  # _should_ already be np.intp
+        self.ngroups = ngroups
+
+        self._slabels = sorted_ids
+        self._sort_idx = sort_idx
+
+        self.axis = axis
+        assert isinstance(axis, int), axis
+
+    def __iter__(self) -> Iterator:
+        sdata = self._sorted_data
+
+        if self.ngroups == 0:
+            # we are inside a generator, rather than raise StopIteration
+            # we merely return signal the end
+            return
+
+        starts, ends = lib.generate_slices(self._slabels, self.ngroups)
+
+        for start, end in zip(starts, ends):
+            yield self._chop(sdata, slice(start, end))
+
+    @cache_readonly
+    def _sorted_data(self) -> NDFrameT:
+        return self.data.take(self._sort_idx, axis=self.axis)
+
+    def _chop(self, sdata, slice_obj: slice) -> NDFrame:
+        raise AbstractMethodError(self)
+
+
+class SeriesSplitter(DataSplitter):
+    def _chop(self, sdata: Series, slice_obj: slice) -> Series:
+        # fastpath equivalent to `sdata.iloc[slice_obj]`
+        mgr = sdata._mgr.get_slice(slice_obj)
+        ser = sdata._constructor_from_mgr(mgr, axes=mgr.axes)
+        ser._name = sdata.name
+        return ser.__finalize__(sdata, method="groupby")
+
+
+class FrameSplitter(DataSplitter):
+    def _chop(self, sdata: DataFrame, slice_obj: slice) -> DataFrame:
+        # Fastpath equivalent to:
+        # if self.axis == 0:
+        #     return sdata.iloc[slice_obj]
+        # else:
+        #     return sdata.iloc[:, slice_obj]
+        mgr = sdata._mgr.get_slice(slice_obj, axis=1 - self.axis)
+        df = sdata._constructor_from_mgr(mgr, axes=mgr.axes)
+        return df.__finalize__(sdata, method="groupby")
+
+
+def _get_splitter(
+    data: NDFrame,
+    labels: npt.NDArray[np.intp],
+    ngroups: int,
+    *,
+    sort_idx: npt.NDArray[np.intp],
+    sorted_ids: npt.NDArray[np.intp],
+    axis: AxisInt = 0,
+) -> DataSplitter:
+    if isinstance(data, Series):
+        klass: type[DataSplitter] = SeriesSplitter
+    else:
+        # i.e. DataFrame
+        klass = FrameSplitter
+
+    return klass(
+        data, labels, ngroups, sort_idx=sort_idx, sorted_ids=sorted_ids, axis=axis
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexers/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/indexers/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..ba8a4f1d0ee7adb668c6b0ac49b2360d3c0dc356
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexers/__init__.py
@@ -0,0 +1,31 @@
+from pandas.core.indexers.utils import (
+    check_array_indexer,
+    check_key_length,
+    check_setitem_lengths,
+    disallow_ndim_indexing,
+    is_empty_indexer,
+    is_list_like_indexer,
+    is_scalar_indexer,
+    is_valid_positional_slice,
+    length_of_indexer,
+    maybe_convert_indices,
+    unpack_1tuple,
+    unpack_tuple_and_ellipses,
+    validate_indices,
+)
+
+__all__ = [
+    "is_valid_positional_slice",
+    "is_list_like_indexer",
+    "is_scalar_indexer",
+    "is_empty_indexer",
+    "check_setitem_lengths",
+    "validate_indices",
+    "maybe_convert_indices",
+    "length_of_indexer",
+    "disallow_ndim_indexing",
+    "unpack_1tuple",
+    "check_key_length",
+    "check_array_indexer",
+    "unpack_tuple_and_ellipses",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexers/objects.py b/.venv/lib/python3.13/site-packages/pandas/core/indexers/objects.py
new file mode 100644
index 0000000000000000000000000000000000000000..f2db4886a559017422ed41bb8bd2246d6a3f0fb0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexers/objects.py
@@ -0,0 +1,453 @@
+"""Indexer objects for computing start/end window bounds for rolling operations"""
+from __future__ import annotations
+
+from datetime import timedelta
+
+import numpy as np
+
+from pandas._libs.tslibs import BaseOffset
+from pandas._libs.window.indexers import calculate_variable_window_bounds
+from pandas.util._decorators import Appender
+
+from pandas.core.dtypes.common import ensure_platform_int
+
+from pandas.core.indexes.datetimes import DatetimeIndex
+
+from pandas.tseries.offsets import Nano
+
+get_window_bounds_doc = """
+Computes the bounds of a window.
+
+Parameters
+----------
+num_values : int, default 0
+    number of values that will be aggregated over
+window_size : int, default 0
+    the number of rows in a window
+min_periods : int, default None
+    min_periods passed from the top level rolling API
+center : bool, default None
+    center passed from the top level rolling API
+closed : str, default None
+    closed passed from the top level rolling API
+step : int, default None
+    step passed from the top level rolling API
+    .. versionadded:: 1.5
+win_type : str, default None
+    win_type passed from the top level rolling API
+
+Returns
+-------
+A tuple of ndarray[int64]s, indicating the boundaries of each
+window
+"""
+
+
+class BaseIndexer:
+    """
+    Base class for window bounds calculations.
+
+    Examples
+    --------
+    >>> from pandas.api.indexers import BaseIndexer
+    >>> class CustomIndexer(BaseIndexer):
+    ...     def get_window_bounds(self, num_values, min_periods, center, closed, step):
+    ...         start = np.empty(num_values, dtype=np.int64)
+    ...         end = np.empty(num_values, dtype=np.int64)
+    ...         for i in range(num_values):
+    ...             start[i] = i
+    ...             end[i] = i + self.window_size
+    ...         return start, end
+    >>> df = pd.DataFrame({"values": range(5)})
+    >>> indexer = CustomIndexer(window_size=2)
+    >>> df.rolling(indexer).sum()
+        values
+    0	1.0
+    1	3.0
+    2	5.0
+    3	7.0
+    4	4.0
+    """
+
+    def __init__(
+        self, index_array: np.ndarray | None = None, window_size: int = 0, **kwargs
+    ) -> None:
+        self.index_array = index_array
+        self.window_size = window_size
+        # Set user defined kwargs as attributes that can be used in get_window_bounds
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        raise NotImplementedError
+
+
+class FixedWindowIndexer(BaseIndexer):
+    """Creates window boundaries that are of fixed length."""
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if center or self.window_size == 0:
+            offset = (self.window_size - 1) // 2
+        else:
+            offset = 0
+
+        end = np.arange(1 + offset, num_values + 1 + offset, step, dtype="int64")
+        start = end - self.window_size
+        if closed in ["left", "both"]:
+            start -= 1
+        if closed in ["left", "neither"]:
+            end -= 1
+
+        end = np.clip(end, 0, num_values)
+        start = np.clip(start, 0, num_values)
+
+        return start, end
+
+
+class VariableWindowIndexer(BaseIndexer):
+    """Creates window boundaries that are of variable length, namely for time series."""
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        # error: Argument 4 to "calculate_variable_window_bounds" has incompatible
+        # type "Optional[bool]"; expected "bool"
+        # error: Argument 6 to "calculate_variable_window_bounds" has incompatible
+        # type "Optional[ndarray]"; expected "ndarray"
+        return calculate_variable_window_bounds(
+            num_values,
+            self.window_size,
+            min_periods,
+            center,  # type: ignore[arg-type]
+            closed,
+            self.index_array,  # type: ignore[arg-type]
+        )
+
+
+class VariableOffsetWindowIndexer(BaseIndexer):
+    """
+    Calculate window boundaries based on a non-fixed offset such as a BusinessDay.
+
+    Examples
+    --------
+    >>> from pandas.api.indexers import VariableOffsetWindowIndexer
+    >>> df = pd.DataFrame(range(10), index=pd.date_range("2020", periods=10))
+    >>> offset = pd.offsets.BDay(1)
+    >>> indexer = VariableOffsetWindowIndexer(index=df.index, offset=offset)
+    >>> df
+                0
+    2020-01-01  0
+    2020-01-02  1
+    2020-01-03  2
+    2020-01-04  3
+    2020-01-05  4
+    2020-01-06  5
+    2020-01-07  6
+    2020-01-08  7
+    2020-01-09  8
+    2020-01-10  9
+    >>> df.rolling(indexer).sum()
+                   0
+    2020-01-01   0.0
+    2020-01-02   1.0
+    2020-01-03   2.0
+    2020-01-04   3.0
+    2020-01-05   7.0
+    2020-01-06  12.0
+    2020-01-07   6.0
+    2020-01-08   7.0
+    2020-01-09   8.0
+    2020-01-10   9.0
+    """
+
+    def __init__(
+        self,
+        index_array: np.ndarray | None = None,
+        window_size: int = 0,
+        index: DatetimeIndex | None = None,
+        offset: BaseOffset | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(index_array, window_size, **kwargs)
+        if not isinstance(index, DatetimeIndex):
+            raise ValueError("index must be a DatetimeIndex.")
+        self.index = index
+        if not isinstance(offset, BaseOffset):
+            raise ValueError("offset must be a DateOffset-like object.")
+        self.offset = offset
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if step is not None:
+            raise NotImplementedError("step not implemented for variable offset window")
+        if num_values <= 0:
+            return np.empty(0, dtype="int64"), np.empty(0, dtype="int64")
+
+        # if windows is variable, default is 'right', otherwise default is 'both'
+        if closed is None:
+            closed = "right" if self.index is not None else "both"
+
+        right_closed = closed in ["right", "both"]
+        left_closed = closed in ["left", "both"]
+
+        if self.index[num_values - 1] < self.index[0]:
+            index_growth_sign = -1
+        else:
+            index_growth_sign = 1
+        offset_diff = index_growth_sign * self.offset
+
+        start = np.empty(num_values, dtype="int64")
+        start.fill(-1)
+        end = np.empty(num_values, dtype="int64")
+        end.fill(-1)
+
+        start[0] = 0
+
+        # right endpoint is closed
+        if right_closed:
+            end[0] = 1
+        # right endpoint is open
+        else:
+            end[0] = 0
+
+        zero = timedelta(0)
+        # start is start of slice interval (including)
+        # end is end of slice interval (not including)
+        for i in range(1, num_values):
+            end_bound = self.index[i]
+            start_bound = end_bound - offset_diff
+
+            # left endpoint is closed
+            if left_closed:
+                start_bound -= Nano(1)
+
+            # advance the start bound until we are
+            # within the constraint
+            start[i] = i
+            for j in range(start[i - 1], i):
+                start_diff = (self.index[j] - start_bound) * index_growth_sign
+                if start_diff > zero:
+                    start[i] = j
+                    break
+
+            # end bound is previous end
+            # or current index
+            end_diff = (self.index[end[i - 1]] - end_bound) * index_growth_sign
+            if end_diff == zero and not right_closed:
+                end[i] = end[i - 1] + 1
+            elif end_diff <= zero:
+                end[i] = i + 1
+            else:
+                end[i] = end[i - 1]
+
+            # right endpoint is open
+            if not right_closed:
+                end[i] -= 1
+
+        return start, end
+
+
+class ExpandingIndexer(BaseIndexer):
+    """Calculate expanding window bounds, mimicking df.expanding()"""
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return (
+            np.zeros(num_values, dtype=np.int64),
+            np.arange(1, num_values + 1, dtype=np.int64),
+        )
+
+
+class FixedForwardWindowIndexer(BaseIndexer):
+    """
+    Creates window boundaries for fixed-length windows that include the current row.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]})
+    >>> df
+         B
+    0  0.0
+    1  1.0
+    2  2.0
+    3  NaN
+    4  4.0
+
+    >>> indexer = pd.api.indexers.FixedForwardWindowIndexer(window_size=2)
+    >>> df.rolling(window=indexer, min_periods=1).sum()
+         B
+    0  1.0
+    1  3.0
+    2  2.0
+    3  4.0
+    4  4.0
+    """
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        if center:
+            raise ValueError("Forward-looking windows can't have center=True")
+        if closed is not None:
+            raise ValueError(
+                "Forward-looking windows don't support setting the closed argument"
+            )
+        if step is None:
+            step = 1
+
+        start = np.arange(0, num_values, step, dtype="int64")
+        end = start + self.window_size
+        if self.window_size:
+            end = np.clip(end, 0, num_values)
+
+        return start, end
+
+
+class GroupbyIndexer(BaseIndexer):
+    """Calculate bounds to compute groupby rolling, mimicking df.groupby().rolling()"""
+
+    def __init__(
+        self,
+        index_array: np.ndarray | None = None,
+        window_size: int | BaseIndexer = 0,
+        groupby_indices: dict | None = None,
+        window_indexer: type[BaseIndexer] = BaseIndexer,
+        indexer_kwargs: dict | None = None,
+        **kwargs,
+    ) -> None:
+        """
+        Parameters
+        ----------
+        index_array : np.ndarray or None
+            np.ndarray of the index of the original object that we are performing
+            a chained groupby operation over. This index has been pre-sorted relative to
+            the groups
+        window_size : int or BaseIndexer
+            window size during the windowing operation
+        groupby_indices : dict or None
+            dict of {group label: [positional index of rows belonging to the group]}
+        window_indexer : BaseIndexer
+            BaseIndexer class determining the start and end bounds of each group
+        indexer_kwargs : dict or None
+            Custom kwargs to be passed to window_indexer
+        **kwargs :
+            keyword arguments that will be available when get_window_bounds is called
+        """
+        self.groupby_indices = groupby_indices or {}
+        self.window_indexer = window_indexer
+        self.indexer_kwargs = indexer_kwargs.copy() if indexer_kwargs else {}
+        super().__init__(
+            index_array=index_array,
+            window_size=self.indexer_kwargs.pop("window_size", window_size),
+            **kwargs,
+        )
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        # 1) For each group, get the indices that belong to the group
+        # 2) Use the indices to calculate the start & end bounds of the window
+        # 3) Append the window bounds in group order
+        start_arrays = []
+        end_arrays = []
+        window_indices_start = 0
+        for key, indices in self.groupby_indices.items():
+            index_array: np.ndarray | None
+
+            if self.index_array is not None:
+                index_array = self.index_array.take(ensure_platform_int(indices))
+            else:
+                index_array = self.index_array
+            indexer = self.window_indexer(
+                index_array=index_array,
+                window_size=self.window_size,
+                **self.indexer_kwargs,
+            )
+            start, end = indexer.get_window_bounds(
+                len(indices), min_periods, center, closed, step
+            )
+            start = start.astype(np.int64)
+            end = end.astype(np.int64)
+            assert len(start) == len(
+                end
+            ), "these should be equal in length from get_window_bounds"
+            # Cannot use groupby_indices as they might not be monotonic with the object
+            # we're rolling over
+            window_indices = np.arange(
+                window_indices_start, window_indices_start + len(indices)
+            )
+            window_indices_start += len(indices)
+            # Extend as we'll be slicing window like [start, end)
+            window_indices = np.append(window_indices, [window_indices[-1] + 1]).astype(
+                np.int64, copy=False
+            )
+            start_arrays.append(window_indices.take(ensure_platform_int(start)))
+            end_arrays.append(window_indices.take(ensure_platform_int(end)))
+        if len(start_arrays) == 0:
+            return np.array([], dtype=np.int64), np.array([], dtype=np.int64)
+        start = np.concatenate(start_arrays)
+        end = np.concatenate(end_arrays)
+        return start, end
+
+
+class ExponentialMovingWindowIndexer(BaseIndexer):
+    """Calculate ewm window bounds (the entire window)"""
+
+    @Appender(get_window_bounds_doc)
+    def get_window_bounds(
+        self,
+        num_values: int = 0,
+        min_periods: int | None = None,
+        center: bool | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+    ) -> tuple[np.ndarray, np.ndarray]:
+        return np.array([0], dtype=np.int64), np.array([num_values], dtype=np.int64)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexers/utils.py b/.venv/lib/python3.13/site-packages/pandas/core/indexers/utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..55bb58f3108c3d7004058494284ea6fb4b2fca7f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexers/utils.py
@@ -0,0 +1,553 @@
+"""
+Low-dependency indexing utilities.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.common import (
+    is_array_like,
+    is_bool_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import AnyArrayLike
+
+    from pandas.core.frame import DataFrame
+    from pandas.core.indexes.base import Index
+
+# -----------------------------------------------------------
+# Indexer Identification
+
+
+def is_valid_positional_slice(slc: slice) -> bool:
+    """
+    Check if a slice object can be interpreted as a positional indexer.
+
+    Parameters
+    ----------
+    slc : slice
+
+    Returns
+    -------
+    bool
+
+    Notes
+    -----
+    A valid positional slice may also be interpreted as a label-based slice
+    depending on the index being sliced.
+    """
+    return (
+        lib.is_int_or_none(slc.start)
+        and lib.is_int_or_none(slc.stop)
+        and lib.is_int_or_none(slc.step)
+    )
+
+
+def is_list_like_indexer(key) -> bool:
+    """
+    Check if we have a list-like indexer that is *not* a NamedTuple.
+
+    Parameters
+    ----------
+    key : object
+
+    Returns
+    -------
+    bool
+    """
+    # allow a list_like, but exclude NamedTuples which can be indexers
+    return is_list_like(key) and not (isinstance(key, tuple) and type(key) is not tuple)
+
+
+def is_scalar_indexer(indexer, ndim: int) -> bool:
+    """
+    Return True if we are all scalar indexers.
+
+    Parameters
+    ----------
+    indexer : object
+    ndim : int
+        Number of dimensions in the object being indexed.
+
+    Returns
+    -------
+    bool
+    """
+    if ndim == 1 and is_integer(indexer):
+        # GH37748: allow indexer to be an integer for Series
+        return True
+    if isinstance(indexer, tuple) and len(indexer) == ndim:
+        return all(is_integer(x) for x in indexer)
+    return False
+
+
+def is_empty_indexer(indexer) -> bool:
+    """
+    Check if we have an empty indexer.
+
+    Parameters
+    ----------
+    indexer : object
+
+    Returns
+    -------
+    bool
+    """
+    if is_list_like(indexer) and not len(indexer):
+        return True
+    if not isinstance(indexer, tuple):
+        indexer = (indexer,)
+    return any(isinstance(idx, np.ndarray) and len(idx) == 0 for idx in indexer)
+
+
+# -----------------------------------------------------------
+# Indexer Validation
+
+
+def check_setitem_lengths(indexer, value, values) -> bool:
+    """
+    Validate that value and indexer are the same length.
+
+    An special-case is allowed for when the indexer is a boolean array
+    and the number of true values equals the length of ``value``. In
+    this case, no exception is raised.
+
+    Parameters
+    ----------
+    indexer : sequence
+        Key for the setitem.
+    value : array-like
+        Value for the setitem.
+    values : array-like
+        Values being set into.
+
+    Returns
+    -------
+    bool
+        Whether this is an empty listlike setting which is a no-op.
+
+    Raises
+    ------
+    ValueError
+        When the indexer is an ndarray or list and the lengths don't match.
+    """
+    no_op = False
+
+    if isinstance(indexer, (np.ndarray, list)):
+        # We can ignore other listlikes because they are either
+        #  a) not necessarily 1-D indexers, e.g. tuple
+        #  b) boolean indexers e.g. BoolArray
+        if is_list_like(value):
+            if len(indexer) != len(value) and values.ndim == 1:
+                # boolean with truth values == len of the value is ok too
+                if isinstance(indexer, list):
+                    indexer = np.array(indexer)
+                if not (
+                    isinstance(indexer, np.ndarray)
+                    and indexer.dtype == np.bool_
+                    and indexer.sum() == len(value)
+                ):
+                    raise ValueError(
+                        "cannot set using a list-like indexer "
+                        "with a different length than the value"
+                    )
+            if not len(indexer):
+                no_op = True
+
+    elif isinstance(indexer, slice):
+        if is_list_like(value):
+            if len(value) != length_of_indexer(indexer, values) and values.ndim == 1:
+                # In case of two dimensional value is used row-wise and broadcasted
+                raise ValueError(
+                    "cannot set using a slice indexer with a "
+                    "different length than the value"
+                )
+            if not len(value):
+                no_op = True
+
+    return no_op
+
+
+def validate_indices(indices: np.ndarray, n: int) -> None:
+    """
+    Perform bounds-checking for an indexer.
+
+    -1 is allowed for indicating missing values.
+
+    Parameters
+    ----------
+    indices : ndarray
+    n : int
+        Length of the array being indexed.
+
+    Raises
+    ------
+    ValueError
+
+    Examples
+    --------
+    >>> validate_indices(np.array([1, 2]), 3) # OK
+
+    >>> validate_indices(np.array([1, -2]), 3)
+    Traceback (most recent call last):
+        ...
+    ValueError: negative dimensions are not allowed
+
+    >>> validate_indices(np.array([1, 2, 3]), 3)
+    Traceback (most recent call last):
+        ...
+    IndexError: indices are out-of-bounds
+
+    >>> validate_indices(np.array([-1, -1]), 0) # OK
+
+    >>> validate_indices(np.array([0, 1]), 0)
+    Traceback (most recent call last):
+        ...
+    IndexError: indices are out-of-bounds
+    """
+    if len(indices):
+        min_idx = indices.min()
+        if min_idx < -1:
+            msg = f"'indices' contains values less than allowed ({min_idx} < -1)"
+            raise ValueError(msg)
+
+        max_idx = indices.max()
+        if max_idx >= n:
+            raise IndexError("indices are out-of-bounds")
+
+
+# -----------------------------------------------------------
+# Indexer Conversion
+
+
+def maybe_convert_indices(indices, n: int, verify: bool = True) -> np.ndarray:
+    """
+    Attempt to convert indices into valid, positive indices.
+
+    If we have negative indices, translate to positive here.
+    If we have indices that are out-of-bounds, raise an IndexError.
+
+    Parameters
+    ----------
+    indices : array-like
+        Array of indices that we are to convert.
+    n : int
+        Number of elements in the array that we are indexing.
+    verify : bool, default True
+        Check that all entries are between 0 and n - 1, inclusive.
+
+    Returns
+    -------
+    array-like
+        An array-like of positive indices that correspond to the ones
+        that were passed in initially to this function.
+
+    Raises
+    ------
+    IndexError
+        One of the converted indices either exceeded the number of,
+        elements (specified by `n`), or was still negative.
+    """
+    if isinstance(indices, list):
+        indices = np.array(indices)
+        if len(indices) == 0:
+            # If `indices` is empty, np.array will return a float,
+            # and will cause indexing errors.
+            return np.empty(0, dtype=np.intp)
+
+    mask = indices < 0
+    if mask.any():
+        indices = indices.copy()
+        indices[mask] += n
+
+    if verify:
+        mask = (indices >= n) | (indices < 0)
+        if mask.any():
+            raise IndexError("indices are out-of-bounds")
+    return indices
+
+
+# -----------------------------------------------------------
+# Unsorted
+
+
+def length_of_indexer(indexer, target=None) -> int:
+    """
+    Return the expected length of target[indexer]
+
+    Returns
+    -------
+    int
+    """
+    if target is not None and isinstance(indexer, slice):
+        target_len = len(target)
+        start = indexer.start
+        stop = indexer.stop
+        step = indexer.step
+        if start is None:
+            start = 0
+        elif start < 0:
+            start += target_len
+        if stop is None or stop > target_len:
+            stop = target_len
+        elif stop < 0:
+            stop += target_len
+        if step is None:
+            step = 1
+        elif step < 0:
+            start, stop = stop + 1, start + 1
+            step = -step
+        return (stop - start + step - 1) // step
+    elif isinstance(indexer, (ABCSeries, ABCIndex, np.ndarray, list)):
+        if isinstance(indexer, list):
+            indexer = np.array(indexer)
+
+        if indexer.dtype == bool:
+            # GH#25774
+            return indexer.sum()
+        return len(indexer)
+    elif isinstance(indexer, range):
+        return (indexer.stop - indexer.start) // indexer.step
+    elif not is_list_like_indexer(indexer):
+        return 1
+    raise AssertionError("cannot find the length of the indexer")
+
+
+def disallow_ndim_indexing(result) -> None:
+    """
+    Helper function to disallow multi-dimensional indexing on 1D Series/Index.
+
+    GH#27125 indexer like idx[:, None] expands dim, but we cannot do that
+    and keep an index, so we used to return ndarray, which was deprecated
+    in GH#30588.
+    """
+    if np.ndim(result) > 1:
+        raise ValueError(
+            "Multi-dimensional indexing (e.g. `obj[:, None]`) is no longer "
+            "supported. Convert to a numpy array before indexing instead."
+        )
+
+
+def unpack_1tuple(tup):
+    """
+    If we have a length-1 tuple/list that contains a slice, unpack to just
+    the slice.
+
+    Notes
+    -----
+    The list case is deprecated.
+    """
+    if len(tup) == 1 and isinstance(tup[0], slice):
+        # if we don't have a MultiIndex, we may still be able to handle
+        #  a 1-tuple.  see test_1tuple_without_multiindex
+
+        if isinstance(tup, list):
+            # GH#31299
+            raise ValueError(
+                "Indexing with a single-item list containing a "
+                "slice is not allowed. Pass a tuple instead.",
+            )
+
+        return tup[0]
+    return tup
+
+
+def check_key_length(columns: Index, key, value: DataFrame) -> None:
+    """
+    Checks if a key used as indexer has the same length as the columns it is
+    associated with.
+
+    Parameters
+    ----------
+    columns : Index The columns of the DataFrame to index.
+    key : A list-like of keys to index with.
+    value : DataFrame The value to set for the keys.
+
+    Raises
+    ------
+    ValueError: If the length of key is not equal to the number of columns in value
+                or if the number of columns referenced by key is not equal to number
+                of columns.
+    """
+    if columns.is_unique:
+        if len(value.columns) != len(key):
+            raise ValueError("Columns must be same length as key")
+    else:
+        # Missing keys in columns are represented as -1
+        if len(columns.get_indexer_non_unique(key)[0]) != len(value.columns):
+            raise ValueError("Columns must be same length as key")
+
+
+def unpack_tuple_and_ellipses(item: tuple):
+    """
+    Possibly unpack arr[..., n] to arr[n]
+    """
+    if len(item) > 1:
+        # Note: we are assuming this indexing is being done on a 1D arraylike
+        if item[0] is Ellipsis:
+            item = item[1:]
+        elif item[-1] is Ellipsis:
+            item = item[:-1]
+
+    if len(item) > 1:
+        raise IndexError("too many indices for array.")
+
+    item = item[0]
+    return item
+
+
+# -----------------------------------------------------------
+# Public indexer validation
+
+
+def check_array_indexer(array: AnyArrayLike, indexer: Any) -> Any:
+    """
+    Check if `indexer` is a valid array indexer for `array`.
+
+    For a boolean mask, `array` and `indexer` are checked to have the same
+    length. The dtype is validated, and if it is an integer or boolean
+    ExtensionArray, it is checked if there are missing values present, and
+    it is converted to the appropriate numpy array. Other dtypes will raise
+    an error.
+
+    Non-array indexers (integer, slice, Ellipsis, tuples, ..) are passed
+    through as is.
+
+    Parameters
+    ----------
+    array : array-like
+        The array that is being indexed (only used for the length).
+    indexer : array-like or list-like
+        The array-like that's used to index. List-like input that is not yet
+        a numpy array or an ExtensionArray is converted to one. Other input
+        types are passed through as is.
+
+    Returns
+    -------
+    numpy.ndarray
+        The validated indexer as a numpy array that can be used to index.
+
+    Raises
+    ------
+    IndexError
+        When the lengths don't match.
+    ValueError
+        When `indexer` cannot be converted to a numpy ndarray to index
+        (e.g. presence of missing values).
+
+    See Also
+    --------
+    api.types.is_bool_dtype : Check if `key` is of boolean dtype.
+
+    Examples
+    --------
+    When checking a boolean mask, a boolean ndarray is returned when the
+    arguments are all valid.
+
+    >>> mask = pd.array([True, False])
+    >>> arr = pd.array([1, 2])
+    >>> pd.api.indexers.check_array_indexer(arr, mask)
+    array([ True, False])
+
+    An IndexError is raised when the lengths don't match.
+
+    >>> mask = pd.array([True, False, True])
+    >>> pd.api.indexers.check_array_indexer(arr, mask)
+    Traceback (most recent call last):
+    ...
+    IndexError: Boolean index has wrong length: 3 instead of 2.
+
+    NA values in a boolean array are treated as False.
+
+    >>> mask = pd.array([True, pd.NA])
+    >>> pd.api.indexers.check_array_indexer(arr, mask)
+    array([ True, False])
+
+    A numpy boolean mask will get passed through (if the length is correct):
+
+    >>> mask = np.array([True, False])
+    >>> pd.api.indexers.check_array_indexer(arr, mask)
+    array([ True, False])
+
+    Similarly for integer indexers, an integer ndarray is returned when it is
+    a valid indexer, otherwise an error is  (for integer indexers, a matching
+    length is not required):
+
+    >>> indexer = pd.array([0, 2], dtype="Int64")
+    >>> arr = pd.array([1, 2, 3])
+    >>> pd.api.indexers.check_array_indexer(arr, indexer)
+    array([0, 2])
+
+    >>> indexer = pd.array([0, pd.NA], dtype="Int64")
+    >>> pd.api.indexers.check_array_indexer(arr, indexer)
+    Traceback (most recent call last):
+    ...
+    ValueError: Cannot index with an integer indexer containing NA values
+
+    For non-integer/boolean dtypes, an appropriate error is raised:
+
+    >>> indexer = np.array([0., 2.], dtype="float64")
+    >>> pd.api.indexers.check_array_indexer(arr, indexer)
+    Traceback (most recent call last):
+    ...
+    IndexError: arrays used as indices must be of integer or boolean type
+    """
+    from pandas.core.construction import array as pd_array
+
+    # whatever is not an array-like is returned as-is (possible valid array
+    # indexers that are not array-like: integer, slice, Ellipsis, None)
+    # In this context, tuples are not considered as array-like, as they have
+    # a specific meaning in indexing (multi-dimensional indexing)
+    if is_list_like(indexer):
+        if isinstance(indexer, tuple):
+            return indexer
+    else:
+        return indexer
+
+    # convert list-likes to array
+    if not is_array_like(indexer):
+        indexer = pd_array(indexer)
+        if len(indexer) == 0:
+            # empty list is converted to float array by pd.array
+            indexer = np.array([], dtype=np.intp)
+
+    dtype = indexer.dtype
+    if is_bool_dtype(dtype):
+        if isinstance(dtype, ExtensionDtype):
+            indexer = indexer.to_numpy(dtype=bool, na_value=False)
+        else:
+            indexer = np.asarray(indexer, dtype=bool)
+
+        # GH26658
+        if len(indexer) != len(array):
+            raise IndexError(
+                f"Boolean index has wrong length: "
+                f"{len(indexer)} instead of {len(array)}"
+            )
+    elif is_integer_dtype(dtype):
+        try:
+            indexer = np.asarray(indexer, dtype=np.intp)
+        except ValueError as err:
+            raise ValueError(
+                "Cannot index with an integer indexer containing NA values"
+            ) from err
+    else:
+        raise IndexError("arrays used as indices must be of integer or boolean type")
+
+    return indexer
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/accessors.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/accessors.py
new file mode 100644
index 0000000000000000000000000000000000000000..7e3ba4089ff60e9ab226f7536c6be1843be8ea59
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/accessors.py
@@ -0,0 +1,643 @@
+"""
+datetimelike delegation
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_integer_dtype,
+    is_list_like,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import ABCSeries
+
+from pandas.core.accessor import (
+    PandasDelegate,
+    delegate_names,
+)
+from pandas.core.arrays import (
+    DatetimeArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.arrow.array import ArrowExtensionArray
+from pandas.core.base import (
+    NoNewAttributesMixin,
+    PandasObject,
+)
+from pandas.core.indexes.datetimes import DatetimeIndex
+from pandas.core.indexes.timedeltas import TimedeltaIndex
+
+if TYPE_CHECKING:
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+class Properties(PandasDelegate, PandasObject, NoNewAttributesMixin):
+    _hidden_attrs = PandasObject._hidden_attrs | {
+        "orig",
+        "name",
+    }
+
+    def __init__(self, data: Series, orig) -> None:
+        if not isinstance(data, ABCSeries):
+            raise TypeError(
+                f"cannot convert an object of type {type(data)} to a datetimelike index"
+            )
+
+        self._parent = data
+        self.orig = orig
+        self.name = getattr(data, "name", None)
+        self._freeze()
+
+    def _get_values(self):
+        data = self._parent
+        if lib.is_np_dtype(data.dtype, "M"):
+            return DatetimeIndex(data, copy=False, name=self.name)
+
+        elif isinstance(data.dtype, DatetimeTZDtype):
+            return DatetimeIndex(data, copy=False, name=self.name)
+
+        elif lib.is_np_dtype(data.dtype, "m"):
+            return TimedeltaIndex(data, copy=False, name=self.name)
+
+        elif isinstance(data.dtype, PeriodDtype):
+            return PeriodArray(data, copy=False)
+
+        raise TypeError(
+            f"cannot convert an object of type {type(data)} to a datetimelike index"
+        )
+
+    def _delegate_property_get(self, name: str):
+        from pandas import Series
+
+        values = self._get_values()
+
+        result = getattr(values, name)
+
+        # maybe need to upcast (ints)
+        if isinstance(result, np.ndarray):
+            if is_integer_dtype(result):
+                result = result.astype("int64")
+        elif not is_list_like(result):
+            return result
+
+        result = np.asarray(result)
+
+        if self.orig is not None:
+            index = self.orig.index
+        else:
+            index = self._parent.index
+        # return the result as a Series
+        result = Series(result, index=index, name=self.name).__finalize__(self._parent)
+
+        # setting this object will show a SettingWithCopyWarning/Error
+        result._is_copy = (
+            "modifications to a property of a datetimelike "
+            "object are not supported and are discarded. "
+            "Change values on the original."
+        )
+
+        return result
+
+    def _delegate_property_set(self, name: str, value, *args, **kwargs):
+        raise ValueError(
+            "modifications to a property of a datetimelike object are not supported. "
+            "Change values on the original."
+        )
+
+    def _delegate_method(self, name: str, *args, **kwargs):
+        from pandas import Series
+
+        values = self._get_values()
+
+        method = getattr(values, name)
+        result = method(*args, **kwargs)
+
+        if not is_list_like(result):
+            return result
+
+        result = Series(result, index=self._parent.index, name=self.name).__finalize__(
+            self._parent
+        )
+
+        # setting this object will show a SettingWithCopyWarning/Error
+        result._is_copy = (
+            "modifications to a method of a datetimelike "
+            "object are not supported and are discarded. "
+            "Change values on the original."
+        )
+
+        return result
+
+
+@delegate_names(
+    delegate=ArrowExtensionArray,
+    accessors=TimedeltaArray._datetimelike_ops,
+    typ="property",
+    accessor_mapping=lambda x: f"_dt_{x}",
+    raise_on_missing=False,
+)
+@delegate_names(
+    delegate=ArrowExtensionArray,
+    accessors=TimedeltaArray._datetimelike_methods,
+    typ="method",
+    accessor_mapping=lambda x: f"_dt_{x}",
+    raise_on_missing=False,
+)
+@delegate_names(
+    delegate=ArrowExtensionArray,
+    accessors=DatetimeArray._datetimelike_ops,
+    typ="property",
+    accessor_mapping=lambda x: f"_dt_{x}",
+    raise_on_missing=False,
+)
+@delegate_names(
+    delegate=ArrowExtensionArray,
+    accessors=DatetimeArray._datetimelike_methods,
+    typ="method",
+    accessor_mapping=lambda x: f"_dt_{x}",
+    raise_on_missing=False,
+)
+class ArrowTemporalProperties(PandasDelegate, PandasObject, NoNewAttributesMixin):
+    def __init__(self, data: Series, orig) -> None:
+        if not isinstance(data, ABCSeries):
+            raise TypeError(
+                f"cannot convert an object of type {type(data)} to a datetimelike index"
+            )
+
+        self._parent = data
+        self._orig = orig
+        self._freeze()
+
+    def _delegate_property_get(self, name: str):
+        if not hasattr(self._parent.array, f"_dt_{name}"):
+            raise NotImplementedError(
+                f"dt.{name} is not supported for {self._parent.dtype}"
+            )
+        result = getattr(self._parent.array, f"_dt_{name}")
+
+        if not is_list_like(result):
+            return result
+
+        if self._orig is not None:
+            index = self._orig.index
+        else:
+            index = self._parent.index
+        # return the result as a Series, which is by definition a copy
+        result = type(self._parent)(
+            result, index=index, name=self._parent.name
+        ).__finalize__(self._parent)
+
+        return result
+
+    def _delegate_method(self, name: str, *args, **kwargs):
+        if not hasattr(self._parent.array, f"_dt_{name}"):
+            raise NotImplementedError(
+                f"dt.{name} is not supported for {self._parent.dtype}"
+            )
+
+        result = getattr(self._parent.array, f"_dt_{name}")(*args, **kwargs)
+
+        if self._orig is not None:
+            index = self._orig.index
+        else:
+            index = self._parent.index
+        # return the result as a Series, which is by definition a copy
+        result = type(self._parent)(
+            result, index=index, name=self._parent.name
+        ).__finalize__(self._parent)
+
+        return result
+
+    def to_pytimedelta(self):
+        return cast(ArrowExtensionArray, self._parent.array)._dt_to_pytimedelta()
+
+    def to_pydatetime(self):
+        # GH#20306
+        warnings.warn(
+            f"The behavior of {type(self).__name__}.to_pydatetime is deprecated, "
+            "in a future version this will return a Series containing python "
+            "datetime objects instead of an ndarray. To retain the old behavior, "
+            "call `np.array` on the result",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return cast(ArrowExtensionArray, self._parent.array)._dt_to_pydatetime()
+
+    def isocalendar(self) -> DataFrame:
+        from pandas import DataFrame
+
+        result = (
+            cast(ArrowExtensionArray, self._parent.array)
+            ._dt_isocalendar()
+            ._pa_array.combine_chunks()
+        )
+        iso_calendar_df = DataFrame(
+            {
+                col: type(self._parent.array)(result.field(i))  # type: ignore[call-arg]
+                for i, col in enumerate(["year", "week", "day"])
+            }
+        )
+        return iso_calendar_df
+
+    @property
+    def components(self) -> DataFrame:
+        from pandas import DataFrame
+
+        components_df = DataFrame(
+            {
+                col: getattr(self._parent.array, f"_dt_{col}")
+                for col in [
+                    "days",
+                    "hours",
+                    "minutes",
+                    "seconds",
+                    "milliseconds",
+                    "microseconds",
+                    "nanoseconds",
+                ]
+            }
+        )
+        return components_df
+
+
+@delegate_names(
+    delegate=DatetimeArray,
+    accessors=DatetimeArray._datetimelike_ops + ["unit"],
+    typ="property",
+)
+@delegate_names(
+    delegate=DatetimeArray,
+    accessors=DatetimeArray._datetimelike_methods + ["as_unit"],
+    typ="method",
+)
+class DatetimeProperties(Properties):
+    """
+    Accessor object for datetimelike properties of the Series values.
+
+    Examples
+    --------
+    >>> seconds_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="s"))
+    >>> seconds_series
+    0   2000-01-01 00:00:00
+    1   2000-01-01 00:00:01
+    2   2000-01-01 00:00:02
+    dtype: datetime64[ns]
+    >>> seconds_series.dt.second
+    0    0
+    1    1
+    2    2
+    dtype: int32
+
+    >>> hours_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="h"))
+    >>> hours_series
+    0   2000-01-01 00:00:00
+    1   2000-01-01 01:00:00
+    2   2000-01-01 02:00:00
+    dtype: datetime64[ns]
+    >>> hours_series.dt.hour
+    0    0
+    1    1
+    2    2
+    dtype: int32
+
+    >>> quarters_series = pd.Series(pd.date_range("2000-01-01", periods=3, freq="QE"))
+    >>> quarters_series
+    0   2000-03-31
+    1   2000-06-30
+    2   2000-09-30
+    dtype: datetime64[ns]
+    >>> quarters_series.dt.quarter
+    0    1
+    1    2
+    2    3
+    dtype: int32
+
+    Returns a Series indexed like the original Series.
+    Raises TypeError if the Series does not contain datetimelike values.
+    """
+
+    def to_pydatetime(self) -> np.ndarray:
+        """
+        Return the data as an array of :class:`datetime.datetime` objects.
+
+        .. deprecated:: 2.1.0
+
+            The current behavior of dt.to_pydatetime is deprecated.
+            In a future version this will return a Series containing python
+            datetime objects instead of a ndarray.
+
+        Timezone information is retained if present.
+
+        .. warning::
+
+           Python's datetime uses microsecond resolution, which is lower than
+           pandas (nanosecond). The values are truncated.
+
+        Returns
+        -------
+        numpy.ndarray
+            Object dtype array containing native Python datetime objects.
+
+        See Also
+        --------
+        datetime.datetime : Standard library value for a datetime.
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.date_range('20180310', periods=2))
+        >>> s
+        0   2018-03-10
+        1   2018-03-11
+        dtype: datetime64[ns]
+
+        >>> s.dt.to_pydatetime()
+        array([datetime.datetime(2018, 3, 10, 0, 0),
+               datetime.datetime(2018, 3, 11, 0, 0)], dtype=object)
+
+        pandas' nanosecond precision is truncated to microseconds.
+
+        >>> s = pd.Series(pd.date_range('20180310', periods=2, freq='ns'))
+        >>> s
+        0   2018-03-10 00:00:00.000000000
+        1   2018-03-10 00:00:00.000000001
+        dtype: datetime64[ns]
+
+        >>> s.dt.to_pydatetime()
+        array([datetime.datetime(2018, 3, 10, 0, 0),
+               datetime.datetime(2018, 3, 10, 0, 0)], dtype=object)
+        """
+        # GH#20306
+        warnings.warn(
+            f"The behavior of {type(self).__name__}.to_pydatetime is deprecated, "
+            "in a future version this will return a Series containing python "
+            "datetime objects instead of an ndarray. To retain the old behavior, "
+            "call `np.array` on the result",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._get_values().to_pydatetime()
+
+    @property
+    def freq(self):
+        return self._get_values().inferred_freq
+
+    def isocalendar(self) -> DataFrame:
+        """
+        Calculate year, week, and day according to the ISO 8601 standard.
+
+        Returns
+        -------
+        DataFrame
+            With columns year, week and day.
+
+        See Also
+        --------
+        Timestamp.isocalendar : Function return a 3-tuple containing ISO year,
+            week number, and weekday for the given Timestamp object.
+        datetime.date.isocalendar : Return a named tuple object with
+            three components: year, week and weekday.
+
+        Examples
+        --------
+        >>> ser = pd.to_datetime(pd.Series(["2010-01-01", pd.NaT]))
+        >>> ser.dt.isocalendar()
+           year  week  day
+        0  2009    53     5
+        1      
+        >>> ser.dt.isocalendar().week
+        0      53
+        1    
+        Name: week, dtype: UInt32
+        """
+        return self._get_values().isocalendar().set_index(self._parent.index)
+
+
+@delegate_names(
+    delegate=TimedeltaArray, accessors=TimedeltaArray._datetimelike_ops, typ="property"
+)
+@delegate_names(
+    delegate=TimedeltaArray,
+    accessors=TimedeltaArray._datetimelike_methods,
+    typ="method",
+)
+class TimedeltaProperties(Properties):
+    """
+    Accessor object for datetimelike properties of the Series values.
+
+    Returns a Series indexed like the original Series.
+    Raises TypeError if the Series does not contain datetimelike values.
+
+    Examples
+    --------
+    >>> seconds_series = pd.Series(
+    ...     pd.timedelta_range(start="1 second", periods=3, freq="s")
+    ... )
+    >>> seconds_series
+    0   0 days 00:00:01
+    1   0 days 00:00:02
+    2   0 days 00:00:03
+    dtype: timedelta64[ns]
+    >>> seconds_series.dt.seconds
+    0    1
+    1    2
+    2    3
+    dtype: int32
+    """
+
+    def to_pytimedelta(self) -> np.ndarray:
+        """
+        Return an array of native :class:`datetime.timedelta` objects.
+
+        Python's standard `datetime` library uses a different representation
+        timedelta's. This method converts a Series of pandas Timedeltas
+        to `datetime.timedelta` format with the same length as the original
+        Series.
+
+        Returns
+        -------
+        numpy.ndarray
+            Array of 1D containing data with `datetime.timedelta` type.
+
+        See Also
+        --------
+        datetime.timedelta : A duration expressing the difference
+            between two date, time, or datetime.
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit="d"))
+        >>> s
+        0   0 days
+        1   1 days
+        2   2 days
+        3   3 days
+        4   4 days
+        dtype: timedelta64[ns]
+
+        >>> s.dt.to_pytimedelta()
+        array([datetime.timedelta(0), datetime.timedelta(days=1),
+        datetime.timedelta(days=2), datetime.timedelta(days=3),
+        datetime.timedelta(days=4)], dtype=object)
+        """
+        return self._get_values().to_pytimedelta()
+
+    @property
+    def components(self):
+        """
+        Return a Dataframe of the components of the Timedeltas.
+
+        Returns
+        -------
+        DataFrame
+
+        Examples
+        --------
+        >>> s = pd.Series(pd.to_timedelta(np.arange(5), unit='s'))
+        >>> s
+        0   0 days 00:00:00
+        1   0 days 00:00:01
+        2   0 days 00:00:02
+        3   0 days 00:00:03
+        4   0 days 00:00:04
+        dtype: timedelta64[ns]
+        >>> s.dt.components
+           days  hours  minutes  seconds  milliseconds  microseconds  nanoseconds
+        0     0      0        0        0             0             0            0
+        1     0      0        0        1             0             0            0
+        2     0      0        0        2             0             0            0
+        3     0      0        0        3             0             0            0
+        4     0      0        0        4             0             0            0
+        """
+        return (
+            self._get_values()
+            .components.set_index(self._parent.index)
+            .__finalize__(self._parent)
+        )
+
+    @property
+    def freq(self):
+        return self._get_values().inferred_freq
+
+
+@delegate_names(
+    delegate=PeriodArray, accessors=PeriodArray._datetimelike_ops, typ="property"
+)
+@delegate_names(
+    delegate=PeriodArray, accessors=PeriodArray._datetimelike_methods, typ="method"
+)
+class PeriodProperties(Properties):
+    """
+    Accessor object for datetimelike properties of the Series values.
+
+    Returns a Series indexed like the original Series.
+    Raises TypeError if the Series does not contain datetimelike values.
+
+    Examples
+    --------
+    >>> seconds_series = pd.Series(
+    ...     pd.period_range(
+    ...         start="2000-01-01 00:00:00", end="2000-01-01 00:00:03", freq="s"
+    ...     )
+    ... )
+    >>> seconds_series
+    0    2000-01-01 00:00:00
+    1    2000-01-01 00:00:01
+    2    2000-01-01 00:00:02
+    3    2000-01-01 00:00:03
+    dtype: period[s]
+    >>> seconds_series.dt.second
+    0    0
+    1    1
+    2    2
+    3    3
+    dtype: int64
+
+    >>> hours_series = pd.Series(
+    ...     pd.period_range(start="2000-01-01 00:00", end="2000-01-01 03:00", freq="h")
+    ... )
+    >>> hours_series
+    0    2000-01-01 00:00
+    1    2000-01-01 01:00
+    2    2000-01-01 02:00
+    3    2000-01-01 03:00
+    dtype: period[h]
+    >>> hours_series.dt.hour
+    0    0
+    1    1
+    2    2
+    3    3
+    dtype: int64
+
+    >>> quarters_series = pd.Series(
+    ...     pd.period_range(start="2000-01-01", end="2000-12-31", freq="Q-DEC")
+    ... )
+    >>> quarters_series
+    0    2000Q1
+    1    2000Q2
+    2    2000Q3
+    3    2000Q4
+    dtype: period[Q-DEC]
+    >>> quarters_series.dt.quarter
+    0    1
+    1    2
+    2    3
+    3    4
+    dtype: int64
+    """
+
+
+class CombinedDatetimelikeProperties(
+    DatetimeProperties, TimedeltaProperties, PeriodProperties
+):
+    def __new__(cls, data: Series):  # pyright: ignore[reportInconsistentConstructor]
+        # CombinedDatetimelikeProperties isn't really instantiated. Instead
+        # we need to choose which parent (datetime or timedelta) is
+        # appropriate. Since we're checking the dtypes anyway, we'll just
+        # do all the validation here.
+
+        if not isinstance(data, ABCSeries):
+            raise TypeError(
+                f"cannot convert an object of type {type(data)} to a datetimelike index"
+            )
+
+        orig = data if isinstance(data.dtype, CategoricalDtype) else None
+        if orig is not None:
+            data = data._constructor(
+                orig.array,
+                name=orig.name,
+                copy=False,
+                dtype=orig._values.categories.dtype,
+                index=orig.index,
+            )
+
+        if isinstance(data.dtype, ArrowDtype) and data.dtype.kind in "Mm":
+            return ArrowTemporalProperties(data, orig)
+        if lib.is_np_dtype(data.dtype, "M"):
+            return DatetimeProperties(data, orig)
+        elif isinstance(data.dtype, DatetimeTZDtype):
+            return DatetimeProperties(data, orig)
+        elif lib.is_np_dtype(data.dtype, "m"):
+            return TimedeltaProperties(data, orig)
+        elif isinstance(data.dtype, PeriodDtype):
+            return PeriodProperties(data, orig)
+
+        raise AttributeError("Can only use .dt accessor with datetimelike values")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/api.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..15292953e72d00a8f57c34d2e2cc8a43f6863d39
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/api.py
@@ -0,0 +1,388 @@
+from __future__ import annotations
+
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    lib,
+)
+from pandas.errors import InvalidIndexError
+
+from pandas.core.dtypes.cast import find_common_type
+
+from pandas.core.algorithms import safe_sort
+from pandas.core.indexes.base import (
+    Index,
+    _new_Index,
+    ensure_index,
+    ensure_index_from_sequences,
+    get_unanimous_names,
+)
+from pandas.core.indexes.category import CategoricalIndex
+from pandas.core.indexes.datetimes import DatetimeIndex
+from pandas.core.indexes.interval import IntervalIndex
+from pandas.core.indexes.multi import MultiIndex
+from pandas.core.indexes.period import PeriodIndex
+from pandas.core.indexes.range import RangeIndex
+from pandas.core.indexes.timedeltas import TimedeltaIndex
+
+if TYPE_CHECKING:
+    from pandas._typing import Axis
+_sort_msg = textwrap.dedent(
+    """\
+Sorting because non-concatenation axis is not aligned. A future version
+of pandas will change to not sort by default.
+
+To accept the future behavior, pass 'sort=False'.
+
+To retain the current behavior and silence the warning, pass 'sort=True'.
+"""
+)
+
+
+__all__ = [
+    "Index",
+    "MultiIndex",
+    "CategoricalIndex",
+    "IntervalIndex",
+    "RangeIndex",
+    "InvalidIndexError",
+    "TimedeltaIndex",
+    "PeriodIndex",
+    "DatetimeIndex",
+    "_new_Index",
+    "NaT",
+    "ensure_index",
+    "ensure_index_from_sequences",
+    "get_objs_combined_axis",
+    "union_indexes",
+    "get_unanimous_names",
+    "all_indexes_same",
+    "default_index",
+    "safe_sort_index",
+]
+
+
+def get_objs_combined_axis(
+    objs,
+    intersect: bool = False,
+    axis: Axis = 0,
+    sort: bool = True,
+    copy: bool = False,
+) -> Index:
+    """
+    Extract combined index: return intersection or union (depending on the
+    value of "intersect") of indexes on given axis, or None if all objects
+    lack indexes (e.g. they are numpy arrays).
+
+    Parameters
+    ----------
+    objs : list
+        Series or DataFrame objects, may be mix of the two.
+    intersect : bool, default False
+        If True, calculate the intersection between indexes. Otherwise,
+        calculate the union.
+    axis : {0 or 'index', 1 or 'outer'}, default 0
+        The axis to extract indexes from.
+    sort : bool, default True
+        Whether the result index should come out sorted or not.
+    copy : bool, default False
+        If True, return a copy of the combined index.
+
+    Returns
+    -------
+    Index
+    """
+    obs_idxes = [obj._get_axis(axis) for obj in objs]
+    return _get_combined_index(obs_idxes, intersect=intersect, sort=sort, copy=copy)
+
+
+def _get_distinct_objs(objs: list[Index]) -> list[Index]:
+    """
+    Return a list with distinct elements of "objs" (different ids).
+    Preserves order.
+    """
+    ids: set[int] = set()
+    res = []
+    for obj in objs:
+        if id(obj) not in ids:
+            ids.add(id(obj))
+            res.append(obj)
+    return res
+
+
+def _get_combined_index(
+    indexes: list[Index],
+    intersect: bool = False,
+    sort: bool = False,
+    copy: bool = False,
+) -> Index:
+    """
+    Return the union or intersection of indexes.
+
+    Parameters
+    ----------
+    indexes : list of Index or list objects
+        When intersect=True, do not accept list of lists.
+    intersect : bool, default False
+        If True, calculate the intersection between indexes. Otherwise,
+        calculate the union.
+    sort : bool, default False
+        Whether the result index should come out sorted or not.
+    copy : bool, default False
+        If True, return a copy of the combined index.
+
+    Returns
+    -------
+    Index
+    """
+    # TODO: handle index names!
+    indexes = _get_distinct_objs(indexes)
+    if len(indexes) == 0:
+        index = Index([])
+    elif len(indexes) == 1:
+        index = indexes[0]
+    elif intersect:
+        index = indexes[0]
+        for other in indexes[1:]:
+            index = index.intersection(other)
+    else:
+        index = union_indexes(indexes, sort=False)
+        index = ensure_index(index)
+
+    if sort:
+        index = safe_sort_index(index)
+    # GH 29879
+    if copy:
+        index = index.copy()
+
+    return index
+
+
+def safe_sort_index(index: Index) -> Index:
+    """
+    Returns the sorted index
+
+    We keep the dtypes and the name attributes.
+
+    Parameters
+    ----------
+    index : an Index
+
+    Returns
+    -------
+    Index
+    """
+    if index.is_monotonic_increasing:
+        return index
+
+    try:
+        array_sorted = safe_sort(index)
+    except TypeError:
+        pass
+    else:
+        if isinstance(array_sorted, Index):
+            return array_sorted
+
+        array_sorted = cast(np.ndarray, array_sorted)
+        if isinstance(index, MultiIndex):
+            index = MultiIndex.from_tuples(array_sorted, names=index.names)
+        else:
+            index = Index(array_sorted, name=index.name, dtype=index.dtype)
+
+    return index
+
+
+def union_indexes(indexes, sort: bool | None = True) -> Index:
+    """
+    Return the union of indexes.
+
+    The behavior of sort and names is not consistent.
+
+    Parameters
+    ----------
+    indexes : list of Index or list objects
+    sort : bool, default True
+        Whether the result index should come out sorted or not.
+
+    Returns
+    -------
+    Index
+    """
+    if len(indexes) == 0:
+        raise AssertionError("Must have at least 1 Index to union")
+    if len(indexes) == 1:
+        result = indexes[0]
+        if isinstance(result, list):
+            if not sort:
+                result = Index(result)
+            else:
+                result = Index(sorted(result))
+        return result
+
+    indexes, kind = _sanitize_and_check(indexes)
+
+    def _unique_indices(inds, dtype) -> Index:
+        """
+        Concatenate indices and remove duplicates.
+
+        Parameters
+        ----------
+        inds : list of Index or list objects
+        dtype : dtype to set for the resulting Index
+
+        Returns
+        -------
+        Index
+        """
+        if all(isinstance(ind, Index) for ind in inds):
+            inds = [ind.astype(dtype, copy=False) for ind in inds]
+            result = inds[0].unique()
+            other = inds[1].append(inds[2:])
+            diff = other[result.get_indexer_for(other) == -1]
+            if len(diff):
+                result = result.append(diff.unique())
+            if sort:
+                result = result.sort_values()
+            return result
+
+        def conv(i):
+            if isinstance(i, Index):
+                i = i.tolist()
+            return i
+
+        return Index(
+            lib.fast_unique_multiple_list([conv(i) for i in inds], sort=sort),
+            dtype=dtype,
+        )
+
+    def _find_common_index_dtype(inds):
+        """
+        Finds a common type for the indexes to pass through to resulting index.
+
+        Parameters
+        ----------
+        inds: list of Index or list objects
+
+        Returns
+        -------
+        The common type or None if no indexes were given
+        """
+        dtypes = [idx.dtype for idx in indexes if isinstance(idx, Index)]
+        if dtypes:
+            dtype = find_common_type(dtypes)
+        else:
+            dtype = None
+
+        return dtype
+
+    if kind == "special":
+        result = indexes[0]
+
+        dtis = [x for x in indexes if isinstance(x, DatetimeIndex)]
+        dti_tzs = [x for x in dtis if x.tz is not None]
+        if len(dti_tzs) not in [0, len(dtis)]:
+            # TODO: this behavior is not tested (so may not be desired),
+            #  but is kept in order to keep behavior the same when
+            #  deprecating union_many
+            # test_frame_from_dict_with_mixed_indexes
+            raise TypeError("Cannot join tz-naive with tz-aware DatetimeIndex")
+
+        if len(dtis) == len(indexes):
+            sort = True
+            result = indexes[0]
+
+        elif len(dtis) > 1:
+            # If we have mixed timezones, our casting behavior may depend on
+            #  the order of indexes, which we don't want.
+            sort = False
+
+            # TODO: what about Categorical[dt64]?
+            # test_frame_from_dict_with_mixed_indexes
+            indexes = [x.astype(object, copy=False) for x in indexes]
+            result = indexes[0]
+
+        for other in indexes[1:]:
+            result = result.union(other, sort=None if sort else False)
+        return result
+
+    elif kind == "array":
+        dtype = _find_common_index_dtype(indexes)
+        index = indexes[0]
+        if not all(index.equals(other) for other in indexes[1:]):
+            index = _unique_indices(indexes, dtype)
+
+        name = get_unanimous_names(*indexes)[0]
+        if name != index.name:
+            index = index.rename(name)
+        return index
+    else:  # kind='list'
+        dtype = _find_common_index_dtype(indexes)
+        return _unique_indices(indexes, dtype)
+
+
+def _sanitize_and_check(indexes):
+    """
+    Verify the type of indexes and convert lists to Index.
+
+    Cases:
+
+    - [list, list, ...]: Return ([list, list, ...], 'list')
+    - [list, Index, ...]: Return _sanitize_and_check([Index, Index, ...])
+        Lists are sorted and converted to Index.
+    - [Index, Index, ...]: Return ([Index, Index, ...], TYPE)
+        TYPE = 'special' if at least one special type, 'array' otherwise.
+
+    Parameters
+    ----------
+    indexes : list of Index or list objects
+
+    Returns
+    -------
+    sanitized_indexes : list of Index or list objects
+    type : {'list', 'array', 'special'}
+    """
+    kinds = list({type(index) for index in indexes})
+
+    if list in kinds:
+        if len(kinds) > 1:
+            indexes = [
+                Index(list(x)) if not isinstance(x, Index) else x for x in indexes
+            ]
+            kinds.remove(list)
+        else:
+            return indexes, "list"
+
+    if len(kinds) > 1 or Index not in kinds:
+        return indexes, "special"
+    else:
+        return indexes, "array"
+
+
+def all_indexes_same(indexes) -> bool:
+    """
+    Determine if all indexes contain the same elements.
+
+    Parameters
+    ----------
+    indexes : iterable of Index objects
+
+    Returns
+    -------
+    bool
+        True if all indexes contain the same elements, False otherwise.
+    """
+    itr = iter(indexes)
+    first = next(itr)
+    return all(first.equals(index) for index in itr)
+
+
+def default_index(n: int) -> RangeIndex:
+    rng = range(n)
+    return RangeIndex._simple_new(rng, name=None)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/base.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..ab3eaac852f7a506a35abab154dcc10321f8b5fb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/base.py
@@ -0,0 +1,7943 @@
+from __future__ import annotations
+
+from collections import abc
+from datetime import datetime
+import functools
+from itertools import zip_longest
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    ClassVar,
+    Literal,
+    NoReturn,
+    cast,
+    final,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import (
+    get_option,
+    using_copy_on_write,
+    using_string_dtype,
+)
+
+from pandas._libs import (
+    NaT,
+    algos as libalgos,
+    index as libindex,
+    lib,
+    writers,
+)
+from pandas._libs.internals import BlockValuesRefs
+import pandas._libs.join as libjoin
+from pandas._libs.lib import (
+    is_datetime_array,
+    no_default,
+)
+from pandas._libs.tslibs import (
+    IncompatibleFrequency,
+    OutOfBoundsDatetime,
+    Timestamp,
+    tz_compare,
+)
+from pandas._typing import (
+    AnyAll,
+    ArrayLike,
+    Axes,
+    Axis,
+    DropKeep,
+    DtypeObj,
+    F,
+    IgnoreRaise,
+    IndexLabel,
+    JoinHow,
+    Level,
+    NaPosition,
+    ReindexMethod,
+    Self,
+    Shape,
+    npt,
+)
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    DuplicateLabelError,
+    InvalidIndexError,
+)
+from pandas.util._decorators import (
+    Appender,
+    cache_readonly,
+    deprecate_nonkeyword_arguments,
+    doc,
+)
+from pandas.util._exceptions import (
+    find_stack_level,
+    rewrite_exception,
+)
+
+from pandas.core.dtypes.astype import (
+    astype_array,
+    astype_is_view,
+)
+from pandas.core.dtypes.cast import (
+    LossySetitemError,
+    can_hold_element,
+    common_dtype_categorical_compat,
+    find_result_type,
+    infer_dtype_from,
+    maybe_cast_pointwise_result,
+    np_can_hold_element,
+)
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    ensure_object,
+    ensure_platform_int,
+    is_any_real_numeric_dtype,
+    is_bool_dtype,
+    is_ea_or_datetimelike_dtype,
+    is_float,
+    is_hashable,
+    is_integer,
+    is_iterator,
+    is_list_like,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_scalar,
+    is_signed_integer_dtype,
+    is_string_dtype,
+    needs_i8_conversion,
+    pandas_dtype,
+    validate_all_hashable,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    IntervalDtype,
+    PeriodDtype,
+    SparseDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCCategoricalIndex,
+    ABCDataFrame,
+    ABCDatetimeIndex,
+    ABCIntervalIndex,
+    ABCMultiIndex,
+    ABCPeriodIndex,
+    ABCRangeIndex,
+    ABCSeries,
+    ABCTimedeltaIndex,
+)
+from pandas.core.dtypes.inference import is_dict_like
+from pandas.core.dtypes.missing import (
+    array_equivalent,
+    is_valid_na_for_dtype,
+    isna,
+)
+
+from pandas.core import (
+    arraylike,
+    nanops,
+    ops,
+)
+from pandas.core.accessor import CachedAccessor
+import pandas.core.algorithms as algos
+from pandas.core.array_algos.putmask import (
+    setitem_datetimelike_compat,
+    validate_putmask,
+)
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    BaseMaskedArray,
+    Categorical,
+    DatetimeArray,
+    ExtensionArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.string_ import (
+    StringArray,
+    StringDtype,
+)
+from pandas.core.base import (
+    IndexOpsMixin,
+    PandasObject,
+)
+import pandas.core.common as com
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+    sanitize_array,
+)
+from pandas.core.indexers import (
+    disallow_ndim_indexing,
+    is_valid_positional_slice,
+)
+from pandas.core.indexes.frozen import FrozenList
+from pandas.core.missing import clean_reindex_fill_method
+from pandas.core.ops import get_op_result_name
+from pandas.core.ops.invalid import make_invalid_op
+from pandas.core.sorting import (
+    ensure_key_mapped,
+    get_group_index_sorter,
+    nargsort,
+)
+from pandas.core.strings.accessor import StringMethods
+
+from pandas.io.formats.printing import (
+    PrettyDict,
+    default_pprint,
+    format_object_summary,
+    pprint_thing,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Sequence,
+    )
+
+    from pandas import (
+        CategoricalIndex,
+        DataFrame,
+        MultiIndex,
+        Series,
+    )
+    from pandas.core.arrays import (
+        IntervalArray,
+        PeriodArray,
+    )
+
+__all__ = ["Index"]
+
+_unsortable_types = frozenset(("mixed", "mixed-integer"))
+
+_index_doc_kwargs: dict[str, str] = {
+    "klass": "Index",
+    "inplace": "",
+    "target_klass": "Index",
+    "raises_section": "",
+    "unique": "Index",
+    "duplicated": "np.ndarray",
+}
+_index_shared_docs: dict[str, str] = {}
+str_t = str
+
+_dtype_obj = np.dtype("object")
+
+_masked_engines = {
+    "Complex128": libindex.MaskedComplex128Engine,
+    "Complex64": libindex.MaskedComplex64Engine,
+    "Float64": libindex.MaskedFloat64Engine,
+    "Float32": libindex.MaskedFloat32Engine,
+    "UInt64": libindex.MaskedUInt64Engine,
+    "UInt32": libindex.MaskedUInt32Engine,
+    "UInt16": libindex.MaskedUInt16Engine,
+    "UInt8": libindex.MaskedUInt8Engine,
+    "Int64": libindex.MaskedInt64Engine,
+    "Int32": libindex.MaskedInt32Engine,
+    "Int16": libindex.MaskedInt16Engine,
+    "Int8": libindex.MaskedInt8Engine,
+    "boolean": libindex.MaskedBoolEngine,
+    "double[pyarrow]": libindex.MaskedFloat64Engine,
+    "float64[pyarrow]": libindex.MaskedFloat64Engine,
+    "float32[pyarrow]": libindex.MaskedFloat32Engine,
+    "float[pyarrow]": libindex.MaskedFloat32Engine,
+    "uint64[pyarrow]": libindex.MaskedUInt64Engine,
+    "uint32[pyarrow]": libindex.MaskedUInt32Engine,
+    "uint16[pyarrow]": libindex.MaskedUInt16Engine,
+    "uint8[pyarrow]": libindex.MaskedUInt8Engine,
+    "int64[pyarrow]": libindex.MaskedInt64Engine,
+    "int32[pyarrow]": libindex.MaskedInt32Engine,
+    "int16[pyarrow]": libindex.MaskedInt16Engine,
+    "int8[pyarrow]": libindex.MaskedInt8Engine,
+    "bool[pyarrow]": libindex.MaskedBoolEngine,
+}
+
+
+def _maybe_return_indexers(meth: F) -> F:
+    """
+    Decorator to simplify 'return_indexers' checks in Index.join.
+    """
+
+    @functools.wraps(meth)
+    def join(
+        self,
+        other: Index,
+        *,
+        how: JoinHow = "left",
+        level=None,
+        return_indexers: bool = False,
+        sort: bool = False,
+    ):
+        join_index, lidx, ridx = meth(self, other, how=how, level=level, sort=sort)
+        if not return_indexers:
+            return join_index
+
+        if lidx is not None:
+            lidx = ensure_platform_int(lidx)
+        if ridx is not None:
+            ridx = ensure_platform_int(ridx)
+        return join_index, lidx, ridx
+
+    return cast(F, join)
+
+
+def _new_Index(cls, d):
+    """
+    This is called upon unpickling, rather than the default which doesn't
+    have arguments and breaks __new__.
+    """
+    # required for backward compat, because PI can't be instantiated with
+    # ordinals through __new__ GH #13277
+    if issubclass(cls, ABCPeriodIndex):
+        from pandas.core.indexes.period import _new_PeriodIndex
+
+        return _new_PeriodIndex(cls, **d)
+
+    if issubclass(cls, ABCMultiIndex):
+        if "labels" in d and "codes" not in d:
+            # GH#23752 "labels" kwarg has been replaced with "codes"
+            d["codes"] = d.pop("labels")
+
+        # Since this was a valid MultiIndex at pickle-time, we don't need to
+        #  check validty at un-pickle time.
+        d["verify_integrity"] = False
+
+    elif "dtype" not in d and "data" in d:
+        # Prevent Index.__new__ from conducting inference;
+        #  "data" key not in RangeIndex
+        d["dtype"] = d["data"].dtype
+    return cls.__new__(cls, **d)
+
+
+class Index(IndexOpsMixin, PandasObject):
+    """
+    Immutable sequence used for indexing and alignment.
+
+    The basic object storing axis labels for all pandas objects.
+
+    .. versionchanged:: 2.0.0
+
+       Index can hold all numpy numeric dtypes (except float16). Previously only
+       int64/uint64/float64 dtypes were accepted.
+
+    Parameters
+    ----------
+    data : array-like (1-dimensional)
+    dtype : str, numpy.dtype, or ExtensionDtype, optional
+        Data type for the output Index. If not specified, this will be
+        inferred from `data`.
+        See the :ref:`user guide ` for more usages.
+    copy : bool, default False
+        Copy input data.
+    name : object
+        Name to be stored in the index.
+    tupleize_cols : bool (default: True)
+        When True, attempt to create a MultiIndex if possible.
+
+    See Also
+    --------
+    RangeIndex : Index implementing a monotonic integer range.
+    CategoricalIndex : Index of :class:`Categorical` s.
+    MultiIndex : A multi-level, or hierarchical Index.
+    IntervalIndex : An Index of :class:`Interval` s.
+    DatetimeIndex : Index of datetime64 data.
+    TimedeltaIndex : Index of timedelta64 data.
+    PeriodIndex : Index of Period data.
+
+    Notes
+    -----
+    An Index instance can **only** contain hashable objects.
+    An Index instance *can not* hold numpy float16 dtype.
+
+    Examples
+    --------
+    >>> pd.Index([1, 2, 3])
+    Index([1, 2, 3], dtype='int64')
+
+    >>> pd.Index(list('abc'))
+    Index(['a', 'b', 'c'], dtype='object')
+
+    >>> pd.Index([1, 2, 3], dtype="uint8")
+    Index([1, 2, 3], dtype='uint8')
+    """
+
+    # similar to __array_priority__, positions Index after Series and DataFrame
+    #  but before ExtensionArray.  Should NOT be overridden by subclasses.
+    __pandas_priority__ = 2000
+
+    # Cython methods; see github.com/cython/cython/issues/2647
+    #  for why we need to wrap these instead of making them class attributes
+    # Moreover, cython will choose the appropriate-dtyped sub-function
+    #  given the dtypes of the passed arguments
+
+    @final
+    def _left_indexer_unique(self, other: Self) -> npt.NDArray[np.intp]:
+        # Caller is responsible for ensuring other.dtype == self.dtype
+        sv = self._get_join_target()
+        ov = other._get_join_target()
+        # similar but not identical to ov.searchsorted(sv)
+        return libjoin.left_join_indexer_unique(sv, ov)
+
+    @final
+    def _left_indexer(
+        self, other: Self
+    ) -> tuple[ArrayLike, npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        # Caller is responsible for ensuring other.dtype == self.dtype
+        sv = self._get_join_target()
+        ov = other._get_join_target()
+        joined_ndarray, lidx, ridx = libjoin.left_join_indexer(sv, ov)
+        joined = self._from_join_target(joined_ndarray)
+        return joined, lidx, ridx
+
+    @final
+    def _inner_indexer(
+        self, other: Self
+    ) -> tuple[ArrayLike, npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        # Caller is responsible for ensuring other.dtype == self.dtype
+        sv = self._get_join_target()
+        ov = other._get_join_target()
+        joined_ndarray, lidx, ridx = libjoin.inner_join_indexer(sv, ov)
+        joined = self._from_join_target(joined_ndarray)
+        return joined, lidx, ridx
+
+    @final
+    def _outer_indexer(
+        self, other: Self
+    ) -> tuple[ArrayLike, npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        # Caller is responsible for ensuring other.dtype == self.dtype
+        sv = self._get_join_target()
+        ov = other._get_join_target()
+        joined_ndarray, lidx, ridx = libjoin.outer_join_indexer(sv, ov)
+        joined = self._from_join_target(joined_ndarray)
+        return joined, lidx, ridx
+
+    _typ: str = "index"
+    _data: ExtensionArray | np.ndarray
+    _data_cls: type[ExtensionArray] | tuple[type[np.ndarray], type[ExtensionArray]] = (
+        np.ndarray,
+        ExtensionArray,
+    )
+    _id: object | None = None
+    _name: Hashable = None
+    # MultiIndex.levels previously allowed setting the index name. We
+    # don't allow this anymore, and raise if it happens rather than
+    # failing silently.
+    _no_setting_name: bool = False
+    _comparables: list[str] = ["name"]
+    _attributes: list[str] = ["name"]
+
+    @cache_readonly
+    def _can_hold_strings(self) -> bool:
+        return not is_numeric_dtype(self.dtype)
+
+    _engine_types: dict[np.dtype | ExtensionDtype, type[libindex.IndexEngine]] = {
+        np.dtype(np.int8): libindex.Int8Engine,
+        np.dtype(np.int16): libindex.Int16Engine,
+        np.dtype(np.int32): libindex.Int32Engine,
+        np.dtype(np.int64): libindex.Int64Engine,
+        np.dtype(np.uint8): libindex.UInt8Engine,
+        np.dtype(np.uint16): libindex.UInt16Engine,
+        np.dtype(np.uint32): libindex.UInt32Engine,
+        np.dtype(np.uint64): libindex.UInt64Engine,
+        np.dtype(np.float32): libindex.Float32Engine,
+        np.dtype(np.float64): libindex.Float64Engine,
+        np.dtype(np.complex64): libindex.Complex64Engine,
+        np.dtype(np.complex128): libindex.Complex128Engine,
+    }
+
+    @property
+    def _engine_type(
+        self,
+    ) -> type[libindex.IndexEngine | libindex.ExtensionEngine]:
+        return self._engine_types.get(self.dtype, libindex.ObjectEngine)
+
+    # whether we support partial string indexing. Overridden
+    # in DatetimeIndex and PeriodIndex
+    _supports_partial_string_indexing = False
+
+    _accessors = {"str"}
+
+    str = CachedAccessor("str", StringMethods)
+
+    _references = None
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data=None,
+        dtype=None,
+        copy: bool = False,
+        name=None,
+        tupleize_cols: bool = True,
+    ) -> Self:
+        from pandas.core.indexes.range import RangeIndex
+
+        name = maybe_extract_name(name, data, cls)
+
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        data_dtype = getattr(data, "dtype", None)
+
+        refs = None
+        if not copy and isinstance(data, (ABCSeries, Index)):
+            refs = data._references
+
+        is_pandas_object = isinstance(data, (ABCSeries, Index, ExtensionArray))
+
+        # range
+        if isinstance(data, (range, RangeIndex)):
+            result = RangeIndex(start=data, copy=copy, name=name)
+            if dtype is not None:
+                return result.astype(dtype, copy=False)
+            # error: Incompatible return value type (got "MultiIndex",
+            # expected "Self")
+            return result  # type: ignore[return-value]
+
+        elif is_ea_or_datetimelike_dtype(dtype):
+            # non-EA dtype indexes have special casting logic, so we punt here
+            if isinstance(data, (set, frozenset)):
+                data = list(data)
+
+        elif is_ea_or_datetimelike_dtype(data_dtype):
+            pass
+
+        elif isinstance(data, (np.ndarray, Index, ABCSeries)):
+            if isinstance(data, ABCMultiIndex):
+                data = data._values
+
+            if data.dtype.kind not in "iufcbmM":
+                # GH#11836 we need to avoid having numpy coerce
+                # things that look like ints/floats to ints unless
+                # they are actually ints, e.g. '0' and 0.0
+                # should not be coerced
+                data = com.asarray_tuplesafe(data, dtype=_dtype_obj)
+
+        elif is_scalar(data):
+            raise cls._raise_scalar_data_error(data)
+        elif hasattr(data, "__array__"):
+            return cls(np.asarray(data), dtype=dtype, copy=copy, name=name)
+        elif not is_list_like(data) and not isinstance(data, memoryview):
+            # 2022-11-16 the memoryview check is only necessary on some CI
+            #  builds, not clear why
+            raise cls._raise_scalar_data_error(data)
+
+        else:
+            if tupleize_cols:
+                # GH21470: convert iterable to list before determining if empty
+                if is_iterator(data):
+                    data = list(data)
+
+                if data and all(isinstance(e, tuple) for e in data):
+                    # we must be all tuples, otherwise don't construct
+                    # 10697
+                    from pandas.core.indexes.multi import MultiIndex
+
+                    # error: Incompatible return value type (got "MultiIndex",
+                    # expected "Self")
+                    return MultiIndex.from_tuples(  # type: ignore[return-value]
+                        data, names=name
+                    )
+            # other iterable of some kind
+
+            if not isinstance(data, (list, tuple)):
+                # we allow set/frozenset, which Series/sanitize_array does not, so
+                #  cast to list here
+                data = list(data)
+            if len(data) == 0:
+                # unlike Series, we default to object dtype:
+                data = np.array(data, dtype=object)
+
+            if len(data) and isinstance(data[0], tuple):
+                # Ensure we get 1-D array of tuples instead of 2D array.
+                data = com.asarray_tuplesafe(data, dtype=_dtype_obj)
+
+        try:
+            arr = sanitize_array(data, None, dtype=dtype, copy=copy)
+        except ValueError as err:
+            if "index must be specified when data is not list-like" in str(err):
+                raise cls._raise_scalar_data_error(data) from err
+            if "Data must be 1-dimensional" in str(err):
+                raise ValueError("Index data must be 1-dimensional") from err
+            raise
+        arr = ensure_wrapped_if_datetimelike(arr)
+
+        klass = cls._dtype_to_subclass(arr.dtype)
+
+        arr = klass._ensure_array(arr, arr.dtype, copy=False)
+        result = klass._simple_new(arr, name, refs=refs)
+        if dtype is None and is_pandas_object and data_dtype == np.object_:
+            if result.dtype != data_dtype:
+                warnings.warn(
+                    "Dtype inference on a pandas object "
+                    "(Series, Index, ExtensionArray) is deprecated. The Index "
+                    "constructor will keep the original dtype in the future. "
+                    "Call `infer_objects` on the result to get the old "
+                    "behavior.",
+                    FutureWarning,
+                    stacklevel=2,
+                )
+        return result  # type: ignore[return-value]
+
+    @classmethod
+    def _ensure_array(cls, data, dtype, copy: bool):
+        """
+        Ensure we have a valid array to pass to _simple_new.
+        """
+        if data.ndim > 1:
+            # GH#13601, GH#20285, GH#27125
+            raise ValueError("Index data must be 1-dimensional")
+        elif dtype == np.float16:
+            # float16 not supported (no indexing engine)
+            raise NotImplementedError("float16 indexes are not supported")
+
+        if copy:
+            # asarray_tuplesafe does not always copy underlying data,
+            #  so need to make sure that this happens
+            data = data.copy()
+        return data
+
+    @final
+    @classmethod
+    def _dtype_to_subclass(cls, dtype: DtypeObj):
+        # Delay import for perf. https://github.com/pandas-dev/pandas/pull/31423
+
+        if isinstance(dtype, ExtensionDtype):
+            return dtype.index_class
+
+        if dtype.kind == "M":
+            from pandas import DatetimeIndex
+
+            return DatetimeIndex
+
+        elif dtype.kind == "m":
+            from pandas import TimedeltaIndex
+
+            return TimedeltaIndex
+
+        elif dtype.kind == "O":
+            # NB: assuming away MultiIndex
+            return Index
+
+        elif issubclass(dtype.type, str) or is_numeric_dtype(dtype):
+            return Index
+
+        raise NotImplementedError(dtype)
+
+    # NOTE for new Index creation:
+
+    # - _simple_new: It returns new Index with the same type as the caller.
+    #   All metadata (such as name) must be provided by caller's responsibility.
+    #   Using _shallow_copy is recommended because it fills these metadata
+    #   otherwise specified.
+
+    # - _shallow_copy: It returns new Index with the same type (using
+    #   _simple_new), but fills caller's metadata otherwise specified. Passed
+    #   kwargs will overwrite corresponding metadata.
+
+    # See each method's docstring.
+
+    @classmethod
+    def _simple_new(
+        cls, values: ArrayLike, name: Hashable | None = None, refs=None
+    ) -> Self:
+        """
+        We require that we have a dtype compat for the values. If we are passed
+        a non-dtype compat, then coerce using the constructor.
+
+        Must be careful not to recurse.
+        """
+        assert isinstance(values, cls._data_cls), type(values)
+
+        result = object.__new__(cls)
+        result._data = values
+        result._name = name
+        result._cache = {}
+        result._reset_identity()
+        if refs is not None:
+            result._references = refs
+        else:
+            result._references = BlockValuesRefs()
+        result._references.add_index_reference(result)
+
+        return result
+
+    @classmethod
+    def _with_infer(cls, *args, **kwargs):
+        """
+        Constructor that uses the 1.0.x behavior inferring numeric dtypes
+        for ndarray[object] inputs.
+        """
+        result = cls(*args, **kwargs)
+
+        if result.dtype == _dtype_obj and not result._is_multi:
+            # error: Argument 1 to "maybe_convert_objects" has incompatible type
+            # "Union[ExtensionArray, ndarray[Any, Any]]"; expected
+            # "ndarray[Any, Any]"
+            values = lib.maybe_convert_objects(result._values)  # type: ignore[arg-type]
+            if values.dtype.kind in "iufb":
+                return Index(values, name=result.name)
+
+        return result
+
+    @cache_readonly
+    def _constructor(self) -> type[Self]:
+        return type(self)
+
+    @final
+    def _maybe_check_unique(self) -> None:
+        """
+        Check that an Index has no duplicates.
+
+        This is typically only called via
+        `NDFrame.flags.allows_duplicate_labels.setter` when it's set to
+        True (duplicates aren't allowed).
+
+        Raises
+        ------
+        DuplicateLabelError
+            When the index is not unique.
+        """
+        if not self.is_unique:
+            msg = """Index has duplicates."""
+            duplicates = self._format_duplicate_message()
+            msg += f"\n{duplicates}"
+
+            raise DuplicateLabelError(msg)
+
+    @final
+    def _format_duplicate_message(self) -> DataFrame:
+        """
+        Construct the DataFrame for a DuplicateLabelError.
+
+        This returns a DataFrame indicating the labels and positions
+        of duplicates in an index. This should only be called when it's
+        already known that duplicates are present.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'a'])
+        >>> idx._format_duplicate_message()
+            positions
+        label
+        a        [0, 2]
+        """
+        from pandas import Series
+
+        duplicates = self[self.duplicated(keep="first")].unique()
+        assert len(duplicates)
+
+        out = (
+            Series(np.arange(len(self)), copy=False)
+            .groupby(self, observed=False)
+            .agg(list)[duplicates]
+        )
+        if self._is_multi:
+            # test_format_duplicate_labels_message_multi
+            # error: "Type[Index]" has no attribute "from_tuples"  [attr-defined]
+            out.index = type(self).from_tuples(out.index)  # type: ignore[attr-defined]
+
+        if self.nlevels == 1:
+            out = out.rename_axis("label")
+        return out.to_frame(name="positions")
+
+    # --------------------------------------------------------------------
+    # Index Internals Methods
+
+    def _shallow_copy(self, values, name: Hashable = no_default) -> Self:
+        """
+        Create a new Index with the same class as the caller, don't copy the
+        data, use the same object attributes with passed in attributes taking
+        precedence.
+
+        *this is an internal non-public method*
+
+        Parameters
+        ----------
+        values : the values to create the new Index, optional
+        name : Label, defaults to self.name
+        """
+        name = self._name if name is no_default else name
+
+        return self._simple_new(values, name=name, refs=self._references)
+
+    def _view(self) -> Self:
+        """
+        fastpath to make a shallow copy, i.e. new object with same data.
+        """
+        result = self._simple_new(self._values, name=self._name, refs=self._references)
+
+        result._cache = self._cache
+        return result
+
+    @final
+    def _rename(self, name: Hashable) -> Self:
+        """
+        fastpath for rename if new name is already validated.
+        """
+        result = self._view()
+        result._name = name
+        return result
+
+    @final
+    def is_(self, other) -> bool:
+        """
+        More flexible, faster check like ``is`` but that works through views.
+
+        Note: this is *not* the same as ``Index.identical()``, which checks
+        that metadata is also the same.
+
+        Parameters
+        ----------
+        other : object
+            Other object to compare against.
+
+        Returns
+        -------
+        bool
+            True if both have same underlying data, False otherwise.
+
+        See Also
+        --------
+        Index.identical : Works like ``Index.is_`` but also checks metadata.
+
+        Examples
+        --------
+        >>> idx1 = pd.Index(['1', '2', '3'])
+        >>> idx1.is_(idx1.view())
+        True
+
+        >>> idx1.is_(idx1.copy())
+        False
+        """
+        if self is other:
+            return True
+        elif not hasattr(other, "_id"):
+            return False
+        elif self._id is None or other._id is None:
+            return False
+        else:
+            return self._id is other._id
+
+    @final
+    def _reset_identity(self) -> None:
+        """
+        Initializes or resets ``_id`` attribute with new object.
+        """
+        self._id = object()
+
+    @final
+    def _cleanup(self) -> None:
+        self._engine.clear_mapping()
+
+    @cache_readonly
+    def _engine(
+        self,
+    ) -> libindex.IndexEngine | libindex.ExtensionEngine | libindex.MaskedIndexEngine:
+        # For base class (object dtype) we get ObjectEngine
+        target_values = self._get_engine_target()
+
+        if isinstance(self._values, ArrowExtensionArray) and self.dtype.kind in "Mm":
+            import pyarrow as pa
+
+            pa_type = self._values._pa_array.type
+            if pa.types.is_timestamp(pa_type):
+                target_values = self._values._to_datetimearray()
+                return libindex.DatetimeEngine(target_values._ndarray)
+            elif pa.types.is_duration(pa_type):
+                target_values = self._values._to_timedeltaarray()
+                return libindex.TimedeltaEngine(target_values._ndarray)
+
+        if isinstance(target_values, ExtensionArray):
+            if isinstance(target_values, (BaseMaskedArray, ArrowExtensionArray)):
+                try:
+                    return _masked_engines[target_values.dtype.name](target_values)
+                except KeyError:
+                    # Not supported yet e.g. decimal
+                    pass
+            elif self._engine_type is libindex.ObjectEngine:
+                return libindex.ExtensionEngine(target_values)
+
+        target_values = cast(np.ndarray, target_values)
+        # to avoid a reference cycle, bind `target_values` to a local variable, so
+        # `self` is not passed into the lambda.
+        if target_values.dtype == bool:
+            return libindex.BoolEngine(target_values)
+        elif target_values.dtype == np.complex64:
+            return libindex.Complex64Engine(target_values)
+        elif target_values.dtype == np.complex128:
+            return libindex.Complex128Engine(target_values)
+        elif needs_i8_conversion(self.dtype):
+            # We need to keep M8/m8 dtype when initializing the Engine,
+            #  but don't want to change _get_engine_target bc it is used
+            #  elsewhere
+            # error: Item "ExtensionArray" of "Union[ExtensionArray,
+            # ndarray[Any, Any]]" has no attribute "_ndarray"  [union-attr]
+            target_values = self._data._ndarray  # type: ignore[union-attr]
+        elif is_string_dtype(self.dtype) and not is_object_dtype(self.dtype):
+            return libindex.StringObjectEngine(target_values, self.dtype.na_value)  # type: ignore[union-attr]
+
+        # error: Argument 1 to "ExtensionEngine" has incompatible type
+        # "ndarray[Any, Any]"; expected "ExtensionArray"
+        return self._engine_type(target_values)  # type: ignore[arg-type]
+
+    @final
+    @cache_readonly
+    def _dir_additions_for_owner(self) -> set[str_t]:
+        """
+        Add the string-like labels to the owner dataframe/series dir output.
+
+        If this is a MultiIndex, it's first level values are used.
+        """
+        return {
+            c
+            for c in self.unique(level=0)[: get_option("display.max_dir_items")]
+            if isinstance(c, str) and c.isidentifier()
+        }
+
+    # --------------------------------------------------------------------
+    # Array-Like Methods
+
+    # ndarray compat
+    def __len__(self) -> int:
+        """
+        Return the length of the Index.
+        """
+        return len(self._data)
+
+    def __array__(self, dtype=None, copy=None) -> np.ndarray:
+        """
+        The array interface, return my values.
+        """
+        if copy is None:
+            # Note, that the if branch exists for NumPy 1.x support
+            return np.asarray(self._data, dtype=dtype)
+
+        return np.array(self._data, dtype=dtype, copy=copy)
+
+    def __array_ufunc__(self, ufunc: np.ufunc, method: str_t, *inputs, **kwargs):
+        if any(isinstance(other, (ABCSeries, ABCDataFrame)) for other in inputs):
+            return NotImplemented
+
+        result = arraylike.maybe_dispatch_ufunc_to_dunder_op(
+            self, ufunc, method, *inputs, **kwargs
+        )
+        if result is not NotImplemented:
+            return result
+
+        if "out" in kwargs:
+            # e.g. test_dti_isub_tdi
+            return arraylike.dispatch_ufunc_with_out(
+                self, ufunc, method, *inputs, **kwargs
+            )
+
+        if method == "reduce":
+            result = arraylike.dispatch_reduction_ufunc(
+                self, ufunc, method, *inputs, **kwargs
+            )
+            if result is not NotImplemented:
+                return result
+
+        new_inputs = [x if x is not self else x._values for x in inputs]
+        result = getattr(ufunc, method)(*new_inputs, **kwargs)
+        if ufunc.nout == 2:
+            # i.e. np.divmod, np.modf, np.frexp
+            return tuple(self.__array_wrap__(x) for x in result)
+        elif method == "reduce":
+            result = lib.item_from_zerodim(result)
+            return result
+
+        if result.dtype == np.float16:
+            result = result.astype(np.float32)
+
+        return self.__array_wrap__(result)
+
+    @final
+    def __array_wrap__(self, result, context=None, return_scalar=False):
+        """
+        Gets called after a ufunc and other functions e.g. np.split.
+        """
+        result = lib.item_from_zerodim(result)
+        if (not isinstance(result, Index) and is_bool_dtype(result.dtype)) or np.ndim(
+            result
+        ) > 1:
+            # exclude Index to avoid warning from is_bool_dtype deprecation;
+            #  in the Index case it doesn't matter which path we go down.
+            # reached in plotting tests with e.g. np.nonzero(index)
+            return result
+
+        return Index(result, name=self.name)
+
+    @cache_readonly
+    def dtype(self) -> DtypeObj:
+        """
+        Return the dtype object of the underlying data.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.dtype
+        dtype('int64')
+        """
+        return self._data.dtype
+
+    @final
+    def ravel(self, order: str_t = "C") -> Self:
+        """
+        Return a view on self.
+
+        Returns
+        -------
+        Index
+
+        See Also
+        --------
+        numpy.ndarray.ravel : Return a flattened array.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3], index=['a', 'b', 'c'])
+        >>> s.index.ravel()
+        Index(['a', 'b', 'c'], dtype='object')
+        """
+        return self[:]
+
+    def view(self, cls=None):
+        # we need to see if we are subclassing an
+        # index type here
+        if cls is not None and not hasattr(cls, "_typ"):
+            dtype = cls
+            if isinstance(cls, str):
+                dtype = pandas_dtype(cls)
+
+            if needs_i8_conversion(dtype):
+                idx_cls = self._dtype_to_subclass(dtype)
+                arr = self.array.view(dtype)
+                if isinstance(arr, ExtensionArray):
+                    # here we exclude non-supported dt64/td64 dtypes
+                    return idx_cls._simple_new(
+                        arr, name=self.name, refs=self._references
+                    )
+                return arr
+
+            result = self._data.view(cls)
+        else:
+            if cls is not None:
+                warnings.warn(
+                    # GH#55709
+                    f"Passing a type in {type(self).__name__}.view is deprecated "
+                    "and will raise in a future version. "
+                    "Call view without any argument to retain the old behavior.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+            result = self._view()
+        if isinstance(result, Index):
+            result._id = self._id
+        return result
+
+    def astype(self, dtype, copy: bool = True):
+        """
+        Create an Index with values cast to dtypes.
+
+        The class of a new Index is determined by dtype. When conversion is
+        impossible, a TypeError exception is raised.
+
+        Parameters
+        ----------
+        dtype : numpy dtype or pandas type
+            Note that any signed integer `dtype` is treated as ``'int64'``,
+            and any unsigned integer `dtype` is treated as ``'uint64'``,
+            regardless of the size.
+        copy : bool, default True
+            By default, astype always returns a newly allocated object.
+            If copy is set to False and internal requirements on dtype are
+            satisfied, the original data is used to create a new Index
+            or the original Index is returned.
+
+        Returns
+        -------
+        Index
+            Index with values cast to specified dtype.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.astype('float')
+        Index([1.0, 2.0, 3.0], dtype='float64')
+        """
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        if self.dtype == dtype:
+            # Ensure that self.astype(self.dtype) is self
+            return self.copy() if copy else self
+
+        values = self._data
+        if isinstance(values, ExtensionArray):
+            with rewrite_exception(type(values).__name__, type(self).__name__):
+                new_values = values.astype(dtype, copy=copy)
+
+        elif isinstance(dtype, ExtensionDtype):
+            cls = dtype.construct_array_type()
+            # Note: for RangeIndex and CategoricalDtype self vs self._values
+            #  behaves differently here.
+            new_values = cls._from_sequence(self, dtype=dtype, copy=copy)
+
+        else:
+            # GH#13149 specifically use astype_array instead of astype
+            new_values = astype_array(values, dtype=dtype, copy=copy)
+
+        # pass copy=False because any copying will be done in the astype above
+        result = Index(new_values, name=self.name, dtype=new_values.dtype, copy=False)
+        if (
+            not copy
+            and self._references is not None
+            and astype_is_view(self.dtype, dtype)
+        ):
+            result._references = self._references
+            result._references.add_index_reference(result)
+        return result
+
+    _index_shared_docs[
+        "take"
+    ] = """
+        Return a new %(klass)s of the values selected by the indices.
+
+        For internal compatibility with numpy arrays.
+
+        Parameters
+        ----------
+        indices : array-like
+            Indices to be taken.
+        axis : int, optional
+            The axis over which to select values, always 0.
+        allow_fill : bool, default True
+        fill_value : scalar, default None
+            If allow_fill=True and fill_value is not None, indices specified by
+            -1 are regarded as NA. If Index doesn't hold NA, raise ValueError.
+
+        Returns
+        -------
+        Index
+            An index formed of elements at the given indices. Will be the same
+            type as self, except for RangeIndex.
+
+        See Also
+        --------
+        numpy.ndarray.take: Return an array formed from the
+            elements of a at the given indices.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.take([2, 2, 1, 2])
+        Index(['c', 'c', 'b', 'c'], dtype='object')
+        """
+
+    @Appender(_index_shared_docs["take"] % _index_doc_kwargs)
+    def take(
+        self,
+        indices,
+        axis: Axis = 0,
+        allow_fill: bool = True,
+        fill_value=None,
+        **kwargs,
+    ) -> Self:
+        if kwargs:
+            nv.validate_take((), kwargs)
+        if is_scalar(indices):
+            raise TypeError("Expected indices to be array-like")
+        indices = ensure_platform_int(indices)
+        allow_fill = self._maybe_disallow_fill(allow_fill, fill_value, indices)
+
+        # Note: we discard fill_value and use self._na_value, only relevant
+        #  in the case where allow_fill is True and fill_value is not None
+        values = self._values
+        if isinstance(values, np.ndarray):
+            taken = algos.take(
+                values, indices, allow_fill=allow_fill, fill_value=self._na_value
+            )
+        else:
+            # algos.take passes 'axis' keyword which not all EAs accept
+            taken = values.take(
+                indices, allow_fill=allow_fill, fill_value=self._na_value
+            )
+        return self._constructor._simple_new(taken, name=self.name)
+
+    @final
+    def _maybe_disallow_fill(self, allow_fill: bool, fill_value, indices) -> bool:
+        """
+        We only use pandas-style take when allow_fill is True _and_
+        fill_value is not None.
+        """
+        if allow_fill and fill_value is not None:
+            # only fill if we are passing a non-None fill_value
+            if self._can_hold_na:
+                if (indices < -1).any():
+                    raise ValueError(
+                        "When allow_fill=True and fill_value is not None, "
+                        "all indices must be >= -1"
+                    )
+            else:
+                cls_name = type(self).__name__
+                raise ValueError(
+                    f"Unable to fill values because {cls_name} cannot contain NA"
+                )
+        else:
+            allow_fill = False
+        return allow_fill
+
+    _index_shared_docs[
+        "repeat"
+    ] = """
+        Repeat elements of a %(klass)s.
+
+        Returns a new %(klass)s where each element of the current %(klass)s
+        is repeated consecutively a given number of times.
+
+        Parameters
+        ----------
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            %(klass)s.
+        axis : None
+            Must be ``None``. Has no effect but is accepted for compatibility
+            with numpy.
+
+        Returns
+        -------
+        %(klass)s
+            Newly created %(klass)s with repeated elements.
+
+        See Also
+        --------
+        Series.repeat : Equivalent function for Series.
+        numpy.repeat : Similar method for :class:`numpy.ndarray`.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx
+        Index(['a', 'b', 'c'], dtype='object')
+        >>> idx.repeat(2)
+        Index(['a', 'a', 'b', 'b', 'c', 'c'], dtype='object')
+        >>> idx.repeat([1, 2, 3])
+        Index(['a', 'b', 'b', 'c', 'c', 'c'], dtype='object')
+        """
+
+    @Appender(_index_shared_docs["repeat"] % _index_doc_kwargs)
+    def repeat(self, repeats, axis: None = None) -> Self:
+        repeats = ensure_platform_int(repeats)
+        nv.validate_repeat((), {"axis": axis})
+        res_values = self._values.repeat(repeats)
+
+        # _constructor so RangeIndex-> Index with an int64 dtype
+        return self._constructor._simple_new(res_values, name=self.name)
+
+    # --------------------------------------------------------------------
+    # Copying Methods
+
+    def copy(
+        self,
+        name: Hashable | None = None,
+        deep: bool = False,
+    ) -> Self:
+        """
+        Make a copy of this object.
+
+        Name is set on the new object.
+
+        Parameters
+        ----------
+        name : Label, optional
+            Set name for new object.
+        deep : bool, default False
+
+        Returns
+        -------
+        Index
+            Index refer to new object which is a copy of this object.
+
+        Notes
+        -----
+        In most cases, there should be no functional difference from using
+        ``deep``, but if ``deep`` is passed it will attempt to deepcopy.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> new_idx = idx.copy()
+        >>> idx is new_idx
+        False
+        """
+
+        name = self._validate_names(name=name, deep=deep)[0]
+        if deep:
+            new_data = self._data.copy()
+            new_index = type(self)._simple_new(new_data, name=name)
+        else:
+            new_index = self._rename(name=name)
+        return new_index
+
+    @final
+    def __copy__(self, **kwargs) -> Self:
+        return self.copy(**kwargs)
+
+    @final
+    def __deepcopy__(self, memo=None) -> Self:
+        """
+        Parameters
+        ----------
+        memo, default None
+            Standard signature. Unused
+        """
+        return self.copy(deep=True)
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+
+    @final
+    def __repr__(self) -> str_t:
+        """
+        Return a string representation for this object.
+        """
+        klass_name = type(self).__name__
+        data = self._format_data()
+        attrs = self._format_attrs()
+        attrs_str = [f"{k}={v}" for k, v in attrs]
+        prepr = ", ".join(attrs_str)
+
+        return f"{klass_name}({data}{prepr})"
+
+    @property
+    def _formatter_func(self):
+        """
+        Return the formatter function.
+        """
+        return default_pprint
+
+    @final
+    def _format_data(self, name=None) -> str_t:
+        """
+        Return the formatted data as a unicode string.
+        """
+        # do we want to justify (only do so for non-objects)
+        is_justify = True
+
+        if self.inferred_type == "string":
+            is_justify = False
+        elif isinstance(self.dtype, CategoricalDtype):
+            self = cast("CategoricalIndex", self)
+            if is_object_dtype(self.categories.dtype):
+                is_justify = False
+        elif isinstance(self, ABCRangeIndex):
+            # We will do the relevant formatting via attrs
+            return ""
+
+        return format_object_summary(
+            self,
+            self._formatter_func,
+            is_justify=is_justify,
+            name=name,
+            line_break_each_value=self._is_multi,
+        )
+
+    def _format_attrs(self) -> list[tuple[str_t, str_t | int | bool | None]]:
+        """
+        Return a list of tuples of the (attr,formatted_value).
+        """
+        attrs: list[tuple[str_t, str_t | int | bool | None]] = []
+
+        if not self._is_multi:
+            attrs.append(("dtype", f"'{self.dtype}'"))
+
+        if self.name is not None:
+            attrs.append(("name", default_pprint(self.name)))
+        elif self._is_multi and any(x is not None for x in self.names):
+            attrs.append(("names", default_pprint(self.names)))
+
+        max_seq_items = get_option("display.max_seq_items") or len(self)
+        if len(self) > max_seq_items:
+            attrs.append(("length", len(self)))
+        return attrs
+
+    @final
+    def _get_level_names(self) -> Hashable | Sequence[Hashable]:
+        """
+        Return a name or list of names with None replaced by the level number.
+        """
+        if self._is_multi:
+            return [
+                level if name is None else name for level, name in enumerate(self.names)
+            ]
+        else:
+            return 0 if self.name is None else self.name
+
+    @final
+    def _mpl_repr(self) -> np.ndarray:
+        # how to represent ourselves to matplotlib
+        if isinstance(self.dtype, np.dtype) and self.dtype.kind != "M":
+            return cast(np.ndarray, self.values)
+        return self.astype(object, copy=False)._values
+
+    def format(
+        self,
+        name: bool = False,
+        formatter: Callable | None = None,
+        na_rep: str_t = "NaN",
+    ) -> list[str_t]:
+        """
+        Render a string representation of the Index.
+        """
+        warnings.warn(
+            # GH#55413
+            f"{type(self).__name__}.format is deprecated and will be removed "
+            "in a future version. Convert using index.astype(str) or "
+            "index.map(formatter) instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        header = []
+        if name:
+            header.append(
+                pprint_thing(self.name, escape_chars=("\t", "\r", "\n"))
+                if self.name is not None
+                else ""
+            )
+
+        if formatter is not None:
+            return header + list(self.map(formatter))
+
+        return self._format_with_header(header=header, na_rep=na_rep)
+
+    _default_na_rep = "NaN"
+
+    @final
+    def _format_flat(
+        self,
+        *,
+        include_name: bool,
+        formatter: Callable | None = None,
+    ) -> list[str_t]:
+        """
+        Render a string representation of the Index.
+        """
+        header = []
+        if include_name:
+            header.append(
+                pprint_thing(self.name, escape_chars=("\t", "\r", "\n"))
+                if self.name is not None
+                else ""
+            )
+
+        if formatter is not None:
+            return header + list(self.map(formatter))
+
+        return self._format_with_header(header=header, na_rep=self._default_na_rep)
+
+    def _format_with_header(self, *, header: list[str_t], na_rep: str_t) -> list[str_t]:
+        from pandas.io.formats.format import format_array
+
+        values = self._values
+
+        if (
+            is_object_dtype(values.dtype)
+            or is_string_dtype(values.dtype)
+            or isinstance(self.dtype, (IntervalDtype, CategoricalDtype))
+        ):
+            # TODO: why do we need different justify for these cases?
+            justify = "all"
+        else:
+            justify = "left"
+        # passing leading_space=False breaks test_format_missing,
+        #  test_index_repr_in_frame_with_nan, but would otherwise make
+        #  trim_front unnecessary
+        formatted = format_array(values, None, justify=justify)
+        result = trim_front(formatted)
+        return header + result
+
+    def _get_values_for_csv(
+        self,
+        *,
+        na_rep: str_t = "",
+        decimal: str_t = ".",
+        float_format=None,
+        date_format=None,
+        quoting=None,
+    ) -> npt.NDArray[np.object_]:
+        return get_values_for_csv(
+            self._values,
+            na_rep=na_rep,
+            decimal=decimal,
+            float_format=float_format,
+            date_format=date_format,
+            quoting=quoting,
+        )
+
+    def _summary(self, name=None) -> str_t:
+        """
+        Return a summarized representation.
+
+        Parameters
+        ----------
+        name : str
+            name to use in the summary representation
+
+        Returns
+        -------
+        String with a summarized representation of the index
+        """
+        if len(self) > 0:
+            head = self[0]
+            if hasattr(head, "format") and not isinstance(head, str):
+                head = head.format()
+            elif needs_i8_conversion(self.dtype):
+                # e.g. Timedelta, display as values, not quoted
+                head = self._formatter_func(head).replace("'", "")
+            tail = self[-1]
+            if hasattr(tail, "format") and not isinstance(tail, str):
+                tail = tail.format()
+            elif needs_i8_conversion(self.dtype):
+                # e.g. Timedelta, display as values, not quoted
+                tail = self._formatter_func(tail).replace("'", "")
+
+            index_summary = f", {head} to {tail}"
+        else:
+            index_summary = ""
+
+        if name is None:
+            name = type(self).__name__
+        return f"{name}: {len(self)} entries{index_summary}"
+
+    # --------------------------------------------------------------------
+    # Conversion Methods
+
+    def to_flat_index(self) -> Self:
+        """
+        Identity method.
+
+        This is implemented for compatibility with subclass implementations
+        when chaining.
+
+        Returns
+        -------
+        pd.Index
+            Caller.
+
+        See Also
+        --------
+        MultiIndex.to_flat_index : Subclass implementation.
+        """
+        return self
+
+    @final
+    def to_series(self, index=None, name: Hashable | None = None) -> Series:
+        """
+        Create a Series with both index and values equal to the index keys.
+
+        Useful with map for returning an indexer based on an index.
+
+        Parameters
+        ----------
+        index : Index, optional
+            Index of resulting Series. If None, defaults to original index.
+        name : str, optional
+            Name of resulting Series. If None, defaults to name of original
+            index.
+
+        Returns
+        -------
+        Series
+            The dtype will be based on the type of the Index values.
+
+        See Also
+        --------
+        Index.to_frame : Convert an Index to a DataFrame.
+        Series.to_frame : Convert Series to DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['Ant', 'Bear', 'Cow'], name='animal')
+
+        By default, the original index and original name is reused.
+
+        >>> idx.to_series()
+        animal
+        Ant      Ant
+        Bear    Bear
+        Cow      Cow
+        Name: animal, dtype: object
+
+        To enforce a new index, specify new labels to ``index``:
+
+        >>> idx.to_series(index=[0, 1, 2])
+        0     Ant
+        1    Bear
+        2     Cow
+        Name: animal, dtype: object
+
+        To override the name of the resulting column, specify ``name``:
+
+        >>> idx.to_series(name='zoo')
+        animal
+        Ant      Ant
+        Bear    Bear
+        Cow      Cow
+        Name: zoo, dtype: object
+        """
+        from pandas import Series
+
+        if index is None:
+            index = self._view()
+        if name is None:
+            name = self.name
+
+        return Series(self._values.copy(), index=index, name=name)
+
+    def to_frame(
+        self, index: bool = True, name: Hashable = lib.no_default
+    ) -> DataFrame:
+        """
+        Create a DataFrame with a column containing the Index.
+
+        Parameters
+        ----------
+        index : bool, default True
+            Set the index of the returned DataFrame as the original Index.
+
+        name : object, defaults to index.name
+            The passed name should substitute for the index name (if it has
+            one).
+
+        Returns
+        -------
+        DataFrame
+            DataFrame containing the original Index data.
+
+        See Also
+        --------
+        Index.to_series : Convert an Index to a Series.
+        Series.to_frame : Convert Series to DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['Ant', 'Bear', 'Cow'], name='animal')
+        >>> idx.to_frame()
+               animal
+        animal
+        Ant       Ant
+        Bear     Bear
+        Cow       Cow
+
+        By default, the original Index is reused. To enforce a new Index:
+
+        >>> idx.to_frame(index=False)
+            animal
+        0   Ant
+        1  Bear
+        2   Cow
+
+        To override the name of the resulting column, specify `name`:
+
+        >>> idx.to_frame(index=False, name='zoo')
+            zoo
+        0   Ant
+        1  Bear
+        2   Cow
+        """
+        from pandas import DataFrame
+
+        if name is lib.no_default:
+            name = self._get_level_names()
+        result = DataFrame({name: self}, copy=not using_copy_on_write())
+
+        if index:
+            result.index = self
+        return result
+
+    # --------------------------------------------------------------------
+    # Name-Centric Methods
+
+    @property
+    def name(self) -> Hashable:
+        """
+        Return Index or MultiIndex name.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3], name='x')
+        >>> idx
+        Index([1, 2, 3], dtype='int64',  name='x')
+        >>> idx.name
+        'x'
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: Hashable) -> None:
+        if self._no_setting_name:
+            # Used in MultiIndex.levels to avoid silently ignoring name updates.
+            raise RuntimeError(
+                "Cannot set name on a level of a MultiIndex. Use "
+                "'MultiIndex.set_names' instead."
+            )
+        maybe_extract_name(value, None, type(self))
+        self._name = value
+
+    @final
+    def _validate_names(
+        self, name=None, names=None, deep: bool = False
+    ) -> list[Hashable]:
+        """
+        Handles the quirks of having a singular 'name' parameter for general
+        Index and plural 'names' parameter for MultiIndex.
+        """
+        from copy import deepcopy
+
+        if names is not None and name is not None:
+            raise TypeError("Can only provide one of `names` and `name`")
+        if names is None and name is None:
+            new_names = deepcopy(self.names) if deep else self.names
+        elif names is not None:
+            if not is_list_like(names):
+                raise TypeError("Must pass list-like as `names`.")
+            new_names = names
+        elif not is_list_like(name):
+            new_names = [name]
+        else:
+            new_names = name
+
+        if len(new_names) != len(self.names):
+            raise ValueError(
+                f"Length of new names must be {len(self.names)}, got {len(new_names)}"
+            )
+
+        # All items in 'new_names' need to be hashable
+        validate_all_hashable(*new_names, error_name=f"{type(self).__name__}.name")
+
+        return new_names
+
+    def _get_default_index_names(
+        self, names: Hashable | Sequence[Hashable] | None = None, default=None
+    ) -> list[Hashable]:
+        """
+        Get names of index.
+
+        Parameters
+        ----------
+        names : int, str or 1-dimensional list, default None
+            Index names to set.
+        default : str
+            Default name of index.
+
+        Raises
+        ------
+        TypeError
+            if names not str or list-like
+        """
+        from pandas.core.indexes.multi import MultiIndex
+
+        if names is not None:
+            if isinstance(names, (int, str)):
+                names = [names]
+
+        if not isinstance(names, list) and names is not None:
+            raise ValueError("Index names must be str or 1-dimensional list")
+
+        if not names:
+            if isinstance(self, MultiIndex):
+                names = com.fill_missing_names(self.names)
+            else:
+                names = [default] if self.name is None else [self.name]
+
+        return names
+
+    def _get_names(self) -> FrozenList:
+        return FrozenList((self.name,))
+
+    def _set_names(self, values, *, level=None) -> None:
+        """
+        Set new names on index. Each name has to be a hashable type.
+
+        Parameters
+        ----------
+        values : str or sequence
+            name(s) to set
+        level : int, level name, or sequence of int/level names (default None)
+            If the index is a MultiIndex (hierarchical), level(s) to set (None
+            for all levels).  Otherwise level must be None
+
+        Raises
+        ------
+        TypeError if each name is not hashable.
+        """
+        if not is_list_like(values):
+            raise ValueError("Names must be a list-like")
+        if len(values) != 1:
+            raise ValueError(f"Length of new names must be 1, got {len(values)}")
+
+        # GH 20527
+        # All items in 'name' need to be hashable:
+        validate_all_hashable(*values, error_name=f"{type(self).__name__}.name")
+
+        self._name = values[0]
+
+    names = property(fset=_set_names, fget=_get_names)
+
+    @overload
+    def set_names(self, names, *, level=..., inplace: Literal[False] = ...) -> Self:
+        ...
+
+    @overload
+    def set_names(self, names, *, level=..., inplace: Literal[True]) -> None:
+        ...
+
+    @overload
+    def set_names(self, names, *, level=..., inplace: bool = ...) -> Self | None:
+        ...
+
+    def set_names(self, names, *, level=None, inplace: bool = False) -> Self | None:
+        """
+        Set Index or MultiIndex name.
+
+        Able to set new names partially and by level.
+
+        Parameters
+        ----------
+
+        names : label or list of label or dict-like for MultiIndex
+            Name(s) to set.
+
+            .. versionchanged:: 1.3.0
+
+        level : int, label or list of int or label, optional
+            If the index is a MultiIndex and names is not dict-like, level(s) to set
+            (None for all levels). Otherwise level must be None.
+
+            .. versionchanged:: 1.3.0
+
+        inplace : bool, default False
+            Modifies the object directly, instead of creating a new Index or
+            MultiIndex.
+
+        Returns
+        -------
+        Index or None
+            The same type as the caller or None if ``inplace=True``.
+
+        See Also
+        --------
+        Index.rename : Able to set new names without level.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx
+        Index([1, 2, 3, 4], dtype='int64')
+        >>> idx.set_names('quarter')
+        Index([1, 2, 3, 4], dtype='int64', name='quarter')
+
+        >>> idx = pd.MultiIndex.from_product([['python', 'cobra'],
+        ...                                   [2018, 2019]])
+        >>> idx
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   )
+        >>> idx = idx.set_names(['kind', 'year'])
+        >>> idx.set_names('species', level=0)
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   names=['species', 'year'])
+
+        When renaming levels with a dict, levels can not be passed.
+
+        >>> idx.set_names({'kind': 'snake'})
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   names=['snake', 'year'])
+        """
+        if level is not None and not isinstance(self, ABCMultiIndex):
+            raise ValueError("Level must be None for non-MultiIndex")
+
+        if level is not None and not is_list_like(level) and is_list_like(names):
+            raise TypeError("Names must be a string when a single level is provided.")
+
+        if not is_list_like(names) and level is None and self.nlevels > 1:
+            raise TypeError("Must pass list-like as `names`.")
+
+        if is_dict_like(names) and not isinstance(self, ABCMultiIndex):
+            raise TypeError("Can only pass dict-like as `names` for MultiIndex.")
+
+        if is_dict_like(names) and level is not None:
+            raise TypeError("Can not pass level for dictlike `names`.")
+
+        if isinstance(self, ABCMultiIndex) and is_dict_like(names) and level is None:
+            # Transform dict to list of new names and corresponding levels
+            level, names_adjusted = [], []
+            for i, name in enumerate(self.names):
+                if name in names.keys():
+                    level.append(i)
+                    names_adjusted.append(names[name])
+            names = names_adjusted
+
+        if not is_list_like(names):
+            names = [names]
+        if level is not None and not is_list_like(level):
+            level = [level]
+
+        if inplace:
+            idx = self
+        else:
+            idx = self._view()
+
+        idx._set_names(names, level=level)
+        if not inplace:
+            return idx
+        return None
+
+    @overload
+    def rename(self, name, *, inplace: Literal[False] = ...) -> Self:
+        ...
+
+    @overload
+    def rename(self, name, *, inplace: Literal[True]) -> None:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self", "name"], name="rename"
+    )
+    def rename(self, name, inplace: bool = False) -> Self | None:
+        """
+        Alter Index or MultiIndex name.
+
+        Able to set new names without level. Defaults to returning new index.
+        Length of names must match number of levels in MultiIndex.
+
+        Parameters
+        ----------
+        name : label or list of labels
+            Name(s) to set.
+        inplace : bool, default False
+            Modifies the object directly, instead of creating a new Index or
+            MultiIndex.
+
+        Returns
+        -------
+        Index or None
+            The same type as the caller or None if ``inplace=True``.
+
+        See Also
+        --------
+        Index.set_names : Able to set new names partially and by level.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['A', 'C', 'A', 'B'], name='score')
+        >>> idx.rename('grade')
+        Index(['A', 'C', 'A', 'B'], dtype='object', name='grade')
+
+        >>> idx = pd.MultiIndex.from_product([['python', 'cobra'],
+        ...                                   [2018, 2019]],
+        ...                                   names=['kind', 'year'])
+        >>> idx
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   names=['kind', 'year'])
+        >>> idx.rename(['species', 'year'])
+        MultiIndex([('python', 2018),
+                    ('python', 2019),
+                    ( 'cobra', 2018),
+                    ( 'cobra', 2019)],
+                   names=['species', 'year'])
+        >>> idx.rename('species')
+        Traceback (most recent call last):
+        TypeError: Must pass list-like as `names`.
+        """
+        return self.set_names([name], inplace=inplace)
+
+    # --------------------------------------------------------------------
+    # Level-Centric Methods
+
+    @property
+    def nlevels(self) -> int:
+        """
+        Number of levels.
+        """
+        return 1
+
+    def _sort_levels_monotonic(self) -> Self:
+        """
+        Compat with MultiIndex.
+        """
+        return self
+
+    @final
+    def _validate_index_level(self, level) -> None:
+        """
+        Validate index level.
+
+        For single-level Index getting level number is a no-op, but some
+        verification must be done like in MultiIndex.
+
+        """
+        if isinstance(level, int):
+            if level < 0 and level != -1:
+                raise IndexError(
+                    "Too many levels: Index has only 1 level, "
+                    f"{level} is not a valid level number"
+                )
+            if level > 0:
+                raise IndexError(
+                    f"Too many levels: Index has only 1 level, not {level + 1}"
+                )
+        elif level != self.name:
+            raise KeyError(
+                f"Requested level ({level}) does not match index name ({self.name})"
+            )
+
+    def _get_level_number(self, level) -> int:
+        self._validate_index_level(level)
+        return 0
+
+    def sortlevel(
+        self,
+        level=None,
+        ascending: bool | list[bool] = True,
+        sort_remaining=None,
+        na_position: NaPosition = "first",
+    ):
+        """
+        For internal compatibility with the Index API.
+
+        Sort the Index. This is for compat with MultiIndex
+
+        Parameters
+        ----------
+        ascending : bool, default True
+            False to sort in descending order
+        na_position : {'first' or 'last'}, default 'first'
+            Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
+            the end.
+
+            .. versionadded:: 2.1.0
+
+        level, sort_remaining are compat parameters
+
+        Returns
+        -------
+        Index
+        """
+        if not isinstance(ascending, (list, bool)):
+            raise TypeError(
+                "ascending must be a single bool value or"
+                "a list of bool values of length 1"
+            )
+
+        if isinstance(ascending, list):
+            if len(ascending) != 1:
+                raise TypeError("ascending must be a list of bool values of length 1")
+            ascending = ascending[0]
+
+        if not isinstance(ascending, bool):
+            raise TypeError("ascending must be a bool value")
+
+        return self.sort_values(
+            return_indexer=True, ascending=ascending, na_position=na_position
+        )
+
+    def _get_level_values(self, level) -> Index:
+        """
+        Return an Index of values for requested level.
+
+        This is primarily useful to get an individual level of values from a
+        MultiIndex, but is provided on Index as well for compatibility.
+
+        Parameters
+        ----------
+        level : int or str
+            It is either the integer position or the name of the level.
+
+        Returns
+        -------
+        Index
+            Calling object, as there is only one level in the Index.
+
+        See Also
+        --------
+        MultiIndex.get_level_values : Get values for a level of a MultiIndex.
+
+        Notes
+        -----
+        For Index, level should be 0, since there are no multiple levels.
+
+        Examples
+        --------
+        >>> idx = pd.Index(list('abc'))
+        >>> idx
+        Index(['a', 'b', 'c'], dtype='object')
+
+        Get level values by supplying `level` as integer:
+
+        >>> idx.get_level_values(0)
+        Index(['a', 'b', 'c'], dtype='object')
+        """
+        self._validate_index_level(level)
+        return self
+
+    get_level_values = _get_level_values
+
+    @final
+    def droplevel(self, level: IndexLabel = 0):
+        """
+        Return index with requested level(s) removed.
+
+        If resulting index has only 1 level left, the result will be
+        of Index type, not MultiIndex. The original index is not modified inplace.
+
+        Parameters
+        ----------
+        level : int, str, or list-like, default 0
+            If a string is given, must be the name of a level
+            If list-like, elements must be names or indexes of levels.
+
+        Returns
+        -------
+        Index or MultiIndex
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays(
+        ... [[1, 2], [3, 4], [5, 6]], names=['x', 'y', 'z'])
+        >>> mi
+        MultiIndex([(1, 3, 5),
+                    (2, 4, 6)],
+                   names=['x', 'y', 'z'])
+
+        >>> mi.droplevel()
+        MultiIndex([(3, 5),
+                    (4, 6)],
+                   names=['y', 'z'])
+
+        >>> mi.droplevel(2)
+        MultiIndex([(1, 3),
+                    (2, 4)],
+                   names=['x', 'y'])
+
+        >>> mi.droplevel('z')
+        MultiIndex([(1, 3),
+                    (2, 4)],
+                   names=['x', 'y'])
+
+        >>> mi.droplevel(['x', 'y'])
+        Index([5, 6], dtype='int64', name='z')
+        """
+        if not isinstance(level, (tuple, list)):
+            level = [level]
+
+        levnums = sorted(self._get_level_number(lev) for lev in level)[::-1]
+
+        return self._drop_level_numbers(levnums)
+
+    @final
+    def _drop_level_numbers(self, levnums: list[int]):
+        """
+        Drop MultiIndex levels by level _number_, not name.
+        """
+
+        if not levnums and not isinstance(self, ABCMultiIndex):
+            return self
+        if len(levnums) >= self.nlevels:
+            raise ValueError(
+                f"Cannot remove {len(levnums)} levels from an index with "
+                f"{self.nlevels} levels: at least one level must be left."
+            )
+        # The two checks above guarantee that here self is a MultiIndex
+        self = cast("MultiIndex", self)
+
+        new_levels = list(self.levels)
+        new_codes = list(self.codes)
+        new_names = list(self.names)
+
+        for i in levnums:
+            new_levels.pop(i)
+            new_codes.pop(i)
+            new_names.pop(i)
+
+        if len(new_levels) == 1:
+            lev = new_levels[0]
+
+            if len(lev) == 0:
+                # If lev is empty, lev.take will fail GH#42055
+                if len(new_codes[0]) == 0:
+                    # GH#45230 preserve RangeIndex here
+                    #  see test_reset_index_empty_rangeindex
+                    result = lev[:0]
+                else:
+                    res_values = algos.take(lev._values, new_codes[0], allow_fill=True)
+                    # _constructor instead of type(lev) for RangeIndex compat GH#35230
+                    result = lev._constructor._simple_new(res_values, name=new_names[0])
+            else:
+                # set nan if needed
+                mask = new_codes[0] == -1
+                result = new_levels[0].take(new_codes[0])
+                if mask.any():
+                    result = result.putmask(mask, np.nan)
+
+                result._name = new_names[0]
+
+            return result
+        else:
+            from pandas.core.indexes.multi import MultiIndex
+
+            return MultiIndex(
+                levels=new_levels,
+                codes=new_codes,
+                names=new_names,
+                verify_integrity=False,
+            )
+
+    # --------------------------------------------------------------------
+    # Introspection Methods
+
+    @cache_readonly
+    @final
+    def _can_hold_na(self) -> bool:
+        if isinstance(self.dtype, ExtensionDtype):
+            return self.dtype._can_hold_na
+        if self.dtype.kind in "iub":
+            return False
+        return True
+
+    @property
+    def is_monotonic_increasing(self) -> bool:
+        """
+        Return a boolean if the values are equal or increasing.
+
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.is_monotonic_decreasing : Check if the values are equal or decreasing.
+
+        Examples
+        --------
+        >>> pd.Index([1, 2, 3]).is_monotonic_increasing
+        True
+        >>> pd.Index([1, 2, 2]).is_monotonic_increasing
+        True
+        >>> pd.Index([1, 3, 2]).is_monotonic_increasing
+        False
+        """
+        return self._engine.is_monotonic_increasing
+
+    @property
+    def is_monotonic_decreasing(self) -> bool:
+        """
+        Return a boolean if the values are equal or decreasing.
+
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.is_monotonic_increasing : Check if the values are equal or increasing.
+
+        Examples
+        --------
+        >>> pd.Index([3, 2, 1]).is_monotonic_decreasing
+        True
+        >>> pd.Index([3, 2, 2]).is_monotonic_decreasing
+        True
+        >>> pd.Index([3, 1, 2]).is_monotonic_decreasing
+        False
+        """
+        return self._engine.is_monotonic_decreasing
+
+    @final
+    @property
+    def _is_strictly_monotonic_increasing(self) -> bool:
+        """
+        Return if the index is strictly monotonic increasing
+        (only increasing) values.
+
+        Examples
+        --------
+        >>> Index([1, 2, 3])._is_strictly_monotonic_increasing
+        True
+        >>> Index([1, 2, 2])._is_strictly_monotonic_increasing
+        False
+        >>> Index([1, 3, 2])._is_strictly_monotonic_increasing
+        False
+        """
+        return self.is_unique and self.is_monotonic_increasing
+
+    @final
+    @property
+    def _is_strictly_monotonic_decreasing(self) -> bool:
+        """
+        Return if the index is strictly monotonic decreasing
+        (only decreasing) values.
+
+        Examples
+        --------
+        >>> Index([3, 2, 1])._is_strictly_monotonic_decreasing
+        True
+        >>> Index([3, 2, 2])._is_strictly_monotonic_decreasing
+        False
+        >>> Index([3, 1, 2])._is_strictly_monotonic_decreasing
+        False
+        """
+        return self.is_unique and self.is_monotonic_decreasing
+
+    @cache_readonly
+    def is_unique(self) -> bool:
+        """
+        Return if the index has unique values.
+
+        Returns
+        -------
+        bool
+
+        See Also
+        --------
+        Index.has_duplicates : Inverse method that checks if it has duplicate values.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 5, 7, 7])
+        >>> idx.is_unique
+        False
+
+        >>> idx = pd.Index([1, 5, 7])
+        >>> idx.is_unique
+        True
+
+        >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_unique
+        False
+
+        >>> idx = pd.Index(["Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_unique
+        True
+        """
+        return self._engine.is_unique
+
+    @final
+    @property
+    def has_duplicates(self) -> bool:
+        """
+        Check if the Index has duplicate values.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index has duplicate values.
+
+        See Also
+        --------
+        Index.is_unique : Inverse method that checks if it has unique values.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 5, 7, 7])
+        >>> idx.has_duplicates
+        True
+
+        >>> idx = pd.Index([1, 5, 7])
+        >>> idx.has_duplicates
+        False
+
+        >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.has_duplicates
+        True
+
+        >>> idx = pd.Index(["Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.has_duplicates
+        False
+        """
+        return not self.is_unique
+
+    @final
+    def is_boolean(self) -> bool:
+        """
+        Check if the Index only consists of booleans.
+
+        .. deprecated:: 2.0.0
+            Use `pandas.api.types.is_bool_dtype` instead.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index only consists of booleans.
+
+        See Also
+        --------
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_object : Check if the Index is of the object dtype (deprecated).
+        is_categorical : Check if the Index holds categorical data.
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index([True, False, True])
+        >>> idx.is_boolean()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index(["True", "False", "True"])
+        >>> idx.is_boolean()  # doctest: +SKIP
+        False
+
+        >>> idx = pd.Index([True, False, "True"])
+        >>> idx.is_boolean()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_boolean is deprecated. "
+            "Use pandas.api.types.is_bool_type instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.inferred_type in ["boolean"]
+
+    @final
+    def is_integer(self) -> bool:
+        """
+        Check if the Index only consists of integers.
+
+        .. deprecated:: 2.0.0
+            Use `pandas.api.types.is_integer_dtype` instead.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index only consists of integers.
+
+        See Also
+        --------
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_object : Check if the Index is of the object dtype. (deprecated).
+        is_categorical : Check if the Index holds categorical data (deprecated).
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx.is_integer()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
+        >>> idx.is_integer()  # doctest: +SKIP
+        False
+
+        >>> idx = pd.Index(["Apple", "Mango", "Watermelon"])
+        >>> idx.is_integer()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_integer is deprecated. "
+            "Use pandas.api.types.is_integer_dtype instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.inferred_type in ["integer"]
+
+    @final
+    def is_floating(self) -> bool:
+        """
+        Check if the Index is a floating type.
+
+        .. deprecated:: 2.0.0
+            Use `pandas.api.types.is_float_dtype` instead
+
+        The Index may consist of only floats, NaNs, or a mix of floats,
+        integers, or NaNs.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index only consists of only consists of floats, NaNs, or
+            a mix of floats, integers, or NaNs.
+
+        See Also
+        --------
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_object : Check if the Index is of the object dtype. (deprecated).
+        is_categorical : Check if the Index holds categorical data (deprecated).
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
+        >>> idx.is_floating()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1.0, 2.0, np.nan, 4.0])
+        >>> idx.is_floating()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4, np.nan])
+        >>> idx.is_floating()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx.is_floating()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_floating is deprecated. "
+            "Use pandas.api.types.is_float_dtype instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.inferred_type in ["floating", "mixed-integer-float", "integer-na"]
+
+    @final
+    def is_numeric(self) -> bool:
+        """
+        Check if the Index only consists of numeric data.
+
+        .. deprecated:: 2.0.0
+            Use `pandas.api.types.is_numeric_dtype` instead.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index only consists of numeric data.
+
+        See Also
+        --------
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_object : Check if the Index is of the object dtype. (deprecated).
+        is_categorical : Check if the Index holds categorical data (deprecated).
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
+        >>> idx.is_numeric()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4.0])
+        >>> idx.is_numeric()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx.is_numeric()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4.0, np.nan])
+        >>> idx.is_numeric()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 2, 3, 4.0, np.nan, "Apple"])
+        >>> idx.is_numeric()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_numeric is deprecated. "
+            "Use pandas.api.types.is_any_real_numeric_dtype instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.inferred_type in ["integer", "floating"]
+
+    @final
+    def is_object(self) -> bool:
+        """
+        Check if the Index is of the object dtype.
+
+        .. deprecated:: 2.0.0
+           Use `pandas.api.types.is_object_dtype` instead.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index is of the object dtype.
+
+        See Also
+        --------
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_categorical : Check if the Index holds categorical data (deprecated).
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index(["Apple", "Mango", "Watermelon"])
+        >>> idx.is_object()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index(["Apple", "Mango", 2.0])
+        >>> idx.is_object()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_object()  # doctest: +SKIP
+        False
+
+        >>> idx = pd.Index([1.0, 2.0, 3.0, 4.0])
+        >>> idx.is_object()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_object is deprecated."
+            "Use pandas.api.types.is_object_dtype instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return is_object_dtype(self.dtype)
+
+    @final
+    def is_categorical(self) -> bool:
+        """
+        Check if the Index holds categorical data.
+
+        .. deprecated:: 2.0.0
+              Use `isinstance(index.dtype, pd.CategoricalDtype)` instead.
+
+        Returns
+        -------
+        bool
+            True if the Index is categorical.
+
+        See Also
+        --------
+        CategoricalIndex : Index for categorical data.
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_object : Check if the Index is of the object dtype. (deprecated).
+        is_interval : Check if the Index holds Interval objects (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index(["Watermelon", "Orange", "Apple",
+        ...                 "Watermelon"]).astype("category")
+        >>> idx.is_categorical()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 3, 5, 7])
+        >>> idx.is_categorical()  # doctest: +SKIP
+        False
+
+        >>> s = pd.Series(["Peter", "Victor", "Elisabeth", "Mar"])
+        >>> s
+        0        Peter
+        1       Victor
+        2    Elisabeth
+        3          Mar
+        dtype: object
+        >>> s.index.is_categorical()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_categorical is deprecated."
+            "Use pandas.api.types.is_categorical_dtype instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        return self.inferred_type in ["categorical"]
+
+    @final
+    def is_interval(self) -> bool:
+        """
+        Check if the Index holds Interval objects.
+
+        .. deprecated:: 2.0.0
+            Use `isinstance(index.dtype, pd.IntervalDtype)` instead.
+
+        Returns
+        -------
+        bool
+            Whether or not the Index holds Interval objects.
+
+        See Also
+        --------
+        IntervalIndex : Index for Interval objects.
+        is_boolean : Check if the Index only consists of booleans (deprecated).
+        is_integer : Check if the Index only consists of integers (deprecated).
+        is_floating : Check if the Index is a floating type (deprecated).
+        is_numeric : Check if the Index only consists of numeric data (deprecated).
+        is_object : Check if the Index is of the object dtype. (deprecated).
+        is_categorical : Check if the Index holds categorical data (deprecated).
+
+        Examples
+        --------
+        >>> idx = pd.Index([pd.Interval(left=0, right=5),
+        ...                 pd.Interval(left=5, right=10)])
+        >>> idx.is_interval()  # doctest: +SKIP
+        True
+
+        >>> idx = pd.Index([1, 3, 5, 7])
+        >>> idx.is_interval()  # doctest: +SKIP
+        False
+        """
+        warnings.warn(
+            f"{type(self).__name__}.is_interval is deprecated."
+            "Use pandas.api.types.is_interval_dtype instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.inferred_type in ["interval"]
+
+    @final
+    def _holds_integer(self) -> bool:
+        """
+        Whether the type is an integer type.
+        """
+        return self.inferred_type in ["integer", "mixed-integer"]
+
+    @final
+    def holds_integer(self) -> bool:
+        """
+        Whether the type is an integer type.
+
+        .. deprecated:: 2.0.0
+            Use `pandas.api.types.infer_dtype` instead
+        """
+        warnings.warn(
+            f"{type(self).__name__}.holds_integer is deprecated. "
+            "Use pandas.api.types.infer_dtype instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._holds_integer()
+
+    @cache_readonly
+    def inferred_type(self) -> str_t:
+        """
+        Return a string of the type inferred from the values.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.inferred_type
+        'integer'
+        """
+        return lib.infer_dtype(self._values, skipna=False)
+
+    @cache_readonly
+    @final
+    def _is_all_dates(self) -> bool:
+        """
+        Whether or not the index values only consist of dates.
+        """
+        if needs_i8_conversion(self.dtype):
+            return True
+        elif self.dtype != _dtype_obj:
+            # TODO(ExtensionIndex): 3rd party EA might override?
+            # Note: this includes IntervalIndex, even when the left/right
+            #  contain datetime-like objects.
+            return False
+        elif self._is_multi:
+            return False
+        return is_datetime_array(ensure_object(self._values))
+
+    @final
+    @cache_readonly
+    def _is_multi(self) -> bool:
+        """
+        Cached check equivalent to isinstance(self, MultiIndex)
+        """
+        return isinstance(self, ABCMultiIndex)
+
+    # --------------------------------------------------------------------
+    # Pickle Methods
+
+    def __reduce__(self):
+        d = {"data": self._data, "name": self.name}
+        return _new_Index, (type(self), d), None
+
+    # --------------------------------------------------------------------
+    # Null Handling Methods
+
+    @cache_readonly
+    def _na_value(self):
+        """The expected NA value to use with this index."""
+        dtype = self.dtype
+        if isinstance(dtype, np.dtype):
+            if dtype.kind in "mM":
+                return NaT
+            return np.nan
+        return dtype.na_value
+
+    @cache_readonly
+    def _isnan(self) -> npt.NDArray[np.bool_]:
+        """
+        Return if each value is NaN.
+        """
+        if self._can_hold_na:
+            return isna(self)
+        else:
+            # shouldn't reach to this condition by checking hasnans beforehand
+            values = np.empty(len(self), dtype=np.bool_)
+            values.fill(False)
+            return values
+
+    @cache_readonly
+    def hasnans(self) -> bool:
+        """
+        Return True if there are any NaNs.
+
+        Enables various performance speedups.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3], index=['a', 'b', None])
+        >>> s
+        a    1
+        b    2
+        None 3
+        dtype: int64
+        >>> s.index.hasnans
+        True
+        """
+        if self._can_hold_na:
+            return bool(self._isnan.any())
+        else:
+            return False
+
+    @final
+    def isna(self) -> npt.NDArray[np.bool_]:
+        """
+        Detect missing values.
+
+        Return a boolean same-sized object indicating if the values are NA.
+        NA values, such as ``None``, :attr:`numpy.NaN` or :attr:`pd.NaT`, get
+        mapped to ``True`` values.
+        Everything else get mapped to ``False`` values. Characters such as
+        empty strings `''` or :attr:`numpy.inf` are not considered NA values.
+
+        Returns
+        -------
+        numpy.ndarray[bool]
+            A boolean array of whether my values are NA.
+
+        See Also
+        --------
+        Index.notna : Boolean inverse of isna.
+        Index.dropna : Omit entries with missing values.
+        isna : Top-level isna.
+        Series.isna : Detect missing values in Series object.
+
+        Examples
+        --------
+        Show which entries in a pandas.Index are NA. The result is an
+        array.
+
+        >>> idx = pd.Index([5.2, 6.0, np.nan])
+        >>> idx
+        Index([5.2, 6.0, nan], dtype='float64')
+        >>> idx.isna()
+        array([False, False,  True])
+
+        Empty strings are not considered NA values. None is considered an NA
+        value.
+
+        >>> idx = pd.Index(['black', '', 'red', None])
+        >>> idx
+        Index(['black', '', 'red', None], dtype='object')
+        >>> idx.isna()
+        array([False, False, False,  True])
+
+        For datetimes, `NaT` (Not a Time) is considered as an NA value.
+
+        >>> idx = pd.DatetimeIndex([pd.Timestamp('1940-04-25'),
+        ...                         pd.Timestamp(''), None, pd.NaT])
+        >>> idx
+        DatetimeIndex(['1940-04-25', 'NaT', 'NaT', 'NaT'],
+                      dtype='datetime64[ns]', freq=None)
+        >>> idx.isna()
+        array([False,  True,  True,  True])
+        """
+        return self._isnan
+
+    isnull = isna
+
+    @final
+    def notna(self) -> npt.NDArray[np.bool_]:
+        """
+        Detect existing (non-missing) values.
+
+        Return a boolean same-sized object indicating if the values are not NA.
+        Non-missing values get mapped to ``True``. Characters such as empty
+        strings ``''`` or :attr:`numpy.inf` are not considered NA values.
+        NA values, such as None or :attr:`numpy.NaN`, get mapped to ``False``
+        values.
+
+        Returns
+        -------
+        numpy.ndarray[bool]
+            Boolean array to indicate which entries are not NA.
+
+        See Also
+        --------
+        Index.notnull : Alias of notna.
+        Index.isna: Inverse of notna.
+        notna : Top-level notna.
+
+        Examples
+        --------
+        Show which entries in an Index are not NA. The result is an
+        array.
+
+        >>> idx = pd.Index([5.2, 6.0, np.nan])
+        >>> idx
+        Index([5.2, 6.0, nan], dtype='float64')
+        >>> idx.notna()
+        array([ True,  True, False])
+
+        Empty strings are not considered NA values. None is considered a NA
+        value.
+
+        >>> idx = pd.Index(['black', '', 'red', None])
+        >>> idx
+        Index(['black', '', 'red', None], dtype='object')
+        >>> idx.notna()
+        array([ True,  True,  True, False])
+        """
+        return ~self.isna()
+
+    notnull = notna
+
+    def fillna(self, value=None, downcast=lib.no_default):
+        """
+        Fill NA/NaN values with the specified value.
+
+        Parameters
+        ----------
+        value : scalar
+            Scalar value to use to fill holes (e.g. 0).
+            This value cannot be a list-likes.
+        downcast : dict, default is None
+            A dict of item->dtype of what to downcast if possible,
+            or the string 'infer' which will try to downcast to an appropriate
+            equal type (e.g. float64 to int64 if possible).
+
+            .. deprecated:: 2.1.0
+
+        Returns
+        -------
+        Index
+
+        See Also
+        --------
+        DataFrame.fillna : Fill NaN values of a DataFrame.
+        Series.fillna : Fill NaN Values of a Series.
+
+        Examples
+        --------
+        >>> idx = pd.Index([np.nan, np.nan, 3])
+        >>> idx.fillna(0)
+        Index([0.0, 0.0, 3.0], dtype='float64')
+        """
+        if not is_scalar(value):
+            raise TypeError(f"'value' must be a scalar, passed: {type(value).__name__}")
+        if downcast is not lib.no_default:
+            warnings.warn(
+                f"The 'downcast' keyword in {type(self).__name__}.fillna is "
+                "deprecated and will be removed in a future version. "
+                "It was previously silently ignored.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            downcast = None
+
+        if self.hasnans:
+            result = self.putmask(self._isnan, value)
+            if downcast is None:
+                # no need to care metadata other than name
+                # because it can't have freq if it has NaTs
+                # _with_infer needed for test_fillna_categorical
+                return Index._with_infer(result, name=self.name)
+            raise NotImplementedError(
+                f"{type(self).__name__}.fillna does not support 'downcast' "
+                "argument values other than 'None'."
+            )
+        return self._view()
+
+    def dropna(self, how: AnyAll = "any") -> Self:
+        """
+        Return Index without NA/NaN values.
+
+        Parameters
+        ----------
+        how : {'any', 'all'}, default 'any'
+            If the Index is a MultiIndex, drop the value when any or all levels
+            are NaN.
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, np.nan, 3])
+        >>> idx.dropna()
+        Index([1.0, 3.0], dtype='float64')
+        """
+        if how not in ("any", "all"):
+            raise ValueError(f"invalid how option: {how}")
+
+        if self.hasnans:
+            res_values = self._values[~self._isnan]
+            return type(self)._simple_new(res_values, name=self.name)
+        return self._view()
+
+    # --------------------------------------------------------------------
+    # Uniqueness Methods
+
+    def unique(self, level: Hashable | None = None) -> Self:
+        """
+        Return unique values in the index.
+
+        Unique values are returned in order of appearance, this does NOT sort.
+
+        Parameters
+        ----------
+        level : int or hashable, optional
+            Only return values from specified level (for MultiIndex).
+            If int, gets the level by integer position, else by level name.
+
+        Returns
+        -------
+        Index
+
+        See Also
+        --------
+        unique : Numpy array of unique values in that column.
+        Series.unique : Return unique values of Series object.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 1, 2, 3, 3])
+        >>> idx.unique()
+        Index([1, 2, 3], dtype='int64')
+        """
+        if level is not None:
+            self._validate_index_level(level)
+
+        if self.is_unique:
+            return self._view()
+
+        result = super().unique()
+        return self._shallow_copy(result)
+
+    def drop_duplicates(self, *, keep: DropKeep = "first") -> Self:
+        """
+        Return Index with duplicate values removed.
+
+        Parameters
+        ----------
+        keep : {'first', 'last', ``False``}, default 'first'
+            - 'first' : Drop duplicates except for the first occurrence.
+            - 'last' : Drop duplicates except for the last occurrence.
+            - ``False`` : Drop all duplicates.
+
+        Returns
+        -------
+        Index
+
+        See Also
+        --------
+        Series.drop_duplicates : Equivalent method on Series.
+        DataFrame.drop_duplicates : Equivalent method on DataFrame.
+        Index.duplicated : Related method on Index, indicating duplicate
+            Index values.
+
+        Examples
+        --------
+        Generate an pandas.Index with duplicate values.
+
+        >>> idx = pd.Index(['lama', 'cow', 'lama', 'beetle', 'lama', 'hippo'])
+
+        The `keep` parameter controls  which duplicate values are removed.
+        The value 'first' keeps the first occurrence for each
+        set of duplicated entries. The default value of keep is 'first'.
+
+        >>> idx.drop_duplicates(keep='first')
+        Index(['lama', 'cow', 'beetle', 'hippo'], dtype='object')
+
+        The value 'last' keeps the last occurrence for each set of duplicated
+        entries.
+
+        >>> idx.drop_duplicates(keep='last')
+        Index(['cow', 'beetle', 'lama', 'hippo'], dtype='object')
+
+        The value ``False`` discards all sets of duplicated entries.
+
+        >>> idx.drop_duplicates(keep=False)
+        Index(['cow', 'beetle', 'hippo'], dtype='object')
+        """
+        if self.is_unique:
+            return self._view()
+
+        return super().drop_duplicates(keep=keep)
+
+    def duplicated(self, keep: DropKeep = "first") -> npt.NDArray[np.bool_]:
+        """
+        Indicate duplicate index values.
+
+        Duplicated values are indicated as ``True`` values in the resulting
+        array. Either all duplicates, all except the first, or all except the
+        last occurrence of duplicates can be indicated.
+
+        Parameters
+        ----------
+        keep : {'first', 'last', False}, default 'first'
+            The value or values in a set of duplicates to mark as missing.
+
+            - 'first' : Mark duplicates as ``True`` except for the first
+              occurrence.
+            - 'last' : Mark duplicates as ``True`` except for the last
+              occurrence.
+            - ``False`` : Mark all duplicates as ``True``.
+
+        Returns
+        -------
+        np.ndarray[bool]
+
+        See Also
+        --------
+        Series.duplicated : Equivalent method on pandas.Series.
+        DataFrame.duplicated : Equivalent method on pandas.DataFrame.
+        Index.drop_duplicates : Remove duplicate values from Index.
+
+        Examples
+        --------
+        By default, for each set of duplicated values, the first occurrence is
+        set to False and all others to True:
+
+        >>> idx = pd.Index(['lama', 'cow', 'lama', 'beetle', 'lama'])
+        >>> idx.duplicated()
+        array([False, False,  True, False,  True])
+
+        which is equivalent to
+
+        >>> idx.duplicated(keep='first')
+        array([False, False,  True, False,  True])
+
+        By using 'last', the last occurrence of each set of duplicated values
+        is set on False and all others on True:
+
+        >>> idx.duplicated(keep='last')
+        array([ True, False,  True, False, False])
+
+        By setting keep on ``False``, all duplicates are True:
+
+        >>> idx.duplicated(keep=False)
+        array([ True, False,  True, False,  True])
+        """
+        if self.is_unique:
+            # fastpath available bc we are immutable
+            return np.zeros(len(self), dtype=bool)
+        return self._duplicated(keep=keep)
+
+    # --------------------------------------------------------------------
+    # Arithmetic & Logical Methods
+
+    def __iadd__(self, other):
+        # alias for __add__
+        return self + other
+
+    @final
+    def __nonzero__(self) -> NoReturn:
+        raise ValueError(
+            f"The truth value of a {type(self).__name__} is ambiguous. "
+            "Use a.empty, a.bool(), a.item(), a.any() or a.all()."
+        )
+
+    __bool__ = __nonzero__
+
+    # --------------------------------------------------------------------
+    # Set Operation Methods
+
+    def _get_reconciled_name_object(self, other):
+        """
+        If the result of a set operation will be self,
+        return self, unless the name changes, in which
+        case make a shallow copy of self.
+        """
+        name = get_op_result_name(self, other)
+        if self.name is not name:
+            return self.rename(name)
+        return self
+
+    @final
+    def _validate_sort_keyword(self, sort):
+        if sort not in [None, False, True]:
+            raise ValueError(
+                "The 'sort' keyword only takes the values of "
+                f"None, True, or False; {sort} was passed."
+            )
+
+    @final
+    def _dti_setop_align_tzs(self, other: Index, setop: str_t) -> tuple[Index, Index]:
+        """
+        With mismatched timezones, cast both to UTC.
+        """
+        # Caller is responsibelf or checking
+        #  `self.dtype != other.dtype`
+        if (
+            isinstance(self, ABCDatetimeIndex)
+            and isinstance(other, ABCDatetimeIndex)
+            and self.tz is not None
+            and other.tz is not None
+        ):
+            # GH#39328, GH#45357
+            left = self.tz_convert("UTC")
+            right = other.tz_convert("UTC")
+            return left, right
+        return self, other
+
+    @final
+    def union(self, other, sort=None):
+        """
+        Form the union of two Index objects.
+
+        If the Index objects are incompatible, both Index objects will be
+        cast to dtype('object') first.
+
+        Parameters
+        ----------
+        other : Index or array-like
+        sort : bool or None, default None
+            Whether to sort the resulting Index.
+
+            * None : Sort the result, except when
+
+              1. `self` and `other` are equal.
+              2. `self` or `other` has length 0.
+              3. Some values in `self` or `other` cannot be compared.
+                 A RuntimeWarning is issued in this case.
+
+            * False : do not sort the result.
+            * True : Sort the result (which may raise TypeError).
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        Union matching dtypes
+
+        >>> idx1 = pd.Index([1, 2, 3, 4])
+        >>> idx2 = pd.Index([3, 4, 5, 6])
+        >>> idx1.union(idx2)
+        Index([1, 2, 3, 4, 5, 6], dtype='int64')
+
+        Union mismatched dtypes
+
+        >>> idx1 = pd.Index(['a', 'b', 'c', 'd'])
+        >>> idx2 = pd.Index([1, 2, 3, 4])
+        >>> idx1.union(idx2)
+        Index(['a', 'b', 'c', 'd', 1, 2, 3, 4], dtype='object')
+
+        MultiIndex case
+
+        >>> idx1 = pd.MultiIndex.from_arrays(
+        ...     [[1, 1, 2, 2], ["Red", "Blue", "Red", "Blue"]]
+        ... )
+        >>> idx1
+        MultiIndex([(1,  'Red'),
+            (1, 'Blue'),
+            (2,  'Red'),
+            (2, 'Blue')],
+           )
+        >>> idx2 = pd.MultiIndex.from_arrays(
+        ...     [[3, 3, 2, 2], ["Red", "Green", "Red", "Green"]]
+        ... )
+        >>> idx2
+        MultiIndex([(3,   'Red'),
+            (3, 'Green'),
+            (2,   'Red'),
+            (2, 'Green')],
+           )
+        >>> idx1.union(idx2)
+        MultiIndex([(1,  'Blue'),
+            (1,   'Red'),
+            (2,  'Blue'),
+            (2, 'Green'),
+            (2,   'Red'),
+            (3, 'Green'),
+            (3,   'Red')],
+           )
+        >>> idx1.union(idx2, sort=False)
+        MultiIndex([(1,   'Red'),
+            (1,  'Blue'),
+            (2,   'Red'),
+            (2,  'Blue'),
+            (3,   'Red'),
+            (3, 'Green'),
+            (2, 'Green')],
+           )
+        """
+        self._validate_sort_keyword(sort)
+        self._assert_can_do_setop(other)
+        other, result_name = self._convert_can_do_setop(other)
+
+        if self.dtype != other.dtype:
+            if (
+                isinstance(self, ABCMultiIndex)
+                and not is_object_dtype(_unpack_nested_dtype(other))
+                and len(other) > 0
+            ):
+                raise NotImplementedError(
+                    "Can only union MultiIndex with MultiIndex or Index of tuples, "
+                    "try mi.to_flat_index().union(other) instead."
+                )
+            self, other = self._dti_setop_align_tzs(other, "union")
+
+            dtype = self._find_common_type_compat(other)
+            left = self.astype(dtype, copy=False)
+            right = other.astype(dtype, copy=False)
+            return left.union(right, sort=sort)
+
+        elif not len(other) or self.equals(other):
+            # NB: whether this (and the `if not len(self)` check below) come before
+            #  or after the dtype equality check above affects the returned dtype
+            result = self._get_reconciled_name_object(other)
+            if sort is True:
+                return result.sort_values()
+            return result
+
+        elif not len(self):
+            result = other._get_reconciled_name_object(self)
+            if sort is True:
+                return result.sort_values()
+            return result
+
+        result = self._union(other, sort=sort)
+
+        return self._wrap_setop_result(other, result)
+
+    def _union(self, other: Index, sort: bool | None):
+        """
+        Specific union logic should go here. In subclasses, union behavior
+        should be overwritten here rather than in `self.union`.
+
+        Parameters
+        ----------
+        other : Index or array-like
+        sort : False or None, default False
+            Whether to sort the resulting index.
+
+            * True : sort the result
+            * False : do not sort the result.
+            * None : sort the result, except when `self` and `other` are equal
+              or when the values cannot be compared.
+
+        Returns
+        -------
+        Index
+        """
+        lvals = self._values
+        rvals = other._values
+
+        if (
+            sort in (None, True)
+            and self.is_monotonic_increasing
+            and other.is_monotonic_increasing
+            and not (self.has_duplicates and other.has_duplicates)
+            and self._can_use_libjoin
+            and other._can_use_libjoin
+        ):
+            # Both are monotonic and at least one is unique, so can use outer join
+            #  (actually don't need either unique, but without this restriction
+            #  test_union_same_value_duplicated_in_both fails)
+            try:
+                return self._outer_indexer(other)[0]
+            except (TypeError, IncompatibleFrequency):
+                # incomparable objects; should only be for object dtype
+                value_list = list(lvals)
+
+                # worth making this faster? a very unusual case
+                value_set = set(lvals)
+                value_list.extend([x for x in rvals if x not in value_set])
+                # If objects are unorderable, we must have object dtype.
+                return np.array(value_list, dtype=object)
+
+        elif not other.is_unique:
+            # other has duplicates
+            result_dups = algos.union_with_duplicates(self, other)
+            return _maybe_try_sort(result_dups, sort)
+
+        # The rest of this method is analogous to Index._intersection_via_get_indexer
+
+        # Self may have duplicates; other already checked as unique
+        # find indexes of things in "other" that are not in "self"
+        if self._index_as_unique:
+            indexer = self.get_indexer(other)
+            missing = (indexer == -1).nonzero()[0]
+        else:
+            missing = algos.unique1d(self.get_indexer_non_unique(other)[1])
+
+        result: Index | MultiIndex | ArrayLike
+        if self._is_multi:
+            # Preserve MultiIndex to avoid losing dtypes
+            result = self.append(other.take(missing))
+
+        else:
+            if len(missing) > 0:
+                other_diff = rvals.take(missing)
+                result = concat_compat((lvals, other_diff))
+            else:
+                result = lvals
+
+        if not self.is_monotonic_increasing or not other.is_monotonic_increasing:
+            # if both are monotonic then result should already be sorted
+            result = _maybe_try_sort(result, sort)
+
+        return result
+
+    @final
+    def _wrap_setop_result(self, other: Index, result) -> Index:
+        name = get_op_result_name(self, other)
+        if isinstance(result, Index):
+            if result.name != name:
+                result = result.rename(name)
+        else:
+            result = self._shallow_copy(result, name=name)
+        return result
+
+    @final
+    def intersection(self, other, sort: bool = False):
+        # default sort keyword is different here from other setops intentionally
+        #  done in GH#25063
+        """
+        Form the intersection of two Index objects.
+
+        This returns a new Index with elements common to the index and `other`.
+
+        Parameters
+        ----------
+        other : Index or array-like
+        sort : True, False or None, default False
+            Whether to sort the resulting index.
+
+            * None : sort the result, except when `self` and `other` are equal
+              or when the values cannot be compared.
+            * False : do not sort the result.
+            * True : Sort the result (which may raise TypeError).
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([1, 2, 3, 4])
+        >>> idx2 = pd.Index([3, 4, 5, 6])
+        >>> idx1.intersection(idx2)
+        Index([3, 4], dtype='int64')
+        """
+        self._validate_sort_keyword(sort)
+        self._assert_can_do_setop(other)
+        other, result_name = self._convert_can_do_setop(other)
+
+        if self.dtype != other.dtype:
+            self, other = self._dti_setop_align_tzs(other, "intersection")
+
+        if self.equals(other):
+            if not self.is_unique:
+                result = self.unique()._get_reconciled_name_object(other)
+            else:
+                result = self._get_reconciled_name_object(other)
+            if sort is True:
+                result = result.sort_values()
+            return result
+
+        if len(self) == 0 or len(other) == 0:
+            # fastpath; we need to be careful about having commutativity
+
+            if self._is_multi or other._is_multi:
+                # _convert_can_do_setop ensures that we have both or neither
+                # We retain self.levels
+                return self[:0].rename(result_name)
+
+            dtype = self._find_common_type_compat(other)
+            if self.dtype == dtype:
+                # Slicing allows us to retain DTI/TDI.freq, RangeIndex
+
+                # Note: self[:0] vs other[:0] affects
+                #  1) which index's `freq` we get in DTI/TDI cases
+                #     This may be a historical artifact, i.e. no documented
+                #     reason for this choice.
+                #  2) The `step` we get in RangeIndex cases
+                if len(self) == 0:
+                    return self[:0].rename(result_name)
+                else:
+                    return other[:0].rename(result_name)
+
+            return Index([], dtype=dtype, name=result_name)
+
+        elif not self._should_compare(other):
+            # We can infer that the intersection is empty.
+            if isinstance(self, ABCMultiIndex):
+                return self[:0].rename(result_name)
+            return Index([], name=result_name)
+
+        elif self.dtype != other.dtype:
+            dtype = self._find_common_type_compat(other)
+            this = self.astype(dtype, copy=False)
+            other = other.astype(dtype, copy=False)
+            return this.intersection(other, sort=sort)
+
+        result = self._intersection(other, sort=sort)
+        return self._wrap_intersection_result(other, result)
+
+    def _intersection(self, other: Index, sort: bool = False):
+        """
+        intersection specialized to the case with matching dtypes.
+        """
+        if (
+            self.is_monotonic_increasing
+            and other.is_monotonic_increasing
+            and self._can_use_libjoin
+            and other._can_use_libjoin
+        ):
+            try:
+                res_indexer, indexer, _ = self._inner_indexer(other)
+            except TypeError:
+                # non-comparable; should only be for object dtype
+                pass
+            else:
+                # TODO: algos.unique1d should preserve DTA/TDA
+                if is_numeric_dtype(self.dtype):
+                    # This is faster, because Index.unique() checks for uniqueness
+                    # before calculating the unique values.
+                    res = algos.unique1d(res_indexer)
+                else:
+                    result = self.take(indexer)
+                    res = result.drop_duplicates()
+                return ensure_wrapped_if_datetimelike(res)
+
+        res_values = self._intersection_via_get_indexer(other, sort=sort)
+        res_values = _maybe_try_sort(res_values, sort)
+        return res_values
+
+    def _wrap_intersection_result(self, other, result):
+        # We will override for MultiIndex to handle empty results
+        return self._wrap_setop_result(other, result)
+
+    @final
+    def _intersection_via_get_indexer(
+        self, other: Index | MultiIndex, sort
+    ) -> ArrayLike | MultiIndex:
+        """
+        Find the intersection of two Indexes using get_indexer.
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray or MultiIndex
+            The returned array will be unique.
+        """
+        left_unique = self.unique()
+        right_unique = other.unique()
+
+        # even though we are unique, we need get_indexer_for for IntervalIndex
+        indexer = left_unique.get_indexer_for(right_unique)
+
+        mask = indexer != -1
+
+        taker = indexer.take(mask.nonzero()[0])
+        if sort is False:
+            # sort bc we want the elements in the same order they are in self
+            # unnecessary in the case with sort=None bc we will sort later
+            taker = np.sort(taker)
+
+        result: MultiIndex | ExtensionArray | np.ndarray
+        if isinstance(left_unique, ABCMultiIndex):
+            result = left_unique.take(taker)
+        else:
+            result = left_unique.take(taker)._values
+        return result
+
+    @final
+    def difference(self, other, sort=None):
+        """
+        Return a new Index with elements of index not in `other`.
+
+        This is the set difference of two Index objects.
+
+        Parameters
+        ----------
+        other : Index or array-like
+        sort : bool or None, default None
+            Whether to sort the resulting index. By default, the
+            values are attempted to be sorted, but any TypeError from
+            incomparable elements is caught by pandas.
+
+            * None : Attempt to sort the result, but catch any TypeErrors
+              from comparing incomparable elements.
+            * False : Do not sort the result.
+            * True : Sort the result (which may raise TypeError).
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([2, 1, 3, 4])
+        >>> idx2 = pd.Index([3, 4, 5, 6])
+        >>> idx1.difference(idx2)
+        Index([1, 2], dtype='int64')
+        >>> idx1.difference(idx2, sort=False)
+        Index([2, 1], dtype='int64')
+        """
+        self._validate_sort_keyword(sort)
+        self._assert_can_do_setop(other)
+        other, result_name = self._convert_can_do_setop(other)
+
+        # Note: we do NOT call _dti_setop_align_tzs here, as there
+        #  is no requirement that .difference be commutative, so it does
+        #  not cast to object.
+
+        if self.equals(other):
+            # Note: we do not (yet) sort even if sort=None GH#24959
+            return self[:0].rename(result_name)
+
+        if len(other) == 0:
+            # Note: we do not (yet) sort even if sort=None GH#24959
+            result = self.unique().rename(result_name)
+            if sort is True:
+                return result.sort_values()
+            return result
+
+        if not self._should_compare(other):
+            # Nothing matches -> difference is everything
+            result = self.unique().rename(result_name)
+            if sort is True:
+                return result.sort_values()
+            return result
+
+        result = self._difference(other, sort=sort)
+        return self._wrap_difference_result(other, result)
+
+    def _difference(self, other, sort):
+        # overridden by RangeIndex
+        this = self
+        if isinstance(self, ABCCategoricalIndex) and self.hasnans and other.hasnans:
+            this = this.dropna()
+        other = other.unique()
+        the_diff = this[other.get_indexer_for(this) == -1]
+        the_diff = the_diff if this.is_unique else the_diff.unique()
+        the_diff = _maybe_try_sort(the_diff, sort)
+        return the_diff
+
+    def _wrap_difference_result(self, other, result):
+        # We will override for MultiIndex to handle empty results
+        return self._wrap_setop_result(other, result)
+
+    def symmetric_difference(self, other, result_name=None, sort=None):
+        """
+        Compute the symmetric difference of two Index objects.
+
+        Parameters
+        ----------
+        other : Index or array-like
+        result_name : str
+        sort : bool or None, default None
+            Whether to sort the resulting index. By default, the
+            values are attempted to be sorted, but any TypeError from
+            incomparable elements is caught by pandas.
+
+            * None : Attempt to sort the result, but catch any TypeErrors
+              from comparing incomparable elements.
+            * False : Do not sort the result.
+            * True : Sort the result (which may raise TypeError).
+
+        Returns
+        -------
+        Index
+
+        Notes
+        -----
+        ``symmetric_difference`` contains elements that appear in either
+        ``idx1`` or ``idx2`` but not both. Equivalent to the Index created by
+        ``idx1.difference(idx2) | idx2.difference(idx1)`` with duplicates
+        dropped.
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([1, 2, 3, 4])
+        >>> idx2 = pd.Index([2, 3, 4, 5])
+        >>> idx1.symmetric_difference(idx2)
+        Index([1, 5], dtype='int64')
+        """
+        self._validate_sort_keyword(sort)
+        self._assert_can_do_setop(other)
+        other, result_name_update = self._convert_can_do_setop(other)
+        if result_name is None:
+            result_name = result_name_update
+
+        if self.dtype != other.dtype:
+            self, other = self._dti_setop_align_tzs(other, "symmetric_difference")
+
+        if not self._should_compare(other):
+            return self.union(other, sort=sort).rename(result_name)
+
+        elif self.dtype != other.dtype:
+            dtype = self._find_common_type_compat(other)
+            this = self.astype(dtype, copy=False)
+            that = other.astype(dtype, copy=False)
+            return this.symmetric_difference(that, sort=sort).rename(result_name)
+
+        this = self.unique()
+        other = other.unique()
+        indexer = this.get_indexer_for(other)
+
+        # {this} minus {other}
+        common_indexer = indexer.take((indexer != -1).nonzero()[0])
+        left_indexer = np.setdiff1d(
+            np.arange(this.size), common_indexer, assume_unique=True
+        )
+        left_diff = this.take(left_indexer)
+
+        # {other} minus {this}
+        right_indexer = (indexer == -1).nonzero()[0]
+        right_diff = other.take(right_indexer)
+
+        res_values = left_diff.append(right_diff)
+        result = _maybe_try_sort(res_values, sort)
+
+        if not self._is_multi:
+            return Index(result, name=result_name, dtype=res_values.dtype)
+        else:
+            left_diff = cast("MultiIndex", left_diff)
+            if len(result) == 0:
+                # result might be an Index, if other was an Index
+                return left_diff.remove_unused_levels().set_names(result_name)
+            return result.set_names(result_name)
+
+    @final
+    def _assert_can_do_setop(self, other) -> bool:
+        if not is_list_like(other):
+            raise TypeError("Input must be Index or array-like")
+        return True
+
+    def _convert_can_do_setop(self, other) -> tuple[Index, Hashable]:
+        if not isinstance(other, Index):
+            other = Index(other, name=self.name)
+            result_name = self.name
+        else:
+            result_name = get_op_result_name(self, other)
+        return other, result_name
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    def get_loc(self, key):
+        """
+        Get integer location, slice or boolean mask for requested label.
+
+        Parameters
+        ----------
+        key : label
+
+        Returns
+        -------
+        int if unique index, slice if monotonic index, else mask
+
+        Examples
+        --------
+        >>> unique_index = pd.Index(list('abc'))
+        >>> unique_index.get_loc('b')
+        1
+
+        >>> monotonic_index = pd.Index(list('abbc'))
+        >>> monotonic_index.get_loc('b')
+        slice(1, 3, None)
+
+        >>> non_monotonic_index = pd.Index(list('abcb'))
+        >>> non_monotonic_index.get_loc('b')
+        array([False,  True, False,  True])
+        """
+        casted_key = self._maybe_cast_indexer(key)
+        try:
+            return self._engine.get_loc(casted_key)
+        except KeyError as err:
+            if isinstance(casted_key, slice) or (
+                isinstance(casted_key, abc.Iterable)
+                and any(isinstance(x, slice) for x in casted_key)
+            ):
+                raise InvalidIndexError(key)
+            raise KeyError(key) from err
+        except TypeError:
+            # If we have a listlike key, _check_indexing_error will raise
+            #  InvalidIndexError. Otherwise we fall through and re-raise
+            #  the TypeError.
+            self._check_indexing_error(key)
+            raise
+
+    @final
+    def get_indexer(
+        self,
+        target,
+        method: ReindexMethod | None = None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> npt.NDArray[np.intp]:
+        """
+        Compute indexer and mask for new index given the current index.
+
+        The indexer should be then used as an input to ndarray.take to align the
+        current data to the new index.
+
+        Parameters
+        ----------
+        target : Index
+        method : {None, 'pad'/'ffill', 'backfill'/'bfill', 'nearest'}, optional
+            * default: exact matches only.
+            * pad / ffill: find the PREVIOUS index value if no exact match.
+            * backfill / bfill: use NEXT index value if no exact match
+            * nearest: use the NEAREST index value if no exact match. Tied
+              distances are broken by preferring the larger index value.
+        limit : int, optional
+            Maximum number of consecutive labels in ``target`` to match for
+            inexact matches.
+        tolerance : optional
+            Maximum distance between original and new labels for inexact
+            matches. The values of the index at the matching locations must
+            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
+
+            Tolerance may be a scalar value, which applies the same tolerance
+            to all values, or list-like, which applies variable tolerance per
+            element. List-like includes list, tuple, array, Series, and must be
+            the same size as the index and its dtype must exactly match the
+            index's type.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            Integers from 0 to n - 1 indicating that the index at these
+            positions matches the corresponding target values. Missing values
+            in the target are marked by -1.
+
+        Notes
+        -----
+        Returns -1 for unmatched values, for further explanation see the
+        example below.
+
+        Examples
+        --------
+        >>> index = pd.Index(['c', 'a', 'b'])
+        >>> index.get_indexer(['a', 'b', 'x'])
+        array([ 1,  2, -1])
+
+        Notice that the return value is an array of locations in ``index``
+        and ``x`` is marked by -1, as it is not in ``index``.
+        """
+        method = clean_reindex_fill_method(method)
+        orig_target = target
+        target = self._maybe_cast_listlike_indexer(target)
+
+        self._check_indexing_method(method, limit, tolerance)
+
+        if not self._index_as_unique:
+            raise InvalidIndexError(self._requires_unique_msg)
+
+        if len(target) == 0:
+            return np.array([], dtype=np.intp)
+
+        if not self._should_compare(target) and not self._should_partial_index(target):
+            # IntervalIndex get special treatment bc numeric scalars can be
+            #  matched to Interval scalars
+            return self._get_indexer_non_comparable(target, method=method, unique=True)
+
+        if isinstance(self.dtype, CategoricalDtype):
+            # _maybe_cast_listlike_indexer ensures target has our dtype
+            #  (could improve perf by doing _should_compare check earlier?)
+            assert self.dtype == target.dtype
+
+            indexer = self._engine.get_indexer(target.codes)
+            if self.hasnans and target.hasnans:
+                # After _maybe_cast_listlike_indexer, target elements which do not
+                # belong to some category are changed to NaNs
+                # Mask to track actual NaN values compared to inserted NaN values
+                # GH#45361
+                target_nans = isna(orig_target)
+                loc = self.get_loc(np.nan)
+                mask = target.isna()
+                indexer[target_nans] = loc
+                indexer[mask & ~target_nans] = -1
+            return indexer
+
+        if isinstance(target.dtype, CategoricalDtype):
+            # potential fastpath
+            # get an indexer for unique categories then propagate to codes via take_nd
+            # get_indexer instead of _get_indexer needed for MultiIndex cases
+            #  e.g. test_append_different_columns_types
+            categories_indexer = self.get_indexer(target.categories)
+
+            indexer = algos.take_nd(categories_indexer, target.codes, fill_value=-1)
+
+            if (not self._is_multi and self.hasnans) and target.hasnans:
+                # Exclude MultiIndex because hasnans raises NotImplementedError
+                # we should only get here if we are unique, so loc is an integer
+                # GH#41934
+                loc = self.get_loc(np.nan)
+                mask = target.isna()
+                indexer[mask] = loc
+
+            return ensure_platform_int(indexer)
+
+        pself, ptarget = self._maybe_downcast_for_indexing(target)
+        if pself is not self or ptarget is not target:
+            return pself.get_indexer(
+                ptarget, method=method, limit=limit, tolerance=tolerance
+            )
+
+        if self.dtype == target.dtype and self.equals(target):
+            # Only call equals if we have same dtype to avoid inference/casting
+            return np.arange(len(target), dtype=np.intp)
+
+        if self.dtype != target.dtype and not self._should_partial_index(target):
+            # _should_partial_index e.g. IntervalIndex with numeric scalars
+            #  that can be matched to Interval scalars.
+            dtype = self._find_common_type_compat(target)
+
+            this = self.astype(dtype, copy=False)
+            target = target.astype(dtype, copy=False)
+            return this._get_indexer(
+                target, method=method, limit=limit, tolerance=tolerance
+            )
+
+        return self._get_indexer(target, method, limit, tolerance)
+
+    def _get_indexer(
+        self,
+        target: Index,
+        method: str_t | None = None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> npt.NDArray[np.intp]:
+        if tolerance is not None:
+            tolerance = self._convert_tolerance(tolerance, target)
+
+        if method in ["pad", "backfill"]:
+            indexer = self._get_fill_indexer(target, method, limit, tolerance)
+        elif method == "nearest":
+            indexer = self._get_nearest_indexer(target, limit, tolerance)
+        else:
+            if target._is_multi and self._is_multi:
+                engine = self._engine
+                # error: Item "IndexEngine" of "Union[IndexEngine, ExtensionEngine]"
+                # has no attribute "_extract_level_codes"
+                tgt_values = engine._extract_level_codes(  # type: ignore[union-attr]
+                    target
+                )
+            else:
+                tgt_values = target._get_engine_target()
+
+            indexer = self._engine.get_indexer(tgt_values)
+
+        return ensure_platform_int(indexer)
+
+    @final
+    def _should_partial_index(self, target: Index) -> bool:
+        """
+        Should we attempt partial-matching indexing?
+        """
+        if isinstance(self.dtype, IntervalDtype):
+            if isinstance(target.dtype, IntervalDtype):
+                return False
+            # "Index" has no attribute "left"
+            return self.left._should_compare(target)  # type: ignore[attr-defined]
+        return False
+
+    @final
+    def _check_indexing_method(
+        self,
+        method: str_t | None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> None:
+        """
+        Raise if we have a get_indexer `method` that is not supported or valid.
+        """
+        if method not in [None, "bfill", "backfill", "pad", "ffill", "nearest"]:
+            # in practice the clean_reindex_fill_method call would raise
+            #  before we get here
+            raise ValueError("Invalid fill method")  # pragma: no cover
+
+        if self._is_multi:
+            if method == "nearest":
+                raise NotImplementedError(
+                    "method='nearest' not implemented yet "
+                    "for MultiIndex; see GitHub issue 9365"
+                )
+            if method in ("pad", "backfill"):
+                if tolerance is not None:
+                    raise NotImplementedError(
+                        "tolerance not implemented yet for MultiIndex"
+                    )
+
+        if isinstance(self.dtype, (IntervalDtype, CategoricalDtype)):
+            # GH#37871 for now this is only for IntervalIndex and CategoricalIndex
+            if method is not None:
+                raise NotImplementedError(
+                    f"method {method} not yet implemented for {type(self).__name__}"
+                )
+
+        if method is None:
+            if tolerance is not None:
+                raise ValueError(
+                    "tolerance argument only valid if doing pad, "
+                    "backfill or nearest reindexing"
+                )
+            if limit is not None:
+                raise ValueError(
+                    "limit argument only valid if doing pad, "
+                    "backfill or nearest reindexing"
+                )
+
+    def _convert_tolerance(self, tolerance, target: np.ndarray | Index) -> np.ndarray:
+        # override this method on subclasses
+        tolerance = np.asarray(tolerance)
+        if target.size != tolerance.size and tolerance.size > 1:
+            raise ValueError("list-like tolerance size must match target index size")
+        elif is_numeric_dtype(self) and not np.issubdtype(tolerance.dtype, np.number):
+            if tolerance.ndim > 0:
+                raise ValueError(
+                    f"tolerance argument for {type(self).__name__} with dtype "
+                    f"{self.dtype} must contain numeric elements if it is list type"
+                )
+
+            raise ValueError(
+                f"tolerance argument for {type(self).__name__} with dtype {self.dtype} "
+                f"must be numeric if it is a scalar: {repr(tolerance)}"
+            )
+        return tolerance
+
+    @final
+    def _get_fill_indexer(
+        self, target: Index, method: str_t, limit: int | None = None, tolerance=None
+    ) -> npt.NDArray[np.intp]:
+        if self._is_multi:
+            if not (self.is_monotonic_increasing or self.is_monotonic_decreasing):
+                raise ValueError("index must be monotonic increasing or decreasing")
+            encoded = self.append(target)._engine.values  # type: ignore[union-attr]
+            self_encoded = Index(encoded[: len(self)])
+            target_encoded = Index(encoded[len(self) :])
+            return self_encoded._get_fill_indexer(
+                target_encoded, method, limit, tolerance
+            )
+
+        if self.is_monotonic_increasing and target.is_monotonic_increasing:
+            target_values = target._get_engine_target()
+            own_values = self._get_engine_target()
+            if not isinstance(target_values, np.ndarray) or not isinstance(
+                own_values, np.ndarray
+            ):
+                raise NotImplementedError
+
+            if method == "pad":
+                indexer = libalgos.pad(own_values, target_values, limit=limit)
+            else:
+                # i.e. "backfill"
+                indexer = libalgos.backfill(own_values, target_values, limit=limit)
+        else:
+            indexer = self._get_fill_indexer_searchsorted(target, method, limit)
+        if tolerance is not None and len(self):
+            indexer = self._filter_indexer_tolerance(target, indexer, tolerance)
+        return indexer
+
+    @final
+    def _get_fill_indexer_searchsorted(
+        self, target: Index, method: str_t, limit: int | None = None
+    ) -> npt.NDArray[np.intp]:
+        """
+        Fallback pad/backfill get_indexer that works for monotonic decreasing
+        indexes and non-monotonic targets.
+        """
+        if limit is not None:
+            raise ValueError(
+                f"limit argument for {repr(method)} method only well-defined "
+                "if index and target are monotonic"
+            )
+
+        side: Literal["left", "right"] = "left" if method == "pad" else "right"
+
+        # find exact matches first (this simplifies the algorithm)
+        indexer = self.get_indexer(target)
+        nonexact = indexer == -1
+        indexer[nonexact] = self._searchsorted_monotonic(target[nonexact], side)
+        if side == "left":
+            # searchsorted returns "indices into a sorted array such that,
+            # if the corresponding elements in v were inserted before the
+            # indices, the order of a would be preserved".
+            # Thus, we need to subtract 1 to find values to the left.
+            indexer[nonexact] -= 1
+            # This also mapped not found values (values of 0 from
+            # np.searchsorted) to -1, which conveniently is also our
+            # sentinel for missing values
+        else:
+            # Mark indices to the right of the largest value as not found
+            indexer[indexer == len(self)] = -1
+        return indexer
+
+    @final
+    def _get_nearest_indexer(
+        self, target: Index, limit: int | None, tolerance
+    ) -> npt.NDArray[np.intp]:
+        """
+        Get the indexer for the nearest index labels; requires an index with
+        values that can be subtracted from each other (e.g., not strings or
+        tuples).
+        """
+        if not len(self):
+            return self._get_fill_indexer(target, "pad")
+
+        left_indexer = self.get_indexer(target, "pad", limit=limit)
+        right_indexer = self.get_indexer(target, "backfill", limit=limit)
+
+        left_distances = self._difference_compat(target, left_indexer)
+        right_distances = self._difference_compat(target, right_indexer)
+
+        op = operator.lt if self.is_monotonic_increasing else operator.le
+        indexer = np.where(
+            # error: Argument 1&2 has incompatible type "Union[ExtensionArray,
+            # ndarray[Any, Any]]"; expected "Union[SupportsDunderLE,
+            # SupportsDunderGE, SupportsDunderGT, SupportsDunderLT]"
+            op(left_distances, right_distances)  # type: ignore[arg-type]
+            | (right_indexer == -1),
+            left_indexer,
+            right_indexer,
+        )
+        if tolerance is not None:
+            indexer = self._filter_indexer_tolerance(target, indexer, tolerance)
+        return indexer
+
+    @final
+    def _filter_indexer_tolerance(
+        self,
+        target: Index,
+        indexer: npt.NDArray[np.intp],
+        tolerance,
+    ) -> npt.NDArray[np.intp]:
+        distance = self._difference_compat(target, indexer)
+
+        return np.where(distance <= tolerance, indexer, -1)
+
+    @final
+    def _difference_compat(
+        self, target: Index, indexer: npt.NDArray[np.intp]
+    ) -> ArrayLike:
+        # Compatibility for PeriodArray, for which __sub__ returns an ndarray[object]
+        #  of DateOffset objects, which do not support __abs__ (and would be slow
+        #  if they did)
+
+        if isinstance(self.dtype, PeriodDtype):
+            # Note: we only get here with matching dtypes
+            own_values = cast("PeriodArray", self._data)._ndarray
+            target_values = cast("PeriodArray", target._data)._ndarray
+            diff = own_values[indexer] - target_values
+        else:
+            # error: Unsupported left operand type for - ("ExtensionArray")
+            diff = self._values[indexer] - target._values  # type: ignore[operator]
+        return abs(diff)
+
+    # --------------------------------------------------------------------
+    # Indexer Conversion Methods
+
+    @final
+    def _validate_positional_slice(self, key: slice) -> None:
+        """
+        For positional indexing, a slice must have either int or None
+        for each of start, stop, and step.
+        """
+        self._validate_indexer("positional", key.start, "iloc")
+        self._validate_indexer("positional", key.stop, "iloc")
+        self._validate_indexer("positional", key.step, "iloc")
+
+    def _convert_slice_indexer(self, key: slice, kind: Literal["loc", "getitem"]):
+        """
+        Convert a slice indexer.
+
+        By definition, these are labels unless 'iloc' is passed in.
+        Floats are not allowed as the start, step, or stop of the slice.
+
+        Parameters
+        ----------
+        key : label of the slice bound
+        kind : {'loc', 'getitem'}
+        """
+
+        # potentially cast the bounds to integers
+        start, stop, step = key.start, key.stop, key.step
+
+        # figure out if this is a positional indexer
+        is_index_slice = is_valid_positional_slice(key)
+
+        # TODO(GH#50617): once Series.__[gs]etitem__ is removed we should be able
+        #  to simplify this.
+        if lib.is_np_dtype(self.dtype, "f"):
+            # We always treat __getitem__ slicing as label-based
+            # translate to locations
+            if kind == "getitem" and is_index_slice and not start == stop and step != 0:
+                # exclude step=0 from the warning because it will raise anyway
+                # start/stop both None e.g. [:] or [::-1] won't change.
+                # exclude start==stop since it will be empty either way, or
+                # will be [:] or [::-1] which won't change
+                warnings.warn(
+                    # GH#49612
+                    "The behavior of obj[i:j] with a float-dtype index is "
+                    "deprecated. In a future version, this will be treated as "
+                    "positional instead of label-based. For label-based slicing, "
+                    "use obj.loc[i:j] instead",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            return self.slice_indexer(start, stop, step)
+
+        if kind == "getitem":
+            # called from the getitem slicers, validate that we are in fact integers
+            if is_index_slice:
+                # In this case the _validate_indexer checks below are redundant
+                return key
+            elif self.dtype.kind in "iu":
+                # Note: these checks are redundant if we know is_index_slice
+                self._validate_indexer("slice", key.start, "getitem")
+                self._validate_indexer("slice", key.stop, "getitem")
+                self._validate_indexer("slice", key.step, "getitem")
+                return key
+
+        # convert the slice to an indexer here; checking that the user didn't
+        #  pass a positional slice to loc
+        is_positional = is_index_slice and self._should_fallback_to_positional
+
+        # if we are mixed and have integers
+        if is_positional:
+            try:
+                # Validate start & stop
+                if start is not None:
+                    self.get_loc(start)
+                if stop is not None:
+                    self.get_loc(stop)
+                is_positional = False
+            except KeyError:
+                pass
+
+        if com.is_null_slice(key):
+            # It doesn't matter if we are positional or label based
+            indexer = key
+        elif is_positional:
+            if kind == "loc":
+                # GH#16121, GH#24612, GH#31810
+                raise TypeError(
+                    "Slicing a positional slice with .loc is not allowed, "
+                    "Use .loc with labels or .iloc with positions instead.",
+                )
+            indexer = key
+        else:
+            indexer = self.slice_indexer(start, stop, step)
+
+        return indexer
+
+    @final
+    def _raise_invalid_indexer(
+        self,
+        form: Literal["slice", "positional"],
+        key,
+        reraise: lib.NoDefault | None | Exception = lib.no_default,
+    ) -> None:
+        """
+        Raise consistent invalid indexer message.
+        """
+        msg = (
+            f"cannot do {form} indexing on {type(self).__name__} with these "
+            f"indexers [{key}] of type {type(key).__name__}"
+        )
+        if reraise is not lib.no_default:
+            raise TypeError(msg) from reraise
+        raise TypeError(msg)
+
+    # --------------------------------------------------------------------
+    # Reindex Methods
+
+    @final
+    def _validate_can_reindex(self, indexer: np.ndarray) -> None:
+        """
+        Check if we are allowing reindexing with this particular indexer.
+
+        Parameters
+        ----------
+        indexer : an integer ndarray
+
+        Raises
+        ------
+        ValueError if its a duplicate axis
+        """
+        # trying to reindex on an axis with duplicates
+        if not self._index_as_unique and len(indexer):
+            raise ValueError("cannot reindex on an axis with duplicate labels")
+
+    def reindex(
+        self,
+        target,
+        method: ReindexMethod | None = None,
+        level=None,
+        limit: int | None = None,
+        tolerance: float | None = None,
+    ) -> tuple[Index, npt.NDArray[np.intp] | None]:
+        """
+        Create index with target's values.
+
+        Parameters
+        ----------
+        target : an iterable
+        method : {None, 'pad'/'ffill', 'backfill'/'bfill', 'nearest'}, optional
+            * default: exact matches only.
+            * pad / ffill: find the PREVIOUS index value if no exact match.
+            * backfill / bfill: use NEXT index value if no exact match
+            * nearest: use the NEAREST index value if no exact match. Tied
+              distances are broken by preferring the larger index value.
+        level : int, optional
+            Level of multiindex.
+        limit : int, optional
+            Maximum number of consecutive labels in ``target`` to match for
+            inexact matches.
+        tolerance : int or float, optional
+            Maximum distance between original and new labels for inexact
+            matches. The values of the index at the matching locations must
+            satisfy the equation ``abs(index[indexer] - target) <= tolerance``.
+
+            Tolerance may be a scalar value, which applies the same tolerance
+            to all values, or list-like, which applies variable tolerance per
+            element. List-like includes list, tuple, array, Series, and must be
+            the same size as the index and its dtype must exactly match the
+            index's type.
+
+        Returns
+        -------
+        new_index : pd.Index
+            Resulting index.
+        indexer : np.ndarray[np.intp] or None
+            Indices of output values in original index.
+
+        Raises
+        ------
+        TypeError
+            If ``method`` passed along with ``level``.
+        ValueError
+            If non-unique multi-index
+        ValueError
+            If non-unique index and ``method`` or ``limit`` passed.
+
+        See Also
+        --------
+        Series.reindex : Conform Series to new index with optional filling logic.
+        DataFrame.reindex : Conform DataFrame to new index with optional filling logic.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['car', 'bike', 'train', 'tractor'])
+        >>> idx
+        Index(['car', 'bike', 'train', 'tractor'], dtype='object')
+        >>> idx.reindex(['car', 'bike'])
+        (Index(['car', 'bike'], dtype='object'), array([0, 1]))
+        """
+        # GH6552: preserve names when reindexing to non-named target
+        # (i.e. neither Index nor Series).
+        preserve_names = not hasattr(target, "name")
+
+        # GH7774: preserve dtype/tz if target is empty and not an Index.
+        target = ensure_has_len(target)  # target may be an iterator
+
+        if not isinstance(target, Index) and len(target) == 0:
+            if level is not None and self._is_multi:
+                # "Index" has no attribute "levels"; maybe "nlevels"?
+                idx = self.levels[level]  # type: ignore[attr-defined]
+            else:
+                idx = self
+            target = idx[:0]
+        else:
+            target = ensure_index(target)
+
+        if level is not None and (
+            isinstance(self, ABCMultiIndex) or isinstance(target, ABCMultiIndex)
+        ):
+            if method is not None:
+                raise TypeError("Fill method not supported if level passed")
+
+            # TODO: tests where passing `keep_order=not self._is_multi`
+            #  makes a difference for non-MultiIndex case
+            target, indexer, _ = self._join_level(
+                target, level, how="right", keep_order=not self._is_multi
+            )
+
+        else:
+            if self.equals(target):
+                indexer = None
+            else:
+                if self._index_as_unique:
+                    indexer = self.get_indexer(
+                        target, method=method, limit=limit, tolerance=tolerance
+                    )
+                elif self._is_multi:
+                    raise ValueError("cannot handle a non-unique multi-index!")
+                elif not self.is_unique:
+                    # GH#42568
+                    raise ValueError("cannot reindex on an axis with duplicate labels")
+                else:
+                    indexer, _ = self.get_indexer_non_unique(target)
+
+        target = self._wrap_reindex_result(target, indexer, preserve_names)
+        return target, indexer
+
+    def _wrap_reindex_result(self, target, indexer, preserve_names: bool):
+        target = self._maybe_preserve_names(target, preserve_names)
+        return target
+
+    def _maybe_preserve_names(self, target: Index, preserve_names: bool):
+        if preserve_names and target.nlevels == 1 and target.name != self.name:
+            target = target.copy(deep=False)
+            target.name = self.name
+        return target
+
+    @final
+    def _reindex_non_unique(
+        self, target: Index
+    ) -> tuple[Index, npt.NDArray[np.intp], npt.NDArray[np.intp] | None]:
+        """
+        Create a new index with target's values (move/add/delete values as
+        necessary) use with non-unique Index and a possibly non-unique target.
+
+        Parameters
+        ----------
+        target : an iterable
+
+        Returns
+        -------
+        new_index : pd.Index
+            Resulting index.
+        indexer : np.ndarray[np.intp]
+            Indices of output values in original index.
+        new_indexer : np.ndarray[np.intp] or None
+
+        """
+        target = ensure_index(target)
+        if len(target) == 0:
+            # GH#13691
+            return self[:0], np.array([], dtype=np.intp), None
+
+        indexer, missing = self.get_indexer_non_unique(target)
+        check = indexer != -1
+        new_labels: Index | np.ndarray = self.take(indexer[check])
+        new_indexer = None
+
+        if len(missing):
+            length = np.arange(len(indexer), dtype=np.intp)
+
+            missing = ensure_platform_int(missing)
+            missing_labels = target.take(missing)
+            missing_indexer = length[~check]
+            cur_labels = self.take(indexer[check]).values
+            cur_indexer = length[check]
+
+            # Index constructor below will do inference
+            new_labels = np.empty((len(indexer),), dtype=object)
+            new_labels[cur_indexer] = cur_labels
+            new_labels[missing_indexer] = missing_labels
+
+            # GH#38906
+            if not len(self):
+                new_indexer = np.arange(0, dtype=np.intp)
+
+            # a unique indexer
+            elif target.is_unique:
+                # see GH5553, make sure we use the right indexer
+                new_indexer = np.arange(len(indexer), dtype=np.intp)
+                new_indexer[cur_indexer] = np.arange(len(cur_labels))
+                new_indexer[missing_indexer] = -1
+
+            # we have a non_unique selector, need to use the original
+            # indexer here
+            else:
+                # need to retake to have the same size as the indexer
+                indexer[~check] = -1
+
+                # reset the new indexer to account for the new size
+                new_indexer = np.arange(len(self.take(indexer)), dtype=np.intp)
+                new_indexer[~check] = -1
+
+        if not isinstance(self, ABCMultiIndex):
+            new_index = Index(new_labels, name=self.name)
+        else:
+            new_index = type(self).from_tuples(new_labels, names=self.names)
+        return new_index, indexer, new_indexer
+
+    # --------------------------------------------------------------------
+    # Join Methods
+
+    @overload
+    def join(
+        self,
+        other: Index,
+        *,
+        how: JoinHow = ...,
+        level: Level = ...,
+        return_indexers: Literal[True],
+        sort: bool = ...,
+    ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        ...
+
+    @overload
+    def join(
+        self,
+        other: Index,
+        *,
+        how: JoinHow = ...,
+        level: Level = ...,
+        return_indexers: Literal[False] = ...,
+        sort: bool = ...,
+    ) -> Index:
+        ...
+
+    @overload
+    def join(
+        self,
+        other: Index,
+        *,
+        how: JoinHow = ...,
+        level: Level = ...,
+        return_indexers: bool = ...,
+        sort: bool = ...,
+    ) -> Index | tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        ...
+
+    @final
+    @_maybe_return_indexers
+    def join(
+        self,
+        other: Index,
+        *,
+        how: JoinHow = "left",
+        level: Level | None = None,
+        return_indexers: bool = False,
+        sort: bool = False,
+    ) -> Index | tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        """
+        Compute join_index and indexers to conform data structures to the new index.
+
+        Parameters
+        ----------
+        other : Index
+        how : {'left', 'right', 'inner', 'outer'}
+        level : int or level name, default None
+        return_indexers : bool, default False
+        sort : bool, default False
+            Sort the join keys lexicographically in the result Index. If False,
+            the order of the join keys depends on the join type (how keyword).
+
+        Returns
+        -------
+        join_index, (left_indexer, right_indexer)
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([1, 2, 3])
+        >>> idx2 = pd.Index([4, 5, 6])
+        >>> idx1.join(idx2, how='outer')
+        Index([1, 2, 3, 4, 5, 6], dtype='int64')
+        """
+        other = ensure_index(other)
+        sort = sort or how == "outer"
+
+        if isinstance(self, ABCDatetimeIndex) and isinstance(other, ABCDatetimeIndex):
+            if (self.tz is None) ^ (other.tz is None):
+                # Raise instead of casting to object below.
+                raise TypeError("Cannot join tz-naive with tz-aware DatetimeIndex")
+
+        if not self._is_multi and not other._is_multi:
+            # We have specific handling for MultiIndex below
+            pself, pother = self._maybe_downcast_for_indexing(other)
+            if pself is not self or pother is not other:
+                return pself.join(
+                    pother, how=how, level=level, return_indexers=True, sort=sort
+                )
+
+        # try to figure out the join level
+        # GH3662
+        if level is None and (self._is_multi or other._is_multi):
+            # have the same levels/names so a simple join
+            if self.names == other.names:
+                pass
+            else:
+                return self._join_multi(other, how=how)
+
+        # join on the level
+        if level is not None and (self._is_multi or other._is_multi):
+            return self._join_level(other, level, how=how)
+
+        if len(self) == 0 or len(other) == 0:
+            try:
+                return self._join_empty(other, how, sort)
+            except TypeError:
+                # object dtype; non-comparable objects
+                pass
+
+        if self.dtype != other.dtype:
+            dtype = self._find_common_type_compat(other)
+            this = self.astype(dtype, copy=False)
+            other = other.astype(dtype, copy=False)
+            return this.join(other, how=how, return_indexers=True)
+        elif (
+            isinstance(self, ABCCategoricalIndex)
+            and isinstance(other, ABCCategoricalIndex)
+            and not self.ordered
+            and not self.categories.equals(other.categories)
+        ):
+            # dtypes are "equal" but categories are in different order
+            other = Index(other._values.reorder_categories(self.categories))
+
+        _validate_join_method(how)
+
+        if (
+            self.is_monotonic_increasing
+            and other.is_monotonic_increasing
+            and self._can_use_libjoin
+            and other._can_use_libjoin
+            and (self.is_unique or other.is_unique)
+        ):
+            try:
+                return self._join_monotonic(other, how=how)
+            except TypeError:
+                # object dtype; non-comparable objects
+                pass
+        elif not self.is_unique or not other.is_unique:
+            return self._join_non_unique(other, how=how, sort=sort)
+
+        return self._join_via_get_indexer(other, how, sort)
+
+    @final
+    def _join_empty(
+        self, other: Index, how: JoinHow, sort: bool
+    ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        assert len(self) == 0 or len(other) == 0
+        _validate_join_method(how)
+
+        lidx: np.ndarray | None
+        ridx: np.ndarray | None
+
+        if len(other):
+            how = cast(JoinHow, {"left": "right", "right": "left"}.get(how, how))
+            join_index, ridx, lidx = other._join_empty(self, how, sort)
+        elif how in ["left", "outer"]:
+            if sort and not self.is_monotonic_increasing:
+                lidx = self.argsort()
+                join_index = self.take(lidx)
+            else:
+                lidx = None
+                join_index = self._view()
+            ridx = np.broadcast_to(np.intp(-1), len(join_index))
+        else:
+            join_index = other._view()
+            lidx = np.array([], dtype=np.intp)
+            ridx = None
+        return join_index, lidx, ridx
+
+    @final
+    def _join_via_get_indexer(
+        self, other: Index, how: JoinHow, sort: bool
+    ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        # Fallback if we do not have any fastpaths available based on
+        #  uniqueness/monotonicity
+
+        # Note: at this point we have checked matching dtypes
+
+        if how == "left":
+            join_index = self.sort_values() if sort else self
+        elif how == "right":
+            join_index = other.sort_values() if sort else other
+        elif how == "inner":
+            join_index = self.intersection(other, sort=sort)
+        elif how == "outer":
+            try:
+                join_index = self.union(other, sort=sort)
+            except TypeError:
+                join_index = self.union(other)
+                try:
+                    join_index = _maybe_try_sort(join_index, sort)
+                except TypeError:
+                    pass
+
+        if join_index is self:
+            lindexer = None
+        else:
+            lindexer = self.get_indexer_for(join_index)
+        if join_index is other:
+            rindexer = None
+        else:
+            rindexer = other.get_indexer_for(join_index)
+        return join_index, lindexer, rindexer
+
+    @final
+    def _join_multi(self, other: Index, how: JoinHow):
+        from pandas.core.indexes.multi import MultiIndex
+        from pandas.core.reshape.merge import restore_dropped_levels_multijoin
+
+        # figure out join names
+        self_names_list = list(com.not_none(*self.names))
+        other_names_list = list(com.not_none(*other.names))
+        self_names_order = self_names_list.index
+        other_names_order = other_names_list.index
+        self_names = set(self_names_list)
+        other_names = set(other_names_list)
+        overlap = self_names & other_names
+
+        # need at least 1 in common
+        if not overlap:
+            raise ValueError("cannot join with no overlapping index names")
+
+        if isinstance(self, MultiIndex) and isinstance(other, MultiIndex):
+            # Drop the non-matching levels from left and right respectively
+            ldrop_names = sorted(self_names - overlap, key=self_names_order)
+            rdrop_names = sorted(other_names - overlap, key=other_names_order)
+
+            # if only the order differs
+            if not len(ldrop_names + rdrop_names):
+                self_jnlevels = self
+                other_jnlevels = other.reorder_levels(self.names)
+            else:
+                self_jnlevels = self.droplevel(ldrop_names)
+                other_jnlevels = other.droplevel(rdrop_names)
+
+            # Join left and right
+            # Join on same leveled multi-index frames is supported
+            join_idx, lidx, ridx = self_jnlevels.join(
+                other_jnlevels, how=how, return_indexers=True
+            )
+
+            # Restore the dropped levels
+            # Returned index level order is
+            # common levels, ldrop_names, rdrop_names
+            dropped_names = ldrop_names + rdrop_names
+
+            # error: Argument 5/6 to "restore_dropped_levels_multijoin" has
+            # incompatible type "Optional[ndarray[Any, dtype[signedinteger[Any
+            # ]]]]"; expected "ndarray[Any, dtype[signedinteger[Any]]]"
+            levels, codes, names = restore_dropped_levels_multijoin(
+                self,
+                other,
+                dropped_names,
+                join_idx,
+                lidx,  # type: ignore[arg-type]
+                ridx,  # type: ignore[arg-type]
+            )
+
+            # Re-create the multi-index
+            multi_join_idx = MultiIndex(
+                levels=levels, codes=codes, names=names, verify_integrity=False
+            )
+
+            multi_join_idx = multi_join_idx.remove_unused_levels()
+
+            # maintain the order of the index levels
+            if how == "right":
+                level_order = other_names_list + ldrop_names
+            else:
+                level_order = self_names_list + rdrop_names
+            multi_join_idx = multi_join_idx.reorder_levels(level_order)
+
+            return multi_join_idx, lidx, ridx
+
+        jl = next(iter(overlap))
+
+        # Case where only one index is multi
+        # make the indices into mi's that match
+        flip_order = False
+        if isinstance(self, MultiIndex):
+            self, other = other, self
+            flip_order = True
+            # flip if join method is right or left
+            flip: dict[JoinHow, JoinHow] = {"right": "left", "left": "right"}
+            how = flip.get(how, how)
+
+        level = other.names.index(jl)
+        result = self._join_level(other, level, how=how)
+
+        if flip_order:
+            return result[0], result[2], result[1]
+        return result
+
+    @final
+    def _join_non_unique(
+        self, other: Index, how: JoinHow = "left", sort: bool = False
+    ) -> tuple[Index, npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        from pandas.core.reshape.merge import get_join_indexers_non_unique
+
+        # We only get here if dtypes match
+        assert self.dtype == other.dtype
+
+        left_idx, right_idx = get_join_indexers_non_unique(
+            self._values, other._values, how=how, sort=sort
+        )
+        mask = left_idx == -1
+
+        join_idx = self.take(left_idx)
+        right = other.take(right_idx)
+        join_index = join_idx.putmask(mask, right)
+        if isinstance(join_index, ABCMultiIndex) and how == "outer":
+            # test_join_index_levels
+            join_index = join_index._sort_levels_monotonic()
+        return join_index, left_idx, right_idx
+
+    @final
+    def _join_level(
+        self, other: Index, level, how: JoinHow = "left", keep_order: bool = True
+    ) -> tuple[MultiIndex, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        """
+        The join method *only* affects the level of the resulting
+        MultiIndex. Otherwise it just exactly aligns the Index data to the
+        labels of the level in the MultiIndex.
+
+        If ```keep_order == True```, the order of the data indexed by the
+        MultiIndex will not be changed; otherwise, it will tie out
+        with `other`.
+        """
+        from pandas.core.indexes.multi import MultiIndex
+
+        def _get_leaf_sorter(labels: list[np.ndarray]) -> npt.NDArray[np.intp]:
+            """
+            Returns sorter for the inner most level while preserving the
+            order of higher levels.
+
+            Parameters
+            ----------
+            labels : list[np.ndarray]
+                Each ndarray has signed integer dtype, not necessarily identical.
+
+            Returns
+            -------
+            np.ndarray[np.intp]
+            """
+            if labels[0].size == 0:
+                return np.empty(0, dtype=np.intp)
+
+            if len(labels) == 1:
+                return get_group_index_sorter(ensure_platform_int(labels[0]))
+
+            # find indexers of beginning of each set of
+            # same-key labels w.r.t all but last level
+            tic = labels[0][:-1] != labels[0][1:]
+            for lab in labels[1:-1]:
+                tic |= lab[:-1] != lab[1:]
+
+            starts = np.hstack(([True], tic, [True])).nonzero()[0]
+            lab = ensure_int64(labels[-1])
+            return lib.get_level_sorter(lab, ensure_platform_int(starts))
+
+        if isinstance(self, MultiIndex) and isinstance(other, MultiIndex):
+            raise TypeError("Join on level between two MultiIndex objects is ambiguous")
+
+        left, right = self, other
+
+        flip_order = not isinstance(self, MultiIndex)
+        if flip_order:
+            left, right = right, left
+            flip: dict[JoinHow, JoinHow] = {"right": "left", "left": "right"}
+            how = flip.get(how, how)
+
+        assert isinstance(left, MultiIndex)
+
+        level = left._get_level_number(level)
+        old_level = left.levels[level]
+
+        if not right.is_unique:
+            raise NotImplementedError(
+                "Index._join_level on non-unique index is not implemented"
+            )
+
+        new_level, left_lev_indexer, right_lev_indexer = old_level.join(
+            right, how=how, return_indexers=True
+        )
+
+        if left_lev_indexer is None:
+            if keep_order or len(left) == 0:
+                left_indexer = None
+                join_index = left
+            else:  # sort the leaves
+                left_indexer = _get_leaf_sorter(left.codes[: level + 1])
+                join_index = left[left_indexer]
+
+        else:
+            left_lev_indexer = ensure_platform_int(left_lev_indexer)
+            rev_indexer = lib.get_reverse_indexer(left_lev_indexer, len(old_level))
+            old_codes = left.codes[level]
+
+            taker = old_codes[old_codes != -1]
+            new_lev_codes = rev_indexer.take(taker)
+
+            new_codes = list(left.codes)
+            new_codes[level] = new_lev_codes
+
+            new_levels = list(left.levels)
+            new_levels[level] = new_level
+
+            if keep_order:  # just drop missing values. o.w. keep order
+                left_indexer = np.arange(len(left), dtype=np.intp)
+                left_indexer = cast(np.ndarray, left_indexer)
+                mask = new_lev_codes != -1
+                if not mask.all():
+                    new_codes = [lab[mask] for lab in new_codes]
+                    left_indexer = left_indexer[mask]
+
+            else:  # tie out the order with other
+                if level == 0:  # outer most level, take the fast route
+                    max_new_lev = 0 if len(new_lev_codes) == 0 else new_lev_codes.max()
+                    ngroups = 1 + max_new_lev
+                    left_indexer, counts = libalgos.groupsort_indexer(
+                        new_lev_codes, ngroups
+                    )
+
+                    # missing values are placed first; drop them!
+                    left_indexer = left_indexer[counts[0] :]
+                    new_codes = [lab[left_indexer] for lab in new_codes]
+
+                else:  # sort the leaves
+                    mask = new_lev_codes != -1
+                    mask_all = mask.all()
+                    if not mask_all:
+                        new_codes = [lab[mask] for lab in new_codes]
+
+                    left_indexer = _get_leaf_sorter(new_codes[: level + 1])
+                    new_codes = [lab[left_indexer] for lab in new_codes]
+
+                    # left_indexers are w.r.t masked frame.
+                    # reverse to original frame!
+                    if not mask_all:
+                        left_indexer = mask.nonzero()[0][left_indexer]
+
+            join_index = MultiIndex(
+                levels=new_levels,
+                codes=new_codes,
+                names=left.names,
+                verify_integrity=False,
+            )
+
+        if right_lev_indexer is not None:
+            right_indexer = right_lev_indexer.take(join_index.codes[level])
+        else:
+            right_indexer = join_index.codes[level]
+
+        if flip_order:
+            left_indexer, right_indexer = right_indexer, left_indexer
+
+        left_indexer = (
+            None if left_indexer is None else ensure_platform_int(left_indexer)
+        )
+        right_indexer = (
+            None if right_indexer is None else ensure_platform_int(right_indexer)
+        )
+        return join_index, left_indexer, right_indexer
+
+    @final
+    def _join_monotonic(
+        self, other: Index, how: JoinHow = "left"
+    ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        # We only get here with matching dtypes and both monotonic increasing
+        assert other.dtype == self.dtype
+        assert self._can_use_libjoin and other._can_use_libjoin
+
+        if self.equals(other):
+            # This is a convenient place for this check, but its correctness
+            #  does not depend on monotonicity, so it could go earlier
+            #  in the calling method.
+            ret_index = other if how == "right" else self
+            return ret_index, None, None
+
+        ridx: npt.NDArray[np.intp] | None
+        lidx: npt.NDArray[np.intp] | None
+
+        if self.is_unique and other.is_unique:
+            # We can perform much better than the general case
+            if how == "left":
+                join_index = self
+                lidx = None
+                ridx = self._left_indexer_unique(other)
+            elif how == "right":
+                join_index = other
+                lidx = other._left_indexer_unique(self)
+                ridx = None
+            elif how == "inner":
+                join_array, lidx, ridx = self._inner_indexer(other)
+                join_index = self._wrap_joined_index(join_array, other, lidx, ridx)
+            elif how == "outer":
+                join_array, lidx, ridx = self._outer_indexer(other)
+                join_index = self._wrap_joined_index(join_array, other, lidx, ridx)
+        else:
+            if how == "left":
+                join_array, lidx, ridx = self._left_indexer(other)
+            elif how == "right":
+                join_array, ridx, lidx = other._left_indexer(self)
+            elif how == "inner":
+                join_array, lidx, ridx = self._inner_indexer(other)
+            elif how == "outer":
+                join_array, lidx, ridx = self._outer_indexer(other)
+
+            assert lidx is not None
+            assert ridx is not None
+
+            join_index = self._wrap_joined_index(join_array, other, lidx, ridx)
+
+        lidx = None if lidx is None else ensure_platform_int(lidx)
+        ridx = None if ridx is None else ensure_platform_int(ridx)
+        return join_index, lidx, ridx
+
+    def _wrap_joined_index(
+        self,
+        joined: ArrayLike,
+        other: Self,
+        lidx: npt.NDArray[np.intp],
+        ridx: npt.NDArray[np.intp],
+    ) -> Self:
+        assert other.dtype == self.dtype
+
+        if isinstance(self, ABCMultiIndex):
+            name = self.names if self.names == other.names else None
+            # error: Incompatible return value type (got "MultiIndex",
+            # expected "Self")
+            mask = lidx == -1
+            join_idx = self.take(lidx)
+            right = cast("MultiIndex", other.take(ridx))
+            join_index = join_idx.putmask(mask, right)._sort_levels_monotonic()
+            return join_index.set_names(name)  # type: ignore[return-value]
+        else:
+            name = get_op_result_name(self, other)
+            return self._constructor._with_infer(joined, name=name, dtype=self.dtype)
+
+    @final
+    @cache_readonly
+    def _can_use_libjoin(self) -> bool:
+        """
+        Whether we can use the fastpaths implemented in _libs.join.
+
+        This is driven by whether (in monotonic increasing cases that are
+        guaranteed not to have NAs) we can convert to a np.ndarray without
+        making a copy. If we cannot, this negates the performance benefit
+        of using libjoin.
+        """
+        if type(self) is Index:
+            # excludes EAs, but include masks, we get here with monotonic
+            # values only, meaning no NA
+            return (
+                isinstance(self.dtype, np.dtype)
+                or isinstance(self._values, (ArrowExtensionArray, BaseMaskedArray))
+                or (
+                    isinstance(self.dtype, StringDtype)
+                    and self.dtype.storage == "python"
+                )
+            )
+        # Exclude index types where the conversion to numpy converts to object dtype,
+        #  which negates the performance benefit of libjoin
+        # Subclasses should override to return False if _get_join_target is
+        #  not zero-copy.
+        # TODO: exclude RangeIndex (which allocates memory)?
+        #  Doing so seems to break test_concat_datetime_timezone
+        return not isinstance(self, (ABCIntervalIndex, ABCMultiIndex))
+
+    # --------------------------------------------------------------------
+    # Uncategorized Methods
+
+    @property
+    def values(self) -> ArrayLike:
+        """
+        Return an array representing the data in the Index.
+
+        .. warning::
+
+           We recommend using :attr:`Index.array` or
+           :meth:`Index.to_numpy`, depending on whether you need
+           a reference to the underlying data or a NumPy array.
+
+        Returns
+        -------
+        array: numpy.ndarray or ExtensionArray
+
+        See Also
+        --------
+        Index.array : Reference to the underlying data.
+        Index.to_numpy : A NumPy array representing the underlying data.
+
+        Examples
+        --------
+        For :class:`pandas.Index`:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.values
+        array([1, 2, 3])
+
+        For :class:`pandas.IntervalIndex`:
+
+        >>> idx = pd.interval_range(start=0, end=5)
+        >>> idx.values
+        
+        [(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]]
+        Length: 5, dtype: interval[int64, right]
+        """
+        if using_copy_on_write():
+            data = self._data
+            if isinstance(data, np.ndarray):
+                data = data.view()
+                data.flags.writeable = False
+            return data
+        return self._data
+
+    @cache_readonly
+    @doc(IndexOpsMixin.array)
+    def array(self) -> ExtensionArray:
+        array = self._data
+        if isinstance(array, np.ndarray):
+            from pandas.core.arrays.numpy_ import NumpyExtensionArray
+
+            array = NumpyExtensionArray(array)
+        return array
+
+    @property
+    def _values(self) -> ExtensionArray | np.ndarray:
+        """
+        The best array representation.
+
+        This is an ndarray or ExtensionArray.
+
+        ``_values`` are consistent between ``Series`` and ``Index``.
+
+        It may differ from the public '.values' method.
+
+        index             | values          | _values       |
+        ----------------- | --------------- | ------------- |
+        Index             | ndarray         | ndarray       |
+        CategoricalIndex  | Categorical     | Categorical   |
+        DatetimeIndex     | ndarray[M8ns]   | DatetimeArray |
+        DatetimeIndex[tz] | ndarray[M8ns]   | DatetimeArray |
+        PeriodIndex       | ndarray[object] | PeriodArray   |
+        IntervalIndex     | IntervalArray   | IntervalArray |
+
+        See Also
+        --------
+        values : Values
+        """
+        return self._data
+
+    def _get_engine_target(self) -> ArrayLike:
+        """
+        Get the ndarray or ExtensionArray that we can pass to the IndexEngine
+        constructor.
+        """
+        vals = self._values
+        if isinstance(vals, StringArray):
+            # GH#45652 much more performant than ExtensionEngine
+            return vals._ndarray
+        if isinstance(vals, ArrowExtensionArray) and self.dtype.kind in "Mm":
+            import pyarrow as pa
+
+            pa_type = vals._pa_array.type
+            if pa.types.is_timestamp(pa_type):
+                vals = vals._to_datetimearray()
+                return vals._ndarray.view("i8")
+            elif pa.types.is_duration(pa_type):
+                vals = vals._to_timedeltaarray()
+                return vals._ndarray.view("i8")
+        if (
+            type(self) is Index
+            and isinstance(self._values, ExtensionArray)
+            and not isinstance(self._values, BaseMaskedArray)
+            and not (
+                isinstance(self._values, ArrowExtensionArray)
+                and is_numeric_dtype(self.dtype)
+                # Exclude decimal
+                and self.dtype.kind != "O"
+            )
+        ):
+            # TODO(ExtensionIndex): remove special-case, just use self._values
+            return self._values.astype(object)
+        return vals
+
+    @final
+    def _get_join_target(self) -> np.ndarray:
+        """
+        Get the ndarray or ExtensionArray that we can pass to the join
+        functions.
+        """
+        if isinstance(self._values, BaseMaskedArray):
+            # This is only used if our array is monotonic, so no NAs present
+            return self._values._data
+        elif isinstance(self._values, ArrowExtensionArray):
+            # This is only used if our array is monotonic, so no missing values
+            # present
+            return self._values.to_numpy()
+
+        # TODO: exclude ABCRangeIndex case here as it copies
+        target = self._get_engine_target()
+        if not isinstance(target, np.ndarray):
+            raise ValueError("_can_use_libjoin should return False.")
+        return target
+
+    def _from_join_target(self, result: np.ndarray) -> ArrayLike:
+        """
+        Cast the ndarray returned from one of the libjoin.foo_indexer functions
+        back to type(self._data).
+        """
+        if isinstance(self.values, BaseMaskedArray):
+            return type(self.values)(result, np.zeros(result.shape, dtype=np.bool_))
+        elif isinstance(self.values, (ArrowExtensionArray, StringArray)):
+            return type(self.values)._from_sequence(result, dtype=self.dtype)
+        return result
+
+    @doc(IndexOpsMixin._memory_usage)
+    def memory_usage(self, deep: bool = False) -> int:
+        result = self._memory_usage(deep=deep)
+
+        # include our engine hashtable
+        result += self._engine.sizeof(deep=deep)
+        return result
+
+    @final
+    def where(self, cond, other=None) -> Index:
+        """
+        Replace values where the condition is False.
+
+        The replacement is taken from other.
+
+        Parameters
+        ----------
+        cond : bool array-like with the same length as self
+            Condition to select the values on.
+        other : scalar, or array-like, default None
+            Replacement if the condition is False.
+
+        Returns
+        -------
+        pandas.Index
+            A copy of self with values replaced from other
+            where the condition is False.
+
+        See Also
+        --------
+        Series.where : Same method for Series.
+        DataFrame.where : Same method for DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['car', 'bike', 'train', 'tractor'])
+        >>> idx
+        Index(['car', 'bike', 'train', 'tractor'], dtype='object')
+        >>> idx.where(idx.isin(['car', 'train']), 'other')
+        Index(['car', 'other', 'train', 'other'], dtype='object')
+        """
+        if isinstance(self, ABCMultiIndex):
+            raise NotImplementedError(
+                ".where is not supported for MultiIndex operations"
+            )
+        cond = np.asarray(cond, dtype=bool)
+        return self.putmask(~cond, other)
+
+    # construction helpers
+    @final
+    @classmethod
+    def _raise_scalar_data_error(cls, data):
+        # We return the TypeError so that we can raise it from the constructor
+        #  in order to keep mypy happy
+        raise TypeError(
+            f"{cls.__name__}(...) must be called with a collection of some "
+            f"kind, {repr(data) if not isinstance(data, np.generic) else str(data)} "
+            "was passed"
+        )
+
+    def _validate_fill_value(self, value):
+        """
+        Check if the value can be inserted into our array without casting,
+        and convert it to an appropriate native type if necessary.
+
+        Raises
+        ------
+        TypeError
+            If the value cannot be inserted into an array of this dtype.
+        """
+        dtype = self.dtype
+        if isinstance(dtype, np.dtype) and dtype.kind not in "mM":
+            # return np_can_hold_element(dtype, value)
+            try:
+                return np_can_hold_element(dtype, value)
+            except LossySetitemError as err:
+                # re-raise as TypeError for consistency
+                raise TypeError from err
+        elif not can_hold_element(self._values, value):
+            raise TypeError
+        return value
+
+    def _is_memory_usage_qualified(self) -> bool:
+        """
+        Return a boolean if we need a qualified .info display.
+        """
+        return is_object_dtype(self.dtype) or (
+            is_string_dtype(self.dtype) and self.dtype.storage == "python"  # type: ignore[union-attr]
+        )
+
+    def __contains__(self, key: Any) -> bool:
+        """
+        Return a boolean indicating whether the provided key is in the index.
+
+        Parameters
+        ----------
+        key : label
+            The key to check if it is present in the index.
+
+        Returns
+        -------
+        bool
+            Whether the key search is in the index.
+
+        Raises
+        ------
+        TypeError
+            If the key is not hashable.
+
+        See Also
+        --------
+        Index.isin : Returns an ndarray of boolean dtype indicating whether the
+            list-like key is in the index.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3, 4])
+        >>> idx
+        Index([1, 2, 3, 4], dtype='int64')
+
+        >>> 2 in idx
+        True
+        >>> 6 in idx
+        False
+        """
+        hash(key)
+        try:
+            return key in self._engine
+        except (OverflowError, TypeError, ValueError):
+            return False
+
+    # https://github.com/python/typeshed/issues/2148#issuecomment-520783318
+    # Incompatible types in assignment (expression has type "None", base class
+    # "object" defined the type as "Callable[[object], int]")
+    __hash__: ClassVar[None]  # type: ignore[assignment]
+
+    @final
+    def __setitem__(self, key, value) -> None:
+        raise TypeError("Index does not support mutable operations")
+
+    def __getitem__(self, key):
+        """
+        Override numpy.ndarray's __getitem__ method to work as desired.
+
+        This function adds lists and Series as valid boolean indexers
+        (ndarrays only supports ndarray with dtype=bool).
+
+        If resulting ndim != 1, plain ndarray is returned instead of
+        corresponding `Index` subclass.
+
+        """
+        getitem = self._data.__getitem__
+
+        if is_integer(key) or is_float(key):
+            # GH#44051 exclude bool, which would return a 2d ndarray
+            key = com.cast_scalar_indexer(key)
+            return getitem(key)
+
+        if isinstance(key, slice):
+            # This case is separated from the conditional above to avoid
+            # pessimization com.is_bool_indexer and ndim checks.
+            return self._getitem_slice(key)
+
+        if com.is_bool_indexer(key):
+            # if we have list[bools, length=1e5] then doing this check+convert
+            #  takes 166 µs + 2.1 ms and cuts the ndarray.__getitem__
+            #  time below from 3.8 ms to 496 µs
+            # if we already have ndarray[bool], the overhead is 1.4 µs or .25%
+            if isinstance(getattr(key, "dtype", None), ExtensionDtype):
+                key = key.to_numpy(dtype=bool, na_value=False)
+            else:
+                key = np.asarray(key, dtype=bool)
+
+            if not isinstance(self.dtype, ExtensionDtype):
+                if len(key) == 0 and len(key) != len(self):
+                    warnings.warn(
+                        "Using a boolean indexer with length 0 on an Index with "
+                        "length greater than 0 is deprecated and will raise in a "
+                        "future version.",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+
+        result = getitem(key)
+        # Because we ruled out integer above, we always get an arraylike here
+        if result.ndim > 1:
+            disallow_ndim_indexing(result)
+
+        # NB: Using _constructor._simple_new would break if MultiIndex
+        #  didn't override __getitem__
+        return self._constructor._simple_new(result, name=self._name)
+
+    def _getitem_slice(self, slobj: slice) -> Self:
+        """
+        Fastpath for __getitem__ when we know we have a slice.
+        """
+        res = self._data[slobj]
+        result = type(self)._simple_new(res, name=self._name, refs=self._references)
+        if "_engine" in self._cache:
+            reverse = slobj.step is not None and slobj.step < 0
+            result._engine._update_from_sliced(self._engine, reverse=reverse)  # type: ignore[union-attr]
+
+        return result
+
+    @final
+    def _can_hold_identifiers_and_holds_name(self, name) -> bool:
+        """
+        Faster check for ``name in self`` when we know `name` is a Python
+        identifier (e.g. in NDFrame.__getattr__, which hits this to support
+        . key lookup). For indexes that can't hold identifiers (everything
+        but object & categorical) we just return False.
+
+        https://github.com/pandas-dev/pandas/issues/19764
+        """
+        if (
+            is_object_dtype(self.dtype)
+            or is_string_dtype(self.dtype)
+            or isinstance(self.dtype, CategoricalDtype)
+        ):
+            return name in self
+        return False
+
+    def append(self, other: Index | Sequence[Index]) -> Index:
+        """
+        Append a collection of Index options together.
+
+        Parameters
+        ----------
+        other : Index or list/tuple of indices
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx.append(pd.Index([4]))
+        Index([1, 2, 3, 4], dtype='int64')
+        """
+        to_concat = [self]
+
+        if isinstance(other, (list, tuple)):
+            to_concat += list(other)
+        else:
+            # error: Argument 1 to "append" of "list" has incompatible type
+            # "Union[Index, Sequence[Index]]"; expected "Index"
+            to_concat.append(other)  # type: ignore[arg-type]
+
+        for obj in to_concat:
+            if not isinstance(obj, Index):
+                raise TypeError("all inputs must be Index")
+
+        names = {obj.name for obj in to_concat}
+        name = None if len(names) > 1 else self.name
+
+        return self._concat(to_concat, name)
+
+    def _concat(self, to_concat: list[Index], name: Hashable) -> Index:
+        """
+        Concatenate multiple Index objects.
+        """
+        to_concat_vals = [x._values for x in to_concat]
+
+        result = concat_compat(to_concat_vals)
+
+        return Index._with_infer(result, name=name)
+
+    def putmask(self, mask, value) -> Index:
+        """
+        Return a new Index of the values set with the mask.
+
+        Returns
+        -------
+        Index
+
+        See Also
+        --------
+        numpy.ndarray.putmask : Changes elements of an array
+            based on conditional and input values.
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([1, 2, 3])
+        >>> idx2 = pd.Index([5, 6, 7])
+        >>> idx1.putmask([True, False, False], idx2)
+        Index([5, 2, 3], dtype='int64')
+        """
+        mask, noop = validate_putmask(self._values, mask)
+        if noop:
+            return self.copy()
+
+        if self.dtype != object and is_valid_na_for_dtype(value, self.dtype):
+            # e.g. None -> np.nan, see also Block._standardize_fill_value
+            value = self._na_value
+
+        try:
+            converted = self._validate_fill_value(value)
+        except (LossySetitemError, ValueError, TypeError) as err:
+            if is_object_dtype(self.dtype):  # pragma: no cover
+                raise err
+
+            # See also: Block.coerce_to_target_dtype
+            dtype = self._find_common_type_compat(value)
+            return self.astype(dtype).putmask(mask, value)
+
+        values = self._values.copy()
+
+        if isinstance(values, np.ndarray):
+            converted = setitem_datetimelike_compat(values, mask.sum(), converted)
+            np.putmask(values, mask, converted)
+
+        else:
+            # Note: we use the original value here, not converted, as
+            #  _validate_fill_value is not idempotent
+            values._putmask(mask, value)
+
+        return self._shallow_copy(values)
+
+    def equals(self, other: Any) -> bool:
+        """
+        Determine if two Index object are equal.
+
+        The things that are being compared are:
+
+        * The elements inside the Index object.
+        * The order of the elements inside the Index object.
+
+        Parameters
+        ----------
+        other : Any
+            The other object to compare against.
+
+        Returns
+        -------
+        bool
+            True if "other" is an Index and it has the same elements and order
+            as the calling index; False otherwise.
+
+        Examples
+        --------
+        >>> idx1 = pd.Index([1, 2, 3])
+        >>> idx1
+        Index([1, 2, 3], dtype='int64')
+        >>> idx1.equals(pd.Index([1, 2, 3]))
+        True
+
+        The elements inside are compared
+
+        >>> idx2 = pd.Index(["1", "2", "3"])
+        >>> idx2
+        Index(['1', '2', '3'], dtype='object')
+
+        >>> idx1.equals(idx2)
+        False
+
+        The order is compared
+
+        >>> ascending_idx = pd.Index([1, 2, 3])
+        >>> ascending_idx
+        Index([1, 2, 3], dtype='int64')
+        >>> descending_idx = pd.Index([3, 2, 1])
+        >>> descending_idx
+        Index([3, 2, 1], dtype='int64')
+        >>> ascending_idx.equals(descending_idx)
+        False
+
+        The dtype is *not* compared
+
+        >>> int64_idx = pd.Index([1, 2, 3], dtype='int64')
+        >>> int64_idx
+        Index([1, 2, 3], dtype='int64')
+        >>> uint64_idx = pd.Index([1, 2, 3], dtype='uint64')
+        >>> uint64_idx
+        Index([1, 2, 3], dtype='uint64')
+        >>> int64_idx.equals(uint64_idx)
+        True
+        """
+        if self.is_(other):
+            return True
+
+        if not isinstance(other, Index):
+            return False
+
+        if len(self) != len(other):
+            # quickly return if the lengths are different
+            return False
+
+        if (
+            isinstance(self.dtype, StringDtype)
+            and self.dtype.na_value is np.nan
+            and other.dtype != self.dtype
+        ):
+            # TODO(infer_string) can we avoid this special case?
+            # special case for object behavior
+            return other.equals(self.astype(object))
+
+        if is_object_dtype(self.dtype) and not is_object_dtype(other.dtype):
+            # if other is not object, use other's logic for coercion
+            return other.equals(self)
+
+        if isinstance(other, ABCMultiIndex):
+            # d-level MultiIndex can equal d-tuple Index
+            return other.equals(self)
+
+        if isinstance(self._values, ExtensionArray):
+            # Dispatch to the ExtensionArray's .equals method.
+            if not isinstance(other, type(self)):
+                return False
+
+            earr = cast(ExtensionArray, self._data)
+            return earr.equals(other._data)
+
+        if isinstance(other.dtype, ExtensionDtype):
+            # All EA-backed Index subclasses override equals
+            return other.equals(self)
+
+        return array_equivalent(self._values, other._values)
+
+    @final
+    def identical(self, other) -> bool:
+        """
+        Similar to equals, but checks that object attributes and types are also equal.
+
+        Returns
+        -------
+        bool
+            If two Index objects have equal elements and same type True,
+            otherwise False.
+
+        Examples
+        --------
+        >>> idx1 = pd.Index(['1', '2', '3'])
+        >>> idx2 = pd.Index(['1', '2', '3'])
+        >>> idx2.identical(idx1)
+        True
+
+        >>> idx1 = pd.Index(['1', '2', '3'], name="A")
+        >>> idx2 = pd.Index(['1', '2', '3'], name="B")
+        >>> idx2.identical(idx1)
+        False
+        """
+        return (
+            self.equals(other)
+            and all(
+                getattr(self, c, None) == getattr(other, c, None)
+                for c in self._comparables
+            )
+            and type(self) == type(other)
+            and self.dtype == other.dtype
+        )
+
+    @final
+    def asof(self, label):
+        """
+        Return the label from the index, or, if not present, the previous one.
+
+        Assuming that the index is sorted, return the passed index label if it
+        is in the index, or return the previous index label if the passed one
+        is not in the index.
+
+        Parameters
+        ----------
+        label : object
+            The label up to which the method returns the latest index label.
+
+        Returns
+        -------
+        object
+            The passed label if it is in the index. The previous label if the
+            passed label is not in the sorted index or `NaN` if there is no
+            such label.
+
+        See Also
+        --------
+        Series.asof : Return the latest value in a Series up to the
+            passed index.
+        merge_asof : Perform an asof merge (similar to left join but it
+            matches on nearest key rather than equal key).
+        Index.get_loc : An `asof` is a thin wrapper around `get_loc`
+            with method='pad'.
+
+        Examples
+        --------
+        `Index.asof` returns the latest index label up to the passed label.
+
+        >>> idx = pd.Index(['2013-12-31', '2014-01-02', '2014-01-03'])
+        >>> idx.asof('2014-01-01')
+        '2013-12-31'
+
+        If the label is in the index, the method returns the passed label.
+
+        >>> idx.asof('2014-01-02')
+        '2014-01-02'
+
+        If all of the labels in the index are later than the passed label,
+        NaN is returned.
+
+        >>> idx.asof('1999-01-02')
+        nan
+
+        If the index is not sorted, an error is raised.
+
+        >>> idx_not_sorted = pd.Index(['2013-12-31', '2015-01-02',
+        ...                            '2014-01-03'])
+        >>> idx_not_sorted.asof('2013-12-31')
+        Traceback (most recent call last):
+        ValueError: index must be monotonic increasing or decreasing
+        """
+        self._searchsorted_monotonic(label)  # validate sortedness
+        try:
+            loc = self.get_loc(label)
+        except (KeyError, TypeError):
+            # KeyError -> No exact match, try for padded
+            # TypeError -> passed e.g. non-hashable, fall through to get
+            #  the tested exception message
+            indexer = self.get_indexer([label], method="pad")
+            if indexer.ndim > 1 or indexer.size > 1:
+                raise TypeError("asof requires scalar valued input")
+            loc = indexer.item()
+            if loc == -1:
+                return self._na_value
+        else:
+            if isinstance(loc, slice):
+                loc = loc.indices(len(self))[-1]
+
+        return self[loc]
+
+    def asof_locs(
+        self, where: Index, mask: npt.NDArray[np.bool_]
+    ) -> npt.NDArray[np.intp]:
+        """
+        Return the locations (indices) of labels in the index.
+
+        As in the :meth:`pandas.Index.asof`, if the label (a particular entry in
+        ``where``) is not in the index, the latest index label up to the
+        passed label is chosen and its index returned.
+
+        If all of the labels in the index are later than a label in ``where``,
+        -1 is returned.
+
+        ``mask`` is used to ignore ``NA`` values in the index during calculation.
+
+        Parameters
+        ----------
+        where : Index
+            An Index consisting of an array of timestamps.
+        mask : np.ndarray[bool]
+            Array of booleans denoting where values in the original
+            data are not ``NA``.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            An array of locations (indices) of the labels from the index
+            which correspond to the return values of :meth:`pandas.Index.asof`
+            for every element in ``where``.
+
+        See Also
+        --------
+        Index.asof : Return the label from the index, or, if not present, the
+            previous one.
+
+        Examples
+        --------
+        >>> idx = pd.date_range('2023-06-01', periods=3, freq='D')
+        >>> where = pd.DatetimeIndex(['2023-05-30 00:12:00', '2023-06-01 00:00:00',
+        ...                           '2023-06-02 23:59:59'])
+        >>> mask = np.ones(3, dtype=bool)
+        >>> idx.asof_locs(where, mask)
+        array([-1,  0,  1])
+
+        We can use ``mask`` to ignore certain values in the index during calculation.
+
+        >>> mask[1] = False
+        >>> idx.asof_locs(where, mask)
+        array([-1,  0,  0])
+        """
+        # error: No overload variant of "searchsorted" of "ndarray" matches argument
+        # types "Union[ExtensionArray, ndarray[Any, Any]]", "str"
+        # TODO: will be fixed when ExtensionArray.searchsorted() is fixed
+        locs = self._values[mask].searchsorted(
+            where._values, side="right"  # type: ignore[call-overload]
+        )
+        locs = np.where(locs > 0, locs - 1, 0)
+
+        result = np.arange(len(self), dtype=np.intp)[mask].take(locs)
+
+        first_value = self._values[mask.argmax()]
+        result[(locs == 0) & (where._values < first_value)] = -1
+
+        return result
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        return_indexer: Literal[False] = ...,
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        return_indexer: Literal[True],
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> tuple[Self, np.ndarray]:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        return_indexer: bool = ...,
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> Self | tuple[Self, np.ndarray]:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self"], name="sort_values"
+    )
+    def sort_values(
+        self,
+        return_indexer: bool = False,
+        ascending: bool = True,
+        na_position: NaPosition = "last",
+        key: Callable | None = None,
+    ) -> Self | tuple[Self, np.ndarray]:
+        """
+        Return a sorted copy of the index.
+
+        Return a sorted copy of the index, and optionally return the indices
+        that sorted the index itself.
+
+        Parameters
+        ----------
+        return_indexer : bool, default False
+            Should the indices that would sort the index be returned.
+        ascending : bool, default True
+            Should the index values be sorted in an ascending order.
+        na_position : {'first' or 'last'}, default 'last'
+            Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
+            the end.
+        key : callable, optional
+            If not None, apply the key function to the index values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect an
+            ``Index`` and return an ``Index`` of the same shape.
+
+        Returns
+        -------
+        sorted_index : pandas.Index
+            Sorted copy of the index.
+        indexer : numpy.ndarray, optional
+            The indices that the index itself was sorted by.
+
+        See Also
+        --------
+        Series.sort_values : Sort values of a Series.
+        DataFrame.sort_values : Sort values in a DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index([10, 100, 1, 1000])
+        >>> idx
+        Index([10, 100, 1, 1000], dtype='int64')
+
+        Sort values in ascending order (default behavior).
+
+        >>> idx.sort_values()
+        Index([1, 10, 100, 1000], dtype='int64')
+
+        Sort values in descending order, and also get the indices `idx` was
+        sorted by.
+
+        >>> idx.sort_values(ascending=False, return_indexer=True)
+        (Index([1000, 100, 10, 1], dtype='int64'), array([3, 1, 0, 2]))
+        """
+        if key is None and (
+            (ascending and self.is_monotonic_increasing)
+            or (not ascending and self.is_monotonic_decreasing)
+        ):
+            if return_indexer:
+                indexer = np.arange(len(self), dtype=np.intp)
+                return self.copy(), indexer
+            else:
+                return self.copy()
+
+        # GH 35584. Sort missing values according to na_position kwarg
+        # ignore na_position for MultiIndex
+        if not isinstance(self, ABCMultiIndex):
+            _as = nargsort(
+                items=self, ascending=ascending, na_position=na_position, key=key
+            )
+        else:
+            idx = cast(Index, ensure_key_mapped(self, key))
+            _as = idx.argsort(na_position=na_position)
+            if not ascending:
+                _as = _as[::-1]
+
+        sorted_index = self.take(_as)
+
+        if return_indexer:
+            return sorted_index, _as
+        else:
+            return sorted_index
+
+    @final
+    def sort(self, *args, **kwargs):
+        """
+        Use sort_values instead.
+        """
+        raise TypeError("cannot sort an Index object in-place, use sort_values instead")
+
+    def shift(self, periods: int = 1, freq=None):
+        """
+        Shift index by desired number of time frequency increments.
+
+        This method is for shifting the values of datetime-like indexes
+        by a specified time increment a given number of times.
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Number of periods (or increments) to shift by,
+            can be positive or negative.
+        freq : pandas.DateOffset, pandas.Timedelta or str, optional
+            Frequency increment to shift by.
+            If None, the index is shifted by its own `freq` attribute.
+            Offset aliases are valid strings, e.g., 'D', 'W', 'M' etc.
+
+        Returns
+        -------
+        pandas.Index
+            Shifted index.
+
+        See Also
+        --------
+        Series.shift : Shift values of Series.
+
+        Notes
+        -----
+        This method is only implemented for datetime-like index classes,
+        i.e., DatetimeIndex, PeriodIndex and TimedeltaIndex.
+
+        Examples
+        --------
+        Put the first 5 month starts of 2011 into an index.
+
+        >>> month_starts = pd.date_range('1/1/2011', periods=5, freq='MS')
+        >>> month_starts
+        DatetimeIndex(['2011-01-01', '2011-02-01', '2011-03-01', '2011-04-01',
+                       '2011-05-01'],
+                      dtype='datetime64[ns]', freq='MS')
+
+        Shift the index by 10 days.
+
+        >>> month_starts.shift(10, freq='D')
+        DatetimeIndex(['2011-01-11', '2011-02-11', '2011-03-11', '2011-04-11',
+                       '2011-05-11'],
+                      dtype='datetime64[ns]', freq=None)
+
+        The default value of `freq` is the `freq` attribute of the index,
+        which is 'MS' (month start) in this example.
+
+        >>> month_starts.shift(10)
+        DatetimeIndex(['2011-11-01', '2011-12-01', '2012-01-01', '2012-02-01',
+                       '2012-03-01'],
+                      dtype='datetime64[ns]', freq='MS')
+        """
+        raise NotImplementedError(
+            f"This method is only implemented for DatetimeIndex, PeriodIndex and "
+            f"TimedeltaIndex; Got type {type(self).__name__}"
+        )
+
+    def argsort(self, *args, **kwargs) -> npt.NDArray[np.intp]:
+        """
+        Return the integer indices that would sort the index.
+
+        Parameters
+        ----------
+        *args
+            Passed to `numpy.ndarray.argsort`.
+        **kwargs
+            Passed to `numpy.ndarray.argsort`.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            Integer indices that would sort the index if used as
+            an indexer.
+
+        See Also
+        --------
+        numpy.argsort : Similar method for NumPy arrays.
+        Index.sort_values : Return sorted copy of Index.
+
+        Examples
+        --------
+        >>> idx = pd.Index(['b', 'a', 'd', 'c'])
+        >>> idx
+        Index(['b', 'a', 'd', 'c'], dtype='object')
+
+        >>> order = idx.argsort()
+        >>> order
+        array([1, 0, 3, 2])
+
+        >>> idx[order]
+        Index(['a', 'b', 'c', 'd'], dtype='object')
+        """
+        # This works for either ndarray or EA, is overridden
+        #  by RangeIndex, MultIIndex
+        return self._data.argsort(*args, **kwargs)
+
+    def _check_indexing_error(self, key):
+        if not is_scalar(key):
+            # if key is not a scalar, directly raise an error (the code below
+            # would convert to numpy arrays and raise later any way) - GH29926
+            raise InvalidIndexError(key)
+
+    @cache_readonly
+    def _should_fallback_to_positional(self) -> bool:
+        """
+        Should an integer key be treated as positional?
+        """
+        return self.inferred_type not in {
+            "integer",
+            "mixed-integer",
+            "floating",
+            "complex",
+        }
+
+    _index_shared_docs[
+        "get_indexer_non_unique"
+    ] = """
+        Compute indexer and mask for new index given the current index.
+
+        The indexer should be then used as an input to ndarray.take to align the
+        current data to the new index.
+
+        Parameters
+        ----------
+        target : %(target_klass)s
+
+        Returns
+        -------
+        indexer : np.ndarray[np.intp]
+            Integers from 0 to n - 1 indicating that the index at these
+            positions matches the corresponding target values. Missing values
+            in the target are marked by -1.
+        missing : np.ndarray[np.intp]
+            An indexer into the target of the values not found.
+            These correspond to the -1 in the indexer array.
+
+        Examples
+        --------
+        >>> index = pd.Index(['c', 'b', 'a', 'b', 'b'])
+        >>> index.get_indexer_non_unique(['b', 'b'])
+        (array([1, 3, 4, 1, 3, 4]), array([], dtype=int64))
+
+        In the example below there are no matched values.
+
+        >>> index = pd.Index(['c', 'b', 'a', 'b', 'b'])
+        >>> index.get_indexer_non_unique(['q', 'r', 't'])
+        (array([-1, -1, -1]), array([0, 1, 2]))
+
+        For this reason, the returned ``indexer`` contains only integers equal to -1.
+        It demonstrates that there's no match between the index and the ``target``
+        values at these positions. The mask [0, 1, 2] in the return value shows that
+        the first, second, and third elements are missing.
+
+        Notice that the return value is a tuple contains two items. In the example
+        below the first item is an array of locations in ``index``. The second
+        item is a mask shows that the first and third elements are missing.
+
+        >>> index = pd.Index(['c', 'b', 'a', 'b', 'b'])
+        >>> index.get_indexer_non_unique(['f', 'b', 's'])
+        (array([-1,  1,  3,  4, -1]), array([0, 2]))
+        """
+
+    @Appender(_index_shared_docs["get_indexer_non_unique"] % _index_doc_kwargs)
+    def get_indexer_non_unique(
+        self, target
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        target = self._maybe_cast_listlike_indexer(target)
+
+        if not self._should_compare(target) and not self._should_partial_index(target):
+            # _should_partial_index e.g. IntervalIndex with numeric scalars
+            #  that can be matched to Interval scalars.
+            return self._get_indexer_non_comparable(target, method=None, unique=False)
+
+        pself, ptarget = self._maybe_downcast_for_indexing(target)
+        if pself is not self or ptarget is not target:
+            return pself.get_indexer_non_unique(ptarget)
+
+        if self.dtype != target.dtype:
+            # TODO: if object, could use infer_dtype to preempt costly
+            #  conversion if still non-comparable?
+            dtype = self._find_common_type_compat(target)
+
+            this = self.astype(dtype, copy=False)
+            that = target.astype(dtype, copy=False)
+            return this.get_indexer_non_unique(that)
+
+        # TODO: get_indexer has fastpaths for both Categorical-self and
+        #  Categorical-target. Can we do something similar here?
+
+        # Note: _maybe_downcast_for_indexing ensures we never get here
+        #  with MultiIndex self and non-Multi target
+        if self._is_multi and target._is_multi:
+            engine = self._engine
+            # Item "IndexEngine" of "Union[IndexEngine, ExtensionEngine]" has
+            # no attribute "_extract_level_codes"
+            tgt_values = engine._extract_level_codes(target)  # type: ignore[union-attr]
+        else:
+            tgt_values = target._get_engine_target()
+
+        indexer, missing = self._engine.get_indexer_non_unique(tgt_values)
+        return ensure_platform_int(indexer), ensure_platform_int(missing)
+
+    @final
+    def get_indexer_for(self, target) -> npt.NDArray[np.intp]:
+        """
+        Guaranteed return of an indexer even when non-unique.
+
+        This dispatches to get_indexer or get_indexer_non_unique
+        as appropriate.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+            List of indices.
+
+        Examples
+        --------
+        >>> idx = pd.Index([np.nan, 'var1', np.nan])
+        >>> idx.get_indexer_for([np.nan])
+        array([0, 2])
+        """
+        if self._index_as_unique:
+            return self.get_indexer(target)
+        indexer, _ = self.get_indexer_non_unique(target)
+        return indexer
+
+    def _get_indexer_strict(self, key, axis_name: str_t) -> tuple[Index, np.ndarray]:
+        """
+        Analogue to get_indexer that raises if any elements are missing.
+        """
+        keyarr = key
+        if not isinstance(keyarr, Index):
+            keyarr = com.asarray_tuplesafe(keyarr)
+
+        if self._index_as_unique:
+            indexer = self.get_indexer_for(keyarr)
+            keyarr = self.reindex(keyarr)[0]
+        else:
+            keyarr, indexer, new_indexer = self._reindex_non_unique(keyarr)
+
+        self._raise_if_missing(keyarr, indexer, axis_name)
+
+        keyarr = self.take(indexer)
+        if isinstance(key, Index):
+            # GH 42790 - Preserve name from an Index
+            keyarr.name = key.name
+        if lib.is_np_dtype(keyarr.dtype, "mM") or isinstance(
+            keyarr.dtype, DatetimeTZDtype
+        ):
+            # DTI/TDI.take can infer a freq in some cases when we dont want one
+            if isinstance(key, list) or (
+                isinstance(key, type(self))
+                # "Index" has no attribute "freq"
+                and key.freq is None  # type: ignore[attr-defined]
+            ):
+                keyarr = keyarr._with_freq(None)
+
+        return keyarr, indexer
+
+    def _raise_if_missing(self, key, indexer, axis_name: str_t) -> None:
+        """
+        Check that indexer can be used to return a result.
+
+        e.g. at least one element was found,
+        unless the list of keys was actually empty.
+
+        Parameters
+        ----------
+        key : list-like
+            Targeted labels (only used to show correct error message).
+        indexer: array-like of booleans
+            Indices corresponding to the key,
+            (with -1 indicating not found).
+        axis_name : str
+
+        Raises
+        ------
+        KeyError
+            If at least one key was requested but none was found.
+        """
+        if len(key) == 0:
+            return
+
+        # Count missing values
+        missing_mask = indexer < 0
+        nmissing = missing_mask.sum()
+
+        if nmissing:
+            if nmissing == len(indexer):
+                raise KeyError(f"None of [{key}] are in the [{axis_name}]")
+
+            not_found = list(ensure_index(key)[missing_mask.nonzero()[0]].unique())
+            raise KeyError(f"{not_found} not in index")
+
+    @overload
+    def _get_indexer_non_comparable(
+        self, target: Index, method, unique: Literal[True] = ...
+    ) -> npt.NDArray[np.intp]:
+        ...
+
+    @overload
+    def _get_indexer_non_comparable(
+        self, target: Index, method, unique: Literal[False]
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        ...
+
+    @overload
+    def _get_indexer_non_comparable(
+        self, target: Index, method, unique: bool = True
+    ) -> npt.NDArray[np.intp] | tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        ...
+
+    @final
+    def _get_indexer_non_comparable(
+        self, target: Index, method, unique: bool = True
+    ) -> npt.NDArray[np.intp] | tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        """
+        Called from get_indexer or get_indexer_non_unique when the target
+        is of a non-comparable dtype.
+
+        For get_indexer lookups with method=None, get_indexer is an _equality_
+        check, so non-comparable dtypes mean we will always have no matches.
+
+        For get_indexer lookups with a method, get_indexer is an _inequality_
+        check, so non-comparable dtypes mean we will always raise TypeError.
+
+        Parameters
+        ----------
+        target : Index
+        method : str or None
+        unique : bool, default True
+            * True if called from get_indexer.
+            * False if called from get_indexer_non_unique.
+
+        Raises
+        ------
+        TypeError
+            If doing an inequality check, i.e. method is not None.
+        """
+        if method is not None:
+            other_dtype = _unpack_nested_dtype(target)
+            raise TypeError(f"Cannot compare dtypes {self.dtype} and {other_dtype}")
+
+        no_matches = -1 * np.ones(target.shape, dtype=np.intp)
+        if unique:
+            # This is for get_indexer
+            return no_matches
+        else:
+            # This is for get_indexer_non_unique
+            missing = np.arange(len(target), dtype=np.intp)
+            return no_matches, missing
+
+    @property
+    def _index_as_unique(self) -> bool:
+        """
+        Whether we should treat this as unique for the sake of
+        get_indexer vs get_indexer_non_unique.
+
+        For IntervalIndex compat.
+        """
+        return self.is_unique
+
+    _requires_unique_msg = "Reindexing only valid with uniquely valued Index objects"
+
+    @final
+    def _maybe_downcast_for_indexing(self, other: Index) -> tuple[Index, Index]:
+        """
+        When dealing with an object-dtype Index and a non-object Index, see
+        if we can upcast the object-dtype one to improve performance.
+        """
+
+        if isinstance(self, ABCDatetimeIndex) and isinstance(other, ABCDatetimeIndex):
+            if (
+                self.tz is not None
+                and other.tz is not None
+                and not tz_compare(self.tz, other.tz)
+            ):
+                # standardize on UTC
+                return self.tz_convert("UTC"), other.tz_convert("UTC")
+
+        elif self.inferred_type == "date" and isinstance(other, ABCDatetimeIndex):
+            try:
+                return type(other)(self), other
+            except OutOfBoundsDatetime:
+                return self, other
+        elif self.inferred_type == "timedelta" and isinstance(other, ABCTimedeltaIndex):
+            # TODO: we dont have tests that get here
+            return type(other)(self), other
+
+        elif self.dtype.kind == "u" and other.dtype.kind == "i":
+            # GH#41873
+            if other.min() >= 0:
+                # lookup min as it may be cached
+                # TODO: may need itemsize check if we have non-64-bit Indexes
+                return self, other.astype(self.dtype)
+
+        elif self._is_multi and not other._is_multi:
+            try:
+                # "Type[Index]" has no attribute "from_tuples"
+                other = type(self).from_tuples(other)  # type: ignore[attr-defined]
+            except (TypeError, ValueError):
+                # let's instead try with a straight Index
+                self = Index(self._values)
+
+        if not is_object_dtype(self.dtype) and is_object_dtype(other.dtype):
+            # Reverse op so we dont need to re-implement on the subclasses
+            other, self = other._maybe_downcast_for_indexing(self)
+
+        return self, other
+
+    @final
+    def _find_common_type_compat(self, target) -> DtypeObj:
+        """
+        Implementation of find_common_type that adjusts for Index-specific
+        special cases.
+        """
+        target_dtype, _ = infer_dtype_from(target)
+
+        if using_string_dtype():
+            # special case: if left or right is a zero-length RangeIndex or
+            # Index[object], those can be created by the default empty constructors
+            # -> for that case ignore this dtype and always return the other
+            # (https://github.com/pandas-dev/pandas/pull/60797)
+            from pandas.core.indexes.range import RangeIndex
+
+            if len(self) == 0 and (
+                isinstance(self, RangeIndex) or self.dtype == np.object_
+            ):
+                if target_dtype.kind == "M":
+                    if hasattr(target_dtype, "tz"):
+                        target_dtype_ns = DatetimeTZDtype("ns", tz=target_dtype.tz)
+                    else:
+                        target_dtype_ns = np.dtype("datetime64[ns]")  # type: ignore[assignment]
+                    try:
+                        Index(target, dtype=target_dtype_ns, copy=False)
+                    except OutOfBoundsDatetime:
+                        return np.dtype(object)
+                    except Exception:
+                        pass
+                    return target_dtype_ns
+                return target_dtype
+            if (
+                isinstance(target, Index)
+                and len(target) == 0
+                and (isinstance(target, RangeIndex) or target_dtype == np.object_)
+            ):
+                return self.dtype
+
+        # special case: if one dtype is uint64 and the other a signed int, return object
+        # See https://github.com/pandas-dev/pandas/issues/26778 for discussion
+        # Now it's:
+        # * float | [u]int -> float
+        # * uint64 | signed int  -> object
+        # We may change union(float | [u]int) to go to object.
+        if self.dtype == "uint64" or target_dtype == "uint64":
+            if is_signed_integer_dtype(self.dtype) or is_signed_integer_dtype(
+                target_dtype
+            ):
+                return _dtype_obj
+
+        dtype = find_result_type(self.dtype, target)
+        dtype = common_dtype_categorical_compat([self, target], dtype)
+        return dtype
+
+    @final
+    def _should_compare(self, other: Index) -> bool:
+        """
+        Check if `self == other` can ever have non-False entries.
+        """
+
+        # NB: we use inferred_type rather than is_bool_dtype to catch
+        #  object_dtype_of_bool and categorical[object_dtype_of_bool] cases
+        if (
+            other.inferred_type == "boolean" and is_any_real_numeric_dtype(self.dtype)
+        ) or (
+            self.inferred_type == "boolean" and is_any_real_numeric_dtype(other.dtype)
+        ):
+            # GH#16877 Treat boolean labels passed to a numeric index as not
+            #  found. Without this fix False and True would be treated as 0 and 1
+            #  respectively.
+            return False
+
+        dtype = _unpack_nested_dtype(other)
+        return (
+            self._is_comparable_dtype(dtype)
+            or is_object_dtype(dtype)
+            or is_string_dtype(dtype)
+        )
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        """
+        Can we compare values of the given dtype to our own?
+        """
+        if self.dtype.kind == "b":
+            return dtype.kind == "b"
+        elif is_numeric_dtype(self.dtype):
+            return is_numeric_dtype(dtype)
+        # TODO: this was written assuming we only get here with object-dtype,
+        #  which is no longer correct. Can we specialize for EA?
+        return True
+
+    @final
+    def groupby(self, values) -> PrettyDict[Hashable, np.ndarray]:
+        """
+        Group the index labels by a given array of values.
+
+        Parameters
+        ----------
+        values : array
+            Values used to determine the groups.
+
+        Returns
+        -------
+        dict
+            {group name -> group labels}
+        """
+        # TODO: if we are a MultiIndex, we can do better
+        # that converting to tuples
+        if isinstance(values, ABCMultiIndex):
+            values = values._values
+        values = Categorical(values)
+        result = values._reverse_indexer()
+
+        # map to the label
+        result = {k: self.take(v) for k, v in result.items()}
+
+        return PrettyDict(result)
+
+    def map(self, mapper, na_action: Literal["ignore"] | None = None):
+        """
+        Map values using an input mapping or function.
+
+        Parameters
+        ----------
+        mapper : function, dict, or Series
+            Mapping correspondence.
+        na_action : {None, 'ignore'}
+            If 'ignore', propagate NA values, without passing them to the
+            mapping correspondence.
+
+        Returns
+        -------
+        Union[Index, MultiIndex]
+            The output of the mapping function applied to the index.
+            If the function returns a tuple with more than one element
+            a MultiIndex will be returned.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx.map({1: 'a', 2: 'b', 3: 'c'})
+        Index(['a', 'b', 'c'], dtype='object')
+
+        Using `map` with a function:
+
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx.map('I am a {}'.format)
+        Index(['I am a 1', 'I am a 2', 'I am a 3'], dtype='object')
+
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.map(lambda x: x.upper())
+        Index(['A', 'B', 'C'], dtype='object')
+        """
+        from pandas.core.indexes.multi import MultiIndex
+
+        new_values = self._map_values(mapper, na_action=na_action)
+
+        # we can return a MultiIndex
+        if new_values.size and isinstance(new_values[0], tuple):
+            if isinstance(self, MultiIndex):
+                names = self.names
+            elif self.name:
+                names = [self.name] * len(new_values[0])
+            else:
+                names = None
+            return MultiIndex.from_tuples(new_values, names=names)
+
+        dtype = None
+        if not new_values.size:
+            # empty
+            dtype = self.dtype
+
+        # e.g. if we are floating and new_values is all ints, then we
+        #  don't want to cast back to floating.  But if we are UInt64
+        #  and new_values is all ints, we want to try.
+        same_dtype = lib.infer_dtype(new_values, skipna=False) == self.inferred_type
+        if same_dtype:
+            new_values = maybe_cast_pointwise_result(
+                new_values, self.dtype, same_dtype=same_dtype
+            )
+
+        return Index._with_infer(new_values, dtype=dtype, copy=False, name=self.name)
+
+    # TODO: De-duplicate with map, xref GH#32349
+    @final
+    def _transform_index(self, func, *, level=None) -> Index:
+        """
+        Apply function to all values found in index.
+
+        This includes transforming multiindex entries separately.
+        Only apply function to one level of the MultiIndex if level is specified.
+        """
+        if isinstance(self, ABCMultiIndex):
+            values = [
+                self.get_level_values(i).map(func)
+                if i == level or level is None
+                else self.get_level_values(i)
+                for i in range(self.nlevels)
+            ]
+            return type(self).from_arrays(values)
+        else:
+            items = [func(x) for x in self]
+            return Index(items, name=self.name, tupleize_cols=False)
+
+    def isin(self, values, level=None) -> npt.NDArray[np.bool_]:
+        """
+        Return a boolean array where the index values are in `values`.
+
+        Compute boolean array of whether each index value is found in the
+        passed set of values. The length of the returned boolean array matches
+        the length of the index.
+
+        Parameters
+        ----------
+        values : set or list-like
+            Sought values.
+        level : str or int, optional
+            Name or position of the index level to use (if the index is a
+            `MultiIndex`).
+
+        Returns
+        -------
+        np.ndarray[bool]
+            NumPy array of boolean values.
+
+        See Also
+        --------
+        Series.isin : Same for Series.
+        DataFrame.isin : Same method for DataFrames.
+
+        Notes
+        -----
+        In the case of `MultiIndex` you must either specify `values` as a
+        list-like object containing tuples that are the same length as the
+        number of levels, or specify `level`. Otherwise it will raise a
+        ``ValueError``.
+
+        If `level` is specified:
+
+        - if it is the name of one *and only one* index level, use that level;
+        - otherwise it should be a number indicating level position.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1,2,3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+
+        Check whether each index value in a list of values.
+
+        >>> idx.isin([1, 4])
+        array([ True, False, False])
+
+        >>> midx = pd.MultiIndex.from_arrays([[1,2,3],
+        ...                                  ['red', 'blue', 'green']],
+        ...                                  names=('number', 'color'))
+        >>> midx
+        MultiIndex([(1,   'red'),
+                    (2,  'blue'),
+                    (3, 'green')],
+                   names=['number', 'color'])
+
+        Check whether the strings in the 'color' level of the MultiIndex
+        are in a list of colors.
+
+        >>> midx.isin(['red', 'orange', 'yellow'], level='color')
+        array([ True, False, False])
+
+        To check across the levels of a MultiIndex, pass a list of tuples:
+
+        >>> midx.isin([(1, 'red'), (3, 'red')])
+        array([ True, False, False])
+        """
+        if level is not None:
+            self._validate_index_level(level)
+        return algos.isin(self._values, values)
+
+    def _get_string_slice(self, key: str_t):
+        # this is for partial string indexing,
+        # overridden in DatetimeIndex, TimedeltaIndex and PeriodIndex
+        raise NotImplementedError
+
+    def slice_indexer(
+        self,
+        start: Hashable | None = None,
+        end: Hashable | None = None,
+        step: int | None = None,
+    ) -> slice:
+        """
+        Compute the slice indexer for input labels and step.
+
+        Index needs to be ordered and unique.
+
+        Parameters
+        ----------
+        start : label, default None
+            If None, defaults to the beginning.
+        end : label, default None
+            If None, defaults to the end.
+        step : int, default None
+
+        Returns
+        -------
+        slice
+
+        Raises
+        ------
+        KeyError : If key does not exist, or key is not unique and index is
+            not ordered.
+
+        Notes
+        -----
+        This function assumes that the data is sorted, so use at your own peril
+
+        Examples
+        --------
+        This is a method on all index types. For example you can do:
+
+        >>> idx = pd.Index(list('abcd'))
+        >>> idx.slice_indexer(start='b', end='c')
+        slice(1, 3, None)
+
+        >>> idx = pd.MultiIndex.from_arrays([list('abcd'), list('efgh')])
+        >>> idx.slice_indexer(start='b', end=('c', 'g'))
+        slice(1, 3, None)
+        """
+        start_slice, end_slice = self.slice_locs(start, end, step=step)
+
+        # return a slice
+        if not is_scalar(start_slice):
+            raise AssertionError("Start slice bound is non-scalar")
+        if not is_scalar(end_slice):
+            raise AssertionError("End slice bound is non-scalar")
+
+        return slice(start_slice, end_slice, step)
+
+    def _maybe_cast_indexer(self, key):
+        """
+        If we have a float key and are not a floating index, then try to cast
+        to an int if equivalent.
+        """
+        return key
+
+    def _maybe_cast_listlike_indexer(self, target) -> Index:
+        """
+        Analogue to maybe_cast_indexer for get_indexer instead of get_loc.
+        """
+        target_index = ensure_index(target)
+        if (
+            not hasattr(target, "dtype")
+            and self.dtype == object
+            and target_index.dtype == "string"
+        ):
+            # If we started with a list-like, avoid inference to string dtype if self
+            # is object dtype (coercing to string dtype will alter the missing values)
+            target_index = Index(target, dtype=self.dtype)
+        return target_index
+
+    @final
+    def _validate_indexer(
+        self,
+        form: Literal["positional", "slice"],
+        key,
+        kind: Literal["getitem", "iloc"],
+    ) -> None:
+        """
+        If we are positional indexer, validate that we have appropriate
+        typed bounds must be an integer.
+        """
+        if not lib.is_int_or_none(key):
+            self._raise_invalid_indexer(form, key)
+
+    def _maybe_cast_slice_bound(self, label, side: str_t):
+        """
+        This function should be overloaded in subclasses that allow non-trivial
+        casting on label-slice bounds, e.g. datetime-like indices allowing
+        strings containing formatted datetimes.
+
+        Parameters
+        ----------
+        label : object
+        side : {'left', 'right'}
+
+        Returns
+        -------
+        label : object
+
+        Notes
+        -----
+        Value of `side` parameter should be validated in caller.
+        """
+
+        # We are a plain index here (sub-class override this method if they
+        # wish to have special treatment for floats/ints, e.g. datetimelike Indexes
+
+        if is_numeric_dtype(self.dtype):
+            return self._maybe_cast_indexer(label)
+
+        # reject them, if index does not contain label
+        if (is_float(label) or is_integer(label)) and label not in self:
+            self._raise_invalid_indexer("slice", label)
+
+        return label
+
+    def _searchsorted_monotonic(self, label, side: Literal["left", "right"] = "left"):
+        if self.is_monotonic_increasing:
+            return self.searchsorted(label, side=side)
+        elif self.is_monotonic_decreasing:
+            # np.searchsorted expects ascending sort order, have to reverse
+            # everything for it to work (element ordering, search side and
+            # resulting value).
+            pos = self[::-1].searchsorted(
+                label, side="right" if side == "left" else "left"
+            )
+            return len(self) - pos
+
+        raise ValueError("index must be monotonic increasing or decreasing")
+
+    def get_slice_bound(self, label, side: Literal["left", "right"]) -> int:
+        """
+        Calculate slice bound that corresponds to given label.
+
+        Returns leftmost (one-past-the-rightmost if ``side=='right'``) position
+        of given label.
+
+        Parameters
+        ----------
+        label : object
+        side : {'left', 'right'}
+
+        Returns
+        -------
+        int
+            Index of label.
+
+        See Also
+        --------
+        Index.get_loc : Get integer location, slice or boolean mask for requested
+            label.
+
+        Examples
+        --------
+        >>> idx = pd.RangeIndex(5)
+        >>> idx.get_slice_bound(3, 'left')
+        3
+
+        >>> idx.get_slice_bound(3, 'right')
+        4
+
+        If ``label`` is non-unique in the index, an error will be raised.
+
+        >>> idx_duplicate = pd.Index(['a', 'b', 'a', 'c', 'd'])
+        >>> idx_duplicate.get_slice_bound('a', 'left')
+        Traceback (most recent call last):
+        KeyError: Cannot get left slice bound for non-unique label: 'a'
+        """
+
+        if side not in ("left", "right"):
+            raise ValueError(
+                "Invalid value for side kwarg, must be either "
+                f"'left' or 'right': {side}"
+            )
+
+        original_label = label
+
+        # For datetime indices label may be a string that has to be converted
+        # to datetime boundary according to its resolution.
+        label = self._maybe_cast_slice_bound(label, side)
+
+        # we need to look up the label
+        try:
+            slc = self.get_loc(label)
+        except KeyError as err:
+            try:
+                return self._searchsorted_monotonic(label, side)
+            except ValueError:
+                # raise the original KeyError
+                raise err
+
+        if isinstance(slc, np.ndarray):
+            # get_loc may return a boolean array, which
+            # is OK as long as they are representable by a slice.
+            assert is_bool_dtype(slc.dtype)
+            slc = lib.maybe_booleans_to_slice(slc.view("u1"))
+            if isinstance(slc, np.ndarray):
+                raise KeyError(
+                    f"Cannot get {side} slice bound for non-unique "
+                    f"label: {repr(original_label)}"
+                )
+
+        if isinstance(slc, slice):
+            if side == "left":
+                return slc.start
+            else:
+                return slc.stop
+        else:
+            if side == "right":
+                return slc + 1
+            else:
+                return slc
+
+    def slice_locs(self, start=None, end=None, step=None) -> tuple[int, int]:
+        """
+        Compute slice locations for input labels.
+
+        Parameters
+        ----------
+        start : label, default None
+            If None, defaults to the beginning.
+        end : label, default None
+            If None, defaults to the end.
+        step : int, defaults None
+            If None, defaults to 1.
+
+        Returns
+        -------
+        tuple[int, int]
+
+        See Also
+        --------
+        Index.get_loc : Get location for a single label.
+
+        Notes
+        -----
+        This method only works if the index is monotonic or unique.
+
+        Examples
+        --------
+        >>> idx = pd.Index(list('abcd'))
+        >>> idx.slice_locs(start='b', end='c')
+        (1, 3)
+        """
+        inc = step is None or step >= 0
+
+        if not inc:
+            # If it's a reverse slice, temporarily swap bounds.
+            start, end = end, start
+
+        # GH 16785: If start and end happen to be date strings with UTC offsets
+        # attempt to parse and check that the offsets are the same
+        if isinstance(start, (str, datetime)) and isinstance(end, (str, datetime)):
+            try:
+                ts_start = Timestamp(start)
+                ts_end = Timestamp(end)
+            except (ValueError, TypeError):
+                pass
+            else:
+                if not tz_compare(ts_start.tzinfo, ts_end.tzinfo):
+                    raise ValueError("Both dates must have the same UTC offset")
+
+        start_slice = None
+        if start is not None:
+            start_slice = self.get_slice_bound(start, "left")
+        if start_slice is None:
+            start_slice = 0
+
+        end_slice = None
+        if end is not None:
+            end_slice = self.get_slice_bound(end, "right")
+        if end_slice is None:
+            end_slice = len(self)
+
+        if not inc:
+            # Bounds at this moment are swapped, swap them back and shift by 1.
+            #
+            # slice_locs('B', 'A', step=-1): s='B', e='A'
+            #
+            #              s='A'                 e='B'
+            # AFTER SWAP:    |                     |
+            #                v ------------------> V
+            #           -----------------------------------
+            #           | | |A|A|A|A| | | | | |B|B| | | | |
+            #           -----------------------------------
+            #              ^ <------------------ ^
+            # SHOULD BE:   |                     |
+            #           end=s-1              start=e-1
+            #
+            end_slice, start_slice = start_slice - 1, end_slice - 1
+
+            # i == -1 triggers ``len(self) + i`` selection that points to the
+            # last element, not before-the-first one, subtracting len(self)
+            # compensates that.
+            if end_slice == -1:
+                end_slice -= len(self)
+            if start_slice == -1:
+                start_slice -= len(self)
+
+        return start_slice, end_slice
+
+    def delete(self, loc) -> Self:
+        """
+        Make new Index with passed location(-s) deleted.
+
+        Parameters
+        ----------
+        loc : int or list of int
+            Location of item(-s) which will be deleted.
+            Use a list of locations to delete more than one value at the same time.
+
+        Returns
+        -------
+        Index
+            Will be same type as self, except for RangeIndex.
+
+        See Also
+        --------
+        numpy.delete : Delete any rows and column from NumPy array (ndarray).
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.delete(1)
+        Index(['a', 'c'], dtype='object')
+
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.delete([0, 2])
+        Index(['b'], dtype='object')
+        """
+        values = self._values
+        res_values: ArrayLike
+        if isinstance(values, np.ndarray):
+            # TODO(__array_function__): special casing will be unnecessary
+            res_values = np.delete(values, loc)
+        else:
+            res_values = values.delete(loc)
+
+        # _constructor so RangeIndex-> Index with an int64 dtype
+        return self._constructor._simple_new(res_values, name=self.name)
+
+    def insert(self, loc: int, item) -> Index:
+        """
+        Make new Index inserting new item at location.
+
+        Follows Python numpy.insert semantics for negative values.
+
+        Parameters
+        ----------
+        loc : int
+        item : object
+
+        Returns
+        -------
+        Index
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.insert(1, 'x')
+        Index(['a', 'x', 'b', 'c'], dtype='object')
+        """
+        item = lib.item_from_zerodim(item)
+        if is_valid_na_for_dtype(item, self.dtype) and self.dtype != object:
+            item = self._na_value
+
+        arr = self._values
+
+        if using_string_dtype() and len(self) == 0 and self.dtype == np.object_:
+            # special case: if we are an empty object-dtype Index, also
+            # take into account the inserted item for the resulting dtype
+            # (https://github.com/pandas-dev/pandas/pull/60797)
+            dtype = self._find_common_type_compat(item)
+            if dtype != self.dtype:
+                return self.astype(dtype).insert(loc, item)
+
+        try:
+            if isinstance(arr, ExtensionArray):
+                res_values = arr.insert(loc, item)
+                return type(self)._simple_new(res_values, name=self.name)
+            else:
+                item = self._validate_fill_value(item)
+        except (TypeError, ValueError, LossySetitemError):
+            # e.g. trying to insert an integer into a DatetimeIndex
+            #  We cannot keep the same dtype, so cast to the (often object)
+            #  minimal shared dtype before doing the insert.
+            dtype = self._find_common_type_compat(item)
+            if dtype == self.dtype:
+                # EA's might run into recursion errors if loc is invalid
+                raise
+            return self.astype(dtype).insert(loc, item)
+
+        if arr.dtype != object or not isinstance(
+            item, (tuple, np.datetime64, np.timedelta64)
+        ):
+            # with object-dtype we need to worry about numpy incorrectly casting
+            # dt64/td64 to integer, also about treating tuples as sequences
+            # special-casing dt64/td64 https://github.com/numpy/numpy/issues/12550
+            casted = arr.dtype.type(item)
+            new_values = np.insert(arr, loc, casted)
+
+        else:
+            # error: No overload variant of "insert" matches argument types
+            # "ndarray[Any, Any]", "int", "None"
+            new_values = np.insert(arr, loc, None)  # type: ignore[call-overload]
+            loc = loc if loc >= 0 else loc - 1
+            new_values[loc] = item
+
+        out = Index._with_infer(new_values, name=self.name)
+        if (
+            using_string_dtype()
+            and is_string_dtype(out.dtype)
+            and new_values.dtype == object
+        ):
+            out = out.astype(new_values.dtype)
+        if self.dtype == object and out.dtype != object:
+            # GH#51363
+            warnings.warn(
+                "The behavior of Index.insert with object-dtype is deprecated, "
+                "in a future version this will return an object-dtype Index "
+                "instead of inferring a non-object dtype. To retain the old "
+                "behavior, do `idx.insert(loc, item).infer_objects(copy=False)`",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return out
+
+    def drop(
+        self,
+        labels: Index | np.ndarray | Iterable[Hashable],
+        errors: IgnoreRaise = "raise",
+    ) -> Index:
+        """
+        Make new Index with passed list of labels deleted.
+
+        Parameters
+        ----------
+        labels : array-like or scalar
+        errors : {'ignore', 'raise'}, default 'raise'
+            If 'ignore', suppress error and existing labels are dropped.
+
+        Returns
+        -------
+        Index
+            Will be same type as self, except for RangeIndex.
+
+        Raises
+        ------
+        KeyError
+            If not all of the labels are found in the selected axis
+
+        Examples
+        --------
+        >>> idx = pd.Index(['a', 'b', 'c'])
+        >>> idx.drop(['a'])
+        Index(['b', 'c'], dtype='object')
+        """
+        if not isinstance(labels, Index):
+            # avoid materializing e.g. RangeIndex
+            arr_dtype = "object" if self.dtype == "object" else None
+            labels = com.index_labels_to_array(labels, dtype=arr_dtype)
+
+        indexer = self.get_indexer_for(labels)
+        mask = indexer == -1
+        if mask.any():
+            if errors != "ignore":
+                raise KeyError(f"{labels[mask].tolist()} not found in axis")
+            indexer = indexer[~mask]
+        return self.delete(indexer)
+
+    @final
+    def infer_objects(self, copy: bool = True) -> Index:
+        """
+        If we have an object dtype, try to infer a non-object dtype.
+
+        Parameters
+        ----------
+        copy : bool, default True
+            Whether to make a copy in cases where no inference occurs.
+        """
+        if self._is_multi:
+            raise NotImplementedError(
+                "infer_objects is not implemented for MultiIndex. "
+                "Use index.to_frame().infer_objects() instead."
+            )
+        if self.dtype != object:
+            return self.copy() if copy else self
+
+        values = self._values
+        values = cast("npt.NDArray[np.object_]", values)
+        res_values = lib.maybe_convert_objects(
+            values,
+            convert_non_numeric=True,
+        )
+        if copy and res_values is values:
+            return self.copy()
+        result = Index(res_values, name=self.name)
+        if not copy and res_values is values and self._references is not None:
+            result._references = self._references
+            result._references.add_index_reference(result)
+        return result
+
+    @final
+    def diff(self, periods: int = 1) -> Index:
+        """
+        Computes the difference between consecutive values in the Index object.
+
+        If periods is greater than 1, computes the difference between values that
+        are `periods` number of positions apart.
+
+        Parameters
+        ----------
+        periods : int, optional
+            The number of positions between the current and previous
+            value to compute the difference with. Default is 1.
+
+        Returns
+        -------
+        Index
+            A new Index object with the computed differences.
+
+        Examples
+        --------
+        >>> import pandas as pd
+        >>> idx = pd.Index([10, 20, 30, 40, 50])
+        >>> idx.diff()
+        Index([nan, 10.0, 10.0, 10.0, 10.0], dtype='float64')
+
+        """
+        return Index(self.to_series().diff(periods))
+
+    @final
+    def round(self, decimals: int = 0) -> Self:
+        """
+        Round each value in the Index to the given number of decimals.
+
+        Parameters
+        ----------
+        decimals : int, optional
+            Number of decimal places to round to. If decimals is negative,
+            it specifies the number of positions to the left of the decimal point.
+
+        Returns
+        -------
+        Index
+            A new Index with the rounded values.
+
+        Examples
+        --------
+        >>> import pandas as pd
+        >>> idx = pd.Index([10.1234, 20.5678, 30.9123, 40.4567, 50.7890])
+        >>> idx.round(decimals=2)
+        Index([10.12, 20.57, 30.91, 40.46, 50.79], dtype='float64')
+
+        """
+        return self._constructor(self.to_series().round(decimals))
+
+    # --------------------------------------------------------------------
+    # Generated Arithmetic, Comparison, and Unary Methods
+
+    def _cmp_method(self, other, op):
+        """
+        Wrapper used to dispatch comparison operations.
+        """
+        if self.is_(other):
+            # fastpath
+            if op in {operator.eq, operator.le, operator.ge}:
+                arr = np.ones(len(self), dtype=bool)
+                if self._can_hold_na and not isinstance(self, ABCMultiIndex):
+                    # TODO: should set MultiIndex._can_hold_na = False?
+                    arr[self.isna()] = False
+                return arr
+            elif op is operator.ne:
+                arr = np.zeros(len(self), dtype=bool)
+                if self._can_hold_na and not isinstance(self, ABCMultiIndex):
+                    arr[self.isna()] = True
+                return arr
+
+        if isinstance(other, (np.ndarray, Index, ABCSeries, ExtensionArray)) and len(
+            self
+        ) != len(other):
+            raise ValueError("Lengths must match to compare")
+
+        if not isinstance(other, ABCMultiIndex):
+            other = extract_array(other, extract_numpy=True)
+        else:
+            other = np.asarray(other)
+
+        if is_object_dtype(self.dtype) and isinstance(other, ExtensionArray):
+            # e.g. PeriodArray, Categorical
+            result = op(self._values, other)
+
+        elif isinstance(self._values, ExtensionArray):
+            result = op(self._values, other)
+
+        elif is_object_dtype(self.dtype) and not isinstance(self, ABCMultiIndex):
+            # don't pass MultiIndex
+            result = ops.comp_method_OBJECT_ARRAY(op, self._values, other)
+
+        else:
+            result = ops.comparison_op(self._values, other, op)
+
+        return result
+
+    @final
+    def _logical_method(self, other, op):
+        res_name = ops.get_op_result_name(self, other)
+
+        lvalues = self._values
+        rvalues = extract_array(other, extract_numpy=True, extract_range=True)
+
+        res_values = ops.logical_op(lvalues, rvalues, op)
+        return self._construct_result(res_values, name=res_name)
+
+    @final
+    def _construct_result(self, result, name):
+        if isinstance(result, tuple):
+            return (
+                Index(result[0], name=name, dtype=result[0].dtype),
+                Index(result[1], name=name, dtype=result[1].dtype),
+            )
+        return Index(result, name=name, dtype=result.dtype)
+
+    def _arith_method(self, other, op):
+        if (
+            isinstance(other, Index)
+            and is_object_dtype(other.dtype)
+            and type(other) is not Index
+        ):
+            # We return NotImplemented for object-dtype index *subclasses* so they have
+            # a chance to implement ops before we unwrap them.
+            # See https://github.com/pandas-dev/pandas/issues/31109
+            return NotImplemented
+
+        return super()._arith_method(other, op)
+
+    @final
+    def _unary_method(self, op):
+        result = op(self._values)
+        return Index(result, name=self.name)
+
+    def __abs__(self) -> Index:
+        return self._unary_method(operator.abs)
+
+    def __neg__(self) -> Index:
+        return self._unary_method(operator.neg)
+
+    def __pos__(self) -> Index:
+        return self._unary_method(operator.pos)
+
+    def __invert__(self) -> Index:
+        # GH#8875
+        return self._unary_method(operator.inv)
+
+    # --------------------------------------------------------------------
+    # Reductions
+
+    def any(self, *args, **kwargs):
+        """
+        Return whether any element is Truthy.
+
+        Parameters
+        ----------
+        *args
+            Required for compatibility with numpy.
+        **kwargs
+            Required for compatibility with numpy.
+
+        Returns
+        -------
+        bool or array-like (if axis is specified)
+            A single element array-like may be converted to bool.
+
+        See Also
+        --------
+        Index.all : Return whether all elements are True.
+        Series.all : Return whether all elements are True.
+
+        Notes
+        -----
+        Not a Number (NaN), positive infinity and negative infinity
+        evaluate to True because these are not equal to zero.
+
+        Examples
+        --------
+        >>> index = pd.Index([0, 1, 2])
+        >>> index.any()
+        True
+
+        >>> index = pd.Index([0, 0, 0])
+        >>> index.any()
+        False
+        """
+        nv.validate_any(args, kwargs)
+        self._maybe_disable_logical_methods("any")
+        vals = self._values
+        if not isinstance(vals, np.ndarray):
+            # i.e. EA, call _reduce instead of "any" to get TypeError instead
+            #  of AttributeError
+            return vals._reduce("any")
+        return np.any(vals)
+
+    def all(self, *args, **kwargs):
+        """
+        Return whether all elements are Truthy.
+
+        Parameters
+        ----------
+        *args
+            Required for compatibility with numpy.
+        **kwargs
+            Required for compatibility with numpy.
+
+        Returns
+        -------
+        bool or array-like (if axis is specified)
+            A single element array-like may be converted to bool.
+
+        See Also
+        --------
+        Index.any : Return whether any element in an Index is True.
+        Series.any : Return whether any element in a Series is True.
+        Series.all : Return whether all elements in a Series are True.
+
+        Notes
+        -----
+        Not a Number (NaN), positive infinity and negative infinity
+        evaluate to True because these are not equal to zero.
+
+        Examples
+        --------
+        True, because nonzero integers are considered True.
+
+        >>> pd.Index([1, 2, 3]).all()
+        True
+
+        False, because ``0`` is considered False.
+
+        >>> pd.Index([0, 1, 2]).all()
+        False
+        """
+        nv.validate_all(args, kwargs)
+        self._maybe_disable_logical_methods("all")
+        vals = self._values
+        if not isinstance(vals, np.ndarray):
+            # i.e. EA, call _reduce instead of "all" to get TypeError instead
+            #  of AttributeError
+            return vals._reduce("all")
+        return np.all(vals)
+
+    @final
+    def _maybe_disable_logical_methods(self, opname: str_t) -> None:
+        """
+        raise if this Index subclass does not support any or all.
+        """
+        if (
+            isinstance(self, ABCMultiIndex)
+            # TODO(3.0): PeriodArray and DatetimeArray any/all will raise,
+            #  so checking needs_i8_conversion will be unnecessary
+            or (needs_i8_conversion(self.dtype) and self.dtype.kind != "m")
+        ):
+            # This call will raise
+            make_invalid_op(opname)(self)
+
+    @Appender(IndexOpsMixin.argmin.__doc__)
+    def argmin(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+        nv.validate_argmin(args, kwargs)
+        nv.validate_minmax_axis(axis)
+
+        if not self._is_multi and self.hasnans:
+            # Take advantage of cache
+            mask = self._isnan
+            if not skipna or mask.all():
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return -1
+        return super().argmin(skipna=skipna)
+
+    @Appender(IndexOpsMixin.argmax.__doc__)
+    def argmax(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+        nv.validate_argmax(args, kwargs)
+        nv.validate_minmax_axis(axis)
+
+        if not self._is_multi and self.hasnans:
+            # Take advantage of cache
+            mask = self._isnan
+            if not skipna or mask.all():
+                warnings.warn(
+                    f"The behavior of {type(self).__name__}.argmax/argmin "
+                    "with skipna=False and NAs, or with all-NAs is deprecated. "
+                    "In a future version this will raise ValueError.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return -1
+        return super().argmax(skipna=skipna)
+
+    def min(self, axis=None, skipna: bool = True, *args, **kwargs):
+        """
+        Return the minimum value of the Index.
+
+        Parameters
+        ----------
+        axis : {None}
+            Dummy argument for consistency with Series.
+        skipna : bool, default True
+            Exclude NA/null values when showing the result.
+        *args, **kwargs
+            Additional arguments and keywords for compatibility with NumPy.
+
+        Returns
+        -------
+        scalar
+            Minimum value.
+
+        See Also
+        --------
+        Index.max : Return the maximum value of the object.
+        Series.min : Return the minimum value in a Series.
+        DataFrame.min : Return the minimum values in a DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index([3, 2, 1])
+        >>> idx.min()
+        1
+
+        >>> idx = pd.Index(['c', 'b', 'a'])
+        >>> idx.min()
+        'a'
+
+        For a MultiIndex, the minimum is determined lexicographically.
+
+        >>> idx = pd.MultiIndex.from_product([('a', 'b'), (2, 1)])
+        >>> idx.min()
+        ('a', 1)
+        """
+        nv.validate_min(args, kwargs)
+        nv.validate_minmax_axis(axis)
+
+        if not len(self):
+            return self._na_value
+
+        if len(self) and self.is_monotonic_increasing:
+            # quick check
+            first = self[0]
+            if not isna(first):
+                return first
+
+        if not self._is_multi and self.hasnans:
+            # Take advantage of cache
+            mask = self._isnan
+            if not skipna or mask.all():
+                return self._na_value
+
+        if not self._is_multi and not isinstance(self._values, np.ndarray):
+            return self._values._reduce(name="min", skipna=skipna)
+
+        return nanops.nanmin(self._values, skipna=skipna)
+
+    def max(self, axis=None, skipna: bool = True, *args, **kwargs):
+        """
+        Return the maximum value of the Index.
+
+        Parameters
+        ----------
+        axis : int, optional
+            For compatibility with NumPy. Only 0 or None are allowed.
+        skipna : bool, default True
+            Exclude NA/null values when showing the result.
+        *args, **kwargs
+            Additional arguments and keywords for compatibility with NumPy.
+
+        Returns
+        -------
+        scalar
+            Maximum value.
+
+        See Also
+        --------
+        Index.min : Return the minimum value in an Index.
+        Series.max : Return the maximum value in a Series.
+        DataFrame.max : Return the maximum values in a DataFrame.
+
+        Examples
+        --------
+        >>> idx = pd.Index([3, 2, 1])
+        >>> idx.max()
+        3
+
+        >>> idx = pd.Index(['c', 'b', 'a'])
+        >>> idx.max()
+        'c'
+
+        For a MultiIndex, the maximum is determined lexicographically.
+
+        >>> idx = pd.MultiIndex.from_product([('a', 'b'), (2, 1)])
+        >>> idx.max()
+        ('b', 2)
+        """
+
+        nv.validate_max(args, kwargs)
+        nv.validate_minmax_axis(axis)
+
+        if not len(self):
+            return self._na_value
+
+        if len(self) and self.is_monotonic_increasing:
+            # quick check
+            last = self[-1]
+            if not isna(last):
+                return last
+
+        if not self._is_multi and self.hasnans:
+            # Take advantage of cache
+            mask = self._isnan
+            if not skipna or mask.all():
+                return self._na_value
+
+        if not self._is_multi and not isinstance(self._values, np.ndarray):
+            return self._values._reduce(name="max", skipna=skipna)
+
+        return nanops.nanmax(self._values, skipna=skipna)
+
+    # --------------------------------------------------------------------
+
+    @final
+    @property
+    def shape(self) -> Shape:
+        """
+        Return a tuple of the shape of the underlying data.
+
+        Examples
+        --------
+        >>> idx = pd.Index([1, 2, 3])
+        >>> idx
+        Index([1, 2, 3], dtype='int64')
+        >>> idx.shape
+        (3,)
+        """
+        # See GH#27775, GH#27384 for history/reasoning in how this is defined.
+        return (len(self),)
+
+
+def ensure_index_from_sequences(sequences, names=None) -> Index:
+    """
+    Construct an index from sequences of data.
+
+    A single sequence returns an Index. Many sequences returns a
+    MultiIndex.
+
+    Parameters
+    ----------
+    sequences : sequence of sequences
+    names : sequence of str
+
+    Returns
+    -------
+    index : Index or MultiIndex
+
+    Examples
+    --------
+    >>> ensure_index_from_sequences([[1, 2, 3]], names=["name"])
+    Index([1, 2, 3], dtype='int64', name='name')
+
+    >>> ensure_index_from_sequences([["a", "a"], ["a", "b"]], names=["L1", "L2"])
+    MultiIndex([('a', 'a'),
+                ('a', 'b')],
+               names=['L1', 'L2'])
+
+    See Also
+    --------
+    ensure_index
+    """
+    from pandas.core.indexes.multi import MultiIndex
+
+    if len(sequences) == 1:
+        if names is not None:
+            names = names[0]
+        return Index(sequences[0], name=names)
+    else:
+        return MultiIndex.from_arrays(sequences, names=names)
+
+
+def ensure_index(index_like: Axes, copy: bool = False) -> Index:
+    """
+    Ensure that we have an index from some index-like object.
+
+    Parameters
+    ----------
+    index_like : sequence
+        An Index or other sequence
+    copy : bool, default False
+
+    Returns
+    -------
+    index : Index or MultiIndex
+
+    See Also
+    --------
+    ensure_index_from_sequences
+
+    Examples
+    --------
+    >>> ensure_index(['a', 'b'])
+    Index(['a', 'b'], dtype='object')
+
+    >>> ensure_index([('a', 'a'),  ('b', 'c')])
+    Index([('a', 'a'), ('b', 'c')], dtype='object')
+
+    >>> ensure_index([['a', 'a'], ['b', 'c']])
+    MultiIndex([('a', 'b'),
+            ('a', 'c')],
+           )
+    """
+    if isinstance(index_like, Index):
+        if copy:
+            index_like = index_like.copy()
+        return index_like
+
+    if isinstance(index_like, ABCSeries):
+        name = index_like.name
+        return Index(index_like, name=name, copy=copy)
+
+    if is_iterator(index_like):
+        index_like = list(index_like)
+
+    if isinstance(index_like, list):
+        if type(index_like) is not list:  # noqa: E721
+            # must check for exactly list here because of strict type
+            # check in clean_index_list
+            index_like = list(index_like)
+
+        if len(index_like) and lib.is_all_arraylike(index_like):
+            from pandas.core.indexes.multi import MultiIndex
+
+            return MultiIndex.from_arrays(index_like)
+        else:
+            return Index(index_like, copy=copy, tupleize_cols=False)
+    else:
+        return Index(index_like, copy=copy)
+
+
+def ensure_has_len(seq):
+    """
+    If seq is an iterator, put its values into a list.
+    """
+    try:
+        len(seq)
+    except TypeError:
+        return list(seq)
+    else:
+        return seq
+
+
+def trim_front(strings: list[str]) -> list[str]:
+    """
+    Trims zeros and decimal points.
+
+    Examples
+    --------
+    >>> trim_front([" a", " b"])
+    ['a', 'b']
+
+    >>> trim_front([" a", " "])
+    ['a', '']
+    """
+    if not strings:
+        return strings
+    while all(strings) and all(x[0] == " " for x in strings):
+        strings = [x[1:] for x in strings]
+    return strings
+
+
+def _validate_join_method(method: str) -> None:
+    if method not in ["left", "right", "inner", "outer"]:
+        raise ValueError(f"do not recognize join method {method}")
+
+
+def maybe_extract_name(name, obj, cls) -> Hashable:
+    """
+    If no name is passed, then extract it from data, validating hashability.
+    """
+    if name is None and isinstance(obj, (Index, ABCSeries)):
+        # Note we don't just check for "name" attribute since that would
+        #  pick up e.g. dtype.name
+        name = obj.name
+
+    # GH#29069
+    if not is_hashable(name):
+        raise TypeError(f"{cls.__name__}.name must be a hashable type")
+
+    return name
+
+
+def get_unanimous_names(*indexes: Index) -> tuple[Hashable, ...]:
+    """
+    Return common name if all indices agree, otherwise None (level-by-level).
+
+    Parameters
+    ----------
+    indexes : list of Index objects
+
+    Returns
+    -------
+    list
+        A list representing the unanimous 'names' found.
+    """
+    name_tups = [tuple(i.names) for i in indexes]
+    name_sets = [{*ns} for ns in zip_longest(*name_tups)]
+    names = tuple(ns.pop() if len(ns) == 1 else None for ns in name_sets)
+    return names
+
+
+def _unpack_nested_dtype(other: Index) -> DtypeObj:
+    """
+    When checking if our dtype is comparable with another, we need
+    to unpack CategoricalDtype to look at its categories.dtype.
+
+    Parameters
+    ----------
+    other : Index
+
+    Returns
+    -------
+    np.dtype or ExtensionDtype
+    """
+    dtype = other.dtype
+    if isinstance(dtype, CategoricalDtype):
+        # If there is ever a SparseIndex, this could get dispatched
+        #  here too.
+        return dtype.categories.dtype
+    elif isinstance(dtype, ArrowDtype):
+        # GH 53617
+        import pyarrow as pa
+
+        if pa.types.is_dictionary(dtype.pyarrow_dtype):
+            other = other[:0].astype(ArrowDtype(dtype.pyarrow_dtype.value_type))
+    return other.dtype
+
+
+def _maybe_try_sort(result: Index | ArrayLike, sort: bool | None):
+    if sort is not False:
+        try:
+            # error: Incompatible types in assignment (expression has type
+            # "Union[ExtensionArray, ndarray[Any, Any], Index, Series,
+            # Tuple[Union[Union[ExtensionArray, ndarray[Any, Any]], Index, Series],
+            # ndarray[Any, Any]]]", variable has type "Union[Index,
+            # Union[ExtensionArray, ndarray[Any, Any]]]")
+            result = algos.safe_sort(result)  # type: ignore[assignment]
+        except TypeError as err:
+            if sort is True:
+                raise
+            warnings.warn(
+                f"{err}, sort order is undefined for incomparable objects.",
+                RuntimeWarning,
+                stacklevel=find_stack_level(),
+            )
+    return result
+
+
+def get_values_for_csv(
+    values: ArrayLike,
+    *,
+    date_format,
+    na_rep: str = "nan",
+    quoting=None,
+    float_format=None,
+    decimal: str = ".",
+) -> npt.NDArray[np.object_]:
+    """
+    Convert to types which can be consumed by the standard library's
+    csv.writer.writerows.
+    """
+    if isinstance(values, Categorical) and values.categories.dtype.kind in "Mm":
+        # GH#40754 Convert categorical datetimes to datetime array
+        values = algos.take_nd(
+            values.categories._values,
+            ensure_platform_int(values._codes),
+            fill_value=na_rep,
+        )
+
+    values = ensure_wrapped_if_datetimelike(values)
+
+    if isinstance(values, (DatetimeArray, TimedeltaArray)):
+        if values.ndim == 1:
+            result = values._format_native_types(na_rep=na_rep, date_format=date_format)
+            result = result.astype(object, copy=False)
+            return result
+
+        # GH#21734 Process every column separately, they might have different formats
+        results_converted = []
+        for i in range(len(values)):
+            result = values[i, :]._format_native_types(
+                na_rep=na_rep, date_format=date_format
+            )
+            results_converted.append(result.astype(object, copy=False))
+        return np.vstack(results_converted)
+
+    elif isinstance(values.dtype, PeriodDtype):
+        # TODO: tests that get here in column path
+        values = cast("PeriodArray", values)
+        res = values._format_native_types(na_rep=na_rep, date_format=date_format)
+        return res
+
+    elif isinstance(values.dtype, IntervalDtype):
+        # TODO: tests that get here in column path
+        values = cast("IntervalArray", values)
+        mask = values.isna()
+        if not quoting:
+            result = np.asarray(values).astype(str)
+        else:
+            result = np.array(values, dtype=object, copy=True)
+
+        result[mask] = na_rep
+        return result
+
+    elif values.dtype.kind == "f" and not isinstance(values.dtype, SparseDtype):
+        # see GH#13418: no special formatting is desired at the
+        # output (important for appropriate 'quoting' behaviour),
+        # so do not pass it through the FloatArrayFormatter
+        if float_format is None and decimal == ".":
+            mask = isna(values)
+
+            if not quoting:
+                values = values.astype(str)
+            else:
+                values = np.array(values, dtype="object")
+
+            values[mask] = na_rep
+            values = values.astype(object, copy=False)
+            return values
+
+        from pandas.io.formats.format import FloatArrayFormatter
+
+        formatter = FloatArrayFormatter(
+            values,
+            na_rep=na_rep,
+            float_format=float_format,
+            decimal=decimal,
+            quoting=quoting,
+            fixed_width=False,
+        )
+        res = formatter.get_result_as_array()
+        res = res.astype(object, copy=False)
+        return res
+
+    elif isinstance(values, ExtensionArray):
+        mask = isna(values)
+
+        new_values = np.asarray(values.astype(object))
+        new_values[mask] = na_rep
+        return new_values
+
+    else:
+        mask = isna(values)
+        itemsize = writers.word_len(na_rep)
+
+        if values.dtype != _dtype_obj and not quoting and itemsize:
+            values = values.astype(str)
+            if values.dtype.itemsize / np.dtype("U1").itemsize < itemsize:
+                # enlarge for the na_rep
+                values = values.astype(f"`__
+    for more.
+
+    Examples
+    --------
+    >>> pd.CategoricalIndex(["a", "b", "c", "a", "b", "c"])
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['a', 'b', 'c'], ordered=False, dtype='category')
+
+    ``CategoricalIndex`` can also be instantiated from a ``Categorical``:
+
+    >>> c = pd.Categorical(["a", "b", "c", "a", "b", "c"])
+    >>> pd.CategoricalIndex(c)
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['a', 'b', 'c'], ordered=False, dtype='category')
+
+    Ordered ``CategoricalIndex`` can have a min and max value.
+
+    >>> ci = pd.CategoricalIndex(
+    ...     ["a", "b", "c", "a", "b", "c"], ordered=True, categories=["c", "b", "a"]
+    ... )
+    >>> ci
+    CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+                     categories=['c', 'b', 'a'], ordered=True, dtype='category')
+    >>> ci.min()
+    'c'
+    """
+
+    _typ = "categoricalindex"
+    _data_cls = Categorical
+
+    @property
+    def _can_hold_strings(self):
+        return self.categories._can_hold_strings
+
+    @cache_readonly
+    def _should_fallback_to_positional(self) -> bool:
+        return self.categories._should_fallback_to_positional
+
+    codes: np.ndarray
+    categories: Index
+    ordered: bool | None
+    _data: Categorical
+    _values: Categorical
+
+    @property
+    def _engine_type(self) -> type[libindex.IndexEngine]:
+        # self.codes can have dtype int8, int16, int32 or int64, so we need
+        # to return the corresponding engine type (libindex.Int8Engine, etc.).
+        return {
+            np.int8: libindex.Int8Engine,
+            np.int16: libindex.Int16Engine,
+            np.int32: libindex.Int32Engine,
+            np.int64: libindex.Int64Engine,
+        }[self.codes.dtype.type]
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data=None,
+        categories=None,
+        ordered=None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+    ) -> Self:
+        name = maybe_extract_name(name, data, cls)
+
+        if is_scalar(data):
+            # GH#38944 include None here, which pre-2.0 subbed in []
+            cls._raise_scalar_data_error(data)
+
+        data = Categorical(
+            data, categories=categories, ordered=ordered, dtype=dtype, copy=copy
+        )
+
+        return cls._simple_new(data, name=name)
+
+    # --------------------------------------------------------------------
+
+    def _is_dtype_compat(self, other: Index) -> Categorical:
+        """
+        *this is an internal non-public method*
+
+        provide a comparison between the dtype of self and other (coercing if
+        needed)
+
+        Parameters
+        ----------
+        other : Index
+
+        Returns
+        -------
+        Categorical
+
+        Raises
+        ------
+        TypeError if the dtypes are not compatible
+        """
+        if isinstance(other.dtype, CategoricalDtype):
+            cat = extract_array(other)
+            cat = cast(Categorical, cat)
+            if not cat._categories_match_up_to_permutation(self._values):
+                raise TypeError(
+                    "categories must match existing categories when appending"
+                )
+
+        elif other._is_multi:
+            # preempt raising NotImplementedError in isna call
+            raise TypeError("MultiIndex is not dtype-compatible with CategoricalIndex")
+        else:
+            values = other
+
+            cat = Categorical(other, dtype=self.dtype)
+            other = CategoricalIndex(cat)
+            if not other.isin(values).all():
+                raise TypeError(
+                    "cannot append a non-category item to a CategoricalIndex"
+                )
+            cat = other._values
+
+            if not ((cat == values) | (isna(cat) & isna(values))).all():
+                # GH#37667 see test_equals_non_category
+                raise TypeError(
+                    "categories must match existing categories when appending"
+                )
+
+        return cat
+
+    def equals(self, other: object) -> bool:
+        """
+        Determine if two CategoricalIndex objects contain the same elements.
+
+        Returns
+        -------
+        bool
+            ``True`` if two :class:`pandas.CategoricalIndex` objects have equal
+            elements, ``False`` otherwise.
+
+        Examples
+        --------
+        >>> ci = pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'])
+        >>> ci2 = pd.CategoricalIndex(pd.Categorical(['a', 'b', 'c', 'a', 'b', 'c']))
+        >>> ci.equals(ci2)
+        True
+
+        The order of elements matters.
+
+        >>> ci3 = pd.CategoricalIndex(['c', 'b', 'a', 'a', 'b', 'c'])
+        >>> ci.equals(ci3)
+        False
+
+        The orderedness also matters.
+
+        >>> ci4 = ci.as_ordered()
+        >>> ci.equals(ci4)
+        False
+
+        The categories matter, but the order of the categories matters only when
+        ``ordered=True``.
+
+        >>> ci5 = ci.set_categories(['a', 'b', 'c', 'd'])
+        >>> ci.equals(ci5)
+        False
+
+        >>> ci6 = ci.set_categories(['b', 'c', 'a'])
+        >>> ci.equals(ci6)
+        True
+        >>> ci_ordered = pd.CategoricalIndex(['a', 'b', 'c', 'a', 'b', 'c'],
+        ...                                  ordered=True)
+        >>> ci2_ordered = ci_ordered.set_categories(['b', 'c', 'a'])
+        >>> ci_ordered.equals(ci2_ordered)
+        False
+        """
+        if self.is_(other):
+            return True
+
+        if not isinstance(other, Index):
+            return False
+
+        try:
+            other = self._is_dtype_compat(other)
+        except (TypeError, ValueError):
+            return False
+
+        return self._data.equals(other)
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+
+    @property
+    def _formatter_func(self):
+        return self.categories._formatter_func
+
+    def _format_attrs(self):
+        """
+        Return a list of tuples of the (attr,formatted_value)
+        """
+        attrs: list[tuple[str, str | int | bool | None]]
+
+        attrs = [
+            (
+                "categories",
+                f"[{', '.join(self._data._repr_categories())}]",
+            ),
+            ("ordered", self.ordered),
+        ]
+        extra = super()._format_attrs()
+        return attrs + extra
+
+    # --------------------------------------------------------------------
+
+    @property
+    def inferred_type(self) -> str:
+        return "categorical"
+
+    @doc(Index.__contains__)
+    def __contains__(self, key: Any) -> bool:
+        # if key is a NaN, check if any NaN is in self.
+        if is_valid_na_for_dtype(key, self.categories.dtype):
+            return self.hasnans
+
+        return contains(self, key, container=self._engine)
+
+    def reindex(
+        self, target, method=None, level=None, limit: int | None = None, tolerance=None
+    ) -> tuple[Index, npt.NDArray[np.intp] | None]:
+        """
+        Create index with target's values (move/add/delete values as necessary)
+
+        Returns
+        -------
+        new_index : pd.Index
+            Resulting index
+        indexer : np.ndarray[np.intp] or None
+            Indices of output values in original index
+
+        """
+        if method is not None:
+            raise NotImplementedError(
+                "argument method is not implemented for CategoricalIndex.reindex"
+            )
+        if level is not None:
+            raise NotImplementedError(
+                "argument level is not implemented for CategoricalIndex.reindex"
+            )
+        if limit is not None:
+            raise NotImplementedError(
+                "argument limit is not implemented for CategoricalIndex.reindex"
+            )
+        return super().reindex(target)
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    def _maybe_cast_indexer(self, key) -> int:
+        # GH#41933: we have to do this instead of self._data._validate_scalar
+        #  because this will correctly get partial-indexing on Interval categories
+        try:
+            return self._data._unbox_scalar(key)
+        except KeyError:
+            if is_valid_na_for_dtype(key, self.categories.dtype):
+                return -1
+            raise
+
+    def _maybe_cast_listlike_indexer(self, values) -> CategoricalIndex:
+        if isinstance(values, CategoricalIndex):
+            values = values._data
+        if isinstance(values, Categorical):
+            # Indexing on codes is more efficient if categories are the same,
+            #  so we can apply some optimizations based on the degree of
+            #  dtype-matching.
+            cat = self._data._encode_with_my_categories(values)
+            codes = cat._codes
+        else:
+            codes = self.categories.get_indexer(values)
+            codes = codes.astype(self.codes.dtype, copy=False)
+            cat = self._data._from_backing_data(codes)
+        return type(self)._simple_new(cat)
+
+    # --------------------------------------------------------------------
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        return self.categories._is_comparable_dtype(dtype)
+
+    def map(self, mapper, na_action: Literal["ignore"] | None = None):
+        """
+        Map values using input an input mapping or function.
+
+        Maps the values (their categories, not the codes) of the index to new
+        categories. If the mapping correspondence is one-to-one the result is a
+        :class:`~pandas.CategoricalIndex` which has the same order property as
+        the original, otherwise an :class:`~pandas.Index` is returned.
+
+        If a `dict` or :class:`~pandas.Series` is used any unmapped category is
+        mapped to `NaN`. Note that if this happens an :class:`~pandas.Index`
+        will be returned.
+
+        Parameters
+        ----------
+        mapper : function, dict, or Series
+            Mapping correspondence.
+
+        Returns
+        -------
+        pandas.CategoricalIndex or pandas.Index
+            Mapped index.
+
+        See Also
+        --------
+        Index.map : Apply a mapping correspondence on an
+            :class:`~pandas.Index`.
+        Series.map : Apply a mapping correspondence on a
+            :class:`~pandas.Series`.
+        Series.apply : Apply more complex functions on a
+            :class:`~pandas.Series`.
+
+        Examples
+        --------
+        >>> idx = pd.CategoricalIndex(['a', 'b', 'c'])
+        >>> idx
+        CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'],
+                          ordered=False, dtype='category')
+        >>> idx.map(lambda x: x.upper())
+        CategoricalIndex(['A', 'B', 'C'], categories=['A', 'B', 'C'],
+                         ordered=False, dtype='category')
+        >>> idx.map({'a': 'first', 'b': 'second', 'c': 'third'})
+        CategoricalIndex(['first', 'second', 'third'], categories=['first',
+                         'second', 'third'], ordered=False, dtype='category')
+
+        If the mapping is one-to-one the ordering of the categories is
+        preserved:
+
+        >>> idx = pd.CategoricalIndex(['a', 'b', 'c'], ordered=True)
+        >>> idx
+        CategoricalIndex(['a', 'b', 'c'], categories=['a', 'b', 'c'],
+                         ordered=True, dtype='category')
+        >>> idx.map({'a': 3, 'b': 2, 'c': 1})
+        CategoricalIndex([3, 2, 1], categories=[3, 2, 1], ordered=True,
+                         dtype='category')
+
+        If the mapping is not one-to-one an :class:`~pandas.Index` is returned:
+
+        >>> idx.map({'a': 'first', 'b': 'second', 'c': 'first'})
+        Index(['first', 'second', 'first'], dtype='object')
+
+        If a `dict` is used, all unmapped categories are mapped to `NaN` and
+        the result is an :class:`~pandas.Index`:
+
+        >>> idx.map({'a': 'first', 'b': 'second'})
+        Index(['first', 'second', nan], dtype='object')
+        """
+        mapped = self._values.map(mapper, na_action=na_action)
+        return Index(mapped, name=self.name)
+
+    def _concat(self, to_concat: list[Index], name: Hashable) -> Index:
+        # if calling index is category, don't check dtype of others
+        try:
+            cat = Categorical._concat_same_type(
+                [self._is_dtype_compat(c) for c in to_concat]
+            )
+        except TypeError:
+            # not all to_concat elements are among our categories (or NA)
+
+            res = concat_compat([x._values for x in to_concat])
+            return Index(res, name=name)
+        else:
+            return type(self)._simple_new(cat, name=name)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimelike.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimelike.py
new file mode 100644
index 0000000000000000000000000000000000000000..cad8737a987d44f23518a8b6fa88e9a686755c65
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimelike.py
@@ -0,0 +1,843 @@
+"""
+Base and utility classes for tseries type pandas objects.
+"""
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    cast,
+    final,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_copy_on_write
+
+from pandas._libs import (
+    NaT,
+    Timedelta,
+    lib,
+)
+from pandas._libs.tslibs import (
+    BaseOffset,
+    Resolution,
+    Tick,
+    parsing,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import freq_to_period_freqstr
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    InvalidIndexError,
+    NullFrequencyError,
+)
+from pandas.util._decorators import (
+    Appender,
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_integer,
+    is_list_like,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+from pandas.core.arrays import (
+    DatetimeArray,
+    ExtensionArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.datetimelike import DatetimeLikeArrayMixin
+import pandas.core.common as com
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.base import (
+    Index,
+    _index_shared_docs,
+)
+from pandas.core.indexes.extension import NDArrayBackedExtensionIndex
+from pandas.core.indexes.range import RangeIndex
+from pandas.core.tools.timedeltas import to_timedelta
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import datetime
+
+    from pandas._typing import (
+        Axis,
+        Self,
+        npt,
+    )
+
+    from pandas import CategoricalIndex
+
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+
+
+class DatetimeIndexOpsMixin(NDArrayBackedExtensionIndex, ABC):
+    """
+    Common ops mixin to support a unified interface datetimelike Index.
+    """
+
+    _can_hold_strings = False
+    _data: DatetimeArray | TimedeltaArray | PeriodArray
+
+    @doc(DatetimeLikeArrayMixin.mean)
+    def mean(self, *, skipna: bool = True, axis: int | None = 0):
+        return self._data.mean(skipna=skipna, axis=axis)
+
+    @property
+    def freq(self) -> BaseOffset | None:
+        return self._data.freq
+
+    @freq.setter
+    def freq(self, value) -> None:
+        # error: Property "freq" defined in "PeriodArray" is read-only  [misc]
+        self._data.freq = value  # type: ignore[misc]
+
+    @property
+    def asi8(self) -> npt.NDArray[np.int64]:
+        return self._data.asi8
+
+    @property
+    @doc(DatetimeLikeArrayMixin.freqstr)
+    def freqstr(self) -> str:
+        from pandas import PeriodIndex
+
+        if self._data.freqstr is not None and isinstance(
+            self._data, (PeriodArray, PeriodIndex)
+        ):
+            freq = freq_to_period_freqstr(self._data.freq.n, self._data.freq.name)
+            return freq
+        else:
+            return self._data.freqstr  # type: ignore[return-value]
+
+    @cache_readonly
+    @abstractmethod
+    def _resolution_obj(self) -> Resolution:
+        ...
+
+    @cache_readonly
+    @doc(DatetimeLikeArrayMixin.resolution)
+    def resolution(self) -> str:
+        return self._data.resolution
+
+    # ------------------------------------------------------------------------
+
+    @cache_readonly
+    def hasnans(self) -> bool:
+        return self._data._hasna
+
+    def equals(self, other: Any) -> bool:
+        """
+        Determines if two Index objects contain the same elements.
+        """
+        if self.is_(other):
+            return True
+
+        if not isinstance(other, Index):
+            return False
+        elif other.dtype.kind in "iufc":
+            return False
+        elif not isinstance(other, type(self)):
+            should_try = False
+            inferable = self._data._infer_matches
+            if other.dtype == object:
+                should_try = other.inferred_type in inferable
+            elif isinstance(other.dtype, CategoricalDtype):
+                other = cast("CategoricalIndex", other)
+                should_try = other.categories.inferred_type in inferable
+
+            if should_try:
+                try:
+                    other = type(self)(other)
+                except (ValueError, TypeError, OverflowError):
+                    # e.g.
+                    #  ValueError -> cannot parse str entry, or OutOfBoundsDatetime
+                    #  TypeError  -> trying to convert IntervalIndex to DatetimeIndex
+                    #  OverflowError -> Index([very_large_timedeltas])
+                    return False
+
+        if self.dtype != other.dtype:
+            # have different timezone
+            return False
+
+        return np.array_equal(self.asi8, other.asi8)
+
+    @Appender(Index.__contains__.__doc__)
+    def __contains__(self, key: Any) -> bool:
+        hash(key)
+        try:
+            self.get_loc(key)
+        except (KeyError, TypeError, ValueError, InvalidIndexError):
+            return False
+        return True
+
+    def _convert_tolerance(self, tolerance, target):
+        tolerance = np.asarray(to_timedelta(tolerance).to_numpy())
+        return super()._convert_tolerance(tolerance, target)
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+    _default_na_rep = "NaT"
+
+    def format(
+        self,
+        name: bool = False,
+        formatter: Callable | None = None,
+        na_rep: str = "NaT",
+        date_format: str | None = None,
+    ) -> list[str]:
+        """
+        Render a string representation of the Index.
+        """
+        warnings.warn(
+            # GH#55413
+            f"{type(self).__name__}.format is deprecated and will be removed "
+            "in a future version. Convert using index.astype(str) or "
+            "index.map(formatter) instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        header = []
+        if name:
+            header.append(
+                ibase.pprint_thing(self.name, escape_chars=("\t", "\r", "\n"))
+                if self.name is not None
+                else ""
+            )
+
+        if formatter is not None:
+            return header + list(self.map(formatter))
+
+        return self._format_with_header(
+            header=header, na_rep=na_rep, date_format=date_format
+        )
+
+    def _format_with_header(
+        self, *, header: list[str], na_rep: str, date_format: str | None = None
+    ) -> list[str]:
+        # TODO: not reached in tests 2023-10-11
+        # matches base class except for whitespace padding and date_format
+        return header + list(
+            self._get_values_for_csv(na_rep=na_rep, date_format=date_format)
+        )
+
+    @property
+    def _formatter_func(self):
+        return self._data._formatter()
+
+    def _format_attrs(self):
+        """
+        Return a list of tuples of the (attr,formatted_value).
+        """
+        attrs = super()._format_attrs()
+        for attrib in self._attributes:
+            # iterating over _attributes prevents us from doing this for PeriodIndex
+            if attrib == "freq":
+                freq = self.freqstr
+                if freq is not None:
+                    freq = repr(freq)  # e.g. D -> 'D'
+                attrs.append(("freq", freq))
+        return attrs
+
+    @Appender(Index._summary.__doc__)
+    def _summary(self, name=None) -> str:
+        result = super()._summary(name=name)
+        if self.freq:
+            result += f"\nFreq: {self.freqstr}"
+
+        return result
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    @final
+    def _can_partial_date_slice(self, reso: Resolution) -> bool:
+        # e.g. test_getitem_setitem_periodindex
+        # History of conversation GH#3452, GH#3931, GH#2369, GH#14826
+        return reso > self._resolution_obj
+        # NB: for DTI/PI, not TDI
+
+    def _parsed_string_to_bounds(self, reso: Resolution, parsed):
+        raise NotImplementedError
+
+    def _parse_with_reso(self, label: str):
+        # overridden by TimedeltaIndex
+        try:
+            if self.freq is None or hasattr(self.freq, "rule_code"):
+                freq = self.freq
+        except NotImplementedError:
+            freq = getattr(self, "freqstr", getattr(self, "inferred_freq", None))
+
+        freqstr: str | None
+        if freq is not None and not isinstance(freq, str):
+            freqstr = freq.rule_code
+        else:
+            freqstr = freq
+
+        if isinstance(label, np.str_):
+            # GH#45580
+            label = str(label)
+
+        parsed, reso_str = parsing.parse_datetime_string_with_reso(label, freqstr)
+        reso = Resolution.from_attrname(reso_str)
+        return parsed, reso
+
+    def _get_string_slice(self, key: str):
+        # overridden by TimedeltaIndex
+        parsed, reso = self._parse_with_reso(key)
+        try:
+            return self._partial_date_slice(reso, parsed)
+        except KeyError as err:
+            raise KeyError(key) from err
+
+    @final
+    def _partial_date_slice(
+        self,
+        reso: Resolution,
+        parsed: datetime,
+    ) -> slice | npt.NDArray[np.intp]:
+        """
+        Parameters
+        ----------
+        reso : Resolution
+        parsed : datetime
+
+        Returns
+        -------
+        slice or ndarray[intp]
+        """
+        if not self._can_partial_date_slice(reso):
+            raise ValueError
+
+        t1, t2 = self._parsed_string_to_bounds(reso, parsed)
+        vals = self._data._ndarray
+        unbox = self._data._unbox
+
+        if self.is_monotonic_increasing:
+            if len(self) and (
+                (t1 < self[0] and t2 < self[0]) or (t1 > self[-1] and t2 > self[-1])
+            ):
+                # we are out of range
+                raise KeyError
+
+            # TODO: does this depend on being monotonic _increasing_?
+
+            # a monotonic (sorted) series can be sliced
+            left = vals.searchsorted(unbox(t1), side="left")
+            right = vals.searchsorted(unbox(t2), side="right")
+            return slice(left, right)
+
+        else:
+            lhs_mask = vals >= unbox(t1)
+            rhs_mask = vals <= unbox(t2)
+
+            # try to find the dates
+            return (lhs_mask & rhs_mask).nonzero()[0]
+
+    def _maybe_cast_slice_bound(self, label, side: str):
+        """
+        If label is a string, cast it to scalar type according to resolution.
+
+        Parameters
+        ----------
+        label : object
+        side : {'left', 'right'}
+
+        Returns
+        -------
+        label : object
+
+        Notes
+        -----
+        Value of `side` parameter should be validated in caller.
+        """
+        if isinstance(label, str):
+            try:
+                parsed, reso = self._parse_with_reso(label)
+            except ValueError as err:
+                # DTI -> parsing.DateParseError
+                # TDI -> 'unit abbreviation w/o a number'
+                # PI -> string cannot be parsed as datetime-like
+                self._raise_invalid_indexer("slice", label, err)
+
+            lower, upper = self._parsed_string_to_bounds(reso, parsed)
+            return lower if side == "left" else upper
+        elif not isinstance(label, self._data._recognized_scalars):
+            self._raise_invalid_indexer("slice", label)
+
+        return label
+
+    # --------------------------------------------------------------------
+    # Arithmetic Methods
+
+    def shift(self, periods: int = 1, freq=None) -> Self:
+        """
+        Shift index by desired number of time frequency increments.
+
+        This method is for shifting the values of datetime-like indexes
+        by a specified time increment a given number of times.
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Number of periods (or increments) to shift by,
+            can be positive or negative.
+        freq : pandas.DateOffset, pandas.Timedelta or string, optional
+            Frequency increment to shift by.
+            If None, the index is shifted by its own `freq` attribute.
+            Offset aliases are valid strings, e.g., 'D', 'W', 'M' etc.
+
+        Returns
+        -------
+        pandas.DatetimeIndex
+            Shifted index.
+
+        See Also
+        --------
+        Index.shift : Shift values of Index.
+        PeriodIndex.shift : Shift values of PeriodIndex.
+        """
+        raise NotImplementedError
+
+    # --------------------------------------------------------------------
+
+    @doc(Index._maybe_cast_listlike_indexer)
+    def _maybe_cast_listlike_indexer(self, keyarr):
+        try:
+            res = self._data._validate_listlike(keyarr, allow_object=True)
+        except (ValueError, TypeError):
+            if not isinstance(keyarr, ExtensionArray):
+                # e.g. we don't want to cast DTA to ndarray[object]
+                res = com.asarray_tuplesafe(keyarr)
+                # TODO: com.asarray_tuplesafe shouldn't cast e.g. DatetimeArray
+            else:
+                res = keyarr
+        return Index(res, dtype=res.dtype)
+
+
+class DatetimeTimedeltaMixin(DatetimeIndexOpsMixin, ABC):
+    """
+    Mixin class for methods shared by DatetimeIndex and TimedeltaIndex,
+    but not PeriodIndex
+    """
+
+    _data: DatetimeArray | TimedeltaArray
+    _comparables = ["name", "freq"]
+    _attributes = ["name", "freq"]
+
+    # Compat for frequency inference, see GH#23789
+    _is_monotonic_increasing = Index.is_monotonic_increasing
+    _is_monotonic_decreasing = Index.is_monotonic_decreasing
+    _is_unique = Index.is_unique
+
+    @property
+    def unit(self) -> str:
+        return self._data.unit
+
+    def as_unit(self, unit: str) -> Self:
+        """
+        Convert to a dtype with the given unit resolution.
+
+        Parameters
+        ----------
+        unit : {'s', 'ms', 'us', 'ns'}
+
+        Returns
+        -------
+        same type as self
+
+        Examples
+        --------
+        For :class:`pandas.DatetimeIndex`:
+
+        >>> idx = pd.DatetimeIndex(['2020-01-02 01:02:03.004005006'])
+        >>> idx
+        DatetimeIndex(['2020-01-02 01:02:03.004005006'],
+                      dtype='datetime64[ns]', freq=None)
+        >>> idx.as_unit('s')
+        DatetimeIndex(['2020-01-02 01:02:03'], dtype='datetime64[s]', freq=None)
+
+        For :class:`pandas.TimedeltaIndex`:
+
+        >>> tdelta_idx = pd.to_timedelta(['1 day 3 min 2 us 42 ns'])
+        >>> tdelta_idx
+        TimedeltaIndex(['1 days 00:03:00.000002042'],
+                        dtype='timedelta64[ns]', freq=None)
+        >>> tdelta_idx.as_unit('s')
+        TimedeltaIndex(['1 days 00:03:00'], dtype='timedelta64[s]', freq=None)
+        """
+        arr = self._data.as_unit(unit)
+        return type(self)._simple_new(arr, name=self.name)
+
+    def _with_freq(self, freq):
+        arr = self._data._with_freq(freq)
+        return type(self)._simple_new(arr, name=self._name)
+
+    @property
+    def values(self) -> np.ndarray:
+        # NB: For Datetime64TZ this is lossy
+        data = self._data._ndarray
+        if using_copy_on_write():
+            data = data.view()
+            data.flags.writeable = False
+        return data
+
+    @doc(DatetimeIndexOpsMixin.shift)
+    def shift(self, periods: int = 1, freq=None) -> Self:
+        if freq is not None and freq != self.freq:
+            if isinstance(freq, str):
+                freq = to_offset(freq)
+            offset = periods * freq
+            return self + offset
+
+        if periods == 0 or len(self) == 0:
+            # GH#14811 empty case
+            return self.copy()
+
+        if self.freq is None:
+            raise NullFrequencyError("Cannot shift with no freq")
+
+        start = self[0] + periods * self.freq
+        end = self[-1] + periods * self.freq
+
+        # Note: in the DatetimeTZ case, _generate_range will infer the
+        #  appropriate timezone from `start` and `end`, so tz does not need
+        #  to be passed explicitly.
+        result = self._data._generate_range(
+            start=start, end=end, periods=None, freq=self.freq, unit=self.unit
+        )
+        return type(self)._simple_new(result, name=self.name)
+
+    @cache_readonly
+    @doc(DatetimeLikeArrayMixin.inferred_freq)
+    def inferred_freq(self) -> str | None:
+        return self._data.inferred_freq
+
+    # --------------------------------------------------------------------
+    # Set Operation Methods
+
+    @cache_readonly
+    def _as_range_index(self) -> RangeIndex:
+        # Convert our i8 representations to RangeIndex
+        # Caller is responsible for checking isinstance(self.freq, Tick)
+        freq = cast(Tick, self.freq)
+        tick = Timedelta(freq).as_unit("ns")._value
+        rng = range(self[0]._value, self[-1]._value + tick, tick)
+        return RangeIndex(rng)
+
+    def _can_range_setop(self, other) -> bool:
+        return isinstance(self.freq, Tick) and isinstance(other.freq, Tick)
+
+    def _wrap_range_setop(self, other, res_i8) -> Self:
+        new_freq = None
+        if not len(res_i8):
+            # RangeIndex defaults to step=1, which we don't want.
+            new_freq = self.freq
+        elif isinstance(res_i8, RangeIndex):
+            new_freq = to_offset(Timedelta(res_i8.step))
+
+        # TODO(GH#41493): we cannot just do
+        #  type(self._data)(res_i8.values, dtype=self.dtype, freq=new_freq)
+        # because test_setops_preserve_freq fails with _validate_frequency raising.
+        # This raising is incorrect, as 'on_freq' is incorrect. This will
+        # be fixed by GH#41493
+        res_values = res_i8.values.view(self._data._ndarray.dtype)
+        result = type(self._data)._simple_new(
+            # error: Argument "dtype" to "_simple_new" of "DatetimeArray" has
+            # incompatible type "Union[dtype[Any], ExtensionDtype]"; expected
+            # "Union[dtype[datetime64], DatetimeTZDtype]"
+            res_values,
+            dtype=self.dtype,  # type: ignore[arg-type]
+            freq=new_freq,  # type: ignore[arg-type]
+        )
+        return cast("Self", self._wrap_setop_result(other, result))
+
+    def _range_intersect(self, other, sort) -> Self:
+        # Dispatch to RangeIndex intersection logic.
+        left = self._as_range_index
+        right = other._as_range_index
+        res_i8 = left.intersection(right, sort=sort)
+        return self._wrap_range_setop(other, res_i8)
+
+    def _range_union(self, other, sort) -> Self:
+        # Dispatch to RangeIndex union logic.
+        left = self._as_range_index
+        right = other._as_range_index
+        res_i8 = left.union(right, sort=sort)
+        return self._wrap_range_setop(other, res_i8)
+
+    def _intersection(self, other: Index, sort: bool = False) -> Index:
+        """
+        intersection specialized to the case with matching dtypes and both non-empty.
+        """
+        other = cast("DatetimeTimedeltaMixin", other)
+
+        if self._can_range_setop(other):
+            return self._range_intersect(other, sort=sort)
+
+        if not self._can_fast_intersect(other):
+            result = Index._intersection(self, other, sort=sort)
+            # We need to invalidate the freq because Index._intersection
+            #  uses _shallow_copy on a view of self._data, which will preserve
+            #  self.freq if we're not careful.
+            # At this point we should have result.dtype == self.dtype
+            #  and type(result) is type(self._data)
+            result = self._wrap_setop_result(other, result)
+            return result._with_freq(None)._with_freq("infer")
+
+        else:
+            return self._fast_intersect(other, sort)
+
+    def _fast_intersect(self, other, sort):
+        # to make our life easier, "sort" the two ranges
+        if self[0] <= other[0]:
+            left, right = self, other
+        else:
+            left, right = other, self
+
+        # after sorting, the intersection always starts with the right index
+        # and ends with the index of which the last elements is smallest
+        end = min(left[-1], right[-1])
+        start = right[0]
+
+        if end < start:
+            result = self[:0]
+        else:
+            lslice = slice(*left.slice_locs(start, end))
+            result = left._values[lslice]
+
+        return result
+
+    def _can_fast_intersect(self, other: Self) -> bool:
+        # Note: we only get here with len(self) > 0 and len(other) > 0
+        if self.freq is None:
+            return False
+
+        elif other.freq != self.freq:
+            return False
+
+        elif not self.is_monotonic_increasing:
+            # Because freq is not None, we must then be monotonic decreasing
+            return False
+
+        # this along with matching freqs ensure that we "line up",
+        #  so intersection will preserve freq
+        # Note we are assuming away Ticks, as those go through _range_intersect
+        # GH#42104
+        return self.freq.n == 1
+
+    def _can_fast_union(self, other: Self) -> bool:
+        # Assumes that type(self) == type(other), as per the annotation
+        # The ability to fast_union also implies that `freq` should be
+        #  retained on union.
+        freq = self.freq
+
+        if freq is None or freq != other.freq:
+            return False
+
+        if not self.is_monotonic_increasing:
+            # Because freq is not None, we must then be monotonic decreasing
+            # TODO: do union on the reversed indexes?
+            return False
+
+        if len(self) == 0 or len(other) == 0:
+            # only reached via union_many
+            return True
+
+        # to make our life easier, "sort" the two ranges
+        if self[0] <= other[0]:
+            left, right = self, other
+        else:
+            left, right = other, self
+
+        right_start = right[0]
+        left_end = left[-1]
+
+        # Only need to "adjoin", not overlap
+        return (right_start == left_end + freq) or right_start in left
+
+    def _fast_union(self, other: Self, sort=None) -> Self:
+        # Caller is responsible for ensuring self and other are non-empty
+
+        # to make our life easier, "sort" the two ranges
+        if self[0] <= other[0]:
+            left, right = self, other
+        elif sort is False:
+            # TDIs are not in the "correct" order and we don't want
+            #  to sort but want to remove overlaps
+            left, right = self, other
+            left_start = left[0]
+            loc = right.searchsorted(left_start, side="left")
+            right_chunk = right._values[:loc]
+            dates = concat_compat((left._values, right_chunk))
+            result = type(self)._simple_new(dates, name=self.name)
+            return result
+        else:
+            left, right = other, self
+
+        left_end = left[-1]
+        right_end = right[-1]
+
+        # concatenate
+        if left_end < right_end:
+            loc = right.searchsorted(left_end, side="right")
+            right_chunk = right._values[loc:]
+            dates = concat_compat([left._values, right_chunk])
+            # The can_fast_union check ensures that the result.freq
+            #  should match self.freq
+            assert isinstance(dates, type(self._data))
+            # error: Item "ExtensionArray" of "ExtensionArray |
+            # ndarray[Any, Any]" has no attribute "_freq"
+            assert dates._freq == self.freq  # type: ignore[union-attr]
+            result = type(self)._simple_new(dates)
+            return result
+        else:
+            return left
+
+    def _union(self, other, sort):
+        # We are called by `union`, which is responsible for this validation
+        assert isinstance(other, type(self))
+        assert self.dtype == other.dtype
+
+        if self._can_range_setop(other):
+            return self._range_union(other, sort=sort)
+
+        if self._can_fast_union(other):
+            result = self._fast_union(other, sort=sort)
+            # in the case with sort=None, the _can_fast_union check ensures
+            #  that result.freq == self.freq
+            return result
+        else:
+            return super()._union(other, sort)._with_freq("infer")
+
+    # --------------------------------------------------------------------
+    # Join Methods
+
+    def _get_join_freq(self, other):
+        """
+        Get the freq to attach to the result of a join operation.
+        """
+        freq = None
+        if self._can_fast_union(other):
+            freq = self.freq
+        return freq
+
+    def _wrap_joined_index(
+        self, joined, other, lidx: npt.NDArray[np.intp], ridx: npt.NDArray[np.intp]
+    ):
+        assert other.dtype == self.dtype, (other.dtype, self.dtype)
+        result = super()._wrap_joined_index(joined, other, lidx, ridx)
+        result._data._freq = self._get_join_freq(other)
+        return result
+
+    def _get_engine_target(self) -> np.ndarray:
+        # engine methods and libjoin methods need dt64/td64 values cast to i8
+        return self._data._ndarray.view("i8")
+
+    def _from_join_target(self, result: np.ndarray):
+        # view e.g. i8 back to M8[ns]
+        result = result.view(self._data._ndarray.dtype)
+        return self._data._from_backing_data(result)
+
+    # --------------------------------------------------------------------
+    # List-like Methods
+
+    def _get_delete_freq(self, loc: int | slice | Sequence[int]):
+        """
+        Find the `freq` for self.delete(loc).
+        """
+        freq = None
+        if self.freq is not None:
+            if is_integer(loc):
+                if loc in (0, -len(self), -1, len(self) - 1):
+                    freq = self.freq
+            else:
+                if is_list_like(loc):
+                    # error: Incompatible types in assignment (expression has
+                    # type "Union[slice, ndarray]", variable has type
+                    # "Union[int, slice, Sequence[int]]")
+                    loc = lib.maybe_indices_to_slice(  # type: ignore[assignment]
+                        np.asarray(loc, dtype=np.intp), len(self)
+                    )
+                if isinstance(loc, slice) and loc.step in (1, None):
+                    if loc.start in (0, None) or loc.stop in (len(self), None):
+                        freq = self.freq
+        return freq
+
+    def _get_insert_freq(self, loc: int, item):
+        """
+        Find the `freq` for self.insert(loc, item).
+        """
+        value = self._data._validate_scalar(item)
+        item = self._data._box_func(value)
+
+        freq = None
+        if self.freq is not None:
+            # freq can be preserved on edge cases
+            if self.size:
+                if item is NaT:
+                    pass
+                elif loc in (0, -len(self)) and item + self.freq == self[0]:
+                    freq = self.freq
+                elif (loc == len(self)) and item - self.freq == self[-1]:
+                    freq = self.freq
+            else:
+                # Adding a single item to an empty index may preserve freq
+                if isinstance(self.freq, Tick):
+                    # all TimedeltaIndex cases go through here; is_on_offset
+                    #  would raise TypeError
+                    freq = self.freq
+                elif self.freq.is_on_offset(item):
+                    freq = self.freq
+        return freq
+
+    @doc(NDArrayBackedExtensionIndex.delete)
+    def delete(self, loc) -> Self:
+        result = super().delete(loc)
+        result._data._freq = self._get_delete_freq(loc)
+        return result
+
+    @doc(NDArrayBackedExtensionIndex.insert)
+    def insert(self, loc: int, item):
+        result = super().insert(loc, item)
+        if isinstance(result, type(self)):
+            # i.e. parent class method did not cast
+            result._data._freq = self._get_insert_freq(loc, item)
+        return result
+
+    # --------------------------------------------------------------------
+    # NDArray-Like Methods
+
+    @Appender(_index_shared_docs["take"] % _index_doc_kwargs)
+    def take(
+        self,
+        indices,
+        axis: Axis = 0,
+        allow_fill: bool = True,
+        fill_value=None,
+        **kwargs,
+    ) -> Self:
+        nv.validate_take((), kwargs)
+        indices = np.asarray(indices, dtype=np.intp)
+
+        result = NDArrayBackedExtensionIndex.take(
+            self, indices, axis, allow_fill, fill_value, **kwargs
+        )
+
+        maybe_slice = lib.maybe_indices_to_slice(indices, len(self))
+        if isinstance(maybe_slice, slice):
+            freq = self._data._get_getitem_freq(maybe_slice)
+            result._data._freq = freq
+        return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimes.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimes.py
new file mode 100644
index 0000000000000000000000000000000000000000..3204a9c97ee73fa873a4cbe461e2f3c4690c781f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/datetimes.py
@@ -0,0 +1,1127 @@
+from __future__ import annotations
+
+import datetime as dt
+import operator
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+import pytz
+
+from pandas._libs import (
+    NaT,
+    Period,
+    Timestamp,
+    index as libindex,
+    lib,
+)
+from pandas._libs.tslibs import (
+    Resolution,
+    Tick,
+    Timedelta,
+    periods_per_day,
+    timezones,
+    to_offset,
+)
+from pandas._libs.tslibs.offsets import prefix_mapping
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_scalar
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+from pandas.core.dtypes.generic import ABCSeries
+from pandas.core.dtypes.missing import is_valid_na_for_dtype
+
+from pandas.core.arrays.datetimes import (
+    DatetimeArray,
+    tz_to_dtype,
+)
+import pandas.core.common as com
+from pandas.core.indexes.base import (
+    Index,
+    maybe_extract_name,
+)
+from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
+from pandas.core.indexes.extension import inherit_names
+from pandas.core.tools.times import to_time
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        Frequency,
+        IntervalClosedType,
+        Self,
+        TimeAmbiguous,
+        TimeNonexistent,
+        npt,
+    )
+
+    from pandas.core.api import (
+        DataFrame,
+        PeriodIndex,
+    )
+
+from pandas._libs.tslibs.dtypes import OFFSET_TO_PERIOD_FREQSTR
+
+
+def _new_DatetimeIndex(cls, d):
+    """
+    This is called upon unpickling, rather than the default which doesn't
+    have arguments and breaks __new__
+    """
+    if "data" in d and not isinstance(d["data"], DatetimeIndex):
+        # Avoid need to verify integrity by calling simple_new directly
+        data = d.pop("data")
+        if not isinstance(data, DatetimeArray):
+            # For backward compat with older pickles, we may need to construct
+            #  a DatetimeArray to adapt to the newer _simple_new signature
+            tz = d.pop("tz")
+            freq = d.pop("freq")
+            dta = DatetimeArray._simple_new(data, dtype=tz_to_dtype(tz), freq=freq)
+        else:
+            dta = data
+            for key in ["tz", "freq"]:
+                # These are already stored in our DatetimeArray; if they are
+                #  also in the pickle and don't match, we have a problem.
+                if key in d:
+                    assert d[key] == getattr(dta, key)
+                    d.pop(key)
+        result = cls._simple_new(dta, **d)
+    else:
+        with warnings.catch_warnings():
+            # TODO: If we knew what was going in to **d, we might be able to
+            #  go through _simple_new instead
+            warnings.simplefilter("ignore")
+            result = cls.__new__(cls, **d)
+
+    return result
+
+
+@inherit_names(
+    DatetimeArray._field_ops
+    + [
+        method
+        for method in DatetimeArray._datetimelike_methods
+        if method not in ("tz_localize", "tz_convert", "strftime")
+    ],
+    DatetimeArray,
+    wrap=True,
+)
+@inherit_names(["is_normalized"], DatetimeArray, cache=True)
+@inherit_names(
+    [
+        "tz",
+        "tzinfo",
+        "dtype",
+        "to_pydatetime",
+        "date",
+        "time",
+        "timetz",
+        "std",
+    ]
+    + DatetimeArray._bool_ops,
+    DatetimeArray,
+)
+class DatetimeIndex(DatetimeTimedeltaMixin):
+    """
+    Immutable ndarray-like of datetime64 data.
+
+    Represented internally as int64, and which can be boxed to Timestamp objects
+    that are subclasses of datetime and carry metadata.
+
+    .. versionchanged:: 2.0.0
+        The various numeric date/time attributes (:attr:`~DatetimeIndex.day`,
+        :attr:`~DatetimeIndex.month`, :attr:`~DatetimeIndex.year` etc.) now have dtype
+        ``int32``. Previously they had dtype ``int64``.
+
+    Parameters
+    ----------
+    data : array-like (1-dimensional)
+        Datetime-like data to construct index with.
+    freq : str or pandas offset object, optional
+        One of pandas date offset strings or corresponding objects. The string
+        'infer' can be passed in order to set the frequency of the index as the
+        inferred frequency upon creation.
+    tz : pytz.timezone or dateutil.tz.tzfile or datetime.tzinfo or str
+        Set the Timezone of the data.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+
+        .. deprecated:: 2.1.0
+
+    closed : {'left', 'right'}, optional
+        Set whether to include `start` and `end` that are on the
+        boundary. The default includes boundary points on either end.
+
+        .. deprecated:: 2.1.0
+
+    ambiguous : 'infer', bool-ndarray, 'NaT', default 'raise'
+        When clocks moved backward due to DST, ambiguous times may arise.
+        For example in Central European Time (UTC+01), when going from 03:00
+        DST to 02:00 non-DST, 02:30:00 local time occurs both at 00:30:00 UTC
+        and at 01:30:00 UTC. In such a situation, the `ambiguous` parameter
+        dictates how ambiguous times should be handled.
+
+        - 'infer' will attempt to infer fall dst-transition hours based on
+          order
+        - bool-ndarray where True signifies a DST time, False signifies a
+          non-DST time (note that this flag is only applicable for ambiguous
+          times)
+        - 'NaT' will return NaT where there are ambiguous times
+        - 'raise' will raise an AmbiguousTimeError if there are ambiguous times.
+    dayfirst : bool, default False
+        If True, parse dates in `data` with the day first order.
+    yearfirst : bool, default False
+        If True parse dates in `data` with the year first order.
+    dtype : numpy.dtype or DatetimeTZDtype or str, default None
+        Note that the only NumPy dtype allowed is `datetime64[ns]`.
+    copy : bool, default False
+        Make a copy of input ndarray.
+    name : label, default None
+        Name to be stored in the index.
+
+    Attributes
+    ----------
+    year
+    month
+    day
+    hour
+    minute
+    second
+    microsecond
+    nanosecond
+    date
+    time
+    timetz
+    dayofyear
+    day_of_year
+    dayofweek
+    day_of_week
+    weekday
+    quarter
+    tz
+    freq
+    freqstr
+    is_month_start
+    is_month_end
+    is_quarter_start
+    is_quarter_end
+    is_year_start
+    is_year_end
+    is_leap_year
+    inferred_freq
+
+    Methods
+    -------
+    normalize
+    strftime
+    snap
+    tz_convert
+    tz_localize
+    round
+    floor
+    ceil
+    to_period
+    to_pydatetime
+    to_series
+    to_frame
+    month_name
+    day_name
+    mean
+    std
+
+    See Also
+    --------
+    Index : The base pandas Index type.
+    TimedeltaIndex : Index of timedelta64 data.
+    PeriodIndex : Index of Period data.
+    to_datetime : Convert argument to datetime.
+    date_range : Create a fixed-frequency DatetimeIndex.
+
+    Notes
+    -----
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    >>> idx = pd.DatetimeIndex(["1/1/2020 10:00:00+00:00", "2/1/2020 11:00:00+00:00"])
+    >>> idx
+    DatetimeIndex(['2020-01-01 10:00:00+00:00', '2020-02-01 11:00:00+00:00'],
+    dtype='datetime64[ns, UTC]', freq=None)
+    """
+
+    _typ = "datetimeindex"
+
+    _data_cls = DatetimeArray
+    _supports_partial_string_indexing = True
+
+    @property
+    def _engine_type(self) -> type[libindex.DatetimeEngine]:
+        return libindex.DatetimeEngine
+
+    _data: DatetimeArray
+    _values: DatetimeArray
+    tz: dt.tzinfo | None
+
+    # --------------------------------------------------------------------
+    # methods that dispatch to DatetimeArray and wrap result
+
+    @doc(DatetimeArray.strftime)
+    def strftime(self, date_format) -> Index:
+        arr = self._data.strftime(date_format)
+        return Index(arr, name=self.name, dtype=arr.dtype)
+
+    @doc(DatetimeArray.tz_convert)
+    def tz_convert(self, tz) -> Self:
+        arr = self._data.tz_convert(tz)
+        return type(self)._simple_new(arr, name=self.name, refs=self._references)
+
+    @doc(DatetimeArray.tz_localize)
+    def tz_localize(
+        self,
+        tz,
+        ambiguous: TimeAmbiguous = "raise",
+        nonexistent: TimeNonexistent = "raise",
+    ) -> Self:
+        arr = self._data.tz_localize(tz, ambiguous, nonexistent)
+        return type(self)._simple_new(arr, name=self.name)
+
+    @doc(DatetimeArray.to_period)
+    def to_period(self, freq=None) -> PeriodIndex:
+        from pandas.core.indexes.api import PeriodIndex
+
+        arr = self._data.to_period(freq)
+        return PeriodIndex._simple_new(arr, name=self.name)
+
+    @doc(DatetimeArray.to_julian_date)
+    def to_julian_date(self) -> Index:
+        arr = self._data.to_julian_date()
+        return Index._simple_new(arr, name=self.name)
+
+    @doc(DatetimeArray.isocalendar)
+    def isocalendar(self) -> DataFrame:
+        df = self._data.isocalendar()
+        return df.set_index(self)
+
+    @cache_readonly
+    def _resolution_obj(self) -> Resolution:
+        return self._data._resolution_obj
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data=None,
+        freq: Frequency | lib.NoDefault = lib.no_default,
+        tz=lib.no_default,
+        normalize: bool | lib.NoDefault = lib.no_default,
+        closed=lib.no_default,
+        ambiguous: TimeAmbiguous = "raise",
+        dayfirst: bool = False,
+        yearfirst: bool = False,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+    ) -> Self:
+        if closed is not lib.no_default:
+            # GH#52628
+            warnings.warn(
+                f"The 'closed' keyword in {cls.__name__} construction is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if normalize is not lib.no_default:
+            # GH#52628
+            warnings.warn(
+                f"The 'normalize' keyword in {cls.__name__} construction is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if is_scalar(data):
+            cls._raise_scalar_data_error(data)
+
+        # - Cases checked above all return/raise before reaching here - #
+
+        name = maybe_extract_name(name, data, cls)
+
+        if (
+            isinstance(data, DatetimeArray)
+            and freq is lib.no_default
+            and tz is lib.no_default
+            and dtype is None
+        ):
+            # fastpath, similar logic in TimedeltaIndex.__new__;
+            # Note in this particular case we retain non-nano.
+            if copy:
+                data = data.copy()
+            return cls._simple_new(data, name=name)
+
+        dtarr = DatetimeArray._from_sequence_not_strict(
+            data,
+            dtype=dtype,
+            copy=copy,
+            tz=tz,
+            freq=freq,
+            dayfirst=dayfirst,
+            yearfirst=yearfirst,
+            ambiguous=ambiguous,
+        )
+        refs = None
+        if not copy and isinstance(data, (Index, ABCSeries)):
+            refs = data._references
+
+        subarr = cls._simple_new(dtarr, name=name, refs=refs)
+        return subarr
+
+    # --------------------------------------------------------------------
+
+    @cache_readonly
+    def _is_dates_only(self) -> bool:
+        """
+        Return a boolean if we are only dates (and don't have a timezone)
+
+        Returns
+        -------
+        bool
+        """
+        if isinstance(self.freq, Tick):
+            delta = Timedelta(self.freq)
+
+            if delta % dt.timedelta(days=1) != dt.timedelta(days=0):
+                return False
+
+        return self._values._is_dates_only
+
+    def __reduce__(self):
+        d = {"data": self._data, "name": self.name}
+        return _new_DatetimeIndex, (type(self), d), None
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        """
+        Can we compare values of the given dtype to our own?
+        """
+        if self.tz is not None:
+            # If we have tz, we can compare to tzaware
+            return isinstance(dtype, DatetimeTZDtype)
+        # if we dont have tz, we can only compare to tznaive
+        return lib.is_np_dtype(dtype, "M")
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+
+    @cache_readonly
+    def _formatter_func(self):
+        # Note this is equivalent to the DatetimeIndexOpsMixin method but
+        #  uses the maybe-cached self._is_dates_only instead of re-computing it.
+        from pandas.io.formats.format import get_format_datetime64
+
+        formatter = get_format_datetime64(is_dates_only=self._is_dates_only)
+        return lambda x: f"'{formatter(x)}'"
+
+    # --------------------------------------------------------------------
+    # Set Operation Methods
+
+    def _can_range_setop(self, other) -> bool:
+        # GH 46702: If self or other have non-UTC tzs, DST transitions prevent
+        # range representation due to no singular step
+        if (
+            self.tz is not None
+            and not timezones.is_utc(self.tz)
+            and not timezones.is_fixed_offset(self.tz)
+        ):
+            return False
+        if (
+            other.tz is not None
+            and not timezones.is_utc(other.tz)
+            and not timezones.is_fixed_offset(other.tz)
+        ):
+            return False
+        return super()._can_range_setop(other)
+
+    # --------------------------------------------------------------------
+
+    def _get_time_micros(self) -> npt.NDArray[np.int64]:
+        """
+        Return the number of microseconds since midnight.
+
+        Returns
+        -------
+        ndarray[int64_t]
+        """
+        values = self._data._local_timestamps()
+
+        ppd = periods_per_day(self._data._creso)
+
+        frac = values % ppd
+        if self.unit == "ns":
+            micros = frac // 1000
+        elif self.unit == "us":
+            micros = frac
+        elif self.unit == "ms":
+            micros = frac * 1000
+        elif self.unit == "s":
+            micros = frac * 1_000_000
+        else:  # pragma: no cover
+            raise NotImplementedError(self.unit)
+
+        micros[self._isnan] = -1
+        return micros
+
+    def snap(self, freq: Frequency = "S") -> DatetimeIndex:
+        """
+        Snap time stamps to nearest occurring frequency.
+
+        Returns
+        -------
+        DatetimeIndex
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(['2023-01-01', '2023-01-02',
+        ...                        '2023-02-01', '2023-02-02'])
+        >>> idx
+        DatetimeIndex(['2023-01-01', '2023-01-02', '2023-02-01', '2023-02-02'],
+        dtype='datetime64[ns]', freq=None)
+        >>> idx.snap('MS')
+        DatetimeIndex(['2023-01-01', '2023-01-01', '2023-02-01', '2023-02-01'],
+        dtype='datetime64[ns]', freq=None)
+        """
+        # Superdumb, punting on any optimizing
+        freq = to_offset(freq)
+
+        dta = self._data.copy()
+
+        for i, v in enumerate(self):
+            s = v
+            if not freq.is_on_offset(s):
+                t0 = freq.rollback(s)
+                t1 = freq.rollforward(s)
+                if abs(s - t0) < abs(t1 - s):
+                    s = t0
+                else:
+                    s = t1
+            dta[i] = s
+
+        return DatetimeIndex._simple_new(dta, name=self.name)
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    def _parsed_string_to_bounds(self, reso: Resolution, parsed: dt.datetime):
+        """
+        Calculate datetime bounds for parsed time string and its resolution.
+
+        Parameters
+        ----------
+        reso : Resolution
+            Resolution provided by parsed string.
+        parsed : datetime
+            Datetime from parsed string.
+
+        Returns
+        -------
+        lower, upper: pd.Timestamp
+        """
+        freq = OFFSET_TO_PERIOD_FREQSTR.get(reso.attr_abbrev, reso.attr_abbrev)
+        per = Period(parsed, freq=freq)
+        start, end = per.start_time, per.end_time
+
+        # GH 24076
+        # If an incoming date string contained a UTC offset, need to localize
+        # the parsed date to this offset first before aligning with the index's
+        # timezone
+        start = start.tz_localize(parsed.tzinfo)
+        end = end.tz_localize(parsed.tzinfo)
+
+        if parsed.tzinfo is not None:
+            if self.tz is None:
+                raise ValueError(
+                    "The index must be timezone aware when indexing "
+                    "with a date string with a UTC offset"
+                )
+        # The flipped case with parsed.tz is None and self.tz is not None
+        #  is ruled out bc parsed and reso are produced by _parse_with_reso,
+        #  which localizes parsed.
+        return start, end
+
+    def _parse_with_reso(self, label: str):
+        parsed, reso = super()._parse_with_reso(label)
+
+        parsed = Timestamp(parsed)
+
+        if self.tz is not None and parsed.tzinfo is None:
+            # we special-case timezone-naive strings and timezone-aware
+            #  DatetimeIndex
+            # https://github.com/pandas-dev/pandas/pull/36148#issuecomment-687883081
+            parsed = parsed.tz_localize(self.tz)
+
+        return parsed, reso
+
+    def _disallow_mismatched_indexing(self, key) -> None:
+        """
+        Check for mismatched-tzawareness indexing and re-raise as KeyError.
+        """
+        # we get here with isinstance(key, self._data._recognized_scalars)
+        try:
+            # GH#36148
+            self._data._assert_tzawareness_compat(key)
+        except TypeError as err:
+            raise KeyError(key) from err
+
+    def get_loc(self, key):
+        """
+        Get integer location for requested label
+
+        Returns
+        -------
+        loc : int
+        """
+        self._check_indexing_error(key)
+
+        orig_key = key
+        if is_valid_na_for_dtype(key, self.dtype):
+            key = NaT
+
+        if isinstance(key, self._data._recognized_scalars):
+            # needed to localize naive datetimes
+            self._disallow_mismatched_indexing(key)
+            key = Timestamp(key)
+
+        elif isinstance(key, str):
+            try:
+                parsed, reso = self._parse_with_reso(key)
+            except (ValueError, pytz.NonExistentTimeError) as err:
+                raise KeyError(key) from err
+            self._disallow_mismatched_indexing(parsed)
+
+            if self._can_partial_date_slice(reso):
+                try:
+                    return self._partial_date_slice(reso, parsed)
+                except KeyError as err:
+                    raise KeyError(key) from err
+
+            key = parsed
+
+        elif isinstance(key, dt.timedelta):
+            # GH#20464
+            raise TypeError(
+                f"Cannot index {type(self).__name__} with {type(key).__name__}"
+            )
+
+        elif isinstance(key, dt.time):
+            return self.indexer_at_time(key)
+
+        else:
+            # unrecognized type
+            raise KeyError(key)
+
+        try:
+            return Index.get_loc(self, key)
+        except KeyError as err:
+            raise KeyError(orig_key) from err
+
+    @doc(DatetimeTimedeltaMixin._maybe_cast_slice_bound)
+    def _maybe_cast_slice_bound(self, label, side: str):
+        # GH#42855 handle date here instead of get_slice_bound
+        if isinstance(label, dt.date) and not isinstance(label, dt.datetime):
+            # Pandas supports slicing with dates, treated as datetimes at midnight.
+            # https://github.com/pandas-dev/pandas/issues/31501
+            label = Timestamp(label).to_pydatetime()
+
+        label = super()._maybe_cast_slice_bound(label, side)
+        self._data._assert_tzawareness_compat(label)
+        return Timestamp(label)
+
+    def slice_indexer(self, start=None, end=None, step=None):
+        """
+        Return indexer for specified label slice.
+        Index.slice_indexer, customized to handle time slicing.
+
+        In addition to functionality provided by Index.slice_indexer, does the
+        following:
+
+        - if both `start` and `end` are instances of `datetime.time`, it
+          invokes `indexer_between_time`
+        - if `start` and `end` are both either string or None perform
+          value-based selection in non-monotonic cases.
+
+        """
+        # For historical reasons DatetimeIndex supports slices between two
+        # instances of datetime.time as if it were applying a slice mask to
+        # an array of (self.hour, self.minute, self.seconds, self.microsecond).
+        if isinstance(start, dt.time) and isinstance(end, dt.time):
+            if step is not None and step != 1:
+                raise ValueError("Must have step size of 1 with time slices")
+            return self.indexer_between_time(start, end)
+
+        if isinstance(start, dt.time) or isinstance(end, dt.time):
+            raise KeyError("Cannot mix time and non-time slice keys")
+
+        def check_str_or_none(point) -> bool:
+            return point is not None and not isinstance(point, str)
+
+        # GH#33146 if start and end are combinations of str and None and Index is not
+        # monotonic, we can not use Index.slice_indexer because it does not honor the
+        # actual elements, is only searching for start and end
+        if (
+            check_str_or_none(start)
+            or check_str_or_none(end)
+            or self.is_monotonic_increasing
+        ):
+            return Index.slice_indexer(self, start, end, step)
+
+        mask = np.array(True)
+        in_index = True
+        if start is not None:
+            start_casted = self._maybe_cast_slice_bound(start, "left")
+            mask = start_casted <= self
+            in_index &= (start_casted == self).any()
+
+        if end is not None:
+            end_casted = self._maybe_cast_slice_bound(end, "right")
+            mask = (self <= end_casted) & mask
+            in_index &= (end_casted == self).any()
+
+        if not in_index:
+            raise KeyError(
+                "Value based partial slicing on non-monotonic DatetimeIndexes "
+                "with non-existing keys is not allowed.",
+            )
+        indexer = mask.nonzero()[0][::step]
+        if len(indexer) == len(self):
+            return slice(None)
+        else:
+            return indexer
+
+    # --------------------------------------------------------------------
+
+    @property
+    def inferred_type(self) -> str:
+        # b/c datetime is represented as microseconds since the epoch, make
+        # sure we can't have ambiguous indexing
+        return "datetime64"
+
+    def indexer_at_time(self, time, asof: bool = False) -> npt.NDArray[np.intp]:
+        """
+        Return index locations of values at particular time of day.
+
+        Parameters
+        ----------
+        time : datetime.time or str
+            Time passed in either as object (datetime.time) or as string in
+            appropriate format ("%H:%M", "%H%M", "%I:%M%p", "%I%M%p",
+            "%H:%M:%S", "%H%M%S", "%I:%M:%S%p", "%I%M%S%p").
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+
+        See Also
+        --------
+        indexer_between_time : Get index locations of values between particular
+            times of day.
+        DataFrame.at_time : Select values at particular time of day.
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(["1/1/2020 10:00", "2/1/2020 11:00",
+        ...                         "3/1/2020 10:00"])
+        >>> idx.indexer_at_time("10:00")
+        array([0, 2])
+        """
+        if asof:
+            raise NotImplementedError("'asof' argument is not supported")
+
+        if isinstance(time, str):
+            from dateutil.parser import parse
+
+            time = parse(time).time()
+
+        if time.tzinfo:
+            if self.tz is None:
+                raise ValueError("Index must be timezone aware.")
+            time_micros = self.tz_convert(time.tzinfo)._get_time_micros()
+        else:
+            time_micros = self._get_time_micros()
+        micros = _time_to_micros(time)
+        return (time_micros == micros).nonzero()[0]
+
+    def indexer_between_time(
+        self, start_time, end_time, include_start: bool = True, include_end: bool = True
+    ) -> npt.NDArray[np.intp]:
+        """
+        Return index locations of values between particular times of day.
+
+        Parameters
+        ----------
+        start_time, end_time : datetime.time, str
+            Time passed either as object (datetime.time) or as string in
+            appropriate format ("%H:%M", "%H%M", "%I:%M%p", "%I%M%p",
+            "%H:%M:%S", "%H%M%S", "%I:%M:%S%p","%I%M%S%p").
+        include_start : bool, default True
+        include_end : bool, default True
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+
+        See Also
+        --------
+        indexer_at_time : Get index locations of values at particular time of day.
+        DataFrame.between_time : Select values between particular times of day.
+
+        Examples
+        --------
+        >>> idx = pd.date_range("2023-01-01", periods=4, freq="h")
+        >>> idx
+        DatetimeIndex(['2023-01-01 00:00:00', '2023-01-01 01:00:00',
+                           '2023-01-01 02:00:00', '2023-01-01 03:00:00'],
+                          dtype='datetime64[ns]', freq='h')
+        >>> idx.indexer_between_time("00:00", "2:00", include_end=False)
+        array([0, 1])
+        """
+        start_time = to_time(start_time)
+        end_time = to_time(end_time)
+        time_micros = self._get_time_micros()
+        start_micros = _time_to_micros(start_time)
+        end_micros = _time_to_micros(end_time)
+
+        if include_start and include_end:
+            lop = rop = operator.le
+        elif include_start:
+            lop = operator.le
+            rop = operator.lt
+        elif include_end:
+            lop = operator.lt
+            rop = operator.le
+        else:
+            lop = rop = operator.lt
+
+        if start_time <= end_time:
+            join_op = operator.and_
+        else:
+            join_op = operator.or_
+
+        mask = join_op(lop(start_micros, time_micros), rop(time_micros, end_micros))
+
+        return mask.nonzero()[0]
+
+
+def date_range(
+    start=None,
+    end=None,
+    periods=None,
+    freq=None,
+    tz=None,
+    normalize: bool = False,
+    name: Hashable | None = None,
+    inclusive: IntervalClosedType = "both",
+    *,
+    unit: str | None = None,
+    **kwargs,
+) -> DatetimeIndex:
+    """
+    Return a fixed frequency DatetimeIndex.
+
+    Returns the range of equally spaced time points (where the difference between any
+    two adjacent points is specified by the given frequency) such that they all
+    satisfy `start <[=] x <[=] end`, where the first one and the last one are, resp.,
+    the first and last time points in that range that fall on the boundary of ``freq``
+    (if given as a frequency string) or that are valid for ``freq`` (if given as a
+    :class:`pandas.tseries.offsets.DateOffset`). (If exactly one of ``start``,
+    ``end``, or ``freq`` is *not* specified, this missing parameter can be computed
+    given ``periods``, the number of timesteps in the range. See the note below.)
+
+    Parameters
+    ----------
+    start : str or datetime-like, optional
+        Left bound for generating dates.
+    end : str or datetime-like, optional
+        Right bound for generating dates.
+    periods : int, optional
+        Number of periods to generate.
+    freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'D'
+        Frequency strings can have multiples, e.g. '5h'. See
+        :ref:`here ` for a list of
+        frequency aliases.
+    tz : str or tzinfo, optional
+        Time zone name for returning localized DatetimeIndex, for example
+        'Asia/Hong_Kong'. By default, the resulting DatetimeIndex is
+        timezone-naive unless timezone-aware datetime-likes are passed.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+    name : str, default None
+        Name of the resulting DatetimeIndex.
+    inclusive : {"both", "neither", "left", "right"}, default "both"
+        Include boundaries; Whether to set each bound as closed or open.
+
+        .. versionadded:: 1.4.0
+    unit : str, default None
+        Specify the desired resolution of the result.
+
+        .. versionadded:: 2.0.0
+    **kwargs
+        For compatibility. Has no effect on the result.
+
+    Returns
+    -------
+    DatetimeIndex
+
+    See Also
+    --------
+    DatetimeIndex : An immutable container for datetimes.
+    timedelta_range : Return a fixed frequency TimedeltaIndex.
+    period_range : Return a fixed frequency PeriodIndex.
+    interval_range : Return a fixed frequency IntervalIndex.
+
+    Notes
+    -----
+    Of the four parameters ``start``, ``end``, ``periods``, and ``freq``,
+    exactly three must be specified. If ``freq`` is omitted, the resulting
+    ``DatetimeIndex`` will have ``periods`` linearly spaced elements between
+    ``start`` and ``end`` (closed on both sides).
+
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    **Specifying the values**
+
+    The next four examples generate the same `DatetimeIndex`, but vary
+    the combination of `start`, `end` and `periods`.
+
+    Specify `start` and `end`, with the default daily frequency.
+
+    >>> pd.date_range(start='1/1/2018', end='1/08/2018')
+    DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',
+                   '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],
+                  dtype='datetime64[ns]', freq='D')
+
+    Specify timezone-aware `start` and `end`, with the default daily frequency.
+
+    >>> pd.date_range(
+    ...     start=pd.to_datetime("1/1/2018").tz_localize("Europe/Berlin"),
+    ...     end=pd.to_datetime("1/08/2018").tz_localize("Europe/Berlin"),
+    ... )
+    DatetimeIndex(['2018-01-01 00:00:00+01:00', '2018-01-02 00:00:00+01:00',
+                   '2018-01-03 00:00:00+01:00', '2018-01-04 00:00:00+01:00',
+                   '2018-01-05 00:00:00+01:00', '2018-01-06 00:00:00+01:00',
+                   '2018-01-07 00:00:00+01:00', '2018-01-08 00:00:00+01:00'],
+                  dtype='datetime64[ns, Europe/Berlin]', freq='D')
+
+    Specify `start` and `periods`, the number of periods (days).
+
+    >>> pd.date_range(start='1/1/2018', periods=8)
+    DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',
+                   '2018-01-05', '2018-01-06', '2018-01-07', '2018-01-08'],
+                  dtype='datetime64[ns]', freq='D')
+
+    Specify `end` and `periods`, the number of periods (days).
+
+    >>> pd.date_range(end='1/1/2018', periods=8)
+    DatetimeIndex(['2017-12-25', '2017-12-26', '2017-12-27', '2017-12-28',
+                   '2017-12-29', '2017-12-30', '2017-12-31', '2018-01-01'],
+                  dtype='datetime64[ns]', freq='D')
+
+    Specify `start`, `end`, and `periods`; the frequency is generated
+    automatically (linearly spaced).
+
+    >>> pd.date_range(start='2018-04-24', end='2018-04-27', periods=3)
+    DatetimeIndex(['2018-04-24 00:00:00', '2018-04-25 12:00:00',
+                   '2018-04-27 00:00:00'],
+                  dtype='datetime64[ns]', freq=None)
+
+    **Other Parameters**
+
+    Changed the `freq` (frequency) to ``'ME'`` (month end frequency).
+
+    >>> pd.date_range(start='1/1/2018', periods=5, freq='ME')
+    DatetimeIndex(['2018-01-31', '2018-02-28', '2018-03-31', '2018-04-30',
+                   '2018-05-31'],
+                  dtype='datetime64[ns]', freq='ME')
+
+    Multiples are allowed
+
+    >>> pd.date_range(start='1/1/2018', periods=5, freq='3ME')
+    DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',
+                   '2019-01-31'],
+                  dtype='datetime64[ns]', freq='3ME')
+
+    `freq` can also be specified as an Offset object.
+
+    >>> pd.date_range(start='1/1/2018', periods=5, freq=pd.offsets.MonthEnd(3))
+    DatetimeIndex(['2018-01-31', '2018-04-30', '2018-07-31', '2018-10-31',
+                   '2019-01-31'],
+                  dtype='datetime64[ns]', freq='3ME')
+
+    Specify `tz` to set the timezone.
+
+    >>> pd.date_range(start='1/1/2018', periods=5, tz='Asia/Tokyo')
+    DatetimeIndex(['2018-01-01 00:00:00+09:00', '2018-01-02 00:00:00+09:00',
+                   '2018-01-03 00:00:00+09:00', '2018-01-04 00:00:00+09:00',
+                   '2018-01-05 00:00:00+09:00'],
+                  dtype='datetime64[ns, Asia/Tokyo]', freq='D')
+
+    `inclusive` controls whether to include `start` and `end` that are on the
+    boundary. The default, "both", includes boundary points on either end.
+
+    >>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive="both")
+    DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03', '2017-01-04'],
+                  dtype='datetime64[ns]', freq='D')
+
+    Use ``inclusive='left'`` to exclude `end` if it falls on the boundary.
+
+    >>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive='left')
+    DatetimeIndex(['2017-01-01', '2017-01-02', '2017-01-03'],
+                  dtype='datetime64[ns]', freq='D')
+
+    Use ``inclusive='right'`` to exclude `start` if it falls on the boundary, and
+    similarly ``inclusive='neither'`` will exclude both `start` and `end`.
+
+    >>> pd.date_range(start='2017-01-01', end='2017-01-04', inclusive='right')
+    DatetimeIndex(['2017-01-02', '2017-01-03', '2017-01-04'],
+                  dtype='datetime64[ns]', freq='D')
+
+    **Specify a unit**
+
+    >>> pd.date_range(start="2017-01-01", periods=10, freq="100YS", unit="s")
+    DatetimeIndex(['2017-01-01', '2117-01-01', '2217-01-01', '2317-01-01',
+                   '2417-01-01', '2517-01-01', '2617-01-01', '2717-01-01',
+                   '2817-01-01', '2917-01-01'],
+                  dtype='datetime64[s]', freq='100YS-JAN')
+    """
+    if freq is None and com.any_none(periods, start, end):
+        freq = "D"
+
+    dtarr = DatetimeArray._generate_range(
+        start=start,
+        end=end,
+        periods=periods,
+        freq=freq,
+        tz=tz,
+        normalize=normalize,
+        inclusive=inclusive,
+        unit=unit,
+        **kwargs,
+    )
+    return DatetimeIndex._simple_new(dtarr, name=name)
+
+
+def bdate_range(
+    start=None,
+    end=None,
+    periods: int | None = None,
+    freq: Frequency | dt.timedelta = "B",
+    tz=None,
+    normalize: bool = True,
+    name: Hashable | None = None,
+    weekmask=None,
+    holidays=None,
+    inclusive: IntervalClosedType = "both",
+    **kwargs,
+) -> DatetimeIndex:
+    """
+    Return a fixed frequency DatetimeIndex with business day as the default.
+
+    Parameters
+    ----------
+    start : str or datetime-like, default None
+        Left bound for generating dates.
+    end : str or datetime-like, default None
+        Right bound for generating dates.
+    periods : int, default None
+        Number of periods to generate.
+    freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'B'
+        Frequency strings can have multiples, e.g. '5h'. The default is
+        business daily ('B').
+    tz : str or None
+        Time zone name for returning localized DatetimeIndex, for example
+        Asia/Beijing.
+    normalize : bool, default False
+        Normalize start/end dates to midnight before generating date range.
+    name : str, default None
+        Name of the resulting DatetimeIndex.
+    weekmask : str or None, default None
+        Weekmask of valid business days, passed to ``numpy.busdaycalendar``,
+        only used when custom frequency strings are passed.  The default
+        value None is equivalent to 'Mon Tue Wed Thu Fri'.
+    holidays : list-like or None, default None
+        Dates to exclude from the set of valid business days, passed to
+        ``numpy.busdaycalendar``, only used when custom frequency strings
+        are passed.
+    inclusive : {"both", "neither", "left", "right"}, default "both"
+        Include boundaries; Whether to set each bound as closed or open.
+
+        .. versionadded:: 1.4.0
+    **kwargs
+        For compatibility. Has no effect on the result.
+
+    Returns
+    -------
+    DatetimeIndex
+
+    Notes
+    -----
+    Of the four parameters: ``start``, ``end``, ``periods``, and ``freq``,
+    exactly three must be specified.  Specifying ``freq`` is a requirement
+    for ``bdate_range``.  Use ``date_range`` if specifying ``freq`` is not
+    desired.
+
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    Note how the two weekend days are skipped in the result.
+
+    >>> pd.bdate_range(start='1/1/2018', end='1/08/2018')
+    DatetimeIndex(['2018-01-01', '2018-01-02', '2018-01-03', '2018-01-04',
+               '2018-01-05', '2018-01-08'],
+              dtype='datetime64[ns]', freq='B')
+    """
+    if freq is None:
+        msg = "freq must be specified for bdate_range; use date_range instead"
+        raise TypeError(msg)
+
+    if isinstance(freq, str) and freq.startswith("C"):
+        try:
+            weekmask = weekmask or "Mon Tue Wed Thu Fri"
+            freq = prefix_mapping[freq](holidays=holidays, weekmask=weekmask)
+        except (KeyError, TypeError) as err:
+            msg = f"invalid custom frequency string: {freq}"
+            raise ValueError(msg) from err
+    elif holidays or weekmask:
+        msg = (
+            "a custom frequency string is required when holidays or "
+            f"weekmask are passed, got frequency {freq}"
+        )
+        raise ValueError(msg)
+
+    return date_range(
+        start=start,
+        end=end,
+        periods=periods,
+        freq=freq,
+        tz=tz,
+        normalize=normalize,
+        name=name,
+        inclusive=inclusive,
+        **kwargs,
+    )
+
+
+def _time_to_micros(time_obj: dt.time) -> int:
+    seconds = time_obj.hour * 60 * 60 + 60 * time_obj.minute + time_obj.second
+    return 1_000_000 * seconds + time_obj.microsecond
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/extension.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/extension.py
new file mode 100644
index 0000000000000000000000000000000000000000..371d3c811e772ba10af5071e6cc9cb97ba9f3f58
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/extension.py
@@ -0,0 +1,172 @@
+"""
+Shared methods for Index subclasses backed by ExtensionArray.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    TypeVar,
+)
+
+from pandas.util._decorators import cache_readonly
+
+from pandas.core.dtypes.generic import ABCDataFrame
+
+from pandas.core.indexes.base import Index
+
+if TYPE_CHECKING:
+    import numpy as np
+
+    from pandas._typing import (
+        ArrayLike,
+        npt,
+    )
+
+    from pandas.core.arrays import IntervalArray
+    from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+
+_ExtensionIndexT = TypeVar("_ExtensionIndexT", bound="ExtensionIndex")
+
+
+def _inherit_from_data(
+    name: str, delegate: type, cache: bool = False, wrap: bool = False
+):
+    """
+    Make an alias for a method of the underlying ExtensionArray.
+
+    Parameters
+    ----------
+    name : str
+        Name of an attribute the class should inherit from its EA parent.
+    delegate : class
+    cache : bool, default False
+        Whether to convert wrapped properties into cache_readonly
+    wrap : bool, default False
+        Whether to wrap the inherited result in an Index.
+
+    Returns
+    -------
+    attribute, method, property, or cache_readonly
+    """
+    attr = getattr(delegate, name)
+
+    if isinstance(attr, property) or type(attr).__name__ == "getset_descriptor":
+        # getset_descriptor i.e. property defined in cython class
+        if cache:
+
+            def cached(self):
+                return getattr(self._data, name)
+
+            cached.__name__ = name
+            cached.__doc__ = attr.__doc__
+            method = cache_readonly(cached)
+
+        else:
+
+            def fget(self):
+                result = getattr(self._data, name)
+                if wrap:
+                    if isinstance(result, type(self._data)):
+                        return type(self)._simple_new(result, name=self.name)
+                    elif isinstance(result, ABCDataFrame):
+                        return result.set_index(self)
+                    return Index(result, name=self.name, dtype=result.dtype)
+                return result
+
+            def fset(self, value) -> None:
+                setattr(self._data, name, value)
+
+            fget.__name__ = name
+            fget.__doc__ = attr.__doc__
+
+            method = property(fget, fset)
+
+    elif not callable(attr):
+        # just a normal attribute, no wrapping
+        method = attr
+
+    else:
+        # error: Incompatible redefinition (redefinition with type "Callable[[Any,
+        # VarArg(Any), KwArg(Any)], Any]", original type "property")
+        def method(self, *args, **kwargs):  # type: ignore[misc]
+            if "inplace" in kwargs:
+                raise ValueError(f"cannot use inplace with {type(self).__name__}")
+            result = attr(self._data, *args, **kwargs)
+            if wrap:
+                if isinstance(result, type(self._data)):
+                    return type(self)._simple_new(result, name=self.name)
+                elif isinstance(result, ABCDataFrame):
+                    return result.set_index(self)
+                return Index(result, name=self.name, dtype=result.dtype)
+            return result
+
+        # error: "property" has no attribute "__name__"
+        method.__name__ = name  # type: ignore[attr-defined]
+        method.__doc__ = attr.__doc__
+    return method
+
+
+def inherit_names(
+    names: list[str], delegate: type, cache: bool = False, wrap: bool = False
+) -> Callable[[type[_ExtensionIndexT]], type[_ExtensionIndexT]]:
+    """
+    Class decorator to pin attributes from an ExtensionArray to a Index subclass.
+
+    Parameters
+    ----------
+    names : List[str]
+    delegate : class
+    cache : bool, default False
+    wrap : bool, default False
+        Whether to wrap the inherited result in an Index.
+    """
+
+    def wrapper(cls: type[_ExtensionIndexT]) -> type[_ExtensionIndexT]:
+        for name in names:
+            meth = _inherit_from_data(name, delegate, cache=cache, wrap=wrap)
+            setattr(cls, name, meth)
+
+        return cls
+
+    return wrapper
+
+
+class ExtensionIndex(Index):
+    """
+    Index subclass for indexes backed by ExtensionArray.
+    """
+
+    # The base class already passes through to _data:
+    #  size, __len__, dtype
+
+    _data: IntervalArray | NDArrayBackedExtensionArray
+
+    # ---------------------------------------------------------------------
+
+    def _validate_fill_value(self, value):
+        """
+        Convert value to be insertable to underlying array.
+        """
+        return self._data._validate_setitem_value(value)
+
+    @cache_readonly
+    def _isnan(self) -> npt.NDArray[np.bool_]:
+        # error: Incompatible return value type (got "ExtensionArray", expected
+        # "ndarray")
+        return self._data.isna()  # type: ignore[return-value]
+
+
+class NDArrayBackedExtensionIndex(ExtensionIndex):
+    """
+    Index subclass for indexes backed by NDArrayBackedExtensionArray.
+    """
+
+    _data: NDArrayBackedExtensionArray
+
+    def _get_engine_target(self) -> np.ndarray:
+        return self._data._ndarray
+
+    def _from_join_target(self, result: np.ndarray) -> ArrayLike:
+        assert result.dtype == self._data._ndarray.dtype
+        return self._data._from_backing_data(result)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/frozen.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/frozen.py
new file mode 100644
index 0000000000000000000000000000000000000000..9d528d34e36845efd44126c087cd15cd81e1e02e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/frozen.py
@@ -0,0 +1,120 @@
+"""
+frozen (immutable) data structures to support MultiIndexing
+
+These are used for:
+
+- .names (FrozenList)
+
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    NoReturn,
+)
+
+from pandas.core.base import PandasObject
+
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from pandas._typing import Self
+
+
+class FrozenList(PandasObject, list):
+    """
+    Container that doesn't allow setting item *but*
+    because it's technically hashable, will be used
+    for lookups, appropriately, etc.
+    """
+
+    # Side note: This has to be of type list. Otherwise,
+    #            it messes up PyTables type checks.
+
+    def union(self, other) -> FrozenList:
+        """
+        Returns a FrozenList with other concatenated to the end of self.
+
+        Parameters
+        ----------
+        other : array-like
+            The array-like whose elements we are concatenating.
+
+        Returns
+        -------
+        FrozenList
+            The collection difference between self and other.
+        """
+        if isinstance(other, tuple):
+            other = list(other)
+        return type(self)(super().__add__(other))
+
+    def difference(self, other) -> FrozenList:
+        """
+        Returns a FrozenList with elements from other removed from self.
+
+        Parameters
+        ----------
+        other : array-like
+            The array-like whose elements we are removing self.
+
+        Returns
+        -------
+        FrozenList
+            The collection difference between self and other.
+        """
+        other = set(other)
+        temp = [x for x in self if x not in other]
+        return type(self)(temp)
+
+    # TODO: Consider deprecating these in favor of `union` (xref gh-15506)
+    # error: Incompatible types in assignment (expression has type
+    # "Callable[[FrozenList, Any], FrozenList]", base class "list" defined the
+    # type as overloaded function)
+    __add__ = __iadd__ = union  # type: ignore[assignment]
+
+    def __getitem__(self, n):
+        if isinstance(n, slice):
+            return type(self)(super().__getitem__(n))
+        return super().__getitem__(n)
+
+    def __radd__(self, other) -> Self:
+        if isinstance(other, tuple):
+            other = list(other)
+        return type(self)(other + list(self))
+
+    def __eq__(self, other: object) -> bool:
+        if isinstance(other, (tuple, FrozenList)):
+            other = list(other)
+        return super().__eq__(other)
+
+    __req__ = __eq__
+
+    def __mul__(self, other) -> Self:
+        return type(self)(super().__mul__(other))
+
+    __imul__ = __mul__
+
+    def __reduce__(self):
+        return type(self), (list(self),)
+
+    # error: Signature of "__hash__" incompatible with supertype "list"
+    def __hash__(self) -> int:  # type: ignore[override]
+        return hash(tuple(self))
+
+    def _disabled(self, *args, **kwargs) -> NoReturn:
+        """
+        This method will not function because object is immutable.
+        """
+        raise TypeError(f"'{type(self).__name__}' does not support mutable operations.")
+
+    def __str__(self) -> str:
+        return pprint_thing(self, quote_strings=True, escape_chars=("\t", "\r", "\n"))
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({str(self)})"
+
+    __setitem__ = __setslice__ = _disabled  # type: ignore[assignment]
+    __delitem__ = __delslice__ = _disabled
+    pop = append = extend = _disabled
+    remove = sort = insert = _disabled  # type: ignore[assignment]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/interval.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/interval.py
new file mode 100644
index 0000000000000000000000000000000000000000..635924674d9f4aec5537f77e5fbcf5e81180e2d4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/interval.py
@@ -0,0 +1,1137 @@
+""" define the IntervalIndex """
+from __future__ import annotations
+
+from operator import (
+    le,
+    lt,
+)
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.interval import (
+    Interval,
+    IntervalMixin,
+    IntervalTree,
+)
+from pandas._libs.tslibs import (
+    BaseOffset,
+    Period,
+    Timedelta,
+    Timestamp,
+    to_offset,
+)
+from pandas.errors import InvalidIndexError
+from pandas.util._decorators import (
+    Appender,
+    cache_readonly,
+)
+from pandas.util._exceptions import rewrite_exception
+
+from pandas.core.dtypes.cast import (
+    find_common_type,
+    infer_dtype_from_scalar,
+    maybe_box_datetimelike,
+    maybe_downcast_numeric,
+    maybe_upcast_numeric_to_64bit,
+)
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_float_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_number,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    IntervalDtype,
+)
+from pandas.core.dtypes.missing import is_valid_na_for_dtype
+
+from pandas.core.algorithms import unique
+from pandas.core.arrays.datetimelike import validate_periods
+from pandas.core.arrays.interval import (
+    IntervalArray,
+    _interval_shared_docs,
+)
+import pandas.core.common as com
+from pandas.core.indexers import is_valid_positional_slice
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.base import (
+    Index,
+    _index_shared_docs,
+    ensure_index,
+    maybe_extract_name,
+)
+from pandas.core.indexes.datetimes import (
+    DatetimeIndex,
+    date_range,
+)
+from pandas.core.indexes.extension import (
+    ExtensionIndex,
+    inherit_names,
+)
+from pandas.core.indexes.multi import MultiIndex
+from pandas.core.indexes.timedeltas import (
+    TimedeltaIndex,
+    timedelta_range,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        IntervalClosedType,
+        Self,
+        npt,
+    )
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+
+_index_doc_kwargs.update(
+    {
+        "klass": "IntervalIndex",
+        "qualname": "IntervalIndex",
+        "target_klass": "IntervalIndex or list of Intervals",
+        "name": textwrap.dedent(
+            """\
+         name : object, optional
+              Name to be stored in the index.
+         """
+        ),
+    }
+)
+
+
+def _get_next_label(label):
+    # see test_slice_locs_with_ints_and_floats_succeeds
+    dtype = getattr(label, "dtype", type(label))
+    if isinstance(label, (Timestamp, Timedelta)):
+        dtype = "datetime64[ns]"
+    dtype = pandas_dtype(dtype)
+
+    if lib.is_np_dtype(dtype, "mM") or isinstance(dtype, DatetimeTZDtype):
+        return label + np.timedelta64(1, "ns")
+    elif is_integer_dtype(dtype):
+        return label + 1
+    elif is_float_dtype(dtype):
+        return np.nextafter(label, np.inf)
+    else:
+        raise TypeError(f"cannot determine next label for type {repr(type(label))}")
+
+
+def _get_prev_label(label):
+    # see test_slice_locs_with_ints_and_floats_succeeds
+    dtype = getattr(label, "dtype", type(label))
+    if isinstance(label, (Timestamp, Timedelta)):
+        dtype = "datetime64[ns]"
+    dtype = pandas_dtype(dtype)
+
+    if lib.is_np_dtype(dtype, "mM") or isinstance(dtype, DatetimeTZDtype):
+        return label - np.timedelta64(1, "ns")
+    elif is_integer_dtype(dtype):
+        return label - 1
+    elif is_float_dtype(dtype):
+        return np.nextafter(label, -np.inf)
+    else:
+        raise TypeError(f"cannot determine next label for type {repr(type(label))}")
+
+
+def _new_IntervalIndex(cls, d):
+    """
+    This is called upon unpickling, rather than the default which doesn't have
+    arguments and breaks __new__.
+    """
+    return cls.from_arrays(**d)
+
+
+@Appender(
+    _interval_shared_docs["class"]
+    % {
+        "klass": "IntervalIndex",
+        "summary": "Immutable index of intervals that are closed on the same side.",
+        "name": _index_doc_kwargs["name"],
+        "extra_attributes": "is_overlapping\nvalues\n",
+        "extra_methods": "",
+        "examples": textwrap.dedent(
+            """\
+    Examples
+    --------
+    A new ``IntervalIndex`` is typically constructed using
+    :func:`interval_range`:
+
+    >>> pd.interval_range(start=0, end=5)
+    IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]],
+                  dtype='interval[int64, right]')
+
+    It may also be constructed using one of the constructor
+    methods: :meth:`IntervalIndex.from_arrays`,
+    :meth:`IntervalIndex.from_breaks`, and :meth:`IntervalIndex.from_tuples`.
+
+    See further examples in the doc strings of ``interval_range`` and the
+    mentioned constructor methods.
+    """
+        ),
+    }
+)
+@inherit_names(["set_closed", "to_tuples"], IntervalArray, wrap=True)
+@inherit_names(
+    [
+        "__array__",
+        "overlaps",
+        "contains",
+        "closed_left",
+        "closed_right",
+        "open_left",
+        "open_right",
+        "is_empty",
+    ],
+    IntervalArray,
+)
+@inherit_names(["is_non_overlapping_monotonic", "closed"], IntervalArray, cache=True)
+class IntervalIndex(ExtensionIndex):
+    _typ = "intervalindex"
+
+    # annotate properties pinned via inherit_names
+    closed: IntervalClosedType
+    is_non_overlapping_monotonic: bool
+    closed_left: bool
+    closed_right: bool
+    open_left: bool
+    open_right: bool
+
+    _data: IntervalArray
+    _values: IntervalArray
+    _can_hold_strings = False
+    _data_cls = IntervalArray
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data,
+        closed: IntervalClosedType | None = None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+        verify_integrity: bool = True,
+    ) -> Self:
+        name = maybe_extract_name(name, data, cls)
+
+        with rewrite_exception("IntervalArray", cls.__name__):
+            array = IntervalArray(
+                data,
+                closed=closed,
+                copy=copy,
+                dtype=dtype,
+                verify_integrity=verify_integrity,
+            )
+
+        return cls._simple_new(array, name)
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_breaks"]
+        % {
+            "klass": "IntervalIndex",
+            "name": textwrap.dedent(
+                """
+             name : str, optional
+                  Name of the resulting IntervalIndex."""
+            ),
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_breaks([0, 1, 2, 3])
+        IntervalIndex([(0, 1], (1, 2], (2, 3]],
+                      dtype='interval[int64, right]')
+        """
+            ),
+        }
+    )
+    def from_breaks(
+        cls,
+        breaks,
+        closed: IntervalClosedType | None = "right",
+        name: Hashable | None = None,
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> IntervalIndex:
+        with rewrite_exception("IntervalArray", cls.__name__):
+            array = IntervalArray.from_breaks(
+                breaks, closed=closed, copy=copy, dtype=dtype
+            )
+        return cls._simple_new(array, name=name)
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_arrays"]
+        % {
+            "klass": "IntervalIndex",
+            "name": textwrap.dedent(
+                """
+             name : str, optional
+                  Name of the resulting IntervalIndex."""
+            ),
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_arrays([0, 1, 2], [1, 2, 3])
+        IntervalIndex([(0, 1], (1, 2], (2, 3]],
+                      dtype='interval[int64, right]')
+        """
+            ),
+        }
+    )
+    def from_arrays(
+        cls,
+        left,
+        right,
+        closed: IntervalClosedType = "right",
+        name: Hashable | None = None,
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> IntervalIndex:
+        with rewrite_exception("IntervalArray", cls.__name__):
+            array = IntervalArray.from_arrays(
+                left, right, closed, copy=copy, dtype=dtype
+            )
+        return cls._simple_new(array, name=name)
+
+    @classmethod
+    @Appender(
+        _interval_shared_docs["from_tuples"]
+        % {
+            "klass": "IntervalIndex",
+            "name": textwrap.dedent(
+                """
+             name : str, optional
+                  Name of the resulting IntervalIndex."""
+            ),
+            "examples": textwrap.dedent(
+                """\
+        Examples
+        --------
+        >>> pd.IntervalIndex.from_tuples([(0, 1), (1, 2)])
+        IntervalIndex([(0, 1], (1, 2]],
+                       dtype='interval[int64, right]')
+        """
+            ),
+        }
+    )
+    def from_tuples(
+        cls,
+        data,
+        closed: IntervalClosedType = "right",
+        name: Hashable | None = None,
+        copy: bool = False,
+        dtype: Dtype | None = None,
+    ) -> IntervalIndex:
+        with rewrite_exception("IntervalArray", cls.__name__):
+            arr = IntervalArray.from_tuples(data, closed=closed, copy=copy, dtype=dtype)
+        return cls._simple_new(arr, name=name)
+
+    # --------------------------------------------------------------------
+    # error: Return type "IntervalTree" of "_engine" incompatible with return type
+    # "Union[IndexEngine, ExtensionEngine]" in supertype "Index"
+    @cache_readonly
+    def _engine(self) -> IntervalTree:  # type: ignore[override]
+        # IntervalTree does not supports numpy array unless they are 64 bit
+        left = self._maybe_convert_i8(self.left)
+        left = maybe_upcast_numeric_to_64bit(left)
+        right = self._maybe_convert_i8(self.right)
+        right = maybe_upcast_numeric_to_64bit(right)
+        return IntervalTree(left, right, closed=self.closed)
+
+    def __contains__(self, key: Any) -> bool:
+        """
+        return a boolean if this key is IN the index
+        We *only* accept an Interval
+
+        Parameters
+        ----------
+        key : Interval
+
+        Returns
+        -------
+        bool
+        """
+        hash(key)
+        if not isinstance(key, Interval):
+            if is_valid_na_for_dtype(key, self.dtype):
+                return self.hasnans
+            return False
+
+        try:
+            self.get_loc(key)
+            return True
+        except KeyError:
+            return False
+
+    def _getitem_slice(self, slobj: slice) -> IntervalIndex:
+        """
+        Fastpath for __getitem__ when we know we have a slice.
+        """
+        res = self._data[slobj]
+        return type(self)._simple_new(res, name=self._name)
+
+    @cache_readonly
+    def _multiindex(self) -> MultiIndex:
+        return MultiIndex.from_arrays([self.left, self.right], names=["left", "right"])
+
+    def __reduce__(self):
+        d = {
+            "left": self.left,
+            "right": self.right,
+            "closed": self.closed,
+            "name": self.name,
+        }
+        return _new_IntervalIndex, (type(self), d), None
+
+    @property
+    def inferred_type(self) -> str:
+        """Return a string of the type inferred from the values"""
+        return "interval"
+
+    # Cannot determine type of "memory_usage"
+    @Appender(Index.memory_usage.__doc__)  # type: ignore[has-type]
+    def memory_usage(self, deep: bool = False) -> int:
+        # we don't use an explicit engine
+        # so return the bytes here
+        return self.left.memory_usage(deep=deep) + self.right.memory_usage(deep=deep)
+
+    # IntervalTree doesn't have a is_monotonic_decreasing, so have to override
+    #  the Index implementation
+    @cache_readonly
+    def is_monotonic_decreasing(self) -> bool:
+        """
+        Return True if the IntervalIndex is monotonic decreasing (only equal or
+        decreasing values), else False
+        """
+        return self[::-1].is_monotonic_increasing
+
+    @cache_readonly
+    def is_unique(self) -> bool:
+        """
+        Return True if the IntervalIndex contains unique elements, else False.
+        """
+        left = self.left
+        right = self.right
+
+        if self.isna().sum() > 1:
+            return False
+
+        if left.is_unique or right.is_unique:
+            return True
+
+        seen_pairs = set()
+        check_idx = np.where(left.duplicated(keep=False))[0]
+        for idx in check_idx:
+            pair = (left[idx], right[idx])
+            if pair in seen_pairs:
+                return False
+            seen_pairs.add(pair)
+
+        return True
+
+    @property
+    def is_overlapping(self) -> bool:
+        """
+        Return True if the IntervalIndex has overlapping intervals, else False.
+
+        Two intervals overlap if they share a common point, including closed
+        endpoints. Intervals that only have an open endpoint in common do not
+        overlap.
+
+        Returns
+        -------
+        bool
+            Boolean indicating if the IntervalIndex has overlapping intervals.
+
+        See Also
+        --------
+        Interval.overlaps : Check whether two Interval objects overlap.
+        IntervalIndex.overlaps : Check an IntervalIndex elementwise for
+            overlaps.
+
+        Examples
+        --------
+        >>> index = pd.IntervalIndex.from_tuples([(0, 2), (1, 3), (4, 5)])
+        >>> index
+        IntervalIndex([(0, 2], (1, 3], (4, 5]],
+              dtype='interval[int64, right]')
+        >>> index.is_overlapping
+        True
+
+        Intervals that share closed endpoints overlap:
+
+        >>> index = pd.interval_range(0, 3, closed='both')
+        >>> index
+        IntervalIndex([[0, 1], [1, 2], [2, 3]],
+              dtype='interval[int64, both]')
+        >>> index.is_overlapping
+        True
+
+        Intervals that only have an open endpoint in common do not overlap:
+
+        >>> index = pd.interval_range(0, 3, closed='left')
+        >>> index
+        IntervalIndex([[0, 1), [1, 2), [2, 3)],
+              dtype='interval[int64, left]')
+        >>> index.is_overlapping
+        False
+        """
+        # GH 23309
+        return self._engine.is_overlapping
+
+    def _needs_i8_conversion(self, key) -> bool:
+        """
+        Check if a given key needs i8 conversion. Conversion is necessary for
+        Timestamp, Timedelta, DatetimeIndex, and TimedeltaIndex keys. An
+        Interval-like requires conversion if its endpoints are one of the
+        aforementioned types.
+
+        Assumes that any list-like data has already been cast to an Index.
+
+        Parameters
+        ----------
+        key : scalar or Index-like
+            The key that should be checked for i8 conversion
+
+        Returns
+        -------
+        bool
+        """
+        key_dtype = getattr(key, "dtype", None)
+        if isinstance(key_dtype, IntervalDtype) or isinstance(key, Interval):
+            return self._needs_i8_conversion(key.left)
+
+        i8_types = (Timestamp, Timedelta, DatetimeIndex, TimedeltaIndex)
+        return isinstance(key, i8_types)
+
+    def _maybe_convert_i8(self, key):
+        """
+        Maybe convert a given key to its equivalent i8 value(s). Used as a
+        preprocessing step prior to IntervalTree queries (self._engine), which
+        expects numeric data.
+
+        Parameters
+        ----------
+        key : scalar or list-like
+            The key that should maybe be converted to i8.
+
+        Returns
+        -------
+        scalar or list-like
+            The original key if no conversion occurred, int if converted scalar,
+            Index with an int64 dtype if converted list-like.
+        """
+        if is_list_like(key):
+            key = ensure_index(key)
+            key = maybe_upcast_numeric_to_64bit(key)
+
+        if not self._needs_i8_conversion(key):
+            return key
+
+        scalar = is_scalar(key)
+        key_dtype = getattr(key, "dtype", None)
+        if isinstance(key_dtype, IntervalDtype) or isinstance(key, Interval):
+            # convert left/right and reconstruct
+            left = self._maybe_convert_i8(key.left)
+            right = self._maybe_convert_i8(key.right)
+            constructor = Interval if scalar else IntervalIndex.from_arrays
+            # error: "object" not callable
+            return constructor(
+                left, right, closed=self.closed
+            )  # type: ignore[operator]
+
+        if scalar:
+            # Timestamp/Timedelta
+            key_dtype, key_i8 = infer_dtype_from_scalar(key)
+            if isinstance(key, Period):
+                key_i8 = key.ordinal
+            elif isinstance(key_i8, Timestamp):
+                key_i8 = key_i8._value
+            elif isinstance(key_i8, (np.datetime64, np.timedelta64)):
+                key_i8 = key_i8.view("i8")
+        else:
+            # DatetimeIndex/TimedeltaIndex
+            key_dtype, key_i8 = key.dtype, Index(key.asi8)
+            if key.hasnans:
+                # convert NaT from its i8 value to np.nan so it's not viewed
+                # as a valid value, maybe causing errors (e.g. is_overlapping)
+                key_i8 = key_i8.where(~key._isnan)
+
+        # ensure consistency with IntervalIndex subtype
+        # error: Item "ExtensionDtype"/"dtype[Any]" of "Union[dtype[Any],
+        # ExtensionDtype]" has no attribute "subtype"
+        subtype = self.dtype.subtype  # type: ignore[union-attr]
+
+        if subtype != key_dtype:
+            raise ValueError(
+                f"Cannot index an IntervalIndex of subtype {subtype} with "
+                f"values of dtype {key_dtype}"
+            )
+
+        return key_i8
+
+    def _searchsorted_monotonic(self, label, side: Literal["left", "right"] = "left"):
+        if not self.is_non_overlapping_monotonic:
+            raise KeyError(
+                "can only get slices from an IntervalIndex if bounds are "
+                "non-overlapping and all monotonic increasing or decreasing"
+            )
+
+        if isinstance(label, (IntervalMixin, IntervalIndex)):
+            raise NotImplementedError("Interval objects are not currently supported")
+
+        # GH 20921: "not is_monotonic_increasing" for the second condition
+        # instead of "is_monotonic_decreasing" to account for single element
+        # indexes being both increasing and decreasing
+        if (side == "left" and self.left.is_monotonic_increasing) or (
+            side == "right" and not self.left.is_monotonic_increasing
+        ):
+            sub_idx = self.right
+            if self.open_right:
+                label = _get_next_label(label)
+        else:
+            sub_idx = self.left
+            if self.open_left:
+                label = _get_prev_label(label)
+
+        return sub_idx._searchsorted_monotonic(label, side)
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    def get_loc(self, key) -> int | slice | np.ndarray:
+        """
+        Get integer location, slice or boolean mask for requested label.
+
+        Parameters
+        ----------
+        key : label
+
+        Returns
+        -------
+        int if unique index, slice if monotonic index, else mask
+
+        Examples
+        --------
+        >>> i1, i2 = pd.Interval(0, 1), pd.Interval(1, 2)
+        >>> index = pd.IntervalIndex([i1, i2])
+        >>> index.get_loc(1)
+        0
+
+        You can also supply a point inside an interval.
+
+        >>> index.get_loc(1.5)
+        1
+
+        If a label is in several intervals, you get the locations of all the
+        relevant intervals.
+
+        >>> i3 = pd.Interval(0, 2)
+        >>> overlapping_index = pd.IntervalIndex([i1, i2, i3])
+        >>> overlapping_index.get_loc(0.5)
+        array([ True, False,  True])
+
+        Only exact matches will be returned if an interval is provided.
+
+        >>> index.get_loc(pd.Interval(0, 1))
+        0
+        """
+        self._check_indexing_error(key)
+
+        if isinstance(key, Interval):
+            if self.closed != key.closed:
+                raise KeyError(key)
+            mask = (self.left == key.left) & (self.right == key.right)
+        elif is_valid_na_for_dtype(key, self.dtype):
+            mask = self.isna()
+        else:
+            # assume scalar
+            op_left = le if self.closed_left else lt
+            op_right = le if self.closed_right else lt
+            try:
+                mask = op_left(self.left, key) & op_right(key, self.right)
+            except TypeError as err:
+                # scalar is not comparable to II subtype --> invalid label
+                raise KeyError(key) from err
+
+        matches = mask.sum()
+        if matches == 0:
+            raise KeyError(key)
+        if matches == 1:
+            return mask.argmax()
+
+        res = lib.maybe_booleans_to_slice(mask.view("u1"))
+        if isinstance(res, slice) and res.stop is None:
+            # TODO: DO this in maybe_booleans_to_slice?
+            res = slice(res.start, len(self), res.step)
+        return res
+
+    def _get_indexer(
+        self,
+        target: Index,
+        method: str | None = None,
+        limit: int | None = None,
+        tolerance: Any | None = None,
+    ) -> npt.NDArray[np.intp]:
+        if isinstance(target, IntervalIndex):
+            # We only get here with not self.is_overlapping
+            # -> at most one match per interval in target
+            # want exact matches -> need both left/right to match, so defer to
+            # left/right get_indexer, compare elementwise, equality -> match
+            indexer = self._get_indexer_unique_sides(target)
+
+        elif not (is_object_dtype(target.dtype) or is_string_dtype(target.dtype)):
+            # homogeneous scalar index: use IntervalTree
+            # we should always have self._should_partial_index(target) here
+            target = self._maybe_convert_i8(target)
+            indexer = self._engine.get_indexer(target.values)
+        else:
+            # heterogeneous scalar index: defer elementwise to get_loc
+            # we should always have self._should_partial_index(target) here
+            return self._get_indexer_pointwise(target)[0]
+
+        return ensure_platform_int(indexer)
+
+    @Appender(_index_shared_docs["get_indexer_non_unique"] % _index_doc_kwargs)
+    def get_indexer_non_unique(
+        self, target: Index
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        target = ensure_index(target)
+
+        if not self._should_compare(target) and not self._should_partial_index(target):
+            # e.g. IntervalIndex with different closed or incompatible subtype
+            #  -> no matches
+            return self._get_indexer_non_comparable(target, None, unique=False)
+
+        elif isinstance(target, IntervalIndex):
+            if self.left.is_unique and self.right.is_unique:
+                # fastpath available even if we don't have self._index_as_unique
+                indexer = self._get_indexer_unique_sides(target)
+                missing = (indexer == -1).nonzero()[0]
+            else:
+                return self._get_indexer_pointwise(target)
+
+        elif is_object_dtype(target.dtype) or not self._should_partial_index(target):
+            # target might contain intervals: defer elementwise to get_loc
+            return self._get_indexer_pointwise(target)
+
+        else:
+            # Note: this case behaves differently from other Index subclasses
+            #  because IntervalIndex does partial-int indexing
+            target = self._maybe_convert_i8(target)
+            indexer, missing = self._engine.get_indexer_non_unique(target.values)
+
+        return ensure_platform_int(indexer), ensure_platform_int(missing)
+
+    def _get_indexer_unique_sides(self, target: IntervalIndex) -> npt.NDArray[np.intp]:
+        """
+        _get_indexer specialized to the case where both of our sides are unique.
+        """
+        # Caller is responsible for checking
+        #  `self.left.is_unique and self.right.is_unique`
+
+        left_indexer = self.left.get_indexer(target.left)
+        right_indexer = self.right.get_indexer(target.right)
+        indexer = np.where(left_indexer == right_indexer, left_indexer, -1)
+        return indexer
+
+    def _get_indexer_pointwise(
+        self, target: Index
+    ) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        """
+        pointwise implementation for get_indexer and get_indexer_non_unique.
+        """
+        indexer, missing = [], []
+        for i, key in enumerate(target):
+            try:
+                locs = self.get_loc(key)
+                if isinstance(locs, slice):
+                    # Only needed for get_indexer_non_unique
+                    locs = np.arange(locs.start, locs.stop, locs.step, dtype="intp")
+                elif lib.is_integer(locs):
+                    locs = np.array(locs, ndmin=1)
+                else:
+                    # otherwise we have ndarray[bool]
+                    locs = np.where(locs)[0]
+            except KeyError:
+                missing.append(i)
+                locs = np.array([-1])
+            except InvalidIndexError:
+                # i.e. non-scalar key e.g. a tuple.
+                # see test_append_different_columns_types_raises
+                missing.append(i)
+                locs = np.array([-1])
+
+            indexer.append(locs)
+
+        indexer = np.concatenate(indexer)
+        return ensure_platform_int(indexer), ensure_platform_int(missing)
+
+    @cache_readonly
+    def _index_as_unique(self) -> bool:
+        return not self.is_overlapping and self._engine._na_count < 2
+
+    _requires_unique_msg = (
+        "cannot handle overlapping indices; use IntervalIndex.get_indexer_non_unique"
+    )
+
+    def _convert_slice_indexer(self, key: slice, kind: Literal["loc", "getitem"]):
+        if not (key.step is None or key.step == 1):
+            # GH#31658 if label-based, we require step == 1,
+            #  if positional, we disallow float start/stop
+            msg = "label-based slicing with step!=1 is not supported for IntervalIndex"
+            if kind == "loc":
+                raise ValueError(msg)
+            if kind == "getitem":
+                if not is_valid_positional_slice(key):
+                    # i.e. this cannot be interpreted as a positional slice
+                    raise ValueError(msg)
+
+        return super()._convert_slice_indexer(key, kind)
+
+    @cache_readonly
+    def _should_fallback_to_positional(self) -> bool:
+        # integer lookups in Series.__getitem__ are unambiguously
+        #  positional in this case
+        # error: Item "ExtensionDtype"/"dtype[Any]" of "Union[dtype[Any],
+        # ExtensionDtype]" has no attribute "subtype"
+        return self.dtype.subtype.kind in "mM"  # type: ignore[union-attr]
+
+    def _maybe_cast_slice_bound(self, label, side: str):
+        return getattr(self, side)._maybe_cast_slice_bound(label, side)
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        if not isinstance(dtype, IntervalDtype):
+            return False
+        common_subtype = find_common_type([self.dtype, dtype])
+        return not is_object_dtype(common_subtype)
+
+    # --------------------------------------------------------------------
+
+    @cache_readonly
+    def left(self) -> Index:
+        return Index(self._data.left, copy=False)
+
+    @cache_readonly
+    def right(self) -> Index:
+        return Index(self._data.right, copy=False)
+
+    @cache_readonly
+    def mid(self) -> Index:
+        return Index(self._data.mid, copy=False)
+
+    @property
+    def length(self) -> Index:
+        return Index(self._data.length, copy=False)
+
+    # --------------------------------------------------------------------
+    # Set Operations
+
+    def _intersection(self, other, sort):
+        """
+        intersection specialized to the case with matching dtypes.
+        """
+        # For IntervalIndex we also know other.closed == self.closed
+        if self.left.is_unique and self.right.is_unique:
+            taken = self._intersection_unique(other)
+        elif other.left.is_unique and other.right.is_unique and self.isna().sum() <= 1:
+            # Swap other/self if other is unique and self does not have
+            # multiple NaNs
+            taken = other._intersection_unique(self)
+        else:
+            # duplicates
+            taken = self._intersection_non_unique(other)
+
+        if sort is None:
+            taken = taken.sort_values()
+
+        return taken
+
+    def _intersection_unique(self, other: IntervalIndex) -> IntervalIndex:
+        """
+        Used when the IntervalIndex does not have any common endpoint,
+        no matter left or right.
+        Return the intersection with another IntervalIndex.
+        Parameters
+        ----------
+        other : IntervalIndex
+        Returns
+        -------
+        IntervalIndex
+        """
+        # Note: this is much more performant than super()._intersection(other)
+        lindexer = self.left.get_indexer(other.left)
+        rindexer = self.right.get_indexer(other.right)
+
+        match = (lindexer == rindexer) & (lindexer != -1)
+        indexer = lindexer.take(match.nonzero()[0])
+        indexer = unique(indexer)
+
+        return self.take(indexer)
+
+    def _intersection_non_unique(self, other: IntervalIndex) -> IntervalIndex:
+        """
+        Used when the IntervalIndex does have some common endpoints,
+        on either sides.
+        Return the intersection with another IntervalIndex.
+
+        Parameters
+        ----------
+        other : IntervalIndex
+
+        Returns
+        -------
+        IntervalIndex
+        """
+        # Note: this is about 3.25x faster than super()._intersection(other)
+        #  in IntervalIndexMethod.time_intersection_both_duplicate(1000)
+        mask = np.zeros(len(self), dtype=bool)
+
+        if self.hasnans and other.hasnans:
+            first_nan_loc = np.arange(len(self))[self.isna()][0]
+            mask[first_nan_loc] = True
+
+        other_tups = set(zip(other.left, other.right))
+        for i, tup in enumerate(zip(self.left, self.right)):
+            if tup in other_tups:
+                mask[i] = True
+
+        return self[mask]
+
+    # --------------------------------------------------------------------
+
+    def _get_engine_target(self) -> np.ndarray:
+        # Note: we _could_ use libjoin functions by either casting to object
+        #  dtype or constructing tuples (faster than constructing Intervals)
+        #  but the libjoin fastpaths are no longer fast in these cases.
+        raise NotImplementedError(
+            "IntervalIndex does not use libjoin fastpaths or pass values to "
+            "IndexEngine objects"
+        )
+
+    def _from_join_target(self, result):
+        raise NotImplementedError("IntervalIndex does not use libjoin fastpaths")
+
+    # TODO: arithmetic operations
+
+
+def _is_valid_endpoint(endpoint) -> bool:
+    """
+    Helper for interval_range to check if start/end are valid types.
+    """
+    return any(
+        [
+            is_number(endpoint),
+            isinstance(endpoint, Timestamp),
+            isinstance(endpoint, Timedelta),
+            endpoint is None,
+        ]
+    )
+
+
+def _is_type_compatible(a, b) -> bool:
+    """
+    Helper for interval_range to check type compat of start/end/freq.
+    """
+    is_ts_compat = lambda x: isinstance(x, (Timestamp, BaseOffset))
+    is_td_compat = lambda x: isinstance(x, (Timedelta, BaseOffset))
+    return (
+        (is_number(a) and is_number(b))
+        or (is_ts_compat(a) and is_ts_compat(b))
+        or (is_td_compat(a) and is_td_compat(b))
+        or com.any_none(a, b)
+    )
+
+
+def interval_range(
+    start=None,
+    end=None,
+    periods=None,
+    freq=None,
+    name: Hashable | None = None,
+    closed: IntervalClosedType = "right",
+) -> IntervalIndex:
+    """
+    Return a fixed frequency IntervalIndex.
+
+    Parameters
+    ----------
+    start : numeric or datetime-like, default None
+        Left bound for generating intervals.
+    end : numeric or datetime-like, default None
+        Right bound for generating intervals.
+    periods : int, default None
+        Number of periods to generate.
+    freq : numeric, str, Timedelta, datetime.timedelta, or DateOffset, default None
+        The length of each interval. Must be consistent with the type of start
+        and end, e.g. 2 for numeric, or '5H' for datetime-like.  Default is 1
+        for numeric and 'D' for datetime-like.
+    name : str, default None
+        Name of the resulting IntervalIndex.
+    closed : {'left', 'right', 'both', 'neither'}, default 'right'
+        Whether the intervals are closed on the left-side, right-side, both
+        or neither.
+
+    Returns
+    -------
+    IntervalIndex
+
+    See Also
+    --------
+    IntervalIndex : An Index of intervals that are all closed on the same side.
+
+    Notes
+    -----
+    Of the four parameters ``start``, ``end``, ``periods``, and ``freq``,
+    exactly three must be specified. If ``freq`` is omitted, the resulting
+    ``IntervalIndex`` will have ``periods`` linearly spaced elements between
+    ``start`` and ``end``, inclusively.
+
+    To learn more about datetime-like frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    Numeric ``start`` and  ``end`` is supported.
+
+    >>> pd.interval_range(start=0, end=5)
+    IntervalIndex([(0, 1], (1, 2], (2, 3], (3, 4], (4, 5]],
+                  dtype='interval[int64, right]')
+
+    Additionally, datetime-like input is also supported.
+
+    >>> pd.interval_range(start=pd.Timestamp('2017-01-01'),
+    ...                   end=pd.Timestamp('2017-01-04'))
+    IntervalIndex([(2017-01-01 00:00:00, 2017-01-02 00:00:00],
+                   (2017-01-02 00:00:00, 2017-01-03 00:00:00],
+                   (2017-01-03 00:00:00, 2017-01-04 00:00:00]],
+                  dtype='interval[datetime64[ns], right]')
+
+    The ``freq`` parameter specifies the frequency between the left and right.
+    endpoints of the individual intervals within the ``IntervalIndex``.  For
+    numeric ``start`` and ``end``, the frequency must also be numeric.
+
+    >>> pd.interval_range(start=0, periods=4, freq=1.5)
+    IntervalIndex([(0.0, 1.5], (1.5, 3.0], (3.0, 4.5], (4.5, 6.0]],
+                  dtype='interval[float64, right]')
+
+    Similarly, for datetime-like ``start`` and ``end``, the frequency must be
+    convertible to a DateOffset.
+
+    >>> pd.interval_range(start=pd.Timestamp('2017-01-01'),
+    ...                   periods=3, freq='MS')
+    IntervalIndex([(2017-01-01 00:00:00, 2017-02-01 00:00:00],
+                   (2017-02-01 00:00:00, 2017-03-01 00:00:00],
+                   (2017-03-01 00:00:00, 2017-04-01 00:00:00]],
+                  dtype='interval[datetime64[ns], right]')
+
+    Specify ``start``, ``end``, and ``periods``; the frequency is generated
+    automatically (linearly spaced).
+
+    >>> pd.interval_range(start=0, end=6, periods=4)
+    IntervalIndex([(0.0, 1.5], (1.5, 3.0], (3.0, 4.5], (4.5, 6.0]],
+              dtype='interval[float64, right]')
+
+    The ``closed`` parameter specifies which endpoints of the individual
+    intervals within the ``IntervalIndex`` are closed.
+
+    >>> pd.interval_range(end=5, periods=4, closed='both')
+    IntervalIndex([[1, 2], [2, 3], [3, 4], [4, 5]],
+                  dtype='interval[int64, both]')
+    """
+    start = maybe_box_datetimelike(start)
+    end = maybe_box_datetimelike(end)
+    endpoint = start if start is not None else end
+
+    if freq is None and com.any_none(periods, start, end):
+        freq = 1 if is_number(endpoint) else "D"
+
+    if com.count_not_none(start, end, periods, freq) != 3:
+        raise ValueError(
+            "Of the four parameters: start, end, periods, and "
+            "freq, exactly three must be specified"
+        )
+
+    if not _is_valid_endpoint(start):
+        raise ValueError(f"start must be numeric or datetime-like, got {start}")
+    if not _is_valid_endpoint(end):
+        raise ValueError(f"end must be numeric or datetime-like, got {end}")
+
+    periods = validate_periods(periods)
+
+    if freq is not None and not is_number(freq):
+        try:
+            freq = to_offset(freq)
+        except ValueError as err:
+            raise ValueError(
+                f"freq must be numeric or convertible to DateOffset, got {freq}"
+            ) from err
+
+    # verify type compatibility
+    if not all(
+        [
+            _is_type_compatible(start, end),
+            _is_type_compatible(start, freq),
+            _is_type_compatible(end, freq),
+        ]
+    ):
+        raise TypeError("start, end, freq need to be type compatible")
+
+    # +1 to convert interval count to breaks count (n breaks = n-1 intervals)
+    if periods is not None:
+        periods += 1
+
+    breaks: np.ndarray | TimedeltaIndex | DatetimeIndex
+
+    if is_number(endpoint):
+        if com.all_not_none(start, end, freq):
+            # 0.1 ensures we capture end
+            breaks = np.arange(start, end + (freq * 0.1), freq)
+        else:
+            # compute the period/start/end if unspecified (at most one)
+            if periods is None:
+                periods = int((end - start) // freq) + 1
+            elif start is None:
+                start = end - (periods - 1) * freq
+            elif end is None:
+                end = start + (periods - 1) * freq
+
+            breaks = np.linspace(start, end, periods)
+        if all(is_integer(x) for x in com.not_none(start, end, freq)):
+            # np.linspace always produces float output
+
+            # error: Argument 1 to "maybe_downcast_numeric" has incompatible type
+            # "Union[ndarray[Any, Any], TimedeltaIndex, DatetimeIndex]";
+            # expected "ndarray[Any, Any]"  [
+            breaks = maybe_downcast_numeric(
+                breaks,  # type: ignore[arg-type]
+                np.dtype("int64"),
+            )
+    else:
+        # delegate to the appropriate range function
+        if isinstance(endpoint, Timestamp):
+            breaks = date_range(start=start, end=end, periods=periods, freq=freq)
+        else:
+            breaks = timedelta_range(start=start, end=end, periods=periods, freq=freq)
+
+    return IntervalIndex.from_breaks(breaks, name=name, closed=closed)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/multi.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/multi.py
new file mode 100644
index 0000000000000000000000000000000000000000..8954d49649a2b132927980f5874a9006a65301f4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/multi.py
@@ -0,0 +1,4176 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Collection,
+    Generator,
+    Hashable,
+    Iterable,
+    Sequence,
+)
+from functools import wraps
+from sys import getsizeof
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs import (
+    algos as libalgos,
+    index as libindex,
+    lib,
+)
+from pandas._libs.hashtable import duplicated
+from pandas._typing import (
+    AnyAll,
+    AnyArrayLike,
+    Axis,
+    DropKeep,
+    DtypeObj,
+    F,
+    IgnoreRaise,
+    IndexLabel,
+    Scalar,
+    Self,
+    Shape,
+    npt,
+)
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    InvalidIndexError,
+    PerformanceWarning,
+    UnsortedIndexError,
+)
+from pandas.util._decorators import (
+    Appender,
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import coerce_indexer_dtype
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    ensure_platform_int,
+    is_hashable,
+    is_integer,
+    is_iterator,
+    is_list_like,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import is_array_like
+from pandas.core.dtypes.missing import (
+    array_equivalent,
+    isna,
+)
+
+import pandas.core.algorithms as algos
+from pandas.core.array_algos.putmask import validate_putmask
+from pandas.core.arrays import (
+    Categorical,
+    ExtensionArray,
+)
+from pandas.core.arrays.categorical import (
+    factorize_from_iterables,
+    recode_for_categories,
+)
+import pandas.core.common as com
+from pandas.core.construction import sanitize_array
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.base import (
+    Index,
+    _index_shared_docs,
+    ensure_index,
+    get_unanimous_names,
+)
+from pandas.core.indexes.frozen import FrozenList
+from pandas.core.ops.invalid import make_invalid_op
+from pandas.core.sorting import (
+    get_group_index,
+    lexsort_indexer,
+)
+
+from pandas.io.formats.printing import (
+    get_adjustment,
+    pprint_thing,
+)
+
+if TYPE_CHECKING:
+    from pandas import (
+        CategoricalIndex,
+        DataFrame,
+        Series,
+    )
+
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+_index_doc_kwargs.update(
+    {"klass": "MultiIndex", "target_klass": "MultiIndex or list of tuples"}
+)
+
+
+class MultiIndexUIntEngine(libindex.BaseMultiIndexCodesEngine, libindex.UInt64Engine):
+    """
+    This class manages a MultiIndex by mapping label combinations to positive
+    integers.
+    """
+
+    _base = libindex.UInt64Engine
+
+    def _codes_to_ints(self, codes):
+        """
+        Transform combination(s) of uint64 in one uint64 (each), in a strictly
+        monotonic way (i.e. respecting the lexicographic order of integer
+        combinations): see BaseMultiIndexCodesEngine documentation.
+
+        Parameters
+        ----------
+        codes : 1- or 2-dimensional array of dtype uint64
+            Combinations of integers (one per row)
+
+        Returns
+        -------
+        scalar or 1-dimensional array, of dtype uint64
+            Integer(s) representing one combination (each).
+        """
+        # Shift the representation of each level by the pre-calculated number
+        # of bits:
+        codes <<= self.offsets
+
+        # Now sum and OR are in fact interchangeable. This is a simple
+        # composition of the (disjunct) significant bits of each level (i.e.
+        # each column in "codes") in a single positive integer:
+        if codes.ndim == 1:
+            # Single key
+            return np.bitwise_or.reduce(codes)
+
+        # Multiple keys
+        return np.bitwise_or.reduce(codes, axis=1)
+
+
+class MultiIndexPyIntEngine(libindex.BaseMultiIndexCodesEngine, libindex.ObjectEngine):
+    """
+    This class manages those (extreme) cases in which the number of possible
+    label combinations overflows the 64 bits integers, and uses an ObjectEngine
+    containing Python integers.
+    """
+
+    _base = libindex.ObjectEngine
+
+    def _codes_to_ints(self, codes):
+        """
+        Transform combination(s) of uint64 in one Python integer (each), in a
+        strictly monotonic way (i.e. respecting the lexicographic order of
+        integer combinations): see BaseMultiIndexCodesEngine documentation.
+
+        Parameters
+        ----------
+        codes : 1- or 2-dimensional array of dtype uint64
+            Combinations of integers (one per row)
+
+        Returns
+        -------
+        int, or 1-dimensional array of dtype object
+            Integer(s) representing one combination (each).
+        """
+        # Shift the representation of each level by the pre-calculated number
+        # of bits. Since this can overflow uint64, first make sure we are
+        # working with Python integers:
+        codes = codes.astype("object") << self.offsets
+
+        # Now sum and OR are in fact interchangeable. This is a simple
+        # composition of the (disjunct) significant bits of each level (i.e.
+        # each column in "codes") in a single positive integer (per row):
+        if codes.ndim == 1:
+            # Single key
+            return np.bitwise_or.reduce(codes)
+
+        # Multiple keys
+        return np.bitwise_or.reduce(codes, axis=1)
+
+
+def names_compat(meth: F) -> F:
+    """
+    A decorator to allow either `name` or `names` keyword but not both.
+
+    This makes it easier to share code with base class.
+    """
+
+    @wraps(meth)
+    def new_meth(self_or_cls, *args, **kwargs):
+        if "name" in kwargs and "names" in kwargs:
+            raise TypeError("Can only provide one of `names` and `name`")
+        if "name" in kwargs:
+            kwargs["names"] = kwargs.pop("name")
+
+        return meth(self_or_cls, *args, **kwargs)
+
+    return cast(F, new_meth)
+
+
+class MultiIndex(Index):
+    """
+    A multi-level, or hierarchical, index object for pandas objects.
+
+    Parameters
+    ----------
+    levels : sequence of arrays
+        The unique labels for each level.
+    codes : sequence of arrays
+        Integers for each level designating which label at each location.
+    sortorder : optional int
+        Level of sortedness (must be lexicographically sorted by that
+        level).
+    names : optional sequence of objects
+        Names for each of the index levels. (name is accepted for compat).
+    copy : bool, default False
+        Copy the meta-data.
+    verify_integrity : bool, default True
+        Check that the levels/codes are consistent and valid.
+
+    Attributes
+    ----------
+    names
+    levels
+    codes
+    nlevels
+    levshape
+    dtypes
+
+    Methods
+    -------
+    from_arrays
+    from_tuples
+    from_product
+    from_frame
+    set_levels
+    set_codes
+    to_frame
+    to_flat_index
+    sortlevel
+    droplevel
+    swaplevel
+    reorder_levels
+    remove_unused_levels
+    get_level_values
+    get_indexer
+    get_loc
+    get_locs
+    get_loc_level
+    drop
+
+    See Also
+    --------
+    MultiIndex.from_arrays  : Convert list of arrays to MultiIndex.
+    MultiIndex.from_product : Create a MultiIndex from the cartesian product
+                              of iterables.
+    MultiIndex.from_tuples  : Convert list of tuples to a MultiIndex.
+    MultiIndex.from_frame   : Make a MultiIndex from a DataFrame.
+    Index : The base pandas Index type.
+
+    Notes
+    -----
+    See the `user guide
+    `__
+    for more.
+
+    Examples
+    --------
+    A new ``MultiIndex`` is typically constructed using one of the helper
+    methods :meth:`MultiIndex.from_arrays`, :meth:`MultiIndex.from_product`
+    and :meth:`MultiIndex.from_tuples`. For example (using ``.from_arrays``):
+
+    >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
+    >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color'))
+    MultiIndex([(1,  'red'),
+                (1, 'blue'),
+                (2,  'red'),
+                (2, 'blue')],
+               names=['number', 'color'])
+
+    See further examples for how to construct a MultiIndex in the doc strings
+    of the mentioned helper methods.
+    """
+
+    _hidden_attrs = Index._hidden_attrs | frozenset()
+
+    # initialize to zero-length tuples to make everything work
+    _typ = "multiindex"
+    _names: list[Hashable | None] = []
+    _levels = FrozenList()
+    _codes = FrozenList()
+    _comparables = ["names"]
+
+    sortorder: int | None
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        levels=None,
+        codes=None,
+        sortorder=None,
+        names=None,
+        dtype=None,
+        copy: bool = False,
+        name=None,
+        verify_integrity: bool = True,
+    ) -> Self:
+        # compat with Index
+        if name is not None:
+            names = name
+        if levels is None or codes is None:
+            raise TypeError("Must pass both levels and codes")
+        if len(levels) != len(codes):
+            raise ValueError("Length of levels and codes must be the same.")
+        if len(levels) == 0:
+            raise ValueError("Must pass non-zero number of levels/codes")
+
+        result = object.__new__(cls)
+        result._cache = {}
+
+        # we've already validated levels and codes, so shortcut here
+        result._set_levels(levels, copy=copy, validate=False)
+        result._set_codes(codes, copy=copy, validate=False)
+
+        result._names = [None] * len(levels)
+        if names is not None:
+            # handles name validation
+            result._set_names(names)
+
+        if sortorder is not None:
+            result.sortorder = int(sortorder)
+        else:
+            result.sortorder = sortorder
+
+        if verify_integrity:
+            new_codes = result._verify_integrity()
+            result._codes = new_codes
+
+        result._reset_identity()
+        result._references = None
+
+        return result
+
+    def _validate_codes(self, level: list, code: list):
+        """
+        Reassign code values as -1 if their corresponding levels are NaN.
+
+        Parameters
+        ----------
+        code : list
+            Code to reassign.
+        level : list
+            Level to check for missing values (NaN, NaT, None).
+
+        Returns
+        -------
+        new code where code value = -1 if it corresponds
+        to a level with missing values (NaN, NaT, None).
+        """
+        null_mask = isna(level)
+        if np.any(null_mask):
+            # error: Incompatible types in assignment
+            # (expression has type "ndarray[Any, dtype[Any]]",
+            # variable has type "List[Any]")
+            code = np.where(null_mask[code], -1, code)  # type: ignore[assignment]
+        return code
+
+    def _verify_integrity(
+        self,
+        codes: list | None = None,
+        levels: list | None = None,
+        levels_to_verify: list[int] | range | None = None,
+    ):
+        """
+        Parameters
+        ----------
+        codes : optional list
+            Codes to check for validity. Defaults to current codes.
+        levels : optional list
+            Levels to check for validity. Defaults to current levels.
+        levels_to_validate: optional list
+            Specifies the levels to verify.
+
+        Raises
+        ------
+        ValueError
+            If length of levels and codes don't match, if the codes for any
+            level would exceed level bounds, or there are any duplicate levels.
+
+        Returns
+        -------
+        new codes where code value = -1 if it corresponds to a
+        NaN level.
+        """
+        # NOTE: Currently does not check, among other things, that cached
+        # nlevels matches nor that sortorder matches actually sortorder.
+        codes = codes or self.codes
+        levels = levels or self.levels
+        if levels_to_verify is None:
+            levels_to_verify = range(len(levels))
+
+        if len(levels) != len(codes):
+            raise ValueError(
+                "Length of levels and codes must match. NOTE: "
+                "this index is in an inconsistent state."
+            )
+        codes_length = len(codes[0])
+        for i in levels_to_verify:
+            level = levels[i]
+            level_codes = codes[i]
+
+            if len(level_codes) != codes_length:
+                raise ValueError(
+                    f"Unequal code lengths: {[len(code_) for code_ in codes]}"
+                )
+            if len(level_codes) and level_codes.max() >= len(level):
+                raise ValueError(
+                    f"On level {i}, code max ({level_codes.max()}) >= length of "
+                    f"level ({len(level)}). NOTE: this index is in an "
+                    "inconsistent state"
+                )
+            if len(level_codes) and level_codes.min() < -1:
+                raise ValueError(f"On level {i}, code value ({level_codes.min()}) < -1")
+            if not level.is_unique:
+                raise ValueError(
+                    f"Level values must be unique: {list(level)} on level {i}"
+                )
+        if self.sortorder is not None:
+            if self.sortorder > _lexsort_depth(self.codes, self.nlevels):
+                raise ValueError(
+                    "Value for sortorder must be inferior or equal to actual "
+                    f"lexsort_depth: sortorder {self.sortorder} "
+                    f"with lexsort_depth {_lexsort_depth(self.codes, self.nlevels)}"
+                )
+
+        result_codes = []
+        for i in range(len(levels)):
+            if i in levels_to_verify:
+                result_codes.append(self._validate_codes(levels[i], codes[i]))
+            else:
+                result_codes.append(codes[i])
+
+        new_codes = FrozenList(result_codes)
+        return new_codes
+
+    @classmethod
+    def from_arrays(
+        cls,
+        arrays,
+        sortorder: int | None = None,
+        names: Sequence[Hashable] | Hashable | lib.NoDefault = lib.no_default,
+    ) -> MultiIndex:
+        """
+        Convert arrays to MultiIndex.
+
+        Parameters
+        ----------
+        arrays : list / sequence of array-likes
+            Each array-like gives one level's value for each data point.
+            len(arrays) is the number of levels.
+        sortorder : int or None
+            Level of sortedness (must be lexicographically sorted by that
+            level).
+        names : list / sequence of str, optional
+            Names for the levels in the index.
+
+        Returns
+        -------
+        MultiIndex
+
+        See Also
+        --------
+        MultiIndex.from_tuples : Convert list of tuples to MultiIndex.
+        MultiIndex.from_product : Make a MultiIndex from cartesian product
+                                  of iterables.
+        MultiIndex.from_frame : Make a MultiIndex from a DataFrame.
+
+        Examples
+        --------
+        >>> arrays = [[1, 1, 2, 2], ['red', 'blue', 'red', 'blue']]
+        >>> pd.MultiIndex.from_arrays(arrays, names=('number', 'color'))
+        MultiIndex([(1,  'red'),
+                    (1, 'blue'),
+                    (2,  'red'),
+                    (2, 'blue')],
+                   names=['number', 'color'])
+        """
+        error_msg = "Input must be a list / sequence of array-likes."
+        if not is_list_like(arrays):
+            raise TypeError(error_msg)
+        if is_iterator(arrays):
+            arrays = list(arrays)
+
+        # Check if elements of array are list-like
+        for array in arrays:
+            if not is_list_like(array):
+                raise TypeError(error_msg)
+
+        # Check if lengths of all arrays are equal or not,
+        # raise ValueError, if not
+        for i in range(1, len(arrays)):
+            if len(arrays[i]) != len(arrays[i - 1]):
+                raise ValueError("all arrays must be same length")
+
+        codes, levels = factorize_from_iterables(arrays)
+        if names is lib.no_default:
+            names = [getattr(arr, "name", None) for arr in arrays]
+
+        return cls(
+            levels=levels,
+            codes=codes,
+            sortorder=sortorder,
+            names=names,
+            verify_integrity=False,
+        )
+
+    @classmethod
+    @names_compat
+    def from_tuples(
+        cls,
+        tuples: Iterable[tuple[Hashable, ...]],
+        sortorder: int | None = None,
+        names: Sequence[Hashable] | Hashable | None = None,
+    ) -> MultiIndex:
+        """
+        Convert list of tuples to MultiIndex.
+
+        Parameters
+        ----------
+        tuples : list / sequence of tuple-likes
+            Each tuple is the index of one row/column.
+        sortorder : int or None
+            Level of sortedness (must be lexicographically sorted by that
+            level).
+        names : list / sequence of str, optional
+            Names for the levels in the index.
+
+        Returns
+        -------
+        MultiIndex
+
+        See Also
+        --------
+        MultiIndex.from_arrays : Convert list of arrays to MultiIndex.
+        MultiIndex.from_product : Make a MultiIndex from cartesian product
+                                  of iterables.
+        MultiIndex.from_frame : Make a MultiIndex from a DataFrame.
+
+        Examples
+        --------
+        >>> tuples = [(1, 'red'), (1, 'blue'),
+        ...           (2, 'red'), (2, 'blue')]
+        >>> pd.MultiIndex.from_tuples(tuples, names=('number', 'color'))
+        MultiIndex([(1,  'red'),
+                    (1, 'blue'),
+                    (2,  'red'),
+                    (2, 'blue')],
+                   names=['number', 'color'])
+        """
+        if not is_list_like(tuples):
+            raise TypeError("Input must be a list / sequence of tuple-likes.")
+        if is_iterator(tuples):
+            tuples = list(tuples)
+        tuples = cast(Collection[tuple[Hashable, ...]], tuples)
+
+        # handling the empty tuple cases
+        if len(tuples) and all(isinstance(e, tuple) and not e for e in tuples):
+            codes = [np.zeros(len(tuples))]
+            levels = [Index(com.asarray_tuplesafe(tuples, dtype=np.dtype("object")))]
+            return cls(
+                levels=levels,
+                codes=codes,
+                sortorder=sortorder,
+                names=names,
+                verify_integrity=False,
+            )
+
+        arrays: list[Sequence[Hashable]]
+        if len(tuples) == 0:
+            if names is None:
+                raise TypeError("Cannot infer number of levels from empty list")
+            # error: Argument 1 to "len" has incompatible type "Hashable";
+            # expected "Sized"
+            arrays = [[]] * len(names)  # type: ignore[arg-type]
+        elif isinstance(tuples, (np.ndarray, Index)):
+            if isinstance(tuples, Index):
+                tuples = np.asarray(tuples._values)
+
+            arrays = list(lib.tuples_to_object_array(tuples).T)
+        elif isinstance(tuples, list):
+            arrays = list(lib.to_object_array_tuples(tuples).T)
+        else:
+            arrs = zip(*tuples)
+            arrays = cast(list[Sequence[Hashable]], arrs)
+
+        return cls.from_arrays(arrays, sortorder=sortorder, names=names)
+
+    @classmethod
+    def from_product(
+        cls,
+        iterables: Sequence[Iterable[Hashable]],
+        sortorder: int | None = None,
+        names: Sequence[Hashable] | Hashable | lib.NoDefault = lib.no_default,
+    ) -> MultiIndex:
+        """
+        Make a MultiIndex from the cartesian product of multiple iterables.
+
+        Parameters
+        ----------
+        iterables : list / sequence of iterables
+            Each iterable has unique labels for each level of the index.
+        sortorder : int or None
+            Level of sortedness (must be lexicographically sorted by that
+            level).
+        names : list / sequence of str, optional
+            Names for the levels in the index.
+            If not explicitly provided, names will be inferred from the
+            elements of iterables if an element has a name attribute.
+
+        Returns
+        -------
+        MultiIndex
+
+        See Also
+        --------
+        MultiIndex.from_arrays : Convert list of arrays to MultiIndex.
+        MultiIndex.from_tuples : Convert list of tuples to MultiIndex.
+        MultiIndex.from_frame : Make a MultiIndex from a DataFrame.
+
+        Examples
+        --------
+        >>> numbers = [0, 1, 2]
+        >>> colors = ['green', 'purple']
+        >>> pd.MultiIndex.from_product([numbers, colors],
+        ...                            names=['number', 'color'])
+        MultiIndex([(0,  'green'),
+                    (0, 'purple'),
+                    (1,  'green'),
+                    (1, 'purple'),
+                    (2,  'green'),
+                    (2, 'purple')],
+                   names=['number', 'color'])
+        """
+        from pandas.core.reshape.util import cartesian_product
+
+        if not is_list_like(iterables):
+            raise TypeError("Input must be a list / sequence of iterables.")
+        if is_iterator(iterables):
+            iterables = list(iterables)
+
+        codes, levels = factorize_from_iterables(iterables)
+        if names is lib.no_default:
+            names = [getattr(it, "name", None) for it in iterables]
+
+        # codes are all ndarrays, so cartesian_product is lossless
+        codes = cartesian_product(codes)
+        return cls(levels, codes, sortorder=sortorder, names=names)
+
+    @classmethod
+    def from_frame(
+        cls,
+        df: DataFrame,
+        sortorder: int | None = None,
+        names: Sequence[Hashable] | Hashable | None = None,
+    ) -> MultiIndex:
+        """
+        Make a MultiIndex from a DataFrame.
+
+        Parameters
+        ----------
+        df : DataFrame
+            DataFrame to be converted to MultiIndex.
+        sortorder : int, optional
+            Level of sortedness (must be lexicographically sorted by that
+            level).
+        names : list-like, optional
+            If no names are provided, use the column names, or tuple of column
+            names if the columns is a MultiIndex. If a sequence, overwrite
+            names with the given sequence.
+
+        Returns
+        -------
+        MultiIndex
+            The MultiIndex representation of the given DataFrame.
+
+        See Also
+        --------
+        MultiIndex.from_arrays : Convert list of arrays to MultiIndex.
+        MultiIndex.from_tuples : Convert list of tuples to MultiIndex.
+        MultiIndex.from_product : Make a MultiIndex from cartesian product
+                                  of iterables.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([['HI', 'Temp'], ['HI', 'Precip'],
+        ...                    ['NJ', 'Temp'], ['NJ', 'Precip']],
+        ...                   columns=['a', 'b'])
+        >>> df
+              a       b
+        0    HI    Temp
+        1    HI  Precip
+        2    NJ    Temp
+        3    NJ  Precip
+
+        >>> pd.MultiIndex.from_frame(df)
+        MultiIndex([('HI',   'Temp'),
+                    ('HI', 'Precip'),
+                    ('NJ',   'Temp'),
+                    ('NJ', 'Precip')],
+                   names=['a', 'b'])
+
+        Using explicit names, instead of the column names
+
+        >>> pd.MultiIndex.from_frame(df, names=['state', 'observation'])
+        MultiIndex([('HI',   'Temp'),
+                    ('HI', 'Precip'),
+                    ('NJ',   'Temp'),
+                    ('NJ', 'Precip')],
+                   names=['state', 'observation'])
+        """
+        if not isinstance(df, ABCDataFrame):
+            raise TypeError("Input must be a DataFrame")
+
+        column_names, columns = zip(*df.items())
+        names = column_names if names is None else names
+        return cls.from_arrays(columns, sortorder=sortorder, names=names)
+
+    # --------------------------------------------------------------------
+
+    @cache_readonly
+    def _values(self) -> np.ndarray:
+        # We override here, since our parent uses _data, which we don't use.
+        values = []
+
+        for i in range(self.nlevels):
+            index = self.levels[i]
+            codes = self.codes[i]
+
+            vals = index
+            if isinstance(vals.dtype, CategoricalDtype):
+                vals = cast("CategoricalIndex", vals)
+                vals = vals._data._internal_get_values()
+
+            if isinstance(vals.dtype, ExtensionDtype) or lib.is_np_dtype(
+                vals.dtype, "mM"
+            ):
+                vals = vals.astype(object)
+
+            vals = np.asarray(vals)
+            vals = algos.take_nd(vals, codes, fill_value=index._na_value)
+            values.append(vals)
+
+        arr = lib.fast_zip(values)
+        return arr
+
+    @property
+    def values(self) -> np.ndarray:
+        return self._values
+
+    @property
+    def array(self):
+        """
+        Raises a ValueError for `MultiIndex` because there's no single
+        array backing a MultiIndex.
+
+        Raises
+        ------
+        ValueError
+        """
+        raise ValueError(
+            "MultiIndex has no single backing array. Use "
+            "'MultiIndex.to_numpy()' to get a NumPy array of tuples."
+        )
+
+    @cache_readonly
+    def dtypes(self) -> Series:
+        """
+        Return the dtypes as a Series for the underlying MultiIndex.
+
+        Examples
+        --------
+        >>> idx = pd.MultiIndex.from_product([(0, 1, 2), ('green', 'purple')],
+        ...                                  names=['number', 'color'])
+        >>> idx
+        MultiIndex([(0,  'green'),
+                    (0, 'purple'),
+                    (1,  'green'),
+                    (1, 'purple'),
+                    (2,  'green'),
+                    (2, 'purple')],
+                   names=['number', 'color'])
+        >>> idx.dtypes
+        number     int64
+        color     object
+        dtype: object
+        """
+        from pandas import Series
+
+        names = com.fill_missing_names([level.name for level in self.levels])
+        return Series([level.dtype for level in self.levels], index=Index(names))
+
+    def __len__(self) -> int:
+        return len(self.codes[0])
+
+    @property
+    def size(self) -> int:
+        """
+        Return the number of elements in the underlying data.
+        """
+        # override Index.size to avoid materializing _values
+        return len(self)
+
+    # --------------------------------------------------------------------
+    # Levels Methods
+
+    @cache_readonly
+    def levels(self) -> FrozenList:
+        """
+        Levels of the MultiIndex.
+
+        Levels refer to the different hierarchical levels or layers in a MultiIndex.
+        In a MultiIndex, each level represents a distinct dimension or category of
+        the index.
+
+        To access the levels, you can use the levels attribute of the MultiIndex,
+        which returns a tuple of Index objects. Each Index object represents a
+        level in the MultiIndex and contains the unique values found in that
+        specific level.
+
+        If a MultiIndex is created with levels A, B, C, and the DataFrame using
+        it filters out all rows of the level C, MultiIndex.levels will still
+        return A, B, C.
+
+        Examples
+        --------
+        >>> index = pd.MultiIndex.from_product([['mammal'],
+        ...                                     ('goat', 'human', 'cat', 'dog')],
+        ...                                    names=['Category', 'Animals'])
+        >>> leg_num = pd.DataFrame(data=(4, 2, 4, 4), index=index, columns=['Legs'])
+        >>> leg_num
+                          Legs
+        Category Animals
+        mammal   goat        4
+                 human       2
+                 cat         4
+                 dog         4
+
+        >>> leg_num.index.levels
+        FrozenList([['mammal'], ['cat', 'dog', 'goat', 'human']])
+
+        MultiIndex levels will not change even if the DataFrame using the MultiIndex
+        does not contain all them anymore.
+        See how "human" is not in the DataFrame, but it is still in levels:
+
+        >>> large_leg_num = leg_num[leg_num.Legs > 2]
+        >>> large_leg_num
+                          Legs
+        Category Animals
+        mammal   goat        4
+                 cat         4
+                 dog         4
+
+        >>> large_leg_num.index.levels
+        FrozenList([['mammal'], ['cat', 'dog', 'goat', 'human']])
+        """
+        # Use cache_readonly to ensure that self.get_locs doesn't repeatedly
+        # create new IndexEngine
+        # https://github.com/pandas-dev/pandas/issues/31648
+        result = [x._rename(name=name) for x, name in zip(self._levels, self._names)]
+        for level in result:
+            # disallow midx.levels[0].name = "foo"
+            level._no_setting_name = True
+        return FrozenList(result)
+
+    def _set_levels(
+        self,
+        levels,
+        *,
+        level=None,
+        copy: bool = False,
+        validate: bool = True,
+        verify_integrity: bool = False,
+    ) -> None:
+        # This is NOT part of the levels property because it should be
+        # externally not allowed to set levels. User beware if you change
+        # _levels directly
+        if validate:
+            if len(levels) == 0:
+                raise ValueError("Must set non-zero number of levels.")
+            if level is None and len(levels) != self.nlevels:
+                raise ValueError("Length of levels must match number of levels.")
+            if level is not None and len(levels) != len(level):
+                raise ValueError("Length of levels must match length of level.")
+
+        if level is None:
+            new_levels = FrozenList(
+                ensure_index(lev, copy=copy)._view() for lev in levels
+            )
+            level_numbers = list(range(len(new_levels)))
+        else:
+            level_numbers = [self._get_level_number(lev) for lev in level]
+            new_levels_list = list(self._levels)
+            for lev_num, lev in zip(level_numbers, levels):
+                new_levels_list[lev_num] = ensure_index(lev, copy=copy)._view()
+            new_levels = FrozenList(new_levels_list)
+
+        if verify_integrity:
+            new_codes = self._verify_integrity(
+                levels=new_levels, levels_to_verify=level_numbers
+            )
+            self._codes = new_codes
+
+        names = self.names
+        self._levels = new_levels
+        if any(names):
+            self._set_names(names)
+
+        self._reset_cache()
+
+    def set_levels(
+        self, levels, *, level=None, verify_integrity: bool = True
+    ) -> MultiIndex:
+        """
+        Set new levels on MultiIndex. Defaults to returning new index.
+
+        Parameters
+        ----------
+        levels : sequence or list of sequence
+            New level(s) to apply.
+        level : int, level name, or sequence of int/level names (default None)
+            Level(s) to set (None for all levels).
+        verify_integrity : bool, default True
+            If True, checks that levels and codes are compatible.
+
+        Returns
+        -------
+        MultiIndex
+
+        Examples
+        --------
+        >>> idx = pd.MultiIndex.from_tuples(
+        ...     [
+        ...         (1, "one"),
+        ...         (1, "two"),
+        ...         (2, "one"),
+        ...         (2, "two"),
+        ...         (3, "one"),
+        ...         (3, "two")
+        ...     ],
+        ...     names=["foo", "bar"]
+        ... )
+        >>> idx
+        MultiIndex([(1, 'one'),
+            (1, 'two'),
+            (2, 'one'),
+            (2, 'two'),
+            (3, 'one'),
+            (3, 'two')],
+           names=['foo', 'bar'])
+
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2]])
+        MultiIndex([('a', 1),
+                    ('a', 2),
+                    ('b', 1),
+                    ('b', 2),
+                    ('c', 1),
+                    ('c', 2)],
+                   names=['foo', 'bar'])
+        >>> idx.set_levels(['a', 'b', 'c'], level=0)
+        MultiIndex([('a', 'one'),
+                    ('a', 'two'),
+                    ('b', 'one'),
+                    ('b', 'two'),
+                    ('c', 'one'),
+                    ('c', 'two')],
+                   names=['foo', 'bar'])
+        >>> idx.set_levels(['a', 'b'], level='bar')
+        MultiIndex([(1, 'a'),
+                    (1, 'b'),
+                    (2, 'a'),
+                    (2, 'b'),
+                    (3, 'a'),
+                    (3, 'b')],
+                   names=['foo', 'bar'])
+
+        If any of the levels passed to ``set_levels()`` exceeds the
+        existing length, all of the values from that argument will
+        be stored in the MultiIndex levels, though the values will
+        be truncated in the MultiIndex output.
+
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1])
+        MultiIndex([('a', 1),
+            ('a', 2),
+            ('b', 1),
+            ('b', 2),
+            ('c', 1),
+            ('c', 2)],
+           names=['foo', 'bar'])
+        >>> idx.set_levels([['a', 'b', 'c'], [1, 2, 3, 4]], level=[0, 1]).levels
+        FrozenList([['a', 'b', 'c'], [1, 2, 3, 4]])
+        """
+
+        if isinstance(levels, Index):
+            pass
+        elif is_array_like(levels):
+            levels = Index(levels)
+        elif is_list_like(levels):
+            levels = list(levels)
+
+        level, levels = _require_listlike(level, levels, "Levels")
+        idx = self._view()
+        idx._reset_identity()
+        idx._set_levels(
+            levels, level=level, validate=True, verify_integrity=verify_integrity
+        )
+        return idx
+
+    @property
+    def nlevels(self) -> int:
+        """
+        Integer number of levels in this MultiIndex.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a'], ['b'], ['c']])
+        >>> mi
+        MultiIndex([('a', 'b', 'c')],
+                   )
+        >>> mi.nlevels
+        3
+        """
+        return len(self._levels)
+
+    @property
+    def levshape(self) -> Shape:
+        """
+        A tuple with the length of each level.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a'], ['b'], ['c']])
+        >>> mi
+        MultiIndex([('a', 'b', 'c')],
+                   )
+        >>> mi.levshape
+        (1, 1, 1)
+        """
+        return tuple(len(x) for x in self.levels)
+
+    # --------------------------------------------------------------------
+    # Codes Methods
+
+    @property
+    def codes(self) -> FrozenList:
+        return self._codes
+
+    def _set_codes(
+        self,
+        codes,
+        *,
+        level=None,
+        copy: bool = False,
+        validate: bool = True,
+        verify_integrity: bool = False,
+    ) -> None:
+        if validate:
+            if level is None and len(codes) != self.nlevels:
+                raise ValueError("Length of codes must match number of levels")
+            if level is not None and len(codes) != len(level):
+                raise ValueError("Length of codes must match length of levels.")
+
+        level_numbers: list[int] | range
+        if level is None:
+            new_codes = FrozenList(
+                _coerce_indexer_frozen(level_codes, lev, copy=copy).view()
+                for lev, level_codes in zip(self._levels, codes)
+            )
+            level_numbers = range(len(new_codes))
+        else:
+            level_numbers = [self._get_level_number(lev) for lev in level]
+            new_codes_list = list(self._codes)
+            for lev_num, level_codes in zip(level_numbers, codes):
+                lev = self.levels[lev_num]
+                new_codes_list[lev_num] = _coerce_indexer_frozen(
+                    level_codes, lev, copy=copy
+                )
+            new_codes = FrozenList(new_codes_list)
+
+        if verify_integrity:
+            new_codes = self._verify_integrity(
+                codes=new_codes, levels_to_verify=level_numbers
+            )
+
+        self._codes = new_codes
+
+        self._reset_cache()
+
+    def set_codes(
+        self, codes, *, level=None, verify_integrity: bool = True
+    ) -> MultiIndex:
+        """
+        Set new codes on MultiIndex. Defaults to returning new index.
+
+        Parameters
+        ----------
+        codes : sequence or list of sequence
+            New codes to apply.
+        level : int, level name, or sequence of int/level names (default None)
+            Level(s) to set (None for all levels).
+        verify_integrity : bool, default True
+            If True, checks that levels and codes are compatible.
+
+        Returns
+        -------
+        new index (of same type and class...etc) or None
+            The same type as the caller or None if ``inplace=True``.
+
+        Examples
+        --------
+        >>> idx = pd.MultiIndex.from_tuples(
+        ...     [(1, "one"), (1, "two"), (2, "one"), (2, "two")], names=["foo", "bar"]
+        ... )
+        >>> idx
+        MultiIndex([(1, 'one'),
+            (1, 'two'),
+            (2, 'one'),
+            (2, 'two')],
+           names=['foo', 'bar'])
+
+        >>> idx.set_codes([[1, 0, 1, 0], [0, 0, 1, 1]])
+        MultiIndex([(2, 'one'),
+                    (1, 'one'),
+                    (2, 'two'),
+                    (1, 'two')],
+                   names=['foo', 'bar'])
+        >>> idx.set_codes([1, 0, 1, 0], level=0)
+        MultiIndex([(2, 'one'),
+                    (1, 'two'),
+                    (2, 'one'),
+                    (1, 'two')],
+                   names=['foo', 'bar'])
+        >>> idx.set_codes([0, 0, 1, 1], level='bar')
+        MultiIndex([(1, 'one'),
+                    (1, 'one'),
+                    (2, 'two'),
+                    (2, 'two')],
+                   names=['foo', 'bar'])
+        >>> idx.set_codes([[1, 0, 1, 0], [0, 0, 1, 1]], level=[0, 1])
+        MultiIndex([(2, 'one'),
+                    (1, 'one'),
+                    (2, 'two'),
+                    (1, 'two')],
+                   names=['foo', 'bar'])
+        """
+
+        level, codes = _require_listlike(level, codes, "Codes")
+        idx = self._view()
+        idx._reset_identity()
+        idx._set_codes(codes, level=level, verify_integrity=verify_integrity)
+        return idx
+
+    # --------------------------------------------------------------------
+    # Index Internals
+
+    @cache_readonly
+    def _engine(self):
+        # Calculate the number of bits needed to represent labels in each
+        # level, as log2 of their sizes:
+        # NaN values are shifted to 1 and missing values in other while
+        # calculating the indexer are shifted to 0
+        sizes = np.ceil(
+            np.log2(
+                [len(level) + libindex.multiindex_nulls_shift for level in self.levels]
+            )
+        )
+
+        # Sum bit counts, starting from the _right_....
+        lev_bits = np.cumsum(sizes[::-1])[::-1]
+
+        # ... in order to obtain offsets such that sorting the combination of
+        # shifted codes (one for each level, resulting in a unique integer) is
+        # equivalent to sorting lexicographically the codes themselves. Notice
+        # that each level needs to be shifted by the number of bits needed to
+        # represent the _previous_ ones:
+        offsets = np.concatenate([lev_bits[1:], [0]]).astype("uint64")
+
+        # Check the total number of bits needed for our representation:
+        if lev_bits[0] > 64:
+            # The levels would overflow a 64 bit uint - use Python integers:
+            return MultiIndexPyIntEngine(self.levels, self.codes, offsets)
+        return MultiIndexUIntEngine(self.levels, self.codes, offsets)
+
+    # Return type "Callable[..., MultiIndex]" of "_constructor" incompatible with return
+    # type "Type[MultiIndex]" in supertype "Index"
+    @property
+    def _constructor(self) -> Callable[..., MultiIndex]:  # type: ignore[override]
+        return type(self).from_tuples
+
+    @doc(Index._shallow_copy)
+    def _shallow_copy(self, values: np.ndarray, name=lib.no_default) -> MultiIndex:
+        names = name if name is not lib.no_default else self.names
+
+        return type(self).from_tuples(values, sortorder=None, names=names)
+
+    def _view(self) -> MultiIndex:
+        result = type(self)(
+            levels=self.levels,
+            codes=self.codes,
+            sortorder=self.sortorder,
+            names=self.names,
+            verify_integrity=False,
+        )
+        result._cache = self._cache.copy()
+        result._cache.pop("levels", None)  # GH32669
+        return result
+
+    # --------------------------------------------------------------------
+
+    # error: Signature of "copy" incompatible with supertype "Index"
+    def copy(  # type: ignore[override]
+        self,
+        names=None,
+        deep: bool = False,
+        name=None,
+    ) -> Self:
+        """
+        Make a copy of this object.
+
+        Names, dtype, levels and codes can be passed and will be set on new copy.
+
+        Parameters
+        ----------
+        names : sequence, optional
+        deep : bool, default False
+        name : Label
+            Kept for compatibility with 1-dimensional Index. Should not be used.
+
+        Returns
+        -------
+        MultiIndex
+
+        Notes
+        -----
+        In most cases, there should be no functional difference from using
+        ``deep``, but if ``deep`` is passed it will attempt to deepcopy.
+        This could be potentially expensive on large MultiIndex objects.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a'], ['b'], ['c']])
+        >>> mi
+        MultiIndex([('a', 'b', 'c')],
+                   )
+        >>> mi.copy()
+        MultiIndex([('a', 'b', 'c')],
+                   )
+        """
+        names = self._validate_names(name=name, names=names, deep=deep)
+        keep_id = not deep
+        levels, codes = None, None
+
+        if deep:
+            from copy import deepcopy
+
+            levels = deepcopy(self.levels)
+            codes = deepcopy(self.codes)
+
+        levels = levels if levels is not None else self.levels
+        codes = codes if codes is not None else self.codes
+
+        new_index = type(self)(
+            levels=levels,
+            codes=codes,
+            sortorder=self.sortorder,
+            names=names,
+            verify_integrity=False,
+        )
+        new_index._cache = self._cache.copy()
+        new_index._cache.pop("levels", None)  # GH32669
+        if keep_id:
+            new_index._id = self._id
+        return new_index
+
+    def __array__(self, dtype=None, copy=None) -> np.ndarray:
+        """the array interface, return my values"""
+        if copy is False:
+            # self.values is always a newly construct array, so raise.
+            warnings.warn(
+                "Starting with NumPy 2.0, the behavior of the 'copy' keyword has "
+                "changed and passing 'copy=False' raises an error when returning "
+                "a zero-copy NumPy array is not possible. pandas will follow "
+                "this behavior starting with pandas 3.0.\nThis conversion to "
+                "NumPy requires a copy, but 'copy=False' was passed. Consider "
+                "using 'np.asarray(..)' instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if copy is True:
+            # explicit np.array call to ensure a copy is made and unique objects
+            # are returned, because self.values is cached
+            return np.array(self.values, dtype=dtype)
+        return self.values
+
+    def view(self, cls=None) -> Self:
+        """this is defined as a copy with the same identity"""
+        result = self.copy()
+        result._id = self._id
+        return result
+
+    @doc(Index.__contains__)
+    def __contains__(self, key: Any) -> bool:
+        hash(key)
+        try:
+            self.get_loc(key)
+            return True
+        except (LookupError, TypeError, ValueError):
+            return False
+
+    @cache_readonly
+    def dtype(self) -> np.dtype:
+        return np.dtype("O")
+
+    def _is_memory_usage_qualified(self) -> bool:
+        """return a boolean if we need a qualified .info display"""
+
+        def f(dtype) -> bool:
+            return is_object_dtype(dtype) or (
+                is_string_dtype(dtype) and dtype.storage == "python"
+            )
+
+        return any(f(level.dtype) for level in self.levels)
+
+    # Cannot determine type of "memory_usage"
+    @doc(Index.memory_usage)  # type: ignore[has-type]
+    def memory_usage(self, deep: bool = False) -> int:
+        # we are overwriting our base class to avoid
+        # computing .values here which could materialize
+        # a tuple representation unnecessarily
+        return self._nbytes(deep)
+
+    @cache_readonly
+    def nbytes(self) -> int:
+        """return the number of bytes in the underlying data"""
+        return self._nbytes(False)
+
+    def _nbytes(self, deep: bool = False) -> int:
+        """
+        return the number of bytes in the underlying data
+        deeply introspect the level data if deep=True
+
+        include the engine hashtable
+
+        *this is in internal routine*
+
+        """
+        # for implementations with no useful getsizeof (PyPy)
+        objsize = 24
+
+        level_nbytes = sum(i.memory_usage(deep=deep) for i in self.levels)
+        label_nbytes = sum(i.nbytes for i in self.codes)
+        names_nbytes = sum(getsizeof(i, objsize) for i in self.names)
+        result = level_nbytes + label_nbytes + names_nbytes
+
+        # include our engine hashtable
+        result += self._engine.sizeof(deep=deep)
+        return result
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+
+    def _formatter_func(self, tup):
+        """
+        Formats each item in tup according to its level's formatter function.
+        """
+        formatter_funcs = [level._formatter_func for level in self.levels]
+        return tuple(func(val) for func, val in zip(formatter_funcs, tup))
+
+    def _get_values_for_csv(
+        self, *, na_rep: str = "nan", **kwargs
+    ) -> npt.NDArray[np.object_]:
+        new_levels = []
+        new_codes = []
+
+        # go through the levels and format them
+        for level, level_codes in zip(self.levels, self.codes):
+            level_strs = level._get_values_for_csv(na_rep=na_rep, **kwargs)
+            # add nan values, if there are any
+            mask = level_codes == -1
+            if mask.any():
+                nan_index = len(level_strs)
+                # numpy 1.21 deprecated implicit string casting
+                level_strs = level_strs.astype(str)
+                level_strs = np.append(level_strs, na_rep)
+                assert not level_codes.flags.writeable  # i.e. copy is needed
+                level_codes = level_codes.copy()  # make writeable
+                level_codes[mask] = nan_index
+            new_levels.append(level_strs)
+            new_codes.append(level_codes)
+
+        if len(new_levels) == 1:
+            # a single-level multi-index
+            return Index(new_levels[0].take(new_codes[0]))._get_values_for_csv()
+        else:
+            # reconstruct the multi-index
+            mi = MultiIndex(
+                levels=new_levels,
+                codes=new_codes,
+                names=self.names,
+                sortorder=self.sortorder,
+                verify_integrity=False,
+            )
+            return mi._values
+
+    def format(
+        self,
+        name: bool | None = None,
+        formatter: Callable | None = None,
+        na_rep: str | None = None,
+        names: bool = False,
+        space: int = 2,
+        sparsify=None,
+        adjoin: bool = True,
+    ) -> list:
+        warnings.warn(
+            # GH#55413
+            f"{type(self).__name__}.format is deprecated and will be removed "
+            "in a future version. Convert using index.astype(str) or "
+            "index.map(formatter) instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        if name is not None:
+            names = name
+
+        if len(self) == 0:
+            return []
+
+        stringified_levels = []
+        for lev, level_codes in zip(self.levels, self.codes):
+            na = na_rep if na_rep is not None else _get_na_rep(lev.dtype)
+
+            if len(lev) > 0:
+                formatted = lev.take(level_codes).format(formatter=formatter)
+
+                # we have some NA
+                mask = level_codes == -1
+                if mask.any():
+                    formatted = np.array(formatted, dtype=object)
+                    formatted[mask] = na
+                    formatted = formatted.tolist()
+
+            else:
+                # weird all NA case
+                formatted = [
+                    pprint_thing(na if isna(x) else x, escape_chars=("\t", "\r", "\n"))
+                    for x in algos.take_nd(lev._values, level_codes)
+                ]
+            stringified_levels.append(formatted)
+
+        result_levels = []
+        for lev, lev_name in zip(stringified_levels, self.names):
+            level = []
+
+            if names:
+                level.append(
+                    pprint_thing(lev_name, escape_chars=("\t", "\r", "\n"))
+                    if lev_name is not None
+                    else ""
+                )
+
+            level.extend(np.array(lev, dtype=object))
+            result_levels.append(level)
+
+        if sparsify is None:
+            sparsify = get_option("display.multi_sparse")
+
+        if sparsify:
+            sentinel: Literal[""] | bool | lib.NoDefault = ""
+            # GH3547 use value of sparsify as sentinel if it's "Falsey"
+            assert isinstance(sparsify, bool) or sparsify is lib.no_default
+            if sparsify in [False, lib.no_default]:
+                sentinel = sparsify
+            # little bit of a kludge job for #1217
+            result_levels = sparsify_labels(
+                result_levels, start=int(names), sentinel=sentinel
+            )
+
+        if adjoin:
+            adj = get_adjustment()
+            return adj.adjoin(space, *result_levels).split("\n")
+        else:
+            return result_levels
+
+    def _format_multi(
+        self,
+        *,
+        include_names: bool,
+        sparsify: bool | None | lib.NoDefault,
+        formatter: Callable | None = None,
+    ) -> list:
+        if len(self) == 0:
+            return []
+
+        stringified_levels = []
+        for lev, level_codes in zip(self.levels, self.codes):
+            na = _get_na_rep(lev.dtype)
+
+            if len(lev) > 0:
+                taken = formatted = lev.take(level_codes)
+                formatted = taken._format_flat(include_name=False, formatter=formatter)
+
+                # we have some NA
+                mask = level_codes == -1
+                if mask.any():
+                    formatted = np.array(formatted, dtype=object)
+                    formatted[mask] = na
+                    formatted = formatted.tolist()
+
+            else:
+                # weird all NA case
+                formatted = [
+                    pprint_thing(na if isna(x) else x, escape_chars=("\t", "\r", "\n"))
+                    for x in algos.take_nd(lev._values, level_codes)
+                ]
+            stringified_levels.append(formatted)
+
+        result_levels = []
+        for lev, lev_name in zip(stringified_levels, self.names):
+            level = []
+
+            if include_names:
+                level.append(
+                    pprint_thing(lev_name, escape_chars=("\t", "\r", "\n"))
+                    if lev_name is not None
+                    else ""
+                )
+
+            level.extend(np.array(lev, dtype=object))
+            result_levels.append(level)
+
+        if sparsify is None:
+            sparsify = get_option("display.multi_sparse")
+
+        if sparsify:
+            sentinel: Literal[""] | bool | lib.NoDefault = ""
+            # GH3547 use value of sparsify as sentinel if it's "Falsey"
+            assert isinstance(sparsify, bool) or sparsify is lib.no_default
+            if sparsify is lib.no_default:
+                sentinel = sparsify
+            # little bit of a kludge job for #1217
+            result_levels = sparsify_labels(
+                result_levels, start=int(include_names), sentinel=sentinel
+            )
+
+        return result_levels
+
+    # --------------------------------------------------------------------
+    # Names Methods
+
+    def _get_names(self) -> FrozenList:
+        return FrozenList(self._names)
+
+    def _set_names(self, names, *, level=None, validate: bool = True):
+        """
+        Set new names on index. Each name has to be a hashable type.
+
+        Parameters
+        ----------
+        values : str or sequence
+            name(s) to set
+        level : int, level name, or sequence of int/level names (default None)
+            If the index is a MultiIndex (hierarchical), level(s) to set (None
+            for all levels).  Otherwise level must be None
+        validate : bool, default True
+            validate that the names match level lengths
+
+        Raises
+        ------
+        TypeError if each name is not hashable.
+
+        Notes
+        -----
+        sets names on levels. WARNING: mutates!
+
+        Note that you generally want to set this *after* changing levels, so
+        that it only acts on copies
+        """
+        # GH 15110
+        # Don't allow a single string for names in a MultiIndex
+        if names is not None and not is_list_like(names):
+            raise ValueError("Names should be list-like for a MultiIndex")
+        names = list(names)
+
+        if validate:
+            if level is not None and len(names) != len(level):
+                raise ValueError("Length of names must match length of level.")
+            if level is None and len(names) != self.nlevels:
+                raise ValueError(
+                    "Length of names must match number of levels in MultiIndex."
+                )
+
+        if level is None:
+            level = range(self.nlevels)
+        else:
+            level = [self._get_level_number(lev) for lev in level]
+
+        # set the name
+        for lev, name in zip(level, names):
+            if name is not None:
+                # GH 20527
+                # All items in 'names' need to be hashable:
+                if not is_hashable(name):
+                    raise TypeError(
+                        f"{type(self).__name__}.name must be a hashable type"
+                    )
+            self._names[lev] = name
+
+        # If .levels has been accessed, the names in our cache will be stale.
+        self._reset_cache()
+
+    names = property(
+        fset=_set_names,
+        fget=_get_names,
+        doc="""
+        Names of levels in MultiIndex.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays(
+        ... [[1, 2], [3, 4], [5, 6]], names=['x', 'y', 'z'])
+        >>> mi
+        MultiIndex([(1, 3, 5),
+                    (2, 4, 6)],
+                   names=['x', 'y', 'z'])
+        >>> mi.names
+        FrozenList(['x', 'y', 'z'])
+        """,
+    )
+
+    # --------------------------------------------------------------------
+
+    @cache_readonly
+    def inferred_type(self) -> str:
+        return "mixed"
+
+    def _get_level_number(self, level) -> int:
+        count = self.names.count(level)
+        if (count > 1) and not is_integer(level):
+            raise ValueError(
+                f"The name {level} occurs multiple times, use a level number"
+            )
+        try:
+            level = self.names.index(level)
+        except ValueError as err:
+            if not is_integer(level):
+                raise KeyError(f"Level {level} not found") from err
+            if level < 0:
+                level += self.nlevels
+                if level < 0:
+                    orig_level = level - self.nlevels
+                    raise IndexError(
+                        f"Too many levels: Index has only {self.nlevels} levels, "
+                        f"{orig_level} is not a valid level number"
+                    ) from err
+            # Note: levels are zero-based
+            elif level >= self.nlevels:
+                raise IndexError(
+                    f"Too many levels: Index has only {self.nlevels} levels, "
+                    f"not {level + 1}"
+                ) from err
+        return level
+
+    @cache_readonly
+    def is_monotonic_increasing(self) -> bool:
+        """
+        Return a boolean if the values are equal or increasing.
+        """
+        if any(-1 in code for code in self.codes):
+            return False
+
+        if all(level.is_monotonic_increasing for level in self.levels):
+            # If each level is sorted, we can operate on the codes directly. GH27495
+            return libalgos.is_lexsorted(
+                [x.astype("int64", copy=False) for x in self.codes]
+            )
+
+        # reversed() because lexsort() wants the most significant key last.
+        values = [
+            self._get_level_values(i)._values for i in reversed(range(len(self.levels)))
+        ]
+        try:
+            # error: Argument 1 to "lexsort" has incompatible type
+            # "List[Union[ExtensionArray, ndarray[Any, Any]]]";
+            # expected "Union[_SupportsArray[dtype[Any]],
+            # _NestedSequence[_SupportsArray[dtype[Any]]], bool,
+            # int, float, complex, str, bytes, _NestedSequence[Union
+            # [bool, int, float, complex, str, bytes]]]"
+            sort_order = np.lexsort(values)  # type: ignore[arg-type]
+            return Index(sort_order).is_monotonic_increasing
+        except TypeError:
+            # we have mixed types and np.lexsort is not happy
+            return Index(self._values).is_monotonic_increasing
+
+    @cache_readonly
+    def is_monotonic_decreasing(self) -> bool:
+        """
+        Return a boolean if the values are equal or decreasing.
+        """
+        # monotonic decreasing if and only if reverse is monotonic increasing
+        return self[::-1].is_monotonic_increasing
+
+    @cache_readonly
+    def _inferred_type_levels(self) -> list[str]:
+        """return a list of the inferred types, one for each level"""
+        return [i.inferred_type for i in self.levels]
+
+    @doc(Index.duplicated)
+    def duplicated(self, keep: DropKeep = "first") -> npt.NDArray[np.bool_]:
+        shape = tuple(len(lev) for lev in self.levels)
+        ids = get_group_index(self.codes, shape, sort=False, xnull=False)
+
+        return duplicated(ids, keep)
+
+    # error: Cannot override final attribute "_duplicated"
+    # (previously declared in base class "IndexOpsMixin")
+    _duplicated = duplicated  # type: ignore[misc]
+
+    def fillna(self, value=None, downcast=None):
+        """
+        fillna is not implemented for MultiIndex
+        """
+        raise NotImplementedError("isna is not defined for MultiIndex")
+
+    @doc(Index.dropna)
+    def dropna(self, how: AnyAll = "any") -> MultiIndex:
+        nans = [level_codes == -1 for level_codes in self.codes]
+        if how == "any":
+            indexer = np.any(nans, axis=0)
+        elif how == "all":
+            indexer = np.all(nans, axis=0)
+        else:
+            raise ValueError(f"invalid how option: {how}")
+
+        new_codes = [level_codes[~indexer] for level_codes in self.codes]
+        return self.set_codes(codes=new_codes)
+
+    def _get_level_values(self, level: int, unique: bool = False) -> Index:
+        """
+        Return vector of label values for requested level,
+        equal to the length of the index
+
+        **this is an internal method**
+
+        Parameters
+        ----------
+        level : int
+        unique : bool, default False
+            if True, drop duplicated values
+
+        Returns
+        -------
+        Index
+        """
+        lev = self.levels[level]
+        level_codes = self.codes[level]
+        name = self._names[level]
+        if unique:
+            level_codes = algos.unique(level_codes)
+        filled = algos.take_nd(lev._values, level_codes, fill_value=lev._na_value)
+        return lev._shallow_copy(filled, name=name)
+
+    # error: Signature of "get_level_values" incompatible with supertype "Index"
+    def get_level_values(self, level) -> Index:  # type: ignore[override]
+        """
+        Return vector of label values for requested level.
+
+        Length of returned vector is equal to the length of the index.
+
+        Parameters
+        ----------
+        level : int or str
+            ``level`` is either the integer position of the level in the
+            MultiIndex, or the name of the level.
+
+        Returns
+        -------
+        Index
+            Values is a level of this MultiIndex converted to
+            a single :class:`Index` (or subclass thereof).
+
+        Notes
+        -----
+        If the level contains missing values, the result may be casted to
+        ``float`` with missing values specified as ``NaN``. This is because
+        the level is converted to a regular ``Index``.
+
+        Examples
+        --------
+        Create a MultiIndex:
+
+        >>> mi = pd.MultiIndex.from_arrays((list('abc'), list('def')))
+        >>> mi.names = ['level_1', 'level_2']
+
+        Get level values by supplying level as either integer or name:
+
+        >>> mi.get_level_values(0)
+        Index(['a', 'b', 'c'], dtype='object', name='level_1')
+        >>> mi.get_level_values('level_2')
+        Index(['d', 'e', 'f'], dtype='object', name='level_2')
+
+        If a level contains missing values, the return type of the level
+        may be cast to ``float``.
+
+        >>> pd.MultiIndex.from_arrays([[1, None, 2], [3, 4, 5]]).dtypes
+        level_0    int64
+        level_1    int64
+        dtype: object
+        >>> pd.MultiIndex.from_arrays([[1, None, 2], [3, 4, 5]]).get_level_values(0)
+        Index([1.0, nan, 2.0], dtype='float64')
+        """
+        level = self._get_level_number(level)
+        values = self._get_level_values(level)
+        return values
+
+    @doc(Index.unique)
+    def unique(self, level=None):
+        if level is None:
+            return self.drop_duplicates()
+        else:
+            level = self._get_level_number(level)
+            return self._get_level_values(level=level, unique=True)
+
+    def to_frame(
+        self,
+        index: bool = True,
+        name=lib.no_default,
+        allow_duplicates: bool = False,
+    ) -> DataFrame:
+        """
+        Create a DataFrame with the levels of the MultiIndex as columns.
+
+        Column ordering is determined by the DataFrame constructor with data as
+        a dict.
+
+        Parameters
+        ----------
+        index : bool, default True
+            Set the index of the returned DataFrame as the original MultiIndex.
+
+        name : list / sequence of str, optional
+            The passed names should substitute index level names.
+
+        allow_duplicates : bool, optional default False
+            Allow duplicate column labels to be created.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        DataFrame : Two-dimensional, size-mutable, potentially heterogeneous
+            tabular data.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a', 'b'], ['c', 'd']])
+        >>> mi
+        MultiIndex([('a', 'c'),
+                    ('b', 'd')],
+                   )
+
+        >>> df = mi.to_frame()
+        >>> df
+             0  1
+        a c  a  c
+        b d  b  d
+
+        >>> df = mi.to_frame(index=False)
+        >>> df
+           0  1
+        0  a  c
+        1  b  d
+
+        >>> df = mi.to_frame(name=['x', 'y'])
+        >>> df
+             x  y
+        a c  a  c
+        b d  b  d
+        """
+        from pandas import DataFrame
+
+        if name is not lib.no_default:
+            if not is_list_like(name):
+                raise TypeError("'name' must be a list / sequence of column names.")
+
+            if len(name) != len(self.levels):
+                raise ValueError(
+                    "'name' should have same length as number of levels on index."
+                )
+            idx_names = name
+        else:
+            idx_names = self._get_level_names()
+
+        if not allow_duplicates and len(set(idx_names)) != len(idx_names):
+            raise ValueError(
+                "Cannot create duplicate column labels if allow_duplicates is False"
+            )
+
+        # Guarantee resulting column order - PY36+ dict maintains insertion order
+        result = DataFrame(
+            {level: self._get_level_values(level) for level in range(len(self.levels))},
+            copy=False,
+        )
+        result.columns = idx_names
+
+        if index:
+            result.index = self
+        return result
+
+    # error: Return type "Index" of "to_flat_index" incompatible with return type
+    # "MultiIndex" in supertype "Index"
+    def to_flat_index(self) -> Index:  # type: ignore[override]
+        """
+        Convert a MultiIndex to an Index of Tuples containing the level values.
+
+        Returns
+        -------
+        pd.Index
+            Index with the MultiIndex data represented in Tuples.
+
+        See Also
+        --------
+        MultiIndex.from_tuples : Convert flat index back to MultiIndex.
+
+        Notes
+        -----
+        This method will simply return the caller if called by anything other
+        than a MultiIndex.
+
+        Examples
+        --------
+        >>> index = pd.MultiIndex.from_product(
+        ...     [['foo', 'bar'], ['baz', 'qux']],
+        ...     names=['a', 'b'])
+        >>> index.to_flat_index()
+        Index([('foo', 'baz'), ('foo', 'qux'),
+               ('bar', 'baz'), ('bar', 'qux')],
+              dtype='object')
+        """
+        return Index(self._values, tupleize_cols=False)
+
+    def _is_lexsorted(self) -> bool:
+        """
+        Return True if the codes are lexicographically sorted.
+
+        Returns
+        -------
+        bool
+
+        Examples
+        --------
+        In the below examples, the first level of the MultiIndex is sorted because
+        a>> pd.MultiIndex.from_arrays([['a', 'b', 'c'],
+        ...                            ['d', 'e', 'f']])._is_lexsorted()
+        True
+        >>> pd.MultiIndex.from_arrays([['a', 'b', 'c'],
+        ...                            ['d', 'f', 'e']])._is_lexsorted()
+        True
+
+        In case there is a tie, the lexicographical sorting looks
+        at the next level of the MultiIndex.
+
+        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'b', 'c']])._is_lexsorted()
+        True
+        >>> pd.MultiIndex.from_arrays([[0, 1, 1], ['a', 'c', 'b']])._is_lexsorted()
+        False
+        >>> pd.MultiIndex.from_arrays([['a', 'a', 'b', 'b'],
+        ...                            ['aa', 'bb', 'aa', 'bb']])._is_lexsorted()
+        True
+        >>> pd.MultiIndex.from_arrays([['a', 'a', 'b', 'b'],
+        ...                            ['bb', 'aa', 'aa', 'bb']])._is_lexsorted()
+        False
+        """
+        return self._lexsort_depth == self.nlevels
+
+    @cache_readonly
+    def _lexsort_depth(self) -> int:
+        """
+        Compute and return the lexsort_depth, the number of levels of the
+        MultiIndex that are sorted lexically
+
+        Returns
+        -------
+        int
+        """
+        if self.sortorder is not None:
+            return self.sortorder
+        return _lexsort_depth(self.codes, self.nlevels)
+
+    def _sort_levels_monotonic(self, raise_if_incomparable: bool = False) -> MultiIndex:
+        """
+        This is an *internal* function.
+
+        Create a new MultiIndex from the current to monotonically sorted
+        items IN the levels. This does not actually make the entire MultiIndex
+        monotonic, JUST the levels.
+
+        The resulting MultiIndex will have the same outward
+        appearance, meaning the same .values and ordering. It will also
+        be .equals() to the original.
+
+        Returns
+        -------
+        MultiIndex
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex(levels=[['a', 'b'], ['bb', 'aa']],
+        ...                    codes=[[0, 0, 1, 1], [0, 1, 0, 1]])
+        >>> mi
+        MultiIndex([('a', 'bb'),
+                    ('a', 'aa'),
+                    ('b', 'bb'),
+                    ('b', 'aa')],
+                   )
+
+        >>> mi.sort_values()
+        MultiIndex([('a', 'aa'),
+                    ('a', 'bb'),
+                    ('b', 'aa'),
+                    ('b', 'bb')],
+                   )
+        """
+        if self._is_lexsorted() and self.is_monotonic_increasing:
+            return self
+
+        new_levels = []
+        new_codes = []
+
+        for lev, level_codes in zip(self.levels, self.codes):
+            if not lev.is_monotonic_increasing:
+                try:
+                    # indexer to reorder the levels
+                    indexer = lev.argsort()
+                except TypeError:
+                    if raise_if_incomparable:
+                        raise
+                else:
+                    lev = lev.take(indexer)
+
+                    # indexer to reorder the level codes
+                    indexer = ensure_platform_int(indexer)
+                    ri = lib.get_reverse_indexer(indexer, len(indexer))
+                    level_codes = algos.take_nd(ri, level_codes, fill_value=-1)
+
+            new_levels.append(lev)
+            new_codes.append(level_codes)
+
+        return MultiIndex(
+            new_levels,
+            new_codes,
+            names=self.names,
+            sortorder=self.sortorder,
+            verify_integrity=False,
+        )
+
+    def remove_unused_levels(self) -> MultiIndex:
+        """
+        Create new MultiIndex from current that removes unused levels.
+
+        Unused level(s) means levels that are not expressed in the
+        labels. The resulting MultiIndex will have the same outward
+        appearance, meaning the same .values and ordering. It will
+        also be .equals() to the original.
+
+        Returns
+        -------
+        MultiIndex
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_product([range(2), list('ab')])
+        >>> mi
+        MultiIndex([(0, 'a'),
+                    (0, 'b'),
+                    (1, 'a'),
+                    (1, 'b')],
+                   )
+
+        >>> mi[2:]
+        MultiIndex([(1, 'a'),
+                    (1, 'b')],
+                   )
+
+        The 0 from the first level is not represented
+        and can be removed
+
+        >>> mi2 = mi[2:].remove_unused_levels()
+        >>> mi2.levels
+        FrozenList([[1], ['a', 'b']])
+        """
+        new_levels = []
+        new_codes = []
+
+        changed = False
+        for lev, level_codes in zip(self.levels, self.codes):
+            # Since few levels are typically unused, bincount() is more
+            # efficient than unique() - however it only accepts positive values
+            # (and drops order):
+            uniques = np.where(np.bincount(level_codes + 1) > 0)[0] - 1
+            has_na = int(len(uniques) and (uniques[0] == -1))
+
+            if len(uniques) != len(lev) + has_na:
+                if lev.isna().any() and len(uniques) == len(lev):
+                    break
+                # We have unused levels
+                changed = True
+
+                # Recalculate uniques, now preserving order.
+                # Can easily be cythonized by exploiting the already existing
+                # "uniques" and stop parsing "level_codes" when all items
+                # are found:
+                uniques = algos.unique(level_codes)
+                if has_na:
+                    na_idx = np.where(uniques == -1)[0]
+                    # Just ensure that -1 is in first position:
+                    uniques[[0, na_idx[0]]] = uniques[[na_idx[0], 0]]
+
+                # codes get mapped from uniques to 0:len(uniques)
+                # -1 (if present) is mapped to last position
+                code_mapping = np.zeros(len(lev) + has_na)
+                # ... and reassigned value -1:
+                code_mapping[uniques] = np.arange(len(uniques)) - has_na
+
+                level_codes = code_mapping[level_codes]
+
+                # new levels are simple
+                lev = lev.take(uniques[has_na:])
+
+            new_levels.append(lev)
+            new_codes.append(level_codes)
+
+        result = self.view()
+
+        if changed:
+            result._reset_identity()
+            result._set_levels(new_levels, validate=False)
+            result._set_codes(new_codes, validate=False)
+
+        return result
+
+    # --------------------------------------------------------------------
+    # Pickling Methods
+
+    def __reduce__(self):
+        """Necessary for making this object picklable"""
+        d = {
+            "levels": list(self.levels),
+            "codes": list(self.codes),
+            "sortorder": self.sortorder,
+            "names": list(self.names),
+        }
+        return ibase._new_Index, (type(self), d), None
+
+    # --------------------------------------------------------------------
+
+    def __getitem__(self, key):
+        if is_scalar(key):
+            key = com.cast_scalar_indexer(key)
+
+            retval = []
+            for lev, level_codes in zip(self.levels, self.codes):
+                if level_codes[key] == -1:
+                    retval.append(np.nan)
+                else:
+                    retval.append(lev[level_codes[key]])
+
+            return tuple(retval)
+        else:
+            # in general cannot be sure whether the result will be sorted
+            sortorder = None
+            if com.is_bool_indexer(key):
+                key = np.asarray(key, dtype=bool)
+                sortorder = self.sortorder
+            elif isinstance(key, slice):
+                if key.step is None or key.step > 0:
+                    sortorder = self.sortorder
+            elif isinstance(key, Index):
+                key = np.asarray(key)
+
+            new_codes = [level_codes[key] for level_codes in self.codes]
+
+            return MultiIndex(
+                levels=self.levels,
+                codes=new_codes,
+                names=self.names,
+                sortorder=sortorder,
+                verify_integrity=False,
+            )
+
+    def _getitem_slice(self: MultiIndex, slobj: slice) -> MultiIndex:
+        """
+        Fastpath for __getitem__ when we know we have a slice.
+        """
+        sortorder = None
+        if slobj.step is None or slobj.step > 0:
+            sortorder = self.sortorder
+
+        new_codes = [level_codes[slobj] for level_codes in self.codes]
+
+        return type(self)(
+            levels=self.levels,
+            codes=new_codes,
+            names=self._names,
+            sortorder=sortorder,
+            verify_integrity=False,
+        )
+
+    @Appender(_index_shared_docs["take"] % _index_doc_kwargs)
+    def take(
+        self: MultiIndex,
+        indices,
+        axis: Axis = 0,
+        allow_fill: bool = True,
+        fill_value=None,
+        **kwargs,
+    ) -> MultiIndex:
+        nv.validate_take((), kwargs)
+        indices = ensure_platform_int(indices)
+
+        # only fill if we are passing a non-None fill_value
+        allow_fill = self._maybe_disallow_fill(allow_fill, fill_value, indices)
+
+        na_value = -1
+
+        taken = [lab.take(indices) for lab in self.codes]
+        if allow_fill:
+            mask = indices == -1
+            if mask.any():
+                masked = []
+                for new_label in taken:
+                    label_values = new_label
+                    label_values[mask] = na_value
+                    masked.append(np.asarray(label_values))
+                taken = masked
+
+        return MultiIndex(
+            levels=self.levels, codes=taken, names=self.names, verify_integrity=False
+        )
+
+    def append(self, other):
+        """
+        Append a collection of Index options together.
+
+        Parameters
+        ----------
+        other : Index or list/tuple of indices
+
+        Returns
+        -------
+        Index
+            The combined index.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a'], ['b']])
+        >>> mi
+        MultiIndex([('a', 'b')],
+                   )
+        >>> mi.append(mi)
+        MultiIndex([('a', 'b'), ('a', 'b')],
+                   )
+        """
+        if not isinstance(other, (list, tuple)):
+            other = [other]
+
+        if all(
+            (isinstance(o, MultiIndex) and o.nlevels >= self.nlevels) for o in other
+        ):
+            codes = []
+            levels = []
+            names = []
+            for i in range(self.nlevels):
+                level_values = self.levels[i]
+                for mi in other:
+                    level_values = level_values.union(mi.levels[i])
+                level_codes = [
+                    recode_for_categories(
+                        mi.codes[i], mi.levels[i], level_values, copy=False
+                    )
+                    for mi in ([self, *other])
+                ]
+                level_name = self.names[i]
+                if any(mi.names[i] != level_name for mi in other):
+                    level_name = None
+                codes.append(np.concatenate(level_codes))
+                levels.append(level_values)
+                names.append(level_name)
+            return MultiIndex(
+                codes=codes, levels=levels, names=names, verify_integrity=False
+            )
+
+        to_concat = (self._values,) + tuple(k._values for k in other)
+        new_tuples = np.concatenate(to_concat)
+
+        # if all(isinstance(x, MultiIndex) for x in other):
+        try:
+            # We only get here if other contains at least one index with tuples,
+            # setting names to None automatically
+            return MultiIndex.from_tuples(new_tuples)
+        except (TypeError, IndexError):
+            return Index(new_tuples)
+
+    def argsort(
+        self, *args, na_position: str = "last", **kwargs
+    ) -> npt.NDArray[np.intp]:
+        target = self._sort_levels_monotonic(raise_if_incomparable=True)
+        keys = [lev.codes for lev in target._get_codes_for_sorting()]
+        return lexsort_indexer(keys, na_position=na_position, codes_given=True)
+
+    @Appender(_index_shared_docs["repeat"] % _index_doc_kwargs)
+    def repeat(self, repeats: int, axis=None) -> MultiIndex:
+        nv.validate_repeat((), {"axis": axis})
+        # error: Incompatible types in assignment (expression has type "ndarray",
+        # variable has type "int")
+        repeats = ensure_platform_int(repeats)  # type: ignore[assignment]
+        return MultiIndex(
+            levels=self.levels,
+            codes=[
+                level_codes.view(np.ndarray).astype(np.intp, copy=False).repeat(repeats)
+                for level_codes in self.codes
+            ],
+            names=self.names,
+            sortorder=self.sortorder,
+            verify_integrity=False,
+        )
+
+    # error: Signature of "drop" incompatible with supertype "Index"
+    def drop(  # type: ignore[override]
+        self,
+        codes,
+        level: Index | np.ndarray | Iterable[Hashable] | None = None,
+        errors: IgnoreRaise = "raise",
+    ) -> MultiIndex:
+        """
+        Make a new :class:`pandas.MultiIndex` with the passed list of codes deleted.
+
+        Parameters
+        ----------
+        codes : array-like
+            Must be a list of tuples when ``level`` is not specified.
+        level : int or level name, default None
+        errors : str, default 'raise'
+
+        Returns
+        -------
+        MultiIndex
+
+        Examples
+        --------
+        >>> idx = pd.MultiIndex.from_product([(0, 1, 2), ('green', 'purple')],
+        ...                                  names=["number", "color"])
+        >>> idx
+        MultiIndex([(0,  'green'),
+                    (0, 'purple'),
+                    (1,  'green'),
+                    (1, 'purple'),
+                    (2,  'green'),
+                    (2, 'purple')],
+                   names=['number', 'color'])
+        >>> idx.drop([(1, 'green'), (2, 'purple')])
+        MultiIndex([(0,  'green'),
+                    (0, 'purple'),
+                    (1, 'purple'),
+                    (2,  'green')],
+                   names=['number', 'color'])
+
+        We can also drop from a specific level.
+
+        >>> idx.drop('green', level='color')
+        MultiIndex([(0, 'purple'),
+                    (1, 'purple'),
+                    (2, 'purple')],
+                   names=['number', 'color'])
+
+        >>> idx.drop([1, 2], level=0)
+        MultiIndex([(0,  'green'),
+                    (0, 'purple')],
+                   names=['number', 'color'])
+        """
+        if level is not None:
+            return self._drop_from_level(codes, level, errors)
+
+        if not isinstance(codes, (np.ndarray, Index)):
+            try:
+                codes = com.index_labels_to_array(codes, dtype=np.dtype("object"))
+            except ValueError:
+                pass
+
+        inds = []
+        for level_codes in codes:
+            try:
+                loc = self.get_loc(level_codes)
+                # get_loc returns either an integer, a slice, or a boolean
+                # mask
+                if isinstance(loc, int):
+                    inds.append(loc)
+                elif isinstance(loc, slice):
+                    step = loc.step if loc.step is not None else 1
+                    inds.extend(range(loc.start, loc.stop, step))
+                elif com.is_bool_indexer(loc):
+                    if self._lexsort_depth == 0:
+                        warnings.warn(
+                            "dropping on a non-lexsorted multi-index "
+                            "without a level parameter may impact performance.",
+                            PerformanceWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    loc = loc.nonzero()[0]
+                    inds.extend(loc)
+                else:
+                    msg = f"unsupported indexer of type {type(loc)}"
+                    raise AssertionError(msg)
+            except KeyError:
+                if errors != "ignore":
+                    raise
+
+        return self.delete(inds)
+
+    def _drop_from_level(
+        self, codes, level, errors: IgnoreRaise = "raise"
+    ) -> MultiIndex:
+        codes = com.index_labels_to_array(codes)
+        i = self._get_level_number(level)
+        index = self.levels[i]
+        values = index.get_indexer(codes)
+        # If nan should be dropped it will equal -1 here. We have to check which values
+        # are not nan and equal -1, this means they are missing in the index
+        nan_codes = isna(codes)
+        values[(np.equal(nan_codes, False)) & (values == -1)] = -2
+        if index.shape[0] == self.shape[0]:
+            values[np.equal(nan_codes, True)] = -2
+
+        not_found = codes[values == -2]
+        if len(not_found) != 0 and errors != "ignore":
+            raise KeyError(f"labels {not_found} not found in level")
+        mask = ~algos.isin(self.codes[i], values)
+
+        return self[mask]
+
+    def swaplevel(self, i=-2, j=-1) -> MultiIndex:
+        """
+        Swap level i with level j.
+
+        Calling this method does not change the ordering of the values.
+
+        Parameters
+        ----------
+        i : int, str, default -2
+            First level of index to be swapped. Can pass level name as string.
+            Type of parameters can be mixed.
+        j : int, str, default -1
+            Second level of index to be swapped. Can pass level name as string.
+            Type of parameters can be mixed.
+
+        Returns
+        -------
+        MultiIndex
+            A new MultiIndex.
+
+        See Also
+        --------
+        Series.swaplevel : Swap levels i and j in a MultiIndex.
+        DataFrame.swaplevel : Swap levels i and j in a MultiIndex on a
+            particular axis.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex(levels=[['a', 'b'], ['bb', 'aa']],
+        ...                    codes=[[0, 0, 1, 1], [0, 1, 0, 1]])
+        >>> mi
+        MultiIndex([('a', 'bb'),
+                    ('a', 'aa'),
+                    ('b', 'bb'),
+                    ('b', 'aa')],
+                   )
+        >>> mi.swaplevel(0, 1)
+        MultiIndex([('bb', 'a'),
+                    ('aa', 'a'),
+                    ('bb', 'b'),
+                    ('aa', 'b')],
+                   )
+        """
+        new_levels = list(self.levels)
+        new_codes = list(self.codes)
+        new_names = list(self.names)
+
+        i = self._get_level_number(i)
+        j = self._get_level_number(j)
+
+        new_levels[i], new_levels[j] = new_levels[j], new_levels[i]
+        new_codes[i], new_codes[j] = new_codes[j], new_codes[i]
+        new_names[i], new_names[j] = new_names[j], new_names[i]
+
+        return MultiIndex(
+            levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+        )
+
+    def reorder_levels(self, order) -> MultiIndex:
+        """
+        Rearrange levels using input order. May not drop or duplicate levels.
+
+        Parameters
+        ----------
+        order : list of int or list of str
+            List representing new level order. Reference level by number
+            (position) or by key (label).
+
+        Returns
+        -------
+        MultiIndex
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([[1, 2], [3, 4]], names=['x', 'y'])
+        >>> mi
+        MultiIndex([(1, 3),
+                    (2, 4)],
+                   names=['x', 'y'])
+
+        >>> mi.reorder_levels(order=[1, 0])
+        MultiIndex([(3, 1),
+                    (4, 2)],
+                   names=['y', 'x'])
+
+        >>> mi.reorder_levels(order=['y', 'x'])
+        MultiIndex([(3, 1),
+                    (4, 2)],
+                   names=['y', 'x'])
+        """
+        order = [self._get_level_number(i) for i in order]
+        result = self._reorder_ilevels(order)
+        return result
+
+    def _reorder_ilevels(self, order) -> MultiIndex:
+        if len(order) != self.nlevels:
+            raise AssertionError(
+                f"Length of order must be same as number of levels ({self.nlevels}), "
+                f"got {len(order)}"
+            )
+        new_levels = [self.levels[i] for i in order]
+        new_codes = [self.codes[i] for i in order]
+        new_names = [self.names[i] for i in order]
+
+        return MultiIndex(
+            levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+        )
+
+    def _recode_for_new_levels(
+        self, new_levels, copy: bool = True
+    ) -> Generator[np.ndarray, None, None]:
+        if len(new_levels) > self.nlevels:
+            raise AssertionError(
+                f"Length of new_levels ({len(new_levels)}) "
+                f"must be <= self.nlevels ({self.nlevels})"
+            )
+        for i in range(len(new_levels)):
+            yield recode_for_categories(
+                self.codes[i], self.levels[i], new_levels[i], copy=copy
+            )
+
+    def _get_codes_for_sorting(self) -> list[Categorical]:
+        """
+        we are categorizing our codes by using the
+        available categories (all, not just observed)
+        excluding any missing ones (-1); this is in preparation
+        for sorting, where we need to disambiguate that -1 is not
+        a valid valid
+        """
+
+        def cats(level_codes):
+            return np.arange(
+                np.array(level_codes).max() + 1 if len(level_codes) else 0,
+                dtype=level_codes.dtype,
+            )
+
+        return [
+            Categorical.from_codes(level_codes, cats(level_codes), True, validate=False)
+            for level_codes in self.codes
+        ]
+
+    def sortlevel(
+        self,
+        level: IndexLabel = 0,
+        ascending: bool | list[bool] = True,
+        sort_remaining: bool = True,
+        na_position: str = "first",
+    ) -> tuple[MultiIndex, npt.NDArray[np.intp]]:
+        """
+        Sort MultiIndex at the requested level.
+
+        The result will respect the original ordering of the associated
+        factor at that level.
+
+        Parameters
+        ----------
+        level : list-like, int or str, default 0
+            If a string is given, must be a name of the level.
+            If list-like must be names or ints of levels.
+        ascending : bool, default True
+            False to sort in descending order.
+            Can also be a list to specify a directed ordering.
+        sort_remaining : sort by the remaining levels after level
+        na_position : {'first' or 'last'}, default 'first'
+            Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
+            the end.
+
+            .. versionadded:: 2.1.0
+
+        Returns
+        -------
+        sorted_index : pd.MultiIndex
+            Resulting index.
+        indexer : np.ndarray[np.intp]
+            Indices of output values in original index.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([[0, 0], [2, 1]])
+        >>> mi
+        MultiIndex([(0, 2),
+                    (0, 1)],
+                   )
+
+        >>> mi.sortlevel()
+        (MultiIndex([(0, 1),
+                    (0, 2)],
+                   ), array([1, 0]))
+
+        >>> mi.sortlevel(sort_remaining=False)
+        (MultiIndex([(0, 2),
+                    (0, 1)],
+                   ), array([0, 1]))
+
+        >>> mi.sortlevel(1)
+        (MultiIndex([(0, 1),
+                    (0, 2)],
+                   ), array([1, 0]))
+
+        >>> mi.sortlevel(1, ascending=False)
+        (MultiIndex([(0, 2),
+                    (0, 1)],
+                   ), array([0, 1]))
+        """
+        if not is_list_like(level):
+            level = [level]
+        # error: Item "Hashable" of "Union[Hashable, Sequence[Hashable]]" has
+        # no attribute "__iter__" (not iterable)
+        level = [
+            self._get_level_number(lev) for lev in level  # type: ignore[union-attr]
+        ]
+        sortorder = None
+
+        codes = [self.codes[lev] for lev in level]
+        # we have a directed ordering via ascending
+        if isinstance(ascending, list):
+            if not len(level) == len(ascending):
+                raise ValueError("level must have same length as ascending")
+        elif sort_remaining:
+            codes.extend(
+                [self.codes[lev] for lev in range(len(self.levels)) if lev not in level]
+            )
+        else:
+            sortorder = level[0]
+
+        indexer = lexsort_indexer(
+            codes, orders=ascending, na_position=na_position, codes_given=True
+        )
+
+        indexer = ensure_platform_int(indexer)
+        new_codes = [level_codes.take(indexer) for level_codes in self.codes]
+
+        new_index = MultiIndex(
+            codes=new_codes,
+            levels=self.levels,
+            names=self.names,
+            sortorder=sortorder,
+            verify_integrity=False,
+        )
+
+        return new_index, indexer
+
+    def _wrap_reindex_result(self, target, indexer, preserve_names: bool):
+        if not isinstance(target, MultiIndex):
+            if indexer is None:
+                target = self
+            elif (indexer >= 0).all():
+                target = self.take(indexer)
+            else:
+                try:
+                    target = MultiIndex.from_tuples(target)
+                except TypeError:
+                    # not all tuples, see test_constructor_dict_multiindex_reindex_flat
+                    return target
+
+        target = self._maybe_preserve_names(target, preserve_names)
+        return target
+
+    def _maybe_preserve_names(self, target: Index, preserve_names: bool) -> Index:
+        if (
+            preserve_names
+            and target.nlevels == self.nlevels
+            and target.names != self.names
+        ):
+            target = target.copy(deep=False)
+            target.names = self.names
+        return target
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    def _check_indexing_error(self, key) -> None:
+        if not is_hashable(key) or is_iterator(key):
+            # We allow tuples if they are hashable, whereas other Index
+            #  subclasses require scalar.
+            # We have to explicitly exclude generators, as these are hashable.
+            raise InvalidIndexError(key)
+
+    @cache_readonly
+    def _should_fallback_to_positional(self) -> bool:
+        """
+        Should integer key(s) be treated as positional?
+        """
+        # GH#33355
+        return self.levels[0]._should_fallback_to_positional
+
+    def _get_indexer_strict(
+        self, key, axis_name: str
+    ) -> tuple[Index, npt.NDArray[np.intp]]:
+        keyarr = key
+        if not isinstance(keyarr, Index):
+            keyarr = com.asarray_tuplesafe(keyarr)
+
+        if len(keyarr) and not isinstance(keyarr[0], tuple):
+            indexer = self._get_indexer_level_0(keyarr)
+
+            self._raise_if_missing(key, indexer, axis_name)
+            return self[indexer], indexer
+
+        return super()._get_indexer_strict(key, axis_name)
+
+    def _raise_if_missing(self, key, indexer, axis_name: str) -> None:
+        keyarr = key
+        if not isinstance(key, Index):
+            keyarr = com.asarray_tuplesafe(key)
+
+        if len(keyarr) and not isinstance(keyarr[0], tuple):
+            # i.e. same condition for special case in MultiIndex._get_indexer_strict
+
+            mask = indexer == -1
+            if mask.any():
+                check = self.levels[0].get_indexer(keyarr)
+                cmask = check == -1
+                if cmask.any():
+                    raise KeyError(f"{keyarr[cmask]} not in index")
+                # We get here when levels still contain values which are not
+                # actually in Index anymore
+                raise KeyError(f"{keyarr} not in index")
+        else:
+            return super()._raise_if_missing(key, indexer, axis_name)
+
+    def _get_indexer_level_0(self, target) -> npt.NDArray[np.intp]:
+        """
+        Optimized equivalent to `self.get_level_values(0).get_indexer_for(target)`.
+        """
+        lev = self.levels[0]
+        codes = self._codes[0]
+        cat = Categorical.from_codes(codes=codes, categories=lev, validate=False)
+        ci = Index(cat)
+        return ci.get_indexer_for(target)
+
+    def get_slice_bound(
+        self,
+        label: Hashable | Sequence[Hashable],
+        side: Literal["left", "right"],
+    ) -> int:
+        """
+        For an ordered MultiIndex, compute slice bound
+        that corresponds to given label.
+
+        Returns leftmost (one-past-the-rightmost if `side=='right') position
+        of given label.
+
+        Parameters
+        ----------
+        label : object or tuple of objects
+        side : {'left', 'right'}
+
+        Returns
+        -------
+        int
+            Index of label.
+
+        Notes
+        -----
+        This method only works if level 0 index of the MultiIndex is lexsorted.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abbc'), list('gefd')])
+
+        Get the locations from the leftmost 'b' in the first level
+        until the end of the multiindex:
+
+        >>> mi.get_slice_bound('b', side="left")
+        1
+
+        Like above, but if you get the locations from the rightmost
+        'b' in the first level and 'f' in the second level:
+
+        >>> mi.get_slice_bound(('b','f'), side="right")
+        3
+
+        See Also
+        --------
+        MultiIndex.get_loc : Get location for a label or a tuple of labels.
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+        """
+        if not isinstance(label, tuple):
+            label = (label,)
+        return self._partial_tup_index(label, side=side)
+
+    # pylint: disable-next=useless-parent-delegation
+    def slice_locs(self, start=None, end=None, step=None) -> tuple[int, int]:
+        """
+        For an ordered MultiIndex, compute the slice locations for input
+        labels.
+
+        The input labels can be tuples representing partial levels, e.g. for a
+        MultiIndex with 3 levels, you can pass a single value (corresponding to
+        the first level), or a 1-, 2-, or 3-tuple.
+
+        Parameters
+        ----------
+        start : label or tuple, default None
+            If None, defaults to the beginning
+        end : label or tuple
+            If None, defaults to the end
+        step : int or None
+            Slice step
+
+        Returns
+        -------
+        (start, end) : (int, int)
+
+        Notes
+        -----
+        This method only works if the MultiIndex is properly lexsorted. So,
+        if only the first 2 levels of a 3-level MultiIndex are lexsorted,
+        you can only pass two levels to ``.slice_locs``.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abbd'), list('deff')],
+        ...                                names=['A', 'B'])
+
+        Get the slice locations from the beginning of 'b' in the first level
+        until the end of the multiindex:
+
+        >>> mi.slice_locs(start='b')
+        (1, 4)
+
+        Like above, but stop at the end of 'b' in the first level and 'f' in
+        the second level:
+
+        >>> mi.slice_locs(start='b', end=('b', 'f'))
+        (1, 3)
+
+        See Also
+        --------
+        MultiIndex.get_loc : Get location for a label or a tuple of labels.
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+        """
+        # This function adds nothing to its parent implementation (the magic
+        # happens in get_slice_bound method), but it adds meaningful doc.
+        return super().slice_locs(start, end, step)
+
+    def _partial_tup_index(self, tup: tuple, side: Literal["left", "right"] = "left"):
+        if len(tup) > self._lexsort_depth:
+            raise UnsortedIndexError(
+                f"Key length ({len(tup)}) was greater than MultiIndex lexsort depth "
+                f"({self._lexsort_depth})"
+            )
+
+        n = len(tup)
+        start, end = 0, len(self)
+        zipped = zip(tup, self.levels, self.codes)
+        for k, (lab, lev, level_codes) in enumerate(zipped):
+            section = level_codes[start:end]
+
+            loc: npt.NDArray[np.intp] | np.intp | int
+            if lab not in lev and not isna(lab):
+                # short circuit
+                try:
+                    loc = algos.searchsorted(lev, lab, side=side)
+                except TypeError as err:
+                    # non-comparable e.g. test_slice_locs_with_type_mismatch
+                    raise TypeError(f"Level type mismatch: {lab}") from err
+                if not is_integer(loc):
+                    # non-comparable level, e.g. test_groupby_example
+                    raise TypeError(f"Level type mismatch: {lab}")
+                if side == "right" and loc >= 0:
+                    loc -= 1
+                return start + algos.searchsorted(section, loc, side=side)
+
+            idx = self._get_loc_single_level_index(lev, lab)
+            if isinstance(idx, slice) and k < n - 1:
+                # Get start and end value from slice, necessary when a non-integer
+                # interval is given as input GH#37707
+                start = idx.start
+                end = idx.stop
+            elif k < n - 1:
+                # error: Incompatible types in assignment (expression has type
+                # "Union[ndarray[Any, dtype[signedinteger[Any]]]
+                end = start + algos.searchsorted(  # type: ignore[assignment]
+                    section, idx, side="right"
+                )
+                # error: Incompatible types in assignment (expression has type
+                # "Union[ndarray[Any, dtype[signedinteger[Any]]]
+                start = start + algos.searchsorted(  # type: ignore[assignment]
+                    section, idx, side="left"
+                )
+            elif isinstance(idx, slice):
+                idx = idx.start
+                return start + algos.searchsorted(section, idx, side=side)
+            else:
+                return start + algos.searchsorted(section, idx, side=side)
+
+    def _get_loc_single_level_index(self, level_index: Index, key: Hashable) -> int:
+        """
+        If key is NA value, location of index unify as -1.
+
+        Parameters
+        ----------
+        level_index: Index
+        key : label
+
+        Returns
+        -------
+        loc : int
+            If key is NA value, loc is -1
+            Else, location of key in index.
+
+        See Also
+        --------
+        Index.get_loc : The get_loc method for (single-level) index.
+        """
+        if is_scalar(key) and isna(key):
+            # TODO: need is_valid_na_for_dtype(key, level_index.dtype)
+            return -1
+        else:
+            return level_index.get_loc(key)
+
+    def get_loc(self, key):
+        """
+        Get location for a label or a tuple of labels.
+
+        The location is returned as an integer/slice or boolean
+        mask.
+
+        Parameters
+        ----------
+        key : label or tuple of labels (one for each level)
+
+        Returns
+        -------
+        int, slice object or boolean mask
+            If the key is past the lexsort depth, the return may be a
+            boolean mask array, otherwise it is always a slice or int.
+
+        See Also
+        --------
+        Index.get_loc : The get_loc method for (single-level) index.
+        MultiIndex.slice_locs : Get slice location given start label(s) and
+                                end label(s).
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+
+        Notes
+        -----
+        The key cannot be a slice, list of same-level labels, a boolean mask,
+        or a sequence of such. If you want to use those, use
+        :meth:`MultiIndex.get_locs` instead.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
+
+        >>> mi.get_loc('b')
+        slice(1, 3, None)
+
+        >>> mi.get_loc(('b', 'e'))
+        1
+        """
+        self._check_indexing_error(key)
+
+        def _maybe_to_slice(loc):
+            """convert integer indexer to boolean mask or slice if possible"""
+            if not isinstance(loc, np.ndarray) or loc.dtype != np.intp:
+                return loc
+
+            loc = lib.maybe_indices_to_slice(loc, len(self))
+            if isinstance(loc, slice):
+                return loc
+
+            mask = np.empty(len(self), dtype="bool")
+            mask.fill(False)
+            mask[loc] = True
+            return mask
+
+        if not isinstance(key, tuple):
+            loc = self._get_level_indexer(key, level=0)
+            return _maybe_to_slice(loc)
+
+        keylen = len(key)
+        if self.nlevels < keylen:
+            raise KeyError(
+                f"Key length ({keylen}) exceeds index depth ({self.nlevels})"
+            )
+
+        if keylen == self.nlevels and self.is_unique:
+            # TODO: what if we have an IntervalIndex level?
+            #  i.e. do we need _index_as_unique on that level?
+            try:
+                return self._engine.get_loc(key)
+            except KeyError as err:
+                raise KeyError(key) from err
+            except TypeError:
+                # e.g. test_partial_slicing_with_multiindex partial string slicing
+                loc, _ = self.get_loc_level(key, list(range(self.nlevels)))
+                return loc
+
+        # -- partial selection or non-unique index
+        # break the key into 2 parts based on the lexsort_depth of the index;
+        # the first part returns a continuous slice of the index; the 2nd part
+        # needs linear search within the slice
+        i = self._lexsort_depth
+        lead_key, follow_key = key[:i], key[i:]
+
+        if not lead_key:
+            start = 0
+            stop = len(self)
+        else:
+            try:
+                start, stop = self.slice_locs(lead_key, lead_key)
+            except TypeError as err:
+                # e.g. test_groupby_example key = ((0, 0, 1, 2), "new_col")
+                #  when self has 5 integer levels
+                raise KeyError(key) from err
+
+        if start == stop:
+            raise KeyError(key)
+
+        if not follow_key:
+            return slice(start, stop)
+
+        warnings.warn(
+            "indexing past lexsort depth may impact performance.",
+            PerformanceWarning,
+            stacklevel=find_stack_level(),
+        )
+
+        loc = np.arange(start, stop, dtype=np.intp)
+
+        for i, k in enumerate(follow_key, len(lead_key)):
+            mask = self.codes[i][loc] == self._get_loc_single_level_index(
+                self.levels[i], k
+            )
+            if not mask.all():
+                loc = loc[mask]
+            if not len(loc):
+                raise KeyError(key)
+
+        return _maybe_to_slice(loc) if len(loc) != stop - start else slice(start, stop)
+
+    def get_loc_level(self, key, level: IndexLabel = 0, drop_level: bool = True):
+        """
+        Get location and sliced index for requested label(s)/level(s).
+
+        Parameters
+        ----------
+        key : label or sequence of labels
+        level : int/level name or list thereof, optional
+        drop_level : bool, default True
+            If ``False``, the resulting index will not drop any level.
+
+        Returns
+        -------
+        tuple
+            A 2-tuple where the elements :
+
+            Element 0: int, slice object or boolean array.
+
+            Element 1: The resulting sliced multiindex/index. If the key
+            contains all levels, this will be ``None``.
+
+        See Also
+        --------
+        MultiIndex.get_loc  : Get location for a label or a tuple of labels.
+        MultiIndex.get_locs : Get location for a label/slice/list/mask or a
+                              sequence of such.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')],
+        ...                                names=['A', 'B'])
+
+        >>> mi.get_loc_level('b')
+        (slice(1, 3, None), Index(['e', 'f'], dtype='object', name='B'))
+
+        >>> mi.get_loc_level('e', level='B')
+        (array([False,  True, False]), Index(['b'], dtype='object', name='A'))
+
+        >>> mi.get_loc_level(['b', 'e'])
+        (1, None)
+        """
+        if not isinstance(level, (list, tuple)):
+            level = self._get_level_number(level)
+        else:
+            level = [self._get_level_number(lev) for lev in level]
+
+        loc, mi = self._get_loc_level(key, level=level)
+        if not drop_level:
+            if lib.is_integer(loc):
+                # Slice index must be an integer or None
+                mi = self[loc : loc + 1]
+            else:
+                mi = self[loc]
+        return loc, mi
+
+    def _get_loc_level(self, key, level: int | list[int] = 0):
+        """
+        get_loc_level but with `level` known to be positional, not name-based.
+        """
+
+        # different name to distinguish from maybe_droplevels
+        def maybe_mi_droplevels(indexer, levels):
+            """
+            If level does not exist or all levels were dropped, the exception
+            has to be handled outside.
+            """
+            new_index = self[indexer]
+
+            for i in sorted(levels, reverse=True):
+                new_index = new_index._drop_level_numbers([i])
+
+            return new_index
+
+        if isinstance(level, (tuple, list)):
+            if len(key) != len(level):
+                raise AssertionError(
+                    "Key for location must have same length as number of levels"
+                )
+            result = None
+            for lev, k in zip(level, key):
+                loc, new_index = self._get_loc_level(k, level=lev)
+                if isinstance(loc, slice):
+                    mask = np.zeros(len(self), dtype=bool)
+                    mask[loc] = True
+                    loc = mask
+                result = loc if result is None else result & loc
+
+            try:
+                # FIXME: we should be only dropping levels on which we are
+                #  scalar-indexing
+                mi = maybe_mi_droplevels(result, level)
+            except ValueError:
+                # droplevel failed because we tried to drop all levels,
+                #  i.e. len(level) == self.nlevels
+                mi = self[result]
+
+            return result, mi
+
+        # kludge for #1796
+        if isinstance(key, list):
+            key = tuple(key)
+
+        if isinstance(key, tuple) and level == 0:
+            try:
+                # Check if this tuple is a single key in our first level
+                if key in self.levels[0]:
+                    indexer = self._get_level_indexer(key, level=level)
+                    new_index = maybe_mi_droplevels(indexer, [0])
+                    return indexer, new_index
+            except (TypeError, InvalidIndexError):
+                pass
+
+            if not any(isinstance(k, slice) for k in key):
+                if len(key) == self.nlevels and self.is_unique:
+                    # Complete key in unique index -> standard get_loc
+                    try:
+                        return (self._engine.get_loc(key), None)
+                    except KeyError as err:
+                        raise KeyError(key) from err
+                    except TypeError:
+                        # e.g. partial string indexing
+                        #  test_partial_string_timestamp_multiindex
+                        pass
+
+                # partial selection
+                indexer = self.get_loc(key)
+                ilevels = [i for i in range(len(key)) if key[i] != slice(None, None)]
+                if len(ilevels) == self.nlevels:
+                    if is_integer(indexer):
+                        # we are dropping all levels
+                        return indexer, None
+
+                    # TODO: in some cases we still need to drop some levels,
+                    #  e.g. test_multiindex_perf_warn
+                    # test_partial_string_timestamp_multiindex
+                    ilevels = [
+                        i
+                        for i in range(len(key))
+                        if (
+                            not isinstance(key[i], str)
+                            or not self.levels[i]._supports_partial_string_indexing
+                        )
+                        and key[i] != slice(None, None)
+                    ]
+                    if len(ilevels) == self.nlevels:
+                        # TODO: why?
+                        ilevels = []
+                return indexer, maybe_mi_droplevels(indexer, ilevels)
+
+            else:
+                indexer = None
+                for i, k in enumerate(key):
+                    if not isinstance(k, slice):
+                        loc_level = self._get_level_indexer(k, level=i)
+                        if isinstance(loc_level, slice):
+                            if com.is_null_slice(loc_level) or com.is_full_slice(
+                                loc_level, len(self)
+                            ):
+                                # everything
+                                continue
+
+                            # e.g. test_xs_IndexSlice_argument_not_implemented
+                            k_index = np.zeros(len(self), dtype=bool)
+                            k_index[loc_level] = True
+
+                        else:
+                            k_index = loc_level
+
+                    elif com.is_null_slice(k):
+                        # taking everything, does not affect `indexer` below
+                        continue
+
+                    else:
+                        # FIXME: this message can be inaccurate, e.g.
+                        #  test_series_varied_multiindex_alignment
+                        raise TypeError(f"Expected label or tuple of labels, got {key}")
+
+                    if indexer is None:
+                        indexer = k_index
+                    else:
+                        indexer &= k_index
+                if indexer is None:
+                    indexer = slice(None, None)
+                ilevels = [i for i in range(len(key)) if key[i] != slice(None, None)]
+                return indexer, maybe_mi_droplevels(indexer, ilevels)
+        else:
+            indexer = self._get_level_indexer(key, level=level)
+            if (
+                isinstance(key, str)
+                and self.levels[level]._supports_partial_string_indexing
+            ):
+                # check to see if we did an exact lookup vs sliced
+                check = self.levels[level].get_loc(key)
+                if not is_integer(check):
+                    # e.g. test_partial_string_timestamp_multiindex
+                    return indexer, self[indexer]
+
+            try:
+                result_index = maybe_mi_droplevels(indexer, [level])
+            except ValueError:
+                result_index = self[indexer]
+
+            return indexer, result_index
+
+    def _get_level_indexer(
+        self, key, level: int = 0, indexer: npt.NDArray[np.bool_] | None = None
+    ):
+        # `level` kwarg is _always_ positional, never name
+        # return a boolean array or slice showing where the key is
+        # in the totality of values
+        # if the indexer is provided, then use this
+
+        level_index = self.levels[level]
+        level_codes = self.codes[level]
+
+        def convert_indexer(start, stop, step, indexer=indexer, codes=level_codes):
+            # Compute a bool indexer to identify the positions to take.
+            # If we have an existing indexer, we only need to examine the
+            # subset of positions where the existing indexer is True.
+            if indexer is not None:
+                # we only need to look at the subset of codes where the
+                # existing indexer equals True
+                codes = codes[indexer]
+
+            if step is None or step == 1:
+                new_indexer = (codes >= start) & (codes < stop)
+            else:
+                r = np.arange(start, stop, step, dtype=codes.dtype)
+                new_indexer = algos.isin(codes, r)
+
+            if indexer is None:
+                return new_indexer
+
+            indexer = indexer.copy()
+            indexer[indexer] = new_indexer
+            return indexer
+
+        if isinstance(key, slice):
+            # handle a slice, returning a slice if we can
+            # otherwise a boolean indexer
+            step = key.step
+            is_negative_step = step is not None and step < 0
+
+            try:
+                if key.start is not None:
+                    start = level_index.get_loc(key.start)
+                elif is_negative_step:
+                    start = len(level_index) - 1
+                else:
+                    start = 0
+
+                if key.stop is not None:
+                    stop = level_index.get_loc(key.stop)
+                elif is_negative_step:
+                    stop = 0
+                elif isinstance(start, slice):
+                    stop = len(level_index)
+                else:
+                    stop = len(level_index) - 1
+            except KeyError:
+                # we have a partial slice (like looking up a partial date
+                # string)
+                start = stop = level_index.slice_indexer(key.start, key.stop, key.step)
+                step = start.step
+
+            if isinstance(start, slice) or isinstance(stop, slice):
+                # we have a slice for start and/or stop
+                # a partial date slicer on a DatetimeIndex generates a slice
+                # note that the stop ALREADY includes the stopped point (if
+                # it was a string sliced)
+                start = getattr(start, "start", start)
+                stop = getattr(stop, "stop", stop)
+                return convert_indexer(start, stop, step)
+
+            elif level > 0 or self._lexsort_depth == 0 or step is not None:
+                # need to have like semantics here to right
+                # searching as when we are using a slice
+                # so adjust the stop by 1 (so we include stop)
+                stop = (stop - 1) if is_negative_step else (stop + 1)
+                return convert_indexer(start, stop, step)
+            else:
+                # sorted, so can return slice object -> view
+                i = algos.searchsorted(level_codes, start, side="left")
+                j = algos.searchsorted(level_codes, stop, side="right")
+                return slice(i, j, step)
+
+        else:
+            idx = self._get_loc_single_level_index(level_index, key)
+
+            if level > 0 or self._lexsort_depth == 0:
+                # Desired level is not sorted
+                if isinstance(idx, slice):
+                    # test_get_loc_partial_timestamp_multiindex
+                    locs = (level_codes >= idx.start) & (level_codes < idx.stop)
+                    return locs
+
+                locs = np.asarray(level_codes == idx, dtype=bool)
+
+                if not locs.any():
+                    # The label is present in self.levels[level] but unused:
+                    raise KeyError(key)
+                return locs
+
+            if isinstance(idx, slice):
+                # e.g. test_partial_string_timestamp_multiindex
+                start = algos.searchsorted(level_codes, idx.start, side="left")
+                # NB: "left" here bc of slice semantics
+                end = algos.searchsorted(level_codes, idx.stop, side="left")
+            else:
+                start = algos.searchsorted(level_codes, idx, side="left")
+                end = algos.searchsorted(level_codes, idx, side="right")
+
+            if start == end:
+                # The label is present in self.levels[level] but unused:
+                raise KeyError(key)
+            return slice(start, end)
+
+    def get_locs(self, seq) -> npt.NDArray[np.intp]:
+        """
+        Get location for a sequence of labels.
+
+        Parameters
+        ----------
+        seq : label, slice, list, mask or a sequence of such
+           You should use one of the above for each level.
+           If a level should not be used, set it to ``slice(None)``.
+
+        Returns
+        -------
+        numpy.ndarray
+            NumPy array of integers suitable for passing to iloc.
+
+        See Also
+        --------
+        MultiIndex.get_loc : Get location for a label or a tuple of labels.
+        MultiIndex.slice_locs : Get slice location given start label(s) and
+                                end label(s).
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([list('abb'), list('def')])
+
+        >>> mi.get_locs('b')  # doctest: +SKIP
+        array([1, 2], dtype=int64)
+
+        >>> mi.get_locs([slice(None), ['e', 'f']])  # doctest: +SKIP
+        array([1, 2], dtype=int64)
+
+        >>> mi.get_locs([[True, False, True], slice('e', 'f')])  # doctest: +SKIP
+        array([2], dtype=int64)
+        """
+
+        # must be lexsorted to at least as many levels
+        true_slices = [i for (i, s) in enumerate(com.is_true_slices(seq)) if s]
+        if true_slices and true_slices[-1] >= self._lexsort_depth:
+            raise UnsortedIndexError(
+                "MultiIndex slicing requires the index to be lexsorted: slicing "
+                f"on levels {true_slices}, lexsort depth {self._lexsort_depth}"
+            )
+
+        if any(x is Ellipsis for x in seq):
+            raise NotImplementedError(
+                "MultiIndex does not support indexing with Ellipsis"
+            )
+
+        n = len(self)
+
+        def _to_bool_indexer(indexer) -> npt.NDArray[np.bool_]:
+            if isinstance(indexer, slice):
+                new_indexer = np.zeros(n, dtype=np.bool_)
+                new_indexer[indexer] = True
+                return new_indexer
+            return indexer
+
+        # a bool indexer for the positions we want to take
+        indexer: npt.NDArray[np.bool_] | None = None
+
+        for i, k in enumerate(seq):
+            lvl_indexer: npt.NDArray[np.bool_] | slice | None = None
+
+            if com.is_bool_indexer(k):
+                if len(k) != n:
+                    raise ValueError(
+                        "cannot index with a boolean indexer that "
+                        "is not the same length as the index"
+                    )
+                lvl_indexer = np.asarray(k)
+                if indexer is None:
+                    lvl_indexer = lvl_indexer.copy()
+
+            elif is_list_like(k):
+                # a collection of labels to include from this level (these are or'd)
+
+                # GH#27591 check if this is a single tuple key in the level
+                try:
+                    lvl_indexer = self._get_level_indexer(k, level=i, indexer=indexer)
+                except (InvalidIndexError, TypeError, KeyError) as err:
+                    # InvalidIndexError e.g. non-hashable, fall back to treating
+                    #  this as a sequence of labels
+                    # KeyError it can be ambiguous if this is a label or sequence
+                    #  of labels
+                    #  github.com/pandas-dev/pandas/issues/39424#issuecomment-871626708
+                    for x in k:
+                        if not is_hashable(x):
+                            # e.g. slice
+                            raise err
+                        # GH 39424: Ignore not founds
+                        # GH 42351: No longer ignore not founds & enforced in 2.0
+                        # TODO: how to handle IntervalIndex level? (no test cases)
+                        item_indexer = self._get_level_indexer(
+                            x, level=i, indexer=indexer
+                        )
+                        if lvl_indexer is None:
+                            lvl_indexer = _to_bool_indexer(item_indexer)
+                        elif isinstance(item_indexer, slice):
+                            lvl_indexer[item_indexer] = True  # type: ignore[index]
+                        else:
+                            lvl_indexer |= item_indexer
+
+                if lvl_indexer is None:
+                    # no matches we are done
+                    # test_loc_getitem_duplicates_multiindex_empty_indexer
+                    return np.array([], dtype=np.intp)
+
+            elif com.is_null_slice(k):
+                # empty slice
+                if indexer is None and i == len(seq) - 1:
+                    return np.arange(n, dtype=np.intp)
+                continue
+
+            else:
+                # a slice or a single label
+                lvl_indexer = self._get_level_indexer(k, level=i, indexer=indexer)
+
+            # update indexer
+            lvl_indexer = _to_bool_indexer(lvl_indexer)
+            if indexer is None:
+                indexer = lvl_indexer
+            else:
+                indexer &= lvl_indexer
+                if not np.any(indexer) and np.any(lvl_indexer):
+                    raise KeyError(seq)
+
+        # empty indexer
+        if indexer is None:
+            return np.array([], dtype=np.intp)
+
+        pos_indexer = indexer.nonzero()[0]
+        return self._reorder_indexer(seq, pos_indexer)
+
+    # --------------------------------------------------------------------
+
+    def _reorder_indexer(
+        self,
+        seq: tuple[Scalar | Iterable | AnyArrayLike, ...],
+        indexer: npt.NDArray[np.intp],
+    ) -> npt.NDArray[np.intp]:
+        """
+        Reorder an indexer of a MultiIndex (self) so that the labels are in the
+        same order as given in seq
+
+        Parameters
+        ----------
+        seq : label/slice/list/mask or a sequence of such
+        indexer: a position indexer of self
+
+        Returns
+        -------
+        indexer : a sorted position indexer of self ordered as seq
+        """
+
+        # check if sorting is necessary
+        need_sort = False
+        for i, k in enumerate(seq):
+            if com.is_null_slice(k) or com.is_bool_indexer(k) or is_scalar(k):
+                pass
+            elif is_list_like(k):
+                if len(k) <= 1:  # type: ignore[arg-type]
+                    pass
+                elif self._is_lexsorted():
+                    # If the index is lexsorted and the list_like label
+                    # in seq are sorted then we do not need to sort
+                    k_codes = self.levels[i].get_indexer(k)
+                    k_codes = k_codes[k_codes >= 0]  # Filter absent keys
+                    # True if the given codes are not ordered
+                    need_sort = (k_codes[:-1] > k_codes[1:]).any()
+                else:
+                    need_sort = True
+            elif isinstance(k, slice):
+                if self._is_lexsorted():
+                    need_sort = k.step is not None and k.step < 0
+                else:
+                    need_sort = True
+            else:
+                need_sort = True
+            if need_sort:
+                break
+        if not need_sort:
+            return indexer
+
+        n = len(self)
+        keys: tuple[np.ndarray, ...] = ()
+        # For each level of the sequence in seq, map the level codes with the
+        # order they appears in a list-like sequence
+        # This mapping is then use to reorder the indexer
+        for i, k in enumerate(seq):
+            if is_scalar(k):
+                # GH#34603 we want to treat a scalar the same as an all equal list
+                k = [k]
+            if com.is_bool_indexer(k):
+                new_order = np.arange(n)[indexer]
+            elif is_list_like(k):
+                # Generate a map with all level codes as sorted initially
+                if not isinstance(k, (np.ndarray, ExtensionArray, Index, ABCSeries)):
+                    k = sanitize_array(k, None)
+                k = algos.unique(k)
+                key_order_map = np.ones(len(self.levels[i]), dtype=np.uint64) * len(
+                    self.levels[i]
+                )
+                # Set order as given in the indexer list
+                level_indexer = self.levels[i].get_indexer(k)
+                level_indexer = level_indexer[level_indexer >= 0]  # Filter absent keys
+                key_order_map[level_indexer] = np.arange(len(level_indexer))
+
+                new_order = key_order_map[self.codes[i][indexer]]
+            elif isinstance(k, slice) and k.step is not None and k.step < 0:
+                # flip order for negative step
+                new_order = np.arange(n)[::-1][indexer]
+            elif isinstance(k, slice) and k.start is None and k.stop is None:
+                # slice(None) should not determine order GH#31330
+                new_order = np.ones((n,), dtype=np.intp)[indexer]
+            else:
+                # For all other case, use the same order as the level
+                new_order = np.arange(n)[indexer]
+            keys = (new_order,) + keys
+
+        # Find the reordering using lexsort on the keys mapping
+        ind = np.lexsort(keys)
+        return indexer[ind]
+
+    def truncate(self, before=None, after=None) -> MultiIndex:
+        """
+        Slice index between two labels / tuples, return new MultiIndex.
+
+        Parameters
+        ----------
+        before : label or tuple, can be partial. Default None
+            None defaults to start.
+        after : label or tuple, can be partial. Default None
+            None defaults to end.
+
+        Returns
+        -------
+        MultiIndex
+            The truncated MultiIndex.
+
+        Examples
+        --------
+        >>> mi = pd.MultiIndex.from_arrays([['a', 'b', 'c'], ['x', 'y', 'z']])
+        >>> mi
+        MultiIndex([('a', 'x'), ('b', 'y'), ('c', 'z')],
+                   )
+        >>> mi.truncate(before='a', after='b')
+        MultiIndex([('a', 'x'), ('b', 'y')],
+                   )
+        """
+        if after and before and after < before:
+            raise ValueError("after < before")
+
+        i, j = self.levels[0].slice_locs(before, after)
+        left, right = self.slice_locs(before, after)
+
+        new_levels = list(self.levels)
+        new_levels[0] = new_levels[0][i:j]
+
+        new_codes = [level_codes[left:right] for level_codes in self.codes]
+        new_codes[0] = new_codes[0] - i
+
+        return MultiIndex(
+            levels=new_levels,
+            codes=new_codes,
+            names=self._names,
+            verify_integrity=False,
+        )
+
+    def equals(self, other: object) -> bool:
+        """
+        Determines if two MultiIndex objects have the same labeling information
+        (the levels themselves do not necessarily have to be the same)
+
+        See Also
+        --------
+        equal_levels
+        """
+        if self.is_(other):
+            return True
+
+        if not isinstance(other, Index):
+            return False
+
+        if len(self) != len(other):
+            return False
+
+        if not isinstance(other, MultiIndex):
+            # d-level MultiIndex can equal d-tuple Index
+            if not self._should_compare(other):
+                # object Index or Categorical[object] may contain tuples
+                return False
+            return array_equivalent(self._values, other._values)
+
+        if self.nlevels != other.nlevels:
+            return False
+
+        for i in range(self.nlevels):
+            self_codes = self.codes[i]
+            other_codes = other.codes[i]
+            self_mask = self_codes == -1
+            other_mask = other_codes == -1
+            if not np.array_equal(self_mask, other_mask):
+                return False
+            self_codes = self_codes[~self_mask]
+            self_values = self.levels[i]._values.take(self_codes)
+
+            other_codes = other_codes[~other_mask]
+            other_values = other.levels[i]._values.take(other_codes)
+
+            # since we use NaT both datetime64 and timedelta64 we can have a
+            # situation where a level is typed say timedelta64 in self (IOW it
+            # has other values than NaT) but types datetime64 in other (where
+            # its all NaT) but these are equivalent
+            if len(self_values) == 0 and len(other_values) == 0:
+                continue
+
+            if not isinstance(self_values, np.ndarray):
+                # i.e. ExtensionArray
+                if not self_values.equals(other_values):
+                    return False
+            elif not isinstance(other_values, np.ndarray):
+                # i.e. other is ExtensionArray
+                if not other_values.equals(self_values):
+                    return False
+            else:
+                if not array_equivalent(self_values, other_values):
+                    return False
+
+        return True
+
+    def equal_levels(self, other: MultiIndex) -> bool:
+        """
+        Return True if the levels of both MultiIndex objects are the same
+
+        """
+        if self.nlevels != other.nlevels:
+            return False
+
+        for i in range(self.nlevels):
+            if not self.levels[i].equals(other.levels[i]):
+                return False
+        return True
+
+    # --------------------------------------------------------------------
+    # Set Methods
+
+    def _union(self, other, sort) -> MultiIndex:
+        other, result_names = self._convert_can_do_setop(other)
+        if other.has_duplicates:
+            # This is only necessary if other has dupes,
+            # otherwise difference is faster
+            result = super()._union(other, sort)
+
+            if isinstance(result, MultiIndex):
+                return result
+            return MultiIndex.from_arrays(
+                zip(*result), sortorder=None, names=result_names
+            )
+
+        else:
+            right_missing = other.difference(self, sort=False)
+            if len(right_missing):
+                result = self.append(right_missing)
+            else:
+                result = self._get_reconciled_name_object(other)
+
+            if sort is not False:
+                try:
+                    result = result.sort_values()
+                except TypeError:
+                    if sort is True:
+                        raise
+                    warnings.warn(
+                        "The values in the array are unorderable. "
+                        "Pass `sort=False` to suppress this warning.",
+                        RuntimeWarning,
+                        stacklevel=find_stack_level(),
+                    )
+            return result
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        return is_object_dtype(dtype)
+
+    def _get_reconciled_name_object(self, other) -> MultiIndex:
+        """
+        If the result of a set operation will be self,
+        return self, unless the names change, in which
+        case make a shallow copy of self.
+        """
+        names = self._maybe_match_names(other)
+        if self.names != names:
+            # error: Cannot determine type of "rename"
+            return self.rename(names)  # type: ignore[has-type]
+        return self
+
+    def _maybe_match_names(self, other):
+        """
+        Try to find common names to attach to the result of an operation between
+        a and b. Return a consensus list of names if they match at least partly
+        or list of None if they have completely different names.
+        """
+        if len(self.names) != len(other.names):
+            return [None] * len(self.names)
+        names = []
+        for a_name, b_name in zip(self.names, other.names):
+            if a_name == b_name:
+                names.append(a_name)
+            else:
+                # TODO: what if they both have np.nan for their names?
+                names.append(None)
+        return names
+
+    def _wrap_intersection_result(self, other, result) -> MultiIndex:
+        _, result_names = self._convert_can_do_setop(other)
+        return result.set_names(result_names)
+
+    def _wrap_difference_result(self, other, result: MultiIndex) -> MultiIndex:
+        _, result_names = self._convert_can_do_setop(other)
+
+        if len(result) == 0:
+            return result.remove_unused_levels().set_names(result_names)
+        else:
+            return result.set_names(result_names)
+
+    def _convert_can_do_setop(self, other):
+        result_names = self.names
+
+        if not isinstance(other, Index):
+            if len(other) == 0:
+                return self[:0], self.names
+            else:
+                msg = "other must be a MultiIndex or a list of tuples"
+                try:
+                    other = MultiIndex.from_tuples(other, names=self.names)
+                except (ValueError, TypeError) as err:
+                    # ValueError raised by tuples_to_object_array if we
+                    #  have non-object dtype
+                    raise TypeError(msg) from err
+        else:
+            result_names = get_unanimous_names(self, other)
+
+        return other, result_names
+
+    # --------------------------------------------------------------------
+
+    @doc(Index.astype)
+    def astype(self, dtype, copy: bool = True):
+        dtype = pandas_dtype(dtype)
+        if isinstance(dtype, CategoricalDtype):
+            msg = "> 1 ndim Categorical are not supported at this time"
+            raise NotImplementedError(msg)
+        if not is_object_dtype(dtype):
+            raise TypeError(
+                "Setting a MultiIndex dtype to anything other than object "
+                "is not supported"
+            )
+        if copy is True:
+            return self._view()
+        return self
+
+    def _validate_fill_value(self, item):
+        if isinstance(item, MultiIndex):
+            # GH#43212
+            if item.nlevels != self.nlevels:
+                raise ValueError("Item must have length equal to number of levels.")
+            return item._values
+        elif not isinstance(item, tuple):
+            # Pad the key with empty strings if lower levels of the key
+            # aren't specified:
+            item = (item,) + ("",) * (self.nlevels - 1)
+        elif len(item) != self.nlevels:
+            raise ValueError("Item must have length equal to number of levels.")
+        return item
+
+    def putmask(self, mask, value: MultiIndex) -> MultiIndex:
+        """
+        Return a new MultiIndex of the values set with the mask.
+
+        Parameters
+        ----------
+        mask : array like
+        value : MultiIndex
+            Must either be the same length as self or length one
+
+        Returns
+        -------
+        MultiIndex
+        """
+        mask, noop = validate_putmask(self, mask)
+        if noop:
+            return self.copy()
+
+        if len(mask) == len(value):
+            subset = value[mask].remove_unused_levels()
+        else:
+            subset = value.remove_unused_levels()
+
+        new_levels = []
+        new_codes = []
+
+        for i, (value_level, level, level_codes) in enumerate(
+            zip(subset.levels, self.levels, self.codes)
+        ):
+            new_level = level.union(value_level, sort=False)
+            value_codes = new_level.get_indexer_for(subset.get_level_values(i))
+            new_code = ensure_int64(level_codes)
+            new_code[mask] = value_codes
+            new_levels.append(new_level)
+            new_codes.append(new_code)
+
+        return MultiIndex(
+            levels=new_levels, codes=new_codes, names=self.names, verify_integrity=False
+        )
+
+    def insert(self, loc: int, item) -> MultiIndex:
+        """
+        Make new MultiIndex inserting new item at location
+
+        Parameters
+        ----------
+        loc : int
+        item : tuple
+            Must be same length as number of levels in the MultiIndex
+
+        Returns
+        -------
+        new_index : Index
+        """
+        item = self._validate_fill_value(item)
+
+        new_levels = []
+        new_codes = []
+        for k, level, level_codes in zip(item, self.levels, self.codes):
+            if k not in level:
+                # have to insert into level
+                # must insert at end otherwise you have to recompute all the
+                # other codes
+                lev_loc = len(level)
+                level = level.insert(lev_loc, k)
+            else:
+                lev_loc = level.get_loc(k)
+
+            new_levels.append(level)
+            new_codes.append(np.insert(ensure_int64(level_codes), loc, lev_loc))
+
+        return MultiIndex(
+            levels=new_levels, codes=new_codes, names=self.names, verify_integrity=False
+        )
+
+    def delete(self, loc) -> MultiIndex:
+        """
+        Make new index with passed location deleted
+
+        Returns
+        -------
+        new_index : MultiIndex
+        """
+        new_codes = [np.delete(level_codes, loc) for level_codes in self.codes]
+        return MultiIndex(
+            levels=self.levels,
+            codes=new_codes,
+            names=self.names,
+            verify_integrity=False,
+        )
+
+    @doc(Index.isin)
+    def isin(self, values, level=None) -> npt.NDArray[np.bool_]:
+        if isinstance(values, Generator):
+            values = list(values)
+
+        if level is None:
+            if len(values) == 0:
+                return np.zeros((len(self),), dtype=np.bool_)
+            if not isinstance(values, MultiIndex):
+                values = MultiIndex.from_tuples(values)
+            return values.unique().get_indexer_for(self) != -1
+        else:
+            num = self._get_level_number(level)
+            levs = self.get_level_values(num)
+
+            if levs.size == 0:
+                return np.zeros(len(levs), dtype=np.bool_)
+            return levs.isin(values)
+
+    # error: Incompatible types in assignment (expression has type overloaded function,
+    # base class "Index" defined the type as "Callable[[Index, Any, bool], Any]")
+    rename = Index.set_names  # type: ignore[assignment]
+
+    # ---------------------------------------------------------------
+    # Arithmetic/Numeric Methods - Disabled
+
+    __add__ = make_invalid_op("__add__")
+    __radd__ = make_invalid_op("__radd__")
+    __iadd__ = make_invalid_op("__iadd__")
+    __sub__ = make_invalid_op("__sub__")
+    __rsub__ = make_invalid_op("__rsub__")
+    __isub__ = make_invalid_op("__isub__")
+    __pow__ = make_invalid_op("__pow__")
+    __rpow__ = make_invalid_op("__rpow__")
+    __mul__ = make_invalid_op("__mul__")
+    __rmul__ = make_invalid_op("__rmul__")
+    __floordiv__ = make_invalid_op("__floordiv__")
+    __rfloordiv__ = make_invalid_op("__rfloordiv__")
+    __truediv__ = make_invalid_op("__truediv__")
+    __rtruediv__ = make_invalid_op("__rtruediv__")
+    __mod__ = make_invalid_op("__mod__")
+    __rmod__ = make_invalid_op("__rmod__")
+    __divmod__ = make_invalid_op("__divmod__")
+    __rdivmod__ = make_invalid_op("__rdivmod__")
+    # Unary methods disabled
+    __neg__ = make_invalid_op("__neg__")
+    __pos__ = make_invalid_op("__pos__")
+    __abs__ = make_invalid_op("__abs__")
+    __invert__ = make_invalid_op("__invert__")
+
+
+def _lexsort_depth(codes: list[np.ndarray], nlevels: int) -> int:
+    """Count depth (up to a maximum of `nlevels`) with which codes are lexsorted."""
+    int64_codes = [ensure_int64(level_codes) for level_codes in codes]
+    for k in range(nlevels, 0, -1):
+        if libalgos.is_lexsorted(int64_codes[:k]):
+            return k
+    return 0
+
+
+def sparsify_labels(label_list, start: int = 0, sentinel: object = ""):
+    pivoted = list(zip(*label_list))
+    k = len(label_list)
+
+    result = pivoted[: start + 1]
+    prev = pivoted[start]
+
+    for cur in pivoted[start + 1 :]:
+        sparse_cur = []
+
+        for i, (p, t) in enumerate(zip(prev, cur)):
+            if i == k - 1:
+                sparse_cur.append(t)
+                # error: Argument 1 to "append" of "list" has incompatible
+                # type "list[Any]"; expected "tuple[Any, ...]"
+                result.append(sparse_cur)  # type: ignore[arg-type]
+                break
+
+            if p == t:
+                sparse_cur.append(sentinel)
+            else:
+                sparse_cur.extend(cur[i:])
+                # error: Argument 1 to "append" of "list" has incompatible
+                # type "list[Any]"; expected "tuple[Any, ...]"
+                result.append(sparse_cur)  # type: ignore[arg-type]
+                break
+
+        prev = cur
+
+    return list(zip(*result))
+
+
+def _get_na_rep(dtype: DtypeObj) -> str:
+    if isinstance(dtype, ExtensionDtype):
+        return f"{dtype.na_value}"
+    else:
+        dtype_type = dtype.type
+
+    return {np.datetime64: "NaT", np.timedelta64: "NaT"}.get(dtype_type, "NaN")
+
+
+def maybe_droplevels(index: Index, key) -> Index:
+    """
+    Attempt to drop level or levels from the given index.
+
+    Parameters
+    ----------
+    index: Index
+    key : scalar or tuple
+
+    Returns
+    -------
+    Index
+    """
+    # drop levels
+    original_index = index
+    if isinstance(key, tuple):
+        # Caller is responsible for ensuring the key is not an entry in the first
+        #  level of the MultiIndex.
+        for _ in key:
+            try:
+                index = index._drop_level_numbers([0])
+            except ValueError:
+                # we have dropped too much, so back out
+                return original_index
+    else:
+        try:
+            index = index._drop_level_numbers([0])
+        except ValueError:
+            pass
+
+    return index
+
+
+def _coerce_indexer_frozen(array_like, categories, copy: bool = False) -> np.ndarray:
+    """
+    Coerce the array-like indexer to the smallest integer dtype that can encode all
+    of the given categories.
+
+    Parameters
+    ----------
+    array_like : array-like
+    categories : array-like
+    copy : bool
+
+    Returns
+    -------
+    np.ndarray
+        Non-writeable.
+    """
+    array_like = coerce_indexer_dtype(array_like, categories)
+    if copy:
+        array_like = array_like.copy()
+    array_like.flags.writeable = False
+    return array_like
+
+
+def _require_listlike(level, arr, arrname: str):
+    """
+    Ensure that level is either None or listlike, and arr is list-of-listlike.
+    """
+    if level is not None and not is_list_like(level):
+        if not is_list_like(arr):
+            raise TypeError(f"{arrname} must be list-like")
+        if len(arr) > 0 and is_list_like(arr[0]):
+            raise TypeError(f"{arrname} must be list-like")
+        level = [level]
+        arr = [arr]
+    elif level is None or is_list_like(level):
+        if not is_list_like(arr) or not is_list_like(arr[0]):
+            raise TypeError(f"{arrname} must be list of lists-like")
+    return level, arr
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/period.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/period.py
new file mode 100644
index 0000000000000000000000000000000000000000..b2f1933800fd383df9dc52a211b54190985fc32e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/period.py
@@ -0,0 +1,614 @@
+from __future__ import annotations
+
+from datetime import (
+    datetime,
+    timedelta,
+)
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+
+from pandas._libs import index as libindex
+from pandas._libs.tslibs import (
+    BaseOffset,
+    NaT,
+    Period,
+    Resolution,
+    Tick,
+)
+from pandas._libs.tslibs.dtypes import OFFSET_TO_PERIOD_FREQSTR
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_integer
+from pandas.core.dtypes.dtypes import PeriodDtype
+from pandas.core.dtypes.generic import ABCSeries
+from pandas.core.dtypes.missing import is_valid_na_for_dtype
+
+from pandas.core.arrays.period import (
+    PeriodArray,
+    period_array,
+    raise_on_incompatible,
+    validate_dtype_freq,
+)
+import pandas.core.common as com
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.base import maybe_extract_name
+from pandas.core.indexes.datetimelike import DatetimeIndexOpsMixin
+from pandas.core.indexes.datetimes import (
+    DatetimeIndex,
+    Index,
+)
+from pandas.core.indexes.extension import inherit_names
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import (
+        Dtype,
+        DtypeObj,
+        Self,
+        npt,
+    )
+
+
+_index_doc_kwargs = dict(ibase._index_doc_kwargs)
+_index_doc_kwargs.update({"target_klass": "PeriodIndex or list of Periods"})
+_shared_doc_kwargs = {
+    "klass": "PeriodArray",
+}
+
+# --- Period index sketch
+
+
+def _new_PeriodIndex(cls, **d):
+    # GH13277 for unpickling
+    values = d.pop("data")
+    if values.dtype == "int64":
+        freq = d.pop("freq", None)
+        dtype = PeriodDtype(freq)
+        values = PeriodArray(values, dtype=dtype)
+        return cls._simple_new(values, **d)
+    else:
+        return cls(values, **d)
+
+
+@inherit_names(
+    ["strftime", "start_time", "end_time"] + PeriodArray._field_ops,
+    PeriodArray,
+    wrap=True,
+)
+@inherit_names(["is_leap_year"], PeriodArray)
+class PeriodIndex(DatetimeIndexOpsMixin):
+    """
+    Immutable ndarray holding ordinal values indicating regular periods in time.
+
+    Index keys are boxed to Period objects which carries the metadata (eg,
+    frequency information).
+
+    Parameters
+    ----------
+    data : array-like (1d int np.ndarray or PeriodArray), optional
+        Optional period-like data to construct index with.
+    copy : bool
+        Make a copy of input ndarray.
+    freq : str or period object, optional
+        One of pandas period strings or corresponding objects.
+    year : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    month : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    quarter : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    day : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    hour : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    minute : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    second : int, array, or Series, default None
+
+        .. deprecated:: 2.2.0
+           Use PeriodIndex.from_fields instead.
+    dtype : str or PeriodDtype, default None
+
+    Attributes
+    ----------
+    day
+    dayofweek
+    day_of_week
+    dayofyear
+    day_of_year
+    days_in_month
+    daysinmonth
+    end_time
+    freq
+    freqstr
+    hour
+    is_leap_year
+    minute
+    month
+    quarter
+    qyear
+    second
+    start_time
+    week
+    weekday
+    weekofyear
+    year
+
+    Methods
+    -------
+    asfreq
+    strftime
+    to_timestamp
+    from_fields
+    from_ordinals
+
+    See Also
+    --------
+    Index : The base pandas Index type.
+    Period : Represents a period of time.
+    DatetimeIndex : Index with datetime64 data.
+    TimedeltaIndex : Index of timedelta64 data.
+    period_range : Create a fixed-frequency PeriodIndex.
+
+    Examples
+    --------
+    >>> idx = pd.PeriodIndex.from_fields(year=[2000, 2002], quarter=[1, 3])
+    >>> idx
+    PeriodIndex(['2000Q1', '2002Q3'], dtype='period[Q-DEC]')
+    """
+
+    _typ = "periodindex"
+
+    _data: PeriodArray
+    freq: BaseOffset
+    dtype: PeriodDtype
+
+    _data_cls = PeriodArray
+    _supports_partial_string_indexing = True
+
+    @property
+    def _engine_type(self) -> type[libindex.PeriodEngine]:
+        return libindex.PeriodEngine
+
+    @cache_readonly
+    def _resolution_obj(self) -> Resolution:
+        # for compat with DatetimeIndex
+        return self.dtype._resolution_obj
+
+    # --------------------------------------------------------------------
+    # methods that dispatch to array and wrap result in Index
+    # These are defined here instead of via inherit_names for mypy
+
+    @doc(
+        PeriodArray.asfreq,
+        other="pandas.arrays.PeriodArray",
+        other_name="PeriodArray",
+        **_shared_doc_kwargs,
+    )
+    def asfreq(self, freq=None, how: str = "E") -> Self:
+        arr = self._data.asfreq(freq, how)
+        return type(self)._simple_new(arr, name=self.name)
+
+    @doc(PeriodArray.to_timestamp)
+    def to_timestamp(self, freq=None, how: str = "start") -> DatetimeIndex:
+        arr = self._data.to_timestamp(freq, how)
+        return DatetimeIndex._simple_new(arr, name=self.name)
+
+    @property
+    @doc(PeriodArray.hour.fget)
+    def hour(self) -> Index:
+        return Index(self._data.hour, name=self.name)
+
+    @property
+    @doc(PeriodArray.minute.fget)
+    def minute(self) -> Index:
+        return Index(self._data.minute, name=self.name)
+
+    @property
+    @doc(PeriodArray.second.fget)
+    def second(self) -> Index:
+        return Index(self._data.second, name=self.name)
+
+    # ------------------------------------------------------------------------
+    # Index Constructors
+
+    def __new__(
+        cls,
+        data=None,
+        ordinal=None,
+        freq=None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+        **fields,
+    ) -> Self:
+        valid_field_set = {
+            "year",
+            "month",
+            "day",
+            "quarter",
+            "hour",
+            "minute",
+            "second",
+        }
+
+        refs = None
+        if not copy and isinstance(data, (Index, ABCSeries)):
+            refs = data._references
+
+        if not set(fields).issubset(valid_field_set):
+            argument = next(iter(set(fields) - valid_field_set))
+            raise TypeError(f"__new__() got an unexpected keyword argument {argument}")
+        elif len(fields):
+            # GH#55960
+            warnings.warn(
+                "Constructing PeriodIndex from fields is deprecated. Use "
+                "PeriodIndex.from_fields instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if ordinal is not None:
+            # GH#55960
+            warnings.warn(
+                "The 'ordinal' keyword in PeriodIndex is deprecated and will "
+                "be removed in a future version. Use PeriodIndex.from_ordinals "
+                "instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        name = maybe_extract_name(name, data, cls)
+
+        if data is None and ordinal is None:
+            # range-based.
+            if not fields:
+                # test_pickle_compat_construction
+                cls._raise_scalar_data_error(None)
+            data = cls.from_fields(**fields, freq=freq)._data
+            copy = False
+
+        elif fields:
+            if data is not None:
+                raise ValueError("Cannot pass both data and fields")
+            raise ValueError("Cannot pass both ordinal and fields")
+
+        else:
+            freq = validate_dtype_freq(dtype, freq)
+
+            # PeriodIndex allow PeriodIndex(period_index, freq=different)
+            # Let's not encourage that kind of behavior in PeriodArray.
+
+            if freq and isinstance(data, cls) and data.freq != freq:
+                # TODO: We can do some of these with no-copy / coercion?
+                # e.g. D -> 2D seems to be OK
+                data = data.asfreq(freq)
+
+            if data is None and ordinal is not None:
+                ordinal = np.asarray(ordinal, dtype=np.int64)
+                dtype = PeriodDtype(freq)
+                data = PeriodArray(ordinal, dtype=dtype)
+            elif data is not None and ordinal is not None:
+                raise ValueError("Cannot pass both data and ordinal")
+            else:
+                # don't pass copy here, since we copy later.
+                data = period_array(data=data, freq=freq)
+
+        if copy:
+            data = data.copy()
+
+        return cls._simple_new(data, name=name, refs=refs)
+
+    @classmethod
+    def from_fields(
+        cls,
+        *,
+        year=None,
+        quarter=None,
+        month=None,
+        day=None,
+        hour=None,
+        minute=None,
+        second=None,
+        freq=None,
+    ) -> Self:
+        fields = {
+            "year": year,
+            "quarter": quarter,
+            "month": month,
+            "day": day,
+            "hour": hour,
+            "minute": minute,
+            "second": second,
+        }
+        fields = {key: value for key, value in fields.items() if value is not None}
+        arr = PeriodArray._from_fields(fields=fields, freq=freq)
+        return cls._simple_new(arr)
+
+    @classmethod
+    def from_ordinals(cls, ordinals, *, freq, name=None) -> Self:
+        ordinals = np.asarray(ordinals, dtype=np.int64)
+        dtype = PeriodDtype(freq)
+        data = PeriodArray._simple_new(ordinals, dtype=dtype)
+        return cls._simple_new(data, name=name)
+
+    # ------------------------------------------------------------------------
+    # Data
+
+    @property
+    def values(self) -> npt.NDArray[np.object_]:
+        return np.asarray(self, dtype=object)
+
+    def _maybe_convert_timedelta(self, other) -> int | npt.NDArray[np.int64]:
+        """
+        Convert timedelta-like input to an integer multiple of self.freq
+
+        Parameters
+        ----------
+        other : timedelta, np.timedelta64, DateOffset, int, np.ndarray
+
+        Returns
+        -------
+        converted : int, np.ndarray[int64]
+
+        Raises
+        ------
+        IncompatibleFrequency : if the input cannot be written as a multiple
+            of self.freq.  Note IncompatibleFrequency subclasses ValueError.
+        """
+        if isinstance(other, (timedelta, np.timedelta64, Tick, np.ndarray)):
+            if isinstance(self.freq, Tick):
+                # _check_timedeltalike_freq_compat will raise if incompatible
+                delta = self._data._check_timedeltalike_freq_compat(other)
+                return delta
+        elif isinstance(other, BaseOffset):
+            if other.base == self.freq.base:
+                return other.n
+
+            raise raise_on_incompatible(self, other)
+        elif is_integer(other):
+            assert isinstance(other, int)
+            return other
+
+        # raise when input doesn't have freq
+        raise raise_on_incompatible(self, None)
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        """
+        Can we compare values of the given dtype to our own?
+        """
+        return self.dtype == dtype
+
+    # ------------------------------------------------------------------------
+    # Index Methods
+
+    def asof_locs(self, where: Index, mask: npt.NDArray[np.bool_]) -> np.ndarray:
+        """
+        where : array of timestamps
+        mask : np.ndarray[bool]
+            Array of booleans where data is not NA.
+        """
+        if isinstance(where, DatetimeIndex):
+            where = PeriodIndex(where._values, freq=self.freq)
+        elif not isinstance(where, PeriodIndex):
+            raise TypeError("asof_locs `where` must be DatetimeIndex or PeriodIndex")
+
+        return super().asof_locs(where, mask)
+
+    @property
+    def is_full(self) -> bool:
+        """
+        Returns True if this PeriodIndex is range-like in that all Periods
+        between start and end are present, in order.
+        """
+        if len(self) == 0:
+            return True
+        if not self.is_monotonic_increasing:
+            raise ValueError("Index is not monotonic")
+        values = self.asi8
+        return bool(((values[1:] - values[:-1]) < 2).all())
+
+    @property
+    def inferred_type(self) -> str:
+        # b/c data is represented as ints make sure we can't have ambiguous
+        # indexing
+        return "period"
+
+    # ------------------------------------------------------------------------
+    # Indexing Methods
+
+    def _convert_tolerance(self, tolerance, target):
+        # Returned tolerance must be in dtype/units so that
+        #  `|self._get_engine_target() - target._engine_target()| <= tolerance`
+        #  is meaningful.  Since PeriodIndex returns int64 for engine_target,
+        #  we may need to convert timedelta64 tolerance to int64.
+        tolerance = super()._convert_tolerance(tolerance, target)
+
+        if self.dtype == target.dtype:
+            # convert tolerance to i8
+            tolerance = self._maybe_convert_timedelta(tolerance)
+
+        return tolerance
+
+    def get_loc(self, key):
+        """
+        Get integer location for requested label.
+
+        Parameters
+        ----------
+        key : Period, NaT, str, or datetime
+            String or datetime key must be parsable as Period.
+
+        Returns
+        -------
+        loc : int or ndarray[int64]
+
+        Raises
+        ------
+        KeyError
+            Key is not present in the index.
+        TypeError
+            If key is listlike or otherwise not hashable.
+        """
+        orig_key = key
+
+        self._check_indexing_error(key)
+
+        if is_valid_na_for_dtype(key, self.dtype):
+            key = NaT
+
+        elif isinstance(key, str):
+            try:
+                parsed, reso = self._parse_with_reso(key)
+            except ValueError as err:
+                # A string with invalid format
+                raise KeyError(f"Cannot interpret '{key}' as period") from err
+
+            if self._can_partial_date_slice(reso):
+                try:
+                    return self._partial_date_slice(reso, parsed)
+                except KeyError as err:
+                    raise KeyError(key) from err
+
+            if reso == self._resolution_obj:
+                # the reso < self._resolution_obj case goes
+                #  through _get_string_slice
+                key = self._cast_partial_indexing_scalar(parsed)
+            else:
+                raise KeyError(key)
+
+        elif isinstance(key, Period):
+            self._disallow_mismatched_indexing(key)
+
+        elif isinstance(key, datetime):
+            key = self._cast_partial_indexing_scalar(key)
+
+        else:
+            # in particular integer, which Period constructor would cast to string
+            raise KeyError(key)
+
+        try:
+            return Index.get_loc(self, key)
+        except KeyError as err:
+            raise KeyError(orig_key) from err
+
+    def _disallow_mismatched_indexing(self, key: Period) -> None:
+        if key._dtype != self.dtype:
+            raise KeyError(key)
+
+    def _cast_partial_indexing_scalar(self, label: datetime) -> Period:
+        try:
+            period = Period(label, freq=self.freq)
+        except ValueError as err:
+            # we cannot construct the Period
+            raise KeyError(label) from err
+        return period
+
+    @doc(DatetimeIndexOpsMixin._maybe_cast_slice_bound)
+    def _maybe_cast_slice_bound(self, label, side: str):
+        if isinstance(label, datetime):
+            label = self._cast_partial_indexing_scalar(label)
+
+        return super()._maybe_cast_slice_bound(label, side)
+
+    def _parsed_string_to_bounds(self, reso: Resolution, parsed: datetime):
+        freq = OFFSET_TO_PERIOD_FREQSTR.get(reso.attr_abbrev, reso.attr_abbrev)
+        iv = Period(parsed, freq=freq)
+        return (iv.asfreq(self.freq, how="start"), iv.asfreq(self.freq, how="end"))
+
+    @doc(DatetimeIndexOpsMixin.shift)
+    def shift(self, periods: int = 1, freq=None) -> Self:
+        if freq is not None:
+            raise TypeError(
+                f"`freq` argument is not supported for {type(self).__name__}.shift"
+            )
+        return self + periods
+
+
+def period_range(
+    start=None,
+    end=None,
+    periods: int | None = None,
+    freq=None,
+    name: Hashable | None = None,
+) -> PeriodIndex:
+    """
+    Return a fixed frequency PeriodIndex.
+
+    The day (calendar) is the default frequency.
+
+    Parameters
+    ----------
+    start : str, datetime, date, pandas.Timestamp, or period-like, default None
+        Left bound for generating periods.
+    end : str, datetime, date, pandas.Timestamp, or period-like, default None
+        Right bound for generating periods.
+    periods : int, default None
+        Number of periods to generate.
+    freq : str or DateOffset, optional
+        Frequency alias. By default the freq is taken from `start` or `end`
+        if those are Period objects. Otherwise, the default is ``"D"`` for
+        daily frequency.
+    name : str, default None
+        Name of the resulting PeriodIndex.
+
+    Returns
+    -------
+    PeriodIndex
+
+    Notes
+    -----
+    Of the three parameters: ``start``, ``end``, and ``periods``, exactly two
+    must be specified.
+
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    >>> pd.period_range(start='2017-01-01', end='2018-01-01', freq='M')
+    PeriodIndex(['2017-01', '2017-02', '2017-03', '2017-04', '2017-05', '2017-06',
+             '2017-07', '2017-08', '2017-09', '2017-10', '2017-11', '2017-12',
+             '2018-01'],
+            dtype='period[M]')
+
+    If ``start`` or ``end`` are ``Period`` objects, they will be used as anchor
+    endpoints for a ``PeriodIndex`` with frequency matching that of the
+    ``period_range`` constructor.
+
+    >>> pd.period_range(start=pd.Period('2017Q1', freq='Q'),
+    ...                 end=pd.Period('2017Q2', freq='Q'), freq='M')
+    PeriodIndex(['2017-03', '2017-04', '2017-05', '2017-06'],
+                dtype='period[M]')
+    """
+    if com.count_not_none(start, end, periods) != 2:
+        raise ValueError(
+            "Of the three parameters: start, end, and periods, "
+            "exactly two must be specified"
+        )
+    if freq is None and (not isinstance(start, Period) and not isinstance(end, Period)):
+        freq = "D"
+
+    data, freq = PeriodArray._generate_range(start, end, periods, freq)
+    dtype = PeriodDtype(freq)
+    data = PeriodArray(data, dtype=dtype)
+    return PeriodIndex(data, name=name)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/range.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/range.py
new file mode 100644
index 0000000000000000000000000000000000000000..62afcf8badb50d95f2cc006bf8d89e79f6fe8615
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/range.py
@@ -0,0 +1,1187 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterator,
+)
+from datetime import timedelta
+import operator
+from sys import getsizeof
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    index as libindex,
+    lib,
+)
+from pandas._libs.algos import unique_deltas
+from pandas._libs.lib import no_default
+from pandas.compat.numpy import function as nv
+from pandas.util._decorators import (
+    cache_readonly,
+    deprecate_nonkeyword_arguments,
+    doc,
+)
+
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    ensure_python_int,
+    is_float,
+    is_integer,
+    is_scalar,
+    is_signed_integer_dtype,
+)
+from pandas.core.dtypes.generic import ABCTimedeltaIndex
+
+from pandas.core import ops
+import pandas.core.common as com
+from pandas.core.construction import extract_array
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.base import (
+    Index,
+    maybe_extract_name,
+)
+from pandas.core.ops.common import unpack_zerodim_and_defer
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Axis,
+        Dtype,
+        NaPosition,
+        Self,
+        npt,
+    )
+_empty_range = range(0)
+_dtype_int64 = np.dtype(np.int64)
+
+
+class RangeIndex(Index):
+    """
+    Immutable Index implementing a monotonic integer range.
+
+    RangeIndex is a memory-saving special case of an Index limited to representing
+    monotonic ranges with a 64-bit dtype. Using RangeIndex may in some instances
+    improve computing speed.
+
+    This is the default index type used
+    by DataFrame and Series when no explicit index is provided by the user.
+
+    Parameters
+    ----------
+    start : int (default: 0), range, or other RangeIndex instance
+        If int and "stop" is not given, interpreted as "stop" instead.
+    stop : int (default: 0)
+    step : int (default: 1)
+    dtype : np.int64
+        Unused, accepted for homogeneity with other index types.
+    copy : bool, default False
+        Unused, accepted for homogeneity with other index types.
+    name : object, optional
+        Name to be stored in the index.
+
+    Attributes
+    ----------
+    start
+    stop
+    step
+
+    Methods
+    -------
+    from_range
+
+    See Also
+    --------
+    Index : The base pandas Index type.
+
+    Examples
+    --------
+    >>> list(pd.RangeIndex(5))
+    [0, 1, 2, 3, 4]
+
+    >>> list(pd.RangeIndex(-2, 4))
+    [-2, -1, 0, 1, 2, 3]
+
+    >>> list(pd.RangeIndex(0, 10, 2))
+    [0, 2, 4, 6, 8]
+
+    >>> list(pd.RangeIndex(2, -10, -3))
+    [2, -1, -4, -7]
+
+    >>> list(pd.RangeIndex(0))
+    []
+
+    >>> list(pd.RangeIndex(1, 0))
+    []
+    """
+
+    _typ = "rangeindex"
+    _dtype_validation_metadata = (is_signed_integer_dtype, "signed integer")
+    _range: range
+    _values: np.ndarray
+
+    @property
+    def _engine_type(self) -> type[libindex.Int64Engine]:
+        return libindex.Int64Engine
+
+    # --------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        start=None,
+        stop=None,
+        step=None,
+        dtype: Dtype | None = None,
+        copy: bool = False,
+        name: Hashable | None = None,
+    ) -> Self:
+        cls._validate_dtype(dtype)
+        name = maybe_extract_name(name, start, cls)
+
+        # RangeIndex
+        if isinstance(start, cls):
+            return start.copy(name=name)
+        elif isinstance(start, range):
+            return cls._simple_new(start, name=name)
+
+        # validate the arguments
+        if com.all_none(start, stop, step):
+            raise TypeError("RangeIndex(...) must be called with integers")
+
+        start = ensure_python_int(start) if start is not None else 0
+
+        if stop is None:
+            start, stop = 0, start
+        else:
+            stop = ensure_python_int(stop)
+
+        step = ensure_python_int(step) if step is not None else 1
+        if step == 0:
+            raise ValueError("Step must not be zero")
+
+        rng = range(start, stop, step)
+        return cls._simple_new(rng, name=name)
+
+    @classmethod
+    def from_range(cls, data: range, name=None, dtype: Dtype | None = None) -> Self:
+        """
+        Create :class:`pandas.RangeIndex` from a ``range`` object.
+
+        Returns
+        -------
+        RangeIndex
+
+        Examples
+        --------
+        >>> pd.RangeIndex.from_range(range(5))
+        RangeIndex(start=0, stop=5, step=1)
+
+        >>> pd.RangeIndex.from_range(range(2, -10, -3))
+        RangeIndex(start=2, stop=-10, step=-3)
+        """
+        if not isinstance(data, range):
+            raise TypeError(
+                f"{cls.__name__}(...) must be called with object coercible to a "
+                f"range, {repr(data)} was passed"
+            )
+        cls._validate_dtype(dtype)
+        return cls._simple_new(data, name=name)
+
+    #  error: Argument 1 of "_simple_new" is incompatible with supertype "Index";
+    #  supertype defines the argument type as
+    #  "Union[ExtensionArray, ndarray[Any, Any]]"  [override]
+    @classmethod
+    def _simple_new(  # type: ignore[override]
+        cls, values: range, name: Hashable | None = None
+    ) -> Self:
+        result = object.__new__(cls)
+
+        assert isinstance(values, range)
+
+        result._range = values
+        result._name = name
+        result._cache = {}
+        result._reset_identity()
+        result._references = None
+        return result
+
+    @classmethod
+    def _validate_dtype(cls, dtype: Dtype | None) -> None:
+        if dtype is None:
+            return
+
+        validation_func, expected = cls._dtype_validation_metadata
+        if not validation_func(dtype):
+            raise ValueError(
+                f"Incorrect `dtype` passed: expected {expected}, received {dtype}"
+            )
+
+    # --------------------------------------------------------------------
+
+    # error: Return type "Type[Index]" of "_constructor" incompatible with return
+    # type "Type[RangeIndex]" in supertype "Index"
+    @cache_readonly
+    def _constructor(self) -> type[Index]:  # type: ignore[override]
+        """return the class to use for construction"""
+        return Index
+
+    # error: Signature of "_data" incompatible with supertype "Index"
+    @cache_readonly
+    def _data(self) -> np.ndarray:  # type: ignore[override]
+        """
+        An int array that for performance reasons is created only when needed.
+
+        The constructed array is saved in ``_cache``.
+        """
+        return np.arange(self.start, self.stop, self.step, dtype=np.int64)
+
+    def _get_data_as_items(self) -> list[tuple[str, int]]:
+        """return a list of tuples of start, stop, step"""
+        rng = self._range
+        return [("start", rng.start), ("stop", rng.stop), ("step", rng.step)]
+
+    def __reduce__(self):
+        d = {"name": self._name}
+        d.update(dict(self._get_data_as_items()))
+        return ibase._new_Index, (type(self), d), None
+
+    # --------------------------------------------------------------------
+    # Rendering Methods
+
+    def _format_attrs(self):
+        """
+        Return a list of tuples of the (attr, formatted_value)
+        """
+        attrs = cast("list[tuple[str, str | int]]", self._get_data_as_items())
+        if self._name is not None:
+            attrs.append(("name", ibase.default_pprint(self._name)))
+        return attrs
+
+    def _format_with_header(self, *, header: list[str], na_rep: str) -> list[str]:
+        # Equivalent to Index implementation, but faster
+        if not len(self._range):
+            return header
+        first_val_str = str(self._range[0])
+        last_val_str = str(self._range[-1])
+        max_length = max(len(first_val_str), len(last_val_str))
+
+        return header + [f"{x:<{max_length}}" for x in self._range]
+
+    # --------------------------------------------------------------------
+
+    @property
+    def start(self) -> int:
+        """
+        The value of the `start` parameter (``0`` if this was not supplied).
+
+        Examples
+        --------
+        >>> idx = pd.RangeIndex(5)
+        >>> idx.start
+        0
+
+        >>> idx = pd.RangeIndex(2, -10, -3)
+        >>> idx.start
+        2
+        """
+        # GH 25710
+        return self._range.start
+
+    @property
+    def stop(self) -> int:
+        """
+        The value of the `stop` parameter.
+
+        Examples
+        --------
+        >>> idx = pd.RangeIndex(5)
+        >>> idx.stop
+        5
+
+        >>> idx = pd.RangeIndex(2, -10, -3)
+        >>> idx.stop
+        -10
+        """
+        return self._range.stop
+
+    @property
+    def step(self) -> int:
+        """
+        The value of the `step` parameter (``1`` if this was not supplied).
+
+        Examples
+        --------
+        >>> idx = pd.RangeIndex(5)
+        >>> idx.step
+        1
+
+        >>> idx = pd.RangeIndex(2, -10, -3)
+        >>> idx.step
+        -3
+
+        Even if :class:`pandas.RangeIndex` is empty, ``step`` is still ``1`` if
+        not supplied.
+
+        >>> idx = pd.RangeIndex(1, 0)
+        >>> idx.step
+        1
+        """
+        # GH 25710
+        return self._range.step
+
+    @cache_readonly
+    def nbytes(self) -> int:
+        """
+        Return the number of bytes in the underlying data.
+        """
+        rng = self._range
+        return getsizeof(rng) + sum(
+            getsizeof(getattr(rng, attr_name))
+            for attr_name in ["start", "stop", "step"]
+        )
+
+    def memory_usage(self, deep: bool = False) -> int:
+        """
+        Memory usage of my values
+
+        Parameters
+        ----------
+        deep : bool
+            Introspect the data deeply, interrogate
+            `object` dtypes for system-level memory consumption
+
+        Returns
+        -------
+        bytes used
+
+        Notes
+        -----
+        Memory usage does not include memory consumed by elements that
+        are not components of the array if deep=False
+
+        See Also
+        --------
+        numpy.ndarray.nbytes
+        """
+        return self.nbytes
+
+    @property
+    def dtype(self) -> np.dtype:
+        return _dtype_int64
+
+    @property
+    def is_unique(self) -> bool:
+        """return if the index has unique values"""
+        return True
+
+    @cache_readonly
+    def is_monotonic_increasing(self) -> bool:
+        return self._range.step > 0 or len(self) <= 1
+
+    @cache_readonly
+    def is_monotonic_decreasing(self) -> bool:
+        return self._range.step < 0 or len(self) <= 1
+
+    def __contains__(self, key: Any) -> bool:
+        hash(key)
+        try:
+            key = ensure_python_int(key)
+        except TypeError:
+            return False
+        return key in self._range
+
+    @property
+    def inferred_type(self) -> str:
+        return "integer"
+
+    # --------------------------------------------------------------------
+    # Indexing Methods
+
+    @doc(Index.get_loc)
+    def get_loc(self, key) -> int:
+        if is_integer(key) or (is_float(key) and key.is_integer()):
+            new_key = int(key)
+            try:
+                return self._range.index(new_key)
+            except ValueError as err:
+                raise KeyError(key) from err
+        if isinstance(key, Hashable):
+            raise KeyError(key)
+        self._check_indexing_error(key)
+        raise KeyError(key)
+
+    def _get_indexer(
+        self,
+        target: Index,
+        method: str | None = None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> npt.NDArray[np.intp]:
+        if com.any_not_none(method, tolerance, limit):
+            return super()._get_indexer(
+                target, method=method, tolerance=tolerance, limit=limit
+            )
+
+        if self.step > 0:
+            start, stop, step = self.start, self.stop, self.step
+        else:
+            # GH 28678: work on reversed range for simplicity
+            reverse = self._range[::-1]
+            start, stop, step = reverse.start, reverse.stop, reverse.step
+
+        target_array = np.asarray(target)
+        locs = target_array - start
+        valid = (locs % step == 0) & (locs >= 0) & (target_array < stop)
+        locs[~valid] = -1
+        locs[valid] = locs[valid] / step
+
+        if step != self.step:
+            # We reversed this range: transform to original locs
+            locs[valid] = len(self) - 1 - locs[valid]
+        return ensure_platform_int(locs)
+
+    @cache_readonly
+    def _should_fallback_to_positional(self) -> bool:
+        """
+        Should an integer key be treated as positional?
+        """
+        return False
+
+    # --------------------------------------------------------------------
+
+    def tolist(self) -> list[int]:
+        return list(self._range)
+
+    @doc(Index.__iter__)
+    def __iter__(self) -> Iterator[int]:
+        yield from self._range
+
+    @doc(Index._shallow_copy)
+    def _shallow_copy(self, values, name: Hashable = no_default):
+        name = self._name if name is no_default else name
+
+        if values.dtype.kind == "f":
+            return Index(values, name=name, dtype=np.float64)
+        # GH 46675 & 43885: If values is equally spaced, return a
+        # more memory-compact RangeIndex instead of Index with 64-bit dtype
+        unique_diffs = unique_deltas(values)
+        if len(unique_diffs) == 1 and unique_diffs[0] != 0:
+            diff = unique_diffs[0]
+            new_range = range(values[0], values[-1] + diff, diff)
+            return type(self)._simple_new(new_range, name=name)
+        else:
+            return self._constructor._simple_new(values, name=name)
+
+    def _view(self) -> Self:
+        result = type(self)._simple_new(self._range, name=self._name)
+        result._cache = self._cache
+        return result
+
+    @doc(Index.copy)
+    def copy(self, name: Hashable | None = None, deep: bool = False) -> Self:
+        name = self._validate_names(name=name, deep=deep)[0]
+        new_index = self._rename(name=name)
+        return new_index
+
+    def _minmax(self, meth: str):
+        no_steps = len(self) - 1
+        if no_steps == -1:
+            return np.nan
+        elif (meth == "min" and self.step > 0) or (meth == "max" and self.step < 0):
+            return self.start
+
+        return self.start + self.step * no_steps
+
+    def min(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+        """The minimum value of the RangeIndex"""
+        nv.validate_minmax_axis(axis)
+        nv.validate_min(args, kwargs)
+        return self._minmax("min")
+
+    def max(self, axis=None, skipna: bool = True, *args, **kwargs) -> int:
+        """The maximum value of the RangeIndex"""
+        nv.validate_minmax_axis(axis)
+        nv.validate_max(args, kwargs)
+        return self._minmax("max")
+
+    def argsort(self, *args, **kwargs) -> npt.NDArray[np.intp]:
+        """
+        Returns the indices that would sort the index and its
+        underlying data.
+
+        Returns
+        -------
+        np.ndarray[np.intp]
+
+        See Also
+        --------
+        numpy.ndarray.argsort
+        """
+        ascending = kwargs.pop("ascending", True)  # EA compat
+        kwargs.pop("kind", None)  # e.g. "mergesort" is irrelevant
+        nv.validate_argsort(args, kwargs)
+
+        if self._range.step > 0:
+            result = np.arange(len(self), dtype=np.intp)
+        else:
+            result = np.arange(len(self) - 1, -1, -1, dtype=np.intp)
+
+        if not ascending:
+            result = result[::-1]
+        return result
+
+    def factorize(
+        self,
+        sort: bool = False,
+        use_na_sentinel: bool = True,
+    ) -> tuple[npt.NDArray[np.intp], RangeIndex]:
+        codes = np.arange(len(self), dtype=np.intp)
+        uniques = self
+        if sort and self.step < 0:
+            codes = codes[::-1]
+            uniques = uniques[::-1]
+        return codes, uniques
+
+    def equals(self, other: object) -> bool:
+        """
+        Determines if two Index objects contain the same elements.
+        """
+        if isinstance(other, RangeIndex):
+            return self._range == other._range
+        return super().equals(other)
+
+    # error: Signature of "sort_values" incompatible with supertype "Index"
+    @overload  # type: ignore[override]
+    def sort_values(
+        self,
+        *,
+        return_indexer: Literal[False] = ...,
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        return_indexer: Literal[True],
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> tuple[Self, np.ndarray | RangeIndex]:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        return_indexer: bool = ...,
+        ascending: bool = ...,
+        na_position: NaPosition = ...,
+        key: Callable | None = ...,
+    ) -> Self | tuple[Self, np.ndarray | RangeIndex]:
+        ...
+
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self"], name="sort_values"
+    )
+    def sort_values(
+        self,
+        return_indexer: bool = False,
+        ascending: bool = True,
+        na_position: NaPosition = "last",
+        key: Callable | None = None,
+    ) -> Self | tuple[Self, np.ndarray | RangeIndex]:
+        if key is not None:
+            return super().sort_values(
+                return_indexer=return_indexer,
+                ascending=ascending,
+                na_position=na_position,
+                key=key,
+            )
+        else:
+            sorted_index = self
+            inverse_indexer = False
+            if ascending:
+                if self.step < 0:
+                    sorted_index = self[::-1]
+                    inverse_indexer = True
+            else:
+                if self.step > 0:
+                    sorted_index = self[::-1]
+                    inverse_indexer = True
+
+        if return_indexer:
+            if inverse_indexer:
+                rng = range(len(self) - 1, -1, -1)
+            else:
+                rng = range(len(self))
+            return sorted_index, RangeIndex(rng)
+        else:
+            return sorted_index
+
+    # --------------------------------------------------------------------
+    # Set Operations
+
+    def _intersection(self, other: Index, sort: bool = False):
+        # caller is responsible for checking self and other are both non-empty
+
+        if not isinstance(other, RangeIndex):
+            return super()._intersection(other, sort=sort)
+
+        first = self._range[::-1] if self.step < 0 else self._range
+        second = other._range[::-1] if other.step < 0 else other._range
+
+        # check whether intervals intersect
+        # deals with in- and decreasing ranges
+        int_low = max(first.start, second.start)
+        int_high = min(first.stop, second.stop)
+        if int_high <= int_low:
+            return self._simple_new(_empty_range)
+
+        # Method hint: linear Diophantine equation
+        # solve intersection problem
+        # performance hint: for identical step sizes, could use
+        # cheaper alternative
+        gcd, s, _ = self._extended_gcd(first.step, second.step)
+
+        # check whether element sets intersect
+        if (first.start - second.start) % gcd:
+            return self._simple_new(_empty_range)
+
+        # calculate parameters for the RangeIndex describing the
+        # intersection disregarding the lower bounds
+        tmp_start = first.start + (second.start - first.start) * first.step // gcd * s
+        new_step = first.step * second.step // gcd
+        new_range = range(tmp_start, int_high, new_step)
+        new_index = self._simple_new(new_range)
+
+        # adjust index to limiting interval
+        new_start = new_index._min_fitting_element(int_low)
+        new_range = range(new_start, new_index.stop, new_index.step)
+        new_index = self._simple_new(new_range)
+
+        if (self.step < 0 and other.step < 0) is not (new_index.step < 0):
+            new_index = new_index[::-1]
+
+        if sort is None:
+            new_index = new_index.sort_values()
+
+        return new_index
+
+    def _min_fitting_element(self, lower_limit: int) -> int:
+        """Returns the smallest element greater than or equal to the limit"""
+        no_steps = -(-(lower_limit - self.start) // abs(self.step))
+        return self.start + abs(self.step) * no_steps
+
+    def _extended_gcd(self, a: int, b: int) -> tuple[int, int, int]:
+        """
+        Extended Euclidean algorithms to solve Bezout's identity:
+           a*x + b*y = gcd(x, y)
+        Finds one particular solution for x, y: s, t
+        Returns: gcd, s, t
+        """
+        s, old_s = 0, 1
+        t, old_t = 1, 0
+        r, old_r = b, a
+        while r:
+            quotient = old_r // r
+            old_r, r = r, old_r - quotient * r
+            old_s, s = s, old_s - quotient * s
+            old_t, t = t, old_t - quotient * t
+        return old_r, old_s, old_t
+
+    def _range_in_self(self, other: range) -> bool:
+        """Check if other range is contained in self"""
+        # https://stackoverflow.com/a/32481015
+        if not other:
+            return True
+        if not self._range:
+            return False
+        if len(other) > 1 and other.step % self._range.step:
+            return False
+        return other.start in self._range and other[-1] in self._range
+
+    def _union(self, other: Index, sort: bool | None):
+        """
+        Form the union of two Index objects and sorts if possible
+
+        Parameters
+        ----------
+        other : Index or array-like
+
+        sort : bool or None, default None
+            Whether to sort (monotonically increasing) the resulting index.
+            ``sort=None|True`` returns a ``RangeIndex`` if possible or a sorted
+            ``Index`` with a int64 dtype if not.
+            ``sort=False`` can return a ``RangeIndex`` if self is monotonically
+            increasing and other is fully contained in self. Otherwise, returns
+            an unsorted ``Index`` with an int64 dtype.
+
+        Returns
+        -------
+        union : Index
+        """
+        if isinstance(other, RangeIndex):
+            if sort in (None, True) or (
+                sort is False and self.step > 0 and self._range_in_self(other._range)
+            ):
+                # GH 47557: Can still return a RangeIndex
+                # if other range in self and sort=False
+                start_s, step_s = self.start, self.step
+                end_s = self.start + self.step * (len(self) - 1)
+                start_o, step_o = other.start, other.step
+                end_o = other.start + other.step * (len(other) - 1)
+                if self.step < 0:
+                    start_s, step_s, end_s = end_s, -step_s, start_s
+                if other.step < 0:
+                    start_o, step_o, end_o = end_o, -step_o, start_o
+                if len(self) == 1 and len(other) == 1:
+                    step_s = step_o = abs(self.start - other.start)
+                elif len(self) == 1:
+                    step_s = step_o
+                elif len(other) == 1:
+                    step_o = step_s
+                start_r = min(start_s, start_o)
+                end_r = max(end_s, end_o)
+                if step_o == step_s:
+                    if (
+                        (start_s - start_o) % step_s == 0
+                        and (start_s - end_o) <= step_s
+                        and (start_o - end_s) <= step_s
+                    ):
+                        return type(self)(start_r, end_r + step_s, step_s)
+                    if (
+                        (step_s % 2 == 0)
+                        and (abs(start_s - start_o) == step_s / 2)
+                        and (abs(end_s - end_o) == step_s / 2)
+                    ):
+                        # e.g. range(0, 10, 2) and range(1, 11, 2)
+                        #  but not range(0, 20, 4) and range(1, 21, 4) GH#44019
+                        return type(self)(start_r, end_r + step_s / 2, step_s / 2)
+
+                elif step_o % step_s == 0:
+                    if (
+                        (start_o - start_s) % step_s == 0
+                        and (start_o + step_s >= start_s)
+                        and (end_o - step_s <= end_s)
+                    ):
+                        return type(self)(start_r, end_r + step_s, step_s)
+                elif step_s % step_o == 0:
+                    if (
+                        (start_s - start_o) % step_o == 0
+                        and (start_s + step_o >= start_o)
+                        and (end_s - step_o <= end_o)
+                    ):
+                        return type(self)(start_r, end_r + step_o, step_o)
+
+        return super()._union(other, sort=sort)
+
+    def _difference(self, other, sort=None):
+        # optimized set operation if we have another RangeIndex
+        self._validate_sort_keyword(sort)
+        self._assert_can_do_setop(other)
+        other, result_name = self._convert_can_do_setop(other)
+
+        if not isinstance(other, RangeIndex):
+            return super()._difference(other, sort=sort)
+
+        if sort is not False and self.step < 0:
+            return self[::-1]._difference(other)
+
+        res_name = ops.get_op_result_name(self, other)
+
+        first = self._range[::-1] if self.step < 0 else self._range
+        overlap = self.intersection(other)
+        if overlap.step < 0:
+            overlap = overlap[::-1]
+
+        if len(overlap) == 0:
+            return self.rename(name=res_name)
+        if len(overlap) == len(self):
+            return self[:0].rename(res_name)
+
+        # overlap.step will always be a multiple of self.step (see _intersection)
+
+        if len(overlap) == 1:
+            if overlap[0] == self[0]:
+                return self[1:]
+
+            elif overlap[0] == self[-1]:
+                return self[:-1]
+
+            elif len(self) == 3 and overlap[0] == self[1]:
+                return self[::2]
+
+            else:
+                return super()._difference(other, sort=sort)
+
+        elif len(overlap) == 2 and overlap[0] == first[0] and overlap[-1] == first[-1]:
+            # e.g. range(-8, 20, 7) and range(13, -9, -3)
+            return self[1:-1]
+
+        if overlap.step == first.step:
+            if overlap[0] == first.start:
+                # The difference is everything after the intersection
+                new_rng = range(overlap[-1] + first.step, first.stop, first.step)
+            elif overlap[-1] == first[-1]:
+                # The difference is everything before the intersection
+                new_rng = range(first.start, overlap[0], first.step)
+            elif overlap._range == first[1:-1]:
+                # e.g. range(4) and range(1, 3)
+                step = len(first) - 1
+                new_rng = first[::step]
+            else:
+                # The difference is not range-like
+                # e.g. range(1, 10, 1) and range(3, 7, 1)
+                return super()._difference(other, sort=sort)
+
+        else:
+            # We must have len(self) > 1, bc we ruled out above
+            #  len(overlap) == 0 and len(overlap) == len(self)
+            assert len(self) > 1
+
+            if overlap.step == first.step * 2:
+                if overlap[0] == first[0] and overlap[-1] in (first[-1], first[-2]):
+                    # e.g. range(1, 10, 1) and range(1, 10, 2)
+                    new_rng = first[1::2]
+
+                elif overlap[0] == first[1] and overlap[-1] in (first[-1], first[-2]):
+                    # e.g. range(1, 10, 1) and range(2, 10, 2)
+                    new_rng = first[::2]
+
+                else:
+                    # We can get here with  e.g. range(20) and range(0, 10, 2)
+                    return super()._difference(other, sort=sort)
+
+            else:
+                # e.g. range(10) and range(0, 10, 3)
+                return super()._difference(other, sort=sort)
+
+        new_index = type(self)._simple_new(new_rng, name=res_name)
+        if first is not self._range:
+            new_index = new_index[::-1]
+
+        return new_index
+
+    def symmetric_difference(
+        self, other, result_name: Hashable | None = None, sort=None
+    ):
+        if not isinstance(other, RangeIndex) or sort is not None:
+            return super().symmetric_difference(other, result_name, sort)
+
+        left = self.difference(other)
+        right = other.difference(self)
+        result = left.union(right)
+
+        if result_name is not None:
+            result = result.rename(result_name)
+        return result
+
+    # --------------------------------------------------------------------
+
+    # error: Return type "Index" of "delete" incompatible with return type
+    #  "RangeIndex" in supertype "Index"
+    def delete(self, loc) -> Index:  # type: ignore[override]
+        # In some cases we can retain RangeIndex, see also
+        #  DatetimeTimedeltaMixin._get_delete_Freq
+        if is_integer(loc):
+            if loc in (0, -len(self)):
+                return self[1:]
+            if loc in (-1, len(self) - 1):
+                return self[:-1]
+            if len(self) == 3 and loc in (1, -2):
+                return self[::2]
+
+        elif lib.is_list_like(loc):
+            slc = lib.maybe_indices_to_slice(np.asarray(loc, dtype=np.intp), len(self))
+
+            if isinstance(slc, slice):
+                # defer to RangeIndex._difference, which is optimized to return
+                #  a RangeIndex whenever possible
+                other = self[slc]
+                return self.difference(other, sort=False)
+
+        return super().delete(loc)
+
+    def insert(self, loc: int, item) -> Index:
+        if len(self) and (is_integer(item) or is_float(item)):
+            # We can retain RangeIndex is inserting at the beginning or end,
+            #  or right in the middle.
+            rng = self._range
+            if loc == 0 and item == self[0] - self.step:
+                new_rng = range(rng.start - rng.step, rng.stop, rng.step)
+                return type(self)._simple_new(new_rng, name=self._name)
+
+            elif loc == len(self) and item == self[-1] + self.step:
+                new_rng = range(rng.start, rng.stop + rng.step, rng.step)
+                return type(self)._simple_new(new_rng, name=self._name)
+
+            elif len(self) == 2 and item == self[0] + self.step / 2:
+                # e.g. inserting 1 into [0, 2]
+                step = int(self.step / 2)
+                new_rng = range(self.start, self.stop, step)
+                return type(self)._simple_new(new_rng, name=self._name)
+
+        return super().insert(loc, item)
+
+    def _concat(self, indexes: list[Index], name: Hashable) -> Index:
+        """
+        Overriding parent method for the case of all RangeIndex instances.
+
+        When all members of "indexes" are of type RangeIndex: result will be
+        RangeIndex if possible, Index with a int64 dtype otherwise. E.g.:
+        indexes = [RangeIndex(3), RangeIndex(3, 6)] -> RangeIndex(6)
+        indexes = [RangeIndex(3), RangeIndex(4, 6)] -> Index([0,1,2,4,5], dtype='int64')
+        """
+        if not all(isinstance(x, RangeIndex) for x in indexes):
+            return super()._concat(indexes, name)
+
+        elif len(indexes) == 1:
+            return indexes[0]
+
+        rng_indexes = cast(list[RangeIndex], indexes)
+
+        start = step = next_ = None
+
+        # Filter the empty indexes
+        non_empty_indexes = [obj for obj in rng_indexes if len(obj)]
+
+        for obj in non_empty_indexes:
+            rng = obj._range
+
+            if start is None:
+                # This is set by the first non-empty index
+                start = rng.start
+                if step is None and len(rng) > 1:
+                    step = rng.step
+            elif step is None:
+                # First non-empty index had only one element
+                if rng.start == start:
+                    values = np.concatenate([x._values for x in rng_indexes])
+                    result = self._constructor(values)
+                    return result.rename(name)
+
+                step = rng.start - start
+
+            non_consecutive = (step != rng.step and len(rng) > 1) or (
+                next_ is not None and rng.start != next_
+            )
+            if non_consecutive:
+                result = self._constructor(
+                    np.concatenate([x._values for x in rng_indexes])
+                )
+                return result.rename(name)
+
+            if step is not None:
+                next_ = rng[-1] + step
+
+        if non_empty_indexes:
+            # Get the stop value from "next" or alternatively
+            # from the last non-empty index
+            stop = non_empty_indexes[-1].stop if next_ is None else next_
+            return RangeIndex(start, stop, step).rename(name)
+
+        # Here all "indexes" had 0 length, i.e. were empty.
+        # In this case return an empty range index.
+        return RangeIndex(0, 0).rename(name)
+
+    def __len__(self) -> int:
+        """
+        return the length of the RangeIndex
+        """
+        return len(self._range)
+
+    @property
+    def size(self) -> int:
+        return len(self)
+
+    def __getitem__(self, key):
+        """
+        Conserve RangeIndex type for scalar and slice keys.
+        """
+        if isinstance(key, slice):
+            return self._getitem_slice(key)
+        elif is_integer(key):
+            new_key = int(key)
+            try:
+                return self._range[new_key]
+            except IndexError as err:
+                raise IndexError(
+                    f"index {key} is out of bounds for axis 0 with size {len(self)}"
+                ) from err
+        elif is_scalar(key):
+            raise IndexError(
+                "only integers, slices (`:`), "
+                "ellipsis (`...`), numpy.newaxis (`None`) "
+                "and integer or boolean "
+                "arrays are valid indices"
+            )
+        return super().__getitem__(key)
+
+    def _getitem_slice(self, slobj: slice) -> Self:
+        """
+        Fastpath for __getitem__ when we know we have a slice.
+        """
+        res = self._range[slobj]
+        return type(self)._simple_new(res, name=self._name)
+
+    @unpack_zerodim_and_defer("__floordiv__")
+    def __floordiv__(self, other):
+        if is_integer(other) and other != 0:
+            if len(self) == 0 or self.start % other == 0 and self.step % other == 0:
+                start = self.start // other
+                step = self.step // other
+                stop = start + len(self) * step
+                new_range = range(start, stop, step or 1)
+                return self._simple_new(new_range, name=self._name)
+            if len(self) == 1:
+                start = self.start // other
+                new_range = range(start, start + 1, 1)
+                return self._simple_new(new_range, name=self._name)
+
+        return super().__floordiv__(other)
+
+    # --------------------------------------------------------------------
+    # Reductions
+
+    def all(self, *args, **kwargs) -> bool:
+        return 0 not in self._range
+
+    def any(self, *args, **kwargs) -> bool:
+        return any(self._range)
+
+    # --------------------------------------------------------------------
+
+    def _cmp_method(self, other, op):
+        if isinstance(other, RangeIndex) and self._range == other._range:
+            # Both are immutable so if ._range attr. are equal, shortcut is possible
+            return super()._cmp_method(self, op)
+        return super()._cmp_method(other, op)
+
+    def _arith_method(self, other, op):
+        """
+        Parameters
+        ----------
+        other : Any
+        op : callable that accepts 2 params
+            perform the binary op
+        """
+
+        if isinstance(other, ABCTimedeltaIndex):
+            # Defer to TimedeltaIndex implementation
+            return NotImplemented
+        elif isinstance(other, (timedelta, np.timedelta64)):
+            # GH#19333 is_integer evaluated True on timedelta64,
+            # so we need to catch these explicitly
+            return super()._arith_method(other, op)
+        elif lib.is_np_dtype(getattr(other, "dtype", None), "m"):
+            # Must be an np.ndarray; GH#22390
+            return super()._arith_method(other, op)
+
+        if op in [
+            operator.pow,
+            ops.rpow,
+            operator.mod,
+            ops.rmod,
+            operator.floordiv,
+            ops.rfloordiv,
+            divmod,
+            ops.rdivmod,
+        ]:
+            return super()._arith_method(other, op)
+
+        step: Callable | None = None
+        if op in [operator.mul, ops.rmul, operator.truediv, ops.rtruediv]:
+            step = op
+
+        # TODO: if other is a RangeIndex we may have more efficient options
+        right = extract_array(other, extract_numpy=True, extract_range=True)
+        left = self
+
+        try:
+            # apply if we have an override
+            if step:
+                with np.errstate(all="ignore"):
+                    rstep = step(left.step, right)
+
+                # we don't have a representable op
+                # so return a base index
+                if not is_integer(rstep) or not rstep:
+                    raise ValueError
+
+            # GH#53255
+            else:
+                rstep = -left.step if op == ops.rsub else left.step
+
+            with np.errstate(all="ignore"):
+                rstart = op(left.start, right)
+                rstop = op(left.stop, right)
+
+            res_name = ops.get_op_result_name(self, other)
+            result = type(self)(rstart, rstop, rstep, name=res_name)
+
+            # for compat with numpy / Index with int64 dtype
+            # even if we can represent as a RangeIndex, return
+            # as a float64 Index if we have float-like descriptors
+            if not all(is_integer(x) for x in [rstart, rstop, rstep]):
+                result = result.astype("float64")
+
+            return result
+
+        except (ValueError, TypeError, ZeroDivisionError):
+            # test_arithmetic_explicit_conversions
+            return super()._arith_method(other, op)
+
+    # error: Return type "Index" of "take" incompatible with return type
+    # "RangeIndex" in supertype "Index"
+    def take(  # type: ignore[override]
+        self,
+        indices,
+        axis: Axis = 0,
+        allow_fill: bool = True,
+        fill_value=None,
+        **kwargs,
+    ) -> Index:
+        if kwargs:
+            nv.validate_take((), kwargs)
+        if is_scalar(indices):
+            raise TypeError("Expected indices to be array-like")
+        indices = ensure_platform_int(indices)
+
+        # raise an exception if allow_fill is True and fill_value is not None
+        self._maybe_disallow_fill(allow_fill, fill_value, indices)
+
+        if len(indices) == 0:
+            taken = np.array([], dtype=self.dtype)
+        else:
+            ind_max = indices.max()
+            if ind_max >= len(self):
+                raise IndexError(
+                    f"index {ind_max} is out of bounds for axis 0 with size {len(self)}"
+                )
+            ind_min = indices.min()
+            if ind_min < -len(self):
+                raise IndexError(
+                    f"index {ind_min} is out of bounds for axis 0 with size {len(self)}"
+                )
+            taken = indices.astype(self.dtype, casting="safe")
+            if ind_min < 0:
+                taken %= len(self)
+            if self.step != 1:
+                taken *= self.step
+            if self.start != 0:
+                taken += self.start
+
+        # _constructor so RangeIndex-> Index with an int64 dtype
+        return self._constructor._simple_new(taken, name=self.name)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexes/timedeltas.py b/.venv/lib/python3.13/site-packages/pandas/core/indexes/timedeltas.py
new file mode 100644
index 0000000000000000000000000000000000000000..08a265ba4764892fde0bc50670b6706ff788c8bc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexes/timedeltas.py
@@ -0,0 +1,356 @@
+""" implement the TimedeltaIndex """
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+import warnings
+
+from pandas._libs import (
+    index as libindex,
+    lib,
+)
+from pandas._libs.tslibs import (
+    Resolution,
+    Timedelta,
+    to_offset,
+)
+from pandas._libs.tslibs.timedeltas import disallow_ambiguous_unit
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_scalar,
+    pandas_dtype,
+)
+from pandas.core.dtypes.generic import ABCSeries
+
+from pandas.core.arrays.timedeltas import TimedeltaArray
+import pandas.core.common as com
+from pandas.core.indexes.base import (
+    Index,
+    maybe_extract_name,
+)
+from pandas.core.indexes.datetimelike import DatetimeTimedeltaMixin
+from pandas.core.indexes.extension import inherit_names
+
+if TYPE_CHECKING:
+    from pandas._typing import DtypeObj
+
+
+@inherit_names(
+    ["__neg__", "__pos__", "__abs__", "total_seconds", "round", "floor", "ceil"]
+    + TimedeltaArray._field_ops,
+    TimedeltaArray,
+    wrap=True,
+)
+@inherit_names(
+    [
+        "components",
+        "to_pytimedelta",
+        "sum",
+        "std",
+        "median",
+    ],
+    TimedeltaArray,
+)
+class TimedeltaIndex(DatetimeTimedeltaMixin):
+    """
+    Immutable Index of timedelta64 data.
+
+    Represented internally as int64, and scalars returned Timedelta objects.
+
+    Parameters
+    ----------
+    data : array-like (1-dimensional), optional
+        Optional timedelta-like data to construct index with.
+    unit : {'D', 'h', 'm', 's', 'ms', 'us', 'ns'}, optional
+        The unit of ``data``.
+
+        .. deprecated:: 2.2.0
+         Use ``pd.to_timedelta`` instead.
+
+    freq : str or pandas offset object, optional
+        One of pandas date offset strings or corresponding objects. The string
+        ``'infer'`` can be passed in order to set the frequency of the index as
+        the inferred frequency upon creation.
+    dtype : numpy.dtype or str, default None
+        Valid ``numpy`` dtypes are ``timedelta64[ns]``, ``timedelta64[us]``,
+        ``timedelta64[ms]``, and ``timedelta64[s]``.
+    copy : bool
+        Make a copy of input array.
+    name : object
+        Name to be stored in the index.
+
+    Attributes
+    ----------
+    days
+    seconds
+    microseconds
+    nanoseconds
+    components
+    inferred_freq
+
+    Methods
+    -------
+    to_pytimedelta
+    to_series
+    round
+    floor
+    ceil
+    to_frame
+    mean
+
+    See Also
+    --------
+    Index : The base pandas Index type.
+    Timedelta : Represents a duration between two dates or times.
+    DatetimeIndex : Index of datetime64 data.
+    PeriodIndex : Index of Period data.
+    timedelta_range : Create a fixed-frequency TimedeltaIndex.
+
+    Notes
+    -----
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    >>> pd.TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'])
+    TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq=None)
+
+    We can also let pandas infer the frequency when possible.
+
+    >>> pd.TimedeltaIndex(np.arange(5) * 24 * 3600 * 1e9, freq='infer')
+    TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq='D')
+    """
+
+    _typ = "timedeltaindex"
+
+    _data_cls = TimedeltaArray
+
+    @property
+    def _engine_type(self) -> type[libindex.TimedeltaEngine]:
+        return libindex.TimedeltaEngine
+
+    _data: TimedeltaArray
+
+    # Use base class method instead of DatetimeTimedeltaMixin._get_string_slice
+    _get_string_slice = Index._get_string_slice
+
+    # error: Signature of "_resolution_obj" incompatible with supertype
+    # "DatetimeIndexOpsMixin"
+    @property
+    def _resolution_obj(self) -> Resolution | None:  # type: ignore[override]
+        return self._data._resolution_obj
+
+    # -------------------------------------------------------------------
+    # Constructors
+
+    def __new__(
+        cls,
+        data=None,
+        unit=lib.no_default,
+        freq=lib.no_default,
+        closed=lib.no_default,
+        dtype=None,
+        copy: bool = False,
+        name=None,
+    ):
+        if closed is not lib.no_default:
+            # GH#52628
+            warnings.warn(
+                f"The 'closed' keyword in {cls.__name__} construction is "
+                "deprecated and will be removed in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        if unit is not lib.no_default:
+            # GH#55499
+            warnings.warn(
+                f"The 'unit' keyword in {cls.__name__} construction is "
+                "deprecated and will be removed in a future version. "
+                "Use pd.to_timedelta instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            unit = None
+
+        name = maybe_extract_name(name, data, cls)
+
+        if is_scalar(data):
+            cls._raise_scalar_data_error(data)
+
+        disallow_ambiguous_unit(unit)
+        if dtype is not None:
+            dtype = pandas_dtype(dtype)
+
+        if (
+            isinstance(data, TimedeltaArray)
+            and freq is lib.no_default
+            and (dtype is None or dtype == data.dtype)
+        ):
+            if copy:
+                data = data.copy()
+            return cls._simple_new(data, name=name)
+
+        if (
+            isinstance(data, TimedeltaIndex)
+            and freq is lib.no_default
+            and name is None
+            and (dtype is None or dtype == data.dtype)
+        ):
+            if copy:
+                return data.copy()
+            else:
+                return data._view()
+
+        # - Cases checked above all return/raise before reaching here - #
+
+        tdarr = TimedeltaArray._from_sequence_not_strict(
+            data, freq=freq, unit=unit, dtype=dtype, copy=copy
+        )
+        refs = None
+        if not copy and isinstance(data, (ABCSeries, Index)):
+            refs = data._references
+
+        return cls._simple_new(tdarr, name=name, refs=refs)
+
+    # -------------------------------------------------------------------
+
+    def _is_comparable_dtype(self, dtype: DtypeObj) -> bool:
+        """
+        Can we compare values of the given dtype to our own?
+        """
+        return lib.is_np_dtype(dtype, "m")  # aka self._data._is_recognized_dtype
+
+    # -------------------------------------------------------------------
+    # Indexing Methods
+
+    def get_loc(self, key):
+        """
+        Get integer location for requested label
+
+        Returns
+        -------
+        loc : int, slice, or ndarray[int]
+        """
+        self._check_indexing_error(key)
+
+        try:
+            key = self._data._validate_scalar(key, unbox=False)
+        except TypeError as err:
+            raise KeyError(key) from err
+
+        return Index.get_loc(self, key)
+
+    def _parse_with_reso(self, label: str):
+        # the "with_reso" is a no-op for TimedeltaIndex
+        parsed = Timedelta(label)
+        return parsed, None
+
+    def _parsed_string_to_bounds(self, reso, parsed: Timedelta):
+        # reso is unused, included to match signature of DTI/PI
+        lbound = parsed.round(parsed.resolution_string)
+        rbound = lbound + to_offset(parsed.resolution_string) - Timedelta(1, "ns")
+        return lbound, rbound
+
+    # -------------------------------------------------------------------
+
+    @property
+    def inferred_type(self) -> str:
+        return "timedelta64"
+
+
+def timedelta_range(
+    start=None,
+    end=None,
+    periods: int | None = None,
+    freq=None,
+    name=None,
+    closed=None,
+    *,
+    unit: str | None = None,
+) -> TimedeltaIndex:
+    """
+    Return a fixed frequency TimedeltaIndex with day as the default.
+
+    Parameters
+    ----------
+    start : str or timedelta-like, default None
+        Left bound for generating timedeltas.
+    end : str or timedelta-like, default None
+        Right bound for generating timedeltas.
+    periods : int, default None
+        Number of periods to generate.
+    freq : str, Timedelta, datetime.timedelta, or DateOffset, default 'D'
+        Frequency strings can have multiples, e.g. '5h'.
+    name : str, default None
+        Name of the resulting TimedeltaIndex.
+    closed : str, default None
+        Make the interval closed with respect to the given frequency to
+        the 'left', 'right', or both sides (None).
+    unit : str, default None
+        Specify the desired resolution of the result.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    TimedeltaIndex
+
+    Notes
+    -----
+    Of the four parameters ``start``, ``end``, ``periods``, and ``freq``,
+    exactly three must be specified. If ``freq`` is omitted, the resulting
+    ``TimedeltaIndex`` will have ``periods`` linearly spaced elements between
+    ``start`` and ``end`` (closed on both sides).
+
+    To learn more about the frequency strings, please see `this link
+    `__.
+
+    Examples
+    --------
+    >>> pd.timedelta_range(start='1 day', periods=4)
+    TimedeltaIndex(['1 days', '2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq='D')
+
+    The ``closed`` parameter specifies which endpoint is included.  The default
+    behavior is to include both endpoints.
+
+    >>> pd.timedelta_range(start='1 day', periods=4, closed='right')
+    TimedeltaIndex(['2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq='D')
+
+    The ``freq`` parameter specifies the frequency of the TimedeltaIndex.
+    Only fixed frequencies can be passed, non-fixed frequencies such as
+    'M' (month end) will raise.
+
+    >>> pd.timedelta_range(start='1 day', end='2 days', freq='6h')
+    TimedeltaIndex(['1 days 00:00:00', '1 days 06:00:00', '1 days 12:00:00',
+                    '1 days 18:00:00', '2 days 00:00:00'],
+                   dtype='timedelta64[ns]', freq='6h')
+
+    Specify ``start``, ``end``, and ``periods``; the frequency is generated
+    automatically (linearly spaced).
+
+    >>> pd.timedelta_range(start='1 day', end='5 days', periods=4)
+    TimedeltaIndex(['1 days 00:00:00', '2 days 08:00:00', '3 days 16:00:00',
+                    '5 days 00:00:00'],
+                   dtype='timedelta64[ns]', freq=None)
+
+    **Specify a unit**
+
+    >>> pd.timedelta_range("1 Day", periods=3, freq="100000D", unit="s")
+    TimedeltaIndex(['1 days', '100001 days', '200001 days'],
+                   dtype='timedelta64[s]', freq='100000D')
+    """
+    if freq is None and com.any_none(periods, start, end):
+        freq = "D"
+
+    freq = to_offset(freq)
+    tdarr = TimedeltaArray._generate_range(
+        start, end, periods, freq, closed=closed, unit=unit
+    )
+    return TimedeltaIndex._simple_new(tdarr, name=name)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/indexing.py b/.venv/lib/python3.13/site-packages/pandas/core/indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..c7bab4860411f37c177366177fb5d53d16837d17
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/indexing.py
@@ -0,0 +1,2821 @@
+from __future__ import annotations
+
+from contextlib import suppress
+import sys
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypeVar,
+    cast,
+    final,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import (
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs.indexing import NDFrameIndexerBase
+from pandas._libs.lib import item_from_zerodim
+from pandas.compat import PYPY
+from pandas.compat._constants import WARNING_CHECK_DISABLED
+from pandas.errors import (
+    AbstractMethodError,
+    ChainedAssignmentError,
+    IndexingError,
+    InvalidIndexError,
+    LossySetitemError,
+    _chained_assignment_msg,
+    _chained_assignment_warning_msg,
+    _check_cacher,
+)
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    can_hold_element,
+    maybe_promote,
+)
+from pandas.core.dtypes.common import (
+    is_array_like,
+    is_bool_dtype,
+    is_hashable,
+    is_integer,
+    is_iterator,
+    is_list_like,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_scalar,
+    is_sequence,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    construct_1d_array_from_inferred_fill_value,
+    infer_fill_value,
+    is_valid_na_for_dtype,
+    isna,
+    na_value_for_dtype,
+)
+
+from pandas.core import algorithms as algos
+import pandas.core.common as com
+from pandas.core.construction import (
+    array as pd_array,
+    extract_array,
+)
+from pandas.core.indexers import (
+    check_array_indexer,
+    is_list_like_indexer,
+    is_scalar_indexer,
+    length_of_indexer,
+)
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        Axis,
+        AxisInt,
+        Self,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+T = TypeVar("T")
+# "null slice"
+_NS = slice(None, None)
+_one_ellipsis_message = "indexer may only contain one '...' entry"
+
+
+# the public IndexSlicerMaker
+class _IndexSlice:
+    """
+    Create an object to more easily perform multi-index slicing.
+
+    See Also
+    --------
+    MultiIndex.remove_unused_levels : New MultiIndex with no unused levels.
+
+    Notes
+    -----
+    See :ref:`Defined Levels `
+    for further info on slicing a MultiIndex.
+
+    Examples
+    --------
+    >>> midx = pd.MultiIndex.from_product([['A0','A1'], ['B0','B1','B2','B3']])
+    >>> columns = ['foo', 'bar']
+    >>> dfmi = pd.DataFrame(np.arange(16).reshape((len(midx), len(columns))),
+    ...                     index=midx, columns=columns)
+
+    Using the default slice command:
+
+    >>> dfmi.loc[(slice(None), slice('B0', 'B1')), :]
+               foo  bar
+        A0 B0    0    1
+           B1    2    3
+        A1 B0    8    9
+           B1   10   11
+
+    Using the IndexSlice class for a more intuitive command:
+
+    >>> idx = pd.IndexSlice
+    >>> dfmi.loc[idx[:, 'B0':'B1'], :]
+               foo  bar
+        A0 B0    0    1
+           B1    2    3
+        A1 B0    8    9
+           B1   10   11
+    """
+
+    def __getitem__(self, arg):
+        return arg
+
+
+IndexSlice = _IndexSlice()
+
+
+class IndexingMixin:
+    """
+    Mixin for adding .loc/.iloc/.at/.iat to Dataframes and Series.
+    """
+
+    @property
+    def iloc(self) -> _iLocIndexer:
+        """
+        Purely integer-location based indexing for selection by position.
+
+        .. deprecated:: 2.2.0
+
+           Returning a tuple from a callable is deprecated.
+
+        ``.iloc[]`` is primarily integer position based (from ``0`` to
+        ``length-1`` of the axis), but may also be used with a boolean
+        array.
+
+        Allowed inputs are:
+
+        - An integer, e.g. ``5``.
+        - A list or array of integers, e.g. ``[4, 3, 0]``.
+        - A slice object with ints, e.g. ``1:7``.
+        - A boolean array.
+        - A ``callable`` function with one argument (the calling Series or
+          DataFrame) and that returns valid output for indexing (one of the above).
+          This is useful in method chains, when you don't have a reference to the
+          calling object, but would like to base your selection on
+          some value.
+        - A tuple of row and column indexes. The tuple elements consist of one of the
+          above inputs, e.g. ``(0, 1)``.
+
+        ``.iloc`` will raise ``IndexError`` if a requested indexer is
+        out-of-bounds, except *slice* indexers which allow out-of-bounds
+        indexing (this conforms with python/numpy *slice* semantics).
+
+        See more at :ref:`Selection by Position `.
+
+        See Also
+        --------
+        DataFrame.iat : Fast integer location scalar accessor.
+        DataFrame.loc : Purely label-location based indexer for selection by label.
+        Series.iloc : Purely integer-location based indexing for
+                       selection by position.
+
+        Examples
+        --------
+        >>> mydict = [{'a': 1, 'b': 2, 'c': 3, 'd': 4},
+        ...           {'a': 100, 'b': 200, 'c': 300, 'd': 400},
+        ...           {'a': 1000, 'b': 2000, 'c': 3000, 'd': 4000}]
+        >>> df = pd.DataFrame(mydict)
+        >>> df
+              a     b     c     d
+        0     1     2     3     4
+        1   100   200   300   400
+        2  1000  2000  3000  4000
+
+        **Indexing just the rows**
+
+        With a scalar integer.
+
+        >>> type(df.iloc[0])
+        
+        >>> df.iloc[0]
+        a    1
+        b    2
+        c    3
+        d    4
+        Name: 0, dtype: int64
+
+        With a list of integers.
+
+        >>> df.iloc[[0]]
+           a  b  c  d
+        0  1  2  3  4
+        >>> type(df.iloc[[0]])
+        
+
+        >>> df.iloc[[0, 1]]
+             a    b    c    d
+        0    1    2    3    4
+        1  100  200  300  400
+
+        With a `slice` object.
+
+        >>> df.iloc[:3]
+              a     b     c     d
+        0     1     2     3     4
+        1   100   200   300   400
+        2  1000  2000  3000  4000
+
+        With a boolean mask the same length as the index.
+
+        >>> df.iloc[[True, False, True]]
+              a     b     c     d
+        0     1     2     3     4
+        2  1000  2000  3000  4000
+
+        With a callable, useful in method chains. The `x` passed
+        to the ``lambda`` is the DataFrame being sliced. This selects
+        the rows whose index label even.
+
+        >>> df.iloc[lambda x: x.index % 2 == 0]
+              a     b     c     d
+        0     1     2     3     4
+        2  1000  2000  3000  4000
+
+        **Indexing both axes**
+
+        You can mix the indexer types for the index and columns. Use ``:`` to
+        select the entire axis.
+
+        With scalar integers.
+
+        >>> df.iloc[0, 1]
+        2
+
+        With lists of integers.
+
+        >>> df.iloc[[0, 2], [1, 3]]
+              b     d
+        0     2     4
+        2  2000  4000
+
+        With `slice` objects.
+
+        >>> df.iloc[1:3, 0:3]
+              a     b     c
+        1   100   200   300
+        2  1000  2000  3000
+
+        With a boolean array whose length matches the columns.
+
+        >>> df.iloc[:, [True, False, True, False]]
+              a     c
+        0     1     3
+        1   100   300
+        2  1000  3000
+
+        With a callable function that expects the Series or DataFrame.
+
+        >>> df.iloc[:, lambda df: [0, 2]]
+              a     c
+        0     1     3
+        1   100   300
+        2  1000  3000
+        """
+        return _iLocIndexer("iloc", self)
+
+    @property
+    def loc(self) -> _LocIndexer:
+        """
+        Access a group of rows and columns by label(s) or a boolean array.
+
+        ``.loc[]`` is primarily label based, but may also be used with a
+        boolean array.
+
+        Allowed inputs are:
+
+        - A single label, e.g. ``5`` or ``'a'``, (note that ``5`` is
+          interpreted as a *label* of the index, and **never** as an
+          integer position along the index).
+        - A list or array of labels, e.g. ``['a', 'b', 'c']``.
+        - A slice object with labels, e.g. ``'a':'f'``.
+
+          .. warning:: Note that contrary to usual python slices, **both** the
+              start and the stop are included
+
+        - A boolean array of the same length as the axis being sliced,
+          e.g. ``[True, False, True]``.
+        - An alignable boolean Series. The index of the key will be aligned before
+          masking.
+        - An alignable Index. The Index of the returned selection will be the input.
+        - A ``callable`` function with one argument (the calling Series or
+          DataFrame) and that returns valid output for indexing (one of the above)
+
+        See more at :ref:`Selection by Label `.
+
+        Raises
+        ------
+        KeyError
+            If any items are not found.
+        IndexingError
+            If an indexed key is passed and its index is unalignable to the frame index.
+
+        See Also
+        --------
+        DataFrame.at : Access a single value for a row/column label pair.
+        DataFrame.iloc : Access group of rows and columns by integer position(s).
+        DataFrame.xs : Returns a cross-section (row(s) or column(s)) from the
+                       Series/DataFrame.
+        Series.loc : Access group of values using labels.
+
+        Examples
+        --------
+        **Getting values**
+
+        >>> df = pd.DataFrame([[1, 2], [4, 5], [7, 8]],
+        ...                   index=['cobra', 'viper', 'sidewinder'],
+        ...                   columns=['max_speed', 'shield'])
+        >>> df
+                    max_speed  shield
+        cobra               1       2
+        viper               4       5
+        sidewinder          7       8
+
+        Single label. Note this returns the row as a Series.
+
+        >>> df.loc['viper']
+        max_speed    4
+        shield       5
+        Name: viper, dtype: int64
+
+        List of labels. Note using ``[[]]`` returns a DataFrame.
+
+        >>> df.loc[['viper', 'sidewinder']]
+                    max_speed  shield
+        viper               4       5
+        sidewinder          7       8
+
+        Single label for row and column
+
+        >>> df.loc['cobra', 'shield']
+        2
+
+        Slice with labels for row and single label for column. As mentioned
+        above, note that both the start and stop of the slice are included.
+
+        >>> df.loc['cobra':'viper', 'max_speed']
+        cobra    1
+        viper    4
+        Name: max_speed, dtype: int64
+
+        Boolean list with the same length as the row axis
+
+        >>> df.loc[[False, False, True]]
+                    max_speed  shield
+        sidewinder          7       8
+
+        Alignable boolean Series:
+
+        >>> df.loc[pd.Series([False, True, False],
+        ...                  index=['viper', 'sidewinder', 'cobra'])]
+                             max_speed  shield
+        sidewinder          7       8
+
+        Index (same behavior as ``df.reindex``)
+
+        >>> df.loc[pd.Index(["cobra", "viper"], name="foo")]
+               max_speed  shield
+        foo
+        cobra          1       2
+        viper          4       5
+
+        Conditional that returns a boolean Series
+
+        >>> df.loc[df['shield'] > 6]
+                    max_speed  shield
+        sidewinder          7       8
+
+        Conditional that returns a boolean Series with column labels specified
+
+        >>> df.loc[df['shield'] > 6, ['max_speed']]
+                    max_speed
+        sidewinder          7
+
+        Multiple conditional using ``&`` that returns a boolean Series
+
+        >>> df.loc[(df['max_speed'] > 1) & (df['shield'] < 8)]
+                    max_speed  shield
+        viper          4       5
+
+        Multiple conditional using ``|`` that returns a boolean Series
+
+        >>> df.loc[(df['max_speed'] > 4) | (df['shield'] < 5)]
+                    max_speed  shield
+        cobra               1       2
+        sidewinder          7       8
+
+        Please ensure that each condition is wrapped in parentheses ``()``.
+        See the :ref:`user guide`
+        for more details and explanations of Boolean indexing.
+
+        .. note::
+            If you find yourself using 3 or more conditionals in ``.loc[]``,
+            consider using :ref:`advanced indexing`.
+
+            See below for using ``.loc[]`` on MultiIndex DataFrames.
+
+        Callable that returns a boolean Series
+
+        >>> df.loc[lambda df: df['shield'] == 8]
+                    max_speed  shield
+        sidewinder          7       8
+
+        **Setting values**
+
+        Set value for all items matching the list of labels
+
+        >>> df.loc[['viper', 'sidewinder'], ['shield']] = 50
+        >>> df
+                    max_speed  shield
+        cobra               1       2
+        viper               4      50
+        sidewinder          7      50
+
+        Set value for an entire row
+
+        >>> df.loc['cobra'] = 10
+        >>> df
+                    max_speed  shield
+        cobra              10      10
+        viper               4      50
+        sidewinder          7      50
+
+        Set value for an entire column
+
+        >>> df.loc[:, 'max_speed'] = 30
+        >>> df
+                    max_speed  shield
+        cobra              30      10
+        viper              30      50
+        sidewinder         30      50
+
+        Set value for rows matching callable condition
+
+        >>> df.loc[df['shield'] > 35] = 0
+        >>> df
+                    max_speed  shield
+        cobra              30      10
+        viper               0       0
+        sidewinder          0       0
+
+        Add value matching location
+
+        >>> df.loc["viper", "shield"] += 5
+        >>> df
+                    max_speed  shield
+        cobra              30      10
+        viper               0       5
+        sidewinder          0       0
+
+        Setting using a ``Series`` or a ``DataFrame`` sets the values matching the
+        index labels, not the index positions.
+
+        >>> shuffled_df = df.loc[["viper", "cobra", "sidewinder"]]
+        >>> df.loc[:] += shuffled_df
+        >>> df
+                    max_speed  shield
+        cobra              60      20
+        viper               0      10
+        sidewinder          0       0
+
+        **Getting values on a DataFrame with an index that has integer labels**
+
+        Another example using integers for the index
+
+        >>> df = pd.DataFrame([[1, 2], [4, 5], [7, 8]],
+        ...                   index=[7, 8, 9], columns=['max_speed', 'shield'])
+        >>> df
+           max_speed  shield
+        7          1       2
+        8          4       5
+        9          7       8
+
+        Slice with integer labels for rows. As mentioned above, note that both
+        the start and stop of the slice are included.
+
+        >>> df.loc[7:9]
+           max_speed  shield
+        7          1       2
+        8          4       5
+        9          7       8
+
+        **Getting values with a MultiIndex**
+
+        A number of examples using a DataFrame with a MultiIndex
+
+        >>> tuples = [
+        ...     ('cobra', 'mark i'), ('cobra', 'mark ii'),
+        ...     ('sidewinder', 'mark i'), ('sidewinder', 'mark ii'),
+        ...     ('viper', 'mark ii'), ('viper', 'mark iii')
+        ... ]
+        >>> index = pd.MultiIndex.from_tuples(tuples)
+        >>> values = [[12, 2], [0, 4], [10, 20],
+        ...           [1, 4], [7, 1], [16, 36]]
+        >>> df = pd.DataFrame(values, columns=['max_speed', 'shield'], index=index)
+        >>> df
+                             max_speed  shield
+        cobra      mark i           12       2
+                   mark ii           0       4
+        sidewinder mark i           10      20
+                   mark ii           1       4
+        viper      mark ii           7       1
+                   mark iii         16      36
+
+        Single label. Note this returns a DataFrame with a single index.
+
+        >>> df.loc['cobra']
+                 max_speed  shield
+        mark i          12       2
+        mark ii          0       4
+
+        Single index tuple. Note this returns a Series.
+
+        >>> df.loc[('cobra', 'mark ii')]
+        max_speed    0
+        shield       4
+        Name: (cobra, mark ii), dtype: int64
+
+        Single label for row and column. Similar to passing in a tuple, this
+        returns a Series.
+
+        >>> df.loc['cobra', 'mark i']
+        max_speed    12
+        shield        2
+        Name: (cobra, mark i), dtype: int64
+
+        Single tuple. Note using ``[[]]`` returns a DataFrame.
+
+        >>> df.loc[[('cobra', 'mark ii')]]
+                       max_speed  shield
+        cobra mark ii          0       4
+
+        Single tuple for the index with a single label for the column
+
+        >>> df.loc[('cobra', 'mark i'), 'shield']
+        2
+
+        Slice from index tuple to single label
+
+        >>> df.loc[('cobra', 'mark i'):'viper']
+                             max_speed  shield
+        cobra      mark i           12       2
+                   mark ii           0       4
+        sidewinder mark i           10      20
+                   mark ii           1       4
+        viper      mark ii           7       1
+                   mark iii         16      36
+
+        Slice from index tuple to index tuple
+
+        >>> df.loc[('cobra', 'mark i'):('viper', 'mark ii')]
+                            max_speed  shield
+        cobra      mark i          12       2
+                   mark ii          0       4
+        sidewinder mark i          10      20
+                   mark ii          1       4
+        viper      mark ii          7       1
+
+        Please see the :ref:`user guide`
+        for more details and explanations of advanced indexing.
+        """
+        return _LocIndexer("loc", self)
+
+    @property
+    def at(self) -> _AtIndexer:
+        """
+        Access a single value for a row/column label pair.
+
+        Similar to ``loc``, in that both provide label-based lookups. Use
+        ``at`` if you only need to get or set a single value in a DataFrame
+        or Series.
+
+        Raises
+        ------
+        KeyError
+            If getting a value and 'label' does not exist in a DataFrame or Series.
+
+        ValueError
+            If row/column label pair is not a tuple or if any label
+            from the pair is not a scalar for DataFrame.
+            If label is list-like (*excluding* NamedTuple) for Series.
+
+        See Also
+        --------
+        DataFrame.at : Access a single value for a row/column pair by label.
+        DataFrame.iat : Access a single value for a row/column pair by integer
+            position.
+        DataFrame.loc : Access a group of rows and columns by label(s).
+        DataFrame.iloc : Access a group of rows and columns by integer
+            position(s).
+        Series.at : Access a single value by label.
+        Series.iat : Access a single value by integer position.
+        Series.loc : Access a group of rows by label(s).
+        Series.iloc : Access a group of rows by integer position(s).
+
+        Notes
+        -----
+        See :ref:`Fast scalar value getting and setting `
+        for more details.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[0, 2, 3], [0, 4, 1], [10, 20, 30]],
+        ...                   index=[4, 5, 6], columns=['A', 'B', 'C'])
+        >>> df
+            A   B   C
+        4   0   2   3
+        5   0   4   1
+        6  10  20  30
+
+        Get value at specified row/column pair
+
+        >>> df.at[4, 'B']
+        2
+
+        Set value at specified row/column pair
+
+        >>> df.at[4, 'B'] = 10
+        >>> df.at[4, 'B']
+        10
+
+        Get value within a Series
+
+        >>> df.loc[5].at['B']
+        4
+        """
+        return _AtIndexer("at", self)
+
+    @property
+    def iat(self) -> _iAtIndexer:
+        """
+        Access a single value for a row/column pair by integer position.
+
+        Similar to ``iloc``, in that both provide integer-based lookups. Use
+        ``iat`` if you only need to get or set a single value in a DataFrame
+        or Series.
+
+        Raises
+        ------
+        IndexError
+            When integer position is out of bounds.
+
+        See Also
+        --------
+        DataFrame.at : Access a single value for a row/column label pair.
+        DataFrame.loc : Access a group of rows and columns by label(s).
+        DataFrame.iloc : Access a group of rows and columns by integer position(s).
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[0, 2, 3], [0, 4, 1], [10, 20, 30]],
+        ...                   columns=['A', 'B', 'C'])
+        >>> df
+            A   B   C
+        0   0   2   3
+        1   0   4   1
+        2  10  20  30
+
+        Get value at specified row/column pair
+
+        >>> df.iat[1, 2]
+        1
+
+        Set value at specified row/column pair
+
+        >>> df.iat[1, 2] = 10
+        >>> df.iat[1, 2]
+        10
+
+        Get value within a series
+
+        >>> df.loc[0].iat[1]
+        2
+        """
+        return _iAtIndexer("iat", self)
+
+
+class _LocationIndexer(NDFrameIndexerBase):
+    _valid_types: str
+    axis: AxisInt | None = None
+
+    # sub-classes need to set _takeable
+    _takeable: bool
+
+    @final
+    def __call__(self, axis: Axis | None = None) -> Self:
+        # we need to return a copy of ourselves
+        new_self = type(self)(self.name, self.obj)
+
+        if axis is not None:
+            axis_int_none = self.obj._get_axis_number(axis)
+        else:
+            axis_int_none = axis
+        new_self.axis = axis_int_none
+        return new_self
+
+    def _get_setitem_indexer(self, key):
+        """
+        Convert a potentially-label-based key into a positional indexer.
+        """
+        if self.name == "loc":
+            # always holds here bc iloc overrides _get_setitem_indexer
+            self._ensure_listlike_indexer(key)
+
+        if isinstance(key, tuple):
+            for x in key:
+                check_dict_or_set_indexers(x)
+
+        if self.axis is not None:
+            key = _tupleize_axis_indexer(self.ndim, self.axis, key)
+
+        ax = self.obj._get_axis(0)
+
+        if (
+            isinstance(ax, MultiIndex)
+            and self.name != "iloc"
+            and is_hashable(key)
+            and not isinstance(key, slice)
+        ):
+            with suppress(KeyError, InvalidIndexError):
+                # TypeError e.g. passed a bool
+                return ax.get_loc(key)
+
+        if isinstance(key, tuple):
+            with suppress(IndexingError):
+                # suppress "Too many indexers"
+                return self._convert_tuple(key)
+
+        if isinstance(key, range):
+            # GH#45479 test_loc_setitem_range_key
+            key = list(key)
+
+        return self._convert_to_indexer(key, axis=0)
+
+    @final
+    def _maybe_mask_setitem_value(self, indexer, value):
+        """
+        If we have obj.iloc[mask] = series_or_frame and series_or_frame has the
+        same length as obj, we treat this as obj.iloc[mask] = series_or_frame[mask],
+        similar to Series.__setitem__.
+
+        Note this is only for loc, not iloc.
+        """
+
+        if (
+            isinstance(indexer, tuple)
+            and len(indexer) == 2
+            and isinstance(value, (ABCSeries, ABCDataFrame))
+        ):
+            pi, icols = indexer
+            ndim = value.ndim
+            if com.is_bool_indexer(pi) and len(value) == len(pi):
+                newkey = pi.nonzero()[0]
+
+                if is_scalar_indexer(icols, self.ndim - 1) and ndim == 1:
+                    # e.g. test_loc_setitem_boolean_mask_allfalse
+                    # test_loc_setitem_ndframe_values_alignment
+                    value = self.obj.iloc._align_series(indexer, value)
+                    indexer = (newkey, icols)
+
+                elif (
+                    isinstance(icols, np.ndarray)
+                    and icols.dtype.kind == "i"
+                    and len(icols) == 1
+                ):
+                    if ndim == 1:
+                        # We implicitly broadcast, though numpy does not, see
+                        # github.com/pandas-dev/pandas/pull/45501#discussion_r789071825
+                        # test_loc_setitem_ndframe_values_alignment
+                        value = self.obj.iloc._align_series(indexer, value)
+                        indexer = (newkey, icols)
+
+                    elif ndim == 2 and value.shape[1] == 1:
+                        # test_loc_setitem_ndframe_values_alignment
+                        value = self.obj.iloc._align_frame(indexer, value)
+                        indexer = (newkey, icols)
+        elif com.is_bool_indexer(indexer):
+            indexer = indexer.nonzero()[0]
+
+        return indexer, value
+
+    @final
+    def _ensure_listlike_indexer(self, key, axis=None, value=None) -> None:
+        """
+        Ensure that a list-like of column labels are all present by adding them if
+        they do not already exist.
+
+        Parameters
+        ----------
+        key : list-like of column labels
+            Target labels.
+        axis : key axis if known
+        """
+        column_axis = 1
+
+        # column only exists in 2-dimensional DataFrame
+        if self.ndim != 2:
+            return
+
+        if isinstance(key, tuple) and len(key) > 1:
+            # key may be a tuple if we are .loc
+            # if length of key is > 1 set key to column part
+            key = key[column_axis]
+            axis = column_axis
+
+        if (
+            axis == column_axis
+            and not isinstance(self.obj.columns, MultiIndex)
+            and is_list_like_indexer(key)
+            and not com.is_bool_indexer(key)
+            and all(is_hashable(k) for k in key)
+        ):
+            # GH#38148
+            keys = self.obj.columns.union(key, sort=False)
+            diff = Index(key).difference(self.obj.columns, sort=False)
+
+            if len(diff):
+                # e.g. if we are doing df.loc[:, ["A", "B"]] = 7 and "B"
+                #  is a new column, add the new columns with dtype=np.void
+                #  so that later when we go through setitem_single_column
+                #  we will use isetitem. Without this, the reindex_axis
+                #  below would create float64 columns in this example, which
+                #  would successfully hold 7, so we would end up with the wrong
+                #  dtype.
+                indexer = np.arange(len(keys), dtype=np.intp)
+                indexer[len(self.obj.columns) :] = -1
+                new_mgr = self.obj._mgr.reindex_indexer(
+                    keys, indexer=indexer, axis=0, only_slice=True, use_na_proxy=True
+                )
+                self.obj._mgr = new_mgr
+                return
+
+            self.obj._mgr = self.obj._mgr.reindex_axis(keys, axis=0, only_slice=True)
+
+    @final
+    def __setitem__(self, key, value) -> None:
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self.obj) <= 2:
+                warnings.warn(
+                    _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
+                )
+        elif not PYPY and not WARNING_CHECK_DISABLED and not using_copy_on_write():
+            ctr = sys.getrefcount(self.obj)
+            ref_count = 2
+            if not warn_copy_on_write() and _check_cacher(self.obj):
+                # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                ref_count += 1
+            if ctr <= ref_count:
+                warnings.warn(
+                    _chained_assignment_warning_msg, FutureWarning, stacklevel=2
+                )
+
+        check_dict_or_set_indexers(key)
+        if isinstance(key, tuple):
+            key = tuple(list(x) if is_iterator(x) else x for x in key)
+            key = tuple(com.apply_if_callable(x, self.obj) for x in key)
+        else:
+            maybe_callable = com.apply_if_callable(key, self.obj)
+            key = self._check_deprecated_callable_usage(key, maybe_callable)
+        indexer = self._get_setitem_indexer(key)
+        self._has_valid_setitem_indexer(key)
+
+        iloc = self if self.name == "iloc" else self.obj.iloc
+        iloc._setitem_with_indexer(indexer, value, self.name)
+
+    def _validate_key(self, key, axis: AxisInt):
+        """
+        Ensure that key is valid for current indexer.
+
+        Parameters
+        ----------
+        key : scalar, slice or list-like
+            Key requested.
+        axis : int
+            Dimension on which the indexing is being made.
+
+        Raises
+        ------
+        TypeError
+            If the key (or some element of it) has wrong type.
+        IndexError
+            If the key (or some element of it) is out of bounds.
+        KeyError
+            If the key was not found.
+        """
+        raise AbstractMethodError(self)
+
+    @final
+    def _expand_ellipsis(self, tup: tuple) -> tuple:
+        """
+        If a tuple key includes an Ellipsis, replace it with an appropriate
+        number of null slices.
+        """
+        if any(x is Ellipsis for x in tup):
+            if tup.count(Ellipsis) > 1:
+                raise IndexingError(_one_ellipsis_message)
+
+            if len(tup) == self.ndim:
+                # It is unambiguous what axis this Ellipsis is indexing,
+                #  treat as a single null slice.
+                i = tup.index(Ellipsis)
+                # FIXME: this assumes only one Ellipsis
+                new_key = tup[:i] + (_NS,) + tup[i + 1 :]
+                return new_key
+
+            # TODO: other cases?  only one test gets here, and that is covered
+            #  by _validate_key_length
+        return tup
+
+    @final
+    def _validate_tuple_indexer(self, key: tuple) -> tuple:
+        """
+        Check the key for valid keys across my indexer.
+        """
+        key = self._validate_key_length(key)
+        key = self._expand_ellipsis(key)
+        for i, k in enumerate(key):
+            try:
+                self._validate_key(k, i)
+            except ValueError as err:
+                raise ValueError(
+                    "Location based indexing can only have "
+                    f"[{self._valid_types}] types"
+                ) from err
+        return key
+
+    @final
+    def _is_nested_tuple_indexer(self, tup: tuple) -> bool:
+        """
+        Returns
+        -------
+        bool
+        """
+        if any(isinstance(ax, MultiIndex) for ax in self.obj.axes):
+            return any(is_nested_tuple(tup, ax) for ax in self.obj.axes)
+        return False
+
+    @final
+    def _convert_tuple(self, key: tuple) -> tuple:
+        # Note: we assume _tupleize_axis_indexer has been called, if necessary.
+        self._validate_key_length(key)
+        keyidx = [self._convert_to_indexer(k, axis=i) for i, k in enumerate(key)]
+        return tuple(keyidx)
+
+    @final
+    def _validate_key_length(self, key: tuple) -> tuple:
+        if len(key) > self.ndim:
+            if key[0] is Ellipsis:
+                # e.g. Series.iloc[..., 3] reduces to just Series.iloc[3]
+                key = key[1:]
+                if Ellipsis in key:
+                    raise IndexingError(_one_ellipsis_message)
+                return self._validate_key_length(key)
+            raise IndexingError("Too many indexers")
+        return key
+
+    @final
+    def _getitem_tuple_same_dim(self, tup: tuple):
+        """
+        Index with indexers that should return an object of the same dimension
+        as self.obj.
+
+        This is only called after a failed call to _getitem_lowerdim.
+        """
+        retval = self.obj
+        # Selecting columns before rows is significantly faster
+        start_val = (self.ndim - len(tup)) + 1
+        for i, key in enumerate(reversed(tup)):
+            i = self.ndim - i - start_val
+            if com.is_null_slice(key):
+                continue
+
+            retval = getattr(retval, self.name)._getitem_axis(key, axis=i)
+            # We should never have retval.ndim < self.ndim, as that should
+            #  be handled by the _getitem_lowerdim call above.
+            assert retval.ndim == self.ndim
+
+        if retval is self.obj:
+            # if all axes were a null slice (`df.loc[:, :]`), ensure we still
+            # return a new object (https://github.com/pandas-dev/pandas/pull/49469)
+            retval = retval.copy(deep=False)
+
+        return retval
+
+    @final
+    def _getitem_lowerdim(self, tup: tuple):
+        # we can directly get the axis result since the axis is specified
+        if self.axis is not None:
+            axis = self.obj._get_axis_number(self.axis)
+            return self._getitem_axis(tup, axis=axis)
+
+        # we may have a nested tuples indexer here
+        if self._is_nested_tuple_indexer(tup):
+            return self._getitem_nested_tuple(tup)
+
+        # we maybe be using a tuple to represent multiple dimensions here
+        ax0 = self.obj._get_axis(0)
+        # ...but iloc should handle the tuple as simple integer-location
+        # instead of checking it as multiindex representation (GH 13797)
+        if (
+            isinstance(ax0, MultiIndex)
+            and self.name != "iloc"
+            and not any(isinstance(x, slice) for x in tup)
+        ):
+            # Note: in all extant test cases, replacing the slice condition with
+            #  `all(is_hashable(x) or com.is_null_slice(x) for x in tup)`
+            #  is equivalent.
+            #  (see the other place where we call _handle_lowerdim_multi_index_axis0)
+            with suppress(IndexingError):
+                return cast(_LocIndexer, self)._handle_lowerdim_multi_index_axis0(tup)
+
+        tup = self._validate_key_length(tup)
+
+        for i, key in enumerate(tup):
+            if is_label_like(key):
+                # We don't need to check for tuples here because those are
+                #  caught by the _is_nested_tuple_indexer check above.
+                section = self._getitem_axis(key, axis=i)
+
+                # We should never have a scalar section here, because
+                #  _getitem_lowerdim is only called after a check for
+                #  is_scalar_access, which that would be.
+                if section.ndim == self.ndim:
+                    # we're in the middle of slicing through a MultiIndex
+                    # revise the key wrt to `section` by inserting an _NS
+                    new_key = tup[:i] + (_NS,) + tup[i + 1 :]
+
+                else:
+                    # Note: the section.ndim == self.ndim check above
+                    #  rules out having DataFrame here, so we dont need to worry
+                    #  about transposing.
+                    new_key = tup[:i] + tup[i + 1 :]
+
+                    if len(new_key) == 1:
+                        new_key = new_key[0]
+
+                # Slices should return views, but calling iloc/loc with a null
+                # slice returns a new object.
+                if com.is_null_slice(new_key):
+                    return section
+                # This is an elided recursive call to iloc/loc
+                return getattr(section, self.name)[new_key]
+
+        raise IndexingError("not applicable")
+
+    @final
+    def _getitem_nested_tuple(self, tup: tuple):
+        # we have a nested tuple so have at least 1 multi-index level
+        # we should be able to match up the dimensionality here
+
+        def _contains_slice(x: object) -> bool:
+            # Check if object is a slice or a tuple containing a slice
+            if isinstance(x, tuple):
+                return any(isinstance(v, slice) for v in x)
+            elif isinstance(x, slice):
+                return True
+            return False
+
+        for key in tup:
+            check_dict_or_set_indexers(key)
+
+        # we have too many indexers for our dim, but have at least 1
+        # multi-index dimension, try to see if we have something like
+        # a tuple passed to a series with a multi-index
+        if len(tup) > self.ndim:
+            if self.name != "loc":
+                # This should never be reached, but let's be explicit about it
+                raise ValueError("Too many indices")  # pragma: no cover
+            if all(
+                (is_hashable(x) and not _contains_slice(x)) or com.is_null_slice(x)
+                for x in tup
+            ):
+                # GH#10521 Series should reduce MultiIndex dimensions instead of
+                #  DataFrame, IndexingError is not raised when slice(None,None,None)
+                #  with one row.
+                with suppress(IndexingError):
+                    return cast(_LocIndexer, self)._handle_lowerdim_multi_index_axis0(
+                        tup
+                    )
+            elif isinstance(self.obj, ABCSeries) and any(
+                isinstance(k, tuple) for k in tup
+            ):
+                # GH#35349 Raise if tuple in tuple for series
+                # Do this after the all-hashable-or-null-slice check so that
+                #  we are only getting non-hashable tuples, in particular ones
+                #  that themselves contain a slice entry
+                # See test_loc_series_getitem_too_many_dimensions
+                raise IndexingError("Too many indexers")
+
+            # this is a series with a multi-index specified a tuple of
+            # selectors
+            axis = self.axis or 0
+            return self._getitem_axis(tup, axis=axis)
+
+        # handle the multi-axis by taking sections and reducing
+        # this is iterative
+        obj = self.obj
+        # GH#41369 Loop in reverse order ensures indexing along columns before rows
+        # which selects only necessary blocks which avoids dtype conversion if possible
+        axis = len(tup) - 1
+        for key in tup[::-1]:
+            if com.is_null_slice(key):
+                axis -= 1
+                continue
+
+            obj = getattr(obj, self.name)._getitem_axis(key, axis=axis)
+            axis -= 1
+
+            # if we have a scalar, we are done
+            if is_scalar(obj) or not hasattr(obj, "ndim"):
+                break
+
+        return obj
+
+    def _convert_to_indexer(self, key, axis: AxisInt):
+        raise AbstractMethodError(self)
+
+    def _check_deprecated_callable_usage(self, key: Any, maybe_callable: T) -> T:
+        # GH53533
+        if self.name == "iloc" and callable(key) and isinstance(maybe_callable, tuple):
+            warnings.warn(
+                "Returning a tuple from a callable with iloc "
+                "is deprecated and will be removed in a future version",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return maybe_callable
+
+    @final
+    def __getitem__(self, key):
+        check_dict_or_set_indexers(key)
+        if type(key) is tuple:
+            key = tuple(list(x) if is_iterator(x) else x for x in key)
+            key = tuple(com.apply_if_callable(x, self.obj) for x in key)
+            if self._is_scalar_access(key):
+                return self.obj._get_value(*key, takeable=self._takeable)
+            return self._getitem_tuple(key)
+        else:
+            # we by definition only have the 0th axis
+            axis = self.axis or 0
+
+            maybe_callable = com.apply_if_callable(key, self.obj)
+            maybe_callable = self._check_deprecated_callable_usage(key, maybe_callable)
+            return self._getitem_axis(maybe_callable, axis=axis)
+
+    def _is_scalar_access(self, key: tuple):
+        raise NotImplementedError()
+
+    def _getitem_tuple(self, tup: tuple):
+        raise AbstractMethodError(self)
+
+    def _getitem_axis(self, key, axis: AxisInt):
+        raise NotImplementedError()
+
+    def _has_valid_setitem_indexer(self, indexer) -> bool:
+        raise AbstractMethodError(self)
+
+    @final
+    def _getbool_axis(self, key, axis: AxisInt):
+        # caller is responsible for ensuring non-None axis
+        labels = self.obj._get_axis(axis)
+        key = check_bool_indexer(labels, key)
+        inds = key.nonzero()[0]
+        return self.obj._take_with_is_copy(inds, axis=axis)
+
+
+@doc(IndexingMixin.loc)
+class _LocIndexer(_LocationIndexer):
+    _takeable: bool = False
+    _valid_types = (
+        "labels (MUST BE IN THE INDEX), slices of labels (BOTH "
+        "endpoints included! Can be slices of integers if the "
+        "index is integers), listlike of labels, boolean"
+    )
+
+    # -------------------------------------------------------------------
+    # Key Checks
+
+    @doc(_LocationIndexer._validate_key)
+    def _validate_key(self, key, axis: Axis):
+        # valid for a collection of labels (we check their presence later)
+        # slice of labels (where start-end in labels)
+        # slice of integers (only if in the labels)
+        # boolean not in slice and with boolean index
+        ax = self.obj._get_axis(axis)
+        if isinstance(key, bool) and not (
+            is_bool_dtype(ax.dtype)
+            or ax.dtype.name == "boolean"
+            or isinstance(ax, MultiIndex)
+            and is_bool_dtype(ax.get_level_values(0).dtype)
+        ):
+            raise KeyError(
+                f"{key}: boolean label can not be used without a boolean index"
+            )
+
+        if isinstance(key, slice) and (
+            isinstance(key.start, bool) or isinstance(key.stop, bool)
+        ):
+            raise TypeError(f"{key}: boolean values can not be used in a slice")
+
+    def _has_valid_setitem_indexer(self, indexer) -> bool:
+        return True
+
+    def _is_scalar_access(self, key: tuple) -> bool:
+        """
+        Returns
+        -------
+        bool
+        """
+        # this is a shortcut accessor to both .loc and .iloc
+        # that provide the equivalent access of .at and .iat
+        # a) avoid getting things via sections and (to minimize dtype changes)
+        # b) provide a performant path
+        if len(key) != self.ndim:
+            return False
+
+        for i, k in enumerate(key):
+            if not is_scalar(k):
+                return False
+
+            ax = self.obj.axes[i]
+            if isinstance(ax, MultiIndex):
+                return False
+
+            if isinstance(k, str) and ax._supports_partial_string_indexing:
+                # partial string indexing, df.loc['2000', 'A']
+                # should not be considered scalar
+                return False
+
+            if not ax._index_as_unique:
+                return False
+
+        return True
+
+    # -------------------------------------------------------------------
+    # MultiIndex Handling
+
+    def _multi_take_opportunity(self, tup: tuple) -> bool:
+        """
+        Check whether there is the possibility to use ``_multi_take``.
+
+        Currently the limit is that all axes being indexed, must be indexed with
+        list-likes.
+
+        Parameters
+        ----------
+        tup : tuple
+            Tuple of indexers, one per axis.
+
+        Returns
+        -------
+        bool
+            Whether the current indexing,
+            can be passed through `_multi_take`.
+        """
+        if not all(is_list_like_indexer(x) for x in tup):
+            return False
+
+        # just too complicated
+        return not any(com.is_bool_indexer(x) for x in tup)
+
+    def _multi_take(self, tup: tuple):
+        """
+        Create the indexers for the passed tuple of keys, and
+        executes the take operation. This allows the take operation to be
+        executed all at once, rather than once for each dimension.
+        Improving efficiency.
+
+        Parameters
+        ----------
+        tup : tuple
+            Tuple of indexers, one per axis.
+
+        Returns
+        -------
+        values: same type as the object being indexed
+        """
+        # GH 836
+        d = {
+            axis: self._get_listlike_indexer(key, axis)
+            for (key, axis) in zip(tup, self.obj._AXIS_ORDERS)
+        }
+        return self.obj._reindex_with_indexers(d, copy=True, allow_dups=True)
+
+    # -------------------------------------------------------------------
+
+    def _getitem_iterable(self, key, axis: AxisInt):
+        """
+        Index current object with an iterable collection of keys.
+
+        Parameters
+        ----------
+        key : iterable
+            Targeted labels.
+        axis : int
+            Dimension on which the indexing is being made.
+
+        Raises
+        ------
+        KeyError
+            If no key was found. Will change in the future to raise if not all
+            keys were found.
+
+        Returns
+        -------
+        scalar, DataFrame, or Series: indexed value(s).
+        """
+        # we assume that not com.is_bool_indexer(key), as that is
+        #  handled before we get here.
+        self._validate_key(key, axis)
+
+        # A collection of keys
+        keyarr, indexer = self._get_listlike_indexer(key, axis)
+        return self.obj._reindex_with_indexers(
+            {axis: [keyarr, indexer]}, copy=True, allow_dups=True
+        )
+
+    def _getitem_tuple(self, tup: tuple):
+        with suppress(IndexingError):
+            tup = self._expand_ellipsis(tup)
+            return self._getitem_lowerdim(tup)
+
+        # no multi-index, so validate all of the indexers
+        tup = self._validate_tuple_indexer(tup)
+
+        # ugly hack for GH #836
+        if self._multi_take_opportunity(tup):
+            return self._multi_take(tup)
+
+        return self._getitem_tuple_same_dim(tup)
+
+    def _get_label(self, label, axis: AxisInt):
+        # GH#5567 this will fail if the label is not present in the axis.
+        return self.obj.xs(label, axis=axis)
+
+    def _handle_lowerdim_multi_index_axis0(self, tup: tuple):
+        # we have an axis0 multi-index, handle or raise
+        axis = self.axis or 0
+        try:
+            # fast path for series or for tup devoid of slices
+            return self._get_label(tup, axis=axis)
+
+        except KeyError as ek:
+            # raise KeyError if number of indexers match
+            # else IndexingError will be raised
+            if self.ndim < len(tup) <= self.obj.index.nlevels:
+                raise ek
+            raise IndexingError("No label returned") from ek
+
+    def _getitem_axis(self, key, axis: AxisInt):
+        key = item_from_zerodim(key)
+        if is_iterator(key):
+            key = list(key)
+        if key is Ellipsis:
+            key = slice(None)
+
+        labels = self.obj._get_axis(axis)
+
+        if isinstance(key, tuple) and isinstance(labels, MultiIndex):
+            key = tuple(key)
+
+        if isinstance(key, slice):
+            self._validate_key(key, axis)
+            return self._get_slice_axis(key, axis=axis)
+        elif com.is_bool_indexer(key):
+            return self._getbool_axis(key, axis=axis)
+        elif is_list_like_indexer(key):
+            # an iterable multi-selection
+            if not (isinstance(key, tuple) and isinstance(labels, MultiIndex)):
+                if hasattr(key, "ndim") and key.ndim > 1:
+                    raise ValueError("Cannot index with multidimensional key")
+
+                return self._getitem_iterable(key, axis=axis)
+
+            # nested tuple slicing
+            if is_nested_tuple(key, labels):
+                locs = labels.get_locs(key)
+                indexer: list[slice | npt.NDArray[np.intp]] = [slice(None)] * self.ndim
+                indexer[axis] = locs
+                return self.obj.iloc[tuple(indexer)]
+
+        # fall thru to straight lookup
+        self._validate_key(key, axis)
+        return self._get_label(key, axis=axis)
+
+    def _get_slice_axis(self, slice_obj: slice, axis: AxisInt):
+        """
+        This is pretty simple as we just have to deal with labels.
+        """
+        # caller is responsible for ensuring non-None axis
+        obj = self.obj
+        if not need_slice(slice_obj):
+            return obj.copy(deep=False)
+
+        labels = obj._get_axis(axis)
+        indexer = labels.slice_indexer(slice_obj.start, slice_obj.stop, slice_obj.step)
+
+        if isinstance(indexer, slice):
+            return self.obj._slice(indexer, axis=axis)
+        else:
+            # DatetimeIndex overrides Index.slice_indexer and may
+            #  return a DatetimeIndex instead of a slice object.
+            return self.obj.take(indexer, axis=axis)
+
+    def _convert_to_indexer(self, key, axis: AxisInt):
+        """
+        Convert indexing key into something we can use to do actual fancy
+        indexing on a ndarray.
+
+        Examples
+        ix[:5] -> slice(0, 5)
+        ix[[1,2,3]] -> [1,2,3]
+        ix[['foo', 'bar', 'baz']] -> [i, j, k] (indices of foo, bar, baz)
+
+        Going by Zen of Python?
+        'In the face of ambiguity, refuse the temptation to guess.'
+        raise AmbiguousIndexError with integer labels?
+        - No, prefer label-based indexing
+        """
+        labels = self.obj._get_axis(axis)
+
+        if isinstance(key, slice):
+            return labels._convert_slice_indexer(key, kind="loc")
+
+        if (
+            isinstance(key, tuple)
+            and not isinstance(labels, MultiIndex)
+            and self.ndim < 2
+            and len(key) > 1
+        ):
+            raise IndexingError("Too many indexers")
+
+        # Slices are not valid keys passed in by the user,
+        # even though they are hashable in Python 3.12
+        contains_slice = False
+        if isinstance(key, tuple):
+            contains_slice = any(isinstance(v, slice) for v in key)
+
+        if is_scalar(key) or (
+            isinstance(labels, MultiIndex) and is_hashable(key) and not contains_slice
+        ):
+            # Otherwise get_loc will raise InvalidIndexError
+
+            # if we are a label return me
+            try:
+                return labels.get_loc(key)
+            except LookupError:
+                if isinstance(key, tuple) and isinstance(labels, MultiIndex):
+                    if len(key) == labels.nlevels:
+                        return {"key": key}
+                    raise
+            except InvalidIndexError:
+                # GH35015, using datetime as column indices raises exception
+                if not isinstance(labels, MultiIndex):
+                    raise
+            except ValueError:
+                if not is_integer(key):
+                    raise
+                return {"key": key}
+
+        if is_nested_tuple(key, labels):
+            if self.ndim == 1 and any(isinstance(k, tuple) for k in key):
+                # GH#35349 Raise if tuple in tuple for series
+                raise IndexingError("Too many indexers")
+            return labels.get_locs(key)
+
+        elif is_list_like_indexer(key):
+            if is_iterator(key):
+                key = list(key)
+
+            if com.is_bool_indexer(key):
+                key = check_bool_indexer(labels, key)
+                return key
+            else:
+                return self._get_listlike_indexer(key, axis)[1]
+        else:
+            try:
+                return labels.get_loc(key)
+            except LookupError:
+                # allow a not found key only if we are a setter
+                if not is_list_like_indexer(key):
+                    return {"key": key}
+                raise
+
+    def _get_listlike_indexer(self, key, axis: AxisInt):
+        """
+        Transform a list-like of keys into a new index and an indexer.
+
+        Parameters
+        ----------
+        key : list-like
+            Targeted labels.
+        axis:  int
+            Dimension on which the indexing is being made.
+
+        Raises
+        ------
+        KeyError
+            If at least one key was requested but none was found.
+
+        Returns
+        -------
+        keyarr: Index
+            New index (coinciding with 'key' if the axis is unique).
+        values : array-like
+            Indexer for the return object, -1 denotes keys not found.
+        """
+        ax = self.obj._get_axis(axis)
+        axis_name = self.obj._get_axis_name(axis)
+
+        keyarr, indexer = ax._get_indexer_strict(key, axis_name)
+
+        return keyarr, indexer
+
+
+@doc(IndexingMixin.iloc)
+class _iLocIndexer(_LocationIndexer):
+    _valid_types = (
+        "integer, integer slice (START point is INCLUDED, END "
+        "point is EXCLUDED), listlike of integers, boolean array"
+    )
+    _takeable = True
+
+    # -------------------------------------------------------------------
+    # Key Checks
+
+    def _validate_key(self, key, axis: AxisInt):
+        if com.is_bool_indexer(key):
+            if hasattr(key, "index") and isinstance(key.index, Index):
+                if key.index.inferred_type == "integer":
+                    raise NotImplementedError(
+                        "iLocation based boolean "
+                        "indexing on an integer type "
+                        "is not available"
+                    )
+                raise ValueError(
+                    "iLocation based boolean indexing cannot use "
+                    "an indexable as a mask"
+                )
+            return
+
+        if isinstance(key, slice):
+            return
+        elif is_integer(key):
+            self._validate_integer(key, axis)
+        elif isinstance(key, tuple):
+            # a tuple should already have been caught by this point
+            # so don't treat a tuple as a valid indexer
+            raise IndexingError("Too many indexers")
+        elif is_list_like_indexer(key):
+            if isinstance(key, ABCSeries):
+                arr = key._values
+            elif is_array_like(key):
+                arr = key
+            else:
+                arr = np.array(key)
+            len_axis = len(self.obj._get_axis(axis))
+
+            # check that the key has a numeric dtype
+            if not is_numeric_dtype(arr.dtype):
+                raise IndexError(f".iloc requires numeric indexers, got {arr}")
+
+            # check that the key does not exceed the maximum size of the index
+            if len(arr) and (arr.max() >= len_axis or arr.min() < -len_axis):
+                raise IndexError("positional indexers are out-of-bounds")
+        else:
+            raise ValueError(f"Can only index by location with a [{self._valid_types}]")
+
+    def _has_valid_setitem_indexer(self, indexer) -> bool:
+        """
+        Validate that a positional indexer cannot enlarge its target
+        will raise if needed, does not modify the indexer externally.
+
+        Returns
+        -------
+        bool
+        """
+        if isinstance(indexer, dict):
+            raise IndexError("iloc cannot enlarge its target object")
+
+        if isinstance(indexer, ABCDataFrame):
+            raise TypeError(
+                "DataFrame indexer for .iloc is not supported. "
+                "Consider using .loc with a DataFrame indexer for automatic alignment.",
+            )
+
+        if not isinstance(indexer, tuple):
+            indexer = _tuplify(self.ndim, indexer)
+
+        for ax, i in zip(self.obj.axes, indexer):
+            if isinstance(i, slice):
+                # should check the stop slice?
+                pass
+            elif is_list_like_indexer(i):
+                # should check the elements?
+                pass
+            elif is_integer(i):
+                if i >= len(ax):
+                    raise IndexError("iloc cannot enlarge its target object")
+            elif isinstance(i, dict):
+                raise IndexError("iloc cannot enlarge its target object")
+
+        return True
+
+    def _is_scalar_access(self, key: tuple) -> bool:
+        """
+        Returns
+        -------
+        bool
+        """
+        # this is a shortcut accessor to both .loc and .iloc
+        # that provide the equivalent access of .at and .iat
+        # a) avoid getting things via sections and (to minimize dtype changes)
+        # b) provide a performant path
+        if len(key) != self.ndim:
+            return False
+
+        return all(is_integer(k) for k in key)
+
+    def _validate_integer(self, key: int | np.integer, axis: AxisInt) -> None:
+        """
+        Check that 'key' is a valid position in the desired axis.
+
+        Parameters
+        ----------
+        key : int
+            Requested position.
+        axis : int
+            Desired axis.
+
+        Raises
+        ------
+        IndexError
+            If 'key' is not a valid position in axis 'axis'.
+        """
+        len_axis = len(self.obj._get_axis(axis))
+        if key >= len_axis or key < -len_axis:
+            raise IndexError("single positional indexer is out-of-bounds")
+
+    # -------------------------------------------------------------------
+
+    def _getitem_tuple(self, tup: tuple):
+        tup = self._validate_tuple_indexer(tup)
+        with suppress(IndexingError):
+            return self._getitem_lowerdim(tup)
+
+        return self._getitem_tuple_same_dim(tup)
+
+    def _get_list_axis(self, key, axis: AxisInt):
+        """
+        Return Series values by list or array of integers.
+
+        Parameters
+        ----------
+        key : list-like positional indexer
+        axis : int
+
+        Returns
+        -------
+        Series object
+
+        Notes
+        -----
+        `axis` can only be zero.
+        """
+        try:
+            return self.obj._take_with_is_copy(key, axis=axis)
+        except IndexError as err:
+            # re-raise with different error message, e.g. test_getitem_ndarray_3d
+            raise IndexError("positional indexers are out-of-bounds") from err
+
+    def _getitem_axis(self, key, axis: AxisInt):
+        if key is Ellipsis:
+            key = slice(None)
+        elif isinstance(key, ABCDataFrame):
+            raise IndexError(
+                "DataFrame indexer is not allowed for .iloc\n"
+                "Consider using .loc for automatic alignment."
+            )
+
+        if isinstance(key, slice):
+            return self._get_slice_axis(key, axis=axis)
+
+        if is_iterator(key):
+            key = list(key)
+
+        if isinstance(key, list):
+            key = np.asarray(key)
+
+        if com.is_bool_indexer(key):
+            self._validate_key(key, axis)
+            return self._getbool_axis(key, axis=axis)
+
+        # a list of integers
+        elif is_list_like_indexer(key):
+            return self._get_list_axis(key, axis=axis)
+
+        # a single integer
+        else:
+            key = item_from_zerodim(key)
+            if not is_integer(key):
+                raise TypeError("Cannot index by location index with a non-integer key")
+
+            # validate the location
+            self._validate_integer(key, axis)
+
+            return self.obj._ixs(key, axis=axis)
+
+    def _get_slice_axis(self, slice_obj: slice, axis: AxisInt):
+        # caller is responsible for ensuring non-None axis
+        obj = self.obj
+
+        if not need_slice(slice_obj):
+            return obj.copy(deep=False)
+
+        labels = obj._get_axis(axis)
+        labels._validate_positional_slice(slice_obj)
+        return self.obj._slice(slice_obj, axis=axis)
+
+    def _convert_to_indexer(self, key, axis: AxisInt):
+        """
+        Much simpler as we only have to deal with our valid types.
+        """
+        return key
+
+    def _get_setitem_indexer(self, key):
+        # GH#32257 Fall through to let numpy do validation
+        if is_iterator(key):
+            key = list(key)
+
+        if self.axis is not None:
+            key = _tupleize_axis_indexer(self.ndim, self.axis, key)
+
+        return key
+
+    # -------------------------------------------------------------------
+
+    def _setitem_with_indexer(self, indexer, value, name: str = "iloc"):
+        """
+        _setitem_with_indexer is for setting values on a Series/DataFrame
+        using positional indexers.
+
+        If the relevant keys are not present, the Series/DataFrame may be
+        expanded.
+
+        This method is currently broken when dealing with non-unique Indexes,
+        since it goes from positional indexers back to labels when calling
+        BlockManager methods, see GH#12991, GH#22046, GH#15686.
+        """
+        info_axis = self.obj._info_axis_number
+
+        # maybe partial set
+        take_split_path = not self.obj._mgr.is_single_block
+
+        if not take_split_path and isinstance(value, ABCDataFrame):
+            # Avoid cast of values
+            take_split_path = not value._mgr.is_single_block
+
+        # if there is only one block/type, still have to take split path
+        # unless the block is one-dimensional or it can hold the value
+        if not take_split_path and len(self.obj._mgr.arrays) and self.ndim > 1:
+            # in case of dict, keys are indices
+            val = list(value.values()) if isinstance(value, dict) else value
+            arr = self.obj._mgr.arrays[0]
+            take_split_path = not can_hold_element(
+                arr, extract_array(val, extract_numpy=True)
+            )
+
+        # if we have any multi-indexes that have non-trivial slices
+        # (not null slices) then we must take the split path, xref
+        # GH 10360, GH 27841
+        if isinstance(indexer, tuple) and len(indexer) == len(self.obj.axes):
+            for i, ax in zip(indexer, self.obj.axes):
+                if isinstance(ax, MultiIndex) and not (
+                    is_integer(i) or com.is_null_slice(i)
+                ):
+                    take_split_path = True
+                    break
+
+        if isinstance(indexer, tuple):
+            nindexer = []
+            for i, idx in enumerate(indexer):
+                if isinstance(idx, dict):
+                    # reindex the axis to the new value
+                    # and set inplace
+                    key, _ = convert_missing_indexer(idx)
+
+                    # if this is the items axes, then take the main missing
+                    # path first
+                    # this correctly sets the dtype and avoids cache issues
+                    # essentially this separates out the block that is needed
+                    # to possibly be modified
+                    if self.ndim > 1 and i == info_axis:
+                        # add the new item, and set the value
+                        # must have all defined axes if we have a scalar
+                        # or a list-like on the non-info axes if we have a
+                        # list-like
+                        if not len(self.obj):
+                            if not is_list_like_indexer(value):
+                                raise ValueError(
+                                    "cannot set a frame with no "
+                                    "defined index and a scalar"
+                                )
+                            self.obj[key] = value
+                            return
+
+                        # add a new item with the dtype setup
+                        if com.is_null_slice(indexer[0]):
+                            # We are setting an entire column
+                            self.obj[key] = value
+                            return
+                        elif is_array_like(value):
+                            # GH#42099
+                            arr = extract_array(value, extract_numpy=True)
+                            taker = -1 * np.ones(len(self.obj), dtype=np.intp)
+                            empty_value = algos.take_nd(arr, taker)
+                            if not isinstance(value, ABCSeries):
+                                # if not Series (in which case we need to align),
+                                #  we can short-circuit
+                                if (
+                                    isinstance(arr, np.ndarray)
+                                    and arr.ndim == 1
+                                    and len(arr) == 1
+                                ):
+                                    # NumPy 1.25 deprecation: https://github.com/numpy/numpy/pull/10615
+                                    arr = arr[0, ...]
+                                empty_value[indexer[0]] = arr
+                                self.obj[key] = empty_value
+                                return
+
+                            self.obj[key] = empty_value
+                        elif not is_list_like(value):
+                            self.obj[key] = construct_1d_array_from_inferred_fill_value(
+                                value, len(self.obj)
+                            )
+                        else:
+                            # FIXME: GH#42099#issuecomment-864326014
+                            self.obj[key] = infer_fill_value(value)
+
+                        new_indexer = convert_from_missing_indexer_tuple(
+                            indexer, self.obj.axes
+                        )
+                        self._setitem_with_indexer(new_indexer, value, name)
+
+                        return
+
+                    # reindex the axis
+                    # make sure to clear the cache because we are
+                    # just replacing the block manager here
+                    # so the object is the same
+                    index = self.obj._get_axis(i)
+                    with warnings.catch_warnings():
+                        # TODO: re-issue this with setitem-specific message?
+                        warnings.filterwarnings(
+                            "ignore",
+                            "The behavior of Index.insert with object-dtype "
+                            "is deprecated",
+                            category=FutureWarning,
+                        )
+                        labels = index.insert(len(index), key)
+
+                    # We are expanding the Series/DataFrame values to match
+                    #  the length of thenew index `labels`.  GH#40096 ensure
+                    #  this is valid even if the index has duplicates.
+                    taker = np.arange(len(index) + 1, dtype=np.intp)
+                    taker[-1] = -1
+                    reindexers = {i: (labels, taker)}
+                    new_obj = self.obj._reindex_with_indexers(
+                        reindexers, allow_dups=True
+                    )
+                    self.obj._mgr = new_obj._mgr
+                    self.obj._maybe_update_cacher(clear=True)
+                    self.obj._is_copy = None
+
+                    nindexer.append(labels.get_loc(key))
+
+                else:
+                    nindexer.append(idx)
+
+            indexer = tuple(nindexer)
+        else:
+            indexer, missing = convert_missing_indexer(indexer)
+
+            if missing:
+                self._setitem_with_indexer_missing(indexer, value)
+                return
+
+        if name == "loc":
+            # must come after setting of missing
+            indexer, value = self._maybe_mask_setitem_value(indexer, value)
+
+        # align and set the values
+        if take_split_path:
+            # We have to operate column-wise
+            self._setitem_with_indexer_split_path(indexer, value, name)
+        else:
+            self._setitem_single_block(indexer, value, name)
+
+    def _setitem_with_indexer_split_path(self, indexer, value, name: str):
+        """
+        Setitem column-wise.
+        """
+        # Above we only set take_split_path to True for 2D cases
+        assert self.ndim == 2
+
+        if not isinstance(indexer, tuple):
+            indexer = _tuplify(self.ndim, indexer)
+        if len(indexer) > self.ndim:
+            raise IndexError("too many indices for array")
+        if isinstance(indexer[0], np.ndarray) and indexer[0].ndim > 2:
+            raise ValueError(r"Cannot set values with ndim > 2")
+
+        if (isinstance(value, ABCSeries) and name != "iloc") or isinstance(value, dict):
+            from pandas import Series
+
+            value = self._align_series(indexer, Series(value))
+
+        # Ensure we have something we can iterate over
+        info_axis = indexer[1]
+        ilocs = self._ensure_iterable_column_indexer(info_axis)
+
+        pi = indexer[0]
+        lplane_indexer = length_of_indexer(pi, self.obj.index)
+        # lplane_indexer gives the expected length of obj[indexer[0]]
+
+        # we need an iterable, with a ndim of at least 1
+        # eg. don't pass through np.array(0)
+        if is_list_like_indexer(value) and getattr(value, "ndim", 1) > 0:
+            if isinstance(value, ABCDataFrame):
+                self._setitem_with_indexer_frame_value(indexer, value, name)
+
+            elif np.ndim(value) == 2:
+                # TODO: avoid np.ndim call in case it isn't an ndarray, since
+                #  that will construct an ndarray, which will be wasteful
+                self._setitem_with_indexer_2d_value(indexer, value)
+
+            elif len(ilocs) == 1 and lplane_indexer == len(value) and not is_scalar(pi):
+                # We are setting multiple rows in a single column.
+                self._setitem_single_column(ilocs[0], value, pi)
+
+            elif len(ilocs) == 1 and 0 != lplane_indexer != len(value):
+                # We are trying to set N values into M entries of a single
+                #  column, which is invalid for N != M
+                # Exclude zero-len for e.g. boolean masking that is all-false
+
+                if len(value) == 1 and not is_integer(info_axis):
+                    # This is a case like df.iloc[:3, [1]] = [0]
+                    #  where we treat as df.iloc[:3, 1] = 0
+                    return self._setitem_with_indexer((pi, info_axis[0]), value[0])
+
+                raise ValueError(
+                    "Must have equal len keys and value "
+                    "when setting with an iterable"
+                )
+
+            elif lplane_indexer == 0 and len(value) == len(self.obj.index):
+                # We get here in one case via .loc with a all-False mask
+                pass
+
+            elif self._is_scalar_access(indexer) and is_object_dtype(
+                self.obj.dtypes._values[ilocs[0]]
+            ):
+                # We are setting nested data, only possible for object dtype data
+                self._setitem_single_column(indexer[1], value, pi)
+
+            elif len(ilocs) == len(value):
+                # We are setting multiple columns in a single row.
+                for loc, v in zip(ilocs, value):
+                    self._setitem_single_column(loc, v, pi)
+
+            elif len(ilocs) == 1 and com.is_null_slice(pi) and len(self.obj) == 0:
+                # This is a setitem-with-expansion, see
+                #  test_loc_setitem_empty_append_expands_rows_mixed_dtype
+                # e.g. df = DataFrame(columns=["x", "y"])
+                #  df["x"] = df["x"].astype(np.int64)
+                #  df.loc[:, "x"] = [1, 2, 3]
+                self._setitem_single_column(ilocs[0], value, pi)
+
+            else:
+                raise ValueError(
+                    "Must have equal len keys and value "
+                    "when setting with an iterable"
+                )
+
+        else:
+            # scalar value
+            for loc in ilocs:
+                self._setitem_single_column(loc, value, pi)
+
+    def _setitem_with_indexer_2d_value(self, indexer, value):
+        # We get here with np.ndim(value) == 2, excluding DataFrame,
+        #  which goes through _setitem_with_indexer_frame_value
+        pi = indexer[0]
+
+        ilocs = self._ensure_iterable_column_indexer(indexer[1])
+
+        if not is_array_like(value):
+            # cast lists to array
+            value = np.array(value, dtype=object)
+        if len(ilocs) != value.shape[1]:
+            raise ValueError(
+                "Must have equal len keys and value when setting with an ndarray"
+            )
+
+        for i, loc in enumerate(ilocs):
+            value_col = value[:, i]
+            if is_object_dtype(value_col.dtype):
+                # casting to list so that we do type inference in setitem_single_column
+                value_col = value_col.tolist()
+            self._setitem_single_column(loc, value_col, pi)
+
+    def _setitem_with_indexer_frame_value(self, indexer, value: DataFrame, name: str):
+        ilocs = self._ensure_iterable_column_indexer(indexer[1])
+
+        sub_indexer = list(indexer)
+        pi = indexer[0]
+
+        multiindex_indexer = isinstance(self.obj.columns, MultiIndex)
+
+        unique_cols = value.columns.is_unique
+
+        # We do not want to align the value in case of iloc GH#37728
+        if name == "iloc":
+            for i, loc in enumerate(ilocs):
+                val = value.iloc[:, i]
+                self._setitem_single_column(loc, val, pi)
+
+        elif not unique_cols and value.columns.equals(self.obj.columns):
+            # We assume we are already aligned, see
+            # test_iloc_setitem_frame_duplicate_columns_multiple_blocks
+            for loc in ilocs:
+                item = self.obj.columns[loc]
+                if item in value:
+                    sub_indexer[1] = item
+                    val = self._align_series(
+                        tuple(sub_indexer),
+                        value.iloc[:, loc],
+                        multiindex_indexer,
+                    )
+                else:
+                    val = np.nan
+
+                self._setitem_single_column(loc, val, pi)
+
+        elif not unique_cols:
+            raise ValueError("Setting with non-unique columns is not allowed.")
+
+        else:
+            for loc in ilocs:
+                item = self.obj.columns[loc]
+                if item in value:
+                    sub_indexer[1] = item
+                    val = self._align_series(
+                        tuple(sub_indexer),
+                        value[item],
+                        multiindex_indexer,
+                        using_cow=using_copy_on_write(),
+                    )
+                else:
+                    val = np.nan
+
+                self._setitem_single_column(loc, val, pi)
+
+    def _setitem_single_column(self, loc: int, value, plane_indexer) -> None:
+        """
+
+        Parameters
+        ----------
+        loc : int
+            Indexer for column position
+        plane_indexer : int, slice, listlike[int]
+            The indexer we use for setitem along axis=0.
+        """
+        pi = plane_indexer
+
+        is_full_setter = com.is_null_slice(pi) or com.is_full_slice(pi, len(self.obj))
+
+        is_null_setter = com.is_empty_slice(pi) or is_array_like(pi) and len(pi) == 0
+
+        if is_null_setter:
+            # no-op, don't cast dtype later
+            return
+
+        elif is_full_setter:
+            try:
+                self.obj._mgr.column_setitem(
+                    loc, plane_indexer, value, inplace_only=True
+                )
+            except (ValueError, TypeError, LossySetitemError):
+                # If we're setting an entire column and we can't do it inplace,
+                #  then we can use value's dtype (or inferred dtype)
+                #  instead of object
+                dtype = self.obj.dtypes.iloc[loc]
+                if dtype not in (np.void, object) and not self.obj.empty:
+                    # - Exclude np.void, as that is a special case for expansion.
+                    #   We want to warn for
+                    #       df = pd.DataFrame({'a': [1, 2]})
+                    #       df.loc[:, 'a'] = .3
+                    #   but not for
+                    #       df = pd.DataFrame({'a': [1, 2]})
+                    #       df.loc[:, 'b'] = .3
+                    # - Exclude `object`, as then no upcasting happens.
+                    # - Exclude empty initial object with enlargement,
+                    #   as then there's nothing to be inconsistent with.
+                    warnings.warn(
+                        f"Setting an item of incompatible dtype is deprecated "
+                        "and will raise in a future error of pandas. "
+                        f"Value '{value}' has dtype incompatible with {dtype}, "
+                        "please explicitly cast to a compatible dtype first.",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                self.obj.isetitem(loc, value)
+        else:
+            # set value into the column (first attempting to operate inplace, then
+            #  falling back to casting if necessary)
+            dtype = self.obj.dtypes.iloc[loc]
+            if dtype == np.void:
+                # This means we're expanding, with multiple columns, e.g.
+                #     df = pd.DataFrame({'A': [1,2,3], 'B': [4,5,6]})
+                #     df.loc[df.index <= 2, ['F', 'G']] = (1, 'abc')
+                # Columns F and G will initially be set to np.void.
+                # Here, we replace those temporary `np.void` columns with
+                # columns of the appropriate dtype, based on `value`.
+                self.obj.iloc[:, loc] = construct_1d_array_from_inferred_fill_value(
+                    value, len(self.obj)
+                )
+            self.obj._mgr.column_setitem(loc, plane_indexer, value)
+
+        self.obj._clear_item_cache()
+
+    def _setitem_single_block(self, indexer, value, name: str) -> None:
+        """
+        _setitem_with_indexer for the case when we have a single Block.
+        """
+        from pandas import Series
+
+        if (isinstance(value, ABCSeries) and name != "iloc") or isinstance(value, dict):
+            # TODO(EA): ExtensionBlock.setitem this causes issues with
+            # setting for extensionarrays that store dicts. Need to decide
+            # if it's worth supporting that.
+            value = self._align_series(indexer, Series(value))
+
+        info_axis = self.obj._info_axis_number
+        item_labels = self.obj._get_axis(info_axis)
+        if isinstance(indexer, tuple):
+            # if we are setting on the info axis ONLY
+            # set using those methods to avoid block-splitting
+            # logic here
+            if (
+                self.ndim == len(indexer) == 2
+                and is_integer(indexer[1])
+                and com.is_null_slice(indexer[0])
+            ):
+                col = item_labels[indexer[info_axis]]
+                if len(item_labels.get_indexer_for([col])) == 1:
+                    # e.g. test_loc_setitem_empty_append_expands_rows
+                    loc = item_labels.get_loc(col)
+                    self._setitem_single_column(loc, value, indexer[0])
+                    return
+
+            indexer = maybe_convert_ix(*indexer)  # e.g. test_setitem_frame_align
+
+        if isinstance(value, ABCDataFrame) and name != "iloc":
+            value = self._align_frame(indexer, value)._values
+
+        # check for chained assignment
+        self.obj._check_is_chained_assignment_possible()
+
+        # actually do the set
+        self.obj._mgr = self.obj._mgr.setitem(indexer=indexer, value=value)
+        self.obj._maybe_update_cacher(clear=True, inplace=True)
+
+    def _setitem_with_indexer_missing(self, indexer, value):
+        """
+        Insert new row(s) or column(s) into the Series or DataFrame.
+        """
+        from pandas import Series
+
+        # reindex the axis to the new value
+        # and set inplace
+        if self.ndim == 1:
+            index = self.obj.index
+            with warnings.catch_warnings():
+                # TODO: re-issue this with setitem-specific message?
+                warnings.filterwarnings(
+                    "ignore",
+                    "The behavior of Index.insert with object-dtype is deprecated",
+                    category=FutureWarning,
+                )
+                new_index = index.insert(len(index), indexer)
+
+            # we have a coerced indexer, e.g. a float
+            # that matches in an int64 Index, so
+            # we will not create a duplicate index, rather
+            # index to that element
+            # e.g. 0.0 -> 0
+            # GH#12246
+            if index.is_unique:
+                # pass new_index[-1:] instead if [new_index[-1]]
+                #  so that we retain dtype
+                new_indexer = index.get_indexer(new_index[-1:])
+                if (new_indexer != -1).any():
+                    # We get only here with loc, so can hard code
+                    return self._setitem_with_indexer(new_indexer, value, "loc")
+
+            # this preserves dtype of the value and of the object
+            if not is_scalar(value):
+                new_dtype = None
+
+            elif is_valid_na_for_dtype(value, self.obj.dtype):
+                if not is_object_dtype(self.obj.dtype):
+                    # Every NA value is suitable for object, no conversion needed
+                    value = na_value_for_dtype(self.obj.dtype, compat=False)
+
+                new_dtype = maybe_promote(self.obj.dtype, value)[0]
+
+            elif isna(value):
+                new_dtype = None
+            elif not self.obj.empty and not is_object_dtype(self.obj.dtype):
+                # We should not cast, if we have object dtype because we can
+                # set timedeltas into object series
+                curr_dtype = self.obj.dtype
+                curr_dtype = getattr(curr_dtype, "numpy_dtype", curr_dtype)
+                new_dtype = maybe_promote(curr_dtype, value)[0]
+            else:
+                new_dtype = None
+
+            new_values = Series([value], dtype=new_dtype)._values
+
+            if len(self.obj._values):
+                # GH#22717 handle casting compatibility that np.concatenate
+                #  does incorrectly
+                new_values = concat_compat([self.obj._values, new_values])
+            self.obj._mgr = self.obj._constructor(
+                new_values, index=new_index, name=self.obj.name
+            )._mgr
+            self.obj._maybe_update_cacher(clear=True)
+
+        elif self.ndim == 2:
+            if not len(self.obj.columns):
+                # no columns and scalar
+                raise ValueError("cannot set a frame with no defined columns")
+
+            has_dtype = hasattr(value, "dtype")
+            if isinstance(value, ABCSeries):
+                # append a Series
+                value = value.reindex(index=self.obj.columns, copy=True)
+                value.name = indexer
+            elif isinstance(value, dict):
+                value = Series(
+                    value, index=self.obj.columns, name=indexer, dtype=object
+                )
+            else:
+                # a list-list
+                if is_list_like_indexer(value):
+                    # must have conforming columns
+                    if len(value) != len(self.obj.columns):
+                        raise ValueError("cannot set a row with mismatched columns")
+
+                value = Series(value, index=self.obj.columns, name=indexer)
+
+            if not len(self.obj):
+                # We will ignore the existing dtypes instead of using
+                #  internals.concat logic
+                df = value.to_frame().T
+
+                idx = self.obj.index
+                if isinstance(idx, MultiIndex):
+                    name = idx.names
+                else:
+                    name = idx.name
+
+                df.index = Index([indexer], name=name)
+                if not has_dtype:
+                    # i.e. if we already had a Series or ndarray, keep that
+                    #  dtype.  But if we had a list or dict, then do inference
+                    df = df.infer_objects(copy=False)
+                self.obj._mgr = df._mgr
+            else:
+                self.obj._mgr = self.obj._append(value)._mgr
+            self.obj._maybe_update_cacher(clear=True)
+
+    def _ensure_iterable_column_indexer(self, column_indexer):
+        """
+        Ensure that our column indexer is something that can be iterated over.
+        """
+        ilocs: Sequence[int | np.integer] | np.ndarray
+        if is_integer(column_indexer):
+            ilocs = [column_indexer]
+        elif isinstance(column_indexer, slice):
+            ilocs = np.arange(len(self.obj.columns))[column_indexer]
+        elif (
+            isinstance(column_indexer, np.ndarray) and column_indexer.dtype.kind == "b"
+        ):
+            ilocs = np.arange(len(column_indexer))[column_indexer]
+        else:
+            ilocs = column_indexer
+        return ilocs
+
+    def _align_series(
+        self,
+        indexer,
+        ser: Series,
+        multiindex_indexer: bool = False,
+        using_cow: bool = False,
+    ):
+        """
+        Parameters
+        ----------
+        indexer : tuple, slice, scalar
+            Indexer used to get the locations that will be set to `ser`.
+        ser : pd.Series
+            Values to assign to the locations specified by `indexer`.
+        multiindex_indexer : bool, optional
+            Defaults to False. Should be set to True if `indexer` was from
+            a `pd.MultiIndex`, to avoid unnecessary broadcasting.
+
+        Returns
+        -------
+        `np.array` of `ser` broadcast to the appropriate shape for assignment
+        to the locations selected by `indexer`
+        """
+        if isinstance(indexer, (slice, np.ndarray, list, Index)):
+            indexer = (indexer,)
+
+        if isinstance(indexer, tuple):
+            # flatten np.ndarray indexers
+            def ravel(i):
+                return i.ravel() if isinstance(i, np.ndarray) else i
+
+            indexer = tuple(map(ravel, indexer))
+
+            aligners = [not com.is_null_slice(idx) for idx in indexer]
+            sum_aligners = sum(aligners)
+            single_aligner = sum_aligners == 1
+            is_frame = self.ndim == 2
+            obj = self.obj
+
+            # are we a single alignable value on a non-primary
+            # dim (e.g. panel: 1,2, or frame: 0) ?
+            # hence need to align to a single axis dimension
+            # rather that find all valid dims
+
+            # frame
+            if is_frame:
+                single_aligner = single_aligner and aligners[0]
+
+            # we have a frame, with multiple indexers on both axes; and a
+            # series, so need to broadcast (see GH5206)
+            if sum_aligners == self.ndim and all(is_sequence(_) for _ in indexer):
+                ser_values = ser.reindex(obj.axes[0][indexer[0]], copy=True)._values
+
+                # single indexer
+                if len(indexer) > 1 and not multiindex_indexer:
+                    len_indexer = len(indexer[1])
+                    ser_values = (
+                        np.tile(ser_values, len_indexer).reshape(len_indexer, -1).T
+                    )
+
+                return ser_values
+
+            for i, idx in enumerate(indexer):
+                ax = obj.axes[i]
+
+                # multiple aligners (or null slices)
+                if is_sequence(idx) or isinstance(idx, slice):
+                    if single_aligner and com.is_null_slice(idx):
+                        continue
+                    new_ix = ax[idx]
+                    if not is_list_like_indexer(new_ix):
+                        new_ix = Index([new_ix])
+                    else:
+                        new_ix = Index(new_ix)
+                    if ser.index.equals(new_ix):
+                        if using_cow:
+                            return ser
+                        return ser._values.copy()
+
+                    return ser.reindex(new_ix)._values
+
+                # 2 dims
+                elif single_aligner:
+                    # reindex along index
+                    ax = self.obj.axes[1]
+                    if ser.index.equals(ax) or not len(ax):
+                        return ser._values.copy()
+                    return ser.reindex(ax)._values
+
+        elif is_integer(indexer) and self.ndim == 1:
+            if is_object_dtype(self.obj.dtype):
+                return ser
+            ax = self.obj._get_axis(0)
+
+            if ser.index.equals(ax):
+                return ser._values.copy()
+
+            return ser.reindex(ax)._values[indexer]
+
+        elif is_integer(indexer):
+            ax = self.obj._get_axis(1)
+
+            if ser.index.equals(ax):
+                return ser._values.copy()
+
+            return ser.reindex(ax)._values
+
+        raise ValueError("Incompatible indexer with Series")
+
+    def _align_frame(self, indexer, df: DataFrame) -> DataFrame:
+        is_frame = self.ndim == 2
+
+        if isinstance(indexer, tuple):
+            idx, cols = None, None
+            sindexers = []
+            for i, ix in enumerate(indexer):
+                ax = self.obj.axes[i]
+                if is_sequence(ix) or isinstance(ix, slice):
+                    if isinstance(ix, np.ndarray):
+                        ix = ix.ravel()
+                    if idx is None:
+                        idx = ax[ix]
+                    elif cols is None:
+                        cols = ax[ix]
+                    else:
+                        break
+                else:
+                    sindexers.append(i)
+
+            if idx is not None and cols is not None:
+                if df.index.equals(idx) and df.columns.equals(cols):
+                    val = df.copy()
+                else:
+                    val = df.reindex(idx, columns=cols)
+                return val
+
+        elif (isinstance(indexer, slice) or is_list_like_indexer(indexer)) and is_frame:
+            ax = self.obj.index[indexer]
+            if df.index.equals(ax):
+                val = df.copy()
+            else:
+                # we have a multi-index and are trying to align
+                # with a particular, level GH3738
+                if (
+                    isinstance(ax, MultiIndex)
+                    and isinstance(df.index, MultiIndex)
+                    and ax.nlevels != df.index.nlevels
+                ):
+                    raise TypeError(
+                        "cannot align on a multi-index with out "
+                        "specifying the join levels"
+                    )
+
+                val = df.reindex(index=ax)
+            return val
+
+        raise ValueError("Incompatible indexer with DataFrame")
+
+
+class _ScalarAccessIndexer(NDFrameIndexerBase):
+    """
+    Access scalars quickly.
+    """
+
+    # sub-classes need to set _takeable
+    _takeable: bool
+
+    def _convert_key(self, key):
+        raise AbstractMethodError(self)
+
+    def __getitem__(self, key):
+        if not isinstance(key, tuple):
+            # we could have a convertible item here (e.g. Timestamp)
+            if not is_list_like_indexer(key):
+                key = (key,)
+            else:
+                raise ValueError("Invalid call for scalar access (getting)!")
+
+        key = self._convert_key(key)
+        return self.obj._get_value(*key, takeable=self._takeable)
+
+    def __setitem__(self, key, value) -> None:
+        if isinstance(key, tuple):
+            key = tuple(com.apply_if_callable(x, self.obj) for x in key)
+        else:
+            # scalar callable may return tuple
+            key = com.apply_if_callable(key, self.obj)
+
+        if not isinstance(key, tuple):
+            key = _tuplify(self.ndim, key)
+        key = list(self._convert_key(key))
+        if len(key) != self.ndim:
+            raise ValueError("Not enough indexers for scalar access (setting)!")
+
+        self.obj._set_value(*key, value=value, takeable=self._takeable)
+
+
+@doc(IndexingMixin.at)
+class _AtIndexer(_ScalarAccessIndexer):
+    _takeable = False
+
+    def _convert_key(self, key):
+        """
+        Require they keys to be the same type as the index. (so we don't
+        fallback)
+        """
+        # GH 26989
+        # For series, unpacking key needs to result in the label.
+        # This is already the case for len(key) == 1; e.g. (1,)
+        if self.ndim == 1 and len(key) > 1:
+            key = (key,)
+
+        return key
+
+    @property
+    def _axes_are_unique(self) -> bool:
+        # Only relevant for self.ndim == 2
+        assert self.ndim == 2
+        return self.obj.index.is_unique and self.obj.columns.is_unique
+
+    def __getitem__(self, key):
+        if self.ndim == 2 and not self._axes_are_unique:
+            # GH#33041 fall back to .loc
+            if not isinstance(key, tuple) or not all(is_scalar(x) for x in key):
+                raise ValueError("Invalid call for scalar access (getting)!")
+            return self.obj.loc[key]
+
+        return super().__getitem__(key)
+
+    def __setitem__(self, key, value) -> None:
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self.obj) <= 2:
+                warnings.warn(
+                    _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
+                )
+        elif not PYPY and not WARNING_CHECK_DISABLED and not using_copy_on_write():
+            ctr = sys.getrefcount(self.obj)
+            ref_count = 2
+            if not warn_copy_on_write() and _check_cacher(self.obj):
+                # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                ref_count += 1
+            if ctr <= ref_count:
+                warnings.warn(
+                    _chained_assignment_warning_msg, FutureWarning, stacklevel=2
+                )
+
+        if self.ndim == 2 and not self._axes_are_unique:
+            # GH#33041 fall back to .loc
+            if not isinstance(key, tuple) or not all(is_scalar(x) for x in key):
+                raise ValueError("Invalid call for scalar access (setting)!")
+
+            self.obj.loc[key] = value
+            return
+
+        return super().__setitem__(key, value)
+
+
+@doc(IndexingMixin.iat)
+class _iAtIndexer(_ScalarAccessIndexer):
+    _takeable = True
+
+    def _convert_key(self, key):
+        """
+        Require integer args. (and convert to label arguments)
+        """
+        for i in key:
+            if not is_integer(i):
+                raise ValueError("iAt based indexing can only have integer indexers")
+        return key
+
+    def __setitem__(self, key, value) -> None:
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self.obj) <= 2:
+                warnings.warn(
+                    _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
+                )
+        elif not PYPY and not WARNING_CHECK_DISABLED and not using_copy_on_write():
+            ctr = sys.getrefcount(self.obj)
+            ref_count = 2
+            if not warn_copy_on_write() and _check_cacher(self.obj):
+                # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                ref_count += 1
+            if ctr <= ref_count:
+                warnings.warn(
+                    _chained_assignment_warning_msg, FutureWarning, stacklevel=2
+                )
+
+        return super().__setitem__(key, value)
+
+
+def _tuplify(ndim: int, loc: Hashable) -> tuple[Hashable | slice, ...]:
+    """
+    Given an indexer for the first dimension, create an equivalent tuple
+    for indexing over all dimensions.
+
+    Parameters
+    ----------
+    ndim : int
+    loc : object
+
+    Returns
+    -------
+    tuple
+    """
+    _tup: list[Hashable | slice]
+    _tup = [slice(None, None) for _ in range(ndim)]
+    _tup[0] = loc
+    return tuple(_tup)
+
+
+def _tupleize_axis_indexer(ndim: int, axis: AxisInt, key) -> tuple:
+    """
+    If we have an axis, adapt the given key to be axis-independent.
+    """
+    new_key = [slice(None)] * ndim
+    new_key[axis] = key
+    return tuple(new_key)
+
+
+def check_bool_indexer(index: Index, key) -> np.ndarray:
+    """
+    Check if key is a valid boolean indexer for an object with such index and
+    perform reindexing or conversion if needed.
+
+    This function assumes that is_bool_indexer(key) == True.
+
+    Parameters
+    ----------
+    index : Index
+        Index of the object on which the indexing is done.
+    key : list-like
+        Boolean indexer to check.
+
+    Returns
+    -------
+    np.array
+        Resulting key.
+
+    Raises
+    ------
+    IndexError
+        If the key does not have the same length as index.
+    IndexingError
+        If the index of the key is unalignable to index.
+    """
+    result = key
+    if isinstance(key, ABCSeries) and not key.index.equals(index):
+        indexer = result.index.get_indexer_for(index)
+        if -1 in indexer:
+            raise IndexingError(
+                "Unalignable boolean Series provided as "
+                "indexer (index of the boolean Series and of "
+                "the indexed object do not match)."
+            )
+
+        result = result.take(indexer)
+
+        # fall through for boolean
+        if not isinstance(result.dtype, ExtensionDtype):
+            return result.astype(bool)._values
+
+    if is_object_dtype(key):
+        # key might be object-dtype bool, check_array_indexer needs bool array
+        result = np.asarray(result, dtype=bool)
+    elif not is_array_like(result):
+        # GH 33924
+        # key may contain nan elements, check_array_indexer needs bool array
+        result = pd_array(result, dtype=bool)
+    return check_array_indexer(index, result)
+
+
+def convert_missing_indexer(indexer):
+    """
+    Reverse convert a missing indexer, which is a dict
+    return the scalar indexer and a boolean indicating if we converted
+    """
+    if isinstance(indexer, dict):
+        # a missing key (but not a tuple indexer)
+        indexer = indexer["key"]
+
+        if isinstance(indexer, bool):
+            raise KeyError("cannot use a single bool to index into setitem")
+        return indexer, True
+
+    return indexer, False
+
+
+def convert_from_missing_indexer_tuple(indexer, axes):
+    """
+    Create a filtered indexer that doesn't have any missing indexers.
+    """
+
+    def get_indexer(_i, _idx):
+        return axes[_i].get_loc(_idx["key"]) if isinstance(_idx, dict) else _idx
+
+    return tuple(get_indexer(_i, _idx) for _i, _idx in enumerate(indexer))
+
+
+def maybe_convert_ix(*args):
+    """
+    We likely want to take the cross-product.
+    """
+    for arg in args:
+        if not isinstance(arg, (np.ndarray, list, ABCSeries, Index)):
+            return args
+    return np.ix_(*args)
+
+
+def is_nested_tuple(tup, labels) -> bool:
+    """
+    Returns
+    -------
+    bool
+    """
+    # check for a compatible nested tuple and multiindexes among the axes
+    if not isinstance(tup, tuple):
+        return False
+
+    for k in tup:
+        if is_list_like(k) or isinstance(k, slice):
+            return isinstance(labels, MultiIndex)
+
+    return False
+
+
+def is_label_like(key) -> bool:
+    """
+    Returns
+    -------
+    bool
+    """
+    # select a label or row
+    return (
+        not isinstance(key, slice)
+        and not is_list_like_indexer(key)
+        and key is not Ellipsis
+    )
+
+
+def need_slice(obj: slice) -> bool:
+    """
+    Returns
+    -------
+    bool
+    """
+    return (
+        obj.start is not None
+        or obj.stop is not None
+        or (obj.step is not None and obj.step != 1)
+    )
+
+
+def check_dict_or_set_indexers(key) -> None:
+    """
+    Check if the indexer is or contains a dict or set, which is no longer allowed.
+    """
+    if (
+        isinstance(key, set)
+        or isinstance(key, tuple)
+        and any(isinstance(x, set) for x in key)
+    ):
+        raise TypeError(
+            "Passing a set as an indexer is not supported. Use a list instead."
+        )
+
+    if (
+        isinstance(key, dict)
+        or isinstance(key, tuple)
+        and any(isinstance(x, dict) for x in key)
+    ):
+        raise TypeError(
+            "Passing a dict as an indexer is not supported. Use a list instead."
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/buffer.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/buffer.py
new file mode 100644
index 0000000000000000000000000000000000000000..5d24325e67f62a5da0fa3863d81576dd61f86869
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/buffer.py
@@ -0,0 +1,136 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from pandas.core.interchange.dataframe_protocol import (
+    Buffer,
+    DlpackDeviceType,
+)
+
+if TYPE_CHECKING:
+    import numpy as np
+    import pyarrow as pa
+
+
+class PandasBuffer(Buffer):
+    """
+    Data in the buffer is guaranteed to be contiguous in memory.
+    """
+
+    def __init__(self, x: np.ndarray, allow_copy: bool = True) -> None:
+        """
+        Handle only regular columns (= numpy arrays) for now.
+        """
+        if x.strides[0] and not x.strides == (x.dtype.itemsize,):
+            # The protocol does not support strided buffers, so a copy is
+            # necessary. If that's not allowed, we need to raise an exception.
+            if allow_copy:
+                x = x.copy()
+            else:
+                raise RuntimeError(
+                    "Exports cannot be zero-copy in the case "
+                    "of a non-contiguous buffer"
+                )
+
+        # Store the numpy array in which the data resides as a private
+        # attribute, so we can use it to retrieve the public attributes
+        self._x = x
+
+    @property
+    def bufsize(self) -> int:
+        """
+        Buffer size in bytes.
+        """
+        return self._x.size * self._x.dtype.itemsize
+
+    @property
+    def ptr(self) -> int:
+        """
+        Pointer to start of the buffer as an integer.
+        """
+        return self._x.__array_interface__["data"][0]
+
+    def __dlpack__(self) -> Any:
+        """
+        Represent this structure as DLPack interface.
+        """
+        return self._x.__dlpack__()
+
+    def __dlpack_device__(self) -> tuple[DlpackDeviceType, int | None]:
+        """
+        Device type and device ID for where the data in the buffer resides.
+        """
+        return (DlpackDeviceType.CPU, None)
+
+    def __repr__(self) -> str:
+        return (
+            "PandasBuffer("
+            + str(
+                {
+                    "bufsize": self.bufsize,
+                    "ptr": self.ptr,
+                    "device": self.__dlpack_device__()[0].name,
+                }
+            )
+            + ")"
+        )
+
+
+class PandasBufferPyarrow(Buffer):
+    """
+    Data in the buffer is guaranteed to be contiguous in memory.
+    """
+
+    def __init__(
+        self,
+        buffer: pa.Buffer,
+        *,
+        length: int,
+    ) -> None:
+        """
+        Handle pyarrow chunked arrays.
+        """
+        self._buffer = buffer
+        self._length = length
+
+    @property
+    def bufsize(self) -> int:
+        """
+        Buffer size in bytes.
+        """
+        return self._buffer.size
+
+    @property
+    def ptr(self) -> int:
+        """
+        Pointer to start of the buffer as an integer.
+        """
+        return self._buffer.address
+
+    def __dlpack__(self) -> Any:
+        """
+        Represent this structure as DLPack interface.
+        """
+        raise NotImplementedError()
+
+    def __dlpack_device__(self) -> tuple[DlpackDeviceType, int | None]:
+        """
+        Device type and device ID for where the data in the buffer resides.
+        """
+        return (DlpackDeviceType.CPU, None)
+
+    def __repr__(self) -> str:
+        return (
+            "PandasBuffer[pyarrow]("
+            + str(
+                {
+                    "bufsize": self.bufsize,
+                    "ptr": self.ptr,
+                    "device": "CPU",
+                }
+            )
+            + ")"
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/column.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/column.py
new file mode 100644
index 0000000000000000000000000000000000000000..d59a3df694bb3f6ab5716c25592704d49737a215
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/column.py
@@ -0,0 +1,461 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+
+from pandas._libs.lib import infer_dtype
+from pandas._libs.tslibs import iNaT
+from pandas.errors import NoBufferPresent
+from pandas.util._decorators import cache_readonly
+
+from pandas.core.dtypes.dtypes import BaseMaskedDtype
+
+import pandas as pd
+from pandas import (
+    ArrowDtype,
+    DatetimeTZDtype,
+)
+from pandas.api.types import is_string_dtype
+from pandas.core.interchange.buffer import (
+    PandasBuffer,
+    PandasBufferPyarrow,
+)
+from pandas.core.interchange.dataframe_protocol import (
+    Column,
+    ColumnBuffers,
+    ColumnNullType,
+    DtypeKind,
+)
+from pandas.core.interchange.utils import (
+    ArrowCTypes,
+    Endianness,
+    dtype_to_arrow_c_fmt,
+)
+
+if TYPE_CHECKING:
+    from pandas.core.interchange.dataframe_protocol import Buffer
+
+_NP_KINDS = {
+    "i": DtypeKind.INT,
+    "u": DtypeKind.UINT,
+    "f": DtypeKind.FLOAT,
+    "b": DtypeKind.BOOL,
+    "U": DtypeKind.STRING,
+    "M": DtypeKind.DATETIME,
+    "m": DtypeKind.DATETIME,
+}
+
+_NULL_DESCRIPTION = {
+    DtypeKind.FLOAT: (ColumnNullType.USE_NAN, None),
+    DtypeKind.DATETIME: (ColumnNullType.USE_SENTINEL, iNaT),
+    DtypeKind.INT: (ColumnNullType.NON_NULLABLE, None),
+    DtypeKind.UINT: (ColumnNullType.NON_NULLABLE, None),
+    DtypeKind.BOOL: (ColumnNullType.NON_NULLABLE, None),
+    # Null values for categoricals are stored as `-1` sentinel values
+    # in the category date (e.g., `col.values.codes` is int8 np.ndarray)
+    DtypeKind.CATEGORICAL: (ColumnNullType.USE_SENTINEL, -1),
+    # follow Arrow in using 1 as valid value and 0 for missing/null value
+    DtypeKind.STRING: (ColumnNullType.USE_BYTEMASK, 0),
+}
+
+_NO_VALIDITY_BUFFER = {
+    ColumnNullType.NON_NULLABLE: "This column is non-nullable",
+    ColumnNullType.USE_NAN: "This column uses NaN as null",
+    ColumnNullType.USE_SENTINEL: "This column uses a sentinel value",
+}
+
+
+class PandasColumn(Column):
+    """
+    A column object, with only the methods and properties required by the
+    interchange protocol defined.
+    A column can contain one or more chunks. Each chunk can contain up to three
+    buffers - a data buffer, a mask buffer (depending on null representation),
+    and an offsets buffer (if variable-size binary; e.g., variable-length
+    strings).
+    Note: this Column object can only be produced by ``__dataframe__``, so
+          doesn't need its own version or ``__column__`` protocol.
+    """
+
+    def __init__(self, column: pd.Series, allow_copy: bool = True) -> None:
+        """
+        Note: doesn't deal with extension arrays yet, just assume a regular
+        Series/ndarray for now.
+        """
+        if isinstance(column, pd.DataFrame):
+            raise TypeError(
+                "Expected a Series, got a DataFrame. This likely happened "
+                "because you called __dataframe__ on a DataFrame which, "
+                "after converting column names to string, resulted in duplicated "
+                f"names: {column.columns}. Please rename these columns before "
+                "using the interchange protocol."
+            )
+        if not isinstance(column, pd.Series):
+            raise NotImplementedError(f"Columns of type {type(column)} not handled yet")
+
+        # Store the column as a private attribute
+        self._col = column
+        self._allow_copy = allow_copy
+
+    def size(self) -> int:
+        """
+        Size of the column, in elements.
+        """
+        return self._col.size
+
+    @property
+    def offset(self) -> int:
+        """
+        Offset of first element. Always zero.
+        """
+        # TODO: chunks are implemented now, probably this should return something
+        return 0
+
+    @cache_readonly
+    def dtype(self) -> tuple[DtypeKind, int, str, str]:
+        dtype = self._col.dtype
+
+        if isinstance(dtype, pd.CategoricalDtype):
+            codes = self._col.values.codes
+            (
+                _,
+                bitwidth,
+                c_arrow_dtype_f_str,
+                _,
+            ) = self._dtype_from_pandasdtype(codes.dtype)
+            return (
+                DtypeKind.CATEGORICAL,
+                bitwidth,
+                c_arrow_dtype_f_str,
+                Endianness.NATIVE,
+            )
+        elif is_string_dtype(dtype):
+            if infer_dtype(self._col) in ("string", "empty"):
+                return (
+                    DtypeKind.STRING,
+                    8,
+                    dtype_to_arrow_c_fmt(dtype),
+                    Endianness.NATIVE,
+                )
+            raise NotImplementedError("Non-string object dtypes are not supported yet")
+        else:
+            return self._dtype_from_pandasdtype(dtype)
+
+    def _dtype_from_pandasdtype(self, dtype) -> tuple[DtypeKind, int, str, str]:
+        """
+        See `self.dtype` for details.
+        """
+        # Note: 'c' (complex) not handled yet (not in array spec v1).
+        #       'b', 'B' (bytes), 'S', 'a', (old-style string) 'V' (void) not handled
+        #       datetime and timedelta both map to datetime (is timedelta handled?)
+
+        kind = _NP_KINDS.get(dtype.kind, None)
+        if kind is None:
+            # Not a NumPy dtype. Check if it's a categorical maybe
+            raise ValueError(f"Data type {dtype} not supported by interchange protocol")
+        if isinstance(dtype, ArrowDtype):
+            byteorder = dtype.numpy_dtype.byteorder
+        elif isinstance(dtype, DatetimeTZDtype):
+            byteorder = dtype.base.byteorder  # type: ignore[union-attr]
+        elif isinstance(dtype, BaseMaskedDtype):
+            byteorder = dtype.numpy_dtype.byteorder
+        else:
+            byteorder = dtype.byteorder
+
+        if dtype == "bool[pyarrow]":
+            # return early to avoid the `* 8` below, as this is a bitmask
+            # rather than a bytemask
+            return (
+                kind,
+                dtype.itemsize,  # pyright: ignore[reportGeneralTypeIssues]
+                ArrowCTypes.BOOL,
+                byteorder,
+            )
+
+        return kind, dtype.itemsize * 8, dtype_to_arrow_c_fmt(dtype), byteorder
+
+    @property
+    def describe_categorical(self):
+        """
+        If the dtype is categorical, there are two options:
+        - There are only values in the data buffer.
+        - There is a separate non-categorical Column encoding for categorical values.
+
+        Raises TypeError if the dtype is not categorical
+
+        Content of returned dict:
+            - "is_ordered" : bool, whether the ordering of dictionary indices is
+                             semantically meaningful.
+            - "is_dictionary" : bool, whether a dictionary-style mapping of
+                                categorical values to other objects exists
+            - "categories" : Column representing the (implicit) mapping of indices to
+                             category values (e.g. an array of cat1, cat2, ...).
+                             None if not a dictionary-style categorical.
+        """
+        if not self.dtype[0] == DtypeKind.CATEGORICAL:
+            raise TypeError(
+                "describe_categorical only works on a column with categorical dtype!"
+            )
+
+        return {
+            "is_ordered": self._col.cat.ordered,
+            "is_dictionary": True,
+            "categories": PandasColumn(pd.Series(self._col.cat.categories)),
+        }
+
+    @property
+    def describe_null(self):
+        if isinstance(self._col.dtype, BaseMaskedDtype):
+            column_null_dtype = ColumnNullType.USE_BYTEMASK
+            null_value = 1
+            return column_null_dtype, null_value
+        if isinstance(self._col.dtype, ArrowDtype):
+            # We already rechunk (if necessary / allowed) upon initialization, so this
+            # is already single-chunk by the time we get here.
+            if self._col.array._pa_array.chunks[0].buffers()[0] is None:  # type: ignore[attr-defined]
+                return ColumnNullType.NON_NULLABLE, None
+            return ColumnNullType.USE_BITMASK, 0
+        kind = self.dtype[0]
+        try:
+            null, value = _NULL_DESCRIPTION[kind]
+        except KeyError:
+            raise NotImplementedError(f"Data type {kind} not yet supported")
+
+        return null, value
+
+    @cache_readonly
+    def null_count(self) -> int:
+        """
+        Number of null elements. Should always be known.
+        """
+        return self._col.isna().sum().item()
+
+    @property
+    def metadata(self) -> dict[str, pd.Index]:
+        """
+        Store specific metadata of the column.
+        """
+        return {"pandas.index": self._col.index}
+
+    def num_chunks(self) -> int:
+        """
+        Return the number of chunks the column consists of.
+        """
+        return 1
+
+    def get_chunks(self, n_chunks: int | None = None):
+        """
+        Return an iterator yielding the chunks.
+        See `DataFrame.get_chunks` for details on ``n_chunks``.
+        """
+        if n_chunks and n_chunks > 1:
+            size = len(self._col)
+            step = size // n_chunks
+            if size % n_chunks != 0:
+                step += 1
+            for start in range(0, step * n_chunks, step):
+                yield PandasColumn(
+                    self._col.iloc[start : start + step], self._allow_copy
+                )
+        else:
+            yield self
+
+    def get_buffers(self) -> ColumnBuffers:
+        """
+        Return a dictionary containing the underlying buffers.
+        The returned dictionary has the following contents:
+            - "data": a two-element tuple whose first element is a buffer
+                      containing the data and whose second element is the data
+                      buffer's associated dtype.
+            - "validity": a two-element tuple whose first element is a buffer
+                          containing mask values indicating missing data and
+                          whose second element is the mask value buffer's
+                          associated dtype. None if the null representation is
+                          not a bit or byte mask.
+            - "offsets": a two-element tuple whose first element is a buffer
+                         containing the offset values for variable-size binary
+                         data (e.g., variable-length strings) and whose second
+                         element is the offsets buffer's associated dtype. None
+                         if the data buffer does not have an associated offsets
+                         buffer.
+        """
+        buffers: ColumnBuffers = {
+            "data": self._get_data_buffer(),
+            "validity": None,
+            "offsets": None,
+        }
+
+        try:
+            buffers["validity"] = self._get_validity_buffer()
+        except NoBufferPresent:
+            pass
+
+        try:
+            buffers["offsets"] = self._get_offsets_buffer()
+        except NoBufferPresent:
+            pass
+
+        return buffers
+
+    def _get_data_buffer(
+        self,
+    ) -> tuple[Buffer, tuple[DtypeKind, int, str, str]]:
+        """
+        Return the buffer containing the data and the buffer's associated dtype.
+        """
+        buffer: Buffer
+        if self.dtype[0] in (
+            DtypeKind.INT,
+            DtypeKind.UINT,
+            DtypeKind.FLOAT,
+            DtypeKind.BOOL,
+            DtypeKind.DATETIME,
+        ):
+            # self.dtype[2] is an ArrowCTypes.TIMESTAMP where the tz will make
+            # it longer than 4 characters
+            dtype = self.dtype
+            if self.dtype[0] == DtypeKind.DATETIME and len(self.dtype[2]) > 4:
+                np_arr = self._col.dt.tz_convert(None).to_numpy()
+            else:
+                arr = self._col.array
+                if isinstance(self._col.dtype, BaseMaskedDtype):
+                    np_arr = arr._data  # type: ignore[attr-defined]
+                elif isinstance(self._col.dtype, ArrowDtype):
+                    # We already rechunk (if necessary / allowed) upon initialization,
+                    # so this is already single-chunk by the time we get here.
+                    arr = arr._pa_array.chunks[0]  # type: ignore[attr-defined]
+                    buffer = PandasBufferPyarrow(
+                        arr.buffers()[1],  # type: ignore[attr-defined]
+                        length=len(arr),
+                    )
+                    return buffer, dtype
+                else:
+                    np_arr = arr._ndarray  # type: ignore[attr-defined]
+            buffer = PandasBuffer(np_arr, allow_copy=self._allow_copy)
+        elif self.dtype[0] == DtypeKind.CATEGORICAL:
+            codes = self._col.values._codes
+            buffer = PandasBuffer(codes, allow_copy=self._allow_copy)
+            dtype = self._dtype_from_pandasdtype(codes.dtype)
+        elif self.dtype[0] == DtypeKind.STRING:
+            # Marshal the strings from a NumPy object array into a byte array
+            buf = self._col.to_numpy()
+            b = bytearray()
+
+            # TODO: this for-loop is slow; can be implemented in Cython/C/C++ later
+            for obj in buf:
+                if isinstance(obj, str):
+                    b.extend(obj.encode(encoding="utf-8"))
+
+            # Convert the byte array to a Pandas "buffer" using
+            # a NumPy array as the backing store
+            buffer = PandasBuffer(np.frombuffer(b, dtype="uint8"))
+
+            # Define the dtype for the returned buffer
+            # TODO: this will need correcting
+            # https://github.com/pandas-dev/pandas/issues/54781
+            dtype = self.dtype
+        else:
+            raise NotImplementedError(f"Data type {self._col.dtype} not handled yet")
+
+        return buffer, dtype
+
+    def _get_validity_buffer(self) -> tuple[Buffer, Any] | None:
+        """
+        Return the buffer containing the mask values indicating missing data and
+        the buffer's associated dtype.
+        Raises NoBufferPresent if null representation is not a bit or byte mask.
+        """
+        null, invalid = self.describe_null
+        buffer: Buffer
+        if isinstance(self._col.dtype, ArrowDtype):
+            # We already rechunk (if necessary / allowed) upon initialization, so this
+            # is already single-chunk by the time we get here.
+            arr = self._col.array._pa_array.chunks[0]  # type: ignore[attr-defined]
+            dtype = (DtypeKind.BOOL, 1, ArrowCTypes.BOOL, Endianness.NATIVE)
+            if arr.buffers()[0] is None:
+                return None
+            buffer = PandasBufferPyarrow(
+                arr.buffers()[0],
+                length=len(arr),
+            )
+            return buffer, dtype
+
+        if isinstance(self._col.dtype, BaseMaskedDtype):
+            mask = self._col.array._mask  # type: ignore[attr-defined]
+            buffer = PandasBuffer(mask)
+            dtype = (DtypeKind.BOOL, 8, ArrowCTypes.BOOL, Endianness.NATIVE)
+            return buffer, dtype
+
+        if self.dtype[0] == DtypeKind.STRING:
+            # For now, use byte array as the mask.
+            # TODO: maybe store as bit array to save space?..
+            buf = self._col.to_numpy()
+
+            # Determine the encoding for valid values
+            valid = invalid == 0
+            invalid = not valid
+
+            mask = np.zeros(shape=(len(buf),), dtype=np.bool_)
+            for i, obj in enumerate(buf):
+                mask[i] = valid if isinstance(obj, str) else invalid
+
+            # Convert the mask array to a Pandas "buffer" using
+            # a NumPy array as the backing store
+            buffer = PandasBuffer(mask)
+
+            # Define the dtype of the returned buffer
+            dtype = (DtypeKind.BOOL, 8, ArrowCTypes.BOOL, Endianness.NATIVE)
+
+            return buffer, dtype
+
+        try:
+            msg = f"{_NO_VALIDITY_BUFFER[null]} so does not have a separate mask"
+        except KeyError:
+            # TODO: implement for other bit/byte masks?
+            raise NotImplementedError("See self.describe_null")
+
+        raise NoBufferPresent(msg)
+
+    def _get_offsets_buffer(self) -> tuple[PandasBuffer, Any]:
+        """
+        Return the buffer containing the offset values for variable-size binary
+        data (e.g., variable-length strings) and the buffer's associated dtype.
+        Raises NoBufferPresent if the data buffer does not have an associated
+        offsets buffer.
+        """
+        if self.dtype[0] == DtypeKind.STRING:
+            # For each string, we need to manually determine the next offset
+            values = self._col.to_numpy()
+            ptr = 0
+            offsets = np.zeros(shape=(len(values) + 1,), dtype=np.int64)
+            for i, v in enumerate(values):
+                # For missing values (in this case, `np.nan` values)
+                # we don't increment the pointer
+                if isinstance(v, str):
+                    b = v.encode(encoding="utf-8")
+                    ptr += len(b)
+
+                offsets[i + 1] = ptr
+
+            # Convert the offsets to a Pandas "buffer" using
+            # the NumPy array as the backing store
+            buffer = PandasBuffer(offsets)
+
+            # Assemble the buffer dtype info
+            dtype = (
+                DtypeKind.INT,
+                64,
+                ArrowCTypes.INT64,
+                Endianness.NATIVE,
+            )  # note: currently only support native endianness
+        else:
+            raise NoBufferPresent(
+                "This column has a fixed-length dtype so "
+                "it does not have an offsets buffer"
+            )
+
+        return buffer, dtype
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe.py
new file mode 100644
index 0000000000000000000000000000000000000000..1abacddfc7e3b7035a9446cd4118097c6accd385
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe.py
@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections import abc
+from typing import TYPE_CHECKING
+
+from pandas.core.interchange.column import PandasColumn
+from pandas.core.interchange.dataframe_protocol import DataFrame as DataFrameXchg
+from pandas.core.interchange.utils import maybe_rechunk
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Sequence,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+    )
+
+
+class PandasDataFrameXchg(DataFrameXchg):
+    """
+    A data frame class, with only the methods required by the interchange
+    protocol defined.
+    Instances of this (private) class are returned from
+    ``pd.DataFrame.__dataframe__`` as objects with the methods and
+    attributes defined on this class.
+    """
+
+    def __init__(self, df: DataFrame, allow_copy: bool = True) -> None:
+        """
+        Constructor - an instance of this (private) class is returned from
+        `pd.DataFrame.__dataframe__`.
+        """
+        self._df = df.rename(columns=str, copy=False)
+        self._allow_copy = allow_copy
+        for i, _col in enumerate(self._df.columns):
+            rechunked = maybe_rechunk(self._df.iloc[:, i], allow_copy=allow_copy)
+            if rechunked is not None:
+                self._df.isetitem(i, rechunked)
+
+    def __dataframe__(
+        self, nan_as_null: bool = False, allow_copy: bool = True
+    ) -> PandasDataFrameXchg:
+        # `nan_as_null` can be removed here once it's removed from
+        # Dataframe.__dataframe__
+        return PandasDataFrameXchg(self._df, allow_copy)
+
+    @property
+    def metadata(self) -> dict[str, Index]:
+        # `index` isn't a regular column, and the protocol doesn't support row
+        # labels - so we export it as Pandas-specific metadata here.
+        return {"pandas.index": self._df.index}
+
+    def num_columns(self) -> int:
+        return len(self._df.columns)
+
+    def num_rows(self) -> int:
+        return len(self._df)
+
+    def num_chunks(self) -> int:
+        return 1
+
+    def column_names(self) -> Index:
+        return self._df.columns
+
+    def get_column(self, i: int) -> PandasColumn:
+        return PandasColumn(self._df.iloc[:, i], allow_copy=self._allow_copy)
+
+    def get_column_by_name(self, name: str) -> PandasColumn:
+        return PandasColumn(self._df[name], allow_copy=self._allow_copy)
+
+    def get_columns(self) -> list[PandasColumn]:
+        return [
+            PandasColumn(self._df[name], allow_copy=self._allow_copy)
+            for name in self._df.columns
+        ]
+
+    def select_columns(self, indices: Sequence[int]) -> PandasDataFrameXchg:
+        if not isinstance(indices, abc.Sequence):
+            raise ValueError("`indices` is not a sequence")
+        if not isinstance(indices, list):
+            indices = list(indices)
+
+        return PandasDataFrameXchg(
+            self._df.iloc[:, indices], allow_copy=self._allow_copy
+        )
+
+    def select_columns_by_name(self, names: list[str]) -> PandasDataFrameXchg:  # type: ignore[override]
+        if not isinstance(names, abc.Sequence):
+            raise ValueError("`names` is not a sequence")
+        if not isinstance(names, list):
+            names = list(names)
+
+        return PandasDataFrameXchg(self._df.loc[:, names], allow_copy=self._allow_copy)
+
+    def get_chunks(self, n_chunks: int | None = None) -> Iterable[PandasDataFrameXchg]:
+        """
+        Return an iterator yielding the chunks.
+        """
+        if n_chunks and n_chunks > 1:
+            size = len(self._df)
+            step = size // n_chunks
+            if size % n_chunks != 0:
+                step += 1
+            for start in range(0, step * n_chunks, step):
+                yield PandasDataFrameXchg(
+                    self._df.iloc[start : start + step, :],
+                    allow_copy=self._allow_copy,
+                )
+        else:
+            yield self
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe_protocol.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe_protocol.py
new file mode 100644
index 0000000000000000000000000000000000000000..95e7b6a26f93a8cd10048076bd6906190e04d2ba
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/dataframe_protocol.py
@@ -0,0 +1,465 @@
+"""
+A verbatim copy (vendored) of the spec from https://github.com/data-apis/dataframe-api
+"""
+
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+import enum
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    TypedDict,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Sequence,
+    )
+
+
+class DlpackDeviceType(enum.IntEnum):
+    """Integer enum for device type codes matching DLPack."""
+
+    CPU = 1
+    CUDA = 2
+    CPU_PINNED = 3
+    OPENCL = 4
+    VULKAN = 7
+    METAL = 8
+    VPI = 9
+    ROCM = 10
+
+
+class DtypeKind(enum.IntEnum):
+    """
+    Integer enum for data types.
+
+    Attributes
+    ----------
+    INT : int
+        Matches to signed integer data type.
+    UINT : int
+        Matches to unsigned integer data type.
+    FLOAT : int
+        Matches to floating point data type.
+    BOOL : int
+        Matches to boolean data type.
+    STRING : int
+        Matches to string data type (UTF-8 encoded).
+    DATETIME : int
+        Matches to datetime data type.
+    CATEGORICAL : int
+        Matches to categorical data type.
+    """
+
+    INT = 0
+    UINT = 1
+    FLOAT = 2
+    BOOL = 20
+    STRING = 21  # UTF-8
+    DATETIME = 22
+    CATEGORICAL = 23
+
+
+class ColumnNullType(enum.IntEnum):
+    """
+    Integer enum for null type representation.
+
+    Attributes
+    ----------
+    NON_NULLABLE : int
+        Non-nullable column.
+    USE_NAN : int
+        Use explicit float NaN value.
+    USE_SENTINEL : int
+        Sentinel value besides NaN/NaT.
+    USE_BITMASK : int
+        The bit is set/unset representing a null on a certain position.
+    USE_BYTEMASK : int
+        The byte is set/unset representing a null on a certain position.
+    """
+
+    NON_NULLABLE = 0
+    USE_NAN = 1
+    USE_SENTINEL = 2
+    USE_BITMASK = 3
+    USE_BYTEMASK = 4
+
+
+class ColumnBuffers(TypedDict):
+    # first element is a buffer containing the column data;
+    # second element is the data buffer's associated dtype
+    data: tuple[Buffer, Any]
+
+    # first element is a buffer containing mask values indicating missing data;
+    # second element is the mask value buffer's associated dtype.
+    # None if the null representation is not a bit or byte mask
+    validity: tuple[Buffer, Any] | None
+
+    # first element is a buffer containing the offset values for
+    # variable-size binary data (e.g., variable-length strings);
+    # second element is the offsets buffer's associated dtype.
+    # None if the data buffer does not have an associated offsets buffer
+    offsets: tuple[Buffer, Any] | None
+
+
+class CategoricalDescription(TypedDict):
+    # whether the ordering of dictionary indices is semantically meaningful
+    is_ordered: bool
+    # whether a dictionary-style mapping of categorical values to other objects exists
+    is_dictionary: bool
+    # Python-level only (e.g. ``{int: str}``).
+    # None if not a dictionary-style categorical.
+    categories: Column | None
+
+
+class Buffer(ABC):
+    """
+    Data in the buffer is guaranteed to be contiguous in memory.
+
+    Note that there is no dtype attribute present, a buffer can be thought of
+    as simply a block of memory. However, if the column that the buffer is
+    attached to has a dtype that's supported by DLPack and ``__dlpack__`` is
+    implemented, then that dtype information will be contained in the return
+    value from ``__dlpack__``.
+
+    This distinction is useful to support both data exchange via DLPack on a
+    buffer and (b) dtypes like variable-length strings which do not have a
+    fixed number of bytes per element.
+    """
+
+    @property
+    @abstractmethod
+    def bufsize(self) -> int:
+        """
+        Buffer size in bytes.
+        """
+
+    @property
+    @abstractmethod
+    def ptr(self) -> int:
+        """
+        Pointer to start of the buffer as an integer.
+        """
+
+    @abstractmethod
+    def __dlpack__(self):
+        """
+        Produce DLPack capsule (see array API standard).
+
+        Raises:
+
+            - TypeError : if the buffer contains unsupported dtypes.
+            - NotImplementedError : if DLPack support is not implemented
+
+        Useful to have to connect to array libraries. Support optional because
+        it's not completely trivial to implement for a Python-only library.
+        """
+        raise NotImplementedError("__dlpack__")
+
+    @abstractmethod
+    def __dlpack_device__(self) -> tuple[DlpackDeviceType, int | None]:
+        """
+        Device type and device ID for where the data in the buffer resides.
+        Uses device type codes matching DLPack.
+        Note: must be implemented even if ``__dlpack__`` is not.
+        """
+
+
+class Column(ABC):
+    """
+    A column object, with only the methods and properties required by the
+    interchange protocol defined.
+
+    A column can contain one or more chunks. Each chunk can contain up to three
+    buffers - a data buffer, a mask buffer (depending on null representation),
+    and an offsets buffer (if variable-size binary; e.g., variable-length
+    strings).
+
+    TBD: Arrow has a separate "null" dtype, and has no separate mask concept.
+         Instead, it seems to use "children" for both columns with a bit mask,
+         and for nested dtypes. Unclear whether this is elegant or confusing.
+         This design requires checking the null representation explicitly.
+
+         The Arrow design requires checking:
+         1. the ARROW_FLAG_NULLABLE (for sentinel values)
+         2. if a column has two children, combined with one of those children
+            having a null dtype.
+
+         Making the mask concept explicit seems useful. One null dtype would
+         not be enough to cover both bit and byte masks, so that would mean
+         even more checking if we did it the Arrow way.
+
+    TBD: there's also the "chunk" concept here, which is implicit in Arrow as
+         multiple buffers per array (= column here). Semantically it may make
+         sense to have both: chunks were meant for example for lazy evaluation
+         of data which doesn't fit in memory, while multiple buffers per column
+         could also come from doing a selection operation on a single
+         contiguous buffer.
+
+         Given these concepts, one would expect chunks to be all of the same
+         size (say a 10,000 row dataframe could have 10 chunks of 1,000 rows),
+         while multiple buffers could have data-dependent lengths. Not an issue
+         in pandas if one column is backed by a single NumPy array, but in
+         Arrow it seems possible.
+         Are multiple chunks *and* multiple buffers per column necessary for
+         the purposes of this interchange protocol, or must producers either
+         reuse the chunk concept for this or copy the data?
+
+    Note: this Column object can only be produced by ``__dataframe__``, so
+          doesn't need its own version or ``__column__`` protocol.
+    """
+
+    @abstractmethod
+    def size(self) -> int:
+        """
+        Size of the column, in elements.
+
+        Corresponds to DataFrame.num_rows() if column is a single chunk;
+        equal to size of this current chunk otherwise.
+        """
+
+    @property
+    @abstractmethod
+    def offset(self) -> int:
+        """
+        Offset of first element.
+
+        May be > 0 if using chunks; for example for a column with N chunks of
+        equal size M (only the last chunk may be shorter),
+        ``offset = n * M``, ``n = 0 .. N-1``.
+        """
+
+    @property
+    @abstractmethod
+    def dtype(self) -> tuple[DtypeKind, int, str, str]:
+        """
+        Dtype description as a tuple ``(kind, bit-width, format string, endianness)``.
+
+        Bit-width : the number of bits as an integer
+        Format string : data type description format string in Apache Arrow C
+                        Data Interface format.
+        Endianness : current only native endianness (``=``) is supported
+
+        Notes:
+            - Kind specifiers are aligned with DLPack where possible (hence the
+              jump to 20, leave enough room for future extension)
+            - Masks must be specified as boolean with either bit width 1 (for bit
+              masks) or 8 (for byte masks).
+            - Dtype width in bits was preferred over bytes
+            - Endianness isn't too useful, but included now in case in the future
+              we need to support non-native endianness
+            - Went with Apache Arrow format strings over NumPy format strings
+              because they're more complete from a dataframe perspective
+            - Format strings are mostly useful for datetime specification, and
+              for categoricals.
+            - For categoricals, the format string describes the type of the
+              categorical in the data buffer. In case of a separate encoding of
+              the categorical (e.g. an integer to string mapping), this can
+              be derived from ``self.describe_categorical``.
+            - Data types not included: complex, Arrow-style null, binary, decimal,
+              and nested (list, struct, map, union) dtypes.
+        """
+
+    @property
+    @abstractmethod
+    def describe_categorical(self) -> CategoricalDescription:
+        """
+        If the dtype is categorical, there are two options:
+        - There are only values in the data buffer.
+        - There is a separate non-categorical Column encoding for categorical values.
+
+        Raises TypeError if the dtype is not categorical
+
+        Returns the dictionary with description on how to interpret the data buffer:
+            - "is_ordered" : bool, whether the ordering of dictionary indices is
+                             semantically meaningful.
+            - "is_dictionary" : bool, whether a mapping of
+                                categorical values to other objects exists
+            - "categories" : Column representing the (implicit) mapping of indices to
+                             category values (e.g. an array of cat1, cat2, ...).
+                             None if not a dictionary-style categorical.
+
+        TBD: are there any other in-memory representations that are needed?
+        """
+
+    @property
+    @abstractmethod
+    def describe_null(self) -> tuple[ColumnNullType, Any]:
+        """
+        Return the missing value (or "null") representation the column dtype
+        uses, as a tuple ``(kind, value)``.
+
+        Value : if kind is "sentinel value", the actual value. If kind is a bit
+        mask or a byte mask, the value (0 or 1) indicating a missing value. None
+        otherwise.
+        """
+
+    @property
+    @abstractmethod
+    def null_count(self) -> int | None:
+        """
+        Number of null elements, if known.
+
+        Note: Arrow uses -1 to indicate "unknown", but None seems cleaner.
+        """
+
+    @property
+    @abstractmethod
+    def metadata(self) -> dict[str, Any]:
+        """
+        The metadata for the column. See `DataFrame.metadata` for more details.
+        """
+
+    @abstractmethod
+    def num_chunks(self) -> int:
+        """
+        Return the number of chunks the column consists of.
+        """
+
+    @abstractmethod
+    def get_chunks(self, n_chunks: int | None = None) -> Iterable[Column]:
+        """
+        Return an iterator yielding the chunks.
+
+        See `DataFrame.get_chunks` for details on ``n_chunks``.
+        """
+
+    @abstractmethod
+    def get_buffers(self) -> ColumnBuffers:
+        """
+        Return a dictionary containing the underlying buffers.
+
+        The returned dictionary has the following contents:
+
+            - "data": a two-element tuple whose first element is a buffer
+                      containing the data and whose second element is the data
+                      buffer's associated dtype.
+            - "validity": a two-element tuple whose first element is a buffer
+                          containing mask values indicating missing data and
+                          whose second element is the mask value buffer's
+                          associated dtype. None if the null representation is
+                          not a bit or byte mask.
+            - "offsets": a two-element tuple whose first element is a buffer
+                         containing the offset values for variable-size binary
+                         data (e.g., variable-length strings) and whose second
+                         element is the offsets buffer's associated dtype. None
+                         if the data buffer does not have an associated offsets
+                         buffer.
+        """
+
+
+#    def get_children(self) -> Iterable[Column]:
+#        """
+#        Children columns underneath the column, each object in this iterator
+#        must adhere to the column specification.
+#        """
+#        pass
+
+
+class DataFrame(ABC):
+    """
+    A data frame class, with only the methods required by the interchange
+    protocol defined.
+
+    A "data frame" represents an ordered collection of named columns.
+    A column's "name" must be a unique string.
+    Columns may be accessed by name or by position.
+
+    This could be a public data frame class, or an object with the methods and
+    attributes defined on this DataFrame class could be returned from the
+    ``__dataframe__`` method of a public data frame class in a library adhering
+    to the dataframe interchange protocol specification.
+    """
+
+    version = 0  # version of the protocol
+
+    @abstractmethod
+    def __dataframe__(self, nan_as_null: bool = False, allow_copy: bool = True):
+        """Construct a new interchange object, potentially changing the parameters."""
+
+    @property
+    @abstractmethod
+    def metadata(self) -> dict[str, Any]:
+        """
+        The metadata for the data frame, as a dictionary with string keys. The
+        contents of `metadata` may be anything, they are meant for a library
+        to store information that it needs to, e.g., roundtrip losslessly or
+        for two implementations to share data that is not (yet) part of the
+        interchange protocol specification. For avoiding collisions with other
+        entries, please add name the keys with the name of the library
+        followed by a period and the desired name, e.g, ``pandas.indexcol``.
+        """
+
+    @abstractmethod
+    def num_columns(self) -> int:
+        """
+        Return the number of columns in the DataFrame.
+        """
+
+    @abstractmethod
+    def num_rows(self) -> int | None:
+        # TODO: not happy with Optional, but need to flag it may be expensive
+        #       why include it if it may be None - what do we expect consumers
+        #       to do here?
+        """
+        Return the number of rows in the DataFrame, if available.
+        """
+
+    @abstractmethod
+    def num_chunks(self) -> int:
+        """
+        Return the number of chunks the DataFrame consists of.
+        """
+
+    @abstractmethod
+    def column_names(self) -> Iterable[str]:
+        """
+        Return an iterator yielding the column names.
+        """
+
+    @abstractmethod
+    def get_column(self, i: int) -> Column:
+        """
+        Return the column at the indicated position.
+        """
+
+    @abstractmethod
+    def get_column_by_name(self, name: str) -> Column:
+        """
+        Return the column whose name is the indicated name.
+        """
+
+    @abstractmethod
+    def get_columns(self) -> Iterable[Column]:
+        """
+        Return an iterator yielding the columns.
+        """
+
+    @abstractmethod
+    def select_columns(self, indices: Sequence[int]) -> DataFrame:
+        """
+        Create a new DataFrame by selecting a subset of columns by index.
+        """
+
+    @abstractmethod
+    def select_columns_by_name(self, names: Sequence[str]) -> DataFrame:
+        """
+        Create a new DataFrame by selecting a subset of columns by name.
+        """
+
+    @abstractmethod
+    def get_chunks(self, n_chunks: int | None = None) -> Iterable[DataFrame]:
+        """
+        Return an iterator yielding the chunks.
+
+        By default (None), yields the chunks that the data is stored as by the
+        producer. If given, ``n_chunks`` must be a multiple of
+        ``self.num_chunks()``, meaning the producer must subdivide each chunk
+        before yielding it.
+        """
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/from_dataframe.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/from_dataframe.py
new file mode 100644
index 0000000000000000000000000000000000000000..c0df1c17e3a7c5276ff055e4fe23b5fca90988ca
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/from_dataframe.py
@@ -0,0 +1,557 @@
+from __future__ import annotations
+
+import ctypes
+import re
+from typing import Any
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import SettingWithCopyError
+
+import pandas as pd
+from pandas.core.interchange.dataframe_protocol import (
+    Buffer,
+    Column,
+    ColumnNullType,
+    DataFrame as DataFrameXchg,
+    DtypeKind,
+)
+from pandas.core.interchange.utils import (
+    ArrowCTypes,
+    Endianness,
+)
+
+_NP_DTYPES: dict[DtypeKind, dict[int, Any]] = {
+    DtypeKind.INT: {8: np.int8, 16: np.int16, 32: np.int32, 64: np.int64},
+    DtypeKind.UINT: {8: np.uint8, 16: np.uint16, 32: np.uint32, 64: np.uint64},
+    DtypeKind.FLOAT: {32: np.float32, 64: np.float64},
+    DtypeKind.BOOL: {1: bool, 8: bool},
+}
+
+
+def from_dataframe(df, allow_copy: bool = True) -> pd.DataFrame:
+    """
+    Build a ``pd.DataFrame`` from any DataFrame supporting the interchange protocol.
+
+    .. note::
+
+       For new development, we highly recommend using the Arrow C Data Interface
+       alongside the Arrow PyCapsule Interface instead of the interchange protocol.
+       From pandas 2.3 onwards, `from_dataframe` uses the PyCapsule Interface,
+       only falling back to the interchange protocol if that fails.
+
+    .. warning::
+
+        Due to severe implementation issues, we recommend only considering using the
+        interchange protocol in the following cases:
+
+        - converting to pandas: for pandas >= 2.0.3
+        - converting from pandas: for pandas >= 3.0.0
+
+    Parameters
+    ----------
+    df : DataFrameXchg
+        Object supporting the interchange protocol, i.e. `__dataframe__` method.
+    allow_copy : bool, default: True
+        Whether to allow copying the memory to perform the conversion
+        (if false then zero-copy approach is requested).
+
+    Returns
+    -------
+    pd.DataFrame
+
+    Examples
+    --------
+    >>> df_not_necessarily_pandas = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+    >>> interchange_object = df_not_necessarily_pandas.__dataframe__()
+    >>> interchange_object.column_names()
+    Index(['A', 'B'], dtype='object')
+    >>> df_pandas = (pd.api.interchange.from_dataframe
+    ...              (interchange_object.select_columns_by_name(['A'])))
+    >>> df_pandas
+         A
+    0    1
+    1    2
+
+    These methods (``column_names``, ``select_columns_by_name``) should work
+    for any dataframe library which implements the interchange protocol.
+    """
+    if isinstance(df, pd.DataFrame):
+        return df
+
+    if hasattr(df, "__arrow_c_stream__"):
+        try:
+            pa = import_optional_dependency("pyarrow", min_version="14.0.0")
+        except ImportError:
+            # fallback to _from_dataframe
+            pass
+        else:
+            try:
+                return pa.table(df).to_pandas(zero_copy_only=not allow_copy)
+            except pa.ArrowInvalid as e:
+                raise RuntimeError(e) from e
+
+    if not hasattr(df, "__dataframe__"):
+        raise ValueError("`df` does not support __dataframe__")
+
+    return _from_dataframe(
+        df.__dataframe__(allow_copy=allow_copy), allow_copy=allow_copy
+    )
+
+
+def _from_dataframe(df: DataFrameXchg, allow_copy: bool = True):
+    """
+    Build a ``pd.DataFrame`` from the DataFrame interchange object.
+
+    Parameters
+    ----------
+    df : DataFrameXchg
+        Object supporting the interchange protocol, i.e. `__dataframe__` method.
+    allow_copy : bool, default: True
+        Whether to allow copying the memory to perform the conversion
+        (if false then zero-copy approach is requested).
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    pandas_dfs = []
+    for chunk in df.get_chunks():
+        pandas_df = protocol_df_chunk_to_pandas(chunk)
+        pandas_dfs.append(pandas_df)
+
+    if not allow_copy and len(pandas_dfs) > 1:
+        raise RuntimeError(
+            "To join chunks a copy is required which is forbidden by allow_copy=False"
+        )
+    if not pandas_dfs:
+        pandas_df = protocol_df_chunk_to_pandas(df)
+    elif len(pandas_dfs) == 1:
+        pandas_df = pandas_dfs[0]
+    else:
+        pandas_df = pd.concat(pandas_dfs, axis=0, ignore_index=True, copy=False)
+
+    index_obj = df.metadata.get("pandas.index", None)
+    if index_obj is not None:
+        pandas_df.index = index_obj
+
+    return pandas_df
+
+
+def protocol_df_chunk_to_pandas(df: DataFrameXchg) -> pd.DataFrame:
+    """
+    Convert interchange protocol chunk to ``pd.DataFrame``.
+
+    Parameters
+    ----------
+    df : DataFrameXchg
+
+    Returns
+    -------
+    pd.DataFrame
+    """
+    columns: dict[str, Any] = {}
+    buffers = []  # hold on to buffers, keeps memory alive
+    for name in df.column_names():
+        if not isinstance(name, str):
+            raise ValueError(f"Column {name} is not a string")
+        if name in columns:
+            raise ValueError(f"Column {name} is not unique")
+        col = df.get_column_by_name(name)
+        dtype = col.dtype[0]
+        if dtype in (
+            DtypeKind.INT,
+            DtypeKind.UINT,
+            DtypeKind.FLOAT,
+            DtypeKind.BOOL,
+        ):
+            columns[name], buf = primitive_column_to_ndarray(col)
+        elif dtype == DtypeKind.CATEGORICAL:
+            columns[name], buf = categorical_column_to_series(col)
+        elif dtype == DtypeKind.STRING:
+            columns[name], buf = string_column_to_ndarray(col)
+        elif dtype == DtypeKind.DATETIME:
+            columns[name], buf = datetime_column_to_ndarray(col)
+        else:
+            raise NotImplementedError(f"Data type {dtype} not handled yet")
+
+        buffers.append(buf)
+
+    pandas_df = pd.DataFrame(columns)
+    pandas_df.attrs["_INTERCHANGE_PROTOCOL_BUFFERS"] = buffers
+    return pandas_df
+
+
+def primitive_column_to_ndarray(col: Column) -> tuple[np.ndarray, Any]:
+    """
+    Convert a column holding one of the primitive dtypes to a NumPy array.
+
+    A primitive type is one of: int, uint, float, bool.
+
+    Parameters
+    ----------
+    col : Column
+
+    Returns
+    -------
+    tuple
+        Tuple of np.ndarray holding the data and the memory owner object
+        that keeps the memory alive.
+    """
+    buffers = col.get_buffers()
+
+    data_buff, data_dtype = buffers["data"]
+    data = buffer_to_ndarray(
+        data_buff, data_dtype, offset=col.offset, length=col.size()
+    )
+
+    data = set_nulls(data, col, buffers["validity"])
+    return data, buffers
+
+
+def categorical_column_to_series(col: Column) -> tuple[pd.Series, Any]:
+    """
+    Convert a column holding categorical data to a pandas Series.
+
+    Parameters
+    ----------
+    col : Column
+
+    Returns
+    -------
+    tuple
+        Tuple of pd.Series holding the data and the memory owner object
+        that keeps the memory alive.
+    """
+    categorical = col.describe_categorical
+
+    if not categorical["is_dictionary"]:
+        raise NotImplementedError("Non-dictionary categoricals not supported yet")
+
+    cat_column = categorical["categories"]
+    if hasattr(cat_column, "_col"):
+        # Item "Column" of "Optional[Column]" has no attribute "_col"
+        # Item "None" of "Optional[Column]" has no attribute "_col"
+        categories = np.array(cat_column._col)  # type: ignore[union-attr]
+    else:
+        raise NotImplementedError(
+            "Interchanging categorical columns isn't supported yet, and our "
+            "fallback of using the `col._col` attribute (a ndarray) failed."
+        )
+    buffers = col.get_buffers()
+
+    codes_buff, codes_dtype = buffers["data"]
+    codes = buffer_to_ndarray(
+        codes_buff, codes_dtype, offset=col.offset, length=col.size()
+    )
+
+    # Doing module in order to not get ``IndexError`` for
+    # out-of-bounds sentinel values in `codes`
+    if len(categories) > 0:
+        values = categories[codes % len(categories)]
+    else:
+        values = codes
+
+    cat = pd.Categorical(
+        values, categories=categories, ordered=categorical["is_ordered"]
+    )
+    data = pd.Series(cat)
+
+    data = set_nulls(data, col, buffers["validity"])
+    return data, buffers
+
+
+def string_column_to_ndarray(col: Column) -> tuple[np.ndarray, Any]:
+    """
+    Convert a column holding string data to a NumPy array.
+
+    Parameters
+    ----------
+    col : Column
+
+    Returns
+    -------
+    tuple
+        Tuple of np.ndarray holding the data and the memory owner object
+        that keeps the memory alive.
+    """
+    null_kind, sentinel_val = col.describe_null
+
+    if null_kind not in (
+        ColumnNullType.NON_NULLABLE,
+        ColumnNullType.USE_BITMASK,
+        ColumnNullType.USE_BYTEMASK,
+    ):
+        raise NotImplementedError(
+            f"{null_kind} null kind is not yet supported for string columns."
+        )
+
+    buffers = col.get_buffers()
+
+    assert buffers["offsets"], "String buffers must contain offsets"
+    # Retrieve the data buffer containing the UTF-8 code units
+    data_buff, _ = buffers["data"]
+    # We're going to reinterpret the buffer as uint8, so make sure we can do it safely
+    assert col.dtype[2] in (
+        ArrowCTypes.STRING,
+        ArrowCTypes.LARGE_STRING,
+    )  # format_str == utf-8
+    # Convert the buffers to NumPy arrays. In order to go from STRING to
+    # an equivalent ndarray, we claim that the buffer is uint8 (i.e., a byte array)
+    data_dtype = (
+        DtypeKind.UINT,
+        8,
+        ArrowCTypes.UINT8,
+        Endianness.NATIVE,
+    )
+    # Specify zero offset as we don't want to chunk the string data
+    data = buffer_to_ndarray(data_buff, data_dtype, offset=0, length=data_buff.bufsize)
+
+    # Retrieve the offsets buffer containing the index offsets demarcating
+    # the beginning and the ending of each string
+    offset_buff, offset_dtype = buffers["offsets"]
+    # Offsets buffer contains start-stop positions of strings in the data buffer,
+    # meaning that it has more elements than in the data buffer, do `col.size() + 1`
+    # here to pass a proper offsets buffer size
+    offsets = buffer_to_ndarray(
+        offset_buff, offset_dtype, offset=col.offset, length=col.size() + 1
+    )
+
+    null_pos = None
+    if null_kind in (ColumnNullType.USE_BITMASK, ColumnNullType.USE_BYTEMASK):
+        validity = buffers["validity"]
+        if validity is not None:
+            valid_buff, valid_dtype = validity
+            null_pos = buffer_to_ndarray(
+                valid_buff, valid_dtype, offset=col.offset, length=col.size()
+            )
+            if sentinel_val == 0:
+                null_pos = ~null_pos
+
+    # Assemble the strings from the code units
+    str_list: list[None | float | str] = [None] * col.size()
+    for i in range(col.size()):
+        # Check for missing values
+        if null_pos is not None and null_pos[i]:
+            str_list[i] = np.nan
+            continue
+
+        # Extract a range of code units
+        units = data[offsets[i] : offsets[i + 1]]
+
+        # Convert the list of code units to bytes
+        str_bytes = bytes(units)
+
+        # Create the string
+        string = str_bytes.decode(encoding="utf-8")
+
+        # Add to our list of strings
+        str_list[i] = string
+
+    if using_string_dtype():
+        res = pd.Series(str_list, dtype="str")
+    else:
+        res = np.asarray(str_list, dtype="object")  # type: ignore[assignment]
+
+    return res, buffers  # type: ignore[return-value]
+
+
+def parse_datetime_format_str(format_str, data) -> pd.Series | np.ndarray:
+    """Parse datetime `format_str` to interpret the `data`."""
+    # timestamp 'ts{unit}:tz'
+    timestamp_meta = re.match(r"ts([smun]):(.*)", format_str)
+    if timestamp_meta:
+        unit, tz = timestamp_meta.group(1), timestamp_meta.group(2)
+        if unit != "s":
+            # the format string describes only a first letter of the unit, so
+            # add one extra letter to convert the unit to numpy-style:
+            # 'm' -> 'ms', 'u' -> 'us', 'n' -> 'ns'
+            unit += "s"
+        data = data.astype(f"datetime64[{unit}]")
+        if tz != "":
+            data = pd.Series(data).dt.tz_localize("UTC").dt.tz_convert(tz)
+        return data
+
+    # date 'td{Days/Ms}'
+    date_meta = re.match(r"td([Dm])", format_str)
+    if date_meta:
+        unit = date_meta.group(1)
+        if unit == "D":
+            # NumPy doesn't support DAY unit, so converting days to seconds
+            # (converting to uint64 to avoid overflow)
+            data = (data.astype(np.uint64) * (24 * 60 * 60)).astype("datetime64[s]")
+        elif unit == "m":
+            data = data.astype("datetime64[ms]")
+        else:
+            raise NotImplementedError(f"Date unit is not supported: {unit}")
+        return data
+
+    raise NotImplementedError(f"DateTime kind is not supported: {format_str}")
+
+
+def datetime_column_to_ndarray(col: Column) -> tuple[np.ndarray | pd.Series, Any]:
+    """
+    Convert a column holding DateTime data to a NumPy array.
+
+    Parameters
+    ----------
+    col : Column
+
+    Returns
+    -------
+    tuple
+        Tuple of np.ndarray holding the data and the memory owner object
+        that keeps the memory alive.
+    """
+    buffers = col.get_buffers()
+
+    _, col_bit_width, format_str, _ = col.dtype
+    dbuf, _ = buffers["data"]
+    # Consider dtype being `uint` to get number of units passed since the 01.01.1970
+
+    data = buffer_to_ndarray(
+        dbuf,
+        (
+            DtypeKind.INT,
+            col_bit_width,
+            getattr(ArrowCTypes, f"INT{col_bit_width}"),
+            Endianness.NATIVE,
+        ),
+        offset=col.offset,
+        length=col.size(),
+    )
+
+    data = parse_datetime_format_str(format_str, data)  # type: ignore[assignment]
+    data = set_nulls(data, col, buffers["validity"])
+    return data, buffers
+
+
+def buffer_to_ndarray(
+    buffer: Buffer,
+    dtype: tuple[DtypeKind, int, str, str],
+    *,
+    length: int,
+    offset: int = 0,
+) -> np.ndarray:
+    """
+    Build a NumPy array from the passed buffer.
+
+    Parameters
+    ----------
+    buffer : Buffer
+        Buffer to build a NumPy array from.
+    dtype : tuple
+        Data type of the buffer conforming protocol dtypes format.
+    offset : int, default: 0
+        Number of elements to offset from the start of the buffer.
+    length : int, optional
+        If the buffer is a bit-mask, specifies a number of bits to read
+        from the buffer. Has no effect otherwise.
+
+    Returns
+    -------
+    np.ndarray
+
+    Notes
+    -----
+    The returned array doesn't own the memory. The caller of this function is
+    responsible for keeping the memory owner object alive as long as
+    the returned NumPy array is being used.
+    """
+    kind, bit_width, _, _ = dtype
+
+    column_dtype = _NP_DTYPES.get(kind, {}).get(bit_width, None)
+    if column_dtype is None:
+        raise NotImplementedError(f"Conversion for {dtype} is not yet supported.")
+
+    # TODO: No DLPack yet, so need to construct a new ndarray from the data pointer
+    # and size in the buffer plus the dtype on the column. Use DLPack as NumPy supports
+    # it since https://github.com/numpy/numpy/pull/19083
+    ctypes_type = np.ctypeslib.as_ctypes_type(column_dtype)
+
+    if bit_width == 1:
+        assert length is not None, "`length` must be specified for a bit-mask buffer."
+        pa = import_optional_dependency("pyarrow")
+        arr = pa.BooleanArray.from_buffers(
+            pa.bool_(),
+            length,
+            [None, pa.foreign_buffer(buffer.ptr, length)],
+            offset=offset,
+        )
+        return np.asarray(arr)
+    else:
+        data_pointer = ctypes.cast(
+            buffer.ptr + (offset * bit_width // 8), ctypes.POINTER(ctypes_type)
+        )
+        if length > 0:
+            return np.ctypeslib.as_array(data_pointer, shape=(length,))
+        return np.array([], dtype=ctypes_type)
+
+
+def set_nulls(
+    data: np.ndarray | pd.Series,
+    col: Column,
+    validity: tuple[Buffer, tuple[DtypeKind, int, str, str]] | None,
+    allow_modify_inplace: bool = True,
+):
+    """
+    Set null values for the data according to the column null kind.
+
+    Parameters
+    ----------
+    data : np.ndarray or pd.Series
+        Data to set nulls in.
+    col : Column
+        Column object that describes the `data`.
+    validity : tuple(Buffer, dtype) or None
+        The return value of ``col.buffers()``. We do not access the ``col.buffers()``
+        here to not take the ownership of the memory of buffer objects.
+    allow_modify_inplace : bool, default: True
+        Whether to modify the `data` inplace when zero-copy is possible (True) or always
+        modify a copy of the `data` (False).
+
+    Returns
+    -------
+    np.ndarray or pd.Series
+        Data with the nulls being set.
+    """
+    if validity is None:
+        return data
+    null_kind, sentinel_val = col.describe_null
+    null_pos = None
+
+    if null_kind == ColumnNullType.USE_SENTINEL:
+        null_pos = pd.Series(data) == sentinel_val
+    elif null_kind in (ColumnNullType.USE_BITMASK, ColumnNullType.USE_BYTEMASK):
+        assert validity, "Expected to have a validity buffer for the mask"
+        valid_buff, valid_dtype = validity
+        null_pos = buffer_to_ndarray(
+            valid_buff, valid_dtype, offset=col.offset, length=col.size()
+        )
+        if sentinel_val == 0:
+            null_pos = ~null_pos
+    elif null_kind in (ColumnNullType.NON_NULLABLE, ColumnNullType.USE_NAN):
+        pass
+    else:
+        raise NotImplementedError(f"Null kind {null_kind} is not yet supported.")
+
+    if null_pos is not None and np.any(null_pos):
+        if not allow_modify_inplace:
+            data = data.copy()
+        try:
+            data[null_pos] = None
+        except TypeError:
+            # TypeError happens if the `data` dtype appears to be non-nullable
+            # in numpy notation (bool, int, uint). If this happens,
+            # cast the `data` to nullable float dtype.
+            data = data.astype(float)
+            data[null_pos] = None
+        except SettingWithCopyError:
+            # `SettingWithCopyError` may happen for datetime-like with missing values.
+            data = data.copy()
+            data[null_pos] = None
+
+    return data
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/interchange/utils.py b/.venv/lib/python3.13/site-packages/pandas/core/interchange/utils.py
new file mode 100644
index 0000000000000000000000000000000000000000..035a1f8abdbc5d07ccec000d38c3fc159ccf94b6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/interchange/utils.py
@@ -0,0 +1,183 @@
+"""
+Utility functions and objects for implementing the interchange API.
+"""
+
+from __future__ import annotations
+
+import typing
+
+import numpy as np
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+    DatetimeTZDtype,
+)
+
+import pandas as pd
+
+if typing.TYPE_CHECKING:
+    from pandas._typing import DtypeObj
+
+
+# Maps str(pyarrow.DataType) = C type format string
+# Currently, no pyarrow API for this
+PYARROW_CTYPES = {
+    "null": "n",
+    "bool": "b",
+    "uint8": "C",
+    "uint16": "S",
+    "uint32": "I",
+    "uint64": "L",
+    "int8": "c",
+    "int16": "S",
+    "int32": "i",
+    "int64": "l",
+    "halffloat": "e",  # float16
+    "float": "f",  # float32
+    "double": "g",  # float64
+    "string": "u",
+    "large_string": "U",
+    "binary": "z",
+    "time32[s]": "tts",
+    "time32[ms]": "ttm",
+    "time64[us]": "ttu",
+    "time64[ns]": "ttn",
+    "date32[day]": "tdD",
+    "date64[ms]": "tdm",
+    "timestamp[s]": "tss:",
+    "timestamp[ms]": "tsm:",
+    "timestamp[us]": "tsu:",
+    "timestamp[ns]": "tsn:",
+    "duration[s]": "tDs",
+    "duration[ms]": "tDm",
+    "duration[us]": "tDu",
+    "duration[ns]": "tDn",
+}
+
+
+class ArrowCTypes:
+    """
+    Enum for Apache Arrow C type format strings.
+
+    The Arrow C data interface:
+    https://arrow.apache.org/docs/format/CDataInterface.html#data-type-description-format-strings
+    """
+
+    NULL = "n"
+    BOOL = "b"
+    INT8 = "c"
+    UINT8 = "C"
+    INT16 = "s"
+    UINT16 = "S"
+    INT32 = "i"
+    UINT32 = "I"
+    INT64 = "l"
+    UINT64 = "L"
+    FLOAT16 = "e"
+    FLOAT32 = "f"
+    FLOAT64 = "g"
+    STRING = "u"  # utf-8
+    LARGE_STRING = "U"  # utf-8
+    DATE32 = "tdD"
+    DATE64 = "tdm"
+    # Resoulution:
+    #   - seconds -> 's'
+    #   - milliseconds -> 'm'
+    #   - microseconds -> 'u'
+    #   - nanoseconds -> 'n'
+    TIMESTAMP = "ts{resolution}:{tz}"
+    TIME = "tt{resolution}"
+
+
+class Endianness:
+    """Enum indicating the byte-order of a data-type."""
+
+    LITTLE = "<"
+    BIG = ">"
+    NATIVE = "="
+    NA = "|"
+
+
+def dtype_to_arrow_c_fmt(dtype: DtypeObj) -> str:
+    """
+    Represent pandas `dtype` as a format string in Apache Arrow C notation.
+
+    Parameters
+    ----------
+    dtype : np.dtype
+        Datatype of pandas DataFrame to represent.
+
+    Returns
+    -------
+    str
+        Format string in Apache Arrow C notation of the given `dtype`.
+    """
+    if isinstance(dtype, CategoricalDtype):
+        return ArrowCTypes.INT64
+    elif dtype == np.dtype("O"):
+        return ArrowCTypes.STRING
+    elif isinstance(dtype, ArrowDtype):
+        import pyarrow as pa
+
+        pa_type = dtype.pyarrow_dtype
+        if pa.types.is_decimal(pa_type):
+            return f"d:{pa_type.precision},{pa_type.scale}"
+        elif pa.types.is_timestamp(pa_type) and pa_type.tz is not None:
+            return f"ts{pa_type.unit[0]}:{pa_type.tz}"
+        format_str = PYARROW_CTYPES.get(str(pa_type), None)
+        if format_str is not None:
+            return format_str
+
+    format_str = getattr(ArrowCTypes, dtype.name.upper(), None)
+    if format_str is not None:
+        return format_str
+
+    if isinstance(dtype, pd.StringDtype):
+        # TODO(infer_string) this should be LARGE_STRING for pyarrow storage,
+        # but current tests don't cover this distinction
+        return ArrowCTypes.STRING
+
+    elif lib.is_np_dtype(dtype, "M"):
+        # Selecting the first char of resolution string:
+        # dtype.str -> ' 'n'
+        resolution = np.datetime_data(dtype)[0][0]
+        return ArrowCTypes.TIMESTAMP.format(resolution=resolution, tz="")
+
+    elif isinstance(dtype, DatetimeTZDtype):
+        return ArrowCTypes.TIMESTAMP.format(resolution=dtype.unit[0], tz=dtype.tz)
+
+    elif isinstance(dtype, pd.BooleanDtype):
+        return ArrowCTypes.BOOL
+
+    raise NotImplementedError(
+        f"Conversion of {dtype} to Arrow C format string is not implemented."
+    )
+
+
+def maybe_rechunk(series: pd.Series, *, allow_copy: bool) -> pd.Series | None:
+    """
+    Rechunk a multi-chunk pyarrow array into a single-chunk array, if necessary.
+
+    - Returns `None` if the input series is not backed by a multi-chunk pyarrow array
+      (and so doesn't need rechunking)
+    - Returns a single-chunk-backed-Series if the input is backed by a multi-chunk
+      pyarrow array and `allow_copy` is `True`.
+    - Raises a `RuntimeError` if `allow_copy` is `False` and input is a
+      based by a multi-chunk pyarrow array.
+    """
+    if not isinstance(series.dtype, pd.ArrowDtype):
+        return None
+    chunked_array = series.array._pa_array  # type: ignore[attr-defined]
+    if len(chunked_array.chunks) == 1:
+        return None
+    if not allow_copy:
+        raise RuntimeError(
+            "Found multi-chunk pyarrow array, but `allow_copy` is False. "
+            "Please rechunk the array before calling this function, or set "
+            "`allow_copy=True`."
+        )
+    arr = chunked_array.combine_chunks()
+    return pd.Series(arr, dtype=series.dtype, name=series.name, index=series.index)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..2eb413440ba9c1ef4c016cd874d19c2aba6d791e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/__init__.py
@@ -0,0 +1,85 @@
+from pandas.core.internals.api import make_block  # 2023-09-18 pyarrow uses this
+from pandas.core.internals.array_manager import (
+    ArrayManager,
+    SingleArrayManager,
+)
+from pandas.core.internals.base import (
+    DataManager,
+    SingleDataManager,
+)
+from pandas.core.internals.concat import concatenate_managers
+from pandas.core.internals.managers import (
+    BlockManager,
+    SingleBlockManager,
+)
+
+__all__ = [
+    "Block",  # pylint: disable=undefined-all-variable
+    "DatetimeTZBlock",  # pylint: disable=undefined-all-variable
+    "ExtensionBlock",  # pylint: disable=undefined-all-variable
+    "make_block",
+    "DataManager",
+    "ArrayManager",
+    "BlockManager",
+    "SingleDataManager",
+    "SingleBlockManager",
+    "SingleArrayManager",
+    "concatenate_managers",
+]
+
+
+def __getattr__(name: str):
+    # GH#55139
+    import warnings
+
+    if name == "create_block_manager_from_blocks":
+        # GH#33892
+        warnings.warn(
+            f"{name} is deprecated and will be removed in a future version. "
+            "Use public APIs instead.",
+            DeprecationWarning,
+            # https://github.com/pandas-dev/pandas/pull/55139#pullrequestreview-1720690758
+            # on hard-coding stacklevel
+            stacklevel=2,
+        )
+        from pandas.core.internals.managers import create_block_manager_from_blocks
+
+        return create_block_manager_from_blocks
+
+    if name in [
+        "NumericBlock",
+        "ObjectBlock",
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+    ]:
+        warnings.warn(
+            f"{name} is deprecated and will be removed in a future version. "
+            "Use public APIs instead.",
+            DeprecationWarning,
+            # https://github.com/pandas-dev/pandas/pull/55139#pullrequestreview-1720690758
+            # on hard-coding stacklevel
+            stacklevel=2,
+        )
+        if name == "NumericBlock":
+            from pandas.core.internals.blocks import NumericBlock
+
+            return NumericBlock
+        elif name == "DatetimeTZBlock":
+            from pandas.core.internals.blocks import DatetimeTZBlock
+
+            return DatetimeTZBlock
+        elif name == "ExtensionBlock":
+            from pandas.core.internals.blocks import ExtensionBlock
+
+            return ExtensionBlock
+        elif name == "Block":
+            from pandas.core.internals.blocks import Block
+
+            return Block
+        else:
+            from pandas.core.internals.blocks import ObjectBlock
+
+            return ObjectBlock
+
+    raise AttributeError(f"module 'pandas.core.internals' has no attribute '{name}'")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/api.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..b0b3937ca47ea06c42b4b51964f6a74830a5d9ee
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/api.py
@@ -0,0 +1,156 @@
+"""
+This is a pseudo-public API for downstream libraries.  We ask that downstream
+authors
+
+1) Try to avoid using internals directly altogether, and failing that,
+2) Use only functions exposed here (or in core.internals)
+
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs.internals import BlockPlacement
+
+from pandas.core.dtypes.common import pandas_dtype
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    PeriodDtype,
+)
+
+from pandas.core.arrays import DatetimeArray
+from pandas.core.construction import extract_array
+from pandas.core.internals.blocks import (
+    check_ndim,
+    ensure_block_shape,
+    extract_pandas_array,
+    get_block_type,
+    maybe_coerce_values,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import Dtype
+
+    from pandas.core.internals.blocks import Block
+
+
+def make_block(
+    values, placement, klass=None, ndim=None, dtype: Dtype | None = None
+) -> Block:
+    """
+    This is a pseudo-public analogue to blocks.new_block.
+
+    We ask that downstream libraries use this rather than any fully-internal
+    APIs, including but not limited to:
+
+    - core.internals.blocks.make_block
+    - Block.make_block
+    - Block.make_block_same_class
+    - Block.__init__
+    """
+    if dtype is not None:
+        dtype = pandas_dtype(dtype)
+
+    values, dtype = extract_pandas_array(values, dtype, ndim)
+
+    from pandas.core.internals.blocks import (
+        DatetimeTZBlock,
+        ExtensionBlock,
+    )
+
+    if klass is ExtensionBlock and isinstance(values.dtype, PeriodDtype):
+        # GH-44681 changed PeriodArray to be stored in the 2D
+        # NDArrayBackedExtensionBlock instead of ExtensionBlock
+        # -> still allow ExtensionBlock to be passed in this case for back compat
+        klass = None
+
+    if klass is None:
+        dtype = dtype or values.dtype
+        klass = get_block_type(dtype)
+
+    elif klass is DatetimeTZBlock and not isinstance(values.dtype, DatetimeTZDtype):
+        # pyarrow calls get here
+        values = DatetimeArray._simple_new(
+            # error: Argument "dtype" to "_simple_new" of "DatetimeArray" has
+            # incompatible type "Union[ExtensionDtype, dtype[Any], None]";
+            # expected "Union[dtype[datetime64], DatetimeTZDtype]"
+            values,
+            dtype=dtype,  # type: ignore[arg-type]
+        )
+
+    if not isinstance(placement, BlockPlacement):
+        placement = BlockPlacement(placement)
+
+    ndim = maybe_infer_ndim(values, placement, ndim)
+    if isinstance(values.dtype, (PeriodDtype, DatetimeTZDtype)):
+        # GH#41168 ensure we can pass 1D dt64tz values
+        # More generally, any EA dtype that isn't is_1d_only_ea_dtype
+        values = extract_array(values, extract_numpy=True)
+        values = ensure_block_shape(values, ndim)
+
+    check_ndim(values, placement, ndim)
+    values = maybe_coerce_values(values)
+    return klass(values, ndim=ndim, placement=placement)
+
+
+def maybe_infer_ndim(values, placement: BlockPlacement, ndim: int | None) -> int:
+    """
+    If `ndim` is not provided, infer it from placement and values.
+    """
+    if ndim is None:
+        # GH#38134 Block constructor now assumes ndim is not None
+        if not isinstance(values.dtype, np.dtype):
+            if len(placement) != 1:
+                ndim = 1
+            else:
+                ndim = 2
+        else:
+            ndim = values.ndim
+    return ndim
+
+
+def __getattr__(name: str):
+    # GH#55139
+    import warnings
+
+    if name in [
+        "Block",
+        "ExtensionBlock",
+        "DatetimeTZBlock",
+        "create_block_manager_from_blocks",
+    ]:
+        # GH#33892
+        warnings.warn(
+            f"{name} is deprecated and will be removed in a future version. "
+            "Use public APIs instead.",
+            DeprecationWarning,
+            # https://github.com/pandas-dev/pandas/pull/55139#pullrequestreview-1720690758
+            # on hard-coding stacklevel
+            stacklevel=2,
+        )
+
+        if name == "create_block_manager_from_blocks":
+            from pandas.core.internals.managers import create_block_manager_from_blocks
+
+            return create_block_manager_from_blocks
+
+        elif name == "Block":
+            from pandas.core.internals.blocks import Block
+
+            return Block
+
+        elif name == "DatetimeTZBlock":
+            from pandas.core.internals.blocks import DatetimeTZBlock
+
+            return DatetimeTZBlock
+
+        elif name == "ExtensionBlock":
+            from pandas.core.internals.blocks import ExtensionBlock
+
+            return ExtensionBlock
+
+    raise AttributeError(
+        f"module 'pandas.core.internals.api' has no attribute '{name}'"
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/array_manager.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/array_manager.py
new file mode 100644
index 0000000000000000000000000000000000000000..e253f82256a5f6dd8b277b576a33597355d69dcc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/array_manager.py
@@ -0,0 +1,1340 @@
+"""
+Experimental manager based on storing a collection of 1D arrays
+"""
+from __future__ import annotations
+
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    lib,
+)
+
+from pandas.core.dtypes.astype import (
+    astype_array,
+    astype_array_safe,
+)
+from pandas.core.dtypes.cast import (
+    ensure_dtype_can_hold_na,
+    find_common_type,
+    infer_dtype_from_scalar,
+    np_find_common_type,
+)
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_datetime64_ns_dtype,
+    is_integer,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_timedelta64_ns_dtype,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    array_equals,
+    isna,
+    na_value_for_dtype,
+)
+
+import pandas.core.algorithms as algos
+from pandas.core.array_algos.quantile import quantile_compat
+from pandas.core.array_algos.take import take_1d
+from pandas.core.arrays import (
+    DatetimeArray,
+    ExtensionArray,
+    NumpyExtensionArray,
+    TimedeltaArray,
+)
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+    sanitize_array,
+)
+from pandas.core.indexers import (
+    maybe_convert_indices,
+    validate_indices,
+)
+from pandas.core.indexes.api import (
+    Index,
+    ensure_index,
+)
+from pandas.core.indexes.base import get_values_for_csv
+from pandas.core.internals.base import (
+    DataManager,
+    SingleDataManager,
+    ensure_np_dtype,
+    interleaved_dtype,
+)
+from pandas.core.internals.blocks import (
+    BlockPlacement,
+    ensure_block_shape,
+    external_values,
+    extract_pandas_array,
+    maybe_coerce_values,
+    new_block,
+)
+from pandas.core.internals.managers import make_na_array
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        DtypeObj,
+        QuantileInterpolation,
+        Self,
+        npt,
+    )
+
+
+class BaseArrayManager(DataManager):
+    """
+    Core internal data structure to implement DataFrame and Series.
+
+    Alternative to the BlockManager, storing a list of 1D arrays instead of
+    Blocks.
+
+    This is *not* a public API class
+
+    Parameters
+    ----------
+    arrays : Sequence of arrays
+    axes : Sequence of Index
+    verify_integrity : bool, default True
+
+    """
+
+    __slots__ = [
+        "_axes",  # private attribute, because 'axes' has different order, see below
+        "arrays",
+    ]
+
+    arrays: list[np.ndarray | ExtensionArray]
+    _axes: list[Index]
+
+    def __init__(
+        self,
+        arrays: list[np.ndarray | ExtensionArray],
+        axes: list[Index],
+        verify_integrity: bool = True,
+    ) -> None:
+        raise NotImplementedError
+
+    def make_empty(self, axes=None) -> Self:
+        """Return an empty ArrayManager with the items axis of len 0 (no columns)"""
+        if axes is None:
+            axes = [self.axes[1:], Index([])]
+
+        arrays: list[np.ndarray | ExtensionArray] = []
+        return type(self)(arrays, axes)
+
+    @property
+    def items(self) -> Index:
+        return self._axes[-1]
+
+    @property
+    # error: Signature of "axes" incompatible with supertype "DataManager"
+    def axes(self) -> list[Index]:  # type: ignore[override]
+        # mypy doesn't work to override attribute with property
+        # see https://github.com/python/mypy/issues/4125
+        """Axes is BlockManager-compatible order (columns, rows)"""
+        return [self._axes[1], self._axes[0]]
+
+    @property
+    def shape_proper(self) -> tuple[int, ...]:
+        # this returns (n_rows, n_columns)
+        return tuple(len(ax) for ax in self._axes)
+
+    @staticmethod
+    def _normalize_axis(axis: AxisInt) -> int:
+        # switch axis
+        axis = 1 if axis == 0 else 0
+        return axis
+
+    def set_axis(self, axis: AxisInt, new_labels: Index) -> None:
+        # Caller is responsible for ensuring we have an Index object.
+        self._validate_set_axis(axis, new_labels)
+        axis = self._normalize_axis(axis)
+        self._axes[axis] = new_labels
+
+    def get_dtypes(self) -> npt.NDArray[np.object_]:
+        return np.array([arr.dtype for arr in self.arrays], dtype="object")
+
+    def add_references(self, mgr: BaseArrayManager) -> None:
+        """
+        Only implemented on the BlockManager level
+        """
+        return
+
+    def __getstate__(self):
+        return self.arrays, self._axes
+
+    def __setstate__(self, state) -> None:
+        self.arrays = state[0]
+        self._axes = state[1]
+
+    def __repr__(self) -> str:
+        output = type(self).__name__
+        output += f"\nIndex: {self._axes[0]}"
+        if self.ndim == 2:
+            output += f"\nColumns: {self._axes[1]}"
+        output += f"\n{len(self.arrays)} arrays:"
+        for arr in self.arrays:
+            output += f"\n{arr.dtype}"
+        return output
+
+    def apply(
+        self,
+        f,
+        align_keys: list[str] | None = None,
+        **kwargs,
+    ) -> Self:
+        """
+        Iterate over the arrays, collect and create a new ArrayManager.
+
+        Parameters
+        ----------
+        f : str or callable
+            Name of the Array method to apply.
+        align_keys: List[str] or None, default None
+        **kwargs
+            Keywords to pass to `f`
+
+        Returns
+        -------
+        ArrayManager
+        """
+        assert "filter" not in kwargs
+
+        align_keys = align_keys or []
+        result_arrays: list[ArrayLike] = []
+        # fillna: Series/DataFrame is responsible for making sure value is aligned
+
+        aligned_args = {k: kwargs[k] for k in align_keys}
+
+        if f == "apply":
+            f = kwargs.pop("func")
+
+        for i, arr in enumerate(self.arrays):
+            if aligned_args:
+                for k, obj in aligned_args.items():
+                    if isinstance(obj, (ABCSeries, ABCDataFrame)):
+                        # The caller is responsible for ensuring that
+                        #  obj.axes[-1].equals(self.items)
+                        if obj.ndim == 1:
+                            kwargs[k] = obj.iloc[i]
+                        else:
+                            kwargs[k] = obj.iloc[:, i]._values
+                    else:
+                        # otherwise we have an array-like
+                        kwargs[k] = obj[i]
+
+            if callable(f):
+                applied = f(arr, **kwargs)
+            else:
+                applied = getattr(arr, f)(**kwargs)
+
+            result_arrays.append(applied)
+
+        new_axes = self._axes
+        return type(self)(result_arrays, new_axes)
+
+    def apply_with_block(self, f, align_keys=None, **kwargs) -> Self:
+        # switch axis to follow BlockManager logic
+        swap_axis = True
+        if f == "interpolate":
+            swap_axis = False
+        if swap_axis and "axis" in kwargs and self.ndim == 2:
+            kwargs["axis"] = 1 if kwargs["axis"] == 0 else 0
+
+        align_keys = align_keys or []
+        aligned_args = {k: kwargs[k] for k in align_keys}
+
+        result_arrays = []
+
+        for i, arr in enumerate(self.arrays):
+            if aligned_args:
+                for k, obj in aligned_args.items():
+                    if isinstance(obj, (ABCSeries, ABCDataFrame)):
+                        # The caller is responsible for ensuring that
+                        #  obj.axes[-1].equals(self.items)
+                        if obj.ndim == 1:
+                            if self.ndim == 2:
+                                kwargs[k] = obj.iloc[slice(i, i + 1)]._values
+                            else:
+                                kwargs[k] = obj.iloc[:]._values
+                        else:
+                            kwargs[k] = obj.iloc[:, [i]]._values
+                    else:
+                        # otherwise we have an ndarray
+                        if obj.ndim == 2:
+                            kwargs[k] = obj[[i]]
+
+            if isinstance(arr.dtype, np.dtype) and not isinstance(arr, np.ndarray):
+                # i.e. TimedeltaArray, DatetimeArray with tz=None. Need to
+                #  convert for the Block constructors.
+                arr = np.asarray(arr)
+
+            arr = maybe_coerce_values(arr)
+            if self.ndim == 2:
+                arr = ensure_block_shape(arr, 2)
+                bp = BlockPlacement(slice(0, 1, 1))
+                block = new_block(arr, placement=bp, ndim=2)
+            else:
+                bp = BlockPlacement(slice(0, len(self), 1))
+                block = new_block(arr, placement=bp, ndim=1)
+
+            applied = getattr(block, f)(**kwargs)
+            if isinstance(applied, list):
+                applied = applied[0]
+            arr = applied.values
+            if self.ndim == 2 and arr.ndim == 2:
+                # 2D for np.ndarray or DatetimeArray/TimedeltaArray
+                assert len(arr) == 1
+                # error: No overload variant of "__getitem__" of "ExtensionArray"
+                # matches argument type "Tuple[int, slice]"
+                arr = arr[0, :]  # type: ignore[call-overload]
+            result_arrays.append(arr)
+
+        return type(self)(result_arrays, self._axes)
+
+    def setitem(self, indexer, value, warn: bool = True) -> Self:
+        return self.apply_with_block("setitem", indexer=indexer, value=value)
+
+    def diff(self, n: int) -> Self:
+        assert self.ndim == 2  # caller ensures
+        return self.apply(algos.diff, n=n)
+
+    def astype(self, dtype, copy: bool | None = False, errors: str = "raise") -> Self:
+        if copy is None:
+            copy = True
+
+        return self.apply(astype_array_safe, dtype=dtype, copy=copy, errors=errors)
+
+    def convert(self, copy: bool | None) -> Self:
+        if copy is None:
+            copy = True
+
+        def _convert(arr):
+            if is_object_dtype(arr.dtype):
+                # extract NumpyExtensionArray for tests that patch
+                #  NumpyExtensionArray._typ
+                arr = np.asarray(arr)
+                result = lib.maybe_convert_objects(
+                    arr,
+                    convert_non_numeric=True,
+                )
+                if result is arr and copy:
+                    return arr.copy()
+                return result
+            else:
+                return arr.copy() if copy else arr
+
+        return self.apply(_convert)
+
+    def get_values_for_csv(
+        self, *, float_format, date_format, decimal, na_rep: str = "nan", quoting=None
+    ) -> Self:
+        return self.apply(
+            get_values_for_csv,
+            na_rep=na_rep,
+            quoting=quoting,
+            float_format=float_format,
+            date_format=date_format,
+            decimal=decimal,
+        )
+
+    @property
+    def any_extension_types(self) -> bool:
+        """Whether any of the blocks in this manager are extension blocks"""
+        return False  # any(block.is_extension for block in self.blocks)
+
+    @property
+    def is_view(self) -> bool:
+        """return a boolean if we are a single block and are a view"""
+        # TODO what is this used for?
+        return False
+
+    @property
+    def is_single_block(self) -> bool:
+        return len(self.arrays) == 1
+
+    def _get_data_subset(self, predicate: Callable) -> Self:
+        indices = [i for i, arr in enumerate(self.arrays) if predicate(arr)]
+        arrays = [self.arrays[i] for i in indices]
+        # TODO copy?
+        # Note: using Index.take ensures we can retain e.g. DatetimeIndex.freq,
+        #  see test_describe_datetime_columns
+        taker = np.array(indices, dtype="intp")
+        new_cols = self._axes[1].take(taker)
+        new_axes = [self._axes[0], new_cols]
+        return type(self)(arrays, new_axes, verify_integrity=False)
+
+    def get_bool_data(self, copy: bool = False) -> Self:
+        """
+        Select columns that are bool-dtype and object-dtype columns that are all-bool.
+
+        Parameters
+        ----------
+        copy : bool, default False
+            Whether to copy the blocks
+        """
+        return self._get_data_subset(lambda x: x.dtype == np.dtype(bool))
+
+    def get_numeric_data(self, copy: bool = False) -> Self:
+        """
+        Select columns that have a numeric dtype.
+
+        Parameters
+        ----------
+        copy : bool, default False
+            Whether to copy the blocks
+        """
+        return self._get_data_subset(
+            lambda arr: is_numeric_dtype(arr.dtype)
+            or getattr(arr.dtype, "_is_numeric", False)
+        )
+
+    def copy(self, deep: bool | Literal["all"] | None = True) -> Self:
+        """
+        Make deep or shallow copy of ArrayManager
+
+        Parameters
+        ----------
+        deep : bool or string, default True
+            If False, return shallow copy (do not copy data)
+            If 'all', copy data and a deep copy of the index
+
+        Returns
+        -------
+        BlockManager
+        """
+        if deep is None:
+            # ArrayManager does not yet support CoW, so deep=None always means
+            # deep=True for now
+            deep = True
+
+        # this preserves the notion of view copying of axes
+        if deep:
+            # hit in e.g. tests.io.json.test_pandas
+
+            def copy_func(ax):
+                return ax.copy(deep=True) if deep == "all" else ax.view()
+
+            new_axes = [copy_func(ax) for ax in self._axes]
+        else:
+            new_axes = list(self._axes)
+
+        if deep:
+            new_arrays = [arr.copy() for arr in self.arrays]
+        else:
+            new_arrays = list(self.arrays)
+        return type(self)(new_arrays, new_axes, verify_integrity=False)
+
+    def reindex_indexer(
+        self,
+        new_axis,
+        indexer,
+        axis: AxisInt,
+        fill_value=None,
+        allow_dups: bool = False,
+        copy: bool | None = True,
+        # ignored keywords
+        only_slice: bool = False,
+        # ArrayManager specific keywords
+        use_na_proxy: bool = False,
+    ) -> Self:
+        axis = self._normalize_axis(axis)
+        return self._reindex_indexer(
+            new_axis,
+            indexer,
+            axis,
+            fill_value,
+            allow_dups,
+            copy,
+            use_na_proxy,
+        )
+
+    def _reindex_indexer(
+        self,
+        new_axis,
+        indexer: npt.NDArray[np.intp] | None,
+        axis: AxisInt,
+        fill_value=None,
+        allow_dups: bool = False,
+        copy: bool | None = True,
+        use_na_proxy: bool = False,
+    ) -> Self:
+        """
+        Parameters
+        ----------
+        new_axis : Index
+        indexer : ndarray[intp] or None
+        axis : int
+        fill_value : object, default None
+        allow_dups : bool, default False
+        copy : bool, default True
+
+
+        pandas-indexer with -1's only.
+        """
+        if copy is None:
+            # ArrayManager does not yet support CoW, so deep=None always means
+            # deep=True for now
+            copy = True
+
+        if indexer is None:
+            if new_axis is self._axes[axis] and not copy:
+                return self
+
+            result = self.copy(deep=copy)
+            result._axes = list(self._axes)
+            result._axes[axis] = new_axis
+            return result
+
+        # some axes don't allow reindexing with dups
+        if not allow_dups:
+            self._axes[axis]._validate_can_reindex(indexer)
+
+        if axis >= self.ndim:
+            raise IndexError("Requested axis not found in manager")
+
+        if axis == 1:
+            new_arrays = []
+            for i in indexer:
+                if i == -1:
+                    arr = self._make_na_array(
+                        fill_value=fill_value, use_na_proxy=use_na_proxy
+                    )
+                else:
+                    arr = self.arrays[i]
+                    if copy:
+                        arr = arr.copy()
+                new_arrays.append(arr)
+
+        else:
+            validate_indices(indexer, len(self._axes[0]))
+            indexer = ensure_platform_int(indexer)
+            mask = indexer == -1
+            needs_masking = mask.any()
+            new_arrays = [
+                take_1d(
+                    arr,
+                    indexer,
+                    allow_fill=needs_masking,
+                    fill_value=fill_value,
+                    mask=mask,
+                    # if fill_value is not None else blk.fill_value
+                )
+                for arr in self.arrays
+            ]
+
+        new_axes = list(self._axes)
+        new_axes[axis] = new_axis
+
+        return type(self)(new_arrays, new_axes, verify_integrity=False)
+
+    def take(
+        self,
+        indexer: npt.NDArray[np.intp],
+        axis: AxisInt = 1,
+        verify: bool = True,
+    ) -> Self:
+        """
+        Take items along any axis.
+        """
+        assert isinstance(indexer, np.ndarray), type(indexer)
+        assert indexer.dtype == np.intp, indexer.dtype
+
+        axis = self._normalize_axis(axis)
+
+        if not indexer.ndim == 1:
+            raise ValueError("indexer should be 1-dimensional")
+
+        n = self.shape_proper[axis]
+        indexer = maybe_convert_indices(indexer, n, verify=verify)
+
+        new_labels = self._axes[axis].take(indexer)
+        return self._reindex_indexer(
+            new_axis=new_labels, indexer=indexer, axis=axis, allow_dups=True
+        )
+
+    def _make_na_array(self, fill_value=None, use_na_proxy: bool = False):
+        if use_na_proxy:
+            assert fill_value is None
+            return NullArrayProxy(self.shape_proper[0])
+
+        if fill_value is None:
+            fill_value = np.nan
+
+        dtype, fill_value = infer_dtype_from_scalar(fill_value)
+        array_values = make_na_array(dtype, self.shape_proper[:1], fill_value)
+        return array_values
+
+    def _equal_values(self, other) -> bool:
+        """
+        Used in .equals defined in base class. Only check the column values
+        assuming shape and indexes have already been checked.
+        """
+        for left, right in zip(self.arrays, other.arrays):
+            if not array_equals(left, right):
+                return False
+        return True
+
+    # TODO
+    # to_dict
+
+
+class ArrayManager(BaseArrayManager):
+    @property
+    def ndim(self) -> Literal[2]:
+        return 2
+
+    def __init__(
+        self,
+        arrays: list[np.ndarray | ExtensionArray],
+        axes: list[Index],
+        verify_integrity: bool = True,
+    ) -> None:
+        # Note: we are storing the axes in "_axes" in the (row, columns) order
+        # which contrasts the order how it is stored in BlockManager
+        self._axes = axes
+        self.arrays = arrays
+
+        if verify_integrity:
+            self._axes = [ensure_index(ax) for ax in axes]
+            arrays = [extract_pandas_array(x, None, 1)[0] for x in arrays]
+            self.arrays = [maybe_coerce_values(arr) for arr in arrays]
+            self._verify_integrity()
+
+    def _verify_integrity(self) -> None:
+        n_rows, n_columns = self.shape_proper
+        if not len(self.arrays) == n_columns:
+            raise ValueError(
+                "Number of passed arrays must equal the size of the column Index: "
+                f"{len(self.arrays)} arrays vs {n_columns} columns."
+            )
+        for arr in self.arrays:
+            if not len(arr) == n_rows:
+                raise ValueError(
+                    "Passed arrays should have the same length as the rows Index: "
+                    f"{len(arr)} vs {n_rows} rows"
+                )
+            if not isinstance(arr, (np.ndarray, ExtensionArray)):
+                raise ValueError(
+                    "Passed arrays should be np.ndarray or ExtensionArray instances, "
+                    f"got {type(arr)} instead"
+                )
+            if not arr.ndim == 1:
+                raise ValueError(
+                    "Passed arrays should be 1-dimensional, got array with "
+                    f"{arr.ndim} dimensions instead."
+                )
+
+    # --------------------------------------------------------------------
+    # Indexing
+
+    def fast_xs(self, loc: int) -> SingleArrayManager:
+        """
+        Return the array corresponding to `frame.iloc[loc]`.
+
+        Parameters
+        ----------
+        loc : int
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+        """
+        dtype = interleaved_dtype([arr.dtype for arr in self.arrays])
+
+        values = [arr[loc] for arr in self.arrays]
+        if isinstance(dtype, ExtensionDtype):
+            result = dtype.construct_array_type()._from_sequence(values, dtype=dtype)
+        # for datetime64/timedelta64, the np.ndarray constructor cannot handle pd.NaT
+        elif is_datetime64_ns_dtype(dtype):
+            result = DatetimeArray._from_sequence(values, dtype=dtype)._ndarray
+        elif is_timedelta64_ns_dtype(dtype):
+            result = TimedeltaArray._from_sequence(values, dtype=dtype)._ndarray
+        else:
+            result = np.array(values, dtype=dtype)
+        return SingleArrayManager([result], [self._axes[1]])
+
+    def get_slice(self, slobj: slice, axis: AxisInt = 0) -> ArrayManager:
+        axis = self._normalize_axis(axis)
+
+        if axis == 0:
+            arrays = [arr[slobj] for arr in self.arrays]
+        elif axis == 1:
+            arrays = self.arrays[slobj]
+
+        new_axes = list(self._axes)
+        new_axes[axis] = new_axes[axis]._getitem_slice(slobj)
+
+        return type(self)(arrays, new_axes, verify_integrity=False)
+
+    def iget(self, i: int) -> SingleArrayManager:
+        """
+        Return the data as a SingleArrayManager.
+        """
+        values = self.arrays[i]
+        return SingleArrayManager([values], [self._axes[0]])
+
+    def iget_values(self, i: int) -> ArrayLike:
+        """
+        Return the data for column i as the values (ndarray or ExtensionArray).
+        """
+        return self.arrays[i]
+
+    @property
+    def column_arrays(self) -> list[ArrayLike]:
+        """
+        Used in the JSON C code to access column arrays.
+        """
+
+        return [np.asarray(arr) for arr in self.arrays]
+
+    def iset(
+        self,
+        loc: int | slice | np.ndarray,
+        value: ArrayLike,
+        inplace: bool = False,
+        refs=None,
+    ) -> None:
+        """
+        Set new column(s).
+
+        This changes the ArrayManager in-place, but replaces (an) existing
+        column(s), not changing column values in-place).
+
+        Parameters
+        ----------
+        loc : integer, slice or boolean mask
+            Positional location (already bounds checked)
+        value : np.ndarray or ExtensionArray
+        inplace : bool, default False
+            Whether overwrite existing array as opposed to replacing it.
+        """
+        # single column -> single integer index
+        if lib.is_integer(loc):
+            # TODO can we avoid needing to unpack this here? That means converting
+            # DataFrame into 1D array when loc is an integer
+            if isinstance(value, np.ndarray) and value.ndim == 2:
+                assert value.shape[1] == 1
+                value = value[:, 0]
+
+            # TODO we receive a datetime/timedelta64 ndarray from DataFrame._iset_item
+            # but we should avoid that and pass directly the proper array
+            value = maybe_coerce_values(value)
+
+            assert isinstance(value, (np.ndarray, ExtensionArray))
+            assert value.ndim == 1
+            assert len(value) == len(self._axes[0])
+            self.arrays[loc] = value
+            return
+
+        # multiple columns -> convert slice or array to integer indices
+        elif isinstance(loc, slice):
+            indices: range | np.ndarray = range(
+                loc.start if loc.start is not None else 0,
+                loc.stop if loc.stop is not None else self.shape_proper[1],
+                loc.step if loc.step is not None else 1,
+            )
+        else:
+            assert isinstance(loc, np.ndarray)
+            assert loc.dtype == "bool"
+            indices = np.nonzero(loc)[0]
+
+        assert value.ndim == 2
+        assert value.shape[0] == len(self._axes[0])
+
+        for value_idx, mgr_idx in enumerate(indices):
+            # error: No overload variant of "__getitem__" of "ExtensionArray" matches
+            # argument type "Tuple[slice, int]"
+            value_arr = value[:, value_idx]  # type: ignore[call-overload]
+            self.arrays[mgr_idx] = value_arr
+        return
+
+    def column_setitem(
+        self, loc: int, idx: int | slice | np.ndarray, value, inplace_only: bool = False
+    ) -> None:
+        """
+        Set values ("setitem") into a single column (not setting the full column).
+
+        This is a method on the ArrayManager level, to avoid creating an
+        intermediate Series at the DataFrame level (`s = df[loc]; s[idx] = value`)
+        """
+        if not is_integer(loc):
+            raise TypeError("The column index should be an integer")
+        arr = self.arrays[loc]
+        mgr = SingleArrayManager([arr], [self._axes[0]])
+        if inplace_only:
+            mgr.setitem_inplace(idx, value)
+        else:
+            new_mgr = mgr.setitem((idx,), value)
+            # update existing ArrayManager in-place
+            self.arrays[loc] = new_mgr.arrays[0]
+
+    def insert(self, loc: int, item: Hashable, value: ArrayLike, refs=None) -> None:
+        """
+        Insert item at selected position.
+
+        Parameters
+        ----------
+        loc : int
+        item : hashable
+        value : np.ndarray or ExtensionArray
+        """
+        # insert to the axis; this could possibly raise a TypeError
+        new_axis = self.items.insert(loc, item)
+
+        value = extract_array(value, extract_numpy=True)
+        if value.ndim == 2:
+            if value.shape[0] == 1:
+                # error: No overload variant of "__getitem__" of "ExtensionArray"
+                # matches argument type "Tuple[int, slice]"
+                value = value[0, :]  # type: ignore[call-overload]
+            else:
+                raise ValueError(
+                    f"Expected a 1D array, got an array with shape {value.shape}"
+                )
+        value = maybe_coerce_values(value)
+
+        # TODO self.arrays can be empty
+        # assert len(value) == len(self.arrays[0])
+
+        # TODO is this copy needed?
+        arrays = self.arrays.copy()
+        arrays.insert(loc, value)
+
+        self.arrays = arrays
+        self._axes[1] = new_axis
+
+    def idelete(self, indexer) -> ArrayManager:
+        """
+        Delete selected locations in-place (new block and array, same BlockManager)
+        """
+        to_keep = np.ones(self.shape[0], dtype=np.bool_)
+        to_keep[indexer] = False
+
+        self.arrays = [self.arrays[i] for i in np.nonzero(to_keep)[0]]
+        self._axes = [self._axes[0], self._axes[1][to_keep]]
+        return self
+
+    # --------------------------------------------------------------------
+    # Array-wise Operation
+
+    def grouped_reduce(self, func: Callable) -> Self:
+        """
+        Apply grouped reduction function columnwise, returning a new ArrayManager.
+
+        Parameters
+        ----------
+        func : grouped reduction function
+
+        Returns
+        -------
+        ArrayManager
+        """
+        result_arrays: list[np.ndarray] = []
+        result_indices: list[int] = []
+
+        for i, arr in enumerate(self.arrays):
+            # grouped_reduce functions all expect 2D arrays
+            arr = ensure_block_shape(arr, ndim=2)
+            res = func(arr)
+            if res.ndim == 2:
+                # reverse of ensure_block_shape
+                assert res.shape[0] == 1
+                res = res[0]
+
+            result_arrays.append(res)
+            result_indices.append(i)
+
+        if len(result_arrays) == 0:
+            nrows = 0
+        else:
+            nrows = result_arrays[0].shape[0]
+        index = Index(range(nrows))
+
+        columns = self.items
+
+        # error: Argument 1 to "ArrayManager" has incompatible type "List[ndarray]";
+        # expected "List[Union[ndarray, ExtensionArray]]"
+        return type(self)(result_arrays, [index, columns])  # type: ignore[arg-type]
+
+    def reduce(self, func: Callable) -> Self:
+        """
+        Apply reduction function column-wise, returning a single-row ArrayManager.
+
+        Parameters
+        ----------
+        func : reduction function
+
+        Returns
+        -------
+        ArrayManager
+        """
+        result_arrays: list[np.ndarray] = []
+        for i, arr in enumerate(self.arrays):
+            res = func(arr, axis=0)
+
+            # TODO NaT doesn't preserve dtype, so we need to ensure to create
+            # a timedelta result array if original was timedelta
+            # what if datetime results in timedelta? (eg std)
+            dtype = arr.dtype if res is NaT else None
+            result_arrays.append(
+                sanitize_array([res], None, dtype=dtype)  # type: ignore[arg-type]
+            )
+
+        index = Index._simple_new(np.array([None], dtype=object))  # placeholder
+        columns = self.items
+
+        # error: Argument 1 to "ArrayManager" has incompatible type "List[ndarray]";
+        # expected "List[Union[ndarray, ExtensionArray]]"
+        new_mgr = type(self)(result_arrays, [index, columns])  # type: ignore[arg-type]
+        return new_mgr
+
+    def operate_blockwise(self, other: ArrayManager, array_op) -> ArrayManager:
+        """
+        Apply array_op blockwise with another (aligned) BlockManager.
+        """
+        # TODO what if `other` is BlockManager ?
+        left_arrays = self.arrays
+        right_arrays = other.arrays
+        result_arrays = [
+            array_op(left, right) for left, right in zip(left_arrays, right_arrays)
+        ]
+        return type(self)(result_arrays, self._axes)
+
+    def quantile(
+        self,
+        *,
+        qs: Index,  # with dtype float64
+        transposed: bool = False,
+        interpolation: QuantileInterpolation = "linear",
+    ) -> ArrayManager:
+        arrs = [ensure_block_shape(x, 2) for x in self.arrays]
+        new_arrs = [
+            quantile_compat(x, np.asarray(qs._values), interpolation) for x in arrs
+        ]
+        for i, arr in enumerate(new_arrs):
+            if arr.ndim == 2:
+                assert arr.shape[0] == 1, arr.shape
+                new_arrs[i] = arr[0]
+
+        axes = [qs, self._axes[1]]
+        return type(self)(new_arrs, axes)
+
+    # ----------------------------------------------------------------
+
+    def unstack(self, unstacker, fill_value) -> ArrayManager:
+        """
+        Return a BlockManager with all blocks unstacked.
+
+        Parameters
+        ----------
+        unstacker : reshape._Unstacker
+        fill_value : Any
+            fill_value for newly introduced missing values.
+
+        Returns
+        -------
+        unstacked : BlockManager
+        """
+        indexer, _ = unstacker._indexer_and_to_sort
+        if unstacker.mask.all():
+            new_indexer = indexer
+            allow_fill = False
+            new_mask2D = None
+            needs_masking = None
+        else:
+            new_indexer = np.full(unstacker.mask.shape, -1)
+            new_indexer[unstacker.mask] = indexer
+            allow_fill = True
+            # calculating the full mask once and passing it to take_1d is faster
+            # than letting take_1d calculate it in each repeated call
+            new_mask2D = (~unstacker.mask).reshape(*unstacker.full_shape)
+            needs_masking = new_mask2D.any(axis=0)
+        new_indexer2D = new_indexer.reshape(*unstacker.full_shape)
+        new_indexer2D = ensure_platform_int(new_indexer2D)
+
+        new_arrays = []
+        for arr in self.arrays:
+            for i in range(unstacker.full_shape[1]):
+                if allow_fill:
+                    # error: Value of type "Optional[Any]" is not indexable  [index]
+                    new_arr = take_1d(
+                        arr,
+                        new_indexer2D[:, i],
+                        allow_fill=needs_masking[i],  # type: ignore[index]
+                        fill_value=fill_value,
+                        mask=new_mask2D[:, i],  # type: ignore[index]
+                    )
+                else:
+                    new_arr = take_1d(arr, new_indexer2D[:, i], allow_fill=False)
+                new_arrays.append(new_arr)
+
+        new_index = unstacker.new_index
+        new_columns = unstacker.get_new_columns(self._axes[1])
+        new_axes = [new_index, new_columns]
+
+        return type(self)(new_arrays, new_axes, verify_integrity=False)
+
+    def as_array(
+        self,
+        dtype=None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Convert the blockmanager data into an numpy array.
+
+        Parameters
+        ----------
+        dtype : object, default None
+            Data type of the return array.
+        copy : bool, default False
+            If True then guarantee that a copy is returned. A value of
+            False does not guarantee that the underlying data is not
+            copied.
+        na_value : object, default lib.no_default
+            Value to be used as the missing value sentinel.
+
+        Returns
+        -------
+        arr : ndarray
+        """
+        if len(self.arrays) == 0:
+            empty_arr = np.empty(self.shape, dtype=float)
+            return empty_arr.transpose()
+
+        # We want to copy when na_value is provided to avoid
+        # mutating the original object
+        copy = copy or na_value is not lib.no_default
+
+        if not dtype:
+            dtype = interleaved_dtype([arr.dtype for arr in self.arrays])
+
+        dtype = ensure_np_dtype(dtype)
+
+        result = np.empty(self.shape_proper, dtype=dtype)
+
+        for i, arr in enumerate(self.arrays):
+            arr = arr.astype(dtype, copy=copy)
+            result[:, i] = arr
+
+        if na_value is not lib.no_default:
+            result[isna(result)] = na_value
+
+        return result
+
+    @classmethod
+    def concat_horizontal(cls, mgrs: list[Self], axes: list[Index]) -> Self:
+        """
+        Concatenate uniformly-indexed ArrayManagers horizontally.
+        """
+        # concatting along the columns -> combine reindexed arrays in a single manager
+        arrays = list(itertools.chain.from_iterable([mgr.arrays for mgr in mgrs]))
+        new_mgr = cls(arrays, [axes[1], axes[0]], verify_integrity=False)
+        return new_mgr
+
+    @classmethod
+    def concat_vertical(cls, mgrs: list[Self], axes: list[Index]) -> Self:
+        """
+        Concatenate uniformly-indexed ArrayManagers vertically.
+        """
+        # concatting along the rows -> concat the reindexed arrays
+        # TODO(ArrayManager) doesn't yet preserve the correct dtype
+        arrays = [
+            concat_arrays([mgrs[i].arrays[j] for i in range(len(mgrs))])
+            for j in range(len(mgrs[0].arrays))
+        ]
+        new_mgr = cls(arrays, [axes[1], axes[0]], verify_integrity=False)
+        return new_mgr
+
+
+class SingleArrayManager(BaseArrayManager, SingleDataManager):
+    __slots__ = [
+        "_axes",  # private attribute, because 'axes' has different order, see below
+        "arrays",
+    ]
+
+    arrays: list[np.ndarray | ExtensionArray]
+    _axes: list[Index]
+
+    @property
+    def ndim(self) -> Literal[1]:
+        return 1
+
+    def __init__(
+        self,
+        arrays: list[np.ndarray | ExtensionArray],
+        axes: list[Index],
+        verify_integrity: bool = True,
+    ) -> None:
+        self._axes = axes
+        self.arrays = arrays
+
+        if verify_integrity:
+            assert len(axes) == 1
+            assert len(arrays) == 1
+            self._axes = [ensure_index(ax) for ax in self._axes]
+            arr = arrays[0]
+            arr = maybe_coerce_values(arr)
+            arr = extract_pandas_array(arr, None, 1)[0]
+            self.arrays = [arr]
+            self._verify_integrity()
+
+    def _verify_integrity(self) -> None:
+        (n_rows,) = self.shape
+        assert len(self.arrays) == 1
+        arr = self.arrays[0]
+        assert len(arr) == n_rows
+        if not arr.ndim == 1:
+            raise ValueError(
+                "Passed array should be 1-dimensional, got array with "
+                f"{arr.ndim} dimensions instead."
+            )
+
+    @staticmethod
+    def _normalize_axis(axis):
+        return axis
+
+    def make_empty(self, axes=None) -> Self:
+        """Return an empty ArrayManager with index/array of length 0"""
+        if axes is None:
+            axes = [Index([], dtype=object)]
+        array: np.ndarray = np.array([], dtype=self.dtype)
+        return type(self)([array], axes)
+
+    @classmethod
+    def from_array(cls, array, index) -> SingleArrayManager:
+        return cls([array], [index])
+
+    # error: Cannot override writeable attribute with read-only property
+    @property
+    def axes(self) -> list[Index]:  # type: ignore[override]
+        return self._axes
+
+    @property
+    def index(self) -> Index:
+        return self._axes[0]
+
+    @property
+    def dtype(self):
+        return self.array.dtype
+
+    def external_values(self):
+        """The array that Series.values returns"""
+        return external_values(self.array)
+
+    def internal_values(self):
+        """The array that Series._values returns"""
+        return self.array
+
+    def array_values(self):
+        """The array that Series.array returns"""
+        arr = self.array
+        if isinstance(arr, np.ndarray):
+            arr = NumpyExtensionArray(arr)
+        return arr
+
+    @property
+    def _can_hold_na(self) -> bool:
+        if isinstance(self.array, np.ndarray):
+            return self.array.dtype.kind not in "iub"
+        else:
+            # ExtensionArray
+            return self.array._can_hold_na
+
+    @property
+    def is_single_block(self) -> bool:
+        return True
+
+    def fast_xs(self, loc: int) -> SingleArrayManager:
+        raise NotImplementedError("Use series._values[loc] instead")
+
+    def get_slice(self, slobj: slice, axis: AxisInt = 0) -> SingleArrayManager:
+        if axis >= self.ndim:
+            raise IndexError("Requested axis not found in manager")
+
+        new_array = self.array[slobj]
+        new_index = self.index._getitem_slice(slobj)
+        return type(self)([new_array], [new_index], verify_integrity=False)
+
+    def get_rows_with_mask(self, indexer: npt.NDArray[np.bool_]) -> SingleArrayManager:
+        new_array = self.array[indexer]
+        new_index = self.index[indexer]
+        return type(self)([new_array], [new_index])
+
+    # error: Signature of "apply" incompatible with supertype "BaseArrayManager"
+    def apply(self, func, **kwargs) -> Self:  # type: ignore[override]
+        if callable(func):
+            new_array = func(self.array, **kwargs)
+        else:
+            new_array = getattr(self.array, func)(**kwargs)
+        return type(self)([new_array], self._axes)
+
+    def setitem(self, indexer, value, warn: bool = True) -> SingleArrayManager:
+        """
+        Set values with indexer.
+
+        For SingleArrayManager, this backs s[indexer] = value
+
+        See `setitem_inplace` for a version that works inplace and doesn't
+        return a new Manager.
+        """
+        if isinstance(indexer, np.ndarray) and indexer.ndim > self.ndim:
+            raise ValueError(f"Cannot set values with ndim > {self.ndim}")
+        return self.apply_with_block("setitem", indexer=indexer, value=value)
+
+    def idelete(self, indexer) -> SingleArrayManager:
+        """
+        Delete selected locations in-place (new array, same ArrayManager)
+        """
+        to_keep = np.ones(self.shape[0], dtype=np.bool_)
+        to_keep[indexer] = False
+
+        self.arrays = [self.arrays[0][to_keep]]
+        self._axes = [self._axes[0][to_keep]]
+        return self
+
+    def _get_data_subset(self, predicate: Callable) -> SingleArrayManager:
+        # used in get_numeric_data / get_bool_data
+        if predicate(self.array):
+            return type(self)(self.arrays, self._axes, verify_integrity=False)
+        else:
+            return self.make_empty()
+
+    def set_values(self, values: ArrayLike) -> None:
+        """
+        Set (replace) the values of the SingleArrayManager in place.
+
+        Use at your own risk! This does not check if the passed values are
+        valid for the current SingleArrayManager (length, dtype, etc).
+        """
+        self.arrays[0] = values
+
+    def to_2d_mgr(self, columns: Index) -> ArrayManager:
+        """
+        Manager analogue of Series.to_frame
+        """
+        arrays = [self.arrays[0]]
+        axes = [self.axes[0], columns]
+
+        return ArrayManager(arrays, axes, verify_integrity=False)
+
+
+class NullArrayProxy:
+    """
+    Proxy object for an all-NA array.
+
+    Only stores the length of the array, and not the dtype. The dtype
+    will only be known when actually concatenating (after determining the
+    common dtype, for which this proxy is ignored).
+    Using this object avoids that the internals/concat.py needs to determine
+    the proper dtype and array type.
+    """
+
+    ndim = 1
+
+    def __init__(self, n: int) -> None:
+        self.n = n
+
+    @property
+    def shape(self) -> tuple[int]:
+        return (self.n,)
+
+    def to_array(self, dtype: DtypeObj) -> ArrayLike:
+        """
+        Helper function to create the actual all-NA array from the NullArrayProxy
+        object.
+
+        Parameters
+        ----------
+        arr : NullArrayProxy
+        dtype : the dtype for the resulting array
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+        """
+        if isinstance(dtype, ExtensionDtype):
+            empty = dtype.construct_array_type()._from_sequence([], dtype=dtype)
+            indexer = -np.ones(self.n, dtype=np.intp)
+            return empty.take(indexer, allow_fill=True)
+        else:
+            # when introducing missing values, int becomes float, bool becomes object
+            dtype = ensure_dtype_can_hold_na(dtype)
+            fill_value = na_value_for_dtype(dtype)
+            arr = np.empty(self.n, dtype=dtype)
+            arr.fill(fill_value)
+            return ensure_wrapped_if_datetimelike(arr)
+
+
+def concat_arrays(to_concat: list) -> ArrayLike:
+    """
+    Alternative for concat_compat but specialized for use in the ArrayManager.
+
+    Differences: only deals with 1D arrays (no axis keyword), assumes
+    ensure_wrapped_if_datetimelike and does not skip empty arrays to determine
+    the dtype.
+    In addition ensures that all NullArrayProxies get replaced with actual
+    arrays.
+
+    Parameters
+    ----------
+    to_concat : list of arrays
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    # ignore the all-NA proxies to determine the resulting dtype
+    to_concat_no_proxy = [x for x in to_concat if not isinstance(x, NullArrayProxy)]
+
+    dtypes = {x.dtype for x in to_concat_no_proxy}
+    single_dtype = len(dtypes) == 1
+
+    if single_dtype:
+        target_dtype = to_concat_no_proxy[0].dtype
+    elif all(lib.is_np_dtype(x, "iub") for x in dtypes):
+        # GH#42092
+        target_dtype = np_find_common_type(*dtypes)
+    else:
+        target_dtype = find_common_type([arr.dtype for arr in to_concat_no_proxy])
+
+    to_concat = [
+        arr.to_array(target_dtype)
+        if isinstance(arr, NullArrayProxy)
+        else astype_array(arr, target_dtype, copy=False)
+        for arr in to_concat
+    ]
+
+    if isinstance(to_concat[0], ExtensionArray):
+        cls = type(to_concat[0])
+        return cls._concat_same_type(to_concat)
+
+    result = np.concatenate(to_concat)
+
+    # TODO decide on exact behaviour (we shouldn't do this only for empty result)
+    # see https://github.com/pandas-dev/pandas/issues/39817
+    if len(result) == 0:
+        # all empties -> check for bool to not coerce to float
+        kinds = {obj.dtype.kind for obj in to_concat_no_proxy}
+        if len(kinds) != 1:
+            if "b" in kinds:
+                result = result.astype(object)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/base.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..ae91f167205a0628c4bcf9b61ce58e888fe6ec8e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/base.py
@@ -0,0 +1,407 @@
+"""
+Base class for the internal managers. Both BlockManager and ArrayManager
+inherit from this class.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+    final,
+)
+
+import numpy as np
+
+from pandas._config import (
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs import (
+    algos as libalgos,
+    lib,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._validators import validate_bool_kwarg
+
+from pandas.core.dtypes.cast import (
+    find_common_type,
+    np_can_hold_element,
+)
+from pandas.core.dtypes.dtypes import (
+    ExtensionDtype,
+    SparseDtype,
+)
+
+from pandas.core.base import PandasObject
+from pandas.core.construction import extract_array
+from pandas.core.indexes.api import (
+    Index,
+    default_index,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        DtypeObj,
+        Self,
+        Shape,
+    )
+
+
+class _AlreadyWarned:
+    def __init__(self):
+        # This class is used on the manager level to the block level to
+        # ensure that we warn only once. The block method can update the
+        # warned_already option without returning a value to keep the
+        # interface consistent. This is only a temporary solution for
+        # CoW warnings.
+        self.warned_already = False
+
+
+class DataManager(PandasObject):
+    # TODO share more methods/attributes
+
+    axes: list[Index]
+
+    @property
+    def items(self) -> Index:
+        raise AbstractMethodError(self)
+
+    @final
+    def __len__(self) -> int:
+        return len(self.items)
+
+    @property
+    def ndim(self) -> int:
+        return len(self.axes)
+
+    @property
+    def shape(self) -> Shape:
+        return tuple(len(ax) for ax in self.axes)
+
+    @final
+    def _validate_set_axis(self, axis: AxisInt, new_labels: Index) -> None:
+        # Caller is responsible for ensuring we have an Index object.
+        old_len = len(self.axes[axis])
+        new_len = len(new_labels)
+
+        if axis == 1 and len(self.items) == 0:
+            # If we are setting the index on a DataFrame with no columns,
+            #  it is OK to change the length.
+            pass
+
+        elif new_len != old_len:
+            raise ValueError(
+                f"Length mismatch: Expected axis has {old_len} elements, new "
+                f"values have {new_len} elements"
+            )
+
+    def reindex_indexer(
+        self,
+        new_axis,
+        indexer,
+        axis: AxisInt,
+        fill_value=None,
+        allow_dups: bool = False,
+        copy: bool = True,
+        only_slice: bool = False,
+    ) -> Self:
+        raise AbstractMethodError(self)
+
+    @final
+    def reindex_axis(
+        self,
+        new_index: Index,
+        axis: AxisInt,
+        fill_value=None,
+        only_slice: bool = False,
+    ) -> Self:
+        """
+        Conform data manager to new index.
+        """
+        new_index, indexer = self.axes[axis].reindex(new_index)
+
+        return self.reindex_indexer(
+            new_index,
+            indexer,
+            axis=axis,
+            fill_value=fill_value,
+            copy=False,
+            only_slice=only_slice,
+        )
+
+    def _equal_values(self, other: Self) -> bool:
+        """
+        To be implemented by the subclasses. Only check the column values
+        assuming shape and indexes have already been checked.
+        """
+        raise AbstractMethodError(self)
+
+    @final
+    def equals(self, other: object) -> bool:
+        """
+        Implementation for DataFrame.equals
+        """
+        if not isinstance(other, type(self)):
+            return False
+
+        self_axes, other_axes = self.axes, other.axes
+        if len(self_axes) != len(other_axes):
+            return False
+        if not all(ax1.equals(ax2) for ax1, ax2 in zip(self_axes, other_axes)):
+            return False
+
+        return self._equal_values(other)
+
+    def apply(
+        self,
+        f,
+        align_keys: list[str] | None = None,
+        **kwargs,
+    ) -> Self:
+        raise AbstractMethodError(self)
+
+    def apply_with_block(
+        self,
+        f,
+        align_keys: list[str] | None = None,
+        **kwargs,
+    ) -> Self:
+        raise AbstractMethodError(self)
+
+    @final
+    def isna(self, func) -> Self:
+        return self.apply("apply", func=func)
+
+    @final
+    def fillna(self, value, limit: int | None, inplace: bool, downcast) -> Self:
+        if limit is not None:
+            # Do this validation even if we go through one of the no-op paths
+            limit = libalgos.validate_limit(None, limit=limit)
+
+        return self.apply_with_block(
+            "fillna",
+            value=value,
+            limit=limit,
+            inplace=inplace,
+            downcast=downcast,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+
+    @final
+    def where(self, other, cond, align: bool) -> Self:
+        if align:
+            align_keys = ["other", "cond"]
+        else:
+            align_keys = ["cond"]
+            other = extract_array(other, extract_numpy=True)
+
+        return self.apply_with_block(
+            "where",
+            align_keys=align_keys,
+            other=other,
+            cond=cond,
+            using_cow=using_copy_on_write(),
+        )
+
+    @final
+    def putmask(self, mask, new, align: bool = True, warn: bool = True) -> Self:
+        if align:
+            align_keys = ["new", "mask"]
+        else:
+            align_keys = ["mask"]
+            new = extract_array(new, extract_numpy=True)
+
+        already_warned = None
+        if warn_copy_on_write():
+            already_warned = _AlreadyWarned()
+            if not warn:
+                already_warned.warned_already = True
+
+        return self.apply_with_block(
+            "putmask",
+            align_keys=align_keys,
+            mask=mask,
+            new=new,
+            using_cow=using_copy_on_write(),
+            already_warned=already_warned,
+        )
+
+    @final
+    def round(self, decimals: int, using_cow: bool = False) -> Self:
+        return self.apply_with_block(
+            "round",
+            decimals=decimals,
+            using_cow=using_cow,
+        )
+
+    @final
+    def replace(self, to_replace, value, inplace: bool) -> Self:
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        # NDFrame.replace ensures the not-is_list_likes here
+        assert not lib.is_list_like(to_replace)
+        assert not lib.is_list_like(value)
+        return self.apply_with_block(
+            "replace",
+            to_replace=to_replace,
+            value=value,
+            inplace=inplace,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+
+    @final
+    def replace_regex(self, **kwargs) -> Self:
+        return self.apply_with_block(
+            "_replace_regex",
+            **kwargs,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+
+    @final
+    def replace_list(
+        self,
+        src_list: list[Any],
+        dest_list: list[Any],
+        inplace: bool = False,
+        regex: bool = False,
+    ) -> Self:
+        """do a list replace"""
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        bm = self.apply_with_block(
+            "replace_list",
+            src_list=src_list,
+            dest_list=dest_list,
+            inplace=inplace,
+            regex=regex,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+        bm._consolidate_inplace()
+        return bm
+
+    def interpolate(self, inplace: bool, **kwargs) -> Self:
+        return self.apply_with_block(
+            "interpolate",
+            inplace=inplace,
+            **kwargs,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+
+    def pad_or_backfill(self, inplace: bool, **kwargs) -> Self:
+        return self.apply_with_block(
+            "pad_or_backfill",
+            inplace=inplace,
+            **kwargs,
+            using_cow=using_copy_on_write(),
+            already_warned=_AlreadyWarned(),
+        )
+
+    def shift(self, periods: int, fill_value) -> Self:
+        if fill_value is lib.no_default:
+            fill_value = None
+
+        return self.apply_with_block("shift", periods=periods, fill_value=fill_value)
+
+    # --------------------------------------------------------------------
+    # Consolidation: No-ops for all but BlockManager
+
+    def is_consolidated(self) -> bool:
+        return True
+
+    def consolidate(self) -> Self:
+        return self
+
+    def _consolidate_inplace(self) -> None:
+        return
+
+
+class SingleDataManager(DataManager):
+    @property
+    def ndim(self) -> Literal[1]:
+        return 1
+
+    @final
+    @property
+    def array(self) -> ArrayLike:
+        """
+        Quick access to the backing array of the Block or SingleArrayManager.
+        """
+        # error: "SingleDataManager" has no attribute "arrays"; maybe "array"
+        return self.arrays[0]  # type: ignore[attr-defined]
+
+    def setitem_inplace(self, indexer, value, warn: bool = True) -> None:
+        """
+        Set values with indexer.
+
+        For Single[Block/Array]Manager, this backs s[indexer] = value
+
+        This is an inplace version of `setitem()`, mutating the manager/values
+        in place, not returning a new Manager (and Block), and thus never changing
+        the dtype.
+        """
+        arr = self.array
+
+        # EAs will do this validation in their own __setitem__ methods.
+        if isinstance(arr, np.ndarray):
+            # Note: checking for ndarray instead of np.dtype means we exclude
+            #  dt64/td64, which do their own validation.
+            value = np_can_hold_element(arr.dtype, value)
+
+        if isinstance(value, np.ndarray) and value.ndim == 1 and len(value) == 1:
+            # NumPy 1.25 deprecation: https://github.com/numpy/numpy/pull/10615
+            value = value[0, ...]
+
+        arr[indexer] = value
+
+    def grouped_reduce(self, func):
+        arr = self.array
+        res = func(arr)
+        index = default_index(len(res))
+
+        mgr = type(self).from_array(res, index)
+        return mgr
+
+    @classmethod
+    def from_array(cls, arr: ArrayLike, index: Index):
+        raise AbstractMethodError(cls)
+
+
+def interleaved_dtype(dtypes: list[DtypeObj]) -> DtypeObj | None:
+    """
+    Find the common dtype for `blocks`.
+
+    Parameters
+    ----------
+    blocks : List[DtypeObj]
+
+    Returns
+    -------
+    dtype : np.dtype, ExtensionDtype, or None
+        None is returned when `blocks` is empty.
+    """
+    if not len(dtypes):
+        return None
+
+    return find_common_type(dtypes)
+
+
+def ensure_np_dtype(dtype: DtypeObj) -> np.dtype:
+    # TODO: https://github.com/pandas-dev/pandas/issues/22791
+    # Give EAs some input on what happens here. Sparse needs this.
+    if isinstance(dtype, SparseDtype):
+        dtype = dtype.subtype
+        dtype = cast(np.dtype, dtype)
+    elif isinstance(dtype, ExtensionDtype):
+        dtype = np.dtype("object")
+    elif dtype == np.dtype(str):
+        dtype = np.dtype("object")
+    return dtype
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/blocks.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/blocks.py
new file mode 100644
index 0000000000000000000000000000000000000000..452c919449ec40c042bdb68b249801f2267b2b19
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/blocks.py
@@ -0,0 +1,2923 @@
+from __future__ import annotations
+
+from functools import wraps
+import inspect
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    final,
+)
+import warnings
+import weakref
+
+import numpy as np
+
+from pandas._config import (
+    get_option,
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs import (
+    NaT,
+    internals as libinternals,
+    lib,
+)
+from pandas._libs.internals import (
+    BlockPlacement,
+    BlockValuesRefs,
+)
+from pandas._libs.missing import NA
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    DtypeBackend,
+    DtypeObj,
+    F,
+    FillnaOptions,
+    IgnoreRaise,
+    InterpolateOptions,
+    QuantileInterpolation,
+    Self,
+    Shape,
+    npt,
+)
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import validate_bool_kwarg
+
+from pandas.core.dtypes.astype import (
+    astype_array_safe,
+    astype_is_view,
+)
+from pandas.core.dtypes.cast import (
+    LossySetitemError,
+    can_hold_element,
+    convert_dtypes,
+    find_result_type,
+    maybe_downcast_to_dtype,
+    np_can_hold_element,
+)
+from pandas.core.dtypes.common import (
+    is_1d_only_ea_dtype,
+    is_float_dtype,
+    is_integer_dtype,
+    is_list_like,
+    is_scalar,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    ExtensionDtype,
+    IntervalDtype,
+    NumpyEADtype,
+    PeriodDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCNumpyExtensionArray,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import is_re
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+    na_value_for_dtype,
+)
+
+from pandas.core import missing
+import pandas.core.algorithms as algos
+from pandas.core.array_algos.putmask import (
+    extract_bool_array,
+    putmask_inplace,
+    putmask_without_repeat,
+    setitem_datetimelike_compat,
+    validate_putmask,
+)
+from pandas.core.array_algos.quantile import quantile_compat
+from pandas.core.array_algos.replace import (
+    compare_or_regex_search,
+    replace_regex,
+    should_use_regex,
+)
+from pandas.core.array_algos.transforms import shift
+from pandas.core.arrays import (
+    Categorical,
+    DatetimeArray,
+    ExtensionArray,
+    IntervalArray,
+    NumpyExtensionArray,
+    PeriodArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.base import PandasObject
+import pandas.core.common as com
+from pandas.core.computation import expressions
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import check_setitem_lengths
+from pandas.core.indexes.base import get_values_for_csv
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Sequence,
+    )
+
+    from pandas.core.api import Index
+    from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+
+# comparison is faster than is_object_dtype
+_dtype_obj = np.dtype("object")
+
+
+COW_WARNING_GENERAL_MSG = """\
+Setting a value on a view: behaviour will change in pandas 3.0.
+You are mutating a Series or DataFrame object, and currently this mutation will
+also have effect on other Series or DataFrame objects that share data with this
+object. In pandas 3.0 (with Copy-on-Write), updating one Series or DataFrame object
+will never modify another.
+"""
+
+
+COW_WARNING_SETITEM_MSG = """\
+Setting a value on a view: behaviour will change in pandas 3.0.
+Currently, the mutation will also have effect on the object that shares data
+with this object. For example, when setting a value in a Series that was
+extracted from a column of a DataFrame, that DataFrame will also be updated:
+
+    ser = df["col"]
+    ser[0] = 0     <--- in pandas 2, this also updates `df`
+
+In pandas 3.0 (with Copy-on-Write), updating one Series/DataFrame will never
+modify another, and thus in the example above, `df` will not be changed.
+"""
+
+
+def maybe_split(meth: F) -> F:
+    """
+    If we have a multi-column block, split and operate block-wise.  Otherwise
+    use the original method.
+    """
+
+    @wraps(meth)
+    def newfunc(self, *args, **kwargs) -> list[Block]:
+        if self.ndim == 1 or self.shape[0] == 1:
+            return meth(self, *args, **kwargs)
+        else:
+            # Split and operate column-by-column
+            return self.split_and_operate(meth, *args, **kwargs)
+
+    return cast(F, newfunc)
+
+
+class Block(PandasObject, libinternals.Block):
+    """
+    Canonical n-dimensional unit of homogeneous dtype contained in a pandas
+    data structure
+
+    Index-ignorant; let the container take care of that
+    """
+
+    values: np.ndarray | ExtensionArray
+    ndim: int
+    refs: BlockValuesRefs
+    __init__: Callable
+
+    __slots__ = ()
+    is_numeric = False
+
+    @final
+    @cache_readonly
+    def _validate_ndim(self) -> bool:
+        """
+        We validate dimension for blocks that can hold 2D values, which for now
+        means numpy dtypes or DatetimeTZDtype.
+        """
+        dtype = self.dtype
+        return not isinstance(dtype, ExtensionDtype) or isinstance(
+            dtype, DatetimeTZDtype
+        )
+
+    @final
+    @cache_readonly
+    def is_object(self) -> bool:
+        return self.values.dtype == _dtype_obj
+
+    @final
+    @cache_readonly
+    def is_extension(self) -> bool:
+        return not lib.is_np_dtype(self.values.dtype)
+
+    @final
+    @cache_readonly
+    def _can_consolidate(self) -> bool:
+        # We _could_ consolidate for DatetimeTZDtype but don't for now.
+        return not self.is_extension
+
+    @final
+    @cache_readonly
+    def _consolidate_key(self):
+        return self._can_consolidate, self.dtype.name
+
+    @final
+    @cache_readonly
+    def _can_hold_na(self) -> bool:
+        """
+        Can we store NA values in this Block?
+        """
+        dtype = self.dtype
+        if isinstance(dtype, np.dtype):
+            return dtype.kind not in "iub"
+        return dtype._can_hold_na
+
+    @final
+    @property
+    def is_bool(self) -> bool:
+        """
+        We can be bool if a) we are bool dtype or b) object dtype with bool objects.
+        """
+        return self.values.dtype == np.dtype(bool)
+
+    @final
+    def external_values(self):
+        return external_values(self.values)
+
+    @final
+    @cache_readonly
+    def fill_value(self):
+        # Used in reindex_indexer
+        return na_value_for_dtype(self.dtype, compat=False)
+
+    @final
+    def _standardize_fill_value(self, value):
+        # if we are passed a scalar None, convert it here
+        if self.dtype != _dtype_obj and is_valid_na_for_dtype(value, self.dtype):
+            value = self.fill_value
+        return value
+
+    @property
+    def mgr_locs(self) -> BlockPlacement:
+        return self._mgr_locs
+
+    @mgr_locs.setter
+    def mgr_locs(self, new_mgr_locs: BlockPlacement) -> None:
+        self._mgr_locs = new_mgr_locs
+
+    @final
+    def make_block(
+        self,
+        values,
+        placement: BlockPlacement | None = None,
+        refs: BlockValuesRefs | None = None,
+    ) -> Block:
+        """
+        Create a new block, with type inference propagate any values that are
+        not specified
+        """
+        if placement is None:
+            placement = self._mgr_locs
+        if self.is_extension:
+            values = ensure_block_shape(values, ndim=self.ndim)
+
+        return new_block(values, placement=placement, ndim=self.ndim, refs=refs)
+
+    @final
+    def make_block_same_class(
+        self,
+        values,
+        placement: BlockPlacement | None = None,
+        refs: BlockValuesRefs | None = None,
+    ) -> Self:
+        """Wrap given values in a block of same type as self."""
+        # Pre-2.0 we called ensure_wrapped_if_datetimelike because fastparquet
+        #  relied on it, as of 2.0 the caller is responsible for this.
+        if placement is None:
+            placement = self._mgr_locs
+
+        # We assume maybe_coerce_values has already been called
+        return type(self)(values, placement=placement, ndim=self.ndim, refs=refs)
+
+    @final
+    def __repr__(self) -> str:
+        # don't want to print out all of the items here
+        name = type(self).__name__
+        if self.ndim == 1:
+            result = f"{name}: {len(self)} dtype: {self.dtype}"
+        else:
+            shape = " x ".join([str(s) for s in self.shape])
+            result = f"{name}: {self.mgr_locs.indexer}, {shape}, dtype: {self.dtype}"
+
+        return result
+
+    @final
+    def __len__(self) -> int:
+        return len(self.values)
+
+    @final
+    def slice_block_columns(self, slc: slice) -> Self:
+        """
+        Perform __getitem__-like, return result as block.
+        """
+        new_mgr_locs = self._mgr_locs[slc]
+
+        new_values = self._slice(slc)
+        refs = self.refs
+        return type(self)(new_values, new_mgr_locs, self.ndim, refs=refs)
+
+    @final
+    def take_block_columns(self, indices: npt.NDArray[np.intp]) -> Self:
+        """
+        Perform __getitem__-like, return result as block.
+
+        Only supports slices that preserve dimensionality.
+        """
+        # Note: only called from is from internals.concat, and we can verify
+        #  that never happens with 1-column blocks, i.e. never for ExtensionBlock.
+
+        new_mgr_locs = self._mgr_locs[indices]
+
+        new_values = self._slice(indices)
+        return type(self)(new_values, new_mgr_locs, self.ndim, refs=None)
+
+    @final
+    def getitem_block_columns(
+        self, slicer: slice, new_mgr_locs: BlockPlacement, ref_inplace_op: bool = False
+    ) -> Self:
+        """
+        Perform __getitem__-like, return result as block.
+
+        Only supports slices that preserve dimensionality.
+        """
+        new_values = self._slice(slicer)
+        refs = self.refs if not ref_inplace_op or self.refs.has_reference() else None
+        return type(self)(new_values, new_mgr_locs, self.ndim, refs=refs)
+
+    @final
+    def _can_hold_element(self, element: Any) -> bool:
+        """require the same dtype as ourselves"""
+        element = extract_array(element, extract_numpy=True)
+        return can_hold_element(self.values, element)
+
+    @final
+    def should_store(self, value: ArrayLike) -> bool:
+        """
+        Should we set self.values[indexer] = value inplace or do we need to cast?
+
+        Parameters
+        ----------
+        value : np.ndarray or ExtensionArray
+
+        Returns
+        -------
+        bool
+        """
+        return value.dtype == self.dtype
+
+    # ---------------------------------------------------------------------
+    # Apply/Reduce and Helpers
+
+    @final
+    def apply(self, func, **kwargs) -> list[Block]:
+        """
+        apply the function to my values; return a block if we are not
+        one
+        """
+        result = func(self.values, **kwargs)
+
+        result = maybe_coerce_values(result)
+        return self._split_op_result(result)
+
+    @final
+    def reduce(self, func) -> list[Block]:
+        # We will apply the function and reshape the result into a single-row
+        #  Block with the same mgr_locs; squeezing will be done at a higher level
+        assert self.ndim == 2
+
+        result = func(self.values)
+
+        if self.values.ndim == 1:
+            res_values = result
+        else:
+            res_values = result.reshape(-1, 1)
+
+        nb = self.make_block(res_values)
+        return [nb]
+
+    @final
+    def _split_op_result(self, result: ArrayLike) -> list[Block]:
+        # See also: split_and_operate
+        if result.ndim > 1 and isinstance(result.dtype, ExtensionDtype):
+            # TODO(EA2D): unnecessary with 2D EAs
+            # if we get a 2D ExtensionArray, we need to split it into 1D pieces
+            nbs = []
+            for i, loc in enumerate(self._mgr_locs):
+                if not is_1d_only_ea_dtype(result.dtype):
+                    vals = result[i : i + 1]
+                else:
+                    vals = result[i]
+
+                bp = BlockPlacement(loc)
+                block = self.make_block(values=vals, placement=bp)
+                nbs.append(block)
+            return nbs
+
+        nb = self.make_block(result)
+
+        return [nb]
+
+    @final
+    def _split(self) -> list[Block]:
+        """
+        Split a block into a list of single-column blocks.
+        """
+        assert self.ndim == 2
+
+        new_blocks = []
+        for i, ref_loc in enumerate(self._mgr_locs):
+            vals = self.values[slice(i, i + 1)]
+
+            bp = BlockPlacement(ref_loc)
+            nb = type(self)(vals, placement=bp, ndim=2, refs=self.refs)
+            new_blocks.append(nb)
+        return new_blocks
+
+    @final
+    def split_and_operate(self, func, *args, **kwargs) -> list[Block]:
+        """
+        Split the block and apply func column-by-column.
+
+        Parameters
+        ----------
+        func : Block method
+        *args
+        **kwargs
+
+        Returns
+        -------
+        List[Block]
+        """
+        assert self.ndim == 2 and self.shape[0] != 1
+
+        res_blocks = []
+        for nb in self._split():
+            rbs = func(nb, *args, **kwargs)
+            res_blocks.extend(rbs)
+        return res_blocks
+
+    # ---------------------------------------------------------------------
+    # Up/Down-casting
+
+    @final
+    def coerce_to_target_dtype(
+        self, other, warn_on_upcast: bool = False, using_cow: bool = False
+    ) -> Block:
+        """
+        coerce the current block to a dtype compat for other
+        we will return a block, possibly object, and not raise
+
+        we can also safely try to coerce to the same dtype
+        and will receive the same block
+        """
+        new_dtype = find_result_type(self.values.dtype, other)
+        if new_dtype == self.dtype:
+            # GH#52927 avoid RecursionError
+            raise AssertionError(
+                "Something has gone wrong, please report a bug at "
+                "https://github.com/pandas-dev/pandas/issues"
+            )
+
+        # In a future version of pandas, the default will be that
+        # setting `nan` into an integer series won't raise.
+        if (
+            is_scalar(other)
+            and is_integer_dtype(self.values.dtype)
+            and isna(other)
+            and other is not NaT
+            and not (
+                isinstance(other, (np.datetime64, np.timedelta64)) and np.isnat(other)
+            )
+        ):
+            warn_on_upcast = False
+        elif (
+            isinstance(other, np.ndarray)
+            and other.ndim == 1
+            and is_integer_dtype(self.values.dtype)
+            and is_float_dtype(other.dtype)
+            and lib.has_only_ints_or_nan(other)
+        ):
+            warn_on_upcast = False
+
+        if warn_on_upcast:
+            warnings.warn(
+                f"Setting an item of incompatible dtype is deprecated "
+                "and will raise an error in a future version of pandas. "
+                f"Value '{other}' has dtype incompatible with {self.values.dtype}, "
+                "please explicitly cast to a compatible dtype first.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if self.values.dtype == new_dtype:
+            raise AssertionError(
+                f"Did not expect new dtype {new_dtype} to equal self.dtype "
+                f"{self.values.dtype}. Please report a bug at "
+                "https://github.com/pandas-dev/pandas/issues."
+            )
+        copy = False
+        if (
+            not using_cow
+            and isinstance(self.dtype, StringDtype)
+            and self.dtype.storage == "python"
+        ):
+            copy = True
+        return self.astype(new_dtype, copy=copy, using_cow=using_cow)
+
+    @final
+    def _maybe_downcast(
+        self,
+        blocks: list[Block],
+        downcast,
+        using_cow: bool,
+        caller: str,
+    ) -> list[Block]:
+        if downcast is False:
+            return blocks
+
+        if self.dtype == _dtype_obj:
+            # TODO: does it matter that self.dtype might not match blocks[i].dtype?
+            # GH#44241 We downcast regardless of the argument;
+            #  respecting 'downcast=None' may be worthwhile at some point,
+            #  but ATM it breaks too much existing code.
+            # split and convert the blocks
+
+            if caller == "fillna" and get_option("future.no_silent_downcasting"):
+                return blocks
+
+            nbs = extend_blocks(
+                [
+                    blk.convert(
+                        using_cow=using_cow, copy=not using_cow, convert_string=False
+                    )
+                    for blk in blocks
+                ]
+            )
+            if caller == "fillna":
+                if len(nbs) != len(blocks) or not all(
+                    x.dtype == y.dtype for x, y in zip(nbs, blocks)
+                ):
+                    # GH#54261
+                    warnings.warn(
+                        "Downcasting object dtype arrays on .fillna, .ffill, .bfill "
+                        "is deprecated and will change in a future version. "
+                        "Call result.infer_objects(copy=False) instead. "
+                        "To opt-in to the future "
+                        "behavior, set "
+                        "`pd.set_option('future.no_silent_downcasting', True)`",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+
+            return nbs
+
+        elif downcast is None:
+            return blocks
+        elif caller == "where" and get_option("future.no_silent_downcasting") is True:
+            return blocks
+        else:
+            nbs = extend_blocks([b._downcast_2d(downcast, using_cow) for b in blocks])
+
+        # When _maybe_downcast is called with caller="where", it is either
+        #  a) with downcast=False, which is a no-op (the desired future behavior)
+        #  b) with downcast="infer", which is _not_ passed by the user.
+        # In the latter case the future behavior is to stop doing inference,
+        #  so we issue a warning if and only if some inference occurred.
+        if caller == "where":
+            # GH#53656
+            if len(blocks) != len(nbs) or any(
+                left.dtype != right.dtype for left, right in zip(blocks, nbs)
+            ):
+                # In this case _maybe_downcast was _not_ a no-op, so the behavior
+                #  will change, so we issue a warning.
+                warnings.warn(
+                    "Downcasting behavior in Series and DataFrame methods 'where', "
+                    "'mask', and 'clip' is deprecated. In a future "
+                    "version this will not infer object dtypes or cast all-round "
+                    "floats to integers. Instead call "
+                    "result.infer_objects(copy=False) for object inference, "
+                    "or cast round floats explicitly. To opt-in to the future "
+                    "behavior, set "
+                    "`pd.set_option('future.no_silent_downcasting', True)`",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        return nbs
+
+    @final
+    @maybe_split
+    def _downcast_2d(self, dtype, using_cow: bool = False) -> list[Block]:
+        """
+        downcast specialized to 2D case post-validation.
+
+        Refactored to allow use of maybe_split.
+        """
+        new_values = maybe_downcast_to_dtype(self.values, dtype=dtype)
+        new_values = maybe_coerce_values(new_values)
+        refs = self.refs if new_values is self.values else None
+        return [self.make_block(new_values, refs=refs)]
+
+    @final
+    def convert(
+        self,
+        *,
+        copy: bool = True,
+        using_cow: bool = False,
+        convert_string: bool = True,
+    ) -> list[Block]:
+        """
+        Attempt to coerce any object types to better types. Return a copy
+        of the block (if copy = True).
+        """
+        if not self.is_object:
+            if not copy and using_cow:
+                return [self.copy(deep=False)]
+            return [self.copy()] if copy else [self]
+
+        if self.ndim != 1 and self.shape[0] != 1:
+            blocks = self.split_and_operate(
+                Block.convert,
+                copy=copy,
+                using_cow=using_cow,
+                convert_string=convert_string,
+            )
+            if all(blk.dtype.kind == "O" for blk in blocks):
+                # Avoid fragmenting the block if convert is a no-op
+                if using_cow:
+                    return [self.copy(deep=False)]
+                return [self.copy()] if copy else [self]
+            return blocks
+
+        values = self.values
+        if values.ndim == 2:
+            # the check above ensures we only get here with values.shape[0] == 1,
+            # avoid doing .ravel as that might make a copy
+            values = values[0]
+
+        res_values = lib.maybe_convert_objects(
+            values,  # type: ignore[arg-type]
+            convert_non_numeric=True,
+            convert_string=convert_string,
+        )
+        refs = None
+        if (
+            copy
+            and res_values is values
+            or isinstance(res_values, NumpyExtensionArray)
+            and res_values._ndarray is values
+        ):
+            res_values = res_values.copy()
+        elif res_values is values:
+            refs = self.refs
+
+        res_values = ensure_block_shape(res_values, self.ndim)
+        res_values = maybe_coerce_values(res_values)
+        return [self.make_block(res_values, refs=refs)]
+
+    def convert_dtypes(
+        self,
+        copy: bool,
+        using_cow: bool,
+        infer_objects: bool = True,
+        convert_string: bool = True,
+        convert_integer: bool = True,
+        convert_boolean: bool = True,
+        convert_floating: bool = True,
+        dtype_backend: DtypeBackend = "numpy_nullable",
+    ) -> list[Block]:
+        if infer_objects and self.is_object:
+            blks = self.convert(copy=False, using_cow=using_cow)
+        else:
+            blks = [self]
+
+        if not any(
+            [convert_floating, convert_integer, convert_boolean, convert_string]
+        ):
+            return [b.copy(deep=copy) for b in blks]
+
+        rbs = []
+        for blk in blks:
+            # Determine dtype column by column
+            sub_blks = [blk] if blk.ndim == 1 or self.shape[0] == 1 else blk._split()
+            dtypes = [
+                convert_dtypes(
+                    b.values,
+                    convert_string,
+                    convert_integer,
+                    convert_boolean,
+                    convert_floating,
+                    infer_objects,
+                    dtype_backend,
+                )
+                for b in sub_blks
+            ]
+            if all(dtype == self.dtype for dtype in dtypes):
+                # Avoid block splitting if no dtype changes
+                rbs.append(blk.copy(deep=copy))
+                continue
+
+            for dtype, b in zip(dtypes, sub_blks):
+                rbs.append(b.astype(dtype=dtype, copy=copy, squeeze=b.ndim != 1))
+        return rbs
+
+    # ---------------------------------------------------------------------
+    # Array-Like Methods
+
+    @final
+    @cache_readonly
+    def dtype(self) -> DtypeObj:
+        return self.values.dtype
+
+    @final
+    def astype(
+        self,
+        dtype: DtypeObj,
+        copy: bool = False,
+        errors: IgnoreRaise = "raise",
+        using_cow: bool = False,
+        squeeze: bool = False,
+    ) -> Block:
+        """
+        Coerce to the new dtype.
+
+        Parameters
+        ----------
+        dtype : np.dtype or ExtensionDtype
+        copy : bool, default False
+            copy if indicated
+        errors : str, {'raise', 'ignore'}, default 'raise'
+            - ``raise`` : allow exceptions to be raised
+            - ``ignore`` : suppress exceptions. On error return original object
+        using_cow: bool, default False
+            Signaling if copy on write copy logic is used.
+        squeeze : bool, default False
+            squeeze values to ndim=1 if only one column is given
+
+        Returns
+        -------
+        Block
+        """
+        values = self.values
+        if squeeze and values.ndim == 2 and is_1d_only_ea_dtype(dtype):
+            if values.shape[0] != 1:
+                raise ValueError("Can not squeeze with more than one column.")
+            values = values[0, :]  # type: ignore[call-overload]
+
+        new_values = astype_array_safe(values, dtype, copy=copy, errors=errors)
+
+        new_values = maybe_coerce_values(new_values)
+
+        refs = None
+        if (using_cow or not copy) and astype_is_view(values.dtype, new_values.dtype):
+            refs = self.refs
+
+        newb = self.make_block(new_values, refs=refs)
+        if newb.shape != self.shape:
+            raise TypeError(
+                f"cannot set astype for copy = [{copy}] for dtype "
+                f"({self.dtype.name} [{self.shape}]) to different shape "
+                f"({newb.dtype.name} [{newb.shape}])"
+            )
+        return newb
+
+    @final
+    def get_values_for_csv(
+        self, *, float_format, date_format, decimal, na_rep: str = "nan", quoting=None
+    ) -> Block:
+        """convert to our native types format"""
+        result = get_values_for_csv(
+            self.values,
+            na_rep=na_rep,
+            quoting=quoting,
+            float_format=float_format,
+            date_format=date_format,
+            decimal=decimal,
+        )
+        return self.make_block(result)
+
+    @final
+    def copy(self, deep: bool = True) -> Self:
+        """copy constructor"""
+        values = self.values
+        refs: BlockValuesRefs | None
+        if deep:
+            values = values.copy()
+            refs = None
+        else:
+            refs = self.refs
+        return type(self)(values, placement=self._mgr_locs, ndim=self.ndim, refs=refs)
+
+    # ---------------------------------------------------------------------
+    # Copy-on-Write Helpers
+
+    @final
+    def _maybe_copy(self, using_cow: bool, inplace: bool) -> Self:
+        if using_cow and inplace:
+            deep = self.refs.has_reference()
+            blk = self.copy(deep=deep)
+        else:
+            blk = self if inplace else self.copy()
+        return blk
+
+    @final
+    def _get_refs_and_copy(self, using_cow: bool, inplace: bool):
+        refs = None
+        copy = not inplace
+        if inplace:
+            if using_cow and self.refs.has_reference():
+                copy = True
+            else:
+                refs = self.refs
+        return copy, refs
+
+    # ---------------------------------------------------------------------
+    # Replace
+
+    @final
+    def replace(
+        self,
+        to_replace,
+        value,
+        inplace: bool = False,
+        # mask may be pre-computed if we're called from replace_list
+        mask: npt.NDArray[np.bool_] | None = None,
+        using_cow: bool = False,
+        already_warned=None,
+        convert_string=None,
+    ) -> list[Block]:
+        """
+        replace the to_replace value with value, possible to create new
+        blocks here this is just a call to putmask.
+        """
+
+        # Note: the checks we do in NDFrame.replace ensure we never get
+        #  here with listlike to_replace or value, as those cases
+        #  go through replace_list
+        values = self.values
+
+        if isinstance(values, Categorical):
+            # TODO: avoid special-casing
+            # GH49404
+            blk = self._maybe_copy(using_cow, inplace)
+            values = cast(Categorical, blk.values)
+            values._replace(to_replace=to_replace, value=value, inplace=True)
+            return [blk]
+
+        if not self._can_hold_element(to_replace):
+            # We cannot hold `to_replace`, so we know immediately that
+            #  replacing it is a no-op.
+            # Note: If to_replace were a list, NDFrame.replace would call
+            #  replace_list instead of replace.
+            if using_cow:
+                return [self.copy(deep=False)]
+            else:
+                return [self] if inplace else [self.copy()]
+
+        if mask is None:
+            mask = missing.mask_missing(values, to_replace)
+        if not mask.any():
+            # Note: we get here with test_replace_extension_other incorrectly
+            #  bc _can_hold_element is incorrect.
+            if using_cow:
+                return [self.copy(deep=False)]
+            else:
+                return [self] if inplace else [self.copy()]
+
+        elif self._can_hold_element(value) or (self.dtype == "string" and is_re(value)):
+            # TODO(CoW): Maybe split here as well into columns where mask has True
+            # and rest?
+            blk = self._maybe_copy(using_cow, inplace)
+            putmask_inplace(blk.values, mask, value)
+            if (
+                inplace
+                and warn_copy_on_write()
+                and already_warned is not None
+                and not already_warned.warned_already
+            ):
+                if self.refs.has_reference():
+                    warnings.warn(
+                        COW_WARNING_GENERAL_MSG,
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    already_warned.warned_already = True
+
+            if not (self.is_object and value is None):
+                # if the user *explicitly* gave None, we keep None, otherwise
+                #  may downcast to NaN
+                if get_option("future.no_silent_downcasting") is True:
+                    blocks = [blk]
+                else:
+                    blocks = blk.convert(
+                        copy=False,
+                        using_cow=using_cow,
+                        convert_string=convert_string or self.dtype == "string",
+                    )
+                    if len(blocks) > 1 or blocks[0].dtype != blk.dtype:
+                        warnings.warn(
+                            # GH#54710
+                            "Downcasting behavior in `replace` is deprecated and "
+                            "will be removed in a future version. To retain the old "
+                            "behavior, explicitly call "
+                            "`result.infer_objects(copy=False)`. "
+                            "To opt-in to the future "
+                            "behavior, set "
+                            "`pd.set_option('future.no_silent_downcasting', True)`",
+                            FutureWarning,
+                            stacklevel=find_stack_level(),
+                        )
+            else:
+                blocks = [blk]
+            return blocks
+
+        elif self.ndim == 1 or self.shape[0] == 1:
+            if value is None or value is NA:
+                blk = self.astype(np.dtype(object))
+            else:
+                blk = self.coerce_to_target_dtype(value, using_cow=using_cow)
+            return blk.replace(
+                to_replace=to_replace,
+                value=value,
+                inplace=True,
+                mask=mask,
+                using_cow=using_cow,
+                convert_string=convert_string,
+            )
+
+        else:
+            # split so that we only upcast where necessary
+            blocks = []
+            for i, nb in enumerate(self._split()):
+                blocks.extend(
+                    type(self).replace(
+                        nb,
+                        to_replace=to_replace,
+                        value=value,
+                        inplace=True,
+                        mask=mask[i : i + 1],
+                        using_cow=using_cow,
+                        convert_string=convert_string,
+                    )
+                )
+            return blocks
+
+    @final
+    def _replace_regex(
+        self,
+        to_replace,
+        value,
+        inplace: bool = False,
+        mask=None,
+        using_cow: bool = False,
+        convert_string=None,
+        already_warned=None,
+    ) -> list[Block]:
+        """
+        Replace elements by the given value.
+
+        Parameters
+        ----------
+        to_replace : object or pattern
+            Scalar to replace or regular expression to match.
+        value : object
+            Replacement object.
+        inplace : bool, default False
+            Perform inplace modification.
+        mask : array-like of bool, optional
+            True indicate corresponding element is ignored.
+        using_cow: bool, default False
+            Specifying if copy on write is enabled.
+
+        Returns
+        -------
+        List[Block]
+        """
+        if not is_re(to_replace) and not self._can_hold_element(to_replace):
+            # i.e. only if self.is_object is True, but could in principle include a
+            #  String ExtensionBlock
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self] if inplace else [self.copy()]
+
+        if is_re(to_replace) and self.dtype not in [object, "string"]:
+            # only object or string dtype can hold strings, and a regex object
+            # will only match strings
+            return [self.copy(deep=False)]
+
+        if not (
+            self._can_hold_element(value) or (self.dtype == "string" and is_re(value))
+        ):
+            block = self.astype(np.dtype(object))
+        else:
+            block = self._maybe_copy(using_cow, inplace)
+
+        rx = re.compile(to_replace)
+
+        replace_regex(block.values, rx, value, mask)
+
+        if (
+            inplace
+            and warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+
+        nbs = block.convert(
+            copy=False,
+            using_cow=using_cow,
+            convert_string=convert_string or self.dtype == "string",
+        )
+        opt = get_option("future.no_silent_downcasting")
+        if (
+            len(nbs) > 1
+            or (
+                nbs[0].dtype != block.dtype
+                and not (self.dtype == "string" and nbs[0].dtype == "string")
+            )
+        ) and not opt:
+            warnings.warn(
+                # GH#54710
+                "Downcasting behavior in `replace` is deprecated and "
+                "will be removed in a future version. To retain the old "
+                "behavior, explicitly call `result.infer_objects(copy=False)`. "
+                "To opt-in to the future "
+                "behavior, set "
+                "`pd.set_option('future.no_silent_downcasting', True)`",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return nbs
+
+    @final
+    def replace_list(
+        self,
+        src_list: Iterable[Any],
+        dest_list: Sequence[Any],
+        inplace: bool = False,
+        regex: bool = False,
+        using_cow: bool = False,
+        already_warned=None,
+    ) -> list[Block]:
+        """
+        See BlockManager.replace_list docstring.
+        """
+        values = self.values
+
+        if isinstance(values, Categorical):
+            # TODO: avoid special-casing
+            # GH49404
+            blk = self._maybe_copy(using_cow, inplace)
+            values = cast(Categorical, blk.values)
+            values._replace(to_replace=src_list, value=dest_list, inplace=True)
+            return [blk]
+
+        convert_string = self.dtype == "string"
+
+        # Exclude anything that we know we won't contain
+        pairs = [
+            (x, y)
+            for x, y in zip(src_list, dest_list)
+            if (self._can_hold_element(x) or (self.dtype == "string" and is_re(x)))
+        ]
+        if not len(pairs):
+            if using_cow:
+                return [self.copy(deep=False)]
+            # shortcut, nothing to replace
+            return [self] if inplace else [self.copy()]
+
+        src_len = len(pairs) - 1
+
+        if is_string_dtype(values.dtype):
+            # Calculate the mask once, prior to the call of comp
+            # in order to avoid repeating the same computations
+            na_mask = ~isna(values)
+            masks: Iterable[npt.NDArray[np.bool_]] = (
+                extract_bool_array(
+                    cast(
+                        ArrayLike,
+                        compare_or_regex_search(
+                            values, s[0], regex=regex, mask=na_mask
+                        ),
+                    )
+                )
+                for s in pairs
+            )
+        else:
+            # GH#38086 faster if we know we dont need to check for regex
+            masks = (missing.mask_missing(values, s[0]) for s in pairs)
+        # Materialize if inplace = True, since the masks can change
+        # as we replace
+        if inplace:
+            masks = list(masks)
+
+        if using_cow:
+            # Don't set up refs here, otherwise we will think that we have
+            # references when we check again later
+            rb = [self]
+        else:
+            rb = [self if inplace else self.copy()]
+
+        if (
+            inplace
+            and warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+
+        opt = get_option("future.no_silent_downcasting")
+        for i, ((src, dest), mask) in enumerate(zip(pairs, masks)):
+            convert = i == src_len  # only convert once at the end
+            new_rb: list[Block] = []
+
+            # GH-39338: _replace_coerce can split a block into
+            # single-column blocks, so track the index so we know
+            # where to index into the mask
+            for blk_num, blk in enumerate(rb):
+                if len(rb) == 1:
+                    m = mask
+                else:
+                    mib = mask
+                    assert not isinstance(mib, bool)
+                    m = mib[blk_num : blk_num + 1]
+
+                # error: Argument "mask" to "_replace_coerce" of "Block" has
+                # incompatible type "Union[ExtensionArray, ndarray[Any, Any], bool]";
+                # expected "ndarray[Any, dtype[bool_]]"
+                result = blk._replace_coerce(
+                    to_replace=src,
+                    value=dest,
+                    mask=m,
+                    inplace=inplace,
+                    regex=regex,
+                    using_cow=using_cow,
+                    convert_string=convert_string,
+                )
+
+                if using_cow and i != src_len:
+                    # This is ugly, but we have to get rid of intermediate refs
+                    # that did not go out of scope yet, otherwise we will trigger
+                    # many unnecessary copies
+                    for b in result:
+                        ref = weakref.ref(b)
+                        b.refs.referenced_blocks.pop(
+                            b.refs.referenced_blocks.index(ref)
+                        )
+
+                if (
+                    not opt
+                    and convert
+                    and blk.is_object
+                    and not all(x is None for x in dest_list)
+                ):
+                    # GH#44498 avoid unwanted cast-back
+                    nbs = []
+                    for res_blk in result:
+                        converted = res_blk.convert(
+                            copy=True and not using_cow,
+                            using_cow=using_cow,
+                            convert_string=convert_string,
+                        )
+                        if len(converted) > 1 or converted[0].dtype != res_blk.dtype:
+                            warnings.warn(
+                                # GH#54710
+                                "Downcasting behavior in `replace` is deprecated "
+                                "and will be removed in a future version. To "
+                                "retain the old behavior, explicitly call "
+                                "`result.infer_objects(copy=False)`. "
+                                "To opt-in to the future "
+                                "behavior, set "
+                                "`pd.set_option('future.no_silent_downcasting', True)`",
+                                FutureWarning,
+                                stacklevel=find_stack_level(),
+                            )
+                        nbs.extend(converted)
+                    result = nbs
+                new_rb.extend(result)
+            rb = new_rb
+        return rb
+
+    @final
+    def _replace_coerce(
+        self,
+        to_replace,
+        value,
+        mask: npt.NDArray[np.bool_],
+        inplace: bool = True,
+        regex: bool = False,
+        using_cow: bool = False,
+        convert_string: bool = True,
+    ) -> list[Block]:
+        """
+        Replace value corresponding to the given boolean array with another
+        value.
+
+        Parameters
+        ----------
+        to_replace : object or pattern
+            Scalar to replace or regular expression to match.
+        value : object
+            Replacement object.
+        mask : np.ndarray[bool]
+            True indicate corresponding element is ignored.
+        inplace : bool, default True
+            Perform inplace modification.
+        regex : bool, default False
+            If true, perform regular expression substitution.
+
+        Returns
+        -------
+        List[Block]
+        """
+        if should_use_regex(regex, to_replace):
+            return self._replace_regex(
+                to_replace,
+                value,
+                inplace=inplace,
+                mask=mask,
+                using_cow=using_cow,
+                convert_string=convert_string,
+            )
+        else:
+            if value is None:
+                # gh-45601, gh-45836, gh-46634
+                if mask.any():
+                    has_ref = self.refs.has_reference()
+                    nb = self.astype(np.dtype(object), copy=False, using_cow=using_cow)
+                    if (nb is self or using_cow) and not inplace:
+                        nb = nb.copy()
+                    elif inplace and has_ref and nb.refs.has_reference() and using_cow:
+                        # no copy in astype and we had refs before
+                        nb = nb.copy()
+                    putmask_inplace(nb.values, mask, value)
+                    return [nb]
+                if using_cow:
+                    return [self.copy(deep=False)]
+                return [self] if inplace else [self.copy()]
+            return self.replace(
+                to_replace=to_replace,
+                value=value,
+                inplace=inplace,
+                mask=mask,
+                using_cow=using_cow,
+                convert_string=convert_string,
+            )
+
+    # ---------------------------------------------------------------------
+    # 2D Methods - Shared by NumpyBlock and NDArrayBackedExtensionBlock
+    #  but not ExtensionBlock
+
+    def _maybe_squeeze_arg(self, arg: np.ndarray) -> np.ndarray:
+        """
+        For compatibility with 1D-only ExtensionArrays.
+        """
+        return arg
+
+    def _unwrap_setitem_indexer(self, indexer):
+        """
+        For compatibility with 1D-only ExtensionArrays.
+        """
+        return indexer
+
+    # NB: this cannot be made cache_readonly because in mgr.set_values we pin
+    #  new .values that can have different shape GH#42631
+    @property
+    def shape(self) -> Shape:
+        return self.values.shape
+
+    def iget(self, i: int | tuple[int, int] | tuple[slice, int]) -> np.ndarray:
+        # In the case where we have a tuple[slice, int], the slice will always
+        #  be slice(None)
+        # Note: only reached with self.ndim == 2
+        # Invalid index type "Union[int, Tuple[int, int], Tuple[slice, int]]"
+        # for "Union[ndarray[Any, Any], ExtensionArray]"; expected type
+        # "Union[int, integer[Any]]"
+        return self.values[i]  # type: ignore[index]
+
+    def _slice(
+        self, slicer: slice | npt.NDArray[np.bool_] | npt.NDArray[np.intp]
+    ) -> ArrayLike:
+        """return a slice of my values"""
+
+        return self.values[slicer]
+
+    def set_inplace(self, locs, values: ArrayLike, copy: bool = False) -> None:
+        """
+        Modify block values in-place with new item value.
+
+        If copy=True, first copy the underlying values in place before modifying
+        (for Copy-on-Write).
+
+        Notes
+        -----
+        `set_inplace` never creates a new array or new Block, whereas `setitem`
+        _may_ create a new array and always creates a new Block.
+
+        Caller is responsible for checking values.dtype == self.dtype.
+        """
+        if copy:
+            self.values = self.values.copy()
+        self.values[locs] = values
+
+    @final
+    def take_nd(
+        self,
+        indexer: npt.NDArray[np.intp],
+        axis: AxisInt,
+        new_mgr_locs: BlockPlacement | None = None,
+        fill_value=lib.no_default,
+    ) -> Block:
+        """
+        Take values according to indexer and return them as a block.
+        """
+        values = self.values
+
+        if fill_value is lib.no_default:
+            fill_value = self.fill_value
+            allow_fill = False
+        else:
+            allow_fill = True
+
+        # Note: algos.take_nd has upcast logic similar to coerce_to_target_dtype
+        new_values = algos.take_nd(
+            values, indexer, axis=axis, allow_fill=allow_fill, fill_value=fill_value
+        )
+
+        # Called from three places in managers, all of which satisfy
+        #  these assertions
+        if isinstance(self, ExtensionBlock):
+            # NB: in this case, the 'axis' kwarg will be ignored in the
+            #  algos.take_nd call above.
+            assert not (self.ndim == 1 and new_mgr_locs is None)
+        assert not (axis == 0 and new_mgr_locs is None)
+
+        if new_mgr_locs is None:
+            new_mgr_locs = self._mgr_locs
+
+        if new_values.dtype != self.dtype:
+            return self.make_block(new_values, new_mgr_locs)
+        else:
+            return self.make_block_same_class(new_values, new_mgr_locs)
+
+    def _unstack(
+        self,
+        unstacker,
+        fill_value,
+        new_placement: npt.NDArray[np.intp],
+        needs_masking: npt.NDArray[np.bool_],
+    ):
+        """
+        Return a list of unstacked blocks of self
+
+        Parameters
+        ----------
+        unstacker : reshape._Unstacker
+        fill_value : int
+            Only used in ExtensionBlock._unstack
+        new_placement : np.ndarray[np.intp]
+        allow_fill : bool
+        needs_masking : np.ndarray[bool]
+
+        Returns
+        -------
+        blocks : list of Block
+            New blocks of unstacked values.
+        mask : array-like of bool
+            The mask of columns of `blocks` we should keep.
+        """
+        new_values, mask = unstacker.get_new_values(
+            self.values.T, fill_value=fill_value
+        )
+
+        mask = mask.any(0)
+        # TODO: in all tests we have mask.all(); can we rely on that?
+
+        # Note: these next two lines ensure that
+        #  mask.sum() == sum(len(nb.mgr_locs) for nb in blocks)
+        #  which the calling function needs in order to pass verify_integrity=False
+        #  to the BlockManager constructor
+        new_values = new_values.T[mask]
+        new_placement = new_placement[mask]
+
+        bp = BlockPlacement(new_placement)
+        blocks = [new_block_2d(new_values, placement=bp)]
+        return blocks, mask
+
+    # ---------------------------------------------------------------------
+
+    def setitem(self, indexer, value, using_cow: bool = False) -> Block:
+        """
+        Attempt self.values[indexer] = value, possibly creating a new array.
+
+        Parameters
+        ----------
+        indexer : tuple, list-like, array-like, slice, int
+            The subset of self.values to set
+        value : object
+            The value being set
+        using_cow: bool, default False
+            Signaling if CoW is used.
+
+        Returns
+        -------
+        Block
+
+        Notes
+        -----
+        `indexer` is a direct slice/positional indexer. `value` must
+        be a compatible shape.
+        """
+
+        value = self._standardize_fill_value(value)
+
+        values = cast(np.ndarray, self.values)
+        if self.ndim == 2:
+            values = values.T
+
+        # length checking
+        check_setitem_lengths(indexer, value, values)
+
+        if self.dtype != _dtype_obj:
+            # GH48933: extract_array would convert a pd.Series value to np.ndarray
+            value = extract_array(value, extract_numpy=True)
+        try:
+            casted = np_can_hold_element(values.dtype, value)
+        except LossySetitemError:
+            # current dtype cannot store value, coerce to common dtype
+            nb = self.coerce_to_target_dtype(value, warn_on_upcast=True)
+            return nb.setitem(indexer, value)
+        else:
+            if self.dtype == _dtype_obj:
+                # TODO: avoid having to construct values[indexer]
+                vi = values[indexer]
+                if lib.is_list_like(vi):
+                    # checking lib.is_scalar here fails on
+                    #  test_iloc_setitem_custom_object
+                    casted = setitem_datetimelike_compat(values, len(vi), casted)
+
+            self = self._maybe_copy(using_cow, inplace=True)
+            values = cast(np.ndarray, self.values.T)
+            if isinstance(casted, np.ndarray) and casted.ndim == 1 and len(casted) == 1:
+                # NumPy 1.25 deprecation: https://github.com/numpy/numpy/pull/10615
+                casted = casted[0, ...]
+            try:
+                values[indexer] = casted
+            except (TypeError, ValueError) as err:
+                if is_list_like(casted):
+                    raise ValueError(
+                        "setting an array element with a sequence."
+                    ) from err
+                raise
+        return self
+
+    def putmask(
+        self, mask, new, using_cow: bool = False, already_warned=None
+    ) -> list[Block]:
+        """
+        putmask the data to the block; it is possible that we may create a
+        new dtype of block
+
+        Return the resulting block(s).
+
+        Parameters
+        ----------
+        mask : np.ndarray[bool], SparseArray[bool], or BooleanArray
+        new : a ndarray/object
+        using_cow: bool, default False
+
+        Returns
+        -------
+        List[Block]
+        """
+        orig_mask = mask
+        values = cast(np.ndarray, self.values)
+        mask, noop = validate_putmask(values.T, mask)
+        assert not isinstance(new, (ABCIndex, ABCSeries, ABCDataFrame))
+
+        if new is lib.no_default:
+            new = self.fill_value
+
+        new = self._standardize_fill_value(new)
+        new = extract_array(new, extract_numpy=True)
+
+        if noop:
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self]
+
+        if (
+            warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+
+        try:
+            casted = np_can_hold_element(values.dtype, new)
+
+            self = self._maybe_copy(using_cow, inplace=True)
+            values = cast(np.ndarray, self.values)
+
+            putmask_without_repeat(values.T, mask, casted)
+            return [self]
+        except LossySetitemError:
+            if self.ndim == 1 or self.shape[0] == 1:
+                # no need to split columns
+
+                if not is_list_like(new):
+                    # using just new[indexer] can't save us the need to cast
+                    return self.coerce_to_target_dtype(
+                        new, warn_on_upcast=True
+                    ).putmask(mask, new)
+                else:
+                    indexer = mask.nonzero()[0]
+                    nb = self.setitem(indexer, new[indexer], using_cow=using_cow)
+                    return [nb]
+
+            else:
+                is_array = isinstance(new, np.ndarray)
+
+                res_blocks = []
+                nbs = self._split()
+                for i, nb in enumerate(nbs):
+                    n = new
+                    if is_array:
+                        # we have a different value per-column
+                        n = new[:, i : i + 1]
+
+                    submask = orig_mask[:, i : i + 1]
+                    rbs = nb.putmask(submask, n, using_cow=using_cow)
+                    res_blocks.extend(rbs)
+                return res_blocks
+
+    def where(
+        self, other, cond, _downcast: str | bool = "infer", using_cow: bool = False
+    ) -> list[Block]:
+        """
+        evaluate the block; return result block(s) from the result
+
+        Parameters
+        ----------
+        other : a ndarray/object
+        cond : np.ndarray[bool], SparseArray[bool], or BooleanArray
+        _downcast : str or None, default "infer"
+            Private because we only specify it when calling from fillna.
+
+        Returns
+        -------
+        List[Block]
+        """
+        assert cond.ndim == self.ndim
+        assert not isinstance(other, (ABCIndex, ABCSeries, ABCDataFrame))
+
+        transpose = self.ndim == 2
+
+        cond = extract_bool_array(cond)
+
+        # EABlocks override where
+        values = cast(np.ndarray, self.values)
+        orig_other = other
+        if transpose:
+            values = values.T
+
+        icond, noop = validate_putmask(values, ~cond)
+        if noop:
+            # GH-39595: Always return a copy; short-circuit up/downcasting
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self.copy()]
+
+        if other is lib.no_default:
+            other = self.fill_value
+
+        other = self._standardize_fill_value(other)
+
+        try:
+            # try/except here is equivalent to a self._can_hold_element check,
+            #  but this gets us back 'casted' which we will reuse below;
+            #  without using 'casted', expressions.where may do unwanted upcasts.
+            casted = np_can_hold_element(values.dtype, other)
+        except (ValueError, TypeError, LossySetitemError):
+            # we cannot coerce, return a compat dtype
+
+            if self.ndim == 1 or self.shape[0] == 1:
+                # no need to split columns
+
+                block = self.coerce_to_target_dtype(other)
+                blocks = block.where(orig_other, cond, using_cow=using_cow)
+                return self._maybe_downcast(
+                    blocks, downcast=_downcast, using_cow=using_cow, caller="where"
+                )
+
+            else:
+                # since _maybe_downcast would split blocks anyway, we
+                #  can avoid some potential upcast/downcast by splitting
+                #  on the front end.
+                is_array = isinstance(other, (np.ndarray, ExtensionArray))
+
+                res_blocks = []
+                nbs = self._split()
+                for i, nb in enumerate(nbs):
+                    oth = other
+                    if is_array:
+                        # we have a different value per-column
+                        oth = other[:, i : i + 1]
+
+                    submask = cond[:, i : i + 1]
+                    rbs = nb.where(
+                        oth, submask, _downcast=_downcast, using_cow=using_cow
+                    )
+                    res_blocks.extend(rbs)
+                return res_blocks
+
+        else:
+            other = casted
+            alt = setitem_datetimelike_compat(values, icond.sum(), other)
+            if alt is not other:
+                if is_list_like(other) and len(other) < len(values):
+                    # call np.where with other to get the appropriate ValueError
+                    np.where(~icond, values, other)
+                    raise NotImplementedError(
+                        "This should not be reached; call to np.where above is "
+                        "expected to raise ValueError. Please report a bug at "
+                        "github.com/pandas-dev/pandas"
+                    )
+                result = values.copy()
+                np.putmask(result, icond, alt)
+            else:
+                # By the time we get here, we should have all Series/Index
+                #  args extracted to ndarray
+                if (
+                    is_list_like(other)
+                    and not isinstance(other, np.ndarray)
+                    and len(other) == self.shape[-1]
+                ):
+                    # If we don't do this broadcasting here, then expressions.where
+                    #  will broadcast a 1D other to be row-like instead of
+                    #  column-like.
+                    other = np.array(other).reshape(values.shape)
+                    # If lengths don't match (or len(other)==1), we will raise
+                    #  inside expressions.where, see test_series_where
+
+                # Note: expressions.where may upcast.
+                result = expressions.where(~icond, values, other)
+                # The np_can_hold_element check _should_ ensure that we always
+                #  have result.dtype == self.dtype here.
+
+        if transpose:
+            result = result.T
+
+        return [self.make_block(result)]
+
+    def fillna(
+        self,
+        value,
+        limit: int | None = None,
+        inplace: bool = False,
+        downcast=None,
+        using_cow: bool = False,
+        already_warned=None,
+    ) -> list[Block]:
+        """
+        fillna on the block with the value. If we fail, then convert to
+        block to hold objects instead and try again
+        """
+        # Caller is responsible for validating limit; if int it is strictly positive
+        inplace = validate_bool_kwarg(inplace, "inplace")
+
+        if not self._can_hold_na:
+            # can short-circuit the isna call
+            noop = True
+        else:
+            mask = isna(self.values)
+            mask, noop = validate_putmask(self.values, mask)
+
+        if noop:
+            # we can't process the value, but nothing to do
+            if inplace:
+                if using_cow:
+                    return [self.copy(deep=False)]
+                # Arbitrarily imposing the convention that we ignore downcast
+                #  on no-op when inplace=True
+                return [self]
+            else:
+                # GH#45423 consistent downcasting on no-ops.
+                nb = self.copy(deep=not using_cow)
+                nbs = nb._maybe_downcast(
+                    [nb], downcast=downcast, using_cow=using_cow, caller="fillna"
+                )
+                return nbs
+
+        if limit is not None:
+            mask[mask.cumsum(self.values.ndim - 1) > limit] = False
+
+        if inplace:
+            nbs = self.putmask(
+                mask.T, value, using_cow=using_cow, already_warned=already_warned
+            )
+        else:
+            # without _downcast, we would break
+            #  test_fillna_dtype_conversion_equiv_replace
+            nbs = self.where(value, ~mask.T, _downcast=False)
+
+        # Note: blk._maybe_downcast vs self._maybe_downcast(nbs)
+        #  makes a difference bc blk may have object dtype, which has
+        #  different behavior in _maybe_downcast.
+        return extend_blocks(
+            [
+                blk._maybe_downcast(
+                    [blk], downcast=downcast, using_cow=using_cow, caller="fillna"
+                )
+                for blk in nbs
+            ]
+        )
+
+    def pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        axis: AxisInt = 0,
+        inplace: bool = False,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: Literal["infer"] | None = None,
+        using_cow: bool = False,
+        already_warned=None,
+    ) -> list[Block]:
+        if not self._can_hold_na:
+            # If there are no NAs, then interpolate is a no-op
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self] if inplace else [self.copy()]
+
+        copy, refs = self._get_refs_and_copy(using_cow, inplace)
+
+        # Dispatch to the NumpyExtensionArray method.
+        # We know self.array_values is a NumpyExtensionArray bc EABlock overrides
+        vals = cast(NumpyExtensionArray, self.array_values)
+        if axis == 1:
+            vals = vals.T
+        new_values = vals._pad_or_backfill(
+            method=method,
+            limit=limit,
+            limit_area=limit_area,
+            copy=copy,
+        )
+        if (
+            not copy
+            and warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+        if axis == 1:
+            new_values = new_values.T
+
+        data = extract_array(new_values, extract_numpy=True)
+
+        nb = self.make_block_same_class(data, refs=refs)
+        return nb._maybe_downcast([nb], downcast, using_cow, caller="fillna")
+
+    @final
+    def interpolate(
+        self,
+        *,
+        method: InterpolateOptions,
+        index: Index,
+        inplace: bool = False,
+        limit: int | None = None,
+        limit_direction: Literal["forward", "backward", "both"] = "forward",
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: Literal["infer"] | None = None,
+        using_cow: bool = False,
+        already_warned=None,
+        **kwargs,
+    ) -> list[Block]:
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        # error: Non-overlapping equality check [...]
+        if method == "asfreq":  # type: ignore[comparison-overlap]
+            # clean_fill_method used to allow this
+            missing.clean_fill_method(method)
+
+        if not self._can_hold_na:
+            # If there are no NAs, then interpolate is a no-op
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self] if inplace else [self.copy()]
+
+        # TODO(3.0): this case will not be reachable once GH#53638 is enforced
+        if self.dtype == _dtype_obj:
+            # only deal with floats
+            # bc we already checked that can_hold_na, we don't have int dtype here
+            # test_interp_basic checks that we make a copy here
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self] if inplace else [self.copy()]
+
+        copy, refs = self._get_refs_and_copy(using_cow, inplace)
+
+        # Dispatch to the EA method.
+        new_values = self.array_values.interpolate(
+            method=method,
+            axis=self.ndim - 1,
+            index=index,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            copy=copy,
+            **kwargs,
+        )
+        data = extract_array(new_values, extract_numpy=True)
+
+        if (
+            not copy
+            and warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+
+        nb = self.make_block_same_class(data, refs=refs)
+        return nb._maybe_downcast([nb], downcast, using_cow, caller="interpolate")
+
+    @final
+    def diff(self, n: int) -> list[Block]:
+        """return block for the diff of the values"""
+        # only reached with ndim == 2
+        # TODO(EA2D): transpose will be unnecessary with 2D EAs
+        new_values = algos.diff(self.values.T, n, axis=0).T
+        return [self.make_block(values=new_values)]
+
+    def shift(self, periods: int, fill_value: Any = None) -> list[Block]:
+        """shift the block by periods, possibly upcast"""
+        # convert integer to float if necessary. need to do a lot more than
+        # that, handle boolean etc also
+        axis = self.ndim - 1
+
+        # Note: periods is never 0 here, as that is handled at the top of
+        #  NDFrame.shift.  If that ever changes, we can do a check for periods=0
+        #  and possibly avoid coercing.
+
+        if not lib.is_scalar(fill_value) and self.dtype != _dtype_obj:
+            # with object dtype there is nothing to promote, and the user can
+            #  pass pretty much any weird fill_value they like
+            # see test_shift_object_non_scalar_fill
+            raise ValueError("fill_value must be a scalar")
+
+        fill_value = self._standardize_fill_value(fill_value)
+
+        try:
+            # error: Argument 1 to "np_can_hold_element" has incompatible type
+            # "Union[dtype[Any], ExtensionDtype]"; expected "dtype[Any]"
+            casted = np_can_hold_element(
+                self.dtype, fill_value  # type: ignore[arg-type]
+            )
+        except LossySetitemError:
+            nb = self.coerce_to_target_dtype(fill_value)
+            return nb.shift(periods, fill_value=fill_value)
+
+        else:
+            values = cast(np.ndarray, self.values)
+            new_values = shift(values, periods, axis, casted)
+            return [self.make_block_same_class(new_values)]
+
+    @final
+    def quantile(
+        self,
+        qs: Index,  # with dtype float64
+        interpolation: QuantileInterpolation = "linear",
+    ) -> Block:
+        """
+        compute the quantiles of the
+
+        Parameters
+        ----------
+        qs : Index
+            The quantiles to be computed in float64.
+        interpolation : str, default 'linear'
+            Type of interpolation.
+
+        Returns
+        -------
+        Block
+        """
+        # We should always have ndim == 2 because Series dispatches to DataFrame
+        assert self.ndim == 2
+        assert is_list_like(qs)  # caller is responsible for this
+
+        result = quantile_compat(self.values, np.asarray(qs._values), interpolation)
+        # ensure_block_shape needed for cases where we start with EA and result
+        #  is ndarray, e.g. IntegerArray, SparseArray
+        result = ensure_block_shape(result, ndim=2)
+        return new_block_2d(result, placement=self._mgr_locs)
+
+    @final
+    def round(self, decimals: int, using_cow: bool = False) -> Self:
+        """
+        Rounds the values.
+        If the block is not of an integer or float dtype, nothing happens.
+        This is consistent with DataFrame.round behavivor.
+        (Note: Series.round would raise)
+
+        Parameters
+        ----------
+        decimals: int,
+            Number of decimal places to round to.
+            Caller is responsible for validating this
+        using_cow: bool,
+            Whether Copy on Write is enabled right now
+        """
+        if not self.is_numeric or self.is_bool:
+            return self.copy(deep=not using_cow)
+        refs = None
+        # TODO: round only defined on BaseMaskedArray
+        # Series also does this, so would need to fix both places
+        # error: Item "ExtensionArray" of "Union[ndarray[Any, Any], ExtensionArray]"
+        # has no attribute "round"
+        values = self.values.round(decimals)  # type: ignore[union-attr]
+        if values is self.values:
+            if not using_cow:
+                # Normally would need to do this before, but
+                # numpy only returns same array when round operation
+                # is no-op
+                # https://github.com/numpy/numpy/blob/486878b37fc7439a3b2b87747f50db9b62fea8eb/numpy/core/src/multiarray/calculation.c#L625-L636
+                values = values.copy()
+            else:
+                refs = self.refs
+        return self.make_block_same_class(values, refs=refs)
+
+    # ---------------------------------------------------------------------
+    # Abstract Methods Overridden By EABackedBlock and NumpyBlock
+
+    def delete(self, loc) -> list[Block]:
+        """Deletes the locs from the block.
+
+        We split the block to avoid copying the underlying data. We create new
+        blocks for every connected segment of the initial block that is not deleted.
+        The new blocks point to the initial array.
+        """
+        if not is_list_like(loc):
+            loc = [loc]
+
+        if self.ndim == 1:
+            values = cast(np.ndarray, self.values)
+            values = np.delete(values, loc)
+            mgr_locs = self._mgr_locs.delete(loc)
+            return [type(self)(values, placement=mgr_locs, ndim=self.ndim)]
+
+        if np.max(loc) >= self.values.shape[0]:
+            raise IndexError
+
+        # Add one out-of-bounds indexer as maximum to collect
+        # all columns after our last indexer if any
+        loc = np.concatenate([loc, [self.values.shape[0]]])
+        mgr_locs_arr = self._mgr_locs.as_array
+        new_blocks: list[Block] = []
+
+        previous_loc = -1
+        # TODO(CoW): This is tricky, if parent block goes out of scope
+        # all split blocks are referencing each other even though they
+        # don't share data
+        refs = self.refs if self.refs.has_reference() else None
+        for idx in loc:
+            if idx == previous_loc + 1:
+                # There is no column between current and last idx
+                pass
+            else:
+                # No overload variant of "__getitem__" of "ExtensionArray" matches
+                # argument type "Tuple[slice, slice]"
+                values = self.values[previous_loc + 1 : idx, :]  # type: ignore[call-overload]
+                locs = mgr_locs_arr[previous_loc + 1 : idx]
+                nb = type(self)(
+                    values, placement=BlockPlacement(locs), ndim=self.ndim, refs=refs
+                )
+                new_blocks.append(nb)
+
+            previous_loc = idx
+
+        return new_blocks
+
+    @property
+    def is_view(self) -> bool:
+        """return a boolean if I am possibly a view"""
+        raise AbstractMethodError(self)
+
+    @property
+    def array_values(self) -> ExtensionArray:
+        """
+        The array that Series.array returns. Always an ExtensionArray.
+        """
+        raise AbstractMethodError(self)
+
+    def get_values(self, dtype: DtypeObj | None = None) -> np.ndarray:
+        """
+        return an internal format, currently just the ndarray
+        this is often overridden to handle to_dense like operations
+        """
+        raise AbstractMethodError(self)
+
+
+class EABackedBlock(Block):
+    """
+    Mixin for Block subclasses backed by ExtensionArray.
+    """
+
+    values: ExtensionArray
+
+    @final
+    def shift(self, periods: int, fill_value: Any = None) -> list[Block]:
+        """
+        Shift the block by `periods`.
+
+        Dispatches to underlying ExtensionArray and re-boxes in an
+        ExtensionBlock.
+        """
+        # Transpose since EA.shift is always along axis=0, while we want to shift
+        #  along rows.
+        new_values = self.values.T.shift(periods=periods, fill_value=fill_value).T
+        return [self.make_block_same_class(new_values)]
+
+    @final
+    def setitem(self, indexer, value, using_cow: bool = False):
+        """
+        Attempt self.values[indexer] = value, possibly creating a new array.
+
+        This differs from Block.setitem by not allowing setitem to change
+        the dtype of the Block.
+
+        Parameters
+        ----------
+        indexer : tuple, list-like, array-like, slice, int
+            The subset of self.values to set
+        value : object
+            The value being set
+        using_cow: bool, default False
+            Signaling if CoW is used.
+
+        Returns
+        -------
+        Block
+
+        Notes
+        -----
+        `indexer` is a direct slice/positional indexer. `value` must
+        be a compatible shape.
+        """
+        orig_indexer = indexer
+        orig_value = value
+
+        indexer = self._unwrap_setitem_indexer(indexer)
+        value = self._maybe_squeeze_arg(value)
+
+        values = self.values
+        if values.ndim == 2:
+            # TODO(GH#45419): string[pyarrow] tests break if we transpose
+            #  unconditionally
+            values = values.T
+        check_setitem_lengths(indexer, value, values)
+
+        try:
+            values[indexer] = value
+        except (ValueError, TypeError):
+            if isinstance(self.dtype, IntervalDtype):
+                # see TestSetitemFloatIntervalWithIntIntervalValues
+                nb = self.coerce_to_target_dtype(orig_value, warn_on_upcast=True)
+                return nb.setitem(orig_indexer, orig_value)
+
+            elif isinstance(self, NDArrayBackedExtensionBlock):
+                nb = self.coerce_to_target_dtype(orig_value, warn_on_upcast=True)
+                return nb.setitem(orig_indexer, orig_value)
+
+            else:
+                raise
+
+        else:
+            return self
+
+    @final
+    def where(
+        self, other, cond, _downcast: str | bool = "infer", using_cow: bool = False
+    ) -> list[Block]:
+        # _downcast private bc we only specify it when calling from fillna
+        arr = self.values.T
+
+        cond = extract_bool_array(cond)
+
+        orig_other = other
+        orig_cond = cond
+        other = self._maybe_squeeze_arg(other)
+        cond = self._maybe_squeeze_arg(cond)
+
+        if other is lib.no_default:
+            other = self.fill_value
+
+        icond, noop = validate_putmask(arr, ~cond)
+        if noop:
+            # GH#44181, GH#45135
+            # Avoid a) raising for Interval/PeriodDtype and b) unnecessary object upcast
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self.copy()]
+
+        try:
+            res_values = arr._where(cond, other).T
+        except (ValueError, TypeError):
+            if self.ndim == 1 or self.shape[0] == 1:
+                if isinstance(self.dtype, (IntervalDtype, StringDtype)):
+                    # TestSetitemFloatIntervalWithIntIntervalValues
+                    blk = self.coerce_to_target_dtype(orig_other)
+                    if (
+                        self.ndim == 2
+                        and isinstance(orig_cond, np.ndarray)
+                        and orig_cond.ndim == 1
+                        and not is_1d_only_ea_dtype(blk.dtype)
+                    ):
+                        orig_cond = orig_cond[:, None]
+                    nbs = blk.where(orig_other, orig_cond, using_cow=using_cow)
+                    return self._maybe_downcast(
+                        nbs, downcast=_downcast, using_cow=using_cow, caller="where"
+                    )
+
+                elif isinstance(self, NDArrayBackedExtensionBlock):
+                    # NB: not (yet) the same as
+                    #  isinstance(values, NDArrayBackedExtensionArray)
+                    blk = self.coerce_to_target_dtype(orig_other)
+                    nbs = blk.where(orig_other, orig_cond, using_cow=using_cow)
+                    return self._maybe_downcast(
+                        nbs, downcast=_downcast, using_cow=using_cow, caller="where"
+                    )
+
+                else:
+                    raise
+
+            else:
+                # Same pattern we use in Block.putmask
+                is_array = isinstance(orig_other, (np.ndarray, ExtensionArray))
+
+                res_blocks = []
+                nbs = self._split()
+                for i, nb in enumerate(nbs):
+                    n = orig_other
+                    if is_array:
+                        # we have a different value per-column
+                        n = orig_other[:, i : i + 1]
+
+                    submask = orig_cond[:, i : i + 1]
+                    rbs = nb.where(n, submask, using_cow=using_cow)
+                    res_blocks.extend(rbs)
+                return res_blocks
+
+        nb = self.make_block_same_class(res_values)
+        return [nb]
+
+    @final
+    def putmask(
+        self, mask, new, using_cow: bool = False, already_warned=None
+    ) -> list[Block]:
+        """
+        See Block.putmask.__doc__
+        """
+        mask = extract_bool_array(mask)
+        if new is lib.no_default:
+            new = self.fill_value
+
+        orig_new = new
+        orig_mask = mask
+        new = self._maybe_squeeze_arg(new)
+        mask = self._maybe_squeeze_arg(mask)
+
+        if not mask.any():
+            if using_cow:
+                return [self.copy(deep=False)]
+            return [self]
+
+        if (
+            warn_copy_on_write()
+            and already_warned is not None
+            and not already_warned.warned_already
+        ):
+            if self.refs.has_reference():
+                warnings.warn(
+                    COW_WARNING_GENERAL_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                already_warned.warned_already = True
+
+        self = self._maybe_copy(using_cow, inplace=True)
+        values = self.values
+        if values.ndim == 2:
+            values = values.T
+
+        try:
+            # Caller is responsible for ensuring matching lengths
+            values._putmask(mask, new)
+        except (TypeError, ValueError):
+            if self.ndim == 1 or self.shape[0] == 1:
+                if isinstance(self.dtype, IntervalDtype):
+                    # Discussion about what we want to support in the general
+                    #  case GH#39584
+                    blk = self.coerce_to_target_dtype(orig_new, warn_on_upcast=True)
+                    return blk.putmask(orig_mask, orig_new)
+
+                elif isinstance(self, NDArrayBackedExtensionBlock):
+                    # NB: not (yet) the same as
+                    #  isinstance(values, NDArrayBackedExtensionArray)
+                    blk = self.coerce_to_target_dtype(orig_new, warn_on_upcast=True)
+                    return blk.putmask(orig_mask, orig_new)
+
+                else:
+                    raise
+
+            else:
+                # Same pattern we use in Block.putmask
+                is_array = isinstance(orig_new, (np.ndarray, ExtensionArray))
+
+                res_blocks = []
+                nbs = self._split()
+                for i, nb in enumerate(nbs):
+                    n = orig_new
+                    if is_array:
+                        # we have a different value per-column
+                        n = orig_new[:, i : i + 1]
+
+                    submask = orig_mask[:, i : i + 1]
+                    rbs = nb.putmask(submask, n)
+                    res_blocks.extend(rbs)
+                return res_blocks
+
+        return [self]
+
+    @final
+    def delete(self, loc) -> list[Block]:
+        # This will be unnecessary if/when __array_function__ is implemented
+        if self.ndim == 1:
+            values = self.values.delete(loc)
+            mgr_locs = self._mgr_locs.delete(loc)
+            return [type(self)(values, placement=mgr_locs, ndim=self.ndim)]
+        elif self.values.ndim == 1:
+            # We get here through to_stata
+            return []
+        return super().delete(loc)
+
+    @final
+    @cache_readonly
+    def array_values(self) -> ExtensionArray:
+        return self.values
+
+    @final
+    def get_values(self, dtype: DtypeObj | None = None) -> np.ndarray:
+        """
+        return object dtype as boxed values, such as Timestamps/Timedelta
+        """
+        values: ArrayLike = self.values
+        if dtype == _dtype_obj:
+            values = values.astype(object)
+        # TODO(EA2D): reshape not needed with 2D EAs
+        return np.asarray(values).reshape(self.shape)
+
+    @final
+    def pad_or_backfill(
+        self,
+        *,
+        method: FillnaOptions,
+        axis: AxisInt = 0,
+        inplace: bool = False,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        downcast: Literal["infer"] | None = None,
+        using_cow: bool = False,
+        already_warned=None,
+    ) -> list[Block]:
+        values = self.values
+
+        kwargs: dict[str, Any] = {"method": method, "limit": limit}
+        if "limit_area" in inspect.signature(values._pad_or_backfill).parameters:
+            kwargs["limit_area"] = limit_area
+        elif limit_area is not None:
+            raise NotImplementedError(
+                f"{type(values).__name__} does not implement limit_area "
+                "(added in pandas 2.2). 3rd-party ExtnsionArray authors "
+                "need to add this argument to _pad_or_backfill."
+            )
+
+        if values.ndim == 2 and axis == 1:
+            # NDArrayBackedExtensionArray.fillna assumes axis=0
+            new_values = values.T._pad_or_backfill(**kwargs).T
+        else:
+            new_values = values._pad_or_backfill(**kwargs)
+        return [self.make_block_same_class(new_values)]
+
+
+class ExtensionBlock(EABackedBlock):
+    """
+    Block for holding extension types.
+
+    Notes
+    -----
+    This holds all 3rd-party extension array types. It's also the immediate
+    parent class for our internal extension types' blocks.
+
+    ExtensionArrays are limited to 1-D.
+    """
+
+    values: ExtensionArray
+
+    def fillna(
+        self,
+        value,
+        limit: int | None = None,
+        inplace: bool = False,
+        downcast=None,
+        using_cow: bool = False,
+        already_warned=None,
+    ) -> list[Block]:
+        if isinstance(self.dtype, (IntervalDtype, StringDtype)):
+            # Block.fillna handles coercion (test_fillna_interval)
+            return super().fillna(
+                value=value,
+                limit=limit,
+                inplace=inplace,
+                downcast=downcast,
+                using_cow=using_cow,
+                already_warned=already_warned,
+            )
+        if using_cow and self._can_hold_na and not self.values._hasna:
+            refs = self.refs
+            new_values = self.values
+        else:
+            copy, refs = self._get_refs_and_copy(using_cow, inplace)
+
+            try:
+                new_values = self.values.fillna(
+                    value=value, method=None, limit=limit, copy=copy
+                )
+            except TypeError:
+                # 3rd party EA that has not implemented copy keyword yet
+                refs = None
+                new_values = self.values.fillna(value=value, method=None, limit=limit)
+                # issue the warning *after* retrying, in case the TypeError
+                #  was caused by an invalid fill_value
+                warnings.warn(
+                    # GH#53278
+                    "ExtensionArray.fillna added a 'copy' keyword in pandas "
+                    "2.1.0. In a future version, ExtensionArray subclasses will "
+                    "need to implement this keyword or an exception will be "
+                    "raised. In the interim, the keyword is ignored by "
+                    f"{type(self.values).__name__}.",
+                    DeprecationWarning,
+                    stacklevel=find_stack_level(),
+                )
+            else:
+                if (
+                    not copy
+                    and warn_copy_on_write()
+                    and already_warned is not None
+                    and not already_warned.warned_already
+                ):
+                    if self.refs.has_reference():
+                        warnings.warn(
+                            COW_WARNING_GENERAL_MSG,
+                            FutureWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                        already_warned.warned_already = True
+
+        nb = self.make_block_same_class(new_values, refs=refs)
+        return nb._maybe_downcast([nb], downcast, using_cow=using_cow, caller="fillna")
+
+    @cache_readonly
+    def shape(self) -> Shape:
+        # TODO(EA2D): override unnecessary with 2D EAs
+        if self.ndim == 1:
+            return (len(self.values),)
+        return len(self._mgr_locs), len(self.values)
+
+    def iget(self, i: int | tuple[int, int] | tuple[slice, int]):
+        # In the case where we have a tuple[slice, int], the slice will always
+        #  be slice(None)
+        # We _could_ make the annotation more specific, but mypy would
+        #  complain about override mismatch:
+        #  Literal[0] | tuple[Literal[0], int] | tuple[slice, int]
+
+        # Note: only reached with self.ndim == 2
+
+        if isinstance(i, tuple):
+            # TODO(EA2D): unnecessary with 2D EAs
+            col, loc = i
+            if not com.is_null_slice(col) and col != 0:
+                raise IndexError(f"{self} only contains one item")
+            if isinstance(col, slice):
+                # the is_null_slice check above assures that col is slice(None)
+                #  so what we want is a view on all our columns and row loc
+                if loc < 0:
+                    loc += len(self.values)
+                # Note: loc:loc+1 vs [[loc]] makes a difference when called
+                #  from fast_xs because we want to get a view back.
+                return self.values[loc : loc + 1]
+            return self.values[loc]
+        else:
+            if i != 0:
+                raise IndexError(f"{self} only contains one item")
+            return self.values
+
+    def set_inplace(self, locs, values: ArrayLike, copy: bool = False) -> None:
+        # When an ndarray, we should have locs.tolist() == [0]
+        # When a BlockPlacement we should have list(locs) == [0]
+        if copy:
+            self.values = self.values.copy()
+        self.values[:] = values
+
+    def _maybe_squeeze_arg(self, arg):
+        """
+        If necessary, squeeze a (N, 1) ndarray to (N,)
+        """
+        # e.g. if we are passed a 2D mask for putmask
+        if (
+            isinstance(arg, (np.ndarray, ExtensionArray))
+            and arg.ndim == self.values.ndim + 1
+        ):
+            # TODO(EA2D): unnecessary with 2D EAs
+            assert arg.shape[1] == 1
+            # error: No overload variant of "__getitem__" of "ExtensionArray"
+            # matches argument type "Tuple[slice, int]"
+            arg = arg[:, 0]  # type: ignore[call-overload]
+        elif isinstance(arg, ABCDataFrame):
+            # 2022-01-06 only reached for setitem
+            # TODO: should we avoid getting here with DataFrame?
+            assert arg.shape[1] == 1
+            arg = arg._ixs(0, axis=1)._values
+
+        return arg
+
+    def _unwrap_setitem_indexer(self, indexer):
+        """
+        Adapt a 2D-indexer to our 1D values.
+
+        This is intended for 'setitem', not 'iget' or '_slice'.
+        """
+        # TODO: ATM this doesn't work for iget/_slice, can we change that?
+
+        if isinstance(indexer, tuple) and len(indexer) == 2:
+            # TODO(EA2D): not needed with 2D EAs
+            #  Should never have length > 2.  Caller is responsible for checking.
+            #  Length 1 is reached vis setitem_single_block and setitem_single_column
+            #  each of which pass indexer=(pi,)
+            if all(isinstance(x, np.ndarray) and x.ndim == 2 for x in indexer):
+                # GH#44703 went through indexing.maybe_convert_ix
+                first, second = indexer
+                if not (
+                    second.size == 1 and (second == 0).all() and first.shape[1] == 1
+                ):
+                    raise NotImplementedError(
+                        "This should not be reached. Please report a bug at "
+                        "github.com/pandas-dev/pandas/"
+                    )
+                indexer = first[:, 0]
+
+            elif lib.is_integer(indexer[1]) and indexer[1] == 0:
+                # reached via setitem_single_block passing the whole indexer
+                indexer = indexer[0]
+
+            elif com.is_null_slice(indexer[1]):
+                indexer = indexer[0]
+
+            elif is_list_like(indexer[1]) and indexer[1][0] == 0:
+                indexer = indexer[0]
+
+            else:
+                raise NotImplementedError(
+                    "This should not be reached. Please report a bug at "
+                    "github.com/pandas-dev/pandas/"
+                )
+        return indexer
+
+    @property
+    def is_view(self) -> bool:
+        """Extension arrays are never treated as views."""
+        return False
+
+    # error: Cannot override writeable attribute with read-only property
+    @cache_readonly
+    def is_numeric(self) -> bool:  # type: ignore[override]
+        return self.values.dtype._is_numeric
+
+    def _slice(
+        self, slicer: slice | npt.NDArray[np.bool_] | npt.NDArray[np.intp]
+    ) -> ExtensionArray:
+        """
+        Return a slice of my values.
+
+        Parameters
+        ----------
+        slicer : slice, ndarray[int], or ndarray[bool]
+            Valid (non-reducing) indexer for self.values.
+
+        Returns
+        -------
+        ExtensionArray
+        """
+        # Notes: ndarray[bool] is only reachable when via get_rows_with_mask, which
+        #  is only for Series, i.e. self.ndim == 1.
+
+        # return same dims as we currently have
+        if self.ndim == 2:
+            # reached via getitem_block via _slice_take_blocks_ax0
+            # TODO(EA2D): won't be necessary with 2D EAs
+
+            if not isinstance(slicer, slice):
+                raise AssertionError(
+                    "invalid slicing for a 1-ndim ExtensionArray", slicer
+                )
+            # GH#32959 only full-slicers along fake-dim0 are valid
+            # TODO(EA2D): won't be necessary with 2D EAs
+            # range(1) instead of self._mgr_locs to avoid exception on [::-1]
+            #  see test_iloc_getitem_slice_negative_step_ea_block
+            new_locs = range(1)[slicer]
+            if not len(new_locs):
+                raise AssertionError(
+                    "invalid slicing for a 1-ndim ExtensionArray", slicer
+                )
+            slicer = slice(None)
+
+        return self.values[slicer]
+
+    @final
+    def slice_block_rows(self, slicer: slice) -> Self:
+        """
+        Perform __getitem__-like specialized to slicing along index.
+        """
+        # GH#42787 in principle this is equivalent to values[..., slicer], but we don't
+        # require subclasses of ExtensionArray to support that form (for now).
+        new_values = self.values[slicer]
+        return type(self)(new_values, self._mgr_locs, ndim=self.ndim, refs=self.refs)
+
+    def _unstack(
+        self,
+        unstacker,
+        fill_value,
+        new_placement: npt.NDArray[np.intp],
+        needs_masking: npt.NDArray[np.bool_],
+    ):
+        # ExtensionArray-safe unstack.
+        # We override Block._unstack, which unstacks directly on the
+        # values of the array. For EA-backed blocks, this would require
+        # converting to a 2-D ndarray of objects.
+        # Instead, we unstack an ndarray of integer positions, followed by
+        # a `take` on the actual values.
+
+        # Caller is responsible for ensuring self.shape[-1] == len(unstacker.index)
+        new_values, mask = unstacker.arange_result
+
+        # Note: these next two lines ensure that
+        #  mask.sum() == sum(len(nb.mgr_locs) for nb in blocks)
+        #  which the calling function needs in order to pass verify_integrity=False
+        #  to the BlockManager constructor
+        new_values = new_values.T[mask]
+        new_placement = new_placement[mask]
+
+        # needs_masking[i] calculated once in BlockManager.unstack tells
+        #  us if there are any -1s in the relevant indices.  When False,
+        #  that allows us to go through a faster path in 'take', among
+        #  other things avoiding e.g. Categorical._validate_scalar.
+        blocks = [
+            # TODO: could cast to object depending on fill_value?
+            type(self)(
+                self.values.take(
+                    indices, allow_fill=needs_masking[i], fill_value=fill_value
+                ),
+                BlockPlacement(place),
+                ndim=2,
+            )
+            for i, (indices, place) in enumerate(zip(new_values, new_placement))
+        ]
+        return blocks, mask
+
+
+class NumpyBlock(Block):
+    values: np.ndarray
+    __slots__ = ()
+
+    @property
+    def is_view(self) -> bool:
+        """return a boolean if I am possibly a view"""
+        return self.values.base is not None
+
+    @property
+    def array_values(self) -> ExtensionArray:
+        return NumpyExtensionArray(self.values)
+
+    def get_values(self, dtype: DtypeObj | None = None) -> np.ndarray:
+        if dtype == _dtype_obj:
+            return self.values.astype(_dtype_obj)
+        return self.values
+
+    @cache_readonly
+    def is_numeric(self) -> bool:  # type: ignore[override]
+        dtype = self.values.dtype
+        kind = dtype.kind
+
+        return kind in "fciub"
+
+
+class NumericBlock(NumpyBlock):
+    # this Block type is kept for backwards-compatibility
+    # TODO(3.0): delete and remove deprecation in __init__.py.
+    __slots__ = ()
+
+
+class ObjectBlock(NumpyBlock):
+    # this Block type is kept for backwards-compatibility
+    # TODO(3.0): delete and remove deprecation in __init__.py.
+    __slots__ = ()
+
+
+class NDArrayBackedExtensionBlock(EABackedBlock):
+    """
+    Block backed by an NDArrayBackedExtensionArray
+    """
+
+    values: NDArrayBackedExtensionArray
+
+    @property
+    def is_view(self) -> bool:
+        """return a boolean if I am possibly a view"""
+        # check the ndarray values of the DatetimeIndex values
+        return self.values._ndarray.base is not None
+
+
+class DatetimeLikeBlock(NDArrayBackedExtensionBlock):
+    """Block for datetime64[ns], timedelta64[ns]."""
+
+    __slots__ = ()
+    is_numeric = False
+    values: DatetimeArray | TimedeltaArray
+
+
+class DatetimeTZBlock(DatetimeLikeBlock):
+    """implement a datetime64 block with a tz attribute"""
+
+    values: DatetimeArray
+
+    __slots__ = ()
+
+
+# -----------------------------------------------------------------
+# Constructor Helpers
+
+
+def maybe_coerce_values(values: ArrayLike) -> ArrayLike:
+    """
+    Input validation for values passed to __init__. Ensure that
+    any datetime64/timedelta64 dtypes are in nanoseconds.  Ensure
+    that we do not have string dtypes.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+
+    Returns
+    -------
+    values : np.ndarray or ExtensionArray
+    """
+    # Caller is responsible for ensuring NumpyExtensionArray is already extracted.
+
+    if isinstance(values, np.ndarray):
+        values = ensure_wrapped_if_datetimelike(values)
+
+        if issubclass(values.dtype.type, str):
+            values = np.array(values, dtype=object)
+
+    if isinstance(values, (DatetimeArray, TimedeltaArray)) and values.freq is not None:
+        # freq is only stored in DatetimeIndex/TimedeltaIndex, not in Series/DataFrame
+        values = values._with_freq(None)
+
+    return values
+
+
+def get_block_type(dtype: DtypeObj) -> type[Block]:
+    """
+    Find the appropriate Block subclass to use for the given values and dtype.
+
+    Parameters
+    ----------
+    dtype : numpy or pandas dtype
+
+    Returns
+    -------
+    cls : class, subclass of Block
+    """
+    if isinstance(dtype, DatetimeTZDtype):
+        return DatetimeTZBlock
+    elif isinstance(dtype, PeriodDtype):
+        return NDArrayBackedExtensionBlock
+    elif isinstance(dtype, ExtensionDtype):
+        # Note: need to be sure NumpyExtensionArray is unwrapped before we get here
+        return ExtensionBlock
+
+    # We use kind checks because it is much more performant
+    #  than is_foo_dtype
+    kind = dtype.kind
+    if kind in "Mm":
+        return DatetimeLikeBlock
+
+    return NumpyBlock
+
+
+def new_block_2d(
+    values: ArrayLike, placement: BlockPlacement, refs: BlockValuesRefs | None = None
+):
+    # new_block specialized to case with
+    #  ndim=2
+    #  isinstance(placement, BlockPlacement)
+    #  check_ndim/ensure_block_shape already checked
+    klass = get_block_type(values.dtype)
+
+    values = maybe_coerce_values(values)
+    return klass(values, ndim=2, placement=placement, refs=refs)
+
+
+def new_block(
+    values,
+    placement: BlockPlacement,
+    *,
+    ndim: int,
+    refs: BlockValuesRefs | None = None,
+) -> Block:
+    # caller is responsible for ensuring:
+    # - values is NOT a NumpyExtensionArray
+    # - check_ndim/ensure_block_shape already checked
+    # - maybe_coerce_values already called/unnecessary
+    klass = get_block_type(values.dtype)
+    return klass(values, ndim=ndim, placement=placement, refs=refs)
+
+
+def check_ndim(values, placement: BlockPlacement, ndim: int) -> None:
+    """
+    ndim inference and validation.
+
+    Validates that values.ndim and ndim are consistent.
+    Validates that len(values) and len(placement) are consistent.
+
+    Parameters
+    ----------
+    values : array-like
+    placement : BlockPlacement
+    ndim : int
+
+    Raises
+    ------
+    ValueError : the number of dimensions do not match
+    """
+
+    if values.ndim > ndim:
+        # Check for both np.ndarray and ExtensionArray
+        raise ValueError(
+            "Wrong number of dimensions. "
+            f"values.ndim > ndim [{values.ndim} > {ndim}]"
+        )
+
+    if not is_1d_only_ea_dtype(values.dtype):
+        # TODO(EA2D): special case not needed with 2D EAs
+        if values.ndim != ndim:
+            raise ValueError(
+                "Wrong number of dimensions. "
+                f"values.ndim != ndim [{values.ndim} != {ndim}]"
+            )
+        if len(placement) != len(values):
+            raise ValueError(
+                f"Wrong number of items passed {len(values)}, "
+                f"placement implies {len(placement)}"
+            )
+    elif ndim == 2 and len(placement) != 1:
+        # TODO(EA2D): special case unnecessary with 2D EAs
+        raise ValueError("need to split")
+
+
+def extract_pandas_array(
+    values: ArrayLike, dtype: DtypeObj | None, ndim: int
+) -> tuple[ArrayLike, DtypeObj | None]:
+    """
+    Ensure that we don't allow NumpyExtensionArray / NumpyEADtype in internals.
+    """
+    # For now, blocks should be backed by ndarrays when possible.
+    if isinstance(values, ABCNumpyExtensionArray):
+        values = values.to_numpy()
+        if ndim and ndim > 1:
+            # TODO(EA2D): special case not needed with 2D EAs
+            values = np.atleast_2d(values)
+
+    if isinstance(dtype, NumpyEADtype):
+        dtype = dtype.numpy_dtype
+
+    return values, dtype
+
+
+# -----------------------------------------------------------------
+
+
+def extend_blocks(result, blocks=None) -> list[Block]:
+    """return a new extended blocks, given the result"""
+    if blocks is None:
+        blocks = []
+    if isinstance(result, list):
+        for r in result:
+            if isinstance(r, list):
+                blocks.extend(r)
+            else:
+                blocks.append(r)
+    else:
+        assert isinstance(result, Block), type(result)
+        blocks.append(result)
+    return blocks
+
+
+def ensure_block_shape(values: ArrayLike, ndim: int = 1) -> ArrayLike:
+    """
+    Reshape if possible to have values.ndim == ndim.
+    """
+
+    if values.ndim < ndim:
+        if not is_1d_only_ea_dtype(values.dtype):
+            # TODO(EA2D): https://github.com/pandas-dev/pandas/issues/23023
+            # block.shape is incorrect for "2D" ExtensionArrays
+            # We can't, and don't need to, reshape.
+            values = cast("np.ndarray | DatetimeArray | TimedeltaArray", values)
+            values = values.reshape(1, -1)
+
+    return values
+
+
+def external_values(values: ArrayLike) -> ArrayLike:
+    """
+    The array that Series.values returns (public attribute).
+
+    This has some historical constraints, and is overridden in block
+    subclasses to return the correct array (e.g. period returns
+    object ndarray and datetimetz a datetime64[ns] ndarray instead of
+    proper extension array).
+    """
+    if isinstance(values, (PeriodArray, IntervalArray)):
+        return values.astype(object)
+    elif isinstance(values, (DatetimeArray, TimedeltaArray)):
+        # NB: for datetime64tz this is different from np.asarray(values), since
+        #  that returns an object-dtype ndarray of Timestamps.
+        # Avoid raising in .astype in casting from dt64tz to dt64
+        values = values._ndarray
+
+    if isinstance(values, np.ndarray) and using_copy_on_write():
+        values = values.view()
+        values.flags.writeable = False
+
+    # TODO(CoW) we should also mark our ExtensionArrays as read-only
+
+    return values
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/concat.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/concat.py
new file mode 100644
index 0000000000000000000000000000000000000000..b2d463a8c6c26f62ded5a06283f29275612c9b40
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/concat.py
@@ -0,0 +1,598 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    algos as libalgos,
+    internals as libinternals,
+    lib,
+)
+from pandas._libs.missing import NA
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    ensure_dtype_can_hold_na,
+    find_common_type,
+)
+from pandas.core.dtypes.common import (
+    is_1d_only_ea_dtype,
+    is_scalar,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.dtypes import (
+    ExtensionDtype,
+    SparseDtype,
+)
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+    isna_all,
+)
+
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+from pandas.core.internals.array_manager import ArrayManager
+from pandas.core.internals.blocks import (
+    ensure_block_shape,
+    new_block_2d,
+)
+from pandas.core.internals.managers import (
+    BlockManager,
+    make_na_array,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        DtypeObj,
+        Manager2D,
+        Shape,
+    )
+
+    from pandas import Index
+    from pandas.core.internals.blocks import (
+        Block,
+        BlockPlacement,
+    )
+
+
+def _concatenate_array_managers(
+    mgrs: list[ArrayManager], axes: list[Index], concat_axis: AxisInt
+) -> Manager2D:
+    """
+    Concatenate array managers into one.
+
+    Parameters
+    ----------
+    mgrs_indexers : list of (ArrayManager, {axis: indexer,...}) tuples
+    axes : list of Index
+    concat_axis : int
+
+    Returns
+    -------
+    ArrayManager
+    """
+    if concat_axis == 1:
+        return mgrs[0].concat_vertical(mgrs, axes)
+    else:
+        # concatting along the columns -> combine reindexed arrays in a single manager
+        assert concat_axis == 0
+        return mgrs[0].concat_horizontal(mgrs, axes)
+
+
+def concatenate_managers(
+    mgrs_indexers, axes: list[Index], concat_axis: AxisInt, copy: bool
+) -> Manager2D:
+    """
+    Concatenate block managers into one.
+
+    Parameters
+    ----------
+    mgrs_indexers : list of (BlockManager, {axis: indexer,...}) tuples
+    axes : list of Index
+    concat_axis : int
+    copy : bool
+
+    Returns
+    -------
+    BlockManager
+    """
+
+    needs_copy = copy and concat_axis == 0
+
+    # TODO(ArrayManager) this assumes that all managers are of the same type
+    if isinstance(mgrs_indexers[0][0], ArrayManager):
+        mgrs = _maybe_reindex_columns_na_proxy(axes, mgrs_indexers, needs_copy)
+        # error: Argument 1 to "_concatenate_array_managers" has incompatible
+        # type "List[BlockManager]"; expected "List[Union[ArrayManager,
+        # SingleArrayManager, BlockManager, SingleBlockManager]]"
+        return _concatenate_array_managers(
+            mgrs, axes, concat_axis  # type: ignore[arg-type]
+        )
+
+    # Assertions disabled for performance
+    # for tup in mgrs_indexers:
+    #    # caller is responsible for ensuring this
+    #    indexers = tup[1]
+    #    assert concat_axis not in indexers
+
+    if concat_axis == 0:
+        mgrs = _maybe_reindex_columns_na_proxy(axes, mgrs_indexers, needs_copy)
+        return mgrs[0].concat_horizontal(mgrs, axes)
+
+    if len(mgrs_indexers) > 0 and mgrs_indexers[0][0].nblocks > 0:
+        first_dtype = mgrs_indexers[0][0].blocks[0].dtype
+        if first_dtype in [np.float64, np.float32]:
+            # TODO: support more dtypes here.  This will be simpler once
+            #  JoinUnit.is_na behavior is deprecated.
+            if (
+                all(_is_homogeneous_mgr(mgr, first_dtype) for mgr, _ in mgrs_indexers)
+                and len(mgrs_indexers) > 1
+            ):
+                # Fastpath!
+                # Length restriction is just to avoid having to worry about 'copy'
+                shape = tuple(len(x) for x in axes)
+                nb = _concat_homogeneous_fastpath(mgrs_indexers, shape, first_dtype)
+                return BlockManager((nb,), axes)
+
+    mgrs = _maybe_reindex_columns_na_proxy(axes, mgrs_indexers, needs_copy)
+
+    if len(mgrs) == 1:
+        mgr = mgrs[0]
+        out = mgr.copy(deep=False)
+        out.axes = axes
+        return out
+
+    concat_plan = _get_combined_plan(mgrs)
+
+    blocks = []
+    values: ArrayLike
+
+    for placement, join_units in concat_plan:
+        unit = join_units[0]
+        blk = unit.block
+
+        if _is_uniform_join_units(join_units):
+            vals = [ju.block.values for ju in join_units]
+
+            if not blk.is_extension:
+                # _is_uniform_join_units ensures a single dtype, so
+                #  we can use np.concatenate, which is more performant
+                #  than concat_compat
+                # error: Argument 1 to "concatenate" has incompatible type
+                # "List[Union[ndarray[Any, Any], ExtensionArray]]";
+                # expected "Union[_SupportsArray[dtype[Any]],
+                # _NestedSequence[_SupportsArray[dtype[Any]]]]"
+                values = np.concatenate(vals, axis=1)  # type: ignore[arg-type]
+            elif is_1d_only_ea_dtype(blk.dtype):
+                # TODO(EA2D): special-casing not needed with 2D EAs
+                values = concat_compat(vals, axis=0, ea_compat_axis=True)
+                values = ensure_block_shape(values, ndim=2)
+            else:
+                values = concat_compat(vals, axis=1)
+
+            values = ensure_wrapped_if_datetimelike(values)
+
+            fastpath = blk.values.dtype == values.dtype
+        else:
+            values = _concatenate_join_units(join_units, copy=copy)
+            fastpath = False
+
+        if fastpath:
+            b = blk.make_block_same_class(values, placement=placement)
+        else:
+            b = new_block_2d(values, placement=placement)
+
+        blocks.append(b)
+
+    return BlockManager(tuple(blocks), axes)
+
+
+def _maybe_reindex_columns_na_proxy(
+    axes: list[Index],
+    mgrs_indexers: list[tuple[BlockManager, dict[int, np.ndarray]]],
+    needs_copy: bool,
+) -> list[BlockManager]:
+    """
+    Reindex along columns so that all of the BlockManagers being concatenated
+    have matching columns.
+
+    Columns added in this reindexing have dtype=np.void, indicating they
+    should be ignored when choosing a column's final dtype.
+    """
+    new_mgrs = []
+
+    for mgr, indexers in mgrs_indexers:
+        # For axis=0 (i.e. columns) we use_na_proxy and only_slice, so this
+        #  is a cheap reindexing.
+        for i, indexer in indexers.items():
+            mgr = mgr.reindex_indexer(
+                axes[i],
+                indexers[i],
+                axis=i,
+                copy=False,
+                only_slice=True,  # only relevant for i==0
+                allow_dups=True,
+                use_na_proxy=True,  # only relevant for i==0
+            )
+        if needs_copy and not indexers:
+            mgr = mgr.copy()
+
+        new_mgrs.append(mgr)
+    return new_mgrs
+
+
+def _is_homogeneous_mgr(mgr: BlockManager, first_dtype: DtypeObj) -> bool:
+    """
+    Check if this Manager can be treated as a single ndarray.
+    """
+    if mgr.nblocks != 1:
+        return False
+    blk = mgr.blocks[0]
+    if not (blk.mgr_locs.is_slice_like and blk.mgr_locs.as_slice.step == 1):
+        return False
+
+    return blk.dtype == first_dtype
+
+
+def _concat_homogeneous_fastpath(
+    mgrs_indexers, shape: Shape, first_dtype: np.dtype
+) -> Block:
+    """
+    With single-Block managers with homogeneous dtypes (that can already hold nan),
+    we avoid [...]
+    """
+    # assumes
+    #  all(_is_homogeneous_mgr(mgr, first_dtype) for mgr, _ in in mgrs_indexers)
+
+    if all(not indexers for _, indexers in mgrs_indexers):
+        # https://github.com/pandas-dev/pandas/pull/52685#issuecomment-1523287739
+        arrs = [mgr.blocks[0].values.T for mgr, _ in mgrs_indexers]
+        arr = np.concatenate(arrs).T
+        bp = libinternals.BlockPlacement(slice(shape[0]))
+        nb = new_block_2d(arr, bp)
+        return nb
+
+    arr = np.empty(shape, dtype=first_dtype)
+
+    if first_dtype == np.float64:
+        take_func = libalgos.take_2d_axis0_float64_float64
+    else:
+        take_func = libalgos.take_2d_axis0_float32_float32
+
+    start = 0
+    for mgr, indexers in mgrs_indexers:
+        mgr_len = mgr.shape[1]
+        end = start + mgr_len
+
+        if 0 in indexers:
+            take_func(
+                mgr.blocks[0].values,
+                indexers[0],
+                arr[:, start:end],
+            )
+        else:
+            # No reindexing necessary, we can copy values directly
+            arr[:, start:end] = mgr.blocks[0].values
+
+        start += mgr_len
+
+    bp = libinternals.BlockPlacement(slice(shape[0]))
+    nb = new_block_2d(arr, bp)
+    return nb
+
+
+def _get_combined_plan(
+    mgrs: list[BlockManager],
+) -> list[tuple[BlockPlacement, list[JoinUnit]]]:
+    plan = []
+
+    max_len = mgrs[0].shape[0]
+
+    blknos_list = [mgr.blknos for mgr in mgrs]
+    pairs = libinternals.get_concat_blkno_indexers(blknos_list)
+    for ind, (blknos, bp) in enumerate(pairs):
+        # assert bp.is_slice_like
+        # assert len(bp) > 0
+
+        units_for_bp = []
+        for k, mgr in enumerate(mgrs):
+            blkno = blknos[k]
+
+            nb = _get_block_for_concat_plan(mgr, bp, blkno, max_len=max_len)
+            unit = JoinUnit(nb)
+            units_for_bp.append(unit)
+
+        plan.append((bp, units_for_bp))
+
+    return plan
+
+
+def _get_block_for_concat_plan(
+    mgr: BlockManager, bp: BlockPlacement, blkno: int, *, max_len: int
+) -> Block:
+    blk = mgr.blocks[blkno]
+    # Assertions disabled for performance:
+    #  assert bp.is_slice_like
+    #  assert blkno != -1
+    #  assert (mgr.blknos[bp] == blkno).all()
+
+    if len(bp) == len(blk.mgr_locs) and (
+        blk.mgr_locs.is_slice_like and blk.mgr_locs.as_slice.step == 1
+    ):
+        nb = blk
+    else:
+        ax0_blk_indexer = mgr.blklocs[bp.indexer]
+
+        slc = lib.maybe_indices_to_slice(ax0_blk_indexer, max_len)
+        # TODO: in all extant test cases 2023-04-08 we have a slice here.
+        #  Will this always be the case?
+        if isinstance(slc, slice):
+            nb = blk.slice_block_columns(slc)
+        else:
+            nb = blk.take_block_columns(slc)
+
+    # assert nb.shape == (len(bp), mgr.shape[1])
+    return nb
+
+
+class JoinUnit:
+    def __init__(self, block: Block) -> None:
+        self.block = block
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}({repr(self.block)})"
+
+    def _is_valid_na_for(self, dtype: DtypeObj) -> bool:
+        """
+        Check that we are all-NA of a type/dtype that is compatible with this dtype.
+        Augments `self.is_na` with an additional check of the type of NA values.
+        """
+        if not self.is_na:
+            return False
+
+        blk = self.block
+        if blk.dtype.kind == "V":
+            return True
+
+        if blk.dtype == object:
+            values = blk.values
+            return all(is_valid_na_for_dtype(x, dtype) for x in values.ravel(order="K"))
+
+        na_value = blk.fill_value
+        if na_value is NaT and blk.dtype != dtype:
+            # e.g. we are dt64 and other is td64
+            # fill_values match but we should not cast blk.values to dtype
+            # TODO: this will need updating if we ever have non-nano dt64/td64
+            return False
+
+        if na_value is NA and needs_i8_conversion(dtype):
+            # FIXME: kludge; test_append_empty_frame_with_timedelta64ns_nat
+            #  e.g. blk.dtype == "Int64" and dtype is td64, we dont want
+            #  to consider these as matching
+            return False
+
+        # TODO: better to use can_hold_element?
+        return is_valid_na_for_dtype(na_value, dtype)
+
+    @cache_readonly
+    def is_na(self) -> bool:
+        blk = self.block
+        if blk.dtype.kind == "V":
+            return True
+
+        if not blk._can_hold_na:
+            return False
+
+        values = blk.values
+        if values.size == 0:
+            # GH#39122 this case will return False once deprecation is enforced
+            return True
+
+        if isinstance(values.dtype, SparseDtype):
+            return False
+
+        if values.ndim == 1:
+            # TODO(EA2D): no need for special case with 2D EAs
+            val = values[0]
+            if not is_scalar(val) or not isna(val):
+                # ideally isna_all would do this short-circuiting
+                return False
+            return isna_all(values)
+        else:
+            val = values[0][0]
+            if not is_scalar(val) or not isna(val):
+                # ideally isna_all would do this short-circuiting
+                return False
+            return all(isna_all(row) for row in values)
+
+    @cache_readonly
+    def is_na_after_size_and_isna_all_deprecation(self) -> bool:
+        """
+        Will self.is_na be True after values.size == 0 deprecation and isna_all
+        deprecation are enforced?
+        """
+        blk = self.block
+        if blk.dtype.kind == "V":
+            return True
+        return False
+
+    def get_reindexed_values(self, empty_dtype: DtypeObj, upcasted_na) -> ArrayLike:
+        values: ArrayLike
+
+        if upcasted_na is None and self.block.dtype.kind != "V":
+            # No upcasting is necessary
+            return self.block.values
+        else:
+            fill_value = upcasted_na
+
+            if self._is_valid_na_for(empty_dtype):
+                # note: always holds when self.block.dtype.kind == "V"
+                blk_dtype = self.block.dtype
+
+                if blk_dtype == np.dtype("object"):
+                    # we want to avoid filling with np.nan if we are
+                    # using None; we already know that we are all
+                    # nulls
+                    values = cast(np.ndarray, self.block.values)
+                    if values.size and values[0, 0] is None:
+                        fill_value = None
+
+                return make_na_array(empty_dtype, self.block.shape, fill_value)
+
+            return self.block.values
+
+
+def _concatenate_join_units(join_units: list[JoinUnit], copy: bool) -> ArrayLike:
+    """
+    Concatenate values from several join units along axis=1.
+    """
+    empty_dtype, empty_dtype_future = _get_empty_dtype(join_units)
+
+    has_none_blocks = any(unit.block.dtype.kind == "V" for unit in join_units)
+    upcasted_na = _dtype_to_na_value(empty_dtype, has_none_blocks)
+
+    to_concat = [
+        ju.get_reindexed_values(empty_dtype=empty_dtype, upcasted_na=upcasted_na)
+        for ju in join_units
+    ]
+
+    if any(is_1d_only_ea_dtype(t.dtype) for t in to_concat):
+        # TODO(EA2D): special case not needed if all EAs used HybridBlocks
+
+        # error: No overload variant of "__getitem__" of "ExtensionArray" matches
+        # argument type "Tuple[int, slice]"
+        to_concat = [
+            t
+            if is_1d_only_ea_dtype(t.dtype)
+            else t[0, :]  # type: ignore[call-overload]
+            for t in to_concat
+        ]
+        concat_values = concat_compat(to_concat, axis=0, ea_compat_axis=True)
+        concat_values = ensure_block_shape(concat_values, 2)
+
+    else:
+        concat_values = concat_compat(to_concat, axis=1)
+
+    if empty_dtype != empty_dtype_future:
+        if empty_dtype == concat_values.dtype:
+            # GH#39122, GH#40893
+            warnings.warn(
+                "The behavior of DataFrame concatenation with empty or all-NA "
+                "entries is deprecated. In a future version, this will no longer "
+                "exclude empty or all-NA columns when determining the result dtypes. "
+                "To retain the old behavior, exclude the relevant entries before "
+                "the concat operation.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+    return concat_values
+
+
+def _dtype_to_na_value(dtype: DtypeObj, has_none_blocks: bool):
+    """
+    Find the NA value to go with this dtype.
+    """
+    if isinstance(dtype, ExtensionDtype):
+        return dtype.na_value
+    elif dtype.kind in "mM":
+        return dtype.type("NaT")
+    elif dtype.kind in "fc":
+        return dtype.type("NaN")
+    elif dtype.kind == "b":
+        # different from missing.na_value_for_dtype
+        return None
+    elif dtype.kind in "iu":
+        if not has_none_blocks:
+            # different from missing.na_value_for_dtype
+            return None
+        return np.nan
+    elif dtype.kind == "O":
+        return np.nan
+    raise NotImplementedError
+
+
+def _get_empty_dtype(join_units: Sequence[JoinUnit]) -> tuple[DtypeObj, DtypeObj]:
+    """
+    Return dtype and N/A values to use when concatenating specified units.
+
+    Returned N/A value may be None which means there was no casting involved.
+
+    Returns
+    -------
+    dtype
+    """
+    if lib.dtypes_all_equal([ju.block.dtype for ju in join_units]):
+        empty_dtype = join_units[0].block.dtype
+        return empty_dtype, empty_dtype
+
+    has_none_blocks = any(unit.block.dtype.kind == "V" for unit in join_units)
+
+    dtypes = [unit.block.dtype for unit in join_units if not unit.is_na]
+    if not len(dtypes):
+        dtypes = [
+            unit.block.dtype for unit in join_units if unit.block.dtype.kind != "V"
+        ]
+
+    dtype = find_common_type(dtypes)
+    if has_none_blocks:
+        dtype = ensure_dtype_can_hold_na(dtype)
+
+    dtype_future = dtype
+    if len(dtypes) != len(join_units):
+        dtypes_future = [
+            unit.block.dtype
+            for unit in join_units
+            if not unit.is_na_after_size_and_isna_all_deprecation
+        ]
+        if not len(dtypes_future):
+            dtypes_future = [
+                unit.block.dtype for unit in join_units if unit.block.dtype.kind != "V"
+            ]
+
+        if len(dtypes) != len(dtypes_future):
+            dtype_future = find_common_type(dtypes_future)
+            if has_none_blocks:
+                dtype_future = ensure_dtype_can_hold_na(dtype_future)
+
+    return dtype, dtype_future
+
+
+def _is_uniform_join_units(join_units: list[JoinUnit]) -> bool:
+    """
+    Check if the join units consist of blocks of uniform type that can
+    be concatenated using Block.concat_same_type instead of the generic
+    _concatenate_join_units (which uses `concat_compat`).
+
+    """
+    first = join_units[0].block
+    if first.dtype.kind == "V":
+        return False
+    return (
+        # exclude cases where a) ju.block is None or b) we have e.g. Int64+int64
+        all(type(ju.block) is type(first) for ju in join_units)
+        and
+        # e.g. DatetimeLikeBlock can be dt64 or td64, but these are not uniform
+        all(
+            ju.block.dtype == first.dtype
+            # GH#42092 we only want the dtype_equal check for non-numeric blocks
+            #  (for now, may change but that would need a deprecation)
+            or ju.block.dtype.kind in "iub"
+            for ju in join_units
+        )
+        and
+        # no blocks that would get missing values (can lead to type upcasts)
+        # unless we're an extension dtype.
+        all(not ju.is_na or ju.block.is_extension for ju in join_units)
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/construction.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/construction.py
new file mode 100644
index 0000000000000000000000000000000000000000..64fac5fcfcdc29aab451cce31b3591e56da744a0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/construction.py
@@ -0,0 +1,1073 @@
+"""
+Functions for preparing various inputs passed to the DataFrame or Series
+constructors before passing them to a BlockManager.
+"""
+from __future__ import annotations
+
+from collections import abc
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+import numpy as np
+from numpy import ma
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.astype import astype_is_view
+from pandas.core.dtypes.cast import (
+    construct_1d_arraylike_from_scalar,
+    dict_compat,
+    maybe_cast_to_datetime,
+    maybe_convert_platform,
+    maybe_infer_to_datetimelike,
+)
+from pandas.core.dtypes.common import (
+    is_1d_only_ea_dtype,
+    is_integer_dtype,
+    is_list_like,
+    is_named_tuple,
+    is_object_dtype,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+from pandas.core import (
+    algorithms,
+    common as com,
+)
+from pandas.core.arrays import ExtensionArray
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.construction import (
+    array as pd_array,
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+    range_to_ndarray,
+    sanitize_array,
+)
+from pandas.core.indexes.api import (
+    DatetimeIndex,
+    Index,
+    TimedeltaIndex,
+    default_index,
+    ensure_index,
+    get_objs_combined_axis,
+    union_indexes,
+)
+from pandas.core.internals.array_manager import (
+    ArrayManager,
+    SingleArrayManager,
+)
+from pandas.core.internals.blocks import (
+    BlockPlacement,
+    ensure_block_shape,
+    new_block,
+    new_block_2d,
+)
+from pandas.core.internals.managers import (
+    BlockManager,
+    SingleBlockManager,
+    create_block_manager_from_blocks,
+    create_block_manager_from_column_arrays,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        DtypeObj,
+        Manager,
+        npt,
+    )
+# ---------------------------------------------------------------------
+# BlockManager Interface
+
+
+def arrays_to_mgr(
+    arrays,
+    columns: Index,
+    index,
+    *,
+    dtype: DtypeObj | None = None,
+    verify_integrity: bool = True,
+    typ: str | None = None,
+    consolidate: bool = True,
+) -> Manager:
+    """
+    Segregate Series based on type and coerce into matrices.
+
+    Needs to handle a lot of exceptional cases.
+    """
+    if verify_integrity:
+        # figure out the index, if necessary
+        if index is None:
+            index = _extract_index(arrays)
+        else:
+            index = ensure_index(index)
+
+        # don't force copy because getting jammed in an ndarray anyway
+        arrays, refs = _homogenize(arrays, index, dtype)
+        # _homogenize ensures
+        #  - all(len(x) == len(index) for x in arrays)
+        #  - all(x.ndim == 1 for x in arrays)
+        #  - all(isinstance(x, (np.ndarray, ExtensionArray)) for x in arrays)
+        #  - all(type(x) is not NumpyExtensionArray for x in arrays)
+
+    else:
+        index = ensure_index(index)
+        arrays = [extract_array(x, extract_numpy=True) for x in arrays]
+        # with _from_arrays, the passed arrays should never be Series objects
+        refs = [None] * len(arrays)
+
+        # Reached via DataFrame._from_arrays; we do minimal validation here
+        for arr in arrays:
+            if (
+                not isinstance(arr, (np.ndarray, ExtensionArray))
+                or arr.ndim != 1
+                or len(arr) != len(index)
+            ):
+                raise ValueError(
+                    "Arrays must be 1-dimensional np.ndarray or ExtensionArray "
+                    "with length matching len(index)"
+                )
+
+    columns = ensure_index(columns)
+    if len(columns) != len(arrays):
+        raise ValueError("len(arrays) must match len(columns)")
+
+    # from BlockManager perspective
+    axes = [columns, index]
+
+    if typ == "block":
+        return create_block_manager_from_column_arrays(
+            arrays, axes, consolidate=consolidate, refs=refs
+        )
+    elif typ == "array":
+        return ArrayManager(arrays, [index, columns])
+    else:
+        raise ValueError(f"'typ' needs to be one of {{'block', 'array'}}, got '{typ}'")
+
+
+def rec_array_to_mgr(
+    data: np.rec.recarray | np.ndarray,
+    index,
+    columns,
+    dtype: DtypeObj | None,
+    copy: bool,
+    typ: str,
+) -> Manager:
+    """
+    Extract from a masked rec array and create the manager.
+    """
+    # essentially process a record array then fill it
+    fdata = ma.getdata(data)
+    if index is None:
+        index = default_index(len(fdata))
+    else:
+        index = ensure_index(index)
+
+    if columns is not None:
+        columns = ensure_index(columns)
+    arrays, arr_columns = to_arrays(fdata, columns)
+
+    # create the manager
+
+    arrays, arr_columns = reorder_arrays(arrays, arr_columns, columns, len(index))
+    if columns is None:
+        columns = arr_columns
+
+    mgr = arrays_to_mgr(arrays, columns, index, dtype=dtype, typ=typ)
+
+    if copy:
+        mgr = mgr.copy()
+    return mgr
+
+
+def mgr_to_mgr(mgr, typ: str, copy: bool = True) -> Manager:
+    """
+    Convert to specific type of Manager. Does not copy if the type is already
+    correct. Does not guarantee a copy otherwise. `copy` keyword only controls
+    whether conversion from Block->ArrayManager copies the 1D arrays.
+    """
+    new_mgr: Manager
+
+    if typ == "block":
+        if isinstance(mgr, BlockManager):
+            new_mgr = mgr
+        else:
+            if mgr.ndim == 2:
+                new_mgr = arrays_to_mgr(
+                    mgr.arrays, mgr.axes[0], mgr.axes[1], typ="block"
+                )
+            else:
+                new_mgr = SingleBlockManager.from_array(mgr.arrays[0], mgr.index)
+    elif typ == "array":
+        if isinstance(mgr, ArrayManager):
+            new_mgr = mgr
+        else:
+            if mgr.ndim == 2:
+                arrays = [mgr.iget_values(i) for i in range(len(mgr.axes[0]))]
+                if copy:
+                    arrays = [arr.copy() for arr in arrays]
+                new_mgr = ArrayManager(arrays, [mgr.axes[1], mgr.axes[0]])
+            else:
+                array = mgr.internal_values()
+                if copy:
+                    array = array.copy()
+                new_mgr = SingleArrayManager([array], [mgr.index])
+    else:
+        raise ValueError(f"'typ' needs to be one of {{'block', 'array'}}, got '{typ}'")
+    return new_mgr
+
+
+# ---------------------------------------------------------------------
+# DataFrame Constructor Interface
+
+
+def ndarray_to_mgr(
+    values, index, columns, dtype: DtypeObj | None, copy: bool, typ: str
+) -> Manager:
+    # used in DataFrame.__init__
+    # input must be a ndarray, list, Series, Index, ExtensionArray
+
+    if isinstance(values, ABCSeries):
+        if columns is None:
+            if values.name is not None:
+                columns = Index([values.name])
+        if index is None:
+            index = values.index
+        else:
+            values = values.reindex(index)
+
+        # zero len case (GH #2234)
+        if not len(values) and columns is not None and len(columns):
+            values = np.empty((0, 1), dtype=object)
+
+    # if the array preparation does a copy -> avoid this for ArrayManager,
+    # since the copy is done on conversion to 1D arrays
+    copy_on_sanitize = False if typ == "array" else copy
+
+    vdtype = getattr(values, "dtype", None)
+    refs = None
+    if is_1d_only_ea_dtype(vdtype) or is_1d_only_ea_dtype(dtype):
+        # GH#19157
+
+        if isinstance(values, (np.ndarray, ExtensionArray)) and values.ndim > 1:
+            # GH#12513 a EA dtype passed with a 2D array, split into
+            #  multiple EAs that view the values
+            # error: No overload variant of "__getitem__" of "ExtensionArray"
+            # matches argument type "Tuple[slice, int]"
+            values = [
+                values[:, n]  # type: ignore[call-overload]
+                for n in range(values.shape[1])
+            ]
+        else:
+            values = [values]
+
+        if columns is None:
+            columns = Index(range(len(values)))
+        else:
+            columns = ensure_index(columns)
+
+        return arrays_to_mgr(values, columns, index, dtype=dtype, typ=typ)
+
+    elif isinstance(vdtype, ExtensionDtype):
+        # i.e. Datetime64TZ, PeriodDtype; cases with is_1d_only_ea_dtype(vdtype)
+        #  are already caught above
+        values = extract_array(values, extract_numpy=True)
+        if copy:
+            values = values.copy()
+        if values.ndim == 1:
+            values = values.reshape(-1, 1)
+
+    elif isinstance(values, (ABCSeries, Index)):
+        if not copy_on_sanitize and (
+            dtype is None or astype_is_view(values.dtype, dtype)
+        ):
+            refs = values._references
+
+        if copy_on_sanitize:
+            values = values._values.copy()
+        else:
+            values = values._values
+
+        values = _ensure_2d(values)
+
+    elif isinstance(values, (np.ndarray, ExtensionArray)):
+        # drop subclass info
+        if copy_on_sanitize and (dtype is None or astype_is_view(values.dtype, dtype)):
+            # only force a copy now if copy=True was requested
+            # and a subsequent `astype` will not already result in a copy
+            values = np.array(values, copy=True, order="F")
+        else:
+            values = np.asarray(values)
+        values = _ensure_2d(values)
+
+    else:
+        # by definition an array here
+        # the dtypes will be coerced to a single dtype
+        values = _prep_ndarraylike(values, copy=copy_on_sanitize)
+
+    if dtype is not None and values.dtype != dtype:
+        # GH#40110 see similar check inside sanitize_array
+        values = sanitize_array(
+            values,
+            None,
+            dtype=dtype,
+            copy=copy_on_sanitize,
+            allow_2d=True,
+        )
+
+    # _prep_ndarraylike ensures that values.ndim == 2 at this point
+    index, columns = _get_axes(
+        values.shape[0], values.shape[1], index=index, columns=columns
+    )
+
+    _check_values_indices_shape_match(values, index, columns)
+
+    if typ == "array":
+        if issubclass(values.dtype.type, str):
+            values = np.array(values, dtype=object)
+
+        if dtype is None and is_object_dtype(values.dtype):
+            arrays = [
+                ensure_wrapped_if_datetimelike(
+                    maybe_infer_to_datetimelike(values[:, i])
+                )
+                for i in range(values.shape[1])
+            ]
+        else:
+            if lib.is_np_dtype(values.dtype, "mM"):
+                values = ensure_wrapped_if_datetimelike(values)
+            arrays = [values[:, i] for i in range(values.shape[1])]
+
+        if copy:
+            arrays = [arr.copy() for arr in arrays]
+
+        return ArrayManager(arrays, [index, columns], verify_integrity=False)
+
+    values = values.T
+
+    # if we don't have a dtype specified, then try to convert objects
+    # on the entire block; this is to convert if we have datetimelike's
+    # embedded in an object type
+    if dtype is None and is_object_dtype(values.dtype):
+        obj_columns = list(values)
+        maybe_datetime = [maybe_infer_to_datetimelike(x) for x in obj_columns]
+        # don't convert (and copy) the objects if no type inference occurs
+        if any(x is not y for x, y in zip(obj_columns, maybe_datetime)):
+            dvals_list = [ensure_block_shape(dval, 2) for dval in maybe_datetime]
+            block_values = [
+                new_block_2d(dvals_list[n], placement=BlockPlacement(n))
+                for n in range(len(dvals_list))
+            ]
+        else:
+            bp = BlockPlacement(slice(len(columns)))
+            nb = new_block_2d(values, placement=bp, refs=refs)
+            block_values = [nb]
+    elif dtype is None and values.dtype.kind == "U" and using_string_dtype():
+        dtype = StringDtype(na_value=np.nan)
+
+        obj_columns = list(values)
+        block_values = [
+            new_block(
+                dtype.construct_array_type()._from_sequence(data, dtype=dtype),
+                BlockPlacement(slice(i, i + 1)),
+                ndim=2,
+            )
+            for i, data in enumerate(obj_columns)
+        ]
+
+    else:
+        bp = BlockPlacement(slice(len(columns)))
+        nb = new_block_2d(values, placement=bp, refs=refs)
+        block_values = [nb]
+
+    if len(columns) == 0:
+        # TODO: check len(values) == 0?
+        block_values = []
+
+    return create_block_manager_from_blocks(
+        block_values, [columns, index], verify_integrity=False
+    )
+
+
+def _check_values_indices_shape_match(
+    values: np.ndarray, index: Index, columns: Index
+) -> None:
+    """
+    Check that the shape implied by our axes matches the actual shape of the
+    data.
+    """
+    if values.shape[1] != len(columns) or values.shape[0] != len(index):
+        # Could let this raise in Block constructor, but we get a more
+        #  helpful exception message this way.
+        if values.shape[0] == 0 < len(index):
+            raise ValueError("Empty data passed with indices specified.")
+
+        passed = values.shape
+        implied = (len(index), len(columns))
+        raise ValueError(f"Shape of passed values is {passed}, indices imply {implied}")
+
+
+def dict_to_mgr(
+    data: dict,
+    index,
+    columns,
+    *,
+    dtype: DtypeObj | None = None,
+    typ: str = "block",
+    copy: bool = True,
+) -> Manager:
+    """
+    Segregate Series based on type and coerce into matrices.
+    Needs to handle a lot of exceptional cases.
+
+    Used in DataFrame.__init__
+    """
+    arrays: Sequence[Any] | Series
+
+    if columns is not None:
+        from pandas.core.series import Series
+
+        arrays = Series(data, index=columns, dtype=object)
+        missing = arrays.isna()
+        if index is None:
+            # GH10856
+            # raise ValueError if only scalars in dict
+            index = _extract_index(arrays[~missing])
+        else:
+            index = ensure_index(index)
+
+        # no obvious "empty" int column
+        if missing.any() and not is_integer_dtype(dtype):
+            nan_dtype: DtypeObj
+
+            if dtype is not None:
+                # calling sanitize_array ensures we don't mix-and-match
+                #  NA dtypes
+                midxs = missing.values.nonzero()[0]
+                for i in midxs:
+                    arr = sanitize_array(arrays.iat[i], index, dtype=dtype)
+                    arrays.iat[i] = arr
+            else:
+                # GH#1783
+                nan_dtype = np.dtype("object")
+                val = construct_1d_arraylike_from_scalar(np.nan, len(index), nan_dtype)
+                nmissing = missing.sum()
+                if copy:
+                    rhs = [val] * nmissing
+                else:
+                    # GH#45369
+                    rhs = [val.copy() for _ in range(nmissing)]
+                arrays.loc[missing] = rhs
+
+        arrays = list(arrays)
+        columns = ensure_index(columns)
+
+    else:
+        keys = list(data.keys())
+        columns = Index(keys) if keys else default_index(0)
+        arrays = [com.maybe_iterable_to_list(data[k]) for k in keys]
+
+    if copy:
+        if typ == "block":
+            # We only need to copy arrays that will not get consolidated, i.e.
+            #  only EA arrays
+            arrays = [
+                x.copy()
+                if isinstance(x, ExtensionArray)
+                else x.copy(deep=True)
+                if (
+                    isinstance(x, Index)
+                    or isinstance(x, ABCSeries)
+                    and is_1d_only_ea_dtype(x.dtype)
+                )
+                else x
+                for x in arrays
+            ]
+        else:
+            # dtype check to exclude e.g. range objects, scalars
+            arrays = [x.copy() if hasattr(x, "dtype") else x for x in arrays]
+
+    return arrays_to_mgr(arrays, columns, index, dtype=dtype, typ=typ, consolidate=copy)
+
+
+def nested_data_to_arrays(
+    data: Sequence,
+    columns: Index | None,
+    index: Index | None,
+    dtype: DtypeObj | None,
+) -> tuple[list[ArrayLike], Index, Index]:
+    """
+    Convert a single sequence of arrays to multiple arrays.
+    """
+    # By the time we get here we have already checked treat_as_nested(data)
+
+    if is_named_tuple(data[0]) and columns is None:
+        columns = ensure_index(data[0]._fields)
+
+    arrays, columns = to_arrays(data, columns, dtype=dtype)
+    columns = ensure_index(columns)
+
+    if index is None:
+        if isinstance(data[0], ABCSeries):
+            index = _get_names_from_index(data)
+        else:
+            index = default_index(len(data))
+
+    return arrays, columns, index
+
+
+def treat_as_nested(data) -> bool:
+    """
+    Check if we should use nested_data_to_arrays.
+    """
+    return (
+        len(data) > 0
+        and is_list_like(data[0])
+        and getattr(data[0], "ndim", 1) == 1
+        and not (isinstance(data, ExtensionArray) and data.ndim == 2)
+    )
+
+
+# ---------------------------------------------------------------------
+
+
+def _prep_ndarraylike(values, copy: bool = True) -> np.ndarray:
+    # values is specifically _not_ ndarray, EA, Index, or Series
+    # We only get here with `not treat_as_nested(values)`
+
+    if len(values) == 0:
+        # TODO: check for length-zero range, in which case return int64 dtype?
+        # TODO: reuse anything in try_cast?
+        return np.empty((0, 0), dtype=object)
+    elif isinstance(values, range):
+        arr = range_to_ndarray(values)
+        return arr[..., np.newaxis]
+
+    def convert(v):
+        if not is_list_like(v) or isinstance(v, ABCDataFrame):
+            return v
+
+        v = extract_array(v, extract_numpy=True)
+        res = maybe_convert_platform(v)
+        # We don't do maybe_infer_to_datetimelike here bc we will end up doing
+        #  it column-by-column in ndarray_to_mgr
+        return res
+
+    # we could have a 1-dim or 2-dim list here
+    # this is equiv of np.asarray, but does object conversion
+    # and platform dtype preservation
+    # does not convert e.g. [1, "a", True] to ["1", "a", "True"] like
+    #  np.asarray would
+    if is_list_like(values[0]):
+        values = np.array([convert(v) for v in values])
+    elif isinstance(values[0], np.ndarray) and values[0].ndim == 0:
+        # GH#21861 see test_constructor_list_of_lists
+        values = np.array([convert(v) for v in values])
+    else:
+        values = convert(values)
+
+    return _ensure_2d(values)
+
+
+def _ensure_2d(values: np.ndarray) -> np.ndarray:
+    """
+    Reshape 1D values, raise on anything else other than 2D.
+    """
+    if values.ndim == 1:
+        values = values.reshape((values.shape[0], 1))
+    elif values.ndim != 2:
+        raise ValueError(f"Must pass 2-d input. shape={values.shape}")
+    return values
+
+
+def _homogenize(
+    data, index: Index, dtype: DtypeObj | None
+) -> tuple[list[ArrayLike], list[Any]]:
+    oindex = None
+    homogenized = []
+    # if the original array-like in `data` is a Series, keep track of this Series' refs
+    refs: list[Any] = []
+
+    for val in data:
+        if isinstance(val, (ABCSeries, Index)):
+            if dtype is not None:
+                val = val.astype(dtype, copy=False)
+            if isinstance(val, ABCSeries) and val.index is not index:
+                # Forces alignment. No need to copy data since we
+                # are putting it into an ndarray later
+                val = val.reindex(index, copy=False)
+            refs.append(val._references)
+            val = val._values
+        else:
+            if isinstance(val, dict):
+                # GH#41785 this _should_ be equivalent to (but faster than)
+                #  val = Series(val, index=index)._values
+                if oindex is None:
+                    oindex = index.astype("O")
+
+                if isinstance(index, (DatetimeIndex, TimedeltaIndex)):
+                    # see test_constructor_dict_datetime64_index
+                    val = dict_compat(val)
+                else:
+                    # see test_constructor_subclass_dict
+                    val = dict(val)
+                val = lib.fast_multiget(val, oindex._values, default=np.nan)
+
+            val = sanitize_array(val, index, dtype=dtype, copy=False)
+            com.require_length_match(val, index)
+            refs.append(None)
+
+        homogenized.append(val)
+
+    return homogenized, refs
+
+
+def _extract_index(data) -> Index:
+    """
+    Try to infer an Index from the passed data, raise ValueError on failure.
+    """
+    index: Index
+    if len(data) == 0:
+        return default_index(0)
+
+    raw_lengths = []
+    indexes: list[list[Hashable] | Index] = []
+
+    have_raw_arrays = False
+    have_series = False
+    have_dicts = False
+
+    for val in data:
+        if isinstance(val, ABCSeries):
+            have_series = True
+            indexes.append(val.index)
+        elif isinstance(val, dict):
+            have_dicts = True
+            indexes.append(list(val.keys()))
+        elif is_list_like(val) and getattr(val, "ndim", 1) == 1:
+            have_raw_arrays = True
+            raw_lengths.append(len(val))
+        elif isinstance(val, np.ndarray) and val.ndim > 1:
+            raise ValueError("Per-column arrays must each be 1-dimensional")
+
+    if not indexes and not raw_lengths:
+        raise ValueError("If using all scalar values, you must pass an index")
+
+    if have_series:
+        index = union_indexes(indexes)
+    elif have_dicts:
+        index = union_indexes(indexes, sort=False)
+
+    if have_raw_arrays:
+        lengths = list(set(raw_lengths))
+        if len(lengths) > 1:
+            raise ValueError("All arrays must be of the same length")
+
+        if have_dicts:
+            raise ValueError(
+                "Mixing dicts with non-Series may lead to ambiguous ordering."
+            )
+
+        if have_series:
+            if lengths[0] != len(index):
+                msg = (
+                    f"array length {lengths[0]} does not match index "
+                    f"length {len(index)}"
+                )
+                raise ValueError(msg)
+        else:
+            index = default_index(lengths[0])
+
+    return ensure_index(index)
+
+
+def reorder_arrays(
+    arrays: list[ArrayLike], arr_columns: Index, columns: Index | None, length: int
+) -> tuple[list[ArrayLike], Index]:
+    """
+    Pre-emptively (cheaply) reindex arrays with new columns.
+    """
+    # reorder according to the columns
+    if columns is not None:
+        if not columns.equals(arr_columns):
+            # if they are equal, there is nothing to do
+            new_arrays: list[ArrayLike] = []
+            indexer = arr_columns.get_indexer(columns)
+            for i, k in enumerate(indexer):
+                if k == -1:
+                    # by convention default is all-NaN object dtype
+                    arr = np.empty(length, dtype=object)
+                    arr.fill(np.nan)
+                else:
+                    arr = arrays[k]
+                new_arrays.append(arr)
+
+            arrays = new_arrays
+            arr_columns = columns
+
+    return arrays, arr_columns
+
+
+def _get_names_from_index(data) -> Index:
+    has_some_name = any(getattr(s, "name", None) is not None for s in data)
+    if not has_some_name:
+        return default_index(len(data))
+
+    index: list[Hashable] = list(range(len(data)))
+    count = 0
+    for i, s in enumerate(data):
+        n = getattr(s, "name", None)
+        if n is not None:
+            index[i] = n
+        else:
+            index[i] = f"Unnamed {count}"
+            count += 1
+
+    return Index(index)
+
+
+def _get_axes(
+    N: int, K: int, index: Index | None, columns: Index | None
+) -> tuple[Index, Index]:
+    # helper to create the axes as indexes
+    # return axes or defaults
+
+    if index is None:
+        index = default_index(N)
+    else:
+        index = ensure_index(index)
+
+    if columns is None:
+        columns = default_index(K)
+    else:
+        columns = ensure_index(columns)
+    return index, columns
+
+
+def dataclasses_to_dicts(data):
+    """
+    Converts a list of dataclass instances to a list of dictionaries.
+
+    Parameters
+    ----------
+    data : List[Type[dataclass]]
+
+    Returns
+    --------
+    list_dict : List[dict]
+
+    Examples
+    --------
+    >>> from dataclasses import dataclass
+    >>> @dataclass
+    ... class Point:
+    ...     x: int
+    ...     y: int
+
+    >>> dataclasses_to_dicts([Point(1, 2), Point(2, 3)])
+    [{'x': 1, 'y': 2}, {'x': 2, 'y': 3}]
+
+    """
+    from dataclasses import asdict
+
+    return list(map(asdict, data))
+
+
+# ---------------------------------------------------------------------
+# Conversion of Inputs to Arrays
+
+
+def to_arrays(
+    data, columns: Index | None, dtype: DtypeObj | None = None
+) -> tuple[list[ArrayLike], Index]:
+    """
+    Return list of arrays, columns.
+
+    Returns
+    -------
+    list[ArrayLike]
+        These will become columns in a DataFrame.
+    Index
+        This will become frame.columns.
+
+    Notes
+    -----
+    Ensures that len(result_arrays) == len(result_index).
+    """
+
+    if not len(data):
+        if isinstance(data, np.ndarray):
+            if data.dtype.names is not None:
+                # i.e. numpy structured array
+                columns = ensure_index(data.dtype.names)
+                arrays = [data[name] for name in columns]
+
+                if len(data) == 0:
+                    # GH#42456 the indexing above results in list of 2D ndarrays
+                    # TODO: is that an issue with numpy?
+                    for i, arr in enumerate(arrays):
+                        if arr.ndim == 2:
+                            arrays[i] = arr[:, 0]
+
+                return arrays, columns
+        return [], ensure_index([])
+
+    elif isinstance(data, np.ndarray) and data.dtype.names is not None:
+        # e.g. recarray
+        columns = Index(list(data.dtype.names))
+        arrays = [data[k] for k in columns]
+        return arrays, columns
+
+    if isinstance(data[0], (list, tuple)):
+        arr = _list_to_arrays(data)
+    elif isinstance(data[0], abc.Mapping):
+        arr, columns = _list_of_dict_to_arrays(data, columns)
+    elif isinstance(data[0], ABCSeries):
+        arr, columns = _list_of_series_to_arrays(data, columns)
+    else:
+        # last ditch effort
+        data = [tuple(x) for x in data]
+        arr = _list_to_arrays(data)
+
+    content, columns = _finalize_columns_and_data(arr, columns, dtype)
+    return content, columns
+
+
+def _list_to_arrays(data: list[tuple | list]) -> np.ndarray:
+    # Returned np.ndarray has ndim = 2
+    # Note: we already check len(data) > 0 before getting hre
+    if isinstance(data[0], tuple):
+        content = lib.to_object_array_tuples(data)
+    else:
+        # list of lists
+        content = lib.to_object_array(data)
+    return content
+
+
+def _list_of_series_to_arrays(
+    data: list,
+    columns: Index | None,
+) -> tuple[np.ndarray, Index]:
+    # returned np.ndarray has ndim == 2
+
+    if columns is None:
+        # We know pass_data is non-empty because data[0] is a Series
+        pass_data = [x for x in data if isinstance(x, (ABCSeries, ABCDataFrame))]
+        columns = get_objs_combined_axis(pass_data, sort=False)
+
+    indexer_cache: dict[int, np.ndarray] = {}
+
+    aligned_values = []
+    for s in data:
+        index = getattr(s, "index", None)
+        if index is None:
+            index = default_index(len(s))
+
+        if id(index) in indexer_cache:
+            indexer = indexer_cache[id(index)]
+        else:
+            indexer = indexer_cache[id(index)] = index.get_indexer(columns)
+
+        values = extract_array(s, extract_numpy=True)
+        aligned_values.append(algorithms.take_nd(values, indexer))
+
+    content = np.vstack(aligned_values)
+    return content, columns
+
+
+def _list_of_dict_to_arrays(
+    data: list[dict],
+    columns: Index | None,
+) -> tuple[np.ndarray, Index]:
+    """
+    Convert list of dicts to numpy arrays
+
+    if `columns` is not passed, column names are inferred from the records
+    - for OrderedDict and dicts, the column names match
+      the key insertion-order from the first record to the last.
+    - For other kinds of dict-likes, the keys are lexically sorted.
+
+    Parameters
+    ----------
+    data : iterable
+        collection of records (OrderedDict, dict)
+    columns: iterables or None
+
+    Returns
+    -------
+    content : np.ndarray[object, ndim=2]
+    columns : Index
+    """
+    if columns is None:
+        gen = (list(x.keys()) for x in data)
+        sort = not any(isinstance(d, dict) for d in data)
+        pre_cols = lib.fast_unique_multiple_list_gen(gen, sort=sort)
+        columns = ensure_index(pre_cols)
+
+    # assure that they are of the base dict class and not of derived
+    # classes
+    data = [d if type(d) is dict else dict(d) for d in data]  # noqa: E721
+
+    content = lib.dicts_to_array(data, list(columns))
+    return content, columns
+
+
+def _finalize_columns_and_data(
+    content: np.ndarray,  # ndim == 2
+    columns: Index | None,
+    dtype: DtypeObj | None,
+) -> tuple[list[ArrayLike], Index]:
+    """
+    Ensure we have valid columns, cast object dtypes if possible.
+    """
+    contents = list(content.T)
+
+    try:
+        columns = _validate_or_indexify_columns(contents, columns)
+    except AssertionError as err:
+        # GH#26429 do not raise user-facing AssertionError
+        raise ValueError(err) from err
+
+    if len(contents) and contents[0].dtype == np.object_:
+        contents = convert_object_array(contents, dtype=dtype)
+
+    return contents, columns
+
+
+def _validate_or_indexify_columns(
+    content: list[np.ndarray], columns: Index | None
+) -> Index:
+    """
+    If columns is None, make numbers as column names; Otherwise, validate that
+    columns have valid length.
+
+    Parameters
+    ----------
+    content : list of np.ndarrays
+    columns : Index or None
+
+    Returns
+    -------
+    Index
+        If columns is None, assign positional column index value as columns.
+
+    Raises
+    ------
+    1. AssertionError when content is not composed of list of lists, and if
+        length of columns is not equal to length of content.
+    2. ValueError when content is list of lists, but length of each sub-list
+        is not equal
+    3. ValueError when content is list of lists, but length of sub-list is
+        not equal to length of content
+    """
+    if columns is None:
+        columns = default_index(len(content))
+    else:
+        # Add mask for data which is composed of list of lists
+        is_mi_list = isinstance(columns, list) and all(
+            isinstance(col, list) for col in columns
+        )
+
+        if not is_mi_list and len(columns) != len(content):  # pragma: no cover
+            # caller's responsibility to check for this...
+            raise AssertionError(
+                f"{len(columns)} columns passed, passed data had "
+                f"{len(content)} columns"
+            )
+        if is_mi_list:
+            # check if nested list column, length of each sub-list should be equal
+            if len({len(col) for col in columns}) > 1:
+                raise ValueError(
+                    "Length of columns passed for MultiIndex columns is different"
+                )
+
+            # if columns is not empty and length of sublist is not equal to content
+            if columns and len(columns[0]) != len(content):
+                raise ValueError(
+                    f"{len(columns[0])} columns passed, passed data had "
+                    f"{len(content)} columns"
+                )
+    return columns
+
+
+def convert_object_array(
+    content: list[npt.NDArray[np.object_]],
+    dtype: DtypeObj | None,
+    dtype_backend: str = "numpy",
+    coerce_float: bool = False,
+) -> list[ArrayLike]:
+    """
+    Internal function to convert object array.
+
+    Parameters
+    ----------
+    content: List[np.ndarray]
+    dtype: np.dtype or ExtensionDtype
+    dtype_backend: Controls if nullable/pyarrow dtypes are returned.
+    coerce_float: Cast floats that are integers to int.
+
+    Returns
+    -------
+    List[ArrayLike]
+    """
+    # provide soft conversion of object dtypes
+
+    def convert(arr):
+        if dtype != np.dtype("O"):
+            arr = lib.maybe_convert_objects(
+                arr,
+                try_float=coerce_float,
+                convert_to_nullable_dtype=dtype_backend != "numpy",
+            )
+            # Notes on cases that get here 2023-02-15
+            # 1) we DO get here when arr is all Timestamps and dtype=None
+            # 2) disabling this doesn't break the world, so this must be
+            #    getting caught at a higher level
+            # 3) passing convert_non_numeric to maybe_convert_objects get this right
+            # 4) convert_non_numeric?
+
+            if dtype is None:
+                if arr.dtype == np.dtype("O"):
+                    # i.e. maybe_convert_objects didn't convert
+                    convert_to_nullable_dtype = dtype_backend != "numpy"
+                    arr = maybe_infer_to_datetimelike(arr, convert_to_nullable_dtype)
+                    if convert_to_nullable_dtype and arr.dtype == np.dtype("O"):
+                        new_dtype = StringDtype()
+                        arr_cls = new_dtype.construct_array_type()
+                        arr = arr_cls._from_sequence(arr, dtype=new_dtype)
+                elif dtype_backend != "numpy" and isinstance(arr, np.ndarray):
+                    if arr.dtype.kind in "iufb":
+                        arr = pd_array(arr, copy=False)
+
+            elif isinstance(dtype, ExtensionDtype):
+                # TODO: test(s) that get here
+                # TODO: try to de-duplicate this convert function with
+                #  core.construction functions
+                cls = dtype.construct_array_type()
+                arr = cls._from_sequence(arr, dtype=dtype, copy=False)
+            elif dtype.kind in "mM":
+                # This restriction is harmless bc these are the only cases
+                #  where maybe_cast_to_datetime is not a no-op.
+                # Here we know:
+                #  1) dtype.kind in "mM" and
+                #  2) arr is either object or numeric dtype
+                arr = maybe_cast_to_datetime(arr, dtype)
+
+        return arr
+
+    arrays = [convert(arr) for arr in content]
+
+    return arrays
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/managers.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/managers.py
new file mode 100644
index 0000000000000000000000000000000000000000..5e3a67d5363fdd7333217df1256c29df58df8665
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/managers.py
@@ -0,0 +1,2394 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Sequence,
+)
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import (
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+
+from pandas._libs import (
+    internals as libinternals,
+    lib,
+)
+from pandas._libs.internals import (
+    BlockPlacement,
+    BlockValuesRefs,
+)
+from pandas._libs.tslibs import Timestamp
+from pandas.errors import PerformanceWarning
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import infer_dtype_from_scalar
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_1d_only_ea_dtype,
+    is_list_like,
+)
+from pandas.core.dtypes.dtypes import (
+    DatetimeTZDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    array_equals,
+    isna,
+)
+
+import pandas.core.algorithms as algos
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    ArrowStringArray,
+    DatetimeArray,
+)
+from pandas.core.arrays._mixins import NDArrayBackedExtensionArray
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.indexers import maybe_convert_indices
+from pandas.core.indexes.api import (
+    Index,
+    ensure_index,
+)
+from pandas.core.internals.base import (
+    DataManager,
+    SingleDataManager,
+    ensure_np_dtype,
+    interleaved_dtype,
+)
+from pandas.core.internals.blocks import (
+    COW_WARNING_GENERAL_MSG,
+    COW_WARNING_SETITEM_MSG,
+    Block,
+    NumpyBlock,
+    ensure_block_shape,
+    extend_blocks,
+    get_block_type,
+    maybe_coerce_values,
+    new_block,
+    new_block_2d,
+)
+from pandas.core.internals.ops import (
+    blockwise_all,
+    operate_blockwise,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        DtypeObj,
+        QuantileInterpolation,
+        Self,
+        Shape,
+        npt,
+    )
+
+    from pandas.api.extensions import ExtensionArray
+
+
+class BaseBlockManager(DataManager):
+    """
+    Core internal data structure to implement DataFrame, Series, etc.
+
+    Manage a bunch of labeled 2D mixed-type ndarrays. Essentially it's a
+    lightweight blocked set of labeled data to be manipulated by the DataFrame
+    public API class
+
+    Attributes
+    ----------
+    shape
+    ndim
+    axes
+    values
+    items
+
+    Methods
+    -------
+    set_axis(axis, new_labels)
+    copy(deep=True)
+
+    get_dtypes
+
+    apply(func, axes, block_filter_fn)
+
+    get_bool_data
+    get_numeric_data
+
+    get_slice(slice_like, axis)
+    get(label)
+    iget(loc)
+
+    take(indexer, axis)
+    reindex_axis(new_labels, axis)
+    reindex_indexer(new_labels, indexer, axis)
+
+    delete(label)
+    insert(loc, label, value)
+    set(label, value)
+
+    Parameters
+    ----------
+    blocks: Sequence of Block
+    axes: Sequence of Index
+    verify_integrity: bool, default True
+
+    Notes
+    -----
+    This is *not* a public API class
+    """
+
+    __slots__ = ()
+
+    _blknos: npt.NDArray[np.intp]
+    _blklocs: npt.NDArray[np.intp]
+    blocks: tuple[Block, ...]
+    axes: list[Index]
+
+    @property
+    def ndim(self) -> int:
+        raise NotImplementedError
+
+    _known_consolidated: bool
+    _is_consolidated: bool
+
+    def __init__(self, blocks, axes, verify_integrity: bool = True) -> None:
+        raise NotImplementedError
+
+    @classmethod
+    def from_blocks(cls, blocks: list[Block], axes: list[Index]) -> Self:
+        raise NotImplementedError
+
+    @property
+    def blknos(self) -> npt.NDArray[np.intp]:
+        """
+        Suppose we want to find the array corresponding to our i'th column.
+
+        blknos[i] identifies the block from self.blocks that contains this column.
+
+        blklocs[i] identifies the column of interest within
+        self.blocks[self.blknos[i]]
+        """
+        if self._blknos is None:
+            # Note: these can be altered by other BlockManager methods.
+            self._rebuild_blknos_and_blklocs()
+
+        return self._blknos
+
+    @property
+    def blklocs(self) -> npt.NDArray[np.intp]:
+        """
+        See blknos.__doc__
+        """
+        if self._blklocs is None:
+            # Note: these can be altered by other BlockManager methods.
+            self._rebuild_blknos_and_blklocs()
+
+        return self._blklocs
+
+    def make_empty(self, axes=None) -> Self:
+        """return an empty BlockManager with the items axis of len 0"""
+        if axes is None:
+            axes = [Index([])] + self.axes[1:]
+
+        # preserve dtype if possible
+        if self.ndim == 1:
+            assert isinstance(self, SingleBlockManager)  # for mypy
+            blk = self.blocks[0]
+            arr = blk.values[:0]
+            bp = BlockPlacement(slice(0, 0))
+            nb = blk.make_block_same_class(arr, placement=bp)
+            blocks = [nb]
+        else:
+            blocks = []
+        return type(self).from_blocks(blocks, axes)
+
+    def __nonzero__(self) -> bool:
+        return True
+
+    # Python3 compat
+    __bool__ = __nonzero__
+
+    def _normalize_axis(self, axis: AxisInt) -> int:
+        # switch axis to follow BlockManager logic
+        if self.ndim == 2:
+            axis = 1 if axis == 0 else 0
+        return axis
+
+    def set_axis(self, axis: AxisInt, new_labels: Index) -> None:
+        # Caller is responsible for ensuring we have an Index object.
+        self._validate_set_axis(axis, new_labels)
+        self.axes[axis] = new_labels
+
+    @property
+    def is_single_block(self) -> bool:
+        # Assumes we are 2D; overridden by SingleBlockManager
+        return len(self.blocks) == 1
+
+    @property
+    def items(self) -> Index:
+        return self.axes[0]
+
+    def _has_no_reference(self, i: int) -> bool:
+        """
+        Check for column `i` if it has references.
+        (whether it references another array or is itself being referenced)
+        Returns True if the column has no references.
+        """
+        blkno = self.blknos[i]
+        return self._has_no_reference_block(blkno)
+
+    def _has_no_reference_block(self, blkno: int) -> bool:
+        """
+        Check for block `i` if it has references.
+        (whether it references another array or is itself being referenced)
+        Returns True if the block has no references.
+        """
+        return not self.blocks[blkno].refs.has_reference()
+
+    def add_references(self, mgr: BaseBlockManager) -> None:
+        """
+        Adds the references from one manager to another. We assume that both
+        managers have the same block structure.
+        """
+        if len(self.blocks) != len(mgr.blocks):
+            # If block structure changes, then we made a copy
+            return
+        for i, blk in enumerate(self.blocks):
+            blk.refs = mgr.blocks[i].refs
+            blk.refs.add_reference(blk)
+
+    def references_same_values(self, mgr: BaseBlockManager, blkno: int) -> bool:
+        """
+        Checks if two blocks from two different block managers reference the
+        same underlying values.
+        """
+        blk = self.blocks[blkno]
+        return any(blk is ref() for ref in mgr.blocks[blkno].refs.referenced_blocks)
+
+    def get_dtypes(self) -> npt.NDArray[np.object_]:
+        dtypes = np.array([blk.dtype for blk in self.blocks], dtype=object)
+        return dtypes.take(self.blknos)
+
+    @property
+    def arrays(self) -> list[ArrayLike]:
+        """
+        Quick access to the backing arrays of the Blocks.
+
+        Only for compatibility with ArrayManager for testing convenience.
+        Not to be used in actual code, and return value is not the same as the
+        ArrayManager method (list of 1D arrays vs iterator of 2D ndarrays / 1D EAs).
+
+        Warning! The returned arrays don't handle Copy-on-Write, so this should
+        be used with caution (only in read-mode).
+        """
+        return [blk.values for blk in self.blocks]
+
+    def __repr__(self) -> str:
+        output = type(self).__name__
+        for i, ax in enumerate(self.axes):
+            if i == 0:
+                output += f"\nItems: {ax}"
+            else:
+                output += f"\nAxis {i}: {ax}"
+
+        for block in self.blocks:
+            output += f"\n{block}"
+        return output
+
+    def apply(
+        self,
+        f,
+        align_keys: list[str] | None = None,
+        **kwargs,
+    ) -> Self:
+        """
+        Iterate over the blocks, collect and create a new BlockManager.
+
+        Parameters
+        ----------
+        f : str or callable
+            Name of the Block method to apply.
+        align_keys: List[str] or None, default None
+        **kwargs
+            Keywords to pass to `f`
+
+        Returns
+        -------
+        BlockManager
+        """
+        assert "filter" not in kwargs
+
+        align_keys = align_keys or []
+        result_blocks: list[Block] = []
+        # fillna: Series/DataFrame is responsible for making sure value is aligned
+
+        aligned_args = {k: kwargs[k] for k in align_keys}
+
+        for b in self.blocks:
+            if aligned_args:
+                for k, obj in aligned_args.items():
+                    if isinstance(obj, (ABCSeries, ABCDataFrame)):
+                        # The caller is responsible for ensuring that
+                        #  obj.axes[-1].equals(self.items)
+                        if obj.ndim == 1:
+                            kwargs[k] = obj.iloc[b.mgr_locs.indexer]._values
+                        else:
+                            kwargs[k] = obj.iloc[:, b.mgr_locs.indexer]._values
+                    else:
+                        # otherwise we have an ndarray
+                        kwargs[k] = obj[b.mgr_locs.indexer]
+
+            if callable(f):
+                applied = b.apply(f, **kwargs)
+            else:
+                applied = getattr(b, f)(**kwargs)
+            result_blocks = extend_blocks(applied, result_blocks)
+
+        out = type(self).from_blocks(result_blocks, self.axes)
+        return out
+
+    # Alias so we can share code with ArrayManager
+    apply_with_block = apply
+
+    def setitem(self, indexer, value, warn: bool = True) -> Self:
+        """
+        Set values with indexer.
+
+        For SingleBlockManager, this backs s[indexer] = value
+        """
+        if isinstance(indexer, np.ndarray) and indexer.ndim > self.ndim:
+            raise ValueError(f"Cannot set values with ndim > {self.ndim}")
+
+        if warn and warn_copy_on_write() and not self._has_no_reference(0):
+            warnings.warn(
+                COW_WARNING_GENERAL_MSG,
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        elif using_copy_on_write() and not self._has_no_reference(0):
+            # this method is only called if there is a single block -> hardcoded 0
+            # Split blocks to only copy the columns we want to modify
+            if self.ndim == 2 and isinstance(indexer, tuple):
+                blk_loc = self.blklocs[indexer[1]]
+                if is_list_like(blk_loc) and blk_loc.ndim == 2:
+                    blk_loc = np.squeeze(blk_loc, axis=0)
+                elif not is_list_like(blk_loc):
+                    # Keep dimension and copy data later
+                    blk_loc = [blk_loc]  # type: ignore[assignment]
+                if len(blk_loc) == 0:
+                    return self.copy(deep=False)
+
+                values = self.blocks[0].values
+                if values.ndim == 2:
+                    values = values[blk_loc]
+                    # "T" has no attribute "_iset_split_block"
+                    self._iset_split_block(  # type: ignore[attr-defined]
+                        0, blk_loc, values
+                    )
+
+                    indexer = list(indexer)
+                    # first block equals values we are setting to -> set to all columns
+                    if lib.is_integer(indexer[1]):
+                        col_indexer = 0
+                    elif len(blk_loc) > 1:
+                        col_indexer = slice(None)  # type: ignore[assignment]
+                    else:
+                        col_indexer = np.arange(len(blk_loc))  # type: ignore[assignment]
+                    indexer[1] = col_indexer
+
+                    row_indexer = indexer[0]
+                    if isinstance(row_indexer, np.ndarray) and row_indexer.ndim == 2:
+                        # numpy cannot handle a 2d indexer in combo with a slice
+                        row_indexer = np.squeeze(row_indexer, axis=1)
+                    if isinstance(row_indexer, np.ndarray) and len(row_indexer) == 0:
+                        # numpy does not like empty indexer combined with slice
+                        # and we are setting nothing anyway
+                        return self
+                    indexer[0] = row_indexer
+                    self.blocks[0].setitem(tuple(indexer), value)
+                    return self
+            # No need to split if we either set all columns or on a single block
+            # manager
+            self = self.copy()
+
+        return self.apply("setitem", indexer=indexer, value=value)
+
+    def diff(self, n: int) -> Self:
+        # only reached with self.ndim == 2
+        return self.apply("diff", n=n)
+
+    def astype(self, dtype, copy: bool | None = False, errors: str = "raise") -> Self:
+        if copy is None:
+            if using_copy_on_write():
+                copy = False
+            else:
+                copy = True
+        elif using_copy_on_write():
+            copy = False
+
+        return self.apply(
+            "astype",
+            dtype=dtype,
+            copy=copy,
+            errors=errors,
+            using_cow=using_copy_on_write(),
+        )
+
+    def convert(self, copy: bool | None) -> Self:
+        if copy is None:
+            if using_copy_on_write():
+                copy = False
+            else:
+                copy = True
+        elif using_copy_on_write():
+            copy = False
+
+        return self.apply("convert", copy=copy, using_cow=using_copy_on_write())
+
+    def convert_dtypes(self, **kwargs):
+        if using_copy_on_write():
+            copy = False
+        else:
+            copy = True
+
+        return self.apply(
+            "convert_dtypes", copy=copy, using_cow=using_copy_on_write(), **kwargs
+        )
+
+    def get_values_for_csv(
+        self, *, float_format, date_format, decimal, na_rep: str = "nan", quoting=None
+    ) -> Self:
+        """
+        Convert values to native types (strings / python objects) that are used
+        in formatting (repr / csv).
+        """
+        return self.apply(
+            "get_values_for_csv",
+            na_rep=na_rep,
+            quoting=quoting,
+            float_format=float_format,
+            date_format=date_format,
+            decimal=decimal,
+        )
+
+    @property
+    def any_extension_types(self) -> bool:
+        """Whether any of the blocks in this manager are extension blocks"""
+        return any(block.is_extension for block in self.blocks)
+
+    @property
+    def is_view(self) -> bool:
+        """return a boolean if we are a single block and are a view"""
+        if len(self.blocks) == 1:
+            return self.blocks[0].is_view
+
+        # It is technically possible to figure out which blocks are views
+        # e.g. [ b.values.base is not None for b in self.blocks ]
+        # but then we have the case of possibly some blocks being a view
+        # and some blocks not. setting in theory is possible on the non-view
+        # blocks w/o causing a SettingWithCopy raise/warn. But this is a bit
+        # complicated
+
+        return False
+
+    def _get_data_subset(self, predicate: Callable) -> Self:
+        blocks = [blk for blk in self.blocks if predicate(blk.values)]
+        return self._combine(blocks)
+
+    def get_bool_data(self) -> Self:
+        """
+        Select blocks that are bool-dtype and columns from object-dtype blocks
+        that are all-bool.
+        """
+
+        new_blocks = []
+
+        for blk in self.blocks:
+            if blk.dtype == bool:
+                new_blocks.append(blk)
+
+            elif blk.is_object:
+                nbs = blk._split()
+                new_blocks.extend(nb for nb in nbs if nb.is_bool)
+
+        return self._combine(new_blocks)
+
+    def get_numeric_data(self) -> Self:
+        numeric_blocks = [blk for blk in self.blocks if blk.is_numeric]
+        if len(numeric_blocks) == len(self.blocks):
+            # Avoid somewhat expensive _combine
+            return self
+        return self._combine(numeric_blocks)
+
+    def _combine(self, blocks: list[Block], index: Index | None = None) -> Self:
+        """return a new manager with the blocks"""
+        if len(blocks) == 0:
+            if self.ndim == 2:
+                # retain our own Index dtype
+                if index is not None:
+                    axes = [self.items[:0], index]
+                else:
+                    axes = [self.items[:0]] + self.axes[1:]
+                return self.make_empty(axes)
+            return self.make_empty()
+
+        # FIXME: optimization potential
+        indexer = np.sort(np.concatenate([b.mgr_locs.as_array for b in blocks]))
+        inv_indexer = lib.get_reverse_indexer(indexer, self.shape[0])
+
+        new_blocks: list[Block] = []
+        for b in blocks:
+            nb = b.copy(deep=False)
+            nb.mgr_locs = BlockPlacement(inv_indexer[nb.mgr_locs.indexer])
+            new_blocks.append(nb)
+
+        axes = list(self.axes)
+        if index is not None:
+            axes[-1] = index
+        axes[0] = self.items.take(indexer)
+
+        return type(self).from_blocks(new_blocks, axes)
+
+    @property
+    def nblocks(self) -> int:
+        return len(self.blocks)
+
+    def copy(self, deep: bool | None | Literal["all"] = True) -> Self:
+        """
+        Make deep or shallow copy of BlockManager
+
+        Parameters
+        ----------
+        deep : bool, string or None, default True
+            If False or None, return a shallow copy (do not copy data)
+            If 'all', copy data and a deep copy of the index
+
+        Returns
+        -------
+        BlockManager
+        """
+        if deep is None:
+            if using_copy_on_write():
+                # use shallow copy
+                deep = False
+            else:
+                # preserve deep copy for BlockManager with copy=None
+                deep = True
+
+        # this preserves the notion of view copying of axes
+        if deep:
+            # hit in e.g. tests.io.json.test_pandas
+
+            def copy_func(ax):
+                return ax.copy(deep=True) if deep == "all" else ax.view()
+
+            new_axes = [copy_func(ax) for ax in self.axes]
+        else:
+            if using_copy_on_write():
+                new_axes = [ax.view() for ax in self.axes]
+            else:
+                new_axes = list(self.axes)
+
+        res = self.apply("copy", deep=deep)
+        res.axes = new_axes
+
+        if self.ndim > 1:
+            # Avoid needing to re-compute these
+            blknos = self._blknos
+            if blknos is not None:
+                res._blknos = blknos.copy()
+                res._blklocs = self._blklocs.copy()
+
+        if deep:
+            res._consolidate_inplace()
+        return res
+
+    def consolidate(self) -> Self:
+        """
+        Join together blocks having same dtype
+
+        Returns
+        -------
+        y : BlockManager
+        """
+        if self.is_consolidated():
+            return self
+
+        bm = type(self)(self.blocks, self.axes, verify_integrity=False)
+        bm._is_consolidated = False
+        bm._consolidate_inplace()
+        return bm
+
+    def reindex_indexer(
+        self,
+        new_axis: Index,
+        indexer: npt.NDArray[np.intp] | None,
+        axis: AxisInt,
+        fill_value=None,
+        allow_dups: bool = False,
+        copy: bool | None = True,
+        only_slice: bool = False,
+        *,
+        use_na_proxy: bool = False,
+    ) -> Self:
+        """
+        Parameters
+        ----------
+        new_axis : Index
+        indexer : ndarray[intp] or None
+        axis : int
+        fill_value : object, default None
+        allow_dups : bool, default False
+        copy : bool or None, default True
+            If None, regard as False to get shallow copy.
+        only_slice : bool, default False
+            Whether to take views, not copies, along columns.
+        use_na_proxy : bool, default False
+            Whether to use a np.void ndarray for newly introduced columns.
+
+        pandas-indexer with -1's only.
+        """
+        if copy is None:
+            if using_copy_on_write():
+                # use shallow copy
+                copy = False
+            else:
+                # preserve deep copy for BlockManager with copy=None
+                copy = True
+
+        if indexer is None:
+            if new_axis is self.axes[axis] and not copy:
+                return self
+
+            result = self.copy(deep=copy)
+            result.axes = list(self.axes)
+            result.axes[axis] = new_axis
+            return result
+
+        # Should be intp, but in some cases we get int64 on 32bit builds
+        assert isinstance(indexer, np.ndarray)
+
+        # some axes don't allow reindexing with dups
+        if not allow_dups:
+            self.axes[axis]._validate_can_reindex(indexer)
+
+        if axis >= self.ndim:
+            raise IndexError("Requested axis not found in manager")
+
+        if axis == 0:
+            new_blocks = self._slice_take_blocks_ax0(
+                indexer,
+                fill_value=fill_value,
+                only_slice=only_slice,
+                use_na_proxy=use_na_proxy,
+            )
+        else:
+            new_blocks = [
+                blk.take_nd(
+                    indexer,
+                    axis=1,
+                    fill_value=(
+                        fill_value if fill_value is not None else blk.fill_value
+                    ),
+                )
+                for blk in self.blocks
+            ]
+
+        new_axes = list(self.axes)
+        new_axes[axis] = new_axis
+
+        new_mgr = type(self).from_blocks(new_blocks, new_axes)
+        if axis == 1:
+            # We can avoid the need to rebuild these
+            new_mgr._blknos = self.blknos.copy()
+            new_mgr._blklocs = self.blklocs.copy()
+        return new_mgr
+
+    def _slice_take_blocks_ax0(
+        self,
+        slice_or_indexer: slice | np.ndarray,
+        fill_value=lib.no_default,
+        only_slice: bool = False,
+        *,
+        use_na_proxy: bool = False,
+        ref_inplace_op: bool = False,
+    ) -> list[Block]:
+        """
+        Slice/take blocks along axis=0.
+
+        Overloaded for SingleBlock
+
+        Parameters
+        ----------
+        slice_or_indexer : slice or np.ndarray[int64]
+        fill_value : scalar, default lib.no_default
+        only_slice : bool, default False
+            If True, we always return views on existing arrays, never copies.
+            This is used when called from ops.blockwise.operate_blockwise.
+        use_na_proxy : bool, default False
+            Whether to use a np.void ndarray for newly introduced columns.
+        ref_inplace_op: bool, default False
+            Don't track refs if True because we operate inplace
+
+        Returns
+        -------
+        new_blocks : list of Block
+        """
+        allow_fill = fill_value is not lib.no_default
+
+        sl_type, slobj, sllen = _preprocess_slice_or_indexer(
+            slice_or_indexer, self.shape[0], allow_fill=allow_fill
+        )
+
+        if self.is_single_block:
+            blk = self.blocks[0]
+
+            if sl_type == "slice":
+                # GH#32959 EABlock would fail since we can't make 0-width
+                # TODO(EA2D): special casing unnecessary with 2D EAs
+                if sllen == 0:
+                    return []
+                bp = BlockPlacement(slice(0, sllen))
+                return [blk.getitem_block_columns(slobj, new_mgr_locs=bp)]
+            elif not allow_fill or self.ndim == 1:
+                if allow_fill and fill_value is None:
+                    fill_value = blk.fill_value
+
+                if not allow_fill and only_slice:
+                    # GH#33597 slice instead of take, so we get
+                    #  views instead of copies
+                    blocks = [
+                        blk.getitem_block_columns(
+                            slice(ml, ml + 1),
+                            new_mgr_locs=BlockPlacement(i),
+                            ref_inplace_op=ref_inplace_op,
+                        )
+                        for i, ml in enumerate(slobj)
+                    ]
+                    return blocks
+                else:
+                    bp = BlockPlacement(slice(0, sllen))
+                    return [
+                        blk.take_nd(
+                            slobj,
+                            axis=0,
+                            new_mgr_locs=bp,
+                            fill_value=fill_value,
+                        )
+                    ]
+
+        if sl_type == "slice":
+            blknos = self.blknos[slobj]
+            blklocs = self.blklocs[slobj]
+        else:
+            blknos = algos.take_nd(
+                self.blknos, slobj, fill_value=-1, allow_fill=allow_fill
+            )
+            blklocs = algos.take_nd(
+                self.blklocs, slobj, fill_value=-1, allow_fill=allow_fill
+            )
+
+        # When filling blknos, make sure blknos is updated before appending to
+        # blocks list, that way new blkno is exactly len(blocks).
+        blocks = []
+        group = not only_slice
+        for blkno, mgr_locs in libinternals.get_blkno_placements(blknos, group=group):
+            if blkno == -1:
+                # If we've got here, fill_value was not lib.no_default
+
+                blocks.append(
+                    self._make_na_block(
+                        placement=mgr_locs,
+                        fill_value=fill_value,
+                        use_na_proxy=use_na_proxy,
+                    )
+                )
+            else:
+                blk = self.blocks[blkno]
+
+                # Otherwise, slicing along items axis is necessary.
+                if not blk._can_consolidate and not blk._validate_ndim:
+                    # i.e. we dont go through here for DatetimeTZBlock
+                    # A non-consolidatable block, it's easy, because there's
+                    # only one item and each mgr loc is a copy of that single
+                    # item.
+                    deep = not (only_slice or using_copy_on_write())
+                    for mgr_loc in mgr_locs:
+                        newblk = blk.copy(deep=deep)
+                        newblk.mgr_locs = BlockPlacement(slice(mgr_loc, mgr_loc + 1))
+                        blocks.append(newblk)
+
+                else:
+                    # GH#32779 to avoid the performance penalty of copying,
+                    #  we may try to only slice
+                    taker = blklocs[mgr_locs.indexer]
+                    max_len = max(len(mgr_locs), taker.max() + 1)
+                    if only_slice or using_copy_on_write():
+                        taker = lib.maybe_indices_to_slice(taker, max_len)
+
+                    if isinstance(taker, slice):
+                        nb = blk.getitem_block_columns(taker, new_mgr_locs=mgr_locs)
+                        blocks.append(nb)
+                    elif only_slice:
+                        # GH#33597 slice instead of take, so we get
+                        #  views instead of copies
+                        for i, ml in zip(taker, mgr_locs):
+                            slc = slice(i, i + 1)
+                            bp = BlockPlacement(ml)
+                            nb = blk.getitem_block_columns(slc, new_mgr_locs=bp)
+                            # We have np.shares_memory(nb.values, blk.values)
+                            blocks.append(nb)
+                    else:
+                        nb = blk.take_nd(taker, axis=0, new_mgr_locs=mgr_locs)
+                        blocks.append(nb)
+
+        return blocks
+
+    def _make_na_block(
+        self, placement: BlockPlacement, fill_value=None, use_na_proxy: bool = False
+    ) -> Block:
+        # Note: we only get here with self.ndim == 2
+
+        if use_na_proxy:
+            assert fill_value is None
+            shape = (len(placement), self.shape[1])
+            vals = np.empty(shape, dtype=np.void)
+            nb = NumpyBlock(vals, placement, ndim=2)
+            return nb
+
+        if fill_value is None:
+            fill_value = np.nan
+
+        shape = (len(placement), self.shape[1])
+
+        dtype, fill_value = infer_dtype_from_scalar(fill_value)
+        block_values = make_na_array(dtype, shape, fill_value)
+        return new_block_2d(block_values, placement=placement)
+
+    def take(
+        self,
+        indexer: npt.NDArray[np.intp],
+        axis: AxisInt = 1,
+        verify: bool = True,
+    ) -> Self:
+        """
+        Take items along any axis.
+
+        indexer : np.ndarray[np.intp]
+        axis : int, default 1
+        verify : bool, default True
+            Check that all entries are between 0 and len(self) - 1, inclusive.
+            Pass verify=False if this check has been done by the caller.
+
+        Returns
+        -------
+        BlockManager
+        """
+        # Caller is responsible for ensuring indexer annotation is accurate
+
+        n = self.shape[axis]
+        indexer = maybe_convert_indices(indexer, n, verify=verify)
+
+        new_labels = self.axes[axis].take(indexer)
+        return self.reindex_indexer(
+            new_axis=new_labels,
+            indexer=indexer,
+            axis=axis,
+            allow_dups=True,
+            copy=None,
+        )
+
+
+class BlockManager(libinternals.BlockManager, BaseBlockManager):
+    """
+    BaseBlockManager that holds 2D blocks.
+    """
+
+    ndim = 2
+
+    # ----------------------------------------------------------------
+    # Constructors
+
+    def __init__(
+        self,
+        blocks: Sequence[Block],
+        axes: Sequence[Index],
+        verify_integrity: bool = True,
+    ) -> None:
+        if verify_integrity:
+            # Assertion disabled for performance
+            # assert all(isinstance(x, Index) for x in axes)
+
+            for block in blocks:
+                if self.ndim != block.ndim:
+                    raise AssertionError(
+                        f"Number of Block dimensions ({block.ndim}) must equal "
+                        f"number of axes ({self.ndim})"
+                    )
+                # As of 2.0, the caller is responsible for ensuring that
+                #  DatetimeTZBlock with block.ndim == 2 has block.values.ndim ==2;
+                #  previously there was a special check for fastparquet compat.
+
+            self._verify_integrity()
+
+    def _verify_integrity(self) -> None:
+        mgr_shape = self.shape
+        tot_items = sum(len(x.mgr_locs) for x in self.blocks)
+        for block in self.blocks:
+            if block.shape[1:] != mgr_shape[1:]:
+                raise_construction_error(tot_items, block.shape[1:], self.axes)
+        if len(self.items) != tot_items:
+            raise AssertionError(
+                "Number of manager items must equal union of "
+                f"block items\n# manager items: {len(self.items)}, # "
+                f"tot_items: {tot_items}"
+            )
+
+    @classmethod
+    def from_blocks(cls, blocks: list[Block], axes: list[Index]) -> Self:
+        """
+        Constructor for BlockManager and SingleBlockManager with same signature.
+        """
+        return cls(blocks, axes, verify_integrity=False)
+
+    # ----------------------------------------------------------------
+    # Indexing
+
+    def fast_xs(self, loc: int) -> SingleBlockManager:
+        """
+        Return the array corresponding to `frame.iloc[loc]`.
+
+        Parameters
+        ----------
+        loc : int
+
+        Returns
+        -------
+        np.ndarray or ExtensionArray
+        """
+        if len(self.blocks) == 1:
+            # TODO: this could be wrong if blk.mgr_locs is not slice(None)-like;
+            #  is this ruled out in the general case?
+            result = self.blocks[0].iget((slice(None), loc))
+            # in the case of a single block, the new block is a view
+            bp = BlockPlacement(slice(0, len(result)))
+            block = new_block(
+                result,
+                placement=bp,
+                ndim=1,
+                refs=self.blocks[0].refs,
+            )
+            return SingleBlockManager(block, self.axes[0])
+
+        dtype = interleaved_dtype([blk.dtype for blk in self.blocks])
+
+        n = len(self)
+
+        if isinstance(dtype, ExtensionDtype):
+            # TODO: use object dtype as workaround for non-performant
+            #  EA.__setitem__ methods. (primarily ArrowExtensionArray.__setitem__
+            #  when iteratively setting individual values)
+            #  https://github.com/pandas-dev/pandas/pull/54508#issuecomment-1675827918
+            result = np.empty(n, dtype=object)
+        else:
+            result = np.empty(n, dtype=dtype)
+            result = ensure_wrapped_if_datetimelike(result)
+
+        for blk in self.blocks:
+            # Such assignment may incorrectly coerce NaT to None
+            # result[blk.mgr_locs] = blk._slice((slice(None), loc))
+            for i, rl in enumerate(blk.mgr_locs):
+                result[rl] = blk.iget((i, loc))
+
+        if isinstance(dtype, ExtensionDtype):
+            cls = dtype.construct_array_type()
+            result = cls._from_sequence(result, dtype=dtype)
+
+        bp = BlockPlacement(slice(0, len(result)))
+        block = new_block(result, placement=bp, ndim=1)
+        return SingleBlockManager(block, self.axes[0])
+
+    def iget(self, i: int, track_ref: bool = True) -> SingleBlockManager:
+        """
+        Return the data as a SingleBlockManager.
+        """
+        block = self.blocks[self.blknos[i]]
+        values = block.iget(self.blklocs[i])
+
+        # shortcut for select a single-dim from a 2-dim BM
+        bp = BlockPlacement(slice(0, len(values)))
+        nb = type(block)(
+            values, placement=bp, ndim=1, refs=block.refs if track_ref else None
+        )
+        return SingleBlockManager(nb, self.axes[1])
+
+    def iget_values(self, i: int) -> ArrayLike:
+        """
+        Return the data for column i as the values (ndarray or ExtensionArray).
+
+        Warning! The returned array is a view but doesn't handle Copy-on-Write,
+        so this should be used with caution.
+        """
+        # TODO(CoW) making the arrays read-only might make this safer to use?
+        block = self.blocks[self.blknos[i]]
+        values = block.iget(self.blklocs[i])
+        return values
+
+    @property
+    def column_arrays(self) -> list[np.ndarray]:
+        """
+        Used in the JSON C code to access column arrays.
+        This optimizes compared to using `iget_values` by converting each
+
+        Warning! This doesn't handle Copy-on-Write, so should be used with
+        caution (current use case of consuming this in the JSON code is fine).
+        """
+        # This is an optimized equivalent to
+        #  result = [self.iget_values(i) for i in range(len(self.items))]
+        result: list[np.ndarray | None] = [None] * len(self.items)
+
+        for blk in self.blocks:
+            mgr_locs = blk._mgr_locs
+            values = blk.array_values._values_for_json()
+            if values.ndim == 1:
+                # TODO(EA2D): special casing not needed with 2D EAs
+                result[mgr_locs[0]] = values
+
+            else:
+                for i, loc in enumerate(mgr_locs):
+                    result[loc] = values[i]
+
+        # error: Incompatible return value type (got "List[None]",
+        # expected "List[ndarray[Any, Any]]")
+        return result  # type: ignore[return-value]
+
+    def iset(
+        self,
+        loc: int | slice | np.ndarray,
+        value: ArrayLike,
+        inplace: bool = False,
+        refs: BlockValuesRefs | None = None,
+    ) -> None:
+        """
+        Set new item in-place. Does not consolidate. Adds new Block if not
+        contained in the current set of items
+        """
+
+        # FIXME: refactor, clearly separate broadcasting & zip-like assignment
+        #        can prob also fix the various if tests for sparse/categorical
+        if self._blklocs is None and self.ndim > 1:
+            self._rebuild_blknos_and_blklocs()
+
+        # Note: we exclude DTA/TDA here
+        value_is_extension_type = is_1d_only_ea_dtype(value.dtype)
+        if not value_is_extension_type:
+            if value.ndim == 2:
+                value = value.T
+            else:
+                value = ensure_block_shape(value, ndim=2)
+
+            if value.shape[1:] != self.shape[1:]:
+                raise AssertionError(
+                    "Shape of new values must be compatible with manager shape"
+                )
+
+        if lib.is_integer(loc):
+            # We have 6 tests where loc is _not_ an int.
+            # In this case, get_blkno_placements will yield only one tuple,
+            #  containing (self._blknos[loc], BlockPlacement(slice(0, 1, 1)))
+
+            # Check if we can use _iset_single fastpath
+            loc = cast(int, loc)
+            blkno = self.blknos[loc]
+            blk = self.blocks[blkno]
+            if len(blk._mgr_locs) == 1:  # TODO: fastest way to check this?
+                return self._iset_single(
+                    loc,
+                    value,
+                    inplace=inplace,
+                    blkno=blkno,
+                    blk=blk,
+                    refs=refs,
+                )
+
+            # error: Incompatible types in assignment (expression has type
+            # "List[Union[int, slice, ndarray]]", variable has type "Union[int,
+            # slice, ndarray]")
+            loc = [loc]  # type: ignore[assignment]
+
+        # categorical/sparse/datetimetz
+        if value_is_extension_type:
+
+            def value_getitem(placement):
+                return value
+
+        else:
+
+            def value_getitem(placement):
+                return value[placement.indexer]
+
+        # Accessing public blknos ensures the public versions are initialized
+        blknos = self.blknos[loc]
+        blklocs = self.blklocs[loc].copy()
+
+        unfit_mgr_locs = []
+        unfit_val_locs = []
+        removed_blknos = []
+        for blkno_l, val_locs in libinternals.get_blkno_placements(blknos, group=True):
+            blk = self.blocks[blkno_l]
+            blk_locs = blklocs[val_locs.indexer]
+            if inplace and blk.should_store(value):
+                # Updating inplace -> check if we need to do Copy-on-Write
+                if using_copy_on_write() and not self._has_no_reference_block(blkno_l):
+                    self._iset_split_block(
+                        blkno_l, blk_locs, value_getitem(val_locs), refs=refs
+                    )
+                else:
+                    blk.set_inplace(blk_locs, value_getitem(val_locs))
+                    continue
+            else:
+                unfit_mgr_locs.append(blk.mgr_locs.as_array[blk_locs])
+                unfit_val_locs.append(val_locs)
+
+                # If all block items are unfit, schedule the block for removal.
+                if len(val_locs) == len(blk.mgr_locs):
+                    removed_blknos.append(blkno_l)
+                    continue
+                else:
+                    # Defer setting the new values to enable consolidation
+                    self._iset_split_block(blkno_l, blk_locs, refs=refs)
+
+        if len(removed_blknos):
+            # Remove blocks & update blknos accordingly
+            is_deleted = np.zeros(self.nblocks, dtype=np.bool_)
+            is_deleted[removed_blknos] = True
+
+            new_blknos = np.empty(self.nblocks, dtype=np.intp)
+            new_blknos.fill(-1)
+            new_blknos[~is_deleted] = np.arange(self.nblocks - len(removed_blknos))
+            self._blknos = new_blknos[self._blknos]
+            self.blocks = tuple(
+                blk for i, blk in enumerate(self.blocks) if i not in set(removed_blknos)
+            )
+
+        if unfit_val_locs:
+            unfit_idxr = np.concatenate(unfit_mgr_locs)
+            unfit_count = len(unfit_idxr)
+
+            new_blocks: list[Block] = []
+            if value_is_extension_type:
+                # This code (ab-)uses the fact that EA blocks contain only
+                # one item.
+                # TODO(EA2D): special casing unnecessary with 2D EAs
+                new_blocks.extend(
+                    new_block_2d(
+                        values=value,
+                        placement=BlockPlacement(slice(mgr_loc, mgr_loc + 1)),
+                        refs=refs,
+                    )
+                    for mgr_loc in unfit_idxr
+                )
+
+                self._blknos[unfit_idxr] = np.arange(unfit_count) + len(self.blocks)
+                self._blklocs[unfit_idxr] = 0
+
+            else:
+                # unfit_val_locs contains BlockPlacement objects
+                unfit_val_items = unfit_val_locs[0].append(unfit_val_locs[1:])
+
+                new_blocks.append(
+                    new_block_2d(
+                        values=value_getitem(unfit_val_items),
+                        placement=BlockPlacement(unfit_idxr),
+                        refs=refs,
+                    )
+                )
+
+                self._blknos[unfit_idxr] = len(self.blocks)
+                self._blklocs[unfit_idxr] = np.arange(unfit_count)
+
+            self.blocks += tuple(new_blocks)
+
+            # Newly created block's dtype may already be present.
+            self._known_consolidated = False
+
+    def _iset_split_block(
+        self,
+        blkno_l: int,
+        blk_locs: np.ndarray | list[int],
+        value: ArrayLike | None = None,
+        refs: BlockValuesRefs | None = None,
+    ) -> None:
+        """Removes columns from a block by splitting the block.
+
+        Avoids copying the whole block through slicing and updates the manager
+        after determinint the new block structure. Optionally adds a new block,
+        otherwise has to be done by the caller.
+
+        Parameters
+        ----------
+        blkno_l: The block number to operate on, relevant for updating the manager
+        blk_locs: The locations of our block that should be deleted.
+        value: The value to set as a replacement.
+        refs: The reference tracking object of the value to set.
+        """
+        blk = self.blocks[blkno_l]
+
+        if self._blklocs is None:
+            self._rebuild_blknos_and_blklocs()
+
+        nbs_tup = tuple(blk.delete(blk_locs))
+        if value is not None:
+            locs = blk.mgr_locs.as_array[blk_locs]
+            first_nb = new_block_2d(value, BlockPlacement(locs), refs=refs)
+        else:
+            first_nb = nbs_tup[0]
+            nbs_tup = tuple(nbs_tup[1:])
+
+        nr_blocks = len(self.blocks)
+        blocks_tup = (
+            self.blocks[:blkno_l] + (first_nb,) + self.blocks[blkno_l + 1 :] + nbs_tup
+        )
+        self.blocks = blocks_tup
+
+        if not nbs_tup and value is not None:
+            # No need to update anything if split did not happen
+            return
+
+        self._blklocs[first_nb.mgr_locs.indexer] = np.arange(len(first_nb))
+
+        for i, nb in enumerate(nbs_tup):
+            self._blklocs[nb.mgr_locs.indexer] = np.arange(len(nb))
+            self._blknos[nb.mgr_locs.indexer] = i + nr_blocks
+
+    def _iset_single(
+        self,
+        loc: int,
+        value: ArrayLike,
+        inplace: bool,
+        blkno: int,
+        blk: Block,
+        refs: BlockValuesRefs | None = None,
+    ) -> None:
+        """
+        Fastpath for iset when we are only setting a single position and
+        the Block currently in that position is itself single-column.
+
+        In this case we can swap out the entire Block and blklocs and blknos
+        are unaffected.
+        """
+        # Caller is responsible for verifying value.shape
+
+        if inplace and blk.should_store(value):
+            copy = False
+            if using_copy_on_write() and not self._has_no_reference_block(blkno):
+                # perform Copy-on-Write and clear the reference
+                copy = True
+            iloc = self.blklocs[loc]
+            blk.set_inplace(slice(iloc, iloc + 1), value, copy=copy)
+            return
+
+        nb = new_block_2d(value, placement=blk._mgr_locs, refs=refs)
+        old_blocks = self.blocks
+        new_blocks = old_blocks[:blkno] + (nb,) + old_blocks[blkno + 1 :]
+        self.blocks = new_blocks
+        return
+
+    def column_setitem(
+        self, loc: int, idx: int | slice | np.ndarray, value, inplace_only: bool = False
+    ) -> None:
+        """
+        Set values ("setitem") into a single column (not setting the full column).
+
+        This is a method on the BlockManager level, to avoid creating an
+        intermediate Series at the DataFrame level (`s = df[loc]; s[idx] = value`)
+        """
+        needs_to_warn = False
+        if warn_copy_on_write() and not self._has_no_reference(loc):
+            if not isinstance(
+                self.blocks[self.blknos[loc]].values,
+                (ArrowExtensionArray, ArrowStringArray),
+            ):
+                # We might raise if we are in an expansion case, so defer
+                # warning till we actually updated
+                needs_to_warn = True
+
+        elif using_copy_on_write() and not self._has_no_reference(loc):
+            blkno = self.blknos[loc]
+            # Split blocks to only copy the column we want to modify
+            blk_loc = self.blklocs[loc]
+            # Copy our values
+            values = self.blocks[blkno].values
+            if values.ndim == 1:
+                values = values.copy()
+            else:
+                # Use [blk_loc] as indexer to keep ndim=2, this already results in a
+                # copy
+                values = values[[blk_loc]]
+            self._iset_split_block(blkno, [blk_loc], values)
+
+        # this manager is only created temporarily to mutate the values in place
+        # so don't track references, otherwise the `setitem` would perform CoW again
+        col_mgr = self.iget(loc, track_ref=False)
+        if inplace_only:
+            col_mgr.setitem_inplace(idx, value)
+        else:
+            new_mgr = col_mgr.setitem((idx,), value)
+            self.iset(loc, new_mgr._block.values, inplace=True)
+
+        if needs_to_warn:
+            warnings.warn(
+                COW_WARNING_GENERAL_MSG,
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    def insert(self, loc: int, item: Hashable, value: ArrayLike, refs=None) -> None:
+        """
+        Insert item at selected position.
+
+        Parameters
+        ----------
+        loc : int
+        item : hashable
+        value : np.ndarray or ExtensionArray
+        refs : The reference tracking object of the value to set.
+        """
+        with warnings.catch_warnings():
+            # TODO: re-issue this with setitem-specific message?
+            warnings.filterwarnings(
+                "ignore",
+                "The behavior of Index.insert with object-dtype is deprecated",
+                category=FutureWarning,
+            )
+            new_axis = self.items.insert(loc, item)
+
+        if value.ndim == 2:
+            value = value.T
+            if len(value) > 1:
+                raise ValueError(
+                    f"Expected a 1D array, got an array with shape {value.T.shape}"
+                )
+        else:
+            value = ensure_block_shape(value, ndim=self.ndim)
+
+        bp = BlockPlacement(slice(loc, loc + 1))
+        block = new_block_2d(values=value, placement=bp, refs=refs)
+
+        if not len(self.blocks):
+            # Fastpath
+            self._blklocs = np.array([0], dtype=np.intp)
+            self._blknos = np.array([0], dtype=np.intp)
+        else:
+            self._insert_update_mgr_locs(loc)
+            self._insert_update_blklocs_and_blknos(loc)
+
+        self.axes[0] = new_axis
+        self.blocks += (block,)
+
+        self._known_consolidated = False
+
+        if sum(not block.is_extension for block in self.blocks) > 100:
+            warnings.warn(
+                "DataFrame is highly fragmented.  This is usually the result "
+                "of calling `frame.insert` many times, which has poor performance.  "
+                "Consider joining all columns at once using pd.concat(axis=1) "
+                "instead. To get a de-fragmented frame, use `newframe = frame.copy()`",
+                PerformanceWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    def _insert_update_mgr_locs(self, loc) -> None:
+        """
+        When inserting a new Block at location 'loc', we increment
+        all of the mgr_locs of blocks above that by one.
+        """
+        for blkno, count in _fast_count_smallints(self.blknos[loc:]):
+            # .620 this way, .326 of which is in increment_above
+            blk = self.blocks[blkno]
+            blk._mgr_locs = blk._mgr_locs.increment_above(loc)
+
+    def _insert_update_blklocs_and_blknos(self, loc) -> None:
+        """
+        When inserting a new Block at location 'loc', we update our
+        _blklocs and _blknos.
+        """
+
+        # Accessing public blklocs ensures the public versions are initialized
+        if loc == self.blklocs.shape[0]:
+            # np.append is a lot faster, let's use it if we can.
+            self._blklocs = np.append(self._blklocs, 0)
+            self._blknos = np.append(self._blknos, len(self.blocks))
+        elif loc == 0:
+            # np.append is a lot faster, let's use it if we can.
+            self._blklocs = np.append(self._blklocs[::-1], 0)[::-1]
+            self._blknos = np.append(self._blknos[::-1], len(self.blocks))[::-1]
+        else:
+            new_blklocs, new_blknos = libinternals.update_blklocs_and_blknos(
+                self.blklocs, self.blknos, loc, len(self.blocks)
+            )
+            self._blklocs = new_blklocs
+            self._blknos = new_blknos
+
+    def idelete(self, indexer) -> BlockManager:
+        """
+        Delete selected locations, returning a new BlockManager.
+        """
+        is_deleted = np.zeros(self.shape[0], dtype=np.bool_)
+        is_deleted[indexer] = True
+        taker = (~is_deleted).nonzero()[0]
+
+        nbs = self._slice_take_blocks_ax0(taker, only_slice=True, ref_inplace_op=True)
+        new_columns = self.items[~is_deleted]
+        axes = [new_columns, self.axes[1]]
+        return type(self)(tuple(nbs), axes, verify_integrity=False)
+
+    # ----------------------------------------------------------------
+    # Block-wise Operation
+
+    def grouped_reduce(self, func: Callable) -> Self:
+        """
+        Apply grouped reduction function blockwise, returning a new BlockManager.
+
+        Parameters
+        ----------
+        func : grouped reduction function
+
+        Returns
+        -------
+        BlockManager
+        """
+        result_blocks: list[Block] = []
+
+        for blk in self.blocks:
+            if blk.is_object:
+                # split on object-dtype blocks bc some columns may raise
+                #  while others do not.
+                for sb in blk._split():
+                    applied = sb.apply(func)
+                    result_blocks = extend_blocks(applied, result_blocks)
+            else:
+                applied = blk.apply(func)
+                result_blocks = extend_blocks(applied, result_blocks)
+
+        if len(result_blocks) == 0:
+            nrows = 0
+        else:
+            nrows = result_blocks[0].values.shape[-1]
+        index = Index(range(nrows))
+
+        return type(self).from_blocks(result_blocks, [self.axes[0], index])
+
+    def reduce(self, func: Callable) -> Self:
+        """
+        Apply reduction function blockwise, returning a single-row BlockManager.
+
+        Parameters
+        ----------
+        func : reduction function
+
+        Returns
+        -------
+        BlockManager
+        """
+        # If 2D, we assume that we're operating column-wise
+        assert self.ndim == 2
+
+        res_blocks: list[Block] = []
+        for blk in self.blocks:
+            nbs = blk.reduce(func)
+            res_blocks.extend(nbs)
+
+        index = Index([None])  # placeholder
+        new_mgr = type(self).from_blocks(res_blocks, [self.items, index])
+        return new_mgr
+
+    def operate_blockwise(self, other: BlockManager, array_op) -> BlockManager:
+        """
+        Apply array_op blockwise with another (aligned) BlockManager.
+        """
+        return operate_blockwise(self, other, array_op)
+
+    def _equal_values(self: BlockManager, other: BlockManager) -> bool:
+        """
+        Used in .equals defined in base class. Only check the column values
+        assuming shape and indexes have already been checked.
+        """
+        return blockwise_all(self, other, array_equals)
+
+    def quantile(
+        self,
+        *,
+        qs: Index,  # with dtype float 64
+        interpolation: QuantileInterpolation = "linear",
+    ) -> Self:
+        """
+        Iterate over blocks applying quantile reduction.
+        This routine is intended for reduction type operations and
+        will do inference on the generated blocks.
+
+        Parameters
+        ----------
+        interpolation : type of interpolation, default 'linear'
+        qs : list of the quantiles to be computed
+
+        Returns
+        -------
+        BlockManager
+        """
+        # Series dispatches to DataFrame for quantile, which allows us to
+        #  simplify some of the code here and in the blocks
+        assert self.ndim >= 2
+        assert is_list_like(qs)  # caller is responsible for this
+
+        new_axes = list(self.axes)
+        new_axes[1] = Index(qs, dtype=np.float64)
+
+        blocks = [
+            blk.quantile(qs=qs, interpolation=interpolation) for blk in self.blocks
+        ]
+
+        return type(self)(blocks, new_axes)
+
+    # ----------------------------------------------------------------
+
+    def unstack(self, unstacker, fill_value) -> BlockManager:
+        """
+        Return a BlockManager with all blocks unstacked.
+
+        Parameters
+        ----------
+        unstacker : reshape._Unstacker
+        fill_value : Any
+            fill_value for newly introduced missing values.
+
+        Returns
+        -------
+        unstacked : BlockManager
+        """
+        new_columns = unstacker.get_new_columns(self.items)
+        new_index = unstacker.new_index
+
+        allow_fill = not unstacker.mask_all
+        if allow_fill:
+            # calculating the full mask once and passing it to Block._unstack is
+            #  faster than letting calculating it in each repeated call
+            new_mask2D = (~unstacker.mask).reshape(*unstacker.full_shape)
+            needs_masking = new_mask2D.any(axis=0)
+        else:
+            needs_masking = np.zeros(unstacker.full_shape[1], dtype=bool)
+
+        new_blocks: list[Block] = []
+        columns_mask: list[np.ndarray] = []
+
+        if len(self.items) == 0:
+            factor = 1
+        else:
+            fac = len(new_columns) / len(self.items)
+            assert fac == int(fac)
+            factor = int(fac)
+
+        for blk in self.blocks:
+            mgr_locs = blk.mgr_locs
+            new_placement = mgr_locs.tile_for_unstack(factor)
+
+            blocks, mask = blk._unstack(
+                unstacker,
+                fill_value,
+                new_placement=new_placement,
+                needs_masking=needs_masking,
+            )
+
+            new_blocks.extend(blocks)
+            columns_mask.extend(mask)
+
+            # Block._unstack should ensure this holds,
+            assert mask.sum() == sum(len(nb._mgr_locs) for nb in blocks)
+            # In turn this ensures that in the BlockManager call below
+            #  we have len(new_columns) == sum(x.shape[0] for x in new_blocks)
+            #  which suffices to allow us to pass verify_inegrity=False
+
+        new_columns = new_columns[columns_mask]
+
+        bm = BlockManager(new_blocks, [new_columns, new_index], verify_integrity=False)
+        return bm
+
+    def to_dict(self) -> dict[str, Self]:
+        """
+        Return a dict of str(dtype) -> BlockManager
+
+        Returns
+        -------
+        values : a dict of dtype -> BlockManager
+        """
+
+        bd: dict[str, list[Block]] = {}
+        for b in self.blocks:
+            bd.setdefault(str(b.dtype), []).append(b)
+
+        # TODO(EA2D): the combine will be unnecessary with 2D EAs
+        return {dtype: self._combine(blocks) for dtype, blocks in bd.items()}
+
+    def as_array(
+        self,
+        dtype: np.dtype | None = None,
+        copy: bool = False,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Convert the blockmanager data into an numpy array.
+
+        Parameters
+        ----------
+        dtype : np.dtype or None, default None
+            Data type of the return array.
+        copy : bool, default False
+            If True then guarantee that a copy is returned. A value of
+            False does not guarantee that the underlying data is not
+            copied.
+        na_value : object, default lib.no_default
+            Value to be used as the missing value sentinel.
+
+        Returns
+        -------
+        arr : ndarray
+        """
+        passed_nan = lib.is_float(na_value) and isna(na_value)
+
+        if len(self.blocks) == 0:
+            arr = np.empty(self.shape, dtype=float)
+            return arr.transpose()
+
+        if self.is_single_block:
+            blk = self.blocks[0]
+
+            if na_value is not lib.no_default:
+                # We want to copy when na_value is provided to avoid
+                # mutating the original object
+                if lib.is_np_dtype(blk.dtype, "f") and passed_nan:
+                    # We are already numpy-float and na_value=np.nan
+                    pass
+                else:
+                    copy = True
+
+            if blk.is_extension:
+                # Avoid implicit conversion of extension blocks to object
+
+                # error: Item "ndarray" of "Union[ndarray, ExtensionArray]" has no
+                # attribute "to_numpy"
+                arr = blk.values.to_numpy(  # type: ignore[union-attr]
+                    dtype=dtype,
+                    na_value=na_value,
+                    copy=copy,
+                ).reshape(blk.shape)
+            elif not copy:
+                arr = np.asarray(blk.values, dtype=dtype)
+            else:
+                arr = np.array(blk.values, dtype=dtype, copy=copy)
+
+            if using_copy_on_write() and not copy:
+                arr = arr.view()
+                arr.flags.writeable = False
+        else:
+            arr = self._interleave(dtype=dtype, na_value=na_value)
+            # The underlying data was copied within _interleave, so no need
+            # to further copy if copy=True or setting na_value
+
+        if na_value is lib.no_default:
+            pass
+        elif arr.dtype.kind == "f" and passed_nan:
+            pass
+        else:
+            arr[isna(arr)] = na_value
+
+        return arr.transpose()
+
+    def _interleave(
+        self,
+        dtype: np.dtype | None = None,
+        na_value: object = lib.no_default,
+    ) -> np.ndarray:
+        """
+        Return ndarray from blocks with specified item order
+        Items must be contained in the blocks
+        """
+        if not dtype:
+            # Incompatible types in assignment (expression has type
+            # "Optional[Union[dtype[Any], ExtensionDtype]]", variable has
+            # type "Optional[dtype[Any]]")
+            dtype = interleaved_dtype(  # type: ignore[assignment]
+                [blk.dtype for blk in self.blocks]
+            )
+
+        # error: Argument 1 to "ensure_np_dtype" has incompatible type
+        # "Optional[dtype[Any]]"; expected "Union[dtype[Any], ExtensionDtype]"
+        dtype = ensure_np_dtype(dtype)  # type: ignore[arg-type]
+        result = np.empty(self.shape, dtype=dtype)
+
+        itemmask = np.zeros(self.shape[0])
+
+        if dtype == np.dtype("object") and na_value is lib.no_default:
+            # much more performant than using to_numpy below
+            for blk in self.blocks:
+                rl = blk.mgr_locs
+                arr = blk.get_values(dtype)
+                result[rl.indexer] = arr
+                itemmask[rl.indexer] = 1
+            return result
+
+        for blk in self.blocks:
+            rl = blk.mgr_locs
+            if blk.is_extension:
+                # Avoid implicit conversion of extension blocks to object
+
+                # error: Item "ndarray" of "Union[ndarray, ExtensionArray]" has no
+                # attribute "to_numpy"
+                arr = blk.values.to_numpy(  # type: ignore[union-attr]
+                    dtype=dtype,
+                    na_value=na_value,
+                )
+            else:
+                arr = blk.get_values(dtype)
+            result[rl.indexer] = arr
+            itemmask[rl.indexer] = 1
+
+        if not itemmask.all():
+            raise AssertionError("Some items were not contained in blocks")
+
+        return result
+
+    # ----------------------------------------------------------------
+    # Consolidation
+
+    def is_consolidated(self) -> bool:
+        """
+        Return True if more than one block with the same dtype
+        """
+        if not self._known_consolidated:
+            self._consolidate_check()
+        return self._is_consolidated
+
+    def _consolidate_check(self) -> None:
+        if len(self.blocks) == 1:
+            # fastpath
+            self._is_consolidated = True
+            self._known_consolidated = True
+            return
+        dtypes = [blk.dtype for blk in self.blocks if blk._can_consolidate]
+        self._is_consolidated = len(dtypes) == len(set(dtypes))
+        self._known_consolidated = True
+
+    def _consolidate_inplace(self) -> None:
+        # In general, _consolidate_inplace should only be called via
+        #  DataFrame._consolidate_inplace, otherwise we will fail to invalidate
+        #  the DataFrame's _item_cache. The exception is for newly-created
+        #  BlockManager objects not yet attached to a DataFrame.
+        if not self.is_consolidated():
+            self.blocks = _consolidate(self.blocks)
+            self._is_consolidated = True
+            self._known_consolidated = True
+            self._rebuild_blknos_and_blklocs()
+
+    # ----------------------------------------------------------------
+    # Concatenation
+
+    @classmethod
+    def concat_horizontal(cls, mgrs: list[Self], axes: list[Index]) -> Self:
+        """
+        Concatenate uniformly-indexed BlockManagers horizontally.
+        """
+        offset = 0
+        blocks: list[Block] = []
+        for mgr in mgrs:
+            for blk in mgr.blocks:
+                # We need to do getitem_block here otherwise we would be altering
+                #  blk.mgr_locs in place, which would render it invalid. This is only
+                #  relevant in the copy=False case.
+                nb = blk.slice_block_columns(slice(None))
+                nb._mgr_locs = nb._mgr_locs.add(offset)
+                blocks.append(nb)
+
+            offset += len(mgr.items)
+
+        new_mgr = cls(tuple(blocks), axes)
+        return new_mgr
+
+    @classmethod
+    def concat_vertical(cls, mgrs: list[Self], axes: list[Index]) -> Self:
+        """
+        Concatenate uniformly-indexed BlockManagers vertically.
+        """
+        raise NotImplementedError("This logic lives (for now) in internals.concat")
+
+
+class SingleBlockManager(BaseBlockManager, SingleDataManager):
+    """manage a single block with"""
+
+    @property
+    def ndim(self) -> Literal[1]:
+        return 1
+
+    _is_consolidated = True
+    _known_consolidated = True
+    __slots__ = ()
+    is_single_block = True
+
+    def __init__(
+        self,
+        block: Block,
+        axis: Index,
+        verify_integrity: bool = False,
+    ) -> None:
+        # Assertions disabled for performance
+        # assert isinstance(block, Block), type(block)
+        # assert isinstance(axis, Index), type(axis)
+
+        self.axes = [axis]
+        self.blocks = (block,)
+
+    @classmethod
+    def from_blocks(
+        cls,
+        blocks: list[Block],
+        axes: list[Index],
+    ) -> Self:
+        """
+        Constructor for BlockManager and SingleBlockManager with same signature.
+        """
+        assert len(blocks) == 1
+        assert len(axes) == 1
+        return cls(blocks[0], axes[0], verify_integrity=False)
+
+    @classmethod
+    def from_array(
+        cls, array: ArrayLike, index: Index, refs: BlockValuesRefs | None = None
+    ) -> SingleBlockManager:
+        """
+        Constructor for if we have an array that is not yet a Block.
+        """
+        array = maybe_coerce_values(array)
+        bp = BlockPlacement(slice(0, len(index)))
+        block = new_block(array, placement=bp, ndim=1, refs=refs)
+        return cls(block, index)
+
+    def to_2d_mgr(self, columns: Index) -> BlockManager:
+        """
+        Manager analogue of Series.to_frame
+        """
+        blk = self.blocks[0]
+        arr = ensure_block_shape(blk.values, ndim=2)
+        bp = BlockPlacement(0)
+        new_blk = type(blk)(arr, placement=bp, ndim=2, refs=blk.refs)
+        axes = [columns, self.axes[0]]
+        return BlockManager([new_blk], axes=axes, verify_integrity=False)
+
+    def _has_no_reference(self, i: int = 0) -> bool:
+        """
+        Check for column `i` if it has references.
+        (whether it references another array or is itself being referenced)
+        Returns True if the column has no references.
+        """
+        return not self.blocks[0].refs.has_reference()
+
+    def __getstate__(self):
+        block_values = [b.values for b in self.blocks]
+        block_items = [self.items[b.mgr_locs.indexer] for b in self.blocks]
+        axes_array = list(self.axes)
+
+        extra_state = {
+            "0.14.1": {
+                "axes": axes_array,
+                "blocks": [
+                    {"values": b.values, "mgr_locs": b.mgr_locs.indexer}
+                    for b in self.blocks
+                ],
+            }
+        }
+
+        # First three elements of the state are to maintain forward
+        # compatibility with 0.13.1.
+        return axes_array, block_values, block_items, extra_state
+
+    def __setstate__(self, state) -> None:
+        def unpickle_block(values, mgr_locs, ndim: int) -> Block:
+            # TODO(EA2D): ndim would be unnecessary with 2D EAs
+            # older pickles may store e.g. DatetimeIndex instead of DatetimeArray
+            values = extract_array(values, extract_numpy=True)
+            if not isinstance(mgr_locs, BlockPlacement):
+                mgr_locs = BlockPlacement(mgr_locs)
+
+            values = maybe_coerce_values(values)
+            return new_block(values, placement=mgr_locs, ndim=ndim)
+
+        if isinstance(state, tuple) and len(state) >= 4 and "0.14.1" in state[3]:
+            state = state[3]["0.14.1"]
+            self.axes = [ensure_index(ax) for ax in state["axes"]]
+            ndim = len(self.axes)
+            self.blocks = tuple(
+                unpickle_block(b["values"], b["mgr_locs"], ndim=ndim)
+                for b in state["blocks"]
+            )
+        else:
+            raise NotImplementedError("pre-0.14.1 pickles are no longer supported")
+
+        self._post_setstate()
+
+    def _post_setstate(self) -> None:
+        pass
+
+    @cache_readonly
+    def _block(self) -> Block:
+        return self.blocks[0]
+
+    @property
+    def _blknos(self):
+        """compat with BlockManager"""
+        return None
+
+    @property
+    def _blklocs(self):
+        """compat with BlockManager"""
+        return None
+
+    def get_rows_with_mask(self, indexer: npt.NDArray[np.bool_]) -> Self:
+        # similar to get_slice, but not restricted to slice indexer
+        blk = self._block
+        if using_copy_on_write() and len(indexer) > 0 and indexer.all():
+            return type(self)(blk.copy(deep=False), self.index)
+        array = blk.values[indexer]
+
+        if isinstance(indexer, np.ndarray) and indexer.dtype.kind == "b":
+            # boolean indexing always gives a copy with numpy
+            refs = None
+        else:
+            # TODO(CoW) in theory only need to track reference if new_array is a view
+            refs = blk.refs
+
+        bp = BlockPlacement(slice(0, len(array)))
+        block = type(blk)(array, placement=bp, ndim=1, refs=refs)
+
+        new_idx = self.index[indexer]
+        return type(self)(block, new_idx)
+
+    def get_slice(self, slobj: slice, axis: AxisInt = 0) -> SingleBlockManager:
+        # Assertion disabled for performance
+        # assert isinstance(slobj, slice), type(slobj)
+        if axis >= self.ndim:
+            raise IndexError("Requested axis not found in manager")
+
+        blk = self._block
+        array = blk.values[slobj]
+        bp = BlockPlacement(slice(0, len(array)))
+        # TODO this method is only used in groupby SeriesSplitter at the moment,
+        # so passing refs is not yet covered by the tests
+        block = type(blk)(array, placement=bp, ndim=1, refs=blk.refs)
+        new_index = self.index._getitem_slice(slobj)
+        return type(self)(block, new_index)
+
+    @property
+    def index(self) -> Index:
+        return self.axes[0]
+
+    @property
+    def dtype(self) -> DtypeObj:
+        return self._block.dtype
+
+    def get_dtypes(self) -> npt.NDArray[np.object_]:
+        return np.array([self._block.dtype], dtype=object)
+
+    def external_values(self):
+        """The array that Series.values returns"""
+        return self._block.external_values()
+
+    def internal_values(self):
+        """The array that Series._values returns"""
+        return self._block.values
+
+    def array_values(self) -> ExtensionArray:
+        """The array that Series.array returns"""
+        return self._block.array_values
+
+    def get_numeric_data(self) -> Self:
+        if self._block.is_numeric:
+            return self.copy(deep=False)
+        return self.make_empty()
+
+    @property
+    def _can_hold_na(self) -> bool:
+        return self._block._can_hold_na
+
+    def setitem_inplace(self, indexer, value, warn: bool = True) -> None:
+        """
+        Set values with indexer.
+
+        For Single[Block/Array]Manager, this backs s[indexer] = value
+
+        This is an inplace version of `setitem()`, mutating the manager/values
+        in place, not returning a new Manager (and Block), and thus never changing
+        the dtype.
+        """
+        using_cow = using_copy_on_write()
+        warn_cow = warn_copy_on_write()
+        if (using_cow or warn_cow) and not self._has_no_reference(0):
+            if using_cow:
+                self.blocks = (self._block.copy(),)
+                self._cache.clear()
+            elif warn_cow and warn:
+                warnings.warn(
+                    COW_WARNING_SETITEM_MSG,
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+        super().setitem_inplace(indexer, value)
+
+    def idelete(self, indexer) -> SingleBlockManager:
+        """
+        Delete single location from SingleBlockManager.
+
+        Ensures that self.blocks doesn't become empty.
+        """
+        nb = self._block.delete(indexer)[0]
+        self.blocks = (nb,)
+        self.axes[0] = self.axes[0].delete(indexer)
+        self._cache.clear()
+        return self
+
+    def fast_xs(self, loc):
+        """
+        fast path for getting a cross-section
+        return a view of the data
+        """
+        raise NotImplementedError("Use series._values[loc] instead")
+
+    def set_values(self, values: ArrayLike) -> None:
+        """
+        Set the values of the single block in place.
+
+        Use at your own risk! This does not check if the passed values are
+        valid for the current Block/SingleBlockManager (length, dtype, etc),
+        and this does not properly keep track of references.
+        """
+        # NOTE(CoW) Currently this is only used for FrameColumnApply.series_generator
+        # which handles CoW by setting the refs manually if necessary
+        self.blocks[0].values = values
+        self.blocks[0]._mgr_locs = BlockPlacement(slice(len(values)))
+
+    def _equal_values(self, other: Self) -> bool:
+        """
+        Used in .equals defined in base class. Only check the column values
+        assuming shape and indexes have already been checked.
+        """
+        # For SingleBlockManager (i.e.Series)
+        if other.ndim != 1:
+            return False
+        left = self.blocks[0].values
+        right = other.blocks[0].values
+        return array_equals(left, right)
+
+
+# --------------------------------------------------------------------
+# Constructor Helpers
+
+
+def create_block_manager_from_blocks(
+    blocks: list[Block],
+    axes: list[Index],
+    consolidate: bool = True,
+    verify_integrity: bool = True,
+) -> BlockManager:
+    # If verify_integrity=False, then caller is responsible for checking
+    #  all(x.shape[-1] == len(axes[1]) for x in blocks)
+    #  sum(x.shape[0] for x in blocks) == len(axes[0])
+    #  set(x for blk in blocks for x in blk.mgr_locs) == set(range(len(axes[0])))
+    #  all(blk.ndim == 2 for blk in blocks)
+    # This allows us to safely pass verify_integrity=False
+
+    try:
+        mgr = BlockManager(blocks, axes, verify_integrity=verify_integrity)
+
+    except ValueError as err:
+        arrays = [blk.values for blk in blocks]
+        tot_items = sum(arr.shape[0] for arr in arrays)
+        raise_construction_error(tot_items, arrays[0].shape[1:], axes, err)
+
+    if consolidate:
+        mgr._consolidate_inplace()
+    return mgr
+
+
+def create_block_manager_from_column_arrays(
+    arrays: list[ArrayLike],
+    axes: list[Index],
+    consolidate: bool,
+    refs: list,
+) -> BlockManager:
+    # Assertions disabled for performance (caller is responsible for verifying)
+    # assert isinstance(axes, list)
+    # assert all(isinstance(x, Index) for x in axes)
+    # assert all(isinstance(x, (np.ndarray, ExtensionArray)) for x in arrays)
+    # assert all(type(x) is not NumpyExtensionArray for x in arrays)
+    # assert all(x.ndim == 1 for x in arrays)
+    # assert all(len(x) == len(axes[1]) for x in arrays)
+    # assert len(arrays) == len(axes[0])
+    # These last three are sufficient to allow us to safely pass
+    #  verify_integrity=False below.
+
+    try:
+        blocks = _form_blocks(arrays, consolidate, refs)
+        mgr = BlockManager(blocks, axes, verify_integrity=False)
+    except ValueError as e:
+        raise_construction_error(len(arrays), arrays[0].shape, axes, e)
+    if consolidate:
+        mgr._consolidate_inplace()
+    return mgr
+
+
+def raise_construction_error(
+    tot_items: int,
+    block_shape: Shape,
+    axes: list[Index],
+    e: ValueError | None = None,
+):
+    """raise a helpful message about our construction"""
+    passed = tuple(map(int, [tot_items] + list(block_shape)))
+    # Correcting the user facing error message during dataframe construction
+    if len(passed) <= 2:
+        passed = passed[::-1]
+
+    implied = tuple(len(ax) for ax in axes)
+    # Correcting the user facing error message during dataframe construction
+    if len(implied) <= 2:
+        implied = implied[::-1]
+
+    # We return the exception object instead of raising it so that we
+    #  can raise it in the caller; mypy plays better with that
+    if passed == implied and e is not None:
+        raise e
+    if block_shape[0] == 0:
+        raise ValueError("Empty data passed with indices specified.")
+    raise ValueError(f"Shape of passed values is {passed}, indices imply {implied}")
+
+
+# -----------------------------------------------------------------------
+
+
+def _grouping_func(tup: tuple[int, ArrayLike]) -> tuple[int, DtypeObj]:
+    dtype = tup[1].dtype
+
+    if is_1d_only_ea_dtype(dtype):
+        # We know these won't be consolidated, so don't need to group these.
+        # This avoids expensive comparisons of CategoricalDtype objects
+        sep = id(dtype)
+    else:
+        sep = 0
+
+    return sep, dtype
+
+
+def _form_blocks(arrays: list[ArrayLike], consolidate: bool, refs: list) -> list[Block]:
+    tuples = list(enumerate(arrays))
+
+    if not consolidate:
+        return _tuples_to_blocks_no_consolidate(tuples, refs)
+
+    # when consolidating, we can ignore refs (either stacking always copies,
+    # or the EA is already copied in the calling dict_to_mgr)
+
+    # group by dtype
+    grouper = itertools.groupby(tuples, _grouping_func)
+
+    nbs: list[Block] = []
+    for (_, dtype), tup_block in grouper:
+        block_type = get_block_type(dtype)
+
+        if isinstance(dtype, np.dtype):
+            is_dtlike = dtype.kind in "mM"
+
+            if issubclass(dtype.type, (str, bytes)):
+                dtype = np.dtype(object)
+
+            values, placement = _stack_arrays(list(tup_block), dtype)
+            if is_dtlike:
+                values = ensure_wrapped_if_datetimelike(values)
+            blk = block_type(values, placement=BlockPlacement(placement), ndim=2)
+            nbs.append(blk)
+
+        elif is_1d_only_ea_dtype(dtype):
+            dtype_blocks = [
+                block_type(x[1], placement=BlockPlacement(x[0]), ndim=2)
+                for x in tup_block
+            ]
+            nbs.extend(dtype_blocks)
+
+        else:
+            dtype_blocks = [
+                block_type(
+                    ensure_block_shape(x[1], 2), placement=BlockPlacement(x[0]), ndim=2
+                )
+                for x in tup_block
+            ]
+            nbs.extend(dtype_blocks)
+    return nbs
+
+
+def _tuples_to_blocks_no_consolidate(tuples, refs) -> list[Block]:
+    # tuples produced within _form_blocks are of the form (placement, array)
+    return [
+        new_block_2d(
+            ensure_block_shape(arr, ndim=2), placement=BlockPlacement(i), refs=ref
+        )
+        for ((i, arr), ref) in zip(tuples, refs)
+    ]
+
+
+def _stack_arrays(tuples, dtype: np.dtype):
+    placement, arrays = zip(*tuples)
+
+    first = arrays[0]
+    shape = (len(arrays),) + first.shape
+
+    stacked = np.empty(shape, dtype=dtype)
+    for i, arr in enumerate(arrays):
+        stacked[i] = arr
+
+    return stacked, placement
+
+
+def _consolidate(blocks: tuple[Block, ...]) -> tuple[Block, ...]:
+    """
+    Merge blocks having same dtype, exclude non-consolidating blocks
+    """
+    # sort by _can_consolidate, dtype
+    gkey = lambda x: x._consolidate_key
+    grouper = itertools.groupby(sorted(blocks, key=gkey), gkey)
+
+    new_blocks: list[Block] = []
+    for (_can_consolidate, dtype), group_blocks in grouper:
+        merged_blocks, _ = _merge_blocks(
+            list(group_blocks), dtype=dtype, can_consolidate=_can_consolidate
+        )
+        new_blocks = extend_blocks(merged_blocks, new_blocks)
+    return tuple(new_blocks)
+
+
+def _merge_blocks(
+    blocks: list[Block], dtype: DtypeObj, can_consolidate: bool
+) -> tuple[list[Block], bool]:
+    if len(blocks) == 1:
+        return blocks, False
+
+    if can_consolidate:
+        # TODO: optimization potential in case all mgrs contain slices and
+        # combination of those slices is a slice, too.
+        new_mgr_locs = np.concatenate([b.mgr_locs.as_array for b in blocks])
+
+        new_values: ArrayLike
+
+        if isinstance(blocks[0].dtype, np.dtype):
+            # error: List comprehension has incompatible type List[Union[ndarray,
+            # ExtensionArray]]; expected List[Union[complex, generic,
+            # Sequence[Union[int, float, complex, str, bytes, generic]],
+            # Sequence[Sequence[Any]], SupportsArray]]
+            new_values = np.vstack([b.values for b in blocks])  # type: ignore[misc]
+        else:
+            bvals = [blk.values for blk in blocks]
+            bvals2 = cast(Sequence[NDArrayBackedExtensionArray], bvals)
+            new_values = bvals2[0]._concat_same_type(bvals2, axis=0)
+
+        argsort = np.argsort(new_mgr_locs)
+        new_values = new_values[argsort]
+        new_mgr_locs = new_mgr_locs[argsort]
+
+        bp = BlockPlacement(new_mgr_locs)
+        return [new_block_2d(new_values, placement=bp)], True
+
+    # can't consolidate --> no merge
+    return blocks, False
+
+
+def _fast_count_smallints(arr: npt.NDArray[np.intp]):
+    """Faster version of set(arr) for sequences of small numbers."""
+    counts = np.bincount(arr)
+    nz = counts.nonzero()[0]
+    # Note: list(zip(...) outperforms list(np.c_[nz, counts[nz]]) here,
+    #  in one benchmark by a factor of 11
+    return zip(nz, counts[nz])
+
+
+def _preprocess_slice_or_indexer(
+    slice_or_indexer: slice | np.ndarray, length: int, allow_fill: bool
+):
+    if isinstance(slice_or_indexer, slice):
+        return (
+            "slice",
+            slice_or_indexer,
+            libinternals.slice_len(slice_or_indexer, length),
+        )
+    else:
+        if (
+            not isinstance(slice_or_indexer, np.ndarray)
+            or slice_or_indexer.dtype.kind != "i"
+        ):
+            dtype = getattr(slice_or_indexer, "dtype", None)
+            raise TypeError(type(slice_or_indexer), dtype)
+
+        indexer = ensure_platform_int(slice_or_indexer)
+        if not allow_fill:
+            indexer = maybe_convert_indices(indexer, length)
+        return "fancy", indexer, len(indexer)
+
+
+def make_na_array(dtype: DtypeObj, shape: Shape, fill_value) -> ArrayLike:
+    if isinstance(dtype, DatetimeTZDtype):
+        # NB: exclude e.g. pyarrow[dt64tz] dtypes
+        ts = Timestamp(fill_value).as_unit(dtype.unit)
+        i8values = np.full(shape, ts._value)
+        dt64values = i8values.view(f"M8[{dtype.unit}]")
+        return DatetimeArray._simple_new(dt64values, dtype=dtype)
+
+    elif is_1d_only_ea_dtype(dtype):
+        dtype = cast(ExtensionDtype, dtype)
+        cls = dtype.construct_array_type()
+
+        missing_arr = cls._from_sequence([], dtype=dtype)
+        ncols, nrows = shape
+        assert ncols == 1, ncols
+        empty_arr = -1 * np.ones((nrows,), dtype=np.intp)
+        return missing_arr.take(empty_arr, allow_fill=True, fill_value=fill_value)
+    elif isinstance(dtype, ExtensionDtype):
+        # TODO: no tests get here, a handful would if we disabled
+        #  the dt64tz special-case above (which is faster)
+        cls = dtype.construct_array_type()
+        missing_arr = cls._empty(shape=shape, dtype=dtype)
+        missing_arr[:] = fill_value
+        return missing_arr
+    else:
+        # NB: we should never get here with dtype integer or bool;
+        #  if we did, the missing_arr.fill would cast to gibberish
+        missing_arr = np.empty(shape, dtype=dtype)
+        missing_arr.fill(fill_value)
+
+        if dtype.kind in "mM":
+            missing_arr = ensure_wrapped_if_datetimelike(missing_arr)
+        return missing_arr
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/internals/ops.py b/.venv/lib/python3.13/site-packages/pandas/core/internals/ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..cf9466c0bdf0bf4df623e2d819faf3ea7b36c878
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/internals/ops.py
@@ -0,0 +1,154 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    NamedTuple,
+)
+
+from pandas.core.dtypes.common import is_1d_only_ea_dtype
+
+if TYPE_CHECKING:
+    from collections.abc import Iterator
+
+    from pandas._libs.internals import BlockPlacement
+    from pandas._typing import ArrayLike
+
+    from pandas.core.internals.blocks import Block
+    from pandas.core.internals.managers import BlockManager
+
+
+class BlockPairInfo(NamedTuple):
+    lvals: ArrayLike
+    rvals: ArrayLike
+    locs: BlockPlacement
+    left_ea: bool
+    right_ea: bool
+    rblk: Block
+
+
+def _iter_block_pairs(
+    left: BlockManager, right: BlockManager
+) -> Iterator[BlockPairInfo]:
+    # At this point we have already checked the parent DataFrames for
+    #  assert rframe._indexed_same(lframe)
+
+    for blk in left.blocks:
+        locs = blk.mgr_locs
+        blk_vals = blk.values
+
+        left_ea = blk_vals.ndim == 1
+
+        rblks = right._slice_take_blocks_ax0(locs.indexer, only_slice=True)
+
+        # Assertions are disabled for performance, but should hold:
+        # if left_ea:
+        #    assert len(locs) == 1, locs
+        #    assert len(rblks) == 1, rblks
+        #    assert rblks[0].shape[0] == 1, rblks[0].shape
+
+        for rblk in rblks:
+            right_ea = rblk.values.ndim == 1
+
+            lvals, rvals = _get_same_shape_values(blk, rblk, left_ea, right_ea)
+            info = BlockPairInfo(lvals, rvals, locs, left_ea, right_ea, rblk)
+            yield info
+
+
+def operate_blockwise(
+    left: BlockManager, right: BlockManager, array_op
+) -> BlockManager:
+    # At this point we have already checked the parent DataFrames for
+    #  assert rframe._indexed_same(lframe)
+
+    res_blks: list[Block] = []
+    for lvals, rvals, locs, left_ea, right_ea, rblk in _iter_block_pairs(left, right):
+        res_values = array_op(lvals, rvals)
+        if (
+            left_ea
+            and not right_ea
+            and hasattr(res_values, "reshape")
+            and not is_1d_only_ea_dtype(res_values.dtype)
+        ):
+            res_values = res_values.reshape(1, -1)
+        nbs = rblk._split_op_result(res_values)
+
+        # Assertions are disabled for performance, but should hold:
+        # if right_ea or left_ea:
+        #    assert len(nbs) == 1
+        # else:
+        #    assert res_values.shape == lvals.shape, (res_values.shape, lvals.shape)
+
+        _reset_block_mgr_locs(nbs, locs)
+
+        res_blks.extend(nbs)
+
+    # Assertions are disabled for performance, but should hold:
+    #  slocs = {y for nb in res_blks for y in nb.mgr_locs.as_array}
+    #  nlocs = sum(len(nb.mgr_locs.as_array) for nb in res_blks)
+    #  assert nlocs == len(left.items), (nlocs, len(left.items))
+    #  assert len(slocs) == nlocs, (len(slocs), nlocs)
+    #  assert slocs == set(range(nlocs)), slocs
+
+    new_mgr = type(right)(tuple(res_blks), axes=right.axes, verify_integrity=False)
+    return new_mgr
+
+
+def _reset_block_mgr_locs(nbs: list[Block], locs) -> None:
+    """
+    Reset mgr_locs to correspond to our original DataFrame.
+    """
+    for nb in nbs:
+        nblocs = locs[nb.mgr_locs.indexer]
+        nb.mgr_locs = nblocs
+        # Assertions are disabled for performance, but should hold:
+        #  assert len(nblocs) == nb.shape[0], (len(nblocs), nb.shape)
+        #  assert all(x in locs.as_array for x in nb.mgr_locs.as_array)
+
+
+def _get_same_shape_values(
+    lblk: Block, rblk: Block, left_ea: bool, right_ea: bool
+) -> tuple[ArrayLike, ArrayLike]:
+    """
+    Slice lblk.values to align with rblk.  Squeeze if we have EAs.
+    """
+    lvals = lblk.values
+    rvals = rblk.values
+
+    # Require that the indexing into lvals be slice-like
+    assert rblk.mgr_locs.is_slice_like, rblk.mgr_locs
+
+    # TODO(EA2D): with 2D EAs only this first clause would be needed
+    if not (left_ea or right_ea):
+        # error: No overload variant of "__getitem__" of "ExtensionArray" matches
+        # argument type "Tuple[Union[ndarray, slice], slice]"
+        lvals = lvals[rblk.mgr_locs.indexer, :]  # type: ignore[call-overload]
+        assert lvals.shape == rvals.shape, (lvals.shape, rvals.shape)
+    elif left_ea and right_ea:
+        assert lvals.shape == rvals.shape, (lvals.shape, rvals.shape)
+    elif right_ea:
+        # lvals are 2D, rvals are 1D
+
+        # error: No overload variant of "__getitem__" of "ExtensionArray" matches
+        # argument type "Tuple[Union[ndarray, slice], slice]"
+        lvals = lvals[rblk.mgr_locs.indexer, :]  # type: ignore[call-overload]
+        assert lvals.shape[0] == 1, lvals.shape
+        lvals = lvals[0, :]
+    else:
+        # lvals are 1D, rvals are 2D
+        assert rvals.shape[0] == 1, rvals.shape
+        # error: No overload variant of "__getitem__" of "ExtensionArray" matches
+        # argument type "Tuple[int, slice]"
+        rvals = rvals[0, :]  # type: ignore[call-overload]
+
+    return lvals, rvals
+
+
+def blockwise_all(left: BlockManager, right: BlockManager, op) -> bool:
+    """
+    Blockwise `all` reduction.
+    """
+    for info in _iter_block_pairs(left, right):
+        res = op(info.lvals, info.rvals)
+        if not res:
+            return False
+    return True
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/methods/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/methods/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/methods/describe.py b/.venv/lib/python3.13/site-packages/pandas/core/methods/describe.py
new file mode 100644
index 0000000000000000000000000000000000000000..c620bb9d17976a9deeb682ff323476c484f283ff
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/methods/describe.py
@@ -0,0 +1,416 @@
+"""
+Module responsible for execution of NDFrame.describe() method.
+
+Method NDFrame.describe() delegates actual execution to function describe_ndframe().
+"""
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import Timestamp
+from pandas._typing import (
+    DtypeObj,
+    NDFrameT,
+    npt,
+)
+from pandas.util._validators import validate_percentile
+
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_numeric_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+)
+
+from pandas.core.arrays.floating import Float64Dtype
+from pandas.core.reshape.concat import concat
+
+from pandas.io.formats.format import format_percentiles
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+def describe_ndframe(
+    *,
+    obj: NDFrameT,
+    include: str | Sequence[str] | None,
+    exclude: str | Sequence[str] | None,
+    percentiles: Sequence[float] | np.ndarray | None,
+) -> NDFrameT:
+    """Describe series or dataframe.
+
+    Called from pandas.core.generic.NDFrame.describe()
+
+    Parameters
+    ----------
+    obj: DataFrame or Series
+        Either dataframe or series to be described.
+    include : 'all', list-like of dtypes or None (default), optional
+        A white list of data types to include in the result. Ignored for ``Series``.
+    exclude : list-like of dtypes or None (default), optional,
+        A black list of data types to omit from the result. Ignored for ``Series``.
+    percentiles : list-like of numbers, optional
+        The percentiles to include in the output. All should fall between 0 and 1.
+        The default is ``[.25, .5, .75]``, which returns the 25th, 50th, and
+        75th percentiles.
+
+    Returns
+    -------
+    Dataframe or series description.
+    """
+    percentiles = _refine_percentiles(percentiles)
+
+    describer: NDFrameDescriberAbstract
+    if obj.ndim == 1:
+        describer = SeriesDescriber(
+            obj=cast("Series", obj),
+        )
+    else:
+        describer = DataFrameDescriber(
+            obj=cast("DataFrame", obj),
+            include=include,
+            exclude=exclude,
+        )
+
+    result = describer.describe(percentiles=percentiles)
+    return cast(NDFrameT, result)
+
+
+class NDFrameDescriberAbstract(ABC):
+    """Abstract class for describing dataframe or series.
+
+    Parameters
+    ----------
+    obj : Series or DataFrame
+        Object to be described.
+    """
+
+    def __init__(self, obj: DataFrame | Series) -> None:
+        self.obj = obj
+
+    @abstractmethod
+    def describe(self, percentiles: Sequence[float] | np.ndarray) -> DataFrame | Series:
+        """Do describe either series or dataframe.
+
+        Parameters
+        ----------
+        percentiles : list-like of numbers
+            The percentiles to include in the output.
+        """
+
+
+class SeriesDescriber(NDFrameDescriberAbstract):
+    """Class responsible for creating series description."""
+
+    obj: Series
+
+    def describe(self, percentiles: Sequence[float] | np.ndarray) -> Series:
+        describe_func = select_describe_func(
+            self.obj,
+        )
+        return describe_func(self.obj, percentiles)
+
+
+class DataFrameDescriber(NDFrameDescriberAbstract):
+    """Class responsible for creating dataobj description.
+
+    Parameters
+    ----------
+    obj : DataFrame
+        DataFrame to be described.
+    include : 'all', list-like of dtypes or None
+        A white list of data types to include in the result.
+    exclude : list-like of dtypes or None
+        A black list of data types to omit from the result.
+    """
+
+    obj: DataFrame
+
+    def __init__(
+        self,
+        obj: DataFrame,
+        *,
+        include: str | Sequence[str] | None,
+        exclude: str | Sequence[str] | None,
+    ) -> None:
+        self.include = include
+        self.exclude = exclude
+
+        if obj.ndim == 2 and obj.columns.size == 0:
+            raise ValueError("Cannot describe a DataFrame without columns")
+
+        super().__init__(obj)
+
+    def describe(self, percentiles: Sequence[float] | np.ndarray) -> DataFrame:
+        data = self._select_data()
+
+        ldesc: list[Series] = []
+        for _, series in data.items():
+            describe_func = select_describe_func(series)
+            ldesc.append(describe_func(series, percentiles))
+
+        col_names = reorder_columns(ldesc)
+        d = concat(
+            [x.reindex(col_names, copy=False) for x in ldesc],
+            axis=1,
+            sort=False,
+        )
+        d.columns = data.columns.copy()
+        return d
+
+    def _select_data(self) -> DataFrame:
+        """Select columns to be described."""
+        if (self.include is None) and (self.exclude is None):
+            # when some numerics are found, keep only numerics
+            default_include: list[npt.DTypeLike] = [np.number, "datetime"]
+            data = self.obj.select_dtypes(include=default_include)
+            if len(data.columns) == 0:
+                data = self.obj
+        elif self.include == "all":
+            if self.exclude is not None:
+                msg = "exclude must be None when include is 'all'"
+                raise ValueError(msg)
+            data = self.obj
+        else:
+            data = self.obj.select_dtypes(
+                include=self.include,
+                exclude=self.exclude,
+            )
+        return data
+
+
+def reorder_columns(ldesc: Sequence[Series]) -> list[Hashable]:
+    """Set a convenient order for rows for display."""
+    names: list[Hashable] = []
+    seen_names: set[Hashable] = set()
+    ldesc_indexes = sorted((x.index for x in ldesc), key=len)
+    for idxnames in ldesc_indexes:
+        for name in idxnames:
+            if name not in seen_names:
+                seen_names.add(name)
+                names.append(name)
+    return names
+
+
+def describe_numeric_1d(series: Series, percentiles: Sequence[float]) -> Series:
+    """Describe series containing numerical data.
+
+    Parameters
+    ----------
+    series : Series
+        Series to be described.
+    percentiles : list-like of numbers
+        The percentiles to include in the output.
+    """
+    from pandas import Series
+
+    formatted_percentiles = format_percentiles(percentiles)
+
+    stat_index = ["count", "mean", "std", "min"] + formatted_percentiles + ["max"]
+    d = (
+        [series.count(), series.mean(), series.std(), series.min()]
+        + series.quantile(percentiles).tolist()
+        + [series.max()]
+    )
+    # GH#48340 - always return float on non-complex numeric data
+    dtype: DtypeObj | None
+    if isinstance(series.dtype, ExtensionDtype):
+        if isinstance(series.dtype, ArrowDtype):
+            if series.dtype.kind == "m":
+                # GH53001: describe timedeltas with object dtype
+                dtype = None
+            else:
+                import pyarrow as pa
+
+                dtype = ArrowDtype(pa.float64())
+        else:
+            dtype = Float64Dtype()
+    elif series.dtype.kind in "iufb":
+        # i.e. numeric but exclude complex dtype
+        dtype = np.dtype("float")
+    else:
+        dtype = None
+    return Series(d, index=stat_index, name=series.name, dtype=dtype)
+
+
+def describe_categorical_1d(
+    data: Series,
+    percentiles_ignored: Sequence[float],
+) -> Series:
+    """Describe series containing categorical data.
+
+    Parameters
+    ----------
+    data : Series
+        Series to be described.
+    percentiles_ignored : list-like of numbers
+        Ignored, but in place to unify interface.
+    """
+    names = ["count", "unique", "top", "freq"]
+    objcounts = data.value_counts()
+    count_unique = len(objcounts[objcounts != 0])
+    if count_unique > 0:
+        top, freq = objcounts.index[0], objcounts.iloc[0]
+        dtype = None
+    else:
+        # If the DataFrame is empty, set 'top' and 'freq' to None
+        # to maintain output shape consistency
+        top, freq = np.nan, np.nan
+        dtype = "object"
+
+    result = [data.count(), count_unique, top, freq]
+
+    from pandas import Series
+
+    return Series(result, index=names, name=data.name, dtype=dtype)
+
+
+def describe_timestamp_as_categorical_1d(
+    data: Series,
+    percentiles_ignored: Sequence[float],
+) -> Series:
+    """Describe series containing timestamp data treated as categorical.
+
+    Parameters
+    ----------
+    data : Series
+        Series to be described.
+    percentiles_ignored : list-like of numbers
+        Ignored, but in place to unify interface.
+    """
+    names = ["count", "unique"]
+    objcounts = data.value_counts()
+    count_unique = len(objcounts[objcounts != 0])
+    result: list[float | Timestamp] = [data.count(), count_unique]
+    dtype = None
+    if count_unique > 0:
+        top, freq = objcounts.index[0], objcounts.iloc[0]
+        tz = data.dt.tz
+        asint = data.dropna().values.view("i8")
+        top = Timestamp(top)
+        if top.tzinfo is not None and tz is not None:
+            # Don't tz_localize(None) if key is already tz-aware
+            top = top.tz_convert(tz)
+        else:
+            top = top.tz_localize(tz)
+        names += ["top", "freq", "first", "last"]
+        result += [
+            top,
+            freq,
+            Timestamp(asint.min(), tz=tz),
+            Timestamp(asint.max(), tz=tz),
+        ]
+
+    # If the DataFrame is empty, set 'top' and 'freq' to None
+    # to maintain output shape consistency
+    else:
+        names += ["top", "freq"]
+        result += [np.nan, np.nan]
+        dtype = "object"
+
+    from pandas import Series
+
+    return Series(result, index=names, name=data.name, dtype=dtype)
+
+
+def describe_timestamp_1d(data: Series, percentiles: Sequence[float]) -> Series:
+    """Describe series containing datetime64 dtype.
+
+    Parameters
+    ----------
+    data : Series
+        Series to be described.
+    percentiles : list-like of numbers
+        The percentiles to include in the output.
+    """
+    # GH-30164
+    from pandas import Series
+
+    formatted_percentiles = format_percentiles(percentiles)
+
+    stat_index = ["count", "mean", "min"] + formatted_percentiles + ["max"]
+    d = (
+        [data.count(), data.mean(), data.min()]
+        + data.quantile(percentiles).tolist()
+        + [data.max()]
+    )
+    return Series(d, index=stat_index, name=data.name)
+
+
+def select_describe_func(
+    data: Series,
+) -> Callable:
+    """Select proper function for describing series based on data type.
+
+    Parameters
+    ----------
+    data : Series
+        Series to be described.
+    """
+    if is_bool_dtype(data.dtype):
+        return describe_categorical_1d
+    elif is_numeric_dtype(data):
+        return describe_numeric_1d
+    elif data.dtype.kind == "M" or isinstance(data.dtype, DatetimeTZDtype):
+        return describe_timestamp_1d
+    elif data.dtype.kind == "m":
+        return describe_numeric_1d
+    else:
+        return describe_categorical_1d
+
+
+def _refine_percentiles(
+    percentiles: Sequence[float] | np.ndarray | None,
+) -> npt.NDArray[np.float64]:
+    """
+    Ensure that percentiles are unique and sorted.
+
+    Parameters
+    ----------
+    percentiles : list-like of numbers, optional
+        The percentiles to include in the output.
+    """
+    if percentiles is None:
+        return np.array([0.25, 0.5, 0.75])
+
+    # explicit conversion of `percentiles` to list
+    percentiles = list(percentiles)
+
+    # get them all to be in [0, 1]
+    validate_percentile(percentiles)
+
+    # median should always be included
+    if 0.5 not in percentiles:
+        percentiles.append(0.5)
+
+    percentiles = np.asarray(percentiles)
+
+    # sort and check for duplicates
+    unique_pcts = np.unique(percentiles)
+    assert percentiles is not None
+    if len(unique_pcts) < len(percentiles):
+        raise ValueError("percentiles cannot contain duplicates")
+
+    return unique_pcts
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/methods/selectn.py b/.venv/lib/python3.13/site-packages/pandas/core/methods/selectn.py
new file mode 100644
index 0000000000000000000000000000000000000000..a2f8ca94134b897bd3f7824a6cb45ca13516e5ff
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/methods/selectn.py
@@ -0,0 +1,269 @@
+"""
+Implementation of nlargest and nsmallest.
+"""
+
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Sequence,
+)
+from typing import (
+    TYPE_CHECKING,
+    cast,
+    final,
+)
+
+import numpy as np
+
+from pandas._libs import algos as libalgos
+
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_complex_dtype,
+    is_integer_dtype,
+    is_list_like,
+    is_numeric_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import BaseMaskedDtype
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DtypeObj,
+        IndexLabel,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+class SelectN:
+    def __init__(self, obj, n: int, keep: str) -> None:
+        self.obj = obj
+        self.n = n
+        self.keep = keep
+
+        if self.keep not in ("first", "last", "all"):
+            raise ValueError('keep must be either "first", "last" or "all"')
+
+    def compute(self, method: str) -> DataFrame | Series:
+        raise NotImplementedError
+
+    @final
+    def nlargest(self):
+        return self.compute("nlargest")
+
+    @final
+    def nsmallest(self):
+        return self.compute("nsmallest")
+
+    @final
+    @staticmethod
+    def is_valid_dtype_n_method(dtype: DtypeObj) -> bool:
+        """
+        Helper function to determine if dtype is valid for
+        nsmallest/nlargest methods
+        """
+        if is_numeric_dtype(dtype):
+            return not is_complex_dtype(dtype)
+        return needs_i8_conversion(dtype)
+
+
+class SelectNSeries(SelectN):
+    """
+    Implement n largest/smallest for Series
+
+    Parameters
+    ----------
+    obj : Series
+    n : int
+    keep : {'first', 'last'}, default 'first'
+
+    Returns
+    -------
+    nordered : Series
+    """
+
+    def compute(self, method: str) -> Series:
+        from pandas.core.reshape.concat import concat
+
+        n = self.n
+        dtype = self.obj.dtype
+        if not self.is_valid_dtype_n_method(dtype):
+            raise TypeError(f"Cannot use method '{method}' with dtype {dtype}")
+
+        if n <= 0:
+            return self.obj[[]]
+
+        dropped = self.obj.dropna()
+        nan_index = self.obj.drop(dropped.index)
+
+        # slow method
+        if n >= len(self.obj):
+            ascending = method == "nsmallest"
+            return self.obj.sort_values(ascending=ascending).head(n)
+
+        # fast method
+        new_dtype = dropped.dtype
+
+        # Similar to algorithms._ensure_data
+        arr = dropped._values
+        if needs_i8_conversion(arr.dtype):
+            arr = arr.view("i8")
+        elif isinstance(arr.dtype, BaseMaskedDtype):
+            arr = arr._data
+        else:
+            arr = np.asarray(arr)
+        if arr.dtype.kind == "b":
+            arr = arr.view(np.uint8)
+
+        if method == "nlargest":
+            arr = -arr
+            if is_integer_dtype(new_dtype):
+                # GH 21426: ensure reverse ordering at boundaries
+                arr -= 1
+
+            elif is_bool_dtype(new_dtype):
+                # GH 26154: ensure False is smaller than True
+                arr = 1 - (-arr)
+
+        if self.keep == "last":
+            arr = arr[::-1]
+
+        nbase = n
+        narr = len(arr)
+        n = min(n, narr)
+
+        # arr passed into kth_smallest must be contiguous. We copy
+        # here because kth_smallest will modify its input
+        # avoid OOB access with kth_smallest_c when n <= 0
+        if len(arr) > 0:
+            kth_val = libalgos.kth_smallest(arr.copy(order="C"), n - 1)
+        else:
+            kth_val = np.nan
+        (ns,) = np.nonzero(arr <= kth_val)
+        inds = ns[arr[ns].argsort(kind="mergesort")]
+
+        if self.keep != "all":
+            inds = inds[:n]
+            findex = nbase
+        else:
+            if len(inds) < nbase <= len(nan_index) + len(inds):
+                findex = len(nan_index) + len(inds)
+            else:
+                findex = len(inds)
+
+        if self.keep == "last":
+            # reverse indices
+            inds = narr - 1 - inds
+
+        return concat([dropped.iloc[inds], nan_index]).iloc[:findex]
+
+
+class SelectNFrame(SelectN):
+    """
+    Implement n largest/smallest for DataFrame
+
+    Parameters
+    ----------
+    obj : DataFrame
+    n : int
+    keep : {'first', 'last'}, default 'first'
+    columns : list or str
+
+    Returns
+    -------
+    nordered : DataFrame
+    """
+
+    def __init__(self, obj: DataFrame, n: int, keep: str, columns: IndexLabel) -> None:
+        super().__init__(obj, n, keep)
+        if not is_list_like(columns) or isinstance(columns, tuple):
+            columns = [columns]
+
+        columns = cast(Sequence[Hashable], columns)
+        columns = list(columns)
+        self.columns = columns
+
+    def compute(self, method: str) -> DataFrame:
+        from pandas.core.api import Index
+
+        n = self.n
+        frame = self.obj
+        columns = self.columns
+
+        for column in columns:
+            dtype = frame[column].dtype
+            if not self.is_valid_dtype_n_method(dtype):
+                raise TypeError(
+                    f"Column {repr(column)} has dtype {dtype}, "
+                    f"cannot use method {repr(method)} with this dtype"
+                )
+
+        def get_indexer(current_indexer, other_indexer):
+            """
+            Helper function to concat `current_indexer` and `other_indexer`
+            depending on `method`
+            """
+            if method == "nsmallest":
+                return current_indexer.append(other_indexer)
+            else:
+                return other_indexer.append(current_indexer)
+
+        # Below we save and reset the index in case index contains duplicates
+        original_index = frame.index
+        cur_frame = frame = frame.reset_index(drop=True)
+        cur_n = n
+        indexer = Index([], dtype=np.int64)
+
+        for i, column in enumerate(columns):
+            # For each column we apply method to cur_frame[column].
+            # If it's the last column or if we have the number of
+            # results desired we are done.
+            # Otherwise there are duplicates of the largest/smallest
+            # value and we need to look at the rest of the columns
+            # to determine which of the rows with the largest/smallest
+            # value in the column to keep.
+            series = cur_frame[column]
+            is_last_column = len(columns) - 1 == i
+            values = getattr(series, method)(
+                cur_n, keep=self.keep if is_last_column else "all"
+            )
+
+            if is_last_column or len(values) <= cur_n:
+                indexer = get_indexer(indexer, values.index)
+                break
+
+            # Now find all values which are equal to
+            # the (nsmallest: largest)/(nlargest: smallest)
+            # from our series.
+            border_value = values == values[values.index[-1]]
+
+            # Some of these values are among the top-n
+            # some aren't.
+            unsafe_values = values[border_value]
+
+            # These values are definitely among the top-n
+            safe_values = values[~border_value]
+            indexer = get_indexer(indexer, safe_values.index)
+
+            # Go on and separate the unsafe_values on the remaining
+            # columns.
+            cur_frame = cur_frame.loc[unsafe_values.index]
+            cur_n = n - len(indexer)
+
+        frame = frame.take(indexer)
+
+        # Restore the index on frame
+        frame.index = original_index.take(indexer)
+
+        # If there is only one column, the frame is already sorted.
+        if len(columns) == 1:
+            return frame
+
+        ascending = method == "nsmallest"
+
+        return frame.sort_values(columns, ascending=ascending, kind="mergesort")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/methods/to_dict.py b/.venv/lib/python3.13/site-packages/pandas/core/methods/to_dict.py
new file mode 100644
index 0000000000000000000000000000000000000000..accbd92a91ed66fe4dfd1e3939fe8c498184285d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/methods/to_dict.py
@@ -0,0 +1,272 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import maybe_box_native
+from pandas.core.dtypes.dtypes import (
+    BaseMaskedDtype,
+    ExtensionDtype,
+)
+
+from pandas.core import common as com
+
+if TYPE_CHECKING:
+    from pandas._typing import MutableMappingT
+
+    from pandas import DataFrame
+
+
+@overload
+def to_dict(
+    df: DataFrame,
+    orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
+    *,
+    into: type[MutableMappingT] | MutableMappingT,
+    index: bool = ...,
+) -> MutableMappingT:
+    ...
+
+
+@overload
+def to_dict(
+    df: DataFrame,
+    orient: Literal["records"],
+    *,
+    into: type[MutableMappingT] | MutableMappingT,
+    index: bool = ...,
+) -> list[MutableMappingT]:
+    ...
+
+
+@overload
+def to_dict(
+    df: DataFrame,
+    orient: Literal["dict", "list", "series", "split", "tight", "index"] = ...,
+    *,
+    into: type[dict] = ...,
+    index: bool = ...,
+) -> dict:
+    ...
+
+
+@overload
+def to_dict(
+    df: DataFrame,
+    orient: Literal["records"],
+    *,
+    into: type[dict] = ...,
+    index: bool = ...,
+) -> list[dict]:
+    ...
+
+
+# error: Incompatible default for argument "into" (default has type "type[dict
+# [Any, Any]]", argument has type "type[MutableMappingT] | MutableMappingT")
+def to_dict(
+    df: DataFrame,
+    orient: Literal[
+        "dict", "list", "series", "split", "tight", "records", "index"
+    ] = "dict",
+    *,
+    into: type[MutableMappingT] | MutableMappingT = dict,  # type: ignore[assignment]
+    index: bool = True,
+) -> MutableMappingT | list[MutableMappingT]:
+    """
+    Convert the DataFrame to a dictionary.
+
+    The type of the key-value pairs can be customized with the parameters
+    (see below).
+
+    Parameters
+    ----------
+    orient : str {'dict', 'list', 'series', 'split', 'tight', 'records', 'index'}
+        Determines the type of the values of the dictionary.
+
+        - 'dict' (default) : dict like {column -> {index -> value}}
+        - 'list' : dict like {column -> [values]}
+        - 'series' : dict like {column -> Series(values)}
+        - 'split' : dict like
+          {'index' -> [index], 'columns' -> [columns], 'data' -> [values]}
+        - 'tight' : dict like
+          {'index' -> [index], 'columns' -> [columns], 'data' -> [values],
+          'index_names' -> [index.names], 'column_names' -> [column.names]}
+        - 'records' : list like
+          [{column -> value}, ... , {column -> value}]
+        - 'index' : dict like {index -> {column -> value}}
+
+        .. versionadded:: 1.4.0
+            'tight' as an allowed value for the ``orient`` argument
+
+    into : class, default dict
+        The collections.abc.MutableMapping subclass used for all Mappings
+        in the return value.  Can be the actual class or an empty
+        instance of the mapping type you want.  If you want a
+        collections.defaultdict, you must pass it initialized.
+
+    index : bool, default True
+        Whether to include the index item (and index_names item if `orient`
+        is 'tight') in the returned dictionary. Can only be ``False``
+        when `orient` is 'split' or 'tight'.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    dict, list or collections.abc.Mapping
+        Return a collections.abc.MutableMapping object representing the
+        DataFrame. The resulting transformation depends on the `orient` parameter.
+    """
+    if not df.columns.is_unique:
+        warnings.warn(
+            "DataFrame columns are not unique, some columns will be omitted.",
+            UserWarning,
+            stacklevel=find_stack_level(),
+        )
+    # GH16122
+    into_c = com.standardize_mapping(into)
+
+    #  error: Incompatible types in assignment (expression has type "str",
+    # variable has type "Literal['dict', 'list', 'series', 'split', 'tight',
+    # 'records', 'index']")
+    orient = orient.lower()  # type: ignore[assignment]
+
+    if not index and orient not in ["split", "tight"]:
+        raise ValueError(
+            "'index=False' is only valid when 'orient' is 'split' or 'tight'"
+        )
+
+    if orient == "series":
+        # GH46470 Return quickly if orient series to avoid creating dtype objects
+        return into_c((k, v) for k, v in df.items())
+
+    box_native_indices = [
+        i
+        for i, col_dtype in enumerate(df.dtypes.values)
+        if col_dtype == np.dtype(object) or isinstance(col_dtype, ExtensionDtype)
+    ]
+    box_na_values = [
+        lib.no_default if not isinstance(col_dtype, BaseMaskedDtype) else libmissing.NA
+        for i, col_dtype in enumerate(df.dtypes.values)
+    ]
+    are_all_object_dtype_cols = len(box_native_indices) == len(df.dtypes)
+
+    if orient == "dict":
+        return into_c((k, v.to_dict(into=into)) for k, v in df.items())
+
+    elif orient == "list":
+        object_dtype_indices_as_set: set[int] = set(box_native_indices)
+        return into_c(
+            (
+                k,
+                list(map(maybe_box_native, v.to_numpy(na_value=box_na_values[i])))
+                if i in object_dtype_indices_as_set
+                else list(map(maybe_box_native, v.to_numpy())),
+            )
+            for i, (k, v) in enumerate(df.items())
+        )
+
+    elif orient == "split":
+        data = df._create_data_for_split_and_tight_to_dict(
+            are_all_object_dtype_cols, box_native_indices
+        )
+
+        return into_c(
+            ((("index", df.index.tolist()),) if index else ())
+            + (
+                ("columns", df.columns.tolist()),
+                ("data", data),
+            )
+        )
+
+    elif orient == "tight":
+        data = df._create_data_for_split_and_tight_to_dict(
+            are_all_object_dtype_cols, box_native_indices
+        )
+
+        return into_c(
+            ((("index", df.index.tolist()),) if index else ())
+            + (
+                ("columns", df.columns.tolist()),
+                (
+                    "data",
+                    [
+                        list(map(maybe_box_native, t))
+                        for t in df.itertuples(index=False, name=None)
+                    ],
+                ),
+            )
+            + ((("index_names", list(df.index.names)),) if index else ())
+            + (("column_names", list(df.columns.names)),)
+        )
+
+    elif orient == "records":
+        columns = df.columns.tolist()
+        if are_all_object_dtype_cols:
+            rows = (
+                dict(zip(columns, row)) for row in df.itertuples(index=False, name=None)
+            )
+            return [
+                into_c((k, maybe_box_native(v)) for k, v in row.items()) for row in rows
+            ]
+        else:
+            data = [
+                into_c(zip(columns, t)) for t in df.itertuples(index=False, name=None)
+            ]
+            if box_native_indices:
+                object_dtype_indices_as_set = set(box_native_indices)
+                object_dtype_cols = {
+                    col
+                    for i, col in enumerate(df.columns)
+                    if i in object_dtype_indices_as_set
+                }
+                for row in data:
+                    for col in object_dtype_cols:
+                        row[col] = maybe_box_native(row[col])
+            return data
+
+    elif orient == "index":
+        if not df.index.is_unique:
+            raise ValueError("DataFrame index must be unique for orient='index'.")
+        columns = df.columns.tolist()
+        if are_all_object_dtype_cols:
+            return into_c(
+                (t[0], dict(zip(df.columns, map(maybe_box_native, t[1:]))))
+                for t in df.itertuples(name=None)
+            )
+        elif box_native_indices:
+            object_dtype_indices_as_set = set(box_native_indices)
+            is_object_dtype_by_index = [
+                i in object_dtype_indices_as_set for i in range(len(df.columns))
+            ]
+            return into_c(
+                (
+                    t[0],
+                    {
+                        columns[i]: maybe_box_native(v)
+                        if is_object_dtype_by_index[i]
+                        else v
+                        for i, v in enumerate(t[1:])
+                    },
+                )
+                for t in df.itertuples(name=None)
+            )
+        else:
+            return into_c(
+                (t[0], dict(zip(df.columns, t[1:]))) for t in df.itertuples(name=None)
+            )
+
+    else:
+        raise ValueError(f"orient '{orient}' not understood")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/missing.py b/.venv/lib/python3.13/site-packages/pandas/core/missing.py
new file mode 100644
index 0000000000000000000000000000000000000000..c016aab8ad0748220d04d047f84d3aa14564ab80
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/missing.py
@@ -0,0 +1,1158 @@
+"""
+Routines for filling missing data.
+"""
+from __future__ import annotations
+
+from functools import wraps
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+    overload,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    algos,
+    lib,
+)
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    F,
+    ReindexMethod,
+    npt,
+)
+from pandas.compat._optional import import_optional_dependency
+
+from pandas.core.dtypes.cast import infer_dtype_from
+from pandas.core.dtypes.common import (
+    is_array_like,
+    is_bool_dtype,
+    is_numeric_dtype,
+    is_numeric_v_string_like,
+    is_object_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+from pandas.core.dtypes.missing import (
+    is_valid_na_for_dtype,
+    isna,
+    na_value_for_dtype,
+)
+
+if TYPE_CHECKING:
+    from pandas import Index
+
+
+def check_value_size(value, mask: npt.NDArray[np.bool_], length: int):
+    """
+    Validate the size of the values passed to ExtensionArray.fillna.
+    """
+    if is_array_like(value):
+        if len(value) != length:
+            raise ValueError(
+                f"Length of 'value' does not match. Got ({len(value)}) "
+                f" expected {length}"
+            )
+        value = value[mask]
+
+    return value
+
+
+def mask_missing(arr: ArrayLike, values_to_mask) -> npt.NDArray[np.bool_]:
+    """
+    Return a masking array of same size/shape as arr
+    with entries equaling any member of values_to_mask set to True
+
+    Parameters
+    ----------
+    arr : ArrayLike
+    values_to_mask: list, tuple, or scalar
+
+    Returns
+    -------
+    np.ndarray[bool]
+    """
+    # When called from Block.replace/replace_list, values_to_mask is a scalar
+    #  known to be holdable by arr.
+    # When called from Series._single_replace, values_to_mask is tuple or list
+    dtype, values_to_mask = infer_dtype_from(values_to_mask)
+
+    if isinstance(dtype, np.dtype):
+        values_to_mask = np.array(values_to_mask, dtype=dtype)
+    else:
+        cls = dtype.construct_array_type()
+        if not lib.is_list_like(values_to_mask):
+            values_to_mask = [values_to_mask]
+        values_to_mask = cls._from_sequence(values_to_mask, dtype=dtype, copy=False)
+
+    potential_na = False
+    if is_object_dtype(arr.dtype):
+        # pre-compute mask to avoid comparison to NA
+        potential_na = True
+        arr_mask = ~isna(arr)
+
+    na_mask = isna(values_to_mask)
+    nonna = values_to_mask[~na_mask]
+
+    # GH 21977
+    mask = np.zeros(arr.shape, dtype=bool)
+    if (
+        is_numeric_dtype(arr.dtype)
+        and not is_bool_dtype(arr.dtype)
+        and is_bool_dtype(nonna.dtype)
+    ):
+        pass
+    elif (
+        is_bool_dtype(arr.dtype)
+        and is_numeric_dtype(nonna.dtype)
+        and not is_bool_dtype(nonna.dtype)
+    ):
+        pass
+    else:
+        for x in nonna:
+            if is_numeric_v_string_like(arr, x):
+                # GH#29553 prevent numpy deprecation warnings
+                pass
+            else:
+                if potential_na:
+                    new_mask = np.zeros(arr.shape, dtype=np.bool_)
+                    new_mask[arr_mask] = arr[arr_mask] == x
+                else:
+                    new_mask = arr == x
+
+                    if not isinstance(new_mask, np.ndarray):
+                        # usually BooleanArray
+                        new_mask = new_mask.to_numpy(dtype=bool, na_value=False)
+                mask |= new_mask
+
+    if na_mask.any():
+        mask |= isna(arr)
+
+    return mask
+
+
+@overload
+def clean_fill_method(
+    method: Literal["ffill", "pad", "bfill", "backfill"],
+    *,
+    allow_nearest: Literal[False] = ...,
+) -> Literal["pad", "backfill"]:
+    ...
+
+
+@overload
+def clean_fill_method(
+    method: Literal["ffill", "pad", "bfill", "backfill", "nearest"],
+    *,
+    allow_nearest: Literal[True],
+) -> Literal["pad", "backfill", "nearest"]:
+    ...
+
+
+def clean_fill_method(
+    method: Literal["ffill", "pad", "bfill", "backfill", "nearest"],
+    *,
+    allow_nearest: bool = False,
+) -> Literal["pad", "backfill", "nearest"]:
+    if isinstance(method, str):
+        # error: Incompatible types in assignment (expression has type "str", variable
+        # has type "Literal['ffill', 'pad', 'bfill', 'backfill', 'nearest']")
+        method = method.lower()  # type: ignore[assignment]
+        if method == "ffill":
+            method = "pad"
+        elif method == "bfill":
+            method = "backfill"
+
+    valid_methods = ["pad", "backfill"]
+    expecting = "pad (ffill) or backfill (bfill)"
+    if allow_nearest:
+        valid_methods.append("nearest")
+        expecting = "pad (ffill), backfill (bfill) or nearest"
+    if method not in valid_methods:
+        raise ValueError(f"Invalid fill method. Expecting {expecting}. Got {method}")
+    return method
+
+
+# interpolation methods that dispatch to np.interp
+
+NP_METHODS = ["linear", "time", "index", "values"]
+
+# interpolation methods that dispatch to _interpolate_scipy_wrapper
+
+SP_METHODS = [
+    "nearest",
+    "zero",
+    "slinear",
+    "quadratic",
+    "cubic",
+    "barycentric",
+    "krogh",
+    "spline",
+    "polynomial",
+    "from_derivatives",
+    "piecewise_polynomial",
+    "pchip",
+    "akima",
+    "cubicspline",
+]
+
+
+def clean_interp_method(method: str, index: Index, **kwargs) -> str:
+    order = kwargs.get("order")
+
+    if method in ("spline", "polynomial") and order is None:
+        raise ValueError("You must specify the order of the spline or polynomial.")
+
+    valid = NP_METHODS + SP_METHODS
+    if method not in valid:
+        raise ValueError(f"method must be one of {valid}. Got '{method}' instead.")
+
+    if method in ("krogh", "piecewise_polynomial", "pchip"):
+        if not index.is_monotonic_increasing:
+            raise ValueError(
+                f"{method} interpolation requires that the index be monotonic."
+            )
+
+    return method
+
+
+def find_valid_index(how: str, is_valid: npt.NDArray[np.bool_]) -> int | None:
+    """
+    Retrieves the positional index of the first valid value.
+
+    Parameters
+    ----------
+    how : {'first', 'last'}
+        Use this parameter to change between the first or last valid index.
+    is_valid: np.ndarray
+        Mask to find na_values.
+
+    Returns
+    -------
+    int or None
+    """
+    assert how in ["first", "last"]
+
+    if len(is_valid) == 0:  # early stop
+        return None
+
+    if is_valid.ndim == 2:
+        is_valid = is_valid.any(axis=1)  # reduce axis 1
+
+    if how == "first":
+        idxpos = is_valid[::].argmax()
+
+    elif how == "last":
+        idxpos = len(is_valid) - 1 - is_valid[::-1].argmax()
+
+    chk_notna = is_valid[idxpos]
+
+    if not chk_notna:
+        return None
+    # Incompatible return value type (got "signedinteger[Any]",
+    # expected "Optional[int]")
+    return idxpos  # type: ignore[return-value]
+
+
+def validate_limit_direction(
+    limit_direction: str,
+) -> Literal["forward", "backward", "both"]:
+    valid_limit_directions = ["forward", "backward", "both"]
+    limit_direction = limit_direction.lower()
+    if limit_direction not in valid_limit_directions:
+        raise ValueError(
+            "Invalid limit_direction: expecting one of "
+            f"{valid_limit_directions}, got '{limit_direction}'."
+        )
+    # error: Incompatible return value type (got "str", expected
+    # "Literal['forward', 'backward', 'both']")
+    return limit_direction  # type: ignore[return-value]
+
+
+def validate_limit_area(limit_area: str | None) -> Literal["inside", "outside"] | None:
+    if limit_area is not None:
+        valid_limit_areas = ["inside", "outside"]
+        limit_area = limit_area.lower()
+        if limit_area not in valid_limit_areas:
+            raise ValueError(
+                f"Invalid limit_area: expecting one of {valid_limit_areas}, got "
+                f"{limit_area}."
+            )
+    # error: Incompatible return value type (got "Optional[str]", expected
+    # "Optional[Literal['inside', 'outside']]")
+    return limit_area  # type: ignore[return-value]
+
+
+def infer_limit_direction(
+    limit_direction: Literal["backward", "forward", "both"] | None, method: str
+) -> Literal["backward", "forward", "both"]:
+    # Set `limit_direction` depending on `method`
+    if limit_direction is None:
+        if method in ("backfill", "bfill"):
+            limit_direction = "backward"
+        else:
+            limit_direction = "forward"
+    else:
+        if method in ("pad", "ffill") and limit_direction != "forward":
+            raise ValueError(
+                f"`limit_direction` must be 'forward' for method `{method}`"
+            )
+        if method in ("backfill", "bfill") and limit_direction != "backward":
+            raise ValueError(
+                f"`limit_direction` must be 'backward' for method `{method}`"
+            )
+    return limit_direction
+
+
+def get_interp_index(method, index: Index) -> Index:
+    # create/use the index
+    if method == "linear":
+        # prior default
+        from pandas import Index
+
+        index = Index(np.arange(len(index)))
+    else:
+        methods = {"index", "values", "nearest", "time"}
+        is_numeric_or_datetime = (
+            is_numeric_dtype(index.dtype)
+            or isinstance(index.dtype, DatetimeTZDtype)
+            or lib.is_np_dtype(index.dtype, "mM")
+        )
+        if method not in methods and not is_numeric_or_datetime:
+            raise ValueError(
+                "Index column must be numeric or datetime type when "
+                f"using {method} method other than linear. "
+                "Try setting a numeric or datetime index column before "
+                "interpolating."
+            )
+
+    if isna(index).any():
+        raise NotImplementedError(
+            "Interpolation with NaNs in the index "
+            "has not been implemented. Try filling "
+            "those NaNs before interpolating."
+        )
+    return index
+
+
+def interpolate_2d_inplace(
+    data: np.ndarray,  # floating dtype
+    index: Index,
+    axis: AxisInt,
+    method: str = "linear",
+    limit: int | None = None,
+    limit_direction: str = "forward",
+    limit_area: str | None = None,
+    fill_value: Any | None = None,
+    mask=None,
+    **kwargs,
+) -> None:
+    """
+    Column-wise application of _interpolate_1d.
+
+    Notes
+    -----
+    Alters 'data' in-place.
+
+    The signature does differ from _interpolate_1d because it only
+    includes what is needed for Block.interpolate.
+    """
+    # validate the interp method
+    clean_interp_method(method, index, **kwargs)
+
+    if is_valid_na_for_dtype(fill_value, data.dtype):
+        fill_value = na_value_for_dtype(data.dtype, compat=False)
+
+    if method == "time":
+        if not needs_i8_conversion(index.dtype):
+            raise ValueError(
+                "time-weighted interpolation only works "
+                "on Series or DataFrames with a "
+                "DatetimeIndex"
+            )
+        method = "values"
+
+    limit_direction = validate_limit_direction(limit_direction)
+    limit_area_validated = validate_limit_area(limit_area)
+
+    # default limit is unlimited GH #16282
+    limit = algos.validate_limit(nobs=None, limit=limit)
+
+    indices = _index_to_interp_indices(index, method)
+
+    def func(yvalues: np.ndarray) -> None:
+        # process 1-d slices in the axis direction
+
+        _interpolate_1d(
+            indices=indices,
+            yvalues=yvalues,
+            method=method,
+            limit=limit,
+            limit_direction=limit_direction,
+            limit_area=limit_area_validated,
+            fill_value=fill_value,
+            bounds_error=False,
+            mask=mask,
+            **kwargs,
+        )
+
+    # error: Argument 1 to "apply_along_axis" has incompatible type
+    # "Callable[[ndarray[Any, Any]], None]"; expected "Callable[...,
+    # Union[_SupportsArray[dtype[]], Sequence[_SupportsArray
+    # [dtype[]]], Sequence[Sequence[_SupportsArray[dtype[]]]],
+    # Sequence[Sequence[Sequence[_SupportsArray[dtype[]]]]],
+    # Sequence[Sequence[Sequence[Sequence[_SupportsArray[dtype[]]]]]]]]"
+    np.apply_along_axis(func, axis, data)  # type: ignore[arg-type]
+
+
+def _index_to_interp_indices(index: Index, method: str) -> np.ndarray:
+    """
+    Convert Index to ndarray of indices to pass to NumPy/SciPy.
+    """
+    xarr = index._values
+    if needs_i8_conversion(xarr.dtype):
+        # GH#1646 for dt64tz
+        xarr = xarr.view("i8")
+
+    if method == "linear":
+        inds = xarr
+        inds = cast(np.ndarray, inds)
+    else:
+        inds = np.asarray(xarr)
+
+        if method in ("values", "index"):
+            if inds.dtype == np.object_:
+                inds = lib.maybe_convert_objects(inds)
+
+    return inds
+
+
+def _interpolate_1d(
+    indices: np.ndarray,
+    yvalues: np.ndarray,
+    method: str = "linear",
+    limit: int | None = None,
+    limit_direction: str = "forward",
+    limit_area: Literal["inside", "outside"] | None = None,
+    fill_value: Any | None = None,
+    bounds_error: bool = False,
+    order: int | None = None,
+    mask=None,
+    **kwargs,
+) -> None:
+    """
+    Logic for the 1-d interpolation.  The input
+    indices and yvalues will each be 1-d arrays of the same length.
+
+    Bounds_error is currently hardcoded to False since non-scipy ones don't
+    take it as an argument.
+
+    Notes
+    -----
+    Fills 'yvalues' in-place.
+    """
+    if mask is not None:
+        invalid = mask
+    else:
+        invalid = isna(yvalues)
+    valid = ~invalid
+
+    if not valid.any():
+        return
+
+    if valid.all():
+        return
+
+    # These are sets of index pointers to invalid values... i.e. {0, 1, etc...
+    all_nans = set(np.flatnonzero(invalid))
+
+    first_valid_index = find_valid_index(how="first", is_valid=valid)
+    if first_valid_index is None:  # no nan found in start
+        first_valid_index = 0
+    start_nans = set(range(first_valid_index))
+
+    last_valid_index = find_valid_index(how="last", is_valid=valid)
+    if last_valid_index is None:  # no nan found in end
+        last_valid_index = len(yvalues)
+    end_nans = set(range(1 + last_valid_index, len(valid)))
+
+    # Like the sets above, preserve_nans contains indices of invalid values,
+    # but in this case, it is the final set of indices that need to be
+    # preserved as NaN after the interpolation.
+
+    # For example if limit_direction='forward' then preserve_nans will
+    # contain indices of NaNs at the beginning of the series, and NaNs that
+    # are more than 'limit' away from the prior non-NaN.
+
+    # set preserve_nans based on direction using _interp_limit
+    preserve_nans: list | set
+    if limit_direction == "forward":
+        preserve_nans = start_nans | set(_interp_limit(invalid, limit, 0))
+    elif limit_direction == "backward":
+        preserve_nans = end_nans | set(_interp_limit(invalid, 0, limit))
+    else:
+        # both directions... just use _interp_limit
+        preserve_nans = set(_interp_limit(invalid, limit, limit))
+
+    # if limit_area is set, add either mid or outside indices
+    # to preserve_nans GH #16284
+    if limit_area == "inside":
+        # preserve NaNs on the outside
+        preserve_nans |= start_nans | end_nans
+    elif limit_area == "outside":
+        # preserve NaNs on the inside
+        mid_nans = all_nans - start_nans - end_nans
+        preserve_nans |= mid_nans
+
+    # sort preserve_nans and convert to list
+    preserve_nans = sorted(preserve_nans)
+
+    is_datetimelike = yvalues.dtype.kind in "mM"
+
+    if is_datetimelike:
+        yvalues = yvalues.view("i8")
+
+    if method in NP_METHODS:
+        # np.interp requires sorted X values, #21037
+
+        indexer = np.argsort(indices[valid])
+        yvalues[invalid] = np.interp(
+            indices[invalid], indices[valid][indexer], yvalues[valid][indexer]
+        )
+    else:
+        yvalues[invalid] = _interpolate_scipy_wrapper(
+            indices[valid],
+            yvalues[valid],
+            indices[invalid],
+            method=method,
+            fill_value=fill_value,
+            bounds_error=bounds_error,
+            order=order,
+            **kwargs,
+        )
+
+    if mask is not None:
+        mask[:] = False
+        mask[preserve_nans] = True
+    elif is_datetimelike:
+        yvalues[preserve_nans] = NaT.value
+    else:
+        yvalues[preserve_nans] = np.nan
+    return
+
+
+def _interpolate_scipy_wrapper(
+    x: np.ndarray,
+    y: np.ndarray,
+    new_x: np.ndarray,
+    method: str,
+    fill_value=None,
+    bounds_error: bool = False,
+    order=None,
+    **kwargs,
+):
+    """
+    Passed off to scipy.interpolate.interp1d. method is scipy's kind.
+    Returns an array interpolated at new_x.  Add any new methods to
+    the list in _clean_interp_method.
+    """
+    extra = f"{method} interpolation requires SciPy."
+    import_optional_dependency("scipy", extra=extra)
+    from scipy import interpolate
+
+    new_x = np.asarray(new_x)
+
+    # ignores some kwargs that could be passed along.
+    alt_methods = {
+        "barycentric": interpolate.barycentric_interpolate,
+        "krogh": interpolate.krogh_interpolate,
+        "from_derivatives": _from_derivatives,
+        "piecewise_polynomial": _from_derivatives,
+        "cubicspline": _cubicspline_interpolate,
+        "akima": _akima_interpolate,
+        "pchip": interpolate.pchip_interpolate,
+    }
+
+    interp1d_methods = [
+        "nearest",
+        "zero",
+        "slinear",
+        "quadratic",
+        "cubic",
+        "polynomial",
+    ]
+    if method in interp1d_methods:
+        if method == "polynomial":
+            kind = order
+        else:
+            kind = method
+        terp = interpolate.interp1d(
+            x, y, kind=kind, fill_value=fill_value, bounds_error=bounds_error
+        )
+        new_y = terp(new_x)
+    elif method == "spline":
+        # GH #10633, #24014
+        if isna(order) or (order <= 0):
+            raise ValueError(
+                f"order needs to be specified and greater than 0; got order: {order}"
+            )
+        terp = interpolate.UnivariateSpline(x, y, k=order, **kwargs)
+        new_y = terp(new_x)
+    else:
+        # GH 7295: need to be able to write for some reason
+        # in some circumstances: check all three
+        if not x.flags.writeable:
+            x = x.copy()
+        if not y.flags.writeable:
+            y = y.copy()
+        if not new_x.flags.writeable:
+            new_x = new_x.copy()
+        terp = alt_methods[method]
+        new_y = terp(x, y, new_x, **kwargs)
+    return new_y
+
+
+def _from_derivatives(
+    xi: np.ndarray,
+    yi: np.ndarray,
+    x: np.ndarray,
+    order=None,
+    der: int | list[int] | None = 0,
+    extrapolate: bool = False,
+):
+    """
+    Convenience function for interpolate.BPoly.from_derivatives.
+
+    Construct a piecewise polynomial in the Bernstein basis, compatible
+    with the specified values and derivatives at breakpoints.
+
+    Parameters
+    ----------
+    xi : array-like
+        sorted 1D array of x-coordinates
+    yi : array-like or list of array-likes
+        yi[i][j] is the j-th derivative known at xi[i]
+    order: None or int or array-like of ints. Default: None.
+        Specifies the degree of local polynomials. If not None, some
+        derivatives are ignored.
+    der : int or list
+        How many derivatives to extract; None for all potentially nonzero
+        derivatives (that is a number equal to the number of points), or a
+        list of derivatives to extract. This number includes the function
+        value as 0th derivative.
+     extrapolate : bool, optional
+        Whether to extrapolate to ouf-of-bounds points based on first and last
+        intervals, or to return NaNs. Default: True.
+
+    See Also
+    --------
+    scipy.interpolate.BPoly.from_derivatives
+
+    Returns
+    -------
+    y : scalar or array-like
+        The result, of length R or length M or M by R.
+    """
+    from scipy import interpolate
+
+    # return the method for compat with scipy version & backwards compat
+    method = interpolate.BPoly.from_derivatives
+    m = method(xi, yi.reshape(-1, 1), orders=order, extrapolate=extrapolate)
+
+    return m(x)
+
+
+def _akima_interpolate(
+    xi: np.ndarray,
+    yi: np.ndarray,
+    x: np.ndarray,
+    der: int | list[int] | None = 0,
+    axis: AxisInt = 0,
+):
+    """
+    Convenience function for akima interpolation.
+    xi and yi are arrays of values used to approximate some function f,
+    with ``yi = f(xi)``.
+
+    See `Akima1DInterpolator` for details.
+
+    Parameters
+    ----------
+    xi : np.ndarray
+        A sorted list of x-coordinates, of length N.
+    yi : np.ndarray
+        A 1-D array of real values.  `yi`'s length along the interpolation
+        axis must be equal to the length of `xi`. If N-D array, use axis
+        parameter to select correct axis.
+    x : np.ndarray
+        Of length M.
+    der : int, optional
+        How many derivatives to extract; None for all potentially
+        nonzero derivatives (that is a number equal to the number
+        of points), or a list of derivatives to extract. This number
+        includes the function value as 0th derivative.
+    axis : int, optional
+        Axis in the yi array corresponding to the x-coordinate values.
+
+    See Also
+    --------
+    scipy.interpolate.Akima1DInterpolator
+
+    Returns
+    -------
+    y : scalar or array-like
+        The result, of length R or length M or M by R,
+
+    """
+    from scipy import interpolate
+
+    P = interpolate.Akima1DInterpolator(xi, yi, axis=axis)
+
+    return P(x, nu=der)
+
+
+def _cubicspline_interpolate(
+    xi: np.ndarray,
+    yi: np.ndarray,
+    x: np.ndarray,
+    axis: AxisInt = 0,
+    bc_type: str | tuple[Any, Any] = "not-a-knot",
+    extrapolate=None,
+):
+    """
+    Convenience function for cubic spline data interpolator.
+
+    See `scipy.interpolate.CubicSpline` for details.
+
+    Parameters
+    ----------
+    xi : np.ndarray, shape (n,)
+        1-d array containing values of the independent variable.
+        Values must be real, finite and in strictly increasing order.
+    yi : np.ndarray
+        Array containing values of the dependent variable. It can have
+        arbitrary number of dimensions, but the length along ``axis``
+        (see below) must match the length of ``x``. Values must be finite.
+    x : np.ndarray, shape (m,)
+    axis : int, optional
+        Axis along which `y` is assumed to be varying. Meaning that for
+        ``x[i]`` the corresponding values are ``np.take(y, i, axis=axis)``.
+        Default is 0.
+    bc_type : string or 2-tuple, optional
+        Boundary condition type. Two additional equations, given by the
+        boundary conditions, are required to determine all coefficients of
+        polynomials on each segment [2]_.
+        If `bc_type` is a string, then the specified condition will be applied
+        at both ends of a spline. Available conditions are:
+        * 'not-a-knot' (default): The first and second segment at a curve end
+          are the same polynomial. It is a good default when there is no
+          information on boundary conditions.
+        * 'periodic': The interpolated functions is assumed to be periodic
+          of period ``x[-1] - x[0]``. The first and last value of `y` must be
+          identical: ``y[0] == y[-1]``. This boundary condition will result in
+          ``y'[0] == y'[-1]`` and ``y''[0] == y''[-1]``.
+        * 'clamped': The first derivative at curves ends are zero. Assuming
+          a 1D `y`, ``bc_type=((1, 0.0), (1, 0.0))`` is the same condition.
+        * 'natural': The second derivative at curve ends are zero. Assuming
+          a 1D `y`, ``bc_type=((2, 0.0), (2, 0.0))`` is the same condition.
+        If `bc_type` is a 2-tuple, the first and the second value will be
+        applied at the curve start and end respectively. The tuple values can
+        be one of the previously mentioned strings (except 'periodic') or a
+        tuple `(order, deriv_values)` allowing to specify arbitrary
+        derivatives at curve ends:
+        * `order`: the derivative order, 1 or 2.
+        * `deriv_value`: array-like containing derivative values, shape must
+          be the same as `y`, excluding ``axis`` dimension. For example, if
+          `y` is 1D, then `deriv_value` must be a scalar. If `y` is 3D with
+          the shape (n0, n1, n2) and axis=2, then `deriv_value` must be 2D
+          and have the shape (n0, n1).
+    extrapolate : {bool, 'periodic', None}, optional
+        If bool, determines whether to extrapolate to out-of-bounds points
+        based on first and last intervals, or to return NaNs. If 'periodic',
+        periodic extrapolation is used. If None (default), ``extrapolate`` is
+        set to 'periodic' for ``bc_type='periodic'`` and to True otherwise.
+
+    See Also
+    --------
+    scipy.interpolate.CubicHermiteSpline
+
+    Returns
+    -------
+    y : scalar or array-like
+        The result, of shape (m,)
+
+    References
+    ----------
+    .. [1] `Cubic Spline Interpolation
+            `_
+            on Wikiversity.
+    .. [2] Carl de Boor, "A Practical Guide to Splines", Springer-Verlag, 1978.
+    """
+    from scipy import interpolate
+
+    P = interpolate.CubicSpline(
+        xi, yi, axis=axis, bc_type=bc_type, extrapolate=extrapolate
+    )
+
+    return P(x)
+
+
+def _interpolate_with_limit_area(
+    values: np.ndarray,
+    method: Literal["pad", "backfill"],
+    limit: int | None,
+    limit_area: Literal["inside", "outside"],
+) -> None:
+    """
+    Apply interpolation and limit_area logic to values along a to-be-specified axis.
+
+    Parameters
+    ----------
+    values: np.ndarray
+        Input array.
+    method: str
+        Interpolation method. Could be "bfill" or "pad"
+    limit: int, optional
+        Index limit on interpolation.
+    limit_area: {'inside', 'outside'}
+        Limit area for interpolation.
+
+    Notes
+    -----
+    Modifies values in-place.
+    """
+
+    invalid = isna(values)
+    is_valid = ~invalid
+
+    if not invalid.all():
+        first = find_valid_index(how="first", is_valid=is_valid)
+        if first is None:
+            first = 0
+        last = find_valid_index(how="last", is_valid=is_valid)
+        if last is None:
+            last = len(values)
+
+        pad_or_backfill_inplace(
+            values,
+            method=method,
+            limit=limit,
+            limit_area=limit_area,
+        )
+
+        if limit_area == "inside":
+            invalid[first : last + 1] = False
+        elif limit_area == "outside":
+            invalid[:first] = invalid[last + 1 :] = False
+        else:
+            raise ValueError("limit_area should be 'inside' or 'outside'")
+
+        values[invalid] = np.nan
+
+
+def pad_or_backfill_inplace(
+    values: np.ndarray,
+    method: Literal["pad", "backfill"] = "pad",
+    axis: AxisInt = 0,
+    limit: int | None = None,
+    limit_area: Literal["inside", "outside"] | None = None,
+) -> None:
+    """
+    Perform an actual interpolation of values, values will be make 2-d if
+    needed fills inplace, returns the result.
+
+    Parameters
+    ----------
+    values: np.ndarray
+        Input array.
+    method: str, default "pad"
+        Interpolation method. Could be "bfill" or "pad"
+    axis: 0 or 1
+        Interpolation axis
+    limit: int, optional
+        Index limit on interpolation.
+    limit_area: str, optional
+        Limit area for interpolation. Can be "inside" or "outside"
+
+    Notes
+    -----
+    Modifies values in-place.
+    """
+    transf = (lambda x: x) if axis == 0 else (lambda x: x.T)
+
+    # reshape a 1 dim if needed
+    if values.ndim == 1:
+        if axis != 0:  # pragma: no cover
+            raise AssertionError("cannot interpolate on a ndim == 1 with axis != 0")
+        values = values.reshape(tuple((1,) + values.shape))
+
+    method = clean_fill_method(method)
+    tvalues = transf(values)
+
+    func = get_fill_func(method, ndim=2)
+    # _pad_2d and _backfill_2d both modify tvalues inplace
+    func(tvalues, limit=limit, limit_area=limit_area)
+
+
+def _fillna_prep(
+    values, mask: npt.NDArray[np.bool_] | None = None
+) -> npt.NDArray[np.bool_]:
+    # boilerplate for _pad_1d, _backfill_1d, _pad_2d, _backfill_2d
+
+    if mask is None:
+        mask = isna(values)
+
+    return mask
+
+
+def _datetimelike_compat(func: F) -> F:
+    """
+    Wrapper to handle datetime64 and timedelta64 dtypes.
+    """
+
+    @wraps(func)
+    def new_func(
+        values,
+        limit: int | None = None,
+        limit_area: Literal["inside", "outside"] | None = None,
+        mask=None,
+    ):
+        if needs_i8_conversion(values.dtype):
+            if mask is None:
+                # This needs to occur before casting to int64
+                mask = isna(values)
+
+            result, mask = func(
+                values.view("i8"), limit=limit, limit_area=limit_area, mask=mask
+            )
+            return result.view(values.dtype), mask
+
+        return func(values, limit=limit, limit_area=limit_area, mask=mask)
+
+    return cast(F, new_func)
+
+
+@_datetimelike_compat
+def _pad_1d(
+    values: np.ndarray,
+    limit: int | None = None,
+    limit_area: Literal["inside", "outside"] | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> tuple[np.ndarray, npt.NDArray[np.bool_]]:
+    mask = _fillna_prep(values, mask)
+    if limit_area is not None and not mask.all():
+        _fill_limit_area_1d(mask, limit_area)
+    algos.pad_inplace(values, mask, limit=limit)
+    return values, mask
+
+
+@_datetimelike_compat
+def _backfill_1d(
+    values: np.ndarray,
+    limit: int | None = None,
+    limit_area: Literal["inside", "outside"] | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> tuple[np.ndarray, npt.NDArray[np.bool_]]:
+    mask = _fillna_prep(values, mask)
+    if limit_area is not None and not mask.all():
+        _fill_limit_area_1d(mask, limit_area)
+    algos.backfill_inplace(values, mask, limit=limit)
+    return values, mask
+
+
+@_datetimelike_compat
+def _pad_2d(
+    values: np.ndarray,
+    limit: int | None = None,
+    limit_area: Literal["inside", "outside"] | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+):
+    mask = _fillna_prep(values, mask)
+    if limit_area is not None:
+        _fill_limit_area_2d(mask, limit_area)
+
+    if values.size:
+        algos.pad_2d_inplace(values, mask, limit=limit)
+    else:
+        # for test coverage
+        pass
+    return values, mask
+
+
+@_datetimelike_compat
+def _backfill_2d(
+    values,
+    limit: int | None = None,
+    limit_area: Literal["inside", "outside"] | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+):
+    mask = _fillna_prep(values, mask)
+    if limit_area is not None:
+        _fill_limit_area_2d(mask, limit_area)
+
+    if values.size:
+        algos.backfill_2d_inplace(values, mask, limit=limit)
+    else:
+        # for test coverage
+        pass
+    return values, mask
+
+
+def _fill_limit_area_1d(
+    mask: npt.NDArray[np.bool_], limit_area: Literal["outside", "inside"]
+) -> None:
+    """Prepare 1d mask for ffill/bfill with limit_area.
+
+    Caller is responsible for checking at least one value of mask is False.
+    When called, mask will no longer faithfully represent when
+    the corresponding are NA or not.
+
+    Parameters
+    ----------
+    mask : np.ndarray[bool, ndim=1]
+        Mask representing NA values when filling.
+    limit_area : { "outside", "inside" }
+        Whether to limit filling to outside or inside the outer most non-NA value.
+    """
+    neg_mask = ~mask
+    first = neg_mask.argmax()
+    last = len(neg_mask) - neg_mask[::-1].argmax() - 1
+    if limit_area == "inside":
+        mask[:first] = False
+        mask[last + 1 :] = False
+    elif limit_area == "outside":
+        mask[first + 1 : last] = False
+
+
+def _fill_limit_area_2d(
+    mask: npt.NDArray[np.bool_], limit_area: Literal["outside", "inside"]
+) -> None:
+    """Prepare 2d mask for ffill/bfill with limit_area.
+
+    When called, mask will no longer faithfully represent when
+    the corresponding are NA or not.
+
+    Parameters
+    ----------
+    mask : np.ndarray[bool, ndim=1]
+        Mask representing NA values when filling.
+    limit_area : { "outside", "inside" }
+        Whether to limit filling to outside or inside the outer most non-NA value.
+    """
+    neg_mask = ~mask.T
+    if limit_area == "outside":
+        # Identify inside
+        la_mask = (
+            np.maximum.accumulate(neg_mask, axis=0)
+            & np.maximum.accumulate(neg_mask[::-1], axis=0)[::-1]
+        )
+    else:
+        # Identify outside
+        la_mask = (
+            ~np.maximum.accumulate(neg_mask, axis=0)
+            | ~np.maximum.accumulate(neg_mask[::-1], axis=0)[::-1]
+        )
+    mask[la_mask.T] = False
+
+
+_fill_methods = {"pad": _pad_1d, "backfill": _backfill_1d}
+
+
+def get_fill_func(method, ndim: int = 1):
+    method = clean_fill_method(method)
+    if ndim == 1:
+        return _fill_methods[method]
+    return {"pad": _pad_2d, "backfill": _backfill_2d}[method]
+
+
+def clean_reindex_fill_method(method) -> ReindexMethod | None:
+    if method is None:
+        return None
+    return clean_fill_method(method, allow_nearest=True)
+
+
+def _interp_limit(
+    invalid: npt.NDArray[np.bool_], fw_limit: int | None, bw_limit: int | None
+):
+    """
+    Get indexers of values that won't be filled
+    because they exceed the limits.
+
+    Parameters
+    ----------
+    invalid : np.ndarray[bool]
+    fw_limit : int or None
+        forward limit to index
+    bw_limit : int or None
+        backward limit to index
+
+    Returns
+    -------
+    set of indexers
+
+    Notes
+    -----
+    This is equivalent to the more readable, but slower
+
+    .. code-block:: python
+
+        def _interp_limit(invalid, fw_limit, bw_limit):
+            for x in np.where(invalid)[0]:
+                if invalid[max(0, x - fw_limit):x + bw_limit + 1].all():
+                    yield x
+    """
+    # handle forward first; the backward direction is the same except
+    # 1. operate on the reversed array
+    # 2. subtract the returned indices from N - 1
+    N = len(invalid)
+    f_idx = set()
+    b_idx = set()
+
+    def inner(invalid, limit: int):
+        limit = min(limit, N)
+        windowed = _rolling_window(invalid, limit + 1).all(1)
+        idx = set(np.where(windowed)[0] + limit) | set(
+            np.where((~invalid[: limit + 1]).cumsum() == 0)[0]
+        )
+        return idx
+
+    if fw_limit is not None:
+        if fw_limit == 0:
+            f_idx = set(np.where(invalid)[0])
+        else:
+            f_idx = inner(invalid, fw_limit)
+
+    if bw_limit is not None:
+        if bw_limit == 0:
+            # then we don't even need to care about backwards
+            # just use forwards
+            return f_idx
+        else:
+            b_idx_inv = list(inner(invalid[::-1], bw_limit))
+            b_idx = set(N - 1 - np.asarray(b_idx_inv))
+            if fw_limit == 0:
+                return b_idx
+
+    return f_idx & b_idx
+
+
+def _rolling_window(a: npt.NDArray[np.bool_], window: int) -> npt.NDArray[np.bool_]:
+    """
+    [True, True, False, True, False], 2 ->
+
+    [
+        [True,  True],
+        [True, False],
+        [False, True],
+        [True, False],
+    ]
+    """
+    # https://stackoverflow.com/a/6811241
+    shape = a.shape[:-1] + (a.shape[-1] - window + 1, window)
+    strides = a.strides + (a.strides[-1],)
+    return np.lib.stride_tricks.as_strided(a, shape=shape, strides=strides)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/nanops.py b/.venv/lib/python3.13/site-packages/pandas/core/nanops.py
new file mode 100644
index 0000000000000000000000000000000000000000..6cb825e9b79a25742d6f9f622b7226dbd68d88fe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/nanops.py
@@ -0,0 +1,1748 @@
+from __future__ import annotations
+
+import functools
+import itertools
+from typing import (
+    Any,
+    Callable,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs import (
+    NaT,
+    NaTType,
+    iNaT,
+    lib,
+)
+from pandas._typing import (
+    ArrayLike,
+    AxisInt,
+    CorrelationMethod,
+    Dtype,
+    DtypeObj,
+    F,
+    Scalar,
+    Shape,
+    npt,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_complex,
+    is_float,
+    is_float_dtype,
+    is_integer,
+    is_numeric_dtype,
+    is_object_dtype,
+    needs_i8_conversion,
+    pandas_dtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+    notna,
+)
+
+bn = import_optional_dependency("bottleneck", errors="warn")
+_BOTTLENECK_INSTALLED = bn is not None
+_USE_BOTTLENECK = False
+
+
+def set_use_bottleneck(v: bool = True) -> None:
+    # set/unset to use bottleneck
+    global _USE_BOTTLENECK
+    if _BOTTLENECK_INSTALLED:
+        _USE_BOTTLENECK = v
+
+
+set_use_bottleneck(get_option("compute.use_bottleneck"))
+
+
+class disallow:
+    def __init__(self, *dtypes: Dtype) -> None:
+        super().__init__()
+        self.dtypes = tuple(pandas_dtype(dtype).type for dtype in dtypes)
+
+    def check(self, obj) -> bool:
+        return hasattr(obj, "dtype") and issubclass(obj.dtype.type, self.dtypes)
+
+    def __call__(self, f: F) -> F:
+        @functools.wraps(f)
+        def _f(*args, **kwargs):
+            obj_iter = itertools.chain(args, kwargs.values())
+            if any(self.check(obj) for obj in obj_iter):
+                f_name = f.__name__.replace("nan", "")
+                raise TypeError(
+                    f"reduction operation '{f_name}' not allowed for this dtype"
+                )
+            try:
+                return f(*args, **kwargs)
+            except ValueError as e:
+                # we want to transform an object array
+                # ValueError message to the more typical TypeError
+                # e.g. this is normally a disallowed function on
+                # object arrays that contain strings
+                if is_object_dtype(args[0]):
+                    raise TypeError(e) from e
+                raise
+
+        return cast(F, _f)
+
+
+class bottleneck_switch:
+    def __init__(self, name=None, **kwargs) -> None:
+        self.name = name
+        self.kwargs = kwargs
+
+    def __call__(self, alt: F) -> F:
+        bn_name = self.name or alt.__name__
+
+        try:
+            bn_func = getattr(bn, bn_name)
+        except (AttributeError, NameError):  # pragma: no cover
+            bn_func = None
+
+        @functools.wraps(alt)
+        def f(
+            values: np.ndarray,
+            *,
+            axis: AxisInt | None = None,
+            skipna: bool = True,
+            **kwds,
+        ):
+            if len(self.kwargs) > 0:
+                for k, v in self.kwargs.items():
+                    if k not in kwds:
+                        kwds[k] = v
+
+            if values.size == 0 and kwds.get("min_count") is None:
+                # We are empty, returning NA for our type
+                # Only applies for the default `min_count` of None
+                # since that affects how empty arrays are handled.
+                # TODO(GH-18976) update all the nanops methods to
+                # correctly handle empty inputs and remove this check.
+                # It *may* just be `var`
+                return _na_for_min_count(values, axis)
+
+            if _USE_BOTTLENECK and skipna and _bn_ok_dtype(values.dtype, bn_name):
+                if kwds.get("mask", None) is None:
+                    # `mask` is not recognised by bottleneck, would raise
+                    #  TypeError if called
+                    kwds.pop("mask", None)
+                    result = bn_func(values, axis=axis, **kwds)
+
+                    # prefer to treat inf/-inf as NA, but must compute the func
+                    # twice :(
+                    if _has_infs(result):
+                        result = alt(values, axis=axis, skipna=skipna, **kwds)
+                else:
+                    result = alt(values, axis=axis, skipna=skipna, **kwds)
+            else:
+                result = alt(values, axis=axis, skipna=skipna, **kwds)
+
+            return result
+
+        return cast(F, f)
+
+
+def _bn_ok_dtype(dtype: DtypeObj, name: str) -> bool:
+    # Bottleneck chokes on datetime64, PeriodDtype (or and EA)
+    if dtype != object and not needs_i8_conversion(dtype):
+        # GH 42878
+        # Bottleneck uses naive summation leading to O(n) loss of precision
+        # unlike numpy which implements pairwise summation, which has O(log(n)) loss
+        # crossref: https://github.com/pydata/bottleneck/issues/379
+
+        # GH 15507
+        # bottleneck does not properly upcast during the sum
+        # so can overflow
+
+        # GH 9422
+        # further we also want to preserve NaN when all elements
+        # are NaN, unlike bottleneck/numpy which consider this
+        # to be 0
+        return name not in ["nansum", "nanprod", "nanmean"]
+    return False
+
+
+def _has_infs(result) -> bool:
+    if isinstance(result, np.ndarray):
+        if result.dtype in ("f8", "f4"):
+            # Note: outside of an nanops-specific test, we always have
+            #  result.ndim == 1, so there is no risk of this ravel making a copy.
+            return lib.has_infs(result.ravel("K"))
+    try:
+        return np.isinf(result).any()
+    except (TypeError, NotImplementedError):
+        # if it doesn't support infs, then it can't have infs
+        return False
+
+
+def _get_fill_value(
+    dtype: DtypeObj, fill_value: Scalar | None = None, fill_value_typ=None
+):
+    """return the correct fill value for the dtype of the values"""
+    if fill_value is not None:
+        return fill_value
+    if _na_ok_dtype(dtype):
+        if fill_value_typ is None:
+            return np.nan
+        else:
+            if fill_value_typ == "+inf":
+                return np.inf
+            else:
+                return -np.inf
+    else:
+        if fill_value_typ == "+inf":
+            # need the max int here
+            return lib.i8max
+        else:
+            return iNaT
+
+
+def _maybe_get_mask(
+    values: np.ndarray, skipna: bool, mask: npt.NDArray[np.bool_] | None
+) -> npt.NDArray[np.bool_] | None:
+    """
+    Compute a mask if and only if necessary.
+
+    This function will compute a mask iff it is necessary. Otherwise,
+    return the provided mask (potentially None) when a mask does not need to be
+    computed.
+
+    A mask is never necessary if the values array is of boolean or integer
+    dtypes, as these are incapable of storing NaNs. If passing a NaN-capable
+    dtype that is interpretable as either boolean or integer data (eg,
+    timedelta64), a mask must be provided.
+
+    If the skipna parameter is False, a new mask will not be computed.
+
+    The mask is computed using isna() by default. Setting invert=True selects
+    notna() as the masking function.
+
+    Parameters
+    ----------
+    values : ndarray
+        input array to potentially compute mask for
+    skipna : bool
+        boolean for whether NaNs should be skipped
+    mask : Optional[ndarray]
+        nan-mask if known
+
+    Returns
+    -------
+    Optional[np.ndarray[bool]]
+    """
+    if mask is None:
+        if values.dtype.kind in "biu":
+            # Boolean data cannot contain nulls, so signal via mask being None
+            return None
+
+        if skipna or values.dtype.kind in "mM":
+            mask = isna(values)
+
+    return mask
+
+
+def _get_values(
+    values: np.ndarray,
+    skipna: bool,
+    fill_value: Any = None,
+    fill_value_typ: str | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> tuple[np.ndarray, npt.NDArray[np.bool_] | None]:
+    """
+    Utility to get the values view, mask, dtype, dtype_max, and fill_value.
+
+    If both mask and fill_value/fill_value_typ are not None and skipna is True,
+    the values array will be copied.
+
+    For input arrays of boolean or integer dtypes, copies will only occur if a
+    precomputed mask, a fill_value/fill_value_typ, and skipna=True are
+    provided.
+
+    Parameters
+    ----------
+    values : ndarray
+        input array to potentially compute mask for
+    skipna : bool
+        boolean for whether NaNs should be skipped
+    fill_value : Any
+        value to fill NaNs with
+    fill_value_typ : str
+        Set to '+inf' or '-inf' to handle dtype-specific infinities
+    mask : Optional[np.ndarray[bool]]
+        nan-mask if known
+
+    Returns
+    -------
+    values : ndarray
+        Potential copy of input value array
+    mask : Optional[ndarray[bool]]
+        Mask for values, if deemed necessary to compute
+    """
+    # In _get_values is only called from within nanops, and in all cases
+    #  with scalar fill_value.  This guarantee is important for the
+    #  np.where call below
+
+    mask = _maybe_get_mask(values, skipna, mask)
+
+    dtype = values.dtype
+
+    datetimelike = False
+    if values.dtype.kind in "mM":
+        # changing timedelta64/datetime64 to int64 needs to happen after
+        #  finding `mask` above
+        values = np.asarray(values.view("i8"))
+        datetimelike = True
+
+    if skipna and (mask is not None):
+        # get our fill value (in case we need to provide an alternative
+        # dtype for it)
+        fill_value = _get_fill_value(
+            dtype, fill_value=fill_value, fill_value_typ=fill_value_typ
+        )
+
+        if fill_value is not None:
+            if mask.any():
+                if datetimelike or _na_ok_dtype(dtype):
+                    values = values.copy()
+                    np.putmask(values, mask, fill_value)
+                else:
+                    # np.where will promote if needed
+                    values = np.where(~mask, values, fill_value)
+
+    return values, mask
+
+
+def _get_dtype_max(dtype: np.dtype) -> np.dtype:
+    # return a platform independent precision dtype
+    dtype_max = dtype
+    if dtype.kind in "bi":
+        dtype_max = np.dtype(np.int64)
+    elif dtype.kind == "u":
+        dtype_max = np.dtype(np.uint64)
+    elif dtype.kind == "f":
+        dtype_max = np.dtype(np.float64)
+    return dtype_max
+
+
+def _na_ok_dtype(dtype: DtypeObj) -> bool:
+    if needs_i8_conversion(dtype):
+        return False
+    return not issubclass(dtype.type, np.integer)
+
+
+def _wrap_results(result, dtype: np.dtype, fill_value=None):
+    """wrap our results if needed"""
+    if result is NaT:
+        pass
+
+    elif dtype.kind == "M":
+        if fill_value is None:
+            # GH#24293
+            fill_value = iNaT
+        if not isinstance(result, np.ndarray):
+            assert not isna(fill_value), "Expected non-null fill_value"
+            if result == fill_value:
+                result = np.nan
+
+            if isna(result):
+                result = np.datetime64("NaT", "ns").astype(dtype)
+            else:
+                result = np.int64(result).view(dtype)
+            # retain original unit
+            result = result.astype(dtype, copy=False)
+        else:
+            # If we have float dtype, taking a view will give the wrong result
+            result = result.astype(dtype)
+    elif dtype.kind == "m":
+        if not isinstance(result, np.ndarray):
+            if result == fill_value or np.isnan(result):
+                result = np.timedelta64("NaT").astype(dtype)
+
+            elif np.fabs(result) > lib.i8max:
+                # raise if we have a timedelta64[ns] which is too large
+                raise ValueError("overflow in timedelta operation")
+            else:
+                # return a timedelta64 with the original unit
+                result = np.int64(result).astype(dtype, copy=False)
+
+        else:
+            result = result.astype("m8[ns]").view(dtype)
+
+    return result
+
+
+def _datetimelike_compat(func: F) -> F:
+    """
+    If we have datetime64 or timedelta64 values, ensure we have a correct
+    mask before calling the wrapped function, then cast back afterwards.
+    """
+
+    @functools.wraps(func)
+    def new_func(
+        values: np.ndarray,
+        *,
+        axis: AxisInt | None = None,
+        skipna: bool = True,
+        mask: npt.NDArray[np.bool_] | None = None,
+        **kwargs,
+    ):
+        orig_values = values
+
+        datetimelike = values.dtype.kind in "mM"
+        if datetimelike and mask is None:
+            mask = isna(values)
+
+        result = func(values, axis=axis, skipna=skipna, mask=mask, **kwargs)
+
+        if datetimelike:
+            result = _wrap_results(result, orig_values.dtype, fill_value=iNaT)
+            if not skipna:
+                assert mask is not None  # checked above
+                result = _mask_datetimelike_result(result, axis, mask, orig_values)
+
+        return result
+
+    return cast(F, new_func)
+
+
+def _na_for_min_count(values: np.ndarray, axis: AxisInt | None) -> Scalar | np.ndarray:
+    """
+    Return the missing value for `values`.
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int or None
+        axis for the reduction, required if values.ndim > 1.
+
+    Returns
+    -------
+    result : scalar or ndarray
+        For 1-D values, returns a scalar of the correct missing type.
+        For 2-D values, returns a 1-D array where each element is missing.
+    """
+    # we either return np.nan or pd.NaT
+    if values.dtype.kind in "iufcb":
+        values = values.astype("float64")
+    fill_value = na_value_for_dtype(values.dtype)
+
+    if values.ndim == 1:
+        return fill_value
+    elif axis is None:
+        return fill_value
+    else:
+        result_shape = values.shape[:axis] + values.shape[axis + 1 :]
+
+        return np.full(result_shape, fill_value, dtype=values.dtype)
+
+
+def maybe_operate_rowwise(func: F) -> F:
+    """
+    NumPy operations on C-contiguous ndarrays with axis=1 can be
+    very slow if axis 1 >> axis 0.
+    Operate row-by-row and concatenate the results.
+    """
+
+    @functools.wraps(func)
+    def newfunc(values: np.ndarray, *, axis: AxisInt | None = None, **kwargs):
+        if (
+            axis == 1
+            and values.ndim == 2
+            and values.flags["C_CONTIGUOUS"]
+            # only takes this path for wide arrays (long dataframes), for threshold see
+            # https://github.com/pandas-dev/pandas/pull/43311#issuecomment-974891737
+            and (values.shape[1] / 1000) > values.shape[0]
+            and values.dtype != object
+            and values.dtype != bool
+        ):
+            arrs = list(values)
+            if kwargs.get("mask") is not None:
+                mask = kwargs.pop("mask")
+                results = [
+                    func(arrs[i], mask=mask[i], **kwargs) for i in range(len(arrs))
+                ]
+            else:
+                results = [func(x, **kwargs) for x in arrs]
+            return np.array(results)
+
+        return func(values, axis=axis, **kwargs)
+
+    return cast(F, newfunc)
+
+
+def nanany(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> bool:
+    """
+    Check if any elements along an axis evaluate to True.
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : bool
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 2])
+    >>> nanops.nanany(s.values)
+    True
+
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([np.nan])
+    >>> nanops.nanany(s.values)
+    False
+    """
+    if values.dtype.kind in "iub" and mask is None:
+        # GH#26032 fastpath
+        # error: Incompatible return value type (got "Union[bool_, ndarray]",
+        # expected "bool")
+        return values.any(axis)  # type: ignore[return-value]
+
+    if values.dtype.kind == "M":
+        # GH#34479
+        warnings.warn(
+            "'any' with datetime64 dtypes is deprecated and will raise in a "
+            "future version. Use (obj != pd.Timestamp(0)).any() instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    values, _ = _get_values(values, skipna, fill_value=False, mask=mask)
+
+    # For object type, any won't necessarily return
+    # boolean values (numpy/numpy#4352)
+    if values.dtype == object:
+        values = values.astype(bool)
+
+    # error: Incompatible return value type (got "Union[bool_, ndarray]", expected
+    # "bool")
+    return values.any(axis)  # type: ignore[return-value]
+
+
+def nanall(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> bool:
+    """
+    Check if all elements along an axis evaluate to True.
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : bool
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 2, np.nan])
+    >>> nanops.nanall(s.values)
+    True
+
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 0])
+    >>> nanops.nanall(s.values)
+    False
+    """
+    if values.dtype.kind in "iub" and mask is None:
+        # GH#26032 fastpath
+        # error: Incompatible return value type (got "Union[bool_, ndarray]",
+        # expected "bool")
+        return values.all(axis)  # type: ignore[return-value]
+
+    if values.dtype.kind == "M":
+        # GH#34479
+        warnings.warn(
+            "'all' with datetime64 dtypes is deprecated and will raise in a "
+            "future version. Use (obj != pd.Timestamp(0)).all() instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    values, _ = _get_values(values, skipna, fill_value=True, mask=mask)
+
+    # For object type, all won't necessarily return
+    # boolean values (numpy/numpy#4352)
+    if values.dtype == object:
+        values = values.astype(bool)
+
+    # error: Incompatible return value type (got "Union[bool_, ndarray]", expected
+    # "bool")
+    return values.all(axis)  # type: ignore[return-value]
+
+
+@disallow("M8")
+@_datetimelike_compat
+@maybe_operate_rowwise
+def nansum(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    min_count: int = 0,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Sum the elements along an axis ignoring NaNs
+
+    Parameters
+    ----------
+    values : ndarray[dtype]
+    axis : int, optional
+    skipna : bool, default True
+    min_count: int, default 0
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : dtype
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 2, np.nan])
+    >>> nanops.nansum(s.values)
+    3.0
+    """
+    dtype = values.dtype
+    values, mask = _get_values(values, skipna, fill_value=0, mask=mask)
+    dtype_sum = _get_dtype_max(dtype)
+    if dtype.kind == "f":
+        dtype_sum = dtype
+    elif dtype.kind == "m":
+        dtype_sum = np.dtype(np.float64)
+
+    the_sum = values.sum(axis, dtype=dtype_sum)
+    the_sum = _maybe_null_out(the_sum, axis, mask, values.shape, min_count=min_count)
+
+    return the_sum
+
+
+def _mask_datetimelike_result(
+    result: np.ndarray | np.datetime64 | np.timedelta64,
+    axis: AxisInt | None,
+    mask: npt.NDArray[np.bool_],
+    orig_values: np.ndarray,
+) -> np.ndarray | np.datetime64 | np.timedelta64 | NaTType:
+    if isinstance(result, np.ndarray):
+        # we need to apply the mask
+        result = result.astype("i8").view(orig_values.dtype)
+        axis_mask = mask.any(axis=axis)
+        # error: Unsupported target for indexed assignment ("Union[ndarray[Any, Any],
+        # datetime64, timedelta64]")
+        result[axis_mask] = iNaT  # type: ignore[index]
+    else:
+        if mask.any():
+            return np.int64(iNaT).view(orig_values.dtype)
+    return result
+
+
+@bottleneck_switch()
+@_datetimelike_compat
+def nanmean(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Compute the mean of the element along an axis ignoring NaNs
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    float
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 2, np.nan])
+    >>> nanops.nanmean(s.values)
+    1.5
+    """
+    dtype = values.dtype
+    values, mask = _get_values(values, skipna, fill_value=0, mask=mask)
+    dtype_sum = _get_dtype_max(dtype)
+    dtype_count = np.dtype(np.float64)
+
+    # not using needs_i8_conversion because that includes period
+    if dtype.kind in "mM":
+        dtype_sum = np.dtype(np.float64)
+    elif dtype.kind in "iu":
+        dtype_sum = np.dtype(np.float64)
+    elif dtype.kind == "f":
+        dtype_sum = dtype
+        dtype_count = dtype
+
+    count = _get_counts(values.shape, mask, axis, dtype=dtype_count)
+    the_sum = values.sum(axis, dtype=dtype_sum)
+    the_sum = _ensure_numeric(the_sum)
+
+    if axis is not None and getattr(the_sum, "ndim", False):
+        count = cast(np.ndarray, count)
+        with np.errstate(all="ignore"):
+            # suppress division by zero warnings
+            the_mean = the_sum / count
+        ct_mask = count == 0
+        if ct_mask.any():
+            the_mean[ct_mask] = np.nan
+    else:
+        the_mean = the_sum / count if count > 0 else np.nan
+
+    return the_mean
+
+
+@bottleneck_switch()
+def nanmedian(values, *, axis: AxisInt | None = None, skipna: bool = True, mask=None):
+    """
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 2, 2])
+    >>> nanops.nanmedian(s.values)
+    2.0
+    """
+    # for floats without mask, the data already uses NaN as missing value
+    # indicator, and `mask` will be calculated from that below -> in those
+    # cases we never need to set NaN to the masked values
+    using_nan_sentinel = values.dtype.kind == "f" and mask is None
+
+    def get_median(x, _mask=None):
+        if _mask is None:
+            _mask = notna(x)
+        else:
+            _mask = ~_mask
+        if not skipna and not _mask.all():
+            return np.nan
+        with warnings.catch_warnings():
+            # Suppress RuntimeWarning about All-NaN slice
+            warnings.filterwarnings(
+                "ignore", "All-NaN slice encountered", RuntimeWarning
+            )
+            res = np.nanmedian(x[_mask])
+        return res
+
+    dtype = values.dtype
+    values, mask = _get_values(values, skipna, mask=mask, fill_value=None)
+    if values.dtype.kind != "f":
+        if values.dtype == object:
+            # GH#34671 avoid casting strings to numeric
+            inferred = lib.infer_dtype(values)
+            if inferred in ["string", "mixed"]:
+                raise TypeError(f"Cannot convert {values} to numeric")
+        try:
+            values = values.astype("f8")
+        except ValueError as err:
+            # e.g. "could not convert string to float: 'a'"
+            raise TypeError(str(err)) from err
+    if not using_nan_sentinel and mask is not None:
+        if not values.flags.writeable:
+            values = values.copy()
+        values[mask] = np.nan
+
+    notempty = values.size
+
+    # an array from a frame
+    if values.ndim > 1 and axis is not None:
+        # there's a non-empty array to apply over otherwise numpy raises
+        if notempty:
+            if not skipna:
+                res = np.apply_along_axis(get_median, axis, values)
+
+            else:
+                # fastpath for the skipna case
+                with warnings.catch_warnings():
+                    # Suppress RuntimeWarning about All-NaN slice
+                    warnings.filterwarnings(
+                        "ignore", "All-NaN slice encountered", RuntimeWarning
+                    )
+                    if (values.shape[1] == 1 and axis == 0) or (
+                        values.shape[0] == 1 and axis == 1
+                    ):
+                        # GH52788: fastpath when squeezable, nanmedian for 2D array slow
+                        res = np.nanmedian(np.squeeze(values), keepdims=True)
+                    else:
+                        res = np.nanmedian(values, axis=axis)
+
+        else:
+            # must return the correct shape, but median is not defined for the
+            # empty set so return nans of shape "everything but the passed axis"
+            # since "axis" is where the reduction would occur if we had a nonempty
+            # array
+            res = _get_empty_reduction_result(values.shape, axis)
+
+    else:
+        # otherwise return a scalar value
+        res = get_median(values, mask) if notempty else np.nan
+    return _wrap_results(res, dtype)
+
+
+def _get_empty_reduction_result(
+    shape: Shape,
+    axis: AxisInt,
+) -> np.ndarray:
+    """
+    The result from a reduction on an empty ndarray.
+
+    Parameters
+    ----------
+    shape : Tuple[int, ...]
+    axis : int
+
+    Returns
+    -------
+    np.ndarray
+    """
+    shp = np.array(shape)
+    dims = np.arange(len(shape))
+    ret = np.empty(shp[dims != axis], dtype=np.float64)
+    ret.fill(np.nan)
+    return ret
+
+
+def _get_counts_nanvar(
+    values_shape: Shape,
+    mask: npt.NDArray[np.bool_] | None,
+    axis: AxisInt | None,
+    ddof: int,
+    dtype: np.dtype = np.dtype(np.float64),
+) -> tuple[float | np.ndarray, float | np.ndarray]:
+    """
+    Get the count of non-null values along an axis, accounting
+    for degrees of freedom.
+
+    Parameters
+    ----------
+    values_shape : Tuple[int, ...]
+        shape tuple from values ndarray, used if mask is None
+    mask : Optional[ndarray[bool]]
+        locations in values that should be considered missing
+    axis : Optional[int]
+        axis to count along
+    ddof : int
+        degrees of freedom
+    dtype : type, optional
+        type to use for count
+
+    Returns
+    -------
+    count : int, np.nan or np.ndarray
+    d : int, np.nan or np.ndarray
+    """
+    count = _get_counts(values_shape, mask, axis, dtype=dtype)
+    d = count - dtype.type(ddof)
+
+    # always return NaN, never inf
+    if is_float(count):
+        if count <= ddof:
+            # error: Incompatible types in assignment (expression has type
+            # "float", variable has type "Union[floating[Any], ndarray[Any,
+            # dtype[floating[Any]]]]")
+            count = np.nan  # type: ignore[assignment]
+            d = np.nan
+    else:
+        # count is not narrowed by is_float check
+        count = cast(np.ndarray, count)
+        mask = count <= ddof
+        if mask.any():
+            np.putmask(d, mask, np.nan)
+            np.putmask(count, mask, np.nan)
+    return count, d
+
+
+@bottleneck_switch(ddof=1)
+def nanstd(
+    values,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    ddof: int = 1,
+    mask=None,
+):
+    """
+    Compute the standard deviation along given axis while ignoring NaNs
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    ddof : int, default 1
+        Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
+        where N represents the number of elements.
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 2, 3])
+    >>> nanops.nanstd(s.values)
+    1.0
+    """
+    if values.dtype == "M8[ns]":
+        values = values.view("m8[ns]")
+
+    orig_dtype = values.dtype
+    values, mask = _get_values(values, skipna, mask=mask)
+
+    result = np.sqrt(nanvar(values, axis=axis, skipna=skipna, ddof=ddof, mask=mask))
+    return _wrap_results(result, orig_dtype)
+
+
+@disallow("M8", "m8")
+@bottleneck_switch(ddof=1)
+def nanvar(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    ddof: int = 1,
+    mask=None,
+):
+    """
+    Compute the variance along given axis while ignoring NaNs
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    ddof : int, default 1
+        Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
+        where N represents the number of elements.
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 2, 3])
+    >>> nanops.nanvar(s.values)
+    1.0
+    """
+    dtype = values.dtype
+    mask = _maybe_get_mask(values, skipna, mask)
+    if dtype.kind in "iu":
+        values = values.astype("f8")
+        if mask is not None:
+            values[mask] = np.nan
+
+    if values.dtype.kind == "f":
+        count, d = _get_counts_nanvar(values.shape, mask, axis, ddof, values.dtype)
+    else:
+        count, d = _get_counts_nanvar(values.shape, mask, axis, ddof)
+
+    if skipna and mask is not None:
+        values = values.copy()
+        np.putmask(values, mask, 0)
+
+    # xref GH10242
+    # Compute variance via two-pass algorithm, which is stable against
+    # cancellation errors and relatively accurate for small numbers of
+    # observations.
+    #
+    # See https://en.wikipedia.org/wiki/Algorithms_for_calculating_variance
+    avg = _ensure_numeric(values.sum(axis=axis, dtype=np.float64)) / count
+    if axis is not None:
+        avg = np.expand_dims(avg, axis)
+    sqr = _ensure_numeric((avg - values) ** 2)
+    if mask is not None:
+        np.putmask(sqr, mask, 0)
+    result = sqr.sum(axis=axis, dtype=np.float64) / d
+
+    # Return variance as np.float64 (the datatype used in the accumulator),
+    # unless we were dealing with a float array, in which case use the same
+    # precision as the original values array.
+    if dtype.kind == "f":
+        result = result.astype(dtype, copy=False)
+    return result
+
+
+@disallow("M8", "m8")
+def nansem(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    ddof: int = 1,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Compute the standard error in the mean along given axis while ignoring NaNs
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    ddof : int, default 1
+        Delta Degrees of Freedom. The divisor used in calculations is N - ddof,
+        where N represents the number of elements.
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float64
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 2, 3])
+    >>> nanops.nansem(s.values)
+     0.5773502691896258
+    """
+    # This checks if non-numeric-like data is passed with numeric_only=False
+    # and raises a TypeError otherwise
+    nanvar(values, axis=axis, skipna=skipna, ddof=ddof, mask=mask)
+
+    mask = _maybe_get_mask(values, skipna, mask)
+    if values.dtype.kind != "f":
+        values = values.astype("f8")
+
+    if not skipna and mask is not None and mask.any():
+        return np.nan
+
+    count, _ = _get_counts_nanvar(values.shape, mask, axis, ddof, values.dtype)
+    var = nanvar(values, axis=axis, skipna=skipna, ddof=ddof, mask=mask)
+
+    return np.sqrt(var) / np.sqrt(count)
+
+
+def _nanminmax(meth, fill_value_typ):
+    @bottleneck_switch(name=f"nan{meth}")
+    @_datetimelike_compat
+    def reduction(
+        values: np.ndarray,
+        *,
+        axis: AxisInt | None = None,
+        skipna: bool = True,
+        mask: npt.NDArray[np.bool_] | None = None,
+    ):
+        if values.size == 0:
+            return _na_for_min_count(values, axis)
+
+        values, mask = _get_values(
+            values, skipna, fill_value_typ=fill_value_typ, mask=mask
+        )
+        result = getattr(values, meth)(axis)
+        result = _maybe_null_out(result, axis, mask, values.shape)
+        return result
+
+    return reduction
+
+
+nanmin = _nanminmax("min", fill_value_typ="+inf")
+nanmax = _nanminmax("max", fill_value_typ="-inf")
+
+
+def nanargmax(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> int | np.ndarray:
+    """
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : int or ndarray[int]
+        The index/indices  of max value in specified axis or -1 in the NA case
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> arr = np.array([1, 2, 3, np.nan, 4])
+    >>> nanops.nanargmax(arr)
+    4
+
+    >>> arr = np.array(range(12), dtype=np.float64).reshape(4, 3)
+    >>> arr[2:, 2] = np.nan
+    >>> arr
+    array([[ 0.,  1.,  2.],
+           [ 3.,  4.,  5.],
+           [ 6.,  7., nan],
+           [ 9., 10., nan]])
+    >>> nanops.nanargmax(arr, axis=1)
+    array([2, 2, 1, 1])
+    """
+    values, mask = _get_values(values, True, fill_value_typ="-inf", mask=mask)
+    result = values.argmax(axis)
+    # error: Argument 1 to "_maybe_arg_null_out" has incompatible type "Any |
+    # signedinteger[Any]"; expected "ndarray[Any, Any]"
+    result = _maybe_arg_null_out(result, axis, mask, skipna)  # type: ignore[arg-type]
+    return result
+
+
+def nanargmin(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> int | np.ndarray:
+    """
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : int or ndarray[int]
+        The index/indices of min value in specified axis or -1 in the NA case
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> arr = np.array([1, 2, 3, np.nan, 4])
+    >>> nanops.nanargmin(arr)
+    0
+
+    >>> arr = np.array(range(12), dtype=np.float64).reshape(4, 3)
+    >>> arr[2:, 0] = np.nan
+    >>> arr
+    array([[ 0.,  1.,  2.],
+           [ 3.,  4.,  5.],
+           [nan,  7.,  8.],
+           [nan, 10., 11.]])
+    >>> nanops.nanargmin(arr, axis=1)
+    array([0, 0, 1, 1])
+    """
+    values, mask = _get_values(values, True, fill_value_typ="+inf", mask=mask)
+    result = values.argmin(axis)
+    # error: Argument 1 to "_maybe_arg_null_out" has incompatible type "Any |
+    # signedinteger[Any]"; expected "ndarray[Any, Any]"
+    result = _maybe_arg_null_out(result, axis, mask, skipna)  # type: ignore[arg-type]
+    return result
+
+
+@disallow("M8", "m8")
+@maybe_operate_rowwise
+def nanskew(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Compute the sample skewness.
+
+    The statistic computed here is the adjusted Fisher-Pearson standardized
+    moment coefficient G1. The algorithm computes this coefficient directly
+    from the second and third central moment.
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float64
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 1, 2])
+    >>> nanops.nanskew(s.values)
+    1.7320508075688787
+    """
+    mask = _maybe_get_mask(values, skipna, mask)
+    if values.dtype.kind != "f":
+        values = values.astype("f8")
+        count = _get_counts(values.shape, mask, axis)
+    else:
+        count = _get_counts(values.shape, mask, axis, dtype=values.dtype)
+
+    if skipna and mask is not None:
+        values = values.copy()
+        np.putmask(values, mask, 0)
+    elif not skipna and mask is not None and mask.any():
+        return np.nan
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        mean = values.sum(axis, dtype=np.float64) / count
+    if axis is not None:
+        mean = np.expand_dims(mean, axis)
+
+    adjusted = values - mean
+    if skipna and mask is not None:
+        np.putmask(adjusted, mask, 0)
+    adjusted2 = adjusted**2
+    adjusted3 = adjusted2 * adjusted
+    m2 = adjusted2.sum(axis, dtype=np.float64)
+    m3 = adjusted3.sum(axis, dtype=np.float64)
+
+    # floating point error
+    #
+    # #18044 in _libs/windows.pyx calc_skew follow this behavior
+    # to fix the fperr to treat m2 <1e-14 as zero
+    m2 = _zero_out_fperr(m2)
+    m3 = _zero_out_fperr(m3)
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        result = (count * (count - 1) ** 0.5 / (count - 2)) * (m3 / m2**1.5)
+
+    dtype = values.dtype
+    if dtype.kind == "f":
+        result = result.astype(dtype, copy=False)
+
+    if isinstance(result, np.ndarray):
+        result = np.where(m2 == 0, 0, result)
+        result[count < 3] = np.nan
+    else:
+        result = dtype.type(0) if m2 == 0 else result
+        if count < 3:
+            return np.nan
+
+    return result
+
+
+@disallow("M8", "m8")
+@maybe_operate_rowwise
+def nankurt(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Compute the sample excess kurtosis
+
+    The statistic computed here is the adjusted Fisher-Pearson standardized
+    moment coefficient G2, computed directly from the second and fourth
+    central moment.
+
+    Parameters
+    ----------
+    values : ndarray
+    axis : int, optional
+    skipna : bool, default True
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    result : float64
+        Unless input is a float array, in which case use the same
+        precision as the input array.
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, np.nan, 1, 3, 2])
+    >>> nanops.nankurt(s.values)
+    -1.2892561983471076
+    """
+    mask = _maybe_get_mask(values, skipna, mask)
+    if values.dtype.kind != "f":
+        values = values.astype("f8")
+        count = _get_counts(values.shape, mask, axis)
+    else:
+        count = _get_counts(values.shape, mask, axis, dtype=values.dtype)
+
+    if skipna and mask is not None:
+        values = values.copy()
+        np.putmask(values, mask, 0)
+    elif not skipna and mask is not None and mask.any():
+        return np.nan
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        mean = values.sum(axis, dtype=np.float64) / count
+    if axis is not None:
+        mean = np.expand_dims(mean, axis)
+
+    adjusted = values - mean
+    if skipna and mask is not None:
+        np.putmask(adjusted, mask, 0)
+    adjusted2 = adjusted**2
+    adjusted4 = adjusted2**2
+    m2 = adjusted2.sum(axis, dtype=np.float64)
+    m4 = adjusted4.sum(axis, dtype=np.float64)
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        adj = 3 * (count - 1) ** 2 / ((count - 2) * (count - 3))
+        numerator = count * (count + 1) * (count - 1) * m4
+        denominator = (count - 2) * (count - 3) * m2**2
+
+    # floating point error
+    #
+    # #18044 in _libs/windows.pyx calc_kurt follow this behavior
+    # to fix the fperr to treat denom <1e-14 as zero
+    numerator = _zero_out_fperr(numerator)
+    denominator = _zero_out_fperr(denominator)
+
+    if not isinstance(denominator, np.ndarray):
+        # if ``denom`` is a scalar, check these corner cases first before
+        # doing division
+        if count < 4:
+            return np.nan
+        if denominator == 0:
+            return values.dtype.type(0)
+
+    with np.errstate(invalid="ignore", divide="ignore"):
+        result = numerator / denominator - adj
+
+    dtype = values.dtype
+    if dtype.kind == "f":
+        result = result.astype(dtype, copy=False)
+
+    if isinstance(result, np.ndarray):
+        result = np.where(denominator == 0, 0, result)
+        result[count < 4] = np.nan
+
+    return result
+
+
+@disallow("M8", "m8")
+@maybe_operate_rowwise
+def nanprod(
+    values: np.ndarray,
+    *,
+    axis: AxisInt | None = None,
+    skipna: bool = True,
+    min_count: int = 0,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> float:
+    """
+    Parameters
+    ----------
+    values : ndarray[dtype]
+    axis : int, optional
+    skipna : bool, default True
+    min_count: int, default 0
+    mask : ndarray[bool], optional
+        nan-mask if known
+
+    Returns
+    -------
+    Dtype
+        The product of all elements on a given axis. ( NaNs are treated as 1)
+
+    Examples
+    --------
+    >>> from pandas.core import nanops
+    >>> s = pd.Series([1, 2, 3, np.nan])
+    >>> nanops.nanprod(s.values)
+    6.0
+    """
+    mask = _maybe_get_mask(values, skipna, mask)
+
+    if skipna and mask is not None:
+        values = values.copy()
+        values[mask] = 1
+    result = values.prod(axis)
+    # error: Incompatible return value type (got "Union[ndarray, float]", expected
+    # "float")
+    return _maybe_null_out(  # type: ignore[return-value]
+        result, axis, mask, values.shape, min_count=min_count
+    )
+
+
+def _maybe_arg_null_out(
+    result: np.ndarray,
+    axis: AxisInt | None,
+    mask: npt.NDArray[np.bool_] | None,
+    skipna: bool,
+) -> np.ndarray | int:
+    # helper function for nanargmin/nanargmax
+    if mask is None:
+        return result
+
+    if axis is None or not getattr(result, "ndim", False):
+        if skipna:
+            if mask.all():
+                return -1
+        else:
+            if mask.any():
+                return -1
+    else:
+        if skipna:
+            na_mask = mask.all(axis)
+        else:
+            na_mask = mask.any(axis)
+        if na_mask.any():
+            result[na_mask] = -1
+    return result
+
+
+def _get_counts(
+    values_shape: Shape,
+    mask: npt.NDArray[np.bool_] | None,
+    axis: AxisInt | None,
+    dtype: np.dtype[np.floating] = np.dtype(np.float64),
+) -> np.floating | npt.NDArray[np.floating]:
+    """
+    Get the count of non-null values along an axis
+
+    Parameters
+    ----------
+    values_shape : tuple of int
+        shape tuple from values ndarray, used if mask is None
+    mask : Optional[ndarray[bool]]
+        locations in values that should be considered missing
+    axis : Optional[int]
+        axis to count along
+    dtype : type, optional
+        type to use for count
+
+    Returns
+    -------
+    count : scalar or array
+    """
+    if axis is None:
+        if mask is not None:
+            n = mask.size - mask.sum()
+        else:
+            n = np.prod(values_shape)
+        return dtype.type(n)
+
+    if mask is not None:
+        count = mask.shape[axis] - mask.sum(axis)
+    else:
+        count = values_shape[axis]
+
+    if is_integer(count):
+        return dtype.type(count)
+    return count.astype(dtype, copy=False)
+
+
+def _maybe_null_out(
+    result: np.ndarray | float | NaTType,
+    axis: AxisInt | None,
+    mask: npt.NDArray[np.bool_] | None,
+    shape: tuple[int, ...],
+    min_count: int = 1,
+) -> np.ndarray | float | NaTType:
+    """
+    Returns
+    -------
+    Dtype
+        The product of all elements on a given axis. ( NaNs are treated as 1)
+    """
+    if mask is None and min_count == 0:
+        # nothing to check; short-circuit
+        return result
+
+    if axis is not None and isinstance(result, np.ndarray):
+        if mask is not None:
+            null_mask = (mask.shape[axis] - mask.sum(axis) - min_count) < 0
+        else:
+            # we have no nulls, kept mask=None in _maybe_get_mask
+            below_count = shape[axis] - min_count < 0
+            new_shape = shape[:axis] + shape[axis + 1 :]
+            null_mask = np.broadcast_to(below_count, new_shape)
+
+        if np.any(null_mask):
+            if is_numeric_dtype(result):
+                if np.iscomplexobj(result):
+                    result = result.astype("c16")
+                elif not is_float_dtype(result):
+                    result = result.astype("f8", copy=False)
+                result[null_mask] = np.nan
+            else:
+                # GH12941, use None to auto cast null
+                result[null_mask] = None
+    elif result is not NaT:
+        if check_below_min_count(shape, mask, min_count):
+            result_dtype = getattr(result, "dtype", None)
+            if is_float_dtype(result_dtype):
+                # error: Item "None" of "Optional[Any]" has no attribute "type"
+                result = result_dtype.type("nan")  # type: ignore[union-attr]
+            else:
+                result = np.nan
+
+    return result
+
+
+def check_below_min_count(
+    shape: tuple[int, ...], mask: npt.NDArray[np.bool_] | None, min_count: int
+) -> bool:
+    """
+    Check for the `min_count` keyword. Returns True if below `min_count` (when
+    missing value should be returned from the reduction).
+
+    Parameters
+    ----------
+    shape : tuple
+        The shape of the values (`values.shape`).
+    mask : ndarray[bool] or None
+        Boolean numpy array (typically of same shape as `shape`) or None.
+    min_count : int
+        Keyword passed through from sum/prod call.
+
+    Returns
+    -------
+    bool
+    """
+    if min_count > 0:
+        if mask is None:
+            # no missing values, only check size
+            non_nulls = np.prod(shape)
+        else:
+            non_nulls = mask.size - mask.sum()
+        if non_nulls < min_count:
+            return True
+    return False
+
+
+def _zero_out_fperr(arg):
+    # #18044 reference this behavior to fix rolling skew/kurt issue
+    if isinstance(arg, np.ndarray):
+        return np.where(np.abs(arg) < 1e-14, 0, arg)
+    else:
+        return arg.dtype.type(0) if np.abs(arg) < 1e-14 else arg
+
+
+@disallow("M8", "m8")
+def nancorr(
+    a: np.ndarray,
+    b: np.ndarray,
+    *,
+    method: CorrelationMethod = "pearson",
+    min_periods: int | None = None,
+) -> float:
+    """
+    a, b: ndarrays
+    """
+    if len(a) != len(b):
+        raise AssertionError("Operands to nancorr must have same size")
+
+    if min_periods is None:
+        min_periods = 1
+
+    valid = notna(a) & notna(b)
+    if not valid.all():
+        a = a[valid]
+        b = b[valid]
+
+    if len(a) < min_periods:
+        return np.nan
+
+    a = _ensure_numeric(a)
+    b = _ensure_numeric(b)
+
+    f = get_corr_func(method)
+    return f(a, b)
+
+
+def get_corr_func(
+    method: CorrelationMethod,
+) -> Callable[[np.ndarray, np.ndarray], float]:
+    if method == "kendall":
+        from scipy.stats import kendalltau
+
+        def func(a, b):
+            return kendalltau(a, b)[0]
+
+        return func
+    elif method == "spearman":
+        from scipy.stats import spearmanr
+
+        def func(a, b):
+            return spearmanr(a, b)[0]
+
+        return func
+    elif method == "pearson":
+
+        def func(a, b):
+            return np.corrcoef(a, b)[0, 1]
+
+        return func
+    elif callable(method):
+        return method
+
+    raise ValueError(
+        f"Unknown method '{method}', expected one of "
+        "'kendall', 'spearman', 'pearson', or callable"
+    )
+
+
+@disallow("M8", "m8")
+def nancov(
+    a: np.ndarray,
+    b: np.ndarray,
+    *,
+    min_periods: int | None = None,
+    ddof: int | None = 1,
+) -> float:
+    if len(a) != len(b):
+        raise AssertionError("Operands to nancov must have same size")
+
+    if min_periods is None:
+        min_periods = 1
+
+    valid = notna(a) & notna(b)
+    if not valid.all():
+        a = a[valid]
+        b = b[valid]
+
+    if len(a) < min_periods:
+        return np.nan
+
+    a = _ensure_numeric(a)
+    b = _ensure_numeric(b)
+
+    return np.cov(a, b, ddof=ddof)[0, 1]
+
+
+def _ensure_numeric(x):
+    if isinstance(x, np.ndarray):
+        if x.dtype.kind in "biu":
+            x = x.astype(np.float64)
+        elif x.dtype == object:
+            inferred = lib.infer_dtype(x)
+            if inferred in ["string", "mixed"]:
+                # GH#44008, GH#36703 avoid casting e.g. strings to numeric
+                raise TypeError(f"Could not convert {x} to numeric")
+            try:
+                x = x.astype(np.complex128)
+            except (TypeError, ValueError):
+                try:
+                    x = x.astype(np.float64)
+                except ValueError as err:
+                    # GH#29941 we get here with object arrays containing strs
+                    raise TypeError(f"Could not convert {x} to numeric") from err
+            else:
+                if not np.any(np.imag(x)):
+                    x = x.real
+    elif not (is_float(x) or is_integer(x) or is_complex(x)):
+        if isinstance(x, str):
+            # GH#44008, GH#36703 avoid casting e.g. strings to numeric
+            raise TypeError(f"Could not convert string '{x}' to numeric")
+        try:
+            x = float(x)
+        except (TypeError, ValueError):
+            # e.g. "1+1j" or "foo"
+            try:
+                x = complex(x)
+            except ValueError as err:
+                # e.g. "foo"
+                raise TypeError(f"Could not convert {x} to numeric") from err
+    return x
+
+
+def na_accum_func(values: ArrayLike, accum_func, *, skipna: bool) -> ArrayLike:
+    """
+    Cumulative function with skipna support.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+    accum_func : {np.cumprod, np.maximum.accumulate, np.cumsum, np.minimum.accumulate}
+    skipna : bool
+
+    Returns
+    -------
+    np.ndarray or ExtensionArray
+    """
+    mask_a, mask_b = {
+        np.cumprod: (1.0, np.nan),
+        np.maximum.accumulate: (-np.inf, np.nan),
+        np.cumsum: (0.0, np.nan),
+        np.minimum.accumulate: (np.inf, np.nan),
+    }[accum_func]
+
+    # This should go through ea interface
+    assert values.dtype.kind not in "mM"
+
+    # We will be applying this function to block values
+    if skipna and not issubclass(values.dtype.type, (np.integer, np.bool_)):
+        vals = values.copy()
+        mask = isna(vals)
+        vals[mask] = mask_a
+        result = accum_func(vals, axis=0)
+        result[mask] = mask_b
+    else:
+        result = accum_func(values, axis=0)
+
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..ae889a7fdbc24935c0884e8bbcdf56bde8946460
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/__init__.py
@@ -0,0 +1,93 @@
+"""
+Arithmetic operations for PandasObjects
+
+This is not a public API.
+"""
+from __future__ import annotations
+
+from pandas.core.ops.array_ops import (
+    arithmetic_op,
+    comp_method_OBJECT_ARRAY,
+    comparison_op,
+    fill_binop,
+    get_array_op,
+    logical_op,
+    maybe_prepare_scalar_for_op,
+)
+from pandas.core.ops.common import (
+    get_op_result_name,
+    unpack_zerodim_and_defer,
+)
+from pandas.core.ops.docstrings import make_flex_doc
+from pandas.core.ops.invalid import invalid_comparison
+from pandas.core.ops.mask_ops import (
+    kleene_and,
+    kleene_or,
+    kleene_xor,
+)
+from pandas.core.roperator import (
+    radd,
+    rand_,
+    rdiv,
+    rdivmod,
+    rfloordiv,
+    rmod,
+    rmul,
+    ror_,
+    rpow,
+    rsub,
+    rtruediv,
+    rxor,
+)
+
+# -----------------------------------------------------------------------------
+# constants
+ARITHMETIC_BINOPS: set[str] = {
+    "add",
+    "sub",
+    "mul",
+    "pow",
+    "mod",
+    "floordiv",
+    "truediv",
+    "divmod",
+    "radd",
+    "rsub",
+    "rmul",
+    "rpow",
+    "rmod",
+    "rfloordiv",
+    "rtruediv",
+    "rdivmod",
+}
+
+
+__all__ = [
+    "ARITHMETIC_BINOPS",
+    "arithmetic_op",
+    "comparison_op",
+    "comp_method_OBJECT_ARRAY",
+    "invalid_comparison",
+    "fill_binop",
+    "kleene_and",
+    "kleene_or",
+    "kleene_xor",
+    "logical_op",
+    "make_flex_doc",
+    "radd",
+    "rand_",
+    "rdiv",
+    "rdivmod",
+    "rfloordiv",
+    "rmod",
+    "rmul",
+    "ror_",
+    "rpow",
+    "rsub",
+    "rtruediv",
+    "rxor",
+    "unpack_zerodim_and_defer",
+    "get_op_result_name",
+    "maybe_prepare_scalar_for_op",
+    "get_array_op",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/array_ops.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/array_ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..4b762a359d321ea61660e78ec63d392f8436939d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/array_ops.py
@@ -0,0 +1,604 @@
+"""
+Functions for arithmetic and comparison operations on NumPy arrays and
+ExtensionArrays.
+"""
+from __future__ import annotations
+
+import datetime
+from functools import partial
+import operator
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    NaT,
+    Timedelta,
+    Timestamp,
+    lib,
+    ops as libops,
+)
+from pandas._libs.tslibs import (
+    BaseOffset,
+    get_supported_dtype,
+    is_supported_dtype,
+    is_unitless,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    construct_1d_object_array_from_listlike,
+    find_common_type,
+)
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_bool_dtype,
+    is_list_like,
+    is_numeric_v_string_like,
+    is_object_dtype,
+    is_scalar,
+)
+from pandas.core.dtypes.generic import (
+    ABCExtensionArray,
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    notna,
+)
+
+from pandas.core import roperator
+from pandas.core.computation import expressions
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+from pandas.core.ops import missing
+from pandas.core.ops.dispatch import should_extension_dispatch
+from pandas.core.ops.invalid import invalid_comparison
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        Shape,
+    )
+
+# -----------------------------------------------------------------------------
+# Masking NA values and fallbacks for operations numpy does not support
+
+
+def fill_binop(left, right, fill_value):
+    """
+    If a non-None fill_value is given, replace null entries in left and right
+    with this value, but only in positions where _one_ of left/right is null,
+    not both.
+
+    Parameters
+    ----------
+    left : array-like
+    right : array-like
+    fill_value : object
+
+    Returns
+    -------
+    left : array-like
+    right : array-like
+
+    Notes
+    -----
+    Makes copies if fill_value is not None and NAs are present.
+    """
+    if fill_value is not None:
+        left_mask = isna(left)
+        right_mask = isna(right)
+
+        # one but not both
+        mask = left_mask ^ right_mask
+
+        if left_mask.any():
+            # Avoid making a copy if we can
+            left = left.copy()
+            left[left_mask & mask] = fill_value
+
+        if right_mask.any():
+            # Avoid making a copy if we can
+            right = right.copy()
+            right[right_mask & mask] = fill_value
+
+    return left, right
+
+
+def comp_method_OBJECT_ARRAY(op, x, y):
+    if isinstance(y, list):
+        # e.g. test_tuple_categories
+        y = construct_1d_object_array_from_listlike(y)
+
+    if isinstance(y, (np.ndarray, ABCSeries, ABCIndex)):
+        if not is_object_dtype(y.dtype):
+            y = y.astype(np.object_)
+
+        if isinstance(y, (ABCSeries, ABCIndex)):
+            y = y._values
+
+        if x.shape != y.shape:
+            raise ValueError("Shapes must match", x.shape, y.shape)
+        result = libops.vec_compare(x.ravel(), y.ravel(), op)
+    else:
+        result = libops.scalar_compare(x.ravel(), y, op)
+    return result.reshape(x.shape)
+
+
+def _masked_arith_op(x: np.ndarray, y, op):
+    """
+    If the given arithmetic operation fails, attempt it again on
+    only the non-null elements of the input array(s).
+
+    Parameters
+    ----------
+    x : np.ndarray
+    y : np.ndarray, Series, Index
+    op : binary operator
+    """
+    # For Series `x` is 1D so ravel() is a no-op; calling it anyway makes
+    # the logic valid for both Series and DataFrame ops.
+    xrav = x.ravel()
+
+    if isinstance(y, np.ndarray):
+        dtype = find_common_type([x.dtype, y.dtype])
+        result = np.empty(x.size, dtype=dtype)
+
+        if len(x) != len(y):
+            raise ValueError(x.shape, y.shape)
+        ymask = notna(y)
+
+        # NB: ravel() is only safe since y is ndarray; for e.g. PeriodIndex
+        #  we would get int64 dtype, see GH#19956
+        yrav = y.ravel()
+        mask = notna(xrav) & ymask.ravel()
+
+        # See GH#5284, GH#5035, GH#19448 for historical reference
+        if mask.any():
+            result[mask] = op(xrav[mask], yrav[mask])
+
+    else:
+        if not is_scalar(y):
+            raise TypeError(
+                f"Cannot broadcast np.ndarray with operand of type { type(y) }"
+            )
+
+        # mask is only meaningful for x
+        result = np.empty(x.size, dtype=x.dtype)
+        mask = notna(xrav)
+
+        # 1 ** np.nan is 1. So we have to unmask those.
+        if op is pow:
+            mask = np.where(x == 1, False, mask)
+        elif op is roperator.rpow:
+            mask = np.where(y == 1, False, mask)
+
+        if mask.any():
+            result[mask] = op(xrav[mask], y)
+
+    np.putmask(result, ~mask, np.nan)
+    result = result.reshape(x.shape)  # 2D compat
+    return result
+
+
+def _na_arithmetic_op(left: np.ndarray, right, op, is_cmp: bool = False):
+    """
+    Return the result of evaluating op on the passed in values.
+
+    If native types are not compatible, try coercion to object dtype.
+
+    Parameters
+    ----------
+    left : np.ndarray
+    right : np.ndarray or scalar
+        Excludes DataFrame, Series, Index, ExtensionArray.
+    is_cmp : bool, default False
+        If this a comparison operation.
+
+    Returns
+    -------
+    array-like
+
+    Raises
+    ------
+    TypeError : invalid operation
+    """
+    if isinstance(right, str):
+        # can never use numexpr
+        func = op
+    else:
+        func = partial(expressions.evaluate, op)
+
+    try:
+        result = func(left, right)
+    except TypeError:
+        if not is_cmp and (
+            left.dtype == object or getattr(right, "dtype", None) == object
+        ):
+            # For object dtype, fallback to a masked operation (only operating
+            #  on the non-missing values)
+            # Don't do this for comparisons, as that will handle complex numbers
+            #  incorrectly, see GH#32047
+            result = _masked_arith_op(left, right, op)
+        else:
+            raise
+
+    if is_cmp and (is_scalar(result) or result is NotImplemented):
+        # numpy returned a scalar instead of operating element-wise
+        # e.g. numeric array vs str
+        # TODO: can remove this after dropping some future numpy version?
+        return invalid_comparison(left, right, op)
+
+    return missing.dispatch_fill_zeros(op, left, right, result)
+
+
+def arithmetic_op(left: ArrayLike, right: Any, op):
+    """
+    Evaluate an arithmetic operation `+`, `-`, `*`, `/`, `//`, `%`, `**`, ...
+
+    Note: the caller is responsible for ensuring that numpy warnings are
+    suppressed (with np.errstate(all="ignore")) if needed.
+
+    Parameters
+    ----------
+    left : np.ndarray or ExtensionArray
+    right : object
+        Cannot be a DataFrame or Index.  Series is *not* excluded.
+    op : {operator.add, operator.sub, ...}
+        Or one of the reversed variants from roperator.
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+        Or a 2-tuple of these in the case of divmod or rdivmod.
+    """
+    # NB: We assume that extract_array and ensure_wrapped_if_datetimelike
+    #  have already been called on `left` and `right`,
+    #  and `maybe_prepare_scalar_for_op` has already been called on `right`
+    # We need to special-case datetime64/timedelta64 dtypes (e.g. because numpy
+    # casts integer dtypes to timedelta64 when operating with timedelta64 - GH#22390)
+
+    if (
+        should_extension_dispatch(left, right)
+        or isinstance(right, (Timedelta, BaseOffset, Timestamp))
+        or right is NaT
+    ):
+        # Timedelta/Timestamp and other custom scalars are included in the check
+        # because numexpr will fail on it, see GH#31457
+        res_values = op(left, right)
+    else:
+        # TODO we should handle EAs consistently and move this check before the if/else
+        # (https://github.com/pandas-dev/pandas/issues/41165)
+        # error: Argument 2 to "_bool_arith_check" has incompatible type
+        # "Union[ExtensionArray, ndarray[Any, Any]]"; expected "ndarray[Any, Any]"
+        _bool_arith_check(op, left, right)  # type: ignore[arg-type]
+
+        # error: Argument 1 to "_na_arithmetic_op" has incompatible type
+        # "Union[ExtensionArray, ndarray[Any, Any]]"; expected "ndarray[Any, Any]"
+        res_values = _na_arithmetic_op(left, right, op)  # type: ignore[arg-type]
+
+    return res_values
+
+
+def comparison_op(left: ArrayLike, right: Any, op) -> ArrayLike:
+    """
+    Evaluate a comparison operation `=`, `!=`, `>=`, `>`, `<=`, or `<`.
+
+    Note: the caller is responsible for ensuring that numpy warnings are
+    suppressed (with np.errstate(all="ignore")) if needed.
+
+    Parameters
+    ----------
+    left : np.ndarray or ExtensionArray
+    right : object
+        Cannot be a DataFrame, Series, or Index.
+    op : {operator.eq, operator.ne, operator.gt, operator.ge, operator.lt, operator.le}
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+    # NB: We assume extract_array has already been called on left and right
+    lvalues = ensure_wrapped_if_datetimelike(left)
+    rvalues = ensure_wrapped_if_datetimelike(right)
+
+    rvalues = lib.item_from_zerodim(rvalues)
+    if isinstance(rvalues, list):
+        # We don't catch tuple here bc we may be comparing e.g. MultiIndex
+        #  to a tuple that represents a single entry, see test_compare_tuple_strs
+        rvalues = np.asarray(rvalues)
+
+    if isinstance(rvalues, (np.ndarray, ABCExtensionArray)):
+        # TODO: make this treatment consistent across ops and classes.
+        #  We are not catching all listlikes here (e.g. frozenset, tuple)
+        #  The ambiguous case is object-dtype.  See GH#27803
+        if len(lvalues) != len(rvalues):
+            raise ValueError(
+                "Lengths must match to compare", lvalues.shape, rvalues.shape
+            )
+
+    if should_extension_dispatch(lvalues, rvalues) or (
+        (isinstance(rvalues, (Timedelta, BaseOffset, Timestamp)) or right is NaT)
+        and lvalues.dtype != object
+    ):
+        # Call the method on lvalues
+        res_values = op(lvalues, rvalues)
+
+    elif is_scalar(rvalues) and isna(rvalues):  # TODO: but not pd.NA?
+        # numpy does not like comparisons vs None
+        if op is operator.ne:
+            res_values = np.ones(lvalues.shape, dtype=bool)
+        else:
+            res_values = np.zeros(lvalues.shape, dtype=bool)
+
+    elif is_numeric_v_string_like(lvalues, rvalues):
+        # GH#36377 going through the numexpr path would incorrectly raise
+        return invalid_comparison(lvalues, rvalues, op)
+
+    elif lvalues.dtype == object or isinstance(rvalues, str):
+        res_values = comp_method_OBJECT_ARRAY(op, lvalues, rvalues)
+
+    else:
+        res_values = _na_arithmetic_op(lvalues, rvalues, op, is_cmp=True)
+
+    return res_values
+
+
+def na_logical_op(x: np.ndarray, y, op):
+    try:
+        # For exposition, write:
+        #  yarr = isinstance(y, np.ndarray)
+        #  yint = is_integer(y) or (yarr and y.dtype.kind == "i")
+        #  ybool = is_bool(y) or (yarr and y.dtype.kind == "b")
+        #  xint = x.dtype.kind == "i"
+        #  xbool = x.dtype.kind == "b"
+        # Then Cases where this goes through without raising include:
+        #  (xint or xbool) and (yint or bool)
+        result = op(x, y)
+    except TypeError:
+        if isinstance(y, np.ndarray):
+            # bool-bool dtype operations should be OK, should not get here
+            assert not (x.dtype.kind == "b" and y.dtype.kind == "b")
+            x = ensure_object(x)
+            y = ensure_object(y)
+            result = libops.vec_binop(x.ravel(), y.ravel(), op)
+        else:
+            # let null fall thru
+            assert lib.is_scalar(y)
+            if not isna(y):
+                y = bool(y)
+            try:
+                result = libops.scalar_binop(x, y, op)
+            except (
+                TypeError,
+                ValueError,
+                AttributeError,
+                OverflowError,
+                NotImplementedError,
+            ) as err:
+                typ = type(y).__name__
+                raise TypeError(
+                    f"Cannot perform '{op.__name__}' with a dtyped [{x.dtype}] array "
+                    f"and scalar of type [{typ}]"
+                ) from err
+
+    return result.reshape(x.shape)
+
+
+def logical_op(left: ArrayLike, right: Any, op) -> ArrayLike:
+    """
+    Evaluate a logical operation `|`, `&`, or `^`.
+
+    Parameters
+    ----------
+    left : np.ndarray or ExtensionArray
+    right : object
+        Cannot be a DataFrame, Series, or Index.
+    op : {operator.and_, operator.or_, operator.xor}
+        Or one of the reversed variants from roperator.
+
+    Returns
+    -------
+    ndarray or ExtensionArray
+    """
+
+    def fill_bool(x, left=None):
+        # if `left` is specifically not-boolean, we do not cast to bool
+        if x.dtype.kind in "cfO":
+            # dtypes that can hold NA
+            mask = isna(x)
+            if mask.any():
+                x = x.astype(object)
+                x[mask] = False
+
+        if left is None or left.dtype.kind == "b":
+            x = x.astype(bool)
+        return x
+
+    right = lib.item_from_zerodim(right)
+    if is_list_like(right) and not hasattr(right, "dtype"):
+        # e.g. list, tuple
+        warnings.warn(
+            "Logical ops (and, or, xor) between Pandas objects and dtype-less "
+            "sequences (e.g. list, tuple) are deprecated and will raise in a "
+            "future version. Wrap the object in a Series, Index, or np.array "
+            "before operating instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        right = construct_1d_object_array_from_listlike(right)
+
+    # NB: We assume extract_array has already been called on left and right
+    lvalues = ensure_wrapped_if_datetimelike(left)
+    rvalues = right
+
+    if should_extension_dispatch(lvalues, rvalues):
+        # Call the method on lvalues
+        res_values = op(lvalues, rvalues)
+
+    else:
+        if isinstance(rvalues, np.ndarray):
+            is_other_int_dtype = rvalues.dtype.kind in "iu"
+            if not is_other_int_dtype:
+                rvalues = fill_bool(rvalues, lvalues)
+
+        else:
+            # i.e. scalar
+            is_other_int_dtype = lib.is_integer(rvalues)
+
+        res_values = na_logical_op(lvalues, rvalues, op)
+
+        # For int vs int `^`, `|`, `&` are bitwise operators and return
+        #   integer dtypes.  Otherwise these are boolean ops
+        if not (left.dtype.kind in "iu" and is_other_int_dtype):
+            res_values = fill_bool(res_values)
+
+    return res_values
+
+
+def get_array_op(op):
+    """
+    Return a binary array operation corresponding to the given operator op.
+
+    Parameters
+    ----------
+    op : function
+        Binary operator from operator or roperator module.
+
+    Returns
+    -------
+    functools.partial
+    """
+    if isinstance(op, partial):
+        # We get here via dispatch_to_series in DataFrame case
+        # e.g. test_rolling_consistency_var_debiasing_factors
+        return op
+
+    op_name = op.__name__.strip("_").lstrip("r")
+    if op_name == "arith_op":
+        # Reached via DataFrame._combine_frame i.e. flex methods
+        # e.g. test_df_add_flex_filled_mixed_dtypes
+        return op
+
+    if op_name in {"eq", "ne", "lt", "le", "gt", "ge"}:
+        return partial(comparison_op, op=op)
+    elif op_name in {"and", "or", "xor", "rand", "ror", "rxor"}:
+        return partial(logical_op, op=op)
+    elif op_name in {
+        "add",
+        "sub",
+        "mul",
+        "truediv",
+        "floordiv",
+        "mod",
+        "divmod",
+        "pow",
+    }:
+        return partial(arithmetic_op, op=op)
+    else:
+        raise NotImplementedError(op_name)
+
+
+def maybe_prepare_scalar_for_op(obj, shape: Shape):
+    """
+    Cast non-pandas objects to pandas types to unify behavior of arithmetic
+    and comparison operations.
+
+    Parameters
+    ----------
+    obj: object
+    shape : tuple[int]
+
+    Returns
+    -------
+    out : object
+
+    Notes
+    -----
+    Be careful to call this *after* determining the `name` attribute to be
+    attached to the result of the arithmetic operation.
+    """
+    if type(obj) is datetime.timedelta:
+        # GH#22390  cast up to Timedelta to rely on Timedelta
+        # implementation; otherwise operation against numeric-dtype
+        # raises TypeError
+        return Timedelta(obj)
+    elif type(obj) is datetime.datetime:
+        # cast up to Timestamp to rely on Timestamp implementation, see Timedelta above
+        return Timestamp(obj)
+    elif isinstance(obj, np.datetime64):
+        # GH#28080 numpy casts integer-dtype to datetime64 when doing
+        #  array[int] + datetime64, which we do not allow
+        if isna(obj):
+            from pandas.core.arrays import DatetimeArray
+
+            # Avoid possible ambiguities with pd.NaT
+            # GH 52295
+            if is_unitless(obj.dtype):
+                obj = obj.astype("datetime64[ns]")
+            elif not is_supported_dtype(obj.dtype):
+                new_dtype = get_supported_dtype(obj.dtype)
+                obj = obj.astype(new_dtype)
+            right = np.broadcast_to(obj, shape)
+            return DatetimeArray._simple_new(right, dtype=right.dtype)
+
+        return Timestamp(obj)
+
+    elif isinstance(obj, np.timedelta64):
+        if isna(obj):
+            from pandas.core.arrays import TimedeltaArray
+
+            # wrapping timedelta64("NaT") in Timedelta returns NaT,
+            #  which would incorrectly be treated as a datetime-NaT, so
+            #  we broadcast and wrap in a TimedeltaArray
+            # GH 52295
+            if is_unitless(obj.dtype):
+                obj = obj.astype("timedelta64[ns]")
+            elif not is_supported_dtype(obj.dtype):
+                new_dtype = get_supported_dtype(obj.dtype)
+                obj = obj.astype(new_dtype)
+            right = np.broadcast_to(obj, shape)
+            return TimedeltaArray._simple_new(right, dtype=right.dtype)
+
+        # In particular non-nanosecond timedelta64 needs to be cast to
+        #  nanoseconds, or else we get undesired behavior like
+        #  np.timedelta64(3, 'D') / 2 == np.timedelta64(1, 'D')
+        return Timedelta(obj)
+
+    # We want NumPy numeric scalars to behave like Python scalars
+    # post NEP 50
+    elif isinstance(obj, np.integer):
+        return int(obj)
+
+    elif isinstance(obj, np.floating):
+        return float(obj)
+
+    return obj
+
+
+_BOOL_OP_NOT_ALLOWED = {
+    operator.truediv,
+    roperator.rtruediv,
+    operator.floordiv,
+    roperator.rfloordiv,
+    operator.pow,
+    roperator.rpow,
+}
+
+
+def _bool_arith_check(op, a: np.ndarray, b):
+    """
+    In contrast to numpy, pandas raises an error for certain operations
+    with booleans.
+    """
+    if op in _BOOL_OP_NOT_ALLOWED:
+        if a.dtype.kind == "b" and (is_bool_dtype(b) or lib.is_bool(b)):
+            op_name = op.__name__.strip("_").lstrip("r")
+            raise NotImplementedError(
+                f"operator '{op_name}' not implemented for bool dtypes"
+            )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/common.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..559977bacf881552d546e7704d4cf4b12b4a32fe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/common.py
@@ -0,0 +1,146 @@
+"""
+Boilerplate functions used in defining binary operations.
+"""
+from __future__ import annotations
+
+from functools import wraps
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+
+from pandas._libs.lib import item_from_zerodim
+from pandas._libs.missing import is_matching_na
+
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import F
+
+
+def unpack_zerodim_and_defer(name: str) -> Callable[[F], F]:
+    """
+    Boilerplate for pandas conventions in arithmetic and comparison methods.
+
+    Parameters
+    ----------
+    name : str
+
+    Returns
+    -------
+    decorator
+    """
+
+    def wrapper(method: F) -> F:
+        return _unpack_zerodim_and_defer(method, name)
+
+    return wrapper
+
+
+def _unpack_zerodim_and_defer(method, name: str):
+    """
+    Boilerplate for pandas conventions in arithmetic and comparison methods.
+
+    Ensure method returns NotImplemented when operating against "senior"
+    classes.  Ensure zero-dimensional ndarrays are always unpacked.
+
+    Parameters
+    ----------
+    method : binary method
+    name : str
+
+    Returns
+    -------
+    method
+    """
+    stripped_name = name.removeprefix("__").removesuffix("__")
+    is_cmp = stripped_name in {"eq", "ne", "lt", "le", "gt", "ge"}
+
+    @wraps(method)
+    def new_method(self, other):
+        if is_cmp and isinstance(self, ABCIndex) and isinstance(other, ABCSeries):
+            # For comparison ops, Index does *not* defer to Series
+            pass
+        else:
+            prio = getattr(other, "__pandas_priority__", None)
+            if prio is not None:
+                if prio > self.__pandas_priority__:
+                    # e.g. other is DataFrame while self is Index/Series/EA
+                    return NotImplemented
+
+        other = item_from_zerodim(other)
+
+        return method(self, other)
+
+    return new_method
+
+
+def get_op_result_name(left, right):
+    """
+    Find the appropriate name to pin to an operation result.  This result
+    should always be either an Index or a Series.
+
+    Parameters
+    ----------
+    left : {Series, Index}
+    right : object
+
+    Returns
+    -------
+    name : object
+        Usually a string
+    """
+    if isinstance(right, (ABCSeries, ABCIndex)):
+        name = _maybe_match_name(left, right)
+    else:
+        name = left.name
+    return name
+
+
+def _maybe_match_name(a, b):
+    """
+    Try to find a name to attach to the result of an operation between
+    a and b.  If only one of these has a `name` attribute, return that
+    name.  Otherwise return a consensus name if they match or None if
+    they have different names.
+
+    Parameters
+    ----------
+    a : object
+    b : object
+
+    Returns
+    -------
+    name : str or None
+
+    See Also
+    --------
+    pandas.core.common.consensus_name_attr
+    """
+    a_has = hasattr(a, "name")
+    b_has = hasattr(b, "name")
+    if a_has and b_has:
+        try:
+            if a.name == b.name:
+                return a.name
+            elif is_matching_na(a.name, b.name):
+                # e.g. both are np.nan
+                return a.name
+            else:
+                return None
+        except TypeError:
+            # pd.NA
+            if is_matching_na(a.name, b.name):
+                return a.name
+            return None
+        except ValueError:
+            # e.g. np.int64(1) vs (np.int64(1), np.int64(2))
+            return None
+    elif a_has:
+        return a.name
+    elif b_has:
+        return b.name
+    return None
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/dispatch.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/dispatch.py
new file mode 100644
index 0000000000000000000000000000000000000000..a939fdd3d041e9f99dde7ea40fd7aa0572d0d9b7
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/dispatch.py
@@ -0,0 +1,30 @@
+"""
+Functions for defining unary operations.
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from pandas.core.dtypes.generic import ABCExtensionArray
+
+if TYPE_CHECKING:
+    from pandas._typing import ArrayLike
+
+
+def should_extension_dispatch(left: ArrayLike, right: Any) -> bool:
+    """
+    Identify cases where Series operation should dispatch to ExtensionArray method.
+
+    Parameters
+    ----------
+    left : np.ndarray or ExtensionArray
+    right : object
+
+    Returns
+    -------
+    bool
+    """
+    return isinstance(left, ABCExtensionArray) or isinstance(right, ABCExtensionArray)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/docstrings.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/docstrings.py
new file mode 100644
index 0000000000000000000000000000000000000000..bd2e532536d8491af44631e52982217a04ef5b17
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/docstrings.py
@@ -0,0 +1,772 @@
+"""
+Templating for ops docstrings
+"""
+from __future__ import annotations
+
+
+def make_flex_doc(op_name: str, typ: str) -> str:
+    """
+    Make the appropriate substitutions for the given operation and class-typ
+    into either _flex_doc_SERIES or _flex_doc_FRAME to return the docstring
+    to attach to a generated method.
+
+    Parameters
+    ----------
+    op_name : str {'__add__', '__sub__', ... '__eq__', '__ne__', ...}
+    typ : str {series, 'dataframe']}
+
+    Returns
+    -------
+    doc : str
+    """
+    op_name = op_name.replace("__", "")
+    op_desc = _op_descriptions[op_name]
+
+    op_desc_op = op_desc["op"]
+    assert op_desc_op is not None  # for mypy
+    if op_name.startswith("r"):
+        equiv = f"other {op_desc_op} {typ}"
+    elif op_name == "divmod":
+        equiv = f"{op_name}({typ}, other)"
+    else:
+        equiv = f"{typ} {op_desc_op} other"
+
+    if typ == "series":
+        base_doc = _flex_doc_SERIES
+        if op_desc["reverse"]:
+            base_doc += _see_also_reverse_SERIES.format(
+                reverse=op_desc["reverse"], see_also_desc=op_desc["see_also_desc"]
+            )
+        doc_no_examples = base_doc.format(
+            desc=op_desc["desc"],
+            op_name=op_name,
+            equiv=equiv,
+            series_returns=op_desc["series_returns"],
+        )
+        ser_example = op_desc["series_examples"]
+        if ser_example:
+            doc = doc_no_examples + ser_example
+        else:
+            doc = doc_no_examples
+    elif typ == "dataframe":
+        if op_name in ["eq", "ne", "le", "lt", "ge", "gt"]:
+            base_doc = _flex_comp_doc_FRAME
+            doc = _flex_comp_doc_FRAME.format(
+                op_name=op_name,
+                desc=op_desc["desc"],
+            )
+        else:
+            base_doc = _flex_doc_FRAME
+            doc = base_doc.format(
+                desc=op_desc["desc"],
+                op_name=op_name,
+                equiv=equiv,
+                reverse=op_desc["reverse"],
+            )
+    else:
+        raise AssertionError("Invalid typ argument.")
+    return doc
+
+
+_common_examples_algebra_SERIES = """
+Examples
+--------
+>>> a = pd.Series([1, 1, 1, np.nan], index=['a', 'b', 'c', 'd'])
+>>> a
+a    1.0
+b    1.0
+c    1.0
+d    NaN
+dtype: float64
+>>> b = pd.Series([1, np.nan, 1, np.nan], index=['a', 'b', 'd', 'e'])
+>>> b
+a    1.0
+b    NaN
+d    1.0
+e    NaN
+dtype: float64"""
+
+_common_examples_comparison_SERIES = """
+Examples
+--------
+>>> a = pd.Series([1, 1, 1, np.nan, 1], index=['a', 'b', 'c', 'd', 'e'])
+>>> a
+a    1.0
+b    1.0
+c    1.0
+d    NaN
+e    1.0
+dtype: float64
+>>> b = pd.Series([0, 1, 2, np.nan, 1], index=['a', 'b', 'c', 'd', 'f'])
+>>> b
+a    0.0
+b    1.0
+c    2.0
+d    NaN
+f    1.0
+dtype: float64"""
+
+_add_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.add(b, fill_value=0)
+a    2.0
+b    1.0
+c    1.0
+d    1.0
+e    NaN
+dtype: float64
+"""
+)
+
+_sub_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.subtract(b, fill_value=0)
+a    0.0
+b    1.0
+c    1.0
+d   -1.0
+e    NaN
+dtype: float64
+"""
+)
+
+_mul_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.multiply(b, fill_value=0)
+a    1.0
+b    0.0
+c    0.0
+d    0.0
+e    NaN
+dtype: float64
+"""
+)
+
+_div_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.divide(b, fill_value=0)
+a    1.0
+b    inf
+c    inf
+d    0.0
+e    NaN
+dtype: float64
+"""
+)
+
+_floordiv_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.floordiv(b, fill_value=0)
+a    1.0
+b    inf
+c    inf
+d    0.0
+e    NaN
+dtype: float64
+"""
+)
+
+_divmod_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.divmod(b, fill_value=0)
+(a    1.0
+ b    inf
+ c    inf
+ d    0.0
+ e    NaN
+ dtype: float64,
+ a    0.0
+ b    NaN
+ c    NaN
+ d    0.0
+ e    NaN
+ dtype: float64)
+"""
+)
+
+_mod_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.mod(b, fill_value=0)
+a    0.0
+b    NaN
+c    NaN
+d    0.0
+e    NaN
+dtype: float64
+"""
+)
+_pow_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.pow(b, fill_value=0)
+a    1.0
+b    1.0
+c    1.0
+d    0.0
+e    NaN
+dtype: float64
+"""
+)
+
+_ne_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.ne(b, fill_value=0)
+a    False
+b     True
+c     True
+d     True
+e     True
+dtype: bool
+"""
+)
+
+_eq_example_SERIES = (
+    _common_examples_algebra_SERIES
+    + """
+>>> a.eq(b, fill_value=0)
+a     True
+b    False
+c    False
+d    False
+e    False
+dtype: bool
+"""
+)
+
+_lt_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.lt(b, fill_value=0)
+a    False
+b    False
+c     True
+d    False
+e    False
+f     True
+dtype: bool
+"""
+)
+
+_le_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.le(b, fill_value=0)
+a    False
+b     True
+c     True
+d    False
+e    False
+f     True
+dtype: bool
+"""
+)
+
+_gt_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.gt(b, fill_value=0)
+a     True
+b    False
+c    False
+d    False
+e     True
+f    False
+dtype: bool
+"""
+)
+
+_ge_example_SERIES = (
+    _common_examples_comparison_SERIES
+    + """
+>>> a.ge(b, fill_value=0)
+a     True
+b     True
+c    False
+d    False
+e     True
+f    False
+dtype: bool
+"""
+)
+
+_returns_series = """Series\n    The result of the operation."""
+
+_returns_tuple = """2-Tuple of Series\n    The result of the operation."""
+
+_op_descriptions: dict[str, dict[str, str | None]] = {
+    # Arithmetic Operators
+    "add": {
+        "op": "+",
+        "desc": "Addition",
+        "reverse": "radd",
+        "series_examples": _add_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "sub": {
+        "op": "-",
+        "desc": "Subtraction",
+        "reverse": "rsub",
+        "series_examples": _sub_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "mul": {
+        "op": "*",
+        "desc": "Multiplication",
+        "reverse": "rmul",
+        "series_examples": _mul_example_SERIES,
+        "series_returns": _returns_series,
+        "df_examples": None,
+    },
+    "mod": {
+        "op": "%",
+        "desc": "Modulo",
+        "reverse": "rmod",
+        "series_examples": _mod_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "pow": {
+        "op": "**",
+        "desc": "Exponential power",
+        "reverse": "rpow",
+        "series_examples": _pow_example_SERIES,
+        "series_returns": _returns_series,
+        "df_examples": None,
+    },
+    "truediv": {
+        "op": "/",
+        "desc": "Floating division",
+        "reverse": "rtruediv",
+        "series_examples": _div_example_SERIES,
+        "series_returns": _returns_series,
+        "df_examples": None,
+    },
+    "floordiv": {
+        "op": "//",
+        "desc": "Integer division",
+        "reverse": "rfloordiv",
+        "series_examples": _floordiv_example_SERIES,
+        "series_returns": _returns_series,
+        "df_examples": None,
+    },
+    "divmod": {
+        "op": "divmod",
+        "desc": "Integer division and modulo",
+        "reverse": "rdivmod",
+        "series_examples": _divmod_example_SERIES,
+        "series_returns": _returns_tuple,
+        "df_examples": None,
+    },
+    # Comparison Operators
+    "eq": {
+        "op": "==",
+        "desc": "Equal to",
+        "reverse": None,
+        "series_examples": _eq_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "ne": {
+        "op": "!=",
+        "desc": "Not equal to",
+        "reverse": None,
+        "series_examples": _ne_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "lt": {
+        "op": "<",
+        "desc": "Less than",
+        "reverse": None,
+        "series_examples": _lt_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "le": {
+        "op": "<=",
+        "desc": "Less than or equal to",
+        "reverse": None,
+        "series_examples": _le_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "gt": {
+        "op": ">",
+        "desc": "Greater than",
+        "reverse": None,
+        "series_examples": _gt_example_SERIES,
+        "series_returns": _returns_series,
+    },
+    "ge": {
+        "op": ">=",
+        "desc": "Greater than or equal to",
+        "reverse": None,
+        "series_examples": _ge_example_SERIES,
+        "series_returns": _returns_series,
+    },
+}
+
+_py_num_ref = """see
+    `Python documentation
+    `_
+    for more details"""
+_op_names = list(_op_descriptions.keys())
+for key in _op_names:
+    reverse_op = _op_descriptions[key]["reverse"]
+    if reverse_op is not None:
+        _op_descriptions[reverse_op] = _op_descriptions[key].copy()
+        _op_descriptions[reverse_op]["reverse"] = key
+        _op_descriptions[key][
+            "see_also_desc"
+        ] = f"Reverse of the {_op_descriptions[key]['desc']} operator, {_py_num_ref}"
+        _op_descriptions[reverse_op][
+            "see_also_desc"
+        ] = f"Element-wise {_op_descriptions[key]['desc']}, {_py_num_ref}"
+
+_flex_doc_SERIES = """
+Return {desc} of series and other, element-wise (binary operator `{op_name}`).
+
+Equivalent to ``{equiv}``, but with support to substitute a fill_value for
+missing data in either one of the inputs.
+
+Parameters
+----------
+other : Series or scalar value
+level : int or name
+    Broadcast across a level, matching Index values on the
+    passed MultiIndex level.
+fill_value : None or float value, default None (NaN)
+    Fill existing missing (NaN) values, and any new element needed for
+    successful Series alignment, with this value before computation.
+    If data in both corresponding Series locations is missing
+    the result of filling (at that location) will be missing.
+axis : {{0 or 'index'}}
+    Unused. Parameter needed for compatibility with DataFrame.
+
+Returns
+-------
+{series_returns}
+"""
+
+_see_also_reverse_SERIES = """
+See Also
+--------
+Series.{reverse} : {see_also_desc}.
+"""
+
+_flex_doc_FRAME = """
+Get {desc} of dataframe and other, element-wise (binary operator `{op_name}`).
+
+Equivalent to ``{equiv}``, but with support to substitute a fill_value
+for missing data in one of the inputs. With reverse version, `{reverse}`.
+
+Among flexible wrappers (`add`, `sub`, `mul`, `div`, `floordiv`, `mod`, `pow`) to
+arithmetic operators: `+`, `-`, `*`, `/`, `//`, `%`, `**`.
+
+Parameters
+----------
+other : scalar, sequence, Series, dict or DataFrame
+    Any single or multiple element data structure, or list-like object.
+axis : {{0 or 'index', 1 or 'columns'}}
+    Whether to compare by the index (0 or 'index') or columns.
+    (1 or 'columns'). For Series input, axis to match Series index on.
+level : int or label
+    Broadcast across a level, matching Index values on the
+    passed MultiIndex level.
+fill_value : float or None, default None
+    Fill existing missing (NaN) values, and any new element needed for
+    successful DataFrame alignment, with this value before computation.
+    If data in both corresponding DataFrame locations is missing
+    the result will be missing.
+
+Returns
+-------
+DataFrame
+    Result of the arithmetic operation.
+
+See Also
+--------
+DataFrame.add : Add DataFrames.
+DataFrame.sub : Subtract DataFrames.
+DataFrame.mul : Multiply DataFrames.
+DataFrame.div : Divide DataFrames (float division).
+DataFrame.truediv : Divide DataFrames (float division).
+DataFrame.floordiv : Divide DataFrames (integer division).
+DataFrame.mod : Calculate modulo (remainder after division).
+DataFrame.pow : Calculate exponential power.
+
+Notes
+-----
+Mismatched indices will be unioned together.
+
+Examples
+--------
+>>> df = pd.DataFrame({{'angles': [0, 3, 4],
+...                    'degrees': [360, 180, 360]}},
+...                   index=['circle', 'triangle', 'rectangle'])
+>>> df
+           angles  degrees
+circle          0      360
+triangle        3      180
+rectangle       4      360
+
+Add a scalar with operator version which return the same
+results.
+
+>>> df + 1
+           angles  degrees
+circle          1      361
+triangle        4      181
+rectangle       5      361
+
+>>> df.add(1)
+           angles  degrees
+circle          1      361
+triangle        4      181
+rectangle       5      361
+
+Divide by constant with reverse version.
+
+>>> df.div(10)
+           angles  degrees
+circle        0.0     36.0
+triangle      0.3     18.0
+rectangle     0.4     36.0
+
+>>> df.rdiv(10)
+             angles   degrees
+circle          inf  0.027778
+triangle   3.333333  0.055556
+rectangle  2.500000  0.027778
+
+Subtract a list and Series by axis with operator version.
+
+>>> df - [1, 2]
+           angles  degrees
+circle         -1      358
+triangle        2      178
+rectangle       3      358
+
+>>> df.sub([1, 2], axis='columns')
+           angles  degrees
+circle         -1      358
+triangle        2      178
+rectangle       3      358
+
+>>> df.sub(pd.Series([1, 1, 1], index=['circle', 'triangle', 'rectangle']),
+...        axis='index')
+           angles  degrees
+circle         -1      359
+triangle        2      179
+rectangle       3      359
+
+Multiply a dictionary by axis.
+
+>>> df.mul({{'angles': 0, 'degrees': 2}})
+            angles  degrees
+circle           0      720
+triangle         0      360
+rectangle        0      720
+
+>>> df.mul({{'circle': 0, 'triangle': 2, 'rectangle': 3}}, axis='index')
+            angles  degrees
+circle           0        0
+triangle         6      360
+rectangle       12     1080
+
+Multiply a DataFrame of different shape with operator version.
+
+>>> other = pd.DataFrame({{'angles': [0, 3, 4]}},
+...                      index=['circle', 'triangle', 'rectangle'])
+>>> other
+           angles
+circle          0
+triangle        3
+rectangle       4
+
+>>> df * other
+           angles  degrees
+circle          0      NaN
+triangle        9      NaN
+rectangle      16      NaN
+
+>>> df.mul(other, fill_value=0)
+           angles  degrees
+circle          0      0.0
+triangle        9      0.0
+rectangle      16      0.0
+
+Divide by a MultiIndex by level.
+
+>>> df_multindex = pd.DataFrame({{'angles': [0, 3, 4, 4, 5, 6],
+...                              'degrees': [360, 180, 360, 360, 540, 720]}},
+...                             index=[['A', 'A', 'A', 'B', 'B', 'B'],
+...                                    ['circle', 'triangle', 'rectangle',
+...                                     'square', 'pentagon', 'hexagon']])
+>>> df_multindex
+             angles  degrees
+A circle          0      360
+  triangle        3      180
+  rectangle       4      360
+B square          4      360
+  pentagon        5      540
+  hexagon         6      720
+
+>>> df.div(df_multindex, level=1, fill_value=0)
+             angles  degrees
+A circle        NaN      1.0
+  triangle      1.0      1.0
+  rectangle     1.0      1.0
+B square        0.0      0.0
+  pentagon      0.0      0.0
+  hexagon       0.0      0.0
+"""
+
+_flex_comp_doc_FRAME = """
+Get {desc} of dataframe and other, element-wise (binary operator `{op_name}`).
+
+Among flexible wrappers (`eq`, `ne`, `le`, `lt`, `ge`, `gt`) to comparison
+operators.
+
+Equivalent to `==`, `!=`, `<=`, `<`, `>=`, `>` with support to choose axis
+(rows or columns) and level for comparison.
+
+Parameters
+----------
+other : scalar, sequence, Series, or DataFrame
+    Any single or multiple element data structure, or list-like object.
+axis : {{0 or 'index', 1 or 'columns'}}, default 'columns'
+    Whether to compare by the index (0 or 'index') or columns
+    (1 or 'columns').
+level : int or label
+    Broadcast across a level, matching Index values on the passed
+    MultiIndex level.
+
+Returns
+-------
+DataFrame of bool
+    Result of the comparison.
+
+See Also
+--------
+DataFrame.eq : Compare DataFrames for equality elementwise.
+DataFrame.ne : Compare DataFrames for inequality elementwise.
+DataFrame.le : Compare DataFrames for less than inequality
+    or equality elementwise.
+DataFrame.lt : Compare DataFrames for strictly less than
+    inequality elementwise.
+DataFrame.ge : Compare DataFrames for greater than inequality
+    or equality elementwise.
+DataFrame.gt : Compare DataFrames for strictly greater than
+    inequality elementwise.
+
+Notes
+-----
+Mismatched indices will be unioned together.
+`NaN` values are considered different (i.e. `NaN` != `NaN`).
+
+Examples
+--------
+>>> df = pd.DataFrame({{'cost': [250, 150, 100],
+...                    'revenue': [100, 250, 300]}},
+...                   index=['A', 'B', 'C'])
+>>> df
+   cost  revenue
+A   250      100
+B   150      250
+C   100      300
+
+Comparison with a scalar, using either the operator or method:
+
+>>> df == 100
+    cost  revenue
+A  False     True
+B  False    False
+C   True    False
+
+>>> df.eq(100)
+    cost  revenue
+A  False     True
+B  False    False
+C   True    False
+
+When `other` is a :class:`Series`, the columns of a DataFrame are aligned
+with the index of `other` and broadcast:
+
+>>> df != pd.Series([100, 250], index=["cost", "revenue"])
+    cost  revenue
+A   True     True
+B   True    False
+C  False     True
+
+Use the method to control the broadcast axis:
+
+>>> df.ne(pd.Series([100, 300], index=["A", "D"]), axis='index')
+   cost  revenue
+A  True    False
+B  True     True
+C  True     True
+D  True     True
+
+When comparing to an arbitrary sequence, the number of columns must
+match the number elements in `other`:
+
+>>> df == [250, 100]
+    cost  revenue
+A   True     True
+B  False    False
+C  False    False
+
+Use the method to control the axis:
+
+>>> df.eq([250, 250, 100], axis='index')
+    cost  revenue
+A   True    False
+B  False     True
+C   True    False
+
+Compare to a DataFrame of different shape.
+
+>>> other = pd.DataFrame({{'revenue': [300, 250, 100, 150]}},
+...                      index=['A', 'B', 'C', 'D'])
+>>> other
+   revenue
+A      300
+B      250
+C      100
+D      150
+
+>>> df.gt(other)
+    cost  revenue
+A  False    False
+B  False    False
+C  False     True
+D  False    False
+
+Compare to a MultiIndex by level.
+
+>>> df_multindex = pd.DataFrame({{'cost': [250, 150, 100, 150, 300, 220],
+...                              'revenue': [100, 250, 300, 200, 175, 225]}},
+...                             index=[['Q1', 'Q1', 'Q1', 'Q2', 'Q2', 'Q2'],
+...                                    ['A', 'B', 'C', 'A', 'B', 'C']])
+>>> df_multindex
+      cost  revenue
+Q1 A   250      100
+   B   150      250
+   C   100      300
+Q2 A   150      200
+   B   300      175
+   C   220      225
+
+>>> df.le(df_multindex, level=1)
+       cost  revenue
+Q1 A   True     True
+   B   True     True
+   C   True     True
+Q2 A  False     True
+   B   True    False
+   C   True    False
+"""
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/invalid.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/invalid.py
new file mode 100644
index 0000000000000000000000000000000000000000..e5ae6d359ac2205b01706211382d116b29176c7a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/invalid.py
@@ -0,0 +1,62 @@
+"""
+Templates for invalid operations.
+"""
+from __future__ import annotations
+
+import operator
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from pandas._typing import npt
+
+
+def invalid_comparison(left, right, op) -> npt.NDArray[np.bool_]:
+    """
+    If a comparison has mismatched types and is not necessarily meaningful,
+    follow python3 conventions by:
+
+        - returning all-False for equality
+        - returning all-True for inequality
+        - raising TypeError otherwise
+
+    Parameters
+    ----------
+    left : array-like
+    right : scalar, array-like
+    op : operator.{eq, ne, lt, le, gt}
+
+    Raises
+    ------
+    TypeError : on inequality comparisons
+    """
+    if op is operator.eq:
+        res_values = np.zeros(left.shape, dtype=bool)
+    elif op is operator.ne:
+        res_values = np.ones(left.shape, dtype=bool)
+    else:
+        typ = type(right).__name__
+        raise TypeError(f"Invalid comparison between dtype={left.dtype} and {typ}")
+    return res_values
+
+
+def make_invalid_op(name: str):
+    """
+    Return a binary method that always raises a TypeError.
+
+    Parameters
+    ----------
+    name : str
+
+    Returns
+    -------
+    invalid_op : function
+    """
+
+    def invalid_op(self, other=None):
+        typ = type(self).__name__
+        raise TypeError(f"cannot perform {name} with this index type: {typ}")
+
+    invalid_op.__name__ = name
+    return invalid_op
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/mask_ops.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/mask_ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..adc1f63c568bf579f31b13446f4614435d443df1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/mask_ops.py
@@ -0,0 +1,189 @@
+"""
+Ops for masked arrays.
+"""
+from __future__ import annotations
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+
+
+def kleene_or(
+    left: bool | np.ndarray | libmissing.NAType,
+    right: bool | np.ndarray | libmissing.NAType,
+    left_mask: np.ndarray | None,
+    right_mask: np.ndarray | None,
+):
+    """
+    Boolean ``or`` using Kleene logic.
+
+    Values are NA where we have ``NA | NA`` or ``NA | False``.
+    ``NA | True`` is considered True.
+
+    Parameters
+    ----------
+    left, right : ndarray, NA, or bool
+        The values of the array.
+    left_mask, right_mask : ndarray, optional
+        The masks. Only one of these may be None, which implies that
+        the associated `left` or `right` value is a scalar.
+
+    Returns
+    -------
+    result, mask: ndarray[bool]
+        The result of the logical or, and the new mask.
+    """
+    # To reduce the number of cases, we ensure that `left` & `left_mask`
+    # always come from an array, not a scalar. This is safe, since
+    # A | B == B | A
+    if left_mask is None:
+        return kleene_or(right, left, right_mask, left_mask)
+
+    if not isinstance(left, np.ndarray):
+        raise TypeError("Either `left` or `right` need to be a np.ndarray.")
+
+    raise_for_nan(right, method="or")
+
+    if right is libmissing.NA:
+        result = left.copy()
+    else:
+        result = left | right
+
+    if right_mask is not None:
+        # output is unknown where (False & NA), (NA & False), (NA & NA)
+        left_false = ~(left | left_mask)
+        right_false = ~(right | right_mask)
+        mask = (
+            (left_false & right_mask)
+            | (right_false & left_mask)
+            | (left_mask & right_mask)
+        )
+    else:
+        if right is True:
+            mask = np.zeros_like(left_mask)
+        elif right is libmissing.NA:
+            mask = (~left & ~left_mask) | left_mask
+        else:
+            # False
+            mask = left_mask.copy()
+
+    return result, mask
+
+
+def kleene_xor(
+    left: bool | np.ndarray | libmissing.NAType,
+    right: bool | np.ndarray | libmissing.NAType,
+    left_mask: np.ndarray | None,
+    right_mask: np.ndarray | None,
+):
+    """
+    Boolean ``xor`` using Kleene logic.
+
+    This is the same as ``or``, with the following adjustments
+
+    * True, True -> False
+    * True, NA   -> NA
+
+    Parameters
+    ----------
+    left, right : ndarray, NA, or bool
+        The values of the array.
+    left_mask, right_mask : ndarray, optional
+        The masks. Only one of these may be None, which implies that
+        the associated `left` or `right` value is a scalar.
+
+    Returns
+    -------
+    result, mask: ndarray[bool]
+        The result of the logical xor, and the new mask.
+    """
+    # To reduce the number of cases, we ensure that `left` & `left_mask`
+    # always come from an array, not a scalar. This is safe, since
+    # A ^ B == B ^ A
+    if left_mask is None:
+        return kleene_xor(right, left, right_mask, left_mask)
+
+    if not isinstance(left, np.ndarray):
+        raise TypeError("Either `left` or `right` need to be a np.ndarray.")
+
+    raise_for_nan(right, method="xor")
+    if right is libmissing.NA:
+        result = np.zeros_like(left)
+    else:
+        result = left ^ right
+
+    if right_mask is None:
+        if right is libmissing.NA:
+            mask = np.ones_like(left_mask)
+        else:
+            mask = left_mask.copy()
+    else:
+        mask = left_mask | right_mask
+
+    return result, mask
+
+
+def kleene_and(
+    left: bool | libmissing.NAType | np.ndarray,
+    right: bool | libmissing.NAType | np.ndarray,
+    left_mask: np.ndarray | None,
+    right_mask: np.ndarray | None,
+):
+    """
+    Boolean ``and`` using Kleene logic.
+
+    Values are ``NA`` for ``NA & NA`` or ``True & NA``.
+
+    Parameters
+    ----------
+    left, right : ndarray, NA, or bool
+        The values of the array.
+    left_mask, right_mask : ndarray, optional
+        The masks. Only one of these may be None, which implies that
+        the associated `left` or `right` value is a scalar.
+
+    Returns
+    -------
+    result, mask: ndarray[bool]
+        The result of the logical xor, and the new mask.
+    """
+    # To reduce the number of cases, we ensure that `left` & `left_mask`
+    # always come from an array, not a scalar. This is safe, since
+    # A & B == B & A
+    if left_mask is None:
+        return kleene_and(right, left, right_mask, left_mask)
+
+    if not isinstance(left, np.ndarray):
+        raise TypeError("Either `left` or `right` need to be a np.ndarray.")
+    raise_for_nan(right, method="and")
+
+    if right is libmissing.NA:
+        result = np.zeros_like(left)
+    else:
+        result = left & right
+
+    if right_mask is None:
+        # Scalar `right`
+        if right is libmissing.NA:
+            mask = (left & ~left_mask) | left_mask
+
+        else:
+            mask = left_mask.copy()
+            if right is False:
+                # unmask everything
+                mask[:] = False
+    else:
+        # unmask where either left or right is False
+        left_false = ~(left | left_mask)
+        right_false = ~(right | right_mask)
+        mask = (left_mask & ~right_false) | (right_mask & ~left_false)
+
+    return result, mask
+
+
+def raise_for_nan(value, method: str) -> None:
+    if lib.is_float(value) and np.isnan(value):
+        raise ValueError(f"Cannot perform logical '{method}' with floating NaN")
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/ops/missing.py b/.venv/lib/python3.13/site-packages/pandas/core/ops/missing.py
new file mode 100644
index 0000000000000000000000000000000000000000..fc685935a35fceab74012912d3c3cae65b9c1818
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/ops/missing.py
@@ -0,0 +1,176 @@
+"""
+Missing data handling for arithmetic operations.
+
+In particular, pandas conventions regarding division by zero differ
+from numpy in the following ways:
+    1) np.array([-1, 0, 1], dtype=dtype1) // np.array([0, 0, 0], dtype=dtype2)
+       gives [nan, nan, nan] for most dtype combinations, and [0, 0, 0] for
+       the remaining pairs
+       (the remaining being dtype1==dtype2==intN and dtype==dtype2==uintN).
+
+       pandas convention is to return [-inf, nan, inf] for all dtype
+       combinations.
+
+       Note: the numpy behavior described here is py3-specific.
+
+    2) np.array([-1, 0, 1], dtype=dtype1) % np.array([0, 0, 0], dtype=dtype2)
+       gives precisely the same results as the // operation.
+
+       pandas convention is to return [nan, nan, nan] for all dtype
+       combinations.
+
+    3) divmod behavior consistent with 1) and 2).
+"""
+from __future__ import annotations
+
+import operator
+
+import numpy as np
+
+from pandas.core import roperator
+
+
+def _fill_zeros(result: np.ndarray, x, y):
+    """
+    If this is a reversed op, then flip x,y
+
+    If we have an integer value (or array in y)
+    and we have 0's, fill them with np.nan,
+    return the result.
+
+    Mask the nan's from x.
+    """
+    if result.dtype.kind == "f":
+        return result
+
+    is_variable_type = hasattr(y, "dtype")
+    is_scalar_type = not isinstance(y, np.ndarray)
+
+    if not is_variable_type and not is_scalar_type:
+        # e.g. test_series_ops_name_retention with mod we get here with list/tuple
+        return result
+
+    if is_scalar_type:
+        y = np.array(y)
+
+    if y.dtype.kind in "iu":
+        ymask = y == 0
+        if ymask.any():
+            # GH#7325, mask and nans must be broadcastable
+            mask = ymask & ~np.isnan(result)
+
+            # GH#9308 doing ravel on result and mask can improve putmask perf,
+            #  but can also make unwanted copies.
+            result = result.astype("float64", copy=False)
+
+            np.putmask(result, mask, np.nan)
+
+    return result
+
+
+def mask_zero_div_zero(x, y, result: np.ndarray) -> np.ndarray:
+    """
+    Set results of  0 // 0 to np.nan, regardless of the dtypes
+    of the numerator or the denominator.
+
+    Parameters
+    ----------
+    x : ndarray
+    y : ndarray
+    result : ndarray
+
+    Returns
+    -------
+    ndarray
+        The filled result.
+
+    Examples
+    --------
+    >>> x = np.array([1, 0, -1], dtype=np.int64)
+    >>> x
+    array([ 1,  0, -1])
+    >>> y = 0       # int 0; numpy behavior is different with float
+    >>> result = x // y
+    >>> result      # raw numpy result does not fill division by zero
+    array([0, 0, 0])
+    >>> mask_zero_div_zero(x, y, result)
+    array([ inf,  nan, -inf])
+    """
+
+    if not hasattr(y, "dtype"):
+        # e.g. scalar, tuple
+        y = np.array(y)
+    if not hasattr(x, "dtype"):
+        # e.g scalar, tuple
+        x = np.array(x)
+
+    zmask = y == 0
+
+    if zmask.any():
+        # Flip sign if necessary for -0.0
+        zneg_mask = zmask & np.signbit(y)
+        zpos_mask = zmask & ~zneg_mask
+
+        x_lt0 = x < 0
+        x_gt0 = x > 0
+        nan_mask = zmask & (x == 0)
+        neginf_mask = (zpos_mask & x_lt0) | (zneg_mask & x_gt0)
+        posinf_mask = (zpos_mask & x_gt0) | (zneg_mask & x_lt0)
+
+        if nan_mask.any() or neginf_mask.any() or posinf_mask.any():
+            # Fill negative/0 with -inf, positive/0 with +inf, 0/0 with NaN
+            result = result.astype("float64", copy=False)
+
+            result[nan_mask] = np.nan
+            result[posinf_mask] = np.inf
+            result[neginf_mask] = -np.inf
+
+    return result
+
+
+def dispatch_fill_zeros(op, left, right, result):
+    """
+    Call _fill_zeros with the appropriate fill value depending on the operation,
+    with special logic for divmod and rdivmod.
+
+    Parameters
+    ----------
+    op : function (operator.add, operator.div, ...)
+    left : object (np.ndarray for non-reversed ops)
+        We have excluded ExtensionArrays here
+    right : object (np.ndarray for reversed ops)
+        We have excluded ExtensionArrays here
+    result : ndarray
+
+    Returns
+    -------
+    result : np.ndarray
+
+    Notes
+    -----
+    For divmod and rdivmod, the `result` parameter and returned `result`
+    is a 2-tuple of ndarray objects.
+    """
+    if op is divmod:
+        result = (
+            mask_zero_div_zero(left, right, result[0]),
+            _fill_zeros(result[1], left, right),
+        )
+    elif op is roperator.rdivmod:
+        result = (
+            mask_zero_div_zero(right, left, result[0]),
+            _fill_zeros(result[1], right, left),
+        )
+    elif op is operator.floordiv:
+        # Note: no need to do this for truediv; in py3 numpy behaves the way
+        #  we want.
+        result = mask_zero_div_zero(left, right, result)
+    elif op is roperator.rfloordiv:
+        # Note: no need to do this for rtruediv; in py3 numpy behaves the way
+        #  we want.
+        result = mask_zero_div_zero(right, left, result)
+    elif op is operator.mod:
+        result = _fill_zeros(result, left, right)
+    elif op is roperator.rmod:
+        result = _fill_zeros(result, right, left)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/resample.py b/.venv/lib/python3.13/site-packages/pandas/core/resample.py
new file mode 100644
index 0000000000000000000000000000000000000000..6c5da08a86fdc883ed9f2b66bf07d0e743b1d63b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/resample.py
@@ -0,0 +1,2906 @@
+from __future__ import annotations
+
+import copy
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+    final,
+    no_type_check,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs import (
+    BaseOffset,
+    IncompatibleFrequency,
+    NaT,
+    Period,
+    Timedelta,
+    Timestamp,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import freq_to_period_freqstr
+from pandas._typing import NDFrameT
+from pandas.compat.numpy import function as nv
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    doc,
+)
+from pandas.util._exceptions import (
+    find_stack_level,
+    rewrite_warning,
+)
+
+from pandas.core.dtypes.dtypes import ArrowDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+import pandas.core.algorithms as algos
+from pandas.core.apply import (
+    ResamplerWindowApply,
+    warn_alias_replacement,
+)
+from pandas.core.arrays import ArrowExtensionArray
+from pandas.core.base import (
+    PandasObject,
+    SelectionMixin,
+)
+import pandas.core.common as com
+from pandas.core.generic import (
+    NDFrame,
+    _shared_docs,
+)
+from pandas.core.groupby.generic import SeriesGroupBy
+from pandas.core.groupby.groupby import (
+    BaseGroupBy,
+    GroupBy,
+    _apply_groupings_depr,
+    _pipe_template,
+    get_groupby,
+)
+from pandas.core.groupby.grouper import Grouper
+from pandas.core.groupby.ops import BinGrouper
+from pandas.core.indexes.api import MultiIndex
+from pandas.core.indexes.base import Index
+from pandas.core.indexes.datetimes import (
+    DatetimeIndex,
+    date_range,
+)
+from pandas.core.indexes.period import (
+    PeriodIndex,
+    period_range,
+)
+from pandas.core.indexes.timedeltas import (
+    TimedeltaIndex,
+    timedelta_range,
+)
+
+from pandas.tseries.frequencies import (
+    is_subperiod,
+    is_superperiod,
+)
+from pandas.tseries.offsets import (
+    Day,
+    Tick,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import (
+        AnyArrayLike,
+        Axis,
+        AxisInt,
+        Frequency,
+        IndexLabel,
+        InterpolateOptions,
+        T,
+        TimedeltaConvertibleTypes,
+        TimeGrouperOrigin,
+        TimestampConvertibleTypes,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+_shared_docs_kwargs: dict[str, str] = {}
+
+
+class Resampler(BaseGroupBy, PandasObject):
+    """
+    Class for resampling datetimelike data, a groupby-like operation.
+    See aggregate, transform, and apply functions on this object.
+
+    It's easiest to use obj.resample(...) to use Resampler.
+
+    Parameters
+    ----------
+    obj : Series or DataFrame
+    groupby : TimeGrouper
+    axis : int, default 0
+    kind : str or None
+        'period', 'timestamp' to override default index treatment
+
+    Returns
+    -------
+    a Resampler of the appropriate type
+
+    Notes
+    -----
+    After resampling, see aggregate, apply, and transform functions.
+    """
+
+    _grouper: BinGrouper
+    _timegrouper: TimeGrouper
+    binner: DatetimeIndex | TimedeltaIndex | PeriodIndex  # depends on subclass
+    exclusions: frozenset[Hashable] = frozenset()  # for SelectionMixin compat
+    _internal_names_set = set({"obj", "ax", "_indexer"})
+
+    # to the groupby descriptor
+    _attributes = [
+        "freq",
+        "axis",
+        "closed",
+        "label",
+        "convention",
+        "kind",
+        "origin",
+        "offset",
+    ]
+
+    def __init__(
+        self,
+        obj: NDFrame,
+        timegrouper: TimeGrouper,
+        axis: Axis = 0,
+        kind=None,
+        *,
+        gpr_index: Index,
+        group_keys: bool = False,
+        selection=None,
+        include_groups: bool = True,
+    ) -> None:
+        self._timegrouper = timegrouper
+        self.keys = None
+        self.sort = True
+        self.axis = obj._get_axis_number(axis)
+        self.kind = kind
+        self.group_keys = group_keys
+        self.as_index = True
+        self.include_groups = include_groups
+
+        self.obj, self.ax, self._indexer = self._timegrouper._set_grouper(
+            self._convert_obj(obj), sort=True, gpr_index=gpr_index
+        )
+        self.binner, self._grouper = self._get_binner()
+        self._selection = selection
+        if self._timegrouper.key is not None:
+            self.exclusions = frozenset([self._timegrouper.key])
+        else:
+            self.exclusions = frozenset()
+
+    @final
+    def __str__(self) -> str:
+        """
+        Provide a nice str repr of our rolling object.
+        """
+        attrs = (
+            f"{k}={getattr(self._timegrouper, k)}"
+            for k in self._attributes
+            if getattr(self._timegrouper, k, None) is not None
+        )
+        return f"{type(self).__name__} [{', '.join(attrs)}]"
+
+    @final
+    def __getattr__(self, attr: str):
+        if attr in self._internal_names_set:
+            return object.__getattribute__(self, attr)
+        if attr in self._attributes:
+            return getattr(self._timegrouper, attr)
+        if attr in self.obj:
+            return self[attr]
+
+        return object.__getattribute__(self, attr)
+
+    @final
+    @property
+    def _from_selection(self) -> bool:
+        """
+        Is the resampling from a DataFrame column or MultiIndex level.
+        """
+        # upsampling and PeriodIndex resampling do not work
+        # with selection, this state used to catch and raise an error
+        return self._timegrouper is not None and (
+            self._timegrouper.key is not None or self._timegrouper.level is not None
+        )
+
+    def _convert_obj(self, obj: NDFrameT) -> NDFrameT:
+        """
+        Provide any conversions for the object in order to correctly handle.
+
+        Parameters
+        ----------
+        obj : Series or DataFrame
+
+        Returns
+        -------
+        Series or DataFrame
+        """
+        return obj._consolidate()
+
+    def _get_binner_for_time(self):
+        raise AbstractMethodError(self)
+
+    @final
+    def _get_binner(self):
+        """
+        Create the BinGrouper, assume that self.set_grouper(obj)
+        has already been called.
+        """
+        binner, bins, binlabels = self._get_binner_for_time()
+        assert len(bins) == len(binlabels)
+        bin_grouper = BinGrouper(bins, binlabels, indexer=self._indexer)
+        return binner, bin_grouper
+
+    @final
+    @Substitution(
+        klass="Resampler",
+        examples="""
+    >>> df = pd.DataFrame({'A': [1, 2, 3, 4]},
+    ...                   index=pd.date_range('2012-08-02', periods=4))
+    >>> df
+                A
+    2012-08-02  1
+    2012-08-03  2
+    2012-08-04  3
+    2012-08-05  4
+
+    To get the difference between each 2-day period's maximum and minimum
+    value in one pass, you can do
+
+    >>> df.resample('2D').pipe(lambda x: x.max() - x.min())
+                A
+    2012-08-02  1
+    2012-08-04  1""",
+    )
+    @Appender(_pipe_template)
+    def pipe(
+        self,
+        func: Callable[..., T] | tuple[Callable[..., T], str],
+        *args,
+        **kwargs,
+    ) -> T:
+        return super().pipe(func, *args, **kwargs)
+
+    _agg_see_also_doc = dedent(
+        """
+    See Also
+    --------
+    DataFrame.groupby.aggregate : Aggregate using callable, string, dict,
+        or list of string/callables.
+    DataFrame.resample.transform : Transforms the Series on each group
+        based on the given function.
+    DataFrame.aggregate: Aggregate using one or more
+        operations over the specified axis.
+    """
+    )
+
+    _agg_examples_doc = dedent(
+        """
+    Examples
+    --------
+    >>> s = pd.Series([1, 2, 3, 4, 5],
+    ...               index=pd.date_range('20130101', periods=5, freq='s'))
+    >>> s
+    2013-01-01 00:00:00    1
+    2013-01-01 00:00:01    2
+    2013-01-01 00:00:02    3
+    2013-01-01 00:00:03    4
+    2013-01-01 00:00:04    5
+    Freq: s, dtype: int64
+
+    >>> r = s.resample('2s')
+
+    >>> r.agg("sum")
+    2013-01-01 00:00:00    3
+    2013-01-01 00:00:02    7
+    2013-01-01 00:00:04    5
+    Freq: 2s, dtype: int64
+
+    >>> r.agg(['sum', 'mean', 'max'])
+                         sum  mean  max
+    2013-01-01 00:00:00    3   1.5    2
+    2013-01-01 00:00:02    7   3.5    4
+    2013-01-01 00:00:04    5   5.0    5
+
+    >>> r.agg({'result': lambda x: x.mean() / x.std(),
+    ...        'total': "sum"})
+                           result  total
+    2013-01-01 00:00:00  2.121320      3
+    2013-01-01 00:00:02  4.949747      7
+    2013-01-01 00:00:04       NaN      5
+
+    >>> r.agg(average="mean", total="sum")
+                             average  total
+    2013-01-01 00:00:00      1.5      3
+    2013-01-01 00:00:02      3.5      7
+    2013-01-01 00:00:04      5.0      5
+    """
+    )
+
+    @final
+    @doc(
+        _shared_docs["aggregate"],
+        see_also=_agg_see_also_doc,
+        examples=_agg_examples_doc,
+        klass="DataFrame",
+        axis="",
+    )
+    def aggregate(self, func=None, *args, **kwargs):
+        result = ResamplerWindowApply(self, func, args=args, kwargs=kwargs).agg()
+        if result is None:
+            how = func
+            result = self._groupby_and_aggregate(how, *args, **kwargs)
+
+        return result
+
+    agg = aggregate
+    apply = aggregate
+
+    @final
+    def transform(self, arg, *args, **kwargs):
+        """
+        Call function producing a like-indexed Series on each group.
+
+        Return a Series with the transformed values.
+
+        Parameters
+        ----------
+        arg : function
+            To apply to each group. Should return a Series with the same index.
+
+        Returns
+        -------
+        Series
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2],
+        ...               index=pd.date_range('20180101',
+        ...                                   periods=2,
+        ...                                   freq='1h'))
+        >>> s
+        2018-01-01 00:00:00    1
+        2018-01-01 01:00:00    2
+        Freq: h, dtype: int64
+
+        >>> resampled = s.resample('15min')
+        >>> resampled.transform(lambda x: (x - x.mean()) / x.std())
+        2018-01-01 00:00:00   NaN
+        2018-01-01 01:00:00   NaN
+        Freq: h, dtype: float64
+        """
+        return self._selected_obj.groupby(self._timegrouper).transform(
+            arg, *args, **kwargs
+        )
+
+    def _downsample(self, f, **kwargs):
+        raise AbstractMethodError(self)
+
+    def _upsample(self, f, limit: int | None = None, fill_value=None):
+        raise AbstractMethodError(self)
+
+    def _gotitem(self, key, ndim: int, subset=None):
+        """
+        Sub-classes to define. Return a sliced object.
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        grouper = self._grouper
+        if subset is None:
+            subset = self.obj
+            if key is not None:
+                subset = subset[key]
+            else:
+                # reached via Apply.agg_dict_like with selection=None and ndim=1
+                assert subset.ndim == 1
+        if ndim == 1:
+            assert subset.ndim == 1
+
+        grouped = get_groupby(
+            subset, by=None, grouper=grouper, axis=self.axis, group_keys=self.group_keys
+        )
+        return grouped
+
+    def _groupby_and_aggregate(self, how, *args, **kwargs):
+        """
+        Re-evaluate the obj with a groupby aggregation.
+        """
+        grouper = self._grouper
+
+        # Excludes `on` column when provided
+        obj = self._obj_with_exclusions
+
+        grouped = get_groupby(
+            obj, by=None, grouper=grouper, axis=self.axis, group_keys=self.group_keys
+        )
+
+        try:
+            if callable(how):
+                # TODO: test_resample_apply_with_additional_args fails if we go
+                #  through the non-lambda path, not clear that it should.
+                func = lambda x: how(x, *args, **kwargs)
+                result = grouped.aggregate(func)
+            else:
+                result = grouped.aggregate(how, *args, **kwargs)
+        except (AttributeError, KeyError):
+            # we have a non-reducing function; try to evaluate
+            # alternatively we want to evaluate only a column of the input
+
+            # test_apply_to_one_column_of_df the function being applied references
+            #  a DataFrame column, but aggregate_item_by_item operates column-wise
+            #  on Series, raising AttributeError or KeyError
+            #  (depending on whether the column lookup uses getattr/__getitem__)
+            result = _apply(
+                grouped, how, *args, include_groups=self.include_groups, **kwargs
+            )
+
+        except ValueError as err:
+            if "Must produce aggregated value" in str(err):
+                # raised in _aggregate_named
+                # see test_apply_without_aggregation, test_apply_with_mutated_index
+                pass
+            else:
+                raise
+
+            # we have a non-reducing function
+            # try to evaluate
+            result = _apply(
+                grouped, how, *args, include_groups=self.include_groups, **kwargs
+            )
+
+        return self._wrap_result(result)
+
+    @final
+    def _get_resampler_for_grouping(
+        self, groupby: GroupBy, key, include_groups: bool = True
+    ):
+        """
+        Return the correct class for resampling with groupby.
+        """
+        return self._resampler_for_grouping(
+            groupby=groupby, key=key, parent=self, include_groups=include_groups
+        )
+
+    def _wrap_result(self, result):
+        """
+        Potentially wrap any results.
+        """
+        # GH 47705
+        obj = self.obj
+        if (
+            isinstance(result, ABCDataFrame)
+            and len(result) == 0
+            and not isinstance(result.index, PeriodIndex)
+        ):
+            result = result.set_index(
+                _asfreq_compat(obj.index[:0], freq=self.freq), append=True
+            )
+
+        if isinstance(result, ABCSeries) and self._selection is not None:
+            result.name = self._selection
+
+        if isinstance(result, ABCSeries) and result.empty:
+            # When index is all NaT, result is empty but index is not
+            result.index = _asfreq_compat(obj.index[:0], freq=self.freq)
+            result.name = getattr(obj, "name", None)
+
+        if self._timegrouper._arrow_dtype is not None:
+            result.index = result.index.astype(self._timegrouper._arrow_dtype)
+
+        return result
+
+    @final
+    def ffill(self, limit: int | None = None):
+        """
+        Forward fill the values.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        An upsampled Series.
+
+        See Also
+        --------
+        Series.fillna: Fill NA/NaN values using the specified method.
+        DataFrame.fillna: Fill NA/NaN values using the specified method.
+
+        Examples
+        --------
+        Here we only create a ``Series``.
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+
+        Example for ``ffill`` with downsampling (we have fewer dates after resampling):
+
+        >>> ser.resample('MS').ffill()
+        2023-01-01    1
+        2023-02-01    3
+        Freq: MS, dtype: int64
+
+        Example for ``ffill`` with upsampling (fill the new dates with
+        the previous value):
+
+        >>> ser.resample('W').ffill()
+        2023-01-01    1
+        2023-01-08    1
+        2023-01-15    2
+        2023-01-22    2
+        2023-01-29    2
+        2023-02-05    3
+        2023-02-12    3
+        2023-02-19    4
+        Freq: W-SUN, dtype: int64
+
+        With upsampling and limiting (only fill the first new date with the
+        previous value):
+
+        >>> ser.resample('W').ffill(limit=1)
+        2023-01-01    1.0
+        2023-01-08    1.0
+        2023-01-15    2.0
+        2023-01-22    2.0
+        2023-01-29    NaN
+        2023-02-05    3.0
+        2023-02-12    NaN
+        2023-02-19    4.0
+        Freq: W-SUN, dtype: float64
+        """
+        return self._upsample("ffill", limit=limit)
+
+    @final
+    def nearest(self, limit: int | None = None):
+        """
+        Resample by using the nearest value.
+
+        When resampling data, missing values may appear (e.g., when the
+        resampling frequency is higher than the original frequency).
+        The `nearest` method will replace ``NaN`` values that appeared in
+        the resampled data with the value from the nearest member of the
+        sequence, based on the index value.
+        Missing values that existed in the original data will not be modified.
+        If `limit` is given, fill only this many values in each direction for
+        each of the original values.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            An upsampled Series or DataFrame with ``NaN`` values filled with
+            their nearest value.
+
+        See Also
+        --------
+        backfill : Backward fill the new missing values in the resampled data.
+        pad : Forward fill ``NaN`` values.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2],
+        ...               index=pd.date_range('20180101',
+        ...                                   periods=2,
+        ...                                   freq='1h'))
+        >>> s
+        2018-01-01 00:00:00    1
+        2018-01-01 01:00:00    2
+        Freq: h, dtype: int64
+
+        >>> s.resample('15min').nearest()
+        2018-01-01 00:00:00    1
+        2018-01-01 00:15:00    1
+        2018-01-01 00:30:00    2
+        2018-01-01 00:45:00    2
+        2018-01-01 01:00:00    2
+        Freq: 15min, dtype: int64
+
+        Limit the number of upsampled values imputed by the nearest:
+
+        >>> s.resample('15min').nearest(limit=1)
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:15:00    1.0
+        2018-01-01 00:30:00    NaN
+        2018-01-01 00:45:00    2.0
+        2018-01-01 01:00:00    2.0
+        Freq: 15min, dtype: float64
+        """
+        return self._upsample("nearest", limit=limit)
+
+    @final
+    def bfill(self, limit: int | None = None):
+        """
+        Backward fill the new missing values in the resampled data.
+
+        In statistics, imputation is the process of replacing missing data with
+        substituted values [1]_. When resampling data, missing values may
+        appear (e.g., when the resampling frequency is higher than the original
+        frequency). The backward fill will replace NaN values that appeared in
+        the resampled data with the next value in the original sequence.
+        Missing values that existed in the original data will not be modified.
+
+        Parameters
+        ----------
+        limit : int, optional
+            Limit of how many values to fill.
+
+        Returns
+        -------
+        Series, DataFrame
+            An upsampled Series or DataFrame with backward filled NaN values.
+
+        See Also
+        --------
+        bfill : Alias of backfill.
+        fillna : Fill NaN values using the specified method, which can be
+            'backfill'.
+        nearest : Fill NaN values with nearest neighbor starting from center.
+        ffill : Forward fill NaN values.
+        Series.fillna : Fill NaN values in the Series using the
+            specified method, which can be 'backfill'.
+        DataFrame.fillna : Fill NaN values in the DataFrame using the
+            specified method, which can be 'backfill'.
+
+        References
+        ----------
+        .. [1] https://en.wikipedia.org/wiki/Imputation_(statistics)
+
+        Examples
+        --------
+        Resampling a Series:
+
+        >>> s = pd.Series([1, 2, 3],
+        ...               index=pd.date_range('20180101', periods=3, freq='h'))
+        >>> s
+        2018-01-01 00:00:00    1
+        2018-01-01 01:00:00    2
+        2018-01-01 02:00:00    3
+        Freq: h, dtype: int64
+
+        >>> s.resample('30min').bfill()
+        2018-01-01 00:00:00    1
+        2018-01-01 00:30:00    2
+        2018-01-01 01:00:00    2
+        2018-01-01 01:30:00    3
+        2018-01-01 02:00:00    3
+        Freq: 30min, dtype: int64
+
+        >>> s.resample('15min').bfill(limit=2)
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:15:00    NaN
+        2018-01-01 00:30:00    2.0
+        2018-01-01 00:45:00    2.0
+        2018-01-01 01:00:00    2.0
+        2018-01-01 01:15:00    NaN
+        2018-01-01 01:30:00    3.0
+        2018-01-01 01:45:00    3.0
+        2018-01-01 02:00:00    3.0
+        Freq: 15min, dtype: float64
+
+        Resampling a DataFrame that has missing values:
+
+        >>> df = pd.DataFrame({'a': [2, np.nan, 6], 'b': [1, 3, 5]},
+        ...                   index=pd.date_range('20180101', periods=3,
+        ...                                       freq='h'))
+        >>> df
+                               a  b
+        2018-01-01 00:00:00  2.0  1
+        2018-01-01 01:00:00  NaN  3
+        2018-01-01 02:00:00  6.0  5
+
+        >>> df.resample('30min').bfill()
+                               a  b
+        2018-01-01 00:00:00  2.0  1
+        2018-01-01 00:30:00  NaN  3
+        2018-01-01 01:00:00  NaN  3
+        2018-01-01 01:30:00  6.0  5
+        2018-01-01 02:00:00  6.0  5
+
+        >>> df.resample('15min').bfill(limit=2)
+                               a    b
+        2018-01-01 00:00:00  2.0  1.0
+        2018-01-01 00:15:00  NaN  NaN
+        2018-01-01 00:30:00  NaN  3.0
+        2018-01-01 00:45:00  NaN  3.0
+        2018-01-01 01:00:00  NaN  3.0
+        2018-01-01 01:15:00  NaN  NaN
+        2018-01-01 01:30:00  6.0  5.0
+        2018-01-01 01:45:00  6.0  5.0
+        2018-01-01 02:00:00  6.0  5.0
+        """
+        return self._upsample("bfill", limit=limit)
+
+    @final
+    def fillna(self, method, limit: int | None = None):
+        """
+        Fill missing values introduced by upsampling.
+
+        In statistics, imputation is the process of replacing missing data with
+        substituted values [1]_. When resampling data, missing values may
+        appear (e.g., when the resampling frequency is higher than the original
+        frequency).
+
+        Missing values that existed in the original data will
+        not be modified.
+
+        Parameters
+        ----------
+        method : {'pad', 'backfill', 'ffill', 'bfill', 'nearest'}
+            Method to use for filling holes in resampled data
+
+            * 'pad' or 'ffill': use previous valid observation to fill gap
+              (forward fill).
+            * 'backfill' or 'bfill': use next valid observation to fill gap.
+            * 'nearest': use nearest valid observation to fill gap.
+
+        limit : int, optional
+            Limit of how many consecutive missing values to fill.
+
+        Returns
+        -------
+        Series or DataFrame
+            An upsampled Series or DataFrame with missing values filled.
+
+        See Also
+        --------
+        bfill : Backward fill NaN values in the resampled data.
+        ffill : Forward fill NaN values in the resampled data.
+        nearest : Fill NaN values in the resampled data
+            with nearest neighbor starting from center.
+        interpolate : Fill NaN values using interpolation.
+        Series.fillna : Fill NaN values in the Series using the
+            specified method, which can be 'bfill' and 'ffill'.
+        DataFrame.fillna : Fill NaN values in the DataFrame using the
+            specified method, which can be 'bfill' and 'ffill'.
+
+        References
+        ----------
+        .. [1] https://en.wikipedia.org/wiki/Imputation_(statistics)
+
+        Examples
+        --------
+        Resampling a Series:
+
+        >>> s = pd.Series([1, 2, 3],
+        ...               index=pd.date_range('20180101', periods=3, freq='h'))
+        >>> s
+        2018-01-01 00:00:00    1
+        2018-01-01 01:00:00    2
+        2018-01-01 02:00:00    3
+        Freq: h, dtype: int64
+
+        Without filling the missing values you get:
+
+        >>> s.resample("30min").asfreq()
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:30:00    NaN
+        2018-01-01 01:00:00    2.0
+        2018-01-01 01:30:00    NaN
+        2018-01-01 02:00:00    3.0
+        Freq: 30min, dtype: float64
+
+        >>> s.resample('30min').fillna("backfill")
+        2018-01-01 00:00:00    1
+        2018-01-01 00:30:00    2
+        2018-01-01 01:00:00    2
+        2018-01-01 01:30:00    3
+        2018-01-01 02:00:00    3
+        Freq: 30min, dtype: int64
+
+        >>> s.resample('15min').fillna("backfill", limit=2)
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:15:00    NaN
+        2018-01-01 00:30:00    2.0
+        2018-01-01 00:45:00    2.0
+        2018-01-01 01:00:00    2.0
+        2018-01-01 01:15:00    NaN
+        2018-01-01 01:30:00    3.0
+        2018-01-01 01:45:00    3.0
+        2018-01-01 02:00:00    3.0
+        Freq: 15min, dtype: float64
+
+        >>> s.resample('30min').fillna("pad")
+        2018-01-01 00:00:00    1
+        2018-01-01 00:30:00    1
+        2018-01-01 01:00:00    2
+        2018-01-01 01:30:00    2
+        2018-01-01 02:00:00    3
+        Freq: 30min, dtype: int64
+
+        >>> s.resample('30min').fillna("nearest")
+        2018-01-01 00:00:00    1
+        2018-01-01 00:30:00    2
+        2018-01-01 01:00:00    2
+        2018-01-01 01:30:00    3
+        2018-01-01 02:00:00    3
+        Freq: 30min, dtype: int64
+
+        Missing values present before the upsampling are not affected.
+
+        >>> sm = pd.Series([1, None, 3],
+        ...                index=pd.date_range('20180101', periods=3, freq='h'))
+        >>> sm
+        2018-01-01 00:00:00    1.0
+        2018-01-01 01:00:00    NaN
+        2018-01-01 02:00:00    3.0
+        Freq: h, dtype: float64
+
+        >>> sm.resample('30min').fillna('backfill')
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:30:00    NaN
+        2018-01-01 01:00:00    NaN
+        2018-01-01 01:30:00    3.0
+        2018-01-01 02:00:00    3.0
+        Freq: 30min, dtype: float64
+
+        >>> sm.resample('30min').fillna('pad')
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:30:00    1.0
+        2018-01-01 01:00:00    NaN
+        2018-01-01 01:30:00    NaN
+        2018-01-01 02:00:00    3.0
+        Freq: 30min, dtype: float64
+
+        >>> sm.resample('30min').fillna('nearest')
+        2018-01-01 00:00:00    1.0
+        2018-01-01 00:30:00    NaN
+        2018-01-01 01:00:00    NaN
+        2018-01-01 01:30:00    3.0
+        2018-01-01 02:00:00    3.0
+        Freq: 30min, dtype: float64
+
+        DataFrame resampling is done column-wise. All the same options are
+        available.
+
+        >>> df = pd.DataFrame({'a': [2, np.nan, 6], 'b': [1, 3, 5]},
+        ...                   index=pd.date_range('20180101', periods=3,
+        ...                                       freq='h'))
+        >>> df
+                               a  b
+        2018-01-01 00:00:00  2.0  1
+        2018-01-01 01:00:00  NaN  3
+        2018-01-01 02:00:00  6.0  5
+
+        >>> df.resample('30min').fillna("bfill")
+                               a  b
+        2018-01-01 00:00:00  2.0  1
+        2018-01-01 00:30:00  NaN  3
+        2018-01-01 01:00:00  NaN  3
+        2018-01-01 01:30:00  6.0  5
+        2018-01-01 02:00:00  6.0  5
+        """
+        warnings.warn(
+            f"{type(self).__name__}.fillna is deprecated and will be removed "
+            "in a future version. Use obj.ffill(), obj.bfill(), "
+            "or obj.nearest() instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self._upsample(method, limit=limit)
+
+    @final
+    def interpolate(
+        self,
+        method: InterpolateOptions = "linear",
+        *,
+        axis: Axis = 0,
+        limit: int | None = None,
+        inplace: bool = False,
+        limit_direction: Literal["forward", "backward", "both"] = "forward",
+        limit_area=None,
+        downcast=lib.no_default,
+        **kwargs,
+    ):
+        """
+        Interpolate values between target timestamps according to different methods.
+
+        The original index is first reindexed to target timestamps
+        (see :meth:`core.resample.Resampler.asfreq`),
+        then the interpolation of ``NaN`` values via :meth:`DataFrame.interpolate`
+        happens.
+
+        Parameters
+        ----------
+        method : str, default 'linear'
+            Interpolation technique to use. One of:
+
+            * 'linear': Ignore the index and treat the values as equally
+              spaced. This is the only method supported on MultiIndexes.
+            * 'time': Works on daily and higher resolution data to interpolate
+              given length of interval.
+            * 'index', 'values': use the actual numerical values of the index.
+            * 'pad': Fill in NaNs using existing values.
+            * 'nearest', 'zero', 'slinear', 'quadratic', 'cubic',
+              'barycentric', 'polynomial': Passed to
+              `scipy.interpolate.interp1d`, whereas 'spline' is passed to
+              `scipy.interpolate.UnivariateSpline`. These methods use the numerical
+              values of the index.  Both 'polynomial' and 'spline' require that
+              you also specify an `order` (int), e.g.
+              ``df.interpolate(method='polynomial', order=5)``. Note that,
+              `slinear` method in Pandas refers to the Scipy first order `spline`
+              instead of Pandas first order `spline`.
+            * 'krogh', 'piecewise_polynomial', 'spline', 'pchip', 'akima',
+              'cubicspline': Wrappers around the SciPy interpolation methods of
+              similar names. See `Notes`.
+            * 'from_derivatives': Refers to
+              `scipy.interpolate.BPoly.from_derivatives`.
+
+        axis : {{0 or 'index', 1 or 'columns', None}}, default None
+            Axis to interpolate along. For `Series` this parameter is unused
+            and defaults to 0.
+        limit : int, optional
+            Maximum number of consecutive NaNs to fill. Must be greater than
+            0.
+        inplace : bool, default False
+            Update the data in place if possible.
+        limit_direction : {{'forward', 'backward', 'both'}}, Optional
+            Consecutive NaNs will be filled in this direction.
+
+            If limit is specified:
+                * If 'method' is 'pad' or 'ffill', 'limit_direction' must be 'forward'.
+                * If 'method' is 'backfill' or 'bfill', 'limit_direction' must be
+                  'backwards'.
+
+            If 'limit' is not specified:
+                * If 'method' is 'backfill' or 'bfill', the default is 'backward'
+                * else the default is 'forward'
+
+                raises ValueError if `limit_direction` is 'forward' or 'both' and
+                    method is 'backfill' or 'bfill'.
+                raises ValueError if `limit_direction` is 'backward' or 'both' and
+                    method is 'pad' or 'ffill'.
+
+        limit_area : {{`None`, 'inside', 'outside'}}, default None
+            If limit is specified, consecutive NaNs will be filled with this
+            restriction.
+
+            * ``None``: No fill restriction.
+            * 'inside': Only fill NaNs surrounded by valid values
+              (interpolate).
+            * 'outside': Only fill NaNs outside valid values (extrapolate).
+
+        downcast : optional, 'infer' or None, defaults to None
+            Downcast dtypes if possible.
+
+            .. deprecated:: 2.1.0
+
+        ``**kwargs`` : optional
+            Keyword arguments to pass on to the interpolating function.
+
+        Returns
+        -------
+        DataFrame or Series
+            Interpolated values at the specified freq.
+
+        See Also
+        --------
+        core.resample.Resampler.asfreq: Return the values at the new freq,
+            essentially a reindex.
+        DataFrame.interpolate: Fill NaN values using an interpolation method.
+
+        Notes
+        -----
+        For high-frequent or non-equidistant time-series with timestamps
+        the reindexing followed by interpolation may lead to information loss
+        as shown in the last example.
+
+        Examples
+        --------
+
+        >>> start = "2023-03-01T07:00:00"
+        >>> timesteps = pd.date_range(start, periods=5, freq="s")
+        >>> series = pd.Series(data=[1, -1, 2, 1, 3], index=timesteps)
+        >>> series
+        2023-03-01 07:00:00    1
+        2023-03-01 07:00:01   -1
+        2023-03-01 07:00:02    2
+        2023-03-01 07:00:03    1
+        2023-03-01 07:00:04    3
+        Freq: s, dtype: int64
+
+        Upsample the dataframe to 0.5Hz by providing the period time of 2s.
+
+        >>> series.resample("2s").interpolate("linear")
+        2023-03-01 07:00:00    1
+        2023-03-01 07:00:02    2
+        2023-03-01 07:00:04    3
+        Freq: 2s, dtype: int64
+
+        Downsample the dataframe to 2Hz by providing the period time of 500ms.
+
+        >>> series.resample("500ms").interpolate("linear")
+        2023-03-01 07:00:00.000    1.0
+        2023-03-01 07:00:00.500    0.0
+        2023-03-01 07:00:01.000   -1.0
+        2023-03-01 07:00:01.500    0.5
+        2023-03-01 07:00:02.000    2.0
+        2023-03-01 07:00:02.500    1.5
+        2023-03-01 07:00:03.000    1.0
+        2023-03-01 07:00:03.500    2.0
+        2023-03-01 07:00:04.000    3.0
+        Freq: 500ms, dtype: float64
+
+        Internal reindexing with ``asfreq()`` prior to interpolation leads to
+        an interpolated timeseries on the basis the reindexed timestamps (anchors).
+        Since not all datapoints from original series become anchors,
+        it can lead to misleading interpolation results as in the following example:
+
+        >>> series.resample("400ms").interpolate("linear")
+        2023-03-01 07:00:00.000    1.0
+        2023-03-01 07:00:00.400    1.2
+        2023-03-01 07:00:00.800    1.4
+        2023-03-01 07:00:01.200    1.6
+        2023-03-01 07:00:01.600    1.8
+        2023-03-01 07:00:02.000    2.0
+        2023-03-01 07:00:02.400    2.2
+        2023-03-01 07:00:02.800    2.4
+        2023-03-01 07:00:03.200    2.6
+        2023-03-01 07:00:03.600    2.8
+        2023-03-01 07:00:04.000    3.0
+        Freq: 400ms, dtype: float64
+
+        Note that the series erroneously increases between two anchors
+        ``07:00:00`` and ``07:00:02``.
+        """
+        assert downcast is lib.no_default  # just checking coverage
+        result = self._upsample("asfreq")
+        return result.interpolate(
+            method=method,
+            axis=axis,
+            limit=limit,
+            inplace=inplace,
+            limit_direction=limit_direction,
+            limit_area=limit_area,
+            downcast=downcast,
+            **kwargs,
+        )
+
+    @final
+    def asfreq(self, fill_value=None):
+        """
+        Return the values at the new freq, essentially a reindex.
+
+        Parameters
+        ----------
+        fill_value : scalar, optional
+            Value to use for missing values, applied during upsampling (note
+            this does not fill NaNs that already were present).
+
+        Returns
+        -------
+        DataFrame or Series
+            Values at the specified freq.
+
+        See Also
+        --------
+        Series.asfreq: Convert TimeSeries to specified frequency.
+        DataFrame.asfreq: Convert TimeSeries to specified frequency.
+
+        Examples
+        --------
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-31', '2023-02-01', '2023-02-28']))
+        >>> ser
+        2023-01-01    1
+        2023-01-31    2
+        2023-02-01    3
+        2023-02-28    4
+        dtype: int64
+        >>> ser.resample('MS').asfreq()
+        2023-01-01    1
+        2023-02-01    3
+        Freq: MS, dtype: int64
+        """
+        return self._upsample("asfreq", fill_value=fill_value)
+
+    @final
+    def sum(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute sum of group values.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only no longer accepts ``None``.
+
+        min_count : int, default 0
+            The required number of valid values to perform the operation. If fewer
+            than ``min_count`` non-NA values are present the result will be NA.
+
+        Returns
+        -------
+        Series or DataFrame
+            Computed sum of values within each group.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').sum()
+        2023-01-01    3
+        2023-02-01    7
+        Freq: MS, dtype: int64
+        """
+        maybe_warn_args_and_kwargs(type(self), "sum", args, kwargs)
+        nv.validate_resampler_func("sum", args, kwargs)
+        return self._downsample("sum", numeric_only=numeric_only, min_count=min_count)
+
+    @final
+    def prod(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute prod of group values.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only float, int, boolean columns.
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only no longer accepts ``None``.
+
+        min_count : int, default 0
+            The required number of valid values to perform the operation. If fewer
+            than ``min_count`` non-NA values are present the result will be NA.
+
+        Returns
+        -------
+        Series or DataFrame
+            Computed prod of values within each group.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').prod()
+        2023-01-01    2
+        2023-02-01   12
+        Freq: MS, dtype: int64
+        """
+        maybe_warn_args_and_kwargs(type(self), "prod", args, kwargs)
+        nv.validate_resampler_func("prod", args, kwargs)
+        return self._downsample("prod", numeric_only=numeric_only, min_count=min_count)
+
+    @final
+    def min(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute min value of group.
+
+        Returns
+        -------
+        Series or DataFrame
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').min()
+        2023-01-01    1
+        2023-02-01    3
+        Freq: MS, dtype: int64
+        """
+
+        maybe_warn_args_and_kwargs(type(self), "min", args, kwargs)
+        nv.validate_resampler_func("min", args, kwargs)
+        return self._downsample("min", numeric_only=numeric_only, min_count=min_count)
+
+    @final
+    def max(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute max value of group.
+
+        Returns
+        -------
+        Series or DataFrame
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').max()
+        2023-01-01    2
+        2023-02-01    4
+        Freq: MS, dtype: int64
+        """
+        maybe_warn_args_and_kwargs(type(self), "max", args, kwargs)
+        nv.validate_resampler_func("max", args, kwargs)
+        return self._downsample("max", numeric_only=numeric_only, min_count=min_count)
+
+    @final
+    @doc(GroupBy.first)
+    def first(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        skipna: bool = True,
+        *args,
+        **kwargs,
+    ):
+        maybe_warn_args_and_kwargs(type(self), "first", args, kwargs)
+        nv.validate_resampler_func("first", args, kwargs)
+        return self._downsample(
+            "first", numeric_only=numeric_only, min_count=min_count, skipna=skipna
+        )
+
+    @final
+    @doc(GroupBy.last)
+    def last(
+        self,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        skipna: bool = True,
+        *args,
+        **kwargs,
+    ):
+        maybe_warn_args_and_kwargs(type(self), "last", args, kwargs)
+        nv.validate_resampler_func("last", args, kwargs)
+        return self._downsample(
+            "last", numeric_only=numeric_only, min_count=min_count, skipna=skipna
+        )
+
+    @final
+    @doc(GroupBy.median)
+    def median(self, numeric_only: bool = False, *args, **kwargs):
+        maybe_warn_args_and_kwargs(type(self), "median", args, kwargs)
+        nv.validate_resampler_func("median", args, kwargs)
+        return self._downsample("median", numeric_only=numeric_only)
+
+    @final
+    def mean(
+        self,
+        numeric_only: bool = False,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute mean of groups, excluding missing values.
+
+        Parameters
+        ----------
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        DataFrame or Series
+            Mean of values within each group.
+
+        Examples
+        --------
+
+        >>> ser = pd.Series([1, 2, 3, 4], index=pd.DatetimeIndex(
+        ...                 ['2023-01-01', '2023-01-15', '2023-02-01', '2023-02-15']))
+        >>> ser
+        2023-01-01    1
+        2023-01-15    2
+        2023-02-01    3
+        2023-02-15    4
+        dtype: int64
+        >>> ser.resample('MS').mean()
+        2023-01-01    1.5
+        2023-02-01    3.5
+        Freq: MS, dtype: float64
+        """
+        maybe_warn_args_and_kwargs(type(self), "mean", args, kwargs)
+        nv.validate_resampler_func("mean", args, kwargs)
+        return self._downsample("mean", numeric_only=numeric_only)
+
+    @final
+    def std(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute standard deviation of groups, excluding missing values.
+
+        Parameters
+        ----------
+        ddof : int, default 1
+            Degrees of freedom.
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        DataFrame or Series
+            Standard deviation of values within each group.
+
+        Examples
+        --------
+
+        >>> ser = pd.Series([1, 3, 2, 4, 3, 8],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').std()
+        2023-01-01    1.000000
+        2023-02-01    2.645751
+        Freq: MS, dtype: float64
+        """
+        maybe_warn_args_and_kwargs(type(self), "std", args, kwargs)
+        nv.validate_resampler_func("std", args, kwargs)
+        return self._downsample("std", ddof=ddof, numeric_only=numeric_only)
+
+    @final
+    def var(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        *args,
+        **kwargs,
+    ):
+        """
+        Compute variance of groups, excluding missing values.
+
+        Parameters
+        ----------
+        ddof : int, default 1
+            Degrees of freedom.
+
+        numeric_only : bool, default False
+            Include only `float`, `int` or `boolean` data.
+
+            .. versionadded:: 1.5.0
+
+            .. versionchanged:: 2.0.0
+
+                numeric_only now defaults to ``False``.
+
+        Returns
+        -------
+        DataFrame or Series
+            Variance of values within each group.
+
+        Examples
+        --------
+
+        >>> ser = pd.Series([1, 3, 2, 4, 3, 8],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').var()
+        2023-01-01    1.0
+        2023-02-01    7.0
+        Freq: MS, dtype: float64
+
+        >>> ser.resample('MS').var(ddof=0)
+        2023-01-01    0.666667
+        2023-02-01    4.666667
+        Freq: MS, dtype: float64
+        """
+        maybe_warn_args_and_kwargs(type(self), "var", args, kwargs)
+        nv.validate_resampler_func("var", args, kwargs)
+        return self._downsample("var", ddof=ddof, numeric_only=numeric_only)
+
+    @final
+    @doc(GroupBy.sem)
+    def sem(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        *args,
+        **kwargs,
+    ):
+        maybe_warn_args_and_kwargs(type(self), "sem", args, kwargs)
+        nv.validate_resampler_func("sem", args, kwargs)
+        return self._downsample("sem", ddof=ddof, numeric_only=numeric_only)
+
+    @final
+    @doc(GroupBy.ohlc)
+    def ohlc(
+        self,
+        *args,
+        **kwargs,
+    ):
+        maybe_warn_args_and_kwargs(type(self), "ohlc", args, kwargs)
+        nv.validate_resampler_func("ohlc", args, kwargs)
+
+        ax = self.ax
+        obj = self._obj_with_exclusions
+        if len(ax) == 0:
+            # GH#42902
+            obj = obj.copy()
+            obj.index = _asfreq_compat(obj.index, self.freq)
+            if obj.ndim == 1:
+                obj = obj.to_frame()
+                obj = obj.reindex(["open", "high", "low", "close"], axis=1)
+            else:
+                mi = MultiIndex.from_product(
+                    [obj.columns, ["open", "high", "low", "close"]]
+                )
+                obj = obj.reindex(mi, axis=1)
+            return obj
+
+        return self._downsample("ohlc")
+
+    @final
+    @doc(SeriesGroupBy.nunique)
+    def nunique(
+        self,
+        *args,
+        **kwargs,
+    ):
+        maybe_warn_args_and_kwargs(type(self), "nunique", args, kwargs)
+        nv.validate_resampler_func("nunique", args, kwargs)
+        return self._downsample("nunique")
+
+    @final
+    @doc(GroupBy.size)
+    def size(self):
+        result = self._downsample("size")
+
+        # If the result is a non-empty DataFrame we stack to get a Series
+        # GH 46826
+        if isinstance(result, ABCDataFrame) and not result.empty:
+            result = result.stack(future_stack=True)
+
+        if not len(self.ax):
+            from pandas import Series
+
+            if self._selected_obj.ndim == 1:
+                name = self._selected_obj.name
+            else:
+                name = None
+            result = Series([], index=result.index, dtype="int64", name=name)
+        return result
+
+    @final
+    @doc(GroupBy.count)
+    def count(self):
+        result = self._downsample("count")
+        if not len(self.ax):
+            if self._selected_obj.ndim == 1:
+                result = type(self._selected_obj)(
+                    [], index=result.index, dtype="int64", name=self._selected_obj.name
+                )
+            else:
+                from pandas import DataFrame
+
+                result = DataFrame(
+                    [], index=result.index, columns=result.columns, dtype="int64"
+                )
+
+        return result
+
+    @final
+    def quantile(self, q: float | list[float] | AnyArrayLike = 0.5, **kwargs):
+        """
+        Return value at the given quantile.
+
+        Parameters
+        ----------
+        q : float or array-like, default 0.5 (50% quantile)
+
+        Returns
+        -------
+        DataFrame or Series
+            Quantile of values within each group.
+
+        See Also
+        --------
+        Series.quantile
+            Return a series, where the index is q and the values are the quantiles.
+        DataFrame.quantile
+            Return a DataFrame, where the columns are the columns of self,
+            and the values are the quantiles.
+        DataFrameGroupBy.quantile
+            Return a DataFrame, where the columns are groupby columns,
+            and the values are its quantiles.
+
+        Examples
+        --------
+
+        >>> ser = pd.Series([1, 3, 2, 4, 3, 8],
+        ...                 index=pd.DatetimeIndex(['2023-01-01',
+        ...                                         '2023-01-10',
+        ...                                         '2023-01-15',
+        ...                                         '2023-02-01',
+        ...                                         '2023-02-10',
+        ...                                         '2023-02-15']))
+        >>> ser.resample('MS').quantile()
+        2023-01-01    2.0
+        2023-02-01    4.0
+        Freq: MS, dtype: float64
+
+        >>> ser.resample('MS').quantile(.25)
+        2023-01-01    1.5
+        2023-02-01    3.5
+        Freq: MS, dtype: float64
+        """
+        return self._downsample("quantile", q=q, **kwargs)
+
+
+class _GroupByMixin(PandasObject, SelectionMixin):
+    """
+    Provide the groupby facilities.
+    """
+
+    _attributes: list[str]  # in practice the same as Resampler._attributes
+    _selection: IndexLabel | None = None
+    _groupby: GroupBy
+    _timegrouper: TimeGrouper
+
+    def __init__(
+        self,
+        *,
+        parent: Resampler,
+        groupby: GroupBy,
+        key=None,
+        selection: IndexLabel | None = None,
+        include_groups: bool = False,
+    ) -> None:
+        # reached via ._gotitem and _get_resampler_for_grouping
+
+        assert isinstance(groupby, GroupBy), type(groupby)
+
+        # parent is always a Resampler, sometimes a _GroupByMixin
+        assert isinstance(parent, Resampler), type(parent)
+
+        # initialize our GroupByMixin object with
+        # the resampler attributes
+        for attr in self._attributes:
+            setattr(self, attr, getattr(parent, attr))
+        self._selection = selection
+
+        self.binner = parent.binner
+        self.key = key
+
+        self._groupby = groupby
+        self._timegrouper = copy.copy(parent._timegrouper)
+
+        self.ax = parent.ax
+        self.obj = parent.obj
+        self.include_groups = include_groups
+
+    @no_type_check
+    def _apply(self, f, *args, **kwargs):
+        """
+        Dispatch to _upsample; we are stripping all of the _upsample kwargs and
+        performing the original function call on the grouped object.
+        """
+
+        def func(x):
+            x = self._resampler_cls(x, timegrouper=self._timegrouper, gpr_index=self.ax)
+
+            if isinstance(f, str):
+                return getattr(x, f)(**kwargs)
+
+            return x.apply(f, *args, **kwargs)
+
+        result = _apply(self._groupby, func, include_groups=self.include_groups)
+        return self._wrap_result(result)
+
+    _upsample = _apply
+    _downsample = _apply
+    _groupby_and_aggregate = _apply
+
+    @final
+    def _gotitem(self, key, ndim, subset=None):
+        """
+        Sub-classes to define. Return a sliced object.
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        # create a new object to prevent aliasing
+        if subset is None:
+            subset = self.obj
+            if key is not None:
+                subset = subset[key]
+            else:
+                # reached via Apply.agg_dict_like with selection=None, ndim=1
+                assert subset.ndim == 1
+
+        # Try to select from a DataFrame, falling back to a Series
+        try:
+            if isinstance(key, list) and self.key not in key and self.key is not None:
+                key.append(self.key)
+            groupby = self._groupby[key]
+        except IndexError:
+            groupby = self._groupby
+
+        selection = self._infer_selection(key, subset)
+
+        new_rs = type(self)(
+            groupby=groupby,
+            parent=cast(Resampler, self),
+            selection=selection,
+        )
+        return new_rs
+
+
+class DatetimeIndexResampler(Resampler):
+    ax: DatetimeIndex
+
+    @property
+    def _resampler_for_grouping(self):
+        return DatetimeIndexResamplerGroupby
+
+    def _get_binner_for_time(self):
+        # this is how we are actually creating the bins
+        if self.kind == "period":
+            return self._timegrouper._get_time_period_bins(self.ax)
+        return self._timegrouper._get_time_bins(self.ax)
+
+    def _downsample(self, how, **kwargs):
+        """
+        Downsample the cython defined function.
+
+        Parameters
+        ----------
+        how : string / cython mapped function
+        **kwargs : kw args passed to how function
+        """
+        orig_how = how
+        how = com.get_cython_func(how) or how
+        if orig_how != how:
+            warn_alias_replacement(self, orig_how, how)
+        ax = self.ax
+
+        # Excludes `on` column when provided
+        obj = self._obj_with_exclusions
+
+        if not len(ax):
+            # reset to the new freq
+            obj = obj.copy()
+            obj.index = obj.index._with_freq(self.freq)
+            assert obj.index.freq == self.freq, (obj.index.freq, self.freq)
+            return obj
+
+        # do we have a regular frequency
+
+        # error: Item "None" of "Optional[Any]" has no attribute "binlabels"
+        if (
+            (ax.freq is not None or ax.inferred_freq is not None)
+            and len(self._grouper.binlabels) > len(ax)
+            and how is None
+        ):
+            # let's do an asfreq
+            return self.asfreq()
+
+        # we are downsampling
+        # we want to call the actual grouper method here
+        if self.axis == 0:
+            result = obj.groupby(self._grouper).aggregate(how, **kwargs)
+        else:
+            # test_resample_axis1
+            result = obj.T.groupby(self._grouper).aggregate(how, **kwargs).T
+
+        return self._wrap_result(result)
+
+    def _adjust_binner_for_upsample(self, binner):
+        """
+        Adjust our binner when upsampling.
+
+        The range of a new index should not be outside specified range
+        """
+        if self.closed == "right":
+            binner = binner[1:]
+        else:
+            binner = binner[:-1]
+        return binner
+
+    def _upsample(self, method, limit: int | None = None, fill_value=None):
+        """
+        Parameters
+        ----------
+        method : string {'backfill', 'bfill', 'pad',
+            'ffill', 'asfreq'} method for upsampling
+        limit : int, default None
+            Maximum size gap to fill when reindexing
+        fill_value : scalar, default None
+            Value to use for missing values
+
+        See Also
+        --------
+        .fillna: Fill NA/NaN values using the specified method.
+
+        """
+        if self.axis:
+            raise AssertionError("axis must be 0")
+        if self._from_selection:
+            raise ValueError(
+                "Upsampling from level= or on= selection "
+                "is not supported, use .set_index(...) "
+                "to explicitly set index to datetime-like"
+            )
+
+        ax = self.ax
+        obj = self._selected_obj
+        binner = self.binner
+        res_index = self._adjust_binner_for_upsample(binner)
+
+        # if we have the same frequency as our axis, then we are equal sampling
+        if (
+            limit is None
+            and to_offset(ax.inferred_freq) == self.freq
+            and len(obj) == len(res_index)
+        ):
+            result = obj.copy()
+            result.index = res_index
+        else:
+            if method == "asfreq":
+                method = None
+            result = obj.reindex(
+                res_index, method=method, limit=limit, fill_value=fill_value
+            )
+
+        return self._wrap_result(result)
+
+    def _wrap_result(self, result):
+        result = super()._wrap_result(result)
+
+        # we may have a different kind that we were asked originally
+        # convert if needed
+        if self.kind == "period" and not isinstance(result.index, PeriodIndex):
+            if isinstance(result.index, MultiIndex):
+                # GH 24103 - e.g. groupby resample
+                if not isinstance(result.index.levels[-1], PeriodIndex):
+                    new_level = result.index.levels[-1].to_period(self.freq)
+                    result.index = result.index.set_levels(new_level, level=-1)
+            else:
+                result.index = result.index.to_period(self.freq)
+        return result
+
+
+# error: Definition of "ax" in base class "_GroupByMixin" is incompatible
+# with definition in base class "DatetimeIndexResampler"
+class DatetimeIndexResamplerGroupby(  # type: ignore[misc]
+    _GroupByMixin, DatetimeIndexResampler
+):
+    """
+    Provides a resample of a groupby implementation
+    """
+
+    @property
+    def _resampler_cls(self):
+        return DatetimeIndexResampler
+
+
+class PeriodIndexResampler(DatetimeIndexResampler):
+    # error: Incompatible types in assignment (expression has type "PeriodIndex", base
+    # class "DatetimeIndexResampler" defined the type as "DatetimeIndex")
+    ax: PeriodIndex  # type: ignore[assignment]
+
+    @property
+    def _resampler_for_grouping(self):
+        return PeriodIndexResamplerGroupby
+
+    def _get_binner_for_time(self):
+        if self.kind == "timestamp":
+            return super()._get_binner_for_time()
+        return self._timegrouper._get_period_bins(self.ax)
+
+    def _convert_obj(self, obj: NDFrameT) -> NDFrameT:
+        obj = super()._convert_obj(obj)
+
+        if self._from_selection:
+            # see GH 14008, GH 12871
+            msg = (
+                "Resampling from level= or on= selection "
+                "with a PeriodIndex is not currently supported, "
+                "use .set_index(...) to explicitly set index"
+            )
+            raise NotImplementedError(msg)
+
+        # convert to timestamp
+        if self.kind == "timestamp":
+            obj = obj.to_timestamp(how=self.convention)
+
+        return obj
+
+    def _downsample(self, how, **kwargs):
+        """
+        Downsample the cython defined function.
+
+        Parameters
+        ----------
+        how : string / cython mapped function
+        **kwargs : kw args passed to how function
+        """
+        # we may need to actually resample as if we are timestamps
+        if self.kind == "timestamp":
+            return super()._downsample(how, **kwargs)
+
+        orig_how = how
+        how = com.get_cython_func(how) or how
+        if orig_how != how:
+            warn_alias_replacement(self, orig_how, how)
+        ax = self.ax
+
+        if is_subperiod(ax.freq, self.freq):
+            # Downsampling
+            return self._groupby_and_aggregate(how, **kwargs)
+        elif is_superperiod(ax.freq, self.freq):
+            if how == "ohlc":
+                # GH #13083
+                # upsampling to subperiods is handled as an asfreq, which works
+                # for pure aggregating/reducing methods
+                # OHLC reduces along the time dimension, but creates multiple
+                # values for each period -> handle by _groupby_and_aggregate()
+                return self._groupby_and_aggregate(how)
+            return self.asfreq()
+        elif ax.freq == self.freq:
+            return self.asfreq()
+
+        raise IncompatibleFrequency(
+            f"Frequency {ax.freq} cannot be resampled to {self.freq}, "
+            "as they are not sub or super periods"
+        )
+
+    def _upsample(self, method, limit: int | None = None, fill_value=None):
+        """
+        Parameters
+        ----------
+        method : {'backfill', 'bfill', 'pad', 'ffill'}
+            Method for upsampling.
+        limit : int, default None
+            Maximum size gap to fill when reindexing.
+        fill_value : scalar, default None
+            Value to use for missing values.
+
+        See Also
+        --------
+        .fillna: Fill NA/NaN values using the specified method.
+
+        """
+        # we may need to actually resample as if we are timestamps
+        if self.kind == "timestamp":
+            return super()._upsample(method, limit=limit, fill_value=fill_value)
+
+        ax = self.ax
+        obj = self.obj
+        new_index = self.binner
+
+        # Start vs. end of period
+        memb = ax.asfreq(self.freq, how=self.convention)
+
+        # Get the fill indexer
+        if method == "asfreq":
+            method = None
+        indexer = memb.get_indexer(new_index, method=method, limit=limit)
+        new_obj = _take_new_index(
+            obj,
+            indexer,
+            new_index,
+            axis=self.axis,
+        )
+        return self._wrap_result(new_obj)
+
+
+# error: Definition of "ax" in base class "_GroupByMixin" is incompatible with
+# definition in base class "PeriodIndexResampler"
+class PeriodIndexResamplerGroupby(  # type: ignore[misc]
+    _GroupByMixin, PeriodIndexResampler
+):
+    """
+    Provides a resample of a groupby implementation.
+    """
+
+    @property
+    def _resampler_cls(self):
+        return PeriodIndexResampler
+
+
+class TimedeltaIndexResampler(DatetimeIndexResampler):
+    # error: Incompatible types in assignment (expression has type "TimedeltaIndex",
+    # base class "DatetimeIndexResampler" defined the type as "DatetimeIndex")
+    ax: TimedeltaIndex  # type: ignore[assignment]
+
+    @property
+    def _resampler_for_grouping(self):
+        return TimedeltaIndexResamplerGroupby
+
+    def _get_binner_for_time(self):
+        return self._timegrouper._get_time_delta_bins(self.ax)
+
+    def _adjust_binner_for_upsample(self, binner):
+        """
+        Adjust our binner when upsampling.
+
+        The range of a new index is allowed to be greater than original range
+        so we don't need to change the length of a binner, GH 13022
+        """
+        return binner
+
+
+# error: Definition of "ax" in base class "_GroupByMixin" is incompatible with
+# definition in base class "DatetimeIndexResampler"
+class TimedeltaIndexResamplerGroupby(  # type: ignore[misc]
+    _GroupByMixin, TimedeltaIndexResampler
+):
+    """
+    Provides a resample of a groupby implementation.
+    """
+
+    @property
+    def _resampler_cls(self):
+        return TimedeltaIndexResampler
+
+
+def get_resampler(obj: Series | DataFrame, kind=None, **kwds) -> Resampler:
+    """
+    Create a TimeGrouper and return our resampler.
+    """
+    tg = TimeGrouper(obj, **kwds)  # type: ignore[arg-type]
+    return tg._get_resampler(obj, kind=kind)
+
+
+get_resampler.__doc__ = Resampler.__doc__
+
+
+def get_resampler_for_grouping(
+    groupby: GroupBy,
+    rule,
+    how=None,
+    fill_method=None,
+    limit: int | None = None,
+    kind=None,
+    on=None,
+    include_groups: bool = True,
+    **kwargs,
+) -> Resampler:
+    """
+    Return our appropriate resampler when grouping as well.
+    """
+    # .resample uses 'on' similar to how .groupby uses 'key'
+    tg = TimeGrouper(freq=rule, key=on, **kwargs)
+    resampler = tg._get_resampler(groupby.obj, kind=kind)
+    return resampler._get_resampler_for_grouping(
+        groupby=groupby, include_groups=include_groups, key=tg.key
+    )
+
+
+class TimeGrouper(Grouper):
+    """
+    Custom groupby class for time-interval grouping.
+
+    Parameters
+    ----------
+    freq : pandas date offset or offset alias for identifying bin edges
+    closed : closed end of interval; 'left' or 'right'
+    label : interval boundary to use for labeling; 'left' or 'right'
+    convention : {'start', 'end', 'e', 's'}
+        If axis is PeriodIndex
+    """
+
+    _attributes = Grouper._attributes + (
+        "closed",
+        "label",
+        "how",
+        "kind",
+        "convention",
+        "origin",
+        "offset",
+    )
+
+    origin: TimeGrouperOrigin
+
+    def __init__(
+        self,
+        obj: Grouper | None = None,
+        freq: Frequency = "Min",
+        key: str | None = None,
+        closed: Literal["left", "right"] | None = None,
+        label: Literal["left", "right"] | None = None,
+        how: str = "mean",
+        axis: Axis = 0,
+        fill_method=None,
+        limit: int | None = None,
+        kind: str | None = None,
+        convention: Literal["start", "end", "e", "s"] | None = None,
+        origin: Literal["epoch", "start", "start_day", "end", "end_day"]
+        | TimestampConvertibleTypes = "start_day",
+        offset: TimedeltaConvertibleTypes | None = None,
+        group_keys: bool = False,
+        **kwargs,
+    ) -> None:
+        # Check for correctness of the keyword arguments which would
+        # otherwise silently use the default if misspelled
+        if label not in {None, "left", "right"}:
+            raise ValueError(f"Unsupported value {label} for `label`")
+        if closed not in {None, "left", "right"}:
+            raise ValueError(f"Unsupported value {closed} for `closed`")
+        if convention not in {None, "start", "end", "e", "s"}:
+            raise ValueError(f"Unsupported value {convention} for `convention`")
+
+        if (
+            key is None
+            and obj is not None
+            and isinstance(obj.index, PeriodIndex)  # type: ignore[attr-defined]
+            or (
+                key is not None
+                and obj is not None
+                and getattr(obj[key], "dtype", None) == "period"  # type: ignore[index]
+            )
+        ):
+            freq = to_offset(freq, is_period=True)
+        else:
+            freq = to_offset(freq)
+
+        end_types = {"ME", "YE", "QE", "BME", "BYE", "BQE", "W"}
+        rule = freq.rule_code
+        if rule in end_types or ("-" in rule and rule[: rule.find("-")] in end_types):
+            if closed is None:
+                closed = "right"
+            if label is None:
+                label = "right"
+        else:
+            # The backward resample sets ``closed`` to ``'right'`` by default
+            # since the last value should be considered as the edge point for
+            # the last bin. When origin in "end" or "end_day", the value for a
+            # specific ``Timestamp`` index stands for the resample result from
+            # the current ``Timestamp`` minus ``freq`` to the current
+            # ``Timestamp`` with a right close.
+            if origin in ["end", "end_day"]:
+                if closed is None:
+                    closed = "right"
+                if label is None:
+                    label = "right"
+            else:
+                if closed is None:
+                    closed = "left"
+                if label is None:
+                    label = "left"
+
+        self.closed = closed
+        self.label = label
+        self.kind = kind
+        self.convention = convention if convention is not None else "e"
+        self.how = how
+        self.fill_method = fill_method
+        self.limit = limit
+        self.group_keys = group_keys
+        self._arrow_dtype: ArrowDtype | None = None
+
+        if origin in ("epoch", "start", "start_day", "end", "end_day"):
+            # error: Incompatible types in assignment (expression has type "Union[Union[
+            # Timestamp, datetime, datetime64, signedinteger[_64Bit], float, str],
+            # Literal['epoch', 'start', 'start_day', 'end', 'end_day']]", variable has
+            # type "Union[Timestamp, Literal['epoch', 'start', 'start_day', 'end',
+            # 'end_day']]")
+            self.origin = origin  # type: ignore[assignment]
+        else:
+            try:
+                self.origin = Timestamp(origin)
+            except (ValueError, TypeError) as err:
+                raise ValueError(
+                    "'origin' should be equal to 'epoch', 'start', 'start_day', "
+                    "'end', 'end_day' or "
+                    f"should be a Timestamp convertible type. Got '{origin}' instead."
+                ) from err
+
+        try:
+            self.offset = Timedelta(offset) if offset is not None else None
+        except (ValueError, TypeError) as err:
+            raise ValueError(
+                "'offset' should be a Timedelta convertible type. "
+                f"Got '{offset}' instead."
+            ) from err
+
+        # always sort time groupers
+        kwargs["sort"] = True
+
+        super().__init__(freq=freq, key=key, axis=axis, **kwargs)
+
+    def _get_resampler(self, obj: NDFrame, kind=None) -> Resampler:
+        """
+        Return my resampler or raise if we have an invalid axis.
+
+        Parameters
+        ----------
+        obj : Series or DataFrame
+        kind : string, optional
+            'period','timestamp','timedelta' are valid
+
+        Returns
+        -------
+        Resampler
+
+        Raises
+        ------
+        TypeError if incompatible axis
+
+        """
+        _, ax, _ = self._set_grouper(obj, gpr_index=None)
+        if isinstance(ax, DatetimeIndex):
+            return DatetimeIndexResampler(
+                obj,
+                timegrouper=self,
+                kind=kind,
+                axis=self.axis,
+                group_keys=self.group_keys,
+                gpr_index=ax,
+            )
+        elif isinstance(ax, PeriodIndex) or kind == "period":
+            if not isinstance(ax, PeriodIndex):
+                warnings.warn(
+                    "Resampling with kind='period' is deprecated.  "
+                    "Use datetime paths instead.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            return PeriodIndexResampler(
+                obj,
+                timegrouper=self,
+                kind=kind,
+                axis=self.axis,
+                group_keys=self.group_keys,
+                gpr_index=ax,
+            )
+        elif isinstance(ax, TimedeltaIndex):
+            return TimedeltaIndexResampler(
+                obj,
+                timegrouper=self,
+                axis=self.axis,
+                group_keys=self.group_keys,
+                gpr_index=ax,
+            )
+
+        raise TypeError(
+            "Only valid with DatetimeIndex, "
+            "TimedeltaIndex or PeriodIndex, "
+            f"but got an instance of '{type(ax).__name__}'"
+        )
+
+    def _get_grouper(
+        self, obj: NDFrameT, validate: bool = True
+    ) -> tuple[BinGrouper, NDFrameT]:
+        # create the resampler and return our binner
+        r = self._get_resampler(obj)
+        return r._grouper, cast(NDFrameT, r.obj)
+
+    def _get_time_bins(self, ax: DatetimeIndex):
+        if not isinstance(ax, DatetimeIndex):
+            raise TypeError(
+                "axis must be a DatetimeIndex, but got "
+                f"an instance of {type(ax).__name__}"
+            )
+
+        if len(ax) == 0:
+            binner = labels = DatetimeIndex(
+                data=[], freq=self.freq, name=ax.name, dtype=ax.dtype
+            )
+            return binner, [], labels
+
+        first, last = _get_timestamp_range_edges(
+            ax.min(),
+            ax.max(),
+            self.freq,
+            unit=ax.unit,
+            closed=self.closed,
+            origin=self.origin,
+            offset=self.offset,
+        )
+        # GH #12037
+        # use first/last directly instead of call replace() on them
+        # because replace() will swallow the nanosecond part
+        # thus last bin maybe slightly before the end if the end contains
+        # nanosecond part and lead to `Values falls after last bin` error
+        # GH 25758: If DST lands at midnight (e.g. 'America/Havana'), user feedback
+        # has noted that ambiguous=True provides the most sensible result
+        binner = labels = date_range(
+            freq=self.freq,
+            start=first,
+            end=last,
+            tz=ax.tz,
+            name=ax.name,
+            ambiguous=True,
+            nonexistent="shift_forward",
+            unit=ax.unit,
+        )
+
+        ax_values = ax.asi8
+        binner, bin_edges = self._adjust_bin_edges(binner, ax_values)
+
+        # general version, knowing nothing about relative frequencies
+        bins = lib.generate_bins_dt64(
+            ax_values, bin_edges, self.closed, hasnans=ax.hasnans
+        )
+
+        if self.closed == "right":
+            labels = binner
+            if self.label == "right":
+                labels = labels[1:]
+        elif self.label == "right":
+            labels = labels[1:]
+
+        if ax.hasnans:
+            binner = binner.insert(0, NaT)
+            labels = labels.insert(0, NaT)
+
+        # if we end up with more labels than bins
+        # adjust the labels
+        # GH4076
+        if len(bins) < len(labels):
+            labels = labels[: len(bins)]
+
+        return binner, bins, labels
+
+    def _adjust_bin_edges(
+        self, binner: DatetimeIndex, ax_values: npt.NDArray[np.int64]
+    ) -> tuple[DatetimeIndex, npt.NDArray[np.int64]]:
+        # Some hacks for > daily data, see #1471, #1458, #1483
+
+        if self.freq.name in ("BME", "ME", "W") or self.freq.name.split("-")[0] in (
+            "BQE",
+            "BYE",
+            "QE",
+            "YE",
+            "W",
+        ):
+            # If the right end-point is on the last day of the month, roll forwards
+            # until the last moment of that day. Note that we only do this for offsets
+            # which correspond to the end of a super-daily period - "month start", for
+            # example, is excluded.
+            if self.closed == "right":
+                # GH 21459, GH 9119: Adjust the bins relative to the wall time
+                edges_dti = binner.tz_localize(None)
+                edges_dti = (
+                    edges_dti
+                    + Timedelta(days=1, unit=edges_dti.unit).as_unit(edges_dti.unit)
+                    - Timedelta(1, unit=edges_dti.unit).as_unit(edges_dti.unit)
+                )
+                bin_edges = edges_dti.tz_localize(binner.tz).asi8
+            else:
+                bin_edges = binner.asi8
+
+            # intraday values on last day
+            if bin_edges[-2] > ax_values.max():
+                bin_edges = bin_edges[:-1]
+                binner = binner[:-1]
+        else:
+            bin_edges = binner.asi8
+        return binner, bin_edges
+
+    def _get_time_delta_bins(self, ax: TimedeltaIndex):
+        if not isinstance(ax, TimedeltaIndex):
+            raise TypeError(
+                "axis must be a TimedeltaIndex, but got "
+                f"an instance of {type(ax).__name__}"
+            )
+
+        if not isinstance(self.freq, Tick):
+            # GH#51896
+            raise ValueError(
+                "Resampling on a TimedeltaIndex requires fixed-duration `freq`, "
+                f"e.g. '24h' or '3D', not {self.freq}"
+            )
+
+        if not len(ax):
+            binner = labels = TimedeltaIndex(data=[], freq=self.freq, name=ax.name)
+            return binner, [], labels
+
+        start, end = ax.min(), ax.max()
+
+        if self.closed == "right":
+            end += self.freq
+
+        labels = binner = timedelta_range(
+            start=start, end=end, freq=self.freq, name=ax.name
+        )
+
+        end_stamps = labels
+        if self.closed == "left":
+            end_stamps += self.freq
+
+        bins = ax.searchsorted(end_stamps, side=self.closed)
+
+        if self.offset:
+            # GH 10530 & 31809
+            labels += self.offset
+
+        return binner, bins, labels
+
+    def _get_time_period_bins(self, ax: DatetimeIndex):
+        if not isinstance(ax, DatetimeIndex):
+            raise TypeError(
+                "axis must be a DatetimeIndex, but got "
+                f"an instance of {type(ax).__name__}"
+            )
+
+        freq = self.freq
+
+        if len(ax) == 0:
+            binner = labels = PeriodIndex(
+                data=[], freq=freq, name=ax.name, dtype=ax.dtype
+            )
+            return binner, [], labels
+
+        labels = binner = period_range(start=ax[0], end=ax[-1], freq=freq, name=ax.name)
+
+        end_stamps = (labels + freq).asfreq(freq, "s").to_timestamp()
+        if ax.tz:
+            end_stamps = end_stamps.tz_localize(ax.tz)
+        bins = ax.searchsorted(end_stamps, side="left")
+
+        return binner, bins, labels
+
+    def _get_period_bins(self, ax: PeriodIndex):
+        if not isinstance(ax, PeriodIndex):
+            raise TypeError(
+                "axis must be a PeriodIndex, but got "
+                f"an instance of {type(ax).__name__}"
+            )
+
+        memb = ax.asfreq(self.freq, how=self.convention)
+
+        # NaT handling as in pandas._lib.lib.generate_bins_dt64()
+        nat_count = 0
+        if memb.hasnans:
+            # error: Incompatible types in assignment (expression has type
+            # "bool_", variable has type "int")  [assignment]
+            nat_count = np.sum(memb._isnan)  # type: ignore[assignment]
+            memb = memb[~memb._isnan]
+
+        if not len(memb):
+            # index contains no valid (non-NaT) values
+            bins = np.array([], dtype=np.int64)
+            binner = labels = PeriodIndex(data=[], freq=self.freq, name=ax.name)
+            if len(ax) > 0:
+                # index is all NaT
+                binner, bins, labels = _insert_nat_bin(binner, bins, labels, len(ax))
+            return binner, bins, labels
+
+        freq_mult = self.freq.n
+
+        start = ax.min().asfreq(self.freq, how=self.convention)
+        end = ax.max().asfreq(self.freq, how="end")
+        bin_shift = 0
+
+        if isinstance(self.freq, Tick):
+            # GH 23882 & 31809: get adjusted bin edge labels with 'origin'
+            # and 'origin' support. This call only makes sense if the freq is a
+            # Tick since offset and origin are only used in those cases.
+            # Not doing this check could create an extra empty bin.
+            p_start, end = _get_period_range_edges(
+                start,
+                end,
+                self.freq,
+                closed=self.closed,
+                origin=self.origin,
+                offset=self.offset,
+            )
+
+            # Get offset for bin edge (not label edge) adjustment
+            start_offset = Period(start, self.freq) - Period(p_start, self.freq)
+            # error: Item "Period" of "Union[Period, Any]" has no attribute "n"
+            bin_shift = start_offset.n % freq_mult  # type: ignore[union-attr]
+            start = p_start
+
+        labels = binner = period_range(
+            start=start, end=end, freq=self.freq, name=ax.name
+        )
+
+        i8 = memb.asi8
+
+        # when upsampling to subperiods, we need to generate enough bins
+        expected_bins_count = len(binner) * freq_mult
+        i8_extend = expected_bins_count - (i8[-1] - i8[0])
+        rng = np.arange(i8[0], i8[-1] + i8_extend, freq_mult)
+        rng += freq_mult
+        # adjust bin edge indexes to account for base
+        rng -= bin_shift
+
+        # Wrap in PeriodArray for PeriodArray.searchsorted
+        prng = type(memb._data)(rng, dtype=memb.dtype)
+        bins = memb.searchsorted(prng, side="left")
+
+        if nat_count > 0:
+            binner, bins, labels = _insert_nat_bin(binner, bins, labels, nat_count)
+
+        return binner, bins, labels
+
+    def _set_grouper(
+        self, obj: NDFrameT, sort: bool = False, *, gpr_index: Index | None = None
+    ) -> tuple[NDFrameT, Index, npt.NDArray[np.intp] | None]:
+        obj, ax, indexer = super()._set_grouper(obj, sort, gpr_index=gpr_index)
+        if isinstance(ax.dtype, ArrowDtype) and ax.dtype.kind in "Mm":
+            self._arrow_dtype = ax.dtype
+            ax = Index(
+                cast(ArrowExtensionArray, ax.array)._maybe_convert_datelike_array()
+            )
+        return obj, ax, indexer
+
+
+def _take_new_index(
+    obj: NDFrameT, indexer: npt.NDArray[np.intp], new_index: Index, axis: AxisInt = 0
+) -> NDFrameT:
+    if isinstance(obj, ABCSeries):
+        new_values = algos.take_nd(obj._values, indexer)
+        # error: Incompatible return value type (got "Series", expected "NDFrameT")
+        return obj._constructor(  # type: ignore[return-value]
+            new_values, index=new_index, name=obj.name
+        )
+    elif isinstance(obj, ABCDataFrame):
+        if axis == 1:
+            raise NotImplementedError("axis 1 is not supported")
+        new_mgr = obj._mgr.reindex_indexer(new_axis=new_index, indexer=indexer, axis=1)
+        # error: Incompatible return value type (got "DataFrame", expected "NDFrameT")
+        return obj._constructor_from_mgr(new_mgr, axes=new_mgr.axes)  # type: ignore[return-value]
+    else:
+        raise ValueError("'obj' should be either a Series or a DataFrame")
+
+
+def _get_timestamp_range_edges(
+    first: Timestamp,
+    last: Timestamp,
+    freq: BaseOffset,
+    unit: str,
+    closed: Literal["right", "left"] = "left",
+    origin: TimeGrouperOrigin = "start_day",
+    offset: Timedelta | None = None,
+) -> tuple[Timestamp, Timestamp]:
+    """
+    Adjust the `first` Timestamp to the preceding Timestamp that resides on
+    the provided offset. Adjust the `last` Timestamp to the following
+    Timestamp that resides on the provided offset. Input Timestamps that
+    already reside on the offset will be adjusted depending on the type of
+    offset and the `closed` parameter.
+
+    Parameters
+    ----------
+    first : pd.Timestamp
+        The beginning Timestamp of the range to be adjusted.
+    last : pd.Timestamp
+        The ending Timestamp of the range to be adjusted.
+    freq : pd.DateOffset
+        The dateoffset to which the Timestamps will be adjusted.
+    closed : {'right', 'left'}, default "left"
+        Which side of bin interval is closed.
+    origin : {'epoch', 'start', 'start_day'} or Timestamp, default 'start_day'
+        The timestamp on which to adjust the grouping. The timezone of origin must
+        match the timezone of the index.
+        If a timestamp is not used, these values are also supported:
+
+        - 'epoch': `origin` is 1970-01-01
+        - 'start': `origin` is the first value of the timeseries
+        - 'start_day': `origin` is the first day at midnight of the timeseries
+    offset : pd.Timedelta, default is None
+        An offset timedelta added to the origin.
+
+    Returns
+    -------
+    A tuple of length 2, containing the adjusted pd.Timestamp objects.
+    """
+    if isinstance(freq, Tick):
+        index_tz = first.tz
+        if isinstance(origin, Timestamp) and (origin.tz is None) != (index_tz is None):
+            raise ValueError("The origin must have the same timezone as the index.")
+        if origin == "epoch":
+            # set the epoch based on the timezone to have similar bins results when
+            # resampling on the same kind of indexes on different timezones
+            origin = Timestamp("1970-01-01", tz=index_tz)
+
+        if isinstance(freq, Day):
+            # _adjust_dates_anchored assumes 'D' means 24h, but first/last
+            # might contain a DST transition (23h, 24h, or 25h).
+            # So "pretend" the dates are naive when adjusting the endpoints
+            first = first.tz_localize(None)
+            last = last.tz_localize(None)
+            if isinstance(origin, Timestamp):
+                origin = origin.tz_localize(None)
+
+        first, last = _adjust_dates_anchored(
+            first, last, freq, closed=closed, origin=origin, offset=offset, unit=unit
+        )
+        if isinstance(freq, Day):
+            first = first.tz_localize(index_tz)
+            last = last.tz_localize(index_tz)
+    else:
+        first = first.normalize()
+        last = last.normalize()
+
+        if closed == "left":
+            first = Timestamp(freq.rollback(first))
+        else:
+            first = Timestamp(first - freq)
+
+        last = Timestamp(last + freq)
+
+    return first, last
+
+
+def _get_period_range_edges(
+    first: Period,
+    last: Period,
+    freq: BaseOffset,
+    closed: Literal["right", "left"] = "left",
+    origin: TimeGrouperOrigin = "start_day",
+    offset: Timedelta | None = None,
+) -> tuple[Period, Period]:
+    """
+    Adjust the provided `first` and `last` Periods to the respective Period of
+    the given offset that encompasses them.
+
+    Parameters
+    ----------
+    first : pd.Period
+        The beginning Period of the range to be adjusted.
+    last : pd.Period
+        The ending Period of the range to be adjusted.
+    freq : pd.DateOffset
+        The freq to which the Periods will be adjusted.
+    closed : {'right', 'left'}, default "left"
+        Which side of bin interval is closed.
+    origin : {'epoch', 'start', 'start_day'}, Timestamp, default 'start_day'
+        The timestamp on which to adjust the grouping. The timezone of origin must
+        match the timezone of the index.
+
+        If a timestamp is not used, these values are also supported:
+
+        - 'epoch': `origin` is 1970-01-01
+        - 'start': `origin` is the first value of the timeseries
+        - 'start_day': `origin` is the first day at midnight of the timeseries
+    offset : pd.Timedelta, default is None
+        An offset timedelta added to the origin.
+
+    Returns
+    -------
+    A tuple of length 2, containing the adjusted pd.Period objects.
+    """
+    if not all(isinstance(obj, Period) for obj in [first, last]):
+        raise TypeError("'first' and 'last' must be instances of type Period")
+
+    # GH 23882
+    first_ts = first.to_timestamp()
+    last_ts = last.to_timestamp()
+    adjust_first = not freq.is_on_offset(first_ts)
+    adjust_last = freq.is_on_offset(last_ts)
+
+    first_ts, last_ts = _get_timestamp_range_edges(
+        first_ts, last_ts, freq, unit="ns", closed=closed, origin=origin, offset=offset
+    )
+
+    first = (first_ts + int(adjust_first) * freq).to_period(freq)
+    last = (last_ts - int(adjust_last) * freq).to_period(freq)
+    return first, last
+
+
+def _insert_nat_bin(
+    binner: PeriodIndex, bins: np.ndarray, labels: PeriodIndex, nat_count: int
+) -> tuple[PeriodIndex, np.ndarray, PeriodIndex]:
+    # NaT handling as in pandas._lib.lib.generate_bins_dt64()
+    # shift bins by the number of NaT
+    assert nat_count > 0
+    bins += nat_count
+    bins = np.insert(bins, 0, nat_count)
+
+    # Incompatible types in assignment (expression has type "Index", variable
+    # has type "PeriodIndex")
+    binner = binner.insert(0, NaT)  # type: ignore[assignment]
+    # Incompatible types in assignment (expression has type "Index", variable
+    # has type "PeriodIndex")
+    labels = labels.insert(0, NaT)  # type: ignore[assignment]
+    return binner, bins, labels
+
+
+def _adjust_dates_anchored(
+    first: Timestamp,
+    last: Timestamp,
+    freq: Tick,
+    closed: Literal["right", "left"] = "right",
+    origin: TimeGrouperOrigin = "start_day",
+    offset: Timedelta | None = None,
+    unit: str = "ns",
+) -> tuple[Timestamp, Timestamp]:
+    # First and last offsets should be calculated from the start day to fix an
+    # error cause by resampling across multiple days when a one day period is
+    # not a multiple of the frequency. See GH 8683
+    # To handle frequencies that are not multiple or divisible by a day we let
+    # the possibility to define a fixed origin timestamp. See GH 31809
+    first = first.as_unit(unit)
+    last = last.as_unit(unit)
+    if offset is not None:
+        offset = offset.as_unit(unit)
+
+    freq_value = Timedelta(freq).as_unit(unit)._value
+
+    origin_timestamp = 0  # origin == "epoch"
+    if origin == "start_day":
+        origin_timestamp = first.normalize()._value
+    elif origin == "start":
+        origin_timestamp = first._value
+    elif isinstance(origin, Timestamp):
+        origin_timestamp = origin.as_unit(unit)._value
+    elif origin in ["end", "end_day"]:
+        origin_last = last if origin == "end" else last.ceil("D")
+        sub_freq_times = (origin_last._value - first._value) // freq_value
+        if closed == "left":
+            sub_freq_times += 1
+        first = origin_last - sub_freq_times * freq
+        origin_timestamp = first._value
+    origin_timestamp += offset._value if offset else 0
+
+    # GH 10117 & GH 19375. If first and last contain timezone information,
+    # Perform the calculation in UTC in order to avoid localizing on an
+    # Ambiguous or Nonexistent time.
+    first_tzinfo = first.tzinfo
+    last_tzinfo = last.tzinfo
+    if first_tzinfo is not None:
+        first = first.tz_convert("UTC")
+    if last_tzinfo is not None:
+        last = last.tz_convert("UTC")
+
+    foffset = (first._value - origin_timestamp) % freq_value
+    loffset = (last._value - origin_timestamp) % freq_value
+
+    if closed == "right":
+        if foffset > 0:
+            # roll back
+            fresult_int = first._value - foffset
+        else:
+            fresult_int = first._value - freq_value
+
+        if loffset > 0:
+            # roll forward
+            lresult_int = last._value + (freq_value - loffset)
+        else:
+            # already the end of the road
+            lresult_int = last._value
+    else:  # closed == 'left'
+        if foffset > 0:
+            fresult_int = first._value - foffset
+        else:
+            # start of the road
+            fresult_int = first._value
+
+        if loffset > 0:
+            # roll forward
+            lresult_int = last._value + (freq_value - loffset)
+        else:
+            lresult_int = last._value + freq_value
+    fresult = Timestamp(fresult_int, unit=unit)
+    lresult = Timestamp(lresult_int, unit=unit)
+    if first_tzinfo is not None:
+        fresult = fresult.tz_localize("UTC").tz_convert(first_tzinfo)
+    if last_tzinfo is not None:
+        lresult = lresult.tz_localize("UTC").tz_convert(last_tzinfo)
+    return fresult, lresult
+
+
+def asfreq(
+    obj: NDFrameT,
+    freq,
+    method=None,
+    how=None,
+    normalize: bool = False,
+    fill_value=None,
+) -> NDFrameT:
+    """
+    Utility frequency conversion method for Series/DataFrame.
+
+    See :meth:`pandas.NDFrame.asfreq` for full documentation.
+    """
+    if isinstance(obj.index, PeriodIndex):
+        if method is not None:
+            raise NotImplementedError("'method' argument is not supported")
+
+        if how is None:
+            how = "E"
+
+        if isinstance(freq, BaseOffset):
+            if hasattr(freq, "_period_dtype_code"):
+                freq = freq_to_period_freqstr(freq.n, freq.name)
+            else:
+                raise ValueError(
+                    f"Invalid offset: '{freq.base}' for converting time series "
+                    f"with PeriodIndex."
+                )
+
+        new_obj = obj.copy()
+        new_obj.index = obj.index.asfreq(freq, how=how)
+
+    elif len(obj.index) == 0:
+        new_obj = obj.copy()
+
+        new_obj.index = _asfreq_compat(obj.index, freq)
+    else:
+        unit = None
+        if isinstance(obj.index, DatetimeIndex):
+            # TODO: should we disallow non-DatetimeIndex?
+            unit = obj.index.unit
+        dti = date_range(obj.index.min(), obj.index.max(), freq=freq, unit=unit)
+        dti.name = obj.index.name
+        new_obj = obj.reindex(dti, method=method, fill_value=fill_value)
+        if normalize:
+            new_obj.index = new_obj.index.normalize()
+
+    return new_obj
+
+
+def _asfreq_compat(index: DatetimeIndex | PeriodIndex | TimedeltaIndex, freq):
+    """
+    Helper to mimic asfreq on (empty) DatetimeIndex and TimedeltaIndex.
+
+    Parameters
+    ----------
+    index : PeriodIndex, DatetimeIndex, or TimedeltaIndex
+    freq : DateOffset
+
+    Returns
+    -------
+    same type as index
+    """
+    if len(index) != 0:
+        # This should never be reached, always checked by the caller
+        raise ValueError(
+            "Can only set arbitrary freq for empty DatetimeIndex or TimedeltaIndex"
+        )
+    new_index: Index
+    if isinstance(index, PeriodIndex):
+        new_index = index.asfreq(freq=freq)
+    elif isinstance(index, DatetimeIndex):
+        new_index = DatetimeIndex([], dtype=index.dtype, freq=freq, name=index.name)
+    elif isinstance(index, TimedeltaIndex):
+        new_index = TimedeltaIndex([], dtype=index.dtype, freq=freq, name=index.name)
+    else:  # pragma: no cover
+        raise TypeError(type(index))
+    return new_index
+
+
+def maybe_warn_args_and_kwargs(cls, kernel: str, args, kwargs) -> None:
+    """
+    Warn for deprecation of args and kwargs in resample functions.
+
+    Parameters
+    ----------
+    cls : type
+        Class to warn about.
+    kernel : str
+        Operation name.
+    args : tuple or None
+        args passed by user. Will be None if and only if kernel does not have args.
+    kwargs : dict or None
+        kwargs passed by user. Will be None if and only if kernel does not have kwargs.
+    """
+    warn_args = args is not None and len(args) > 0
+    warn_kwargs = kwargs is not None and len(kwargs) > 0
+    if warn_args and warn_kwargs:
+        msg = "args and kwargs"
+    elif warn_args:
+        msg = "args"
+    elif warn_kwargs:
+        msg = "kwargs"
+    else:
+        return
+    warnings.warn(
+        f"Passing additional {msg} to {cls.__name__}.{kernel} has "
+        "no impact on the result and is deprecated. This will "
+        "raise a TypeError in a future version of pandas.",
+        category=FutureWarning,
+        stacklevel=find_stack_level(),
+    )
+
+
+def _apply(
+    grouped: GroupBy, how: Callable, *args, include_groups: bool, **kwargs
+) -> DataFrame:
+    # GH#7155 - rewrite warning to appear as if it came from `.resample`
+    target_message = "DataFrameGroupBy.apply operated on the grouping columns"
+    new_message = _apply_groupings_depr.format("DataFrameGroupBy", "resample")
+    with rewrite_warning(
+        target_message=target_message,
+        target_category=FutureWarning,
+        new_message=new_message,
+    ):
+        result = grouped.apply(how, *args, include_groups=include_groups, **kwargs)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/api.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..b1884c497f0ad7000351e131ef11dadab4a7c700
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/api.py
@@ -0,0 +1,41 @@
+from pandas.core.reshape.concat import concat
+from pandas.core.reshape.encoding import (
+    from_dummies,
+    get_dummies,
+)
+from pandas.core.reshape.melt import (
+    lreshape,
+    melt,
+    wide_to_long,
+)
+from pandas.core.reshape.merge import (
+    merge,
+    merge_asof,
+    merge_ordered,
+)
+from pandas.core.reshape.pivot import (
+    crosstab,
+    pivot,
+    pivot_table,
+)
+from pandas.core.reshape.tile import (
+    cut,
+    qcut,
+)
+
+__all__ = [
+    "concat",
+    "crosstab",
+    "cut",
+    "from_dummies",
+    "get_dummies",
+    "lreshape",
+    "melt",
+    "merge",
+    "merge_asof",
+    "merge_ordered",
+    "pivot",
+    "pivot_table",
+    "qcut",
+    "wide_to_long",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/concat.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/concat.py
new file mode 100644
index 0000000000000000000000000000000000000000..dc18bb65b35bcfa5c3789b35e7d41690923b50a7
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/concat.py
@@ -0,0 +1,894 @@
+"""
+Concat routines.
+"""
+from __future__ import annotations
+
+from collections import abc
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_copy_on_write
+
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_iterator,
+)
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.arrays.categorical import (
+    factorize_from_iterable,
+    factorize_from_iterables,
+)
+import pandas.core.common as com
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    all_indexes_same,
+    default_index,
+    ensure_index,
+    get_objs_combined_axis,
+    get_unanimous_names,
+)
+from pandas.core.internals import concatenate_managers
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Mapping,
+    )
+
+    from pandas._typing import (
+        Axis,
+        AxisInt,
+        HashableT,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+# ---------------------------------------------------------------------
+# Concatenate DataFrame objects
+
+
+@overload
+def concat(
+    objs: Iterable[DataFrame] | Mapping[HashableT, DataFrame],
+    *,
+    axis: Literal[0, "index"] = ...,
+    join: str = ...,
+    ignore_index: bool = ...,
+    keys: Iterable[Hashable] | None = ...,
+    levels=...,
+    names: list[HashableT] | None = ...,
+    verify_integrity: bool = ...,
+    sort: bool = ...,
+    copy: bool | None = ...,
+) -> DataFrame:
+    ...
+
+
+@overload
+def concat(
+    objs: Iterable[Series] | Mapping[HashableT, Series],
+    *,
+    axis: Literal[0, "index"] = ...,
+    join: str = ...,
+    ignore_index: bool = ...,
+    keys: Iterable[Hashable] | None = ...,
+    levels=...,
+    names: list[HashableT] | None = ...,
+    verify_integrity: bool = ...,
+    sort: bool = ...,
+    copy: bool | None = ...,
+) -> Series:
+    ...
+
+
+@overload
+def concat(
+    objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+    *,
+    axis: Literal[0, "index"] = ...,
+    join: str = ...,
+    ignore_index: bool = ...,
+    keys: Iterable[Hashable] | None = ...,
+    levels=...,
+    names: list[HashableT] | None = ...,
+    verify_integrity: bool = ...,
+    sort: bool = ...,
+    copy: bool | None = ...,
+) -> DataFrame | Series:
+    ...
+
+
+@overload
+def concat(
+    objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+    *,
+    axis: Literal[1, "columns"],
+    join: str = ...,
+    ignore_index: bool = ...,
+    keys: Iterable[Hashable] | None = ...,
+    levels=...,
+    names: list[HashableT] | None = ...,
+    verify_integrity: bool = ...,
+    sort: bool = ...,
+    copy: bool | None = ...,
+) -> DataFrame:
+    ...
+
+
+@overload
+def concat(
+    objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+    *,
+    axis: Axis = ...,
+    join: str = ...,
+    ignore_index: bool = ...,
+    keys: Iterable[Hashable] | None = ...,
+    levels=...,
+    names: list[HashableT] | None = ...,
+    verify_integrity: bool = ...,
+    sort: bool = ...,
+    copy: bool | None = ...,
+) -> DataFrame | Series:
+    ...
+
+
+def concat(
+    objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+    *,
+    axis: Axis = 0,
+    join: str = "outer",
+    ignore_index: bool = False,
+    keys: Iterable[Hashable] | None = None,
+    levels=None,
+    names: list[HashableT] | None = None,
+    verify_integrity: bool = False,
+    sort: bool = False,
+    copy: bool | None = None,
+) -> DataFrame | Series:
+    """
+    Concatenate pandas objects along a particular axis.
+
+    Allows optional set logic along the other axes.
+
+    Can also add a layer of hierarchical indexing on the concatenation axis,
+    which may be useful if the labels are the same (or overlapping) on
+    the passed axis number.
+
+    Parameters
+    ----------
+    objs : a sequence or mapping of Series or DataFrame objects
+        If a mapping is passed, the sorted keys will be used as the `keys`
+        argument, unless it is passed, in which case the values will be
+        selected (see below). Any None objects will be dropped silently unless
+        they are all None in which case a ValueError will be raised.
+    axis : {0/'index', 1/'columns'}, default 0
+        The axis to concatenate along.
+    join : {'inner', 'outer'}, default 'outer'
+        How to handle indexes on other axis (or axes).
+    ignore_index : bool, default False
+        If True, do not use the index values along the concatenation axis. The
+        resulting axis will be labeled 0, ..., n - 1. This is useful if you are
+        concatenating objects where the concatenation axis does not have
+        meaningful indexing information. Note the index values on the other
+        axes are still respected in the join.
+    keys : sequence, default None
+        If multiple levels passed, should contain tuples. Construct
+        hierarchical index using the passed keys as the outermost level.
+    levels : list of sequences, default None
+        Specific levels (unique values) to use for constructing a
+        MultiIndex. Otherwise they will be inferred from the keys.
+    names : list, default None
+        Names for the levels in the resulting hierarchical index.
+    verify_integrity : bool, default False
+        Check whether the new concatenated axis contains duplicates. This can
+        be very expensive relative to the actual data concatenation.
+    sort : bool, default False
+        Sort non-concatenation axis if it is not already aligned. One exception to
+        this is when the non-concatentation axis is a DatetimeIndex and join='outer'
+        and the axis is not already aligned. In that case, the non-concatenation
+        axis is always sorted lexicographically.
+    copy : bool, default True
+        If False, do not copy data unnecessarily.
+
+    Returns
+    -------
+    object, type of objs
+        When concatenating all ``Series`` along the index (axis=0), a
+        ``Series`` is returned. When ``objs`` contains at least one
+        ``DataFrame``, a ``DataFrame`` is returned. When concatenating along
+        the columns (axis=1), a ``DataFrame`` is returned.
+
+    See Also
+    --------
+    DataFrame.join : Join DataFrames using indexes.
+    DataFrame.merge : Merge DataFrames by indexes or columns.
+
+    Notes
+    -----
+    The keys, levels, and names arguments are all optional.
+
+    A walkthrough of how this method fits in with other tools for combining
+    pandas objects can be found `here
+    `__.
+
+    It is not recommended to build DataFrames by adding single rows in a
+    for loop. Build a list of rows and make a DataFrame in a single concat.
+
+    Examples
+    --------
+    Combine two ``Series``.
+
+    >>> s1 = pd.Series(['a', 'b'])
+    >>> s2 = pd.Series(['c', 'd'])
+    >>> pd.concat([s1, s2])
+    0    a
+    1    b
+    0    c
+    1    d
+    dtype: object
+
+    Clear the existing index and reset it in the result
+    by setting the ``ignore_index`` option to ``True``.
+
+    >>> pd.concat([s1, s2], ignore_index=True)
+    0    a
+    1    b
+    2    c
+    3    d
+    dtype: object
+
+    Add a hierarchical index at the outermost level of
+    the data with the ``keys`` option.
+
+    >>> pd.concat([s1, s2], keys=['s1', 's2'])
+    s1  0    a
+        1    b
+    s2  0    c
+        1    d
+    dtype: object
+
+    Label the index keys you create with the ``names`` option.
+
+    >>> pd.concat([s1, s2], keys=['s1', 's2'],
+    ...           names=['Series name', 'Row ID'])
+    Series name  Row ID
+    s1           0         a
+                 1         b
+    s2           0         c
+                 1         d
+    dtype: object
+
+    Combine two ``DataFrame`` objects with identical columns.
+
+    >>> df1 = pd.DataFrame([['a', 1], ['b', 2]],
+    ...                    columns=['letter', 'number'])
+    >>> df1
+      letter  number
+    0      a       1
+    1      b       2
+    >>> df2 = pd.DataFrame([['c', 3], ['d', 4]],
+    ...                    columns=['letter', 'number'])
+    >>> df2
+      letter  number
+    0      c       3
+    1      d       4
+    >>> pd.concat([df1, df2])
+      letter  number
+    0      a       1
+    1      b       2
+    0      c       3
+    1      d       4
+
+    Combine ``DataFrame`` objects with overlapping columns
+    and return everything. Columns outside the intersection will
+    be filled with ``NaN`` values.
+
+    >>> df3 = pd.DataFrame([['c', 3, 'cat'], ['d', 4, 'dog']],
+    ...                    columns=['letter', 'number', 'animal'])
+    >>> df3
+      letter  number animal
+    0      c       3    cat
+    1      d       4    dog
+    >>> pd.concat([df1, df3], sort=False)
+      letter  number animal
+    0      a       1    NaN
+    1      b       2    NaN
+    0      c       3    cat
+    1      d       4    dog
+
+    Combine ``DataFrame`` objects with overlapping columns
+    and return only those that are shared by passing ``inner`` to
+    the ``join`` keyword argument.
+
+    >>> pd.concat([df1, df3], join="inner")
+      letter  number
+    0      a       1
+    1      b       2
+    0      c       3
+    1      d       4
+
+    Combine ``DataFrame`` objects horizontally along the x axis by
+    passing in ``axis=1``.
+
+    >>> df4 = pd.DataFrame([['bird', 'polly'], ['monkey', 'george']],
+    ...                    columns=['animal', 'name'])
+    >>> pd.concat([df1, df4], axis=1)
+      letter  number  animal    name
+    0      a       1    bird   polly
+    1      b       2  monkey  george
+
+    Prevent the result from including duplicate index values with the
+    ``verify_integrity`` option.
+
+    >>> df5 = pd.DataFrame([1], index=['a'])
+    >>> df5
+       0
+    a  1
+    >>> df6 = pd.DataFrame([2], index=['a'])
+    >>> df6
+       0
+    a  2
+    >>> pd.concat([df5, df6], verify_integrity=True)
+    Traceback (most recent call last):
+        ...
+    ValueError: Indexes have overlapping values: ['a']
+
+    Append a single row to the end of a ``DataFrame`` object.
+
+    >>> df7 = pd.DataFrame({'a': 1, 'b': 2}, index=[0])
+    >>> df7
+        a   b
+    0   1   2
+    >>> new_row = pd.Series({'a': 3, 'b': 4})
+    >>> new_row
+    a    3
+    b    4
+    dtype: int64
+    >>> pd.concat([df7, new_row.to_frame().T], ignore_index=True)
+        a   b
+    0   1   2
+    1   3   4
+    """
+    if copy is None:
+        if using_copy_on_write():
+            copy = False
+        else:
+            copy = True
+    elif copy and using_copy_on_write():
+        copy = False
+
+    op = _Concatenator(
+        objs,
+        axis=axis,
+        ignore_index=ignore_index,
+        join=join,
+        keys=keys,
+        levels=levels,
+        names=names,
+        verify_integrity=verify_integrity,
+        copy=copy,
+        sort=sort,
+    )
+
+    return op.get_result()
+
+
+class _Concatenator:
+    """
+    Orchestrates a concatenation operation for BlockManagers
+    """
+
+    sort: bool
+
+    def __init__(
+        self,
+        objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+        axis: Axis = 0,
+        join: str = "outer",
+        keys: Iterable[Hashable] | None = None,
+        levels=None,
+        names: list[HashableT] | None = None,
+        ignore_index: bool = False,
+        verify_integrity: bool = False,
+        copy: bool = True,
+        sort: bool = False,
+    ) -> None:
+        if isinstance(objs, (ABCSeries, ABCDataFrame, str)):
+            raise TypeError(
+                "first argument must be an iterable of pandas "
+                f'objects, you passed an object of type "{type(objs).__name__}"'
+            )
+
+        if join == "outer":
+            self.intersect = False
+        elif join == "inner":
+            self.intersect = True
+        else:  # pragma: no cover
+            raise ValueError(
+                "Only can inner (intersect) or outer (union) join the other axis"
+            )
+
+        if not is_bool(sort):
+            raise ValueError(
+                f"The 'sort' keyword only accepts boolean values; {sort} was passed."
+            )
+        # Incompatible types in assignment (expression has type "Union[bool, bool_]",
+        # variable has type "bool")
+        self.sort = sort  # type: ignore[assignment]
+
+        self.ignore_index = ignore_index
+        self.verify_integrity = verify_integrity
+        self.copy = copy
+
+        objs, keys = self._clean_keys_and_objs(objs, keys)
+
+        # figure out what our result ndim is going to be
+        ndims = self._get_ndims(objs)
+        sample, objs = self._get_sample_object(objs, ndims, keys, names, levels)
+
+        # Standardize axis parameter to int
+        if sample.ndim == 1:
+            from pandas import DataFrame
+
+            axis = DataFrame._get_axis_number(axis)
+            self._is_frame = False
+            self._is_series = True
+        else:
+            axis = sample._get_axis_number(axis)
+            self._is_frame = True
+            self._is_series = False
+
+            # Need to flip BlockManager axis in the DataFrame special case
+            axis = sample._get_block_manager_axis(axis)
+
+        # if we have mixed ndims, then convert to highest ndim
+        # creating column numbers as needed
+        if len(ndims) > 1:
+            objs = self._sanitize_mixed_ndim(objs, sample, ignore_index, axis)
+
+        self.objs = objs
+
+        # note: this is the BlockManager axis (since DataFrame is transposed)
+        self.bm_axis = axis
+        self.axis = 1 - self.bm_axis if self._is_frame else 0
+        self.keys = keys
+        self.names = names or getattr(keys, "names", None)
+        self.levels = levels
+
+    def _get_ndims(self, objs: list[Series | DataFrame]) -> set[int]:
+        # figure out what our result ndim is going to be
+        ndims = set()
+        for obj in objs:
+            if not isinstance(obj, (ABCSeries, ABCDataFrame)):
+                msg = (
+                    f"cannot concatenate object of type '{type(obj)}'; "
+                    "only Series and DataFrame objs are valid"
+                )
+                raise TypeError(msg)
+
+            ndims.add(obj.ndim)
+        return ndims
+
+    def _clean_keys_and_objs(
+        self,
+        objs: Iterable[Series | DataFrame] | Mapping[HashableT, Series | DataFrame],
+        keys,
+    ) -> tuple[list[Series | DataFrame], Index | None]:
+        if isinstance(objs, abc.Mapping):
+            if keys is None:
+                keys = list(objs.keys())
+            objs_list = [objs[k] for k in keys]
+        else:
+            objs_list = list(objs)
+
+        if len(objs_list) == 0:
+            raise ValueError("No objects to concatenate")
+
+        if keys is None:
+            objs_list = list(com.not_none(*objs_list))
+        else:
+            # GH#1649
+            clean_keys = []
+            clean_objs = []
+            if is_iterator(keys):
+                keys = list(keys)
+            if len(keys) != len(objs_list):
+                # GH#43485
+                warnings.warn(
+                    "The behavior of pd.concat with len(keys) != len(objs) is "
+                    "deprecated. In a future version this will raise instead of "
+                    "truncating to the smaller of the two sequences",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+            for k, v in zip(keys, objs_list):
+                if v is None:
+                    continue
+                clean_keys.append(k)
+                clean_objs.append(v)
+            objs_list = clean_objs
+
+            if isinstance(keys, MultiIndex):
+                # TODO: retain levels?
+                keys = type(keys).from_tuples(clean_keys, names=keys.names)
+            else:
+                name = getattr(keys, "name", None)
+                keys = Index(clean_keys, name=name, dtype=getattr(keys, "dtype", None))
+
+        if len(objs_list) == 0:
+            raise ValueError("All objects passed were None")
+
+        return objs_list, keys
+
+    def _get_sample_object(
+        self,
+        objs: list[Series | DataFrame],
+        ndims: set[int],
+        keys,
+        names,
+        levels,
+    ) -> tuple[Series | DataFrame, list[Series | DataFrame]]:
+        # get the sample
+        # want the highest ndim that we have, and must be non-empty
+        # unless all objs are empty
+        sample: Series | DataFrame | None = None
+        if len(ndims) > 1:
+            max_ndim = max(ndims)
+            for obj in objs:
+                if obj.ndim == max_ndim and np.sum(obj.shape):
+                    sample = obj
+                    break
+
+        else:
+            # filter out the empties if we have not multi-index possibilities
+            # note to keep empty Series as it affect to result columns / name
+            non_empties = [obj for obj in objs if sum(obj.shape) > 0 or obj.ndim == 1]
+
+            if len(non_empties) and (
+                keys is None and names is None and levels is None and not self.intersect
+            ):
+                objs = non_empties
+                sample = objs[0]
+
+        if sample is None:
+            sample = objs[0]
+        return sample, objs
+
+    def _sanitize_mixed_ndim(
+        self,
+        objs: list[Series | DataFrame],
+        sample: Series | DataFrame,
+        ignore_index: bool,
+        axis: AxisInt,
+    ) -> list[Series | DataFrame]:
+        # if we have mixed ndims, then convert to highest ndim
+        # creating column numbers as needed
+
+        new_objs = []
+
+        current_column = 0
+        max_ndim = sample.ndim
+        for obj in objs:
+            ndim = obj.ndim
+            if ndim == max_ndim:
+                pass
+
+            elif ndim != max_ndim - 1:
+                raise ValueError(
+                    "cannot concatenate unaligned mixed dimensional NDFrame objects"
+                )
+
+            else:
+                name = getattr(obj, "name", None)
+                if ignore_index or name is None:
+                    if axis == 1:
+                        # doing a row-wise concatenation so need everything
+                        # to line up
+                        name = 0
+                    else:
+                        # doing a column-wise concatenation so need series
+                        # to have unique names
+                        name = current_column
+                        current_column += 1
+
+                obj = sample._constructor({name: obj}, copy=False)
+
+            new_objs.append(obj)
+
+        return new_objs
+
+    def get_result(self):
+        cons: Callable[..., DataFrame | Series]
+        sample: DataFrame | Series
+
+        # series only
+        if self._is_series:
+            sample = cast("Series", self.objs[0])
+
+            # stack blocks
+            if self.bm_axis == 0:
+                name = com.consensus_name_attr(self.objs)
+                cons = sample._constructor
+
+                arrs = [ser._values for ser in self.objs]
+
+                res = concat_compat(arrs, axis=0)
+
+                new_index: Index
+                if self.ignore_index:
+                    # We can avoid surprisingly-expensive _get_concat_axis
+                    new_index = default_index(len(res))
+                else:
+                    new_index = self.new_axes[0]
+
+                mgr = type(sample._mgr).from_array(res, index=new_index)
+
+                result = sample._constructor_from_mgr(mgr, axes=mgr.axes)
+                result._name = name
+                return result.__finalize__(self, method="concat")
+
+            # combine as columns in a frame
+            else:
+                data = dict(zip(range(len(self.objs)), self.objs))
+
+                # GH28330 Preserves subclassed objects through concat
+                cons = sample._constructor_expanddim
+
+                index, columns = self.new_axes
+                df = cons(data, index=index, copy=self.copy)
+                df.columns = columns
+                return df.__finalize__(self, method="concat")
+
+        # combine block managers
+        else:
+            sample = cast("DataFrame", self.objs[0])
+
+            mgrs_indexers = []
+            for obj in self.objs:
+                indexers = {}
+                for ax, new_labels in enumerate(self.new_axes):
+                    # ::-1 to convert BlockManager ax to DataFrame ax
+                    if ax == self.bm_axis:
+                        # Suppress reindexing on concat axis
+                        continue
+
+                    # 1-ax to convert BlockManager axis to DataFrame axis
+                    obj_labels = obj.axes[1 - ax]
+                    if not new_labels.equals(obj_labels):
+                        indexers[ax] = obj_labels.get_indexer(new_labels)
+
+                mgrs_indexers.append((obj._mgr, indexers))
+
+            new_data = concatenate_managers(
+                mgrs_indexers, self.new_axes, concat_axis=self.bm_axis, copy=self.copy
+            )
+            if not self.copy and not using_copy_on_write():
+                new_data._consolidate_inplace()
+
+            out = sample._constructor_from_mgr(new_data, axes=new_data.axes)
+            return out.__finalize__(self, method="concat")
+
+    def _get_result_dim(self) -> int:
+        if self._is_series and self.bm_axis == 1:
+            return 2
+        else:
+            return self.objs[0].ndim
+
+    @cache_readonly
+    def new_axes(self) -> list[Index]:
+        ndim = self._get_result_dim()
+        return [
+            self._get_concat_axis if i == self.bm_axis else self._get_comb_axis(i)
+            for i in range(ndim)
+        ]
+
+    def _get_comb_axis(self, i: AxisInt) -> Index:
+        data_axis = self.objs[0]._get_block_manager_axis(i)
+        return get_objs_combined_axis(
+            self.objs,
+            axis=data_axis,
+            intersect=self.intersect,
+            sort=self.sort,
+            copy=self.copy,
+        )
+
+    @cache_readonly
+    def _get_concat_axis(self) -> Index:
+        """
+        Return index to be used along concatenation axis.
+        """
+        if self._is_series:
+            if self.bm_axis == 0:
+                indexes = [x.index for x in self.objs]
+            elif self.ignore_index:
+                idx = default_index(len(self.objs))
+                return idx
+            elif self.keys is None:
+                names: list[Hashable] = [None] * len(self.objs)
+                num = 0
+                has_names = False
+                for i, x in enumerate(self.objs):
+                    if x.ndim != 1:
+                        raise TypeError(
+                            f"Cannot concatenate type 'Series' with "
+                            f"object of type '{type(x).__name__}'"
+                        )
+                    if x.name is not None:
+                        names[i] = x.name
+                        has_names = True
+                    else:
+                        names[i] = num
+                        num += 1
+                if has_names:
+                    return Index(names)
+                else:
+                    return default_index(len(self.objs))
+            else:
+                return ensure_index(self.keys).set_names(self.names)
+        else:
+            indexes = [x.axes[self.axis] for x in self.objs]
+
+        if self.ignore_index:
+            idx = default_index(sum(len(i) for i in indexes))
+            return idx
+
+        if self.keys is None:
+            if self.levels is not None:
+                raise ValueError("levels supported only when keys is not None")
+            concat_axis = _concat_indexes(indexes)
+        else:
+            concat_axis = _make_concat_multiindex(
+                indexes, self.keys, self.levels, self.names
+            )
+
+        self._maybe_check_integrity(concat_axis)
+
+        return concat_axis
+
+    def _maybe_check_integrity(self, concat_index: Index):
+        if self.verify_integrity:
+            if not concat_index.is_unique:
+                overlap = concat_index[concat_index.duplicated()].unique()
+                raise ValueError(f"Indexes have overlapping values: {overlap}")
+
+
+def _concat_indexes(indexes) -> Index:
+    return indexes[0].append(indexes[1:])
+
+
+def _make_concat_multiindex(indexes, keys, levels=None, names=None) -> MultiIndex:
+    if (levels is None and isinstance(keys[0], tuple)) or (
+        levels is not None and len(levels) > 1
+    ):
+        zipped = list(zip(*keys))
+        if names is None:
+            names = [None] * len(zipped)
+
+        if levels is None:
+            _, levels = factorize_from_iterables(zipped)
+        else:
+            levels = [ensure_index(x) for x in levels]
+    else:
+        zipped = [keys]
+        if names is None:
+            names = [None]
+
+        if levels is None:
+            levels = [ensure_index(keys).unique()]
+        else:
+            levels = [ensure_index(x) for x in levels]
+
+    for level in levels:
+        if not level.is_unique:
+            raise ValueError(f"Level values not unique: {level.tolist()}")
+
+    if not all_indexes_same(indexes) or not all(level.is_unique for level in levels):
+        codes_list = []
+
+        # things are potentially different sizes, so compute the exact codes
+        # for each level and pass those to MultiIndex.from_arrays
+
+        for hlevel, level in zip(zipped, levels):
+            to_concat = []
+            if isinstance(hlevel, Index) and hlevel.equals(level):
+                lens = [len(idx) for idx in indexes]
+                codes_list.append(np.repeat(np.arange(len(hlevel)), lens))
+            else:
+                for key, index in zip(hlevel, indexes):
+                    # Find matching codes, include matching nan values as equal.
+                    mask = (isna(level) & isna(key)) | (level == key)
+                    if not mask.any():
+                        raise ValueError(f"Key {key} not in level {level}")
+                    i = np.nonzero(mask)[0][0]
+
+                    to_concat.append(np.repeat(i, len(index)))
+                codes_list.append(np.concatenate(to_concat))
+
+        concat_index = _concat_indexes(indexes)
+
+        # these go at the end
+        if isinstance(concat_index, MultiIndex):
+            levels.extend(concat_index.levels)
+            codes_list.extend(concat_index.codes)
+        else:
+            codes, categories = factorize_from_iterable(concat_index)
+            levels.append(categories)
+            codes_list.append(codes)
+
+        if len(names) == len(levels):
+            names = list(names)
+        else:
+            # make sure that all of the passed indices have the same nlevels
+            if not len({idx.nlevels for idx in indexes}) == 1:
+                raise AssertionError(
+                    "Cannot concat indices that do not have the same number of levels"
+                )
+
+            # also copies
+            names = list(names) + list(get_unanimous_names(*indexes))
+
+        return MultiIndex(
+            levels=levels, codes=codes_list, names=names, verify_integrity=False
+        )
+
+    new_index = indexes[0]
+    n = len(new_index)
+    kpieces = len(indexes)
+
+    # also copies
+    new_names = list(names)
+    new_levels = list(levels)
+
+    # construct codes
+    new_codes = []
+
+    # do something a bit more speedy
+
+    for hlevel, level in zip(zipped, levels):
+        hlevel_index = ensure_index(hlevel)
+        mapped = level.get_indexer(hlevel_index)
+
+        mask = mapped == -1
+        if mask.any():
+            raise ValueError(
+                f"Values not found in passed level: {hlevel_index[mask]!s}"
+            )
+
+        new_codes.append(np.repeat(mapped, n))
+
+    if isinstance(new_index, MultiIndex):
+        new_levels.extend(new_index.levels)
+        new_codes.extend([np.tile(lab, kpieces) for lab in new_index.codes])
+    else:
+        new_levels.append(new_index.unique())
+        single_codes = new_index.unique().get_indexer(new_index)
+        new_codes.append(np.tile(single_codes, kpieces))
+
+    if len(new_names) < len(new_levels):
+        new_names.extend(new_index.names)
+
+    return MultiIndex(
+        levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/encoding.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/encoding.py
new file mode 100644
index 0000000000000000000000000000000000000000..85c10f11665776680b3249fcec304f9c029a5599
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/encoding.py
@@ -0,0 +1,571 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import (
+    Hashable,
+    Iterable,
+)
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import missing as libmissing
+from pandas._libs.sparse import IntIndex
+
+from pandas.core.dtypes.common import (
+    is_integer_dtype,
+    is_list_like,
+    is_object_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+)
+
+from pandas.core.arrays import SparseArray
+from pandas.core.arrays.categorical import factorize_from_iterable
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.frame import DataFrame
+from pandas.core.indexes.api import (
+    Index,
+    default_index,
+)
+from pandas.core.series import Series
+
+if TYPE_CHECKING:
+    from pandas._typing import NpDtype
+
+
+def get_dummies(
+    data,
+    prefix=None,
+    prefix_sep: str | Iterable[str] | dict[str, str] = "_",
+    dummy_na: bool = False,
+    columns=None,
+    sparse: bool = False,
+    drop_first: bool = False,
+    dtype: NpDtype | None = None,
+) -> DataFrame:
+    """
+    Convert categorical variable into dummy/indicator variables.
+
+    Each variable is converted in as many 0/1 variables as there are different
+    values. Columns in the output are each named after a value; if the input is
+    a DataFrame, the name of the original variable is prepended to the value.
+
+    Parameters
+    ----------
+    data : array-like, Series, or DataFrame
+        Data of which to get dummy indicators.
+    prefix : str, list of str, or dict of str, default None
+        String to append DataFrame column names.
+        Pass a list with length equal to the number of columns
+        when calling get_dummies on a DataFrame. Alternatively, `prefix`
+        can be a dictionary mapping column names to prefixes.
+    prefix_sep : str, default '_'
+        If appending prefix, separator/delimiter to use. Or pass a
+        list or dictionary as with `prefix`.
+    dummy_na : bool, default False
+        Add a column to indicate NaNs, if False NaNs are ignored.
+    columns : list-like, default None
+        Column names in the DataFrame to be encoded.
+        If `columns` is None then all the columns with
+        `object`, `string`, or `category` dtype will be converted.
+    sparse : bool, default False
+        Whether the dummy-encoded columns should be backed by
+        a :class:`SparseArray` (True) or a regular NumPy array (False).
+    drop_first : bool, default False
+        Whether to get k-1 dummies out of k categorical levels by removing the
+        first level.
+    dtype : dtype, default bool
+        Data type for new columns. Only a single dtype is allowed.
+
+    Returns
+    -------
+    DataFrame
+        Dummy-coded data. If `data` contains other columns than the
+        dummy-coded one(s), these will be prepended, unaltered, to the result.
+
+    See Also
+    --------
+    Series.str.get_dummies : Convert Series of strings to dummy codes.
+    :func:`~pandas.from_dummies` : Convert dummy codes to categorical ``DataFrame``.
+
+    Notes
+    -----
+    Reference :ref:`the user guide ` for more examples.
+
+    Examples
+    --------
+    >>> s = pd.Series(list('abca'))
+
+    >>> pd.get_dummies(s)
+           a      b      c
+    0   True  False  False
+    1  False   True  False
+    2  False  False   True
+    3   True  False  False
+
+    >>> s1 = ['a', 'b', np.nan]
+
+    >>> pd.get_dummies(s1)
+           a      b
+    0   True  False
+    1  False   True
+    2  False  False
+
+    >>> pd.get_dummies(s1, dummy_na=True)
+           a      b    NaN
+    0   True  False  False
+    1  False   True  False
+    2  False  False   True
+
+    >>> df = pd.DataFrame({'A': ['a', 'b', 'a'], 'B': ['b', 'a', 'c'],
+    ...                    'C': [1, 2, 3]})
+
+    >>> pd.get_dummies(df, prefix=['col1', 'col2'])
+       C  col1_a  col1_b  col2_a  col2_b  col2_c
+    0  1    True   False   False    True   False
+    1  2   False    True    True   False   False
+    2  3    True   False   False   False    True
+
+    >>> pd.get_dummies(pd.Series(list('abcaa')))
+           a      b      c
+    0   True  False  False
+    1  False   True  False
+    2  False  False   True
+    3   True  False  False
+    4   True  False  False
+
+    >>> pd.get_dummies(pd.Series(list('abcaa')), drop_first=True)
+           b      c
+    0  False  False
+    1   True  False
+    2  False   True
+    3  False  False
+    4  False  False
+
+    >>> pd.get_dummies(pd.Series(list('abc')), dtype=float)
+         a    b    c
+    0  1.0  0.0  0.0
+    1  0.0  1.0  0.0
+    2  0.0  0.0  1.0
+    """
+    from pandas.core.reshape.concat import concat
+
+    dtypes_to_encode = ["object", "string", "category"]
+
+    if isinstance(data, DataFrame):
+        # determine columns being encoded
+        if columns is None:
+            data_to_encode = data.select_dtypes(include=dtypes_to_encode)
+        elif not is_list_like(columns):
+            raise TypeError("Input must be a list-like for parameter `columns`")
+        else:
+            data_to_encode = data[columns]
+
+        # validate prefixes and separator to avoid silently dropping cols
+        def check_len(item, name: str):
+            if is_list_like(item):
+                if not len(item) == data_to_encode.shape[1]:
+                    len_msg = (
+                        f"Length of '{name}' ({len(item)}) did not match the "
+                        "length of the columns being encoded "
+                        f"({data_to_encode.shape[1]})."
+                    )
+                    raise ValueError(len_msg)
+
+        check_len(prefix, "prefix")
+        check_len(prefix_sep, "prefix_sep")
+
+        if isinstance(prefix, str):
+            prefix = itertools.cycle([prefix])
+        if isinstance(prefix, dict):
+            prefix = [prefix[col] for col in data_to_encode.columns]
+
+        if prefix is None:
+            prefix = data_to_encode.columns
+
+        # validate separators
+        if isinstance(prefix_sep, str):
+            prefix_sep = itertools.cycle([prefix_sep])
+        elif isinstance(prefix_sep, dict):
+            prefix_sep = [prefix_sep[col] for col in data_to_encode.columns]
+
+        with_dummies: list[DataFrame]
+        if data_to_encode.shape == data.shape:
+            # Encoding the entire df, do not prepend any dropped columns
+            with_dummies = []
+        elif columns is not None:
+            # Encoding only cols specified in columns. Get all cols not in
+            # columns to prepend to result.
+            with_dummies = [data.drop(columns, axis=1)]
+        else:
+            # Encoding only object and category dtype columns. Get remaining
+            # columns to prepend to result.
+            with_dummies = [data.select_dtypes(exclude=dtypes_to_encode)]
+
+        for col, pre, sep in zip(data_to_encode.items(), prefix, prefix_sep):
+            # col is (column_name, column), use just column data here
+            dummy = _get_dummies_1d(
+                col[1],
+                prefix=pre,
+                prefix_sep=sep,
+                dummy_na=dummy_na,
+                sparse=sparse,
+                drop_first=drop_first,
+                dtype=dtype,
+            )
+            with_dummies.append(dummy)
+        result = concat(with_dummies, axis=1)
+    else:
+        result = _get_dummies_1d(
+            data,
+            prefix,
+            prefix_sep,
+            dummy_na,
+            sparse=sparse,
+            drop_first=drop_first,
+            dtype=dtype,
+        )
+    return result
+
+
+def _get_dummies_1d(
+    data,
+    prefix,
+    prefix_sep: str | Iterable[str] | dict[str, str] = "_",
+    dummy_na: bool = False,
+    sparse: bool = False,
+    drop_first: bool = False,
+    dtype: NpDtype | None = None,
+) -> DataFrame:
+    from pandas.core.reshape.concat import concat
+
+    # Series avoids inconsistent NaN handling
+    codes, levels = factorize_from_iterable(Series(data, copy=False))
+
+    if dtype is None and hasattr(data, "dtype"):
+        input_dtype = data.dtype
+        if isinstance(input_dtype, CategoricalDtype):
+            input_dtype = input_dtype.categories.dtype
+
+        if isinstance(input_dtype, ArrowDtype):
+            import pyarrow as pa
+
+            dtype = ArrowDtype(pa.bool_())  # type: ignore[assignment]
+        elif (
+            isinstance(input_dtype, StringDtype)
+            and input_dtype.na_value is libmissing.NA
+        ):
+            dtype = pandas_dtype("boolean")  # type: ignore[assignment]
+        else:
+            dtype = np.dtype(bool)
+    elif dtype is None:
+        dtype = np.dtype(bool)
+
+    _dtype = pandas_dtype(dtype)
+
+    if is_object_dtype(_dtype):
+        raise ValueError("dtype=object is not a valid dtype for get_dummies")
+
+    def get_empty_frame(data) -> DataFrame:
+        index: Index | np.ndarray
+        if isinstance(data, Series):
+            index = data.index
+        else:
+            index = default_index(len(data))
+        return DataFrame(index=index)
+
+    # if all NaN
+    if not dummy_na and len(levels) == 0:
+        return get_empty_frame(data)
+
+    codes = codes.copy()
+    if dummy_na:
+        codes[codes == -1] = len(levels)
+        levels = levels.insert(len(levels), np.nan)
+
+    # if dummy_na, we just fake a nan level. drop_first will drop it again
+    if drop_first and len(levels) == 1:
+        return get_empty_frame(data)
+
+    number_of_cols = len(levels)
+
+    if prefix is None:
+        dummy_cols = levels
+    else:
+        dummy_cols = Index([f"{prefix}{prefix_sep}{level}" for level in levels])
+
+    index: Index | None
+    if isinstance(data, Series):
+        index = data.index
+    else:
+        index = None
+
+    if sparse:
+        fill_value: bool | float
+        if is_integer_dtype(dtype):
+            fill_value = 0
+        elif dtype == np.dtype(bool):
+            fill_value = False
+        else:
+            fill_value = 0.0
+
+        sparse_series = []
+        N = len(data)
+        sp_indices: list[list] = [[] for _ in range(len(dummy_cols))]
+        mask = codes != -1
+        codes = codes[mask]
+        n_idx = np.arange(N)[mask]
+
+        for ndx, code in zip(n_idx, codes):
+            sp_indices[code].append(ndx)
+
+        if drop_first:
+            # remove first categorical level to avoid perfect collinearity
+            # GH12042
+            sp_indices = sp_indices[1:]
+            dummy_cols = dummy_cols[1:]
+        for col, ixs in zip(dummy_cols, sp_indices):
+            sarr = SparseArray(
+                np.ones(len(ixs), dtype=dtype),
+                sparse_index=IntIndex(N, ixs),
+                fill_value=fill_value,
+                dtype=dtype,
+            )
+            sparse_series.append(Series(data=sarr, index=index, name=col, copy=False))
+
+        return concat(sparse_series, axis=1, copy=False)
+
+    else:
+        # ensure ndarray layout is column-major
+        shape = len(codes), number_of_cols
+        dummy_dtype: NpDtype
+        if isinstance(_dtype, np.dtype):
+            dummy_dtype = _dtype
+        else:
+            dummy_dtype = np.bool_
+        dummy_mat = np.zeros(shape=shape, dtype=dummy_dtype, order="F")
+        dummy_mat[np.arange(len(codes)), codes] = 1
+
+        if not dummy_na:
+            # reset NaN GH4446
+            dummy_mat[codes == -1] = 0
+
+        if drop_first:
+            # remove first GH12042
+            dummy_mat = dummy_mat[:, 1:]
+            dummy_cols = dummy_cols[1:]
+        return DataFrame(dummy_mat, index=index, columns=dummy_cols, dtype=_dtype)
+
+
+def from_dummies(
+    data: DataFrame,
+    sep: None | str = None,
+    default_category: None | Hashable | dict[str, Hashable] = None,
+) -> DataFrame:
+    """
+    Create a categorical ``DataFrame`` from a ``DataFrame`` of dummy variables.
+
+    Inverts the operation performed by :func:`~pandas.get_dummies`.
+
+    .. versionadded:: 1.5.0
+
+    Parameters
+    ----------
+    data : DataFrame
+        Data which contains dummy-coded variables in form of integer columns of
+        1's and 0's.
+    sep : str, default None
+        Separator used in the column names of the dummy categories they are
+        character indicating the separation of the categorical names from the prefixes.
+        For example, if your column names are 'prefix_A' and 'prefix_B',
+        you can strip the underscore by specifying sep='_'.
+    default_category : None, Hashable or dict of Hashables, default None
+        The default category is the implied category when a value has none of the
+        listed categories specified with a one, i.e. if all dummies in a row are
+        zero. Can be a single value for all variables or a dict directly mapping
+        the default categories to a prefix of a variable.
+
+    Returns
+    -------
+    DataFrame
+        Categorical data decoded from the dummy input-data.
+
+    Raises
+    ------
+    ValueError
+        * When the input ``DataFrame`` ``data`` contains NA values.
+        * When the input ``DataFrame`` ``data`` contains column names with separators
+          that do not match the separator specified with ``sep``.
+        * When a ``dict`` passed to ``default_category`` does not include an implied
+          category for each prefix.
+        * When a value in ``data`` has more than one category assigned to it.
+        * When ``default_category=None`` and a value in ``data`` has no category
+          assigned to it.
+    TypeError
+        * When the input ``data`` is not of type ``DataFrame``.
+        * When the input ``DataFrame`` ``data`` contains non-dummy data.
+        * When the passed ``sep`` is of a wrong data type.
+        * When the passed ``default_category`` is of a wrong data type.
+
+    See Also
+    --------
+    :func:`~pandas.get_dummies` : Convert ``Series`` or ``DataFrame`` to dummy codes.
+    :class:`~pandas.Categorical` : Represent a categorical variable in classic.
+
+    Notes
+    -----
+    The columns of the passed dummy data should only include 1's and 0's,
+    or boolean values.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"a": [1, 0, 0, 1], "b": [0, 1, 0, 0],
+    ...                    "c": [0, 0, 1, 0]})
+
+    >>> df
+       a  b  c
+    0  1  0  0
+    1  0  1  0
+    2  0  0  1
+    3  1  0  0
+
+    >>> pd.from_dummies(df)
+    0     a
+    1     b
+    2     c
+    3     a
+
+    >>> df = pd.DataFrame({"col1_a": [1, 0, 1], "col1_b": [0, 1, 0],
+    ...                    "col2_a": [0, 1, 0], "col2_b": [1, 0, 0],
+    ...                    "col2_c": [0, 0, 1]})
+
+    >>> df
+          col1_a  col1_b  col2_a  col2_b  col2_c
+    0       1       0       0       1       0
+    1       0       1       1       0       0
+    2       1       0       0       0       1
+
+    >>> pd.from_dummies(df, sep="_")
+        col1    col2
+    0    a       b
+    1    b       a
+    2    a       c
+
+    >>> df = pd.DataFrame({"col1_a": [1, 0, 0], "col1_b": [0, 1, 0],
+    ...                    "col2_a": [0, 1, 0], "col2_b": [1, 0, 0],
+    ...                    "col2_c": [0, 0, 0]})
+
+    >>> df
+          col1_a  col1_b  col2_a  col2_b  col2_c
+    0       1       0       0       1       0
+    1       0       1       1       0       0
+    2       0       0       0       0       0
+
+    >>> pd.from_dummies(df, sep="_", default_category={"col1": "d", "col2": "e"})
+        col1    col2
+    0    a       b
+    1    b       a
+    2    d       e
+    """
+    from pandas.core.reshape.concat import concat
+
+    if not isinstance(data, DataFrame):
+        raise TypeError(
+            "Expected 'data' to be a 'DataFrame'; "
+            f"Received 'data' of type: {type(data).__name__}"
+        )
+
+    col_isna_mask = cast(Series, data.isna().any())
+
+    if col_isna_mask.any():
+        raise ValueError(
+            "Dummy DataFrame contains NA value in column: "
+            f"'{col_isna_mask.idxmax()}'"
+        )
+
+    # index data with a list of all columns that are dummies
+    try:
+        data_to_decode = data.astype("boolean", copy=False)
+    except TypeError:
+        raise TypeError("Passed DataFrame contains non-dummy data")
+
+    # collect prefixes and get lists to slice data for each prefix
+    variables_slice = defaultdict(list)
+    if sep is None:
+        variables_slice[""] = list(data.columns)
+    elif isinstance(sep, str):
+        for col in data_to_decode.columns:
+            prefix = col.split(sep)[0]
+            if len(prefix) == len(col):
+                raise ValueError(f"Separator not specified for column: {col}")
+            variables_slice[prefix].append(col)
+    else:
+        raise TypeError(
+            "Expected 'sep' to be of type 'str' or 'None'; "
+            f"Received 'sep' of type: {type(sep).__name__}"
+        )
+
+    if default_category is not None:
+        if isinstance(default_category, dict):
+            if not len(default_category) == len(variables_slice):
+                len_msg = (
+                    f"Length of 'default_category' ({len(default_category)}) "
+                    f"did not match the length of the columns being encoded "
+                    f"({len(variables_slice)})"
+                )
+                raise ValueError(len_msg)
+        elif isinstance(default_category, Hashable):
+            default_category = dict(
+                zip(variables_slice, [default_category] * len(variables_slice))
+            )
+        else:
+            raise TypeError(
+                "Expected 'default_category' to be of type "
+                "'None', 'Hashable', or 'dict'; "
+                "Received 'default_category' of type: "
+                f"{type(default_category).__name__}"
+            )
+
+    cat_data = {}
+    for prefix, prefix_slice in variables_slice.items():
+        if sep is None:
+            cats = prefix_slice.copy()
+        else:
+            cats = [col[len(prefix + sep) :] for col in prefix_slice]
+        assigned = data_to_decode.loc[:, prefix_slice].sum(axis=1)
+        if any(assigned > 1):
+            raise ValueError(
+                "Dummy DataFrame contains multi-assignment(s); "
+                f"First instance in row: {assigned.idxmax()}"
+            )
+        if any(assigned == 0):
+            if isinstance(default_category, dict):
+                cats.append(default_category[prefix])
+            else:
+                raise ValueError(
+                    "Dummy DataFrame contains unassigned value(s); "
+                    f"First instance in row: {assigned.idxmin()}"
+                )
+            data_slice = concat(
+                (data_to_decode.loc[:, prefix_slice], assigned == 0), axis=1
+            )
+        else:
+            data_slice = data_to_decode.loc[:, prefix_slice]
+        cats_array = data._constructor_sliced(cats, dtype=data.columns.dtype)
+        # get indices of True entries along axis=1
+        true_values = data_slice.idxmax(axis=1)
+        indexer = data_slice.columns.get_indexer_for(true_values)
+        cat_data[prefix] = cats_array.take(indexer).set_axis(data.index)
+
+    result = DataFrame(cat_data)
+    if sep is not None:
+        result.columns = result.columns.astype(data.columns.dtype)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/melt.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/melt.py
new file mode 100644
index 0000000000000000000000000000000000000000..e54f847895f1a42cf1782392da684f2bcfa7e81c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/melt.py
@@ -0,0 +1,512 @@
+from __future__ import annotations
+
+import re
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.util._decorators import Appender
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.concat import concat_compat
+from pandas.core.dtypes.missing import notna
+
+import pandas.core.algorithms as algos
+from pandas.core.indexes.api import MultiIndex
+from pandas.core.reshape.concat import concat
+from pandas.core.reshape.util import tile_compat
+from pandas.core.shared_docs import _shared_docs
+from pandas.core.tools.numeric import to_numeric
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import AnyArrayLike
+
+    from pandas import DataFrame
+
+
+def ensure_list_vars(arg_vars, variable: str, columns) -> list:
+    if arg_vars is not None:
+        if not is_list_like(arg_vars):
+            return [arg_vars]
+        elif isinstance(columns, MultiIndex) and not isinstance(arg_vars, list):
+            raise ValueError(
+                f"{variable} must be a list of tuples when columns are a MultiIndex"
+            )
+        else:
+            return list(arg_vars)
+    else:
+        return []
+
+
+@Appender(_shared_docs["melt"] % {"caller": "pd.melt(df, ", "other": "DataFrame.melt"})
+def melt(
+    frame: DataFrame,
+    id_vars=None,
+    value_vars=None,
+    var_name=None,
+    value_name: Hashable = "value",
+    col_level=None,
+    ignore_index: bool = True,
+) -> DataFrame:
+    if value_name in frame.columns:
+        raise ValueError(
+            f"value_name ({value_name}) cannot match an element in "
+            "the DataFrame columns."
+        )
+    id_vars = ensure_list_vars(id_vars, "id_vars", frame.columns)
+    value_vars_was_not_none = value_vars is not None
+    value_vars = ensure_list_vars(value_vars, "value_vars", frame.columns)
+
+    if id_vars or value_vars:
+        if col_level is not None:
+            level = frame.columns.get_level_values(col_level)
+        else:
+            level = frame.columns
+        labels = id_vars + value_vars
+        idx = level.get_indexer_for(labels)
+        missing = idx == -1
+        if missing.any():
+            missing_labels = [
+                lab for lab, not_found in zip(labels, missing) if not_found
+            ]
+            raise KeyError(
+                "The following id_vars or value_vars are not present in "
+                f"the DataFrame: {missing_labels}"
+            )
+        if value_vars_was_not_none:
+            frame = frame.iloc[:, algos.unique(idx)]
+        else:
+            frame = frame.copy()
+    else:
+        frame = frame.copy()
+
+    if col_level is not None:  # allow list or other?
+        # frame is a copy
+        frame.columns = frame.columns.get_level_values(col_level)
+
+    if var_name is None:
+        if isinstance(frame.columns, MultiIndex):
+            if len(frame.columns.names) == len(set(frame.columns.names)):
+                var_name = frame.columns.names
+            else:
+                var_name = [f"variable_{i}" for i in range(len(frame.columns.names))]
+        else:
+            var_name = [
+                frame.columns.name if frame.columns.name is not None else "variable"
+            ]
+    elif is_list_like(var_name):
+        raise ValueError(f"{var_name=} must be a scalar.")
+    else:
+        var_name = [var_name]
+
+    num_rows, K = frame.shape
+    num_cols_adjusted = K - len(id_vars)
+
+    mdata: dict[Hashable, AnyArrayLike] = {}
+    for col in id_vars:
+        id_data = frame.pop(col)
+        if not isinstance(id_data.dtype, np.dtype):
+            # i.e. ExtensionDtype
+            if num_cols_adjusted > 0:
+                mdata[col] = concat([id_data] * num_cols_adjusted, ignore_index=True)
+            else:
+                # We can't concat empty list. (GH 46044)
+                mdata[col] = type(id_data)([], name=id_data.name, dtype=id_data.dtype)
+        else:
+            mdata[col] = np.tile(id_data._values, num_cols_adjusted)
+
+    mcolumns = id_vars + var_name + [value_name]
+
+    if frame.shape[1] > 0 and not any(
+        not isinstance(dt, np.dtype) and dt._supports_2d for dt in frame.dtypes
+    ):
+        mdata[value_name] = concat(
+            [frame.iloc[:, i] for i in range(frame.shape[1])]
+        ).values
+    else:
+        mdata[value_name] = frame._values.ravel("F")
+    for i, col in enumerate(var_name):
+        mdata[col] = frame.columns._get_level_values(i).repeat(num_rows)
+
+    result = frame._constructor(mdata, columns=mcolumns)
+
+    if not ignore_index:
+        result.index = tile_compat(frame.index, num_cols_adjusted)
+
+    return result
+
+
+def lreshape(data: DataFrame, groups: dict, dropna: bool = True) -> DataFrame:
+    """
+    Reshape wide-format data to long. Generalized inverse of DataFrame.pivot.
+
+    Accepts a dictionary, ``groups``, in which each key is a new column name
+    and each value is a list of old column names that will be "melted" under
+    the new column name as part of the reshape.
+
+    Parameters
+    ----------
+    data : DataFrame
+        The wide-format DataFrame.
+    groups : dict
+        {new_name : list_of_columns}.
+    dropna : bool, default True
+        Do not include columns whose entries are all NaN.
+
+    Returns
+    -------
+    DataFrame
+        Reshaped DataFrame.
+
+    See Also
+    --------
+    melt : Unpivot a DataFrame from wide to long format, optionally leaving
+        identifiers set.
+    pivot : Create a spreadsheet-style pivot table as a DataFrame.
+    DataFrame.pivot : Pivot without aggregation that can handle
+        non-numeric data.
+    DataFrame.pivot_table : Generalization of pivot that can handle
+        duplicate values for one index/column pair.
+    DataFrame.unstack : Pivot based on the index values instead of a
+        column.
+    wide_to_long : Wide panel to long format. Less flexible but more
+        user-friendly than melt.
+
+    Examples
+    --------
+    >>> data = pd.DataFrame({'hr1': [514, 573], 'hr2': [545, 526],
+    ...                      'team': ['Red Sox', 'Yankees'],
+    ...                      'year1': [2007, 2007], 'year2': [2008, 2008]})
+    >>> data
+       hr1  hr2     team  year1  year2
+    0  514  545  Red Sox   2007   2008
+    1  573  526  Yankees   2007   2008
+
+    >>> pd.lreshape(data, {'year': ['year1', 'year2'], 'hr': ['hr1', 'hr2']})
+          team  year   hr
+    0  Red Sox  2007  514
+    1  Yankees  2007  573
+    2  Red Sox  2008  545
+    3  Yankees  2008  526
+    """
+    mdata = {}
+    pivot_cols = []
+    all_cols: set[Hashable] = set()
+    K = len(next(iter(groups.values())))
+    for target, names in groups.items():
+        if len(names) != K:
+            raise ValueError("All column lists must be same length")
+        to_concat = [data[col]._values for col in names]
+
+        mdata[target] = concat_compat(to_concat)
+        pivot_cols.append(target)
+        all_cols = all_cols.union(names)
+
+    id_cols = list(data.columns.difference(all_cols))
+    for col in id_cols:
+        mdata[col] = np.tile(data[col]._values, K)
+
+    if dropna:
+        mask = np.ones(len(mdata[pivot_cols[0]]), dtype=bool)
+        for c in pivot_cols:
+            mask &= notna(mdata[c])
+        if not mask.all():
+            mdata = {k: v[mask] for k, v in mdata.items()}
+
+    return data._constructor(mdata, columns=id_cols + pivot_cols)
+
+
+def wide_to_long(
+    df: DataFrame, stubnames, i, j, sep: str = "", suffix: str = r"\d+"
+) -> DataFrame:
+    r"""
+    Unpivot a DataFrame from wide to long format.
+
+    Less flexible but more user-friendly than melt.
+
+    With stubnames ['A', 'B'], this function expects to find one or more
+    group of columns with format
+    A-suffix1, A-suffix2,..., B-suffix1, B-suffix2,...
+    You specify what you want to call this suffix in the resulting long format
+    with `j` (for example `j='year'`)
+
+    Each row of these wide variables are assumed to be uniquely identified by
+    `i` (can be a single column name or a list of column names)
+
+    All remaining variables in the data frame are left intact.
+
+    Parameters
+    ----------
+    df : DataFrame
+        The wide-format DataFrame.
+    stubnames : str or list-like
+        The stub name(s). The wide format variables are assumed to
+        start with the stub names.
+    i : str or list-like
+        Column(s) to use as id variable(s).
+    j : str
+        The name of the sub-observation variable. What you wish to name your
+        suffix in the long format.
+    sep : str, default ""
+        A character indicating the separation of the variable names
+        in the wide format, to be stripped from the names in the long format.
+        For example, if your column names are A-suffix1, A-suffix2, you
+        can strip the hyphen by specifying `sep='-'`.
+    suffix : str, default '\\d+'
+        A regular expression capturing the wanted suffixes. '\\d+' captures
+        numeric suffixes. Suffixes with no numbers could be specified with the
+        negated character class '\\D+'. You can also further disambiguate
+        suffixes, for example, if your wide variables are of the form A-one,
+        B-two,.., and you have an unrelated column A-rating, you can ignore the
+        last one by specifying `suffix='(!?one|two)'`. When all suffixes are
+        numeric, they are cast to int64/float64.
+
+    Returns
+    -------
+    DataFrame
+        A DataFrame that contains each stub name as a variable, with new index
+        (i, j).
+
+    See Also
+    --------
+    melt : Unpivot a DataFrame from wide to long format, optionally leaving
+        identifiers set.
+    pivot : Create a spreadsheet-style pivot table as a DataFrame.
+    DataFrame.pivot : Pivot without aggregation that can handle
+        non-numeric data.
+    DataFrame.pivot_table : Generalization of pivot that can handle
+        duplicate values for one index/column pair.
+    DataFrame.unstack : Pivot based on the index values instead of a
+        column.
+
+    Notes
+    -----
+    All extra variables are left untouched. This simply uses
+    `pandas.melt` under the hood, but is hard-coded to "do the right thing"
+    in a typical case.
+
+    Examples
+    --------
+    >>> np.random.seed(123)
+    >>> df = pd.DataFrame({"A1970" : {0 : "a", 1 : "b", 2 : "c"},
+    ...                    "A1980" : {0 : "d", 1 : "e", 2 : "f"},
+    ...                    "B1970" : {0 : 2.5, 1 : 1.2, 2 : .7},
+    ...                    "B1980" : {0 : 3.2, 1 : 1.3, 2 : .1},
+    ...                    "X"     : dict(zip(range(3), np.random.randn(3)))
+    ...                   })
+    >>> df["id"] = df.index
+    >>> df
+      A1970 A1980  B1970  B1980         X  id
+    0     a     d    2.5    3.2 -1.085631   0
+    1     b     e    1.2    1.3  0.997345   1
+    2     c     f    0.7    0.1  0.282978   2
+    >>> pd.wide_to_long(df, ["A", "B"], i="id", j="year")
+    ... # doctest: +NORMALIZE_WHITESPACE
+                    X  A    B
+    id year
+    0  1970 -1.085631  a  2.5
+    1  1970  0.997345  b  1.2
+    2  1970  0.282978  c  0.7
+    0  1980 -1.085631  d  3.2
+    1  1980  0.997345  e  1.3
+    2  1980  0.282978  f  0.1
+
+    With multiple id columns
+
+    >>> df = pd.DataFrame({
+    ...     'famid': [1, 1, 1, 2, 2, 2, 3, 3, 3],
+    ...     'birth': [1, 2, 3, 1, 2, 3, 1, 2, 3],
+    ...     'ht1': [2.8, 2.9, 2.2, 2, 1.8, 1.9, 2.2, 2.3, 2.1],
+    ...     'ht2': [3.4, 3.8, 2.9, 3.2, 2.8, 2.4, 3.3, 3.4, 2.9]
+    ... })
+    >>> df
+       famid  birth  ht1  ht2
+    0      1      1  2.8  3.4
+    1      1      2  2.9  3.8
+    2      1      3  2.2  2.9
+    3      2      1  2.0  3.2
+    4      2      2  1.8  2.8
+    5      2      3  1.9  2.4
+    6      3      1  2.2  3.3
+    7      3      2  2.3  3.4
+    8      3      3  2.1  2.9
+    >>> l = pd.wide_to_long(df, stubnames='ht', i=['famid', 'birth'], j='age')
+    >>> l
+    ... # doctest: +NORMALIZE_WHITESPACE
+                      ht
+    famid birth age
+    1     1     1    2.8
+                2    3.4
+          2     1    2.9
+                2    3.8
+          3     1    2.2
+                2    2.9
+    2     1     1    2.0
+                2    3.2
+          2     1    1.8
+                2    2.8
+          3     1    1.9
+                2    2.4
+    3     1     1    2.2
+                2    3.3
+          2     1    2.3
+                2    3.4
+          3     1    2.1
+                2    2.9
+
+    Going from long back to wide just takes some creative use of `unstack`
+
+    >>> w = l.unstack()
+    >>> w.columns = w.columns.map('{0[0]}{0[1]}'.format)
+    >>> w.reset_index()
+       famid  birth  ht1  ht2
+    0      1      1  2.8  3.4
+    1      1      2  2.9  3.8
+    2      1      3  2.2  2.9
+    3      2      1  2.0  3.2
+    4      2      2  1.8  2.8
+    5      2      3  1.9  2.4
+    6      3      1  2.2  3.3
+    7      3      2  2.3  3.4
+    8      3      3  2.1  2.9
+
+    Less wieldy column names are also handled
+
+    >>> np.random.seed(0)
+    >>> df = pd.DataFrame({'A(weekly)-2010': np.random.rand(3),
+    ...                    'A(weekly)-2011': np.random.rand(3),
+    ...                    'B(weekly)-2010': np.random.rand(3),
+    ...                    'B(weekly)-2011': np.random.rand(3),
+    ...                    'X' : np.random.randint(3, size=3)})
+    >>> df['id'] = df.index
+    >>> df # doctest: +NORMALIZE_WHITESPACE, +ELLIPSIS
+       A(weekly)-2010  A(weekly)-2011  B(weekly)-2010  B(weekly)-2011  X  id
+    0        0.548814        0.544883        0.437587        0.383442  0   0
+    1        0.715189        0.423655        0.891773        0.791725  1   1
+    2        0.602763        0.645894        0.963663        0.528895  1   2
+
+    >>> pd.wide_to_long(df, ['A(weekly)', 'B(weekly)'], i='id',
+    ...                 j='year', sep='-')
+    ... # doctest: +NORMALIZE_WHITESPACE
+             X  A(weekly)  B(weekly)
+    id year
+    0  2010  0   0.548814   0.437587
+    1  2010  1   0.715189   0.891773
+    2  2010  1   0.602763   0.963663
+    0  2011  0   0.544883   0.383442
+    1  2011  1   0.423655   0.791725
+    2  2011  1   0.645894   0.528895
+
+    If we have many columns, we could also use a regex to find our
+    stubnames and pass that list on to wide_to_long
+
+    >>> stubnames = sorted(
+    ...     set([match[0] for match in df.columns.str.findall(
+    ...         r'[A-B]\(.*\)').values if match != []])
+    ... )
+    >>> list(stubnames)
+    ['A(weekly)', 'B(weekly)']
+
+    All of the above examples have integers as suffixes. It is possible to
+    have non-integers as suffixes.
+
+    >>> df = pd.DataFrame({
+    ...     'famid': [1, 1, 1, 2, 2, 2, 3, 3, 3],
+    ...     'birth': [1, 2, 3, 1, 2, 3, 1, 2, 3],
+    ...     'ht_one': [2.8, 2.9, 2.2, 2, 1.8, 1.9, 2.2, 2.3, 2.1],
+    ...     'ht_two': [3.4, 3.8, 2.9, 3.2, 2.8, 2.4, 3.3, 3.4, 2.9]
+    ... })
+    >>> df
+       famid  birth  ht_one  ht_two
+    0      1      1     2.8     3.4
+    1      1      2     2.9     3.8
+    2      1      3     2.2     2.9
+    3      2      1     2.0     3.2
+    4      2      2     1.8     2.8
+    5      2      3     1.9     2.4
+    6      3      1     2.2     3.3
+    7      3      2     2.3     3.4
+    8      3      3     2.1     2.9
+
+    >>> l = pd.wide_to_long(df, stubnames='ht', i=['famid', 'birth'], j='age',
+    ...                     sep='_', suffix=r'\w+')
+    >>> l
+    ... # doctest: +NORMALIZE_WHITESPACE
+                      ht
+    famid birth age
+    1     1     one  2.8
+                two  3.4
+          2     one  2.9
+                two  3.8
+          3     one  2.2
+                two  2.9
+    2     1     one  2.0
+                two  3.2
+          2     one  1.8
+                two  2.8
+          3     one  1.9
+                two  2.4
+    3     1     one  2.2
+                two  3.3
+          2     one  2.3
+                two  3.4
+          3     one  2.1
+                two  2.9
+    """
+
+    def get_var_names(df, stub: str, sep: str, suffix: str):
+        regex = rf"^{re.escape(stub)}{re.escape(sep)}{suffix}$"
+        return df.columns[df.columns.str.match(regex)]
+
+    def melt_stub(df, stub: str, i, j, value_vars, sep: str):
+        newdf = melt(
+            df,
+            id_vars=i,
+            value_vars=value_vars,
+            value_name=stub.rstrip(sep),
+            var_name=j,
+        )
+        newdf[j] = newdf[j].str.replace(re.escape(stub + sep), "", regex=True)
+
+        # GH17627 Cast numerics suffixes to int/float
+        try:
+            newdf[j] = to_numeric(newdf[j])
+        except (TypeError, ValueError, OverflowError):
+            # TODO: anything else to catch?
+            pass
+
+        return newdf.set_index(i + [j])
+
+    if not is_list_like(stubnames):
+        stubnames = [stubnames]
+    else:
+        stubnames = list(stubnames)
+
+    if df.columns.isin(stubnames).any():
+        raise ValueError("stubname can't be identical to a column name")
+
+    if not is_list_like(i):
+        i = [i]
+    else:
+        i = list(i)
+
+    if df[i].duplicated().any():
+        raise ValueError("the id variables need to uniquely identify each row")
+
+    _melted = []
+    value_vars_flattened = []
+    for stub in stubnames:
+        value_var = get_var_names(df, stub, sep, suffix)
+        value_vars_flattened.extend(value_var)
+        _melted.append(melt_stub(df, stub, i, j, value_var, sep))
+
+    melted = concat(_melted, axis=1)
+    id_vars = df.columns.difference(value_vars_flattened)
+    new = df[id_vars]
+
+    if len(i) == 1:
+        return new.set_index(i).join(melted)
+    else:
+        return new.merge(melted.reset_index(), on=i).set_index(i + [j])
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/merge.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/merge.py
new file mode 100644
index 0000000000000000000000000000000000000000..a1e003c2001d24de56a066f30f17b7b60a8ed8f8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/merge.py
@@ -0,0 +1,2762 @@
+"""
+SQL-style merge routines
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Sequence,
+)
+import datetime
+from functools import partial
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+    final,
+)
+import uuid
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    Timedelta,
+    hashtable as libhashtable,
+    join as libjoin,
+    lib,
+)
+from pandas._libs.lib import is_range_indexer
+from pandas._typing import (
+    AnyArrayLike,
+    ArrayLike,
+    IndexLabel,
+    JoinHow,
+    MergeHow,
+    Shape,
+    Suffixes,
+    npt,
+)
+from pandas.errors import MergeError
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    cache_readonly,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import ExtensionDtype
+from pandas.core.dtypes.cast import find_common_type
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    ensure_object,
+    is_bool,
+    is_bool_dtype,
+    is_float_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_number,
+    is_numeric_dtype,
+    is_object_dtype,
+    is_string_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+)
+
+from pandas import (
+    ArrowDtype,
+    Categorical,
+    Index,
+    MultiIndex,
+    Series,
+)
+import pandas.core.algorithms as algos
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    BaseMaskedArray,
+    ExtensionArray,
+)
+from pandas.core.arrays.string_ import StringDtype
+import pandas.core.common as com
+from pandas.core.construction import (
+    ensure_wrapped_if_datetimelike,
+    extract_array,
+)
+from pandas.core.frame import _merge_doc
+from pandas.core.indexes.api import default_index
+from pandas.core.sorting import (
+    get_group_index,
+    is_int64_overflow_possible,
+)
+
+if TYPE_CHECKING:
+    from pandas import DataFrame
+    from pandas.core import groupby
+    from pandas.core.arrays import DatetimeArray
+    from pandas.core.indexes.frozen import FrozenList
+
+_factorizers = {
+    np.int64: libhashtable.Int64Factorizer,
+    np.longlong: libhashtable.Int64Factorizer,
+    np.int32: libhashtable.Int32Factorizer,
+    np.int16: libhashtable.Int16Factorizer,
+    np.int8: libhashtable.Int8Factorizer,
+    np.uint64: libhashtable.UInt64Factorizer,
+    np.uint32: libhashtable.UInt32Factorizer,
+    np.uint16: libhashtable.UInt16Factorizer,
+    np.uint8: libhashtable.UInt8Factorizer,
+    np.bool_: libhashtable.UInt8Factorizer,
+    np.float64: libhashtable.Float64Factorizer,
+    np.float32: libhashtable.Float32Factorizer,
+    np.complex64: libhashtable.Complex64Factorizer,
+    np.complex128: libhashtable.Complex128Factorizer,
+    np.object_: libhashtable.ObjectFactorizer,
+}
+
+# See https://github.com/pandas-dev/pandas/issues/52451
+if np.intc is not np.int32:
+    _factorizers[np.intc] = libhashtable.Int64Factorizer
+
+_known = (np.ndarray, ExtensionArray, Index, ABCSeries)
+
+
+@Substitution("\nleft : DataFrame or named Series")
+@Appender(_merge_doc, indents=0)
+def merge(
+    left: DataFrame | Series,
+    right: DataFrame | Series,
+    how: MergeHow = "inner",
+    on: IndexLabel | AnyArrayLike | None = None,
+    left_on: IndexLabel | AnyArrayLike | None = None,
+    right_on: IndexLabel | AnyArrayLike | None = None,
+    left_index: bool = False,
+    right_index: bool = False,
+    sort: bool = False,
+    suffixes: Suffixes = ("_x", "_y"),
+    copy: bool | None = None,
+    indicator: str | bool = False,
+    validate: str | None = None,
+) -> DataFrame:
+    left_df = _validate_operand(left)
+    right_df = _validate_operand(right)
+    if how == "cross":
+        return _cross_merge(
+            left_df,
+            right_df,
+            on=on,
+            left_on=left_on,
+            right_on=right_on,
+            left_index=left_index,
+            right_index=right_index,
+            sort=sort,
+            suffixes=suffixes,
+            indicator=indicator,
+            validate=validate,
+            copy=copy,
+        )
+    else:
+        op = _MergeOperation(
+            left_df,
+            right_df,
+            how=how,
+            on=on,
+            left_on=left_on,
+            right_on=right_on,
+            left_index=left_index,
+            right_index=right_index,
+            sort=sort,
+            suffixes=suffixes,
+            indicator=indicator,
+            validate=validate,
+        )
+        return op.get_result(copy=copy)
+
+
+def _cross_merge(
+    left: DataFrame,
+    right: DataFrame,
+    on: IndexLabel | AnyArrayLike | None = None,
+    left_on: IndexLabel | AnyArrayLike | None = None,
+    right_on: IndexLabel | AnyArrayLike | None = None,
+    left_index: bool = False,
+    right_index: bool = False,
+    sort: bool = False,
+    suffixes: Suffixes = ("_x", "_y"),
+    copy: bool | None = None,
+    indicator: str | bool = False,
+    validate: str | None = None,
+) -> DataFrame:
+    """
+    See merge.__doc__ with how='cross'
+    """
+
+    if (
+        left_index
+        or right_index
+        or right_on is not None
+        or left_on is not None
+        or on is not None
+    ):
+        raise MergeError(
+            "Can not pass on, right_on, left_on or set right_index=True or "
+            "left_index=True"
+        )
+
+    cross_col = f"_cross_{uuid.uuid4()}"
+    left = left.assign(**{cross_col: 1})
+    right = right.assign(**{cross_col: 1})
+
+    left_on = right_on = [cross_col]
+
+    res = merge(
+        left,
+        right,
+        how="inner",
+        on=on,
+        left_on=left_on,
+        right_on=right_on,
+        left_index=left_index,
+        right_index=right_index,
+        sort=sort,
+        suffixes=suffixes,
+        indicator=indicator,
+        validate=validate,
+        copy=copy,
+    )
+    del res[cross_col]
+    return res
+
+
+def _groupby_and_merge(
+    by, left: DataFrame | Series, right: DataFrame | Series, merge_pieces
+):
+    """
+    groupby & merge; we are always performing a left-by type operation
+
+    Parameters
+    ----------
+    by: field to group
+    left: DataFrame
+    right: DataFrame
+    merge_pieces: function for merging
+    """
+    pieces = []
+    if not isinstance(by, (list, tuple)):
+        by = [by]
+
+    lby = left.groupby(by, sort=False)
+    rby: groupby.DataFrameGroupBy | groupby.SeriesGroupBy | None = None
+
+    # if we can groupby the rhs
+    # then we can get vastly better perf
+    if all(item in right.columns for item in by):
+        rby = right.groupby(by, sort=False)
+
+    for key, lhs in lby._grouper.get_iterator(lby._selected_obj, axis=lby.axis):
+        if rby is None:
+            rhs = right
+        else:
+            try:
+                rhs = right.take(rby.indices[key])
+            except KeyError:
+                # key doesn't exist in left
+                lcols = lhs.columns.tolist()
+                cols = lcols + [r for r in right.columns if r not in set(lcols)]
+                merged = lhs.reindex(columns=cols)
+                merged.index = range(len(merged))
+                pieces.append(merged)
+                continue
+
+        merged = merge_pieces(lhs, rhs)
+
+        # make sure join keys are in the merged
+        # TODO, should merge_pieces do this?
+        merged[by] = key
+
+        pieces.append(merged)
+
+    # preserve the original order
+    # if we have a missing piece this can be reset
+    from pandas.core.reshape.concat import concat
+
+    result = concat(pieces, ignore_index=True)
+    result = result.reindex(columns=pieces[0].columns, copy=False)
+    return result, lby
+
+
+def merge_ordered(
+    left: DataFrame | Series,
+    right: DataFrame | Series,
+    on: IndexLabel | None = None,
+    left_on: IndexLabel | None = None,
+    right_on: IndexLabel | None = None,
+    left_by=None,
+    right_by=None,
+    fill_method: str | None = None,
+    suffixes: Suffixes = ("_x", "_y"),
+    how: JoinHow = "outer",
+) -> DataFrame:
+    """
+    Perform a merge for ordered data with optional filling/interpolation.
+
+    Designed for ordered data like time series data. Optionally
+    perform group-wise merge (see examples).
+
+    Parameters
+    ----------
+    left : DataFrame or named Series
+    right : DataFrame or named Series
+    on : label or list
+        Field names to join on. Must be found in both DataFrames.
+    left_on : label or list, or array-like
+        Field names to join on in left DataFrame. Can be a vector or list of
+        vectors of the length of the DataFrame to use a particular vector as
+        the join key instead of columns.
+    right_on : label or list, or array-like
+        Field names to join on in right DataFrame or vector/list of vectors per
+        left_on docs.
+    left_by : column name or list of column names
+        Group left DataFrame by group columns and merge piece by piece with
+        right DataFrame. Must be None if either left or right are a Series.
+    right_by : column name or list of column names
+        Group right DataFrame by group columns and merge piece by piece with
+        left DataFrame. Must be None if either left or right are a Series.
+    fill_method : {'ffill', None}, default None
+        Interpolation method for data.
+    suffixes : list-like, default is ("_x", "_y")
+        A length-2 sequence where each element is optionally a string
+        indicating the suffix to add to overlapping column names in
+        `left` and `right` respectively. Pass a value of `None` instead
+        of a string to indicate that the column name from `left` or
+        `right` should be left as-is, with no suffix. At least one of the
+        values must not be None.
+
+    how : {'left', 'right', 'outer', 'inner'}, default 'outer'
+        * left: use only keys from left frame (SQL: left outer join)
+        * right: use only keys from right frame (SQL: right outer join)
+        * outer: use union of keys from both frames (SQL: full outer join)
+        * inner: use intersection of keys from both frames (SQL: inner join).
+
+    Returns
+    -------
+    DataFrame
+        The merged DataFrame output type will be the same as
+        'left', if it is a subclass of DataFrame.
+
+    See Also
+    --------
+    merge : Merge with a database-style join.
+    merge_asof : Merge on nearest keys.
+
+    Examples
+    --------
+    >>> from pandas import merge_ordered
+    >>> df1 = pd.DataFrame(
+    ...     {
+    ...         "key": ["a", "c", "e", "a", "c", "e"],
+    ...         "lvalue": [1, 2, 3, 1, 2, 3],
+    ...         "group": ["a", "a", "a", "b", "b", "b"]
+    ...     }
+    ... )
+    >>> df1
+      key  lvalue group
+    0   a       1     a
+    1   c       2     a
+    2   e       3     a
+    3   a       1     b
+    4   c       2     b
+    5   e       3     b
+
+    >>> df2 = pd.DataFrame({"key": ["b", "c", "d"], "rvalue": [1, 2, 3]})
+    >>> df2
+      key  rvalue
+    0   b       1
+    1   c       2
+    2   d       3
+
+    >>> merge_ordered(df1, df2, fill_method="ffill", left_by="group")
+      key  lvalue group  rvalue
+    0   a       1     a     NaN
+    1   b       1     a     1.0
+    2   c       2     a     2.0
+    3   d       2     a     3.0
+    4   e       3     a     3.0
+    5   a       1     b     NaN
+    6   b       1     b     1.0
+    7   c       2     b     2.0
+    8   d       2     b     3.0
+    9   e       3     b     3.0
+    """
+
+    def _merger(x, y) -> DataFrame:
+        # perform the ordered merge operation
+        op = _OrderedMerge(
+            x,
+            y,
+            on=on,
+            left_on=left_on,
+            right_on=right_on,
+            suffixes=suffixes,
+            fill_method=fill_method,
+            how=how,
+        )
+        return op.get_result()
+
+    if left_by is not None and right_by is not None:
+        raise ValueError("Can only group either left or right frames")
+    if left_by is not None:
+        if isinstance(left_by, str):
+            left_by = [left_by]
+        check = set(left_by).difference(left.columns)
+        if len(check) != 0:
+            raise KeyError(f"{check} not found in left columns")
+        result, _ = _groupby_and_merge(left_by, left, right, lambda x, y: _merger(x, y))
+    elif right_by is not None:
+        if isinstance(right_by, str):
+            right_by = [right_by]
+        check = set(right_by).difference(right.columns)
+        if len(check) != 0:
+            raise KeyError(f"{check} not found in right columns")
+        result, _ = _groupby_and_merge(
+            right_by, right, left, lambda x, y: _merger(y, x)
+        )
+    else:
+        result = _merger(left, right)
+    return result
+
+
+def merge_asof(
+    left: DataFrame | Series,
+    right: DataFrame | Series,
+    on: IndexLabel | None = None,
+    left_on: IndexLabel | None = None,
+    right_on: IndexLabel | None = None,
+    left_index: bool = False,
+    right_index: bool = False,
+    by=None,
+    left_by=None,
+    right_by=None,
+    suffixes: Suffixes = ("_x", "_y"),
+    tolerance: int | Timedelta | None = None,
+    allow_exact_matches: bool = True,
+    direction: str = "backward",
+) -> DataFrame:
+    """
+    Perform a merge by key distance.
+
+    This is similar to a left-join except that we match on nearest
+    key rather than equal keys. Both DataFrames must be sorted by the key.
+
+    For each row in the left DataFrame:
+
+      - A "backward" search selects the last row in the right DataFrame whose
+        'on' key is less than or equal to the left's key.
+
+      - A "forward" search selects the first row in the right DataFrame whose
+        'on' key is greater than or equal to the left's key.
+
+      - A "nearest" search selects the row in the right DataFrame whose 'on'
+        key is closest in absolute distance to the left's key.
+
+    Optionally match on equivalent keys with 'by' before searching with 'on'.
+
+    Parameters
+    ----------
+    left : DataFrame or named Series
+    right : DataFrame or named Series
+    on : label
+        Field name to join on. Must be found in both DataFrames.
+        The data MUST be ordered. Furthermore this must be a numeric column,
+        such as datetimelike, integer, or float. On or left_on/right_on
+        must be given.
+    left_on : label
+        Field name to join on in left DataFrame.
+    right_on : label
+        Field name to join on in right DataFrame.
+    left_index : bool
+        Use the index of the left DataFrame as the join key.
+    right_index : bool
+        Use the index of the right DataFrame as the join key.
+    by : column name or list of column names
+        Match on these columns before performing merge operation.
+    left_by : column name
+        Field names to match on in the left DataFrame.
+    right_by : column name
+        Field names to match on in the right DataFrame.
+    suffixes : 2-length sequence (tuple, list, ...)
+        Suffix to apply to overlapping column names in the left and right
+        side, respectively.
+    tolerance : int or Timedelta, optional, default None
+        Select asof tolerance within this range; must be compatible
+        with the merge index.
+    allow_exact_matches : bool, default True
+
+        - If True, allow matching with the same 'on' value
+          (i.e. less-than-or-equal-to / greater-than-or-equal-to)
+        - If False, don't match the same 'on' value
+          (i.e., strictly less-than / strictly greater-than).
+
+    direction : 'backward' (default), 'forward', or 'nearest'
+        Whether to search for prior, subsequent, or closest matches.
+
+    Returns
+    -------
+    DataFrame
+
+    See Also
+    --------
+    merge : Merge with a database-style join.
+    merge_ordered : Merge with optional filling/interpolation.
+
+    Examples
+    --------
+    >>> left = pd.DataFrame({"a": [1, 5, 10], "left_val": ["a", "b", "c"]})
+    >>> left
+        a left_val
+    0   1        a
+    1   5        b
+    2  10        c
+
+    >>> right = pd.DataFrame({"a": [1, 2, 3, 6, 7], "right_val": [1, 2, 3, 6, 7]})
+    >>> right
+       a  right_val
+    0  1          1
+    1  2          2
+    2  3          3
+    3  6          6
+    4  7          7
+
+    >>> pd.merge_asof(left, right, on="a")
+        a left_val  right_val
+    0   1        a          1
+    1   5        b          3
+    2  10        c          7
+
+    >>> pd.merge_asof(left, right, on="a", allow_exact_matches=False)
+        a left_val  right_val
+    0   1        a        NaN
+    1   5        b        3.0
+    2  10        c        7.0
+
+    >>> pd.merge_asof(left, right, on="a", direction="forward")
+        a left_val  right_val
+    0   1        a        1.0
+    1   5        b        6.0
+    2  10        c        NaN
+
+    >>> pd.merge_asof(left, right, on="a", direction="nearest")
+        a left_val  right_val
+    0   1        a          1
+    1   5        b          6
+    2  10        c          7
+
+    We can use indexed DataFrames as well.
+
+    >>> left = pd.DataFrame({"left_val": ["a", "b", "c"]}, index=[1, 5, 10])
+    >>> left
+       left_val
+    1         a
+    5         b
+    10        c
+
+    >>> right = pd.DataFrame({"right_val": [1, 2, 3, 6, 7]}, index=[1, 2, 3, 6, 7])
+    >>> right
+       right_val
+    1          1
+    2          2
+    3          3
+    6          6
+    7          7
+
+    >>> pd.merge_asof(left, right, left_index=True, right_index=True)
+       left_val  right_val
+    1         a          1
+    5         b          3
+    10        c          7
+
+    Here is a real-world times-series example
+
+    >>> quotes = pd.DataFrame(
+    ...     {
+    ...         "time": [
+    ...             pd.Timestamp("2016-05-25 13:30:00.023"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.023"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.030"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.041"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.048"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.049"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.072"),
+    ...             pd.Timestamp("2016-05-25 13:30:00.075")
+    ...         ],
+    ...         "ticker": [
+    ...                "GOOG",
+    ...                "MSFT",
+    ...                "MSFT",
+    ...                "MSFT",
+    ...                "GOOG",
+    ...                "AAPL",
+    ...                "GOOG",
+    ...                "MSFT"
+    ...            ],
+    ...            "bid": [720.50, 51.95, 51.97, 51.99, 720.50, 97.99, 720.50, 52.01],
+    ...            "ask": [720.93, 51.96, 51.98, 52.00, 720.93, 98.01, 720.88, 52.03]
+    ...     }
+    ... )
+    >>> quotes
+                         time ticker     bid     ask
+    0 2016-05-25 13:30:00.023   GOOG  720.50  720.93
+    1 2016-05-25 13:30:00.023   MSFT   51.95   51.96
+    2 2016-05-25 13:30:00.030   MSFT   51.97   51.98
+    3 2016-05-25 13:30:00.041   MSFT   51.99   52.00
+    4 2016-05-25 13:30:00.048   GOOG  720.50  720.93
+    5 2016-05-25 13:30:00.049   AAPL   97.99   98.01
+    6 2016-05-25 13:30:00.072   GOOG  720.50  720.88
+    7 2016-05-25 13:30:00.075   MSFT   52.01   52.03
+
+    >>> trades = pd.DataFrame(
+    ...        {
+    ...            "time": [
+    ...                pd.Timestamp("2016-05-25 13:30:00.023"),
+    ...                pd.Timestamp("2016-05-25 13:30:00.038"),
+    ...                pd.Timestamp("2016-05-25 13:30:00.048"),
+    ...                pd.Timestamp("2016-05-25 13:30:00.048"),
+    ...                pd.Timestamp("2016-05-25 13:30:00.048")
+    ...            ],
+    ...            "ticker": ["MSFT", "MSFT", "GOOG", "GOOG", "AAPL"],
+    ...            "price": [51.95, 51.95, 720.77, 720.92, 98.0],
+    ...            "quantity": [75, 155, 100, 100, 100]
+    ...        }
+    ...    )
+    >>> trades
+                         time ticker   price  quantity
+    0 2016-05-25 13:30:00.023   MSFT   51.95        75
+    1 2016-05-25 13:30:00.038   MSFT   51.95       155
+    2 2016-05-25 13:30:00.048   GOOG  720.77       100
+    3 2016-05-25 13:30:00.048   GOOG  720.92       100
+    4 2016-05-25 13:30:00.048   AAPL   98.00       100
+
+    By default we are taking the asof of the quotes
+
+    >>> pd.merge_asof(trades, quotes, on="time", by="ticker")
+                         time ticker   price  quantity     bid     ask
+    0 2016-05-25 13:30:00.023   MSFT   51.95        75   51.95   51.96
+    1 2016-05-25 13:30:00.038   MSFT   51.95       155   51.97   51.98
+    2 2016-05-25 13:30:00.048   GOOG  720.77       100  720.50  720.93
+    3 2016-05-25 13:30:00.048   GOOG  720.92       100  720.50  720.93
+    4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN
+
+    We only asof within 2ms between the quote time and the trade time
+
+    >>> pd.merge_asof(
+    ...     trades, quotes, on="time", by="ticker", tolerance=pd.Timedelta("2ms")
+    ... )
+                         time ticker   price  quantity     bid     ask
+    0 2016-05-25 13:30:00.023   MSFT   51.95        75   51.95   51.96
+    1 2016-05-25 13:30:00.038   MSFT   51.95       155     NaN     NaN
+    2 2016-05-25 13:30:00.048   GOOG  720.77       100  720.50  720.93
+    3 2016-05-25 13:30:00.048   GOOG  720.92       100  720.50  720.93
+    4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN
+
+    We only asof within 10ms between the quote time and the trade time
+    and we exclude exact matches on time. However *prior* data will
+    propagate forward
+
+    >>> pd.merge_asof(
+    ...     trades,
+    ...     quotes,
+    ...     on="time",
+    ...     by="ticker",
+    ...     tolerance=pd.Timedelta("10ms"),
+    ...     allow_exact_matches=False
+    ... )
+                         time ticker   price  quantity     bid     ask
+    0 2016-05-25 13:30:00.023   MSFT   51.95        75     NaN     NaN
+    1 2016-05-25 13:30:00.038   MSFT   51.95       155   51.97   51.98
+    2 2016-05-25 13:30:00.048   GOOG  720.77       100     NaN     NaN
+    3 2016-05-25 13:30:00.048   GOOG  720.92       100     NaN     NaN
+    4 2016-05-25 13:30:00.048   AAPL   98.00       100     NaN     NaN
+    """
+    op = _AsOfMerge(
+        left,
+        right,
+        on=on,
+        left_on=left_on,
+        right_on=right_on,
+        left_index=left_index,
+        right_index=right_index,
+        by=by,
+        left_by=left_by,
+        right_by=right_by,
+        suffixes=suffixes,
+        how="asof",
+        tolerance=tolerance,
+        allow_exact_matches=allow_exact_matches,
+        direction=direction,
+    )
+    return op.get_result()
+
+
+# TODO: transformations??
+# TODO: only copy DataFrames when modification necessary
+class _MergeOperation:
+    """
+    Perform a database (SQL) merge operation between two DataFrame or Series
+    objects using either columns as keys or their row indexes
+    """
+
+    _merge_type = "merge"
+    how: JoinHow | Literal["asof"]
+    on: IndexLabel | None
+    # left_on/right_on may be None when passed, but in validate_specification
+    #  get replaced with non-None.
+    left_on: Sequence[Hashable | AnyArrayLike]
+    right_on: Sequence[Hashable | AnyArrayLike]
+    left_index: bool
+    right_index: bool
+    sort: bool
+    suffixes: Suffixes
+    copy: bool
+    indicator: str | bool
+    validate: str | None
+    join_names: list[Hashable]
+    right_join_keys: list[ArrayLike]
+    left_join_keys: list[ArrayLike]
+
+    def __init__(
+        self,
+        left: DataFrame | Series,
+        right: DataFrame | Series,
+        how: JoinHow | Literal["asof"] = "inner",
+        on: IndexLabel | AnyArrayLike | None = None,
+        left_on: IndexLabel | AnyArrayLike | None = None,
+        right_on: IndexLabel | AnyArrayLike | None = None,
+        left_index: bool = False,
+        right_index: bool = False,
+        sort: bool = True,
+        suffixes: Suffixes = ("_x", "_y"),
+        indicator: str | bool = False,
+        validate: str | None = None,
+    ) -> None:
+        _left = _validate_operand(left)
+        _right = _validate_operand(right)
+        self.left = self.orig_left = _left
+        self.right = self.orig_right = _right
+        self.how = how
+
+        self.on = com.maybe_make_list(on)
+
+        self.suffixes = suffixes
+        self.sort = sort or how == "outer"
+
+        self.left_index = left_index
+        self.right_index = right_index
+
+        self.indicator = indicator
+
+        if not is_bool(left_index):
+            raise ValueError(
+                f"left_index parameter must be of type bool, not {type(left_index)}"
+            )
+        if not is_bool(right_index):
+            raise ValueError(
+                f"right_index parameter must be of type bool, not {type(right_index)}"
+            )
+
+        # GH 40993: raise when merging between different levels; enforced in 2.0
+        if _left.columns.nlevels != _right.columns.nlevels:
+            msg = (
+                "Not allowed to merge between different levels. "
+                f"({_left.columns.nlevels} levels on the left, "
+                f"{_right.columns.nlevels} on the right)"
+            )
+            raise MergeError(msg)
+
+        self.left_on, self.right_on = self._validate_left_right_on(left_on, right_on)
+
+        (
+            self.left_join_keys,
+            self.right_join_keys,
+            self.join_names,
+            left_drop,
+            right_drop,
+        ) = self._get_merge_keys()
+
+        if left_drop:
+            self.left = self.left._drop_labels_or_levels(left_drop)
+
+        if right_drop:
+            self.right = self.right._drop_labels_or_levels(right_drop)
+
+        self._maybe_require_matching_dtypes(self.left_join_keys, self.right_join_keys)
+        self._validate_tolerance(self.left_join_keys)
+
+        # validate the merge keys dtypes. We may need to coerce
+        # to avoid incompatible dtypes
+        self._maybe_coerce_merge_keys()
+
+        # If argument passed to validate,
+        # check if columns specified as unique
+        # are in fact unique.
+        if validate is not None:
+            self._validate_validate_kwd(validate)
+
+    def _maybe_require_matching_dtypes(
+        self, left_join_keys: list[ArrayLike], right_join_keys: list[ArrayLike]
+    ) -> None:
+        # Overridden by AsOfMerge
+        pass
+
+    def _validate_tolerance(self, left_join_keys: list[ArrayLike]) -> None:
+        # Overridden by AsOfMerge
+        pass
+
+    @final
+    def _reindex_and_concat(
+        self,
+        join_index: Index,
+        left_indexer: npt.NDArray[np.intp] | None,
+        right_indexer: npt.NDArray[np.intp] | None,
+        copy: bool | None,
+    ) -> DataFrame:
+        """
+        reindex along index and concat along columns.
+        """
+        # Take views so we do not alter the originals
+        left = self.left[:]
+        right = self.right[:]
+
+        llabels, rlabels = _items_overlap_with_suffix(
+            self.left._info_axis, self.right._info_axis, self.suffixes
+        )
+
+        if left_indexer is not None and not is_range_indexer(left_indexer, len(left)):
+            # Pinning the index here (and in the right code just below) is not
+            #  necessary, but makes the `.take` more performant if we have e.g.
+            #  a MultiIndex for left.index.
+            lmgr = left._mgr.reindex_indexer(
+                join_index,
+                left_indexer,
+                axis=1,
+                copy=False,
+                only_slice=True,
+                allow_dups=True,
+                use_na_proxy=True,
+            )
+            left = left._constructor_from_mgr(lmgr, axes=lmgr.axes)
+        left.index = join_index
+
+        if right_indexer is not None and not is_range_indexer(
+            right_indexer, len(right)
+        ):
+            rmgr = right._mgr.reindex_indexer(
+                join_index,
+                right_indexer,
+                axis=1,
+                copy=False,
+                only_slice=True,
+                allow_dups=True,
+                use_na_proxy=True,
+            )
+            right = right._constructor_from_mgr(rmgr, axes=rmgr.axes)
+        right.index = join_index
+
+        from pandas import concat
+
+        left.columns = llabels
+        right.columns = rlabels
+        result = concat([left, right], axis=1, copy=copy)
+        return result
+
+    def get_result(self, copy: bool | None = True) -> DataFrame:
+        if self.indicator:
+            self.left, self.right = self._indicator_pre_merge(self.left, self.right)
+
+        join_index, left_indexer, right_indexer = self._get_join_info()
+
+        result = self._reindex_and_concat(
+            join_index, left_indexer, right_indexer, copy=copy
+        )
+        result = result.__finalize__(self, method=self._merge_type)
+
+        if self.indicator:
+            result = self._indicator_post_merge(result)
+
+        self._maybe_add_join_keys(result, left_indexer, right_indexer)
+
+        self._maybe_restore_index_levels(result)
+
+        return result.__finalize__(self, method="merge")
+
+    @final
+    @cache_readonly
+    def _indicator_name(self) -> str | None:
+        if isinstance(self.indicator, str):
+            return self.indicator
+        elif isinstance(self.indicator, bool):
+            return "_merge" if self.indicator else None
+        else:
+            raise ValueError(
+                "indicator option can only accept boolean or string arguments"
+            )
+
+    @final
+    def _indicator_pre_merge(
+        self, left: DataFrame, right: DataFrame
+    ) -> tuple[DataFrame, DataFrame]:
+        columns = left.columns.union(right.columns)
+
+        for i in ["_left_indicator", "_right_indicator"]:
+            if i in columns:
+                raise ValueError(
+                    "Cannot use `indicator=True` option when "
+                    f"data contains a column named {i}"
+                )
+        if self._indicator_name in columns:
+            raise ValueError(
+                "Cannot use name of an existing column for indicator column"
+            )
+
+        left = left.copy()
+        right = right.copy()
+
+        left["_left_indicator"] = 1
+        left["_left_indicator"] = left["_left_indicator"].astype("int8")
+
+        right["_right_indicator"] = 2
+        right["_right_indicator"] = right["_right_indicator"].astype("int8")
+
+        return left, right
+
+    @final
+    def _indicator_post_merge(self, result: DataFrame) -> DataFrame:
+        result["_left_indicator"] = result["_left_indicator"].fillna(0)
+        result["_right_indicator"] = result["_right_indicator"].fillna(0)
+
+        result[self._indicator_name] = Categorical(
+            (result["_left_indicator"] + result["_right_indicator"]),
+            categories=[1, 2, 3],
+        )
+        result[self._indicator_name] = result[
+            self._indicator_name
+        ].cat.rename_categories(["left_only", "right_only", "both"])
+
+        result = result.drop(labels=["_left_indicator", "_right_indicator"], axis=1)
+        return result
+
+    @final
+    def _maybe_restore_index_levels(self, result: DataFrame) -> None:
+        """
+        Restore index levels specified as `on` parameters
+
+        Here we check for cases where `self.left_on` and `self.right_on` pairs
+        each reference an index level in their respective DataFrames. The
+        joined columns corresponding to these pairs are then restored to the
+        index of `result`.
+
+        **Note:** This method has side effects. It modifies `result` in-place
+
+        Parameters
+        ----------
+        result: DataFrame
+            merge result
+
+        Returns
+        -------
+        None
+        """
+        names_to_restore = []
+        for name, left_key, right_key in zip(
+            self.join_names, self.left_on, self.right_on
+        ):
+            if (
+                # Argument 1 to "_is_level_reference" of "NDFrame" has incompatible
+                # type "Union[Hashable, ExtensionArray, Index, Series]"; expected
+                # "Hashable"
+                self.orig_left._is_level_reference(left_key)  # type: ignore[arg-type]
+                # Argument 1 to "_is_level_reference" of "NDFrame" has incompatible
+                # type "Union[Hashable, ExtensionArray, Index, Series]"; expected
+                # "Hashable"
+                and self.orig_right._is_level_reference(
+                    right_key  # type: ignore[arg-type]
+                )
+                and left_key == right_key
+                and name not in result.index.names
+            ):
+                names_to_restore.append(name)
+
+        if names_to_restore:
+            result.set_index(names_to_restore, inplace=True)
+
+    @final
+    def _maybe_add_join_keys(
+        self,
+        result: DataFrame,
+        left_indexer: npt.NDArray[np.intp] | None,
+        right_indexer: npt.NDArray[np.intp] | None,
+    ) -> None:
+        left_has_missing = None
+        right_has_missing = None
+
+        assert all(isinstance(x, _known) for x in self.left_join_keys)
+
+        keys = zip(self.join_names, self.left_on, self.right_on)
+        for i, (name, lname, rname) in enumerate(keys):
+            if not _should_fill(lname, rname):
+                continue
+
+            take_left, take_right = None, None
+
+            if name in result:
+                if left_indexer is not None or right_indexer is not None:
+                    if name in self.left:
+                        if left_has_missing is None:
+                            left_has_missing = (
+                                False
+                                if left_indexer is None
+                                else (left_indexer == -1).any()
+                            )
+
+                        if left_has_missing:
+                            take_right = self.right_join_keys[i]
+
+                            if result[name].dtype != self.left[name].dtype:
+                                take_left = self.left[name]._values
+
+                    elif name in self.right:
+                        if right_has_missing is None:
+                            right_has_missing = (
+                                False
+                                if right_indexer is None
+                                else (right_indexer == -1).any()
+                            )
+
+                        if right_has_missing:
+                            take_left = self.left_join_keys[i]
+
+                            if result[name].dtype != self.right[name].dtype:
+                                take_right = self.right[name]._values
+
+            else:
+                take_left = self.left_join_keys[i]
+                take_right = self.right_join_keys[i]
+
+            if take_left is not None or take_right is not None:
+                if take_left is None:
+                    lvals = result[name]._values
+                elif left_indexer is None:
+                    lvals = take_left
+                else:
+                    # TODO: can we pin down take_left's type earlier?
+                    take_left = extract_array(take_left, extract_numpy=True)
+                    lfill = na_value_for_dtype(take_left.dtype)
+                    lvals = algos.take_nd(take_left, left_indexer, fill_value=lfill)
+
+                if take_right is None:
+                    rvals = result[name]._values
+                elif right_indexer is None:
+                    rvals = take_right
+                else:
+                    # TODO: can we pin down take_right's type earlier?
+                    taker = extract_array(take_right, extract_numpy=True)
+                    rfill = na_value_for_dtype(taker.dtype)
+                    rvals = algos.take_nd(taker, right_indexer, fill_value=rfill)
+
+                # if we have an all missing left_indexer
+                # make sure to just use the right values or vice-versa
+                if left_indexer is not None and (left_indexer == -1).all():
+                    key_col = Index(rvals, dtype=rvals.dtype, copy=False)
+                    result_dtype = rvals.dtype
+                elif right_indexer is not None and (right_indexer == -1).all():
+                    key_col = Index(lvals, dtype=lvals.dtype, copy=False)
+                    result_dtype = lvals.dtype
+                else:
+                    key_col = Index(lvals, dtype=lvals.dtype, copy=False)
+                    if left_indexer is not None:
+                        mask_left = left_indexer == -1
+                        key_col = key_col.where(~mask_left, rvals)
+                    result_dtype = find_common_type([lvals.dtype, rvals.dtype])
+                    if (
+                        lvals.dtype.kind == "M"
+                        and rvals.dtype.kind == "M"
+                        and result_dtype.kind == "O"
+                    ):
+                        # TODO(non-nano) Workaround for common_type not dealing
+                        # with different resolutions
+                        result_dtype = key_col.dtype
+
+                if result._is_label_reference(name):
+                    result[name] = result._constructor_sliced(
+                        key_col, dtype=result_dtype, index=result.index
+                    )
+                elif result._is_level_reference(name):
+                    if isinstance(result.index, MultiIndex):
+                        key_col.name = name
+                        idx_list = [
+                            result.index.get_level_values(level_name)
+                            if level_name != name
+                            else key_col
+                            for level_name in result.index.names
+                        ]
+
+                        result.set_index(idx_list, inplace=True)
+                    else:
+                        key_col.name = name
+                        result.index = key_col
+                else:
+                    result.insert(i, name or f"key_{i}", key_col)
+
+    def _get_join_indexers(
+        self,
+    ) -> tuple[npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        """return the join indexers"""
+        # make mypy happy
+        assert self.how != "asof"
+        return get_join_indexers(
+            self.left_join_keys, self.right_join_keys, sort=self.sort, how=self.how
+        )
+
+    @final
+    def _get_join_info(
+        self,
+    ) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+        left_ax = self.left.index
+        right_ax = self.right.index
+
+        if self.left_index and self.right_index and self.how != "asof":
+            join_index, left_indexer, right_indexer = left_ax.join(
+                right_ax, how=self.how, return_indexers=True, sort=self.sort
+            )
+
+        elif self.right_index and self.how == "left":
+            join_index, left_indexer, right_indexer = _left_join_on_index(
+                left_ax, right_ax, self.left_join_keys, sort=self.sort
+            )
+
+        elif self.left_index and self.how == "right":
+            join_index, right_indexer, left_indexer = _left_join_on_index(
+                right_ax, left_ax, self.right_join_keys, sort=self.sort
+            )
+        else:
+            (left_indexer, right_indexer) = self._get_join_indexers()
+
+            if self.right_index:
+                if len(self.left) > 0:
+                    join_index = self._create_join_index(
+                        left_ax,
+                        right_ax,
+                        left_indexer,
+                        how="right",
+                    )
+                elif right_indexer is None:
+                    join_index = right_ax.copy()
+                else:
+                    join_index = right_ax.take(right_indexer)
+            elif self.left_index:
+                if self.how == "asof":
+                    # GH#33463 asof should always behave like a left merge
+                    join_index = self._create_join_index(
+                        left_ax,
+                        right_ax,
+                        left_indexer,
+                        how="left",
+                    )
+
+                elif len(self.right) > 0:
+                    join_index = self._create_join_index(
+                        right_ax,
+                        left_ax,
+                        right_indexer,
+                        how="left",
+                    )
+                elif left_indexer is None:
+                    join_index = left_ax.copy()
+                else:
+                    join_index = left_ax.take(left_indexer)
+            else:
+                n = len(left_ax) if left_indexer is None else len(left_indexer)
+                join_index = default_index(n)
+
+        return join_index, left_indexer, right_indexer
+
+    @final
+    def _create_join_index(
+        self,
+        index: Index,
+        other_index: Index,
+        indexer: npt.NDArray[np.intp] | None,
+        how: JoinHow = "left",
+    ) -> Index:
+        """
+        Create a join index by rearranging one index to match another
+
+        Parameters
+        ----------
+        index : Index
+            index being rearranged
+        other_index : Index
+            used to supply values not found in index
+        indexer : np.ndarray[np.intp] or None
+            how to rearrange index
+        how : str
+            Replacement is only necessary if indexer based on other_index.
+
+        Returns
+        -------
+        Index
+        """
+        if self.how in (how, "outer") and not isinstance(other_index, MultiIndex):
+            # if final index requires values in other_index but not target
+            # index, indexer may hold missing (-1) values, causing Index.take
+            # to take the final value in target index. So, we set the last
+            # element to be the desired fill value. We do not use allow_fill
+            # and fill_value because it throws a ValueError on integer indices
+            mask = indexer == -1
+            if np.any(mask):
+                fill_value = na_value_for_dtype(index.dtype, compat=False)
+                index = index.append(Index([fill_value]))
+        if indexer is None:
+            return index.copy()
+        return index.take(indexer)
+
+    @final
+    def _get_merge_keys(
+        self,
+    ) -> tuple[
+        list[ArrayLike],
+        list[ArrayLike],
+        list[Hashable],
+        list[Hashable],
+        list[Hashable],
+    ]:
+        """
+        Returns
+        -------
+        left_keys, right_keys, join_names, left_drop, right_drop
+        """
+        left_keys: list[ArrayLike] = []
+        right_keys: list[ArrayLike] = []
+        join_names: list[Hashable] = []
+        right_drop: list[Hashable] = []
+        left_drop: list[Hashable] = []
+
+        left, right = self.left, self.right
+
+        is_lkey = lambda x: isinstance(x, _known) and len(x) == len(left)
+        is_rkey = lambda x: isinstance(x, _known) and len(x) == len(right)
+
+        # Note that pd.merge_asof() has separate 'on' and 'by' parameters. A
+        # user could, for example, request 'left_index' and 'left_by'. In a
+        # regular pd.merge(), users cannot specify both 'left_index' and
+        # 'left_on'. (Instead, users have a MultiIndex). That means the
+        # self.left_on in this function is always empty in a pd.merge(), but
+        # a pd.merge_asof(left_index=True, left_by=...) will result in a
+        # self.left_on array with a None in the middle of it. This requires
+        # a work-around as designated in the code below.
+        # See _validate_left_right_on() for where this happens.
+
+        # ugh, spaghetti re #733
+        if _any(self.left_on) and _any(self.right_on):
+            for lk, rk in zip(self.left_on, self.right_on):
+                lk = extract_array(lk, extract_numpy=True)
+                rk = extract_array(rk, extract_numpy=True)
+                if is_lkey(lk):
+                    lk = cast(ArrayLike, lk)
+                    left_keys.append(lk)
+                    if is_rkey(rk):
+                        rk = cast(ArrayLike, rk)
+                        right_keys.append(rk)
+                        join_names.append(None)  # what to do?
+                    else:
+                        # Then we're either Hashable or a wrong-length arraylike,
+                        #  the latter of which will raise
+                        rk = cast(Hashable, rk)
+                        if rk is not None:
+                            right_keys.append(right._get_label_or_level_values(rk))
+                            join_names.append(rk)
+                        else:
+                            # work-around for merge_asof(right_index=True)
+                            right_keys.append(right.index._values)
+                            join_names.append(right.index.name)
+                else:
+                    if not is_rkey(rk):
+                        # Then we're either Hashable or a wrong-length arraylike,
+                        #  the latter of which will raise
+                        rk = cast(Hashable, rk)
+                        if rk is not None:
+                            right_keys.append(right._get_label_or_level_values(rk))
+                        else:
+                            # work-around for merge_asof(right_index=True)
+                            right_keys.append(right.index._values)
+                        if lk is not None and lk == rk:  # FIXME: what about other NAs?
+                            right_drop.append(rk)
+                    else:
+                        rk = cast(ArrayLike, rk)
+                        right_keys.append(rk)
+                    if lk is not None:
+                        # Then we're either Hashable or a wrong-length arraylike,
+                        #  the latter of which will raise
+                        lk = cast(Hashable, lk)
+                        left_keys.append(left._get_label_or_level_values(lk))
+                        join_names.append(lk)
+                    else:
+                        # work-around for merge_asof(left_index=True)
+                        left_keys.append(left.index._values)
+                        join_names.append(left.index.name)
+        elif _any(self.left_on):
+            for k in self.left_on:
+                if is_lkey(k):
+                    k = extract_array(k, extract_numpy=True)
+                    k = cast(ArrayLike, k)
+                    left_keys.append(k)
+                    join_names.append(None)
+                else:
+                    # Then we're either Hashable or a wrong-length arraylike,
+                    #  the latter of which will raise
+                    k = cast(Hashable, k)
+                    left_keys.append(left._get_label_or_level_values(k))
+                    join_names.append(k)
+            if isinstance(self.right.index, MultiIndex):
+                right_keys = [
+                    lev._values.take(lev_codes)
+                    for lev, lev_codes in zip(
+                        self.right.index.levels, self.right.index.codes
+                    )
+                ]
+            else:
+                right_keys = [self.right.index._values]
+        elif _any(self.right_on):
+            for k in self.right_on:
+                k = extract_array(k, extract_numpy=True)
+                if is_rkey(k):
+                    k = cast(ArrayLike, k)
+                    right_keys.append(k)
+                    join_names.append(None)
+                else:
+                    # Then we're either Hashable or a wrong-length arraylike,
+                    #  the latter of which will raise
+                    k = cast(Hashable, k)
+                    right_keys.append(right._get_label_or_level_values(k))
+                    join_names.append(k)
+            if isinstance(self.left.index, MultiIndex):
+                left_keys = [
+                    lev._values.take(lev_codes)
+                    for lev, lev_codes in zip(
+                        self.left.index.levels, self.left.index.codes
+                    )
+                ]
+            else:
+                left_keys = [self.left.index._values]
+
+        return left_keys, right_keys, join_names, left_drop, right_drop
+
+    @final
+    def _maybe_coerce_merge_keys(self) -> None:
+        # we have valid merges but we may have to further
+        # coerce these if they are originally incompatible types
+        #
+        # for example if these are categorical, but are not dtype_equal
+        # or if we have object and integer dtypes
+
+        for lk, rk, name in zip(
+            self.left_join_keys, self.right_join_keys, self.join_names
+        ):
+            if (len(lk) and not len(rk)) or (not len(lk) and len(rk)):
+                continue
+
+            lk = extract_array(lk, extract_numpy=True)
+            rk = extract_array(rk, extract_numpy=True)
+
+            lk_is_cat = isinstance(lk.dtype, CategoricalDtype)
+            rk_is_cat = isinstance(rk.dtype, CategoricalDtype)
+            lk_is_object_or_string = is_object_dtype(lk.dtype) or is_string_dtype(
+                lk.dtype
+            )
+            rk_is_object_or_string = is_object_dtype(rk.dtype) or is_string_dtype(
+                rk.dtype
+            )
+
+            # if either left or right is a categorical
+            # then the must match exactly in categories & ordered
+            if lk_is_cat and rk_is_cat:
+                lk = cast(Categorical, lk)
+                rk = cast(Categorical, rk)
+                if lk._categories_match_up_to_permutation(rk):
+                    continue
+
+            elif lk_is_cat or rk_is_cat:
+                pass
+
+            elif lk.dtype == rk.dtype:
+                continue
+
+            msg = (
+                f"You are trying to merge on {lk.dtype} and {rk.dtype} columns "
+                f"for key '{name}'. If you wish to proceed you should use pd.concat"
+            )
+
+            # if we are numeric, then allow differing
+            # kinds to proceed, eg. int64 and int8, int and float
+            # further if we are object, but we infer to
+            # the same, then proceed
+            if is_numeric_dtype(lk.dtype) and is_numeric_dtype(rk.dtype):
+                if lk.dtype.kind == rk.dtype.kind:
+                    continue
+
+                if isinstance(lk.dtype, ExtensionDtype) and not isinstance(
+                    rk.dtype, ExtensionDtype
+                ):
+                    ct = find_common_type([lk.dtype, rk.dtype])
+                    if isinstance(ct, ExtensionDtype):
+                        com_cls = ct.construct_array_type()
+                        rk = com_cls._from_sequence(rk, dtype=ct, copy=False)
+                    else:
+                        rk = rk.astype(ct)
+                elif isinstance(rk.dtype, ExtensionDtype):
+                    ct = find_common_type([lk.dtype, rk.dtype])
+                    if isinstance(ct, ExtensionDtype):
+                        com_cls = ct.construct_array_type()
+                        lk = com_cls._from_sequence(lk, dtype=ct, copy=False)
+                    else:
+                        lk = lk.astype(ct)
+
+                # check whether ints and floats
+                if is_integer_dtype(rk.dtype) and is_float_dtype(lk.dtype):
+                    # GH 47391 numpy > 1.24 will raise a RuntimeError for nan -> int
+                    with np.errstate(invalid="ignore"):
+                        # error: Argument 1 to "astype" of "ndarray" has incompatible
+                        # type "Union[ExtensionDtype, Any, dtype[Any]]"; expected
+                        # "Union[dtype[Any], Type[Any], _SupportsDType[dtype[Any]]]"
+                        casted = lk.astype(rk.dtype)  # type: ignore[arg-type]
+
+                    mask = ~np.isnan(lk)
+                    match = lk == casted
+                    if not match[mask].all():
+                        warnings.warn(
+                            "You are merging on int and float "
+                            "columns where the float values "
+                            "are not equal to their int representation.",
+                            UserWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    continue
+
+                if is_float_dtype(rk.dtype) and is_integer_dtype(lk.dtype):
+                    # GH 47391 numpy > 1.24 will raise a RuntimeError for nan -> int
+                    with np.errstate(invalid="ignore"):
+                        # error: Argument 1 to "astype" of "ndarray" has incompatible
+                        # type "Union[ExtensionDtype, Any, dtype[Any]]"; expected
+                        # "Union[dtype[Any], Type[Any], _SupportsDType[dtype[Any]]]"
+                        casted = rk.astype(lk.dtype)  # type: ignore[arg-type]
+
+                    mask = ~np.isnan(rk)
+                    match = rk == casted
+                    if not match[mask].all():
+                        warnings.warn(
+                            "You are merging on int and float "
+                            "columns where the float values "
+                            "are not equal to their int representation.",
+                            UserWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    continue
+
+                # let's infer and see if we are ok
+                if lib.infer_dtype(lk, skipna=False) == lib.infer_dtype(
+                    rk, skipna=False
+                ):
+                    continue
+
+            # Check if we are trying to merge on obviously
+            # incompatible dtypes GH 9780, GH 15800
+
+            # bool values are coerced to object
+            elif (lk_is_object_or_string and is_bool_dtype(rk.dtype)) or (
+                is_bool_dtype(lk.dtype) and rk_is_object_or_string
+            ):
+                pass
+
+            # object values are allowed to be merged
+            elif (lk_is_object_or_string and is_numeric_dtype(rk.dtype)) or (
+                is_numeric_dtype(lk.dtype) and rk_is_object_or_string
+            ):
+                inferred_left = lib.infer_dtype(lk, skipna=False)
+                inferred_right = lib.infer_dtype(rk, skipna=False)
+                bool_types = ["integer", "mixed-integer", "boolean", "empty"]
+                string_types = ["string", "unicode", "mixed", "bytes", "empty"]
+
+                # inferred bool
+                if inferred_left in bool_types and inferred_right in bool_types:
+                    pass
+
+                # unless we are merging non-string-like with string-like
+                elif (
+                    inferred_left in string_types and inferred_right not in string_types
+                ) or (
+                    inferred_right in string_types and inferred_left not in string_types
+                ):
+                    raise ValueError(msg)
+
+            # datetimelikes must match exactly
+            elif needs_i8_conversion(lk.dtype) and not needs_i8_conversion(rk.dtype):
+                raise ValueError(msg)
+            elif not needs_i8_conversion(lk.dtype) and needs_i8_conversion(rk.dtype):
+                raise ValueError(msg)
+            elif isinstance(lk.dtype, DatetimeTZDtype) and not isinstance(
+                rk.dtype, DatetimeTZDtype
+            ):
+                raise ValueError(msg)
+            elif not isinstance(lk.dtype, DatetimeTZDtype) and isinstance(
+                rk.dtype, DatetimeTZDtype
+            ):
+                raise ValueError(msg)
+            elif (
+                isinstance(lk.dtype, DatetimeTZDtype)
+                and isinstance(rk.dtype, DatetimeTZDtype)
+            ) or (lk.dtype.kind == "M" and rk.dtype.kind == "M"):
+                # allows datetime with different resolutions
+                continue
+            # datetime and timedelta not allowed
+            elif lk.dtype.kind == "M" and rk.dtype.kind == "m":
+                raise ValueError(msg)
+            elif lk.dtype.kind == "m" and rk.dtype.kind == "M":
+                raise ValueError(msg)
+
+            elif is_object_dtype(lk.dtype) and is_object_dtype(rk.dtype):
+                continue
+
+            # Houston, we have a problem!
+            # let's coerce to object if the dtypes aren't
+            # categorical, otherwise coerce to the category
+            # dtype. If we coerced categories to object,
+            # then we would lose type information on some
+            # columns, and end up trying to merge
+            # incompatible dtypes. See GH 16900.
+            if name in self.left.columns:
+                typ = cast(Categorical, lk).categories.dtype if lk_is_cat else object
+                self.left = self.left.copy()
+                self.left[name] = self.left[name].astype(typ)
+            if name in self.right.columns:
+                typ = cast(Categorical, rk).categories.dtype if rk_is_cat else object
+                self.right = self.right.copy()
+                self.right[name] = self.right[name].astype(typ)
+
+    def _validate_left_right_on(self, left_on, right_on):
+        left_on = com.maybe_make_list(left_on)
+        right_on = com.maybe_make_list(right_on)
+
+        # Hm, any way to make this logic less complicated??
+        if self.on is None and left_on is None and right_on is None:
+            if self.left_index and self.right_index:
+                left_on, right_on = (), ()
+            elif self.left_index:
+                raise MergeError("Must pass right_on or right_index=True")
+            elif self.right_index:
+                raise MergeError("Must pass left_on or left_index=True")
+            else:
+                # use the common columns
+                left_cols = self.left.columns
+                right_cols = self.right.columns
+                common_cols = left_cols.intersection(right_cols)
+                if len(common_cols) == 0:
+                    raise MergeError(
+                        "No common columns to perform merge on. "
+                        f"Merge options: left_on={left_on}, "
+                        f"right_on={right_on}, "
+                        f"left_index={self.left_index}, "
+                        f"right_index={self.right_index}"
+                    )
+                if (
+                    not left_cols.join(common_cols, how="inner").is_unique
+                    or not right_cols.join(common_cols, how="inner").is_unique
+                ):
+                    raise MergeError(f"Data columns not unique: {repr(common_cols)}")
+                left_on = right_on = common_cols
+        elif self.on is not None:
+            if left_on is not None or right_on is not None:
+                raise MergeError(
+                    'Can only pass argument "on" OR "left_on" '
+                    'and "right_on", not a combination of both.'
+                )
+            if self.left_index or self.right_index:
+                raise MergeError(
+                    'Can only pass argument "on" OR "left_index" '
+                    'and "right_index", not a combination of both.'
+                )
+            left_on = right_on = self.on
+        elif left_on is not None:
+            if self.left_index:
+                raise MergeError(
+                    'Can only pass argument "left_on" OR "left_index" not both.'
+                )
+            if not self.right_index and right_on is None:
+                raise MergeError('Must pass "right_on" OR "right_index".')
+            n = len(left_on)
+            if self.right_index:
+                if len(left_on) != self.right.index.nlevels:
+                    raise ValueError(
+                        "len(left_on) must equal the number "
+                        'of levels in the index of "right"'
+                    )
+                right_on = [None] * n
+        elif right_on is not None:
+            if self.right_index:
+                raise MergeError(
+                    'Can only pass argument "right_on" OR "right_index" not both.'
+                )
+            if not self.left_index and left_on is None:
+                raise MergeError('Must pass "left_on" OR "left_index".')
+            n = len(right_on)
+            if self.left_index:
+                if len(right_on) != self.left.index.nlevels:
+                    raise ValueError(
+                        "len(right_on) must equal the number "
+                        'of levels in the index of "left"'
+                    )
+                left_on = [None] * n
+        if len(right_on) != len(left_on):
+            raise ValueError("len(right_on) must equal len(left_on)")
+
+        return left_on, right_on
+
+    @final
+    def _validate_validate_kwd(self, validate: str) -> None:
+        # Check uniqueness of each
+        if self.left_index:
+            left_unique = self.orig_left.index.is_unique
+        else:
+            left_unique = MultiIndex.from_arrays(self.left_join_keys).is_unique
+
+        if self.right_index:
+            right_unique = self.orig_right.index.is_unique
+        else:
+            right_unique = MultiIndex.from_arrays(self.right_join_keys).is_unique
+
+        # Check data integrity
+        if validate in ["one_to_one", "1:1"]:
+            if not left_unique and not right_unique:
+                raise MergeError(
+                    "Merge keys are not unique in either left "
+                    "or right dataset; not a one-to-one merge"
+                )
+            if not left_unique:
+                raise MergeError(
+                    "Merge keys are not unique in left dataset; not a one-to-one merge"
+                )
+            if not right_unique:
+                raise MergeError(
+                    "Merge keys are not unique in right dataset; not a one-to-one merge"
+                )
+
+        elif validate in ["one_to_many", "1:m"]:
+            if not left_unique:
+                raise MergeError(
+                    "Merge keys are not unique in left dataset; not a one-to-many merge"
+                )
+
+        elif validate in ["many_to_one", "m:1"]:
+            if not right_unique:
+                raise MergeError(
+                    "Merge keys are not unique in right dataset; "
+                    "not a many-to-one merge"
+                )
+
+        elif validate in ["many_to_many", "m:m"]:
+            pass
+
+        else:
+            raise ValueError(
+                f'"{validate}" is not a valid argument. '
+                "Valid arguments are:\n"
+                '- "1:1"\n'
+                '- "1:m"\n'
+                '- "m:1"\n'
+                '- "m:m"\n'
+                '- "one_to_one"\n'
+                '- "one_to_many"\n'
+                '- "many_to_one"\n'
+                '- "many_to_many"'
+            )
+
+
+def get_join_indexers(
+    left_keys: list[ArrayLike],
+    right_keys: list[ArrayLike],
+    sort: bool = False,
+    how: JoinHow = "inner",
+) -> tuple[npt.NDArray[np.intp] | None, npt.NDArray[np.intp] | None]:
+    """
+
+    Parameters
+    ----------
+    left_keys : list[ndarray, ExtensionArray, Index, Series]
+    right_keys : list[ndarray, ExtensionArray, Index, Series]
+    sort : bool, default False
+    how : {'inner', 'outer', 'left', 'right'}, default 'inner'
+
+    Returns
+    -------
+    np.ndarray[np.intp] or None
+        Indexer into the left_keys.
+    np.ndarray[np.intp] or None
+        Indexer into the right_keys.
+    """
+    assert len(left_keys) == len(
+        right_keys
+    ), "left_keys and right_keys must be the same length"
+
+    # fast-path for empty left/right
+    left_n = len(left_keys[0])
+    right_n = len(right_keys[0])
+    if left_n == 0:
+        if how in ["left", "inner"]:
+            return _get_empty_indexer()
+        elif not sort and how in ["right", "outer"]:
+            return _get_no_sort_one_missing_indexer(right_n, True)
+    elif right_n == 0:
+        if how in ["right", "inner"]:
+            return _get_empty_indexer()
+        elif not sort and how in ["left", "outer"]:
+            return _get_no_sort_one_missing_indexer(left_n, False)
+
+    lkey: ArrayLike
+    rkey: ArrayLike
+    if len(left_keys) > 1:
+        # get left & right join labels and num. of levels at each location
+        mapped = (
+            _factorize_keys(left_keys[n], right_keys[n], sort=sort)
+            for n in range(len(left_keys))
+        )
+        zipped = zip(*mapped)
+        llab, rlab, shape = (list(x) for x in zipped)
+
+        # get flat i8 keys from label lists
+        lkey, rkey = _get_join_keys(llab, rlab, tuple(shape), sort)
+    else:
+        lkey = left_keys[0]
+        rkey = right_keys[0]
+
+    left = Index(lkey)
+    right = Index(rkey)
+
+    if (
+        left.is_monotonic_increasing
+        and right.is_monotonic_increasing
+        and (left.is_unique or right.is_unique)
+    ):
+        _, lidx, ridx = left.join(right, how=how, return_indexers=True, sort=sort)
+    else:
+        lidx, ridx = get_join_indexers_non_unique(
+            left._values, right._values, sort, how
+        )
+
+    if lidx is not None and is_range_indexer(lidx, len(left)):
+        lidx = None
+    if ridx is not None and is_range_indexer(ridx, len(right)):
+        ridx = None
+    return lidx, ridx
+
+
+def get_join_indexers_non_unique(
+    left: ArrayLike,
+    right: ArrayLike,
+    sort: bool = False,
+    how: JoinHow = "inner",
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+    """
+    Get join indexers for left and right.
+
+    Parameters
+    ----------
+    left : ArrayLike
+    right : ArrayLike
+    sort : bool, default False
+    how : {'inner', 'outer', 'left', 'right'}, default 'inner'
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+        Indexer into left.
+    np.ndarray[np.intp]
+        Indexer into right.
+    """
+    lkey, rkey, count = _factorize_keys(left, right, sort=sort)
+    if how == "left":
+        lidx, ridx = libjoin.left_outer_join(lkey, rkey, count, sort=sort)
+    elif how == "right":
+        ridx, lidx = libjoin.left_outer_join(rkey, lkey, count, sort=sort)
+    elif how == "inner":
+        lidx, ridx = libjoin.inner_join(lkey, rkey, count, sort=sort)
+    elif how == "outer":
+        lidx, ridx = libjoin.full_outer_join(lkey, rkey, count)
+    return lidx, ridx
+
+
+def restore_dropped_levels_multijoin(
+    left: MultiIndex,
+    right: MultiIndex,
+    dropped_level_names,
+    join_index: Index,
+    lindexer: npt.NDArray[np.intp],
+    rindexer: npt.NDArray[np.intp],
+) -> tuple[FrozenList, FrozenList, FrozenList]:
+    """
+    *this is an internal non-public method*
+
+    Returns the levels, labels and names of a multi-index to multi-index join.
+    Depending on the type of join, this method restores the appropriate
+    dropped levels of the joined multi-index.
+    The method relies on lindexer, rindexer which hold the index positions of
+    left and right, where a join was feasible
+
+    Parameters
+    ----------
+    left : MultiIndex
+        left index
+    right : MultiIndex
+        right index
+    dropped_level_names : str array
+        list of non-common level names
+    join_index : Index
+        the index of the join between the
+        common levels of left and right
+    lindexer : np.ndarray[np.intp]
+        left indexer
+    rindexer : np.ndarray[np.intp]
+        right indexer
+
+    Returns
+    -------
+    levels : list of Index
+        levels of combined multiindexes
+    labels : np.ndarray[np.intp]
+        labels of combined multiindexes
+    names : List[Hashable]
+        names of combined multiindex levels
+
+    """
+
+    def _convert_to_multiindex(index: Index) -> MultiIndex:
+        if isinstance(index, MultiIndex):
+            return index
+        else:
+            return MultiIndex.from_arrays([index._values], names=[index.name])
+
+    # For multi-multi joins with one overlapping level,
+    # the returned index if of type Index
+    # Assure that join_index is of type MultiIndex
+    # so that dropped levels can be appended
+    join_index = _convert_to_multiindex(join_index)
+
+    join_levels = join_index.levels
+    join_codes = join_index.codes
+    join_names = join_index.names
+
+    # Iterate through the levels that must be restored
+    for dropped_level_name in dropped_level_names:
+        if dropped_level_name in left.names:
+            idx = left
+            indexer = lindexer
+        else:
+            idx = right
+            indexer = rindexer
+
+        # The index of the level name to be restored
+        name_idx = idx.names.index(dropped_level_name)
+
+        restore_levels = idx.levels[name_idx]
+        # Inject -1 in the codes list where a join was not possible
+        # IOW indexer[i]=-1
+        codes = idx.codes[name_idx]
+        if indexer is None:
+            restore_codes = codes
+        else:
+            restore_codes = algos.take_nd(codes, indexer, fill_value=-1)
+
+        # error: Cannot determine type of "__add__"
+        join_levels = join_levels + [restore_levels]  # type: ignore[has-type]
+        join_codes = join_codes + [restore_codes]  # type: ignore[has-type]
+        join_names = join_names + [dropped_level_name]
+
+    return join_levels, join_codes, join_names
+
+
+class _OrderedMerge(_MergeOperation):
+    _merge_type = "ordered_merge"
+
+    def __init__(
+        self,
+        left: DataFrame | Series,
+        right: DataFrame | Series,
+        on: IndexLabel | None = None,
+        left_on: IndexLabel | None = None,
+        right_on: IndexLabel | None = None,
+        left_index: bool = False,
+        right_index: bool = False,
+        suffixes: Suffixes = ("_x", "_y"),
+        fill_method: str | None = None,
+        how: JoinHow | Literal["asof"] = "outer",
+    ) -> None:
+        self.fill_method = fill_method
+        _MergeOperation.__init__(
+            self,
+            left,
+            right,
+            on=on,
+            left_on=left_on,
+            left_index=left_index,
+            right_index=right_index,
+            right_on=right_on,
+            how=how,
+            suffixes=suffixes,
+            sort=True,  # factorize sorts
+        )
+
+    def get_result(self, copy: bool | None = True) -> DataFrame:
+        join_index, left_indexer, right_indexer = self._get_join_info()
+
+        left_join_indexer: npt.NDArray[np.intp] | None
+        right_join_indexer: npt.NDArray[np.intp] | None
+
+        if self.fill_method == "ffill":
+            if left_indexer is None:
+                left_join_indexer = None
+            else:
+                left_join_indexer = libjoin.ffill_indexer(left_indexer)
+            if right_indexer is None:
+                right_join_indexer = None
+            else:
+                right_join_indexer = libjoin.ffill_indexer(right_indexer)
+        elif self.fill_method is None:
+            left_join_indexer = left_indexer
+            right_join_indexer = right_indexer
+        else:
+            raise ValueError("fill_method must be 'ffill' or None")
+
+        result = self._reindex_and_concat(
+            join_index, left_join_indexer, right_join_indexer, copy=copy
+        )
+        self._maybe_add_join_keys(result, left_indexer, right_indexer)
+
+        return result
+
+
+def _asof_by_function(direction: str):
+    name = f"asof_join_{direction}_on_X_by_Y"
+    return getattr(libjoin, name, None)
+
+
+class _AsOfMerge(_OrderedMerge):
+    _merge_type = "asof_merge"
+
+    def __init__(
+        self,
+        left: DataFrame | Series,
+        right: DataFrame | Series,
+        on: IndexLabel | None = None,
+        left_on: IndexLabel | None = None,
+        right_on: IndexLabel | None = None,
+        left_index: bool = False,
+        right_index: bool = False,
+        by=None,
+        left_by=None,
+        right_by=None,
+        suffixes: Suffixes = ("_x", "_y"),
+        how: Literal["asof"] = "asof",
+        tolerance=None,
+        allow_exact_matches: bool = True,
+        direction: str = "backward",
+    ) -> None:
+        self.by = by
+        self.left_by = left_by
+        self.right_by = right_by
+        self.tolerance = tolerance
+        self.allow_exact_matches = allow_exact_matches
+        self.direction = direction
+
+        # check 'direction' is valid
+        if self.direction not in ["backward", "forward", "nearest"]:
+            raise MergeError(f"direction invalid: {self.direction}")
+
+        # validate allow_exact_matches
+        if not is_bool(self.allow_exact_matches):
+            msg = (
+                "allow_exact_matches must be boolean, "
+                f"passed {self.allow_exact_matches}"
+            )
+            raise MergeError(msg)
+
+        _OrderedMerge.__init__(
+            self,
+            left,
+            right,
+            on=on,
+            left_on=left_on,
+            right_on=right_on,
+            left_index=left_index,
+            right_index=right_index,
+            how=how,
+            suffixes=suffixes,
+            fill_method=None,
+        )
+
+    def _validate_left_right_on(self, left_on, right_on):
+        left_on, right_on = super()._validate_left_right_on(left_on, right_on)
+
+        # we only allow on to be a single item for on
+        if len(left_on) != 1 and not self.left_index:
+            raise MergeError("can only asof on a key for left")
+
+        if len(right_on) != 1 and not self.right_index:
+            raise MergeError("can only asof on a key for right")
+
+        if self.left_index and isinstance(self.left.index, MultiIndex):
+            raise MergeError("left can only have one index")
+
+        if self.right_index and isinstance(self.right.index, MultiIndex):
+            raise MergeError("right can only have one index")
+
+        # set 'by' columns
+        if self.by is not None:
+            if self.left_by is not None or self.right_by is not None:
+                raise MergeError("Can only pass by OR left_by and right_by")
+            self.left_by = self.right_by = self.by
+        if self.left_by is None and self.right_by is not None:
+            raise MergeError("missing left_by")
+        if self.left_by is not None and self.right_by is None:
+            raise MergeError("missing right_by")
+
+        # GH#29130 Check that merge keys do not have dtype object
+        if not self.left_index:
+            left_on_0 = left_on[0]
+            if isinstance(left_on_0, _known):
+                lo_dtype = left_on_0.dtype
+            else:
+                lo_dtype = (
+                    self.left._get_label_or_level_values(left_on_0).dtype
+                    if left_on_0 in self.left.columns
+                    else self.left.index.get_level_values(left_on_0)
+                )
+        else:
+            lo_dtype = self.left.index.dtype
+
+        if not self.right_index:
+            right_on_0 = right_on[0]
+            if isinstance(right_on_0, _known):
+                ro_dtype = right_on_0.dtype
+            else:
+                ro_dtype = (
+                    self.right._get_label_or_level_values(right_on_0).dtype
+                    if right_on_0 in self.right.columns
+                    else self.right.index.get_level_values(right_on_0)
+                )
+        else:
+            ro_dtype = self.right.index.dtype
+
+        if (
+            is_object_dtype(lo_dtype)
+            or is_object_dtype(ro_dtype)
+            or is_string_dtype(lo_dtype)
+            or is_string_dtype(ro_dtype)
+        ):
+            raise MergeError(
+                f"Incompatible merge dtype, {repr(ro_dtype)} and "
+                f"{repr(lo_dtype)}, both sides must have numeric dtype"
+            )
+
+        # add 'by' to our key-list so we can have it in the
+        # output as a key
+        if self.left_by is not None:
+            if not is_list_like(self.left_by):
+                self.left_by = [self.left_by]
+            if not is_list_like(self.right_by):
+                self.right_by = [self.right_by]
+
+            if len(self.left_by) != len(self.right_by):
+                raise MergeError("left_by and right_by must be the same length")
+
+            left_on = self.left_by + list(left_on)
+            right_on = self.right_by + list(right_on)
+
+        return left_on, right_on
+
+    def _maybe_require_matching_dtypes(
+        self, left_join_keys: list[ArrayLike], right_join_keys: list[ArrayLike]
+    ) -> None:
+        # TODO: why do we do this for AsOfMerge but not the others?
+
+        def _check_dtype_match(left: ArrayLike, right: ArrayLike, i: int):
+            if left.dtype != right.dtype:
+                if isinstance(left.dtype, CategoricalDtype) and isinstance(
+                    right.dtype, CategoricalDtype
+                ):
+                    # The generic error message is confusing for categoricals.
+                    #
+                    # In this function, the join keys include both the original
+                    # ones of the merge_asof() call, and also the keys passed
+                    # to its by= argument. Unordered but equal categories
+                    # are not supported for the former, but will fail
+                    # later with a ValueError, so we don't *need* to check
+                    # for them here.
+                    msg = (
+                        f"incompatible merge keys [{i}] {repr(left.dtype)} and "
+                        f"{repr(right.dtype)}, both sides category, but not equal ones"
+                    )
+                else:
+                    msg = (
+                        f"incompatible merge keys [{i}] {repr(left.dtype)} and "
+                        f"{repr(right.dtype)}, must be the same type"
+                    )
+                raise MergeError(msg)
+
+        # validate index types are the same
+        for i, (lk, rk) in enumerate(zip(left_join_keys, right_join_keys)):
+            _check_dtype_match(lk, rk, i)
+
+        if self.left_index:
+            lt = self.left.index._values
+        else:
+            lt = left_join_keys[-1]
+
+        if self.right_index:
+            rt = self.right.index._values
+        else:
+            rt = right_join_keys[-1]
+
+        _check_dtype_match(lt, rt, 0)
+
+    def _validate_tolerance(self, left_join_keys: list[ArrayLike]) -> None:
+        # validate tolerance; datetime.timedelta or Timedelta if we have a DTI
+        if self.tolerance is not None:
+            if self.left_index:
+                lt = self.left.index._values
+            else:
+                lt = left_join_keys[-1]
+
+            msg = (
+                f"incompatible tolerance {self.tolerance}, must be compat "
+                f"with type {repr(lt.dtype)}"
+            )
+
+            if needs_i8_conversion(lt.dtype) or (
+                isinstance(lt, ArrowExtensionArray) and lt.dtype.kind in "mM"
+            ):
+                if not isinstance(self.tolerance, datetime.timedelta):
+                    raise MergeError(msg)
+                if self.tolerance < Timedelta(0):
+                    raise MergeError("tolerance must be positive")
+
+            elif is_integer_dtype(lt.dtype):
+                if not is_integer(self.tolerance):
+                    raise MergeError(msg)
+                if self.tolerance < 0:
+                    raise MergeError("tolerance must be positive")
+
+            elif is_float_dtype(lt.dtype):
+                if not is_number(self.tolerance):
+                    raise MergeError(msg)
+                # error: Unsupported operand types for > ("int" and "Number")
+                if self.tolerance < 0:  # type: ignore[operator]
+                    raise MergeError("tolerance must be positive")
+
+            else:
+                raise MergeError("key must be integer, timestamp or float")
+
+    def _convert_values_for_libjoin(
+        self, values: AnyArrayLike, side: str
+    ) -> np.ndarray:
+        # we require sortedness and non-null values in the join keys
+        if not Index(values).is_monotonic_increasing:
+            if isna(values).any():
+                raise ValueError(f"Merge keys contain null values on {side} side")
+            raise ValueError(f"{side} keys must be sorted")
+
+        if isinstance(values, ArrowExtensionArray):
+            values = values._maybe_convert_datelike_array()
+
+        if needs_i8_conversion(values.dtype):
+            values = values.view("i8")
+
+        elif isinstance(values, BaseMaskedArray):
+            # we've verified above that no nulls exist
+            values = values._data
+        elif isinstance(values, ExtensionArray):
+            values = values.to_numpy()
+
+        # error: Incompatible return value type (got "Union[ExtensionArray,
+        # Any, ndarray[Any, Any], ndarray[Any, dtype[Any]], Index, Series]",
+        # expected "ndarray[Any, Any]")
+        return values  # type: ignore[return-value]
+
+    def _get_join_indexers(self) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+        """return the join indexers"""
+
+        # values to compare
+        left_values = (
+            self.left.index._values if self.left_index else self.left_join_keys[-1]
+        )
+        right_values = (
+            self.right.index._values if self.right_index else self.right_join_keys[-1]
+        )
+
+        # _maybe_require_matching_dtypes already checked for dtype matching
+        assert left_values.dtype == right_values.dtype
+
+        tolerance = self.tolerance
+        if tolerance is not None:
+            # TODO: can we reuse a tolerance-conversion function from
+            #  e.g. TimedeltaIndex?
+            if needs_i8_conversion(left_values.dtype) or (
+                isinstance(left_values, ArrowExtensionArray)
+                and left_values.dtype.kind in "mM"
+            ):
+                tolerance = Timedelta(tolerance)
+                # TODO: we have no test cases with PeriodDtype here; probably
+                #  need to adjust tolerance for that case.
+                if left_values.dtype.kind in "mM":
+                    # Make sure the i8 representation for tolerance
+                    #  matches that for left_values/right_values.
+                    if isinstance(left_values, ArrowExtensionArray):
+                        unit = left_values.dtype.pyarrow_dtype.unit
+                    else:
+                        unit = ensure_wrapped_if_datetimelike(left_values).unit
+                    tolerance = tolerance.as_unit(unit)
+
+                tolerance = tolerance._value
+
+        # initial type conversion as needed
+        left_values = self._convert_values_for_libjoin(left_values, "left")
+        right_values = self._convert_values_for_libjoin(right_values, "right")
+
+        # a "by" parameter requires special handling
+        if self.left_by is not None:
+            # remove 'on' parameter from values if one existed
+            if self.left_index and self.right_index:
+                left_join_keys = self.left_join_keys
+                right_join_keys = self.right_join_keys
+            else:
+                left_join_keys = self.left_join_keys[0:-1]
+                right_join_keys = self.right_join_keys[0:-1]
+
+            mapped = [
+                _factorize_keys(
+                    left_join_keys[n],
+                    right_join_keys[n],
+                    sort=False,
+                )
+                for n in range(len(left_join_keys))
+            ]
+
+            if len(left_join_keys) == 1:
+                left_by_values = mapped[0][0]
+                right_by_values = mapped[0][1]
+            else:
+                arrs = [np.concatenate(m[:2]) for m in mapped]
+                shape = tuple(m[2] for m in mapped)
+                group_index = get_group_index(
+                    arrs, shape=shape, sort=False, xnull=False
+                )
+                left_len = len(left_join_keys[0])
+                left_by_values = group_index[:left_len]
+                right_by_values = group_index[left_len:]
+
+            left_by_values = ensure_int64(left_by_values)
+            right_by_values = ensure_int64(right_by_values)
+
+            # choose appropriate function by type
+            func = _asof_by_function(self.direction)
+            return func(
+                left_values,
+                right_values,
+                left_by_values,
+                right_by_values,
+                self.allow_exact_matches,
+                tolerance,
+            )
+        else:
+            # choose appropriate function by type
+            func = _asof_by_function(self.direction)
+            return func(
+                left_values,
+                right_values,
+                None,
+                None,
+                self.allow_exact_matches,
+                tolerance,
+                False,
+            )
+
+
+def _get_multiindex_indexer(
+    join_keys: list[ArrayLike], index: MultiIndex, sort: bool
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+    # left & right join labels and num. of levels at each location
+    mapped = (
+        _factorize_keys(index.levels[n]._values, join_keys[n], sort=sort)
+        for n in range(index.nlevels)
+    )
+    zipped = zip(*mapped)
+    rcodes, lcodes, shape = (list(x) for x in zipped)
+    if sort:
+        rcodes = list(map(np.take, rcodes, index.codes))
+    else:
+        i8copy = lambda a: a.astype("i8", subok=False, copy=True)
+        rcodes = list(map(i8copy, index.codes))
+
+    # fix right labels if there were any nulls
+    for i, join_key in enumerate(join_keys):
+        mask = index.codes[i] == -1
+        if mask.any():
+            # check if there already was any nulls at this location
+            # if there was, it is factorized to `shape[i] - 1`
+            a = join_key[lcodes[i] == shape[i] - 1]
+            if a.size == 0 or not a[0] != a[0]:
+                shape[i] += 1
+
+            rcodes[i][mask] = shape[i] - 1
+
+    # get flat i8 join keys
+    lkey, rkey = _get_join_keys(lcodes, rcodes, tuple(shape), sort)
+    return lkey, rkey
+
+
+def _get_empty_indexer() -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+    """Return empty join indexers."""
+    return (
+        np.array([], dtype=np.intp),
+        np.array([], dtype=np.intp),
+    )
+
+
+def _get_no_sort_one_missing_indexer(
+    n: int, left_missing: bool
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+    """
+    Return join indexers where all of one side is selected without sorting
+    and none of the other side is selected.
+
+    Parameters
+    ----------
+    n : int
+        Length of indexers to create.
+    left_missing : bool
+        If True, the left indexer will contain only -1's.
+        If False, the right indexer will contain only -1's.
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+        Left indexer
+    np.ndarray[np.intp]
+        Right indexer
+    """
+    idx = np.arange(n, dtype=np.intp)
+    idx_missing = np.full(shape=n, fill_value=-1, dtype=np.intp)
+    if left_missing:
+        return idx_missing, idx
+    return idx, idx_missing
+
+
+def _left_join_on_index(
+    left_ax: Index, right_ax: Index, join_keys: list[ArrayLike], sort: bool = False
+) -> tuple[Index, npt.NDArray[np.intp] | None, npt.NDArray[np.intp]]:
+    if isinstance(right_ax, MultiIndex):
+        lkey, rkey = _get_multiindex_indexer(join_keys, right_ax, sort=sort)
+    else:
+        # error: Incompatible types in assignment (expression has type
+        # "Union[Union[ExtensionArray, ndarray[Any, Any]], Index, Series]",
+        # variable has type "ndarray[Any, dtype[signedinteger[Any]]]")
+        lkey = join_keys[0]  # type: ignore[assignment]
+        # error: Incompatible types in assignment (expression has type "Index",
+        # variable has type "ndarray[Any, dtype[signedinteger[Any]]]")
+        rkey = right_ax._values  # type: ignore[assignment]
+
+    left_key, right_key, count = _factorize_keys(lkey, rkey, sort=sort)
+    left_indexer, right_indexer = libjoin.left_outer_join(
+        left_key, right_key, count, sort=sort
+    )
+
+    if sort or len(left_ax) != len(left_indexer):
+        # if asked to sort or there are 1-to-many matches
+        join_index = left_ax.take(left_indexer)
+        return join_index, left_indexer, right_indexer
+
+    # left frame preserves order & length of its index
+    return left_ax, None, right_indexer
+
+
+def _factorize_keys(
+    lk: ArrayLike, rk: ArrayLike, sort: bool = True
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp], int]:
+    """
+    Encode left and right keys as enumerated types.
+
+    This is used to get the join indexers to be used when merging DataFrames.
+
+    Parameters
+    ----------
+    lk : ndarray, ExtensionArray
+        Left key.
+    rk : ndarray, ExtensionArray
+        Right key.
+    sort : bool, defaults to True
+        If True, the encoding is done such that the unique elements in the
+        keys are sorted.
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+        Left (resp. right if called with `key='right'`) labels, as enumerated type.
+    np.ndarray[np.intp]
+        Right (resp. left if called with `key='right'`) labels, as enumerated type.
+    int
+        Number of unique elements in union of left and right labels.
+
+    See Also
+    --------
+    merge : Merge DataFrame or named Series objects
+        with a database-style join.
+    algorithms.factorize : Encode the object as an enumerated type
+        or categorical variable.
+
+    Examples
+    --------
+    >>> lk = np.array(["a", "c", "b"])
+    >>> rk = np.array(["a", "c"])
+
+    Here, the unique values are `'a', 'b', 'c'`. With the default
+    `sort=True`, the encoding will be `{0: 'a', 1: 'b', 2: 'c'}`:
+
+    >>> pd.core.reshape.merge._factorize_keys(lk, rk)
+    (array([0, 2, 1]), array([0, 2]), 3)
+
+    With the `sort=False`, the encoding will correspond to the order
+    in which the unique elements first appear: `{0: 'a', 1: 'c', 2: 'b'}`:
+
+    >>> pd.core.reshape.merge._factorize_keys(lk, rk, sort=False)
+    (array([0, 1, 2]), array([0, 1]), 3)
+    """
+    # TODO: if either is a RangeIndex, we can likely factorize more efficiently?
+
+    if (
+        isinstance(lk.dtype, DatetimeTZDtype) and isinstance(rk.dtype, DatetimeTZDtype)
+    ) or (lib.is_np_dtype(lk.dtype, "M") and lib.is_np_dtype(rk.dtype, "M")):
+        # Extract the ndarray (UTC-localized) values
+        # Note: we dont need the dtypes to match, as these can still be compared
+        lk, rk = cast("DatetimeArray", lk)._ensure_matching_resos(rk)
+        lk = cast("DatetimeArray", lk)._ndarray
+        rk = cast("DatetimeArray", rk)._ndarray
+
+    elif (
+        isinstance(lk.dtype, CategoricalDtype)
+        and isinstance(rk.dtype, CategoricalDtype)
+        and lk.dtype == rk.dtype
+    ):
+        assert isinstance(lk, Categorical)
+        assert isinstance(rk, Categorical)
+        # Cast rk to encoding so we can compare codes with lk
+
+        rk = lk._encode_with_my_categories(rk)
+
+        lk = ensure_int64(lk.codes)
+        rk = ensure_int64(rk.codes)
+
+    elif isinstance(lk, ExtensionArray) and lk.dtype == rk.dtype:
+        if (isinstance(lk.dtype, ArrowDtype) and is_string_dtype(lk.dtype)) or (
+            isinstance(lk.dtype, StringDtype) and lk.dtype.storage == "pyarrow"
+        ):
+            import pyarrow as pa
+            import pyarrow.compute as pc
+
+            len_lk = len(lk)
+            lk = lk._pa_array  # type: ignore[attr-defined]
+            rk = rk._pa_array  # type: ignore[union-attr]
+            dc = (
+                pa.chunked_array(lk.chunks + rk.chunks)  # type: ignore[union-attr]
+                .combine_chunks()
+                .dictionary_encode()
+            )
+
+            llab, rlab, count = (
+                pc.fill_null(dc.indices[slice(len_lk)], -1)
+                .to_numpy()
+                .astype(np.intp, copy=False),
+                pc.fill_null(dc.indices[slice(len_lk, None)], -1)
+                .to_numpy()
+                .astype(np.intp, copy=False),
+                len(dc.dictionary),
+            )
+
+            if sort:
+                uniques = dc.dictionary.to_numpy(zero_copy_only=False)
+                llab, rlab = _sort_labels(uniques, llab, rlab)
+
+            if dc.null_count > 0:
+                lmask = llab == -1
+                lany = lmask.any()
+                rmask = rlab == -1
+                rany = rmask.any()
+                if lany:
+                    np.putmask(llab, lmask, count)
+                if rany:
+                    np.putmask(rlab, rmask, count)
+                count += 1
+            return llab, rlab, count
+
+        if not isinstance(lk, BaseMaskedArray) and not (
+            # exclude arrow dtypes that would get cast to object
+            isinstance(lk.dtype, ArrowDtype)
+            and (
+                is_numeric_dtype(lk.dtype.numpy_dtype)
+                or is_string_dtype(lk.dtype)
+                and not sort
+            )
+        ):
+            lk, _ = lk._values_for_factorize()
+
+            # error: Item "ndarray" of "Union[Any, ndarray]" has no attribute
+            # "_values_for_factorize"
+            rk, _ = rk._values_for_factorize()  # type: ignore[union-attr]
+
+    if needs_i8_conversion(lk.dtype) and lk.dtype == rk.dtype:
+        # GH#23917 TODO: Needs tests for non-matching dtypes
+        # GH#23917 TODO: needs tests for case where lk is integer-dtype
+        #  and rk is datetime-dtype
+        lk = np.asarray(lk, dtype=np.int64)
+        rk = np.asarray(rk, dtype=np.int64)
+
+    klass, lk, rk = _convert_arrays_and_get_rizer_klass(lk, rk)
+
+    rizer = klass(max(len(lk), len(rk)))
+
+    if isinstance(lk, BaseMaskedArray):
+        assert isinstance(rk, BaseMaskedArray)
+        llab = rizer.factorize(lk._data, mask=lk._mask)
+        rlab = rizer.factorize(rk._data, mask=rk._mask)
+    elif isinstance(lk, ArrowExtensionArray):
+        assert isinstance(rk, ArrowExtensionArray)
+        # we can only get here with numeric dtypes
+        # TODO: Remove when we have a Factorizer for Arrow
+        llab = rizer.factorize(
+            lk.to_numpy(na_value=1, dtype=lk.dtype.numpy_dtype), mask=lk.isna()
+        )
+        rlab = rizer.factorize(
+            rk.to_numpy(na_value=1, dtype=lk.dtype.numpy_dtype), mask=rk.isna()
+        )
+    else:
+        # Argument 1 to "factorize" of "ObjectFactorizer" has incompatible type
+        # "Union[ndarray[Any, dtype[signedinteger[_64Bit]]],
+        # ndarray[Any, dtype[object_]]]"; expected "ndarray[Any, dtype[object_]]"
+        llab = rizer.factorize(lk)  # type: ignore[arg-type]
+        rlab = rizer.factorize(rk)  # type: ignore[arg-type]
+    assert llab.dtype == np.dtype(np.intp), llab.dtype
+    assert rlab.dtype == np.dtype(np.intp), rlab.dtype
+
+    count = rizer.get_count()
+
+    if sort:
+        uniques = rizer.uniques.to_array()
+        llab, rlab = _sort_labels(uniques, llab, rlab)
+
+    # NA group
+    lmask = llab == -1
+    lany = lmask.any()
+    rmask = rlab == -1
+    rany = rmask.any()
+
+    if lany or rany:
+        if lany:
+            np.putmask(llab, lmask, count)
+        if rany:
+            np.putmask(rlab, rmask, count)
+        count += 1
+
+    return llab, rlab, count
+
+
+def _convert_arrays_and_get_rizer_klass(
+    lk: ArrayLike, rk: ArrayLike
+) -> tuple[type[libhashtable.Factorizer], ArrayLike, ArrayLike]:
+    klass: type[libhashtable.Factorizer]
+    if is_numeric_dtype(lk.dtype):
+        if lk.dtype != rk.dtype:
+            dtype = find_common_type([lk.dtype, rk.dtype])
+            if isinstance(dtype, ExtensionDtype):
+                cls = dtype.construct_array_type()
+                if not isinstance(lk, ExtensionArray):
+                    lk = cls._from_sequence(lk, dtype=dtype, copy=False)
+                else:
+                    lk = lk.astype(dtype, copy=False)
+
+                if not isinstance(rk, ExtensionArray):
+                    rk = cls._from_sequence(rk, dtype=dtype, copy=False)
+                else:
+                    rk = rk.astype(dtype, copy=False)
+            else:
+                lk = lk.astype(dtype, copy=False)
+                rk = rk.astype(dtype, copy=False)
+        if isinstance(lk, BaseMaskedArray):
+            #  Invalid index type "type" for "Dict[Type[object], Type[Factorizer]]";
+            #  expected type "Type[object]"
+            klass = _factorizers[lk.dtype.type]  # type: ignore[index]
+        elif isinstance(lk.dtype, ArrowDtype):
+            klass = _factorizers[lk.dtype.numpy_dtype.type]
+        else:
+            klass = _factorizers[lk.dtype.type]
+
+    else:
+        klass = libhashtable.ObjectFactorizer
+        lk = ensure_object(lk)
+        rk = ensure_object(rk)
+    return klass, lk, rk
+
+
+def _sort_labels(
+    uniques: np.ndarray, left: npt.NDArray[np.intp], right: npt.NDArray[np.intp]
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.intp]]:
+    llength = len(left)
+    labels = np.concatenate([left, right])
+
+    _, new_labels = algos.safe_sort(uniques, labels, use_na_sentinel=True)
+    new_left, new_right = new_labels[:llength], new_labels[llength:]
+
+    return new_left, new_right
+
+
+def _get_join_keys(
+    llab: list[npt.NDArray[np.int64 | np.intp]],
+    rlab: list[npt.NDArray[np.int64 | np.intp]],
+    shape: Shape,
+    sort: bool,
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]:
+    # how many levels can be done without overflow
+    nlev = next(
+        lev
+        for lev in range(len(shape), 0, -1)
+        if not is_int64_overflow_possible(shape[:lev])
+    )
+
+    # get keys for the first `nlev` levels
+    stride = np.prod(shape[1:nlev], dtype="i8")
+    lkey = stride * llab[0].astype("i8", subok=False, copy=False)
+    rkey = stride * rlab[0].astype("i8", subok=False, copy=False)
+
+    for i in range(1, nlev):
+        with np.errstate(divide="ignore"):
+            stride //= shape[i]
+        lkey += llab[i] * stride
+        rkey += rlab[i] * stride
+
+    if nlev == len(shape):  # all done!
+        return lkey, rkey
+
+    # densify current keys to avoid overflow
+    lkey, rkey, count = _factorize_keys(lkey, rkey, sort=sort)
+
+    llab = [lkey] + llab[nlev:]
+    rlab = [rkey] + rlab[nlev:]
+    shape = (count,) + shape[nlev:]
+
+    return _get_join_keys(llab, rlab, shape, sort)
+
+
+def _should_fill(lname, rname) -> bool:
+    if not isinstance(lname, str) or not isinstance(rname, str):
+        return True
+    return lname == rname
+
+
+def _any(x) -> bool:
+    return x is not None and com.any_not_none(*x)
+
+
+def _validate_operand(obj: DataFrame | Series) -> DataFrame:
+    if isinstance(obj, ABCDataFrame):
+        return obj
+    elif isinstance(obj, ABCSeries):
+        if obj.name is None:
+            raise ValueError("Cannot merge a Series without a name")
+        return obj.to_frame()
+    else:
+        raise TypeError(
+            f"Can only merge Series or DataFrame objects, a {type(obj)} was passed"
+        )
+
+
+def _items_overlap_with_suffix(
+    left: Index, right: Index, suffixes: Suffixes
+) -> tuple[Index, Index]:
+    """
+    Suffixes type validation.
+
+    If two indices overlap, add suffixes to overlapping entries.
+
+    If corresponding suffix is empty, the entry is simply converted to string.
+
+    """
+    if not is_list_like(suffixes, allow_sets=False) or isinstance(suffixes, dict):
+        raise TypeError(
+            f"Passing 'suffixes' as a {type(suffixes)}, is not supported. "
+            "Provide 'suffixes' as a tuple instead."
+        )
+
+    to_rename = left.intersection(right)
+    if len(to_rename) == 0:
+        return left, right
+
+    lsuffix, rsuffix = suffixes
+
+    if not lsuffix and not rsuffix:
+        raise ValueError(f"columns overlap but no suffix specified: {to_rename}")
+
+    def renamer(x, suffix: str | None):
+        """
+        Rename the left and right indices.
+
+        If there is overlap, and suffix is not None, add
+        suffix, otherwise, leave it as-is.
+
+        Parameters
+        ----------
+        x : original column name
+        suffix : str or None
+
+        Returns
+        -------
+        x : renamed column name
+        """
+        if x in to_rename and suffix is not None:
+            return f"{x}{suffix}"
+        return x
+
+    lrenamer = partial(renamer, suffix=lsuffix)
+    rrenamer = partial(renamer, suffix=rsuffix)
+
+    llabels = left._transform_index(lrenamer)
+    rlabels = right._transform_index(rrenamer)
+
+    dups = []
+    if not llabels.is_unique:
+        # Only warn when duplicates are caused because of suffixes, already duplicated
+        # columns in origin should not warn
+        dups = llabels[(llabels.duplicated()) & (~left.duplicated())].tolist()
+    if not rlabels.is_unique:
+        dups.extend(rlabels[(rlabels.duplicated()) & (~right.duplicated())].tolist())
+    if dups:
+        raise MergeError(
+            f"Passing 'suffixes' which cause duplicate columns {set(dups)} is "
+            f"not allowed.",
+        )
+
+    return llabels, rlabels
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/pivot.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/pivot.py
new file mode 100644
index 0000000000000000000000000000000000000000..b2a915589cba756c16ecaa95c3d056bd7c902c68
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/pivot.py
@@ -0,0 +1,899 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Sequence,
+)
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import maybe_downcast_to_dtype
+from pandas.core.dtypes.common import (
+    is_list_like,
+    is_nested_list_like,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+import pandas.core.common as com
+from pandas.core.frame import _shared_docs
+from pandas.core.groupby import Grouper
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    get_objs_combined_axis,
+)
+from pandas.core.reshape.concat import concat
+from pandas.core.reshape.util import cartesian_product
+from pandas.core.series import Series
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        AggFuncType,
+        AggFuncTypeBase,
+        AggFuncTypeDict,
+        IndexLabel,
+    )
+
+    from pandas import DataFrame
+
+
+# Note: We need to make sure `frame` is imported before `pivot`, otherwise
+# _shared_docs['pivot_table'] will not yet exist.  TODO: Fix this dependency
+@Substitution("\ndata : DataFrame")
+@Appender(_shared_docs["pivot_table"], indents=1)
+def pivot_table(
+    data: DataFrame,
+    values=None,
+    index=None,
+    columns=None,
+    aggfunc: AggFuncType = "mean",
+    fill_value=None,
+    margins: bool = False,
+    dropna: bool = True,
+    margins_name: Hashable = "All",
+    observed: bool | lib.NoDefault = lib.no_default,
+    sort: bool = True,
+) -> DataFrame:
+    index = _convert_by(index)
+    columns = _convert_by(columns)
+
+    if isinstance(aggfunc, list):
+        pieces: list[DataFrame] = []
+        keys = []
+        for func in aggfunc:
+            _table = __internal_pivot_table(
+                data,
+                values=values,
+                index=index,
+                columns=columns,
+                fill_value=fill_value,
+                aggfunc=func,
+                margins=margins,
+                dropna=dropna,
+                margins_name=margins_name,
+                observed=observed,
+                sort=sort,
+            )
+            pieces.append(_table)
+            keys.append(getattr(func, "__name__", func))
+
+        table = concat(pieces, keys=keys, axis=1)
+        return table.__finalize__(data, method="pivot_table")
+
+    table = __internal_pivot_table(
+        data,
+        values,
+        index,
+        columns,
+        aggfunc,
+        fill_value,
+        margins,
+        dropna,
+        margins_name,
+        observed,
+        sort,
+    )
+    return table.__finalize__(data, method="pivot_table")
+
+
+def __internal_pivot_table(
+    data: DataFrame,
+    values,
+    index,
+    columns,
+    aggfunc: AggFuncTypeBase | AggFuncTypeDict,
+    fill_value,
+    margins: bool,
+    dropna: bool,
+    margins_name: Hashable,
+    observed: bool | lib.NoDefault,
+    sort: bool,
+) -> DataFrame:
+    """
+    Helper of :func:`pandas.pivot_table` for any non-list ``aggfunc``.
+    """
+    keys = index + columns
+
+    values_passed = values is not None
+    if values_passed:
+        if is_list_like(values):
+            values_multi = True
+            values = list(values)
+        else:
+            values_multi = False
+            values = [values]
+
+        # GH14938 Make sure value labels are in data
+        for i in values:
+            if i not in data:
+                raise KeyError(i)
+
+        to_filter = []
+        for x in keys + values:
+            if isinstance(x, Grouper):
+                x = x.key
+            try:
+                if x in data:
+                    to_filter.append(x)
+            except TypeError:
+                pass
+        if len(to_filter) < len(data.columns):
+            data = data[to_filter]
+
+    else:
+        values = data.columns
+        for key in keys:
+            try:
+                values = values.drop(key)
+            except (TypeError, ValueError, KeyError):
+                pass
+        values = list(values)
+
+    observed_bool = False if observed is lib.no_default else observed
+    grouped = data.groupby(keys, observed=observed_bool, sort=sort, dropna=dropna)
+    if observed is lib.no_default and any(
+        ping._passed_categorical for ping in grouped._grouper.groupings
+    ):
+        warnings.warn(
+            "The default value of observed=False is deprecated and will change "
+            "to observed=True in a future version of pandas. Specify "
+            "observed=False to silence this warning and retain the current behavior",
+            category=FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    agged = grouped.agg(aggfunc)
+
+    if dropna and isinstance(agged, ABCDataFrame) and len(agged.columns):
+        agged = agged.dropna(how="all")
+
+    table = agged
+
+    # GH17038, this check should only happen if index is defined (not None)
+    if table.index.nlevels > 1 and index:
+        # Related GH #17123
+        # If index_names are integers, determine whether the integers refer
+        # to the level position or name.
+        index_names = agged.index.names[: len(index)]
+        to_unstack = []
+        for i in range(len(index), len(keys)):
+            name = agged.index.names[i]
+            if name is None or name in index_names:
+                to_unstack.append(i)
+            else:
+                to_unstack.append(name)
+        table = agged.unstack(to_unstack, fill_value=fill_value)
+
+    if not dropna:
+        if isinstance(table.index, MultiIndex):
+            m = MultiIndex.from_arrays(
+                cartesian_product(table.index.levels), names=table.index.names
+            )
+            table = table.reindex(m, axis=0, fill_value=fill_value)
+
+        if isinstance(table.columns, MultiIndex):
+            m = MultiIndex.from_arrays(
+                cartesian_product(table.columns.levels), names=table.columns.names
+            )
+            table = table.reindex(m, axis=1, fill_value=fill_value)
+
+    if sort is True and isinstance(table, ABCDataFrame):
+        table = table.sort_index(axis=1)
+
+    if fill_value is not None:
+        table = table.fillna(fill_value)
+        if aggfunc is len and not observed and lib.is_integer(fill_value):
+            # TODO: can we avoid this?  this used to be handled by
+            #  downcast="infer" in fillna
+            table = table.astype(np.int64)
+
+    if margins:
+        if dropna:
+            data = data[data.notna().all(axis=1)]
+        table = _add_margins(
+            table,
+            data,
+            values,
+            rows=index,
+            cols=columns,
+            aggfunc=aggfunc,
+            observed=dropna,
+            margins_name=margins_name,
+            fill_value=fill_value,
+        )
+
+    # discard the top level
+    if values_passed and not values_multi and table.columns.nlevels > 1:
+        table.columns = table.columns.droplevel(0)
+    if len(index) == 0 and len(columns) > 0:
+        table = table.T
+
+    # GH 15193 Make sure empty columns are removed if dropna=True
+    if isinstance(table, ABCDataFrame) and dropna:
+        table = table.dropna(how="all", axis=1)
+
+    return table
+
+
+def _add_margins(
+    table: DataFrame | Series,
+    data: DataFrame,
+    values,
+    rows,
+    cols,
+    aggfunc,
+    observed: bool,
+    margins_name: Hashable = "All",
+    fill_value=None,
+):
+    if not isinstance(margins_name, str):
+        raise ValueError("margins_name argument must be a string")
+
+    msg = f'Conflicting name "{margins_name}" in margins'
+    for level in table.index.names:
+        if margins_name in table.index.get_level_values(level):
+            raise ValueError(msg)
+
+    grand_margin = _compute_grand_margin(data, values, aggfunc, margins_name)
+
+    if table.ndim == 2:
+        # i.e. DataFrame
+        for level in table.columns.names[1:]:
+            if margins_name in table.columns.get_level_values(level):
+                raise ValueError(msg)
+
+    key: str | tuple[str, ...]
+    if len(rows) > 1:
+        key = (margins_name,) + ("",) * (len(rows) - 1)
+    else:
+        key = margins_name
+
+    if not values and isinstance(table, ABCSeries):
+        # If there are no values and the table is a series, then there is only
+        # one column in the data. Compute grand margin and return it.
+        return table._append(table._constructor({key: grand_margin[margins_name]}))
+
+    elif values:
+        marginal_result_set = _generate_marginal_results(
+            table, data, values, rows, cols, aggfunc, observed, margins_name
+        )
+        if not isinstance(marginal_result_set, tuple):
+            return marginal_result_set
+        result, margin_keys, row_margin = marginal_result_set
+    else:
+        # no values, and table is a DataFrame
+        assert isinstance(table, ABCDataFrame)
+        marginal_result_set = _generate_marginal_results_without_values(
+            table, data, rows, cols, aggfunc, observed, margins_name
+        )
+        if not isinstance(marginal_result_set, tuple):
+            return marginal_result_set
+        result, margin_keys, row_margin = marginal_result_set
+
+    row_margin = row_margin.reindex(result.columns, fill_value=fill_value)
+    # populate grand margin
+    for k in margin_keys:
+        if isinstance(k, str):
+            row_margin[k] = grand_margin[k]
+        else:
+            row_margin[k] = grand_margin[k[0]]
+
+    from pandas import DataFrame
+
+    margin_dummy = DataFrame(row_margin, columns=Index([key])).T
+
+    row_names = result.index.names
+    # check the result column and leave floats
+
+    for dtype in set(result.dtypes):
+        if isinstance(dtype, ExtensionDtype):
+            # Can hold NA already
+            continue
+
+        cols = result.select_dtypes([dtype]).columns
+        margin_dummy[cols] = margin_dummy[cols].apply(
+            maybe_downcast_to_dtype, args=(dtype,)
+        )
+    result = result._append(margin_dummy)
+    result.index.names = row_names
+
+    return result
+
+
+def _compute_grand_margin(
+    data: DataFrame, values, aggfunc, margins_name: Hashable = "All"
+):
+    if values:
+        grand_margin = {}
+        for k, v in data[values].items():
+            try:
+                if isinstance(aggfunc, str):
+                    grand_margin[k] = getattr(v, aggfunc)()
+                elif isinstance(aggfunc, dict):
+                    if isinstance(aggfunc[k], str):
+                        grand_margin[k] = getattr(v, aggfunc[k])()
+                    else:
+                        grand_margin[k] = aggfunc[k](v)
+                else:
+                    grand_margin[k] = aggfunc(v)
+            except TypeError:
+                pass
+        return grand_margin
+    else:
+        return {margins_name: aggfunc(data.index)}
+
+
+def _generate_marginal_results(
+    table,
+    data: DataFrame,
+    values,
+    rows,
+    cols,
+    aggfunc,
+    observed: bool,
+    margins_name: Hashable = "All",
+):
+    margin_keys: list | Index
+    if len(cols) > 0:
+        # need to "interleave" the margins
+        table_pieces = []
+        margin_keys = []
+
+        def _all_key(key):
+            return (key, margins_name) + ("",) * (len(cols) - 1)
+
+        if len(rows) > 0:
+            margin = data[rows + values].groupby(rows, observed=observed).agg(aggfunc)
+            cat_axis = 1
+
+            for key, piece in table.T.groupby(level=0, observed=observed):
+                piece = piece.T
+                all_key = _all_key(key)
+
+                # we are going to mutate this, so need to copy!
+                piece = piece.copy()
+                piece[all_key] = margin[key]
+
+                table_pieces.append(piece)
+                margin_keys.append(all_key)
+        else:
+            from pandas import DataFrame
+
+            cat_axis = 0
+            for key, piece in table.groupby(level=0, observed=observed):
+                if len(cols) > 1:
+                    all_key = _all_key(key)
+                else:
+                    all_key = margins_name
+                table_pieces.append(piece)
+                # GH31016 this is to calculate margin for each group, and assign
+                # corresponded key as index
+                transformed_piece = DataFrame(piece.apply(aggfunc)).T
+                if isinstance(piece.index, MultiIndex):
+                    # We are adding an empty level
+                    transformed_piece.index = MultiIndex.from_tuples(
+                        [all_key], names=piece.index.names + [None]
+                    )
+                else:
+                    transformed_piece.index = Index([all_key], name=piece.index.name)
+
+                # append piece for margin into table_piece
+                table_pieces.append(transformed_piece)
+                margin_keys.append(all_key)
+
+        if not table_pieces:
+            # GH 49240
+            return table
+        else:
+            result = concat(table_pieces, axis=cat_axis)
+
+        if len(rows) == 0:
+            return result
+    else:
+        result = table
+        margin_keys = table.columns
+
+    if len(cols) > 0:
+        row_margin = data[cols + values].groupby(cols, observed=observed).agg(aggfunc)
+        row_margin = row_margin.stack(future_stack=True)
+
+        # GH#26568. Use names instead of indices in case of numeric names
+        new_order_indices = [len(cols)] + list(range(len(cols)))
+        new_order_names = [row_margin.index.names[i] for i in new_order_indices]
+        row_margin.index = row_margin.index.reorder_levels(new_order_names)
+    else:
+        row_margin = data._constructor_sliced(np.nan, index=result.columns)
+
+    return result, margin_keys, row_margin
+
+
+def _generate_marginal_results_without_values(
+    table: DataFrame,
+    data: DataFrame,
+    rows,
+    cols,
+    aggfunc,
+    observed: bool,
+    margins_name: Hashable = "All",
+):
+    margin_keys: list | Index
+    if len(cols) > 0:
+        # need to "interleave" the margins
+        margin_keys = []
+
+        def _all_key():
+            if len(cols) == 1:
+                return margins_name
+            return (margins_name,) + ("",) * (len(cols) - 1)
+
+        if len(rows) > 0:
+            margin = data.groupby(rows, observed=observed)[rows].apply(aggfunc)
+            all_key = _all_key()
+            table[all_key] = margin
+            result = table
+            margin_keys.append(all_key)
+
+        else:
+            margin = data.groupby(level=0, axis=0, observed=observed).apply(aggfunc)
+            all_key = _all_key()
+            table[all_key] = margin
+            result = table
+            margin_keys.append(all_key)
+            return result
+    else:
+        result = table
+        margin_keys = table.columns
+
+    if len(cols):
+        row_margin = data.groupby(cols, observed=observed)[cols].apply(aggfunc)
+    else:
+        row_margin = Series(np.nan, index=result.columns)
+
+    return result, margin_keys, row_margin
+
+
+def _convert_by(by):
+    if by is None:
+        by = []
+    elif (
+        is_scalar(by)
+        or isinstance(by, (np.ndarray, Index, ABCSeries, Grouper))
+        or callable(by)
+    ):
+        by = [by]
+    else:
+        by = list(by)
+    return by
+
+
+@Substitution("\ndata : DataFrame")
+@Appender(_shared_docs["pivot"], indents=1)
+def pivot(
+    data: DataFrame,
+    *,
+    columns: IndexLabel,
+    index: IndexLabel | lib.NoDefault = lib.no_default,
+    values: IndexLabel | lib.NoDefault = lib.no_default,
+) -> DataFrame:
+    columns_listlike = com.convert_to_list_like(columns)
+
+    # If columns is None we will create a MultiIndex level with None as name
+    # which might cause duplicated names because None is the default for
+    # level names
+    data = data.copy(deep=False)
+    data.index = data.index.copy()
+    data.index.names = [
+        name if name is not None else lib.no_default for name in data.index.names
+    ]
+
+    indexed: DataFrame | Series
+    if values is lib.no_default:
+        if index is not lib.no_default:
+            cols = com.convert_to_list_like(index)
+        else:
+            cols = []
+
+        append = index is lib.no_default
+        # error: Unsupported operand types for + ("List[Any]" and "ExtensionArray")
+        # error: Unsupported left operand type for + ("ExtensionArray")
+        indexed = data.set_index(
+            cols + columns_listlike, append=append  # type: ignore[operator]
+        )
+    else:
+        index_list: list[Index] | list[Series]
+        if index is lib.no_default:
+            if isinstance(data.index, MultiIndex):
+                # GH 23955
+                index_list = [
+                    data.index.get_level_values(i) for i in range(data.index.nlevels)
+                ]
+            else:
+                index_list = [
+                    data._constructor_sliced(data.index, name=data.index.name)
+                ]
+        else:
+            index_list = [data[idx] for idx in com.convert_to_list_like(index)]
+
+        data_columns = [data[col] for col in columns_listlike]
+        index_list.extend(data_columns)
+        multiindex = MultiIndex.from_arrays(index_list)
+
+        if is_list_like(values) and not isinstance(values, tuple):
+            # Exclude tuple because it is seen as a single column name
+            values = cast(Sequence[Hashable], values)
+            indexed = data._constructor(
+                data[values]._values, index=multiindex, columns=values
+            )
+        else:
+            indexed = data._constructor_sliced(data[values]._values, index=multiindex)
+    # error: Argument 1 to "unstack" of "DataFrame" has incompatible type "Union
+    # [List[Any], ExtensionArray, ndarray[Any, Any], Index, Series]"; expected
+    # "Hashable"
+    result = indexed.unstack(columns_listlike)  # type: ignore[arg-type]
+    result.index.names = [
+        name if name is not lib.no_default else None for name in result.index.names
+    ]
+
+    return result
+
+
+def crosstab(
+    index,
+    columns,
+    values=None,
+    rownames=None,
+    colnames=None,
+    aggfunc=None,
+    margins: bool = False,
+    margins_name: Hashable = "All",
+    dropna: bool = True,
+    normalize: bool | Literal[0, 1, "all", "index", "columns"] = False,
+) -> DataFrame:
+    """
+    Compute a simple cross tabulation of two (or more) factors.
+
+    By default, computes a frequency table of the factors unless an
+    array of values and an aggregation function are passed.
+
+    Parameters
+    ----------
+    index : array-like, Series, or list of arrays/Series
+        Values to group by in the rows.
+    columns : array-like, Series, or list of arrays/Series
+        Values to group by in the columns.
+    values : array-like, optional
+        Array of values to aggregate according to the factors.
+        Requires `aggfunc` be specified.
+    rownames : sequence, default None
+        If passed, must match number of row arrays passed.
+    colnames : sequence, default None
+        If passed, must match number of column arrays passed.
+    aggfunc : function, optional
+        If specified, requires `values` be specified as well.
+    margins : bool, default False
+        Add row/column margins (subtotals).
+    margins_name : str, default 'All'
+        Name of the row/column that will contain the totals
+        when margins is True.
+    dropna : bool, default True
+        Do not include columns whose entries are all NaN.
+    normalize : bool, {'all', 'index', 'columns'}, or {0,1}, default False
+        Normalize by dividing all values by the sum of values.
+
+        - If passed 'all' or `True`, will normalize over all values.
+        - If passed 'index' will normalize over each row.
+        - If passed 'columns' will normalize over each column.
+        - If margins is `True`, will also normalize margin values.
+
+    Returns
+    -------
+    DataFrame
+        Cross tabulation of the data.
+
+    See Also
+    --------
+    DataFrame.pivot : Reshape data based on column values.
+    pivot_table : Create a pivot table as a DataFrame.
+
+    Notes
+    -----
+    Any Series passed will have their name attributes used unless row or column
+    names for the cross-tabulation are specified.
+
+    Any input passed containing Categorical data will have **all** of its
+    categories included in the cross-tabulation, even if the actual data does
+    not contain any instances of a particular category.
+
+    In the event that there aren't overlapping indexes an empty DataFrame will
+    be returned.
+
+    Reference :ref:`the user guide ` for more examples.
+
+    Examples
+    --------
+    >>> a = np.array(["foo", "foo", "foo", "foo", "bar", "bar",
+    ...               "bar", "bar", "foo", "foo", "foo"], dtype=object)
+    >>> b = np.array(["one", "one", "one", "two", "one", "one",
+    ...               "one", "two", "two", "two", "one"], dtype=object)
+    >>> c = np.array(["dull", "dull", "shiny", "dull", "dull", "shiny",
+    ...               "shiny", "dull", "shiny", "shiny", "shiny"],
+    ...              dtype=object)
+    >>> pd.crosstab(a, [b, c], rownames=['a'], colnames=['b', 'c'])
+    b   one        two
+    c   dull shiny dull shiny
+    a
+    bar    1     2    1     0
+    foo    2     2    1     2
+
+    Here 'c' and 'f' are not represented in the data and will not be
+    shown in the output because dropna is True by default. Set
+    dropna=False to preserve categories with no data.
+
+    >>> foo = pd.Categorical(['a', 'b'], categories=['a', 'b', 'c'])
+    >>> bar = pd.Categorical(['d', 'e'], categories=['d', 'e', 'f'])
+    >>> pd.crosstab(foo, bar)
+    col_0  d  e
+    row_0
+    a      1  0
+    b      0  1
+    >>> pd.crosstab(foo, bar, dropna=False)
+    col_0  d  e  f
+    row_0
+    a      1  0  0
+    b      0  1  0
+    c      0  0  0
+    """
+    if values is None and aggfunc is not None:
+        raise ValueError("aggfunc cannot be used without values.")
+
+    if values is not None and aggfunc is None:
+        raise ValueError("values cannot be used without an aggfunc.")
+
+    if not is_nested_list_like(index):
+        index = [index]
+    if not is_nested_list_like(columns):
+        columns = [columns]
+
+    common_idx = None
+    pass_objs = [x for x in index + columns if isinstance(x, (ABCSeries, ABCDataFrame))]
+    if pass_objs:
+        common_idx = get_objs_combined_axis(pass_objs, intersect=True, sort=False)
+
+    rownames = _get_names(index, rownames, prefix="row")
+    colnames = _get_names(columns, colnames, prefix="col")
+
+    # duplicate names mapped to unique names for pivot op
+    (
+        rownames_mapper,
+        unique_rownames,
+        colnames_mapper,
+        unique_colnames,
+    ) = _build_names_mapper(rownames, colnames)
+
+    from pandas import DataFrame
+
+    data = {
+        **dict(zip(unique_rownames, index)),
+        **dict(zip(unique_colnames, columns)),
+    }
+    df = DataFrame(data, index=common_idx)
+
+    if values is None:
+        df["__dummy__"] = 0
+        kwargs = {"aggfunc": len, "fill_value": 0}
+    else:
+        df["__dummy__"] = values
+        kwargs = {"aggfunc": aggfunc}
+
+    # error: Argument 7 to "pivot_table" of "DataFrame" has incompatible type
+    # "**Dict[str, object]"; expected "Union[...]"
+    table = df.pivot_table(
+        "__dummy__",
+        index=unique_rownames,
+        columns=unique_colnames,
+        margins=margins,
+        margins_name=margins_name,
+        dropna=dropna,
+        observed=False,
+        **kwargs,  # type: ignore[arg-type]
+    )
+
+    # Post-process
+    if normalize is not False:
+        table = _normalize(
+            table, normalize=normalize, margins=margins, margins_name=margins_name
+        )
+
+    table = table.rename_axis(index=rownames_mapper, axis=0)
+    table = table.rename_axis(columns=colnames_mapper, axis=1)
+
+    return table
+
+
+def _normalize(
+    table: DataFrame, normalize, margins: bool, margins_name: Hashable = "All"
+) -> DataFrame:
+    if not isinstance(normalize, (bool, str)):
+        axis_subs = {0: "index", 1: "columns"}
+        try:
+            normalize = axis_subs[normalize]
+        except KeyError as err:
+            raise ValueError("Not a valid normalize argument") from err
+
+    if margins is False:
+        # Actual Normalizations
+        normalizers: dict[bool | str, Callable] = {
+            "all": lambda x: x / x.sum(axis=1).sum(axis=0),
+            "columns": lambda x: x / x.sum(),
+            "index": lambda x: x.div(x.sum(axis=1), axis=0),
+        }
+
+        normalizers[True] = normalizers["all"]
+
+        try:
+            f = normalizers[normalize]
+        except KeyError as err:
+            raise ValueError("Not a valid normalize argument") from err
+
+        table = f(table)
+        table = table.fillna(0)
+
+    elif margins is True:
+        # keep index and column of pivoted table
+        table_index = table.index
+        table_columns = table.columns
+        last_ind_or_col = table.iloc[-1, :].name
+
+        # check if margin name is not in (for MI cases) and not equal to last
+        # index/column and save the column and index margin
+        if (margins_name not in last_ind_or_col) & (margins_name != last_ind_or_col):
+            raise ValueError(f"{margins_name} not in pivoted DataFrame")
+        column_margin = table.iloc[:-1, -1]
+        index_margin = table.iloc[-1, :-1]
+
+        # keep the core table
+        table = table.iloc[:-1, :-1]
+
+        # Normalize core
+        table = _normalize(table, normalize=normalize, margins=False)
+
+        # Fix Margins
+        if normalize == "columns":
+            column_margin = column_margin / column_margin.sum()
+            table = concat([table, column_margin], axis=1)
+            table = table.fillna(0)
+            table.columns = table_columns
+
+        elif normalize == "index":
+            index_margin = index_margin / index_margin.sum()
+            table = table._append(index_margin)
+            table = table.fillna(0)
+            table.index = table_index
+
+        elif normalize == "all" or normalize is True:
+            column_margin = column_margin / column_margin.sum()
+            index_margin = index_margin / index_margin.sum()
+            index_margin.loc[margins_name] = 1
+            table = concat([table, column_margin], axis=1)
+            table = table._append(index_margin)
+
+            table = table.fillna(0)
+            table.index = table_index
+            table.columns = table_columns
+
+        else:
+            raise ValueError("Not a valid normalize argument")
+
+    else:
+        raise ValueError("Not a valid margins argument")
+
+    return table
+
+
+def _get_names(arrs, names, prefix: str = "row"):
+    if names is None:
+        names = []
+        for i, arr in enumerate(arrs):
+            if isinstance(arr, ABCSeries) and arr.name is not None:
+                names.append(arr.name)
+            else:
+                names.append(f"{prefix}_{i}")
+    else:
+        if len(names) != len(arrs):
+            raise AssertionError("arrays and names must have the same length")
+        if not isinstance(names, list):
+            names = list(names)
+
+    return names
+
+
+def _build_names_mapper(
+    rownames: list[str], colnames: list[str]
+) -> tuple[dict[str, str], list[str], dict[str, str], list[str]]:
+    """
+    Given the names of a DataFrame's rows and columns, returns a set of unique row
+    and column names and mappers that convert to original names.
+
+    A row or column name is replaced if it is duplicate among the rows of the inputs,
+    among the columns of the inputs or between the rows and the columns.
+
+    Parameters
+    ----------
+    rownames: list[str]
+    colnames: list[str]
+
+    Returns
+    -------
+    Tuple(Dict[str, str], List[str], Dict[str, str], List[str])
+
+    rownames_mapper: dict[str, str]
+        a dictionary with new row names as keys and original rownames as values
+    unique_rownames: list[str]
+        a list of rownames with duplicate names replaced by dummy names
+    colnames_mapper: dict[str, str]
+        a dictionary with new column names as keys and original column names as values
+    unique_colnames: list[str]
+        a list of column names with duplicate names replaced by dummy names
+
+    """
+
+    def get_duplicates(names):
+        seen: set = set()
+        return {name for name in names if name not in seen}
+
+    shared_names = set(rownames).intersection(set(colnames))
+    dup_names = get_duplicates(rownames) | get_duplicates(colnames) | shared_names
+
+    rownames_mapper = {
+        f"row_{i}": name for i, name in enumerate(rownames) if name in dup_names
+    }
+    unique_rownames = [
+        f"row_{i}" if name in dup_names else name for i, name in enumerate(rownames)
+    ]
+
+    colnames_mapper = {
+        f"col_{i}": name for i, name in enumerate(colnames) if name in dup_names
+    }
+    unique_colnames = [
+        f"col_{i}" if name in dup_names else name for i, name in enumerate(colnames)
+    ]
+
+    return rownames_mapper, unique_rownames, colnames_mapper, unique_colnames
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/reshape.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/reshape.py
new file mode 100644
index 0000000000000000000000000000000000000000..7a49682d7c57c90ed26e890777758ad806bd961b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/reshape.py
@@ -0,0 +1,989 @@
+from __future__ import annotations
+
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+import pandas._libs.reshape as libreshape
+from pandas.errors import PerformanceWarning
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.cast import (
+    find_common_type,
+    maybe_promote,
+)
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_1d_only_ea_dtype,
+    is_integer,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import ExtensionDtype
+from pandas.core.dtypes.missing import notna
+
+import pandas.core.algorithms as algos
+from pandas.core.algorithms import (
+    factorize,
+    unique,
+)
+from pandas.core.arrays.categorical import factorize_from_iterable
+from pandas.core.construction import ensure_wrapped_if_datetimelike
+from pandas.core.frame import DataFrame
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    RangeIndex,
+)
+from pandas.core.reshape.concat import concat
+from pandas.core.series import Series
+from pandas.core.sorting import (
+    compress_group_index,
+    decons_obs_group_ids,
+    get_compressed_ids,
+    get_group_index,
+    get_group_index_sorter,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        Level,
+        npt,
+    )
+
+    from pandas.core.arrays import ExtensionArray
+    from pandas.core.indexes.frozen import FrozenList
+
+
+class _Unstacker:
+    """
+    Helper class to unstack data / pivot with multi-level index
+
+    Parameters
+    ----------
+    index : MultiIndex
+    level : int or str, default last level
+        Level to "unstack". Accepts a name for the level.
+    fill_value : scalar, optional
+        Default value to fill in missing values if subgroups do not have the
+        same set of labels. By default, missing values will be replaced with
+        the default fill value for that data type, NaN for float, NaT for
+        datetimelike, etc. For integer types, by default data will converted to
+        float and missing values will be set to NaN.
+    constructor : object
+        Pandas ``DataFrame`` or subclass used to create unstacked
+        response.  If None, DataFrame will be used.
+
+    Examples
+    --------
+    >>> index = pd.MultiIndex.from_tuples([('one', 'a'), ('one', 'b'),
+    ...                                    ('two', 'a'), ('two', 'b')])
+    >>> s = pd.Series(np.arange(1, 5, dtype=np.int64), index=index)
+    >>> s
+    one  a    1
+         b    2
+    two  a    3
+         b    4
+    dtype: int64
+
+    >>> s.unstack(level=-1)
+         a  b
+    one  1  2
+    two  3  4
+
+    >>> s.unstack(level=0)
+       one  two
+    a    1    3
+    b    2    4
+
+    Returns
+    -------
+    unstacked : DataFrame
+    """
+
+    def __init__(
+        self, index: MultiIndex, level: Level, constructor, sort: bool = True
+    ) -> None:
+        self.constructor = constructor
+        self.sort = sort
+
+        self.index = index.remove_unused_levels()
+
+        self.level = self.index._get_level_number(level)
+
+        # when index includes `nan`, need to lift levels/strides by 1
+        self.lift = 1 if -1 in self.index.codes[self.level] else 0
+
+        # Note: the "pop" below alters these in-place.
+        self.new_index_levels = list(self.index.levels)
+        self.new_index_names = list(self.index.names)
+
+        self.removed_name = self.new_index_names.pop(self.level)
+        self.removed_level = self.new_index_levels.pop(self.level)
+        self.removed_level_full = index.levels[self.level]
+        if not self.sort:
+            unique_codes = unique(self.index.codes[self.level])
+            self.removed_level = self.removed_level.take(unique_codes)
+            self.removed_level_full = self.removed_level_full.take(unique_codes)
+
+        # Bug fix GH 20601
+        # If the data frame is too big, the number of unique index combination
+        # will cause int32 overflow on windows environments.
+        # We want to check and raise an warning before this happens
+        num_rows = np.max([index_level.size for index_level in self.new_index_levels])
+        num_columns = self.removed_level.size
+
+        # GH20601: This forces an overflow if the number of cells is too high.
+        num_cells = num_rows * num_columns
+
+        # GH 26314: Previous ValueError raised was too restrictive for many users.
+        if num_cells > np.iinfo(np.int32).max:
+            warnings.warn(
+                f"The following operation may generate {num_cells} cells "
+                f"in the resulting pandas object.",
+                PerformanceWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        self._make_selectors()
+
+    @cache_readonly
+    def _indexer_and_to_sort(
+        self,
+    ) -> tuple[
+        npt.NDArray[np.intp],
+        list[np.ndarray],  # each has _some_ signed integer dtype
+    ]:
+        v = self.level
+
+        codes = list(self.index.codes)
+        levs = list(self.index.levels)
+        to_sort = codes[:v] + codes[v + 1 :] + [codes[v]]
+        sizes = tuple(len(x) for x in levs[:v] + levs[v + 1 :] + [levs[v]])
+
+        comp_index, obs_ids = get_compressed_ids(to_sort, sizes)
+        ngroups = len(obs_ids)
+
+        indexer = get_group_index_sorter(comp_index, ngroups)
+        return indexer, to_sort
+
+    @cache_readonly
+    def sorted_labels(self) -> list[np.ndarray]:
+        indexer, to_sort = self._indexer_and_to_sort
+        if self.sort:
+            return [line.take(indexer) for line in to_sort]
+        return to_sort
+
+    def _make_sorted_values(self, values: np.ndarray) -> np.ndarray:
+        if self.sort:
+            indexer, _ = self._indexer_and_to_sort
+
+            sorted_values = algos.take_nd(values, indexer, axis=0)
+            return sorted_values
+        return values
+
+    def _make_selectors(self):
+        new_levels = self.new_index_levels
+
+        # make the mask
+        remaining_labels = self.sorted_labels[:-1]
+        level_sizes = tuple(len(x) for x in new_levels)
+
+        comp_index, obs_ids = get_compressed_ids(remaining_labels, level_sizes)
+        ngroups = len(obs_ids)
+
+        comp_index = ensure_platform_int(comp_index)
+        stride = self.index.levshape[self.level] + self.lift
+        self.full_shape = ngroups, stride
+
+        selector = self.sorted_labels[-1] + stride * comp_index + self.lift
+        mask = np.zeros(np.prod(self.full_shape), dtype=bool)
+        mask.put(selector, True)
+
+        if mask.sum() < len(self.index):
+            raise ValueError("Index contains duplicate entries, cannot reshape")
+
+        self.group_index = comp_index
+        self.mask = mask
+        if self.sort:
+            self.compressor = comp_index.searchsorted(np.arange(ngroups))
+        else:
+            self.compressor = np.sort(np.unique(comp_index, return_index=True)[1])
+
+    @cache_readonly
+    def mask_all(self) -> bool:
+        return bool(self.mask.all())
+
+    @cache_readonly
+    def arange_result(self) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.bool_]]:
+        # We cache this for reuse in ExtensionBlock._unstack
+        dummy_arr = np.arange(len(self.index), dtype=np.intp)
+        new_values, mask = self.get_new_values(dummy_arr, fill_value=-1)
+        return new_values, mask.any(0)
+        # TODO: in all tests we have mask.any(0).all(); can we rely on that?
+
+    def get_result(self, values, value_columns, fill_value) -> DataFrame:
+        if values.ndim == 1:
+            values = values[:, np.newaxis]
+
+        if value_columns is None and values.shape[1] != 1:  # pragma: no cover
+            raise ValueError("must pass column labels for multi-column data")
+
+        values, _ = self.get_new_values(values, fill_value)
+        columns = self.get_new_columns(value_columns)
+        index = self.new_index
+
+        return self.constructor(
+            values, index=index, columns=columns, dtype=values.dtype
+        )
+
+    def get_new_values(self, values, fill_value=None):
+        if values.ndim == 1:
+            values = values[:, np.newaxis]
+
+        sorted_values = self._make_sorted_values(values)
+
+        # place the values
+        length, width = self.full_shape
+        stride = values.shape[1]
+        result_width = width * stride
+        result_shape = (length, result_width)
+        mask = self.mask
+        mask_all = self.mask_all
+
+        # we can simply reshape if we don't have a mask
+        if mask_all and len(values):
+            # TODO: Under what circumstances can we rely on sorted_values
+            #  matching values?  When that holds, we can slice instead
+            #  of take (in particular for EAs)
+            new_values = (
+                sorted_values.reshape(length, width, stride)
+                .swapaxes(1, 2)
+                .reshape(result_shape)
+            )
+            new_mask = np.ones(result_shape, dtype=bool)
+            return new_values, new_mask
+
+        dtype = values.dtype
+
+        # if our mask is all True, then we can use our existing dtype
+        if mask_all:
+            dtype = values.dtype
+            new_values = np.empty(result_shape, dtype=dtype)
+        else:
+            if isinstance(dtype, ExtensionDtype):
+                # GH#41875
+                # We are assuming that fill_value can be held by this dtype,
+                #  unlike the non-EA case that promotes.
+                cls = dtype.construct_array_type()
+                new_values = cls._empty(result_shape, dtype=dtype)
+                new_values[:] = fill_value
+            else:
+                dtype, fill_value = maybe_promote(dtype, fill_value)
+                new_values = np.empty(result_shape, dtype=dtype)
+                new_values.fill(fill_value)
+
+        name = dtype.name
+        new_mask = np.zeros(result_shape, dtype=bool)
+
+        # we need to convert to a basic dtype
+        # and possibly coerce an input to our output dtype
+        # e.g. ints -> floats
+        if needs_i8_conversion(values.dtype):
+            sorted_values = sorted_values.view("i8")
+            new_values = new_values.view("i8")
+        else:
+            sorted_values = sorted_values.astype(name, copy=False)
+
+        # fill in our values & mask
+        libreshape.unstack(
+            sorted_values,
+            mask.view("u1"),
+            stride,
+            length,
+            width,
+            new_values,
+            new_mask.view("u1"),
+        )
+
+        # reconstruct dtype if needed
+        if needs_i8_conversion(values.dtype):
+            # view as datetime64 so we can wrap in DatetimeArray and use
+            #  DTA's view method
+            new_values = new_values.view("M8[ns]")
+            new_values = ensure_wrapped_if_datetimelike(new_values)
+            new_values = new_values.view(values.dtype)
+
+        return new_values, new_mask
+
+    def get_new_columns(self, value_columns: Index | None):
+        if value_columns is None:
+            if self.lift == 0:
+                return self.removed_level._rename(name=self.removed_name)
+
+            lev = self.removed_level.insert(0, item=self.removed_level._na_value)
+            return lev.rename(self.removed_name)
+
+        stride = len(self.removed_level) + self.lift
+        width = len(value_columns)
+        propagator = np.repeat(np.arange(width), stride)
+
+        new_levels: FrozenList | list[Index]
+
+        if isinstance(value_columns, MultiIndex):
+            # error: Cannot determine type of "__add__"  [has-type]
+            new_levels = value_columns.levels + (  # type: ignore[has-type]
+                self.removed_level_full,
+            )
+            new_names = value_columns.names + (self.removed_name,)
+
+            new_codes = [lab.take(propagator) for lab in value_columns.codes]
+        else:
+            new_levels = [
+                value_columns,
+                self.removed_level_full,
+            ]
+            new_names = [value_columns.name, self.removed_name]
+            new_codes = [propagator]
+
+        repeater = self._repeater
+
+        # The entire level is then just a repetition of the single chunk:
+        new_codes.append(np.tile(repeater, width))
+        return MultiIndex(
+            levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+        )
+
+    @cache_readonly
+    def _repeater(self) -> np.ndarray:
+        # The two indices differ only if the unstacked level had unused items:
+        if len(self.removed_level_full) != len(self.removed_level):
+            # In this case, we remap the new codes to the original level:
+            repeater = self.removed_level_full.get_indexer(self.removed_level)
+            if self.lift:
+                repeater = np.insert(repeater, 0, -1)
+        else:
+            # Otherwise, we just use each level item exactly once:
+            stride = len(self.removed_level) + self.lift
+            repeater = np.arange(stride) - self.lift
+
+        return repeater
+
+    @cache_readonly
+    def new_index(self) -> MultiIndex:
+        # Does not depend on values or value_columns
+        result_codes = [lab.take(self.compressor) for lab in self.sorted_labels[:-1]]
+
+        # construct the new index
+        if len(self.new_index_levels) == 1:
+            level, level_codes = self.new_index_levels[0], result_codes[0]
+            if (level_codes == -1).any():
+                level = level.insert(len(level), level._na_value)
+            return level.take(level_codes).rename(self.new_index_names[0])
+
+        return MultiIndex(
+            levels=self.new_index_levels,
+            codes=result_codes,
+            names=self.new_index_names,
+            verify_integrity=False,
+        )
+
+
+def _unstack_multiple(
+    data: Series | DataFrame, clocs, fill_value=None, sort: bool = True
+):
+    if len(clocs) == 0:
+        return data
+
+    # NOTE: This doesn't deal with hierarchical columns yet
+
+    index = data.index
+    index = cast(MultiIndex, index)  # caller is responsible for checking
+
+    # GH 19966 Make sure if MultiIndexed index has tuple name, they will be
+    # recognised as a whole
+    if clocs in index.names:
+        clocs = [clocs]
+    clocs = [index._get_level_number(i) for i in clocs]
+
+    rlocs = [i for i in range(index.nlevels) if i not in clocs]
+
+    clevels = [index.levels[i] for i in clocs]
+    ccodes = [index.codes[i] for i in clocs]
+    cnames = [index.names[i] for i in clocs]
+    rlevels = [index.levels[i] for i in rlocs]
+    rcodes = [index.codes[i] for i in rlocs]
+    rnames = [index.names[i] for i in rlocs]
+
+    shape = tuple(len(x) for x in clevels)
+    group_index = get_group_index(ccodes, shape, sort=False, xnull=False)
+
+    comp_ids, obs_ids = compress_group_index(group_index, sort=False)
+    recons_codes = decons_obs_group_ids(comp_ids, obs_ids, shape, ccodes, xnull=False)
+
+    if not rlocs:
+        # Everything is in clocs, so the dummy df has a regular index
+        dummy_index = Index(obs_ids, name="__placeholder__")
+    else:
+        dummy_index = MultiIndex(
+            levels=rlevels + [obs_ids],
+            codes=rcodes + [comp_ids],
+            names=rnames + ["__placeholder__"],
+            verify_integrity=False,
+        )
+
+    if isinstance(data, Series):
+        dummy = data.copy()
+        dummy.index = dummy_index
+
+        unstacked = dummy.unstack("__placeholder__", fill_value=fill_value, sort=sort)
+        new_levels = clevels
+        new_names = cnames
+        new_codes = recons_codes
+    else:
+        if isinstance(data.columns, MultiIndex):
+            result = data
+            while clocs:
+                val = clocs.pop(0)
+                result = result.unstack(val, fill_value=fill_value, sort=sort)
+                clocs = [v if v < val else v - 1 for v in clocs]
+
+            return result
+
+        # GH#42579 deep=False to avoid consolidating
+        dummy_df = data.copy(deep=False)
+        dummy_df.index = dummy_index
+
+        unstacked = dummy_df.unstack(
+            "__placeholder__", fill_value=fill_value, sort=sort
+        )
+        if isinstance(unstacked, Series):
+            unstcols = unstacked.index
+        else:
+            unstcols = unstacked.columns
+        assert isinstance(unstcols, MultiIndex)  # for mypy
+        new_levels = [unstcols.levels[0]] + clevels
+        new_names = [data.columns.name] + cnames
+
+        new_codes = [unstcols.codes[0]]
+        new_codes.extend(rec.take(unstcols.codes[-1]) for rec in recons_codes)
+
+    new_columns = MultiIndex(
+        levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+    )
+
+    if isinstance(unstacked, Series):
+        unstacked.index = new_columns
+    else:
+        unstacked.columns = new_columns
+
+    return unstacked
+
+
+def unstack(obj: Series | DataFrame, level, fill_value=None, sort: bool = True):
+    if isinstance(level, (tuple, list)):
+        if len(level) != 1:
+            # _unstack_multiple only handles MultiIndexes,
+            # and isn't needed for a single level
+            return _unstack_multiple(obj, level, fill_value=fill_value, sort=sort)
+        else:
+            level = level[0]
+
+    if not is_integer(level) and not level == "__placeholder__":
+        # check if level is valid in case of regular index
+        obj.index._get_level_number(level)
+
+    if isinstance(obj, DataFrame):
+        if isinstance(obj.index, MultiIndex):
+            return _unstack_frame(obj, level, fill_value=fill_value, sort=sort)
+        else:
+            return obj.T.stack(future_stack=True)
+    elif not isinstance(obj.index, MultiIndex):
+        # GH 36113
+        # Give nicer error messages when unstack a Series whose
+        # Index is not a MultiIndex.
+        raise ValueError(
+            f"index must be a MultiIndex to unstack, {type(obj.index)} was passed"
+        )
+    else:
+        if is_1d_only_ea_dtype(obj.dtype):
+            return _unstack_extension_series(obj, level, fill_value, sort=sort)
+        unstacker = _Unstacker(
+            obj.index, level=level, constructor=obj._constructor_expanddim, sort=sort
+        )
+        return unstacker.get_result(
+            obj._values, value_columns=None, fill_value=fill_value
+        )
+
+
+def _unstack_frame(
+    obj: DataFrame, level, fill_value=None, sort: bool = True
+) -> DataFrame:
+    assert isinstance(obj.index, MultiIndex)  # checked by caller
+    unstacker = _Unstacker(
+        obj.index, level=level, constructor=obj._constructor, sort=sort
+    )
+
+    if not obj._can_fast_transpose:
+        mgr = obj._mgr.unstack(unstacker, fill_value=fill_value)
+        return obj._constructor_from_mgr(mgr, axes=mgr.axes)
+    else:
+        return unstacker.get_result(
+            obj._values, value_columns=obj.columns, fill_value=fill_value
+        )
+
+
+def _unstack_extension_series(
+    series: Series, level, fill_value, sort: bool
+) -> DataFrame:
+    """
+    Unstack an ExtensionArray-backed Series.
+
+    The ExtensionDtype is preserved.
+
+    Parameters
+    ----------
+    series : Series
+        A Series with an ExtensionArray for values
+    level : Any
+        The level name or number.
+    fill_value : Any
+        The user-level (not physical storage) fill value to use for
+        missing values introduced by the reshape. Passed to
+        ``series.values.take``.
+    sort : bool
+        Whether to sort the resulting MuliIndex levels
+
+    Returns
+    -------
+    DataFrame
+        Each column of the DataFrame will have the same dtype as
+        the input Series.
+    """
+    # Defer to the logic in ExtensionBlock._unstack
+    df = series.to_frame()
+    result = df.unstack(level=level, fill_value=fill_value, sort=sort)
+
+    # equiv: result.droplevel(level=0, axis=1)
+    #  but this avoids an extra copy
+    result.columns = result.columns._drop_level_numbers([0])
+    return result
+
+
+def stack(frame: DataFrame, level=-1, dropna: bool = True, sort: bool = True):
+    """
+    Convert DataFrame to Series with multi-level Index. Columns become the
+    second level of the resulting hierarchical index
+
+    Returns
+    -------
+    stacked : Series or DataFrame
+    """
+
+    def stack_factorize(index):
+        if index.is_unique:
+            return index, np.arange(len(index))
+        codes, categories = factorize_from_iterable(index)
+        return categories, codes
+
+    N, K = frame.shape
+
+    # Will also convert negative level numbers and check if out of bounds.
+    level_num = frame.columns._get_level_number(level)
+
+    if isinstance(frame.columns, MultiIndex):
+        return _stack_multi_columns(
+            frame, level_num=level_num, dropna=dropna, sort=sort
+        )
+    elif isinstance(frame.index, MultiIndex):
+        new_levels = list(frame.index.levels)
+        new_codes = [lab.repeat(K) for lab in frame.index.codes]
+
+        clev, clab = stack_factorize(frame.columns)
+        new_levels.append(clev)
+        new_codes.append(np.tile(clab, N).ravel())
+
+        new_names = list(frame.index.names)
+        new_names.append(frame.columns.name)
+        new_index = MultiIndex(
+            levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+        )
+    else:
+        levels, (ilab, clab) = zip(*map(stack_factorize, (frame.index, frame.columns)))
+        codes = ilab.repeat(K), np.tile(clab, N).ravel()
+        new_index = MultiIndex(
+            levels=levels,
+            codes=codes,
+            names=[frame.index.name, frame.columns.name],
+            verify_integrity=False,
+        )
+
+    new_values: ArrayLike
+    if not frame.empty and frame._is_homogeneous_type:
+        # For homogeneous EAs, frame._values will coerce to object. So
+        # we concatenate instead.
+        dtypes = list(frame.dtypes._values)
+        dtype = dtypes[0]
+
+        if isinstance(dtype, ExtensionDtype):
+            arr = dtype.construct_array_type()
+            new_values = arr._concat_same_type(
+                [col._values for _, col in frame.items()]
+            )
+            new_values = _reorder_for_extension_array_stack(new_values, N, K)
+        else:
+            # homogeneous, non-EA
+            new_values = frame._values.ravel()
+
+    else:
+        # non-homogeneous
+        new_values = frame._values.ravel()
+
+    if dropna:
+        mask = notna(new_values)
+        new_values = new_values[mask]
+        new_index = new_index[mask]
+
+    return frame._constructor_sliced(new_values, index=new_index)
+
+
+def stack_multiple(frame: DataFrame, level, dropna: bool = True, sort: bool = True):
+    # If all passed levels match up to column names, no
+    # ambiguity about what to do
+    if all(lev in frame.columns.names for lev in level):
+        result = frame
+        for lev in level:
+            result = stack(result, lev, dropna=dropna, sort=sort)
+
+    # Otherwise, level numbers may change as each successive level is stacked
+    elif all(isinstance(lev, int) for lev in level):
+        # As each stack is done, the level numbers decrease, so we need
+        #  to account for that when level is a sequence of ints
+        result = frame
+        # _get_level_number() checks level numbers are in range and converts
+        # negative numbers to positive
+        level = [frame.columns._get_level_number(lev) for lev in level]
+
+        while level:
+            lev = level.pop(0)
+            result = stack(result, lev, dropna=dropna, sort=sort)
+            # Decrement all level numbers greater than current, as these
+            # have now shifted down by one
+            level = [v if v <= lev else v - 1 for v in level]
+
+    else:
+        raise ValueError(
+            "level should contain all level names or all level "
+            "numbers, not a mixture of the two."
+        )
+
+    return result
+
+
+def _stack_multi_column_index(columns: MultiIndex) -> MultiIndex:
+    """Creates a MultiIndex from the first N-1 levels of this MultiIndex."""
+    if len(columns.levels) <= 2:
+        return columns.levels[0]._rename(name=columns.names[0])
+
+    levs = [
+        [lev[c] if c >= 0 else None for c in codes]
+        for lev, codes in zip(columns.levels[:-1], columns.codes[:-1])
+    ]
+
+    # Remove duplicate tuples in the MultiIndex.
+    tuples = zip(*levs)
+    unique_tuples = (key for key, _ in itertools.groupby(tuples))
+    new_levs = zip(*unique_tuples)
+
+    # The dtype of each level must be explicitly set to avoid inferring the wrong type.
+    # See GH-36991.
+    return MultiIndex.from_arrays(
+        [
+            # Not all indices can accept None values.
+            Index(new_lev, dtype=lev.dtype) if None not in new_lev else new_lev
+            for new_lev, lev in zip(new_levs, columns.levels)
+        ],
+        names=columns.names[:-1],
+    )
+
+
+def _stack_multi_columns(
+    frame: DataFrame, level_num: int = -1, dropna: bool = True, sort: bool = True
+) -> DataFrame:
+    def _convert_level_number(level_num: int, columns: Index):
+        """
+        Logic for converting the level number to something we can safely pass
+        to swaplevel.
+
+        If `level_num` matches a column name return the name from
+        position `level_num`, otherwise return `level_num`.
+        """
+        if level_num in columns.names:
+            return columns.names[level_num]
+
+        return level_num
+
+    this = frame.copy(deep=False)
+    mi_cols = this.columns  # cast(MultiIndex, this.columns)
+    assert isinstance(mi_cols, MultiIndex)  # caller is responsible
+
+    # this makes life much simpler
+    if level_num != mi_cols.nlevels - 1:
+        # roll levels to put selected level at end
+        roll_columns = mi_cols
+        for i in range(level_num, mi_cols.nlevels - 1):
+            # Need to check if the ints conflict with level names
+            lev1 = _convert_level_number(i, roll_columns)
+            lev2 = _convert_level_number(i + 1, roll_columns)
+            roll_columns = roll_columns.swaplevel(lev1, lev2)
+        this.columns = mi_cols = roll_columns
+
+    if not mi_cols._is_lexsorted() and sort:
+        # Workaround the edge case where 0 is one of the column names,
+        # which interferes with trying to sort based on the first
+        # level
+        level_to_sort = _convert_level_number(0, mi_cols)
+        this = this.sort_index(level=level_to_sort, axis=1)
+        mi_cols = this.columns
+
+    mi_cols = cast(MultiIndex, mi_cols)
+    new_columns = _stack_multi_column_index(mi_cols)
+
+    # time to ravel the values
+    new_data = {}
+    level_vals = mi_cols.levels[-1]
+    level_codes = unique(mi_cols.codes[-1])
+    if sort:
+        level_codes = np.sort(level_codes)
+    level_vals_nan = level_vals.insert(len(level_vals), None)
+
+    level_vals_used = np.take(level_vals_nan, level_codes)
+    levsize = len(level_codes)
+    drop_cols = []
+    for key in new_columns:
+        try:
+            loc = this.columns.get_loc(key)
+        except KeyError:
+            drop_cols.append(key)
+            continue
+
+        # can make more efficient?
+        # we almost always return a slice
+        # but if unsorted can get a boolean
+        # indexer
+        if not isinstance(loc, slice):
+            slice_len = len(loc)
+        else:
+            slice_len = loc.stop - loc.start
+
+        if slice_len != levsize:
+            chunk = this.loc[:, this.columns[loc]]
+            chunk.columns = level_vals_nan.take(chunk.columns.codes[-1])
+            value_slice = chunk.reindex(columns=level_vals_used).values
+        else:
+            subset = this.iloc[:, loc]
+            dtype = find_common_type(subset.dtypes.tolist())
+            if isinstance(dtype, ExtensionDtype):
+                # TODO(EA2D): won't need special case, can go through .values
+                #  paths below (might change to ._values)
+                value_slice = dtype.construct_array_type()._concat_same_type(
+                    [x._values.astype(dtype, copy=False) for _, x in subset.items()]
+                )
+                N, K = subset.shape
+                idx = np.arange(N * K).reshape(K, N).T.ravel()
+                value_slice = value_slice.take(idx)
+            else:
+                value_slice = subset.values
+
+        if value_slice.ndim > 1:
+            # i.e. not extension
+            value_slice = value_slice.ravel()
+
+        new_data[key] = value_slice
+
+    if len(drop_cols) > 0:
+        new_columns = new_columns.difference(drop_cols)
+
+    N = len(this)
+
+    if isinstance(this.index, MultiIndex):
+        new_levels = list(this.index.levels)
+        new_names = list(this.index.names)
+        new_codes = [lab.repeat(levsize) for lab in this.index.codes]
+    else:
+        old_codes, old_levels = factorize_from_iterable(this.index)
+        new_levels = [old_levels]
+        new_codes = [old_codes.repeat(levsize)]
+        new_names = [this.index.name]  # something better?
+
+    new_levels.append(level_vals)
+    new_codes.append(np.tile(level_codes, N))
+    new_names.append(frame.columns.names[level_num])
+
+    new_index = MultiIndex(
+        levels=new_levels, codes=new_codes, names=new_names, verify_integrity=False
+    )
+
+    result = frame._constructor(new_data, index=new_index, columns=new_columns)
+
+    if frame.columns.nlevels > 1:
+        desired_columns = frame.columns._drop_level_numbers([level_num]).unique()
+        if not result.columns.equals(desired_columns):
+            result = result[desired_columns]
+
+    # more efficient way to go about this? can do the whole masking biz but
+    # will only save a small amount of time...
+    if dropna:
+        result = result.dropna(axis=0, how="all")
+
+    return result
+
+
+def _reorder_for_extension_array_stack(
+    arr: ExtensionArray, n_rows: int, n_columns: int
+) -> ExtensionArray:
+    """
+    Re-orders the values when stacking multiple extension-arrays.
+
+    The indirect stacking method used for EAs requires a followup
+    take to get the order correct.
+
+    Parameters
+    ----------
+    arr : ExtensionArray
+    n_rows, n_columns : int
+        The number of rows and columns in the original DataFrame.
+
+    Returns
+    -------
+    taken : ExtensionArray
+        The original `arr` with elements re-ordered appropriately
+
+    Examples
+    --------
+    >>> arr = np.array(['a', 'b', 'c', 'd', 'e', 'f'])
+    >>> _reorder_for_extension_array_stack(arr, 2, 3)
+    array(['a', 'c', 'e', 'b', 'd', 'f'], dtype='>> _reorder_for_extension_array_stack(arr, 3, 2)
+    array(['a', 'd', 'b', 'e', 'c', 'f'], dtype=' Series | DataFrame:
+    if frame.columns.nunique() != len(frame.columns):
+        raise ValueError("Columns with duplicate values are not supported in stack")
+
+    # If we need to drop `level` from columns, it needs to be in descending order
+    drop_levnums = sorted(level, reverse=True)
+    stack_cols = frame.columns._drop_level_numbers(
+        [k for k in range(frame.columns.nlevels) if k not in level][::-1]
+    )
+    if len(level) > 1:
+        # Arrange columns in the order we want to take them, e.g. level=[2, 0, 1]
+        sorter = np.argsort(level)
+        ordered_stack_cols = stack_cols._reorder_ilevels(sorter)
+    else:
+        ordered_stack_cols = stack_cols
+
+    stack_cols_unique = stack_cols.unique()
+    ordered_stack_cols_unique = ordered_stack_cols.unique()
+
+    # Grab data for each unique index to be stacked
+    buf = []
+    for idx in stack_cols_unique:
+        if len(frame.columns) == 1:
+            data = frame.copy()
+        else:
+            # Take the data from frame corresponding to this idx value
+            if len(level) == 1:
+                idx = (idx,)
+            gen = iter(idx)
+            column_indexer = tuple(
+                next(gen) if k in level else slice(None)
+                for k in range(frame.columns.nlevels)
+            )
+            data = frame.loc[:, column_indexer]
+
+        if len(level) < frame.columns.nlevels:
+            data.columns = data.columns._drop_level_numbers(drop_levnums)
+        elif stack_cols.nlevels == 1:
+            if data.ndim == 1:
+                data.name = 0
+            else:
+                data.columns = RangeIndex(len(data.columns))
+        buf.append(data)
+
+    result: Series | DataFrame
+    if len(buf) > 0 and not frame.empty:
+        result = concat(buf)
+        ratio = len(result) // len(frame)
+    else:
+        # input is empty
+        if len(level) < frame.columns.nlevels:
+            # concat column order may be different from dropping the levels
+            new_columns = frame.columns._drop_level_numbers(drop_levnums).unique()
+        else:
+            new_columns = [0]
+        result = DataFrame(columns=new_columns, dtype=frame._values.dtype)
+        ratio = 0
+
+    if len(level) < frame.columns.nlevels:
+        # concat column order may be different from dropping the levels
+        desired_columns = frame.columns._drop_level_numbers(drop_levnums).unique()
+        if not result.columns.equals(desired_columns):
+            result = result[desired_columns]
+
+    # Construct the correct MultiIndex by combining the frame's index and
+    # stacked columns.
+    index_levels: list | FrozenList
+    if isinstance(frame.index, MultiIndex):
+        index_levels = frame.index.levels
+        index_codes = list(np.tile(frame.index.codes, (1, ratio)))
+    else:
+        codes, uniques = factorize(frame.index, use_na_sentinel=False)
+        index_levels = [uniques]
+        index_codes = list(np.tile(codes, (1, ratio)))
+    if isinstance(stack_cols, MultiIndex):
+        column_levels = ordered_stack_cols.levels
+        column_codes = ordered_stack_cols.drop_duplicates().codes
+    else:
+        column_levels = [ordered_stack_cols.unique()]
+        column_codes = [factorize(ordered_stack_cols_unique, use_na_sentinel=False)[0]]
+    column_codes = [np.repeat(codes, len(frame)) for codes in column_codes]
+    result.index = MultiIndex(
+        levels=index_levels + column_levels,
+        codes=index_codes + column_codes,
+        names=frame.index.names + list(ordered_stack_cols.names),
+        verify_integrity=False,
+    )
+
+    # sort result, but faster than calling sort_index since we know the order we need
+    len_df = len(frame)
+    n_uniques = len(ordered_stack_cols_unique)
+    indexer = np.arange(n_uniques)
+    idxs = np.tile(len_df * indexer, len_df) + np.repeat(np.arange(len_df), n_uniques)
+    result = result.take(idxs)
+
+    # Reshape/rename if needed and dropna
+    if result.ndim == 2 and frame.columns.nlevels == len(level):
+        if len(result.columns) == 0:
+            result = Series(index=result.index)
+        else:
+            result = result.iloc[:, 0]
+    if result.ndim == 1:
+        result.name = None
+
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/tile.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/tile.py
new file mode 100644
index 0000000000000000000000000000000000000000..2b0c6fbb8e3bf69fcb60ce3257450260af2a9f6b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/tile.py
@@ -0,0 +1,638 @@
+"""
+Quantilization functions and related stuff
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    Timedelta,
+    Timestamp,
+    lib,
+)
+
+from pandas.core.dtypes.common import (
+    ensure_platform_int,
+    is_bool_dtype,
+    is_integer,
+    is_list_like,
+    is_numeric_dtype,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import ABCSeries
+from pandas.core.dtypes.missing import isna
+
+from pandas import (
+    Categorical,
+    Index,
+    IntervalIndex,
+)
+import pandas.core.algorithms as algos
+from pandas.core.arrays.datetimelike import dtype_to_unit
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DtypeObj,
+        IntervalLeftRight,
+    )
+
+
+def cut(
+    x,
+    bins,
+    right: bool = True,
+    labels=None,
+    retbins: bool = False,
+    precision: int = 3,
+    include_lowest: bool = False,
+    duplicates: str = "raise",
+    ordered: bool = True,
+):
+    """
+    Bin values into discrete intervals.
+
+    Use `cut` when you need to segment and sort data values into bins. This
+    function is also useful for going from a continuous variable to a
+    categorical variable. For example, `cut` could convert ages to groups of
+    age ranges. Supports binning into an equal number of bins, or a
+    pre-specified array of bins.
+
+    Parameters
+    ----------
+    x : array-like
+        The input array to be binned. Must be 1-dimensional.
+    bins : int, sequence of scalars, or IntervalIndex
+        The criteria to bin by.
+
+        * int : Defines the number of equal-width bins in the range of `x`. The
+          range of `x` is extended by .1% on each side to include the minimum
+          and maximum values of `x`.
+        * sequence of scalars : Defines the bin edges allowing for non-uniform
+          width. No extension of the range of `x` is done.
+        * IntervalIndex : Defines the exact bins to be used. Note that
+          IntervalIndex for `bins` must be non-overlapping.
+
+    right : bool, default True
+        Indicates whether `bins` includes the rightmost edge or not. If
+        ``right == True`` (the default), then the `bins` ``[1, 2, 3, 4]``
+        indicate (1,2], (2,3], (3,4]. This argument is ignored when
+        `bins` is an IntervalIndex.
+    labels : array or False, default None
+        Specifies the labels for the returned bins. Must be the same length as
+        the resulting bins. If False, returns only integer indicators of the
+        bins. This affects the type of the output container (see below).
+        This argument is ignored when `bins` is an IntervalIndex. If True,
+        raises an error. When `ordered=False`, labels must be provided.
+    retbins : bool, default False
+        Whether to return the bins or not. Useful when bins is provided
+        as a scalar.
+    precision : int, default 3
+        The precision at which to store and display the bins labels.
+    include_lowest : bool, default False
+        Whether the first interval should be left-inclusive or not.
+    duplicates : {default 'raise', 'drop'}, optional
+        If bin edges are not unique, raise ValueError or drop non-uniques.
+    ordered : bool, default True
+        Whether the labels are ordered or not. Applies to returned types
+        Categorical and Series (with Categorical dtype). If True,
+        the resulting categorical will be ordered. If False, the resulting
+        categorical will be unordered (labels must be provided).
+
+    Returns
+    -------
+    out : Categorical, Series, or ndarray
+        An array-like object representing the respective bin for each value
+        of `x`. The type depends on the value of `labels`.
+
+        * None (default) : returns a Series for Series `x` or a
+          Categorical for all other inputs. The values stored within
+          are Interval dtype.
+
+        * sequence of scalars : returns a Series for Series `x` or a
+          Categorical for all other inputs. The values stored within
+          are whatever the type in the sequence is.
+
+        * False : returns an ndarray of integers.
+
+    bins : numpy.ndarray or IntervalIndex.
+        The computed or specified bins. Only returned when `retbins=True`.
+        For scalar or sequence `bins`, this is an ndarray with the computed
+        bins. If set `duplicates=drop`, `bins` will drop non-unique bin. For
+        an IntervalIndex `bins`, this is equal to `bins`.
+
+    See Also
+    --------
+    qcut : Discretize variable into equal-sized buckets based on rank
+        or based on sample quantiles.
+    Categorical : Array type for storing data that come from a
+        fixed set of values.
+    Series : One-dimensional array with axis labels (including time series).
+    IntervalIndex : Immutable Index implementing an ordered, sliceable set.
+
+    Notes
+    -----
+    Any NA values will be NA in the result. Out of bounds values will be NA in
+    the resulting Series or Categorical object.
+
+    Reference :ref:`the user guide ` for more examples.
+
+    Examples
+    --------
+    Discretize into three equal-sized bins.
+
+    >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3)
+    ... # doctest: +ELLIPSIS
+    [(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
+    Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...
+
+    >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3, retbins=True)
+    ... # doctest: +ELLIPSIS
+    ([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
+    Categories (3, interval[float64, right]): [(0.994, 3.0] < (3.0, 5.0] ...
+    array([0.994, 3.   , 5.   , 7.   ]))
+
+    Discovers the same bins, but assign them specific labels. Notice that
+    the returned Categorical's categories are `labels` and is ordered.
+
+    >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]),
+    ...        3, labels=["bad", "medium", "good"])
+    ['bad', 'good', 'medium', 'medium', 'good', 'bad']
+    Categories (3, object): ['bad' < 'medium' < 'good']
+
+    ``ordered=False`` will result in unordered categories when labels are passed.
+    This parameter can be used to allow non-unique labels:
+
+    >>> pd.cut(np.array([1, 7, 5, 4, 6, 3]), 3,
+    ...        labels=["B", "A", "B"], ordered=False)
+    ['B', 'B', 'A', 'A', 'B', 'B']
+    Categories (2, object): ['A', 'B']
+
+    ``labels=False`` implies you just want the bins back.
+
+    >>> pd.cut([0, 1, 1, 2], bins=4, labels=False)
+    array([0, 1, 1, 3])
+
+    Passing a Series as an input returns a Series with categorical dtype:
+
+    >>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
+    ...               index=['a', 'b', 'c', 'd', 'e'])
+    >>> pd.cut(s, 3)
+    ... # doctest: +ELLIPSIS
+    a    (1.992, 4.667]
+    b    (1.992, 4.667]
+    c    (4.667, 7.333]
+    d     (7.333, 10.0]
+    e     (7.333, 10.0]
+    dtype: category
+    Categories (3, interval[float64, right]): [(1.992, 4.667] < (4.667, ...
+
+    Passing a Series as an input returns a Series with mapping value.
+    It is used to map numerically to intervals based on bins.
+
+    >>> s = pd.Series(np.array([2, 4, 6, 8, 10]),
+    ...               index=['a', 'b', 'c', 'd', 'e'])
+    >>> pd.cut(s, [0, 2, 4, 6, 8, 10], labels=False, retbins=True, right=False)
+    ... # doctest: +ELLIPSIS
+    (a    1.0
+     b    2.0
+     c    3.0
+     d    4.0
+     e    NaN
+     dtype: float64,
+     array([ 0,  2,  4,  6,  8, 10]))
+
+    Use `drop` optional when bins is not unique
+
+    >>> pd.cut(s, [0, 2, 4, 6, 10, 10], labels=False, retbins=True,
+    ...        right=False, duplicates='drop')
+    ... # doctest: +ELLIPSIS
+    (a    1.0
+     b    2.0
+     c    3.0
+     d    3.0
+     e    NaN
+     dtype: float64,
+     array([ 0,  2,  4,  6, 10]))
+
+    Passing an IntervalIndex for `bins` results in those categories exactly.
+    Notice that values not covered by the IntervalIndex are set to NaN. 0
+    is to the left of the first bin (which is closed on the right), and 1.5
+    falls between two bins.
+
+    >>> bins = pd.IntervalIndex.from_tuples([(0, 1), (2, 3), (4, 5)])
+    >>> pd.cut([0, 0.5, 1.5, 2.5, 4.5], bins)
+    [NaN, (0.0, 1.0], NaN, (2.0, 3.0], (4.0, 5.0]]
+    Categories (3, interval[int64, right]): [(0, 1] < (2, 3] < (4, 5]]
+    """
+    # NOTE: this binning code is changed a bit from histogram for var(x) == 0
+
+    original = x
+    x_idx = _preprocess_for_cut(x)
+    x_idx, _ = _coerce_to_type(x_idx)
+
+    if not np.iterable(bins):
+        bins = _nbins_to_bins(x_idx, bins, right)
+
+    elif isinstance(bins, IntervalIndex):
+        if bins.is_overlapping:
+            raise ValueError("Overlapping IntervalIndex is not accepted.")
+
+    else:
+        bins = Index(bins)
+        if not bins.is_monotonic_increasing:
+            raise ValueError("bins must increase monotonically.")
+
+    fac, bins = _bins_to_cuts(
+        x_idx,
+        bins,
+        right=right,
+        labels=labels,
+        precision=precision,
+        include_lowest=include_lowest,
+        duplicates=duplicates,
+        ordered=ordered,
+    )
+
+    return _postprocess_for_cut(fac, bins, retbins, original)
+
+
+def qcut(
+    x,
+    q,
+    labels=None,
+    retbins: bool = False,
+    precision: int = 3,
+    duplicates: str = "raise",
+):
+    """
+    Quantile-based discretization function.
+
+    Discretize variable into equal-sized buckets based on rank or based
+    on sample quantiles. For example 1000 values for 10 quantiles would
+    produce a Categorical object indicating quantile membership for each data point.
+
+    Parameters
+    ----------
+    x : 1d ndarray or Series
+    q : int or list-like of float
+        Number of quantiles. 10 for deciles, 4 for quartiles, etc. Alternately
+        array of quantiles, e.g. [0, .25, .5, .75, 1.] for quartiles.
+    labels : array or False, default None
+        Used as labels for the resulting bins. Must be of the same length as
+        the resulting bins. If False, return only integer indicators of the
+        bins. If True, raises an error.
+    retbins : bool, optional
+        Whether to return the (bins, labels) or not. Can be useful if bins
+        is given as a scalar.
+    precision : int, optional
+        The precision at which to store and display the bins labels.
+    duplicates : {default 'raise', 'drop'}, optional
+        If bin edges are not unique, raise ValueError or drop non-uniques.
+
+    Returns
+    -------
+    out : Categorical or Series or array of integers if labels is False
+        The return type (Categorical or Series) depends on the input: a Series
+        of type category if input is a Series else Categorical. Bins are
+        represented as categories when categorical data is returned.
+    bins : ndarray of floats
+        Returned only if `retbins` is True.
+
+    Notes
+    -----
+    Out of bounds values will be NA in the resulting Categorical object
+
+    Examples
+    --------
+    >>> pd.qcut(range(5), 4)
+    ... # doctest: +ELLIPSIS
+    [(-0.001, 1.0], (-0.001, 1.0], (1.0, 2.0], (2.0, 3.0], (3.0, 4.0]]
+    Categories (4, interval[float64, right]): [(-0.001, 1.0] < (1.0, 2.0] ...
+
+    >>> pd.qcut(range(5), 3, labels=["good", "medium", "bad"])
+    ... # doctest: +SKIP
+    [good, good, medium, bad, bad]
+    Categories (3, object): [good < medium < bad]
+
+    >>> pd.qcut(range(5), 4, labels=False)
+    array([0, 0, 1, 2, 3])
+    """
+    original = x
+    x_idx = _preprocess_for_cut(x)
+    x_idx, _ = _coerce_to_type(x_idx)
+
+    quantiles = np.linspace(0, 1, q + 1) if is_integer(q) else q
+
+    bins = x_idx.to_series().dropna().quantile(quantiles)
+
+    fac, bins = _bins_to_cuts(
+        x_idx,
+        Index(bins),
+        labels=labels,
+        precision=precision,
+        include_lowest=True,
+        duplicates=duplicates,
+    )
+
+    return _postprocess_for_cut(fac, bins, retbins, original)
+
+
+def _nbins_to_bins(x_idx: Index, nbins: int, right: bool) -> Index:
+    """
+    If a user passed an integer N for bins, convert this to a sequence of N
+    equal(ish)-sized bins.
+    """
+    if is_scalar(nbins) and nbins < 1:
+        raise ValueError("`bins` should be a positive integer.")
+
+    if x_idx.size == 0:
+        raise ValueError("Cannot cut empty array")
+
+    rng = (x_idx.min(), x_idx.max())
+    mn, mx = rng
+
+    if is_numeric_dtype(x_idx.dtype) and (np.isinf(mn) or np.isinf(mx)):
+        # GH#24314
+        raise ValueError(
+            "cannot specify integer `bins` when input data contains infinity"
+        )
+
+    if mn == mx:  # adjust end points before binning
+        if _is_dt_or_td(x_idx.dtype):
+            # using seconds=1 is pretty arbitrary here
+            # error: Argument 1 to "dtype_to_unit" has incompatible type
+            # "dtype[Any] | ExtensionDtype"; expected "DatetimeTZDtype | dtype[Any]"
+            unit = dtype_to_unit(x_idx.dtype)  # type: ignore[arg-type]
+            td = Timedelta(seconds=1).as_unit(unit)
+            # Use DatetimeArray/TimedeltaArray method instead of linspace
+            # error: Item "ExtensionArray" of "ExtensionArray | ndarray[Any, Any]"
+            # has no attribute "_generate_range"
+            bins = x_idx._values._generate_range(  # type: ignore[union-attr]
+                start=mn - td, end=mx + td, periods=nbins + 1, freq=None, unit=unit
+            )
+        else:
+            mn -= 0.001 * abs(mn) if mn != 0 else 0.001
+            mx += 0.001 * abs(mx) if mx != 0 else 0.001
+
+            bins = np.linspace(mn, mx, nbins + 1, endpoint=True)
+    else:  # adjust end points after binning
+        if _is_dt_or_td(x_idx.dtype):
+            # Use DatetimeArray/TimedeltaArray method instead of linspace
+
+            # error: Argument 1 to "dtype_to_unit" has incompatible type
+            # "dtype[Any] | ExtensionDtype"; expected "DatetimeTZDtype | dtype[Any]"
+            unit = dtype_to_unit(x_idx.dtype)  # type: ignore[arg-type]
+            # error: Item "ExtensionArray" of "ExtensionArray | ndarray[Any, Any]"
+            # has no attribute "_generate_range"
+            bins = x_idx._values._generate_range(  # type: ignore[union-attr]
+                start=mn, end=mx, periods=nbins + 1, freq=None, unit=unit
+            )
+        else:
+            bins = np.linspace(mn, mx, nbins + 1, endpoint=True)
+        adj = (mx - mn) * 0.001  # 0.1% of the range
+        if right:
+            bins[0] -= adj
+        else:
+            bins[-1] += adj
+
+    return Index(bins)
+
+
+def _bins_to_cuts(
+    x_idx: Index,
+    bins: Index,
+    right: bool = True,
+    labels=None,
+    precision: int = 3,
+    include_lowest: bool = False,
+    duplicates: str = "raise",
+    ordered: bool = True,
+):
+    if not ordered and labels is None:
+        raise ValueError("'labels' must be provided if 'ordered = False'")
+
+    if duplicates not in ["raise", "drop"]:
+        raise ValueError(
+            "invalid value for 'duplicates' parameter, valid options are: raise, drop"
+        )
+
+    result: Categorical | np.ndarray
+
+    if isinstance(bins, IntervalIndex):
+        # we have a fast-path here
+        ids = bins.get_indexer(x_idx)
+        cat_dtype = CategoricalDtype(bins, ordered=True)
+        result = Categorical.from_codes(ids, dtype=cat_dtype, validate=False)
+        return result, bins
+
+    unique_bins = algos.unique(bins)
+    if len(unique_bins) < len(bins) and len(bins) != 2:
+        if duplicates == "raise":
+            raise ValueError(
+                f"Bin edges must be unique: {repr(bins)}.\n"
+                f"You can drop duplicate edges by setting the 'duplicates' kwarg"
+            )
+        bins = unique_bins
+
+    side: Literal["left", "right"] = "left" if right else "right"
+
+    try:
+        ids = bins.searchsorted(x_idx, side=side)
+    except TypeError as err:
+        # e.g. test_datetime_nan_error if bins are DatetimeArray and x_idx
+        #  is integers
+        if x_idx.dtype.kind == "m":
+            raise ValueError("bins must be of timedelta64 dtype") from err
+        elif x_idx.dtype.kind == bins.dtype.kind == "M":
+            raise ValueError(
+                "Cannot use timezone-naive bins with timezone-aware values, "
+                "or vice-versa"
+            ) from err
+        elif x_idx.dtype.kind == "M":
+            raise ValueError("bins must be of datetime64 dtype") from err
+        else:
+            raise
+    ids = ensure_platform_int(ids)
+
+    if include_lowest:
+        ids[x_idx == bins[0]] = 1
+
+    na_mask = isna(x_idx) | (ids == len(bins)) | (ids == 0)
+    has_nas = na_mask.any()
+
+    if labels is not False:
+        if not (labels is None or is_list_like(labels)):
+            raise ValueError(
+                "Bin labels must either be False, None or passed in as a "
+                "list-like argument"
+            )
+
+        if labels is None:
+            labels = _format_labels(
+                bins, precision, right=right, include_lowest=include_lowest
+            )
+        elif ordered and len(set(labels)) != len(labels):
+            raise ValueError(
+                "labels must be unique if ordered=True; pass ordered=False "
+                "for duplicate labels"
+            )
+        else:
+            if len(labels) != len(bins) - 1:
+                raise ValueError(
+                    "Bin labels must be one fewer than the number of bin edges"
+                )
+
+        if not isinstance(getattr(labels, "dtype", None), CategoricalDtype):
+            labels = Categorical(
+                labels,
+                categories=labels if len(set(labels)) == len(labels) else None,
+                ordered=ordered,
+            )
+        # TODO: handle mismatch between categorical label order and pandas.cut order.
+        np.putmask(ids, na_mask, 0)
+        result = algos.take_nd(labels, ids - 1)
+
+    else:
+        result = ids - 1
+        if has_nas:
+            result = result.astype(np.float64)
+            np.putmask(result, na_mask, np.nan)
+
+    return result, bins
+
+
+def _coerce_to_type(x: Index) -> tuple[Index, DtypeObj | None]:
+    """
+    if the passed data is of datetime/timedelta, bool or nullable int type,
+    this method converts it to numeric so that cut or qcut method can
+    handle it
+    """
+    dtype: DtypeObj | None = None
+
+    if _is_dt_or_td(x.dtype):
+        dtype = x.dtype
+    elif is_bool_dtype(x.dtype):
+        # GH 20303
+        x = x.astype(np.int64)
+    # To support cut and qcut for IntegerArray we convert to float dtype.
+    # Will properly support in the future.
+    # https://github.com/pandas-dev/pandas/pull/31290
+    # https://github.com/pandas-dev/pandas/issues/31389
+    elif isinstance(x.dtype, ExtensionDtype) and is_numeric_dtype(x.dtype):
+        x_arr = x.to_numpy(dtype=np.float64, na_value=np.nan)
+        x = Index(x_arr)
+
+    return Index(x), dtype
+
+
+def _is_dt_or_td(dtype: DtypeObj) -> bool:
+    # Note: the dtype here comes from an Index.dtype, so we know that that any
+    #  dt64/td64 dtype is of a supported unit.
+    return isinstance(dtype, DatetimeTZDtype) or lib.is_np_dtype(dtype, "mM")
+
+
+def _format_labels(
+    bins: Index,
+    precision: int,
+    right: bool = True,
+    include_lowest: bool = False,
+):
+    """based on the dtype, return our labels"""
+    closed: IntervalLeftRight = "right" if right else "left"
+
+    formatter: Callable[[Any], Timestamp] | Callable[[Any], Timedelta]
+
+    if _is_dt_or_td(bins.dtype):
+        # error: Argument 1 to "dtype_to_unit" has incompatible type
+        # "dtype[Any] | ExtensionDtype"; expected "DatetimeTZDtype | dtype[Any]"
+        unit = dtype_to_unit(bins.dtype)  # type: ignore[arg-type]
+        formatter = lambda x: x
+        adjust = lambda x: x - Timedelta(1, unit=unit).as_unit(unit)
+    else:
+        precision = _infer_precision(precision, bins)
+        formatter = lambda x: _round_frac(x, precision)
+        adjust = lambda x: x - 10 ** (-precision)
+
+    breaks = [formatter(b) for b in bins]
+    if right and include_lowest:
+        # adjust lhs of first interval by precision to account for being right closed
+        breaks[0] = adjust(breaks[0])
+
+    if _is_dt_or_td(bins.dtype):
+        # error: "Index" has no attribute "as_unit"
+        breaks = type(bins)(breaks).as_unit(unit)  # type: ignore[attr-defined]
+
+    return IntervalIndex.from_breaks(breaks, closed=closed)
+
+
+def _preprocess_for_cut(x) -> Index:
+    """
+    handles preprocessing for cut where we convert passed
+    input to array, strip the index information and store it
+    separately
+    """
+    # Check that the passed array is a Pandas or Numpy object
+    # We don't want to strip away a Pandas data-type here (e.g. datetimetz)
+    ndim = getattr(x, "ndim", None)
+    if ndim is None:
+        x = np.asarray(x)
+    if x.ndim != 1:
+        raise ValueError("Input array must be 1 dimensional")
+
+    return Index(x)
+
+
+def _postprocess_for_cut(fac, bins, retbins: bool, original):
+    """
+    handles post processing for the cut method where
+    we combine the index information if the originally passed
+    datatype was a series
+    """
+    if isinstance(original, ABCSeries):
+        fac = original._constructor(fac, index=original.index, name=original.name)
+
+    if not retbins:
+        return fac
+
+    if isinstance(bins, Index) and is_numeric_dtype(bins.dtype):
+        bins = bins._values
+
+    return fac, bins
+
+
+def _round_frac(x, precision: int):
+    """
+    Round the fractional part of the given number
+    """
+    if not np.isfinite(x) or x == 0:
+        return x
+    else:
+        frac, whole = np.modf(x)
+        if whole == 0:
+            digits = -int(np.floor(np.log10(abs(frac)))) - 1 + precision
+        else:
+            digits = precision
+        return np.around(x, digits)
+
+
+def _infer_precision(base_precision: int, bins: Index) -> int:
+    """
+    Infer an appropriate precision for _round_frac
+    """
+    for precision in range(base_precision, 20):
+        levels = np.asarray([_round_frac(b, precision) for b in bins])
+        if algos.unique(levels).size == bins.size:
+            return precision
+    return base_precision  # default
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/reshape/util.py b/.venv/lib/python3.13/site-packages/pandas/core/reshape/util.py
new file mode 100644
index 0000000000000000000000000000000000000000..476e3922b6989e4267aeeafd5943a80c1599b1d5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/reshape/util.py
@@ -0,0 +1,85 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.core.dtypes.common import is_list_like
+
+if TYPE_CHECKING:
+    from pandas._typing import NumpyIndexT
+
+
+def cartesian_product(X) -> list[np.ndarray]:
+    """
+    Numpy version of itertools.product.
+    Sometimes faster (for large inputs)...
+
+    Parameters
+    ----------
+    X : list-like of list-likes
+
+    Returns
+    -------
+    product : list of ndarrays
+
+    Examples
+    --------
+    >>> cartesian_product([list('ABC'), [1, 2]])
+    [array(['A', 'A', 'B', 'B', 'C', 'C'], dtype=' NumpyIndexT:
+    """
+    Index compat for np.tile.
+
+    Notes
+    -----
+    Does not support multi-dimensional `num`.
+    """
+    if isinstance(arr, np.ndarray):
+        return np.tile(arr, num)
+
+    # Otherwise we have an Index
+    taker = np.tile(np.arange(len(arr)), num)
+    return arr.take(taker)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/roperator.py b/.venv/lib/python3.13/site-packages/pandas/core/roperator.py
new file mode 100644
index 0000000000000000000000000000000000000000..2f320f4e9c6b984b64e0fc1268e50a8ad1a7e1fe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/roperator.py
@@ -0,0 +1,62 @@
+"""
+Reversed Operations not available in the stdlib operator module.
+Defining these instead of using lambdas allows us to reference them by name.
+"""
+from __future__ import annotations
+
+import operator
+
+
+def radd(left, right):
+    return right + left
+
+
+def rsub(left, right):
+    return right - left
+
+
+def rmul(left, right):
+    return right * left
+
+
+def rdiv(left, right):
+    return right / left
+
+
+def rtruediv(left, right):
+    return right / left
+
+
+def rfloordiv(left, right):
+    return right // left
+
+
+def rmod(left, right):
+    # check if right is a string as % is the string
+    # formatting operation; this is a TypeError
+    # otherwise perform the op
+    if isinstance(right, str):
+        typ = type(left).__name__
+        raise TypeError(f"{typ} cannot perform the operation mod")
+
+    return right % left
+
+
+def rdivmod(left, right):
+    return divmod(right, left)
+
+
+def rpow(left, right):
+    return right**left
+
+
+def rand_(left, right):
+    return operator.and_(right, left)
+
+
+def ror_(left, right):
+    return operator.or_(right, left)
+
+
+def rxor(left, right):
+    return operator.xor(right, left)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/sample.py b/.venv/lib/python3.13/site-packages/pandas/core/sample.py
new file mode 100644
index 0000000000000000000000000000000000000000..eebbed3512c4eca42e401c40605838c6f69011df
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/sample.py
@@ -0,0 +1,154 @@
+"""
+Module containing utilities for NDFrame.sample() and .GroupBy.sample()
+"""
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs import lib
+
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import AxisInt
+
+    from pandas.core.generic import NDFrame
+
+
+def preprocess_weights(obj: NDFrame, weights, axis: AxisInt) -> np.ndarray:
+    """
+    Process and validate the `weights` argument to `NDFrame.sample` and
+    `.GroupBy.sample`.
+
+    Returns `weights` as an ndarray[np.float64], validated except for normalizing
+    weights (because that must be done groupwise in groupby sampling).
+    """
+    # If a series, align with frame
+    if isinstance(weights, ABCSeries):
+        weights = weights.reindex(obj.axes[axis])
+
+    # Strings acceptable if a dataframe and axis = 0
+    if isinstance(weights, str):
+        if isinstance(obj, ABCDataFrame):
+            if axis == 0:
+                try:
+                    weights = obj[weights]
+                except KeyError as err:
+                    raise KeyError(
+                        "String passed to weights not a valid column"
+                    ) from err
+            else:
+                raise ValueError(
+                    "Strings can only be passed to "
+                    "weights when sampling from rows on "
+                    "a DataFrame"
+                )
+        else:
+            raise ValueError(
+                "Strings cannot be passed as weights when sampling from a Series."
+            )
+
+    if isinstance(obj, ABCSeries):
+        func = obj._constructor
+    else:
+        func = obj._constructor_sliced
+
+    weights = func(weights, dtype="float64")._values
+
+    if len(weights) != obj.shape[axis]:
+        raise ValueError("Weights and axis to be sampled must be of same length")
+
+    if lib.has_infs(weights):
+        raise ValueError("weight vector may not include `inf` values")
+
+    if (weights < 0).any():
+        raise ValueError("weight vector many not include negative values")
+
+    missing = np.isnan(weights)
+    if missing.any():
+        # Don't modify weights in place
+        weights = weights.copy()
+        weights[missing] = 0
+    return weights
+
+
+def process_sampling_size(
+    n: int | None, frac: float | None, replace: bool
+) -> int | None:
+    """
+    Process and validate the `n` and `frac` arguments to `NDFrame.sample` and
+    `.GroupBy.sample`.
+
+    Returns None if `frac` should be used (variable sampling sizes), otherwise returns
+    the constant sampling size.
+    """
+    # If no frac or n, default to n=1.
+    if n is None and frac is None:
+        n = 1
+    elif n is not None and frac is not None:
+        raise ValueError("Please enter a value for `frac` OR `n`, not both")
+    elif n is not None:
+        if n < 0:
+            raise ValueError(
+                "A negative number of rows requested. Please provide `n` >= 0."
+            )
+        if n % 1 != 0:
+            raise ValueError("Only integers accepted as `n` values")
+    else:
+        assert frac is not None  # for mypy
+        if frac > 1 and not replace:
+            raise ValueError(
+                "Replace has to be set to `True` when "
+                "upsampling the population `frac` > 1."
+            )
+        if frac < 0:
+            raise ValueError(
+                "A negative number of rows requested. Please provide `frac` >= 0."
+            )
+
+    return n
+
+
+def sample(
+    obj_len: int,
+    size: int,
+    replace: bool,
+    weights: np.ndarray | None,
+    random_state: np.random.RandomState | np.random.Generator,
+) -> np.ndarray:
+    """
+    Randomly sample `size` indices in `np.arange(obj_len)`
+
+    Parameters
+    ----------
+    obj_len : int
+        The length of the indices being considered
+    size : int
+        The number of values to choose
+    replace : bool
+        Allow or disallow sampling of the same row more than once.
+    weights : np.ndarray[np.float64] or None
+        If None, equal probability weighting, otherwise weights according
+        to the vector normalized
+    random_state: np.random.RandomState or np.random.Generator
+        State used for the random sampling
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+    """
+    if weights is not None:
+        weight_sum = weights.sum()
+        if weight_sum != 0:
+            weights = weights / weight_sum
+        else:
+            raise ValueError("Invalid weights: weights sum to zero")
+
+    return random_state.choice(obj_len, size=size, replace=replace, p=weights).astype(
+        np.intp, copy=False
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/series.py b/.venv/lib/python3.13/site-packages/pandas/core/series.py
new file mode 100644
index 0000000000000000000000000000000000000000..ef0b41f3ae552221a9e3b186945f1f0fbee85b61
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/series.py
@@ -0,0 +1,6652 @@
+"""
+Data structure for 1-dimensional cross-sectional and time series data
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Mapping,
+    Sequence,
+)
+import operator
+import sys
+from textwrap import dedent
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+import weakref
+
+import numpy as np
+
+from pandas._config import (
+    using_copy_on_write,
+    warn_copy_on_write,
+)
+from pandas._config.config import _get_option
+
+from pandas._libs import (
+    lib,
+    properties,
+    reshape,
+)
+from pandas._libs.lib import is_range_indexer
+from pandas.compat import PYPY
+from pandas.compat._constants import (
+    REF_COUNT,
+    WARNING_CHECK_DISABLED,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.compat.numpy import function as nv
+from pandas.errors import (
+    ChainedAssignmentError,
+    InvalidIndexError,
+    _chained_assignment_method_msg,
+    _chained_assignment_msg,
+    _chained_assignment_warning_method_msg,
+    _chained_assignment_warning_msg,
+    _check_cacher,
+)
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+    deprecate_nonkeyword_arguments,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import (
+    validate_ascending,
+    validate_bool_kwarg,
+    validate_percentile,
+)
+
+from pandas.core.dtypes.astype import astype_is_view
+from pandas.core.dtypes.cast import (
+    LossySetitemError,
+    construct_1d_arraylike_from_scalar,
+    find_common_type,
+    infer_dtype_from,
+    maybe_box_native,
+    maybe_cast_pointwise_result,
+)
+from pandas.core.dtypes.common import (
+    is_dict_like,
+    is_integer,
+    is_iterator,
+    is_list_like,
+    is_object_dtype,
+    is_scalar,
+    pandas_dtype,
+    validate_all_hashable,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    ExtensionDtype,
+    SparseDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.inference import is_hashable
+from pandas.core.dtypes.missing import (
+    isna,
+    na_value_for_dtype,
+    notna,
+    remove_na_arraylike,
+)
+
+from pandas.core import (
+    algorithms,
+    base,
+    common as com,
+    missing,
+    nanops,
+    ops,
+    roperator,
+)
+from pandas.core.accessor import CachedAccessor
+from pandas.core.apply import SeriesApply
+from pandas.core.arrays import ExtensionArray
+from pandas.core.arrays.arrow import (
+    ListAccessor,
+    StructAccessor,
+)
+from pandas.core.arrays.categorical import CategoricalAccessor
+from pandas.core.arrays.sparse import SparseAccessor
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.construction import (
+    array as pd_array,
+    extract_array,
+    sanitize_array,
+)
+from pandas.core.generic import (
+    NDFrame,
+    make_doc,
+)
+from pandas.core.indexers import (
+    disallow_ndim_indexing,
+    unpack_1tuple,
+)
+from pandas.core.indexes.accessors import CombinedDatetimelikeProperties
+from pandas.core.indexes.api import (
+    DatetimeIndex,
+    Index,
+    MultiIndex,
+    PeriodIndex,
+    default_index,
+    ensure_index,
+)
+import pandas.core.indexes.base as ibase
+from pandas.core.indexes.multi import maybe_droplevels
+from pandas.core.indexing import (
+    check_bool_indexer,
+    check_dict_or_set_indexers,
+)
+from pandas.core.internals import (
+    SingleArrayManager,
+    SingleBlockManager,
+)
+from pandas.core.methods import selectn
+from pandas.core.shared_docs import _shared_docs
+from pandas.core.sorting import (
+    ensure_key_mapped,
+    nargsort,
+)
+from pandas.core.strings.accessor import StringMethods
+from pandas.core.tools.datetimes import to_datetime
+
+import pandas.io.formats.format as fmt
+from pandas.io.formats.info import (
+    INFO_DOCSTRING,
+    SeriesInfo,
+    series_sub_kwargs,
+)
+import pandas.plotting
+
+if TYPE_CHECKING:
+    from pandas._libs.internals import BlockValuesRefs
+    from pandas._typing import (
+        AggFuncType,
+        AnyAll,
+        AnyArrayLike,
+        ArrayLike,
+        Axis,
+        AxisInt,
+        CorrelationMethod,
+        DropKeep,
+        Dtype,
+        DtypeObj,
+        FilePath,
+        Frequency,
+        IgnoreRaise,
+        IndexKeyFunc,
+        IndexLabel,
+        Level,
+        MutableMappingT,
+        NaPosition,
+        NumpySorter,
+        NumpyValueArrayLike,
+        QuantileInterpolation,
+        ReindexMethod,
+        Renamer,
+        Scalar,
+        Self,
+        SingleManager,
+        SortKind,
+        StorageOptions,
+        Suffixes,
+        ValueKeyFunc,
+        WriteBuffer,
+        npt,
+    )
+
+    from pandas.core.frame import DataFrame
+    from pandas.core.groupby.generic import SeriesGroupBy
+
+__all__ = ["Series"]
+
+_shared_doc_kwargs = {
+    "axes": "index",
+    "klass": "Series",
+    "axes_single_arg": "{0 or 'index'}",
+    "axis": """axis : {0 or 'index'}
+        Unused. Parameter needed for compatibility with DataFrame.""",
+    "inplace": """inplace : bool, default False
+        If True, performs operation inplace and returns None.""",
+    "unique": "np.ndarray",
+    "duplicated": "Series",
+    "optional_by": "",
+    "optional_reindex": """
+index : array-like, optional
+    New labels for the index. Preferably an Index object to avoid
+    duplicating data.
+axis : int or str, optional
+    Unused.""",
+}
+
+
+def _coerce_method(converter):
+    """
+    Install the scalar coercion methods.
+    """
+
+    def wrapper(self):
+        if len(self) == 1:
+            warnings.warn(
+                f"Calling {converter.__name__} on a single element Series is "
+                "deprecated and will raise a TypeError in the future. "
+                f"Use {converter.__name__}(ser.iloc[0]) instead",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            return converter(self.iloc[0])
+        raise TypeError(f"cannot convert the series to {converter}")
+
+    wrapper.__name__ = f"__{converter.__name__}__"
+    return wrapper
+
+
+# ----------------------------------------------------------------------
+# Series class
+
+
+# error: Cannot override final attribute "ndim" (previously declared in base
+# class "NDFrame")
+# error: Cannot override final attribute "size" (previously declared in base
+# class "NDFrame")
+# definition in base class "NDFrame"
+class Series(base.IndexOpsMixin, NDFrame):  # type: ignore[misc]
+    """
+    One-dimensional ndarray with axis labels (including time series).
+
+    Labels need not be unique but must be a hashable type. The object
+    supports both integer- and label-based indexing and provides a host of
+    methods for performing operations involving the index. Statistical
+    methods from ndarray have been overridden to automatically exclude
+    missing data (currently represented as NaN).
+
+    Operations between Series (+, -, /, \\*, \\*\\*) align values based on their
+    associated index values-- they need not be the same length. The result
+    index will be the sorted union of the two indexes.
+
+    Parameters
+    ----------
+    data : array-like, Iterable, dict, or scalar value
+        Contains data stored in Series. If data is a dict, argument order is
+        maintained.
+    index : array-like or Index (1d)
+        Values must be hashable and have the same length as `data`.
+        Non-unique index values are allowed. Will default to
+        RangeIndex (0, 1, 2, ..., n) if not provided. If data is dict-like
+        and index is None, then the keys in the data are used as the index. If the
+        index is not None, the resulting Series is reindexed with the index values.
+    dtype : str, numpy.dtype, or ExtensionDtype, optional
+        Data type for the output Series. If not specified, this will be
+        inferred from `data`.
+        See the :ref:`user guide ` for more usages.
+    name : Hashable, default None
+        The name to give to the Series.
+    copy : bool, default False
+        Copy input data. Only affects Series or 1d ndarray input. See examples.
+
+    Notes
+    -----
+    Please reference the :ref:`User Guide ` for more information.
+
+    Examples
+    --------
+    Constructing Series from a dictionary with an Index specified
+
+    >>> d = {'a': 1, 'b': 2, 'c': 3}
+    >>> ser = pd.Series(data=d, index=['a', 'b', 'c'])
+    >>> ser
+    a   1
+    b   2
+    c   3
+    dtype: int64
+
+    The keys of the dictionary match with the Index values, hence the Index
+    values have no effect.
+
+    >>> d = {'a': 1, 'b': 2, 'c': 3}
+    >>> ser = pd.Series(data=d, index=['x', 'y', 'z'])
+    >>> ser
+    x   NaN
+    y   NaN
+    z   NaN
+    dtype: float64
+
+    Note that the Index is first build with the keys from the dictionary.
+    After this the Series is reindexed with the given Index values, hence we
+    get all NaN as a result.
+
+    Constructing Series from a list with `copy=False`.
+
+    >>> r = [1, 2]
+    >>> ser = pd.Series(r, copy=False)
+    >>> ser.iloc[0] = 999
+    >>> r
+    [1, 2]
+    >>> ser
+    0    999
+    1      2
+    dtype: int64
+
+    Due to input data type the Series has a `copy` of
+    the original data even though `copy=False`, so
+    the data is unchanged.
+
+    Constructing Series from a 1d ndarray with `copy=False`.
+
+    >>> r = np.array([1, 2])
+    >>> ser = pd.Series(r, copy=False)
+    >>> ser.iloc[0] = 999
+    >>> r
+    array([999,   2])
+    >>> ser
+    0    999
+    1      2
+    dtype: int64
+
+    Due to input data type the Series has a `view` on
+    the original data, so
+    the data is changed as well.
+    """
+
+    _typ = "series"
+    _HANDLED_TYPES = (Index, ExtensionArray, np.ndarray)
+
+    _name: Hashable
+    _metadata: list[str] = ["_name"]
+    _internal_names_set = {"index", "name"} | NDFrame._internal_names_set
+    _accessors = {"dt", "cat", "str", "sparse"}
+    _hidden_attrs = (
+        base.IndexOpsMixin._hidden_attrs | NDFrame._hidden_attrs | frozenset([])
+    )
+
+    # similar to __array_priority__, positions Series after DataFrame
+    #  but before Index and ExtensionArray.  Should NOT be overridden by subclasses.
+    __pandas_priority__ = 3000
+
+    # Override cache_readonly bc Series is mutable
+    # error: Incompatible types in assignment (expression has type "property",
+    # base class "IndexOpsMixin" defined the type as "Callable[[IndexOpsMixin], bool]")
+    hasnans = property(  # type: ignore[assignment]
+        # error: "Callable[[IndexOpsMixin], bool]" has no attribute "fget"
+        base.IndexOpsMixin.hasnans.fget,  # type: ignore[attr-defined]
+        doc=base.IndexOpsMixin.hasnans.__doc__,
+    )
+    _mgr: SingleManager
+
+    # ----------------------------------------------------------------------
+    # Constructors
+
+    def __init__(
+        self,
+        data=None,
+        index=None,
+        dtype: Dtype | None = None,
+        name=None,
+        copy: bool | None = None,
+        fastpath: bool | lib.NoDefault = lib.no_default,
+    ) -> None:
+        if fastpath is not lib.no_default:
+            warnings.warn(
+                "The 'fastpath' keyword in pd.Series is deprecated and will "
+                "be removed in a future version.",
+                DeprecationWarning,
+                stacklevel=find_stack_level(),
+            )
+        else:
+            fastpath = False
+
+        allow_mgr = False
+        if (
+            isinstance(data, (SingleBlockManager, SingleArrayManager))
+            and index is None
+            and dtype is None
+            and (copy is False or copy is None)
+        ):
+            if not allow_mgr:
+                # GH#52419
+                warnings.warn(
+                    f"Passing a {type(data).__name__} to {type(self).__name__} "
+                    "is deprecated and will raise in a future version. "
+                    "Use public APIs instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+            if using_copy_on_write():
+                data = data.copy(deep=False)
+            # GH#33357 called with just the SingleBlockManager
+            NDFrame.__init__(self, data)
+            if fastpath:
+                # e.g. from _box_col_values, skip validation of name
+                object.__setattr__(self, "_name", name)
+            else:
+                self.name = name
+            return
+
+        is_pandas_object = isinstance(data, (Series, Index, ExtensionArray))
+        data_dtype = getattr(data, "dtype", None)
+        original_dtype = dtype
+
+        if isinstance(data, (ExtensionArray, np.ndarray)):
+            if copy is not False and using_copy_on_write():
+                if dtype is None or astype_is_view(data.dtype, pandas_dtype(dtype)):
+                    data = data.copy()
+        if copy is None:
+            copy = False
+
+        # we are called internally, so short-circuit
+        if fastpath:
+            # data is a ndarray, index is defined
+            if not isinstance(data, (SingleBlockManager, SingleArrayManager)):
+                manager = _get_option("mode.data_manager", silent=True)
+                if manager == "block":
+                    data = SingleBlockManager.from_array(data, index)
+                elif manager == "array":
+                    data = SingleArrayManager.from_array(data, index)
+                allow_mgr = True
+            elif using_copy_on_write() and not copy:
+                data = data.copy(deep=False)
+
+            if not allow_mgr:
+                warnings.warn(
+                    f"Passing a {type(data).__name__} to {type(self).__name__} "
+                    "is deprecated and will raise in a future version. "
+                    "Use public APIs instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+            if copy:
+                data = data.copy()
+            # skips validation of the name
+            object.__setattr__(self, "_name", name)
+            NDFrame.__init__(self, data)
+            return
+
+        if isinstance(data, SingleBlockManager) and using_copy_on_write() and not copy:
+            data = data.copy(deep=False)
+
+            if not allow_mgr:
+                warnings.warn(
+                    f"Passing a {type(data).__name__} to {type(self).__name__} "
+                    "is deprecated and will raise in a future version. "
+                    "Use public APIs instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+
+        name = ibase.maybe_extract_name(name, data, type(self))
+
+        if index is not None:
+            index = ensure_index(index)
+
+        if dtype is not None:
+            dtype = self._validate_dtype(dtype)
+
+        if data is None:
+            index = index if index is not None else default_index(0)
+            if len(index) or dtype is not None:
+                data = na_value_for_dtype(pandas_dtype(dtype), compat=False)
+            else:
+                data = []
+
+        if isinstance(data, MultiIndex):
+            raise NotImplementedError(
+                "initializing a Series from a MultiIndex is not supported"
+            )
+
+        refs = None
+        if isinstance(data, Index):
+            if dtype is not None:
+                data = data.astype(dtype, copy=False)
+
+            if using_copy_on_write():
+                refs = data._references
+                data = data._values
+            else:
+                # GH#24096 we need to ensure the index remains immutable
+                data = data._values.copy()
+            copy = False
+
+        elif isinstance(data, np.ndarray):
+            if len(data.dtype):
+                # GH#13296 we are dealing with a compound dtype, which
+                #  should be treated as 2D
+                raise ValueError(
+                    "Cannot construct a Series from an ndarray with "
+                    "compound dtype.  Use DataFrame instead."
+                )
+        elif isinstance(data, Series):
+            if index is None:
+                index = data.index
+                data = data._mgr.copy(deep=False)
+            else:
+                data = data.reindex(index, copy=copy)
+                copy = False
+                data = data._mgr
+        elif isinstance(data, Mapping):
+            data, index = self._init_dict(data, index, dtype)
+            dtype = None
+            copy = False
+        elif isinstance(data, (SingleBlockManager, SingleArrayManager)):
+            if index is None:
+                index = data.index
+            elif not data.index.equals(index) or copy:
+                # GH#19275 SingleBlockManager input should only be called
+                # internally
+                raise AssertionError(
+                    "Cannot pass both SingleBlockManager "
+                    "`data` argument and a different "
+                    "`index` argument. `copy` must be False."
+                )
+
+            if not allow_mgr:
+                warnings.warn(
+                    f"Passing a {type(data).__name__} to {type(self).__name__} "
+                    "is deprecated and will raise in a future version. "
+                    "Use public APIs instead.",
+                    DeprecationWarning,
+                    stacklevel=2,
+                )
+                allow_mgr = True
+
+        elif isinstance(data, ExtensionArray):
+            pass
+        else:
+            data = com.maybe_iterable_to_list(data)
+            if is_list_like(data) and not len(data) and dtype is None:
+                # GH 29405: Pre-2.0, this defaulted to float.
+                dtype = np.dtype(object)
+
+        if index is None:
+            if not is_list_like(data):
+                data = [data]
+            index = default_index(len(data))
+        elif is_list_like(data):
+            com.require_length_match(data, index)
+
+        # create/copy the manager
+        if isinstance(data, (SingleBlockManager, SingleArrayManager)):
+            if dtype is not None:
+                data = data.astype(dtype=dtype, errors="ignore", copy=copy)
+            elif copy:
+                data = data.copy()
+        else:
+            data = sanitize_array(data, index, dtype, copy)
+
+            manager = _get_option("mode.data_manager", silent=True)
+            if manager == "block":
+                data = SingleBlockManager.from_array(data, index, refs=refs)
+            elif manager == "array":
+                data = SingleArrayManager.from_array(data, index)
+
+        NDFrame.__init__(self, data)
+        self.name = name
+        self._set_axis(0, index)
+
+        if original_dtype is None and is_pandas_object and data_dtype == np.object_:
+            if self.dtype != data_dtype:
+                warnings.warn(
+                    "Dtype inference on a pandas object "
+                    "(Series, Index, ExtensionArray) is deprecated. The Series "
+                    "constructor will keep the original dtype in the future. "
+                    "Call `infer_objects` on the result to get the old behavior.",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+    def _init_dict(
+        self, data: Mapping, index: Index | None = None, dtype: DtypeObj | None = None
+    ):
+        """
+        Derive the "_mgr" and "index" attributes of a new Series from a
+        dictionary input.
+
+        Parameters
+        ----------
+        data : dict or dict-like
+            Data used to populate the new Series.
+        index : Index or None, default None
+            Index for the new Series: if None, use dict keys.
+        dtype : np.dtype, ExtensionDtype, or None, default None
+            The dtype for the new Series: if None, infer from data.
+
+        Returns
+        -------
+        _data : BlockManager for the new Series
+        index : index for the new Series
+        """
+        keys: Index | tuple
+
+        # Looking for NaN in dict doesn't work ({np.nan : 1}[float('nan')]
+        # raises KeyError), so we iterate the entire dict, and align
+        if data:
+            # GH:34717, issue was using zip to extract key and values from data.
+            # using generators in effects the performance.
+            # Below is the new way of extracting the keys and values
+
+            keys = tuple(data.keys())
+            values = list(data.values())  # Generating list of values- faster way
+        elif index is not None:
+            # fastpath for Series(data=None). Just use broadcasting a scalar
+            # instead of reindexing.
+            if len(index) or dtype is not None:
+                values = na_value_for_dtype(pandas_dtype(dtype), compat=False)
+            else:
+                values = []
+            keys = index
+        else:
+            keys, values = default_index(0), []
+
+        # Input is now list-like, so rely on "standard" construction:
+        s = Series(values, index=keys, dtype=dtype)
+
+        # Now we just make sure the order is respected, if any
+        if data and index is not None:
+            s = s.reindex(index, copy=False)
+        return s._mgr, s.index
+
+    # ----------------------------------------------------------------------
+
+    @property
+    def _constructor(self) -> Callable[..., Series]:
+        return Series
+
+    def _constructor_from_mgr(self, mgr, axes):
+        ser = Series._from_mgr(mgr, axes=axes)
+        ser._name = None  # caller is responsible for setting real name
+
+        if type(self) is Series:
+            # This would also work `if self._constructor is Series`, but
+            #  this check is slightly faster, benefiting the most-common case.
+            return ser
+
+        # We assume that the subclass __init__ knows how to handle a
+        #  pd.Series object.
+        return self._constructor(ser)
+
+    @property
+    def _constructor_expanddim(self) -> Callable[..., DataFrame]:
+        """
+        Used when a manipulation result has one higher dimension as the
+        original, such as Series.to_frame()
+        """
+        from pandas.core.frame import DataFrame
+
+        return DataFrame
+
+    def _constructor_expanddim_from_mgr(self, mgr, axes):
+        from pandas.core.frame import DataFrame
+
+        df = DataFrame._from_mgr(mgr, axes=mgr.axes)
+
+        if type(self) is Series:
+            # This would also work `if self._constructor_expanddim is DataFrame`,
+            #  but this check is slightly faster, benefiting the most-common case.
+            return df
+
+        # We assume that the subclass __init__ knows how to handle a
+        #  pd.DataFrame object.
+        return self._constructor_expanddim(df)
+
+    # types
+    @property
+    def _can_hold_na(self) -> bool:
+        return self._mgr._can_hold_na
+
+    # ndarray compatibility
+    @property
+    def dtype(self) -> DtypeObj:
+        """
+        Return the dtype object of the underlying data.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.dtype
+        dtype('int64')
+        """
+        return self._mgr.dtype
+
+    @property
+    def dtypes(self) -> DtypeObj:
+        """
+        Return the dtype object of the underlying data.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.dtypes
+        dtype('int64')
+        """
+        # DataFrame compatibility
+        return self.dtype
+
+    @property
+    def name(self) -> Hashable:
+        """
+        Return the name of the Series.
+
+        The name of a Series becomes its index or column name if it is used
+        to form a DataFrame. It is also used whenever displaying the Series
+        using the interpreter.
+
+        Returns
+        -------
+        label (hashable object)
+            The name of the Series, also the column name if part of a DataFrame.
+
+        See Also
+        --------
+        Series.rename : Sets the Series name when given a scalar input.
+        Index.name : Corresponding Index property.
+
+        Examples
+        --------
+        The Series name can be set initially when calling the constructor.
+
+        >>> s = pd.Series([1, 2, 3], dtype=np.int64, name='Numbers')
+        >>> s
+        0    1
+        1    2
+        2    3
+        Name: Numbers, dtype: int64
+        >>> s.name = "Integers"
+        >>> s
+        0    1
+        1    2
+        2    3
+        Name: Integers, dtype: int64
+
+        The name of a Series within a DataFrame is its column name.
+
+        >>> df = pd.DataFrame([[1, 2], [3, 4], [5, 6]],
+        ...                   columns=["Odd Numbers", "Even Numbers"])
+        >>> df
+           Odd Numbers  Even Numbers
+        0            1             2
+        1            3             4
+        2            5             6
+        >>> df["Even Numbers"].name
+        'Even Numbers'
+        """
+        return self._name
+
+    @name.setter
+    def name(self, value: Hashable) -> None:
+        validate_all_hashable(value, error_name=f"{type(self).__name__}.name")
+        object.__setattr__(self, "_name", value)
+
+    @property
+    def values(self):
+        """
+        Return Series as ndarray or ndarray-like depending on the dtype.
+
+        .. warning::
+
+           We recommend using :attr:`Series.array` or
+           :meth:`Series.to_numpy`, depending on whether you need
+           a reference to the underlying data or a NumPy array.
+
+        Returns
+        -------
+        numpy.ndarray or ndarray-like
+
+        See Also
+        --------
+        Series.array : Reference to the underlying data.
+        Series.to_numpy : A NumPy array representing the underlying data.
+
+        Examples
+        --------
+        >>> pd.Series([1, 2, 3]).values
+        array([1, 2, 3])
+
+        >>> pd.Series(list('aabc')).values
+        array(['a', 'a', 'b', 'c'], dtype=object)
+
+        >>> pd.Series(list('aabc')).astype('category').values
+        ['a', 'a', 'b', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+
+        Timezone aware datetime data is converted to UTC:
+
+        >>> pd.Series(pd.date_range('20130101', periods=3,
+        ...                         tz='US/Eastern')).values
+        array(['2013-01-01T05:00:00.000000000',
+               '2013-01-02T05:00:00.000000000',
+               '2013-01-03T05:00:00.000000000'], dtype='datetime64[ns]')
+        """
+        return self._mgr.external_values()
+
+    @property
+    def _values(self):
+        """
+        Return the internal repr of this data (defined by Block.interval_values).
+        This are the values as stored in the Block (ndarray or ExtensionArray
+        depending on the Block class), with datetime64[ns] and timedelta64[ns]
+        wrapped in ExtensionArrays to match Index._values behavior.
+
+        Differs from the public ``.values`` for certain data types, because of
+        historical backwards compatibility of the public attribute (e.g. period
+        returns object ndarray and datetimetz a datetime64[ns] ndarray for
+        ``.values`` while it returns an ExtensionArray for ``._values`` in those
+        cases).
+
+        Differs from ``.array`` in that this still returns the numpy array if
+        the Block is backed by a numpy array (except for datetime64 and
+        timedelta64 dtypes), while ``.array`` ensures to always return an
+        ExtensionArray.
+
+        Overview:
+
+        dtype       | values        | _values       | array                 |
+        ----------- | ------------- | ------------- | --------------------- |
+        Numeric     | ndarray       | ndarray       | NumpyExtensionArray   |
+        Category    | Categorical   | Categorical   | Categorical           |
+        dt64[ns]    | ndarray[M8ns] | DatetimeArray | DatetimeArray         |
+        dt64[ns tz] | ndarray[M8ns] | DatetimeArray | DatetimeArray         |
+        td64[ns]    | ndarray[m8ns] | TimedeltaArray| TimedeltaArray        |
+        Period      | ndarray[obj]  | PeriodArray   | PeriodArray           |
+        Nullable    | EA            | EA            | EA                    |
+
+        """
+        return self._mgr.internal_values()
+
+    @property
+    def _references(self) -> BlockValuesRefs | None:
+        if isinstance(self._mgr, SingleArrayManager):
+            return None
+        return self._mgr._block.refs
+
+    # error: Decorated property not supported
+    @Appender(base.IndexOpsMixin.array.__doc__)  # type: ignore[misc]
+    @property
+    def array(self) -> ExtensionArray:
+        return self._mgr.array_values()
+
+    # ops
+    def ravel(self, order: str = "C") -> ArrayLike:
+        """
+        Return the flattened underlying data as an ndarray or ExtensionArray.
+
+        .. deprecated:: 2.2.0
+            Series.ravel is deprecated. The underlying array is already 1D, so
+            ravel is not necessary.  Use :meth:`to_numpy` for conversion to a numpy
+            array instead.
+
+        Returns
+        -------
+        numpy.ndarray or ExtensionArray
+            Flattened data of the Series.
+
+        See Also
+        --------
+        numpy.ndarray.ravel : Return a flattened array.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.ravel()  # doctest: +SKIP
+        array([1, 2, 3])
+        """
+        warnings.warn(
+            "Series.ravel is deprecated. The underlying array is already 1D, so "
+            "ravel is not necessary.  Use `to_numpy()` for conversion to a numpy "
+            "array instead.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        arr = self._values.ravel(order=order)
+        if isinstance(arr, np.ndarray) and using_copy_on_write():
+            arr.flags.writeable = False
+        return arr
+
+    def __len__(self) -> int:
+        """
+        Return the length of the Series.
+        """
+        return len(self._mgr)
+
+    def view(self, dtype: Dtype | None = None) -> Series:
+        """
+        Create a new view of the Series.
+
+        .. deprecated:: 2.2.0
+            ``Series.view`` is deprecated and will be removed in a future version.
+            Use :meth:`Series.astype` as an alternative to change the dtype.
+
+        This function will return a new Series with a view of the same
+        underlying values in memory, optionally reinterpreted with a new data
+        type. The new data type must preserve the same size in bytes as to not
+        cause index misalignment.
+
+        Parameters
+        ----------
+        dtype : data type
+            Data type object or one of their string representations.
+
+        Returns
+        -------
+        Series
+            A new Series object as a view of the same data in memory.
+
+        See Also
+        --------
+        numpy.ndarray.view : Equivalent numpy function to create a new view of
+            the same data in memory.
+
+        Notes
+        -----
+        Series are instantiated with ``dtype=float64`` by default. While
+        ``numpy.ndarray.view()`` will return a view with the same data type as
+        the original array, ``Series.view()`` (without specified dtype)
+        will try using ``float64`` and may fail if the original data type size
+        in bytes is not the same.
+
+        Examples
+        --------
+        Use ``astype`` to change the dtype instead.
+        """
+        warnings.warn(
+            "Series.view is deprecated and will be removed in a future version. "
+            "Use ``astype`` as an alternative to change the dtype.",
+            FutureWarning,
+            stacklevel=2,
+        )
+        # self.array instead of self._values so we piggyback on NumpyExtensionArray
+        #  implementation
+        res_values = self.array.view(dtype)
+        res_ser = self._constructor(res_values, index=self.index, copy=False)
+        if isinstance(res_ser._mgr, SingleBlockManager):
+            blk = res_ser._mgr._block
+            blk.refs = cast("BlockValuesRefs", self._references)
+            blk.refs.add_reference(blk)
+        return res_ser.__finalize__(self, method="view")
+
+    # ----------------------------------------------------------------------
+    # NDArray Compat
+    def __array__(
+        self, dtype: npt.DTypeLike | None = None, copy: bool | None = None
+    ) -> np.ndarray:
+        """
+        Return the values as a NumPy array.
+
+        Users should not call this directly. Rather, it is invoked by
+        :func:`numpy.array` and :func:`numpy.asarray`.
+
+        Parameters
+        ----------
+        dtype : str or numpy.dtype, optional
+            The dtype to use for the resulting NumPy array. By default,
+            the dtype is inferred from the data.
+
+        copy : bool or None, optional
+            See :func:`numpy.asarray`.
+
+        Returns
+        -------
+        numpy.ndarray
+            The values in the series converted to a :class:`numpy.ndarray`
+            with the specified `dtype`.
+
+        See Also
+        --------
+        array : Create a new array from data.
+        Series.array : Zero-copy view to the array backing the Series.
+        Series.to_numpy : Series method for similar behavior.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3])
+        >>> np.asarray(ser)
+        array([1, 2, 3])
+
+        For timezone-aware data, the timezones may be retained with
+        ``dtype='object'``
+
+        >>> tzser = pd.Series(pd.date_range('2000', periods=2, tz="CET"))
+        >>> np.asarray(tzser, dtype="object")
+        array([Timestamp('2000-01-01 00:00:00+0100', tz='CET'),
+               Timestamp('2000-01-02 00:00:00+0100', tz='CET')],
+              dtype=object)
+
+        Or the values may be localized to UTC and the tzinfo discarded with
+        ``dtype='datetime64[ns]'``
+
+        >>> np.asarray(tzser, dtype="datetime64[ns]")  # doctest: +ELLIPSIS
+        array(['1999-12-31T23:00:00.000000000', ...],
+              dtype='datetime64[ns]')
+        """
+        values = self._values
+        if copy is None:
+            # Note: branch avoids `copy=None` for NumPy 1.x support
+            arr = np.asarray(values, dtype=dtype)
+        else:
+            arr = np.array(values, dtype=dtype, copy=copy)
+
+        if copy is True:
+            return arr
+        if using_copy_on_write() and (
+            copy is False or astype_is_view(values.dtype, arr.dtype)
+        ):
+            arr = arr.view()
+            arr.flags.writeable = False
+        return arr
+
+    # ----------------------------------------------------------------------
+
+    def __column_consortium_standard__(self, *, api_version: str | None = None) -> Any:
+        """
+        Provide entry point to the Consortium DataFrame Standard API.
+
+        This is developed and maintained outside of pandas.
+        Please report any issues to https://github.com/data-apis/dataframe-api-compat.
+        """
+        dataframe_api_compat = import_optional_dependency("dataframe_api_compat")
+        return (
+            dataframe_api_compat.pandas_standard.convert_to_standard_compliant_column(
+                self, api_version=api_version
+            )
+        )
+
+    # ----------------------------------------------------------------------
+    # Unary Methods
+
+    # coercion
+    __float__ = _coerce_method(float)
+    __int__ = _coerce_method(int)
+
+    # ----------------------------------------------------------------------
+
+    # indexers
+    @property
+    def axes(self) -> list[Index]:
+        """
+        Return a list of the row axis labels.
+        """
+        return [self.index]
+
+    # ----------------------------------------------------------------------
+    # Indexing Methods
+
+    def _ixs(self, i: int, axis: AxisInt = 0) -> Any:
+        """
+        Return the i-th value or values in the Series by location.
+
+        Parameters
+        ----------
+        i : int
+
+        Returns
+        -------
+        scalar
+        """
+        return self._values[i]
+
+    def _slice(self, slobj: slice, axis: AxisInt = 0) -> Series:
+        # axis kwarg is retained for compat with NDFrame method
+        #  _slice is *always* positional
+        mgr = self._mgr.get_slice(slobj, axis=axis)
+        out = self._constructor_from_mgr(mgr, axes=mgr.axes)
+        out._name = self._name
+        return out.__finalize__(self)
+
+    def __getitem__(self, key):
+        check_dict_or_set_indexers(key)
+        key = com.apply_if_callable(key, self)
+
+        if key is Ellipsis:
+            if using_copy_on_write() or warn_copy_on_write():
+                return self.copy(deep=False)
+            return self
+
+        key_is_scalar = is_scalar(key)
+        if isinstance(key, (list, tuple)):
+            key = unpack_1tuple(key)
+
+        if is_integer(key) and self.index._should_fallback_to_positional:
+            warnings.warn(
+                # GH#50617
+                "Series.__getitem__ treating keys as positions is deprecated. "
+                "In a future version, integer keys will always be treated "
+                "as labels (consistent with DataFrame behavior). To access "
+                "a value by position, use `ser.iloc[pos]`",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            return self._values[key]
+
+        elif key_is_scalar:
+            return self._get_value(key)
+
+        # Convert generator to list before going through hashable part
+        # (We will iterate through the generator there to check for slices)
+        if is_iterator(key):
+            key = list(key)
+
+        if is_hashable(key) and not isinstance(key, slice):
+            # Otherwise index.get_value will raise InvalidIndexError
+            try:
+                # For labels that don't resolve as scalars like tuples and frozensets
+                result = self._get_value(key)
+
+                return result
+
+            except (KeyError, TypeError, InvalidIndexError):
+                # InvalidIndexError for e.g. generator
+                #  see test_series_getitem_corner_generator
+                if isinstance(key, tuple) and isinstance(self.index, MultiIndex):
+                    # We still have the corner case where a tuple is a key
+                    # in the first level of our MultiIndex
+                    return self._get_values_tuple(key)
+
+        if isinstance(key, slice):
+            # Do slice check before somewhat-costly is_bool_indexer
+            return self._getitem_slice(key)
+
+        if com.is_bool_indexer(key):
+            key = check_bool_indexer(self.index, key)
+            key = np.asarray(key, dtype=bool)
+            return self._get_rows_with_mask(key)
+
+        return self._get_with(key)
+
+    def _get_with(self, key):
+        # other: fancy integer or otherwise
+        if isinstance(key, ABCDataFrame):
+            raise TypeError(
+                "Indexing a Series with DataFrame is not "
+                "supported, use the appropriate DataFrame column"
+            )
+        elif isinstance(key, tuple):
+            return self._get_values_tuple(key)
+
+        elif not is_list_like(key):
+            # e.g. scalars that aren't recognized by lib.is_scalar, GH#32684
+            return self.loc[key]
+
+        if not isinstance(key, (list, np.ndarray, ExtensionArray, Series, Index)):
+            key = list(key)
+
+        key_type = lib.infer_dtype(key, skipna=False)
+
+        # Note: The key_type == "boolean" case should be caught by the
+        #  com.is_bool_indexer check in __getitem__
+        if key_type == "integer":
+            # We need to decide whether to treat this as a positional indexer
+            #  (i.e. self.iloc) or label-based (i.e. self.loc)
+            if not self.index._should_fallback_to_positional:
+                return self.loc[key]
+            else:
+                warnings.warn(
+                    # GH#50617
+                    "Series.__getitem__ treating keys as positions is deprecated. "
+                    "In a future version, integer keys will always be treated "
+                    "as labels (consistent with DataFrame behavior). To access "
+                    "a value by position, use `ser.iloc[pos]`",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                return self.iloc[key]
+
+        # handle the dup indexing case GH#4246
+        return self.loc[key]
+
+    def _get_values_tuple(self, key: tuple):
+        # mpl hackaround
+        if com.any_none(*key):
+            # mpl compat if we look up e.g. ser[:, np.newaxis];
+            #  see tests.series.timeseries.test_mpl_compat_hack
+            # the asarray is needed to avoid returning a 2D DatetimeArray
+            result = np.asarray(self._values[key])
+            disallow_ndim_indexing(result)
+            return result
+
+        if not isinstance(self.index, MultiIndex):
+            raise KeyError("key of type tuple not found and not a MultiIndex")
+
+        # If key is contained, would have returned by now
+        indexer, new_index = self.index.get_loc_level(key)
+        new_ser = self._constructor(self._values[indexer], index=new_index, copy=False)
+        if isinstance(indexer, slice):
+            new_ser._mgr.add_references(self._mgr)  # type: ignore[arg-type]
+        return new_ser.__finalize__(self)
+
+    def _get_rows_with_mask(self, indexer: npt.NDArray[np.bool_]) -> Series:
+        new_mgr = self._mgr.get_rows_with_mask(indexer)
+        return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(self)
+
+    def _get_value(self, label, takeable: bool = False):
+        """
+        Quickly retrieve single value at passed index label.
+
+        Parameters
+        ----------
+        label : object
+        takeable : interpret the index as indexers, default False
+
+        Returns
+        -------
+        scalar value
+        """
+        if takeable:
+            return self._values[label]
+
+        # Similar to Index.get_value, but we do not fall back to positional
+        loc = self.index.get_loc(label)
+
+        if is_integer(loc):
+            return self._values[loc]
+
+        if isinstance(self.index, MultiIndex):
+            mi = self.index
+            new_values = self._values[loc]
+            if len(new_values) == 1 and mi.nlevels == 1:
+                # If more than one level left, we can not return a scalar
+                return new_values[0]
+
+            new_index = mi[loc]
+            new_index = maybe_droplevels(new_index, label)
+            new_ser = self._constructor(
+                new_values, index=new_index, name=self.name, copy=False
+            )
+            if isinstance(loc, slice):
+                new_ser._mgr.add_references(self._mgr)  # type: ignore[arg-type]
+            return new_ser.__finalize__(self)
+
+        else:
+            return self.iloc[loc]
+
+    def __setitem__(self, key, value) -> None:
+        warn = True
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self) <= 3:
+                warnings.warn(
+                    _chained_assignment_msg, ChainedAssignmentError, stacklevel=2
+                )
+        elif not PYPY and not WARNING_CHECK_DISABLED and not using_copy_on_write():
+            ctr = sys.getrefcount(self)
+            ref_count = 3
+            if not warn_copy_on_write() and _check_cacher(self):
+                # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                ref_count += 1
+            if ctr <= ref_count and (
+                warn_copy_on_write()
+                or (
+                    not warn_copy_on_write()
+                    and self._mgr.blocks[0].refs.has_reference()  # type: ignore[union-attr]
+                )
+            ):
+                warn = False
+                warnings.warn(
+                    _chained_assignment_warning_msg, FutureWarning, stacklevel=2
+                )
+
+        check_dict_or_set_indexers(key)
+        key = com.apply_if_callable(key, self)
+        cacher_needs_updating = self._check_is_chained_assignment_possible()
+
+        if key is Ellipsis:
+            key = slice(None)
+
+        if isinstance(key, slice):
+            indexer = self.index._convert_slice_indexer(key, kind="getitem")
+            return self._set_values(indexer, value, warn=warn)
+
+        try:
+            self._set_with_engine(key, value, warn=warn)
+        except KeyError:
+            # We have a scalar (or for MultiIndex or object-dtype, scalar-like)
+            #  key that is not present in self.index.
+            if is_integer(key):
+                if not self.index._should_fallback_to_positional:
+                    # GH#33469
+                    self.loc[key] = value
+                else:
+                    # positional setter
+                    # can't use _mgr.setitem_inplace yet bc could have *both*
+                    #  KeyError and then ValueError, xref GH#45070
+                    warnings.warn(
+                        # GH#50617
+                        "Series.__setitem__ treating keys as positions is deprecated. "
+                        "In a future version, integer keys will always be treated "
+                        "as labels (consistent with DataFrame behavior). To set "
+                        "a value by position, use `ser.iloc[pos] = value`",
+                        FutureWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    self._set_values(key, value)
+            else:
+                # GH#12862 adding a new key to the Series
+                self.loc[key] = value
+
+        except (TypeError, ValueError, LossySetitemError):
+            # The key was OK, but we cannot set the value losslessly
+            indexer = self.index.get_loc(key)
+            self._set_values(indexer, value)
+
+        except InvalidIndexError as err:
+            if isinstance(key, tuple) and not isinstance(self.index, MultiIndex):
+                # cases with MultiIndex don't get here bc they raise KeyError
+                # e.g. test_basic_getitem_setitem_corner
+                raise KeyError(
+                    "key of type tuple not found and not a MultiIndex"
+                ) from err
+
+            if com.is_bool_indexer(key):
+                key = check_bool_indexer(self.index, key)
+                key = np.asarray(key, dtype=bool)
+
+                if (
+                    is_list_like(value)
+                    and len(value) != len(self)
+                    and not isinstance(value, Series)
+                    and not is_object_dtype(self.dtype)
+                ):
+                    # Series will be reindexed to have matching length inside
+                    #  _where call below
+                    # GH#44265
+                    indexer = key.nonzero()[0]
+                    self._set_values(indexer, value)
+                    return
+
+                # otherwise with listlike other we interpret series[mask] = other
+                #  as series[mask] = other[mask]
+                try:
+                    self._where(~key, value, inplace=True, warn=warn)
+                except InvalidIndexError:
+                    # test_where_dups
+                    self.iloc[key] = value
+                return
+
+            else:
+                self._set_with(key, value, warn=warn)
+
+        if cacher_needs_updating:
+            self._maybe_update_cacher(inplace=True)
+
+    def _set_with_engine(self, key, value, warn: bool = True) -> None:
+        loc = self.index.get_loc(key)
+
+        # this is equivalent to self._values[key] = value
+        self._mgr.setitem_inplace(loc, value, warn=warn)
+
+    def _set_with(self, key, value, warn: bool = True) -> None:
+        # We got here via exception-handling off of InvalidIndexError, so
+        #  key should always be listlike at this point.
+        assert not isinstance(key, tuple)
+
+        if is_iterator(key):
+            # Without this, the call to infer_dtype will consume the generator
+            key = list(key)
+
+        if not self.index._should_fallback_to_positional:
+            # Regardless of the key type, we're treating it as labels
+            self._set_labels(key, value, warn=warn)
+
+        else:
+            # Note: key_type == "boolean" should not occur because that
+            #  should be caught by the is_bool_indexer check in __setitem__
+            key_type = lib.infer_dtype(key, skipna=False)
+
+            if key_type == "integer":
+                warnings.warn(
+                    # GH#50617
+                    "Series.__setitem__ treating keys as positions is deprecated. "
+                    "In a future version, integer keys will always be treated "
+                    "as labels (consistent with DataFrame behavior). To set "
+                    "a value by position, use `ser.iloc[pos] = value`",
+                    FutureWarning,
+                    stacklevel=find_stack_level(),
+                )
+                self._set_values(key, value, warn=warn)
+            else:
+                self._set_labels(key, value, warn=warn)
+
+    def _set_labels(self, key, value, warn: bool = True) -> None:
+        key = com.asarray_tuplesafe(key)
+        indexer: np.ndarray = self.index.get_indexer(key)
+        mask = indexer == -1
+        if mask.any():
+            raise KeyError(f"{key[mask]} not in index")
+        self._set_values(indexer, value, warn=warn)
+
+    def _set_values(self, key, value, warn: bool = True) -> None:
+        if isinstance(key, (Index, Series)):
+            key = key._values
+
+        self._mgr = self._mgr.setitem(indexer=key, value=value, warn=warn)
+        self._maybe_update_cacher()
+
+    def _set_value(self, label, value, takeable: bool = False) -> None:
+        """
+        Quickly set single value at passed label.
+
+        If label is not contained, a new object is created with the label
+        placed at the end of the result index.
+
+        Parameters
+        ----------
+        label : object
+            Partial indexing with MultiIndex not allowed.
+        value : object
+            Scalar value.
+        takeable : interpret the index as indexers, default False
+        """
+        if not takeable:
+            try:
+                loc = self.index.get_loc(label)
+            except KeyError:
+                # set using a non-recursive method
+                self.loc[label] = value
+                return
+        else:
+            loc = label
+
+        self._set_values(loc, value)
+
+    # ----------------------------------------------------------------------
+    # Lookup Caching
+
+    @property
+    def _is_cached(self) -> bool:
+        """Return boolean indicating if self is cached or not."""
+        return getattr(self, "_cacher", None) is not None
+
+    def _get_cacher(self):
+        """return my cacher or None"""
+        cacher = getattr(self, "_cacher", None)
+        if cacher is not None:
+            cacher = cacher[1]()
+        return cacher
+
+    def _reset_cacher(self) -> None:
+        """
+        Reset the cacher.
+        """
+        if hasattr(self, "_cacher"):
+            del self._cacher
+
+    def _set_as_cached(self, item, cacher) -> None:
+        """
+        Set the _cacher attribute on the calling object with a weakref to
+        cacher.
+        """
+        if using_copy_on_write():
+            return
+        self._cacher = (item, weakref.ref(cacher))
+
+    def _clear_item_cache(self) -> None:
+        # no-op for Series
+        pass
+
+    def _check_is_chained_assignment_possible(self) -> bool:
+        """
+        See NDFrame._check_is_chained_assignment_possible.__doc__
+        """
+        if self._is_view and self._is_cached:
+            ref = self._get_cacher()
+            if ref is not None and ref._is_mixed_type:
+                self._check_setitem_copy(t="referent", force=True)
+            return True
+        return super()._check_is_chained_assignment_possible()
+
+    def _maybe_update_cacher(
+        self, clear: bool = False, verify_is_copy: bool = True, inplace: bool = False
+    ) -> None:
+        """
+        See NDFrame._maybe_update_cacher.__doc__
+        """
+        # for CoW, we never want to update the parent DataFrame cache
+        # if the Series changed, but don't keep track of any cacher
+        if using_copy_on_write():
+            return
+        cacher = getattr(self, "_cacher", None)
+        if cacher is not None:
+            ref: DataFrame = cacher[1]()
+
+            # we are trying to reference a dead referent, hence
+            # a copy
+            if ref is None:
+                del self._cacher
+            elif len(self) == len(ref) and self.name in ref.columns:
+                # GH#42530 self.name must be in ref.columns
+                # to ensure column still in dataframe
+                # otherwise, either self or ref has swapped in new arrays
+                ref._maybe_cache_changed(cacher[0], self, inplace=inplace)
+            else:
+                # GH#33675 we have swapped in a new array, so parent
+                #  reference to self is now invalid
+                ref._item_cache.pop(cacher[0], None)
+
+        super()._maybe_update_cacher(
+            clear=clear, verify_is_copy=verify_is_copy, inplace=inplace
+        )
+
+    # ----------------------------------------------------------------------
+    # Unsorted
+
+    def repeat(self, repeats: int | Sequence[int], axis: None = None) -> Series:
+        """
+        Repeat elements of a Series.
+
+        Returns a new Series where each element of the current Series
+        is repeated consecutively a given number of times.
+
+        Parameters
+        ----------
+        repeats : int or array of ints
+            The number of repetitions for each element. This should be a
+            non-negative integer. Repeating 0 times will return an empty
+            Series.
+        axis : None
+            Unused. Parameter needed for compatibility with DataFrame.
+
+        Returns
+        -------
+        Series
+            Newly created Series with repeated elements.
+
+        See Also
+        --------
+        Index.repeat : Equivalent function for Index.
+        numpy.repeat : Similar method for :class:`numpy.ndarray`.
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c'])
+        >>> s
+        0    a
+        1    b
+        2    c
+        dtype: object
+        >>> s.repeat(2)
+        0    a
+        0    a
+        1    b
+        1    b
+        2    c
+        2    c
+        dtype: object
+        >>> s.repeat([1, 2, 3])
+        0    a
+        1    b
+        1    b
+        2    c
+        2    c
+        2    c
+        dtype: object
+        """
+        nv.validate_repeat((), {"axis": axis})
+        new_index = self.index.repeat(repeats)
+        new_values = self._values.repeat(repeats)
+        return self._constructor(new_values, index=new_index, copy=False).__finalize__(
+            self, method="repeat"
+        )
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: Literal[False] = ...,
+        name: Level = ...,
+        inplace: Literal[False] = ...,
+        allow_duplicates: bool = ...,
+    ) -> DataFrame:
+        ...
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: Literal[True],
+        name: Level = ...,
+        inplace: Literal[False] = ...,
+        allow_duplicates: bool = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def reset_index(
+        self,
+        level: IndexLabel = ...,
+        *,
+        drop: bool = ...,
+        name: Level = ...,
+        inplace: Literal[True],
+        allow_duplicates: bool = ...,
+    ) -> None:
+        ...
+
+    def reset_index(
+        self,
+        level: IndexLabel | None = None,
+        *,
+        drop: bool = False,
+        name: Level = lib.no_default,
+        inplace: bool = False,
+        allow_duplicates: bool = False,
+    ) -> DataFrame | Series | None:
+        """
+        Generate a new DataFrame or Series with the index reset.
+
+        This is useful when the index needs to be treated as a column, or
+        when the index is meaningless and needs to be reset to the default
+        before another operation.
+
+        Parameters
+        ----------
+        level : int, str, tuple, or list, default optional
+            For a Series with a MultiIndex, only remove the specified levels
+            from the index. Removes all levels by default.
+        drop : bool, default False
+            Just reset the index, without inserting it as a column in
+            the new DataFrame.
+        name : object, optional
+            The name to use for the column containing the original Series
+            values. Uses ``self.name`` by default. This argument is ignored
+            when `drop` is True.
+        inplace : bool, default False
+            Modify the Series in place (do not create a new object).
+        allow_duplicates : bool, default False
+            Allow duplicate column labels to be created.
+
+            .. versionadded:: 1.5.0
+
+        Returns
+        -------
+        Series or DataFrame or None
+            When `drop` is False (the default), a DataFrame is returned.
+            The newly created columns will come first in the DataFrame,
+            followed by the original Series values.
+            When `drop` is True, a `Series` is returned.
+            In either case, if ``inplace=True``, no value is returned.
+
+        See Also
+        --------
+        DataFrame.reset_index: Analogous function for DataFrame.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4], name='foo',
+        ...               index=pd.Index(['a', 'b', 'c', 'd'], name='idx'))
+
+        Generate a DataFrame with default index.
+
+        >>> s.reset_index()
+          idx  foo
+        0   a    1
+        1   b    2
+        2   c    3
+        3   d    4
+
+        To specify the name of the new column use `name`.
+
+        >>> s.reset_index(name='values')
+          idx  values
+        0   a       1
+        1   b       2
+        2   c       3
+        3   d       4
+
+        To generate a new Series with the default set `drop` to True.
+
+        >>> s.reset_index(drop=True)
+        0    1
+        1    2
+        2    3
+        3    4
+        Name: foo, dtype: int64
+
+        The `level` parameter is interesting for Series with a multi-level
+        index.
+
+        >>> arrays = [np.array(['bar', 'bar', 'baz', 'baz']),
+        ...           np.array(['one', 'two', 'one', 'two'])]
+        >>> s2 = pd.Series(
+        ...     range(4), name='foo',
+        ...     index=pd.MultiIndex.from_arrays(arrays,
+        ...                                     names=['a', 'b']))
+
+        To remove a specific level from the Index, use `level`.
+
+        >>> s2.reset_index(level='a')
+               a  foo
+        b
+        one  bar    0
+        two  bar    1
+        one  baz    2
+        two  baz    3
+
+        If `level` is not set, all levels are removed from the Index.
+
+        >>> s2.reset_index()
+             a    b  foo
+        0  bar  one    0
+        1  bar  two    1
+        2  baz  one    2
+        3  baz  two    3
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        if drop:
+            new_index = default_index(len(self))
+            if level is not None:
+                level_list: Sequence[Hashable]
+                if not isinstance(level, (tuple, list)):
+                    level_list = [level]
+                else:
+                    level_list = level
+                level_list = [self.index._get_level_number(lev) for lev in level_list]
+                if len(level_list) < self.index.nlevels:
+                    new_index = self.index.droplevel(level_list)
+
+            if inplace:
+                self.index = new_index
+            elif using_copy_on_write():
+                new_ser = self.copy(deep=False)
+                new_ser.index = new_index
+                return new_ser.__finalize__(self, method="reset_index")
+            else:
+                return self._constructor(
+                    self._values.copy(), index=new_index, copy=False, dtype=self.dtype
+                ).__finalize__(self, method="reset_index")
+        elif inplace:
+            raise TypeError(
+                "Cannot reset_index inplace on a Series to create a DataFrame"
+            )
+        else:
+            if name is lib.no_default:
+                # For backwards compatibility, keep columns as [0] instead of
+                #  [None] when self.name is None
+                if self.name is None:
+                    name = 0
+                else:
+                    name = self.name
+
+            df = self.to_frame(name)
+            return df.reset_index(
+                level=level, drop=drop, allow_duplicates=allow_duplicates
+            )
+        return None
+
+    # ----------------------------------------------------------------------
+    # Rendering Methods
+
+    def __repr__(self) -> str:
+        """
+        Return a string representation for a particular Series.
+        """
+        # pylint: disable=invalid-repr-returned
+        repr_params = fmt.get_series_repr_params()
+        return self.to_string(**repr_params)
+
+    @overload
+    def to_string(
+        self,
+        buf: None = ...,
+        na_rep: str = ...,
+        float_format: str | None = ...,
+        header: bool = ...,
+        index: bool = ...,
+        length: bool = ...,
+        dtype=...,
+        name=...,
+        max_rows: int | None = ...,
+        min_rows: int | None = ...,
+    ) -> str:
+        ...
+
+    @overload
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        na_rep: str = ...,
+        float_format: str | None = ...,
+        header: bool = ...,
+        index: bool = ...,
+        length: bool = ...,
+        dtype=...,
+        name=...,
+        max_rows: int | None = ...,
+        min_rows: int | None = ...,
+    ) -> None:
+        ...
+
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        na_rep: str = "NaN",
+        float_format: str | None = None,
+        header: bool = True,
+        index: bool = True,
+        length: bool = False,
+        dtype: bool = False,
+        name: bool = False,
+        max_rows: int | None = None,
+        min_rows: int | None = None,
+    ) -> str | None:
+        """
+        Render a string representation of the Series.
+
+        Parameters
+        ----------
+        buf : StringIO-like, optional
+            Buffer to write to.
+        na_rep : str, optional
+            String representation of NaN to use, default 'NaN'.
+        float_format : one-parameter function, optional
+            Formatter function to apply to columns' elements if they are
+            floats, default None.
+        header : bool, default True
+            Add the Series header (index name).
+        index : bool, optional
+            Add index (row) labels, default True.
+        length : bool, default False
+            Add the Series length.
+        dtype : bool, default False
+            Add the Series dtype.
+        name : bool, default False
+            Add the Series name if not None.
+        max_rows : int, optional
+            Maximum number of rows to show before truncating. If None, show
+            all.
+        min_rows : int, optional
+            The number of rows to display in a truncated repr (when number
+            of rows is above `max_rows`).
+
+        Returns
+        -------
+        str or None
+            String representation of Series if ``buf=None``, otherwise None.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3]).to_string()
+        >>> ser
+        '0    1\\n1    2\\n2    3'
+        """
+        formatter = fmt.SeriesFormatter(
+            self,
+            name=name,
+            length=length,
+            header=header,
+            index=index,
+            dtype=dtype,
+            na_rep=na_rep,
+            float_format=float_format,
+            min_rows=min_rows,
+            max_rows=max_rows,
+        )
+        result = formatter.to_string()
+
+        # catch contract violations
+        if not isinstance(result, str):
+            raise AssertionError(
+                "result must be of type str, type "
+                f"of result is {repr(type(result).__name__)}"
+            )
+
+        if buf is None:
+            return result
+        else:
+            if hasattr(buf, "write"):
+                buf.write(result)
+            else:
+                with open(buf, "w", encoding="utf-8") as f:
+                    f.write(result)
+        return None
+
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        storage_options=_shared_docs["storage_options"],
+        examples=dedent(
+            """Examples
+            --------
+            >>> s = pd.Series(["elk", "pig", "dog", "quetzal"], name="animal")
+            >>> print(s.to_markdown())
+            |    | animal   |
+            |---:|:---------|
+            |  0 | elk      |
+            |  1 | pig      |
+            |  2 | dog      |
+            |  3 | quetzal  |
+
+            Output markdown with a tabulate option.
+
+            >>> print(s.to_markdown(tablefmt="grid"))
+            +----+----------+
+            |    | animal   |
+            +====+==========+
+            |  0 | elk      |
+            +----+----------+
+            |  1 | pig      |
+            +----+----------+
+            |  2 | dog      |
+            +----+----------+
+            |  3 | quetzal  |
+            +----+----------+"""
+        ),
+    )
+    def to_markdown(
+        self,
+        buf: IO[str] | None = None,
+        mode: str = "wt",
+        index: bool = True,
+        storage_options: StorageOptions | None = None,
+        **kwargs,
+    ) -> str | None:
+        """
+        Print {klass} in Markdown-friendly format.
+
+        Parameters
+        ----------
+        buf : str, Path or StringIO-like, optional, default None
+            Buffer to write to. If None, the output is returned as a string.
+        mode : str, optional
+            Mode in which file is opened, "wt" by default.
+        index : bool, optional, default True
+            Add index (row) labels.
+
+        {storage_options}
+
+        **kwargs
+            These parameters will be passed to `tabulate \
+                `_.
+
+        Returns
+        -------
+        str
+            {klass} in Markdown-friendly format.
+
+        Notes
+        -----
+        Requires the `tabulate `_ package.
+
+        {examples}
+        """
+        return self.to_frame().to_markdown(
+            buf, mode=mode, index=index, storage_options=storage_options, **kwargs
+        )
+
+    # ----------------------------------------------------------------------
+
+    def items(self) -> Iterable[tuple[Hashable, Any]]:
+        """
+        Lazily iterate over (index, value) tuples.
+
+        This method returns an iterable tuple (index, value). This is
+        convenient if you want to create a lazy iterator.
+
+        Returns
+        -------
+        iterable
+            Iterable of tuples containing the (index, value) pairs from a
+            Series.
+
+        See Also
+        --------
+        DataFrame.items : Iterate over (column name, Series) pairs.
+        DataFrame.iterrows : Iterate over DataFrame rows as (index, Series) pairs.
+
+        Examples
+        --------
+        >>> s = pd.Series(['A', 'B', 'C'])
+        >>> for index, value in s.items():
+        ...     print(f"Index : {index}, Value : {value}")
+        Index : 0, Value : A
+        Index : 1, Value : B
+        Index : 2, Value : C
+        """
+        return zip(iter(self.index), iter(self))
+
+    # ----------------------------------------------------------------------
+    # Misc public methods
+
+    def keys(self) -> Index:
+        """
+        Return alias for index.
+
+        Returns
+        -------
+        Index
+            Index of the Series.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3], index=[0, 1, 2])
+        >>> s.keys()
+        Index([0, 1, 2], dtype='int64')
+        """
+        return self.index
+
+    @overload
+    def to_dict(
+        self, *, into: type[MutableMappingT] | MutableMappingT
+    ) -> MutableMappingT:
+        ...
+
+    @overload
+    def to_dict(self, *, into: type[dict] = ...) -> dict:
+        ...
+
+    # error: Incompatible default for argument "into" (default has type "type[
+    # dict[Any, Any]]", argument has type "type[MutableMappingT] | MutableMappingT")
+    @deprecate_nonkeyword_arguments(
+        version="3.0", allowed_args=["self"], name="to_dict"
+    )
+    def to_dict(
+        self,
+        into: type[MutableMappingT]
+        | MutableMappingT = dict,  # type: ignore[assignment]
+    ) -> MutableMappingT:
+        """
+        Convert Series to {label -> value} dict or dict-like object.
+
+        Parameters
+        ----------
+        into : class, default dict
+            The collections.abc.MutableMapping subclass to use as the return
+            object. Can be the actual class or an empty instance of the mapping
+            type you want.  If you want a collections.defaultdict, you must
+            pass it initialized.
+
+        Returns
+        -------
+        collections.abc.MutableMapping
+            Key-value representation of Series.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s.to_dict()
+        {0: 1, 1: 2, 2: 3, 3: 4}
+        >>> from collections import OrderedDict, defaultdict
+        >>> s.to_dict(into=OrderedDict)
+        OrderedDict([(0, 1), (1, 2), (2, 3), (3, 4)])
+        >>> dd = defaultdict(list)
+        >>> s.to_dict(into=dd)
+        defaultdict(, {0: 1, 1: 2, 2: 3, 3: 4})
+        """
+        # GH16122
+        into_c = com.standardize_mapping(into)
+
+        if is_object_dtype(self.dtype) or isinstance(self.dtype, ExtensionDtype):
+            return into_c((k, maybe_box_native(v)) for k, v in self.items())
+        else:
+            # Not an object dtype => all types will be the same so let the default
+            # indexer return native python type
+            return into_c(self.items())
+
+    def to_frame(self, name: Hashable = lib.no_default) -> DataFrame:
+        """
+        Convert Series to DataFrame.
+
+        Parameters
+        ----------
+        name : object, optional
+            The passed name should substitute for the series name (if it has
+            one).
+
+        Returns
+        -------
+        DataFrame
+            DataFrame representation of Series.
+
+        Examples
+        --------
+        >>> s = pd.Series(["a", "b", "c"],
+        ...               name="vals")
+        >>> s.to_frame()
+          vals
+        0    a
+        1    b
+        2    c
+        """
+        columns: Index
+        if name is lib.no_default:
+            name = self.name
+            if name is None:
+                # default to [0], same as we would get with DataFrame(self)
+                columns = default_index(1)
+            else:
+                columns = Index([name])
+        else:
+            columns = Index([name])
+
+        mgr = self._mgr.to_2d_mgr(columns)
+        df = self._constructor_expanddim_from_mgr(mgr, axes=mgr.axes)
+        return df.__finalize__(self, method="to_frame")
+
+    def _set_name(
+        self, name, inplace: bool = False, deep: bool | None = None
+    ) -> Series:
+        """
+        Set the Series name.
+
+        Parameters
+        ----------
+        name : str
+        inplace : bool
+            Whether to modify `self` directly or return a copy.
+        deep : bool|None, default None
+            Whether to do a deep copy, a shallow copy, or Copy on Write(None)
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        ser = self if inplace else self.copy(deep and not using_copy_on_write())
+        ser.name = name
+        return ser
+
+    @Appender(
+        dedent(
+            """
+        Examples
+        --------
+        >>> ser = pd.Series([390., 350., 30., 20.],
+        ...                 index=['Falcon', 'Falcon', 'Parrot', 'Parrot'],
+        ...                 name="Max Speed")
+        >>> ser
+        Falcon    390.0
+        Falcon    350.0
+        Parrot     30.0
+        Parrot     20.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(["a", "b", "a", "b"]).mean()
+        a    210.0
+        b    185.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(level=0).mean()
+        Falcon    370.0
+        Parrot     25.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(ser > 100).mean()
+        Max Speed
+        False     25.0
+        True     370.0
+        Name: Max Speed, dtype: float64
+
+        **Grouping by Indexes**
+
+        We can groupby different levels of a hierarchical index
+        using the `level` parameter:
+
+        >>> arrays = [['Falcon', 'Falcon', 'Parrot', 'Parrot'],
+        ...           ['Captive', 'Wild', 'Captive', 'Wild']]
+        >>> index = pd.MultiIndex.from_arrays(arrays, names=('Animal', 'Type'))
+        >>> ser = pd.Series([390., 350., 30., 20.], index=index, name="Max Speed")
+        >>> ser
+        Animal  Type
+        Falcon  Captive    390.0
+                Wild       350.0
+        Parrot  Captive     30.0
+                Wild        20.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(level=0).mean()
+        Animal
+        Falcon    370.0
+        Parrot     25.0
+        Name: Max Speed, dtype: float64
+        >>> ser.groupby(level="Type").mean()
+        Type
+        Captive    210.0
+        Wild       185.0
+        Name: Max Speed, dtype: float64
+
+        We can also choose to include `NA` in group keys or not by defining
+        `dropna` parameter, the default setting is `True`.
+
+        >>> ser = pd.Series([1, 2, 3, 3], index=["a", 'a', 'b', np.nan])
+        >>> ser.groupby(level=0).sum()
+        a    3
+        b    3
+        dtype: int64
+
+        >>> ser.groupby(level=0, dropna=False).sum()
+        a    3
+        b    3
+        NaN  3
+        dtype: int64
+
+        >>> arrays = ['Falcon', 'Falcon', 'Parrot', 'Parrot']
+        >>> ser = pd.Series([390., 350., 30., 20.], index=arrays, name="Max Speed")
+        >>> ser.groupby(["a", "b", "a", np.nan]).mean()
+        a    210.0
+        b    350.0
+        Name: Max Speed, dtype: float64
+
+        >>> ser.groupby(["a", "b", "a", np.nan], dropna=False).mean()
+        a    210.0
+        b    350.0
+        NaN   20.0
+        Name: Max Speed, dtype: float64
+        """
+        )
+    )
+    @Appender(_shared_docs["groupby"] % _shared_doc_kwargs)
+    def groupby(
+        self,
+        by=None,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        as_index: bool = True,
+        sort: bool = True,
+        group_keys: bool = True,
+        observed: bool | lib.NoDefault = lib.no_default,
+        dropna: bool = True,
+    ) -> SeriesGroupBy:
+        from pandas.core.groupby.generic import SeriesGroupBy
+
+        if level is None and by is None:
+            raise TypeError("You have to supply one of 'by' and 'level'")
+        if not as_index:
+            raise TypeError("as_index=False only valid with DataFrame")
+        axis = self._get_axis_number(axis)
+
+        return SeriesGroupBy(
+            obj=self,
+            keys=by,
+            axis=axis,
+            level=level,
+            as_index=as_index,
+            sort=sort,
+            group_keys=group_keys,
+            observed=observed,
+            dropna=dropna,
+        )
+
+    # ----------------------------------------------------------------------
+    # Statistics, overridden ndarray methods
+
+    # TODO: integrate bottleneck
+    def count(self) -> int:
+        """
+        Return number of non-NA/null observations in the Series.
+
+        Returns
+        -------
+        int
+            Number of non-null values in the Series.
+
+        See Also
+        --------
+        DataFrame.count : Count non-NA cells for each column or row.
+
+        Examples
+        --------
+        >>> s = pd.Series([0.0, 1.0, np.nan])
+        >>> s.count()
+        2
+        """
+        return notna(self._values).sum().astype("int64")
+
+    def mode(self, dropna: bool = True) -> Series:
+        """
+        Return the mode(s) of the Series.
+
+        The mode is the value that appears most often. There can be multiple modes.
+
+        Always returns Series even if only one value is returned.
+
+        Parameters
+        ----------
+        dropna : bool, default True
+            Don't consider counts of NaN/NaT.
+
+        Returns
+        -------
+        Series
+            Modes of the Series in sorted order.
+
+        Examples
+        --------
+        >>> s = pd.Series([2, 4, 2, 2, 4, None])
+        >>> s.mode()
+        0    2.0
+        dtype: float64
+
+        More than one mode:
+
+        >>> s = pd.Series([2, 4, 8, 2, 4, None])
+        >>> s.mode()
+        0    2.0
+        1    4.0
+        dtype: float64
+
+        With and without considering null value:
+
+        >>> s = pd.Series([2, 4, None, None, 4, None])
+        >>> s.mode(dropna=False)
+        0   NaN
+        dtype: float64
+        >>> s = pd.Series([2, 4, None, None, 4, None])
+        >>> s.mode()
+        0    4.0
+        dtype: float64
+        """
+        # TODO: Add option for bins like value_counts()
+        values = self._values
+        if isinstance(values, np.ndarray):
+            res_values = algorithms.mode(values, dropna=dropna)
+        else:
+            res_values = values._mode(dropna=dropna)
+
+        # Ensure index is type stable (should always use int index)
+        return self._constructor(
+            res_values,
+            index=range(len(res_values)),
+            name=self.name,
+            copy=False,
+            dtype=self.dtype,
+        ).__finalize__(self, method="mode")
+
+    def unique(self) -> ArrayLike:  # pylint: disable=useless-parent-delegation
+        """
+        Return unique values of Series object.
+
+        Uniques are returned in order of appearance. Hash table-based unique,
+        therefore does NOT sort.
+
+        Returns
+        -------
+        ndarray or ExtensionArray
+            The unique values returned as a NumPy array. See Notes.
+
+        See Also
+        --------
+        Series.drop_duplicates : Return Series with duplicate values removed.
+        unique : Top-level unique method for any 1-d array-like object.
+        Index.unique : Return Index with unique values from an Index object.
+
+        Notes
+        -----
+        Returns the unique values as a NumPy array. In case of an
+        extension-array backed Series, a new
+        :class:`~api.extensions.ExtensionArray` of that type with just
+        the unique values is returned. This includes
+
+            * Categorical
+            * Period
+            * Datetime with Timezone
+            * Datetime without Timezone
+            * Timedelta
+            * Interval
+            * Sparse
+            * IntegerNA
+
+        See Examples section.
+
+        Examples
+        --------
+        >>> pd.Series([2, 1, 3, 3], name='A').unique()
+        array([2, 1, 3])
+
+        >>> pd.Series([pd.Timestamp('2016-01-01') for _ in range(3)]).unique()
+        
+        ['2016-01-01 00:00:00']
+        Length: 1, dtype: datetime64[ns]
+
+        >>> pd.Series([pd.Timestamp('2016-01-01', tz='US/Eastern')
+        ...            for _ in range(3)]).unique()
+        
+        ['2016-01-01 00:00:00-05:00']
+        Length: 1, dtype: datetime64[ns, US/Eastern]
+
+        An Categorical will return categories in the order of
+        appearance and with the same dtype.
+
+        >>> pd.Series(pd.Categorical(list('baabc'))).unique()
+        ['b', 'a', 'c']
+        Categories (3, object): ['a', 'b', 'c']
+        >>> pd.Series(pd.Categorical(list('baabc'), categories=list('abc'),
+        ...                          ordered=True)).unique()
+        ['b', 'a', 'c']
+        Categories (3, object): ['a' < 'b' < 'c']
+        """
+        return super().unique()
+
+    @overload
+    def drop_duplicates(
+        self,
+        *,
+        keep: DropKeep = ...,
+        inplace: Literal[False] = ...,
+        ignore_index: bool = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def drop_duplicates(
+        self, *, keep: DropKeep = ..., inplace: Literal[True], ignore_index: bool = ...
+    ) -> None:
+        ...
+
+    @overload
+    def drop_duplicates(
+        self, *, keep: DropKeep = ..., inplace: bool = ..., ignore_index: bool = ...
+    ) -> Series | None:
+        ...
+
+    def drop_duplicates(
+        self,
+        *,
+        keep: DropKeep = "first",
+        inplace: bool = False,
+        ignore_index: bool = False,
+    ) -> Series | None:
+        """
+        Return Series with duplicate values removed.
+
+        Parameters
+        ----------
+        keep : {'first', 'last', ``False``}, default 'first'
+            Method to handle dropping duplicates:
+
+            - 'first' : Drop duplicates except for the first occurrence.
+            - 'last' : Drop duplicates except for the last occurrence.
+            - ``False`` : Drop all duplicates.
+
+        inplace : bool, default ``False``
+            If ``True``, performs operation inplace and returns None.
+
+        ignore_index : bool, default ``False``
+            If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        Series or None
+            Series with duplicates dropped or None if ``inplace=True``.
+
+        See Also
+        --------
+        Index.drop_duplicates : Equivalent method on Index.
+        DataFrame.drop_duplicates : Equivalent method on DataFrame.
+        Series.duplicated : Related method on Series, indicating duplicate
+            Series values.
+        Series.unique : Return unique values as an array.
+
+        Examples
+        --------
+        Generate a Series with duplicated entries.
+
+        >>> s = pd.Series(['llama', 'cow', 'llama', 'beetle', 'llama', 'hippo'],
+        ...               name='animal')
+        >>> s
+        0     llama
+        1       cow
+        2     llama
+        3    beetle
+        4     llama
+        5     hippo
+        Name: animal, dtype: object
+
+        With the 'keep' parameter, the selection behaviour of duplicated values
+        can be changed. The value 'first' keeps the first occurrence for each
+        set of duplicated entries. The default value of keep is 'first'.
+
+        >>> s.drop_duplicates()
+        0     llama
+        1       cow
+        3    beetle
+        5     hippo
+        Name: animal, dtype: object
+
+        The value 'last' for parameter 'keep' keeps the last occurrence for
+        each set of duplicated entries.
+
+        >>> s.drop_duplicates(keep='last')
+        1       cow
+        3    beetle
+        4     llama
+        5     hippo
+        Name: animal, dtype: object
+
+        The value ``False`` for parameter 'keep' discards all sets of
+        duplicated entries.
+
+        >>> s.drop_duplicates(keep=False)
+        1       cow
+        3    beetle
+        5     hippo
+        Name: animal, dtype: object
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        result = super().drop_duplicates(keep=keep)
+
+        if ignore_index:
+            result.index = default_index(len(result))
+
+        if inplace:
+            self._update_inplace(result)
+            return None
+        else:
+            return result
+
+    def duplicated(self, keep: DropKeep = "first") -> Series:
+        """
+        Indicate duplicate Series values.
+
+        Duplicated values are indicated as ``True`` values in the resulting
+        Series. Either all duplicates, all except the first or all except the
+        last occurrence of duplicates can be indicated.
+
+        Parameters
+        ----------
+        keep : {'first', 'last', False}, default 'first'
+            Method to handle dropping duplicates:
+
+            - 'first' : Mark duplicates as ``True`` except for the first
+              occurrence.
+            - 'last' : Mark duplicates as ``True`` except for the last
+              occurrence.
+            - ``False`` : Mark all duplicates as ``True``.
+
+        Returns
+        -------
+        Series[bool]
+            Series indicating whether each value has occurred in the
+            preceding values.
+
+        See Also
+        --------
+        Index.duplicated : Equivalent method on pandas.Index.
+        DataFrame.duplicated : Equivalent method on pandas.DataFrame.
+        Series.drop_duplicates : Remove duplicate values from Series.
+
+        Examples
+        --------
+        By default, for each set of duplicated values, the first occurrence is
+        set on False and all others on True:
+
+        >>> animals = pd.Series(['llama', 'cow', 'llama', 'beetle', 'llama'])
+        >>> animals.duplicated()
+        0    False
+        1    False
+        2     True
+        3    False
+        4     True
+        dtype: bool
+
+        which is equivalent to
+
+        >>> animals.duplicated(keep='first')
+        0    False
+        1    False
+        2     True
+        3    False
+        4     True
+        dtype: bool
+
+        By using 'last', the last occurrence of each set of duplicated values
+        is set on False and all others on True:
+
+        >>> animals.duplicated(keep='last')
+        0     True
+        1    False
+        2     True
+        3    False
+        4    False
+        dtype: bool
+
+        By setting keep on ``False``, all duplicates are True:
+
+        >>> animals.duplicated(keep=False)
+        0     True
+        1    False
+        2     True
+        3    False
+        4     True
+        dtype: bool
+        """
+        res = self._duplicated(keep=keep)
+        result = self._constructor(res, index=self.index, copy=False)
+        return result.__finalize__(self, method="duplicated")
+
+    def idxmin(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Hashable:
+        """
+        Return the row label of the minimum value.
+
+        If multiple values equal the minimum, the first row label with that
+        value is returned.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        skipna : bool, default True
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
+        *args, **kwargs
+            Additional arguments and keywords have no effect but might be
+            accepted for compatibility with NumPy.
+
+        Returns
+        -------
+        Index
+            Label of the minimum value.
+
+        Raises
+        ------
+        ValueError
+            If the Series is empty.
+
+        See Also
+        --------
+        numpy.argmin : Return indices of the minimum values
+            along the given axis.
+        DataFrame.idxmin : Return index of first occurrence of minimum
+            over requested axis.
+        Series.idxmax : Return index *label* of the first occurrence
+            of maximum of values.
+
+        Notes
+        -----
+        This method is the Series version of ``ndarray.argmin``. This method
+        returns the label of the minimum, while ``ndarray.argmin`` returns
+        the position. To get the position, use ``series.values.argmin()``.
+
+        Examples
+        --------
+        >>> s = pd.Series(data=[1, None, 4, 1],
+        ...               index=['A', 'B', 'C', 'D'])
+        >>> s
+        A    1.0
+        B    NaN
+        C    4.0
+        D    1.0
+        dtype: float64
+
+        >>> s.idxmin()
+        'A'
+
+        If `skipna` is False and there is an NA value in the data,
+        the function returns ``nan``.
+
+        >>> s.idxmin(skipna=False)
+        nan
+        """
+        axis = self._get_axis_number(axis)
+        with warnings.catch_warnings():
+            # TODO(3.0): this catching/filtering can be removed
+            # ignore warning produced by argmin since we will issue a different
+            #  warning for idxmin
+            warnings.simplefilter("ignore")
+            i = self.argmin(axis, skipna, *args, **kwargs)
+
+        if i == -1:
+            # GH#43587 give correct NA value for Index.
+            warnings.warn(
+                f"The behavior of {type(self).__name__}.idxmin with all-NA "
+                "values, or any-NA and skipna=False, is deprecated. In a future "
+                "version this will raise ValueError",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            return self.index._na_value
+        return self.index[i]
+
+    def idxmax(self, axis: Axis = 0, skipna: bool = True, *args, **kwargs) -> Hashable:
+        """
+        Return the row label of the maximum value.
+
+        If multiple values equal the maximum, the first row label with that
+        value is returned.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        skipna : bool, default True
+            Exclude NA/null values. If the entire Series is NA, the result
+            will be NA.
+        *args, **kwargs
+            Additional arguments and keywords have no effect but might be
+            accepted for compatibility with NumPy.
+
+        Returns
+        -------
+        Index
+            Label of the maximum value.
+
+        Raises
+        ------
+        ValueError
+            If the Series is empty.
+
+        See Also
+        --------
+        numpy.argmax : Return indices of the maximum values
+            along the given axis.
+        DataFrame.idxmax : Return index of first occurrence of maximum
+            over requested axis.
+        Series.idxmin : Return index *label* of the first occurrence
+            of minimum of values.
+
+        Notes
+        -----
+        This method is the Series version of ``ndarray.argmax``. This method
+        returns the label of the maximum, while ``ndarray.argmax`` returns
+        the position. To get the position, use ``series.values.argmax()``.
+
+        Examples
+        --------
+        >>> s = pd.Series(data=[1, None, 4, 3, 4],
+        ...               index=['A', 'B', 'C', 'D', 'E'])
+        >>> s
+        A    1.0
+        B    NaN
+        C    4.0
+        D    3.0
+        E    4.0
+        dtype: float64
+
+        >>> s.idxmax()
+        'C'
+
+        If `skipna` is False and there is an NA value in the data,
+        the function returns ``nan``.
+
+        >>> s.idxmax(skipna=False)
+        nan
+        """
+        axis = self._get_axis_number(axis)
+        with warnings.catch_warnings():
+            # TODO(3.0): this catching/filtering can be removed
+            # ignore warning produced by argmax since we will issue a different
+            #  warning for argmax
+            warnings.simplefilter("ignore")
+            i = self.argmax(axis, skipna, *args, **kwargs)
+
+        if i == -1:
+            # GH#43587 give correct NA value for Index.
+            warnings.warn(
+                f"The behavior of {type(self).__name__}.idxmax with all-NA "
+                "values, or any-NA and skipna=False, is deprecated. In a future "
+                "version this will raise ValueError",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            return self.index._na_value
+        return self.index[i]
+
+    def round(self, decimals: int = 0, *args, **kwargs) -> Series:
+        """
+        Round each value in a Series to the given number of decimals.
+
+        Parameters
+        ----------
+        decimals : int, default 0
+            Number of decimal places to round to. If decimals is negative,
+            it specifies the number of positions to the left of the decimal point.
+        *args, **kwargs
+            Additional arguments and keywords have no effect but might be
+            accepted for compatibility with NumPy.
+
+        Returns
+        -------
+        Series
+            Rounded values of the Series.
+
+        See Also
+        --------
+        numpy.around : Round values of an np.array.
+        DataFrame.round : Round values of a DataFrame.
+
+        Examples
+        --------
+        >>> s = pd.Series([0.1, 1.3, 2.7])
+        >>> s.round()
+        0    0.0
+        1    1.0
+        2    3.0
+        dtype: float64
+        """
+        nv.validate_round(args, kwargs)
+        if self.dtype == "object":
+            raise TypeError("Expected numeric dtype, got object instead.")
+        new_mgr = self._mgr.round(decimals=decimals, using_cow=using_copy_on_write())
+        return self._constructor_from_mgr(new_mgr, axes=new_mgr.axes).__finalize__(
+            self, method="round"
+        )
+
+    @overload
+    def quantile(
+        self, q: float = ..., interpolation: QuantileInterpolation = ...
+    ) -> float:
+        ...
+
+    @overload
+    def quantile(
+        self,
+        q: Sequence[float] | AnyArrayLike,
+        interpolation: QuantileInterpolation = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def quantile(
+        self,
+        q: float | Sequence[float] | AnyArrayLike = ...,
+        interpolation: QuantileInterpolation = ...,
+    ) -> float | Series:
+        ...
+
+    def quantile(
+        self,
+        q: float | Sequence[float] | AnyArrayLike = 0.5,
+        interpolation: QuantileInterpolation = "linear",
+    ) -> float | Series:
+        """
+        Return value at the given quantile.
+
+        Parameters
+        ----------
+        q : float or array-like, default 0.5 (50% quantile)
+            The quantile(s) to compute, which can lie in range: 0 <= q <= 1.
+        interpolation : {'linear', 'lower', 'higher', 'midpoint', 'nearest'}
+            This optional parameter specifies the interpolation method to use,
+            when the desired quantile lies between two data points `i` and `j`:
+
+                * linear: `i + (j - i) * (x-i)/(j-i)`, where `(x-i)/(j-i)` is
+                  the fractional part of the index surrounded by `i > j`.
+                * lower: `i`.
+                * higher: `j`.
+                * nearest: `i` or `j` whichever is nearest.
+                * midpoint: (`i` + `j`) / 2.
+
+        Returns
+        -------
+        float or Series
+            If ``q`` is an array, a Series will be returned where the
+            index is ``q`` and the values are the quantiles, otherwise
+            a float will be returned.
+
+        See Also
+        --------
+        core.window.Rolling.quantile : Calculate the rolling quantile.
+        numpy.percentile : Returns the q-th percentile(s) of the array elements.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s.quantile(.5)
+        2.5
+        >>> s.quantile([.25, .5, .75])
+        0.25    1.75
+        0.50    2.50
+        0.75    3.25
+        dtype: float64
+        """
+        validate_percentile(q)
+
+        # We dispatch to DataFrame so that core.internals only has to worry
+        #  about 2D cases.
+        df = self.to_frame()
+
+        result = df.quantile(q=q, interpolation=interpolation, numeric_only=False)
+        if result.ndim == 2:
+            result = result.iloc[:, 0]
+
+        if is_list_like(q):
+            result.name = self.name
+            idx = Index(q, dtype=np.float64)
+            return self._constructor(result, index=idx, name=self.name)
+        else:
+            # scalar
+            return result.iloc[0]
+
+    def corr(
+        self,
+        other: Series,
+        method: CorrelationMethod = "pearson",
+        min_periods: int | None = None,
+    ) -> float:
+        """
+        Compute correlation with `other` Series, excluding missing values.
+
+        The two `Series` objects are not required to be the same length and will be
+        aligned internally before the correlation function is applied.
+
+        Parameters
+        ----------
+        other : Series
+            Series with which to compute the correlation.
+        method : {'pearson', 'kendall', 'spearman'} or callable
+            Method used to compute correlation:
+
+            - pearson : Standard correlation coefficient
+            - kendall : Kendall Tau correlation coefficient
+            - spearman : Spearman rank correlation
+            - callable: Callable with input two 1d ndarrays and returning a float.
+
+            .. warning::
+                Note that the returned matrix from corr will have 1 along the
+                diagonals and will be symmetric regardless of the callable's
+                behavior.
+        min_periods : int, optional
+            Minimum number of observations needed to have a valid result.
+
+        Returns
+        -------
+        float
+            Correlation with other.
+
+        See Also
+        --------
+        DataFrame.corr : Compute pairwise correlation between columns.
+        DataFrame.corrwith : Compute pairwise correlation with another
+            DataFrame or Series.
+
+        Notes
+        -----
+        Pearson, Kendall and Spearman correlation are currently computed using pairwise complete observations.
+
+        * `Pearson correlation coefficient `_
+        * `Kendall rank correlation coefficient `_
+        * `Spearman's rank correlation coefficient `_
+
+        Automatic data alignment: as with all pandas operations, automatic data alignment is performed for this method.
+        ``corr()`` automatically considers values with matching indices.
+
+        Examples
+        --------
+        >>> def histogram_intersection(a, b):
+        ...     v = np.minimum(a, b).sum().round(decimals=1)
+        ...     return v
+        >>> s1 = pd.Series([.2, .0, .6, .2])
+        >>> s2 = pd.Series([.3, .6, .0, .1])
+        >>> s1.corr(s2, method=histogram_intersection)
+        0.3
+
+        Pandas auto-aligns the values with matching indices
+
+        >>> s1 = pd.Series([1, 2, 3], index=[0, 1, 2])
+        >>> s2 = pd.Series([1, 2, 3], index=[2, 1, 0])
+        >>> s1.corr(s2)
+        -1.0
+        """  # noqa: E501
+        this, other = self.align(other, join="inner", copy=False)
+        if len(this) == 0:
+            return np.nan
+
+        this_values = this.to_numpy(dtype=float, na_value=np.nan, copy=False)
+        other_values = other.to_numpy(dtype=float, na_value=np.nan, copy=False)
+
+        if method in ["pearson", "spearman", "kendall"] or callable(method):
+            return nanops.nancorr(
+                this_values, other_values, method=method, min_periods=min_periods
+            )
+
+        raise ValueError(
+            "method must be either 'pearson', "
+            "'spearman', 'kendall', or a callable, "
+            f"'{method}' was supplied"
+        )
+
+    def cov(
+        self,
+        other: Series,
+        min_periods: int | None = None,
+        ddof: int | None = 1,
+    ) -> float:
+        """
+        Compute covariance with Series, excluding missing values.
+
+        The two `Series` objects are not required to be the same length and
+        will be aligned internally before the covariance is calculated.
+
+        Parameters
+        ----------
+        other : Series
+            Series with which to compute the covariance.
+        min_periods : int, optional
+            Minimum number of observations needed to have a valid result.
+        ddof : int, default 1
+            Delta degrees of freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+
+        Returns
+        -------
+        float
+            Covariance between Series and other normalized by N-1
+            (unbiased estimator).
+
+        See Also
+        --------
+        DataFrame.cov : Compute pairwise covariance of columns.
+
+        Examples
+        --------
+        >>> s1 = pd.Series([0.90010907, 0.13484424, 0.62036035])
+        >>> s2 = pd.Series([0.12528585, 0.26962463, 0.51111198])
+        >>> s1.cov(s2)
+        -0.01685762652715874
+        """
+        this, other = self.align(other, join="inner", copy=False)
+        if len(this) == 0:
+            return np.nan
+        this_values = this.to_numpy(dtype=float, na_value=np.nan, copy=False)
+        other_values = other.to_numpy(dtype=float, na_value=np.nan, copy=False)
+        return nanops.nancov(
+            this_values, other_values, min_periods=min_periods, ddof=ddof
+        )
+
+    @doc(
+        klass="Series",
+        extra_params="",
+        other_klass="DataFrame",
+        examples=dedent(
+            """
+        Difference with previous row
+
+        >>> s = pd.Series([1, 1, 2, 3, 5, 8])
+        >>> s.diff()
+        0    NaN
+        1    0.0
+        2    1.0
+        3    1.0
+        4    2.0
+        5    3.0
+        dtype: float64
+
+        Difference with 3rd previous row
+
+        >>> s.diff(periods=3)
+        0    NaN
+        1    NaN
+        2    NaN
+        3    2.0
+        4    4.0
+        5    6.0
+        dtype: float64
+
+        Difference with following row
+
+        >>> s.diff(periods=-1)
+        0    0.0
+        1   -1.0
+        2   -1.0
+        3   -2.0
+        4   -3.0
+        5    NaN
+        dtype: float64
+
+        Overflow in input dtype
+
+        >>> s = pd.Series([1, 0], dtype=np.uint8)
+        >>> s.diff()
+        0      NaN
+        1    255.0
+        dtype: float64"""
+        ),
+    )
+    def diff(self, periods: int = 1) -> Series:
+        """
+        First discrete difference of element.
+
+        Calculates the difference of a {klass} element compared with another
+        element in the {klass} (default is element in previous row).
+
+        Parameters
+        ----------
+        periods : int, default 1
+            Periods to shift for calculating difference, accepts negative
+            values.
+        {extra_params}
+        Returns
+        -------
+        {klass}
+            First differences of the Series.
+
+        See Also
+        --------
+        {klass}.pct_change: Percent change over given number of periods.
+        {klass}.shift: Shift index by desired number of periods with an
+            optional time freq.
+        {other_klass}.diff: First discrete difference of object.
+
+        Notes
+        -----
+        For boolean dtypes, this uses :meth:`operator.xor` rather than
+        :meth:`operator.sub`.
+        The result is calculated according to current dtype in {klass},
+        however dtype of the result is always float64.
+
+        Examples
+        --------
+        {examples}
+        """
+        result = algorithms.diff(self._values, periods)
+        return self._constructor(result, index=self.index, copy=False).__finalize__(
+            self, method="diff"
+        )
+
+    def autocorr(self, lag: int = 1) -> float:
+        """
+        Compute the lag-N autocorrelation.
+
+        This method computes the Pearson correlation between
+        the Series and its shifted self.
+
+        Parameters
+        ----------
+        lag : int, default 1
+            Number of lags to apply before performing autocorrelation.
+
+        Returns
+        -------
+        float
+            The Pearson correlation between self and self.shift(lag).
+
+        See Also
+        --------
+        Series.corr : Compute the correlation between two Series.
+        Series.shift : Shift index by desired number of periods.
+        DataFrame.corr : Compute pairwise correlation of columns.
+        DataFrame.corrwith : Compute pairwise correlation between rows or
+            columns of two DataFrame objects.
+
+        Notes
+        -----
+        If the Pearson correlation is not well defined return 'NaN'.
+
+        Examples
+        --------
+        >>> s = pd.Series([0.25, 0.5, 0.2, -0.05])
+        >>> s.autocorr()  # doctest: +ELLIPSIS
+        0.10355...
+        >>> s.autocorr(lag=2)  # doctest: +ELLIPSIS
+        -0.99999...
+
+        If the Pearson correlation is not well defined, then 'NaN' is returned.
+
+        >>> s = pd.Series([1, 0, 0, 0])
+        >>> s.autocorr()
+        nan
+        """
+        return self.corr(cast(Series, self.shift(lag)))
+
+    def dot(self, other: AnyArrayLike) -> Series | np.ndarray:
+        """
+        Compute the dot product between the Series and the columns of other.
+
+        This method computes the dot product between the Series and another
+        one, or the Series and each columns of a DataFrame, or the Series and
+        each columns of an array.
+
+        It can also be called using `self @ other`.
+
+        Parameters
+        ----------
+        other : Series, DataFrame or array-like
+            The other object to compute the dot product with its columns.
+
+        Returns
+        -------
+        scalar, Series or numpy.ndarray
+            Return the dot product of the Series and other if other is a
+            Series, the Series of the dot product of Series and each rows of
+            other if other is a DataFrame or a numpy.ndarray between the Series
+            and each columns of the numpy array.
+
+        See Also
+        --------
+        DataFrame.dot: Compute the matrix product with the DataFrame.
+        Series.mul: Multiplication of series and other, element-wise.
+
+        Notes
+        -----
+        The Series and other has to share the same index if other is a Series
+        or a DataFrame.
+
+        Examples
+        --------
+        >>> s = pd.Series([0, 1, 2, 3])
+        >>> other = pd.Series([-1, 2, -3, 4])
+        >>> s.dot(other)
+        8
+        >>> s @ other
+        8
+        >>> df = pd.DataFrame([[0, 1], [-2, 3], [4, -5], [6, 7]])
+        >>> s.dot(df)
+        0    24
+        1    14
+        dtype: int64
+        >>> arr = np.array([[0, 1], [-2, 3], [4, -5], [6, 7]])
+        >>> s.dot(arr)
+        array([24, 14])
+        """
+        if isinstance(other, (Series, ABCDataFrame)):
+            common = self.index.union(other.index)
+            if len(common) > len(self.index) or len(common) > len(other.index):
+                raise ValueError("matrices are not aligned")
+
+            left = self.reindex(index=common, copy=False)
+            right = other.reindex(index=common, copy=False)
+            lvals = left.values
+            rvals = right.values
+        else:
+            lvals = self.values
+            rvals = np.asarray(other)
+            if lvals.shape[0] != rvals.shape[0]:
+                raise Exception(
+                    f"Dot product shape mismatch, {lvals.shape} vs {rvals.shape}"
+                )
+
+        if isinstance(other, ABCDataFrame):
+            return self._constructor(
+                np.dot(lvals, rvals), index=other.columns, copy=False
+            ).__finalize__(self, method="dot")
+        elif isinstance(other, Series):
+            return np.dot(lvals, rvals)
+        elif isinstance(rvals, np.ndarray):
+            return np.dot(lvals, rvals)
+        else:  # pragma: no cover
+            raise TypeError(f"unsupported type: {type(other)}")
+
+    def __matmul__(self, other):
+        """
+        Matrix multiplication using binary `@` operator.
+        """
+        return self.dot(other)
+
+    def __rmatmul__(self, other):
+        """
+        Matrix multiplication using binary `@` operator.
+        """
+        return self.dot(np.transpose(other))
+
+    @doc(base.IndexOpsMixin.searchsorted, klass="Series")
+    # Signature of "searchsorted" incompatible with supertype "IndexOpsMixin"
+    def searchsorted(  # type: ignore[override]
+        self,
+        value: NumpyValueArrayLike | ExtensionArray,
+        side: Literal["left", "right"] = "left",
+        sorter: NumpySorter | None = None,
+    ) -> npt.NDArray[np.intp] | np.intp:
+        return base.IndexOpsMixin.searchsorted(self, value, side=side, sorter=sorter)
+
+    # -------------------------------------------------------------------
+    # Combination
+
+    def _append(
+        self, to_append, ignore_index: bool = False, verify_integrity: bool = False
+    ):
+        from pandas.core.reshape.concat import concat
+
+        if isinstance(to_append, (list, tuple)):
+            to_concat = [self]
+            to_concat.extend(to_append)
+        else:
+            to_concat = [self, to_append]
+        if any(isinstance(x, (ABCDataFrame,)) for x in to_concat[1:]):
+            msg = "to_append should be a Series or list/tuple of Series, got DataFrame"
+            raise TypeError(msg)
+        return concat(
+            to_concat, ignore_index=ignore_index, verify_integrity=verify_integrity
+        )
+
+    @doc(
+        _shared_docs["compare"],
+        dedent(
+            """
+        Returns
+        -------
+        Series or DataFrame
+            If axis is 0 or 'index' the result will be a Series.
+            The resulting index will be a MultiIndex with 'self' and 'other'
+            stacked alternately at the inner level.
+
+            If axis is 1 or 'columns' the result will be a DataFrame.
+            It will have two columns namely 'self' and 'other'.
+
+        See Also
+        --------
+        DataFrame.compare : Compare with another DataFrame and show differences.
+
+        Notes
+        -----
+        Matching NaNs will not appear as a difference.
+
+        Examples
+        --------
+        >>> s1 = pd.Series(["a", "b", "c", "d", "e"])
+        >>> s2 = pd.Series(["a", "a", "c", "b", "e"])
+
+        Align the differences on columns
+
+        >>> s1.compare(s2)
+          self other
+        1    b     a
+        3    d     b
+
+        Stack the differences on indices
+
+        >>> s1.compare(s2, align_axis=0)
+        1  self     b
+           other    a
+        3  self     d
+           other    b
+        dtype: object
+
+        Keep all original rows
+
+        >>> s1.compare(s2, keep_shape=True)
+          self other
+        0  NaN   NaN
+        1    b     a
+        2  NaN   NaN
+        3    d     b
+        4  NaN   NaN
+
+        Keep all original rows and also all original values
+
+        >>> s1.compare(s2, keep_shape=True, keep_equal=True)
+          self other
+        0    a     a
+        1    b     a
+        2    c     c
+        3    d     b
+        4    e     e
+        """
+        ),
+        klass=_shared_doc_kwargs["klass"],
+    )
+    def compare(
+        self,
+        other: Series,
+        align_axis: Axis = 1,
+        keep_shape: bool = False,
+        keep_equal: bool = False,
+        result_names: Suffixes = ("self", "other"),
+    ) -> DataFrame | Series:
+        return super().compare(
+            other=other,
+            align_axis=align_axis,
+            keep_shape=keep_shape,
+            keep_equal=keep_equal,
+            result_names=result_names,
+        )
+
+    def combine(
+        self,
+        other: Series | Hashable,
+        func: Callable[[Hashable, Hashable], Hashable],
+        fill_value: Hashable | None = None,
+    ) -> Series:
+        """
+        Combine the Series with a Series or scalar according to `func`.
+
+        Combine the Series and `other` using `func` to perform elementwise
+        selection for combined Series.
+        `fill_value` is assumed when value is missing at some index
+        from one of the two objects being combined.
+
+        Parameters
+        ----------
+        other : Series or scalar
+            The value(s) to be combined with the `Series`.
+        func : function
+            Function that takes two scalars as inputs and returns an element.
+        fill_value : scalar, optional
+            The value to assume when an index is missing from
+            one Series or the other. The default specifies to use the
+            appropriate NaN value for the underlying dtype of the Series.
+
+        Returns
+        -------
+        Series
+            The result of combining the Series with the other object.
+
+        See Also
+        --------
+        Series.combine_first : Combine Series values, choosing the calling
+            Series' values first.
+
+        Examples
+        --------
+        Consider 2 Datasets ``s1`` and ``s2`` containing
+        highest clocked speeds of different birds.
+
+        >>> s1 = pd.Series({'falcon': 330.0, 'eagle': 160.0})
+        >>> s1
+        falcon    330.0
+        eagle     160.0
+        dtype: float64
+        >>> s2 = pd.Series({'falcon': 345.0, 'eagle': 200.0, 'duck': 30.0})
+        >>> s2
+        falcon    345.0
+        eagle     200.0
+        duck       30.0
+        dtype: float64
+
+        Now, to combine the two datasets and view the highest speeds
+        of the birds across the two datasets
+
+        >>> s1.combine(s2, max)
+        duck        NaN
+        eagle     200.0
+        falcon    345.0
+        dtype: float64
+
+        In the previous example, the resulting value for duck is missing,
+        because the maximum of a NaN and a float is a NaN.
+        So, in the example, we set ``fill_value=0``,
+        so the maximum value returned will be the value from some dataset.
+
+        >>> s1.combine(s2, max, fill_value=0)
+        duck       30.0
+        eagle     200.0
+        falcon    345.0
+        dtype: float64
+        """
+        if fill_value is None:
+            fill_value = na_value_for_dtype(self.dtype, compat=False)
+
+        if isinstance(other, Series):
+            # If other is a Series, result is based on union of Series,
+            # so do this element by element
+            new_index = self.index.union(other.index)
+            new_name = ops.get_op_result_name(self, other)
+            new_values = np.empty(len(new_index), dtype=object)
+            with np.errstate(all="ignore"):
+                for i, idx in enumerate(new_index):
+                    lv = self.get(idx, fill_value)
+                    rv = other.get(idx, fill_value)
+                    new_values[i] = func(lv, rv)
+        else:
+            # Assume that other is a scalar, so apply the function for
+            # each element in the Series
+            new_index = self.index
+            new_values = np.empty(len(new_index), dtype=object)
+            with np.errstate(all="ignore"):
+                new_values[:] = [func(lv, other) for lv in self._values]
+            new_name = self.name
+
+        # try_float=False is to match agg_series
+        npvalues = lib.maybe_convert_objects(new_values, try_float=False)
+        # same_dtype here is a kludge to avoid casting e.g. [True, False] to
+        #  ["True", "False"]
+        same_dtype = isinstance(self.dtype, (StringDtype, CategoricalDtype))
+        res_values = maybe_cast_pointwise_result(
+            npvalues, self.dtype, same_dtype=same_dtype
+        )
+        return self._constructor(res_values, index=new_index, name=new_name, copy=False)
+
+    def combine_first(self, other) -> Series:
+        """
+        Update null elements with value in the same location in 'other'.
+
+        Combine two Series objects by filling null values in one Series with
+        non-null values from the other Series. Result index will be the union
+        of the two indexes.
+
+        Parameters
+        ----------
+        other : Series
+            The value(s) to be used for filling null values.
+
+        Returns
+        -------
+        Series
+            The result of combining the provided Series with the other object.
+
+        See Also
+        --------
+        Series.combine : Perform element-wise operation on two Series
+            using a given function.
+
+        Examples
+        --------
+        >>> s1 = pd.Series([1, np.nan])
+        >>> s2 = pd.Series([3, 4, 5])
+        >>> s1.combine_first(s2)
+        0    1.0
+        1    4.0
+        2    5.0
+        dtype: float64
+
+        Null values still persist if the location of that null value
+        does not exist in `other`
+
+        >>> s1 = pd.Series({'falcon': np.nan, 'eagle': 160.0})
+        >>> s2 = pd.Series({'eagle': 200.0, 'duck': 30.0})
+        >>> s1.combine_first(s2)
+        duck       30.0
+        eagle     160.0
+        falcon      NaN
+        dtype: float64
+        """
+        from pandas.core.reshape.concat import concat
+
+        if self.dtype == other.dtype:
+            if self.index.equals(other.index):
+                return self.mask(self.isna(), other)
+            elif self._can_hold_na and not isinstance(self.dtype, SparseDtype):
+                this, other = self.align(other, join="outer")
+                return this.mask(this.isna(), other)
+
+        new_index = self.index.union(other.index)
+
+        this = self
+        # identify the index subset to keep for each series
+        keep_other = other.index.difference(this.index[notna(this)])
+        keep_this = this.index.difference(keep_other)
+
+        this = this.reindex(keep_this, copy=False)
+        other = other.reindex(keep_other, copy=False)
+
+        if this.dtype.kind == "M" and other.dtype.kind != "M":
+            other = to_datetime(other)
+        combined = concat([this, other])
+        combined = combined.reindex(new_index, copy=False)
+        return combined.__finalize__(self, method="combine_first")
+
+    def update(self, other: Series | Sequence | Mapping) -> None:
+        """
+        Modify Series in place using values from passed Series.
+
+        Uses non-NA values from passed Series to make updates. Aligns
+        on index.
+
+        Parameters
+        ----------
+        other : Series, or object coercible into Series
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.update(pd.Series([4, 5, 6]))
+        >>> s
+        0    4
+        1    5
+        2    6
+        dtype: int64
+
+        >>> s = pd.Series(['a', 'b', 'c'])
+        >>> s.update(pd.Series(['d', 'e'], index=[0, 2]))
+        >>> s
+        0    d
+        1    b
+        2    e
+        dtype: object
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.update(pd.Series([4, 5, 6, 7, 8]))
+        >>> s
+        0    4
+        1    5
+        2    6
+        dtype: int64
+
+        If ``other`` contains NaNs the corresponding values are not updated
+        in the original Series.
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.update(pd.Series([4, np.nan, 6]))
+        >>> s
+        0    4
+        1    2
+        2    6
+        dtype: int64
+
+        ``other`` can also be a non-Series object type
+        that is coercible into a Series
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.update([4, np.nan, 6])
+        >>> s
+        0    4
+        1    2
+        2    6
+        dtype: int64
+
+        >>> s = pd.Series([1, 2, 3])
+        >>> s.update({1: 9})
+        >>> s
+        0    1
+        1    9
+        2    3
+        dtype: int64
+        """
+        if not PYPY and not WARNING_CHECK_DISABLED and using_copy_on_write():
+            if sys.getrefcount(self) <= REF_COUNT:
+                warnings.warn(
+                    _chained_assignment_method_msg,
+                    ChainedAssignmentError,
+                    stacklevel=2,
+                )
+        elif (
+            not PYPY
+            and not WARNING_CHECK_DISABLED
+            and not using_copy_on_write()
+            and self._is_view_after_cow_rules()
+        ):
+            ctr = sys.getrefcount(self)
+            ref_count = REF_COUNT
+            if _check_cacher(self):
+                # see https://github.com/pandas-dev/pandas/pull/56060#discussion_r1399245221
+                ref_count += 1
+            if ctr <= ref_count:
+                warnings.warn(
+                    _chained_assignment_warning_method_msg,
+                    FutureWarning,
+                    stacklevel=2,
+                )
+
+        if not isinstance(other, Series):
+            other = Series(other)
+
+        other = other.reindex_like(self)
+        mask = notna(other)
+
+        self._mgr = self._mgr.putmask(mask=mask, new=other)
+        self._maybe_update_cacher()
+
+    # ----------------------------------------------------------------------
+    # Reindexing, sorting
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool = ...,
+        key: ValueKeyFunc = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool = ...,
+        key: ValueKeyFunc = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def sort_values(
+        self,
+        *,
+        axis: Axis = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: bool = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        ignore_index: bool = ...,
+        key: ValueKeyFunc = ...,
+    ) -> Series | None:
+        ...
+
+    def sort_values(
+        self,
+        *,
+        axis: Axis = 0,
+        ascending: bool | Sequence[bool] = True,
+        inplace: bool = False,
+        kind: SortKind = "quicksort",
+        na_position: NaPosition = "last",
+        ignore_index: bool = False,
+        key: ValueKeyFunc | None = None,
+    ) -> Series | None:
+        """
+        Sort by the values.
+
+        Sort a Series in ascending or descending order by some
+        criterion.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        ascending : bool or list of bools, default True
+            If True, sort values in ascending order, otherwise descending.
+        inplace : bool, default False
+            If True, perform operation in-place.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+            Choice of sorting algorithm. See also :func:`numpy.sort` for more
+            information. 'mergesort' and 'stable' are the only stable  algorithms.
+        na_position : {'first' or 'last'}, default 'last'
+            Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
+            the end.
+        ignore_index : bool, default False
+            If True, the resulting axis will be labeled 0, 1, …, n - 1.
+        key : callable, optional
+            If not None, apply the key function to the series values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect a
+            ``Series`` and return an array-like.
+
+        Returns
+        -------
+        Series or None
+            Series ordered by values or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.sort_index : Sort by the Series indices.
+        DataFrame.sort_values : Sort DataFrame by the values along either axis.
+        DataFrame.sort_index : Sort DataFrame by indices.
+
+        Examples
+        --------
+        >>> s = pd.Series([np.nan, 1, 3, 10, 5])
+        >>> s
+        0     NaN
+        1     1.0
+        2     3.0
+        3     10.0
+        4     5.0
+        dtype: float64
+
+        Sort values ascending order (default behaviour)
+
+        >>> s.sort_values(ascending=True)
+        1     1.0
+        2     3.0
+        4     5.0
+        3    10.0
+        0     NaN
+        dtype: float64
+
+        Sort values descending order
+
+        >>> s.sort_values(ascending=False)
+        3    10.0
+        4     5.0
+        2     3.0
+        1     1.0
+        0     NaN
+        dtype: float64
+
+        Sort values putting NAs first
+
+        >>> s.sort_values(na_position='first')
+        0     NaN
+        1     1.0
+        2     3.0
+        4     5.0
+        3    10.0
+        dtype: float64
+
+        Sort a series of strings
+
+        >>> s = pd.Series(['z', 'b', 'd', 'a', 'c'])
+        >>> s
+        0    z
+        1    b
+        2    d
+        3    a
+        4    c
+        dtype: object
+
+        >>> s.sort_values()
+        3    a
+        1    b
+        4    c
+        2    d
+        0    z
+        dtype: object
+
+        Sort using a key function. Your `key` function will be
+        given the ``Series`` of values and should return an array-like.
+
+        >>> s = pd.Series(['a', 'B', 'c', 'D', 'e'])
+        >>> s.sort_values()
+        1    B
+        3    D
+        0    a
+        2    c
+        4    e
+        dtype: object
+        >>> s.sort_values(key=lambda x: x.str.lower())
+        0    a
+        1    B
+        2    c
+        3    D
+        4    e
+        dtype: object
+
+        NumPy ufuncs work well here. For example, we can
+        sort by the ``sin`` of the value
+
+        >>> s = pd.Series([-4, -2, 0, 2, 4])
+        >>> s.sort_values(key=np.sin)
+        1   -2
+        4    4
+        2    0
+        0   -4
+        3    2
+        dtype: int64
+
+        More complicated user-defined functions can be used,
+        as long as they expect a Series and return an array-like
+
+        >>> s.sort_values(key=lambda x: (np.tan(x.cumsum())))
+        0   -4
+        3    2
+        4    4
+        1   -2
+        2    0
+        dtype: int64
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        # Validate the axis parameter
+        self._get_axis_number(axis)
+
+        # GH 5856/5853
+        if inplace and self._is_cached:
+            raise ValueError(
+                "This Series is a view of some other array, to "
+                "sort in-place you must create a copy"
+            )
+
+        if is_list_like(ascending):
+            ascending = cast(Sequence[bool], ascending)
+            if len(ascending) != 1:
+                raise ValueError(
+                    f"Length of ascending ({len(ascending)}) must be 1 for Series"
+                )
+            ascending = ascending[0]
+
+        ascending = validate_ascending(ascending)
+
+        if na_position not in ["first", "last"]:
+            raise ValueError(f"invalid na_position: {na_position}")
+
+        # GH 35922. Make sorting stable by leveraging nargsort
+        if key:
+            values_to_sort = cast(Series, ensure_key_mapped(self, key))._values
+        else:
+            values_to_sort = self._values
+        sorted_index = nargsort(values_to_sort, kind, bool(ascending), na_position)
+
+        if is_range_indexer(sorted_index, len(sorted_index)):
+            if inplace:
+                return self._update_inplace(self)
+            return self.copy(deep=None)
+
+        result = self._constructor(
+            self._values[sorted_index], index=self.index[sorted_index], copy=False
+        )
+
+        if ignore_index:
+            result.index = default_index(len(sorted_index))
+
+        if not inplace:
+            return result.__finalize__(self, method="sort_values")
+        self._update_inplace(result)
+        return None
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[True],
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: Literal[False] = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def sort_index(
+        self,
+        *,
+        axis: Axis = ...,
+        level: IndexLabel = ...,
+        ascending: bool | Sequence[bool] = ...,
+        inplace: bool = ...,
+        kind: SortKind = ...,
+        na_position: NaPosition = ...,
+        sort_remaining: bool = ...,
+        ignore_index: bool = ...,
+        key: IndexKeyFunc = ...,
+    ) -> Series | None:
+        ...
+
+    def sort_index(
+        self,
+        *,
+        axis: Axis = 0,
+        level: IndexLabel | None = None,
+        ascending: bool | Sequence[bool] = True,
+        inplace: bool = False,
+        kind: SortKind = "quicksort",
+        na_position: NaPosition = "last",
+        sort_remaining: bool = True,
+        ignore_index: bool = False,
+        key: IndexKeyFunc | None = None,
+    ) -> Series | None:
+        """
+        Sort Series by index labels.
+
+        Returns a new Series sorted by label if `inplace` argument is
+        ``False``, otherwise updates the original series and returns None.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        level : int, optional
+            If not None, sort on values in specified index level(s).
+        ascending : bool or list-like of bools, default True
+            Sort ascending vs. descending. When the index is a MultiIndex the
+            sort direction can be controlled for each level individually.
+        inplace : bool, default False
+            If True, perform operation in-place.
+        kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+            Choice of sorting algorithm. See also :func:`numpy.sort` for more
+            information. 'mergesort' and 'stable' are the only stable algorithms. For
+            DataFrames, this option is only applied when sorting on a single
+            column or label.
+        na_position : {'first', 'last'}, default 'last'
+            If 'first' puts NaNs at the beginning, 'last' puts NaNs at the end.
+            Not implemented for MultiIndex.
+        sort_remaining : bool, default True
+            If True and sorting by level and index is multilevel, sort by other
+            levels too (in order) after sorting by specified level.
+        ignore_index : bool, default False
+            If True, the resulting axis will be labeled 0, 1, …, n - 1.
+        key : callable, optional
+            If not None, apply the key function to the index values
+            before sorting. This is similar to the `key` argument in the
+            builtin :meth:`sorted` function, with the notable difference that
+            this `key` function should be *vectorized*. It should expect an
+            ``Index`` and return an ``Index`` of the same shape.
+
+        Returns
+        -------
+        Series or None
+            The original Series sorted by the labels or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.sort_index: Sort DataFrame by the index.
+        DataFrame.sort_values: Sort DataFrame by the value.
+        Series.sort_values : Sort Series by the value.
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c', 'd'], index=[3, 2, 1, 4])
+        >>> s.sort_index()
+        1    c
+        2    b
+        3    a
+        4    d
+        dtype: object
+
+        Sort Descending
+
+        >>> s.sort_index(ascending=False)
+        4    d
+        3    a
+        2    b
+        1    c
+        dtype: object
+
+        By default NaNs are put at the end, but use `na_position` to place
+        them at the beginning
+
+        >>> s = pd.Series(['a', 'b', 'c', 'd'], index=[3, 2, 1, np.nan])
+        >>> s.sort_index(na_position='first')
+        NaN     d
+         1.0    c
+         2.0    b
+         3.0    a
+        dtype: object
+
+        Specify index level to sort
+
+        >>> arrays = [np.array(['qux', 'qux', 'foo', 'foo',
+        ...                     'baz', 'baz', 'bar', 'bar']),
+        ...           np.array(['two', 'one', 'two', 'one',
+        ...                     'two', 'one', 'two', 'one'])]
+        >>> s = pd.Series([1, 2, 3, 4, 5, 6, 7, 8], index=arrays)
+        >>> s.sort_index(level=1)
+        bar  one    8
+        baz  one    6
+        foo  one    4
+        qux  one    2
+        bar  two    7
+        baz  two    5
+        foo  two    3
+        qux  two    1
+        dtype: int64
+
+        Does not sort by remaining levels when sorting by levels
+
+        >>> s.sort_index(level=1, sort_remaining=False)
+        qux  one    2
+        foo  one    4
+        baz  one    6
+        bar  one    8
+        qux  two    1
+        foo  two    3
+        baz  two    5
+        bar  two    7
+        dtype: int64
+
+        Apply a key function before sorting
+
+        >>> s = pd.Series([1, 2, 3, 4], index=['A', 'b', 'C', 'd'])
+        >>> s.sort_index(key=lambda x : x.str.lower())
+        A    1
+        b    2
+        C    3
+        d    4
+        dtype: int64
+        """
+
+        return super().sort_index(
+            axis=axis,
+            level=level,
+            ascending=ascending,
+            inplace=inplace,
+            kind=kind,
+            na_position=na_position,
+            sort_remaining=sort_remaining,
+            ignore_index=ignore_index,
+            key=key,
+        )
+
+    def argsort(
+        self,
+        axis: Axis = 0,
+        kind: SortKind = "quicksort",
+        order: None = None,
+        stable: None = None,
+    ) -> Series:
+        """
+        Return the integer indices that would sort the Series values.
+
+        Override ndarray.argsort. Argsorts the value, omitting NA/null values,
+        and places the result in the same locations as the non-NA values.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        kind : {'mergesort', 'quicksort', 'heapsort', 'stable'}, default 'quicksort'
+            Choice of sorting algorithm. See :func:`numpy.sort` for more
+            information. 'mergesort' and 'stable' are the only stable algorithms.
+        order : None
+            Has no effect but is accepted for compatibility with numpy.
+        stable : None
+            Has no effect but is accepted for compatibility with numpy.
+
+        Returns
+        -------
+        Series[np.intp]
+            Positions of values within the sort order with -1 indicating
+            nan values.
+
+        See Also
+        --------
+        numpy.ndarray.argsort : Returns the indices that would sort this array.
+
+        Examples
+        --------
+        >>> s = pd.Series([3, 2, 1])
+        >>> s.argsort()
+        0    2
+        1    1
+        2    0
+        dtype: int64
+        """
+        if axis != -1:
+            # GH#54257 We allow -1 here so that np.argsort(series) works
+            self._get_axis_number(axis)
+
+        values = self._values
+        mask = isna(values)
+
+        if mask.any():
+            # TODO(3.0): once this deprecation is enforced we can call
+            #  self.array.argsort directly, which will close GH#43840 and
+            #  GH#12694
+            warnings.warn(
+                "The behavior of Series.argsort in the presence of NA values is "
+                "deprecated. In a future version, NA values will be ordered "
+                "last instead of set to -1.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+            result = np.full(len(self), -1, dtype=np.intp)
+            notmask = ~mask
+            result[notmask] = np.argsort(values[notmask], kind=kind)
+        else:
+            result = np.argsort(values, kind=kind)
+
+        res = self._constructor(
+            result, index=self.index, name=self.name, dtype=np.intp, copy=False
+        )
+        return res.__finalize__(self, method="argsort")
+
+    def nlargest(
+        self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
+    ) -> Series:
+        """
+        Return the largest `n` elements.
+
+        Parameters
+        ----------
+        n : int, default 5
+            Return this many descending sorted values.
+        keep : {'first', 'last', 'all'}, default 'first'
+            When there are duplicate values that cannot all fit in a
+            Series of `n` elements:
+
+            - ``first`` : return the first `n` occurrences in order
+              of appearance.
+            - ``last`` : return the last `n` occurrences in reverse
+              order of appearance.
+            - ``all`` : keep all occurrences. This can result in a Series of
+              size larger than `n`.
+
+        Returns
+        -------
+        Series
+            The `n` largest values in the Series, sorted in decreasing order.
+
+        See Also
+        --------
+        Series.nsmallest: Get the `n` smallest elements.
+        Series.sort_values: Sort Series by values.
+        Series.head: Return the first `n` rows.
+
+        Notes
+        -----
+        Faster than ``.sort_values(ascending=False).head(n)`` for small `n`
+        relative to the size of the ``Series`` object.
+
+        Examples
+        --------
+        >>> countries_population = {"Italy": 59000000, "France": 65000000,
+        ...                         "Malta": 434000, "Maldives": 434000,
+        ...                         "Brunei": 434000, "Iceland": 337000,
+        ...                         "Nauru": 11300, "Tuvalu": 11300,
+        ...                         "Anguilla": 11300, "Montserrat": 5200}
+        >>> s = pd.Series(countries_population)
+        >>> s
+        Italy       59000000
+        France      65000000
+        Malta         434000
+        Maldives      434000
+        Brunei        434000
+        Iceland       337000
+        Nauru          11300
+        Tuvalu         11300
+        Anguilla       11300
+        Montserrat      5200
+        dtype: int64
+
+        The `n` largest elements where ``n=5`` by default.
+
+        >>> s.nlargest()
+        France      65000000
+        Italy       59000000
+        Malta         434000
+        Maldives      434000
+        Brunei        434000
+        dtype: int64
+
+        The `n` largest elements where ``n=3``. Default `keep` value is 'first'
+        so Malta will be kept.
+
+        >>> s.nlargest(3)
+        France    65000000
+        Italy     59000000
+        Malta       434000
+        dtype: int64
+
+        The `n` largest elements where ``n=3`` and keeping the last duplicates.
+        Brunei will be kept since it is the last with value 434000 based on
+        the index order.
+
+        >>> s.nlargest(3, keep='last')
+        France      65000000
+        Italy       59000000
+        Brunei        434000
+        dtype: int64
+
+        The `n` largest elements where ``n=3`` with all duplicates kept. Note
+        that the returned Series has five elements due to the three duplicates.
+
+        >>> s.nlargest(3, keep='all')
+        France      65000000
+        Italy       59000000
+        Malta         434000
+        Maldives      434000
+        Brunei        434000
+        dtype: int64
+        """
+        return selectn.SelectNSeries(self, n=n, keep=keep).nlargest()
+
+    def nsmallest(
+        self, n: int = 5, keep: Literal["first", "last", "all"] = "first"
+    ) -> Series:
+        """
+        Return the smallest `n` elements.
+
+        Parameters
+        ----------
+        n : int, default 5
+            Return this many ascending sorted values.
+        keep : {'first', 'last', 'all'}, default 'first'
+            When there are duplicate values that cannot all fit in a
+            Series of `n` elements:
+
+            - ``first`` : return the first `n` occurrences in order
+              of appearance.
+            - ``last`` : return the last `n` occurrences in reverse
+              order of appearance.
+            - ``all`` : keep all occurrences. This can result in a Series of
+              size larger than `n`.
+
+        Returns
+        -------
+        Series
+            The `n` smallest values in the Series, sorted in increasing order.
+
+        See Also
+        --------
+        Series.nlargest: Get the `n` largest elements.
+        Series.sort_values: Sort Series by values.
+        Series.head: Return the first `n` rows.
+
+        Notes
+        -----
+        Faster than ``.sort_values().head(n)`` for small `n` relative to
+        the size of the ``Series`` object.
+
+        Examples
+        --------
+        >>> countries_population = {"Italy": 59000000, "France": 65000000,
+        ...                         "Brunei": 434000, "Malta": 434000,
+        ...                         "Maldives": 434000, "Iceland": 337000,
+        ...                         "Nauru": 11300, "Tuvalu": 11300,
+        ...                         "Anguilla": 11300, "Montserrat": 5200}
+        >>> s = pd.Series(countries_population)
+        >>> s
+        Italy       59000000
+        France      65000000
+        Brunei        434000
+        Malta         434000
+        Maldives      434000
+        Iceland       337000
+        Nauru          11300
+        Tuvalu         11300
+        Anguilla       11300
+        Montserrat      5200
+        dtype: int64
+
+        The `n` smallest elements where ``n=5`` by default.
+
+        >>> s.nsmallest()
+        Montserrat    5200
+        Nauru        11300
+        Tuvalu       11300
+        Anguilla     11300
+        Iceland     337000
+        dtype: int64
+
+        The `n` smallest elements where ``n=3``. Default `keep` value is
+        'first' so Nauru and Tuvalu will be kept.
+
+        >>> s.nsmallest(3)
+        Montserrat   5200
+        Nauru       11300
+        Tuvalu      11300
+        dtype: int64
+
+        The `n` smallest elements where ``n=3`` and keeping the last
+        duplicates. Anguilla and Tuvalu will be kept since they are the last
+        with value 11300 based on the index order.
+
+        >>> s.nsmallest(3, keep='last')
+        Montserrat   5200
+        Anguilla    11300
+        Tuvalu      11300
+        dtype: int64
+
+        The `n` smallest elements where ``n=3`` with all duplicates kept. Note
+        that the returned Series has four elements due to the three duplicates.
+
+        >>> s.nsmallest(3, keep='all')
+        Montserrat   5200
+        Nauru       11300
+        Tuvalu      11300
+        Anguilla    11300
+        dtype: int64
+        """
+        return selectn.SelectNSeries(self, n=n, keep=keep).nsmallest()
+
+    @doc(
+        klass=_shared_doc_kwargs["klass"],
+        extra_params=dedent(
+            """copy : bool, default True
+            Whether to copy underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``"""
+        ),
+        examples=dedent(
+            """\
+        Examples
+        --------
+        >>> s = pd.Series(
+        ...     ["A", "B", "A", "C"],
+        ...     index=[
+        ...         ["Final exam", "Final exam", "Coursework", "Coursework"],
+        ...         ["History", "Geography", "History", "Geography"],
+        ...         ["January", "February", "March", "April"],
+        ...     ],
+        ... )
+        >>> s
+        Final exam  History     January      A
+                    Geography   February     B
+        Coursework  History     March        A
+                    Geography   April        C
+        dtype: object
+
+        In the following example, we will swap the levels of the indices.
+        Here, we will swap the levels column-wise, but levels can be swapped row-wise
+        in a similar manner. Note that column-wise is the default behaviour.
+        By not supplying any arguments for i and j, we swap the last and second to
+        last indices.
+
+        >>> s.swaplevel()
+        Final exam  January     History         A
+                    February    Geography       B
+        Coursework  March       History         A
+                    April       Geography       C
+        dtype: object
+
+        By supplying one argument, we can choose which index to swap the last
+        index with. We can for example swap the first index with the last one as
+        follows.
+
+        >>> s.swaplevel(0)
+        January     History     Final exam      A
+        February    Geography   Final exam      B
+        March       History     Coursework      A
+        April       Geography   Coursework      C
+        dtype: object
+
+        We can also define explicitly which indices we want to swap by supplying values
+        for both i and j. Here, we for example swap the first and second indices.
+
+        >>> s.swaplevel(0, 1)
+        History     Final exam  January         A
+        Geography   Final exam  February        B
+        History     Coursework  March           A
+        Geography   Coursework  April           C
+        dtype: object"""
+        ),
+    )
+    def swaplevel(
+        self, i: Level = -2, j: Level = -1, copy: bool | None = None
+    ) -> Series:
+        """
+        Swap levels i and j in a :class:`MultiIndex`.
+
+        Default is to swap the two innermost levels of the index.
+
+        Parameters
+        ----------
+        i, j : int or str
+            Levels of the indices to be swapped. Can pass level name as string.
+        {extra_params}
+
+        Returns
+        -------
+        {klass}
+            {klass} with levels swapped in MultiIndex.
+
+        {examples}
+        """
+        assert isinstance(self.index, MultiIndex)
+        result = self.copy(deep=copy and not using_copy_on_write())
+        result.index = self.index.swaplevel(i, j)
+        return result
+
+    def reorder_levels(self, order: Sequence[Level]) -> Series:
+        """
+        Rearrange index levels using input order.
+
+        May not drop or duplicate levels.
+
+        Parameters
+        ----------
+        order : list of int representing new level order
+            Reference level by number or key.
+
+        Returns
+        -------
+        type of caller (new object)
+
+        Examples
+        --------
+        >>> arrays = [np.array(["dog", "dog", "cat", "cat", "bird", "bird"]),
+        ...           np.array(["white", "black", "white", "black", "white", "black"])]
+        >>> s = pd.Series([1, 2, 3, 3, 5, 2], index=arrays)
+        >>> s
+        dog   white    1
+              black    2
+        cat   white    3
+              black    3
+        bird  white    5
+              black    2
+        dtype: int64
+        >>> s.reorder_levels([1, 0])
+        white  dog     1
+        black  dog     2
+        white  cat     3
+        black  cat     3
+        white  bird    5
+        black  bird    2
+        dtype: int64
+        """
+        if not isinstance(self.index, MultiIndex):  # pragma: no cover
+            raise Exception("Can only reorder levels on a hierarchical axis.")
+
+        result = self.copy(deep=None)
+        assert isinstance(result.index, MultiIndex)
+        result.index = result.index.reorder_levels(order)
+        return result
+
+    def explode(self, ignore_index: bool = False) -> Series:
+        """
+        Transform each element of a list-like to a row.
+
+        Parameters
+        ----------
+        ignore_index : bool, default False
+            If True, the resulting index will be labeled 0, 1, …, n - 1.
+
+        Returns
+        -------
+        Series
+            Exploded lists to rows; index will be duplicated for these rows.
+
+        See Also
+        --------
+        Series.str.split : Split string values on specified separator.
+        Series.unstack : Unstack, a.k.a. pivot, Series with MultiIndex
+            to produce DataFrame.
+        DataFrame.melt : Unpivot a DataFrame from wide format to long format.
+        DataFrame.explode : Explode a DataFrame from list-like
+            columns to long format.
+
+        Notes
+        -----
+        This routine will explode list-likes including lists, tuples, sets,
+        Series, and np.ndarray. The result dtype of the subset rows will
+        be object. Scalars will be returned unchanged, and empty list-likes will
+        result in a np.nan for that row. In addition, the ordering of elements in
+        the output will be non-deterministic when exploding sets.
+
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> s = pd.Series([[1, 2, 3], 'foo', [], [3, 4]])
+        >>> s
+        0    [1, 2, 3]
+        1          foo
+        2           []
+        3       [3, 4]
+        dtype: object
+
+        >>> s.explode()
+        0      1
+        0      2
+        0      3
+        1    foo
+        2    NaN
+        3      3
+        3      4
+        dtype: object
+        """
+        if isinstance(self.dtype, ExtensionDtype):
+            values, counts = self._values._explode()
+        elif len(self) and is_object_dtype(self.dtype):
+            values, counts = reshape.explode(np.asarray(self._values))
+        else:
+            result = self.copy()
+            return result.reset_index(drop=True) if ignore_index else result
+
+        if ignore_index:
+            index: Index = default_index(len(values))
+        else:
+            index = self.index.repeat(counts)
+
+        return self._constructor(values, index=index, name=self.name, copy=False)
+
+    def unstack(
+        self,
+        level: IndexLabel = -1,
+        fill_value: Hashable | None = None,
+        sort: bool = True,
+    ) -> DataFrame:
+        """
+        Unstack, also known as pivot, Series with MultiIndex to produce DataFrame.
+
+        Parameters
+        ----------
+        level : int, str, or list of these, default last level
+            Level(s) to unstack, can pass level name.
+        fill_value : scalar value, default None
+            Value to use when replacing NaN values.
+        sort : bool, default True
+            Sort the level(s) in the resulting MultiIndex columns.
+
+        Returns
+        -------
+        DataFrame
+            Unstacked Series.
+
+        Notes
+        -----
+        Reference :ref:`the user guide ` for more examples.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3, 4],
+        ...               index=pd.MultiIndex.from_product([['one', 'two'],
+        ...                                                 ['a', 'b']]))
+        >>> s
+        one  a    1
+             b    2
+        two  a    3
+             b    4
+        dtype: int64
+
+        >>> s.unstack(level=-1)
+             a  b
+        one  1  2
+        two  3  4
+
+        >>> s.unstack(level=0)
+           one  two
+        a    1    3
+        b    2    4
+        """
+        from pandas.core.reshape.reshape import unstack
+
+        return unstack(self, level, fill_value, sort)
+
+    # ----------------------------------------------------------------------
+    # function application
+
+    def map(
+        self,
+        arg: Callable | Mapping | Series,
+        na_action: Literal["ignore"] | None = None,
+    ) -> Series:
+        """
+        Map values of Series according to an input mapping or function.
+
+        Used for substituting each value in a Series with another value,
+        that may be derived from a function, a ``dict`` or
+        a :class:`Series`.
+
+        Parameters
+        ----------
+        arg : function, collections.abc.Mapping subclass or Series
+            Mapping correspondence.
+        na_action : {None, 'ignore'}, default None
+            If 'ignore', propagate NaN values, without passing them to the
+            mapping correspondence.
+
+        Returns
+        -------
+        Series
+            Same index as caller.
+
+        See Also
+        --------
+        Series.apply : For applying more complex functions on a Series.
+        Series.replace: Replace values given in `to_replace` with `value`.
+        DataFrame.apply : Apply a function row-/column-wise.
+        DataFrame.map : Apply a function elementwise on a whole DataFrame.
+
+        Notes
+        -----
+        When ``arg`` is a dictionary, values in Series that are not in the
+        dictionary (as keys) are converted to ``NaN``. However, if the
+        dictionary is a ``dict`` subclass that defines ``__missing__`` (i.e.
+        provides a method for default values), then this default is used
+        rather than ``NaN``.
+
+        Examples
+        --------
+        >>> s = pd.Series(['cat', 'dog', np.nan, 'rabbit'])
+        >>> s
+        0      cat
+        1      dog
+        2      NaN
+        3   rabbit
+        dtype: object
+
+        ``map`` accepts a ``dict`` or a ``Series``. Values that are not found
+        in the ``dict`` are converted to ``NaN``, unless the dict has a default
+        value (e.g. ``defaultdict``):
+
+        >>> s.map({'cat': 'kitten', 'dog': 'puppy'})
+        0   kitten
+        1    puppy
+        2      NaN
+        3      NaN
+        dtype: object
+
+        It also accepts a function:
+
+        >>> s.map('I am a {}'.format)
+        0       I am a cat
+        1       I am a dog
+        2       I am a nan
+        3    I am a rabbit
+        dtype: object
+
+        To avoid applying the function to missing values (and keep them as
+        ``NaN``) ``na_action='ignore'`` can be used:
+
+        >>> s.map('I am a {}'.format, na_action='ignore')
+        0     I am a cat
+        1     I am a dog
+        2            NaN
+        3  I am a rabbit
+        dtype: object
+        """
+        new_values = self._map_values(arg, na_action=na_action)
+        return self._constructor(new_values, index=self.index, copy=False).__finalize__(
+            self, method="map"
+        )
+
+    def _gotitem(self, key, ndim, subset=None) -> Self:
+        """
+        Sub-classes to define. Return a sliced object.
+
+        Parameters
+        ----------
+        key : string / list of selections
+        ndim : {1, 2}
+            Requested ndim of result.
+        subset : object, default None
+            Subset to act on.
+        """
+        return self
+
+    _agg_see_also_doc = dedent(
+        """
+    See Also
+    --------
+    Series.apply : Invoke function on a Series.
+    Series.transform : Transform function producing a Series with like indexes.
+    """
+    )
+
+    _agg_examples_doc = dedent(
+        """
+    Examples
+    --------
+    >>> s = pd.Series([1, 2, 3, 4])
+    >>> s
+    0    1
+    1    2
+    2    3
+    3    4
+    dtype: int64
+
+    >>> s.agg('min')
+    1
+
+    >>> s.agg(['min', 'max'])
+    min   1
+    max   4
+    dtype: int64
+    """
+    )
+
+    @doc(
+        _shared_docs["aggregate"],
+        klass=_shared_doc_kwargs["klass"],
+        axis=_shared_doc_kwargs["axis"],
+        see_also=_agg_see_also_doc,
+        examples=_agg_examples_doc,
+    )
+    def aggregate(self, func=None, axis: Axis = 0, *args, **kwargs):
+        # Validate the axis parameter
+        self._get_axis_number(axis)
+
+        # if func is None, will switch to user-provided "named aggregation" kwargs
+        if func is None:
+            func = dict(kwargs.items())
+
+        op = SeriesApply(self, func, args=args, kwargs=kwargs)
+        result = op.agg()
+        return result
+
+    agg = aggregate
+
+    @doc(
+        _shared_docs["transform"],
+        klass=_shared_doc_kwargs["klass"],
+        axis=_shared_doc_kwargs["axis"],
+    )
+    def transform(
+        self, func: AggFuncType, axis: Axis = 0, *args, **kwargs
+    ) -> DataFrame | Series:
+        # Validate axis argument
+        self._get_axis_number(axis)
+        ser = (
+            self.copy(deep=False)
+            if using_copy_on_write() or warn_copy_on_write()
+            else self
+        )
+        result = SeriesApply(ser, func=func, args=args, kwargs=kwargs).transform()
+        return result
+
+    def apply(
+        self,
+        func: AggFuncType,
+        convert_dtype: bool | lib.NoDefault = lib.no_default,
+        args: tuple[Any, ...] = (),
+        *,
+        by_row: Literal[False, "compat"] = "compat",
+        **kwargs,
+    ) -> DataFrame | Series:
+        """
+        Invoke function on values of Series.
+
+        Can be ufunc (a NumPy function that applies to the entire Series)
+        or a Python function that only works on single values.
+
+        Parameters
+        ----------
+        func : function
+            Python function or NumPy ufunc to apply.
+        convert_dtype : bool, default True
+            Try to find better dtype for elementwise function results. If
+            False, leave as dtype=object. Note that the dtype is always
+            preserved for some extension array dtypes, such as Categorical.
+
+            .. deprecated:: 2.1.0
+                ``convert_dtype`` has been deprecated. Do ``ser.astype(object).apply()``
+                instead if you want ``convert_dtype=False``.
+        args : tuple
+            Positional arguments passed to func after the series value.
+        by_row : False or "compat", default "compat"
+            If ``"compat"`` and func is a callable, func will be passed each element of
+            the Series, like ``Series.map``. If func is a list or dict of
+            callables, will first try to translate each func into pandas methods. If
+            that doesn't work, will try call to apply again with ``by_row="compat"``
+            and if that fails, will call apply again with ``by_row=False``
+            (backward compatible).
+            If False, the func will be passed the whole Series at once.
+
+            ``by_row`` has no effect when ``func`` is a string.
+
+            .. versionadded:: 2.1.0
+        **kwargs
+            Additional keyword arguments passed to func.
+
+        Returns
+        -------
+        Series or DataFrame
+            If func returns a Series object the result will be a DataFrame.
+
+        See Also
+        --------
+        Series.map: For element-wise operations.
+        Series.agg: Only perform aggregating type operations.
+        Series.transform: Only perform transforming type operations.
+
+        Notes
+        -----
+        Functions that mutate the passed object can produce unexpected
+        behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+        for more details.
+
+        Examples
+        --------
+        Create a series with typical summer temperatures for each city.
+
+        >>> s = pd.Series([20, 21, 12],
+        ...               index=['London', 'New York', 'Helsinki'])
+        >>> s
+        London      20
+        New York    21
+        Helsinki    12
+        dtype: int64
+
+        Square the values by defining a function and passing it as an
+        argument to ``apply()``.
+
+        >>> def square(x):
+        ...     return x ** 2
+        >>> s.apply(square)
+        London      400
+        New York    441
+        Helsinki    144
+        dtype: int64
+
+        Square the values by passing an anonymous function as an
+        argument to ``apply()``.
+
+        >>> s.apply(lambda x: x ** 2)
+        London      400
+        New York    441
+        Helsinki    144
+        dtype: int64
+
+        Define a custom function that needs additional positional
+        arguments and pass these additional arguments using the
+        ``args`` keyword.
+
+        >>> def subtract_custom_value(x, custom_value):
+        ...     return x - custom_value
+
+        >>> s.apply(subtract_custom_value, args=(5,))
+        London      15
+        New York    16
+        Helsinki     7
+        dtype: int64
+
+        Define a custom function that takes keyword arguments
+        and pass these arguments to ``apply``.
+
+        >>> def add_custom_values(x, **kwargs):
+        ...     for month in kwargs:
+        ...         x += kwargs[month]
+        ...     return x
+
+        >>> s.apply(add_custom_values, june=30, july=20, august=25)
+        London      95
+        New York    96
+        Helsinki    87
+        dtype: int64
+
+        Use a function from the Numpy library.
+
+        >>> s.apply(np.log)
+        London      2.995732
+        New York    3.044522
+        Helsinki    2.484907
+        dtype: float64
+        """
+        return SeriesApply(
+            self,
+            func,
+            convert_dtype=convert_dtype,
+            by_row=by_row,
+            args=args,
+            kwargs=kwargs,
+        ).apply()
+
+    def _reindex_indexer(
+        self,
+        new_index: Index | None,
+        indexer: npt.NDArray[np.intp] | None,
+        copy: bool | None,
+    ) -> Series:
+        # Note: new_index is None iff indexer is None
+        # if not None, indexer is np.intp
+        if indexer is None and (
+            new_index is None or new_index.names == self.index.names
+        ):
+            if using_copy_on_write():
+                return self.copy(deep=copy)
+            if copy or copy is None:
+                return self.copy(deep=copy)
+            return self
+
+        new_values = algorithms.take_nd(
+            self._values, indexer, allow_fill=True, fill_value=None
+        )
+        return self._constructor(new_values, index=new_index, copy=False)
+
+    def _needs_reindex_multi(self, axes, method, level) -> bool:
+        """
+        Check if we do need a multi reindex; this is for compat with
+        higher dims.
+        """
+        return False
+
+    @overload
+    def rename(
+        self,
+        index: Renamer | Hashable | None = ...,
+        *,
+        axis: Axis | None = ...,
+        copy: bool = ...,
+        inplace: Literal[True],
+        level: Level | None = ...,
+        errors: IgnoreRaise = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def rename(
+        self,
+        index: Renamer | Hashable | None = ...,
+        *,
+        axis: Axis | None = ...,
+        copy: bool = ...,
+        inplace: Literal[False] = ...,
+        level: Level | None = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def rename(
+        self,
+        index: Renamer | Hashable | None = ...,
+        *,
+        axis: Axis | None = ...,
+        copy: bool = ...,
+        inplace: bool = ...,
+        level: Level | None = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Series | None:
+        ...
+
+    def rename(
+        self,
+        index: Renamer | Hashable | None = None,
+        *,
+        axis: Axis | None = None,
+        copy: bool | None = None,
+        inplace: bool = False,
+        level: Level | None = None,
+        errors: IgnoreRaise = "ignore",
+    ) -> Series | None:
+        """
+        Alter Series index labels or name.
+
+        Function / dict values must be unique (1-to-1). Labels not contained in
+        a dict / Series will be left as-is. Extra labels listed don't throw an
+        error.
+
+        Alternatively, change ``Series.name`` with a scalar value.
+
+        See the :ref:`user guide ` for more.
+
+        Parameters
+        ----------
+        index : scalar, hashable sequence, dict-like or function optional
+            Functions or dict-like are transformations to apply to
+            the index.
+            Scalar or hashable sequence-like will alter the ``Series.name``
+            attribute.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        copy : bool, default True
+            Also copy underlying data.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+        inplace : bool, default False
+            Whether to return a new Series. If True the value of copy is ignored.
+        level : int or level name, default None
+            In case of MultiIndex, only rename labels in the specified level.
+        errors : {'ignore', 'raise'}, default 'ignore'
+            If 'raise', raise `KeyError` when a `dict-like mapper` or
+            `index` contains labels that are not present in the index being transformed.
+            If 'ignore', existing keys will be renamed and extra keys will be ignored.
+
+        Returns
+        -------
+        Series or None
+            Series with index labels or name altered or None if ``inplace=True``.
+
+        See Also
+        --------
+        DataFrame.rename : Corresponding DataFrame method.
+        Series.rename_axis : Set the name of the axis.
+
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s
+        0    1
+        1    2
+        2    3
+        dtype: int64
+        >>> s.rename("my_name")  # scalar, changes Series.name
+        0    1
+        1    2
+        2    3
+        Name: my_name, dtype: int64
+        >>> s.rename(lambda x: x ** 2)  # function, changes labels
+        0    1
+        1    2
+        4    3
+        dtype: int64
+        >>> s.rename({1: 3, 2: 5})  # mapping, changes labels
+        0    1
+        3    2
+        5    3
+        dtype: int64
+        """
+        if axis is not None:
+            # Make sure we raise if an invalid 'axis' is passed.
+            axis = self._get_axis_number(axis)
+
+        if callable(index) or is_dict_like(index):
+            # error: Argument 1 to "_rename" of "NDFrame" has incompatible
+            # type "Union[Union[Mapping[Any, Hashable], Callable[[Any],
+            # Hashable]], Hashable, None]"; expected "Union[Mapping[Any,
+            # Hashable], Callable[[Any], Hashable], None]"
+            return super()._rename(
+                index,  # type: ignore[arg-type]
+                copy=copy,
+                inplace=inplace,
+                level=level,
+                errors=errors,
+            )
+        else:
+            return self._set_name(index, inplace=inplace, deep=copy)
+
+    @Appender(
+        """
+        Examples
+        --------
+        >>> s = pd.Series([1, 2, 3])
+        >>> s
+        0    1
+        1    2
+        2    3
+        dtype: int64
+
+        >>> s.set_axis(['a', 'b', 'c'], axis=0)
+        a    1
+        b    2
+        c    3
+        dtype: int64
+    """
+    )
+    @Substitution(
+        klass=_shared_doc_kwargs["klass"],
+        axes_single_arg=_shared_doc_kwargs["axes_single_arg"],
+        extended_summary_sub="",
+        axis_description_sub="",
+        see_also_sub="",
+    )
+    @Appender(NDFrame.set_axis.__doc__)
+    def set_axis(
+        self,
+        labels,
+        *,
+        axis: Axis = 0,
+        copy: bool | None = None,
+    ) -> Series:
+        return super().set_axis(labels, axis=axis, copy=copy)
+
+    # error: Cannot determine type of 'reindex'
+    @doc(
+        NDFrame.reindex,  # type: ignore[has-type]
+        klass=_shared_doc_kwargs["klass"],
+        optional_reindex=_shared_doc_kwargs["optional_reindex"],
+    )
+    def reindex(  # type: ignore[override]
+        self,
+        index=None,
+        *,
+        axis: Axis | None = None,
+        method: ReindexMethod | None = None,
+        copy: bool | None = None,
+        level: Level | None = None,
+        fill_value: Scalar | None = None,
+        limit: int | None = None,
+        tolerance=None,
+    ) -> Series:
+        return super().reindex(
+            index=index,
+            method=method,
+            copy=copy,
+            level=level,
+            fill_value=fill_value,
+            limit=limit,
+            tolerance=tolerance,
+        )
+
+    @overload  # type: ignore[override]
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        axis: Axis = ...,
+        copy: bool = ...,
+        inplace: Literal[True],
+    ) -> None:
+        ...
+
+    @overload
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        axis: Axis = ...,
+        copy: bool = ...,
+        inplace: Literal[False] = ...,
+    ) -> Self:
+        ...
+
+    @overload
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = ...,
+        *,
+        index=...,
+        axis: Axis = ...,
+        copy: bool = ...,
+        inplace: bool = ...,
+    ) -> Self | None:
+        ...
+
+    @doc(NDFrame.rename_axis)
+    def rename_axis(
+        self,
+        mapper: IndexLabel | lib.NoDefault = lib.no_default,
+        *,
+        index=lib.no_default,
+        axis: Axis = 0,
+        copy: bool = True,
+        inplace: bool = False,
+    ) -> Self | None:
+        return super().rename_axis(
+            mapper=mapper,
+            index=index,
+            axis=axis,
+            copy=copy,
+            inplace=inplace,
+        )
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: Literal[True],
+        errors: IgnoreRaise = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: Literal[False] = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def drop(
+        self,
+        labels: IndexLabel = ...,
+        *,
+        axis: Axis = ...,
+        index: IndexLabel = ...,
+        columns: IndexLabel = ...,
+        level: Level | None = ...,
+        inplace: bool = ...,
+        errors: IgnoreRaise = ...,
+    ) -> Series | None:
+        ...
+
+    def drop(
+        self,
+        labels: IndexLabel | None = None,
+        *,
+        axis: Axis = 0,
+        index: IndexLabel | None = None,
+        columns: IndexLabel | None = None,
+        level: Level | None = None,
+        inplace: bool = False,
+        errors: IgnoreRaise = "raise",
+    ) -> Series | None:
+        """
+        Return Series with specified index labels removed.
+
+        Remove elements of a Series based on specifying the index labels.
+        When using a multi-index, labels on different levels can be removed
+        by specifying the level.
+
+        Parameters
+        ----------
+        labels : single label or list-like
+            Index labels to drop.
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        index : single label or list-like
+            Redundant for application on Series, but 'index' can be used instead
+            of 'labels'.
+        columns : single label or list-like
+            No change is made to the Series; use 'index' or 'labels' instead.
+        level : int or level name, optional
+            For MultiIndex, level for which the labels will be removed.
+        inplace : bool, default False
+            If True, do operation inplace and return None.
+        errors : {'ignore', 'raise'}, default 'raise'
+            If 'ignore', suppress error and only existing labels are dropped.
+
+        Returns
+        -------
+        Series or None
+            Series with specified index labels removed or None if ``inplace=True``.
+
+        Raises
+        ------
+        KeyError
+            If none of the labels are found in the index.
+
+        See Also
+        --------
+        Series.reindex : Return only specified index labels of Series.
+        Series.dropna : Return series without null values.
+        Series.drop_duplicates : Return Series with duplicate values removed.
+        DataFrame.drop : Drop specified labels from rows or columns.
+
+        Examples
+        --------
+        >>> s = pd.Series(data=np.arange(3), index=['A', 'B', 'C'])
+        >>> s
+        A  0
+        B  1
+        C  2
+        dtype: int64
+
+        Drop labels B en C
+
+        >>> s.drop(labels=['B', 'C'])
+        A  0
+        dtype: int64
+
+        Drop 2nd level label in MultiIndex Series
+
+        >>> midx = pd.MultiIndex(levels=[['llama', 'cow', 'falcon'],
+        ...                              ['speed', 'weight', 'length']],
+        ...                      codes=[[0, 0, 0, 1, 1, 1, 2, 2, 2],
+        ...                             [0, 1, 2, 0, 1, 2, 0, 1, 2]])
+        >>> s = pd.Series([45, 200, 1.2, 30, 250, 1.5, 320, 1, 0.3],
+        ...               index=midx)
+        >>> s
+        llama   speed      45.0
+                weight    200.0
+                length      1.2
+        cow     speed      30.0
+                weight    250.0
+                length      1.5
+        falcon  speed     320.0
+                weight      1.0
+                length      0.3
+        dtype: float64
+
+        >>> s.drop(labels='weight', level=1)
+        llama   speed      45.0
+                length      1.2
+        cow     speed      30.0
+                length      1.5
+        falcon  speed     320.0
+                length      0.3
+        dtype: float64
+        """
+        return super().drop(
+            labels=labels,
+            axis=axis,
+            index=index,
+            columns=columns,
+            level=level,
+            inplace=inplace,
+            errors=errors,
+        )
+
+    def pop(self, item: Hashable) -> Any:
+        """
+        Return item and drops from series. Raise KeyError if not found.
+
+        Parameters
+        ----------
+        item : label
+            Index of the element that needs to be removed.
+
+        Returns
+        -------
+        Value that is popped from series.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1, 2, 3])
+
+        >>> ser.pop(0)
+        1
+
+        >>> ser
+        1    2
+        2    3
+        dtype: int64
+        """
+        return super().pop(item=item)
+
+    @doc(INFO_DOCSTRING, **series_sub_kwargs)
+    def info(
+        self,
+        verbose: bool | None = None,
+        buf: IO[str] | None = None,
+        max_cols: int | None = None,
+        memory_usage: bool | str | None = None,
+        show_counts: bool = True,
+    ) -> None:
+        return SeriesInfo(self, memory_usage).render(
+            buf=buf,
+            max_cols=max_cols,
+            verbose=verbose,
+            show_counts=show_counts,
+        )
+
+    # TODO(3.0): this can be removed once GH#33302 deprecation is enforced
+    def _replace_single(self, to_replace, method: str, inplace: bool, limit):
+        """
+        Replaces values in a Series using the fill method specified when no
+        replacement value is given in the replace method
+        """
+
+        result = self if inplace else self.copy()
+
+        values = result._values
+        mask = missing.mask_missing(values, to_replace)
+
+        if isinstance(values, ExtensionArray):
+            # dispatch to the EA's _pad_mask_inplace method
+            values._fill_mask_inplace(method, limit, mask)
+        else:
+            fill_f = missing.get_fill_func(method)
+            fill_f(values, limit=limit, mask=mask)
+
+        if inplace:
+            return
+        return result
+
+    def memory_usage(self, index: bool = True, deep: bool = False) -> int:
+        """
+        Return the memory usage of the Series.
+
+        The memory usage can optionally include the contribution of
+        the index and of elements of `object` dtype.
+
+        Parameters
+        ----------
+        index : bool, default True
+            Specifies whether to include the memory usage of the Series index.
+        deep : bool, default False
+            If True, introspect the data deeply by interrogating
+            `object` dtypes for system-level memory consumption, and include
+            it in the returned value.
+
+        Returns
+        -------
+        int
+            Bytes of memory consumed.
+
+        See Also
+        --------
+        numpy.ndarray.nbytes : Total bytes consumed by the elements of the
+            array.
+        DataFrame.memory_usage : Bytes consumed by a DataFrame.
+
+        Examples
+        --------
+        >>> s = pd.Series(range(3))
+        >>> s.memory_usage()
+        152
+
+        Not including the index gives the size of the rest of the data, which
+        is necessarily smaller:
+
+        >>> s.memory_usage(index=False)
+        24
+
+        The memory footprint of `object` values is ignored by default:
+
+        >>> s = pd.Series(["a", "b"])
+        >>> s.values
+        array(['a', 'b'], dtype=object)
+        >>> s.memory_usage()
+        144
+        >>> s.memory_usage(deep=True)
+        244
+        """
+        v = self._memory_usage(deep=deep)
+        if index:
+            v += self.index.memory_usage(deep=deep)
+        return v
+
+    def isin(self, values) -> Series:
+        """
+        Whether elements in Series are contained in `values`.
+
+        Return a boolean Series showing whether each element in the Series
+        matches an element in the passed sequence of `values` exactly.
+
+        Parameters
+        ----------
+        values : set or list-like
+            The sequence of values to test. Passing in a single string will
+            raise a ``TypeError``. Instead, turn a single string into a
+            list of one element.
+
+        Returns
+        -------
+        Series
+            Series of booleans indicating if each element is in values.
+
+        Raises
+        ------
+        TypeError
+          * If `values` is a string
+
+        See Also
+        --------
+        DataFrame.isin : Equivalent method on DataFrame.
+
+        Examples
+        --------
+        >>> s = pd.Series(['llama', 'cow', 'llama', 'beetle', 'llama',
+        ...                'hippo'], name='animal')
+        >>> s.isin(['cow', 'llama'])
+        0     True
+        1     True
+        2     True
+        3    False
+        4     True
+        5    False
+        Name: animal, dtype: bool
+
+        To invert the boolean values, use the ``~`` operator:
+
+        >>> ~s.isin(['cow', 'llama'])
+        0    False
+        1    False
+        2    False
+        3     True
+        4    False
+        5     True
+        Name: animal, dtype: bool
+
+        Passing a single string as ``s.isin('llama')`` will raise an error. Use
+        a list of one element instead:
+
+        >>> s.isin(['llama'])
+        0     True
+        1    False
+        2     True
+        3    False
+        4     True
+        5    False
+        Name: animal, dtype: bool
+
+        Strings and integers are distinct and are therefore not comparable:
+
+        >>> pd.Series([1]).isin(['1'])
+        0    False
+        dtype: bool
+        >>> pd.Series([1.1]).isin(['1.1'])
+        0    False
+        dtype: bool
+        """
+        result = algorithms.isin(self._values, values)
+        return self._constructor(result, index=self.index, copy=False).__finalize__(
+            self, method="isin"
+        )
+
+    def between(
+        self,
+        left,
+        right,
+        inclusive: Literal["both", "neither", "left", "right"] = "both",
+    ) -> Series:
+        """
+        Return boolean Series equivalent to left <= series <= right.
+
+        This function returns a boolean vector containing `True` wherever the
+        corresponding Series element is between the boundary values `left` and
+        `right`. NA values are treated as `False`.
+
+        Parameters
+        ----------
+        left : scalar or list-like
+            Left boundary.
+        right : scalar or list-like
+            Right boundary.
+        inclusive : {"both", "neither", "left", "right"}
+            Include boundaries. Whether to set each bound as closed or open.
+
+            .. versionchanged:: 1.3.0
+
+        Returns
+        -------
+        Series
+            Series representing whether each element is between left and
+            right (inclusive).
+
+        See Also
+        --------
+        Series.gt : Greater than of series and other.
+        Series.lt : Less than of series and other.
+
+        Notes
+        -----
+        This function is equivalent to ``(left <= ser) & (ser <= right)``
+
+        Examples
+        --------
+        >>> s = pd.Series([2, 0, 4, 8, np.nan])
+
+        Boundary values are included by default:
+
+        >>> s.between(1, 4)
+        0     True
+        1    False
+        2     True
+        3    False
+        4    False
+        dtype: bool
+
+        With `inclusive` set to ``"neither"`` boundary values are excluded:
+
+        >>> s.between(1, 4, inclusive="neither")
+        0     True
+        1    False
+        2    False
+        3    False
+        4    False
+        dtype: bool
+
+        `left` and `right` can be any scalar value:
+
+        >>> s = pd.Series(['Alice', 'Bob', 'Carol', 'Eve'])
+        >>> s.between('Anna', 'Daniel')
+        0    False
+        1     True
+        2     True
+        3    False
+        dtype: bool
+        """
+        if inclusive == "both":
+            lmask = self >= left
+            rmask = self <= right
+        elif inclusive == "left":
+            lmask = self >= left
+            rmask = self < right
+        elif inclusive == "right":
+            lmask = self > left
+            rmask = self <= right
+        elif inclusive == "neither":
+            lmask = self > left
+            rmask = self < right
+        else:
+            raise ValueError(
+                "Inclusive has to be either string of 'both',"
+                "'left', 'right', or 'neither'."
+            )
+
+        return lmask & rmask
+
+    def case_when(
+        self,
+        caselist: list[
+            tuple[
+                ArrayLike | Callable[[Series], Series | np.ndarray | Sequence[bool]],
+                ArrayLike | Scalar | Callable[[Series], Series | np.ndarray],
+            ],
+        ],
+    ) -> Series:
+        """
+        Replace values where the conditions are True.
+
+        Parameters
+        ----------
+        caselist : A list of tuples of conditions and expected replacements
+            Takes the form:  ``(condition0, replacement0)``,
+            ``(condition1, replacement1)``, ... .
+            ``condition`` should be a 1-D boolean array-like object
+            or a callable. If ``condition`` is a callable,
+            it is computed on the Series
+            and should return a boolean Series or array.
+            The callable must not change the input Series
+            (though pandas doesn`t check it). ``replacement`` should be a
+            1-D array-like object, a scalar or a callable.
+            If ``replacement`` is a callable, it is computed on the Series
+            and should return a scalar or Series. The callable
+            must not change the input Series
+            (though pandas doesn`t check it).
+
+            .. versionadded:: 2.2.0
+
+        Returns
+        -------
+        Series
+
+        See Also
+        --------
+        Series.mask : Replace values where the condition is True.
+
+        Examples
+        --------
+        >>> c = pd.Series([6, 7, 8, 9], name='c')
+        >>> a = pd.Series([0, 0, 1, 2])
+        >>> b = pd.Series([0, 3, 4, 5])
+
+        >>> c.case_when(caselist=[(a.gt(0), a),  # condition, replacement
+        ...                       (b.gt(0), b)])
+        0    6
+        1    3
+        2    1
+        3    2
+        Name: c, dtype: int64
+        """
+        if not isinstance(caselist, list):
+            raise TypeError(
+                f"The caselist argument should be a list; instead got {type(caselist)}"
+            )
+
+        if not caselist:
+            raise ValueError(
+                "provide at least one boolean condition, "
+                "with a corresponding replacement."
+            )
+
+        for num, entry in enumerate(caselist):
+            if not isinstance(entry, tuple):
+                raise TypeError(
+                    f"Argument {num} must be a tuple; instead got {type(entry)}."
+                )
+            if len(entry) != 2:
+                raise ValueError(
+                    f"Argument {num} must have length 2; "
+                    "a condition and replacement; "
+                    f"instead got length {len(entry)}."
+                )
+        caselist = [
+            (
+                com.apply_if_callable(condition, self),
+                com.apply_if_callable(replacement, self),
+            )
+            for condition, replacement in caselist
+        ]
+        default = self.copy()
+        conditions, replacements = zip(*caselist)
+        common_dtypes = [infer_dtype_from(arg)[0] for arg in [*replacements, default]]
+        if len(set(common_dtypes)) > 1:
+            common_dtype = find_common_type(common_dtypes)
+            updated_replacements = []
+            for condition, replacement in zip(conditions, replacements):
+                if is_scalar(replacement):
+                    replacement = construct_1d_arraylike_from_scalar(
+                        value=replacement, length=len(condition), dtype=common_dtype
+                    )
+                elif isinstance(replacement, ABCSeries):
+                    replacement = replacement.astype(common_dtype)
+                else:
+                    replacement = pd_array(replacement, dtype=common_dtype)
+                updated_replacements.append(replacement)
+            replacements = updated_replacements
+            default = default.astype(common_dtype)
+
+        counter = reversed(range(len(conditions)))
+        for position, condition, replacement in zip(
+            counter, conditions[::-1], replacements[::-1]
+        ):
+            try:
+                default = default.mask(
+                    condition, other=replacement, axis=0, inplace=False, level=None
+                )
+            except Exception as error:
+                raise ValueError(
+                    f"Failed to apply condition{position} and replacement{position}."
+                ) from error
+        return default
+
+    # error: Cannot determine type of 'isna'
+    @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])  # type: ignore[has-type]
+    def isna(self) -> Series:
+        return NDFrame.isna(self)
+
+    # error: Cannot determine type of 'isna'
+    @doc(NDFrame.isna, klass=_shared_doc_kwargs["klass"])  # type: ignore[has-type]
+    def isnull(self) -> Series:
+        """
+        Series.isnull is an alias for Series.isna.
+        """
+        return super().isnull()
+
+    # error: Cannot determine type of 'notna'
+    @doc(NDFrame.notna, klass=_shared_doc_kwargs["klass"])  # type: ignore[has-type]
+    def notna(self) -> Series:
+        return super().notna()
+
+    # error: Cannot determine type of 'notna'
+    @doc(NDFrame.notna, klass=_shared_doc_kwargs["klass"])  # type: ignore[has-type]
+    def notnull(self) -> Series:
+        """
+        Series.notnull is an alias for Series.notna.
+        """
+        return super().notnull()
+
+    @overload
+    def dropna(
+        self,
+        *,
+        axis: Axis = ...,
+        inplace: Literal[False] = ...,
+        how: AnyAll | None = ...,
+        ignore_index: bool = ...,
+    ) -> Series:
+        ...
+
+    @overload
+    def dropna(
+        self,
+        *,
+        axis: Axis = ...,
+        inplace: Literal[True],
+        how: AnyAll | None = ...,
+        ignore_index: bool = ...,
+    ) -> None:
+        ...
+
+    def dropna(
+        self,
+        *,
+        axis: Axis = 0,
+        inplace: bool = False,
+        how: AnyAll | None = None,
+        ignore_index: bool = False,
+    ) -> Series | None:
+        """
+        Return a new Series with missing values removed.
+
+        See the :ref:`User Guide ` for more on which values are
+        considered missing, and how to work with missing data.
+
+        Parameters
+        ----------
+        axis : {0 or 'index'}
+            Unused. Parameter needed for compatibility with DataFrame.
+        inplace : bool, default False
+            If True, do operation inplace and return None.
+        how : str, optional
+            Not in use. Kept for compatibility.
+        ignore_index : bool, default ``False``
+            If ``True``, the resulting axis will be labeled 0, 1, …, n - 1.
+
+            .. versionadded:: 2.0.0
+
+        Returns
+        -------
+        Series or None
+            Series with NA entries dropped from it or None if ``inplace=True``.
+
+        See Also
+        --------
+        Series.isna: Indicate missing values.
+        Series.notna : Indicate existing (non-missing) values.
+        Series.fillna : Replace missing values.
+        DataFrame.dropna : Drop rows or columns which contain NA values.
+        Index.dropna : Drop missing indices.
+
+        Examples
+        --------
+        >>> ser = pd.Series([1., 2., np.nan])
+        >>> ser
+        0    1.0
+        1    2.0
+        2    NaN
+        dtype: float64
+
+        Drop NA values from a Series.
+
+        >>> ser.dropna()
+        0    1.0
+        1    2.0
+        dtype: float64
+
+        Empty strings are not considered NA values. ``None`` is considered an
+        NA value.
+
+        >>> ser = pd.Series([np.nan, 2, pd.NaT, '', None, 'I stay'])
+        >>> ser
+        0       NaN
+        1         2
+        2       NaT
+        3
+        4      None
+        5    I stay
+        dtype: object
+        >>> ser.dropna()
+        1         2
+        3
+        5    I stay
+        dtype: object
+        """
+        inplace = validate_bool_kwarg(inplace, "inplace")
+        ignore_index = validate_bool_kwarg(ignore_index, "ignore_index")
+        # Validate the axis parameter
+        self._get_axis_number(axis or 0)
+
+        if self._can_hold_na:
+            result = remove_na_arraylike(self)
+        else:
+            if not inplace:
+                result = self.copy(deep=None)
+            else:
+                result = self
+
+        if ignore_index:
+            result.index = default_index(len(result))
+
+        if inplace:
+            return self._update_inplace(result)
+        else:
+            return result
+
+    # ----------------------------------------------------------------------
+    # Time series-oriented methods
+
+    def to_timestamp(
+        self,
+        freq: Frequency | None = None,
+        how: Literal["s", "e", "start", "end"] = "start",
+        copy: bool | None = None,
+    ) -> Series:
+        """
+        Cast to DatetimeIndex of Timestamps, at *beginning* of period.
+
+        Parameters
+        ----------
+        freq : str, default frequency of PeriodIndex
+            Desired frequency.
+        how : {'s', 'e', 'start', 'end'}
+            Convention for converting period to timestamp; start of period
+            vs. end.
+        copy : bool, default True
+            Whether or not to return a copy.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        Series with DatetimeIndex
+
+        Examples
+        --------
+        >>> idx = pd.PeriodIndex(['2023', '2024', '2025'], freq='Y')
+        >>> s1 = pd.Series([1, 2, 3], index=idx)
+        >>> s1
+        2023    1
+        2024    2
+        2025    3
+        Freq: Y-DEC, dtype: int64
+
+        The resulting frequency of the Timestamps is `YearBegin`
+
+        >>> s1 = s1.to_timestamp()
+        >>> s1
+        2023-01-01    1
+        2024-01-01    2
+        2025-01-01    3
+        Freq: YS-JAN, dtype: int64
+
+        Using `freq` which is the offset that the Timestamps will have
+
+        >>> s2 = pd.Series([1, 2, 3], index=idx)
+        >>> s2 = s2.to_timestamp(freq='M')
+        >>> s2
+        2023-01-31    1
+        2024-01-31    2
+        2025-01-31    3
+        Freq: YE-JAN, dtype: int64
+        """
+        if not isinstance(self.index, PeriodIndex):
+            raise TypeError(f"unsupported Type {type(self.index).__name__}")
+
+        new_obj = self.copy(deep=copy and not using_copy_on_write())
+        new_index = self.index.to_timestamp(freq=freq, how=how)
+        setattr(new_obj, "index", new_index)
+        return new_obj
+
+    def to_period(self, freq: str | None = None, copy: bool | None = None) -> Series:
+        """
+        Convert Series from DatetimeIndex to PeriodIndex.
+
+        Parameters
+        ----------
+        freq : str, default None
+            Frequency associated with the PeriodIndex.
+        copy : bool, default True
+            Whether or not to return a copy.
+
+            .. note::
+                The `copy` keyword will change behavior in pandas 3.0.
+                `Copy-on-Write
+                `__
+                will be enabled by default, which means that all methods with a
+                `copy` keyword will use a lazy copy mechanism to defer the copy and
+                ignore the `copy` keyword. The `copy` keyword will be removed in a
+                future version of pandas.
+
+                You can already get the future behavior and improvements through
+                enabling copy on write ``pd.options.mode.copy_on_write = True``
+
+        Returns
+        -------
+        Series
+            Series with index converted to PeriodIndex.
+
+        Examples
+        --------
+        >>> idx = pd.DatetimeIndex(['2023', '2024', '2025'])
+        >>> s = pd.Series([1, 2, 3], index=idx)
+        >>> s = s.to_period()
+        >>> s
+        2023    1
+        2024    2
+        2025    3
+        Freq: Y-DEC, dtype: int64
+
+        Viewing the index
+
+        >>> s.index
+        PeriodIndex(['2023', '2024', '2025'], dtype='period[Y-DEC]')
+        """
+        if not isinstance(self.index, DatetimeIndex):
+            raise TypeError(f"unsupported Type {type(self.index).__name__}")
+
+        new_obj = self.copy(deep=copy and not using_copy_on_write())
+        new_index = self.index.to_period(freq=freq)
+        setattr(new_obj, "index", new_index)
+        return new_obj
+
+    # ----------------------------------------------------------------------
+    # Add index
+    _AXIS_ORDERS: list[Literal["index", "columns"]] = ["index"]
+    _AXIS_LEN = len(_AXIS_ORDERS)
+    _info_axis_number: Literal[0] = 0
+    _info_axis_name: Literal["index"] = "index"
+
+    index = properties.AxisProperty(
+        axis=0,
+        doc="""
+        The index (axis labels) of the Series.
+
+        The index of a Series is used to label and identify each element of the
+        underlying data. The index can be thought of as an immutable ordered set
+        (technically a multi-set, as it may contain duplicate labels), and is
+        used to index and align data in pandas.
+
+        Returns
+        -------
+        Index
+            The index labels of the Series.
+
+        See Also
+        --------
+        Series.reindex : Conform Series to new index.
+        Index : The base pandas index type.
+
+        Notes
+        -----
+        For more information on pandas indexing, see the `indexing user guide
+        `__.
+
+        Examples
+        --------
+        To create a Series with a custom index and view the index labels:
+
+        >>> cities = ['Kolkata', 'Chicago', 'Toronto', 'Lisbon']
+        >>> populations = [14.85, 2.71, 2.93, 0.51]
+        >>> city_series = pd.Series(populations, index=cities)
+        >>> city_series.index
+        Index(['Kolkata', 'Chicago', 'Toronto', 'Lisbon'], dtype='object')
+
+        To change the index labels of an existing Series:
+
+        >>> city_series.index = ['KOL', 'CHI', 'TOR', 'LIS']
+        >>> city_series.index
+        Index(['KOL', 'CHI', 'TOR', 'LIS'], dtype='object')
+        """,
+    )
+
+    # ----------------------------------------------------------------------
+    # Accessor Methods
+    # ----------------------------------------------------------------------
+    str = CachedAccessor("str", StringMethods)
+    dt = CachedAccessor("dt", CombinedDatetimelikeProperties)
+    cat = CachedAccessor("cat", CategoricalAccessor)
+    plot = CachedAccessor("plot", pandas.plotting.PlotAccessor)
+    sparse = CachedAccessor("sparse", SparseAccessor)
+    struct = CachedAccessor("struct", StructAccessor)
+    list = CachedAccessor("list", ListAccessor)
+
+    # ----------------------------------------------------------------------
+    # Add plotting methods to Series
+    hist = pandas.plotting.hist_series
+
+    # ----------------------------------------------------------------------
+    # Template-Based Arithmetic/Comparison Methods
+
+    def _cmp_method(self, other, op):
+        res_name = ops.get_op_result_name(self, other)
+
+        if isinstance(other, Series) and not self._indexed_same(other):
+            raise ValueError("Can only compare identically-labeled Series objects")
+
+        lvalues = self._values
+        rvalues = extract_array(other, extract_numpy=True, extract_range=True)
+
+        res_values = ops.comparison_op(lvalues, rvalues, op)
+
+        return self._construct_result(res_values, name=res_name)
+
+    def _logical_method(self, other, op):
+        res_name = ops.get_op_result_name(self, other)
+        self, other = self._align_for_op(other, align_asobject=True)
+
+        lvalues = self._values
+        rvalues = extract_array(other, extract_numpy=True, extract_range=True)
+
+        res_values = ops.logical_op(lvalues, rvalues, op)
+        return self._construct_result(res_values, name=res_name)
+
+    def _arith_method(self, other, op):
+        self, other = self._align_for_op(other)
+        return base.IndexOpsMixin._arith_method(self, other, op)
+
+    def _align_for_op(self, right, align_asobject: bool = False):
+        """align lhs and rhs Series"""
+        # TODO: Different from DataFrame._align_for_op, list, tuple and ndarray
+        # are not coerced here
+        # because Series has inconsistencies described in GH#13637
+        left = self
+
+        if isinstance(right, Series):
+            # avoid repeated alignment
+            if not left.index.equals(right.index):
+                if align_asobject:
+                    if left.dtype not in (object, np.bool_) or right.dtype not in (
+                        object,
+                        np.bool_,
+                    ):
+                        warnings.warn(
+                            "Operation between Series with different indexes "
+                            "that are not of numpy boolean or object dtype "
+                            "will no longer return a numpy boolean result "
+                            "in a future version. "
+                            "Cast both Series to object type "
+                            "to maintain the prior behavior.",
+                            FutureWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    # to keep original value's dtype for bool ops
+                    left = left.astype(object)
+                    right = right.astype(object)
+
+                left, right = left.align(right, copy=False)
+
+        return left, right
+
+    def _binop(self, other: Series, func, level=None, fill_value=None) -> Series:
+        """
+        Perform generic binary operation with optional fill value.
+
+        Parameters
+        ----------
+        other : Series
+        func : binary operator
+        fill_value : float or object
+            Value to substitute for NA/null values. If both Series are NA in a
+            location, the result will be NA regardless of the passed fill value.
+        level : int or level name, default None
+            Broadcast across a level, matching Index values on the
+            passed MultiIndex level.
+
+        Returns
+        -------
+        Series
+        """
+        this = self
+
+        if not self.index.equals(other.index):
+            this, other = self.align(other, level=level, join="outer", copy=False)
+
+        this_vals, other_vals = ops.fill_binop(this._values, other._values, fill_value)
+
+        with np.errstate(all="ignore"):
+            result = func(this_vals, other_vals)
+
+        name = ops.get_op_result_name(self, other)
+        out = this._construct_result(result, name)
+        return cast(Series, out)
+
+    def _construct_result(
+        self, result: ArrayLike | tuple[ArrayLike, ArrayLike], name: Hashable
+    ) -> Series | tuple[Series, Series]:
+        """
+        Construct an appropriately-labelled Series from the result of an op.
+
+        Parameters
+        ----------
+        result : ndarray or ExtensionArray
+        name : Label
+
+        Returns
+        -------
+        Series
+            In the case of __divmod__ or __rdivmod__, a 2-tuple of Series.
+        """
+        if isinstance(result, tuple):
+            # produced by divmod or rdivmod
+
+            res1 = self._construct_result(result[0], name=name)
+            res2 = self._construct_result(result[1], name=name)
+
+            # GH#33427 assertions to keep mypy happy
+            assert isinstance(res1, Series)
+            assert isinstance(res2, Series)
+            return (res1, res2)
+
+        # TODO: result should always be ArrayLike, but this fails for some
+        #  JSONArray tests
+        dtype = getattr(result, "dtype", None)
+        out = self._constructor(result, index=self.index, dtype=dtype, copy=False)
+        out = out.__finalize__(self)
+
+        # Set the result's name after __finalize__ is called because __finalize__
+        #  would set it back to self.name
+        out.name = name
+        return out
+
+    def _flex_method(self, other, op, *, level=None, fill_value=None, axis: Axis = 0):
+        if axis is not None:
+            self._get_axis_number(axis)
+
+        res_name = ops.get_op_result_name(self, other)
+
+        if isinstance(other, Series):
+            return self._binop(other, op, level=level, fill_value=fill_value)
+        elif isinstance(other, (np.ndarray, list, tuple)):
+            if len(other) != len(self):
+                raise ValueError("Lengths must be equal")
+            other = self._constructor(other, self.index, copy=False)
+            result = self._binop(other, op, level=level, fill_value=fill_value)
+            result._name = res_name
+            return result
+        else:
+            if fill_value is not None:
+                if isna(other):
+                    return op(self, fill_value)
+                self = self.fillna(fill_value)
+
+            return op(self, other)
+
+    @Appender(ops.make_flex_doc("eq", "series"))
+    def eq(
+        self,
+        other,
+        level: Level | None = None,
+        fill_value: float | None = None,
+        axis: Axis = 0,
+    ) -> Series:
+        return self._flex_method(
+            other, operator.eq, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("ne", "series"))
+    def ne(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.ne, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("le", "series"))
+    def le(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.le, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("lt", "series"))
+    def lt(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.lt, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("ge", "series"))
+    def ge(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.ge, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("gt", "series"))
+    def gt(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.gt, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("add", "series"))
+    def add(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.add, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("radd", "series"))
+    def radd(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.radd, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("sub", "series"))
+    def sub(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.sub, level=level, fill_value=fill_value, axis=axis
+        )
+
+    subtract = sub
+
+    @Appender(ops.make_flex_doc("rsub", "series"))
+    def rsub(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rsub, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("mul", "series"))
+    def mul(
+        self,
+        other,
+        level: Level | None = None,
+        fill_value: float | None = None,
+        axis: Axis = 0,
+    ) -> Series:
+        return self._flex_method(
+            other, operator.mul, level=level, fill_value=fill_value, axis=axis
+        )
+
+    multiply = mul
+
+    @Appender(ops.make_flex_doc("rmul", "series"))
+    def rmul(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rmul, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("truediv", "series"))
+    def truediv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.truediv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    div = truediv
+    divide = truediv
+
+    @Appender(ops.make_flex_doc("rtruediv", "series"))
+    def rtruediv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rtruediv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    rdiv = rtruediv
+
+    @Appender(ops.make_flex_doc("floordiv", "series"))
+    def floordiv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.floordiv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rfloordiv", "series"))
+    def rfloordiv(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rfloordiv, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("mod", "series"))
+    def mod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.mod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rmod", "series"))
+    def rmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rmod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("pow", "series"))
+    def pow(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, operator.pow, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rpow", "series"))
+    def rpow(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rpow, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("divmod", "series"))
+    def divmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, divmod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    @Appender(ops.make_flex_doc("rdivmod", "series"))
+    def rdivmod(self, other, level=None, fill_value=None, axis: Axis = 0) -> Series:
+        return self._flex_method(
+            other, roperator.rdivmod, level=level, fill_value=fill_value, axis=axis
+        )
+
+    # ----------------------------------------------------------------------
+    # Reductions
+
+    def _reduce(
+        self,
+        op,
+        # error: Variable "pandas.core.series.Series.str" is not valid as a type
+        name: str,  # type: ignore[valid-type]
+        *,
+        axis: Axis = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        filter_type=None,
+        **kwds,
+    ):
+        """
+        Perform a reduction operation.
+
+        If we have an ndarray as a value, then simply perform the operation,
+        otherwise delegate to the object.
+        """
+        delegate = self._values
+
+        if axis is not None:
+            self._get_axis_number(axis)
+
+        if isinstance(delegate, ExtensionArray):
+            # dispatch to ExtensionArray interface
+            return delegate._reduce(name, skipna=skipna, **kwds)
+
+        else:
+            # dispatch to numpy arrays
+            if numeric_only and self.dtype.kind not in "iufcb":
+                # i.e. not is_numeric_dtype(self.dtype)
+                kwd_name = "numeric_only"
+                if name in ["any", "all"]:
+                    kwd_name = "bool_only"
+                # GH#47500 - change to TypeError to match other methods
+                raise TypeError(
+                    f"Series.{name} does not allow {kwd_name}={numeric_only} "
+                    "with non-numeric dtypes."
+                )
+            return op(delegate, skipna=skipna, **kwds)
+
+    @Appender(make_doc("any", ndim=1))
+    # error: Signature of "any" incompatible with supertype "NDFrame"
+    def any(  # type: ignore[override]
+        self,
+        *,
+        axis: Axis = 0,
+        bool_only: bool = False,
+        skipna: bool = True,
+        **kwargs,
+    ) -> bool:
+        nv.validate_logical_func((), kwargs, fname="any")
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+        return self._reduce(
+            nanops.nanany,
+            name="any",
+            axis=axis,
+            numeric_only=bool_only,
+            skipna=skipna,
+            filter_type="bool",
+        )
+
+    @Appender(make_doc("all", ndim=1))
+    def all(
+        self,
+        axis: Axis = 0,
+        bool_only: bool = False,
+        skipna: bool = True,
+        **kwargs,
+    ) -> bool:
+        nv.validate_logical_func((), kwargs, fname="all")
+        validate_bool_kwarg(skipna, "skipna", none_allowed=False)
+        return self._reduce(
+            nanops.nanall,
+            name="all",
+            axis=axis,
+            numeric_only=bool_only,
+            skipna=skipna,
+            filter_type="bool",
+        )
+
+    @doc(make_doc("min", ndim=1))
+    def min(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.min(self, axis, skipna, numeric_only, **kwargs)
+
+    @doc(make_doc("max", ndim=1))
+    def max(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.max(self, axis, skipna, numeric_only, **kwargs)
+
+    @doc(make_doc("sum", ndim=1))
+    def sum(
+        self,
+        axis: Axis | None = None,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        return NDFrame.sum(self, axis, skipna, numeric_only, min_count, **kwargs)
+
+    @doc(make_doc("prod", ndim=1))
+    def prod(
+        self,
+        axis: Axis | None = None,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        min_count: int = 0,
+        **kwargs,
+    ):
+        return NDFrame.prod(self, axis, skipna, numeric_only, min_count, **kwargs)
+
+    @doc(make_doc("mean", ndim=1))
+    def mean(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.mean(self, axis, skipna, numeric_only, **kwargs)
+
+    @doc(make_doc("median", ndim=1))
+    def median(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.median(self, axis, skipna, numeric_only, **kwargs)
+
+    @doc(make_doc("sem", ndim=1))
+    def sem(
+        self,
+        axis: Axis | None = None,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.sem(self, axis, skipna, ddof, numeric_only, **kwargs)
+
+    @doc(make_doc("var", ndim=1))
+    def var(
+        self,
+        axis: Axis | None = None,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.var(self, axis, skipna, ddof, numeric_only, **kwargs)
+
+    @doc(make_doc("std", ndim=1))
+    def std(
+        self,
+        axis: Axis | None = None,
+        skipna: bool = True,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.std(self, axis, skipna, ddof, numeric_only, **kwargs)
+
+    @doc(make_doc("skew", ndim=1))
+    def skew(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.skew(self, axis, skipna, numeric_only, **kwargs)
+
+    @doc(make_doc("kurt", ndim=1))
+    def kurt(
+        self,
+        axis: Axis | None = 0,
+        skipna: bool = True,
+        numeric_only: bool = False,
+        **kwargs,
+    ):
+        return NDFrame.kurt(self, axis, skipna, numeric_only, **kwargs)
+
+    kurtosis = kurt
+    product = prod
+
+    @doc(make_doc("cummin", ndim=1))
+    def cummin(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cummin(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cummax", ndim=1))
+    def cummax(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cummax(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cumsum", ndim=1))
+    def cumsum(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cumsum(self, axis, skipna, *args, **kwargs)
+
+    @doc(make_doc("cumprod", 1))
+    def cumprod(self, axis: Axis | None = None, skipna: bool = True, *args, **kwargs):
+        return NDFrame.cumprod(self, axis, skipna, *args, **kwargs)
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/shared_docs.py b/.venv/lib/python3.13/site-packages/pandas/core/shared_docs.py
new file mode 100644
index 0000000000000000000000000000000000000000..25f7e7e9f832b0142af32acbb9690d0ae3f0b5e3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/shared_docs.py
@@ -0,0 +1,952 @@
+from __future__ import annotations
+
+_shared_docs: dict[str, str] = {}
+
+_shared_docs[
+    "aggregate"
+] = """
+Aggregate using one or more operations over the specified axis.
+
+Parameters
+----------
+func : function, str, list or dict
+    Function to use for aggregating the data. If a function, must either
+    work when passed a {klass} or when passed to {klass}.apply.
+
+    Accepted combinations are:
+
+    - function
+    - string function name
+    - list of functions and/or function names, e.g. ``[np.sum, 'mean']``
+    - dict of axis labels -> functions, function names or list of such.
+{axis}
+*args
+    Positional arguments to pass to `func`.
+**kwargs
+    Keyword arguments to pass to `func`.
+
+Returns
+-------
+scalar, Series or DataFrame
+
+    The return can be:
+
+    * scalar : when Series.agg is called with single function
+    * Series : when DataFrame.agg is called with a single function
+    * DataFrame : when DataFrame.agg is called with several functions
+{see_also}
+Notes
+-----
+The aggregation operations are always performed over an axis, either the
+index (default) or the column axis. This behavior is different from
+`numpy` aggregation functions (`mean`, `median`, `prod`, `sum`, `std`,
+`var`), where the default is to compute the aggregation of the flattened
+array, e.g., ``numpy.mean(arr_2d)`` as opposed to
+``numpy.mean(arr_2d, axis=0)``.
+
+`agg` is an alias for `aggregate`. Use the alias.
+
+Functions that mutate the passed object can produce unexpected
+behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+for more details.
+
+A passed user-defined-function will be passed a Series for evaluation.
+{examples}"""
+
+_shared_docs[
+    "compare"
+] = """
+Compare to another {klass} and show the differences.
+
+Parameters
+----------
+other : {klass}
+    Object to compare with.
+
+align_axis : {{0 or 'index', 1 or 'columns'}}, default 1
+    Determine which axis to align the comparison on.
+
+    * 0, or 'index' : Resulting differences are stacked vertically
+        with rows drawn alternately from self and other.
+    * 1, or 'columns' : Resulting differences are aligned horizontally
+        with columns drawn alternately from self and other.
+
+keep_shape : bool, default False
+    If true, all rows and columns are kept.
+    Otherwise, only the ones with different values are kept.
+
+keep_equal : bool, default False
+    If true, the result keeps values that are equal.
+    Otherwise, equal values are shown as NaNs.
+
+result_names : tuple, default ('self', 'other')
+    Set the dataframes names in the comparison.
+
+    .. versionadded:: 1.5.0
+"""
+
+_shared_docs[
+    "groupby"
+] = """
+Group %(klass)s using a mapper or by a Series of columns.
+
+A groupby operation involves some combination of splitting the
+object, applying a function, and combining the results. This can be
+used to group large amounts of data and compute operations on these
+groups.
+
+Parameters
+----------
+by : mapping, function, label, pd.Grouper or list of such
+    Used to determine the groups for the groupby.
+    If ``by`` is a function, it's called on each value of the object's
+    index. If a dict or Series is passed, the Series or dict VALUES
+    will be used to determine the groups (the Series' values are first
+    aligned; see ``.align()`` method). If a list or ndarray of length
+    equal to the selected axis is passed (see the `groupby user guide
+    `_),
+    the values are used as-is to determine the groups. A label or list
+    of labels may be passed to group by the columns in ``self``.
+    Notice that a tuple is interpreted as a (single) key.
+axis : {0 or 'index', 1 or 'columns'}, default 0
+    Split along rows (0) or columns (1). For `Series` this parameter
+    is unused and defaults to 0.
+
+    .. deprecated:: 2.1.0
+
+        Will be removed and behave like axis=0 in a future version.
+        For ``axis=1``, do ``frame.T.groupby(...)`` instead.
+
+level : int, level name, or sequence of such, default None
+    If the axis is a MultiIndex (hierarchical), group by a particular
+    level or levels. Do not specify both ``by`` and ``level``.
+as_index : bool, default True
+    Return object with group labels as the
+    index. Only relevant for DataFrame input. as_index=False is
+    effectively "SQL-style" grouped output. This argument has no effect
+    on filtrations (see the `filtrations in the user guide
+    `_),
+    such as ``head()``, ``tail()``, ``nth()`` and in transformations
+    (see the `transformations in the user guide
+    `_).
+sort : bool, default True
+    Sort group keys. Get better performance by turning this off.
+    Note this does not influence the order of observations within each
+    group. Groupby preserves the order of rows within each group. If False,
+    the groups will appear in the same order as they did in the original DataFrame.
+    This argument has no effect on filtrations (see the `filtrations in the user guide
+    `_),
+    such as ``head()``, ``tail()``, ``nth()`` and in transformations
+    (see the `transformations in the user guide
+    `_).
+
+    .. versionchanged:: 2.0.0
+
+        Specifying ``sort=False`` with an ordered categorical grouper will no
+        longer sort the values.
+
+group_keys : bool, default True
+    When calling apply and the ``by`` argument produces a like-indexed
+    (i.e. :ref:`a transform `) result, add group keys to
+    index to identify pieces. By default group keys are not included
+    when the result's index (and column) labels match the inputs, and
+    are included otherwise.
+
+    .. versionchanged:: 1.5.0
+
+       Warns that ``group_keys`` will no longer be ignored when the
+       result from ``apply`` is a like-indexed Series or DataFrame.
+       Specify ``group_keys`` explicitly to include the group keys or
+       not.
+
+    .. versionchanged:: 2.0.0
+
+       ``group_keys`` now defaults to ``True``.
+
+observed : bool, default False
+    This only applies if any of the groupers are Categoricals.
+    If True: only show observed values for categorical groupers.
+    If False: show all values for categorical groupers.
+
+    .. deprecated:: 2.1.0
+
+        The default value will change to True in a future version of pandas.
+
+dropna : bool, default True
+    If True, and if group keys contain NA values, NA values together
+    with row/column will be dropped.
+    If False, NA values will also be treated as the key in groups.
+
+Returns
+-------
+pandas.api.typing.%(klass)sGroupBy
+    Returns a groupby object that contains information about the groups.
+
+See Also
+--------
+resample : Convenience method for frequency conversion and resampling
+    of time series.
+
+Notes
+-----
+See the `user guide
+`__ for more
+detailed usage and examples, including splitting an object into groups,
+iterating through groups, selecting a group, aggregation, and more.
+"""
+
+_shared_docs[
+    "melt"
+] = """
+Unpivot a DataFrame from wide to long format, optionally leaving identifiers set.
+
+This function is useful to massage a DataFrame into a format where one
+or more columns are identifier variables (`id_vars`), while all other
+columns, considered measured variables (`value_vars`), are "unpivoted" to
+the row axis, leaving just two non-identifier columns, 'variable' and
+'value'.
+
+Parameters
+----------
+id_vars : scalar, tuple, list, or ndarray, optional
+    Column(s) to use as identifier variables.
+value_vars : scalar, tuple, list, or ndarray, optional
+    Column(s) to unpivot. If not specified, uses all columns that
+    are not set as `id_vars`.
+var_name : scalar, default None
+    Name to use for the 'variable' column. If None it uses
+    ``frame.columns.name`` or 'variable'.
+value_name : scalar, default 'value'
+    Name to use for the 'value' column, can't be an existing column label.
+col_level : scalar, optional
+    If columns are a MultiIndex then use this level to melt.
+ignore_index : bool, default True
+    If True, original index is ignored. If False, the original index is retained.
+    Index labels will be repeated as necessary.
+
+Returns
+-------
+DataFrame
+    Unpivoted DataFrame.
+
+See Also
+--------
+%(other)s : Identical method.
+pivot_table : Create a spreadsheet-style pivot table as a DataFrame.
+DataFrame.pivot : Return reshaped DataFrame organized
+    by given index / column values.
+DataFrame.explode : Explode a DataFrame from list-like
+        columns to long format.
+
+Notes
+-----
+Reference :ref:`the user guide ` for more examples.
+
+Examples
+--------
+>>> df = pd.DataFrame({'A': {0: 'a', 1: 'b', 2: 'c'},
+...                    'B': {0: 1, 1: 3, 2: 5},
+...                    'C': {0: 2, 1: 4, 2: 6}})
+>>> df
+   A  B  C
+0  a  1  2
+1  b  3  4
+2  c  5  6
+
+>>> %(caller)sid_vars=['A'], value_vars=['B'])
+   A variable  value
+0  a        B      1
+1  b        B      3
+2  c        B      5
+
+>>> %(caller)sid_vars=['A'], value_vars=['B', 'C'])
+   A variable  value
+0  a        B      1
+1  b        B      3
+2  c        B      5
+3  a        C      2
+4  b        C      4
+5  c        C      6
+
+The names of 'variable' and 'value' columns can be customized:
+
+>>> %(caller)sid_vars=['A'], value_vars=['B'],
+...         var_name='myVarname', value_name='myValname')
+   A myVarname  myValname
+0  a         B          1
+1  b         B          3
+2  c         B          5
+
+Original index values can be kept around:
+
+>>> %(caller)sid_vars=['A'], value_vars=['B', 'C'], ignore_index=False)
+   A variable  value
+0  a        B      1
+1  b        B      3
+2  c        B      5
+0  a        C      2
+1  b        C      4
+2  c        C      6
+
+If you have multi-index columns:
+
+>>> df.columns = [list('ABC'), list('DEF')]
+>>> df
+   A  B  C
+   D  E  F
+0  a  1  2
+1  b  3  4
+2  c  5  6
+
+>>> %(caller)scol_level=0, id_vars=['A'], value_vars=['B'])
+   A variable  value
+0  a        B      1
+1  b        B      3
+2  c        B      5
+
+>>> %(caller)sid_vars=[('A', 'D')], value_vars=[('B', 'E')])
+  (A, D) variable_0 variable_1  value
+0      a          B          E      1
+1      b          B          E      3
+2      c          B          E      5
+"""
+
+_shared_docs[
+    "transform"
+] = """
+Call ``func`` on self producing a {klass} with the same axis shape as self.
+
+Parameters
+----------
+func : function, str, list-like or dict-like
+    Function to use for transforming the data. If a function, must either
+    work when passed a {klass} or when passed to {klass}.apply. If func
+    is both list-like and dict-like, dict-like behavior takes precedence.
+
+    Accepted combinations are:
+
+    - function
+    - string function name
+    - list-like of functions and/or function names, e.g. ``[np.exp, 'sqrt']``
+    - dict-like of axis labels -> functions, function names or list-like of such.
+{axis}
+*args
+    Positional arguments to pass to `func`.
+**kwargs
+    Keyword arguments to pass to `func`.
+
+Returns
+-------
+{klass}
+    A {klass} that must have the same length as self.
+
+Raises
+------
+ValueError : If the returned {klass} has a different length than self.
+
+See Also
+--------
+{klass}.agg : Only perform aggregating type operations.
+{klass}.apply : Invoke function on a {klass}.
+
+Notes
+-----
+Functions that mutate the passed object can produce unexpected
+behavior or errors and are not supported. See :ref:`gotchas.udf-mutation`
+for more details.
+
+Examples
+--------
+>>> df = pd.DataFrame({{'A': range(3), 'B': range(1, 4)}})
+>>> df
+   A  B
+0  0  1
+1  1  2
+2  2  3
+>>> df.transform(lambda x: x + 1)
+   A  B
+0  1  2
+1  2  3
+2  3  4
+
+Even though the resulting {klass} must have the same length as the
+input {klass}, it is possible to provide several input functions:
+
+>>> s = pd.Series(range(3))
+>>> s
+0    0
+1    1
+2    2
+dtype: int64
+>>> s.transform([np.sqrt, np.exp])
+       sqrt        exp
+0  0.000000   1.000000
+1  1.000000   2.718282
+2  1.414214   7.389056
+
+You can call transform on a GroupBy object:
+
+>>> df = pd.DataFrame({{
+...     "Date": [
+...         "2015-05-08", "2015-05-07", "2015-05-06", "2015-05-05",
+...         "2015-05-08", "2015-05-07", "2015-05-06", "2015-05-05"],
+...     "Data": [5, 8, 6, 1, 50, 100, 60, 120],
+... }})
+>>> df
+         Date  Data
+0  2015-05-08     5
+1  2015-05-07     8
+2  2015-05-06     6
+3  2015-05-05     1
+4  2015-05-08    50
+5  2015-05-07   100
+6  2015-05-06    60
+7  2015-05-05   120
+>>> df.groupby('Date')['Data'].transform('sum')
+0     55
+1    108
+2     66
+3    121
+4     55
+5    108
+6     66
+7    121
+Name: Data, dtype: int64
+
+>>> df = pd.DataFrame({{
+...     "c": [1, 1, 1, 2, 2, 2, 2],
+...     "type": ["m", "n", "o", "m", "m", "n", "n"]
+... }})
+>>> df
+   c type
+0  1    m
+1  1    n
+2  1    o
+3  2    m
+4  2    m
+5  2    n
+6  2    n
+>>> df['size'] = df.groupby('c')['type'].transform(len)
+>>> df
+   c type size
+0  1    m    3
+1  1    n    3
+2  1    o    3
+3  2    m    4
+4  2    m    4
+5  2    n    4
+6  2    n    4
+"""
+
+_shared_docs[
+    "storage_options"
+] = """storage_options : dict, optional
+    Extra options that make sense for a particular storage connection, e.g.
+    host, port, username, password, etc. For HTTP(S) URLs the key-value pairs
+    are forwarded to ``urllib.request.Request`` as header options. For other
+    URLs (e.g. starting with "s3://", and "gcs://") the key-value pairs are
+    forwarded to ``fsspec.open``. Please see ``fsspec`` and ``urllib`` for more
+    details, and for more examples on storage options refer `here
+    `_."""
+
+_shared_docs[
+    "compression_options"
+] = """compression : str or dict, default 'infer'
+    For on-the-fly compression of the output data. If 'infer' and '%s' is
+    path-like, then detect compression from the following extensions: '.gz',
+    '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2'
+    (otherwise no compression).
+    Set to ``None`` for no compression.
+    Can also be a dict with key ``'method'`` set
+    to one of {``'zip'``, ``'gzip'``, ``'bz2'``, ``'zstd'``, ``'xz'``, ``'tar'``} and
+    other key-value pairs are forwarded to
+    ``zipfile.ZipFile``, ``gzip.GzipFile``,
+    ``bz2.BZ2File``, ``zstandard.ZstdCompressor``, ``lzma.LZMAFile`` or
+    ``tarfile.TarFile``, respectively.
+    As an example, the following could be passed for faster compression and to create
+    a reproducible gzip archive:
+    ``compression={'method': 'gzip', 'compresslevel': 1, 'mtime': 1}``.
+
+    .. versionadded:: 1.5.0
+        Added support for `.tar` files."""
+
+_shared_docs[
+    "decompression_options"
+] = """compression : str or dict, default 'infer'
+    For on-the-fly decompression of on-disk data. If 'infer' and '%s' is
+    path-like, then detect compression from the following extensions: '.gz',
+    '.bz2', '.zip', '.xz', '.zst', '.tar', '.tar.gz', '.tar.xz' or '.tar.bz2'
+    (otherwise no compression).
+    If using 'zip' or 'tar', the ZIP file must contain only one data file to be read in.
+    Set to ``None`` for no decompression.
+    Can also be a dict with key ``'method'`` set
+    to one of {``'zip'``, ``'gzip'``, ``'bz2'``, ``'zstd'``, ``'xz'``, ``'tar'``} and
+    other key-value pairs are forwarded to
+    ``zipfile.ZipFile``, ``gzip.GzipFile``,
+    ``bz2.BZ2File``, ``zstandard.ZstdDecompressor``, ``lzma.LZMAFile`` or
+    ``tarfile.TarFile``, respectively.
+    As an example, the following could be passed for Zstandard decompression using a
+    custom compression dictionary:
+    ``compression={'method': 'zstd', 'dict_data': my_compression_dict}``.
+
+    .. versionadded:: 1.5.0
+        Added support for `.tar` files."""
+
+_shared_docs[
+    "replace"
+] = """
+    Replace values given in `to_replace` with `value`.
+
+    Values of the {klass} are replaced with other values dynamically.
+    This differs from updating with ``.loc`` or ``.iloc``, which require
+    you to specify a location to update with some value.
+
+    Parameters
+    ----------
+    to_replace : str, regex, list, dict, Series, int, float, or None
+        How to find the values that will be replaced.
+
+        * numeric, str or regex:
+
+            - numeric: numeric values equal to `to_replace` will be
+              replaced with `value`
+            - str: string exactly matching `to_replace` will be replaced
+              with `value`
+            - regex: regexs matching `to_replace` will be replaced with
+              `value`
+
+        * list of str, regex, or numeric:
+
+            - First, if `to_replace` and `value` are both lists, they
+              **must** be the same length.
+            - Second, if ``regex=True`` then all of the strings in **both**
+              lists will be interpreted as regexs otherwise they will match
+              directly. This doesn't matter much for `value` since there
+              are only a few possible substitution regexes you can use.
+            - str, regex and numeric rules apply as above.
+
+        * dict:
+
+            - Dicts can be used to specify different replacement values
+              for different existing values. For example,
+              ``{{'a': 'b', 'y': 'z'}}`` replaces the value 'a' with 'b' and
+              'y' with 'z'. To use a dict in this way, the optional `value`
+              parameter should not be given.
+            - For a DataFrame a dict can specify that different values
+              should be replaced in different columns. For example,
+              ``{{'a': 1, 'b': 'z'}}`` looks for the value 1 in column 'a'
+              and the value 'z' in column 'b' and replaces these values
+              with whatever is specified in `value`. The `value` parameter
+              should not be ``None`` in this case. You can treat this as a
+              special case of passing two lists except that you are
+              specifying the column to search in.
+            - For a DataFrame nested dictionaries, e.g.,
+              ``{{'a': {{'b': np.nan}}}}``, are read as follows: look in column
+              'a' for the value 'b' and replace it with NaN. The optional `value`
+              parameter should not be specified to use a nested dict in this
+              way. You can nest regular expressions as well. Note that
+              column names (the top-level dictionary keys in a nested
+              dictionary) **cannot** be regular expressions.
+
+        * None:
+
+            - This means that the `regex` argument must be a string,
+              compiled regular expression, or list, dict, ndarray or
+              Series of such elements. If `value` is also ``None`` then
+              this **must** be a nested dictionary or Series.
+
+        See the examples section for examples of each of these.
+    value : scalar, dict, list, str, regex, default None
+        Value to replace any values matching `to_replace` with.
+        For a DataFrame a dict of values can be used to specify which
+        value to use for each column (columns not in the dict will not be
+        filled). Regular expressions, strings and lists or dicts of such
+        objects are also allowed.
+    {inplace}
+    limit : int, default None
+        Maximum size gap to forward or backward fill.
+
+        .. deprecated:: 2.1.0
+    regex : bool or same types as `to_replace`, default False
+        Whether to interpret `to_replace` and/or `value` as regular
+        expressions. Alternatively, this could be a regular expression or a
+        list, dict, or array of regular expressions in which case
+        `to_replace` must be ``None``.
+    method : {{'pad', 'ffill', 'bfill'}}
+        The method to use when for replacement, when `to_replace` is a
+        scalar, list or tuple and `value` is ``None``.
+
+        .. deprecated:: 2.1.0
+
+    Returns
+    -------
+    {klass}
+        Object after replacement.
+
+    Raises
+    ------
+    AssertionError
+        * If `regex` is not a ``bool`` and `to_replace` is not
+          ``None``.
+
+    TypeError
+        * If `to_replace` is not a scalar, array-like, ``dict``, or ``None``
+        * If `to_replace` is a ``dict`` and `value` is not a ``list``,
+          ``dict``, ``ndarray``, or ``Series``
+        * If `to_replace` is ``None`` and `regex` is not compilable
+          into a regular expression or is a list, dict, ndarray, or
+          Series.
+        * When replacing multiple ``bool`` or ``datetime64`` objects and
+          the arguments to `to_replace` does not match the type of the
+          value being replaced
+
+    ValueError
+        * If a ``list`` or an ``ndarray`` is passed to `to_replace` and
+          `value` but they are not the same length.
+
+    See Also
+    --------
+    Series.fillna : Fill NA values.
+    DataFrame.fillna : Fill NA values.
+    Series.where : Replace values based on boolean condition.
+    DataFrame.where : Replace values based on boolean condition.
+    DataFrame.map: Apply a function to a Dataframe elementwise.
+    Series.map: Map values of Series according to an input mapping or function.
+    Series.str.replace : Simple string replacement.
+
+    Notes
+    -----
+    * Regex substitution is performed under the hood with ``re.sub``. The
+      rules for substitution for ``re.sub`` are the same.
+    * Regular expressions will only substitute on strings, meaning you
+      cannot provide, for example, a regular expression matching floating
+      point numbers and expect the columns in your frame that have a
+      numeric dtype to be matched. However, if those floating point
+      numbers *are* strings, then you can do this.
+    * This method has *a lot* of options. You are encouraged to experiment
+      and play with this method to gain intuition about how it works.
+    * When dict is used as the `to_replace` value, it is like
+      key(s) in the dict are the to_replace part and
+      value(s) in the dict are the value parameter.
+
+    Examples
+    --------
+
+    **Scalar `to_replace` and `value`**
+
+    >>> s = pd.Series([1, 2, 3, 4, 5])
+    >>> s.replace(1, 5)
+    0    5
+    1    2
+    2    3
+    3    4
+    4    5
+    dtype: int64
+
+    >>> df = pd.DataFrame({{'A': [0, 1, 2, 3, 4],
+    ...                    'B': [5, 6, 7, 8, 9],
+    ...                    'C': ['a', 'b', 'c', 'd', 'e']}})
+    >>> df.replace(0, 5)
+        A  B  C
+    0  5  5  a
+    1  1  6  b
+    2  2  7  c
+    3  3  8  d
+    4  4  9  e
+
+    **List-like `to_replace`**
+
+    >>> df.replace([0, 1, 2, 3], 4)
+        A  B  C
+    0  4  5  a
+    1  4  6  b
+    2  4  7  c
+    3  4  8  d
+    4  4  9  e
+
+    >>> df.replace([0, 1, 2, 3], [4, 3, 2, 1])
+        A  B  C
+    0  4  5  a
+    1  3  6  b
+    2  2  7  c
+    3  1  8  d
+    4  4  9  e
+
+    >>> s.replace([1, 2], method='bfill')
+    0    3
+    1    3
+    2    3
+    3    4
+    4    5
+    dtype: int64
+
+    **dict-like `to_replace`**
+
+    >>> df.replace({{0: 10, 1: 100}})
+            A  B  C
+    0   10  5  a
+    1  100  6  b
+    2    2  7  c
+    3    3  8  d
+    4    4  9  e
+
+    >>> df.replace({{'A': 0, 'B': 5}}, 100)
+            A    B  C
+    0  100  100  a
+    1    1    6  b
+    2    2    7  c
+    3    3    8  d
+    4    4    9  e
+
+    >>> df.replace({{'A': {{0: 100, 4: 400}}}})
+            A  B  C
+    0  100  5  a
+    1    1  6  b
+    2    2  7  c
+    3    3  8  d
+    4  400  9  e
+
+    **Regular expression `to_replace`**
+
+    >>> df = pd.DataFrame({{'A': ['bat', 'foo', 'bait'],
+    ...                    'B': ['abc', 'bar', 'xyz']}})
+    >>> df.replace(to_replace=r'^ba.$', value='new', regex=True)
+            A    B
+    0   new  abc
+    1   foo  new
+    2  bait  xyz
+
+    >>> df.replace({{'A': r'^ba.$'}}, {{'A': 'new'}}, regex=True)
+            A    B
+    0   new  abc
+    1   foo  bar
+    2  bait  xyz
+
+    >>> df.replace(regex=r'^ba.$', value='new')
+            A    B
+    0   new  abc
+    1   foo  new
+    2  bait  xyz
+
+    >>> df.replace(regex={{r'^ba.$': 'new', 'foo': 'xyz'}})
+            A    B
+    0   new  abc
+    1   xyz  new
+    2  bait  xyz
+
+    >>> df.replace(regex=[r'^ba.$', 'foo'], value='new')
+            A    B
+    0   new  abc
+    1   new  new
+    2  bait  xyz
+
+    Compare the behavior of ``s.replace({{'a': None}})`` and
+    ``s.replace('a', None)`` to understand the peculiarities
+    of the `to_replace` parameter:
+
+    >>> s = pd.Series([10, 'a', 'a', 'b', 'a'])
+
+    When one uses a dict as the `to_replace` value, it is like the
+    value(s) in the dict are equal to the `value` parameter.
+    ``s.replace({{'a': None}})`` is equivalent to
+    ``s.replace(to_replace={{'a': None}}, value=None, method=None)``:
+
+    >>> s.replace({{'a': None}})
+    0      10
+    1    None
+    2    None
+    3       b
+    4    None
+    dtype: object
+
+    When ``value`` is not explicitly passed and `to_replace` is a scalar, list
+    or tuple, `replace` uses the method parameter (default 'pad') to do the
+    replacement. So this is why the 'a' values are being replaced by 10
+    in rows 1 and 2 and 'b' in row 4 in this case.
+
+    >>> s.replace('a')
+    0    10
+    1    10
+    2    10
+    3     b
+    4     b
+    dtype: object
+
+        .. deprecated:: 2.1.0
+            The 'method' parameter and padding behavior are deprecated.
+
+    On the other hand, if ``None`` is explicitly passed for ``value``, it will
+    be respected:
+
+    >>> s.replace('a', None)
+    0      10
+    1    None
+    2    None
+    3       b
+    4    None
+    dtype: object
+
+        .. versionchanged:: 1.4.0
+            Previously the explicit ``None`` was silently ignored.
+
+    When ``regex=True``, ``value`` is not ``None`` and `to_replace` is a string,
+    the replacement will be applied in all columns of the DataFrame.
+
+    >>> df = pd.DataFrame({{'A': [0, 1, 2, 3, 4],
+    ...                    'B': ['a', 'b', 'c', 'd', 'e'],
+    ...                    'C': ['f', 'g', 'h', 'i', 'j']}})
+
+    >>> df.replace(to_replace='^[a-g]', value='e', regex=True)
+        A  B  C
+    0  0  e  e
+    1  1  e  e
+    2  2  e  h
+    3  3  e  i
+    4  4  e  j
+
+    If ``value`` is not ``None`` and `to_replace` is a dictionary, the dictionary
+    keys will be the DataFrame columns that the replacement will be applied.
+
+    >>> df.replace(to_replace={{'B': '^[a-c]', 'C': '^[h-j]'}}, value='e', regex=True)
+        A  B  C
+    0  0  e  f
+    1  1  e  g
+    2  2  e  e
+    3  3  d  e
+    4  4  e  e
+"""
+
+_shared_docs[
+    "idxmin"
+] = """
+    Return index of first occurrence of minimum over requested axis.
+
+    NA/null values are excluded.
+
+    Parameters
+    ----------
+    axis : {{0 or 'index', 1 or 'columns'}}, default 0
+        The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+    skipna : bool, default True
+        Exclude NA/null values. If an entire row/column is NA, the result
+        will be NA.
+    numeric_only : bool, default {numeric_only_default}
+        Include only `float`, `int` or `boolean` data.
+
+        .. versionadded:: 1.5.0
+
+    Returns
+    -------
+    Series
+        Indexes of minima along the specified axis.
+
+    Raises
+    ------
+    ValueError
+        * If the row/column is empty
+
+    See Also
+    --------
+    Series.idxmin : Return index of the minimum element.
+
+    Notes
+    -----
+    This method is the DataFrame version of ``ndarray.argmin``.
+
+    Examples
+    --------
+    Consider a dataset containing food consumption in Argentina.
+
+    >>> df = pd.DataFrame({{'consumption': [10.51, 103.11, 55.48],
+    ...                     'co2_emissions': [37.2, 19.66, 1712]}},
+    ...                   index=['Pork', 'Wheat Products', 'Beef'])
+
+    >>> df
+                    consumption  co2_emissions
+    Pork                  10.51         37.20
+    Wheat Products       103.11         19.66
+    Beef                  55.48       1712.00
+
+    By default, it returns the index for the minimum value in each column.
+
+    >>> df.idxmin()
+    consumption                Pork
+    co2_emissions    Wheat Products
+    dtype: object
+
+    To return the index for the minimum value in each row, use ``axis="columns"``.
+
+    >>> df.idxmin(axis="columns")
+    Pork                consumption
+    Wheat Products    co2_emissions
+    Beef                consumption
+    dtype: object
+"""
+
+_shared_docs[
+    "idxmax"
+] = """
+    Return index of first occurrence of maximum over requested axis.
+
+    NA/null values are excluded.
+
+    Parameters
+    ----------
+    axis : {{0 or 'index', 1 or 'columns'}}, default 0
+        The axis to use. 0 or 'index' for row-wise, 1 or 'columns' for column-wise.
+    skipna : bool, default True
+        Exclude NA/null values. If an entire row/column is NA, the result
+        will be NA.
+    numeric_only : bool, default {numeric_only_default}
+        Include only `float`, `int` or `boolean` data.
+
+        .. versionadded:: 1.5.0
+
+    Returns
+    -------
+    Series
+        Indexes of maxima along the specified axis.
+
+    Raises
+    ------
+    ValueError
+        * If the row/column is empty
+
+    See Also
+    --------
+    Series.idxmax : Return index of the maximum element.
+
+    Notes
+    -----
+    This method is the DataFrame version of ``ndarray.argmax``.
+
+    Examples
+    --------
+    Consider a dataset containing food consumption in Argentina.
+
+    >>> df = pd.DataFrame({{'consumption': [10.51, 103.11, 55.48],
+    ...                     'co2_emissions': [37.2, 19.66, 1712]}},
+    ...                   index=['Pork', 'Wheat Products', 'Beef'])
+
+    >>> df
+                    consumption  co2_emissions
+    Pork                  10.51         37.20
+    Wheat Products       103.11         19.66
+    Beef                  55.48       1712.00
+
+    By default, it returns the index for the maximum value in each column.
+
+    >>> df.idxmax()
+    consumption     Wheat Products
+    co2_emissions             Beef
+    dtype: object
+
+    To return the index for the maximum value in each row, use ``axis="columns"``.
+
+    >>> df.idxmax(axis="columns")
+    Pork              co2_emissions
+    Wheat Products     consumption
+    Beef              co2_emissions
+    dtype: object
+"""
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/sorting.py b/.venv/lib/python3.13/site-packages/pandas/core/sorting.py
new file mode 100644
index 0000000000000000000000000000000000000000..a431842218b3bbb97cb5373e03d2a31a4f69ca10
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/sorting.py
@@ -0,0 +1,748 @@
+""" miscellaneous sorting / groupby utilities """
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    DefaultDict,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import (
+    algos,
+    hashtable,
+    lib,
+)
+from pandas._libs.hashtable import unique_label_indices
+
+from pandas.core.dtypes.common import (
+    ensure_int64,
+    ensure_platform_int,
+)
+from pandas.core.dtypes.generic import (
+    ABCMultiIndex,
+    ABCRangeIndex,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.construction import extract_array
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        AxisInt,
+        IndexKeyFunc,
+        Level,
+        NaPosition,
+        Shape,
+        SortKind,
+        npt,
+    )
+
+    from pandas import (
+        MultiIndex,
+        Series,
+    )
+    from pandas.core.arrays import ExtensionArray
+    from pandas.core.indexes.base import Index
+
+
+def get_indexer_indexer(
+    target: Index,
+    level: Level | list[Level] | None,
+    ascending: list[bool] | bool,
+    kind: SortKind,
+    na_position: NaPosition,
+    sort_remaining: bool,
+    key: IndexKeyFunc,
+) -> npt.NDArray[np.intp] | None:
+    """
+    Helper method that return the indexer according to input parameters for
+    the sort_index method of DataFrame and Series.
+
+    Parameters
+    ----------
+    target : Index
+    level : int or level name or list of ints or list of level names
+    ascending : bool or list of bools, default True
+    kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}
+    na_position : {'first', 'last'}
+    sort_remaining : bool
+    key : callable, optional
+
+    Returns
+    -------
+    Optional[ndarray[intp]]
+        The indexer for the new index.
+    """
+
+    # error: Incompatible types in assignment (expression has type
+    # "Union[ExtensionArray, ndarray[Any, Any], Index, Series]", variable has
+    # type "Index")
+    target = ensure_key_mapped(target, key, levels=level)  # type: ignore[assignment]
+    target = target._sort_levels_monotonic()
+
+    if level is not None:
+        _, indexer = target.sortlevel(
+            level,
+            ascending=ascending,
+            sort_remaining=sort_remaining,
+            na_position=na_position,
+        )
+    elif (np.all(ascending) and target.is_monotonic_increasing) or (
+        not np.any(ascending) and target.is_monotonic_decreasing
+    ):
+        # Check monotonic-ness before sort an index (GH 11080)
+        return None
+    elif isinstance(target, ABCMultiIndex):
+        codes = [lev.codes for lev in target._get_codes_for_sorting()]
+        indexer = lexsort_indexer(
+            codes, orders=ascending, na_position=na_position, codes_given=True
+        )
+    else:
+        # ascending can only be a Sequence for MultiIndex
+        indexer = nargsort(
+            target,
+            kind=kind,
+            ascending=cast(bool, ascending),
+            na_position=na_position,
+        )
+    return indexer
+
+
+def get_group_index(
+    labels, shape: Shape, sort: bool, xnull: bool
+) -> npt.NDArray[np.int64]:
+    """
+    For the particular label_list, gets the offsets into the hypothetical list
+    representing the totally ordered cartesian product of all possible label
+    combinations, *as long as* this space fits within int64 bounds;
+    otherwise, though group indices identify unique combinations of
+    labels, they cannot be deconstructed.
+    - If `sort`, rank of returned ids preserve lexical ranks of labels.
+      i.e. returned id's can be used to do lexical sort on labels;
+    - If `xnull` nulls (-1 labels) are passed through.
+
+    Parameters
+    ----------
+    labels : sequence of arrays
+        Integers identifying levels at each location
+    shape : tuple[int, ...]
+        Number of unique levels at each location
+    sort : bool
+        If the ranks of returned ids should match lexical ranks of labels
+    xnull : bool
+        If true nulls are excluded. i.e. -1 values in the labels are
+        passed through.
+
+    Returns
+    -------
+    An array of type int64 where two elements are equal if their corresponding
+    labels are equal at all location.
+
+    Notes
+    -----
+    The length of `labels` and `shape` must be identical.
+    """
+
+    def _int64_cut_off(shape) -> int:
+        acc = 1
+        for i, mul in enumerate(shape):
+            acc *= int(mul)
+            if not acc < lib.i8max:
+                return i
+        return len(shape)
+
+    def maybe_lift(lab, size: int) -> tuple[np.ndarray, int]:
+        # promote nan values (assigned -1 label in lab array)
+        # so that all output values are non-negative
+        return (lab + 1, size + 1) if (lab == -1).any() else (lab, size)
+
+    labels = [ensure_int64(x) for x in labels]
+    lshape = list(shape)
+    if not xnull:
+        for i, (lab, size) in enumerate(zip(labels, shape)):
+            labels[i], lshape[i] = maybe_lift(lab, size)
+
+    labels = list(labels)
+
+    # Iteratively process all the labels in chunks sized so less
+    # than lib.i8max unique int ids will be required for each chunk
+    while True:
+        # how many levels can be done without overflow:
+        nlev = _int64_cut_off(lshape)
+
+        # compute flat ids for the first `nlev` levels
+        stride = np.prod(lshape[1:nlev], dtype="i8")
+        out = stride * labels[0].astype("i8", subok=False, copy=False)
+
+        for i in range(1, nlev):
+            if lshape[i] == 0:
+                stride = np.int64(0)
+            else:
+                stride //= lshape[i]
+            out += labels[i] * stride
+
+        if xnull:  # exclude nulls
+            mask = labels[0] == -1
+            for lab in labels[1:nlev]:
+                mask |= lab == -1
+            out[mask] = -1
+
+        if nlev == len(lshape):  # all levels done!
+            break
+
+        # compress what has been done so far in order to avoid overflow
+        # to retain lexical ranks, obs_ids should be sorted
+        comp_ids, obs_ids = compress_group_index(out, sort=sort)
+
+        labels = [comp_ids] + labels[nlev:]
+        lshape = [len(obs_ids)] + lshape[nlev:]
+
+    return out
+
+
+def get_compressed_ids(
+    labels, sizes: Shape
+) -> tuple[npt.NDArray[np.intp], npt.NDArray[np.int64]]:
+    """
+    Group_index is offsets into cartesian product of all possible labels. This
+    space can be huge, so this function compresses it, by computing offsets
+    (comp_ids) into the list of unique labels (obs_group_ids).
+
+    Parameters
+    ----------
+    labels : list of label arrays
+    sizes : tuple[int] of size of the levels
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+        comp_ids
+    np.ndarray[np.int64]
+        obs_group_ids
+    """
+    ids = get_group_index(labels, sizes, sort=True, xnull=False)
+    return compress_group_index(ids, sort=True)
+
+
+def is_int64_overflow_possible(shape: Shape) -> bool:
+    the_prod = 1
+    for x in shape:
+        the_prod *= int(x)
+
+    return the_prod >= lib.i8max
+
+
+def _decons_group_index(
+    comp_labels: npt.NDArray[np.intp], shape: Shape
+) -> list[npt.NDArray[np.intp]]:
+    # reconstruct labels
+    if is_int64_overflow_possible(shape):
+        # at some point group indices are factorized,
+        # and may not be deconstructed here! wrong path!
+        raise ValueError("cannot deconstruct factorized group indices!")
+
+    label_list = []
+    factor = 1
+    y = np.array(0)
+    x = comp_labels
+    for i in reversed(range(len(shape))):
+        labels = (x - y) % (factor * shape[i]) // factor
+        np.putmask(labels, comp_labels < 0, -1)
+        label_list.append(labels)
+        y = labels * factor
+        factor *= shape[i]
+    return label_list[::-1]
+
+
+def decons_obs_group_ids(
+    comp_ids: npt.NDArray[np.intp],
+    obs_ids: npt.NDArray[np.intp],
+    shape: Shape,
+    labels: Sequence[npt.NDArray[np.signedinteger]],
+    xnull: bool,
+) -> list[npt.NDArray[np.intp]]:
+    """
+    Reconstruct labels from observed group ids.
+
+    Parameters
+    ----------
+    comp_ids : np.ndarray[np.intp]
+    obs_ids: np.ndarray[np.intp]
+    shape : tuple[int]
+    labels : Sequence[np.ndarray[np.signedinteger]]
+    xnull : bool
+        If nulls are excluded; i.e. -1 labels are passed through.
+    """
+    if not xnull:
+        lift = np.fromiter(((a == -1).any() for a in labels), dtype=np.intp)
+        arr_shape = np.asarray(shape, dtype=np.intp) + lift
+        shape = tuple(arr_shape)
+
+    if not is_int64_overflow_possible(shape):
+        # obs ids are deconstructable! take the fast route!
+        out = _decons_group_index(obs_ids, shape)
+        return out if xnull or not lift.any() else [x - y for x, y in zip(out, lift)]
+
+    indexer = unique_label_indices(comp_ids)
+    return [lab[indexer].astype(np.intp, subok=False, copy=True) for lab in labels]
+
+
+def lexsort_indexer(
+    keys: Sequence[ArrayLike | Index | Series],
+    orders=None,
+    na_position: str = "last",
+    key: Callable | None = None,
+    codes_given: bool = False,
+) -> npt.NDArray[np.intp]:
+    """
+    Performs lexical sorting on a set of keys
+
+    Parameters
+    ----------
+    keys : Sequence[ArrayLike | Index | Series]
+        Sequence of arrays to be sorted by the indexer
+        Sequence[Series] is only if key is not None.
+    orders : bool or list of booleans, optional
+        Determines the sorting order for each element in keys. If a list,
+        it must be the same length as keys. This determines whether the
+        corresponding element in keys should be sorted in ascending
+        (True) or descending (False) order. if bool, applied to all
+        elements as above. if None, defaults to True.
+    na_position : {'first', 'last'}, default 'last'
+        Determines placement of NA elements in the sorted list ("last" or "first")
+    key : Callable, optional
+        Callable key function applied to every element in keys before sorting
+    codes_given: bool, False
+        Avoid categorical materialization if codes are already provided.
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+    """
+    from pandas.core.arrays import Categorical
+
+    if na_position not in ["last", "first"]:
+        raise ValueError(f"invalid na_position: {na_position}")
+
+    if isinstance(orders, bool):
+        orders = [orders] * len(keys)
+    elif orders is None:
+        orders = [True] * len(keys)
+
+    labels = []
+
+    for k, order in zip(keys, orders):
+        k = ensure_key_mapped(k, key)
+        if codes_given:
+            codes = cast(np.ndarray, k)
+            n = codes.max() + 1 if len(codes) else 0
+        else:
+            cat = Categorical(k, ordered=True)
+            codes = cat.codes
+            n = len(cat.categories)
+
+        mask = codes == -1
+
+        if na_position == "last" and mask.any():
+            codes = np.where(mask, n, codes)
+
+        # not order means descending
+        if not order:
+            codes = np.where(mask, codes, n - codes - 1)
+
+        labels.append(codes)
+
+    return np.lexsort(labels[::-1])
+
+
+def nargsort(
+    items: ArrayLike | Index | Series,
+    kind: SortKind = "quicksort",
+    ascending: bool = True,
+    na_position: str = "last",
+    key: Callable | None = None,
+    mask: npt.NDArray[np.bool_] | None = None,
+) -> npt.NDArray[np.intp]:
+    """
+    Intended to be a drop-in replacement for np.argsort which handles NaNs.
+
+    Adds ascending, na_position, and key parameters.
+
+    (GH #6399, #5231, #27237)
+
+    Parameters
+    ----------
+    items : np.ndarray, ExtensionArray, Index, or Series
+    kind : {'quicksort', 'mergesort', 'heapsort', 'stable'}, default 'quicksort'
+    ascending : bool, default True
+    na_position : {'first', 'last'}, default 'last'
+    key : Optional[Callable], default None
+    mask : Optional[np.ndarray[bool]], default None
+        Passed when called by ExtensionArray.argsort.
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+    """
+
+    if key is not None:
+        # see TestDataFrameSortKey, TestRangeIndex::test_sort_values_key
+        items = ensure_key_mapped(items, key)
+        return nargsort(
+            items,
+            kind=kind,
+            ascending=ascending,
+            na_position=na_position,
+            key=None,
+            mask=mask,
+        )
+
+    if isinstance(items, ABCRangeIndex):
+        return items.argsort(ascending=ascending)
+    elif not isinstance(items, ABCMultiIndex):
+        items = extract_array(items)
+    else:
+        raise TypeError(
+            "nargsort does not support MultiIndex. Use index.sort_values instead."
+        )
+
+    if mask is None:
+        mask = np.asarray(isna(items))
+
+    if not isinstance(items, np.ndarray):
+        # i.e. ExtensionArray
+        return items.argsort(
+            ascending=ascending,
+            kind=kind,
+            na_position=na_position,
+        )
+
+    idx = np.arange(len(items))
+    non_nans = items[~mask]
+    non_nan_idx = idx[~mask]
+
+    nan_idx = np.nonzero(mask)[0]
+    if not ascending:
+        non_nans = non_nans[::-1]
+        non_nan_idx = non_nan_idx[::-1]
+    indexer = non_nan_idx[non_nans.argsort(kind=kind)]
+    if not ascending:
+        indexer = indexer[::-1]
+    # Finally, place the NaNs at the end or the beginning according to
+    # na_position
+    if na_position == "last":
+        indexer = np.concatenate([indexer, nan_idx])
+    elif na_position == "first":
+        indexer = np.concatenate([nan_idx, indexer])
+    else:
+        raise ValueError(f"invalid na_position: {na_position}")
+    return ensure_platform_int(indexer)
+
+
+def nargminmax(values: ExtensionArray, method: str, axis: AxisInt = 0):
+    """
+    Implementation of np.argmin/argmax but for ExtensionArray and which
+    handles missing values.
+
+    Parameters
+    ----------
+    values : ExtensionArray
+    method : {"argmax", "argmin"}
+    axis : int, default 0
+
+    Returns
+    -------
+    int
+    """
+    assert method in {"argmax", "argmin"}
+    func = np.argmax if method == "argmax" else np.argmin
+
+    mask = np.asarray(isna(values))
+    arr_values = values._values_for_argsort()
+
+    if arr_values.ndim > 1:
+        if mask.any():
+            if axis == 1:
+                zipped = zip(arr_values, mask)
+            else:
+                zipped = zip(arr_values.T, mask.T)
+            return np.array([_nanargminmax(v, m, func) for v, m in zipped])
+        return func(arr_values, axis=axis)
+
+    return _nanargminmax(arr_values, mask, func)
+
+
+def _nanargminmax(values: np.ndarray, mask: npt.NDArray[np.bool_], func) -> int:
+    """
+    See nanargminmax.__doc__.
+    """
+    idx = np.arange(values.shape[0])
+    non_nans = values[~mask]
+    non_nan_idx = idx[~mask]
+
+    return non_nan_idx[func(non_nans)]
+
+
+def _ensure_key_mapped_multiindex(
+    index: MultiIndex, key: Callable, level=None
+) -> MultiIndex:
+    """
+    Returns a new MultiIndex in which key has been applied
+    to all levels specified in level (or all levels if level
+    is None). Used for key sorting for MultiIndex.
+
+    Parameters
+    ----------
+    index : MultiIndex
+        Index to which to apply the key function on the
+        specified levels.
+    key : Callable
+        Function that takes an Index and returns an Index of
+        the same shape. This key is applied to each level
+        separately. The name of the level can be used to
+        distinguish different levels for application.
+    level : list-like, int or str, default None
+        Level or list of levels to apply the key function to.
+        If None, key function is applied to all levels. Other
+        levels are left unchanged.
+
+    Returns
+    -------
+    labels : MultiIndex
+        Resulting MultiIndex with modified levels.
+    """
+
+    if level is not None:
+        if isinstance(level, (str, int)):
+            sort_levels = [level]
+        else:
+            sort_levels = level
+
+        sort_levels = [index._get_level_number(lev) for lev in sort_levels]
+    else:
+        sort_levels = list(range(index.nlevels))  # satisfies mypy
+
+    mapped = [
+        ensure_key_mapped(index._get_level_values(level), key)
+        if level in sort_levels
+        else index._get_level_values(level)
+        for level in range(index.nlevels)
+    ]
+
+    return type(index).from_arrays(mapped)
+
+
+def ensure_key_mapped(
+    values: ArrayLike | Index | Series, key: Callable | None, levels=None
+) -> ArrayLike | Index | Series:
+    """
+    Applies a callable key function to the values function and checks
+    that the resulting value has the same shape. Can be called on Index
+    subclasses, Series, DataFrames, or ndarrays.
+
+    Parameters
+    ----------
+    values : Series, DataFrame, Index subclass, or ndarray
+    key : Optional[Callable], key to be called on the values array
+    levels : Optional[List], if values is a MultiIndex, list of levels to
+    apply the key to.
+    """
+    from pandas.core.indexes.api import Index
+
+    if not key:
+        return values
+
+    if isinstance(values, ABCMultiIndex):
+        return _ensure_key_mapped_multiindex(values, key, level=levels)
+
+    result = key(values.copy())
+    if len(result) != len(values):
+        raise ValueError(
+            "User-provided `key` function must not change the shape of the array."
+        )
+
+    try:
+        if isinstance(
+            values, Index
+        ):  # convert to a new Index subclass, not necessarily the same
+            result = Index(result)
+        else:
+            # try to revert to original type otherwise
+            type_of_values = type(values)
+            #  error: Too many arguments for "ExtensionArray"
+            result = type_of_values(result)  # type: ignore[call-arg]
+    except TypeError:
+        raise TypeError(
+            f"User-provided `key` function returned an invalid type {type(result)} \
+            which could not be converted to {type(values)}."
+        )
+
+    return result
+
+
+def get_flattened_list(
+    comp_ids: npt.NDArray[np.intp],
+    ngroups: int,
+    levels: Iterable[Index],
+    labels: Iterable[np.ndarray],
+) -> list[tuple]:
+    """Map compressed group id -> key tuple."""
+    comp_ids = comp_ids.astype(np.int64, copy=False)
+    arrays: DefaultDict[int, list[int]] = defaultdict(list)
+    for labs, level in zip(labels, levels):
+        table = hashtable.Int64HashTable(ngroups)
+        table.map_keys_to_values(comp_ids, labs.astype(np.int64, copy=False))
+        for i in range(ngroups):
+            arrays[i].append(level[table.get_item(i)])
+    return [tuple(array) for array in arrays.values()]
+
+
+def get_indexer_dict(
+    label_list: list[np.ndarray], keys: list[Index]
+) -> dict[Hashable, npt.NDArray[np.intp]]:
+    """
+    Returns
+    -------
+    dict:
+        Labels mapped to indexers.
+    """
+    shape = tuple(len(x) for x in keys)
+
+    group_index = get_group_index(label_list, shape, sort=True, xnull=True)
+    if np.all(group_index == -1):
+        # Short-circuit, lib.indices_fast will return the same
+        return {}
+    ngroups = (
+        ((group_index.size and group_index.max()) + 1)
+        if is_int64_overflow_possible(shape)
+        else np.prod(shape, dtype="i8")
+    )
+
+    sorter = get_group_index_sorter(group_index, ngroups)
+
+    sorted_labels = [lab.take(sorter) for lab in label_list]
+    group_index = group_index.take(sorter)
+
+    return lib.indices_fast(sorter, group_index, keys, sorted_labels)
+
+
+# ----------------------------------------------------------------------
+# sorting levels...cleverly?
+
+
+def get_group_index_sorter(
+    group_index: npt.NDArray[np.intp], ngroups: int | None = None
+) -> npt.NDArray[np.intp]:
+    """
+    algos.groupsort_indexer implements `counting sort` and it is at least
+    O(ngroups), where
+        ngroups = prod(shape)
+        shape = map(len, keys)
+    that is, linear in the number of combinations (cartesian product) of unique
+    values of groupby keys. This can be huge when doing multi-key groupby.
+    np.argsort(kind='mergesort') is O(count x log(count)) where count is the
+    length of the data-frame;
+    Both algorithms are `stable` sort and that is necessary for correctness of
+    groupby operations. e.g. consider:
+        df.groupby(key)[col].transform('first')
+
+    Parameters
+    ----------
+    group_index : np.ndarray[np.intp]
+        signed integer dtype
+    ngroups : int or None, default None
+
+    Returns
+    -------
+    np.ndarray[np.intp]
+    """
+    if ngroups is None:
+        ngroups = 1 + group_index.max()
+    count = len(group_index)
+    alpha = 0.0  # taking complexities literally; there may be
+    beta = 1.0  # some room for fine-tuning these parameters
+    do_groupsort = count > 0 and ((alpha + beta * ngroups) < (count * np.log(count)))
+    if do_groupsort:
+        sorter, _ = algos.groupsort_indexer(
+            ensure_platform_int(group_index),
+            ngroups,
+        )
+        # sorter _should_ already be intp, but mypy is not yet able to verify
+    else:
+        sorter = group_index.argsort(kind="mergesort")
+    return ensure_platform_int(sorter)
+
+
+def compress_group_index(
+    group_index: npt.NDArray[np.int64], sort: bool = True
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.int64]]:
+    """
+    Group_index is offsets into cartesian product of all possible labels. This
+    space can be huge, so this function compresses it, by computing offsets
+    (comp_ids) into the list of unique labels (obs_group_ids).
+    """
+    if len(group_index) and np.all(group_index[1:] >= group_index[:-1]):
+        # GH 53806: fast path for sorted group_index
+        unique_mask = np.concatenate(
+            [group_index[:1] > -1, group_index[1:] != group_index[:-1]]
+        )
+        comp_ids = unique_mask.cumsum()
+        comp_ids -= 1
+        obs_group_ids = group_index[unique_mask]
+    else:
+        size_hint = len(group_index)
+        table = hashtable.Int64HashTable(size_hint)
+
+        group_index = ensure_int64(group_index)
+
+        # note, group labels come out ascending (ie, 1,2,3 etc)
+        comp_ids, obs_group_ids = table.get_labels_groupby(group_index)
+
+        if sort and len(obs_group_ids) > 0:
+            obs_group_ids, comp_ids = _reorder_by_uniques(obs_group_ids, comp_ids)
+
+    return ensure_int64(comp_ids), ensure_int64(obs_group_ids)
+
+
+def _reorder_by_uniques(
+    uniques: npt.NDArray[np.int64], labels: npt.NDArray[np.intp]
+) -> tuple[npt.NDArray[np.int64], npt.NDArray[np.intp]]:
+    """
+    Parameters
+    ----------
+    uniques : np.ndarray[np.int64]
+    labels : np.ndarray[np.intp]
+
+    Returns
+    -------
+    np.ndarray[np.int64]
+    np.ndarray[np.intp]
+    """
+    # sorter is index where elements ought to go
+    sorter = uniques.argsort()
+
+    # reverse_indexer is where elements came from
+    reverse_indexer = np.empty(len(sorter), dtype=np.intp)
+    reverse_indexer.put(sorter, np.arange(len(sorter)))
+
+    mask = labels < 0
+
+    # move labels to right locations (ie, unsort ascending labels)
+    labels = reverse_indexer.take(labels)
+    np.putmask(labels, mask, -1)
+
+    # sort observed ids
+    uniques = uniques.take(sorter)
+
+    return uniques, labels
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/sparse/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/sparse/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/sparse/api.py b/.venv/lib/python3.13/site-packages/pandas/core/sparse/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..6650a5c4e90a0f73a43e6e35cdd26c1189daf256
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/sparse/api.py
@@ -0,0 +1,5 @@
+from pandas.core.dtypes.dtypes import SparseDtype
+
+from pandas.core.arrays.sparse import SparseArray
+
+__all__ = ["SparseArray", "SparseDtype"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/strings/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/strings/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..d4ce75f768c5d1dcd8586264fe1faf756d5d5e94
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/strings/__init__.py
@@ -0,0 +1,28 @@
+"""
+Implementation of pandas.Series.str and its interface.
+
+* strings.accessor.StringMethods : Accessor for Series.str
+* strings.base.BaseStringArrayMethods: Mixin ABC for EAs to implement str methods
+
+Most methods on the StringMethods accessor follow the pattern:
+
+    1. extract the array from the series (or index)
+    2. Call that array's implementation of the string method
+    3. Wrap the result (in a Series, index, or DataFrame)
+
+Pandas extension arrays implementing string methods should inherit from
+pandas.core.strings.base.BaseStringArrayMethods. This is an ABC defining
+the various string methods. To avoid namespace clashes and pollution,
+these are prefixed with `_str_`. So ``Series.str.upper()`` calls
+``Series.array._str_upper()``. The interface isn't currently public
+to other string extension arrays.
+"""
+# Pandas current implementation is in ObjectStringArrayMixin. This is designed
+# to work on object-dtype ndarrays.
+#
+# BaseStringArrayMethods
+#  - ObjectStringArrayMixin
+#     - StringArray
+#     - NumpyExtensionArray
+#     - Categorical
+#     - ArrowStringArray
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/strings/accessor.py b/.venv/lib/python3.13/site-packages/pandas/core/strings/accessor.py
new file mode 100644
index 0000000000000000000000000000000000000000..da17543f8470d2394ad7d9aac66c6db99b100df0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/strings/accessor.py
@@ -0,0 +1,3571 @@
+from __future__ import annotations
+
+import codecs
+from functools import wraps
+import re
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs import lib
+from pandas._typing import (
+    AlignJoin,
+    DtypeObj,
+    F,
+    Scalar,
+    npt,
+)
+from pandas.util._decorators import Appender
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_bool_dtype,
+    is_integer,
+    is_list_like,
+    is_object_dtype,
+    is_re,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    CategoricalDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.arrays import ExtensionArray
+from pandas.core.base import NoNewAttributesMixin
+from pandas.core.construction import extract_array
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+
+_shared_docs: dict[str, str] = {}
+_cpython_optimized_encoders = (
+    "utf-8",
+    "utf8",
+    "latin-1",
+    "latin1",
+    "iso-8859-1",
+    "mbcs",
+    "ascii",
+)
+_cpython_optimized_decoders = _cpython_optimized_encoders + ("utf-16", "utf-32")
+
+
+def forbid_nonstring_types(
+    forbidden: list[str] | None, name: str | None = None
+) -> Callable[[F], F]:
+    """
+    Decorator to forbid specific types for a method of StringMethods.
+
+    For calling `.str.{method}` on a Series or Index, it is necessary to first
+    initialize the :class:`StringMethods` object, and then call the method.
+    However, different methods allow different input types, and so this can not
+    be checked during :meth:`StringMethods.__init__`, but must be done on a
+    per-method basis. This decorator exists to facilitate this process, and
+    make it explicit which (inferred) types are disallowed by the method.
+
+    :meth:`StringMethods.__init__` allows the *union* of types its different
+    methods allow (after skipping NaNs; see :meth:`StringMethods._validate`),
+    namely: ['string', 'empty', 'bytes', 'mixed', 'mixed-integer'].
+
+    The default string types ['string', 'empty'] are allowed for all methods.
+    For the additional types ['bytes', 'mixed', 'mixed-integer'], each method
+    then needs to forbid the types it is not intended for.
+
+    Parameters
+    ----------
+    forbidden : list-of-str or None
+        List of forbidden non-string types, may be one or more of
+        `['bytes', 'mixed', 'mixed-integer']`.
+    name : str, default None
+        Name of the method to use in the error message. By default, this is
+        None, in which case the name from the method being wrapped will be
+        copied. However, for working with further wrappers (like _pat_wrapper
+        and _noarg_wrapper), it is necessary to specify the name.
+
+    Returns
+    -------
+    func : wrapper
+        The method to which the decorator is applied, with an added check that
+        enforces the inferred type to not be in the list of forbidden types.
+
+    Raises
+    ------
+    TypeError
+        If the inferred type of the underlying data is in `forbidden`.
+    """
+    # deal with None
+    forbidden = [] if forbidden is None else forbidden
+
+    allowed_types = {"string", "empty", "bytes", "mixed", "mixed-integer"} - set(
+        forbidden
+    )
+
+    def _forbid_nonstring_types(func: F) -> F:
+        func_name = func.__name__ if name is None else name
+
+        @wraps(func)
+        def wrapper(self, *args, **kwargs):
+            if self._inferred_dtype not in allowed_types:
+                msg = (
+                    f"Cannot use .str.{func_name} with values of "
+                    f"inferred dtype '{self._inferred_dtype}'."
+                )
+                raise TypeError(msg)
+            return func(self, *args, **kwargs)
+
+        wrapper.__name__ = func_name
+        return cast(F, wrapper)
+
+    return _forbid_nonstring_types
+
+
+def _map_and_wrap(name: str | None, docstring: str | None):
+    @forbid_nonstring_types(["bytes"], name=name)
+    def wrapper(self):
+        result = getattr(self._data.array, f"_str_{name}")()
+        return self._wrap_result(
+            result, returns_string=name not in ("isnumeric", "isdecimal")
+        )
+
+    wrapper.__doc__ = docstring
+    return wrapper
+
+
+class StringMethods(NoNewAttributesMixin):
+    """
+    Vectorized string functions for Series and Index.
+
+    NAs stay NA unless handled otherwise by a particular method.
+    Patterned after Python's string methods, with some inspiration from
+    R's stringr package.
+
+    Examples
+    --------
+    >>> s = pd.Series(["A_Str_Series"])
+    >>> s
+    0    A_Str_Series
+    dtype: object
+
+    >>> s.str.split("_")
+    0    [A, Str, Series]
+    dtype: object
+
+    >>> s.str.replace("_", "")
+    0    AStrSeries
+    dtype: object
+    """
+
+    # Note: see the docstring in pandas.core.strings.__init__
+    # for an explanation of the implementation.
+    # TODO: Dispatch all the methods
+    # Currently the following are not dispatched to the array
+    # * cat
+    # * extractall
+
+    def __init__(self, data) -> None:
+        from pandas.core.arrays.string_ import StringDtype
+
+        self._inferred_dtype = self._validate(data)
+        self._is_categorical = isinstance(data.dtype, CategoricalDtype)
+        self._is_string = isinstance(data.dtype, StringDtype)
+        self._data = data
+
+        self._index = self._name = None
+        if isinstance(data, ABCSeries):
+            self._index = data.index
+            self._name = data.name
+
+        # ._values.categories works for both Series/Index
+        self._parent = data._values.categories if self._is_categorical else data
+        # save orig to blow up categoricals to the right type
+        self._orig = data
+        self._freeze()
+
+    @staticmethod
+    def _validate(data):
+        """
+        Auxiliary function for StringMethods, infers and checks dtype of data.
+
+        This is a "first line of defence" at the creation of the StringMethods-
+        object, and just checks that the dtype is in the
+        *union* of the allowed types over all string methods below; this
+        restriction is then refined on a per-method basis using the decorator
+        @forbid_nonstring_types (more info in the corresponding docstring).
+
+        This really should exclude all series/index with any non-string values,
+        but that isn't practical for performance reasons until we have a str
+        dtype (GH 9343 / 13877)
+
+        Parameters
+        ----------
+        data : The content of the Series
+
+        Returns
+        -------
+        dtype : inferred dtype of data
+        """
+        if isinstance(data, ABCMultiIndex):
+            raise AttributeError(
+                "Can only use .str accessor with Index, not MultiIndex"
+            )
+
+        # see _libs/lib.pyx for list of inferred types
+        allowed_types = ["string", "empty", "bytes", "mixed", "mixed-integer"]
+
+        data = extract_array(data)
+
+        values = getattr(data, "categories", data)  # categorical / normal
+
+        inferred_dtype = lib.infer_dtype(values, skipna=True)
+
+        if inferred_dtype not in allowed_types:
+            raise AttributeError("Can only use .str accessor with string values!")
+        return inferred_dtype
+
+    def __getitem__(self, key):
+        result = self._data.array._str_getitem(key)
+        return self._wrap_result(result)
+
+    def __iter__(self) -> Iterator:
+        raise TypeError(f"'{type(self).__name__}' object is not iterable")
+
+    def _wrap_result(
+        self,
+        result,
+        name=None,
+        expand: bool | None = None,
+        fill_value=np.nan,
+        returns_string: bool = True,
+        returns_bool: bool = False,
+        dtype=None,
+    ):
+        from pandas import (
+            Index,
+            MultiIndex,
+        )
+
+        if not hasattr(result, "ndim") or not hasattr(result, "dtype"):
+            if isinstance(result, ABCDataFrame):
+                result = result.__finalize__(self._orig, name="str")
+            return result
+        assert result.ndim < 3
+
+        # We can be wrapping a string / object / categorical result, in which
+        # case we'll want to return the same dtype as the input.
+        # Or we can be wrapping a numeric output, in which case we don't want
+        # to return a StringArray.
+        # Ideally the array method returns the right array type.
+        if expand is None:
+            # infer from ndim if expand is not specified
+            expand = result.ndim != 1
+        elif expand is True and not isinstance(self._orig, ABCIndex):
+            # required when expand=True is explicitly specified
+            # not needed when inferred
+            if isinstance(result.dtype, ArrowDtype):
+                import pyarrow as pa
+
+                from pandas.compat import pa_version_under11p0
+
+                from pandas.core.arrays.arrow.array import ArrowExtensionArray
+
+                value_lengths = pa.compute.list_value_length(result._pa_array)
+                max_len = pa.compute.max(value_lengths).as_py()
+                min_len = pa.compute.min(value_lengths).as_py()
+                if result._hasna:
+                    # ArrowExtensionArray.fillna doesn't work for list scalars
+                    result = ArrowExtensionArray(
+                        result._pa_array.fill_null([None] * max_len)
+                    )
+                if min_len < max_len:
+                    # append nulls to each scalar list element up to max_len
+                    if not pa_version_under11p0:
+                        result = ArrowExtensionArray(
+                            pa.compute.list_slice(
+                                result._pa_array,
+                                start=0,
+                                stop=max_len,
+                                return_fixed_size_list=True,
+                            )
+                        )
+                    else:
+                        all_null = np.full(max_len, fill_value=None, dtype=object)
+                        values = result.to_numpy()
+                        new_values = []
+                        for row in values:
+                            if len(row) < max_len:
+                                nulls = all_null[: max_len - len(row)]
+                                row = np.append(row, nulls)
+                            new_values.append(row)
+                        pa_type = result._pa_array.type
+                        result = ArrowExtensionArray(pa.array(new_values, type=pa_type))
+                if name is not None:
+                    labels = name
+                else:
+                    labels = range(max_len)
+                result = (
+                    pa.compute.list_flatten(result._pa_array)
+                    .to_numpy()
+                    .reshape(len(result), max_len)
+                )
+                result = {
+                    label: ArrowExtensionArray(pa.array(res))
+                    for label, res in zip(labels, result.T)
+                }
+            elif is_object_dtype(result):
+
+                def cons_row(x):
+                    if is_list_like(x):
+                        return x
+                    else:
+                        return [x]
+
+                result = [cons_row(x) for x in result]
+                if result and not self._is_string:
+                    # propagate nan values to match longest sequence (GH 18450)
+                    max_len = max(len(x) for x in result)
+                    result = [
+                        x * max_len if len(x) == 0 or x[0] is np.nan else x
+                        for x in result
+                    ]
+
+        if not isinstance(expand, bool):
+            raise ValueError("expand must be True or False")
+
+        if expand is False:
+            # if expand is False, result should have the same name
+            # as the original otherwise specified
+            if name is None:
+                name = getattr(result, "name", None)
+            if name is None:
+                # do not use logical or, _orig may be a DataFrame
+                # which has "name" column
+                name = self._orig.name
+
+        # Wait until we are sure result is a Series or Index before
+        # checking attributes (GH 12180)
+        if isinstance(self._orig, ABCIndex):
+            # if result is a boolean np.array, return the np.array
+            # instead of wrapping it into a boolean Index (GH 8875)
+            if is_bool_dtype(result):
+                return result
+
+            if expand:
+                result = list(result)
+                out: Index = MultiIndex.from_tuples(result, names=name)
+                if out.nlevels == 1:
+                    # We had all tuples of length-one, which are
+                    # better represented as a regular Index.
+                    out = out.get_level_values(0)
+                return out
+            else:
+                return Index(result, name=name, dtype=dtype)
+        else:
+            index = self._orig.index
+            # This is a mess.
+            _dtype: DtypeObj | str | None = dtype
+            vdtype = getattr(result, "dtype", None)
+            if _dtype is not None:
+                pass
+            elif self._is_string:
+                if is_bool_dtype(vdtype):
+                    _dtype = result.dtype
+                elif returns_string:
+                    _dtype = self._orig.dtype
+                else:
+                    _dtype = vdtype
+            elif vdtype is not None:
+                _dtype = vdtype
+
+            if expand:
+                cons = self._orig._constructor_expanddim
+                result = cons(result, columns=name, index=index, dtype=_dtype)
+            else:
+                # Must be a Series
+                cons = self._orig._constructor
+                result = cons(result, name=name, index=index, dtype=_dtype)
+            result = result.__finalize__(self._orig, method="str")
+            if name is not None and result.ndim == 1:
+                # __finalize__ might copy over the original name, but we may
+                # want the new name (e.g. str.extract).
+                result.name = name
+            return result
+
+    def _get_series_list(self, others):
+        """
+        Auxiliary function for :meth:`str.cat`. Turn potentially mixed input
+        into a list of Series (elements without an index must match the length
+        of the calling Series/Index).
+
+        Parameters
+        ----------
+        others : Series, DataFrame, np.ndarray, list-like or list-like of
+            Objects that are either Series, Index or np.ndarray (1-dim).
+
+        Returns
+        -------
+        list of Series
+            Others transformed into list of Series.
+        """
+        from pandas import (
+            DataFrame,
+            Series,
+        )
+
+        # self._orig is either Series or Index
+        idx = self._orig if isinstance(self._orig, ABCIndex) else self._orig.index
+
+        # Generally speaking, all objects without an index inherit the index
+        # `idx` of the calling Series/Index - i.e. must have matching length.
+        # Objects with an index (i.e. Series/Index/DataFrame) keep their own.
+        if isinstance(others, ABCSeries):
+            return [others]
+        elif isinstance(others, ABCIndex):
+            return [Series(others, index=idx, dtype=others.dtype)]
+        elif isinstance(others, ABCDataFrame):
+            return [others[x] for x in others]
+        elif isinstance(others, np.ndarray) and others.ndim == 2:
+            others = DataFrame(others, index=idx)
+            return [others[x] for x in others]
+        elif is_list_like(others, allow_sets=False):
+            try:
+                others = list(others)  # ensure iterators do not get read twice etc
+            except TypeError:
+                # e.g. ser.str, raise below
+                pass
+            else:
+                # in case of list-like `others`, all elements must be
+                # either Series/Index/np.ndarray (1-dim)...
+                if all(
+                    isinstance(x, (ABCSeries, ABCIndex, ExtensionArray))
+                    or (isinstance(x, np.ndarray) and x.ndim == 1)
+                    for x in others
+                ):
+                    los: list[Series] = []
+                    while others:  # iterate through list and append each element
+                        los = los + self._get_series_list(others.pop(0))
+                    return los
+                # ... or just strings
+                elif all(not is_list_like(x) for x in others):
+                    return [Series(others, index=idx)]
+        raise TypeError(
+            "others must be Series, Index, DataFrame, np.ndarray "
+            "or list-like (either containing only strings or "
+            "containing only objects of type Series/Index/"
+            "np.ndarray[1-dim])"
+        )
+
+    @forbid_nonstring_types(["bytes", "mixed", "mixed-integer"])
+    def cat(
+        self,
+        others=None,
+        sep: str | None = None,
+        na_rep=None,
+        join: AlignJoin = "left",
+    ) -> str | Series | Index:
+        """
+        Concatenate strings in the Series/Index with given separator.
+
+        If `others` is specified, this function concatenates the Series/Index
+        and elements of `others` element-wise.
+        If `others` is not passed, then all values in the Series/Index are
+        concatenated into a single string with a given `sep`.
+
+        Parameters
+        ----------
+        others : Series, Index, DataFrame, np.ndarray or list-like
+            Series, Index, DataFrame, np.ndarray (one- or two-dimensional) and
+            other list-likes of strings must have the same length as the
+            calling Series/Index, with the exception of indexed objects (i.e.
+            Series/Index/DataFrame) if `join` is not None.
+
+            If others is a list-like that contains a combination of Series,
+            Index or np.ndarray (1-dim), then all elements will be unpacked and
+            must satisfy the above criteria individually.
+
+            If others is None, the method returns the concatenation of all
+            strings in the calling Series/Index.
+        sep : str, default ''
+            The separator between the different elements/columns. By default
+            the empty string `''` is used.
+        na_rep : str or None, default None
+            Representation that is inserted for all missing values:
+
+            - If `na_rep` is None, and `others` is None, missing values in the
+              Series/Index are omitted from the result.
+            - If `na_rep` is None, and `others` is not None, a row containing a
+              missing value in any of the columns (before concatenation) will
+              have a missing value in the result.
+        join : {'left', 'right', 'outer', 'inner'}, default 'left'
+            Determines the join-style between the calling Series/Index and any
+            Series/Index/DataFrame in `others` (objects without an index need
+            to match the length of the calling Series/Index). To disable
+            alignment, use `.values` on any Series/Index/DataFrame in `others`.
+
+        Returns
+        -------
+        str, Series or Index
+            If `others` is None, `str` is returned, otherwise a `Series/Index`
+            (same type as caller) of objects is returned.
+
+        See Also
+        --------
+        split : Split each string in the Series/Index.
+        join : Join lists contained as elements in the Series/Index.
+
+        Examples
+        --------
+        When not passing `others`, all values are concatenated into a single
+        string:
+
+        >>> s = pd.Series(['a', 'b', np.nan, 'd'])
+        >>> s.str.cat(sep=' ')
+        'a b d'
+
+        By default, NA values in the Series are ignored. Using `na_rep`, they
+        can be given a representation:
+
+        >>> s.str.cat(sep=' ', na_rep='?')
+        'a b ? d'
+
+        If `others` is specified, corresponding values are concatenated with
+        the separator. Result will be a Series of strings.
+
+        >>> s.str.cat(['A', 'B', 'C', 'D'], sep=',')
+        0    a,A
+        1    b,B
+        2    NaN
+        3    d,D
+        dtype: object
+
+        Missing values will remain missing in the result, but can again be
+        represented using `na_rep`
+
+        >>> s.str.cat(['A', 'B', 'C', 'D'], sep=',', na_rep='-')
+        0    a,A
+        1    b,B
+        2    -,C
+        3    d,D
+        dtype: object
+
+        If `sep` is not specified, the values are concatenated without
+        separation.
+
+        >>> s.str.cat(['A', 'B', 'C', 'D'], na_rep='-')
+        0    aA
+        1    bB
+        2    -C
+        3    dD
+        dtype: object
+
+        Series with different indexes can be aligned before concatenation. The
+        `join`-keyword works as in other methods.
+
+        >>> t = pd.Series(['d', 'a', 'e', 'c'], index=[3, 0, 4, 2])
+        >>> s.str.cat(t, join='left', na_rep='-')
+        0    aa
+        1    b-
+        2    -c
+        3    dd
+        dtype: object
+        >>>
+        >>> s.str.cat(t, join='outer', na_rep='-')
+        0    aa
+        1    b-
+        2    -c
+        3    dd
+        4    -e
+        dtype: object
+        >>>
+        >>> s.str.cat(t, join='inner', na_rep='-')
+        0    aa
+        2    -c
+        3    dd
+        dtype: object
+        >>>
+        >>> s.str.cat(t, join='right', na_rep='-')
+        3    dd
+        0    aa
+        4    -e
+        2    -c
+        dtype: object
+
+        For more examples, see :ref:`here `.
+        """
+        # TODO: dispatch
+        from pandas import (
+            Index,
+            Series,
+            concat,
+        )
+
+        if isinstance(others, str):
+            raise ValueError("Did you mean to supply a `sep` keyword?")
+        if sep is None:
+            sep = ""
+
+        if isinstance(self._orig, ABCIndex):
+            data = Series(self._orig, index=self._orig, dtype=self._orig.dtype)
+        else:  # Series
+            data = self._orig
+
+        # concatenate Series/Index with itself if no "others"
+        if others is None:
+            # error: Incompatible types in assignment (expression has type
+            # "ndarray", variable has type "Series")
+            data = ensure_object(data)  # type: ignore[assignment]
+            na_mask = isna(data)
+            if na_rep is None and na_mask.any():
+                return sep.join(data[~na_mask])
+            elif na_rep is not None and na_mask.any():
+                return sep.join(np.where(na_mask, na_rep, data))
+            else:
+                return sep.join(data)
+
+        try:
+            # turn anything in "others" into lists of Series
+            others = self._get_series_list(others)
+        except ValueError as err:  # do not catch TypeError raised by _get_series_list
+            raise ValueError(
+                "If `others` contains arrays or lists (or other "
+                "list-likes without an index), these must all be "
+                "of the same length as the calling Series/Index."
+            ) from err
+
+        # align if required
+        if any(not data.index.equals(x.index) for x in others):
+            # Need to add keys for uniqueness in case of duplicate columns
+            others = concat(
+                others,
+                axis=1,
+                join=(join if join == "inner" else "outer"),
+                keys=range(len(others)),
+                sort=False,
+                copy=False,
+            )
+            data, others = data.align(others, join=join)
+            others = [others[x] for x in others]  # again list of Series
+
+        all_cols = [ensure_object(x) for x in [data] + others]
+        na_masks = np.array([isna(x) for x in all_cols])
+        union_mask = np.logical_or.reduce(na_masks, axis=0)
+
+        if na_rep is None and union_mask.any():
+            # no na_rep means NaNs for all rows where any column has a NaN
+            # only necessary if there are actually any NaNs
+            result = np.empty(len(data), dtype=object)
+            np.putmask(result, union_mask, np.nan)
+
+            not_masked = ~union_mask
+            result[not_masked] = cat_safe([x[not_masked] for x in all_cols], sep)
+        elif na_rep is not None and union_mask.any():
+            # fill NaNs with na_rep in case there are actually any NaNs
+            all_cols = [
+                np.where(nm, na_rep, col) for nm, col in zip(na_masks, all_cols)
+            ]
+            result = cat_safe(all_cols, sep)
+        else:
+            # no NaNs - can just concatenate
+            result = cat_safe(all_cols, sep)
+
+        out: Index | Series
+        if isinstance(self._orig.dtype, CategoricalDtype):
+            # We need to infer the new categories.
+            dtype = self._orig.dtype.categories.dtype
+        else:
+            dtype = self._orig.dtype
+        if isinstance(self._orig, ABCIndex):
+            # add dtype for case that result is all-NA
+            if isna(result).all():
+                dtype = object  # type: ignore[assignment]
+
+            out = Index(result, dtype=dtype, name=self._orig.name)
+        else:  # Series
+            res_ser = Series(
+                result, dtype=dtype, index=data.index, name=self._orig.name, copy=False
+            )
+            out = res_ser.__finalize__(self._orig, method="str_cat")
+        return out
+
+    _shared_docs[
+        "str_split"
+    ] = r"""
+    Split strings around given separator/delimiter.
+
+    Splits the string in the Series/Index from the %(side)s,
+    at the specified delimiter string.
+
+    Parameters
+    ----------
+    pat : str%(pat_regex)s, optional
+        %(pat_description)s.
+        If not specified, split on whitespace.
+    n : int, default -1 (all)
+        Limit number of splits in output.
+        ``None``, 0 and -1 will be interpreted as return all splits.
+    expand : bool, default False
+        Expand the split strings into separate columns.
+
+        - If ``True``, return DataFrame/MultiIndex expanding dimensionality.
+        - If ``False``, return Series/Index, containing lists of strings.
+    %(regex_argument)s
+    Returns
+    -------
+    Series, Index, DataFrame or MultiIndex
+        Type matches caller unless ``expand=True`` (see Notes).
+    %(raises_split)s
+    See Also
+    --------
+    Series.str.split : Split strings around given separator/delimiter.
+    Series.str.rsplit : Splits string around given separator/delimiter,
+        starting from the right.
+    Series.str.join : Join lists contained as elements in the Series/Index
+        with passed delimiter.
+    str.split : Standard library version for split.
+    str.rsplit : Standard library version for rsplit.
+
+    Notes
+    -----
+    The handling of the `n` keyword depends on the number of found splits:
+
+    - If found splits > `n`,  make first `n` splits only
+    - If found splits <= `n`, make all splits
+    - If for a certain row the number of found splits < `n`,
+      append `None` for padding up to `n` if ``expand=True``
+
+    If using ``expand=True``, Series and Index callers return DataFrame and
+    MultiIndex objects, respectively.
+    %(regex_pat_note)s
+    Examples
+    --------
+    >>> s = pd.Series(
+    ...     [
+    ...         "this is a regular sentence",
+    ...         "https://docs.python.org/3/tutorial/index.html",
+    ...         np.nan
+    ...     ]
+    ... )
+    >>> s
+    0                       this is a regular sentence
+    1    https://docs.python.org/3/tutorial/index.html
+    2                                              NaN
+    dtype: object
+
+    In the default setting, the string is split by whitespace.
+
+    >>> s.str.split()
+    0                   [this, is, a, regular, sentence]
+    1    [https://docs.python.org/3/tutorial/index.html]
+    2                                                NaN
+    dtype: object
+
+    Without the `n` parameter, the outputs of `rsplit` and `split`
+    are identical.
+
+    >>> s.str.rsplit()
+    0                   [this, is, a, regular, sentence]
+    1    [https://docs.python.org/3/tutorial/index.html]
+    2                                                NaN
+    dtype: object
+
+    The `n` parameter can be used to limit the number of splits on the
+    delimiter. The outputs of `split` and `rsplit` are different.
+
+    >>> s.str.split(n=2)
+    0                     [this, is, a regular sentence]
+    1    [https://docs.python.org/3/tutorial/index.html]
+    2                                                NaN
+    dtype: object
+
+    >>> s.str.rsplit(n=2)
+    0                     [this is a, regular, sentence]
+    1    [https://docs.python.org/3/tutorial/index.html]
+    2                                                NaN
+    dtype: object
+
+    The `pat` parameter can be used to split by other characters.
+
+    >>> s.str.split(pat="/")
+    0                         [this is a regular sentence]
+    1    [https:, , docs.python.org, 3, tutorial, index...
+    2                                                  NaN
+    dtype: object
+
+    When using ``expand=True``, the split elements will expand out into
+    separate columns. If NaN is present, it is propagated throughout
+    the columns during the split.
+
+    >>> s.str.split(expand=True)
+                                                   0     1     2        3         4
+    0                                           this    is     a  regular  sentence
+    1  https://docs.python.org/3/tutorial/index.html  None  None     None      None
+    2                                            NaN   NaN   NaN      NaN       NaN
+
+    For slightly more complex use cases like splitting the html document name
+    from a url, a combination of parameter settings can be used.
+
+    >>> s.str.rsplit("/", n=1, expand=True)
+                                        0           1
+    0          this is a regular sentence        None
+    1  https://docs.python.org/3/tutorial  index.html
+    2                                 NaN         NaN
+    %(regex_examples)s"""
+
+    @Appender(
+        _shared_docs["str_split"]
+        % {
+            "side": "beginning",
+            "pat_regex": " or compiled regex",
+            "pat_description": "String or regular expression to split on",
+            "regex_argument": """
+    regex : bool, default None
+        Determines if the passed-in pattern is a regular expression:
+
+        - If ``True``, assumes the passed-in pattern is a regular expression
+        - If ``False``, treats the pattern as a literal string.
+        - If ``None`` and `pat` length is 1, treats `pat` as a literal string.
+        - If ``None`` and `pat` length is not 1, treats `pat` as a regular expression.
+        - Cannot be set to False if `pat` is a compiled regex
+
+        .. versionadded:: 1.4.0
+         """,
+            "raises_split": """
+                      Raises
+                      ------
+                      ValueError
+                          * if `regex` is False and `pat` is a compiled regex
+                      """,
+            "regex_pat_note": """
+    Use of `regex =False` with a `pat` as a compiled regex will raise an error.
+            """,
+            "method": "split",
+            "regex_examples": r"""
+    Remember to escape special characters when explicitly using regular expressions.
+
+    >>> s = pd.Series(["foo and bar plus baz"])
+    >>> s.str.split(r"and|plus", expand=True)
+        0   1   2
+    0 foo bar baz
+
+    Regular expressions can be used to handle urls or file names.
+    When `pat` is a string and ``regex=None`` (the default), the given `pat` is compiled
+    as a regex only if ``len(pat) != 1``.
+
+    >>> s = pd.Series(['foojpgbar.jpg'])
+    >>> s.str.split(r".", expand=True)
+               0    1
+    0  foojpgbar  jpg
+
+    >>> s.str.split(r"\.jpg", expand=True)
+               0 1
+    0  foojpgbar
+
+    When ``regex=True``, `pat` is interpreted as a regex
+
+    >>> s.str.split(r"\.jpg", regex=True, expand=True)
+               0 1
+    0  foojpgbar
+
+    A compiled regex can be passed as `pat`
+
+    >>> import re
+    >>> s.str.split(re.compile(r"\.jpg"), expand=True)
+               0 1
+    0  foojpgbar
+
+    When ``regex=False``, `pat` is interpreted as the string itself
+
+    >>> s.str.split(r"\.jpg", regex=False, expand=True)
+                   0
+    0  foojpgbar.jpg
+    """,
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def split(
+        self,
+        pat: str | re.Pattern | None = None,
+        *,
+        n=-1,
+        expand: bool = False,
+        regex: bool | None = None,
+    ):
+        if regex is False and is_re(pat):
+            raise ValueError(
+                "Cannot use a compiled regex as replacement pattern with regex=False"
+            )
+        if is_re(pat):
+            regex = True
+        result = self._data.array._str_split(pat, n, expand, regex)
+        if self._data.dtype == "category":
+            dtype = self._data.dtype.categories.dtype
+        else:
+            dtype = object if self._data.dtype == object else None
+        return self._wrap_result(
+            result, expand=expand, returns_string=expand, dtype=dtype
+        )
+
+    @Appender(
+        _shared_docs["str_split"]
+        % {
+            "side": "end",
+            "pat_regex": "",
+            "pat_description": "String to split on",
+            "regex_argument": "",
+            "raises_split": "",
+            "regex_pat_note": "",
+            "method": "rsplit",
+            "regex_examples": "",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def rsplit(self, pat=None, *, n=-1, expand: bool = False):
+        result = self._data.array._str_rsplit(pat, n=n)
+        dtype = object if self._data.dtype == object else None
+        return self._wrap_result(
+            result, expand=expand, returns_string=expand, dtype=dtype
+        )
+
+    _shared_docs[
+        "str_partition"
+    ] = """
+    Split the string at the %(side)s occurrence of `sep`.
+
+    This method splits the string at the %(side)s occurrence of `sep`,
+    and returns 3 elements containing the part before the separator,
+    the separator itself, and the part after the separator.
+    If the separator is not found, return %(return)s.
+
+    Parameters
+    ----------
+    sep : str, default whitespace
+        String to split on.
+    expand : bool, default True
+        If True, return DataFrame/MultiIndex expanding dimensionality.
+        If False, return Series/Index.
+
+    Returns
+    -------
+    DataFrame/MultiIndex or Series/Index of objects
+
+    See Also
+    --------
+    %(also)s
+    Series.str.split : Split strings around given separators.
+    str.partition : Standard library version.
+
+    Examples
+    --------
+
+    >>> s = pd.Series(['Linda van der Berg', 'George Pitt-Rivers'])
+    >>> s
+    0    Linda van der Berg
+    1    George Pitt-Rivers
+    dtype: object
+
+    >>> s.str.partition()
+            0  1             2
+    0   Linda     van der Berg
+    1  George      Pitt-Rivers
+
+    To partition by the last space instead of the first one:
+
+    >>> s.str.rpartition()
+                   0  1            2
+    0  Linda van der            Berg
+    1         George     Pitt-Rivers
+
+    To partition by something different than a space:
+
+    >>> s.str.partition('-')
+                        0  1       2
+    0  Linda van der Berg
+    1         George Pitt  -  Rivers
+
+    To return a Series containing tuples instead of a DataFrame:
+
+    >>> s.str.partition('-', expand=False)
+    0    (Linda van der Berg, , )
+    1    (George Pitt, -, Rivers)
+    dtype: object
+
+    Also available on indices:
+
+    >>> idx = pd.Index(['X 123', 'Y 999'])
+    >>> idx
+    Index(['X 123', 'Y 999'], dtype='object')
+
+    Which will create a MultiIndex:
+
+    >>> idx.str.partition()
+    MultiIndex([('X', ' ', '123'),
+                ('Y', ' ', '999')],
+               )
+
+    Or an index with tuples with ``expand=False``:
+
+    >>> idx.str.partition(expand=False)
+    Index([('X', ' ', '123'), ('Y', ' ', '999')], dtype='object')
+    """
+
+    @Appender(
+        _shared_docs["str_partition"]
+        % {
+            "side": "first",
+            "return": "3 elements containing the string itself, followed by two "
+            "empty strings",
+            "also": "rpartition : Split the string at the last occurrence of `sep`.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def partition(self, sep: str = " ", expand: bool = True):
+        result = self._data.array._str_partition(sep, expand)
+        if self._data.dtype == "category":
+            dtype = self._data.dtype.categories.dtype
+        else:
+            dtype = object if self._data.dtype == object else None
+        return self._wrap_result(
+            result, expand=expand, returns_string=expand, dtype=dtype
+        )
+
+    @Appender(
+        _shared_docs["str_partition"]
+        % {
+            "side": "last",
+            "return": "3 elements containing two empty strings, followed by the "
+            "string itself",
+            "also": "partition : Split the string at the first occurrence of `sep`.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def rpartition(self, sep: str = " ", expand: bool = True):
+        result = self._data.array._str_rpartition(sep, expand)
+        if self._data.dtype == "category":
+            dtype = self._data.dtype.categories.dtype
+        else:
+            dtype = object if self._data.dtype == object else None
+        return self._wrap_result(
+            result, expand=expand, returns_string=expand, dtype=dtype
+        )
+
+    def get(self, i):
+        """
+        Extract element from each component at specified position or with specified key.
+
+        Extract element from lists, tuples, dict, or strings in each element in the
+        Series/Index.
+
+        Parameters
+        ----------
+        i : int or hashable dict label
+            Position or key of element to extract.
+
+        Returns
+        -------
+        Series or Index
+
+        Examples
+        --------
+        >>> s = pd.Series(["String",
+        ...               (1, 2, 3),
+        ...               ["a", "b", "c"],
+        ...               123,
+        ...               -456,
+        ...               {1: "Hello", "2": "World"}])
+        >>> s
+        0                        String
+        1                     (1, 2, 3)
+        2                     [a, b, c]
+        3                           123
+        4                          -456
+        5    {1: 'Hello', '2': 'World'}
+        dtype: object
+
+        >>> s.str.get(1)
+        0        t
+        1        2
+        2        b
+        3      NaN
+        4      NaN
+        5    Hello
+        dtype: object
+
+        >>> s.str.get(-1)
+        0      g
+        1      3
+        2      c
+        3    NaN
+        4    NaN
+        5    None
+        dtype: object
+
+        Return element with given key
+
+        >>> s = pd.Series([{"name": "Hello", "value": "World"},
+        ...               {"name": "Goodbye", "value": "Planet"}])
+        >>> s.str.get('name')
+        0      Hello
+        1    Goodbye
+        dtype: object
+        """
+        result = self._data.array._str_get(i)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def join(self, sep: str):
+        """
+        Join lists contained as elements in the Series/Index with passed delimiter.
+
+        If the elements of a Series are lists themselves, join the content of these
+        lists using the delimiter passed to the function.
+        This function is an equivalent to :meth:`str.join`.
+
+        Parameters
+        ----------
+        sep : str
+            Delimiter to use between list entries.
+
+        Returns
+        -------
+        Series/Index: object
+            The list entries concatenated by intervening occurrences of the
+            delimiter.
+
+        Raises
+        ------
+        AttributeError
+            If the supplied Series contains neither strings nor lists.
+
+        See Also
+        --------
+        str.join : Standard library version of this method.
+        Series.str.split : Split strings around given separator/delimiter.
+
+        Notes
+        -----
+        If any of the list items is not a string object, the result of the join
+        will be `NaN`.
+
+        Examples
+        --------
+        Example with a list that contains non-string elements.
+
+        >>> s = pd.Series([['lion', 'elephant', 'zebra'],
+        ...                [1.1, 2.2, 3.3],
+        ...                ['cat', np.nan, 'dog'],
+        ...                ['cow', 4.5, 'goat'],
+        ...                ['duck', ['swan', 'fish'], 'guppy']])
+        >>> s
+        0        [lion, elephant, zebra]
+        1                [1.1, 2.2, 3.3]
+        2                [cat, nan, dog]
+        3               [cow, 4.5, goat]
+        4    [duck, [swan, fish], guppy]
+        dtype: object
+
+        Join all lists using a '-'. The lists containing object(s) of types other
+        than str will produce a NaN.
+
+        >>> s.str.join('-')
+        0    lion-elephant-zebra
+        1                    NaN
+        2                    NaN
+        3                    NaN
+        4                    NaN
+        dtype: object
+        """
+        result = self._data.array._str_join(sep)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def contains(
+        self,
+        pat,
+        case: bool = True,
+        flags: int = 0,
+        na=lib.no_default,
+        regex: bool = True,
+    ):
+        r"""
+        Test if pattern or regex is contained within a string of a Series or Index.
+
+        Return boolean Series or Index based on whether a given pattern or regex is
+        contained within a string of a Series or Index.
+
+        Parameters
+        ----------
+        pat : str
+            Character sequence or regular expression.
+        case : bool, default True
+            If True, case sensitive.
+        flags : int, default 0 (no flags)
+            Flags to pass through to the re module, e.g. re.IGNORECASE.
+        na : scalar, optional
+            Fill value for missing values. The default depends on dtype of the
+            array. For object-dtype, ``numpy.nan`` is used. For the nullable
+            ``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
+            ``False`` is used.
+        regex : bool, default True
+            If True, assumes the pat is a regular expression.
+
+            If False, treats the pat as a literal string.
+
+        Returns
+        -------
+        Series or Index of boolean values
+            A Series or Index of boolean values indicating whether the
+            given pattern is contained within the string of each element
+            of the Series or Index.
+
+        See Also
+        --------
+        match : Analogous, but stricter, relying on re.match instead of re.search.
+        Series.str.startswith : Test if the start of each string element matches a
+            pattern.
+        Series.str.endswith : Same as startswith, but tests the end of string.
+
+        Examples
+        --------
+        Returning a Series of booleans using only a literal pattern.
+
+        >>> s1 = pd.Series(['Mouse', 'dog', 'house and parrot', '23', np.nan])
+        >>> s1.str.contains('og', regex=False)
+        0    False
+        1     True
+        2    False
+        3    False
+        4      NaN
+        dtype: object
+
+        Returning an Index of booleans using only a literal pattern.
+
+        >>> ind = pd.Index(['Mouse', 'dog', 'house and parrot', '23.0', np.nan])
+        >>> ind.str.contains('23', regex=False)
+        Index([False, False, False, True, nan], dtype='object')
+
+        Specifying case sensitivity using `case`.
+
+        >>> s1.str.contains('oG', case=True, regex=True)
+        0    False
+        1    False
+        2    False
+        3    False
+        4      NaN
+        dtype: object
+
+        Specifying `na` to be `False` instead of `NaN` replaces NaN values
+        with `False`. If Series or Index does not contain NaN values
+        the resultant dtype will be `bool`, otherwise, an `object` dtype.
+
+        >>> s1.str.contains('og', na=False, regex=True)
+        0    False
+        1     True
+        2    False
+        3    False
+        4    False
+        dtype: bool
+
+        Returning 'house' or 'dog' when either expression occurs in a string.
+
+        >>> s1.str.contains('house|dog', regex=True)
+        0    False
+        1     True
+        2     True
+        3    False
+        4      NaN
+        dtype: object
+
+        Ignoring case sensitivity using `flags` with regex.
+
+        >>> import re
+        >>> s1.str.contains('PARROT', flags=re.IGNORECASE, regex=True)
+        0    False
+        1    False
+        2     True
+        3    False
+        4      NaN
+        dtype: object
+
+        Returning any digit using regular expression.
+
+        >>> s1.str.contains('\\d', regex=True)
+        0    False
+        1    False
+        2    False
+        3     True
+        4      NaN
+        dtype: object
+
+        Ensure `pat` is a not a literal pattern when `regex` is set to True.
+        Note in the following example one might expect only `s2[1]` and `s2[3]` to
+        return `True`. However, '.0' as a regex matches any character
+        followed by a 0.
+
+        >>> s2 = pd.Series(['40', '40.0', '41', '41.0', '35'])
+        >>> s2.str.contains('.0', regex=True)
+        0     True
+        1     True
+        2    False
+        3     True
+        4    False
+        dtype: bool
+        """
+        if regex and re.compile(pat).groups:
+            warnings.warn(
+                "This pattern is interpreted as a regular expression, and has "
+                "match groups. To actually get the groups, use str.extract.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        result = self._data.array._str_contains(pat, case, flags, na, regex)
+        return self._wrap_result(result, fill_value=na, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def match(self, pat: str, case: bool = True, flags: int = 0, na=lib.no_default):
+        """
+        Determine if each string starts with a match of a regular expression.
+
+        Parameters
+        ----------
+        pat : str or compiled regex
+            Character sequence or regular expression.
+        case : bool, default True
+            If True, case sensitive.
+        flags : int, default 0 (no flags)
+            Regex module flags, e.g. re.IGNORECASE.
+        na : scalar, optional
+            Fill value for missing values. The default depends on dtype of the
+            array. For object-dtype, ``numpy.nan`` is used. For the nullable
+            ``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
+            ``False`` is used.
+
+        Returns
+        -------
+        Series/Index/array of boolean values
+
+        See Also
+        --------
+        fullmatch : Stricter matching that requires the entire string to match.
+        contains : Analogous, but less strict, relying on re.search instead of
+            re.match.
+        extract : Extract matched groups.
+
+        Examples
+        --------
+        >>> ser = pd.Series(["horse", "eagle", "donkey"])
+        >>> ser.str.match("e")
+        0   False
+        1   True
+        2   False
+        dtype: bool
+        """
+        result = self._data.array._str_match(pat, case=case, flags=flags, na=na)
+        return self._wrap_result(result, fill_value=na, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def fullmatch(self, pat, case: bool = True, flags: int = 0, na=lib.no_default):
+        """
+        Determine if each string entirely matches a regular expression.
+
+        Parameters
+        ----------
+        pat : str
+            Character sequence or regular expression.
+        case : bool, default True
+            If True, case sensitive.
+        flags : int, default 0 (no flags)
+            Regex module flags, e.g. re.IGNORECASE.
+        na : scalar, optional
+            Fill value for missing values. The default depends on dtype of the
+            array. For object-dtype, ``numpy.nan`` is used. For the nullable
+            ``StringDtype``, ``pandas.NA`` is used. For the ``"str"`` dtype,
+            ``False`` is used.
+
+        Returns
+        -------
+        Series/Index/array of boolean values
+
+        See Also
+        --------
+        match : Similar, but also returns `True` when only a *prefix* of the string
+            matches the regular expression.
+        extract : Extract matched groups.
+
+        Examples
+        --------
+        >>> ser = pd.Series(["cat", "duck", "dove"])
+        >>> ser.str.fullmatch(r'd.+')
+        0   False
+        1    True
+        2    True
+        dtype: bool
+        """
+        result = self._data.array._str_fullmatch(pat, case=case, flags=flags, na=na)
+        return self._wrap_result(result, fill_value=na, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def replace(
+        self,
+        pat: str | re.Pattern,
+        repl: str | Callable,
+        n: int = -1,
+        case: bool | None = None,
+        flags: int = 0,
+        regex: bool = False,
+    ):
+        r"""
+        Replace each occurrence of pattern/regex in the Series/Index.
+
+        Equivalent to :meth:`str.replace` or :func:`re.sub`, depending on
+        the regex value.
+
+        Parameters
+        ----------
+        pat : str or compiled regex
+            String can be a character sequence or regular expression.
+        repl : str or callable
+            Replacement string or a callable. The callable is passed the regex
+            match object and must return a replacement string to be used.
+            See :func:`re.sub`.
+        n : int, default -1 (all)
+            Number of replacements to make from start.
+        case : bool, default None
+            Determines if replace is case sensitive:
+
+            - If True, case sensitive (the default if `pat` is a string)
+            - Set to False for case insensitive
+            - Cannot be set if `pat` is a compiled regex.
+
+        flags : int, default 0 (no flags)
+            Regex module flags, e.g. re.IGNORECASE. Cannot be set if `pat` is a compiled
+            regex.
+        regex : bool, default False
+            Determines if the passed-in pattern is a regular expression:
+
+            - If True, assumes the passed-in pattern is a regular expression.
+            - If False, treats the pattern as a literal string
+            - Cannot be set to False if `pat` is a compiled regex or `repl` is
+              a callable.
+
+        Returns
+        -------
+        Series or Index of object
+            A copy of the object with all matching occurrences of `pat` replaced by
+            `repl`.
+
+        Raises
+        ------
+        ValueError
+            * if `regex` is False and `repl` is a callable or `pat` is a compiled
+              regex
+            * if `pat` is a compiled regex and `case` or `flags` is set
+
+        Notes
+        -----
+        When `pat` is a compiled regex, all flags should be included in the
+        compiled regex. Use of `case`, `flags`, or `regex=False` with a compiled
+        regex will raise an error.
+
+        Examples
+        --------
+        When `pat` is a string and `regex` is True, the given `pat`
+        is compiled as a regex. When `repl` is a string, it replaces matching
+        regex patterns as with :meth:`re.sub`. NaN value(s) in the Series are
+        left as is:
+
+        >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f.', 'ba', regex=True)
+        0    bao
+        1    baz
+        2    NaN
+        dtype: object
+
+        When `pat` is a string and `regex` is False, every `pat` is replaced with
+        `repl` as with :meth:`str.replace`:
+
+        >>> pd.Series(['f.o', 'fuz', np.nan]).str.replace('f.', 'ba', regex=False)
+        0    bao
+        1    fuz
+        2    NaN
+        dtype: object
+
+        When `repl` is a callable, it is called on every `pat` using
+        :func:`re.sub`. The callable should expect one positional argument
+        (a regex object) and return a string.
+
+        To get the idea:
+
+        >>> pd.Series(['foo', 'fuz', np.nan]).str.replace('f', repr, regex=True)
+        0    oo
+        1    uz
+        2                                            NaN
+        dtype: object
+
+        Reverse every lowercase alphabetic word:
+
+        >>> repl = lambda m: m.group(0)[::-1]
+        >>> ser = pd.Series(['foo 123', 'bar baz', np.nan])
+        >>> ser.str.replace(r'[a-z]+', repl, regex=True)
+        0    oof 123
+        1    rab zab
+        2        NaN
+        dtype: object
+
+        Using regex groups (extract second group and swap case):
+
+        >>> pat = r"(?P\w+) (?P\w+) (?P\w+)"
+        >>> repl = lambda m: m.group('two').swapcase()
+        >>> ser = pd.Series(['One Two Three', 'Foo Bar Baz'])
+        >>> ser.str.replace(pat, repl, regex=True)
+        0    tWO
+        1    bAR
+        dtype: object
+
+        Using a compiled regex with flags
+
+        >>> import re
+        >>> regex_pat = re.compile(r'FUZ', flags=re.IGNORECASE)
+        >>> pd.Series(['foo', 'fuz', np.nan]).str.replace(regex_pat, 'bar', regex=True)
+        0    foo
+        1    bar
+        2    NaN
+        dtype: object
+        """
+        # Check whether repl is valid (GH 13438, GH 15055)
+        if not (isinstance(repl, str) or callable(repl)):
+            raise TypeError("repl must be a string or callable")
+
+        is_compiled_re = is_re(pat)
+        if regex or regex is None:
+            if is_compiled_re and (case is not None or flags != 0):
+                raise ValueError(
+                    "case and flags cannot be set when pat is a compiled regex"
+                )
+
+        elif is_compiled_re:
+            raise ValueError(
+                "Cannot use a compiled regex as replacement pattern with regex=False"
+            )
+        elif callable(repl):
+            raise ValueError("Cannot use a callable replacement when regex=False")
+
+        if case is None:
+            case = True
+
+        result = self._data.array._str_replace(
+            pat, repl, n=n, case=case, flags=flags, regex=regex
+        )
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def repeat(self, repeats):
+        """
+        Duplicate each string in the Series or Index.
+
+        Parameters
+        ----------
+        repeats : int or sequence of int
+            Same value for all (int) or different value per (sequence).
+
+        Returns
+        -------
+        Series or pandas.Index
+            Series or Index of repeated string objects specified by
+            input parameter repeats.
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'b', 'c'])
+        >>> s
+        0    a
+        1    b
+        2    c
+        dtype: object
+
+        Single int repeats string in Series
+
+        >>> s.str.repeat(repeats=2)
+        0    aa
+        1    bb
+        2    cc
+        dtype: object
+
+        Sequence of int repeats corresponding string in Series
+
+        >>> s.str.repeat(repeats=[1, 2, 3])
+        0      a
+        1     bb
+        2    ccc
+        dtype: object
+        """
+        result = self._data.array._str_repeat(repeats)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def pad(
+        self,
+        width: int,
+        side: Literal["left", "right", "both"] = "left",
+        fillchar: str = " ",
+    ):
+        """
+        Pad strings in the Series/Index up to width.
+
+        Parameters
+        ----------
+        width : int
+            Minimum width of resulting string; additional characters will be filled
+            with character defined in `fillchar`.
+        side : {'left', 'right', 'both'}, default 'left'
+            Side from which to fill resulting string.
+        fillchar : str, default ' '
+            Additional character for filling, default is whitespace.
+
+        Returns
+        -------
+        Series or Index of object
+            Returns Series or Index with minimum number of char in object.
+
+        See Also
+        --------
+        Series.str.rjust : Fills the left side of strings with an arbitrary
+            character. Equivalent to ``Series.str.pad(side='left')``.
+        Series.str.ljust : Fills the right side of strings with an arbitrary
+            character. Equivalent to ``Series.str.pad(side='right')``.
+        Series.str.center : Fills both sides of strings with an arbitrary
+            character. Equivalent to ``Series.str.pad(side='both')``.
+        Series.str.zfill : Pad strings in the Series/Index by prepending '0'
+            character. Equivalent to ``Series.str.pad(side='left', fillchar='0')``.
+
+        Examples
+        --------
+        >>> s = pd.Series(["caribou", "tiger"])
+        >>> s
+        0    caribou
+        1      tiger
+        dtype: object
+
+        >>> s.str.pad(width=10)
+        0       caribou
+        1         tiger
+        dtype: object
+
+        >>> s.str.pad(width=10, side='right', fillchar='-')
+        0    caribou---
+        1    tiger-----
+        dtype: object
+
+        >>> s.str.pad(width=10, side='both', fillchar='-')
+        0    -caribou--
+        1    --tiger---
+        dtype: object
+        """
+        if not isinstance(fillchar, str):
+            msg = f"fillchar must be a character, not {type(fillchar).__name__}"
+            raise TypeError(msg)
+
+        if len(fillchar) != 1:
+            raise TypeError("fillchar must be a character, not str")
+
+        if not is_integer(width):
+            msg = f"width must be of integer type, not {type(width).__name__}"
+            raise TypeError(msg)
+
+        result = self._data.array._str_pad(width, side=side, fillchar=fillchar)
+        return self._wrap_result(result)
+
+    _shared_docs[
+        "str_pad"
+    ] = """
+    Pad %(side)s side of strings in the Series/Index.
+
+    Equivalent to :meth:`str.%(method)s`.
+
+    Parameters
+    ----------
+    width : int
+        Minimum width of resulting string; additional characters will be filled
+        with ``fillchar``.
+    fillchar : str
+        Additional character for filling, default is whitespace.
+
+    Returns
+    -------
+    Series/Index of objects.
+
+    Examples
+    --------
+    For Series.str.center:
+
+    >>> ser = pd.Series(['dog', 'bird', 'mouse'])
+    >>> ser.str.center(8, fillchar='.')
+    0   ..dog...
+    1   ..bird..
+    2   .mouse..
+    dtype: object
+
+    For Series.str.ljust:
+
+    >>> ser = pd.Series(['dog', 'bird', 'mouse'])
+    >>> ser.str.ljust(8, fillchar='.')
+    0   dog.....
+    1   bird....
+    2   mouse...
+    dtype: object
+
+    For Series.str.rjust:
+
+    >>> ser = pd.Series(['dog', 'bird', 'mouse'])
+    >>> ser.str.rjust(8, fillchar='.')
+    0   .....dog
+    1   ....bird
+    2   ...mouse
+    dtype: object
+    """
+
+    @Appender(_shared_docs["str_pad"] % {"side": "left and right", "method": "center"})
+    @forbid_nonstring_types(["bytes"])
+    def center(self, width: int, fillchar: str = " "):
+        return self.pad(width, side="both", fillchar=fillchar)
+
+    @Appender(_shared_docs["str_pad"] % {"side": "right", "method": "ljust"})
+    @forbid_nonstring_types(["bytes"])
+    def ljust(self, width: int, fillchar: str = " "):
+        return self.pad(width, side="right", fillchar=fillchar)
+
+    @Appender(_shared_docs["str_pad"] % {"side": "left", "method": "rjust"})
+    @forbid_nonstring_types(["bytes"])
+    def rjust(self, width: int, fillchar: str = " "):
+        return self.pad(width, side="left", fillchar=fillchar)
+
+    @forbid_nonstring_types(["bytes"])
+    def zfill(self, width: int):
+        """
+        Pad strings in the Series/Index by prepending '0' characters.
+
+        Strings in the Series/Index are padded with '0' characters on the
+        left of the string to reach a total string length  `width`. Strings
+        in the Series/Index with length greater or equal to `width` are
+        unchanged.
+
+        Parameters
+        ----------
+        width : int
+            Minimum length of resulting string; strings with length less
+            than `width` be prepended with '0' characters.
+
+        Returns
+        -------
+        Series/Index of objects.
+
+        See Also
+        --------
+        Series.str.rjust : Fills the left side of strings with an arbitrary
+            character.
+        Series.str.ljust : Fills the right side of strings with an arbitrary
+            character.
+        Series.str.pad : Fills the specified sides of strings with an arbitrary
+            character.
+        Series.str.center : Fills both sides of strings with an arbitrary
+            character.
+
+        Notes
+        -----
+        Differs from :meth:`str.zfill` which has special handling
+        for '+'/'-' in the string.
+
+        Examples
+        --------
+        >>> s = pd.Series(['-1', '1', '1000', 10, np.nan])
+        >>> s
+        0      -1
+        1       1
+        2    1000
+        3      10
+        4     NaN
+        dtype: object
+
+        Note that ``10`` and ``NaN`` are not strings, therefore they are
+        converted to ``NaN``. The minus sign in ``'-1'`` is treated as a
+        special character and the zero is added to the right of it
+        (:meth:`str.zfill` would have moved it to the left). ``1000``
+        remains unchanged as it is longer than `width`.
+
+        >>> s.str.zfill(3)
+        0     -01
+        1     001
+        2    1000
+        3     NaN
+        4     NaN
+        dtype: object
+        """
+        if not is_integer(width):
+            msg = f"width must be of integer type, not {type(width).__name__}"
+            raise TypeError(msg)
+        f = lambda x: x.zfill(width)
+        result = self._data.array._str_map(f)
+        return self._wrap_result(result)
+
+    def slice(self, start=None, stop=None, step=None):
+        """
+        Slice substrings from each element in the Series or Index.
+
+        Parameters
+        ----------
+        start : int, optional
+            Start position for slice operation.
+        stop : int, optional
+            Stop position for slice operation.
+        step : int, optional
+            Step size for slice operation.
+
+        Returns
+        -------
+        Series or Index of object
+            Series or Index from sliced substring from original string object.
+
+        See Also
+        --------
+        Series.str.slice_replace : Replace a slice with a string.
+        Series.str.get : Return element at position.
+            Equivalent to `Series.str.slice(start=i, stop=i+1)` with `i`
+            being the position.
+
+        Examples
+        --------
+        >>> s = pd.Series(["koala", "dog", "chameleon"])
+        >>> s
+        0        koala
+        1          dog
+        2    chameleon
+        dtype: object
+
+        >>> s.str.slice(start=1)
+        0        oala
+        1          og
+        2    hameleon
+        dtype: object
+
+        >>> s.str.slice(start=-1)
+        0           a
+        1           g
+        2           n
+        dtype: object
+
+        >>> s.str.slice(stop=2)
+        0    ko
+        1    do
+        2    ch
+        dtype: object
+
+        >>> s.str.slice(step=2)
+        0      kaa
+        1       dg
+        2    caeen
+        dtype: object
+
+        >>> s.str.slice(start=0, stop=5, step=3)
+        0    kl
+        1     d
+        2    cm
+        dtype: object
+
+        Equivalent behaviour to:
+
+        >>> s.str[0:5:3]
+        0    kl
+        1     d
+        2    cm
+        dtype: object
+        """
+        result = self._data.array._str_slice(start, stop, step)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def slice_replace(self, start=None, stop=None, repl=None):
+        """
+        Replace a positional slice of a string with another value.
+
+        Parameters
+        ----------
+        start : int, optional
+            Left index position to use for the slice. If not specified (None),
+            the slice is unbounded on the left, i.e. slice from the start
+            of the string.
+        stop : int, optional
+            Right index position to use for the slice. If not specified (None),
+            the slice is unbounded on the right, i.e. slice until the
+            end of the string.
+        repl : str, optional
+            String for replacement. If not specified (None), the sliced region
+            is replaced with an empty string.
+
+        Returns
+        -------
+        Series or Index
+            Same type as the original object.
+
+        See Also
+        --------
+        Series.str.slice : Just slicing without replacement.
+
+        Examples
+        --------
+        >>> s = pd.Series(['a', 'ab', 'abc', 'abdc', 'abcde'])
+        >>> s
+        0        a
+        1       ab
+        2      abc
+        3     abdc
+        4    abcde
+        dtype: object
+
+        Specify just `start`, meaning replace `start` until the end of the
+        string with `repl`.
+
+        >>> s.str.slice_replace(1, repl='X')
+        0    aX
+        1    aX
+        2    aX
+        3    aX
+        4    aX
+        dtype: object
+
+        Specify just `stop`, meaning the start of the string to `stop` is replaced
+        with `repl`, and the rest of the string is included.
+
+        >>> s.str.slice_replace(stop=2, repl='X')
+        0       X
+        1       X
+        2      Xc
+        3     Xdc
+        4    Xcde
+        dtype: object
+
+        Specify `start` and `stop`, meaning the slice from `start` to `stop` is
+        replaced with `repl`. Everything before or after `start` and `stop` is
+        included as is.
+
+        >>> s.str.slice_replace(start=1, stop=3, repl='X')
+        0      aX
+        1      aX
+        2      aX
+        3     aXc
+        4    aXde
+        dtype: object
+        """
+        result = self._data.array._str_slice_replace(start, stop, repl)
+        return self._wrap_result(result)
+
+    def decode(
+        self, encoding, errors: str = "strict", dtype: str | DtypeObj | None = None
+    ):
+        """
+        Decode character string in the Series/Index using indicated encoding.
+
+        Equivalent to :meth:`str.decode` in python2 and :meth:`bytes.decode` in
+        python3.
+
+        Parameters
+        ----------
+        encoding : str
+        errors : str, optional
+            Specifies the error handling scheme.
+            Possible values are those supported by :meth:`bytes.decode`.
+        dtype : str or dtype, optional
+            The dtype of the result. When not ``None``, must be either a string or
+            object dtype. When ``None``, the dtype of the result is determined by
+            ``pd.options.future.infer_string``.
+
+            .. versionadded:: 2.3.0
+
+        Returns
+        -------
+        Series or Index
+
+        Examples
+        --------
+        For Series:
+
+        >>> ser = pd.Series([b'cow', b'123', b'()'])
+        >>> ser.str.decode('ascii')
+        0   cow
+        1   123
+        2   ()
+        dtype: object
+        """
+        if dtype is not None and not is_string_dtype(dtype):
+            raise ValueError(f"dtype must be string or object, got {dtype=}")
+        if dtype is None and get_option("future.infer_string"):
+            dtype = "str"
+        # TODO: Add a similar _bytes interface.
+        if encoding in _cpython_optimized_decoders:
+            # CPython optimized implementation
+            f = lambda x: x.decode(encoding, errors)
+        else:
+            decoder = codecs.getdecoder(encoding)
+            f = lambda x: decoder(x, errors)[0]
+        arr = self._data.array
+        result = arr._str_map(f)
+        return self._wrap_result(result, dtype=dtype)
+
+    @forbid_nonstring_types(["bytes"])
+    def encode(self, encoding, errors: str = "strict"):
+        """
+        Encode character string in the Series/Index using indicated encoding.
+
+        Equivalent to :meth:`str.encode`.
+
+        Parameters
+        ----------
+        encoding : str
+        errors : str, optional
+
+        Returns
+        -------
+        Series/Index of objects
+
+        Examples
+        --------
+        >>> ser = pd.Series(['cow', '123', '()'])
+        >>> ser.str.encode(encoding='ascii')
+        0     b'cow'
+        1     b'123'
+        2      b'()'
+        dtype: object
+        """
+        result = self._data.array._str_encode(encoding, errors)
+        return self._wrap_result(result, returns_string=False)
+
+    _shared_docs[
+        "str_strip"
+    ] = r"""
+    Remove %(position)s characters.
+
+    Strip whitespaces (including newlines) or a set of specified characters
+    from each string in the Series/Index from %(side)s.
+    Replaces any non-strings in Series with NaNs.
+    Equivalent to :meth:`str.%(method)s`.
+
+    Parameters
+    ----------
+    to_strip : str or None, default None
+        Specifying the set of characters to be removed.
+        All combinations of this set of characters will be stripped.
+        If None then whitespaces are removed.
+
+    Returns
+    -------
+    Series or Index of object
+
+    See Also
+    --------
+    Series.str.strip : Remove leading and trailing characters in Series/Index.
+    Series.str.lstrip : Remove leading characters in Series/Index.
+    Series.str.rstrip : Remove trailing characters in Series/Index.
+
+    Examples
+    --------
+    >>> s = pd.Series(['1. Ant.  ', '2. Bee!\n', '3. Cat?\t', np.nan, 10, True])
+    >>> s
+    0    1. Ant.
+    1    2. Bee!\n
+    2    3. Cat?\t
+    3          NaN
+    4           10
+    5         True
+    dtype: object
+
+    >>> s.str.strip()
+    0    1. Ant.
+    1    2. Bee!
+    2    3. Cat?
+    3        NaN
+    4        NaN
+    5        NaN
+    dtype: object
+
+    >>> s.str.lstrip('123.')
+    0    Ant.
+    1    Bee!\n
+    2    Cat?\t
+    3       NaN
+    4       NaN
+    5       NaN
+    dtype: object
+
+    >>> s.str.rstrip('.!? \n\t')
+    0    1. Ant
+    1    2. Bee
+    2    3. Cat
+    3       NaN
+    4       NaN
+    5       NaN
+    dtype: object
+
+    >>> s.str.strip('123.!? \n\t')
+    0    Ant
+    1    Bee
+    2    Cat
+    3    NaN
+    4    NaN
+    5    NaN
+    dtype: object
+    """
+
+    @Appender(
+        _shared_docs["str_strip"]
+        % {
+            "side": "left and right sides",
+            "method": "strip",
+            "position": "leading and trailing",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def strip(self, to_strip=None):
+        result = self._data.array._str_strip(to_strip)
+        return self._wrap_result(result)
+
+    @Appender(
+        _shared_docs["str_strip"]
+        % {"side": "left side", "method": "lstrip", "position": "leading"}
+    )
+    @forbid_nonstring_types(["bytes"])
+    def lstrip(self, to_strip=None):
+        result = self._data.array._str_lstrip(to_strip)
+        return self._wrap_result(result)
+
+    @Appender(
+        _shared_docs["str_strip"]
+        % {"side": "right side", "method": "rstrip", "position": "trailing"}
+    )
+    @forbid_nonstring_types(["bytes"])
+    def rstrip(self, to_strip=None):
+        result = self._data.array._str_rstrip(to_strip)
+        return self._wrap_result(result)
+
+    _shared_docs[
+        "str_removefix"
+    ] = r"""
+    Remove a %(side)s from an object series.
+
+    If the %(side)s is not present, the original string will be returned.
+
+    Parameters
+    ----------
+    %(side)s : str
+        Remove the %(side)s of the string.
+
+    Returns
+    -------
+    Series/Index: object
+        The Series or Index with given %(side)s removed.
+
+    See Also
+    --------
+    Series.str.remove%(other_side)s : Remove a %(other_side)s from an object series.
+
+    Examples
+    --------
+    >>> s = pd.Series(["str_foo", "str_bar", "no_prefix"])
+    >>> s
+    0    str_foo
+    1    str_bar
+    2    no_prefix
+    dtype: object
+    >>> s.str.removeprefix("str_")
+    0    foo
+    1    bar
+    2    no_prefix
+    dtype: object
+
+    >>> s = pd.Series(["foo_str", "bar_str", "no_suffix"])
+    >>> s
+    0    foo_str
+    1    bar_str
+    2    no_suffix
+    dtype: object
+    >>> s.str.removesuffix("_str")
+    0    foo
+    1    bar
+    2    no_suffix
+    dtype: object
+    """
+
+    @Appender(
+        _shared_docs["str_removefix"] % {"side": "prefix", "other_side": "suffix"}
+    )
+    @forbid_nonstring_types(["bytes"])
+    def removeprefix(self, prefix: str):
+        result = self._data.array._str_removeprefix(prefix)
+        return self._wrap_result(result)
+
+    @Appender(
+        _shared_docs["str_removefix"] % {"side": "suffix", "other_side": "prefix"}
+    )
+    @forbid_nonstring_types(["bytes"])
+    def removesuffix(self, suffix: str):
+        result = self._data.array._str_removesuffix(suffix)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def wrap(self, width: int, **kwargs):
+        r"""
+        Wrap strings in Series/Index at specified line width.
+
+        This method has the same keyword parameters and defaults as
+        :class:`textwrap.TextWrapper`.
+
+        Parameters
+        ----------
+        width : int
+            Maximum line width.
+        expand_tabs : bool, optional
+            If True, tab characters will be expanded to spaces (default: True).
+        replace_whitespace : bool, optional
+            If True, each whitespace character (as defined by string.whitespace)
+            remaining after tab expansion will be replaced by a single space
+            (default: True).
+        drop_whitespace : bool, optional
+            If True, whitespace that, after wrapping, happens to end up at the
+            beginning or end of a line is dropped (default: True).
+        break_long_words : bool, optional
+            If True, then words longer than width will be broken in order to ensure
+            that no lines are longer than width. If it is false, long words will
+            not be broken, and some lines may be longer than width (default: True).
+        break_on_hyphens : bool, optional
+            If True, wrapping will occur preferably on whitespace and right after
+            hyphens in compound words, as it is customary in English. If false,
+            only whitespaces will be considered as potentially good places for line
+            breaks, but you need to set break_long_words to false if you want truly
+            insecable words (default: True).
+
+        Returns
+        -------
+        Series or Index
+
+        Notes
+        -----
+        Internally, this method uses a :class:`textwrap.TextWrapper` instance with
+        default settings. To achieve behavior matching R's stringr library str_wrap
+        function, use the arguments:
+
+        - expand_tabs = False
+        - replace_whitespace = True
+        - drop_whitespace = True
+        - break_long_words = False
+        - break_on_hyphens = False
+
+        Examples
+        --------
+        >>> s = pd.Series(['line to be wrapped', 'another line to be wrapped'])
+        >>> s.str.wrap(12)
+        0             line to be\nwrapped
+        1    another line\nto be\nwrapped
+        dtype: object
+        """
+        result = self._data.array._str_wrap(width, **kwargs)
+        return self._wrap_result(result)
+
+    @forbid_nonstring_types(["bytes"])
+    def get_dummies(self, sep: str = "|"):
+        """
+        Return DataFrame of dummy/indicator variables for Series.
+
+        Each string in Series is split by sep and returned as a DataFrame
+        of dummy/indicator variables.
+
+        Parameters
+        ----------
+        sep : str, default "|"
+            String to split on.
+
+        Returns
+        -------
+        DataFrame
+            Dummy variables corresponding to values of the Series.
+
+        See Also
+        --------
+        get_dummies : Convert categorical variable into dummy/indicator
+            variables.
+
+        Examples
+        --------
+        >>> pd.Series(['a|b', 'a', 'a|c']).str.get_dummies()
+           a  b  c
+        0  1  1  0
+        1  1  0  0
+        2  1  0  1
+
+        >>> pd.Series(['a|b', np.nan, 'a|c']).str.get_dummies()
+           a  b  c
+        0  1  1  0
+        1  0  0  0
+        2  1  0  1
+        """
+        # we need to cast to Series of strings as only that has all
+        # methods available for making the dummies...
+        result, name = self._data.array._str_get_dummies(sep)
+        return self._wrap_result(
+            result,
+            name=name,
+            expand=True,
+            returns_string=False,
+        )
+
+    @forbid_nonstring_types(["bytes"])
+    def translate(self, table):
+        """
+        Map all characters in the string through the given mapping table.
+
+        Equivalent to standard :meth:`str.translate`.
+
+        Parameters
+        ----------
+        table : dict
+            Table is a mapping of Unicode ordinals to Unicode ordinals, strings, or
+            None. Unmapped characters are left untouched.
+            Characters mapped to None are deleted. :meth:`str.maketrans` is a
+            helper function for making translation tables.
+
+        Returns
+        -------
+        Series or Index
+
+        Examples
+        --------
+        >>> ser = pd.Series(["El niño", "Françoise"])
+        >>> mytable = str.maketrans({'ñ': 'n', 'ç': 'c'})
+        >>> ser.str.translate(mytable)
+        0   El nino
+        1   Francoise
+        dtype: object
+        """
+        result = self._data.array._str_translate(table)
+        dtype = object if self._data.dtype == "object" else None
+        return self._wrap_result(result, dtype=dtype)
+
+    @forbid_nonstring_types(["bytes"])
+    def count(self, pat, flags: int = 0):
+        r"""
+        Count occurrences of pattern in each string of the Series/Index.
+
+        This function is used to count the number of times a particular regex
+        pattern is repeated in each of the string elements of the
+        :class:`~pandas.Series`.
+
+        Parameters
+        ----------
+        pat : str
+            Valid regular expression.
+        flags : int, default 0, meaning no flags
+            Flags for the `re` module. For a complete list, `see here
+            `_.
+        **kwargs
+            For compatibility with other string methods. Not used.
+
+        Returns
+        -------
+        Series or Index
+            Same type as the calling object containing the integer counts.
+
+        See Also
+        --------
+        re : Standard library module for regular expressions.
+        str.count : Standard library version, without regular expression support.
+
+        Notes
+        -----
+        Some characters need to be escaped when passing in `pat`.
+        eg. ``'$'`` has a special meaning in regex and must be escaped when
+        finding this literal character.
+
+        Examples
+        --------
+        >>> s = pd.Series(['A', 'B', 'Aaba', 'Baca', np.nan, 'CABA', 'cat'])
+        >>> s.str.count('a')
+        0    0.0
+        1    0.0
+        2    2.0
+        3    2.0
+        4    NaN
+        5    0.0
+        6    1.0
+        dtype: float64
+
+        Escape ``'$'`` to find the literal dollar sign.
+
+        >>> s = pd.Series(['$', 'B', 'Aab$', '$$ca', 'C$B$', 'cat'])
+        >>> s.str.count('\\$')
+        0    1
+        1    0
+        2    1
+        3    2
+        4    2
+        5    0
+        dtype: int64
+
+        This is also available on Index
+
+        >>> pd.Index(['A', 'A', 'Aaba', 'cat']).str.count('a')
+        Index([0, 0, 2, 1], dtype='int64')
+        """
+        result = self._data.array._str_count(pat, flags)
+        return self._wrap_result(result, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def startswith(
+        self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default
+    ) -> Series | Index:
+        """
+        Test if the start of each string element matches a pattern.
+
+        Equivalent to :meth:`str.startswith`.
+
+        Parameters
+        ----------
+        pat : str or tuple[str, ...]
+            Character sequence or tuple of strings. Regular expressions are not
+            accepted.
+        na : scalar, optional
+            Object shown if element tested is not a string. The default depends
+            on dtype of the array. For object-dtype, ``numpy.nan`` is used.
+            For the nullable ``StringDtype``, ``pandas.NA`` is used.
+            For the ``"str"`` dtype, ``False`` is used.
+
+        Returns
+        -------
+        Series or Index of bool
+            A Series of booleans indicating whether the given pattern matches
+            the start of each string element.
+
+        See Also
+        --------
+        str.startswith : Python standard library string method.
+        Series.str.endswith : Same as startswith, but tests the end of string.
+        Series.str.contains : Tests if string element contains a pattern.
+
+        Examples
+        --------
+        >>> s = pd.Series(['bat', 'Bear', 'cat', np.nan])
+        >>> s
+        0     bat
+        1    Bear
+        2     cat
+        3     NaN
+        dtype: object
+
+        >>> s.str.startswith('b')
+        0     True
+        1    False
+        2    False
+        3      NaN
+        dtype: object
+
+        >>> s.str.startswith(('b', 'B'))
+        0     True
+        1     True
+        2    False
+        3      NaN
+        dtype: object
+
+        Specifying `na` to be `False` instead of `NaN`.
+
+        >>> s.str.startswith('b', na=False)
+        0     True
+        1    False
+        2    False
+        3    False
+        dtype: bool
+        """
+        if not isinstance(pat, (str, tuple)):
+            msg = f"expected a string or tuple, not {type(pat).__name__}"
+            raise TypeError(msg)
+        result = self._data.array._str_startswith(pat, na=na)
+        return self._wrap_result(result, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def endswith(
+        self, pat: str | tuple[str, ...], na: Scalar | lib.NoDefault = lib.no_default
+    ) -> Series | Index:
+        """
+        Test if the end of each string element matches a pattern.
+
+        Equivalent to :meth:`str.endswith`.
+
+        Parameters
+        ----------
+        pat : str or tuple[str, ...]
+            Character sequence or tuple of strings. Regular expressions are not
+            accepted.
+        na : scalar, optional
+            Object shown if element tested is not a string. The default depends
+            on dtype of the array. For object-dtype, ``numpy.nan`` is used.
+            For the nullable ``StringDtype``, ``pandas.NA`` is used.
+            For the ``"str"`` dtype, ``False`` is used.
+
+        Returns
+        -------
+        Series or Index of bool
+            A Series of booleans indicating whether the given pattern matches
+            the end of each string element.
+
+        See Also
+        --------
+        str.endswith : Python standard library string method.
+        Series.str.startswith : Same as endswith, but tests the start of string.
+        Series.str.contains : Tests if string element contains a pattern.
+
+        Examples
+        --------
+        >>> s = pd.Series(['bat', 'bear', 'caT', np.nan])
+        >>> s
+        0     bat
+        1    bear
+        2     caT
+        3     NaN
+        dtype: object
+
+        >>> s.str.endswith('t')
+        0     True
+        1    False
+        2    False
+        3      NaN
+        dtype: object
+
+        >>> s.str.endswith(('t', 'T'))
+        0     True
+        1    False
+        2     True
+        3      NaN
+        dtype: object
+
+        Specifying `na` to be `False` instead of `NaN`.
+
+        >>> s.str.endswith('t', na=False)
+        0     True
+        1    False
+        2    False
+        3    False
+        dtype: bool
+        """
+        if not isinstance(pat, (str, tuple)):
+            msg = f"expected a string or tuple, not {type(pat).__name__}"
+            raise TypeError(msg)
+        result = self._data.array._str_endswith(pat, na=na)
+        return self._wrap_result(result, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def findall(self, pat, flags: int = 0):
+        """
+        Find all occurrences of pattern or regular expression in the Series/Index.
+
+        Equivalent to applying :func:`re.findall` to all the elements in the
+        Series/Index.
+
+        Parameters
+        ----------
+        pat : str
+            Pattern or regular expression.
+        flags : int, default 0
+            Flags from ``re`` module, e.g. `re.IGNORECASE` (default is 0, which
+            means no flags).
+
+        Returns
+        -------
+        Series/Index of lists of strings
+            All non-overlapping matches of pattern or regular expression in each
+            string of this Series/Index.
+
+        See Also
+        --------
+        count : Count occurrences of pattern or regular expression in each string
+            of the Series/Index.
+        extractall : For each string in the Series, extract groups from all matches
+            of regular expression and return a DataFrame with one row for each
+            match and one column for each group.
+        re.findall : The equivalent ``re`` function to all non-overlapping matches
+            of pattern or regular expression in string, as a list of strings.
+
+        Examples
+        --------
+        >>> s = pd.Series(['Lion', 'Monkey', 'Rabbit'])
+
+        The search for the pattern 'Monkey' returns one match:
+
+        >>> s.str.findall('Monkey')
+        0          []
+        1    [Monkey]
+        2          []
+        dtype: object
+
+        On the other hand, the search for the pattern 'MONKEY' doesn't return any
+        match:
+
+        >>> s.str.findall('MONKEY')
+        0    []
+        1    []
+        2    []
+        dtype: object
+
+        Flags can be added to the pattern or regular expression. For instance,
+        to find the pattern 'MONKEY' ignoring the case:
+
+        >>> import re
+        >>> s.str.findall('MONKEY', flags=re.IGNORECASE)
+        0          []
+        1    [Monkey]
+        2          []
+        dtype: object
+
+        When the pattern matches more than one string in the Series, all matches
+        are returned:
+
+        >>> s.str.findall('on')
+        0    [on]
+        1    [on]
+        2      []
+        dtype: object
+
+        Regular expressions are supported too. For instance, the search for all the
+        strings ending with the word 'on' is shown next:
+
+        >>> s.str.findall('on$')
+        0    [on]
+        1      []
+        2      []
+        dtype: object
+
+        If the pattern is found more than once in the same string, then a list of
+        multiple strings is returned:
+
+        >>> s.str.findall('b')
+        0        []
+        1        []
+        2    [b, b]
+        dtype: object
+        """
+        result = self._data.array._str_findall(pat, flags)
+        return self._wrap_result(result, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def extract(
+        self, pat: str, flags: int = 0, expand: bool = True
+    ) -> DataFrame | Series | Index:
+        r"""
+        Extract capture groups in the regex `pat` as columns in a DataFrame.
+
+        For each subject string in the Series, extract groups from the
+        first match of regular expression `pat`.
+
+        Parameters
+        ----------
+        pat : str
+            Regular expression pattern with capturing groups.
+        flags : int, default 0 (no flags)
+            Flags from the ``re`` module, e.g. ``re.IGNORECASE``, that
+            modify regular expression matching for things like case,
+            spaces, etc. For more details, see :mod:`re`.
+        expand : bool, default True
+            If True, return DataFrame with one column per capture group.
+            If False, return a Series/Index if there is one capture group
+            or DataFrame if there are multiple capture groups.
+
+        Returns
+        -------
+        DataFrame or Series or Index
+            A DataFrame with one row for each subject string, and one
+            column for each group. Any capture group names in regular
+            expression pat will be used for column names; otherwise
+            capture group numbers will be used. The dtype of each result
+            column is always object, even when no match is found. If
+            ``expand=False`` and pat has only one capture group, then
+            return a Series (if subject is a Series) or Index (if subject
+            is an Index).
+
+        See Also
+        --------
+        extractall : Returns all matches (not just the first match).
+
+        Examples
+        --------
+        A pattern with two groups will return a DataFrame with two columns.
+        Non-matches will be NaN.
+
+        >>> s = pd.Series(['a1', 'b2', 'c3'])
+        >>> s.str.extract(r'([ab])(\d)')
+            0    1
+        0    a    1
+        1    b    2
+        2  NaN  NaN
+
+        A pattern may contain optional groups.
+
+        >>> s.str.extract(r'([ab])?(\d)')
+            0  1
+        0    a  1
+        1    b  2
+        2  NaN  3
+
+        Named groups will become column names in the result.
+
+        >>> s.str.extract(r'(?P[ab])(?P\d)')
+        letter digit
+        0      a     1
+        1      b     2
+        2    NaN   NaN
+
+        A pattern with one group will return a DataFrame with one column
+        if expand=True.
+
+        >>> s.str.extract(r'[ab](\d)', expand=True)
+            0
+        0    1
+        1    2
+        2  NaN
+
+        A pattern with one group will return a Series if expand=False.
+
+        >>> s.str.extract(r'[ab](\d)', expand=False)
+        0      1
+        1      2
+        2    NaN
+        dtype: object
+        """
+        from pandas import DataFrame
+
+        if not isinstance(expand, bool):
+            raise ValueError("expand must be True or False")
+
+        regex = re.compile(pat, flags=flags)
+        if regex.groups == 0:
+            raise ValueError("pattern contains no capture groups")
+
+        if not expand and regex.groups > 1 and isinstance(self._data, ABCIndex):
+            raise ValueError("only one regex group is supported with Index")
+
+        obj = self._data
+        result_dtype = _result_dtype(obj)
+
+        returns_df = regex.groups > 1 or expand
+
+        if returns_df:
+            name = None
+            columns = _get_group_names(regex)
+
+            if obj.array.size == 0:
+                result = DataFrame(columns=columns, dtype=result_dtype)
+
+            else:
+                result_list = self._data.array._str_extract(
+                    pat, flags=flags, expand=returns_df
+                )
+
+                result_index: Index | None
+                if isinstance(obj, ABCSeries):
+                    result_index = obj.index
+                else:
+                    result_index = None
+
+                result = DataFrame(
+                    result_list, columns=columns, index=result_index, dtype=result_dtype
+                )
+
+        else:
+            name = _get_single_group_name(regex)
+            result = self._data.array._str_extract(pat, flags=flags, expand=returns_df)
+        return self._wrap_result(result, name=name, dtype=result_dtype)
+
+    @forbid_nonstring_types(["bytes"])
+    def extractall(self, pat, flags: int = 0) -> DataFrame:
+        r"""
+        Extract capture groups in the regex `pat` as columns in DataFrame.
+
+        For each subject string in the Series, extract groups from all
+        matches of regular expression pat. When each subject string in the
+        Series has exactly one match, extractall(pat).xs(0, level='match')
+        is the same as extract(pat).
+
+        Parameters
+        ----------
+        pat : str
+            Regular expression pattern with capturing groups.
+        flags : int, default 0 (no flags)
+            A ``re`` module flag, for example ``re.IGNORECASE``. These allow
+            to modify regular expression matching for things like case, spaces,
+            etc. Multiple flags can be combined with the bitwise OR operator,
+            for example ``re.IGNORECASE | re.MULTILINE``.
+
+        Returns
+        -------
+        DataFrame
+            A ``DataFrame`` with one row for each match, and one column for each
+            group. Its rows have a ``MultiIndex`` with first levels that come from
+            the subject ``Series``. The last level is named 'match' and indexes the
+            matches in each item of the ``Series``. Any capture group names in
+            regular expression pat will be used for column names; otherwise capture
+            group numbers will be used.
+
+        See Also
+        --------
+        extract : Returns first match only (not all matches).
+
+        Examples
+        --------
+        A pattern with one group will return a DataFrame with one column.
+        Indices with no matches will not appear in the result.
+
+        >>> s = pd.Series(["a1a2", "b1", "c1"], index=["A", "B", "C"])
+        >>> s.str.extractall(r"[ab](\d)")
+                0
+        match
+        A 0      1
+          1      2
+        B 0      1
+
+        Capture group names are used for column names of the result.
+
+        >>> s.str.extractall(r"[ab](?P\d)")
+                digit
+        match
+        A 0         1
+          1         2
+        B 0         1
+
+        A pattern with two groups will return a DataFrame with two columns.
+
+        >>> s.str.extractall(r"(?P[ab])(?P\d)")
+                letter digit
+        match
+        A 0          a     1
+          1          a     2
+        B 0          b     1
+
+        Optional groups that do not match are NaN in the result.
+
+        >>> s.str.extractall(r"(?P[ab])?(?P\d)")
+                letter digit
+        match
+        A 0          a     1
+          1          a     2
+        B 0          b     1
+        C 0        NaN     1
+        """
+        # TODO: dispatch
+        return str_extractall(self._orig, pat, flags)
+
+    _shared_docs[
+        "find"
+    ] = """
+    Return %(side)s indexes in each strings in the Series/Index.
+
+    Each of returned indexes corresponds to the position where the
+    substring is fully contained between [start:end]. Return -1 on
+    failure. Equivalent to standard :meth:`str.%(method)s`.
+
+    Parameters
+    ----------
+    sub : str
+        Substring being searched.
+    start : int
+        Left edge index.
+    end : int
+        Right edge index.
+
+    Returns
+    -------
+    Series or Index of int.
+
+    See Also
+    --------
+    %(also)s
+
+    Examples
+    --------
+    For Series.str.find:
+
+    >>> ser = pd.Series(["cow_", "duck_", "do_ve"])
+    >>> ser.str.find("_")
+    0   3
+    1   4
+    2   2
+    dtype: int64
+
+    For Series.str.rfind:
+
+    >>> ser = pd.Series(["_cow_", "duck_", "do_v_e"])
+    >>> ser.str.rfind("_")
+    0   4
+    1   4
+    2   4
+    dtype: int64
+    """
+
+    @Appender(
+        _shared_docs["find"]
+        % {
+            "side": "lowest",
+            "method": "find",
+            "also": "rfind : Return highest indexes in each strings.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def find(self, sub, start: int = 0, end=None):
+        if not isinstance(sub, str):
+            msg = f"expected a string object, not {type(sub).__name__}"
+            raise TypeError(msg)
+
+        result = self._data.array._str_find(sub, start, end)
+        return self._wrap_result(result, returns_string=False)
+
+    @Appender(
+        _shared_docs["find"]
+        % {
+            "side": "highest",
+            "method": "rfind",
+            "also": "find : Return lowest indexes in each strings.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def rfind(self, sub, start: int = 0, end=None):
+        if not isinstance(sub, str):
+            msg = f"expected a string object, not {type(sub).__name__}"
+            raise TypeError(msg)
+
+        result = self._data.array._str_rfind(sub, start=start, end=end)
+        return self._wrap_result(result, returns_string=False)
+
+    @forbid_nonstring_types(["bytes"])
+    def normalize(self, form):
+        """
+        Return the Unicode normal form for the strings in the Series/Index.
+
+        For more information on the forms, see the
+        :func:`unicodedata.normalize`.
+
+        Parameters
+        ----------
+        form : {'NFC', 'NFKC', 'NFD', 'NFKD'}
+            Unicode form.
+
+        Returns
+        -------
+        Series/Index of objects
+
+        Examples
+        --------
+        >>> ser = pd.Series(['ñ'])
+        >>> ser.str.normalize('NFC') == ser.str.normalize('NFD')
+        0   False
+        dtype: bool
+        """
+        result = self._data.array._str_normalize(form)
+        return self._wrap_result(result)
+
+    _shared_docs[
+        "index"
+    ] = """
+    Return %(side)s indexes in each string in Series/Index.
+
+    Each of the returned indexes corresponds to the position where the
+    substring is fully contained between [start:end]. This is the same
+    as ``str.%(similar)s`` except instead of returning -1, it raises a
+    ValueError when the substring is not found. Equivalent to standard
+    ``str.%(method)s``.
+
+    Parameters
+    ----------
+    sub : str
+        Substring being searched.
+    start : int
+        Left edge index.
+    end : int
+        Right edge index.
+
+    Returns
+    -------
+    Series or Index of object
+
+    See Also
+    --------
+    %(also)s
+
+    Examples
+    --------
+    For Series.str.index:
+
+    >>> ser = pd.Series(["horse", "eagle", "donkey"])
+    >>> ser.str.index("e")
+    0   4
+    1   0
+    2   4
+    dtype: int64
+
+    For Series.str.rindex:
+
+    >>> ser = pd.Series(["Deer", "eagle", "Sheep"])
+    >>> ser.str.rindex("e")
+    0   2
+    1   4
+    2   3
+    dtype: int64
+    """
+
+    @Appender(
+        _shared_docs["index"]
+        % {
+            "side": "lowest",
+            "similar": "find",
+            "method": "index",
+            "also": "rindex : Return highest indexes in each strings.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def index(self, sub, start: int = 0, end=None):
+        if not isinstance(sub, str):
+            msg = f"expected a string object, not {type(sub).__name__}"
+            raise TypeError(msg)
+
+        result = self._data.array._str_index(sub, start=start, end=end)
+        return self._wrap_result(result, returns_string=False)
+
+    @Appender(
+        _shared_docs["index"]
+        % {
+            "side": "highest",
+            "similar": "rfind",
+            "method": "rindex",
+            "also": "index : Return lowest indexes in each strings.",
+        }
+    )
+    @forbid_nonstring_types(["bytes"])
+    def rindex(self, sub, start: int = 0, end=None):
+        if not isinstance(sub, str):
+            msg = f"expected a string object, not {type(sub).__name__}"
+            raise TypeError(msg)
+
+        result = self._data.array._str_rindex(sub, start=start, end=end)
+        return self._wrap_result(result, returns_string=False)
+
+    def len(self):
+        """
+        Compute the length of each element in the Series/Index.
+
+        The element may be a sequence (such as a string, tuple or list) or a collection
+        (such as a dictionary).
+
+        Returns
+        -------
+        Series or Index of int
+            A Series or Index of integer values indicating the length of each
+            element in the Series or Index.
+
+        See Also
+        --------
+        str.len : Python built-in function returning the length of an object.
+        Series.size : Returns the length of the Series.
+
+        Examples
+        --------
+        Returns the length (number of characters) in a string. Returns the
+        number of entries for dictionaries, lists or tuples.
+
+        >>> s = pd.Series(['dog',
+        ...                 '',
+        ...                 5,
+        ...                 {'foo' : 'bar'},
+        ...                 [2, 3, 5, 7],
+        ...                 ('one', 'two', 'three')])
+        >>> s
+        0                  dog
+        1
+        2                    5
+        3       {'foo': 'bar'}
+        4         [2, 3, 5, 7]
+        5    (one, two, three)
+        dtype: object
+        >>> s.str.len()
+        0    3.0
+        1    0.0
+        2    NaN
+        3    1.0
+        4    4.0
+        5    3.0
+        dtype: float64
+        """
+        result = self._data.array._str_len()
+        return self._wrap_result(result, returns_string=False)
+
+    _shared_docs[
+        "casemethods"
+    ] = """
+    Convert strings in the Series/Index to %(type)s.
+    %(version)s
+    Equivalent to :meth:`str.%(method)s`.
+
+    Returns
+    -------
+    Series or Index of object
+
+    See Also
+    --------
+    Series.str.lower : Converts all characters to lowercase.
+    Series.str.upper : Converts all characters to uppercase.
+    Series.str.title : Converts first character of each word to uppercase and
+        remaining to lowercase.
+    Series.str.capitalize : Converts first character to uppercase and
+        remaining to lowercase.
+    Series.str.swapcase : Converts uppercase to lowercase and lowercase to
+        uppercase.
+    Series.str.casefold: Removes all case distinctions in the string.
+
+    Examples
+    --------
+    >>> s = pd.Series(['lower', 'CAPITALS', 'this is a sentence', 'SwApCaSe'])
+    >>> s
+    0                 lower
+    1              CAPITALS
+    2    this is a sentence
+    3              SwApCaSe
+    dtype: object
+
+    >>> s.str.lower()
+    0                 lower
+    1              capitals
+    2    this is a sentence
+    3              swapcase
+    dtype: object
+
+    >>> s.str.upper()
+    0                 LOWER
+    1              CAPITALS
+    2    THIS IS A SENTENCE
+    3              SWAPCASE
+    dtype: object
+
+    >>> s.str.title()
+    0                 Lower
+    1              Capitals
+    2    This Is A Sentence
+    3              Swapcase
+    dtype: object
+
+    >>> s.str.capitalize()
+    0                 Lower
+    1              Capitals
+    2    This is a sentence
+    3              Swapcase
+    dtype: object
+
+    >>> s.str.swapcase()
+    0                 LOWER
+    1              capitals
+    2    THIS IS A SENTENCE
+    3              sWaPcAsE
+    dtype: object
+    """
+    # Types:
+    #   cases:
+    #       upper, lower, title, capitalize, swapcase, casefold
+    #   boolean:
+    #     isalpha, isnumeric isalnum isdigit isdecimal isspace islower isupper istitle
+    # _doc_args holds dict of strings to use in substituting casemethod docs
+    _doc_args: dict[str, dict[str, str]] = {}
+    _doc_args["lower"] = {"type": "lowercase", "method": "lower", "version": ""}
+    _doc_args["upper"] = {"type": "uppercase", "method": "upper", "version": ""}
+    _doc_args["title"] = {"type": "titlecase", "method": "title", "version": ""}
+    _doc_args["capitalize"] = {
+        "type": "be capitalized",
+        "method": "capitalize",
+        "version": "",
+    }
+    _doc_args["swapcase"] = {
+        "type": "be swapcased",
+        "method": "swapcase",
+        "version": "",
+    }
+    _doc_args["casefold"] = {
+        "type": "be casefolded",
+        "method": "casefold",
+        "version": "",
+    }
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["lower"])
+    @forbid_nonstring_types(["bytes"])
+    def lower(self):
+        result = self._data.array._str_lower()
+        return self._wrap_result(result)
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["upper"])
+    @forbid_nonstring_types(["bytes"])
+    def upper(self):
+        result = self._data.array._str_upper()
+        return self._wrap_result(result)
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["title"])
+    @forbid_nonstring_types(["bytes"])
+    def title(self):
+        result = self._data.array._str_title()
+        return self._wrap_result(result)
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["capitalize"])
+    @forbid_nonstring_types(["bytes"])
+    def capitalize(self):
+        result = self._data.array._str_capitalize()
+        return self._wrap_result(result)
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["swapcase"])
+    @forbid_nonstring_types(["bytes"])
+    def swapcase(self):
+        result = self._data.array._str_swapcase()
+        return self._wrap_result(result)
+
+    @Appender(_shared_docs["casemethods"] % _doc_args["casefold"])
+    @forbid_nonstring_types(["bytes"])
+    def casefold(self):
+        result = self._data.array._str_casefold()
+        return self._wrap_result(result)
+
+    _shared_docs[
+        "ismethods"
+    ] = """
+    Check whether all characters in each string are %(type)s.
+
+    This is equivalent to running the Python string method
+    :meth:`str.%(method)s` for each element of the Series/Index. If a string
+    has zero characters, ``False`` is returned for that check.
+
+    Returns
+    -------
+    Series or Index of bool
+        Series or Index of boolean values with the same length as the original
+        Series/Index.
+
+    See Also
+    --------
+    Series.str.isalpha : Check whether all characters are alphabetic.
+    Series.str.isnumeric : Check whether all characters are numeric.
+    Series.str.isalnum : Check whether all characters are alphanumeric.
+    Series.str.isdigit : Check whether all characters are digits.
+    Series.str.isdecimal : Check whether all characters are decimal.
+    Series.str.isspace : Check whether all characters are whitespace.
+    Series.str.islower : Check whether all characters are lowercase.
+    Series.str.isupper : Check whether all characters are uppercase.
+    Series.str.istitle : Check whether all characters are titlecase.
+
+    Examples
+    --------
+    **Checks for Alphabetic and Numeric Characters**
+
+    >>> s1 = pd.Series(['one', 'one1', '1', ''])
+
+    >>> s1.str.isalpha()
+    0     True
+    1    False
+    2    False
+    3    False
+    dtype: bool
+
+    >>> s1.str.isnumeric()
+    0    False
+    1    False
+    2     True
+    3    False
+    dtype: bool
+
+    >>> s1.str.isalnum()
+    0     True
+    1     True
+    2     True
+    3    False
+    dtype: bool
+
+    Note that checks against characters mixed with any additional punctuation
+    or whitespace will evaluate to false for an alphanumeric check.
+
+    >>> s2 = pd.Series(['A B', '1.5', '3,000'])
+    >>> s2.str.isalnum()
+    0    False
+    1    False
+    2    False
+    dtype: bool
+
+    **More Detailed Checks for Numeric Characters**
+
+    There are several different but overlapping sets of numeric characters that
+    can be checked for.
+
+    >>> s3 = pd.Series(['23', '³', '⅕', ''])
+
+    The ``s3.str.isdecimal`` method checks for characters used to form numbers
+    in base 10.
+
+    >>> s3.str.isdecimal()
+    0     True
+    1    False
+    2    False
+    3    False
+    dtype: bool
+
+    The ``s.str.isdigit`` method is the same as ``s3.str.isdecimal`` but also
+    includes special digits, like superscripted and subscripted digits in
+    unicode.
+
+    >>> s3.str.isdigit()
+    0     True
+    1     True
+    2    False
+    3    False
+    dtype: bool
+
+    The ``s.str.isnumeric`` method is the same as ``s3.str.isdigit`` but also
+    includes other characters that can represent quantities such as unicode
+    fractions.
+
+    >>> s3.str.isnumeric()
+    0     True
+    1     True
+    2     True
+    3    False
+    dtype: bool
+
+    **Checks for Whitespace**
+
+    >>> s4 = pd.Series([' ', '\\t\\r\\n ', ''])
+    >>> s4.str.isspace()
+    0     True
+    1     True
+    2    False
+    dtype: bool
+
+    **Checks for Character Case**
+
+    >>> s5 = pd.Series(['leopard', 'Golden Eagle', 'SNAKE', ''])
+
+    >>> s5.str.islower()
+    0     True
+    1    False
+    2    False
+    3    False
+    dtype: bool
+
+    >>> s5.str.isupper()
+    0    False
+    1    False
+    2     True
+    3    False
+    dtype: bool
+
+    The ``s5.str.istitle`` method checks for whether all words are in title
+    case (whether only the first letter of each word is capitalized). Words are
+    assumed to be as any sequence of non-numeric characters separated by
+    whitespace characters.
+
+    >>> s5.str.istitle()
+    0    False
+    1     True
+    2    False
+    3    False
+    dtype: bool
+    """
+    _doc_args["isalnum"] = {"type": "alphanumeric", "method": "isalnum"}
+    _doc_args["isalpha"] = {"type": "alphabetic", "method": "isalpha"}
+    _doc_args["isdigit"] = {"type": "digits", "method": "isdigit"}
+    _doc_args["isspace"] = {"type": "whitespace", "method": "isspace"}
+    _doc_args["islower"] = {"type": "lowercase", "method": "islower"}
+    _doc_args["isupper"] = {"type": "uppercase", "method": "isupper"}
+    _doc_args["istitle"] = {"type": "titlecase", "method": "istitle"}
+    _doc_args["isnumeric"] = {"type": "numeric", "method": "isnumeric"}
+    _doc_args["isdecimal"] = {"type": "decimal", "method": "isdecimal"}
+    # force _noarg_wrapper return type with dtype=np.dtype(bool) (GH 29624)
+
+    isalnum = _map_and_wrap(
+        "isalnum", docstring=_shared_docs["ismethods"] % _doc_args["isalnum"]
+    )
+    isalpha = _map_and_wrap(
+        "isalpha", docstring=_shared_docs["ismethods"] % _doc_args["isalpha"]
+    )
+    isdigit = _map_and_wrap(
+        "isdigit", docstring=_shared_docs["ismethods"] % _doc_args["isdigit"]
+    )
+    isspace = _map_and_wrap(
+        "isspace", docstring=_shared_docs["ismethods"] % _doc_args["isspace"]
+    )
+    islower = _map_and_wrap(
+        "islower", docstring=_shared_docs["ismethods"] % _doc_args["islower"]
+    )
+    isupper = _map_and_wrap(
+        "isupper", docstring=_shared_docs["ismethods"] % _doc_args["isupper"]
+    )
+    istitle = _map_and_wrap(
+        "istitle", docstring=_shared_docs["ismethods"] % _doc_args["istitle"]
+    )
+    isnumeric = _map_and_wrap(
+        "isnumeric", docstring=_shared_docs["ismethods"] % _doc_args["isnumeric"]
+    )
+    isdecimal = _map_and_wrap(
+        "isdecimal", docstring=_shared_docs["ismethods"] % _doc_args["isdecimal"]
+    )
+
+
+def cat_safe(list_of_columns: list[npt.NDArray[np.object_]], sep: str):
+    """
+    Auxiliary function for :meth:`str.cat`.
+
+    Same signature as cat_core, but handles TypeErrors in concatenation, which
+    happen if the arrays in list_of columns have the wrong dtypes or content.
+
+    Parameters
+    ----------
+    list_of_columns : list of numpy arrays
+        List of arrays to be concatenated with sep;
+        these arrays may not contain NaNs!
+    sep : string
+        The separator string for concatenating the columns.
+
+    Returns
+    -------
+    nd.array
+        The concatenation of list_of_columns with sep.
+    """
+    try:
+        result = cat_core(list_of_columns, sep)
+    except TypeError:
+        # if there are any non-string values (wrong dtype or hidden behind
+        # object dtype), np.sum will fail; catch and return with better message
+        for column in list_of_columns:
+            dtype = lib.infer_dtype(column, skipna=True)
+            if dtype not in ["string", "empty"]:
+                raise TypeError(
+                    "Concatenation requires list-likes containing only "
+                    "strings (or missing values). Offending values found in "
+                    f"column {dtype}"
+                ) from None
+    return result
+
+
+def cat_core(list_of_columns: list, sep: str):
+    """
+    Auxiliary function for :meth:`str.cat`
+
+    Parameters
+    ----------
+    list_of_columns : list of numpy arrays
+        List of arrays to be concatenated with sep;
+        these arrays may not contain NaNs!
+    sep : string
+        The separator string for concatenating the columns.
+
+    Returns
+    -------
+    nd.array
+        The concatenation of list_of_columns with sep.
+    """
+    if sep == "":
+        # no need to interleave sep if it is empty
+        arr_of_cols = np.asarray(list_of_columns, dtype=object)
+        return np.sum(arr_of_cols, axis=0)
+    list_with_sep = [sep] * (2 * len(list_of_columns) - 1)
+    list_with_sep[::2] = list_of_columns
+    arr_with_sep = np.asarray(list_with_sep, dtype=object)
+    return np.sum(arr_with_sep, axis=0)
+
+
+def _result_dtype(arr):
+    # workaround #27953
+    # ideally we just pass `dtype=arr.dtype` unconditionally, but this fails
+    # when the list of values is empty.
+    from pandas.core.arrays.string_ import StringDtype
+
+    if isinstance(arr.dtype, (ArrowDtype, StringDtype)):
+        return arr.dtype
+    return object
+
+
+def _get_single_group_name(regex: re.Pattern) -> Hashable:
+    if regex.groupindex:
+        return next(iter(regex.groupindex))
+    else:
+        return None
+
+
+def _get_group_names(regex: re.Pattern) -> list[Hashable]:
+    """
+    Get named groups from compiled regex.
+
+    Unnamed groups are numbered.
+
+    Parameters
+    ----------
+    regex : compiled regex
+
+    Returns
+    -------
+    list of column labels
+    """
+    names = {v: k for k, v in regex.groupindex.items()}
+    return [names.get(1 + i, i) for i in range(regex.groups)]
+
+
+def str_extractall(arr, pat, flags: int = 0) -> DataFrame:
+    regex = re.compile(pat, flags=flags)
+    # the regex must contain capture groups.
+    if regex.groups == 0:
+        raise ValueError("pattern contains no capture groups")
+
+    if isinstance(arr, ABCIndex):
+        arr = arr.to_series().reset_index(drop=True).astype(arr.dtype)
+
+    columns = _get_group_names(regex)
+    match_list = []
+    index_list = []
+    is_mi = arr.index.nlevels > 1
+
+    for subject_key, subject in arr.items():
+        if isinstance(subject, str):
+            if not is_mi:
+                subject_key = (subject_key,)
+
+            for match_i, match_tuple in enumerate(regex.findall(subject)):
+                if isinstance(match_tuple, str):
+                    match_tuple = (match_tuple,)
+                na_tuple = [np.nan if group == "" else group for group in match_tuple]
+                match_list.append(na_tuple)
+                result_key = tuple(subject_key + (match_i,))
+                index_list.append(result_key)
+
+    from pandas import MultiIndex
+
+    index = MultiIndex.from_tuples(index_list, names=arr.index.names + ["match"])
+    dtype = _result_dtype(arr)
+
+    result = arr._constructor_expanddim(
+        match_list, index=index, columns=columns, dtype=dtype
+    )
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/strings/base.py b/.venv/lib/python3.13/site-packages/pandas/core/strings/base.py
new file mode 100644
index 0000000000000000000000000000000000000000..316c86d152db32048f4de154ead0ec8fc76ec027
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/strings/base.py
@@ -0,0 +1,266 @@
+from __future__ import annotations
+
+import abc
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+)
+
+from pandas._libs import lib
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    import re
+
+    from pandas._typing import Scalar
+
+    from pandas import Series
+
+
+class BaseStringArrayMethods(abc.ABC):
+    """
+    Base class for extension arrays implementing string methods.
+
+    This is where our ExtensionArrays can override the implementation of
+    Series.str.. We don't expect this to work with
+    3rd-party extension arrays.
+
+    * User calls Series.str.
+    * pandas extracts the extension array from the Series
+    * pandas calls ``extension_array._str_(*args, **kwargs)``
+    * pandas wraps the result, to return to the user.
+
+    See :ref:`Series.str` for the docstring of each method.
+    """
+
+    def _str_getitem(self, key):
+        if isinstance(key, slice):
+            return self._str_slice(start=key.start, stop=key.stop, step=key.step)
+        else:
+            return self._str_get(key)
+
+    @abc.abstractmethod
+    def _str_count(self, pat, flags: int = 0):
+        pass
+
+    @abc.abstractmethod
+    def _str_pad(
+        self,
+        width: int,
+        side: Literal["left", "right", "both"] = "left",
+        fillchar: str = " ",
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_contains(
+        self, pat, case: bool = True, flags: int = 0, na=None, regex: bool = True
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_startswith(self, pat, na=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_endswith(self, pat, na=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_replace(
+        self,
+        pat: str | re.Pattern,
+        repl: str | Callable,
+        n: int = -1,
+        case: bool = True,
+        flags: int = 0,
+        regex: bool = True,
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_repeat(self, repeats: int | Sequence[int]):
+        pass
+
+    @abc.abstractmethod
+    def _str_match(
+        self,
+        pat: str,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_fullmatch(
+        self,
+        pat: str | re.Pattern,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_encode(self, encoding, errors: str = "strict"):
+        pass
+
+    @abc.abstractmethod
+    def _str_find(self, sub, start: int = 0, end=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_rfind(self, sub, start: int = 0, end=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_findall(self, pat, flags: int = 0):
+        pass
+
+    @abc.abstractmethod
+    def _str_get(self, i):
+        pass
+
+    @abc.abstractmethod
+    def _str_index(self, sub, start: int = 0, end=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_rindex(self, sub, start: int = 0, end=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_join(self, sep: str):
+        pass
+
+    @abc.abstractmethod
+    def _str_partition(self, sep: str, expand):
+        pass
+
+    @abc.abstractmethod
+    def _str_rpartition(self, sep: str, expand):
+        pass
+
+    @abc.abstractmethod
+    def _str_len(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_slice(self, start=None, stop=None, step=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_slice_replace(self, start=None, stop=None, repl=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_translate(self, table):
+        pass
+
+    @abc.abstractmethod
+    def _str_wrap(self, width: int, **kwargs):
+        pass
+
+    @abc.abstractmethod
+    def _str_get_dummies(self, sep: str = "|"):
+        pass
+
+    @abc.abstractmethod
+    def _str_isalnum(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isalpha(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isdecimal(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isdigit(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_islower(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isnumeric(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isspace(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_istitle(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_isupper(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_capitalize(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_casefold(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_title(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_swapcase(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_lower(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_upper(self):
+        pass
+
+    @abc.abstractmethod
+    def _str_normalize(self, form):
+        pass
+
+    @abc.abstractmethod
+    def _str_strip(self, to_strip=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_lstrip(self, to_strip=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_rstrip(self, to_strip=None):
+        pass
+
+    @abc.abstractmethod
+    def _str_removeprefix(self, prefix: str) -> Series:
+        pass
+
+    @abc.abstractmethod
+    def _str_removesuffix(self, suffix: str) -> Series:
+        pass
+
+    @abc.abstractmethod
+    def _str_split(
+        self, pat=None, n=-1, expand: bool = False, regex: bool | None = None
+    ):
+        pass
+
+    @abc.abstractmethod
+    def _str_rsplit(self, pat=None, n=-1):
+        pass
+
+    @abc.abstractmethod
+    def _str_extract(self, pat: str, flags: int = 0, expand: bool = True):
+        pass
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/strings/object_array.py b/.venv/lib/python3.13/site-packages/pandas/core/strings/object_array.py
new file mode 100644
index 0000000000000000000000000000000000000000..05ffee662dbac69e2e942e37f0701d4b65adb6af
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/strings/object_array.py
@@ -0,0 +1,534 @@
+from __future__ import annotations
+
+import functools
+import re
+import textwrap
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+    cast,
+)
+import unicodedata
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+import pandas._libs.missing as libmissing
+import pandas._libs.ops as libops
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.strings.base import BaseStringArrayMethods
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from pandas._typing import (
+        NpDtype,
+        Scalar,
+    )
+
+    from pandas import Series
+
+
+class ObjectStringArrayMixin(BaseStringArrayMethods):
+    """
+    String Methods operating on object-dtype ndarrays.
+    """
+
+    def __len__(self) -> int:
+        # For typing, _str_map relies on the object being sized.
+        raise NotImplementedError
+
+    def _str_map(
+        self,
+        f,
+        na_value=lib.no_default,
+        dtype: NpDtype | None = None,
+        convert: bool = True,
+    ):
+        """
+        Map a callable over valid elements of the array.
+
+        Parameters
+        ----------
+        f : Callable
+            A function to call on each non-NA element.
+        na_value : Scalar, optional
+            The value to set for NA values. Might also be used for the
+            fill value if the callable `f` raises an exception.
+            This defaults to ``self.dtype.na_value`` which is ``np.nan``
+            for object-dtype and Categorical and ``pd.NA`` for StringArray.
+        dtype : Dtype, optional
+            The dtype of the result array.
+        convert : bool, default True
+            Whether to call `maybe_convert_objects` on the resulting ndarray
+        """
+        if dtype is None:
+            dtype = np.dtype("object")
+        if na_value is lib.no_default:
+            na_value = self.dtype.na_value  # type: ignore[attr-defined]
+
+        if not len(self):
+            return np.array([], dtype=dtype)
+
+        arr = np.asarray(self, dtype=object)
+        mask = isna(arr)
+        map_convert = convert and not np.all(mask)
+        try:
+            result = lib.map_infer_mask(arr, f, mask.view(np.uint8), map_convert)
+        except (TypeError, AttributeError) as err:
+            # Reraise the exception if callable `f` got wrong number of args.
+            # The user may want to be warned by this, instead of getting NaN
+            p_err = (
+                r"((takes)|(missing)) (?(2)from \d+ to )?\d+ "
+                r"(?(3)required )positional arguments?"
+            )
+
+            if len(err.args) >= 1 and re.search(p_err, err.args[0]):
+                # FIXME: this should be totally avoidable
+                raise err
+
+            def g(x):
+                # This type of fallback behavior can be removed once
+                # we remove object-dtype .str accessor.
+                try:
+                    return f(x)
+                except (TypeError, AttributeError):
+                    return na_value
+
+            return self._str_map(g, na_value=na_value, dtype=dtype)
+        if not isinstance(result, np.ndarray):
+            return result
+        if na_value is not np.nan:
+            np.putmask(result, mask, na_value)
+            if convert and result.dtype == object:
+                result = lib.maybe_convert_objects(result)
+        return result
+
+    def _str_count(self, pat, flags: int = 0):
+        regex = re.compile(pat, flags=flags)
+        f = lambda x: len(regex.findall(x))
+        return self._str_map(f, dtype="int64")
+
+    def _str_pad(
+        self,
+        width: int,
+        side: Literal["left", "right", "both"] = "left",
+        fillchar: str = " ",
+    ):
+        if side == "left":
+            f = lambda x: x.rjust(width, fillchar)
+        elif side == "right":
+            f = lambda x: x.ljust(width, fillchar)
+        elif side == "both":
+            f = lambda x: x.center(width, fillchar)
+        else:  # pragma: no cover
+            raise ValueError("Invalid side")
+        return self._str_map(f)
+
+    def _str_contains(
+        self,
+        pat,
+        case: bool = True,
+        flags: int = 0,
+        na=lib.no_default,
+        regex: bool = True,
+    ):
+        if regex:
+            if not case:
+                flags |= re.IGNORECASE
+
+            pat = re.compile(pat, flags=flags)
+
+            f = lambda x: pat.search(x) is not None
+        else:
+            if case:
+                f = lambda x: pat in x
+            else:
+                upper_pat = pat.upper()
+                f = lambda x: upper_pat in x.upper()
+        if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # GH#59561
+            warnings.warn(
+                "Allowing a non-bool 'na' in obj.str.contains is deprecated "
+                "and will raise in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return self._str_map(f, na, dtype=np.dtype("bool"))
+
+    def _str_startswith(self, pat, na=lib.no_default):
+        f = lambda x: x.startswith(pat)
+        if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # GH#59561
+            warnings.warn(
+                "Allowing a non-bool 'na' in obj.str.startswith is deprecated "
+                "and will raise in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return self._str_map(f, na_value=na, dtype=np.dtype(bool))
+
+    def _str_endswith(self, pat, na=lib.no_default):
+        f = lambda x: x.endswith(pat)
+        if na is not lib.no_default and not isna(na) and not isinstance(na, bool):
+            # GH#59561
+            warnings.warn(
+                "Allowing a non-bool 'na' in obj.str.endswith is deprecated "
+                "and will raise in a future version.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return self._str_map(f, na_value=na, dtype=np.dtype(bool))
+
+    def _str_replace(
+        self,
+        pat: str | re.Pattern,
+        repl: str | Callable,
+        n: int = -1,
+        case: bool = True,
+        flags: int = 0,
+        regex: bool = True,
+    ):
+        if case is False:
+            # add case flag, if provided
+            flags |= re.IGNORECASE
+
+        if regex or flags or callable(repl):
+            if not isinstance(pat, re.Pattern):
+                if regex is False:
+                    pat = re.escape(pat)
+                pat = re.compile(pat, flags=flags)
+
+            n = n if n >= 0 else 0
+            f = lambda x: pat.sub(repl=repl, string=x, count=n)
+        else:
+            f = lambda x: x.replace(pat, repl, n)
+
+        return self._str_map(f, dtype=str)
+
+    def _str_repeat(self, repeats: int | Sequence[int]):
+        if lib.is_integer(repeats):
+            rint = cast(int, repeats)
+
+            def scalar_rep(x):
+                try:
+                    return bytes.__mul__(x, rint)
+                except TypeError:
+                    return str.__mul__(x, rint)
+
+            return self._str_map(scalar_rep, dtype=str)
+        else:
+            from pandas.core.arrays.string_ import BaseStringArray
+
+            def rep(x, r):
+                if x is libmissing.NA:
+                    return x
+                try:
+                    return bytes.__mul__(x, r)
+                except TypeError:
+                    return str.__mul__(x, r)
+
+            result = libops.vec_binop(
+                np.asarray(self),
+                np.asarray(repeats, dtype=object),
+                rep,
+            )
+            if isinstance(self, BaseStringArray):
+                # Not going through map, so we have to do this here.
+                result = type(self)._from_sequence(result, dtype=self.dtype)
+            return result
+
+    def _str_match(
+        self,
+        pat: str | re.Pattern,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if not case:
+            flags |= re.IGNORECASE
+
+        regex = re.compile(pat, flags=flags)
+
+        f = lambda x: regex.match(x) is not None
+        return self._str_map(f, na_value=na, dtype=np.dtype(bool))
+
+    def _str_fullmatch(
+        self,
+        pat: str | re.Pattern,
+        case: bool = True,
+        flags: int = 0,
+        na: Scalar | lib.NoDefault = lib.no_default,
+    ):
+        if not case:
+            flags |= re.IGNORECASE
+
+        regex = re.compile(pat, flags=flags)
+
+        f = lambda x: regex.fullmatch(x) is not None
+        return self._str_map(f, na_value=na, dtype=np.dtype(bool))
+
+    def _str_encode(self, encoding, errors: str = "strict"):
+        f = lambda x: x.encode(encoding, errors=errors)
+        return self._str_map(f, dtype=object)
+
+    def _str_find(self, sub, start: int = 0, end=None):
+        return self._str_find_(sub, start, end, side="left")
+
+    def _str_rfind(self, sub, start: int = 0, end=None):
+        return self._str_find_(sub, start, end, side="right")
+
+    def _str_find_(self, sub, start, end, side):
+        if side == "left":
+            method = "find"
+        elif side == "right":
+            method = "rfind"
+        else:  # pragma: no cover
+            raise ValueError("Invalid side")
+
+        if end is None:
+            f = lambda x: getattr(x, method)(sub, start)
+        else:
+            f = lambda x: getattr(x, method)(sub, start, end)
+        return self._str_map(f, dtype="int64")
+
+    def _str_findall(self, pat, flags: int = 0):
+        regex = re.compile(pat, flags=flags)
+        return self._str_map(regex.findall, dtype="object")
+
+    def _str_get(self, i):
+        def f(x):
+            if isinstance(x, dict):
+                return x.get(i)
+            elif len(x) > i >= -len(x):
+                return x[i]
+            return self.dtype.na_value  # type: ignore[attr-defined]
+
+        return self._str_map(f)
+
+    def _str_index(self, sub, start: int = 0, end=None):
+        if end:
+            f = lambda x: x.index(sub, start, end)
+        else:
+            f = lambda x: x.index(sub, start, end)
+        return self._str_map(f, dtype="int64")
+
+    def _str_rindex(self, sub, start: int = 0, end=None):
+        if end:
+            f = lambda x: x.rindex(sub, start, end)
+        else:
+            f = lambda x: x.rindex(sub, start, end)
+        return self._str_map(f, dtype="int64")
+
+    def _str_join(self, sep: str):
+        return self._str_map(sep.join)
+
+    def _str_partition(self, sep: str, expand):
+        result = self._str_map(lambda x: x.partition(sep), dtype="object")
+        return result
+
+    def _str_rpartition(self, sep: str, expand):
+        return self._str_map(lambda x: x.rpartition(sep), dtype="object")
+
+    def _str_len(self):
+        return self._str_map(len, dtype="int64")
+
+    def _str_slice(self, start=None, stop=None, step=None):
+        obj = slice(start, stop, step)
+        return self._str_map(lambda x: x[obj])
+
+    def _str_slice_replace(self, start=None, stop=None, repl=None):
+        if repl is None:
+            repl = ""
+
+        def f(x):
+            if x[start:stop] == "":
+                local_stop = start
+            else:
+                local_stop = stop
+            y = ""
+            if start is not None:
+                y += x[:start]
+            y += repl
+            if stop is not None:
+                y += x[local_stop:]
+            return y
+
+        return self._str_map(f)
+
+    def _str_split(
+        self,
+        pat: str | re.Pattern | None = None,
+        n=-1,
+        expand: bool = False,
+        regex: bool | None = None,
+    ):
+        if pat is None:
+            if n is None or n == 0:
+                n = -1
+            f = lambda x: x.split(pat, n)
+        else:
+            new_pat: str | re.Pattern
+            if regex is True or isinstance(pat, re.Pattern):
+                new_pat = re.compile(pat)
+            elif regex is False:
+                new_pat = pat
+            # regex is None so link to old behavior #43563
+            else:
+                if len(pat) == 1:
+                    new_pat = pat
+                else:
+                    new_pat = re.compile(pat)
+
+            if isinstance(new_pat, re.Pattern):
+                if n is None or n == -1:
+                    n = 0
+                f = lambda x: new_pat.split(x, maxsplit=n)
+            else:
+                if n is None or n == 0:
+                    n = -1
+                f = lambda x: x.split(pat, n)
+        return self._str_map(f, dtype=object)
+
+    def _str_rsplit(self, pat=None, n=-1):
+        if n is None or n == 0:
+            n = -1
+        f = lambda x: x.rsplit(pat, n)
+        return self._str_map(f, dtype="object")
+
+    def _str_translate(self, table):
+        return self._str_map(lambda x: x.translate(table))
+
+    def _str_wrap(self, width: int, **kwargs):
+        kwargs["width"] = width
+        tw = textwrap.TextWrapper(**kwargs)
+        return self._str_map(lambda s: "\n".join(tw.wrap(s)))
+
+    def _str_get_dummies(self, sep: str = "|"):
+        from pandas import Series
+
+        arr = Series(self).fillna("")
+        try:
+            arr = sep + arr + sep
+        except (TypeError, NotImplementedError):
+            arr = sep + arr.astype(str) + sep
+
+        tags: set[str] = set()
+        for ts in Series(arr, copy=False).str.split(sep):
+            tags.update(ts)
+        tags2 = sorted(tags - {""})
+
+        dummies = np.empty((len(arr), len(tags2)), dtype=np.int64)
+
+        def _isin(test_elements: str, element: str) -> bool:
+            return element in test_elements
+
+        for i, t in enumerate(tags2):
+            pat = sep + t + sep
+            dummies[:, i] = lib.map_infer(
+                arr.to_numpy(), functools.partial(_isin, element=pat)
+            )
+        return dummies, tags2
+
+    def _str_upper(self):
+        return self._str_map(lambda x: x.upper())
+
+    def _str_isalnum(self):
+        return self._str_map(str.isalnum, dtype="bool")
+
+    def _str_isalpha(self):
+        return self._str_map(str.isalpha, dtype="bool")
+
+    def _str_isdecimal(self):
+        return self._str_map(str.isdecimal, dtype="bool")
+
+    def _str_isdigit(self):
+        return self._str_map(str.isdigit, dtype="bool")
+
+    def _str_islower(self):
+        return self._str_map(str.islower, dtype="bool")
+
+    def _str_isnumeric(self):
+        return self._str_map(str.isnumeric, dtype="bool")
+
+    def _str_isspace(self):
+        return self._str_map(str.isspace, dtype="bool")
+
+    def _str_istitle(self):
+        return self._str_map(str.istitle, dtype="bool")
+
+    def _str_isupper(self):
+        return self._str_map(str.isupper, dtype="bool")
+
+    def _str_capitalize(self):
+        return self._str_map(str.capitalize)
+
+    def _str_casefold(self):
+        return self._str_map(str.casefold)
+
+    def _str_title(self):
+        return self._str_map(str.title)
+
+    def _str_swapcase(self):
+        return self._str_map(str.swapcase)
+
+    def _str_lower(self):
+        return self._str_map(str.lower)
+
+    def _str_normalize(self, form):
+        f = lambda x: unicodedata.normalize(form, x)
+        return self._str_map(f)
+
+    def _str_strip(self, to_strip=None):
+        return self._str_map(lambda x: x.strip(to_strip))
+
+    def _str_lstrip(self, to_strip=None):
+        return self._str_map(lambda x: x.lstrip(to_strip))
+
+    def _str_rstrip(self, to_strip=None):
+        return self._str_map(lambda x: x.rstrip(to_strip))
+
+    def _str_removeprefix(self, prefix: str) -> Series:
+        # outstanding question on whether to use native methods for users on Python 3.9+
+        # https://github.com/pandas-dev/pandas/pull/39226#issuecomment-836719770,
+        # in which case we could do return self._str_map(str.removeprefix)
+
+        def removeprefix(text: str) -> str:
+            if text.startswith(prefix):
+                return text[len(prefix) :]
+            return text
+
+        return self._str_map(removeprefix)
+
+    def _str_removesuffix(self, suffix: str) -> Series:
+        return self._str_map(lambda x: x.removesuffix(suffix))
+
+    def _str_extract(self, pat: str, flags: int = 0, expand: bool = True):
+        regex = re.compile(pat, flags=flags)
+        na_value = self.dtype.na_value  # type: ignore[attr-defined]
+
+        if not expand:
+
+            def g(x):
+                m = regex.search(x)
+                return m.groups()[0] if m else na_value
+
+            return self._str_map(g, convert=False)
+
+        empty_row = [na_value] * regex.groups
+
+        def f(x):
+            if not isinstance(x, str):
+                return empty_row
+            m = regex.search(x)
+            if m:
+                return [na_value if item is None else item for item in m.groups()]
+            else:
+                return empty_row
+
+        return [f(val) for val in np.asarray(self)]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/tools/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/tools/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/tools/datetimes.py b/.venv/lib/python3.13/site-packages/pandas/core/tools/datetimes.py
new file mode 100644
index 0000000000000000000000000000000000000000..8f700cfa631327fb09b1d6d50f86eefb212f3f87
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/tools/datetimes.py
@@ -0,0 +1,1240 @@
+from __future__ import annotations
+
+from collections import abc
+from datetime import date
+from functools import partial
+from itertools import islice
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    TypedDict,
+    Union,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import (
+    lib,
+    tslib,
+)
+from pandas._libs.tslibs import (
+    OutOfBoundsDatetime,
+    Timedelta,
+    Timestamp,
+    astype_overflowsafe,
+    is_supported_dtype,
+    timezones as libtimezones,
+)
+from pandas._libs.tslibs.conversion import cast_from_unit_vectorized
+from pandas._libs.tslibs.parsing import (
+    DateParseError,
+    guess_datetime_format,
+)
+from pandas._libs.tslibs.strptime import array_strptime
+from pandas._typing import (
+    AnyArrayLike,
+    ArrayLike,
+    DateTimeErrorChoices,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_float,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_numeric_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    ArrowDtype,
+    DatetimeTZDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+from pandas.arrays import (
+    DatetimeArray,
+    IntegerArray,
+    NumpyExtensionArray,
+)
+from pandas.core.algorithms import unique
+from pandas.core.arrays import ArrowExtensionArray
+from pandas.core.arrays.base import ExtensionArray
+from pandas.core.arrays.datetimes import (
+    maybe_convert_dtype,
+    objects_to_datetime64,
+    tz_to_dtype,
+)
+from pandas.core.construction import extract_array
+from pandas.core.indexes.base import Index
+from pandas.core.indexes.datetimes import DatetimeIndex
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._libs.tslibs.nattype import NaTType
+    from pandas._libs.tslibs.timedeltas import UnitChoices
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+# ---------------------------------------------------------------------
+# types used in annotations
+
+ArrayConvertible = Union[list, tuple, AnyArrayLike]
+Scalar = Union[float, str]
+DatetimeScalar = Union[Scalar, date, np.datetime64]
+
+DatetimeScalarOrArrayConvertible = Union[DatetimeScalar, ArrayConvertible]
+
+DatetimeDictArg = Union[list[Scalar], tuple[Scalar, ...], AnyArrayLike]
+
+
+class YearMonthDayDict(TypedDict, total=True):
+    year: DatetimeDictArg
+    month: DatetimeDictArg
+    day: DatetimeDictArg
+
+
+class FulldatetimeDict(YearMonthDayDict, total=False):
+    hour: DatetimeDictArg
+    hours: DatetimeDictArg
+    minute: DatetimeDictArg
+    minutes: DatetimeDictArg
+    second: DatetimeDictArg
+    seconds: DatetimeDictArg
+    ms: DatetimeDictArg
+    us: DatetimeDictArg
+    ns: DatetimeDictArg
+
+
+DictConvertible = Union[FulldatetimeDict, "DataFrame"]
+start_caching_at = 50
+
+
+# ---------------------------------------------------------------------
+
+
+def _guess_datetime_format_for_array(arr, dayfirst: bool | None = False) -> str | None:
+    # Try to guess the format based on the first non-NaN element, return None if can't
+    if (first_non_null := tslib.first_non_null(arr)) != -1:
+        if type(first_non_nan_element := arr[first_non_null]) is str:  # noqa: E721
+            # GH#32264 np.str_ object
+            guessed_format = guess_datetime_format(
+                first_non_nan_element, dayfirst=dayfirst
+            )
+            if guessed_format is not None:
+                return guessed_format
+            # If there are multiple non-null elements, warn about
+            # how parsing might not be consistent
+            if tslib.first_non_null(arr[first_non_null + 1 :]) != -1:
+                warnings.warn(
+                    "Could not infer format, so each element will be parsed "
+                    "individually, falling back to `dateutil`. To ensure parsing is "
+                    "consistent and as-expected, please specify a format.",
+                    UserWarning,
+                    stacklevel=find_stack_level(),
+                )
+    return None
+
+
+def should_cache(
+    arg: ArrayConvertible, unique_share: float = 0.7, check_count: int | None = None
+) -> bool:
+    """
+    Decides whether to do caching.
+
+    If the percent of unique elements among `check_count` elements less
+    than `unique_share * 100` then we can do caching.
+
+    Parameters
+    ----------
+    arg: listlike, tuple, 1-d array, Series
+    unique_share: float, default=0.7, optional
+        0 < unique_share < 1
+    check_count: int, optional
+        0 <= check_count <= len(arg)
+
+    Returns
+    -------
+    do_caching: bool
+
+    Notes
+    -----
+    By default for a sequence of less than 50 items in size, we don't do
+    caching; for the number of elements less than 5000, we take ten percent of
+    all elements to check for a uniqueness share; if the sequence size is more
+    than 5000, then we check only the first 500 elements.
+    All constants were chosen empirically by.
+    """
+    do_caching = True
+
+    # default realization
+    if check_count is None:
+        # in this case, the gain from caching is negligible
+        if len(arg) <= start_caching_at:
+            return False
+
+        if len(arg) <= 5000:
+            check_count = len(arg) // 10
+        else:
+            check_count = 500
+    else:
+        assert (
+            0 <= check_count <= len(arg)
+        ), "check_count must be in next bounds: [0; len(arg)]"
+        if check_count == 0:
+            return False
+
+    assert 0 < unique_share < 1, "unique_share must be in next bounds: (0; 1)"
+
+    try:
+        # We can't cache if the items are not hashable.
+        unique_elements = set(islice(arg, check_count))
+    except TypeError:
+        return False
+    if len(unique_elements) > check_count * unique_share:
+        do_caching = False
+    return do_caching
+
+
+def _maybe_cache(
+    arg: ArrayConvertible,
+    format: str | None,
+    cache: bool,
+    convert_listlike: Callable,
+) -> Series:
+    """
+    Create a cache of unique dates from an array of dates
+
+    Parameters
+    ----------
+    arg : listlike, tuple, 1-d array, Series
+    format : string
+        Strftime format to parse time
+    cache : bool
+        True attempts to create a cache of converted values
+    convert_listlike : function
+        Conversion function to apply on dates
+
+    Returns
+    -------
+    cache_array : Series
+        Cache of converted, unique dates. Can be empty
+    """
+    from pandas import Series
+
+    cache_array = Series(dtype=object)
+
+    if cache:
+        # Perform a quicker unique check
+        if not should_cache(arg):
+            return cache_array
+
+        if not isinstance(arg, (np.ndarray, ExtensionArray, Index, ABCSeries)):
+            arg = np.array(arg)
+
+        unique_dates = unique(arg)
+        if len(unique_dates) < len(arg):
+            cache_dates = convert_listlike(unique_dates, format)
+            # GH#45319
+            try:
+                cache_array = Series(cache_dates, index=unique_dates, copy=False)
+            except OutOfBoundsDatetime:
+                return cache_array
+            # GH#39882 and GH#35888 in case of None and NaT we get duplicates
+            if not cache_array.index.is_unique:
+                cache_array = cache_array[~cache_array.index.duplicated()]
+    return cache_array
+
+
+def _box_as_indexlike(
+    dt_array: ArrayLike, utc: bool = False, name: Hashable | None = None
+) -> Index:
+    """
+    Properly boxes the ndarray of datetimes to DatetimeIndex
+    if it is possible or to generic Index instead
+
+    Parameters
+    ----------
+    dt_array: 1-d array
+        Array of datetimes to be wrapped in an Index.
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
+    name : string, default None
+        Name for a resulting index
+
+    Returns
+    -------
+    result : datetime of converted dates
+        - DatetimeIndex if convertible to sole datetime64 type
+        - general Index otherwise
+    """
+
+    if lib.is_np_dtype(dt_array.dtype, "M"):
+        tz = "utc" if utc else None
+        return DatetimeIndex(dt_array, tz=tz, name=name)
+    return Index(dt_array, name=name, dtype=dt_array.dtype)
+
+
+def _convert_and_box_cache(
+    arg: DatetimeScalarOrArrayConvertible,
+    cache_array: Series,
+    name: Hashable | None = None,
+) -> Index:
+    """
+    Convert array of dates with a cache and wrap the result in an Index.
+
+    Parameters
+    ----------
+    arg : integer, float, string, datetime, list, tuple, 1-d array, Series
+    cache_array : Series
+        Cache of converted, unique dates
+    name : string, default None
+        Name for a DatetimeIndex
+
+    Returns
+    -------
+    result : Index-like of converted dates
+    """
+    from pandas import Series
+
+    result = Series(arg, dtype=cache_array.index.dtype).map(cache_array)
+    return _box_as_indexlike(result._values, utc=False, name=name)
+
+
+def _convert_listlike_datetimes(
+    arg,
+    format: str | None,
+    name: Hashable | None = None,
+    utc: bool = False,
+    unit: str | None = None,
+    errors: DateTimeErrorChoices = "raise",
+    dayfirst: bool | None = None,
+    yearfirst: bool | None = None,
+    exact: bool = True,
+):
+    """
+    Helper function for to_datetime. Performs the conversions of 1D listlike
+    of dates
+
+    Parameters
+    ----------
+    arg : list, tuple, ndarray, Series, Index
+        date to be parsed
+    name : object
+        None or string for the Index name
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
+    unit : str
+        None or string of the frequency of the passed data
+    errors : str
+        error handing behaviors from to_datetime, 'raise', 'coerce', 'ignore'
+    dayfirst : bool
+        dayfirst parsing behavior from to_datetime
+    yearfirst : bool
+        yearfirst parsing behavior from to_datetime
+    exact : bool, default True
+        exact format matching behavior from to_datetime
+
+    Returns
+    -------
+    Index-like of parsed dates
+    """
+    if isinstance(arg, (list, tuple)):
+        arg = np.array(arg, dtype="O")
+    elif isinstance(arg, NumpyExtensionArray):
+        arg = np.array(arg)
+
+    arg_dtype = getattr(arg, "dtype", None)
+    # these are shortcutable
+    tz = "utc" if utc else None
+    if isinstance(arg_dtype, DatetimeTZDtype):
+        if not isinstance(arg, (DatetimeArray, DatetimeIndex)):
+            return DatetimeIndex(arg, tz=tz, name=name)
+        if utc:
+            arg = arg.tz_convert(None).tz_localize("utc")
+        return arg
+
+    elif isinstance(arg_dtype, ArrowDtype) and arg_dtype.type is Timestamp:
+        # TODO: Combine with above if DTI/DTA supports Arrow timestamps
+        if utc:
+            # pyarrow uses UTC, not lowercase utc
+            if isinstance(arg, Index):
+                arg_array = cast(ArrowExtensionArray, arg.array)
+                if arg_dtype.pyarrow_dtype.tz is not None:
+                    arg_array = arg_array._dt_tz_convert("UTC")
+                else:
+                    arg_array = arg_array._dt_tz_localize("UTC")
+                arg = Index(arg_array)
+            else:
+                # ArrowExtensionArray
+                if arg_dtype.pyarrow_dtype.tz is not None:
+                    arg = arg._dt_tz_convert("UTC")
+                else:
+                    arg = arg._dt_tz_localize("UTC")
+        return arg
+
+    elif lib.is_np_dtype(arg_dtype, "M"):
+        if not is_supported_dtype(arg_dtype):
+            # We go to closest supported reso, i.e. "s"
+            arg = astype_overflowsafe(
+                # TODO: looks like we incorrectly raise with errors=="ignore"
+                np.asarray(arg),
+                np.dtype("M8[s]"),
+                is_coerce=errors == "coerce",
+            )
+
+        if not isinstance(arg, (DatetimeArray, DatetimeIndex)):
+            return DatetimeIndex(arg, tz=tz, name=name)
+        elif utc:
+            # DatetimeArray, DatetimeIndex
+            return arg.tz_localize("utc")
+
+        return arg
+
+    elif unit is not None:
+        if format is not None:
+            raise ValueError("cannot specify both format and unit")
+        return _to_datetime_with_unit(arg, unit, name, utc, errors)
+    elif getattr(arg, "ndim", 1) > 1:
+        raise TypeError(
+            "arg must be a string, datetime, list, tuple, 1-d array, or Series"
+        )
+
+    # warn if passing timedelta64, raise for PeriodDtype
+    # NB: this must come after unit transformation
+    try:
+        arg, _ = maybe_convert_dtype(arg, copy=False, tz=libtimezones.maybe_get_tz(tz))
+    except TypeError:
+        if errors == "coerce":
+            npvalues = np.array(["NaT"], dtype="datetime64[ns]").repeat(len(arg))
+            return DatetimeIndex(npvalues, name=name)
+        elif errors == "ignore":
+            idx = Index(arg, name=name)
+            return idx
+        raise
+
+    arg = ensure_object(arg)
+
+    if format is None:
+        format = _guess_datetime_format_for_array(arg, dayfirst=dayfirst)
+
+    # `format` could be inferred, or user didn't ask for mixed-format parsing.
+    if format is not None and format != "mixed":
+        return _array_strptime_with_fallback(arg, name, utc, format, exact, errors)
+
+    result, tz_parsed = objects_to_datetime64(
+        arg,
+        dayfirst=dayfirst,
+        yearfirst=yearfirst,
+        utc=utc,
+        errors=errors,
+        allow_object=True,
+    )
+
+    if tz_parsed is not None:
+        # We can take a shortcut since the datetime64 numpy array
+        # is in UTC
+        out_unit = np.datetime_data(result.dtype)[0]
+        dtype = cast(DatetimeTZDtype, tz_to_dtype(tz_parsed, out_unit))
+        dt64_values = result.view(f"M8[{dtype.unit}]")
+        dta = DatetimeArray._simple_new(dt64_values, dtype=dtype)
+        return DatetimeIndex._simple_new(dta, name=name)
+
+    return _box_as_indexlike(result, utc=utc, name=name)
+
+
+def _array_strptime_with_fallback(
+    arg,
+    name,
+    utc: bool,
+    fmt: str,
+    exact: bool,
+    errors: str,
+) -> Index:
+    """
+    Call array_strptime, with fallback behavior depending on 'errors'.
+    """
+    result, tz_out = array_strptime(arg, fmt, exact=exact, errors=errors, utc=utc)
+    if tz_out is not None:
+        unit = np.datetime_data(result.dtype)[0]
+        dtype = DatetimeTZDtype(tz=tz_out, unit=unit)
+        dta = DatetimeArray._simple_new(result, dtype=dtype)
+        if utc:
+            dta = dta.tz_convert("UTC")
+        return Index(dta, name=name)
+    elif result.dtype != object and utc:
+        unit = np.datetime_data(result.dtype)[0]
+        res = Index(result, dtype=f"M8[{unit}, UTC]", name=name)
+        return res
+    elif using_string_dtype() and result.dtype == object:
+        if lib.is_string_array(result):
+            return Index(result, dtype="str", name=name)
+    return Index(result, dtype=result.dtype, name=name)
+
+
+def _to_datetime_with_unit(arg, unit, name, utc: bool, errors: str) -> Index:
+    """
+    to_datetime specalized to the case where a 'unit' is passed.
+    """
+    arg = extract_array(arg, extract_numpy=True)
+
+    # GH#30050 pass an ndarray to tslib.array_with_unit_to_datetime
+    # because it expects an ndarray argument
+    if isinstance(arg, IntegerArray):
+        arr = arg.astype(f"datetime64[{unit}]")
+        tz_parsed = None
+    else:
+        arg = np.asarray(arg)
+
+        if arg.dtype.kind in "iu":
+            # Note we can't do "f" here because that could induce unwanted
+            #  rounding GH#14156, GH#20445
+            arr = arg.astype(f"datetime64[{unit}]", copy=False)
+            try:
+                arr = astype_overflowsafe(arr, np.dtype("M8[ns]"), copy=False)
+            except OutOfBoundsDatetime:
+                if errors == "raise":
+                    raise
+                arg = arg.astype(object)
+                return _to_datetime_with_unit(arg, unit, name, utc, errors)
+            tz_parsed = None
+
+        elif arg.dtype.kind == "f":
+            with np.errstate(over="raise"):
+                try:
+                    arr = cast_from_unit_vectorized(arg, unit=unit)
+                except OutOfBoundsDatetime:
+                    if errors != "raise":
+                        return _to_datetime_with_unit(
+                            arg.astype(object), unit, name, utc, errors
+                        )
+                    raise OutOfBoundsDatetime(
+                        f"cannot convert input with unit '{unit}'"
+                    )
+
+            arr = arr.view("M8[ns]")
+            tz_parsed = None
+        else:
+            arg = arg.astype(object, copy=False)
+            arr, tz_parsed = tslib.array_with_unit_to_datetime(arg, unit, errors=errors)
+
+    if errors == "ignore":
+        # Index constructor _may_ infer to DatetimeIndex
+        result = Index._with_infer(arr, name=name)
+    else:
+        result = DatetimeIndex(arr, name=name)
+
+    if not isinstance(result, DatetimeIndex):
+        return result
+
+    # GH#23758: We may still need to localize the result with tz
+    # GH#25546: Apply tz_parsed first (from arg), then tz (from caller)
+    # result will be naive but in UTC
+    result = result.tz_localize("UTC").tz_convert(tz_parsed)
+
+    if utc:
+        if result.tz is None:
+            result = result.tz_localize("utc")
+        else:
+            result = result.tz_convert("utc")
+    return result
+
+
+def _adjust_to_origin(arg, origin, unit):
+    """
+    Helper function for to_datetime.
+    Adjust input argument to the specified origin
+
+    Parameters
+    ----------
+    arg : list, tuple, ndarray, Series, Index
+        date to be adjusted
+    origin : 'julian' or Timestamp
+        origin offset for the arg
+    unit : str
+        passed unit from to_datetime, must be 'D'
+
+    Returns
+    -------
+    ndarray or scalar of adjusted date(s)
+    """
+    if origin == "julian":
+        original = arg
+        j0 = Timestamp(0).to_julian_date()
+        if unit != "D":
+            raise ValueError("unit must be 'D' for origin='julian'")
+        try:
+            arg = arg - j0
+        except TypeError as err:
+            raise ValueError(
+                "incompatible 'arg' type for given 'origin'='julian'"
+            ) from err
+
+        # preemptively check this for a nice range
+        j_max = Timestamp.max.to_julian_date() - j0
+        j_min = Timestamp.min.to_julian_date() - j0
+        if np.any(arg > j_max) or np.any(arg < j_min):
+            raise OutOfBoundsDatetime(
+                f"{original} is Out of Bounds for origin='julian'"
+            )
+    else:
+        # arg must be numeric
+        if not (
+            (is_integer(arg) or is_float(arg)) or is_numeric_dtype(np.asarray(arg))
+        ):
+            raise ValueError(
+                f"'{arg}' is not compatible with origin='{origin}'; "
+                "it must be numeric with a unit specified"
+            )
+
+        # we are going to offset back to unix / epoch time
+        try:
+            offset = Timestamp(origin, unit=unit)
+        except OutOfBoundsDatetime as err:
+            raise OutOfBoundsDatetime(f"origin {origin} is Out of Bounds") from err
+        except ValueError as err:
+            raise ValueError(
+                f"origin {origin} cannot be converted to a Timestamp"
+            ) from err
+
+        if offset.tz is not None:
+            raise ValueError(f"origin offset {offset} must be tz-naive")
+        td_offset = offset - Timestamp(0)
+
+        # convert the offset to the unit of the arg
+        # this should be lossless in terms of precision
+        ioffset = td_offset // Timedelta(1, unit=unit)
+
+        # scalars & ndarray-like can handle the addition
+        if is_list_like(arg) and not isinstance(arg, (ABCSeries, Index, np.ndarray)):
+            arg = np.asarray(arg)
+        arg = arg + ioffset
+    return arg
+
+
+@overload
+def to_datetime(
+    arg: DatetimeScalar,
+    errors: DateTimeErrorChoices = ...,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    utc: bool = ...,
+    format: str | None = ...,
+    exact: bool = ...,
+    unit: str | None = ...,
+    infer_datetime_format: bool = ...,
+    origin=...,
+    cache: bool = ...,
+) -> Timestamp:
+    ...
+
+
+@overload
+def to_datetime(
+    arg: Series | DictConvertible,
+    errors: DateTimeErrorChoices = ...,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    utc: bool = ...,
+    format: str | None = ...,
+    exact: bool = ...,
+    unit: str | None = ...,
+    infer_datetime_format: bool = ...,
+    origin=...,
+    cache: bool = ...,
+) -> Series:
+    ...
+
+
+@overload
+def to_datetime(
+    arg: list | tuple | Index | ArrayLike,
+    errors: DateTimeErrorChoices = ...,
+    dayfirst: bool = ...,
+    yearfirst: bool = ...,
+    utc: bool = ...,
+    format: str | None = ...,
+    exact: bool = ...,
+    unit: str | None = ...,
+    infer_datetime_format: bool = ...,
+    origin=...,
+    cache: bool = ...,
+) -> DatetimeIndex:
+    ...
+
+
+def to_datetime(
+    arg: DatetimeScalarOrArrayConvertible | DictConvertible,
+    errors: DateTimeErrorChoices = "raise",
+    dayfirst: bool = False,
+    yearfirst: bool = False,
+    utc: bool = False,
+    format: str | None = None,
+    exact: bool | lib.NoDefault = lib.no_default,
+    unit: str | None = None,
+    infer_datetime_format: lib.NoDefault | bool = lib.no_default,
+    origin: str = "unix",
+    cache: bool = True,
+) -> DatetimeIndex | Series | DatetimeScalar | NaTType | None:
+    """
+    Convert argument to datetime.
+
+    This function converts a scalar, array-like, :class:`Series` or
+    :class:`DataFrame`/dict-like to a pandas datetime object.
+
+    Parameters
+    ----------
+    arg : int, float, str, datetime, list, tuple, 1-d array, Series, DataFrame/dict-like
+        The object to convert to a datetime. If a :class:`DataFrame` is provided, the
+        method expects minimally the following columns: :const:`"year"`,
+        :const:`"month"`, :const:`"day"`. The column "year"
+        must be specified in 4-digit format.
+    errors : {'ignore', 'raise', 'coerce'}, default 'raise'
+        - If :const:`'raise'`, then invalid parsing will raise an exception.
+        - If :const:`'coerce'`, then invalid parsing will be set as :const:`NaT`.
+        - If :const:`'ignore'`, then invalid parsing will return the input.
+    dayfirst : bool, default False
+        Specify a date parse order if `arg` is str or is list-like.
+        If :const:`True`, parses dates with the day first, e.g. :const:`"10/11/12"`
+        is parsed as :const:`2012-11-10`.
+
+        .. warning::
+
+            ``dayfirst=True`` is not strict, but will prefer to parse
+            with day first.
+
+    yearfirst : bool, default False
+        Specify a date parse order if `arg` is str or is list-like.
+
+        - If :const:`True` parses dates with the year first, e.g.
+          :const:`"10/11/12"` is parsed as :const:`2010-11-12`.
+        - If both `dayfirst` and `yearfirst` are :const:`True`, `yearfirst` is
+          preceded (same as :mod:`dateutil`).
+
+        .. warning::
+
+            ``yearfirst=True`` is not strict, but will prefer to parse
+            with year first.
+
+    utc : bool, default False
+        Control timezone-related parsing, localization and conversion.
+
+        - If :const:`True`, the function *always* returns a timezone-aware
+          UTC-localized :class:`Timestamp`, :class:`Series` or
+          :class:`DatetimeIndex`. To do this, timezone-naive inputs are
+          *localized* as UTC, while timezone-aware inputs are *converted* to UTC.
+
+        - If :const:`False` (default), inputs will not be coerced to UTC.
+          Timezone-naive inputs will remain naive, while timezone-aware ones
+          will keep their time offsets. Limitations exist for mixed
+          offsets (typically, daylight savings), see :ref:`Examples
+          ` section for details.
+
+        .. warning::
+
+            In a future version of pandas, parsing datetimes with mixed time
+            zones will raise an error unless `utc=True`.
+            Please specify `utc=True` to opt in to the new behaviour
+            and silence this warning. To create a `Series` with mixed offsets and
+            `object` dtype, please use `apply` and `datetime.datetime.strptime`.
+
+        See also: pandas general documentation about `timezone conversion and
+        localization
+        `_.
+
+    format : str, default None
+        The strftime to parse time, e.g. :const:`"%d/%m/%Y"`. See
+        `strftime documentation
+        `_ for more information on choices, though
+        note that :const:`"%f"` will parse all the way up to nanoseconds.
+        You can also pass:
+
+        - "ISO8601", to parse any `ISO8601 `_
+          time string (not necessarily in exactly the same format);
+        - "mixed", to infer the format for each element individually. This is risky,
+          and you should probably use it along with `dayfirst`.
+
+        .. note::
+
+            If a :class:`DataFrame` is passed, then `format` has no effect.
+
+    exact : bool, default True
+        Control how `format` is used:
+
+        - If :const:`True`, require an exact `format` match.
+        - If :const:`False`, allow the `format` to match anywhere in the target
+          string.
+
+        Cannot be used alongside ``format='ISO8601'`` or ``format='mixed'``.
+    unit : str, default 'ns'
+        The unit of the arg (D,s,ms,us,ns) denote the unit, which is an
+        integer or float number. This will be based off the origin.
+        Example, with ``unit='ms'`` and ``origin='unix'``, this would calculate
+        the number of milliseconds to the unix epoch start.
+    infer_datetime_format : bool, default False
+        If :const:`True` and no `format` is given, attempt to infer the format
+        of the datetime strings based on the first non-NaN element,
+        and if it can be inferred, switch to a faster method of parsing them.
+        In some cases this can increase the parsing speed by ~5-10x.
+
+        .. deprecated:: 2.0.0
+            A strict version of this argument is now the default, passing it has
+            no effect.
+
+    origin : scalar, default 'unix'
+        Define the reference date. The numeric values would be parsed as number
+        of units (defined by `unit`) since this reference date.
+
+        - If :const:`'unix'` (or POSIX) time; origin is set to 1970-01-01.
+        - If :const:`'julian'`, unit must be :const:`'D'`, and origin is set to
+          beginning of Julian Calendar. Julian day number :const:`0` is assigned
+          to the day starting at noon on January 1, 4713 BC.
+        - If Timestamp convertible (Timestamp, dt.datetime, np.datetimt64 or date
+          string), origin is set to Timestamp identified by origin.
+        - If a float or integer, origin is the difference
+          (in units determined by the ``unit`` argument) relative to 1970-01-01.
+    cache : bool, default True
+        If :const:`True`, use a cache of unique, converted dates to apply the
+        datetime conversion. May produce significant speed-up when parsing
+        duplicate date strings, especially ones with timezone offsets. The cache
+        is only used when there are at least 50 values. The presence of
+        out-of-bounds values will render the cache unusable and may slow down
+        parsing.
+
+    Returns
+    -------
+    datetime
+        If parsing succeeded.
+        Return type depends on input (types in parenthesis correspond to
+        fallback in case of unsuccessful timezone or out-of-range timestamp
+        parsing):
+
+        - scalar: :class:`Timestamp` (or :class:`datetime.datetime`)
+        - array-like: :class:`DatetimeIndex` (or :class:`Series` with
+          :class:`object` dtype containing :class:`datetime.datetime`)
+        - Series: :class:`Series` of :class:`datetime64` dtype (or
+          :class:`Series` of :class:`object` dtype containing
+          :class:`datetime.datetime`)
+        - DataFrame: :class:`Series` of :class:`datetime64` dtype (or
+          :class:`Series` of :class:`object` dtype containing
+          :class:`datetime.datetime`)
+
+    Raises
+    ------
+    ParserError
+        When parsing a date from string fails.
+    ValueError
+        When another datetime conversion error happens. For example when one
+        of 'year', 'month', day' columns is missing in a :class:`DataFrame`, or
+        when a Timezone-aware :class:`datetime.datetime` is found in an array-like
+        of mixed time offsets, and ``utc=False``.
+
+    See Also
+    --------
+    DataFrame.astype : Cast argument to a specified dtype.
+    to_timedelta : Convert argument to timedelta.
+    convert_dtypes : Convert dtypes.
+
+    Notes
+    -----
+
+    Many input types are supported, and lead to different output types:
+
+    - **scalars** can be int, float, str, datetime object (from stdlib :mod:`datetime`
+      module or :mod:`numpy`). They are converted to :class:`Timestamp` when
+      possible, otherwise they are converted to :class:`datetime.datetime`.
+      None/NaN/null scalars are converted to :const:`NaT`.
+
+    - **array-like** can contain int, float, str, datetime objects. They are
+      converted to :class:`DatetimeIndex` when possible, otherwise they are
+      converted to :class:`Index` with :class:`object` dtype, containing
+      :class:`datetime.datetime`. None/NaN/null entries are converted to
+      :const:`NaT` in both cases.
+
+    - **Series** are converted to :class:`Series` with :class:`datetime64`
+      dtype when possible, otherwise they are converted to :class:`Series` with
+      :class:`object` dtype, containing :class:`datetime.datetime`. None/NaN/null
+      entries are converted to :const:`NaT` in both cases.
+
+    - **DataFrame/dict-like** are converted to :class:`Series` with
+      :class:`datetime64` dtype. For each row a datetime is created from assembling
+      the various dataframe columns. Column keys can be common abbreviations
+      like ['year', 'month', 'day', 'minute', 'second', 'ms', 'us', 'ns']) or
+      plurals of the same.
+
+    The following causes are responsible for :class:`datetime.datetime` objects
+    being returned (possibly inside an :class:`Index` or a :class:`Series` with
+    :class:`object` dtype) instead of a proper pandas designated type
+    (:class:`Timestamp`, :class:`DatetimeIndex` or :class:`Series`
+    with :class:`datetime64` dtype):
+
+    - when any input element is before :const:`Timestamp.min` or after
+      :const:`Timestamp.max`, see `timestamp limitations
+      `_.
+
+    - when ``utc=False`` (default) and the input is an array-like or
+      :class:`Series` containing mixed naive/aware datetime, or aware with mixed
+      time offsets. Note that this happens in the (quite frequent) situation when
+      the timezone has a daylight savings policy. In that case you may wish to
+      use ``utc=True``.
+
+    Examples
+    --------
+
+    **Handling various input formats**
+
+    Assembling a datetime from multiple columns of a :class:`DataFrame`. The keys
+    can be common abbreviations like ['year', 'month', 'day', 'minute', 'second',
+    'ms', 'us', 'ns']) or plurals of the same
+
+    >>> df = pd.DataFrame({'year': [2015, 2016],
+    ...                    'month': [2, 3],
+    ...                    'day': [4, 5]})
+    >>> pd.to_datetime(df)
+    0   2015-02-04
+    1   2016-03-05
+    dtype: datetime64[ns]
+
+    Using a unix epoch time
+
+    >>> pd.to_datetime(1490195805, unit='s')
+    Timestamp('2017-03-22 15:16:45')
+    >>> pd.to_datetime(1490195805433502912, unit='ns')
+    Timestamp('2017-03-22 15:16:45.433502912')
+
+    .. warning:: For float arg, precision rounding might happen. To prevent
+        unexpected behavior use a fixed-width exact type.
+
+    Using a non-unix epoch origin
+
+    >>> pd.to_datetime([1, 2, 3], unit='D',
+    ...                origin=pd.Timestamp('1960-01-01'))
+    DatetimeIndex(['1960-01-02', '1960-01-03', '1960-01-04'],
+                  dtype='datetime64[ns]', freq=None)
+
+    **Differences with strptime behavior**
+
+    :const:`"%f"` will parse all the way up to nanoseconds.
+
+    >>> pd.to_datetime('2018-10-26 12:00:00.0000000011',
+    ...                format='%Y-%m-%d %H:%M:%S.%f')
+    Timestamp('2018-10-26 12:00:00.000000001')
+
+    **Non-convertible date/times**
+
+    Passing ``errors='coerce'`` will force an out-of-bounds date to :const:`NaT`,
+    in addition to forcing non-dates (or non-parseable dates) to :const:`NaT`.
+
+    >>> pd.to_datetime('13000101', format='%Y%m%d', errors='coerce')
+    NaT
+
+    .. _to_datetime_tz_examples:
+
+    **Timezones and time offsets**
+
+    The default behaviour (``utc=False``) is as follows:
+
+    - Timezone-naive inputs are converted to timezone-naive :class:`DatetimeIndex`:
+
+    >>> pd.to_datetime(['2018-10-26 12:00:00', '2018-10-26 13:00:15'])
+    DatetimeIndex(['2018-10-26 12:00:00', '2018-10-26 13:00:15'],
+                  dtype='datetime64[ns]', freq=None)
+
+    - Timezone-aware inputs *with constant time offset* are converted to
+      timezone-aware :class:`DatetimeIndex`:
+
+    >>> pd.to_datetime(['2018-10-26 12:00 -0500', '2018-10-26 13:00 -0500'])
+    DatetimeIndex(['2018-10-26 12:00:00-05:00', '2018-10-26 13:00:00-05:00'],
+                  dtype='datetime64[ns, UTC-05:00]', freq=None)
+
+    - However, timezone-aware inputs *with mixed time offsets* (for example
+      issued from a timezone with daylight savings, such as Europe/Paris)
+      are **not successfully converted** to a :class:`DatetimeIndex`.
+      Parsing datetimes with mixed time zones will show a warning unless
+      `utc=True`. If you specify `utc=False` the warning below will be shown
+      and a simple :class:`Index` containing :class:`datetime.datetime`
+      objects will be returned:
+
+    >>> pd.to_datetime(['2020-10-25 02:00 +0200',
+    ...                 '2020-10-25 04:00 +0100'])  # doctest: +SKIP
+    FutureWarning: In a future version of pandas, parsing datetimes with mixed
+    time zones will raise an error unless `utc=True`. Please specify `utc=True`
+    to opt in to the new behaviour and silence this warning. To create a `Series`
+    with mixed offsets and `object` dtype, please use `apply` and
+    `datetime.datetime.strptime`.
+    Index([2020-10-25 02:00:00+02:00, 2020-10-25 04:00:00+01:00],
+          dtype='object')
+
+    - A mix of timezone-aware and timezone-naive inputs is also converted to
+      a simple :class:`Index` containing :class:`datetime.datetime` objects:
+
+    >>> from datetime import datetime
+    >>> pd.to_datetime(["2020-01-01 01:00:00-01:00",
+    ...                 datetime(2020, 1, 1, 3, 0)])  # doctest: +SKIP
+    FutureWarning: In a future version of pandas, parsing datetimes with mixed
+    time zones will raise an error unless `utc=True`. Please specify `utc=True`
+    to opt in to the new behaviour and silence this warning. To create a `Series`
+    with mixed offsets and `object` dtype, please use `apply` and
+    `datetime.datetime.strptime`.
+    Index([2020-01-01 01:00:00-01:00, 2020-01-01 03:00:00], dtype='object')
+
+    |
+
+    Setting ``utc=True`` solves most of the above issues:
+
+    - Timezone-naive inputs are *localized* as UTC
+
+    >>> pd.to_datetime(['2018-10-26 12:00', '2018-10-26 13:00'], utc=True)
+    DatetimeIndex(['2018-10-26 12:00:00+00:00', '2018-10-26 13:00:00+00:00'],
+                  dtype='datetime64[ns, UTC]', freq=None)
+
+    - Timezone-aware inputs are *converted* to UTC (the output represents the
+      exact same datetime, but viewed from the UTC time offset `+00:00`).
+
+    >>> pd.to_datetime(['2018-10-26 12:00 -0530', '2018-10-26 12:00 -0500'],
+    ...                utc=True)
+    DatetimeIndex(['2018-10-26 17:30:00+00:00', '2018-10-26 17:00:00+00:00'],
+                  dtype='datetime64[ns, UTC]', freq=None)
+
+    - Inputs can contain both string or datetime, the above
+      rules still apply
+
+    >>> pd.to_datetime(['2018-10-26 12:00', datetime(2020, 1, 1, 18)], utc=True)
+    DatetimeIndex(['2018-10-26 12:00:00+00:00', '2020-01-01 18:00:00+00:00'],
+                  dtype='datetime64[ns, UTC]', freq=None)
+    """
+    if exact is not lib.no_default and format in {"mixed", "ISO8601"}:
+        raise ValueError("Cannot use 'exact' when 'format' is 'mixed' or 'ISO8601'")
+    if infer_datetime_format is not lib.no_default:
+        warnings.warn(
+            "The argument 'infer_datetime_format' is deprecated and will "
+            "be removed in a future version. "
+            "A strict version of it is now the default, see "
+            "https://pandas.pydata.org/pdeps/0004-consistent-to-datetime-parsing.html. "
+            "You can safely remove this argument.",
+            stacklevel=find_stack_level(),
+        )
+    if errors == "ignore":
+        # GH#54467
+        warnings.warn(
+            "errors='ignore' is deprecated and will raise in a future version. "
+            "Use to_datetime without passing `errors` and catch exceptions "
+            "explicitly instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if arg is None:
+        return None
+
+    if origin != "unix":
+        arg = _adjust_to_origin(arg, origin, unit)
+
+    convert_listlike = partial(
+        _convert_listlike_datetimes,
+        utc=utc,
+        unit=unit,
+        dayfirst=dayfirst,
+        yearfirst=yearfirst,
+        errors=errors,
+        exact=exact,
+    )
+    # pylint: disable-next=used-before-assignment
+    result: Timestamp | NaTType | Series | Index
+
+    if isinstance(arg, Timestamp):
+        result = arg
+        if utc:
+            if arg.tz is not None:
+                result = arg.tz_convert("utc")
+            else:
+                result = arg.tz_localize("utc")
+    elif isinstance(arg, ABCSeries):
+        cache_array = _maybe_cache(arg, format, cache, convert_listlike)
+        if not cache_array.empty:
+            result = arg.map(cache_array)
+        else:
+            values = convert_listlike(arg._values, format)
+            result = arg._constructor(values, index=arg.index, name=arg.name)
+    elif isinstance(arg, (ABCDataFrame, abc.MutableMapping)):
+        result = _assemble_from_unit_mappings(arg, errors, utc)
+    elif isinstance(arg, Index):
+        cache_array = _maybe_cache(arg, format, cache, convert_listlike)
+        if not cache_array.empty:
+            result = _convert_and_box_cache(arg, cache_array, name=arg.name)
+        else:
+            result = convert_listlike(arg, format, name=arg.name)
+    elif is_list_like(arg):
+        try:
+            # error: Argument 1 to "_maybe_cache" has incompatible type
+            # "Union[float, str, datetime, List[Any], Tuple[Any, ...], ExtensionArray,
+            # ndarray[Any, Any], Series]"; expected "Union[List[Any], Tuple[Any, ...],
+            # Union[Union[ExtensionArray, ndarray[Any, Any]], Index, Series], Series]"
+            argc = cast(
+                Union[list, tuple, ExtensionArray, np.ndarray, "Series", Index], arg
+            )
+            cache_array = _maybe_cache(argc, format, cache, convert_listlike)
+        except OutOfBoundsDatetime:
+            # caching attempts to create a DatetimeIndex, which may raise
+            # an OOB. If that's the desired behavior, then just reraise...
+            if errors == "raise":
+                raise
+            # ... otherwise, continue without the cache.
+            from pandas import Series
+
+            cache_array = Series([], dtype=object)  # just an empty array
+        if not cache_array.empty:
+            result = _convert_and_box_cache(argc, cache_array)
+        else:
+            result = convert_listlike(argc, format)
+    else:
+        result = convert_listlike(np.array([arg]), format)[0]
+        if isinstance(arg, bool) and isinstance(result, np.bool_):
+            result = bool(result)  # TODO: avoid this kludge.
+
+    #  error: Incompatible return value type (got "Union[Timestamp, NaTType,
+    # Series, Index]", expected "Union[DatetimeIndex, Series, float, str,
+    # NaTType, None]")
+    return result  # type: ignore[return-value]
+
+
+# mappings for assembling units
+_unit_map = {
+    "year": "year",
+    "years": "year",
+    "month": "month",
+    "months": "month",
+    "day": "day",
+    "days": "day",
+    "hour": "h",
+    "hours": "h",
+    "minute": "m",
+    "minutes": "m",
+    "second": "s",
+    "seconds": "s",
+    "ms": "ms",
+    "millisecond": "ms",
+    "milliseconds": "ms",
+    "us": "us",
+    "microsecond": "us",
+    "microseconds": "us",
+    "ns": "ns",
+    "nanosecond": "ns",
+    "nanoseconds": "ns",
+}
+
+
+def _assemble_from_unit_mappings(arg, errors: DateTimeErrorChoices, utc: bool):
+    """
+    assemble the unit specified fields from the arg (DataFrame)
+    Return a Series for actual parsing
+
+    Parameters
+    ----------
+    arg : DataFrame
+    errors : {'ignore', 'raise', 'coerce'}, default 'raise'
+
+        - If :const:`'raise'`, then invalid parsing will raise an exception
+        - If :const:`'coerce'`, then invalid parsing will be set as :const:`NaT`
+        - If :const:`'ignore'`, then invalid parsing will return the input
+    utc : bool
+        Whether to convert/localize timestamps to UTC.
+
+    Returns
+    -------
+    Series
+    """
+    from pandas import (
+        DataFrame,
+        to_numeric,
+        to_timedelta,
+    )
+
+    arg = DataFrame(arg)
+    if not arg.columns.is_unique:
+        raise ValueError("cannot assemble with duplicate keys")
+
+    # replace passed unit with _unit_map
+    def f(value):
+        if value in _unit_map:
+            return _unit_map[value]
+
+        # m is case significant
+        if value.lower() in _unit_map:
+            return _unit_map[value.lower()]
+
+        return value
+
+    unit = {k: f(k) for k in arg.keys()}
+    unit_rev = {v: k for k, v in unit.items()}
+
+    # we require at least Ymd
+    required = ["year", "month", "day"]
+    req = sorted(set(required) - set(unit_rev.keys()))
+    if len(req):
+        _required = ",".join(req)
+        raise ValueError(
+            "to assemble mappings requires at least that "
+            f"[year, month, day] be specified: [{_required}] is missing"
+        )
+
+    # keys we don't recognize
+    excess = sorted(set(unit_rev.keys()) - set(_unit_map.values()))
+    if len(excess):
+        _excess = ",".join(excess)
+        raise ValueError(
+            f"extra keys have been passed to the datetime assemblage: [{_excess}]"
+        )
+
+    def coerce(values):
+        # we allow coercion to if errors allows
+        values = to_numeric(values, errors=errors)
+
+        # prevent overflow in case of int8 or int16
+        if is_integer_dtype(values.dtype):
+            values = values.astype("int64", copy=False)
+        return values
+
+    values = (
+        coerce(arg[unit_rev["year"]]) * 10000
+        + coerce(arg[unit_rev["month"]]) * 100
+        + coerce(arg[unit_rev["day"]])
+    )
+    try:
+        values = to_datetime(values, format="%Y%m%d", errors=errors, utc=utc)
+    except (TypeError, ValueError) as err:
+        raise ValueError(f"cannot assemble the datetimes: {err}") from err
+
+    units: list[UnitChoices] = ["h", "m", "s", "ms", "us", "ns"]
+    for u in units:
+        value = unit_rev.get(u)
+        if value is not None and value in arg:
+            try:
+                values += to_timedelta(coerce(arg[value]), unit=u, errors=errors)
+            except (TypeError, ValueError) as err:
+                raise ValueError(
+                    f"cannot assemble the datetimes [{value}]: {err}"
+                ) from err
+    return values
+
+
+__all__ = [
+    "DateParseError",
+    "should_cache",
+    "to_datetime",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/tools/numeric.py b/.venv/lib/python3.13/site-packages/pandas/core/tools/numeric.py
new file mode 100644
index 0000000000000000000000000000000000000000..ca703e0362611b9b2ccecdbf282104ad450a8d83
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/tools/numeric.py
@@ -0,0 +1,332 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    missing as libmissing,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.cast import maybe_downcast_numeric
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_bool_dtype,
+    is_decimal,
+    is_integer_dtype,
+    is_number,
+    is_numeric_dtype,
+    is_scalar,
+    is_string_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import ArrowDtype
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+
+from pandas.core.arrays import BaseMaskedArray
+from pandas.core.arrays.string_ import StringDtype
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DateTimeErrorChoices,
+        DtypeBackend,
+        npt,
+    )
+
+
+def to_numeric(
+    arg,
+    errors: DateTimeErrorChoices = "raise",
+    downcast: Literal["integer", "signed", "unsigned", "float"] | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+):
+    """
+    Convert argument to a numeric type.
+
+    The default return dtype is `float64` or `int64`
+    depending on the data supplied. Use the `downcast` parameter
+    to obtain other dtypes.
+
+    Please note that precision loss may occur if really large numbers
+    are passed in. Due to the internal limitations of `ndarray`, if
+    numbers smaller than `-9223372036854775808` (np.iinfo(np.int64).min)
+    or larger than `18446744073709551615` (np.iinfo(np.uint64).max) are
+    passed in, it is very likely they will be converted to float so that
+    they can be stored in an `ndarray`. These warnings apply similarly to
+    `Series` since it internally leverages `ndarray`.
+
+    Parameters
+    ----------
+    arg : scalar, list, tuple, 1-d array, or Series
+        Argument to be converted.
+    errors : {'ignore', 'raise', 'coerce'}, default 'raise'
+        - If 'raise', then invalid parsing will raise an exception.
+        - If 'coerce', then invalid parsing will be set as NaN.
+        - If 'ignore', then invalid parsing will return the input.
+
+        .. versionchanged:: 2.2
+
+        "ignore" is deprecated. Catch exceptions explicitly instead.
+
+    downcast : str, default None
+        Can be 'integer', 'signed', 'unsigned', or 'float'.
+        If not None, and if the data has been successfully cast to a
+        numerical dtype (or if the data was numeric to begin with),
+        downcast that resulting data to the smallest numerical dtype
+        possible according to the following rules:
+
+        - 'integer' or 'signed': smallest signed int dtype (min.: np.int8)
+        - 'unsigned': smallest unsigned int dtype (min.: np.uint8)
+        - 'float': smallest float dtype (min.: np.float32)
+
+        As this behaviour is separate from the core conversion to
+        numeric values, any errors raised during the downcasting
+        will be surfaced regardless of the value of the 'errors' input.
+
+        In addition, downcasting will only occur if the size
+        of the resulting data's dtype is strictly larger than
+        the dtype it is to be cast to, so if none of the dtypes
+        checked satisfy that specification, no downcasting will be
+        performed on the data.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    ret
+        Numeric if parsing succeeded.
+        Return type depends on input.  Series if Series, otherwise ndarray.
+
+    See Also
+    --------
+    DataFrame.astype : Cast argument to a specified dtype.
+    to_datetime : Convert argument to datetime.
+    to_timedelta : Convert argument to timedelta.
+    numpy.ndarray.astype : Cast a numpy array to a specified type.
+    DataFrame.convert_dtypes : Convert dtypes.
+
+    Examples
+    --------
+    Take separate series and convert to numeric, coercing when told to
+
+    >>> s = pd.Series(['1.0', '2', -3])
+    >>> pd.to_numeric(s)
+    0    1.0
+    1    2.0
+    2   -3.0
+    dtype: float64
+    >>> pd.to_numeric(s, downcast='float')
+    0    1.0
+    1    2.0
+    2   -3.0
+    dtype: float32
+    >>> pd.to_numeric(s, downcast='signed')
+    0    1
+    1    2
+    2   -3
+    dtype: int8
+    >>> s = pd.Series(['apple', '1.0', '2', -3])
+    >>> pd.to_numeric(s, errors='coerce')
+    0    NaN
+    1    1.0
+    2    2.0
+    3   -3.0
+    dtype: float64
+
+    Downcasting of nullable integer and floating dtypes is supported:
+
+    >>> s = pd.Series([1, 2, 3], dtype="Int64")
+    >>> pd.to_numeric(s, downcast="integer")
+    0    1
+    1    2
+    2    3
+    dtype: Int8
+    >>> s = pd.Series([1.0, 2.1, 3.0], dtype="Float64")
+    >>> pd.to_numeric(s, downcast="float")
+    0    1.0
+    1    2.1
+    2    3.0
+    dtype: Float32
+    """
+    if downcast not in (None, "integer", "signed", "unsigned", "float"):
+        raise ValueError("invalid downcasting method provided")
+
+    if errors not in ("ignore", "raise", "coerce"):
+        raise ValueError("invalid error value specified")
+    if errors == "ignore":
+        # GH#54467
+        warnings.warn(
+            "errors='ignore' is deprecated and will raise in a future version. "
+            "Use to_numeric without passing `errors` and catch exceptions "
+            "explicitly instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    check_dtype_backend(dtype_backend)
+
+    is_series = False
+    is_index = False
+    is_scalars = False
+
+    if isinstance(arg, ABCSeries):
+        is_series = True
+        values = arg.values
+    elif isinstance(arg, ABCIndex):
+        is_index = True
+        if needs_i8_conversion(arg.dtype):
+            values = arg.view("i8")
+        else:
+            values = arg.values
+    elif isinstance(arg, (list, tuple)):
+        values = np.array(arg, dtype="O")
+    elif is_scalar(arg):
+        if is_decimal(arg):
+            return float(arg)
+        if is_number(arg):
+            return arg
+        is_scalars = True
+        values = np.array([arg], dtype="O")
+    elif getattr(arg, "ndim", 1) > 1:
+        raise TypeError("arg must be a list, tuple, 1-d array, or Series")
+    else:
+        values = arg
+
+    orig_values = values
+
+    # GH33013: for IntegerArray & FloatingArray extract non-null values for casting
+    # save mask to reconstruct the full array after casting
+    mask: npt.NDArray[np.bool_] | None = None
+    if isinstance(values, BaseMaskedArray):
+        mask = values._mask
+        values = values._data[~mask]
+
+    values_dtype = getattr(values, "dtype", None)
+    if isinstance(values_dtype, ArrowDtype):
+        mask = values.isna()
+        values = values.dropna().to_numpy()
+    new_mask: np.ndarray | None = None
+    if is_numeric_dtype(values_dtype):
+        pass
+    elif lib.is_np_dtype(values_dtype, "mM"):
+        values = values.view(np.int64)
+    else:
+        values = ensure_object(values)
+        coerce_numeric = errors not in ("ignore", "raise")
+        try:
+            values, new_mask = lib.maybe_convert_numeric(  # type: ignore[call-overload]
+                values,
+                set(),
+                coerce_numeric=coerce_numeric,
+                convert_to_masked_nullable=dtype_backend is not lib.no_default
+                or isinstance(values_dtype, StringDtype)
+                and values_dtype.na_value is libmissing.NA,
+            )
+        except (ValueError, TypeError):
+            if errors == "raise":
+                raise
+            values = orig_values
+
+    if new_mask is not None:
+        # Remove unnecessary values, is expected later anyway and enables
+        # downcasting
+        values = values[~new_mask]
+    elif (
+        dtype_backend is not lib.no_default
+        and new_mask is None
+        or isinstance(values_dtype, StringDtype)
+        and values_dtype.na_value is libmissing.NA
+    ):
+        new_mask = np.zeros(values.shape, dtype=np.bool_)
+
+    # attempt downcast only if the data has been successfully converted
+    # to a numerical dtype and if a downcast method has been specified
+    if downcast is not None and is_numeric_dtype(values.dtype):
+        typecodes: str | None = None
+
+        if downcast in ("integer", "signed"):
+            typecodes = np.typecodes["Integer"]
+        elif downcast == "unsigned" and (not len(values) or np.min(values) >= 0):
+            typecodes = np.typecodes["UnsignedInteger"]
+        elif downcast == "float":
+            typecodes = np.typecodes["Float"]
+
+            # pandas support goes only to np.float32,
+            # as float dtypes smaller than that are
+            # extremely rare and not well supported
+            float_32_char = np.dtype(np.float32).char
+            float_32_ind = typecodes.index(float_32_char)
+            typecodes = typecodes[float_32_ind:]
+
+        if typecodes is not None:
+            # from smallest to largest
+            for typecode in typecodes:
+                dtype = np.dtype(typecode)
+                if dtype.itemsize <= values.dtype.itemsize:
+                    values = maybe_downcast_numeric(values, dtype)
+
+                    # successful conversion
+                    if values.dtype == dtype:
+                        break
+
+    # GH33013: for IntegerArray, BooleanArray & FloatingArray need to reconstruct
+    # masked array
+    if (mask is not None or new_mask is not None) and not is_string_dtype(values.dtype):
+        if mask is None or (new_mask is not None and new_mask.shape == mask.shape):
+            # GH 52588
+            mask = new_mask
+        else:
+            mask = mask.copy()
+        assert isinstance(mask, np.ndarray)
+        data = np.zeros(mask.shape, dtype=values.dtype)
+        data[~mask] = values
+
+        from pandas.core.arrays import (
+            ArrowExtensionArray,
+            BooleanArray,
+            FloatingArray,
+            IntegerArray,
+        )
+
+        klass: type[IntegerArray | BooleanArray | FloatingArray]
+        if is_integer_dtype(data.dtype):
+            klass = IntegerArray
+        elif is_bool_dtype(data.dtype):
+            klass = BooleanArray
+        else:
+            klass = FloatingArray
+        values = klass(data, mask)
+
+        if dtype_backend == "pyarrow" or isinstance(values_dtype, ArrowDtype):
+            values = ArrowExtensionArray(values.__arrow_array__())
+
+    if is_series:
+        return arg._constructor(values, index=arg.index, name=arg.name)
+    elif is_index:
+        # because we want to coerce to numeric if possible,
+        # do not use _shallow_copy
+        from pandas import Index
+
+        return Index(values, name=arg.name)
+    elif is_scalars:
+        return values[0]
+    else:
+        return values
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/tools/timedeltas.py b/.venv/lib/python3.13/site-packages/pandas/core/tools/timedeltas.py
new file mode 100644
index 0000000000000000000000000000000000000000..d772c908c473109fcf7e37e06014b43226328e31
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/tools/timedeltas.py
@@ -0,0 +1,283 @@
+"""
+timedelta support tools
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs import (
+    NaT,
+    NaTType,
+)
+from pandas._libs.tslibs.timedeltas import (
+    Timedelta,
+    disallow_ambiguous_unit,
+    parse_timedelta_unit,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.dtypes import ArrowDtype
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+
+from pandas.core.arrays.timedeltas import sequence_to_td64ns
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+    from datetime import timedelta
+
+    from pandas._libs.tslibs.timedeltas import UnitChoices
+    from pandas._typing import (
+        ArrayLike,
+        DateTimeErrorChoices,
+    )
+
+    from pandas import (
+        Index,
+        Series,
+        TimedeltaIndex,
+    )
+
+
+@overload
+def to_timedelta(
+    arg: str | float | timedelta,
+    unit: UnitChoices | None = ...,
+    errors: DateTimeErrorChoices = ...,
+) -> Timedelta:
+    ...
+
+
+@overload
+def to_timedelta(
+    arg: Series,
+    unit: UnitChoices | None = ...,
+    errors: DateTimeErrorChoices = ...,
+) -> Series:
+    ...
+
+
+@overload
+def to_timedelta(
+    arg: list | tuple | range | ArrayLike | Index,
+    unit: UnitChoices | None = ...,
+    errors: DateTimeErrorChoices = ...,
+) -> TimedeltaIndex:
+    ...
+
+
+def to_timedelta(
+    arg: str
+    | int
+    | float
+    | timedelta
+    | list
+    | tuple
+    | range
+    | ArrayLike
+    | Index
+    | Series,
+    unit: UnitChoices | None = None,
+    errors: DateTimeErrorChoices = "raise",
+) -> Timedelta | TimedeltaIndex | Series:
+    """
+    Convert argument to timedelta.
+
+    Timedeltas are absolute differences in times, expressed in difference
+    units (e.g. days, hours, minutes, seconds). This method converts
+    an argument from a recognized timedelta format / value into
+    a Timedelta type.
+
+    Parameters
+    ----------
+    arg : str, timedelta, list-like or Series
+        The data to be converted to timedelta.
+
+        .. versionchanged:: 2.0
+            Strings with units 'M', 'Y' and 'y' do not represent
+            unambiguous timedelta values and will raise an exception.
+
+    unit : str, optional
+        Denotes the unit of the arg for numeric `arg`. Defaults to ``"ns"``.
+
+        Possible values:
+
+        * 'W'
+        * 'D' / 'days' / 'day'
+        * 'hours' / 'hour' / 'hr' / 'h' / 'H'
+        * 'm' / 'minute' / 'min' / 'minutes' / 'T'
+        * 's' / 'seconds' / 'sec' / 'second' / 'S'
+        * 'ms' / 'milliseconds' / 'millisecond' / 'milli' / 'millis' / 'L'
+        * 'us' / 'microseconds' / 'microsecond' / 'micro' / 'micros' / 'U'
+        * 'ns' / 'nanoseconds' / 'nano' / 'nanos' / 'nanosecond' / 'N'
+
+        Must not be specified when `arg` contains strings and ``errors="raise"``.
+
+        .. deprecated:: 2.2.0
+            Units 'H', 'T', 'S', 'L', 'U' and 'N' are deprecated and will be removed
+            in a future version. Please use 'h', 'min', 's', 'ms', 'us', and 'ns'
+            instead of 'H', 'T', 'S', 'L', 'U' and 'N'.
+
+    errors : {'ignore', 'raise', 'coerce'}, default 'raise'
+        - If 'raise', then invalid parsing will raise an exception.
+        - If 'coerce', then invalid parsing will be set as NaT.
+        - If 'ignore', then invalid parsing will return the input.
+
+    Returns
+    -------
+    timedelta
+        If parsing succeeded.
+        Return type depends on input:
+
+        - list-like: TimedeltaIndex of timedelta64 dtype
+        - Series: Series of timedelta64 dtype
+        - scalar: Timedelta
+
+    See Also
+    --------
+    DataFrame.astype : Cast argument to a specified dtype.
+    to_datetime : Convert argument to datetime.
+    convert_dtypes : Convert dtypes.
+
+    Notes
+    -----
+    If the precision is higher than nanoseconds, the precision of the duration is
+    truncated to nanoseconds for string inputs.
+
+    Examples
+    --------
+    Parsing a single string to a Timedelta:
+
+    >>> pd.to_timedelta('1 days 06:05:01.00003')
+    Timedelta('1 days 06:05:01.000030')
+    >>> pd.to_timedelta('15.5us')
+    Timedelta('0 days 00:00:00.000015500')
+
+    Parsing a list or array of strings:
+
+    >>> pd.to_timedelta(['1 days 06:05:01.00003', '15.5us', 'nan'])
+    TimedeltaIndex(['1 days 06:05:01.000030', '0 days 00:00:00.000015500', NaT],
+                   dtype='timedelta64[ns]', freq=None)
+
+    Converting numbers by specifying the `unit` keyword argument:
+
+    >>> pd.to_timedelta(np.arange(5), unit='s')
+    TimedeltaIndex(['0 days 00:00:00', '0 days 00:00:01', '0 days 00:00:02',
+                    '0 days 00:00:03', '0 days 00:00:04'],
+                   dtype='timedelta64[ns]', freq=None)
+    >>> pd.to_timedelta(np.arange(5), unit='d')
+    TimedeltaIndex(['0 days', '1 days', '2 days', '3 days', '4 days'],
+                   dtype='timedelta64[ns]', freq=None)
+    """
+    if unit is not None:
+        unit = parse_timedelta_unit(unit)
+        disallow_ambiguous_unit(unit)
+
+    if errors not in ("ignore", "raise", "coerce"):
+        raise ValueError("errors must be one of 'ignore', 'raise', or 'coerce'.")
+    if errors == "ignore":
+        # GH#54467
+        warnings.warn(
+            "errors='ignore' is deprecated and will raise in a future version. "
+            "Use to_timedelta without passing `errors` and catch exceptions "
+            "explicitly instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if arg is None:
+        return arg
+    elif isinstance(arg, ABCSeries):
+        values = _convert_listlike(arg._values, unit=unit, errors=errors)
+        return arg._constructor(values, index=arg.index, name=arg.name)
+    elif isinstance(arg, ABCIndex):
+        return _convert_listlike(arg, unit=unit, errors=errors, name=arg.name)
+    elif isinstance(arg, np.ndarray) and arg.ndim == 0:
+        # extract array scalar and process below
+        # error: Incompatible types in assignment (expression has type "object",
+        # variable has type "Union[str, int, float, timedelta, List[Any],
+        # Tuple[Any, ...], Union[Union[ExtensionArray, ndarray[Any, Any]], Index,
+        # Series]]")  [assignment]
+        arg = lib.item_from_zerodim(arg)  # type: ignore[assignment]
+    elif is_list_like(arg) and getattr(arg, "ndim", 1) == 1:
+        return _convert_listlike(arg, unit=unit, errors=errors)
+    elif getattr(arg, "ndim", 1) > 1:
+        raise TypeError(
+            "arg must be a string, timedelta, list, tuple, 1-d array, or Series"
+        )
+
+    if isinstance(arg, str) and unit is not None:
+        raise ValueError("unit must not be specified if the input is/contains a str")
+
+    # ...so it must be a scalar value. Return scalar.
+    return _coerce_scalar_to_timedelta_type(arg, unit=unit, errors=errors)
+
+
+def _coerce_scalar_to_timedelta_type(
+    r, unit: UnitChoices | None = "ns", errors: DateTimeErrorChoices = "raise"
+):
+    """Convert string 'r' to a timedelta object."""
+    result: Timedelta | NaTType
+
+    try:
+        result = Timedelta(r, unit)
+    except ValueError:
+        if errors == "raise":
+            raise
+        if errors == "ignore":
+            return r
+
+        # coerce
+        result = NaT
+
+    return result
+
+
+def _convert_listlike(
+    arg,
+    unit: UnitChoices | None = None,
+    errors: DateTimeErrorChoices = "raise",
+    name: Hashable | None = None,
+):
+    """Convert a list of objects to a timedelta index object."""
+    arg_dtype = getattr(arg, "dtype", None)
+    if isinstance(arg, (list, tuple)) or arg_dtype is None:
+        # This is needed only to ensure that in the case where we end up
+        #  returning arg (errors == "ignore"), and where the input is a
+        #  generator, we return a useful list-like instead of a
+        #  used-up generator
+        if not hasattr(arg, "__array__"):
+            arg = list(arg)
+        arg = np.array(arg, dtype=object)
+    elif isinstance(arg_dtype, ArrowDtype) and arg_dtype.kind == "m":
+        return arg
+
+    try:
+        td64arr = sequence_to_td64ns(arg, unit=unit, errors=errors, copy=False)[0]
+    except ValueError:
+        if errors == "ignore":
+            return arg
+        else:
+            # This else-block accounts for the cases when errors='raise'
+            # and errors='coerce'. If errors == 'raise', these errors
+            # should be raised. If errors == 'coerce', we shouldn't
+            # expect any errors to be raised, since all parsing errors
+            # cause coercion to pd.NaT. However, if an error / bug is
+            # introduced that causes an Exception to be raised, we would
+            # like to surface it.
+            raise
+
+    from pandas import TimedeltaIndex
+
+    value = TimedeltaIndex(td64arr, name=name)
+    return value
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/tools/times.py b/.venv/lib/python3.13/site-packages/pandas/core/tools/times.py
new file mode 100644
index 0000000000000000000000000000000000000000..d77bcc91df7096bfad4b3eddf6355435a4b9e7f6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/tools/times.py
@@ -0,0 +1,168 @@
+from __future__ import annotations
+
+from datetime import (
+    datetime,
+    time,
+)
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+
+from pandas._libs.lib import is_list_like
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.generic import (
+    ABCIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import notna
+
+if TYPE_CHECKING:
+    from pandas._typing import DateTimeErrorChoices
+
+
+def to_time(
+    arg,
+    format: str | None = None,
+    infer_time_format: bool = False,
+    errors: DateTimeErrorChoices = "raise",
+):
+    """
+    Parse time strings to time objects using fixed strptime formats ("%H:%M",
+    "%H%M", "%I:%M%p", "%I%M%p", "%H:%M:%S", "%H%M%S", "%I:%M:%S%p",
+    "%I%M%S%p")
+
+    Use infer_time_format if all the strings are in the same format to speed
+    up conversion.
+
+    Parameters
+    ----------
+    arg : string in time format, datetime.time, list, tuple, 1-d array,  Series
+    format : str, default None
+        Format used to convert arg into a time object.  If None, fixed formats
+        are used.
+    infer_time_format: bool, default False
+        Infer the time format based on the first non-NaN element.  If all
+        strings are in the same format, this will speed up conversion.
+    errors : {'ignore', 'raise', 'coerce'}, default 'raise'
+        - If 'raise', then invalid parsing will raise an exception
+        - If 'coerce', then invalid parsing will be set as None
+        - If 'ignore', then invalid parsing will return the input
+
+    Returns
+    -------
+    datetime.time
+    """
+    if errors == "ignore":
+        # GH#54467
+        warnings.warn(
+            "errors='ignore' is deprecated and will raise in a future version. "
+            "Use to_time without passing `errors` and catch exceptions "
+            "explicitly instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    def _convert_listlike(arg, format):
+        if isinstance(arg, (list, tuple)):
+            arg = np.array(arg, dtype="O")
+
+        elif getattr(arg, "ndim", 1) > 1:
+            raise TypeError(
+                "arg must be a string, datetime, list, tuple, 1-d array, or Series"
+            )
+
+        arg = np.asarray(arg, dtype="O")
+
+        if infer_time_format and format is None:
+            format = _guess_time_format_for_array(arg)
+
+        times: list[time | None] = []
+        if format is not None:
+            for element in arg:
+                try:
+                    times.append(datetime.strptime(element, format).time())
+                except (ValueError, TypeError) as err:
+                    if errors == "raise":
+                        msg = (
+                            f"Cannot convert {element} to a time with given "
+                            f"format {format}"
+                        )
+                        raise ValueError(msg) from err
+                    if errors == "ignore":
+                        return arg
+                    else:
+                        times.append(None)
+        else:
+            formats = _time_formats[:]
+            format_found = False
+            for element in arg:
+                time_object = None
+                try:
+                    time_object = time.fromisoformat(element)
+                except (ValueError, TypeError):
+                    for time_format in formats:
+                        try:
+                            time_object = datetime.strptime(element, time_format).time()
+                            if not format_found:
+                                # Put the found format in front
+                                fmt = formats.pop(formats.index(time_format))
+                                formats.insert(0, fmt)
+                                format_found = True
+                            break
+                        except (ValueError, TypeError):
+                            continue
+
+                if time_object is not None:
+                    times.append(time_object)
+                elif errors == "raise":
+                    raise ValueError(f"Cannot convert arg {arg} to a time")
+                elif errors == "ignore":
+                    return arg
+                else:
+                    times.append(None)
+
+        return times
+
+    if arg is None:
+        return arg
+    elif isinstance(arg, time):
+        return arg
+    elif isinstance(arg, ABCSeries):
+        values = _convert_listlike(arg._values, format)
+        return arg._constructor(values, index=arg.index, name=arg.name)
+    elif isinstance(arg, ABCIndex):
+        return _convert_listlike(arg, format)
+    elif is_list_like(arg):
+        return _convert_listlike(arg, format)
+
+    return _convert_listlike(np.array([arg]), format)[0]
+
+
+# Fixed time formats for time parsing
+_time_formats = [
+    "%H:%M",
+    "%H%M",
+    "%I:%M%p",
+    "%I%M%p",
+    "%H:%M:%S",
+    "%H%M%S",
+    "%I:%M:%S%p",
+    "%I%M%S%p",
+]
+
+
+def _guess_time_format_for_array(arr):
+    # Try to guess the format based on the first non-NaN element
+    non_nan_elements = notna(arr).nonzero()[0]
+    if len(non_nan_elements):
+        element = arr[non_nan_elements[0]]
+        for time_format in _time_formats:
+            try:
+                datetime.strptime(element, time_format)
+                return time_format
+            except ValueError:
+                pass
+
+    return None
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/util/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/util/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/util/hashing.py b/.venv/lib/python3.13/site-packages/pandas/core/util/hashing.py
new file mode 100644
index 0000000000000000000000000000000000000000..4933de32125814baa6cc96926721c0c839540b2a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/util/hashing.py
@@ -0,0 +1,339 @@
+"""
+data hash pandas / numpy objects
+"""
+from __future__ import annotations
+
+import itertools
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs.hashing import hash_object_array
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.dtypes import CategoricalDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCExtensionArray,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Iterator,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Index,
+        MultiIndex,
+        Series,
+    )
+
+
+# 16 byte long hashing key
+_default_hash_key = "0123456789123456"
+
+
+def combine_hash_arrays(
+    arrays: Iterator[np.ndarray], num_items: int
+) -> npt.NDArray[np.uint64]:
+    """
+    Parameters
+    ----------
+    arrays : Iterator[np.ndarray]
+    num_items : int
+
+    Returns
+    -------
+    np.ndarray[uint64]
+
+    Should be the same as CPython's tupleobject.c
+    """
+    try:
+        first = next(arrays)
+    except StopIteration:
+        return np.array([], dtype=np.uint64)
+
+    arrays = itertools.chain([first], arrays)
+
+    mult = np.uint64(1000003)
+    out = np.zeros_like(first) + np.uint64(0x345678)
+    last_i = 0
+    for i, a in enumerate(arrays):
+        inverse_i = num_items - i
+        out ^= a
+        out *= mult
+        mult += np.uint64(82520 + inverse_i + inverse_i)
+        last_i = i
+    assert last_i + 1 == num_items, "Fed in wrong num_items"
+    out += np.uint64(97531)
+    return out
+
+
+def hash_pandas_object(
+    obj: Index | DataFrame | Series,
+    index: bool = True,
+    encoding: str = "utf8",
+    hash_key: str | None = _default_hash_key,
+    categorize: bool = True,
+) -> Series:
+    """
+    Return a data hash of the Index/Series/DataFrame.
+
+    Parameters
+    ----------
+    obj : Index, Series, or DataFrame
+    index : bool, default True
+        Include the index in the hash (if Series/DataFrame).
+    encoding : str, default 'utf8'
+        Encoding for data & key when strings.
+    hash_key : str, default _default_hash_key
+        Hash_key for string key to encode.
+    categorize : bool, default True
+        Whether to first categorize object arrays before hashing. This is more
+        efficient when the array contains duplicate values.
+
+    Returns
+    -------
+    Series of uint64, same length as the object
+
+    Examples
+    --------
+    >>> pd.util.hash_pandas_object(pd.Series([1, 2, 3]))
+    0    14639053686158035780
+    1     3869563279212530728
+    2      393322362522515241
+    dtype: uint64
+    """
+    from pandas import Series
+
+    if hash_key is None:
+        hash_key = _default_hash_key
+
+    if isinstance(obj, ABCMultiIndex):
+        return Series(hash_tuples(obj, encoding, hash_key), dtype="uint64", copy=False)
+
+    elif isinstance(obj, ABCIndex):
+        h = hash_array(obj._values, encoding, hash_key, categorize).astype(
+            "uint64", copy=False
+        )
+        ser = Series(h, index=obj, dtype="uint64", copy=False)
+
+    elif isinstance(obj, ABCSeries):
+        h = hash_array(obj._values, encoding, hash_key, categorize).astype(
+            "uint64", copy=False
+        )
+        if index:
+            index_iter = (
+                hash_pandas_object(
+                    obj.index,
+                    index=False,
+                    encoding=encoding,
+                    hash_key=hash_key,
+                    categorize=categorize,
+                )._values
+                for _ in [None]
+            )
+            arrays = itertools.chain([h], index_iter)
+            h = combine_hash_arrays(arrays, 2)
+
+        ser = Series(h, index=obj.index, dtype="uint64", copy=False)
+
+    elif isinstance(obj, ABCDataFrame):
+        hashes = (
+            hash_array(series._values, encoding, hash_key, categorize)
+            for _, series in obj.items()
+        )
+        num_items = len(obj.columns)
+        if index:
+            index_hash_generator = (
+                hash_pandas_object(
+                    obj.index,
+                    index=False,
+                    encoding=encoding,
+                    hash_key=hash_key,
+                    categorize=categorize,
+                )._values
+                for _ in [None]
+            )
+            num_items += 1
+
+            # keep `hashes` specifically a generator to keep mypy happy
+            _hashes = itertools.chain(hashes, index_hash_generator)
+            hashes = (x for x in _hashes)
+        h = combine_hash_arrays(hashes, num_items)
+
+        ser = Series(h, index=obj.index, dtype="uint64", copy=False)
+    else:
+        raise TypeError(f"Unexpected type for hashing {type(obj)}")
+
+    return ser
+
+
+def hash_tuples(
+    vals: MultiIndex | Iterable[tuple[Hashable, ...]],
+    encoding: str = "utf8",
+    hash_key: str = _default_hash_key,
+) -> npt.NDArray[np.uint64]:
+    """
+    Hash an MultiIndex / listlike-of-tuples efficiently.
+
+    Parameters
+    ----------
+    vals : MultiIndex or listlike-of-tuples
+    encoding : str, default 'utf8'
+    hash_key : str, default _default_hash_key
+
+    Returns
+    -------
+    ndarray[np.uint64] of hashed values
+    """
+    if not is_list_like(vals):
+        raise TypeError("must be convertible to a list-of-tuples")
+
+    from pandas import (
+        Categorical,
+        MultiIndex,
+    )
+
+    if not isinstance(vals, ABCMultiIndex):
+        mi = MultiIndex.from_tuples(vals)
+    else:
+        mi = vals
+
+    # create a list-of-Categoricals
+    cat_vals = [
+        Categorical._simple_new(
+            mi.codes[level],
+            CategoricalDtype(categories=mi.levels[level], ordered=False),
+        )
+        for level in range(mi.nlevels)
+    ]
+
+    # hash the list-of-ndarrays
+    hashes = (
+        cat._hash_pandas_object(encoding=encoding, hash_key=hash_key, categorize=False)
+        for cat in cat_vals
+    )
+    h = combine_hash_arrays(hashes, len(cat_vals))
+
+    return h
+
+
+def hash_array(
+    vals: ArrayLike,
+    encoding: str = "utf8",
+    hash_key: str = _default_hash_key,
+    categorize: bool = True,
+) -> npt.NDArray[np.uint64]:
+    """
+    Given a 1d array, return an array of deterministic integers.
+
+    Parameters
+    ----------
+    vals : ndarray or ExtensionArray
+    encoding : str, default 'utf8'
+        Encoding for data & key when strings.
+    hash_key : str, default _default_hash_key
+        Hash_key for string key to encode.
+    categorize : bool, default True
+        Whether to first categorize object arrays before hashing. This is more
+        efficient when the array contains duplicate values.
+
+    Returns
+    -------
+    ndarray[np.uint64, ndim=1]
+        Hashed values, same length as the vals.
+
+    Examples
+    --------
+    >>> pd.util.hash_array(np.array([1, 2, 3]))
+    array([ 6238072747940578789, 15839785061582574730,  2185194620014831856],
+      dtype=uint64)
+    """
+    if not hasattr(vals, "dtype"):
+        raise TypeError("must pass a ndarray-like")
+
+    if isinstance(vals, ABCExtensionArray):
+        return vals._hash_pandas_object(
+            encoding=encoding, hash_key=hash_key, categorize=categorize
+        )
+
+    if not isinstance(vals, np.ndarray):
+        # GH#42003
+        raise TypeError(
+            "hash_array requires np.ndarray or ExtensionArray, not "
+            f"{type(vals).__name__}. Use hash_pandas_object instead."
+        )
+
+    return _hash_ndarray(vals, encoding, hash_key, categorize)
+
+
+def _hash_ndarray(
+    vals: np.ndarray,
+    encoding: str = "utf8",
+    hash_key: str = _default_hash_key,
+    categorize: bool = True,
+) -> npt.NDArray[np.uint64]:
+    """
+    See hash_array.__doc__.
+    """
+    dtype = vals.dtype
+
+    # _hash_ndarray only takes 64-bit values, so handle 128-bit by parts
+    if np.issubdtype(dtype, np.complex128):
+        hash_real = _hash_ndarray(vals.real, encoding, hash_key, categorize)
+        hash_imag = _hash_ndarray(vals.imag, encoding, hash_key, categorize)
+        return hash_real + 23 * hash_imag
+
+    # First, turn whatever array this is into unsigned 64-bit ints, if we can
+    # manage it.
+    if dtype == bool:
+        vals = vals.astype("u8")
+    elif issubclass(dtype.type, (np.datetime64, np.timedelta64)):
+        vals = vals.view("i8").astype("u8", copy=False)
+    elif issubclass(dtype.type, np.number) and dtype.itemsize <= 8:
+        vals = vals.view(f"u{vals.dtype.itemsize}").astype("u8")
+    else:
+        # With repeated values, its MUCH faster to categorize object dtypes,
+        # then hash and rename categories. We allow skipping the categorization
+        # when the values are known/likely to be unique.
+        if categorize:
+            from pandas import (
+                Categorical,
+                Index,
+                factorize,
+            )
+
+            codes, categories = factorize(vals, sort=False)
+            dtype = CategoricalDtype(categories=Index(categories), ordered=False)
+            cat = Categorical._simple_new(codes, dtype)
+            return cat._hash_pandas_object(
+                encoding=encoding, hash_key=hash_key, categorize=False
+            )
+
+        try:
+            vals = hash_object_array(vals, hash_key, encoding)
+        except TypeError:
+            # we have mixed types
+            vals = hash_object_array(
+                vals.astype(str).astype(object), hash_key, encoding
+            )
+
+    # Then, redistribute these 64-bit ints within the space of 64-bit ints
+    vals ^= vals >> 30
+    vals *= np.uint64(0xBF58476D1CE4E5B9)
+    vals ^= vals >> 27
+    vals *= np.uint64(0x94D049BB133111EB)
+    vals ^= vals >> 31
+    return vals
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/util/numba_.py b/.venv/lib/python3.13/site-packages/pandas/core/util/numba_.py
new file mode 100644
index 0000000000000000000000000000000000000000..4825c9fee24b1b1272c5f245a9c7ae49f53003fc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/util/numba_.py
@@ -0,0 +1,98 @@
+"""Common utilities for Numba operations"""
+from __future__ import annotations
+
+import types
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import NumbaUtilError
+
+GLOBAL_USE_NUMBA: bool = False
+
+
+def maybe_use_numba(engine: str | None) -> bool:
+    """Signal whether to use numba routines."""
+    return engine == "numba" or (engine is None and GLOBAL_USE_NUMBA)
+
+
+def set_use_numba(enable: bool = False) -> None:
+    global GLOBAL_USE_NUMBA
+    if enable:
+        import_optional_dependency("numba")
+    GLOBAL_USE_NUMBA = enable
+
+
+def get_jit_arguments(
+    engine_kwargs: dict[str, bool] | None = None, kwargs: dict | None = None
+) -> dict[str, bool]:
+    """
+    Return arguments to pass to numba.JIT, falling back on pandas default JIT settings.
+
+    Parameters
+    ----------
+    engine_kwargs : dict, default None
+        user passed keyword arguments for numba.JIT
+    kwargs : dict, default None
+        user passed keyword arguments to pass into the JITed function
+
+    Returns
+    -------
+    dict[str, bool]
+        nopython, nogil, parallel
+
+    Raises
+    ------
+    NumbaUtilError
+    """
+    if engine_kwargs is None:
+        engine_kwargs = {}
+
+    nopython = engine_kwargs.get("nopython", True)
+    if kwargs and nopython:
+        raise NumbaUtilError(
+            "numba does not support kwargs with nopython=True: "
+            "https://github.com/numba/numba/issues/2916"
+        )
+    nogil = engine_kwargs.get("nogil", False)
+    parallel = engine_kwargs.get("parallel", False)
+    return {"nopython": nopython, "nogil": nogil, "parallel": parallel}
+
+
+def jit_user_function(func: Callable) -> Callable:
+    """
+    If user function is not jitted already, mark the user's function
+    as jitable.
+
+    Parameters
+    ----------
+    func : function
+        user defined function
+
+    Returns
+    -------
+    function
+        Numba JITed function, or function marked as JITable by numba
+    """
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    if numba.extending.is_jitted(func):
+        # Don't jit a user passed jitted function
+        numba_func = func
+    elif getattr(np, func.__name__, False) is func or isinstance(
+        func, types.BuiltinFunctionType
+    ):
+        # Not necessary to jit builtins or np functions
+        # This will mess up register_jitable
+        numba_func = func
+    else:
+        numba_func = numba.extending.register_jitable(func)
+
+    return numba_func
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/__init__.py b/.venv/lib/python3.13/site-packages/pandas/core/window/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..857e12e5467a6a7d2263d9add33e65b9499778fa
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/__init__.py
@@ -0,0 +1,23 @@
+from pandas.core.window.ewm import (
+    ExponentialMovingWindow,
+    ExponentialMovingWindowGroupby,
+)
+from pandas.core.window.expanding import (
+    Expanding,
+    ExpandingGroupby,
+)
+from pandas.core.window.rolling import (
+    Rolling,
+    RollingGroupby,
+    Window,
+)
+
+__all__ = [
+    "Expanding",
+    "ExpandingGroupby",
+    "ExponentialMovingWindow",
+    "ExponentialMovingWindowGroupby",
+    "Rolling",
+    "RollingGroupby",
+    "Window",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/common.py b/.venv/lib/python3.13/site-packages/pandas/core/window/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..fc8eddca09c84029b9ac92b658a47b45e4764414
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/common.py
@@ -0,0 +1,169 @@
+"""Common utility functions for rolling operations"""
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import cast
+
+import numpy as np
+
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+from pandas.core.indexes.api import MultiIndex
+
+
+def flex_binary_moment(arg1, arg2, f, pairwise: bool = False):
+    if isinstance(arg1, ABCSeries) and isinstance(arg2, ABCSeries):
+        X, Y = prep_binary(arg1, arg2)
+        return f(X, Y)
+
+    elif isinstance(arg1, ABCDataFrame):
+        from pandas import DataFrame
+
+        def dataframe_from_int_dict(data, frame_template) -> DataFrame:
+            result = DataFrame(data, index=frame_template.index)
+            if len(result.columns) > 0:
+                result.columns = frame_template.columns[result.columns]
+            else:
+                result.columns = frame_template.columns.copy()
+            return result
+
+        results = {}
+        if isinstance(arg2, ABCDataFrame):
+            if pairwise is False:
+                if arg1 is arg2:
+                    # special case in order to handle duplicate column names
+                    for i in range(len(arg1.columns)):
+                        results[i] = f(arg1.iloc[:, i], arg2.iloc[:, i])
+                    return dataframe_from_int_dict(results, arg1)
+                else:
+                    if not arg1.columns.is_unique:
+                        raise ValueError("'arg1' columns are not unique")
+                    if not arg2.columns.is_unique:
+                        raise ValueError("'arg2' columns are not unique")
+                    X, Y = arg1.align(arg2, join="outer")
+                    X, Y = prep_binary(X, Y)
+                    res_columns = arg1.columns.union(arg2.columns)
+                    for col in res_columns:
+                        if col in X and col in Y:
+                            results[col] = f(X[col], Y[col])
+                    return DataFrame(results, index=X.index, columns=res_columns)
+            elif pairwise is True:
+                results = defaultdict(dict)
+                for i in range(len(arg1.columns)):
+                    for j in range(len(arg2.columns)):
+                        if j < i and arg2 is arg1:
+                            # Symmetric case
+                            results[i][j] = results[j][i]
+                        else:
+                            results[i][j] = f(
+                                *prep_binary(arg1.iloc[:, i], arg2.iloc[:, j])
+                            )
+
+                from pandas import concat
+
+                result_index = arg1.index.union(arg2.index)
+                if len(result_index):
+                    # construct result frame
+                    result = concat(
+                        [
+                            concat(
+                                [results[i][j] for j in range(len(arg2.columns))],
+                                ignore_index=True,
+                            )
+                            for i in range(len(arg1.columns))
+                        ],
+                        ignore_index=True,
+                        axis=1,
+                    )
+                    result.columns = arg1.columns
+
+                    # set the index and reorder
+                    if arg2.columns.nlevels > 1:
+                        # mypy needs to know columns is a MultiIndex, Index doesn't
+                        # have levels attribute
+                        arg2.columns = cast(MultiIndex, arg2.columns)
+                        # GH 21157: Equivalent to MultiIndex.from_product(
+                        #  [result_index], ,
+                        # )
+                        # A normal MultiIndex.from_product will produce too many
+                        # combinations.
+                        result_level = np.tile(
+                            result_index, len(result) // len(result_index)
+                        )
+                        arg2_levels = (
+                            np.repeat(
+                                arg2.columns.get_level_values(i),
+                                len(result) // len(arg2.columns),
+                            )
+                            for i in range(arg2.columns.nlevels)
+                        )
+                        result_names = list(arg2.columns.names) + [result_index.name]
+                        result.index = MultiIndex.from_arrays(
+                            [*arg2_levels, result_level], names=result_names
+                        )
+                        # GH 34440
+                        num_levels = len(result.index.levels)
+                        new_order = [num_levels - 1] + list(range(num_levels - 1))
+                        result = result.reorder_levels(new_order).sort_index()
+                    else:
+                        result.index = MultiIndex.from_product(
+                            [range(len(arg2.columns)), range(len(result_index))]
+                        )
+                        result = result.swaplevel(1, 0).sort_index()
+                        result.index = MultiIndex.from_product(
+                            [result_index] + [arg2.columns]
+                        )
+                else:
+                    # empty result
+                    result = DataFrame(
+                        index=MultiIndex(
+                            levels=[arg1.index, arg2.columns], codes=[[], []]
+                        ),
+                        columns=arg2.columns,
+                        dtype="float64",
+                    )
+
+                # reset our index names to arg1 names
+                # reset our column names to arg2 names
+                # careful not to mutate the original names
+                result.columns = result.columns.set_names(arg1.columns.names)
+                result.index = result.index.set_names(
+                    result_index.names + arg2.columns.names
+                )
+
+                return result
+        else:
+            results = {
+                i: f(*prep_binary(arg1.iloc[:, i], arg2))
+                for i in range(len(arg1.columns))
+            }
+            return dataframe_from_int_dict(results, arg1)
+
+    else:
+        return flex_binary_moment(arg2, arg1, f)
+
+
+def zsqrt(x):
+    with np.errstate(all="ignore"):
+        result = np.sqrt(x)
+        mask = x < 0
+
+    if isinstance(x, ABCDataFrame):
+        if mask._values.any():
+            result[mask] = 0
+    else:
+        if mask.any():
+            result[mask] = 0
+
+    return result
+
+
+def prep_binary(arg1, arg2):
+    # mask out values, this also makes a common index...
+    X = arg1 + 0 * arg2
+    Y = arg2 + 0 * arg1
+
+    return X, Y
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/doc.py b/.venv/lib/python3.13/site-packages/pandas/core/window/doc.py
new file mode 100644
index 0000000000000000000000000000000000000000..2a5cbc04921fadacf18a89608f2c0665bd8177e2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/doc.py
@@ -0,0 +1,116 @@
+"""Any shareable docstring components for rolling/expanding/ewm"""
+from __future__ import annotations
+
+from textwrap import dedent
+
+from pandas.core.shared_docs import _shared_docs
+
+_shared_docs = dict(**_shared_docs)
+
+
+def create_section_header(header: str) -> str:
+    """Create numpydoc section header"""
+    return f"{header}\n{'-' * len(header)}\n"
+
+
+template_header = "\nCalculate the {window_method} {aggregation_description}.\n\n"
+
+template_returns = dedent(
+    """
+    Series or DataFrame
+        Return type is the same as the original object with ``np.float64`` dtype.\n
+    """
+).replace("\n", "", 1)
+
+template_see_also = dedent(
+    """
+    pandas.Series.{window_method} : Calling {window_method} with Series data.
+    pandas.DataFrame.{window_method} : Calling {window_method} with DataFrames.
+    pandas.Series.{agg_method} : Aggregating {agg_method} for Series.
+    pandas.DataFrame.{agg_method} : Aggregating {agg_method} for DataFrame.\n
+    """
+).replace("\n", "", 1)
+
+kwargs_numeric_only = dedent(
+    """
+    numeric_only : bool, default False
+        Include only float, int, boolean columns.
+
+        .. versionadded:: 1.5.0\n
+    """
+).replace("\n", "", 1)
+
+kwargs_scipy = dedent(
+    """
+    **kwargs
+        Keyword arguments to configure the ``SciPy`` weighted window type.\n
+    """
+).replace("\n", "", 1)
+
+window_apply_parameters = dedent(
+    """
+    func : function
+        Must produce a single value from an ndarray input if ``raw=True``
+        or a single value from a Series if ``raw=False``. Can also accept a
+        Numba JIT function with ``engine='numba'`` specified.
+
+    raw : bool, default False
+        * ``False`` : passes each row or column as a Series to the
+          function.
+        * ``True`` : the passed function will receive ndarray
+          objects instead.
+          If you are just applying a NumPy reduction function this will
+          achieve much better performance.
+
+    engine : str, default None
+        * ``'cython'`` : Runs rolling apply through C-extensions from cython.
+        * ``'numba'`` : Runs rolling apply through JIT compiled code from numba.
+          Only available when ``raw`` is set to ``True``.
+        * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
+
+    engine_kwargs : dict, default None
+        * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+        * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+          and ``parallel`` dictionary keys. The values must either be ``True`` or
+          ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+          ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
+          applied to both the ``func`` and the ``apply`` rolling aggregation.
+
+    args : tuple, default None
+        Positional arguments to be passed into func.
+
+    kwargs : dict, default None
+        Keyword arguments to be passed into func.\n
+    """
+).replace("\n", "", 1)
+
+numba_notes = (
+    "See :ref:`window.numba_engine` and :ref:`enhancingperf.numba` for "
+    "extended documentation and performance considerations for the Numba engine.\n\n"
+)
+
+
+def window_agg_numba_parameters(version: str = "1.3") -> str:
+    return (
+        dedent(
+            """
+    engine : str, default None
+        * ``'cython'`` : Runs the operation through C-extensions from cython.
+        * ``'numba'`` : Runs the operation through JIT compiled code from numba.
+        * ``None`` : Defaults to ``'cython'`` or globally setting ``compute.use_numba``
+
+          .. versionadded:: {version}.0
+
+    engine_kwargs : dict, default None
+        * For ``'cython'`` engine, there are no accepted ``engine_kwargs``
+        * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+          and ``parallel`` dictionary keys. The values must either be ``True`` or
+          ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+          ``{{'nopython': True, 'nogil': False, 'parallel': False}}``
+
+          .. versionadded:: {version}.0\n
+    """
+        )
+        .replace("\n", "", 1)
+        .replace("{version}", version)
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/ewm.py b/.venv/lib/python3.13/site-packages/pandas/core/window/ewm.py
new file mode 100644
index 0000000000000000000000000000000000000000..9ebf32d3e536eee7233b911acb880f3d40521793
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/ewm.py
@@ -0,0 +1,1095 @@
+from __future__ import annotations
+
+import datetime
+from functools import partial
+from textwrap import dedent
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._libs.tslibs import Timedelta
+import pandas._libs.window.aggregations as window_aggregations
+from pandas.util._decorators import doc
+
+from pandas.core.dtypes.common import (
+    is_datetime64_dtype,
+    is_numeric_dtype,
+)
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+from pandas.core.dtypes.generic import ABCSeries
+from pandas.core.dtypes.missing import isna
+
+from pandas.core import common
+from pandas.core.arrays.datetimelike import dtype_to_unit
+from pandas.core.indexers.objects import (
+    BaseIndexer,
+    ExponentialMovingWindowIndexer,
+    GroupbyIndexer,
+)
+from pandas.core.util.numba_ import (
+    get_jit_arguments,
+    maybe_use_numba,
+)
+from pandas.core.window.common import zsqrt
+from pandas.core.window.doc import (
+    _shared_docs,
+    create_section_header,
+    kwargs_numeric_only,
+    numba_notes,
+    template_header,
+    template_returns,
+    template_see_also,
+    window_agg_numba_parameters,
+)
+from pandas.core.window.numba_ import (
+    generate_numba_ewm_func,
+    generate_numba_ewm_table_func,
+)
+from pandas.core.window.online import (
+    EWMMeanState,
+    generate_online_numba_ewma_func,
+)
+from pandas.core.window.rolling import (
+    BaseWindow,
+    BaseWindowGroupby,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Axis,
+        TimedeltaConvertibleTypes,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.generic import NDFrame
+
+
+def get_center_of_mass(
+    comass: float | None,
+    span: float | None,
+    halflife: float | None,
+    alpha: float | None,
+) -> float:
+    valid_count = common.count_not_none(comass, span, halflife, alpha)
+    if valid_count > 1:
+        raise ValueError("comass, span, halflife, and alpha are mutually exclusive")
+
+    # Convert to center of mass; domain checks ensure 0 < alpha <= 1
+    if comass is not None:
+        if comass < 0:
+            raise ValueError("comass must satisfy: comass >= 0")
+    elif span is not None:
+        if span < 1:
+            raise ValueError("span must satisfy: span >= 1")
+        comass = (span - 1) / 2
+    elif halflife is not None:
+        if halflife <= 0:
+            raise ValueError("halflife must satisfy: halflife > 0")
+        decay = 1 - np.exp(np.log(0.5) / halflife)
+        comass = 1 / decay - 1
+    elif alpha is not None:
+        if alpha <= 0 or alpha > 1:
+            raise ValueError("alpha must satisfy: 0 < alpha <= 1")
+        comass = (1 - alpha) / alpha
+    else:
+        raise ValueError("Must pass one of comass, span, halflife, or alpha")
+
+    return float(comass)
+
+
+def _calculate_deltas(
+    times: np.ndarray | NDFrame,
+    halflife: float | TimedeltaConvertibleTypes | None,
+) -> npt.NDArray[np.float64]:
+    """
+    Return the diff of the times divided by the half-life. These values are used in
+    the calculation of the ewm mean.
+
+    Parameters
+    ----------
+    times : np.ndarray, Series
+        Times corresponding to the observations. Must be monotonically increasing
+        and ``datetime64[ns]`` dtype.
+    halflife : float, str, timedelta, optional
+        Half-life specifying the decay
+
+    Returns
+    -------
+    np.ndarray
+        Diff of the times divided by the half-life
+    """
+    unit = dtype_to_unit(times.dtype)
+    if isinstance(times, ABCSeries):
+        times = times._values
+    _times = np.asarray(times.view(np.int64), dtype=np.float64)
+    _halflife = float(Timedelta(halflife).as_unit(unit)._value)
+    return np.diff(_times) / _halflife
+
+
+class ExponentialMovingWindow(BaseWindow):
+    r"""
+    Provide exponentially weighted (EW) calculations.
+
+    Exactly one of ``com``, ``span``, ``halflife``, or ``alpha`` must be
+    provided if ``times`` is not provided. If ``times`` is provided,
+    ``halflife`` and one of ``com``, ``span`` or ``alpha`` may be provided.
+
+    Parameters
+    ----------
+    com : float, optional
+        Specify decay in terms of center of mass
+
+        :math:`\alpha = 1 / (1 + com)`, for :math:`com \geq 0`.
+
+    span : float, optional
+        Specify decay in terms of span
+
+        :math:`\alpha = 2 / (span + 1)`, for :math:`span \geq 1`.
+
+    halflife : float, str, timedelta, optional
+        Specify decay in terms of half-life
+
+        :math:`\alpha = 1 - \exp\left(-\ln(2) / halflife\right)`, for
+        :math:`halflife > 0`.
+
+        If ``times`` is specified, a timedelta convertible unit over which an
+        observation decays to half its value. Only applicable to ``mean()``,
+        and halflife value will not apply to the other functions.
+
+    alpha : float, optional
+        Specify smoothing factor :math:`\alpha` directly
+
+        :math:`0 < \alpha \leq 1`.
+
+    min_periods : int, default 0
+        Minimum number of observations in window required to have a value;
+        otherwise, result is ``np.nan``.
+
+    adjust : bool, default True
+        Divide by decaying adjustment factor in beginning periods to account
+        for imbalance in relative weightings (viewing EWMA as a moving average).
+
+        - When ``adjust=True`` (default), the EW function is calculated using weights
+          :math:`w_i = (1 - \alpha)^i`. For example, the EW moving average of the series
+          [:math:`x_0, x_1, ..., x_t`] would be:
+
+        .. math::
+            y_t = \frac{x_t + (1 - \alpha)x_{t-1} + (1 - \alpha)^2 x_{t-2} + ... + (1 -
+            \alpha)^t x_0}{1 + (1 - \alpha) + (1 - \alpha)^2 + ... + (1 - \alpha)^t}
+
+        - When ``adjust=False``, the exponentially weighted function is calculated
+          recursively:
+
+        .. math::
+            \begin{split}
+                y_0 &= x_0\\
+                y_t &= (1 - \alpha) y_{t-1} + \alpha x_t,
+            \end{split}
+    ignore_na : bool, default False
+        Ignore missing values when calculating weights.
+
+        - When ``ignore_na=False`` (default), weights are based on absolute positions.
+          For example, the weights of :math:`x_0` and :math:`x_2` used in calculating
+          the final weighted average of [:math:`x_0`, None, :math:`x_2`] are
+          :math:`(1-\alpha)^2` and :math:`1` if ``adjust=True``, and
+          :math:`(1-\alpha)^2` and :math:`\alpha` if ``adjust=False``.
+
+        - When ``ignore_na=True``, weights are based
+          on relative positions. For example, the weights of :math:`x_0` and :math:`x_2`
+          used in calculating the final weighted average of
+          [:math:`x_0`, None, :math:`x_2`] are :math:`1-\alpha` and :math:`1` if
+          ``adjust=True``, and :math:`1-\alpha` and :math:`\alpha` if ``adjust=False``.
+
+    axis : {0, 1}, default 0
+        If ``0`` or ``'index'``, calculate across the rows.
+
+        If ``1`` or ``'columns'``, calculate across the columns.
+
+        For `Series` this parameter is unused and defaults to 0.
+
+    times : np.ndarray, Series, default None
+
+        Only applicable to ``mean()``.
+
+        Times corresponding to the observations. Must be monotonically increasing and
+        ``datetime64[ns]`` dtype.
+
+        If 1-D array like, a sequence with the same shape as the observations.
+
+    method : str {'single', 'table'}, default 'single'
+        .. versionadded:: 1.4.0
+
+        Execute the rolling operation per single column or row (``'single'``)
+        or over the entire object (``'table'``).
+
+        This argument is only implemented when specifying ``engine='numba'``
+        in the method call.
+
+        Only applicable to ``mean()``
+
+    Returns
+    -------
+    pandas.api.typing.ExponentialMovingWindow
+
+    See Also
+    --------
+    rolling : Provides rolling window calculations.
+    expanding : Provides expanding transformations.
+
+    Notes
+    -----
+    See :ref:`Windowing Operations `
+    for further usage details and examples.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]})
+    >>> df
+         B
+    0  0.0
+    1  1.0
+    2  2.0
+    3  NaN
+    4  4.0
+
+    >>> df.ewm(com=0.5).mean()
+              B
+    0  0.000000
+    1  0.750000
+    2  1.615385
+    3  1.615385
+    4  3.670213
+    >>> df.ewm(alpha=2 / 3).mean()
+              B
+    0  0.000000
+    1  0.750000
+    2  1.615385
+    3  1.615385
+    4  3.670213
+
+    **adjust**
+
+    >>> df.ewm(com=0.5, adjust=True).mean()
+              B
+    0  0.000000
+    1  0.750000
+    2  1.615385
+    3  1.615385
+    4  3.670213
+    >>> df.ewm(com=0.5, adjust=False).mean()
+              B
+    0  0.000000
+    1  0.666667
+    2  1.555556
+    3  1.555556
+    4  3.650794
+
+    **ignore_na**
+
+    >>> df.ewm(com=0.5, ignore_na=True).mean()
+              B
+    0  0.000000
+    1  0.750000
+    2  1.615385
+    3  1.615385
+    4  3.225000
+    >>> df.ewm(com=0.5, ignore_na=False).mean()
+              B
+    0  0.000000
+    1  0.750000
+    2  1.615385
+    3  1.615385
+    4  3.670213
+
+    **times**
+
+    Exponentially weighted mean with weights calculated with a timedelta ``halflife``
+    relative to ``times``.
+
+    >>> times = ['2020-01-01', '2020-01-03', '2020-01-10', '2020-01-15', '2020-01-17']
+    >>> df.ewm(halflife='4 days', times=pd.DatetimeIndex(times)).mean()
+              B
+    0  0.000000
+    1  0.585786
+    2  1.523889
+    3  1.523889
+    4  3.233686
+    """
+
+    _attributes = [
+        "com",
+        "span",
+        "halflife",
+        "alpha",
+        "min_periods",
+        "adjust",
+        "ignore_na",
+        "axis",
+        "times",
+        "method",
+    ]
+
+    def __init__(
+        self,
+        obj: NDFrame,
+        com: float | None = None,
+        span: float | None = None,
+        halflife: float | TimedeltaConvertibleTypes | None = None,
+        alpha: float | None = None,
+        min_periods: int | None = 0,
+        adjust: bool = True,
+        ignore_na: bool = False,
+        axis: Axis = 0,
+        times: np.ndarray | NDFrame | None = None,
+        method: str = "single",
+        *,
+        selection=None,
+    ) -> None:
+        super().__init__(
+            obj=obj,
+            min_periods=1 if min_periods is None else max(int(min_periods), 1),
+            on=None,
+            center=False,
+            closed=None,
+            method=method,
+            axis=axis,
+            selection=selection,
+        )
+        self.com = com
+        self.span = span
+        self.halflife = halflife
+        self.alpha = alpha
+        self.adjust = adjust
+        self.ignore_na = ignore_na
+        self.times = times
+        if self.times is not None:
+            if not self.adjust:
+                raise NotImplementedError("times is not supported with adjust=False.")
+            times_dtype = getattr(self.times, "dtype", None)
+            if not (
+                is_datetime64_dtype(times_dtype)
+                or isinstance(times_dtype, DatetimeTZDtype)
+            ):
+                raise ValueError("times must be datetime64 dtype.")
+            if len(self.times) != len(obj):
+                raise ValueError("times must be the same length as the object.")
+            if not isinstance(self.halflife, (str, datetime.timedelta, np.timedelta64)):
+                raise ValueError("halflife must be a timedelta convertible object")
+            if isna(self.times).any():
+                raise ValueError("Cannot convert NaT values to integer")
+            self._deltas = _calculate_deltas(self.times, self.halflife)
+            # Halflife is no longer applicable when calculating COM
+            # But allow COM to still be calculated if the user passes other decay args
+            if common.count_not_none(self.com, self.span, self.alpha) > 0:
+                self._com = get_center_of_mass(self.com, self.span, None, self.alpha)
+            else:
+                self._com = 1.0
+        else:
+            if self.halflife is not None and isinstance(
+                self.halflife, (str, datetime.timedelta, np.timedelta64)
+            ):
+                raise ValueError(
+                    "halflife can only be a timedelta convertible argument if "
+                    "times is not None."
+                )
+            # Without times, points are equally spaced
+            self._deltas = np.ones(
+                max(self.obj.shape[self.axis] - 1, 0), dtype=np.float64
+            )
+            self._com = get_center_of_mass(
+                # error: Argument 3 to "get_center_of_mass" has incompatible type
+                # "Union[float, Any, None, timedelta64, signedinteger[_64Bit]]";
+                # expected "Optional[float]"
+                self.com,
+                self.span,
+                self.halflife,  # type: ignore[arg-type]
+                self.alpha,
+            )
+
+    def _check_window_bounds(
+        self, start: np.ndarray, end: np.ndarray, num_vals: int
+    ) -> None:
+        # emw algorithms are iterative with each point
+        # ExponentialMovingWindowIndexer "bounds" are the entire window
+        pass
+
+    def _get_window_indexer(self) -> BaseIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+        """
+        return ExponentialMovingWindowIndexer()
+
+    def online(
+        self, engine: str = "numba", engine_kwargs=None
+    ) -> OnlineExponentialMovingWindow:
+        """
+        Return an ``OnlineExponentialMovingWindow`` object to calculate
+        exponentially moving window aggregations in an online method.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        engine: str, default ``'numba'``
+            Execution engine to calculate online aggregations.
+            Applies to all supported aggregation methods.
+
+        engine_kwargs : dict, default None
+            Applies to all supported aggregation methods.
+
+            * For ``'numba'`` engine, the engine can accept ``nopython``, ``nogil``
+              and ``parallel`` dictionary keys. The values must either be ``True`` or
+              ``False``. The default ``engine_kwargs`` for the ``'numba'`` engine is
+              ``{{'nopython': True, 'nogil': False, 'parallel': False}}`` and will be
+              applied to the function
+
+        Returns
+        -------
+        OnlineExponentialMovingWindow
+        """
+        return OnlineExponentialMovingWindow(
+            obj=self.obj,
+            com=self.com,
+            span=self.span,
+            halflife=self.halflife,
+            alpha=self.alpha,
+            min_periods=self.min_periods,
+            adjust=self.adjust,
+            ignore_na=self.ignore_na,
+            axis=self.axis,
+            times=self.times,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+            selection=self._selection,
+        )
+
+    @doc(
+        _shared_docs["aggregate"],
+        see_also=dedent(
+            """
+        See Also
+        --------
+        pandas.DataFrame.rolling.aggregate
+        """
+        ),
+        examples=dedent(
+            """
+        Examples
+        --------
+        >>> df = pd.DataFrame({"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.ewm(alpha=0.5).mean()
+                  A         B         C
+        0  1.000000  4.000000  7.000000
+        1  1.666667  4.666667  7.666667
+        2  2.428571  5.428571  8.428571
+        """
+        ),
+        klass="Series/Dataframe",
+        axis="",
+    )
+    def aggregate(self, func, *args, **kwargs):
+        return super().aggregate(func, *args, **kwargs)
+
+    agg = aggregate
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4])
+        >>> ser.ewm(alpha=.2).mean()
+        0    1.000000
+        1    1.555556
+        2    2.147541
+        3    2.775068
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) mean",
+        agg_method="mean",
+    )
+    def mean(
+        self,
+        numeric_only: bool = False,
+        engine=None,
+        engine_kwargs=None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "single":
+                func = generate_numba_ewm_func
+            else:
+                func = generate_numba_ewm_table_func
+            ewm_func = func(
+                **get_jit_arguments(engine_kwargs),
+                com=self._com,
+                adjust=self.adjust,
+                ignore_na=self.ignore_na,
+                deltas=tuple(self._deltas),
+                normalize=True,
+            )
+            return self._apply(ewm_func, name="mean")
+        elif engine in ("cython", None):
+            if engine_kwargs is not None:
+                raise ValueError("cython engine does not accept engine_kwargs")
+
+            deltas = None if self.times is None else self._deltas
+            window_func = partial(
+                window_aggregations.ewm,
+                com=self._com,
+                adjust=self.adjust,
+                ignore_na=self.ignore_na,
+                deltas=deltas,
+                normalize=True,
+            )
+            return self._apply(window_func, name="mean", numeric_only=numeric_only)
+        else:
+            raise ValueError("engine must be either 'numba' or 'cython'")
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4])
+        >>> ser.ewm(alpha=.2).sum()
+        0    1.000
+        1    2.800
+        2    5.240
+        3    8.192
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) sum",
+        agg_method="sum",
+    )
+    def sum(
+        self,
+        numeric_only: bool = False,
+        engine=None,
+        engine_kwargs=None,
+    ):
+        if not self.adjust:
+            raise NotImplementedError("sum is not implemented with adjust=False")
+        if maybe_use_numba(engine):
+            if self.method == "single":
+                func = generate_numba_ewm_func
+            else:
+                func = generate_numba_ewm_table_func
+            ewm_func = func(
+                **get_jit_arguments(engine_kwargs),
+                com=self._com,
+                adjust=self.adjust,
+                ignore_na=self.ignore_na,
+                deltas=tuple(self._deltas),
+                normalize=False,
+            )
+            return self._apply(ewm_func, name="sum")
+        elif engine in ("cython", None):
+            if engine_kwargs is not None:
+                raise ValueError("cython engine does not accept engine_kwargs")
+
+            deltas = None if self.times is None else self._deltas
+            window_func = partial(
+                window_aggregations.ewm,
+                com=self._com,
+                adjust=self.adjust,
+                ignore_na=self.ignore_na,
+                deltas=deltas,
+                normalize=False,
+            )
+            return self._apply(window_func, name="sum", numeric_only=numeric_only)
+        else:
+            raise ValueError("engine must be either 'numba' or 'cython'")
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """\
+        bias : bool, default False
+            Use a standard estimation bias correction.
+        """
+        ),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4])
+        >>> ser.ewm(alpha=.2).std()
+        0         NaN
+        1    0.707107
+        2    0.995893
+        3    1.277320
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) standard deviation",
+        agg_method="std",
+    )
+    def std(self, bias: bool = False, numeric_only: bool = False):
+        if (
+            numeric_only
+            and self._selected_obj.ndim == 1
+            and not is_numeric_dtype(self._selected_obj.dtype)
+        ):
+            # Raise directly so error message says std instead of var
+            raise NotImplementedError(
+                f"{type(self).__name__}.std does not implement numeric_only"
+            )
+        return zsqrt(self.var(bias=bias, numeric_only=numeric_only))
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """\
+        bias : bool, default False
+            Use a standard estimation bias correction.
+        """
+        ),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4])
+        >>> ser.ewm(alpha=.2).var()
+        0         NaN
+        1    0.500000
+        2    0.991803
+        3    1.631547
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) variance",
+        agg_method="var",
+    )
+    def var(self, bias: bool = False, numeric_only: bool = False):
+        window_func = window_aggregations.ewmcov
+        wfunc = partial(
+            window_func,
+            com=self._com,
+            adjust=self.adjust,
+            ignore_na=self.ignore_na,
+            bias=bias,
+        )
+
+        def var_func(values, begin, end, min_periods):
+            return wfunc(values, begin, end, min_periods, values)
+
+        return self._apply(var_func, name="var", numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """\
+        other : Series or DataFrame , optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndex DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        bias : bool, default False
+            Use a standard estimation bias correction.
+        """
+        ),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser1 = pd.Series([1, 2, 3, 4])
+        >>> ser2 = pd.Series([10, 11, 13, 16])
+        >>> ser1.ewm(alpha=.2).cov(ser2)
+        0         NaN
+        1    0.500000
+        2    1.524590
+        3    3.408836
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) sample covariance",
+        agg_method="cov",
+    )
+    def cov(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        bias: bool = False,
+        numeric_only: bool = False,
+    ):
+        from pandas import Series
+
+        self._validate_numeric_only("cov", numeric_only)
+
+        def cov_func(x, y):
+            x_array = self._prep_values(x)
+            y_array = self._prep_values(y)
+            window_indexer = self._get_window_indexer()
+            min_periods = (
+                self.min_periods
+                if self.min_periods is not None
+                else window_indexer.window_size
+            )
+            start, end = window_indexer.get_window_bounds(
+                num_values=len(x_array),
+                min_periods=min_periods,
+                center=self.center,
+                closed=self.closed,
+                step=self.step,
+            )
+            result = window_aggregations.ewmcov(
+                x_array,
+                start,
+                end,
+                # error: Argument 4 to "ewmcov" has incompatible type
+                # "Optional[int]"; expected "int"
+                self.min_periods,  # type: ignore[arg-type]
+                y_array,
+                self._com,
+                self.adjust,
+                self.ignore_na,
+                bias,
+            )
+            return Series(result, index=x.index, name=x.name, copy=False)
+
+        return self._apply_pairwise(
+            self._selected_obj, other, pairwise, cov_func, numeric_only
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """\
+        other : Series or DataFrame, optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndex DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        """
+        ),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser1 = pd.Series([1, 2, 3, 4])
+        >>> ser2 = pd.Series([10, 11, 13, 16])
+        >>> ser1.ewm(alpha=.2).corr(ser2)
+        0         NaN
+        1    1.000000
+        2    0.982821
+        3    0.977802
+        dtype: float64
+        """
+        ),
+        window_method="ewm",
+        aggregation_description="(exponential weighted moment) sample correlation",
+        agg_method="corr",
+    )
+    def corr(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        numeric_only: bool = False,
+    ):
+        from pandas import Series
+
+        self._validate_numeric_only("corr", numeric_only)
+
+        def cov_func(x, y):
+            x_array = self._prep_values(x)
+            y_array = self._prep_values(y)
+            window_indexer = self._get_window_indexer()
+            min_periods = (
+                self.min_periods
+                if self.min_periods is not None
+                else window_indexer.window_size
+            )
+            start, end = window_indexer.get_window_bounds(
+                num_values=len(x_array),
+                min_periods=min_periods,
+                center=self.center,
+                closed=self.closed,
+                step=self.step,
+            )
+
+            def _cov(X, Y):
+                return window_aggregations.ewmcov(
+                    X,
+                    start,
+                    end,
+                    min_periods,
+                    Y,
+                    self._com,
+                    self.adjust,
+                    self.ignore_na,
+                    True,
+                )
+
+            with np.errstate(all="ignore"):
+                cov = _cov(x_array, y_array)
+                x_var = _cov(x_array, x_array)
+                y_var = _cov(y_array, y_array)
+                result = cov / zsqrt(x_var * y_var)
+            return Series(result, index=x.index, name=x.name, copy=False)
+
+        return self._apply_pairwise(
+            self._selected_obj, other, pairwise, cov_func, numeric_only
+        )
+
+
+class ExponentialMovingWindowGroupby(BaseWindowGroupby, ExponentialMovingWindow):
+    """
+    Provide an exponential moving window groupby implementation.
+    """
+
+    _attributes = ExponentialMovingWindow._attributes + BaseWindowGroupby._attributes
+
+    def __init__(self, obj, *args, _grouper=None, **kwargs) -> None:
+        super().__init__(obj, *args, _grouper=_grouper, **kwargs)
+
+        if not obj.empty and self.times is not None:
+            # sort the times and recalculate the deltas according to the groups
+            groupby_order = np.concatenate(list(self._grouper.indices.values()))
+            self._deltas = _calculate_deltas(
+                self.times.take(groupby_order),
+                self.halflife,
+            )
+
+    def _get_window_indexer(self) -> GroupbyIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+
+        Returns
+        -------
+        GroupbyIndexer
+        """
+        window_indexer = GroupbyIndexer(
+            groupby_indices=self._grouper.indices,
+            window_indexer=ExponentialMovingWindowIndexer,
+        )
+        return window_indexer
+
+
+class OnlineExponentialMovingWindow(ExponentialMovingWindow):
+    def __init__(
+        self,
+        obj: NDFrame,
+        com: float | None = None,
+        span: float | None = None,
+        halflife: float | TimedeltaConvertibleTypes | None = None,
+        alpha: float | None = None,
+        min_periods: int | None = 0,
+        adjust: bool = True,
+        ignore_na: bool = False,
+        axis: Axis = 0,
+        times: np.ndarray | NDFrame | None = None,
+        engine: str = "numba",
+        engine_kwargs: dict[str, bool] | None = None,
+        *,
+        selection=None,
+    ) -> None:
+        if times is not None:
+            raise NotImplementedError(
+                "times is not implemented with online operations."
+            )
+        super().__init__(
+            obj=obj,
+            com=com,
+            span=span,
+            halflife=halflife,
+            alpha=alpha,
+            min_periods=min_periods,
+            adjust=adjust,
+            ignore_na=ignore_na,
+            axis=axis,
+            times=times,
+            selection=selection,
+        )
+        self._mean = EWMMeanState(
+            self._com, self.adjust, self.ignore_na, self.axis, obj.shape
+        )
+        if maybe_use_numba(engine):
+            self.engine = engine
+            self.engine_kwargs = engine_kwargs
+        else:
+            raise ValueError("'numba' is the only supported engine")
+
+    def reset(self) -> None:
+        """
+        Reset the state captured by `update` calls.
+        """
+        self._mean.reset()
+
+    def aggregate(self, func, *args, **kwargs):
+        raise NotImplementedError("aggregate is not implemented.")
+
+    def std(self, bias: bool = False, *args, **kwargs):
+        raise NotImplementedError("std is not implemented.")
+
+    def corr(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        numeric_only: bool = False,
+    ):
+        raise NotImplementedError("corr is not implemented.")
+
+    def cov(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        bias: bool = False,
+        numeric_only: bool = False,
+    ):
+        raise NotImplementedError("cov is not implemented.")
+
+    def var(self, bias: bool = False, numeric_only: bool = False):
+        raise NotImplementedError("var is not implemented.")
+
+    def mean(self, *args, update=None, update_times=None, **kwargs):
+        """
+        Calculate an online exponentially weighted mean.
+
+        Parameters
+        ----------
+        update: DataFrame or Series, default None
+            New values to continue calculating the
+            exponentially weighted mean from the last values and weights.
+            Values should be float64 dtype.
+
+            ``update`` needs to be ``None`` the first time the
+            exponentially weighted mean is calculated.
+
+        update_times: Series or 1-D np.ndarray, default None
+            New times to continue calculating the
+            exponentially weighted mean from the last values and weights.
+            If ``None``, values are assumed to be evenly spaced
+            in time.
+            This feature is currently unsupported.
+
+        Returns
+        -------
+        DataFrame or Series
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"a": range(5), "b": range(5, 10)})
+        >>> online_ewm = df.head(2).ewm(0.5).online()
+        >>> online_ewm.mean()
+              a     b
+        0  0.00  5.00
+        1  0.75  5.75
+        >>> online_ewm.mean(update=df.tail(3))
+                  a         b
+        2  1.615385  6.615385
+        3  2.550000  7.550000
+        4  3.520661  8.520661
+        >>> online_ewm.reset()
+        >>> online_ewm.mean()
+              a     b
+        0  0.00  5.00
+        1  0.75  5.75
+        """
+        result_kwargs = {}
+        is_frame = self._selected_obj.ndim == 2
+        if update_times is not None:
+            raise NotImplementedError("update_times is not implemented.")
+        update_deltas = np.ones(
+            max(self._selected_obj.shape[self.axis - 1] - 1, 0), dtype=np.float64
+        )
+        if update is not None:
+            if self._mean.last_ewm is None:
+                raise ValueError(
+                    "Must call mean with update=None first before passing update"
+                )
+            result_from = 1
+            result_kwargs["index"] = update.index
+            if is_frame:
+                last_value = self._mean.last_ewm[np.newaxis, :]
+                result_kwargs["columns"] = update.columns
+            else:
+                last_value = self._mean.last_ewm
+                result_kwargs["name"] = update.name
+            np_array = np.concatenate((last_value, update.to_numpy()))
+        else:
+            result_from = 0
+            result_kwargs["index"] = self._selected_obj.index
+            if is_frame:
+                result_kwargs["columns"] = self._selected_obj.columns
+            else:
+                result_kwargs["name"] = self._selected_obj.name
+            np_array = self._selected_obj.astype(np.float64, copy=False).to_numpy()
+        ewma_func = generate_online_numba_ewma_func(
+            **get_jit_arguments(self.engine_kwargs)
+        )
+        result = self._mean.run_ewm(
+            np_array if is_frame else np_array[:, np.newaxis],
+            update_deltas,
+            self.min_periods,
+            ewma_func,
+        )
+        if not is_frame:
+            result = result.squeeze()
+        result = result[result_from:]
+        result = self._selected_obj._constructor(result, **result_kwargs)
+        return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/expanding.py b/.venv/lib/python3.13/site-packages/pandas/core/window/expanding.py
new file mode 100644
index 0000000000000000000000000000000000000000..aac10596ffc699c2b229f959b9c1b26393384b03
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/expanding.py
@@ -0,0 +1,964 @@
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+)
+
+from pandas.util._decorators import (
+    deprecate_kwarg,
+    doc,
+)
+
+from pandas.core.indexers.objects import (
+    BaseIndexer,
+    ExpandingIndexer,
+    GroupbyIndexer,
+)
+from pandas.core.window.doc import (
+    _shared_docs,
+    create_section_header,
+    kwargs_numeric_only,
+    numba_notes,
+    template_header,
+    template_returns,
+    template_see_also,
+    window_agg_numba_parameters,
+    window_apply_parameters,
+)
+from pandas.core.window.rolling import (
+    BaseWindowGroupby,
+    RollingAndExpandingMixin,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        Axis,
+        QuantileInterpolation,
+        WindowingRankType,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.generic import NDFrame
+
+
+class Expanding(RollingAndExpandingMixin):
+    """
+    Provide expanding window calculations.
+
+    Parameters
+    ----------
+    min_periods : int, default 1
+        Minimum number of observations in window required to have a value;
+        otherwise, result is ``np.nan``.
+
+    axis : int or str, default 0
+        If ``0`` or ``'index'``, roll across the rows.
+
+        If ``1`` or ``'columns'``, roll across the columns.
+
+        For `Series` this parameter is unused and defaults to 0.
+
+    method : str {'single', 'table'}, default 'single'
+        Execute the rolling operation per single column or row (``'single'``)
+        or over the entire object (``'table'``).
+
+        This argument is only implemented when specifying ``engine='numba'``
+        in the method call.
+
+        .. versionadded:: 1.3.0
+
+    Returns
+    -------
+    pandas.api.typing.Expanding
+
+    See Also
+    --------
+    rolling : Provides rolling window calculations.
+    ewm : Provides exponential weighted functions.
+
+    Notes
+    -----
+    See :ref:`Windowing Operations ` for further usage details
+    and examples.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"B": [0, 1, 2, np.nan, 4]})
+    >>> df
+         B
+    0  0.0
+    1  1.0
+    2  2.0
+    3  NaN
+    4  4.0
+
+    **min_periods**
+
+    Expanding sum with 1 vs 3 observations needed to calculate a value.
+
+    >>> df.expanding(1).sum()
+         B
+    0  0.0
+    1  1.0
+    2  3.0
+    3  3.0
+    4  7.0
+    >>> df.expanding(3).sum()
+         B
+    0  NaN
+    1  NaN
+    2  3.0
+    3  3.0
+    4  7.0
+    """
+
+    _attributes: list[str] = ["min_periods", "axis", "method"]
+
+    def __init__(
+        self,
+        obj: NDFrame,
+        min_periods: int = 1,
+        axis: Axis = 0,
+        method: str = "single",
+        selection=None,
+    ) -> None:
+        super().__init__(
+            obj=obj,
+            min_periods=min_periods,
+            axis=axis,
+            method=method,
+            selection=selection,
+        )
+
+    def _get_window_indexer(self) -> BaseIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+        """
+        return ExpandingIndexer()
+
+    @doc(
+        _shared_docs["aggregate"],
+        see_also=dedent(
+            """
+        See Also
+        --------
+        pandas.DataFrame.aggregate : Similar DataFrame method.
+        pandas.Series.aggregate : Similar Series method.
+        """
+        ),
+        examples=dedent(
+            """
+        Examples
+        --------
+        >>> df = pd.DataFrame({"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.ewm(alpha=0.5).mean()
+                  A         B         C
+        0  1.000000  4.000000  7.000000
+        1  1.666667  4.666667  7.666667
+        2  2.428571  5.428571  8.428571
+        """
+        ),
+        klass="Series/Dataframe",
+        axis="",
+    )
+    def aggregate(self, func, *args, **kwargs):
+        return super().aggregate(func, *args, **kwargs)
+
+    agg = aggregate
+
+    @doc(
+        template_header,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().count()
+        a    1.0
+        b    2.0
+        c    3.0
+        d    4.0
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="count of non NaN observations",
+        agg_method="count",
+    )
+    def count(self, numeric_only: bool = False):
+        return super().count(numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        window_apply_parameters,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().apply(lambda s: s.max() - 2 * s.min())
+        a   -1.0
+        b    0.0
+        c    1.0
+        d    2.0
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="custom aggregation function",
+        agg_method="apply",
+    )
+    def apply(
+        self,
+        func: Callable[..., Any],
+        raw: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+    ):
+        return super().apply(
+            func,
+            raw=raw,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().sum()
+        a     1.0
+        b     3.0
+        c     6.0
+        d    10.0
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="sum",
+        agg_method="sum",
+    )
+    def sum(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().sum(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([3, 2, 1, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().max()
+        a    3.0
+        b    3.0
+        c    3.0
+        d    4.0
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="maximum",
+        agg_method="max",
+    )
+    def max(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().max(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([2, 3, 4, 1], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().min()
+        a    2.0
+        b    2.0
+        c    2.0
+        d    1.0
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="minimum",
+        agg_method="min",
+    )
+    def min(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().min(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().mean()
+        a    1.0
+        b    1.5
+        c    2.0
+        d    2.5
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="mean",
+        agg_method="mean",
+    )
+    def mean(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().mean(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser.expanding().median()
+        a    1.0
+        b    1.5
+        c    2.0
+        d    2.5
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="median",
+        agg_method="median",
+    )
+    def median(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().median(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.\n
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        window_agg_numba_parameters("1.4"),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "numpy.std : Equivalent method for NumPy array.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        The default ``ddof`` of 1 used in :meth:`Series.std` is different
+        than the default ``ddof`` of 0 in :func:`numpy.std`.
+
+        A minimum of one period is required for the rolling calculation.\n
+        """
+        ).replace("\n", "", 1),
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5])
+
+        >>> s.expanding(3).std()
+        0         NaN
+        1         NaN
+        2    0.577350
+        3    0.957427
+        4    0.894427
+        5    0.836660
+        6    0.786796
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="expanding",
+        aggregation_description="standard deviation",
+        agg_method="std",
+    )
+    def std(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().std(
+            ddof=ddof,
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.\n
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        window_agg_numba_parameters("1.4"),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "numpy.var : Equivalent method for NumPy array.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        The default ``ddof`` of 1 used in :meth:`Series.var` is different
+        than the default ``ddof`` of 0 in :func:`numpy.var`.
+
+        A minimum of one period is required for the rolling calculation.\n
+        """
+        ).replace("\n", "", 1),
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5])
+
+        >>> s.expanding(3).var()
+        0         NaN
+        1         NaN
+        2    0.333333
+        3    0.916667
+        4    0.800000
+        5    0.700000
+        6    0.619048
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="expanding",
+        aggregation_description="variance",
+        agg_method="var",
+    )
+    def var(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().var(
+            ddof=ddof,
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.\n
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        "A minimum of one period is required for the calculation.\n\n",
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([0, 1, 2, 3])
+
+        >>> s.expanding().sem()
+        0         NaN
+        1    0.707107
+        2    0.707107
+        3    0.745356
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="expanding",
+        aggregation_description="standard error of mean",
+        agg_method="sem",
+    )
+    def sem(self, ddof: int = 1, numeric_only: bool = False):
+        return super().sem(ddof=ddof, numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "scipy.stats.skew : Third moment of a probability density.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        "A minimum of three periods is required for the rolling calculation.\n\n",
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([-1, 0, 2, -1, 2], index=['a', 'b', 'c', 'd', 'e'])
+        >>> ser.expanding().skew()
+        a         NaN
+        b         NaN
+        c    0.935220
+        d    1.414214
+        e    0.315356
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="unbiased skewness",
+        agg_method="skew",
+    )
+    def skew(self, numeric_only: bool = False):
+        return super().skew(numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "scipy.stats.kurtosis : Reference SciPy method.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        "A minimum of four periods is required for the calculation.\n\n",
+        create_section_header("Examples"),
+        dedent(
+            """
+        The example below will show a rolling calculation with a window size of
+        four matching the equivalent function call using `scipy.stats`.
+
+        >>> arr = [1, 2, 3, 4, 999]
+        >>> import scipy.stats
+        >>> print(f"{{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}}")
+        -1.200000
+        >>> print(f"{{scipy.stats.kurtosis(arr, bias=False):.6f}}")
+        4.999874
+        >>> s = pd.Series(arr)
+        >>> s.expanding(4).kurt()
+        0         NaN
+        1         NaN
+        2         NaN
+        3   -1.200000
+        4    4.999874
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="expanding",
+        aggregation_description="Fisher's definition of kurtosis without bias",
+        agg_method="kurt",
+    )
+    def kurt(self, numeric_only: bool = False):
+        return super().kurt(numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        quantile : float
+            Quantile to compute. 0 <= quantile <= 1.
+
+            .. deprecated:: 2.1.0
+                This will be renamed to 'q' in a future version.
+        interpolation : {{'linear', 'lower', 'higher', 'midpoint', 'nearest'}}
+            This optional parameter specifies the interpolation method to use,
+            when the desired quantile lies between two data points `i` and `j`:
+
+                * linear: `i + (j - i) * fraction`, where `fraction` is the
+                  fractional part of the index surrounded by `i` and `j`.
+                * lower: `i`.
+                * higher: `j`.
+                * nearest: `i` or `j` whichever is nearest.
+                * midpoint: (`i` + `j`) / 2.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4, 5, 6], index=['a', 'b', 'c', 'd', 'e', 'f'])
+        >>> ser.expanding(min_periods=4).quantile(.25)
+        a     NaN
+        b     NaN
+        c     NaN
+        d    1.75
+        e    2.00
+        f    2.25
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="quantile",
+        agg_method="quantile",
+    )
+    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q")
+    def quantile(
+        self,
+        q: float,
+        interpolation: QuantileInterpolation = "linear",
+        numeric_only: bool = False,
+    ):
+        return super().quantile(
+            q=q,
+            interpolation=interpolation,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        ".. versionadded:: 1.4.0 \n\n",
+        create_section_header("Parameters"),
+        dedent(
+            """
+        method : {{'average', 'min', 'max'}}, default 'average'
+            How to rank the group of records that have the same value (i.e. ties):
+
+            * average: average rank of the group
+            * min: lowest rank in the group
+            * max: highest rank in the group
+
+        ascending : bool, default True
+            Whether or not the elements should be ranked in ascending order.
+        pct : bool, default False
+            Whether or not to display the returned rankings in percentile
+            form.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([1, 4, 2, 3, 5, 3])
+        >>> s.expanding().rank()
+        0    1.0
+        1    2.0
+        2    2.0
+        3    3.0
+        4    5.0
+        5    3.5
+        dtype: float64
+
+        >>> s.expanding().rank(method="max")
+        0    1.0
+        1    2.0
+        2    2.0
+        3    3.0
+        4    5.0
+        5    4.0
+        dtype: float64
+
+        >>> s.expanding().rank(method="min")
+        0    1.0
+        1    2.0
+        2    2.0
+        3    3.0
+        4    5.0
+        5    3.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="expanding",
+        aggregation_description="rank",
+        agg_method="rank",
+    )
+    def rank(
+        self,
+        method: WindowingRankType = "average",
+        ascending: bool = True,
+        pct: bool = False,
+        numeric_only: bool = False,
+    ):
+        return super().rank(
+            method=method,
+            ascending=ascending,
+            pct=pct,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        other : Series or DataFrame, optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndexed DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser1 = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser2 = pd.Series([10, 11, 13, 16], index=['a', 'b', 'c', 'd'])
+        >>> ser1.expanding().cov(ser2)
+        a         NaN
+        b    0.500000
+        c    1.500000
+        d    3.333333
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="sample covariance",
+        agg_method="cov",
+    )
+    def cov(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        return super().cov(
+            other=other,
+            pairwise=pairwise,
+            ddof=ddof,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        other : Series or DataFrame, optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndexed DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        dedent(
+            """
+        cov : Similar method to calculate covariance.
+        numpy.corrcoef : NumPy Pearson's correlation calculation.
+        """
+        ).replace("\n", "", 1),
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        This function uses Pearson's definition of correlation
+        (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient).
+
+        When `other` is not specified, the output will be self correlation (e.g.
+        all 1's), except for :class:`~pandas.DataFrame` inputs with `pairwise`
+        set to `True`.
+
+        Function will return ``NaN`` for correlations of equal valued sequences;
+        this is the result of a 0/0 division error.
+
+        When `pairwise` is set to `False`, only matching columns between `self` and
+        `other` will be used.
+
+        When `pairwise` is set to `True`, the output will be a MultiIndex DataFrame
+        with the original index on the first level, and the `other` DataFrame
+        columns on the second level.
+
+        In the case of missing elements, only complete pairwise observations
+        will be used.\n
+        """
+        ),
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser1 = pd.Series([1, 2, 3, 4], index=['a', 'b', 'c', 'd'])
+        >>> ser2 = pd.Series([10, 11, 13, 16], index=['a', 'b', 'c', 'd'])
+        >>> ser1.expanding().corr(ser2)
+        a         NaN
+        b    1.000000
+        c    0.981981
+        d    0.975900
+        dtype: float64
+        """
+        ),
+        window_method="expanding",
+        aggregation_description="correlation",
+        agg_method="corr",
+    )
+    def corr(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        return super().corr(
+            other=other,
+            pairwise=pairwise,
+            ddof=ddof,
+            numeric_only=numeric_only,
+        )
+
+
+class ExpandingGroupby(BaseWindowGroupby, Expanding):
+    """
+    Provide a expanding groupby implementation.
+    """
+
+    _attributes = Expanding._attributes + BaseWindowGroupby._attributes
+
+    def _get_window_indexer(self) -> GroupbyIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+
+        Returns
+        -------
+        GroupbyIndexer
+        """
+        window_indexer = GroupbyIndexer(
+            groupby_indices=self._grouper.indices,
+            window_indexer=ExpandingIndexer,
+        )
+        return window_indexer
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/numba_.py b/.venv/lib/python3.13/site-packages/pandas/core/window/numba_.py
new file mode 100644
index 0000000000000000000000000000000000000000..9357945e78c631a3fada24ec3015ca0cf183b99c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/numba_.py
@@ -0,0 +1,351 @@
+from __future__ import annotations
+
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+
+from pandas.core.util.numba_ import jit_user_function
+
+if TYPE_CHECKING:
+    from pandas._typing import Scalar
+
+
+@functools.cache
+def generate_numba_apply_func(
+    func: Callable[..., Scalar],
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+):
+    """
+    Generate a numba jitted apply function specified by values from engine_kwargs.
+
+    1. jit the user's function
+    2. Return a rolling apply function with the jitted function inline
+
+    Configurations specified in engine_kwargs apply to both the user's
+    function _AND_ the rolling apply function.
+
+    Parameters
+    ----------
+    func : function
+        function to be applied to each window and will be JITed
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+    numba_func = jit_user_function(func)
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def roll_apply(
+        values: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        minimum_periods: int,
+        *args: Any,
+    ) -> np.ndarray:
+        result = np.empty(len(begin))
+        for i in numba.prange(len(result)):
+            start = begin[i]
+            stop = end[i]
+            window = values[start:stop]
+            count_nan = np.sum(np.isnan(window))
+            if len(window) - count_nan >= minimum_periods:
+                result[i] = numba_func(window, *args)
+            else:
+                result[i] = np.nan
+        return result
+
+    return roll_apply
+
+
+@functools.cache
+def generate_numba_ewm_func(
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+    com: float,
+    adjust: bool,
+    ignore_na: bool,
+    deltas: tuple,
+    normalize: bool,
+):
+    """
+    Generate a numba jitted ewm mean or sum function specified by values
+    from engine_kwargs.
+
+    Parameters
+    ----------
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+    com : float
+    adjust : bool
+    ignore_na : bool
+    deltas : tuple
+    normalize : bool
+
+    Returns
+    -------
+    Numba function
+    """
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def ewm(
+        values: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        minimum_periods: int,
+    ) -> np.ndarray:
+        result = np.empty(len(values))
+        alpha = 1.0 / (1.0 + com)
+        old_wt_factor = 1.0 - alpha
+        new_wt = 1.0 if adjust else alpha
+
+        for i in numba.prange(len(begin)):
+            start = begin[i]
+            stop = end[i]
+            window = values[start:stop]
+            sub_result = np.empty(len(window))
+
+            weighted = window[0]
+            nobs = int(not np.isnan(weighted))
+            sub_result[0] = weighted if nobs >= minimum_periods else np.nan
+            old_wt = 1.0
+
+            for j in range(1, len(window)):
+                cur = window[j]
+                is_observation = not np.isnan(cur)
+                nobs += is_observation
+                if not np.isnan(weighted):
+                    if is_observation or not ignore_na:
+                        if normalize:
+                            # note that len(deltas) = len(vals) - 1 and deltas[i]
+                            # is to be used in conjunction with vals[i+1]
+                            old_wt *= old_wt_factor ** deltas[start + j - 1]
+                        else:
+                            weighted = old_wt_factor * weighted
+                        if is_observation:
+                            if normalize:
+                                # avoid numerical errors on constant series
+                                if weighted != cur:
+                                    weighted = old_wt * weighted + new_wt * cur
+                                    if normalize:
+                                        weighted = weighted / (old_wt + new_wt)
+                                if adjust:
+                                    old_wt += new_wt
+                                else:
+                                    old_wt = 1.0
+                            else:
+                                weighted += cur
+                elif is_observation:
+                    weighted = cur
+
+                sub_result[j] = weighted if nobs >= minimum_periods else np.nan
+
+            result[start:stop] = sub_result
+
+        return result
+
+    return ewm
+
+
+@functools.cache
+def generate_numba_table_func(
+    func: Callable[..., np.ndarray],
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+):
+    """
+    Generate a numba jitted function to apply window calculations table-wise.
+
+    Func will be passed a M window size x N number of columns array, and
+    must return a 1 x N number of columns array. Func is intended to operate
+    row-wise, but the result will be transposed for axis=1.
+
+    1. jit the user's function
+    2. Return a rolling apply function with the jitted function inline
+
+    Parameters
+    ----------
+    func : function
+        function to be applied to each window and will be JITed
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+    numba_func = jit_user_function(func)
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def roll_table(
+        values: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        minimum_periods: int,
+        *args: Any,
+    ):
+        result = np.empty((len(begin), values.shape[1]))
+        min_periods_mask = np.empty(result.shape)
+        for i in numba.prange(len(result)):
+            start = begin[i]
+            stop = end[i]
+            window = values[start:stop]
+            count_nan = np.sum(np.isnan(window), axis=0)
+            sub_result = numba_func(window, *args)
+            nan_mask = len(window) - count_nan >= minimum_periods
+            min_periods_mask[i, :] = nan_mask
+            result[i, :] = sub_result
+        result = np.where(min_periods_mask, result, np.nan)
+        return result
+
+    return roll_table
+
+
+# This function will no longer be needed once numba supports
+# axis for all np.nan* agg functions
+# https://github.com/numba/numba/issues/1269
+@functools.cache
+def generate_manual_numpy_nan_agg_with_axis(nan_func):
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=True, nogil=True, parallel=True)
+    def nan_agg_with_axis(table):
+        result = np.empty(table.shape[1])
+        for i in numba.prange(table.shape[1]):
+            partition = table[:, i]
+            result[i] = nan_func(partition)
+        return result
+
+    return nan_agg_with_axis
+
+
+@functools.cache
+def generate_numba_ewm_table_func(
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+    com: float,
+    adjust: bool,
+    ignore_na: bool,
+    deltas: tuple,
+    normalize: bool,
+):
+    """
+    Generate a numba jitted ewm mean or sum function applied table wise specified
+    by values from engine_kwargs.
+
+    Parameters
+    ----------
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+    com : float
+    adjust : bool
+    ignore_na : bool
+    deltas : tuple
+    normalize: bool
+
+    Returns
+    -------
+    Numba function
+    """
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def ewm_table(
+        values: np.ndarray,
+        begin: np.ndarray,
+        end: np.ndarray,
+        minimum_periods: int,
+    ) -> np.ndarray:
+        alpha = 1.0 / (1.0 + com)
+        old_wt_factor = 1.0 - alpha
+        new_wt = 1.0 if adjust else alpha
+        old_wt = np.ones(values.shape[1])
+
+        result = np.empty(values.shape)
+        weighted = values[0].copy()
+        nobs = (~np.isnan(weighted)).astype(np.int64)
+        result[0] = np.where(nobs >= minimum_periods, weighted, np.nan)
+        for i in range(1, len(values)):
+            cur = values[i]
+            is_observations = ~np.isnan(cur)
+            nobs += is_observations.astype(np.int64)
+            for j in numba.prange(len(cur)):
+                if not np.isnan(weighted[j]):
+                    if is_observations[j] or not ignore_na:
+                        if normalize:
+                            # note that len(deltas) = len(vals) - 1 and deltas[i]
+                            # is to be used in conjunction with vals[i+1]
+                            old_wt[j] *= old_wt_factor ** deltas[i - 1]
+                        else:
+                            weighted[j] = old_wt_factor * weighted[j]
+                        if is_observations[j]:
+                            if normalize:
+                                # avoid numerical errors on constant series
+                                if weighted[j] != cur[j]:
+                                    weighted[j] = (
+                                        old_wt[j] * weighted[j] + new_wt * cur[j]
+                                    )
+                                    if normalize:
+                                        weighted[j] = weighted[j] / (old_wt[j] + new_wt)
+                                if adjust:
+                                    old_wt[j] += new_wt
+                                else:
+                                    old_wt[j] = 1.0
+                            else:
+                                weighted[j] += cur[j]
+                elif is_observations[j]:
+                    weighted[j] = cur[j]
+
+            result[i] = np.where(nobs >= minimum_periods, weighted, np.nan)
+
+        return result
+
+    return ewm_table
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/online.py b/.venv/lib/python3.13/site-packages/pandas/core/window/online.py
new file mode 100644
index 0000000000000000000000000000000000000000..29d1f740e021fd30d3bfc7d72a5e6baefe62ac4c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/online.py
@@ -0,0 +1,118 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+
+
+def generate_online_numba_ewma_func(
+    nopython: bool,
+    nogil: bool,
+    parallel: bool,
+):
+    """
+    Generate a numba jitted groupby ewma function specified by values
+    from engine_kwargs.
+
+    Parameters
+    ----------
+    nopython : bool
+        nopython to be passed into numba.jit
+    nogil : bool
+        nogil to be passed into numba.jit
+    parallel : bool
+        parallel to be passed into numba.jit
+
+    Returns
+    -------
+    Numba function
+    """
+    if TYPE_CHECKING:
+        import numba
+    else:
+        numba = import_optional_dependency("numba")
+
+    @numba.jit(nopython=nopython, nogil=nogil, parallel=parallel)
+    def online_ewma(
+        values: np.ndarray,
+        deltas: np.ndarray,
+        minimum_periods: int,
+        old_wt_factor: float,
+        new_wt: float,
+        old_wt: np.ndarray,
+        adjust: bool,
+        ignore_na: bool,
+    ):
+        """
+        Compute online exponentially weighted mean per column over 2D values.
+
+        Takes the first observation as is, then computes the subsequent
+        exponentially weighted mean accounting minimum periods.
+        """
+        result = np.empty(values.shape)
+        weighted_avg = values[0].copy()
+        nobs = (~np.isnan(weighted_avg)).astype(np.int64)
+        result[0] = np.where(nobs >= minimum_periods, weighted_avg, np.nan)
+
+        for i in range(1, len(values)):
+            cur = values[i]
+            is_observations = ~np.isnan(cur)
+            nobs += is_observations.astype(np.int64)
+            for j in numba.prange(len(cur)):
+                if not np.isnan(weighted_avg[j]):
+                    if is_observations[j] or not ignore_na:
+                        # note that len(deltas) = len(vals) - 1 and deltas[i] is to be
+                        # used in conjunction with vals[i+1]
+                        old_wt[j] *= old_wt_factor ** deltas[j - 1]
+                        if is_observations[j]:
+                            # avoid numerical errors on constant series
+                            if weighted_avg[j] != cur[j]:
+                                weighted_avg[j] = (
+                                    (old_wt[j] * weighted_avg[j]) + (new_wt * cur[j])
+                                ) / (old_wt[j] + new_wt)
+                            if adjust:
+                                old_wt[j] += new_wt
+                            else:
+                                old_wt[j] = 1.0
+                elif is_observations[j]:
+                    weighted_avg[j] = cur[j]
+
+            result[i] = np.where(nobs >= minimum_periods, weighted_avg, np.nan)
+
+        return result, old_wt
+
+    return online_ewma
+
+
+class EWMMeanState:
+    def __init__(self, com, adjust, ignore_na, axis, shape) -> None:
+        alpha = 1.0 / (1.0 + com)
+        self.axis = axis
+        self.shape = shape
+        self.adjust = adjust
+        self.ignore_na = ignore_na
+        self.new_wt = 1.0 if adjust else alpha
+        self.old_wt_factor = 1.0 - alpha
+        self.old_wt = np.ones(self.shape[self.axis - 1])
+        self.last_ewm = None
+
+    def run_ewm(self, weighted_avg, deltas, min_periods, ewm_func):
+        result, old_wt = ewm_func(
+            weighted_avg,
+            deltas,
+            min_periods,
+            self.old_wt_factor,
+            self.new_wt,
+            self.old_wt,
+            self.adjust,
+            self.ignore_na,
+        )
+        self.old_wt = old_wt
+        self.last_ewm = result[-1]
+        return result
+
+    def reset(self) -> None:
+        self.old_wt = np.ones(self.shape[self.axis - 1])
+        self.last_ewm = None
diff --git a/.venv/lib/python3.13/site-packages/pandas/core/window/rolling.py b/.venv/lib/python3.13/site-packages/pandas/core/window/rolling.py
new file mode 100644
index 0000000000000000000000000000000000000000..68cec16ec9eca8b34fadd9e67221219ebd7fe736
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/core/window/rolling.py
@@ -0,0 +1,2930 @@
+"""
+Provide a generic structure to support window functions,
+similar to how we have a Groupby object.
+"""
+from __future__ import annotations
+
+import copy
+from datetime import timedelta
+from functools import partial
+import inspect
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._libs.tslibs import (
+    BaseOffset,
+    Timedelta,
+    to_offset,
+)
+import pandas._libs.window.aggregations as window_aggregations
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import DataError
+from pandas.util._decorators import (
+    deprecate_kwarg,
+    doc,
+)
+
+from pandas.core.dtypes.common import (
+    ensure_float64,
+    is_bool,
+    is_integer,
+    is_numeric_dtype,
+    needs_i8_conversion,
+)
+from pandas.core.dtypes.dtypes import ArrowDtype
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import notna
+
+from pandas.core._numba import executor
+from pandas.core.algorithms import factorize
+from pandas.core.apply import ResamplerWindowApply
+from pandas.core.arrays import ExtensionArray
+from pandas.core.base import SelectionMixin
+import pandas.core.common as com
+from pandas.core.indexers.objects import (
+    BaseIndexer,
+    FixedWindowIndexer,
+    GroupbyIndexer,
+    VariableWindowIndexer,
+)
+from pandas.core.indexes.api import (
+    DatetimeIndex,
+    Index,
+    MultiIndex,
+    PeriodIndex,
+    TimedeltaIndex,
+)
+from pandas.core.reshape.concat import concat
+from pandas.core.util.numba_ import (
+    get_jit_arguments,
+    maybe_use_numba,
+)
+from pandas.core.window.common import (
+    flex_binary_moment,
+    zsqrt,
+)
+from pandas.core.window.doc import (
+    _shared_docs,
+    create_section_header,
+    kwargs_numeric_only,
+    kwargs_scipy,
+    numba_notes,
+    template_header,
+    template_returns,
+    template_see_also,
+    window_agg_numba_parameters,
+    window_apply_parameters,
+)
+from pandas.core.window.numba_ import (
+    generate_manual_numpy_nan_agg_with_axis,
+    generate_numba_apply_func,
+    generate_numba_table_func,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterator,
+        Sized,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        Axis,
+        NDFrameT,
+        QuantileInterpolation,
+        WindowingRankType,
+        npt,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.generic import NDFrame
+    from pandas.core.groupby.ops import BaseGrouper
+
+from pandas.core.arrays.datetimelike import dtype_to_unit
+
+
+class BaseWindow(SelectionMixin):
+    """Provides utilities for performing windowing operations."""
+
+    _attributes: list[str] = []
+    exclusions: frozenset[Hashable] = frozenset()
+    _on: Index
+
+    def __init__(
+        self,
+        obj: NDFrame,
+        window=None,
+        min_periods: int | None = None,
+        center: bool | None = False,
+        win_type: str | None = None,
+        axis: Axis = 0,
+        on: str | Index | None = None,
+        closed: str | None = None,
+        step: int | None = None,
+        method: str = "single",
+        *,
+        selection=None,
+    ) -> None:
+        self.obj = obj
+        self.on = on
+        self.closed = closed
+        self.step = step
+        self.window = window
+        self.min_periods = min_periods
+        self.center = center
+        self.win_type = win_type
+        self.axis = obj._get_axis_number(axis) if axis is not None else None
+        self.method = method
+        self._win_freq_i8: int | None = None
+        if self.on is None:
+            if self.axis == 0:
+                self._on = self.obj.index
+            else:
+                # i.e. self.axis == 1
+                self._on = self.obj.columns
+        elif isinstance(self.on, Index):
+            self._on = self.on
+        elif isinstance(self.obj, ABCDataFrame) and self.on in self.obj.columns:
+            self._on = Index(self.obj[self.on])
+        else:
+            raise ValueError(
+                f"invalid on specified as {self.on}, "
+                "must be a column (of DataFrame), an Index or None"
+            )
+
+        self._selection = selection
+        self._validate()
+
+    def _validate(self) -> None:
+        if self.center is not None and not is_bool(self.center):
+            raise ValueError("center must be a boolean")
+        if self.min_periods is not None:
+            if not is_integer(self.min_periods):
+                raise ValueError("min_periods must be an integer")
+            if self.min_periods < 0:
+                raise ValueError("min_periods must be >= 0")
+            if is_integer(self.window) and self.min_periods > self.window:
+                raise ValueError(
+                    f"min_periods {self.min_periods} must be <= window {self.window}"
+                )
+        if self.closed is not None and self.closed not in [
+            "right",
+            "both",
+            "left",
+            "neither",
+        ]:
+            raise ValueError("closed must be 'right', 'left', 'both' or 'neither'")
+        if not isinstance(self.obj, (ABCSeries, ABCDataFrame)):
+            raise TypeError(f"invalid type: {type(self)}")
+        if isinstance(self.window, BaseIndexer):
+            # Validate that the passed BaseIndexer subclass has
+            # a get_window_bounds with the correct signature.
+            get_window_bounds_signature = inspect.signature(
+                self.window.get_window_bounds
+            ).parameters.keys()
+            expected_signature = inspect.signature(
+                BaseIndexer().get_window_bounds
+            ).parameters.keys()
+            if get_window_bounds_signature != expected_signature:
+                raise ValueError(
+                    f"{type(self.window).__name__} does not implement "
+                    f"the correct signature for get_window_bounds"
+                )
+        if self.method not in ["table", "single"]:
+            raise ValueError("method must be 'table' or 'single")
+        if self.step is not None:
+            if not is_integer(self.step):
+                raise ValueError("step must be an integer")
+            if self.step < 0:
+                raise ValueError("step must be >= 0")
+
+    def _check_window_bounds(
+        self, start: np.ndarray, end: np.ndarray, num_vals: int
+    ) -> None:
+        if len(start) != len(end):
+            raise ValueError(
+                f"start ({len(start)}) and end ({len(end)}) bounds must be the "
+                f"same length"
+            )
+        if len(start) != (num_vals + (self.step or 1) - 1) // (self.step or 1):
+            raise ValueError(
+                f"start and end bounds ({len(start)}) must be the same length "
+                f"as the object ({num_vals}) divided by the step ({self.step}) "
+                f"if given and rounded up"
+            )
+
+    def _slice_axis_for_step(self, index: Index, result: Sized | None = None) -> Index:
+        """
+        Slices the index for a given result and the preset step.
+        """
+        return (
+            index
+            if result is None or len(result) == len(index)
+            else index[:: self.step]
+        )
+
+    def _validate_numeric_only(self, name: str, numeric_only: bool) -> None:
+        """
+        Validate numeric_only argument, raising if invalid for the input.
+
+        Parameters
+        ----------
+        name : str
+            Name of the operator (kernel).
+        numeric_only : bool
+            Value passed by user.
+        """
+        if (
+            self._selected_obj.ndim == 1
+            and numeric_only
+            and not is_numeric_dtype(self._selected_obj.dtype)
+        ):
+            raise NotImplementedError(
+                f"{type(self).__name__}.{name} does not implement numeric_only"
+            )
+
+    def _make_numeric_only(self, obj: NDFrameT) -> NDFrameT:
+        """Subset DataFrame to numeric columns.
+
+        Parameters
+        ----------
+        obj : DataFrame
+
+        Returns
+        -------
+        obj subset to numeric-only columns.
+        """
+        result = obj.select_dtypes(include=["number"], exclude=["timedelta"])
+        return result
+
+    def _create_data(self, obj: NDFrameT, numeric_only: bool = False) -> NDFrameT:
+        """
+        Split data into blocks & return conformed data.
+        """
+        # filter out the on from the object
+        if self.on is not None and not isinstance(self.on, Index) and obj.ndim == 2:
+            obj = obj.reindex(columns=obj.columns.difference([self.on]), copy=False)
+        if obj.ndim > 1 and (numeric_only or self.axis == 1):
+            # GH: 20649 in case of mixed dtype and axis=1 we have to convert everything
+            # to float to calculate the complete row at once. We exclude all non-numeric
+            # dtypes.
+            obj = self._make_numeric_only(obj)
+        if self.axis == 1:
+            obj = obj.astype("float64", copy=False)
+            obj._mgr = obj._mgr.consolidate()
+        return obj
+
+    def _gotitem(self, key, ndim, subset=None):
+        """
+        Sub-classes to define. Return a sliced object.
+
+        Parameters
+        ----------
+        key : str / list of selections
+        ndim : {1, 2}
+            requested ndim of result
+        subset : object, default None
+            subset to act on
+        """
+        # create a new object to prevent aliasing
+        if subset is None:
+            subset = self.obj
+
+        # we need to make a shallow copy of ourselves
+        # with the same groupby
+        kwargs = {attr: getattr(self, attr) for attr in self._attributes}
+
+        selection = self._infer_selection(key, subset)
+        new_win = type(self)(subset, selection=selection, **kwargs)
+        return new_win
+
+    def __getattr__(self, attr: str):
+        if attr in self._internal_names_set:
+            return object.__getattribute__(self, attr)
+        if attr in self.obj:
+            return self[attr]
+
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{attr}'"
+        )
+
+    def _dir_additions(self):
+        return self.obj._dir_additions()
+
+    def __repr__(self) -> str:
+        """
+        Provide a nice str repr of our rolling object.
+        """
+        attrs_list = (
+            f"{attr_name}={getattr(self, attr_name)}"
+            for attr_name in self._attributes
+            if getattr(self, attr_name, None) is not None and attr_name[0] != "_"
+        )
+        attrs = ",".join(attrs_list)
+        return f"{type(self).__name__} [{attrs}]"
+
+    def __iter__(self) -> Iterator:
+        obj = self._selected_obj.set_axis(self._on)
+        obj = self._create_data(obj)
+        indexer = self._get_window_indexer()
+
+        start, end = indexer.get_window_bounds(
+            num_values=len(obj),
+            min_periods=self.min_periods,
+            center=self.center,
+            closed=self.closed,
+            step=self.step,
+        )
+        self._check_window_bounds(start, end, len(obj))
+
+        for s, e in zip(start, end):
+            result = obj.iloc[slice(s, e)]
+            yield result
+
+    def _prep_values(self, values: ArrayLike) -> np.ndarray:
+        """Convert input to numpy arrays for Cython routines"""
+        if needs_i8_conversion(values.dtype):
+            raise NotImplementedError(
+                f"ops for {type(self).__name__} for this "
+                f"dtype {values.dtype} are not implemented"
+            )
+        # GH #12373 : rolling functions error on float32 data
+        # make sure the data is coerced to float64
+        try:
+            if isinstance(values, ExtensionArray):
+                values = values.to_numpy(np.float64, na_value=np.nan)
+            else:
+                values = ensure_float64(values)
+        except (ValueError, TypeError) as err:
+            raise TypeError(f"cannot handle this type -> {values.dtype}") from err
+
+        # Convert inf to nan for C funcs
+        inf = np.isinf(values)
+        if inf.any():
+            values = np.where(inf, np.nan, values)
+
+        return values
+
+    def _insert_on_column(self, result: DataFrame, obj: DataFrame) -> None:
+        # if we have an 'on' column we want to put it back into
+        # the results in the same location
+        from pandas import Series
+
+        if self.on is not None and not self._on.equals(obj.index):
+            name = self._on.name
+            extra_col = Series(self._on, index=self.obj.index, name=name, copy=False)
+            if name in result.columns:
+                # TODO: sure we want to overwrite results?
+                result[name] = extra_col
+            elif name in result.index.names:
+                pass
+            elif name in self._selected_obj.columns:
+                # insert in the same location as we had in _selected_obj
+                old_cols = self._selected_obj.columns
+                new_cols = result.columns
+                old_loc = old_cols.get_loc(name)
+                overlap = new_cols.intersection(old_cols[:old_loc])
+                new_loc = len(overlap)
+                result.insert(new_loc, name, extra_col)
+            else:
+                # insert at the end
+                result[name] = extra_col
+
+    @property
+    def _index_array(self) -> npt.NDArray[np.int64] | None:
+        # TODO: why do we get here with e.g. MultiIndex?
+        if isinstance(self._on, (PeriodIndex, DatetimeIndex, TimedeltaIndex)):
+            return self._on.asi8
+        elif isinstance(self._on.dtype, ArrowDtype) and self._on.dtype.kind in "mM":
+            return self._on.to_numpy(dtype=np.int64)
+        return None
+
+    def _resolve_output(self, out: DataFrame, obj: DataFrame) -> DataFrame:
+        """Validate and finalize result."""
+        if out.shape[1] == 0 and obj.shape[1] > 0:
+            raise DataError("No numeric types to aggregate")
+        if out.shape[1] == 0:
+            return obj.astype("float64")
+
+        self._insert_on_column(out, obj)
+        return out
+
+    def _get_window_indexer(self) -> BaseIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+        """
+        if isinstance(self.window, BaseIndexer):
+            return self.window
+        if self._win_freq_i8 is not None:
+            return VariableWindowIndexer(
+                index_array=self._index_array,
+                window_size=self._win_freq_i8,
+                center=self.center,
+            )
+        return FixedWindowIndexer(window_size=self.window)
+
+    def _apply_series(
+        self, homogeneous_func: Callable[..., ArrayLike], name: str | None = None
+    ) -> Series:
+        """
+        Series version of _apply_columnwise
+        """
+        obj = self._create_data(self._selected_obj)
+
+        if name == "count":
+            # GH 12541: Special case for count where we support date-like types
+            obj = notna(obj).astype(int)
+        try:
+            values = self._prep_values(obj._values)
+        except (TypeError, NotImplementedError) as err:
+            raise DataError("No numeric types to aggregate") from err
+
+        result = homogeneous_func(values)
+        index = self._slice_axis_for_step(obj.index, result)
+        return obj._constructor(result, index=index, name=obj.name)
+
+    def _apply_columnwise(
+        self,
+        homogeneous_func: Callable[..., ArrayLike],
+        name: str,
+        numeric_only: bool = False,
+    ) -> DataFrame | Series:
+        """
+        Apply the given function to the DataFrame broken down into homogeneous
+        sub-frames.
+        """
+        self._validate_numeric_only(name, numeric_only)
+        if self._selected_obj.ndim == 1:
+            return self._apply_series(homogeneous_func, name)
+
+        obj = self._create_data(self._selected_obj, numeric_only)
+        if name == "count":
+            # GH 12541: Special case for count where we support date-like types
+            obj = notna(obj).astype(int)
+            obj._mgr = obj._mgr.consolidate()
+
+        if self.axis == 1:
+            obj = obj.T
+
+        taker = []
+        res_values = []
+        for i, arr in enumerate(obj._iter_column_arrays()):
+            # GH#42736 operate column-wise instead of block-wise
+            # As of 2.0, hfunc will raise for nuisance columns
+            try:
+                arr = self._prep_values(arr)
+            except (TypeError, NotImplementedError) as err:
+                raise DataError(
+                    f"Cannot aggregate non-numeric type: {arr.dtype}"
+                ) from err
+            res = homogeneous_func(arr)
+            res_values.append(res)
+            taker.append(i)
+
+        index = self._slice_axis_for_step(
+            obj.index, res_values[0] if len(res_values) > 0 else None
+        )
+        df = type(obj)._from_arrays(
+            res_values,
+            index=index,
+            columns=obj.columns.take(taker),
+            verify_integrity=False,
+        )
+
+        if self.axis == 1:
+            df = df.T
+
+        return self._resolve_output(df, obj)
+
+    def _apply_tablewise(
+        self,
+        homogeneous_func: Callable[..., ArrayLike],
+        name: str | None = None,
+        numeric_only: bool = False,
+    ) -> DataFrame | Series:
+        """
+        Apply the given function to the DataFrame across the entire object
+        """
+        if self._selected_obj.ndim == 1:
+            raise ValueError("method='table' not applicable for Series objects.")
+        obj = self._create_data(self._selected_obj, numeric_only)
+        values = self._prep_values(obj.to_numpy())
+        values = values.T if self.axis == 1 else values
+        result = homogeneous_func(values)
+        result = result.T if self.axis == 1 else result
+        index = self._slice_axis_for_step(obj.index, result)
+        columns = (
+            obj.columns
+            if result.shape[1] == len(obj.columns)
+            else obj.columns[:: self.step]
+        )
+        out = obj._constructor(result, index=index, columns=columns)
+
+        return self._resolve_output(out, obj)
+
+    def _apply_pairwise(
+        self,
+        target: DataFrame | Series,
+        other: DataFrame | Series | None,
+        pairwise: bool | None,
+        func: Callable[[DataFrame | Series, DataFrame | Series], DataFrame | Series],
+        numeric_only: bool,
+    ) -> DataFrame | Series:
+        """
+        Apply the given pairwise function given 2 pandas objects (DataFrame/Series)
+        """
+        target = self._create_data(target, numeric_only)
+        if other is None:
+            other = target
+            # only default unset
+            pairwise = True if pairwise is None else pairwise
+        elif not isinstance(other, (ABCDataFrame, ABCSeries)):
+            raise ValueError("other must be a DataFrame or Series")
+        elif other.ndim == 2 and numeric_only:
+            other = self._make_numeric_only(other)
+
+        return flex_binary_moment(target, other, func, pairwise=bool(pairwise))
+
+    def _apply(
+        self,
+        func: Callable[..., Any],
+        name: str,
+        numeric_only: bool = False,
+        numba_args: tuple[Any, ...] = (),
+        **kwargs,
+    ):
+        """
+        Rolling statistical measure using supplied function.
+
+        Designed to be used with passed-in Cython array-based functions.
+
+        Parameters
+        ----------
+        func : callable function to apply
+        name : str,
+        numba_args : tuple
+            args to be passed when func is a numba func
+        **kwargs
+            additional arguments for rolling function and window function
+
+        Returns
+        -------
+        y : type of input
+        """
+        window_indexer = self._get_window_indexer()
+        min_periods = (
+            self.min_periods
+            if self.min_periods is not None
+            else window_indexer.window_size
+        )
+
+        def homogeneous_func(values: np.ndarray):
+            # calculation function
+
+            if values.size == 0:
+                return values.copy()
+
+            def calc(x):
+                start, end = window_indexer.get_window_bounds(
+                    num_values=len(x),
+                    min_periods=min_periods,
+                    center=self.center,
+                    closed=self.closed,
+                    step=self.step,
+                )
+                self._check_window_bounds(start, end, len(x))
+
+                return func(x, start, end, min_periods, *numba_args)
+
+            with np.errstate(all="ignore"):
+                result = calc(values)
+
+            return result
+
+        if self.method == "single":
+            return self._apply_columnwise(homogeneous_func, name, numeric_only)
+        else:
+            return self._apply_tablewise(homogeneous_func, name, numeric_only)
+
+    def _numba_apply(
+        self,
+        func: Callable[..., Any],
+        engine_kwargs: dict[str, bool] | None = None,
+        **func_kwargs,
+    ):
+        window_indexer = self._get_window_indexer()
+        min_periods = (
+            self.min_periods
+            if self.min_periods is not None
+            else window_indexer.window_size
+        )
+        obj = self._create_data(self._selected_obj)
+        if self.axis == 1:
+            obj = obj.T
+        values = self._prep_values(obj.to_numpy())
+        if values.ndim == 1:
+            values = values.reshape(-1, 1)
+        start, end = window_indexer.get_window_bounds(
+            num_values=len(values),
+            min_periods=min_periods,
+            center=self.center,
+            closed=self.closed,
+            step=self.step,
+        )
+        self._check_window_bounds(start, end, len(values))
+        # For now, map everything to float to match the Cython impl
+        # even though it is wrong
+        # TODO: Could preserve correct dtypes in future
+        # xref #53214
+        dtype_mapping = executor.float_dtype_mapping
+        aggregator = executor.generate_shared_aggregator(
+            func,
+            dtype_mapping,
+            is_grouped_kernel=False,
+            **get_jit_arguments(engine_kwargs),
+        )
+        result = aggregator(
+            values.T, start=start, end=end, min_periods=min_periods, **func_kwargs
+        ).T
+        result = result.T if self.axis == 1 else result
+        index = self._slice_axis_for_step(obj.index, result)
+        if obj.ndim == 1:
+            result = result.squeeze()
+            out = obj._constructor(result, index=index, name=obj.name)
+            return out
+        else:
+            columns = self._slice_axis_for_step(obj.columns, result.T)
+            out = obj._constructor(result, index=index, columns=columns)
+            return self._resolve_output(out, obj)
+
+    def aggregate(self, func, *args, **kwargs):
+        result = ResamplerWindowApply(self, func, args=args, kwargs=kwargs).agg()
+        if result is None:
+            return self.apply(func, raw=False, args=args, kwargs=kwargs)
+        return result
+
+    agg = aggregate
+
+
+class BaseWindowGroupby(BaseWindow):
+    """
+    Provide the groupby windowing facilities.
+    """
+
+    _grouper: BaseGrouper
+    _as_index: bool
+    _attributes: list[str] = ["_grouper"]
+
+    def __init__(
+        self,
+        obj: DataFrame | Series,
+        *args,
+        _grouper: BaseGrouper,
+        _as_index: bool = True,
+        **kwargs,
+    ) -> None:
+        from pandas.core.groupby.ops import BaseGrouper
+
+        if not isinstance(_grouper, BaseGrouper):
+            raise ValueError("Must pass a BaseGrouper object.")
+        self._grouper = _grouper
+        self._as_index = _as_index
+        # GH 32262: It's convention to keep the grouping column in
+        # groupby., but unexpected to users in
+        # groupby.rolling.
+        obj = obj.drop(columns=self._grouper.names, errors="ignore")
+        # GH 15354
+        if kwargs.get("step") is not None:
+            raise NotImplementedError("step not implemented for groupby")
+        super().__init__(obj, *args, **kwargs)
+
+    def _apply(
+        self,
+        func: Callable[..., Any],
+        name: str,
+        numeric_only: bool = False,
+        numba_args: tuple[Any, ...] = (),
+        **kwargs,
+    ) -> DataFrame | Series:
+        result = super()._apply(
+            func,
+            name,
+            numeric_only,
+            numba_args,
+            **kwargs,
+        )
+        # Reconstruct the resulting MultiIndex
+        # 1st set of levels = group by labels
+        # 2nd set of levels = original DataFrame/Series index
+        grouped_object_index = self.obj.index
+        grouped_index_name = [*grouped_object_index.names]
+        groupby_keys = copy.copy(self._grouper.names)
+        result_index_names = groupby_keys + grouped_index_name
+
+        drop_columns = [
+            key
+            for key in self._grouper.names
+            if key not in self.obj.index.names or key is None
+        ]
+
+        if len(drop_columns) != len(groupby_keys):
+            # Our result will have still kept the column in the result
+            result = result.drop(columns=drop_columns, errors="ignore")
+
+        codes = self._grouper.codes
+        levels = copy.copy(self._grouper.levels)
+
+        group_indices = self._grouper.indices.values()
+        if group_indices:
+            indexer = np.concatenate(list(group_indices))
+        else:
+            indexer = np.array([], dtype=np.intp)
+        codes = [c.take(indexer) for c in codes]
+
+        # if the index of the original dataframe needs to be preserved, append
+        # this index (but reordered) to the codes/levels from the groupby
+        if grouped_object_index is not None:
+            idx = grouped_object_index.take(indexer)
+            if not isinstance(idx, MultiIndex):
+                idx = MultiIndex.from_arrays([idx])
+            codes.extend(list(idx.codes))
+            levels.extend(list(idx.levels))
+
+        result_index = MultiIndex(
+            levels, codes, names=result_index_names, verify_integrity=False
+        )
+
+        result.index = result_index
+        if not self._as_index:
+            result = result.reset_index(level=list(range(len(groupby_keys))))
+        return result
+
+    def _apply_pairwise(
+        self,
+        target: DataFrame | Series,
+        other: DataFrame | Series | None,
+        pairwise: bool | None,
+        func: Callable[[DataFrame | Series, DataFrame | Series], DataFrame | Series],
+        numeric_only: bool,
+    ) -> DataFrame | Series:
+        """
+        Apply the given pairwise function given 2 pandas objects (DataFrame/Series)
+        """
+        # Manually drop the grouping column first
+        target = target.drop(columns=self._grouper.names, errors="ignore")
+        result = super()._apply_pairwise(target, other, pairwise, func, numeric_only)
+        # 1) Determine the levels + codes of the groupby levels
+        if other is not None and not all(
+            len(group) == len(other) for group in self._grouper.indices.values()
+        ):
+            # GH 42915
+            # len(other) != len(any group), so must reindex (expand) the result
+            # from flex_binary_moment to a "transform"-like result
+            # per groupby combination
+            old_result_len = len(result)
+            result = concat(
+                [
+                    result.take(gb_indices).reindex(result.index)
+                    for gb_indices in self._grouper.indices.values()
+                ]
+            )
+
+            gb_pairs = (
+                com.maybe_make_list(pair) for pair in self._grouper.indices.keys()
+            )
+            groupby_codes = []
+            groupby_levels = []
+            # e.g. [[1, 2], [4, 5]] as [[1, 4], [2, 5]]
+            for gb_level_pair in map(list, zip(*gb_pairs)):
+                labels = np.repeat(np.array(gb_level_pair), old_result_len)
+                codes, levels = factorize(labels)
+                groupby_codes.append(codes)
+                groupby_levels.append(levels)
+        else:
+            # pairwise=True or len(other) == len(each group), so repeat
+            # the groupby labels by the number of columns in the original object
+            groupby_codes = self._grouper.codes
+            # error: Incompatible types in assignment (expression has type
+            # "List[Index]", variable has type "List[Union[ndarray, Index]]")
+            groupby_levels = self._grouper.levels  # type: ignore[assignment]
+
+            group_indices = self._grouper.indices.values()
+            if group_indices:
+                indexer = np.concatenate(list(group_indices))
+            else:
+                indexer = np.array([], dtype=np.intp)
+
+            if target.ndim == 1:
+                repeat_by = 1
+            else:
+                repeat_by = len(target.columns)
+            groupby_codes = [
+                np.repeat(c.take(indexer), repeat_by) for c in groupby_codes
+            ]
+        # 2) Determine the levels + codes of the result from super()._apply_pairwise
+        if isinstance(result.index, MultiIndex):
+            result_codes = list(result.index.codes)
+            result_levels = list(result.index.levels)
+            result_names = list(result.index.names)
+        else:
+            idx_codes, idx_levels = factorize(result.index)
+            result_codes = [idx_codes]
+            result_levels = [idx_levels]
+            result_names = [result.index.name]
+
+        # 3) Create the resulting index by combining 1) + 2)
+        result_codes = groupby_codes + result_codes
+        result_levels = groupby_levels + result_levels
+        result_names = self._grouper.names + result_names
+
+        result_index = MultiIndex(
+            result_levels, result_codes, names=result_names, verify_integrity=False
+        )
+        result.index = result_index
+        return result
+
+    def _create_data(self, obj: NDFrameT, numeric_only: bool = False) -> NDFrameT:
+        """
+        Split data into blocks & return conformed data.
+        """
+        # Ensure the object we're rolling over is monotonically sorted relative
+        # to the groups
+        # GH 36197
+        if not obj.empty:
+            groupby_order = np.concatenate(list(self._grouper.indices.values())).astype(
+                np.int64
+            )
+            obj = obj.take(groupby_order)
+        return super()._create_data(obj, numeric_only)
+
+    def _gotitem(self, key, ndim, subset=None):
+        # we are setting the index on the actual object
+        # here so our index is carried through to the selected obj
+        # when we do the splitting for the groupby
+        if self.on is not None:
+            # GH 43355
+            subset = self.obj.set_index(self._on)
+        return super()._gotitem(key, ndim, subset=subset)
+
+
+class Window(BaseWindow):
+    """
+    Provide rolling window calculations.
+
+    Parameters
+    ----------
+    window : int, timedelta, str, offset, or BaseIndexer subclass
+        Size of the moving window.
+
+        If an integer, the fixed number of observations used for
+        each window.
+
+        If a timedelta, str, or offset, the time period of each window. Each
+        window will be a variable sized based on the observations included in
+        the time-period. This is only valid for datetimelike indexes.
+        To learn more about the offsets & frequency strings, please see `this link
+        `__.
+
+        If a BaseIndexer subclass, the window boundaries
+        based on the defined ``get_window_bounds`` method. Additional rolling
+        keyword arguments, namely ``min_periods``, ``center``, ``closed`` and
+        ``step`` will be passed to ``get_window_bounds``.
+
+    min_periods : int, default None
+        Minimum number of observations in window required to have a value;
+        otherwise, result is ``np.nan``.
+
+        For a window that is specified by an offset, ``min_periods`` will default to 1.
+
+        For a window that is specified by an integer, ``min_periods`` will default
+        to the size of the window.
+
+    center : bool, default False
+        If False, set the window labels as the right edge of the window index.
+
+        If True, set the window labels as the center of the window index.
+
+    win_type : str, default None
+        If ``None``, all points are evenly weighted.
+
+        If a string, it must be a valid `scipy.signal window function
+        `__.
+
+        Certain Scipy window types require additional parameters to be passed
+        in the aggregation function. The additional parameters must match
+        the keywords specified in the Scipy window type method signature.
+
+    on : str, optional
+        For a DataFrame, a column label or Index level on which
+        to calculate the rolling window, rather than the DataFrame's index.
+
+        Provided integer column is ignored and excluded from result since
+        an integer index is not used to calculate the rolling window.
+
+    axis : int or str, default 0
+        If ``0`` or ``'index'``, roll across the rows.
+
+        If ``1`` or ``'columns'``, roll across the columns.
+
+        For `Series` this parameter is unused and defaults to 0.
+
+        .. deprecated:: 2.1.0
+
+            The axis keyword is deprecated. For ``axis=1``,
+            transpose the DataFrame first instead.
+
+    closed : str, default None
+        If ``'right'``, the first point in the window is excluded from calculations.
+
+        If ``'left'``, the last point in the window is excluded from calculations.
+
+        If ``'both'``, the no points in the window are excluded from calculations.
+
+        If ``'neither'``, the first and last points in the window are excluded
+        from calculations.
+
+        Default ``None`` (``'right'``).
+
+    step : int, default None
+
+        .. versionadded:: 1.5.0
+
+        Evaluate the window at every ``step`` result, equivalent to slicing as
+        ``[::step]``. ``window`` must be an integer. Using a step argument other
+        than None or 1 will produce a result with a different shape than the input.
+
+    method : str {'single', 'table'}, default 'single'
+
+        .. versionadded:: 1.3.0
+
+        Execute the rolling operation per single column or row (``'single'``)
+        or over the entire object (``'table'``).
+
+        This argument is only implemented when specifying ``engine='numba'``
+        in the method call.
+
+    Returns
+    -------
+    pandas.api.typing.Window or pandas.api.typing.Rolling
+        An instance of Window is returned if ``win_type`` is passed. Otherwise,
+        an instance of Rolling is returned.
+
+    See Also
+    --------
+    expanding : Provides expanding transformations.
+    ewm : Provides exponential weighted functions.
+
+    Notes
+    -----
+    See :ref:`Windowing Operations ` for further usage details
+    and examples.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]})
+    >>> df
+         B
+    0  0.0
+    1  1.0
+    2  2.0
+    3  NaN
+    4  4.0
+
+    **window**
+
+    Rolling sum with a window length of 2 observations.
+
+    >>> df.rolling(2).sum()
+         B
+    0  NaN
+    1  1.0
+    2  3.0
+    3  NaN
+    4  NaN
+
+    Rolling sum with a window span of 2 seconds.
+
+    >>> df_time = pd.DataFrame({'B': [0, 1, 2, np.nan, 4]},
+    ...                        index=[pd.Timestamp('20130101 09:00:00'),
+    ...                               pd.Timestamp('20130101 09:00:02'),
+    ...                               pd.Timestamp('20130101 09:00:03'),
+    ...                               pd.Timestamp('20130101 09:00:05'),
+    ...                               pd.Timestamp('20130101 09:00:06')])
+
+    >>> df_time
+                           B
+    2013-01-01 09:00:00  0.0
+    2013-01-01 09:00:02  1.0
+    2013-01-01 09:00:03  2.0
+    2013-01-01 09:00:05  NaN
+    2013-01-01 09:00:06  4.0
+
+    >>> df_time.rolling('2s').sum()
+                           B
+    2013-01-01 09:00:00  0.0
+    2013-01-01 09:00:02  1.0
+    2013-01-01 09:00:03  3.0
+    2013-01-01 09:00:05  NaN
+    2013-01-01 09:00:06  4.0
+
+    Rolling sum with forward looking windows with 2 observations.
+
+    >>> indexer = pd.api.indexers.FixedForwardWindowIndexer(window_size=2)
+    >>> df.rolling(window=indexer, min_periods=1).sum()
+         B
+    0  1.0
+    1  3.0
+    2  2.0
+    3  4.0
+    4  4.0
+
+    **min_periods**
+
+    Rolling sum with a window length of 2 observations, but only needs a minimum of 1
+    observation to calculate a value.
+
+    >>> df.rolling(2, min_periods=1).sum()
+         B
+    0  0.0
+    1  1.0
+    2  3.0
+    3  2.0
+    4  4.0
+
+    **center**
+
+    Rolling sum with the result assigned to the center of the window index.
+
+    >>> df.rolling(3, min_periods=1, center=True).sum()
+         B
+    0  1.0
+    1  3.0
+    2  3.0
+    3  6.0
+    4  4.0
+
+    >>> df.rolling(3, min_periods=1, center=False).sum()
+         B
+    0  0.0
+    1  1.0
+    2  3.0
+    3  3.0
+    4  6.0
+
+    **step**
+
+    Rolling sum with a window length of 2 observations, minimum of 1 observation to
+    calculate a value, and a step of 2.
+
+    >>> df.rolling(2, min_periods=1, step=2).sum()
+         B
+    0  0.0
+    2  3.0
+    4  4.0
+
+    **win_type**
+
+    Rolling sum with a window length of 2, using the Scipy ``'gaussian'``
+    window type. ``std`` is required in the aggregation function.
+
+    >>> df.rolling(2, win_type='gaussian').sum(std=3)
+              B
+    0       NaN
+    1  0.986207
+    2  2.958621
+    3       NaN
+    4       NaN
+
+    **on**
+
+    Rolling sum with a window length of 2 days.
+
+    >>> df = pd.DataFrame({
+    ...     'A': [pd.to_datetime('2020-01-01'),
+    ...           pd.to_datetime('2020-01-01'),
+    ...           pd.to_datetime('2020-01-02'),],
+    ...     'B': [1, 2, 3], },
+    ...     index=pd.date_range('2020', periods=3))
+
+    >>> df
+                        A  B
+    2020-01-01 2020-01-01  1
+    2020-01-02 2020-01-01  2
+    2020-01-03 2020-01-02  3
+
+    >>> df.rolling('2D', on='A').sum()
+                        A    B
+    2020-01-01 2020-01-01  1.0
+    2020-01-02 2020-01-01  3.0
+    2020-01-03 2020-01-02  6.0
+    """
+
+    _attributes = [
+        "window",
+        "min_periods",
+        "center",
+        "win_type",
+        "axis",
+        "on",
+        "closed",
+        "step",
+        "method",
+    ]
+
+    def _validate(self):
+        super()._validate()
+
+        if not isinstance(self.win_type, str):
+            raise ValueError(f"Invalid win_type {self.win_type}")
+        signal = import_optional_dependency(
+            "scipy.signal.windows", extra="Scipy is required to generate window weight."
+        )
+        self._scipy_weight_generator = getattr(signal, self.win_type, None)
+        if self._scipy_weight_generator is None:
+            raise ValueError(f"Invalid win_type {self.win_type}")
+
+        if isinstance(self.window, BaseIndexer):
+            raise NotImplementedError(
+                "BaseIndexer subclasses not implemented with win_types."
+            )
+        if not is_integer(self.window) or self.window < 0:
+            raise ValueError("window must be an integer 0 or greater")
+
+        if self.method != "single":
+            raise NotImplementedError("'single' is the only supported method type.")
+
+    def _center_window(self, result: np.ndarray, offset: int) -> np.ndarray:
+        """
+        Center the result in the window for weighted rolling aggregations.
+        """
+        if offset > 0:
+            lead_indexer = [slice(offset, None)]
+            result = np.copy(result[tuple(lead_indexer)])
+        return result
+
+    def _apply(
+        self,
+        func: Callable[[np.ndarray, int, int], np.ndarray],
+        name: str,
+        numeric_only: bool = False,
+        numba_args: tuple[Any, ...] = (),
+        **kwargs,
+    ):
+        """
+        Rolling with weights statistical measure using supplied function.
+
+        Designed to be used with passed-in Cython array-based functions.
+
+        Parameters
+        ----------
+        func : callable function to apply
+        name : str,
+        numeric_only : bool, default False
+            Whether to only operate on bool, int, and float columns
+        numba_args : tuple
+            unused
+        **kwargs
+            additional arguments for scipy windows if necessary
+
+        Returns
+        -------
+        y : type of input
+        """
+        # "None" not callable  [misc]
+        window = self._scipy_weight_generator(  # type: ignore[misc]
+            self.window, **kwargs
+        )
+        offset = (len(window) - 1) // 2 if self.center else 0
+
+        def homogeneous_func(values: np.ndarray):
+            # calculation function
+
+            if values.size == 0:
+                return values.copy()
+
+            def calc(x):
+                additional_nans = np.array([np.nan] * offset)
+                x = np.concatenate((x, additional_nans))
+                return func(
+                    x,
+                    window,
+                    self.min_periods if self.min_periods is not None else len(window),
+                )
+
+            with np.errstate(all="ignore"):
+                # Our weighted aggregations return memoryviews
+                result = np.asarray(calc(values))
+
+            if self.center:
+                result = self._center_window(result, offset)
+
+            return result
+
+        return self._apply_columnwise(homogeneous_func, name, numeric_only)[
+            :: self.step
+        ]
+
+    @doc(
+        _shared_docs["aggregate"],
+        see_also=dedent(
+            """
+        See Also
+        --------
+        pandas.DataFrame.aggregate : Similar DataFrame method.
+        pandas.Series.aggregate : Similar Series method.
+        """
+        ),
+        examples=dedent(
+            """
+        Examples
+        --------
+        >>> df = pd.DataFrame({"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.rolling(2, win_type="boxcar").agg("mean")
+             A    B    C
+        0  NaN  NaN  NaN
+        1  1.5  4.5  7.5
+        2  2.5  5.5  8.5
+        """
+        ),
+        klass="Series/DataFrame",
+        axis="",
+    )
+    def aggregate(self, func, *args, **kwargs):
+        result = ResamplerWindowApply(self, func, args=args, kwargs=kwargs).agg()
+        if result is None:
+            # these must apply directly
+            result = func(self)
+
+        return result
+
+    agg = aggregate
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        kwargs_scipy,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([0, 1, 5, 2, 8])
+
+        To get an instance of :class:`~pandas.core.window.rolling.Window` we need
+        to pass the parameter `win_type`.
+
+        >>> type(ser.rolling(2, win_type='gaussian'))
+        
+
+        In order to use the `SciPy` Gaussian window we need to provide the parameters
+        `M` and `std`. The parameter `M` corresponds to 2 in our example.
+        We pass the second parameter `std` as a parameter of the following method
+        (`sum` in this case):
+
+        >>> ser.rolling(2, win_type='gaussian').sum(std=3)
+        0         NaN
+        1    0.986207
+        2    5.917243
+        3    6.903450
+        4    9.862071
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="weighted window sum",
+        agg_method="sum",
+    )
+    def sum(self, numeric_only: bool = False, **kwargs):
+        window_func = window_aggregations.roll_weighted_sum
+        # error: Argument 1 to "_apply" of "Window" has incompatible type
+        # "Callable[[ndarray, ndarray, int], ndarray]"; expected
+        # "Callable[[ndarray, int, int], ndarray]"
+        return self._apply(
+            window_func,  # type: ignore[arg-type]
+            name="sum",
+            numeric_only=numeric_only,
+            **kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        kwargs_scipy,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([0, 1, 5, 2, 8])
+
+        To get an instance of :class:`~pandas.core.window.rolling.Window` we need
+        to pass the parameter `win_type`.
+
+        >>> type(ser.rolling(2, win_type='gaussian'))
+        
+
+        In order to use the `SciPy` Gaussian window we need to provide the parameters
+        `M` and `std`. The parameter `M` corresponds to 2 in our example.
+        We pass the second parameter `std` as a parameter of the following method:
+
+        >>> ser.rolling(2, win_type='gaussian').mean(std=3)
+        0    NaN
+        1    0.5
+        2    3.0
+        3    3.5
+        4    5.0
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="weighted window mean",
+        agg_method="mean",
+    )
+    def mean(self, numeric_only: bool = False, **kwargs):
+        window_func = window_aggregations.roll_weighted_mean
+        # error: Argument 1 to "_apply" of "Window" has incompatible type
+        # "Callable[[ndarray, ndarray, int], ndarray]"; expected
+        # "Callable[[ndarray, int, int], ndarray]"
+        return self._apply(
+            window_func,  # type: ignore[arg-type]
+            name="mean",
+            numeric_only=numeric_only,
+            **kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        kwargs_scipy,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([0, 1, 5, 2, 8])
+
+        To get an instance of :class:`~pandas.core.window.rolling.Window` we need
+        to pass the parameter `win_type`.
+
+        >>> type(ser.rolling(2, win_type='gaussian'))
+        
+
+        In order to use the `SciPy` Gaussian window we need to provide the parameters
+        `M` and `std`. The parameter `M` corresponds to 2 in our example.
+        We pass the second parameter `std` as a parameter of the following method:
+
+        >>> ser.rolling(2, win_type='gaussian').var(std=3)
+        0     NaN
+        1     0.5
+        2     8.0
+        3     4.5
+        4    18.0
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="weighted window variance",
+        agg_method="var",
+    )
+    def var(self, ddof: int = 1, numeric_only: bool = False, **kwargs):
+        window_func = partial(window_aggregations.roll_weighted_var, ddof=ddof)
+        kwargs.pop("name", None)
+        return self._apply(window_func, name="var", numeric_only=numeric_only, **kwargs)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        kwargs_scipy,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([0, 1, 5, 2, 8])
+
+        To get an instance of :class:`~pandas.core.window.rolling.Window` we need
+        to pass the parameter `win_type`.
+
+        >>> type(ser.rolling(2, win_type='gaussian'))
+        
+
+        In order to use the `SciPy` Gaussian window we need to provide the parameters
+        `M` and `std`. The parameter `M` corresponds to 2 in our example.
+        We pass the second parameter `std` as a parameter of the following method:
+
+        >>> ser.rolling(2, win_type='gaussian').std(std=3)
+        0         NaN
+        1    0.707107
+        2    2.828427
+        3    2.121320
+        4    4.242641
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="weighted window standard deviation",
+        agg_method="std",
+    )
+    def std(self, ddof: int = 1, numeric_only: bool = False, **kwargs):
+        return zsqrt(
+            self.var(ddof=ddof, name="std", numeric_only=numeric_only, **kwargs)
+        )
+
+
+class RollingAndExpandingMixin(BaseWindow):
+    def count(self, numeric_only: bool = False):
+        window_func = window_aggregations.roll_sum
+        return self._apply(window_func, name="count", numeric_only=numeric_only)
+
+    def apply(
+        self,
+        func: Callable[..., Any],
+        raw: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+    ):
+        if args is None:
+            args = ()
+        if kwargs is None:
+            kwargs = {}
+
+        if not is_bool(raw):
+            raise ValueError("raw parameter must be `True` or `False`")
+
+        numba_args: tuple[Any, ...] = ()
+        if maybe_use_numba(engine):
+            if raw is False:
+                raise ValueError("raw must be `True` when using the numba engine")
+            numba_args = args
+            if self.method == "single":
+                apply_func = generate_numba_apply_func(
+                    func, **get_jit_arguments(engine_kwargs, kwargs)
+                )
+            else:
+                apply_func = generate_numba_table_func(
+                    func, **get_jit_arguments(engine_kwargs, kwargs)
+                )
+        elif engine in ("cython", None):
+            if engine_kwargs is not None:
+                raise ValueError("cython engine does not accept engine_kwargs")
+            apply_func = self._generate_cython_apply_func(args, kwargs, raw, func)
+        else:
+            raise ValueError("engine must be either 'numba' or 'cython'")
+
+        return self._apply(
+            apply_func,
+            name="apply",
+            numba_args=numba_args,
+        )
+
+    def _generate_cython_apply_func(
+        self,
+        args: tuple[Any, ...],
+        kwargs: dict[str, Any],
+        raw: bool | np.bool_,
+        function: Callable[..., Any],
+    ) -> Callable[[np.ndarray, np.ndarray, np.ndarray, int], np.ndarray]:
+        from pandas import Series
+
+        window_func = partial(
+            window_aggregations.roll_apply,
+            args=args,
+            kwargs=kwargs,
+            raw=raw,
+            function=function,
+        )
+
+        def apply_func(values, begin, end, min_periods, raw=raw):
+            if not raw:
+                # GH 45912
+                values = Series(values, index=self._on, copy=False)
+            return window_func(values, begin, end, min_periods)
+
+        return apply_func
+
+    def sum(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                func = generate_manual_numpy_nan_agg_with_axis(np.nansum)
+                return self.apply(
+                    func,
+                    raw=True,
+                    engine=engine,
+                    engine_kwargs=engine_kwargs,
+                )
+            else:
+                from pandas.core._numba.kernels import sliding_sum
+
+                return self._numba_apply(sliding_sum, engine_kwargs)
+        window_func = window_aggregations.roll_sum
+        return self._apply(window_func, name="sum", numeric_only=numeric_only)
+
+    def max(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                func = generate_manual_numpy_nan_agg_with_axis(np.nanmax)
+                return self.apply(
+                    func,
+                    raw=True,
+                    engine=engine,
+                    engine_kwargs=engine_kwargs,
+                )
+            else:
+                from pandas.core._numba.kernels import sliding_min_max
+
+                return self._numba_apply(sliding_min_max, engine_kwargs, is_max=True)
+        window_func = window_aggregations.roll_max
+        return self._apply(window_func, name="max", numeric_only=numeric_only)
+
+    def min(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                func = generate_manual_numpy_nan_agg_with_axis(np.nanmin)
+                return self.apply(
+                    func,
+                    raw=True,
+                    engine=engine,
+                    engine_kwargs=engine_kwargs,
+                )
+            else:
+                from pandas.core._numba.kernels import sliding_min_max
+
+                return self._numba_apply(sliding_min_max, engine_kwargs, is_max=False)
+        window_func = window_aggregations.roll_min
+        return self._apply(window_func, name="min", numeric_only=numeric_only)
+
+    def mean(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                func = generate_manual_numpy_nan_agg_with_axis(np.nanmean)
+                return self.apply(
+                    func,
+                    raw=True,
+                    engine=engine,
+                    engine_kwargs=engine_kwargs,
+                )
+            else:
+                from pandas.core._numba.kernels import sliding_mean
+
+                return self._numba_apply(sliding_mean, engine_kwargs)
+        window_func = window_aggregations.roll_mean
+        return self._apply(window_func, name="mean", numeric_only=numeric_only)
+
+    def median(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                func = generate_manual_numpy_nan_agg_with_axis(np.nanmedian)
+            else:
+                func = np.nanmedian
+
+            return self.apply(
+                func,
+                raw=True,
+                engine=engine,
+                engine_kwargs=engine_kwargs,
+            )
+        window_func = window_aggregations.roll_median_c
+        return self._apply(window_func, name="median", numeric_only=numeric_only)
+
+    def std(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                raise NotImplementedError("std not supported with method='table'")
+            from pandas.core._numba.kernels import sliding_var
+
+            return zsqrt(self._numba_apply(sliding_var, engine_kwargs, ddof=ddof))
+        window_func = window_aggregations.roll_var
+
+        def zsqrt_func(values, begin, end, min_periods):
+            return zsqrt(window_func(values, begin, end, min_periods, ddof=ddof))
+
+        return self._apply(
+            zsqrt_func,
+            name="std",
+            numeric_only=numeric_only,
+        )
+
+    def var(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        if maybe_use_numba(engine):
+            if self.method == "table":
+                raise NotImplementedError("var not supported with method='table'")
+            from pandas.core._numba.kernels import sliding_var
+
+            return self._numba_apply(sliding_var, engine_kwargs, ddof=ddof)
+        window_func = partial(window_aggregations.roll_var, ddof=ddof)
+        return self._apply(
+            window_func,
+            name="var",
+            numeric_only=numeric_only,
+        )
+
+    def skew(self, numeric_only: bool = False):
+        window_func = window_aggregations.roll_skew
+        return self._apply(
+            window_func,
+            name="skew",
+            numeric_only=numeric_only,
+        )
+
+    def sem(self, ddof: int = 1, numeric_only: bool = False):
+        # Raise here so error message says sem instead of std
+        self._validate_numeric_only("sem", numeric_only)
+        return self.std(numeric_only=numeric_only) / (
+            self.count(numeric_only=numeric_only) - ddof
+        ).pow(0.5)
+
+    def kurt(self, numeric_only: bool = False):
+        window_func = window_aggregations.roll_kurt
+        return self._apply(
+            window_func,
+            name="kurt",
+            numeric_only=numeric_only,
+        )
+
+    def quantile(
+        self,
+        q: float,
+        interpolation: QuantileInterpolation = "linear",
+        numeric_only: bool = False,
+    ):
+        if q == 1.0:
+            window_func = window_aggregations.roll_max
+        elif q == 0.0:
+            window_func = window_aggregations.roll_min
+        else:
+            window_func = partial(
+                window_aggregations.roll_quantile,
+                quantile=q,
+                interpolation=interpolation,
+            )
+
+        return self._apply(window_func, name="quantile", numeric_only=numeric_only)
+
+    def rank(
+        self,
+        method: WindowingRankType = "average",
+        ascending: bool = True,
+        pct: bool = False,
+        numeric_only: bool = False,
+    ):
+        window_func = partial(
+            window_aggregations.roll_rank,
+            method=method,
+            ascending=ascending,
+            percentile=pct,
+        )
+
+        return self._apply(window_func, name="rank", numeric_only=numeric_only)
+
+    def cov(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        if self.step is not None:
+            raise NotImplementedError("step not implemented for cov")
+        self._validate_numeric_only("cov", numeric_only)
+
+        from pandas import Series
+
+        def cov_func(x, y):
+            x_array = self._prep_values(x)
+            y_array = self._prep_values(y)
+            window_indexer = self._get_window_indexer()
+            min_periods = (
+                self.min_periods
+                if self.min_periods is not None
+                else window_indexer.window_size
+            )
+            start, end = window_indexer.get_window_bounds(
+                num_values=len(x_array),
+                min_periods=min_periods,
+                center=self.center,
+                closed=self.closed,
+                step=self.step,
+            )
+            self._check_window_bounds(start, end, len(x_array))
+
+            with np.errstate(all="ignore"):
+                mean_x_y = window_aggregations.roll_mean(
+                    x_array * y_array, start, end, min_periods
+                )
+                mean_x = window_aggregations.roll_mean(x_array, start, end, min_periods)
+                mean_y = window_aggregations.roll_mean(y_array, start, end, min_periods)
+                count_x_y = window_aggregations.roll_sum(
+                    notna(x_array + y_array).astype(np.float64), start, end, 0
+                )
+                result = (mean_x_y - mean_x * mean_y) * (count_x_y / (count_x_y - ddof))
+            return Series(result, index=x.index, name=x.name, copy=False)
+
+        return self._apply_pairwise(
+            self._selected_obj, other, pairwise, cov_func, numeric_only
+        )
+
+    def corr(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        if self.step is not None:
+            raise NotImplementedError("step not implemented for corr")
+        self._validate_numeric_only("corr", numeric_only)
+
+        from pandas import Series
+
+        def corr_func(x, y):
+            x_array = self._prep_values(x)
+            y_array = self._prep_values(y)
+            window_indexer = self._get_window_indexer()
+            min_periods = (
+                self.min_periods
+                if self.min_periods is not None
+                else window_indexer.window_size
+            )
+            start, end = window_indexer.get_window_bounds(
+                num_values=len(x_array),
+                min_periods=min_periods,
+                center=self.center,
+                closed=self.closed,
+                step=self.step,
+            )
+            self._check_window_bounds(start, end, len(x_array))
+
+            with np.errstate(all="ignore"):
+                mean_x_y = window_aggregations.roll_mean(
+                    x_array * y_array, start, end, min_periods
+                )
+                mean_x = window_aggregations.roll_mean(x_array, start, end, min_periods)
+                mean_y = window_aggregations.roll_mean(y_array, start, end, min_periods)
+                count_x_y = window_aggregations.roll_sum(
+                    notna(x_array + y_array).astype(np.float64), start, end, 0
+                )
+                x_var = window_aggregations.roll_var(
+                    x_array, start, end, min_periods, ddof
+                )
+                y_var = window_aggregations.roll_var(
+                    y_array, start, end, min_periods, ddof
+                )
+                numerator = (mean_x_y - mean_x * mean_y) * (
+                    count_x_y / (count_x_y - ddof)
+                )
+                denominator = (x_var * y_var) ** 0.5
+                result = numerator / denominator
+            return Series(result, index=x.index, name=x.name, copy=False)
+
+        return self._apply_pairwise(
+            self._selected_obj, other, pairwise, corr_func, numeric_only
+        )
+
+
+class Rolling(RollingAndExpandingMixin):
+    _attributes: list[str] = [
+        "window",
+        "min_periods",
+        "center",
+        "win_type",
+        "axis",
+        "on",
+        "closed",
+        "step",
+        "method",
+    ]
+
+    def _validate(self):
+        super()._validate()
+
+        # we allow rolling on a datetimelike index
+        if (
+            self.obj.empty
+            or isinstance(self._on, (DatetimeIndex, TimedeltaIndex, PeriodIndex))
+            or (isinstance(self._on.dtype, ArrowDtype) and self._on.dtype.kind in "mM")
+        ) and isinstance(self.window, (str, BaseOffset, timedelta)):
+            self._validate_datetimelike_monotonic()
+
+            # this will raise ValueError on non-fixed freqs
+            try:
+                freq = to_offset(self.window)
+            except (TypeError, ValueError) as err:
+                raise ValueError(
+                    f"passed window {self.window} is not "
+                    "compatible with a datetimelike index"
+                ) from err
+            if isinstance(self._on, PeriodIndex):
+                # error: Incompatible types in assignment (expression has type
+                # "float", variable has type "Optional[int]")
+                self._win_freq_i8 = freq.nanos / (  # type: ignore[assignment]
+                    self._on.freq.nanos / self._on.freq.n
+                )
+            else:
+                try:
+                    unit = dtype_to_unit(self._on.dtype)  # type: ignore[arg-type]
+                except TypeError:
+                    # if not a datetime dtype, eg for empty dataframes
+                    unit = "ns"
+                self._win_freq_i8 = Timedelta(freq.nanos).as_unit(unit)._value
+
+            # min_periods must be an integer
+            if self.min_periods is None:
+                self.min_periods = 1
+
+            if self.step is not None:
+                raise NotImplementedError(
+                    "step is not supported with frequency windows"
+                )
+
+        elif isinstance(self.window, BaseIndexer):
+            # Passed BaseIndexer subclass should handle all other rolling kwargs
+            pass
+        elif not is_integer(self.window) or self.window < 0:
+            raise ValueError("window must be an integer 0 or greater")
+
+    def _validate_datetimelike_monotonic(self) -> None:
+        """
+        Validate self._on is monotonic (increasing or decreasing) and has
+        no NaT values for frequency windows.
+        """
+        if self._on.hasnans:
+            self._raise_monotonic_error("values must not have NaT")
+        if not (self._on.is_monotonic_increasing or self._on.is_monotonic_decreasing):
+            self._raise_monotonic_error("values must be monotonic")
+
+    def _raise_monotonic_error(self, msg: str):
+        on = self.on
+        if on is None:
+            if self.axis == 0:
+                on = "index"
+            else:
+                on = "column"
+        raise ValueError(f"{on} {msg}")
+
+    @doc(
+        _shared_docs["aggregate"],
+        see_also=dedent(
+            """
+        See Also
+        --------
+        pandas.Series.rolling : Calling object with Series data.
+        pandas.DataFrame.rolling : Calling object with DataFrame data.
+        """
+        ),
+        examples=dedent(
+            """
+        Examples
+        --------
+        >>> df = pd.DataFrame({"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.rolling(2).sum()
+             A     B     C
+        0  NaN   NaN   NaN
+        1  3.0   9.0  15.0
+        2  5.0  11.0  17.0
+
+        >>> df.rolling(2).agg({"A": "sum", "B": "min"})
+             A    B
+        0  NaN  NaN
+        1  3.0  4.0
+        2  5.0  5.0
+        """
+        ),
+        klass="Series/Dataframe",
+        axis="",
+    )
+    def aggregate(self, func, *args, **kwargs):
+        return super().aggregate(func, *args, **kwargs)
+
+    agg = aggregate
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([2, 3, np.nan, 10])
+        >>> s.rolling(2).count()
+        0    NaN
+        1    2.0
+        2    1.0
+        3    1.0
+        dtype: float64
+        >>> s.rolling(3).count()
+        0    NaN
+        1    NaN
+        2    2.0
+        3    2.0
+        dtype: float64
+        >>> s.rolling(4).count()
+        0    NaN
+        1    NaN
+        2    NaN
+        3    3.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="count of non NaN observations",
+        agg_method="count",
+    )
+    def count(self, numeric_only: bool = False):
+        return super().count(numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        window_apply_parameters,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 6, 5, 4])
+        >>> ser.rolling(2).apply(lambda s: s.sum() - s.min())
+        0    NaN
+        1    6.0
+        2    6.0
+        3    5.0
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="custom aggregation function",
+        agg_method="apply",
+    )
+    def apply(
+        self,
+        func: Callable[..., Any],
+        raw: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        args: tuple[Any, ...] | None = None,
+        kwargs: dict[str, Any] | None = None,
+    ):
+        return super().apply(
+            func,
+            raw=raw,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+            args=args,
+            kwargs=kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([1, 2, 3, 4, 5])
+        >>> s
+        0    1
+        1    2
+        2    3
+        3    4
+        4    5
+        dtype: int64
+
+        >>> s.rolling(3).sum()
+        0     NaN
+        1     NaN
+        2     6.0
+        3     9.0
+        4    12.0
+        dtype: float64
+
+        >>> s.rolling(3, center=True).sum()
+        0     NaN
+        1     6.0
+        2     9.0
+        3    12.0
+        4     NaN
+        dtype: float64
+
+        For DataFrame, each sum is computed column-wise.
+
+        >>> df = pd.DataFrame({{"A": s, "B": s ** 2}})
+        >>> df
+           A   B
+        0  1   1
+        1  2   4
+        2  3   9
+        3  4  16
+        4  5  25
+
+        >>> df.rolling(3).sum()
+              A     B
+        0   NaN   NaN
+        1   NaN   NaN
+        2   6.0  14.0
+        3   9.0  29.0
+        4  12.0  50.0
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="sum",
+        agg_method="sum",
+    )
+    def sum(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().sum(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 2, 3, 4])
+        >>> ser.rolling(2).max()
+        0    NaN
+        1    2.0
+        2    3.0
+        3    4.0
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="maximum",
+        agg_method="max",
+    )
+    def max(
+        self,
+        numeric_only: bool = False,
+        *args,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+        **kwargs,
+    ):
+        return super().max(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """
+        Performing a rolling minimum with a window size of 3.
+
+        >>> s = pd.Series([4, 3, 5, 2, 6])
+        >>> s.rolling(3).min()
+        0    NaN
+        1    NaN
+        2    3.0
+        3    2.0
+        4    2.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="minimum",
+        agg_method="min",
+    )
+    def min(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().min(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """
+        The below examples will show rolling mean calculations with window sizes of
+        two and three, respectively.
+
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s.rolling(2).mean()
+        0    NaN
+        1    1.5
+        2    2.5
+        3    3.5
+        dtype: float64
+
+        >>> s.rolling(3).mean()
+        0    NaN
+        1    NaN
+        2    2.0
+        3    3.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="mean",
+        agg_method="mean",
+    )
+    def mean(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().mean(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        window_agg_numba_parameters(),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        numba_notes,
+        create_section_header("Examples"),
+        dedent(
+            """
+        Compute the rolling median of a series with a window size of 3.
+
+        >>> s = pd.Series([0, 1, 2, 3, 4])
+        >>> s.rolling(3).median()
+        0    NaN
+        1    NaN
+        2    1.0
+        3    2.0
+        4    3.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="median",
+        agg_method="median",
+    )
+    def median(
+        self,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().median(
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        window_agg_numba_parameters("1.4"),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "numpy.std : Equivalent method for NumPy array.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        The default ``ddof`` of 1 used in :meth:`Series.std` is different
+        than the default ``ddof`` of 0 in :func:`numpy.std`.
+
+        A minimum of one period is required for the rolling calculation.\n
+        """
+        ).replace("\n", "", 1),
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5])
+        >>> s.rolling(3).std()
+        0         NaN
+        1         NaN
+        2    0.577350
+        3    1.000000
+        4    1.000000
+        5    1.154701
+        6    0.000000
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="standard deviation",
+        agg_method="std",
+    )
+    def std(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().std(
+            ddof=ddof,
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        window_agg_numba_parameters("1.4"),
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "numpy.var : Equivalent method for NumPy array.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        The default ``ddof`` of 1 used in :meth:`Series.var` is different
+        than the default ``ddof`` of 0 in :func:`numpy.var`.
+
+        A minimum of one period is required for the rolling calculation.\n
+        """
+        ).replace("\n", "", 1),
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([5, 5, 6, 7, 5, 5, 5])
+        >>> s.rolling(3).var()
+        0         NaN
+        1         NaN
+        2    0.333333
+        3    1.000000
+        4    1.000000
+        5    1.333333
+        6    0.000000
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="variance",
+        agg_method="var",
+    )
+    def var(
+        self,
+        ddof: int = 1,
+        numeric_only: bool = False,
+        engine: Literal["cython", "numba"] | None = None,
+        engine_kwargs: dict[str, bool] | None = None,
+    ):
+        return super().var(
+            ddof=ddof,
+            numeric_only=numeric_only,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "scipy.stats.skew : Third moment of a probability density.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        A minimum of three periods is required for the rolling calculation.\n
+        """
+        ),
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser = pd.Series([1, 5, 2, 7, 15, 6])
+        >>> ser.rolling(3).skew().round(6)
+        0         NaN
+        1         NaN
+        2    1.293343
+        3   -0.585583
+        4    0.670284
+        5    1.652317
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="unbiased skewness",
+        agg_method="skew",
+    )
+    def skew(self, numeric_only: bool = False):
+        return super().skew(numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Notes"),
+        "A minimum of one period is required for the calculation.\n\n",
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([0, 1, 2, 3])
+        >>> s.rolling(2, min_periods=1).sem()
+        0         NaN
+        1    0.707107
+        2    0.707107
+        3    0.707107
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="standard error of mean",
+        agg_method="sem",
+    )
+    def sem(self, ddof: int = 1, numeric_only: bool = False):
+        # Raise here so error message says sem instead of std
+        self._validate_numeric_only("sem", numeric_only)
+        return self.std(numeric_only=numeric_only) / (
+            self.count(numeric_only) - ddof
+        ).pow(0.5)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        "scipy.stats.kurtosis : Reference SciPy method.\n",
+        template_see_also,
+        create_section_header("Notes"),
+        "A minimum of four periods is required for the calculation.\n\n",
+        create_section_header("Examples"),
+        dedent(
+            """
+        The example below will show a rolling calculation with a window size of
+        four matching the equivalent function call using `scipy.stats`.
+
+        >>> arr = [1, 2, 3, 4, 999]
+        >>> import scipy.stats
+        >>> print(f"{{scipy.stats.kurtosis(arr[:-1], bias=False):.6f}}")
+        -1.200000
+        >>> print(f"{{scipy.stats.kurtosis(arr[1:], bias=False):.6f}}")
+        3.999946
+        >>> s = pd.Series(arr)
+        >>> s.rolling(4).kurt()
+        0         NaN
+        1         NaN
+        2         NaN
+        3   -1.200000
+        4    3.999946
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="Fisher's definition of kurtosis without bias",
+        agg_method="kurt",
+    )
+    def kurt(self, numeric_only: bool = False):
+        return super().kurt(numeric_only=numeric_only)
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        quantile : float
+            Quantile to compute. 0 <= quantile <= 1.
+
+            .. deprecated:: 2.1.0
+                This will be renamed to 'q' in a future version.
+        interpolation : {{'linear', 'lower', 'higher', 'midpoint', 'nearest'}}
+            This optional parameter specifies the interpolation method to use,
+            when the desired quantile lies between two data points `i` and `j`:
+
+                * linear: `i + (j - i) * fraction`, where `fraction` is the
+                  fractional part of the index surrounded by `i` and `j`.
+                * lower: `i`.
+                * higher: `j`.
+                * nearest: `i` or `j` whichever is nearest.
+                * midpoint: (`i` + `j`) / 2.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([1, 2, 3, 4])
+        >>> s.rolling(2).quantile(.4, interpolation='lower')
+        0    NaN
+        1    1.0
+        2    2.0
+        3    3.0
+        dtype: float64
+
+        >>> s.rolling(2).quantile(.4, interpolation='midpoint')
+        0    NaN
+        1    1.5
+        2    2.5
+        3    3.5
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="quantile",
+        agg_method="quantile",
+    )
+    @deprecate_kwarg(old_arg_name="quantile", new_arg_name="q")
+    def quantile(
+        self,
+        q: float,
+        interpolation: QuantileInterpolation = "linear",
+        numeric_only: bool = False,
+    ):
+        return super().quantile(
+            q=q,
+            interpolation=interpolation,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        ".. versionadded:: 1.4.0 \n\n",
+        create_section_header("Parameters"),
+        dedent(
+            """
+        method : {{'average', 'min', 'max'}}, default 'average'
+            How to rank the group of records that have the same value (i.e. ties):
+
+            * average: average rank of the group
+            * min: lowest rank in the group
+            * max: highest rank in the group
+
+        ascending : bool, default True
+            Whether or not the elements should be ranked in ascending order.
+        pct : bool, default False
+            Whether or not to display the returned rankings in percentile
+            form.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """
+        >>> s = pd.Series([1, 4, 2, 3, 5, 3])
+        >>> s.rolling(3).rank()
+        0    NaN
+        1    NaN
+        2    2.0
+        3    2.0
+        4    3.0
+        5    1.5
+        dtype: float64
+
+        >>> s.rolling(3).rank(method="max")
+        0    NaN
+        1    NaN
+        2    2.0
+        3    2.0
+        4    3.0
+        5    2.0
+        dtype: float64
+
+        >>> s.rolling(3).rank(method="min")
+        0    NaN
+        1    NaN
+        2    2.0
+        3    2.0
+        4    3.0
+        5    1.0
+        dtype: float64
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="rank",
+        agg_method="rank",
+    )
+    def rank(
+        self,
+        method: WindowingRankType = "average",
+        ascending: bool = True,
+        pct: bool = False,
+        numeric_only: bool = False,
+    ):
+        return super().rank(
+            method=method,
+            ascending=ascending,
+            pct=pct,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        other : Series or DataFrame, optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndexed DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        template_see_also,
+        create_section_header("Examples"),
+        dedent(
+            """\
+        >>> ser1 = pd.Series([1, 2, 3, 4])
+        >>> ser2 = pd.Series([1, 4, 5, 8])
+        >>> ser1.rolling(2).cov(ser2)
+        0    NaN
+        1    1.5
+        2    0.5
+        3    1.5
+        dtype: float64
+        """
+        ),
+        window_method="rolling",
+        aggregation_description="sample covariance",
+        agg_method="cov",
+    )
+    def cov(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        return super().cov(
+            other=other,
+            pairwise=pairwise,
+            ddof=ddof,
+            numeric_only=numeric_only,
+        )
+
+    @doc(
+        template_header,
+        create_section_header("Parameters"),
+        dedent(
+            """
+        other : Series or DataFrame, optional
+            If not supplied then will default to self and produce pairwise
+            output.
+        pairwise : bool, default None
+            If False then only matching columns between self and other will be
+            used and the output will be a DataFrame.
+            If True then all pairwise combinations will be calculated and the
+            output will be a MultiIndexed DataFrame in the case of DataFrame
+            inputs. In the case of missing elements, only complete pairwise
+            observations will be used.
+        ddof : int, default 1
+            Delta Degrees of Freedom.  The divisor used in calculations
+            is ``N - ddof``, where ``N`` represents the number of elements.
+        """
+        ).replace("\n", "", 1),
+        kwargs_numeric_only,
+        create_section_header("Returns"),
+        template_returns,
+        create_section_header("See Also"),
+        dedent(
+            """
+        cov : Similar method to calculate covariance.
+        numpy.corrcoef : NumPy Pearson's correlation calculation.
+        """
+        ).replace("\n", "", 1),
+        template_see_also,
+        create_section_header("Notes"),
+        dedent(
+            """
+        This function uses Pearson's definition of correlation
+        (https://en.wikipedia.org/wiki/Pearson_correlation_coefficient).
+
+        When `other` is not specified, the output will be self correlation (e.g.
+        all 1's), except for :class:`~pandas.DataFrame` inputs with `pairwise`
+        set to `True`.
+
+        Function will return ``NaN`` for correlations of equal valued sequences;
+        this is the result of a 0/0 division error.
+
+        When `pairwise` is set to `False`, only matching columns between `self` and
+        `other` will be used.
+
+        When `pairwise` is set to `True`, the output will be a MultiIndex DataFrame
+        with the original index on the first level, and the `other` DataFrame
+        columns on the second level.
+
+        In the case of missing elements, only complete pairwise observations
+        will be used.\n
+        """
+        ).replace("\n", "", 1),
+        create_section_header("Examples"),
+        dedent(
+            """
+        The below example shows a rolling calculation with a window size of
+        four matching the equivalent function call using :meth:`numpy.corrcoef`.
+
+        >>> v1 = [3, 3, 3, 5, 8]
+        >>> v2 = [3, 4, 4, 4, 8]
+        >>> np.corrcoef(v1[:-1], v2[:-1])
+        array([[1.        , 0.33333333],
+               [0.33333333, 1.        ]])
+        >>> np.corrcoef(v1[1:], v2[1:])
+        array([[1.       , 0.9169493],
+               [0.9169493, 1.       ]])
+        >>> s1 = pd.Series(v1)
+        >>> s2 = pd.Series(v2)
+        >>> s1.rolling(4).corr(s2)
+        0         NaN
+        1         NaN
+        2         NaN
+        3    0.333333
+        4    0.916949
+        dtype: float64
+
+        The below example shows a similar rolling calculation on a
+        DataFrame using the pairwise option.
+
+        >>> matrix = np.array([[51., 35.],
+        ...                    [49., 30.],
+        ...                    [47., 32.],
+        ...                    [46., 31.],
+        ...                    [50., 36.]])
+        >>> np.corrcoef(matrix[:-1, 0], matrix[:-1, 1])
+        array([[1.       , 0.6263001],
+               [0.6263001, 1.       ]])
+        >>> np.corrcoef(matrix[1:, 0], matrix[1:, 1])
+        array([[1.        , 0.55536811],
+               [0.55536811, 1.        ]])
+        >>> df = pd.DataFrame(matrix, columns=['X', 'Y'])
+        >>> df
+              X     Y
+        0  51.0  35.0
+        1  49.0  30.0
+        2  47.0  32.0
+        3  46.0  31.0
+        4  50.0  36.0
+        >>> df.rolling(4).corr(pairwise=True)
+                    X         Y
+        0 X       NaN       NaN
+          Y       NaN       NaN
+        1 X       NaN       NaN
+          Y       NaN       NaN
+        2 X       NaN       NaN
+          Y       NaN       NaN
+        3 X  1.000000  0.626300
+          Y  0.626300  1.000000
+        4 X  1.000000  0.555368
+          Y  0.555368  1.000000
+        """
+        ).replace("\n", "", 1),
+        window_method="rolling",
+        aggregation_description="correlation",
+        agg_method="corr",
+    )
+    def corr(
+        self,
+        other: DataFrame | Series | None = None,
+        pairwise: bool | None = None,
+        ddof: int = 1,
+        numeric_only: bool = False,
+    ):
+        return super().corr(
+            other=other,
+            pairwise=pairwise,
+            ddof=ddof,
+            numeric_only=numeric_only,
+        )
+
+
+Rolling.__doc__ = Window.__doc__
+
+
+class RollingGroupby(BaseWindowGroupby, Rolling):
+    """
+    Provide a rolling groupby implementation.
+    """
+
+    _attributes = Rolling._attributes + BaseWindowGroupby._attributes
+
+    def _get_window_indexer(self) -> GroupbyIndexer:
+        """
+        Return an indexer class that will compute the window start and end bounds
+
+        Returns
+        -------
+        GroupbyIndexer
+        """
+        rolling_indexer: type[BaseIndexer]
+        indexer_kwargs: dict[str, Any] | None = None
+        index_array = self._index_array
+        if isinstance(self.window, BaseIndexer):
+            rolling_indexer = type(self.window)
+            indexer_kwargs = self.window.__dict__.copy()
+            assert isinstance(indexer_kwargs, dict)  # for mypy
+            # We'll be using the index of each group later
+            indexer_kwargs.pop("index_array", None)
+            window = self.window
+        elif self._win_freq_i8 is not None:
+            rolling_indexer = VariableWindowIndexer
+            # error: Incompatible types in assignment (expression has type
+            # "int", variable has type "BaseIndexer")
+            window = self._win_freq_i8  # type: ignore[assignment]
+        else:
+            rolling_indexer = FixedWindowIndexer
+            window = self.window
+        window_indexer = GroupbyIndexer(
+            index_array=index_array,
+            window_size=window,
+            groupby_indices=self._grouper.indices,
+            window_indexer=rolling_indexer,
+            indexer_kwargs=indexer_kwargs,
+        )
+        return window_indexer
+
+    def _validate_datetimelike_monotonic(self):
+        """
+        Validate that each group in self._on is monotonic
+        """
+        # GH 46061
+        if self._on.hasnans:
+            self._raise_monotonic_error("values must not have NaT")
+        for group_indices in self._grouper.indices.values():
+            group_on = self._on.take(group_indices)
+            if not (
+                group_on.is_monotonic_increasing or group_on.is_monotonic_decreasing
+            ):
+                on = "index" if self.on is None else self.on
+                raise ValueError(
+                    f"Each group within {on} must be monotonic. "
+                    f"Sort the values in {on} first."
+                )
diff --git a/.venv/lib/python3.13/site-packages/pandas/errors/__init__.py b/.venv/lib/python3.13/site-packages/pandas/errors/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..01094ba36b9dd5f3414c32a9a4f832b85902e021
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/errors/__init__.py
@@ -0,0 +1,850 @@
+"""
+Expose public exceptions & warnings
+"""
+from __future__ import annotations
+
+import ctypes
+
+from pandas._config.config import OptionError
+
+from pandas._libs.tslibs import (
+    OutOfBoundsDatetime,
+    OutOfBoundsTimedelta,
+)
+
+from pandas.util.version import InvalidVersion
+
+
+class IntCastingNaNError(ValueError):
+    """
+    Exception raised when converting (``astype``) an array with NaN to an integer type.
+
+    Examples
+    --------
+    >>> pd.DataFrame(np.array([[1, np.nan], [2, 3]]), dtype="i8")
+    Traceback (most recent call last):
+    IntCastingNaNError: Cannot convert non-finite values (NA or inf) to integer
+    """
+
+
+class NullFrequencyError(ValueError):
+    """
+    Exception raised when a ``freq`` cannot be null.
+
+    Particularly ``DatetimeIndex.shift``, ``TimedeltaIndex.shift``,
+    ``PeriodIndex.shift``.
+
+    Examples
+    --------
+    >>> df = pd.DatetimeIndex(["2011-01-01 10:00", "2011-01-01"], freq=None)
+    >>> df.shift(2)
+    Traceback (most recent call last):
+    NullFrequencyError: Cannot shift with no freq
+    """
+
+
+class PerformanceWarning(Warning):
+    """
+    Warning raised when there is a possible performance impact.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"jim": [0, 0, 1, 1],
+    ...                    "joe": ["x", "x", "z", "y"],
+    ...                    "jolie": [1, 2, 3, 4]})
+    >>> df = df.set_index(["jim", "joe"])
+    >>> df
+              jolie
+    jim  joe
+    0    x    1
+         x    2
+    1    z    3
+         y    4
+    >>> df.loc[(1, 'z')]  # doctest: +SKIP
+    # PerformanceWarning: indexing past lexsort depth may impact performance.
+    df.loc[(1, 'z')]
+              jolie
+    jim  joe
+    1    z        3
+    """
+
+
+class UnsupportedFunctionCall(ValueError):
+    """
+    Exception raised when attempting to call a unsupported numpy function.
+
+    For example, ``np.cumsum(groupby_object)``.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"A": [0, 0, 1, 1],
+    ...                    "B": ["x", "x", "z", "y"],
+    ...                    "C": [1, 2, 3, 4]}
+    ...                   )
+    >>> np.cumsum(df.groupby(["A"]))
+    Traceback (most recent call last):
+    UnsupportedFunctionCall: numpy operations are not valid with groupby.
+    Use .groupby(...).cumsum() instead
+    """
+
+
+class UnsortedIndexError(KeyError):
+    """
+    Error raised when slicing a MultiIndex which has not been lexsorted.
+
+    Subclass of `KeyError`.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"cat": [0, 0, 1, 1],
+    ...                    "color": ["white", "white", "brown", "black"],
+    ...                    "lives": [4, 4, 3, 7]},
+    ...                   )
+    >>> df = df.set_index(["cat", "color"])
+    >>> df
+                lives
+    cat  color
+    0    white    4
+         white    4
+    1    brown    3
+         black    7
+    >>> df.loc[(0, "black"):(1, "white")]
+    Traceback (most recent call last):
+    UnsortedIndexError: 'Key length (2) was greater
+    than MultiIndex lexsort depth (1)'
+    """
+
+
+class ParserError(ValueError):
+    """
+    Exception that is raised by an error encountered in parsing file contents.
+
+    This is a generic error raised for errors encountered when functions like
+    `read_csv` or `read_html` are parsing contents of a file.
+
+    See Also
+    --------
+    read_csv : Read CSV (comma-separated) file into a DataFrame.
+    read_html : Read HTML table into a DataFrame.
+
+    Examples
+    --------
+    >>> data = '''a,b,c
+    ... cat,foo,bar
+    ... dog,foo,"baz'''
+    >>> from io import StringIO
+    >>> pd.read_csv(StringIO(data), skipfooter=1, engine='python')
+    Traceback (most recent call last):
+    ParserError: ',' expected after '"'. Error could possibly be due
+    to parsing errors in the skipped footer rows
+    """
+
+
+class DtypeWarning(Warning):
+    """
+    Warning raised when reading different dtypes in a column from a file.
+
+    Raised for a dtype incompatibility. This can happen whenever `read_csv`
+    or `read_table` encounter non-uniform dtypes in a column(s) of a given
+    CSV file.
+
+    See Also
+    --------
+    read_csv : Read CSV (comma-separated) file into a DataFrame.
+    read_table : Read general delimited file into a DataFrame.
+
+    Notes
+    -----
+    This warning is issued when dealing with larger files because the dtype
+    checking happens per chunk read.
+
+    Despite the warning, the CSV file is read with mixed types in a single
+    column which will be an object type. See the examples below to better
+    understand this issue.
+
+    Examples
+    --------
+    This example creates and reads a large CSV file with a column that contains
+    `int` and `str`.
+
+    >>> df = pd.DataFrame({'a': (['1'] * 100000 + ['X'] * 100000 +
+    ...                          ['1'] * 100000),
+    ...                    'b': ['b'] * 300000})  # doctest: +SKIP
+    >>> df.to_csv('test.csv', index=False)  # doctest: +SKIP
+    >>> df2 = pd.read_csv('test.csv')  # doctest: +SKIP
+    ... # DtypeWarning: Columns (0) have mixed types
+
+    Important to notice that ``df2`` will contain both `str` and `int` for the
+    same input, '1'.
+
+    >>> df2.iloc[262140, 0]  # doctest: +SKIP
+    '1'
+    >>> type(df2.iloc[262140, 0])  # doctest: +SKIP
+    
+    >>> df2.iloc[262150, 0]  # doctest: +SKIP
+    1
+    >>> type(df2.iloc[262150, 0])  # doctest: +SKIP
+    
+
+    One way to solve this issue is using the `dtype` parameter in the
+    `read_csv` and `read_table` functions to explicit the conversion:
+
+    >>> df2 = pd.read_csv('test.csv', sep=',', dtype={'a': str})  # doctest: +SKIP
+
+    No warning was issued.
+    """
+
+
+class EmptyDataError(ValueError):
+    """
+    Exception raised in ``pd.read_csv`` when empty data or header is encountered.
+
+    Examples
+    --------
+    >>> from io import StringIO
+    >>> empty = StringIO()
+    >>> pd.read_csv(empty)
+    Traceback (most recent call last):
+    EmptyDataError: No columns to parse from file
+    """
+
+
+class ParserWarning(Warning):
+    """
+    Warning raised when reading a file that doesn't use the default 'c' parser.
+
+    Raised by `pd.read_csv` and `pd.read_table` when it is necessary to change
+    parsers, generally from the default 'c' parser to 'python'.
+
+    It happens due to a lack of support or functionality for parsing a
+    particular attribute of a CSV file with the requested engine.
+
+    Currently, 'c' unsupported options include the following parameters:
+
+    1. `sep` other than a single character (e.g. regex separators)
+    2. `skipfooter` higher than 0
+    3. `sep=None` with `delim_whitespace=False`
+
+    The warning can be avoided by adding `engine='python'` as a parameter in
+    `pd.read_csv` and `pd.read_table` methods.
+
+    See Also
+    --------
+    pd.read_csv : Read CSV (comma-separated) file into DataFrame.
+    pd.read_table : Read general delimited file into DataFrame.
+
+    Examples
+    --------
+    Using a `sep` in `pd.read_csv` other than a single character:
+
+    >>> import io
+    >>> csv = '''a;b;c
+    ...           1;1,8
+    ...           1;2,1'''
+    >>> df = pd.read_csv(io.StringIO(csv), sep='[;,]')  # doctest: +SKIP
+    ... # ParserWarning: Falling back to the 'python' engine...
+
+    Adding `engine='python'` to `pd.read_csv` removes the Warning:
+
+    >>> df = pd.read_csv(io.StringIO(csv), sep='[;,]', engine='python')
+    """
+
+
+class MergeError(ValueError):
+    """
+    Exception raised when merging data.
+
+    Subclass of ``ValueError``.
+
+    Examples
+    --------
+    >>> left = pd.DataFrame({"a": ["a", "b", "b", "d"],
+    ...                     "b": ["cat", "dog", "weasel", "horse"]},
+    ...                     index=range(4))
+    >>> right = pd.DataFrame({"a": ["a", "b", "c", "d"],
+    ...                      "c": ["meow", "bark", "chirp", "nay"]},
+    ...                      index=range(4)).set_index("a")
+    >>> left.join(right, on="a", validate="one_to_one",)
+    Traceback (most recent call last):
+    MergeError: Merge keys are not unique in left dataset; not a one-to-one merge
+    """
+
+
+class AbstractMethodError(NotImplementedError):
+    """
+    Raise this error instead of NotImplementedError for abstract methods.
+
+    Examples
+    --------
+    >>> class Foo:
+    ...     @classmethod
+    ...     def classmethod(cls):
+    ...         raise pd.errors.AbstractMethodError(cls, methodtype="classmethod")
+    ...     def method(self):
+    ...         raise pd.errors.AbstractMethodError(self)
+    >>> test = Foo.classmethod()
+    Traceback (most recent call last):
+    AbstractMethodError: This classmethod must be defined in the concrete class Foo
+
+    >>> test2 = Foo().method()
+    Traceback (most recent call last):
+    AbstractMethodError: This classmethod must be defined in the concrete class Foo
+    """
+
+    def __init__(self, class_instance, methodtype: str = "method") -> None:
+        types = {"method", "classmethod", "staticmethod", "property"}
+        if methodtype not in types:
+            raise ValueError(
+                f"methodtype must be one of {methodtype}, got {types} instead."
+            )
+        self.methodtype = methodtype
+        self.class_instance = class_instance
+
+    def __str__(self) -> str:
+        if self.methodtype == "classmethod":
+            name = self.class_instance.__name__
+        else:
+            name = type(self.class_instance).__name__
+        return f"This {self.methodtype} must be defined in the concrete class {name}"
+
+
+class NumbaUtilError(Exception):
+    """
+    Error raised for unsupported Numba engine routines.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"key": ["a", "a", "b", "b"], "data": [1, 2, 3, 4]},
+    ...                   columns=["key", "data"])
+    >>> def incorrect_function(x):
+    ...     return sum(x) * 2.7
+    >>> df.groupby("key").agg(incorrect_function, engine="numba")
+    Traceback (most recent call last):
+    NumbaUtilError: The first 2 arguments to incorrect_function
+    must be ['values', 'index']
+    """
+
+
+class DuplicateLabelError(ValueError):
+    """
+    Error raised when an operation would introduce duplicate labels.
+
+    Examples
+    --------
+    >>> s = pd.Series([0, 1, 2], index=['a', 'b', 'c']).set_flags(
+    ...     allows_duplicate_labels=False
+    ... )
+    >>> s.reindex(['a', 'a', 'b'])
+    Traceback (most recent call last):
+       ...
+    DuplicateLabelError: Index has duplicates.
+          positions
+    label
+    a        [0, 1]
+    """
+
+
+class InvalidIndexError(Exception):
+    """
+    Exception raised when attempting to use an invalid index key.
+
+    Examples
+    --------
+    >>> idx = pd.MultiIndex.from_product([["x", "y"], [0, 1]])
+    >>> df = pd.DataFrame([[1, 1, 2, 2],
+    ...                   [3, 3, 4, 4]], columns=idx)
+    >>> df
+        x       y
+        0   1   0   1
+    0   1   1   2   2
+    1   3   3   4   4
+    >>> df[:, 0]
+    Traceback (most recent call last):
+    InvalidIndexError: (slice(None, None, None), 0)
+    """
+
+
+class DataError(Exception):
+    """
+    Exceptionn raised when performing an operation on non-numerical data.
+
+    For example, calling ``ohlc`` on a non-numerical column or a function
+    on a rolling window.
+
+    Examples
+    --------
+    >>> ser = pd.Series(['a', 'b', 'c'])
+    >>> ser.rolling(2).sum()
+    Traceback (most recent call last):
+    DataError: No numeric types to aggregate
+    """
+
+
+class SpecificationError(Exception):
+    """
+    Exception raised by ``agg`` when the functions are ill-specified.
+
+    The exception raised in two scenarios.
+
+    The first way is calling ``agg`` on a
+    Dataframe or Series using a nested renamer (dict-of-dict).
+
+    The second way is calling ``agg`` on a Dataframe with duplicated functions
+    names without assigning column name.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2],
+    ...                    'B': range(5),
+    ...                    'C': range(5)})
+    >>> df.groupby('A').B.agg({'foo': 'count'}) # doctest: +SKIP
+    ... # SpecificationError: nested renamer is not supported
+
+    >>> df.groupby('A').agg({'B': {'foo': ['sum', 'max']}}) # doctest: +SKIP
+    ... # SpecificationError: nested renamer is not supported
+
+    >>> df.groupby('A').agg(['min', 'min']) # doctest: +SKIP
+    ... # SpecificationError: nested renamer is not supported
+    """
+
+
+class SettingWithCopyError(ValueError):
+    """
+    Exception raised when trying to set on a copied slice from a ``DataFrame``.
+
+    The ``mode.chained_assignment`` needs to be set to set to 'raise.' This can
+    happen unintentionally when chained indexing.
+
+    For more information on evaluation order,
+    see :ref:`the user guide`.
+
+    For more information on view vs. copy,
+    see :ref:`the user guide`.
+
+    Examples
+    --------
+    >>> pd.options.mode.chained_assignment = 'raise'
+    >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
+    >>> df.loc[0:3]['A'] = 'a' # doctest: +SKIP
+    ... # SettingWithCopyError: A value is trying to be set on a copy of a...
+    """
+
+
+class SettingWithCopyWarning(Warning):
+    """
+    Warning raised when trying to set on a copied slice from a ``DataFrame``.
+
+    The ``mode.chained_assignment`` needs to be set to set to 'warn.'
+    'Warn' is the default option. This can happen unintentionally when
+    chained indexing.
+
+    For more information on evaluation order,
+    see :ref:`the user guide`.
+
+    For more information on view vs. copy,
+    see :ref:`the user guide`.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
+    >>> df.loc[0:3]['A'] = 'a' # doctest: +SKIP
+    ... # SettingWithCopyWarning: A value is trying to be set on a copy of a...
+    """
+
+
+class ChainedAssignmentError(Warning):
+    """
+    Warning raised when trying to set using chained assignment.
+
+    When the ``mode.copy_on_write`` option is enabled, chained assignment can
+    never work. In such a situation, we are always setting into a temporary
+    object that is the result of an indexing operation (getitem), which under
+    Copy-on-Write always behaves as a copy. Thus, assigning through a chain
+    can never update the original Series or DataFrame.
+
+    For more information on view vs. copy,
+    see :ref:`the user guide`.
+
+    Examples
+    --------
+    >>> pd.options.mode.copy_on_write = True
+    >>> df = pd.DataFrame({'A': [1, 1, 1, 2, 2]}, columns=['A'])
+    >>> df["A"][0:3] = 10 # doctest: +SKIP
+    ... # ChainedAssignmentError: ...
+    >>> pd.options.mode.copy_on_write = False
+    """
+
+
+_chained_assignment_msg = (
+    "A value is trying to be set on a copy of a DataFrame or Series "
+    "through chained assignment.\n"
+    "When using the Copy-on-Write mode, such chained assignment never works "
+    "to update the original DataFrame or Series, because the intermediate "
+    "object on which we are setting values always behaves as a copy.\n\n"
+    "Try using '.loc[row_indexer, col_indexer] = value' instead, to perform "
+    "the assignment in a single step.\n\n"
+    "See the caveats in the documentation: "
+    "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
+    "indexing.html#returning-a-view-versus-a-copy"
+)
+
+
+_chained_assignment_method_msg = (
+    "A value is trying to be set on a copy of a DataFrame or Series "
+    "through chained assignment using an inplace method.\n"
+    "When using the Copy-on-Write mode, such inplace method never works "
+    "to update the original DataFrame or Series, because the intermediate "
+    "object on which we are setting values always behaves as a copy.\n\n"
+    "For example, when doing 'df[col].method(value, inplace=True)', try "
+    "using 'df.method({col: value}, inplace=True)' instead, to perform "
+    "the operation inplace on the original object.\n\n"
+)
+
+
+_chained_assignment_warning_msg = (
+    "ChainedAssignmentError: behaviour will change in pandas 3.0!\n"
+    "You are setting values through chained assignment. Currently this works "
+    "in certain cases, but when using Copy-on-Write (which will become the "
+    "default behaviour in pandas 3.0) this will never work to update the "
+    "original DataFrame or Series, because the intermediate object on which "
+    "we are setting values will behave as a copy.\n"
+    "A typical example is when you are setting values in a column of a "
+    "DataFrame, like:\n\n"
+    'df["col"][row_indexer] = value\n\n'
+    'Use `df.loc[row_indexer, "col"] = values` instead, to perform the '
+    "assignment in a single step and ensure this keeps updating the original `df`.\n\n"
+    "See the caveats in the documentation: "
+    "https://pandas.pydata.org/pandas-docs/stable/user_guide/"
+    "indexing.html#returning-a-view-versus-a-copy\n"
+)
+
+
+_chained_assignment_warning_method_msg = (
+    "A value is trying to be set on a copy of a DataFrame or Series "
+    "through chained assignment using an inplace method.\n"
+    "The behavior will change in pandas 3.0. This inplace method will "
+    "never work because the intermediate object on which we are setting "
+    "values always behaves as a copy.\n\n"
+    "For example, when doing 'df[col].method(value, inplace=True)', try "
+    "using 'df.method({col: value}, inplace=True)' or "
+    "df[col] = df[col].method(value) instead, to perform "
+    "the operation inplace on the original object.\n\n"
+)
+
+
+def _check_cacher(obj):
+    # This is a mess, selection paths that return a view set the _cacher attribute
+    # on the Series; most of them also set _item_cache which adds 1 to our relevant
+    # reference count, but iloc does not, so we have to check if we are actually
+    # in the item cache
+    if hasattr(obj, "_cacher"):
+        parent = obj._cacher[1]()
+        # parent could be dead
+        if parent is None:
+            return False
+        if hasattr(parent, "_item_cache"):
+            if obj._cacher[0] in parent._item_cache:
+                # Check if we are actually the item from item_cache, iloc creates a
+                # new object
+                return obj is parent._item_cache[obj._cacher[0]]
+    return False
+
+
+class NumExprClobberingError(NameError):
+    """
+    Exception raised when trying to use a built-in numexpr name as a variable name.
+
+    ``eval`` or ``query`` will throw the error if the engine is set
+    to 'numexpr'. 'numexpr' is the default engine value for these methods if the
+    numexpr package is installed.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'abs': [1, 1, 1]})
+    >>> df.query("abs > 2") # doctest: +SKIP
+    ... # NumExprClobberingError: Variables in expression "(abs) > (2)" overlap...
+    >>> sin, a = 1, 2
+    >>> pd.eval("sin + a", engine='numexpr') # doctest: +SKIP
+    ... # NumExprClobberingError: Variables in expression "(sin) + (a)" overlap...
+    """
+
+
+class UndefinedVariableError(NameError):
+    """
+    Exception raised by ``query`` or ``eval`` when using an undefined variable name.
+
+    It will also specify whether the undefined variable is local or not.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'A': [1, 1, 1]})
+    >>> df.query("A > x") # doctest: +SKIP
+    ... # UndefinedVariableError: name 'x' is not defined
+    >>> df.query("A > @y") # doctest: +SKIP
+    ... # UndefinedVariableError: local variable 'y' is not defined
+    >>> pd.eval('x + 1') # doctest: +SKIP
+    ... # UndefinedVariableError: name 'x' is not defined
+    """
+
+    def __init__(self, name: str, is_local: bool | None = None) -> None:
+        base_msg = f"{repr(name)} is not defined"
+        if is_local:
+            msg = f"local variable {base_msg}"
+        else:
+            msg = f"name {base_msg}"
+        super().__init__(msg)
+
+
+class IndexingError(Exception):
+    """
+    Exception is raised when trying to index and there is a mismatch in dimensions.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'A': [1, 1, 1]})
+    >>> df.loc[..., ..., 'A'] # doctest: +SKIP
+    ... # IndexingError: indexer may only contain one '...' entry
+    >>> df = pd.DataFrame({'A': [1, 1, 1]})
+    >>> df.loc[1, ..., ...] # doctest: +SKIP
+    ... # IndexingError: Too many indexers
+    >>> df[pd.Series([True], dtype=bool)] # doctest: +SKIP
+    ... # IndexingError: Unalignable boolean Series provided as indexer...
+    >>> s = pd.Series(range(2),
+    ...               index = pd.MultiIndex.from_product([["a", "b"], ["c"]]))
+    >>> s.loc["a", "c", "d"] # doctest: +SKIP
+    ... # IndexingError: Too many indexers
+    """
+
+
+class PyperclipException(RuntimeError):
+    """
+    Exception raised when clipboard functionality is unsupported.
+
+    Raised by ``to_clipboard()`` and ``read_clipboard()``.
+    """
+
+
+class PyperclipWindowsException(PyperclipException):
+    """
+    Exception raised when clipboard functionality is unsupported by Windows.
+
+    Access to the clipboard handle would be denied due to some other
+    window process is accessing it.
+    """
+
+    def __init__(self, message: str) -> None:
+        # attr only exists on Windows, so typing fails on other platforms
+        message += f" ({ctypes.WinError()})"  # type: ignore[attr-defined]
+        super().__init__(message)
+
+
+class CSSWarning(UserWarning):
+    """
+    Warning is raised when converting css styling fails.
+
+    This can be due to the styling not having an equivalent value or because the
+    styling isn't properly formatted.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({'A': [1, 1, 1]})
+    >>> df.style.applymap(
+    ...     lambda x: 'background-color: blueGreenRed;'
+    ... ).to_excel('styled.xlsx')  # doctest: +SKIP
+    CSSWarning: Unhandled color format: 'blueGreenRed'
+    >>> df.style.applymap(
+    ...     lambda x: 'border: 1px solid red red;'
+    ... ).to_excel('styled.xlsx')  # doctest: +SKIP
+    CSSWarning: Unhandled color format: 'blueGreenRed'
+    """
+
+
+class PossibleDataLossError(Exception):
+    """
+    Exception raised when trying to open a HDFStore file when already opened.
+
+    Examples
+    --------
+    >>> store = pd.HDFStore('my-store', 'a') # doctest: +SKIP
+    >>> store.open("w") # doctest: +SKIP
+    ... # PossibleDataLossError: Re-opening the file [my-store] with mode [a]...
+    """
+
+
+class ClosedFileError(Exception):
+    """
+    Exception is raised when trying to perform an operation on a closed HDFStore file.
+
+    Examples
+    --------
+    >>> store = pd.HDFStore('my-store', 'a') # doctest: +SKIP
+    >>> store.close() # doctest: +SKIP
+    >>> store.keys() # doctest: +SKIP
+    ... # ClosedFileError: my-store file is not open!
+    """
+
+
+class IncompatibilityWarning(Warning):
+    """
+    Warning raised when trying to use where criteria on an incompatible HDF5 file.
+    """
+
+
+class AttributeConflictWarning(Warning):
+    """
+    Warning raised when index attributes conflict when using HDFStore.
+
+    Occurs when attempting to append an index with a different
+    name than the existing index on an HDFStore or attempting to append an index with a
+    different frequency than the existing index on an HDFStore.
+
+    Examples
+    --------
+    >>> idx1 = pd.Index(['a', 'b'], name='name1')
+    >>> df1 = pd.DataFrame([[1, 2], [3, 4]], index=idx1)
+    >>> df1.to_hdf('file', 'data', 'w', append=True)  # doctest: +SKIP
+    >>> idx2 = pd.Index(['c', 'd'], name='name2')
+    >>> df2 = pd.DataFrame([[5, 6], [7, 8]], index=idx2)
+    >>> df2.to_hdf('file', 'data', 'a', append=True)  # doctest: +SKIP
+    AttributeConflictWarning: the [index_name] attribute of the existing index is
+    [name1] which conflicts with the new [name2]...
+    """
+
+
+class DatabaseError(OSError):
+    """
+    Error is raised when executing sql with bad syntax or sql that throws an error.
+
+    Examples
+    --------
+    >>> from sqlite3 import connect
+    >>> conn = connect(':memory:')
+    >>> pd.read_sql('select * test', conn) # doctest: +SKIP
+    ... # DatabaseError: Execution failed on sql 'test': near "test": syntax error
+    """
+
+
+class PossiblePrecisionLoss(Warning):
+    """
+    Warning raised by to_stata on a column with a value outside or equal to int64.
+
+    When the column value is outside or equal to the int64 value the column is
+    converted to a float64 dtype.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"s": pd.Series([1, 2**53], dtype=np.int64)})
+    >>> df.to_stata('test') # doctest: +SKIP
+    ... # PossiblePrecisionLoss: Column converted from int64 to float64...
+    """
+
+
+class ValueLabelTypeMismatch(Warning):
+    """
+    Warning raised by to_stata on a category column that contains non-string values.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"categories": pd.Series(["a", 2], dtype="category")})
+    >>> df.to_stata('test') # doctest: +SKIP
+    ... # ValueLabelTypeMismatch: Stata value labels (pandas categories) must be str...
+    """
+
+
+class InvalidColumnName(Warning):
+    """
+    Warning raised by to_stata the column contains a non-valid stata name.
+
+    Because the column name is an invalid Stata variable, the name needs to be
+    converted.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame({"0categories": pd.Series([2, 2])})
+    >>> df.to_stata('test') # doctest: +SKIP
+    ... # InvalidColumnName: Not all pandas column names were valid Stata variable...
+    """
+
+
+class CategoricalConversionWarning(Warning):
+    """
+    Warning is raised when reading a partial labeled Stata file using a iterator.
+
+    Examples
+    --------
+    >>> from pandas.io.stata import StataReader
+    >>> with StataReader('dta_file', chunksize=2) as reader: # doctest: +SKIP
+    ...   for i, block in enumerate(reader):
+    ...      print(i, block)
+    ... # CategoricalConversionWarning: One or more series with value labels...
+    """
+
+
+class LossySetitemError(Exception):
+    """
+    Raised when trying to do a __setitem__ on an np.ndarray that is not lossless.
+
+    Notes
+    -----
+    This is an internal error.
+    """
+
+
+class NoBufferPresent(Exception):
+    """
+    Exception is raised in _get_data_buffer to signal that there is no requested buffer.
+    """
+
+
+class InvalidComparison(Exception):
+    """
+    Exception is raised by _validate_comparison_value to indicate an invalid comparison.
+
+    Notes
+    -----
+    This is an internal error.
+    """
+
+
+__all__ = [
+    "AbstractMethodError",
+    "AttributeConflictWarning",
+    "CategoricalConversionWarning",
+    "ClosedFileError",
+    "CSSWarning",
+    "DatabaseError",
+    "DataError",
+    "DtypeWarning",
+    "DuplicateLabelError",
+    "EmptyDataError",
+    "IncompatibilityWarning",
+    "IntCastingNaNError",
+    "InvalidColumnName",
+    "InvalidComparison",
+    "InvalidIndexError",
+    "InvalidVersion",
+    "IndexingError",
+    "LossySetitemError",
+    "MergeError",
+    "NoBufferPresent",
+    "NullFrequencyError",
+    "NumbaUtilError",
+    "NumExprClobberingError",
+    "OptionError",
+    "OutOfBoundsDatetime",
+    "OutOfBoundsTimedelta",
+    "ParserError",
+    "ParserWarning",
+    "PerformanceWarning",
+    "PossibleDataLossError",
+    "PossiblePrecisionLoss",
+    "PyperclipException",
+    "PyperclipWindowsException",
+    "SettingWithCopyError",
+    "SettingWithCopyWarning",
+    "SpecificationError",
+    "UndefinedVariableError",
+    "UnsortedIndexError",
+    "UnsupportedFunctionCall",
+    "ValueLabelTypeMismatch",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..c804b81c49e7c8abb406f2132909df6036df1c09
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/__init__.py
@@ -0,0 +1,13 @@
+# ruff: noqa: TCH004
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # import modules that have public classes/functions
+    from pandas.io import (
+        formats,
+        json,
+        stata,
+    )
+
+    # mark only those modules as public
+    __all__ = ["formats", "json", "stata"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/_util.py b/.venv/lib/python3.13/site-packages/pandas/io/_util.py
new file mode 100644
index 0000000000000000000000000000000000000000..35fdfb1a9ee82b4e09afc2da35bb89cdc5f10739
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/_util.py
@@ -0,0 +1,94 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+)
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import lib
+from pandas.compat import (
+    pa_version_under18p0,
+    pa_version_under19p0,
+)
+from pandas.compat._optional import import_optional_dependency
+
+import pandas as pd
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import pyarrow
+
+    from pandas._typing import DtypeBackend
+
+
+def _arrow_dtype_mapping() -> dict:
+    pa = import_optional_dependency("pyarrow")
+    return {
+        pa.int8(): pd.Int8Dtype(),
+        pa.int16(): pd.Int16Dtype(),
+        pa.int32(): pd.Int32Dtype(),
+        pa.int64(): pd.Int64Dtype(),
+        pa.uint8(): pd.UInt8Dtype(),
+        pa.uint16(): pd.UInt16Dtype(),
+        pa.uint32(): pd.UInt32Dtype(),
+        pa.uint64(): pd.UInt64Dtype(),
+        pa.bool_(): pd.BooleanDtype(),
+        pa.string(): pd.StringDtype(),
+        pa.float32(): pd.Float32Dtype(),
+        pa.float64(): pd.Float64Dtype(),
+        pa.string(): pd.StringDtype(),
+        pa.large_string(): pd.StringDtype(),
+    }
+
+
+def _arrow_string_types_mapper() -> Callable:
+    pa = import_optional_dependency("pyarrow")
+
+    mapping = {
+        pa.string(): pd.StringDtype(na_value=np.nan),
+        pa.large_string(): pd.StringDtype(na_value=np.nan),
+    }
+    if not pa_version_under18p0:
+        mapping[pa.string_view()] = pd.StringDtype(na_value=np.nan)
+
+    return mapping.get
+
+
+def arrow_table_to_pandas(
+    table: pyarrow.Table,
+    dtype_backend: DtypeBackend | Literal["numpy"] | lib.NoDefault = lib.no_default,
+    null_to_int64: bool = False,
+    to_pandas_kwargs: dict | None = None,
+) -> pd.DataFrame:
+    if to_pandas_kwargs is None:
+        to_pandas_kwargs = {}
+
+    pa = import_optional_dependency("pyarrow")
+
+    types_mapper: type[pd.ArrowDtype] | None | Callable
+    if dtype_backend == "numpy_nullable":
+        mapping = _arrow_dtype_mapping()
+        if null_to_int64:
+            # Modify the default mapping to also map null to Int64
+            # (to match other engines - only for CSV parser)
+            mapping[pa.null()] = pd.Int64Dtype()
+        types_mapper = mapping.get
+    elif dtype_backend == "pyarrow":
+        types_mapper = pd.ArrowDtype
+    elif using_string_dtype():
+        if pa_version_under19p0:
+            types_mapper = _arrow_string_types_mapper()
+        else:
+            types_mapper = None
+    elif dtype_backend is lib.no_default or dtype_backend == "numpy":
+        types_mapper = None
+    else:
+        raise NotImplementedError
+
+    df = table.to_pandas(types_mapper=types_mapper, **to_pandas_kwargs)
+    return df
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/api.py b/.venv/lib/python3.13/site-packages/pandas/io/api.py
new file mode 100644
index 0000000000000000000000000000000000000000..4e8b34a61dfc62992a37d9fab3263ee00a28d1fc
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/api.py
@@ -0,0 +1,65 @@
+"""
+Data IO api
+"""
+
+from pandas.io.clipboards import read_clipboard
+from pandas.io.excel import (
+    ExcelFile,
+    ExcelWriter,
+    read_excel,
+)
+from pandas.io.feather_format import read_feather
+from pandas.io.gbq import read_gbq
+from pandas.io.html import read_html
+from pandas.io.json import read_json
+from pandas.io.orc import read_orc
+from pandas.io.parquet import read_parquet
+from pandas.io.parsers import (
+    read_csv,
+    read_fwf,
+    read_table,
+)
+from pandas.io.pickle import (
+    read_pickle,
+    to_pickle,
+)
+from pandas.io.pytables import (
+    HDFStore,
+    read_hdf,
+)
+from pandas.io.sas import read_sas
+from pandas.io.spss import read_spss
+from pandas.io.sql import (
+    read_sql,
+    read_sql_query,
+    read_sql_table,
+)
+from pandas.io.stata import read_stata
+from pandas.io.xml import read_xml
+
+__all__ = [
+    "ExcelFile",
+    "ExcelWriter",
+    "HDFStore",
+    "read_clipboard",
+    "read_csv",
+    "read_excel",
+    "read_feather",
+    "read_fwf",
+    "read_gbq",
+    "read_hdf",
+    "read_html",
+    "read_json",
+    "read_orc",
+    "read_parquet",
+    "read_pickle",
+    "read_sas",
+    "read_spss",
+    "read_sql",
+    "read_sql_query",
+    "read_sql_table",
+    "read_stata",
+    "read_table",
+    "read_xml",
+    "to_pickle",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/clipboard/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/clipboard/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..6491849925e863c35a98390a31729cb13e28ca19
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/clipboard/__init__.py
@@ -0,0 +1,747 @@
+"""
+Pyperclip
+
+A cross-platform clipboard module for Python,
+with copy & paste functions for plain text.
+By Al Sweigart al@inventwithpython.com
+Licence at LICENSES/PYPERCLIP_LICENSE
+
+Usage:
+  import pyperclip
+  pyperclip.copy('The text to be copied to the clipboard.')
+  spam = pyperclip.paste()
+
+  if not pyperclip.is_available():
+    print("Copy functionality unavailable!")
+
+On Windows, no additional modules are needed.
+On Mac, the pyobjc module is used, falling back to the pbcopy and pbpaste cli
+    commands. (These commands should come with OS X.).
+On Linux, install xclip, xsel, or wl-clipboard (for "wayland" sessions) via
+package manager.
+For example, in Debian:
+    sudo apt-get install xclip
+    sudo apt-get install xsel
+    sudo apt-get install wl-clipboard
+
+Otherwise on Linux, you will need the PyQt5 modules installed.
+
+This module does not work with PyGObject yet.
+
+Cygwin is currently not supported.
+
+Security Note: This module runs programs with these names:
+    - pbcopy
+    - pbpaste
+    - xclip
+    - xsel
+    - wl-copy/wl-paste
+    - klipper
+    - qdbus
+A malicious user could rename or add programs with these names, tricking
+Pyperclip into running them with whatever permissions the Python process has.
+
+"""
+
+__version__ = "1.8.2"
+
+
+import contextlib
+import ctypes
+from ctypes import (
+    c_size_t,
+    c_wchar,
+    c_wchar_p,
+    get_errno,
+    sizeof,
+)
+import os
+import platform
+from shutil import which as _executable_exists
+import subprocess
+import time
+import warnings
+
+from pandas.errors import (
+    PyperclipException,
+    PyperclipWindowsException,
+)
+from pandas.util._exceptions import find_stack_level
+
+# `import PyQt4` sys.exit()s if DISPLAY is not in the environment.
+# Thus, we need to detect the presence of $DISPLAY manually
+# and not load PyQt4 if it is absent.
+HAS_DISPLAY = os.getenv("DISPLAY")
+
+EXCEPT_MSG = """
+    Pyperclip could not find a copy/paste mechanism for your system.
+    For more information, please visit
+    https://pyperclip.readthedocs.io/en/latest/index.html#not-implemented-error
+    """
+
+ENCODING = "utf-8"
+
+
+class PyperclipTimeoutException(PyperclipException):
+    pass
+
+
+def _stringifyText(text) -> str:
+    acceptedTypes = (str, int, float, bool)
+    if not isinstance(text, acceptedTypes):
+        raise PyperclipException(
+            f"only str, int, float, and bool values "
+            f"can be copied to the clipboard, not {type(text).__name__}"
+        )
+    return str(text)
+
+
+def init_osx_pbcopy_clipboard():
+    def copy_osx_pbcopy(text):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        with subprocess.Popen(
+            ["pbcopy", "w"], stdin=subprocess.PIPE, close_fds=True
+        ) as p:
+            p.communicate(input=text.encode(ENCODING))
+
+    def paste_osx_pbcopy():
+        with subprocess.Popen(
+            ["pbpaste", "r"], stdout=subprocess.PIPE, close_fds=True
+        ) as p:
+            stdout = p.communicate()[0]
+        return stdout.decode(ENCODING)
+
+    return copy_osx_pbcopy, paste_osx_pbcopy
+
+
+def init_osx_pyobjc_clipboard():
+    def copy_osx_pyobjc(text):
+        """Copy string argument to clipboard"""
+        text = _stringifyText(text)  # Converts non-str values to str.
+        newStr = Foundation.NSString.stringWithString_(text).nsstring()
+        newData = newStr.dataUsingEncoding_(Foundation.NSUTF8StringEncoding)
+        board = AppKit.NSPasteboard.generalPasteboard()
+        board.declareTypes_owner_([AppKit.NSStringPboardType], None)
+        board.setData_forType_(newData, AppKit.NSStringPboardType)
+
+    def paste_osx_pyobjc():
+        """Returns contents of clipboard"""
+        board = AppKit.NSPasteboard.generalPasteboard()
+        content = board.stringForType_(AppKit.NSStringPboardType)
+        return content
+
+    return copy_osx_pyobjc, paste_osx_pyobjc
+
+
+def init_qt_clipboard():
+    global QApplication
+    # $DISPLAY should exist
+
+    # Try to import from qtpy, but if that fails try PyQt5 then PyQt4
+    try:
+        from qtpy.QtWidgets import QApplication
+    except ImportError:
+        try:
+            from PyQt5.QtWidgets import QApplication
+        except ImportError:
+            from PyQt4.QtGui import QApplication
+
+    app = QApplication.instance()
+    if app is None:
+        app = QApplication([])
+
+    def copy_qt(text):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        cb = app.clipboard()
+        cb.setText(text)
+
+    def paste_qt() -> str:
+        cb = app.clipboard()
+        return str(cb.text())
+
+    return copy_qt, paste_qt
+
+
+def init_xclip_clipboard():
+    DEFAULT_SELECTION = "c"
+    PRIMARY_SELECTION = "p"
+
+    def copy_xclip(text, primary=False):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        selection = DEFAULT_SELECTION
+        if primary:
+            selection = PRIMARY_SELECTION
+        with subprocess.Popen(
+            ["xclip", "-selection", selection], stdin=subprocess.PIPE, close_fds=True
+        ) as p:
+            p.communicate(input=text.encode(ENCODING))
+
+    def paste_xclip(primary=False):
+        selection = DEFAULT_SELECTION
+        if primary:
+            selection = PRIMARY_SELECTION
+        with subprocess.Popen(
+            ["xclip", "-selection", selection, "-o"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            close_fds=True,
+        ) as p:
+            stdout = p.communicate()[0]
+        # Intentionally ignore extraneous output on stderr when clipboard is empty
+        return stdout.decode(ENCODING)
+
+    return copy_xclip, paste_xclip
+
+
+def init_xsel_clipboard():
+    DEFAULT_SELECTION = "-b"
+    PRIMARY_SELECTION = "-p"
+
+    def copy_xsel(text, primary=False):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        selection_flag = DEFAULT_SELECTION
+        if primary:
+            selection_flag = PRIMARY_SELECTION
+        with subprocess.Popen(
+            ["xsel", selection_flag, "-i"], stdin=subprocess.PIPE, close_fds=True
+        ) as p:
+            p.communicate(input=text.encode(ENCODING))
+
+    def paste_xsel(primary=False):
+        selection_flag = DEFAULT_SELECTION
+        if primary:
+            selection_flag = PRIMARY_SELECTION
+        with subprocess.Popen(
+            ["xsel", selection_flag, "-o"], stdout=subprocess.PIPE, close_fds=True
+        ) as p:
+            stdout = p.communicate()[0]
+        return stdout.decode(ENCODING)
+
+    return copy_xsel, paste_xsel
+
+
+def init_wl_clipboard():
+    PRIMARY_SELECTION = "-p"
+
+    def copy_wl(text, primary=False):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        args = ["wl-copy"]
+        if primary:
+            args.append(PRIMARY_SELECTION)
+        if not text:
+            args.append("--clear")
+            subprocess.check_call(args, close_fds=True)
+        else:
+            p = subprocess.Popen(args, stdin=subprocess.PIPE, close_fds=True)
+            p.communicate(input=text.encode(ENCODING))
+
+    def paste_wl(primary=False):
+        args = ["wl-paste", "-n"]
+        if primary:
+            args.append(PRIMARY_SELECTION)
+        p = subprocess.Popen(args, stdout=subprocess.PIPE, close_fds=True)
+        stdout, _stderr = p.communicate()
+        return stdout.decode(ENCODING)
+
+    return copy_wl, paste_wl
+
+
+def init_klipper_clipboard():
+    def copy_klipper(text):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        with subprocess.Popen(
+            [
+                "qdbus",
+                "org.kde.klipper",
+                "/klipper",
+                "setClipboardContents",
+                text.encode(ENCODING),
+            ],
+            stdin=subprocess.PIPE,
+            close_fds=True,
+        ) as p:
+            p.communicate(input=None)
+
+    def paste_klipper():
+        with subprocess.Popen(
+            ["qdbus", "org.kde.klipper", "/klipper", "getClipboardContents"],
+            stdout=subprocess.PIPE,
+            close_fds=True,
+        ) as p:
+            stdout = p.communicate()[0]
+
+        # Workaround for https://bugs.kde.org/show_bug.cgi?id=342874
+        # TODO: https://github.com/asweigart/pyperclip/issues/43
+        clipboardContents = stdout.decode(ENCODING)
+        # even if blank, Klipper will append a newline at the end
+        assert len(clipboardContents) > 0
+        # make sure that newline is there
+        assert clipboardContents.endswith("\n")
+        if clipboardContents.endswith("\n"):
+            clipboardContents = clipboardContents[:-1]
+        return clipboardContents
+
+    return copy_klipper, paste_klipper
+
+
+def init_dev_clipboard_clipboard():
+    def copy_dev_clipboard(text):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        if text == "":
+            warnings.warn(
+                "Pyperclip cannot copy a blank string to the clipboard on Cygwin. "
+                "This is effectively a no-op.",
+                stacklevel=find_stack_level(),
+            )
+        if "\r" in text:
+            warnings.warn(
+                "Pyperclip cannot handle \\r characters on Cygwin.",
+                stacklevel=find_stack_level(),
+            )
+
+        with open("/dev/clipboard", "w", encoding="utf-8") as fd:
+            fd.write(text)
+
+    def paste_dev_clipboard() -> str:
+        with open("/dev/clipboard", encoding="utf-8") as fd:
+            content = fd.read()
+        return content
+
+    return copy_dev_clipboard, paste_dev_clipboard
+
+
+def init_no_clipboard():
+    class ClipboardUnavailable:
+        def __call__(self, *args, **kwargs):
+            raise PyperclipException(EXCEPT_MSG)
+
+        def __bool__(self) -> bool:
+            return False
+
+    return ClipboardUnavailable(), ClipboardUnavailable()
+
+
+# Windows-related clipboard functions:
+class CheckedCall:
+    def __init__(self, f) -> None:
+        super().__setattr__("f", f)
+
+    def __call__(self, *args):
+        ret = self.f(*args)
+        if not ret and get_errno():
+            raise PyperclipWindowsException("Error calling " + self.f.__name__)
+        return ret
+
+    def __setattr__(self, key, value):
+        setattr(self.f, key, value)
+
+
+def init_windows_clipboard():
+    global HGLOBAL, LPVOID, DWORD, LPCSTR, INT
+    global HWND, HINSTANCE, HMENU, BOOL, UINT, HANDLE
+    from ctypes.wintypes import (
+        BOOL,
+        DWORD,
+        HANDLE,
+        HGLOBAL,
+        HINSTANCE,
+        HMENU,
+        HWND,
+        INT,
+        LPCSTR,
+        LPVOID,
+        UINT,
+    )
+
+    windll = ctypes.windll
+    msvcrt = ctypes.CDLL("msvcrt")
+
+    safeCreateWindowExA = CheckedCall(windll.user32.CreateWindowExA)
+    safeCreateWindowExA.argtypes = [
+        DWORD,
+        LPCSTR,
+        LPCSTR,
+        DWORD,
+        INT,
+        INT,
+        INT,
+        INT,
+        HWND,
+        HMENU,
+        HINSTANCE,
+        LPVOID,
+    ]
+    safeCreateWindowExA.restype = HWND
+
+    safeDestroyWindow = CheckedCall(windll.user32.DestroyWindow)
+    safeDestroyWindow.argtypes = [HWND]
+    safeDestroyWindow.restype = BOOL
+
+    OpenClipboard = windll.user32.OpenClipboard
+    OpenClipboard.argtypes = [HWND]
+    OpenClipboard.restype = BOOL
+
+    safeCloseClipboard = CheckedCall(windll.user32.CloseClipboard)
+    safeCloseClipboard.argtypes = []
+    safeCloseClipboard.restype = BOOL
+
+    safeEmptyClipboard = CheckedCall(windll.user32.EmptyClipboard)
+    safeEmptyClipboard.argtypes = []
+    safeEmptyClipboard.restype = BOOL
+
+    safeGetClipboardData = CheckedCall(windll.user32.GetClipboardData)
+    safeGetClipboardData.argtypes = [UINT]
+    safeGetClipboardData.restype = HANDLE
+
+    safeSetClipboardData = CheckedCall(windll.user32.SetClipboardData)
+    safeSetClipboardData.argtypes = [UINT, HANDLE]
+    safeSetClipboardData.restype = HANDLE
+
+    safeGlobalAlloc = CheckedCall(windll.kernel32.GlobalAlloc)
+    safeGlobalAlloc.argtypes = [UINT, c_size_t]
+    safeGlobalAlloc.restype = HGLOBAL
+
+    safeGlobalLock = CheckedCall(windll.kernel32.GlobalLock)
+    safeGlobalLock.argtypes = [HGLOBAL]
+    safeGlobalLock.restype = LPVOID
+
+    safeGlobalUnlock = CheckedCall(windll.kernel32.GlobalUnlock)
+    safeGlobalUnlock.argtypes = [HGLOBAL]
+    safeGlobalUnlock.restype = BOOL
+
+    wcslen = CheckedCall(msvcrt.wcslen)
+    wcslen.argtypes = [c_wchar_p]
+    wcslen.restype = UINT
+
+    GMEM_MOVEABLE = 0x0002
+    CF_UNICODETEXT = 13
+
+    @contextlib.contextmanager
+    def window():
+        """
+        Context that provides a valid Windows hwnd.
+        """
+        # we really just need the hwnd, so setting "STATIC"
+        # as predefined lpClass is just fine.
+        hwnd = safeCreateWindowExA(
+            0, b"STATIC", None, 0, 0, 0, 0, 0, None, None, None, None
+        )
+        try:
+            yield hwnd
+        finally:
+            safeDestroyWindow(hwnd)
+
+    @contextlib.contextmanager
+    def clipboard(hwnd):
+        """
+        Context manager that opens the clipboard and prevents
+        other applications from modifying the clipboard content.
+        """
+        # We may not get the clipboard handle immediately because
+        # some other application is accessing it (?)
+        # We try for at least 500ms to get the clipboard.
+        t = time.time() + 0.5
+        success = False
+        while time.time() < t:
+            success = OpenClipboard(hwnd)
+            if success:
+                break
+            time.sleep(0.01)
+        if not success:
+            raise PyperclipWindowsException("Error calling OpenClipboard")
+
+        try:
+            yield
+        finally:
+            safeCloseClipboard()
+
+    def copy_windows(text):
+        # This function is heavily based on
+        # http://msdn.com/ms649016#_win32_Copying_Information_to_the_Clipboard
+
+        text = _stringifyText(text)  # Converts non-str values to str.
+
+        with window() as hwnd:
+            # http://msdn.com/ms649048
+            # If an application calls OpenClipboard with hwnd set to NULL,
+            # EmptyClipboard sets the clipboard owner to NULL;
+            # this causes SetClipboardData to fail.
+            # => We need a valid hwnd to copy something.
+            with clipboard(hwnd):
+                safeEmptyClipboard()
+
+                if text:
+                    # http://msdn.com/ms649051
+                    # If the hMem parameter identifies a memory object,
+                    # the object must have been allocated using the
+                    # function with the GMEM_MOVEABLE flag.
+                    count = wcslen(text) + 1
+                    handle = safeGlobalAlloc(GMEM_MOVEABLE, count * sizeof(c_wchar))
+                    locked_handle = safeGlobalLock(handle)
+
+                    ctypes.memmove(
+                        c_wchar_p(locked_handle),
+                        c_wchar_p(text),
+                        count * sizeof(c_wchar),
+                    )
+
+                    safeGlobalUnlock(handle)
+                    safeSetClipboardData(CF_UNICODETEXT, handle)
+
+    def paste_windows():
+        with clipboard(None):
+            handle = safeGetClipboardData(CF_UNICODETEXT)
+            if not handle:
+                # GetClipboardData may return NULL with errno == NO_ERROR
+                # if the clipboard is empty.
+                # (Also, it may return a handle to an empty buffer,
+                # but technically that's not empty)
+                return ""
+            return c_wchar_p(handle).value
+
+    return copy_windows, paste_windows
+
+
+def init_wsl_clipboard():
+    def copy_wsl(text):
+        text = _stringifyText(text)  # Converts non-str values to str.
+        with subprocess.Popen(["clip.exe"], stdin=subprocess.PIPE, close_fds=True) as p:
+            p.communicate(input=text.encode(ENCODING))
+
+    def paste_wsl():
+        with subprocess.Popen(
+            ["powershell.exe", "-command", "Get-Clipboard"],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            close_fds=True,
+        ) as p:
+            stdout = p.communicate()[0]
+        # WSL appends "\r\n" to the contents.
+        return stdout[:-2].decode(ENCODING)
+
+    return copy_wsl, paste_wsl
+
+
+# Automatic detection of clipboard mechanisms
+# and importing is done in determine_clipboard():
+def determine_clipboard():
+    """
+    Determine the OS/platform and set the copy() and paste() functions
+    accordingly.
+    """
+    global Foundation, AppKit, qtpy, PyQt4, PyQt5
+
+    # Setup for the CYGWIN platform:
+    if (
+        "cygwin" in platform.system().lower()
+    ):  # Cygwin has a variety of values returned by platform.system(),
+        # such as 'CYGWIN_NT-6.1'
+        # FIXME(pyperclip#55): pyperclip currently does not support Cygwin,
+        # see https://github.com/asweigart/pyperclip/issues/55
+        if os.path.exists("/dev/clipboard"):
+            warnings.warn(
+                "Pyperclip's support for Cygwin is not perfect, "
+                "see https://github.com/asweigart/pyperclip/issues/55",
+                stacklevel=find_stack_level(),
+            )
+            return init_dev_clipboard_clipboard()
+
+    # Setup for the WINDOWS platform:
+    elif os.name == "nt" or platform.system() == "Windows":
+        return init_windows_clipboard()
+
+    if platform.system() == "Linux":
+        if _executable_exists("wslconfig.exe"):
+            return init_wsl_clipboard()
+
+    # Setup for the macOS platform:
+    if os.name == "mac" or platform.system() == "Darwin":
+        try:
+            import AppKit
+            import Foundation  # check if pyobjc is installed
+        except ImportError:
+            return init_osx_pbcopy_clipboard()
+        else:
+            return init_osx_pyobjc_clipboard()
+
+    # Setup for the LINUX platform:
+    if HAS_DISPLAY:
+        if os.environ.get("WAYLAND_DISPLAY") and _executable_exists("wl-copy"):
+            return init_wl_clipboard()
+        if _executable_exists("xsel"):
+            return init_xsel_clipboard()
+        if _executable_exists("xclip"):
+            return init_xclip_clipboard()
+        if _executable_exists("klipper") and _executable_exists("qdbus"):
+            return init_klipper_clipboard()
+
+        try:
+            # qtpy is a small abstraction layer that lets you write applications
+            # using a single api call to either PyQt or PySide.
+            # https://pypi.python.org/project/QtPy
+            import qtpy  # check if qtpy is installed
+        except ImportError:
+            # If qtpy isn't installed, fall back on importing PyQt4.
+            try:
+                import PyQt5  # check if PyQt5 is installed
+            except ImportError:
+                try:
+                    import PyQt4  # check if PyQt4 is installed
+                except ImportError:
+                    pass  # We want to fail fast for all non-ImportError exceptions.
+                else:
+                    return init_qt_clipboard()
+            else:
+                return init_qt_clipboard()
+        else:
+            return init_qt_clipboard()
+
+    return init_no_clipboard()
+
+
+def set_clipboard(clipboard):
+    """
+    Explicitly sets the clipboard mechanism. The "clipboard mechanism" is how
+    the copy() and paste() functions interact with the operating system to
+    implement the copy/paste feature. The clipboard parameter must be one of:
+        - pbcopy
+        - pyobjc (default on macOS)
+        - qt
+        - xclip
+        - xsel
+        - klipper
+        - windows (default on Windows)
+        - no (this is what is set when no clipboard mechanism can be found)
+    """
+    global copy, paste
+
+    clipboard_types = {
+        "pbcopy": init_osx_pbcopy_clipboard,
+        "pyobjc": init_osx_pyobjc_clipboard,
+        "qt": init_qt_clipboard,  # TODO - split this into 'qtpy', 'pyqt4', and 'pyqt5'
+        "xclip": init_xclip_clipboard,
+        "xsel": init_xsel_clipboard,
+        "wl-clipboard": init_wl_clipboard,
+        "klipper": init_klipper_clipboard,
+        "windows": init_windows_clipboard,
+        "no": init_no_clipboard,
+    }
+
+    if clipboard not in clipboard_types:
+        allowed_clipboard_types = [repr(_) for _ in clipboard_types]
+        raise ValueError(
+            f"Argument must be one of {', '.join(allowed_clipboard_types)}"
+        )
+
+    # Sets pyperclip's copy() and paste() functions:
+    copy, paste = clipboard_types[clipboard]()
+
+
+def lazy_load_stub_copy(text):
+    """
+    A stub function for copy(), which will load the real copy() function when
+    called so that the real copy() function is used for later calls.
+
+    This allows users to import pyperclip without having determine_clipboard()
+    automatically run, which will automatically select a clipboard mechanism.
+    This could be a problem if it selects, say, the memory-heavy PyQt4 module
+    but the user was just going to immediately call set_clipboard() to use a
+    different clipboard mechanism.
+
+    The lazy loading this stub function implements gives the user a chance to
+    call set_clipboard() to pick another clipboard mechanism. Or, if the user
+    simply calls copy() or paste() without calling set_clipboard() first,
+    will fall back on whatever clipboard mechanism that determine_clipboard()
+    automatically chooses.
+    """
+    global copy, paste
+    copy, paste = determine_clipboard()
+    return copy(text)
+
+
+def lazy_load_stub_paste():
+    """
+    A stub function for paste(), which will load the real paste() function when
+    called so that the real paste() function is used for later calls.
+
+    This allows users to import pyperclip without having determine_clipboard()
+    automatically run, which will automatically select a clipboard mechanism.
+    This could be a problem if it selects, say, the memory-heavy PyQt4 module
+    but the user was just going to immediately call set_clipboard() to use a
+    different clipboard mechanism.
+
+    The lazy loading this stub function implements gives the user a chance to
+    call set_clipboard() to pick another clipboard mechanism. Or, if the user
+    simply calls copy() or paste() without calling set_clipboard() first,
+    will fall back on whatever clipboard mechanism that determine_clipboard()
+    automatically chooses.
+    """
+    global copy, paste
+    copy, paste = determine_clipboard()
+    return paste()
+
+
+def is_available() -> bool:
+    return copy != lazy_load_stub_copy and paste != lazy_load_stub_paste
+
+
+# Initially, copy() and paste() are set to lazy loading wrappers which will
+# set `copy` and `paste` to real functions the first time they're used, unless
+# set_clipboard() or determine_clipboard() is called first.
+copy, paste = lazy_load_stub_copy, lazy_load_stub_paste
+
+
+def waitForPaste(timeout=None):
+    """This function call blocks until a non-empty text string exists on the
+    clipboard. It returns this text.
+
+    This function raises PyperclipTimeoutException if timeout was set to
+    a number of seconds that has elapsed without non-empty text being put on
+    the clipboard."""
+    startTime = time.time()
+    while True:
+        clipboardText = paste()
+        if clipboardText != "":
+            return clipboardText
+        time.sleep(0.01)
+
+        if timeout is not None and time.time() > startTime + timeout:
+            raise PyperclipTimeoutException(
+                "waitForPaste() timed out after " + str(timeout) + " seconds."
+            )
+
+
+def waitForNewPaste(timeout=None):
+    """This function call blocks until a new text string exists on the
+    clipboard that is different from the text that was there when the function
+    was first called. It returns this text.
+
+    This function raises PyperclipTimeoutException if timeout was set to
+    a number of seconds that has elapsed without non-empty text being put on
+    the clipboard."""
+    startTime = time.time()
+    originalText = paste()
+    while True:
+        currentText = paste()
+        if currentText != originalText:
+            return currentText
+        time.sleep(0.01)
+
+        if timeout is not None and time.time() > startTime + timeout:
+            raise PyperclipTimeoutException(
+                "waitForNewPaste() timed out after " + str(timeout) + " seconds."
+            )
+
+
+__all__ = [
+    "copy",
+    "paste",
+    "waitForPaste",
+    "waitForNewPaste",
+    "set_clipboard",
+    "determine_clipboard",
+]
+
+# pandas aliases
+clipboard_get = paste
+clipboard_set = copy
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/clipboards.py b/.venv/lib/python3.13/site-packages/pandas/io/clipboards.py
new file mode 100644
index 0000000000000000000000000000000000000000..a15e37328e9fa95587d53b58b1af10e1e57fd60c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/clipboards.py
@@ -0,0 +1,197 @@
+""" io on the clipboard """
+from __future__ import annotations
+
+from io import StringIO
+from typing import TYPE_CHECKING
+import warnings
+
+from pandas._libs import lib
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.generic import ABCDataFrame
+
+from pandas import (
+    get_option,
+    option_context,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import DtypeBackend
+
+
+def read_clipboard(
+    sep: str = r"\s+",
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    **kwargs,
+):  # pragma: no cover
+    r"""
+    Read text from clipboard and pass to :func:`~pandas.read_csv`.
+
+    Parses clipboard contents similar to how CSV files are parsed
+    using :func:`~pandas.read_csv`.
+
+    Parameters
+    ----------
+    sep : str, default '\\s+'
+        A string or regex delimiter. The default of ``'\\s+'`` denotes
+        one or more whitespace characters.
+
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    **kwargs
+        See :func:`~pandas.read_csv` for the full argument list.
+
+    Returns
+    -------
+    DataFrame
+        A parsed :class:`~pandas.DataFrame` object.
+
+    See Also
+    --------
+    DataFrame.to_clipboard : Copy object to the system clipboard.
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
+    read_fwf : Read a table of fixed-width formatted lines into DataFrame.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], columns=['A', 'B', 'C'])
+    >>> df.to_clipboard()  # doctest: +SKIP
+    >>> pd.read_clipboard()  # doctest: +SKIP
+         A  B  C
+    0    1  2  3
+    1    4  5  6
+    """
+    encoding = kwargs.pop("encoding", "utf-8")
+
+    # only utf-8 is valid for passed value because that's what clipboard
+    # supports
+    if encoding is not None and encoding.lower().replace("-", "") != "utf8":
+        raise NotImplementedError("reading from clipboard only supports utf-8 encoding")
+
+    check_dtype_backend(dtype_backend)
+
+    from pandas.io.clipboard import clipboard_get
+    from pandas.io.parsers import read_csv
+
+    text = clipboard_get()
+
+    # Try to decode (if needed, as "text" might already be a string here).
+    try:
+        text = text.decode(kwargs.get("encoding") or get_option("display.encoding"))
+    except AttributeError:
+        pass
+
+    # Excel copies into clipboard with \t separation
+    # inspect no more then the 10 first lines, if they
+    # all contain an equal number (>0) of tabs, infer
+    # that this came from excel and set 'sep' accordingly
+    lines = text[:10000].split("\n")[:-1][:10]
+
+    # Need to remove leading white space, since read_csv
+    # accepts:
+    #    a  b
+    # 0  1  2
+    # 1  3  4
+
+    counts = {x.lstrip(" ").count("\t") for x in lines}
+    if len(lines) > 1 and len(counts) == 1 and counts.pop() != 0:
+        sep = "\t"
+        # check the number of leading tabs in the first line
+        # to account for index columns
+        index_length = len(lines[0]) - len(lines[0].lstrip(" \t"))
+        if index_length != 0:
+            kwargs.setdefault("index_col", list(range(index_length)))
+
+    # Edge case where sep is specified to be None, return to default
+    if sep is None and kwargs.get("delim_whitespace") is None:
+        sep = r"\s+"
+
+    # Regex separator currently only works with python engine.
+    # Default to python if separator is multi-character (regex)
+    if len(sep) > 1 and kwargs.get("engine") is None:
+        kwargs["engine"] = "python"
+    elif len(sep) > 1 and kwargs.get("engine") == "c":
+        warnings.warn(
+            "read_clipboard with regex separator does not work properly with c engine.",
+            stacklevel=find_stack_level(),
+        )
+
+    return read_csv(StringIO(text), sep=sep, dtype_backend=dtype_backend, **kwargs)
+
+
+def to_clipboard(
+    obj, excel: bool | None = True, sep: str | None = None, **kwargs
+) -> None:  # pragma: no cover
+    """
+    Attempt to write text representation of object to the system clipboard
+    The clipboard can be then pasted into Excel for example.
+
+    Parameters
+    ----------
+    obj : the object to write to the clipboard
+    excel : bool, defaults to True
+            if True, use the provided separator, writing in a csv
+            format for allowing easy pasting into excel.
+            if False, write a string representation of the object
+            to the clipboard
+    sep : optional, defaults to tab
+    other keywords are passed to to_csv
+
+    Notes
+    -----
+    Requirements for your platform
+      - Linux: xclip, or xsel (with PyQt4 modules)
+      - Windows:
+      - OS X:
+    """
+    encoding = kwargs.pop("encoding", "utf-8")
+
+    # testing if an invalid encoding is passed to clipboard
+    if encoding is not None and encoding.lower().replace("-", "") != "utf8":
+        raise ValueError("clipboard only supports utf-8 encoding")
+
+    from pandas.io.clipboard import clipboard_set
+
+    if excel is None:
+        excel = True
+
+    if excel:
+        try:
+            if sep is None:
+                sep = "\t"
+            buf = StringIO()
+
+            # clipboard_set (pyperclip) expects unicode
+            obj.to_csv(buf, sep=sep, encoding="utf-8", **kwargs)
+            text = buf.getvalue()
+
+            clipboard_set(text)
+            return
+        except TypeError:
+            warnings.warn(
+                "to_clipboard in excel mode requires a single character separator.",
+                stacklevel=find_stack_level(),
+            )
+    elif sep is not None:
+        warnings.warn(
+            "to_clipboard with excel=False ignores the sep argument.",
+            stacklevel=find_stack_level(),
+        )
+
+    if isinstance(obj, ABCDataFrame):
+        # str(df) has various unhelpful defaults, like truncation
+        with option_context("display.max_colwidth", None):
+            objstr = obj.to_string(**kwargs)
+    else:
+        objstr = str(obj)
+    clipboard_set(objstr)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/common.py b/.venv/lib/python3.13/site-packages/pandas/io/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..72c9deeb54fc7aaab781b2870171cf983a47da1f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/common.py
@@ -0,0 +1,1267 @@
+"""Common IO api utilities"""
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+import codecs
+from collections import defaultdict
+from collections.abc import (
+    Hashable,
+    Mapping,
+    Sequence,
+)
+import dataclasses
+import functools
+import gzip
+from io import (
+    BufferedIOBase,
+    BytesIO,
+    RawIOBase,
+    StringIO,
+    TextIOBase,
+    TextIOWrapper,
+)
+import mmap
+import os
+from pathlib import Path
+import re
+import tarfile
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+    AnyStr,
+    DefaultDict,
+    Generic,
+    Literal,
+    TypeVar,
+    cast,
+    overload,
+)
+from urllib.parse import (
+    urljoin,
+    urlparse as parse_url,
+    uses_netloc,
+    uses_params,
+    uses_relative,
+)
+import warnings
+import zipfile
+
+from pandas._typing import (
+    BaseBuffer,
+    ReadCsvBuffer,
+)
+from pandas.compat import (
+    get_bz2_file,
+    get_lzma_file,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_file_like,
+    is_integer,
+    is_list_like,
+)
+from pandas.core.dtypes.generic import ABCMultiIndex
+
+from pandas.core.shared_docs import _shared_docs
+
+_VALID_URLS = set(uses_relative + uses_netloc + uses_params)
+_VALID_URLS.discard("")
+_RFC_3986_PATTERN = re.compile(r"^[A-Za-z][A-Za-z0-9+\-+.]*://")
+
+BaseBufferT = TypeVar("BaseBufferT", bound=BaseBuffer)
+
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from pandas._typing import (
+        CompressionDict,
+        CompressionOptions,
+        FilePath,
+        ReadBuffer,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+    from pandas import MultiIndex
+
+
+@dataclasses.dataclass
+class IOArgs:
+    """
+    Return value of io/common.py:_get_filepath_or_buffer.
+    """
+
+    filepath_or_buffer: str | BaseBuffer
+    encoding: str
+    mode: str
+    compression: CompressionDict
+    should_close: bool = False
+
+
+@dataclasses.dataclass
+class IOHandles(Generic[AnyStr]):
+    """
+    Return value of io/common.py:get_handle
+
+    Can be used as a context manager.
+
+    This is used to easily close created buffers and to handle corner cases when
+    TextIOWrapper is inserted.
+
+    handle: The file handle to be used.
+    created_handles: All file handles that are created by get_handle
+    is_wrapped: Whether a TextIOWrapper needs to be detached.
+    """
+
+    # handle might not implement the IO-interface
+    handle: IO[AnyStr]
+    compression: CompressionDict
+    created_handles: list[IO[bytes] | IO[str]] = dataclasses.field(default_factory=list)
+    is_wrapped: bool = False
+
+    def close(self) -> None:
+        """
+        Close all created buffers.
+
+        Note: If a TextIOWrapper was inserted, it is flushed and detached to
+        avoid closing the potentially user-created buffer.
+        """
+        if self.is_wrapped:
+            assert isinstance(self.handle, TextIOWrapper)
+            self.handle.flush()
+            self.handle.detach()
+            self.created_handles.remove(self.handle)
+        for handle in self.created_handles:
+            handle.close()
+        self.created_handles = []
+        self.is_wrapped = False
+
+    def __enter__(self) -> IOHandles[AnyStr]:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def is_url(url: object) -> bool:
+    """
+    Check to see if a URL has a valid protocol.
+
+    Parameters
+    ----------
+    url : str or unicode
+
+    Returns
+    -------
+    isurl : bool
+        If `url` has a valid protocol return True otherwise False.
+    """
+    if not isinstance(url, str):
+        return False
+    return parse_url(url).scheme in _VALID_URLS
+
+
+@overload
+def _expand_user(filepath_or_buffer: str) -> str:
+    ...
+
+
+@overload
+def _expand_user(filepath_or_buffer: BaseBufferT) -> BaseBufferT:
+    ...
+
+
+def _expand_user(filepath_or_buffer: str | BaseBufferT) -> str | BaseBufferT:
+    """
+    Return the argument with an initial component of ~ or ~user
+    replaced by that user's home directory.
+
+    Parameters
+    ----------
+    filepath_or_buffer : object to be converted if possible
+
+    Returns
+    -------
+    expanded_filepath_or_buffer : an expanded filepath or the
+                                  input if not expandable
+    """
+    if isinstance(filepath_or_buffer, str):
+        return os.path.expanduser(filepath_or_buffer)
+    return filepath_or_buffer
+
+
+def validate_header_arg(header: object) -> None:
+    if header is None:
+        return
+    if is_integer(header):
+        header = cast(int, header)
+        if header < 0:
+            # GH 27779
+            raise ValueError(
+                "Passing negative integer to header is invalid. "
+                "For no header, use header=None instead"
+            )
+        return
+    if is_list_like(header, allow_sets=False):
+        header = cast(Sequence, header)
+        if not all(map(is_integer, header)):
+            raise ValueError("header must be integer or list of integers")
+        if any(i < 0 for i in header):
+            raise ValueError("cannot specify multi-index header with negative integers")
+        return
+    if is_bool(header):
+        raise TypeError(
+            "Passing a bool to header is invalid. Use header=None for no header or "
+            "header=int or list-like of ints to specify "
+            "the row(s) making up the column names"
+        )
+    # GH 16338
+    raise ValueError("header must be integer or list of integers")
+
+
+@overload
+def stringify_path(filepath_or_buffer: FilePath, convert_file_like: bool = ...) -> str:
+    ...
+
+
+@overload
+def stringify_path(
+    filepath_or_buffer: BaseBufferT, convert_file_like: bool = ...
+) -> BaseBufferT:
+    ...
+
+
+def stringify_path(
+    filepath_or_buffer: FilePath | BaseBufferT,
+    convert_file_like: bool = False,
+) -> str | BaseBufferT:
+    """
+    Attempt to convert a path-like object to a string.
+
+    Parameters
+    ----------
+    filepath_or_buffer : object to be converted
+
+    Returns
+    -------
+    str_filepath_or_buffer : maybe a string version of the object
+
+    Notes
+    -----
+    Objects supporting the fspath protocol are coerced
+    according to its __fspath__ method.
+
+    Any other object is passed through unchanged, which includes bytes,
+    strings, buffers, or anything else that's not even path-like.
+    """
+    if not convert_file_like and is_file_like(filepath_or_buffer):
+        # GH 38125: some fsspec objects implement os.PathLike but have already opened a
+        # file. This prevents opening the file a second time. infer_compression calls
+        # this function with convert_file_like=True to infer the compression.
+        return cast(BaseBufferT, filepath_or_buffer)
+
+    if isinstance(filepath_or_buffer, os.PathLike):
+        filepath_or_buffer = filepath_or_buffer.__fspath__()
+    return _expand_user(filepath_or_buffer)
+
+
+def urlopen(*args, **kwargs):
+    """
+    Lazy-import wrapper for stdlib urlopen, as that imports a big chunk of
+    the stdlib.
+    """
+    import urllib.request
+
+    return urllib.request.urlopen(*args, **kwargs)
+
+
+def is_fsspec_url(url: FilePath | BaseBuffer) -> bool:
+    """
+    Returns true if the given URL looks like
+    something fsspec can handle
+    """
+    return (
+        isinstance(url, str)
+        and bool(_RFC_3986_PATTERN.match(url))
+        and not url.startswith(("http://", "https://"))
+    )
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    compression_options=_shared_docs["compression_options"] % "filepath_or_buffer",
+)
+def _get_filepath_or_buffer(
+    filepath_or_buffer: FilePath | BaseBuffer,
+    encoding: str = "utf-8",
+    compression: CompressionOptions | None = None,
+    mode: str = "r",
+    storage_options: StorageOptions | None = None,
+) -> IOArgs:
+    """
+    If the filepath_or_buffer is a url, translate and return the buffer.
+    Otherwise passthrough.
+
+    Parameters
+    ----------
+    filepath_or_buffer : a url, filepath (str, py.path.local or pathlib.Path),
+                         or buffer
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    encoding : the encoding to use to decode bytes, default is 'utf-8'
+    mode : str, optional
+
+    {storage_options}
+
+
+    Returns the dataclass IOArgs.
+    """
+    filepath_or_buffer = stringify_path(filepath_or_buffer)
+
+    # handle compression dict
+    compression_method, compression = get_compression_method(compression)
+    compression_method = infer_compression(filepath_or_buffer, compression_method)
+
+    # GH21227 internal compression is not used for non-binary handles.
+    if compression_method and hasattr(filepath_or_buffer, "write") and "b" not in mode:
+        warnings.warn(
+            "compression has no effect when passing a non-binary object as input.",
+            RuntimeWarning,
+            stacklevel=find_stack_level(),
+        )
+        compression_method = None
+
+    compression = dict(compression, method=compression_method)
+
+    # bz2 and xz do not write the byte order mark for utf-16 and utf-32
+    # print a warning when writing such files
+    if (
+        "w" in mode
+        and compression_method in ["bz2", "xz"]
+        and encoding in ["utf-16", "utf-32"]
+    ):
+        warnings.warn(
+            f"{compression} will not write the byte order mark for {encoding}",
+            UnicodeWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    # Use binary mode when converting path-like objects to file-like objects (fsspec)
+    # except when text mode is explicitly requested. The original mode is returned if
+    # fsspec is not used.
+    fsspec_mode = mode
+    if "t" not in fsspec_mode and "b" not in fsspec_mode:
+        fsspec_mode += "b"
+
+    if isinstance(filepath_or_buffer, str) and is_url(filepath_or_buffer):
+        # TODO: fsspec can also handle HTTP via requests, but leaving this
+        # unchanged. using fsspec appears to break the ability to infer if the
+        # server responded with gzipped data
+        storage_options = storage_options or {}
+
+        # waiting until now for importing to match intended lazy logic of
+        # urlopen function defined elsewhere in this module
+        import urllib.request
+
+        # assuming storage_options is to be interpreted as headers
+        req_info = urllib.request.Request(filepath_or_buffer, headers=storage_options)
+        with urlopen(req_info) as req:
+            content_encoding = req.headers.get("Content-Encoding", None)
+            if content_encoding == "gzip":
+                # Override compression based on Content-Encoding header
+                compression = {"method": "gzip"}
+            reader = BytesIO(req.read())
+        return IOArgs(
+            filepath_or_buffer=reader,
+            encoding=encoding,
+            compression=compression,
+            should_close=True,
+            mode=fsspec_mode,
+        )
+
+    if is_fsspec_url(filepath_or_buffer):
+        assert isinstance(
+            filepath_or_buffer, str
+        )  # just to appease mypy for this branch
+        # two special-case s3-like protocols; these have special meaning in Hadoop,
+        # but are equivalent to just "s3" from fsspec's point of view
+        # cc #11071
+        if filepath_or_buffer.startswith("s3a://"):
+            filepath_or_buffer = filepath_or_buffer.replace("s3a://", "s3://")
+        if filepath_or_buffer.startswith("s3n://"):
+            filepath_or_buffer = filepath_or_buffer.replace("s3n://", "s3://")
+        fsspec = import_optional_dependency("fsspec")
+
+        # If botocore is installed we fallback to reading with anon=True
+        # to allow reads from public buckets
+        err_types_to_retry_with_anon: list[Any] = []
+        try:
+            import_optional_dependency("botocore")
+            from botocore.exceptions import (
+                ClientError,
+                NoCredentialsError,
+            )
+
+            err_types_to_retry_with_anon = [
+                ClientError,
+                NoCredentialsError,
+                PermissionError,
+            ]
+        except ImportError:
+            pass
+
+        try:
+            file_obj = fsspec.open(
+                filepath_or_buffer, mode=fsspec_mode, **(storage_options or {})
+            ).open()
+        # GH 34626 Reads from Public Buckets without Credentials needs anon=True
+        except tuple(err_types_to_retry_with_anon):
+            if storage_options is None:
+                storage_options = {"anon": True}
+            else:
+                # don't mutate user input.
+                storage_options = dict(storage_options)
+                storage_options["anon"] = True
+            file_obj = fsspec.open(
+                filepath_or_buffer, mode=fsspec_mode, **(storage_options or {})
+            ).open()
+
+        return IOArgs(
+            filepath_or_buffer=file_obj,
+            encoding=encoding,
+            compression=compression,
+            should_close=True,
+            mode=fsspec_mode,
+        )
+    elif storage_options:
+        raise ValueError(
+            "storage_options passed with file object or non-fsspec file path"
+        )
+
+    if isinstance(filepath_or_buffer, (str, bytes, mmap.mmap)):
+        return IOArgs(
+            filepath_or_buffer=_expand_user(filepath_or_buffer),
+            encoding=encoding,
+            compression=compression,
+            should_close=False,
+            mode=mode,
+        )
+
+    # is_file_like requires (read | write) & __iter__ but __iter__ is only
+    # needed for read_csv(engine=python)
+    if not (
+        hasattr(filepath_or_buffer, "read") or hasattr(filepath_or_buffer, "write")
+    ):
+        msg = f"Invalid file path or buffer object type: {type(filepath_or_buffer)}"
+        raise ValueError(msg)
+
+    return IOArgs(
+        filepath_or_buffer=filepath_or_buffer,
+        encoding=encoding,
+        compression=compression,
+        should_close=False,
+        mode=mode,
+    )
+
+
+def file_path_to_url(path: str) -> str:
+    """
+    converts an absolute native path to a FILE URL.
+
+    Parameters
+    ----------
+    path : a path in native format
+
+    Returns
+    -------
+    a valid FILE URL
+    """
+    # lazify expensive import (~30ms)
+    from urllib.request import pathname2url
+
+    return urljoin("file:", pathname2url(path))
+
+
+extension_to_compression = {
+    ".tar": "tar",
+    ".tar.gz": "tar",
+    ".tar.bz2": "tar",
+    ".tar.xz": "tar",
+    ".gz": "gzip",
+    ".bz2": "bz2",
+    ".zip": "zip",
+    ".xz": "xz",
+    ".zst": "zstd",
+}
+_supported_compressions = set(extension_to_compression.values())
+
+
+def get_compression_method(
+    compression: CompressionOptions,
+) -> tuple[str | None, CompressionDict]:
+    """
+    Simplifies a compression argument to a compression method string and
+    a mapping containing additional arguments.
+
+    Parameters
+    ----------
+    compression : str or mapping
+        If string, specifies the compression method. If mapping, value at key
+        'method' specifies compression method.
+
+    Returns
+    -------
+    tuple of ({compression method}, Optional[str]
+              {compression arguments}, Dict[str, Any])
+
+    Raises
+    ------
+    ValueError on mapping missing 'method' key
+    """
+    compression_method: str | None
+    if isinstance(compression, Mapping):
+        compression_args = dict(compression)
+        try:
+            compression_method = compression_args.pop("method")
+        except KeyError as err:
+            raise ValueError("If mapping, compression must have key 'method'") from err
+    else:
+        compression_args = {}
+        compression_method = compression
+    return compression_method, compression_args
+
+
+@doc(compression_options=_shared_docs["compression_options"] % "filepath_or_buffer")
+def infer_compression(
+    filepath_or_buffer: FilePath | BaseBuffer, compression: str | None
+) -> str | None:
+    """
+    Get the compression method for filepath_or_buffer. If compression='infer',
+    the inferred compression method is returned. Otherwise, the input
+    compression method is returned unchanged, unless it's invalid, in which
+    case an error is raised.
+
+    Parameters
+    ----------
+    filepath_or_buffer : str or file handle
+        File path or object.
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    Returns
+    -------
+    string or None
+
+    Raises
+    ------
+    ValueError on invalid compression specified.
+    """
+    if compression is None:
+        return None
+
+    # Infer compression
+    if compression == "infer":
+        # Convert all path types (e.g. pathlib.Path) to strings
+        filepath_or_buffer = stringify_path(filepath_or_buffer, convert_file_like=True)
+        if not isinstance(filepath_or_buffer, str):
+            # Cannot infer compression of a buffer, assume no compression
+            return None
+
+        # Infer compression from the filename/URL extension
+        for extension, compression in extension_to_compression.items():
+            if filepath_or_buffer.lower().endswith(extension):
+                return compression
+        return None
+
+    # Compression has been specified. Check that it's valid
+    if compression in _supported_compressions:
+        return compression
+
+    valid = ["infer", None] + sorted(_supported_compressions)
+    msg = (
+        f"Unrecognized compression type: {compression}\n"
+        f"Valid compression types are {valid}"
+    )
+    raise ValueError(msg)
+
+
+def check_parent_directory(path: Path | str) -> None:
+    """
+    Check if parent directory of a file exists, raise OSError if it does not
+
+    Parameters
+    ----------
+    path: Path or str
+        Path to check parent directory of
+    """
+    parent = Path(path).parent
+    if not parent.is_dir():
+        raise OSError(rf"Cannot save file into a non-existent directory: '{parent}'")
+
+
+@overload
+def get_handle(
+    path_or_buf: FilePath | BaseBuffer,
+    mode: str,
+    *,
+    encoding: str | None = ...,
+    compression: CompressionOptions = ...,
+    memory_map: bool = ...,
+    is_text: Literal[False],
+    errors: str | None = ...,
+    storage_options: StorageOptions = ...,
+) -> IOHandles[bytes]:
+    ...
+
+
+@overload
+def get_handle(
+    path_or_buf: FilePath | BaseBuffer,
+    mode: str,
+    *,
+    encoding: str | None = ...,
+    compression: CompressionOptions = ...,
+    memory_map: bool = ...,
+    is_text: Literal[True] = ...,
+    errors: str | None = ...,
+    storage_options: StorageOptions = ...,
+) -> IOHandles[str]:
+    ...
+
+
+@overload
+def get_handle(
+    path_or_buf: FilePath | BaseBuffer,
+    mode: str,
+    *,
+    encoding: str | None = ...,
+    compression: CompressionOptions = ...,
+    memory_map: bool = ...,
+    is_text: bool = ...,
+    errors: str | None = ...,
+    storage_options: StorageOptions = ...,
+) -> IOHandles[str] | IOHandles[bytes]:
+    ...
+
+
+@doc(compression_options=_shared_docs["compression_options"] % "path_or_buf")
+def get_handle(
+    path_or_buf: FilePath | BaseBuffer,
+    mode: str,
+    *,
+    encoding: str | None = None,
+    compression: CompressionOptions | None = None,
+    memory_map: bool = False,
+    is_text: bool = True,
+    errors: str | None = None,
+    storage_options: StorageOptions | None = None,
+) -> IOHandles[str] | IOHandles[bytes]:
+    """
+    Get file handle for given path/buffer and mode.
+
+    Parameters
+    ----------
+    path_or_buf : str or file handle
+        File path or object.
+    mode : str
+        Mode to open path_or_buf with.
+    encoding : str or None
+        Encoding to use.
+    {compression_options}
+
+           May be a dict with key 'method' as compression mode
+           and other keys as compression options if compression
+           mode is 'zip'.
+
+           Passing compression options as keys in dict is
+           supported for compression modes 'gzip', 'bz2', 'zstd' and 'zip'.
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    memory_map : bool, default False
+        See parsers._parser_params for more information. Only used by read_csv.
+    is_text : bool, default True
+        Whether the type of the content passed to the file/buffer is string or
+        bytes. This is not the same as `"b" not in mode`. If a string content is
+        passed to a binary file/buffer, a wrapper is inserted.
+    errors : str, default 'strict'
+        Specifies how encoding and decoding errors are to be handled.
+        See the errors argument for :func:`open` for a full list
+        of options.
+    storage_options: StorageOptions = None
+        Passed to _get_filepath_or_buffer
+
+    Returns the dataclass IOHandles
+    """
+    # Windows does not default to utf-8. Set to utf-8 for a consistent behavior
+    encoding = encoding or "utf-8"
+
+    errors = errors or "strict"
+
+    # read_csv does not know whether the buffer is opened in binary/text mode
+    if _is_binary_mode(path_or_buf, mode) and "b" not in mode:
+        mode += "b"
+
+    # validate encoding and errors
+    codecs.lookup(encoding)
+    if isinstance(errors, str):
+        codecs.lookup_error(errors)
+
+    # open URLs
+    ioargs = _get_filepath_or_buffer(
+        path_or_buf,
+        encoding=encoding,
+        compression=compression,
+        mode=mode,
+        storage_options=storage_options,
+    )
+
+    handle = ioargs.filepath_or_buffer
+    handles: list[BaseBuffer]
+
+    # memory mapping needs to be the first step
+    # only used for read_csv
+    handle, memory_map, handles = _maybe_memory_map(handle, memory_map)
+
+    is_path = isinstance(handle, str)
+    compression_args = dict(ioargs.compression)
+    compression = compression_args.pop("method")
+
+    # Only for write methods
+    if "r" not in mode and is_path:
+        check_parent_directory(str(handle))
+
+    if compression:
+        if compression != "zstd":
+            # compression libraries do not like an explicit text-mode
+            ioargs.mode = ioargs.mode.replace("t", "")
+        elif compression == "zstd" and "b" not in ioargs.mode:
+            # python-zstandard defaults to text mode, but we always expect
+            # compression libraries to use binary mode.
+            ioargs.mode += "b"
+
+        # GZ Compression
+        if compression == "gzip":
+            if isinstance(handle, str):
+                # error: Incompatible types in assignment (expression has type
+                # "GzipFile", variable has type "Union[str, BaseBuffer]")
+                handle = gzip.GzipFile(  # type: ignore[assignment]
+                    filename=handle,
+                    mode=ioargs.mode,
+                    **compression_args,
+                )
+            else:
+                handle = gzip.GzipFile(
+                    # No overload variant of "GzipFile" matches argument types
+                    # "Union[str, BaseBuffer]", "str", "Dict[str, Any]"
+                    fileobj=handle,  # type: ignore[call-overload]
+                    mode=ioargs.mode,
+                    **compression_args,
+                )
+
+        # BZ Compression
+        elif compression == "bz2":
+            # Overload of "BZ2File" to handle pickle protocol 5
+            # "Union[str, BaseBuffer]", "str", "Dict[str, Any]"
+            handle = get_bz2_file()(  # type: ignore[call-overload]
+                handle,
+                mode=ioargs.mode,
+                **compression_args,
+            )
+
+        # ZIP Compression
+        elif compression == "zip":
+            # error: Argument 1 to "_BytesZipFile" has incompatible type
+            # "Union[str, BaseBuffer]"; expected "Union[Union[str, PathLike[str]],
+            # ReadBuffer[bytes], WriteBuffer[bytes]]"
+            handle = _BytesZipFile(
+                handle, ioargs.mode, **compression_args  # type: ignore[arg-type]
+            )
+            if handle.buffer.mode == "r":
+                handles.append(handle)
+                zip_names = handle.buffer.namelist()
+                if len(zip_names) == 1:
+                    handle = handle.buffer.open(zip_names.pop())
+                elif not zip_names:
+                    raise ValueError(f"Zero files found in ZIP file {path_or_buf}")
+                else:
+                    raise ValueError(
+                        "Multiple files found in ZIP file. "
+                        f"Only one file per ZIP: {zip_names}"
+                    )
+
+        # TAR Encoding
+        elif compression == "tar":
+            compression_args.setdefault("mode", ioargs.mode)
+            if isinstance(handle, str):
+                handle = _BytesTarFile(name=handle, **compression_args)
+            else:
+                # error: Argument "fileobj" to "_BytesTarFile" has incompatible
+                # type "BaseBuffer"; expected "Union[ReadBuffer[bytes],
+                # WriteBuffer[bytes], None]"
+                handle = _BytesTarFile(
+                    fileobj=handle, **compression_args  # type: ignore[arg-type]
+                )
+            assert isinstance(handle, _BytesTarFile)
+            if "r" in handle.buffer.mode:
+                handles.append(handle)
+                files = handle.buffer.getnames()
+                if len(files) == 1:
+                    file = handle.buffer.extractfile(files[0])
+                    assert file is not None
+                    handle = file
+                elif not files:
+                    raise ValueError(f"Zero files found in TAR archive {path_or_buf}")
+                else:
+                    raise ValueError(
+                        "Multiple files found in TAR archive. "
+                        f"Only one file per TAR archive: {files}"
+                    )
+
+        # XZ Compression
+        elif compression == "xz":
+            # error: Argument 1 to "LZMAFile" has incompatible type "Union[str,
+            # BaseBuffer]"; expected "Optional[Union[Union[str, bytes, PathLike[str],
+            # PathLike[bytes]], IO[bytes]], None]"
+            handle = get_lzma_file()(
+                handle, ioargs.mode, **compression_args  # type: ignore[arg-type]
+            )
+
+        # Zstd Compression
+        elif compression == "zstd":
+            zstd = import_optional_dependency("zstandard")
+            if "r" in ioargs.mode:
+                open_args = {"dctx": zstd.ZstdDecompressor(**compression_args)}
+            else:
+                open_args = {"cctx": zstd.ZstdCompressor(**compression_args)}
+            handle = zstd.open(
+                handle,
+                mode=ioargs.mode,
+                **open_args,
+            )
+
+        # Unrecognized Compression
+        else:
+            msg = f"Unrecognized compression type: {compression}"
+            raise ValueError(msg)
+
+        assert not isinstance(handle, str)
+        handles.append(handle)
+
+    elif isinstance(handle, str):
+        # Check whether the filename is to be opened in binary mode.
+        # Binary mode does not support 'encoding' and 'newline'.
+        if ioargs.encoding and "b" not in ioargs.mode:
+            # Encoding
+            handle = open(
+                handle,
+                ioargs.mode,
+                encoding=ioargs.encoding,
+                errors=errors,
+                newline="",
+            )
+        else:
+            # Binary mode
+            handle = open(handle, ioargs.mode)
+        handles.append(handle)
+
+    # Convert BytesIO or file objects passed with an encoding
+    is_wrapped = False
+    if not is_text and ioargs.mode == "rb" and isinstance(handle, TextIOBase):
+        # not added to handles as it does not open/buffer resources
+        handle = _BytesIOWrapper(
+            handle,
+            encoding=ioargs.encoding,
+        )
+    elif is_text and (
+        compression or memory_map or _is_binary_mode(handle, ioargs.mode)
+    ):
+        if (
+            not hasattr(handle, "readable")
+            or not hasattr(handle, "writable")
+            or not hasattr(handle, "seekable")
+        ):
+            handle = _IOWrapper(handle)
+        # error: Argument 1 to "TextIOWrapper" has incompatible type
+        # "_IOWrapper"; expected "IO[bytes]"
+        handle = TextIOWrapper(
+            handle,  # type: ignore[arg-type]
+            encoding=ioargs.encoding,
+            errors=errors,
+            newline="",
+        )
+        handles.append(handle)
+        # only marked as wrapped when the caller provided a handle
+        is_wrapped = not (
+            isinstance(ioargs.filepath_or_buffer, str) or ioargs.should_close
+        )
+
+    if "r" in ioargs.mode and not hasattr(handle, "read"):
+        raise TypeError(
+            "Expected file path name or file-like object, "
+            f"got {type(ioargs.filepath_or_buffer)} type"
+        )
+
+    handles.reverse()  # close the most recently added buffer first
+    if ioargs.should_close:
+        assert not isinstance(ioargs.filepath_or_buffer, str)
+        handles.append(ioargs.filepath_or_buffer)
+
+    return IOHandles(
+        # error: Argument "handle" to "IOHandles" has incompatible type
+        # "Union[TextIOWrapper, GzipFile, BaseBuffer, typing.IO[bytes],
+        # typing.IO[Any]]"; expected "pandas._typing.IO[Any]"
+        handle=handle,  # type: ignore[arg-type]
+        # error: Argument "created_handles" to "IOHandles" has incompatible type
+        # "List[BaseBuffer]"; expected "List[Union[IO[bytes], IO[str]]]"
+        created_handles=handles,  # type: ignore[arg-type]
+        is_wrapped=is_wrapped,
+        compression=ioargs.compression,
+    )
+
+
+# error: Definition of "__enter__" in base class "IOBase" is incompatible
+# with definition in base class "BinaryIO"
+class _BufferedWriter(BytesIO, ABC):  # type: ignore[misc]
+    """
+    Some objects do not support multiple .write() calls (TarFile and ZipFile).
+    This wrapper writes to the underlying buffer on close.
+    """
+
+    buffer = BytesIO()
+
+    @abstractmethod
+    def write_to_buffer(self) -> None:
+        ...
+
+    def close(self) -> None:
+        if self.closed:
+            # already closed
+            return
+        if self.getbuffer().nbytes:
+            # write to buffer
+            self.seek(0)
+            with self.buffer:
+                self.write_to_buffer()
+        else:
+            self.buffer.close()
+        super().close()
+
+
+class _BytesTarFile(_BufferedWriter):
+    def __init__(
+        self,
+        name: str | None = None,
+        mode: Literal["r", "a", "w", "x"] = "r",
+        fileobj: ReadBuffer[bytes] | WriteBuffer[bytes] | None = None,
+        archive_name: str | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__()
+        self.archive_name = archive_name
+        self.name = name
+        # error: Incompatible types in assignment (expression has type "TarFile",
+        # base class "_BufferedWriter" defined the type as "BytesIO")
+        self.buffer: tarfile.TarFile = tarfile.TarFile.open(  # type: ignore[assignment]
+            name=name,
+            mode=self.extend_mode(mode),
+            fileobj=fileobj,
+            **kwargs,
+        )
+
+    def extend_mode(self, mode: str) -> str:
+        mode = mode.replace("b", "")
+        if mode != "w":
+            return mode
+        if self.name is not None:
+            suffix = Path(self.name).suffix
+            if suffix in (".gz", ".xz", ".bz2"):
+                mode = f"{mode}:{suffix[1:]}"
+        return mode
+
+    def infer_filename(self) -> str | None:
+        """
+        If an explicit archive_name is not given, we still want the file inside the zip
+        file not to be named something.tar, because that causes confusion (GH39465).
+        """
+        if self.name is None:
+            return None
+
+        filename = Path(self.name)
+        if filename.suffix == ".tar":
+            return filename.with_suffix("").name
+        elif filename.suffix in (".tar.gz", ".tar.bz2", ".tar.xz"):
+            return filename.with_suffix("").with_suffix("").name
+        return filename.name
+
+    def write_to_buffer(self) -> None:
+        # TarFile needs a non-empty string
+        archive_name = self.archive_name or self.infer_filename() or "tar"
+        tarinfo = tarfile.TarInfo(name=archive_name)
+        tarinfo.size = len(self.getvalue())
+        self.buffer.addfile(tarinfo, self)
+
+
+class _BytesZipFile(_BufferedWriter):
+    def __init__(
+        self,
+        file: FilePath | ReadBuffer[bytes] | WriteBuffer[bytes],
+        mode: str,
+        archive_name: str | None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__()
+        mode = mode.replace("b", "")
+        self.archive_name = archive_name
+
+        kwargs.setdefault("compression", zipfile.ZIP_DEFLATED)
+        # error: Incompatible types in assignment (expression has type "ZipFile",
+        # base class "_BufferedWriter" defined the type as "BytesIO")
+        self.buffer: zipfile.ZipFile = zipfile.ZipFile(  # type: ignore[assignment]
+            file, mode, **kwargs
+        )
+
+    def infer_filename(self) -> str | None:
+        """
+        If an explicit archive_name is not given, we still want the file inside the zip
+        file not to be named something.zip, because that causes confusion (GH39465).
+        """
+        if isinstance(self.buffer.filename, (os.PathLike, str)):
+            filename = Path(self.buffer.filename)
+            if filename.suffix == ".zip":
+                return filename.with_suffix("").name
+            return filename.name
+        return None
+
+    def write_to_buffer(self) -> None:
+        # ZipFile needs a non-empty string
+        archive_name = self.archive_name or self.infer_filename() or "zip"
+        self.buffer.writestr(archive_name, self.getvalue())
+
+
+class _IOWrapper:
+    # TextIOWrapper is overly strict: it request that the buffer has seekable, readable,
+    # and writable. If we have a read-only buffer, we shouldn't need writable and vice
+    # versa. Some buffers, are seek/read/writ-able but they do not have the "-able"
+    # methods, e.g., tempfile.SpooledTemporaryFile.
+    # If a buffer does not have the above "-able" methods, we simple assume they are
+    # seek/read/writ-able.
+    def __init__(self, buffer: BaseBuffer) -> None:
+        self.buffer = buffer
+
+    def __getattr__(self, name: str):
+        return getattr(self.buffer, name)
+
+    def readable(self) -> bool:
+        if hasattr(self.buffer, "readable"):
+            return self.buffer.readable()
+        return True
+
+    def seekable(self) -> bool:
+        if hasattr(self.buffer, "seekable"):
+            return self.buffer.seekable()
+        return True
+
+    def writable(self) -> bool:
+        if hasattr(self.buffer, "writable"):
+            return self.buffer.writable()
+        return True
+
+
+class _BytesIOWrapper:
+    # Wrapper that wraps a StringIO buffer and reads bytes from it
+    # Created for compat with pyarrow read_csv
+    def __init__(self, buffer: StringIO | TextIOBase, encoding: str = "utf-8") -> None:
+        self.buffer = buffer
+        self.encoding = encoding
+        # Because a character can be represented by more than 1 byte,
+        # it is possible that reading will produce more bytes than n
+        # We store the extra bytes in this overflow variable, and append the
+        # overflow to the front of the bytestring the next time reading is performed
+        self.overflow = b""
+
+    def __getattr__(self, attr: str):
+        return getattr(self.buffer, attr)
+
+    def read(self, n: int | None = -1) -> bytes:
+        assert self.buffer is not None
+        bytestring = self.buffer.read(n).encode(self.encoding)
+        # When n=-1/n greater than remaining bytes: Read entire file/rest of file
+        combined_bytestring = self.overflow + bytestring
+        if n is None or n < 0 or n >= len(combined_bytestring):
+            self.overflow = b""
+            return combined_bytestring
+        else:
+            to_return = combined_bytestring[:n]
+            self.overflow = combined_bytestring[n:]
+            return to_return
+
+
+def _maybe_memory_map(
+    handle: str | BaseBuffer, memory_map: bool
+) -> tuple[str | BaseBuffer, bool, list[BaseBuffer]]:
+    """Try to memory map file/buffer."""
+    handles: list[BaseBuffer] = []
+    memory_map &= hasattr(handle, "fileno") or isinstance(handle, str)
+    if not memory_map:
+        return handle, memory_map, handles
+
+    # mmap used by only read_csv
+    handle = cast(ReadCsvBuffer, handle)
+
+    # need to open the file first
+    if isinstance(handle, str):
+        handle = open(handle, "rb")
+        handles.append(handle)
+
+    try:
+        # open mmap and adds *-able
+        # error: Argument 1 to "_IOWrapper" has incompatible type "mmap";
+        # expected "BaseBuffer"
+        wrapped = _IOWrapper(
+            mmap.mmap(
+                handle.fileno(), 0, access=mmap.ACCESS_READ  # type: ignore[arg-type]
+            )
+        )
+    finally:
+        for handle in reversed(handles):
+            # error: "BaseBuffer" has no attribute "close"
+            handle.close()  # type: ignore[attr-defined]
+
+    return wrapped, memory_map, [wrapped]
+
+
+def file_exists(filepath_or_buffer: FilePath | BaseBuffer) -> bool:
+    """Test whether file exists."""
+    exists = False
+    filepath_or_buffer = stringify_path(filepath_or_buffer)
+    if not isinstance(filepath_or_buffer, str):
+        return exists
+    try:
+        exists = os.path.exists(filepath_or_buffer)
+        # gh-5874: if the filepath is too long will raise here
+    except (TypeError, ValueError):
+        pass
+    return exists
+
+
+def _is_binary_mode(handle: FilePath | BaseBuffer, mode: str) -> bool:
+    """Whether the handle is opened in binary mode"""
+    # specified by user
+    if "t" in mode or "b" in mode:
+        return "b" in mode
+
+    # exceptions
+    text_classes = (
+        # classes that expect string but have 'b' in mode
+        codecs.StreamWriter,
+        codecs.StreamReader,
+        codecs.StreamReaderWriter,
+    )
+    if issubclass(type(handle), text_classes):
+        return False
+
+    return isinstance(handle, _get_binary_io_classes()) or "b" in getattr(
+        handle, "mode", mode
+    )
+
+
+@functools.lru_cache
+def _get_binary_io_classes() -> tuple[type, ...]:
+    """IO classes that that expect bytes"""
+    binary_classes: tuple[type, ...] = (BufferedIOBase, RawIOBase)
+
+    # python-zstandard doesn't use any of the builtin base classes; instead we
+    # have to use the `zstd.ZstdDecompressionReader` class for isinstance checks.
+    # Unfortunately `zstd.ZstdDecompressionReader` isn't exposed by python-zstandard
+    # so we have to get it from a `zstd.ZstdDecompressor` instance.
+    # See also https://github.com/indygreg/python-zstandard/pull/165.
+    zstd = import_optional_dependency("zstandard", errors="ignore")
+    if zstd is not None:
+        with zstd.ZstdDecompressor().stream_reader(b"") as reader:
+            binary_classes += (type(reader),)
+
+    return binary_classes
+
+
+def is_potential_multi_index(
+    columns: Sequence[Hashable] | MultiIndex,
+    index_col: bool | Sequence[int] | None = None,
+) -> bool:
+    """
+    Check whether or not the `columns` parameter
+    could be converted into a MultiIndex.
+
+    Parameters
+    ----------
+    columns : array-like
+        Object which may or may not be convertible into a MultiIndex
+    index_col : None, bool or list, optional
+        Column or columns to use as the (possibly hierarchical) index
+
+    Returns
+    -------
+    bool : Whether or not columns could become a MultiIndex
+    """
+    if index_col is None or isinstance(index_col, bool):
+        index_col = []
+
+    return bool(
+        len(columns)
+        and not isinstance(columns, ABCMultiIndex)
+        and all(isinstance(c, tuple) for c in columns if c not in list(index_col))
+    )
+
+
+def dedup_names(
+    names: Sequence[Hashable], is_potential_multiindex: bool
+) -> Sequence[Hashable]:
+    """
+    Rename column names if duplicates exist.
+
+    Currently the renaming is done by appending a period and an autonumeric,
+    but a custom pattern may be supported in the future.
+
+    Examples
+    --------
+    >>> dedup_names(["x", "y", "x", "x"], is_potential_multiindex=False)
+    ['x', 'y', 'x.1', 'x.2']
+    """
+    names = list(names)  # so we can index
+    counts: DefaultDict[Hashable, int] = defaultdict(int)
+
+    for i, col in enumerate(names):
+        cur_count = counts[col]
+
+        while cur_count > 0:
+            counts[col] = cur_count + 1
+
+            if is_potential_multiindex:
+                # for mypy
+                assert isinstance(col, tuple)
+                col = col[:-1] + (f"{col[-1]}.{cur_count}",)
+            else:
+                col = f"{col}.{cur_count}"
+            cur_count = counts[col]
+
+        names[i] = col
+        counts[col] = cur_count + 1
+
+    return names
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..275cbf0148f944eb04ca6c40c624cc5df77aa626
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/__init__.py
@@ -0,0 +1,19 @@
+from pandas.io.excel._base import (
+    ExcelFile,
+    ExcelWriter,
+    read_excel,
+)
+from pandas.io.excel._odswriter import ODSWriter as _ODSWriter
+from pandas.io.excel._openpyxl import OpenpyxlWriter as _OpenpyxlWriter
+from pandas.io.excel._util import register_writer
+from pandas.io.excel._xlsxwriter import XlsxWriter as _XlsxWriter
+
+__all__ = ["read_excel", "ExcelWriter", "ExcelFile"]
+
+
+register_writer(_OpenpyxlWriter)
+
+register_writer(_XlsxWriter)
+
+
+register_writer(_ODSWriter)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_base.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_base.py
new file mode 100644
index 0000000000000000000000000000000000000000..786f719337b84a29e5b6ea7577edd412b596920f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_base.py
@@ -0,0 +1,1659 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Mapping,
+    Sequence,
+)
+import datetime
+from functools import partial
+from io import BytesIO
+import os
+from textwrap import fill
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    TypeVar,
+    Union,
+    cast,
+    overload,
+)
+import warnings
+import zipfile
+
+from pandas._config import config
+
+from pandas._libs import lib
+from pandas._libs.parsers import STR_NA_VALUES
+from pandas.compat._optional import (
+    get_version,
+    import_optional_dependency,
+)
+from pandas.errors import EmptyDataError
+from pandas.util._decorators import (
+    Appender,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import (
+    is_bool,
+    is_float,
+    is_integer,
+    is_list_like,
+)
+
+from pandas.core.frame import DataFrame
+from pandas.core.shared_docs import _shared_docs
+from pandas.util.version import Version
+
+from pandas.io.common import (
+    IOHandles,
+    get_handle,
+    stringify_path,
+    validate_header_arg,
+)
+from pandas.io.excel._util import (
+    fill_mi_header,
+    get_default_engine,
+    get_writer,
+    maybe_convert_usecols,
+    pop_header_name,
+)
+from pandas.io.parsers import TextParser
+from pandas.io.parsers.readers import validate_integer
+
+if TYPE_CHECKING:
+    from types import TracebackType
+
+    from pandas._typing import (
+        DtypeArg,
+        DtypeBackend,
+        ExcelWriterIfSheetExists,
+        FilePath,
+        IntStrT,
+        ReadBuffer,
+        Self,
+        SequenceNotStr,
+        StorageOptions,
+        WriteExcelBuffer,
+    )
+_read_excel_doc = (
+    """
+Read an Excel file into a ``pandas`` ``DataFrame``.
+
+Supports `xls`, `xlsx`, `xlsm`, `xlsb`, `odf`, `ods` and `odt` file extensions
+read from a local filesystem or URL. Supports an option to read
+a single sheet or a list of sheets.
+
+Parameters
+----------
+io : str, bytes, ExcelFile, xlrd.Book, path object, or file-like object
+    Any valid string path is acceptable. The string could be a URL. Valid
+    URL schemes include http, ftp, s3, and file. For file URLs, a host is
+    expected. A local file could be: ``file://localhost/path/to/table.xlsx``.
+
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
+
+    By file-like object, we refer to objects with a ``read()`` method,
+    such as a file handle (e.g. via builtin ``open`` function)
+    or ``StringIO``.
+
+    .. deprecated:: 2.1.0
+        Passing byte strings is deprecated. To read from a
+        byte string, wrap it in a ``BytesIO`` object.
+sheet_name : str, int, list, or None, default 0
+    Strings are used for sheet names. Integers are used in zero-indexed
+    sheet positions (chart sheets do not count as a sheet position).
+    Lists of strings/integers are used to request multiple sheets.
+    Specify ``None`` to get all worksheets.
+
+    Available cases:
+
+    * Defaults to ``0``: 1st sheet as a `DataFrame`
+    * ``1``: 2nd sheet as a `DataFrame`
+    * ``"Sheet1"``: Load sheet with name "Sheet1"
+    * ``[0, 1, "Sheet5"]``: Load first, second and sheet named "Sheet5"
+      as a dict of `DataFrame`
+    * ``None``: All worksheets.
+
+header : int, list of int, default 0
+    Row (0-indexed) to use for the column labels of the parsed
+    DataFrame. If a list of integers is passed those row positions will
+    be combined into a ``MultiIndex``. Use None if there is no header.
+names : array-like, default None
+    List of column names to use. If file contains no header row,
+    then you should explicitly pass header=None.
+index_col : int, str, list of int, default None
+    Column (0-indexed) to use as the row labels of the DataFrame.
+    Pass None if there is no such column.  If a list is passed,
+    those columns will be combined into a ``MultiIndex``.  If a
+    subset of data is selected with ``usecols``, index_col
+    is based on the subset.
+
+    Missing values will be forward filled to allow roundtripping with
+    ``to_excel`` for ``merged_cells=True``. To avoid forward filling the
+    missing values use ``set_index`` after reading the data instead of
+    ``index_col``.
+usecols : str, list-like, or callable, default None
+    * If None, then parse all columns.
+    * If str, then indicates comma separated list of Excel column letters
+      and column ranges (e.g. "A:E" or "A,C,E:F"). Ranges are inclusive of
+      both sides.
+    * If list of int, then indicates list of column numbers to be parsed
+      (0-indexed).
+    * If list of string, then indicates list of column names to be parsed.
+    * If callable, then evaluate each column name against it and parse the
+      column if the callable returns ``True``.
+
+    Returns a subset of the columns according to behavior above.
+dtype : Type name or dict of column -> type, default None
+    Data type for data or columns. E.g. {{'a': np.float64, 'b': np.int32}}
+    Use ``object`` to preserve data as stored in Excel and not interpret dtype,
+    which will necessarily result in ``object`` dtype.
+    If converters are specified, they will be applied INSTEAD
+    of dtype conversion.
+    If you use ``None``, it will infer the dtype of each column based on the data.
+engine : {{'openpyxl', 'calamine', 'odf', 'pyxlsb', 'xlrd'}}, default None
+    If io is not a buffer or path, this must be set to identify io.
+    Engine compatibility :
+
+    - ``openpyxl`` supports newer Excel file formats.
+    - ``calamine`` supports Excel (.xls, .xlsx, .xlsm, .xlsb)
+      and OpenDocument (.ods) file formats.
+    - ``odf`` supports OpenDocument file formats (.odf, .ods, .odt).
+    - ``pyxlsb`` supports Binary Excel files.
+    - ``xlrd`` supports old-style Excel files (.xls).
+
+    When ``engine=None``, the following logic will be used to determine the engine:
+
+    - If ``path_or_buffer`` is an OpenDocument format (.odf, .ods, .odt),
+      then `odf `_ will be used.
+    - Otherwise if ``path_or_buffer`` is an xls format, ``xlrd`` will be used.
+    - Otherwise if ``path_or_buffer`` is in xlsb format, ``pyxlsb`` will be used.
+    - Otherwise ``openpyxl`` will be used.
+converters : dict, default None
+    Dict of functions for converting values in certain columns. Keys can
+    either be integers or column labels, values are functions that take one
+    input argument, the Excel cell content, and return the transformed
+    content.
+true_values : list, default None
+    Values to consider as True.
+false_values : list, default None
+    Values to consider as False.
+skiprows : list-like, int, or callable, optional
+    Line numbers to skip (0-indexed) or number of lines to skip (int) at the
+    start of the file. If callable, the callable function will be evaluated
+    against the row indices, returning True if the row should be skipped and
+    False otherwise. An example of a valid callable argument would be ``lambda
+    x: x in [0, 2]``.
+nrows : int, default None
+    Number of rows to parse.
+na_values : scalar, str, list-like, or dict, default None
+    Additional strings to recognize as NA/NaN. If dict passed, specific
+    per-column NA values. By default the following values are interpreted
+    as NaN: '"""
+    + fill("', '".join(sorted(STR_NA_VALUES)), 70, subsequent_indent="    ")
+    + """'.
+keep_default_na : bool, default True
+    Whether or not to include the default NaN values when parsing the data.
+    Depending on whether ``na_values`` is passed in, the behavior is as follows:
+
+    * If ``keep_default_na`` is True, and ``na_values`` are specified,
+      ``na_values`` is appended to the default NaN values used for parsing.
+    * If ``keep_default_na`` is True, and ``na_values`` are not specified, only
+      the default NaN values are used for parsing.
+    * If ``keep_default_na`` is False, and ``na_values`` are specified, only
+      the NaN values specified ``na_values`` are used for parsing.
+    * If ``keep_default_na`` is False, and ``na_values`` are not specified, no
+      strings will be parsed as NaN.
+
+    Note that if `na_filter` is passed in as False, the ``keep_default_na`` and
+    ``na_values`` parameters will be ignored.
+na_filter : bool, default True
+    Detect missing value markers (empty strings and the value of na_values). In
+    data without any NAs, passing ``na_filter=False`` can improve the
+    performance of reading a large file.
+verbose : bool, default False
+    Indicate number of NA values placed in non-numeric columns.
+parse_dates : bool, list-like, or dict, default False
+    The behavior is as follows:
+
+    * ``bool``. If True -> try parsing the index.
+    * ``list`` of int or names. e.g. If [1, 2, 3] -> try parsing columns 1, 2, 3
+      each as a separate date column.
+    * ``list`` of lists. e.g.  If [[1, 3]] -> combine columns 1 and 3 and parse as
+      a single date column.
+    * ``dict``, e.g. {{'foo' : [1, 3]}} -> parse columns 1, 3 as date and call
+      result 'foo'
+
+    If a column or index contains an unparsable date, the entire column or
+    index will be returned unaltered as an object data type. If you don`t want to
+    parse some cells as date just change their type in Excel to "Text".
+    For non-standard datetime parsing, use ``pd.to_datetime`` after ``pd.read_excel``.
+
+    Note: A fast-path exists for iso8601-formatted dates.
+date_parser : function, optional
+    Function to use for converting a sequence of string columns to an array of
+    datetime instances. The default uses ``dateutil.parser.parser`` to do the
+    conversion. Pandas will try to call `date_parser` in three different ways,
+    advancing to the next if an exception occurs: 1) Pass one or more arrays
+    (as defined by `parse_dates`) as arguments; 2) concatenate (row-wise) the
+    string values from the columns defined by `parse_dates` into a single array
+    and pass that; and 3) call `date_parser` once for each row using one or
+    more strings (corresponding to the columns defined by `parse_dates`) as
+    arguments.
+
+    .. deprecated:: 2.0.0
+       Use ``date_format`` instead, or read in as ``object`` and then apply
+       :func:`to_datetime` as-needed.
+date_format : str or dict of column -> format, default ``None``
+   If used in conjunction with ``parse_dates``, will parse dates according to this
+   format. For anything more complex,
+   please read in as ``object`` and then apply :func:`to_datetime` as-needed.
+
+   .. versionadded:: 2.0.0
+thousands : str, default None
+    Thousands separator for parsing string columns to numeric.  Note that
+    this parameter is only necessary for columns stored as TEXT in Excel,
+    any numeric columns will automatically be parsed, regardless of display
+    format.
+decimal : str, default '.'
+    Character to recognize as decimal point for parsing string columns to numeric.
+    Note that this parameter is only necessary for columns stored as TEXT in Excel,
+    any numeric columns will automatically be parsed, regardless of display
+    format.(e.g. use ',' for European data).
+
+    .. versionadded:: 1.4.0
+
+comment : str, default None
+    Comments out remainder of line. Pass a character or characters to this
+    argument to indicate comments in the input file. Any data between the
+    comment string and the end of the current line is ignored.
+skipfooter : int, default 0
+    Rows at the end to skip (0-indexed).
+{storage_options}
+
+dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+    Back-end data type applied to the resultant :class:`DataFrame`
+    (still experimental). Behaviour is as follows:
+
+    * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+      (default).
+    * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+      DataFrame.
+
+    .. versionadded:: 2.0
+
+engine_kwargs : dict, optional
+    Arbitrary keyword arguments passed to excel engine.
+
+Returns
+-------
+DataFrame or dict of DataFrames
+    DataFrame from the passed in Excel file. See notes in sheet_name
+    argument for more information on when a dict of DataFrames is returned.
+
+See Also
+--------
+DataFrame.to_excel : Write DataFrame to an Excel file.
+DataFrame.to_csv : Write DataFrame to a comma-separated values (csv) file.
+read_csv : Read a comma-separated values (csv) file into DataFrame.
+read_fwf : Read a table of fixed-width formatted lines into DataFrame.
+
+Notes
+-----
+For specific information on the methods used for each Excel engine, refer to the pandas
+:ref:`user guide `
+
+Examples
+--------
+The file can be read using the file name as string or an open file object:
+
+>>> pd.read_excel('tmp.xlsx', index_col=0)  # doctest: +SKIP
+       Name  Value
+0   string1      1
+1   string2      2
+2  #Comment      3
+
+>>> pd.read_excel(open('tmp.xlsx', 'rb'),
+...               sheet_name='Sheet3')  # doctest: +SKIP
+   Unnamed: 0      Name  Value
+0           0   string1      1
+1           1   string2      2
+2           2  #Comment      3
+
+Index and header can be specified via the `index_col` and `header` arguments
+
+>>> pd.read_excel('tmp.xlsx', index_col=None, header=None)  # doctest: +SKIP
+     0         1      2
+0  NaN      Name  Value
+1  0.0   string1      1
+2  1.0   string2      2
+3  2.0  #Comment      3
+
+Column types are inferred but can be explicitly specified
+
+>>> pd.read_excel('tmp.xlsx', index_col=0,
+...               dtype={{'Name': str, 'Value': float}})  # doctest: +SKIP
+       Name  Value
+0   string1    1.0
+1   string2    2.0
+2  #Comment    3.0
+
+True, False, and NA values, and thousands separators have defaults,
+but can be explicitly specified, too. Supply the values you would like
+as strings or lists of strings!
+
+>>> pd.read_excel('tmp.xlsx', index_col=0,
+...               na_values=['string1', 'string2'])  # doctest: +SKIP
+       Name  Value
+0       NaN      1
+1       NaN      2
+2  #Comment      3
+
+Comment lines in the excel input file can be skipped using the
+``comment`` kwarg.
+
+>>> pd.read_excel('tmp.xlsx', index_col=0, comment='#')  # doctest: +SKIP
+      Name  Value
+0  string1    1.0
+1  string2    2.0
+2     None    NaN
+"""
+)
+
+
+@overload
+def read_excel(
+    io,
+    # sheet name is str or int -> DataFrame
+    sheet_name: str | int = ...,
+    *,
+    header: int | Sequence[int] | None = ...,
+    names: SequenceNotStr[Hashable] | range | None = ...,
+    index_col: int | str | Sequence[int] | None = ...,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = ...,
+    dtype: DtypeArg | None = ...,
+    engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = ...,
+    converters: dict[str, Callable] | dict[int, Callable] | None = ...,
+    true_values: Iterable[Hashable] | None = ...,
+    false_values: Iterable[Hashable] | None = ...,
+    skiprows: Sequence[int] | int | Callable[[int], object] | None = ...,
+    nrows: int | None = ...,
+    na_values=...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool = ...,
+    parse_dates: list | dict | bool = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: dict[Hashable, str] | str | None = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    comment: str | None = ...,
+    skipfooter: int = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame:
+    ...
+
+
+@overload
+def read_excel(
+    io,
+    # sheet name is list or None -> dict[IntStrT, DataFrame]
+    sheet_name: list[IntStrT] | None,
+    *,
+    header: int | Sequence[int] | None = ...,
+    names: SequenceNotStr[Hashable] | range | None = ...,
+    index_col: int | str | Sequence[int] | None = ...,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = ...,
+    dtype: DtypeArg | None = ...,
+    engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = ...,
+    converters: dict[str, Callable] | dict[int, Callable] | None = ...,
+    true_values: Iterable[Hashable] | None = ...,
+    false_values: Iterable[Hashable] | None = ...,
+    skiprows: Sequence[int] | int | Callable[[int], object] | None = ...,
+    nrows: int | None = ...,
+    na_values=...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool = ...,
+    parse_dates: list | dict | bool = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: dict[Hashable, str] | str | None = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    comment: str | None = ...,
+    skipfooter: int = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> dict[IntStrT, DataFrame]:
+    ...
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+@Appender(_read_excel_doc)
+def read_excel(
+    io,
+    sheet_name: str | int | list[IntStrT] | None = 0,
+    *,
+    header: int | Sequence[int] | None = 0,
+    names: SequenceNotStr[Hashable] | range | None = None,
+    index_col: int | str | Sequence[int] | None = None,
+    usecols: int
+    | str
+    | Sequence[int]
+    | Sequence[str]
+    | Callable[[str], bool]
+    | None = None,
+    dtype: DtypeArg | None = None,
+    engine: Literal["xlrd", "openpyxl", "odf", "pyxlsb", "calamine"] | None = None,
+    converters: dict[str, Callable] | dict[int, Callable] | None = None,
+    true_values: Iterable[Hashable] | None = None,
+    false_values: Iterable[Hashable] | None = None,
+    skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
+    nrows: int | None = None,
+    na_values=None,
+    keep_default_na: bool = True,
+    na_filter: bool = True,
+    verbose: bool = False,
+    parse_dates: list | dict | bool = False,
+    date_parser: Callable | lib.NoDefault = lib.no_default,
+    date_format: dict[Hashable, str] | str | None = None,
+    thousands: str | None = None,
+    decimal: str = ".",
+    comment: str | None = None,
+    skipfooter: int = 0,
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    engine_kwargs: dict | None = None,
+) -> DataFrame | dict[IntStrT, DataFrame]:
+    check_dtype_backend(dtype_backend)
+    should_close = False
+    if engine_kwargs is None:
+        engine_kwargs = {}
+
+    if not isinstance(io, ExcelFile):
+        should_close = True
+        io = ExcelFile(
+            io,
+            storage_options=storage_options,
+            engine=engine,
+            engine_kwargs=engine_kwargs,
+        )
+    elif engine and engine != io.engine:
+        raise ValueError(
+            "Engine should not be specified when passing "
+            "an ExcelFile - ExcelFile already has the engine set"
+        )
+
+    try:
+        data = io.parse(
+            sheet_name=sheet_name,
+            header=header,
+            names=names,
+            index_col=index_col,
+            usecols=usecols,
+            dtype=dtype,
+            converters=converters,
+            true_values=true_values,
+            false_values=false_values,
+            skiprows=skiprows,
+            nrows=nrows,
+            na_values=na_values,
+            keep_default_na=keep_default_na,
+            na_filter=na_filter,
+            verbose=verbose,
+            parse_dates=parse_dates,
+            date_parser=date_parser,
+            date_format=date_format,
+            thousands=thousands,
+            decimal=decimal,
+            comment=comment,
+            skipfooter=skipfooter,
+            dtype_backend=dtype_backend,
+        )
+    finally:
+        # make sure to close opened file handles
+        if should_close:
+            io.close()
+    return data
+
+
+_WorkbookT = TypeVar("_WorkbookT")
+
+
+class BaseExcelReader(Generic[_WorkbookT]):
+    book: _WorkbookT
+
+    def __init__(
+        self,
+        filepath_or_buffer,
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        if engine_kwargs is None:
+            engine_kwargs = {}
+
+        # First argument can also be bytes, so create a buffer
+        if isinstance(filepath_or_buffer, bytes):
+            filepath_or_buffer = BytesIO(filepath_or_buffer)
+
+        self.handles = IOHandles(
+            handle=filepath_or_buffer, compression={"method": None}
+        )
+        if not isinstance(filepath_or_buffer, (ExcelFile, self._workbook_class)):
+            self.handles = get_handle(
+                filepath_or_buffer, "rb", storage_options=storage_options, is_text=False
+            )
+
+        if isinstance(self.handles.handle, self._workbook_class):
+            self.book = self.handles.handle
+        elif hasattr(self.handles.handle, "read"):
+            # N.B. xlrd.Book has a read attribute too
+            self.handles.handle.seek(0)
+            try:
+                self.book = self.load_workbook(self.handles.handle, engine_kwargs)
+            except Exception:
+                self.close()
+                raise
+        else:
+            raise ValueError(
+                "Must explicitly set engine if not passing in buffer or path for io."
+            )
+
+    @property
+    def _workbook_class(self) -> type[_WorkbookT]:
+        raise NotImplementedError
+
+    def load_workbook(self, filepath_or_buffer, engine_kwargs) -> _WorkbookT:
+        raise NotImplementedError
+
+    def close(self) -> None:
+        if hasattr(self, "book"):
+            if hasattr(self.book, "close"):
+                # pyxlsb: opens a TemporaryFile
+                # openpyxl: https://stackoverflow.com/questions/31416842/
+                #     openpyxl-does-not-close-excel-workbook-in-read-only-mode
+                self.book.close()
+            elif hasattr(self.book, "release_resources"):
+                # xlrd
+                # https://github.com/python-excel/xlrd/blob/2.0.1/xlrd/book.py#L548
+                self.book.release_resources()
+        self.handles.close()
+
+    @property
+    def sheet_names(self) -> list[str]:
+        raise NotImplementedError
+
+    def get_sheet_by_name(self, name: str):
+        raise NotImplementedError
+
+    def get_sheet_by_index(self, index: int):
+        raise NotImplementedError
+
+    def get_sheet_data(self, sheet, rows: int | None = None):
+        raise NotImplementedError
+
+    def raise_if_bad_sheet_by_index(self, index: int) -> None:
+        n_sheets = len(self.sheet_names)
+        if index >= n_sheets:
+            raise ValueError(
+                f"Worksheet index {index} is invalid, {n_sheets} worksheets found"
+            )
+
+    def raise_if_bad_sheet_by_name(self, name: str) -> None:
+        if name not in self.sheet_names:
+            raise ValueError(f"Worksheet named '{name}' not found")
+
+    def _check_skiprows_func(
+        self,
+        skiprows: Callable,
+        rows_to_use: int,
+    ) -> int:
+        """
+        Determine how many file rows are required to obtain `nrows` data
+        rows when `skiprows` is a function.
+
+        Parameters
+        ----------
+        skiprows : function
+            The function passed to read_excel by the user.
+        rows_to_use : int
+            The number of rows that will be needed for the header and
+            the data.
+
+        Returns
+        -------
+        int
+        """
+        i = 0
+        rows_used_so_far = 0
+        while rows_used_so_far < rows_to_use:
+            if not skiprows(i):
+                rows_used_so_far += 1
+            i += 1
+        return i
+
+    def _calc_rows(
+        self,
+        header: int | Sequence[int] | None,
+        index_col: int | Sequence[int] | None,
+        skiprows: Sequence[int] | int | Callable[[int], object] | None,
+        nrows: int | None,
+    ) -> int | None:
+        """
+        If nrows specified, find the number of rows needed from the
+        file, otherwise return None.
+
+
+        Parameters
+        ----------
+        header : int, list of int, or None
+            See read_excel docstring.
+        index_col : int, str, list of int, or None
+            See read_excel docstring.
+        skiprows : list-like, int, callable, or None
+            See read_excel docstring.
+        nrows : int or None
+            See read_excel docstring.
+
+        Returns
+        -------
+        int or None
+        """
+        if nrows is None:
+            return None
+        if header is None:
+            header_rows = 1
+        elif is_integer(header):
+            header = cast(int, header)
+            header_rows = 1 + header
+        else:
+            header = cast(Sequence, header)
+            header_rows = 1 + header[-1]
+        # If there is a MultiIndex header and an index then there is also
+        # a row containing just the index name(s)
+        if is_list_like(header) and index_col is not None:
+            header = cast(Sequence, header)
+            if len(header) > 1:
+                header_rows += 1
+        if skiprows is None:
+            return header_rows + nrows
+        if is_integer(skiprows):
+            skiprows = cast(int, skiprows)
+            return header_rows + nrows + skiprows
+        if is_list_like(skiprows):
+
+            def f(skiprows: Sequence, x: int) -> bool:
+                return x in skiprows
+
+            skiprows = cast(Sequence, skiprows)
+            return self._check_skiprows_func(partial(f, skiprows), header_rows + nrows)
+        if callable(skiprows):
+            return self._check_skiprows_func(
+                skiprows,
+                header_rows + nrows,
+            )
+        # else unexpected skiprows type: read_excel will not optimize
+        # the number of rows read from file
+        return None
+
+    def parse(
+        self,
+        sheet_name: str | int | list[int] | list[str] | None = 0,
+        header: int | Sequence[int] | None = 0,
+        names: SequenceNotStr[Hashable] | range | None = None,
+        index_col: int | Sequence[int] | None = None,
+        usecols=None,
+        dtype: DtypeArg | None = None,
+        true_values: Iterable[Hashable] | None = None,
+        false_values: Iterable[Hashable] | None = None,
+        skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
+        nrows: int | None = None,
+        na_values=None,
+        verbose: bool = False,
+        parse_dates: list | dict | bool = False,
+        date_parser: Callable | lib.NoDefault = lib.no_default,
+        date_format: dict[Hashable, str] | str | None = None,
+        thousands: str | None = None,
+        decimal: str = ".",
+        comment: str | None = None,
+        skipfooter: int = 0,
+        dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+        **kwds,
+    ):
+        validate_header_arg(header)
+        validate_integer("nrows", nrows)
+
+        ret_dict = False
+
+        # Keep sheetname to maintain backwards compatibility.
+        sheets: list[int] | list[str]
+        if isinstance(sheet_name, list):
+            sheets = sheet_name
+            ret_dict = True
+        elif sheet_name is None:
+            sheets = self.sheet_names
+            ret_dict = True
+        elif isinstance(sheet_name, str):
+            sheets = [sheet_name]
+        else:
+            sheets = [sheet_name]
+
+        # handle same-type duplicates.
+        sheets = cast(Union[list[int], list[str]], list(dict.fromkeys(sheets).keys()))
+
+        output = {}
+
+        last_sheetname = None
+        for asheetname in sheets:
+            last_sheetname = asheetname
+            if verbose:
+                print(f"Reading sheet {asheetname}")
+
+            if isinstance(asheetname, str):
+                sheet = self.get_sheet_by_name(asheetname)
+            else:  # assume an integer if not a string
+                sheet = self.get_sheet_by_index(asheetname)
+
+            file_rows_needed = self._calc_rows(header, index_col, skiprows, nrows)
+            data = self.get_sheet_data(sheet, file_rows_needed)
+            if hasattr(sheet, "close"):
+                # pyxlsb opens two TemporaryFiles
+                sheet.close()
+            usecols = maybe_convert_usecols(usecols)
+
+            if not data:
+                output[asheetname] = DataFrame()
+                continue
+
+            is_list_header = False
+            is_len_one_list_header = False
+            if is_list_like(header):
+                assert isinstance(header, Sequence)
+                is_list_header = True
+                if len(header) == 1:
+                    is_len_one_list_header = True
+
+            if is_len_one_list_header:
+                header = cast(Sequence[int], header)[0]
+
+            # forward fill and pull out names for MultiIndex column
+            header_names = None
+            if header is not None and is_list_like(header):
+                assert isinstance(header, Sequence)
+
+                header_names = []
+                control_row = [True] * len(data[0])
+
+                for row in header:
+                    if is_integer(skiprows):
+                        assert isinstance(skiprows, int)
+                        row += skiprows
+
+                    if row > len(data) - 1:
+                        raise ValueError(
+                            f"header index {row} exceeds maximum index "
+                            f"{len(data) - 1} of data.",
+                        )
+
+                    data[row], control_row = fill_mi_header(data[row], control_row)
+
+                    if index_col is not None:
+                        header_name, _ = pop_header_name(data[row], index_col)
+                        header_names.append(header_name)
+
+            # If there is a MultiIndex header and an index then there is also
+            # a row containing just the index name(s)
+            has_index_names = False
+            if is_list_header and not is_len_one_list_header and index_col is not None:
+                index_col_list: Sequence[int]
+                if isinstance(index_col, int):
+                    index_col_list = [index_col]
+                else:
+                    assert isinstance(index_col, Sequence)
+                    index_col_list = index_col
+
+                # We have to handle mi without names. If any of the entries in the data
+                # columns are not empty, this is a regular row
+                assert isinstance(header, Sequence)
+                if len(header) < len(data):
+                    potential_index_names = data[len(header)]
+                    potential_data = [
+                        x
+                        for i, x in enumerate(potential_index_names)
+                        if not control_row[i] and i not in index_col_list
+                    ]
+                    has_index_names = all(x == "" or x is None for x in potential_data)
+
+            if is_list_like(index_col):
+                # Forward fill values for MultiIndex index.
+                if header is None:
+                    offset = 0
+                elif isinstance(header, int):
+                    offset = 1 + header
+                else:
+                    offset = 1 + max(header)
+
+                # GH34673: if MultiIndex names present and not defined in the header,
+                # offset needs to be incremented so that forward filling starts
+                # from the first MI value instead of the name
+                if has_index_names:
+                    offset += 1
+
+                # Check if we have an empty dataset
+                # before trying to collect data.
+                if offset < len(data):
+                    assert isinstance(index_col, Sequence)
+
+                    for col in index_col:
+                        last = data[offset][col]
+
+                        for row in range(offset + 1, len(data)):
+                            if data[row][col] == "" or data[row][col] is None:
+                                data[row][col] = last
+                            else:
+                                last = data[row][col]
+
+            # GH 12292 : error when read one empty column from excel file
+            try:
+                parser = TextParser(
+                    data,
+                    names=names,
+                    header=header,
+                    index_col=index_col,
+                    has_index_names=has_index_names,
+                    dtype=dtype,
+                    true_values=true_values,
+                    false_values=false_values,
+                    skiprows=skiprows,
+                    nrows=nrows,
+                    na_values=na_values,
+                    skip_blank_lines=False,  # GH 39808
+                    parse_dates=parse_dates,
+                    date_parser=date_parser,
+                    date_format=date_format,
+                    thousands=thousands,
+                    decimal=decimal,
+                    comment=comment,
+                    skipfooter=skipfooter,
+                    usecols=usecols,
+                    dtype_backend=dtype_backend,
+                    **kwds,
+                )
+
+                output[asheetname] = parser.read(nrows=nrows)
+
+                if header_names:
+                    output[asheetname].columns = output[asheetname].columns.set_names(
+                        header_names
+                    )
+
+            except EmptyDataError:
+                # No Data, return an empty DataFrame
+                output[asheetname] = DataFrame()
+
+            except Exception as err:
+                err.args = (f"{err.args[0]} (sheet: {asheetname})", *err.args[1:])
+                raise err
+
+        if last_sheetname is None:
+            raise ValueError("Sheet name is an empty list")
+
+        if ret_dict:
+            return output
+        else:
+            return output[last_sheetname]
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+class ExcelWriter(Generic[_WorkbookT]):
+    """
+    Class for writing DataFrame objects into excel sheets.
+
+    Default is to use:
+
+    * `xlsxwriter `__ for xlsx files if xlsxwriter
+      is installed otherwise `openpyxl `__
+    * `odswriter `__ for ods files
+
+    See ``DataFrame.to_excel`` for typical usage.
+
+    The writer should be used as a context manager. Otherwise, call `close()` to save
+    and close any opened file handles.
+
+    Parameters
+    ----------
+    path : str or typing.BinaryIO
+        Path to xls or xlsx or ods file.
+    engine : str (optional)
+        Engine to use for writing. If None, defaults to
+        ``io.excel..writer``.  NOTE: can only be passed as a keyword
+        argument.
+    date_format : str, default None
+        Format string for dates written into Excel files (e.g. 'YYYY-MM-DD').
+    datetime_format : str, default None
+        Format string for datetime objects written into Excel files.
+        (e.g. 'YYYY-MM-DD HH:MM:SS').
+    mode : {{'w', 'a'}}, default 'w'
+        File mode to use (write or append). Append does not work with fsspec URLs.
+    {storage_options}
+
+    if_sheet_exists : {{'error', 'new', 'replace', 'overlay'}}, default 'error'
+        How to behave when trying to write to a sheet that already
+        exists (append mode only).
+
+        * error: raise a ValueError.
+        * new: Create a new sheet, with a name determined by the engine.
+        * replace: Delete the contents of the sheet before writing to it.
+        * overlay: Write contents to the existing sheet without first removing,
+          but possibly over top of, the existing contents.
+
+        .. versionadded:: 1.3.0
+
+        .. versionchanged:: 1.4.0
+
+           Added ``overlay`` option
+
+    engine_kwargs : dict, optional
+        Keyword arguments to be passed into the engine. These will be passed to
+        the following functions of the respective engines:
+
+        * xlsxwriter: ``xlsxwriter.Workbook(file, **engine_kwargs)``
+        * openpyxl (write mode): ``openpyxl.Workbook(**engine_kwargs)``
+        * openpyxl (append mode): ``openpyxl.load_workbook(file, **engine_kwargs)``
+        * odswriter: ``odf.opendocument.OpenDocumentSpreadsheet(**engine_kwargs)``
+
+        .. versionadded:: 1.3.0
+
+    Notes
+    -----
+    For compatibility with CSV writers, ExcelWriter serializes lists
+    and dicts to strings before writing.
+
+    Examples
+    --------
+    Default usage:
+
+    >>> df = pd.DataFrame([["ABC", "XYZ"]], columns=["Foo", "Bar"])  # doctest: +SKIP
+    >>> with pd.ExcelWriter("path_to_file.xlsx") as writer:
+    ...     df.to_excel(writer)  # doctest: +SKIP
+
+    To write to separate sheets in a single file:
+
+    >>> df1 = pd.DataFrame([["AAA", "BBB"]], columns=["Spam", "Egg"])  # doctest: +SKIP
+    >>> df2 = pd.DataFrame([["ABC", "XYZ"]], columns=["Foo", "Bar"])  # doctest: +SKIP
+    >>> with pd.ExcelWriter("path_to_file.xlsx") as writer:
+    ...     df1.to_excel(writer, sheet_name="Sheet1")  # doctest: +SKIP
+    ...     df2.to_excel(writer, sheet_name="Sheet2")  # doctest: +SKIP
+
+    You can set the date format or datetime format:
+
+    >>> from datetime import date, datetime  # doctest: +SKIP
+    >>> df = pd.DataFrame(
+    ...     [
+    ...         [date(2014, 1, 31), date(1999, 9, 24)],
+    ...         [datetime(1998, 5, 26, 23, 33, 4), datetime(2014, 2, 28, 13, 5, 13)],
+    ...     ],
+    ...     index=["Date", "Datetime"],
+    ...     columns=["X", "Y"],
+    ... )  # doctest: +SKIP
+    >>> with pd.ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     date_format="YYYY-MM-DD",
+    ...     datetime_format="YYYY-MM-DD HH:MM:SS"
+    ... ) as writer:
+    ...     df.to_excel(writer)  # doctest: +SKIP
+
+    You can also append to an existing Excel file:
+
+    >>> with pd.ExcelWriter("path_to_file.xlsx", mode="a", engine="openpyxl") as writer:
+    ...     df.to_excel(writer, sheet_name="Sheet3")  # doctest: +SKIP
+
+    Here, the `if_sheet_exists` parameter can be set to replace a sheet if it
+    already exists:
+
+    >>> with ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     mode="a",
+    ...     engine="openpyxl",
+    ...     if_sheet_exists="replace",
+    ... ) as writer:
+    ...     df.to_excel(writer, sheet_name="Sheet1")  # doctest: +SKIP
+
+    You can also write multiple DataFrames to a single sheet. Note that the
+    ``if_sheet_exists`` parameter needs to be set to ``overlay``:
+
+    >>> with ExcelWriter("path_to_file.xlsx",
+    ...     mode="a",
+    ...     engine="openpyxl",
+    ...     if_sheet_exists="overlay",
+    ... ) as writer:
+    ...     df1.to_excel(writer, sheet_name="Sheet1")
+    ...     df2.to_excel(writer, sheet_name="Sheet1", startcol=3)  # doctest: +SKIP
+
+    You can store Excel file in RAM:
+
+    >>> import io
+    >>> df = pd.DataFrame([["ABC", "XYZ"]], columns=["Foo", "Bar"])
+    >>> buffer = io.BytesIO()
+    >>> with pd.ExcelWriter(buffer) as writer:
+    ...     df.to_excel(writer)
+
+    You can pack Excel file into zip archive:
+
+    >>> import zipfile  # doctest: +SKIP
+    >>> df = pd.DataFrame([["ABC", "XYZ"]], columns=["Foo", "Bar"])  # doctest: +SKIP
+    >>> with zipfile.ZipFile("path_to_file.zip", "w") as zf:
+    ...     with zf.open("filename.xlsx", "w") as buffer:
+    ...         with pd.ExcelWriter(buffer) as writer:
+    ...             df.to_excel(writer)  # doctest: +SKIP
+
+    You can specify additional arguments to the underlying engine:
+
+    >>> with pd.ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     engine="xlsxwriter",
+    ...     engine_kwargs={{"options": {{"nan_inf_to_errors": True}}}}
+    ... ) as writer:
+    ...     df.to_excel(writer)  # doctest: +SKIP
+
+    In append mode, ``engine_kwargs`` are passed through to
+    openpyxl's ``load_workbook``:
+
+    >>> with pd.ExcelWriter(
+    ...     "path_to_file.xlsx",
+    ...     engine="openpyxl",
+    ...     mode="a",
+    ...     engine_kwargs={{"keep_vba": True}}
+    ... ) as writer:
+    ...     df.to_excel(writer, sheet_name="Sheet2")  # doctest: +SKIP
+    """
+
+    # Defining an ExcelWriter implementation (see abstract methods for more...)
+
+    # - Mandatory
+    #   - ``write_cells(self, cells, sheet_name=None, startrow=0, startcol=0)``
+    #     --> called to write additional DataFrames to disk
+    #   - ``_supported_extensions`` (tuple of supported extensions), used to
+    #      check that engine supports the given extension.
+    #   - ``_engine`` - string that gives the engine name. Necessary to
+    #     instantiate class directly and bypass ``ExcelWriterMeta`` engine
+    #     lookup.
+    #   - ``save(self)`` --> called to save file to disk
+    # - Mostly mandatory (i.e. should at least exist)
+    #   - book, cur_sheet, path
+
+    # - Optional:
+    #   - ``__init__(self, path, engine=None, **kwargs)`` --> always called
+    #     with path as first argument.
+
+    # You also need to register the class with ``register_writer()``.
+    # Technically, ExcelWriter implementations don't need to subclass
+    # ExcelWriter.
+
+    _engine: str
+    _supported_extensions: tuple[str, ...]
+
+    def __new__(
+        cls,
+        path: FilePath | WriteExcelBuffer | ExcelWriter,
+        engine: str | None = None,
+        date_format: str | None = None,
+        datetime_format: str | None = None,
+        mode: str = "w",
+        storage_options: StorageOptions | None = None,
+        if_sheet_exists: ExcelWriterIfSheetExists | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> Self:
+        # only switch class if generic(ExcelWriter)
+        if cls is ExcelWriter:
+            if engine is None or (isinstance(engine, str) and engine == "auto"):
+                if isinstance(path, str):
+                    ext = os.path.splitext(path)[-1][1:]
+                else:
+                    ext = "xlsx"
+
+                try:
+                    engine = config.get_option(f"io.excel.{ext}.writer", silent=True)
+                    if engine == "auto":
+                        engine = get_default_engine(ext, mode="writer")
+                except KeyError as err:
+                    raise ValueError(f"No engine for filetype: '{ext}'") from err
+
+            # for mypy
+            assert engine is not None
+            #  error: Incompatible types in assignment (expression has type
+            #  "type[ExcelWriter[Any]]", variable has type "type[Self]")
+            cls = get_writer(engine)  # type: ignore[assignment]
+
+        return object.__new__(cls)
+
+    # declare external properties you can count on
+    _path = None
+
+    @property
+    def supported_extensions(self) -> tuple[str, ...]:
+        """Extensions that writer engine supports."""
+        return self._supported_extensions
+
+    @property
+    def engine(self) -> str:
+        """Name of engine."""
+        return self._engine
+
+    @property
+    def sheets(self) -> dict[str, Any]:
+        """Mapping of sheet names to sheet objects."""
+        raise NotImplementedError
+
+    @property
+    def book(self) -> _WorkbookT:
+        """
+        Book instance. Class type will depend on the engine used.
+
+        This attribute can be used to access engine-specific features.
+        """
+        raise NotImplementedError
+
+    def _write_cells(
+        self,
+        cells,
+        sheet_name: str | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        freeze_panes: tuple[int, int] | None = None,
+    ) -> None:
+        """
+        Write given formatted cells into Excel an excel sheet
+
+        Parameters
+        ----------
+        cells : generator
+            cell of formatted data to save to Excel sheet
+        sheet_name : str, default None
+            Name of Excel sheet, if None, then use self.cur_sheet
+        startrow : upper left cell row to dump data frame
+        startcol : upper left cell column to dump data frame
+        freeze_panes: int tuple of length 2
+            contains the bottom-most row and right-most column to freeze
+        """
+        raise NotImplementedError
+
+    def _save(self) -> None:
+        """
+        Save workbook to disk.
+        """
+        raise NotImplementedError
+
+    def __init__(
+        self,
+        path: FilePath | WriteExcelBuffer | ExcelWriter,
+        engine: str | None = None,
+        date_format: str | None = None,
+        datetime_format: str | None = None,
+        mode: str = "w",
+        storage_options: StorageOptions | None = None,
+        if_sheet_exists: ExcelWriterIfSheetExists | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+    ) -> None:
+        # validate that this engine can handle the extension
+        if isinstance(path, str):
+            ext = os.path.splitext(path)[-1]
+            self.check_extension(ext)
+
+        # use mode to open the file
+        if "b" not in mode:
+            mode += "b"
+        # use "a" for the user to append data to excel but internally use "r+" to let
+        # the excel backend first read the existing file and then write any data to it
+        mode = mode.replace("a", "r+")
+
+        if if_sheet_exists not in (None, "error", "new", "replace", "overlay"):
+            raise ValueError(
+                f"'{if_sheet_exists}' is not valid for if_sheet_exists. "
+                "Valid options are 'error', 'new', 'replace' and 'overlay'."
+            )
+        if if_sheet_exists and "r+" not in mode:
+            raise ValueError("if_sheet_exists is only valid in append mode (mode='a')")
+        if if_sheet_exists is None:
+            if_sheet_exists = "error"
+        self._if_sheet_exists = if_sheet_exists
+
+        # cast ExcelWriter to avoid adding 'if self._handles is not None'
+        self._handles = IOHandles(
+            cast(IO[bytes], path), compression={"compression": None}
+        )
+        if not isinstance(path, ExcelWriter):
+            self._handles = get_handle(
+                path, mode, storage_options=storage_options, is_text=False
+            )
+        self._cur_sheet = None
+
+        if date_format is None:
+            self._date_format = "YYYY-MM-DD"
+        else:
+            self._date_format = date_format
+        if datetime_format is None:
+            self._datetime_format = "YYYY-MM-DD HH:MM:SS"
+        else:
+            self._datetime_format = datetime_format
+
+        self._mode = mode
+
+    @property
+    def date_format(self) -> str:
+        """
+        Format string for dates written into Excel files (e.g. 'YYYY-MM-DD').
+        """
+        return self._date_format
+
+    @property
+    def datetime_format(self) -> str:
+        """
+        Format string for dates written into Excel files (e.g. 'YYYY-MM-DD').
+        """
+        return self._datetime_format
+
+    @property
+    def if_sheet_exists(self) -> str:
+        """
+        How to behave when writing to a sheet that already exists in append mode.
+        """
+        return self._if_sheet_exists
+
+    def __fspath__(self) -> str:
+        return getattr(self._handles.handle, "name", "")
+
+    def _get_sheet_name(self, sheet_name: str | None) -> str:
+        if sheet_name is None:
+            sheet_name = self._cur_sheet
+        if sheet_name is None:  # pragma: no cover
+            raise ValueError("Must pass explicit sheet_name or set _cur_sheet property")
+        return sheet_name
+
+    def _value_with_fmt(
+        self, val
+    ) -> tuple[
+        int | float | bool | str | datetime.datetime | datetime.date, str | None
+    ]:
+        """
+        Convert numpy types to Python types for the Excel writers.
+
+        Parameters
+        ----------
+        val : object
+            Value to be written into cells
+
+        Returns
+        -------
+        Tuple with the first element being the converted value and the second
+            being an optional format
+        """
+        fmt = None
+
+        if is_integer(val):
+            val = int(val)
+        elif is_float(val):
+            val = float(val)
+        elif is_bool(val):
+            val = bool(val)
+        elif isinstance(val, datetime.datetime):
+            fmt = self._datetime_format
+        elif isinstance(val, datetime.date):
+            fmt = self._date_format
+        elif isinstance(val, datetime.timedelta):
+            val = val.total_seconds() / 86400
+            fmt = "0"
+        else:
+            val = str(val)
+
+        return val, fmt
+
+    @classmethod
+    def check_extension(cls, ext: str) -> Literal[True]:
+        """
+        checks that path's extension against the Writer's supported
+        extensions.  If it isn't supported, raises UnsupportedFiletypeError.
+        """
+        if ext.startswith("."):
+            ext = ext[1:]
+        if not any(ext in extension for extension in cls._supported_extensions):
+            raise ValueError(f"Invalid extension for engine '{cls.engine}': '{ext}'")
+        return True
+
+    # Allow use as a contextmanager
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """synonym for save, to make it more file-like"""
+        self._save()
+        self._handles.close()
+
+
+XLS_SIGNATURES = (
+    b"\x09\x00\x04\x00\x07\x00\x10\x00",  # BIFF2
+    b"\x09\x02\x06\x00\x00\x00\x10\x00",  # BIFF3
+    b"\x09\x04\x06\x00\x00\x00\x10\x00",  # BIFF4
+    b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1",  # Compound File Binary
+)
+ZIP_SIGNATURE = b"PK\x03\x04"
+PEEK_SIZE = max(map(len, XLS_SIGNATURES + (ZIP_SIGNATURE,)))
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def inspect_excel_format(
+    content_or_path: FilePath | ReadBuffer[bytes],
+    storage_options: StorageOptions | None = None,
+) -> str | None:
+    """
+    Inspect the path or content of an excel file and get its format.
+
+    Adopted from xlrd: https://github.com/python-excel/xlrd.
+
+    Parameters
+    ----------
+    content_or_path : str or file-like object
+        Path to file or content of file to inspect. May be a URL.
+    {storage_options}
+
+    Returns
+    -------
+    str or None
+        Format of file if it can be determined.
+
+    Raises
+    ------
+    ValueError
+        If resulting stream is empty.
+    BadZipFile
+        If resulting stream does not have an XLS signature and is not a valid zipfile.
+    """
+    if isinstance(content_or_path, bytes):
+        content_or_path = BytesIO(content_or_path)
+
+    with get_handle(
+        content_or_path, "rb", storage_options=storage_options, is_text=False
+    ) as handle:
+        stream = handle.handle
+        stream.seek(0)
+        buf = stream.read(PEEK_SIZE)
+        if buf is None:
+            raise ValueError("stream is empty")
+        assert isinstance(buf, bytes)
+        peek = buf
+        stream.seek(0)
+
+        if any(peek.startswith(sig) for sig in XLS_SIGNATURES):
+            return "xls"
+        elif not peek.startswith(ZIP_SIGNATURE):
+            return None
+
+        with zipfile.ZipFile(stream) as zf:
+            # Workaround for some third party files that use forward slashes and
+            # lower case names.
+            component_names = [
+                name.replace("\\", "/").lower() for name in zf.namelist()
+            ]
+
+        if "xl/workbook.xml" in component_names:
+            return "xlsx"
+        if "xl/workbook.bin" in component_names:
+            return "xlsb"
+        if "content.xml" in component_names:
+            return "ods"
+        return "zip"
+
+
+class ExcelFile:
+    """
+    Class for parsing tabular Excel sheets into DataFrame objects.
+
+    See read_excel for more documentation.
+
+    Parameters
+    ----------
+    path_or_buffer : str, bytes, path object (pathlib.Path or py._path.local.LocalPath),
+        A file-like object, xlrd workbook or openpyxl workbook.
+        If a string or path object, expected to be a path to a
+        .xls, .xlsx, .xlsb, .xlsm, .odf, .ods, or .odt file.
+    engine : str, default None
+        If io is not a buffer or path, this must be set to identify io.
+        Supported engines: ``xlrd``, ``openpyxl``, ``odf``, ``pyxlsb``, ``calamine``
+        Engine compatibility :
+
+        - ``xlrd`` supports old-style Excel files (.xls).
+        - ``openpyxl`` supports newer Excel file formats.
+        - ``odf`` supports OpenDocument file formats (.odf, .ods, .odt).
+        - ``pyxlsb`` supports Binary Excel files.
+        - ``calamine`` supports Excel (.xls, .xlsx, .xlsm, .xlsb)
+          and OpenDocument (.ods) file formats.
+
+        .. versionchanged:: 1.2.0
+
+           The engine `xlrd `_
+           now only supports old-style ``.xls`` files.
+           When ``engine=None``, the following logic will be
+           used to determine the engine:
+
+           - If ``path_or_buffer`` is an OpenDocument format (.odf, .ods, .odt),
+             then `odf `_ will be used.
+           - Otherwise if ``path_or_buffer`` is an xls format,
+             ``xlrd`` will be used.
+           - Otherwise if ``path_or_buffer`` is in xlsb format,
+             `pyxlsb `_ will be used.
+
+           .. versionadded:: 1.3.0
+
+           - Otherwise if `openpyxl `_ is installed,
+             then ``openpyxl`` will be used.
+           - Otherwise if ``xlrd >= 2.0`` is installed, a ``ValueError`` will be raised.
+
+           .. warning::
+
+            Please do not report issues when using ``xlrd`` to read ``.xlsx`` files.
+            This is not supported, switch to using ``openpyxl`` instead.
+    engine_kwargs : dict, optional
+        Arbitrary keyword arguments passed to excel engine.
+
+    Examples
+    --------
+    >>> file = pd.ExcelFile('myfile.xlsx')  # doctest: +SKIP
+    >>> with pd.ExcelFile("myfile.xls") as xls:  # doctest: +SKIP
+    ...     df1 = pd.read_excel(xls, "Sheet1")  # doctest: +SKIP
+    """
+
+    from pandas.io.excel._calamine import CalamineReader
+    from pandas.io.excel._odfreader import ODFReader
+    from pandas.io.excel._openpyxl import OpenpyxlReader
+    from pandas.io.excel._pyxlsb import PyxlsbReader
+    from pandas.io.excel._xlrd import XlrdReader
+
+    _engines: Mapping[str, Any] = {
+        "xlrd": XlrdReader,
+        "openpyxl": OpenpyxlReader,
+        "odf": ODFReader,
+        "pyxlsb": PyxlsbReader,
+        "calamine": CalamineReader,
+    }
+
+    def __init__(
+        self,
+        path_or_buffer,
+        engine: str | None = None,
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        if engine_kwargs is None:
+            engine_kwargs = {}
+
+        if engine is not None and engine not in self._engines:
+            raise ValueError(f"Unknown engine: {engine}")
+
+        # First argument can also be bytes, so create a buffer
+        if isinstance(path_or_buffer, bytes):
+            path_or_buffer = BytesIO(path_or_buffer)
+            warnings.warn(
+                "Passing bytes to 'read_excel' is deprecated and "
+                "will be removed in a future version. To read from a "
+                "byte string, wrap it in a `BytesIO` object.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        # Could be a str, ExcelFile, Book, etc.
+        self.io = path_or_buffer
+        # Always a string
+        self._io = stringify_path(path_or_buffer)
+
+        # Determine xlrd version if installed
+        if import_optional_dependency("xlrd", errors="ignore") is None:
+            xlrd_version = None
+        else:
+            import xlrd
+
+            xlrd_version = Version(get_version(xlrd))
+
+        if engine is None:
+            # Only determine ext if it is needed
+            ext: str | None
+            if xlrd_version is not None and isinstance(path_or_buffer, xlrd.Book):
+                ext = "xls"
+            else:
+                ext = inspect_excel_format(
+                    content_or_path=path_or_buffer, storage_options=storage_options
+                )
+                if ext is None:
+                    raise ValueError(
+                        "Excel file format cannot be determined, you must specify "
+                        "an engine manually."
+                    )
+
+            engine = config.get_option(f"io.excel.{ext}.reader", silent=True)
+            if engine == "auto":
+                engine = get_default_engine(ext, mode="reader")
+
+        assert engine is not None
+        self.engine = engine
+        self.storage_options = storage_options
+
+        self._reader = self._engines[engine](
+            self._io,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    def __fspath__(self):
+        return self._io
+
+    def parse(
+        self,
+        sheet_name: str | int | list[int] | list[str] | None = 0,
+        header: int | Sequence[int] | None = 0,
+        names: SequenceNotStr[Hashable] | range | None = None,
+        index_col: int | Sequence[int] | None = None,
+        usecols=None,
+        converters=None,
+        true_values: Iterable[Hashable] | None = None,
+        false_values: Iterable[Hashable] | None = None,
+        skiprows: Sequence[int] | int | Callable[[int], object] | None = None,
+        nrows: int | None = None,
+        na_values=None,
+        parse_dates: list | dict | bool = False,
+        date_parser: Callable | lib.NoDefault = lib.no_default,
+        date_format: str | dict[Hashable, str] | None = None,
+        thousands: str | None = None,
+        comment: str | None = None,
+        skipfooter: int = 0,
+        dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+        **kwds,
+    ) -> DataFrame | dict[str, DataFrame] | dict[int, DataFrame]:
+        """
+        Parse specified sheet(s) into a DataFrame.
+
+        Equivalent to read_excel(ExcelFile, ...)  See the read_excel
+        docstring for more info on accepted parameters.
+
+        Returns
+        -------
+        DataFrame or dict of DataFrames
+            DataFrame from the passed in Excel file.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2, 3], [4, 5, 6]], columns=['A', 'B', 'C'])
+        >>> df.to_excel('myfile.xlsx')  # doctest: +SKIP
+        >>> file = pd.ExcelFile('myfile.xlsx')  # doctest: +SKIP
+        >>> file.parse()  # doctest: +SKIP
+        """
+        return self._reader.parse(
+            sheet_name=sheet_name,
+            header=header,
+            names=names,
+            index_col=index_col,
+            usecols=usecols,
+            converters=converters,
+            true_values=true_values,
+            false_values=false_values,
+            skiprows=skiprows,
+            nrows=nrows,
+            na_values=na_values,
+            parse_dates=parse_dates,
+            date_parser=date_parser,
+            date_format=date_format,
+            thousands=thousands,
+            comment=comment,
+            skipfooter=skipfooter,
+            dtype_backend=dtype_backend,
+            **kwds,
+        )
+
+    @property
+    def book(self):
+        return self._reader.book
+
+    @property
+    def sheet_names(self):
+        return self._reader.sheet_names
+
+    def close(self) -> None:
+        """close io if necessary"""
+        self._reader.close()
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_calamine.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_calamine.py
new file mode 100644
index 0000000000000000000000000000000000000000..5259469f7a569a1913aa49635b3c14e89a18d157
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_calamine.py
@@ -0,0 +1,121 @@
+from __future__ import annotations
+
+from datetime import (
+    date,
+    datetime,
+    time,
+    timedelta,
+)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Union,
+)
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+
+import pandas as pd
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.excel._base import BaseExcelReader
+
+if TYPE_CHECKING:
+    from python_calamine import (
+        CalamineSheet,
+        CalamineWorkbook,
+    )
+
+    from pandas._typing import (
+        FilePath,
+        NaTType,
+        ReadBuffer,
+        Scalar,
+        StorageOptions,
+    )
+
+_CellValue = Union[int, float, str, bool, time, date, datetime, timedelta]
+
+
+class CalamineReader(BaseExcelReader["CalamineWorkbook"]):
+    @doc(storage_options=_shared_docs["storage_options"])
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Reader using calamine engine (xlsx/xls/xlsb/ods).
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path to be parsed or
+            an open readable stream.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        import_optional_dependency("python_calamine")
+        super().__init__(
+            filepath_or_buffer,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @property
+    def _workbook_class(self) -> type[CalamineWorkbook]:
+        from python_calamine import CalamineWorkbook
+
+        return CalamineWorkbook
+
+    def load_workbook(
+        self, filepath_or_buffer: FilePath | ReadBuffer[bytes], engine_kwargs: Any
+    ) -> CalamineWorkbook:
+        from python_calamine import load_workbook
+
+        return load_workbook(filepath_or_buffer, **engine_kwargs)
+
+    @property
+    def sheet_names(self) -> list[str]:
+        from python_calamine import SheetTypeEnum
+
+        return [
+            sheet.name
+            for sheet in self.book.sheets_metadata
+            if sheet.typ == SheetTypeEnum.WorkSheet
+        ]
+
+    def get_sheet_by_name(self, name: str) -> CalamineSheet:
+        self.raise_if_bad_sheet_by_name(name)
+        return self.book.get_sheet_by_name(name)
+
+    def get_sheet_by_index(self, index: int) -> CalamineSheet:
+        self.raise_if_bad_sheet_by_index(index)
+        return self.book.get_sheet_by_index(index)
+
+    def get_sheet_data(
+        self, sheet: CalamineSheet, file_rows_needed: int | None = None
+    ) -> list[list[Scalar | NaTType | time]]:
+        def _convert_cell(value: _CellValue) -> Scalar | NaTType | time:
+            if isinstance(value, float):
+                val = int(value)
+                if val == value:
+                    return val
+                else:
+                    return value
+            elif isinstance(value, date):
+                return pd.Timestamp(value)
+            elif isinstance(value, timedelta):
+                return pd.Timedelta(value)
+            elif isinstance(value, time):
+                return value
+
+            return value
+
+        rows: list[list[_CellValue]] = sheet.to_python(
+            skip_empty_area=False, nrows=file_rows_needed
+        )
+        data = [[_convert_cell(cell) for cell in row] for row in rows]
+
+        return data
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_odfreader.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_odfreader.py
new file mode 100644
index 0000000000000000000000000000000000000000..69b514da32857119f048a25f647d1002315a9889
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_odfreader.py
@@ -0,0 +1,253 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+
+import numpy as np
+
+from pandas._typing import (
+    FilePath,
+    ReadBuffer,
+    Scalar,
+    StorageOptions,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+
+import pandas as pd
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.excel._base import BaseExcelReader
+
+if TYPE_CHECKING:
+    from odf.opendocument import OpenDocument
+
+    from pandas._libs.tslibs.nattype import NaTType
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+class ODFReader(BaseExcelReader["OpenDocument"]):
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Read tables out of OpenDocument formatted files.
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path to be parsed or
+            an open readable stream.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        import_optional_dependency("odf")
+        super().__init__(
+            filepath_or_buffer,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @property
+    def _workbook_class(self) -> type[OpenDocument]:
+        from odf.opendocument import OpenDocument
+
+        return OpenDocument
+
+    def load_workbook(
+        self, filepath_or_buffer: FilePath | ReadBuffer[bytes], engine_kwargs
+    ) -> OpenDocument:
+        from odf.opendocument import load
+
+        return load(filepath_or_buffer, **engine_kwargs)
+
+    @property
+    def empty_value(self) -> str:
+        """Property for compat with other readers."""
+        return ""
+
+    @property
+    def sheet_names(self) -> list[str]:
+        """Return a list of sheet names present in the document"""
+        from odf.table import Table
+
+        tables = self.book.getElementsByType(Table)
+        return [t.getAttribute("name") for t in tables]
+
+    def get_sheet_by_index(self, index: int):
+        from odf.table import Table
+
+        self.raise_if_bad_sheet_by_index(index)
+        tables = self.book.getElementsByType(Table)
+        return tables[index]
+
+    def get_sheet_by_name(self, name: str):
+        from odf.table import Table
+
+        self.raise_if_bad_sheet_by_name(name)
+        tables = self.book.getElementsByType(Table)
+
+        for table in tables:
+            if table.getAttribute("name") == name:
+                return table
+
+        self.close()
+        raise ValueError(f"sheet {name} not found")
+
+    def get_sheet_data(
+        self, sheet, file_rows_needed: int | None = None
+    ) -> list[list[Scalar | NaTType]]:
+        """
+        Parse an ODF Table into a list of lists
+        """
+        from odf.table import (
+            CoveredTableCell,
+            TableCell,
+            TableRow,
+        )
+
+        covered_cell_name = CoveredTableCell().qname
+        table_cell_name = TableCell().qname
+        cell_names = {covered_cell_name, table_cell_name}
+
+        sheet_rows = sheet.getElementsByType(TableRow)
+        empty_rows = 0
+        max_row_len = 0
+
+        table: list[list[Scalar | NaTType]] = []
+
+        for sheet_row in sheet_rows:
+            sheet_cells = [
+                x
+                for x in sheet_row.childNodes
+                if hasattr(x, "qname") and x.qname in cell_names
+            ]
+            empty_cells = 0
+            table_row: list[Scalar | NaTType] = []
+
+            for sheet_cell in sheet_cells:
+                if sheet_cell.qname == table_cell_name:
+                    value = self._get_cell_value(sheet_cell)
+                else:
+                    value = self.empty_value
+
+                column_repeat = self._get_column_repeat(sheet_cell)
+
+                # Queue up empty values, writing only if content succeeds them
+                if value == self.empty_value:
+                    empty_cells += column_repeat
+                else:
+                    table_row.extend([self.empty_value] * empty_cells)
+                    empty_cells = 0
+                    table_row.extend([value] * column_repeat)
+
+            if max_row_len < len(table_row):
+                max_row_len = len(table_row)
+
+            row_repeat = self._get_row_repeat(sheet_row)
+            if len(table_row) == 0:
+                empty_rows += row_repeat
+            else:
+                # add blank rows to our table
+                table.extend([[self.empty_value]] * empty_rows)
+                empty_rows = 0
+                table.extend(table_row for _ in range(row_repeat))
+            if file_rows_needed is not None and len(table) >= file_rows_needed:
+                break
+
+        # Make our table square
+        for row in table:
+            if len(row) < max_row_len:
+                row.extend([self.empty_value] * (max_row_len - len(row)))
+
+        return table
+
+    def _get_row_repeat(self, row) -> int:
+        """
+        Return number of times this row was repeated
+        Repeating an empty row appeared to be a common way
+        of representing sparse rows in the table.
+        """
+        from odf.namespaces import TABLENS
+
+        return int(row.attributes.get((TABLENS, "number-rows-repeated"), 1))
+
+    def _get_column_repeat(self, cell) -> int:
+        from odf.namespaces import TABLENS
+
+        return int(cell.attributes.get((TABLENS, "number-columns-repeated"), 1))
+
+    def _get_cell_value(self, cell) -> Scalar | NaTType:
+        from odf.namespaces import OFFICENS
+
+        if str(cell) == "#N/A":
+            return np.nan
+
+        cell_type = cell.attributes.get((OFFICENS, "value-type"))
+        if cell_type == "boolean":
+            if str(cell) == "TRUE":
+                return True
+            return False
+        if cell_type is None:
+            return self.empty_value
+        elif cell_type == "float":
+            # GH5394
+            cell_value = float(cell.attributes.get((OFFICENS, "value")))
+            val = int(cell_value)
+            if val == cell_value:
+                return val
+            return cell_value
+        elif cell_type == "percentage":
+            cell_value = cell.attributes.get((OFFICENS, "value"))
+            return float(cell_value)
+        elif cell_type == "string":
+            return self._get_cell_string_value(cell)
+        elif cell_type == "currency":
+            cell_value = cell.attributes.get((OFFICENS, "value"))
+            return float(cell_value)
+        elif cell_type == "date":
+            cell_value = cell.attributes.get((OFFICENS, "date-value"))
+            return pd.Timestamp(cell_value)
+        elif cell_type == "time":
+            stamp = pd.Timestamp(str(cell))
+            # cast needed here because Scalar doesn't include datetime.time
+            return cast(Scalar, stamp.time())
+        else:
+            self.close()
+            raise ValueError(f"Unrecognized type {cell_type}")
+
+    def _get_cell_string_value(self, cell) -> str:
+        """
+        Find and decode OpenDocument text:s tags that represent
+        a run length encoded sequence of space characters.
+        """
+        from odf.element import Element
+        from odf.namespaces import TEXTNS
+        from odf.office import Annotation
+        from odf.text import S
+
+        office_annotation = Annotation().qname
+        text_s = S().qname
+
+        value = []
+
+        for fragment in cell.childNodes:
+            if isinstance(fragment, Element):
+                if fragment.qname == text_s:
+                    spaces = int(fragment.attributes.get((TEXTNS, "c"), 1))
+                    value.append(" " * spaces)
+                elif fragment.qname == office_annotation:
+                    continue
+                else:
+                    # recursive impl needed in case of nested fragments
+                    # with multiple spaces
+                    # https://github.com/pandas-dev/pandas/pull/36175#discussion_r484639704
+                    value.append(self._get_cell_string_value(fragment))
+            else:
+                value.append(str(fragment).strip("\n"))
+        return "".join(value)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_odswriter.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_odswriter.py
new file mode 100644
index 0000000000000000000000000000000000000000..bc7dca2d95b6b434279f8290fdf929e737f75459
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_odswriter.py
@@ -0,0 +1,357 @@
+from __future__ import annotations
+
+from collections import defaultdict
+import datetime
+import json
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    DefaultDict,
+    cast,
+    overload,
+)
+
+from pandas.io.excel._base import ExcelWriter
+from pandas.io.excel._util import (
+    combine_kwargs,
+    validate_freeze_panes,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ExcelWriterIfSheetExists,
+        FilePath,
+        StorageOptions,
+        WriteExcelBuffer,
+    )
+
+    from pandas.io.formats.excel import ExcelCell
+
+
+class ODSWriter(ExcelWriter):
+    _engine = "odf"
+    _supported_extensions = (".ods",)
+
+    def __init__(
+        self,
+        path: FilePath | WriteExcelBuffer | ExcelWriter,
+        engine: str | None = None,
+        date_format: str | None = None,
+        datetime_format=None,
+        mode: str = "w",
+        storage_options: StorageOptions | None = None,
+        if_sheet_exists: ExcelWriterIfSheetExists | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> None:
+        from odf.opendocument import OpenDocumentSpreadsheet
+
+        if mode == "a":
+            raise ValueError("Append mode is not supported with odf!")
+
+        engine_kwargs = combine_kwargs(engine_kwargs, kwargs)
+        self._book = OpenDocumentSpreadsheet(**engine_kwargs)
+
+        super().__init__(
+            path,
+            mode=mode,
+            storage_options=storage_options,
+            if_sheet_exists=if_sheet_exists,
+            engine_kwargs=engine_kwargs,
+        )
+
+        self._style_dict: dict[str, str] = {}
+
+    @property
+    def book(self):
+        """
+        Book instance of class odf.opendocument.OpenDocumentSpreadsheet.
+
+        This attribute can be used to access engine-specific features.
+        """
+        return self._book
+
+    @property
+    def sheets(self) -> dict[str, Any]:
+        """Mapping of sheet names to sheet objects."""
+        from odf.table import Table
+
+        result = {
+            sheet.getAttribute("name"): sheet
+            for sheet in self.book.getElementsByType(Table)
+        }
+        return result
+
+    def _save(self) -> None:
+        """
+        Save workbook to disk.
+        """
+        for sheet in self.sheets.values():
+            self.book.spreadsheet.addElement(sheet)
+        self.book.save(self._handles.handle)
+
+    def _write_cells(
+        self,
+        cells: list[ExcelCell],
+        sheet_name: str | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        freeze_panes: tuple[int, int] | None = None,
+    ) -> None:
+        """
+        Write the frame cells using odf
+        """
+        from odf.table import (
+            Table,
+            TableCell,
+            TableRow,
+        )
+        from odf.text import P
+
+        sheet_name = self._get_sheet_name(sheet_name)
+        assert sheet_name is not None
+
+        if sheet_name in self.sheets:
+            wks = self.sheets[sheet_name]
+        else:
+            wks = Table(name=sheet_name)
+            self.book.spreadsheet.addElement(wks)
+
+        if validate_freeze_panes(freeze_panes):
+            freeze_panes = cast(tuple[int, int], freeze_panes)
+            self._create_freeze_panes(sheet_name, freeze_panes)
+
+        for _ in range(startrow):
+            wks.addElement(TableRow())
+
+        rows: DefaultDict = defaultdict(TableRow)
+        col_count: DefaultDict = defaultdict(int)
+
+        for cell in sorted(cells, key=lambda cell: (cell.row, cell.col)):
+            # only add empty cells if the row is still empty
+            if not col_count[cell.row]:
+                for _ in range(startcol):
+                    rows[cell.row].addElement(TableCell())
+
+            # fill with empty cells if needed
+            for _ in range(cell.col - col_count[cell.row]):
+                rows[cell.row].addElement(TableCell())
+                col_count[cell.row] += 1
+
+            pvalue, tc = self._make_table_cell(cell)
+            rows[cell.row].addElement(tc)
+            col_count[cell.row] += 1
+            p = P(text=pvalue)
+            tc.addElement(p)
+
+        # add all rows to the sheet
+        if len(rows) > 0:
+            for row_nr in range(max(rows.keys()) + 1):
+                wks.addElement(rows[row_nr])
+
+    def _make_table_cell_attributes(self, cell) -> dict[str, int | str]:
+        """Convert cell attributes to OpenDocument attributes
+
+        Parameters
+        ----------
+        cell : ExcelCell
+            Spreadsheet cell data
+
+        Returns
+        -------
+        attributes : Dict[str, Union[int, str]]
+            Dictionary with attributes and attribute values
+        """
+        attributes: dict[str, int | str] = {}
+        style_name = self._process_style(cell.style)
+        if style_name is not None:
+            attributes["stylename"] = style_name
+        if cell.mergestart is not None and cell.mergeend is not None:
+            attributes["numberrowsspanned"] = max(1, cell.mergestart)
+            attributes["numbercolumnsspanned"] = cell.mergeend
+        return attributes
+
+    def _make_table_cell(self, cell) -> tuple[object, Any]:
+        """Convert cell data to an OpenDocument spreadsheet cell
+
+        Parameters
+        ----------
+        cell : ExcelCell
+            Spreadsheet cell data
+
+        Returns
+        -------
+        pvalue, cell : Tuple[str, TableCell]
+            Display value, Cell value
+        """
+        from odf.table import TableCell
+
+        attributes = self._make_table_cell_attributes(cell)
+        val, fmt = self._value_with_fmt(cell.val)
+        pvalue = value = val
+        if isinstance(val, bool):
+            value = str(val).lower()
+            pvalue = str(val).upper()
+            return (
+                pvalue,
+                TableCell(
+                    valuetype="boolean",
+                    booleanvalue=value,
+                    attributes=attributes,
+                ),
+            )
+        elif isinstance(val, datetime.datetime):
+            # Fast formatting
+            value = val.isoformat()
+            # Slow but locale-dependent
+            pvalue = val.strftime("%c")
+            return (
+                pvalue,
+                TableCell(valuetype="date", datevalue=value, attributes=attributes),
+            )
+        elif isinstance(val, datetime.date):
+            # Fast formatting
+            value = f"{val.year}-{val.month:02d}-{val.day:02d}"
+            # Slow but locale-dependent
+            pvalue = val.strftime("%x")
+            return (
+                pvalue,
+                TableCell(valuetype="date", datevalue=value, attributes=attributes),
+            )
+        elif isinstance(val, str):
+            return (
+                pvalue,
+                TableCell(
+                    valuetype="string",
+                    stringvalue=value,
+                    attributes=attributes,
+                ),
+            )
+        else:
+            return (
+                pvalue,
+                TableCell(
+                    valuetype="float",
+                    value=value,
+                    attributes=attributes,
+                ),
+            )
+
+    @overload
+    def _process_style(self, style: dict[str, Any]) -> str:
+        ...
+
+    @overload
+    def _process_style(self, style: None) -> None:
+        ...
+
+    def _process_style(self, style: dict[str, Any] | None) -> str | None:
+        """Convert a style dictionary to a OpenDocument style sheet
+
+        Parameters
+        ----------
+        style : Dict
+            Style dictionary
+
+        Returns
+        -------
+        style_key : str
+            Unique style key for later reference in sheet
+        """
+        from odf.style import (
+            ParagraphProperties,
+            Style,
+            TableCellProperties,
+            TextProperties,
+        )
+
+        if style is None:
+            return None
+        style_key = json.dumps(style)
+        if style_key in self._style_dict:
+            return self._style_dict[style_key]
+        name = f"pd{len(self._style_dict)+1}"
+        self._style_dict[style_key] = name
+        odf_style = Style(name=name, family="table-cell")
+        if "font" in style:
+            font = style["font"]
+            if font.get("bold", False):
+                odf_style.addElement(TextProperties(fontweight="bold"))
+        if "borders" in style:
+            borders = style["borders"]
+            for side, thickness in borders.items():
+                thickness_translation = {"thin": "0.75pt solid #000000"}
+                odf_style.addElement(
+                    TableCellProperties(
+                        attributes={f"border{side}": thickness_translation[thickness]}
+                    )
+                )
+        if "alignment" in style:
+            alignment = style["alignment"]
+            horizontal = alignment.get("horizontal")
+            if horizontal:
+                odf_style.addElement(ParagraphProperties(textalign=horizontal))
+            vertical = alignment.get("vertical")
+            if vertical:
+                odf_style.addElement(TableCellProperties(verticalalign=vertical))
+        self.book.styles.addElement(odf_style)
+        return name
+
+    def _create_freeze_panes(
+        self, sheet_name: str, freeze_panes: tuple[int, int]
+    ) -> None:
+        """
+        Create freeze panes in the sheet.
+
+        Parameters
+        ----------
+        sheet_name : str
+            Name of the spreadsheet
+        freeze_panes : tuple of (int, int)
+            Freeze pane location x and y
+        """
+        from odf.config import (
+            ConfigItem,
+            ConfigItemMapEntry,
+            ConfigItemMapIndexed,
+            ConfigItemMapNamed,
+            ConfigItemSet,
+        )
+
+        config_item_set = ConfigItemSet(name="ooo:view-settings")
+        self.book.settings.addElement(config_item_set)
+
+        config_item_map_indexed = ConfigItemMapIndexed(name="Views")
+        config_item_set.addElement(config_item_map_indexed)
+
+        config_item_map_entry = ConfigItemMapEntry()
+        config_item_map_indexed.addElement(config_item_map_entry)
+
+        config_item_map_named = ConfigItemMapNamed(name="Tables")
+        config_item_map_entry.addElement(config_item_map_named)
+
+        config_item_map_entry = ConfigItemMapEntry(name=sheet_name)
+        config_item_map_named.addElement(config_item_map_entry)
+
+        config_item_map_entry.addElement(
+            ConfigItem(name="HorizontalSplitMode", type="short", text="2")
+        )
+        config_item_map_entry.addElement(
+            ConfigItem(name="VerticalSplitMode", type="short", text="2")
+        )
+        config_item_map_entry.addElement(
+            ConfigItem(
+                name="HorizontalSplitPosition", type="int", text=str(freeze_panes[0])
+            )
+        )
+        config_item_map_entry.addElement(
+            ConfigItem(
+                name="VerticalSplitPosition", type="int", text=str(freeze_panes[1])
+            )
+        )
+        config_item_map_entry.addElement(
+            ConfigItem(name="PositionRight", type="int", text=str(freeze_panes[0]))
+        )
+        config_item_map_entry.addElement(
+            ConfigItem(name="PositionBottom", type="int", text=str(freeze_panes[1]))
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_openpyxl.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_openpyxl.py
new file mode 100644
index 0000000000000000000000000000000000000000..c546443868a62aed062bf3fd41d80933e4fbc59e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_openpyxl.py
@@ -0,0 +1,639 @@
+from __future__ import annotations
+
+import mmap
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.excel._base import (
+    BaseExcelReader,
+    ExcelWriter,
+)
+from pandas.io.excel._util import (
+    combine_kwargs,
+    validate_freeze_panes,
+)
+
+if TYPE_CHECKING:
+    from openpyxl import Workbook
+    from openpyxl.descriptors.serialisable import Serialisable
+
+    from pandas._typing import (
+        ExcelWriterIfSheetExists,
+        FilePath,
+        ReadBuffer,
+        Scalar,
+        StorageOptions,
+        WriteExcelBuffer,
+    )
+
+
+class OpenpyxlWriter(ExcelWriter):
+    _engine = "openpyxl"
+    _supported_extensions = (".xlsx", ".xlsm")
+
+    def __init__(
+        self,
+        path: FilePath | WriteExcelBuffer | ExcelWriter,
+        engine: str | None = None,
+        date_format: str | None = None,
+        datetime_format: str | None = None,
+        mode: str = "w",
+        storage_options: StorageOptions | None = None,
+        if_sheet_exists: ExcelWriterIfSheetExists | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> None:
+        # Use the openpyxl module as the Excel writer.
+        from openpyxl.workbook import Workbook
+
+        engine_kwargs = combine_kwargs(engine_kwargs, kwargs)
+
+        super().__init__(
+            path,
+            mode=mode,
+            storage_options=storage_options,
+            if_sheet_exists=if_sheet_exists,
+            engine_kwargs=engine_kwargs,
+        )
+
+        # ExcelWriter replaced "a" by "r+" to allow us to first read the excel file from
+        # the file and later write to it
+        if "r+" in self._mode:  # Load from existing workbook
+            from openpyxl import load_workbook
+
+            try:
+                self._book = load_workbook(self._handles.handle, **engine_kwargs)
+            except TypeError:
+                self._handles.handle.close()
+                raise
+            self._handles.handle.seek(0)
+        else:
+            # Create workbook object with default optimized_write=True.
+            try:
+                self._book = Workbook(**engine_kwargs)
+            except TypeError:
+                self._handles.handle.close()
+                raise
+
+            if self.book.worksheets:
+                self.book.remove(self.book.worksheets[0])
+
+    @property
+    def book(self) -> Workbook:
+        """
+        Book instance of class openpyxl.workbook.Workbook.
+
+        This attribute can be used to access engine-specific features.
+        """
+        return self._book
+
+    @property
+    def sheets(self) -> dict[str, Any]:
+        """Mapping of sheet names to sheet objects."""
+        result = {name: self.book[name] for name in self.book.sheetnames}
+        return result
+
+    def _save(self) -> None:
+        """
+        Save workbook to disk.
+        """
+        self.book.save(self._handles.handle)
+        if "r+" in self._mode and not isinstance(self._handles.handle, mmap.mmap):
+            # truncate file to the written content
+            self._handles.handle.truncate()
+
+    @classmethod
+    def _convert_to_style_kwargs(cls, style_dict: dict) -> dict[str, Serialisable]:
+        """
+        Convert a style_dict to a set of kwargs suitable for initializing
+        or updating-on-copy an openpyxl v2 style object.
+
+        Parameters
+        ----------
+        style_dict : dict
+            A dict with zero or more of the following keys (or their synonyms).
+                'font'
+                'fill'
+                'border' ('borders')
+                'alignment'
+                'number_format'
+                'protection'
+
+        Returns
+        -------
+        style_kwargs : dict
+            A dict with the same, normalized keys as ``style_dict`` but each
+            value has been replaced with a native openpyxl style object of the
+            appropriate class.
+        """
+        _style_key_map = {"borders": "border"}
+
+        style_kwargs: dict[str, Serialisable] = {}
+        for k, v in style_dict.items():
+            k = _style_key_map.get(k, k)
+            _conv_to_x = getattr(cls, f"_convert_to_{k}", lambda x: None)
+            new_v = _conv_to_x(v)
+            if new_v:
+                style_kwargs[k] = new_v
+
+        return style_kwargs
+
+    @classmethod
+    def _convert_to_color(cls, color_spec):
+        """
+        Convert ``color_spec`` to an openpyxl v2 Color object.
+
+        Parameters
+        ----------
+        color_spec : str, dict
+            A 32-bit ARGB hex string, or a dict with zero or more of the
+            following keys.
+                'rgb'
+                'indexed'
+                'auto'
+                'theme'
+                'tint'
+                'index'
+                'type'
+
+        Returns
+        -------
+        color : openpyxl.styles.Color
+        """
+        from openpyxl.styles import Color
+
+        if isinstance(color_spec, str):
+            return Color(color_spec)
+        else:
+            return Color(**color_spec)
+
+    @classmethod
+    def _convert_to_font(cls, font_dict):
+        """
+        Convert ``font_dict`` to an openpyxl v2 Font object.
+
+        Parameters
+        ----------
+        font_dict : dict
+            A dict with zero or more of the following keys (or their synonyms).
+                'name'
+                'size' ('sz')
+                'bold' ('b')
+                'italic' ('i')
+                'underline' ('u')
+                'strikethrough' ('strike')
+                'color'
+                'vertAlign' ('vertalign')
+                'charset'
+                'scheme'
+                'family'
+                'outline'
+                'shadow'
+                'condense'
+
+        Returns
+        -------
+        font : openpyxl.styles.Font
+        """
+        from openpyxl.styles import Font
+
+        _font_key_map = {
+            "sz": "size",
+            "b": "bold",
+            "i": "italic",
+            "u": "underline",
+            "strike": "strikethrough",
+            "vertalign": "vertAlign",
+        }
+
+        font_kwargs = {}
+        for k, v in font_dict.items():
+            k = _font_key_map.get(k, k)
+            if k == "color":
+                v = cls._convert_to_color(v)
+            font_kwargs[k] = v
+
+        return Font(**font_kwargs)
+
+    @classmethod
+    def _convert_to_stop(cls, stop_seq):
+        """
+        Convert ``stop_seq`` to a list of openpyxl v2 Color objects,
+        suitable for initializing the ``GradientFill`` ``stop`` parameter.
+
+        Parameters
+        ----------
+        stop_seq : iterable
+            An iterable that yields objects suitable for consumption by
+            ``_convert_to_color``.
+
+        Returns
+        -------
+        stop : list of openpyxl.styles.Color
+        """
+        return map(cls._convert_to_color, stop_seq)
+
+    @classmethod
+    def _convert_to_fill(cls, fill_dict: dict[str, Any]):
+        """
+        Convert ``fill_dict`` to an openpyxl v2 Fill object.
+
+        Parameters
+        ----------
+        fill_dict : dict
+            A dict with one or more of the following keys (or their synonyms),
+                'fill_type' ('patternType', 'patterntype')
+                'start_color' ('fgColor', 'fgcolor')
+                'end_color' ('bgColor', 'bgcolor')
+            or one or more of the following keys (or their synonyms).
+                'type' ('fill_type')
+                'degree'
+                'left'
+                'right'
+                'top'
+                'bottom'
+                'stop'
+
+        Returns
+        -------
+        fill : openpyxl.styles.Fill
+        """
+        from openpyxl.styles import (
+            GradientFill,
+            PatternFill,
+        )
+
+        _pattern_fill_key_map = {
+            "patternType": "fill_type",
+            "patterntype": "fill_type",
+            "fgColor": "start_color",
+            "fgcolor": "start_color",
+            "bgColor": "end_color",
+            "bgcolor": "end_color",
+        }
+
+        _gradient_fill_key_map = {"fill_type": "type"}
+
+        pfill_kwargs = {}
+        gfill_kwargs = {}
+        for k, v in fill_dict.items():
+            pk = _pattern_fill_key_map.get(k)
+            gk = _gradient_fill_key_map.get(k)
+            if pk in ["start_color", "end_color"]:
+                v = cls._convert_to_color(v)
+            if gk == "stop":
+                v = cls._convert_to_stop(v)
+            if pk:
+                pfill_kwargs[pk] = v
+            elif gk:
+                gfill_kwargs[gk] = v
+            else:
+                pfill_kwargs[k] = v
+                gfill_kwargs[k] = v
+
+        try:
+            return PatternFill(**pfill_kwargs)
+        except TypeError:
+            return GradientFill(**gfill_kwargs)
+
+    @classmethod
+    def _convert_to_side(cls, side_spec):
+        """
+        Convert ``side_spec`` to an openpyxl v2 Side object.
+
+        Parameters
+        ----------
+        side_spec : str, dict
+            A string specifying the border style, or a dict with zero or more
+            of the following keys (or their synonyms).
+                'style' ('border_style')
+                'color'
+
+        Returns
+        -------
+        side : openpyxl.styles.Side
+        """
+        from openpyxl.styles import Side
+
+        _side_key_map = {"border_style": "style"}
+
+        if isinstance(side_spec, str):
+            return Side(style=side_spec)
+
+        side_kwargs = {}
+        for k, v in side_spec.items():
+            k = _side_key_map.get(k, k)
+            if k == "color":
+                v = cls._convert_to_color(v)
+            side_kwargs[k] = v
+
+        return Side(**side_kwargs)
+
+    @classmethod
+    def _convert_to_border(cls, border_dict):
+        """
+        Convert ``border_dict`` to an openpyxl v2 Border object.
+
+        Parameters
+        ----------
+        border_dict : dict
+            A dict with zero or more of the following keys (or their synonyms).
+                'left'
+                'right'
+                'top'
+                'bottom'
+                'diagonal'
+                'diagonal_direction'
+                'vertical'
+                'horizontal'
+                'diagonalUp' ('diagonalup')
+                'diagonalDown' ('diagonaldown')
+                'outline'
+
+        Returns
+        -------
+        border : openpyxl.styles.Border
+        """
+        from openpyxl.styles import Border
+
+        _border_key_map = {"diagonalup": "diagonalUp", "diagonaldown": "diagonalDown"}
+
+        border_kwargs = {}
+        for k, v in border_dict.items():
+            k = _border_key_map.get(k, k)
+            if k == "color":
+                v = cls._convert_to_color(v)
+            if k in ["left", "right", "top", "bottom", "diagonal"]:
+                v = cls._convert_to_side(v)
+            border_kwargs[k] = v
+
+        return Border(**border_kwargs)
+
+    @classmethod
+    def _convert_to_alignment(cls, alignment_dict):
+        """
+        Convert ``alignment_dict`` to an openpyxl v2 Alignment object.
+
+        Parameters
+        ----------
+        alignment_dict : dict
+            A dict with zero or more of the following keys (or their synonyms).
+                'horizontal'
+                'vertical'
+                'text_rotation'
+                'wrap_text'
+                'shrink_to_fit'
+                'indent'
+        Returns
+        -------
+        alignment : openpyxl.styles.Alignment
+        """
+        from openpyxl.styles import Alignment
+
+        return Alignment(**alignment_dict)
+
+    @classmethod
+    def _convert_to_number_format(cls, number_format_dict):
+        """
+        Convert ``number_format_dict`` to an openpyxl v2.1.0 number format
+        initializer.
+
+        Parameters
+        ----------
+        number_format_dict : dict
+            A dict with zero or more of the following keys.
+                'format_code' : str
+
+        Returns
+        -------
+        number_format : str
+        """
+        return number_format_dict["format_code"]
+
+    @classmethod
+    def _convert_to_protection(cls, protection_dict):
+        """
+        Convert ``protection_dict`` to an openpyxl v2 Protection object.
+
+        Parameters
+        ----------
+        protection_dict : dict
+            A dict with zero or more of the following keys.
+                'locked'
+                'hidden'
+
+        Returns
+        -------
+        """
+        from openpyxl.styles import Protection
+
+        return Protection(**protection_dict)
+
+    def _write_cells(
+        self,
+        cells,
+        sheet_name: str | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        freeze_panes: tuple[int, int] | None = None,
+    ) -> None:
+        # Write the frame cells using openpyxl.
+        sheet_name = self._get_sheet_name(sheet_name)
+
+        _style_cache: dict[str, dict[str, Serialisable]] = {}
+
+        if sheet_name in self.sheets and self._if_sheet_exists != "new":
+            if "r+" in self._mode:
+                if self._if_sheet_exists == "replace":
+                    old_wks = self.sheets[sheet_name]
+                    target_index = self.book.index(old_wks)
+                    del self.book[sheet_name]
+                    wks = self.book.create_sheet(sheet_name, target_index)
+                elif self._if_sheet_exists == "error":
+                    raise ValueError(
+                        f"Sheet '{sheet_name}' already exists and "
+                        f"if_sheet_exists is set to 'error'."
+                    )
+                elif self._if_sheet_exists == "overlay":
+                    wks = self.sheets[sheet_name]
+                else:
+                    raise ValueError(
+                        f"'{self._if_sheet_exists}' is not valid for if_sheet_exists. "
+                        "Valid options are 'error', 'new', 'replace' and 'overlay'."
+                    )
+            else:
+                wks = self.sheets[sheet_name]
+        else:
+            wks = self.book.create_sheet()
+            wks.title = sheet_name
+
+        if validate_freeze_panes(freeze_panes):
+            freeze_panes = cast(tuple[int, int], freeze_panes)
+            wks.freeze_panes = wks.cell(
+                row=freeze_panes[0] + 1, column=freeze_panes[1] + 1
+            )
+
+        for cell in cells:
+            xcell = wks.cell(
+                row=startrow + cell.row + 1, column=startcol + cell.col + 1
+            )
+            xcell.value, fmt = self._value_with_fmt(cell.val)
+            if fmt:
+                xcell.number_format = fmt
+
+            style_kwargs: dict[str, Serialisable] | None = {}
+            if cell.style:
+                key = str(cell.style)
+                style_kwargs = _style_cache.get(key)
+                if style_kwargs is None:
+                    style_kwargs = self._convert_to_style_kwargs(cell.style)
+                    _style_cache[key] = style_kwargs
+
+            if style_kwargs:
+                for k, v in style_kwargs.items():
+                    setattr(xcell, k, v)
+
+            if cell.mergestart is not None and cell.mergeend is not None:
+                wks.merge_cells(
+                    start_row=startrow + cell.row + 1,
+                    start_column=startcol + cell.col + 1,
+                    end_column=startcol + cell.mergeend + 1,
+                    end_row=startrow + cell.mergestart + 1,
+                )
+
+                # When cells are merged only the top-left cell is preserved
+                # The behaviour of the other cells in a merged range is
+                # undefined
+                if style_kwargs:
+                    first_row = startrow + cell.row + 1
+                    last_row = startrow + cell.mergestart + 1
+                    first_col = startcol + cell.col + 1
+                    last_col = startcol + cell.mergeend + 1
+
+                    for row in range(first_row, last_row + 1):
+                        for col in range(first_col, last_col + 1):
+                            if row == first_row and col == first_col:
+                                # Ignore first cell. It is already handled.
+                                continue
+                            xcell = wks.cell(column=col, row=row)
+                            for k, v in style_kwargs.items():
+                                setattr(xcell, k, v)
+
+
+class OpenpyxlReader(BaseExcelReader["Workbook"]):
+    @doc(storage_options=_shared_docs["storage_options"])
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Reader using openpyxl engine.
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path object or Workbook
+            Object to be parsed.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        import_optional_dependency("openpyxl")
+        super().__init__(
+            filepath_or_buffer,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @property
+    def _workbook_class(self) -> type[Workbook]:
+        from openpyxl import Workbook
+
+        return Workbook
+
+    def load_workbook(
+        self, filepath_or_buffer: FilePath | ReadBuffer[bytes], engine_kwargs
+    ) -> Workbook:
+        from openpyxl import load_workbook
+
+        default_kwargs = {"read_only": True, "data_only": True, "keep_links": False}
+
+        return load_workbook(
+            filepath_or_buffer,
+            **(default_kwargs | engine_kwargs),
+        )
+
+    @property
+    def sheet_names(self) -> list[str]:
+        return [sheet.title for sheet in self.book.worksheets]
+
+    def get_sheet_by_name(self, name: str):
+        self.raise_if_bad_sheet_by_name(name)
+        return self.book[name]
+
+    def get_sheet_by_index(self, index: int):
+        self.raise_if_bad_sheet_by_index(index)
+        return self.book.worksheets[index]
+
+    def _convert_cell(self, cell) -> Scalar:
+        from openpyxl.cell.cell import (
+            TYPE_ERROR,
+            TYPE_NUMERIC,
+        )
+
+        if cell.value is None:
+            return ""  # compat with xlrd
+        elif cell.data_type == TYPE_ERROR:
+            return np.nan
+        elif cell.data_type == TYPE_NUMERIC:
+            val = int(cell.value)
+            if val == cell.value:
+                return val
+            return float(cell.value)
+
+        return cell.value
+
+    def get_sheet_data(
+        self, sheet, file_rows_needed: int | None = None
+    ) -> list[list[Scalar]]:
+        if self.book.read_only:
+            sheet.reset_dimensions()
+
+        data: list[list[Scalar]] = []
+        last_row_with_data = -1
+        for row_number, row in enumerate(sheet.rows):
+            converted_row = [self._convert_cell(cell) for cell in row]
+            while converted_row and converted_row[-1] == "":
+                # trim trailing empty elements
+                converted_row.pop()
+            if converted_row:
+                last_row_with_data = row_number
+            data.append(converted_row)
+            if file_rows_needed is not None and len(data) >= file_rows_needed:
+                break
+
+        # Trim trailing empty rows
+        data = data[: last_row_with_data + 1]
+
+        if len(data) > 0:
+            # extend rows to max width
+            max_width = max(len(data_row) for data_row in data)
+            if min(len(data_row) for data_row in data) < max_width:
+                empty_cell: list[Scalar] = [""]
+                data = [
+                    data_row + (max_width - len(data_row)) * empty_cell
+                    for data_row in data
+                ]
+
+        return data
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_pyxlsb.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_pyxlsb.py
new file mode 100644
index 0000000000000000000000000000000000000000..a6e42616c20438fa4cab16e94b5d16a01c9c61df
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_pyxlsb.py
@@ -0,0 +1,127 @@
+# pyright: reportMissingImports=false
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.excel._base import BaseExcelReader
+
+if TYPE_CHECKING:
+    from pyxlsb import Workbook
+
+    from pandas._typing import (
+        FilePath,
+        ReadBuffer,
+        Scalar,
+        StorageOptions,
+    )
+
+
+class PyxlsbReader(BaseExcelReader["Workbook"]):
+    @doc(storage_options=_shared_docs["storage_options"])
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Reader using pyxlsb engine.
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path object, or Workbook
+            Object to be parsed.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        import_optional_dependency("pyxlsb")
+        # This will call load_workbook on the filepath or buffer
+        # And set the result to the book-attribute
+        super().__init__(
+            filepath_or_buffer,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @property
+    def _workbook_class(self) -> type[Workbook]:
+        from pyxlsb import Workbook
+
+        return Workbook
+
+    def load_workbook(
+        self, filepath_or_buffer: FilePath | ReadBuffer[bytes], engine_kwargs
+    ) -> Workbook:
+        from pyxlsb import open_workbook
+
+        # TODO: hack in buffer capability
+        # This might need some modifications to the Pyxlsb library
+        # Actual work for opening it is in xlsbpackage.py, line 20-ish
+
+        return open_workbook(filepath_or_buffer, **engine_kwargs)
+
+    @property
+    def sheet_names(self) -> list[str]:
+        return self.book.sheets
+
+    def get_sheet_by_name(self, name: str):
+        self.raise_if_bad_sheet_by_name(name)
+        return self.book.get_sheet(name)
+
+    def get_sheet_by_index(self, index: int):
+        self.raise_if_bad_sheet_by_index(index)
+        # pyxlsb sheets are indexed from 1 onwards
+        # There's a fix for this in the source, but the pypi package doesn't have it
+        return self.book.get_sheet(index + 1)
+
+    def _convert_cell(self, cell) -> Scalar:
+        # TODO: there is no way to distinguish between floats and datetimes in pyxlsb
+        # This means that there is no way to read datetime types from an xlsb file yet
+        if cell.v is None:
+            return ""  # Prevents non-named columns from not showing up as Unnamed: i
+        if isinstance(cell.v, float):
+            val = int(cell.v)
+            if val == cell.v:
+                return val
+            else:
+                return float(cell.v)
+
+        return cell.v
+
+    def get_sheet_data(
+        self,
+        sheet,
+        file_rows_needed: int | None = None,
+    ) -> list[list[Scalar]]:
+        data: list[list[Scalar]] = []
+        previous_row_number = -1
+        # When sparse=True the rows can have different lengths and empty rows are
+        # not returned. The cells are namedtuples of row, col, value (r, c, v).
+        for row in sheet.rows(sparse=True):
+            row_number = row[0].r
+            converted_row = [self._convert_cell(cell) for cell in row]
+            while converted_row and converted_row[-1] == "":
+                # trim trailing empty elements
+                converted_row.pop()
+            if converted_row:
+                data.extend([[]] * (row_number - previous_row_number - 1))
+                data.append(converted_row)
+                previous_row_number = row_number
+            if file_rows_needed is not None and len(data) >= file_rows_needed:
+                break
+        if data:
+            # extend rows to max_width
+            max_width = max(len(data_row) for data_row in data)
+            if min(len(data_row) for data_row in data) < max_width:
+                empty_cell: list[Scalar] = [""]
+                data = [
+                    data_row + (max_width - len(data_row)) * empty_cell
+                    for data_row in data
+                ]
+        return data
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_util.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_util.py
new file mode 100644
index 0000000000000000000000000000000000000000..f7a1fcb8052e391d0853be64866663f4e6de9d08
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_util.py
@@ -0,0 +1,334 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterable,
+    MutableMapping,
+    Sequence,
+)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    TypeVar,
+    overload,
+)
+
+from pandas.compat._optional import import_optional_dependency
+
+from pandas.core.dtypes.common import (
+    is_integer,
+    is_list_like,
+)
+
+if TYPE_CHECKING:
+    from pandas.io.excel._base import ExcelWriter
+
+    ExcelWriter_t = type[ExcelWriter]
+    usecols_func = TypeVar("usecols_func", bound=Callable[[Hashable], object])
+
+_writers: MutableMapping[str, ExcelWriter_t] = {}
+
+
+def register_writer(klass: ExcelWriter_t) -> None:
+    """
+    Add engine to the excel writer registry.io.excel.
+
+    You must use this method to integrate with ``to_excel``.
+
+    Parameters
+    ----------
+    klass : ExcelWriter
+    """
+    if not callable(klass):
+        raise ValueError("Can only register callables as engines")
+    engine_name = klass._engine
+    _writers[engine_name] = klass
+
+
+def get_default_engine(ext: str, mode: Literal["reader", "writer"] = "reader") -> str:
+    """
+    Return the default reader/writer for the given extension.
+
+    Parameters
+    ----------
+    ext : str
+        The excel file extension for which to get the default engine.
+    mode : str {'reader', 'writer'}
+        Whether to get the default engine for reading or writing.
+        Either 'reader' or 'writer'
+
+    Returns
+    -------
+    str
+        The default engine for the extension.
+    """
+    _default_readers = {
+        "xlsx": "openpyxl",
+        "xlsm": "openpyxl",
+        "xlsb": "pyxlsb",
+        "xls": "xlrd",
+        "ods": "odf",
+    }
+    _default_writers = {
+        "xlsx": "openpyxl",
+        "xlsm": "openpyxl",
+        "xlsb": "pyxlsb",
+        "ods": "odf",
+    }
+    assert mode in ["reader", "writer"]
+    if mode == "writer":
+        # Prefer xlsxwriter over openpyxl if installed
+        xlsxwriter = import_optional_dependency("xlsxwriter", errors="warn")
+        if xlsxwriter:
+            _default_writers["xlsx"] = "xlsxwriter"
+        return _default_writers[ext]
+    else:
+        return _default_readers[ext]
+
+
+def get_writer(engine_name: str) -> ExcelWriter_t:
+    try:
+        return _writers[engine_name]
+    except KeyError as err:
+        raise ValueError(f"No Excel writer '{engine_name}'") from err
+
+
+def _excel2num(x: str) -> int:
+    """
+    Convert Excel column name like 'AB' to 0-based column index.
+
+    Parameters
+    ----------
+    x : str
+        The Excel column name to convert to a 0-based column index.
+
+    Returns
+    -------
+    num : int
+        The column index corresponding to the name.
+
+    Raises
+    ------
+    ValueError
+        Part of the Excel column name was invalid.
+    """
+    index = 0
+
+    for c in x.upper().strip():
+        cp = ord(c)
+
+        if cp < ord("A") or cp > ord("Z"):
+            raise ValueError(f"Invalid column name: {x}")
+
+        index = index * 26 + cp - ord("A") + 1
+
+    return index - 1
+
+
+def _range2cols(areas: str) -> list[int]:
+    """
+    Convert comma separated list of column names and ranges to indices.
+
+    Parameters
+    ----------
+    areas : str
+        A string containing a sequence of column ranges (or areas).
+
+    Returns
+    -------
+    cols : list
+        A list of 0-based column indices.
+
+    Examples
+    --------
+    >>> _range2cols('A:E')
+    [0, 1, 2, 3, 4]
+    >>> _range2cols('A,C,Z:AB')
+    [0, 2, 25, 26, 27]
+    """
+    cols: list[int] = []
+
+    for rng in areas.split(","):
+        if ":" in rng:
+            rngs = rng.split(":")
+            cols.extend(range(_excel2num(rngs[0]), _excel2num(rngs[1]) + 1))
+        else:
+            cols.append(_excel2num(rng))
+
+    return cols
+
+
+@overload
+def maybe_convert_usecols(usecols: str | list[int]) -> list[int]:
+    ...
+
+
+@overload
+def maybe_convert_usecols(usecols: list[str]) -> list[str]:
+    ...
+
+
+@overload
+def maybe_convert_usecols(usecols: usecols_func) -> usecols_func:
+    ...
+
+
+@overload
+def maybe_convert_usecols(usecols: None) -> None:
+    ...
+
+
+def maybe_convert_usecols(
+    usecols: str | list[int] | list[str] | usecols_func | None,
+) -> None | list[int] | list[str] | usecols_func:
+    """
+    Convert `usecols` into a compatible format for parsing in `parsers.py`.
+
+    Parameters
+    ----------
+    usecols : object
+        The use-columns object to potentially convert.
+
+    Returns
+    -------
+    converted : object
+        The compatible format of `usecols`.
+    """
+    if usecols is None:
+        return usecols
+
+    if is_integer(usecols):
+        raise ValueError(
+            "Passing an integer for `usecols` is no longer supported.  "
+            "Please pass in a list of int from 0 to `usecols` inclusive instead."
+        )
+
+    if isinstance(usecols, str):
+        return _range2cols(usecols)
+
+    return usecols
+
+
+@overload
+def validate_freeze_panes(freeze_panes: tuple[int, int]) -> Literal[True]:
+    ...
+
+
+@overload
+def validate_freeze_panes(freeze_panes: None) -> Literal[False]:
+    ...
+
+
+def validate_freeze_panes(freeze_panes: tuple[int, int] | None) -> bool:
+    if freeze_panes is not None:
+        if len(freeze_panes) == 2 and all(
+            isinstance(item, int) for item in freeze_panes
+        ):
+            return True
+
+        raise ValueError(
+            "freeze_panes must be of form (row, column) "
+            "where row and column are integers"
+        )
+
+    # freeze_panes wasn't specified, return False so it won't be applied
+    # to output sheet
+    return False
+
+
+def fill_mi_header(
+    row: list[Hashable], control_row: list[bool]
+) -> tuple[list[Hashable], list[bool]]:
+    """
+    Forward fill blank entries in row but only inside the same parent index.
+
+    Used for creating headers in Multiindex.
+
+    Parameters
+    ----------
+    row : list
+        List of items in a single row.
+    control_row : list of bool
+        Helps to determine if particular column is in same parent index as the
+        previous value. Used to stop propagation of empty cells between
+        different indexes.
+
+    Returns
+    -------
+    Returns changed row and control_row
+    """
+    last = row[0]
+    for i in range(1, len(row)):
+        if not control_row[i]:
+            last = row[i]
+
+        if row[i] == "" or row[i] is None:
+            row[i] = last
+        else:
+            control_row[i] = False
+            last = row[i]
+
+    return row, control_row
+
+
+def pop_header_name(
+    row: list[Hashable], index_col: int | Sequence[int]
+) -> tuple[Hashable | None, list[Hashable]]:
+    """
+    Pop the header name for MultiIndex parsing.
+
+    Parameters
+    ----------
+    row : list
+        The data row to parse for the header name.
+    index_col : int, list
+        The index columns for our data. Assumed to be non-null.
+
+    Returns
+    -------
+    header_name : str
+        The extracted header name.
+    trimmed_row : list
+        The original data row with the header name removed.
+    """
+    # Pop out header name and fill w/blank.
+    if is_list_like(index_col):
+        assert isinstance(index_col, Iterable)
+        i = max(index_col)
+    else:
+        assert not isinstance(index_col, Iterable)
+        i = index_col
+
+    header_name = row[i]
+    header_name = None if header_name == "" else header_name
+
+    return header_name, row[:i] + [""] + row[i + 1 :]
+
+
+def combine_kwargs(engine_kwargs: dict[str, Any] | None, kwargs: dict) -> dict:
+    """
+    Used to combine two sources of kwargs for the backend engine.
+
+    Use of kwargs is deprecated, this function is solely for use in 1.3 and should
+    be removed in 1.4/2.0. Also _base.ExcelWriter.__new__ ensures either engine_kwargs
+    or kwargs must be None or empty respectively.
+
+    Parameters
+    ----------
+    engine_kwargs: dict
+        kwargs to be passed through to the engine.
+    kwargs: dict
+        kwargs to be psased through to the engine (deprecated)
+
+    Returns
+    -------
+    engine_kwargs combined with kwargs
+    """
+    if engine_kwargs is None:
+        result = {}
+    else:
+        result = engine_kwargs.copy()
+    result.update(kwargs)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlrd.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlrd.py
new file mode 100644
index 0000000000000000000000000000000000000000..a444970792e6e65faf3d8947b721fff59487d994
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlrd.py
@@ -0,0 +1,143 @@
+from __future__ import annotations
+
+from datetime import time
+import math
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.excel._base import BaseExcelReader
+
+if TYPE_CHECKING:
+    from xlrd import Book
+
+    from pandas._typing import (
+        Scalar,
+        StorageOptions,
+    )
+
+
+class XlrdReader(BaseExcelReader["Book"]):
+    @doc(storage_options=_shared_docs["storage_options"])
+    def __init__(
+        self,
+        filepath_or_buffer,
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        Reader using xlrd engine.
+
+        Parameters
+        ----------
+        filepath_or_buffer : str, path object or Workbook
+            Object to be parsed.
+        {storage_options}
+        engine_kwargs : dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        err_msg = "Install xlrd >= 2.0.1 for xls Excel support"
+        import_optional_dependency("xlrd", extra=err_msg)
+        super().__init__(
+            filepath_or_buffer,
+            storage_options=storage_options,
+            engine_kwargs=engine_kwargs,
+        )
+
+    @property
+    def _workbook_class(self) -> type[Book]:
+        from xlrd import Book
+
+        return Book
+
+    def load_workbook(self, filepath_or_buffer, engine_kwargs) -> Book:
+        from xlrd import open_workbook
+
+        if hasattr(filepath_or_buffer, "read"):
+            data = filepath_or_buffer.read()
+            return open_workbook(file_contents=data, **engine_kwargs)
+        else:
+            return open_workbook(filepath_or_buffer, **engine_kwargs)
+
+    @property
+    def sheet_names(self):
+        return self.book.sheet_names()
+
+    def get_sheet_by_name(self, name):
+        self.raise_if_bad_sheet_by_name(name)
+        return self.book.sheet_by_name(name)
+
+    def get_sheet_by_index(self, index):
+        self.raise_if_bad_sheet_by_index(index)
+        return self.book.sheet_by_index(index)
+
+    def get_sheet_data(
+        self, sheet, file_rows_needed: int | None = None
+    ) -> list[list[Scalar]]:
+        from xlrd import (
+            XL_CELL_BOOLEAN,
+            XL_CELL_DATE,
+            XL_CELL_ERROR,
+            XL_CELL_NUMBER,
+            xldate,
+        )
+
+        epoch1904 = self.book.datemode
+
+        def _parse_cell(cell_contents, cell_typ):
+            """
+            converts the contents of the cell into a pandas appropriate object
+            """
+            if cell_typ == XL_CELL_DATE:
+                # Use the newer xlrd datetime handling.
+                try:
+                    cell_contents = xldate.xldate_as_datetime(cell_contents, epoch1904)
+                except OverflowError:
+                    return cell_contents
+
+                # Excel doesn't distinguish between dates and time,
+                # so we treat dates on the epoch as times only.
+                # Also, Excel supports 1900 and 1904 epochs.
+                year = (cell_contents.timetuple())[0:3]
+                if (not epoch1904 and year == (1899, 12, 31)) or (
+                    epoch1904 and year == (1904, 1, 1)
+                ):
+                    cell_contents = time(
+                        cell_contents.hour,
+                        cell_contents.minute,
+                        cell_contents.second,
+                        cell_contents.microsecond,
+                    )
+
+            elif cell_typ == XL_CELL_ERROR:
+                cell_contents = np.nan
+            elif cell_typ == XL_CELL_BOOLEAN:
+                cell_contents = bool(cell_contents)
+            elif cell_typ == XL_CELL_NUMBER:
+                # GH5394 - Excel 'numbers' are always floats
+                # it's a minimal perf hit and less surprising
+                if math.isfinite(cell_contents):
+                    # GH54564 - don't attempt to convert NaN/Inf
+                    val = int(cell_contents)
+                    if val == cell_contents:
+                        cell_contents = val
+            return cell_contents
+
+        data = []
+
+        nrows = sheet.nrows
+        if file_rows_needed is not None:
+            nrows = min(nrows, file_rows_needed)
+        for i in range(nrows):
+            row = [
+                _parse_cell(value, typ)
+                for value, typ in zip(sheet.row_values(i), sheet.row_types(i))
+            ]
+            data.append(row)
+
+        return data
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlsxwriter.py b/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlsxwriter.py
new file mode 100644
index 0000000000000000000000000000000000000000..e7a9789ccd0f3317c83b1542b823586d3419c485
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/excel/_xlsxwriter.py
@@ -0,0 +1,284 @@
+from __future__ import annotations
+
+import json
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from pandas.io.excel._base import ExcelWriter
+from pandas.io.excel._util import (
+    combine_kwargs,
+    validate_freeze_panes,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ExcelWriterIfSheetExists,
+        FilePath,
+        StorageOptions,
+        WriteExcelBuffer,
+    )
+
+
+class _XlsxStyler:
+    # Map from openpyxl-oriented styles to flatter xlsxwriter representation
+    # Ordering necessary for both determinism and because some are keyed by
+    # prefixes of others.
+    STYLE_MAPPING: dict[str, list[tuple[tuple[str, ...], str]]] = {
+        "font": [
+            (("name",), "font_name"),
+            (("sz",), "font_size"),
+            (("size",), "font_size"),
+            (("color", "rgb"), "font_color"),
+            (("color",), "font_color"),
+            (("b",), "bold"),
+            (("bold",), "bold"),
+            (("i",), "italic"),
+            (("italic",), "italic"),
+            (("u",), "underline"),
+            (("underline",), "underline"),
+            (("strike",), "font_strikeout"),
+            (("vertAlign",), "font_script"),
+            (("vertalign",), "font_script"),
+        ],
+        "number_format": [(("format_code",), "num_format"), ((), "num_format")],
+        "protection": [(("locked",), "locked"), (("hidden",), "hidden")],
+        "alignment": [
+            (("horizontal",), "align"),
+            (("vertical",), "valign"),
+            (("text_rotation",), "rotation"),
+            (("wrap_text",), "text_wrap"),
+            (("indent",), "indent"),
+            (("shrink_to_fit",), "shrink"),
+        ],
+        "fill": [
+            (("patternType",), "pattern"),
+            (("patterntype",), "pattern"),
+            (("fill_type",), "pattern"),
+            (("start_color", "rgb"), "fg_color"),
+            (("fgColor", "rgb"), "fg_color"),
+            (("fgcolor", "rgb"), "fg_color"),
+            (("start_color",), "fg_color"),
+            (("fgColor",), "fg_color"),
+            (("fgcolor",), "fg_color"),
+            (("end_color", "rgb"), "bg_color"),
+            (("bgColor", "rgb"), "bg_color"),
+            (("bgcolor", "rgb"), "bg_color"),
+            (("end_color",), "bg_color"),
+            (("bgColor",), "bg_color"),
+            (("bgcolor",), "bg_color"),
+        ],
+        "border": [
+            (("color", "rgb"), "border_color"),
+            (("color",), "border_color"),
+            (("style",), "border"),
+            (("top", "color", "rgb"), "top_color"),
+            (("top", "color"), "top_color"),
+            (("top", "style"), "top"),
+            (("top",), "top"),
+            (("right", "color", "rgb"), "right_color"),
+            (("right", "color"), "right_color"),
+            (("right", "style"), "right"),
+            (("right",), "right"),
+            (("bottom", "color", "rgb"), "bottom_color"),
+            (("bottom", "color"), "bottom_color"),
+            (("bottom", "style"), "bottom"),
+            (("bottom",), "bottom"),
+            (("left", "color", "rgb"), "left_color"),
+            (("left", "color"), "left_color"),
+            (("left", "style"), "left"),
+            (("left",), "left"),
+        ],
+    }
+
+    @classmethod
+    def convert(cls, style_dict, num_format_str=None):
+        """
+        converts a style_dict to an xlsxwriter format dict
+
+        Parameters
+        ----------
+        style_dict : style dictionary to convert
+        num_format_str : optional number format string
+        """
+        # Create a XlsxWriter format object.
+        props = {}
+
+        if num_format_str is not None:
+            props["num_format"] = num_format_str
+
+        if style_dict is None:
+            return props
+
+        if "borders" in style_dict:
+            style_dict = style_dict.copy()
+            style_dict["border"] = style_dict.pop("borders")
+
+        for style_group_key, style_group in style_dict.items():
+            for src, dst in cls.STYLE_MAPPING.get(style_group_key, []):
+                # src is a sequence of keys into a nested dict
+                # dst is a flat key
+                if dst in props:
+                    continue
+                v = style_group
+                for k in src:
+                    try:
+                        v = v[k]
+                    except (KeyError, TypeError):
+                        break
+                else:
+                    props[dst] = v
+
+        if isinstance(props.get("pattern"), str):
+            # TODO: support other fill patterns
+            props["pattern"] = 0 if props["pattern"] == "none" else 1
+
+        for k in ["border", "top", "right", "bottom", "left"]:
+            if isinstance(props.get(k), str):
+                try:
+                    props[k] = [
+                        "none",
+                        "thin",
+                        "medium",
+                        "dashed",
+                        "dotted",
+                        "thick",
+                        "double",
+                        "hair",
+                        "mediumDashed",
+                        "dashDot",
+                        "mediumDashDot",
+                        "dashDotDot",
+                        "mediumDashDotDot",
+                        "slantDashDot",
+                    ].index(props[k])
+                except ValueError:
+                    props[k] = 2
+
+        if isinstance(props.get("font_script"), str):
+            props["font_script"] = ["baseline", "superscript", "subscript"].index(
+                props["font_script"]
+            )
+
+        if isinstance(props.get("underline"), str):
+            props["underline"] = {
+                "none": 0,
+                "single": 1,
+                "double": 2,
+                "singleAccounting": 33,
+                "doubleAccounting": 34,
+            }[props["underline"]]
+
+        # GH 30107 - xlsxwriter uses different name
+        if props.get("valign") == "center":
+            props["valign"] = "vcenter"
+
+        return props
+
+
+class XlsxWriter(ExcelWriter):
+    _engine = "xlsxwriter"
+    _supported_extensions = (".xlsx",)
+
+    def __init__(
+        self,
+        path: FilePath | WriteExcelBuffer | ExcelWriter,
+        engine: str | None = None,
+        date_format: str | None = None,
+        datetime_format: str | None = None,
+        mode: str = "w",
+        storage_options: StorageOptions | None = None,
+        if_sheet_exists: ExcelWriterIfSheetExists | None = None,
+        engine_kwargs: dict[str, Any] | None = None,
+        **kwargs,
+    ) -> None:
+        # Use the xlsxwriter module as the Excel writer.
+        from xlsxwriter import Workbook
+
+        engine_kwargs = combine_kwargs(engine_kwargs, kwargs)
+
+        if mode == "a":
+            raise ValueError("Append mode is not supported with xlsxwriter!")
+
+        super().__init__(
+            path,
+            engine=engine,
+            date_format=date_format,
+            datetime_format=datetime_format,
+            mode=mode,
+            storage_options=storage_options,
+            if_sheet_exists=if_sheet_exists,
+            engine_kwargs=engine_kwargs,
+        )
+
+        try:
+            self._book = Workbook(self._handles.handle, **engine_kwargs)  # type: ignore[arg-type]
+        except TypeError:
+            self._handles.handle.close()
+            raise
+
+    @property
+    def book(self):
+        """
+        Book instance of class xlsxwriter.Workbook.
+
+        This attribute can be used to access engine-specific features.
+        """
+        return self._book
+
+    @property
+    def sheets(self) -> dict[str, Any]:
+        result = self.book.sheetnames
+        return result
+
+    def _save(self) -> None:
+        """
+        Save workbook to disk.
+        """
+        self.book.close()
+
+    def _write_cells(
+        self,
+        cells,
+        sheet_name: str | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        freeze_panes: tuple[int, int] | None = None,
+    ) -> None:
+        # Write the frame cells using xlsxwriter.
+        sheet_name = self._get_sheet_name(sheet_name)
+
+        wks = self.book.get_worksheet_by_name(sheet_name)
+        if wks is None:
+            wks = self.book.add_worksheet(sheet_name)
+
+        style_dict = {"null": None}
+
+        if validate_freeze_panes(freeze_panes):
+            wks.freeze_panes(*(freeze_panes))
+
+        for cell in cells:
+            val, fmt = self._value_with_fmt(cell.val)
+
+            stylekey = json.dumps(cell.style)
+            if fmt:
+                stylekey += fmt
+
+            if stylekey in style_dict:
+                style = style_dict[stylekey]
+            else:
+                style = self.book.add_format(_XlsxStyler.convert(cell.style, fmt))
+                style_dict[stylekey] = style
+
+            if cell.mergestart is not None and cell.mergeend is not None:
+                wks.merge_range(
+                    startrow + cell.row,
+                    startcol + cell.col,
+                    startrow + cell.mergestart,
+                    startcol + cell.mergeend,
+                    val,
+                    style,
+                )
+            else:
+                wks.write(startrow + cell.row, startcol + cell.col, val, style)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/feather_format.py b/.venv/lib/python3.13/site-packages/pandas/io/feather_format.py
new file mode 100644
index 0000000000000000000000000000000000000000..1bdb732cb10de7c9622a10f6b353b766d049376c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/feather_format.py
@@ -0,0 +1,130 @@
+""" feather-format compat """
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._decorators import doc
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.api import DataFrame
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io._util import arrow_table_to_pandas
+from pandas.io.common import get_handle
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        DtypeBackend,
+        FilePath,
+        ReadBuffer,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def to_feather(
+    df: DataFrame,
+    path: FilePath | WriteBuffer[bytes],
+    storage_options: StorageOptions | None = None,
+    **kwargs: Any,
+) -> None:
+    """
+    Write a DataFrame to the binary Feather format.
+
+    Parameters
+    ----------
+    df : DataFrame
+    path : str, path object, or file-like object
+    {storage_options}
+    **kwargs :
+        Additional keywords passed to `pyarrow.feather.write_feather`.
+
+    """
+    import_optional_dependency("pyarrow")
+    from pyarrow import feather
+
+    if not isinstance(df, DataFrame):
+        raise ValueError("feather only support IO with DataFrames")
+
+    with get_handle(
+        path, "wb", storage_options=storage_options, is_text=False
+    ) as handles:
+        feather.write_feather(df, handles.handle, **kwargs)
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def read_feather(
+    path: FilePath | ReadBuffer[bytes],
+    columns: Sequence[Hashable] | None = None,
+    use_threads: bool = True,
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame:
+    """
+    Load a feather-format object from the file path.
+
+    Parameters
+    ----------
+    path : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``read()`` function. The string could be a URL.
+        Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be: ``file://localhost/path/to/table.feather``.
+    columns : sequence, default None
+        If not provided, all columns are read.
+    use_threads : bool, default True
+        Whether to parallelize reading using multiple threads.
+    {storage_options}
+
+    dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    type of object stored in file
+
+    Examples
+    --------
+    >>> df = pd.read_feather("path/to/file.feather")  # doctest: +SKIP
+    """
+    import_optional_dependency("pyarrow")
+    from pyarrow import feather
+
+    # import utils to register the pyarrow extension types
+    import pandas.core.arrays.arrow.extension_types  # pyright: ignore[reportUnusedImport] # noqa: F401
+
+    check_dtype_backend(dtype_backend)
+
+    with get_handle(
+        path, "rb", storage_options=storage_options, is_text=False
+    ) as handles:
+        if dtype_backend is lib.no_default and not using_string_dtype():
+            return feather.read_feather(
+                handles.handle, columns=columns, use_threads=bool(use_threads)
+            )
+
+        pa_table = feather.read_table(
+            handles.handle, columns=columns, use_threads=bool(use_threads)
+        )
+        return arrow_table_to_pandas(pa_table, dtype_backend=dtype_backend)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..5e56b1bc7ba4377cc5de9d68a1424524aef21cb5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/__init__.py
@@ -0,0 +1,9 @@
+# ruff: noqa: TCH004
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    # import modules that have public classes/functions
+    from pandas.io.formats import style
+
+    # and mark only those modules as public
+    __all__ = ["style"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/_color_data.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/_color_data.py
new file mode 100644
index 0000000000000000000000000000000000000000..2e7cb7f29646eb11c0ec83d8a909a8cfd7953182
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/_color_data.py
@@ -0,0 +1,157 @@
+# GH37967: Enable the use of CSS named colors, as defined in
+# matplotlib.colors.CSS4_COLORS, when exporting to Excel.
+# This data has been copied here, instead of being imported from matplotlib,
+# not to have ``to_excel`` methods require matplotlib.
+# source: matplotlib._color_data (3.3.3)
+from __future__ import annotations
+
+CSS4_COLORS = {
+    "aliceblue": "F0F8FF",
+    "antiquewhite": "FAEBD7",
+    "aqua": "00FFFF",
+    "aquamarine": "7FFFD4",
+    "azure": "F0FFFF",
+    "beige": "F5F5DC",
+    "bisque": "FFE4C4",
+    "black": "000000",
+    "blanchedalmond": "FFEBCD",
+    "blue": "0000FF",
+    "blueviolet": "8A2BE2",
+    "brown": "A52A2A",
+    "burlywood": "DEB887",
+    "cadetblue": "5F9EA0",
+    "chartreuse": "7FFF00",
+    "chocolate": "D2691E",
+    "coral": "FF7F50",
+    "cornflowerblue": "6495ED",
+    "cornsilk": "FFF8DC",
+    "crimson": "DC143C",
+    "cyan": "00FFFF",
+    "darkblue": "00008B",
+    "darkcyan": "008B8B",
+    "darkgoldenrod": "B8860B",
+    "darkgray": "A9A9A9",
+    "darkgreen": "006400",
+    "darkgrey": "A9A9A9",
+    "darkkhaki": "BDB76B",
+    "darkmagenta": "8B008B",
+    "darkolivegreen": "556B2F",
+    "darkorange": "FF8C00",
+    "darkorchid": "9932CC",
+    "darkred": "8B0000",
+    "darksalmon": "E9967A",
+    "darkseagreen": "8FBC8F",
+    "darkslateblue": "483D8B",
+    "darkslategray": "2F4F4F",
+    "darkslategrey": "2F4F4F",
+    "darkturquoise": "00CED1",
+    "darkviolet": "9400D3",
+    "deeppink": "FF1493",
+    "deepskyblue": "00BFFF",
+    "dimgray": "696969",
+    "dimgrey": "696969",
+    "dodgerblue": "1E90FF",
+    "firebrick": "B22222",
+    "floralwhite": "FFFAF0",
+    "forestgreen": "228B22",
+    "fuchsia": "FF00FF",
+    "gainsboro": "DCDCDC",
+    "ghostwhite": "F8F8FF",
+    "gold": "FFD700",
+    "goldenrod": "DAA520",
+    "gray": "808080",
+    "green": "008000",
+    "greenyellow": "ADFF2F",
+    "grey": "808080",
+    "honeydew": "F0FFF0",
+    "hotpink": "FF69B4",
+    "indianred": "CD5C5C",
+    "indigo": "4B0082",
+    "ivory": "FFFFF0",
+    "khaki": "F0E68C",
+    "lavender": "E6E6FA",
+    "lavenderblush": "FFF0F5",
+    "lawngreen": "7CFC00",
+    "lemonchiffon": "FFFACD",
+    "lightblue": "ADD8E6",
+    "lightcoral": "F08080",
+    "lightcyan": "E0FFFF",
+    "lightgoldenrodyellow": "FAFAD2",
+    "lightgray": "D3D3D3",
+    "lightgreen": "90EE90",
+    "lightgrey": "D3D3D3",
+    "lightpink": "FFB6C1",
+    "lightsalmon": "FFA07A",
+    "lightseagreen": "20B2AA",
+    "lightskyblue": "87CEFA",
+    "lightslategray": "778899",
+    "lightslategrey": "778899",
+    "lightsteelblue": "B0C4DE",
+    "lightyellow": "FFFFE0",
+    "lime": "00FF00",
+    "limegreen": "32CD32",
+    "linen": "FAF0E6",
+    "magenta": "FF00FF",
+    "maroon": "800000",
+    "mediumaquamarine": "66CDAA",
+    "mediumblue": "0000CD",
+    "mediumorchid": "BA55D3",
+    "mediumpurple": "9370DB",
+    "mediumseagreen": "3CB371",
+    "mediumslateblue": "7B68EE",
+    "mediumspringgreen": "00FA9A",
+    "mediumturquoise": "48D1CC",
+    "mediumvioletred": "C71585",
+    "midnightblue": "191970",
+    "mintcream": "F5FFFA",
+    "mistyrose": "FFE4E1",
+    "moccasin": "FFE4B5",
+    "navajowhite": "FFDEAD",
+    "navy": "000080",
+    "oldlace": "FDF5E6",
+    "olive": "808000",
+    "olivedrab": "6B8E23",
+    "orange": "FFA500",
+    "orangered": "FF4500",
+    "orchid": "DA70D6",
+    "palegoldenrod": "EEE8AA",
+    "palegreen": "98FB98",
+    "paleturquoise": "AFEEEE",
+    "palevioletred": "DB7093",
+    "papayawhip": "FFEFD5",
+    "peachpuff": "FFDAB9",
+    "peru": "CD853F",
+    "pink": "FFC0CB",
+    "plum": "DDA0DD",
+    "powderblue": "B0E0E6",
+    "purple": "800080",
+    "rebeccapurple": "663399",
+    "red": "FF0000",
+    "rosybrown": "BC8F8F",
+    "royalblue": "4169E1",
+    "saddlebrown": "8B4513",
+    "salmon": "FA8072",
+    "sandybrown": "F4A460",
+    "seagreen": "2E8B57",
+    "seashell": "FFF5EE",
+    "sienna": "A0522D",
+    "silver": "C0C0C0",
+    "skyblue": "87CEEB",
+    "slateblue": "6A5ACD",
+    "slategray": "708090",
+    "slategrey": "708090",
+    "snow": "FFFAFA",
+    "springgreen": "00FF7F",
+    "steelblue": "4682B4",
+    "tan": "D2B48C",
+    "teal": "008080",
+    "thistle": "D8BFD8",
+    "tomato": "FF6347",
+    "turquoise": "40E0D0",
+    "violet": "EE82EE",
+    "wheat": "F5DEB3",
+    "white": "FFFFFF",
+    "whitesmoke": "F5F5F5",
+    "yellow": "FFFF00",
+    "yellowgreen": "9ACD32",
+}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/console.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/console.py
new file mode 100644
index 0000000000000000000000000000000000000000..2a6cbe07629031687c249f70b51bdfbe2dd84041
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/console.py
@@ -0,0 +1,94 @@
+"""
+Internal module for console introspection
+"""
+from __future__ import annotations
+
+from shutil import get_terminal_size
+
+
+def get_console_size() -> tuple[int | None, int | None]:
+    """
+    Return console size as tuple = (width, height).
+
+    Returns (None,None) in non-interactive session.
+    """
+    from pandas import get_option
+
+    display_width = get_option("display.width")
+    display_height = get_option("display.max_rows")
+
+    # Consider
+    # interactive shell terminal, can detect term size
+    # interactive non-shell terminal (ipnb/ipqtconsole), cannot detect term
+    # size non-interactive script, should disregard term size
+
+    # in addition
+    # width,height have default values, but setting to 'None' signals
+    # should use Auto-Detection, But only in interactive shell-terminal.
+    # Simple. yeah.
+
+    if in_interactive_session():
+        if in_ipython_frontend():
+            # sane defaults for interactive non-shell terminal
+            # match default for width,height in config_init
+            from pandas._config.config import get_default_val
+
+            terminal_width = get_default_val("display.width")
+            terminal_height = get_default_val("display.max_rows")
+        else:
+            # pure terminal
+            terminal_width, terminal_height = get_terminal_size()
+    else:
+        terminal_width, terminal_height = None, None
+
+    # Note if the User sets width/Height to None (auto-detection)
+    # and we're in a script (non-inter), this will return (None,None)
+    # caller needs to deal.
+    return display_width or terminal_width, display_height or terminal_height
+
+
+# ----------------------------------------------------------------------
+# Detect our environment
+
+
+def in_interactive_session() -> bool:
+    """
+    Check if we're running in an interactive shell.
+
+    Returns
+    -------
+    bool
+        True if running under python/ipython interactive shell.
+    """
+    from pandas import get_option
+
+    def check_main():
+        try:
+            import __main__ as main
+        except ModuleNotFoundError:
+            return get_option("mode.sim_interactive")
+        return not hasattr(main, "__file__") or get_option("mode.sim_interactive")
+
+    try:
+        # error: Name '__IPYTHON__' is not defined
+        return __IPYTHON__ or check_main()  # type: ignore[name-defined]
+    except NameError:
+        return check_main()
+
+
+def in_ipython_frontend() -> bool:
+    """
+    Check if we're inside an IPython zmq frontend.
+
+    Returns
+    -------
+    bool
+    """
+    try:
+        # error: Name 'get_ipython' is not defined
+        ip = get_ipython()  # type: ignore[name-defined]
+        return "zmq" in str(type(ip)).lower()
+    except NameError:
+        pass
+
+    return False
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/css.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/css.py
new file mode 100644
index 0000000000000000000000000000000000000000..ccce60c00a9e02bf3bb7f21c5ec799b7123e8eed
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/css.py
@@ -0,0 +1,421 @@
+"""
+Utilities for interpreting CSS from Stylers for formatting non-HTML outputs.
+"""
+from __future__ import annotations
+
+import re
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+)
+import warnings
+
+from pandas.errors import CSSWarning
+from pandas.util._exceptions import find_stack_level
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Iterable,
+        Iterator,
+    )
+
+
+def _side_expander(prop_fmt: str) -> Callable:
+    """
+    Wrapper to expand shorthand property into top, right, bottom, left properties
+
+    Parameters
+    ----------
+    side : str
+        The border side to expand into properties
+
+    Returns
+    -------
+        function: Return to call when a 'border(-{side}): {value}' string is encountered
+    """
+
+    def expand(self, prop, value: str) -> Generator[tuple[str, str], None, None]:
+        """
+        Expand shorthand property into side-specific property (top, right, bottom, left)
+
+        Parameters
+        ----------
+            prop (str): CSS property name
+            value (str): String token for property
+
+        Yields
+        ------
+            Tuple (str, str): Expanded property, value
+        """
+        tokens = value.split()
+        try:
+            mapping = self.SIDE_SHORTHANDS[len(tokens)]
+        except KeyError:
+            warnings.warn(
+                f'Could not expand "{prop}: {value}"',
+                CSSWarning,
+                stacklevel=find_stack_level(),
+            )
+            return
+        for key, idx in zip(self.SIDES, mapping):
+            yield prop_fmt.format(key), tokens[idx]
+
+    return expand
+
+
+def _border_expander(side: str = "") -> Callable:
+    """
+    Wrapper to expand 'border' property into border color, style, and width properties
+
+    Parameters
+    ----------
+    side : str
+        The border side to expand into properties
+
+    Returns
+    -------
+        function: Return to call when a 'border(-{side}): {value}' string is encountered
+    """
+    if side != "":
+        side = f"-{side}"
+
+    def expand(self, prop, value: str) -> Generator[tuple[str, str], None, None]:
+        """
+        Expand border into color, style, and width tuples
+
+        Parameters
+        ----------
+            prop : str
+                CSS property name passed to styler
+            value : str
+                Value passed to styler for property
+
+        Yields
+        ------
+            Tuple (str, str): Expanded property, value
+        """
+        tokens = value.split()
+        if len(tokens) == 0 or len(tokens) > 3:
+            warnings.warn(
+                f'Too many tokens provided to "{prop}" (expected 1-3)',
+                CSSWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        # TODO: Can we use current color as initial value to comply with CSS standards?
+        border_declarations = {
+            f"border{side}-color": "black",
+            f"border{side}-style": "none",
+            f"border{side}-width": "medium",
+        }
+        for token in tokens:
+            if token.lower() in self.BORDER_STYLES:
+                border_declarations[f"border{side}-style"] = token
+            elif any(ratio in token.lower() for ratio in self.BORDER_WIDTH_RATIOS):
+                border_declarations[f"border{side}-width"] = token
+            else:
+                border_declarations[f"border{side}-color"] = token
+            # TODO: Warn user if item entered more than once (e.g. "border: red green")
+
+        # Per CSS, "border" will reset previous "border-*" definitions
+        yield from self.atomize(border_declarations.items())
+
+    return expand
+
+
+class CSSResolver:
+    """
+    A callable for parsing and resolving CSS to atomic properties.
+    """
+
+    UNIT_RATIOS = {
+        "pt": ("pt", 1),
+        "em": ("em", 1),
+        "rem": ("pt", 12),
+        "ex": ("em", 0.5),
+        # 'ch':
+        "px": ("pt", 0.75),
+        "pc": ("pt", 12),
+        "in": ("pt", 72),
+        "cm": ("in", 1 / 2.54),
+        "mm": ("in", 1 / 25.4),
+        "q": ("mm", 0.25),
+        "!!default": ("em", 0),
+    }
+
+    FONT_SIZE_RATIOS = UNIT_RATIOS.copy()
+    FONT_SIZE_RATIOS.update(
+        {
+            "%": ("em", 0.01),
+            "xx-small": ("rem", 0.5),
+            "x-small": ("rem", 0.625),
+            "small": ("rem", 0.8),
+            "medium": ("rem", 1),
+            "large": ("rem", 1.125),
+            "x-large": ("rem", 1.5),
+            "xx-large": ("rem", 2),
+            "smaller": ("em", 1 / 1.2),
+            "larger": ("em", 1.2),
+            "!!default": ("em", 1),
+        }
+    )
+
+    MARGIN_RATIOS = UNIT_RATIOS.copy()
+    MARGIN_RATIOS.update({"none": ("pt", 0)})
+
+    BORDER_WIDTH_RATIOS = UNIT_RATIOS.copy()
+    BORDER_WIDTH_RATIOS.update(
+        {
+            "none": ("pt", 0),
+            "thick": ("px", 4),
+            "medium": ("px", 2),
+            "thin": ("px", 1),
+            # Default: medium only if solid
+        }
+    )
+
+    BORDER_STYLES = [
+        "none",
+        "hidden",
+        "dotted",
+        "dashed",
+        "solid",
+        "double",
+        "groove",
+        "ridge",
+        "inset",
+        "outset",
+        "mediumdashdot",
+        "dashdotdot",
+        "hair",
+        "mediumdashdotdot",
+        "dashdot",
+        "slantdashdot",
+        "mediumdashed",
+    ]
+
+    SIDE_SHORTHANDS = {
+        1: [0, 0, 0, 0],
+        2: [0, 1, 0, 1],
+        3: [0, 1, 2, 1],
+        4: [0, 1, 2, 3],
+    }
+
+    SIDES = ("top", "right", "bottom", "left")
+
+    CSS_EXPANSIONS = {
+        **{
+            (f"border-{prop}" if prop else "border"): _border_expander(prop)
+            for prop in ["", "top", "right", "bottom", "left"]
+        },
+        **{
+            f"border-{prop}": _side_expander(f"border-{{:s}}-{prop}")
+            for prop in ["color", "style", "width"]
+        },
+        "margin": _side_expander("margin-{:s}"),
+        "padding": _side_expander("padding-{:s}"),
+    }
+
+    def __call__(
+        self,
+        declarations: str | Iterable[tuple[str, str]],
+        inherited: dict[str, str] | None = None,
+    ) -> dict[str, str]:
+        """
+        The given declarations to atomic properties.
+
+        Parameters
+        ----------
+        declarations_str : str | Iterable[tuple[str, str]]
+            A CSS string or set of CSS declaration tuples
+            e.g. "font-weight: bold; background: blue" or
+            {("font-weight", "bold"), ("background", "blue")}
+        inherited : dict, optional
+            Atomic properties indicating the inherited style context in which
+            declarations_str is to be resolved. ``inherited`` should already
+            be resolved, i.e. valid output of this method.
+
+        Returns
+        -------
+        dict
+            Atomic CSS 2.2 properties.
+
+        Examples
+        --------
+        >>> resolve = CSSResolver()
+        >>> inherited = {'font-family': 'serif', 'font-weight': 'bold'}
+        >>> out = resolve('''
+        ...               border-color: BLUE RED;
+        ...               font-size: 1em;
+        ...               font-size: 2em;
+        ...               font-weight: normal;
+        ...               font-weight: inherit;
+        ...               ''', inherited)
+        >>> sorted(out.items())  # doctest: +NORMALIZE_WHITESPACE
+        [('border-bottom-color', 'blue'),
+         ('border-left-color', 'red'),
+         ('border-right-color', 'red'),
+         ('border-top-color', 'blue'),
+         ('font-family', 'serif'),
+         ('font-size', '24pt'),
+         ('font-weight', 'bold')]
+        """
+        if isinstance(declarations, str):
+            declarations = self.parse(declarations)
+        props = dict(self.atomize(declarations))
+        if inherited is None:
+            inherited = {}
+
+        props = self._update_initial(props, inherited)
+        props = self._update_font_size(props, inherited)
+        return self._update_other_units(props)
+
+    def _update_initial(
+        self,
+        props: dict[str, str],
+        inherited: dict[str, str],
+    ) -> dict[str, str]:
+        # 1. resolve inherited, initial
+        for prop, val in inherited.items():
+            if prop not in props:
+                props[prop] = val
+
+        new_props = props.copy()
+        for prop, val in props.items():
+            if val == "inherit":
+                val = inherited.get(prop, "initial")
+
+            if val in ("initial", None):
+                # we do not define a complete initial stylesheet
+                del new_props[prop]
+            else:
+                new_props[prop] = val
+        return new_props
+
+    def _update_font_size(
+        self,
+        props: dict[str, str],
+        inherited: dict[str, str],
+    ) -> dict[str, str]:
+        # 2. resolve relative font size
+        if props.get("font-size"):
+            props["font-size"] = self.size_to_pt(
+                props["font-size"],
+                self._get_font_size(inherited),
+                conversions=self.FONT_SIZE_RATIOS,
+            )
+        return props
+
+    def _get_font_size(self, props: dict[str, str]) -> float | None:
+        if props.get("font-size"):
+            font_size_string = props["font-size"]
+            return self._get_float_font_size_from_pt(font_size_string)
+        return None
+
+    def _get_float_font_size_from_pt(self, font_size_string: str) -> float:
+        assert font_size_string.endswith("pt")
+        return float(font_size_string.rstrip("pt"))
+
+    def _update_other_units(self, props: dict[str, str]) -> dict[str, str]:
+        font_size = self._get_font_size(props)
+        # 3. TODO: resolve other font-relative units
+        for side in self.SIDES:
+            prop = f"border-{side}-width"
+            if prop in props:
+                props[prop] = self.size_to_pt(
+                    props[prop],
+                    em_pt=font_size,
+                    conversions=self.BORDER_WIDTH_RATIOS,
+                )
+
+            for prop in [f"margin-{side}", f"padding-{side}"]:
+                if prop in props:
+                    # TODO: support %
+                    props[prop] = self.size_to_pt(
+                        props[prop],
+                        em_pt=font_size,
+                        conversions=self.MARGIN_RATIOS,
+                    )
+        return props
+
+    def size_to_pt(self, in_val, em_pt=None, conversions=UNIT_RATIOS) -> str:
+        def _error():
+            warnings.warn(
+                f"Unhandled size: {repr(in_val)}",
+                CSSWarning,
+                stacklevel=find_stack_level(),
+            )
+            return self.size_to_pt("1!!default", conversions=conversions)
+
+        match = re.match(r"^(\S*?)([a-zA-Z%!].*)", in_val)
+        if match is None:
+            return _error()
+
+        val, unit = match.groups()
+        if val == "":
+            # hack for 'large' etc.
+            val = 1
+        else:
+            try:
+                val = float(val)
+            except ValueError:
+                return _error()
+
+        while unit != "pt":
+            if unit == "em":
+                if em_pt is None:
+                    unit = "rem"
+                else:
+                    val *= em_pt
+                    unit = "pt"
+                continue
+
+            try:
+                unit, mul = conversions[unit]
+            except KeyError:
+                return _error()
+            val *= mul
+
+        val = round(val, 5)
+        if int(val) == val:
+            size_fmt = f"{int(val):d}pt"
+        else:
+            size_fmt = f"{val:f}pt"
+        return size_fmt
+
+    def atomize(self, declarations: Iterable) -> Generator[tuple[str, str], None, None]:
+        for prop, value in declarations:
+            prop = prop.lower()
+            value = value.lower()
+            if prop in self.CSS_EXPANSIONS:
+                expand = self.CSS_EXPANSIONS[prop]
+                yield from expand(self, prop, value)
+            else:
+                yield prop, value
+
+    def parse(self, declarations_str: str) -> Iterator[tuple[str, str]]:
+        """
+        Generates (prop, value) pairs from declarations.
+
+        In a future version may generate parsed tokens from tinycss/tinycss2
+
+        Parameters
+        ----------
+        declarations_str : str
+        """
+        for decl in declarations_str.split(";"):
+            if not decl.strip():
+                continue
+            prop, sep, val = decl.partition(":")
+            prop = prop.strip().lower()
+            # TODO: don't lowercase case sensitive parts of values (strings)
+            val = val.strip().lower()
+            if sep:
+                yield prop, val
+            else:
+                warnings.warn(
+                    f"Ill-formatted attribute: expected a colon in {repr(decl)}",
+                    CSSWarning,
+                    stacklevel=find_stack_level(),
+                )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/csvs.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/csvs.py
new file mode 100644
index 0000000000000000000000000000000000000000..50503e862ef433901f40715987c2105f6f16263a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/csvs.py
@@ -0,0 +1,330 @@
+"""
+Module for formatting output data into CSV files.
+"""
+
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Iterator,
+    Sequence,
+)
+import csv as csvlib
+import os
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+
+import numpy as np
+
+from pandas._libs import writers as libwriters
+from pandas._typing import SequenceNotStr
+from pandas.util._decorators import cache_readonly
+
+from pandas.core.dtypes.generic import (
+    ABCDatetimeIndex,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCPeriodIndex,
+)
+from pandas.core.dtypes.missing import notna
+
+from pandas.core.indexes.api import Index
+
+from pandas.io.common import get_handle
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        FloatFormatType,
+        IndexLabel,
+        StorageOptions,
+        WriteBuffer,
+        npt,
+    )
+
+    from pandas.io.formats.format import DataFrameFormatter
+
+
+_DEFAULT_CHUNKSIZE_CELLS = 100_000
+
+
+class CSVFormatter:
+    cols: npt.NDArray[np.object_]
+
+    def __init__(
+        self,
+        formatter: DataFrameFormatter,
+        path_or_buf: FilePath | WriteBuffer[str] | WriteBuffer[bytes] = "",
+        sep: str = ",",
+        cols: Sequence[Hashable] | None = None,
+        index_label: IndexLabel | None = None,
+        mode: str = "w",
+        encoding: str | None = None,
+        errors: str = "strict",
+        compression: CompressionOptions = "infer",
+        quoting: int | None = None,
+        lineterminator: str | None = "\n",
+        chunksize: int | None = None,
+        quotechar: str | None = '"',
+        date_format: str | None = None,
+        doublequote: bool = True,
+        escapechar: str | None = None,
+        storage_options: StorageOptions | None = None,
+    ) -> None:
+        self.fmt = formatter
+
+        self.obj = self.fmt.frame
+
+        self.filepath_or_buffer = path_or_buf
+        self.encoding = encoding
+        self.compression: CompressionOptions = compression
+        self.mode = mode
+        self.storage_options = storage_options
+
+        self.sep = sep
+        self.index_label = self._initialize_index_label(index_label)
+        self.errors = errors
+        self.quoting = quoting or csvlib.QUOTE_MINIMAL
+        self.quotechar = self._initialize_quotechar(quotechar)
+        self.doublequote = doublequote
+        self.escapechar = escapechar
+        self.lineterminator = lineterminator or os.linesep
+        self.date_format = date_format
+        self.cols = self._initialize_columns(cols)
+        self.chunksize = self._initialize_chunksize(chunksize)
+
+    @property
+    def na_rep(self) -> str:
+        return self.fmt.na_rep
+
+    @property
+    def float_format(self) -> FloatFormatType | None:
+        return self.fmt.float_format
+
+    @property
+    def decimal(self) -> str:
+        return self.fmt.decimal
+
+    @property
+    def header(self) -> bool | SequenceNotStr[str]:
+        return self.fmt.header
+
+    @property
+    def index(self) -> bool:
+        return self.fmt.index
+
+    def _initialize_index_label(self, index_label: IndexLabel | None) -> IndexLabel:
+        if index_label is not False:
+            if index_label is None:
+                return self._get_index_label_from_obj()
+            elif not isinstance(index_label, (list, tuple, np.ndarray, ABCIndex)):
+                # given a string for a DF with Index
+                return [index_label]
+        return index_label
+
+    def _get_index_label_from_obj(self) -> Sequence[Hashable]:
+        if isinstance(self.obj.index, ABCMultiIndex):
+            return self._get_index_label_multiindex()
+        else:
+            return self._get_index_label_flat()
+
+    def _get_index_label_multiindex(self) -> Sequence[Hashable]:
+        return [name or "" for name in self.obj.index.names]
+
+    def _get_index_label_flat(self) -> Sequence[Hashable]:
+        index_label = self.obj.index.name
+        return [""] if index_label is None else [index_label]
+
+    def _initialize_quotechar(self, quotechar: str | None) -> str | None:
+        if self.quoting != csvlib.QUOTE_NONE:
+            # prevents crash in _csv
+            return quotechar
+        return None
+
+    @property
+    def has_mi_columns(self) -> bool:
+        return bool(isinstance(self.obj.columns, ABCMultiIndex))
+
+    def _initialize_columns(
+        self, cols: Iterable[Hashable] | None
+    ) -> npt.NDArray[np.object_]:
+        # validate mi options
+        if self.has_mi_columns:
+            if cols is not None:
+                msg = "cannot specify cols with a MultiIndex on the columns"
+                raise TypeError(msg)
+
+        if cols is not None:
+            if isinstance(cols, ABCIndex):
+                cols = cols._get_values_for_csv(**self._number_format)
+            else:
+                cols = list(cols)
+            self.obj = self.obj.loc[:, cols]
+
+        # update columns to include possible multiplicity of dupes
+        # and make sure cols is just a list of labels
+        new_cols = self.obj.columns
+        return new_cols._get_values_for_csv(**self._number_format)
+
+    def _initialize_chunksize(self, chunksize: int | None) -> int:
+        if chunksize is None:
+            return (_DEFAULT_CHUNKSIZE_CELLS // (len(self.cols) or 1)) or 1
+        return int(chunksize)
+
+    @property
+    def _number_format(self) -> dict[str, Any]:
+        """Dictionary used for storing number formatting settings."""
+        return {
+            "na_rep": self.na_rep,
+            "float_format": self.float_format,
+            "date_format": self.date_format,
+            "quoting": self.quoting,
+            "decimal": self.decimal,
+        }
+
+    @cache_readonly
+    def data_index(self) -> Index:
+        data_index = self.obj.index
+        if (
+            isinstance(data_index, (ABCDatetimeIndex, ABCPeriodIndex))
+            and self.date_format is not None
+        ):
+            data_index = Index(
+                [x.strftime(self.date_format) if notna(x) else "" for x in data_index]
+            )
+        elif isinstance(data_index, ABCMultiIndex):
+            data_index = data_index.remove_unused_levels()
+        return data_index
+
+    @property
+    def nlevels(self) -> int:
+        if self.index:
+            return getattr(self.data_index, "nlevels", 1)
+        else:
+            return 0
+
+    @property
+    def _has_aliases(self) -> bool:
+        return isinstance(self.header, (tuple, list, np.ndarray, ABCIndex))
+
+    @property
+    def _need_to_save_header(self) -> bool:
+        return bool(self._has_aliases or self.header)
+
+    @property
+    def write_cols(self) -> SequenceNotStr[Hashable]:
+        if self._has_aliases:
+            assert not isinstance(self.header, bool)
+            if len(self.header) != len(self.cols):
+                raise ValueError(
+                    f"Writing {len(self.cols)} cols but got {len(self.header)} aliases"
+                )
+            return self.header
+        else:
+            # self.cols is an ndarray derived from Index._get_values_for_csv,
+            #  so its entries are strings, i.e. hashable
+            return cast(SequenceNotStr[Hashable], self.cols)
+
+    @property
+    def encoded_labels(self) -> list[Hashable]:
+        encoded_labels: list[Hashable] = []
+
+        if self.index and self.index_label:
+            assert isinstance(self.index_label, Sequence)
+            encoded_labels = list(self.index_label)
+
+        if not self.has_mi_columns or self._has_aliases:
+            encoded_labels += list(self.write_cols)
+
+        return encoded_labels
+
+    def save(self) -> None:
+        """
+        Create the writer & save.
+        """
+        # apply compression and byte/text conversion
+        with get_handle(
+            self.filepath_or_buffer,
+            self.mode,
+            encoding=self.encoding,
+            errors=self.errors,
+            compression=self.compression,
+            storage_options=self.storage_options,
+        ) as handles:
+            # Note: self.encoding is irrelevant here
+            self.writer = csvlib.writer(
+                handles.handle,
+                lineterminator=self.lineterminator,
+                delimiter=self.sep,
+                quoting=self.quoting,
+                doublequote=self.doublequote,
+                escapechar=self.escapechar,
+                quotechar=self.quotechar,
+            )
+
+            self._save()
+
+    def _save(self) -> None:
+        if self._need_to_save_header:
+            self._save_header()
+        self._save_body()
+
+    def _save_header(self) -> None:
+        if not self.has_mi_columns or self._has_aliases:
+            self.writer.writerow(self.encoded_labels)
+        else:
+            for row in self._generate_multiindex_header_rows():
+                self.writer.writerow(row)
+
+    def _generate_multiindex_header_rows(self) -> Iterator[list[Hashable]]:
+        columns = self.obj.columns
+        for i in range(columns.nlevels):
+            # we need at least 1 index column to write our col names
+            col_line = []
+            if self.index:
+                # name is the first column
+                col_line.append(columns.names[i])
+
+                if isinstance(self.index_label, list) and len(self.index_label) > 1:
+                    col_line.extend([""] * (len(self.index_label) - 1))
+
+            col_line.extend(columns._get_level_values(i))
+            yield col_line
+
+        # Write out the index line if it's not empty.
+        # Otherwise, we will print out an extraneous
+        # blank line between the mi and the data rows.
+        if self.encoded_labels and set(self.encoded_labels) != {""}:
+            yield self.encoded_labels + [""] * len(columns)
+
+    def _save_body(self) -> None:
+        nrows = len(self.data_index)
+        chunks = (nrows // self.chunksize) + 1
+        for i in range(chunks):
+            start_i = i * self.chunksize
+            end_i = min(start_i + self.chunksize, nrows)
+            if start_i >= end_i:
+                break
+            self._save_chunk(start_i, end_i)
+
+    def _save_chunk(self, start_i: int, end_i: int) -> None:
+        # create the data for a chunk
+        slicer = slice(start_i, end_i)
+        df = self.obj.iloc[slicer]
+
+        res = df._get_values_for_csv(**self._number_format)
+        data = list(res._iter_column_arrays())
+
+        ix = self.data_index[slicer]._get_values_for_csv(**self._number_format)
+        libwriters.write_csv_rows(
+            data,
+            ix,
+            self.nlevels,
+            self.cols,
+            self.writer,
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/excel.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/excel.py
new file mode 100644
index 0000000000000000000000000000000000000000..5fd23cd7d918ad0efddb1088d79fd78f6079cca7
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/excel.py
@@ -0,0 +1,962 @@
+"""
+Utilities for conversion to writer-agnostic Excel representation.
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Mapping,
+    Sequence,
+)
+import functools
+import itertools
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs.lib import is_list_like
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes import missing
+from pandas.core.dtypes.common import (
+    is_float,
+    is_scalar,
+)
+
+from pandas import (
+    DataFrame,
+    Index,
+    MultiIndex,
+    PeriodIndex,
+)
+import pandas.core.common as com
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.formats._color_data import CSS4_COLORS
+from pandas.io.formats.css import (
+    CSSResolver,
+    CSSWarning,
+)
+from pandas.io.formats.format import get_level_lengths
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        FilePath,
+        IndexLabel,
+        StorageOptions,
+        WriteExcelBuffer,
+    )
+
+    from pandas import ExcelWriter
+
+
+class ExcelCell:
+    __fields__ = ("row", "col", "val", "style", "mergestart", "mergeend")
+    __slots__ = __fields__
+
+    def __init__(
+        self,
+        row: int,
+        col: int,
+        val,
+        style=None,
+        mergestart: int | None = None,
+        mergeend: int | None = None,
+    ) -> None:
+        self.row = row
+        self.col = col
+        self.val = val
+        self.style = style
+        self.mergestart = mergestart
+        self.mergeend = mergeend
+
+
+class CssExcelCell(ExcelCell):
+    def __init__(
+        self,
+        row: int,
+        col: int,
+        val,
+        style: dict | None,
+        css_styles: dict[tuple[int, int], list[tuple[str, Any]]] | None,
+        css_row: int,
+        css_col: int,
+        css_converter: Callable | None,
+        **kwargs,
+    ) -> None:
+        if css_styles and css_converter:
+            # Use dict to get only one (case-insensitive) declaration per property
+            declaration_dict = {
+                prop.lower(): val for prop, val in css_styles[css_row, css_col]
+            }
+            # Convert to frozenset for order-invariant caching
+            unique_declarations = frozenset(declaration_dict.items())
+            style = css_converter(unique_declarations)
+
+        super().__init__(row=row, col=col, val=val, style=style, **kwargs)
+
+
+class CSSToExcelConverter:
+    """
+    A callable for converting CSS declarations to ExcelWriter styles
+
+    Supports parts of CSS 2.2, with minimal CSS 3.0 support (e.g. text-shadow),
+    focusing on font styling, backgrounds, borders and alignment.
+
+    Operates by first computing CSS styles in a fairly generic
+    way (see :meth:`compute_css`) then determining Excel style
+    properties from CSS properties (see :meth:`build_xlstyle`).
+
+    Parameters
+    ----------
+    inherited : str, optional
+        CSS declarations understood to be the containing scope for the
+        CSS processed by :meth:`__call__`.
+    """
+
+    NAMED_COLORS = CSS4_COLORS
+
+    VERTICAL_MAP = {
+        "top": "top",
+        "text-top": "top",
+        "middle": "center",
+        "baseline": "bottom",
+        "bottom": "bottom",
+        "text-bottom": "bottom",
+        # OpenXML also has 'justify', 'distributed'
+    }
+
+    BOLD_MAP = {
+        "bold": True,
+        "bolder": True,
+        "600": True,
+        "700": True,
+        "800": True,
+        "900": True,
+        "normal": False,
+        "lighter": False,
+        "100": False,
+        "200": False,
+        "300": False,
+        "400": False,
+        "500": False,
+    }
+
+    ITALIC_MAP = {
+        "normal": False,
+        "italic": True,
+        "oblique": True,
+    }
+
+    FAMILY_MAP = {
+        "serif": 1,  # roman
+        "sans-serif": 2,  # swiss
+        "cursive": 4,  # script
+        "fantasy": 5,  # decorative
+    }
+
+    BORDER_STYLE_MAP = {
+        style.lower(): style
+        for style in [
+            "dashed",
+            "mediumDashDot",
+            "dashDotDot",
+            "hair",
+            "dotted",
+            "mediumDashDotDot",
+            "double",
+            "dashDot",
+            "slantDashDot",
+            "mediumDashed",
+        ]
+    }
+
+    # NB: Most of the methods here could be classmethods, as only __init__
+    #     and __call__ make use of instance attributes.  We leave them as
+    #     instancemethods so that users can easily experiment with extensions
+    #     without monkey-patching.
+    inherited: dict[str, str] | None
+
+    def __init__(self, inherited: str | None = None) -> None:
+        if inherited is not None:
+            self.inherited = self.compute_css(inherited)
+        else:
+            self.inherited = None
+        # We should avoid cache on the __call__ method.
+        # Otherwise once the method __call__ has been called
+        # garbage collection no longer deletes the instance.
+        self._call_cached = functools.cache(self._call_uncached)
+
+    compute_css = CSSResolver()
+
+    def __call__(
+        self, declarations: str | frozenset[tuple[str, str]]
+    ) -> dict[str, dict[str, str]]:
+        """
+        Convert CSS declarations to ExcelWriter style.
+
+        Parameters
+        ----------
+        declarations : str | frozenset[tuple[str, str]]
+            CSS string or set of CSS declaration tuples.
+            e.g. "font-weight: bold; background: blue" or
+            {("font-weight", "bold"), ("background", "blue")}
+
+        Returns
+        -------
+        xlstyle : dict
+            A style as interpreted by ExcelWriter when found in
+            ExcelCell.style.
+        """
+        return self._call_cached(declarations)
+
+    def _call_uncached(
+        self, declarations: str | frozenset[tuple[str, str]]
+    ) -> dict[str, dict[str, str]]:
+        properties = self.compute_css(declarations, self.inherited)
+        return self.build_xlstyle(properties)
+
+    def build_xlstyle(self, props: Mapping[str, str]) -> dict[str, dict[str, str]]:
+        out = {
+            "alignment": self.build_alignment(props),
+            "border": self.build_border(props),
+            "fill": self.build_fill(props),
+            "font": self.build_font(props),
+            "number_format": self.build_number_format(props),
+        }
+
+        # TODO: handle cell width and height: needs support in pandas.io.excel
+
+        def remove_none(d: dict[str, str | None]) -> None:
+            """Remove key where value is None, through nested dicts"""
+            for k, v in list(d.items()):
+                if v is None:
+                    del d[k]
+                elif isinstance(v, dict):
+                    remove_none(v)
+                    if not v:
+                        del d[k]
+
+        remove_none(out)
+        return out
+
+    def build_alignment(self, props: Mapping[str, str]) -> dict[str, bool | str | None]:
+        # TODO: text-indent, padding-left -> alignment.indent
+        return {
+            "horizontal": props.get("text-align"),
+            "vertical": self._get_vertical_alignment(props),
+            "wrap_text": self._get_is_wrap_text(props),
+        }
+
+    def _get_vertical_alignment(self, props: Mapping[str, str]) -> str | None:
+        vertical_align = props.get("vertical-align")
+        if vertical_align:
+            return self.VERTICAL_MAP.get(vertical_align)
+        return None
+
+    def _get_is_wrap_text(self, props: Mapping[str, str]) -> bool | None:
+        if props.get("white-space") is None:
+            return None
+        return bool(props["white-space"] not in ("nowrap", "pre", "pre-line"))
+
+    def build_border(
+        self, props: Mapping[str, str]
+    ) -> dict[str, dict[str, str | None]]:
+        return {
+            side: {
+                "style": self._border_style(
+                    props.get(f"border-{side}-style"),
+                    props.get(f"border-{side}-width"),
+                    self.color_to_excel(props.get(f"border-{side}-color")),
+                ),
+                "color": self.color_to_excel(props.get(f"border-{side}-color")),
+            }
+            for side in ["top", "right", "bottom", "left"]
+        }
+
+    def _border_style(self, style: str | None, width: str | None, color: str | None):
+        # convert styles and widths to openxml, one of:
+        #       'dashDot'
+        #       'dashDotDot'
+        #       'dashed'
+        #       'dotted'
+        #       'double'
+        #       'hair'
+        #       'medium'
+        #       'mediumDashDot'
+        #       'mediumDashDotDot'
+        #       'mediumDashed'
+        #       'slantDashDot'
+        #       'thick'
+        #       'thin'
+        if width is None and style is None and color is None:
+            # Return None will remove "border" from style dictionary
+            return None
+
+        if width is None and style is None:
+            # Return "none" will keep "border" in style dictionary
+            return "none"
+
+        if style in ("none", "hidden"):
+            return "none"
+
+        width_name = self._get_width_name(width)
+        if width_name is None:
+            return "none"
+
+        if style in (None, "groove", "ridge", "inset", "outset", "solid"):
+            # not handled
+            return width_name
+
+        if style == "double":
+            return "double"
+        if style == "dotted":
+            if width_name in ("hair", "thin"):
+                return "dotted"
+            return "mediumDashDotDot"
+        if style == "dashed":
+            if width_name in ("hair", "thin"):
+                return "dashed"
+            return "mediumDashed"
+        elif style in self.BORDER_STYLE_MAP:
+            # Excel-specific styles
+            return self.BORDER_STYLE_MAP[style]
+        else:
+            warnings.warn(
+                f"Unhandled border style format: {repr(style)}",
+                CSSWarning,
+                stacklevel=find_stack_level(),
+            )
+            return "none"
+
+    def _get_width_name(self, width_input: str | None) -> str | None:
+        width = self._width_to_float(width_input)
+        if width < 1e-5:
+            return None
+        elif width < 1.3:
+            return "thin"
+        elif width < 2.8:
+            return "medium"
+        return "thick"
+
+    def _width_to_float(self, width: str | None) -> float:
+        if width is None:
+            width = "2pt"
+        return self._pt_to_float(width)
+
+    def _pt_to_float(self, pt_string: str) -> float:
+        assert pt_string.endswith("pt")
+        return float(pt_string.rstrip("pt"))
+
+    def build_fill(self, props: Mapping[str, str]):
+        # TODO: perhaps allow for special properties
+        #       -excel-pattern-bgcolor and -excel-pattern-type
+        fill_color = props.get("background-color")
+        if fill_color not in (None, "transparent", "none"):
+            return {"fgColor": self.color_to_excel(fill_color), "patternType": "solid"}
+
+    def build_number_format(self, props: Mapping[str, str]) -> dict[str, str | None]:
+        fc = props.get("number-format")
+        fc = fc.replace("§", ";") if isinstance(fc, str) else fc
+        return {"format_code": fc}
+
+    def build_font(
+        self, props: Mapping[str, str]
+    ) -> dict[str, bool | float | str | None]:
+        font_names = self._get_font_names(props)
+        decoration = self._get_decoration(props)
+        return {
+            "name": font_names[0] if font_names else None,
+            "family": self._select_font_family(font_names),
+            "size": self._get_font_size(props),
+            "bold": self._get_is_bold(props),
+            "italic": self._get_is_italic(props),
+            "underline": ("single" if "underline" in decoration else None),
+            "strike": ("line-through" in decoration) or None,
+            "color": self.color_to_excel(props.get("color")),
+            # shadow if nonzero digit before shadow color
+            "shadow": self._get_shadow(props),
+        }
+
+    def _get_is_bold(self, props: Mapping[str, str]) -> bool | None:
+        weight = props.get("font-weight")
+        if weight:
+            return self.BOLD_MAP.get(weight)
+        return None
+
+    def _get_is_italic(self, props: Mapping[str, str]) -> bool | None:
+        font_style = props.get("font-style")
+        if font_style:
+            return self.ITALIC_MAP.get(font_style)
+        return None
+
+    def _get_decoration(self, props: Mapping[str, str]) -> Sequence[str]:
+        decoration = props.get("text-decoration")
+        if decoration is not None:
+            return decoration.split()
+        else:
+            return ()
+
+    def _get_underline(self, decoration: Sequence[str]) -> str | None:
+        if "underline" in decoration:
+            return "single"
+        return None
+
+    def _get_shadow(self, props: Mapping[str, str]) -> bool | None:
+        if "text-shadow" in props:
+            return bool(re.search("^[^#(]*[1-9]", props["text-shadow"]))
+        return None
+
+    def _get_font_names(self, props: Mapping[str, str]) -> Sequence[str]:
+        font_names_tmp = re.findall(
+            r"""(?x)
+            (
+            "(?:[^"]|\\")+"
+            |
+            '(?:[^']|\\')+'
+            |
+            [^'",]+
+            )(?=,|\s*$)
+        """,
+            props.get("font-family", ""),
+        )
+
+        font_names = []
+        for name in font_names_tmp:
+            if name[:1] == '"':
+                name = name[1:-1].replace('\\"', '"')
+            elif name[:1] == "'":
+                name = name[1:-1].replace("\\'", "'")
+            else:
+                name = name.strip()
+            if name:
+                font_names.append(name)
+        return font_names
+
+    def _get_font_size(self, props: Mapping[str, str]) -> float | None:
+        size = props.get("font-size")
+        if size is None:
+            return size
+        return self._pt_to_float(size)
+
+    def _select_font_family(self, font_names: Sequence[str]) -> int | None:
+        family = None
+        for name in font_names:
+            family = self.FAMILY_MAP.get(name)
+            if family:
+                break
+
+        return family
+
+    def color_to_excel(self, val: str | None) -> str | None:
+        if val is None:
+            return None
+
+        if self._is_hex_color(val):
+            return self._convert_hex_to_excel(val)
+
+        try:
+            return self.NAMED_COLORS[val]
+        except KeyError:
+            warnings.warn(
+                f"Unhandled color format: {repr(val)}",
+                CSSWarning,
+                stacklevel=find_stack_level(),
+            )
+        return None
+
+    def _is_hex_color(self, color_string: str) -> bool:
+        return bool(color_string.startswith("#"))
+
+    def _convert_hex_to_excel(self, color_string: str) -> str:
+        code = color_string.lstrip("#")
+        if self._is_shorthand_color(color_string):
+            return (code[0] * 2 + code[1] * 2 + code[2] * 2).upper()
+        else:
+            return code.upper()
+
+    def _is_shorthand_color(self, color_string: str) -> bool:
+        """Check if color code is shorthand.
+
+        #FFF is a shorthand as opposed to full #FFFFFF.
+        """
+        code = color_string.lstrip("#")
+        if len(code) == 3:
+            return True
+        elif len(code) == 6:
+            return False
+        else:
+            raise ValueError(f"Unexpected color {color_string}")
+
+
+class ExcelFormatter:
+    """
+    Class for formatting a DataFrame to a list of ExcelCells,
+
+    Parameters
+    ----------
+    df : DataFrame or Styler
+    na_rep: na representation
+    float_format : str, default None
+        Format string for floating point numbers
+    cols : sequence, optional
+        Columns to write
+    header : bool or sequence of str, default True
+        Write out column names. If a list of string is given it is
+        assumed to be aliases for the column names
+    index : bool, default True
+        output row names (index)
+    index_label : str or sequence, default None
+        Column label for index column(s) if desired. If None is given, and
+        `header` and `index` are True, then the index names are used. A
+        sequence should be given if the DataFrame uses MultiIndex.
+    merge_cells : bool, default False
+        Format MultiIndex and Hierarchical Rows as merged cells.
+    inf_rep : str, default `'inf'`
+        representation for np.inf values (which aren't representable in Excel)
+        A `'-'` sign will be added in front of -inf.
+    style_converter : callable, optional
+        This translates Styler styles (CSS) into ExcelWriter styles.
+        Defaults to ``CSSToExcelConverter()``.
+        It should have signature css_declarations string -> excel style.
+        This is only called for body cells.
+    """
+
+    max_rows = 2**20
+    max_cols = 2**14
+
+    def __init__(
+        self,
+        df,
+        na_rep: str = "",
+        float_format: str | None = None,
+        cols: Sequence[Hashable] | None = None,
+        header: Sequence[Hashable] | bool = True,
+        index: bool = True,
+        index_label: IndexLabel | None = None,
+        merge_cells: bool = False,
+        inf_rep: str = "inf",
+        style_converter: Callable | None = None,
+    ) -> None:
+        self.rowcounter = 0
+        self.na_rep = na_rep
+        if not isinstance(df, DataFrame):
+            self.styler = df
+            self.styler._compute()  # calculate applied styles
+            df = df.data
+            if style_converter is None:
+                style_converter = CSSToExcelConverter()
+            self.style_converter: Callable | None = style_converter
+        else:
+            self.styler = None
+            self.style_converter = None
+        self.df = df
+        if cols is not None:
+            # all missing, raise
+            if not len(Index(cols).intersection(df.columns)):
+                raise KeyError("passes columns are not ALL present dataframe")
+
+            if len(Index(cols).intersection(df.columns)) != len(set(cols)):
+                # Deprecated in GH#17295, enforced in 1.0.0
+                raise KeyError("Not all names specified in 'columns' are found")
+
+            self.df = df.reindex(columns=cols)
+
+        self.columns = self.df.columns
+        self.float_format = float_format
+        self.index = index
+        self.index_label = index_label
+        self.header = header
+        self.merge_cells = merge_cells
+        self.inf_rep = inf_rep
+
+    @property
+    def header_style(self) -> dict[str, dict[str, str | bool]]:
+        return {
+            "font": {"bold": True},
+            "borders": {
+                "top": "thin",
+                "right": "thin",
+                "bottom": "thin",
+                "left": "thin",
+            },
+            "alignment": {"horizontal": "center", "vertical": "top"},
+        }
+
+    def _format_value(self, val):
+        if is_scalar(val) and missing.isna(val):
+            val = self.na_rep
+        elif is_float(val):
+            if missing.isposinf_scalar(val):
+                val = self.inf_rep
+            elif missing.isneginf_scalar(val):
+                val = f"-{self.inf_rep}"
+            elif self.float_format is not None:
+                val = float(self.float_format % val)
+        if getattr(val, "tzinfo", None) is not None:
+            raise ValueError(
+                "Excel does not support datetimes with "
+                "timezones. Please ensure that datetimes "
+                "are timezone unaware before writing to Excel."
+            )
+        return val
+
+    def _format_header_mi(self) -> Iterable[ExcelCell]:
+        if self.columns.nlevels > 1:
+            if not self.index:
+                raise NotImplementedError(
+                    "Writing to Excel with MultiIndex columns and no "
+                    "index ('index'=False) is not yet implemented."
+                )
+
+        if not (self._has_aliases or self.header):
+            return
+
+        columns = self.columns
+        level_strs = columns._format_multi(
+            sparsify=self.merge_cells, include_names=False
+        )
+        level_lengths = get_level_lengths(level_strs)
+        coloffset = 0
+        lnum = 0
+
+        if self.index and isinstance(self.df.index, MultiIndex):
+            coloffset = len(self.df.index[0]) - 1
+
+        if self.merge_cells:
+            # Format multi-index as a merged cells.
+            for lnum, name in enumerate(columns.names):
+                yield ExcelCell(
+                    row=lnum,
+                    col=coloffset,
+                    val=name,
+                    style=self.header_style,
+                )
+
+            for lnum, (spans, levels, level_codes) in enumerate(
+                zip(level_lengths, columns.levels, columns.codes)
+            ):
+                values = levels.take(level_codes)
+                for i, span_val in spans.items():
+                    mergestart, mergeend = None, None
+                    if span_val > 1:
+                        mergestart, mergeend = lnum, coloffset + i + span_val
+                    yield CssExcelCell(
+                        row=lnum,
+                        col=coloffset + i + 1,
+                        val=values[i],
+                        style=self.header_style,
+                        css_styles=getattr(self.styler, "ctx_columns", None),
+                        css_row=lnum,
+                        css_col=i,
+                        css_converter=self.style_converter,
+                        mergestart=mergestart,
+                        mergeend=mergeend,
+                    )
+        else:
+            # Format in legacy format with dots to indicate levels.
+            for i, values in enumerate(zip(*level_strs)):
+                v = ".".join(map(pprint_thing, values))
+                yield CssExcelCell(
+                    row=lnum,
+                    col=coloffset + i + 1,
+                    val=v,
+                    style=self.header_style,
+                    css_styles=getattr(self.styler, "ctx_columns", None),
+                    css_row=lnum,
+                    css_col=i,
+                    css_converter=self.style_converter,
+                )
+
+        self.rowcounter = lnum
+
+    def _format_header_regular(self) -> Iterable[ExcelCell]:
+        if self._has_aliases or self.header:
+            coloffset = 0
+
+            if self.index:
+                coloffset = 1
+                if isinstance(self.df.index, MultiIndex):
+                    coloffset = len(self.df.index.names)
+
+            colnames = self.columns
+            if self._has_aliases:
+                self.header = cast(Sequence, self.header)
+                if len(self.header) != len(self.columns):
+                    raise ValueError(
+                        f"Writing {len(self.columns)} cols "
+                        f"but got {len(self.header)} aliases"
+                    )
+                colnames = self.header
+
+            for colindex, colname in enumerate(colnames):
+                yield CssExcelCell(
+                    row=self.rowcounter,
+                    col=colindex + coloffset,
+                    val=colname,
+                    style=self.header_style,
+                    css_styles=getattr(self.styler, "ctx_columns", None),
+                    css_row=0,
+                    css_col=colindex,
+                    css_converter=self.style_converter,
+                )
+
+    def _format_header(self) -> Iterable[ExcelCell]:
+        gen: Iterable[ExcelCell]
+
+        if isinstance(self.columns, MultiIndex):
+            gen = self._format_header_mi()
+        else:
+            gen = self._format_header_regular()
+
+        gen2: Iterable[ExcelCell] = ()
+
+        if self.df.index.names:
+            row = [x if x is not None else "" for x in self.df.index.names] + [
+                ""
+            ] * len(self.columns)
+            if functools.reduce(lambda x, y: x and y, (x != "" for x in row)):
+                gen2 = (
+                    ExcelCell(self.rowcounter, colindex, val, self.header_style)
+                    for colindex, val in enumerate(row)
+                )
+                self.rowcounter += 1
+        return itertools.chain(gen, gen2)
+
+    def _format_body(self) -> Iterable[ExcelCell]:
+        if isinstance(self.df.index, MultiIndex):
+            return self._format_hierarchical_rows()
+        else:
+            return self._format_regular_rows()
+
+    def _format_regular_rows(self) -> Iterable[ExcelCell]:
+        if self._has_aliases or self.header:
+            self.rowcounter += 1
+
+        # output index and index_label?
+        if self.index:
+            # check aliases
+            # if list only take first as this is not a MultiIndex
+            if self.index_label and isinstance(
+                self.index_label, (list, tuple, np.ndarray, Index)
+            ):
+                index_label = self.index_label[0]
+            # if string good to go
+            elif self.index_label and isinstance(self.index_label, str):
+                index_label = self.index_label
+            else:
+                index_label = self.df.index.names[0]
+
+            if isinstance(self.columns, MultiIndex):
+                self.rowcounter += 1
+
+            if index_label and self.header is not False:
+                yield ExcelCell(self.rowcounter - 1, 0, index_label, self.header_style)
+
+            # write index_values
+            index_values = self.df.index
+            if isinstance(self.df.index, PeriodIndex):
+                index_values = self.df.index.to_timestamp()
+
+            for idx, idxval in enumerate(index_values):
+                yield CssExcelCell(
+                    row=self.rowcounter + idx,
+                    col=0,
+                    val=idxval,
+                    style=self.header_style,
+                    css_styles=getattr(self.styler, "ctx_index", None),
+                    css_row=idx,
+                    css_col=0,
+                    css_converter=self.style_converter,
+                )
+            coloffset = 1
+        else:
+            coloffset = 0
+
+        yield from self._generate_body(coloffset)
+
+    def _format_hierarchical_rows(self) -> Iterable[ExcelCell]:
+        if self._has_aliases or self.header:
+            self.rowcounter += 1
+
+        gcolidx = 0
+
+        if self.index:
+            index_labels = self.df.index.names
+            # check for aliases
+            if self.index_label and isinstance(
+                self.index_label, (list, tuple, np.ndarray, Index)
+            ):
+                index_labels = self.index_label
+
+            # MultiIndex columns require an extra row
+            # with index names (blank if None) for
+            # unambiguous round-trip, unless not merging,
+            # in which case the names all go on one row Issue #11328
+            if isinstance(self.columns, MultiIndex) and self.merge_cells:
+                self.rowcounter += 1
+
+            # if index labels are not empty go ahead and dump
+            if com.any_not_none(*index_labels) and self.header is not False:
+                for cidx, name in enumerate(index_labels):
+                    yield ExcelCell(self.rowcounter - 1, cidx, name, self.header_style)
+
+            if self.merge_cells:
+                # Format hierarchical rows as merged cells.
+                level_strs = self.df.index._format_multi(
+                    sparsify=True, include_names=False
+                )
+                level_lengths = get_level_lengths(level_strs)
+
+                for spans, levels, level_codes in zip(
+                    level_lengths, self.df.index.levels, self.df.index.codes
+                ):
+                    values = levels.take(
+                        level_codes,
+                        allow_fill=levels._can_hold_na,
+                        fill_value=levels._na_value,
+                    )
+
+                    for i, span_val in spans.items():
+                        mergestart, mergeend = None, None
+                        if span_val > 1:
+                            mergestart = self.rowcounter + i + span_val - 1
+                            mergeend = gcolidx
+                        yield CssExcelCell(
+                            row=self.rowcounter + i,
+                            col=gcolidx,
+                            val=values[i],
+                            style=self.header_style,
+                            css_styles=getattr(self.styler, "ctx_index", None),
+                            css_row=i,
+                            css_col=gcolidx,
+                            css_converter=self.style_converter,
+                            mergestart=mergestart,
+                            mergeend=mergeend,
+                        )
+                    gcolidx += 1
+
+            else:
+                # Format hierarchical rows with non-merged values.
+                for indexcolvals in zip(*self.df.index):
+                    for idx, indexcolval in enumerate(indexcolvals):
+                        yield CssExcelCell(
+                            row=self.rowcounter + idx,
+                            col=gcolidx,
+                            val=indexcolval,
+                            style=self.header_style,
+                            css_styles=getattr(self.styler, "ctx_index", None),
+                            css_row=idx,
+                            css_col=gcolidx,
+                            css_converter=self.style_converter,
+                        )
+                    gcolidx += 1
+
+        yield from self._generate_body(gcolidx)
+
+    @property
+    def _has_aliases(self) -> bool:
+        """Whether the aliases for column names are present."""
+        return is_list_like(self.header)
+
+    def _generate_body(self, coloffset: int) -> Iterable[ExcelCell]:
+        # Write the body of the frame data series by series.
+        for colidx in range(len(self.columns)):
+            series = self.df.iloc[:, colidx]
+            for i, val in enumerate(series):
+                yield CssExcelCell(
+                    row=self.rowcounter + i,
+                    col=colidx + coloffset,
+                    val=val,
+                    style=None,
+                    css_styles=getattr(self.styler, "ctx", None),
+                    css_row=i,
+                    css_col=colidx,
+                    css_converter=self.style_converter,
+                )
+
+    def get_formatted_cells(self) -> Iterable[ExcelCell]:
+        for cell in itertools.chain(self._format_header(), self._format_body()):
+            cell.val = self._format_value(cell.val)
+            yield cell
+
+    @doc(storage_options=_shared_docs["storage_options"])
+    def write(
+        self,
+        writer: FilePath | WriteExcelBuffer | ExcelWriter,
+        sheet_name: str = "Sheet1",
+        startrow: int = 0,
+        startcol: int = 0,
+        freeze_panes: tuple[int, int] | None = None,
+        engine: str | None = None,
+        storage_options: StorageOptions | None = None,
+        engine_kwargs: dict | None = None,
+    ) -> None:
+        """
+        writer : path-like, file-like, or ExcelWriter object
+            File path or existing ExcelWriter
+        sheet_name : str, default 'Sheet1'
+            Name of sheet which will contain DataFrame
+        startrow :
+            upper left cell row to dump data frame
+        startcol :
+            upper left cell column to dump data frame
+        freeze_panes : tuple of integer (length 2), default None
+            Specifies the one-based bottommost row and rightmost column that
+            is to be frozen
+        engine : string, default None
+            write engine to use if writer is a path - you can also set this
+            via the options ``io.excel.xlsx.writer``,
+            or ``io.excel.xlsm.writer``.
+
+        {storage_options}
+
+        engine_kwargs: dict, optional
+            Arbitrary keyword arguments passed to excel engine.
+        """
+        from pandas.io.excel import ExcelWriter
+
+        num_rows, num_cols = self.df.shape
+        if num_rows > self.max_rows or num_cols > self.max_cols:
+            raise ValueError(
+                f"This sheet is too large! Your sheet size is: {num_rows}, {num_cols} "
+                f"Max sheet size is: {self.max_rows}, {self.max_cols}"
+            )
+
+        if engine_kwargs is None:
+            engine_kwargs = {}
+
+        formatted_cells = self.get_formatted_cells()
+        if isinstance(writer, ExcelWriter):
+            need_save = False
+        else:
+            writer = ExcelWriter(
+                writer,
+                engine=engine,
+                storage_options=storage_options,
+                engine_kwargs=engine_kwargs,
+            )
+            need_save = True
+
+        try:
+            writer._write_cells(
+                formatted_cells,
+                sheet_name,
+                startrow=startrow,
+                startcol=startcol,
+                freeze_panes=freeze_panes,
+            )
+        finally:
+            # make sure to close opened file handles
+            if need_save:
+                writer.close()
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/format.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/format.py
new file mode 100644
index 0000000000000000000000000000000000000000..bcbee6ce2662f00646b20eba39d0509fb228db1a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/format.py
@@ -0,0 +1,2058 @@
+"""
+Internal module for formatting output data in csv, html, xml,
+and latex files. This module also applies to display formatting.
+"""
+from __future__ import annotations
+
+from collections.abc import (
+    Generator,
+    Hashable,
+    Mapping,
+    Sequence,
+)
+from contextlib import contextmanager
+from csv import QUOTE_NONE
+from decimal import Decimal
+from functools import partial
+from io import StringIO
+import math
+import re
+from shutil import get_terminal_size
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Final,
+    cast,
+)
+
+import numpy as np
+
+from pandas._config.config import (
+    get_option,
+    set_option,
+)
+
+from pandas._libs import lib
+from pandas._libs.missing import NA
+from pandas._libs.tslibs import (
+    NaT,
+    Timedelta,
+    Timestamp,
+)
+from pandas._libs.tslibs.nattype import NaTType
+
+from pandas.core.dtypes.common import (
+    is_complex_dtype,
+    is_float,
+    is_integer,
+    is_list_like,
+    is_numeric_dtype,
+    is_scalar,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    notna,
+)
+
+from pandas.core.arrays import (
+    Categorical,
+    DatetimeArray,
+    ExtensionArray,
+    TimedeltaArray,
+)
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.base import PandasObject
+import pandas.core.common as com
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    PeriodIndex,
+    ensure_index,
+)
+from pandas.core.indexes.datetimes import DatetimeIndex
+from pandas.core.indexes.timedeltas import TimedeltaIndex
+from pandas.core.reshape.concat import concat
+
+from pandas.io.common import (
+    check_parent_directory,
+    stringify_path,
+)
+from pandas.io.formats import printing
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        Axes,
+        ColspaceArgType,
+        ColspaceType,
+        CompressionOptions,
+        FilePath,
+        FloatFormatType,
+        FormattersType,
+        IndexLabel,
+        SequenceNotStr,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+common_docstring: Final = """
+        Parameters
+        ----------
+        buf : str, Path or StringIO-like, optional, default None
+            Buffer to write to. If None, the output is returned as a string.
+        columns : array-like, optional, default None
+            The subset of columns to write. Writes all columns by default.
+        col_space : %(col_space_type)s, optional
+            %(col_space)s.
+        header : %(header_type)s, optional
+            %(header)s.
+        index : bool, optional, default True
+            Whether to print index (row) labels.
+        na_rep : str, optional, default 'NaN'
+            String representation of ``NaN`` to use.
+        formatters : list, tuple or dict of one-param. functions, optional
+            Formatter functions to apply to columns' elements by position or
+            name.
+            The result of each function must be a unicode string.
+            List/tuple must be of length equal to the number of columns.
+        float_format : one-parameter function, optional, default None
+            Formatter function to apply to columns' elements if they are
+            floats. This function must return a unicode string and will be
+            applied only to the non-``NaN`` elements, with ``NaN`` being
+            handled by ``na_rep``.
+        sparsify : bool, optional, default True
+            Set to False for a DataFrame with a hierarchical index to print
+            every multiindex key at each row.
+        index_names : bool, optional, default True
+            Prints the names of the indexes.
+        justify : str, default None
+            How to justify the column labels. If None uses the option from
+            the print configuration (controlled by set_option), 'right' out
+            of the box. Valid values are
+
+            * left
+            * right
+            * center
+            * justify
+            * justify-all
+            * start
+            * end
+            * inherit
+            * match-parent
+            * initial
+            * unset.
+        max_rows : int, optional
+            Maximum number of rows to display in the console.
+        max_cols : int, optional
+            Maximum number of columns to display in the console.
+        show_dimensions : bool, default False
+            Display DataFrame dimensions (number of rows by number of columns).
+        decimal : str, default '.'
+            Character recognized as decimal separator, e.g. ',' in Europe.
+    """
+
+VALID_JUSTIFY_PARAMETERS = (
+    "left",
+    "right",
+    "center",
+    "justify",
+    "justify-all",
+    "start",
+    "end",
+    "inherit",
+    "match-parent",
+    "initial",
+    "unset",
+)
+
+return_docstring: Final = """
+        Returns
+        -------
+        str or None
+            If buf is None, returns the result as a string. Otherwise returns
+            None.
+    """
+
+
+class SeriesFormatter:
+    """
+    Implement the main logic of Series.to_string, which underlies
+    Series.__repr__.
+    """
+
+    def __init__(
+        self,
+        series: Series,
+        *,
+        length: bool | str = True,
+        header: bool = True,
+        index: bool = True,
+        na_rep: str = "NaN",
+        name: bool = False,
+        float_format: str | None = None,
+        dtype: bool = True,
+        max_rows: int | None = None,
+        min_rows: int | None = None,
+    ) -> None:
+        self.series = series
+        self.buf = StringIO()
+        self.name = name
+        self.na_rep = na_rep
+        self.header = header
+        self.length = length
+        self.index = index
+        self.max_rows = max_rows
+        self.min_rows = min_rows
+
+        if float_format is None:
+            float_format = get_option("display.float_format")
+        self.float_format = float_format
+        self.dtype = dtype
+        self.adj = printing.get_adjustment()
+
+        self._chk_truncate()
+
+    def _chk_truncate(self) -> None:
+        self.tr_row_num: int | None
+
+        min_rows = self.min_rows
+        max_rows = self.max_rows
+        # truncation determined by max_rows, actual truncated number of rows
+        # used below by min_rows
+        is_truncated_vertically = max_rows and (len(self.series) > max_rows)
+        series = self.series
+        if is_truncated_vertically:
+            max_rows = cast(int, max_rows)
+            if min_rows:
+                # if min_rows is set (not None or 0), set max_rows to minimum
+                # of both
+                max_rows = min(min_rows, max_rows)
+            if max_rows == 1:
+                row_num = max_rows
+                series = series.iloc[:max_rows]
+            else:
+                row_num = max_rows // 2
+                series = concat((series.iloc[:row_num], series.iloc[-row_num:]))
+            self.tr_row_num = row_num
+        else:
+            self.tr_row_num = None
+        self.tr_series = series
+        self.is_truncated_vertically = is_truncated_vertically
+
+    def _get_footer(self) -> str:
+        name = self.series.name
+        footer = ""
+
+        index = self.series.index
+        if (
+            isinstance(index, (DatetimeIndex, PeriodIndex, TimedeltaIndex))
+            and index.freq is not None
+        ):
+            footer += f"Freq: {index.freqstr}"
+
+        if self.name is not False and name is not None:
+            if footer:
+                footer += ", "
+
+            series_name = printing.pprint_thing(name, escape_chars=("\t", "\r", "\n"))
+            footer += f"Name: {series_name}"
+
+        if self.length is True or (
+            self.length == "truncate" and self.is_truncated_vertically
+        ):
+            if footer:
+                footer += ", "
+            footer += f"Length: {len(self.series)}"
+
+        if self.dtype is not False and self.dtype is not None:
+            dtype_name = getattr(self.tr_series.dtype, "name", None)
+            if dtype_name:
+                if footer:
+                    footer += ", "
+                footer += f"dtype: {printing.pprint_thing(dtype_name)}"
+
+        # level infos are added to the end and in a new line, like it is done
+        # for Categoricals
+        if isinstance(self.tr_series.dtype, CategoricalDtype):
+            level_info = self.tr_series._values._get_repr_footer()
+            if footer:
+                footer += "\n"
+            footer += level_info
+
+        return str(footer)
+
+    def _get_formatted_values(self) -> list[str]:
+        return format_array(
+            self.tr_series._values,
+            None,
+            float_format=self.float_format,
+            na_rep=self.na_rep,
+            leading_space=self.index,
+        )
+
+    def to_string(self) -> str:
+        series = self.tr_series
+        footer = self._get_footer()
+
+        if len(series) == 0:
+            return f"{type(self.series).__name__}([], {footer})"
+
+        index = series.index
+        have_header = _has_names(index)
+        if isinstance(index, MultiIndex):
+            fmt_index = index._format_multi(include_names=True, sparsify=None)
+            adj = printing.get_adjustment()
+            fmt_index = adj.adjoin(2, *fmt_index).split("\n")
+        else:
+            fmt_index = index._format_flat(include_name=True)
+        fmt_values = self._get_formatted_values()
+
+        if self.is_truncated_vertically:
+            n_header_rows = 0
+            row_num = self.tr_row_num
+            row_num = cast(int, row_num)
+            width = self.adj.len(fmt_values[row_num - 1])
+            if width > 3:
+                dot_str = "..."
+            else:
+                dot_str = ".."
+            # Series uses mode=center because it has single value columns
+            # DataFrame uses mode=left
+            dot_str = self.adj.justify([dot_str], width, mode="center")[0]
+            fmt_values.insert(row_num + n_header_rows, dot_str)
+            fmt_index.insert(row_num + 1, "")
+
+        if self.index:
+            result = self.adj.adjoin(3, *[fmt_index[1:], fmt_values])
+        else:
+            result = self.adj.adjoin(3, fmt_values)
+
+        if self.header and have_header:
+            result = fmt_index[0] + "\n" + result
+
+        if footer:
+            result += "\n" + footer
+
+        return str("".join(result))
+
+
+def get_dataframe_repr_params() -> dict[str, Any]:
+    """Get the parameters used to repr(dataFrame) calls using DataFrame.to_string.
+
+    Supplying these parameters to DataFrame.to_string is equivalent to calling
+    ``repr(DataFrame)``. This is useful if you want to adjust the repr output.
+
+    .. versionadded:: 1.4.0
+
+    Example
+    -------
+    >>> import pandas as pd
+    >>>
+    >>> df = pd.DataFrame([[1, 2], [3, 4]])
+    >>> repr_params = pd.io.formats.format.get_dataframe_repr_params()
+    >>> repr(df) == df.to_string(**repr_params)
+    True
+    """
+    from pandas.io.formats import console
+
+    if get_option("display.expand_frame_repr"):
+        line_width, _ = console.get_console_size()
+    else:
+        line_width = None
+    return {
+        "max_rows": get_option("display.max_rows"),
+        "min_rows": get_option("display.min_rows"),
+        "max_cols": get_option("display.max_columns"),
+        "max_colwidth": get_option("display.max_colwidth"),
+        "show_dimensions": get_option("display.show_dimensions"),
+        "line_width": line_width,
+    }
+
+
+def get_series_repr_params() -> dict[str, Any]:
+    """Get the parameters used to repr(Series) calls using Series.to_string.
+
+    Supplying these parameters to Series.to_string is equivalent to calling
+    ``repr(series)``. This is useful if you want to adjust the series repr output.
+
+    .. versionadded:: 1.4.0
+
+    Example
+    -------
+    >>> import pandas as pd
+    >>>
+    >>> ser = pd.Series([1, 2, 3, 4])
+    >>> repr_params = pd.io.formats.format.get_series_repr_params()
+    >>> repr(ser) == ser.to_string(**repr_params)
+    True
+    """
+    width, height = get_terminal_size()
+    max_rows_opt = get_option("display.max_rows")
+    max_rows = height if max_rows_opt == 0 else max_rows_opt
+    min_rows = height if max_rows_opt == 0 else get_option("display.min_rows")
+
+    return {
+        "name": True,
+        "dtype": True,
+        "min_rows": min_rows,
+        "max_rows": max_rows,
+        "length": get_option("display.show_dimensions"),
+    }
+
+
+class DataFrameFormatter:
+    """
+    Class for processing dataframe formatting options and data.
+
+    Used by DataFrame.to_string, which backs DataFrame.__repr__.
+    """
+
+    __doc__ = __doc__ if __doc__ else ""
+    __doc__ += common_docstring + return_docstring
+
+    def __init__(
+        self,
+        frame: DataFrame,
+        columns: Axes | None = None,
+        col_space: ColspaceArgType | None = None,
+        header: bool | SequenceNotStr[str] = True,
+        index: bool = True,
+        na_rep: str = "NaN",
+        formatters: FormattersType | None = None,
+        justify: str | None = None,
+        float_format: FloatFormatType | None = None,
+        sparsify: bool | None = None,
+        index_names: bool = True,
+        max_rows: int | None = None,
+        min_rows: int | None = None,
+        max_cols: int | None = None,
+        show_dimensions: bool | str = False,
+        decimal: str = ".",
+        bold_rows: bool = False,
+        escape: bool = True,
+    ) -> None:
+        self.frame = frame
+        self.columns = self._initialize_columns(columns)
+        self.col_space = self._initialize_colspace(col_space)
+        self.header = header
+        self.index = index
+        self.na_rep = na_rep
+        self.formatters = self._initialize_formatters(formatters)
+        self.justify = self._initialize_justify(justify)
+        self.float_format = float_format
+        self.sparsify = self._initialize_sparsify(sparsify)
+        self.show_index_names = index_names
+        self.decimal = decimal
+        self.bold_rows = bold_rows
+        self.escape = escape
+        self.max_rows = max_rows
+        self.min_rows = min_rows
+        self.max_cols = max_cols
+        self.show_dimensions = show_dimensions
+
+        self.max_cols_fitted = self._calc_max_cols_fitted()
+        self.max_rows_fitted = self._calc_max_rows_fitted()
+
+        self.tr_frame = self.frame
+        self.truncate()
+        self.adj = printing.get_adjustment()
+
+    def get_strcols(self) -> list[list[str]]:
+        """
+        Render a DataFrame to a list of columns (as lists of strings).
+        """
+        strcols = self._get_strcols_without_index()
+
+        if self.index:
+            str_index = self._get_formatted_index(self.tr_frame)
+            strcols.insert(0, str_index)
+
+        return strcols
+
+    @property
+    def should_show_dimensions(self) -> bool:
+        return self.show_dimensions is True or (
+            self.show_dimensions == "truncate" and self.is_truncated
+        )
+
+    @property
+    def is_truncated(self) -> bool:
+        return bool(self.is_truncated_horizontally or self.is_truncated_vertically)
+
+    @property
+    def is_truncated_horizontally(self) -> bool:
+        return bool(self.max_cols_fitted and (len(self.columns) > self.max_cols_fitted))
+
+    @property
+    def is_truncated_vertically(self) -> bool:
+        return bool(self.max_rows_fitted and (len(self.frame) > self.max_rows_fitted))
+
+    @property
+    def dimensions_info(self) -> str:
+        return f"\n\n[{len(self.frame)} rows x {len(self.frame.columns)} columns]"
+
+    @property
+    def has_index_names(self) -> bool:
+        return _has_names(self.frame.index)
+
+    @property
+    def has_column_names(self) -> bool:
+        return _has_names(self.frame.columns)
+
+    @property
+    def show_row_idx_names(self) -> bool:
+        return all((self.has_index_names, self.index, self.show_index_names))
+
+    @property
+    def show_col_idx_names(self) -> bool:
+        return all((self.has_column_names, self.show_index_names, self.header))
+
+    @property
+    def max_rows_displayed(self) -> int:
+        return min(self.max_rows or len(self.frame), len(self.frame))
+
+    def _initialize_sparsify(self, sparsify: bool | None) -> bool:
+        if sparsify is None:
+            return get_option("display.multi_sparse")
+        return sparsify
+
+    def _initialize_formatters(
+        self, formatters: FormattersType | None
+    ) -> FormattersType:
+        if formatters is None:
+            return {}
+        elif len(self.frame.columns) == len(formatters) or isinstance(formatters, dict):
+            return formatters
+        else:
+            raise ValueError(
+                f"Formatters length({len(formatters)}) should match "
+                f"DataFrame number of columns({len(self.frame.columns)})"
+            )
+
+    def _initialize_justify(self, justify: str | None) -> str:
+        if justify is None:
+            return get_option("display.colheader_justify")
+        else:
+            return justify
+
+    def _initialize_columns(self, columns: Axes | None) -> Index:
+        if columns is not None:
+            cols = ensure_index(columns)
+            self.frame = self.frame[cols]
+            return cols
+        else:
+            return self.frame.columns
+
+    def _initialize_colspace(self, col_space: ColspaceArgType | None) -> ColspaceType:
+        result: ColspaceType
+
+        if col_space is None:
+            result = {}
+        elif isinstance(col_space, (int, str)):
+            result = {"": col_space}
+            result.update({column: col_space for column in self.frame.columns})
+        elif isinstance(col_space, Mapping):
+            for column in col_space.keys():
+                if column not in self.frame.columns and column != "":
+                    raise ValueError(
+                        f"Col_space is defined for an unknown column: {column}"
+                    )
+            result = col_space
+        else:
+            if len(self.frame.columns) != len(col_space):
+                raise ValueError(
+                    f"Col_space length({len(col_space)}) should match "
+                    f"DataFrame number of columns({len(self.frame.columns)})"
+                )
+            result = dict(zip(self.frame.columns, col_space))
+        return result
+
+    def _calc_max_cols_fitted(self) -> int | None:
+        """Number of columns fitting the screen."""
+        if not self._is_in_terminal():
+            return self.max_cols
+
+        width, _ = get_terminal_size()
+        if self._is_screen_narrow(width):
+            return width
+        else:
+            return self.max_cols
+
+    def _calc_max_rows_fitted(self) -> int | None:
+        """Number of rows with data fitting the screen."""
+        max_rows: int | None
+
+        if self._is_in_terminal():
+            _, height = get_terminal_size()
+            if self.max_rows == 0:
+                # rows available to fill with actual data
+                return height - self._get_number_of_auxiliary_rows()
+
+            if self._is_screen_short(height):
+                max_rows = height
+            else:
+                max_rows = self.max_rows
+        else:
+            max_rows = self.max_rows
+
+        return self._adjust_max_rows(max_rows)
+
+    def _adjust_max_rows(self, max_rows: int | None) -> int | None:
+        """Adjust max_rows using display logic.
+
+        See description here:
+        https://pandas.pydata.org/docs/dev/user_guide/options.html#frequently-used-options
+
+        GH #37359
+        """
+        if max_rows:
+            if (len(self.frame) > max_rows) and self.min_rows:
+                # if truncated, set max_rows showed to min_rows
+                max_rows = min(self.min_rows, max_rows)
+        return max_rows
+
+    def _is_in_terminal(self) -> bool:
+        """Check if the output is to be shown in terminal."""
+        return bool(self.max_cols == 0 or self.max_rows == 0)
+
+    def _is_screen_narrow(self, max_width) -> bool:
+        return bool(self.max_cols == 0 and len(self.frame.columns) > max_width)
+
+    def _is_screen_short(self, max_height) -> bool:
+        return bool(self.max_rows == 0 and len(self.frame) > max_height)
+
+    def _get_number_of_auxiliary_rows(self) -> int:
+        """Get number of rows occupied by prompt, dots and dimension info."""
+        dot_row = 1
+        prompt_row = 1
+        num_rows = dot_row + prompt_row
+
+        if self.show_dimensions:
+            num_rows += len(self.dimensions_info.splitlines())
+
+        if self.header:
+            num_rows += 1
+
+        return num_rows
+
+    def truncate(self) -> None:
+        """
+        Check whether the frame should be truncated. If so, slice the frame up.
+        """
+        if self.is_truncated_horizontally:
+            self._truncate_horizontally()
+
+        if self.is_truncated_vertically:
+            self._truncate_vertically()
+
+    def _truncate_horizontally(self) -> None:
+        """Remove columns, which are not to be displayed and adjust formatters.
+
+        Attributes affected:
+            - tr_frame
+            - formatters
+            - tr_col_num
+        """
+        assert self.max_cols_fitted is not None
+        col_num = self.max_cols_fitted // 2
+        if col_num >= 1:
+            left = self.tr_frame.iloc[:, :col_num]
+            right = self.tr_frame.iloc[:, -col_num:]
+            self.tr_frame = concat((left, right), axis=1)
+
+            # truncate formatter
+            if isinstance(self.formatters, (list, tuple)):
+                self.formatters = [
+                    *self.formatters[:col_num],
+                    *self.formatters[-col_num:],
+                ]
+        else:
+            col_num = cast(int, self.max_cols)
+            self.tr_frame = self.tr_frame.iloc[:, :col_num]
+        self.tr_col_num = col_num
+
+    def _truncate_vertically(self) -> None:
+        """Remove rows, which are not to be displayed.
+
+        Attributes affected:
+            - tr_frame
+            - tr_row_num
+        """
+        assert self.max_rows_fitted is not None
+        row_num = self.max_rows_fitted // 2
+        if row_num >= 1:
+            _len = len(self.tr_frame)
+            _slice = np.hstack([np.arange(row_num), np.arange(_len - row_num, _len)])
+            self.tr_frame = self.tr_frame.iloc[_slice]
+        else:
+            row_num = cast(int, self.max_rows)
+            self.tr_frame = self.tr_frame.iloc[:row_num, :]
+        self.tr_row_num = row_num
+
+    def _get_strcols_without_index(self) -> list[list[str]]:
+        strcols: list[list[str]] = []
+
+        if not is_list_like(self.header) and not self.header:
+            for i, c in enumerate(self.tr_frame):
+                fmt_values = self.format_col(i)
+                fmt_values = _make_fixed_width(
+                    strings=fmt_values,
+                    justify=self.justify,
+                    minimum=int(self.col_space.get(c, 0)),
+                    adj=self.adj,
+                )
+                strcols.append(fmt_values)
+            return strcols
+
+        if is_list_like(self.header):
+            # cast here since can't be bool if is_list_like
+            self.header = cast(list[str], self.header)
+            if len(self.header) != len(self.columns):
+                raise ValueError(
+                    f"Writing {len(self.columns)} cols "
+                    f"but got {len(self.header)} aliases"
+                )
+            str_columns = [[label] for label in self.header]
+        else:
+            str_columns = self._get_formatted_column_labels(self.tr_frame)
+
+        if self.show_row_idx_names:
+            for x in str_columns:
+                x.append("")
+
+        for i, c in enumerate(self.tr_frame):
+            cheader = str_columns[i]
+            header_colwidth = max(
+                int(self.col_space.get(c, 0)), *(self.adj.len(x) for x in cheader)
+            )
+            fmt_values = self.format_col(i)
+            fmt_values = _make_fixed_width(
+                fmt_values, self.justify, minimum=header_colwidth, adj=self.adj
+            )
+
+            max_len = max(*(self.adj.len(x) for x in fmt_values), header_colwidth)
+            cheader = self.adj.justify(cheader, max_len, mode=self.justify)
+            strcols.append(cheader + fmt_values)
+
+        return strcols
+
+    def format_col(self, i: int) -> list[str]:
+        frame = self.tr_frame
+        formatter = self._get_formatter(i)
+        return format_array(
+            frame.iloc[:, i]._values,
+            formatter,
+            float_format=self.float_format,
+            na_rep=self.na_rep,
+            space=self.col_space.get(frame.columns[i]),
+            decimal=self.decimal,
+            leading_space=self.index,
+        )
+
+    def _get_formatter(self, i: str | int) -> Callable | None:
+        if isinstance(self.formatters, (list, tuple)):
+            if is_integer(i):
+                i = cast(int, i)
+                return self.formatters[i]
+            else:
+                return None
+        else:
+            if is_integer(i) and i not in self.columns:
+                i = self.columns[i]
+            return self.formatters.get(i, None)
+
+    def _get_formatted_column_labels(self, frame: DataFrame) -> list[list[str]]:
+        from pandas.core.indexes.multi import sparsify_labels
+
+        columns = frame.columns
+
+        if isinstance(columns, MultiIndex):
+            fmt_columns = columns._format_multi(sparsify=False, include_names=False)
+            fmt_columns = list(zip(*fmt_columns))
+            dtypes = self.frame.dtypes._values
+
+            # if we have a Float level, they don't use leading space at all
+            restrict_formatting = any(level.is_floating for level in columns.levels)
+            need_leadsp = dict(zip(fmt_columns, map(is_numeric_dtype, dtypes)))
+
+            def space_format(x, y):
+                if (
+                    y not in self.formatters
+                    and need_leadsp[x]
+                    and not restrict_formatting
+                ):
+                    return " " + y
+                return y
+
+            str_columns_tuple = list(
+                zip(*([space_format(x, y) for y in x] for x in fmt_columns))
+            )
+            if self.sparsify and len(str_columns_tuple):
+                str_columns_tuple = sparsify_labels(str_columns_tuple)
+
+            str_columns = [list(x) for x in zip(*str_columns_tuple)]
+        else:
+            fmt_columns = columns._format_flat(include_name=False)
+            dtypes = self.frame.dtypes
+            need_leadsp = dict(zip(fmt_columns, map(is_numeric_dtype, dtypes)))
+            str_columns = [
+                [" " + x if not self._get_formatter(i) and need_leadsp[x] else x]
+                for i, x in enumerate(fmt_columns)
+            ]
+        # self.str_columns = str_columns
+        return str_columns
+
+    def _get_formatted_index(self, frame: DataFrame) -> list[str]:
+        # Note: this is only used by to_string() and to_latex(), not by
+        # to_html(). so safe to cast col_space here.
+        col_space = {k: cast(int, v) for k, v in self.col_space.items()}
+        index = frame.index
+        columns = frame.columns
+        fmt = self._get_formatter("__index__")
+
+        if isinstance(index, MultiIndex):
+            fmt_index = index._format_multi(
+                sparsify=self.sparsify,
+                include_names=self.show_row_idx_names,
+                formatter=fmt,
+            )
+        else:
+            fmt_index = [
+                index._format_flat(include_name=self.show_row_idx_names, formatter=fmt)
+            ]
+
+        fmt_index = [
+            tuple(
+                _make_fixed_width(
+                    list(x), justify="left", minimum=col_space.get("", 0), adj=self.adj
+                )
+            )
+            for x in fmt_index
+        ]
+
+        adjoined = self.adj.adjoin(1, *fmt_index).split("\n")
+
+        # empty space for columns
+        if self.show_col_idx_names:
+            col_header = [str(x) for x in self._get_column_name_list()]
+        else:
+            col_header = [""] * columns.nlevels
+
+        if self.header:
+            return col_header + adjoined
+        else:
+            return adjoined
+
+    def _get_column_name_list(self) -> list[Hashable]:
+        names: list[Hashable] = []
+        columns = self.frame.columns
+        if isinstance(columns, MultiIndex):
+            names.extend("" if name is None else name for name in columns.names)
+        else:
+            names.append("" if columns.name is None else columns.name)
+        return names
+
+
+class DataFrameRenderer:
+    """Class for creating dataframe output in multiple formats.
+
+    Called in pandas.core.generic.NDFrame:
+        - to_csv
+        - to_latex
+
+    Called in pandas.core.frame.DataFrame:
+        - to_html
+        - to_string
+
+    Parameters
+    ----------
+    fmt : DataFrameFormatter
+        Formatter with the formatting options.
+    """
+
+    def __init__(self, fmt: DataFrameFormatter) -> None:
+        self.fmt = fmt
+
+    def to_html(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        encoding: str | None = None,
+        classes: str | list | tuple | None = None,
+        notebook: bool = False,
+        border: int | bool | None = None,
+        table_id: str | None = None,
+        render_links: bool = False,
+    ) -> str | None:
+        """
+        Render a DataFrame to a html table.
+
+        Parameters
+        ----------
+        buf : str, path object, file-like object, or None, default None
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a string ``write()`` function. If None, the result is
+            returned as a string.
+        encoding : str, default “utf-8”
+            Set character encoding.
+        classes : str or list-like
+            classes to include in the `class` attribute of the opening
+            ```` tag, in addition to the default "dataframe".
+        notebook : {True, False}, optional, default False
+            Whether the generated HTML is for IPython Notebook.
+        border : int
+            A ``border=border`` attribute is included in the opening
+            ``
`` tag. Default ``pd.options.display.html.border``.
+        table_id : str, optional
+            A css id is included in the opening `
` tag if specified.
+        render_links : bool, default False
+            Convert URLs to HTML links.
+        """
+        from pandas.io.formats.html import (
+            HTMLFormatter,
+            NotebookFormatter,
+        )
+
+        Klass = NotebookFormatter if notebook else HTMLFormatter
+
+        html_formatter = Klass(
+            self.fmt,
+            classes=classes,
+            border=border,
+            table_id=table_id,
+            render_links=render_links,
+        )
+        string = html_formatter.to_string()
+        return save_to_buffer(string, buf=buf, encoding=encoding)
+
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        encoding: str | None = None,
+        line_width: int | None = None,
+    ) -> str | None:
+        """
+        Render a DataFrame to a console-friendly tabular output.
+
+        Parameters
+        ----------
+        buf : str, path object, file-like object, or None, default None
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a string ``write()`` function. If None, the result is
+            returned as a string.
+        encoding: str, default “utf-8”
+            Set character encoding.
+        line_width : int, optional
+            Width to wrap a line in characters.
+        """
+        from pandas.io.formats.string import StringFormatter
+
+        string_formatter = StringFormatter(self.fmt, line_width=line_width)
+        string = string_formatter.to_string()
+        return save_to_buffer(string, buf=buf, encoding=encoding)
+
+    def to_csv(
+        self,
+        path_or_buf: FilePath | WriteBuffer[bytes] | WriteBuffer[str] | None = None,
+        encoding: str | None = None,
+        sep: str = ",",
+        columns: Sequence[Hashable] | None = None,
+        index_label: IndexLabel | None = None,
+        mode: str = "w",
+        compression: CompressionOptions = "infer",
+        quoting: int | None = None,
+        quotechar: str = '"',
+        lineterminator: str | None = None,
+        chunksize: int | None = None,
+        date_format: str | None = None,
+        doublequote: bool = True,
+        escapechar: str | None = None,
+        errors: str = "strict",
+        storage_options: StorageOptions | None = None,
+    ) -> str | None:
+        """
+        Render dataframe as comma-separated file.
+        """
+        from pandas.io.formats.csvs import CSVFormatter
+
+        if path_or_buf is None:
+            created_buffer = True
+            path_or_buf = StringIO()
+        else:
+            created_buffer = False
+
+        csv_formatter = CSVFormatter(
+            path_or_buf=path_or_buf,
+            lineterminator=lineterminator,
+            sep=sep,
+            encoding=encoding,
+            errors=errors,
+            compression=compression,
+            quoting=quoting,
+            cols=columns,
+            index_label=index_label,
+            mode=mode,
+            chunksize=chunksize,
+            quotechar=quotechar,
+            date_format=date_format,
+            doublequote=doublequote,
+            escapechar=escapechar,
+            storage_options=storage_options,
+            formatter=self.fmt,
+        )
+        csv_formatter.save()
+
+        if created_buffer:
+            assert isinstance(path_or_buf, StringIO)
+            content = path_or_buf.getvalue()
+            path_or_buf.close()
+            return content
+
+        return None
+
+
+def save_to_buffer(
+    string: str,
+    buf: FilePath | WriteBuffer[str] | None = None,
+    encoding: str | None = None,
+) -> str | None:
+    """
+    Perform serialization. Write to buf or return as string if buf is None.
+    """
+    with _get_buffer(buf, encoding=encoding) as fd:
+        fd.write(string)
+        if buf is None:
+            # error: "WriteBuffer[str]" has no attribute "getvalue"
+            return fd.getvalue()  # type: ignore[attr-defined]
+        return None
+
+
+@contextmanager
+def _get_buffer(
+    buf: FilePath | WriteBuffer[str] | None, encoding: str | None = None
+) -> Generator[WriteBuffer[str], None, None] | Generator[StringIO, None, None]:
+    """
+    Context manager to open, yield and close buffer for filenames or Path-like
+    objects, otherwise yield buf unchanged.
+    """
+    if buf is not None:
+        buf = stringify_path(buf)
+    else:
+        buf = StringIO()
+
+    if encoding is None:
+        encoding = "utf-8"
+    elif not isinstance(buf, str):
+        raise ValueError("buf is not a file name and encoding is specified.")
+
+    if hasattr(buf, "write"):
+        # Incompatible types in "yield" (actual type "Union[str, WriteBuffer[str],
+        # StringIO]", expected type "Union[WriteBuffer[str], StringIO]")
+        yield buf  # type: ignore[misc]
+    elif isinstance(buf, str):
+        check_parent_directory(str(buf))
+        with open(buf, "w", encoding=encoding, newline="") as f:
+            # GH#30034 open instead of codecs.open prevents a file leak
+            #  if we have an invalid encoding argument.
+            # newline="" is needed to roundtrip correctly on
+            #  windows test_to_latex_filename
+            yield f
+    else:
+        raise TypeError("buf is not a file name and it has no write method")
+
+
+# ----------------------------------------------------------------------
+# Array formatters
+
+
+def format_array(
+    values: ArrayLike,
+    formatter: Callable | None,
+    float_format: FloatFormatType | None = None,
+    na_rep: str = "NaN",
+    digits: int | None = None,
+    space: str | int | None = None,
+    justify: str = "right",
+    decimal: str = ".",
+    leading_space: bool | None = True,
+    quoting: int | None = None,
+    fallback_formatter: Callable | None = None,
+) -> list[str]:
+    """
+    Format an array for printing.
+
+    Parameters
+    ----------
+    values : np.ndarray or ExtensionArray
+    formatter
+    float_format
+    na_rep
+    digits
+    space
+    justify
+    decimal
+    leading_space : bool, optional, default True
+        Whether the array should be formatted with a leading space.
+        When an array as a column of a Series or DataFrame, we do want
+        the leading space to pad between columns.
+
+        When formatting an Index subclass
+        (e.g. IntervalIndex._get_values_for_csv), we don't want the
+        leading space since it should be left-aligned.
+    fallback_formatter
+
+    Returns
+    -------
+    List[str]
+    """
+    fmt_klass: type[_GenericArrayFormatter]
+    if lib.is_np_dtype(values.dtype, "M"):
+        fmt_klass = _Datetime64Formatter
+        values = cast(DatetimeArray, values)
+    elif isinstance(values.dtype, DatetimeTZDtype):
+        fmt_klass = _Datetime64TZFormatter
+        values = cast(DatetimeArray, values)
+    elif lib.is_np_dtype(values.dtype, "m"):
+        fmt_klass = _Timedelta64Formatter
+        values = cast(TimedeltaArray, values)
+    elif isinstance(values.dtype, ExtensionDtype):
+        fmt_klass = _ExtensionArrayFormatter
+    elif lib.is_np_dtype(values.dtype, "fc"):
+        fmt_klass = FloatArrayFormatter
+    elif lib.is_np_dtype(values.dtype, "iu"):
+        fmt_klass = _IntArrayFormatter
+    else:
+        fmt_klass = _GenericArrayFormatter
+
+    if space is None:
+        space = 12
+
+    if float_format is None:
+        float_format = get_option("display.float_format")
+
+    if digits is None:
+        digits = get_option("display.precision")
+
+    fmt_obj = fmt_klass(
+        values,
+        digits=digits,
+        na_rep=na_rep,
+        float_format=float_format,
+        formatter=formatter,
+        space=space,
+        justify=justify,
+        decimal=decimal,
+        leading_space=leading_space,
+        quoting=quoting,
+        fallback_formatter=fallback_formatter,
+    )
+
+    return fmt_obj.get_result()
+
+
+class _GenericArrayFormatter:
+    def __init__(
+        self,
+        values: ArrayLike,
+        digits: int = 7,
+        formatter: Callable | None = None,
+        na_rep: str = "NaN",
+        space: str | int = 12,
+        float_format: FloatFormatType | None = None,
+        justify: str = "right",
+        decimal: str = ".",
+        quoting: int | None = None,
+        fixed_width: bool = True,
+        leading_space: bool | None = True,
+        fallback_formatter: Callable | None = None,
+    ) -> None:
+        self.values = values
+        self.digits = digits
+        self.na_rep = na_rep
+        self.space = space
+        self.formatter = formatter
+        self.float_format = float_format
+        self.justify = justify
+        self.decimal = decimal
+        self.quoting = quoting
+        self.fixed_width = fixed_width
+        self.leading_space = leading_space
+        self.fallback_formatter = fallback_formatter
+
+    def get_result(self) -> list[str]:
+        fmt_values = self._format_strings()
+        return _make_fixed_width(fmt_values, self.justify)
+
+    def _format_strings(self) -> list[str]:
+        if self.float_format is None:
+            float_format = get_option("display.float_format")
+            if float_format is None:
+                precision = get_option("display.precision")
+                float_format = lambda x: _trim_zeros_single_float(
+                    f"{x: .{precision:d}f}"
+                )
+        else:
+            float_format = self.float_format
+
+        if self.formatter is not None:
+            formatter = self.formatter
+        elif self.fallback_formatter is not None:
+            formatter = self.fallback_formatter
+        else:
+            quote_strings = self.quoting is not None and self.quoting != QUOTE_NONE
+            formatter = partial(
+                printing.pprint_thing,
+                escape_chars=("\t", "\r", "\n"),
+                quote_strings=quote_strings,
+            )
+
+        def _format(x):
+            if self.na_rep is not None and is_scalar(x) and isna(x):
+                if x is None:
+                    return "None"
+                elif x is NA:
+                    return str(NA)
+                elif lib.is_float(x) and np.isinf(x):
+                    # TODO(3.0): this will be unreachable when use_inf_as_na
+                    #  deprecation is enforced
+                    return str(x)
+                elif x is NaT or isinstance(x, (np.datetime64, np.timedelta64)):
+                    return "NaT"
+                return self.na_rep
+            elif isinstance(x, PandasObject):
+                return str(x)
+            elif isinstance(x, StringDtype) and x.na_value is NA:
+                return repr(x)
+            else:
+                # object dtype
+                return str(formatter(x))
+
+        vals = self.values
+        if not isinstance(vals, np.ndarray):
+            raise TypeError(
+                "ExtensionArray formatting should use _ExtensionArrayFormatter"
+            )
+        inferred = lib.map_infer(vals, is_float)
+        is_float_type = (
+            inferred
+            # vals may have 2 or more dimensions
+            & np.all(notna(vals), axis=tuple(range(1, len(vals.shape))))
+        )
+        leading_space = self.leading_space
+        if leading_space is None:
+            leading_space = is_float_type.any()
+
+        fmt_values = []
+        for i, v in enumerate(vals):
+            if (not is_float_type[i] or self.formatter is not None) and leading_space:
+                fmt_values.append(f" {_format(v)}")
+            elif is_float_type[i]:
+                fmt_values.append(float_format(v))
+            else:
+                if leading_space is False:
+                    # False specifically, so that the default is
+                    # to include a space if we get here.
+                    tpl = "{v}"
+                else:
+                    tpl = " {v}"
+                fmt_values.append(tpl.format(v=_format(v)))
+
+        return fmt_values
+
+
+class FloatArrayFormatter(_GenericArrayFormatter):
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+        # float_format is expected to be a string
+        # formatter should be used to pass a function
+        if self.float_format is not None and self.formatter is None:
+            # GH21625, GH22270
+            self.fixed_width = False
+            if callable(self.float_format):
+                self.formatter = self.float_format
+                self.float_format = None
+
+    def _value_formatter(
+        self,
+        float_format: FloatFormatType | None = None,
+        threshold: float | None = None,
+    ) -> Callable:
+        """Returns a function to be applied on each value to format it"""
+        # the float_format parameter supersedes self.float_format
+        if float_format is None:
+            float_format = self.float_format
+
+        # we are going to compose different functions, to first convert to
+        # a string, then replace the decimal symbol, and finally chop according
+        # to the threshold
+
+        # when there is no float_format, we use str instead of '%g'
+        # because str(0.0) = '0.0' while '%g' % 0.0 = '0'
+        if float_format:
+
+            def base_formatter(v):
+                assert float_format is not None  # for mypy
+                # error: "str" not callable
+                # error: Unexpected keyword argument "value" for "__call__" of
+                # "EngFormatter"
+                return (
+                    float_format(value=v)  # type: ignore[operator,call-arg]
+                    if notna(v)
+                    else self.na_rep
+                )
+
+        else:
+
+            def base_formatter(v):
+                return str(v) if notna(v) else self.na_rep
+
+        if self.decimal != ".":
+
+            def decimal_formatter(v):
+                return base_formatter(v).replace(".", self.decimal, 1)
+
+        else:
+            decimal_formatter = base_formatter
+
+        if threshold is None:
+            return decimal_formatter
+
+        def formatter(value):
+            if notna(value):
+                if abs(value) > threshold:
+                    return decimal_formatter(value)
+                else:
+                    return decimal_formatter(0.0)
+            else:
+                return self.na_rep
+
+        return formatter
+
+    def get_result_as_array(self) -> np.ndarray:
+        """
+        Returns the float values converted into strings using
+        the parameters given at initialisation, as a numpy array
+        """
+
+        def format_with_na_rep(values: ArrayLike, formatter: Callable, na_rep: str):
+            mask = isna(values)
+            formatted = np.array(
+                [
+                    formatter(val) if not m else na_rep
+                    for val, m in zip(values.ravel(), mask.ravel())
+                ]
+            ).reshape(values.shape)
+            return formatted
+
+        def format_complex_with_na_rep(
+            values: ArrayLike, formatter: Callable, na_rep: str
+        ):
+            real_values = np.real(values).ravel()  # type: ignore[arg-type]
+            imag_values = np.imag(values).ravel()  # type: ignore[arg-type]
+            real_mask, imag_mask = isna(real_values), isna(imag_values)
+            formatted_lst = []
+            for val, real_val, imag_val, re_isna, im_isna in zip(
+                values.ravel(),
+                real_values,
+                imag_values,
+                real_mask,
+                imag_mask,
+            ):
+                if not re_isna and not im_isna:
+                    formatted_lst.append(formatter(val))
+                elif not re_isna:  # xxx+nanj
+                    formatted_lst.append(f"{formatter(real_val)}+{na_rep}j")
+                elif not im_isna:  # nan[+/-]xxxj
+                    # The imaginary part may either start with a "-" or a space
+                    imag_formatted = formatter(imag_val).strip()
+                    if imag_formatted.startswith("-"):
+                        formatted_lst.append(f"{na_rep}{imag_formatted}j")
+                    else:
+                        formatted_lst.append(f"{na_rep}+{imag_formatted}j")
+                else:  # nan+nanj
+                    formatted_lst.append(f"{na_rep}+{na_rep}j")
+            return np.array(formatted_lst).reshape(values.shape)
+
+        if self.formatter is not None:
+            return format_with_na_rep(self.values, self.formatter, self.na_rep)
+
+        if self.fixed_width:
+            threshold = get_option("display.chop_threshold")
+        else:
+            threshold = None
+
+        # if we have a fixed_width, we'll need to try different float_format
+        def format_values_with(float_format):
+            formatter = self._value_formatter(float_format, threshold)
+
+            # default formatter leaves a space to the left when formatting
+            # floats, must be consistent for left-justifying NaNs (GH #25061)
+            na_rep = " " + self.na_rep if self.justify == "left" else self.na_rep
+
+            # different formatting strategies for complex and non-complex data
+            # need to distinguish complex and float NaNs (GH #53762)
+            values = self.values
+            is_complex = is_complex_dtype(values)
+
+            # separate the wheat from the chaff
+            if is_complex:
+                values = format_complex_with_na_rep(values, formatter, na_rep)
+            else:
+                values = format_with_na_rep(values, formatter, na_rep)
+
+            if self.fixed_width:
+                if is_complex:
+                    result = _trim_zeros_complex(values, self.decimal)
+                else:
+                    result = _trim_zeros_float(values, self.decimal)
+                return np.asarray(result, dtype="object")
+
+            return values
+
+        # There is a special default string when we are fixed-width
+        # The default is otherwise to use str instead of a formatting string
+        float_format: FloatFormatType | None
+        if self.float_format is None:
+            if self.fixed_width:
+                if self.leading_space is True:
+                    fmt_str = "{value: .{digits:d}f}"
+                else:
+                    fmt_str = "{value:.{digits:d}f}"
+                float_format = partial(fmt_str.format, digits=self.digits)
+            else:
+                float_format = self.float_format
+        else:
+            float_format = lambda value: self.float_format % value
+
+        formatted_values = format_values_with(float_format)
+
+        if not self.fixed_width:
+            return formatted_values
+
+        # we need do convert to engineering format if some values are too small
+        # and would appear as 0, or if some values are too big and take too
+        # much space
+
+        if len(formatted_values) > 0:
+            maxlen = max(len(x) for x in formatted_values)
+            too_long = maxlen > self.digits + 6
+        else:
+            too_long = False
+
+        abs_vals = np.abs(self.values)
+        # this is pretty arbitrary for now
+        # large values: more that 8 characters including decimal symbol
+        # and first digit, hence > 1e6
+        has_large_values = (abs_vals > 1e6).any()
+        has_small_values = ((abs_vals < 10 ** (-self.digits)) & (abs_vals > 0)).any()
+
+        if has_small_values or (too_long and has_large_values):
+            if self.leading_space is True:
+                fmt_str = "{value: .{digits:d}e}"
+            else:
+                fmt_str = "{value:.{digits:d}e}"
+            float_format = partial(fmt_str.format, digits=self.digits)
+            formatted_values = format_values_with(float_format)
+
+        return formatted_values
+
+    def _format_strings(self) -> list[str]:
+        return list(self.get_result_as_array())
+
+
+class _IntArrayFormatter(_GenericArrayFormatter):
+    def _format_strings(self) -> list[str]:
+        if self.leading_space is False:
+            formatter_str = lambda x: f"{x:d}".format(x=x)
+        else:
+            formatter_str = lambda x: f"{x: d}".format(x=x)
+        formatter = self.formatter or formatter_str
+        fmt_values = [formatter(x) for x in self.values]
+        return fmt_values
+
+
+class _Datetime64Formatter(_GenericArrayFormatter):
+    values: DatetimeArray
+
+    def __init__(
+        self,
+        values: DatetimeArray,
+        nat_rep: str = "NaT",
+        date_format: None = None,
+        **kwargs,
+    ) -> None:
+        super().__init__(values, **kwargs)
+        self.nat_rep = nat_rep
+        self.date_format = date_format
+
+    def _format_strings(self) -> list[str]:
+        """we by definition have DO NOT have a TZ"""
+        values = self.values
+
+        if self.formatter is not None:
+            return [self.formatter(x) for x in values]
+
+        fmt_values = values._format_native_types(
+            na_rep=self.nat_rep, date_format=self.date_format
+        )
+        return fmt_values.tolist()
+
+
+class _ExtensionArrayFormatter(_GenericArrayFormatter):
+    values: ExtensionArray
+
+    def _format_strings(self) -> list[str]:
+        values = self.values
+
+        formatter = self.formatter
+        fallback_formatter = None
+        if formatter is None:
+            fallback_formatter = values._formatter(boxed=True)
+
+        if isinstance(values, Categorical):
+            # Categorical is special for now, so that we can preserve tzinfo
+            array = values._internal_get_values()
+        else:
+            array = np.asarray(values, dtype=object)
+
+        fmt_values = format_array(
+            array,
+            formatter,
+            float_format=self.float_format,
+            na_rep=self.na_rep,
+            digits=self.digits,
+            space=self.space,
+            justify=self.justify,
+            decimal=self.decimal,
+            leading_space=self.leading_space,
+            quoting=self.quoting,
+            fallback_formatter=fallback_formatter,
+        )
+        return fmt_values
+
+
+def format_percentiles(
+    percentiles: (np.ndarray | Sequence[float]),
+) -> list[str]:
+    """
+    Outputs rounded and formatted percentiles.
+
+    Parameters
+    ----------
+    percentiles : list-like, containing floats from interval [0,1]
+
+    Returns
+    -------
+    formatted : list of strings
+
+    Notes
+    -----
+    Rounding precision is chosen so that: (1) if any two elements of
+    ``percentiles`` differ, they remain different after rounding
+    (2) no entry is *rounded* to 0% or 100%.
+    Any non-integer is always rounded to at least 1 decimal place.
+
+    Examples
+    --------
+    Keeps all entries different after rounding:
+
+    >>> format_percentiles([0.01999, 0.02001, 0.5, 0.666666, 0.9999])
+    ['1.999%', '2.001%', '50%', '66.667%', '99.99%']
+
+    No element is rounded to 0% or 100% (unless already equal to it).
+    Duplicates are allowed:
+
+    >>> format_percentiles([0, 0.5, 0.02001, 0.5, 0.666666, 0.9999])
+    ['0%', '50%', '2.0%', '50%', '66.67%', '99.99%']
+    """
+    percentiles = np.asarray(percentiles)
+
+    # It checks for np.nan as well
+    if (
+        not is_numeric_dtype(percentiles)
+        or not np.all(percentiles >= 0)
+        or not np.all(percentiles <= 1)
+    ):
+        raise ValueError("percentiles should all be in the interval [0,1]")
+
+    percentiles = 100 * percentiles
+    prec = get_precision(percentiles)
+    percentiles_round_type = percentiles.round(prec).astype(int)
+
+    int_idx = np.isclose(percentiles_round_type, percentiles)
+
+    if np.all(int_idx):
+        out = percentiles_round_type.astype(str)
+        return [i + "%" for i in out]
+
+    unique_pcts = np.unique(percentiles)
+    prec = get_precision(unique_pcts)
+    out = np.empty_like(percentiles, dtype=object)
+    out[int_idx] = percentiles[int_idx].round().astype(int).astype(str)
+
+    out[~int_idx] = percentiles[~int_idx].round(prec).astype(str)
+    return [i + "%" for i in out]
+
+
+def get_precision(array: np.ndarray | Sequence[float]) -> int:
+    to_begin = array[0] if array[0] > 0 else None
+    to_end = 100 - array[-1] if array[-1] < 100 else None
+    diff = np.ediff1d(array, to_begin=to_begin, to_end=to_end)
+    diff = abs(diff)
+    prec = -np.floor(np.log10(np.min(diff))).astype(int)
+    prec = max(1, prec)
+    return prec
+
+
+def _format_datetime64(x: NaTType | Timestamp, nat_rep: str = "NaT") -> str:
+    if x is NaT:
+        return nat_rep
+
+    # Timestamp.__str__ falls back to datetime.datetime.__str__ = isoformat(sep=' ')
+    # so it already uses string formatting rather than strftime (faster).
+    return str(x)
+
+
+def _format_datetime64_dateonly(
+    x: NaTType | Timestamp,
+    nat_rep: str = "NaT",
+    date_format: str | None = None,
+) -> str:
+    if isinstance(x, NaTType):
+        return nat_rep
+
+    if date_format:
+        return x.strftime(date_format)
+    else:
+        # Timestamp._date_repr relies on string formatting (faster than strftime)
+        return x._date_repr
+
+
+def get_format_datetime64(
+    is_dates_only: bool, nat_rep: str = "NaT", date_format: str | None = None
+) -> Callable:
+    """Return a formatter callable taking a datetime64 as input and providing
+    a string as output"""
+
+    if is_dates_only:
+        return lambda x: _format_datetime64_dateonly(
+            x, nat_rep=nat_rep, date_format=date_format
+        )
+    else:
+        return lambda x: _format_datetime64(x, nat_rep=nat_rep)
+
+
+class _Datetime64TZFormatter(_Datetime64Formatter):
+    values: DatetimeArray
+
+    def _format_strings(self) -> list[str]:
+        """we by definition have a TZ"""
+        ido = self.values._is_dates_only
+        values = self.values.astype(object)
+        formatter = self.formatter or get_format_datetime64(
+            ido, date_format=self.date_format
+        )
+        fmt_values = [formatter(x) for x in values]
+
+        return fmt_values
+
+
+class _Timedelta64Formatter(_GenericArrayFormatter):
+    values: TimedeltaArray
+
+    def __init__(
+        self,
+        values: TimedeltaArray,
+        nat_rep: str = "NaT",
+        **kwargs,
+    ) -> None:
+        # TODO: nat_rep is never passed, na_rep is.
+        super().__init__(values, **kwargs)
+        self.nat_rep = nat_rep
+
+    def _format_strings(self) -> list[str]:
+        formatter = self.formatter or get_format_timedelta64(
+            self.values, nat_rep=self.nat_rep, box=False
+        )
+        return [formatter(x) for x in self.values]
+
+
+def get_format_timedelta64(
+    values: TimedeltaArray,
+    nat_rep: str | float = "NaT",
+    box: bool = False,
+) -> Callable:
+    """
+    Return a formatter function for a range of timedeltas.
+    These will all have the same format argument
+
+    If box, then show the return in quotes
+    """
+    even_days = values._is_dates_only
+
+    if even_days:
+        format = None
+    else:
+        format = "long"
+
+    def _formatter(x):
+        if x is None or (is_scalar(x) and isna(x)):
+            return nat_rep
+
+        if not isinstance(x, Timedelta):
+            x = Timedelta(x)
+
+        # Timedelta._repr_base uses string formatting (faster than strftime)
+        result = x._repr_base(format=format)
+        if box:
+            result = f"'{result}'"
+        return result
+
+    return _formatter
+
+
+def _make_fixed_width(
+    strings: list[str],
+    justify: str = "right",
+    minimum: int | None = None,
+    adj: printing._TextAdjustment | None = None,
+) -> list[str]:
+    if len(strings) == 0 or justify == "all":
+        return strings
+
+    if adj is None:
+        adjustment = printing.get_adjustment()
+    else:
+        adjustment = adj
+
+    max_len = max(adjustment.len(x) for x in strings)
+
+    if minimum is not None:
+        max_len = max(minimum, max_len)
+
+    conf_max = get_option("display.max_colwidth")
+    if conf_max is not None and max_len > conf_max:
+        max_len = conf_max
+
+    def just(x: str) -> str:
+        if conf_max is not None:
+            if (conf_max > 3) & (adjustment.len(x) > max_len):
+                x = x[: max_len - 3] + "..."
+        return x
+
+    strings = [just(x) for x in strings]
+    result = adjustment.justify(strings, max_len, mode=justify)
+    return result
+
+
+def _trim_zeros_complex(str_complexes: ArrayLike, decimal: str = ".") -> list[str]:
+    """
+    Separates the real and imaginary parts from the complex number, and
+    executes the _trim_zeros_float method on each of those.
+    """
+    real_part, imag_part = [], []
+    for x in str_complexes:
+        # Complex numbers are represented as "(-)xxx(+/-)xxxj"
+        # The split will give [{"", "-"}, "xxx", "+/-", "xxx", "j", ""]
+        # Therefore, the imaginary part is the 4th and 3rd last elements,
+        # and the real part is everything before the imaginary part
+        trimmed = re.split(r"([j+-])", x)
+        real_part.append("".join(trimmed[:-4]))
+        imag_part.append("".join(trimmed[-4:-2]))
+
+    # We want to align the lengths of the real and imaginary parts of each complex
+    # number, as well as the lengths the real (resp. complex) parts of all numbers
+    # in the array
+    n = len(str_complexes)
+    padded_parts = _trim_zeros_float(real_part + imag_part, decimal)
+    if len(padded_parts) == 0:
+        return []
+    padded_length = max(len(part) for part in padded_parts) - 1
+    padded = [
+        real_pt  # real part, possibly NaN
+        + imag_pt[0]  # +/-
+        + f"{imag_pt[1:]:>{padded_length}}"  # complex part (no sign), possibly nan
+        + "j"
+        for real_pt, imag_pt in zip(padded_parts[:n], padded_parts[n:])
+    ]
+    return padded
+
+
+def _trim_zeros_single_float(str_float: str) -> str:
+    """
+    Trims trailing zeros after a decimal point,
+    leaving just one if necessary.
+    """
+    str_float = str_float.rstrip("0")
+    if str_float.endswith("."):
+        str_float += "0"
+
+    return str_float
+
+
+def _trim_zeros_float(
+    str_floats: ArrayLike | list[str], decimal: str = "."
+) -> list[str]:
+    """
+    Trims the maximum number of trailing zeros equally from
+    all numbers containing decimals, leaving just one if
+    necessary.
+    """
+    trimmed = str_floats
+    number_regex = re.compile(rf"^\s*[\+-]?[0-9]+\{decimal}[0-9]*$")
+
+    def is_number_with_decimal(x) -> bool:
+        return re.match(number_regex, x) is not None
+
+    def should_trim(values: ArrayLike | list[str]) -> bool:
+        """
+        Determine if an array of strings should be trimmed.
+
+        Returns True if all numbers containing decimals (defined by the
+        above regular expression) within the array end in a zero, otherwise
+        returns False.
+        """
+        numbers = [x for x in values if is_number_with_decimal(x)]
+        return len(numbers) > 0 and all(x.endswith("0") for x in numbers)
+
+    while should_trim(trimmed):
+        trimmed = [x[:-1] if is_number_with_decimal(x) else x for x in trimmed]
+
+    # leave one 0 after the decimal points if need be.
+    result = [
+        x + "0" if is_number_with_decimal(x) and x.endswith(decimal) else x
+        for x in trimmed
+    ]
+    return result
+
+
+def _has_names(index: Index) -> bool:
+    if isinstance(index, MultiIndex):
+        return com.any_not_none(*index.names)
+    else:
+        return index.name is not None
+
+
+class EngFormatter:
+    """
+    Formats float values according to engineering format.
+
+    Based on matplotlib.ticker.EngFormatter
+    """
+
+    # The SI engineering prefixes
+    ENG_PREFIXES = {
+        -24: "y",
+        -21: "z",
+        -18: "a",
+        -15: "f",
+        -12: "p",
+        -9: "n",
+        -6: "u",
+        -3: "m",
+        0: "",
+        3: "k",
+        6: "M",
+        9: "G",
+        12: "T",
+        15: "P",
+        18: "E",
+        21: "Z",
+        24: "Y",
+    }
+
+    def __init__(
+        self, accuracy: int | None = None, use_eng_prefix: bool = False
+    ) -> None:
+        self.accuracy = accuracy
+        self.use_eng_prefix = use_eng_prefix
+
+    def __call__(self, num: float) -> str:
+        """
+        Formats a number in engineering notation, appending a letter
+        representing the power of 1000 of the original number. Some examples:
+        >>> format_eng = EngFormatter(accuracy=0, use_eng_prefix=True)
+        >>> format_eng(0)
+        ' 0'
+        >>> format_eng = EngFormatter(accuracy=1, use_eng_prefix=True)
+        >>> format_eng(1_000_000)
+        ' 1.0M'
+        >>> format_eng = EngFormatter(accuracy=2, use_eng_prefix=False)
+        >>> format_eng("-1e-6")
+        '-1.00E-06'
+
+        @param num: the value to represent
+        @type num: either a numeric value or a string that can be converted to
+                   a numeric value (as per decimal.Decimal constructor)
+
+        @return: engineering formatted string
+        """
+        dnum = Decimal(str(num))
+
+        if Decimal.is_nan(dnum):
+            return "NaN"
+
+        if Decimal.is_infinite(dnum):
+            return "inf"
+
+        sign = 1
+
+        if dnum < 0:  # pragma: no cover
+            sign = -1
+            dnum = -dnum
+
+        if dnum != 0:
+            pow10 = Decimal(int(math.floor(dnum.log10() / 3) * 3))
+        else:
+            pow10 = Decimal(0)
+
+        pow10 = pow10.min(max(self.ENG_PREFIXES.keys()))
+        pow10 = pow10.max(min(self.ENG_PREFIXES.keys()))
+        int_pow10 = int(pow10)
+
+        if self.use_eng_prefix:
+            prefix = self.ENG_PREFIXES[int_pow10]
+        elif int_pow10 < 0:
+            prefix = f"E-{-int_pow10:02d}"
+        else:
+            prefix = f"E+{int_pow10:02d}"
+
+        mant = sign * dnum / (10**pow10)
+
+        if self.accuracy is None:  # pragma: no cover
+            format_str = "{mant: g}{prefix}"
+        else:
+            format_str = f"{{mant: .{self.accuracy:d}f}}{{prefix}}"
+
+        formatted = format_str.format(mant=mant, prefix=prefix)
+
+        return formatted
+
+
+def set_eng_float_format(accuracy: int = 3, use_eng_prefix: bool = False) -> None:
+    """
+    Format float representation in DataFrame with SI notation.
+
+    Parameters
+    ----------
+    accuracy : int, default 3
+        Number of decimal digits after the floating point.
+    use_eng_prefix : bool, default False
+        Whether to represent a value with SI prefixes.
+
+    Returns
+    -------
+    None
+
+    Examples
+    --------
+    >>> df = pd.DataFrame([1e-9, 1e-3, 1, 1e3, 1e6])
+    >>> df
+                  0
+    0  1.000000e-09
+    1  1.000000e-03
+    2  1.000000e+00
+    3  1.000000e+03
+    4  1.000000e+06
+
+    >>> pd.set_eng_float_format(accuracy=1)
+    >>> df
+             0
+    0  1.0E-09
+    1  1.0E-03
+    2  1.0E+00
+    3  1.0E+03
+    4  1.0E+06
+
+    >>> pd.set_eng_float_format(use_eng_prefix=True)
+    >>> df
+            0
+    0  1.000n
+    1  1.000m
+    2   1.000
+    3  1.000k
+    4  1.000M
+
+    >>> pd.set_eng_float_format(accuracy=1, use_eng_prefix=True)
+    >>> df
+          0
+    0  1.0n
+    1  1.0m
+    2   1.0
+    3  1.0k
+    4  1.0M
+
+    >>> pd.set_option("display.float_format", None)  # unset option
+    """
+    set_option("display.float_format", EngFormatter(accuracy, use_eng_prefix))
+
+
+def get_level_lengths(
+    levels: Any, sentinel: bool | object | str = ""
+) -> list[dict[int, int]]:
+    """
+    For each index in each level the function returns lengths of indexes.
+
+    Parameters
+    ----------
+    levels : list of lists
+        List of values on for level.
+    sentinel : string, optional
+        Value which states that no new index starts on there.
+
+    Returns
+    -------
+    Returns list of maps. For each level returns map of indexes (key is index
+    in row and value is length of index).
+    """
+    if len(levels) == 0:
+        return []
+
+    control = [True] * len(levels[0])
+
+    result = []
+    for level in levels:
+        last_index = 0
+
+        lengths = {}
+        for i, key in enumerate(level):
+            if control[i] and key == sentinel:
+                pass
+            else:
+                control[i] = False
+                lengths[last_index] = i - last_index
+                last_index = i
+
+        lengths[last_index] = len(level) - last_index
+
+        result.append(lengths)
+
+    return result
+
+
+def buffer_put_lines(buf: WriteBuffer[str], lines: list[str]) -> None:
+    """
+    Appends lines to a buffer.
+
+    Parameters
+    ----------
+    buf
+        The buffer to write to
+    lines
+        The lines to append.
+    """
+    if any(isinstance(x, str) for x in lines):
+        lines = [str(x) for x in lines]
+    buf.write("\n".join(lines))
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/html.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/html.py
new file mode 100644
index 0000000000000000000000000000000000000000..794ce77b3b45ec38d9fa58a708939e53bb8ae629
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/html.py
@@ -0,0 +1,646 @@
+"""
+Module for formatting output data in HTML.
+"""
+from __future__ import annotations
+
+from textwrap import dedent
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Final,
+    cast,
+)
+
+from pandas._config import get_option
+
+from pandas._libs import lib
+
+from pandas import (
+    MultiIndex,
+    option_context,
+)
+
+from pandas.io.common import is_url
+from pandas.io.formats.format import (
+    DataFrameFormatter,
+    get_level_lengths,
+)
+from pandas.io.formats.printing import pprint_thing
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Mapping,
+    )
+
+
+class HTMLFormatter:
+    """
+    Internal class for formatting output data in html.
+    This class is intended for shared functionality between
+    DataFrame.to_html() and DataFrame._repr_html_().
+    Any logic in common with other output formatting methods
+    should ideally be inherited from classes in format.py
+    and this class responsible for only producing html markup.
+    """
+
+    indent_delta: Final = 2
+
+    def __init__(
+        self,
+        formatter: DataFrameFormatter,
+        classes: str | list[str] | tuple[str, ...] | None = None,
+        border: int | bool | None = None,
+        table_id: str | None = None,
+        render_links: bool = False,
+    ) -> None:
+        self.fmt = formatter
+        self.classes = classes
+
+        self.frame = self.fmt.frame
+        self.columns = self.fmt.tr_frame.columns
+        self.elements: list[str] = []
+        self.bold_rows = self.fmt.bold_rows
+        self.escape = self.fmt.escape
+        self.show_dimensions = self.fmt.show_dimensions
+        if border is None or border is True:
+            border = cast(int, get_option("display.html.border"))
+        elif not border:
+            border = None
+
+        self.border = border
+        self.table_id = table_id
+        self.render_links = render_links
+
+        self.col_space = {}
+        is_multi_index = isinstance(self.columns, MultiIndex)
+        for column, value in self.fmt.col_space.items():
+            col_space_value = f"{value}px" if isinstance(value, int) else value
+            self.col_space[column] = col_space_value
+            # GH 53885: Handling case where column is index
+            # Flatten the data in the multi index and add in the map
+            if is_multi_index and isinstance(column, tuple):
+                for column_index in column:
+                    self.col_space[str(column_index)] = col_space_value
+
+    def to_string(self) -> str:
+        lines = self.render()
+        if any(isinstance(x, str) for x in lines):
+            lines = [str(x) for x in lines]
+        return "\n".join(lines)
+
+    def render(self) -> list[str]:
+        self._write_table()
+
+        if self.should_show_dimensions:
+            by = chr(215)  # ×  # noqa: RUF003
+            self.write(
+                f"
{len(self.frame)} rows {by} {len(self.frame.columns)} columns
"
+            )
+
+        return self.elements
+
+    @property
+    def should_show_dimensions(self) -> bool:
+        return self.fmt.should_show_dimensions
+
+    @property
+    def show_row_idx_names(self) -> bool:
+        return self.fmt.show_row_idx_names
+
+    @property
+    def show_col_idx_names(self) -> bool:
+        return self.fmt.show_col_idx_names
+
+    @property
+    def row_levels(self) -> int:
+        if self.fmt.index:
+            # showing (row) index
+            return self.frame.index.nlevels
+        elif self.show_col_idx_names:
+            # see gh-22579
+            # Column misalignment also occurs for
+            # a standard index when the columns index is named.
+            # If the row index is not displayed a column of
+            # blank cells need to be included before the DataFrame values.
+            return 1
+        # not showing (row) index
+        return 0
+
+    def _get_columns_formatted_values(self) -> Iterable:
+        return self.columns
+
+    @property
+    def is_truncated(self) -> bool:
+        return self.fmt.is_truncated
+
+    @property
+    def ncols(self) -> int:
+        return len(self.fmt.tr_frame.columns)
+
+    def write(self, s: Any, indent: int = 0) -> None:
+        rs = pprint_thing(s)
+        self.elements.append(" " * indent + rs)
+
+    def write_th(
+        self, s: Any, header: bool = False, indent: int = 0, tags: str | None = None
+    ) -> None:
+        """
+        Method for writing a formatted .  This will
+            cause min-width to be set if there is one.
+        indent : int, default 0
+            The indentation level of the cell.
+        tags : str, default None
+            Tags to include in the cell.
+
+        Returns
+        -------
+        A written ", indent)
+        else:
+            self.write(f'', indent)
+        indent += indent_delta
+
+        for i, s in enumerate(line):
+            val_tag = tags.get(i, None)
+            if header or (self.bold_rows and i < nindex_levels):
+                self.write_th(s, indent=indent, header=header, tags=val_tag)
+            else:
+                self.write_td(s, indent, tags=val_tag)
+
+        indent -= indent_delta
+        self.write("", indent)
+
+    def _write_table(self, indent: int = 0) -> None:
+        _classes = ["dataframe"]  # Default class.
+        use_mathjax = get_option("display.html.use_mathjax")
+        if not use_mathjax:
+            _classes.append("tex2jax_ignore")
+        if self.classes is not None:
+            if isinstance(self.classes, str):
+                self.classes = self.classes.split()
+            if not isinstance(self.classes, (list, tuple)):
+                raise TypeError(
+                    "classes must be a string, list, "
+                    f"or tuple, not {type(self.classes)}"
+                )
+            _classes.extend(self.classes)
+
+        if self.table_id is None:
+            id_section = ""
+        else:
+            id_section = f' id="{self.table_id}"'
+
+        if self.border is None:
+            border_attr = ""
+        else:
+            border_attr = f' border="{self.border}"'
+
+        self.write(
+            f'',
+            indent,
+        )
+
+        if self.fmt.header or self.show_row_idx_names:
+            self._write_header(indent + self.indent_delta)
+
+        self._write_body(indent + self.indent_delta)
+
+        self.write("
 cell.
+
+        If col_space is set on the formatter then that is used for
+        the value of min-width.
+
+        Parameters
+        ----------
+        s : object
+            The data to be written inside the cell.
+        header : bool, default False
+            Set to True if the  is for use inside 
 cell.
+        """
+        col_space = self.col_space.get(s, None)
+
+        if header and col_space is not None:
+            tags = tags or ""
+            tags += f'style="min-width: {col_space};"'
+
+        self._write_cell(s, kind="th", indent=indent, tags=tags)
+
+    def write_td(self, s: Any, indent: int = 0, tags: str | None = None) -> None:
+        self._write_cell(s, kind="td", indent=indent, tags=tags)
+
+    def _write_cell(
+        self, s: Any, kind: str = "td", indent: int = 0, tags: str | None = None
+    ) -> None:
+        if tags is not None:
+            start_tag = f"<{kind} {tags}>"
+        else:
+            start_tag = f"<{kind}>"
+
+        if self.escape:
+            # escape & first to prevent double escaping of &
+            esc = {"&": r"&", "<": r"<", ">": r">"}
+        else:
+            esc = {}
+
+        rs = pprint_thing(s, escape_chars=esc).strip()
+
+        if self.render_links and is_url(rs):
+            rs_unescaped = pprint_thing(s, escape_chars={}).strip()
+            start_tag += f''
+            end_a = ""
+        else:
+            end_a = ""
+
+        self.write(f"{start_tag}{rs}{end_a}", indent)
+
+    def write_tr(
+        self,
+        line: Iterable,
+        indent: int = 0,
+        indent_delta: int = 0,
+        header: bool = False,
+        align: str | None = None,
+        tags: dict[int, str] | None = None,
+        nindex_levels: int = 0,
+    ) -> None:
+        if tags is None:
+            tags = {}
+
+        if align is None:
+            self.write("
", indent)
+
+    def _write_col_header(self, indent: int) -> None:
+        row: list[Hashable]
+        is_truncated_horizontally = self.fmt.is_truncated_horizontally
+        if isinstance(self.columns, MultiIndex):
+            template = 'colspan="{span:d}" halign="left"'
+
+            sentinel: lib.NoDefault | bool
+            if self.fmt.sparsify:
+                # GH3547
+                sentinel = lib.no_default
+            else:
+                sentinel = False
+            levels = self.columns._format_multi(sparsify=sentinel, include_names=False)
+            level_lengths = get_level_lengths(levels, sentinel)
+            inner_lvl = len(level_lengths) - 1
+            for lnum, (records, values) in enumerate(zip(level_lengths, levels)):
+                if is_truncated_horizontally:
+                    # modify the header lines
+                    ins_col = self.fmt.tr_col_num
+                    if self.fmt.sparsify:
+                        recs_new = {}
+                        # Increment tags after ... col.
+                        for tag, span in list(records.items()):
+                            if tag >= ins_col:
+                                recs_new[tag + 1] = span
+                            elif tag + span > ins_col:
+                                recs_new[tag] = span + 1
+                                if lnum == inner_lvl:
+                                    values = (
+                                        values[:ins_col] + ("...",) + values[ins_col:]
+                                    )
+                                else:
+                                    # sparse col headers do not receive a ...
+                                    values = (
+                                        values[:ins_col]
+                                        + (values[ins_col - 1],)
+                                        + values[ins_col:]
+                                    )
+                            else:
+                                recs_new[tag] = span
+                            # if ins_col lies between tags, all col headers
+                            # get ...
+                            if tag + span == ins_col:
+                                recs_new[ins_col] = 1
+                                values = values[:ins_col] + ("...",) + values[ins_col:]
+                        records = recs_new
+                        inner_lvl = len(level_lengths) - 1
+                        if lnum == inner_lvl:
+                            records[ins_col] = 1
+                    else:
+                        recs_new = {}
+                        for tag, span in list(records.items()):
+                            if tag >= ins_col:
+                                recs_new[tag + 1] = span
+                            else:
+                                recs_new[tag] = span
+                        recs_new[ins_col] = 1
+                        records = recs_new
+                        values = values[:ins_col] + ["..."] + values[ins_col:]
+
+                # see gh-22579
+                # Column Offset Bug with to_html(index=False) with
+                # MultiIndex Columns and Index.
+                # Initially fill row with blank cells before column names.
+                # TODO: Refactor to remove code duplication with code
+                # block below for standard columns index.
+                row = [""] * (self.row_levels - 1)
+                if self.fmt.index or self.show_col_idx_names:
+                    # see gh-22747
+                    # If to_html(index_names=False) do not show columns
+                    # index names.
+                    # TODO: Refactor to use _get_column_name_list from
+                    # DataFrameFormatter class and create a
+                    # _get_formatted_column_labels function for code
+                    # parity with DataFrameFormatter class.
+                    if self.fmt.show_index_names:
+                        name = self.columns.names[lnum]
+                        row.append(pprint_thing(name or ""))
+                    else:
+                        row.append("")
+
+                tags = {}
+                j = len(row)
+                for i, v in enumerate(values):
+                    if i in records:
+                        if records[i] > 1:
+                            tags[j] = template.format(span=records[i])
+                    else:
+                        continue
+                    j += 1
+                    row.append(v)
+                self.write_tr(row, indent, self.indent_delta, tags=tags, header=True)
+        else:
+            # see gh-22579
+            # Column misalignment also occurs for
+            # a standard index when the columns index is named.
+            # Initially fill row with blank cells before column names.
+            # TODO: Refactor to remove code duplication with code block
+            # above for columns MultiIndex.
+            row = [""] * (self.row_levels - 1)
+            if self.fmt.index or self.show_col_idx_names:
+                # see gh-22747
+                # If to_html(index_names=False) do not show columns
+                # index names.
+                # TODO: Refactor to use _get_column_name_list from
+                # DataFrameFormatter class.
+                if self.fmt.show_index_names:
+                    row.append(self.columns.name or "")
+                else:
+                    row.append("")
+            row.extend(self._get_columns_formatted_values())
+            align = self.fmt.justify
+
+            if is_truncated_horizontally:
+                ins_col = self.row_levels + self.fmt.tr_col_num
+                row.insert(ins_col, "...")
+
+            self.write_tr(row, indent, self.indent_delta, header=True, align=align)
+
+    def _write_row_header(self, indent: int) -> None:
+        is_truncated_horizontally = self.fmt.is_truncated_horizontally
+        row = [x if x is not None else "" for x in self.frame.index.names] + [""] * (
+            self.ncols + (1 if is_truncated_horizontally else 0)
+        )
+        self.write_tr(row, indent, self.indent_delta, header=True)
+
+    def _write_header(self, indent: int) -> None:
+        self.write("
`` tag
+        in addition to automatic (by default) id.
+    cell_ids : bool, default True
+        If True, each cell will have an ``id`` attribute in their HTML tag.
+        The ``id`` takes the form ``T__row_col``
+        where ```` is the unique identifier, ```` is the row
+        number and ```` is the column number.
+    na_rep : str, optional
+        Representation for missing values.
+        If ``na_rep`` is None, no special formatting is applied, and falls back to
+        ``pandas.options.styler.format.na_rep``.
+
+    uuid_len : int, default 5
+        If ``uuid`` is not specified, the length of the ``uuid`` to randomly generate
+        expressed in hex characters, in range [0, 32].
+    decimal : str, optional
+        Character used as decimal separator for floats, complex and integers. If not
+        given uses ``pandas.options.styler.format.decimal``.
+
+        .. versionadded:: 1.3.0
+
+    thousands : str, optional, default None
+        Character used as thousands separator for floats, complex and integers. If not
+        given uses ``pandas.options.styler.format.thousands``.
+
+        .. versionadded:: 1.3.0
+
+    escape : str, optional
+        Use 'html' to replace the characters ``&``, ``<``, ``>``, ``'``, and ``"``
+        in cell display string with HTML-safe sequences.
+        Use 'latex' to replace the characters ``&``, ``%``, ``$``, ``#``, ``_``,
+        ``{``, ``}``, ``~``, ``^``, and ``\`` in the cell display string with
+        LaTeX-safe sequences. Use 'latex-math' to replace the characters
+        the same way as in 'latex' mode, except for math substrings,
+        which either are surrounded by two characters ``$`` or start with
+        the character ``\(`` and end with ``\)``.
+        If not given uses ``pandas.options.styler.format.escape``.
+
+        .. versionadded:: 1.3.0
+    formatter : str, callable, dict, optional
+        Object to define how values are displayed. See ``Styler.format``. If not given
+        uses ``pandas.options.styler.format.formatter``.
+
+        .. versionadded:: 1.4.0
+
+    Attributes
+    ----------
+    env : Jinja2 jinja2.Environment
+    template_html : Jinja2 Template
+    template_html_table : Jinja2 Template
+    template_html_style : Jinja2 Template
+    template_latex : Jinja2 Template
+    loader : Jinja2 Loader
+
+    See Also
+    --------
+    DataFrame.style : Return a Styler object containing methods for building
+        a styled HTML representation for the DataFrame.
+
+    Notes
+    -----
+    Most styling will be done by passing style functions into
+    ``Styler.apply`` or ``Styler.map``. Style functions should
+    return values with strings containing CSS ``'attr: value'`` that will
+    be applied to the indicated cells.
+
+    If using in the Jupyter notebook, Styler has defined a ``_repr_html_``
+    to automatically render itself. Otherwise call Styler.to_html to get
+    the generated HTML.
+
+    CSS classes are attached to the generated HTML
+
+    * Index and Column names include ``index_name`` and ``level``
+      where `k` is its level in a MultiIndex
+    * Index label cells include
+
+      * ``row_heading``
+      * ``row`` where `n` is the numeric position of the row
+      * ``level`` where `k` is the level in a MultiIndex
+
+    * Column label cells include
+      * ``col_heading``
+      * ``col`` where `n` is the numeric position of the column
+      * ``level`` where `k` is the level in a MultiIndex
+
+    * Blank cells include ``blank``
+    * Data cells include ``data``
+    * Trimmed cells include ``col_trim`` or ``row_trim``.
+
+    Any, or all, or these classes can be renamed by using the ``css_class_names``
+    argument in ``Styler.set_table_classes``, giving a value such as
+    *{"row": "MY_ROW_CLASS", "col_trim": "", "row_trim": ""}*.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame([[1.0, 2.0, 3.0], [4, 5, 6]], index=['a', 'b'],
+    ...                   columns=['A', 'B', 'C'])
+    >>> pd.io.formats.style.Styler(df, precision=2,
+    ...                            caption="My table")  # doctest: +SKIP
+
+    Please see:
+    `Table Visualization <../../user_guide/style.ipynb>`_ for more examples.
+    """
+
+    def __init__(
+        self,
+        data: DataFrame | Series,
+        precision: int | None = None,
+        table_styles: CSSStyles | None = None,
+        uuid: str | None = None,
+        caption: str | tuple | list | None = None,
+        table_attributes: str | None = None,
+        cell_ids: bool = True,
+        na_rep: str | None = None,
+        uuid_len: int = 5,
+        decimal: str | None = None,
+        thousands: str | None = None,
+        escape: str | None = None,
+        formatter: ExtFormatter | None = None,
+    ) -> None:
+        super().__init__(
+            data=data,
+            uuid=uuid,
+            uuid_len=uuid_len,
+            table_styles=table_styles,
+            table_attributes=table_attributes,
+            caption=caption,
+            cell_ids=cell_ids,
+            precision=precision,
+        )
+
+        # validate ordered args
+        thousands = thousands or get_option("styler.format.thousands")
+        decimal = decimal or get_option("styler.format.decimal")
+        na_rep = na_rep or get_option("styler.format.na_rep")
+        escape = escape or get_option("styler.format.escape")
+        formatter = formatter or get_option("styler.format.formatter")
+        # precision is handled by superclass as default for performance
+
+        self.format(
+            formatter=formatter,
+            precision=precision,
+            na_rep=na_rep,
+            escape=escape,
+            decimal=decimal,
+            thousands=thousands,
+        )
+
+    def concat(self, other: Styler) -> Styler:
+        """
+        Append another Styler to combine the output into a single table.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        other : Styler
+            The other Styler object which has already been styled and formatted. The
+            data for this Styler must have the same columns as the original, and the
+            number of index levels must also be the same to render correctly.
+
+        Returns
+        -------
+        Styler
+
+        Notes
+        -----
+        The purpose of this method is to extend existing styled dataframes with other
+        metrics that may be useful but may not conform to the original's structure.
+        For example adding a sub total row, or displaying metrics such as means,
+        variance or counts.
+
+        Styles that are applied using the ``apply``, ``map``, ``apply_index``
+        and ``map_index``, and formatting applied with ``format`` and
+        ``format_index`` will be preserved.
+
+        .. warning::
+            Only the output methods ``to_html``, ``to_string`` and ``to_latex``
+            currently work with concatenated Stylers.
+
+            Other output methods, including ``to_excel``, **do not** work with
+            concatenated Stylers.
+
+        The following should be noted:
+
+          - ``table_styles``, ``table_attributes``, ``caption`` and ``uuid`` are all
+            inherited from the original Styler and not ``other``.
+          - hidden columns and hidden index levels will be inherited from the
+            original Styler
+          - ``css`` will be inherited from the original Styler, and the value of
+            keys ``data``, ``row_heading`` and ``row`` will be prepended with
+            ``foot0_``. If more concats are chained, their styles will be prepended
+            with ``foot1_``, ''foot_2'', etc., and if a concatenated style have
+            another concatanated style, the second style will be prepended with
+            ``foot{parent}_foot{child}_``.
+
+        A common use case is to concatenate user defined functions with
+        ``DataFrame.agg`` or with described statistics via ``DataFrame.describe``.
+        See examples.
+
+        Examples
+        --------
+        A common use case is adding totals rows, or otherwise, via methods calculated
+        in ``DataFrame.agg``.
+
+        >>> df = pd.DataFrame([[4, 6], [1, 9], [3, 4], [5, 5], [9, 6]],
+        ...                   columns=["Mike", "Jim"],
+        ...                   index=["Mon", "Tue", "Wed", "Thurs", "Fri"])
+        >>> styler = df.style.concat(df.agg(["sum"]).style)  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/footer_simple.png
+
+        Since the concatenated object is a Styler the existing functionality can be
+        used to conditionally format it as well as the original.
+
+        >>> descriptors = df.agg(["sum", "mean", lambda s: s.dtype])
+        >>> descriptors.index = ["Total", "Average", "dtype"]
+        >>> other = (descriptors.style
+        ...          .highlight_max(axis=1, subset=(["Total", "Average"], slice(None)))
+        ...          .format(subset=("Average", slice(None)), precision=2, decimal=",")
+        ...          .map(lambda v: "font-weight: bold;"))
+        >>> styler = (df.style
+        ...             .highlight_max(color="salmon")
+        ...             .set_table_styles([{"selector": ".foot_row0",
+        ...                                 "props": "border-top: 1px solid black;"}]))
+        >>> styler.concat(other)  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/footer_extended.png
+
+        When ``other`` has fewer index levels than the original Styler it is possible
+        to extend the index in ``other``, with placeholder levels.
+
+        >>> df = pd.DataFrame([[1], [2]],
+        ...                   index=pd.MultiIndex.from_product([[0], [1, 2]]))
+        >>> descriptors = df.agg(["sum"])
+        >>> descriptors.index = pd.MultiIndex.from_product([[""], descriptors.index])
+        >>> df.style.concat(descriptors.style)  # doctest: +SKIP
+        """
+        if not isinstance(other, Styler):
+            raise TypeError("`other` must be of type `Styler`")
+        if not self.data.columns.equals(other.data.columns):
+            raise ValueError("`other.data` must have same columns as `Styler.data`")
+        if not self.data.index.nlevels == other.data.index.nlevels:
+            raise ValueError(
+                "number of index levels must be same in `other` "
+                "as in `Styler`. See documentation for suggestions."
+            )
+        self.concatenated.append(other)
+        return self
+
+    def _repr_html_(self) -> str | None:
+        """
+        Hooks into Jupyter notebook rich display system, which calls _repr_html_ by
+        default if an object is returned at the end of a cell.
+        """
+        if get_option("styler.render.repr") == "html":
+            return self.to_html()
+        return None
+
+    def _repr_latex_(self) -> str | None:
+        if get_option("styler.render.repr") == "latex":
+            return self.to_latex()
+        return None
+
+    def set_tooltips(
+        self,
+        ttips: DataFrame,
+        props: CSSProperties | None = None,
+        css_class: str | None = None,
+    ) -> Styler:
+        """
+        Set the DataFrame of strings on ``Styler`` generating ``:hover`` tooltips.
+
+        These string based tooltips are only applicable to ``
`` HTML elements,
+        and cannot be used for column or index headers.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        ttips : DataFrame
+            DataFrame containing strings that will be translated to tooltips, mapped
+            by identical column and index values that must exist on the underlying
+            Styler data. None, NaN values, and empty strings will be ignored and
+            not affect the rendered HTML.
+        props : list-like or str, optional
+            List of (attr, value) tuples or a valid CSS string. If ``None`` adopts
+            the internal default values described in notes.
+        css_class : str, optional
+            Name of the tooltip class used in CSS, should conform to HTML standards.
+            Only useful if integrating tooltips with external CSS. If ``None`` uses the
+            internal default value 'pd-t'.
+
+        Returns
+        -------
+        Styler
+
+        Notes
+        -----
+        Tooltips are created by adding `` to each data cell
+        and then manipulating the table level CSS to attach pseudo hover and pseudo
+        after selectors to produce the required the results.
+
+        The default properties for the tooltip CSS class are:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+        The property 'visibility: hidden;' is a key prerequisite to the hover
+        functionality, and should always be included in any manual properties
+        specification, using the ``props`` argument.
+
+        Tooltips are not designed to be efficient, and can add large amounts of
+        additional HTML for larger tables, since they also require that ``cell_ids``
+        is forced to `True`.
+
+        Examples
+        --------
+        Basic application
+
+        >>> df = pd.DataFrame(data=[[0, 1], [2, 3]])
+        >>> ttips = pd.DataFrame(
+        ...    data=[["Min", ""], [np.nan, "Max"]], columns=df.columns, index=df.index
+        ... )
+        >>> s = df.style.set_tooltips(ttips).to_html()
+
+        Optionally controlling the tooltip visual display
+
+        >>> df.style.set_tooltips(ttips, css_class='tt-add', props=[
+        ...     ('visibility', 'hidden'),
+        ...     ('position', 'absolute'),
+        ...     ('z-index', 1)])  # doctest: +SKIP
+        >>> df.style.set_tooltips(ttips, css_class='tt-add',
+        ...     props='visibility:hidden; position:absolute; z-index:1;')
+        ... # doctest: +SKIP
+        """
+        if not self.cell_ids:
+            # tooltips not optimised for individual cell check. requires reasonable
+            # redesign and more extensive code for a feature that might be rarely used.
+            raise NotImplementedError(
+                "Tooltips can only render with 'cell_ids' is True."
+            )
+        if not ttips.index.is_unique or not ttips.columns.is_unique:
+            raise KeyError(
+                "Tooltips render only if `ttips` has unique index and columns."
+            )
+        if self.tooltips is None:  # create a default instance if necessary
+            self.tooltips = Tooltips()
+        self.tooltips.tt_data = ttips
+        if props:
+            self.tooltips.class_properties = props
+        if css_class:
+            self.tooltips.class_name = css_class
+
+        return self
+
+    @doc(
+        NDFrame.to_excel,
+        klass="Styler",
+        storage_options=_shared_docs["storage_options"],
+        storage_options_versionadded="1.5.0",
+    )
+    def to_excel(
+        self,
+        excel_writer: FilePath | WriteExcelBuffer | ExcelWriter,
+        sheet_name: str = "Sheet1",
+        na_rep: str = "",
+        float_format: str | None = None,
+        columns: Sequence[Hashable] | None = None,
+        header: Sequence[Hashable] | bool = True,
+        index: bool = True,
+        index_label: IndexLabel | None = None,
+        startrow: int = 0,
+        startcol: int = 0,
+        engine: str | None = None,
+        merge_cells: bool = True,
+        encoding: str | None = None,
+        inf_rep: str = "inf",
+        verbose: bool = True,
+        freeze_panes: tuple[int, int] | None = None,
+        storage_options: StorageOptions | None = None,
+    ) -> None:
+        from pandas.io.formats.excel import ExcelFormatter
+
+        formatter = ExcelFormatter(
+            self,
+            na_rep=na_rep,
+            cols=columns,
+            header=header,
+            float_format=float_format,
+            index=index,
+            index_label=index_label,
+            merge_cells=merge_cells,
+            inf_rep=inf_rep,
+        )
+        formatter.write(
+            excel_writer,
+            sheet_name=sheet_name,
+            startrow=startrow,
+            startcol=startcol,
+            freeze_panes=freeze_panes,
+            engine=engine,
+            storage_options=storage_options,
+        )
+
+    @overload
+    def to_latex(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        *,
+        column_format: str | None = ...,
+        position: str | None = ...,
+        position_float: str | None = ...,
+        hrules: bool | None = ...,
+        clines: str | None = ...,
+        label: str | None = ...,
+        caption: str | tuple | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        multirow_align: str | None = ...,
+        multicol_align: str | None = ...,
+        siunitx: bool = ...,
+        environment: str | None = ...,
+        encoding: str | None = ...,
+        convert_css: bool = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def to_latex(
+        self,
+        buf: None = ...,
+        *,
+        column_format: str | None = ...,
+        position: str | None = ...,
+        position_float: str | None = ...,
+        hrules: bool | None = ...,
+        clines: str | None = ...,
+        label: str | None = ...,
+        caption: str | tuple | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        multirow_align: str | None = ...,
+        multicol_align: str | None = ...,
+        siunitx: bool = ...,
+        environment: str | None = ...,
+        encoding: str | None = ...,
+        convert_css: bool = ...,
+    ) -> str:
+        ...
+
+    def to_latex(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        *,
+        column_format: str | None = None,
+        position: str | None = None,
+        position_float: str | None = None,
+        hrules: bool | None = None,
+        clines: str | None = None,
+        label: str | None = None,
+        caption: str | tuple | None = None,
+        sparse_index: bool | None = None,
+        sparse_columns: bool | None = None,
+        multirow_align: str | None = None,
+        multicol_align: str | None = None,
+        siunitx: bool = False,
+        environment: str | None = None,
+        encoding: str | None = None,
+        convert_css: bool = False,
+    ) -> str | None:
+        r"""
+        Write Styler to a file, buffer or string in LaTeX format.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        buf : str, path object, file-like object, or None, default None
+            String, path object (implementing ``os.PathLike[str]``), or file-like
+            object implementing a string ``write()`` function. If None, the result is
+            returned as a string.
+        column_format : str, optional
+            The LaTeX column specification placed in location:
+
+            \\begin{tabular}{}
+
+            Defaults to 'l' for index and
+            non-numeric data columns, and, for numeric data columns,
+            to 'r' by default, or 'S' if ``siunitx`` is ``True``.
+        position : str, optional
+            The LaTeX positional argument (e.g. 'h!') for tables, placed in location:
+
+            ``\\begin{table}[]``.
+        position_float : {"centering", "raggedleft", "raggedright"}, optional
+            The LaTeX float command placed in location:
+
+            \\begin{table}[]
+
+            \\
+
+            Cannot be used if ``environment`` is "longtable".
+        hrules : bool
+            Set to `True` to add \\toprule, \\midrule and \\bottomrule from the
+            {booktabs} LaTeX package.
+            Defaults to ``pandas.options.styler.latex.hrules``, which is `False`.
+
+            .. versionchanged:: 1.4.0
+        clines : str, optional
+            Use to control adding \\cline commands for the index labels separation.
+            Possible values are:
+
+              - `None`: no cline commands are added (default).
+              - `"all;data"`: a cline is added for every index value extending the
+                width of the table, including data entries.
+              - `"all;index"`: as above with lines extending only the width of the
+                index entries.
+              - `"skip-last;data"`: a cline is added for each index value except the
+                last level (which is never sparsified), extending the widtn of the
+                table.
+              - `"skip-last;index"`: as above with lines extending only the width of the
+                index entries.
+
+            .. versionadded:: 1.4.0
+        label : str, optional
+            The LaTeX label included as: \\label{
}.
+            If tuple, i.e ("full caption", "short caption"), the caption included
+            as: \\caption[]{}.
+        sparse_index : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each row.
+            Defaults to ``pandas.options.styler.sparse.index``, which is `True`.
+        sparse_columns : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each
+            column. Defaults to ``pandas.options.styler.sparse.columns``, which
+            is `True`.
+        multirow_align : {"c", "t", "b", "naive"}, optional
+            If sparsifying hierarchical MultiIndexes whether to align text centrally,
+            at the top or bottom using the multirow package. If not given defaults to
+            ``pandas.options.styler.latex.multirow_align``, which is `"c"`.
+            If "naive" is given renders without multirow.
+
+            .. versionchanged:: 1.4.0
+        multicol_align : {"r", "c", "l", "naive-l", "naive-r"}, optional
+            If sparsifying hierarchical MultiIndex columns whether to align text at
+            the left, centrally, or at the right. If not given defaults to
+            ``pandas.options.styler.latex.multicol_align``, which is "r".
+            If a naive option is given renders without multicol.
+            Pipe decorators can also be added to non-naive values to draw vertical
+            rules, e.g. "\|r" will draw a rule on the left side of right aligned merged
+            cells.
+
+            .. versionchanged:: 1.4.0
+        siunitx : bool, default False
+            Set to ``True`` to structure LaTeX compatible with the {siunitx} package.
+        environment : str, optional
+            If given, the environment that will replace 'table' in ``\\begin{table}``.
+            If 'longtable' is specified then a more suitable template is
+            rendered. If not given defaults to
+            ``pandas.options.styler.latex.environment``, which is `None`.
+
+            .. versionadded:: 1.4.0
+        encoding : str, optional
+            Character encoding setting. Defaults
+            to ``pandas.options.styler.render.encoding``, which is "utf-8".
+        convert_css : bool, default False
+            Convert simple cell-styles from CSS to LaTeX format. Any CSS not found in
+            conversion table is dropped. A style can be forced by adding option
+            `--latex`. See notes.
+
+        Returns
+        -------
+        str or None
+            If `buf` is None, returns the result as a string. Otherwise returns `None`.
+
+        See Also
+        --------
+        Styler.format: Format the text display value of cells.
+
+        Notes
+        -----
+        **Latex Packages**
+
+        For the following features we recommend the following LaTeX inclusions:
+
+        ===================== ==========================================================
+        Feature               Inclusion
+        ===================== ==========================================================
+        sparse columns        none: included within default {tabular} environment
+        sparse rows           \\usepackage{multirow}
+        hrules                \\usepackage{booktabs}
+        colors                \\usepackage[table]{xcolor}
+        siunitx               \\usepackage{siunitx}
+        bold (with siunitx)   | \\usepackage{etoolbox}
+                              | \\robustify\\bfseries
+                              | \\sisetup{detect-all = true}  *(within {document})*
+        italic (with siunitx) | \\usepackage{etoolbox}
+                              | \\robustify\\itshape
+                              | \\sisetup{detect-all = true}  *(within {document})*
+        environment           \\usepackage{longtable} if arg is "longtable"
+                              | or any other relevant environment package
+        hyperlinks            \\usepackage{hyperref}
+        ===================== ==========================================================
+
+        **Cell Styles**
+
+        LaTeX styling can only be rendered if the accompanying styling functions have
+        been constructed with appropriate LaTeX commands. All styling
+        functionality is built around the concept of a CSS ``(, )``
+        pair (see `Table Visualization <../../user_guide/style.ipynb>`_), and this
+        should be replaced by a LaTeX
+        ``(, )`` approach. Each cell will be styled individually
+        using nested LaTeX commands with their accompanied options.
+
+        For example the following code will highlight and bold a cell in HTML-CSS:
+
+        >>> df = pd.DataFrame([[1,2], [3,4]])
+        >>> s = df.style.highlight_max(axis=None,
+        ...                            props='background-color:red; font-weight:bold;')
+        >>> s.to_html()  # doctest: +SKIP
+
+        The equivalent using LaTeX only commands is the following:
+
+        >>> s = df.style.highlight_max(axis=None,
+        ...                            props='cellcolor:{red}; bfseries: ;')
+        >>> s.to_latex()  # doctest: +SKIP
+
+        Internally these structured LaTeX ``(, )`` pairs
+        are translated to the
+        ``display_value`` with the default structure:
+        ``\ ``.
+        Where there are multiple commands the latter is nested recursively, so that
+        the above example highlighted cell is rendered as
+        ``\cellcolor{red} \bfseries 4``.
+
+        Occasionally this format does not suit the applied command, or
+        combination of LaTeX packages that is in use, so additional flags can be
+        added to the ````, within the tuple, to result in different
+        positions of required braces (the **default** being the same as ``--nowrap``):
+
+        =================================== ============================================
+        Tuple Format                           Output Structure
+        =================================== ============================================
+        (,)               \\ 
+        (, ``--nowrap``)  \\ 
+        (, ``--rwrap``)   \\{}
+        (, ``--wrap``)    {\\ }
+        (, ``--lwrap``)   {\\} 
+        (, ``--dwrap``)   {\\}{}
+        =================================== ============================================
+
+        For example the `textbf` command for font-weight
+        should always be used with `--rwrap` so ``('textbf', '--rwrap')`` will render a
+        working cell, wrapped with braces, as ``\textbf{}``.
+
+        A more comprehensive example is as follows:
+
+        >>> df = pd.DataFrame([[1, 2.2, "dogs"], [3, 4.4, "cats"], [2, 6.6, "cows"]],
+        ...                   index=["ix1", "ix2", "ix3"],
+        ...                   columns=["Integers", "Floats", "Strings"])
+        >>> s = df.style.highlight_max(
+        ...     props='cellcolor:[HTML]{FFFF00}; color:{red};'
+        ...           'textit:--rwrap; textbf:--rwrap;'
+        ... )
+        >>> s.to_latex()  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/latex_1.png
+
+        **Table Styles**
+
+        Internally Styler uses its ``table_styles`` object to parse the
+        ``column_format``, ``position``, ``position_float``, and ``label``
+        input arguments. These arguments are added to table styles in the format:
+
+        .. code-block:: python
+
+            set_table_styles([
+                {"selector": "column_format", "props": f":{column_format};"},
+                {"selector": "position", "props": f":{position};"},
+                {"selector": "position_float", "props": f":{position_float};"},
+                {"selector": "label", "props": f":{{{label.replace(':','§')}}};"}
+            ], overwrite=False)
+
+        Exception is made for the ``hrules`` argument which, in fact, controls all three
+        commands: ``toprule``, ``bottomrule`` and ``midrule`` simultaneously. Instead of
+        setting ``hrules`` to ``True``, it is also possible to set each
+        individual rule definition, by manually setting the ``table_styles``,
+        for example below we set a regular ``toprule``, set an ``hline`` for
+        ``bottomrule`` and exclude the ``midrule``:
+
+        .. code-block:: python
+
+            set_table_styles([
+                {'selector': 'toprule', 'props': ':toprule;'},
+                {'selector': 'bottomrule', 'props': ':hline;'},
+            ], overwrite=False)
+
+        If other ``commands`` are added to table styles they will be detected, and
+        positioned immediately above the '\\begin{tabular}' command. For example to
+        add odd and even row coloring, from the {colortbl} package, in format
+        ``\rowcolors{1}{pink}{red}``, use:
+
+        .. code-block:: python
+
+            set_table_styles([
+                {'selector': 'rowcolors', 'props': ':{1}{pink}{red};'}
+            ], overwrite=False)
+
+        A more comprehensive example using these arguments is as follows:
+
+        >>> df.columns = pd.MultiIndex.from_tuples([
+        ...     ("Numeric", "Integers"),
+        ...     ("Numeric", "Floats"),
+        ...     ("Non-Numeric", "Strings")
+        ... ])
+        >>> df.index = pd.MultiIndex.from_tuples([
+        ...     ("L0", "ix1"), ("L0", "ix2"), ("L1", "ix3")
+        ... ])
+        >>> s = df.style.highlight_max(
+        ...     props='cellcolor:[HTML]{FFFF00}; color:{red}; itshape:; bfseries:;'
+        ... )
+        >>> s.to_latex(
+        ...     column_format="rrrrr", position="h", position_float="centering",
+        ...     hrules=True, label="table:5", caption="Styled LaTeX Table",
+        ...     multirow_align="t", multicol_align="r"
+        ... )  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/latex_2.png
+
+        **Formatting**
+
+        To format values :meth:`Styler.format` should be used prior to calling
+        `Styler.to_latex`, as well as other methods such as :meth:`Styler.hide`
+        for example:
+
+        >>> s.clear()
+        >>> s.table_styles = []
+        >>> s.caption = None
+        >>> s.format({
+        ...    ("Numeric", "Integers"): '\${}',
+        ...    ("Numeric", "Floats"): '{:.3f}',
+        ...    ("Non-Numeric", "Strings"): str.upper
+        ... })  # doctest: +SKIP
+                        Numeric      Non-Numeric
+                  Integers   Floats    Strings
+        L0    ix1       $1   2.200      DOGS
+              ix2       $3   4.400      CATS
+        L1    ix3       $2   6.600      COWS
+
+        >>> s.to_latex()  # doctest: +SKIP
+        \begin{tabular}{llrrl}
+        {} & {} & \multicolumn{2}{r}{Numeric} & {Non-Numeric} \\
+        {} & {} & {Integers} & {Floats} & {Strings} \\
+        \multirow[c]{2}{*}{L0} & ix1 & \\$1 & 2.200 & DOGS \\
+         & ix2 & \$3 & 4.400 & CATS \\
+        L1 & ix3 & \$2 & 6.600 & COWS \\
+        \end{tabular}
+
+        **CSS Conversion**
+
+        This method can convert a Styler constructured with HTML-CSS to LaTeX using
+        the following limited conversions.
+
+        ================== ==================== ============= ==========================
+        CSS Attribute      CSS value            LaTeX Command LaTeX Options
+        ================== ==================== ============= ==========================
+        font-weight        | bold               | bfseries
+                           | bolder             | bfseries
+        font-style         | italic             | itshape
+                           | oblique            | slshape
+        background-color   | red                cellcolor     | {red}--lwrap
+                           | #fe01ea                          | [HTML]{FE01EA}--lwrap
+                           | #f0e                             | [HTML]{FF00EE}--lwrap
+                           | rgb(128,255,0)                   | [rgb]{0.5,1,0}--lwrap
+                           | rgba(128,0,0,0.5)                | [rgb]{0.5,0,0}--lwrap
+                           | rgb(25%,255,50%)                 | [rgb]{0.25,1,0.5}--lwrap
+        color              | red                color         | {red}
+                           | #fe01ea                          | [HTML]{FE01EA}
+                           | #f0e                             | [HTML]{FF00EE}
+                           | rgb(128,255,0)                   | [rgb]{0.5,1,0}
+                           | rgba(128,0,0,0.5)                | [rgb]{0.5,0,0}
+                           | rgb(25%,255,50%)                 | [rgb]{0.25,1,0.5}
+        ================== ==================== ============= ==========================
+
+        It is also possible to add user-defined LaTeX only styles to a HTML-CSS Styler
+        using the ``--latex`` flag, and to add LaTeX parsing options that the
+        converter will detect within a CSS-comment.
+
+        >>> df = pd.DataFrame([[1]])
+        >>> df.style.set_properties(
+        ...     **{"font-weight": "bold /* --dwrap */", "Huge": "--latex--rwrap"}
+        ... ).to_latex(convert_css=True)  # doctest: +SKIP
+        \begin{tabular}{lr}
+        {} & {0} \\
+        0 & {\bfseries}{\Huge{1}} \\
+        \end{tabular}
+
+        Examples
+        --------
+        Below we give a complete step by step example adding some advanced features
+        and noting some common gotchas.
+
+        First we create the DataFrame and Styler as usual, including MultiIndex rows
+        and columns, which allow for more advanced formatting options:
+
+        >>> cidx = pd.MultiIndex.from_arrays([
+        ...     ["Equity", "Equity", "Equity", "Equity",
+        ...      "Stats", "Stats", "Stats", "Stats", "Rating"],
+        ...     ["Energy", "Energy", "Consumer", "Consumer", "", "", "", "", ""],
+        ...     ["BP", "Shell", "H&M", "Unilever",
+        ...      "Std Dev", "Variance", "52w High", "52w Low", ""]
+        ... ])
+        >>> iidx = pd.MultiIndex.from_arrays([
+        ...     ["Equity", "Equity", "Equity", "Equity"],
+        ...     ["Energy", "Energy", "Consumer", "Consumer"],
+        ...     ["BP", "Shell", "H&M", "Unilever"]
+        ... ])
+        >>> styler = pd.DataFrame([
+        ...     [1, 0.8, 0.66, 0.72, 32.1678, 32.1678**2, 335.12, 240.89, "Buy"],
+        ...     [0.8, 1.0, 0.69, 0.79, 1.876, 1.876**2, 14.12, 19.78, "Hold"],
+        ...     [0.66, 0.69, 1.0, 0.86, 7, 7**2, 210.9, 140.6, "Buy"],
+        ...     [0.72, 0.79, 0.86, 1.0, 213.76, 213.76**2, 2807, 3678, "Sell"],
+        ... ], columns=cidx, index=iidx).style
+
+        Second we will format the display and, since our table is quite wide, will
+        hide the repeated level-0 of the index:
+
+        >>> (styler.format(subset="Equity", precision=2)
+        ...       .format(subset="Stats", precision=1, thousands=",")
+        ...       .format(subset="Rating", formatter=str.upper)
+        ...       .format_index(escape="latex", axis=1)
+        ...       .format_index(escape="latex", axis=0)
+        ...       .hide(level=0, axis=0))  # doctest: +SKIP
+
+        Note that one of the string entries of the index and column headers is "H&M".
+        Without applying the `escape="latex"` option to the `format_index` method the
+        resultant LaTeX will fail to render, and the error returned is quite
+        difficult to debug. Using the appropriate escape the "&" is converted to "\\&".
+
+        Thirdly we will apply some (CSS-HTML) styles to our object. We will use a
+        builtin method and also define our own method to highlight the stock
+        recommendation:
+
+        >>> def rating_color(v):
+        ...     if v == "Buy": color = "#33ff85"
+        ...     elif v == "Sell": color = "#ff5933"
+        ...     else: color = "#ffdd33"
+        ...     return f"color: {color}; font-weight: bold;"
+        >>> (styler.background_gradient(cmap="inferno", subset="Equity", vmin=0, vmax=1)
+        ...       .map(rating_color, subset="Rating"))  # doctest: +SKIP
+
+        All the above styles will work with HTML (see below) and LaTeX upon conversion:
+
+        .. figure:: ../../_static/style/latex_stocks_html.png
+
+        However, we finally want to add one LaTeX only style
+        (from the {graphicx} package), that is not easy to convert from CSS and
+        pandas does not support it. Notice the `--latex` flag used here,
+        as well as `--rwrap` to ensure this is formatted correctly and
+        not ignored upon conversion.
+
+        >>> styler.map_index(
+        ...     lambda v: "rotatebox:{45}--rwrap--latex;", level=2, axis=1
+        ... )  # doctest: +SKIP
+
+        Finally we render our LaTeX adding in other options as required:
+
+        >>> styler.to_latex(
+        ...     caption="Selected stock correlation and simple statistics.",
+        ...     clines="skip-last;data",
+        ...     convert_css=True,
+        ...     position_float="centering",
+        ...     multicol_align="|c|",
+        ...     hrules=True,
+        ... )  # doctest: +SKIP
+        \begin{table}
+        \centering
+        \caption{Selected stock correlation and simple statistics.}
+        \begin{tabular}{llrrrrrrrrl}
+        \toprule
+         &  & \multicolumn{4}{|c|}{Equity} & \multicolumn{4}{|c|}{Stats} & Rating \\
+         &  & \multicolumn{2}{|c|}{Energy} & \multicolumn{2}{|c|}{Consumer} &
+        \multicolumn{4}{|c|}{} &  \\
+         &  & \rotatebox{45}{BP} & \rotatebox{45}{Shell} & \rotatebox{45}{H\&M} &
+        \rotatebox{45}{Unilever} & \rotatebox{45}{Std Dev} & \rotatebox{45}{Variance} &
+        \rotatebox{45}{52w High} & \rotatebox{45}{52w Low} & \rotatebox{45}{} \\
+        \midrule
+        \multirow[c]{2}{*}{Energy} & BP & {\cellcolor[HTML]{FCFFA4}}
+        \color[HTML]{000000} 1.00 & {\cellcolor[HTML]{FCA50A}} \color[HTML]{000000}
+        0.80 & {\cellcolor[HTML]{EB6628}} \color[HTML]{F1F1F1} 0.66 &
+        {\cellcolor[HTML]{F68013}} \color[HTML]{F1F1F1} 0.72 & 32.2 & 1,034.8 & 335.1
+        & 240.9 & \color[HTML]{33FF85} \bfseries BUY \\
+         & Shell & {\cellcolor[HTML]{FCA50A}} \color[HTML]{000000} 0.80 &
+        {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 &
+        {\cellcolor[HTML]{F1731D}} \color[HTML]{F1F1F1} 0.69 &
+        {\cellcolor[HTML]{FCA108}} \color[HTML]{000000} 0.79 & 1.9 & 3.5 & 14.1 &
+        19.8 & \color[HTML]{FFDD33} \bfseries HOLD \\
+        \cline{1-11}
+        \multirow[c]{2}{*}{Consumer} & H\&M & {\cellcolor[HTML]{EB6628}}
+        \color[HTML]{F1F1F1} 0.66 & {\cellcolor[HTML]{F1731D}} \color[HTML]{F1F1F1}
+        0.69 & {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 &
+        {\cellcolor[HTML]{FAC42A}} \color[HTML]{000000} 0.86 & 7.0 & 49.0 & 210.9 &
+        140.6 & \color[HTML]{33FF85} \bfseries BUY \\
+         & Unilever & {\cellcolor[HTML]{F68013}} \color[HTML]{F1F1F1} 0.72 &
+        {\cellcolor[HTML]{FCA108}} \color[HTML]{000000} 0.79 &
+        {\cellcolor[HTML]{FAC42A}} \color[HTML]{000000} 0.86 &
+        {\cellcolor[HTML]{FCFFA4}} \color[HTML]{000000} 1.00 & 213.8 & 45,693.3 &
+        2,807.0 & 3,678.0 & \color[HTML]{FF5933} \bfseries SELL \\
+        \cline{1-11}
+        \bottomrule
+        \end{tabular}
+        \end{table}
+
+        .. figure:: ../../_static/style/latex_stocks.png
+        """
+        obj = self._copy(deepcopy=True)  # manipulate table_styles on obj, not self
+
+        table_selectors = (
+            [style["selector"] for style in self.table_styles]
+            if self.table_styles is not None
+            else []
+        )
+
+        if column_format is not None:
+            # add more recent setting to table_styles
+            obj.set_table_styles(
+                [{"selector": "column_format", "props": f":{column_format}"}],
+                overwrite=False,
+            )
+        elif "column_format" in table_selectors:
+            pass  # adopt what has been previously set in table_styles
+        else:
+            # create a default: set float, complex, int cols to 'r' ('S'), index to 'l'
+            _original_columns = self.data.columns
+            self.data.columns = RangeIndex(stop=len(self.data.columns))
+            numeric_cols = self.data._get_numeric_data().columns.to_list()
+            self.data.columns = _original_columns
+            column_format = ""
+            for level in range(self.index.nlevels):
+                column_format += "" if self.hide_index_[level] else "l"
+            for ci, _ in enumerate(self.data.columns):
+                if ci not in self.hidden_columns:
+                    column_format += (
+                        ("r" if not siunitx else "S") if ci in numeric_cols else "l"
+                    )
+            obj.set_table_styles(
+                [{"selector": "column_format", "props": f":{column_format}"}],
+                overwrite=False,
+            )
+
+        if position:
+            obj.set_table_styles(
+                [{"selector": "position", "props": f":{position}"}],
+                overwrite=False,
+            )
+
+        if position_float:
+            if environment == "longtable":
+                raise ValueError(
+                    "`position_float` cannot be used in 'longtable' `environment`"
+                )
+            if position_float not in ["raggedright", "raggedleft", "centering"]:
+                raise ValueError(
+                    f"`position_float` should be one of "
+                    f"'raggedright', 'raggedleft', 'centering', "
+                    f"got: '{position_float}'"
+                )
+            obj.set_table_styles(
+                [{"selector": "position_float", "props": f":{position_float}"}],
+                overwrite=False,
+            )
+
+        hrules = get_option("styler.latex.hrules") if hrules is None else hrules
+        if hrules:
+            obj.set_table_styles(
+                [
+                    {"selector": "toprule", "props": ":toprule"},
+                    {"selector": "midrule", "props": ":midrule"},
+                    {"selector": "bottomrule", "props": ":bottomrule"},
+                ],
+                overwrite=False,
+            )
+
+        if label:
+            obj.set_table_styles(
+                [{"selector": "label", "props": f":{{{label.replace(':', '§')}}}"}],
+                overwrite=False,
+            )
+
+        if caption:
+            obj.set_caption(caption)
+
+        if sparse_index is None:
+            sparse_index = get_option("styler.sparse.index")
+        if sparse_columns is None:
+            sparse_columns = get_option("styler.sparse.columns")
+        environment = environment or get_option("styler.latex.environment")
+        multicol_align = multicol_align or get_option("styler.latex.multicol_align")
+        multirow_align = multirow_align or get_option("styler.latex.multirow_align")
+        latex = obj._render_latex(
+            sparse_index=sparse_index,
+            sparse_columns=sparse_columns,
+            multirow_align=multirow_align,
+            multicol_align=multicol_align,
+            environment=environment,
+            convert_css=convert_css,
+            siunitx=siunitx,
+            clines=clines,
+        )
+
+        encoding = (
+            (encoding or get_option("styler.render.encoding"))
+            if isinstance(buf, str)  # i.e. a filepath
+            else encoding
+        )
+        return save_to_buffer(latex, buf=buf, encoding=encoding)
+
+    @overload
+    def to_html(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        *,
+        table_uuid: str | None = ...,
+        table_attributes: str | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        bold_headers: bool = ...,
+        caption: str | None = ...,
+        max_rows: int | None = ...,
+        max_columns: int | None = ...,
+        encoding: str | None = ...,
+        doctype_html: bool = ...,
+        exclude_styles: bool = ...,
+        **kwargs,
+    ) -> None:
+        ...
+
+    @overload
+    def to_html(
+        self,
+        buf: None = ...,
+        *,
+        table_uuid: str | None = ...,
+        table_attributes: str | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        bold_headers: bool = ...,
+        caption: str | None = ...,
+        max_rows: int | None = ...,
+        max_columns: int | None = ...,
+        encoding: str | None = ...,
+        doctype_html: bool = ...,
+        exclude_styles: bool = ...,
+        **kwargs,
+    ) -> str:
+        ...
+
+    @Substitution(buf=buffering_args, encoding=encoding_args)
+    def to_html(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        *,
+        table_uuid: str | None = None,
+        table_attributes: str | None = None,
+        sparse_index: bool | None = None,
+        sparse_columns: bool | None = None,
+        bold_headers: bool = False,
+        caption: str | None = None,
+        max_rows: int | None = None,
+        max_columns: int | None = None,
+        encoding: str | None = None,
+        doctype_html: bool = False,
+        exclude_styles: bool = False,
+        **kwargs,
+    ) -> str | None:
+        """
+        Write Styler to a file, buffer or string in HTML-CSS format.
+
+        .. versionadded:: 1.3.0
+
+        Parameters
+        ----------
+        %(buf)s
+        table_uuid : str, optional
+            Id attribute assigned to the  HTML element in the format:
+
+            ``
``
+
+            If not given uses Styler's initially assigned value.
+        table_attributes : str, optional
+            Attributes to assign within the `
` HTML element in the format:
+
+            ``
 >``
+
+            If not given defaults to Styler's preexisting value.
+        sparse_index : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each row.
+            Defaults to ``pandas.options.styler.sparse.index`` value.
+
+            .. versionadded:: 1.4.0
+        sparse_columns : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each
+            column. Defaults to ``pandas.options.styler.sparse.columns`` value.
+
+            .. versionadded:: 1.4.0
+        bold_headers : bool, optional
+            Adds "font-weight: bold;" as a CSS property to table style header cells.
+
+            .. versionadded:: 1.4.0
+        caption : str, optional
+            Set, or overwrite, the caption on Styler before rendering.
+
+            .. versionadded:: 1.4.0
+        max_rows : int, optional
+            The maximum number of rows that will be rendered. Defaults to
+            ``pandas.options.styler.render.max_rows/max_columns``.
+
+            .. versionadded:: 1.4.0
+        max_columns : int, optional
+            The maximum number of columns that will be rendered. Defaults to
+            ``pandas.options.styler.render.max_columns``, which is None.
+
+            Rows and columns may be reduced if the number of total elements is
+            large. This value is set to ``pandas.options.styler.render.max_elements``,
+            which is 262144 (18 bit browser rendering).
+
+            .. versionadded:: 1.4.0
+        %(encoding)s
+        doctype_html : bool, default False
+            Whether to output a fully structured HTML file including all
+            HTML elements, or just the core ``
+        

+          
+            
+              
+              
+              
+            
+        ...
+        """
+        obj = self._copy(deepcopy=True)  # manipulate table_styles on obj, not self
+
+        if table_uuid:
+            obj.set_uuid(table_uuid)
+
+        if table_attributes:
+            obj.set_table_attributes(table_attributes)
+
+        if sparse_index is None:
+            sparse_index = get_option("styler.sparse.index")
+        if sparse_columns is None:
+            sparse_columns = get_option("styler.sparse.columns")
+
+        if bold_headers:
+            obj.set_table_styles(
+                [{"selector": "th", "props": "font-weight: bold;"}], overwrite=False
+            )
+
+        if caption is not None:
+            obj.set_caption(caption)
+
+        # Build HTML string..
+        html = obj._render_html(
+            sparse_index=sparse_index,
+            sparse_columns=sparse_columns,
+            max_rows=max_rows,
+            max_cols=max_columns,
+            exclude_styles=exclude_styles,
+            encoding=encoding or get_option("styler.render.encoding"),
+            doctype_html=doctype_html,
+            **kwargs,
+        )
+
+        return save_to_buffer(
+            html, buf=buf, encoding=(encoding if buf is not None else None)
+        )
+
+    @overload
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str],
+        *,
+        encoding: str | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        max_rows: int | None = ...,
+        max_columns: int | None = ...,
+        delimiter: str = ...,
+    ) -> None:
+        ...
+
+    @overload
+    def to_string(
+        self,
+        buf: None = ...,
+        *,
+        encoding: str | None = ...,
+        sparse_index: bool | None = ...,
+        sparse_columns: bool | None = ...,
+        max_rows: int | None = ...,
+        max_columns: int | None = ...,
+        delimiter: str = ...,
+    ) -> str:
+        ...
+
+    @Substitution(buf=buffering_args, encoding=encoding_args)
+    def to_string(
+        self,
+        buf: FilePath | WriteBuffer[str] | None = None,
+        *,
+        encoding: str | None = None,
+        sparse_index: bool | None = None,
+        sparse_columns: bool | None = None,
+        max_rows: int | None = None,
+        max_columns: int | None = None,
+        delimiter: str = " ",
+    ) -> str | None:
+        """
+        Write Styler to a file, buffer or string in text format.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        %(buf)s
+        %(encoding)s
+        sparse_index : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each row.
+            Defaults to ``pandas.options.styler.sparse.index`` value.
+        sparse_columns : bool, optional
+            Whether to sparsify the display of a hierarchical index. Setting to False
+            will display each explicit level element in a hierarchical key for each
+            column. Defaults to ``pandas.options.styler.sparse.columns`` value.
+        max_rows : int, optional
+            The maximum number of rows that will be rendered. Defaults to
+            ``pandas.options.styler.render.max_rows``, which is None.
+        max_columns : int, optional
+            The maximum number of columns that will be rendered. Defaults to
+            ``pandas.options.styler.render.max_columns``, which is None.
+
+            Rows and columns may be reduced if the number of total elements is
+            large. This value is set to ``pandas.options.styler.render.max_elements``,
+            which is 262144 (18 bit browser rendering).
+        delimiter : str, default single space
+            The separator between data elements.
+
+        Returns
+        -------
+        str or None
+            If `buf` is None, returns the result as a string. Otherwise returns `None`.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+        >>> df.style.to_string()
+        ' A B\\n0 1 3\\n1 2 4\\n'
+        """
+        obj = self._copy(deepcopy=True)
+
+        if sparse_index is None:
+            sparse_index = get_option("styler.sparse.index")
+        if sparse_columns is None:
+            sparse_columns = get_option("styler.sparse.columns")
+
+        text = obj._render_string(
+            sparse_columns=sparse_columns,
+            sparse_index=sparse_index,
+            max_rows=max_rows,
+            max_cols=max_columns,
+            delimiter=delimiter,
+        )
+        return save_to_buffer(
+            text, buf=buf, encoding=(encoding if buf is not None else None)
+        )
+
+    def set_td_classes(self, classes: DataFrame) -> Styler:
+        """
+        Set the ``class`` attribute of ``
 AB
`` HTML elements.
+
+        Parameters
+        ----------
+        classes : DataFrame
+            DataFrame containing strings that will be translated to CSS classes,
+            mapped by identical column and index key values that must exist on the
+            underlying Styler data. None, NaN values, and empty strings will
+            be ignored and not affect the rendered HTML.
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.set_table_styles: Set the table styles included within the ``'
+        ''
+        '  '
+        '    '
+        '  '
+        '  '
+        '    '
+        '  '
+        '
0
1
'
+        """
+        if not classes.index.is_unique or not classes.columns.is_unique:
+            raise KeyError(
+                "Classes render only if `classes` has unique index and columns."
+            )
+        classes = classes.reindex_like(self.data)
+
+        for r, row_tup in enumerate(classes.itertuples()):
+            for c, value in enumerate(row_tup[1:]):
+                if not (pd.isna(value) or value == ""):
+                    self.cell_context[(r, c)] = str(value)
+
+        return self
+
+    def _update_ctx(self, attrs: DataFrame) -> None:
+        """
+        Update the state of the ``Styler`` for data cells.
+
+        Collects a mapping of {index_label: [('', ''), ..]}.
+
+        Parameters
+        ----------
+        attrs : DataFrame
+            should contain strings of ': ;: '
+            Whitespace shouldn't matter and the final trailing ';' shouldn't
+            matter.
+        """
+        if not self.index.is_unique or not self.columns.is_unique:
+            raise KeyError(
+                "`Styler.apply` and `.map` are not compatible "
+                "with non-unique index or columns."
+            )
+
+        for cn in attrs.columns:
+            j = self.columns.get_loc(cn)
+            ser = attrs[cn]
+            for rn, c in ser.items():
+                if not c or pd.isna(c):
+                    continue
+                css_list = maybe_convert_css_to_tuples(c)
+                i = self.index.get_loc(rn)
+                self.ctx[(i, j)].extend(css_list)
+
+    def _update_ctx_header(self, attrs: DataFrame, axis: AxisInt) -> None:
+        """
+        Update the state of the ``Styler`` for header cells.
+
+        Collects a mapping of {index_label: [('', ''), ..]}.
+
+        Parameters
+        ----------
+        attrs : Series
+            Should contain strings of ': ;: ', and an
+            integer index.
+            Whitespace shouldn't matter and the final trailing ';' shouldn't
+            matter.
+        axis : int
+            Identifies whether the ctx object being updated is the index or columns
+        """
+        for j in attrs.columns:
+            ser = attrs[j]
+            for i, c in ser.items():
+                if not c or pd.isna(c):
+                    continue
+                css_list = maybe_convert_css_to_tuples(c)
+                if axis == 0:
+                    self.ctx_index[(i, j)].extend(css_list)
+                else:
+                    self.ctx_columns[(j, i)].extend(css_list)
+
+    def _copy(self, deepcopy: bool = False) -> Styler:
+        """
+        Copies a Styler, allowing for deepcopy or shallow copy
+
+        Copying a Styler aims to recreate a new Styler object which contains the same
+        data and styles as the original.
+
+        Data dependent attributes [copied and NOT exported]:
+          - formatting (._display_funcs)
+          - hidden index values or column values (.hidden_rows, .hidden_columns)
+          - tooltips
+          - cell_context (cell css classes)
+          - ctx (cell css styles)
+          - caption
+          - concatenated stylers
+
+        Non-data dependent attributes [copied and exported]:
+          - css
+          - hidden index state and hidden columns state (.hide_index_, .hide_columns_)
+          - table_attributes
+          - table_styles
+          - applied styles (_todo)
+
+        """
+        # GH 40675, 52728
+        styler = type(self)(
+            self.data,  # populates attributes 'data', 'columns', 'index' as shallow
+        )
+        shallow = [  # simple string or boolean immutables
+            "hide_index_",
+            "hide_columns_",
+            "hide_column_names",
+            "hide_index_names",
+            "table_attributes",
+            "cell_ids",
+            "caption",
+            "uuid",
+            "uuid_len",
+            "template_latex",  # also copy templates if these have been customised
+            "template_html_style",
+            "template_html_table",
+            "template_html",
+        ]
+        deep = [  # nested lists or dicts
+            "css",
+            "concatenated",
+            "_display_funcs",
+            "_display_funcs_index",
+            "_display_funcs_columns",
+            "hidden_rows",
+            "hidden_columns",
+            "ctx",
+            "ctx_index",
+            "ctx_columns",
+            "cell_context",
+            "_todo",
+            "table_styles",
+            "tooltips",
+        ]
+
+        for attr in shallow:
+            setattr(styler, attr, getattr(self, attr))
+
+        for attr in deep:
+            val = getattr(self, attr)
+            setattr(styler, attr, copy.deepcopy(val) if deepcopy else val)
+
+        return styler
+
+    def __copy__(self) -> Styler:
+        return self._copy(deepcopy=False)
+
+    def __deepcopy__(self, memo) -> Styler:
+        return self._copy(deepcopy=True)
+
+    def clear(self) -> None:
+        """
+        Reset the ``Styler``, removing any previously applied styles.
+
+        Returns None.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({'A': [1, 2], 'B': [3, np.nan]})
+
+        After any added style:
+
+        >>> df.style.highlight_null(color='yellow')  # doctest: +SKIP
+
+        Remove it with:
+
+        >>> df.style.clear()  # doctest: +SKIP
+
+        Please see:
+        `Table Visualization <../../user_guide/style.ipynb>`_ for more examples.
+        """
+        # create default GH 40675
+        clean_copy = Styler(self.data, uuid=self.uuid)
+        clean_attrs = [a for a in clean_copy.__dict__ if not callable(a)]
+        self_attrs = [a for a in self.__dict__ if not callable(a)]  # maybe more attrs
+        for attr in clean_attrs:
+            setattr(self, attr, getattr(clean_copy, attr))
+        for attr in set(self_attrs).difference(clean_attrs):
+            delattr(self, attr)
+
+    def _apply(
+        self,
+        func: Callable,
+        axis: Axis | None = 0,
+        subset: Subset | None = None,
+        **kwargs,
+    ) -> Styler:
+        subset = slice(None) if subset is None else subset
+        subset = non_reducing_slice(subset)
+        data = self.data.loc[subset]
+        if data.empty:
+            result = DataFrame()
+        elif axis is None:
+            result = func(data, **kwargs)
+            if not isinstance(result, DataFrame):
+                if not isinstance(result, np.ndarray):
+                    raise TypeError(
+                        f"Function {repr(func)} must return a DataFrame or ndarray "
+                        f"when passed to `Styler.apply` with axis=None"
+                    )
+                if data.shape != result.shape:
+                    raise ValueError(
+                        f"Function {repr(func)} returned ndarray with wrong shape.\n"
+                        f"Result has shape: {result.shape}\n"
+                        f"Expected shape: {data.shape}"
+                    )
+                result = DataFrame(result, index=data.index, columns=data.columns)
+        else:
+            axis = self.data._get_axis_number(axis)
+            if axis == 0:
+                result = data.apply(func, axis=0, **kwargs)
+            else:
+                result = data.T.apply(func, axis=0, **kwargs).T  # see GH 42005
+
+        if isinstance(result, Series):
+            raise ValueError(
+                f"Function {repr(func)} resulted in the apply method collapsing to a "
+                f"Series.\nUsually, this is the result of the function returning a "
+                f"single value, instead of list-like."
+            )
+        msg = (
+            f"Function {repr(func)} created invalid {{0}} labels.\nUsually, this is "
+            f"the result of the function returning a "
+            f"{'Series' if axis is not None else 'DataFrame'} which contains invalid "
+            f"labels, or returning an incorrectly shaped, list-like object which "
+            f"cannot be mapped to labels, possibly due to applying the function along "
+            f"the wrong axis.\n"
+            f"Result {{0}} has shape: {{1}}\n"
+            f"Expected {{0}} shape:   {{2}}"
+        )
+        if not all(result.index.isin(data.index)):
+            raise ValueError(msg.format("index", result.index.shape, data.index.shape))
+        if not all(result.columns.isin(data.columns)):
+            raise ValueError(
+                msg.format("columns", result.columns.shape, data.columns.shape)
+            )
+        self._update_ctx(result)
+        return self
+
+    @Substitution(subset=subset_args)
+    def apply(
+        self,
+        func: Callable,
+        axis: Axis | None = 0,
+        subset: Subset | None = None,
+        **kwargs,
+    ) -> Styler:
+        """
+        Apply a CSS-styling function column-wise, row-wise, or table-wise.
+
+        Updates the HTML representation with the result.
+
+        Parameters
+        ----------
+        func : function
+            ``func`` should take a Series if ``axis`` in [0,1] and return a list-like
+            object of same length, or a Series, not necessarily of same length, with
+            valid index labels considering ``subset``.
+            ``func`` should take a DataFrame if ``axis`` is ``None`` and return either
+            an ndarray with the same shape or a DataFrame, not necessarily of the same
+            shape, with valid index and columns labels considering ``subset``.
+
+            .. versionchanged:: 1.3.0
+
+            .. versionchanged:: 1.4.0
+
+        axis : {0 or 'index', 1 or 'columns', None}, default 0
+            Apply to each column (``axis=0`` or ``'index'``), to each row
+            (``axis=1`` or ``'columns'``), or to the entire DataFrame at once
+            with ``axis=None``.
+        %(subset)s
+        **kwargs : dict
+            Pass along to ``func``.
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.map_index: Apply a CSS-styling function to headers elementwise.
+        Styler.apply_index: Apply a CSS-styling function to headers level-wise.
+        Styler.map: Apply a CSS-styling function elementwise.
+
+        Notes
+        -----
+        The elements of the output of ``func`` should be CSS styles as strings, in the
+        format 'attribute: value; attribute2: value2; ...' or,
+        if nothing is to be applied to that element, an empty string or ``None``.
+
+        This is similar to ``DataFrame.apply``, except that ``axis=None``
+        applies the function to the entire DataFrame at once,
+        rather than column-wise or row-wise.
+
+        Examples
+        --------
+        >>> def highlight_max(x, color):
+        ...     return np.where(x == np.nanmax(x.to_numpy()), f"color: {color};", None)
+        >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"])
+        >>> df.style.apply(highlight_max, color='red')  # doctest: +SKIP
+        >>> df.style.apply(highlight_max, color='blue', axis=1)  # doctest: +SKIP
+        >>> df.style.apply(highlight_max, color='green', axis=None)  # doctest: +SKIP
+
+        Using ``subset`` to restrict application to a single column or multiple columns
+
+        >>> df.style.apply(highlight_max, color='red', subset="A")
+        ... # doctest: +SKIP
+        >>> df.style.apply(highlight_max, color='red', subset=["A", "B"])
+        ... # doctest: +SKIP
+
+        Using a 2d input to ``subset`` to select rows in addition to columns
+
+        >>> df.style.apply(highlight_max, color='red', subset=([0, 1, 2], slice(None)))
+        ... # doctest: +SKIP
+        >>> df.style.apply(highlight_max, color='red', subset=(slice(0, 5, 2), "A"))
+        ... # doctest: +SKIP
+
+        Using a function which returns a Series / DataFrame of unequal length but
+        containing valid index labels
+
+        >>> df = pd.DataFrame([[1, 2], [3, 4], [4, 6]], index=["A1", "A2", "Total"])
+        >>> total_style = pd.Series("font-weight: bold;", index=["Total"])
+        >>> df.style.apply(lambda s: total_style)  # doctest: +SKIP
+
+        See `Table Visualization <../../user_guide/style.ipynb>`_ user guide for
+        more details.
+        """
+        self._todo.append(
+            (lambda instance: getattr(instance, "_apply"), (func, axis, subset), kwargs)
+        )
+        return self
+
+    def _apply_index(
+        self,
+        func: Callable,
+        axis: Axis = 0,
+        level: Level | list[Level] | None = None,
+        method: str = "apply",
+        **kwargs,
+    ) -> Styler:
+        axis = self.data._get_axis_number(axis)
+        obj = self.index if axis == 0 else self.columns
+
+        levels_ = refactor_levels(level, obj)
+        data = DataFrame(obj.to_list()).loc[:, levels_]
+
+        if method == "apply":
+            result = data.apply(func, axis=0, **kwargs)
+        elif method == "map":
+            result = data.map(func, **kwargs)
+
+        self._update_ctx_header(result, axis)
+        return self
+
+    @doc(
+        this="apply",
+        wise="level-wise",
+        alt="map",
+        altwise="elementwise",
+        func="take a Series and return a string array of the same length",
+        input_note="the index as a Series, if an Index, or a level of a MultiIndex",
+        output_note="an identically sized array of CSS styles as strings",
+        var="s",
+        ret='np.where(s == "B", "background-color: yellow;", "")',
+        ret2='["background-color: yellow;" if "x" in v else "" for v in s]',
+    )
+    def apply_index(
+        self,
+        func: Callable,
+        axis: AxisInt | str = 0,
+        level: Level | list[Level] | None = None,
+        **kwargs,
+    ) -> Styler:
+        """
+        Apply a CSS-styling function to the index or column headers, {wise}.
+
+        Updates the HTML representation with the result.
+
+        .. versionadded:: 1.4.0
+
+        .. versionadded:: 2.1.0
+           Styler.applymap_index was deprecated and renamed to Styler.map_index.
+
+        Parameters
+        ----------
+        func : function
+            ``func`` should {func}.
+        axis : {{0, 1, "index", "columns"}}
+            The headers over which to apply the function.
+        level : int, str, list, optional
+            If index is MultiIndex the level(s) over which to apply the function.
+        **kwargs : dict
+            Pass along to ``func``.
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.{alt}_index: Apply a CSS-styling function to headers {altwise}.
+        Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise.
+        Styler.map: Apply a CSS-styling function elementwise.
+
+        Notes
+        -----
+        Each input to ``func`` will be {input_note}. The output of ``func`` should be
+        {output_note}, in the format 'attribute: value; attribute2: value2; ...'
+        or, if nothing is to be applied to that element, an empty string or ``None``.
+
+        Examples
+        --------
+        Basic usage to conditionally highlight values in the index.
+
+        >>> df = pd.DataFrame([[1,2], [3,4]], index=["A", "B"])
+        >>> def color_b(s):
+        ...     return {ret}
+        >>> df.style.{this}_index(color_b)  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/appmaphead1.png
+
+        Selectively applying to specific levels of MultiIndex columns.
+
+        >>> midx = pd.MultiIndex.from_product([['ix', 'jy'], [0, 1], ['x3', 'z4']])
+        >>> df = pd.DataFrame([np.arange(8)], columns=midx)
+        >>> def highlight_x({var}):
+        ...     return {ret2}
+        >>> df.style.{this}_index(highlight_x, axis="columns", level=[0, 2])
+        ...  # doctest: +SKIP
+
+        .. figure:: ../../_static/style/appmaphead2.png
+        """
+        self._todo.append(
+            (
+                lambda instance: getattr(instance, "_apply_index"),
+                (func, axis, level, "apply"),
+                kwargs,
+            )
+        )
+        return self
+
+    @doc(
+        apply_index,
+        this="map",
+        wise="elementwise",
+        alt="apply",
+        altwise="level-wise",
+        func="take a scalar and return a string",
+        input_note="an index value, if an Index, or a level value of a MultiIndex",
+        output_note="CSS styles as a string",
+        var="v",
+        ret='"background-color: yellow;" if v == "B" else None',
+        ret2='"background-color: yellow;" if "x" in v else None',
+    )
+    def map_index(
+        self,
+        func: Callable,
+        axis: AxisInt | str = 0,
+        level: Level | list[Level] | None = None,
+        **kwargs,
+    ) -> Styler:
+        self._todo.append(
+            (
+                lambda instance: getattr(instance, "_apply_index"),
+                (func, axis, level, "map"),
+                kwargs,
+            )
+        )
+        return self
+
+    def applymap_index(
+        self,
+        func: Callable,
+        axis: AxisInt | str = 0,
+        level: Level | list[Level] | None = None,
+        **kwargs,
+    ) -> Styler:
+        """
+        Apply a CSS-styling function to the index or column headers, elementwise.
+
+        .. deprecated:: 2.1.0
+
+           Styler.applymap_index has been deprecated. Use Styler.map_index instead.
+
+        Parameters
+        ----------
+        func : function
+            ``func`` should take a scalar and return a string.
+        axis : {{0, 1, "index", "columns"}}
+            The headers over which to apply the function.
+        level : int, str, list, optional
+            If index is MultiIndex the level(s) over which to apply the function.
+        **kwargs : dict
+            Pass along to ``func``.
+
+        Returns
+        -------
+        Styler
+        """
+        warnings.warn(
+            "Styler.applymap_index has been deprecated. Use Styler.map_index instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.map_index(func, axis, level, **kwargs)
+
+    def _map(self, func: Callable, subset: Subset | None = None, **kwargs) -> Styler:
+        func = partial(func, **kwargs)  # map doesn't take kwargs?
+        if subset is None:
+            subset = IndexSlice[:]
+        subset = non_reducing_slice(subset)
+        result = self.data.loc[subset].map(func)
+        self._update_ctx(result)
+        return self
+
+    @Substitution(subset=subset_args)
+    def map(self, func: Callable, subset: Subset | None = None, **kwargs) -> Styler:
+        """
+        Apply a CSS-styling function elementwise.
+
+        Updates the HTML representation with the result.
+
+        Parameters
+        ----------
+        func : function
+            ``func`` should take a scalar and return a string.
+        %(subset)s
+        **kwargs : dict
+            Pass along to ``func``.
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.map_index: Apply a CSS-styling function to headers elementwise.
+        Styler.apply_index: Apply a CSS-styling function to headers level-wise.
+        Styler.apply: Apply a CSS-styling function column-wise, row-wise, or table-wise.
+
+        Notes
+        -----
+        The elements of the output of ``func`` should be CSS styles as strings, in the
+        format 'attribute: value; attribute2: value2; ...' or,
+        if nothing is to be applied to that element, an empty string or ``None``.
+
+        Examples
+        --------
+        >>> def color_negative(v, color):
+        ...     return f"color: {color};" if v < 0 else None
+        >>> df = pd.DataFrame(np.random.randn(5, 2), columns=["A", "B"])
+        >>> df.style.map(color_negative, color='red')  # doctest: +SKIP
+
+        Using ``subset`` to restrict application to a single column or multiple columns
+
+        >>> df.style.map(color_negative, color='red', subset="A")
+        ...  # doctest: +SKIP
+        >>> df.style.map(color_negative, color='red', subset=["A", "B"])
+        ...  # doctest: +SKIP
+
+        Using a 2d input to ``subset`` to select rows in addition to columns
+
+        >>> df.style.map(color_negative, color='red',
+        ...  subset=([0,1,2], slice(None)))  # doctest: +SKIP
+        >>> df.style.map(color_negative, color='red', subset=(slice(0,5,2), "A"))
+        ...  # doctest: +SKIP
+
+        See `Table Visualization <../../user_guide/style.ipynb>`_ user guide for
+        more details.
+        """
+        self._todo.append(
+            (lambda instance: getattr(instance, "_map"), (func, subset), kwargs)
+        )
+        return self
+
+    @Substitution(subset=subset_args)
+    def applymap(
+        self, func: Callable, subset: Subset | None = None, **kwargs
+    ) -> Styler:
+        """
+        Apply a CSS-styling function elementwise.
+
+        .. deprecated:: 2.1.0
+
+           Styler.applymap has been deprecated. Use Styler.map instead.
+
+        Parameters
+        ----------
+        func : function
+            ``func`` should take a scalar and return a string.
+        %(subset)s
+        **kwargs : dict
+            Pass along to ``func``.
+
+        Returns
+        -------
+        Styler
+        """
+        warnings.warn(
+            "Styler.applymap has been deprecated. Use Styler.map instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        return self.map(func, subset, **kwargs)
+
+    def set_table_attributes(self, attributes: str) -> Styler:
+        """
+        Set the table attributes added to the ```` HTML element.
+
+        These are items in addition to automatic (by default) ``id`` attribute.
+
+        Parameters
+        ----------
+        attributes : str
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.set_table_styles: Set the table styles included within the `` block
+
+        Parameters
+        ----------
+        sparsify_index : bool
+            Whether index_headers section will add rowspan attributes (>1) to elements.
+
+        Returns
+        -------
+        body : list
+            The associated HTML elements needed for template rendering.
+        """
+        rlabels = self.data.index.tolist()
+        if not isinstance(self.data.index, MultiIndex):
+            rlabels = [[x] for x in rlabels]
+
+        body: list = []
+        visible_row_count: int = 0
+        for r, row_tup in [
+            z for z in enumerate(self.data.itertuples()) if z[0] not in self.hidden_rows
+        ]:
+            visible_row_count += 1
+            if self._check_trim(
+                visible_row_count,
+                max_rows,
+                body,
+                "row",
+            ):
+                break
+
+            body_row = self._generate_body_row(
+                (r, row_tup, rlabels), max_cols, idx_lengths
+            )
+            body.append(body_row)
+        return body
+
+    def _check_trim(
+        self,
+        count: int,
+        max: int,
+        obj: list,
+        element: str,
+        css: str | None = None,
+        value: str = "...",
+    ) -> bool:
+        """
+        Indicates whether to break render loops and append a trimming indicator
+
+        Parameters
+        ----------
+        count : int
+            The loop count of previous visible items.
+        max : int
+            The allowable rendered items in the loop.
+        obj : list
+            The current render collection of the rendered items.
+        element : str
+            The type of element to append in the case a trimming indicator is needed.
+        css : str, optional
+            The css to add to the trimming indicator element.
+        value : str, optional
+            The value of the elements display if necessary.
+
+        Returns
+        -------
+        result : bool
+            Whether a trimming element was required and appended.
+        """
+        if count > max:
+            if element == "row":
+                obj.append(self._generate_trimmed_row(max))
+            else:
+                obj.append(_element(element, css, value, True, attributes=""))
+            return True
+        return False
+
+    def _generate_trimmed_row(self, max_cols: int) -> list:
+        """
+        When a render has too many rows we generate a trimming row containing "..."
+
+        Parameters
+        ----------
+        max_cols : int
+            Number of permissible columns
+
+        Returns
+        -------
+        list of elements
+        """
+        index_headers = [
+            _element(
+                "th",
+                (
+                    f"{self.css['row_heading']} {self.css['level']}{c} "
+                    f"{self.css['row_trim']}"
+                ),
+                "...",
+                not self.hide_index_[c],
+                attributes="",
+            )
+            for c in range(self.data.index.nlevels)
+        ]
+
+        data: list = []
+        visible_col_count: int = 0
+        for c, _ in enumerate(self.columns):
+            data_element_visible = c not in self.hidden_columns
+            if data_element_visible:
+                visible_col_count += 1
+            if self._check_trim(
+                visible_col_count,
+                max_cols,
+                data,
+                "td",
+                f"{self.css['data']} {self.css['row_trim']} {self.css['col_trim']}",
+            ):
+                break
+
+            data.append(
+                _element(
+                    "td",
+                    f"{self.css['data']} {self.css['col']}{c} {self.css['row_trim']}",
+                    "...",
+                    data_element_visible,
+                    attributes="",
+                )
+            )
+
+        return index_headers + data
+
+    def _generate_body_row(
+        self,
+        iter: tuple,
+        max_cols: int,
+        idx_lengths: dict,
+    ):
+        """
+        Generate a regular row for the body section of appropriate format.
+
+          +--------------------------------------------+---------------------------+
+          |  index_header_0    ...    index_header_n   |  data_by_column   ...     |
+          +--------------------------------------------+---------------------------+
+
+        Parameters
+        ----------
+        iter : tuple
+            Iterable from outer scope: row number, row data tuple, row index labels.
+        max_cols : int
+            Number of permissible columns.
+        idx_lengths : dict
+            A map of the sparsification structure of the index
+
+        Returns
+        -------
+            list of elements
+        """
+        r, row_tup, rlabels = iter
+
+        index_headers = []
+        for c, value in enumerate(rlabels[r]):
+            header_element_visible = (
+                _is_visible(r, c, idx_lengths) and not self.hide_index_[c]
+            )
+            header_element = _element(
+                "th",
+                (
+                    f"{self.css['row_heading']} {self.css['level']}{c} "
+                    f"{self.css['row']}{r}"
+                ),
+                value,
+                header_element_visible,
+                display_value=self._display_funcs_index[(r, c)](value),
+                attributes=(
+                    f'rowspan="{idx_lengths.get((c, r), 0)}"'
+                    if idx_lengths.get((c, r), 0) > 1
+                    else ""
+                ),
+            )
+
+            if self.cell_ids:
+                header_element[
+                    "id"
+                ] = f"{self.css['level']}{c}_{self.css['row']}{r}"  # id is given
+            if (
+                header_element_visible
+                and (r, c) in self.ctx_index
+                and self.ctx_index[r, c]
+            ):
+                # always add id if a style is specified
+                header_element["id"] = f"{self.css['level']}{c}_{self.css['row']}{r}"
+                self.cellstyle_map_index[tuple(self.ctx_index[r, c])].append(
+                    f"{self.css['level']}{c}_{self.css['row']}{r}"
+                )
+
+            index_headers.append(header_element)
+
+        data: list = []
+        visible_col_count: int = 0
+        for c, value in enumerate(row_tup[1:]):
+            data_element_visible = (
+                c not in self.hidden_columns and r not in self.hidden_rows
+            )
+            if data_element_visible:
+                visible_col_count += 1
+            if self._check_trim(
+                visible_col_count,
+                max_cols,
+                data,
+                "td",
+                f"{self.css['data']} {self.css['row']}{r} {self.css['col_trim']}",
+            ):
+                break
+
+            # add custom classes from cell context
+            cls = ""
+            if (r, c) in self.cell_context:
+                cls = " " + self.cell_context[r, c]
+
+            data_element = _element(
+                "td",
+                (
+                    f"{self.css['data']} {self.css['row']}{r} "
+                    f"{self.css['col']}{c}{cls}"
+                ),
+                value,
+                data_element_visible,
+                attributes="",
+                display_value=self._display_funcs[(r, c)](value),
+            )
+
+            if self.cell_ids:
+                data_element["id"] = f"{self.css['row']}{r}_{self.css['col']}{c}"
+            if data_element_visible and (r, c) in self.ctx and self.ctx[r, c]:
+                # always add id if needed due to specified style
+                data_element["id"] = f"{self.css['row']}{r}_{self.css['col']}{c}"
+                self.cellstyle_map[tuple(self.ctx[r, c])].append(
+                    f"{self.css['row']}{r}_{self.css['col']}{c}"
+                )
+
+            data.append(data_element)
+
+        return index_headers + data
+
+    def _translate_latex(self, d: dict, clines: str | None) -> None:
+        r"""
+        Post-process the default render dict for the LaTeX template format.
+
+        Processing items included are:
+          - Remove hidden columns from the non-headers part of the body.
+          - Place cellstyles directly in td cells rather than use cellstyle_map.
+          - Remove hidden indexes or reinsert missing th elements if part of multiindex
+            or multirow sparsification (so that \multirow and \multicol work correctly).
+        """
+        index_levels = self.index.nlevels
+        visible_index_level_n = index_levels - sum(self.hide_index_)
+        d["head"] = [
+            [
+                {**col, "cellstyle": self.ctx_columns[r, c - visible_index_level_n]}
+                for c, col in enumerate(row)
+                if col["is_visible"]
+            ]
+            for r, row in enumerate(d["head"])
+        ]
+
+        def _concatenated_visible_rows(obj, n, row_indices):
+            """
+            Extract all visible row indices recursively from concatenated stylers.
+            """
+            row_indices.extend(
+                [r + n for r in range(len(obj.index)) if r not in obj.hidden_rows]
+            )
+            n += len(obj.index)
+            for concatenated in obj.concatenated:
+                n = _concatenated_visible_rows(concatenated, n, row_indices)
+            return n
+
+        def concatenated_visible_rows(obj):
+            row_indices: list[int] = []
+            _concatenated_visible_rows(obj, 0, row_indices)
+            # TODO try to consolidate the concat visible rows
+            # methods to a single function / recursion for simplicity
+            return row_indices
+
+        body = []
+        for r, row in zip(concatenated_visible_rows(self), d["body"]):
+            # note: cannot enumerate d["body"] because rows were dropped if hidden
+            # during _translate_body so must zip to acquire the true r-index associated
+            # with the ctx obj which contains the cell styles.
+            if all(self.hide_index_):
+                row_body_headers = []
+            else:
+                row_body_headers = [
+                    {
+                        **col,
+                        "display_value": col["display_value"]
+                        if col["is_visible"]
+                        else "",
+                        "cellstyle": self.ctx_index[r, c],
+                    }
+                    for c, col in enumerate(row[:index_levels])
+                    if (col["type"] == "th" and not self.hide_index_[c])
+                ]
+
+            row_body_cells = [
+                {**col, "cellstyle": self.ctx[r, c]}
+                for c, col in enumerate(row[index_levels:])
+                if (col["is_visible"] and col["type"] == "td")
+            ]
+
+            body.append(row_body_headers + row_body_cells)
+        d["body"] = body
+
+        # clines are determined from info on index_lengths and hidden_rows and input
+        # to a dict defining which row clines should be added in the template.
+        if clines not in [
+            None,
+            "all;data",
+            "all;index",
+            "skip-last;data",
+            "skip-last;index",
+        ]:
+            raise ValueError(
+                f"`clines` value of {clines} is invalid. Should either be None or one "
+                f"of 'all;data', 'all;index', 'skip-last;data', 'skip-last;index'."
+            )
+        if clines is not None:
+            data_len = len(row_body_cells) if "data" in clines and d["body"] else 0
+
+            d["clines"] = defaultdict(list)
+            visible_row_indexes: list[int] = [
+                r for r in range(len(self.data.index)) if r not in self.hidden_rows
+            ]
+            visible_index_levels: list[int] = [
+                i for i in range(index_levels) if not self.hide_index_[i]
+            ]
+            for rn, r in enumerate(visible_row_indexes):
+                for lvln, lvl in enumerate(visible_index_levels):
+                    if lvl == index_levels - 1 and "skip-last" in clines:
+                        continue
+                    idx_len = d["index_lengths"].get((lvl, r), None)
+                    if idx_len is not None:  # i.e. not a sparsified entry
+                        d["clines"][rn + idx_len].append(
+                            f"\\cline{{{lvln+1}-{len(visible_index_levels)+data_len}}}"
+                        )
+
+    def format(
+        self,
+        formatter: ExtFormatter | None = None,
+        subset: Subset | None = None,
+        na_rep: str | None = None,
+        precision: int | None = None,
+        decimal: str = ".",
+        thousands: str | None = None,
+        escape: str | None = None,
+        hyperlinks: str | None = None,
+    ) -> StylerRenderer:
+        r"""
+        Format the text display value of cells.
+
+        Parameters
+        ----------
+        formatter : str, callable, dict or None
+            Object to define how values are displayed. See notes.
+        subset : label, array-like, IndexSlice, optional
+            A valid 2d input to `DataFrame.loc[]`, or, in the case of a 1d input
+            or single key, to `DataFrame.loc[:, ]` where the columns are
+            prioritised, to limit ``data`` to *before* applying the function.
+        na_rep : str, optional
+            Representation for missing values.
+            If ``na_rep`` is None, no special formatting is applied.
+        precision : int, optional
+            Floating point precision to use for display purposes, if not determined by
+            the specified ``formatter``.
+
+            .. versionadded:: 1.3.0
+
+        decimal : str, default "."
+            Character used as decimal separator for floats, complex and integers.
+
+            .. versionadded:: 1.3.0
+
+        thousands : str, optional, default None
+            Character used as thousands separator for floats, complex and integers.
+
+            .. versionadded:: 1.3.0
+
+        escape : str, optional
+            Use 'html' to replace the characters ``&``, ``<``, ``>``, ``'``, and ``"``
+            in cell display string with HTML-safe sequences.
+            Use 'latex' to replace the characters ``&``, ``%``, ``$``, ``#``, ``_``,
+            ``{``, ``}``, ``~``, ``^``, and ``\`` in the cell display string with
+            LaTeX-safe sequences.
+            Use 'latex-math' to replace the characters the same way as in 'latex' mode,
+            except for math substrings, which either are surrounded
+            by two characters ``$`` or start with the character ``\(`` and
+            end with ``\)``. Escaping is done before ``formatter``.
+
+            .. versionadded:: 1.3.0
+
+        hyperlinks : {"html", "latex"}, optional
+            Convert string patterns containing https://, http://, ftp:// or www. to
+            HTML  tags as clickable URL hyperlinks if "html", or LaTeX \href
+            commands if "latex".
+
+            .. versionadded:: 1.4.0
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.format_index: Format the text display value of index labels.
+
+        Notes
+        -----
+        This method assigns a formatting function, ``formatter``, to each cell in the
+        DataFrame. If ``formatter`` is ``None``, then the default formatter is used.
+        If a callable then that function should take a data value as input and return
+        a displayable representation, such as a string. If ``formatter`` is
+        given as a string this is assumed to be a valid Python format specification
+        and is wrapped to a callable as ``string.format(x)``. If a ``dict`` is given,
+        keys should correspond to column names, and values should be string or
+        callable, as above.
+
+        The default formatter currently expresses floats and complex numbers with the
+        pandas display precision unless using the ``precision`` argument here. The
+        default formatter does not adjust the representation of missing values unless
+        the ``na_rep`` argument is used.
+
+        The ``subset`` argument defines which region to apply the formatting function
+        to. If the ``formatter`` argument is given in dict form but does not include
+        all columns within the subset then these columns will have the default formatter
+        applied. Any columns in the formatter dict excluded from the subset will
+        be ignored.
+
+        When using a ``formatter`` string the dtypes must be compatible, otherwise a
+        `ValueError` will be raised.
+
+        When instantiating a Styler, default formatting can be applied be setting the
+        ``pandas.options``:
+
+          - ``styler.format.formatter``: default None.
+          - ``styler.format.na_rep``: default None.
+          - ``styler.format.precision``: default 6.
+          - ``styler.format.decimal``: default ".".
+          - ``styler.format.thousands``: default None.
+          - ``styler.format.escape``: default None.
+
+        .. warning::
+           `Styler.format` is ignored when using the output format `Styler.to_excel`,
+           since Excel and Python have inherrently different formatting structures.
+           However, it is possible to use the `number-format` pseudo CSS attribute
+           to force Excel permissible formatting. See examples.
+
+        Examples
+        --------
+        Using ``na_rep`` and ``precision`` with the default ``formatter``
+
+        >>> df = pd.DataFrame([[np.nan, 1.0, 'A'], [2.0, np.nan, 3.0]])
+        >>> df.style.format(na_rep='MISS', precision=3)  # doctest: +SKIP
+                0       1       2
+        0    MISS   1.000       A
+        1   2.000    MISS   3.000
+
+        Using a ``formatter`` specification on consistent column dtypes
+
+        >>> df.style.format('{:.2f}', na_rep='MISS', subset=[0,1])  # doctest: +SKIP
+                0      1          2
+        0    MISS   1.00          A
+        1    2.00   MISS   3.000000
+
+        Using the default ``formatter`` for unspecified columns
+
+        >>> df.style.format({0: '{:.2f}', 1: '£ {:.1f}'}, na_rep='MISS', precision=1)
+        ...  # doctest: +SKIP
+                 0      1     2
+        0    MISS   £ 1.0     A
+        1    2.00    MISS   3.0
+
+        Multiple ``na_rep`` or ``precision`` specifications under the default
+        ``formatter``.
+
+        >>> (df.style.format(na_rep='MISS', precision=1, subset=[0])
+        ...     .format(na_rep='PASS', precision=2, subset=[1, 2]))  # doctest: +SKIP
+                0      1      2
+        0    MISS   1.00      A
+        1     2.0   PASS   3.00
+
+        Using a callable ``formatter`` function.
+
+        >>> func = lambda s: 'STRING' if isinstance(s, str) else 'FLOAT'
+        >>> df.style.format({0: '{:.1f}', 2: func}, precision=4, na_rep='MISS')
+        ...  # doctest: +SKIP
+                0        1        2
+        0    MISS   1.0000   STRING
+        1     2.0     MISS    FLOAT
+
+        Using a ``formatter`` with HTML ``escape`` and ``na_rep``.
+
+        >>> df = pd.DataFrame([['
', '"A&B"', None]])
+        >>> s = df.style.format(
+        ...     '{0}', escape="html", na_rep="NA"
+        ...     )
+        >>> s.to_html()  # doctest: +SKIP
+        ...
+        
+        
+        
+        ...
+
+        Using a ``formatter`` with ``escape`` in 'latex' mode.
+
+        >>> df = pd.DataFrame([["123"], ["~ ^"], ["$%#"]])
+        >>> df.style.format("\\textbf{{{}}}", escape="latex").to_latex()
+        ...  # doctest: +SKIP
+        \begin{tabular}{ll}
+         & 0 \\
+        0 & \textbf{123} \\
+        1 & \textbf{\textasciitilde \space \textasciicircum } \\
+        2 & \textbf{\$\%\#} \\
+        \end{tabular}
+
+        Applying ``escape`` in 'latex-math' mode. In the example below
+        we enter math mode using the character ``$``.
+
+        >>> df = pd.DataFrame([[r"$\sum_{i=1}^{10} a_i$ a~b $\alpha \
+        ...     = \frac{\beta}{\zeta^2}$"], ["%#^ $ \$x^2 $"]])
+        >>> df.style.format(escape="latex-math").to_latex()
+        ...  # doctest: +SKIP
+        \begin{tabular}{ll}
+         & 0 \\
+        0 & $\sum_{i=1}^{10} a_i$ a\textasciitilde b $\alpha = \frac{\beta}{\zeta^2}$ \\
+        1 & \%\#\textasciicircum \space $ \$x^2 $ \\
+        \end{tabular}
+
+        We can use the character ``\(`` to enter math mode and the character ``\)``
+        to close math mode.
+
+        >>> df = pd.DataFrame([[r"\(\sum_{i=1}^{10} a_i\) a~b \(\alpha \
+        ...     = \frac{\beta}{\zeta^2}\)"], ["%#^ \( \$x^2 \)"]])
+        >>> df.style.format(escape="latex-math").to_latex()
+        ...  # doctest: +SKIP
+        \begin{tabular}{ll}
+         & 0 \\
+        0 & \(\sum_{i=1}^{10} a_i\) a\textasciitilde b \(\alpha
+        = \frac{\beta}{\zeta^2}\) \\
+        1 & \%\#\textasciicircum \space \( \$x^2 \) \\
+        \end{tabular}
+
+        If we have in one DataFrame cell a combination of both shorthands
+        for math formulas, the shorthand with the sign ``$`` will be applied.
+
+        >>> df = pd.DataFrame([[r"\( x^2 \)  $x^2$"], \
+        ...     [r"$\frac{\beta}{\zeta}$ \(\frac{\beta}{\zeta}\)"]])
+        >>> df.style.format(escape="latex-math").to_latex()
+        ...  # doctest: +SKIP
+        \begin{tabular}{ll}
+         & 0 \\
+        0 & \textbackslash ( x\textasciicircum 2 \textbackslash )  $x^2$ \\
+        1 & $\frac{\beta}{\zeta}$ \textbackslash (\textbackslash
+        frac\{\textbackslash beta\}\{\textbackslash zeta\}\textbackslash ) \\
+        \end{tabular}
+
+        Pandas defines a `number-format` pseudo CSS attribute instead of the `.format`
+        method to create `to_excel` permissible formatting. Note that semi-colons are
+        CSS protected characters but used as separators in Excel's format string.
+        Replace semi-colons with the section separator character (ASCII-245) when
+        defining the formatting here.
+
+        >>> df = pd.DataFrame({"A": [1, 0, -1]})
+        >>> pseudo_css = "number-format: 0§[Red](0)§-§@;"
+        >>> filename = "formatted_file.xlsx"
+        >>> df.style.map(lambda v: pseudo_css).to_excel(filename) # doctest: +SKIP
+
+        .. figure:: ../../_static/style/format_excel_css.png
+        """
+        if all(
+            (
+                formatter is None,
+                subset is None,
+                precision is None,
+                decimal == ".",
+                thousands is None,
+                na_rep is None,
+                escape is None,
+                hyperlinks is None,
+            )
+        ):
+            self._display_funcs.clear()
+            return self  # clear the formatter / revert to default and avoid looping
+
+        subset = slice(None) if subset is None else subset
+        subset = non_reducing_slice(subset)
+        data = self.data.loc[subset]
+
+        if not isinstance(formatter, dict):
+            formatter = {col: formatter for col in data.columns}
+
+        cis = self.columns.get_indexer_for(data.columns)
+        ris = self.index.get_indexer_for(data.index)
+        for ci in cis:
+            format_func = _maybe_wrap_formatter(
+                formatter.get(self.columns[ci]),
+                na_rep=na_rep,
+                precision=precision,
+                decimal=decimal,
+                thousands=thousands,
+                escape=escape,
+                hyperlinks=hyperlinks,
+            )
+            for ri in ris:
+                self._display_funcs[(ri, ci)] = format_func
+
+        return self
+
+    def format_index(
+        self,
+        formatter: ExtFormatter | None = None,
+        axis: Axis = 0,
+        level: Level | list[Level] | None = None,
+        na_rep: str | None = None,
+        precision: int | None = None,
+        decimal: str = ".",
+        thousands: str | None = None,
+        escape: str | None = None,
+        hyperlinks: str | None = None,
+    ) -> StylerRenderer:
+        r"""
+        Format the text display value of index labels or column headers.
+
+        .. versionadded:: 1.4.0
+
+        Parameters
+        ----------
+        formatter : str, callable, dict or None
+            Object to define how values are displayed. See notes.
+        axis : {0, "index", 1, "columns"}
+            Whether to apply the formatter to the index or column headers.
+        level : int, str, list
+            The level(s) over which to apply the generic formatter.
+        na_rep : str, optional
+            Representation for missing values.
+            If ``na_rep`` is None, no special formatting is applied.
+        precision : int, optional
+            Floating point precision to use for display purposes, if not determined by
+            the specified ``formatter``.
+        decimal : str, default "."
+            Character used as decimal separator for floats, complex and integers.
+        thousands : str, optional, default None
+            Character used as thousands separator for floats, complex and integers.
+        escape : str, optional
+            Use 'html' to replace the characters ``&``, ``<``, ``>``, ``'``, and ``"``
+            in cell display string with HTML-safe sequences.
+            Use 'latex' to replace the characters ``&``, ``%``, ``$``, ``#``, ``_``,
+            ``{``, ``}``, ``~``, ``^``, and ``\`` in the cell display string with
+            LaTeX-safe sequences.
+            Escaping is done before ``formatter``.
+        hyperlinks : {"html", "latex"}, optional
+            Convert string patterns containing https://, http://, ftp:// or www. to
+            HTML  tags as clickable URL hyperlinks if "html", or LaTeX \href
+            commands if "latex".
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.format: Format the text display value of data cells.
+
+        Notes
+        -----
+        This method assigns a formatting function, ``formatter``, to each level label
+        in the DataFrame's index or column headers. If ``formatter`` is ``None``,
+        then the default formatter is used.
+        If a callable then that function should take a label value as input and return
+        a displayable representation, such as a string. If ``formatter`` is
+        given as a string this is assumed to be a valid Python format specification
+        and is wrapped to a callable as ``string.format(x)``. If a ``dict`` is given,
+        keys should correspond to MultiIndex level numbers or names, and values should
+        be string or callable, as above.
+
+        The default formatter currently expresses floats and complex numbers with the
+        pandas display precision unless using the ``precision`` argument here. The
+        default formatter does not adjust the representation of missing values unless
+        the ``na_rep`` argument is used.
+
+        The ``level`` argument defines which levels of a MultiIndex to apply the
+        method to. If the ``formatter`` argument is given in dict form but does
+        not include all levels within the level argument then these unspecified levels
+        will have the default formatter applied. Any levels in the formatter dict
+        specifically excluded from the level argument will be ignored.
+
+        When using a ``formatter`` string the dtypes must be compatible, otherwise a
+        `ValueError` will be raised.
+
+        .. warning::
+           `Styler.format_index` is ignored when using the output format
+           `Styler.to_excel`, since Excel and Python have inherrently different
+           formatting structures.
+           However, it is possible to use the `number-format` pseudo CSS attribute
+           to force Excel permissible formatting. See documentation for `Styler.format`.
+
+        Examples
+        --------
+        Using ``na_rep`` and ``precision`` with the default ``formatter``
+
+        >>> df = pd.DataFrame([[1, 2, 3]], columns=[2.0, np.nan, 4.0])
+        >>> df.style.format_index(axis=1, na_rep='MISS', precision=3)  # doctest: +SKIP
+            2.000    MISS   4.000
+        0       1       2       3
+
+        Using a ``formatter`` specification on consistent dtypes in a level
+
+        >>> df.style.format_index('{:.2f}', axis=1, na_rep='MISS')  # doctest: +SKIP
+             2.00   MISS    4.00
+        0       1      2       3
+
+        Using the default ``formatter`` for unspecified levels
+
+        >>> df = pd.DataFrame([[1, 2, 3]],
+        ...     columns=pd.MultiIndex.from_arrays([["a", "a", "b"],[2, np.nan, 4]]))
+        >>> df.style.format_index({0: lambda v: v.upper()}, axis=1, precision=1)
+        ...  # doctest: +SKIP
+                       A       B
+              2.0    nan     4.0
+        0       1      2       3
+
+        Using a callable ``formatter`` function.
+
+        >>> func = lambda s: 'STRING' if isinstance(s, str) else 'FLOAT'
+        >>> df.style.format_index(func, axis=1, na_rep='MISS')
+        ...  # doctest: +SKIP
+                  STRING  STRING
+            FLOAT   MISS   FLOAT
+        0       1      2       3
+
+        Using a ``formatter`` with HTML ``escape`` and ``na_rep``.
+
+        >>> df = pd.DataFrame([[1, 2, 3]], columns=['"A"', 'A&B', None])
+        >>> s = df.style.format_index('$ {0}', axis=1, escape="html", na_rep="NA")
+        ...  # doctest: +SKIP
+        
+        
+         or  element.
+    """
+    if "display_value" not in kwargs:
+        kwargs["display_value"] = value
+    return {
+        "type": html_element,
+        "value": value,
+        "class": html_class,
+        "is_visible": is_visible,
+        **kwargs,
+    }
+
+
+def _get_trimming_maximums(
+    rn,
+    cn,
+    max_elements,
+    max_rows=None,
+    max_cols=None,
+    scaling_factor: float = 0.8,
+) -> tuple[int, int]:
+    """
+    Recursively reduce the number of rows and columns to satisfy max elements.
+
+    Parameters
+    ----------
+    rn, cn : int
+        The number of input rows / columns
+    max_elements : int
+        The number of allowable elements
+    max_rows, max_cols : int, optional
+        Directly specify an initial maximum rows or columns before compression.
+    scaling_factor : float
+        Factor at which to reduce the number of rows / columns to fit.
+
+    Returns
+    -------
+    rn, cn : tuple
+        New rn and cn values that satisfy the max_elements constraint
+    """
+
+    def scale_down(rn, cn):
+        if cn >= rn:
+            return rn, int(cn * scaling_factor)
+        else:
+            return int(rn * scaling_factor), cn
+
+    if max_rows:
+        rn = max_rows if rn > max_rows else rn
+    if max_cols:
+        cn = max_cols if cn > max_cols else cn
+
+    while rn * cn > max_elements:
+        rn, cn = scale_down(rn, cn)
+
+    return rn, cn
+
+
+def _get_level_lengths(
+    index: Index,
+    sparsify: bool,
+    max_index: int,
+    hidden_elements: Sequence[int] | None = None,
+):
+    """
+    Given an index, find the level length for each element.
+
+    Parameters
+    ----------
+    index : Index
+        Index or columns to determine lengths of each element
+    sparsify : bool
+        Whether to hide or show each distinct element in a MultiIndex
+    max_index : int
+        The maximum number of elements to analyse along the index due to trimming
+    hidden_elements : sequence of int
+        Index positions of elements hidden from display in the index affecting
+        length
+
+    Returns
+    -------
+    Dict :
+        Result is a dictionary of (level, initial_position): span
+    """
+    if isinstance(index, MultiIndex):
+        levels = index._format_multi(sparsify=lib.no_default, include_names=False)
+    else:
+        levels = index._format_flat(include_name=False)
+
+    if hidden_elements is None:
+        hidden_elements = []
+
+    lengths = {}
+    if not isinstance(index, MultiIndex):
+        for i, value in enumerate(levels):
+            if i not in hidden_elements:
+                lengths[(0, i)] = 1
+        return lengths
+
+    for i, lvl in enumerate(levels):
+        visible_row_count = 0  # used to break loop due to display trimming
+        for j, row in enumerate(lvl):
+            if visible_row_count > max_index:
+                break
+            if not sparsify:
+                # then lengths will always equal 1 since no aggregation.
+                if j not in hidden_elements:
+                    lengths[(i, j)] = 1
+                    visible_row_count += 1
+            elif (row is not lib.no_default) and (j not in hidden_elements):
+                # this element has not been sparsified so must be the start of section
+                last_label = j
+                lengths[(i, last_label)] = 1
+                visible_row_count += 1
+            elif row is not lib.no_default:
+                # even if the above is hidden, keep track of it in case length > 1 and
+                # later elements are visible
+                last_label = j
+                lengths[(i, last_label)] = 0
+            elif j not in hidden_elements:
+                # then element must be part of sparsified section and is visible
+                visible_row_count += 1
+                if visible_row_count > max_index:
+                    break  # do not add a length since the render trim limit reached
+                if lengths[(i, last_label)] == 0:
+                    # if previous iteration was first-of-section but hidden then offset
+                    last_label = j
+                    lengths[(i, last_label)] = 1
+                else:
+                    # else add to previous iteration
+                    lengths[(i, last_label)] += 1
+
+    non_zero_lengths = {
+        element: length for element, length in lengths.items() if length >= 1
+    }
+
+    return non_zero_lengths
+
+
+def _is_visible(idx_row, idx_col, lengths) -> bool:
+    """
+    Index -> {(idx_row, idx_col): bool}).
+    """
+    return (idx_col, idx_row) in lengths
+
+
+def format_table_styles(styles: CSSStyles) -> CSSStyles:
+    """
+    looks for multiple CSS selectors and separates them:
+    [{'selector': 'td, th', 'props': 'a:v;'}]
+        ---> [{'selector': 'td', 'props': 'a:v;'},
+              {'selector': 'th', 'props': 'a:v;'}]
+    """
+    return [
+        {"selector": selector, "props": css_dict["props"]}
+        for css_dict in styles
+        for selector in css_dict["selector"].split(",")
+    ]
+
+
+def _default_formatter(x: Any, precision: int, thousands: bool = False) -> Any:
+    """
+    Format the display of a value
+
+    Parameters
+    ----------
+    x : Any
+        Input variable to be formatted
+    precision : Int
+        Floating point precision used if ``x`` is float or complex.
+    thousands : bool, default False
+        Whether to group digits with thousands separated with ",".
+
+    Returns
+    -------
+    value : Any
+        Matches input type, or string if input is float or complex or int with sep.
+    """
+    if is_float(x) or is_complex(x):
+        return f"{x:,.{precision}f}" if thousands else f"{x:.{precision}f}"
+    elif is_integer(x):
+        return f"{x:,}" if thousands else str(x)
+    return x
+
+
+def _wrap_decimal_thousands(
+    formatter: Callable, decimal: str, thousands: str | None
+) -> Callable:
+    """
+    Takes a string formatting function and wraps logic to deal with thousands and
+    decimal parameters, in the case that they are non-standard and that the input
+    is a (float, complex, int).
+    """
+
+    def wrapper(x):
+        if is_float(x) or is_integer(x) or is_complex(x):
+            if decimal != "." and thousands is not None and thousands != ",":
+                return (
+                    formatter(x)
+                    .replace(",", "§_§-")  # rare string to avoid "," <-> "." clash.
+                    .replace(".", decimal)
+                    .replace("§_§-", thousands)
+                )
+            elif decimal != "." and (thousands is None or thousands == ","):
+                return formatter(x).replace(".", decimal)
+            elif decimal == "." and thousands is not None and thousands != ",":
+                return formatter(x).replace(",", thousands)
+        return formatter(x)
+
+    return wrapper
+
+
+def _str_escape(x, escape):
+    """if escaping: only use on str, else return input"""
+    if isinstance(x, str):
+        if escape == "html":
+            return escape_html(x)
+        elif escape == "latex":
+            return _escape_latex(x)
+        elif escape == "latex-math":
+            return _escape_latex_math(x)
+        else:
+            raise ValueError(
+                f"`escape` only permitted in {{'html', 'latex', 'latex-math'}}, \
+got {escape}"
+            )
+    return x
+
+
+def _render_href(x, format):
+    """uses regex to detect a common URL pattern and converts to href tag in format."""
+    if isinstance(x, str):
+        if format == "html":
+            href = '{0}'
+        elif format == "latex":
+            href = r"\href{{{0}}}{{{0}}}"
+        else:
+            raise ValueError("``hyperlinks`` format can only be 'html' or 'latex'")
+        pat = r"((http|ftp)s?:\/\/|www.)[\w/\-?=%.:@]+\.[\w/\-&?=%.,':;~!@#$*()\[\]]+"
+        return re.sub(pat, lambda m: href.format(m.group(0)), x)
+    return x
+
+
+def _maybe_wrap_formatter(
+    formatter: BaseFormatter | None = None,
+    na_rep: str | None = None,
+    precision: int | None = None,
+    decimal: str = ".",
+    thousands: str | None = None,
+    escape: str | None = None,
+    hyperlinks: str | None = None,
+) -> Callable:
+    """
+    Allows formatters to be expressed as str, callable or None, where None returns
+    a default formatting function. wraps with na_rep, and precision where they are
+    available.
+    """
+    # Get initial func from input string, input callable, or from default factory
+    if isinstance(formatter, str):
+        func_0 = lambda x: formatter.format(x)
+    elif callable(formatter):
+        func_0 = formatter
+    elif formatter is None:
+        precision = (
+            get_option("styler.format.precision") if precision is None else precision
+        )
+        func_0 = partial(
+            _default_formatter, precision=precision, thousands=(thousands is not None)
+        )
+    else:
+        raise TypeError(f"'formatter' expected str or callable, got {type(formatter)}")
+
+    # Replace chars if escaping
+    if escape is not None:
+        func_1 = lambda x: func_0(_str_escape(x, escape=escape))
+    else:
+        func_1 = func_0
+
+    # Replace decimals and thousands if non-standard inputs detected
+    if decimal != "." or (thousands is not None and thousands != ","):
+        func_2 = _wrap_decimal_thousands(func_1, decimal=decimal, thousands=thousands)
+    else:
+        func_2 = func_1
+
+    # Render links
+    if hyperlinks is not None:
+        func_3 = lambda x: func_2(_render_href(x, format=hyperlinks))
+    else:
+        func_3 = func_2
+
+    # Replace missing values if na_rep
+    if na_rep is None:
+        return func_3
+    else:
+        return lambda x: na_rep if (isna(x) is True) else func_3(x)
+
+
+def non_reducing_slice(slice_: Subset):
+    """
+    Ensure that a slice doesn't reduce to a Series or Scalar.
+
+    Any user-passed `subset` should have this called on it
+    to make sure we're always working with DataFrames.
+    """
+    # default to column slice, like DataFrame
+    # ['A', 'B'] -> IndexSlices[:, ['A', 'B']]
+    kinds = (ABCSeries, np.ndarray, Index, list, str)
+    if isinstance(slice_, kinds):
+        slice_ = IndexSlice[:, slice_]
+
+    def pred(part) -> bool:
+        """
+        Returns
+        -------
+        bool
+            True if slice does *not* reduce,
+            False if `part` is a tuple.
+        """
+        # true when slice does *not* reduce, False when part is a tuple,
+        # i.e. MultiIndex slice
+        if isinstance(part, tuple):
+            # GH#39421 check for sub-slice:
+            return any((isinstance(s, slice) or is_list_like(s)) for s in part)
+        else:
+            return isinstance(part, slice) or is_list_like(part)
+
+    if not is_list_like(slice_):
+        if not isinstance(slice_, slice):
+            # a 1-d slice, like df.loc[1]
+            slice_ = [[slice_]]
+        else:
+            # slice(a, b, c)
+            slice_ = [slice_]  # to tuplize later
+    else:
+        # error: Item "slice" of "Union[slice, Sequence[Any]]" has no attribute
+        # "__iter__" (not iterable) -> is specifically list_like in conditional
+        slice_ = [p if pred(p) else [p] for p in slice_]  # type: ignore[union-attr]
+    return tuple(slice_)
+
+
+def maybe_convert_css_to_tuples(style: CSSProperties) -> CSSList:
+    """
+    Convert css-string to sequence of tuples format if needed.
+    'color:red; border:1px solid black;' -> [('color', 'red'),
+                                             ('border','1px solid red')]
+    """
+    if isinstance(style, str):
+        s = style.split(";")
+        try:
+            return [
+                (x.split(":")[0].strip(), x.split(":")[1].strip())
+                for x in s
+                if x.strip() != ""
+            ]
+        except IndexError:
+            raise ValueError(
+                "Styles supplied as string must follow CSS rule formats, "
+                f"for example 'attr: val;'. '{style}' was given."
+            )
+    return style
+
+
+def refactor_levels(
+    level: Level | list[Level] | None,
+    obj: Index,
+) -> list[int]:
+    """
+    Returns a consistent levels arg for use in ``hide_index`` or ``hide_columns``.
+
+    Parameters
+    ----------
+    level : int, str, list
+        Original ``level`` arg supplied to above methods.
+    obj:
+        Either ``self.index`` or ``self.columns``
+
+    Returns
+    -------
+    list : refactored arg with a list of levels to hide
+    """
+    if level is None:
+        levels_: list[int] = list(range(obj.nlevels))
+    elif isinstance(level, int):
+        levels_ = [level]
+    elif isinstance(level, str):
+        levels_ = [obj._get_level_number(level)]
+    elif isinstance(level, list):
+        levels_ = [
+            obj._get_level_number(lev) if not isinstance(lev, int) else lev
+            for lev in level
+        ]
+    else:
+        raise ValueError("`level` must be of type `int`, `str` or list of such")
+    return levels_
+
+
+class Tooltips:
+    """
+    An extension to ``Styler`` that allows for and manipulates tooltips on hover
+    of ``
<div></div>"A&B"NA$ "A"$ A&BNA
+        ...
+
+        Using a ``formatter`` with LaTeX ``escape``.
+
+        >>> df = pd.DataFrame([[1, 2, 3]], columns=["123", "~", "$%#"])
+        >>> df.style.format_index("\\textbf{{{}}}", escape="latex", axis=1).to_latex()
+        ...  # doctest: +SKIP
+        \begin{tabular}{lrrr}
+        {} & {\textbf{123}} & {\textbf{\textasciitilde }} & {\textbf{\$\%\#}} \\
+        0 & 1 & 2 & 3 \\
+        \end{tabular}
+        """
+        axis = self.data._get_axis_number(axis)
+        if axis == 0:
+            display_funcs_, obj = self._display_funcs_index, self.index
+        else:
+            display_funcs_, obj = self._display_funcs_columns, self.columns
+        levels_ = refactor_levels(level, obj)
+
+        if all(
+            (
+                formatter is None,
+                level is None,
+                precision is None,
+                decimal == ".",
+                thousands is None,
+                na_rep is None,
+                escape is None,
+                hyperlinks is None,
+            )
+        ):
+            display_funcs_.clear()
+            return self  # clear the formatter / revert to default and avoid looping
+
+        if not isinstance(formatter, dict):
+            formatter = {level: formatter for level in levels_}
+        else:
+            formatter = {
+                obj._get_level_number(level): formatter_
+                for level, formatter_ in formatter.items()
+            }
+
+        for lvl in levels_:
+            format_func = _maybe_wrap_formatter(
+                formatter.get(lvl),
+                na_rep=na_rep,
+                precision=precision,
+                decimal=decimal,
+                thousands=thousands,
+                escape=escape,
+                hyperlinks=hyperlinks,
+            )
+
+            for idx in [(i, lvl) if axis == 0 else (lvl, i) for i in range(len(obj))]:
+                display_funcs_[idx] = format_func
+
+        return self
+
+    def relabel_index(
+        self,
+        labels: Sequence | Index,
+        axis: Axis = 0,
+        level: Level | list[Level] | None = None,
+    ) -> StylerRenderer:
+        r"""
+        Relabel the index, or column header, keys to display a set of specified values.
+
+        .. versionadded:: 1.5.0
+
+        Parameters
+        ----------
+        labels : list-like or Index
+            New labels to display. Must have same length as the underlying values not
+            hidden.
+        axis : {"index", 0, "columns", 1}
+            Apply to the index or columns.
+        level : int, str, list, optional
+            The level(s) over which to apply the new labels. If `None` will apply
+            to all levels of an Index or MultiIndex which are not hidden.
+
+        Returns
+        -------
+        Styler
+
+        See Also
+        --------
+        Styler.format_index: Format the text display value of index or column headers.
+        Styler.hide: Hide the index, column headers, or specified data from display.
+
+        Notes
+        -----
+        As part of Styler, this method allows the display of an index to be
+        completely user-specified without affecting the underlying DataFrame data,
+        index, or column headers. This means that the flexibility of indexing is
+        maintained whilst the final display is customisable.
+
+        Since Styler is designed to be progressively constructed with method chaining,
+        this method is adapted to react to the **currently specified hidden elements**.
+        This is useful because it means one does not have to specify all the new
+        labels if the majority of an index, or column headers, have already been hidden.
+        The following produce equivalent display (note the length of ``labels`` in
+        each case).
+
+        .. code-block:: python
+
+            # relabel first, then hide
+            df = pd.DataFrame({"col": ["a", "b", "c"]})
+            df.style.relabel_index(["A", "B", "C"]).hide([0,1])
+            # hide first, then relabel
+            df = pd.DataFrame({"col": ["a", "b", "c"]})
+            df.style.hide([0,1]).relabel_index(["C"])
+
+        This method should be used, rather than :meth:`Styler.format_index`, in one of
+        the following cases (see examples):
+
+          - A specified set of labels are required which are not a function of the
+            underlying index keys.
+          - The function of the underlying index keys requires a counter variable,
+            such as those available upon enumeration.
+
+        Examples
+        --------
+        Basic use
+
+        >>> df = pd.DataFrame({"col": ["a", "b", "c"]})
+        >>> df.style.relabel_index(["A", "B", "C"])  # doctest: +SKIP
+             col
+        A      a
+        B      b
+        C      c
+
+        Chaining with pre-hidden elements
+
+        >>> df.style.hide([0,1]).relabel_index(["C"])  # doctest: +SKIP
+             col
+        C      c
+
+        Using a MultiIndex
+
+        >>> midx = pd.MultiIndex.from_product([[0, 1], [0, 1], [0, 1]])
+        >>> df = pd.DataFrame({"col": list(range(8))}, index=midx)
+        >>> styler = df.style  # doctest: +SKIP
+                  col
+        0  0  0     0
+              1     1
+           1  0     2
+              1     3
+        1  0  0     4
+              1     5
+           1  0     6
+              1     7
+        >>> styler.hide((midx.get_level_values(0)==0)|(midx.get_level_values(1)==0))
+        ...  # doctest: +SKIP
+        >>> styler.hide(level=[0,1])  # doctest: +SKIP
+        >>> styler.relabel_index(["binary6", "binary7"])  # doctest: +SKIP
+                  col
+        binary6     6
+        binary7     7
+
+        We can also achieve the above by indexing first and then re-labeling
+
+        >>> styler = df.loc[[(1,1,0), (1,1,1)]].style
+        >>> styler.hide(level=[0,1]).relabel_index(["binary6", "binary7"])
+        ...  # doctest: +SKIP
+                  col
+        binary6     6
+        binary7     7
+
+        Defining a formatting function which uses an enumeration counter. Also note
+        that the value of the index key is passed in the case of string labels so it
+        can also be inserted into the label, using curly brackets (or double curly
+        brackets if the string if pre-formatted),
+
+        >>> df = pd.DataFrame({"samples": np.random.rand(10)})
+        >>> styler = df.loc[np.random.randint(0,10,3)].style
+        >>> styler.relabel_index([f"sample{i+1} ({{}})" for i in range(3)])
+        ...  # doctest: +SKIP
+                         samples
+        sample1 (5)     0.315811
+        sample2 (0)     0.495941
+        sample3 (2)     0.067946
+        """
+        axis = self.data._get_axis_number(axis)
+        if axis == 0:
+            display_funcs_, obj = self._display_funcs_index, self.index
+            hidden_labels, hidden_lvls = self.hidden_rows, self.hide_index_
+        else:
+            display_funcs_, obj = self._display_funcs_columns, self.columns
+            hidden_labels, hidden_lvls = self.hidden_columns, self.hide_columns_
+        visible_len = len(obj) - len(set(hidden_labels))
+        if len(labels) != visible_len:
+            raise ValueError(
+                "``labels`` must be of length equal to the number of "
+                f"visible labels along ``axis`` ({visible_len})."
+            )
+
+        if level is None:
+            level = [i for i in range(obj.nlevels) if not hidden_lvls[i]]
+        levels_ = refactor_levels(level, obj)
+
+        def alias_(x, value):
+            if isinstance(value, str):
+                return value.format(x)
+            return value
+
+        for ai, i in enumerate([i for i in range(len(obj)) if i not in hidden_labels]):
+            if len(levels_) == 1:
+                idx = (i, levels_[0]) if axis == 0 else (levels_[0], i)
+                display_funcs_[idx] = partial(alias_, value=labels[ai])
+            else:
+                for aj, lvl in enumerate(levels_):
+                    idx = (i, lvl) if axis == 0 else (lvl, i)
+                    display_funcs_[idx] = partial(alias_, value=labels[ai][aj])
+
+        return self
+
+
+def _element(
+    html_element: str,
+    html_class: str | None,
+    value: Any,
+    is_visible: bool,
+    **kwargs,
+) -> dict:
+    """
+    Template to return container with information for a `` cells in the HTML result.
+
+    Parameters
+    ----------
+    css_name: str, default "pd-t"
+        Name of the CSS class that controls visualisation of tooltips.
+    css_props: list-like, default; see Notes
+        List of (attr, value) tuples defining properties of the CSS class.
+    tooltips: DataFrame, default empty
+        DataFrame of strings aligned with underlying Styler data for tooltip
+        display.
+
+    Notes
+    -----
+    The default properties for the tooltip CSS class are:
+
+        - visibility: hidden
+        - position: absolute
+        - z-index: 1
+        - background-color: black
+        - color: white
+        - transform: translate(-20px, -20px)
+
+    Hidden visibility is a key prerequisite to the hover functionality, and should
+    always be included in any manual properties specification.
+    """
+
+    def __init__(
+        self,
+        css_props: CSSProperties = [
+            ("visibility", "hidden"),
+            ("position", "absolute"),
+            ("z-index", 1),
+            ("background-color", "black"),
+            ("color", "white"),
+            ("transform", "translate(-20px, -20px)"),
+        ],
+        css_name: str = "pd-t",
+        tooltips: DataFrame = DataFrame(),
+    ) -> None:
+        self.class_name = css_name
+        self.class_properties = css_props
+        self.tt_data = tooltips
+        self.table_styles: CSSStyles = []
+
+    @property
+    def _class_styles(self):
+        """
+        Combine the ``_Tooltips`` CSS class name and CSS properties to the format
+        required to extend the underlying ``Styler`` `table_styles` to allow
+        tooltips to render in HTML.
+
+        Returns
+        -------
+        styles : List
+        """
+        return [
+            {
+                "selector": f".{self.class_name}",
+                "props": maybe_convert_css_to_tuples(self.class_properties),
+            }
+        ]
+
+    def _pseudo_css(self, uuid: str, name: str, row: int, col: int, text: str):
+        """
+        For every table data-cell that has a valid tooltip (not None, NaN or
+        empty string) must create two pseudo CSS entries for the specific
+         element id which are added to overall table styles:
+        an on hover visibility change and a content change
+        dependent upon the user's chosen display string.
+
+        For example:
+            [{"selector": "T__row1_col1:hover .pd-t",
+             "props": [("visibility", "visible")]},
+            {"selector": "T__row1_col1 .pd-t::after",
+             "props": [("content", "Some Valid Text String")]}]
+
+        Parameters
+        ----------
+        uuid: str
+            The uuid of the Styler instance
+        name: str
+            The css-name of the class used for styling tooltips
+        row : int
+            The row index of the specified tooltip string data
+        col : int
+            The col index of the specified tooltip string data
+        text : str
+            The textual content of the tooltip to be displayed in HTML.
+
+        Returns
+        -------
+        pseudo_css : List
+        """
+        selector_id = "#T_" + uuid + "_row" + str(row) + "_col" + str(col)
+        return [
+            {
+                "selector": selector_id + f":hover .{name}",
+                "props": [("visibility", "visible")],
+            },
+            {
+                "selector": selector_id + f" .{name}::after",
+                "props": [("content", f'"{text}"')],
+            },
+        ]
+
+    def _translate(self, styler: StylerRenderer, d: dict):
+        """
+        Mutate the render dictionary to allow for tooltips:
+
+        - Add ```` HTML element to each data cells ``display_value``. Ignores
+          headers.
+        - Add table level CSS styles to control pseudo classes.
+
+        Parameters
+        ----------
+        styler_data : DataFrame
+            Underlying ``Styler`` DataFrame used for reindexing.
+        uuid : str
+            The underlying ``Styler`` uuid for CSS id.
+        d : dict
+            The dictionary prior to final render
+
+        Returns
+        -------
+        render_dict : Dict
+        """
+        self.tt_data = self.tt_data.reindex_like(styler.data)
+        if self.tt_data.empty:
+            return d
+
+        name = self.class_name
+        mask = (self.tt_data.isna()) | (self.tt_data.eq(""))  # empty string = no ttip
+        self.table_styles = [
+            style
+            for sublist in [
+                self._pseudo_css(styler.uuid, name, i, j, str(self.tt_data.iloc[i, j]))
+                for i in range(len(self.tt_data.index))
+                for j in range(len(self.tt_data.columns))
+                if not (
+                    mask.iloc[i, j]
+                    or i in styler.hidden_rows
+                    or j in styler.hidden_columns
+                )
+            ]
+            for style in sublist
+        ]
+
+        if self.table_styles:
+            # add span class to every cell only if at least 1 non-empty tooltip
+            for row in d["body"]:
+                for item in row:
+                    if item["type"] == "td":
+                        item["display_value"] = (
+                            str(item["display_value"])
+                            + f''
+                        )
+            d["table_styles"].extend(self._class_styles)
+            d["table_styles"].extend(self.table_styles)
+
+        return d
+
+
+def _parse_latex_table_wrapping(table_styles: CSSStyles, caption: str | None) -> bool:
+    """
+    Indicate whether LaTeX {tabular} should be wrapped with a {table} environment.
+
+    Parses the `table_styles` and detects any selectors which must be included outside
+    of {tabular}, i.e. indicating that wrapping must occur, and therefore return True,
+    or if a caption exists and requires similar.
+    """
+    IGNORED_WRAPPERS = ["toprule", "midrule", "bottomrule", "column_format"]
+    # ignored selectors are included with {tabular} so do not need wrapping
+    return (
+        table_styles is not None
+        and any(d["selector"] not in IGNORED_WRAPPERS for d in table_styles)
+    ) or caption is not None
+
+
+def _parse_latex_table_styles(table_styles: CSSStyles, selector: str) -> str | None:
+    """
+    Return the first 'props' 'value' from ``tables_styles`` identified by ``selector``.
+
+    Examples
+    --------
+    >>> table_styles = [{'selector': 'foo', 'props': [('attr','value')]},
+    ...                 {'selector': 'bar', 'props': [('attr', 'overwritten')]},
+    ...                 {'selector': 'bar', 'props': [('a1', 'baz'), ('a2', 'ignore')]}]
+    >>> _parse_latex_table_styles(table_styles, selector='bar')
+    'baz'
+
+    Notes
+    -----
+    The replacement of "§" with ":" is to avoid the CSS problem where ":" has structural
+    significance and cannot be used in LaTeX labels, but is often required by them.
+    """
+    for style in table_styles[::-1]:  # in reverse for most recently applied style
+        if style["selector"] == selector:
+            return str(style["props"][0][1]).replace("§", ":")
+    return None
+
+
+def _parse_latex_cell_styles(
+    latex_styles: CSSList, display_value: str, convert_css: bool = False
+) -> str:
+    r"""
+    Mutate the ``display_value`` string including LaTeX commands from ``latex_styles``.
+
+    This method builds a recursive latex chain of commands based on the
+    CSSList input, nested around ``display_value``.
+
+    If a CSS style is given as ('', '') this is translated to
+    '\{display_value}', and this value is treated as the
+    display value for the next iteration.
+
+    The most recent style forms the inner component, for example for styles:
+    `[('c1', 'o1'), ('c2', 'o2')]` this returns: `\c1o1{\c2o2{display_value}}`
+
+    Sometimes latex commands have to be wrapped with curly braces in different ways:
+    We create some parsing flags to identify the different behaviours:
+
+     - `--rwrap`        : `\{}`
+     - `--wrap`         : `{\ }`
+     - `--nowrap`       : `\ `
+     - `--lwrap`        : `{\} `
+     - `--dwrap`        : `{\}{}`
+
+    For example for styles:
+    `[('c1', 'o1--wrap'), ('c2', 'o2')]` this returns: `{\c1o1 \c2o2{display_value}}
+    """
+    if convert_css:
+        latex_styles = _parse_latex_css_conversion(latex_styles)
+    for command, options in latex_styles[::-1]:  # in reverse for most recent style
+        formatter = {
+            "--wrap": f"{{\\{command}--to_parse {display_value}}}",
+            "--nowrap": f"\\{command}--to_parse {display_value}",
+            "--lwrap": f"{{\\{command}--to_parse}} {display_value}",
+            "--rwrap": f"\\{command}--to_parse{{{display_value}}}",
+            "--dwrap": f"{{\\{command}--to_parse}}{{{display_value}}}",
+        }
+        display_value = f"\\{command}{options} {display_value}"
+        for arg in ["--nowrap", "--wrap", "--lwrap", "--rwrap", "--dwrap"]:
+            if arg in str(options):
+                display_value = formatter[arg].replace(
+                    "--to_parse", _parse_latex_options_strip(value=options, arg=arg)
+                )
+                break  # only ever one purposeful entry
+    return display_value
+
+
+def _parse_latex_header_span(
+    cell: dict[str, Any],
+    multirow_align: str,
+    multicol_align: str,
+    wrap: bool = False,
+    convert_css: bool = False,
+) -> str:
+    r"""
+    Refactor the cell `display_value` if a 'colspan' or 'rowspan' attribute is present.
+
+    'rowspan' and 'colspan' do not occur simultaneouly. If they are detected then
+    the `display_value` is altered to a LaTeX `multirow` or `multicol` command
+    respectively, with the appropriate cell-span.
+
+    ``wrap`` is used to enclose the `display_value` in braces which is needed for
+    column headers using an siunitx package.
+
+    Requires the package {multirow}, whereas multicol support is usually built in
+    to the {tabular} environment.
+
+    Examples
+    --------
+    >>> cell = {'cellstyle': '', 'display_value':'text', 'attributes': 'colspan="3"'}
+    >>> _parse_latex_header_span(cell, 't', 'c')
+    '\\multicolumn{3}{c}{text}'
+    """
+    display_val = _parse_latex_cell_styles(
+        cell["cellstyle"], cell["display_value"], convert_css
+    )
+    if "attributes" in cell:
+        attrs = cell["attributes"]
+        if 'colspan="' in attrs:
+            colspan = attrs[attrs.find('colspan="') + 9 :]  # len('colspan="') = 9
+            colspan = int(colspan[: colspan.find('"')])
+            if "naive-l" == multicol_align:
+                out = f"{{{display_val}}}" if wrap else f"{display_val}"
+                blanks = " & {}" if wrap else " &"
+                return out + blanks * (colspan - 1)
+            elif "naive-r" == multicol_align:
+                out = f"{{{display_val}}}" if wrap else f"{display_val}"
+                blanks = "{} & " if wrap else "& "
+                return blanks * (colspan - 1) + out
+            return f"\\multicolumn{{{colspan}}}{{{multicol_align}}}{{{display_val}}}"
+        elif 'rowspan="' in attrs:
+            if multirow_align == "naive":
+                return display_val
+            rowspan = attrs[attrs.find('rowspan="') + 9 :]
+            rowspan = int(rowspan[: rowspan.find('"')])
+            return f"\\multirow[{multirow_align}]{{{rowspan}}}{{*}}{{{display_val}}}"
+    if wrap:
+        return f"{{{display_val}}}"
+    else:
+        return display_val
+
+
+def _parse_latex_options_strip(value: str | float, arg: str) -> str:
+    """
+    Strip a css_value which may have latex wrapping arguments, css comment identifiers,
+    and whitespaces, to a valid string for latex options parsing.
+
+    For example: 'red /* --wrap */  ' --> 'red'
+    """
+    return str(value).replace(arg, "").replace("/*", "").replace("*/", "").strip()
+
+
+def _parse_latex_css_conversion(styles: CSSList) -> CSSList:
+    """
+    Convert CSS (attribute,value) pairs to equivalent LaTeX (command,options) pairs.
+
+    Ignore conversion if tagged with `--latex` option, skipped if no conversion found.
+    """
+
+    def font_weight(value, arg):
+        if value in ("bold", "bolder"):
+            return "bfseries", f"{arg}"
+        return None
+
+    def font_style(value, arg):
+        if value == "italic":
+            return "itshape", f"{arg}"
+        if value == "oblique":
+            return "slshape", f"{arg}"
+        return None
+
+    def color(value, user_arg, command, comm_arg):
+        """
+        CSS colors have 5 formats to process:
+
+         - 6 digit hex code: "#ff23ee"     --> [HTML]{FF23EE}
+         - 3 digit hex code: "#f0e"        --> [HTML]{FF00EE}
+         - rgba: rgba(128, 255, 0, 0.5)    --> [rgb]{0.502, 1.000, 0.000}
+         - rgb: rgb(128, 255, 0,)          --> [rbg]{0.502, 1.000, 0.000}
+         - string: red                     --> {red}
+
+        Additionally rgb or rgba can be expressed in % which is also parsed.
+        """
+        arg = user_arg if user_arg != "" else comm_arg
+
+        if value[0] == "#" and len(value) == 7:  # color is hex code
+            return command, f"[HTML]{{{value[1:].upper()}}}{arg}"
+        if value[0] == "#" and len(value) == 4:  # color is short hex code
+            val = f"{value[1].upper()*2}{value[2].upper()*2}{value[3].upper()*2}"
+            return command, f"[HTML]{{{val}}}{arg}"
+        elif value[:3] == "rgb":  # color is rgb or rgba
+            r = re.findall("(?<=\\()[0-9\\s%]+(?=,)", value)[0].strip()
+            r = float(r[:-1]) / 100 if "%" in r else int(r) / 255
+            g = re.findall("(?<=,)[0-9\\s%]+(?=,)", value)[0].strip()
+            g = float(g[:-1]) / 100 if "%" in g else int(g) / 255
+            if value[3] == "a":  # color is rgba
+                b = re.findall("(?<=,)[0-9\\s%]+(?=,)", value)[1].strip()
+            else:  # color is rgb
+                b = re.findall("(?<=,)[0-9\\s%]+(?=\\))", value)[0].strip()
+            b = float(b[:-1]) / 100 if "%" in b else int(b) / 255
+            return command, f"[rgb]{{{r:.3f}, {g:.3f}, {b:.3f}}}{arg}"
+        else:
+            return command, f"{{{value}}}{arg}"  # color is likely string-named
+
+    CONVERTED_ATTRIBUTES: dict[str, Callable] = {
+        "font-weight": font_weight,
+        "background-color": partial(color, command="cellcolor", comm_arg="--lwrap"),
+        "color": partial(color, command="color", comm_arg=""),
+        "font-style": font_style,
+    }
+
+    latex_styles: CSSList = []
+    for attribute, value in styles:
+        if isinstance(value, str) and "--latex" in value:
+            # return the style without conversion but drop '--latex'
+            latex_styles.append((attribute, value.replace("--latex", "")))
+        if attribute in CONVERTED_ATTRIBUTES:
+            arg = ""
+            for x in ["--wrap", "--nowrap", "--lwrap", "--dwrap", "--rwrap"]:
+                if x in str(value):
+                    arg, value = x, _parse_latex_options_strip(value, x)
+                    break
+            latex_style = CONVERTED_ATTRIBUTES[attribute](value, arg)
+            if latex_style is not None:
+                latex_styles.extend([latex_style])
+    return latex_styles
+
+
+def _escape_latex(s: str) -> str:
+    r"""
+    Replace the characters ``&``, ``%``, ``$``, ``#``, ``_``, ``{``, ``}``,
+    ``~``, ``^``, and ``\`` in the string with LaTeX-safe sequences.
+
+    Use this if you need to display text that might contain such characters in LaTeX.
+
+    Parameters
+    ----------
+    s : str
+        Input to be escaped
+
+    Return
+    ------
+    str :
+        Escaped string
+    """
+    return (
+        s.replace("\\", "ab2§=§8yz")  # rare string for final conversion: avoid \\ clash
+        .replace("ab2§=§8yz ", "ab2§=§8yz\\space ")  # since \backslash gobbles spaces
+        .replace("&", "\\&")
+        .replace("%", "\\%")
+        .replace("$", "\\$")
+        .replace("#", "\\#")
+        .replace("_", "\\_")
+        .replace("{", "\\{")
+        .replace("}", "\\}")
+        .replace("~ ", "~\\space ")  # since \textasciitilde gobbles spaces
+        .replace("~", "\\textasciitilde ")
+        .replace("^ ", "^\\space ")  # since \textasciicircum gobbles spaces
+        .replace("^", "\\textasciicircum ")
+        .replace("ab2§=§8yz", "\\textbackslash ")
+    )
+
+
+def _math_mode_with_dollar(s: str) -> str:
+    r"""
+    All characters in LaTeX math mode are preserved.
+
+    The substrings in LaTeX math mode, which start with
+    the character ``$`` and end with ``$``, are preserved
+    without escaping. Otherwise regular LaTeX escaping applies.
+
+    Parameters
+    ----------
+    s : str
+        Input to be escaped
+
+    Return
+    ------
+    str :
+        Escaped string
+    """
+    s = s.replace(r"\$", r"rt8§=§7wz")
+    pattern = re.compile(r"\$.*?\$")
+    pos = 0
+    ps = pattern.search(s, pos)
+    res = []
+    while ps:
+        res.append(_escape_latex(s[pos : ps.span()[0]]))
+        res.append(ps.group())
+        pos = ps.span()[1]
+        ps = pattern.search(s, pos)
+
+    res.append(_escape_latex(s[pos : len(s)]))
+    return "".join(res).replace(r"rt8§=§7wz", r"\$")
+
+
+def _math_mode_with_parentheses(s: str) -> str:
+    r"""
+    All characters in LaTeX math mode are preserved.
+
+    The substrings in LaTeX math mode, which start with
+    the character ``\(`` and end with ``\)``, are preserved
+    without escaping. Otherwise regular LaTeX escaping applies.
+
+    Parameters
+    ----------
+    s : str
+        Input to be escaped
+
+    Return
+    ------
+    str :
+        Escaped string
+    """
+    s = s.replace(r"\(", r"LEFT§=§6yzLEFT").replace(r"\)", r"RIGHTab5§=§RIGHT")
+    res = []
+    for item in re.split(r"LEFT§=§6yz|ab5§=§RIGHT", s):
+        if item.startswith("LEFT") and item.endswith("RIGHT"):
+            res.append(item.replace("LEFT", r"\(").replace("RIGHT", r"\)"))
+        elif "LEFT" in item and "RIGHT" in item:
+            res.append(
+                _escape_latex(item).replace("LEFT", r"\(").replace("RIGHT", r"\)")
+            )
+        else:
+            res.append(
+                _escape_latex(item)
+                .replace("LEFT", r"\textbackslash (")
+                .replace("RIGHT", r"\textbackslash )")
+            )
+    return "".join(res)
+
+
+def _escape_latex_math(s: str) -> str:
+    r"""
+    All characters in LaTeX math mode are preserved.
+
+    The substrings in LaTeX math mode, which either are surrounded
+    by two characters ``$`` or start with the character ``\(`` and end with ``\)``,
+    are preserved without escaping. Otherwise regular LaTeX escaping applies.
+
+    Parameters
+    ----------
+    s : str
+        Input to be escaped
+
+    Return
+    ------
+    str :
+        Escaped string
+    """
+    s = s.replace(r"\$", r"rt8§=§7wz")
+    ps_d = re.compile(r"\$.*?\$").search(s, 0)
+    ps_p = re.compile(r"\(.*?\)").search(s, 0)
+    mode = []
+    if ps_d:
+        mode.append(ps_d.span()[0])
+    if ps_p:
+        mode.append(ps_p.span()[0])
+    if len(mode) == 0:
+        return _escape_latex(s.replace(r"rt8§=§7wz", r"\$"))
+    if s[mode[0]] == r"$":
+        return _math_mode_with_dollar(s.replace(r"rt8§=§7wz", r"\$"))
+    if s[mode[0] - 1 : mode[0] + 1] == r"\(":
+        return _math_mode_with_parentheses(s.replace(r"rt8§=§7wz", r"\$"))
+    else:
+        return _escape_latex(s.replace(r"rt8§=§7wz", r"\$"))
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..8c63be3ad788a8abddf3588b2b9dd6d6126f5df3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html.tpl
@@ -0,0 +1,16 @@
+{# Update the html_style/table_structure.html documentation too #}
+{% if doctype_html %}
+
+
+
+
+{% if not exclude_styles %}{% include html_style_tpl %}{% endif %}
+
+
+{% include html_table_tpl %}
+
+
+{% elif not doctype_html %}
+{% if not exclude_styles %}{% include html_style_tpl %}{% endif %}
+{% include html_table_tpl %}
+{% endif %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_style.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_style.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..5c3fcd97f51bbec263399922579420dfa9ceef9c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_style.tpl
@@ -0,0 +1,26 @@
+{%- block before_style -%}{%- endblock before_style -%}
+{% block style %}
+
+{% endblock style %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_table.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_table.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..17118d2bb21ccd185780d44c83a5242b12bd2a0d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/html_table.tpl
@@ -0,0 +1,63 @@
+{% block before_table %}{% endblock before_table %}
+{% block table %}
+{% if exclude_styles %}
+
+{% else %}
+

+{% endif %}
+{% block caption %}
+{% if caption and caption is string %}
+  
+{% elif caption and caption is sequence %}
+  
+{% endif %}
+{% endblock caption %}
+{% block thead %}
+  
+{% block before_head_rows %}{% endblock %}
+{% for r in head %}
+{% block head_tr scoped %}
+    
+{% if exclude_styles %}
+{% for c in r %}
+{% if c.is_visible != False %}
+      <{{c.type}} {{c.attributes}}>{{c.display_value}}
+{% endif %}
+{% endfor %}
+{% else %}
+{% for c in r %}
+{% if c.is_visible != False %}
+      <{{c.type}} {%- if c.id is defined %} id="T_{{uuid}}_{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}
+{% endif %}
+{% endfor %}
+{% endif %}
+    
+{% endblock head_tr %}
+{% endfor %}
+{% block after_head_rows %}{% endblock %}
+  
+{% endblock thead %}
+{% block tbody %}
+  
+{% block before_rows %}{% endblock before_rows %}
+{% for r in body %}
+{% block tr scoped %}
+    
+{% if exclude_styles %}
+{% for c in r %}{% if c.is_visible != False %}
+      <{{c.type}} {{c.attributes}}>{{c.display_value}}
+{% endif %}{% endfor %}
+{% else %}
+{% for c in r %}{% if c.is_visible != False %}
+      <{{c.type}} {%- if c.id is defined %} id="T_{{uuid}}_{{c.id}}" {%- endif %} class="{{c.class}}" {{c.attributes}}>{{c.display_value}}
+{% endif %}{% endfor %}
+{% endif %}
+    
+{% endblock tr %}
+{% endfor %}
+{% block after_rows %}{% endblock after_rows %}
+  
+{% endblock tbody %}
+
{{caption}}{{caption[0]}}

+{% endblock table %}
+{% block after_table %}{% endblock after_table %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..ae341bbc29823489d9d15e354fae0ce2e10a046d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex.tpl
@@ -0,0 +1,5 @@
+{% if environment == "longtable" %}
+{% include "latex_longtable.tpl" %}
+{% else %}
+{% include "latex_table.tpl" %}
+{% endif %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_longtable.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_longtable.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..b97843eeb918da1b12f6f2edd585c8e42d6b7bb5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_longtable.tpl
@@ -0,0 +1,82 @@
+\begin{longtable}
+{%- set position = parse_table(table_styles, 'position') %}
+{%- if position is not none %}
+[{{position}}]
+{%- endif %}
+{%- set column_format = parse_table(table_styles, 'column_format') %}
+{% raw %}{{% endraw %}{{column_format}}{% raw %}}{% endraw %}
+
+{% for style in table_styles %}
+{% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format', 'label'] %}
+\{{style['selector']}}{{parse_table(table_styles, style['selector'])}}
+{% endif %}
+{% endfor %}
+{% if caption and caption is string %}
+\caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
+{%- set label = parse_table(table_styles, 'label') %}
+{%- if label is not none %}
+ \label{{label}}
+{%- endif %} \\
+{% elif caption and caption is sequence %}
+\caption[{{caption[1]}}]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %}
+{%- set label = parse_table(table_styles, 'label') %}
+{%- if label is not none %}
+ \label{{label}}
+{%- endif %} \\
+{% else %}
+{%- set label = parse_table(table_styles, 'label') %}
+{%- if label is not none %}
+\label{{label}} \\
+{% endif %}
+{% endif %}
+{% set toprule = parse_table(table_styles, 'toprule') %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, siunitx)}}{% endfor %} \\
+{% endfor %}
+{% set midrule = parse_table(table_styles, 'midrule') %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endfirsthead
+{% if caption and caption is string %}
+\caption[]{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %} \\
+{% elif caption and caption is sequence %}
+\caption[]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %} \\
+{% endif %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, siunitx)}}{% endfor %} \\
+{% endfor %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endhead
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\multicolumn{% raw %}{{% endraw %}{{body[0]|length}}{% raw %}}{% endraw %}{r}{Continued on next page} \\
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+\endfoot
+{% set bottomrule = parse_table(table_styles, 'bottomrule') %}
+{% if bottomrule is not none %}
+\{{bottomrule}}
+{% endif %}
+\endlastfoot
+{% for row in body %}
+{% for c in row %}{% if not loop.first %} & {% endif %}
+  {%- if c.type == 'th' %}{{parse_header(c, multirow_align, multicol_align)}}{% else %}{{parse_cell(c.cellstyle, c.display_value, convert_css)}}{% endif %}
+{%- endfor %} \\
+{% if clines and clines[loop.index] | length > 0 %}
+  {%- for cline in clines[loop.index] %}{% if not loop.first %} {% endif %}{{ cline }}{% endfor %}
+
+{% endif %}
+{% endfor %}
+\end{longtable}
+{% raw %}{% endraw %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_table.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_table.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..7858cb4c945534a4d21cd4474460fd1abcf01f82
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/latex_table.tpl
@@ -0,0 +1,57 @@
+{% if environment or parse_wrap(table_styles, caption) %}
+\begin{% raw %}{{% endraw %}{{environment if environment else "table"}}{% raw %}}{% endraw %}
+{%- set position = parse_table(table_styles, 'position') %}
+{%- if position is not none %}
+[{{position}}]
+{%- endif %}
+
+{% set position_float = parse_table(table_styles, 'position_float') %}
+{% if position_float is not none%}
+\{{position_float}}
+{% endif %}
+{% if caption and caption is string %}
+\caption{% raw %}{{% endraw %}{{caption}}{% raw %}}{% endraw %}
+
+{% elif caption and caption is sequence %}
+\caption[{{caption[1]}}]{% raw %}{{% endraw %}{{caption[0]}}{% raw %}}{% endraw %}
+
+{% endif %}
+{% for style in table_styles %}
+{% if style['selector'] not in ['position', 'position_float', 'caption', 'toprule', 'midrule', 'bottomrule', 'column_format'] %}
+\{{style['selector']}}{{parse_table(table_styles, style['selector'])}}
+{% endif %}
+{% endfor %}
+{% endif %}
+\begin{tabular}
+{%- set column_format = parse_table(table_styles, 'column_format') %}
+{% raw %}{{% endraw %}{{column_format}}{% raw %}}{% endraw %}
+
+{% set toprule = parse_table(table_styles, 'toprule') %}
+{% if toprule is not none %}
+\{{toprule}}
+{% endif %}
+{% for row in head %}
+{% for c in row %}{%- if not loop.first %} & {% endif %}{{parse_header(c, multirow_align, multicol_align, siunitx, convert_css)}}{% endfor %} \\
+{% endfor %}
+{% set midrule = parse_table(table_styles, 'midrule') %}
+{% if midrule is not none %}
+\{{midrule}}
+{% endif %}
+{% for row in body %}
+{% for c in row %}{% if not loop.first %} & {% endif %}
+  {%- if c.type == 'th' %}{{parse_header(c, multirow_align, multicol_align, False, convert_css)}}{% else %}{{parse_cell(c.cellstyle, c.display_value, convert_css)}}{% endif %}
+{%- endfor %} \\
+{% if clines and clines[loop.index] | length > 0 %}
+  {%- for cline in clines[loop.index] %}{% if not loop.first %} {% endif %}{{ cline }}{% endfor %}
+
+{% endif %}
+{% endfor %}
+{% set bottomrule = parse_table(table_styles, 'bottomrule') %}
+{% if bottomrule is not none %}
+\{{bottomrule}}
+{% endif %}
+\end{tabular}
+{% if environment or parse_wrap(table_styles, caption) %}
+\end{% raw %}{{% endraw %}{{environment if environment else "table"}}{% raw %}}{% endraw %}
+
+{% endif %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/string.tpl b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/string.tpl
new file mode 100644
index 0000000000000000000000000000000000000000..06aeb2b4e413c61a912b535056c19c794d4b9c85
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/templates/string.tpl
@@ -0,0 +1,12 @@
+{% for r in head %}
+{% for c in r %}{% if c["is_visible"] %}
+{{ c["display_value"] }}{% if not loop.last %}{{ delimiter }}{% endif %}
+{% endif %}{% endfor %}
+
+{% endfor %}
+{% for r in body %}
+{% for c in r %}{% if c["is_visible"] %}
+{{ c["display_value"] }}{% if not loop.last %}{{ delimiter }}{% endif %}
+{% endif %}{% endfor %}
+
+{% endfor %}
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/formats/xml.py b/.venv/lib/python3.13/site-packages/pandas/io/formats/xml.py
new file mode 100644
index 0000000000000000000000000000000000000000..f56fca8d7ef4446727bfa34166b0c6b5a2856338
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/formats/xml.py
@@ -0,0 +1,560 @@
+"""
+:mod:`pandas.io.formats.xml` is a module for formatting data in XML.
+"""
+from __future__ import annotations
+
+import codecs
+import io
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    final,
+)
+import warnings
+
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import (
+    cache_readonly,
+    doc,
+)
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.missing import isna
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import get_handle
+from pandas.io.xml import (
+    get_data_from_filepath,
+    preprocess_data,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        ReadBuffer,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+    from pandas import DataFrame
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    compression_options=_shared_docs["compression_options"] % "path_or_buffer",
+)
+class _BaseXMLFormatter:
+    """
+    Subclass for formatting data in XML.
+
+    Parameters
+    ----------
+    path_or_buffer : str or file-like
+        This can be either a string of raw XML, a valid URL,
+        file or file-like object.
+
+    index : bool
+        Whether to include index in xml document.
+
+    row_name : str
+        Name for root of xml document. Default is 'data'.
+
+    root_name : str
+        Name for row elements of xml document. Default is 'row'.
+
+    na_rep : str
+        Missing data representation.
+
+    attrs_cols : list
+        List of columns to write as attributes in row element.
+
+    elem_cols : list
+        List of columns to write as children in row element.
+
+    namespaces : dict
+        The namespaces to define in XML document as dicts with key
+        being namespace and value the URI.
+
+    prefix : str
+        The prefix for each element in XML document including root.
+
+    encoding : str
+        Encoding of xml object or document.
+
+    xml_declaration : bool
+        Whether to include xml declaration at top line item in xml.
+
+    pretty_print : bool
+        Whether to write xml document with line breaks and indentation.
+
+    stylesheet : str or file-like
+        A URL, file, file-like object, or a raw string containing XSLT.
+
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    {storage_options}
+
+    See also
+    --------
+    pandas.io.formats.xml.EtreeXMLFormatter
+    pandas.io.formats.xml.LxmlXMLFormatter
+
+    """
+
+    def __init__(
+        self,
+        frame: DataFrame,
+        path_or_buffer: FilePath | WriteBuffer[bytes] | WriteBuffer[str] | None = None,
+        index: bool = True,
+        root_name: str | None = "data",
+        row_name: str | None = "row",
+        na_rep: str | None = None,
+        attr_cols: list[str] | None = None,
+        elem_cols: list[str] | None = None,
+        namespaces: dict[str | None, str] | None = None,
+        prefix: str | None = None,
+        encoding: str = "utf-8",
+        xml_declaration: bool | None = True,
+        pretty_print: bool | None = True,
+        stylesheet: FilePath | ReadBuffer[str] | ReadBuffer[bytes] | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+    ) -> None:
+        self.frame = frame
+        self.path_or_buffer = path_or_buffer
+        self.index = index
+        self.root_name = root_name
+        self.row_name = row_name
+        self.na_rep = na_rep
+        self.attr_cols = attr_cols
+        self.elem_cols = elem_cols
+        self.namespaces = namespaces
+        self.prefix = prefix
+        self.encoding = encoding
+        self.xml_declaration = xml_declaration
+        self.pretty_print = pretty_print
+        self.stylesheet = stylesheet
+        self.compression: CompressionOptions = compression
+        self.storage_options = storage_options
+
+        self.orig_cols = self.frame.columns.tolist()
+        self.frame_dicts = self._process_dataframe()
+
+        self._validate_columns()
+        self._validate_encoding()
+        self.prefix_uri = self._get_prefix_uri()
+        self._handle_indexes()
+
+    def _build_tree(self) -> bytes:
+        """
+        Build tree from  data.
+
+        This method initializes the root and builds attributes and elements
+        with optional namespaces.
+        """
+        raise AbstractMethodError(self)
+
+    @final
+    def _validate_columns(self) -> None:
+        """
+        Validate elems_cols and attrs_cols.
+
+        This method will check if columns is list-like.
+
+        Raises
+        ------
+        ValueError
+            * If value is not a list and less then length of nodes.
+        """
+        if self.attr_cols and not is_list_like(self.attr_cols):
+            raise TypeError(
+                f"{type(self.attr_cols).__name__} is not a valid type for attr_cols"
+            )
+
+        if self.elem_cols and not is_list_like(self.elem_cols):
+            raise TypeError(
+                f"{type(self.elem_cols).__name__} is not a valid type for elem_cols"
+            )
+
+    @final
+    def _validate_encoding(self) -> None:
+        """
+        Validate encoding.
+
+        This method will check if encoding is among listed under codecs.
+
+        Raises
+        ------
+        LookupError
+            * If encoding is not available in codecs.
+        """
+
+        codecs.lookup(self.encoding)
+
+    @final
+    def _process_dataframe(self) -> dict[int | str, dict[str, Any]]:
+        """
+        Adjust Data Frame to fit xml output.
+
+        This method will adjust underlying data frame for xml output,
+        including optionally replacing missing values and including indexes.
+        """
+
+        df = self.frame
+
+        if self.index:
+            df = df.reset_index()
+
+        if self.na_rep is not None:
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore",
+                    "Downcasting object dtype arrays",
+                    category=FutureWarning,
+                )
+                df = df.fillna(self.na_rep)
+
+        return df.to_dict(orient="index")
+
+    @final
+    def _handle_indexes(self) -> None:
+        """
+        Handle indexes.
+
+        This method will add indexes into attr_cols or elem_cols.
+        """
+
+        if not self.index:
+            return
+
+        first_key = next(iter(self.frame_dicts))
+        indexes: list[str] = [
+            x for x in self.frame_dicts[first_key].keys() if x not in self.orig_cols
+        ]
+
+        if self.attr_cols:
+            self.attr_cols = indexes + self.attr_cols
+
+        if self.elem_cols:
+            self.elem_cols = indexes + self.elem_cols
+
+    def _get_prefix_uri(self) -> str:
+        """
+        Get uri of namespace prefix.
+
+        This method retrieves corresponding URI to prefix in namespaces.
+
+        Raises
+        ------
+        KeyError
+            *If prefix is not included in namespace dict.
+        """
+
+        raise AbstractMethodError(self)
+
+    @final
+    def _other_namespaces(self) -> dict:
+        """
+        Define other namespaces.
+
+        This method will build dictionary of namespaces attributes
+        for root element, conditionally with optional namespaces and
+        prefix.
+        """
+
+        nmsp_dict: dict[str, str] = {}
+        if self.namespaces:
+            nmsp_dict = {
+                f"xmlns{p if p=='' else f':{p}'}": n
+                for p, n in self.namespaces.items()
+                if n != self.prefix_uri[1:-1]
+            }
+
+        return nmsp_dict
+
+    @final
+    def _build_attribs(self, d: dict[str, Any], elem_row: Any) -> Any:
+        """
+        Create attributes of row.
+
+        This method adds attributes using attr_cols to row element and
+        works with tuples for multindex or hierarchical columns.
+        """
+
+        if not self.attr_cols:
+            return elem_row
+
+        for col in self.attr_cols:
+            attr_name = self._get_flat_col_name(col)
+            try:
+                if not isna(d[col]):
+                    elem_row.attrib[attr_name] = str(d[col])
+            except KeyError:
+                raise KeyError(f"no valid column, {col}")
+        return elem_row
+
+    @final
+    def _get_flat_col_name(self, col: str | tuple) -> str:
+        flat_col = col
+        if isinstance(col, tuple):
+            flat_col = (
+                "".join([str(c) for c in col]).strip()
+                if "" in col
+                else "_".join([str(c) for c in col]).strip()
+            )
+        return f"{self.prefix_uri}{flat_col}"
+
+    @cache_readonly
+    def _sub_element_cls(self):
+        raise AbstractMethodError(self)
+
+    @final
+    def _build_elems(self, d: dict[str, Any], elem_row: Any) -> None:
+        """
+        Create child elements of row.
+
+        This method adds child elements using elem_cols to row element and
+        works with tuples for multindex or hierarchical columns.
+        """
+        sub_element_cls = self._sub_element_cls
+
+        if not self.elem_cols:
+            return
+
+        for col in self.elem_cols:
+            elem_name = self._get_flat_col_name(col)
+            try:
+                val = None if isna(d[col]) or d[col] == "" else str(d[col])
+                sub_element_cls(elem_row, elem_name).text = val
+            except KeyError:
+                raise KeyError(f"no valid column, {col}")
+
+    @final
+    def write_output(self) -> str | None:
+        xml_doc = self._build_tree()
+
+        if self.path_or_buffer is not None:
+            with get_handle(
+                self.path_or_buffer,
+                "wb",
+                compression=self.compression,
+                storage_options=self.storage_options,
+                is_text=False,
+            ) as handles:
+                handles.handle.write(xml_doc)
+            return None
+
+        else:
+            return xml_doc.decode(self.encoding).rstrip()
+
+
+class EtreeXMLFormatter(_BaseXMLFormatter):
+    """
+    Class for formatting data in xml using Python standard library
+    modules: `xml.etree.ElementTree` and `xml.dom.minidom`.
+    """
+
+    def _build_tree(self) -> bytes:
+        from xml.etree.ElementTree import (
+            Element,
+            SubElement,
+            tostring,
+        )
+
+        self.root = Element(
+            f"{self.prefix_uri}{self.root_name}", attrib=self._other_namespaces()
+        )
+
+        for d in self.frame_dicts.values():
+            elem_row = SubElement(self.root, f"{self.prefix_uri}{self.row_name}")
+
+            if not self.attr_cols and not self.elem_cols:
+                self.elem_cols = list(d.keys())
+                self._build_elems(d, elem_row)
+
+            else:
+                elem_row = self._build_attribs(d, elem_row)
+                self._build_elems(d, elem_row)
+
+        self.out_xml = tostring(
+            self.root,
+            method="xml",
+            encoding=self.encoding,
+            xml_declaration=self.xml_declaration,
+        )
+
+        if self.pretty_print:
+            self.out_xml = self._prettify_tree()
+
+        if self.stylesheet is not None:
+            raise ValueError(
+                "To use stylesheet, you need lxml installed and selected as parser."
+            )
+
+        return self.out_xml
+
+    def _get_prefix_uri(self) -> str:
+        from xml.etree.ElementTree import register_namespace
+
+        uri = ""
+        if self.namespaces:
+            for p, n in self.namespaces.items():
+                if isinstance(p, str) and isinstance(n, str):
+                    register_namespace(p, n)
+            if self.prefix:
+                try:
+                    uri = f"{{{self.namespaces[self.prefix]}}}"
+                except KeyError:
+                    raise KeyError(f"{self.prefix} is not included in namespaces")
+            elif "" in self.namespaces:
+                uri = f'{{{self.namespaces[""]}}}'
+            else:
+                uri = ""
+
+        return uri
+
+    @cache_readonly
+    def _sub_element_cls(self):
+        from xml.etree.ElementTree import SubElement
+
+        return SubElement
+
+    def _prettify_tree(self) -> bytes:
+        """
+        Output tree for pretty print format.
+
+        This method will pretty print xml with line breaks and indentation.
+        """
+
+        from xml.dom.minidom import parseString
+
+        dom = parseString(self.out_xml)
+
+        return dom.toprettyxml(indent="  ", encoding=self.encoding)
+
+
+class LxmlXMLFormatter(_BaseXMLFormatter):
+    """
+    Class for formatting data in xml using Python standard library
+    modules: `xml.etree.ElementTree` and `xml.dom.minidom`.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+        self._convert_empty_str_key()
+
+    def _build_tree(self) -> bytes:
+        """
+        Build tree from  data.
+
+        This method initializes the root and builds attributes and elements
+        with optional namespaces.
+        """
+        from lxml.etree import (
+            Element,
+            SubElement,
+            tostring,
+        )
+
+        self.root = Element(f"{self.prefix_uri}{self.root_name}", nsmap=self.namespaces)
+
+        for d in self.frame_dicts.values():
+            elem_row = SubElement(self.root, f"{self.prefix_uri}{self.row_name}")
+
+            if not self.attr_cols and not self.elem_cols:
+                self.elem_cols = list(d.keys())
+                self._build_elems(d, elem_row)
+
+            else:
+                elem_row = self._build_attribs(d, elem_row)
+                self._build_elems(d, elem_row)
+
+        self.out_xml = tostring(
+            self.root,
+            pretty_print=self.pretty_print,
+            method="xml",
+            encoding=self.encoding,
+            xml_declaration=self.xml_declaration,
+        )
+
+        if self.stylesheet is not None:
+            self.out_xml = self._transform_doc()
+
+        return self.out_xml
+
+    def _convert_empty_str_key(self) -> None:
+        """
+        Replace zero-length string in `namespaces`.
+
+        This method will replace '' with None to align to `lxml`
+        requirement that empty string prefixes are not allowed.
+        """
+
+        if self.namespaces and "" in self.namespaces.keys():
+            self.namespaces[None] = self.namespaces.pop("", "default")
+
+    def _get_prefix_uri(self) -> str:
+        uri = ""
+        if self.namespaces:
+            if self.prefix:
+                try:
+                    uri = f"{{{self.namespaces[self.prefix]}}}"
+                except KeyError:
+                    raise KeyError(f"{self.prefix} is not included in namespaces")
+            elif "" in self.namespaces:
+                uri = f'{{{self.namespaces[""]}}}'
+            else:
+                uri = ""
+
+        return uri
+
+    @cache_readonly
+    def _sub_element_cls(self):
+        from lxml.etree import SubElement
+
+        return SubElement
+
+    def _transform_doc(self) -> bytes:
+        """
+        Parse stylesheet from file or buffer and run it.
+
+        This method will parse stylesheet object into tree for parsing
+        conditionally by its specific object type, then transforms
+        original tree with XSLT script.
+        """
+        from lxml.etree import (
+            XSLT,
+            XMLParser,
+            fromstring,
+            parse,
+        )
+
+        style_doc = self.stylesheet
+        assert style_doc is not None  # is ensured by caller
+
+        handle_data = get_data_from_filepath(
+            filepath_or_buffer=style_doc,
+            encoding=self.encoding,
+            compression=self.compression,
+            storage_options=self.storage_options,
+        )
+
+        with preprocess_data(handle_data) as xml_data:
+            curr_parser = XMLParser(encoding=self.encoding)
+
+            if isinstance(xml_data, io.StringIO):
+                xsl_doc = fromstring(
+                    xml_data.getvalue().encode(self.encoding), parser=curr_parser
+                )
+            else:
+                xsl_doc = parse(xml_data, parser=curr_parser)
+
+        transformer = XSLT(xsl_doc)
+        new_doc = transformer(self.root)
+
+        return bytes(new_doc)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/gbq.py b/.venv/lib/python3.13/site-packages/pandas/io/gbq.py
new file mode 100644
index 0000000000000000000000000000000000000000..24e4e0b7cef0a5fa66a70fa0ad70b52364b02091
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/gbq.py
@@ -0,0 +1,255 @@
+""" Google BigQuery support """
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+import warnings
+
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._exceptions import find_stack_level
+
+if TYPE_CHECKING:
+    from google.auth.credentials import Credentials
+
+    from pandas import DataFrame
+
+
+def _try_import():
+    # since pandas is a dependency of pandas-gbq
+    # we need to import on first use
+    msg = (
+        "pandas-gbq is required to load data from Google BigQuery. "
+        "See the docs: https://pandas-gbq.readthedocs.io."
+    )
+    pandas_gbq = import_optional_dependency("pandas_gbq", extra=msg)
+    return pandas_gbq
+
+
+def read_gbq(
+    query: str,
+    project_id: str | None = None,
+    index_col: str | None = None,
+    col_order: list[str] | None = None,
+    reauth: bool = False,
+    auth_local_webserver: bool = True,
+    dialect: str | None = None,
+    location: str | None = None,
+    configuration: dict[str, Any] | None = None,
+    credentials: Credentials | None = None,
+    use_bqstorage_api: bool | None = None,
+    max_results: int | None = None,
+    progress_bar_type: str | None = None,
+) -> DataFrame:
+    """
+    Load data from Google BigQuery.
+
+    .. deprecated:: 2.2.0
+
+       Please use ``pandas_gbq.read_gbq`` instead.
+
+    This function requires the `pandas-gbq package
+    `__.
+
+    See the `How to authenticate with Google BigQuery
+    `__
+    guide for authentication instructions.
+
+    Parameters
+    ----------
+    query : str
+        SQL-Like Query to return data values.
+    project_id : str, optional
+        Google BigQuery Account project ID. Optional when available from
+        the environment.
+    index_col : str, optional
+        Name of result column to use for index in results DataFrame.
+    col_order : list(str), optional
+        List of BigQuery column names in the desired order for results
+        DataFrame.
+    reauth : bool, default False
+        Force Google BigQuery to re-authenticate the user. This is useful
+        if multiple accounts are used.
+    auth_local_webserver : bool, default True
+        Use the `local webserver flow`_ instead of the `console flow`_
+        when getting user credentials.
+
+        .. _local webserver flow:
+            https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
+        .. _console flow:
+            https://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console
+
+        *New in version 0.2.0 of pandas-gbq*.
+
+        .. versionchanged:: 1.5.0
+           Default value is changed to ``True``. Google has deprecated the
+           ``auth_local_webserver = False`` `"out of band" (copy-paste)
+           flow
+           `_.
+    dialect : str, default 'legacy'
+        Note: The default value is changing to 'standard' in a future version.
+
+        SQL syntax dialect to use. Value can be one of:
+
+        ``'legacy'``
+            Use BigQuery's legacy SQL dialect. For more information see
+            `BigQuery Legacy SQL Reference
+            `__.
+        ``'standard'``
+            Use BigQuery's standard SQL, which is
+            compliant with the SQL 2011 standard. For more information
+            see `BigQuery Standard SQL Reference
+            `__.
+    location : str, optional
+        Location where the query job should run. See the `BigQuery locations
+        documentation
+        `__ for a
+        list of available locations. The location must match that of any
+        datasets used in the query.
+
+        *New in version 0.5.0 of pandas-gbq*.
+    configuration : dict, optional
+        Query config parameters for job processing.
+        For example:
+
+            configuration = {'query': {'useQueryCache': False}}
+
+        For more information see `BigQuery REST API Reference
+        `__.
+    credentials : google.auth.credentials.Credentials, optional
+        Credentials for accessing Google APIs. Use this parameter to override
+        default credentials, such as to use Compute Engine
+        :class:`google.auth.compute_engine.Credentials` or Service Account
+        :class:`google.oauth2.service_account.Credentials` directly.
+
+        *New in version 0.8.0 of pandas-gbq*.
+    use_bqstorage_api : bool, default False
+        Use the `BigQuery Storage API
+        `__ to
+        download query results quickly, but at an increased cost. To use this
+        API, first `enable it in the Cloud Console
+        `__.
+        You must also have the `bigquery.readsessions.create
+        `__
+        permission on the project you are billing queries to.
+
+        This feature requires version 0.10.0 or later of the ``pandas-gbq``
+        package. It also requires the ``google-cloud-bigquery-storage`` and
+        ``fastavro`` packages.
+
+    max_results : int, optional
+        If set, limit the maximum number of rows to fetch from the query
+        results.
+
+    progress_bar_type : Optional, str
+        If set, use the `tqdm `__ library to
+        display a progress bar while the data downloads. Install the
+        ``tqdm`` package to use this feature.
+
+        Possible values of ``progress_bar_type`` include:
+
+        ``None``
+            No progress bar.
+        ``'tqdm'``
+            Use the :func:`tqdm.tqdm` function to print a progress bar
+            to :data:`sys.stderr`.
+        ``'tqdm_notebook'``
+            Use the :func:`tqdm.tqdm_notebook` function to display a
+            progress bar as a Jupyter notebook widget.
+        ``'tqdm_gui'``
+            Use the :func:`tqdm.tqdm_gui` function to display a
+            progress bar as a graphical dialog box.
+
+    Returns
+    -------
+    df: DataFrame
+        DataFrame representing results of query.
+
+    See Also
+    --------
+    pandas_gbq.read_gbq : This function in the pandas-gbq library.
+    DataFrame.to_gbq : Write a DataFrame to Google BigQuery.
+
+    Examples
+    --------
+    Example taken from `Google BigQuery documentation
+    `_
+
+    >>> sql = "SELECT name FROM table_name WHERE state = 'TX' LIMIT 100;"
+    >>> df = pd.read_gbq(sql, dialect="standard")  # doctest: +SKIP
+    >>> project_id = "your-project-id"  # doctest: +SKIP
+    >>> df = pd.read_gbq(sql,
+    ...                  project_id=project_id,
+    ...                  dialect="standard"
+    ...                  )  # doctest: +SKIP
+    """
+    warnings.warn(
+        "read_gbq is deprecated and will be removed in a future version. "
+        "Please use pandas_gbq.read_gbq instead: "
+        "https://pandas-gbq.readthedocs.io/en/latest/api.html#pandas_gbq.read_gbq",
+        FutureWarning,
+        stacklevel=find_stack_level(),
+    )
+    pandas_gbq = _try_import()
+
+    kwargs: dict[str, str | bool | int | None] = {}
+
+    # START: new kwargs.  Don't populate unless explicitly set.
+    if use_bqstorage_api is not None:
+        kwargs["use_bqstorage_api"] = use_bqstorage_api
+    if max_results is not None:
+        kwargs["max_results"] = max_results
+
+    kwargs["progress_bar_type"] = progress_bar_type
+    # END: new kwargs
+
+    return pandas_gbq.read_gbq(
+        query,
+        project_id=project_id,
+        index_col=index_col,
+        col_order=col_order,
+        reauth=reauth,
+        auth_local_webserver=auth_local_webserver,
+        dialect=dialect,
+        location=location,
+        configuration=configuration,
+        credentials=credentials,
+        **kwargs,
+    )
+
+
+def to_gbq(
+    dataframe: DataFrame,
+    destination_table: str,
+    project_id: str | None = None,
+    chunksize: int | None = None,
+    reauth: bool = False,
+    if_exists: str = "fail",
+    auth_local_webserver: bool = True,
+    table_schema: list[dict[str, str]] | None = None,
+    location: str | None = None,
+    progress_bar: bool = True,
+    credentials: Credentials | None = None,
+) -> None:
+    warnings.warn(
+        "to_gbq is deprecated and will be removed in a future version. "
+        "Please use pandas_gbq.to_gbq instead: "
+        "https://pandas-gbq.readthedocs.io/en/latest/api.html#pandas_gbq.to_gbq",
+        FutureWarning,
+        stacklevel=find_stack_level(),
+    )
+    pandas_gbq = _try_import()
+    pandas_gbq.to_gbq(
+        dataframe,
+        destination_table,
+        project_id=project_id,
+        chunksize=chunksize,
+        reauth=reauth,
+        if_exists=if_exists,
+        auth_local_webserver=auth_local_webserver,
+        table_schema=table_schema,
+        location=location,
+        progress_bar=progress_bar,
+        credentials=credentials,
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/html.py b/.venv/lib/python3.13/site-packages/pandas/io/html.py
new file mode 100644
index 0000000000000000000000000000000000000000..4eeeb1b655f8ac55309edeacd593f5a5c2516678
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/html.py
@@ -0,0 +1,1259 @@
+"""
+:mod:`pandas.io.html` is a module containing functionality for dealing with
+HTML IO.
+
+"""
+
+from __future__ import annotations
+
+from collections import abc
+import numbers
+import re
+from re import Pattern
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    cast,
+)
+import warnings
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import (
+    AbstractMethodError,
+    EmptyDataError,
+)
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import is_list_like
+
+from pandas import isna
+from pandas.core.indexes.base import Index
+from pandas.core.indexes.multi import MultiIndex
+from pandas.core.series import Series
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import (
+    file_exists,
+    get_handle,
+    is_file_like,
+    is_fsspec_url,
+    is_url,
+    stringify_path,
+    validate_header_arg,
+)
+from pandas.io.formats.printing import pprint_thing
+from pandas.io.parsers import TextParser
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        BaseBuffer,
+        DtypeBackend,
+        FilePath,
+        HTMLFlavors,
+        ReadBuffer,
+        StorageOptions,
+    )
+
+    from pandas import DataFrame
+
+#############
+# READ HTML #
+#############
+_RE_WHITESPACE = re.compile(r"[\r\n]+|\s{2,}")
+
+
+def _remove_whitespace(s: str, regex: Pattern = _RE_WHITESPACE) -> str:
+    """
+    Replace extra whitespace inside of a string with a single space.
+
+    Parameters
+    ----------
+    s : str or unicode
+        The string from which to remove extra whitespace.
+    regex : re.Pattern
+        The regular expression to use to remove extra whitespace.
+
+    Returns
+    -------
+    subd : str or unicode
+        `s` with all extra whitespace replaced with a single space.
+    """
+    return regex.sub(" ", s.strip())
+
+
+def _get_skiprows(skiprows: int | Sequence[int] | slice | None) -> int | Sequence[int]:
+    """
+    Get an iterator given an integer, slice or container.
+
+    Parameters
+    ----------
+    skiprows : int, slice, container
+        The iterator to use to skip rows; can also be a slice.
+
+    Raises
+    ------
+    TypeError
+        * If `skiprows` is not a slice, integer, or Container
+
+    Returns
+    -------
+    it : iterable
+        A proper iterator to use to skip rows of a DataFrame.
+    """
+    if isinstance(skiprows, slice):
+        start, step = skiprows.start or 0, skiprows.step or 1
+        return list(range(start, skiprows.stop, step))
+    elif isinstance(skiprows, numbers.Integral) or is_list_like(skiprows):
+        return cast("int | Sequence[int]", skiprows)
+    elif skiprows is None:
+        return 0
+    raise TypeError(f"{type(skiprows).__name__} is not a valid type for skipping rows")
+
+
+def _read(
+    obj: FilePath | BaseBuffer,
+    encoding: str | None,
+    storage_options: StorageOptions | None,
+) -> str | bytes:
+    """
+    Try to read from a url, file or string.
+
+    Parameters
+    ----------
+    obj : str, unicode, path object, or file-like object
+
+    Returns
+    -------
+    raw_text : str
+    """
+    text: str | bytes
+    if (
+        is_url(obj)
+        or hasattr(obj, "read")
+        or (isinstance(obj, str) and file_exists(obj))
+    ):
+        with get_handle(
+            obj, "r", encoding=encoding, storage_options=storage_options
+        ) as handles:
+            text = handles.handle.read()
+    elif isinstance(obj, (str, bytes)):
+        text = obj
+    else:
+        raise TypeError(f"Cannot read object of type '{type(obj).__name__}'")
+    return text
+
+
+class _HtmlFrameParser:
+    """
+    Base class for parsers that parse HTML into DataFrames.
+
+    Parameters
+    ----------
+    io : str or file-like
+        This can be either a string of raw HTML, a valid URL using the HTTP,
+        FTP, or FILE protocols or a file-like object.
+
+    match : str or regex
+        The text to match in the document.
+
+    attrs : dict
+        List of HTML  element attributes to match.
+
+    encoding : str
+        Encoding to be used by parser
+
+    displayed_only : bool
+        Whether or not items with "display:none" should be ignored
+
+    extract_links : {None, "all", "header", "body", "footer"}
+        Table elements in the specified section(s) with  tags will have their
+        href extracted.
+
+        .. versionadded:: 1.5.0
+
+    Attributes
+    ----------
+    io : str or file-like
+        raw HTML, URL, or file-like object
+
+    match : regex
+        The text to match in the raw HTML
+
+    attrs : dict-like
+        A dictionary of valid table attributes to use to search for table
+        elements.
+
+    encoding : str
+        Encoding to be used by parser
+
+    displayed_only : bool
+        Whether or not items with "display:none" should be ignored
+
+    extract_links : {None, "all", "header", "body", "footer"}
+        Table elements in the specified section(s) with  tags will have their
+        href extracted.
+
+        .. versionadded:: 1.5.0
+
+    Notes
+    -----
+    To subclass this class effectively you must override the following methods:
+        * :func:`_build_doc`
+        * :func:`_attr_getter`
+        * :func:`_href_getter`
+        * :func:`_text_getter`
+        * :func:`_parse_td`
+        * :func:`_parse_thead_tr`
+        * :func:`_parse_tbody_tr`
+        * :func:`_parse_tfoot_tr`
+        * :func:`_parse_tables`
+        * :func:`_equals_tag`
+    See each method's respective documentation for details on their
+    functionality.
+    """
+
+    def __init__(
+        self,
+        io: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+        match: str | Pattern,
+        attrs: dict[str, str] | None,
+        encoding: str,
+        displayed_only: bool,
+        extract_links: Literal[None, "header", "footer", "body", "all"],
+        storage_options: StorageOptions = None,
+    ) -> None:
+        self.io = io
+        self.match = match
+        self.attrs = attrs
+        self.encoding = encoding
+        self.displayed_only = displayed_only
+        self.extract_links = extract_links
+        self.storage_options = storage_options
+
+    def parse_tables(self):
+        """
+        Parse and return all tables from the DOM.
+
+        Returns
+        -------
+        list of parsed (header, body, footer) tuples from tables.
+        """
+        tables = self._parse_tables(self._build_doc(), self.match, self.attrs)
+        return (self._parse_thead_tbody_tfoot(table) for table in tables)
+
+    def _attr_getter(self, obj, attr):
+        """
+        Return the attribute value of an individual DOM node.
+
+        Parameters
+        ----------
+        obj : node-like
+            A DOM node.
+
+        attr : str or unicode
+            The attribute, such as "colspan"
+
+        Returns
+        -------
+        str or unicode
+            The attribute value.
+        """
+        # Both lxml and BeautifulSoup have the same implementation:
+        return obj.get(attr)
+
+    def _href_getter(self, obj) -> str | None:
+        """
+        Return a href if the DOM node contains a child  or None.
+
+        Parameters
+        ----------
+        obj : node-like
+            A DOM node.
+
+        Returns
+        -------
+        href : str or unicode
+            The href from the  child of the DOM node.
+        """
+        raise AbstractMethodError(self)
+
+    def _text_getter(self, obj):
+        """
+        Return the text of an individual DOM node.
+
+        Parameters
+        ----------
+        obj : node-like
+            A DOM node.
+
+        Returns
+        -------
+        text : str or unicode
+            The text from an individual DOM node.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_td(self, obj):
+        """
+        Return the td elements from a row element.
+
+        Parameters
+        ----------
+        obj : node-like
+            A DOM  node.
+
+        Returns
+        -------
+        list of node-like
+            These are the elements of each row, i.e., the columns.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_thead_tr(self, table):
+        """
+        Return the list of thead row elements from the parsed table element.
+
+        Parameters
+        ----------
+        table : a table element that contains zero or more thead elements.
+
+        Returns
+        -------
+        list of node-like
+            These are the  row elements of a table.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_tbody_tr(self, table):
+        """
+        Return the list of tbody row elements from the parsed table element.
+
+        HTML5 table bodies consist of either 0 or more  elements (which
+        only contain  elements) or 0 or more  elements. This method
+        checks for both structures.
+
+        Parameters
+        ----------
+        table : a table element that contains row elements.
+
+        Returns
+        -------
+        list of node-like
+            These are the  row elements of a table.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_tfoot_tr(self, table):
+        """
+        Return the list of tfoot row elements from the parsed table element.
+
+        Parameters
+        ----------
+        table : a table element that contains row elements.
+
+        Returns
+        -------
+        list of node-like
+            These are the  row elements of a table.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_tables(self, document, match, attrs):
+        """
+        Return all tables from the parsed DOM.
+
+        Parameters
+        ----------
+        document : the DOM from which to parse the table element.
+
+        match : str or regular expression
+            The text to search for in the DOM tree.
+
+        attrs : dict
+            A dictionary of table attributes that can be used to disambiguate
+            multiple tables on a page.
+
+        Raises
+        ------
+        ValueError : `match` does not match any text in the document.
+
+        Returns
+        -------
+        list of node-like
+            HTML 
 elements to be parsed into raw data.
+        """
+        raise AbstractMethodError(self)
+
+    def _equals_tag(self, obj, tag) -> bool:
+        """
+        Return whether an individual DOM node matches a tag
+
+        Parameters
+        ----------
+        obj : node-like
+            A DOM node.
+
+        tag : str
+            Tag name to be checked for equality.
+
+        Returns
+        -------
+        boolean
+            Whether `obj`'s tag name is `tag`
+        """
+        raise AbstractMethodError(self)
+
+    def _build_doc(self):
+        """
+        Return a tree-like object that can be used to iterate over the DOM.
+
+        Returns
+        -------
+        node-like
+            The DOM from which to parse the table element.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_thead_tbody_tfoot(self, table_html):
+        """
+        Given a table, return parsed header, body, and foot.
+
+        Parameters
+        ----------
+        table_html : node-like
+
+        Returns
+        -------
+        tuple of (header, body, footer), each a list of list-of-text rows.
+
+        Notes
+        -----
+        Header and body are lists-of-lists. Top level list is a list of
+        rows. Each row is a list of str text.
+
+        Logic: Use , ,  elements to identify
+               header, body, and footer, otherwise:
+               - Put all rows into body
+               - Move rows from top of body to header only if
+                 all elements inside row are . Move the top all- or 
+            while body_rows and row_is_all_th(body_rows[0]):
+                header_rows.append(body_rows.pop(0))
+
+        header = self._expand_colspan_rowspan(header_rows, section="header")
+        body = self._expand_colspan_rowspan(body_rows, section="body")
+        footer = self._expand_colspan_rowspan(footer_rows, section="footer")
+
+        return header, body, footer
+
+    def _expand_colspan_rowspan(
+        self, rows, section: Literal["header", "footer", "body"]
+    ):
+        """
+        Given a list of s, return a list of text rows.
+
+        Parameters
+        ----------
+        rows : list of node-like
+            List of s
+        section : the section that the rows belong to (header, body or footer).
+
+        Returns
+        -------
+        list of list
+            Each returned row is a list of str text, or tuple (text, link)
+            if extract_links is not None.
+
+        Notes
+        -----
+        Any cell with ``rowspan`` or ``colspan`` will have its contents copied
+        to subsequent cells.
+        """
+        all_texts = []  # list of rows, each a list of str
+        text: str | tuple
+        remainder: list[
+            tuple[int, str | tuple, int]
+        ] = []  # list of (index, text, nrows)
+
+        for tr in rows:
+            texts = []  # the output for this row
+            next_remainder = []
+
+            index = 0
+            tds = self._parse_td(tr)
+            for td in tds:
+                # Append texts from previous rows with rowspan>1 that come
+                # before this  or  (see _parse_thead_tr).
+        return row.xpath("./td|./th")
+
+    def _parse_tables(self, document, match, kwargs):
+        pattern = match.pattern
+
+        # 1. check all descendants for the given pattern and only search tables
+        # GH 49929
+        xpath_expr = f"//table[.//text()[re:test(., {repr(pattern)})]]"
+
+        # if any table attributes were given build an xpath expression to
+        # search for them
+        if kwargs:
+            xpath_expr += _build_xpath_expr(kwargs)
+
+        tables = document.xpath(xpath_expr, namespaces=_re_namespace)
+
+        tables = self._handle_hidden_tables(tables, "attrib")
+        if self.displayed_only:
+            for table in tables:
+                # lxml utilizes XPATH 1.0 which does not have regex
+                # support. As a result, we find all elements with a style
+                # attribute and iterate them to check for display:none
+                for elem in table.xpath(".//style"):
+                    elem.drop_tree()
+                for elem in table.xpath(".//*[@style]"):
+                    if "display:none" in elem.attrib.get("style", "").replace(" ", ""):
+                        elem.drop_tree()
+        if not tables:
+            raise ValueError(f"No tables found matching regex {repr(pattern)}")
+        return tables
+
+    def _equals_tag(self, obj, tag) -> bool:
+        return obj.tag == tag
+
+    def _build_doc(self):
+        """
+        Raises
+        ------
+        ValueError
+            * If a URL that lxml cannot parse is passed.
+
+        Exception
+            * Any other ``Exception`` thrown. For example, trying to parse a
+              URL that is syntactically correct on a machine with no internet
+              connection will fail.
+
+        See Also
+        --------
+        pandas.io.html._HtmlFrameParser._build_doc
+        """
+        from lxml.etree import XMLSyntaxError
+        from lxml.html import (
+            HTMLParser,
+            fromstring,
+            parse,
+        )
+
+        parser = HTMLParser(recover=True, encoding=self.encoding)
+
+        try:
+            if is_url(self.io):
+                with get_handle(
+                    self.io, "r", storage_options=self.storage_options
+                ) as f:
+                    r = parse(f.handle, parser=parser)
+            else:
+                # try to parse the input in the simplest way
+                r = parse(self.io, parser=parser)
+            try:
+                r = r.getroot()
+            except AttributeError:
+                pass
+        except (UnicodeDecodeError, OSError) as e:
+            # if the input is a blob of html goop
+            if not is_url(self.io):
+                r = fromstring(self.io, parser=parser)
+
+                try:
+                    r = r.getroot()
+                except AttributeError:
+                    pass
+            else:
+                raise e
+        else:
+            if not hasattr(r, "text_content"):
+                raise XMLSyntaxError("no text parsed from document", 0, 0, 0)
+
+        for br in r.xpath("*//br"):
+            br.tail = "\n" + (br.tail or "")
+
+        return r
+
+    def _parse_thead_tr(self, table):
+        rows = []
+
+        for thead in table.xpath(".//thead"):
+            rows.extend(thead.xpath("./tr"))
+
+            # HACK: lxml does not clean up the clearly-erroneous
+            # . (Missing ). Add
+            # the  and _pretend_ it's a ; _parse_td() will find its
+            # children as though it's a .
+            #
+            # Better solution would be to use html5lib.
+            elements_at_root = thead.xpath("./td|./th")
+            if elements_at_root:
+                rows.append(thead)
+
+        return rows
+
+    def _parse_tbody_tr(self, table):
+        from_tbody = table.xpath(".//tbody//tr")
+        from_root = table.xpath("./tr")
+        # HTML spec: at most one of these lists has content
+        return from_tbody + from_root
+
+    def _parse_tfoot_tr(self, table):
+        return table.xpath(".//tfoot//tr")
+
+
+def _expand_elements(body) -> None:
+    data = [len(elem) for elem in body]
+    lens = Series(data)
+    lens_max = lens.max()
+    not_max = lens[lens != lens_max]
+
+    empty = [""]
+    for ind, length in not_max.items():
+        body[ind] += empty * (lens_max - length)
+
+
+def _data_to_frame(**kwargs):
+    head, body, foot = kwargs.pop("data")
+    header = kwargs.pop("header")
+    kwargs["skiprows"] = _get_skiprows(kwargs["skiprows"])
+    if head:
+        body = head + body
+
+        # Infer header when there is a  or top 

+               - Move rows from bottom of body to footer only if
+                 all elements inside row are 
+        """
+        header_rows = self._parse_thead_tr(table_html)
+        body_rows = self._parse_tbody_tr(table_html)
+        footer_rows = self._parse_tfoot_tr(table_html)
+
+        def row_is_all_th(row):
+            return all(self._equals_tag(t, "th") for t in self._parse_td(row))
+
+        if not header_rows:
+            # The table has no 
 rows from
+            # body_rows to header_rows. (This is a common case because many
+            # tables in the wild have no 

+                while remainder and remainder[0][0] <= index:
+                    prev_i, prev_text, prev_rowspan = remainder.pop(0)
+                    texts.append(prev_text)
+                    if prev_rowspan > 1:
+                        next_remainder.append((prev_i, prev_text, prev_rowspan - 1))
+                    index += 1
+
+                # Append the text from this , colspan times
+                text = _remove_whitespace(self._text_getter(td))
+                if self.extract_links in ("all", section):
+                    href = self._href_getter(td)
+                    text = (text, href)
+                rowspan = int(self._attr_getter(td, "rowspan") or 1)
+                colspan = int(self._attr_getter(td, "colspan") or 1)
+
+                for _ in range(colspan):
+                    texts.append(text)
+                    if rowspan > 1:
+                        next_remainder.append((index, text, rowspan - 1))
+                    index += 1
+
+            # Append texts from previous rows at the final position
+            for prev_i, prev_text, prev_rowspan in remainder:
+                texts.append(prev_text)
+                if prev_rowspan > 1:
+                    next_remainder.append((prev_i, prev_text, prev_rowspan - 1))
+
+            all_texts.append(texts)
+            remainder = next_remainder
+
+        # Append rows that only appear because the previous row had non-1
+        # rowspan
+        while remainder:
+            next_remainder = []
+            texts = []
+            for prev_i, prev_text, prev_rowspan in remainder:
+                texts.append(prev_text)
+                if prev_rowspan > 1:
+                    next_remainder.append((prev_i, prev_text, prev_rowspan - 1))
+            all_texts.append(texts)
+            remainder = next_remainder
+
+        return all_texts
+
+    def _handle_hidden_tables(self, tbl_list, attr_name: str):
+        """
+        Return list of tables, potentially removing hidden elements
+
+        Parameters
+        ----------
+        tbl_list : list of node-like
+            Type of list elements will vary depending upon parser used
+        attr_name : str
+            Name of the accessor for retrieving HTML attributes
+
+        Returns
+        -------
+        list of node-like
+            Return type matches `tbl_list`
+        """
+        if not self.displayed_only:
+            return tbl_list
+
+        return [
+            x
+            for x in tbl_list
+            if "display:none"
+            not in getattr(x, attr_name).get("style", "").replace(" ", "")
+        ]
+
+
+class _BeautifulSoupHtml5LibFrameParser(_HtmlFrameParser):
+    """
+    HTML to DataFrame parser that uses BeautifulSoup under the hood.
+
+    See Also
+    --------
+    pandas.io.html._HtmlFrameParser
+    pandas.io.html._LxmlFrameParser
+
+    Notes
+    -----
+    Documentation strings for this class are in the base class
+    :class:`pandas.io.html._HtmlFrameParser`.
+    """
+
+    def _parse_tables(self, document, match, attrs):
+        element_name = "table"
+        tables = document.find_all(element_name, attrs=attrs)
+        if not tables:
+            raise ValueError("No tables found")
+
+        result = []
+        unique_tables = set()
+        tables = self._handle_hidden_tables(tables, "attrs")
+
+        for table in tables:
+            if self.displayed_only:
+                for elem in table.find_all("style"):
+                    elem.decompose()
+
+                for elem in table.find_all(style=re.compile(r"display:\s*none")):
+                    elem.decompose()
+
+            if table not in unique_tables and table.find(string=match) is not None:
+                result.append(table)
+            unique_tables.add(table)
+        if not result:
+            raise ValueError(f"No tables found matching pattern {repr(match.pattern)}")
+        return result
+
+    def _href_getter(self, obj) -> str | None:
+        a = obj.find("a", href=True)
+        return None if not a else a["href"]
+
+    def _text_getter(self, obj):
+        return obj.text
+
+    def _equals_tag(self, obj, tag) -> bool:
+        return obj.name == tag
+
+    def _parse_td(self, row):
+        return row.find_all(("td", "th"), recursive=False)
+
+    def _parse_thead_tr(self, table):
+        return table.select("thead tr")
+
+    def _parse_tbody_tr(self, table):
+        from_tbody = table.select("tbody tr")
+        from_root = table.find_all("tr", recursive=False)
+        # HTML spec: at most one of these lists has content
+        return from_tbody + from_root
+
+    def _parse_tfoot_tr(self, table):
+        return table.select("tfoot tr")
+
+    def _setup_build_doc(self):
+        raw_text = _read(self.io, self.encoding, self.storage_options)
+        if not raw_text:
+            raise ValueError(f"No text parsed from document: {self.io}")
+        return raw_text
+
+    def _build_doc(self):
+        from bs4 import BeautifulSoup
+
+        bdoc = self._setup_build_doc()
+        if isinstance(bdoc, bytes) and self.encoding is not None:
+            udoc = bdoc.decode(self.encoding)
+            from_encoding = None
+        else:
+            udoc = bdoc
+            from_encoding = self.encoding
+
+        soup = BeautifulSoup(udoc, features="html5lib", from_encoding=from_encoding)
+
+        for br in soup.find_all("br"):
+            br.replace_with("\n" + br.text)
+
+        return soup
+
+
+def _build_xpath_expr(attrs) -> str:
+    """
+    Build an xpath expression to simulate bs4's ability to pass in kwargs to
+    search for attributes when using the lxml parser.
+
+    Parameters
+    ----------
+    attrs : dict
+        A dict of HTML attributes. These are NOT checked for validity.
+
+    Returns
+    -------
+    expr : unicode
+        An XPath expression that checks for the given HTML attributes.
+    """
+    # give class attribute as class_ because class is a python keyword
+    if "class_" in attrs:
+        attrs["class"] = attrs.pop("class_")
+
+    s = " and ".join([f"@{k}={repr(v)}" for k, v in attrs.items()])
+    return f"[{s}]"
+
+
+_re_namespace = {"re": "http://exslt.org/regular-expressions"}
+
+
+class _LxmlFrameParser(_HtmlFrameParser):
+    """
+    HTML to DataFrame parser that uses lxml under the hood.
+
+    Warning
+    -------
+    This parser can only handle HTTP, FTP, and FILE urls.
+
+    See Also
+    --------
+    _HtmlFrameParser
+    _BeautifulSoupLxmlFrameParser
+
+    Notes
+    -----
+    Documentation strings for this class are in the base class
+    :class:`_HtmlFrameParser`.
+    """
+
+    def _href_getter(self, obj) -> str | None:
+        href = obj.xpath(".//a/@href")
+        return None if not href else href[0]
+
+    def _text_getter(self, obj):
+        return obj.text_content()
+
+    def _parse_td(self, row):
+        # Look for direct children only: the "row" element here may be a
+        # 
foobar
-only rows
+        if header is None:
+            if len(head) == 1:
+                header = 0
+            else:
+                # ignore all-empty-text rows
+                header = [i for i, row in enumerate(head) if any(text for text in row)]
+
+    if foot:
+        body += foot
+
+    # fill out elements of body that are "ragged"
+    _expand_elements(body)
+    with TextParser(body, header=header, **kwargs) as tp:
+        return tp.read()
+
+
+_valid_parsers = {
+    "lxml": _LxmlFrameParser,
+    None: _LxmlFrameParser,
+    "html5lib": _BeautifulSoupHtml5LibFrameParser,
+    "bs4": _BeautifulSoupHtml5LibFrameParser,
+}
+
+
+def _parser_dispatch(flavor: HTMLFlavors | None) -> type[_HtmlFrameParser]:
+    """
+    Choose the parser based on the input flavor.
+
+    Parameters
+    ----------
+    flavor : {{"lxml", "html5lib", "bs4"}} or None
+        The type of parser to use. This must be a valid backend.
+
+    Returns
+    -------
+    cls : _HtmlFrameParser subclass
+        The parser class based on the requested input flavor.
+
+    Raises
+    ------
+    ValueError
+        * If `flavor` is not a valid backend.
+    ImportError
+        * If you do not have the requested `flavor`
+    """
+    valid_parsers = list(_valid_parsers.keys())
+    if flavor not in valid_parsers:
+        raise ValueError(
+            f"{repr(flavor)} is not a valid flavor, valid flavors are {valid_parsers}"
+        )
+
+    if flavor in ("bs4", "html5lib"):
+        import_optional_dependency("html5lib")
+        import_optional_dependency("bs4")
+    else:
+        import_optional_dependency("lxml.etree")
+    return _valid_parsers[flavor]
+
+
+def _print_as_set(s) -> str:
+    arg = ", ".join([pprint_thing(el) for el in s])
+    return f"{{{arg}}}"
+
+
+def _validate_flavor(flavor):
+    if flavor is None:
+        flavor = "lxml", "bs4"
+    elif isinstance(flavor, str):
+        flavor = (flavor,)
+    elif isinstance(flavor, abc.Iterable):
+        if not all(isinstance(flav, str) for flav in flavor):
+            raise TypeError(
+                f"Object of type {repr(type(flavor).__name__)} "
+                f"is not an iterable of strings"
+            )
+    else:
+        msg = repr(flavor) if isinstance(flavor, str) else str(flavor)
+        msg += " is not a valid flavor"
+        raise ValueError(msg)
+
+    flavor = tuple(flavor)
+    valid_flavors = set(_valid_parsers)
+    flavor_set = set(flavor)
+
+    if not flavor_set & valid_flavors:
+        raise ValueError(
+            f"{_print_as_set(flavor_set)} is not a valid set of flavors, valid "
+            f"flavors are {_print_as_set(valid_flavors)}"
+        )
+    return flavor
+
+
+def _parse(
+    flavor,
+    io,
+    match,
+    attrs,
+    encoding,
+    displayed_only,
+    extract_links,
+    storage_options,
+    **kwargs,
+):
+    flavor = _validate_flavor(flavor)
+    compiled_match = re.compile(match)  # you can pass a compiled regex here
+
+    retained = None
+    for flav in flavor:
+        parser = _parser_dispatch(flav)
+        p = parser(
+            io,
+            compiled_match,
+            attrs,
+            encoding,
+            displayed_only,
+            extract_links,
+            storage_options,
+        )
+
+        try:
+            tables = p.parse_tables()
+        except ValueError as caught:
+            # if `io` is an io-like object, check if it's seekable
+            # and try to rewind it before trying the next parser
+            if hasattr(io, "seekable") and io.seekable():
+                io.seek(0)
+            elif hasattr(io, "seekable") and not io.seekable():
+                # if we couldn't rewind it, let the user know
+                raise ValueError(
+                    f"The flavor {flav} failed to parse your input. "
+                    "Since you passed a non-rewindable file "
+                    "object, we can't rewind it to try "
+                    "another parser. Try read_html() with a different flavor."
+                ) from caught
+
+            retained = caught
+        else:
+            break
+    else:
+        assert retained is not None  # for mypy
+        raise retained
+
+    ret = []
+    for table in tables:
+        try:
+            df = _data_to_frame(data=table, **kwargs)
+            # Cast MultiIndex header to an Index of tuples when extracting header
+            # links and replace nan with None (therefore can't use mi.to_flat_index()).
+            # This maintains consistency of selection (e.g. df.columns.str[1])
+            if extract_links in ("all", "header") and isinstance(
+                df.columns, MultiIndex
+            ):
+                df.columns = Index(
+                    ((col[0], None if isna(col[1]) else col[1]) for col in df.columns),
+                    tupleize_cols=False,
+                )
+
+            ret.append(df)
+        except EmptyDataError:  # empty table
+            continue
+    return ret
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def read_html(
+    io: FilePath | ReadBuffer[str],
+    *,
+    match: str | Pattern = ".+",
+    flavor: HTMLFlavors | Sequence[HTMLFlavors] | None = None,
+    header: int | Sequence[int] | None = None,
+    index_col: int | Sequence[int] | None = None,
+    skiprows: int | Sequence[int] | slice | None = None,
+    attrs: dict[str, str] | None = None,
+    parse_dates: bool = False,
+    thousands: str | None = ",",
+    encoding: str | None = None,
+    decimal: str = ".",
+    converters: dict | None = None,
+    na_values: Iterable[object] | None = None,
+    keep_default_na: bool = True,
+    displayed_only: bool = True,
+    extract_links: Literal[None, "header", "footer", "body", "all"] = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    storage_options: StorageOptions = None,
+) -> list[DataFrame]:
+    r"""
+    Read HTML tables into a ``list`` of ``DataFrame`` objects.
+
+    Parameters
+    ----------
+    io : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a string ``read()`` function.
+        The string can represent a URL or the HTML itself. Note that
+        lxml only accepts the http, ftp and file url protocols. If you have a
+        URL that starts with ``'https'`` you might try removing the ``'s'``.
+
+        .. deprecated:: 2.1.0
+            Passing html literal strings is deprecated.
+            Wrap literal string/bytes input in ``io.StringIO``/``io.BytesIO`` instead.
+
+    match : str or compiled regular expression, optional
+        The set of tables containing text matching this regex or string will be
+        returned. Unless the HTML is extremely simple you will probably need to
+        pass a non-empty string here. Defaults to '.+' (match any non-empty
+        string). The default value will return all tables contained on a page.
+        This value is converted to a regular expression so that there is
+        consistent behavior between Beautiful Soup and lxml.
+
+    flavor : {{"lxml", "html5lib", "bs4"}} or list-like, optional
+        The parsing engine (or list of parsing engines) to use. 'bs4' and
+        'html5lib' are synonymous with each other, they are both there for
+        backwards compatibility. The default of ``None`` tries to use ``lxml``
+        to parse and if that fails it falls back on ``bs4`` + ``html5lib``.
+
+    header : int or list-like, optional
+        The row (or list of rows for a :class:`~pandas.MultiIndex`) to use to
+        make the columns headers.
+
+    index_col : int or list-like, optional
+        The column (or list of columns) to use to create the index.
+
+    skiprows : int, list-like or slice, optional
+        Number of rows to skip after parsing the column integer. 0-based. If a
+        sequence of integers or a slice is given, will skip the rows indexed by
+        that sequence.  Note that a single element sequence means 'skip the nth
+        row' whereas an integer means 'skip n rows'.
+
+    attrs : dict, optional
+        This is a dictionary of attributes that you can pass to use to identify
+        the table in the HTML. These are not checked for validity before being
+        passed to lxml or Beautiful Soup. However, these attributes must be
+        valid HTML table attributes to work correctly. For example, ::
+
+            attrs = {{'id': 'table'}}
+
+        is a valid attribute dictionary because the 'id' HTML tag attribute is
+        a valid HTML attribute for *any* HTML tag as per `this document
+        `__. ::
+
+            attrs = {{'asdf': 'table'}}
+
+        is *not* a valid attribute dictionary because 'asdf' is not a valid
+        HTML attribute even if it is a valid XML attribute.  Valid HTML 4.01
+        table attributes can be found `here
+        `__. A
+        working draft of the HTML 5 spec can be found `here
+        `__. It contains the
+        latest information on table attributes for the modern web.
+
+    parse_dates : bool, optional
+        See :func:`~read_csv` for more details.
+
+    thousands : str, optional
+        Separator to use to parse thousands. Defaults to ``','``.
+
+    encoding : str, optional
+        The encoding used to decode the web page. Defaults to ``None``.``None``
+        preserves the previous encoding behavior, which depends on the
+        underlying parser library (e.g., the parser library will try to use
+        the encoding provided by the document).
+
+    decimal : str, default '.'
+        Character to recognize as decimal point (e.g. use ',' for European
+        data).
+
+    converters : dict, default None
+        Dict of functions for converting values in certain columns. Keys can
+        either be integers or column labels, values are functions that take one
+        input argument, the cell (not column) content, and return the
+        transformed content.
+
+    na_values : iterable, default None
+        Custom NA values.
+
+    keep_default_na : bool, default True
+        If na_values are specified and keep_default_na is False the default NaN
+        values are overridden, otherwise they're appended to.
+
+    displayed_only : bool, default True
+        Whether elements with "display: none" should be parsed.
+
+    extract_links : {{None, "all", "header", "body", "footer"}}
+        Table elements in the specified section(s) with  tags will have their
+        href extracted.
+
+        .. versionadded:: 1.5.0
+
+    dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    {storage_options}
+
+        .. versionadded:: 2.1.0
+
+    Returns
+    -------
+    dfs
+        A list of DataFrames.
+
+    See Also
+    --------
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
+
+    Notes
+    -----
+    Before using this function you should read the :ref:`gotchas about the
+    HTML parsing libraries `.
+
+    Expect to do some cleanup after you call this function. For example, you
+    might need to manually assign column names if the column names are
+    converted to NaN when you pass the `header=0` argument. We try to assume as
+    little as possible about the structure of the table and push the
+    idiosyncrasies of the HTML contained in the table to the user.
+
+    This function searches for ```` elements and only for ````
+    and ```` or ```` argument, it is used to construct
+    the header, otherwise the function attempts to find the header within
+    the body (by putting rows with only ``
`` rows and ```` elements within each ``
``
+    element in the table. ```` stands for "table data". This function
+    attempts to properly handle ``colspan`` and ``rowspan`` attributes.
+    If the function has a ``
`` elements into the header).
+
+    Similar to :func:`~read_csv` the `header` argument is applied
+    **after** `skiprows` is applied.
+
+    This function will *always* return a list of :class:`DataFrame` *or*
+    it will fail, e.g., it will *not* return an empty list.
+
+    Examples
+    --------
+    See the :ref:`read_html documentation in the IO section of the docs
+    ` for some examples of reading in HTML tables.
+    """
+    # Type check here. We don't want to parse only to fail because of an
+    # invalid value of an integer skiprows.
+    if isinstance(skiprows, numbers.Integral) and skiprows < 0:
+        raise ValueError(
+            "cannot skip rows starting from the end of the "
+            "data (you passed a negative value)"
+        )
+    if extract_links not in [None, "header", "footer", "body", "all"]:
+        raise ValueError(
+            "`extract_links` must be one of "
+            '{None, "header", "footer", "body", "all"}, got '
+            f'"{extract_links}"'
+        )
+
+    validate_header_arg(header)
+    check_dtype_backend(dtype_backend)
+
+    io = stringify_path(io)
+
+    if isinstance(io, str) and not any(
+        [
+            is_file_like(io),
+            file_exists(io),
+            is_url(io),
+            is_fsspec_url(io),
+        ]
+    ):
+        warnings.warn(
+            "Passing literal html to 'read_html' is deprecated and "
+            "will be removed in a future version. To read from a "
+            "literal string, wrap it in a 'StringIO' object.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    return _parse(
+        flavor=flavor,
+        io=io,
+        match=match,
+        header=header,
+        index_col=index_col,
+        skiprows=skiprows,
+        parse_dates=parse_dates,
+        thousands=thousands,
+        attrs=attrs,
+        encoding=encoding,
+        decimal=decimal,
+        converters=converters,
+        na_values=na_values,
+        keep_default_na=keep_default_na,
+        displayed_only=displayed_only,
+        extract_links=extract_links,
+        dtype_backend=dtype_backend,
+        storage_options=storage_options,
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/json/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/json/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..8f4e7a62834b57c151189cdd2994a55d1ad9f7de
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/json/__init__.py
@@ -0,0 +1,15 @@
+from pandas.io.json._json import (
+    read_json,
+    to_json,
+    ujson_dumps,
+    ujson_loads,
+)
+from pandas.io.json._table_schema import build_table_schema
+
+__all__ = [
+    "ujson_dumps",
+    "ujson_loads",
+    "read_json",
+    "to_json",
+    "build_table_schema",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/json/_json.py b/.venv/lib/python3.13/site-packages/pandas/io/json/_json.py
new file mode 100644
index 0000000000000000000000000000000000000000..c0499ce750cf01e7c50a2a117652bae273c5251d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/json/_json.py
@@ -0,0 +1,1494 @@
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from collections import abc
+from io import StringIO
+from itertools import islice
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Generic,
+    Literal,
+    TypeVar,
+    final,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.json import (
+    ujson_dumps,
+    ujson_loads,
+)
+from pandas._libs.tslibs import iNaT
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import (
+    ensure_str,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import PeriodDtype
+
+from pandas import (
+    DataFrame,
+    Index,
+    MultiIndex,
+    Series,
+    isna,
+    notna,
+    to_datetime,
+)
+from pandas.core.reshape.concat import concat
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io._util import arrow_table_to_pandas
+from pandas.io.common import (
+    IOHandles,
+    dedup_names,
+    extension_to_compression,
+    file_exists,
+    get_handle,
+    is_fsspec_url,
+    is_potential_multi_index,
+    is_url,
+    stringify_path,
+)
+from pandas.io.json._normalize import convert_to_line_delimits
+from pandas.io.json._table_schema import (
+    build_table_schema,
+    parse_table_schema,
+)
+from pandas.io.parsers.readers import validate_integer
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Mapping,
+    )
+    from types import TracebackType
+
+    from pandas._typing import (
+        CompressionOptions,
+        DtypeArg,
+        DtypeBackend,
+        FilePath,
+        IndexLabel,
+        JSONEngine,
+        JSONSerializable,
+        ReadBuffer,
+        Self,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+    from pandas.core.generic import NDFrame
+
+FrameSeriesStrT = TypeVar("FrameSeriesStrT", bound=Literal["frame", "series"])
+
+
+# interface to/from
+@overload
+def to_json(
+    path_or_buf: FilePath | WriteBuffer[str] | WriteBuffer[bytes],
+    obj: NDFrame,
+    orient: str | None = ...,
+    date_format: str = ...,
+    double_precision: int = ...,
+    force_ascii: bool = ...,
+    date_unit: str = ...,
+    default_handler: Callable[[Any], JSONSerializable] | None = ...,
+    lines: bool = ...,
+    compression: CompressionOptions = ...,
+    index: bool | None = ...,
+    indent: int = ...,
+    storage_options: StorageOptions = ...,
+    mode: Literal["a", "w"] = ...,
+) -> None:
+    ...
+
+
+@overload
+def to_json(
+    path_or_buf: None,
+    obj: NDFrame,
+    orient: str | None = ...,
+    date_format: str = ...,
+    double_precision: int = ...,
+    force_ascii: bool = ...,
+    date_unit: str = ...,
+    default_handler: Callable[[Any], JSONSerializable] | None = ...,
+    lines: bool = ...,
+    compression: CompressionOptions = ...,
+    index: bool | None = ...,
+    indent: int = ...,
+    storage_options: StorageOptions = ...,
+    mode: Literal["a", "w"] = ...,
+) -> str:
+    ...
+
+
+def to_json(
+    path_or_buf: FilePath | WriteBuffer[str] | WriteBuffer[bytes] | None,
+    obj: NDFrame,
+    orient: str | None = None,
+    date_format: str = "epoch",
+    double_precision: int = 10,
+    force_ascii: bool = True,
+    date_unit: str = "ms",
+    default_handler: Callable[[Any], JSONSerializable] | None = None,
+    lines: bool = False,
+    compression: CompressionOptions = "infer",
+    index: bool | None = None,
+    indent: int = 0,
+    storage_options: StorageOptions | None = None,
+    mode: Literal["a", "w"] = "w",
+) -> str | None:
+    if orient in ["records", "values"] and index is True:
+        raise ValueError(
+            "'index=True' is only valid when 'orient' is 'split', 'table', "
+            "'index', or 'columns'."
+        )
+    elif orient in ["index", "columns"] and index is False:
+        raise ValueError(
+            "'index=False' is only valid when 'orient' is 'split', 'table', "
+            "'records', or 'values'."
+        )
+    elif index is None:
+        # will be ignored for orient='records' and 'values'
+        index = True
+
+    if lines and orient != "records":
+        raise ValueError("'lines' keyword only valid when 'orient' is records")
+
+    if mode not in ["a", "w"]:
+        msg = (
+            f"mode={mode} is not a valid option."
+            "Only 'w' and 'a' are currently supported."
+        )
+        raise ValueError(msg)
+
+    if mode == "a" and (not lines or orient != "records"):
+        msg = (
+            "mode='a' (append) is only supported when "
+            "lines is True and orient is 'records'"
+        )
+        raise ValueError(msg)
+
+    if orient == "table" and isinstance(obj, Series):
+        obj = obj.to_frame(name=obj.name or "values")
+
+    writer: type[Writer]
+    if orient == "table" and isinstance(obj, DataFrame):
+        writer = JSONTableWriter
+    elif isinstance(obj, Series):
+        writer = SeriesWriter
+    elif isinstance(obj, DataFrame):
+        writer = FrameWriter
+    else:
+        raise NotImplementedError("'obj' should be a Series or a DataFrame")
+
+    s = writer(
+        obj,
+        orient=orient,
+        date_format=date_format,
+        double_precision=double_precision,
+        ensure_ascii=force_ascii,
+        date_unit=date_unit,
+        default_handler=default_handler,
+        index=index,
+        indent=indent,
+    ).write()
+
+    if lines:
+        s = convert_to_line_delimits(s)
+
+    if path_or_buf is not None:
+        # apply compression and byte/text conversion
+        with get_handle(
+            path_or_buf, mode, compression=compression, storage_options=storage_options
+        ) as handles:
+            handles.handle.write(s)
+    else:
+        return s
+    return None
+
+
+class Writer(ABC):
+    _default_orient: str
+
+    def __init__(
+        self,
+        obj: NDFrame,
+        orient: str | None,
+        date_format: str,
+        double_precision: int,
+        ensure_ascii: bool,
+        date_unit: str,
+        index: bool,
+        default_handler: Callable[[Any], JSONSerializable] | None = None,
+        indent: int = 0,
+    ) -> None:
+        self.obj = obj
+
+        if orient is None:
+            orient = self._default_orient
+
+        self.orient = orient
+        self.date_format = date_format
+        self.double_precision = double_precision
+        self.ensure_ascii = ensure_ascii
+        self.date_unit = date_unit
+        self.default_handler = default_handler
+        self.index = index
+        self.indent = indent
+
+        self.is_copy = None
+        self._format_axes()
+
+    def _format_axes(self) -> None:
+        raise AbstractMethodError(self)
+
+    def write(self) -> str:
+        iso_dates = self.date_format == "iso"
+        return ujson_dumps(
+            self.obj_to_write,
+            orient=self.orient,
+            double_precision=self.double_precision,
+            ensure_ascii=self.ensure_ascii,
+            date_unit=self.date_unit,
+            iso_dates=iso_dates,
+            default_handler=self.default_handler,
+            indent=self.indent,
+        )
+
+    @property
+    @abstractmethod
+    def obj_to_write(self) -> NDFrame | Mapping[IndexLabel, Any]:
+        """Object to write in JSON format."""
+
+
+class SeriesWriter(Writer):
+    _default_orient = "index"
+
+    @property
+    def obj_to_write(self) -> NDFrame | Mapping[IndexLabel, Any]:
+        if not self.index and self.orient == "split":
+            return {"name": self.obj.name, "data": self.obj.values}
+        else:
+            return self.obj
+
+    def _format_axes(self) -> None:
+        if not self.obj.index.is_unique and self.orient == "index":
+            raise ValueError(f"Series index must be unique for orient='{self.orient}'")
+
+
+class FrameWriter(Writer):
+    _default_orient = "columns"
+
+    @property
+    def obj_to_write(self) -> NDFrame | Mapping[IndexLabel, Any]:
+        if not self.index and self.orient == "split":
+            obj_to_write = self.obj.to_dict(orient="split")
+            del obj_to_write["index"]
+        else:
+            obj_to_write = self.obj
+        return obj_to_write
+
+    def _format_axes(self) -> None:
+        """
+        Try to format axes if they are datelike.
+        """
+        if not self.obj.index.is_unique and self.orient in ("index", "columns"):
+            raise ValueError(
+                f"DataFrame index must be unique for orient='{self.orient}'."
+            )
+        if not self.obj.columns.is_unique and self.orient in (
+            "index",
+            "columns",
+            "records",
+        ):
+            raise ValueError(
+                f"DataFrame columns must be unique for orient='{self.orient}'."
+            )
+
+
+class JSONTableWriter(FrameWriter):
+    _default_orient = "records"
+
+    def __init__(
+        self,
+        obj,
+        orient: str | None,
+        date_format: str,
+        double_precision: int,
+        ensure_ascii: bool,
+        date_unit: str,
+        index: bool,
+        default_handler: Callable[[Any], JSONSerializable] | None = None,
+        indent: int = 0,
+    ) -> None:
+        """
+        Adds a `schema` attribute with the Table Schema, resets
+        the index (can't do in caller, because the schema inference needs
+        to know what the index is, forces orient to records, and forces
+        date_format to 'iso'.
+        """
+        super().__init__(
+            obj,
+            orient,
+            date_format,
+            double_precision,
+            ensure_ascii,
+            date_unit,
+            index,
+            default_handler=default_handler,
+            indent=indent,
+        )
+
+        if date_format != "iso":
+            msg = (
+                "Trying to write with `orient='table'` and "
+                f"`date_format='{date_format}'`. Table Schema requires dates "
+                "to be formatted with `date_format='iso'`"
+            )
+            raise ValueError(msg)
+
+        self.schema = build_table_schema(obj, index=self.index)
+
+        # NotImplemented on a column MultiIndex
+        if obj.ndim == 2 and isinstance(obj.columns, MultiIndex):
+            raise NotImplementedError(
+                "orient='table' is not supported for MultiIndex columns"
+            )
+
+        # TODO: Do this timedelta properly in objToJSON.c See GH #15137
+        if (
+            (obj.ndim == 1)
+            and (obj.name in set(obj.index.names))
+            or len(obj.columns.intersection(obj.index.names))
+        ):
+            msg = "Overlapping names between the index and columns"
+            raise ValueError(msg)
+
+        obj = obj.copy()
+        timedeltas = obj.select_dtypes(include=["timedelta"]).columns
+        if len(timedeltas):
+            obj[timedeltas] = obj[timedeltas].map(lambda x: x.isoformat())
+        # Convert PeriodIndex to datetimes before serializing
+        if isinstance(obj.index.dtype, PeriodDtype):
+            obj.index = obj.index.to_timestamp()
+
+        # exclude index from obj if index=False
+        if not self.index:
+            self.obj = obj.reset_index(drop=True)
+        else:
+            self.obj = obj.reset_index(drop=False)
+        self.date_format = "iso"
+        self.orient = "records"
+        self.index = index
+
+    @property
+    def obj_to_write(self) -> NDFrame | Mapping[IndexLabel, Any]:
+        return {"schema": self.schema, "data": self.obj}
+
+
+@overload
+def read_json(
+    path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+    *,
+    orient: str | None = ...,
+    typ: Literal["frame"] = ...,
+    dtype: DtypeArg | None = ...,
+    convert_axes: bool | None = ...,
+    convert_dates: bool | list[str] = ...,
+    keep_default_dates: bool = ...,
+    precise_float: bool = ...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    lines: bool = ...,
+    chunksize: int,
+    compression: CompressionOptions = ...,
+    nrows: int | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    engine: JSONEngine = ...,
+) -> JsonReader[Literal["frame"]]:
+    ...
+
+
+@overload
+def read_json(
+    path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+    *,
+    orient: str | None = ...,
+    typ: Literal["series"],
+    dtype: DtypeArg | None = ...,
+    convert_axes: bool | None = ...,
+    convert_dates: bool | list[str] = ...,
+    keep_default_dates: bool = ...,
+    precise_float: bool = ...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    lines: bool = ...,
+    chunksize: int,
+    compression: CompressionOptions = ...,
+    nrows: int | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    engine: JSONEngine = ...,
+) -> JsonReader[Literal["series"]]:
+    ...
+
+
+@overload
+def read_json(
+    path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+    *,
+    orient: str | None = ...,
+    typ: Literal["series"],
+    dtype: DtypeArg | None = ...,
+    convert_axes: bool | None = ...,
+    convert_dates: bool | list[str] = ...,
+    keep_default_dates: bool = ...,
+    precise_float: bool = ...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    lines: bool = ...,
+    chunksize: None = ...,
+    compression: CompressionOptions = ...,
+    nrows: int | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    engine: JSONEngine = ...,
+) -> Series:
+    ...
+
+
+@overload
+def read_json(
+    path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+    *,
+    orient: str | None = ...,
+    typ: Literal["frame"] = ...,
+    dtype: DtypeArg | None = ...,
+    convert_axes: bool | None = ...,
+    convert_dates: bool | list[str] = ...,
+    keep_default_dates: bool = ...,
+    precise_float: bool = ...,
+    date_unit: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    lines: bool = ...,
+    chunksize: None = ...,
+    compression: CompressionOptions = ...,
+    nrows: int | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    engine: JSONEngine = ...,
+) -> DataFrame:
+    ...
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    decompression_options=_shared_docs["decompression_options"] % "path_or_buf",
+)
+def read_json(
+    path_or_buf: FilePath | ReadBuffer[str] | ReadBuffer[bytes],
+    *,
+    orient: str | None = None,
+    typ: Literal["frame", "series"] = "frame",
+    dtype: DtypeArg | None = None,
+    convert_axes: bool | None = None,
+    convert_dates: bool | list[str] = True,
+    keep_default_dates: bool = True,
+    precise_float: bool = False,
+    date_unit: str | None = None,
+    encoding: str | None = None,
+    encoding_errors: str | None = "strict",
+    lines: bool = False,
+    chunksize: int | None = None,
+    compression: CompressionOptions = "infer",
+    nrows: int | None = None,
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    engine: JSONEngine = "ujson",
+) -> DataFrame | Series | JsonReader:
+    """
+    Convert a JSON string to pandas object.
+
+    Parameters
+    ----------
+    path_or_buf : a valid JSON str, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.json``.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        By file-like object, we refer to objects with a ``read()`` method,
+        such as a file handle (e.g. via builtin ``open`` function)
+        or ``StringIO``.
+
+        .. deprecated:: 2.1.0
+            Passing json literal strings is deprecated.
+
+    orient : str, optional
+        Indication of expected JSON string format.
+        Compatible JSON strings can be produced by ``to_json()`` with a
+        corresponding orient value.
+        The set of possible orients is:
+
+        - ``'split'`` : dict like
+          ``{{index -> [index], columns -> [columns], data -> [values]}}``
+        - ``'records'`` : list like
+          ``[{{column -> value}}, ... , {{column -> value}}]``
+        - ``'index'`` : dict like ``{{index -> {{column -> value}}}}``
+        - ``'columns'`` : dict like ``{{column -> {{index -> value}}}}``
+        - ``'values'`` : just the values array
+        - ``'table'`` : dict like ``{{'schema': {{schema}}, 'data': {{data}}}}``
+
+        The allowed and default values depend on the value
+        of the `typ` parameter.
+
+        * when ``typ == 'series'``,
+
+          - allowed orients are ``{{'split','records','index'}}``
+          - default is ``'index'``
+          - The Series index must be unique for orient ``'index'``.
+
+        * when ``typ == 'frame'``,
+
+          - allowed orients are ``{{'split','records','index',
+            'columns','values', 'table'}}``
+          - default is ``'columns'``
+          - The DataFrame index must be unique for orients ``'index'`` and
+            ``'columns'``.
+          - The DataFrame columns must be unique for orients ``'index'``,
+            ``'columns'``, and ``'records'``.
+
+    typ : {{'frame', 'series'}}, default 'frame'
+        The type of object to recover.
+
+    dtype : bool or dict, default None
+        If True, infer dtypes; if a dict of column to dtype, then use those;
+        if False, then don't infer dtypes at all, applies only to the data.
+
+        For all ``orient`` values except ``'table'``, default is True.
+
+    convert_axes : bool, default None
+        Try to convert the axes to the proper dtypes.
+
+        For all ``orient`` values except ``'table'``, default is True.
+
+    convert_dates : bool or list of str, default True
+        If True then default datelike columns may be converted (depending on
+        keep_default_dates).
+        If False, no dates will be converted.
+        If a list of column names, then those columns will be converted and
+        default datelike columns may also be converted (depending on
+        keep_default_dates).
+
+    keep_default_dates : bool, default True
+        If parsing dates (convert_dates is not False), then try to parse the
+        default datelike columns.
+        A column label is datelike if
+
+        * it ends with ``'_at'``,
+
+        * it ends with ``'_time'``,
+
+        * it begins with ``'timestamp'``,
+
+        * it is ``'modified'``, or
+
+        * it is ``'date'``.
+
+    precise_float : bool, default False
+        Set to enable usage of higher precision (strtod) function when
+        decoding string to double values. Default (False) is to use fast but
+        less precise builtin functionality.
+
+    date_unit : str, default None
+        The timestamp unit to detect if converting dates. The default behaviour
+        is to try and detect the correct precision, but if this is not desired
+        then pass one of 's', 'ms', 'us' or 'ns' to force parsing only seconds,
+        milliseconds, microseconds or nanoseconds respectively.
+
+    encoding : str, default is 'utf-8'
+        The encoding to use to decode py3 bytes.
+
+    encoding_errors : str, optional, default "strict"
+        How encoding errors are treated. `List of possible values
+        `_ .
+
+        .. versionadded:: 1.3.0
+
+    lines : bool, default False
+        Read the file as a json object per line.
+
+    chunksize : int, optional
+        Return JsonReader object for iteration.
+        See the `line-delimited json docs
+        `_
+        for more information on ``chunksize``.
+        This can only be passed if `lines=True`.
+        If this is None, the file will be read into memory all at once.
+    {decompression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    nrows : int, optional
+        The number of lines from the line-delimited jsonfile that has to be read.
+        This can only be passed if `lines=True`.
+        If this is None, all the rows will be returned.
+
+    {storage_options}
+
+    dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    engine : {{"ujson", "pyarrow"}}, default "ujson"
+        Parser engine to use. The ``"pyarrow"`` engine is only available when
+        ``lines=True``.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    Series, DataFrame, or pandas.api.typing.JsonReader
+        A JsonReader is returned when ``chunksize`` is not ``0`` or ``None``.
+        Otherwise, the type returned depends on the value of ``typ``.
+
+    See Also
+    --------
+    DataFrame.to_json : Convert a DataFrame to a JSON string.
+    Series.to_json : Convert a Series to a JSON string.
+    json_normalize : Normalize semi-structured JSON data into a flat table.
+
+    Notes
+    -----
+    Specific to ``orient='table'``, if a :class:`DataFrame` with a literal
+    :class:`Index` name of `index` gets written with :func:`to_json`, the
+    subsequent read operation will incorrectly set the :class:`Index` name to
+    ``None``. This is because `index` is also used by :func:`DataFrame.to_json`
+    to denote a missing :class:`Index` name, and the subsequent
+    :func:`read_json` operation cannot distinguish between the two. The same
+    limitation is encountered with a :class:`MultiIndex` and any names
+    beginning with ``'level_'``.
+
+    Examples
+    --------
+    >>> from io import StringIO
+    >>> df = pd.DataFrame([['a', 'b'], ['c', 'd']],
+    ...                   index=['row 1', 'row 2'],
+    ...                   columns=['col 1', 'col 2'])
+
+    Encoding/decoding a Dataframe using ``'split'`` formatted JSON:
+
+    >>> df.to_json(orient='split')
+        '\
+{{\
+"columns":["col 1","col 2"],\
+"index":["row 1","row 2"],\
+"data":[["a","b"],["c","d"]]\
+}}\
+'
+    >>> pd.read_json(StringIO(_), orient='split')
+          col 1 col 2
+    row 1     a     b
+    row 2     c     d
+
+    Encoding/decoding a Dataframe using ``'index'`` formatted JSON:
+
+    >>> df.to_json(orient='index')
+    '{{"row 1":{{"col 1":"a","col 2":"b"}},"row 2":{{"col 1":"c","col 2":"d"}}}}'
+
+    >>> pd.read_json(StringIO(_), orient='index')
+          col 1 col 2
+    row 1     a     b
+    row 2     c     d
+
+    Encoding/decoding a Dataframe using ``'records'`` formatted JSON.
+    Note that index labels are not preserved with this encoding.
+
+    >>> df.to_json(orient='records')
+    '[{{"col 1":"a","col 2":"b"}},{{"col 1":"c","col 2":"d"}}]'
+    >>> pd.read_json(StringIO(_), orient='records')
+      col 1 col 2
+    0     a     b
+    1     c     d
+
+    Encoding with Table Schema
+
+    >>> df.to_json(orient='table')
+        '\
+{{"schema":{{"fields":[\
+{{"name":"index","type":"string"}},\
+{{"name":"col 1","type":"string"}},\
+{{"name":"col 2","type":"string"}}],\
+"primaryKey":["index"],\
+"pandas_version":"1.4.0"}},\
+"data":[\
+{{"index":"row 1","col 1":"a","col 2":"b"}},\
+{{"index":"row 2","col 1":"c","col 2":"d"}}]\
+}}\
+'
+
+    The following example uses ``dtype_backend="numpy_nullable"``
+
+    >>> data = '''{{"index": {{"0": 0, "1": 1}},
+    ...        "a": {{"0": 1, "1": null}},
+    ...        "b": {{"0": 2.5, "1": 4.5}},
+    ...        "c": {{"0": true, "1": false}},
+    ...        "d": {{"0": "a", "1": "b"}},
+    ...        "e": {{"0": 1577.2, "1": 1577.1}}}}'''
+    >>> pd.read_json(StringIO(data), dtype_backend="numpy_nullable")
+       index     a    b      c  d       e
+    0      0     1  2.5   True  a  1577.2
+    1      1    4.5  False  b  1577.1
+    """
+    if orient == "table" and dtype:
+        raise ValueError("cannot pass both dtype and orient='table'")
+    if orient == "table" and convert_axes:
+        raise ValueError("cannot pass both convert_axes and orient='table'")
+
+    check_dtype_backend(dtype_backend)
+
+    if dtype is None and orient != "table":
+        # error: Incompatible types in assignment (expression has type "bool", variable
+        # has type "Union[ExtensionDtype, str, dtype[Any], Type[str], Type[float],
+        # Type[int], Type[complex], Type[bool], Type[object], Dict[Hashable,
+        # Union[ExtensionDtype, Union[str, dtype[Any]], Type[str], Type[float],
+        # Type[int], Type[complex], Type[bool], Type[object]]], None]")
+        dtype = True  # type: ignore[assignment]
+    if convert_axes is None and orient != "table":
+        convert_axes = True
+
+    json_reader = JsonReader(
+        path_or_buf,
+        orient=orient,
+        typ=typ,
+        dtype=dtype,
+        convert_axes=convert_axes,
+        convert_dates=convert_dates,
+        keep_default_dates=keep_default_dates,
+        precise_float=precise_float,
+        date_unit=date_unit,
+        encoding=encoding,
+        lines=lines,
+        chunksize=chunksize,
+        compression=compression,
+        nrows=nrows,
+        storage_options=storage_options,
+        encoding_errors=encoding_errors,
+        dtype_backend=dtype_backend,
+        engine=engine,
+    )
+
+    if chunksize:
+        return json_reader
+    else:
+        return json_reader.read()
+
+
+class JsonReader(abc.Iterator, Generic[FrameSeriesStrT]):
+    """
+    JsonReader provides an interface for reading in a JSON file.
+
+    If initialized with ``lines=True`` and ``chunksize``, can be iterated over
+    ``chunksize`` lines at a time. Otherwise, calling ``read`` reads in the
+    whole document.
+    """
+
+    def __init__(
+        self,
+        filepath_or_buffer,
+        orient,
+        typ: FrameSeriesStrT,
+        dtype,
+        convert_axes: bool | None,
+        convert_dates,
+        keep_default_dates: bool,
+        precise_float: bool,
+        date_unit,
+        encoding,
+        lines: bool,
+        chunksize: int | None,
+        compression: CompressionOptions,
+        nrows: int | None,
+        storage_options: StorageOptions | None = None,
+        encoding_errors: str | None = "strict",
+        dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+        engine: JSONEngine = "ujson",
+    ) -> None:
+        self.orient = orient
+        self.typ = typ
+        self.dtype = dtype
+        self.convert_axes = convert_axes
+        self.convert_dates = convert_dates
+        self.keep_default_dates = keep_default_dates
+        self.precise_float = precise_float
+        self.date_unit = date_unit
+        self.encoding = encoding
+        self.engine = engine
+        self.compression = compression
+        self.storage_options = storage_options
+        self.lines = lines
+        self.chunksize = chunksize
+        self.nrows_seen = 0
+        self.nrows = nrows
+        self.encoding_errors = encoding_errors
+        self.handles: IOHandles[str] | None = None
+        self.dtype_backend = dtype_backend
+
+        if self.engine not in {"pyarrow", "ujson"}:
+            raise ValueError(
+                f"The engine type {self.engine} is currently not supported."
+            )
+        if self.chunksize is not None:
+            self.chunksize = validate_integer("chunksize", self.chunksize, 1)
+            if not self.lines:
+                raise ValueError("chunksize can only be passed if lines=True")
+            if self.engine == "pyarrow":
+                raise ValueError(
+                    "currently pyarrow engine doesn't support chunksize parameter"
+                )
+        if self.nrows is not None:
+            self.nrows = validate_integer("nrows", self.nrows, 0)
+            if not self.lines:
+                raise ValueError("nrows can only be passed if lines=True")
+        if (
+            isinstance(filepath_or_buffer, str)
+            and not self.lines
+            and "\n" in filepath_or_buffer
+        ):
+            warnings.warn(
+                "Passing literal json to 'read_json' is deprecated and "
+                "will be removed in a future version. To read from a "
+                "literal string, wrap it in a 'StringIO' object.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        if self.engine == "pyarrow":
+            if not self.lines:
+                raise ValueError(
+                    "currently pyarrow engine only supports "
+                    "the line-delimited JSON format"
+                )
+            self.data = filepath_or_buffer
+        elif self.engine == "ujson":
+            data = self._get_data_from_filepath(filepath_or_buffer)
+            self.data = self._preprocess_data(data)
+
+    def _preprocess_data(self, data):
+        """
+        At this point, the data either has a `read` attribute (e.g. a file
+        object or a StringIO) or is a string that is a JSON document.
+
+        If self.chunksize, we prepare the data for the `__next__` method.
+        Otherwise, we read it into memory for the `read` method.
+        """
+        if hasattr(data, "read") and not (self.chunksize or self.nrows):
+            with self:
+                data = data.read()
+        if not hasattr(data, "read") and (self.chunksize or self.nrows):
+            data = StringIO(data)
+
+        return data
+
+    def _get_data_from_filepath(self, filepath_or_buffer):
+        """
+        The function read_json accepts three input types:
+            1. filepath (string-like)
+            2. file-like object (e.g. open file object, StringIO)
+            3. JSON string
+
+        This method turns (1) into (2) to simplify the rest of the processing.
+        It returns input types (2) and (3) unchanged.
+
+        It raises FileNotFoundError if the input is a string ending in
+        one of .json, .json.gz, .json.bz2, etc. but no such file exists.
+        """
+        # if it is a string but the file does not exist, it might be a JSON string
+        filepath_or_buffer = stringify_path(filepath_or_buffer)
+        if (
+            not isinstance(filepath_or_buffer, str)
+            or is_url(filepath_or_buffer)
+            or is_fsspec_url(filepath_or_buffer)
+            or file_exists(filepath_or_buffer)
+        ):
+            self.handles = get_handle(
+                filepath_or_buffer,
+                "r",
+                encoding=self.encoding,
+                compression=self.compression,
+                storage_options=self.storage_options,
+                errors=self.encoding_errors,
+            )
+            filepath_or_buffer = self.handles.handle
+        elif (
+            isinstance(filepath_or_buffer, str)
+            and filepath_or_buffer.lower().endswith(
+                (".json",) + tuple(f".json{c}" for c in extension_to_compression)
+            )
+            and not file_exists(filepath_or_buffer)
+        ):
+            raise FileNotFoundError(f"File {filepath_or_buffer} does not exist")
+        else:
+            warnings.warn(
+                "Passing literal json to 'read_json' is deprecated and "
+                "will be removed in a future version. To read from a "
+                "literal string, wrap it in a 'StringIO' object.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+        return filepath_or_buffer
+
+    def _combine_lines(self, lines) -> str:
+        """
+        Combines a list of JSON objects into one JSON object.
+        """
+        return (
+            f'[{",".join([line for line in (line.strip() for line in lines) if line])}]'
+        )
+
+    @overload
+    def read(self: JsonReader[Literal["frame"]]) -> DataFrame:
+        ...
+
+    @overload
+    def read(self: JsonReader[Literal["series"]]) -> Series:
+        ...
+
+    @overload
+    def read(self: JsonReader[Literal["frame", "series"]]) -> DataFrame | Series:
+        ...
+
+    def read(self) -> DataFrame | Series:
+        """
+        Read the whole JSON input into a pandas object.
+        """
+        obj: DataFrame | Series
+        with self:
+            if self.engine == "pyarrow":
+                pyarrow_json = import_optional_dependency("pyarrow.json")
+                pa_table = pyarrow_json.read_json(self.data)
+                return arrow_table_to_pandas(pa_table, dtype_backend=self.dtype_backend)
+            elif self.engine == "ujson":
+                if self.lines:
+                    if self.chunksize:
+                        obj = concat(self)
+                    elif self.nrows:
+                        lines = list(islice(self.data, self.nrows))
+                        lines_json = self._combine_lines(lines)
+                        obj = self._get_object_parser(lines_json)
+                    else:
+                        data = ensure_str(self.data)
+                        data_lines = data.split("\n")
+                        obj = self._get_object_parser(self._combine_lines(data_lines))
+                else:
+                    obj = self._get_object_parser(self.data)
+                if self.dtype_backend is not lib.no_default:
+                    return obj.convert_dtypes(
+                        infer_objects=False, dtype_backend=self.dtype_backend
+                    )
+                else:
+                    return obj
+
+    def _get_object_parser(self, json) -> DataFrame | Series:
+        """
+        Parses a json document into a pandas object.
+        """
+        typ = self.typ
+        dtype = self.dtype
+        kwargs = {
+            "orient": self.orient,
+            "dtype": self.dtype,
+            "convert_axes": self.convert_axes,
+            "convert_dates": self.convert_dates,
+            "keep_default_dates": self.keep_default_dates,
+            "precise_float": self.precise_float,
+            "date_unit": self.date_unit,
+            "dtype_backend": self.dtype_backend,
+        }
+        obj = None
+        if typ == "frame":
+            obj = FrameParser(json, **kwargs).parse()
+
+        if typ == "series" or obj is None:
+            if not isinstance(dtype, bool):
+                kwargs["dtype"] = dtype
+            obj = SeriesParser(json, **kwargs).parse()
+
+        return obj
+
+    def close(self) -> None:
+        """
+        If we opened a stream earlier, in _get_data_from_filepath, we should
+        close it.
+
+        If an open stream or file was passed, we leave it open.
+        """
+        if self.handles is not None:
+            self.handles.close()
+
+    def __iter__(self) -> Self:
+        return self
+
+    @overload
+    def __next__(self: JsonReader[Literal["frame"]]) -> DataFrame:
+        ...
+
+    @overload
+    def __next__(self: JsonReader[Literal["series"]]) -> Series:
+        ...
+
+    @overload
+    def __next__(self: JsonReader[Literal["frame", "series"]]) -> DataFrame | Series:
+        ...
+
+    def __next__(self) -> DataFrame | Series:
+        if self.nrows and self.nrows_seen >= self.nrows:
+            self.close()
+            raise StopIteration
+
+        lines = list(islice(self.data, self.chunksize))
+        if not lines:
+            self.close()
+            raise StopIteration
+
+        try:
+            lines_json = self._combine_lines(lines)
+            obj = self._get_object_parser(lines_json)
+
+            # Make sure that the returned objects have the right index.
+            obj.index = range(self.nrows_seen, self.nrows_seen + len(obj))
+            self.nrows_seen += len(obj)
+        except Exception as ex:
+            self.close()
+            raise ex
+
+        if self.dtype_backend is not lib.no_default:
+            return obj.convert_dtypes(
+                infer_objects=False, dtype_backend=self.dtype_backend
+            )
+        else:
+            return obj
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+class Parser:
+    _split_keys: tuple[str, ...]
+    _default_orient: str
+
+    _STAMP_UNITS = ("s", "ms", "us", "ns")
+    _MIN_STAMPS = {
+        "s": 31536000,
+        "ms": 31536000000,
+        "us": 31536000000000,
+        "ns": 31536000000000000,
+    }
+    json: str
+
+    def __init__(
+        self,
+        json: str,
+        orient,
+        dtype: DtypeArg | None = None,
+        convert_axes: bool = True,
+        convert_dates: bool | list[str] = True,
+        keep_default_dates: bool = False,
+        precise_float: bool = False,
+        date_unit=None,
+        dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    ) -> None:
+        self.json = json
+
+        if orient is None:
+            orient = self._default_orient
+
+        self.orient = orient
+
+        self.dtype = dtype
+
+        if date_unit is not None:
+            date_unit = date_unit.lower()
+            if date_unit not in self._STAMP_UNITS:
+                raise ValueError(f"date_unit must be one of {self._STAMP_UNITS}")
+            self.min_stamp = self._MIN_STAMPS[date_unit]
+        else:
+            self.min_stamp = self._MIN_STAMPS["s"]
+
+        self.precise_float = precise_float
+        self.convert_axes = convert_axes
+        self.convert_dates = convert_dates
+        self.date_unit = date_unit
+        self.keep_default_dates = keep_default_dates
+        self.obj: DataFrame | Series | None = None
+        self.dtype_backend = dtype_backend
+
+    @final
+    def check_keys_split(self, decoded: dict) -> None:
+        """
+        Checks that dict has only the appropriate keys for orient='split'.
+        """
+        bad_keys = set(decoded.keys()).difference(set(self._split_keys))
+        if bad_keys:
+            bad_keys_joined = ", ".join(bad_keys)
+            raise ValueError(f"JSON data had unexpected key(s): {bad_keys_joined}")
+
+    @final
+    def parse(self):
+        self._parse()
+
+        if self.obj is None:
+            return None
+        if self.convert_axes:
+            self._convert_axes()
+        self._try_convert_types()
+        return self.obj
+
+    def _parse(self) -> None:
+        raise AbstractMethodError(self)
+
+    @final
+    def _convert_axes(self) -> None:
+        """
+        Try to convert axes.
+        """
+        obj = self.obj
+        assert obj is not None  # for mypy
+        for axis_name in obj._AXIS_ORDERS:
+            ax = obj._get_axis(axis_name)
+            ser = Series(ax, dtype=ax.dtype, copy=False)
+            new_ser, result = self._try_convert_data(
+                name=axis_name,
+                data=ser,
+                use_dtypes=False,
+                convert_dates=True,
+                is_axis=True,
+            )
+            if result:
+                new_axis = Index(new_ser, dtype=new_ser.dtype, copy=False)
+                setattr(self.obj, axis_name, new_axis)
+
+    def _try_convert_types(self) -> None:
+        raise AbstractMethodError(self)
+
+    @final
+    def _try_convert_data(
+        self,
+        name: Hashable,
+        data: Series,
+        use_dtypes: bool = True,
+        convert_dates: bool | list[str] = True,
+        is_axis: bool = False,
+    ) -> tuple[Series, bool]:
+        """
+        Try to parse a Series into a column by inferring dtype.
+        """
+        # don't try to coerce, unless a force conversion
+        if use_dtypes:
+            if not self.dtype:
+                if all(notna(data)):
+                    return data, False
+
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore",
+                        "Downcasting object dtype arrays",
+                        category=FutureWarning,
+                    )
+                    filled = data.fillna(np.nan)
+
+                return filled, True
+
+            elif self.dtype is True:
+                pass
+            else:
+                # dtype to force
+                dtype = (
+                    self.dtype.get(name) if isinstance(self.dtype, dict) else self.dtype
+                )
+                if dtype is not None:
+                    try:
+                        return data.astype(dtype), True
+                    except (TypeError, ValueError):
+                        return data, False
+
+        if convert_dates:
+            new_data, result = self._try_convert_to_date(data)
+            if result:
+                return new_data, True
+
+        converted = False
+        if self.dtype_backend is not lib.no_default and not is_axis:
+            # Fall through for conversion later on
+            return data, True
+        elif is_string_dtype(data.dtype):
+            # try float
+            try:
+                data = data.astype("float64")
+                converted = True
+            except (TypeError, ValueError):
+                pass
+
+        if data.dtype.kind == "f" and data.dtype != "float64":
+            # coerce floats to 64
+            try:
+                data = data.astype("float64")
+                converted = True
+            except (TypeError, ValueError):
+                pass
+
+        # don't coerce 0-len data
+        if len(data) and data.dtype in ("float", "object"):
+            # coerce ints if we can
+            try:
+                new_data = data.astype("int64")
+                if (new_data == data).all():
+                    data = new_data
+                    converted = True
+            except (TypeError, ValueError, OverflowError):
+                pass
+
+        if data.dtype == "int" and data.dtype != "int64":
+            # coerce ints to 64
+            try:
+                data = data.astype("int64")
+                converted = True
+            except (TypeError, ValueError):
+                pass
+
+        # if we have an index, we want to preserve dtypes
+        if name == "index" and len(data):
+            if self.orient == "split":
+                return data, False
+
+        return data, converted
+
+    @final
+    def _try_convert_to_date(self, data: Series) -> tuple[Series, bool]:
+        """
+        Try to parse a ndarray like into a date column.
+
+        Try to coerce object in epoch/iso formats and integer/float in epoch
+        formats. Return a boolean if parsing was successful.
+        """
+        # no conversion on empty
+        if not len(data):
+            return data, False
+
+        new_data = data
+
+        if new_data.dtype == "string":
+            new_data = new_data.astype(object)
+
+        if new_data.dtype == "object":
+            try:
+                new_data = data.astype("int64")
+            except OverflowError:
+                return data, False
+            except (TypeError, ValueError):
+                pass
+
+        # ignore numbers that are out of range
+        if issubclass(new_data.dtype.type, np.number):
+            in_range = (
+                isna(new_data._values)
+                | (new_data > self.min_stamp)
+                | (new_data._values == iNaT)
+            )
+            if not in_range.all():
+                return data, False
+
+        date_units = (self.date_unit,) if self.date_unit else self._STAMP_UNITS
+        for date_unit in date_units:
+            try:
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore",
+                        ".*parsing datetimes with mixed time "
+                        "zones will raise an error",
+                        category=FutureWarning,
+                    )
+                    new_data = to_datetime(new_data, errors="raise", unit=date_unit)
+            except (ValueError, OverflowError, TypeError):
+                continue
+            return new_data, True
+        return data, False
+
+
+class SeriesParser(Parser):
+    _default_orient = "index"
+    _split_keys = ("name", "index", "data")
+    obj: Series | None
+
+    def _parse(self) -> None:
+        data = ujson_loads(self.json, precise_float=self.precise_float)
+
+        if self.orient == "split":
+            decoded = {str(k): v for k, v in data.items()}
+            self.check_keys_split(decoded)
+            self.obj = Series(**decoded)
+        else:
+            self.obj = Series(data)
+
+    def _try_convert_types(self) -> None:
+        if self.obj is None:
+            return
+        obj, result = self._try_convert_data(
+            "data", self.obj, convert_dates=self.convert_dates
+        )
+        if result:
+            self.obj = obj
+
+
+class FrameParser(Parser):
+    _default_orient = "columns"
+    _split_keys = ("columns", "index", "data")
+    obj: DataFrame | None
+
+    def _parse(self) -> None:
+        json = self.json
+        orient = self.orient
+
+        if orient == "columns":
+            self.obj = DataFrame(
+                ujson_loads(json, precise_float=self.precise_float), dtype=None
+            )
+        elif orient == "split":
+            decoded = {
+                str(k): v
+                for k, v in ujson_loads(json, precise_float=self.precise_float).items()
+            }
+            self.check_keys_split(decoded)
+            orig_names = [
+                (tuple(col) if isinstance(col, list) else col)
+                for col in decoded["columns"]
+            ]
+            decoded["columns"] = dedup_names(
+                orig_names,
+                is_potential_multi_index(orig_names, None),
+            )
+            self.obj = DataFrame(dtype=None, **decoded)
+        elif orient == "index":
+            self.obj = DataFrame.from_dict(
+                ujson_loads(json, precise_float=self.precise_float),
+                dtype=None,
+                orient="index",
+            )
+        elif orient == "table":
+            self.obj = parse_table_schema(json, precise_float=self.precise_float)
+        else:
+            self.obj = DataFrame(
+                ujson_loads(json, precise_float=self.precise_float), dtype=None
+            )
+
+    def _process_converter(
+        self,
+        f: Callable[[Hashable, Series], tuple[Series, bool]],
+        filt: Callable[[Hashable], bool] | None = None,
+    ) -> None:
+        """
+        Take a conversion function and possibly recreate the frame.
+        """
+        if filt is None:
+            filt = lambda col: True
+
+        obj = self.obj
+        assert obj is not None  # for mypy
+
+        needs_new_obj = False
+        new_obj = {}
+        for i, (col, c) in enumerate(obj.items()):
+            if filt(col):
+                new_data, result = f(col, c)
+                if result:
+                    c = new_data
+                    needs_new_obj = True
+            new_obj[i] = c
+
+        if needs_new_obj:
+            # possibly handle dup columns
+            new_frame = DataFrame(new_obj, index=obj.index)
+            new_frame.columns = obj.columns
+            self.obj = new_frame
+
+    def _try_convert_types(self) -> None:
+        if self.obj is None:
+            return
+        if self.convert_dates:
+            self._try_convert_dates()
+
+        self._process_converter(
+            lambda col, c: self._try_convert_data(col, c, convert_dates=False)
+        )
+
+    def _try_convert_dates(self) -> None:
+        if self.obj is None:
+            return
+
+        # our columns to parse
+        convert_dates_list_bool = self.convert_dates
+        if isinstance(convert_dates_list_bool, bool):
+            convert_dates_list_bool = []
+        convert_dates = set(convert_dates_list_bool)
+
+        def is_ok(col) -> bool:
+            """
+            Return if this col is ok to try for a date parse.
+            """
+            if col in convert_dates:
+                return True
+            if not self.keep_default_dates:
+                return False
+            if not isinstance(col, str):
+                return False
+
+            col_lower = col.lower()
+            if (
+                col_lower.endswith(("_at", "_time"))
+                or col_lower == "modified"
+                or col_lower == "date"
+                or col_lower == "datetime"
+                or col_lower.startswith("timestamp")
+            ):
+                return True
+            return False
+
+        self._process_converter(lambda col, c: self._try_convert_to_date(c), filt=is_ok)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/json/_normalize.py b/.venv/lib/python3.13/site-packages/pandas/io/json/_normalize.py
new file mode 100644
index 0000000000000000000000000000000000000000..b1e2210f9d8940a0931b07e1631350089140ff95
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/json/_normalize.py
@@ -0,0 +1,544 @@
+# ---------------------------------------------------------------------
+# JSON normalization routines
+from __future__ import annotations
+
+from collections import (
+    abc,
+    defaultdict,
+)
+import copy
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    DefaultDict,
+)
+
+import numpy as np
+
+from pandas._libs.writers import convert_json_to_lines
+
+import pandas as pd
+from pandas import DataFrame
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+    from pandas._typing import (
+        IgnoreRaise,
+        Scalar,
+    )
+
+
+def convert_to_line_delimits(s: str) -> str:
+    """
+    Helper function that converts JSON lists to line delimited JSON.
+    """
+    # Determine we have a JSON list to turn to lines otherwise just return the
+    # json object, only lists can
+    if not s[0] == "[" and s[-1] == "]":
+        return s
+    s = s[1:-1]
+
+    return convert_json_to_lines(s)
+
+
+def nested_to_record(
+    ds,
+    prefix: str = "",
+    sep: str = ".",
+    level: int = 0,
+    max_level: int | None = None,
+):
+    """
+    A simplified json_normalize
+
+    Converts a nested dict into a flat dict ("record"), unlike json_normalize,
+    it does not attempt to extract a subset of the data.
+
+    Parameters
+    ----------
+    ds : dict or list of dicts
+    prefix: the prefix, optional, default: ""
+    sep : str, default '.'
+        Nested records will generate names separated by sep,
+        e.g., for sep='.', { 'foo' : { 'bar' : 0 } } -> foo.bar
+    level: int, optional, default: 0
+        The number of levels in the json string.
+
+    max_level: int, optional, default: None
+        The max depth to normalize.
+
+    Returns
+    -------
+    d - dict or list of dicts, matching `ds`
+
+    Examples
+    --------
+    >>> nested_to_record(
+    ...     dict(flat1=1, dict1=dict(c=1, d=2), nested=dict(e=dict(c=1, d=2), d=2))
+    ... )
+    {\
+'flat1': 1, \
+'dict1.c': 1, \
+'dict1.d': 2, \
+'nested.e.c': 1, \
+'nested.e.d': 2, \
+'nested.d': 2\
+}
+    """
+    singleton = False
+    if isinstance(ds, dict):
+        ds = [ds]
+        singleton = True
+    new_ds = []
+    for d in ds:
+        new_d = copy.deepcopy(d)
+        for k, v in d.items():
+            # each key gets renamed with prefix
+            if not isinstance(k, str):
+                k = str(k)
+            if level == 0:
+                newkey = k
+            else:
+                newkey = prefix + sep + k
+
+            # flatten if type is dict and
+            # current dict level  < maximum level provided and
+            # only dicts gets recurse-flattened
+            # only at level>1 do we rename the rest of the keys
+            if not isinstance(v, dict) or (
+                max_level is not None and level >= max_level
+            ):
+                if level != 0:  # so we skip copying for top level, common case
+                    v = new_d.pop(k)
+                    new_d[newkey] = v
+                continue
+
+            v = new_d.pop(k)
+            new_d.update(nested_to_record(v, newkey, sep, level + 1, max_level))
+        new_ds.append(new_d)
+
+    if singleton:
+        return new_ds[0]
+    return new_ds
+
+
+def _normalise_json(
+    data: Any,
+    key_string: str,
+    normalized_dict: dict[str, Any],
+    separator: str,
+) -> dict[str, Any]:
+    """
+    Main recursive function
+    Designed for the most basic use case of pd.json_normalize(data)
+    intended as a performance improvement, see #15621
+
+    Parameters
+    ----------
+    data : Any
+        Type dependent on types contained within nested Json
+    key_string : str
+        New key (with separator(s) in) for data
+    normalized_dict : dict
+        The new normalized/flattened Json dict
+    separator : str, default '.'
+        Nested records will generate names separated by sep,
+        e.g., for sep='.', { 'foo' : { 'bar' : 0 } } -> foo.bar
+    """
+    if isinstance(data, dict):
+        for key, value in data.items():
+            new_key = f"{key_string}{separator}{key}"
+
+            if not key_string:
+                new_key = new_key.removeprefix(separator)
+
+            _normalise_json(
+                data=value,
+                key_string=new_key,
+                normalized_dict=normalized_dict,
+                separator=separator,
+            )
+    else:
+        normalized_dict[key_string] = data
+    return normalized_dict
+
+
+def _normalise_json_ordered(data: dict[str, Any], separator: str) -> dict[str, Any]:
+    """
+    Order the top level keys and then recursively go to depth
+
+    Parameters
+    ----------
+    data : dict or list of dicts
+    separator : str, default '.'
+        Nested records will generate names separated by sep,
+        e.g., for sep='.', { 'foo' : { 'bar' : 0 } } -> foo.bar
+
+    Returns
+    -------
+    dict or list of dicts, matching `normalised_json_object`
+    """
+    top_dict_ = {k: v for k, v in data.items() if not isinstance(v, dict)}
+    nested_dict_ = _normalise_json(
+        data={k: v for k, v in data.items() if isinstance(v, dict)},
+        key_string="",
+        normalized_dict={},
+        separator=separator,
+    )
+    return {**top_dict_, **nested_dict_}
+
+
+def _simple_json_normalize(
+    ds: dict | list[dict],
+    sep: str = ".",
+) -> dict | list[dict] | Any:
+    """
+    A optimized basic json_normalize
+
+    Converts a nested dict into a flat dict ("record"), unlike
+    json_normalize and nested_to_record it doesn't do anything clever.
+    But for the most basic use cases it enhances performance.
+    E.g. pd.json_normalize(data)
+
+    Parameters
+    ----------
+    ds : dict or list of dicts
+    sep : str, default '.'
+        Nested records will generate names separated by sep,
+        e.g., for sep='.', { 'foo' : { 'bar' : 0 } } -> foo.bar
+
+    Returns
+    -------
+    frame : DataFrame
+    d - dict or list of dicts, matching `normalised_json_object`
+
+    Examples
+    --------
+    >>> _simple_json_normalize(
+    ...     {
+    ...         "flat1": 1,
+    ...         "dict1": {"c": 1, "d": 2},
+    ...         "nested": {"e": {"c": 1, "d": 2}, "d": 2},
+    ...     }
+    ... )
+    {\
+'flat1': 1, \
+'dict1.c': 1, \
+'dict1.d': 2, \
+'nested.e.c': 1, \
+'nested.e.d': 2, \
+'nested.d': 2\
+}
+
+    """
+    normalised_json_object = {}
+    # expect a dictionary, as most jsons are. However, lists are perfectly valid
+    if isinstance(ds, dict):
+        normalised_json_object = _normalise_json_ordered(data=ds, separator=sep)
+    elif isinstance(ds, list):
+        normalised_json_list = [_simple_json_normalize(row, sep=sep) for row in ds]
+        return normalised_json_list
+    return normalised_json_object
+
+
+def json_normalize(
+    data: dict | list[dict],
+    record_path: str | list | None = None,
+    meta: str | list[str | list[str]] | None = None,
+    meta_prefix: str | None = None,
+    record_prefix: str | None = None,
+    errors: IgnoreRaise = "raise",
+    sep: str = ".",
+    max_level: int | None = None,
+) -> DataFrame:
+    """
+    Normalize semi-structured JSON data into a flat table.
+
+    Parameters
+    ----------
+    data : dict or list of dicts
+        Unserialized JSON objects.
+    record_path : str or list of str, default None
+        Path in each object to list of records. If not passed, data will be
+        assumed to be an array of records.
+    meta : list of paths (str or list of str), default None
+        Fields to use as metadata for each record in resulting table.
+    meta_prefix : str, default None
+        If True, prefix records with dotted (?) path, e.g. foo.bar.field if
+        meta is ['foo', 'bar'].
+    record_prefix : str, default None
+        If True, prefix records with dotted (?) path, e.g. foo.bar.field if
+        path to records is ['foo', 'bar'].
+    errors : {'raise', 'ignore'}, default 'raise'
+        Configures error handling.
+
+        * 'ignore' : will ignore KeyError if keys listed in meta are not
+          always present.
+        * 'raise' : will raise KeyError if keys listed in meta are not
+          always present.
+    sep : str, default '.'
+        Nested records will generate names separated by sep.
+        e.g., for sep='.', {'foo': {'bar': 0}} -> foo.bar.
+    max_level : int, default None
+        Max number of levels(depth of dict) to normalize.
+        if None, normalizes all levels.
+
+    Returns
+    -------
+    frame : DataFrame
+    Normalize semi-structured JSON data into a flat table.
+
+    Examples
+    --------
+    >>> data = [
+    ...     {"id": 1, "name": {"first": "Coleen", "last": "Volk"}},
+    ...     {"name": {"given": "Mark", "family": "Regner"}},
+    ...     {"id": 2, "name": "Faye Raker"},
+    ... ]
+    >>> pd.json_normalize(data)
+        id name.first name.last name.given name.family        name
+    0  1.0     Coleen      Volk        NaN         NaN         NaN
+    1  NaN        NaN       NaN       Mark      Regner         NaN
+    2  2.0        NaN       NaN        NaN         NaN  Faye Raker
+
+    >>> data = [
+    ...     {
+    ...         "id": 1,
+    ...         "name": "Cole Volk",
+    ...         "fitness": {"height": 130, "weight": 60},
+    ...     },
+    ...     {"name": "Mark Reg", "fitness": {"height": 130, "weight": 60}},
+    ...     {
+    ...         "id": 2,
+    ...         "name": "Faye Raker",
+    ...         "fitness": {"height": 130, "weight": 60},
+    ...     },
+    ... ]
+    >>> pd.json_normalize(data, max_level=0)
+        id        name                        fitness
+    0  1.0   Cole Volk  {'height': 130, 'weight': 60}
+    1  NaN    Mark Reg  {'height': 130, 'weight': 60}
+    2  2.0  Faye Raker  {'height': 130, 'weight': 60}
+
+    Normalizes nested data up to level 1.
+
+    >>> data = [
+    ...     {
+    ...         "id": 1,
+    ...         "name": "Cole Volk",
+    ...         "fitness": {"height": 130, "weight": 60},
+    ...     },
+    ...     {"name": "Mark Reg", "fitness": {"height": 130, "weight": 60}},
+    ...     {
+    ...         "id": 2,
+    ...         "name": "Faye Raker",
+    ...         "fitness": {"height": 130, "weight": 60},
+    ...     },
+    ... ]
+    >>> pd.json_normalize(data, max_level=1)
+        id        name  fitness.height  fitness.weight
+    0  1.0   Cole Volk             130              60
+    1  NaN    Mark Reg             130              60
+    2  2.0  Faye Raker             130              60
+
+    >>> data = [
+    ...     {
+    ...         "state": "Florida",
+    ...         "shortname": "FL",
+    ...         "info": {"governor": "Rick Scott"},
+    ...         "counties": [
+    ...             {"name": "Dade", "population": 12345},
+    ...             {"name": "Broward", "population": 40000},
+    ...             {"name": "Palm Beach", "population": 60000},
+    ...         ],
+    ...     },
+    ...     {
+    ...         "state": "Ohio",
+    ...         "shortname": "OH",
+    ...         "info": {"governor": "John Kasich"},
+    ...         "counties": [
+    ...             {"name": "Summit", "population": 1234},
+    ...             {"name": "Cuyahoga", "population": 1337},
+    ...         ],
+    ...     },
+    ... ]
+    >>> result = pd.json_normalize(
+    ...     data, "counties", ["state", "shortname", ["info", "governor"]]
+    ... )
+    >>> result
+             name  population    state shortname info.governor
+    0        Dade       12345   Florida    FL    Rick Scott
+    1     Broward       40000   Florida    FL    Rick Scott
+    2  Palm Beach       60000   Florida    FL    Rick Scott
+    3      Summit        1234   Ohio       OH    John Kasich
+    4    Cuyahoga        1337   Ohio       OH    John Kasich
+
+    >>> data = {"A": [1, 2]}
+    >>> pd.json_normalize(data, "A", record_prefix="Prefix.")
+        Prefix.0
+    0          1
+    1          2
+
+    Returns normalized data with columns prefixed with the given string.
+    """
+
+    def _pull_field(
+        js: dict[str, Any], spec: list | str, extract_record: bool = False
+    ) -> Scalar | Iterable:
+        """Internal function to pull field"""
+        result = js
+        try:
+            if isinstance(spec, list):
+                for field in spec:
+                    if result is None:
+                        raise KeyError(field)
+                    result = result[field]
+            else:
+                result = result[spec]
+        except KeyError as e:
+            if extract_record:
+                raise KeyError(
+                    f"Key {e} not found. If specifying a record_path, all elements of "
+                    f"data should have the path."
+                ) from e
+            if errors == "ignore":
+                return np.nan
+            else:
+                raise KeyError(
+                    f"Key {e} not found. To replace missing values of {e} with "
+                    f"np.nan, pass in errors='ignore'"
+                ) from e
+
+        return result
+
+    def _pull_records(js: dict[str, Any], spec: list | str) -> list:
+        """
+        Internal function to pull field for records, and similar to
+        _pull_field, but require to return list. And will raise error
+        if has non iterable value.
+        """
+        result = _pull_field(js, spec, extract_record=True)
+
+        # GH 31507 GH 30145, GH 26284 if result is not list, raise TypeError if not
+        # null, otherwise return an empty list
+        if not isinstance(result, list):
+            if pd.isnull(result):
+                result = []
+            else:
+                raise TypeError(
+                    f"{js} has non list value {result} for path {spec}. "
+                    "Must be list or null."
+                )
+        return result
+
+    if isinstance(data, list) and not data:
+        return DataFrame()
+    elif isinstance(data, dict):
+        # A bit of a hackjob
+        data = [data]
+    elif isinstance(data, abc.Iterable) and not isinstance(data, str):
+        # GH35923 Fix pd.json_normalize to not skip the first element of a
+        # generator input
+        data = list(data)
+    else:
+        raise NotImplementedError
+
+    # check to see if a simple recursive function is possible to
+    # improve performance (see #15621) but only for cases such
+    # as pd.Dataframe(data) or pd.Dataframe(data, sep)
+    if (
+        record_path is None
+        and meta is None
+        and meta_prefix is None
+        and record_prefix is None
+        and max_level is None
+    ):
+        return DataFrame(_simple_json_normalize(data, sep=sep))
+
+    if record_path is None:
+        if any([isinstance(x, dict) for x in y.values()] for y in data):
+            # naive normalization, this is idempotent for flat records
+            # and potentially will inflate the data considerably for
+            # deeply nested structures:
+            #  {VeryLong: { b: 1,c:2}} -> {VeryLong.b:1 ,VeryLong.c:@}
+            #
+            # TODO: handle record value which are lists, at least error
+            #       reasonably
+            data = nested_to_record(data, sep=sep, max_level=max_level)
+        return DataFrame(data)
+    elif not isinstance(record_path, list):
+        record_path = [record_path]
+
+    if meta is None:
+        meta = []
+    elif not isinstance(meta, list):
+        meta = [meta]
+
+    _meta = [m if isinstance(m, list) else [m] for m in meta]
+
+    # Disastrously inefficient for now
+    records: list = []
+    lengths = []
+
+    meta_vals: DefaultDict = defaultdict(list)
+    meta_keys = [sep.join(val) for val in _meta]
+
+    def _recursive_extract(data, path, seen_meta, level: int = 0) -> None:
+        if isinstance(data, dict):
+            data = [data]
+        if len(path) > 1:
+            for obj in data:
+                for val, key in zip(_meta, meta_keys):
+                    if level + 1 == len(val):
+                        seen_meta[key] = _pull_field(obj, val[-1])
+
+                _recursive_extract(obj[path[0]], path[1:], seen_meta, level=level + 1)
+        else:
+            for obj in data:
+                recs = _pull_records(obj, path[0])
+                recs = [
+                    nested_to_record(r, sep=sep, max_level=max_level)
+                    if isinstance(r, dict)
+                    else r
+                    for r in recs
+                ]
+
+                # For repeating the metadata later
+                lengths.append(len(recs))
+                for val, key in zip(_meta, meta_keys):
+                    if level + 1 > len(val):
+                        meta_val = seen_meta[key]
+                    else:
+                        meta_val = _pull_field(obj, val[level:])
+                    meta_vals[key].append(meta_val)
+                records.extend(recs)
+
+    _recursive_extract(data, record_path, {}, level=0)
+
+    result = DataFrame(records)
+
+    if record_prefix is not None:
+        result = result.rename(columns=lambda x: f"{record_prefix}{x}")
+
+    # Data types, a problem
+    for k, v in meta_vals.items():
+        if meta_prefix is not None:
+            k = meta_prefix + k
+
+        if k in result:
+            raise ValueError(
+                f"Conflicting metadata name {k}, need distinguishing prefix "
+            )
+        # GH 37782
+
+        values = np.array(v, dtype=object)
+
+        if values.ndim > 1:
+            # GH 37782
+            values = np.empty((len(v),), dtype=object)
+            for i, v in enumerate(v):
+                values[i] = v
+
+        result[k] = values.repeat(lengths)
+    return result
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/json/_table_schema.py b/.venv/lib/python3.13/site-packages/pandas/io/json/_table_schema.py
new file mode 100644
index 0000000000000000000000000000000000000000..c72411d87eabfe2838061a0a99d1e9de9aeed8a5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/json/_table_schema.py
@@ -0,0 +1,387 @@
+"""
+Table Schema builders
+
+https://specs.frictionlessdata.io/table-schema/
+"""
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+import warnings
+
+from pandas._libs import lib
+from pandas._libs.json import ujson_loads
+from pandas._libs.tslibs import timezones
+from pandas._libs.tslibs.dtypes import freq_to_period_freqstr
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import _registry as registry
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_integer_dtype,
+    is_numeric_dtype,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    DatetimeTZDtype,
+    ExtensionDtype,
+    PeriodDtype,
+)
+
+from pandas import DataFrame
+import pandas.core.common as com
+
+from pandas.tseries.frequencies import to_offset
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DtypeObj,
+        JSONSerializable,
+    )
+
+    from pandas import Series
+    from pandas.core.indexes.multi import MultiIndex
+
+
+TABLE_SCHEMA_VERSION = "1.4.0"
+
+
+def as_json_table_type(x: DtypeObj) -> str:
+    """
+    Convert a NumPy / pandas type to its corresponding json_table.
+
+    Parameters
+    ----------
+    x : np.dtype or ExtensionDtype
+
+    Returns
+    -------
+    str
+        the Table Schema data types
+
+    Notes
+    -----
+    This table shows the relationship between NumPy / pandas dtypes,
+    and Table Schema dtypes.
+
+    ==============  =================
+    Pandas type     Table Schema type
+    ==============  =================
+    int64           integer
+    float64         number
+    bool            boolean
+    datetime64[ns]  datetime
+    timedelta64[ns] duration
+    object          str
+    categorical     any
+    =============== =================
+    """
+    if is_integer_dtype(x):
+        return "integer"
+    elif is_bool_dtype(x):
+        return "boolean"
+    elif is_numeric_dtype(x):
+        return "number"
+    elif lib.is_np_dtype(x, "M") or isinstance(x, (DatetimeTZDtype, PeriodDtype)):
+        return "datetime"
+    elif lib.is_np_dtype(x, "m"):
+        return "duration"
+    elif is_string_dtype(x):
+        return "string"
+    else:
+        return "any"
+
+
+def set_default_names(data):
+    """Sets index names to 'index' for regular, or 'level_x' for Multi"""
+    if com.all_not_none(*data.index.names):
+        nms = data.index.names
+        if len(nms) == 1 and data.index.name == "index":
+            warnings.warn(
+                "Index name of 'index' is not round-trippable.",
+                stacklevel=find_stack_level(),
+            )
+        elif len(nms) > 1 and any(x.startswith("level_") for x in nms):
+            warnings.warn(
+                "Index names beginning with 'level_' are not round-trippable.",
+                stacklevel=find_stack_level(),
+            )
+        return data
+
+    data = data.copy()
+    if data.index.nlevels > 1:
+        data.index.names = com.fill_missing_names(data.index.names)
+    else:
+        data.index.name = data.index.name or "index"
+    return data
+
+
+def convert_pandas_type_to_json_field(arr) -> dict[str, JSONSerializable]:
+    dtype = arr.dtype
+    name: JSONSerializable
+    if arr.name is None:
+        name = "values"
+    else:
+        name = arr.name
+    field: dict[str, JSONSerializable] = {
+        "name": name,
+        "type": as_json_table_type(dtype),
+    }
+
+    if isinstance(dtype, CategoricalDtype):
+        cats = dtype.categories
+        ordered = dtype.ordered
+
+        field["constraints"] = {"enum": list(cats)}
+        field["ordered"] = ordered
+    elif isinstance(dtype, PeriodDtype):
+        field["freq"] = dtype.freq.freqstr
+    elif isinstance(dtype, DatetimeTZDtype):
+        if timezones.is_utc(dtype.tz):
+            # timezone.utc has no "zone" attr
+            field["tz"] = "UTC"
+        else:
+            # error: "tzinfo" has no attribute "zone"
+            field["tz"] = dtype.tz.zone  # type: ignore[attr-defined]
+    elif isinstance(dtype, ExtensionDtype):
+        field["extDtype"] = dtype.name
+    return field
+
+
+def convert_json_field_to_pandas_type(field) -> str | CategoricalDtype:
+    """
+    Converts a JSON field descriptor into its corresponding NumPy / pandas type
+
+    Parameters
+    ----------
+    field
+        A JSON field descriptor
+
+    Returns
+    -------
+    dtype
+
+    Raises
+    ------
+    ValueError
+        If the type of the provided field is unknown or currently unsupported
+
+    Examples
+    --------
+    >>> convert_json_field_to_pandas_type({"name": "an_int", "type": "integer"})
+    'int64'
+
+    >>> convert_json_field_to_pandas_type(
+    ...     {
+    ...         "name": "a_categorical",
+    ...         "type": "any",
+    ...         "constraints": {"enum": ["a", "b", "c"]},
+    ...         "ordered": True,
+    ...     }
+    ... )
+    CategoricalDtype(categories=['a', 'b', 'c'], ordered=True, categories_dtype=object)
+
+    >>> convert_json_field_to_pandas_type({"name": "a_datetime", "type": "datetime"})
+    'datetime64[ns]'
+
+    >>> convert_json_field_to_pandas_type(
+    ...     {"name": "a_datetime_with_tz", "type": "datetime", "tz": "US/Central"}
+    ... )
+    'datetime64[ns, US/Central]'
+    """
+    typ = field["type"]
+    if typ == "string":
+        return field.get("extDtype", None)
+    elif typ == "integer":
+        return field.get("extDtype", "int64")
+    elif typ == "number":
+        return field.get("extDtype", "float64")
+    elif typ == "boolean":
+        return field.get("extDtype", "bool")
+    elif typ == "duration":
+        return "timedelta64"
+    elif typ == "datetime":
+        if field.get("tz"):
+            return f"datetime64[ns, {field['tz']}]"
+        elif field.get("freq"):
+            # GH#9586 rename frequency M to ME for offsets
+            offset = to_offset(field["freq"])
+            freq_n, freq_name = offset.n, offset.name
+            freq = freq_to_period_freqstr(freq_n, freq_name)
+            # GH#47747 using datetime over period to minimize the change surface
+            return f"period[{freq}]"
+        else:
+            return "datetime64[ns]"
+    elif typ == "any":
+        if "constraints" in field and "ordered" in field:
+            return CategoricalDtype(
+                categories=field["constraints"]["enum"], ordered=field["ordered"]
+            )
+        elif "extDtype" in field:
+            return registry.find(field["extDtype"])
+        else:
+            return "object"
+
+    raise ValueError(f"Unsupported or invalid field type: {typ}")
+
+
+def build_table_schema(
+    data: DataFrame | Series,
+    index: bool = True,
+    primary_key: bool | None = None,
+    version: bool = True,
+) -> dict[str, JSONSerializable]:
+    """
+    Create a Table schema from ``data``.
+
+    Parameters
+    ----------
+    data : Series, DataFrame
+    index : bool, default True
+        Whether to include ``data.index`` in the schema.
+    primary_key : bool or None, default True
+        Column names to designate as the primary key.
+        The default `None` will set `'primaryKey'` to the index
+        level or levels if the index is unique.
+    version : bool, default True
+        Whether to include a field `pandas_version` with the version
+        of pandas that last revised the table schema. This version
+        can be different from the installed pandas version.
+
+    Returns
+    -------
+    dict
+
+    Notes
+    -----
+    See `Table Schema
+    `__ for
+    conversion types.
+    Timedeltas as converted to ISO8601 duration format with
+    9 decimal places after the seconds field for nanosecond precision.
+
+    Categoricals are converted to the `any` dtype, and use the `enum` field
+    constraint to list the allowed values. The `ordered` attribute is included
+    in an `ordered` field.
+
+    Examples
+    --------
+    >>> from pandas.io.json._table_schema import build_table_schema
+    >>> df = pd.DataFrame(
+    ...     {'A': [1, 2, 3],
+    ...      'B': ['a', 'b', 'c'],
+    ...      'C': pd.date_range('2016-01-01', freq='d', periods=3),
+    ...     }, index=pd.Index(range(3), name='idx'))
+    >>> build_table_schema(df)
+    {'fields': \
+[{'name': 'idx', 'type': 'integer'}, \
+{'name': 'A', 'type': 'integer'}, \
+{'name': 'B', 'type': 'string'}, \
+{'name': 'C', 'type': 'datetime'}], \
+'primaryKey': ['idx'], \
+'pandas_version': '1.4.0'}
+    """
+    if index is True:
+        data = set_default_names(data)
+
+    schema: dict[str, Any] = {}
+    fields = []
+
+    if index:
+        if data.index.nlevels > 1:
+            data.index = cast("MultiIndex", data.index)
+            for level, name in zip(data.index.levels, data.index.names):
+                new_field = convert_pandas_type_to_json_field(level)
+                new_field["name"] = name
+                fields.append(new_field)
+        else:
+            fields.append(convert_pandas_type_to_json_field(data.index))
+
+    if data.ndim > 1:
+        for column, s in data.items():
+            fields.append(convert_pandas_type_to_json_field(s))
+    else:
+        fields.append(convert_pandas_type_to_json_field(data))
+
+    schema["fields"] = fields
+    if index and data.index.is_unique and primary_key is None:
+        if data.index.nlevels == 1:
+            schema["primaryKey"] = [data.index.name]
+        else:
+            schema["primaryKey"] = data.index.names
+    elif primary_key is not None:
+        schema["primaryKey"] = primary_key
+
+    if version:
+        schema["pandas_version"] = TABLE_SCHEMA_VERSION
+    return schema
+
+
+def parse_table_schema(json, precise_float: bool) -> DataFrame:
+    """
+    Builds a DataFrame from a given schema
+
+    Parameters
+    ----------
+    json :
+        A JSON table schema
+    precise_float : bool
+        Flag controlling precision when decoding string to double values, as
+        dictated by ``read_json``
+
+    Returns
+    -------
+    df : DataFrame
+
+    Raises
+    ------
+    NotImplementedError
+        If the JSON table schema contains either timezone or timedelta data
+
+    Notes
+    -----
+        Because :func:`DataFrame.to_json` uses the string 'index' to denote a
+        name-less :class:`Index`, this function sets the name of the returned
+        :class:`DataFrame` to ``None`` when said string is encountered with a
+        normal :class:`Index`. For a :class:`MultiIndex`, the same limitation
+        applies to any strings beginning with 'level_'. Therefore, an
+        :class:`Index` name of 'index'  and :class:`MultiIndex` names starting
+        with 'level_' are not supported.
+
+    See Also
+    --------
+    build_table_schema : Inverse function.
+    pandas.read_json
+    """
+    table = ujson_loads(json, precise_float=precise_float)
+    col_order = [field["name"] for field in table["schema"]["fields"]]
+    df = DataFrame(table["data"], columns=col_order)[col_order]
+
+    dtypes = {
+        field["name"]: convert_json_field_to_pandas_type(field)
+        for field in table["schema"]["fields"]
+    }
+
+    # No ISO constructor for Timedelta as of yet, so need to raise
+    if "timedelta64" in dtypes.values():
+        raise NotImplementedError(
+            'table="orient" can not yet read ISO-formatted Timedelta data'
+        )
+
+    df = df.astype(dtypes)
+
+    if "primaryKey" in table["schema"]:
+        df = df.set_index(table["schema"]["primaryKey"])
+        if len(df.index.names) == 1:
+            if df.index.name == "index":
+                df.index.name = None
+        else:
+            df.index.names = [
+                None if x.startswith("level_") else x for x in df.index.names
+            ]
+
+    return df
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/orc.py b/.venv/lib/python3.13/site-packages/pandas/io/orc.py
new file mode 100644
index 0000000000000000000000000000000000000000..d7f473a929568faa9a00886d627c65fa57a3aa18
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/orc.py
@@ -0,0 +1,228 @@
+""" orc compat """
+from __future__ import annotations
+
+import io
+from types import ModuleType
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.indexes.api import default_index
+
+from pandas.io._util import arrow_table_to_pandas
+from pandas.io.common import (
+    get_handle,
+    is_fsspec_url,
+)
+
+if TYPE_CHECKING:
+    import fsspec
+    import pyarrow.fs
+
+    from pandas._typing import (
+        DtypeBackend,
+        FilePath,
+        ReadBuffer,
+        WriteBuffer,
+    )
+
+    from pandas.core.frame import DataFrame
+
+
+def read_orc(
+    path: FilePath | ReadBuffer[bytes],
+    columns: list[str] | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    filesystem: pyarrow.fs.FileSystem | fsspec.spec.AbstractFileSystem | None = None,
+    **kwargs: Any,
+) -> DataFrame:
+    """
+    Load an ORC object from the file path, returning a DataFrame.
+
+    Parameters
+    ----------
+    path : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``read()`` function. The string could be a URL.
+        Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.orc``.
+    columns : list, default None
+        If not None, only these columns will be read from the file.
+        Output always follows the ordering of the file and not the columns list.
+        This mirrors the original behaviour of
+        :external+pyarrow:py:meth:`pyarrow.orc.ORCFile.read`.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    filesystem : fsspec or pyarrow filesystem, default None
+        Filesystem object to use when reading the parquet file.
+
+        .. versionadded:: 2.1.0
+
+    **kwargs
+        Any additional kwargs are passed to pyarrow.
+
+    Returns
+    -------
+    DataFrame
+
+    Notes
+    -----
+    Before using this function you should read the :ref:`user guide about ORC `
+    and :ref:`install optional dependencies `.
+
+    If ``path`` is a URI scheme pointing to a local or remote file (e.g. "s3://"),
+    a ``pyarrow.fs`` filesystem will be attempted to read the file. You can also pass a
+    pyarrow or fsspec filesystem object into the filesystem keyword to override this
+    behavior.
+
+    Examples
+    --------
+    >>> result = pd.read_orc("example_pa.orc")  # doctest: +SKIP
+    """
+    # we require a newer version of pyarrow than we support for parquet
+
+    orc = import_optional_dependency("pyarrow.orc")
+
+    check_dtype_backend(dtype_backend)
+
+    with get_handle(path, "rb", is_text=False) as handles:
+        source = handles.handle
+        if is_fsspec_url(path) and filesystem is None:
+            pa = import_optional_dependency("pyarrow")
+            pa_fs = import_optional_dependency("pyarrow.fs")
+            try:
+                filesystem, source = pa_fs.FileSystem.from_uri(path)
+            except (TypeError, pa.ArrowInvalid):
+                pass
+
+        pa_table = orc.read_table(
+            source=source, columns=columns, filesystem=filesystem, **kwargs
+        )
+    return arrow_table_to_pandas(pa_table, dtype_backend=dtype_backend)
+
+
+def to_orc(
+    df: DataFrame,
+    path: FilePath | WriteBuffer[bytes] | None = None,
+    *,
+    engine: Literal["pyarrow"] = "pyarrow",
+    index: bool | None = None,
+    engine_kwargs: dict[str, Any] | None = None,
+) -> bytes | None:
+    """
+    Write a DataFrame to the ORC format.
+
+    .. versionadded:: 1.5.0
+
+    Parameters
+    ----------
+    df : DataFrame
+        The dataframe to be written to ORC. Raises NotImplementedError
+        if dtype of one or more columns is category, unsigned integers,
+        intervals, periods or sparse.
+    path : str, file-like object or None, default None
+        If a string, it will be used as Root Directory path
+        when writing a partitioned dataset. By file-like object,
+        we refer to objects with a write() method, such as a file handle
+        (e.g. via builtin open function). If path is None,
+        a bytes object is returned.
+    engine : str, default 'pyarrow'
+        ORC library to use.
+    index : bool, optional
+        If ``True``, include the dataframe's index(es) in the file output. If
+        ``False``, they will not be written to the file.
+        If ``None``, similar to ``infer`` the dataframe's index(es)
+        will be saved. However, instead of being saved as values,
+        the RangeIndex will be stored as a range in the metadata so it
+        doesn't require much space and is faster. Other indexes will
+        be included as columns in the file output.
+    engine_kwargs : dict[str, Any] or None, default None
+        Additional keyword arguments passed to :func:`pyarrow.orc.write_table`.
+
+    Returns
+    -------
+    bytes if no path argument is provided else None
+
+    Raises
+    ------
+    NotImplementedError
+        Dtype of one or more columns is category, unsigned integers, interval,
+        period or sparse.
+    ValueError
+        engine is not pyarrow.
+
+    Notes
+    -----
+    * Before using this function you should read the
+      :ref:`user guide about ORC ` and
+      :ref:`install optional dependencies `.
+    * This function requires `pyarrow `_
+      library.
+    * For supported dtypes please refer to `supported ORC features in Arrow
+      `__.
+    * Currently timezones in datetime columns are not preserved when a
+      dataframe is converted into ORC files.
+    """
+    if index is None:
+        index = df.index.names[0] is not None
+    if engine_kwargs is None:
+        engine_kwargs = {}
+
+    # validate index
+    # --------------
+
+    # validate that we have only a default index
+    # raise on anything else as we don't serialize the index
+
+    if not df.index.equals(default_index(len(df))):
+        raise ValueError(
+            "orc does not support serializing a non-default index for the index; "
+            "you can .reset_index() to make the index into column(s)"
+        )
+
+    if df.index.name is not None:
+        raise ValueError("orc does not serialize index meta-data on a default index")
+
+    if engine != "pyarrow":
+        raise ValueError("engine must be 'pyarrow'")
+    engine = import_optional_dependency(engine, min_version="10.0.1")
+    pa = import_optional_dependency("pyarrow")
+    orc = import_optional_dependency("pyarrow.orc")
+
+    was_none = path is None
+    if was_none:
+        path = io.BytesIO()
+    assert path is not None  # For mypy
+    with get_handle(path, "wb", is_text=False) as handles:
+        assert isinstance(engine, ModuleType)  # For mypy
+        try:
+            orc.write_table(
+                engine.Table.from_pandas(df, preserve_index=index),
+                handles.handle,
+                **engine_kwargs,
+            )
+        except (TypeError, pa.ArrowNotImplementedError) as e:
+            raise NotImplementedError(
+                "The dtype of one or more columns is not supported yet."
+            ) from e
+
+    if was_none:
+        assert isinstance(path, io.BytesIO)  # For mypy
+        return path.getvalue()
+    return None
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parquet.py b/.venv/lib/python3.13/site-packages/pandas/io/parquet.py
new file mode 100644
index 0000000000000000000000000000000000000000..01e320cdb1b72a4f9425de40721c43189b4c5ed8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parquet.py
@@ -0,0 +1,678 @@
+""" parquet compat """
+from __future__ import annotations
+
+import io
+import json
+import os
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+)
+import warnings
+from warnings import (
+    catch_warnings,
+    filterwarnings,
+)
+
+from pandas._config.config import _get_option
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas import (
+    DataFrame,
+    get_option,
+)
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io._util import arrow_table_to_pandas
+from pandas.io.common import (
+    IOHandles,
+    get_handle,
+    is_fsspec_url,
+    is_url,
+    stringify_path,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        DtypeBackend,
+        FilePath,
+        ReadBuffer,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+
+def get_engine(engine: str) -> BaseImpl:
+    """return our implementation"""
+    if engine == "auto":
+        engine = get_option("io.parquet.engine")
+
+    if engine == "auto":
+        # try engines in this order
+        engine_classes = [PyArrowImpl, FastParquetImpl]
+
+        error_msgs = ""
+        for engine_class in engine_classes:
+            try:
+                return engine_class()
+            except ImportError as err:
+                error_msgs += "\n - " + str(err)
+
+        raise ImportError(
+            "Unable to find a usable engine; "
+            "tried using: 'pyarrow', 'fastparquet'.\n"
+            "A suitable version of "
+            "pyarrow or fastparquet is required for parquet "
+            "support.\n"
+            "Trying to import the above resulted in these errors:"
+            f"{error_msgs}"
+        )
+
+    if engine == "pyarrow":
+        return PyArrowImpl()
+    elif engine == "fastparquet":
+        return FastParquetImpl()
+
+    raise ValueError("engine must be one of 'pyarrow', 'fastparquet'")
+
+
+def _get_path_or_handle(
+    path: FilePath | ReadBuffer[bytes] | WriteBuffer[bytes],
+    fs: Any,
+    storage_options: StorageOptions | None = None,
+    mode: str = "rb",
+    is_dir: bool = False,
+) -> tuple[
+    FilePath | ReadBuffer[bytes] | WriteBuffer[bytes], IOHandles[bytes] | None, Any
+]:
+    """File handling for PyArrow."""
+    path_or_handle = stringify_path(path)
+    if fs is not None:
+        pa_fs = import_optional_dependency("pyarrow.fs", errors="ignore")
+        fsspec = import_optional_dependency("fsspec", errors="ignore")
+        if pa_fs is not None and isinstance(fs, pa_fs.FileSystem):
+            if storage_options:
+                raise NotImplementedError(
+                    "storage_options not supported with a pyarrow FileSystem."
+                )
+        elif fsspec is not None and isinstance(fs, fsspec.spec.AbstractFileSystem):
+            pass
+        else:
+            raise ValueError(
+                f"filesystem must be a pyarrow or fsspec FileSystem, "
+                f"not a {type(fs).__name__}"
+            )
+    if is_fsspec_url(path_or_handle) and fs is None:
+        if storage_options is None:
+            pa = import_optional_dependency("pyarrow")
+            pa_fs = import_optional_dependency("pyarrow.fs")
+
+            try:
+                fs, path_or_handle = pa_fs.FileSystem.from_uri(path)
+            except (TypeError, pa.ArrowInvalid):
+                pass
+        if fs is None:
+            fsspec = import_optional_dependency("fsspec")
+            fs, path_or_handle = fsspec.core.url_to_fs(
+                path_or_handle, **(storage_options or {})
+            )
+    elif storage_options and (not is_url(path_or_handle) or mode != "rb"):
+        # can't write to a remote url
+        # without making use of fsspec at the moment
+        raise ValueError("storage_options passed with buffer, or non-supported URL")
+
+    handles = None
+    if (
+        not fs
+        and not is_dir
+        and isinstance(path_or_handle, str)
+        and not os.path.isdir(path_or_handle)
+    ):
+        # use get_handle only when we are very certain that it is not a directory
+        # fsspec resources can also point to directories
+        # this branch is used for example when reading from non-fsspec URLs
+        handles = get_handle(
+            path_or_handle, mode, is_text=False, storage_options=storage_options
+        )
+        fs = None
+        path_or_handle = handles.handle
+    return path_or_handle, handles, fs
+
+
+class BaseImpl:
+    @staticmethod
+    def validate_dataframe(df: DataFrame) -> None:
+        if not isinstance(df, DataFrame):
+            raise ValueError("to_parquet only supports IO with DataFrames")
+
+    def write(self, df: DataFrame, path, compression, **kwargs):
+        raise AbstractMethodError(self)
+
+    def read(self, path, columns=None, **kwargs) -> DataFrame:
+        raise AbstractMethodError(self)
+
+
+class PyArrowImpl(BaseImpl):
+    def __init__(self) -> None:
+        import_optional_dependency(
+            "pyarrow", extra="pyarrow is required for parquet support."
+        )
+        import pyarrow.parquet
+
+        # import utils to register the pyarrow extension types
+        import pandas.core.arrays.arrow.extension_types  # pyright: ignore[reportUnusedImport] # noqa: F401
+
+        self.api = pyarrow
+
+    def write(
+        self,
+        df: DataFrame,
+        path: FilePath | WriteBuffer[bytes],
+        compression: str | None = "snappy",
+        index: bool | None = None,
+        storage_options: StorageOptions | None = None,
+        partition_cols: list[str] | None = None,
+        filesystem=None,
+        **kwargs,
+    ) -> None:
+        self.validate_dataframe(df)
+
+        from_pandas_kwargs: dict[str, Any] = {"schema": kwargs.pop("schema", None)}
+        if index is not None:
+            from_pandas_kwargs["preserve_index"] = index
+
+        table = self.api.Table.from_pandas(df, **from_pandas_kwargs)
+
+        if df.attrs:
+            df_metadata = {"PANDAS_ATTRS": json.dumps(df.attrs)}
+            existing_metadata = table.schema.metadata
+            merged_metadata = {**existing_metadata, **df_metadata}
+            table = table.replace_schema_metadata(merged_metadata)
+
+        path_or_handle, handles, filesystem = _get_path_or_handle(
+            path,
+            filesystem,
+            storage_options=storage_options,
+            mode="wb",
+            is_dir=partition_cols is not None,
+        )
+        if (
+            isinstance(path_or_handle, io.BufferedWriter)
+            and hasattr(path_or_handle, "name")
+            and isinstance(path_or_handle.name, (str, bytes))
+        ):
+            if isinstance(path_or_handle.name, bytes):
+                path_or_handle = path_or_handle.name.decode()
+            else:
+                path_or_handle = path_or_handle.name
+
+        try:
+            if partition_cols is not None:
+                # writes to multiple files under the given path
+                self.api.parquet.write_to_dataset(
+                    table,
+                    path_or_handle,
+                    compression=compression,
+                    partition_cols=partition_cols,
+                    filesystem=filesystem,
+                    **kwargs,
+                )
+            else:
+                # write to single output file
+                self.api.parquet.write_table(
+                    table,
+                    path_or_handle,
+                    compression=compression,
+                    filesystem=filesystem,
+                    **kwargs,
+                )
+        finally:
+            if handles is not None:
+                handles.close()
+
+    def read(
+        self,
+        path,
+        columns=None,
+        filters=None,
+        use_nullable_dtypes: bool = False,
+        dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+        storage_options: StorageOptions | None = None,
+        filesystem=None,
+        **kwargs,
+    ) -> DataFrame:
+        kwargs["use_pandas_metadata"] = True
+
+        to_pandas_kwargs = {}
+
+        manager = _get_option("mode.data_manager", silent=True)
+        if manager == "array":
+            to_pandas_kwargs["split_blocks"] = True
+        path_or_handle, handles, filesystem = _get_path_or_handle(
+            path,
+            filesystem,
+            storage_options=storage_options,
+            mode="rb",
+        )
+        try:
+            pa_table = self.api.parquet.read_table(
+                path_or_handle,
+                columns=columns,
+                filesystem=filesystem,
+                filters=filters,
+                **kwargs,
+            )
+
+            with catch_warnings():
+                filterwarnings(
+                    "ignore",
+                    "make_block is deprecated",
+                    DeprecationWarning,
+                )
+                result = arrow_table_to_pandas(
+                    pa_table,
+                    dtype_backend=dtype_backend,
+                    to_pandas_kwargs=to_pandas_kwargs,
+                )
+
+            if manager == "array":
+                result = result._as_manager("array", copy=False)
+
+            if pa_table.schema.metadata:
+                if b"PANDAS_ATTRS" in pa_table.schema.metadata:
+                    df_metadata = pa_table.schema.metadata[b"PANDAS_ATTRS"]
+                    result.attrs = json.loads(df_metadata)
+            return result
+        finally:
+            if handles is not None:
+                handles.close()
+
+
+class FastParquetImpl(BaseImpl):
+    def __init__(self) -> None:
+        # since pandas is a dependency of fastparquet
+        # we need to import on first use
+        fastparquet = import_optional_dependency(
+            "fastparquet", extra="fastparquet is required for parquet support."
+        )
+        self.api = fastparquet
+
+    def write(
+        self,
+        df: DataFrame,
+        path,
+        compression: Literal["snappy", "gzip", "brotli"] | None = "snappy",
+        index=None,
+        partition_cols=None,
+        storage_options: StorageOptions | None = None,
+        filesystem=None,
+        **kwargs,
+    ) -> None:
+        self.validate_dataframe(df)
+
+        if "partition_on" in kwargs and partition_cols is not None:
+            raise ValueError(
+                "Cannot use both partition_on and "
+                "partition_cols. Use partition_cols for partitioning data"
+            )
+        if "partition_on" in kwargs:
+            partition_cols = kwargs.pop("partition_on")
+
+        if partition_cols is not None:
+            kwargs["file_scheme"] = "hive"
+
+        if filesystem is not None:
+            raise NotImplementedError(
+                "filesystem is not implemented for the fastparquet engine."
+            )
+
+        # cannot use get_handle as write() does not accept file buffers
+        path = stringify_path(path)
+        if is_fsspec_url(path):
+            fsspec = import_optional_dependency("fsspec")
+
+            # if filesystem is provided by fsspec, file must be opened in 'wb' mode.
+            kwargs["open_with"] = lambda path, _: fsspec.open(
+                path, "wb", **(storage_options or {})
+            ).open()
+        elif storage_options:
+            raise ValueError(
+                "storage_options passed with file object or non-fsspec file path"
+            )
+
+        with catch_warnings(record=True):
+            self.api.write(
+                path,
+                df,
+                compression=compression,
+                write_index=index,
+                partition_on=partition_cols,
+                **kwargs,
+            )
+
+    def read(
+        self,
+        path,
+        columns=None,
+        filters=None,
+        storage_options: StorageOptions | None = None,
+        filesystem=None,
+        **kwargs,
+    ) -> DataFrame:
+        parquet_kwargs: dict[str, Any] = {}
+        use_nullable_dtypes = kwargs.pop("use_nullable_dtypes", False)
+        dtype_backend = kwargs.pop("dtype_backend", lib.no_default)
+        # We are disabling nullable dtypes for fastparquet pending discussion
+        parquet_kwargs["pandas_nulls"] = False
+        if use_nullable_dtypes:
+            raise ValueError(
+                "The 'use_nullable_dtypes' argument is not supported for the "
+                "fastparquet engine"
+            )
+        if dtype_backend is not lib.no_default:
+            raise ValueError(
+                "The 'dtype_backend' argument is not supported for the "
+                "fastparquet engine"
+            )
+        if filesystem is not None:
+            raise NotImplementedError(
+                "filesystem is not implemented for the fastparquet engine."
+            )
+        path = stringify_path(path)
+        handles = None
+        if is_fsspec_url(path):
+            fsspec = import_optional_dependency("fsspec")
+
+            parquet_kwargs["fs"] = fsspec.open(path, "rb", **(storage_options or {})).fs
+        elif isinstance(path, str) and not os.path.isdir(path):
+            # use get_handle only when we are very certain that it is not a directory
+            # fsspec resources can also point to directories
+            # this branch is used for example when reading from non-fsspec URLs
+            handles = get_handle(
+                path, "rb", is_text=False, storage_options=storage_options
+            )
+            path = handles.handle
+
+        try:
+            parquet_file = self.api.ParquetFile(path, **parquet_kwargs)
+            return parquet_file.to_pandas(columns=columns, filters=filters, **kwargs)
+        finally:
+            if handles is not None:
+                handles.close()
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def to_parquet(
+    df: DataFrame,
+    path: FilePath | WriteBuffer[bytes] | None = None,
+    engine: str = "auto",
+    compression: str | None = "snappy",
+    index: bool | None = None,
+    storage_options: StorageOptions | None = None,
+    partition_cols: list[str] | None = None,
+    filesystem: Any = None,
+    **kwargs,
+) -> bytes | None:
+    """
+    Write a DataFrame to the parquet format.
+
+    Parameters
+    ----------
+    df : DataFrame
+    path : str, path object, file-like object, or None, default None
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``write()`` function. If None, the result is
+        returned as bytes. If a string, it will be used as Root Directory path
+        when writing a partitioned dataset. The engine fastparquet does not
+        accept file-like objects.
+    engine : {{'auto', 'pyarrow', 'fastparquet'}}, default 'auto'
+        Parquet library to use. If 'auto', then the option
+        ``io.parquet.engine`` is used. The default ``io.parquet.engine``
+        behavior is to try 'pyarrow', falling back to 'fastparquet' if
+        'pyarrow' is unavailable.
+
+        When using the ``'pyarrow'`` engine and no storage options are provided
+        and a filesystem is implemented by both ``pyarrow.fs`` and ``fsspec``
+        (e.g. "s3://"), then the ``pyarrow.fs`` filesystem is attempted first.
+        Use the filesystem keyword with an instantiated fsspec filesystem
+        if you wish to use its implementation.
+    compression : {{'snappy', 'gzip', 'brotli', 'lz4', 'zstd', None}},
+        default 'snappy'. Name of the compression to use. Use ``None``
+        for no compression.
+    index : bool, default None
+        If ``True``, include the dataframe's index(es) in the file output. If
+        ``False``, they will not be written to the file.
+        If ``None``, similar to ``True`` the dataframe's index(es)
+        will be saved. However, instead of being saved as values,
+        the RangeIndex will be stored as a range in the metadata so it
+        doesn't require much space and is faster. Other indexes will
+        be included as columns in the file output.
+    partition_cols : str or list, optional, default None
+        Column names by which to partition the dataset.
+        Columns are partitioned in the order they are given.
+        Must be None if path is not a string.
+    {storage_options}
+
+    filesystem : fsspec or pyarrow filesystem, default None
+        Filesystem object to use when reading the parquet file. Only implemented
+        for ``engine="pyarrow"``.
+
+        .. versionadded:: 2.1.0
+
+    kwargs
+        Additional keyword arguments passed to the engine
+
+    Returns
+    -------
+    bytes if no path argument is provided else None
+    """
+    if isinstance(partition_cols, str):
+        partition_cols = [partition_cols]
+    impl = get_engine(engine)
+
+    path_or_buf: FilePath | WriteBuffer[bytes] = io.BytesIO() if path is None else path
+
+    impl.write(
+        df,
+        path_or_buf,
+        compression=compression,
+        index=index,
+        partition_cols=partition_cols,
+        storage_options=storage_options,
+        filesystem=filesystem,
+        **kwargs,
+    )
+
+    if path is None:
+        assert isinstance(path_or_buf, io.BytesIO)
+        return path_or_buf.getvalue()
+    else:
+        return None
+
+
+@doc(storage_options=_shared_docs["storage_options"])
+def read_parquet(
+    path: FilePath | ReadBuffer[bytes],
+    engine: str = "auto",
+    columns: list[str] | None = None,
+    storage_options: StorageOptions | None = None,
+    use_nullable_dtypes: bool | lib.NoDefault = lib.no_default,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    filesystem: Any = None,
+    filters: list[tuple] | list[list[tuple]] | None = None,
+    **kwargs,
+) -> DataFrame:
+    """
+    Load a parquet object from the file path, returning a DataFrame.
+
+    Parameters
+    ----------
+    path : str, path object or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``read()`` function.
+        The string could be a URL. Valid URL schemes include http, ftp, s3,
+        gs, and file. For file URLs, a host is expected. A local file could be:
+        ``file://localhost/path/to/table.parquet``.
+        A file URL can also be a path to a directory that contains multiple
+        partitioned parquet files. Both pyarrow and fastparquet support
+        paths to directories as well as file URLs. A directory path could be:
+        ``file://localhost/path/to/tables`` or ``s3://bucket/partition_dir``.
+    engine : {{'auto', 'pyarrow', 'fastparquet'}}, default 'auto'
+        Parquet library to use. If 'auto', then the option
+        ``io.parquet.engine`` is used. The default ``io.parquet.engine``
+        behavior is to try 'pyarrow', falling back to 'fastparquet' if
+        'pyarrow' is unavailable.
+
+        When using the ``'pyarrow'`` engine and no storage options are provided
+        and a filesystem is implemented by both ``pyarrow.fs`` and ``fsspec``
+        (e.g. "s3://"), then the ``pyarrow.fs`` filesystem is attempted first.
+        Use the filesystem keyword with an instantiated fsspec filesystem
+        if you wish to use its implementation.
+    columns : list, default=None
+        If not None, only these columns will be read from the file.
+    {storage_options}
+
+        .. versionadded:: 1.3.0
+
+    use_nullable_dtypes : bool, default False
+        If True, use dtypes that use ``pd.NA`` as missing value indicator
+        for the resulting DataFrame. (only applicable for the ``pyarrow``
+        engine)
+        As new dtypes are added that support ``pd.NA`` in the future, the
+        output with this option will change to use those dtypes.
+        Note: this is an experimental option, and behaviour (e.g. additional
+        support dtypes) may change without notice.
+
+        .. deprecated:: 2.0
+
+    dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    filesystem : fsspec or pyarrow filesystem, default None
+        Filesystem object to use when reading the parquet file. Only implemented
+        for ``engine="pyarrow"``.
+
+        .. versionadded:: 2.1.0
+
+    filters : List[Tuple] or List[List[Tuple]], default None
+        To filter out data.
+        Filter syntax: [[(column, op, val), ...],...]
+        where op is [==, =, >, >=, <, <=, !=, in, not in]
+        The innermost tuples are transposed into a set of filters applied
+        through an `AND` operation.
+        The outer list combines these sets of filters through an `OR`
+        operation.
+        A single list of tuples can also be used, meaning that no `OR`
+        operation between set of filters is to be conducted.
+
+        Using this argument will NOT result in row-wise filtering of the final
+        partitions unless ``engine="pyarrow"`` is also specified.  For
+        other engines, filtering is only performed at the partition level, that is,
+        to prevent the loading of some row-groups and/or files.
+
+        .. versionadded:: 2.1.0
+
+    **kwargs
+        Any additional kwargs are passed to the engine.
+
+    Returns
+    -------
+    DataFrame
+
+    See Also
+    --------
+    DataFrame.to_parquet : Create a parquet object that serializes a DataFrame.
+
+    Examples
+    --------
+    >>> original_df = pd.DataFrame(
+    ...     {{"foo": range(5), "bar": range(5, 10)}}
+    ...    )
+    >>> original_df
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    >>> df_parquet_bytes = original_df.to_parquet()
+    >>> from io import BytesIO
+    >>> restored_df = pd.read_parquet(BytesIO(df_parquet_bytes))
+    >>> restored_df
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    >>> restored_df.equals(original_df)
+    True
+    >>> restored_bar = pd.read_parquet(BytesIO(df_parquet_bytes), columns=["bar"])
+    >>> restored_bar
+        bar
+    0    5
+    1    6
+    2    7
+    3    8
+    4    9
+    >>> restored_bar.equals(original_df[['bar']])
+    True
+
+    The function uses `kwargs` that are passed directly to the engine.
+    In the following example, we use the `filters` argument of the pyarrow
+    engine to filter the rows of the DataFrame.
+
+    Since `pyarrow` is the default engine, we can omit the `engine` argument.
+    Note that the `filters` argument is implemented by the `pyarrow` engine,
+    which can benefit from multithreading and also potentially be more
+    economical in terms of memory.
+
+    >>> sel = [("foo", ">", 2)]
+    >>> restored_part = pd.read_parquet(BytesIO(df_parquet_bytes), filters=sel)
+    >>> restored_part
+        foo  bar
+    0    3    8
+    1    4    9
+    """
+
+    impl = get_engine(engine)
+
+    if use_nullable_dtypes is not lib.no_default:
+        msg = (
+            "The argument 'use_nullable_dtypes' is deprecated and will be removed "
+            "in a future version."
+        )
+        if use_nullable_dtypes is True:
+            msg += (
+                "Use dtype_backend='numpy_nullable' instead of use_nullable_dtype=True."
+            )
+        warnings.warn(msg, FutureWarning, stacklevel=find_stack_level())
+    else:
+        use_nullable_dtypes = False
+    check_dtype_backend(dtype_backend)
+
+    return impl.read(
+        path,
+        columns=columns,
+        filters=filters,
+        storage_options=storage_options,
+        use_nullable_dtypes=use_nullable_dtypes,
+        dtype_backend=dtype_backend,
+        filesystem=filesystem,
+        **kwargs,
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..ff11968db15f0f7c6057a46c252a91daee7b9cd9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/__init__.py
@@ -0,0 +1,9 @@
+from pandas.io.parsers.readers import (
+    TextFileReader,
+    TextParser,
+    read_csv,
+    read_fwf,
+    read_table,
+)
+
+__all__ = ["TextFileReader", "TextParser", "read_csv", "read_fwf", "read_table"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/arrow_parser_wrapper.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/arrow_parser_wrapper.py
new file mode 100644
index 0000000000000000000000000000000000000000..7fe5ecb0e54c2394955101ad13079e721123762d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/arrow_parser_wrapper.py
@@ -0,0 +1,295 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+import warnings
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import (
+    ParserError,
+    ParserWarning,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import pandas_dtype
+from pandas.core.dtypes.inference import is_integer
+
+from pandas.io._util import arrow_table_to_pandas
+from pandas.io.parsers.base_parser import ParserBase
+
+if TYPE_CHECKING:
+    from pandas._typing import ReadBuffer
+
+    from pandas import DataFrame
+
+
+class ArrowParserWrapper(ParserBase):
+    """
+    Wrapper for the pyarrow engine for read_csv()
+    """
+
+    def __init__(self, src: ReadBuffer[bytes], **kwds) -> None:
+        super().__init__(kwds)
+        self.kwds = kwds
+        self.src = src
+
+        self._parse_kwds()
+
+    def _parse_kwds(self) -> None:
+        """
+        Validates keywords before passing to pyarrow.
+        """
+        encoding: str | None = self.kwds.get("encoding")
+        self.encoding = "utf-8" if encoding is None else encoding
+
+        na_values = self.kwds["na_values"]
+        if isinstance(na_values, dict):
+            raise ValueError(
+                "The pyarrow engine doesn't support passing a dict for na_values"
+            )
+        self.na_values = list(self.kwds["na_values"])
+
+    def _get_pyarrow_options(self) -> None:
+        """
+        Rename some arguments to pass to pyarrow
+        """
+        mapping = {
+            "usecols": "include_columns",
+            "na_values": "null_values",
+            "escapechar": "escape_char",
+            "skip_blank_lines": "ignore_empty_lines",
+            "decimal": "decimal_point",
+            "quotechar": "quote_char",
+        }
+        for pandas_name, pyarrow_name in mapping.items():
+            if pandas_name in self.kwds and self.kwds.get(pandas_name) is not None:
+                self.kwds[pyarrow_name] = self.kwds.pop(pandas_name)
+
+        # Date format handling
+        # If we get a string, we need to convert it into a list for pyarrow
+        # If we get a dict, we want to parse those separately
+        date_format = self.date_format
+        if isinstance(date_format, str):
+            date_format = [date_format]
+        else:
+            # In case of dict, we don't want to propagate through, so
+            # just set to pyarrow default of None
+
+            # Ideally, in future we disable pyarrow dtype inference (read in as string)
+            # to prevent misreads.
+            date_format = None
+        self.kwds["timestamp_parsers"] = date_format
+
+        self.parse_options = {
+            option_name: option_value
+            for option_name, option_value in self.kwds.items()
+            if option_value is not None
+            and option_name
+            in ("delimiter", "quote_char", "escape_char", "ignore_empty_lines")
+        }
+
+        on_bad_lines = self.kwds.get("on_bad_lines")
+        if on_bad_lines is not None:
+            if callable(on_bad_lines):
+                self.parse_options["invalid_row_handler"] = on_bad_lines
+            elif on_bad_lines == ParserBase.BadLineHandleMethod.ERROR:
+                self.parse_options[
+                    "invalid_row_handler"
+                ] = None  # PyArrow raises an exception by default
+            elif on_bad_lines == ParserBase.BadLineHandleMethod.WARN:
+
+                def handle_warning(invalid_row) -> str:
+                    warnings.warn(
+                        f"Expected {invalid_row.expected_columns} columns, but found "
+                        f"{invalid_row.actual_columns}: {invalid_row.text}",
+                        ParserWarning,
+                        stacklevel=find_stack_level(),
+                    )
+                    return "skip"
+
+                self.parse_options["invalid_row_handler"] = handle_warning
+            elif on_bad_lines == ParserBase.BadLineHandleMethod.SKIP:
+                self.parse_options["invalid_row_handler"] = lambda _: "skip"
+
+        self.convert_options = {
+            option_name: option_value
+            for option_name, option_value in self.kwds.items()
+            if option_value is not None
+            and option_name
+            in (
+                "include_columns",
+                "null_values",
+                "true_values",
+                "false_values",
+                "decimal_point",
+                "timestamp_parsers",
+            )
+        }
+        self.convert_options["strings_can_be_null"] = "" in self.kwds["null_values"]
+        # autogenerated column names are prefixed with 'f' in pyarrow.csv
+        if self.header is None and "include_columns" in self.convert_options:
+            self.convert_options["include_columns"] = [
+                f"f{n}" for n in self.convert_options["include_columns"]
+            ]
+
+        self.read_options = {
+            "autogenerate_column_names": self.header is None,
+            "skip_rows": self.header
+            if self.header is not None
+            else self.kwds["skiprows"],
+            "encoding": self.encoding,
+        }
+
+    def _finalize_pandas_output(self, frame: DataFrame) -> DataFrame:
+        """
+        Processes data read in based on kwargs.
+
+        Parameters
+        ----------
+        frame: DataFrame
+            The DataFrame to process.
+
+        Returns
+        -------
+        DataFrame
+            The processed DataFrame.
+        """
+        num_cols = len(frame.columns)
+        multi_index_named = True
+        if self.header is None:
+            if self.names is None:
+                if self.header is None:
+                    self.names = range(num_cols)
+            if len(self.names) != num_cols:
+                # usecols is passed through to pyarrow, we only handle index col here
+                # The only way self.names is not the same length as number of cols is
+                # if we have int index_col. We should just pad the names(they will get
+                # removed anyways) to expected length then.
+                columns_prefix = [str(x) for x in range(num_cols - len(self.names))]
+                self.names = columns_prefix + self.names
+                multi_index_named = False
+            frame.columns = self.names
+        # we only need the frame not the names
+        _, frame = self._do_date_conversions(frame.columns, frame)
+        if self.index_col is not None:
+            index_to_set = self.index_col.copy()
+            for i, item in enumerate(self.index_col):
+                if is_integer(item):
+                    index_to_set[i] = frame.columns[item]
+                # String case
+                elif item not in frame.columns:
+                    raise ValueError(f"Index {item} invalid")
+
+                # Process dtype for index_col and drop from dtypes
+                if self.dtype is not None:
+                    key, new_dtype = (
+                        (item, self.dtype.get(item))
+                        if self.dtype.get(item) is not None
+                        else (frame.columns[item], self.dtype.get(frame.columns[item]))
+                    )
+                    if new_dtype is not None:
+                        frame[key] = frame[key].astype(new_dtype)
+                        del self.dtype[key]
+
+            frame.set_index(index_to_set, drop=True, inplace=True)
+            # Clear names if headerless and no name given
+            if self.header is None and not multi_index_named:
+                frame.index.names = [None] * len(frame.index.names)
+
+        if self.dtype is not None:
+            # Ignore non-existent columns from dtype mapping
+            # like other parsers do
+            if isinstance(self.dtype, dict):
+                self.dtype = {
+                    k: pandas_dtype(v)
+                    for k, v in self.dtype.items()
+                    if k in frame.columns
+                }
+            else:
+                self.dtype = pandas_dtype(self.dtype)
+            try:
+                frame = frame.astype(self.dtype)
+            except TypeError as e:
+                # GH#44901 reraise to keep api consistent
+                raise ValueError(e)
+        return frame
+
+    def _validate_usecols(self, usecols) -> None:
+        if lib.is_list_like(usecols) and not all(isinstance(x, str) for x in usecols):
+            raise ValueError(
+                "The pyarrow engine does not allow 'usecols' to be integer "
+                "column positions. Pass a list of string column names instead."
+            )
+        elif callable(usecols):
+            raise ValueError(
+                "The pyarrow engine does not allow 'usecols' to be a callable."
+            )
+
+    def read(self) -> DataFrame:
+        """
+        Reads the contents of a CSV file into a DataFrame and
+        processes it according to the kwargs passed in the
+        constructor.
+
+        Returns
+        -------
+        DataFrame
+            The DataFrame created from the CSV file.
+        """
+        pa = import_optional_dependency("pyarrow")
+        pyarrow_csv = import_optional_dependency("pyarrow.csv")
+        self._get_pyarrow_options()
+
+        try:
+            convert_options = pyarrow_csv.ConvertOptions(**self.convert_options)
+        except TypeError:
+            include = self.convert_options.get("include_columns", None)
+            if include is not None:
+                self._validate_usecols(include)
+
+            nulls = self.convert_options.get("null_values", set())
+            if not lib.is_list_like(nulls) or not all(
+                isinstance(x, str) for x in nulls
+            ):
+                raise TypeError(
+                    "The 'pyarrow' engine requires all na_values to be strings"
+                )
+
+            raise
+
+        try:
+            table = pyarrow_csv.read_csv(
+                self.src,
+                read_options=pyarrow_csv.ReadOptions(**self.read_options),
+                parse_options=pyarrow_csv.ParseOptions(**self.parse_options),
+                convert_options=convert_options,
+            )
+        except pa.ArrowInvalid as e:
+            raise ParserError(e) from e
+
+        dtype_backend = self.kwds["dtype_backend"]
+
+        # Convert all pa.null() cols -> float64 (non nullable)
+        # else Int64 (nullable case, see below)
+        if dtype_backend is lib.no_default:
+            new_schema = table.schema
+            new_type = pa.float64()
+            for i, arrow_type in enumerate(table.schema.types):
+                if pa.types.is_null(arrow_type):
+                    new_schema = new_schema.set(
+                        i, new_schema.field(i).with_type(new_type)
+                    )
+
+            table = table.cast(new_schema)
+
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                "make_block is deprecated",
+                DeprecationWarning,
+            )
+            frame = arrow_table_to_pandas(
+                table, dtype_backend=dtype_backend, null_to_int64=True
+            )
+
+        return self._finalize_pandas_output(frame)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/base_parser.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/base_parser.py
new file mode 100644
index 0000000000000000000000000000000000000000..40e3ea645064785a965783b2a86ef10b282a7045
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/base_parser.py
@@ -0,0 +1,1462 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from copy import copy
+import csv
+import datetime
+from enum import Enum
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    cast,
+    final,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    parsers,
+)
+import pandas._libs.ops as libops
+from pandas._libs.parsers import STR_NA_VALUES
+from pandas._libs.tslibs import parsing
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import (
+    ParserError,
+    ParserWarning,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.astype import astype_array
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_bool_dtype,
+    is_dict_like,
+    is_extension_array_dtype,
+    is_float_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_list_like,
+    is_object_dtype,
+    is_scalar,
+    is_string_dtype,
+    pandas_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.missing import isna
+
+from pandas import (
+    ArrowDtype,
+    DataFrame,
+    DatetimeIndex,
+    StringDtype,
+    concat,
+)
+from pandas.core import algorithms
+from pandas.core.arrays import (
+    ArrowExtensionArray,
+    BaseMaskedArray,
+    BooleanArray,
+    Categorical,
+    ExtensionArray,
+    FloatingArray,
+    IntegerArray,
+)
+from pandas.core.arrays.boolean import BooleanDtype
+from pandas.core.indexes.api import (
+    Index,
+    MultiIndex,
+    default_index,
+    ensure_index_from_sequences,
+)
+from pandas.core.series import Series
+from pandas.core.tools import datetimes as tools
+
+from pandas.io.common import is_potential_multi_index
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Mapping,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        DtypeArg,
+        DtypeObj,
+        Scalar,
+    )
+
+
+class ParserBase:
+    class BadLineHandleMethod(Enum):
+        ERROR = 0
+        WARN = 1
+        SKIP = 2
+
+    _implicit_index: bool
+    _first_chunk: bool
+    keep_default_na: bool
+    dayfirst: bool
+    cache_dates: bool
+    keep_date_col: bool
+    usecols_dtype: str | None
+
+    def __init__(self, kwds) -> None:
+        self._implicit_index = False
+
+        self.names = kwds.get("names")
+        self.orig_names: Sequence[Hashable] | None = None
+
+        self.index_col = kwds.get("index_col", None)
+        self.unnamed_cols: set = set()
+        self.index_names: Sequence[Hashable] | None = None
+        self.col_names: Sequence[Hashable] | None = None
+
+        self.parse_dates = _validate_parse_dates_arg(kwds.pop("parse_dates", False))
+        self._parse_date_cols: Iterable = []
+        self.date_parser = kwds.pop("date_parser", lib.no_default)
+        self.date_format = kwds.pop("date_format", None)
+        self.dayfirst = kwds.pop("dayfirst", False)
+        self.keep_date_col = kwds.pop("keep_date_col", False)
+
+        self.na_values = kwds.get("na_values")
+        self.na_fvalues = kwds.get("na_fvalues")
+        self.na_filter = kwds.get("na_filter", False)
+        self.keep_default_na = kwds.get("keep_default_na", True)
+
+        self.dtype = copy(kwds.get("dtype", None))
+        self.converters = kwds.get("converters")
+        self.dtype_backend = kwds.get("dtype_backend")
+
+        self.true_values = kwds.get("true_values")
+        self.false_values = kwds.get("false_values")
+        self.cache_dates = kwds.pop("cache_dates", True)
+
+        self._date_conv = _make_date_converter(
+            date_parser=self.date_parser,
+            date_format=self.date_format,
+            dayfirst=self.dayfirst,
+            cache_dates=self.cache_dates,
+        )
+
+        # validate header options for mi
+        self.header = kwds.get("header")
+        if is_list_like(self.header, allow_sets=False):
+            if kwds.get("usecols"):
+                raise ValueError(
+                    "cannot specify usecols when specifying a multi-index header"
+                )
+            if kwds.get("names"):
+                raise ValueError(
+                    "cannot specify names when specifying a multi-index header"
+                )
+
+            # validate index_col that only contains integers
+            if self.index_col is not None:
+                # In this case we can pin down index_col as list[int]
+                if is_integer(self.index_col):
+                    self.index_col = [self.index_col]
+                elif not (
+                    is_list_like(self.index_col, allow_sets=False)
+                    and all(map(is_integer, self.index_col))
+                ):
+                    raise ValueError(
+                        "index_col must only contain row numbers "
+                        "when specifying a multi-index header"
+                    )
+                else:
+                    self.index_col = list(self.index_col)
+
+        self._name_processed = False
+
+        self._first_chunk = True
+
+        self.usecols, self.usecols_dtype = self._validate_usecols_arg(kwds["usecols"])
+
+        # Fallback to error to pass a sketchy test(test_override_set_noconvert_columns)
+        # Normally, this arg would get pre-processed earlier on
+        self.on_bad_lines = kwds.get("on_bad_lines", self.BadLineHandleMethod.ERROR)
+
+    def _validate_parse_dates_presence(self, columns: Sequence[Hashable]) -> Iterable:
+        """
+        Check if parse_dates are in columns.
+
+        If user has provided names for parse_dates, check if those columns
+        are available.
+
+        Parameters
+        ----------
+        columns : list
+            List of names of the dataframe.
+
+        Returns
+        -------
+        The names of the columns which will get parsed later if a dict or list
+        is given as specification.
+
+        Raises
+        ------
+        ValueError
+            If column to parse_date is not in dataframe.
+
+        """
+        cols_needed: Iterable
+        if is_dict_like(self.parse_dates):
+            cols_needed = itertools.chain(*self.parse_dates.values())
+        elif is_list_like(self.parse_dates):
+            # a column in parse_dates could be represented
+            # ColReference = Union[int, str]
+            # DateGroups = List[ColReference]
+            # ParseDates = Union[DateGroups, List[DateGroups],
+            #     Dict[ColReference, DateGroups]]
+            cols_needed = itertools.chain.from_iterable(
+                col if is_list_like(col) and not isinstance(col, tuple) else [col]
+                for col in self.parse_dates
+            )
+        else:
+            cols_needed = []
+
+        cols_needed = list(cols_needed)
+
+        # get only columns that are references using names (str), not by index
+        missing_cols = ", ".join(
+            sorted(
+                {
+                    col
+                    for col in cols_needed
+                    if isinstance(col, str) and col not in columns
+                }
+            )
+        )
+        if missing_cols:
+            raise ValueError(
+                f"Missing column provided to 'parse_dates': '{missing_cols}'"
+            )
+        # Convert positions to actual column names
+        return [
+            col if (isinstance(col, str) or col in columns) else columns[col]
+            for col in cols_needed
+        ]
+
+    def close(self) -> None:
+        pass
+
+    @final
+    @property
+    def _has_complex_date_col(self) -> bool:
+        return isinstance(self.parse_dates, dict) or (
+            isinstance(self.parse_dates, list)
+            and len(self.parse_dates) > 0
+            and isinstance(self.parse_dates[0], list)
+        )
+
+    @final
+    def _should_parse_dates(self, i: int) -> bool:
+        if lib.is_bool(self.parse_dates):
+            return bool(self.parse_dates)
+        else:
+            if self.index_names is not None:
+                name = self.index_names[i]
+            else:
+                name = None
+            j = i if self.index_col is None else self.index_col[i]
+
+            return (j in self.parse_dates) or (
+                name is not None and name in self.parse_dates
+            )
+
+    @final
+    def _extract_multi_indexer_columns(
+        self,
+        header,
+        index_names: Sequence[Hashable] | None,
+        passed_names: bool = False,
+    ) -> tuple[
+        Sequence[Hashable], Sequence[Hashable] | None, Sequence[Hashable] | None, bool
+    ]:
+        """
+        Extract and return the names, index_names, col_names if the column
+        names are a MultiIndex.
+
+        Parameters
+        ----------
+        header: list of lists
+            The header rows
+        index_names: list, optional
+            The names of the future index
+        passed_names: bool, default False
+            A flag specifying if names where passed
+
+        """
+        if len(header) < 2:
+            return header[0], index_names, None, passed_names
+
+        # the names are the tuples of the header that are not the index cols
+        # 0 is the name of the index, assuming index_col is a list of column
+        # numbers
+        ic = self.index_col
+        if ic is None:
+            ic = []
+
+        if not isinstance(ic, (list, tuple, np.ndarray)):
+            ic = [ic]
+        sic = set(ic)
+
+        # clean the index_names
+        index_names = header.pop(-1)
+        index_names, _, _ = self._clean_index_names(index_names, self.index_col)
+
+        # extract the columns
+        field_count = len(header[0])
+
+        # check if header lengths are equal
+        if not all(len(header_iter) == field_count for header_iter in header[1:]):
+            raise ParserError("Header rows must have an equal number of columns.")
+
+        def extract(r):
+            return tuple(r[i] for i in range(field_count) if i not in sic)
+
+        columns = list(zip(*(extract(r) for r in header)))
+        names = columns.copy()
+        for single_ic in sorted(ic):
+            names.insert(single_ic, single_ic)
+
+        # Clean the column names (if we have an index_col).
+        if len(ic):
+            col_names = [
+                r[ic[0]]
+                if ((r[ic[0]] is not None) and r[ic[0]] not in self.unnamed_cols)
+                else None
+                for r in header
+            ]
+        else:
+            col_names = [None] * len(header)
+
+        passed_names = True
+
+        return names, index_names, col_names, passed_names
+
+    @final
+    def _maybe_make_multi_index_columns(
+        self,
+        columns: Sequence[Hashable],
+        col_names: Sequence[Hashable] | None = None,
+    ) -> Sequence[Hashable] | MultiIndex:
+        # possibly create a column mi here
+        if is_potential_multi_index(columns):
+            list_columns = cast(list[tuple], columns)
+            return MultiIndex.from_tuples(list_columns, names=col_names)
+        return columns
+
+    @final
+    def _make_index(
+        self, data, alldata, columns, indexnamerow: list[Scalar] | None = None
+    ) -> tuple[Index | None, Sequence[Hashable] | MultiIndex]:
+        index: Index | None
+        if not is_index_col(self.index_col) or not self.index_col:
+            index = None
+
+        elif not self._has_complex_date_col:
+            simple_index = self._get_simple_index(alldata, columns)
+            index = self._agg_index(simple_index)
+        elif self._has_complex_date_col:
+            if not self._name_processed:
+                (self.index_names, _, self.index_col) = self._clean_index_names(
+                    list(columns), self.index_col
+                )
+                self._name_processed = True
+            date_index = self._get_complex_date_index(data, columns)
+            index = self._agg_index(date_index, try_parse_dates=False)
+
+        # add names for the index
+        if indexnamerow:
+            coffset = len(indexnamerow) - len(columns)
+            assert index is not None
+            index = index.set_names(indexnamerow[:coffset])
+
+        # maybe create a mi on the columns
+        columns = self._maybe_make_multi_index_columns(columns, self.col_names)
+
+        return index, columns
+
+    @final
+    def _get_simple_index(self, data, columns):
+        def ix(col):
+            if not isinstance(col, str):
+                return col
+            raise ValueError(f"Index {col} invalid")
+
+        to_remove = []
+        index = []
+        for idx in self.index_col:
+            i = ix(idx)
+            to_remove.append(i)
+            index.append(data[i])
+
+        # remove index items from content and columns, don't pop in
+        # loop
+        for i in sorted(to_remove, reverse=True):
+            data.pop(i)
+            if not self._implicit_index:
+                columns.pop(i)
+
+        return index
+
+    @final
+    def _get_complex_date_index(self, data, col_names):
+        def _get_name(icol):
+            if isinstance(icol, str):
+                return icol
+
+            if col_names is None:
+                raise ValueError(f"Must supply column order to use {icol!s} as index")
+
+            for i, c in enumerate(col_names):
+                if i == icol:
+                    return c
+
+        to_remove = []
+        index = []
+        for idx in self.index_col:
+            name = _get_name(idx)
+            to_remove.append(name)
+            index.append(data[name])
+
+        # remove index items from content and columns, don't pop in
+        # loop
+        for c in sorted(to_remove, reverse=True):
+            data.pop(c)
+            col_names.remove(c)
+
+        return index
+
+    @final
+    def _clean_mapping(self, mapping):
+        """converts col numbers to names"""
+        if not isinstance(mapping, dict):
+            return mapping
+        clean = {}
+        # for mypy
+        assert self.orig_names is not None
+
+        for col, v in mapping.items():
+            if isinstance(col, int) and col not in self.orig_names:
+                col = self.orig_names[col]
+            clean[col] = v
+        if isinstance(mapping, defaultdict):
+            remaining_cols = set(self.orig_names) - set(clean.keys())
+            clean.update({col: mapping[col] for col in remaining_cols})
+        return clean
+
+    @final
+    def _agg_index(self, index, try_parse_dates: bool = True) -> Index:
+        arrays = []
+        converters = self._clean_mapping(self.converters)
+
+        if self.index_names is not None:
+            names: Iterable = self.index_names
+        else:
+            names = itertools.cycle([None])
+        for i, (arr, name) in enumerate(zip(index, names)):
+            if try_parse_dates and self._should_parse_dates(i):
+                arr = self._date_conv(
+                    arr,
+                    col=self.index_names[i] if self.index_names is not None else None,
+                )
+
+            if self.na_filter:
+                col_na_values = self.na_values
+                col_na_fvalues = self.na_fvalues
+            else:
+                col_na_values = set()
+                col_na_fvalues = set()
+
+            if isinstance(self.na_values, dict):
+                assert self.index_names is not None
+                col_name = self.index_names[i]
+                if col_name is not None:
+                    col_na_values, col_na_fvalues = _get_na_values(
+                        col_name, self.na_values, self.na_fvalues, self.keep_default_na
+                    )
+
+            clean_dtypes = self._clean_mapping(self.dtype)
+
+            cast_type = None
+            index_converter = False
+            if self.index_names is not None:
+                if isinstance(clean_dtypes, dict):
+                    cast_type = clean_dtypes.get(self.index_names[i], None)
+
+                if isinstance(converters, dict):
+                    index_converter = converters.get(self.index_names[i]) is not None
+
+            try_num_bool = not (
+                cast_type and is_string_dtype(cast_type) or index_converter
+            )
+
+            arr, _ = self._infer_types(
+                arr, col_na_values | col_na_fvalues, cast_type is None, try_num_bool
+            )
+            if cast_type is not None:
+                # Don't perform RangeIndex inference
+                idx = Index(arr, name=name, dtype=cast_type)
+            else:
+                idx = ensure_index_from_sequences([arr], [name])
+            arrays.append(idx)
+
+        if len(arrays) == 1:
+            return arrays[0]
+        else:
+            return MultiIndex.from_arrays(arrays)
+
+    @final
+    def _convert_to_ndarrays(
+        self,
+        dct: Mapping,
+        na_values,
+        na_fvalues,
+        verbose: bool = False,
+        converters=None,
+        dtypes=None,
+    ):
+        result = {}
+        for c, values in dct.items():
+            conv_f = None if converters is None else converters.get(c, None)
+            if isinstance(dtypes, dict):
+                cast_type = dtypes.get(c, None)
+            else:
+                # single dtype or None
+                cast_type = dtypes
+
+            if self.na_filter:
+                col_na_values, col_na_fvalues = _get_na_values(
+                    c, na_values, na_fvalues, self.keep_default_na
+                )
+            else:
+                col_na_values, col_na_fvalues = set(), set()
+
+            if c in self._parse_date_cols:
+                # GH#26203 Do not convert columns which get converted to dates
+                # but replace nans to ensure to_datetime works
+                mask = algorithms.isin(values, set(col_na_values) | col_na_fvalues)
+                np.putmask(values, mask, np.nan)
+                result[c] = values
+                continue
+
+            if conv_f is not None:
+                # conv_f applied to data before inference
+                if cast_type is not None:
+                    warnings.warn(
+                        (
+                            "Both a converter and dtype were specified "
+                            f"for column {c} - only the converter will be used."
+                        ),
+                        ParserWarning,
+                        stacklevel=find_stack_level(),
+                    )
+
+                try:
+                    values = lib.map_infer(values, conv_f)
+                except ValueError:
+                    mask = algorithms.isin(values, list(na_values)).view(np.uint8)
+                    values = lib.map_infer_mask(values, conv_f, mask)
+
+                cvals, na_count = self._infer_types(
+                    values,
+                    set(col_na_values) | col_na_fvalues,
+                    cast_type is None,
+                    try_num_bool=False,
+                )
+            else:
+                is_ea = is_extension_array_dtype(cast_type)
+                is_str_or_ea_dtype = is_ea or is_string_dtype(cast_type)
+                # skip inference if specified dtype is object
+                # or casting to an EA
+                try_num_bool = not (cast_type and is_str_or_ea_dtype)
+
+                # general type inference and conversion
+                cvals, na_count = self._infer_types(
+                    values,
+                    set(col_na_values) | col_na_fvalues,
+                    cast_type is None,
+                    try_num_bool,
+                )
+
+                # type specified in dtype param or cast_type is an EA
+                if cast_type is not None:
+                    cast_type = pandas_dtype(cast_type)
+                if cast_type and (cvals.dtype != cast_type or is_ea):
+                    if not is_ea and na_count > 0:
+                        if is_bool_dtype(cast_type):
+                            raise ValueError(f"Bool column has NA values in column {c}")
+                    cvals = self._cast_types(cvals, cast_type, c)
+
+            result[c] = cvals
+            if verbose and na_count:
+                print(f"Filled {na_count} NA values in column {c!s}")
+        return result
+
+    @final
+    def _set_noconvert_dtype_columns(
+        self, col_indices: list[int], names: Sequence[Hashable]
+    ) -> set[int]:
+        """
+        Set the columns that should not undergo dtype conversions.
+
+        Currently, any column that is involved with date parsing will not
+        undergo such conversions. If usecols is specified, the positions of the columns
+        not to cast is relative to the usecols not to all columns.
+
+        Parameters
+        ----------
+        col_indices: The indices specifying order and positions of the columns
+        names: The column names which order is corresponding with the order
+               of col_indices
+
+        Returns
+        -------
+        A set of integers containing the positions of the columns not to convert.
+        """
+        usecols: list[int] | list[str] | None
+        noconvert_columns = set()
+        if self.usecols_dtype == "integer":
+            # A set of integers will be converted to a list in
+            # the correct order every single time.
+            usecols = sorted(self.usecols)
+        elif callable(self.usecols) or self.usecols_dtype not in ("empty", None):
+            # The names attribute should have the correct columns
+            # in the proper order for indexing with parse_dates.
+            usecols = col_indices
+        else:
+            # Usecols is empty.
+            usecols = None
+
+        def _set(x) -> int:
+            if usecols is not None and is_integer(x):
+                x = usecols[x]
+
+            if not is_integer(x):
+                x = col_indices[names.index(x)]
+
+            return x
+
+        if isinstance(self.parse_dates, list):
+            for val in self.parse_dates:
+                if isinstance(val, list):
+                    for k in val:
+                        noconvert_columns.add(_set(k))
+                else:
+                    noconvert_columns.add(_set(val))
+
+        elif isinstance(self.parse_dates, dict):
+            for val in self.parse_dates.values():
+                if isinstance(val, list):
+                    for k in val:
+                        noconvert_columns.add(_set(k))
+                else:
+                    noconvert_columns.add(_set(val))
+
+        elif self.parse_dates:
+            if isinstance(self.index_col, list):
+                for k in self.index_col:
+                    noconvert_columns.add(_set(k))
+            elif self.index_col is not None:
+                noconvert_columns.add(_set(self.index_col))
+
+        return noconvert_columns
+
+    @final
+    def _infer_types(
+        self, values, na_values, no_dtype_specified, try_num_bool: bool = True
+    ) -> tuple[ArrayLike, int]:
+        """
+        Infer types of values, possibly casting
+
+        Parameters
+        ----------
+        values : ndarray
+        na_values : set
+        no_dtype_specified: Specifies if we want to cast explicitly
+        try_num_bool : bool, default try
+           try to cast values to numeric (first preference) or boolean
+
+        Returns
+        -------
+        converted : ndarray or ExtensionArray
+        na_count : int
+        """
+        na_count = 0
+        if issubclass(values.dtype.type, (np.number, np.bool_)):
+            # If our array has numeric dtype, we don't have to check for strings in isin
+            na_values = np.array([val for val in na_values if not isinstance(val, str)])
+            mask = algorithms.isin(values, na_values)
+            na_count = mask.astype("uint8", copy=False).sum()
+            if na_count > 0:
+                if is_integer_dtype(values):
+                    values = values.astype(np.float64)
+                np.putmask(values, mask, np.nan)
+            return values, na_count
+
+        dtype_backend = self.dtype_backend
+        non_default_dtype_backend = (
+            no_dtype_specified and dtype_backend is not lib.no_default
+        )
+        result: ArrayLike
+
+        if try_num_bool and is_object_dtype(values.dtype):
+            # exclude e.g DatetimeIndex here
+            try:
+                result, result_mask = lib.maybe_convert_numeric(
+                    values,
+                    na_values,
+                    False,
+                    convert_to_masked_nullable=non_default_dtype_backend,  # type: ignore[arg-type]
+                )
+            except (ValueError, TypeError):
+                # e.g. encountering datetime string gets ValueError
+                #  TypeError can be raised in floatify
+                na_count = parsers.sanitize_objects(values, na_values)
+                result = values
+            else:
+                if non_default_dtype_backend:
+                    if result_mask is None:
+                        result_mask = np.zeros(result.shape, dtype=np.bool_)
+
+                    if result_mask.all():
+                        result = IntegerArray(
+                            np.ones(result_mask.shape, dtype=np.int64), result_mask
+                        )
+                    elif is_integer_dtype(result):
+                        result = IntegerArray(result, result_mask)
+                    elif is_bool_dtype(result):
+                        result = BooleanArray(result, result_mask)
+                    elif is_float_dtype(result):
+                        result = FloatingArray(result, result_mask)
+
+                    na_count = result_mask.sum()
+                else:
+                    na_count = isna(result).sum()
+        else:
+            result = values
+            if values.dtype == np.object_:
+                na_count = parsers.sanitize_objects(values, na_values)
+
+        if result.dtype == np.object_ and try_num_bool:
+            result, bool_mask = libops.maybe_convert_bool(
+                np.asarray(values),
+                true_values=self.true_values,
+                false_values=self.false_values,
+                convert_to_masked_nullable=non_default_dtype_backend,  # type: ignore[arg-type]
+            )
+            if result.dtype == np.bool_ and non_default_dtype_backend:
+                if bool_mask is None:
+                    bool_mask = np.zeros(result.shape, dtype=np.bool_)
+                result = BooleanArray(result, bool_mask)
+            elif result.dtype == np.object_ and non_default_dtype_backend:
+                # read_excel sends array of datetime objects
+                if not lib.is_datetime_array(result, skipna=True):
+                    dtype = StringDtype()
+                    cls = dtype.construct_array_type()
+                    result = cls._from_sequence(values, dtype=dtype)
+
+        if dtype_backend == "pyarrow":
+            pa = import_optional_dependency("pyarrow")
+            if isinstance(result, np.ndarray):
+                result = ArrowExtensionArray(pa.array(result, from_pandas=True))
+            elif isinstance(result, BaseMaskedArray):
+                if result._mask.all():
+                    # We want an arrow null array here
+                    result = ArrowExtensionArray(pa.array([None] * len(result)))
+                else:
+                    result = ArrowExtensionArray(
+                        pa.array(result._data, mask=result._mask)
+                    )
+            else:
+                result = ArrowExtensionArray(
+                    pa.array(result.to_numpy(), from_pandas=True)
+                )
+
+        return result, na_count
+
+    @final
+    def _cast_types(self, values: ArrayLike, cast_type: DtypeObj, column) -> ArrayLike:
+        """
+        Cast values to specified type
+
+        Parameters
+        ----------
+        values : ndarray or ExtensionArray
+        cast_type : np.dtype or ExtensionDtype
+           dtype to cast values to
+        column : string
+            column name - used only for error reporting
+
+        Returns
+        -------
+        converted : ndarray or ExtensionArray
+        """
+        if isinstance(cast_type, CategoricalDtype):
+            known_cats = cast_type.categories is not None
+
+            if not is_object_dtype(values.dtype) and not known_cats:
+                # TODO: this is for consistency with
+                # c-parser which parses all categories
+                # as strings
+                values = lib.ensure_string_array(
+                    values, skipna=False, convert_na_value=False
+                )
+
+            cats = Index(values).unique().dropna()
+            values = Categorical._from_inferred_categories(
+                cats, cats.get_indexer(values), cast_type, true_values=self.true_values
+            )
+
+        # use the EA's implementation of casting
+        elif isinstance(cast_type, ExtensionDtype):
+            array_type = cast_type.construct_array_type()
+            try:
+                if isinstance(cast_type, BooleanDtype):
+                    # error: Unexpected keyword argument "true_values" for
+                    # "_from_sequence_of_strings" of "ExtensionArray"
+                    return array_type._from_sequence_of_strings(  # type: ignore[call-arg]
+                        values,
+                        dtype=cast_type,
+                        true_values=self.true_values,
+                        false_values=self.false_values,
+                    )
+                else:
+                    return array_type._from_sequence_of_strings(values, dtype=cast_type)
+            except NotImplementedError as err:
+                raise NotImplementedError(
+                    f"Extension Array: {array_type} must implement "
+                    "_from_sequence_of_strings in order to be used in parser methods"
+                ) from err
+
+        elif isinstance(values, ExtensionArray):
+            values = values.astype(cast_type, copy=False)
+        elif issubclass(cast_type.type, str):
+            # TODO: why skipna=True here and False above? some tests depend
+            #  on it here, but nothing fails if we change it above
+            #  (as no tests get there as of 2022-12-06)
+            values = lib.ensure_string_array(
+                values, skipna=True, convert_na_value=False
+            )
+        else:
+            try:
+                values = astype_array(values, cast_type, copy=True)
+            except ValueError as err:
+                raise ValueError(
+                    f"Unable to convert column {column} to type {cast_type}"
+                ) from err
+        return values
+
+    @overload
+    def _do_date_conversions(
+        self,
+        names: Index,
+        data: DataFrame,
+    ) -> tuple[Sequence[Hashable] | Index, DataFrame]:
+        ...
+
+    @overload
+    def _do_date_conversions(
+        self,
+        names: Sequence[Hashable],
+        data: Mapping[Hashable, ArrayLike],
+    ) -> tuple[Sequence[Hashable], Mapping[Hashable, ArrayLike]]:
+        ...
+
+    @final
+    def _do_date_conversions(
+        self,
+        names: Sequence[Hashable] | Index,
+        data: Mapping[Hashable, ArrayLike] | DataFrame,
+    ) -> tuple[Sequence[Hashable] | Index, Mapping[Hashable, ArrayLike] | DataFrame]:
+        # returns data, columns
+
+        if self.parse_dates is not None:
+            data, names = _process_date_conversion(
+                data,
+                self._date_conv,
+                self.parse_dates,
+                self.index_col,
+                self.index_names,
+                names,
+                keep_date_col=self.keep_date_col,
+                dtype_backend=self.dtype_backend,
+            )
+
+        return names, data
+
+    @final
+    def _check_data_length(
+        self,
+        columns: Sequence[Hashable],
+        data: Sequence[ArrayLike],
+    ) -> None:
+        """Checks if length of data is equal to length of column names.
+
+        One set of trailing commas is allowed. self.index_col not False
+        results in a ParserError previously when lengths do not match.
+
+        Parameters
+        ----------
+        columns: list of column names
+        data: list of array-likes containing the data column-wise.
+        """
+        if not self.index_col and len(columns) != len(data) and columns:
+            empty_str = is_object_dtype(data[-1]) and data[-1] == ""
+            # error: No overload variant of "__ror__" of "ndarray" matches
+            # argument type "ExtensionArray"
+            empty_str_or_na = empty_str | isna(data[-1])  # type: ignore[operator]
+            if len(columns) == len(data) - 1 and np.all(empty_str_or_na):
+                return
+            warnings.warn(
+                "Length of header or names does not match length of data. This leads "
+                "to a loss of data with index_col=False.",
+                ParserWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    @overload
+    def _evaluate_usecols(
+        self,
+        usecols: set[int] | Callable[[Hashable], object],
+        names: Sequence[Hashable],
+    ) -> set[int]:
+        ...
+
+    @overload
+    def _evaluate_usecols(
+        self, usecols: set[str], names: Sequence[Hashable]
+    ) -> set[str]:
+        ...
+
+    @final
+    def _evaluate_usecols(
+        self,
+        usecols: Callable[[Hashable], object] | set[str] | set[int],
+        names: Sequence[Hashable],
+    ) -> set[str] | set[int]:
+        """
+        Check whether or not the 'usecols' parameter
+        is a callable.  If so, enumerates the 'names'
+        parameter and returns a set of indices for
+        each entry in 'names' that evaluates to True.
+        If not a callable, returns 'usecols'.
+        """
+        if callable(usecols):
+            return {i for i, name in enumerate(names) if usecols(name)}
+        return usecols
+
+    @final
+    def _validate_usecols_names(self, usecols, names: Sequence):
+        """
+        Validates that all usecols are present in a given
+        list of names. If not, raise a ValueError that
+        shows what usecols are missing.
+
+        Parameters
+        ----------
+        usecols : iterable of usecols
+            The columns to validate are present in names.
+        names : iterable of names
+            The column names to check against.
+
+        Returns
+        -------
+        usecols : iterable of usecols
+            The `usecols` parameter if the validation succeeds.
+
+        Raises
+        ------
+        ValueError : Columns were missing. Error message will list them.
+        """
+        missing = [c for c in usecols if c not in names]
+        if len(missing) > 0:
+            raise ValueError(
+                f"Usecols do not match columns, columns expected but not found: "
+                f"{missing}"
+            )
+
+        return usecols
+
+    @final
+    def _validate_usecols_arg(self, usecols):
+        """
+        Validate the 'usecols' parameter.
+
+        Checks whether or not the 'usecols' parameter contains all integers
+        (column selection by index), strings (column by name) or is a callable.
+        Raises a ValueError if that is not the case.
+
+        Parameters
+        ----------
+        usecols : list-like, callable, or None
+            List of columns to use when parsing or a callable that can be used
+            to filter a list of table columns.
+
+        Returns
+        -------
+        usecols_tuple : tuple
+            A tuple of (verified_usecols, usecols_dtype).
+
+            'verified_usecols' is either a set if an array-like is passed in or
+            'usecols' if a callable or None is passed in.
+
+            'usecols_dtype` is the inferred dtype of 'usecols' if an array-like
+            is passed in or None if a callable or None is passed in.
+        """
+        msg = (
+            "'usecols' must either be list-like of all strings, all unicode, "
+            "all integers or a callable."
+        )
+        if usecols is not None:
+            if callable(usecols):
+                return usecols, None
+
+            if not is_list_like(usecols):
+                # see gh-20529
+                #
+                # Ensure it is iterable container but not string.
+                raise ValueError(msg)
+
+            usecols_dtype = lib.infer_dtype(usecols, skipna=False)
+
+            if usecols_dtype not in ("empty", "integer", "string"):
+                raise ValueError(msg)
+
+            usecols = set(usecols)
+
+            return usecols, usecols_dtype
+        return usecols, None
+
+    @final
+    def _clean_index_names(self, columns, index_col) -> tuple[list | None, list, list]:
+        if not is_index_col(index_col):
+            return None, columns, index_col
+
+        columns = list(columns)
+
+        # In case of no rows and multiindex columns we have to set index_names to
+        # list of Nones GH#38292
+        if not columns:
+            return [None] * len(index_col), columns, index_col
+
+        cp_cols = list(columns)
+        index_names: list[str | int | None] = []
+
+        # don't mutate
+        index_col = list(index_col)
+
+        for i, c in enumerate(index_col):
+            if isinstance(c, str):
+                index_names.append(c)
+                for j, name in enumerate(cp_cols):
+                    if name == c:
+                        index_col[i] = j
+                        columns.remove(name)
+                        break
+            else:
+                name = cp_cols[c]
+                columns.remove(name)
+                index_names.append(name)
+
+        # Only clean index names that were placeholders.
+        for i, name in enumerate(index_names):
+            if isinstance(name, str) and name in self.unnamed_cols:
+                index_names[i] = None
+
+        return index_names, columns, index_col
+
+    @final
+    def _get_empty_meta(self, columns, dtype: DtypeArg | None = None):
+        columns = list(columns)
+
+        index_col = self.index_col
+        index_names = self.index_names
+
+        # Convert `dtype` to a defaultdict of some kind.
+        # This will enable us to write `dtype[col_name]`
+        # without worrying about KeyError issues later on.
+        dtype_dict: defaultdict[Hashable, Any]
+        if not is_dict_like(dtype):
+            # if dtype == None, default will be object.
+            dtype_dict = defaultdict(lambda: dtype)
+        else:
+            dtype = cast(dict, dtype)
+            dtype_dict = defaultdict(
+                lambda: None,
+                {columns[k] if is_integer(k) else k: v for k, v in dtype.items()},
+            )
+
+        # Even though we have no data, the "index" of the empty DataFrame
+        # could for example still be an empty MultiIndex. Thus, we need to
+        # check whether we have any index columns specified, via either:
+        #
+        # 1) index_col (column indices)
+        # 2) index_names (column names)
+        #
+        # Both must be non-null to ensure a successful construction. Otherwise,
+        # we have to create a generic empty Index.
+        index: Index
+        if (index_col is None or index_col is False) or index_names is None:
+            index = default_index(0)
+        else:
+            # TODO: We could return default_index(0) if dtype_dict[name] is None
+            data = [
+                Index([], name=name, dtype=dtype_dict[name]) for name in index_names
+            ]
+            if len(data) == 1:
+                index = data[0]
+            else:
+                index = MultiIndex.from_arrays(data)
+            index_col.sort()
+
+            for i, n in enumerate(index_col):
+                columns.pop(n - i)
+
+        col_dict = {
+            col_name: Series([], dtype=dtype_dict[col_name]) for col_name in columns
+        }
+
+        return index, columns, col_dict
+
+
+def _make_date_converter(
+    date_parser=lib.no_default,
+    dayfirst: bool = False,
+    cache_dates: bool = True,
+    date_format: dict[Hashable, str] | str | None = None,
+):
+    if date_parser is not lib.no_default:
+        warnings.warn(
+            "The argument 'date_parser' is deprecated and will "
+            "be removed in a future version. "
+            "Please use 'date_format' instead, or read your data in as 'object' dtype "
+            "and then call 'to_datetime'.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    if date_parser is not lib.no_default and date_format is not None:
+        raise TypeError("Cannot use both 'date_parser' and 'date_format'")
+
+    def unpack_if_single_element(arg):
+        # NumPy 1.25 deprecation: https://github.com/numpy/numpy/pull/10615
+        if isinstance(arg, np.ndarray) and arg.ndim == 1 and len(arg) == 1:
+            return arg[0]
+        return arg
+
+    def converter(*date_cols, col: Hashable):
+        if len(date_cols) == 1 and date_cols[0].dtype.kind in "Mm":
+            return date_cols[0]
+
+        if date_parser is lib.no_default:
+            strs = parsing.concat_date_cols(date_cols)
+            date_fmt = (
+                date_format.get(col) if isinstance(date_format, dict) else date_format
+            )
+
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore",
+                    ".*parsing datetimes with mixed time zones will raise an error",
+                    category=FutureWarning,
+                )
+                str_objs = ensure_object(strs)
+                try:
+                    result = tools.to_datetime(
+                        str_objs,
+                        format=date_fmt,
+                        utc=False,
+                        dayfirst=dayfirst,
+                        cache=cache_dates,
+                    )
+                except (ValueError, TypeError):
+                    # test_usecols_with_parse_dates4
+                    return str_objs
+
+            if isinstance(result, DatetimeIndex):
+                arr = result.to_numpy()
+                arr.flags.writeable = True
+                return arr
+            return result._values
+        else:
+            try:
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore",
+                        ".*parsing datetimes with mixed time zones "
+                        "will raise an error",
+                        category=FutureWarning,
+                    )
+                    pre_parsed = date_parser(
+                        *(unpack_if_single_element(arg) for arg in date_cols)
+                    )
+                    try:
+                        result = tools.to_datetime(
+                            pre_parsed,
+                            cache=cache_dates,
+                        )
+                    except (ValueError, TypeError):
+                        # test_read_csv_with_custom_date_parser
+                        result = pre_parsed
+                if isinstance(result, datetime.datetime):
+                    raise Exception("scalar parser")
+                return result
+            except Exception:
+                # e.g. test_datetime_fractional_seconds
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore",
+                        ".*parsing datetimes with mixed time zones "
+                        "will raise an error",
+                        category=FutureWarning,
+                    )
+                    pre_parsed = parsing.try_parse_dates(
+                        parsing.concat_date_cols(date_cols),
+                        parser=date_parser,
+                    )
+                    try:
+                        return tools.to_datetime(pre_parsed)
+                    except (ValueError, TypeError):
+                        # TODO: not reached in tests 2023-10-27; needed?
+                        return pre_parsed
+
+    return converter
+
+
+parser_defaults = {
+    "delimiter": None,
+    "escapechar": None,
+    "quotechar": '"',
+    "quoting": csv.QUOTE_MINIMAL,
+    "doublequote": True,
+    "skipinitialspace": False,
+    "lineterminator": None,
+    "header": "infer",
+    "index_col": None,
+    "names": None,
+    "skiprows": None,
+    "skipfooter": 0,
+    "nrows": None,
+    "na_values": None,
+    "keep_default_na": True,
+    "true_values": None,
+    "false_values": None,
+    "converters": None,
+    "dtype": None,
+    "cache_dates": True,
+    "thousands": None,
+    "comment": None,
+    "decimal": ".",
+    # 'engine': 'c',
+    "parse_dates": False,
+    "keep_date_col": False,
+    "dayfirst": False,
+    "date_parser": lib.no_default,
+    "date_format": None,
+    "usecols": None,
+    # 'iterator': False,
+    "chunksize": None,
+    "verbose": False,
+    "encoding": None,
+    "compression": None,
+    "skip_blank_lines": True,
+    "encoding_errors": "strict",
+    "on_bad_lines": ParserBase.BadLineHandleMethod.ERROR,
+    "dtype_backend": lib.no_default,
+}
+
+
+def _process_date_conversion(
+    data_dict,
+    converter: Callable,
+    parse_spec,
+    index_col,
+    index_names,
+    columns,
+    keep_date_col: bool = False,
+    dtype_backend=lib.no_default,
+):
+    def _isindex(colspec):
+        return (isinstance(index_col, list) and colspec in index_col) or (
+            isinstance(index_names, list) and colspec in index_names
+        )
+
+    new_cols = []
+    new_data = {}
+
+    orig_names = columns
+    columns = list(columns)
+
+    date_cols = set()
+
+    if parse_spec is None or isinstance(parse_spec, bool):
+        return data_dict, columns
+
+    if isinstance(parse_spec, list):
+        # list of column lists
+        for colspec in parse_spec:
+            if is_scalar(colspec) or isinstance(colspec, tuple):
+                if isinstance(colspec, int) and colspec not in data_dict:
+                    colspec = orig_names[colspec]
+                if _isindex(colspec):
+                    continue
+                elif dtype_backend == "pyarrow":
+                    import pyarrow as pa
+
+                    dtype = data_dict[colspec].dtype
+                    if isinstance(dtype, ArrowDtype) and (
+                        pa.types.is_timestamp(dtype.pyarrow_dtype)
+                        or pa.types.is_date(dtype.pyarrow_dtype)
+                    ):
+                        continue
+
+                # Pyarrow engine returns Series which we need to convert to
+                # numpy array before converter, its a no-op for other parsers
+                data_dict[colspec] = converter(
+                    np.asarray(data_dict[colspec]), col=colspec
+                )
+            else:
+                new_name, col, old_names = _try_convert_dates(
+                    converter, colspec, data_dict, orig_names
+                )
+                if new_name in data_dict:
+                    raise ValueError(f"New date column already in dict {new_name}")
+                new_data[new_name] = col
+                new_cols.append(new_name)
+                date_cols.update(old_names)
+
+    elif isinstance(parse_spec, dict):
+        # dict of new name to column list
+        for new_name, colspec in parse_spec.items():
+            if new_name in data_dict:
+                raise ValueError(f"Date column {new_name} already in dict")
+
+            _, col, old_names = _try_convert_dates(
+                converter,
+                colspec,
+                data_dict,
+                orig_names,
+                target_name=new_name,
+            )
+
+            new_data[new_name] = col
+
+            # If original column can be converted to date we keep the converted values
+            # This can only happen if values are from single column
+            if len(colspec) == 1:
+                new_data[colspec[0]] = col
+
+            new_cols.append(new_name)
+            date_cols.update(old_names)
+
+    if isinstance(data_dict, DataFrame):
+        data_dict = concat([DataFrame(new_data), data_dict], axis=1, copy=False)
+    else:
+        data_dict.update(new_data)
+    new_cols.extend(columns)
+
+    if not keep_date_col:
+        for c in list(date_cols):
+            data_dict.pop(c)
+            new_cols.remove(c)
+
+    return data_dict, new_cols
+
+
+def _try_convert_dates(
+    parser: Callable, colspec, data_dict, columns, target_name: str | None = None
+):
+    colset = set(columns)
+    colnames = []
+
+    for c in colspec:
+        if c in colset:
+            colnames.append(c)
+        elif isinstance(c, int) and c not in columns:
+            colnames.append(columns[c])
+        else:
+            colnames.append(c)
+
+    new_name: tuple | str
+    if all(isinstance(x, tuple) for x in colnames):
+        new_name = tuple(map("_".join, zip(*colnames)))
+    else:
+        new_name = "_".join([str(x) for x in colnames])
+    to_parse = [np.asarray(data_dict[c]) for c in colnames if c in data_dict]
+
+    new_col = parser(*to_parse, col=new_name if target_name is None else target_name)
+    return new_name, new_col, colnames
+
+
+def _get_na_values(col, na_values, na_fvalues, keep_default_na: bool):
+    """
+    Get the NaN values for a given column.
+
+    Parameters
+    ----------
+    col : str
+        The name of the column.
+    na_values : array-like, dict
+        The object listing the NaN values as strings.
+    na_fvalues : array-like, dict
+        The object listing the NaN values as floats.
+    keep_default_na : bool
+        If `na_values` is a dict, and the column is not mapped in the
+        dictionary, whether to return the default NaN values or the empty set.
+
+    Returns
+    -------
+    nan_tuple : A length-two tuple composed of
+
+        1) na_values : the string NaN values for that column.
+        2) na_fvalues : the float NaN values for that column.
+    """
+    if isinstance(na_values, dict):
+        if col in na_values:
+            return na_values[col], na_fvalues[col]
+        else:
+            if keep_default_na:
+                return STR_NA_VALUES, set()
+
+            return set(), set()
+    else:
+        return na_values, na_fvalues
+
+
+def _validate_parse_dates_arg(parse_dates):
+    """
+    Check whether or not the 'parse_dates' parameter
+    is a non-boolean scalar. Raises a ValueError if
+    that is the case.
+    """
+    msg = (
+        "Only booleans, lists, and dictionaries are accepted "
+        "for the 'parse_dates' parameter"
+    )
+
+    if not (
+        parse_dates is None
+        or lib.is_bool(parse_dates)
+        or isinstance(parse_dates, (list, dict))
+    ):
+        raise TypeError(msg)
+
+    return parse_dates
+
+
+def is_index_col(col) -> bool:
+    return col is not None and col is not False
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/c_parser_wrapper.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/c_parser_wrapper.py
new file mode 100644
index 0000000000000000000000000000000000000000..0cd788c5e57399597e3fe4ee1b1bf2af4bffd74b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/c_parser_wrapper.py
@@ -0,0 +1,410 @@
+from __future__ import annotations
+
+from collections import defaultdict
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+
+from pandas._libs import (
+    lib,
+    parsers,
+)
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import DtypeWarning
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import pandas_dtype
+from pandas.core.dtypes.concat import (
+    concat_compat,
+    union_categoricals,
+)
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+from pandas.core.indexes.api import ensure_index_from_sequences
+
+from pandas.io.common import (
+    dedup_names,
+    is_potential_multi_index,
+)
+from pandas.io.parsers.base_parser import (
+    ParserBase,
+    ParserError,
+    is_index_col,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Mapping,
+        Sequence,
+    )
+
+    from pandas._typing import (
+        ArrayLike,
+        DtypeArg,
+        DtypeObj,
+        ReadCsvBuffer,
+    )
+
+    from pandas import (
+        Index,
+        MultiIndex,
+    )
+
+
+class CParserWrapper(ParserBase):
+    low_memory: bool
+    _reader: parsers.TextReader
+
+    def __init__(self, src: ReadCsvBuffer[str], **kwds) -> None:
+        super().__init__(kwds)
+        self.kwds = kwds
+        kwds = kwds.copy()
+
+        self.low_memory = kwds.pop("low_memory", False)
+
+        # #2442
+        # error: Cannot determine type of 'index_col'
+        kwds["allow_leading_cols"] = (
+            self.index_col is not False  # type: ignore[has-type]
+        )
+
+        # GH20529, validate usecol arg before TextReader
+        kwds["usecols"] = self.usecols
+
+        # Have to pass int, would break tests using TextReader directly otherwise :(
+        kwds["on_bad_lines"] = self.on_bad_lines.value
+
+        for key in (
+            "storage_options",
+            "encoding",
+            "memory_map",
+            "compression",
+        ):
+            kwds.pop(key, None)
+
+        kwds["dtype"] = ensure_dtype_objs(kwds.get("dtype", None))
+        if "dtype_backend" not in kwds or kwds["dtype_backend"] is lib.no_default:
+            kwds["dtype_backend"] = "numpy"
+        if kwds["dtype_backend"] == "pyarrow":
+            # Fail here loudly instead of in cython after reading
+            import_optional_dependency("pyarrow")
+        self._reader = parsers.TextReader(src, **kwds)
+
+        self.unnamed_cols = self._reader.unnamed_cols
+
+        # error: Cannot determine type of 'names'
+        passed_names = self.names is None  # type: ignore[has-type]
+
+        if self._reader.header is None:
+            self.names = None
+        else:
+            # error: Cannot determine type of 'names'
+            # error: Cannot determine type of 'index_names'
+            (
+                self.names,  # type: ignore[has-type]
+                self.index_names,
+                self.col_names,
+                passed_names,
+            ) = self._extract_multi_indexer_columns(
+                self._reader.header,
+                self.index_names,  # type: ignore[has-type]
+                passed_names,
+            )
+
+        # error: Cannot determine type of 'names'
+        if self.names is None:  # type: ignore[has-type]
+            self.names = list(range(self._reader.table_width))
+
+        # gh-9755
+        #
+        # need to set orig_names here first
+        # so that proper indexing can be done
+        # with _set_noconvert_columns
+        #
+        # once names has been filtered, we will
+        # then set orig_names again to names
+        # error: Cannot determine type of 'names'
+        self.orig_names = self.names[:]  # type: ignore[has-type]
+
+        if self.usecols:
+            usecols = self._evaluate_usecols(self.usecols, self.orig_names)
+
+            # GH 14671
+            # assert for mypy, orig_names is List or None, None would error in issubset
+            assert self.orig_names is not None
+            if self.usecols_dtype == "string" and not set(usecols).issubset(
+                self.orig_names
+            ):
+                self._validate_usecols_names(usecols, self.orig_names)
+
+            # error: Cannot determine type of 'names'
+            if len(self.names) > len(usecols):  # type: ignore[has-type]
+                # error: Cannot determine type of 'names'
+                self.names = [  # type: ignore[has-type]
+                    n
+                    # error: Cannot determine type of 'names'
+                    for i, n in enumerate(self.names)  # type: ignore[has-type]
+                    if (i in usecols or n in usecols)
+                ]
+
+            # error: Cannot determine type of 'names'
+            if len(self.names) < len(usecols):  # type: ignore[has-type]
+                # error: Cannot determine type of 'names'
+                self._validate_usecols_names(
+                    usecols,
+                    self.names,  # type: ignore[has-type]
+                )
+
+        # error: Cannot determine type of 'names'
+        self._validate_parse_dates_presence(self.names)  # type: ignore[has-type]
+        self._set_noconvert_columns()
+
+        # error: Cannot determine type of 'names'
+        self.orig_names = self.names  # type: ignore[has-type]
+
+        if not self._has_complex_date_col:
+            # error: Cannot determine type of 'index_col'
+            if self._reader.leading_cols == 0 and is_index_col(
+                self.index_col  # type: ignore[has-type]
+            ):
+                self._name_processed = True
+                (
+                    index_names,
+                    # error: Cannot determine type of 'names'
+                    self.names,  # type: ignore[has-type]
+                    self.index_col,
+                ) = self._clean_index_names(
+                    # error: Cannot determine type of 'names'
+                    self.names,  # type: ignore[has-type]
+                    # error: Cannot determine type of 'index_col'
+                    self.index_col,  # type: ignore[has-type]
+                )
+
+                if self.index_names is None:
+                    self.index_names = index_names
+
+            if self._reader.header is None and not passed_names:
+                assert self.index_names is not None
+                self.index_names = [None] * len(self.index_names)
+
+        self._implicit_index = self._reader.leading_cols > 0
+
+    def close(self) -> None:
+        # close handles opened by C parser
+        try:
+            self._reader.close()
+        except ValueError:
+            pass
+
+    def _set_noconvert_columns(self) -> None:
+        """
+        Set the columns that should not undergo dtype conversions.
+
+        Currently, any column that is involved with date parsing will not
+        undergo such conversions.
+        """
+        assert self.orig_names is not None
+        # error: Cannot determine type of 'names'
+
+        # much faster than using orig_names.index(x) xref GH#44106
+        names_dict = {x: i for i, x in enumerate(self.orig_names)}
+        col_indices = [names_dict[x] for x in self.names]  # type: ignore[has-type]
+        # error: Cannot determine type of 'names'
+        noconvert_columns = self._set_noconvert_dtype_columns(
+            col_indices,
+            self.names,  # type: ignore[has-type]
+        )
+        for col in noconvert_columns:
+            self._reader.set_noconvert(col)
+
+    def read(
+        self,
+        nrows: int | None = None,
+    ) -> tuple[
+        Index | MultiIndex | None,
+        Sequence[Hashable] | MultiIndex,
+        Mapping[Hashable, ArrayLike],
+    ]:
+        index: Index | MultiIndex | None
+        column_names: Sequence[Hashable] | MultiIndex
+        try:
+            if self.low_memory:
+                chunks = self._reader.read_low_memory(nrows)
+                # destructive to chunks
+                data = _concatenate_chunks(chunks)
+
+            else:
+                data = self._reader.read(nrows)
+        except StopIteration:
+            if self._first_chunk:
+                self._first_chunk = False
+                names = dedup_names(
+                    self.orig_names,
+                    is_potential_multi_index(self.orig_names, self.index_col),
+                )
+                index, columns, col_dict = self._get_empty_meta(
+                    names,
+                    dtype=self.dtype,
+                )
+                columns = self._maybe_make_multi_index_columns(columns, self.col_names)
+
+                if self.usecols is not None:
+                    columns = self._filter_usecols(columns)
+
+                col_dict = {k: v for k, v in col_dict.items() if k in columns}
+
+                return index, columns, col_dict
+
+            else:
+                self.close()
+                raise
+
+        # Done with first read, next time raise StopIteration
+        self._first_chunk = False
+
+        # error: Cannot determine type of 'names'
+        names = self.names  # type: ignore[has-type]
+
+        if self._reader.leading_cols:
+            if self._has_complex_date_col:
+                raise NotImplementedError("file structure not yet supported")
+
+            # implicit index, no index names
+            arrays = []
+
+            if self.index_col and self._reader.leading_cols != len(self.index_col):
+                raise ParserError(
+                    "Could not construct index. Requested to use "
+                    f"{len(self.index_col)} number of columns, but "
+                    f"{self._reader.leading_cols} left to parse."
+                )
+
+            for i in range(self._reader.leading_cols):
+                if self.index_col is None:
+                    values = data.pop(i)
+                else:
+                    values = data.pop(self.index_col[i])
+
+                values = self._maybe_parse_dates(values, i, try_parse_dates=True)
+                arrays.append(values)
+
+            index = ensure_index_from_sequences(arrays)
+
+            if self.usecols is not None:
+                names = self._filter_usecols(names)
+
+            names = dedup_names(names, is_potential_multi_index(names, self.index_col))
+
+            # rename dict keys
+            data_tups = sorted(data.items())
+            data = {k: v for k, (i, v) in zip(names, data_tups)}
+
+            column_names, date_data = self._do_date_conversions(names, data)
+
+            # maybe create a mi on the columns
+            column_names = self._maybe_make_multi_index_columns(
+                column_names, self.col_names
+            )
+
+        else:
+            # rename dict keys
+            data_tups = sorted(data.items())
+
+            # ugh, mutation
+
+            # assert for mypy, orig_names is List or None, None would error in list(...)
+            assert self.orig_names is not None
+            names = list(self.orig_names)
+            names = dedup_names(names, is_potential_multi_index(names, self.index_col))
+
+            if self.usecols is not None:
+                names = self._filter_usecols(names)
+
+            # columns as list
+            alldata = [x[1] for x in data_tups]
+            if self.usecols is None:
+                self._check_data_length(names, alldata)
+
+            data = {k: v for k, (i, v) in zip(names, data_tups)}
+
+            names, date_data = self._do_date_conversions(names, data)
+            index, column_names = self._make_index(date_data, alldata, names)
+
+        return index, column_names, date_data
+
+    def _filter_usecols(self, names: Sequence[Hashable]) -> Sequence[Hashable]:
+        # hackish
+        usecols = self._evaluate_usecols(self.usecols, names)
+        if usecols is not None and len(names) != len(usecols):
+            names = [
+                name for i, name in enumerate(names) if i in usecols or name in usecols
+            ]
+        return names
+
+    def _maybe_parse_dates(self, values, index: int, try_parse_dates: bool = True):
+        if try_parse_dates and self._should_parse_dates(index):
+            values = self._date_conv(
+                values,
+                col=self.index_names[index] if self.index_names is not None else None,
+            )
+        return values
+
+
+def _concatenate_chunks(chunks: list[dict[int, ArrayLike]]) -> dict:
+    """
+    Concatenate chunks of data read with low_memory=True.
+
+    The tricky part is handling Categoricals, where different chunks
+    may have different inferred categories.
+    """
+    names = list(chunks[0].keys())
+    warning_columns = []
+
+    result: dict = {}
+    for name in names:
+        arrs = [chunk.pop(name) for chunk in chunks]
+        # Check each arr for consistent types.
+        dtypes = {a.dtype for a in arrs}
+        non_cat_dtypes = {x for x in dtypes if not isinstance(x, CategoricalDtype)}
+
+        dtype = dtypes.pop()
+        if isinstance(dtype, CategoricalDtype):
+            result[name] = union_categoricals(arrs, sort_categories=False)
+        else:
+            result[name] = concat_compat(arrs)
+            if len(non_cat_dtypes) > 1 and result[name].dtype == np.dtype(object):
+                warning_columns.append(str(name))
+
+    if warning_columns:
+        warning_names = ",".join(warning_columns)
+        warning_message = " ".join(
+            [
+                f"Columns ({warning_names}) have mixed types. "
+                f"Specify dtype option on import or set low_memory=False."
+            ]
+        )
+        warnings.warn(warning_message, DtypeWarning, stacklevel=find_stack_level())
+    return result
+
+
+def ensure_dtype_objs(
+    dtype: DtypeArg | dict[Hashable, DtypeArg] | None
+) -> DtypeObj | dict[Hashable, DtypeObj] | None:
+    """
+    Ensure we have either None, a dtype object, or a dictionary mapping to
+    dtype objects.
+    """
+    if isinstance(dtype, defaultdict):
+        # "None" not callable  [misc]
+        default_dtype = pandas_dtype(dtype.default_factory())  # type: ignore[misc]
+        dtype_converted: defaultdict = defaultdict(lambda: default_dtype)
+        for key in dtype.keys():
+            dtype_converted[key] = pandas_dtype(dtype[key])
+        return dtype_converted
+    elif isinstance(dtype, dict):
+        return {k: pandas_dtype(dtype[k]) for k in dtype}
+    elif dtype is not None:
+        return pandas_dtype(dtype)
+    return dtype
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/python_parser.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/python_parser.py
new file mode 100644
index 0000000000000000000000000000000000000000..79e7554a5744cf439a65e9fd1e18782a0fa71548
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/python_parser.py
@@ -0,0 +1,1387 @@
+from __future__ import annotations
+
+from collections import (
+    abc,
+    defaultdict,
+)
+from collections.abc import (
+    Hashable,
+    Iterator,
+    Mapping,
+    Sequence,
+)
+import csv
+from io import StringIO
+import re
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    DefaultDict,
+    Literal,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas.errors import (
+    EmptyDataError,
+    ParserError,
+    ParserWarning,
+)
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_bool_dtype,
+    is_integer,
+    is_numeric_dtype,
+)
+from pandas.core.dtypes.inference import is_dict_like
+
+from pandas.io.common import (
+    dedup_names,
+    is_potential_multi_index,
+)
+from pandas.io.parsers.base_parser import (
+    ParserBase,
+    parser_defaults,
+)
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        ArrayLike,
+        ReadCsvBuffer,
+        Scalar,
+    )
+
+    from pandas import (
+        Index,
+        MultiIndex,
+    )
+
+# BOM character (byte order mark)
+# This exists at the beginning of a file to indicate endianness
+# of a file (stream). Unfortunately, this marker screws up parsing,
+# so we need to remove it if we see it.
+_BOM = "\ufeff"
+
+
+class PythonParser(ParserBase):
+    _no_thousands_columns: set[int]
+
+    def __init__(self, f: ReadCsvBuffer[str] | list, **kwds) -> None:
+        """
+        Workhorse function for processing nested list into DataFrame
+        """
+        super().__init__(kwds)
+
+        self.data: Iterator[str] | None = None
+        self.buf: list = []
+        self.pos = 0
+        self.line_pos = 0
+
+        self.skiprows = kwds["skiprows"]
+
+        if callable(self.skiprows):
+            self.skipfunc = self.skiprows
+        else:
+            self.skipfunc = lambda x: x in self.skiprows
+
+        self.skipfooter = _validate_skipfooter_arg(kwds["skipfooter"])
+        self.delimiter = kwds["delimiter"]
+
+        self.quotechar = kwds["quotechar"]
+        if isinstance(self.quotechar, str):
+            self.quotechar = str(self.quotechar)
+
+        self.escapechar = kwds["escapechar"]
+        self.doublequote = kwds["doublequote"]
+        self.skipinitialspace = kwds["skipinitialspace"]
+        self.lineterminator = kwds["lineterminator"]
+        self.quoting = kwds["quoting"]
+        self.skip_blank_lines = kwds["skip_blank_lines"]
+
+        self.has_index_names = False
+        if "has_index_names" in kwds:
+            self.has_index_names = kwds["has_index_names"]
+
+        self.verbose = kwds["verbose"]
+
+        self.thousands = kwds["thousands"]
+        self.decimal = kwds["decimal"]
+
+        self.comment = kwds["comment"]
+
+        # Set self.data to something that can read lines.
+        if isinstance(f, list):
+            # read_excel: f is a list
+            self.data = cast(Iterator[str], f)
+        else:
+            assert hasattr(f, "readline")
+            self.data = self._make_reader(f)
+
+        # Get columns in two steps: infer from data, then
+        # infer column indices from self.usecols if it is specified.
+        self._col_indices: list[int] | None = None
+        columns: list[list[Scalar | None]]
+        (
+            columns,
+            self.num_original_columns,
+            self.unnamed_cols,
+        ) = self._infer_columns()
+
+        # Now self.columns has the set of columns that we will process.
+        # The original set is stored in self.original_columns.
+        # error: Cannot determine type of 'index_names'
+        (
+            self.columns,
+            self.index_names,
+            self.col_names,
+            _,
+        ) = self._extract_multi_indexer_columns(
+            columns,
+            self.index_names,  # type: ignore[has-type]
+        )
+
+        # get popped off for index
+        self.orig_names: list[Hashable] = list(self.columns)
+
+        # needs to be cleaned/refactored
+        # multiple date column thing turning into a real spaghetti factory
+
+        if not self._has_complex_date_col:
+            (index_names, self.orig_names, self.columns) = self._get_index_name()
+            self._name_processed = True
+            if self.index_names is None:
+                self.index_names = index_names
+
+        if self._col_indices is None:
+            self._col_indices = list(range(len(self.columns)))
+
+        self._parse_date_cols = self._validate_parse_dates_presence(self.columns)
+        self._no_thousands_columns = self._set_no_thousand_columns()
+
+        if len(self.decimal) != 1:
+            raise ValueError("Only length-1 decimal markers supported")
+
+    @cache_readonly
+    def num(self) -> re.Pattern:
+        decimal = re.escape(self.decimal)
+        if self.thousands is None:
+            regex = rf"^[\-\+]?[0-9]*({decimal}[0-9]*)?([0-9]?(E|e)\-?[0-9]+)?$"
+        else:
+            thousands = re.escape(self.thousands)
+            regex = (
+                rf"^[\-\+]?([0-9]+{thousands}|[0-9])*({decimal}[0-9]*)?"
+                rf"([0-9]?(E|e)\-?[0-9]+)?$"
+            )
+        return re.compile(regex)
+
+    def _make_reader(self, f: IO[str] | ReadCsvBuffer[str]):
+        sep = self.delimiter
+
+        if sep is None or len(sep) == 1:
+            if self.lineterminator:
+                raise ValueError(
+                    "Custom line terminators not supported in python parser (yet)"
+                )
+
+            class MyDialect(csv.Dialect):
+                delimiter = self.delimiter
+                quotechar = self.quotechar
+                escapechar = self.escapechar
+                doublequote = self.doublequote
+                skipinitialspace = self.skipinitialspace
+                quoting = self.quoting
+                lineterminator = "\n"
+
+            dia = MyDialect
+
+            if sep is not None:
+                dia.delimiter = sep
+            else:
+                # attempt to sniff the delimiter from the first valid line,
+                # i.e. no comment line and not in skiprows
+                line = f.readline()
+                lines = self._check_comments([[line]])[0]
+                while self.skipfunc(self.pos) or not lines:
+                    self.pos += 1
+                    line = f.readline()
+                    lines = self._check_comments([[line]])[0]
+                lines_str = cast(list[str], lines)
+
+                # since `line` was a string, lines will be a list containing
+                # only a single string
+                line = lines_str[0]
+
+                self.pos += 1
+                self.line_pos += 1
+                sniffed = csv.Sniffer().sniff(line)
+                dia.delimiter = sniffed.delimiter
+
+                # Note: encoding is irrelevant here
+                line_rdr = csv.reader(StringIO(line), dialect=dia)
+                self.buf.extend(list(line_rdr))
+
+            # Note: encoding is irrelevant here
+            reader = csv.reader(f, dialect=dia, strict=True)
+
+        else:
+
+            def _read():
+                line = f.readline()
+                pat = re.compile(sep)
+
+                yield pat.split(line.strip())
+
+                for line in f:
+                    yield pat.split(line.strip())
+
+            reader = _read()
+
+        return reader
+
+    def read(
+        self, rows: int | None = None
+    ) -> tuple[
+        Index | None, Sequence[Hashable] | MultiIndex, Mapping[Hashable, ArrayLike]
+    ]:
+        try:
+            content = self._get_lines(rows)
+        except StopIteration:
+            if self._first_chunk:
+                content = []
+            else:
+                self.close()
+                raise
+
+        # done with first read, next time raise StopIteration
+        self._first_chunk = False
+
+        columns: Sequence[Hashable] = list(self.orig_names)
+        if not len(content):  # pragma: no cover
+            # DataFrame with the right metadata, even though it's length 0
+            # error: Cannot determine type of 'index_col'
+            names = dedup_names(
+                self.orig_names,
+                is_potential_multi_index(
+                    self.orig_names,
+                    self.index_col,  # type: ignore[has-type]
+                ),
+            )
+            index, columns, col_dict = self._get_empty_meta(
+                names,
+                self.dtype,
+            )
+            conv_columns = self._maybe_make_multi_index_columns(columns, self.col_names)
+            return index, conv_columns, col_dict
+
+        # handle new style for names in index
+        count_empty_content_vals = count_empty_vals(content[0])
+        indexnamerow = None
+        if self.has_index_names and count_empty_content_vals == len(columns):
+            indexnamerow = content[0]
+            content = content[1:]
+
+        alldata = self._rows_to_cols(content)
+        data, columns = self._exclude_implicit_index(alldata)
+
+        conv_data = self._convert_data(data)
+        columns, conv_data = self._do_date_conversions(columns, conv_data)
+
+        index, result_columns = self._make_index(
+            conv_data, alldata, columns, indexnamerow
+        )
+
+        return index, result_columns, conv_data
+
+    def _exclude_implicit_index(
+        self,
+        alldata: list[np.ndarray],
+    ) -> tuple[Mapping[Hashable, np.ndarray], Sequence[Hashable]]:
+        # error: Cannot determine type of 'index_col'
+        names = dedup_names(
+            self.orig_names,
+            is_potential_multi_index(
+                self.orig_names,
+                self.index_col,  # type: ignore[has-type]
+            ),
+        )
+
+        offset = 0
+        if self._implicit_index:
+            # error: Cannot determine type of 'index_col'
+            offset = len(self.index_col)  # type: ignore[has-type]
+
+        len_alldata = len(alldata)
+        self._check_data_length(names, alldata)
+
+        return {
+            name: alldata[i + offset] for i, name in enumerate(names) if i < len_alldata
+        }, names
+
+    # legacy
+    def get_chunk(
+        self, size: int | None = None
+    ) -> tuple[
+        Index | None, Sequence[Hashable] | MultiIndex, Mapping[Hashable, ArrayLike]
+    ]:
+        if size is None:
+            # error: "PythonParser" has no attribute "chunksize"
+            size = self.chunksize  # type: ignore[attr-defined]
+        return self.read(rows=size)
+
+    def _convert_data(
+        self,
+        data: Mapping[Hashable, np.ndarray],
+    ) -> Mapping[Hashable, ArrayLike]:
+        # apply converters
+        clean_conv = self._clean_mapping(self.converters)
+        clean_dtypes = self._clean_mapping(self.dtype)
+
+        # Apply NA values.
+        clean_na_values = {}
+        clean_na_fvalues = {}
+
+        if isinstance(self.na_values, dict):
+            for col in self.na_values:
+                na_value = self.na_values[col]
+                na_fvalue = self.na_fvalues[col]
+
+                if isinstance(col, int) and col not in self.orig_names:
+                    col = self.orig_names[col]
+
+                clean_na_values[col] = na_value
+                clean_na_fvalues[col] = na_fvalue
+        else:
+            clean_na_values = self.na_values
+            clean_na_fvalues = self.na_fvalues
+
+        return self._convert_to_ndarrays(
+            data,
+            clean_na_values,
+            clean_na_fvalues,
+            self.verbose,
+            clean_conv,
+            clean_dtypes,
+        )
+
+    @cache_readonly
+    def _have_mi_columns(self) -> bool:
+        if self.header is None:
+            return False
+
+        header = self.header
+        if isinstance(header, (list, tuple, np.ndarray)):
+            return len(header) > 1
+        else:
+            return False
+
+    def _infer_columns(
+        self,
+    ) -> tuple[list[list[Scalar | None]], int, set[Scalar | None]]:
+        names = self.names
+        num_original_columns = 0
+        clear_buffer = True
+        unnamed_cols: set[Scalar | None] = set()
+
+        if self.header is not None:
+            header = self.header
+            have_mi_columns = self._have_mi_columns
+
+            if isinstance(header, (list, tuple, np.ndarray)):
+                # we have a mi columns, so read an extra line
+                if have_mi_columns:
+                    header = list(header) + [header[-1] + 1]
+            else:
+                header = [header]
+
+            columns: list[list[Scalar | None]] = []
+            for level, hr in enumerate(header):
+                try:
+                    line = self._buffered_line()
+
+                    while self.line_pos <= hr:
+                        line = self._next_line()
+
+                except StopIteration as err:
+                    if 0 < self.line_pos <= hr and (
+                        not have_mi_columns or hr != header[-1]
+                    ):
+                        # If no rows we want to raise a different message and if
+                        # we have mi columns, the last line is not part of the header
+                        joi = list(map(str, header[:-1] if have_mi_columns else header))
+                        msg = f"[{','.join(joi)}], len of {len(joi)}, "
+                        raise ValueError(
+                            f"Passed header={msg}"
+                            f"but only {self.line_pos} lines in file"
+                        ) from err
+
+                    # We have an empty file, so check
+                    # if columns are provided. That will
+                    # serve as the 'line' for parsing
+                    if have_mi_columns and hr > 0:
+                        if clear_buffer:
+                            self._clear_buffer()
+                        columns.append([None] * len(columns[-1]))
+                        return columns, num_original_columns, unnamed_cols
+
+                    if not self.names:
+                        raise EmptyDataError("No columns to parse from file") from err
+
+                    line = self.names[:]
+
+                this_columns: list[Scalar | None] = []
+                this_unnamed_cols = []
+
+                for i, c in enumerate(line):
+                    if c == "":
+                        if have_mi_columns:
+                            col_name = f"Unnamed: {i}_level_{level}"
+                        else:
+                            col_name = f"Unnamed: {i}"
+
+                        this_unnamed_cols.append(i)
+                        this_columns.append(col_name)
+                    else:
+                        this_columns.append(c)
+
+                if not have_mi_columns:
+                    counts: DefaultDict = defaultdict(int)
+                    # Ensure that regular columns are used before unnamed ones
+                    # to keep given names and mangle unnamed columns
+                    col_loop_order = [
+                        i
+                        for i in range(len(this_columns))
+                        if i not in this_unnamed_cols
+                    ] + this_unnamed_cols
+
+                    # TODO: Use pandas.io.common.dedup_names instead (see #50371)
+                    for i in col_loop_order:
+                        col = this_columns[i]
+                        old_col = col
+                        cur_count = counts[col]
+
+                        if cur_count > 0:
+                            while cur_count > 0:
+                                counts[old_col] = cur_count + 1
+                                col = f"{old_col}.{cur_count}"
+                                if col in this_columns:
+                                    cur_count += 1
+                                else:
+                                    cur_count = counts[col]
+
+                            if (
+                                self.dtype is not None
+                                and is_dict_like(self.dtype)
+                                and self.dtype.get(old_col) is not None
+                                and self.dtype.get(col) is None
+                            ):
+                                self.dtype.update({col: self.dtype.get(old_col)})
+                        this_columns[i] = col
+                        counts[col] = cur_count + 1
+                elif have_mi_columns:
+                    # if we have grabbed an extra line, but its not in our
+                    # format so save in the buffer, and create an blank extra
+                    # line for the rest of the parsing code
+                    if hr == header[-1]:
+                        lc = len(this_columns)
+                        # error: Cannot determine type of 'index_col'
+                        sic = self.index_col  # type: ignore[has-type]
+                        ic = len(sic) if sic is not None else 0
+                        unnamed_count = len(this_unnamed_cols)
+
+                        # if wrong number of blanks or no index, not our format
+                        if (lc != unnamed_count and lc - ic > unnamed_count) or ic == 0:
+                            clear_buffer = False
+                            this_columns = [None] * lc
+                            self.buf = [self.buf[-1]]
+
+                columns.append(this_columns)
+                unnamed_cols.update({this_columns[i] for i in this_unnamed_cols})
+
+                if len(columns) == 1:
+                    num_original_columns = len(this_columns)
+
+            if clear_buffer:
+                self._clear_buffer()
+
+            first_line: list[Scalar] | None
+            if names is not None:
+                # Read first row after header to check if data are longer
+                try:
+                    first_line = self._next_line()
+                except StopIteration:
+                    first_line = None
+
+                len_first_data_row = 0 if first_line is None else len(first_line)
+
+                if len(names) > len(columns[0]) and len(names) > len_first_data_row:
+                    raise ValueError(
+                        "Number of passed names did not match "
+                        "number of header fields in the file"
+                    )
+                if len(columns) > 1:
+                    raise TypeError("Cannot pass names with multi-index columns")
+
+                if self.usecols is not None:
+                    # Set _use_cols. We don't store columns because they are
+                    # overwritten.
+                    self._handle_usecols(columns, names, num_original_columns)
+                else:
+                    num_original_columns = len(names)
+                if self._col_indices is not None and len(names) != len(
+                    self._col_indices
+                ):
+                    columns = [[names[i] for i in sorted(self._col_indices)]]
+                else:
+                    columns = [names]
+            else:
+                columns = self._handle_usecols(
+                    columns, columns[0], num_original_columns
+                )
+        else:
+            ncols = len(self._header_line)
+            num_original_columns = ncols
+
+            if not names:
+                columns = [list(range(ncols))]
+                columns = self._handle_usecols(columns, columns[0], ncols)
+            elif self.usecols is None or len(names) >= ncols:
+                columns = self._handle_usecols([names], names, ncols)
+                num_original_columns = len(names)
+            elif not callable(self.usecols) and len(names) != len(self.usecols):
+                raise ValueError(
+                    "Number of passed names did not match number of "
+                    "header fields in the file"
+                )
+            else:
+                # Ignore output but set used columns.
+                columns = [names]
+                self._handle_usecols(columns, columns[0], ncols)
+
+        return columns, num_original_columns, unnamed_cols
+
+    @cache_readonly
+    def _header_line(self):
+        # Store line for reuse in _get_index_name
+        if self.header is not None:
+            return None
+
+        try:
+            line = self._buffered_line()
+        except StopIteration as err:
+            if not self.names:
+                raise EmptyDataError("No columns to parse from file") from err
+
+            line = self.names[:]
+        return line
+
+    def _handle_usecols(
+        self,
+        columns: list[list[Scalar | None]],
+        usecols_key: list[Scalar | None],
+        num_original_columns: int,
+    ) -> list[list[Scalar | None]]:
+        """
+        Sets self._col_indices
+
+        usecols_key is used if there are string usecols.
+        """
+        col_indices: set[int] | list[int]
+        if self.usecols is not None:
+            if callable(self.usecols):
+                col_indices = self._evaluate_usecols(self.usecols, usecols_key)
+            elif any(isinstance(u, str) for u in self.usecols):
+                if len(columns) > 1:
+                    raise ValueError(
+                        "If using multiple headers, usecols must be integers."
+                    )
+                col_indices = []
+
+                for col in self.usecols:
+                    if isinstance(col, str):
+                        try:
+                            col_indices.append(usecols_key.index(col))
+                        except ValueError:
+                            self._validate_usecols_names(self.usecols, usecols_key)
+                    else:
+                        col_indices.append(col)
+            else:
+                missing_usecols = [
+                    col for col in self.usecols if col >= num_original_columns
+                ]
+                if missing_usecols:
+                    raise ParserError(
+                        "Defining usecols with out-of-bounds indices is not allowed. "
+                        f"{missing_usecols} are out-of-bounds.",
+                    )
+                col_indices = self.usecols
+
+            columns = [
+                [n for i, n in enumerate(column) if i in col_indices]
+                for column in columns
+            ]
+            self._col_indices = sorted(col_indices)
+        return columns
+
+    def _buffered_line(self) -> list[Scalar]:
+        """
+        Return a line from buffer, filling buffer if required.
+        """
+        if len(self.buf) > 0:
+            return self.buf[0]
+        else:
+            return self._next_line()
+
+    def _check_for_bom(self, first_row: list[Scalar]) -> list[Scalar]:
+        """
+        Checks whether the file begins with the BOM character.
+        If it does, remove it. In addition, if there is quoting
+        in the field subsequent to the BOM, remove it as well
+        because it technically takes place at the beginning of
+        the name, not the middle of it.
+        """
+        # first_row will be a list, so we need to check
+        # that that list is not empty before proceeding.
+        if not first_row:
+            return first_row
+
+        # The first element of this row is the one that could have the
+        # BOM that we want to remove. Check that the first element is a
+        # string before proceeding.
+        if not isinstance(first_row[0], str):
+            return first_row
+
+        # Check that the string is not empty, as that would
+        # obviously not have a BOM at the start of it.
+        if not first_row[0]:
+            return first_row
+
+        # Since the string is non-empty, check that it does
+        # in fact begin with a BOM.
+        first_elt = first_row[0][0]
+        if first_elt != _BOM:
+            return first_row
+
+        first_row_bom = first_row[0]
+        new_row: str
+
+        if len(first_row_bom) > 1 and first_row_bom[1] == self.quotechar:
+            start = 2
+            quote = first_row_bom[1]
+            end = first_row_bom[2:].index(quote) + 2
+
+            # Extract the data between the quotation marks
+            new_row = first_row_bom[start:end]
+
+            # Extract any remaining data after the second
+            # quotation mark.
+            if len(first_row_bom) > end + 1:
+                new_row += first_row_bom[end + 1 :]
+
+        else:
+            # No quotation so just remove BOM from first element
+            new_row = first_row_bom[1:]
+
+        new_row_list: list[Scalar] = [new_row]
+        return new_row_list + first_row[1:]
+
+    def _is_line_empty(self, line: list[Scalar]) -> bool:
+        """
+        Check if a line is empty or not.
+
+        Parameters
+        ----------
+        line : str, array-like
+            The line of data to check.
+
+        Returns
+        -------
+        boolean : Whether or not the line is empty.
+        """
+        return not line or all(not x for x in line)
+
+    def _next_line(self) -> list[Scalar]:
+        if isinstance(self.data, list):
+            while self.skipfunc(self.pos):
+                if self.pos >= len(self.data):
+                    break
+                self.pos += 1
+
+            while True:
+                try:
+                    line = self._check_comments([self.data[self.pos]])[0]
+                    self.pos += 1
+                    # either uncommented or blank to begin with
+                    if not self.skip_blank_lines and (
+                        self._is_line_empty(self.data[self.pos - 1]) or line
+                    ):
+                        break
+                    if self.skip_blank_lines:
+                        ret = self._remove_empty_lines([line])
+                        if ret:
+                            line = ret[0]
+                            break
+                except IndexError:
+                    raise StopIteration
+        else:
+            while self.skipfunc(self.pos):
+                self.pos += 1
+                # assert for mypy, data is Iterator[str] or None, would error in next
+                assert self.data is not None
+                next(self.data)
+
+            while True:
+                orig_line = self._next_iter_line(row_num=self.pos + 1)
+                self.pos += 1
+
+                if orig_line is not None:
+                    line = self._check_comments([orig_line])[0]
+
+                    if self.skip_blank_lines:
+                        ret = self._remove_empty_lines([line])
+
+                        if ret:
+                            line = ret[0]
+                            break
+                    elif self._is_line_empty(orig_line) or line:
+                        break
+
+        # This was the first line of the file,
+        # which could contain the BOM at the
+        # beginning of it.
+        if self.pos == 1:
+            line = self._check_for_bom(line)
+
+        self.line_pos += 1
+        self.buf.append(line)
+        return line
+
+    def _alert_malformed(self, msg: str, row_num: int) -> None:
+        """
+        Alert a user about a malformed row, depending on value of
+        `self.on_bad_lines` enum.
+
+        If `self.on_bad_lines` is ERROR, the alert will be `ParserError`.
+        If `self.on_bad_lines` is WARN, the alert will be printed out.
+
+        Parameters
+        ----------
+        msg: str
+            The error message to display.
+        row_num: int
+            The row number where the parsing error occurred.
+            Because this row number is displayed, we 1-index,
+            even though we 0-index internally.
+        """
+        if self.on_bad_lines == self.BadLineHandleMethod.ERROR:
+            raise ParserError(msg)
+        if self.on_bad_lines == self.BadLineHandleMethod.WARN:
+            warnings.warn(
+                f"Skipping line {row_num}: {msg}\n",
+                ParserWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    def _next_iter_line(self, row_num: int) -> list[Scalar] | None:
+        """
+        Wrapper around iterating through `self.data` (CSV source).
+
+        When a CSV error is raised, we check for specific
+        error messages that allow us to customize the
+        error message displayed to the user.
+
+        Parameters
+        ----------
+        row_num: int
+            The row number of the line being parsed.
+        """
+        try:
+            # assert for mypy, data is Iterator[str] or None, would error in next
+            assert self.data is not None
+            line = next(self.data)
+            # for mypy
+            assert isinstance(line, list)
+            return line
+        except csv.Error as e:
+            if self.on_bad_lines in (
+                self.BadLineHandleMethod.ERROR,
+                self.BadLineHandleMethod.WARN,
+            ):
+                msg = str(e)
+
+                if "NULL byte" in msg or "line contains NUL" in msg:
+                    msg = (
+                        "NULL byte detected. This byte "
+                        "cannot be processed in Python's "
+                        "native csv library at the moment, "
+                        "so please pass in engine='c' instead"
+                    )
+
+                if self.skipfooter > 0:
+                    reason = (
+                        "Error could possibly be due to "
+                        "parsing errors in the skipped footer rows "
+                        "(the skipfooter keyword is only applied "
+                        "after Python's csv library has parsed "
+                        "all rows)."
+                    )
+                    msg += ". " + reason
+
+                self._alert_malformed(msg, row_num)
+            return None
+
+    def _check_comments(self, lines: list[list[Scalar]]) -> list[list[Scalar]]:
+        if self.comment is None:
+            return lines
+        ret = []
+        for line in lines:
+            rl = []
+            for x in line:
+                if (
+                    not isinstance(x, str)
+                    or self.comment not in x
+                    or x in self.na_values
+                ):
+                    rl.append(x)
+                else:
+                    x = x[: x.find(self.comment)]
+                    if len(x) > 0:
+                        rl.append(x)
+                    break
+            ret.append(rl)
+        return ret
+
+    def _remove_empty_lines(self, lines: list[list[Scalar]]) -> list[list[Scalar]]:
+        """
+        Iterate through the lines and remove any that are
+        either empty or contain only one whitespace value
+
+        Parameters
+        ----------
+        lines : list of list of Scalars
+            The array of lines that we are to filter.
+
+        Returns
+        -------
+        filtered_lines : list of list of Scalars
+            The same array of lines with the "empty" ones removed.
+        """
+        # Remove empty lines and lines with only one whitespace value
+        ret = [
+            line
+            for line in lines
+            if (
+                len(line) > 1
+                or len(line) == 1
+                and (not isinstance(line[0], str) or line[0].strip())
+            )
+        ]
+        return ret
+
+    def _check_thousands(self, lines: list[list[Scalar]]) -> list[list[Scalar]]:
+        if self.thousands is None:
+            return lines
+
+        return self._search_replace_num_columns(
+            lines=lines, search=self.thousands, replace=""
+        )
+
+    def _search_replace_num_columns(
+        self, lines: list[list[Scalar]], search: str, replace: str
+    ) -> list[list[Scalar]]:
+        ret = []
+        for line in lines:
+            rl = []
+            for i, x in enumerate(line):
+                if (
+                    not isinstance(x, str)
+                    or search not in x
+                    or i in self._no_thousands_columns
+                    or not self.num.search(x.strip())
+                ):
+                    rl.append(x)
+                else:
+                    rl.append(x.replace(search, replace))
+            ret.append(rl)
+        return ret
+
+    def _check_decimal(self, lines: list[list[Scalar]]) -> list[list[Scalar]]:
+        if self.decimal == parser_defaults["decimal"]:
+            return lines
+
+        return self._search_replace_num_columns(
+            lines=lines, search=self.decimal, replace="."
+        )
+
+    def _clear_buffer(self) -> None:
+        self.buf = []
+
+    def _get_index_name(
+        self,
+    ) -> tuple[Sequence[Hashable] | None, list[Hashable], list[Hashable]]:
+        """
+        Try several cases to get lines:
+
+        0) There are headers on row 0 and row 1 and their
+        total summed lengths equals the length of the next line.
+        Treat row 0 as columns and row 1 as indices
+        1) Look for implicit index: there are more columns
+        on row 1 than row 0. If this is true, assume that row
+        1 lists index columns and row 0 lists normal columns.
+        2) Get index from the columns if it was listed.
+        """
+        columns: Sequence[Hashable] = self.orig_names
+        orig_names = list(columns)
+        columns = list(columns)
+
+        line: list[Scalar] | None
+        if self._header_line is not None:
+            line = self._header_line
+        else:
+            try:
+                line = self._next_line()
+            except StopIteration:
+                line = None
+
+        next_line: list[Scalar] | None
+        try:
+            next_line = self._next_line()
+        except StopIteration:
+            next_line = None
+
+        # implicitly index_col=0 b/c 1 fewer column names
+        implicit_first_cols = 0
+        if line is not None:
+            # leave it 0, #2442
+            # Case 1
+            # error: Cannot determine type of 'index_col'
+            index_col = self.index_col  # type: ignore[has-type]
+            if index_col is not False:
+                implicit_first_cols = len(line) - self.num_original_columns
+
+            # Case 0
+            if (
+                next_line is not None
+                and self.header is not None
+                and index_col is not False
+            ):
+                if len(next_line) == len(line) + self.num_original_columns:
+                    # column and index names on diff rows
+                    self.index_col = list(range(len(line)))
+                    self.buf = self.buf[1:]
+
+                    for c in reversed(line):
+                        columns.insert(0, c)
+
+                    # Update list of original names to include all indices.
+                    orig_names = list(columns)
+                    self.num_original_columns = len(columns)
+                    return line, orig_names, columns
+
+        if implicit_first_cols > 0:
+            # Case 1
+            self._implicit_index = True
+            if self.index_col is None:
+                self.index_col = list(range(implicit_first_cols))
+
+            index_name = None
+
+        else:
+            # Case 2
+            (index_name, _, self.index_col) = self._clean_index_names(
+                columns, self.index_col
+            )
+
+        return index_name, orig_names, columns
+
+    def _rows_to_cols(self, content: list[list[Scalar]]) -> list[np.ndarray]:
+        col_len = self.num_original_columns
+
+        if self._implicit_index:
+            col_len += len(self.index_col)
+
+        max_len = max(len(row) for row in content)
+
+        # Check that there are no rows with too many
+        # elements in their row (rows with too few
+        # elements are padded with NaN).
+        # error: Non-overlapping identity check (left operand type: "List[int]",
+        # right operand type: "Literal[False]")
+        if (
+            max_len > col_len
+            and self.index_col is not False  # type: ignore[comparison-overlap]
+            and self.usecols is None
+        ):
+            footers = self.skipfooter if self.skipfooter else 0
+            bad_lines = []
+
+            iter_content = enumerate(content)
+            content_len = len(content)
+            content = []
+
+            for i, _content in iter_content:
+                actual_len = len(_content)
+
+                if actual_len > col_len:
+                    if callable(self.on_bad_lines):
+                        new_l = self.on_bad_lines(_content)
+                        if new_l is not None:
+                            content.append(new_l)
+                    elif self.on_bad_lines in (
+                        self.BadLineHandleMethod.ERROR,
+                        self.BadLineHandleMethod.WARN,
+                    ):
+                        row_num = self.pos - (content_len - i + footers)
+                        bad_lines.append((row_num, actual_len))
+
+                        if self.on_bad_lines == self.BadLineHandleMethod.ERROR:
+                            break
+                else:
+                    content.append(_content)
+
+            for row_num, actual_len in bad_lines:
+                msg = (
+                    f"Expected {col_len} fields in line {row_num + 1}, saw "
+                    f"{actual_len}"
+                )
+                if (
+                    self.delimiter
+                    and len(self.delimiter) > 1
+                    and self.quoting != csv.QUOTE_NONE
+                ):
+                    # see gh-13374
+                    reason = (
+                        "Error could possibly be due to quotes being "
+                        "ignored when a multi-char delimiter is used."
+                    )
+                    msg += ". " + reason
+
+                self._alert_malformed(msg, row_num + 1)
+
+        # see gh-13320
+        zipped_content = list(lib.to_object_array(content, min_width=col_len).T)
+
+        if self.usecols:
+            assert self._col_indices is not None
+            col_indices = self._col_indices
+
+            if self._implicit_index:
+                zipped_content = [
+                    a
+                    for i, a in enumerate(zipped_content)
+                    if (
+                        i < len(self.index_col)
+                        or i - len(self.index_col) in col_indices
+                    )
+                ]
+            else:
+                zipped_content = [
+                    a for i, a in enumerate(zipped_content) if i in col_indices
+                ]
+        return zipped_content
+
+    def _get_lines(self, rows: int | None = None) -> list[list[Scalar]]:
+        lines = self.buf
+        new_rows = None
+
+        # already fetched some number
+        if rows is not None:
+            # we already have the lines in the buffer
+            if len(self.buf) >= rows:
+                new_rows, self.buf = self.buf[:rows], self.buf[rows:]
+
+            # need some lines
+            else:
+                rows -= len(self.buf)
+
+        if new_rows is None:
+            if isinstance(self.data, list):
+                if self.pos > len(self.data):
+                    raise StopIteration
+                if rows is None:
+                    new_rows = self.data[self.pos :]
+                    new_pos = len(self.data)
+                else:
+                    new_rows = self.data[self.pos : self.pos + rows]
+                    new_pos = self.pos + rows
+
+                new_rows = self._remove_skipped_rows(new_rows)
+                lines.extend(new_rows)
+                self.pos = new_pos
+
+            else:
+                new_rows = []
+                try:
+                    if rows is not None:
+                        row_index = 0
+                        row_ct = 0
+                        offset = self.pos if self.pos is not None else 0
+                        while row_ct < rows:
+                            # assert for mypy, data is Iterator[str] or None, would
+                            # error in next
+                            assert self.data is not None
+                            new_row = next(self.data)
+                            if not self.skipfunc(offset + row_index):
+                                row_ct += 1
+                            row_index += 1
+                            new_rows.append(new_row)
+
+                        len_new_rows = len(new_rows)
+                        new_rows = self._remove_skipped_rows(new_rows)
+                        lines.extend(new_rows)
+                    else:
+                        rows = 0
+
+                        while True:
+                            next_row = self._next_iter_line(row_num=self.pos + rows + 1)
+                            rows += 1
+
+                            if next_row is not None:
+                                new_rows.append(next_row)
+                        len_new_rows = len(new_rows)
+
+                except StopIteration:
+                    len_new_rows = len(new_rows)
+                    new_rows = self._remove_skipped_rows(new_rows)
+                    lines.extend(new_rows)
+                    if len(lines) == 0:
+                        raise
+                self.pos += len_new_rows
+
+            self.buf = []
+        else:
+            lines = new_rows
+
+        if self.skipfooter:
+            lines = lines[: -self.skipfooter]
+
+        lines = self._check_comments(lines)
+        if self.skip_blank_lines:
+            lines = self._remove_empty_lines(lines)
+        lines = self._check_thousands(lines)
+        return self._check_decimal(lines)
+
+    def _remove_skipped_rows(self, new_rows: list[list[Scalar]]) -> list[list[Scalar]]:
+        if self.skiprows:
+            return [
+                row for i, row in enumerate(new_rows) if not self.skipfunc(i + self.pos)
+            ]
+        return new_rows
+
+    def _set_no_thousand_columns(self) -> set[int]:
+        no_thousands_columns: set[int] = set()
+        if self.columns and self.parse_dates:
+            assert self._col_indices is not None
+            no_thousands_columns = self._set_noconvert_dtype_columns(
+                self._col_indices, self.columns
+            )
+        if self.columns and self.dtype:
+            assert self._col_indices is not None
+            for i, col in zip(self._col_indices, self.columns):
+                if not isinstance(self.dtype, dict) and not is_numeric_dtype(
+                    self.dtype
+                ):
+                    no_thousands_columns.add(i)
+                if (
+                    isinstance(self.dtype, dict)
+                    and col in self.dtype
+                    and (
+                        not is_numeric_dtype(self.dtype[col])
+                        or is_bool_dtype(self.dtype[col])
+                    )
+                ):
+                    no_thousands_columns.add(i)
+        return no_thousands_columns
+
+
+class FixedWidthReader(abc.Iterator):
+    """
+    A reader of fixed-width lines.
+    """
+
+    def __init__(
+        self,
+        f: IO[str] | ReadCsvBuffer[str],
+        colspecs: list[tuple[int, int]] | Literal["infer"],
+        delimiter: str | None,
+        comment: str | None,
+        skiprows: set[int] | None = None,
+        infer_nrows: int = 100,
+    ) -> None:
+        self.f = f
+        self.buffer: Iterator | None = None
+        self.delimiter = "\r\n" + delimiter if delimiter else "\n\r\t "
+        self.comment = comment
+        if colspecs == "infer":
+            self.colspecs = self.detect_colspecs(
+                infer_nrows=infer_nrows, skiprows=skiprows
+            )
+        else:
+            self.colspecs = colspecs
+
+        if not isinstance(self.colspecs, (tuple, list)):
+            raise TypeError(
+                "column specifications must be a list or tuple, "
+                f"input was a {type(colspecs).__name__}"
+            )
+
+        for colspec in self.colspecs:
+            if not (
+                isinstance(colspec, (tuple, list))
+                and len(colspec) == 2
+                and isinstance(colspec[0], (int, np.integer, type(None)))
+                and isinstance(colspec[1], (int, np.integer, type(None)))
+            ):
+                raise TypeError(
+                    "Each column specification must be "
+                    "2 element tuple or list of integers"
+                )
+
+    def get_rows(self, infer_nrows: int, skiprows: set[int] | None = None) -> list[str]:
+        """
+        Read rows from self.f, skipping as specified.
+
+        We distinguish buffer_rows (the first <= infer_nrows
+        lines) from the rows returned to detect_colspecs
+        because it's simpler to leave the other locations
+        with skiprows logic alone than to modify them to
+        deal with the fact we skipped some rows here as
+        well.
+
+        Parameters
+        ----------
+        infer_nrows : int
+            Number of rows to read from self.f, not counting
+            rows that are skipped.
+        skiprows: set, optional
+            Indices of rows to skip.
+
+        Returns
+        -------
+        detect_rows : list of str
+            A list containing the rows to read.
+
+        """
+        if skiprows is None:
+            skiprows = set()
+        buffer_rows = []
+        detect_rows = []
+        for i, row in enumerate(self.f):
+            if i not in skiprows:
+                detect_rows.append(row)
+            buffer_rows.append(row)
+            if len(detect_rows) >= infer_nrows:
+                break
+        self.buffer = iter(buffer_rows)
+        return detect_rows
+
+    def detect_colspecs(
+        self, infer_nrows: int = 100, skiprows: set[int] | None = None
+    ) -> list[tuple[int, int]]:
+        # Regex escape the delimiters
+        delimiters = "".join([rf"\{x}" for x in self.delimiter])
+        pattern = re.compile(f"([^{delimiters}]+)")
+        rows = self.get_rows(infer_nrows, skiprows)
+        if not rows:
+            raise EmptyDataError("No rows from which to infer column width")
+        max_len = max(map(len, rows))
+        mask = np.zeros(max_len + 1, dtype=int)
+        if self.comment is not None:
+            rows = [row.partition(self.comment)[0] for row in rows]
+        for row in rows:
+            for m in pattern.finditer(row):
+                mask[m.start() : m.end()] = 1
+        shifted = np.roll(mask, 1)
+        shifted[0] = 0
+        edges = np.where((mask ^ shifted) == 1)[0]
+        edge_pairs = list(zip(edges[::2], edges[1::2]))
+        return edge_pairs
+
+    def __next__(self) -> list[str]:
+        # Argument 1 to "next" has incompatible type "Union[IO[str],
+        # ReadCsvBuffer[str]]"; expected "SupportsNext[str]"
+        if self.buffer is not None:
+            try:
+                line = next(self.buffer)
+            except StopIteration:
+                self.buffer = None
+                line = next(self.f)  # type: ignore[arg-type]
+        else:
+            line = next(self.f)  # type: ignore[arg-type]
+        # Note: 'colspecs' is a sequence of half-open intervals.
+        return [line[from_:to].strip(self.delimiter) for (from_, to) in self.colspecs]
+
+
+class FixedWidthFieldParser(PythonParser):
+    """
+    Specialization that Converts fixed-width fields into DataFrames.
+    See PythonParser for details.
+    """
+
+    def __init__(self, f: ReadCsvBuffer[str], **kwds) -> None:
+        # Support iterators, convert to a list.
+        self.colspecs = kwds.pop("colspecs")
+        self.infer_nrows = kwds.pop("infer_nrows")
+        PythonParser.__init__(self, f, **kwds)
+
+    def _make_reader(self, f: IO[str] | ReadCsvBuffer[str]) -> FixedWidthReader:
+        return FixedWidthReader(
+            f,
+            self.colspecs,
+            self.delimiter,
+            self.comment,
+            self.skiprows,
+            self.infer_nrows,
+        )
+
+    def _remove_empty_lines(self, lines: list[list[Scalar]]) -> list[list[Scalar]]:
+        """
+        Returns the list of lines without the empty ones. With fixed-width
+        fields, empty lines become arrays of empty strings.
+
+        See PythonParser._remove_empty_lines.
+        """
+        return [
+            line
+            for line in lines
+            if any(not isinstance(e, str) or e.strip() for e in line)
+        ]
+
+
+def count_empty_vals(vals) -> int:
+    return sum(1 for v in vals if v == "" or v is None)
+
+
+def _validate_skipfooter_arg(skipfooter: int) -> int:
+    """
+    Validate the 'skipfooter' parameter.
+
+    Checks whether 'skipfooter' is a non-negative integer.
+    Raises a ValueError if that is not the case.
+
+    Parameters
+    ----------
+    skipfooter : non-negative integer
+        The number of rows to skip at the end of the file.
+
+    Returns
+    -------
+    validated_skipfooter : non-negative integer
+        The original input if the validation succeeds.
+
+    Raises
+    ------
+    ValueError : 'skipfooter' was not a non-negative integer.
+    """
+    if not is_integer(skipfooter):
+        raise ValueError("skipfooter must be an integer")
+
+    if skipfooter < 0:
+        raise ValueError("skipfooter cannot be negative")
+
+    # Incompatible return value type (got "Union[int, integer[Any]]", expected "int")
+    return skipfooter  # type: ignore[return-value]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/parsers/readers.py b/.venv/lib/python3.13/site-packages/pandas/io/parsers/readers.py
new file mode 100644
index 0000000000000000000000000000000000000000..e04f27b56061030d19081d87439f0461fa53cc76
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/parsers/readers.py
@@ -0,0 +1,2383 @@
+"""
+Module contains tools for processing files into DataFrames or other objects
+
+GH#48849 provides a convenient way of deprecating keyword arguments
+"""
+from __future__ import annotations
+
+from collections import (
+    abc,
+    defaultdict,
+)
+import csv
+import sys
+from textwrap import fill
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    NamedTuple,
+    TypedDict,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_copy_on_write
+
+from pandas._libs import lib
+from pandas._libs.parsers import STR_NA_VALUES
+from pandas.errors import (
+    AbstractMethodError,
+    ParserWarning,
+)
+from pandas.util._decorators import Appender
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import (
+    is_file_like,
+    is_float,
+    is_hashable,
+    is_integer,
+    is_list_like,
+    pandas_dtype,
+)
+
+from pandas import Series
+from pandas.core.frame import DataFrame
+from pandas.core.indexes.api import RangeIndex
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import (
+    IOHandles,
+    get_handle,
+    stringify_path,
+    validate_header_arg,
+)
+from pandas.io.parsers.arrow_parser_wrapper import ArrowParserWrapper
+from pandas.io.parsers.base_parser import (
+    ParserBase,
+    is_index_col,
+    parser_defaults,
+)
+from pandas.io.parsers.c_parser_wrapper import CParserWrapper
+from pandas.io.parsers.python_parser import (
+    FixedWidthFieldParser,
+    PythonParser,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Iterable,
+        Mapping,
+        Sequence,
+    )
+    from types import TracebackType
+
+    from pandas._typing import (
+        CompressionOptions,
+        CSVEngine,
+        DtypeArg,
+        DtypeBackend,
+        FilePath,
+        IndexLabel,
+        ReadCsvBuffer,
+        Self,
+        StorageOptions,
+        UsecolsArgType,
+    )
+_doc_read_csv_and_table = (
+    r"""
+{summary}
+
+Also supports optionally iterating or breaking of the file
+into chunks.
+
+Additional help can be found in the online docs for
+`IO Tools `_.
+
+Parameters
+----------
+filepath_or_buffer : str, path object or file-like object
+    Any valid string path is acceptable. The string could be a URL. Valid
+    URL schemes include http, ftp, s3, gs, and file. For file URLs, a host is
+    expected. A local file could be: file://localhost/path/to/table.csv.
+
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
+
+    By file-like object, we refer to objects with a ``read()`` method, such as
+    a file handle (e.g. via builtin ``open`` function) or ``StringIO``.
+sep : str, default {_default_sep}
+    Character or regex pattern to treat as the delimiter. If ``sep=None``, the
+    C engine cannot automatically detect
+    the separator, but the Python parsing engine can, meaning the latter will
+    be used and automatically detect the separator from only the first valid
+    row of the file by Python's builtin sniffer tool, ``csv.Sniffer``.
+    In addition, separators longer than 1 character and different from
+    ``'\s+'`` will be interpreted as regular expressions and will also force
+    the use of the Python parsing engine. Note that regex delimiters are prone
+    to ignoring quoted data. Regex example: ``'\r\t'``.
+delimiter : str, optional
+    Alias for ``sep``.
+header : int, Sequence of int, 'infer' or None, default 'infer'
+    Row number(s) containing column labels and marking the start of the
+    data (zero-indexed). Default behavior is to infer the column names: if no ``names``
+    are passed the behavior is identical to ``header=0`` and column
+    names are inferred from the first line of the file, if column
+    names are passed explicitly to ``names`` then the behavior is identical to
+    ``header=None``. Explicitly pass ``header=0`` to be able to
+    replace existing names. The header can be a list of integers that
+    specify row locations for a :class:`~pandas.MultiIndex` on the columns
+    e.g. ``[0, 1, 3]``. Intervening rows that are not specified will be
+    skipped (e.g. 2 in this example is skipped). Note that this
+    parameter ignores commented lines and empty lines if
+    ``skip_blank_lines=True``, so ``header=0`` denotes the first line of
+    data rather than the first line of the file.
+names : Sequence of Hashable, optional
+    Sequence of column labels to apply. If the file contains a header row,
+    then you should explicitly pass ``header=0`` to override the column names.
+    Duplicates in this list are not allowed.
+index_col : Hashable, Sequence of Hashable or False, optional
+  Column(s) to use as row label(s), denoted either by column labels or column
+  indices.  If a sequence of labels or indices is given, :class:`~pandas.MultiIndex`
+  will be formed for the row labels.
+
+  Note: ``index_col=False`` can be used to force pandas to *not* use the first
+  column as the index, e.g., when you have a malformed file with delimiters at
+  the end of each line.
+usecols : Sequence of Hashable or Callable, optional
+    Subset of columns to select, denoted either by column labels or column indices.
+    If list-like, all elements must either
+    be positional (i.e. integer indices into the document columns) or strings
+    that correspond to column names provided either by the user in ``names`` or
+    inferred from the document header row(s). If ``names`` are given, the document
+    header row(s) are not taken into account. For example, a valid list-like
+    ``usecols`` parameter would be ``[0, 1, 2]`` or ``['foo', 'bar', 'baz']``.
+    Element order is ignored, so ``usecols=[0, 1]`` is the same as ``[1, 0]``.
+    To instantiate a :class:`~pandas.DataFrame` from ``data`` with element order
+    preserved use ``pd.read_csv(data, usecols=['foo', 'bar'])[['foo', 'bar']]``
+    for columns in ``['foo', 'bar']`` order or
+    ``pd.read_csv(data, usecols=['foo', 'bar'])[['bar', 'foo']]``
+    for ``['bar', 'foo']`` order.
+
+    If callable, the callable function will be evaluated against the column
+    names, returning names where the callable function evaluates to ``True``. An
+    example of a valid callable argument would be ``lambda x: x.upper() in
+    ['AAA', 'BBB', 'DDD']``. Using this parameter results in much faster
+    parsing time and lower memory usage.
+dtype : dtype or dict of {{Hashable : dtype}}, optional
+    Data type(s) to apply to either the whole dataset or individual columns.
+    E.g., ``{{'a': np.float64, 'b': np.int32, 'c': 'Int64'}}``
+    Use ``str`` or ``object`` together with suitable ``na_values`` settings
+    to preserve and not interpret ``dtype``.
+    If ``converters`` are specified, they will be applied INSTEAD
+    of ``dtype`` conversion.
+
+    .. versionadded:: 1.5.0
+
+        Support for ``defaultdict`` was added. Specify a ``defaultdict`` as input where
+        the default determines the ``dtype`` of the columns which are not explicitly
+        listed.
+engine : {{'c', 'python', 'pyarrow'}}, optional
+    Parser engine to use. The C and pyarrow engines are faster, while the python engine
+    is currently more feature-complete. Multithreading is currently only supported by
+    the pyarrow engine.
+
+    .. versionadded:: 1.4.0
+
+        The 'pyarrow' engine was added as an *experimental* engine, and some features
+        are unsupported, or may not work correctly, with this engine.
+converters : dict of {{Hashable : Callable}}, optional
+    Functions for converting values in specified columns. Keys can either
+    be column labels or column indices.
+true_values : list, optional
+    Values to consider as ``True`` in addition to case-insensitive variants of 'True'.
+false_values : list, optional
+    Values to consider as ``False`` in addition to case-insensitive variants of 'False'.
+skipinitialspace : bool, default False
+    Skip spaces after delimiter.
+skiprows : int, list of int or Callable, optional
+    Line numbers to skip (0-indexed) or number of lines to skip (``int``)
+    at the start of the file.
+
+    If callable, the callable function will be evaluated against the row
+    indices, returning ``True`` if the row should be skipped and ``False`` otherwise.
+    An example of a valid callable argument would be ``lambda x: x in [0, 2]``.
+skipfooter : int, default 0
+    Number of lines at bottom of file to skip (Unsupported with ``engine='c'``).
+nrows : int, optional
+    Number of rows of file to read. Useful for reading pieces of large files.
+na_values : Hashable, Iterable of Hashable or dict of {{Hashable : Iterable}}, optional
+    Additional strings to recognize as ``NA``/``NaN``. If ``dict`` passed, specific
+    per-column ``NA`` values.  By default the following values are interpreted as
+    ``NaN``: " """
+    + fill('", "'.join(sorted(STR_NA_VALUES)), 70, subsequent_indent="    ")
+    + """ ".
+
+keep_default_na : bool, default True
+    Whether or not to include the default ``NaN`` values when parsing the data.
+    Depending on whether ``na_values`` is passed in, the behavior is as follows:
+
+    * If ``keep_default_na`` is ``True``, and ``na_values`` are specified, ``na_values``
+      is appended to the default ``NaN`` values used for parsing.
+    * If ``keep_default_na`` is ``True``, and ``na_values`` are not specified, only
+      the default ``NaN`` values are used for parsing.
+    * If ``keep_default_na`` is ``False``, and ``na_values`` are specified, only
+      the ``NaN`` values specified ``na_values`` are used for parsing.
+    * If ``keep_default_na`` is ``False``, and ``na_values`` are not specified, no
+      strings will be parsed as ``NaN``.
+
+    Note that if ``na_filter`` is passed in as ``False``, the ``keep_default_na`` and
+    ``na_values`` parameters will be ignored.
+na_filter : bool, default True
+    Detect missing value markers (empty strings and the value of ``na_values``). In
+    data without any ``NA`` values, passing ``na_filter=False`` can improve the
+    performance of reading a large file.
+verbose : bool, default False
+    Indicate number of ``NA`` values placed in non-numeric columns.
+
+    .. deprecated:: 2.2.0
+skip_blank_lines : bool, default True
+    If ``True``, skip over blank lines rather than interpreting as ``NaN`` values.
+parse_dates : bool, list of Hashable, list of lists or dict of {{Hashable : list}}, \
+default False
+    The behavior is as follows:
+
+    * ``bool``. If ``True`` -> try parsing the index. Note: Automatically set to
+      ``True`` if ``date_format`` or ``date_parser`` arguments have been passed.
+    * ``list`` of ``int`` or names. e.g. If ``[1, 2, 3]`` -> try parsing columns 1, 2, 3
+      each as a separate date column.
+    * ``list`` of ``list``. e.g.  If ``[[1, 3]]`` -> combine columns 1 and 3 and parse
+      as a single date column. Values are joined with a space before parsing.
+    * ``dict``, e.g. ``{{'foo' : [1, 3]}}`` -> parse columns 1, 3 as date and call
+      result 'foo'. Values are joined with a space before parsing.
+
+    If a column or index cannot be represented as an array of ``datetime``,
+    say because of an unparsable value or a mixture of timezones, the column
+    or index will be returned unaltered as an ``object`` data type. For
+    non-standard ``datetime`` parsing, use :func:`~pandas.to_datetime` after
+    :func:`~pandas.read_csv`.
+
+    Note: A fast-path exists for iso8601-formatted dates.
+infer_datetime_format : bool, default False
+    If ``True`` and ``parse_dates`` is enabled, pandas will attempt to infer the
+    format of the ``datetime`` strings in the columns, and if it can be inferred,
+    switch to a faster method of parsing them. In some cases this can increase
+    the parsing speed by 5-10x.
+
+    .. deprecated:: 2.0.0
+        A strict version of this argument is now the default, passing it has no effect.
+
+keep_date_col : bool, default False
+    If ``True`` and ``parse_dates`` specifies combining multiple columns then
+    keep the original columns.
+date_parser : Callable, optional
+    Function to use for converting a sequence of string columns to an array of
+    ``datetime`` instances. The default uses ``dateutil.parser.parser`` to do the
+    conversion. pandas will try to call ``date_parser`` in three different ways,
+    advancing to the next if an exception occurs: 1) Pass one or more arrays
+    (as defined by ``parse_dates``) as arguments; 2) concatenate (row-wise) the
+    string values from the columns defined by ``parse_dates`` into a single array
+    and pass that; and 3) call ``date_parser`` once for each row using one or
+    more strings (corresponding to the columns defined by ``parse_dates``) as
+    arguments.
+
+    .. deprecated:: 2.0.0
+       Use ``date_format`` instead, or read in as ``object`` and then apply
+       :func:`~pandas.to_datetime` as-needed.
+date_format : str or dict of column -> format, optional
+    Format to use for parsing dates when used in conjunction with ``parse_dates``.
+    The strftime to parse time, e.g. :const:`"%d/%m/%Y"`. See
+    `strftime documentation
+    `_ for more information on choices, though
+    note that :const:`"%f"` will parse all the way up to nanoseconds.
+    You can also pass:
+
+    - "ISO8601", to parse any `ISO8601 `_
+        time string (not necessarily in exactly the same format);
+    - "mixed", to infer the format for each element individually. This is risky,
+        and you should probably use it along with `dayfirst`.
+
+    .. versionadded:: 2.0.0
+dayfirst : bool, default False
+    DD/MM format dates, international and European format.
+cache_dates : bool, default True
+    If ``True``, use a cache of unique, converted dates to apply the ``datetime``
+    conversion. May produce significant speed-up when parsing duplicate
+    date strings, especially ones with timezone offsets.
+
+iterator : bool, default False
+    Return ``TextFileReader`` object for iteration or getting chunks with
+    ``get_chunk()``.
+chunksize : int, optional
+    Number of lines to read from the file per chunk. Passing a value will cause the
+    function to return a ``TextFileReader`` object for iteration.
+    See the `IO Tools docs
+    `_
+    for more information on ``iterator`` and ``chunksize``.
+
+{decompression_options}
+
+    .. versionchanged:: 1.4.0 Zstandard support.
+
+thousands : str (length 1), optional
+    Character acting as the thousands separator in numerical values.
+decimal : str (length 1), default '.'
+    Character to recognize as decimal point (e.g., use ',' for European data).
+lineterminator : str (length 1), optional
+    Character used to denote a line break. Only valid with C parser.
+quotechar : str (length 1), optional
+    Character used to denote the start and end of a quoted item. Quoted
+    items can include the ``delimiter`` and it will be ignored.
+quoting : {{0 or csv.QUOTE_MINIMAL, 1 or csv.QUOTE_ALL, 2 or csv.QUOTE_NONNUMERIC, \
+3 or csv.QUOTE_NONE}}, default csv.QUOTE_MINIMAL
+    Control field quoting behavior per ``csv.QUOTE_*`` constants. Default is
+    ``csv.QUOTE_MINIMAL`` (i.e., 0) which implies that only fields containing special
+    characters are quoted (e.g., characters defined in ``quotechar``, ``delimiter``,
+    or ``lineterminator``.
+doublequote : bool, default True
+   When ``quotechar`` is specified and ``quoting`` is not ``QUOTE_NONE``, indicate
+   whether or not to interpret two consecutive ``quotechar`` elements INSIDE a
+   field as a single ``quotechar`` element.
+escapechar : str (length 1), optional
+    Character used to escape other characters.
+comment : str (length 1), optional
+    Character indicating that the remainder of line should not be parsed.
+    If found at the beginning
+    of a line, the line will be ignored altogether. This parameter must be a
+    single character. Like empty lines (as long as ``skip_blank_lines=True``),
+    fully commented lines are ignored by the parameter ``header`` but not by
+    ``skiprows``. For example, if ``comment='#'``, parsing
+    ``#empty\\na,b,c\\n1,2,3`` with ``header=0`` will result in ``'a,b,c'`` being
+    treated as the header.
+encoding : str, optional, default 'utf-8'
+    Encoding to use for UTF when reading/writing (ex. ``'utf-8'``). `List of Python
+    standard encodings
+    `_ .
+
+encoding_errors : str, optional, default 'strict'
+    How encoding errors are treated. `List of possible values
+    `_ .
+
+    .. versionadded:: 1.3.0
+
+dialect : str or csv.Dialect, optional
+    If provided, this parameter will override values (default or not) for the
+    following parameters: ``delimiter``, ``doublequote``, ``escapechar``,
+    ``skipinitialspace``, ``quotechar``, and ``quoting``. If it is necessary to
+    override values, a ``ParserWarning`` will be issued. See ``csv.Dialect``
+    documentation for more details.
+on_bad_lines : {{'error', 'warn', 'skip'}} or Callable, default 'error'
+    Specifies what to do upon encountering a bad line (a line with too many fields).
+    Allowed values are :
+
+    - ``'error'``, raise an Exception when a bad line is encountered.
+    - ``'warn'``, raise a warning when a bad line is encountered and skip that line.
+    - ``'skip'``, skip bad lines without raising or warning when they are encountered.
+
+    .. versionadded:: 1.3.0
+
+    .. versionadded:: 1.4.0
+
+        - Callable, function with signature
+          ``(bad_line: list[str]) -> list[str] | None`` that will process a single
+          bad line. ``bad_line`` is a list of strings split by the ``sep``.
+          If the function returns ``None``, the bad line will be ignored.
+          If the function returns a new ``list`` of strings with more elements than
+          expected, a ``ParserWarning`` will be emitted while dropping extra elements.
+          Only supported when ``engine='python'``
+
+    .. versionchanged:: 2.2.0
+
+        - Callable, function with signature
+          as described in `pyarrow documentation
+          `_ when ``engine='pyarrow'``
+
+delim_whitespace : bool, default False
+    Specifies whether or not whitespace (e.g. ``' '`` or ``'\\t'``) will be
+    used as the ``sep`` delimiter. Equivalent to setting ``sep='\\s+'``. If this option
+    is set to ``True``, nothing should be passed in for the ``delimiter``
+    parameter.
+
+    .. deprecated:: 2.2.0
+        Use ``sep="\\s+"`` instead.
+low_memory : bool, default True
+    Internally process the file in chunks, resulting in lower memory use
+    while parsing, but possibly mixed type inference.  To ensure no mixed
+    types either set ``False``, or specify the type with the ``dtype`` parameter.
+    Note that the entire file is read into a single :class:`~pandas.DataFrame`
+    regardless, use the ``chunksize`` or ``iterator`` parameter to return the data in
+    chunks. (Only valid with C parser).
+memory_map : bool, default False
+    If a filepath is provided for ``filepath_or_buffer``, map the file object
+    directly onto memory and access the data directly from there. Using this
+    option can improve performance because there is no longer any I/O overhead.
+float_precision : {{'high', 'legacy', 'round_trip'}}, optional
+    Specifies which converter the C engine should use for floating-point
+    values. The options are ``None`` or ``'high'`` for the ordinary converter,
+    ``'legacy'`` for the original lower precision pandas converter, and
+    ``'round_trip'`` for the round-trip converter.
+
+{storage_options}
+
+dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+    Back-end data type applied to the resultant :class:`DataFrame`
+    (still experimental). Behaviour is as follows:
+
+    * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+      (default).
+    * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+      DataFrame.
+
+    .. versionadded:: 2.0
+
+Returns
+-------
+DataFrame or TextFileReader
+    A comma-separated values (csv) file is returned as two-dimensional
+    data structure with labeled axes.
+
+See Also
+--------
+DataFrame.to_csv : Write DataFrame to a comma-separated values (csv) file.
+{see_also_func_name} : {see_also_func_summary}
+read_fwf : Read a table of fixed-width formatted lines into DataFrame.
+
+Examples
+--------
+>>> pd.{func_name}('data.csv')  # doctest: +SKIP
+"""
+)
+
+
+class _C_Parser_Defaults(TypedDict):
+    delim_whitespace: Literal[False]
+    na_filter: Literal[True]
+    low_memory: Literal[True]
+    memory_map: Literal[False]
+    float_precision: None
+
+
+_c_parser_defaults: _C_Parser_Defaults = {
+    "delim_whitespace": False,
+    "na_filter": True,
+    "low_memory": True,
+    "memory_map": False,
+    "float_precision": None,
+}
+
+
+class _Fwf_Defaults(TypedDict):
+    colspecs: Literal["infer"]
+    infer_nrows: Literal[100]
+    widths: None
+
+
+_fwf_defaults: _Fwf_Defaults = {"colspecs": "infer", "infer_nrows": 100, "widths": None}
+_c_unsupported = {"skipfooter"}
+_python_unsupported = {"low_memory", "float_precision"}
+_pyarrow_unsupported = {
+    "skipfooter",
+    "float_precision",
+    "chunksize",
+    "comment",
+    "nrows",
+    "thousands",
+    "memory_map",
+    "dialect",
+    "delim_whitespace",
+    "quoting",
+    "lineterminator",
+    "converters",
+    "iterator",
+    "dayfirst",
+    "verbose",
+    "skipinitialspace",
+    "low_memory",
+}
+
+
+class _DeprecationConfig(NamedTuple):
+    default_value: Any
+    msg: str | None
+
+
+@overload
+def validate_integer(name: str, val: None, min_val: int = ...) -> None:
+    ...
+
+
+@overload
+def validate_integer(name: str, val: float, min_val: int = ...) -> int:
+    ...
+
+
+@overload
+def validate_integer(name: str, val: int | None, min_val: int = ...) -> int | None:
+    ...
+
+
+def validate_integer(
+    name: str, val: int | float | None, min_val: int = 0
+) -> int | None:
+    """
+    Checks whether the 'name' parameter for parsing is either
+    an integer OR float that can SAFELY be cast to an integer
+    without losing accuracy. Raises a ValueError if that is
+    not the case.
+
+    Parameters
+    ----------
+    name : str
+        Parameter name (used for error reporting)
+    val : int or float
+        The value to check
+    min_val : int
+        Minimum allowed value (val < min_val will result in a ValueError)
+    """
+    if val is None:
+        return val
+
+    msg = f"'{name:s}' must be an integer >={min_val:d}"
+    if is_float(val):
+        if int(val) != val:
+            raise ValueError(msg)
+        val = int(val)
+    elif not (is_integer(val) and val >= min_val):
+        raise ValueError(msg)
+
+    return int(val)
+
+
+def _validate_names(names: Sequence[Hashable] | None) -> None:
+    """
+    Raise ValueError if the `names` parameter contains duplicates or has an
+    invalid data type.
+
+    Parameters
+    ----------
+    names : array-like or None
+        An array containing a list of the names used for the output DataFrame.
+
+    Raises
+    ------
+    ValueError
+        If names are not unique or are not ordered (e.g. set).
+    """
+    if names is not None:
+        if len(names) != len(set(names)):
+            raise ValueError("Duplicate names are not allowed.")
+        if not (
+            is_list_like(names, allow_sets=False) or isinstance(names, abc.KeysView)
+        ):
+            raise ValueError("Names should be an ordered collection.")
+
+
+def _read(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str], kwds
+) -> DataFrame | TextFileReader:
+    """Generic reader of line files."""
+    # if we pass a date_parser and parse_dates=False, we should not parse the
+    # dates GH#44366
+    if kwds.get("parse_dates", None) is None:
+        if (
+            kwds.get("date_parser", lib.no_default) is lib.no_default
+            and kwds.get("date_format", None) is None
+        ):
+            kwds["parse_dates"] = False
+        else:
+            kwds["parse_dates"] = True
+
+    # Extract some of the arguments (pass chunksize on).
+    iterator = kwds.get("iterator", False)
+    chunksize = kwds.get("chunksize", None)
+    if kwds.get("engine") == "pyarrow":
+        if iterator:
+            raise ValueError(
+                "The 'iterator' option is not supported with the 'pyarrow' engine"
+            )
+
+        if chunksize is not None:
+            raise ValueError(
+                "The 'chunksize' option is not supported with the 'pyarrow' engine"
+            )
+    else:
+        chunksize = validate_integer("chunksize", chunksize, 1)
+
+    nrows = kwds.get("nrows", None)
+
+    # Check for duplicates in names.
+    _validate_names(kwds.get("names", None))
+
+    # Create the parser.
+    parser = TextFileReader(filepath_or_buffer, **kwds)
+
+    if chunksize or iterator:
+        return parser
+
+    with parser:
+        return parser.read(nrows)
+
+
+# iterator=True -> TextFileReader
+@overload
+def read_csv(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Hashable
+    | Iterable[Hashable]
+    | Mapping[Hashable, Iterable[Hashable]]
+    | None = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] | None = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[True],
+    chunksize: int | None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool | lib.NoDefault = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy"] | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> TextFileReader:
+    ...
+
+
+# chunksize=int -> TextFileReader
+@overload
+def read_csv(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Hashable
+    | Iterable[Hashable]
+    | Mapping[Hashable, Iterable[Hashable]]
+    | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] | None = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: bool = ...,
+    chunksize: int,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool | lib.NoDefault = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy"] | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> TextFileReader:
+    ...
+
+
+# default case -> DataFrame
+@overload
+def read_csv(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Hashable
+    | Iterable[Hashable]
+    | Mapping[Hashable, Iterable[Hashable]]
+    | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] | None = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[False] = ...,
+    chunksize: None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool | lib.NoDefault = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy"] | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame:
+    ...
+
+
+# Unions -> DataFrame | TextFileReader
+@overload
+def read_csv(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Hashable
+    | Iterable[Hashable]
+    | Mapping[Hashable, Iterable[Hashable]]
+    | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] | None = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: bool = ...,
+    chunksize: int | None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool | lib.NoDefault = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: Literal["high", "legacy"] | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame | TextFileReader:
+    ...
+
+
+@Appender(
+    _doc_read_csv_and_table.format(
+        func_name="read_csv",
+        summary="Read a comma-separated values (csv) file into DataFrame.",
+        see_also_func_name="read_table",
+        see_also_func_summary="Read general delimited file into DataFrame.",
+        _default_sep="','",
+        storage_options=_shared_docs["storage_options"],
+        decompression_options=_shared_docs["decompression_options"]
+        % "filepath_or_buffer",
+    )
+)
+def read_csv(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = lib.no_default,
+    delimiter: str | None | lib.NoDefault = None,
+    # Column and Index Locations and Names
+    header: int | Sequence[int] | None | Literal["infer"] = "infer",
+    names: Sequence[Hashable] | None | lib.NoDefault = lib.no_default,
+    index_col: IndexLabel | Literal[False] | None = None,
+    usecols: UsecolsArgType = None,
+    # General Parsing Configuration
+    dtype: DtypeArg | None = None,
+    engine: CSVEngine | None = None,
+    converters: Mapping[Hashable, Callable] | None = None,
+    true_values: list | None = None,
+    false_values: list | None = None,
+    skipinitialspace: bool = False,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = None,
+    skipfooter: int = 0,
+    nrows: int | None = None,
+    # NA and Missing Data Handling
+    na_values: Hashable
+    | Iterable[Hashable]
+    | Mapping[Hashable, Iterable[Hashable]]
+    | None = None,
+    keep_default_na: bool = True,
+    na_filter: bool = True,
+    verbose: bool | lib.NoDefault = lib.no_default,
+    skip_blank_lines: bool = True,
+    # Datetime Handling
+    parse_dates: bool | Sequence[Hashable] | None = None,
+    infer_datetime_format: bool | lib.NoDefault = lib.no_default,
+    keep_date_col: bool | lib.NoDefault = lib.no_default,
+    date_parser: Callable | lib.NoDefault = lib.no_default,
+    date_format: str | dict[Hashable, str] | None = None,
+    dayfirst: bool = False,
+    cache_dates: bool = True,
+    # Iteration
+    iterator: bool = False,
+    chunksize: int | None = None,
+    # Quoting, Compression, and File Format
+    compression: CompressionOptions = "infer",
+    thousands: str | None = None,
+    decimal: str = ".",
+    lineterminator: str | None = None,
+    quotechar: str = '"',
+    quoting: int = csv.QUOTE_MINIMAL,
+    doublequote: bool = True,
+    escapechar: str | None = None,
+    comment: str | None = None,
+    encoding: str | None = None,
+    encoding_errors: str | None = "strict",
+    dialect: str | csv.Dialect | None = None,
+    # Error Handling
+    on_bad_lines: str = "error",
+    # Internal
+    delim_whitespace: bool | lib.NoDefault = lib.no_default,
+    low_memory: bool = _c_parser_defaults["low_memory"],
+    memory_map: bool = False,
+    float_precision: Literal["high", "legacy"] | None = None,
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame | TextFileReader:
+    if keep_date_col is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'keep_date_col' keyword in pd.read_csv is deprecated and "
+            "will be removed in a future version. Explicitly remove unwanted "
+            "columns after parsing instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        keep_date_col = False
+
+    if lib.is_list_like(parse_dates):
+        # GH#55569
+        depr = False
+        # error: Item "bool" of "bool | Sequence[Hashable] | None" has no
+        # attribute "__iter__" (not iterable)
+        if not all(is_hashable(x) for x in parse_dates):  # type: ignore[union-attr]
+            depr = True
+        elif isinstance(parse_dates, dict) and any(
+            lib.is_list_like(x) for x in parse_dates.values()
+        ):
+            depr = True
+        if depr:
+            warnings.warn(
+                "Support for nested sequences for 'parse_dates' in pd.read_csv "
+                "is deprecated. Combine the desired columns with pd.to_datetime "
+                "after parsing instead.",
+                FutureWarning,
+                stacklevel=find_stack_level(),
+            )
+
+    if infer_datetime_format is not lib.no_default:
+        warnings.warn(
+            "The argument 'infer_datetime_format' is deprecated and will "
+            "be removed in a future version. "
+            "A strict version of it is now the default, see "
+            "https://pandas.pydata.org/pdeps/0004-consistent-to-datetime-parsing.html. "
+            "You can safely remove this argument.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if delim_whitespace is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'delim_whitespace' keyword in pd.read_csv is deprecated and "
+            "will be removed in a future version. Use ``sep='\\s+'`` instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        delim_whitespace = False
+
+    if verbose is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'verbose' keyword in pd.read_csv is deprecated and "
+            "will be removed in a future version.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        verbose = False
+
+    # locals() should never be modified
+    kwds = locals().copy()
+    del kwds["filepath_or_buffer"]
+    del kwds["sep"]
+
+    kwds_defaults = _refine_defaults_read(
+        dialect,
+        delimiter,
+        delim_whitespace,
+        engine,
+        sep,
+        on_bad_lines,
+        names,
+        defaults={"delimiter": ","},
+        dtype_backend=dtype_backend,
+    )
+    kwds.update(kwds_defaults)
+
+    return _read(filepath_or_buffer, kwds)
+
+
+# iterator=True -> TextFileReader
+@overload
+def read_table(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | Mapping[str, Sequence[str]] | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[True],
+    chunksize: int | None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: str | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> TextFileReader:
+    ...
+
+
+# chunksize=int -> TextFileReader
+@overload
+def read_table(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | Mapping[str, Sequence[str]] | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: bool = ...,
+    chunksize: int,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: str | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> TextFileReader:
+    ...
+
+
+# default -> DataFrame
+@overload
+def read_table(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | Mapping[str, Sequence[str]] | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: Literal[False] = ...,
+    chunksize: None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: str | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame:
+    ...
+
+
+# Unions -> DataFrame | TextFileReader
+@overload
+def read_table(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = ...,
+    delimiter: str | None | lib.NoDefault = ...,
+    header: int | Sequence[int] | None | Literal["infer"] = ...,
+    names: Sequence[Hashable] | None | lib.NoDefault = ...,
+    index_col: IndexLabel | Literal[False] | None = ...,
+    usecols: UsecolsArgType = ...,
+    dtype: DtypeArg | None = ...,
+    engine: CSVEngine | None = ...,
+    converters: Mapping[Hashable, Callable] | None = ...,
+    true_values: list | None = ...,
+    false_values: list | None = ...,
+    skipinitialspace: bool = ...,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = ...,
+    skipfooter: int = ...,
+    nrows: int | None = ...,
+    na_values: Sequence[str] | Mapping[str, Sequence[str]] | None = ...,
+    keep_default_na: bool = ...,
+    na_filter: bool = ...,
+    verbose: bool | lib.NoDefault = ...,
+    skip_blank_lines: bool = ...,
+    parse_dates: bool | Sequence[Hashable] = ...,
+    infer_datetime_format: bool | lib.NoDefault = ...,
+    keep_date_col: bool | lib.NoDefault = ...,
+    date_parser: Callable | lib.NoDefault = ...,
+    date_format: str | dict[Hashable, str] | None = ...,
+    dayfirst: bool = ...,
+    cache_dates: bool = ...,
+    iterator: bool = ...,
+    chunksize: int | None = ...,
+    compression: CompressionOptions = ...,
+    thousands: str | None = ...,
+    decimal: str = ...,
+    lineterminator: str | None = ...,
+    quotechar: str = ...,
+    quoting: int = ...,
+    doublequote: bool = ...,
+    escapechar: str | None = ...,
+    comment: str | None = ...,
+    encoding: str | None = ...,
+    encoding_errors: str | None = ...,
+    dialect: str | csv.Dialect | None = ...,
+    on_bad_lines=...,
+    delim_whitespace: bool = ...,
+    low_memory: bool = ...,
+    memory_map: bool = ...,
+    float_precision: str | None = ...,
+    storage_options: StorageOptions = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame | TextFileReader:
+    ...
+
+
+@Appender(
+    _doc_read_csv_and_table.format(
+        func_name="read_table",
+        summary="Read general delimited file into DataFrame.",
+        see_also_func_name="read_csv",
+        see_also_func_summary=(
+            "Read a comma-separated values (csv) file into DataFrame."
+        ),
+        _default_sep=r"'\\t' (tab-stop)",
+        storage_options=_shared_docs["storage_options"],
+        decompression_options=_shared_docs["decompression_options"]
+        % "filepath_or_buffer",
+    )
+)
+def read_table(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    sep: str | None | lib.NoDefault = lib.no_default,
+    delimiter: str | None | lib.NoDefault = None,
+    # Column and Index Locations and Names
+    header: int | Sequence[int] | None | Literal["infer"] = "infer",
+    names: Sequence[Hashable] | None | lib.NoDefault = lib.no_default,
+    index_col: IndexLabel | Literal[False] | None = None,
+    usecols: UsecolsArgType = None,
+    # General Parsing Configuration
+    dtype: DtypeArg | None = None,
+    engine: CSVEngine | None = None,
+    converters: Mapping[Hashable, Callable] | None = None,
+    true_values: list | None = None,
+    false_values: list | None = None,
+    skipinitialspace: bool = False,
+    skiprows: list[int] | int | Callable[[Hashable], bool] | None = None,
+    skipfooter: int = 0,
+    nrows: int | None = None,
+    # NA and Missing Data Handling
+    na_values: Sequence[str] | Mapping[str, Sequence[str]] | None = None,
+    keep_default_na: bool = True,
+    na_filter: bool = True,
+    verbose: bool | lib.NoDefault = lib.no_default,
+    skip_blank_lines: bool = True,
+    # Datetime Handling
+    parse_dates: bool | Sequence[Hashable] = False,
+    infer_datetime_format: bool | lib.NoDefault = lib.no_default,
+    keep_date_col: bool | lib.NoDefault = lib.no_default,
+    date_parser: Callable | lib.NoDefault = lib.no_default,
+    date_format: str | dict[Hashable, str] | None = None,
+    dayfirst: bool = False,
+    cache_dates: bool = True,
+    # Iteration
+    iterator: bool = False,
+    chunksize: int | None = None,
+    # Quoting, Compression, and File Format
+    compression: CompressionOptions = "infer",
+    thousands: str | None = None,
+    decimal: str = ".",
+    lineterminator: str | None = None,
+    quotechar: str = '"',
+    quoting: int = csv.QUOTE_MINIMAL,
+    doublequote: bool = True,
+    escapechar: str | None = None,
+    comment: str | None = None,
+    encoding: str | None = None,
+    encoding_errors: str | None = "strict",
+    dialect: str | csv.Dialect | None = None,
+    # Error Handling
+    on_bad_lines: str = "error",
+    # Internal
+    delim_whitespace: bool | lib.NoDefault = lib.no_default,
+    low_memory: bool = _c_parser_defaults["low_memory"],
+    memory_map: bool = False,
+    float_precision: str | None = None,
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame | TextFileReader:
+    if keep_date_col is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'keep_date_col' keyword in pd.read_table is deprecated and "
+            "will be removed in a future version. Explicitly remove unwanted "
+            "columns after parsing instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        keep_date_col = False
+
+    # error: Item "bool" of "bool | Sequence[Hashable]" has no attribute "__iter__"
+    if lib.is_list_like(parse_dates) and not all(is_hashable(x) for x in parse_dates):  # type: ignore[union-attr]
+        # GH#55569
+        warnings.warn(
+            "Support for nested sequences for 'parse_dates' in pd.read_table "
+            "is deprecated. Combine the desired columns with pd.to_datetime "
+            "after parsing instead.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if infer_datetime_format is not lib.no_default:
+        warnings.warn(
+            "The argument 'infer_datetime_format' is deprecated and will "
+            "be removed in a future version. "
+            "A strict version of it is now the default, see "
+            "https://pandas.pydata.org/pdeps/0004-consistent-to-datetime-parsing.html. "
+            "You can safely remove this argument.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if delim_whitespace is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'delim_whitespace' keyword in pd.read_table is deprecated and "
+            "will be removed in a future version. Use ``sep='\\s+'`` instead",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        delim_whitespace = False
+
+    if verbose is not lib.no_default:
+        # GH#55569
+        warnings.warn(
+            "The 'verbose' keyword in pd.read_table is deprecated and "
+            "will be removed in a future version.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+    else:
+        verbose = False
+
+    # locals() should never be modified
+    kwds = locals().copy()
+    del kwds["filepath_or_buffer"]
+    del kwds["sep"]
+
+    kwds_defaults = _refine_defaults_read(
+        dialect,
+        delimiter,
+        delim_whitespace,
+        engine,
+        sep,
+        on_bad_lines,
+        names,
+        defaults={"delimiter": "\t"},
+        dtype_backend=dtype_backend,
+    )
+    kwds.update(kwds_defaults)
+
+    return _read(filepath_or_buffer, kwds)
+
+
+@overload
+def read_fwf(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    colspecs: Sequence[tuple[int, int]] | str | None = ...,
+    widths: Sequence[int] | None = ...,
+    infer_nrows: int = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    iterator: Literal[True],
+    chunksize: int | None = ...,
+    **kwds,
+) -> TextFileReader:
+    ...
+
+
+@overload
+def read_fwf(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    colspecs: Sequence[tuple[int, int]] | str | None = ...,
+    widths: Sequence[int] | None = ...,
+    infer_nrows: int = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    iterator: bool = ...,
+    chunksize: int,
+    **kwds,
+) -> TextFileReader:
+    ...
+
+
+@overload
+def read_fwf(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    colspecs: Sequence[tuple[int, int]] | str | None = ...,
+    widths: Sequence[int] | None = ...,
+    infer_nrows: int = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    iterator: Literal[False] = ...,
+    chunksize: None = ...,
+    **kwds,
+) -> DataFrame:
+    ...
+
+
+def read_fwf(
+    filepath_or_buffer: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str],
+    *,
+    colspecs: Sequence[tuple[int, int]] | str | None = "infer",
+    widths: Sequence[int] | None = None,
+    infer_nrows: int = 100,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    iterator: bool = False,
+    chunksize: int | None = None,
+    **kwds,
+) -> DataFrame | TextFileReader:
+    r"""
+    Read a table of fixed-width formatted lines into DataFrame.
+
+    Also supports optionally iterating or breaking of the file
+    into chunks.
+
+    Additional help can be found in the `online docs for IO Tools
+    `_.
+
+    Parameters
+    ----------
+    filepath_or_buffer : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a text ``read()`` function.The string could be a URL.
+        Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.csv``.
+    colspecs : list of tuple (int, int) or 'infer'. optional
+        A list of tuples giving the extents of the fixed-width
+        fields of each line as half-open intervals (i.e.,  [from, to[ ).
+        String value 'infer' can be used to instruct the parser to try
+        detecting the column specifications from the first 100 rows of
+        the data which are not being skipped via skiprows (default='infer').
+    widths : list of int, optional
+        A list of field widths which can be used instead of 'colspecs' if
+        the intervals are contiguous.
+    infer_nrows : int, default 100
+        The number of rows to consider when letting the parser determine the
+        `colspecs`.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    **kwds : optional
+        Optional keyword arguments can be passed to ``TextFileReader``.
+
+    Returns
+    -------
+    DataFrame or TextFileReader
+        A comma-separated values (csv) file is returned as two-dimensional
+        data structure with labeled axes.
+
+    See Also
+    --------
+    DataFrame.to_csv : Write DataFrame to a comma-separated values (csv) file.
+    read_csv : Read a comma-separated values (csv) file into DataFrame.
+
+    Examples
+    --------
+    >>> pd.read_fwf('data.csv')  # doctest: +SKIP
+    """
+    # Check input arguments.
+    if colspecs is None and widths is None:
+        raise ValueError("Must specify either colspecs or widths")
+    if colspecs not in (None, "infer") and widths is not None:
+        raise ValueError("You must specify only one of 'widths' and 'colspecs'")
+
+    # Compute 'colspecs' from 'widths', if specified.
+    if widths is not None:
+        colspecs, col = [], 0
+        for w in widths:
+            colspecs.append((col, col + w))
+            col += w
+
+    # for mypy
+    assert colspecs is not None
+
+    # GH#40830
+    # Ensure length of `colspecs` matches length of `names`
+    names = kwds.get("names")
+    if names is not None:
+        if len(names) != len(colspecs) and colspecs != "infer":
+            # need to check len(index_col) as it might contain
+            # unnamed indices, in which case it's name is not required
+            len_index = 0
+            if kwds.get("index_col") is not None:
+                index_col: Any = kwds.get("index_col")
+                if index_col is not False:
+                    if not is_list_like(index_col):
+                        len_index = 1
+                    else:
+                        len_index = len(index_col)
+            if kwds.get("usecols") is None and len(names) + len_index != len(colspecs):
+                # If usecols is used colspec may be longer than names
+                raise ValueError("Length of colspecs must match length of names")
+
+    kwds["colspecs"] = colspecs
+    kwds["infer_nrows"] = infer_nrows
+    kwds["engine"] = "python-fwf"
+    kwds["iterator"] = iterator
+    kwds["chunksize"] = chunksize
+
+    check_dtype_backend(dtype_backend)
+    kwds["dtype_backend"] = dtype_backend
+    return _read(filepath_or_buffer, kwds)
+
+
+class TextFileReader(abc.Iterator):
+    """
+
+    Passed dialect overrides any of the related parser options
+
+    """
+
+    def __init__(
+        self,
+        f: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str] | list,
+        engine: CSVEngine | None = None,
+        **kwds,
+    ) -> None:
+        if engine is not None:
+            engine_specified = True
+        else:
+            engine = "python"
+            engine_specified = False
+        self.engine = engine
+        self._engine_specified = kwds.get("engine_specified", engine_specified)
+
+        _validate_skipfooter(kwds)
+
+        dialect = _extract_dialect(kwds)
+        if dialect is not None:
+            if engine == "pyarrow":
+                raise ValueError(
+                    "The 'dialect' option is not supported with the 'pyarrow' engine"
+                )
+            kwds = _merge_with_dialect_properties(dialect, kwds)
+
+        if kwds.get("header", "infer") == "infer":
+            kwds["header"] = 0 if kwds.get("names") is None else None
+
+        self.orig_options = kwds
+
+        # miscellanea
+        self._currow = 0
+
+        options = self._get_options_with_defaults(engine)
+        options["storage_options"] = kwds.get("storage_options", None)
+
+        self.chunksize = options.pop("chunksize", None)
+        self.nrows = options.pop("nrows", None)
+
+        self._check_file_or_buffer(f, engine)
+        self.options, self.engine = self._clean_options(options, engine)
+
+        if "has_index_names" in kwds:
+            self.options["has_index_names"] = kwds["has_index_names"]
+
+        self.handles: IOHandles | None = None
+        self._engine = self._make_engine(f, self.engine)
+
+    def close(self) -> None:
+        if self.handles is not None:
+            self.handles.close()
+        self._engine.close()
+
+    def _get_options_with_defaults(self, engine: CSVEngine) -> dict[str, Any]:
+        kwds = self.orig_options
+
+        options = {}
+        default: object | None
+
+        for argname, default in parser_defaults.items():
+            value = kwds.get(argname, default)
+
+            # see gh-12935
+            if (
+                engine == "pyarrow"
+                and argname in _pyarrow_unsupported
+                and value != default
+                and value != getattr(value, "value", default)
+            ):
+                raise ValueError(
+                    f"The {repr(argname)} option is not supported with the "
+                    f"'pyarrow' engine"
+                )
+            options[argname] = value
+
+        for argname, default in _c_parser_defaults.items():
+            if argname in kwds:
+                value = kwds[argname]
+
+                if engine != "c" and value != default:
+                    # TODO: Refactor this logic, its pretty convoluted
+                    if "python" in engine and argname not in _python_unsupported:
+                        pass
+                    elif "pyarrow" in engine and argname not in _pyarrow_unsupported:
+                        pass
+                    else:
+                        raise ValueError(
+                            f"The {repr(argname)} option is not supported with the "
+                            f"{repr(engine)} engine"
+                        )
+            else:
+                value = default
+            options[argname] = value
+
+        if engine == "python-fwf":
+            for argname, default in _fwf_defaults.items():
+                options[argname] = kwds.get(argname, default)
+
+        return options
+
+    def _check_file_or_buffer(self, f, engine: CSVEngine) -> None:
+        # see gh-16530
+        if is_file_like(f) and engine != "c" and not hasattr(f, "__iter__"):
+            # The C engine doesn't need the file-like to have the "__iter__"
+            # attribute. However, the Python engine needs "__iter__(...)"
+            # when iterating through such an object, meaning it
+            # needs to have that attribute
+            raise ValueError(
+                "The 'python' engine cannot iterate through this file buffer."
+            )
+
+    def _clean_options(
+        self, options: dict[str, Any], engine: CSVEngine
+    ) -> tuple[dict[str, Any], CSVEngine]:
+        result = options.copy()
+
+        fallback_reason = None
+
+        # C engine not supported yet
+        if engine == "c":
+            if options["skipfooter"] > 0:
+                fallback_reason = "the 'c' engine does not support skipfooter"
+                engine = "python"
+
+        sep = options["delimiter"]
+        delim_whitespace = options["delim_whitespace"]
+
+        if sep is None and not delim_whitespace:
+            if engine in ("c", "pyarrow"):
+                fallback_reason = (
+                    f"the '{engine}' engine does not support "
+                    "sep=None with delim_whitespace=False"
+                )
+                engine = "python"
+        elif sep is not None and len(sep) > 1:
+            if engine == "c" and sep == r"\s+":
+                result["delim_whitespace"] = True
+                del result["delimiter"]
+            elif engine not in ("python", "python-fwf"):
+                # wait until regex engine integrated
+                fallback_reason = (
+                    f"the '{engine}' engine does not support "
+                    "regex separators (separators > 1 char and "
+                    r"different from '\s+' are interpreted as regex)"
+                )
+                engine = "python"
+        elif delim_whitespace:
+            if "python" in engine:
+                result["delimiter"] = r"\s+"
+        elif sep is not None:
+            encodeable = True
+            encoding = sys.getfilesystemencoding() or "utf-8"
+            try:
+                if len(sep.encode(encoding)) > 1:
+                    encodeable = False
+            except UnicodeDecodeError:
+                encodeable = False
+            if not encodeable and engine not in ("python", "python-fwf"):
+                fallback_reason = (
+                    f"the separator encoded in {encoding} "
+                    f"is > 1 char long, and the '{engine}' engine "
+                    "does not support such separators"
+                )
+                engine = "python"
+
+        quotechar = options["quotechar"]
+        if quotechar is not None and isinstance(quotechar, (str, bytes)):
+            if (
+                len(quotechar) == 1
+                and ord(quotechar) > 127
+                and engine not in ("python", "python-fwf")
+            ):
+                fallback_reason = (
+                    "ord(quotechar) > 127, meaning the "
+                    "quotechar is larger than one byte, "
+                    f"and the '{engine}' engine does not support such quotechars"
+                )
+                engine = "python"
+
+        if fallback_reason and self._engine_specified:
+            raise ValueError(fallback_reason)
+
+        if engine == "c":
+            for arg in _c_unsupported:
+                del result[arg]
+
+        if "python" in engine:
+            for arg in _python_unsupported:
+                if fallback_reason and result[arg] != _c_parser_defaults.get(arg):
+                    raise ValueError(
+                        "Falling back to the 'python' engine because "
+                        f"{fallback_reason}, but this causes {repr(arg)} to be "
+                        "ignored as it is not supported by the 'python' engine."
+                    )
+                del result[arg]
+
+        if fallback_reason:
+            warnings.warn(
+                (
+                    "Falling back to the 'python' engine because "
+                    f"{fallback_reason}; you can avoid this warning by specifying "
+                    "engine='python'."
+                ),
+                ParserWarning,
+                stacklevel=find_stack_level(),
+            )
+
+        index_col = options["index_col"]
+        names = options["names"]
+        converters = options["converters"]
+        na_values = options["na_values"]
+        skiprows = options["skiprows"]
+
+        validate_header_arg(options["header"])
+
+        if index_col is True:
+            raise ValueError("The value of index_col couldn't be 'True'")
+        if is_index_col(index_col):
+            if not isinstance(index_col, (list, tuple, np.ndarray)):
+                index_col = [index_col]
+        result["index_col"] = index_col
+
+        names = list(names) if names is not None else names
+
+        # type conversion-related
+        if converters is not None:
+            if not isinstance(converters, dict):
+                raise TypeError(
+                    "Type converters must be a dict or subclass, "
+                    f"input was a {type(converters).__name__}"
+                )
+        else:
+            converters = {}
+
+        # Converting values to NA
+        keep_default_na = options["keep_default_na"]
+        floatify = engine != "pyarrow"
+        na_values, na_fvalues = _clean_na_values(
+            na_values, keep_default_na, floatify=floatify
+        )
+
+        # handle skiprows; this is internally handled by the
+        # c-engine, so only need for python and pyarrow parsers
+        if engine == "pyarrow":
+            if not is_integer(skiprows) and skiprows is not None:
+                # pyarrow expects skiprows to be passed as an integer
+                raise ValueError(
+                    "skiprows argument must be an integer when using "
+                    "engine='pyarrow'"
+                )
+        else:
+            if is_integer(skiprows):
+                skiprows = list(range(skiprows))
+            if skiprows is None:
+                skiprows = set()
+            elif not callable(skiprows):
+                skiprows = set(skiprows)
+
+        # put stuff back
+        result["names"] = names
+        result["converters"] = converters
+        result["na_values"] = na_values
+        result["na_fvalues"] = na_fvalues
+        result["skiprows"] = skiprows
+
+        return result, engine
+
+    def __next__(self) -> DataFrame:
+        try:
+            return self.get_chunk()
+        except StopIteration:
+            self.close()
+            raise
+
+    def _make_engine(
+        self,
+        f: FilePath | ReadCsvBuffer[bytes] | ReadCsvBuffer[str] | list | IO,
+        engine: CSVEngine = "c",
+    ) -> ParserBase:
+        mapping: dict[str, type[ParserBase]] = {
+            "c": CParserWrapper,
+            "python": PythonParser,
+            "pyarrow": ArrowParserWrapper,
+            "python-fwf": FixedWidthFieldParser,
+        }
+        if engine not in mapping:
+            raise ValueError(
+                f"Unknown engine: {engine} (valid options are {mapping.keys()})"
+            )
+        if not isinstance(f, list):
+            # open file here
+            is_text = True
+            mode = "r"
+            if engine == "pyarrow":
+                is_text = False
+                mode = "rb"
+            elif (
+                engine == "c"
+                and self.options.get("encoding", "utf-8") == "utf-8"
+                and isinstance(stringify_path(f), str)
+            ):
+                # c engine can decode utf-8 bytes, adding TextIOWrapper makes
+                # the c-engine especially for memory_map=True far slower
+                is_text = False
+                if "b" not in mode:
+                    mode += "b"
+            self.handles = get_handle(
+                f,
+                mode,
+                encoding=self.options.get("encoding", None),
+                compression=self.options.get("compression", None),
+                memory_map=self.options.get("memory_map", False),
+                is_text=is_text,
+                errors=self.options.get("encoding_errors", "strict"),
+                storage_options=self.options.get("storage_options", None),
+            )
+            assert self.handles is not None
+            f = self.handles.handle
+
+        elif engine != "python":
+            msg = f"Invalid file path or buffer object type: {type(f)}"
+            raise ValueError(msg)
+
+        try:
+            return mapping[engine](f, **self.options)
+        except Exception:
+            if self.handles is not None:
+                self.handles.close()
+            raise
+
+    def _failover_to_python(self) -> None:
+        raise AbstractMethodError(self)
+
+    def read(self, nrows: int | None = None) -> DataFrame:
+        if self.engine == "pyarrow":
+            try:
+                # error: "ParserBase" has no attribute "read"
+                df = self._engine.read()  # type: ignore[attr-defined]
+            except Exception:
+                self.close()
+                raise
+        else:
+            nrows = validate_integer("nrows", nrows)
+            try:
+                # error: "ParserBase" has no attribute "read"
+                (
+                    index,
+                    columns,
+                    col_dict,
+                ) = self._engine.read(  # type: ignore[attr-defined]
+                    nrows
+                )
+            except Exception:
+                self.close()
+                raise
+
+            if index is None:
+                if col_dict:
+                    # Any column is actually fine:
+                    new_rows = len(next(iter(col_dict.values())))
+                    index = RangeIndex(self._currow, self._currow + new_rows)
+                else:
+                    new_rows = 0
+            else:
+                new_rows = len(index)
+
+            if hasattr(self, "orig_options"):
+                dtype_arg = self.orig_options.get("dtype", None)
+            else:
+                dtype_arg = None
+
+            if isinstance(dtype_arg, dict):
+                dtype = defaultdict(lambda: None)  # type: ignore[var-annotated]
+                dtype.update(dtype_arg)
+            elif dtype_arg is not None and pandas_dtype(dtype_arg) in (
+                np.str_,
+                np.object_,
+            ):
+                dtype = defaultdict(lambda: dtype_arg)
+            else:
+                dtype = None
+
+            if dtype is not None:
+                new_col_dict = {}
+                for k, v in col_dict.items():
+                    d = (
+                        dtype[k]
+                        if pandas_dtype(dtype[k]) in (np.str_, np.object_)
+                        else None
+                    )
+                    new_col_dict[k] = Series(v, index=index, dtype=d, copy=False)
+            else:
+                new_col_dict = col_dict
+
+            df = DataFrame(
+                new_col_dict,
+                columns=columns,
+                index=index,
+                copy=not using_copy_on_write(),
+            )
+
+            self._currow += new_rows
+        return df
+
+    def get_chunk(self, size: int | None = None) -> DataFrame:
+        if size is None:
+            size = self.chunksize
+        if self.nrows is not None:
+            if self._currow >= self.nrows:
+                raise StopIteration
+            size = min(size, self.nrows - self._currow)
+        return self.read(nrows=size)
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+def TextParser(*args, **kwds) -> TextFileReader:
+    """
+    Converts lists of lists/tuples into DataFrames with proper type inference
+    and optional (e.g. string to datetime) conversion. Also enables iterating
+    lazily over chunks of large files
+
+    Parameters
+    ----------
+    data : file-like object or list
+    delimiter : separator character to use
+    dialect : str or csv.Dialect instance, optional
+        Ignored if delimiter is longer than 1 character
+    names : sequence, default
+    header : int, default 0
+        Row to use to parse column labels. Defaults to the first row. Prior
+        rows will be discarded
+    index_col : int or list, optional
+        Column or columns to use as the (possibly hierarchical) index
+    has_index_names: bool, default False
+        True if the cols defined in index_col have an index name and are
+        not in the header.
+    na_values : scalar, str, list-like, or dict, optional
+        Additional strings to recognize as NA/NaN.
+    keep_default_na : bool, default True
+    thousands : str, optional
+        Thousands separator
+    comment : str, optional
+        Comment out remainder of line
+    parse_dates : bool, default False
+    keep_date_col : bool, default False
+    date_parser : function, optional
+
+        .. deprecated:: 2.0.0
+    date_format : str or dict of column -> format, default ``None``
+
+        .. versionadded:: 2.0.0
+    skiprows : list of integers
+        Row numbers to skip
+    skipfooter : int
+        Number of line at bottom of file to skip
+    converters : dict, optional
+        Dict of functions for converting values in certain columns. Keys can
+        either be integers or column labels, values are functions that take one
+        input argument, the cell (not column) content, and return the
+        transformed content.
+    encoding : str, optional
+        Encoding to use for UTF when reading/writing (ex. 'utf-8')
+    float_precision : str, optional
+        Specifies which converter the C engine should use for floating-point
+        values. The options are `None` or `high` for the ordinary converter,
+        `legacy` for the original lower precision pandas converter, and
+        `round_trip` for the round-trip converter.
+    """
+    kwds["engine"] = "python"
+    return TextFileReader(*args, **kwds)
+
+
+def _clean_na_values(na_values, keep_default_na: bool = True, floatify: bool = True):
+    na_fvalues: set | dict
+    if na_values is None:
+        if keep_default_na:
+            na_values = STR_NA_VALUES
+        else:
+            na_values = set()
+        na_fvalues = set()
+    elif isinstance(na_values, dict):
+        old_na_values = na_values.copy()
+        na_values = {}  # Prevent aliasing.
+
+        # Convert the values in the na_values dictionary
+        # into array-likes for further use. This is also
+        # where we append the default NaN values, provided
+        # that `keep_default_na=True`.
+        for k, v in old_na_values.items():
+            if not is_list_like(v):
+                v = [v]
+
+            if keep_default_na:
+                v = set(v) | STR_NA_VALUES
+
+            na_values[k] = v
+        na_fvalues = {k: _floatify_na_values(v) for k, v in na_values.items()}
+    else:
+        if not is_list_like(na_values):
+            na_values = [na_values]
+        na_values = _stringify_na_values(na_values, floatify)
+        if keep_default_na:
+            na_values = na_values | STR_NA_VALUES
+
+        na_fvalues = _floatify_na_values(na_values)
+
+    return na_values, na_fvalues
+
+
+def _floatify_na_values(na_values):
+    # create float versions of the na_values
+    result = set()
+    for v in na_values:
+        try:
+            v = float(v)
+            if not np.isnan(v):
+                result.add(v)
+        except (TypeError, ValueError, OverflowError):
+            pass
+    return result
+
+
+def _stringify_na_values(na_values, floatify: bool):
+    """return a stringified and numeric for these values"""
+    result: list[str | float] = []
+    for x in na_values:
+        result.append(str(x))
+        result.append(x)
+        try:
+            v = float(x)
+
+            # we are like 999 here
+            if v == int(v):
+                v = int(v)
+                result.append(f"{v}.0")
+                result.append(str(v))
+
+            if floatify:
+                result.append(v)
+        except (TypeError, ValueError, OverflowError):
+            pass
+        if floatify:
+            try:
+                result.append(int(x))
+            except (TypeError, ValueError, OverflowError):
+                pass
+    return set(result)
+
+
+def _refine_defaults_read(
+    dialect: str | csv.Dialect | None,
+    delimiter: str | None | lib.NoDefault,
+    delim_whitespace: bool,
+    engine: CSVEngine | None,
+    sep: str | None | lib.NoDefault,
+    on_bad_lines: str | Callable,
+    names: Sequence[Hashable] | None | lib.NoDefault,
+    defaults: dict[str, Any],
+    dtype_backend: DtypeBackend | lib.NoDefault,
+):
+    """Validate/refine default values of input parameters of read_csv, read_table.
+
+    Parameters
+    ----------
+    dialect : str or csv.Dialect
+        If provided, this parameter will override values (default or not) for the
+        following parameters: `delimiter`, `doublequote`, `escapechar`,
+        `skipinitialspace`, `quotechar`, and `quoting`. If it is necessary to
+        override values, a ParserWarning will be issued. See csv.Dialect
+        documentation for more details.
+    delimiter : str or object
+        Alias for sep.
+    delim_whitespace : bool
+        Specifies whether or not whitespace (e.g. ``' '`` or ``'\t'``) will be
+        used as the sep. Equivalent to setting ``sep='\\s+'``. If this option
+        is set to True, nothing should be passed in for the ``delimiter``
+        parameter.
+
+        .. deprecated:: 2.2.0
+            Use ``sep="\\s+"`` instead.
+    engine : {{'c', 'python'}}
+        Parser engine to use. The C engine is faster while the python engine is
+        currently more feature-complete.
+    sep : str or object
+        A delimiter provided by the user (str) or a sentinel value, i.e.
+        pandas._libs.lib.no_default.
+    on_bad_lines : str, callable
+        An option for handling bad lines or a sentinel value(None).
+    names : array-like, optional
+        List of column names to use. If the file contains a header row,
+        then you should explicitly pass ``header=0`` to override the column names.
+        Duplicates in this list are not allowed.
+    defaults: dict
+        Default values of input parameters.
+
+    Returns
+    -------
+    kwds : dict
+        Input parameters with correct values.
+
+    Raises
+    ------
+    ValueError :
+        If a delimiter was specified with ``sep`` (or ``delimiter``) and
+        ``delim_whitespace=True``.
+    """
+    # fix types for sep, delimiter to Union(str, Any)
+    delim_default = defaults["delimiter"]
+    kwds: dict[str, Any] = {}
+    # gh-23761
+    #
+    # When a dialect is passed, it overrides any of the overlapping
+    # parameters passed in directly. We don't want to warn if the
+    # default parameters were passed in (since it probably means
+    # that the user didn't pass them in explicitly in the first place).
+    #
+    # "delimiter" is the annoying corner case because we alias it to
+    # "sep" before doing comparison to the dialect values later on.
+    # Thus, we need a flag to indicate that we need to "override"
+    # the comparison to dialect values by checking if default values
+    # for BOTH "delimiter" and "sep" were provided.
+    if dialect is not None:
+        kwds["sep_override"] = delimiter is None and (
+            sep is lib.no_default or sep == delim_default
+        )
+
+    if delimiter and (sep is not lib.no_default):
+        raise ValueError("Specified a sep and a delimiter; you can only specify one.")
+
+    kwds["names"] = None if names is lib.no_default else names
+
+    # Alias sep -> delimiter.
+    if delimiter is None:
+        delimiter = sep
+
+    if delim_whitespace and (delimiter is not lib.no_default):
+        raise ValueError(
+            "Specified a delimiter with both sep and "
+            "delim_whitespace=True; you can only specify one."
+        )
+
+    if delimiter == "\n":
+        raise ValueError(
+            r"Specified \n as separator or delimiter. This forces the python engine "
+            "which does not accept a line terminator. Hence it is not allowed to use "
+            "the line terminator as separator.",
+        )
+
+    if delimiter is lib.no_default:
+        # assign default separator value
+        kwds["delimiter"] = delim_default
+    else:
+        kwds["delimiter"] = delimiter
+
+    if engine is not None:
+        kwds["engine_specified"] = True
+    else:
+        kwds["engine"] = "c"
+        kwds["engine_specified"] = False
+
+    if on_bad_lines == "error":
+        kwds["on_bad_lines"] = ParserBase.BadLineHandleMethod.ERROR
+    elif on_bad_lines == "warn":
+        kwds["on_bad_lines"] = ParserBase.BadLineHandleMethod.WARN
+    elif on_bad_lines == "skip":
+        kwds["on_bad_lines"] = ParserBase.BadLineHandleMethod.SKIP
+    elif callable(on_bad_lines):
+        if engine not in ["python", "pyarrow"]:
+            raise ValueError(
+                "on_bad_line can only be a callable function "
+                "if engine='python' or 'pyarrow'"
+            )
+        kwds["on_bad_lines"] = on_bad_lines
+    else:
+        raise ValueError(f"Argument {on_bad_lines} is invalid for on_bad_lines")
+
+    check_dtype_backend(dtype_backend)
+
+    kwds["dtype_backend"] = dtype_backend
+
+    return kwds
+
+
+def _extract_dialect(kwds: dict[str, Any]) -> csv.Dialect | None:
+    """
+    Extract concrete csv dialect instance.
+
+    Returns
+    -------
+    csv.Dialect or None
+    """
+    if kwds.get("dialect") is None:
+        return None
+
+    dialect = kwds["dialect"]
+    if dialect in csv.list_dialects():
+        dialect = csv.get_dialect(dialect)
+
+    _validate_dialect(dialect)
+
+    return dialect
+
+
+MANDATORY_DIALECT_ATTRS = (
+    "delimiter",
+    "doublequote",
+    "escapechar",
+    "skipinitialspace",
+    "quotechar",
+    "quoting",
+)
+
+
+def _validate_dialect(dialect: csv.Dialect) -> None:
+    """
+    Validate csv dialect instance.
+
+    Raises
+    ------
+    ValueError
+        If incorrect dialect is provided.
+    """
+    for param in MANDATORY_DIALECT_ATTRS:
+        if not hasattr(dialect, param):
+            raise ValueError(f"Invalid dialect {dialect} provided")
+
+
+def _merge_with_dialect_properties(
+    dialect: csv.Dialect,
+    defaults: dict[str, Any],
+) -> dict[str, Any]:
+    """
+    Merge default kwargs in TextFileReader with dialect parameters.
+
+    Parameters
+    ----------
+    dialect : csv.Dialect
+        Concrete csv dialect. See csv.Dialect documentation for more details.
+    defaults : dict
+        Keyword arguments passed to TextFileReader.
+
+    Returns
+    -------
+    kwds : dict
+        Updated keyword arguments, merged with dialect parameters.
+    """
+    kwds = defaults.copy()
+
+    for param in MANDATORY_DIALECT_ATTRS:
+        dialect_val = getattr(dialect, param)
+
+        parser_default = parser_defaults[param]
+        provided = kwds.get(param, parser_default)
+
+        # Messages for conflicting values between the dialect
+        # instance and the actual parameters provided.
+        conflict_msgs = []
+
+        # Don't warn if the default parameter was passed in,
+        # even if it conflicts with the dialect (gh-23761).
+        if provided not in (parser_default, dialect_val):
+            msg = (
+                f"Conflicting values for '{param}': '{provided}' was "
+                f"provided, but the dialect specifies '{dialect_val}'. "
+                "Using the dialect-specified value."
+            )
+
+            # Annoying corner case for not warning about
+            # conflicts between dialect and delimiter parameter.
+            # Refer to the outer "_read_" function for more info.
+            if not (param == "delimiter" and kwds.pop("sep_override", False)):
+                conflict_msgs.append(msg)
+
+        if conflict_msgs:
+            warnings.warn(
+                "\n\n".join(conflict_msgs), ParserWarning, stacklevel=find_stack_level()
+            )
+        kwds[param] = dialect_val
+    return kwds
+
+
+def _validate_skipfooter(kwds: dict[str, Any]) -> None:
+    """
+    Check whether skipfooter is compatible with other kwargs in TextFileReader.
+
+    Parameters
+    ----------
+    kwds : dict
+        Keyword arguments passed to TextFileReader.
+
+    Raises
+    ------
+    ValueError
+        If skipfooter is not compatible with other parameters.
+    """
+    if kwds.get("skipfooter"):
+        if kwds.get("iterator") or kwds.get("chunksize"):
+            raise ValueError("'skipfooter' not supported for iteration")
+        if kwds.get("nrows"):
+            raise ValueError("'skipfooter' not supported with 'nrows'")
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/pickle.py b/.venv/lib/python3.13/site-packages/pandas/io/pickle.py
new file mode 100644
index 0000000000000000000000000000000000000000..0dae0e7106b69a471f0c2702158cfe0f11f0389c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/pickle.py
@@ -0,0 +1,210 @@
+""" pickle compat """
+from __future__ import annotations
+
+import pickle
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+import warnings
+
+from pandas.compat import pickle_compat as pc
+from pandas.util._decorators import doc
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import get_handle
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        ReadPickleBuffer,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    compression_options=_shared_docs["compression_options"] % "filepath_or_buffer",
+)
+def to_pickle(
+    obj: Any,
+    filepath_or_buffer: FilePath | WriteBuffer[bytes],
+    compression: CompressionOptions = "infer",
+    protocol: int = pickle.HIGHEST_PROTOCOL,
+    storage_options: StorageOptions | None = None,
+) -> None:
+    """
+    Pickle (serialize) object to file.
+
+    Parameters
+    ----------
+    obj : any object
+        Any python object.
+    filepath_or_buffer : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``write()`` function.
+        Also accepts URL. URL has to be of S3 or GCS.
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    protocol : int
+        Int which indicates which protocol should be used by the pickler,
+        default HIGHEST_PROTOCOL (see [1], paragraph 12.1.2). The possible
+        values for this parameter depend on the version of Python. For Python
+        2.x, possible values are 0, 1, 2. For Python>=3.0, 3 is a valid value.
+        For Python >= 3.4, 4 is a valid value. A negative value for the
+        protocol parameter is equivalent to setting its value to
+        HIGHEST_PROTOCOL.
+
+    {storage_options}
+
+        .. [1] https://docs.python.org/3/library/pickle.html
+
+    See Also
+    --------
+    read_pickle : Load pickled pandas object (or any object) from file.
+    DataFrame.to_hdf : Write DataFrame to an HDF5 file.
+    DataFrame.to_sql : Write DataFrame to a SQL database.
+    DataFrame.to_parquet : Write a DataFrame to the binary parquet format.
+
+    Examples
+    --------
+    >>> original_df = pd.DataFrame({{"foo": range(5), "bar": range(5, 10)}})  # doctest: +SKIP
+    >>> original_df  # doctest: +SKIP
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    >>> pd.to_pickle(original_df, "./dummy.pkl")  # doctest: +SKIP
+
+    >>> unpickled_df = pd.read_pickle("./dummy.pkl")  # doctest: +SKIP
+    >>> unpickled_df  # doctest: +SKIP
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    """  # noqa: E501
+    if protocol < 0:
+        protocol = pickle.HIGHEST_PROTOCOL
+
+    with get_handle(
+        filepath_or_buffer,
+        "wb",
+        compression=compression,
+        is_text=False,
+        storage_options=storage_options,
+    ) as handles:
+        # letting pickle write directly to the buffer is more memory-efficient
+        pickle.dump(obj, handles.handle, protocol=protocol)
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    decompression_options=_shared_docs["decompression_options"] % "filepath_or_buffer",
+)
+def read_pickle(
+    filepath_or_buffer: FilePath | ReadPickleBuffer,
+    compression: CompressionOptions = "infer",
+    storage_options: StorageOptions | None = None,
+) -> DataFrame | Series:
+    """
+    Load pickled pandas object (or any object) from file.
+
+    .. warning::
+
+       Loading pickled data received from untrusted sources can be
+       unsafe. See `here `__.
+
+    Parameters
+    ----------
+    filepath_or_buffer : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``readlines()`` function.
+        Also accepts URL. URL is not limited to S3 and GCS.
+
+    {decompression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    {storage_options}
+
+    Returns
+    -------
+    same type as object stored in file
+
+    See Also
+    --------
+    DataFrame.to_pickle : Pickle (serialize) DataFrame object to file.
+    Series.to_pickle : Pickle (serialize) Series object to file.
+    read_hdf : Read HDF5 file into a DataFrame.
+    read_sql : Read SQL query or database table into a DataFrame.
+    read_parquet : Load a parquet object, returning a DataFrame.
+
+    Notes
+    -----
+    read_pickle is only guaranteed to be backwards compatible to pandas 0.20.3
+    provided the object was serialized with to_pickle.
+
+    Examples
+    --------
+    >>> original_df = pd.DataFrame(
+    ...     {{"foo": range(5), "bar": range(5, 10)}}
+    ...    )  # doctest: +SKIP
+    >>> original_df  # doctest: +SKIP
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    >>> pd.to_pickle(original_df, "./dummy.pkl")  # doctest: +SKIP
+
+    >>> unpickled_df = pd.read_pickle("./dummy.pkl")  # doctest: +SKIP
+    >>> unpickled_df  # doctest: +SKIP
+       foo  bar
+    0    0    5
+    1    1    6
+    2    2    7
+    3    3    8
+    4    4    9
+    """
+    excs_to_catch = (AttributeError, ImportError, ModuleNotFoundError, TypeError)
+    with get_handle(
+        filepath_or_buffer,
+        "rb",
+        compression=compression,
+        is_text=False,
+        storage_options=storage_options,
+    ) as handles:
+        # 1) try standard library Pickle
+        # 2) try pickle_compat (older pandas version) to handle subclass changes
+        # 3) try pickle_compat with latin-1 encoding upon a UnicodeDecodeError
+
+        try:
+            # TypeError for Cython complaints about object.__new__ vs Tick.__new__
+            try:
+                with warnings.catch_warnings(record=True):
+                    # We want to silence any warnings about, e.g. moved modules.
+                    warnings.simplefilter("ignore", Warning)
+                    return pickle.load(handles.handle)
+            except excs_to_catch:
+                # e.g.
+                #  "No module named 'pandas.core.sparse.series'"
+                #  "Can't get attribute '__nat_unpickle' on  str:
+    # set the encoding if we need
+    if encoding is None:
+        encoding = _default_encoding
+
+    return encoding
+
+
+def _ensure_str(name):
+    """
+    Ensure that an index / column name is a str (python 3); otherwise they
+    may be np.string dtype. Non-string dtypes are passed through unchanged.
+
+    https://github.com/pandas-dev/pandas/issues/13492
+    """
+    if isinstance(name, str):
+        name = str(name)
+    return name
+
+
+Term = PyTablesExpr
+
+
+def _ensure_term(where, scope_level: int):
+    """
+    Ensure that the where is a Term or a list of Term.
+
+    This makes sure that we are capturing the scope of variables that are
+    passed create the terms here with a frame_level=2 (we are 2 levels down)
+    """
+    # only consider list/tuple here as an ndarray is automatically a coordinate
+    # list
+    level = scope_level + 1
+    if isinstance(where, (list, tuple)):
+        where = [
+            Term(term, scope_level=level + 1) if maybe_expression(term) else term
+            for term in where
+            if term is not None
+        ]
+    elif maybe_expression(where):
+        where = Term(where, scope_level=level)
+    return where if where is None or len(where) else None
+
+
+incompatibility_doc: Final = """
+where criteria is being ignored as this version [%s] is too old (or
+not-defined), read the file in and write it out to a new file to upgrade (with
+the copy_to method)
+"""
+
+attribute_conflict_doc: Final = """
+the [%s] attribute of the existing index is [%s] which conflicts with the new
+[%s], resetting the attribute to None
+"""
+
+performance_doc: Final = """
+your performance may suffer as PyTables will pickle object types that it cannot
+map directly to c-types [inferred_type->%s,key->%s] [items->%s]
+"""
+
+# formats
+_FORMAT_MAP = {"f": "fixed", "fixed": "fixed", "t": "table", "table": "table"}
+
+# axes map
+_AXES_MAP = {DataFrame: [0]}
+
+# register our configuration options
+dropna_doc: Final = """
+: boolean
+    drop ALL nan rows when appending to a table
+"""
+format_doc: Final = """
+: format
+    default format writing format, if None, then
+    put will default to 'fixed' and append will default to 'table'
+"""
+
+with config.config_prefix("io.hdf"):
+    config.register_option("dropna_table", False, dropna_doc, validator=config.is_bool)
+    config.register_option(
+        "default_format",
+        None,
+        format_doc,
+        validator=config.is_one_of_factory(["fixed", "table", None]),
+    )
+
+# oh the troubles to reduce import time
+_table_mod = None
+_table_file_open_policy_is_strict = False
+
+
+def _tables():
+    global _table_mod
+    global _table_file_open_policy_is_strict
+    if _table_mod is None:
+        import tables
+
+        _table_mod = tables
+
+        # set the file open policy
+        # return the file open policy; this changes as of pytables 3.1
+        # depending on the HDF5 version
+        with suppress(AttributeError):
+            _table_file_open_policy_is_strict = (
+                tables.file._FILE_OPEN_POLICY == "strict"
+            )
+
+    return _table_mod
+
+
+# interface to/from ###
+
+
+def to_hdf(
+    path_or_buf: FilePath | HDFStore,
+    key: str,
+    value: DataFrame | Series,
+    mode: str = "a",
+    complevel: int | None = None,
+    complib: str | None = None,
+    append: bool = False,
+    format: str | None = None,
+    index: bool = True,
+    min_itemsize: int | dict[str, int] | None = None,
+    nan_rep=None,
+    dropna: bool | None = None,
+    data_columns: Literal[True] | list[str] | None = None,
+    errors: str = "strict",
+    encoding: str = "UTF-8",
+) -> None:
+    """store this object, close it if we opened it"""
+    if append:
+        f = lambda store: store.append(
+            key,
+            value,
+            format=format,
+            index=index,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            dropna=dropna,
+            data_columns=data_columns,
+            errors=errors,
+            encoding=encoding,
+        )
+    else:
+        # NB: dropna is not passed to `put`
+        f = lambda store: store.put(
+            key,
+            value,
+            format=format,
+            index=index,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            data_columns=data_columns,
+            errors=errors,
+            encoding=encoding,
+            dropna=dropna,
+        )
+
+    path_or_buf = stringify_path(path_or_buf)
+    if isinstance(path_or_buf, str):
+        with HDFStore(
+            path_or_buf, mode=mode, complevel=complevel, complib=complib
+        ) as store:
+            f(store)
+    else:
+        f(path_or_buf)
+
+
+def read_hdf(
+    path_or_buf: FilePath | HDFStore,
+    key=None,
+    mode: str = "r",
+    errors: str = "strict",
+    where: str | list | None = None,
+    start: int | None = None,
+    stop: int | None = None,
+    columns: list[str] | None = None,
+    iterator: bool = False,
+    chunksize: int | None = None,
+    **kwargs,
+):
+    """
+    Read from the store, close it if we opened it.
+
+    Retrieve pandas object stored in file, optionally based on where
+    criteria.
+
+    .. warning::
+
+       Pandas uses PyTables for reading and writing HDF5 files, which allows
+       serializing object-dtype data with pickle when using the "fixed" format.
+       Loading pickled data received from untrusted sources can be unsafe.
+
+       See: https://docs.python.org/3/library/pickle.html for more.
+
+    Parameters
+    ----------
+    path_or_buf : str, path object, pandas.HDFStore
+        Any valid string path is acceptable. Only supports the local file system,
+        remote URLs and file-like objects are not supported.
+
+        If you want to pass in a path object, pandas accepts any
+        ``os.PathLike``.
+
+        Alternatively, pandas accepts an open :class:`pandas.HDFStore` object.
+
+    key : object, optional
+        The group identifier in the store. Can be omitted if the HDF file
+        contains a single pandas object.
+    mode : {'r', 'r+', 'a'}, default 'r'
+        Mode to use when opening the file. Ignored if path_or_buf is a
+        :class:`pandas.HDFStore`. Default is 'r'.
+    errors : str, default 'strict'
+        Specifies how encoding and decoding errors are to be handled.
+        See the errors argument for :func:`open` for a full list
+        of options.
+    where : list, optional
+        A list of Term (or convertible) objects.
+    start : int, optional
+        Row number to start selection.
+    stop  : int, optional
+        Row number to stop selection.
+    columns : list, optional
+        A list of columns names to return.
+    iterator : bool, optional
+        Return an iterator object.
+    chunksize : int, optional
+        Number of rows to include in an iteration when using an iterator.
+    **kwargs
+        Additional keyword arguments passed to HDFStore.
+
+    Returns
+    -------
+    object
+        The selected object. Return type depends on the object stored.
+
+    See Also
+    --------
+    DataFrame.to_hdf : Write a HDF file from a DataFrame.
+    HDFStore : Low-level access to HDF files.
+
+    Notes
+    -----
+    When ``errors="surrogatepass"``, ``pd.options.future.infer_string`` is true,
+    and PyArrow is installed, if a UTF-16 surrogate is encountered when decoding
+    to UTF-8, the resulting dtype will be
+    ``pd.StringDtype(storage="python", na_value=np.nan)``.
+
+    Examples
+    --------
+    >>> df = pd.DataFrame([[1, 1.0, 'a']], columns=['x', 'y', 'z'])  # doctest: +SKIP
+    >>> df.to_hdf('./store.h5', 'data')  # doctest: +SKIP
+    >>> reread = pd.read_hdf('./store.h5')  # doctest: +SKIP
+    """
+    if mode not in ["r", "r+", "a"]:
+        raise ValueError(
+            f"mode {mode} is not allowed while performing a read. "
+            f"Allowed modes are r, r+ and a."
+        )
+    # grab the scope
+    if where is not None:
+        where = _ensure_term(where, scope_level=1)
+
+    if isinstance(path_or_buf, HDFStore):
+        if not path_or_buf.is_open:
+            raise OSError("The HDFStore must be open for reading.")
+
+        store = path_or_buf
+        auto_close = False
+    else:
+        path_or_buf = stringify_path(path_or_buf)
+        if not isinstance(path_or_buf, str):
+            raise NotImplementedError(
+                "Support for generic buffers has not been implemented."
+            )
+        try:
+            exists = os.path.exists(path_or_buf)
+
+        # if filepath is too long
+        except (TypeError, ValueError):
+            exists = False
+
+        if not exists:
+            raise FileNotFoundError(f"File {path_or_buf} does not exist")
+
+        store = HDFStore(path_or_buf, mode=mode, errors=errors, **kwargs)
+        # can't auto open/close if we are using an iterator
+        # so delegate to the iterator
+        auto_close = True
+
+    try:
+        if key is None:
+            groups = store.groups()
+            if len(groups) == 0:
+                raise ValueError(
+                    "Dataset(s) incompatible with Pandas data types, "
+                    "not table, or no datasets found in HDF5 file."
+                )
+            candidate_only_group = groups[0]
+
+            # For the HDF file to have only one dataset, all other groups
+            # should then be metadata groups for that candidate group. (This
+            # assumes that the groups() method enumerates parent groups
+            # before their children.)
+            for group_to_check in groups[1:]:
+                if not _is_metadata_of(group_to_check, candidate_only_group):
+                    raise ValueError(
+                        "key must be provided when HDF5 "
+                        "file contains multiple datasets."
+                    )
+            key = candidate_only_group._v_pathname
+        return store.select(
+            key,
+            where=where,
+            start=start,
+            stop=stop,
+            columns=columns,
+            iterator=iterator,
+            chunksize=chunksize,
+            auto_close=auto_close,
+        )
+    except (ValueError, TypeError, LookupError):
+        if not isinstance(path_or_buf, HDFStore):
+            # if there is an error, close the store if we opened it.
+            with suppress(AttributeError):
+                store.close()
+
+        raise
+
+
+def _is_metadata_of(group: Node, parent_group: Node) -> bool:
+    """Check if a given group is a metadata group for a given parent_group."""
+    if group._v_depth <= parent_group._v_depth:
+        return False
+
+    current = group
+    while current._v_depth > 1:
+        parent = current._v_parent
+        if parent == parent_group and current._v_name == "meta":
+            return True
+        current = current._v_parent
+    return False
+
+
+class HDFStore:
+    """
+    Dict-like IO interface for storing pandas objects in PyTables.
+
+    Either Fixed or Table format.
+
+    .. warning::
+
+       Pandas uses PyTables for reading and writing HDF5 files, which allows
+       serializing object-dtype data with pickle when using the "fixed" format.
+       Loading pickled data received from untrusted sources can be unsafe.
+
+       See: https://docs.python.org/3/library/pickle.html for more.
+
+    Parameters
+    ----------
+    path : str
+        File path to HDF5 file.
+    mode : {'a', 'w', 'r', 'r+'}, default 'a'
+
+        ``'r'``
+            Read-only; no data can be modified.
+        ``'w'``
+            Write; a new file is created (an existing file with the same
+            name would be deleted).
+        ``'a'``
+            Append; an existing file is opened for reading and writing,
+            and if the file does not exist it is created.
+        ``'r+'``
+            It is similar to ``'a'``, but the file must already exist.
+    complevel : int, 0-9, default None
+        Specifies a compression level for data.
+        A value of 0 or None disables compression.
+    complib : {'zlib', 'lzo', 'bzip2', 'blosc'}, default 'zlib'
+        Specifies the compression library to be used.
+        These additional compressors for Blosc are supported
+        (default if no compressor specified: 'blosc:blosclz'):
+        {'blosc:blosclz', 'blosc:lz4', 'blosc:lz4hc', 'blosc:snappy',
+         'blosc:zlib', 'blosc:zstd'}.
+        Specifying a compression library which is not available issues
+        a ValueError.
+    fletcher32 : bool, default False
+        If applying compression use the fletcher32 checksum.
+    **kwargs
+        These parameters will be passed to the PyTables open_file method.
+
+    Examples
+    --------
+    >>> bar = pd.DataFrame(np.random.randn(10, 4))
+    >>> store = pd.HDFStore('test.h5')
+    >>> store['foo'] = bar   # write to HDF5
+    >>> bar = store['foo']   # retrieve
+    >>> store.close()
+
+    **Create or load HDF5 file in-memory**
+
+    When passing the `driver` option to the PyTables open_file method through
+    **kwargs, the HDF5 file is loaded or created in-memory and will only be
+    written when closed:
+
+    >>> bar = pd.DataFrame(np.random.randn(10, 4))
+    >>> store = pd.HDFStore('test.h5', driver='H5FD_CORE')
+    >>> store['foo'] = bar
+    >>> store.close()   # only now, data is written to disk
+    """
+
+    _handle: File | None
+    _mode: str
+
+    def __init__(
+        self,
+        path,
+        mode: str = "a",
+        complevel: int | None = None,
+        complib=None,
+        fletcher32: bool = False,
+        **kwargs,
+    ) -> None:
+        if "format" in kwargs:
+            raise ValueError("format is not a defined argument for HDFStore")
+
+        tables = import_optional_dependency("tables")
+
+        if complib is not None and complib not in tables.filters.all_complibs:
+            raise ValueError(
+                f"complib only supports {tables.filters.all_complibs} compression."
+            )
+
+        if complib is None and complevel is not None:
+            complib = tables.filters.default_complib
+
+        self._path = stringify_path(path)
+        if mode is None:
+            mode = "a"
+        self._mode = mode
+        self._handle = None
+        self._complevel = complevel if complevel else 0
+        self._complib = complib
+        self._fletcher32 = fletcher32
+        self._filters = None
+        self.open(mode=mode, **kwargs)
+
+    def __fspath__(self) -> str:
+        return self._path
+
+    @property
+    def root(self):
+        """return the root node"""
+        self._check_if_open()
+        assert self._handle is not None  # for mypy
+        return self._handle.root
+
+    @property
+    def filename(self) -> str:
+        return self._path
+
+    def __getitem__(self, key: str):
+        return self.get(key)
+
+    def __setitem__(self, key: str, value) -> None:
+        self.put(key, value)
+
+    def __delitem__(self, key: str) -> None:
+        return self.remove(key)
+
+    def __getattr__(self, name: str):
+        """allow attribute access to get stores"""
+        try:
+            return self.get(name)
+        except (KeyError, ClosedFileError):
+            pass
+        raise AttributeError(
+            f"'{type(self).__name__}' object has no attribute '{name}'"
+        )
+
+    def __contains__(self, key: str) -> bool:
+        """
+        check for existence of this key
+        can match the exact pathname or the pathnm w/o the leading '/'
+        """
+        node = self.get_node(key)
+        if node is not None:
+            name = node._v_pathname
+            if key in (name, name[1:]):
+                return True
+        return False
+
+    def __len__(self) -> int:
+        return len(self.groups())
+
+    def __repr__(self) -> str:
+        pstr = pprint_thing(self._path)
+        return f"{type(self)}\nFile path: {pstr}\n"
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def keys(self, include: str = "pandas") -> list[str]:
+        """
+        Return a list of keys corresponding to objects stored in HDFStore.
+
+        Parameters
+        ----------
+
+        include : str, default 'pandas'
+                When kind equals 'pandas' return pandas objects.
+                When kind equals 'native' return native HDF5 Table objects.
+
+        Returns
+        -------
+        list
+            List of ABSOLUTE path-names (e.g. have the leading '/').
+
+        Raises
+        ------
+        raises ValueError if kind has an illegal value
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        >>> store.get('data')  # doctest: +SKIP
+        >>> print(store.keys())  # doctest: +SKIP
+        ['/data1', '/data2']
+        >>> store.close()  # doctest: +SKIP
+        """
+        if include == "pandas":
+            return [n._v_pathname for n in self.groups()]
+
+        elif include == "native":
+            assert self._handle is not None  # mypy
+            return [
+                n._v_pathname for n in self._handle.walk_nodes("/", classname="Table")
+            ]
+        raise ValueError(
+            f"`include` should be either 'pandas' or 'native' but is '{include}'"
+        )
+
+    def __iter__(self) -> Iterator[str]:
+        return iter(self.keys())
+
+    def items(self) -> Iterator[tuple[str, list]]:
+        """
+        iterate on key->group
+        """
+        for g in self.groups():
+            yield g._v_pathname, g
+
+    def open(self, mode: str = "a", **kwargs) -> None:
+        """
+        Open the file in the specified mode
+
+        Parameters
+        ----------
+        mode : {'a', 'w', 'r', 'r+'}, default 'a'
+            See HDFStore docstring or tables.open_file for info about modes
+        **kwargs
+            These parameters will be passed to the PyTables open_file method.
+        """
+        tables = _tables()
+
+        if self._mode != mode:
+            # if we are changing a write mode to read, ok
+            if self._mode in ["a", "w"] and mode in ["r", "r+"]:
+                pass
+            elif mode in ["w"]:
+                # this would truncate, raise here
+                if self.is_open:
+                    raise PossibleDataLossError(
+                        f"Re-opening the file [{self._path}] with mode [{self._mode}] "
+                        "will delete the current file!"
+                    )
+
+            self._mode = mode
+
+        # close and reopen the handle
+        if self.is_open:
+            self.close()
+
+        if self._complevel and self._complevel > 0:
+            self._filters = _tables().Filters(
+                self._complevel, self._complib, fletcher32=self._fletcher32
+            )
+
+        if _table_file_open_policy_is_strict and self.is_open:
+            msg = (
+                "Cannot open HDF5 file, which is already opened, "
+                "even in read-only mode."
+            )
+            raise ValueError(msg)
+
+        self._handle = tables.open_file(self._path, self._mode, **kwargs)
+
+    def close(self) -> None:
+        """
+        Close the PyTables file handle
+        """
+        if self._handle is not None:
+            self._handle.close()
+        self._handle = None
+
+    @property
+    def is_open(self) -> bool:
+        """
+        return a boolean indicating whether the file is open
+        """
+        if self._handle is None:
+            return False
+        return bool(self._handle.isopen)
+
+    def flush(self, fsync: bool = False) -> None:
+        """
+        Force all buffered modifications to be written to disk.
+
+        Parameters
+        ----------
+        fsync : bool (default False)
+          call ``os.fsync()`` on the file handle to force writing to disk.
+
+        Notes
+        -----
+        Without ``fsync=True``, flushing may not guarantee that the OS writes
+        to disk. With fsync, the operation will block until the OS claims the
+        file has been written; however, other caching layers may still
+        interfere.
+        """
+        if self._handle is not None:
+            self._handle.flush()
+            if fsync:
+                with suppress(OSError):
+                    os.fsync(self._handle.fileno())
+
+    def get(self, key: str):
+        """
+        Retrieve pandas object stored in file.
+
+        Parameters
+        ----------
+        key : str
+
+        Returns
+        -------
+        object
+            Same type as object stored in file.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        >>> store.get('data')  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+        """
+        with patch_pickle():
+            # GH#31167 Without this patch, pickle doesn't know how to unpickle
+            #  old DateOffset objects now that they are cdef classes.
+            group = self.get_node(key)
+            if group is None:
+                raise KeyError(f"No object named {key} in the file")
+            return self._read_group(group)
+
+    def select(
+        self,
+        key: str,
+        where=None,
+        start=None,
+        stop=None,
+        columns=None,
+        iterator: bool = False,
+        chunksize: int | None = None,
+        auto_close: bool = False,
+    ):
+        """
+        Retrieve pandas object stored in file, optionally based on where criteria.
+
+        .. warning::
+
+           Pandas uses PyTables for reading and writing HDF5 files, which allows
+           serializing object-dtype data with pickle when using the "fixed" format.
+           Loading pickled data received from untrusted sources can be unsafe.
+
+           See: https://docs.python.org/3/library/pickle.html for more.
+
+        Parameters
+        ----------
+        key : str
+            Object being retrieved from file.
+        where : list or None
+            List of Term (or convertible) objects, optional.
+        start : int or None
+            Row number to start selection.
+        stop : int, default None
+            Row number to stop selection.
+        columns : list or None
+            A list of columns that if not None, will limit the return columns.
+        iterator : bool or False
+            Returns an iterator.
+        chunksize : int or None
+            Number or rows to include in iteration, return an iterator.
+        auto_close : bool or False
+            Should automatically close the store when finished.
+
+        Returns
+        -------
+        object
+            Retrieved object from file.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        >>> store.get('data')  # doctest: +SKIP
+        >>> print(store.keys())  # doctest: +SKIP
+        ['/data1', '/data2']
+        >>> store.select('/data1')  # doctest: +SKIP
+           A  B
+        0  1  2
+        1  3  4
+        >>> store.select('/data1', where='columns == A')  # doctest: +SKIP
+           A
+        0  1
+        1  3
+        >>> store.close()  # doctest: +SKIP
+        """
+        group = self.get_node(key)
+        if group is None:
+            raise KeyError(f"No object named {key} in the file")
+
+        # create the storer and axes
+        where = _ensure_term(where, scope_level=1)
+        s = self._create_storer(group)
+        s.infer_axes()
+
+        # function to call on iteration
+        def func(_start, _stop, _where):
+            return s.read(start=_start, stop=_stop, where=_where, columns=columns)
+
+        # create the iterator
+        it = TableIterator(
+            self,
+            s,
+            func,
+            where=where,
+            nrows=s.nrows,
+            start=start,
+            stop=stop,
+            iterator=iterator,
+            chunksize=chunksize,
+            auto_close=auto_close,
+        )
+
+        return it.get_result()
+
+    def select_as_coordinates(
+        self,
+        key: str,
+        where=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        """
+        return the selection as an Index
+
+        .. warning::
+
+           Pandas uses PyTables for reading and writing HDF5 files, which allows
+           serializing object-dtype data with pickle when using the "fixed" format.
+           Loading pickled data received from untrusted sources can be unsafe.
+
+           See: https://docs.python.org/3/library/pickle.html for more.
+
+
+        Parameters
+        ----------
+        key : str
+        where : list of Term (or convertible) objects, optional
+        start : integer (defaults to None), row number to start selection
+        stop  : integer (defaults to None), row number to stop selection
+        """
+        where = _ensure_term(where, scope_level=1)
+        tbl = self.get_storer(key)
+        if not isinstance(tbl, Table):
+            raise TypeError("can only read_coordinates with a table")
+        return tbl.read_coordinates(where=where, start=start, stop=stop)
+
+    def select_column(
+        self,
+        key: str,
+        column: str,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        """
+        return a single column from the table. This is generally only useful to
+        select an indexable
+
+        .. warning::
+
+           Pandas uses PyTables for reading and writing HDF5 files, which allows
+           serializing object-dtype data with pickle when using the "fixed" format.
+           Loading pickled data received from untrusted sources can be unsafe.
+
+           See: https://docs.python.org/3/library/pickle.html for more.
+
+        Parameters
+        ----------
+        key : str
+        column : str
+            The column of interest.
+        start : int or None, default None
+        stop : int or None, default None
+
+        Raises
+        ------
+        raises KeyError if the column is not found (or key is not a valid
+            store)
+        raises ValueError if the column can not be extracted individually (it
+            is part of a data block)
+
+        """
+        tbl = self.get_storer(key)
+        if not isinstance(tbl, Table):
+            raise TypeError("can only read_column with a table")
+        return tbl.read_column(column=column, start=start, stop=stop)
+
+    def select_as_multiple(
+        self,
+        keys,
+        where=None,
+        selector=None,
+        columns=None,
+        start=None,
+        stop=None,
+        iterator: bool = False,
+        chunksize: int | None = None,
+        auto_close: bool = False,
+    ):
+        """
+        Retrieve pandas objects from multiple tables.
+
+        .. warning::
+
+           Pandas uses PyTables for reading and writing HDF5 files, which allows
+           serializing object-dtype data with pickle when using the "fixed" format.
+           Loading pickled data received from untrusted sources can be unsafe.
+
+           See: https://docs.python.org/3/library/pickle.html for more.
+
+        Parameters
+        ----------
+        keys : a list of the tables
+        selector : the table to apply the where criteria (defaults to keys[0]
+            if not supplied)
+        columns : the columns I want back
+        start : integer (defaults to None), row number to start selection
+        stop  : integer (defaults to None), row number to stop selection
+        iterator : bool, return an iterator, default False
+        chunksize : nrows to include in iteration, return an iterator
+        auto_close : bool, default False
+            Should automatically close the store when finished.
+
+        Raises
+        ------
+        raises KeyError if keys or selector is not found or keys is empty
+        raises TypeError if keys is not a list or tuple
+        raises ValueError if the tables are not ALL THE SAME DIMENSIONS
+        """
+        # default to single select
+        where = _ensure_term(where, scope_level=1)
+        if isinstance(keys, (list, tuple)) and len(keys) == 1:
+            keys = keys[0]
+        if isinstance(keys, str):
+            return self.select(
+                key=keys,
+                where=where,
+                columns=columns,
+                start=start,
+                stop=stop,
+                iterator=iterator,
+                chunksize=chunksize,
+                auto_close=auto_close,
+            )
+
+        if not isinstance(keys, (list, tuple)):
+            raise TypeError("keys must be a list/tuple")
+
+        if not len(keys):
+            raise ValueError("keys must have a non-zero length")
+
+        if selector is None:
+            selector = keys[0]
+
+        # collect the tables
+        tbls = [self.get_storer(k) for k in keys]
+        s = self.get_storer(selector)
+
+        # validate rows
+        nrows = None
+        for t, k in itertools.chain([(s, selector)], zip(tbls, keys)):
+            if t is None:
+                raise KeyError(f"Invalid table [{k}]")
+            if not t.is_table:
+                raise TypeError(
+                    f"object [{t.pathname}] is not a table, and cannot be used in all "
+                    "select as multiple"
+                )
+
+            if nrows is None:
+                nrows = t.nrows
+            elif t.nrows != nrows:
+                raise ValueError("all tables must have exactly the same nrows!")
+
+        # The isinstance checks here are redundant with the check above,
+        #  but necessary for mypy; see GH#29757
+        _tbls = [x for x in tbls if isinstance(x, Table)]
+
+        # axis is the concentration axes
+        axis = {t.non_index_axes[0][0] for t in _tbls}.pop()
+
+        def func(_start, _stop, _where):
+            # retrieve the objs, _where is always passed as a set of
+            # coordinates here
+            objs = [
+                t.read(where=_where, columns=columns, start=_start, stop=_stop)
+                for t in tbls
+            ]
+
+            # concat and return
+            return concat(objs, axis=axis, verify_integrity=False)._consolidate()
+
+        # create the iterator
+        it = TableIterator(
+            self,
+            s,
+            func,
+            where=where,
+            nrows=nrows,
+            start=start,
+            stop=stop,
+            iterator=iterator,
+            chunksize=chunksize,
+            auto_close=auto_close,
+        )
+
+        return it.get_result(coordinates=True)
+
+    def put(
+        self,
+        key: str,
+        value: DataFrame | Series,
+        format=None,
+        index: bool = True,
+        append: bool = False,
+        complib=None,
+        complevel: int | None = None,
+        min_itemsize: int | dict[str, int] | None = None,
+        nan_rep=None,
+        data_columns: Literal[True] | list[str] | None = None,
+        encoding=None,
+        errors: str = "strict",
+        track_times: bool = True,
+        dropna: bool = False,
+    ) -> None:
+        """
+        Store object in HDFStore.
+
+        Parameters
+        ----------
+        key : str
+        value : {Series, DataFrame}
+        format : 'fixed(f)|table(t)', default is 'fixed'
+            Format to use when storing object in HDFStore. Value can be one of:
+
+            ``'fixed'``
+                Fixed format.  Fast writing/reading. Not-appendable, nor searchable.
+            ``'table'``
+                Table format.  Write as a PyTables Table structure which may perform
+                worse but allow more flexible operations like searching / selecting
+                subsets of the data.
+        index : bool, default True
+            Write DataFrame index as a column.
+        append : bool, default False
+            This will force Table format, append the input data to the existing.
+        data_columns : list of columns or True, default None
+            List of columns to create as data columns, or True to use all columns.
+            See `here
+            `__.
+        encoding : str, default None
+            Provide an encoding for strings.
+        track_times : bool, default True
+            Parameter is propagated to 'create_table' method of 'PyTables'.
+            If set to False it enables to have the same h5 files (same hashes)
+            independent on creation time.
+        dropna : bool, default False, optional
+            Remove missing values.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        """
+        if format is None:
+            format = get_option("io.hdf.default_format") or "fixed"
+        format = self._validate_format(format)
+        self._write_to_group(
+            key,
+            value,
+            format=format,
+            index=index,
+            append=append,
+            complib=complib,
+            complevel=complevel,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            data_columns=data_columns,
+            encoding=encoding,
+            errors=errors,
+            track_times=track_times,
+            dropna=dropna,
+        )
+
+    def remove(self, key: str, where=None, start=None, stop=None) -> None:
+        """
+        Remove pandas object partially by specifying the where condition
+
+        Parameters
+        ----------
+        key : str
+            Node to remove or delete rows from
+        where : list of Term (or convertible) objects, optional
+        start : integer (defaults to None), row number to start selection
+        stop  : integer (defaults to None), row number to stop selection
+
+        Returns
+        -------
+        number of rows removed (or None if not a Table)
+
+        Raises
+        ------
+        raises KeyError if key is not a valid store
+
+        """
+        where = _ensure_term(where, scope_level=1)
+        try:
+            s = self.get_storer(key)
+        except KeyError:
+            # the key is not a valid store, re-raising KeyError
+            raise
+        except AssertionError:
+            # surface any assertion errors for e.g. debugging
+            raise
+        except Exception as err:
+            # In tests we get here with ClosedFileError, TypeError, and
+            #  _table_mod.NoSuchNodeError.  TODO: Catch only these?
+
+            if where is not None:
+                raise ValueError(
+                    "trying to remove a node with a non-None where clause!"
+                ) from err
+
+            # we are actually trying to remove a node (with children)
+            node = self.get_node(key)
+            if node is not None:
+                node._f_remove(recursive=True)
+                return None
+
+        # remove the node
+        if com.all_none(where, start, stop):
+            s.group._f_remove(recursive=True)
+
+        # delete from the table
+        else:
+            if not s.is_table:
+                raise ValueError(
+                    "can only remove with where on objects written as tables"
+                )
+            return s.delete(where=where, start=start, stop=stop)
+
+    def append(
+        self,
+        key: str,
+        value: DataFrame | Series,
+        format=None,
+        axes=None,
+        index: bool | list[str] = True,
+        append: bool = True,
+        complib=None,
+        complevel: int | None = None,
+        columns=None,
+        min_itemsize: int | dict[str, int] | None = None,
+        nan_rep=None,
+        chunksize: int | None = None,
+        expectedrows=None,
+        dropna: bool | None = None,
+        data_columns: Literal[True] | list[str] | None = None,
+        encoding=None,
+        errors: str = "strict",
+    ) -> None:
+        """
+        Append to Table in file.
+
+        Node must already exist and be Table format.
+
+        Parameters
+        ----------
+        key : str
+        value : {Series, DataFrame}
+        format : 'table' is the default
+            Format to use when storing object in HDFStore.  Value can be one of:
+
+            ``'table'``
+                Table format. Write as a PyTables Table structure which may perform
+                worse but allow more flexible operations like searching / selecting
+                subsets of the data.
+        index : bool, default True
+            Write DataFrame index as a column.
+        append       : bool, default True
+            Append the input data to the existing.
+        data_columns : list of columns, or True, default None
+            List of columns to create as indexed data columns for on-disk
+            queries, or True to use all columns. By default only the axes
+            of the object are indexed. See `here
+            `__.
+        min_itemsize : dict of columns that specify minimum str sizes
+        nan_rep      : str to use as str nan representation
+        chunksize    : size to chunk the writing
+        expectedrows : expected TOTAL row size of this table
+        encoding     : default None, provide an encoding for str
+        dropna : bool, default False, optional
+            Do not write an ALL nan row to the store settable
+            by the option 'io.hdf.dropna_table'.
+
+        Notes
+        -----
+        Does *not* check if data being appended overlaps with existing
+        data in the table, so be careful
+
+        Examples
+        --------
+        >>> df1 = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df1, format='table')  # doctest: +SKIP
+        >>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=['A', 'B'])
+        >>> store.append('data', df2)  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+           A  B
+        0  1  2
+        1  3  4
+        0  5  6
+        1  7  8
+        """
+        if columns is not None:
+            raise TypeError(
+                "columns is not a supported keyword in append, try data_columns"
+            )
+
+        if dropna is None:
+            dropna = get_option("io.hdf.dropna_table")
+        if format is None:
+            format = get_option("io.hdf.default_format") or "table"
+        format = self._validate_format(format)
+        self._write_to_group(
+            key,
+            value,
+            format=format,
+            axes=axes,
+            index=index,
+            append=append,
+            complib=complib,
+            complevel=complevel,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            chunksize=chunksize,
+            expectedrows=expectedrows,
+            dropna=dropna,
+            data_columns=data_columns,
+            encoding=encoding,
+            errors=errors,
+        )
+
+    def append_to_multiple(
+        self,
+        d: dict,
+        value,
+        selector,
+        data_columns=None,
+        axes=None,
+        dropna: bool = False,
+        **kwargs,
+    ) -> None:
+        """
+        Append to multiple tables
+
+        Parameters
+        ----------
+        d : a dict of table_name to table_columns, None is acceptable as the
+            values of one node (this will get all the remaining columns)
+        value : a pandas object
+        selector : a string that designates the indexable table; all of its
+            columns will be designed as data_columns, unless data_columns is
+            passed, in which case these are used
+        data_columns : list of columns to create as data columns, or True to
+            use all columns
+        dropna : if evaluates to True, drop rows from all tables if any single
+                 row in each table has all NaN. Default False.
+
+        Notes
+        -----
+        axes parameter is currently not accepted
+
+        """
+        if axes is not None:
+            raise TypeError(
+                "axes is currently not accepted as a parameter to append_to_multiple; "
+                "you can create the tables independently instead"
+            )
+
+        if not isinstance(d, dict):
+            raise ValueError(
+                "append_to_multiple must have a dictionary specified as the "
+                "way to split the value"
+            )
+
+        if selector not in d:
+            raise ValueError(
+                "append_to_multiple requires a selector that is in passed dict"
+            )
+
+        # figure out the splitting axis (the non_index_axis)
+        axis = next(iter(set(range(value.ndim)) - set(_AXES_MAP[type(value)])))
+
+        # figure out how to split the value
+        remain_key = None
+        remain_values: list = []
+        for k, v in d.items():
+            if v is None:
+                if remain_key is not None:
+                    raise ValueError(
+                        "append_to_multiple can only have one value in d that is None"
+                    )
+                remain_key = k
+            else:
+                remain_values.extend(v)
+        if remain_key is not None:
+            ordered = value.axes[axis]
+            ordd = ordered.difference(Index(remain_values))
+            ordd = sorted(ordered.get_indexer(ordd))
+            d[remain_key] = ordered.take(ordd)
+
+        # data_columns
+        if data_columns is None:
+            data_columns = d[selector]
+
+        # ensure rows are synchronized across the tables
+        if dropna:
+            idxs = (value[cols].dropna(how="all").index for cols in d.values())
+            valid_index = next(idxs)
+            for index in idxs:
+                valid_index = valid_index.intersection(index)
+            value = value.loc[valid_index]
+
+        min_itemsize = kwargs.pop("min_itemsize", None)
+
+        # append
+        for k, v in d.items():
+            dc = data_columns if k == selector else None
+
+            # compute the val
+            val = value.reindex(v, axis=axis)
+
+            filtered = (
+                {key: value for (key, value) in min_itemsize.items() if key in v}
+                if min_itemsize is not None
+                else None
+            )
+            self.append(k, val, data_columns=dc, min_itemsize=filtered, **kwargs)
+
+    def create_table_index(
+        self,
+        key: str,
+        columns=None,
+        optlevel: int | None = None,
+        kind: str | None = None,
+    ) -> None:
+        """
+        Create a pytables index on the table.
+
+        Parameters
+        ----------
+        key : str
+        columns : None, bool, or listlike[str]
+            Indicate which columns to create an index on.
+
+            * False : Do not create any indexes.
+            * True : Create indexes on all columns.
+            * None : Create indexes on all columns.
+            * listlike : Create indexes on the given columns.
+
+        optlevel : int or None, default None
+            Optimization level, if None, pytables defaults to 6.
+        kind : str or None, default None
+            Kind of index, if None, pytables defaults to "medium".
+
+        Raises
+        ------
+        TypeError: raises if the node is not a table
+        """
+        # version requirements
+        _tables()
+        s = self.get_storer(key)
+        if s is None:
+            return
+
+        if not isinstance(s, Table):
+            raise TypeError("cannot create table index on a Fixed format store")
+        s.create_index(columns=columns, optlevel=optlevel, kind=kind)
+
+    def groups(self) -> list:
+        """
+        Return a list of all the top-level nodes.
+
+        Each node returned is not a pandas storage object.
+
+        Returns
+        -------
+        list
+            List of objects.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        >>> print(store.groups())  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+        [/data (Group) ''
+          children := ['axis0' (Array), 'axis1' (Array), 'block0_values' (Array),
+          'block0_items' (Array)]]
+        """
+        _tables()
+        self._check_if_open()
+        assert self._handle is not None  # for mypy
+        assert _table_mod is not None  # for mypy
+        return [
+            g
+            for g in self._handle.walk_groups()
+            if (
+                not isinstance(g, _table_mod.link.Link)
+                and (
+                    getattr(g._v_attrs, "pandas_type", None)
+                    or getattr(g, "table", None)
+                    or (isinstance(g, _table_mod.table.Table) and g._v_name != "table")
+                )
+            )
+        ]
+
+    def walk(self, where: str = "/") -> Iterator[tuple[str, list[str], list[str]]]:
+        """
+        Walk the pytables group hierarchy for pandas objects.
+
+        This generator will yield the group path, subgroups and pandas object
+        names for each group.
+
+        Any non-pandas PyTables objects that are not a group will be ignored.
+
+        The `where` group itself is listed first (preorder), then each of its
+        child groups (following an alphanumerical order) is also traversed,
+        following the same procedure.
+
+        Parameters
+        ----------
+        where : str, default "/"
+            Group where to start walking.
+
+        Yields
+        ------
+        path : str
+            Full path to a group (without trailing '/').
+        groups : list
+            Names (strings) of the groups contained in `path`.
+        leaves : list
+            Names (strings) of the pandas objects contained in `path`.
+
+        Examples
+        --------
+        >>> df1 = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df1, format='table')  # doctest: +SKIP
+        >>> df2 = pd.DataFrame([[5, 6], [7, 8]], columns=['A', 'B'])
+        >>> store.append('data', df2)  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+        >>> for group in store.walk():  # doctest: +SKIP
+        ...     print(group)  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+        """
+        _tables()
+        self._check_if_open()
+        assert self._handle is not None  # for mypy
+        assert _table_mod is not None  # for mypy
+
+        for g in self._handle.walk_groups(where):
+            if getattr(g._v_attrs, "pandas_type", None) is not None:
+                continue
+
+            groups = []
+            leaves = []
+            for child in g._v_children.values():
+                pandas_type = getattr(child._v_attrs, "pandas_type", None)
+                if pandas_type is None:
+                    if isinstance(child, _table_mod.group.Group):
+                        groups.append(child._v_name)
+                else:
+                    leaves.append(child._v_name)
+
+            yield (g._v_pathname.rstrip("/"), groups, leaves)
+
+    def get_node(self, key: str) -> Node | None:
+        """return the node with the key or None if it does not exist"""
+        self._check_if_open()
+        if not key.startswith("/"):
+            key = "/" + key
+
+        assert self._handle is not None
+        assert _table_mod is not None  # for mypy
+        try:
+            node = self._handle.get_node(self.root, key)
+        except _table_mod.exceptions.NoSuchNodeError:
+            return None
+
+        assert isinstance(node, _table_mod.Node), type(node)
+        return node
+
+    def get_storer(self, key: str) -> GenericFixed | Table:
+        """return the storer object for a key, raise if not in the file"""
+        group = self.get_node(key)
+        if group is None:
+            raise KeyError(f"No object named {key} in the file")
+
+        s = self._create_storer(group)
+        s.infer_axes()
+        return s
+
+    def copy(
+        self,
+        file,
+        mode: str = "w",
+        propindexes: bool = True,
+        keys=None,
+        complib=None,
+        complevel: int | None = None,
+        fletcher32: bool = False,
+        overwrite: bool = True,
+    ) -> HDFStore:
+        """
+        Copy the existing store to a new file, updating in place.
+
+        Parameters
+        ----------
+        propindexes : bool, default True
+            Restore indexes in copied file.
+        keys : list, optional
+            List of keys to include in the copy (defaults to all).
+        overwrite : bool, default True
+            Whether to overwrite (remove and replace) existing nodes in the new store.
+        mode, complib, complevel, fletcher32 same as in HDFStore.__init__
+
+        Returns
+        -------
+        open file handle of the new store
+        """
+        new_store = HDFStore(
+            file, mode=mode, complib=complib, complevel=complevel, fletcher32=fletcher32
+        )
+        if keys is None:
+            keys = list(self.keys())
+        if not isinstance(keys, (tuple, list)):
+            keys = [keys]
+        for k in keys:
+            s = self.get_storer(k)
+            if s is not None:
+                if k in new_store:
+                    if overwrite:
+                        new_store.remove(k)
+
+                data = self.select(k)
+                if isinstance(s, Table):
+                    index: bool | list[str] = False
+                    if propindexes:
+                        index = [a.name for a in s.axes if a.is_indexed]
+                    new_store.append(
+                        k,
+                        data,
+                        index=index,
+                        data_columns=getattr(s, "data_columns", None),
+                        encoding=s.encoding,
+                    )
+                else:
+                    new_store.put(k, data, encoding=s.encoding)
+
+        return new_store
+
+    def info(self) -> str:
+        """
+        Print detailed information on the store.
+
+        Returns
+        -------
+        str
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=['A', 'B'])
+        >>> store = pd.HDFStore("store.h5", 'w')  # doctest: +SKIP
+        >>> store.put('data', df)  # doctest: +SKIP
+        >>> print(store.info())  # doctest: +SKIP
+        >>> store.close()  # doctest: +SKIP
+        
+        File path: store.h5
+        /data    frame    (shape->[2,2])
+        """
+        path = pprint_thing(self._path)
+        output = f"{type(self)}\nFile path: {path}\n"
+
+        if self.is_open:
+            lkeys = sorted(self.keys())
+            if len(lkeys):
+                keys = []
+                values = []
+
+                for k in lkeys:
+                    try:
+                        s = self.get_storer(k)
+                        if s is not None:
+                            keys.append(pprint_thing(s.pathname or k))
+                            values.append(pprint_thing(s or "invalid_HDFStore node"))
+                    except AssertionError:
+                        # surface any assertion errors for e.g. debugging
+                        raise
+                    except Exception as detail:
+                        keys.append(k)
+                        dstr = pprint_thing(detail)
+                        values.append(f"[invalid_HDFStore node: {dstr}]")
+
+                output += adjoin(12, keys, values)
+            else:
+                output += "Empty"
+        else:
+            output += "File is CLOSED"
+
+        return output
+
+    # ------------------------------------------------------------------------
+    # private methods
+
+    def _check_if_open(self) -> None:
+        if not self.is_open:
+            raise ClosedFileError(f"{self._path} file is not open!")
+
+    def _validate_format(self, format: str) -> str:
+        """validate / deprecate formats"""
+        # validate
+        try:
+            format = _FORMAT_MAP[format.lower()]
+        except KeyError as err:
+            raise TypeError(f"invalid HDFStore format specified [{format}]") from err
+
+        return format
+
+    def _create_storer(
+        self,
+        group,
+        format=None,
+        value: DataFrame | Series | None = None,
+        encoding: str = "UTF-8",
+        errors: str = "strict",
+    ) -> GenericFixed | Table:
+        """return a suitable class to operate"""
+        cls: type[GenericFixed | Table]
+
+        if value is not None and not isinstance(value, (Series, DataFrame)):
+            raise TypeError("value must be None, Series, or DataFrame")
+
+        pt = _ensure_decoded(getattr(group._v_attrs, "pandas_type", None))
+        tt = _ensure_decoded(getattr(group._v_attrs, "table_type", None))
+
+        # infer the pt from the passed value
+        if pt is None:
+            if value is None:
+                _tables()
+                assert _table_mod is not None  # for mypy
+                if getattr(group, "table", None) or isinstance(
+                    group, _table_mod.table.Table
+                ):
+                    pt = "frame_table"
+                    tt = "generic_table"
+                else:
+                    raise TypeError(
+                        "cannot create a storer if the object is not existing "
+                        "nor a value are passed"
+                    )
+            else:
+                if isinstance(value, Series):
+                    pt = "series"
+                else:
+                    pt = "frame"
+
+                # we are actually a table
+                if format == "table":
+                    pt += "_table"
+
+        # a storer node
+        if "table" not in pt:
+            _STORER_MAP = {"series": SeriesFixed, "frame": FrameFixed}
+            try:
+                cls = _STORER_MAP[pt]
+            except KeyError as err:
+                raise TypeError(
+                    f"cannot properly create the storer for: [_STORER_MAP] [group->"
+                    f"{group},value->{type(value)},format->{format}"
+                ) from err
+            return cls(self, group, encoding=encoding, errors=errors)
+
+        # existing node (and must be a table)
+        if tt is None:
+            # if we are a writer, determine the tt
+            if value is not None:
+                if pt == "series_table":
+                    index = getattr(value, "index", None)
+                    if index is not None:
+                        if index.nlevels == 1:
+                            tt = "appendable_series"
+                        elif index.nlevels > 1:
+                            tt = "appendable_multiseries"
+                elif pt == "frame_table":
+                    index = getattr(value, "index", None)
+                    if index is not None:
+                        if index.nlevels == 1:
+                            tt = "appendable_frame"
+                        elif index.nlevels > 1:
+                            tt = "appendable_multiframe"
+
+        _TABLE_MAP = {
+            "generic_table": GenericTable,
+            "appendable_series": AppendableSeriesTable,
+            "appendable_multiseries": AppendableMultiSeriesTable,
+            "appendable_frame": AppendableFrameTable,
+            "appendable_multiframe": AppendableMultiFrameTable,
+            "worm": WORMTable,
+        }
+        try:
+            cls = _TABLE_MAP[tt]
+        except KeyError as err:
+            raise TypeError(
+                f"cannot properly create the storer for: [_TABLE_MAP] [group->"
+                f"{group},value->{type(value)},format->{format}"
+            ) from err
+
+        return cls(self, group, encoding=encoding, errors=errors)
+
+    def _write_to_group(
+        self,
+        key: str,
+        value: DataFrame | Series,
+        format,
+        axes=None,
+        index: bool | list[str] = True,
+        append: bool = False,
+        complib=None,
+        complevel: int | None = None,
+        fletcher32=None,
+        min_itemsize: int | dict[str, int] | None = None,
+        chunksize: int | None = None,
+        expectedrows=None,
+        dropna: bool = False,
+        nan_rep=None,
+        data_columns=None,
+        encoding=None,
+        errors: str = "strict",
+        track_times: bool = True,
+    ) -> None:
+        # we don't want to store a table node at all if our object is 0-len
+        # as there are not dtypes
+        if getattr(value, "empty", None) and (format == "table" or append):
+            return
+
+        group = self._identify_group(key, append)
+
+        s = self._create_storer(group, format, value, encoding=encoding, errors=errors)
+        if append:
+            # raise if we are trying to append to a Fixed format,
+            #       or a table that exists (and we are putting)
+            if not s.is_table or (s.is_table and format == "fixed" and s.is_exists):
+                raise ValueError("Can only append to Tables")
+            if not s.is_exists:
+                s.set_object_info()
+        else:
+            s.set_object_info()
+
+        if not s.is_table and complib:
+            raise ValueError("Compression not supported on Fixed format stores")
+
+        # write the object
+        s.write(
+            obj=value,
+            axes=axes,
+            append=append,
+            complib=complib,
+            complevel=complevel,
+            fletcher32=fletcher32,
+            min_itemsize=min_itemsize,
+            chunksize=chunksize,
+            expectedrows=expectedrows,
+            dropna=dropna,
+            nan_rep=nan_rep,
+            data_columns=data_columns,
+            track_times=track_times,
+        )
+
+        if isinstance(s, Table) and index:
+            s.create_index(columns=index)
+
+    def _read_group(self, group: Node):
+        s = self._create_storer(group)
+        s.infer_axes()
+        return s.read()
+
+    def _identify_group(self, key: str, append: bool) -> Node:
+        """Identify HDF5 group based on key, delete/create group if needed."""
+        group = self.get_node(key)
+
+        # we make this assertion for mypy; the get_node call will already
+        # have raised if this is incorrect
+        assert self._handle is not None
+
+        # remove the node if we are not appending
+        if group is not None and not append:
+            self._handle.remove_node(group, recursive=True)
+            group = None
+
+        if group is None:
+            group = self._create_nodes_and_group(key)
+
+        return group
+
+    def _create_nodes_and_group(self, key: str) -> Node:
+        """Create nodes from key and return group name."""
+        # assertion for mypy
+        assert self._handle is not None
+
+        paths = key.split("/")
+        # recursively create the groups
+        path = "/"
+        for p in paths:
+            if not len(p):
+                continue
+            new_path = path
+            if not path.endswith("/"):
+                new_path += "/"
+            new_path += p
+            group = self.get_node(new_path)
+            if group is None:
+                group = self._handle.create_group(path, p)
+            path = new_path
+        return group
+
+
+class TableIterator:
+    """
+    Define the iteration interface on a table
+
+    Parameters
+    ----------
+    store : HDFStore
+    s     : the referred storer
+    func  : the function to execute the query
+    where : the where of the query
+    nrows : the rows to iterate on
+    start : the passed start value (default is None)
+    stop  : the passed stop value (default is None)
+    iterator : bool, default False
+        Whether to use the default iterator.
+    chunksize : the passed chunking value (default is 100000)
+    auto_close : bool, default False
+        Whether to automatically close the store at the end of iteration.
+    """
+
+    chunksize: int | None
+    store: HDFStore
+    s: GenericFixed | Table
+
+    def __init__(
+        self,
+        store: HDFStore,
+        s: GenericFixed | Table,
+        func,
+        where,
+        nrows,
+        start=None,
+        stop=None,
+        iterator: bool = False,
+        chunksize: int | None = None,
+        auto_close: bool = False,
+    ) -> None:
+        self.store = store
+        self.s = s
+        self.func = func
+        self.where = where
+
+        # set start/stop if they are not set if we are a table
+        if self.s.is_table:
+            if nrows is None:
+                nrows = 0
+            if start is None:
+                start = 0
+            if stop is None:
+                stop = nrows
+            stop = min(nrows, stop)
+
+        self.nrows = nrows
+        self.start = start
+        self.stop = stop
+
+        self.coordinates = None
+        if iterator or chunksize is not None:
+            if chunksize is None:
+                chunksize = 100000
+            self.chunksize = int(chunksize)
+        else:
+            self.chunksize = None
+
+        self.auto_close = auto_close
+
+    def __iter__(self) -> Iterator:
+        # iterate
+        current = self.start
+        if self.coordinates is None:
+            raise ValueError("Cannot iterate until get_result is called.")
+        while current < self.stop:
+            stop = min(current + self.chunksize, self.stop)
+            value = self.func(None, None, self.coordinates[current:stop])
+            current = stop
+            if value is None or not len(value):
+                continue
+
+            yield value
+
+        self.close()
+
+    def close(self) -> None:
+        if self.auto_close:
+            self.store.close()
+
+    def get_result(self, coordinates: bool = False):
+        #  return the actual iterator
+        if self.chunksize is not None:
+            if not isinstance(self.s, Table):
+                raise TypeError("can only use an iterator or chunksize on a table")
+
+            self.coordinates = self.s.read_coordinates(where=self.where)
+
+            return self
+
+        # if specified read via coordinates (necessary for multiple selections
+        if coordinates:
+            if not isinstance(self.s, Table):
+                raise TypeError("can only read_coordinates on a table")
+            where = self.s.read_coordinates(
+                where=self.where, start=self.start, stop=self.stop
+            )
+        else:
+            where = self.where
+
+        # directly return the result
+        results = self.func(self.start, self.stop, where)
+        self.close()
+        return results
+
+
+class IndexCol:
+    """
+    an index column description class
+
+    Parameters
+    ----------
+    axis   : axis which I reference
+    values : the ndarray like converted values
+    kind   : a string description of this type
+    typ    : the pytables type
+    pos    : the position in the pytables
+
+    """
+
+    is_an_indexable: bool = True
+    is_data_indexable: bool = True
+    _info_fields = ["freq", "tz", "index_name"]
+
+    def __init__(
+        self,
+        name: str,
+        values=None,
+        kind=None,
+        typ=None,
+        cname: str | None = None,
+        axis=None,
+        pos=None,
+        freq=None,
+        tz=None,
+        index_name=None,
+        ordered=None,
+        table=None,
+        meta=None,
+        metadata=None,
+    ) -> None:
+        if not isinstance(name, str):
+            raise ValueError("`name` must be a str.")
+
+        self.values = values
+        self.kind = kind
+        self.typ = typ
+        self.name = name
+        self.cname = cname or name
+        self.axis = axis
+        self.pos = pos
+        self.freq = freq
+        self.tz = tz
+        self.index_name = index_name
+        self.ordered = ordered
+        self.table = table
+        self.meta = meta
+        self.metadata = metadata
+
+        if pos is not None:
+            self.set_pos(pos)
+
+        # These are ensured as long as the passed arguments match the
+        #  constructor annotations.
+        assert isinstance(self.name, str)
+        assert isinstance(self.cname, str)
+
+    @property
+    def itemsize(self) -> int:
+        # Assumes self.typ has already been initialized
+        return self.typ.itemsize
+
+    @property
+    def kind_attr(self) -> str:
+        return f"{self.name}_kind"
+
+    def set_pos(self, pos: int) -> None:
+        """set the position of this column in the Table"""
+        self.pos = pos
+        if pos is not None and self.typ is not None:
+            self.typ._v_pos = pos
+
+    def __repr__(self) -> str:
+        temp = tuple(
+            map(pprint_thing, (self.name, self.cname, self.axis, self.pos, self.kind))
+        )
+        return ",".join(
+            [
+                f"{key}->{value}"
+                for key, value in zip(["name", "cname", "axis", "pos", "kind"], temp)
+            ]
+        )
+
+    def __eq__(self, other: object) -> bool:
+        """compare 2 col items"""
+        return all(
+            getattr(self, a, None) == getattr(other, a, None)
+            for a in ["name", "cname", "axis", "pos"]
+        )
+
+    def __ne__(self, other) -> bool:
+        return not self.__eq__(other)
+
+    @property
+    def is_indexed(self) -> bool:
+        """return whether I am an indexed column"""
+        if not hasattr(self.table, "cols"):
+            # e.g. if infer hasn't been called yet, self.table will be None.
+            return False
+        return getattr(self.table.cols, self.cname).is_indexed
+
+    def convert(
+        self, values: np.ndarray, nan_rep, encoding: str, errors: str
+    ) -> tuple[np.ndarray, np.ndarray] | tuple[Index, Index]:
+        """
+        Convert the data from this selection to the appropriate pandas type.
+        """
+        assert isinstance(values, np.ndarray), type(values)
+
+        # values is a recarray
+        if values.dtype.fields is not None:
+            # Copy, otherwise values will be a view
+            # preventing the original recarry from being free'ed
+            values = values[self.cname].copy()
+
+        val_kind = _ensure_decoded(self.kind)
+        values = _maybe_convert(values, val_kind, encoding, errors)
+        kwargs = {}
+        kwargs["name"] = _ensure_decoded(self.index_name)
+
+        if self.freq is not None:
+            kwargs["freq"] = _ensure_decoded(self.freq)
+
+        factory: type[Index | DatetimeIndex] = Index
+        if lib.is_np_dtype(values.dtype, "M") or isinstance(
+            values.dtype, DatetimeTZDtype
+        ):
+            factory = DatetimeIndex
+        elif values.dtype == "i8" and "freq" in kwargs:
+            # PeriodIndex data is stored as i8
+            # error: Incompatible types in assignment (expression has type
+            # "Callable[[Any, KwArg(Any)], PeriodIndex]", variable has type
+            # "Union[Type[Index], Type[DatetimeIndex]]")
+            factory = lambda x, **kwds: PeriodIndex.from_ordinals(  # type: ignore[assignment]
+                x, freq=kwds.get("freq", None)
+            )._rename(
+                kwds["name"]
+            )
+
+        # making an Index instance could throw a number of different errors
+        try:
+            new_pd_index = factory(values, **kwargs)
+        except UnicodeEncodeError as err:
+            if (
+                errors == "surrogatepass"
+                and get_option("future.infer_string")
+                and str(err).endswith("surrogates not allowed")
+                and HAS_PYARROW
+            ):
+                new_pd_index = factory(
+                    values,
+                    dtype=StringDtype(storage="python", na_value=np.nan),
+                    **kwargs,
+                )
+            else:
+                raise
+        except ValueError:
+            # if the output freq is different that what we recorded,
+            # it should be None (see also 'doc example part 2')
+            if "freq" in kwargs:
+                kwargs["freq"] = None
+            new_pd_index = factory(values, **kwargs)
+        final_pd_index = _set_tz(new_pd_index, self.tz)
+        return final_pd_index, final_pd_index
+
+    def take_data(self):
+        """return the values"""
+        return self.values
+
+    @property
+    def attrs(self):
+        return self.table._v_attrs
+
+    @property
+    def description(self):
+        return self.table.description
+
+    @property
+    def col(self):
+        """return my current col description"""
+        return getattr(self.description, self.cname, None)
+
+    @property
+    def cvalues(self):
+        """return my cython values"""
+        return self.values
+
+    def __iter__(self) -> Iterator:
+        return iter(self.values)
+
+    def maybe_set_size(self, min_itemsize=None) -> None:
+        """
+        maybe set a string col itemsize:
+            min_itemsize can be an integer or a dict with this columns name
+            with an integer size
+        """
+        if _ensure_decoded(self.kind) == "string":
+            if isinstance(min_itemsize, dict):
+                min_itemsize = min_itemsize.get(self.name)
+
+            if min_itemsize is not None and self.typ.itemsize < min_itemsize:
+                self.typ = _tables().StringCol(itemsize=min_itemsize, pos=self.pos)
+
+    def validate_names(self) -> None:
+        pass
+
+    def validate_and_set(self, handler: AppendableTable, append: bool) -> None:
+        self.table = handler.table
+        self.validate_col()
+        self.validate_attr(append)
+        self.validate_metadata(handler)
+        self.write_metadata(handler)
+        self.set_attr()
+
+    def validate_col(self, itemsize=None):
+        """validate this column: return the compared against itemsize"""
+        # validate this column for string truncation (or reset to the max size)
+        if _ensure_decoded(self.kind) == "string":
+            c = self.col
+            if c is not None:
+                if itemsize is None:
+                    itemsize = self.itemsize
+                if c.itemsize < itemsize:
+                    raise ValueError(
+                        f"Trying to store a string with len [{itemsize}] in "
+                        f"[{self.cname}] column but\nthis column has a limit of "
+                        f"[{c.itemsize}]!\nConsider using min_itemsize to "
+                        "preset the sizes on these columns"
+                    )
+                return c.itemsize
+
+        return None
+
+    def validate_attr(self, append: bool) -> None:
+        # check for backwards incompatibility
+        if append:
+            existing_kind = getattr(self.attrs, self.kind_attr, None)
+            if existing_kind is not None and existing_kind != self.kind:
+                raise TypeError(
+                    f"incompatible kind in col [{existing_kind} - {self.kind}]"
+                )
+
+    def update_info(self, info) -> None:
+        """
+        set/update the info for this indexable with the key/value
+        if there is a conflict raise/warn as needed
+        """
+        for key in self._info_fields:
+            value = getattr(self, key, None)
+            idx = info.setdefault(self.name, {})
+
+            existing_value = idx.get(key)
+            if key in idx and value is not None and existing_value != value:
+                # frequency/name just warn
+                if key in ["freq", "index_name"]:
+                    ws = attribute_conflict_doc % (key, existing_value, value)
+                    warnings.warn(
+                        ws, AttributeConflictWarning, stacklevel=find_stack_level()
+                    )
+
+                    # reset
+                    idx[key] = None
+                    setattr(self, key, None)
+
+                else:
+                    raise ValueError(
+                        f"invalid info for [{self.name}] for [{key}], "
+                        f"existing_value [{existing_value}] conflicts with "
+                        f"new value [{value}]"
+                    )
+            elif value is not None or existing_value is not None:
+                idx[key] = value
+
+    def set_info(self, info) -> None:
+        """set my state from the passed info"""
+        idx = info.get(self.name)
+        if idx is not None:
+            self.__dict__.update(idx)
+
+    def set_attr(self) -> None:
+        """set the kind for this column"""
+        setattr(self.attrs, self.kind_attr, self.kind)
+
+    def validate_metadata(self, handler: AppendableTable) -> None:
+        """validate that kind=category does not change the categories"""
+        if self.meta == "category":
+            new_metadata = self.metadata
+            cur_metadata = handler.read_metadata(self.cname)
+            if (
+                new_metadata is not None
+                and cur_metadata is not None
+                and not array_equivalent(
+                    new_metadata, cur_metadata, strict_nan=True, dtype_equal=True
+                )
+            ):
+                raise ValueError(
+                    "cannot append a categorical with "
+                    "different categories to the existing"
+                )
+
+    def write_metadata(self, handler: AppendableTable) -> None:
+        """set the meta data"""
+        if self.metadata is not None:
+            handler.write_metadata(self.cname, self.metadata)
+
+
+class GenericIndexCol(IndexCol):
+    """an index which is not represented in the data of the table"""
+
+    @property
+    def is_indexed(self) -> bool:
+        return False
+
+    def convert(
+        self, values: np.ndarray, nan_rep, encoding: str, errors: str
+    ) -> tuple[Index, Index]:
+        """
+        Convert the data from this selection to the appropriate pandas type.
+
+        Parameters
+        ----------
+        values : np.ndarray
+        nan_rep : str
+        encoding : str
+        errors : str
+        """
+        assert isinstance(values, np.ndarray), type(values)
+
+        index = RangeIndex(len(values))
+        return index, index
+
+    def set_attr(self) -> None:
+        pass
+
+
+class DataCol(IndexCol):
+    """
+    a data holding column, by definition this is not indexable
+
+    Parameters
+    ----------
+    data   : the actual data
+    cname  : the column name in the table to hold the data (typically
+                values)
+    meta   : a string description of the metadata
+    metadata : the actual metadata
+    """
+
+    is_an_indexable = False
+    is_data_indexable = False
+    _info_fields = ["tz", "ordered"]
+
+    def __init__(
+        self,
+        name: str,
+        values=None,
+        kind=None,
+        typ=None,
+        cname: str | None = None,
+        pos=None,
+        tz=None,
+        ordered=None,
+        table=None,
+        meta=None,
+        metadata=None,
+        dtype: DtypeArg | None = None,
+        data=None,
+    ) -> None:
+        super().__init__(
+            name=name,
+            values=values,
+            kind=kind,
+            typ=typ,
+            pos=pos,
+            cname=cname,
+            tz=tz,
+            ordered=ordered,
+            table=table,
+            meta=meta,
+            metadata=metadata,
+        )
+        self.dtype = dtype
+        self.data = data
+
+    @property
+    def dtype_attr(self) -> str:
+        return f"{self.name}_dtype"
+
+    @property
+    def meta_attr(self) -> str:
+        return f"{self.name}_meta"
+
+    def __repr__(self) -> str:
+        temp = tuple(
+            map(
+                pprint_thing, (self.name, self.cname, self.dtype, self.kind, self.shape)
+            )
+        )
+        return ",".join(
+            [
+                f"{key}->{value}"
+                for key, value in zip(["name", "cname", "dtype", "kind", "shape"], temp)
+            ]
+        )
+
+    def __eq__(self, other: object) -> bool:
+        """compare 2 col items"""
+        return all(
+            getattr(self, a, None) == getattr(other, a, None)
+            for a in ["name", "cname", "dtype", "pos"]
+        )
+
+    def set_data(self, data: ArrayLike) -> None:
+        assert data is not None
+        assert self.dtype is None
+
+        data, dtype_name = _get_data_and_dtype_name(data)
+
+        self.data = data
+        self.dtype = dtype_name
+        self.kind = _dtype_to_kind(dtype_name)
+
+    def take_data(self):
+        """return the data"""
+        return self.data
+
+    @classmethod
+    def _get_atom(cls, values: ArrayLike) -> Col:
+        """
+        Get an appropriately typed and shaped pytables.Col object for values.
+        """
+        dtype = values.dtype
+        # error: Item "ExtensionDtype" of "Union[ExtensionDtype, dtype[Any]]" has no
+        # attribute "itemsize"
+        itemsize = dtype.itemsize  # type: ignore[union-attr]
+
+        shape = values.shape
+        if values.ndim == 1:
+            # EA, use block shape pretending it is 2D
+            # TODO(EA2D): not necessary with 2D EAs
+            shape = (1, values.size)
+
+        if isinstance(values, Categorical):
+            codes = values.codes
+            atom = cls.get_atom_data(shape, kind=codes.dtype.name)
+        elif lib.is_np_dtype(dtype, "M") or isinstance(dtype, DatetimeTZDtype):
+            atom = cls.get_atom_datetime64(shape)
+        elif lib.is_np_dtype(dtype, "m"):
+            atom = cls.get_atom_timedelta64(shape)
+        elif is_complex_dtype(dtype):
+            atom = _tables().ComplexCol(itemsize=itemsize, shape=shape[0])
+        elif is_string_dtype(dtype):
+            atom = cls.get_atom_string(shape, itemsize)
+        else:
+            atom = cls.get_atom_data(shape, kind=dtype.name)
+
+        return atom
+
+    @classmethod
+    def get_atom_string(cls, shape, itemsize):
+        return _tables().StringCol(itemsize=itemsize, shape=shape[0])
+
+    @classmethod
+    def get_atom_coltype(cls, kind: str) -> type[Col]:
+        """return the PyTables column class for this column"""
+        if kind.startswith("uint"):
+            k4 = kind[4:]
+            col_name = f"UInt{k4}Col"
+        elif kind.startswith("period"):
+            # we store as integer
+            col_name = "Int64Col"
+        else:
+            kcap = kind.capitalize()
+            col_name = f"{kcap}Col"
+
+        return getattr(_tables(), col_name)
+
+    @classmethod
+    def get_atom_data(cls, shape, kind: str) -> Col:
+        return cls.get_atom_coltype(kind=kind)(shape=shape[0])
+
+    @classmethod
+    def get_atom_datetime64(cls, shape):
+        return _tables().Int64Col(shape=shape[0])
+
+    @classmethod
+    def get_atom_timedelta64(cls, shape):
+        return _tables().Int64Col(shape=shape[0])
+
+    @property
+    def shape(self):
+        return getattr(self.data, "shape", None)
+
+    @property
+    def cvalues(self):
+        """return my cython values"""
+        return self.data
+
+    def validate_attr(self, append) -> None:
+        """validate that we have the same order as the existing & same dtype"""
+        if append:
+            existing_fields = getattr(self.attrs, self.kind_attr, None)
+            if existing_fields is not None and existing_fields != list(self.values):
+                raise ValueError("appended items do not match existing items in table!")
+
+            existing_dtype = getattr(self.attrs, self.dtype_attr, None)
+            if existing_dtype is not None and existing_dtype != self.dtype:
+                raise ValueError(
+                    "appended items dtype do not match existing items dtype in table!"
+                )
+
+    def convert(self, values: np.ndarray, nan_rep, encoding: str, errors: str):
+        """
+        Convert the data from this selection to the appropriate pandas type.
+
+        Parameters
+        ----------
+        values : np.ndarray
+        nan_rep :
+        encoding : str
+        errors : str
+
+        Returns
+        -------
+        index : listlike to become an Index
+        data : ndarraylike to become a column
+        """
+        assert isinstance(values, np.ndarray), type(values)
+
+        # values is a recarray
+        if values.dtype.fields is not None:
+            values = values[self.cname]
+
+        assert self.typ is not None
+        if self.dtype is None:
+            # Note: in tests we never have timedelta64 or datetime64,
+            #  so the _get_data_and_dtype_name may be unnecessary
+            converted, dtype_name = _get_data_and_dtype_name(values)
+            kind = _dtype_to_kind(dtype_name)
+        else:
+            converted = values
+            dtype_name = self.dtype
+            kind = self.kind
+
+        assert isinstance(converted, np.ndarray)  # for mypy
+
+        # use the meta if needed
+        meta = _ensure_decoded(self.meta)
+        metadata = self.metadata
+        ordered = self.ordered
+        tz = self.tz
+
+        assert dtype_name is not None
+        # convert to the correct dtype
+        dtype = _ensure_decoded(dtype_name)
+
+        # reverse converts
+        if dtype.startswith("datetime64"):
+            # recreate with tz if indicated
+            converted = _set_tz(converted, tz, coerce=True)
+
+        elif dtype == "timedelta64":
+            converted = np.asarray(converted, dtype="m8[ns]")
+        elif dtype == "date":
+            try:
+                converted = np.asarray(
+                    [date.fromordinal(v) for v in converted], dtype=object
+                )
+            except ValueError:
+                converted = np.asarray(
+                    [date.fromtimestamp(v) for v in converted], dtype=object
+                )
+
+        elif meta == "category":
+            # we have a categorical
+            categories = metadata
+            codes = converted.ravel()
+
+            # if we have stored a NaN in the categories
+            # then strip it; in theory we could have BOTH
+            # -1s in the codes and nulls :<
+            if categories is None:
+                # Handle case of NaN-only categorical columns in which case
+                # the categories are an empty array; when this is stored,
+                # pytables cannot write a zero-len array, so on readback
+                # the categories would be None and `read_hdf()` would fail.
+                categories = Index([], dtype=np.float64)
+            else:
+                mask = isna(categories)
+                if mask.any():
+                    categories = categories[~mask]
+                    codes[codes != -1] -= mask.astype(int).cumsum()._values
+
+            converted = Categorical.from_codes(
+                codes, categories=categories, ordered=ordered, validate=False
+            )
+
+        else:
+            try:
+                converted = converted.astype(dtype, copy=False)
+            except TypeError:
+                converted = converted.astype("O", copy=False)
+
+        # convert nans / decode
+        if _ensure_decoded(kind) == "string":
+            converted = _unconvert_string_array(
+                converted, nan_rep=nan_rep, encoding=encoding, errors=errors
+            )
+
+        return self.values, converted
+
+    def set_attr(self) -> None:
+        """set the data for this column"""
+        setattr(self.attrs, self.kind_attr, self.values)
+        setattr(self.attrs, self.meta_attr, self.meta)
+        assert self.dtype is not None
+        setattr(self.attrs, self.dtype_attr, self.dtype)
+
+
+class DataIndexableCol(DataCol):
+    """represent a data column that can be indexed"""
+
+    is_data_indexable = True
+
+    def validate_names(self) -> None:
+        if not is_string_dtype(Index(self.values).dtype):
+            # TODO: should the message here be more specifically non-str?
+            raise ValueError("cannot have non-object label DataIndexableCol")
+
+    @classmethod
+    def get_atom_string(cls, shape, itemsize):
+        return _tables().StringCol(itemsize=itemsize)
+
+    @classmethod
+    def get_atom_data(cls, shape, kind: str) -> Col:
+        return cls.get_atom_coltype(kind=kind)()
+
+    @classmethod
+    def get_atom_datetime64(cls, shape):
+        return _tables().Int64Col()
+
+    @classmethod
+    def get_atom_timedelta64(cls, shape):
+        return _tables().Int64Col()
+
+
+class GenericDataIndexableCol(DataIndexableCol):
+    """represent a generic pytables data column"""
+
+
+class Fixed:
+    """
+    represent an object in my store
+    facilitate read/write of various types of objects
+    this is an abstract base class
+
+    Parameters
+    ----------
+    parent : HDFStore
+    group : Node
+        The group node where the table resides.
+    """
+
+    pandas_kind: str
+    format_type: str = "fixed"  # GH#30962 needed by dask
+    obj_type: type[DataFrame | Series]
+    ndim: int
+    parent: HDFStore
+    is_table: bool = False
+
+    def __init__(
+        self,
+        parent: HDFStore,
+        group: Node,
+        encoding: str | None = "UTF-8",
+        errors: str = "strict",
+    ) -> None:
+        assert isinstance(parent, HDFStore), type(parent)
+        assert _table_mod is not None  # needed for mypy
+        assert isinstance(group, _table_mod.Node), type(group)
+        self.parent = parent
+        self.group = group
+        self.encoding = _ensure_encoding(encoding)
+        self.errors = errors
+
+    @property
+    def is_old_version(self) -> bool:
+        return self.version[0] <= 0 and self.version[1] <= 10 and self.version[2] < 1
+
+    @property
+    def version(self) -> tuple[int, int, int]:
+        """compute and set our version"""
+        version = _ensure_decoded(getattr(self.group._v_attrs, "pandas_version", None))
+        try:
+            version = tuple(int(x) for x in version.split("."))
+            if len(version) == 2:
+                version = version + (0,)
+        except AttributeError:
+            version = (0, 0, 0)
+        return version
+
+    @property
+    def pandas_type(self):
+        return _ensure_decoded(getattr(self.group._v_attrs, "pandas_type", None))
+
+    def __repr__(self) -> str:
+        """return a pretty representation of myself"""
+        self.infer_axes()
+        s = self.shape
+        if s is not None:
+            if isinstance(s, (list, tuple)):
+                jshape = ",".join([pprint_thing(x) for x in s])
+                s = f"[{jshape}]"
+            return f"{self.pandas_type:12.12} (shape->{s})"
+        return self.pandas_type
+
+    def set_object_info(self) -> None:
+        """set my pandas type & version"""
+        self.attrs.pandas_type = str(self.pandas_kind)
+        self.attrs.pandas_version = str(_version)
+
+    def copy(self) -> Fixed:
+        new_self = copy.copy(self)
+        return new_self
+
+    @property
+    def shape(self):
+        return self.nrows
+
+    @property
+    def pathname(self):
+        return self.group._v_pathname
+
+    @property
+    def _handle(self):
+        return self.parent._handle
+
+    @property
+    def _filters(self):
+        return self.parent._filters
+
+    @property
+    def _complevel(self) -> int:
+        return self.parent._complevel
+
+    @property
+    def _fletcher32(self) -> bool:
+        return self.parent._fletcher32
+
+    @property
+    def attrs(self):
+        return self.group._v_attrs
+
+    def set_attrs(self) -> None:
+        """set our object attributes"""
+
+    def get_attrs(self) -> None:
+        """get our object attributes"""
+
+    @property
+    def storable(self):
+        """return my storable"""
+        return self.group
+
+    @property
+    def is_exists(self) -> bool:
+        return False
+
+    @property
+    def nrows(self):
+        return getattr(self.storable, "nrows", None)
+
+    def validate(self, other) -> Literal[True] | None:
+        """validate against an existing storable"""
+        if other is None:
+            return None
+        return True
+
+    def validate_version(self, where=None) -> None:
+        """are we trying to operate on an old version?"""
+
+    def infer_axes(self) -> bool:
+        """
+        infer the axes of my storer
+        return a boolean indicating if we have a valid storer or not
+        """
+        s = self.storable
+        if s is None:
+            return False
+        self.get_attrs()
+        return True
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        raise NotImplementedError(
+            "cannot read on an abstract storer: subclasses should implement"
+        )
+
+    def write(self, obj, **kwargs) -> None:
+        raise NotImplementedError(
+            "cannot write on an abstract storer: subclasses should implement"
+        )
+
+    def delete(
+        self, where=None, start: int | None = None, stop: int | None = None
+    ) -> None:
+        """
+        support fully deleting the node in its entirety (only) - where
+        specification must be None
+        """
+        if com.all_none(where, start, stop):
+            self._handle.remove_node(self.group, recursive=True)
+            return None
+
+        raise TypeError("cannot delete on an abstract storer")
+
+
+class GenericFixed(Fixed):
+    """a generified fixed version"""
+
+    _index_type_map = {DatetimeIndex: "datetime", PeriodIndex: "period"}
+    _reverse_index_map = {v: k for k, v in _index_type_map.items()}
+    attributes: list[str] = []
+
+    # indexer helpers
+    def _class_to_alias(self, cls) -> str:
+        return self._index_type_map.get(cls, "")
+
+    def _alias_to_class(self, alias):
+        if isinstance(alias, type):  # pragma: no cover
+            # compat: for a short period of time master stored types
+            return alias
+        return self._reverse_index_map.get(alias, Index)
+
+    def _get_index_factory(self, attrs):
+        index_class = self._alias_to_class(
+            _ensure_decoded(getattr(attrs, "index_class", ""))
+        )
+
+        factory: Callable
+
+        if index_class == DatetimeIndex:
+
+            def f(values, freq=None, tz=None):
+                # data are already in UTC, localize and convert if tz present
+                dta = DatetimeArray._simple_new(
+                    values.values, dtype=values.dtype, freq=freq
+                )
+                result = DatetimeIndex._simple_new(dta, name=None)
+                if tz is not None:
+                    result = result.tz_localize("UTC").tz_convert(tz)
+                return result
+
+            factory = f
+        elif index_class == PeriodIndex:
+
+            def f(values, freq=None, tz=None):
+                dtype = PeriodDtype(freq)
+                parr = PeriodArray._simple_new(values, dtype=dtype)
+                return PeriodIndex._simple_new(parr, name=None)
+
+            factory = f
+        else:
+            factory = index_class
+
+        kwargs = {}
+        if "freq" in attrs:
+            kwargs["freq"] = attrs["freq"]
+            if index_class is Index:
+                # DTI/PI would be gotten by _alias_to_class
+                factory = TimedeltaIndex
+
+        if "tz" in attrs:
+            if isinstance(attrs["tz"], bytes):
+                # created by python2
+                kwargs["tz"] = attrs["tz"].decode("utf-8")
+            else:
+                # created by python3
+                kwargs["tz"] = attrs["tz"]
+            assert index_class is DatetimeIndex  # just checking
+
+        return factory, kwargs
+
+    def validate_read(self, columns, where) -> None:
+        """
+        raise if any keywords are passed which are not-None
+        """
+        if columns is not None:
+            raise TypeError(
+                "cannot pass a column specification when reading "
+                "a Fixed format store. this store must be selected in its entirety"
+            )
+        if where is not None:
+            raise TypeError(
+                "cannot pass a where specification when reading "
+                "from a Fixed format store. this store must be selected in its entirety"
+            )
+
+    @property
+    def is_exists(self) -> bool:
+        return True
+
+    def set_attrs(self) -> None:
+        """set our object attributes"""
+        self.attrs.encoding = self.encoding
+        self.attrs.errors = self.errors
+
+    def get_attrs(self) -> None:
+        """retrieve our attributes"""
+        self.encoding = _ensure_encoding(getattr(self.attrs, "encoding", None))
+        self.errors = _ensure_decoded(getattr(self.attrs, "errors", "strict"))
+        for n in self.attributes:
+            setattr(self, n, _ensure_decoded(getattr(self.attrs, n, None)))
+
+    def write(self, obj, **kwargs) -> None:
+        self.set_attrs()
+
+    def read_array(self, key: str, start: int | None = None, stop: int | None = None):
+        """read an array for the specified node (off of group"""
+        import tables
+
+        node = getattr(self.group, key)
+        attrs = node._v_attrs
+
+        transposed = getattr(attrs, "transposed", False)
+
+        if isinstance(node, tables.VLArray):
+            ret = node[0][start:stop]
+            dtype = getattr(attrs, "value_type", None)
+            if dtype is not None:
+                ret = pd_array(ret, dtype=dtype)
+        else:
+            dtype = _ensure_decoded(getattr(attrs, "value_type", None))
+            shape = getattr(attrs, "shape", None)
+
+            if shape is not None:
+                # length 0 axis
+                ret = np.empty(shape, dtype=dtype)
+            else:
+                ret = node[start:stop]
+
+            if dtype and dtype.startswith("datetime64"):
+                # reconstruct a timezone if indicated
+                tz = getattr(attrs, "tz", None)
+                ret = _set_tz(ret, tz, coerce=True)
+
+            elif dtype == "timedelta64":
+                ret = np.asarray(ret, dtype="m8[ns]")
+
+        if transposed:
+            return ret.T
+        else:
+            return ret
+
+    def read_index(
+        self, key: str, start: int | None = None, stop: int | None = None
+    ) -> Index:
+        variety = _ensure_decoded(getattr(self.attrs, f"{key}_variety"))
+
+        if variety == "multi":
+            return self.read_multi_index(key, start=start, stop=stop)
+        elif variety == "regular":
+            node = getattr(self.group, key)
+            index = self.read_index_node(node, start=start, stop=stop)
+            return index
+        else:  # pragma: no cover
+            raise TypeError(f"unrecognized index variety: {variety}")
+
+    def write_index(self, key: str, index: Index) -> None:
+        if isinstance(index, MultiIndex):
+            setattr(self.attrs, f"{key}_variety", "multi")
+            self.write_multi_index(key, index)
+        else:
+            setattr(self.attrs, f"{key}_variety", "regular")
+            converted = _convert_index("index", index, self.encoding, self.errors)
+
+            self.write_array(key, converted.values)
+
+            node = getattr(self.group, key)
+            node._v_attrs.kind = converted.kind
+            node._v_attrs.name = index.name
+
+            if isinstance(index, (DatetimeIndex, PeriodIndex)):
+                node._v_attrs.index_class = self._class_to_alias(type(index))
+
+            if isinstance(index, (DatetimeIndex, PeriodIndex, TimedeltaIndex)):
+                node._v_attrs.freq = index.freq
+
+            if isinstance(index, DatetimeIndex) and index.tz is not None:
+                node._v_attrs.tz = _get_tz(index.tz)
+
+    def write_multi_index(self, key: str, index: MultiIndex) -> None:
+        setattr(self.attrs, f"{key}_nlevels", index.nlevels)
+
+        for i, (lev, level_codes, name) in enumerate(
+            zip(index.levels, index.codes, index.names)
+        ):
+            # write the level
+            if isinstance(lev.dtype, ExtensionDtype):
+                raise NotImplementedError(
+                    "Saving a MultiIndex with an extension dtype is not supported."
+                )
+            level_key = f"{key}_level{i}"
+            conv_level = _convert_index(level_key, lev, self.encoding, self.errors)
+            self.write_array(level_key, conv_level.values)
+            node = getattr(self.group, level_key)
+            node._v_attrs.kind = conv_level.kind
+            node._v_attrs.name = name
+
+            # write the name
+            setattr(node._v_attrs, f"{key}_name{name}", name)
+
+            # write the labels
+            label_key = f"{key}_label{i}"
+            self.write_array(label_key, level_codes)
+
+    def read_multi_index(
+        self, key: str, start: int | None = None, stop: int | None = None
+    ) -> MultiIndex:
+        nlevels = getattr(self.attrs, f"{key}_nlevels")
+
+        levels = []
+        codes = []
+        names: list[Hashable] = []
+        for i in range(nlevels):
+            level_key = f"{key}_level{i}"
+            node = getattr(self.group, level_key)
+            lev = self.read_index_node(node, start=start, stop=stop)
+            levels.append(lev)
+            names.append(lev.name)
+
+            label_key = f"{key}_label{i}"
+            level_codes = self.read_array(label_key, start=start, stop=stop)
+            codes.append(level_codes)
+
+        return MultiIndex(
+            levels=levels, codes=codes, names=names, verify_integrity=True
+        )
+
+    def read_index_node(
+        self, node: Node, start: int | None = None, stop: int | None = None
+    ) -> Index:
+        data = node[start:stop]
+        # If the index was an empty array write_array_empty() will
+        # have written a sentinel. Here we replace it with the original.
+        if "shape" in node._v_attrs and np.prod(node._v_attrs.shape) == 0:
+            data = np.empty(node._v_attrs.shape, dtype=node._v_attrs.value_type)
+        kind = _ensure_decoded(node._v_attrs.kind)
+        name = None
+
+        if "name" in node._v_attrs:
+            name = _ensure_str(node._v_attrs.name)
+            name = _ensure_decoded(name)
+
+        attrs = node._v_attrs
+        factory, kwargs = self._get_index_factory(attrs)
+
+        if kind in ("date", "object"):
+            index = factory(
+                _unconvert_index(
+                    data, kind, encoding=self.encoding, errors=self.errors
+                ),
+                dtype=object,
+                **kwargs,
+            )
+        else:
+            try:
+                index = factory(
+                    _unconvert_index(
+                        data, kind, encoding=self.encoding, errors=self.errors
+                    ),
+                    **kwargs,
+                )
+            except UnicodeEncodeError as err:
+                if (
+                    self.errors == "surrogatepass"
+                    and get_option("future.infer_string")
+                    and str(err).endswith("surrogates not allowed")
+                    and HAS_PYARROW
+                ):
+                    index = factory(
+                        _unconvert_index(
+                            data, kind, encoding=self.encoding, errors=self.errors
+                        ),
+                        dtype=StringDtype(storage="python", na_value=np.nan),
+                        **kwargs,
+                    )
+                else:
+                    raise
+
+        index.name = name
+
+        return index
+
+    def write_array_empty(self, key: str, value: ArrayLike) -> None:
+        """write a 0-len array"""
+        # ugly hack for length 0 axes
+        arr = np.empty((1,) * value.ndim)
+        self._handle.create_array(self.group, key, arr)
+        node = getattr(self.group, key)
+        node._v_attrs.value_type = str(value.dtype)
+        node._v_attrs.shape = value.shape
+
+    def write_array(
+        self, key: str, obj: AnyArrayLike, items: Index | None = None
+    ) -> None:
+        # TODO: we only have a few tests that get here, the only EA
+        #  that gets passed is DatetimeArray, and we never have
+        #  both self._filters and EA
+
+        value = extract_array(obj, extract_numpy=True)
+
+        if key in self.group:
+            self._handle.remove_node(self.group, key)
+
+        # Transform needed to interface with pytables row/col notation
+        empty_array = value.size == 0
+        transposed = False
+
+        if isinstance(value.dtype, CategoricalDtype):
+            raise NotImplementedError(
+                "Cannot store a category dtype in a HDF5 dataset that uses format="
+                '"fixed". Use format="table".'
+            )
+        if not empty_array:
+            if hasattr(value, "T"):
+                # ExtensionArrays (1d) may not have transpose.
+                value = value.T
+                transposed = True
+
+        atom = None
+        if self._filters is not None:
+            with suppress(ValueError):
+                # get the atom for this datatype
+                atom = _tables().Atom.from_dtype(value.dtype)
+
+        if atom is not None:
+            # We only get here if self._filters is non-None and
+            #  the Atom.from_dtype call succeeded
+
+            # create an empty chunked array and fill it from value
+            if not empty_array:
+                ca = self._handle.create_carray(
+                    self.group, key, atom, value.shape, filters=self._filters
+                )
+                ca[:] = value
+
+            else:
+                self.write_array_empty(key, value)
+
+        elif value.dtype.type == np.object_:
+            # infer the type, warn if we have a non-string type here (for
+            # performance)
+            inferred_type = lib.infer_dtype(value, skipna=False)
+            if empty_array:
+                pass
+            elif inferred_type == "string":
+                pass
+            else:
+                ws = performance_doc % (inferred_type, key, items)
+                warnings.warn(ws, PerformanceWarning, stacklevel=find_stack_level())
+
+            vlarr = self._handle.create_vlarray(self.group, key, _tables().ObjectAtom())
+            vlarr.append(value)
+
+        elif lib.is_np_dtype(value.dtype, "M"):
+            self._handle.create_array(self.group, key, value.view("i8"))
+            getattr(self.group, key)._v_attrs.value_type = str(value.dtype)
+        elif isinstance(value.dtype, DatetimeTZDtype):
+            # store as UTC
+            # with a zone
+
+            # error: Item "ExtensionArray" of "Union[Any, ExtensionArray]" has no
+            # attribute "asi8"
+            self._handle.create_array(
+                self.group, key, value.asi8  # type: ignore[union-attr]
+            )
+
+            node = getattr(self.group, key)
+            # error: Item "ExtensionArray" of "Union[Any, ExtensionArray]" has no
+            # attribute "tz"
+            node._v_attrs.tz = _get_tz(value.tz)  # type: ignore[union-attr]
+            node._v_attrs.value_type = f"datetime64[{value.dtype.unit}]"
+        elif lib.is_np_dtype(value.dtype, "m"):
+            self._handle.create_array(self.group, key, value.view("i8"))
+            getattr(self.group, key)._v_attrs.value_type = "timedelta64"
+        elif isinstance(value, BaseStringArray):
+            vlarr = self._handle.create_vlarray(self.group, key, _tables().ObjectAtom())
+            vlarr.append(value.to_numpy())
+            node = getattr(self.group, key)
+            node._v_attrs.value_type = str(value.dtype)
+        elif empty_array:
+            self.write_array_empty(key, value)
+        else:
+            self._handle.create_array(self.group, key, value)
+
+        getattr(self.group, key)._v_attrs.transposed = transposed
+
+
+class SeriesFixed(GenericFixed):
+    pandas_kind = "series"
+    attributes = ["name"]
+
+    name: Hashable
+
+    @property
+    def shape(self):
+        try:
+            return (len(self.group.values),)
+        except (TypeError, AttributeError):
+            return None
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> Series:
+        self.validate_read(columns, where)
+        index = self.read_index("index", start=start, stop=stop)
+        values = self.read_array("values", start=start, stop=stop)
+        try:
+            result = Series(values, index=index, name=self.name, copy=False)
+        except UnicodeEncodeError as err:
+            if (
+                self.errors == "surrogatepass"
+                and get_option("future.infer_string")
+                and str(err).endswith("surrogates not allowed")
+                and HAS_PYARROW
+            ):
+                result = Series(
+                    values,
+                    index=index,
+                    name=self.name,
+                    copy=False,
+                    dtype=StringDtype(storage="python", na_value=np.nan),
+                )
+            else:
+                raise
+        return result
+
+    def write(self, obj, **kwargs) -> None:
+        super().write(obj, **kwargs)
+        self.write_index("index", obj.index)
+        self.write_array("values", obj)
+        self.attrs.name = obj.name
+
+
+class BlockManagerFixed(GenericFixed):
+    attributes = ["ndim", "nblocks"]
+
+    nblocks: int
+
+    @property
+    def shape(self) -> Shape | None:
+        try:
+            ndim = self.ndim
+
+            # items
+            items = 0
+            for i in range(self.nblocks):
+                node = getattr(self.group, f"block{i}_items")
+                shape = getattr(node, "shape", None)
+                if shape is not None:
+                    items += shape[0]
+
+            # data shape
+            node = self.group.block0_values
+            shape = getattr(node, "shape", None)
+            if shape is not None:
+                shape = list(shape[0 : (ndim - 1)])
+            else:
+                shape = []
+
+            shape.append(items)
+
+            return shape
+        except AttributeError:
+            return None
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> DataFrame:
+        # start, stop applied to rows, so 0th axis only
+        self.validate_read(columns, where)
+        select_axis = self.obj_type()._get_block_manager_axis(0)
+
+        axes = []
+        for i in range(self.ndim):
+            _start, _stop = (start, stop) if i == select_axis else (None, None)
+            ax = self.read_index(f"axis{i}", start=_start, stop=_stop)
+            axes.append(ax)
+
+        items = axes[0]
+        dfs = []
+
+        for i in range(self.nblocks):
+            blk_items = self.read_index(f"block{i}_items")
+            values = self.read_array(f"block{i}_values", start=_start, stop=_stop)
+
+            columns = items[items.get_indexer(blk_items)]
+            df = DataFrame(values.T, columns=columns, index=axes[1], copy=False)
+            if (
+                using_string_dtype()
+                and isinstance(values, np.ndarray)
+                and is_string_array(values, skipna=True)
+            ):
+                df = df.astype(StringDtype(na_value=np.nan))
+            dfs.append(df)
+
+        if len(dfs) > 0:
+            out = concat(dfs, axis=1, copy=True)
+            if using_copy_on_write():
+                # with CoW, concat ignores the copy keyword. Here, we still want
+                # to copy to enforce optimized column-major layout
+                out = out.copy()
+            out = out.reindex(columns=items, copy=False)
+            return out
+
+        return DataFrame(columns=axes[0], index=axes[1])
+
+    def write(self, obj, **kwargs) -> None:
+        super().write(obj, **kwargs)
+
+        # TODO(ArrayManager) HDFStore relies on accessing the blocks
+        if isinstance(obj._mgr, ArrayManager):
+            obj = obj._as_manager("block")
+
+        data = obj._mgr
+        if not data.is_consolidated():
+            data = data.consolidate()
+
+        self.attrs.ndim = data.ndim
+        for i, ax in enumerate(data.axes):
+            if i == 0 and (not ax.is_unique):
+                raise ValueError("Columns index has to be unique for fixed format")
+            self.write_index(f"axis{i}", ax)
+
+        # Supporting mixed-type DataFrame objects...nontrivial
+        self.attrs.nblocks = len(data.blocks)
+        for i, blk in enumerate(data.blocks):
+            # I have no idea why, but writing values before items fixed #2299
+            blk_items = data.items.take(blk.mgr_locs)
+            self.write_array(f"block{i}_values", blk.values, items=blk_items)
+            self.write_index(f"block{i}_items", blk_items)
+
+
+class FrameFixed(BlockManagerFixed):
+    pandas_kind = "frame"
+    obj_type = DataFrame
+
+
+class Table(Fixed):
+    """
+    represent a table:
+        facilitate read/write of various types of tables
+
+    Attrs in Table Node
+    -------------------
+    These are attributes that are store in the main table node, they are
+    necessary to recreate these tables when read back in.
+
+    index_axes    : a list of tuples of the (original indexing axis and
+        index column)
+    non_index_axes: a list of tuples of the (original index axis and
+        columns on a non-indexing axis)
+    values_axes   : a list of the columns which comprise the data of this
+        table
+    data_columns  : a list of the columns that we are allowing indexing
+        (these become single columns in values_axes)
+    nan_rep       : the string to use for nan representations for string
+        objects
+    levels        : the names of levels
+    metadata      : the names of the metadata columns
+    """
+
+    pandas_kind = "wide_table"
+    format_type: str = "table"  # GH#30962 needed by dask
+    table_type: str
+    levels: int | list[Hashable] = 1
+    is_table = True
+
+    metadata: list
+
+    def __init__(
+        self,
+        parent: HDFStore,
+        group: Node,
+        encoding: str | None = None,
+        errors: str = "strict",
+        index_axes: list[IndexCol] | None = None,
+        non_index_axes: list[tuple[AxisInt, Any]] | None = None,
+        values_axes: list[DataCol] | None = None,
+        data_columns: list | None = None,
+        info: dict | None = None,
+        nan_rep=None,
+    ) -> None:
+        super().__init__(parent, group, encoding=encoding, errors=errors)
+        self.index_axes = index_axes or []
+        self.non_index_axes = non_index_axes or []
+        self.values_axes = values_axes or []
+        self.data_columns = data_columns or []
+        self.info = info or {}
+        self.nan_rep = nan_rep
+
+    @property
+    def table_type_short(self) -> str:
+        return self.table_type.split("_")[0]
+
+    def __repr__(self) -> str:
+        """return a pretty representation of myself"""
+        self.infer_axes()
+        jdc = ",".join(self.data_columns) if len(self.data_columns) else ""
+        dc = f",dc->[{jdc}]"
+
+        ver = ""
+        if self.is_old_version:
+            jver = ".".join([str(x) for x in self.version])
+            ver = f"[{jver}]"
+
+        jindex_axes = ",".join([a.name for a in self.index_axes])
+        return (
+            f"{self.pandas_type:12.12}{ver} "
+            f"(typ->{self.table_type_short},nrows->{self.nrows},"
+            f"ncols->{self.ncols},indexers->[{jindex_axes}]{dc})"
+        )
+
+    def __getitem__(self, c: str):
+        """return the axis for c"""
+        for a in self.axes:
+            if c == a.name:
+                return a
+        return None
+
+    def validate(self, other) -> None:
+        """validate against an existing table"""
+        if other is None:
+            return
+
+        if other.table_type != self.table_type:
+            raise TypeError(
+                "incompatible table_type with existing "
+                f"[{other.table_type} - {self.table_type}]"
+            )
+
+        for c in ["index_axes", "non_index_axes", "values_axes"]:
+            sv = getattr(self, c, None)
+            ov = getattr(other, c, None)
+            if sv != ov:
+                # show the error for the specific axes
+                # Argument 1 to "enumerate" has incompatible type
+                # "Optional[Any]"; expected "Iterable[Any]"  [arg-type]
+                for i, sax in enumerate(sv):  # type: ignore[arg-type]
+                    # Value of type "Optional[Any]" is not indexable  [index]
+                    oax = ov[i]  # type: ignore[index]
+                    if sax != oax:
+                        if c == "values_axes" and sax.kind != oax.kind:
+                            raise ValueError(
+                                f"Cannot serialize the column [{oax.values[0]}] "
+                                f"because its data contents are not [{sax.kind}] "
+                                f"but [{oax.kind}] object dtype"
+                            )
+                        raise ValueError(
+                            f"invalid combination of [{c}] on appending data "
+                            f"[{sax}] vs current table [{oax}]"
+                        )
+
+                # should never get here
+                raise Exception(
+                    f"invalid combination of [{c}] on appending data [{sv}] vs "
+                    f"current table [{ov}]"
+                )
+
+    @property
+    def is_multi_index(self) -> bool:
+        """the levels attribute is 1 or a list in the case of a multi-index"""
+        return isinstance(self.levels, list)
+
+    def validate_multiindex(
+        self, obj: DataFrame | Series
+    ) -> tuple[DataFrame, list[Hashable]]:
+        """
+        validate that we can store the multi-index; reset and return the
+        new object
+        """
+        levels = com.fill_missing_names(obj.index.names)
+        try:
+            reset_obj = obj.reset_index()
+        except ValueError as err:
+            raise ValueError(
+                "duplicate names/columns in the multi-index when storing as a table"
+            ) from err
+        assert isinstance(reset_obj, DataFrame)  # for mypy
+        return reset_obj, levels
+
+    @property
+    def nrows_expected(self) -> int:
+        """based on our axes, compute the expected nrows"""
+        return np.prod([i.cvalues.shape[0] for i in self.index_axes])
+
+    @property
+    def is_exists(self) -> bool:
+        """has this table been created"""
+        return "table" in self.group
+
+    @property
+    def storable(self):
+        return getattr(self.group, "table", None)
+
+    @property
+    def table(self):
+        """return the table group (this is my storable)"""
+        return self.storable
+
+    @property
+    def dtype(self):
+        return self.table.dtype
+
+    @property
+    def description(self):
+        return self.table.description
+
+    @property
+    def axes(self) -> itertools.chain[IndexCol]:
+        return itertools.chain(self.index_axes, self.values_axes)
+
+    @property
+    def ncols(self) -> int:
+        """the number of total columns in the values axes"""
+        return sum(len(a.values) for a in self.values_axes)
+
+    @property
+    def is_transposed(self) -> bool:
+        return False
+
+    @property
+    def data_orientation(self) -> tuple[int, ...]:
+        """return a tuple of my permutated axes, non_indexable at the front"""
+        return tuple(
+            itertools.chain(
+                [int(a[0]) for a in self.non_index_axes],
+                [int(a.axis) for a in self.index_axes],
+            )
+        )
+
+    def queryables(self) -> dict[str, Any]:
+        """return a dict of the kinds allowable columns for this object"""
+        # mypy doesn't recognize DataFrame._AXIS_NAMES, so we re-write it here
+        axis_names = {0: "index", 1: "columns"}
+
+        # compute the values_axes queryables
+        d1 = [(a.cname, a) for a in self.index_axes]
+        d2 = [(axis_names[axis], None) for axis, values in self.non_index_axes]
+        d3 = [
+            (v.cname, v) for v in self.values_axes if v.name in set(self.data_columns)
+        ]
+
+        return dict(d1 + d2 + d3)
+
+    def index_cols(self):
+        """return a list of my index cols"""
+        # Note: each `i.cname` below is assured to be a str.
+        return [(i.axis, i.cname) for i in self.index_axes]
+
+    def values_cols(self) -> list[str]:
+        """return a list of my values cols"""
+        return [i.cname for i in self.values_axes]
+
+    def _get_metadata_path(self, key: str) -> str:
+        """return the metadata pathname for this key"""
+        group = self.group._v_pathname
+        return f"{group}/meta/{key}/meta"
+
+    def write_metadata(self, key: str, values: np.ndarray) -> None:
+        """
+        Write out a metadata array to the key as a fixed-format Series.
+
+        Parameters
+        ----------
+        key : str
+        values : ndarray
+        """
+        self.parent.put(
+            self._get_metadata_path(key),
+            Series(values, copy=False),
+            format="table",
+            encoding=self.encoding,
+            errors=self.errors,
+            nan_rep=self.nan_rep,
+        )
+
+    def read_metadata(self, key: str):
+        """return the meta data array for this key"""
+        if getattr(getattr(self.group, "meta", None), key, None) is not None:
+            return self.parent.select(self._get_metadata_path(key))
+        return None
+
+    def set_attrs(self) -> None:
+        """set our table type & indexables"""
+        self.attrs.table_type = str(self.table_type)
+        self.attrs.index_cols = self.index_cols()
+        self.attrs.values_cols = self.values_cols()
+        self.attrs.non_index_axes = self.non_index_axes
+        self.attrs.data_columns = self.data_columns
+        self.attrs.nan_rep = self.nan_rep
+        self.attrs.encoding = self.encoding
+        self.attrs.errors = self.errors
+        self.attrs.levels = self.levels
+        self.attrs.info = self.info
+
+    def get_attrs(self) -> None:
+        """retrieve our attributes"""
+        self.non_index_axes = getattr(self.attrs, "non_index_axes", None) or []
+        self.data_columns = getattr(self.attrs, "data_columns", None) or []
+        self.info = getattr(self.attrs, "info", None) or {}
+        self.nan_rep = getattr(self.attrs, "nan_rep", None)
+        self.encoding = _ensure_encoding(getattr(self.attrs, "encoding", None))
+        self.errors = _ensure_decoded(getattr(self.attrs, "errors", "strict"))
+        self.levels: list[Hashable] = getattr(self.attrs, "levels", None) or []
+        self.index_axes = [a for a in self.indexables if a.is_an_indexable]
+        self.values_axes = [a for a in self.indexables if not a.is_an_indexable]
+
+    def validate_version(self, where=None) -> None:
+        """are we trying to operate on an old version?"""
+        if where is not None:
+            if self.is_old_version:
+                ws = incompatibility_doc % ".".join([str(x) for x in self.version])
+                warnings.warn(
+                    ws,
+                    IncompatibilityWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+    def validate_min_itemsize(self, min_itemsize) -> None:
+        """
+        validate the min_itemsize doesn't contain items that are not in the
+        axes this needs data_columns to be defined
+        """
+        if min_itemsize is None:
+            return
+        if not isinstance(min_itemsize, dict):
+            return
+
+        q = self.queryables()
+        for k in min_itemsize:
+            # ok, apply generally
+            if k == "values":
+                continue
+            if k not in q:
+                raise ValueError(
+                    f"min_itemsize has the key [{k}] which is not an axis or "
+                    "data_column"
+                )
+
+    @cache_readonly
+    def indexables(self):
+        """create/cache the indexables if they don't exist"""
+        _indexables = []
+
+        desc = self.description
+        table_attrs = self.table.attrs
+
+        # Note: each of the `name` kwargs below are str, ensured
+        #  by the definition in index_cols.
+        # index columns
+        for i, (axis, name) in enumerate(self.attrs.index_cols):
+            atom = getattr(desc, name)
+            md = self.read_metadata(name)
+            meta = "category" if md is not None else None
+
+            kind_attr = f"{name}_kind"
+            kind = getattr(table_attrs, kind_attr, None)
+
+            index_col = IndexCol(
+                name=name,
+                axis=axis,
+                pos=i,
+                kind=kind,
+                typ=atom,
+                table=self.table,
+                meta=meta,
+                metadata=md,
+            )
+            _indexables.append(index_col)
+
+        # values columns
+        dc = set(self.data_columns)
+        base_pos = len(_indexables)
+
+        def f(i, c):
+            assert isinstance(c, str)
+            klass = DataCol
+            if c in dc:
+                klass = DataIndexableCol
+
+            atom = getattr(desc, c)
+            adj_name = _maybe_adjust_name(c, self.version)
+
+            # TODO: why kind_attr here?
+            values = getattr(table_attrs, f"{adj_name}_kind", None)
+            dtype = getattr(table_attrs, f"{adj_name}_dtype", None)
+            # Argument 1 to "_dtype_to_kind" has incompatible type
+            # "Optional[Any]"; expected "str"  [arg-type]
+            kind = _dtype_to_kind(dtype)  # type: ignore[arg-type]
+
+            md = self.read_metadata(c)
+            # TODO: figure out why these two versions of `meta` dont always match.
+            #  meta = "category" if md is not None else None
+            meta = getattr(table_attrs, f"{adj_name}_meta", None)
+
+            obj = klass(
+                name=adj_name,
+                cname=c,
+                values=values,
+                kind=kind,
+                pos=base_pos + i,
+                typ=atom,
+                table=self.table,
+                meta=meta,
+                metadata=md,
+                dtype=dtype,
+            )
+            return obj
+
+        # Note: the definition of `values_cols` ensures that each
+        #  `c` below is a str.
+        _indexables.extend([f(i, c) for i, c in enumerate(self.attrs.values_cols)])
+
+        return _indexables
+
+    def create_index(
+        self, columns=None, optlevel=None, kind: str | None = None
+    ) -> None:
+        """
+        Create a pytables index on the specified columns.
+
+        Parameters
+        ----------
+        columns : None, bool, or listlike[str]
+            Indicate which columns to create an index on.
+
+            * False : Do not create any indexes.
+            * True : Create indexes on all columns.
+            * None : Create indexes on all columns.
+            * listlike : Create indexes on the given columns.
+
+        optlevel : int or None, default None
+            Optimization level, if None, pytables defaults to 6.
+        kind : str or None, default None
+            Kind of index, if None, pytables defaults to "medium".
+
+        Raises
+        ------
+        TypeError if trying to create an index on a complex-type column.
+
+        Notes
+        -----
+        Cannot index Time64Col or ComplexCol.
+        Pytables must be >= 3.0.
+        """
+        if not self.infer_axes():
+            return
+        if columns is False:
+            return
+
+        # index all indexables and data_columns
+        if columns is None or columns is True:
+            columns = [a.cname for a in self.axes if a.is_data_indexable]
+        if not isinstance(columns, (tuple, list)):
+            columns = [columns]
+
+        kw = {}
+        if optlevel is not None:
+            kw["optlevel"] = optlevel
+        if kind is not None:
+            kw["kind"] = kind
+
+        table = self.table
+        for c in columns:
+            v = getattr(table.cols, c, None)
+            if v is not None:
+                # remove the index if the kind/optlevel have changed
+                if v.is_indexed:
+                    index = v.index
+                    cur_optlevel = index.optlevel
+                    cur_kind = index.kind
+
+                    if kind is not None and cur_kind != kind:
+                        v.remove_index()
+                    else:
+                        kw["kind"] = cur_kind
+
+                    if optlevel is not None and cur_optlevel != optlevel:
+                        v.remove_index()
+                    else:
+                        kw["optlevel"] = cur_optlevel
+
+                # create the index
+                if not v.is_indexed:
+                    if v.type.startswith("complex"):
+                        raise TypeError(
+                            "Columns containing complex values can be stored but "
+                            "cannot be indexed when using table format. Either use "
+                            "fixed format, set index=False, or do not include "
+                            "the columns containing complex values to "
+                            "data_columns when initializing the table."
+                        )
+                    v.create_index(**kw)
+            elif c in self.non_index_axes[0][1]:
+                # GH 28156
+                raise AttributeError(
+                    f"column {c} is not a data_column.\n"
+                    f"In order to read column {c} you must reload the dataframe \n"
+                    f"into HDFStore and include {c} with the data_columns argument."
+                )
+
+    def _read_axes(
+        self, where, start: int | None = None, stop: int | None = None
+    ) -> list[tuple[np.ndarray, np.ndarray] | tuple[Index, Index]]:
+        """
+        Create the axes sniffed from the table.
+
+        Parameters
+        ----------
+        where : ???
+        start : int or None, default None
+        stop : int or None, default None
+
+        Returns
+        -------
+        List[Tuple[index_values, column_values]]
+        """
+        # create the selection
+        selection = Selection(self, where=where, start=start, stop=stop)
+        values = selection.select()
+
+        results = []
+        # convert the data
+        for a in self.axes:
+            a.set_info(self.info)
+            res = a.convert(
+                values,
+                nan_rep=self.nan_rep,
+                encoding=self.encoding,
+                errors=self.errors,
+            )
+            results.append(res)
+
+        return results
+
+    @classmethod
+    def get_object(cls, obj, transposed: bool):
+        """return the data for this obj"""
+        return obj
+
+    def validate_data_columns(self, data_columns, min_itemsize, non_index_axes):
+        """
+        take the input data_columns and min_itemize and create a data
+        columns spec
+        """
+        if not len(non_index_axes):
+            return []
+
+        axis, axis_labels = non_index_axes[0]
+        info = self.info.get(axis, {})
+        if info.get("type") == "MultiIndex" and data_columns:
+            raise ValueError(
+                f"cannot use a multi-index on axis [{axis}] with "
+                f"data_columns {data_columns}"
+            )
+
+        # evaluate the passed data_columns, True == use all columns
+        # take only valid axis labels
+        if data_columns is True:
+            data_columns = list(axis_labels)
+        elif data_columns is None:
+            data_columns = []
+
+        # if min_itemsize is a dict, add the keys (exclude 'values')
+        if isinstance(min_itemsize, dict):
+            existing_data_columns = set(data_columns)
+            data_columns = list(data_columns)  # ensure we do not modify
+            data_columns.extend(
+                [
+                    k
+                    for k in min_itemsize.keys()
+                    if k != "values" and k not in existing_data_columns
+                ]
+            )
+
+        # return valid columns in the order of our axis
+        return [c for c in data_columns if c in axis_labels]
+
+    def _create_axes(
+        self,
+        axes,
+        obj: DataFrame,
+        validate: bool = True,
+        nan_rep=None,
+        data_columns=None,
+        min_itemsize=None,
+    ):
+        """
+        Create and return the axes.
+
+        Parameters
+        ----------
+        axes: list or None
+            The names or numbers of the axes to create.
+        obj : DataFrame
+            The object to create axes on.
+        validate: bool, default True
+            Whether to validate the obj against an existing object already written.
+        nan_rep :
+            A value to use for string column nan_rep.
+        data_columns : List[str], True, or None, default None
+            Specify the columns that we want to create to allow indexing on.
+
+            * True : Use all available columns.
+            * None : Use no columns.
+            * List[str] : Use the specified columns.
+
+        min_itemsize: Dict[str, int] or None, default None
+            The min itemsize for a column in bytes.
+        """
+        if not isinstance(obj, DataFrame):
+            group = self.group._v_name
+            raise TypeError(
+                f"cannot properly create the storer for: [group->{group},"
+                f"value->{type(obj)}]"
+            )
+
+        # set the default axes if needed
+        if axes is None:
+            axes = [0]
+
+        # map axes to numbers
+        axes = [obj._get_axis_number(a) for a in axes]
+
+        # do we have an existing table (if so, use its axes & data_columns)
+        if self.infer_axes():
+            table_exists = True
+            axes = [a.axis for a in self.index_axes]
+            data_columns = list(self.data_columns)
+            nan_rep = self.nan_rep
+            # TODO: do we always have validate=True here?
+        else:
+            table_exists = False
+
+        new_info = self.info
+
+        assert self.ndim == 2  # with next check, we must have len(axes) == 1
+        # currently support on ndim-1 axes
+        if len(axes) != self.ndim - 1:
+            raise ValueError(
+                "currently only support ndim-1 indexers in an AppendableTable"
+            )
+
+        # create according to the new data
+        new_non_index_axes: list = []
+
+        # nan_representation
+        if nan_rep is None:
+            nan_rep = "nan"
+
+        # We construct the non-index-axis first, since that alters new_info
+        idx = next(x for x in [0, 1] if x not in axes)
+
+        a = obj.axes[idx]
+        # we might be able to change the axes on the appending data if necessary
+        append_axis = list(a)
+        if table_exists:
+            indexer = len(new_non_index_axes)  # i.e. 0
+            exist_axis = self.non_index_axes[indexer][1]
+            if not array_equivalent(
+                np.array(append_axis),
+                np.array(exist_axis),
+                strict_nan=True,
+                dtype_equal=True,
+            ):
+                # ahah! -> reindex
+                if array_equivalent(
+                    np.array(sorted(append_axis)),
+                    np.array(sorted(exist_axis)),
+                    strict_nan=True,
+                    dtype_equal=True,
+                ):
+                    append_axis = exist_axis
+
+        # the non_index_axes info
+        info = new_info.setdefault(idx, {})
+        info["names"] = list(a.names)
+        info["type"] = type(a).__name__
+
+        new_non_index_axes.append((idx, append_axis))
+
+        # Now we can construct our new index axis
+        idx = axes[0]
+        a = obj.axes[idx]
+        axis_name = obj._get_axis_name(idx)
+        new_index = _convert_index(axis_name, a, self.encoding, self.errors)
+        new_index.axis = idx
+
+        # Because we are always 2D, there is only one new_index, so
+        #  we know it will have pos=0
+        new_index.set_pos(0)
+        new_index.update_info(new_info)
+        new_index.maybe_set_size(min_itemsize)  # check for column conflicts
+
+        new_index_axes = [new_index]
+        j = len(new_index_axes)  # i.e. 1
+        assert j == 1
+
+        # reindex by our non_index_axes & compute data_columns
+        assert len(new_non_index_axes) == 1
+        for a in new_non_index_axes:
+            obj = _reindex_axis(obj, a[0], a[1])
+
+        transposed = new_index.axis == 1
+
+        # figure out data_columns and get out blocks
+        data_columns = self.validate_data_columns(
+            data_columns, min_itemsize, new_non_index_axes
+        )
+
+        frame = self.get_object(obj, transposed)._consolidate()
+
+        blocks, blk_items = self._get_blocks_and_items(
+            frame, table_exists, new_non_index_axes, self.values_axes, data_columns
+        )
+
+        # add my values
+        vaxes = []
+        for i, (blk, b_items) in enumerate(zip(blocks, blk_items)):
+            # shape of the data column are the indexable axes
+            klass = DataCol
+            name = None
+
+            # we have a data_column
+            if data_columns and len(b_items) == 1 and b_items[0] in data_columns:
+                klass = DataIndexableCol
+                name = b_items[0]
+                if not (name is None or isinstance(name, str)):
+                    # TODO: should the message here be more specifically non-str?
+                    raise ValueError("cannot have non-object label DataIndexableCol")
+
+            # make sure that we match up the existing columns
+            # if we have an existing table
+            existing_col: DataCol | None
+
+            if table_exists and validate:
+                try:
+                    existing_col = self.values_axes[i]
+                except (IndexError, KeyError) as err:
+                    raise ValueError(
+                        f"Incompatible appended table [{blocks}]"
+                        f"with existing table [{self.values_axes}]"
+                    ) from err
+            else:
+                existing_col = None
+
+            new_name = name or f"values_block_{i}"
+            data_converted = _maybe_convert_for_string_atom(
+                new_name,
+                blk.values,
+                existing_col=existing_col,
+                min_itemsize=min_itemsize,
+                nan_rep=nan_rep,
+                encoding=self.encoding,
+                errors=self.errors,
+                columns=b_items,
+            )
+            adj_name = _maybe_adjust_name(new_name, self.version)
+
+            typ = klass._get_atom(data_converted)
+            kind = _dtype_to_kind(data_converted.dtype.name)
+            tz = None
+            if getattr(data_converted, "tz", None) is not None:
+                tz = _get_tz(data_converted.tz)
+
+            meta = metadata = ordered = None
+            if isinstance(data_converted.dtype, CategoricalDtype):
+                ordered = data_converted.ordered
+                meta = "category"
+                metadata = np.asarray(data_converted.categories).ravel()
+            elif isinstance(blk.dtype, StringDtype):
+                meta = str(blk.dtype)
+
+            data, dtype_name = _get_data_and_dtype_name(data_converted)
+
+            col = klass(
+                name=adj_name,
+                cname=new_name,
+                values=list(b_items),
+                typ=typ,
+                pos=j,
+                kind=kind,
+                tz=tz,
+                ordered=ordered,
+                meta=meta,
+                metadata=metadata,
+                dtype=dtype_name,
+                data=data,
+            )
+            col.update_info(new_info)
+
+            vaxes.append(col)
+
+            j += 1
+
+        dcs = [col.name for col in vaxes if col.is_data_indexable]
+
+        new_table = type(self)(
+            parent=self.parent,
+            group=self.group,
+            encoding=self.encoding,
+            errors=self.errors,
+            index_axes=new_index_axes,
+            non_index_axes=new_non_index_axes,
+            values_axes=vaxes,
+            data_columns=dcs,
+            info=new_info,
+            nan_rep=nan_rep,
+        )
+        if hasattr(self, "levels"):
+            # TODO: get this into constructor, only for appropriate subclass
+            new_table.levels = self.levels
+
+        new_table.validate_min_itemsize(min_itemsize)
+
+        if validate and table_exists:
+            new_table.validate(self)
+
+        return new_table
+
+    @staticmethod
+    def _get_blocks_and_items(
+        frame: DataFrame,
+        table_exists: bool,
+        new_non_index_axes,
+        values_axes,
+        data_columns,
+    ):
+        # Helper to clarify non-state-altering parts of _create_axes
+
+        # TODO(ArrayManager) HDFStore relies on accessing the blocks
+        if isinstance(frame._mgr, ArrayManager):
+            frame = frame._as_manager("block")
+
+        def get_blk_items(mgr):
+            return [mgr.items.take(blk.mgr_locs) for blk in mgr.blocks]
+
+        mgr = frame._mgr
+        mgr = cast(BlockManager, mgr)
+        blocks: list[Block] = list(mgr.blocks)
+        blk_items: list[Index] = get_blk_items(mgr)
+
+        if len(data_columns):
+            # TODO: prove that we only get here with axis == 1?
+            #  It is the case in all extant tests, but NOT the case
+            #  outside this `if len(data_columns)` check.
+
+            axis, axis_labels = new_non_index_axes[0]
+            new_labels = Index(axis_labels).difference(Index(data_columns))
+            mgr = frame.reindex(new_labels, axis=axis)._mgr
+            mgr = cast(BlockManager, mgr)
+
+            blocks = list(mgr.blocks)
+            blk_items = get_blk_items(mgr)
+            for c in data_columns:
+                # This reindex would raise ValueError if we had a duplicate
+                #  index, so we can infer that (as long as axis==1) we
+                #  get a single column back, so a single block.
+                mgr = frame.reindex([c], axis=axis)._mgr
+                mgr = cast(BlockManager, mgr)
+                blocks.extend(mgr.blocks)
+                blk_items.extend(get_blk_items(mgr))
+
+        # reorder the blocks in the same order as the existing table if we can
+        if table_exists:
+            by_items = {
+                tuple(b_items.tolist()): (b, b_items)
+                for b, b_items in zip(blocks, blk_items)
+            }
+            new_blocks: list[Block] = []
+            new_blk_items = []
+            for ea in values_axes:
+                items = tuple(ea.values)
+                try:
+                    b, b_items = by_items.pop(items)
+                    new_blocks.append(b)
+                    new_blk_items.append(b_items)
+                except (IndexError, KeyError) as err:
+                    jitems = ",".join([pprint_thing(item) for item in items])
+                    raise ValueError(
+                        f"cannot match existing table structure for [{jitems}] "
+                        "on appending data"
+                    ) from err
+            blocks = new_blocks
+            blk_items = new_blk_items
+
+        return blocks, blk_items
+
+    def process_axes(self, obj, selection: Selection, columns=None) -> DataFrame:
+        """process axes filters"""
+        # make a copy to avoid side effects
+        if columns is not None:
+            columns = list(columns)
+
+        # make sure to include levels if we have them
+        if columns is not None and self.is_multi_index:
+            assert isinstance(self.levels, list)  # assured by is_multi_index
+            for n in self.levels:
+                if n not in columns:
+                    columns.insert(0, n)
+
+        # reorder by any non_index_axes & limit to the select columns
+        for axis, labels in self.non_index_axes:
+            obj = _reindex_axis(obj, axis, labels, columns)
+
+            def process_filter(field, filt, op):
+                for axis_name in obj._AXIS_ORDERS:
+                    axis_number = obj._get_axis_number(axis_name)
+                    axis_values = obj._get_axis(axis_name)
+                    assert axis_number is not None
+
+                    # see if the field is the name of an axis
+                    if field == axis_name:
+                        # if we have a multi-index, then need to include
+                        # the levels
+                        if self.is_multi_index:
+                            filt = filt.union(Index(self.levels))
+
+                        takers = op(axis_values, filt)
+                        return obj.loc(axis=axis_number)[takers]
+
+                    # this might be the name of a file IN an axis
+                    elif field in axis_values:
+                        # we need to filter on this dimension
+                        values = ensure_index(getattr(obj, field).values)
+                        filt = ensure_index(filt)
+
+                        # hack until we support reversed dim flags
+                        if isinstance(obj, DataFrame):
+                            axis_number = 1 - axis_number
+
+                        takers = op(values, filt)
+                        return obj.loc(axis=axis_number)[takers]
+
+                raise ValueError(f"cannot find the field [{field}] for filtering!")
+
+        # apply the selection filters (but keep in the same order)
+        if selection.filter is not None:
+            for field, op, filt in selection.filter.format():
+                obj = process_filter(field, filt, op)
+
+        return obj
+
+    def create_description(
+        self,
+        complib,
+        complevel: int | None,
+        fletcher32: bool,
+        expectedrows: int | None,
+    ) -> dict[str, Any]:
+        """create the description of the table from the axes & values"""
+        # provided expected rows if its passed
+        if expectedrows is None:
+            expectedrows = max(self.nrows_expected, 10000)
+
+        d = {"name": "table", "expectedrows": expectedrows}
+
+        # description from the axes & values
+        d["description"] = {a.cname: a.typ for a in self.axes}
+
+        if complib:
+            if complevel is None:
+                complevel = self._complevel or 9
+            filters = _tables().Filters(
+                complevel=complevel,
+                complib=complib,
+                fletcher32=fletcher32 or self._fletcher32,
+            )
+            d["filters"] = filters
+        elif self._filters is not None:
+            d["filters"] = self._filters
+
+        return d
+
+    def read_coordinates(
+        self, where=None, start: int | None = None, stop: int | None = None
+    ):
+        """
+        select coordinates (row numbers) from a table; return the
+        coordinates object
+        """
+        # validate the version
+        self.validate_version(where)
+
+        # infer the data kind
+        if not self.infer_axes():
+            return False
+
+        # create the selection
+        selection = Selection(self, where=where, start=start, stop=stop)
+        coords = selection.select_coords()
+        if selection.filter is not None:
+            for field, op, filt in selection.filter.format():
+                data = self.read_column(
+                    field, start=coords.min(), stop=coords.max() + 1
+                )
+                coords = coords[op(data.iloc[coords - coords.min()], filt).values]
+
+        return Index(coords)
+
+    def read_column(
+        self,
+        column: str,
+        where=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        """
+        return a single column from the table, generally only indexables
+        are interesting
+        """
+        # validate the version
+        self.validate_version()
+
+        # infer the data kind
+        if not self.infer_axes():
+            return False
+
+        if where is not None:
+            raise TypeError("read_column does not currently accept a where clause")
+
+        # find the axes
+        for a in self.axes:
+            if column == a.name:
+                if not a.is_data_indexable:
+                    raise ValueError(
+                        f"column [{column}] can not be extracted individually; "
+                        "it is not data indexable"
+                    )
+
+                # column must be an indexable or a data column
+                c = getattr(self.table.cols, column)
+                a.set_info(self.info)
+                col_values = a.convert(
+                    c[start:stop],
+                    nan_rep=self.nan_rep,
+                    encoding=self.encoding,
+                    errors=self.errors,
+                )
+                cvs = _set_tz(col_values[1], a.tz)
+                dtype = getattr(self.table.attrs, f"{column}_meta", None)
+                return Series(cvs, name=column, copy=False, dtype=dtype)
+
+        raise KeyError(f"column [{column}] not found in the table")
+
+
+class WORMTable(Table):
+    """
+    a write-once read-many table: this format DOES NOT ALLOW appending to a
+    table. writing is a one-time operation the data are stored in a format
+    that allows for searching the data on disk
+    """
+
+    table_type = "worm"
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        """
+        read the indices and the indexing array, calculate offset rows and return
+        """
+        raise NotImplementedError("WORMTable needs to implement read")
+
+    def write(self, obj, **kwargs) -> None:
+        """
+        write in a format that we can search later on (but cannot append
+        to): write out the indices and the values using _write_array
+        (e.g. a CArray) create an indexing table so that we can search
+        """
+        raise NotImplementedError("WORMTable needs to implement write")
+
+
+class AppendableTable(Table):
+    """support the new appendable table formats"""
+
+    table_type = "appendable"
+
+    # error: Signature of "write" incompatible with supertype "Fixed"
+    def write(  # type: ignore[override]
+        self,
+        obj,
+        axes=None,
+        append: bool = False,
+        complib=None,
+        complevel=None,
+        fletcher32=None,
+        min_itemsize=None,
+        chunksize: int | None = None,
+        expectedrows=None,
+        dropna: bool = False,
+        nan_rep=None,
+        data_columns=None,
+        track_times: bool = True,
+    ) -> None:
+        if not append and self.is_exists:
+            self._handle.remove_node(self.group, "table")
+
+        # create the axes
+        table = self._create_axes(
+            axes=axes,
+            obj=obj,
+            validate=append,
+            min_itemsize=min_itemsize,
+            nan_rep=nan_rep,
+            data_columns=data_columns,
+        )
+
+        for a in table.axes:
+            a.validate_names()
+
+        if not table.is_exists:
+            # create the table
+            options = table.create_description(
+                complib=complib,
+                complevel=complevel,
+                fletcher32=fletcher32,
+                expectedrows=expectedrows,
+            )
+
+            # set the table attributes
+            table.set_attrs()
+
+            options["track_times"] = track_times
+
+            # create the table
+            table._handle.create_table(table.group, **options)
+
+        # update my info
+        table.attrs.info = table.info
+
+        # validate the axes and set the kinds
+        for a in table.axes:
+            a.validate_and_set(table, append)
+
+        # add the rows
+        table.write_data(chunksize, dropna=dropna)
+
+    def write_data(self, chunksize: int | None, dropna: bool = False) -> None:
+        """
+        we form the data into a 2-d including indexes,values,mask write chunk-by-chunk
+        """
+        names = self.dtype.names
+        nrows = self.nrows_expected
+
+        # if dropna==True, then drop ALL nan rows
+        masks = []
+        if dropna:
+            for a in self.values_axes:
+                # figure the mask: only do if we can successfully process this
+                # column, otherwise ignore the mask
+                mask = isna(a.data).all(axis=0)
+                if isinstance(mask, np.ndarray):
+                    masks.append(mask.astype("u1", copy=False))
+
+        # consolidate masks
+        if len(masks):
+            mask = masks[0]
+            for m in masks[1:]:
+                mask = mask & m
+            mask = mask.ravel()
+        else:
+            mask = None
+
+        # broadcast the indexes if needed
+        indexes = [a.cvalues for a in self.index_axes]
+        nindexes = len(indexes)
+        assert nindexes == 1, nindexes  # ensures we dont need to broadcast
+
+        # transpose the values so first dimension is last
+        # reshape the values if needed
+        values = [a.take_data() for a in self.values_axes]
+        values = [v.transpose(np.roll(np.arange(v.ndim), v.ndim - 1)) for v in values]
+        bvalues = []
+        for i, v in enumerate(values):
+            new_shape = (nrows,) + self.dtype[names[nindexes + i]].shape
+            bvalues.append(v.reshape(new_shape))
+
+        # write the chunks
+        if chunksize is None:
+            chunksize = 100000
+
+        rows = np.empty(min(chunksize, nrows), dtype=self.dtype)
+        chunks = nrows // chunksize + 1
+        for i in range(chunks):
+            start_i = i * chunksize
+            end_i = min((i + 1) * chunksize, nrows)
+            if start_i >= end_i:
+                break
+
+            self.write_data_chunk(
+                rows,
+                indexes=[a[start_i:end_i] for a in indexes],
+                mask=mask[start_i:end_i] if mask is not None else None,
+                values=[v[start_i:end_i] for v in bvalues],
+            )
+
+    def write_data_chunk(
+        self,
+        rows: np.ndarray,
+        indexes: list[np.ndarray],
+        mask: npt.NDArray[np.bool_] | None,
+        values: list[np.ndarray],
+    ) -> None:
+        """
+        Parameters
+        ----------
+        rows : an empty memory space where we are putting the chunk
+        indexes : an array of the indexes
+        mask : an array of the masks
+        values : an array of the values
+        """
+        # 0 len
+        for v in values:
+            if not np.prod(v.shape):
+                return
+
+        nrows = indexes[0].shape[0]
+        if nrows != len(rows):
+            rows = np.empty(nrows, dtype=self.dtype)
+        names = self.dtype.names
+        nindexes = len(indexes)
+
+        # indexes
+        for i, idx in enumerate(indexes):
+            rows[names[i]] = idx
+
+        # values
+        for i, v in enumerate(values):
+            rows[names[i + nindexes]] = v
+
+        # mask
+        if mask is not None:
+            m = ~mask.ravel().astype(bool, copy=False)
+            if not m.all():
+                rows = rows[m]
+
+        if len(rows):
+            self.table.append(rows)
+            self.table.flush()
+
+    def delete(self, where=None, start: int | None = None, stop: int | None = None):
+        # delete all rows (and return the nrows)
+        if where is None or not len(where):
+            if start is None and stop is None:
+                nrows = self.nrows
+                self._handle.remove_node(self.group, recursive=True)
+            else:
+                # pytables<3.0 would remove a single row with stop=None
+                if stop is None:
+                    stop = self.nrows
+                nrows = self.table.remove_rows(start=start, stop=stop)
+                self.table.flush()
+            return nrows
+
+        # infer the data kind
+        if not self.infer_axes():
+            return None
+
+        # create the selection
+        table = self.table
+        selection = Selection(self, where, start=start, stop=stop)
+        values = selection.select_coords()
+
+        # delete the rows in reverse order
+        sorted_series = Series(values, copy=False).sort_values()
+        ln = len(sorted_series)
+
+        if ln:
+            # construct groups of consecutive rows
+            diff = sorted_series.diff()
+            groups = list(diff[diff > 1].index)
+
+            # 1 group
+            if not len(groups):
+                groups = [0]
+
+            # final element
+            if groups[-1] != ln:
+                groups.append(ln)
+
+            # initial element
+            if groups[0] != 0:
+                groups.insert(0, 0)
+
+            # we must remove in reverse order!
+            pg = groups.pop()
+            for g in reversed(groups):
+                rows = sorted_series.take(range(g, pg))
+                table.remove_rows(
+                    start=rows[rows.index[0]], stop=rows[rows.index[-1]] + 1
+                )
+                pg = g
+
+            self.table.flush()
+
+        # return the number of rows removed
+        return ln
+
+
+class AppendableFrameTable(AppendableTable):
+    """support the new appendable table formats"""
+
+    pandas_kind = "frame_table"
+    table_type = "appendable_frame"
+    ndim = 2
+    obj_type: type[DataFrame | Series] = DataFrame
+
+    @property
+    def is_transposed(self) -> bool:
+        return self.index_axes[0].axis == 1
+
+    @classmethod
+    def get_object(cls, obj, transposed: bool):
+        """these are written transposed"""
+        if transposed:
+            obj = obj.T
+        return obj
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        # validate the version
+        self.validate_version(where)
+
+        # infer the data kind
+        if not self.infer_axes():
+            return None
+
+        result = self._read_axes(where=where, start=start, stop=stop)
+
+        info = (
+            self.info.get(self.non_index_axes[0][0], {})
+            if len(self.non_index_axes)
+            else {}
+        )
+
+        inds = [i for i, ax in enumerate(self.axes) if ax is self.index_axes[0]]
+        assert len(inds) == 1
+        ind = inds[0]
+
+        index = result[ind][0]
+
+        frames = []
+        for i, a in enumerate(self.axes):
+            if a not in self.values_axes:
+                continue
+            index_vals, cvalues = result[i]
+
+            # we could have a multi-index constructor here
+            # ensure_index doesn't recognized our list-of-tuples here
+            if info.get("type") != "MultiIndex":
+                cols = Index(index_vals)
+            else:
+                cols = MultiIndex.from_tuples(index_vals)
+
+            names = info.get("names")
+            if names is not None:
+                cols.set_names(names, inplace=True)
+
+            if self.is_transposed:
+                values = cvalues
+                index_ = cols
+                cols_ = Index(index, name=getattr(index, "name", None))
+            else:
+                values = cvalues.T
+                index_ = Index(index, name=getattr(index, "name", None))
+                cols_ = cols
+
+            # if we have a DataIndexableCol, its shape will only be 1 dim
+            if values.ndim == 1 and isinstance(values, np.ndarray):
+                values = values.reshape((1, values.shape[0]))
+
+            if isinstance(values, np.ndarray):
+                try:
+                    df = DataFrame(values.T, columns=cols_, index=index_, copy=False)
+                except UnicodeEncodeError as err:
+                    if (
+                        self.errors == "surrogatepass"
+                        and get_option("future.infer_string")
+                        and str(err).endswith("surrogates not allowed")
+                        and HAS_PYARROW
+                    ):
+                        df = DataFrame(
+                            values.T,
+                            columns=cols_,
+                            index=index_,
+                            copy=False,
+                            dtype=StringDtype(storage="python", na_value=np.nan),
+                        )
+                    else:
+                        raise
+            elif isinstance(values, Index):
+                df = DataFrame(values, columns=cols_, index=index_)
+            else:
+                # Categorical
+                df = DataFrame._from_arrays([values], columns=cols_, index=index_)
+            if not (using_string_dtype() and values.dtype.kind == "O"):
+                assert (df.dtypes == values.dtype).all(), (df.dtypes, values.dtype)
+
+            # If str / string dtype is stored in meta, use that.
+            for column in cols_:
+                dtype = getattr(self.table.attrs, f"{column}_meta", None)
+                if dtype in ["str", "string"]:
+                    df[column] = df[column].astype(dtype)
+            frames.append(df)
+
+        if len(frames) == 1:
+            df = frames[0]
+        else:
+            df = concat(frames, axis=1)
+
+        selection = Selection(self, where=where, start=start, stop=stop)
+        # apply the selection filters & axis orderings
+        df = self.process_axes(df, selection=selection, columns=columns)
+        return df
+
+
+class AppendableSeriesTable(AppendableFrameTable):
+    """support the new appendable table formats"""
+
+    pandas_kind = "series_table"
+    table_type = "appendable_series"
+    ndim = 2
+    obj_type = Series
+
+    @property
+    def is_transposed(self) -> bool:
+        return False
+
+    @classmethod
+    def get_object(cls, obj, transposed: bool):
+        return obj
+
+    # error: Signature of "write" incompatible with supertype "Fixed"
+    def write(self, obj, data_columns=None, **kwargs) -> None:  # type: ignore[override]
+        """we are going to write this as a frame table"""
+        if not isinstance(obj, DataFrame):
+            name = obj.name or "values"
+            obj = obj.to_frame(name)
+        super().write(obj=obj, data_columns=obj.columns.tolist(), **kwargs)
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> Series:
+        is_multi_index = self.is_multi_index
+        if columns is not None and is_multi_index:
+            assert isinstance(self.levels, list)  # needed for mypy
+            for n in self.levels:
+                if n not in columns:
+                    columns.insert(0, n)
+        s = super().read(where=where, columns=columns, start=start, stop=stop)
+        if is_multi_index:
+            s.set_index(self.levels, inplace=True)
+
+        s = s.iloc[:, 0]
+
+        # remove the default name
+        if s.name == "values":
+            s.name = None
+        return s
+
+
+class AppendableMultiSeriesTable(AppendableSeriesTable):
+    """support the new appendable table formats"""
+
+    pandas_kind = "series_table"
+    table_type = "appendable_multiseries"
+
+    #  error: Signature of "write" incompatible with supertype "Fixed"
+    def write(self, obj, **kwargs) -> None:  # type: ignore[override]
+        """we are going to write this as a frame table"""
+        name = obj.name or "values"
+        newobj, self.levels = self.validate_multiindex(obj)
+        assert isinstance(self.levels, list)  # for mypy
+        cols = list(self.levels)
+        cols.append(name)
+        newobj.columns = Index(cols)
+        super().write(obj=newobj, **kwargs)
+
+
+class GenericTable(AppendableFrameTable):
+    """a table that read/writes the generic pytables table format"""
+
+    pandas_kind = "frame_table"
+    table_type = "generic_table"
+    ndim = 2
+    obj_type = DataFrame
+    levels: list[Hashable]
+
+    @property
+    def pandas_type(self) -> str:
+        return self.pandas_kind
+
+    @property
+    def storable(self):
+        return getattr(self.group, "table", None) or self.group
+
+    def get_attrs(self) -> None:
+        """retrieve our attributes"""
+        self.non_index_axes = []
+        self.nan_rep = None
+        self.levels = []
+
+        self.index_axes = [a for a in self.indexables if a.is_an_indexable]
+        self.values_axes = [a for a in self.indexables if not a.is_an_indexable]
+        self.data_columns = [a.name for a in self.values_axes]
+
+    @cache_readonly
+    def indexables(self):
+        """create the indexables from the table description"""
+        d = self.description
+
+        # TODO: can we get a typ for this?  AFAICT it is the only place
+        #  where we aren't passing one
+        # the index columns is just a simple index
+        md = self.read_metadata("index")
+        meta = "category" if md is not None else None
+        index_col = GenericIndexCol(
+            name="index", axis=0, table=self.table, meta=meta, metadata=md
+        )
+
+        _indexables: list[GenericIndexCol | GenericDataIndexableCol] = [index_col]
+
+        for i, n in enumerate(d._v_names):
+            assert isinstance(n, str)
+
+            atom = getattr(d, n)
+            md = self.read_metadata(n)
+            meta = "category" if md is not None else None
+            dc = GenericDataIndexableCol(
+                name=n,
+                pos=i,
+                values=[n],
+                typ=atom,
+                table=self.table,
+                meta=meta,
+                metadata=md,
+            )
+            _indexables.append(dc)
+
+        return _indexables
+
+    # error: Signature of "write" incompatible with supertype "AppendableTable"
+    def write(self, **kwargs) -> None:  # type: ignore[override]
+        raise NotImplementedError("cannot write on an generic table")
+
+
+class AppendableMultiFrameTable(AppendableFrameTable):
+    """a frame with a multi-index"""
+
+    table_type = "appendable_multiframe"
+    obj_type = DataFrame
+    ndim = 2
+    _re_levels = re.compile(r"^level_\d+$")
+
+    @property
+    def table_type_short(self) -> str:
+        return "appendable_multi"
+
+    # error: Signature of "write" incompatible with supertype "Fixed"
+    def write(self, obj, data_columns=None, **kwargs) -> None:  # type: ignore[override]
+        if data_columns is None:
+            data_columns = []
+        elif data_columns is True:
+            data_columns = obj.columns.tolist()
+        obj, self.levels = self.validate_multiindex(obj)
+        assert isinstance(self.levels, list)  # for mypy
+        for n in self.levels:
+            if n not in data_columns:
+                data_columns.insert(0, n)
+        super().write(obj=obj, data_columns=data_columns, **kwargs)
+
+    def read(
+        self,
+        where=None,
+        columns=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ):
+        df = super().read(where=where, columns=columns, start=start, stop=stop)
+        df = df.set_index(self.levels)
+
+        # remove names for 'level_%d'
+        df.index = df.index.set_names(
+            [None if self._re_levels.search(name) else name for name in df.index.names]
+        )
+
+        return df
+
+
+def _reindex_axis(
+    obj: DataFrame, axis: AxisInt, labels: Index, other=None
+) -> DataFrame:
+    ax = obj._get_axis(axis)
+    labels = ensure_index(labels)
+
+    # try not to reindex even if other is provided
+    # if it equals our current index
+    if other is not None:
+        other = ensure_index(other)
+    if (other is None or labels.equals(other)) and labels.equals(ax):
+        return obj
+
+    labels = ensure_index(labels.unique())
+    if other is not None:
+        labels = ensure_index(other.unique()).intersection(labels, sort=False)
+    if not labels.equals(ax):
+        slicer: list[slice | Index] = [slice(None, None)] * obj.ndim
+        slicer[axis] = labels
+        obj = obj.loc[tuple(slicer)]
+    return obj
+
+
+# tz to/from coercion
+
+
+def _get_tz(tz: tzinfo) -> str | tzinfo:
+    """for a tz-aware type, return an encoded zone"""
+    zone = timezones.get_timezone(tz)
+    return zone
+
+
+@overload
+def _set_tz(
+    values: np.ndarray | Index, tz: str | tzinfo, coerce: bool = False
+) -> DatetimeIndex:
+    ...
+
+
+@overload
+def _set_tz(values: np.ndarray | Index, tz: None, coerce: bool = False) -> np.ndarray:
+    ...
+
+
+def _set_tz(
+    values: np.ndarray | Index, tz: str | tzinfo | None, coerce: bool = False
+) -> np.ndarray | DatetimeIndex:
+    """
+    coerce the values to a DatetimeIndex if tz is set
+    preserve the input shape if possible
+
+    Parameters
+    ----------
+    values : ndarray or Index
+    tz : str or tzinfo
+    coerce : if we do not have a passed timezone, coerce to M8[ns] ndarray
+    """
+    if isinstance(values, DatetimeIndex):
+        # If values is tzaware, the tz gets dropped in the values.ravel()
+        #  call below (which returns an ndarray).  So we are only non-lossy
+        #  if `tz` matches `values.tz`.
+        assert values.tz is None or values.tz == tz
+        if values.tz is not None:
+            return values
+
+    if tz is not None:
+        if isinstance(values, DatetimeIndex):
+            name = values.name
+        else:
+            name = None
+            values = values.ravel()
+
+        tz = _ensure_decoded(tz)
+        values = DatetimeIndex(values, name=name)
+        values = values.tz_localize("UTC").tz_convert(tz)
+    elif coerce:
+        values = np.asarray(values, dtype="M8[ns]")
+
+    # error: Incompatible return value type (got "Union[ndarray, Index]",
+    # expected "Union[ndarray, DatetimeIndex]")
+    return values  # type: ignore[return-value]
+
+
+def _convert_index(name: str, index: Index, encoding: str, errors: str) -> IndexCol:
+    assert isinstance(name, str)
+
+    index_name = index.name
+    # error: Argument 1 to "_get_data_and_dtype_name" has incompatible type "Index";
+    # expected "Union[ExtensionArray, ndarray]"
+    converted, dtype_name = _get_data_and_dtype_name(index)  # type: ignore[arg-type]
+    kind = _dtype_to_kind(dtype_name)
+    atom = DataIndexableCol._get_atom(converted)
+
+    if (
+        lib.is_np_dtype(index.dtype, "iu")
+        or needs_i8_conversion(index.dtype)
+        or is_bool_dtype(index.dtype)
+    ):
+        # Includes Index, RangeIndex, DatetimeIndex, TimedeltaIndex, PeriodIndex,
+        #  in which case "kind" is "integer", "integer", "datetime64",
+        #  "timedelta64", and "integer", respectively.
+        return IndexCol(
+            name,
+            values=converted,
+            kind=kind,
+            typ=atom,
+            freq=getattr(index, "freq", None),
+            tz=getattr(index, "tz", None),
+            index_name=index_name,
+        )
+
+    if isinstance(index, MultiIndex):
+        raise TypeError("MultiIndex not supported here!")
+
+    inferred_type = lib.infer_dtype(index, skipna=False)
+    # we won't get inferred_type of "datetime64" or "timedelta64" as these
+    #  would go through the DatetimeIndex/TimedeltaIndex paths above
+
+    values = np.asarray(index)
+
+    if inferred_type == "date":
+        converted = np.asarray([v.toordinal() for v in values], dtype=np.int32)
+        return IndexCol(
+            name, converted, "date", _tables().Time32Col(), index_name=index_name
+        )
+    elif inferred_type == "string":
+        converted = _convert_string_array(values, encoding, errors)
+        itemsize = converted.dtype.itemsize
+        return IndexCol(
+            name,
+            converted,
+            "string",
+            _tables().StringCol(itemsize),
+            index_name=index_name,
+        )
+
+    elif inferred_type in ["integer", "floating"]:
+        return IndexCol(
+            name, values=converted, kind=kind, typ=atom, index_name=index_name
+        )
+    else:
+        assert isinstance(converted, np.ndarray) and converted.dtype == object
+        assert kind == "object", kind
+        atom = _tables().ObjectAtom()
+        return IndexCol(name, converted, kind, atom, index_name=index_name)
+
+
+def _unconvert_index(data, kind: str, encoding: str, errors: str) -> np.ndarray | Index:
+    index: Index | np.ndarray
+
+    if kind.startswith("datetime64"):
+        if kind == "datetime64":
+            # created before we stored resolution information
+            index = DatetimeIndex(data)
+        else:
+            index = DatetimeIndex(data.view(kind))
+    elif kind == "timedelta64":
+        index = TimedeltaIndex(data)
+    elif kind == "date":
+        try:
+            index = np.asarray([date.fromordinal(v) for v in data], dtype=object)
+        except ValueError:
+            index = np.asarray([date.fromtimestamp(v) for v in data], dtype=object)
+    elif kind in ("integer", "float", "bool"):
+        index = np.asarray(data)
+    elif kind in ("string"):
+        index = _unconvert_string_array(
+            data, nan_rep=None, encoding=encoding, errors=errors
+        )
+    elif kind == "object":
+        index = np.asarray(data[0])
+    else:  # pragma: no cover
+        raise ValueError(f"unrecognized index type {kind}")
+    return index
+
+
+def _maybe_convert_for_string_atom(
+    name: str,
+    bvalues: ArrayLike,
+    existing_col,
+    min_itemsize,
+    nan_rep,
+    encoding,
+    errors,
+    columns: list[str],
+):
+    if isinstance(bvalues.dtype, StringDtype):
+        # "ndarray[Any, Any]" has no attribute "to_numpy"
+        bvalues = bvalues.to_numpy()  # type: ignore[union-attr]
+    if bvalues.dtype != object:
+        return bvalues
+
+    bvalues = cast(np.ndarray, bvalues)
+
+    dtype_name = bvalues.dtype.name
+    inferred_type = lib.infer_dtype(bvalues, skipna=False)
+
+    if inferred_type == "date":
+        raise TypeError("[date] is not implemented as a table column")
+    if inferred_type == "datetime":
+        # after GH#8260
+        # this only would be hit for a multi-timezone dtype which is an error
+        raise TypeError(
+            "too many timezones in this block, create separate data columns"
+        )
+
+    if not (inferred_type == "string" or dtype_name == "object"):
+        return bvalues
+
+    mask = isna(bvalues)
+    data = bvalues.copy()
+    data[mask] = nan_rep
+
+    if existing_col and mask.any() and len(nan_rep) > existing_col.itemsize:
+        raise ValueError("NaN representation is too large for existing column size")
+
+    # see if we have a valid string type
+    inferred_type = lib.infer_dtype(data, skipna=False)
+    if inferred_type != "string":
+        # we cannot serialize this data, so report an exception on a column
+        # by column basis
+
+        # expected behaviour:
+        # search block for a non-string object column by column
+        for i in range(data.shape[0]):
+            col = data[i]
+            inferred_type = lib.infer_dtype(col, skipna=False)
+            if inferred_type != "string":
+                error_column_label = columns[i] if len(columns) > i else f"No.{i}"
+                raise TypeError(
+                    f"Cannot serialize the column [{error_column_label}]\n"
+                    f"because its data contents are not [string] but "
+                    f"[{inferred_type}] object dtype"
+                )
+
+    # itemsize is the maximum length of a string (along any dimension)
+
+    data_converted = _convert_string_array(data, encoding, errors).reshape(data.shape)
+    itemsize = data_converted.itemsize
+
+    # specified min_itemsize?
+    if isinstance(min_itemsize, dict):
+        min_itemsize = int(min_itemsize.get(name) or min_itemsize.get("values") or 0)
+    itemsize = max(min_itemsize or 0, itemsize)
+
+    # check for column in the values conflicts
+    if existing_col is not None:
+        eci = existing_col.validate_col(itemsize)
+        if eci is not None and eci > itemsize:
+            itemsize = eci
+
+    data_converted = data_converted.astype(f"|S{itemsize}", copy=False)
+    return data_converted
+
+
+def _convert_string_array(data: np.ndarray, encoding: str, errors: str) -> np.ndarray:
+    """
+    Take a string-like that is object dtype and coerce to a fixed size string type.
+
+    Parameters
+    ----------
+    data : np.ndarray[object]
+    encoding : str
+    errors : str
+        Handler for encoding errors.
+
+    Returns
+    -------
+    np.ndarray[fixed-length-string]
+    """
+    # encode if needed
+    if len(data):
+        data = (
+            Series(data.ravel(), copy=False, dtype="object")
+            .str.encode(encoding, errors)
+            ._values.reshape(data.shape)
+        )
+
+    # create the sized dtype
+    ensured = ensure_object(data.ravel())
+    itemsize = max(1, libwriters.max_len_string_array(ensured))
+
+    data = np.asarray(data, dtype=f"S{itemsize}")
+    return data
+
+
+def _unconvert_string_array(
+    data: np.ndarray, nan_rep, encoding: str, errors: str
+) -> np.ndarray:
+    """
+    Inverse of _convert_string_array.
+
+    Parameters
+    ----------
+    data : np.ndarray[fixed-length-string]
+    nan_rep : the storage repr of NaN
+    encoding : str
+    errors : str
+        Handler for encoding errors.
+
+    Returns
+    -------
+    np.ndarray[object]
+        Decoded data.
+    """
+    shape = data.shape
+    data = np.asarray(data.ravel(), dtype=object)
+
+    if len(data):
+        itemsize = libwriters.max_len_string_array(ensure_object(data))
+        dtype = f"U{itemsize}"
+
+        if isinstance(data[0], bytes):
+            ser = Series(data, copy=False).str.decode(
+                encoding, errors=errors, dtype="object"
+            )
+            data = ser.to_numpy()
+            data.flags.writeable = True
+        else:
+            data = data.astype(dtype, copy=False).astype(object, copy=False)
+
+    if nan_rep is None:
+        nan_rep = "nan"
+
+    libwriters.string_array_replace_from_nan_rep(data, nan_rep)
+    return data.reshape(shape)
+
+
+def _maybe_convert(values: np.ndarray, val_kind: str, encoding: str, errors: str):
+    assert isinstance(val_kind, str), type(val_kind)
+    if _need_convert(val_kind):
+        conv = _get_converter(val_kind, encoding, errors)
+        values = conv(values)
+    return values
+
+
+def _get_converter(kind: str, encoding: str, errors: str):
+    if kind == "datetime64":
+        return lambda x: np.asarray(x, dtype="M8[ns]")
+    elif "datetime64" in kind:
+        return lambda x: np.asarray(x, dtype=kind)
+    elif kind == "string":
+        return lambda x: _unconvert_string_array(
+            x, nan_rep=None, encoding=encoding, errors=errors
+        )
+    else:  # pragma: no cover
+        raise ValueError(f"invalid kind {kind}")
+
+
+def _need_convert(kind: str) -> bool:
+    if kind in ("datetime64", "string") or "datetime64" in kind:
+        return True
+    return False
+
+
+def _maybe_adjust_name(name: str, version: Sequence[int]) -> str:
+    """
+    Prior to 0.10.1, we named values blocks like: values_block_0 an the
+    name values_0, adjust the given name if necessary.
+
+    Parameters
+    ----------
+    name : str
+    version : Tuple[int, int, int]
+
+    Returns
+    -------
+    str
+    """
+    if isinstance(version, str) or len(version) < 3:
+        raise ValueError("Version is incorrect, expected sequence of 3 integers.")
+
+    if version[0] == 0 and version[1] <= 10 and version[2] == 0:
+        m = re.search(r"values_block_(\d+)", name)
+        if m:
+            grp = m.groups()[0]
+            name = f"values_{grp}"
+    return name
+
+
+def _dtype_to_kind(dtype_str: str) -> str:
+    """
+    Find the "kind" string describing the given dtype name.
+    """
+    dtype_str = _ensure_decoded(dtype_str)
+
+    if dtype_str.startswith(("string", "bytes")):
+        kind = "string"
+    elif dtype_str.startswith("float"):
+        kind = "float"
+    elif dtype_str.startswith("complex"):
+        kind = "complex"
+    elif dtype_str.startswith(("int", "uint")):
+        kind = "integer"
+    elif dtype_str.startswith("datetime64"):
+        kind = dtype_str
+    elif dtype_str.startswith("timedelta"):
+        kind = "timedelta64"
+    elif dtype_str.startswith("bool"):
+        kind = "bool"
+    elif dtype_str.startswith("category"):
+        kind = "category"
+    elif dtype_str.startswith("period"):
+        # We store the `freq` attr so we can restore from integers
+        kind = "integer"
+    elif dtype_str == "object":
+        kind = "object"
+    elif dtype_str == "str":
+        kind = "str"
+    else:
+        raise ValueError(f"cannot interpret dtype of [{dtype_str}]")
+
+    return kind
+
+
+def _get_data_and_dtype_name(data: ArrayLike):
+    """
+    Convert the passed data into a storable form and a dtype string.
+    """
+    if isinstance(data, Categorical):
+        data = data.codes
+
+    if isinstance(data.dtype, DatetimeTZDtype):
+        # For datetime64tz we need to drop the TZ in tests TODO: why?
+        dtype_name = f"datetime64[{data.dtype.unit}]"
+    else:
+        dtype_name = data.dtype.name
+
+    if data.dtype.kind in "mM":
+        data = np.asarray(data.view("i8"))
+        # TODO: we used to reshape for the dt64tz case, but no longer
+        #  doing that doesn't seem to break anything.  why?
+
+    elif isinstance(data, PeriodIndex):
+        data = data.asi8
+
+    data = np.asarray(data)
+    return data, dtype_name
+
+
+class Selection:
+    """
+    Carries out a selection operation on a tables.Table object.
+
+    Parameters
+    ----------
+    table : a Table object
+    where : list of Terms (or convertible to)
+    start, stop: indices to start and/or stop selection
+
+    """
+
+    def __init__(
+        self,
+        table: Table,
+        where=None,
+        start: int | None = None,
+        stop: int | None = None,
+    ) -> None:
+        self.table = table
+        self.where = where
+        self.start = start
+        self.stop = stop
+        self.condition = None
+        self.filter = None
+        self.terms = None
+        self.coordinates = None
+
+        if is_list_like(where):
+            # see if we have a passed coordinate like
+            with suppress(ValueError):
+                inferred = lib.infer_dtype(where, skipna=False)
+                if inferred in ("integer", "boolean"):
+                    where = np.asarray(where)
+                    if where.dtype == np.bool_:
+                        start, stop = self.start, self.stop
+                        if start is None:
+                            start = 0
+                        if stop is None:
+                            stop = self.table.nrows
+                        self.coordinates = np.arange(start, stop)[where]
+                    elif issubclass(where.dtype.type, np.integer):
+                        if (self.start is not None and (where < self.start).any()) or (
+                            self.stop is not None and (where >= self.stop).any()
+                        ):
+                            raise ValueError(
+                                "where must have index locations >= start and < stop"
+                            )
+                        self.coordinates = where
+
+        if self.coordinates is None:
+            self.terms = self.generate(where)
+
+            # create the numexpr & the filter
+            if self.terms is not None:
+                self.condition, self.filter = self.terms.evaluate()
+
+    def generate(self, where):
+        """where can be a : dict,list,tuple,string"""
+        if where is None:
+            return None
+
+        q = self.table.queryables()
+        try:
+            return PyTablesExpr(where, queryables=q, encoding=self.table.encoding)
+        except NameError as err:
+            # raise a nice message, suggesting that the user should use
+            # data_columns
+            qkeys = ",".join(q.keys())
+            msg = dedent(
+                f"""\
+                The passed where expression: {where}
+                            contains an invalid variable reference
+                            all of the variable references must be a reference to
+                            an axis (e.g. 'index' or 'columns'), or a data_column
+                            The currently defined references are: {qkeys}
+                """
+            )
+            raise ValueError(msg) from err
+
+    def select(self):
+        """
+        generate the selection
+        """
+        if self.condition is not None:
+            return self.table.table.read_where(
+                self.condition.format(), start=self.start, stop=self.stop
+            )
+        elif self.coordinates is not None:
+            return self.table.table.read_coordinates(self.coordinates)
+        return self.table.table.read(start=self.start, stop=self.stop)
+
+    def select_coords(self):
+        """
+        generate the selection
+        """
+        start, stop = self.start, self.stop
+        nrows = self.table.nrows
+        if start is None:
+            start = 0
+        elif start < 0:
+            start += nrows
+        if stop is None:
+            stop = nrows
+        elif stop < 0:
+            stop += nrows
+
+        if self.condition is not None:
+            return self.table.table.get_where_list(
+                self.condition.format(), start=start, stop=stop, sort=True
+            )
+        elif self.coordinates is not None:
+            return self.coordinates
+
+        return np.arange(start, stop)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sas/__init__.py b/.venv/lib/python3.13/site-packages/pandas/io/sas/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..317730745b6e3a0278a48b7bb810cf43e718e787
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sas/__init__.py
@@ -0,0 +1,3 @@
+from pandas.io.sas.sasreader import read_sas
+
+__all__ = ["read_sas"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sas/sas7bdat.py b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas7bdat.py
new file mode 100644
index 0000000000000000000000000000000000000000..1d424425cd927784ea2f16c41f635d71143995f9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas7bdat.py
@@ -0,0 +1,762 @@
+"""
+Read SAS7BDAT files
+
+Based on code written by Jared Hobbs:
+  https://bitbucket.org/jaredhobbs/sas7bdat
+
+See also:
+  https://github.com/BioStatMatt/sas7bdat
+
+Partial documentation of the file format:
+  https://cran.r-project.org/package=sas7bdat/vignettes/sas7bdat.pdf
+
+Reference for binary data compression:
+  http://collaboration.cmc.ec.gc.ca/science/rpn/biblio/ddj/Website/articles/CUJ/1992/9210/ross/ross.htm
+"""
+from __future__ import annotations
+
+from collections import abc
+from datetime import (
+    datetime,
+    timedelta,
+)
+import sys
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas._config import get_option
+
+from pandas._libs.byteswap import (
+    read_double_with_byteswap,
+    read_float_with_byteswap,
+    read_uint16_with_byteswap,
+    read_uint32_with_byteswap,
+    read_uint64_with_byteswap,
+)
+from pandas._libs.sas import (
+    Parser,
+    get_subheader_index,
+)
+from pandas._libs.tslibs.conversion import cast_from_unit_vectorized
+from pandas.errors import EmptyDataError
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    Timestamp,
+    isna,
+)
+
+from pandas.io.common import get_handle
+import pandas.io.sas.sas_constants as const
+from pandas.io.sas.sasreader import ReaderBase
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        ReadBuffer,
+    )
+
+
+_unix_origin = Timestamp("1970-01-01")
+_sas_origin = Timestamp("1960-01-01")
+
+
+def _parse_datetime(sas_datetime: float, unit: str):
+    if isna(sas_datetime):
+        return pd.NaT
+
+    if unit == "s":
+        return datetime(1960, 1, 1) + timedelta(seconds=sas_datetime)
+
+    elif unit == "d":
+        return datetime(1960, 1, 1) + timedelta(days=sas_datetime)
+
+    else:
+        raise ValueError("unit must be 'd' or 's'")
+
+
+def _convert_datetimes(sas_datetimes: pd.Series, unit: str) -> pd.Series:
+    """
+    Convert to Timestamp if possible, otherwise to datetime.datetime.
+    SAS float64 lacks precision for more than ms resolution so the fit
+    to datetime.datetime is ok.
+
+    Parameters
+    ----------
+    sas_datetimes : {Series, Sequence[float]}
+       Dates or datetimes in SAS
+    unit : {'d', 's'}
+       "d" if the floats represent dates, "s" for datetimes
+
+    Returns
+    -------
+    Series
+       Series of datetime64 dtype or datetime.datetime.
+    """
+    td = (_sas_origin - _unix_origin).as_unit("s")
+    if unit == "s":
+        millis = cast_from_unit_vectorized(
+            sas_datetimes._values, unit="s", out_unit="ms"
+        )
+        dt64ms = millis.view("M8[ms]") + td
+        return pd.Series(dt64ms, index=sas_datetimes.index, copy=False)
+    else:
+        vals = np.array(sas_datetimes, dtype="M8[D]") + td
+        return pd.Series(vals, dtype="M8[s]", index=sas_datetimes.index, copy=False)
+
+
+class _Column:
+    col_id: int
+    name: str | bytes
+    label: str | bytes
+    format: str | bytes
+    ctype: bytes
+    length: int
+
+    def __init__(
+        self,
+        col_id: int,
+        # These can be bytes when convert_header_text is False
+        name: str | bytes,
+        label: str | bytes,
+        format: str | bytes,
+        ctype: bytes,
+        length: int,
+    ) -> None:
+        self.col_id = col_id
+        self.name = name
+        self.label = label
+        self.format = format
+        self.ctype = ctype
+        self.length = length
+
+
+# SAS7BDAT represents a SAS data file in SAS7BDAT format.
+class SAS7BDATReader(ReaderBase, abc.Iterator):
+    """
+    Read SAS files in SAS7BDAT format.
+
+    Parameters
+    ----------
+    path_or_buf : path name or buffer
+        Name of SAS file or file-like object pointing to SAS file
+        contents.
+    index : column identifier, defaults to None
+        Column to use as index.
+    convert_dates : bool, defaults to True
+        Attempt to convert dates to Pandas datetime values.  Note that
+        some rarely used SAS date formats may be unsupported.
+    blank_missing : bool, defaults to True
+        Convert empty strings to missing values (SAS uses blanks to
+        indicate missing character variables).
+    chunksize : int, defaults to None
+        Return SAS7BDATReader object for iterations, returns chunks
+        with given number of lines.
+    encoding : str, 'infer', defaults to None
+        String encoding acc. to Python standard encodings,
+        encoding='infer' tries to detect the encoding from the file header,
+        encoding=None will leave the data in binary format.
+    convert_text : bool, defaults to True
+        If False, text variables are left as raw bytes.
+    convert_header_text : bool, defaults to True
+        If False, header text, including column names, are left as raw
+        bytes.
+    """
+
+    _int_length: int
+    _cached_page: bytes | None
+
+    def __init__(
+        self,
+        path_or_buf: FilePath | ReadBuffer[bytes],
+        index=None,
+        convert_dates: bool = True,
+        blank_missing: bool = True,
+        chunksize: int | None = None,
+        encoding: str | None = None,
+        convert_text: bool = True,
+        convert_header_text: bool = True,
+        compression: CompressionOptions = "infer",
+    ) -> None:
+        self.index = index
+        self.convert_dates = convert_dates
+        self.blank_missing = blank_missing
+        self.chunksize = chunksize
+        self.encoding = encoding
+        self.convert_text = convert_text
+        self.convert_header_text = convert_header_text
+
+        self.default_encoding = "latin-1"
+        self.compression = b""
+        self.column_names_raw: list[bytes] = []
+        self.column_names: list[str | bytes] = []
+        self.column_formats: list[str | bytes] = []
+        self.columns: list[_Column] = []
+
+        self._current_page_data_subheader_pointers: list[tuple[int, int]] = []
+        self._cached_page = None
+        self._column_data_lengths: list[int] = []
+        self._column_data_offsets: list[int] = []
+        self._column_types: list[bytes] = []
+
+        self._current_row_in_file_index = 0
+        self._current_row_on_page_index = 0
+        self._current_row_in_file_index = 0
+
+        self.handles = get_handle(
+            path_or_buf, "rb", is_text=False, compression=compression
+        )
+
+        self._path_or_buf = self.handles.handle
+
+        # Same order as const.SASIndex
+        self._subheader_processors = [
+            self._process_rowsize_subheader,
+            self._process_columnsize_subheader,
+            self._process_subheader_counts,
+            self._process_columntext_subheader,
+            self._process_columnname_subheader,
+            self._process_columnattributes_subheader,
+            self._process_format_subheader,
+            self._process_columnlist_subheader,
+            None,  # Data
+        ]
+
+        try:
+            self._get_properties()
+            self._parse_metadata()
+        except Exception:
+            self.close()
+            raise
+
+    def column_data_lengths(self) -> np.ndarray:
+        """Return a numpy int64 array of the column data lengths"""
+        return np.asarray(self._column_data_lengths, dtype=np.int64)
+
+    def column_data_offsets(self) -> np.ndarray:
+        """Return a numpy int64 array of the column offsets"""
+        return np.asarray(self._column_data_offsets, dtype=np.int64)
+
+    def column_types(self) -> np.ndarray:
+        """
+        Returns a numpy character array of the column types:
+           s (string) or d (double)
+        """
+        return np.asarray(self._column_types, dtype=np.dtype("S1"))
+
+    def close(self) -> None:
+        self.handles.close()
+
+    def _get_properties(self) -> None:
+        # Check magic number
+        self._path_or_buf.seek(0)
+        self._cached_page = self._path_or_buf.read(288)
+        if self._cached_page[0 : len(const.magic)] != const.magic:
+            raise ValueError("magic number mismatch (not a SAS file?)")
+
+        # Get alignment information
+        buf = self._read_bytes(const.align_1_offset, const.align_1_length)
+        if buf == const.u64_byte_checker_value:
+            self.U64 = True
+            self._int_length = 8
+            self._page_bit_offset = const.page_bit_offset_x64
+            self._subheader_pointer_length = const.subheader_pointer_length_x64
+        else:
+            self.U64 = False
+            self._page_bit_offset = const.page_bit_offset_x86
+            self._subheader_pointer_length = const.subheader_pointer_length_x86
+            self._int_length = 4
+        buf = self._read_bytes(const.align_2_offset, const.align_2_length)
+        if buf == const.align_1_checker_value:
+            align1 = const.align_2_value
+        else:
+            align1 = 0
+
+        # Get endianness information
+        buf = self._read_bytes(const.endianness_offset, const.endianness_length)
+        if buf == b"\x01":
+            self.byte_order = "<"
+            self.need_byteswap = sys.byteorder == "big"
+        else:
+            self.byte_order = ">"
+            self.need_byteswap = sys.byteorder == "little"
+
+        # Get encoding information
+        buf = self._read_bytes(const.encoding_offset, const.encoding_length)[0]
+        if buf in const.encoding_names:
+            self.inferred_encoding = const.encoding_names[buf]
+            if self.encoding == "infer":
+                self.encoding = self.inferred_encoding
+        else:
+            self.inferred_encoding = f"unknown (code={buf})"
+
+        # Timestamp is epoch 01/01/1960
+        epoch = datetime(1960, 1, 1)
+        x = self._read_float(
+            const.date_created_offset + align1, const.date_created_length
+        )
+        self.date_created = epoch + pd.to_timedelta(x, unit="s")
+        x = self._read_float(
+            const.date_modified_offset + align1, const.date_modified_length
+        )
+        self.date_modified = epoch + pd.to_timedelta(x, unit="s")
+
+        self.header_length = self._read_uint(
+            const.header_size_offset + align1, const.header_size_length
+        )
+
+        # Read the rest of the header into cached_page.
+        buf = self._path_or_buf.read(self.header_length - 288)
+        self._cached_page += buf
+        # error: Argument 1 to "len" has incompatible type "Optional[bytes]";
+        #  expected "Sized"
+        if len(self._cached_page) != self.header_length:  # type: ignore[arg-type]
+            raise ValueError("The SAS7BDAT file appears to be truncated.")
+
+        self._page_length = self._read_uint(
+            const.page_size_offset + align1, const.page_size_length
+        )
+
+    def __next__(self) -> DataFrame:
+        da = self.read(nrows=self.chunksize or 1)
+        if da.empty:
+            self.close()
+            raise StopIteration
+        return da
+
+    # Read a single float of the given width (4 or 8).
+    def _read_float(self, offset: int, width: int):
+        assert self._cached_page is not None
+        if width == 4:
+            return read_float_with_byteswap(
+                self._cached_page, offset, self.need_byteswap
+            )
+        elif width == 8:
+            return read_double_with_byteswap(
+                self._cached_page, offset, self.need_byteswap
+            )
+        else:
+            self.close()
+            raise ValueError("invalid float width")
+
+    # Read a single unsigned integer of the given width (1, 2, 4 or 8).
+    def _read_uint(self, offset: int, width: int) -> int:
+        assert self._cached_page is not None
+        if width == 1:
+            return self._read_bytes(offset, 1)[0]
+        elif width == 2:
+            return read_uint16_with_byteswap(
+                self._cached_page, offset, self.need_byteswap
+            )
+        elif width == 4:
+            return read_uint32_with_byteswap(
+                self._cached_page, offset, self.need_byteswap
+            )
+        elif width == 8:
+            return read_uint64_with_byteswap(
+                self._cached_page, offset, self.need_byteswap
+            )
+        else:
+            self.close()
+            raise ValueError("invalid int width")
+
+    def _read_bytes(self, offset: int, length: int):
+        assert self._cached_page is not None
+        if offset + length > len(self._cached_page):
+            self.close()
+            raise ValueError("The cached page is too small.")
+        return self._cached_page[offset : offset + length]
+
+    def _read_and_convert_header_text(self, offset: int, length: int) -> str | bytes:
+        return self._convert_header_text(
+            self._read_bytes(offset, length).rstrip(b"\x00 ")
+        )
+
+    def _parse_metadata(self) -> None:
+        done = False
+        while not done:
+            self._cached_page = self._path_or_buf.read(self._page_length)
+            if len(self._cached_page) <= 0:
+                break
+            if len(self._cached_page) != self._page_length:
+                raise ValueError("Failed to read a meta data page from the SAS file.")
+            done = self._process_page_meta()
+
+    def _process_page_meta(self) -> bool:
+        self._read_page_header()
+        pt = const.page_meta_types + [const.page_amd_type, const.page_mix_type]
+        if self._current_page_type in pt:
+            self._process_page_metadata()
+        is_data_page = self._current_page_type == const.page_data_type
+        is_mix_page = self._current_page_type == const.page_mix_type
+        return bool(
+            is_data_page
+            or is_mix_page
+            or self._current_page_data_subheader_pointers != []
+        )
+
+    def _read_page_header(self) -> None:
+        bit_offset = self._page_bit_offset
+        tx = const.page_type_offset + bit_offset
+        self._current_page_type = (
+            self._read_uint(tx, const.page_type_length) & const.page_type_mask2
+        )
+        tx = const.block_count_offset + bit_offset
+        self._current_page_block_count = self._read_uint(tx, const.block_count_length)
+        tx = const.subheader_count_offset + bit_offset
+        self._current_page_subheaders_count = self._read_uint(
+            tx, const.subheader_count_length
+        )
+
+    def _process_page_metadata(self) -> None:
+        bit_offset = self._page_bit_offset
+
+        for i in range(self._current_page_subheaders_count):
+            offset = const.subheader_pointers_offset + bit_offset
+            total_offset = offset + self._subheader_pointer_length * i
+
+            subheader_offset = self._read_uint(total_offset, self._int_length)
+            total_offset += self._int_length
+
+            subheader_length = self._read_uint(total_offset, self._int_length)
+            total_offset += self._int_length
+
+            subheader_compression = self._read_uint(total_offset, 1)
+            total_offset += 1
+
+            subheader_type = self._read_uint(total_offset, 1)
+
+            if (
+                subheader_length == 0
+                or subheader_compression == const.truncated_subheader_id
+            ):
+                continue
+
+            subheader_signature = self._read_bytes(subheader_offset, self._int_length)
+            subheader_index = get_subheader_index(subheader_signature)
+            subheader_processor = self._subheader_processors[subheader_index]
+
+            if subheader_processor is None:
+                f1 = subheader_compression in (const.compressed_subheader_id, 0)
+                f2 = subheader_type == const.compressed_subheader_type
+                if self.compression and f1 and f2:
+                    self._current_page_data_subheader_pointers.append(
+                        (subheader_offset, subheader_length)
+                    )
+                else:
+                    self.close()
+                    raise ValueError(
+                        f"Unknown subheader signature {subheader_signature}"
+                    )
+            else:
+                subheader_processor(subheader_offset, subheader_length)
+
+    def _process_rowsize_subheader(self, offset: int, length: int) -> None:
+        int_len = self._int_length
+        lcs_offset = offset
+        lcp_offset = offset
+        if self.U64:
+            lcs_offset += 682
+            lcp_offset += 706
+        else:
+            lcs_offset += 354
+            lcp_offset += 378
+
+        self.row_length = self._read_uint(
+            offset + const.row_length_offset_multiplier * int_len,
+            int_len,
+        )
+        self.row_count = self._read_uint(
+            offset + const.row_count_offset_multiplier * int_len,
+            int_len,
+        )
+        self.col_count_p1 = self._read_uint(
+            offset + const.col_count_p1_multiplier * int_len, int_len
+        )
+        self.col_count_p2 = self._read_uint(
+            offset + const.col_count_p2_multiplier * int_len, int_len
+        )
+        mx = const.row_count_on_mix_page_offset_multiplier * int_len
+        self._mix_page_row_count = self._read_uint(offset + mx, int_len)
+        self._lcs = self._read_uint(lcs_offset, 2)
+        self._lcp = self._read_uint(lcp_offset, 2)
+
+    def _process_columnsize_subheader(self, offset: int, length: int) -> None:
+        int_len = self._int_length
+        offset += int_len
+        self.column_count = self._read_uint(offset, int_len)
+        if self.col_count_p1 + self.col_count_p2 != self.column_count:
+            print(
+                f"Warning: column count mismatch ({self.col_count_p1} + "
+                f"{self.col_count_p2} != {self.column_count})\n"
+            )
+
+    # Unknown purpose
+    def _process_subheader_counts(self, offset: int, length: int) -> None:
+        pass
+
+    def _process_columntext_subheader(self, offset: int, length: int) -> None:
+        offset += self._int_length
+        text_block_size = self._read_uint(offset, const.text_block_size_length)
+
+        buf = self._read_bytes(offset, text_block_size)
+        cname_raw = buf[0:text_block_size].rstrip(b"\x00 ")
+        self.column_names_raw.append(cname_raw)
+
+        if len(self.column_names_raw) == 1:
+            compression_literal = b""
+            for cl in const.compression_literals:
+                if cl in cname_raw:
+                    compression_literal = cl
+            self.compression = compression_literal
+            offset -= self._int_length
+
+            offset1 = offset + 16
+            if self.U64:
+                offset1 += 4
+
+            buf = self._read_bytes(offset1, self._lcp)
+            compression_literal = buf.rstrip(b"\x00")
+            if compression_literal == b"":
+                self._lcs = 0
+                offset1 = offset + 32
+                if self.U64:
+                    offset1 += 4
+                buf = self._read_bytes(offset1, self._lcp)
+                self.creator_proc = buf[0 : self._lcp]
+            elif compression_literal == const.rle_compression:
+                offset1 = offset + 40
+                if self.U64:
+                    offset1 += 4
+                buf = self._read_bytes(offset1, self._lcp)
+                self.creator_proc = buf[0 : self._lcp]
+            elif self._lcs > 0:
+                self._lcp = 0
+                offset1 = offset + 16
+                if self.U64:
+                    offset1 += 4
+                buf = self._read_bytes(offset1, self._lcs)
+                self.creator_proc = buf[0 : self._lcp]
+            if hasattr(self, "creator_proc"):
+                self.creator_proc = self._convert_header_text(self.creator_proc)
+
+    def _process_columnname_subheader(self, offset: int, length: int) -> None:
+        int_len = self._int_length
+        offset += int_len
+        column_name_pointers_count = (length - 2 * int_len - 12) // 8
+        for i in range(column_name_pointers_count):
+            text_subheader = (
+                offset
+                + const.column_name_pointer_length * (i + 1)
+                + const.column_name_text_subheader_offset
+            )
+            col_name_offset = (
+                offset
+                + const.column_name_pointer_length * (i + 1)
+                + const.column_name_offset_offset
+            )
+            col_name_length = (
+                offset
+                + const.column_name_pointer_length * (i + 1)
+                + const.column_name_length_offset
+            )
+
+            idx = self._read_uint(
+                text_subheader, const.column_name_text_subheader_length
+            )
+            col_offset = self._read_uint(
+                col_name_offset, const.column_name_offset_length
+            )
+            col_len = self._read_uint(col_name_length, const.column_name_length_length)
+
+            name_raw = self.column_names_raw[idx]
+            cname = name_raw[col_offset : col_offset + col_len]
+            self.column_names.append(self._convert_header_text(cname))
+
+    def _process_columnattributes_subheader(self, offset: int, length: int) -> None:
+        int_len = self._int_length
+        column_attributes_vectors_count = (length - 2 * int_len - 12) // (int_len + 8)
+        for i in range(column_attributes_vectors_count):
+            col_data_offset = (
+                offset + int_len + const.column_data_offset_offset + i * (int_len + 8)
+            )
+            col_data_len = (
+                offset
+                + 2 * int_len
+                + const.column_data_length_offset
+                + i * (int_len + 8)
+            )
+            col_types = (
+                offset + 2 * int_len + const.column_type_offset + i * (int_len + 8)
+            )
+
+            x = self._read_uint(col_data_offset, int_len)
+            self._column_data_offsets.append(x)
+
+            x = self._read_uint(col_data_len, const.column_data_length_length)
+            self._column_data_lengths.append(x)
+
+            x = self._read_uint(col_types, const.column_type_length)
+            self._column_types.append(b"d" if x == 1 else b"s")
+
+    def _process_columnlist_subheader(self, offset: int, length: int) -> None:
+        # unknown purpose
+        pass
+
+    def _process_format_subheader(self, offset: int, length: int) -> None:
+        int_len = self._int_length
+        text_subheader_format = (
+            offset + const.column_format_text_subheader_index_offset + 3 * int_len
+        )
+        col_format_offset = offset + const.column_format_offset_offset + 3 * int_len
+        col_format_len = offset + const.column_format_length_offset + 3 * int_len
+        text_subheader_label = (
+            offset + const.column_label_text_subheader_index_offset + 3 * int_len
+        )
+        col_label_offset = offset + const.column_label_offset_offset + 3 * int_len
+        col_label_len = offset + const.column_label_length_offset + 3 * int_len
+
+        x = self._read_uint(
+            text_subheader_format, const.column_format_text_subheader_index_length
+        )
+        format_idx = min(x, len(self.column_names_raw) - 1)
+
+        format_start = self._read_uint(
+            col_format_offset, const.column_format_offset_length
+        )
+        format_len = self._read_uint(col_format_len, const.column_format_length_length)
+
+        label_idx = self._read_uint(
+            text_subheader_label, const.column_label_text_subheader_index_length
+        )
+        label_idx = min(label_idx, len(self.column_names_raw) - 1)
+
+        label_start = self._read_uint(
+            col_label_offset, const.column_label_offset_length
+        )
+        label_len = self._read_uint(col_label_len, const.column_label_length_length)
+
+        label_names = self.column_names_raw[label_idx]
+        column_label = self._convert_header_text(
+            label_names[label_start : label_start + label_len]
+        )
+        format_names = self.column_names_raw[format_idx]
+        column_format = self._convert_header_text(
+            format_names[format_start : format_start + format_len]
+        )
+        current_column_number = len(self.columns)
+
+        col = _Column(
+            current_column_number,
+            self.column_names[current_column_number],
+            column_label,
+            column_format,
+            self._column_types[current_column_number],
+            self._column_data_lengths[current_column_number],
+        )
+
+        self.column_formats.append(column_format)
+        self.columns.append(col)
+
+    def read(self, nrows: int | None = None) -> DataFrame:
+        if (nrows is None) and (self.chunksize is not None):
+            nrows = self.chunksize
+        elif nrows is None:
+            nrows = self.row_count
+
+        if len(self._column_types) == 0:
+            self.close()
+            raise EmptyDataError("No columns to parse from file")
+
+        if nrows > 0 and self._current_row_in_file_index >= self.row_count:
+            return DataFrame()
+
+        nrows = min(nrows, self.row_count - self._current_row_in_file_index)
+
+        nd = self._column_types.count(b"d")
+        ns = self._column_types.count(b"s")
+
+        self._string_chunk = np.empty((ns, nrows), dtype=object)
+        self._byte_chunk = np.zeros((nd, 8 * nrows), dtype=np.uint8)
+
+        self._current_row_in_chunk_index = 0
+        p = Parser(self)
+        p.read(nrows)
+
+        rslt = self._chunk_to_dataframe()
+        if self.index is not None:
+            rslt = rslt.set_index(self.index)
+
+        return rslt
+
+    def _read_next_page(self):
+        self._current_page_data_subheader_pointers = []
+        self._cached_page = self._path_or_buf.read(self._page_length)
+        if len(self._cached_page) <= 0:
+            return True
+        elif len(self._cached_page) != self._page_length:
+            self.close()
+            msg = (
+                "failed to read complete page from file (read "
+                f"{len(self._cached_page):d} of {self._page_length:d} bytes)"
+            )
+            raise ValueError(msg)
+
+        self._read_page_header()
+        if self._current_page_type in const.page_meta_types:
+            self._process_page_metadata()
+
+        if self._current_page_type not in const.page_meta_types + [
+            const.page_data_type,
+            const.page_mix_type,
+        ]:
+            return self._read_next_page()
+
+        return False
+
+    def _chunk_to_dataframe(self) -> DataFrame:
+        n = self._current_row_in_chunk_index
+        m = self._current_row_in_file_index
+        ix = range(m - n, m)
+        rslt = {}
+
+        js, jb = 0, 0
+        infer_string = get_option("future.infer_string")
+        for j in range(self.column_count):
+            name = self.column_names[j]
+
+            if self._column_types[j] == b"d":
+                col_arr = self._byte_chunk[jb, :].view(dtype=self.byte_order + "d")
+                rslt[name] = pd.Series(col_arr, dtype=np.float64, index=ix, copy=False)
+                if self.convert_dates:
+                    if self.column_formats[j] in const.sas_date_formats:
+                        rslt[name] = _convert_datetimes(rslt[name], "d")
+                    elif self.column_formats[j] in const.sas_datetime_formats:
+                        rslt[name] = _convert_datetimes(rslt[name], "s")
+                jb += 1
+            elif self._column_types[j] == b"s":
+                rslt[name] = pd.Series(self._string_chunk[js, :], index=ix, copy=False)
+                if self.convert_text and (self.encoding is not None):
+                    rslt[name] = self._decode_string(rslt[name].str)
+                    if infer_string:
+                        rslt[name] = rslt[name].astype("str")
+
+                js += 1
+            else:
+                self.close()
+                raise ValueError(f"unknown column type {repr(self._column_types[j])}")
+
+        df = DataFrame(rslt, columns=self.column_names, index=ix, copy=False)
+        return df
+
+    def _decode_string(self, b):
+        return b.decode(self.encoding or self.default_encoding)
+
+    def _convert_header_text(self, b: bytes) -> str | bytes:
+        if self.convert_header_text:
+            return self._decode_string(b)
+        else:
+            return b
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_constants.py b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_constants.py
new file mode 100644
index 0000000000000000000000000000000000000000..62c17bd03927e5f852af708e6b9ef6cf7e74d57c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_constants.py
@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from typing import Final
+
+magic: Final = (
+    b"\x00\x00\x00\x00\x00\x00\x00\x00"
+    b"\x00\x00\x00\x00\xc2\xea\x81\x60"
+    b"\xb3\x14\x11\xcf\xbd\x92\x08\x00"
+    b"\x09\xc7\x31\x8c\x18\x1f\x10\x11"
+)
+
+align_1_checker_value: Final = b"3"
+align_1_offset: Final = 32
+align_1_length: Final = 1
+align_1_value: Final = 4
+u64_byte_checker_value: Final = b"3"
+align_2_offset: Final = 35
+align_2_length: Final = 1
+align_2_value: Final = 4
+endianness_offset: Final = 37
+endianness_length: Final = 1
+platform_offset: Final = 39
+platform_length: Final = 1
+encoding_offset: Final = 70
+encoding_length: Final = 1
+dataset_offset: Final = 92
+dataset_length: Final = 64
+file_type_offset: Final = 156
+file_type_length: Final = 8
+date_created_offset: Final = 164
+date_created_length: Final = 8
+date_modified_offset: Final = 172
+date_modified_length: Final = 8
+header_size_offset: Final = 196
+header_size_length: Final = 4
+page_size_offset: Final = 200
+page_size_length: Final = 4
+page_count_offset: Final = 204
+page_count_length: Final = 4
+sas_release_offset: Final = 216
+sas_release_length: Final = 8
+sas_server_type_offset: Final = 224
+sas_server_type_length: Final = 16
+os_version_number_offset: Final = 240
+os_version_number_length: Final = 16
+os_maker_offset: Final = 256
+os_maker_length: Final = 16
+os_name_offset: Final = 272
+os_name_length: Final = 16
+page_bit_offset_x86: Final = 16
+page_bit_offset_x64: Final = 32
+subheader_pointer_length_x86: Final = 12
+subheader_pointer_length_x64: Final = 24
+page_type_offset: Final = 0
+page_type_length: Final = 2
+block_count_offset: Final = 2
+block_count_length: Final = 2
+subheader_count_offset: Final = 4
+subheader_count_length: Final = 2
+page_type_mask: Final = 0x0F00
+# Keep "page_comp_type" bits
+page_type_mask2: Final = 0xF000 | page_type_mask
+page_meta_type: Final = 0x0000
+page_data_type: Final = 0x0100
+page_mix_type: Final = 0x0200
+page_amd_type: Final = 0x0400
+page_meta2_type: Final = 0x4000
+page_comp_type: Final = 0x9000
+page_meta_types: Final = [page_meta_type, page_meta2_type]
+subheader_pointers_offset: Final = 8
+truncated_subheader_id: Final = 1
+compressed_subheader_id: Final = 4
+compressed_subheader_type: Final = 1
+text_block_size_length: Final = 2
+row_length_offset_multiplier: Final = 5
+row_count_offset_multiplier: Final = 6
+col_count_p1_multiplier: Final = 9
+col_count_p2_multiplier: Final = 10
+row_count_on_mix_page_offset_multiplier: Final = 15
+column_name_pointer_length: Final = 8
+column_name_text_subheader_offset: Final = 0
+column_name_text_subheader_length: Final = 2
+column_name_offset_offset: Final = 2
+column_name_offset_length: Final = 2
+column_name_length_offset: Final = 4
+column_name_length_length: Final = 2
+column_data_offset_offset: Final = 8
+column_data_length_offset: Final = 8
+column_data_length_length: Final = 4
+column_type_offset: Final = 14
+column_type_length: Final = 1
+column_format_text_subheader_index_offset: Final = 22
+column_format_text_subheader_index_length: Final = 2
+column_format_offset_offset: Final = 24
+column_format_offset_length: Final = 2
+column_format_length_offset: Final = 26
+column_format_length_length: Final = 2
+column_label_text_subheader_index_offset: Final = 28
+column_label_text_subheader_index_length: Final = 2
+column_label_offset_offset: Final = 30
+column_label_offset_length: Final = 2
+column_label_length_offset: Final = 32
+column_label_length_length: Final = 2
+rle_compression: Final = b"SASYZCRL"
+rdc_compression: Final = b"SASYZCR2"
+
+compression_literals: Final = [rle_compression, rdc_compression]
+
+# Incomplete list of encodings, using SAS nomenclature:
+# https://support.sas.com/documentation/onlinedoc/dfdmstudio/2.6/dmpdmsug/Content/dfU_Encodings_SAS.html
+# corresponding to the Python documentation of standard encodings
+# https://docs.python.org/3/library/codecs.html#standard-encodings
+encoding_names: Final = {
+    20: "utf-8",
+    29: "latin1",
+    30: "latin2",
+    31: "latin3",
+    32: "latin4",
+    33: "cyrillic",
+    34: "arabic",
+    35: "greek",
+    36: "hebrew",
+    37: "latin5",
+    38: "latin6",
+    39: "cp874",
+    40: "latin9",
+    41: "cp437",
+    42: "cp850",
+    43: "cp852",
+    44: "cp857",
+    45: "cp858",
+    46: "cp862",
+    47: "cp864",
+    48: "cp865",
+    49: "cp866",
+    50: "cp869",
+    51: "cp874",
+    # 52: "",  # not found
+    # 53: "",  # not found
+    # 54: "",  # not found
+    55: "cp720",
+    56: "cp737",
+    57: "cp775",
+    58: "cp860",
+    59: "cp863",
+    60: "cp1250",
+    61: "cp1251",
+    62: "cp1252",
+    63: "cp1253",
+    64: "cp1254",
+    65: "cp1255",
+    66: "cp1256",
+    67: "cp1257",
+    68: "cp1258",
+    118: "cp950",
+    # 119: "",  # not found
+    123: "big5",
+    125: "gb2312",
+    126: "cp936",
+    134: "euc_jp",
+    136: "cp932",
+    138: "shift_jis",
+    140: "euc-kr",
+    141: "cp949",
+    227: "latin8",
+    # 228: "", # not found
+    # 229: ""  # not found
+}
+
+
+class SASIndex:
+    row_size_index: Final = 0
+    column_size_index: Final = 1
+    subheader_counts_index: Final = 2
+    column_text_index: Final = 3
+    column_name_index: Final = 4
+    column_attributes_index: Final = 5
+    format_and_label_index: Final = 6
+    column_list_index: Final = 7
+    data_subheader_index: Final = 8
+
+
+subheader_signature_to_index: Final = {
+    b"\xF7\xF7\xF7\xF7": SASIndex.row_size_index,
+    b"\x00\x00\x00\x00\xF7\xF7\xF7\xF7": SASIndex.row_size_index,
+    b"\xF7\xF7\xF7\xF7\x00\x00\x00\x00": SASIndex.row_size_index,
+    b"\xF7\xF7\xF7\xF7\xFF\xFF\xFB\xFE": SASIndex.row_size_index,
+    b"\xF6\xF6\xF6\xF6": SASIndex.column_size_index,
+    b"\x00\x00\x00\x00\xF6\xF6\xF6\xF6": SASIndex.column_size_index,
+    b"\xF6\xF6\xF6\xF6\x00\x00\x00\x00": SASIndex.column_size_index,
+    b"\xF6\xF6\xF6\xF6\xFF\xFF\xFB\xFE": SASIndex.column_size_index,
+    b"\x00\xFC\xFF\xFF": SASIndex.subheader_counts_index,
+    b"\xFF\xFF\xFC\x00": SASIndex.subheader_counts_index,
+    b"\x00\xFC\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.subheader_counts_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFC\x00": SASIndex.subheader_counts_index,
+    b"\xFD\xFF\xFF\xFF": SASIndex.column_text_index,
+    b"\xFF\xFF\xFF\xFD": SASIndex.column_text_index,
+    b"\xFD\xFF\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.column_text_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFD": SASIndex.column_text_index,
+    b"\xFF\xFF\xFF\xFF": SASIndex.column_name_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.column_name_index,
+    b"\xFC\xFF\xFF\xFF": SASIndex.column_attributes_index,
+    b"\xFF\xFF\xFF\xFC": SASIndex.column_attributes_index,
+    b"\xFC\xFF\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.column_attributes_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFC": SASIndex.column_attributes_index,
+    b"\xFE\xFB\xFF\xFF": SASIndex.format_and_label_index,
+    b"\xFF\xFF\xFB\xFE": SASIndex.format_and_label_index,
+    b"\xFE\xFB\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.format_and_label_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFB\xFE": SASIndex.format_and_label_index,
+    b"\xFE\xFF\xFF\xFF": SASIndex.column_list_index,
+    b"\xFF\xFF\xFF\xFE": SASIndex.column_list_index,
+    b"\xFE\xFF\xFF\xFF\xFF\xFF\xFF\xFF": SASIndex.column_list_index,
+    b"\xFF\xFF\xFF\xFF\xFF\xFF\xFF\xFE": SASIndex.column_list_index,
+}
+
+
+# List of frequently used SAS date and datetime formats
+# http://support.sas.com/documentation/cdl/en/etsug/60372/HTML/default/viewer.htm#etsug_intervals_sect009.htm
+# https://github.com/epam/parso/blob/master/src/main/java/com/epam/parso/impl/SasFileConstants.java
+sas_date_formats: Final = (
+    "DATE",
+    "DAY",
+    "DDMMYY",
+    "DOWNAME",
+    "JULDAY",
+    "JULIAN",
+    "MMDDYY",
+    "MMYY",
+    "MMYYC",
+    "MMYYD",
+    "MMYYP",
+    "MMYYS",
+    "MMYYN",
+    "MONNAME",
+    "MONTH",
+    "MONYY",
+    "QTR",
+    "QTRR",
+    "NENGO",
+    "WEEKDATE",
+    "WEEKDATX",
+    "WEEKDAY",
+    "WEEKV",
+    "WORDDATE",
+    "WORDDATX",
+    "YEAR",
+    "YYMM",
+    "YYMMC",
+    "YYMMD",
+    "YYMMP",
+    "YYMMS",
+    "YYMMN",
+    "YYMON",
+    "YYMMDD",
+    "YYQ",
+    "YYQC",
+    "YYQD",
+    "YYQP",
+    "YYQS",
+    "YYQN",
+    "YYQR",
+    "YYQRC",
+    "YYQRD",
+    "YYQRP",
+    "YYQRS",
+    "YYQRN",
+    "YYMMDDP",
+    "YYMMDDC",
+    "E8601DA",
+    "YYMMDDN",
+    "MMDDYYC",
+    "MMDDYYS",
+    "MMDDYYD",
+    "YYMMDDS",
+    "B8601DA",
+    "DDMMYYN",
+    "YYMMDDD",
+    "DDMMYYB",
+    "DDMMYYP",
+    "MMDDYYP",
+    "YYMMDDB",
+    "MMDDYYN",
+    "DDMMYYC",
+    "DDMMYYD",
+    "DDMMYYS",
+    "MINGUO",
+)
+
+sas_datetime_formats: Final = (
+    "DATETIME",
+    "DTWKDATX",
+    "B8601DN",
+    "B8601DT",
+    "B8601DX",
+    "B8601DZ",
+    "B8601LX",
+    "E8601DN",
+    "E8601DT",
+    "E8601DX",
+    "E8601DZ",
+    "E8601LX",
+    "DATEAMPM",
+    "DTDATE",
+    "DTMONYY",
+    "DTMONYY",
+    "DTWKDATX",
+    "DTYEAR",
+    "TOD",
+    "MDYAMPM",
+)
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_xport.py b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_xport.py
new file mode 100644
index 0000000000000000000000000000000000000000..11b2ed0ee73168ba82e3b8d312f96bcea9398e49
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sas/sas_xport.py
@@ -0,0 +1,508 @@
+"""
+Read a SAS XPort format file into a Pandas DataFrame.
+
+Based on code from Jack Cushman (github.com/jcushman/xport).
+
+The file format is defined here:
+
+https://support.sas.com/content/dam/SAS/support/en/technical-papers/record-layout-of-a-sas-version-5-or-6-data-set-in-sas-transport-xport-format.pdf
+"""
+from __future__ import annotations
+
+from collections import abc
+from datetime import datetime
+import struct
+from typing import TYPE_CHECKING
+import warnings
+
+import numpy as np
+
+from pandas.util._decorators import Appender
+from pandas.util._exceptions import find_stack_level
+
+import pandas as pd
+
+from pandas.io.common import get_handle
+from pandas.io.sas.sasreader import ReaderBase
+
+if TYPE_CHECKING:
+    from pandas._typing import (
+        CompressionOptions,
+        DatetimeNaTType,
+        FilePath,
+        ReadBuffer,
+    )
+_correct_line1 = (
+    "HEADER RECORD*******LIBRARY HEADER RECORD!!!!!!!"
+    "000000000000000000000000000000  "
+)
+_correct_header1 = (
+    "HEADER RECORD*******MEMBER  HEADER RECORD!!!!!!!000000000000000001600000000"
+)
+_correct_header2 = (
+    "HEADER RECORD*******DSCRPTR HEADER RECORD!!!!!!!"
+    "000000000000000000000000000000  "
+)
+_correct_obs_header = (
+    "HEADER RECORD*******OBS     HEADER RECORD!!!!!!!"
+    "000000000000000000000000000000  "
+)
+_fieldkeys = [
+    "ntype",
+    "nhfun",
+    "field_length",
+    "nvar0",
+    "name",
+    "label",
+    "nform",
+    "nfl",
+    "num_decimals",
+    "nfj",
+    "nfill",
+    "niform",
+    "nifl",
+    "nifd",
+    "npos",
+    "_",
+]
+
+
+_base_params_doc = """\
+Parameters
+----------
+filepath_or_buffer : str or file-like object
+    Path to SAS file or object implementing binary read method."""
+
+_params2_doc = """\
+index : identifier of index column
+    Identifier of column that should be used as index of the DataFrame.
+encoding : str
+    Encoding for text data.
+chunksize : int
+    Read file `chunksize` lines at a time, returns iterator."""
+
+_format_params_doc = """\
+format : str
+    File format, only `xport` is currently supported."""
+
+_iterator_doc = """\
+iterator : bool, default False
+    Return XportReader object for reading file incrementally."""
+
+
+_read_sas_doc = f"""Read a SAS file into a DataFrame.
+
+{_base_params_doc}
+{_format_params_doc}
+{_params2_doc}
+{_iterator_doc}
+
+Returns
+-------
+DataFrame or XportReader
+
+Examples
+--------
+Read a SAS Xport file:
+
+>>> df = pd.read_sas('filename.XPT')
+
+Read a Xport file in 10,000 line chunks:
+
+>>> itr = pd.read_sas('filename.XPT', chunksize=10000)
+>>> for chunk in itr:
+>>>     do_something(chunk)
+
+"""
+
+_xport_reader_doc = f"""\
+Class for reading SAS Xport files.
+
+{_base_params_doc}
+{_params2_doc}
+
+Attributes
+----------
+member_info : list
+    Contains information about the file
+fields : list
+    Contains information about the variables in the file
+"""
+
+_read_method_doc = """\
+Read observations from SAS Xport file, returning as data frame.
+
+Parameters
+----------
+nrows : int
+    Number of rows to read from data file; if None, read whole
+    file.
+
+Returns
+-------
+A DataFrame.
+"""
+
+
+def _parse_date(datestr: str) -> DatetimeNaTType:
+    """Given a date in xport format, return Python date."""
+    try:
+        # e.g. "16FEB11:10:07:55"
+        return datetime.strptime(datestr, "%d%b%y:%H:%M:%S")
+    except ValueError:
+        return pd.NaT
+
+
+def _split_line(s: str, parts):
+    """
+    Parameters
+    ----------
+    s: str
+        Fixed-length string to split
+    parts: list of (name, length) pairs
+        Used to break up string, name '_' will be filtered from output.
+
+    Returns
+    -------
+    Dict of name:contents of string at given location.
+    """
+    out = {}
+    start = 0
+    for name, length in parts:
+        out[name] = s[start : start + length].strip()
+        start += length
+    del out["_"]
+    return out
+
+
+def _handle_truncated_float_vec(vec, nbytes):
+    # This feature is not well documented, but some SAS XPORT files
+    # have 2-7 byte "truncated" floats.  To read these truncated
+    # floats, pad them with zeros on the right to make 8 byte floats.
+    #
+    # References:
+    # https://github.com/jcushman/xport/pull/3
+    # The R "foreign" library
+
+    if nbytes != 8:
+        vec1 = np.zeros(len(vec), np.dtype("S8"))
+        dtype = np.dtype(f"S{nbytes},S{8 - nbytes}")
+        vec2 = vec1.view(dtype=dtype)
+        vec2["f0"] = vec
+        return vec2
+
+    return vec
+
+
+def _parse_float_vec(vec):
+    """
+    Parse a vector of float values representing IBM 8 byte floats into
+    native 8 byte floats.
+    """
+    dtype = np.dtype(">u4,>u4")
+    vec1 = vec.view(dtype=dtype)
+    xport1 = vec1["f0"]
+    xport2 = vec1["f1"]
+
+    # Start by setting first half of ieee number to first half of IBM
+    # number sans exponent
+    ieee1 = xport1 & 0x00FFFFFF
+
+    # The fraction bit to the left of the binary point in the ieee
+    # format was set and the number was shifted 0, 1, 2, or 3
+    # places. This will tell us how to adjust the ibm exponent to be a
+    # power of 2 ieee exponent and how to shift the fraction bits to
+    # restore the correct magnitude.
+    shift = np.zeros(len(vec), dtype=np.uint8)
+    shift[np.where(xport1 & 0x00200000)] = 1
+    shift[np.where(xport1 & 0x00400000)] = 2
+    shift[np.where(xport1 & 0x00800000)] = 3
+
+    # shift the ieee number down the correct number of places then
+    # set the second half of the ieee number to be the second half
+    # of the ibm number shifted appropriately, ored with the bits
+    # from the first half that would have been shifted in if we
+    # could shift a double. All we are worried about are the low
+    # order 3 bits of the first half since we're only shifting by
+    # 1, 2, or 3.
+    ieee1 >>= shift
+    ieee2 = (xport2 >> shift) | ((xport1 & 0x00000007) << (29 + (3 - shift)))
+
+    # clear the 1 bit to the left of the binary point
+    ieee1 &= 0xFFEFFFFF
+
+    # set the exponent of the ieee number to be the actual exponent
+    # plus the shift count + 1023. Or this into the first half of the
+    # ieee number. The ibm exponent is excess 64 but is adjusted by 65
+    # since during conversion to ibm format the exponent is
+    # incremented by 1 and the fraction bits left 4 positions to the
+    # right of the radix point.  (had to add >> 24 because C treats &
+    # 0x7f as 0x7f000000 and Python doesn't)
+    ieee1 |= ((((((xport1 >> 24) & 0x7F) - 65) << 2) + shift + 1023) << 20) | (
+        xport1 & 0x80000000
+    )
+
+    ieee = np.empty((len(ieee1),), dtype=">u4,>u4")
+    ieee["f0"] = ieee1
+    ieee["f1"] = ieee2
+    ieee = ieee.view(dtype=">f8")
+    ieee = ieee.astype("f8")
+
+    return ieee
+
+
+class XportReader(ReaderBase, abc.Iterator):
+    __doc__ = _xport_reader_doc
+
+    def __init__(
+        self,
+        filepath_or_buffer: FilePath | ReadBuffer[bytes],
+        index=None,
+        encoding: str | None = "ISO-8859-1",
+        chunksize: int | None = None,
+        compression: CompressionOptions = "infer",
+    ) -> None:
+        self._encoding = encoding
+        self._lines_read = 0
+        self._index = index
+        self._chunksize = chunksize
+
+        self.handles = get_handle(
+            filepath_or_buffer,
+            "rb",
+            encoding=encoding,
+            is_text=False,
+            compression=compression,
+        )
+        self.filepath_or_buffer = self.handles.handle
+
+        try:
+            self._read_header()
+        except Exception:
+            self.close()
+            raise
+
+    def close(self) -> None:
+        self.handles.close()
+
+    def _get_row(self):
+        return self.filepath_or_buffer.read(80).decode()
+
+    def _read_header(self) -> None:
+        self.filepath_or_buffer.seek(0)
+
+        # read file header
+        line1 = self._get_row()
+        if line1 != _correct_line1:
+            if "**COMPRESSED**" in line1:
+                # this was created with the PROC CPORT method and can't be read
+                # https://documentation.sas.com/doc/en/pgmsascdc/9.4_3.5/movefile/p1bm6aqp3fw4uin1hucwh718f6kp.htm
+                raise ValueError(
+                    "Header record indicates a CPORT file, which is not readable."
+                )
+            raise ValueError("Header record is not an XPORT file.")
+
+        line2 = self._get_row()
+        fif = [["prefix", 24], ["version", 8], ["OS", 8], ["_", 24], ["created", 16]]
+        file_info = _split_line(line2, fif)
+        if file_info["prefix"] != "SAS     SAS     SASLIB":
+            raise ValueError("Header record has invalid prefix.")
+        file_info["created"] = _parse_date(file_info["created"])
+        self.file_info = file_info
+
+        line3 = self._get_row()
+        file_info["modified"] = _parse_date(line3[:16])
+
+        # read member header
+        header1 = self._get_row()
+        header2 = self._get_row()
+        headflag1 = header1.startswith(_correct_header1)
+        headflag2 = header2 == _correct_header2
+        if not (headflag1 and headflag2):
+            raise ValueError("Member header not found")
+        # usually 140, could be 135
+        fieldnamelength = int(header1[-5:-2])
+
+        # member info
+        mem = [
+            ["prefix", 8],
+            ["set_name", 8],
+            ["sasdata", 8],
+            ["version", 8],
+            ["OS", 8],
+            ["_", 24],
+            ["created", 16],
+        ]
+        member_info = _split_line(self._get_row(), mem)
+        mem = [["modified", 16], ["_", 16], ["label", 40], ["type", 8]]
+        member_info.update(_split_line(self._get_row(), mem))
+        member_info["modified"] = _parse_date(member_info["modified"])
+        member_info["created"] = _parse_date(member_info["created"])
+        self.member_info = member_info
+
+        # read field names
+        types = {1: "numeric", 2: "char"}
+        fieldcount = int(self._get_row()[54:58])
+        datalength = fieldnamelength * fieldcount
+        # round up to nearest 80
+        if datalength % 80:
+            datalength += 80 - datalength % 80
+        fielddata = self.filepath_or_buffer.read(datalength)
+        fields = []
+        obs_length = 0
+        while len(fielddata) >= fieldnamelength:
+            # pull data for one field
+            fieldbytes, fielddata = (
+                fielddata[:fieldnamelength],
+                fielddata[fieldnamelength:],
+            )
+
+            # rest at end gets ignored, so if field is short, pad out
+            # to match struct pattern below
+            fieldbytes = fieldbytes.ljust(140)
+
+            fieldstruct = struct.unpack(">hhhh8s40s8shhh2s8shhl52s", fieldbytes)
+            field = dict(zip(_fieldkeys, fieldstruct))
+            del field["_"]
+            field["ntype"] = types[field["ntype"]]
+            fl = field["field_length"]
+            if field["ntype"] == "numeric" and ((fl < 2) or (fl > 8)):
+                msg = f"Floating field width {fl} is not between 2 and 8."
+                raise TypeError(msg)
+
+            for k, v in field.items():
+                try:
+                    field[k] = v.strip()
+                except AttributeError:
+                    pass
+
+            obs_length += field["field_length"]
+            fields += [field]
+
+        header = self._get_row()
+        if not header == _correct_obs_header:
+            raise ValueError("Observation header not found.")
+
+        self.fields = fields
+        self.record_length = obs_length
+        self.record_start = self.filepath_or_buffer.tell()
+
+        self.nobs = self._record_count()
+        self.columns = [x["name"].decode() for x in self.fields]
+
+        # Setup the dtype.
+        dtypel = [
+            ("s" + str(i), "S" + str(field["field_length"]))
+            for i, field in enumerate(self.fields)
+        ]
+        dtype = np.dtype(dtypel)
+        self._dtype = dtype
+
+    def __next__(self) -> pd.DataFrame:
+        return self.read(nrows=self._chunksize or 1)
+
+    def _record_count(self) -> int:
+        """
+        Get number of records in file.
+
+        This is maybe suboptimal because we have to seek to the end of
+        the file.
+
+        Side effect: returns file position to record_start.
+        """
+        self.filepath_or_buffer.seek(0, 2)
+        total_records_length = self.filepath_or_buffer.tell() - self.record_start
+
+        if total_records_length % 80 != 0:
+            warnings.warn(
+                "xport file may be corrupted.",
+                stacklevel=find_stack_level(),
+            )
+
+        if self.record_length > 80:
+            self.filepath_or_buffer.seek(self.record_start)
+            return total_records_length // self.record_length
+
+        self.filepath_or_buffer.seek(-80, 2)
+        last_card_bytes = self.filepath_or_buffer.read(80)
+        last_card = np.frombuffer(last_card_bytes, dtype=np.uint64)
+
+        # 8 byte blank
+        ix = np.flatnonzero(last_card == 2314885530818453536)
+
+        if len(ix) == 0:
+            tail_pad = 0
+        else:
+            tail_pad = 8 * len(ix)
+
+        self.filepath_or_buffer.seek(self.record_start)
+
+        return (total_records_length - tail_pad) // self.record_length
+
+    def get_chunk(self, size: int | None = None) -> pd.DataFrame:
+        """
+        Reads lines from Xport file and returns as dataframe
+
+        Parameters
+        ----------
+        size : int, defaults to None
+            Number of lines to read.  If None, reads whole file.
+
+        Returns
+        -------
+        DataFrame
+        """
+        if size is None:
+            size = self._chunksize
+        return self.read(nrows=size)
+
+    def _missing_double(self, vec):
+        v = vec.view(dtype="u1,u1,u2,u4")
+        miss = (v["f1"] == 0) & (v["f2"] == 0) & (v["f3"] == 0)
+        miss1 = (
+            ((v["f0"] >= 0x41) & (v["f0"] <= 0x5A))
+            | (v["f0"] == 0x5F)
+            | (v["f0"] == 0x2E)
+        )
+        miss &= miss1
+        return miss
+
+    @Appender(_read_method_doc)
+    def read(self, nrows: int | None = None) -> pd.DataFrame:
+        if nrows is None:
+            nrows = self.nobs
+
+        read_lines = min(nrows, self.nobs - self._lines_read)
+        read_len = read_lines * self.record_length
+        if read_len <= 0:
+            self.close()
+            raise StopIteration
+        raw = self.filepath_or_buffer.read(read_len)
+        data = np.frombuffer(raw, dtype=self._dtype, count=read_lines)
+
+        df_data = {}
+        for j, x in enumerate(self.columns):
+            vec = data["s" + str(j)]
+            ntype = self.fields[j]["ntype"]
+            if ntype == "numeric":
+                vec = _handle_truncated_float_vec(vec, self.fields[j]["field_length"])
+                miss = self._missing_double(vec)
+                v = _parse_float_vec(vec)
+                v[miss] = np.nan
+            elif self.fields[j]["ntype"] == "char":
+                v = [y.rstrip() for y in vec]
+
+                if self._encoding is not None:
+                    v = [y.decode(self._encoding) for y in v]
+
+            df_data.update({x: v})
+        df = pd.DataFrame(df_data)
+
+        if self._index is None:
+            df.index = pd.Index(range(self._lines_read, self._lines_read + read_lines))
+        else:
+            df = df.set_index(self._index)
+
+        self._lines_read += read_lines
+
+        return df
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sas/sasreader.py b/.venv/lib/python3.13/site-packages/pandas/io/sas/sasreader.py
new file mode 100644
index 0000000000000000000000000000000000000000..c39313d5dc6548fcc014f7a886988a2b9d9001ed
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sas/sasreader.py
@@ -0,0 +1,178 @@
+"""
+Read SAS sas7bdat or xport files.
+"""
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from typing import (
+    TYPE_CHECKING,
+    overload,
+)
+
+from pandas.util._decorators import doc
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import stringify_path
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+    from types import TracebackType
+
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        ReadBuffer,
+        Self,
+    )
+
+    from pandas import DataFrame
+
+
+class ReaderBase(ABC):
+    """
+    Protocol for XportReader and SAS7BDATReader classes.
+    """
+
+    @abstractmethod
+    def read(self, nrows: int | None = None) -> DataFrame:
+        ...
+
+    @abstractmethod
+    def close(self) -> None:
+        ...
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        self.close()
+
+
+@overload
+def read_sas(
+    filepath_or_buffer: FilePath | ReadBuffer[bytes],
+    *,
+    format: str | None = ...,
+    index: Hashable | None = ...,
+    encoding: str | None = ...,
+    chunksize: int = ...,
+    iterator: bool = ...,
+    compression: CompressionOptions = ...,
+) -> ReaderBase:
+    ...
+
+
+@overload
+def read_sas(
+    filepath_or_buffer: FilePath | ReadBuffer[bytes],
+    *,
+    format: str | None = ...,
+    index: Hashable | None = ...,
+    encoding: str | None = ...,
+    chunksize: None = ...,
+    iterator: bool = ...,
+    compression: CompressionOptions = ...,
+) -> DataFrame | ReaderBase:
+    ...
+
+
+@doc(decompression_options=_shared_docs["decompression_options"] % "filepath_or_buffer")
+def read_sas(
+    filepath_or_buffer: FilePath | ReadBuffer[bytes],
+    *,
+    format: str | None = None,
+    index: Hashable | None = None,
+    encoding: str | None = None,
+    chunksize: int | None = None,
+    iterator: bool = False,
+    compression: CompressionOptions = "infer",
+) -> DataFrame | ReaderBase:
+    """
+    Read SAS files stored as either XPORT or SAS7BDAT format files.
+
+    Parameters
+    ----------
+    filepath_or_buffer : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a binary ``read()`` function. The string could be a URL.
+        Valid URL schemes include http, ftp, s3, and file. For file URLs, a host is
+        expected. A local file could be:
+        ``file://localhost/path/to/table.sas7bdat``.
+    format : str {{'xport', 'sas7bdat'}} or None
+        If None, file format is inferred from file extension. If 'xport' or
+        'sas7bdat', uses the corresponding format.
+    index : identifier of index column, defaults to None
+        Identifier of column that should be used as index of the DataFrame.
+    encoding : str, default is None
+        Encoding for text data.  If None, text data are stored as raw bytes.
+    chunksize : int
+        Read file `chunksize` lines at a time, returns iterator.
+    iterator : bool, defaults to False
+        If True, returns an iterator for reading the file incrementally.
+    {decompression_options}
+
+    Returns
+    -------
+    DataFrame if iterator=False and chunksize=None, else SAS7BDATReader
+    or XportReader
+
+    Examples
+    --------
+    >>> df = pd.read_sas("sas_data.sas7bdat")  # doctest: +SKIP
+    """
+    if format is None:
+        buffer_error_msg = (
+            "If this is a buffer object rather "
+            "than a string name, you must specify a format string"
+        )
+        filepath_or_buffer = stringify_path(filepath_or_buffer)
+        if not isinstance(filepath_or_buffer, str):
+            raise ValueError(buffer_error_msg)
+        fname = filepath_or_buffer.lower()
+        if ".xpt" in fname:
+            format = "xport"
+        elif ".sas7bdat" in fname:
+            format = "sas7bdat"
+        else:
+            raise ValueError(
+                f"unable to infer format of SAS file from filename: {repr(fname)}"
+            )
+
+    reader: ReaderBase
+    if format.lower() == "xport":
+        from pandas.io.sas.sas_xport import XportReader
+
+        reader = XportReader(
+            filepath_or_buffer,
+            index=index,
+            encoding=encoding,
+            chunksize=chunksize,
+            compression=compression,
+        )
+    elif format.lower() == "sas7bdat":
+        from pandas.io.sas.sas7bdat import SAS7BDATReader
+
+        reader = SAS7BDATReader(
+            filepath_or_buffer,
+            index=index,
+            encoding=encoding,
+            chunksize=chunksize,
+            compression=compression,
+        )
+    else:
+        raise ValueError("unknown SAS format")
+
+    if iterator or chunksize:
+        return reader
+
+    with reader:
+        return reader.read()
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/spss.py b/.venv/lib/python3.13/site-packages/pandas/io/spss.py
new file mode 100644
index 0000000000000000000000000000000000000000..db31a07df79e6de2862e57fd75de0bd4b9c2455d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/spss.py
@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.inference import is_list_like
+
+from pandas.io.common import stringify_path
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from pandas._typing import DtypeBackend
+
+    from pandas import DataFrame
+
+
+def read_spss(
+    path: str | Path,
+    usecols: Sequence[str] | None = None,
+    convert_categoricals: bool = True,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame:
+    """
+    Load an SPSS file from the file path, returning a DataFrame.
+
+    Parameters
+    ----------
+    path : str or Path
+        File path.
+    usecols : list-like, optional
+        Return a subset of the columns. If None, return all columns.
+    convert_categoricals : bool, default is True
+        Convert categorical columns into pd.Categorical.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    DataFrame
+
+    Examples
+    --------
+    >>> df = pd.read_spss("spss_data.sav")  # doctest: +SKIP
+    """
+    pyreadstat = import_optional_dependency("pyreadstat")
+    check_dtype_backend(dtype_backend)
+
+    if usecols is not None:
+        if not is_list_like(usecols):
+            raise TypeError("usecols must be list-like.")
+        usecols = list(usecols)  # pyreadstat requires a list
+
+    df, metadata = pyreadstat.read_sav(
+        stringify_path(path), usecols=usecols, apply_value_formats=convert_categoricals
+    )
+    df.attrs = metadata.__dict__
+    if dtype_backend is not lib.no_default:
+        df = df.convert_dtypes(dtype_backend=dtype_backend)
+    return df
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/sql.py b/.venv/lib/python3.13/site-packages/pandas/io/sql.py
new file mode 100644
index 0000000000000000000000000000000000000000..7027702a696feda183995a6346238e4076dbc069
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/sql.py
@@ -0,0 +1,2916 @@
+"""
+Collection of query wrappers / abstractions to both facilitate data
+retrieval and to reduce dependency on DB-specific API.
+"""
+
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from contextlib import (
+    ExitStack,
+    contextmanager,
+)
+from datetime import (
+    date,
+    datetime,
+    time,
+)
+from functools import partial
+import re
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+    Literal,
+    cast,
+    overload,
+)
+import warnings
+
+import numpy as np
+
+from pandas._config import using_string_dtype
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import (
+    AbstractMethodError,
+    DatabaseError,
+)
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import (
+    is_dict_like,
+    is_list_like,
+    is_object_dtype,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+from pandas.core.dtypes.missing import isna
+
+from pandas import get_option
+from pandas.core.api import (
+    DataFrame,
+    Series,
+)
+from pandas.core.arrays import ArrowExtensionArray
+from pandas.core.arrays.string_ import StringDtype
+from pandas.core.base import PandasObject
+import pandas.core.common as com
+from pandas.core.common import maybe_make_list
+from pandas.core.internals.construction import convert_object_array
+from pandas.core.tools.datetimes import to_datetime
+
+from pandas.io._util import arrow_table_to_pandas
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterator,
+        Mapping,
+    )
+
+    from sqlalchemy import Table
+    from sqlalchemy.sql.expression import (
+        Select,
+        TextClause,
+    )
+
+    from pandas._typing import (
+        DateTimeErrorChoices,
+        DtypeArg,
+        DtypeBackend,
+        IndexLabel,
+        Self,
+    )
+
+    from pandas import Index
+
+# -----------------------------------------------------------------------------
+# -- Helper functions
+
+
+def _process_parse_dates_argument(parse_dates):
+    """Process parse_dates argument for read_sql functions"""
+    # handle non-list entries for parse_dates gracefully
+    if parse_dates is True or parse_dates is None or parse_dates is False:
+        parse_dates = []
+
+    elif not hasattr(parse_dates, "__iter__"):
+        parse_dates = [parse_dates]
+    return parse_dates
+
+
+def _handle_date_column(
+    col, utc: bool = False, format: str | dict[str, Any] | None = None
+):
+    if isinstance(format, dict):
+        # GH35185 Allow custom error values in parse_dates argument of
+        # read_sql like functions.
+        # Format can take on custom to_datetime argument values such as
+        # {"errors": "coerce"} or {"dayfirst": True}
+        error: DateTimeErrorChoices = format.pop("errors", None) or "ignore"
+        if error == "ignore":
+            try:
+                return to_datetime(col, **format)
+            except (TypeError, ValueError):
+                # TODO: not reached 2023-10-27; needed?
+                return col
+        return to_datetime(col, errors=error, **format)
+    else:
+        # Allow passing of formatting string for integers
+        # GH17855
+        if format is None and (
+            issubclass(col.dtype.type, np.floating)
+            or issubclass(col.dtype.type, np.integer)
+        ):
+            format = "s"
+        if format in ["D", "d", "h", "m", "s", "ms", "us", "ns"]:
+            return to_datetime(col, errors="coerce", unit=format, utc=utc)
+        elif isinstance(col.dtype, DatetimeTZDtype):
+            # coerce to UTC timezone
+            # GH11216
+            return to_datetime(col, utc=True)
+        else:
+            return to_datetime(col, errors="coerce", format=format, utc=utc)
+
+
+def _parse_date_columns(data_frame, parse_dates):
+    """
+    Force non-datetime columns to be read as such.
+    Supports both string formatted and integer timestamp columns.
+    """
+    parse_dates = _process_parse_dates_argument(parse_dates)
+
+    # we want to coerce datetime64_tz dtypes for now to UTC
+    # we could in theory do a 'nice' conversion from a FixedOffset tz
+    # GH11216
+    for i, (col_name, df_col) in enumerate(data_frame.items()):
+        if isinstance(df_col.dtype, DatetimeTZDtype) or col_name in parse_dates:
+            try:
+                fmt = parse_dates[col_name]
+            except (KeyError, TypeError):
+                fmt = None
+            data_frame.isetitem(i, _handle_date_column(df_col, format=fmt))
+
+    return data_frame
+
+
+def _convert_arrays_to_dataframe(
+    data,
+    columns,
+    coerce_float: bool = True,
+    dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+) -> DataFrame:
+    content = lib.to_object_array_tuples(data)
+    arrays = convert_object_array(
+        list(content.T),
+        dtype=None,
+        coerce_float=coerce_float,
+        dtype_backend=dtype_backend,
+    )
+    if dtype_backend == "pyarrow":
+        pa = import_optional_dependency("pyarrow")
+
+        result_arrays = []
+        for arr in arrays:
+            pa_array = pa.array(arr, from_pandas=True)
+            if arr.dtype == "string":
+                # TODO: Arrow still infers strings arrays as regular strings instead
+                # of large_string, which is what we preserver everywhere else for
+                # dtype_backend="pyarrow". We may want to reconsider this
+                pa_array = pa_array.cast(pa.string())
+            result_arrays.append(ArrowExtensionArray(pa_array))
+        arrays = result_arrays  # type: ignore[assignment]
+    if arrays:
+        df = DataFrame(dict(zip(list(range(len(columns))), arrays)))
+        df.columns = columns
+        return df
+    else:
+        return DataFrame(columns=columns)
+
+
+def _wrap_result(
+    data,
+    columns,
+    index_col=None,
+    coerce_float: bool = True,
+    parse_dates=None,
+    dtype: DtypeArg | None = None,
+    dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+):
+    """Wrap result set of a SQLAlchemy query in a DataFrame."""
+    frame = _convert_arrays_to_dataframe(data, columns, coerce_float, dtype_backend)
+
+    if dtype:
+        frame = frame.astype(dtype)
+
+    frame = _parse_date_columns(frame, parse_dates)
+
+    if index_col is not None:
+        frame = frame.set_index(index_col)
+
+    return frame
+
+
+def _wrap_result_adbc(
+    df: DataFrame,
+    *,
+    index_col=None,
+    parse_dates=None,
+    dtype: DtypeArg | None = None,
+    dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+) -> DataFrame:
+    """Wrap result set of a SQLAlchemy query in a DataFrame."""
+    if dtype:
+        df = df.astype(dtype)
+
+    df = _parse_date_columns(df, parse_dates)
+
+    if index_col is not None:
+        df = df.set_index(index_col)
+
+    return df
+
+
+def execute(sql, con, params=None):
+    """
+    Execute the given SQL query using the provided connection object.
+
+    Parameters
+    ----------
+    sql : string
+        SQL query to be executed.
+    con : SQLAlchemy connection or sqlite3 connection
+        If a DBAPI2 object, only sqlite3 is supported.
+    params : list or tuple, optional, default: None
+        List of parameters to pass to execute method.
+
+    Returns
+    -------
+    Results Iterable
+    """
+    warnings.warn(
+        "`pandas.io.sql.execute` is deprecated and "
+        "will be removed in the future version.",
+        FutureWarning,
+        stacklevel=find_stack_level(),
+    )  # GH50185
+    sqlalchemy = import_optional_dependency("sqlalchemy", errors="ignore")
+
+    if sqlalchemy is not None and isinstance(con, (str, sqlalchemy.engine.Engine)):
+        raise TypeError("pandas.io.sql.execute requires a connection")  # GH50185
+    with pandasSQL_builder(con, need_transaction=True) as pandas_sql:
+        return pandas_sql.execute(sql, params)
+
+
+# -----------------------------------------------------------------------------
+# -- Read and write to DataFrames
+
+
+@overload
+def read_sql_table(
+    table_name: str,
+    con,
+    schema=...,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    parse_dates: list[str] | dict[str, str] | None = ...,
+    columns: list[str] | None = ...,
+    chunksize: None = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame:
+    ...
+
+
+@overload
+def read_sql_table(
+    table_name: str,
+    con,
+    schema=...,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    parse_dates: list[str] | dict[str, str] | None = ...,
+    columns: list[str] | None = ...,
+    chunksize: int = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> Iterator[DataFrame]:
+    ...
+
+
+def read_sql_table(
+    table_name: str,
+    con,
+    schema: str | None = None,
+    index_col: str | list[str] | None = None,
+    coerce_float: bool = True,
+    parse_dates: list[str] | dict[str, str] | None = None,
+    columns: list[str] | None = None,
+    chunksize: int | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame | Iterator[DataFrame]:
+    """
+    Read SQL database table into a DataFrame.
+
+    Given a table name and a SQLAlchemy connectable, returns a DataFrame.
+    This function does not support DBAPI connections.
+
+    Parameters
+    ----------
+    table_name : str
+        Name of SQL table in database.
+    con : SQLAlchemy connectable or str
+        A database URI could be provided as str.
+        SQLite DBAPI connection mode not supported.
+    schema : str, default None
+        Name of SQL schema in database to query (if database flavor
+        supports this). Uses default schema if None (default).
+    index_col : str or list of str, optional, default: None
+        Column(s) to set as index(MultiIndex).
+    coerce_float : bool, default True
+        Attempts to convert values of non-string, non-numeric objects (like
+        decimal.Decimal) to floating point. Can result in loss of Precision.
+    parse_dates : list or dict, default None
+        - List of column names to parse as dates.
+        - Dict of ``{column_name: format string}`` where format string is
+          strftime compatible in case of parsing string times or is one of
+          (D, s, ns, ms, us) in case of parsing integer timestamps.
+        - Dict of ``{column_name: arg dict}``, where the arg dict corresponds
+          to the keyword arguments of :func:`pandas.to_datetime`
+          Especially useful with databases without native Datetime support,
+          such as SQLite.
+    columns : list, default None
+        List of column names to select from SQL table.
+    chunksize : int, default None
+        If specified, returns an iterator where `chunksize` is the number of
+        rows to include in each chunk.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    DataFrame or Iterator[DataFrame]
+        A SQL table is returned as two-dimensional data structure with labeled
+        axes.
+
+    See Also
+    --------
+    read_sql_query : Read SQL query into a DataFrame.
+    read_sql : Read SQL query or database table into a DataFrame.
+
+    Notes
+    -----
+    Any datetime values with time zone information will be converted to UTC.
+
+    Examples
+    --------
+    >>> pd.read_sql_table('table_name', 'postgres:///db_name')  # doctest:+SKIP
+    """
+
+    check_dtype_backend(dtype_backend)
+    if dtype_backend is lib.no_default:
+        dtype_backend = "numpy"  # type: ignore[assignment]
+    assert dtype_backend is not lib.no_default
+
+    with pandasSQL_builder(con, schema=schema, need_transaction=True) as pandas_sql:
+        if not pandas_sql.has_table(table_name):
+            raise ValueError(f"Table {table_name} not found")
+
+        table = pandas_sql.read_table(
+            table_name,
+            index_col=index_col,
+            coerce_float=coerce_float,
+            parse_dates=parse_dates,
+            columns=columns,
+            chunksize=chunksize,
+            dtype_backend=dtype_backend,
+        )
+
+    if table is not None:
+        return table
+    else:
+        raise ValueError(f"Table {table_name} not found", con)
+
+
+@overload
+def read_sql_query(
+    sql,
+    con,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    params: list[Any] | Mapping[str, Any] | None = ...,
+    parse_dates: list[str] | dict[str, str] | None = ...,
+    chunksize: None = ...,
+    dtype: DtypeArg | None = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> DataFrame:
+    ...
+
+
+@overload
+def read_sql_query(
+    sql,
+    con,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    params: list[Any] | Mapping[str, Any] | None = ...,
+    parse_dates: list[str] | dict[str, str] | None = ...,
+    chunksize: int = ...,
+    dtype: DtypeArg | None = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+) -> Iterator[DataFrame]:
+    ...
+
+
+def read_sql_query(
+    sql,
+    con,
+    index_col: str | list[str] | None = None,
+    coerce_float: bool = True,
+    params: list[Any] | Mapping[str, Any] | None = None,
+    parse_dates: list[str] | dict[str, str] | None = None,
+    chunksize: int | None = None,
+    dtype: DtypeArg | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame | Iterator[DataFrame]:
+    """
+    Read SQL query into a DataFrame.
+
+    Returns a DataFrame corresponding to the result set of the query
+    string. Optionally provide an `index_col` parameter to use one of the
+    columns as the index, otherwise default integer index will be used.
+
+    Parameters
+    ----------
+    sql : str SQL query or SQLAlchemy Selectable (select or text object)
+        SQL query to be executed.
+    con : SQLAlchemy connectable, str, or sqlite3 connection
+        Using SQLAlchemy makes it possible to use any DB supported by that
+        library. If a DBAPI2 object, only sqlite3 is supported.
+    index_col : str or list of str, optional, default: None
+        Column(s) to set as index(MultiIndex).
+    coerce_float : bool, default True
+        Attempts to convert values of non-string, non-numeric objects (like
+        decimal.Decimal) to floating point. Useful for SQL result sets.
+    params : list, tuple or mapping, optional, default: None
+        List of parameters to pass to execute method.  The syntax used
+        to pass parameters is database driver dependent. Check your
+        database driver documentation for which of the five syntax styles,
+        described in PEP 249's paramstyle, is supported.
+        Eg. for psycopg2, uses %(name)s so use params={'name' : 'value'}.
+    parse_dates : list or dict, default: None
+        - List of column names to parse as dates.
+        - Dict of ``{column_name: format string}`` where format string is
+          strftime compatible in case of parsing string times, or is one of
+          (D, s, ns, ms, us) in case of parsing integer timestamps.
+        - Dict of ``{column_name: arg dict}``, where the arg dict corresponds
+          to the keyword arguments of :func:`pandas.to_datetime`
+          Especially useful with databases without native Datetime support,
+          such as SQLite.
+    chunksize : int, default None
+        If specified, return an iterator where `chunksize` is the number of
+        rows to include in each chunk.
+    dtype : Type name or dict of columns
+        Data type for data or columns. E.g. np.float64 or
+        {'a': np.float64, 'b': np.int32, 'c': 'Int64'}.
+
+        .. versionadded:: 1.3.0
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    DataFrame or Iterator[DataFrame]
+
+    See Also
+    --------
+    read_sql_table : Read SQL database table into a DataFrame.
+    read_sql : Read SQL query or database table into a DataFrame.
+
+    Notes
+    -----
+    Any datetime values with time zone information parsed via the `parse_dates`
+    parameter will be converted to UTC.
+
+    Examples
+    --------
+    >>> from sqlalchemy import create_engine  # doctest: +SKIP
+    >>> engine = create_engine("sqlite:///database.db")  # doctest: +SKIP
+    >>> with engine.connect() as conn, conn.begin():  # doctest: +SKIP
+    ...     data = pd.read_sql_table("data", conn)  # doctest: +SKIP
+    """
+
+    check_dtype_backend(dtype_backend)
+    if dtype_backend is lib.no_default:
+        dtype_backend = "numpy"  # type: ignore[assignment]
+    assert dtype_backend is not lib.no_default
+
+    with pandasSQL_builder(con) as pandas_sql:
+        return pandas_sql.read_query(
+            sql,
+            index_col=index_col,
+            params=params,
+            coerce_float=coerce_float,
+            parse_dates=parse_dates,
+            chunksize=chunksize,
+            dtype=dtype,
+            dtype_backend=dtype_backend,
+        )
+
+
+@overload
+def read_sql(
+    sql,
+    con,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    params=...,
+    parse_dates=...,
+    columns: list[str] = ...,
+    chunksize: None = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    dtype: DtypeArg | None = None,
+) -> DataFrame:
+    ...
+
+
+@overload
+def read_sql(
+    sql,
+    con,
+    index_col: str | list[str] | None = ...,
+    coerce_float=...,
+    params=...,
+    parse_dates=...,
+    columns: list[str] = ...,
+    chunksize: int = ...,
+    dtype_backend: DtypeBackend | lib.NoDefault = ...,
+    dtype: DtypeArg | None = None,
+) -> Iterator[DataFrame]:
+    ...
+
+
+def read_sql(
+    sql,
+    con,
+    index_col: str | list[str] | None = None,
+    coerce_float: bool = True,
+    params=None,
+    parse_dates=None,
+    columns: list[str] | None = None,
+    chunksize: int | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    dtype: DtypeArg | None = None,
+) -> DataFrame | Iterator[DataFrame]:
+    """
+    Read SQL query or database table into a DataFrame.
+
+    This function is a convenience wrapper around ``read_sql_table`` and
+    ``read_sql_query`` (for backward compatibility). It will delegate
+    to the specific function depending on the provided input. A SQL query
+    will be routed to ``read_sql_query``, while a database table name will
+    be routed to ``read_sql_table``. Note that the delegated function might
+    have more specific notes about their functionality not listed here.
+
+    Parameters
+    ----------
+    sql : str or SQLAlchemy Selectable (select or text object)
+        SQL query to be executed or a table name.
+    con : ADBC Connection, SQLAlchemy connectable, str, or sqlite3 connection
+        ADBC provides high performance I/O with native type support, where available.
+        Using SQLAlchemy makes it possible to use any DB supported by that
+        library. If a DBAPI2 object, only sqlite3 is supported. The user is responsible
+        for engine disposal and connection closure for the ADBC connection and
+        SQLAlchemy connectable; str connections are closed automatically. See
+        `here `_.
+    index_col : str or list of str, optional, default: None
+        Column(s) to set as index(MultiIndex).
+    coerce_float : bool, default True
+        Attempts to convert values of non-string, non-numeric objects (like
+        decimal.Decimal) to floating point, useful for SQL result sets.
+    params : list, tuple or dict, optional, default: None
+        List of parameters to pass to execute method.  The syntax used
+        to pass parameters is database driver dependent. Check your
+        database driver documentation for which of the five syntax styles,
+        described in PEP 249's paramstyle, is supported.
+        Eg. for psycopg2, uses %(name)s so use params={'name' : 'value'}.
+    parse_dates : list or dict, default: None
+        - List of column names to parse as dates.
+        - Dict of ``{column_name: format string}`` where format string is
+          strftime compatible in case of parsing string times, or is one of
+          (D, s, ns, ms, us) in case of parsing integer timestamps.
+        - Dict of ``{column_name: arg dict}``, where the arg dict corresponds
+          to the keyword arguments of :func:`pandas.to_datetime`
+          Especially useful with databases without native Datetime support,
+          such as SQLite.
+    columns : list, default: None
+        List of column names to select from SQL table (only used when reading
+        a table).
+    chunksize : int, default None
+        If specified, return an iterator where `chunksize` is the
+        number of rows to include in each chunk.
+    dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+    dtype : Type name or dict of columns
+        Data type for data or columns. E.g. np.float64 or
+        {'a': np.float64, 'b': np.int32, 'c': 'Int64'}.
+        The argument is ignored if a table is passed instead of a query.
+
+        .. versionadded:: 2.0.0
+
+    Returns
+    -------
+    DataFrame or Iterator[DataFrame]
+
+    See Also
+    --------
+    read_sql_table : Read SQL database table into a DataFrame.
+    read_sql_query : Read SQL query into a DataFrame.
+
+    Examples
+    --------
+    Read data from SQL via either a SQL query or a SQL tablename.
+    When using a SQLite database only SQL queries are accepted,
+    providing only the SQL tablename will result in an error.
+
+    >>> from sqlite3 import connect
+    >>> conn = connect(':memory:')
+    >>> df = pd.DataFrame(data=[[0, '10/11/12'], [1, '12/11/10']],
+    ...                   columns=['int_column', 'date_column'])
+    >>> df.to_sql(name='test_data', con=conn)
+    2
+
+    >>> pd.read_sql('SELECT int_column, date_column FROM test_data', conn)
+       int_column date_column
+    0           0    10/11/12
+    1           1    12/11/10
+
+    >>> pd.read_sql('test_data', 'postgres:///db_name')  # doctest:+SKIP
+
+    Apply date parsing to columns through the ``parse_dates`` argument
+    The ``parse_dates`` argument calls ``pd.to_datetime`` on the provided columns.
+    Custom argument values for applying ``pd.to_datetime`` on a column are specified
+    via a dictionary format:
+
+    >>> pd.read_sql('SELECT int_column, date_column FROM test_data',
+    ...             conn,
+    ...             parse_dates={"date_column": {"format": "%d/%m/%y"}})
+       int_column date_column
+    0           0  2012-11-10
+    1           1  2010-11-12
+
+    .. versionadded:: 2.2.0
+
+       pandas now supports reading via ADBC drivers
+
+    >>> from adbc_driver_postgresql import dbapi  # doctest:+SKIP
+    >>> with dbapi.connect('postgres:///db_name') as conn:  # doctest:+SKIP
+    ...     pd.read_sql('SELECT int_column FROM test_data', conn)
+       int_column
+    0           0
+    1           1
+    """
+
+    check_dtype_backend(dtype_backend)
+    if dtype_backend is lib.no_default:
+        dtype_backend = "numpy"  # type: ignore[assignment]
+    assert dtype_backend is not lib.no_default
+
+    with pandasSQL_builder(con) as pandas_sql:
+        if isinstance(pandas_sql, SQLiteDatabase):
+            return pandas_sql.read_query(
+                sql,
+                index_col=index_col,
+                params=params,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                chunksize=chunksize,
+                dtype_backend=dtype_backend,
+                dtype=dtype,
+            )
+
+        try:
+            _is_table_name = pandas_sql.has_table(sql)
+        except Exception:
+            # using generic exception to catch errors from sql drivers (GH24988)
+            _is_table_name = False
+
+        if _is_table_name:
+            return pandas_sql.read_table(
+                sql,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                columns=columns,
+                chunksize=chunksize,
+                dtype_backend=dtype_backend,
+            )
+        else:
+            return pandas_sql.read_query(
+                sql,
+                index_col=index_col,
+                params=params,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                chunksize=chunksize,
+                dtype_backend=dtype_backend,
+                dtype=dtype,
+            )
+
+
+def to_sql(
+    frame,
+    name: str,
+    con,
+    schema: str | None = None,
+    if_exists: Literal["fail", "replace", "append"] = "fail",
+    index: bool = True,
+    index_label: IndexLabel | None = None,
+    chunksize: int | None = None,
+    dtype: DtypeArg | None = None,
+    method: Literal["multi"] | Callable | None = None,
+    engine: str = "auto",
+    **engine_kwargs,
+) -> int | None:
+    """
+    Write records stored in a DataFrame to a SQL database.
+
+    Parameters
+    ----------
+    frame : DataFrame, Series
+    name : str
+        Name of SQL table.
+    con : ADBC Connection, SQLAlchemy connectable, str, or sqlite3 connection
+        or sqlite3 DBAPI2 connection
+        ADBC provides high performance I/O with native type support, where available.
+        Using SQLAlchemy makes it possible to use any DB supported by that
+        library.
+        If a DBAPI2 object, only sqlite3 is supported.
+    schema : str, optional
+        Name of SQL schema in database to write to (if database flavor
+        supports this). If None, use default schema (default).
+    if_exists : {'fail', 'replace', 'append'}, default 'fail'
+        - fail: If table exists, do nothing.
+        - replace: If table exists, drop it, recreate it, and insert data.
+        - append: If table exists, insert data. Create if does not exist.
+    index : bool, default True
+        Write DataFrame index as a column.
+    index_label : str or sequence, optional
+        Column label for index column(s). If None is given (default) and
+        `index` is True, then the index names are used.
+        A sequence should be given if the DataFrame uses MultiIndex.
+    chunksize : int, optional
+        Specify the number of rows in each batch to be written at a time.
+        By default, all rows will be written at once.
+    dtype : dict or scalar, optional
+        Specifying the datatype for columns. If a dictionary is used, the
+        keys should be the column names and the values should be the
+        SQLAlchemy types or strings for the sqlite3 fallback mode. If a
+        scalar is provided, it will be applied to all columns.
+    method : {None, 'multi', callable}, optional
+        Controls the SQL insertion clause used:
+
+        - None : Uses standard SQL ``INSERT`` clause (one per row).
+        - ``'multi'``: Pass multiple values in a single ``INSERT`` clause.
+        - callable with signature ``(pd_table, conn, keys, data_iter) -> int | None``.
+
+        Details and a sample callable implementation can be found in the
+        section :ref:`insert method `.
+    engine : {'auto', 'sqlalchemy'}, default 'auto'
+        SQL engine library to use. If 'auto', then the option
+        ``io.sql.engine`` is used. The default ``io.sql.engine``
+        behavior is 'sqlalchemy'
+
+        .. versionadded:: 1.3.0
+
+    **engine_kwargs
+        Any additional kwargs are passed to the engine.
+
+    Returns
+    -------
+    None or int
+        Number of rows affected by to_sql. None is returned if the callable
+        passed into ``method`` does not return an integer number of rows.
+
+        .. versionadded:: 1.4.0
+
+    Notes
+    -----
+    The returned rows affected is the sum of the ``rowcount`` attribute of ``sqlite3.Cursor``
+    or SQLAlchemy connectable. If using ADBC the returned rows are the result
+    of ``Cursor.adbc_ingest``. The returned value may not reflect the exact number of written
+    rows as stipulated in the
+    `sqlite3 `__ or
+    `SQLAlchemy `__
+    """  # noqa: E501
+    if if_exists not in ("fail", "replace", "append"):
+        raise ValueError(f"'{if_exists}' is not valid for if_exists")
+
+    if isinstance(frame, Series):
+        frame = frame.to_frame()
+    elif not isinstance(frame, DataFrame):
+        raise NotImplementedError(
+            "'frame' argument should be either a Series or a DataFrame"
+        )
+
+    with pandasSQL_builder(con, schema=schema, need_transaction=True) as pandas_sql:
+        return pandas_sql.to_sql(
+            frame,
+            name,
+            if_exists=if_exists,
+            index=index,
+            index_label=index_label,
+            schema=schema,
+            chunksize=chunksize,
+            dtype=dtype,
+            method=method,
+            engine=engine,
+            **engine_kwargs,
+        )
+
+
+def has_table(table_name: str, con, schema: str | None = None) -> bool:
+    """
+    Check if DataBase has named table.
+
+    Parameters
+    ----------
+    table_name: string
+        Name of SQL table.
+    con: ADBC Connection, SQLAlchemy connectable, str, or sqlite3 connection
+        ADBC provides high performance I/O with native type support, where available.
+        Using SQLAlchemy makes it possible to use any DB supported by that
+        library.
+        If a DBAPI2 object, only sqlite3 is supported.
+    schema : string, default None
+        Name of SQL schema in database to write to (if database flavor supports
+        this). If None, use default schema (default).
+
+    Returns
+    -------
+    boolean
+    """
+    with pandasSQL_builder(con, schema=schema) as pandas_sql:
+        return pandas_sql.has_table(table_name)
+
+
+table_exists = has_table
+
+
+def pandasSQL_builder(
+    con,
+    schema: str | None = None,
+    need_transaction: bool = False,
+) -> PandasSQL:
+    """
+    Convenience function to return the correct PandasSQL subclass based on the
+    provided parameters.  Also creates a sqlalchemy connection and transaction
+    if necessary.
+    """
+    import sqlite3
+
+    if isinstance(con, sqlite3.Connection) or con is None:
+        return SQLiteDatabase(con)
+
+    sqlalchemy = import_optional_dependency("sqlalchemy", errors="ignore")
+
+    if isinstance(con, str) and sqlalchemy is None:
+        raise ImportError("Using URI string without sqlalchemy installed.")
+
+    if sqlalchemy is not None and isinstance(con, (str, sqlalchemy.engine.Connectable)):
+        return SQLDatabase(con, schema, need_transaction)
+
+    adbc = import_optional_dependency("adbc_driver_manager.dbapi", errors="ignore")
+    if adbc and isinstance(con, adbc.Connection):
+        return ADBCDatabase(con)
+
+    warnings.warn(
+        "pandas only supports SQLAlchemy connectable (engine/connection) or "
+        "database string URI or sqlite3 DBAPI2 connection. Other DBAPI2 "
+        "objects are not tested. Please consider using SQLAlchemy.",
+        UserWarning,
+        stacklevel=find_stack_level(),
+    )
+    return SQLiteDatabase(con)
+
+
+class SQLTable(PandasObject):
+    """
+    For mapping Pandas tables to SQL tables.
+    Uses fact that table is reflected by SQLAlchemy to
+    do better type conversions.
+    Also holds various flags needed to avoid having to
+    pass them between functions all the time.
+    """
+
+    # TODO: support for multiIndex
+
+    def __init__(
+        self,
+        name: str,
+        pandas_sql_engine,
+        frame=None,
+        index: bool | str | list[str] | None = True,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        prefix: str = "pandas",
+        index_label=None,
+        schema=None,
+        keys=None,
+        dtype: DtypeArg | None = None,
+    ) -> None:
+        self.name = name
+        self.pd_sql = pandas_sql_engine
+        self.prefix = prefix
+        self.frame = frame
+        self.index = self._index_name(index, index_label)
+        self.schema = schema
+        self.if_exists = if_exists
+        self.keys = keys
+        self.dtype = dtype
+
+        if frame is not None:
+            # We want to initialize based on a dataframe
+            self.table = self._create_table_setup()
+        else:
+            # no data provided, read-only mode
+            self.table = self.pd_sql.get_table(self.name, self.schema)
+
+        if self.table is None:
+            raise ValueError(f"Could not init table '{name}'")
+
+        if not len(self.name):
+            raise ValueError("Empty table name specified")
+
+    def exists(self):
+        return self.pd_sql.has_table(self.name, self.schema)
+
+    def sql_schema(self) -> str:
+        from sqlalchemy.schema import CreateTable
+
+        return str(CreateTable(self.table).compile(self.pd_sql.con))
+
+    def _execute_create(self) -> None:
+        # Inserting table into database, add to MetaData object
+        self.table = self.table.to_metadata(self.pd_sql.meta)
+        with self.pd_sql.run_transaction():
+            self.table.create(bind=self.pd_sql.con)
+
+    def create(self) -> None:
+        if self.exists():
+            if self.if_exists == "fail":
+                raise ValueError(f"Table '{self.name}' already exists.")
+            if self.if_exists == "replace":
+                self.pd_sql.drop_table(self.name, self.schema)
+                self._execute_create()
+            elif self.if_exists == "append":
+                pass
+            else:
+                raise ValueError(f"'{self.if_exists}' is not valid for if_exists")
+        else:
+            self._execute_create()
+
+    def _execute_insert(self, conn, keys: list[str], data_iter) -> int:
+        """
+        Execute SQL statement inserting data
+
+        Parameters
+        ----------
+        conn : sqlalchemy.engine.Engine or sqlalchemy.engine.Connection
+        keys : list of str
+           Column names
+        data_iter : generator of list
+           Each item contains a list of values to be inserted
+        """
+        data = [dict(zip(keys, row)) for row in data_iter]
+        result = conn.execute(self.table.insert(), data)
+        return result.rowcount
+
+    def _execute_insert_multi(self, conn, keys: list[str], data_iter) -> int:
+        """
+        Alternative to _execute_insert for DBs support multi-value INSERT.
+
+        Note: multi-value insert is usually faster for analytics DBs
+        and tables containing a few columns
+        but performance degrades quickly with increase of columns.
+
+        """
+
+        from sqlalchemy import insert
+
+        data = [dict(zip(keys, row)) for row in data_iter]
+        stmt = insert(self.table).values(data)
+        result = conn.execute(stmt)
+        return result.rowcount
+
+    def insert_data(self) -> tuple[list[str], list[np.ndarray]]:
+        if self.index is not None:
+            temp = self.frame.copy()
+            temp.index.names = self.index
+            try:
+                temp.reset_index(inplace=True)
+            except ValueError as err:
+                raise ValueError(f"duplicate name in index/columns: {err}") from err
+        else:
+            temp = self.frame
+
+        column_names = list(map(str, temp.columns))
+        ncols = len(column_names)
+        # this just pre-allocates the list: None's will be replaced with ndarrays
+        # error: List item 0 has incompatible type "None"; expected "ndarray"
+        data_list: list[np.ndarray] = [None] * ncols  # type: ignore[list-item]
+
+        for i, (_, ser) in enumerate(temp.items()):
+            if ser.dtype.kind == "M":
+                if isinstance(ser._values, ArrowExtensionArray):
+                    import pyarrow as pa
+
+                    if pa.types.is_date(ser.dtype.pyarrow_dtype):
+                        # GH#53854 to_pydatetime not supported for pyarrow date dtypes
+                        d = ser._values.to_numpy(dtype=object)
+                    else:
+                        with warnings.catch_warnings():
+                            warnings.filterwarnings("ignore", category=FutureWarning)
+                            # GH#52459 to_pydatetime will return Index[object]
+                            d = np.asarray(ser.dt.to_pydatetime(), dtype=object)
+                else:
+                    d = ser._values.to_pydatetime()
+            elif ser.dtype.kind == "m":
+                vals = ser._values
+                if isinstance(vals, ArrowExtensionArray):
+                    vals = vals.to_numpy(dtype=np.dtype("m8[ns]"))
+                # store as integers, see GH#6921, GH#7076
+                d = vals.view("i8").astype(object)
+            else:
+                d = ser._values.astype(object)
+
+            assert isinstance(d, np.ndarray), type(d)
+
+            if ser._can_hold_na:
+                # Note: this will miss timedeltas since they are converted to int
+                mask = isna(d)
+                d[mask] = None
+
+            data_list[i] = d
+
+        return column_names, data_list
+
+    def insert(
+        self,
+        chunksize: int | None = None,
+        method: Literal["multi"] | Callable | None = None,
+    ) -> int | None:
+        # set insert method
+        if method is None:
+            exec_insert = self._execute_insert
+        elif method == "multi":
+            exec_insert = self._execute_insert_multi
+        elif callable(method):
+            exec_insert = partial(method, self)
+        else:
+            raise ValueError(f"Invalid parameter `method`: {method}")
+
+        keys, data_list = self.insert_data()
+
+        nrows = len(self.frame)
+
+        if nrows == 0:
+            return 0
+
+        if chunksize is None:
+            chunksize = nrows
+        elif chunksize == 0:
+            raise ValueError("chunksize argument should be non-zero")
+
+        chunks = (nrows // chunksize) + 1
+        total_inserted = None
+        with self.pd_sql.run_transaction() as conn:
+            for i in range(chunks):
+                start_i = i * chunksize
+                end_i = min((i + 1) * chunksize, nrows)
+                if start_i >= end_i:
+                    break
+
+                chunk_iter = zip(*(arr[start_i:end_i] for arr in data_list))
+                num_inserted = exec_insert(conn, keys, chunk_iter)
+                # GH 46891
+                if num_inserted is not None:
+                    if total_inserted is None:
+                        total_inserted = num_inserted
+                    else:
+                        total_inserted += num_inserted
+        return total_inserted
+
+    def _query_iterator(
+        self,
+        result,
+        exit_stack: ExitStack,
+        chunksize: int | None,
+        columns,
+        coerce_float: bool = True,
+        parse_dates=None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ):
+        """Return generator through chunked result set."""
+        has_read_data = False
+        with exit_stack:
+            while True:
+                data = result.fetchmany(chunksize)
+                if not data:
+                    if not has_read_data:
+                        yield DataFrame.from_records(
+                            [], columns=columns, coerce_float=coerce_float
+                        )
+                    break
+
+                has_read_data = True
+                self.frame = _convert_arrays_to_dataframe(
+                    data, columns, coerce_float, dtype_backend
+                )
+
+                self._harmonize_columns(
+                    parse_dates=parse_dates, dtype_backend=dtype_backend
+                )
+
+                if self.index is not None:
+                    self.frame.set_index(self.index, inplace=True)
+
+                yield self.frame
+
+    def read(
+        self,
+        exit_stack: ExitStack,
+        coerce_float: bool = True,
+        parse_dates=None,
+        columns=None,
+        chunksize: int | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        from sqlalchemy import select
+
+        if columns is not None and len(columns) > 0:
+            cols = [self.table.c[n] for n in columns]
+            if self.index is not None:
+                for idx in self.index[::-1]:
+                    cols.insert(0, self.table.c[idx])
+            sql_select = select(*cols)
+        else:
+            sql_select = select(self.table)
+        result = self.pd_sql.execute(sql_select)
+        column_names = result.keys()
+
+        if chunksize is not None:
+            return self._query_iterator(
+                result,
+                exit_stack,
+                chunksize,
+                column_names,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype_backend=dtype_backend,
+            )
+        else:
+            data = result.fetchall()
+            self.frame = _convert_arrays_to_dataframe(
+                data, column_names, coerce_float, dtype_backend
+            )
+
+            self._harmonize_columns(
+                parse_dates=parse_dates, dtype_backend=dtype_backend
+            )
+
+            if self.index is not None:
+                self.frame.set_index(self.index, inplace=True)
+
+            return self.frame
+
+    def _index_name(self, index, index_label):
+        # for writing: index=True to include index in sql table
+        if index is True:
+            nlevels = self.frame.index.nlevels
+            # if index_label is specified, set this as index name(s)
+            if index_label is not None:
+                if not isinstance(index_label, list):
+                    index_label = [index_label]
+                if len(index_label) != nlevels:
+                    raise ValueError(
+                        "Length of 'index_label' should match number of "
+                        f"levels, which is {nlevels}"
+                    )
+                return index_label
+            # return the used column labels for the index columns
+            if (
+                nlevels == 1
+                and "index" not in self.frame.columns
+                and self.frame.index.name is None
+            ):
+                return ["index"]
+            else:
+                return com.fill_missing_names(self.frame.index.names)
+
+        # for reading: index=(list of) string to specify column to set as index
+        elif isinstance(index, str):
+            return [index]
+        elif isinstance(index, list):
+            return index
+        else:
+            return None
+
+    def _get_column_names_and_types(self, dtype_mapper):
+        column_names_and_types = []
+        if self.index is not None:
+            for i, idx_label in enumerate(self.index):
+                idx_type = dtype_mapper(self.frame.index._get_level_values(i))
+                column_names_and_types.append((str(idx_label), idx_type, True))
+
+        column_names_and_types += [
+            (str(self.frame.columns[i]), dtype_mapper(self.frame.iloc[:, i]), False)
+            for i in range(len(self.frame.columns))
+        ]
+
+        return column_names_and_types
+
+    def _create_table_setup(self):
+        from sqlalchemy import (
+            Column,
+            PrimaryKeyConstraint,
+            Table,
+        )
+        from sqlalchemy.schema import MetaData
+
+        column_names_and_types = self._get_column_names_and_types(self._sqlalchemy_type)
+
+        columns: list[Any] = [
+            Column(name, typ, index=is_index)
+            for name, typ, is_index in column_names_and_types
+        ]
+
+        if self.keys is not None:
+            if not is_list_like(self.keys):
+                keys = [self.keys]
+            else:
+                keys = self.keys
+            pkc = PrimaryKeyConstraint(*keys, name=self.name + "_pk")
+            columns.append(pkc)
+
+        schema = self.schema or self.pd_sql.meta.schema
+
+        # At this point, attach to new metadata, only attach to self.meta
+        # once table is created.
+        meta = MetaData()
+        return Table(self.name, meta, *columns, schema=schema)
+
+    def _harmonize_columns(
+        self,
+        parse_dates=None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> None:
+        """
+        Make the DataFrame's column types align with the SQL table
+        column types.
+        Need to work around limited NA value support. Floats are always
+        fine, ints must always be floats if there are Null values.
+        Booleans are hard because converting bool column with None replaces
+        all Nones with false. Therefore only convert bool if there are no
+        NA values.
+        Datetimes should already be converted to np.datetime64 if supported,
+        but here we also force conversion if required.
+        """
+        parse_dates = _process_parse_dates_argument(parse_dates)
+
+        for sql_col in self.table.columns:
+            col_name = sql_col.name
+            try:
+                df_col = self.frame[col_name]
+
+                # Handle date parsing upfront; don't try to convert columns
+                # twice
+                if col_name in parse_dates:
+                    try:
+                        fmt = parse_dates[col_name]
+                    except TypeError:
+                        fmt = None
+                    self.frame[col_name] = _handle_date_column(df_col, format=fmt)
+                    continue
+
+                # the type the dataframe column should have
+                col_type = self._get_dtype(sql_col.type)
+
+                if (
+                    col_type is datetime
+                    or col_type is date
+                    or col_type is DatetimeTZDtype
+                ):
+                    # Convert tz-aware Datetime SQL columns to UTC
+                    utc = col_type is DatetimeTZDtype
+                    self.frame[col_name] = _handle_date_column(df_col, utc=utc)
+                elif dtype_backend == "numpy" and col_type is float:
+                    # floats support NA, can always convert!
+                    self.frame[col_name] = df_col.astype(col_type, copy=False)
+                elif (
+                    using_string_dtype()
+                    and is_string_dtype(col_type)
+                    and is_object_dtype(self.frame[col_name])
+                ):
+                    self.frame[col_name] = df_col.astype(col_type, copy=False)
+                elif dtype_backend == "numpy" and len(df_col) == df_col.count():
+                    # No NA values, can convert ints and bools
+                    if col_type is np.dtype("int64") or col_type is bool:
+                        self.frame[col_name] = df_col.astype(col_type, copy=False)
+            except KeyError:
+                pass  # this column not in results
+
+    def _sqlalchemy_type(self, col: Index | Series):
+        dtype: DtypeArg = self.dtype or {}
+        if is_dict_like(dtype):
+            dtype = cast(dict, dtype)
+            if col.name in dtype:
+                return dtype[col.name]
+
+        # Infer type of column, while ignoring missing values.
+        # Needed for inserting typed data containing NULLs, GH 8778.
+        col_type = lib.infer_dtype(col, skipna=True)
+
+        from sqlalchemy.types import (
+            TIMESTAMP,
+            BigInteger,
+            Boolean,
+            Date,
+            DateTime,
+            Float,
+            Integer,
+            SmallInteger,
+            Text,
+            Time,
+        )
+
+        if col_type in ("datetime64", "datetime"):
+            # GH 9086: TIMESTAMP is the suggested type if the column contains
+            # timezone information
+            try:
+                # error: Item "Index" of "Union[Index, Series]" has no attribute "dt"
+                if col.dt.tz is not None:  # type: ignore[union-attr]
+                    return TIMESTAMP(timezone=True)
+            except AttributeError:
+                # The column is actually a DatetimeIndex
+                # GH 26761 or an Index with date-like data e.g. 9999-01-01
+                if getattr(col, "tz", None) is not None:
+                    return TIMESTAMP(timezone=True)
+            return DateTime
+        if col_type == "timedelta64":
+            warnings.warn(
+                "the 'timedelta' type is not supported, and will be "
+                "written as integer values (ns frequency) to the database.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+            return BigInteger
+        elif col_type == "floating":
+            if col.dtype == "float32":
+                return Float(precision=23)
+            else:
+                return Float(precision=53)
+        elif col_type == "integer":
+            # GH35076 Map pandas integer to optimal SQLAlchemy integer type
+            if col.dtype.name.lower() in ("int8", "uint8", "int16"):
+                return SmallInteger
+            elif col.dtype.name.lower() in ("uint16", "int32"):
+                return Integer
+            elif col.dtype.name.lower() == "uint64":
+                raise ValueError("Unsigned 64 bit integer datatype is not supported")
+            else:
+                return BigInteger
+        elif col_type == "boolean":
+            return Boolean
+        elif col_type == "date":
+            return Date
+        elif col_type == "time":
+            return Time
+        elif col_type == "complex":
+            raise ValueError("Complex datatypes not supported")
+
+        return Text
+
+    def _get_dtype(self, sqltype):
+        from sqlalchemy.types import (
+            TIMESTAMP,
+            Boolean,
+            Date,
+            DateTime,
+            Float,
+            Integer,
+            String,
+        )
+
+        if isinstance(sqltype, Float):
+            return float
+        elif isinstance(sqltype, Integer):
+            # TODO: Refine integer size.
+            return np.dtype("int64")
+        elif isinstance(sqltype, TIMESTAMP):
+            # we have a timezone capable type
+            if not sqltype.timezone:
+                return datetime
+            return DatetimeTZDtype
+        elif isinstance(sqltype, DateTime):
+            # Caution: np.datetime64 is also a subclass of np.number.
+            return datetime
+        elif isinstance(sqltype, Date):
+            return date
+        elif isinstance(sqltype, Boolean):
+            return bool
+        elif isinstance(sqltype, String):
+            if using_string_dtype():
+                return StringDtype(na_value=np.nan)
+
+        return object
+
+
+class PandasSQL(PandasObject, ABC):
+    """
+    Subclasses Should define read_query and to_sql.
+    """
+
+    def __enter__(self) -> Self:
+        return self
+
+    def __exit__(self, *args) -> None:
+        pass
+
+    def read_table(
+        self,
+        table_name: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        columns=None,
+        schema: str | None = None,
+        chunksize: int | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        raise NotImplementedError
+
+    @abstractmethod
+    def read_query(
+        self,
+        sql: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        params=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        pass
+
+    @abstractmethod
+    def to_sql(
+        self,
+        frame,
+        name: str,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        index: bool = True,
+        index_label=None,
+        schema=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        method: Literal["multi"] | Callable | None = None,
+        engine: str = "auto",
+        **engine_kwargs,
+    ) -> int | None:
+        pass
+
+    @abstractmethod
+    def execute(self, sql: str | Select | TextClause, params=None):
+        pass
+
+    @abstractmethod
+    def has_table(self, name: str, schema: str | None = None) -> bool:
+        pass
+
+    @abstractmethod
+    def _create_sql_schema(
+        self,
+        frame: DataFrame,
+        table_name: str,
+        keys: list[str] | None = None,
+        dtype: DtypeArg | None = None,
+        schema: str | None = None,
+    ) -> str:
+        pass
+
+
+class BaseEngine:
+    def insert_records(
+        self,
+        table: SQLTable,
+        con,
+        frame,
+        name: str,
+        index: bool | str | list[str] | None = True,
+        schema=None,
+        chunksize: int | None = None,
+        method=None,
+        **engine_kwargs,
+    ) -> int | None:
+        """
+        Inserts data into already-prepared table
+        """
+        raise AbstractMethodError(self)
+
+
+class SQLAlchemyEngine(BaseEngine):
+    def __init__(self) -> None:
+        import_optional_dependency(
+            "sqlalchemy", extra="sqlalchemy is required for SQL support."
+        )
+
+    def insert_records(
+        self,
+        table: SQLTable,
+        con,
+        frame,
+        name: str,
+        index: bool | str | list[str] | None = True,
+        schema=None,
+        chunksize: int | None = None,
+        method=None,
+        **engine_kwargs,
+    ) -> int | None:
+        from sqlalchemy import exc
+
+        try:
+            return table.insert(chunksize=chunksize, method=method)
+        except exc.StatementError as err:
+            # GH34431
+            # https://stackoverflow.com/a/67358288/6067848
+            msg = r"""(\(1054, "Unknown column 'inf(e0)?' in 'field list'"\))(?#
+            )|inf can not be used with MySQL"""
+            err_text = str(err.orig)
+            if re.search(msg, err_text):
+                raise ValueError("inf cannot be used with MySQL") from err
+            raise err
+
+
+def get_engine(engine: str) -> BaseEngine:
+    """return our implementation"""
+    if engine == "auto":
+        engine = get_option("io.sql.engine")
+
+    if engine == "auto":
+        # try engines in this order
+        engine_classes = [SQLAlchemyEngine]
+
+        error_msgs = ""
+        for engine_class in engine_classes:
+            try:
+                return engine_class()
+            except ImportError as err:
+                error_msgs += "\n - " + str(err)
+
+        raise ImportError(
+            "Unable to find a usable engine; "
+            "tried using: 'sqlalchemy'.\n"
+            "A suitable version of "
+            "sqlalchemy is required for sql I/O "
+            "support.\n"
+            "Trying to import the above resulted in these errors:"
+            f"{error_msgs}"
+        )
+
+    if engine == "sqlalchemy":
+        return SQLAlchemyEngine()
+
+    raise ValueError("engine must be one of 'auto', 'sqlalchemy'")
+
+
+class SQLDatabase(PandasSQL):
+    """
+    This class enables conversion between DataFrame and SQL databases
+    using SQLAlchemy to handle DataBase abstraction.
+
+    Parameters
+    ----------
+    con : SQLAlchemy Connectable or URI string.
+        Connectable to connect with the database. Using SQLAlchemy makes it
+        possible to use any DB supported by that library.
+    schema : string, default None
+        Name of SQL schema in database to write to (if database flavor
+        supports this). If None, use default schema (default).
+    need_transaction : bool, default False
+        If True, SQLDatabase will create a transaction.
+
+    """
+
+    def __init__(
+        self, con, schema: str | None = None, need_transaction: bool = False
+    ) -> None:
+        from sqlalchemy import create_engine
+        from sqlalchemy.engine import Engine
+        from sqlalchemy.schema import MetaData
+
+        # self.exit_stack cleans up the Engine and Connection and commits the
+        # transaction if any of those objects was created below.
+        # Cleanup happens either in self.__exit__ or at the end of the iterator
+        # returned by read_sql when chunksize is not None.
+        self.exit_stack = ExitStack()
+        if isinstance(con, str):
+            con = create_engine(con)
+            self.exit_stack.callback(con.dispose)
+        if isinstance(con, Engine):
+            con = self.exit_stack.enter_context(con.connect())
+        if need_transaction and not con.in_transaction():
+            self.exit_stack.enter_context(con.begin())
+        self.con = con
+        self.meta = MetaData(schema=schema)
+        self.returns_generator = False
+
+    def __exit__(self, *args) -> None:
+        if not self.returns_generator:
+            self.exit_stack.close()
+
+    @contextmanager
+    def run_transaction(self):
+        if not self.con.in_transaction():
+            with self.con.begin():
+                yield self.con
+        else:
+            yield self.con
+
+    def execute(self, sql: str | Select | TextClause, params=None):
+        """Simple passthrough to SQLAlchemy connectable"""
+        args = [] if params is None else [params]
+        if isinstance(sql, str):
+            return self.con.exec_driver_sql(sql, *args)
+        return self.con.execute(sql, *args)
+
+    def read_table(
+        self,
+        table_name: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        columns=None,
+        schema: str | None = None,
+        chunksize: int | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        """
+        Read SQL database table into a DataFrame.
+
+        Parameters
+        ----------
+        table_name : str
+            Name of SQL table in database.
+        index_col : string, optional, default: None
+            Column to set as index.
+        coerce_float : bool, default True
+            Attempts to convert values of non-string, non-numeric objects
+            (like decimal.Decimal) to floating point. This can result in
+            loss of precision.
+        parse_dates : list or dict, default: None
+            - List of column names to parse as dates.
+            - Dict of ``{column_name: format string}`` where format string is
+              strftime compatible in case of parsing string times, or is one of
+              (D, s, ns, ms, us) in case of parsing integer timestamps.
+            - Dict of ``{column_name: arg}``, where the arg corresponds
+              to the keyword arguments of :func:`pandas.to_datetime`.
+              Especially useful with databases without native Datetime support,
+              such as SQLite.
+        columns : list, default: None
+            List of column names to select from SQL table.
+        schema : string, default None
+            Name of SQL schema in database to query (if database flavor
+            supports this).  If specified, this overwrites the default
+            schema of the SQL database object.
+        chunksize : int, default None
+            If specified, return an iterator where `chunksize` is the number
+            of rows to include in each chunk.
+        dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+            Back-end data type applied to the resultant :class:`DataFrame`
+            (still experimental). Behaviour is as follows:
+
+            * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+              (default).
+            * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+              DataFrame.
+
+            .. versionadded:: 2.0
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        pandas.read_sql_table
+        SQLDatabase.read_query
+
+        """
+        self.meta.reflect(bind=self.con, only=[table_name], views=True)
+        table = SQLTable(table_name, self, index=index_col, schema=schema)
+        if chunksize is not None:
+            self.returns_generator = True
+        return table.read(
+            self.exit_stack,
+            coerce_float=coerce_float,
+            parse_dates=parse_dates,
+            columns=columns,
+            chunksize=chunksize,
+            dtype_backend=dtype_backend,
+        )
+
+    @staticmethod
+    def _query_iterator(
+        result,
+        exit_stack: ExitStack,
+        chunksize: int,
+        columns,
+        index_col=None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ):
+        """Return generator through chunked result set"""
+        has_read_data = False
+        with exit_stack:
+            while True:
+                data = result.fetchmany(chunksize)
+                if not data:
+                    if not has_read_data:
+                        yield _wrap_result(
+                            [],
+                            columns,
+                            index_col=index_col,
+                            coerce_float=coerce_float,
+                            parse_dates=parse_dates,
+                            dtype=dtype,
+                            dtype_backend=dtype_backend,
+                        )
+                    break
+
+                has_read_data = True
+                yield _wrap_result(
+                    data,
+                    columns,
+                    index_col=index_col,
+                    coerce_float=coerce_float,
+                    parse_dates=parse_dates,
+                    dtype=dtype,
+                    dtype_backend=dtype_backend,
+                )
+
+    def read_query(
+        self,
+        sql: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        params=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        """
+        Read SQL query into a DataFrame.
+
+        Parameters
+        ----------
+        sql : str
+            SQL query to be executed.
+        index_col : string, optional, default: None
+            Column name to use as index for the returned DataFrame object.
+        coerce_float : bool, default True
+            Attempt to convert values of non-string, non-numeric objects (like
+            decimal.Decimal) to floating point, useful for SQL result sets.
+        params : list, tuple or dict, optional, default: None
+            List of parameters to pass to execute method.  The syntax used
+            to pass parameters is database driver dependent. Check your
+            database driver documentation for which of the five syntax styles,
+            described in PEP 249's paramstyle, is supported.
+            Eg. for psycopg2, uses %(name)s so use params={'name' : 'value'}
+        parse_dates : list or dict, default: None
+            - List of column names to parse as dates.
+            - Dict of ``{column_name: format string}`` where format string is
+              strftime compatible in case of parsing string times, or is one of
+              (D, s, ns, ms, us) in case of parsing integer timestamps.
+            - Dict of ``{column_name: arg dict}``, where the arg dict
+              corresponds to the keyword arguments of
+              :func:`pandas.to_datetime` Especially useful with databases
+              without native Datetime support, such as SQLite.
+        chunksize : int, default None
+            If specified, return an iterator where `chunksize` is the number
+            of rows to include in each chunk.
+        dtype : Type name or dict of columns
+            Data type for data or columns. E.g. np.float64 or
+            {'a': np.float64, 'b': np.int32, 'c': 'Int64'}
+
+            .. versionadded:: 1.3.0
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        read_sql_table : Read SQL database table into a DataFrame.
+        read_sql
+
+        """
+        result = self.execute(sql, params)
+        columns = result.keys()
+
+        if chunksize is not None:
+            self.returns_generator = True
+            return self._query_iterator(
+                result,
+                self.exit_stack,
+                chunksize,
+                columns,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype=dtype,
+                dtype_backend=dtype_backend,
+            )
+        else:
+            data = result.fetchall()
+            frame = _wrap_result(
+                data,
+                columns,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype=dtype,
+                dtype_backend=dtype_backend,
+            )
+            return frame
+
+    read_sql = read_query
+
+    def prep_table(
+        self,
+        frame,
+        name: str,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        index: bool | str | list[str] | None = True,
+        index_label=None,
+        schema=None,
+        dtype: DtypeArg | None = None,
+    ) -> SQLTable:
+        """
+        Prepares table in the database for data insertion. Creates it if needed, etc.
+        """
+        if dtype:
+            if not is_dict_like(dtype):
+                # error: Value expression in dictionary comprehension has incompatible
+                # type "Union[ExtensionDtype, str, dtype[Any], Type[object],
+                # Dict[Hashable, Union[ExtensionDtype, Union[str, dtype[Any]],
+                # Type[str], Type[float], Type[int], Type[complex], Type[bool],
+                # Type[object]]]]"; expected type "Union[ExtensionDtype, str,
+                # dtype[Any], Type[object]]"
+                dtype = {col_name: dtype for col_name in frame}  # type: ignore[misc]
+            else:
+                dtype = cast(dict, dtype)
+
+            from sqlalchemy.types import TypeEngine
+
+            for col, my_type in dtype.items():
+                if isinstance(my_type, type) and issubclass(my_type, TypeEngine):
+                    pass
+                elif isinstance(my_type, TypeEngine):
+                    pass
+                else:
+                    raise ValueError(f"The type of {col} is not a SQLAlchemy type")
+
+        table = SQLTable(
+            name,
+            self,
+            frame=frame,
+            index=index,
+            if_exists=if_exists,
+            index_label=index_label,
+            schema=schema,
+            dtype=dtype,
+        )
+        table.create()
+        return table
+
+    def check_case_sensitive(
+        self,
+        name: str,
+        schema: str | None,
+    ) -> None:
+        """
+        Checks table name for issues with case-sensitivity.
+        Method is called after data is inserted.
+        """
+        if not name.isdigit() and not name.islower():
+            # check for potentially case sensitivity issues (GH7815)
+            # Only check when name is not a number and name is not lower case
+            from sqlalchemy import inspect as sqlalchemy_inspect
+
+            insp = sqlalchemy_inspect(self.con)
+            table_names = insp.get_table_names(schema=schema or self.meta.schema)
+            if name not in table_names:
+                msg = (
+                    f"The provided table name '{name}' is not found exactly as "
+                    "such in the database after writing the table, possibly "
+                    "due to case sensitivity issues. Consider using lower "
+                    "case table names."
+                )
+                warnings.warn(
+                    msg,
+                    UserWarning,
+                    stacklevel=find_stack_level(),
+                )
+
+    def to_sql(
+        self,
+        frame,
+        name: str,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        index: bool = True,
+        index_label=None,
+        schema: str | None = None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        method: Literal["multi"] | Callable | None = None,
+        engine: str = "auto",
+        **engine_kwargs,
+    ) -> int | None:
+        """
+        Write records stored in a DataFrame to a SQL database.
+
+        Parameters
+        ----------
+        frame : DataFrame
+        name : string
+            Name of SQL table.
+        if_exists : {'fail', 'replace', 'append'}, default 'fail'
+            - fail: If table exists, do nothing.
+            - replace: If table exists, drop it, recreate it, and insert data.
+            - append: If table exists, insert data. Create if does not exist.
+        index : boolean, default True
+            Write DataFrame index as a column.
+        index_label : string or sequence, default None
+            Column label for index column(s). If None is given (default) and
+            `index` is True, then the index names are used.
+            A sequence should be given if the DataFrame uses MultiIndex.
+        schema : string, default None
+            Name of SQL schema in database to write to (if database flavor
+            supports this). If specified, this overwrites the default
+            schema of the SQLDatabase object.
+        chunksize : int, default None
+            If not None, then rows will be written in batches of this size at a
+            time.  If None, all rows will be written at once.
+        dtype : single type or dict of column name to SQL type, default None
+            Optional specifying the datatype for columns. The SQL type should
+            be a SQLAlchemy type. If all columns are of the same type, one
+            single value can be used.
+        method : {None', 'multi', callable}, default None
+            Controls the SQL insertion clause used:
+
+            * None : Uses standard SQL ``INSERT`` clause (one per row).
+            * 'multi': Pass multiple values in a single ``INSERT`` clause.
+            * callable with signature ``(pd_table, conn, keys, data_iter)``.
+
+            Details and a sample callable implementation can be found in the
+            section :ref:`insert method `.
+        engine : {'auto', 'sqlalchemy'}, default 'auto'
+            SQL engine library to use. If 'auto', then the option
+            ``io.sql.engine`` is used. The default ``io.sql.engine``
+            behavior is 'sqlalchemy'
+
+            .. versionadded:: 1.3.0
+
+        **engine_kwargs
+            Any additional kwargs are passed to the engine.
+        """
+        sql_engine = get_engine(engine)
+
+        table = self.prep_table(
+            frame=frame,
+            name=name,
+            if_exists=if_exists,
+            index=index,
+            index_label=index_label,
+            schema=schema,
+            dtype=dtype,
+        )
+
+        total_inserted = sql_engine.insert_records(
+            table=table,
+            con=self.con,
+            frame=frame,
+            name=name,
+            index=index,
+            schema=schema,
+            chunksize=chunksize,
+            method=method,
+            **engine_kwargs,
+        )
+
+        self.check_case_sensitive(name=name, schema=schema)
+        return total_inserted
+
+    @property
+    def tables(self):
+        return self.meta.tables
+
+    def has_table(self, name: str, schema: str | None = None) -> bool:
+        from sqlalchemy import inspect as sqlalchemy_inspect
+
+        insp = sqlalchemy_inspect(self.con)
+        return insp.has_table(name, schema or self.meta.schema)
+
+    def get_table(self, table_name: str, schema: str | None = None) -> Table:
+        from sqlalchemy import (
+            Numeric,
+            Table,
+        )
+
+        schema = schema or self.meta.schema
+        tbl = Table(table_name, self.meta, autoload_with=self.con, schema=schema)
+        for column in tbl.columns:
+            if isinstance(column.type, Numeric):
+                column.type.asdecimal = False
+        return tbl
+
+    def drop_table(self, table_name: str, schema: str | None = None) -> None:
+        schema = schema or self.meta.schema
+        if self.has_table(table_name, schema):
+            self.meta.reflect(
+                bind=self.con, only=[table_name], schema=schema, views=True
+            )
+            with self.run_transaction():
+                self.get_table(table_name, schema).drop(bind=self.con)
+            self.meta.clear()
+
+    def _create_sql_schema(
+        self,
+        frame: DataFrame,
+        table_name: str,
+        keys: list[str] | None = None,
+        dtype: DtypeArg | None = None,
+        schema: str | None = None,
+    ) -> str:
+        table = SQLTable(
+            table_name,
+            self,
+            frame=frame,
+            index=False,
+            keys=keys,
+            dtype=dtype,
+            schema=schema,
+        )
+        return str(table.sql_schema())
+
+
+# ---- SQL without SQLAlchemy ---
+
+
+class ADBCDatabase(PandasSQL):
+    """
+    This class enables conversion between DataFrame and SQL databases
+    using ADBC to handle DataBase abstraction.
+
+    Parameters
+    ----------
+    con : adbc_driver_manager.dbapi.Connection
+    """
+
+    def __init__(self, con) -> None:
+        self.con = con
+
+    @contextmanager
+    def run_transaction(self):
+        with self.con.cursor() as cur:
+            try:
+                yield cur
+            except Exception:
+                self.con.rollback()
+                raise
+            self.con.commit()
+
+    def execute(self, sql: str | Select | TextClause, params=None):
+        if not isinstance(sql, str):
+            raise TypeError("Query must be a string unless using sqlalchemy.")
+        args = [] if params is None else [params]
+        cur = self.con.cursor()
+        try:
+            cur.execute(sql, *args)
+            return cur
+        except Exception as exc:
+            try:
+                self.con.rollback()
+            except Exception as inner_exc:  # pragma: no cover
+                ex = DatabaseError(
+                    f"Execution failed on sql: {sql}\n{exc}\nunable to rollback"
+                )
+                raise ex from inner_exc
+
+            ex = DatabaseError(f"Execution failed on sql '{sql}': {exc}")
+            raise ex from exc
+
+    def read_table(
+        self,
+        table_name: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        columns=None,
+        schema: str | None = None,
+        chunksize: int | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        """
+        Read SQL database table into a DataFrame.
+
+        Parameters
+        ----------
+        table_name : str
+            Name of SQL table in database.
+        coerce_float : bool, default True
+            Raises NotImplementedError
+        parse_dates : list or dict, default: None
+            - List of column names to parse as dates.
+            - Dict of ``{column_name: format string}`` where format string is
+              strftime compatible in case of parsing string times, or is one of
+              (D, s, ns, ms, us) in case of parsing integer timestamps.
+            - Dict of ``{column_name: arg}``, where the arg corresponds
+              to the keyword arguments of :func:`pandas.to_datetime`.
+              Especially useful with databases without native Datetime support,
+              such as SQLite.
+        columns : list, default: None
+            List of column names to select from SQL table.
+        schema : string, default None
+            Name of SQL schema in database to query (if database flavor
+            supports this).  If specified, this overwrites the default
+            schema of the SQL database object.
+        chunksize : int, default None
+            Raises NotImplementedError
+        dtype_backend : {'numpy_nullable', 'pyarrow'}, default 'numpy_nullable'
+            Back-end data type applied to the resultant :class:`DataFrame`
+            (still experimental). Behaviour is as follows:
+
+            * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+              (default).
+            * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+              DataFrame.
+
+            .. versionadded:: 2.0
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        pandas.read_sql_table
+        SQLDatabase.read_query
+
+        """
+        if coerce_float is not True:
+            raise NotImplementedError(
+                "'coerce_float' is not implemented for ADBC drivers"
+            )
+        if chunksize:
+            raise NotImplementedError("'chunksize' is not implemented for ADBC drivers")
+
+        if columns:
+            if index_col:
+                index_select = maybe_make_list(index_col)
+            else:
+                index_select = []
+            to_select = index_select + columns
+            select_list = ", ".join(f'"{x}"' for x in to_select)
+        else:
+            select_list = "*"
+        if schema:
+            stmt = f"SELECT {select_list} FROM {schema}.{table_name}"
+        else:
+            stmt = f"SELECT {select_list} FROM {table_name}"
+
+        with self.con.cursor() as cur:
+            cur.execute(stmt)
+            pa_table = cur.fetch_arrow_table()
+            df = arrow_table_to_pandas(pa_table, dtype_backend=dtype_backend)
+
+        return _wrap_result_adbc(
+            df,
+            index_col=index_col,
+            parse_dates=parse_dates,
+        )
+
+    def read_query(
+        self,
+        sql: str,
+        index_col: str | list[str] | None = None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        params=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        """
+        Read SQL query into a DataFrame.
+
+        Parameters
+        ----------
+        sql : str
+            SQL query to be executed.
+        index_col : string, optional, default: None
+            Column name to use as index for the returned DataFrame object.
+        coerce_float : bool, default True
+            Raises NotImplementedError
+        params : list, tuple or dict, optional, default: None
+            Raises NotImplementedError
+        parse_dates : list or dict, default: None
+            - List of column names to parse as dates.
+            - Dict of ``{column_name: format string}`` where format string is
+              strftime compatible in case of parsing string times, or is one of
+              (D, s, ns, ms, us) in case of parsing integer timestamps.
+            - Dict of ``{column_name: arg dict}``, where the arg dict
+              corresponds to the keyword arguments of
+              :func:`pandas.to_datetime` Especially useful with databases
+              without native Datetime support, such as SQLite.
+        chunksize : int, default None
+            Raises NotImplementedError
+        dtype : Type name or dict of columns
+            Data type for data or columns. E.g. np.float64 or
+            {'a': np.float64, 'b': np.int32, 'c': 'Int64'}
+
+            .. versionadded:: 1.3.0
+
+        Returns
+        -------
+        DataFrame
+
+        See Also
+        --------
+        read_sql_table : Read SQL database table into a DataFrame.
+        read_sql
+
+        """
+        if coerce_float is not True:
+            raise NotImplementedError(
+                "'coerce_float' is not implemented for ADBC drivers"
+            )
+        if params:
+            raise NotImplementedError("'params' is not implemented for ADBC drivers")
+        if chunksize:
+            raise NotImplementedError("'chunksize' is not implemented for ADBC drivers")
+
+        with self.con.cursor() as cur:
+            cur.execute(sql)
+            pa_table = cur.fetch_arrow_table()
+            df = arrow_table_to_pandas(pa_table, dtype_backend=dtype_backend)
+
+        return _wrap_result_adbc(
+            df,
+            index_col=index_col,
+            parse_dates=parse_dates,
+            dtype=dtype,
+        )
+
+    read_sql = read_query
+
+    def to_sql(
+        self,
+        frame,
+        name: str,
+        if_exists: Literal["fail", "replace", "append"] = "fail",
+        index: bool = True,
+        index_label=None,
+        schema: str | None = None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        method: Literal["multi"] | Callable | None = None,
+        engine: str = "auto",
+        **engine_kwargs,
+    ) -> int | None:
+        """
+        Write records stored in a DataFrame to a SQL database.
+
+        Parameters
+        ----------
+        frame : DataFrame
+        name : string
+            Name of SQL table.
+        if_exists : {'fail', 'replace', 'append'}, default 'fail'
+            - fail: If table exists, do nothing.
+            - replace: If table exists, drop it, recreate it, and insert data.
+            - append: If table exists, insert data. Create if does not exist.
+        index : boolean, default True
+            Write DataFrame index as a column.
+        index_label : string or sequence, default None
+            Raises NotImplementedError
+        schema : string, default None
+            Name of SQL schema in database to write to (if database flavor
+            supports this). If specified, this overwrites the default
+            schema of the SQLDatabase object.
+        chunksize : int, default None
+            Raises NotImplementedError
+        dtype : single type or dict of column name to SQL type, default None
+            Raises NotImplementedError
+        method : {None', 'multi', callable}, default None
+            Raises NotImplementedError
+        engine : {'auto', 'sqlalchemy'}, default 'auto'
+            Raises NotImplementedError if not set to 'auto'
+        """
+        if index_label:
+            raise NotImplementedError(
+                "'index_label' is not implemented for ADBC drivers"
+            )
+        if chunksize:
+            raise NotImplementedError("'chunksize' is not implemented for ADBC drivers")
+        if dtype:
+            raise NotImplementedError("'dtype' is not implemented for ADBC drivers")
+        if method:
+            raise NotImplementedError("'method' is not implemented for ADBC drivers")
+        if engine != "auto":
+            raise NotImplementedError(
+                "engine != 'auto' not implemented for ADBC drivers"
+            )
+
+        if schema:
+            table_name = f"{schema}.{name}"
+        else:
+            table_name = name
+
+        # pandas if_exists="append" will still create the
+        # table if it does not exist; ADBC is more explicit with append/create
+        # as applicable modes, so the semantics get blurred across
+        # the libraries
+        mode = "create"
+        if self.has_table(name, schema):
+            if if_exists == "fail":
+                raise ValueError(f"Table '{table_name}' already exists.")
+            elif if_exists == "replace":
+                with self.con.cursor() as cur:
+                    cur.execute(f"DROP TABLE {table_name}")
+            elif if_exists == "append":
+                mode = "append"
+
+        import pyarrow as pa
+
+        try:
+            tbl = pa.Table.from_pandas(frame, preserve_index=index)
+        except pa.ArrowNotImplementedError as exc:
+            raise ValueError("datatypes not supported") from exc
+
+        with self.con.cursor() as cur:
+            total_inserted = cur.adbc_ingest(
+                table_name=name, data=tbl, mode=mode, db_schema_name=schema
+            )
+
+        self.con.commit()
+        return total_inserted
+
+    def has_table(self, name: str, schema: str | None = None) -> bool:
+        meta = self.con.adbc_get_objects(
+            db_schema_filter=schema, table_name_filter=name
+        ).read_all()
+
+        for catalog_schema in meta["catalog_db_schemas"].to_pylist():
+            if not catalog_schema:
+                continue
+            for schema_record in catalog_schema:
+                if not schema_record:
+                    continue
+
+                for table_record in schema_record["db_schema_tables"]:
+                    if table_record["table_name"] == name:
+                        return True
+
+        return False
+
+    def _create_sql_schema(
+        self,
+        frame: DataFrame,
+        table_name: str,
+        keys: list[str] | None = None,
+        dtype: DtypeArg | None = None,
+        schema: str | None = None,
+    ) -> str:
+        raise NotImplementedError("not implemented for adbc")
+
+
+# sqlite-specific sql strings and handler class
+# dictionary used for readability purposes
+_SQL_TYPES = {
+    "string": "TEXT",
+    "floating": "REAL",
+    "integer": "INTEGER",
+    "datetime": "TIMESTAMP",
+    "date": "DATE",
+    "time": "TIME",
+    "boolean": "INTEGER",
+}
+
+
+def _get_unicode_name(name: object):
+    try:
+        uname = str(name).encode("utf-8", "strict").decode("utf-8")
+    except UnicodeError as err:
+        raise ValueError(f"Cannot convert identifier to UTF-8: '{name}'") from err
+    return uname
+
+
+def _get_valid_sqlite_name(name: object):
+    # See https://stackoverflow.com/questions/6514274/how-do-you-escape-strings\
+    # -for-sqlite-table-column-names-in-python
+    # Ensure the string can be encoded as UTF-8.
+    # Ensure the string does not include any NUL characters.
+    # Replace all " with "".
+    # Wrap the entire thing in double quotes.
+
+    uname = _get_unicode_name(name)
+    if not len(uname):
+        raise ValueError("Empty table or column name specified")
+
+    nul_index = uname.find("\x00")
+    if nul_index >= 0:
+        raise ValueError("SQLite identifier cannot contain NULs")
+    return '"' + uname.replace('"', '""') + '"'
+
+
+class SQLiteTable(SQLTable):
+    """
+    Patch the SQLTable for fallback support.
+    Instead of a table variable just use the Create Table statement.
+    """
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+
+        self._register_date_adapters()
+
+    def _register_date_adapters(self) -> None:
+        # GH 8341
+        # register an adapter callable for datetime.time object
+        import sqlite3
+
+        # this will transform time(12,34,56,789) into '12:34:56.000789'
+        # (this is what sqlalchemy does)
+        def _adapt_time(t) -> str:
+            # This is faster than strftime
+            return f"{t.hour:02d}:{t.minute:02d}:{t.second:02d}.{t.microsecond:06d}"
+
+        # Also register adapters for date/datetime and co
+        # xref https://docs.python.org/3.12/library/sqlite3.html#adapter-and-converter-recipes
+        # Python 3.12+ doesn't auto-register adapters for us anymore
+
+        adapt_date_iso = lambda val: val.isoformat()
+        adapt_datetime_iso = lambda val: val.isoformat(" ")
+
+        sqlite3.register_adapter(time, _adapt_time)
+
+        sqlite3.register_adapter(date, adapt_date_iso)
+        sqlite3.register_adapter(datetime, adapt_datetime_iso)
+
+        convert_date = lambda val: date.fromisoformat(val.decode())
+        convert_timestamp = lambda val: datetime.fromisoformat(val.decode())
+
+        sqlite3.register_converter("date", convert_date)
+        sqlite3.register_converter("timestamp", convert_timestamp)
+
+    def sql_schema(self) -> str:
+        return str(";\n".join(self.table))
+
+    def _execute_create(self) -> None:
+        with self.pd_sql.run_transaction() as conn:
+            for stmt in self.table:
+                conn.execute(stmt)
+
+    def insert_statement(self, *, num_rows: int) -> str:
+        names = list(map(str, self.frame.columns))
+        wld = "?"  # wildcard char
+        escape = _get_valid_sqlite_name
+
+        if self.index is not None:
+            for idx in self.index[::-1]:
+                names.insert(0, idx)
+
+        bracketed_names = [escape(column) for column in names]
+        col_names = ",".join(bracketed_names)
+
+        row_wildcards = ",".join([wld] * len(names))
+        wildcards = ",".join([f"({row_wildcards})" for _ in range(num_rows)])
+        insert_statement = (
+            f"INSERT INTO {escape(self.name)} ({col_names}) VALUES {wildcards}"
+        )
+        return insert_statement
+
+    def _execute_insert(self, conn, keys, data_iter) -> int:
+        data_list = list(data_iter)
+        conn.executemany(self.insert_statement(num_rows=1), data_list)
+        return conn.rowcount
+
+    def _execute_insert_multi(self, conn, keys, data_iter) -> int:
+        data_list = list(data_iter)
+        flattened_data = [x for row in data_list for x in row]
+        conn.execute(self.insert_statement(num_rows=len(data_list)), flattened_data)
+        return conn.rowcount
+
+    def _create_table_setup(self):
+        """
+        Return a list of SQL statements that creates a table reflecting the
+        structure of a DataFrame.  The first entry will be a CREATE TABLE
+        statement while the rest will be CREATE INDEX statements.
+        """
+        column_names_and_types = self._get_column_names_and_types(self._sql_type_name)
+        escape = _get_valid_sqlite_name
+
+        create_tbl_stmts = [
+            escape(cname) + " " + ctype for cname, ctype, _ in column_names_and_types
+        ]
+
+        if self.keys is not None and len(self.keys):
+            if not is_list_like(self.keys):
+                keys = [self.keys]
+            else:
+                keys = self.keys
+            cnames_br = ", ".join([escape(c) for c in keys])
+            create_tbl_stmts.append(
+                f"CONSTRAINT {self.name}_pk PRIMARY KEY ({cnames_br})"
+            )
+        if self.schema:
+            schema_name = self.schema + "."
+        else:
+            schema_name = ""
+        create_stmts = [
+            "CREATE TABLE "
+            + schema_name
+            + escape(self.name)
+            + " (\n"
+            + ",\n  ".join(create_tbl_stmts)
+            + "\n)"
+        ]
+
+        ix_cols = [cname for cname, _, is_index in column_names_and_types if is_index]
+        if len(ix_cols):
+            cnames = "_".join(ix_cols)
+            cnames_br = ",".join([escape(c) for c in ix_cols])
+            create_stmts.append(
+                "CREATE INDEX "
+                + escape("ix_" + self.name + "_" + cnames)
+                + "ON "
+                + escape(self.name)
+                + " ("
+                + cnames_br
+                + ")"
+            )
+
+        return create_stmts
+
+    def _sql_type_name(self, col):
+        dtype: DtypeArg = self.dtype or {}
+        if is_dict_like(dtype):
+            dtype = cast(dict, dtype)
+            if col.name in dtype:
+                return dtype[col.name]
+
+        # Infer type of column, while ignoring missing values.
+        # Needed for inserting typed data containing NULLs, GH 8778.
+        col_type = lib.infer_dtype(col, skipna=True)
+
+        if col_type == "timedelta64":
+            warnings.warn(
+                "the 'timedelta' type is not supported, and will be "
+                "written as integer values (ns frequency) to the database.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+            col_type = "integer"
+
+        elif col_type == "datetime64":
+            col_type = "datetime"
+
+        elif col_type == "empty":
+            col_type = "string"
+
+        elif col_type == "complex":
+            raise ValueError("Complex datatypes not supported")
+
+        if col_type not in _SQL_TYPES:
+            col_type = "string"
+
+        return _SQL_TYPES[col_type]
+
+
+class SQLiteDatabase(PandasSQL):
+    """
+    Version of SQLDatabase to support SQLite connections (fallback without
+    SQLAlchemy). This should only be used internally.
+
+    Parameters
+    ----------
+    con : sqlite connection object
+
+    """
+
+    def __init__(self, con) -> None:
+        self.con = con
+
+    @contextmanager
+    def run_transaction(self):
+        cur = self.con.cursor()
+        try:
+            yield cur
+            self.con.commit()
+        except Exception:
+            self.con.rollback()
+            raise
+        finally:
+            cur.close()
+
+    def execute(self, sql: str | Select | TextClause, params=None):
+        if not isinstance(sql, str):
+            raise TypeError("Query must be a string unless using sqlalchemy.")
+        args = [] if params is None else [params]
+        cur = self.con.cursor()
+        try:
+            cur.execute(sql, *args)
+            return cur
+        except Exception as exc:
+            try:
+                self.con.rollback()
+            except Exception as inner_exc:  # pragma: no cover
+                ex = DatabaseError(
+                    f"Execution failed on sql: {sql}\n{exc}\nunable to rollback"
+                )
+                raise ex from inner_exc
+
+            ex = DatabaseError(f"Execution failed on sql '{sql}': {exc}")
+            raise ex from exc
+
+    @staticmethod
+    def _query_iterator(
+        cursor,
+        chunksize: int,
+        columns,
+        index_col=None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ):
+        """Return generator through chunked result set"""
+        has_read_data = False
+        while True:
+            data = cursor.fetchmany(chunksize)
+            if type(data) == tuple:
+                data = list(data)
+            if not data:
+                cursor.close()
+                if not has_read_data:
+                    result = DataFrame.from_records(
+                        [], columns=columns, coerce_float=coerce_float
+                    )
+                    if dtype:
+                        result = result.astype(dtype)
+                    yield result
+                break
+
+            has_read_data = True
+            yield _wrap_result(
+                data,
+                columns,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype=dtype,
+                dtype_backend=dtype_backend,
+            )
+
+    def read_query(
+        self,
+        sql,
+        index_col=None,
+        coerce_float: bool = True,
+        parse_dates=None,
+        params=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        dtype_backend: DtypeBackend | Literal["numpy"] = "numpy",
+    ) -> DataFrame | Iterator[DataFrame]:
+        cursor = self.execute(sql, params)
+        columns = [col_desc[0] for col_desc in cursor.description]
+
+        if chunksize is not None:
+            return self._query_iterator(
+                cursor,
+                chunksize,
+                columns,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype=dtype,
+                dtype_backend=dtype_backend,
+            )
+        else:
+            data = self._fetchall_as_list(cursor)
+            cursor.close()
+
+            frame = _wrap_result(
+                data,
+                columns,
+                index_col=index_col,
+                coerce_float=coerce_float,
+                parse_dates=parse_dates,
+                dtype=dtype,
+                dtype_backend=dtype_backend,
+            )
+            return frame
+
+    def _fetchall_as_list(self, cur):
+        result = cur.fetchall()
+        if not isinstance(result, list):
+            result = list(result)
+        return result
+
+    def to_sql(
+        self,
+        frame,
+        name: str,
+        if_exists: str = "fail",
+        index: bool = True,
+        index_label=None,
+        schema=None,
+        chunksize: int | None = None,
+        dtype: DtypeArg | None = None,
+        method: Literal["multi"] | Callable | None = None,
+        engine: str = "auto",
+        **engine_kwargs,
+    ) -> int | None:
+        """
+        Write records stored in a DataFrame to a SQL database.
+
+        Parameters
+        ----------
+        frame: DataFrame
+        name: string
+            Name of SQL table.
+        if_exists: {'fail', 'replace', 'append'}, default 'fail'
+            fail: If table exists, do nothing.
+            replace: If table exists, drop it, recreate it, and insert data.
+            append: If table exists, insert data. Create if it does not exist.
+        index : bool, default True
+            Write DataFrame index as a column
+        index_label : string or sequence, default None
+            Column label for index column(s). If None is given (default) and
+            `index` is True, then the index names are used.
+            A sequence should be given if the DataFrame uses MultiIndex.
+        schema : string, default None
+            Ignored parameter included for compatibility with SQLAlchemy
+            version of ``to_sql``.
+        chunksize : int, default None
+            If not None, then rows will be written in batches of this
+            size at a time. If None, all rows will be written at once.
+        dtype : single type or dict of column name to SQL type, default None
+            Optional specifying the datatype for columns. The SQL type should
+            be a string. If all columns are of the same type, one single value
+            can be used.
+        method : {None, 'multi', callable}, default None
+            Controls the SQL insertion clause used:
+
+            * None : Uses standard SQL ``INSERT`` clause (one per row).
+            * 'multi': Pass multiple values in a single ``INSERT`` clause.
+            * callable with signature ``(pd_table, conn, keys, data_iter)``.
+
+            Details and a sample callable implementation can be found in the
+            section :ref:`insert method `.
+        """
+        if dtype:
+            if not is_dict_like(dtype):
+                # error: Value expression in dictionary comprehension has incompatible
+                # type "Union[ExtensionDtype, str, dtype[Any], Type[object],
+                # Dict[Hashable, Union[ExtensionDtype, Union[str, dtype[Any]],
+                # Type[str], Type[float], Type[int], Type[complex], Type[bool],
+                # Type[object]]]]"; expected type "Union[ExtensionDtype, str,
+                # dtype[Any], Type[object]]"
+                dtype = {col_name: dtype for col_name in frame}  # type: ignore[misc]
+            else:
+                dtype = cast(dict, dtype)
+
+            for col, my_type in dtype.items():
+                if not isinstance(my_type, str):
+                    raise ValueError(f"{col} ({my_type}) not a string")
+
+        table = SQLiteTable(
+            name,
+            self,
+            frame=frame,
+            index=index,
+            if_exists=if_exists,
+            index_label=index_label,
+            dtype=dtype,
+        )
+        table.create()
+        return table.insert(chunksize, method)
+
+    def has_table(self, name: str, schema: str | None = None) -> bool:
+        wld = "?"
+        query = f"""
+        SELECT
+            name
+        FROM
+            sqlite_master
+        WHERE
+            type IN ('table', 'view')
+            AND name={wld};
+        """
+
+        return len(self.execute(query, [name]).fetchall()) > 0
+
+    def get_table(self, table_name: str, schema: str | None = None) -> None:
+        return None  # not supported in fallback mode
+
+    def drop_table(self, name: str, schema: str | None = None) -> None:
+        drop_sql = f"DROP TABLE {_get_valid_sqlite_name(name)}"
+        self.execute(drop_sql)
+
+    def _create_sql_schema(
+        self,
+        frame,
+        table_name: str,
+        keys=None,
+        dtype: DtypeArg | None = None,
+        schema: str | None = None,
+    ) -> str:
+        table = SQLiteTable(
+            table_name,
+            self,
+            frame=frame,
+            index=False,
+            keys=keys,
+            dtype=dtype,
+            schema=schema,
+        )
+        return str(table.sql_schema())
+
+
+def get_schema(
+    frame,
+    name: str,
+    keys=None,
+    con=None,
+    dtype: DtypeArg | None = None,
+    schema: str | None = None,
+) -> str:
+    """
+    Get the SQL db table schema for the given frame.
+
+    Parameters
+    ----------
+    frame : DataFrame
+    name : str
+        name of SQL table
+    keys : string or sequence, default: None
+        columns to use a primary key
+    con: ADBC Connection, SQLAlchemy connectable, sqlite3 connection, default: None
+        ADBC provides high performance I/O with native type support, where available.
+        Using SQLAlchemy makes it possible to use any DB supported by that
+        library
+        If a DBAPI2 object, only sqlite3 is supported.
+    dtype : dict of column name to SQL type, default None
+        Optional specifying the datatype for columns. The SQL type should
+        be a SQLAlchemy type, or a string for sqlite3 fallback connection.
+    schema: str, default: None
+        Optional specifying the schema to be used in creating the table.
+    """
+    with pandasSQL_builder(con=con) as pandas_sql:
+        return pandas_sql._create_sql_schema(
+            frame, name, keys=keys, dtype=dtype, schema=schema
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/stata.py b/.venv/lib/python3.13/site-packages/pandas/io/stata.py
new file mode 100644
index 0000000000000000000000000000000000000000..b5057a66816386d344a3c9d2ced174ae1b4642e1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/stata.py
@@ -0,0 +1,3768 @@
+"""
+Module contains tools for processing Stata files into DataFrames
+
+The StataReader below was originally written by Joe Presbrey as part of PyDTA.
+It has been extended and improved by Skipper Seabold from the Statsmodels
+project who also developed the StataWriter and was finally added to pandas in
+a once again improved version.
+
+You can find more information on http://presbrey.mit.edu/PyDTA and
+https://www.statsmodels.org/devel/
+"""
+from __future__ import annotations
+
+from collections import abc
+from datetime import (
+    datetime,
+    timedelta,
+)
+from io import BytesIO
+import os
+import struct
+import sys
+from typing import (
+    IO,
+    TYPE_CHECKING,
+    AnyStr,
+    Callable,
+    Final,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.lib import infer_dtype
+from pandas._libs.writers import max_len_string_array
+from pandas.errors import (
+    CategoricalConversionWarning,
+    InvalidColumnName,
+    PossiblePrecisionLoss,
+    ValueLabelTypeMismatch,
+)
+from pandas.util._decorators import (
+    Appender,
+    doc,
+)
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.base import ExtensionDtype
+from pandas.core.dtypes.common import (
+    ensure_object,
+    is_numeric_dtype,
+    is_string_dtype,
+)
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+from pandas import (
+    Categorical,
+    DatetimeIndex,
+    NaT,
+    Timestamp,
+    isna,
+    to_datetime,
+    to_timedelta,
+)
+from pandas.core.frame import DataFrame
+from pandas.core.indexes.base import Index
+from pandas.core.indexes.range import RangeIndex
+from pandas.core.series import Series
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import get_handle
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+    from types import TracebackType
+    from typing import Literal
+
+    from pandas._typing import (
+        CompressionOptions,
+        FilePath,
+        ReadBuffer,
+        Self,
+        StorageOptions,
+        WriteBuffer,
+    )
+
+_version_error = (
+    "Version of given Stata file is {version}. pandas supports importing "
+    "versions 105, 108, 111 (Stata 7SE), 113 (Stata 8/9), "
+    "114 (Stata 10/11), 115 (Stata 12), 117 (Stata 13), 118 (Stata 14/15/16),"
+    "and 119 (Stata 15/16, over 32,767 variables)."
+)
+
+_statafile_processing_params1 = """\
+convert_dates : bool, default True
+    Convert date variables to DataFrame time values.
+convert_categoricals : bool, default True
+    Read value labels and convert columns to Categorical/Factor variables."""
+
+_statafile_processing_params2 = """\
+index_col : str, optional
+    Column to set as index.
+convert_missing : bool, default False
+    Flag indicating whether to convert missing values to their Stata
+    representations.  If False, missing values are replaced with nan.
+    If True, columns containing missing values are returned with
+    object data types and missing values are represented by
+    StataMissingValue objects.
+preserve_dtypes : bool, default True
+    Preserve Stata datatypes. If False, numeric data are upcast to pandas
+    default types for foreign data (float64 or int64).
+columns : list or None
+    Columns to retain.  Columns will be returned in the given order.  None
+    returns all columns.
+order_categoricals : bool, default True
+    Flag indicating whether converted categorical data are ordered."""
+
+_chunksize_params = """\
+chunksize : int, default None
+    Return StataReader object for iterations, returns chunks with
+    given number of lines."""
+
+_iterator_params = """\
+iterator : bool, default False
+    Return StataReader object."""
+
+_reader_notes = """\
+Notes
+-----
+Categorical variables read through an iterator may not have the same
+categories and dtype. This occurs when  a variable stored in a DTA
+file is associated to an incomplete set of value labels that only
+label a strict subset of the values."""
+
+_read_stata_doc = f"""
+Read Stata file into DataFrame.
+
+Parameters
+----------
+filepath_or_buffer : str, path object or file-like object
+    Any valid string path is acceptable. The string could be a URL. Valid
+    URL schemes include http, ftp, s3, and file. For file URLs, a host is
+    expected. A local file could be: ``file://localhost/path/to/table.dta``.
+
+    If you want to pass in a path object, pandas accepts any ``os.PathLike``.
+
+    By file-like object, we refer to objects with a ``read()`` method,
+    such as a file handle (e.g. via builtin ``open`` function)
+    or ``StringIO``.
+{_statafile_processing_params1}
+{_statafile_processing_params2}
+{_chunksize_params}
+{_iterator_params}
+{_shared_docs["decompression_options"] % "filepath_or_buffer"}
+{_shared_docs["storage_options"]}
+
+Returns
+-------
+DataFrame or pandas.api.typing.StataReader
+
+See Also
+--------
+io.stata.StataReader : Low-level reader for Stata data files.
+DataFrame.to_stata: Export Stata data files.
+
+{_reader_notes}
+
+Examples
+--------
+
+Creating a dummy stata for this example
+
+>>> df = pd.DataFrame({{'animal': ['falcon', 'parrot', 'falcon', 'parrot'],
+...                     'speed': [350, 18, 361, 15]}})  # doctest: +SKIP
+>>> df.to_stata('animals.dta')  # doctest: +SKIP
+
+Read a Stata dta file:
+
+>>> df = pd.read_stata('animals.dta')  # doctest: +SKIP
+
+Read a Stata dta file in 10,000 line chunks:
+
+>>> values = np.random.randint(0, 10, size=(20_000, 1), dtype="uint8")  # doctest: +SKIP
+>>> df = pd.DataFrame(values, columns=["i"])  # doctest: +SKIP
+>>> df.to_stata('filename.dta')  # doctest: +SKIP
+
+>>> with pd.read_stata('filename.dta', chunksize=10000) as itr: # doctest: +SKIP
+>>>     for chunk in itr:
+...         # Operate on a single chunk, e.g., chunk.mean()
+...         pass  # doctest: +SKIP
+"""
+
+_read_method_doc = f"""\
+Reads observations from Stata file, converting them into a dataframe
+
+Parameters
+----------
+nrows : int
+    Number of lines to read from data file, if None read whole file.
+{_statafile_processing_params1}
+{_statafile_processing_params2}
+
+Returns
+-------
+DataFrame
+"""
+
+_stata_reader_doc = f"""\
+Class for reading Stata dta files.
+
+Parameters
+----------
+path_or_buf : path (string), buffer or path object
+    string, path object (pathlib.Path or py._path.local.LocalPath) or object
+    implementing a binary read() functions.
+{_statafile_processing_params1}
+{_statafile_processing_params2}
+{_chunksize_params}
+{_shared_docs["decompression_options"]}
+{_shared_docs["storage_options"]}
+
+{_reader_notes}
+"""
+
+
+_date_formats = ["%tc", "%tC", "%td", "%d", "%tw", "%tm", "%tq", "%th", "%ty"]
+
+
+stata_epoch: Final = datetime(1960, 1, 1)
+
+
+def _stata_elapsed_date_to_datetime_vec(dates: Series, fmt: str) -> Series:
+    """
+    Convert from SIF to datetime. https://www.stata.com/help.cgi?datetime
+
+    Parameters
+    ----------
+    dates : Series
+        The Stata Internal Format date to convert to datetime according to fmt
+    fmt : str
+        The format to convert to. Can be, tc, td, tw, tm, tq, th, ty
+        Returns
+
+    Returns
+    -------
+    converted : Series
+        The converted dates
+
+    Examples
+    --------
+    >>> dates = pd.Series([52])
+    >>> _stata_elapsed_date_to_datetime_vec(dates , "%tw")
+    0   1961-01-01
+    dtype: datetime64[ns]
+
+    Notes
+    -----
+    datetime/c - tc
+        milliseconds since 01jan1960 00:00:00.000, assuming 86,400 s/day
+    datetime/C - tC - NOT IMPLEMENTED
+        milliseconds since 01jan1960 00:00:00.000, adjusted for leap seconds
+    date - td
+        days since 01jan1960 (01jan1960 = 0)
+    weekly date - tw
+        weeks since 1960w1
+        This assumes 52 weeks in a year, then adds 7 * remainder of the weeks.
+        The datetime value is the start of the week in terms of days in the
+        year, not ISO calendar weeks.
+    monthly date - tm
+        months since 1960m1
+    quarterly date - tq
+        quarters since 1960q1
+    half-yearly date - th
+        half-years since 1960h1 yearly
+    date - ty
+        years since 0000
+    """
+    MIN_YEAR, MAX_YEAR = Timestamp.min.year, Timestamp.max.year
+    MAX_DAY_DELTA = (Timestamp.max - datetime(1960, 1, 1)).days
+    MIN_DAY_DELTA = (Timestamp.min - datetime(1960, 1, 1)).days
+    MIN_MS_DELTA = MIN_DAY_DELTA * 24 * 3600 * 1000
+    MAX_MS_DELTA = MAX_DAY_DELTA * 24 * 3600 * 1000
+
+    def convert_year_month_safe(year, month) -> Series:
+        """
+        Convert year and month to datetimes, using pandas vectorized versions
+        when the date range falls within the range supported by pandas.
+        Otherwise it falls back to a slower but more robust method
+        using datetime.
+        """
+        if year.max() < MAX_YEAR and year.min() > MIN_YEAR:
+            return to_datetime(100 * year + month, format="%Y%m")
+        else:
+            index = getattr(year, "index", None)
+            return Series([datetime(y, m, 1) for y, m in zip(year, month)], index=index)
+
+    def convert_year_days_safe(year, days) -> Series:
+        """
+        Converts year (e.g. 1999) and days since the start of the year to a
+        datetime or datetime64 Series
+        """
+        if year.max() < (MAX_YEAR - 1) and year.min() > MIN_YEAR:
+            return to_datetime(year, format="%Y") + to_timedelta(days, unit="d")
+        else:
+            index = getattr(year, "index", None)
+            value = [
+                datetime(y, 1, 1) + timedelta(days=int(d)) for y, d in zip(year, days)
+            ]
+            return Series(value, index=index)
+
+    def convert_delta_safe(base, deltas, unit) -> Series:
+        """
+        Convert base dates and deltas to datetimes, using pandas vectorized
+        versions if the deltas satisfy restrictions required to be expressed
+        as dates in pandas.
+        """
+        index = getattr(deltas, "index", None)
+        if unit == "d":
+            if deltas.max() > MAX_DAY_DELTA or deltas.min() < MIN_DAY_DELTA:
+                values = [base + timedelta(days=int(d)) for d in deltas]
+                return Series(values, index=index)
+        elif unit == "ms":
+            if deltas.max() > MAX_MS_DELTA or deltas.min() < MIN_MS_DELTA:
+                values = [
+                    base + timedelta(microseconds=(int(d) * 1000)) for d in deltas
+                ]
+                return Series(values, index=index)
+        else:
+            raise ValueError("format not understood")
+        base = to_datetime(base)
+        deltas = to_timedelta(deltas, unit=unit)
+        return base + deltas
+
+    # TODO(non-nano): If/when pandas supports more than datetime64[ns], this
+    #  should be improved to use correct range, e.g. datetime[Y] for yearly
+    bad_locs = np.isnan(dates)
+    has_bad_values = False
+    if bad_locs.any():
+        has_bad_values = True
+        dates._values[bad_locs] = 1.0  # Replace with NaT
+    dates = dates.astype(np.int64)
+
+    if fmt.startswith(("%tc", "tc")):  # Delta ms relative to base
+        base = stata_epoch
+        ms = dates
+        conv_dates = convert_delta_safe(base, ms, "ms")
+    elif fmt.startswith(("%tC", "tC")):
+        warnings.warn(
+            "Encountered %tC format. Leaving in Stata Internal Format.",
+            stacklevel=find_stack_level(),
+        )
+        conv_dates = Series(dates, dtype=object)
+        if has_bad_values:
+            conv_dates[bad_locs] = NaT
+        return conv_dates
+    # Delta days relative to base
+    elif fmt.startswith(("%td", "td", "%d", "d")):
+        base = stata_epoch
+        days = dates
+        conv_dates = convert_delta_safe(base, days, "d")
+    # does not count leap days - 7 days is a week.
+    # 52nd week may have more than 7 days
+    elif fmt.startswith(("%tw", "tw")):
+        year = stata_epoch.year + dates // 52
+        days = (dates % 52) * 7
+        conv_dates = convert_year_days_safe(year, days)
+    elif fmt.startswith(("%tm", "tm")):  # Delta months relative to base
+        year = stata_epoch.year + dates // 12
+        month = (dates % 12) + 1
+        conv_dates = convert_year_month_safe(year, month)
+    elif fmt.startswith(("%tq", "tq")):  # Delta quarters relative to base
+        year = stata_epoch.year + dates // 4
+        quarter_month = (dates % 4) * 3 + 1
+        conv_dates = convert_year_month_safe(year, quarter_month)
+    elif fmt.startswith(("%th", "th")):  # Delta half-years relative to base
+        year = stata_epoch.year + dates // 2
+        month = (dates % 2) * 6 + 1
+        conv_dates = convert_year_month_safe(year, month)
+    elif fmt.startswith(("%ty", "ty")):  # Years -- not delta
+        year = dates
+        first_month = np.ones_like(dates)
+        conv_dates = convert_year_month_safe(year, first_month)
+    else:
+        raise ValueError(f"Date fmt {fmt} not understood")
+
+    if has_bad_values:  # Restore NaT for bad values
+        conv_dates[bad_locs] = NaT
+
+    return conv_dates
+
+
+def _datetime_to_stata_elapsed_vec(dates: Series, fmt: str) -> Series:
+    """
+    Convert from datetime to SIF. https://www.stata.com/help.cgi?datetime
+
+    Parameters
+    ----------
+    dates : Series
+        Series or array containing datetime or datetime64[ns] to
+        convert to the Stata Internal Format given by fmt
+    fmt : str
+        The format to convert to. Can be, tc, td, tw, tm, tq, th, ty
+    """
+    index = dates.index
+    NS_PER_DAY = 24 * 3600 * 1000 * 1000 * 1000
+    US_PER_DAY = NS_PER_DAY / 1000
+
+    def parse_dates_safe(
+        dates: Series, delta: bool = False, year: bool = False, days: bool = False
+    ):
+        d = {}
+        if lib.is_np_dtype(dates.dtype, "M"):
+            if delta:
+                time_delta = dates - Timestamp(stata_epoch).as_unit("ns")
+                d["delta"] = time_delta._values.view(np.int64) // 1000  # microseconds
+            if days or year:
+                date_index = DatetimeIndex(dates)
+                d["year"] = date_index._data.year
+                d["month"] = date_index._data.month
+            if days:
+                days_in_ns = dates._values.view(np.int64) - to_datetime(
+                    d["year"], format="%Y"
+                )._values.view(np.int64)
+                d["days"] = days_in_ns // NS_PER_DAY
+
+        elif infer_dtype(dates, skipna=False) == "datetime":
+            if delta:
+                delta = dates._values - stata_epoch
+
+                def f(x: timedelta) -> float:
+                    return US_PER_DAY * x.days + 1000000 * x.seconds + x.microseconds
+
+                v = np.vectorize(f)
+                d["delta"] = v(delta)
+            if year:
+                year_month = dates.apply(lambda x: 100 * x.year + x.month)
+                d["year"] = year_month._values // 100
+                d["month"] = year_month._values - d["year"] * 100
+            if days:
+
+                def g(x: datetime) -> int:
+                    return (x - datetime(x.year, 1, 1)).days
+
+                v = np.vectorize(g)
+                d["days"] = v(dates)
+        else:
+            raise ValueError(
+                "Columns containing dates must contain either "
+                "datetime64, datetime or null values."
+            )
+
+        return DataFrame(d, index=index)
+
+    bad_loc = isna(dates)
+    index = dates.index
+    if bad_loc.any():
+        if lib.is_np_dtype(dates.dtype, "M"):
+            dates._values[bad_loc] = to_datetime(stata_epoch)
+        else:
+            dates._values[bad_loc] = stata_epoch
+
+    if fmt in ["%tc", "tc"]:
+        d = parse_dates_safe(dates, delta=True)
+        conv_dates = d.delta / 1000
+    elif fmt in ["%tC", "tC"]:
+        warnings.warn(
+            "Stata Internal Format tC not supported.",
+            stacklevel=find_stack_level(),
+        )
+        conv_dates = dates
+    elif fmt in ["%td", "td"]:
+        d = parse_dates_safe(dates, delta=True)
+        conv_dates = d.delta // US_PER_DAY
+    elif fmt in ["%tw", "tw"]:
+        d = parse_dates_safe(dates, year=True, days=True)
+        conv_dates = 52 * (d.year - stata_epoch.year) + d.days // 7
+    elif fmt in ["%tm", "tm"]:
+        d = parse_dates_safe(dates, year=True)
+        conv_dates = 12 * (d.year - stata_epoch.year) + d.month - 1
+    elif fmt in ["%tq", "tq"]:
+        d = parse_dates_safe(dates, year=True)
+        conv_dates = 4 * (d.year - stata_epoch.year) + (d.month - 1) // 3
+    elif fmt in ["%th", "th"]:
+        d = parse_dates_safe(dates, year=True)
+        conv_dates = 2 * (d.year - stata_epoch.year) + (d.month > 6).astype(int)
+    elif fmt in ["%ty", "ty"]:
+        d = parse_dates_safe(dates, year=True)
+        conv_dates = d.year
+    else:
+        raise ValueError(f"Format {fmt} is not a known Stata date format")
+
+    conv_dates = Series(conv_dates, dtype=np.float64, copy=False)
+    missing_value = struct.unpack(" DataFrame:
+    """
+    Checks the dtypes of the columns of a pandas DataFrame for
+    compatibility with the data types and ranges supported by Stata, and
+    converts if necessary.
+
+    Parameters
+    ----------
+    data : DataFrame
+        The DataFrame to check and convert
+
+    Notes
+    -----
+    Numeric columns in Stata must be one of int8, int16, int32, float32 or
+    float64, with some additional value restrictions.  int8 and int16 columns
+    are checked for violations of the value restrictions and upcast if needed.
+    int64 data is not usable in Stata, and so it is downcast to int32 whenever
+    the value are in the int32 range, and sidecast to float64 when larger than
+    this range.  If the int64 values are outside of the range of those
+    perfectly representable as float64 values, a warning is raised.
+
+    bool columns are cast to int8.  uint columns are converted to int of the
+    same size if there is no loss in precision, otherwise are upcast to a
+    larger type.  uint64 is currently not supported since it is concerted to
+    object in a DataFrame.
+    """
+    ws = ""
+    # original, if small, if large
+    conversion_data: tuple[
+        tuple[type, type, type],
+        tuple[type, type, type],
+        tuple[type, type, type],
+        tuple[type, type, type],
+        tuple[type, type, type],
+    ] = (
+        (np.bool_, np.int8, np.int8),
+        (np.uint8, np.int8, np.int16),
+        (np.uint16, np.int16, np.int32),
+        (np.uint32, np.int32, np.int64),
+        (np.uint64, np.int64, np.float64),
+    )
+
+    float32_max = struct.unpack("= 2**53:
+                        ws = precision_loss_doc.format("uint64", "float64")
+
+                data[col] = data[col].astype(dtype)
+
+        # Check values and upcast if necessary
+
+        if dtype == np.int8 and not empty_df:
+            if data[col].max() > 100 or data[col].min() < -127:
+                data[col] = data[col].astype(np.int16)
+        elif dtype == np.int16 and not empty_df:
+            if data[col].max() > 32740 or data[col].min() < -32767:
+                data[col] = data[col].astype(np.int32)
+        elif dtype == np.int64:
+            if empty_df or (
+                data[col].max() <= 2147483620 and data[col].min() >= -2147483647
+            ):
+                data[col] = data[col].astype(np.int32)
+            else:
+                data[col] = data[col].astype(np.float64)
+                if data[col].max() >= 2**53 or data[col].min() <= -(2**53):
+                    ws = precision_loss_doc.format("int64", "float64")
+        elif dtype in (np.float32, np.float64):
+            if np.isinf(data[col]).any():
+                raise ValueError(
+                    f"Column {col} contains infinity or -infinity"
+                    "which is outside the range supported by Stata."
+                )
+            value = data[col].max()
+            if dtype == np.float32 and value > float32_max:
+                data[col] = data[col].astype(np.float64)
+            elif dtype == np.float64:
+                if value > float64_max:
+                    raise ValueError(
+                        f"Column {col} has a maximum value ({value}) outside the range "
+                        f"supported by Stata ({float64_max})"
+                    )
+        if is_nullable_int:
+            if orig_missing.any():
+                # Replace missing by Stata sentinel value
+                sentinel = StataMissingValue.BASE_MISSING_VALUES[data[col].dtype.name]
+                data.loc[orig_missing, col] = sentinel
+    if ws:
+        warnings.warn(
+            ws,
+            PossiblePrecisionLoss,
+            stacklevel=find_stack_level(),
+        )
+
+    return data
+
+
+class StataValueLabel:
+    """
+    Parse a categorical column and prepare formatted output
+
+    Parameters
+    ----------
+    catarray : Series
+        Categorical Series to encode
+    encoding : {"latin-1", "utf-8"}
+        Encoding to use for value labels.
+    """
+
+    def __init__(
+        self, catarray: Series, encoding: Literal["latin-1", "utf-8"] = "latin-1"
+    ) -> None:
+        if encoding not in ("latin-1", "utf-8"):
+            raise ValueError("Only latin-1 and utf-8 are supported.")
+        self.labname = catarray.name
+        self._encoding = encoding
+        categories = catarray.cat.categories
+        self.value_labels = enumerate(categories)
+
+        self._prepare_value_labels()
+
+    def _prepare_value_labels(self) -> None:
+        """Encode value labels."""
+
+        self.text_len = 0
+        self.txt: list[bytes] = []
+        self.n = 0
+        # Offsets (length of categories), converted to int32
+        self.off = np.array([], dtype=np.int32)
+        # Values, converted to int32
+        self.val = np.array([], dtype=np.int32)
+        self.len = 0
+
+        # Compute lengths and setup lists of offsets and labels
+        offsets: list[int] = []
+        values: list[float] = []
+        for vl in self.value_labels:
+            category: str | bytes = vl[1]
+            if not isinstance(category, str):
+                category = str(category)
+                warnings.warn(
+                    value_label_mismatch_doc.format(self.labname),
+                    ValueLabelTypeMismatch,
+                    stacklevel=find_stack_level(),
+                )
+            category = category.encode(self._encoding)
+            offsets.append(self.text_len)
+            self.text_len += len(category) + 1  # +1 for the padding
+            values.append(vl[0])
+            self.txt.append(category)
+            self.n += 1
+
+        if self.text_len > 32000:
+            raise ValueError(
+                "Stata value labels for a single variable must "
+                "have a combined length less than 32,000 characters."
+            )
+
+        # Ensure int32
+        self.off = np.array(offsets, dtype=np.int32)
+        self.val = np.array(values, dtype=np.int32)
+
+        # Total length
+        self.len = 4 + 4 + 4 * self.n + 4 * self.n + self.text_len
+
+    def generate_value_label(self, byteorder: str) -> bytes:
+        """
+        Generate the binary representation of the value labels.
+
+        Parameters
+        ----------
+        byteorder : str
+            Byte order of the output
+
+        Returns
+        -------
+        value_label : bytes
+            Bytes containing the formatted value label
+        """
+        encoding = self._encoding
+        bio = BytesIO()
+        null_byte = b"\x00"
+
+        # len
+        bio.write(struct.pack(byteorder + "i", self.len))
+
+        # labname
+        labname = str(self.labname)[:32].encode(encoding)
+        lab_len = 32 if encoding not in ("utf-8", "utf8") else 128
+        labname = _pad_bytes(labname, lab_len + 1)
+        bio.write(labname)
+
+        # padding - 3 bytes
+        for i in range(3):
+            bio.write(struct.pack("c", null_byte))
+
+        # value_label_table
+        # n - int32
+        bio.write(struct.pack(byteorder + "i", self.n))
+
+        # textlen  - int32
+        bio.write(struct.pack(byteorder + "i", self.text_len))
+
+        # off - int32 array (n elements)
+        for offset in self.off:
+            bio.write(struct.pack(byteorder + "i", offset))
+
+        # val - int32 array (n elements)
+        for value in self.val:
+            bio.write(struct.pack(byteorder + "i", value))
+
+        # txt - Text labels, null terminated
+        for text in self.txt:
+            bio.write(text + null_byte)
+
+        return bio.getvalue()
+
+
+class StataNonCatValueLabel(StataValueLabel):
+    """
+    Prepare formatted version of value labels
+
+    Parameters
+    ----------
+    labname : str
+        Value label name
+    value_labels: Dictionary
+        Mapping of values to labels
+    encoding : {"latin-1", "utf-8"}
+        Encoding to use for value labels.
+    """
+
+    def __init__(
+        self,
+        labname: str,
+        value_labels: dict[float, str],
+        encoding: Literal["latin-1", "utf-8"] = "latin-1",
+    ) -> None:
+        if encoding not in ("latin-1", "utf-8"):
+            raise ValueError("Only latin-1 and utf-8 are supported.")
+
+        self.labname = labname
+        self._encoding = encoding
+        self.value_labels = sorted(  # type: ignore[assignment]
+            value_labels.items(), key=lambda x: x[0]
+        )
+        self._prepare_value_labels()
+
+
+class StataMissingValue:
+    """
+    An observation's missing value.
+
+    Parameters
+    ----------
+    value : {int, float}
+        The Stata missing value code
+
+    Notes
+    -----
+    More information: 
+
+    Integer missing values make the code '.', '.a', ..., '.z' to the ranges
+    101 ... 127 (for int8), 32741 ... 32767  (for int16) and 2147483621 ...
+    2147483647 (for int32).  Missing values for floating point data types are
+    more complex but the pattern is simple to discern from the following table.
+
+    np.float32 missing values (float in Stata)
+    0000007f    .
+    0008007f    .a
+    0010007f    .b
+    ...
+    00c0007f    .x
+    00c8007f    .y
+    00d0007f    .z
+
+    np.float64 missing values (double in Stata)
+    000000000000e07f    .
+    000000000001e07f    .a
+    000000000002e07f    .b
+    ...
+    000000000018e07f    .x
+    000000000019e07f    .y
+    00000000001ae07f    .z
+    """
+
+    # Construct a dictionary of missing values
+    MISSING_VALUES: dict[float, str] = {}
+    bases: Final = (101, 32741, 2147483621)
+    for b in bases:
+        # Conversion to long to avoid hash issues on 32 bit platforms #8968
+        MISSING_VALUES[b] = "."
+        for i in range(1, 27):
+            MISSING_VALUES[i + b] = "." + chr(96 + i)
+
+    float32_base: bytes = b"\x00\x00\x00\x7f"
+    increment_32: int = struct.unpack(" 0:
+            MISSING_VALUES[key] += chr(96 + i)
+        int_value = struct.unpack(" 0:
+            MISSING_VALUES[key] += chr(96 + i)
+        int_value = struct.unpack("q", struct.pack(" None:
+        self._value = value
+        # Conversion to int to avoid hash issues on 32 bit platforms #8968
+        value = int(value) if value < 2147483648 else float(value)
+        self._str = self.MISSING_VALUES[value]
+
+    @property
+    def string(self) -> str:
+        """
+        The Stata representation of the missing value: '.', '.a'..'.z'
+
+        Returns
+        -------
+        str
+            The representation of the missing value.
+        """
+        return self._str
+
+    @property
+    def value(self) -> float:
+        """
+        The binary representation of the missing value.
+
+        Returns
+        -------
+        {int, float}
+            The binary representation of the missing value.
+        """
+        return self._value
+
+    def __str__(self) -> str:
+        return self.string
+
+    def __repr__(self) -> str:
+        return f"{type(self)}({self})"
+
+    def __eq__(self, other: object) -> bool:
+        return (
+            isinstance(other, type(self))
+            and self.string == other.string
+            and self.value == other.value
+        )
+
+    @classmethod
+    def get_base_missing_value(cls, dtype: np.dtype) -> float:
+        if dtype.type is np.int8:
+            value = cls.BASE_MISSING_VALUES["int8"]
+        elif dtype.type is np.int16:
+            value = cls.BASE_MISSING_VALUES["int16"]
+        elif dtype.type is np.int32:
+            value = cls.BASE_MISSING_VALUES["int32"]
+        elif dtype.type is np.float32:
+            value = cls.BASE_MISSING_VALUES["float32"]
+        elif dtype.type is np.float64:
+            value = cls.BASE_MISSING_VALUES["float64"]
+        else:
+            raise ValueError("Unsupported dtype")
+        return value
+
+
+class StataParser:
+    def __init__(self) -> None:
+        # type          code.
+        # --------------------
+        # str1        1 = 0x01
+        # str2        2 = 0x02
+        # ...
+        # str244    244 = 0xf4
+        # byte      251 = 0xfb  (sic)
+        # int       252 = 0xfc
+        # long      253 = 0xfd
+        # float     254 = 0xfe
+        # double    255 = 0xff
+        # --------------------
+        # NOTE: the byte type seems to be reserved for categorical variables
+        # with a label, but the underlying variable is -127 to 100
+        # we're going to drop the label and cast to int
+        self.DTYPE_MAP = dict(
+            [(i, np.dtype(f"S{i}")) for i in range(1, 245)]
+            + [
+                (251, np.dtype(np.int8)),
+                (252, np.dtype(np.int16)),
+                (253, np.dtype(np.int32)),
+                (254, np.dtype(np.float32)),
+                (255, np.dtype(np.float64)),
+            ]
+        )
+        self.DTYPE_MAP_XML: dict[int, np.dtype] = {
+            32768: np.dtype(np.uint8),  # Keys to GSO
+            65526: np.dtype(np.float64),
+            65527: np.dtype(np.float32),
+            65528: np.dtype(np.int32),
+            65529: np.dtype(np.int16),
+            65530: np.dtype(np.int8),
+        }
+        self.TYPE_MAP = list(tuple(range(251)) + tuple("bhlfd"))
+        self.TYPE_MAP_XML = {
+            # Not really a Q, unclear how to handle byteswap
+            32768: "Q",
+            65526: "d",
+            65527: "f",
+            65528: "l",
+            65529: "h",
+            65530: "b",
+        }
+        # NOTE: technically, some of these are wrong. there are more numbers
+        # that can be represented. it's the 27 ABOVE and BELOW the max listed
+        # numeric data type in [U] 12.2.2 of the 11.2 manual
+        float32_min = b"\xff\xff\xff\xfe"
+        float32_max = b"\xff\xff\xff\x7e"
+        float64_min = b"\xff\xff\xff\xff\xff\xff\xef\xff"
+        float64_max = b"\xff\xff\xff\xff\xff\xff\xdf\x7f"
+        self.VALID_RANGE = {
+            "b": (-127, 100),
+            "h": (-32767, 32740),
+            "l": (-2147483647, 2147483620),
+            "f": (
+                np.float32(struct.unpack(" None:
+        super().__init__()
+
+        # Arguments to the reader (can be temporarily overridden in
+        # calls to read).
+        self._convert_dates = convert_dates
+        self._convert_categoricals = convert_categoricals
+        self._index_col = index_col
+        self._convert_missing = convert_missing
+        self._preserve_dtypes = preserve_dtypes
+        self._columns = columns
+        self._order_categoricals = order_categoricals
+        self._original_path_or_buf = path_or_buf
+        self._compression = compression
+        self._storage_options = storage_options
+        self._encoding = ""
+        self._chunksize = chunksize
+        self._using_iterator = False
+        self._entered = False
+        if self._chunksize is None:
+            self._chunksize = 1
+        elif not isinstance(chunksize, int) or chunksize <= 0:
+            raise ValueError("chunksize must be a positive integer when set.")
+
+        # State variables for the file
+        self._close_file: Callable[[], None] | None = None
+        self._missing_values = False
+        self._can_read_value_labels = False
+        self._column_selector_set = False
+        self._value_labels_read = False
+        self._data_read = False
+        self._dtype: np.dtype | None = None
+        self._lines_read = 0
+
+        self._native_byteorder = _set_endianness(sys.byteorder)
+
+    def _ensure_open(self) -> None:
+        """
+        Ensure the file has been opened and its header data read.
+        """
+        if not hasattr(self, "_path_or_buf"):
+            self._open_file()
+
+    def _open_file(self) -> None:
+        """
+        Open the file (with compression options, etc.), and read header information.
+        """
+        if not self._entered:
+            warnings.warn(
+                "StataReader is being used without using a context manager. "
+                "Using StataReader as a context manager is the only supported method.",
+                ResourceWarning,
+                stacklevel=find_stack_level(),
+            )
+        handles = get_handle(
+            self._original_path_or_buf,
+            "rb",
+            storage_options=self._storage_options,
+            is_text=False,
+            compression=self._compression,
+        )
+        if hasattr(handles.handle, "seekable") and handles.handle.seekable():
+            # If the handle is directly seekable, use it without an extra copy.
+            self._path_or_buf = handles.handle
+            self._close_file = handles.close
+        else:
+            # Copy to memory, and ensure no encoding.
+            with handles:
+                self._path_or_buf = BytesIO(handles.handle.read())
+            self._close_file = self._path_or_buf.close
+
+        self._read_header()
+        self._setup_dtype()
+
+    def __enter__(self) -> Self:
+        """enter context manager"""
+        self._entered = True
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        if self._close_file:
+            self._close_file()
+
+    def close(self) -> None:
+        """Close the handle if its open.
+
+        .. deprecated: 2.0.0
+
+           The close method is not part of the public API.
+           The only supported way to use StataReader is to use it as a context manager.
+        """
+        warnings.warn(
+            "The StataReader.close() method is not part of the public API and "
+            "will be removed in a future version without notice. "
+            "Using StataReader as a context manager is the only supported method.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+        if self._close_file:
+            self._close_file()
+
+    def _set_encoding(self) -> None:
+        """
+        Set string encoding which depends on file version
+        """
+        if self._format_version < 118:
+            self._encoding = "latin-1"
+        else:
+            self._encoding = "utf-8"
+
+    def _read_int8(self) -> int:
+        return struct.unpack("b", self._path_or_buf.read(1))[0]
+
+    def _read_uint8(self) -> int:
+        return struct.unpack("B", self._path_or_buf.read(1))[0]
+
+    def _read_uint16(self) -> int:
+        return struct.unpack(f"{self._byteorder}H", self._path_or_buf.read(2))[0]
+
+    def _read_uint32(self) -> int:
+        return struct.unpack(f"{self._byteorder}I", self._path_or_buf.read(4))[0]
+
+    def _read_uint64(self) -> int:
+        return struct.unpack(f"{self._byteorder}Q", self._path_or_buf.read(8))[0]
+
+    def _read_int16(self) -> int:
+        return struct.unpack(f"{self._byteorder}h", self._path_or_buf.read(2))[0]
+
+    def _read_int32(self) -> int:
+        return struct.unpack(f"{self._byteorder}i", self._path_or_buf.read(4))[0]
+
+    def _read_int64(self) -> int:
+        return struct.unpack(f"{self._byteorder}q", self._path_or_buf.read(8))[0]
+
+    def _read_char8(self) -> bytes:
+        return struct.unpack("c", self._path_or_buf.read(1))[0]
+
+    def _read_int16_count(self, count: int) -> tuple[int, ...]:
+        return struct.unpack(
+            f"{self._byteorder}{'h' * count}",
+            self._path_or_buf.read(2 * count),
+        )
+
+    def _read_header(self) -> None:
+        first_char = self._read_char8()
+        if first_char == b"<":
+            self._read_new_header()
+        else:
+            self._read_old_header(first_char)
+
+    def _read_new_header(self) -> None:
+        # The first part of the header is common to 117 - 119.
+        self._path_or_buf.read(27)  # stata_dta>

+        self._format_version = int(self._path_or_buf.read(3))
+        if self._format_version not in [117, 118, 119]:
+            raise ValueError(_version_error.format(version=self._format_version))
+        self._set_encoding()
+        self._path_or_buf.read(21)  # 
+        self._byteorder = ">" if self._path_or_buf.read(3) == b"MSF" else "<"
+        self._path_or_buf.read(15)  # 
+        self._nvar = (
+            self._read_uint16() if self._format_version <= 118 else self._read_uint32()
+        )
+        self._path_or_buf.read(7)  # 
+
+        self._nobs = self._get_nobs()
+        self._path_or_buf.read(11)  # 
+        self._time_stamp = self._get_time_stamp()
+        self._path_or_buf.read(26)  # 

+        self._path_or_buf.read(8)  # 0x0000000000000000
+        self._path_or_buf.read(8)  # position of 
+
+        self._seek_vartypes = self._read_int64() + 16
+        self._seek_varnames = self._read_int64() + 10
+        self._seek_sortlist = self._read_int64() + 10
+        self._seek_formats = self._read_int64() + 9
+        self._seek_value_label_names = self._read_int64() + 19
+
+        # Requires version-specific treatment
+        self._seek_variable_labels = self._get_seek_variable_labels()
+
+        self._path_or_buf.read(8)  # 
+        self._data_location = self._read_int64() + 6
+        self._seek_strls = self._read_int64() + 7
+        self._seek_value_labels = self._read_int64() + 14
+
+        self._typlist, self._dtyplist = self._get_dtypes(self._seek_vartypes)
+
+        self._path_or_buf.seek(self._seek_varnames)
+        self._varlist = self._get_varlist()
+
+        self._path_or_buf.seek(self._seek_sortlist)
+        self._srtlist = self._read_int16_count(self._nvar + 1)[:-1]
+
+        self._path_or_buf.seek(self._seek_formats)
+        self._fmtlist = self._get_fmtlist()
+
+        self._path_or_buf.seek(self._seek_value_label_names)
+        self._lbllist = self._get_lbllist()
+
+        self._path_or_buf.seek(self._seek_variable_labels)
+        self._variable_labels = self._get_variable_labels()
+
+    # Get data type information, works for versions 117-119.
+    def _get_dtypes(
+        self, seek_vartypes: int
+    ) -> tuple[list[int | str], list[str | np.dtype]]:
+        self._path_or_buf.seek(seek_vartypes)
+        typlist = []
+        dtyplist = []
+        for _ in range(self._nvar):
+            typ = self._read_uint16()
+            if typ <= 2045:
+                typlist.append(typ)
+                dtyplist.append(str(typ))
+            else:
+                try:
+                    typlist.append(self.TYPE_MAP_XML[typ])  # type: ignore[arg-type]
+                    dtyplist.append(self.DTYPE_MAP_XML[typ])  # type: ignore[arg-type]
+                except KeyError as err:
+                    raise ValueError(f"cannot convert stata types [{typ}]") from err
+
+        return typlist, dtyplist  # type: ignore[return-value]
+
+    def _get_varlist(self) -> list[str]:
+        # 33 in order formats, 129 in formats 118 and 119
+        b = 33 if self._format_version < 118 else 129
+        return [self._decode(self._path_or_buf.read(b)) for _ in range(self._nvar)]
+
+    # Returns the format list
+    def _get_fmtlist(self) -> list[str]:
+        if self._format_version >= 118:
+            b = 57
+        elif self._format_version > 113:
+            b = 49
+        elif self._format_version > 104:
+            b = 12
+        else:
+            b = 7
+
+        return [self._decode(self._path_or_buf.read(b)) for _ in range(self._nvar)]
+
+    # Returns the label list
+    def _get_lbllist(self) -> list[str]:
+        if self._format_version >= 118:
+            b = 129
+        elif self._format_version > 108:
+            b = 33
+        else:
+            b = 9
+        return [self._decode(self._path_or_buf.read(b)) for _ in range(self._nvar)]
+
+    def _get_variable_labels(self) -> list[str]:
+        if self._format_version >= 118:
+            vlblist = [
+                self._decode(self._path_or_buf.read(321)) for _ in range(self._nvar)
+            ]
+        elif self._format_version > 105:
+            vlblist = [
+                self._decode(self._path_or_buf.read(81)) for _ in range(self._nvar)
+            ]
+        else:
+            vlblist = [
+                self._decode(self._path_or_buf.read(32)) for _ in range(self._nvar)
+            ]
+        return vlblist
+
+    def _get_nobs(self) -> int:
+        if self._format_version >= 118:
+            return self._read_uint64()
+        else:
+            return self._read_uint32()
+
+    def _get_data_label(self) -> str:
+        if self._format_version >= 118:
+            strlen = self._read_uint16()
+            return self._decode(self._path_or_buf.read(strlen))
+        elif self._format_version == 117:
+            strlen = self._read_int8()
+            return self._decode(self._path_or_buf.read(strlen))
+        elif self._format_version > 105:
+            return self._decode(self._path_or_buf.read(81))
+        else:
+            return self._decode(self._path_or_buf.read(32))
+
+    def _get_time_stamp(self) -> str:
+        if self._format_version >= 118:
+            strlen = self._read_int8()
+            return self._path_or_buf.read(strlen).decode("utf-8")
+        elif self._format_version == 117:
+            strlen = self._read_int8()
+            return self._decode(self._path_or_buf.read(strlen))
+        elif self._format_version > 104:
+            return self._decode(self._path_or_buf.read(18))
+        else:
+            raise ValueError()
+
+    def _get_seek_variable_labels(self) -> int:
+        if self._format_version == 117:
+            self._path_or_buf.read(8)  # , throw away
+            # Stata 117 data files do not follow the described format.  This is
+            # a work around that uses the previous label, 33 bytes for each
+            # variable, 20 for the closing tag and 17 for the opening tag
+            return self._seek_value_label_names + (33 * self._nvar) + 20 + 17
+        elif self._format_version >= 118:
+            return self._read_int64() + 17
+        else:
+            raise ValueError()
+
+    def _read_old_header(self, first_char: bytes) -> None:
+        self._format_version = int(first_char[0])
+        if self._format_version not in [104, 105, 108, 111, 113, 114, 115]:
+            raise ValueError(_version_error.format(version=self._format_version))
+        self._set_encoding()
+        self._byteorder = ">" if self._read_int8() == 0x1 else "<"
+        self._filetype = self._read_int8()
+        self._path_or_buf.read(1)  # unused
+
+        self._nvar = self._read_uint16()
+        self._nobs = self._get_nobs()
+
+        self._data_label = self._get_data_label()
+
+        self._time_stamp = self._get_time_stamp()
+
+        # descriptors
+        if self._format_version > 108:
+            typlist = [int(c) for c in self._path_or_buf.read(self._nvar)]
+        else:
+            buf = self._path_or_buf.read(self._nvar)
+            typlistb = np.frombuffer(buf, dtype=np.uint8)
+            typlist = []
+            for tp in typlistb:
+                if tp in self.OLD_TYPE_MAPPING:
+                    typlist.append(self.OLD_TYPE_MAPPING[tp])
+                else:
+                    typlist.append(tp - 127)  # bytes
+
+        try:
+            self._typlist = [self.TYPE_MAP[typ] for typ in typlist]
+        except ValueError as err:
+            invalid_types = ",".join([str(x) for x in typlist])
+            raise ValueError(f"cannot convert stata types [{invalid_types}]") from err
+        try:
+            self._dtyplist = [self.DTYPE_MAP[typ] for typ in typlist]
+        except ValueError as err:
+            invalid_dtypes = ",".join([str(x) for x in typlist])
+            raise ValueError(f"cannot convert stata dtypes [{invalid_dtypes}]") from err
+
+        if self._format_version > 108:
+            self._varlist = [
+                self._decode(self._path_or_buf.read(33)) for _ in range(self._nvar)
+            ]
+        else:
+            self._varlist = [
+                self._decode(self._path_or_buf.read(9)) for _ in range(self._nvar)
+            ]
+        self._srtlist = self._read_int16_count(self._nvar + 1)[:-1]
+
+        self._fmtlist = self._get_fmtlist()
+
+        self._lbllist = self._get_lbllist()
+
+        self._variable_labels = self._get_variable_labels()
+
+        # ignore expansion fields (Format 105 and later)
+        # When reading, read five bytes; the last four bytes now tell you
+        # the size of the next read, which you discard.  You then continue
+        # like this until you read 5 bytes of zeros.
+
+        if self._format_version > 104:
+            while True:
+                data_type = self._read_int8()
+                if self._format_version > 108:
+                    data_len = self._read_int32()
+                else:
+                    data_len = self._read_int16()
+                if data_type == 0:
+                    break
+                self._path_or_buf.read(data_len)
+
+        # necessary data to continue parsing
+        self._data_location = self._path_or_buf.tell()
+
+    def _setup_dtype(self) -> np.dtype:
+        """Map between numpy and state dtypes"""
+        if self._dtype is not None:
+            return self._dtype
+
+        dtypes = []  # Convert struct data types to numpy data type
+        for i, typ in enumerate(self._typlist):
+            if typ in self.NUMPY_TYPE_MAP:
+                typ = cast(str, typ)  # only strs in NUMPY_TYPE_MAP
+                dtypes.append((f"s{i}", f"{self._byteorder}{self.NUMPY_TYPE_MAP[typ]}"))
+            else:
+                dtypes.append((f"s{i}", f"S{typ}"))
+        self._dtype = np.dtype(dtypes)
+
+        return self._dtype
+
+    def _decode(self, s: bytes) -> str:
+        # have bytes not strings, so must decode
+        s = s.partition(b"\0")[0]
+        try:
+            return s.decode(self._encoding)
+        except UnicodeDecodeError:
+            # GH 25960, fallback to handle incorrect format produced when 117
+            # files are converted to 118 files in Stata
+            encoding = self._encoding
+            msg = f"""
+One or more strings in the dta file could not be decoded using {encoding}, and
+so the fallback encoding of latin-1 is being used.  This can happen when a file
+has been incorrectly encoded by Stata or some other software. You should verify
+the string values returned are correct."""
+            warnings.warn(
+                msg,
+                UnicodeWarning,
+                stacklevel=find_stack_level(),
+            )
+            return s.decode("latin-1")
+
+    def _read_value_labels(self) -> None:
+        self._ensure_open()
+        if self._value_labels_read:
+            # Don't read twice
+            return
+        if self._format_version <= 108:
+            # Value labels are not supported in version 108 and earlier.
+            self._value_labels_read = True
+            self._value_label_dict: dict[str, dict[float, str]] = {}
+            return
+
+        if self._format_version >= 117:
+            self._path_or_buf.seek(self._seek_value_labels)
+        else:
+            assert self._dtype is not None
+            offset = self._nobs * self._dtype.itemsize
+            self._path_or_buf.seek(self._data_location + offset)
+
+        self._value_labels_read = True
+        self._value_label_dict = {}
+
+        while True:
+            if self._format_version >= 117:
+                if self._path_or_buf.read(5) == b"
+                    break  # end of value label table
+
+            slength = self._path_or_buf.read(4)
+            if not slength:
+                break  # end of value label table (format < 117)
+            if self._format_version <= 117:
+                labname = self._decode(self._path_or_buf.read(33))
+            else:
+                labname = self._decode(self._path_or_buf.read(129))
+            self._path_or_buf.read(3)  # padding
+
+            n = self._read_uint32()
+            txtlen = self._read_uint32()
+            off = np.frombuffer(
+                self._path_or_buf.read(4 * n), dtype=f"{self._byteorder}i4", count=n
+            )
+            val = np.frombuffer(
+                self._path_or_buf.read(4 * n), dtype=f"{self._byteorder}i4", count=n
+            )
+            ii = np.argsort(off)
+            off = off[ii]
+            val = val[ii]
+            txt = self._path_or_buf.read(txtlen)
+            self._value_label_dict[labname] = {}
+            for i in range(n):
+                end = off[i + 1] if i < n - 1 else txtlen
+                self._value_label_dict[labname][val[i]] = self._decode(
+                    txt[off[i] : end]
+                )
+            if self._format_version >= 117:
+                self._path_or_buf.read(6)  # 
+        self._value_labels_read = True
+
+    def _read_strls(self) -> None:
+        self._path_or_buf.seek(self._seek_strls)
+        # Wrap v_o in a string to allow uint64 values as keys on 32bit OS
+        self.GSO = {"0": ""}
+        while True:
+            if self._path_or_buf.read(3) != b"GSO":
+                break
+
+            if self._format_version == 117:
+                v_o = self._read_uint64()
+            else:
+                buf = self._path_or_buf.read(12)
+                # Only tested on little endian file on little endian machine.
+                v_size = 2 if self._format_version == 118 else 3
+                if self._byteorder == "<":
+                    buf = buf[0:v_size] + buf[4 : (12 - v_size)]
+                else:
+                    # This path may not be correct, impossible to test
+                    buf = buf[0:v_size] + buf[(4 + v_size) :]
+                v_o = struct.unpack("Q", buf)[0]
+            typ = self._read_uint8()
+            length = self._read_uint32()
+            va = self._path_or_buf.read(length)
+            if typ == 130:
+                decoded_va = va[0:-1].decode(self._encoding)
+            else:
+                # Stata says typ 129 can be binary, so use str
+                decoded_va = str(va)
+                # Wrap v_o in a string to allow uint64 values as keys on 32bit OS
+            self.GSO[str(v_o)] = decoded_va
+
+    def __next__(self) -> DataFrame:
+        self._using_iterator = True
+        return self.read(nrows=self._chunksize)
+
+    def get_chunk(self, size: int | None = None) -> DataFrame:
+        """
+        Reads lines from Stata file and returns as dataframe
+
+        Parameters
+        ----------
+        size : int, defaults to None
+            Number of lines to read.  If None, reads whole file.
+
+        Returns
+        -------
+        DataFrame
+        """
+        if size is None:
+            size = self._chunksize
+        return self.read(nrows=size)
+
+    @Appender(_read_method_doc)
+    def read(
+        self,
+        nrows: int | None = None,
+        convert_dates: bool | None = None,
+        convert_categoricals: bool | None = None,
+        index_col: str | None = None,
+        convert_missing: bool | None = None,
+        preserve_dtypes: bool | None = None,
+        columns: Sequence[str] | None = None,
+        order_categoricals: bool | None = None,
+    ) -> DataFrame:
+        self._ensure_open()
+
+        # Handle options
+        if convert_dates is None:
+            convert_dates = self._convert_dates
+        if convert_categoricals is None:
+            convert_categoricals = self._convert_categoricals
+        if convert_missing is None:
+            convert_missing = self._convert_missing
+        if preserve_dtypes is None:
+            preserve_dtypes = self._preserve_dtypes
+        if columns is None:
+            columns = self._columns
+        if order_categoricals is None:
+            order_categoricals = self._order_categoricals
+        if index_col is None:
+            index_col = self._index_col
+        if nrows is None:
+            nrows = self._nobs
+
+        # Handle empty file or chunk.  If reading incrementally raise
+        # StopIteration.  If reading the whole thing return an empty
+        # data frame.
+        if (self._nobs == 0) and nrows == 0:
+            self._can_read_value_labels = True
+            self._data_read = True
+            data = DataFrame(columns=self._varlist)
+            # Apply dtypes correctly
+            for i, col in enumerate(data.columns):
+                dt = self._dtyplist[i]
+                if isinstance(dt, np.dtype):
+                    if dt.char != "S":
+                        data[col] = data[col].astype(dt)
+            if columns is not None:
+                data = self._do_select_columns(data, columns)
+            return data
+
+        if (self._format_version >= 117) and (not self._value_labels_read):
+            self._can_read_value_labels = True
+            self._read_strls()
+
+        # Read data
+        assert self._dtype is not None
+        dtype = self._dtype
+        max_read_len = (self._nobs - self._lines_read) * dtype.itemsize
+        read_len = nrows * dtype.itemsize
+        read_len = min(read_len, max_read_len)
+        if read_len <= 0:
+            # Iterator has finished, should never be here unless
+            # we are reading the file incrementally
+            if convert_categoricals:
+                self._read_value_labels()
+            raise StopIteration
+        offset = self._lines_read * dtype.itemsize
+        self._path_or_buf.seek(self._data_location + offset)
+        read_lines = min(nrows, self._nobs - self._lines_read)
+        raw_data = np.frombuffer(
+            self._path_or_buf.read(read_len), dtype=dtype, count=read_lines
+        )
+
+        self._lines_read += read_lines
+        if self._lines_read == self._nobs:
+            self._can_read_value_labels = True
+            self._data_read = True
+        # if necessary, swap the byte order to native here
+        if self._byteorder != self._native_byteorder:
+            raw_data = raw_data.byteswap().view(raw_data.dtype.newbyteorder())
+
+        if convert_categoricals:
+            self._read_value_labels()
+
+        if len(raw_data) == 0:
+            data = DataFrame(columns=self._varlist)
+        else:
+            data = DataFrame.from_records(raw_data)
+            data.columns = Index(self._varlist)
+
+        # If index is not specified, use actual row number rather than
+        # restarting at 0 for each chunk.
+        if index_col is None:
+            data.index = RangeIndex(
+                self._lines_read - read_lines, self._lines_read
+            )  # set attr instead of set_index to avoid copy
+
+        if columns is not None:
+            data = self._do_select_columns(data, columns)
+
+        # Decode strings
+        for col, typ in zip(data, self._typlist):
+            if isinstance(typ, int):
+                data[col] = data[col].apply(self._decode)
+
+        data = self._insert_strls(data)
+
+        # Convert columns (if needed) to match input type
+        valid_dtypes = [i for i, dtyp in enumerate(self._dtyplist) if dtyp is not None]
+        object_type = np.dtype(object)
+        for idx in valid_dtypes:
+            dtype = data.iloc[:, idx].dtype
+            if dtype not in (object_type, self._dtyplist[idx]):
+                data.isetitem(idx, data.iloc[:, idx].astype(dtype))
+
+        data = self._do_convert_missing(data, convert_missing)
+
+        if convert_dates:
+            for i, fmt in enumerate(self._fmtlist):
+                if any(fmt.startswith(date_fmt) for date_fmt in _date_formats):
+                    data.isetitem(
+                        i, _stata_elapsed_date_to_datetime_vec(data.iloc[:, i], fmt)
+                    )
+
+        if convert_categoricals and self._format_version > 108:
+            data = self._do_convert_categoricals(
+                data, self._value_label_dict, self._lbllist, order_categoricals
+            )
+
+        if not preserve_dtypes:
+            retyped_data = []
+            convert = False
+            for col in data:
+                dtype = data[col].dtype
+                if dtype in (np.dtype(np.float16), np.dtype(np.float32)):
+                    dtype = np.dtype(np.float64)
+                    convert = True
+                elif dtype in (
+                    np.dtype(np.int8),
+                    np.dtype(np.int16),
+                    np.dtype(np.int32),
+                ):
+                    dtype = np.dtype(np.int64)
+                    convert = True
+                retyped_data.append((col, data[col].astype(dtype)))
+            if convert:
+                data = DataFrame.from_dict(dict(retyped_data))
+
+        if index_col is not None:
+            data = data.set_index(data.pop(index_col))
+
+        return data
+
+    def _do_convert_missing(self, data: DataFrame, convert_missing: bool) -> DataFrame:
+        # Check for missing values, and replace if found
+        replacements = {}
+        for i in range(len(data.columns)):
+            fmt = self._typlist[i]
+            if fmt not in self.VALID_RANGE:
+                continue
+
+            fmt = cast(str, fmt)  # only strs in VALID_RANGE
+            nmin, nmax = self.VALID_RANGE[fmt]
+            series = data.iloc[:, i]
+
+            # appreciably faster to do this with ndarray instead of Series
+            svals = series._values
+            missing = (svals < nmin) | (svals > nmax)
+
+            if not missing.any():
+                continue
+
+            if convert_missing:  # Replacement follows Stata notation
+                missing_loc = np.nonzero(np.asarray(missing))[0]
+                umissing, umissing_loc = np.unique(series[missing], return_inverse=True)
+                replacement = Series(series, dtype=object)
+                for j, um in enumerate(umissing):
+                    missing_value = StataMissingValue(um)
+
+                    loc = missing_loc[umissing_loc == j]
+                    replacement.iloc[loc] = missing_value
+            else:  # All replacements are identical
+                dtype = series.dtype
+                if dtype not in (np.float32, np.float64):
+                    dtype = np.float64
+                replacement = Series(series, dtype=dtype)
+                if not replacement._values.flags["WRITEABLE"]:
+                    # only relevant for ArrayManager; construction
+                    #  path for BlockManager ensures writeability
+                    replacement = replacement.copy()
+                # Note: operating on ._values is much faster than directly
+                # TODO: can we fix that?
+                replacement._values[missing] = np.nan
+            replacements[i] = replacement
+        if replacements:
+            for idx, value in replacements.items():
+                data.isetitem(idx, value)
+        return data
+
+    def _insert_strls(self, data: DataFrame) -> DataFrame:
+        if not hasattr(self, "GSO") or len(self.GSO) == 0:
+            return data
+        for i, typ in enumerate(self._typlist):
+            if typ != "Q":
+                continue
+            # Wrap v_o in a string to allow uint64 values as keys on 32bit OS
+            data.isetitem(i, [self.GSO[str(k)] for k in data.iloc[:, i]])
+        return data
+
+    def _do_select_columns(self, data: DataFrame, columns: Sequence[str]) -> DataFrame:
+        if not self._column_selector_set:
+            column_set = set(columns)
+            if len(column_set) != len(columns):
+                raise ValueError("columns contains duplicate entries")
+            unmatched = column_set.difference(data.columns)
+            if unmatched:
+                joined = ", ".join(list(unmatched))
+                raise ValueError(
+                    "The following columns were not "
+                    f"found in the Stata data set: {joined}"
+                )
+            # Copy information for retained columns for later processing
+            dtyplist = []
+            typlist = []
+            fmtlist = []
+            lbllist = []
+            for col in columns:
+                i = data.columns.get_loc(col)
+                dtyplist.append(self._dtyplist[i])
+                typlist.append(self._typlist[i])
+                fmtlist.append(self._fmtlist[i])
+                lbllist.append(self._lbllist[i])
+
+            self._dtyplist = dtyplist
+            self._typlist = typlist
+            self._fmtlist = fmtlist
+            self._lbllist = lbllist
+            self._column_selector_set = True
+
+        return data[columns]
+
+    def _do_convert_categoricals(
+        self,
+        data: DataFrame,
+        value_label_dict: dict[str, dict[float, str]],
+        lbllist: Sequence[str],
+        order_categoricals: bool,
+    ) -> DataFrame:
+        """
+        Converts categorical columns to Categorical type.
+        """
+        if not value_label_dict:
+            return data
+        cat_converted_data = []
+        for col, label in zip(data, lbllist):
+            if label in value_label_dict:
+                # Explicit call with ordered=True
+                vl = value_label_dict[label]
+                keys = np.array(list(vl.keys()))
+                column = data[col]
+                key_matches = column.isin(keys)
+                if self._using_iterator and key_matches.all():
+                    initial_categories: np.ndarray | None = keys
+                    # If all categories are in the keys and we are iterating,
+                    # use the same keys for all chunks. If some are missing
+                    # value labels, then we will fall back to the categories
+                    # varying across chunks.
+                else:
+                    if self._using_iterator:
+                        # warn is using an iterator
+                        warnings.warn(
+                            categorical_conversion_warning,
+                            CategoricalConversionWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                    initial_categories = None
+                cat_data = Categorical(
+                    column, categories=initial_categories, ordered=order_categoricals
+                )
+                if initial_categories is None:
+                    # If None here, then we need to match the cats in the Categorical
+                    categories = []
+                    for category in cat_data.categories:
+                        if category in vl:
+                            categories.append(vl[category])
+                        else:
+                            categories.append(category)
+                else:
+                    # If all cats are matched, we can use the values
+                    categories = list(vl.values())
+                try:
+                    # Try to catch duplicate categories
+                    # TODO: if we get a non-copying rename_categories, use that
+                    cat_data = cat_data.rename_categories(categories)
+                except ValueError as err:
+                    vc = Series(categories, copy=False).value_counts()
+                    repeated_cats = list(vc.index[vc > 1])
+                    repeats = "-" * 80 + "\n" + "\n".join(repeated_cats)
+                    # GH 25772
+                    msg = f"""
+Value labels for column {col} are not unique. These cannot be converted to
+pandas categoricals.
+
+Either read the file with `convert_categoricals` set to False or use the
+low level interface in `StataReader` to separately read the values and the
+value_labels.
+
+The repeated labels are:
+{repeats}
+"""
+                    raise ValueError(msg) from err
+                # TODO: is the next line needed above in the data(...) method?
+                cat_series = Series(cat_data, index=data.index, copy=False)
+                cat_converted_data.append((col, cat_series))
+            else:
+                cat_converted_data.append((col, data[col]))
+        data = DataFrame(dict(cat_converted_data), copy=False)
+        return data
+
+    @property
+    def data_label(self) -> str:
+        """
+        Return data label of Stata file.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([(1,)], columns=["variable"])
+        >>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
+        >>> data_label = "This is a data file."
+        >>> path = "/My_path/filename.dta"
+        >>> df.to_stata(path, time_stamp=time_stamp,    # doctest: +SKIP
+        ...             data_label=data_label,  # doctest: +SKIP
+        ...             version=None)  # doctest: +SKIP
+        >>> with pd.io.stata.StataReader(path) as reader:  # doctest: +SKIP
+        ...     print(reader.data_label)  # doctest: +SKIP
+        This is a data file.
+        """
+        self._ensure_open()
+        return self._data_label
+
+    @property
+    def time_stamp(self) -> str:
+        """
+        Return time stamp of Stata file.
+        """
+        self._ensure_open()
+        return self._time_stamp
+
+    def variable_labels(self) -> dict[str, str]:
+        """
+        Return a dict associating each variable name with corresponding label.
+
+        Returns
+        -------
+        dict
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=["col_1", "col_2"])
+        >>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
+        >>> path = "/My_path/filename.dta"
+        >>> variable_labels = {"col_1": "This is an example"}
+        >>> df.to_stata(path, time_stamp=time_stamp,  # doctest: +SKIP
+        ...             variable_labels=variable_labels, version=None)  # doctest: +SKIP
+        >>> with pd.io.stata.StataReader(path) as reader:  # doctest: +SKIP
+        ...     print(reader.variable_labels())  # doctest: +SKIP
+        {'index': '', 'col_1': 'This is an example', 'col_2': ''}
+        >>> pd.read_stata(path)  # doctest: +SKIP
+            index col_1 col_2
+        0       0    1    2
+        1       1    3    4
+        """
+        self._ensure_open()
+        return dict(zip(self._varlist, self._variable_labels))
+
+    def value_labels(self) -> dict[str, dict[float, str]]:
+        """
+        Return a nested dict associating each variable name to its value and label.
+
+        Returns
+        -------
+        dict
+
+        Examples
+        --------
+        >>> df = pd.DataFrame([[1, 2], [3, 4]], columns=["col_1", "col_2"])
+        >>> time_stamp = pd.Timestamp(2000, 2, 29, 14, 21)
+        >>> path = "/My_path/filename.dta"
+        >>> value_labels = {"col_1": {3: "x"}}
+        >>> df.to_stata(path, time_stamp=time_stamp,  # doctest: +SKIP
+        ...             value_labels=value_labels, version=None)  # doctest: +SKIP
+        >>> with pd.io.stata.StataReader(path) as reader:  # doctest: +SKIP
+        ...     print(reader.value_labels())  # doctest: +SKIP
+        {'col_1': {3: 'x'}}
+        >>> pd.read_stata(path)  # doctest: +SKIP
+            index col_1 col_2
+        0       0    1    2
+        1       1    x    4
+        """
+        if not self._value_labels_read:
+            self._read_value_labels()
+
+        return self._value_label_dict
+
+
+@Appender(_read_stata_doc)
+def read_stata(
+    filepath_or_buffer: FilePath | ReadBuffer[bytes],
+    *,
+    convert_dates: bool = True,
+    convert_categoricals: bool = True,
+    index_col: str | None = None,
+    convert_missing: bool = False,
+    preserve_dtypes: bool = True,
+    columns: Sequence[str] | None = None,
+    order_categoricals: bool = True,
+    chunksize: int | None = None,
+    iterator: bool = False,
+    compression: CompressionOptions = "infer",
+    storage_options: StorageOptions | None = None,
+) -> DataFrame | StataReader:
+    reader = StataReader(
+        filepath_or_buffer,
+        convert_dates=convert_dates,
+        convert_categoricals=convert_categoricals,
+        index_col=index_col,
+        convert_missing=convert_missing,
+        preserve_dtypes=preserve_dtypes,
+        columns=columns,
+        order_categoricals=order_categoricals,
+        chunksize=chunksize,
+        storage_options=storage_options,
+        compression=compression,
+    )
+
+    if iterator or chunksize:
+        return reader
+
+    with reader:
+        return reader.read()
+
+
+def _set_endianness(endianness: str) -> str:
+    if endianness.lower() in ["<", "little"]:
+        return "<"
+    elif endianness.lower() in [">", "big"]:
+        return ">"
+    else:  # pragma : no cover
+        raise ValueError(f"Endianness {endianness} not understood")
+
+
+def _pad_bytes(name: AnyStr, length: int) -> AnyStr:
+    """
+    Take a char string and pads it with null bytes until it's length chars.
+    """
+    if isinstance(name, bytes):
+        return name + b"\x00" * (length - len(name))
+    return name + "\x00" * (length - len(name))
+
+
+def _convert_datetime_to_stata_type(fmt: str) -> np.dtype:
+    """
+    Convert from one of the stata date formats to a type in TYPE_MAP.
+    """
+    if fmt in [
+        "tc",
+        "%tc",
+        "td",
+        "%td",
+        "tw",
+        "%tw",
+        "tm",
+        "%tm",
+        "tq",
+        "%tq",
+        "th",
+        "%th",
+        "ty",
+        "%ty",
+    ]:
+        return np.dtype(np.float64)  # Stata expects doubles for SIFs
+    else:
+        raise NotImplementedError(f"Format {fmt} not implemented")
+
+
+def _maybe_convert_to_int_keys(convert_dates: dict, varlist: list[Hashable]) -> dict:
+    new_dict = {}
+    for key in convert_dates:
+        if not convert_dates[key].startswith("%"):  # make sure proper fmts
+            convert_dates[key] = "%" + convert_dates[key]
+        if key in varlist:
+            new_dict.update({varlist.index(key): convert_dates[key]})
+        else:
+            if not isinstance(key, int):
+                raise ValueError("convert_dates key must be a column or an integer")
+            new_dict.update({key: convert_dates[key]})
+    return new_dict
+
+
+def _dtype_to_stata_type(dtype: np.dtype, column: Series) -> int:
+    """
+    Convert dtype types to stata types. Returns the byte of the given ordinal.
+    See TYPE_MAP and comments for an explanation. This is also explained in
+    the dta spec.
+    1 - 244 are strings of this length
+                         Pandas    Stata
+    251 - for int8      byte
+    252 - for int16     int
+    253 - for int32     long
+    254 - for float32   float
+    255 - for double    double
+
+    If there are dates to convert, then dtype will already have the correct
+    type inserted.
+    """
+    # TODO: expand to handle datetime to integer conversion
+    if dtype.type is np.object_:  # try to coerce it to the biggest string
+        # not memory efficient, what else could we
+        # do?
+        itemsize = max_len_string_array(ensure_object(column._values))
+        return max(itemsize, 1)
+    elif dtype.type is np.float64:
+        return 255
+    elif dtype.type is np.float32:
+        return 254
+    elif dtype.type is np.int32:
+        return 253
+    elif dtype.type is np.int16:
+        return 252
+    elif dtype.type is np.int8:
+        return 251
+    else:  # pragma : no cover
+        raise NotImplementedError(f"Data type {dtype} not supported.")
+
+
+def _dtype_to_default_stata_fmt(
+    dtype, column: Series, dta_version: int = 114, force_strl: bool = False
+) -> str:
+    """
+    Map numpy dtype to stata's default format for this type. Not terribly
+    important since users can change this in Stata. Semantics are
+
+    object  -> "%DDs" where DD is the length of the string.  If not a string,
+                raise ValueError
+    float64 -> "%10.0g"
+    float32 -> "%9.0g"
+    int64   -> "%9.0g"
+    int32   -> "%12.0g"
+    int16   -> "%8.0g"
+    int8    -> "%8.0g"
+    strl    -> "%9s"
+    """
+    # TODO: Refactor to combine type with format
+    # TODO: expand this to handle a default datetime format?
+    if dta_version < 117:
+        max_str_len = 244
+    else:
+        max_str_len = 2045
+        if force_strl:
+            return "%9s"
+    if dtype.type is np.object_:
+        itemsize = max_len_string_array(ensure_object(column._values))
+        if itemsize > max_str_len:
+            if dta_version >= 117:
+                return "%9s"
+            else:
+                raise ValueError(excessive_string_length_error.format(column.name))
+        return "%" + str(max(itemsize, 1)) + "s"
+    elif dtype == np.float64:
+        return "%10.0g"
+    elif dtype == np.float32:
+        return "%9.0g"
+    elif dtype == np.int32:
+        return "%12.0g"
+    elif dtype in (np.int8, np.int16):
+        return "%8.0g"
+    else:  # pragma : no cover
+        raise NotImplementedError(f"Data type {dtype} not supported.")
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    compression_options=_shared_docs["compression_options"] % "fname",
+)
+class StataWriter(StataParser):
+    """
+    A class for writing Stata binary dta files
+
+    Parameters
+    ----------
+    fname : path (string), buffer or path object
+        string, path object (pathlib.Path or py._path.local.LocalPath) or
+        object implementing a binary write() functions. If using a buffer
+        then the buffer will not be automatically closed after the file
+        is written.
+    data : DataFrame
+        Input to save
+    convert_dates : dict
+        Dictionary mapping columns containing datetime types to stata internal
+        format to use when writing the dates. Options are 'tc', 'td', 'tm',
+        'tw', 'th', 'tq', 'ty'. Column can be either an integer or a name.
+        Datetime columns that do not have a conversion type specified will be
+        converted to 'tc'. Raises NotImplementedError if a datetime column has
+        timezone information
+    write_index : bool
+        Write the index to Stata dataset.
+    byteorder : str
+        Can be ">", "<", "little", or "big". default is `sys.byteorder`
+    time_stamp : datetime
+        A datetime to use as file creation date.  Default is the current time
+    data_label : str
+        A label for the data set.  Must be 80 characters or smaller.
+    variable_labels : dict
+        Dictionary containing columns as keys and variable labels as values.
+        Each label must be 80 characters or smaller.
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    {storage_options}
+
+    value_labels : dict of dicts
+        Dictionary containing columns as keys and dictionaries of column value
+        to labels as values. The combined length of all labels for a single
+        variable must be 32,000 characters or smaller.
+
+        .. versionadded:: 1.4.0
+
+    Returns
+    -------
+    writer : StataWriter instance
+        The StataWriter instance has a write_file method, which will
+        write the file to the given `fname`.
+
+    Raises
+    ------
+    NotImplementedError
+        * If datetimes contain timezone information
+    ValueError
+        * Columns listed in convert_dates are neither datetime64[ns]
+          or datetime
+        * Column dtype is not representable in Stata
+        * Column listed in convert_dates is not in DataFrame
+        * Categorical label contains more than 32,000 characters
+
+    Examples
+    --------
+    >>> data = pd.DataFrame([[1.0, 1]], columns=['a', 'b'])
+    >>> writer = StataWriter('./data_file.dta', data)
+    >>> writer.write_file()
+
+    Directly write a zip file
+    >>> compression = {{"method": "zip", "archive_name": "data_file.dta"}}
+    >>> writer = StataWriter('./data_file.zip', data, compression=compression)
+    >>> writer.write_file()
+
+    Save a DataFrame with dates
+    >>> from datetime import datetime
+    >>> data = pd.DataFrame([[datetime(2000,1,1)]], columns=['date'])
+    >>> writer = StataWriter('./date_data_file.dta', data, {{'date' : 'tw'}})
+    >>> writer.write_file()
+    """
+
+    _max_string_length = 244
+    _encoding: Literal["latin-1", "utf-8"] = "latin-1"
+
+    def __init__(
+        self,
+        fname: FilePath | WriteBuffer[bytes],
+        data: DataFrame,
+        convert_dates: dict[Hashable, str] | None = None,
+        write_index: bool = True,
+        byteorder: str | None = None,
+        time_stamp: datetime | None = None,
+        data_label: str | None = None,
+        variable_labels: dict[Hashable, str] | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+        *,
+        value_labels: dict[Hashable, dict[float, str]] | None = None,
+    ) -> None:
+        super().__init__()
+        self.data = data
+        self._convert_dates = {} if convert_dates is None else convert_dates
+        self._write_index = write_index
+        self._time_stamp = time_stamp
+        self._data_label = data_label
+        self._variable_labels = variable_labels
+        self._non_cat_value_labels = value_labels
+        self._value_labels: list[StataValueLabel] = []
+        self._has_value_labels = np.array([], dtype=bool)
+        self._compression = compression
+        self._output_file: IO[bytes] | None = None
+        self._converted_names: dict[Hashable, str] = {}
+        # attach nobs, nvars, data, varlist, typlist
+        self._prepare_pandas(data)
+        self.storage_options = storage_options
+
+        if byteorder is None:
+            byteorder = sys.byteorder
+        self._byteorder = _set_endianness(byteorder)
+        self._fname = fname
+        self.type_converters = {253: np.int32, 252: np.int16, 251: np.int8}
+
+    def _write(self, to_write: str) -> None:
+        """
+        Helper to call encode before writing to file for Python 3 compat.
+        """
+        self.handles.handle.write(to_write.encode(self._encoding))
+
+    def _write_bytes(self, value: bytes) -> None:
+        """
+        Helper to assert file is open before writing.
+        """
+        self.handles.handle.write(value)
+
+    def _prepare_non_cat_value_labels(
+        self, data: DataFrame
+    ) -> list[StataNonCatValueLabel]:
+        """
+        Check for value labels provided for non-categorical columns. Value
+        labels
+        """
+        non_cat_value_labels: list[StataNonCatValueLabel] = []
+        if self._non_cat_value_labels is None:
+            return non_cat_value_labels
+
+        for labname, labels in self._non_cat_value_labels.items():
+            if labname in self._converted_names:
+                colname = self._converted_names[labname]
+            elif labname in data.columns:
+                colname = str(labname)
+            else:
+                raise KeyError(
+                    f"Can't create value labels for {labname}, it wasn't "
+                    "found in the dataset."
+                )
+
+            if not is_numeric_dtype(data[colname].dtype):
+                # Labels should not be passed explicitly for categorical
+                # columns that will be converted to int
+                raise ValueError(
+                    f"Can't create value labels for {labname}, value labels "
+                    "can only be applied to numeric columns."
+                )
+            svl = StataNonCatValueLabel(colname, labels, self._encoding)
+            non_cat_value_labels.append(svl)
+        return non_cat_value_labels
+
+    def _prepare_categoricals(self, data: DataFrame) -> DataFrame:
+        """
+        Check for categorical columns, retain categorical information for
+        Stata file and convert categorical data to int
+        """
+        is_cat = [isinstance(dtype, CategoricalDtype) for dtype in data.dtypes]
+        if not any(is_cat):
+            return data
+
+        self._has_value_labels |= np.array(is_cat)
+
+        get_base_missing_value = StataMissingValue.get_base_missing_value
+        data_formatted = []
+        for col, col_is_cat in zip(data, is_cat):
+            if col_is_cat:
+                svl = StataValueLabel(data[col], encoding=self._encoding)
+                self._value_labels.append(svl)
+                dtype = data[col].cat.codes.dtype
+                if dtype == np.int64:
+                    raise ValueError(
+                        "It is not possible to export "
+                        "int64-based categorical data to Stata."
+                    )
+                values = data[col].cat.codes._values.copy()
+
+                # Upcast if needed so that correct missing values can be set
+                if values.max() >= get_base_missing_value(dtype):
+                    if dtype == np.int8:
+                        dtype = np.dtype(np.int16)
+                    elif dtype == np.int16:
+                        dtype = np.dtype(np.int32)
+                    else:
+                        dtype = np.dtype(np.float64)
+                    values = np.array(values, dtype=dtype)
+
+                # Replace missing values with Stata missing value for type
+                values[values == -1] = get_base_missing_value(dtype)
+                data_formatted.append((col, values))
+            else:
+                data_formatted.append((col, data[col]))
+        return DataFrame.from_dict(dict(data_formatted))
+
+    def _replace_nans(self, data: DataFrame) -> DataFrame:
+        # return data
+        """
+        Checks floating point data columns for nans, and replaces these with
+        the generic Stata for missing value (.)
+        """
+        for c in data:
+            dtype = data[c].dtype
+            if dtype in (np.float32, np.float64):
+                if dtype == np.float32:
+                    replacement = self.MISSING_VALUES["f"]
+                else:
+                    replacement = self.MISSING_VALUES["d"]
+                data[c] = data[c].fillna(replacement)
+
+        return data
+
+    def _update_strl_names(self) -> None:
+        """No-op, forward compatibility"""
+
+    def _validate_variable_name(self, name: str) -> str:
+        """
+        Validate variable names for Stata export.
+
+        Parameters
+        ----------
+        name : str
+            Variable name
+
+        Returns
+        -------
+        str
+            The validated name with invalid characters replaced with
+            underscores.
+
+        Notes
+        -----
+        Stata 114 and 117 support ascii characters in a-z, A-Z, 0-9
+        and _.
+        """
+        for c in name:
+            if (
+                (c < "A" or c > "Z")
+                and (c < "a" or c > "z")
+                and (c < "0" or c > "9")
+                and c != "_"
+            ):
+                name = name.replace(c, "_")
+        return name
+
+    def _check_column_names(self, data: DataFrame) -> DataFrame:
+        """
+        Checks column names to ensure that they are valid Stata column names.
+        This includes checks for:
+            * Non-string names
+            * Stata keywords
+            * Variables that start with numbers
+            * Variables with names that are too long
+
+        When an illegal variable name is detected, it is converted, and if
+        dates are exported, the variable name is propagated to the date
+        conversion dictionary
+        """
+        converted_names: dict[Hashable, str] = {}
+        columns = list(data.columns)
+        original_columns = columns[:]
+
+        duplicate_var_id = 0
+        for j, name in enumerate(columns):
+            orig_name = name
+            if not isinstance(name, str):
+                name = str(name)
+
+            name = self._validate_variable_name(name)
+
+            # Variable name must not be a reserved word
+            if name in self.RESERVED_WORDS:
+                name = "_" + name
+
+            # Variable name may not start with a number
+            if "0" <= name[0] <= "9":
+                name = "_" + name
+
+            name = name[: min(len(name), 32)]
+
+            if not name == orig_name:
+                # check for duplicates
+                while columns.count(name) > 0:
+                    # prepend ascending number to avoid duplicates
+                    name = "_" + str(duplicate_var_id) + name
+                    name = name[: min(len(name), 32)]
+                    duplicate_var_id += 1
+                converted_names[orig_name] = name
+
+            columns[j] = name
+
+        data.columns = Index(columns)
+
+        # Check date conversion, and fix key if needed
+        if self._convert_dates:
+            for c, o in zip(columns, original_columns):
+                if c != o:
+                    self._convert_dates[c] = self._convert_dates[o]
+                    del self._convert_dates[o]
+
+        if converted_names:
+            conversion_warning = []
+            for orig_name, name in converted_names.items():
+                msg = f"{orig_name}   ->   {name}"
+                conversion_warning.append(msg)
+
+            ws = invalid_name_doc.format("\n    ".join(conversion_warning))
+            warnings.warn(
+                ws,
+                InvalidColumnName,
+                stacklevel=find_stack_level(),
+            )
+
+        self._converted_names = converted_names
+        self._update_strl_names()
+
+        return data
+
+    def _set_formats_and_types(self, dtypes: Series) -> None:
+        self.fmtlist: list[str] = []
+        self.typlist: list[int] = []
+        for col, dtype in dtypes.items():
+            self.fmtlist.append(_dtype_to_default_stata_fmt(dtype, self.data[col]))
+            self.typlist.append(_dtype_to_stata_type(dtype, self.data[col]))
+
+    def _prepare_pandas(self, data: DataFrame) -> None:
+        # NOTE: we might need a different API / class for pandas objects so
+        # we can set different semantics - handle this with a PR to pandas.io
+
+        data = data.copy()
+
+        if self._write_index:
+            temp = data.reset_index()
+            if isinstance(temp, DataFrame):
+                data = temp
+
+        # Ensure column names are strings
+        data = self._check_column_names(data)
+
+        # Check columns for compatibility with stata, upcast if necessary
+        # Raise if outside the supported range
+        data = _cast_to_stata_types(data)
+
+        # Replace NaNs with Stata missing values
+        data = self._replace_nans(data)
+
+        # Set all columns to initially unlabelled
+        self._has_value_labels = np.repeat(False, data.shape[1])
+
+        # Create value labels for non-categorical data
+        non_cat_value_labels = self._prepare_non_cat_value_labels(data)
+
+        non_cat_columns = [svl.labname for svl in non_cat_value_labels]
+        has_non_cat_val_labels = data.columns.isin(non_cat_columns)
+        self._has_value_labels |= has_non_cat_val_labels
+        self._value_labels.extend(non_cat_value_labels)
+
+        # Convert categoricals to int data, and strip labels
+        data = self._prepare_categoricals(data)
+
+        self.nobs, self.nvar = data.shape
+        self.data = data
+        self.varlist = data.columns.tolist()
+
+        dtypes = data.dtypes
+
+        # Ensure all date columns are converted
+        for col in data:
+            if col in self._convert_dates:
+                continue
+            if lib.is_np_dtype(data[col].dtype, "M"):
+                self._convert_dates[col] = "tc"
+
+        self._convert_dates = _maybe_convert_to_int_keys(
+            self._convert_dates, self.varlist
+        )
+        for key in self._convert_dates:
+            new_type = _convert_datetime_to_stata_type(self._convert_dates[key])
+            dtypes.iloc[key] = np.dtype(new_type)
+
+        # Verify object arrays are strings and encode to bytes
+        self._encode_strings()
+
+        self._set_formats_and_types(dtypes)
+
+        # set the given format for the datetime cols
+        if self._convert_dates is not None:
+            for key in self._convert_dates:
+                if isinstance(key, int):
+                    self.fmtlist[key] = self._convert_dates[key]
+
+    def _encode_strings(self) -> None:
+        """
+        Encode strings in dta-specific encoding
+
+        Do not encode columns marked for date conversion or for strL
+        conversion. The strL converter independently handles conversion and
+        also accepts empty string arrays.
+        """
+        convert_dates = self._convert_dates
+        # _convert_strl is not available in dta 114
+        convert_strl = getattr(self, "_convert_strl", [])
+        for i, col in enumerate(self.data):
+            # Skip columns marked for date conversion or strl conversion
+            if i in convert_dates or col in convert_strl:
+                continue
+            column = self.data[col]
+            dtype = column.dtype
+            # TODO could also handle string dtype here specifically
+            if dtype.type is np.object_:
+                inferred_dtype = infer_dtype(column, skipna=True)
+                if not ((inferred_dtype == "string") or len(column) == 0):
+                    col = column.name
+                    raise ValueError(
+                        f"""\
+Column `{col}` cannot be exported.\n\nOnly string-like object arrays
+containing all strings or a mix of strings and None can be exported.
+Object arrays containing only null values are prohibited. Other object
+types cannot be exported and must first be converted to one of the
+supported types."""
+                    )
+                encoded = self.data[col].str.encode(self._encoding)
+                # If larger than _max_string_length do nothing
+                if (
+                    max_len_string_array(ensure_object(encoded._values))
+                    <= self._max_string_length
+                ):
+                    self.data[col] = encoded
+
+    def write_file(self) -> None:
+        """
+        Export DataFrame object to Stata dta format.
+
+        Examples
+        --------
+        >>> df = pd.DataFrame({"fully_labelled": [1, 2, 3, 3, 1],
+        ...                    "partially_labelled": [1.0, 2.0, np.nan, 9.0, np.nan],
+        ...                    "Y": [7, 7, 9, 8, 10],
+        ...                    "Z": pd.Categorical(["j", "k", "l", "k", "j"]),
+        ...                    })
+        >>> path = "/My_path/filename.dta"
+        >>> labels = {"fully_labelled": {1: "one", 2: "two", 3: "three"},
+        ...           "partially_labelled": {1.0: "one", 2.0: "two"},
+        ...           }
+        >>> writer = pd.io.stata.StataWriter(path,
+        ...                                  df,
+        ...                                  value_labels=labels)  # doctest: +SKIP
+        >>> writer.write_file()  # doctest: +SKIP
+        >>> df = pd.read_stata(path)  # doctest: +SKIP
+        >>> df  # doctest: +SKIP
+            index fully_labelled  partially_labeled  Y  Z
+        0       0            one                one  7  j
+        1       1            two                two  7  k
+        2       2          three                NaN  9  l
+        3       3          three                9.0  8  k
+        4       4            one                NaN 10  j
+        """
+        with get_handle(
+            self._fname,
+            "wb",
+            compression=self._compression,
+            is_text=False,
+            storage_options=self.storage_options,
+        ) as self.handles:
+            if self.handles.compression["method"] is not None:
+                # ZipFile creates a file (with the same name) for each write call.
+                # Write it first into a buffer and then write the buffer to the ZipFile.
+                self._output_file, self.handles.handle = self.handles.handle, BytesIO()
+                self.handles.created_handles.append(self.handles.handle)
+
+            try:
+                self._write_header(
+                    data_label=self._data_label, time_stamp=self._time_stamp
+                )
+                self._write_map()
+                self._write_variable_types()
+                self._write_varnames()
+                self._write_sortlist()
+                self._write_formats()
+                self._write_value_label_names()
+                self._write_variable_labels()
+                self._write_expansion_fields()
+                self._write_characteristics()
+                records = self._prepare_data()
+                self._write_data(records)
+                self._write_strls()
+                self._write_value_labels()
+                self._write_file_close_tag()
+                self._write_map()
+                self._close()
+            except Exception as exc:
+                self.handles.close()
+                if isinstance(self._fname, (str, os.PathLike)) and os.path.isfile(
+                    self._fname
+                ):
+                    try:
+                        os.unlink(self._fname)
+                    except OSError:
+                        warnings.warn(
+                            f"This save was not successful but {self._fname} could not "
+                            "be deleted. This file is not valid.",
+                            ResourceWarning,
+                            stacklevel=find_stack_level(),
+                        )
+                raise exc
+
+    def _close(self) -> None:
+        """
+        Close the file if it was created by the writer.
+
+        If a buffer or file-like object was passed in, for example a GzipFile,
+        then leave this file open for the caller to close.
+        """
+        # write compression
+        if self._output_file is not None:
+            assert isinstance(self.handles.handle, BytesIO)
+            bio, self.handles.handle = self.handles.handle, self._output_file
+            self.handles.handle.write(bio.getvalue())
+
+    def _write_map(self) -> None:
+        """No-op, future compatibility"""
+
+    def _write_file_close_tag(self) -> None:
+        """No-op, future compatibility"""
+
+    def _write_characteristics(self) -> None:
+        """No-op, future compatibility"""
+
+    def _write_strls(self) -> None:
+        """No-op, future compatibility"""
+
+    def _write_expansion_fields(self) -> None:
+        """Write 5 zeros for expansion fields"""
+        self._write(_pad_bytes("", 5))
+
+    def _write_value_labels(self) -> None:
+        for vl in self._value_labels:
+            self._write_bytes(vl.generate_value_label(self._byteorder))
+
+    def _write_header(
+        self,
+        data_label: str | None = None,
+        time_stamp: datetime | None = None,
+    ) -> None:
+        byteorder = self._byteorder
+        # ds_format - just use 114
+        self._write_bytes(struct.pack("b", 114))
+        # byteorder
+        self._write(byteorder == ">" and "\x01" or "\x02")
+        # filetype
+        self._write("\x01")
+        # unused
+        self._write("\x00")
+        # number of vars, 2 bytes
+        self._write_bytes(struct.pack(byteorder + "h", self.nvar)[:2])
+        # number of obs, 4 bytes
+        self._write_bytes(struct.pack(byteorder + "i", self.nobs)[:4])
+        # data label 81 bytes, char, null terminated
+        if data_label is None:
+            self._write_bytes(self._null_terminate_bytes(_pad_bytes("", 80)))
+        else:
+            self._write_bytes(
+                self._null_terminate_bytes(_pad_bytes(data_label[:80], 80))
+            )
+        # time stamp, 18 bytes, char, null terminated
+        # format dd Mon yyyy hh:mm
+        if time_stamp is None:
+            time_stamp = datetime.now()
+        elif not isinstance(time_stamp, datetime):
+            raise ValueError("time_stamp should be datetime type")
+        # GH #13856
+        # Avoid locale-specific month conversion
+        months = [
+            "Jan",
+            "Feb",
+            "Mar",
+            "Apr",
+            "May",
+            "Jun",
+            "Jul",
+            "Aug",
+            "Sep",
+            "Oct",
+            "Nov",
+            "Dec",
+        ]
+        month_lookup = {i + 1: month for i, month in enumerate(months)}
+        ts = (
+            time_stamp.strftime("%d ")
+            + month_lookup[time_stamp.month]
+            + time_stamp.strftime(" %Y %H:%M")
+        )
+        self._write_bytes(self._null_terminate_bytes(ts))
+
+    def _write_variable_types(self) -> None:
+        for typ in self.typlist:
+            self._write_bytes(struct.pack("B", typ))
+
+    def _write_varnames(self) -> None:
+        # varlist names are checked by _check_column_names
+        # varlist, requires null terminated
+        for name in self.varlist:
+            name = self._null_terminate_str(name)
+            name = _pad_bytes(name[:32], 33)
+            self._write(name)
+
+    def _write_sortlist(self) -> None:
+        # srtlist, 2*(nvar+1), int array, encoded by byteorder
+        srtlist = _pad_bytes("", 2 * (self.nvar + 1))
+        self._write(srtlist)
+
+    def _write_formats(self) -> None:
+        # fmtlist, 49*nvar, char array
+        for fmt in self.fmtlist:
+            self._write(_pad_bytes(fmt, 49))
+
+    def _write_value_label_names(self) -> None:
+        # lbllist, 33*nvar, char array
+        for i in range(self.nvar):
+            # Use variable name when categorical
+            if self._has_value_labels[i]:
+                name = self.varlist[i]
+                name = self._null_terminate_str(name)
+                name = _pad_bytes(name[:32], 33)
+                self._write(name)
+            else:  # Default is empty label
+                self._write(_pad_bytes("", 33))
+
+    def _write_variable_labels(self) -> None:
+        # Missing labels are 80 blank characters plus null termination
+        blank = _pad_bytes("", 81)
+
+        if self._variable_labels is None:
+            for i in range(self.nvar):
+                self._write(blank)
+            return
+
+        for col in self.data:
+            if col in self._variable_labels:
+                label = self._variable_labels[col]
+                if len(label) > 80:
+                    raise ValueError("Variable labels must be 80 characters or fewer")
+                is_latin1 = all(ord(c) < 256 for c in label)
+                if not is_latin1:
+                    raise ValueError(
+                        "Variable labels must contain only characters that "
+                        "can be encoded in Latin-1"
+                    )
+                self._write(_pad_bytes(label, 81))
+            else:
+                self._write(blank)
+
+    def _convert_strls(self, data: DataFrame) -> DataFrame:
+        """No-op, future compatibility"""
+        return data
+
+    def _prepare_data(self) -> np.rec.recarray:
+        data = self.data
+        typlist = self.typlist
+        convert_dates = self._convert_dates
+        # 1. Convert dates
+        if self._convert_dates is not None:
+            for i, col in enumerate(data):
+                if i in convert_dates:
+                    data[col] = _datetime_to_stata_elapsed_vec(
+                        data[col], self.fmtlist[i]
+                    )
+        # 2. Convert strls
+        data = self._convert_strls(data)
+
+        # 3. Convert bad string data to '' and pad to correct length
+        dtypes = {}
+        native_byteorder = self._byteorder == _set_endianness(sys.byteorder)
+        for i, col in enumerate(data):
+            typ = typlist[i]
+            if typ <= self._max_string_length:
+                with warnings.catch_warnings():
+                    warnings.filterwarnings(
+                        "ignore",
+                        "Downcasting object dtype arrays",
+                        category=FutureWarning,
+                    )
+                    dc = data[col].fillna("")
+                data[col] = dc.apply(_pad_bytes, args=(typ,))
+                stype = f"S{typ}"
+                dtypes[col] = stype
+                data[col] = data[col].astype(stype)
+            else:
+                dtype = data[col].dtype
+                if not native_byteorder:
+                    dtype = dtype.newbyteorder(self._byteorder)
+                dtypes[col] = dtype
+
+        return data.to_records(index=False, column_dtypes=dtypes)
+
+    def _write_data(self, records: np.rec.recarray) -> None:
+        self._write_bytes(records.tobytes())
+
+    @staticmethod
+    def _null_terminate_str(s: str) -> str:
+        s += "\x00"
+        return s
+
+    def _null_terminate_bytes(self, s: str) -> bytes:
+        return self._null_terminate_str(s).encode(self._encoding)
+
+
+def _dtype_to_stata_type_117(dtype: np.dtype, column: Series, force_strl: bool) -> int:
+    """
+    Converts dtype types to stata types. Returns the byte of the given ordinal.
+    See TYPE_MAP and comments for an explanation. This is also explained in
+    the dta spec.
+    1 - 2045 are strings of this length
+                Pandas    Stata
+    32768 - for object    strL
+    65526 - for int8      byte
+    65527 - for int16     int
+    65528 - for int32     long
+    65529 - for float32   float
+    65530 - for double    double
+
+    If there are dates to convert, then dtype will already have the correct
+    type inserted.
+    """
+    # TODO: expand to handle datetime to integer conversion
+    if force_strl:
+        return 32768
+    if dtype.type is np.object_:  # try to coerce it to the biggest string
+        # not memory efficient, what else could we
+        # do?
+        itemsize = max_len_string_array(ensure_object(column._values))
+        itemsize = max(itemsize, 1)
+        if itemsize <= 2045:
+            return itemsize
+        return 32768
+    elif dtype.type is np.float64:
+        return 65526
+    elif dtype.type is np.float32:
+        return 65527
+    elif dtype.type is np.int32:
+        return 65528
+    elif dtype.type is np.int16:
+        return 65529
+    elif dtype.type is np.int8:
+        return 65530
+    else:  # pragma : no cover
+        raise NotImplementedError(f"Data type {dtype} not supported.")
+
+
+def _pad_bytes_new(name: str | bytes, length: int) -> bytes:
+    """
+    Takes a bytes instance and pads it with null bytes until it's length chars.
+    """
+    if isinstance(name, str):
+        name = bytes(name, "utf-8")
+    return name + b"\x00" * (length - len(name))
+
+
+class StataStrLWriter:
+    """
+    Converter for Stata StrLs
+
+    Stata StrLs map 8 byte values to strings which are stored using a
+    dictionary-like format where strings are keyed to two values.
+
+    Parameters
+    ----------
+    df : DataFrame
+        DataFrame to convert
+    columns : Sequence[str]
+        List of columns names to convert to StrL
+    version : int, optional
+        dta version.  Currently supports 117, 118 and 119
+    byteorder : str, optional
+        Can be ">", "<", "little", or "big". default is `sys.byteorder`
+
+    Notes
+    -----
+    Supports creation of the StrL block of a dta file for dta versions
+    117, 118 and 119.  These differ in how the GSO is stored.  118 and
+    119 store the GSO lookup value as a uint32 and a uint64, while 117
+    uses two uint32s. 118 and 119 also encode all strings as unicode
+    which is required by the format.  117 uses 'latin-1' a fixed width
+    encoding that extends the 7-bit ascii table with an additional 128
+    characters.
+    """
+
+    def __init__(
+        self,
+        df: DataFrame,
+        columns: Sequence[str],
+        version: int = 117,
+        byteorder: str | None = None,
+    ) -> None:
+        if version not in (117, 118, 119):
+            raise ValueError("Only dta versions 117, 118 and 119 supported")
+        self._dta_ver = version
+
+        self.df = df
+        self.columns = columns
+        self._gso_table = {"": (0, 0)}
+        if byteorder is None:
+            byteorder = sys.byteorder
+        self._byteorder = _set_endianness(byteorder)
+
+        gso_v_type = "I"  # uint32
+        gso_o_type = "Q"  # uint64
+        self._encoding = "utf-8"
+        if version == 117:
+            o_size = 4
+            gso_o_type = "I"  # 117 used uint32
+            self._encoding = "latin-1"
+        elif version == 118:
+            o_size = 6
+        else:  # version == 119
+            o_size = 5
+        self._o_offet = 2 ** (8 * (8 - o_size))
+        self._gso_o_type = gso_o_type
+        self._gso_v_type = gso_v_type
+
+    def _convert_key(self, key: tuple[int, int]) -> int:
+        v, o = key
+        return v + self._o_offet * o
+
+    def generate_table(self) -> tuple[dict[str, tuple[int, int]], DataFrame]:
+        """
+        Generates the GSO lookup table for the DataFrame
+
+        Returns
+        -------
+        gso_table : dict
+            Ordered dictionary using the string found as keys
+            and their lookup position (v,o) as values
+        gso_df : DataFrame
+            DataFrame where strl columns have been converted to
+            (v,o) values
+
+        Notes
+        -----
+        Modifies the DataFrame in-place.
+
+        The DataFrame returned encodes the (v,o) values as uint64s. The
+        encoding depends on the dta version, and can be expressed as
+
+        enc = v + o * 2 ** (o_size * 8)
+
+        so that v is stored in the lower bits and o is in the upper
+        bits. o_size is
+
+          * 117: 4
+          * 118: 6
+          * 119: 5
+        """
+        gso_table = self._gso_table
+        gso_df = self.df
+        columns = list(gso_df.columns)
+        selected = gso_df[self.columns]
+        col_index = [(col, columns.index(col)) for col in self.columns]
+        keys = np.empty(selected.shape, dtype=np.uint64)
+        for o, (idx, row) in enumerate(selected.iterrows()):
+            for j, (col, v) in enumerate(col_index):
+                val = row[col]
+                # Allow columns with mixed str and None (GH 23633)
+                val = "" if val is None else val
+                key = gso_table.get(val, None)
+                if key is None:
+                    # Stata prefers human numbers
+                    key = (v + 1, o + 1)
+                    gso_table[val] = key
+                keys[o, j] = self._convert_key(key)
+        for i, col in enumerate(self.columns):
+            gso_df[col] = keys[:, i]
+
+        return gso_table, gso_df
+
+    def generate_blob(self, gso_table: dict[str, tuple[int, int]]) -> bytes:
+        """
+        Generates the binary blob of GSOs that is written to the dta file.
+
+        Parameters
+        ----------
+        gso_table : dict
+            Ordered dictionary (str, vo)
+
+        Returns
+        -------
+        gso : bytes
+            Binary content of dta file to be placed between strl tags
+
+        Notes
+        -----
+        Output format depends on dta version.  117 uses two uint32s to
+        express v and o while 118+ uses a uint32 for v and a uint64 for o.
+        """
+        # Format information
+        # Length includes null term
+        # 117
+        # GSOvvvvooootllllxxxxxxxxxxxxxxx...x
+        #  3  u4  u4 u1 u4  string + null term
+        #
+        # 118, 119
+        # GSOvvvvooooooootllllxxxxxxxxxxxxxxx...x
+        #  3  u4   u8   u1 u4    string + null term
+
+        bio = BytesIO()
+        gso = bytes("GSO", "ascii")
+        gso_type = struct.pack(self._byteorder + "B", 130)
+        null = struct.pack(self._byteorder + "B", 0)
+        v_type = self._byteorder + self._gso_v_type
+        o_type = self._byteorder + self._gso_o_type
+        len_type = self._byteorder + "I"
+        for strl, vo in gso_table.items():
+            if vo == (0, 0):
+                continue
+            v, o = vo
+
+            # GSO
+            bio.write(gso)
+
+            # vvvv
+            bio.write(struct.pack(v_type, v))
+
+            # oooo / oooooooo
+            bio.write(struct.pack(o_type, o))
+
+            # t
+            bio.write(gso_type)
+
+            # llll
+            utf8_string = bytes(strl, "utf-8")
+            bio.write(struct.pack(len_type, len(utf8_string) + 1))
+
+            # xxx...xxx
+            bio.write(utf8_string)
+            bio.write(null)
+
+        return bio.getvalue()
+
+
+class StataWriter117(StataWriter):
+    """
+    A class for writing Stata binary dta files in Stata 13 format (117)
+
+    Parameters
+    ----------
+    fname : path (string), buffer or path object
+        string, path object (pathlib.Path or py._path.local.LocalPath) or
+        object implementing a binary write() functions. If using a buffer
+        then the buffer will not be automatically closed after the file
+        is written.
+    data : DataFrame
+        Input to save
+    convert_dates : dict
+        Dictionary mapping columns containing datetime types to stata internal
+        format to use when writing the dates. Options are 'tc', 'td', 'tm',
+        'tw', 'th', 'tq', 'ty'. Column can be either an integer or a name.
+        Datetime columns that do not have a conversion type specified will be
+        converted to 'tc'. Raises NotImplementedError if a datetime column has
+        timezone information
+    write_index : bool
+        Write the index to Stata dataset.
+    byteorder : str
+        Can be ">", "<", "little", or "big". default is `sys.byteorder`
+    time_stamp : datetime
+        A datetime to use as file creation date.  Default is the current time
+    data_label : str
+        A label for the data set.  Must be 80 characters or smaller.
+    variable_labels : dict
+        Dictionary containing columns as keys and variable labels as values.
+        Each label must be 80 characters or smaller.
+    convert_strl : list
+        List of columns names to convert to Stata StrL format.  Columns with
+        more than 2045 characters are automatically written as StrL.
+        Smaller columns can be converted by including the column name.  Using
+        StrLs can reduce output file size when strings are longer than 8
+        characters, and either frequently repeated or sparse.
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    value_labels : dict of dicts
+        Dictionary containing columns as keys and dictionaries of column value
+        to labels as values. The combined length of all labels for a single
+        variable must be 32,000 characters or smaller.
+
+        .. versionadded:: 1.4.0
+
+    Returns
+    -------
+    writer : StataWriter117 instance
+        The StataWriter117 instance has a write_file method, which will
+        write the file to the given `fname`.
+
+    Raises
+    ------
+    NotImplementedError
+        * If datetimes contain timezone information
+    ValueError
+        * Columns listed in convert_dates are neither datetime64[ns]
+          or datetime
+        * Column dtype is not representable in Stata
+        * Column listed in convert_dates is not in DataFrame
+        * Categorical label contains more than 32,000 characters
+
+    Examples
+    --------
+    >>> data = pd.DataFrame([[1.0, 1, 'a']], columns=['a', 'b', 'c'])
+    >>> writer = pd.io.stata.StataWriter117('./data_file.dta', data)
+    >>> writer.write_file()
+
+    Directly write a zip file
+    >>> compression = {"method": "zip", "archive_name": "data_file.dta"}
+    >>> writer = pd.io.stata.StataWriter117(
+    ...     './data_file.zip', data, compression=compression
+    ...     )
+    >>> writer.write_file()
+
+    Or with long strings stored in strl format
+    >>> data = pd.DataFrame([['A relatively long string'], [''], ['']],
+    ...                     columns=['strls'])
+    >>> writer = pd.io.stata.StataWriter117(
+    ...     './data_file_with_long_strings.dta', data, convert_strl=['strls'])
+    >>> writer.write_file()
+    """
+
+    _max_string_length = 2045
+    _dta_version = 117
+
+    def __init__(
+        self,
+        fname: FilePath | WriteBuffer[bytes],
+        data: DataFrame,
+        convert_dates: dict[Hashable, str] | None = None,
+        write_index: bool = True,
+        byteorder: str | None = None,
+        time_stamp: datetime | None = None,
+        data_label: str | None = None,
+        variable_labels: dict[Hashable, str] | None = None,
+        convert_strl: Sequence[Hashable] | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+        *,
+        value_labels: dict[Hashable, dict[float, str]] | None = None,
+    ) -> None:
+        # Copy to new list since convert_strl might be modified later
+        self._convert_strl: list[Hashable] = []
+        if convert_strl is not None:
+            self._convert_strl.extend(convert_strl)
+
+        super().__init__(
+            fname,
+            data,
+            convert_dates,
+            write_index,
+            byteorder=byteorder,
+            time_stamp=time_stamp,
+            data_label=data_label,
+            variable_labels=variable_labels,
+            value_labels=value_labels,
+            compression=compression,
+            storage_options=storage_options,
+        )
+        self._map: dict[str, int] = {}
+        self._strl_blob = b""
+
+    @staticmethod
+    def _tag(val: str | bytes, tag: str) -> bytes:
+        """Surround val with """
+        if isinstance(val, str):
+            val = bytes(val, "utf-8")
+        return bytes("<" + tag + ">", "utf-8") + val + bytes("", "utf-8")
+
+    def _update_map(self, tag: str) -> None:
+        """Update map location for tag with file position"""
+        assert self.handles.handle is not None
+        self._map[tag] = self.handles.handle.tell()
+
+    def _write_header(
+        self,
+        data_label: str | None = None,
+        time_stamp: datetime | None = None,
+    ) -> None:
+        """Write the file header"""
+        byteorder = self._byteorder
+        self._write_bytes(bytes("", "utf-8"))
+        bio = BytesIO()
+        # ds_format - 117
+        bio.write(self._tag(bytes(str(self._dta_version), "utf-8"), "release"))
+        # byteorder
+        bio.write(self._tag(byteorder == ">" and "MSF" or "LSF", "byteorder"))
+        # number of vars, 2 bytes in 117 and 118, 4 byte in 119
+        nvar_type = "H" if self._dta_version <= 118 else "I"
+        bio.write(self._tag(struct.pack(byteorder + nvar_type, self.nvar), "K"))
+        # 117 uses 4 bytes, 118 uses 8
+        nobs_size = "I" if self._dta_version == 117 else "Q"
+        bio.write(self._tag(struct.pack(byteorder + nobs_size, self.nobs), "N"))
+        # data label 81 bytes, char, null terminated
+        label = data_label[:80] if data_label is not None else ""
+        encoded_label = label.encode(self._encoding)
+        label_size = "B" if self._dta_version == 117 else "H"
+        label_len = struct.pack(byteorder + label_size, len(encoded_label))
+        encoded_label = label_len + encoded_label
+        bio.write(self._tag(encoded_label, "label"))
+        # time stamp, 18 bytes, char, null terminated
+        # format dd Mon yyyy hh:mm
+        if time_stamp is None:
+            time_stamp = datetime.now()
+        elif not isinstance(time_stamp, datetime):
+            raise ValueError("time_stamp should be datetime type")
+        # Avoid locale-specific month conversion
+        months = [
+            "Jan",
+            "Feb",
+            "Mar",
+            "Apr",
+            "May",
+            "Jun",
+            "Jul",
+            "Aug",
+            "Sep",
+            "Oct",
+            "Nov",
+            "Dec",
+        ]
+        month_lookup = {i + 1: month for i, month in enumerate(months)}
+        ts = (
+            time_stamp.strftime("%d ")
+            + month_lookup[time_stamp.month]
+            + time_stamp.strftime(" %Y %H:%M")
+        )
+        # '\x11' added due to inspection of Stata file
+        stata_ts = b"\x11" + bytes(ts, "utf-8")
+        bio.write(self._tag(stata_ts, "timestamp"))
+        self._write_bytes(self._tag(bio.getvalue(), "header"))
+
+    def _write_map(self) -> None:
+        """
+        Called twice during file write. The first populates the values in
+        the map with 0s.  The second call writes the final map locations when
+        all blocks have been written.
+        """
+        if not self._map:
+            self._map = {
+                "stata_data": 0,
+                "map": self.handles.handle.tell(),
+                "variable_types": 0,
+                "varnames": 0,
+                "sortlist": 0,
+                "formats": 0,
+                "value_label_names": 0,
+                "variable_labels": 0,
+                "characteristics": 0,
+                "data": 0,
+                "strls": 0,
+                "value_labels": 0,
+                "stata_data_close": 0,
+                "end-of-file": 0,
+            }
+        # Move to start of map
+        self.handles.handle.seek(self._map["map"])
+        bio = BytesIO()
+        for val in self._map.values():
+            bio.write(struct.pack(self._byteorder + "Q", val))
+        self._write_bytes(self._tag(bio.getvalue(), "map"))
+
+    def _write_variable_types(self) -> None:
+        self._update_map("variable_types")
+        bio = BytesIO()
+        for typ in self.typlist:
+            bio.write(struct.pack(self._byteorder + "H", typ))
+        self._write_bytes(self._tag(bio.getvalue(), "variable_types"))
+
+    def _write_varnames(self) -> None:
+        self._update_map("varnames")
+        bio = BytesIO()
+        # 118 scales by 4 to accommodate utf-8 data worst case encoding
+        vn_len = 32 if self._dta_version == 117 else 128
+        for name in self.varlist:
+            name = self._null_terminate_str(name)
+            name = _pad_bytes_new(name[:32].encode(self._encoding), vn_len + 1)
+            bio.write(name)
+        self._write_bytes(self._tag(bio.getvalue(), "varnames"))
+
+    def _write_sortlist(self) -> None:
+        self._update_map("sortlist")
+        sort_size = 2 if self._dta_version < 119 else 4
+        self._write_bytes(self._tag(b"\x00" * sort_size * (self.nvar + 1), "sortlist"))
+
+    def _write_formats(self) -> None:
+        self._update_map("formats")
+        bio = BytesIO()
+        fmt_len = 49 if self._dta_version == 117 else 57
+        for fmt in self.fmtlist:
+            bio.write(_pad_bytes_new(fmt.encode(self._encoding), fmt_len))
+        self._write_bytes(self._tag(bio.getvalue(), "formats"))
+
+    def _write_value_label_names(self) -> None:
+        self._update_map("value_label_names")
+        bio = BytesIO()
+        # 118 scales by 4 to accommodate utf-8 data worst case encoding
+        vl_len = 32 if self._dta_version == 117 else 128
+        for i in range(self.nvar):
+            # Use variable name when categorical
+            name = ""  # default name
+            if self._has_value_labels[i]:
+                name = self.varlist[i]
+            name = self._null_terminate_str(name)
+            encoded_name = _pad_bytes_new(name[:32].encode(self._encoding), vl_len + 1)
+            bio.write(encoded_name)
+        self._write_bytes(self._tag(bio.getvalue(), "value_label_names"))
+
+    def _write_variable_labels(self) -> None:
+        # Missing labels are 80 blank characters plus null termination
+        self._update_map("variable_labels")
+        bio = BytesIO()
+        # 118 scales by 4 to accommodate utf-8 data worst case encoding
+        vl_len = 80 if self._dta_version == 117 else 320
+        blank = _pad_bytes_new("", vl_len + 1)
+
+        if self._variable_labels is None:
+            for _ in range(self.nvar):
+                bio.write(blank)
+            self._write_bytes(self._tag(bio.getvalue(), "variable_labels"))
+            return
+
+        for col in self.data:
+            if col in self._variable_labels:
+                label = self._variable_labels[col]
+                if len(label) > 80:
+                    raise ValueError("Variable labels must be 80 characters or fewer")
+                try:
+                    encoded = label.encode(self._encoding)
+                except UnicodeEncodeError as err:
+                    raise ValueError(
+                        "Variable labels must contain only characters that "
+                        f"can be encoded in {self._encoding}"
+                    ) from err
+
+                bio.write(_pad_bytes_new(encoded, vl_len + 1))
+            else:
+                bio.write(blank)
+        self._write_bytes(self._tag(bio.getvalue(), "variable_labels"))
+
+    def _write_characteristics(self) -> None:
+        self._update_map("characteristics")
+        self._write_bytes(self._tag(b"", "characteristics"))
+
+    def _write_data(self, records) -> None:
+        self._update_map("data")
+        self._write_bytes(b"")
+        self._write_bytes(records.tobytes())
+        self._write_bytes(b"")
+
+    def _write_strls(self) -> None:
+        self._update_map("strls")
+        self._write_bytes(self._tag(self._strl_blob, "strls"))
+
+    def _write_expansion_fields(self) -> None:
+        """No-op in dta 117+"""
+
+    def _write_value_labels(self) -> None:
+        self._update_map("value_labels")
+        bio = BytesIO()
+        for vl in self._value_labels:
+            lab = vl.generate_value_label(self._byteorder)
+            lab = self._tag(lab, "lbl")
+            bio.write(lab)
+        self._write_bytes(self._tag(bio.getvalue(), "value_labels"))
+
+    def _write_file_close_tag(self) -> None:
+        self._update_map("stata_data_close")
+        self._write_bytes(bytes("", "utf-8"))
+        self._update_map("end-of-file")
+
+    def _update_strl_names(self) -> None:
+        """
+        Update column names for conversion to strl if they might have been
+        changed to comply with Stata naming rules
+        """
+        # Update convert_strl if names changed
+        for orig, new in self._converted_names.items():
+            if orig in self._convert_strl:
+                idx = self._convert_strl.index(orig)
+                self._convert_strl[idx] = new
+
+    def _convert_strls(self, data: DataFrame) -> DataFrame:
+        """
+        Convert columns to StrLs if either very large or in the
+        convert_strl variable
+        """
+        convert_cols = [
+            col
+            for i, col in enumerate(data)
+            if self.typlist[i] == 32768 or col in self._convert_strl
+        ]
+
+        if convert_cols:
+            ssw = StataStrLWriter(data, convert_cols, version=self._dta_version)
+            tab, new_data = ssw.generate_table()
+            data = new_data
+            self._strl_blob = ssw.generate_blob(tab)
+        return data
+
+    def _set_formats_and_types(self, dtypes: Series) -> None:
+        self.typlist = []
+        self.fmtlist = []
+        for col, dtype in dtypes.items():
+            force_strl = col in self._convert_strl
+            fmt = _dtype_to_default_stata_fmt(
+                dtype,
+                self.data[col],
+                dta_version=self._dta_version,
+                force_strl=force_strl,
+            )
+            self.fmtlist.append(fmt)
+            self.typlist.append(
+                _dtype_to_stata_type_117(dtype, self.data[col], force_strl)
+            )
+
+
+class StataWriterUTF8(StataWriter117):
+    """
+    Stata binary dta file writing in Stata 15 (118) and 16 (119) formats
+
+    DTA 118 and 119 format files support unicode string data (both fixed
+    and strL) format. Unicode is also supported in value labels, variable
+    labels and the dataset label. Format 119 is automatically used if the
+    file contains more than 32,767 variables.
+
+    Parameters
+    ----------
+    fname : path (string), buffer or path object
+        string, path object (pathlib.Path or py._path.local.LocalPath) or
+        object implementing a binary write() functions. If using a buffer
+        then the buffer will not be automatically closed after the file
+        is written.
+    data : DataFrame
+        Input to save
+    convert_dates : dict, default None
+        Dictionary mapping columns containing datetime types to stata internal
+        format to use when writing the dates. Options are 'tc', 'td', 'tm',
+        'tw', 'th', 'tq', 'ty'. Column can be either an integer or a name.
+        Datetime columns that do not have a conversion type specified will be
+        converted to 'tc'. Raises NotImplementedError if a datetime column has
+        timezone information
+    write_index : bool, default True
+        Write the index to Stata dataset.
+    byteorder : str, default None
+        Can be ">", "<", "little", or "big". default is `sys.byteorder`
+    time_stamp : datetime, default None
+        A datetime to use as file creation date.  Default is the current time
+    data_label : str, default None
+        A label for the data set.  Must be 80 characters or smaller.
+    variable_labels : dict, default None
+        Dictionary containing columns as keys and variable labels as values.
+        Each label must be 80 characters or smaller.
+    convert_strl : list, default None
+        List of columns names to convert to Stata StrL format.  Columns with
+        more than 2045 characters are automatically written as StrL.
+        Smaller columns can be converted by including the column name.  Using
+        StrLs can reduce output file size when strings are longer than 8
+        characters, and either frequently repeated or sparse.
+    version : int, default None
+        The dta version to use. By default, uses the size of data to determine
+        the version. 118 is used if data.shape[1] <= 32767, and 119 is used
+        for storing larger DataFrames.
+    {compression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    value_labels : dict of dicts
+        Dictionary containing columns as keys and dictionaries of column value
+        to labels as values. The combined length of all labels for a single
+        variable must be 32,000 characters or smaller.
+
+        .. versionadded:: 1.4.0
+
+    Returns
+    -------
+    StataWriterUTF8
+        The instance has a write_file method, which will write the file to the
+        given `fname`.
+
+    Raises
+    ------
+    NotImplementedError
+        * If datetimes contain timezone information
+    ValueError
+        * Columns listed in convert_dates are neither datetime64[ns]
+          or datetime
+        * Column dtype is not representable in Stata
+        * Column listed in convert_dates is not in DataFrame
+        * Categorical label contains more than 32,000 characters
+
+    Examples
+    --------
+    Using Unicode data and column names
+
+    >>> from pandas.io.stata import StataWriterUTF8
+    >>> data = pd.DataFrame([[1.0, 1, 'ᴬ']], columns=['a', 'β', 'ĉ'])
+    >>> writer = StataWriterUTF8('./data_file.dta', data)
+    >>> writer.write_file()
+
+    Directly write a zip file
+    >>> compression = {"method": "zip", "archive_name": "data_file.dta"}
+    >>> writer = StataWriterUTF8('./data_file.zip', data, compression=compression)
+    >>> writer.write_file()
+
+    Or with long strings stored in strl format
+
+    >>> data = pd.DataFrame([['ᴀ relatively long ŝtring'], [''], ['']],
+    ...                     columns=['strls'])
+    >>> writer = StataWriterUTF8('./data_file_with_long_strings.dta', data,
+    ...                          convert_strl=['strls'])
+    >>> writer.write_file()
+    """
+
+    _encoding: Literal["utf-8"] = "utf-8"
+
+    def __init__(
+        self,
+        fname: FilePath | WriteBuffer[bytes],
+        data: DataFrame,
+        convert_dates: dict[Hashable, str] | None = None,
+        write_index: bool = True,
+        byteorder: str | None = None,
+        time_stamp: datetime | None = None,
+        data_label: str | None = None,
+        variable_labels: dict[Hashable, str] | None = None,
+        convert_strl: Sequence[Hashable] | None = None,
+        version: int | None = None,
+        compression: CompressionOptions = "infer",
+        storage_options: StorageOptions | None = None,
+        *,
+        value_labels: dict[Hashable, dict[float, str]] | None = None,
+    ) -> None:
+        if version is None:
+            version = 118 if data.shape[1] <= 32767 else 119
+        elif version not in (118, 119):
+            raise ValueError("version must be either 118 or 119.")
+        elif version == 118 and data.shape[1] > 32767:
+            raise ValueError(
+                "You must use version 119 for data sets containing more than"
+                "32,767 variables"
+            )
+
+        super().__init__(
+            fname,
+            data,
+            convert_dates=convert_dates,
+            write_index=write_index,
+            byteorder=byteorder,
+            time_stamp=time_stamp,
+            data_label=data_label,
+            variable_labels=variable_labels,
+            value_labels=value_labels,
+            convert_strl=convert_strl,
+            compression=compression,
+            storage_options=storage_options,
+        )
+        # Override version set in StataWriter117 init
+        self._dta_version = version
+
+    def _validate_variable_name(self, name: str) -> str:
+        """
+        Validate variable names for Stata export.
+
+        Parameters
+        ----------
+        name : str
+            Variable name
+
+        Returns
+        -------
+        str
+            The validated name with invalid characters replaced with
+            underscores.
+
+        Notes
+        -----
+        Stata 118+ support most unicode characters. The only limitation is in
+        the ascii range where the characters supported are a-z, A-Z, 0-9 and _.
+        """
+        # High code points appear to be acceptable
+        for c in name:
+            if (
+                (
+                    ord(c) < 128
+                    and (c < "A" or c > "Z")
+                    and (c < "a" or c > "z")
+                    and (c < "0" or c > "9")
+                    and c != "_"
+                )
+                or 128 <= ord(c) < 192
+                or c in {"×", "÷"}  # noqa: RUF001
+            ):
+                name = name.replace(c, "_")
+
+        return name
diff --git a/.venv/lib/python3.13/site-packages/pandas/io/xml.py b/.venv/lib/python3.13/site-packages/pandas/io/xml.py
new file mode 100644
index 0000000000000000000000000000000000000000..ac497cd266027f7af71884996182e1725baba361
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/io/xml.py
@@ -0,0 +1,1177 @@
+"""
+:mod:``pandas.io.xml`` is a module for reading XML.
+"""
+
+from __future__ import annotations
+
+import io
+from os import PathLike
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Callable,
+)
+import warnings
+
+from pandas._libs import lib
+from pandas.compat._optional import import_optional_dependency
+from pandas.errors import (
+    AbstractMethodError,
+    ParserError,
+)
+from pandas.util._decorators import doc
+from pandas.util._exceptions import find_stack_level
+from pandas.util._validators import check_dtype_backend
+
+from pandas.core.dtypes.common import is_list_like
+
+from pandas.core.shared_docs import _shared_docs
+
+from pandas.io.common import (
+    file_exists,
+    get_handle,
+    infer_compression,
+    is_file_like,
+    is_fsspec_url,
+    is_url,
+    stringify_path,
+)
+from pandas.io.parsers import TextParser
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from xml.etree.ElementTree import Element
+
+    from lxml import etree
+
+    from pandas._typing import (
+        CompressionOptions,
+        ConvertersArg,
+        DtypeArg,
+        DtypeBackend,
+        FilePath,
+        ParseDatesArg,
+        ReadBuffer,
+        StorageOptions,
+        XMLParsers,
+    )
+
+    from pandas import DataFrame
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    decompression_options=_shared_docs["decompression_options"] % "path_or_buffer",
+)
+class _XMLFrameParser:
+    """
+    Internal subclass to parse XML into DataFrames.
+
+    Parameters
+    ----------
+    path_or_buffer : a valid JSON ``str``, path object or file-like object
+        Any valid string path is acceptable. The string could be a URL. Valid
+        URL schemes include http, ftp, s3, and file.
+
+    xpath : str or regex
+        The ``XPath`` expression to parse required set of nodes for
+        migration to :class:`~pandas.DataFrame`. ``etree`` supports limited ``XPath``.
+
+    namespaces : dict
+        The namespaces defined in XML document (``xmlns:namespace='URI'``)
+        as dicts with key being namespace and value the URI.
+
+    elems_only : bool
+        Parse only the child elements at the specified ``xpath``.
+
+    attrs_only : bool
+        Parse only the attributes at the specified ``xpath``.
+
+    names : list
+        Column names for :class:`~pandas.DataFrame` of parsed XML data.
+
+    dtype : dict
+        Data type for data or columns. E.g. {{'a': np.float64,
+        'b': np.int32, 'c': 'Int64'}}
+
+        .. versionadded:: 1.5.0
+
+    converters : dict, optional
+        Dict of functions for converting values in certain columns. Keys can
+        either be integers or column labels.
+
+        .. versionadded:: 1.5.0
+
+    parse_dates : bool or list of int or names or list of lists or dict
+        Converts either index or select columns to datetimes
+
+        .. versionadded:: 1.5.0
+
+    encoding : str
+        Encoding of xml object or document.
+
+    stylesheet : str or file-like
+        URL, file, file-like object, or a raw string containing XSLT,
+        ``etree`` does not support XSLT but retained for consistency.
+
+    iterparse : dict, optional
+        Dict with row element as key and list of descendant elements
+        and/or attributes as value to be retrieved in iterparsing of
+        XML document.
+
+        .. versionadded:: 1.5.0
+
+    {decompression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    {storage_options}
+
+    See also
+    --------
+    pandas.io.xml._EtreeFrameParser
+    pandas.io.xml._LxmlFrameParser
+
+    Notes
+    -----
+    To subclass this class effectively you must override the following methods:`
+        * :func:`parse_data`
+        * :func:`_parse_nodes`
+        * :func:`_iterparse_nodes`
+        * :func:`_parse_doc`
+        * :func:`_validate_names`
+        * :func:`_validate_path`
+
+
+    See each method's respective documentation for details on their
+    functionality.
+    """
+
+    def __init__(
+        self,
+        path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str],
+        xpath: str,
+        namespaces: dict[str, str] | None,
+        elems_only: bool,
+        attrs_only: bool,
+        names: Sequence[str] | None,
+        dtype: DtypeArg | None,
+        converters: ConvertersArg | None,
+        parse_dates: ParseDatesArg | None,
+        encoding: str | None,
+        stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None,
+        iterparse: dict[str, list[str]] | None,
+        compression: CompressionOptions,
+        storage_options: StorageOptions,
+    ) -> None:
+        self.path_or_buffer = path_or_buffer
+        self.xpath = xpath
+        self.namespaces = namespaces
+        self.elems_only = elems_only
+        self.attrs_only = attrs_only
+        self.names = names
+        self.dtype = dtype
+        self.converters = converters
+        self.parse_dates = parse_dates
+        self.encoding = encoding
+        self.stylesheet = stylesheet
+        self.iterparse = iterparse
+        self.is_style = None
+        self.compression: CompressionOptions = compression
+        self.storage_options = storage_options
+
+    def parse_data(self) -> list[dict[str, str | None]]:
+        """
+        Parse xml data.
+
+        This method will call the other internal methods to
+        validate ``xpath``, names, parse and return specific nodes.
+        """
+
+        raise AbstractMethodError(self)
+
+    def _parse_nodes(self, elems: list[Any]) -> list[dict[str, str | None]]:
+        """
+        Parse xml nodes.
+
+        This method will parse the children and attributes of elements
+        in ``xpath``, conditionally for only elements, only attributes
+        or both while optionally renaming node names.
+
+        Raises
+        ------
+        ValueError
+            * If only elements and only attributes are specified.
+
+        Notes
+        -----
+        Namespace URIs will be removed from return node values. Also,
+        elements with missing children or attributes compared to siblings
+        will have optional keys filled with None values.
+        """
+
+        dicts: list[dict[str, str | None]]
+
+        if self.elems_only and self.attrs_only:
+            raise ValueError("Either element or attributes can be parsed not both.")
+        if self.elems_only:
+            if self.names:
+                dicts = [
+                    {
+                        **(
+                            {el.tag: el.text}
+                            if el.text and not el.text.isspace()
+                            else {}
+                        ),
+                        **{
+                            nm: ch.text if ch.text else None
+                            for nm, ch in zip(self.names, el.findall("*"))
+                        },
+                    }
+                    for el in elems
+                ]
+            else:
+                dicts = [
+                    {ch.tag: ch.text if ch.text else None for ch in el.findall("*")}
+                    for el in elems
+                ]
+
+        elif self.attrs_only:
+            dicts = [
+                {k: v if v else None for k, v in el.attrib.items()} for el in elems
+            ]
+
+        elif self.names:
+            dicts = [
+                {
+                    **el.attrib,
+                    **({el.tag: el.text} if el.text and not el.text.isspace() else {}),
+                    **{
+                        nm: ch.text if ch.text else None
+                        for nm, ch in zip(self.names, el.findall("*"))
+                    },
+                }
+                for el in elems
+            ]
+
+        else:
+            dicts = [
+                {
+                    **el.attrib,
+                    **({el.tag: el.text} if el.text and not el.text.isspace() else {}),
+                    **{ch.tag: ch.text if ch.text else None for ch in el.findall("*")},
+                }
+                for el in elems
+            ]
+
+        dicts = [
+            {k.split("}")[1] if "}" in k else k: v for k, v in d.items()} for d in dicts
+        ]
+
+        keys = list(dict.fromkeys([k for d in dicts for k in d.keys()]))
+        dicts = [{k: d[k] if k in d.keys() else None for k in keys} for d in dicts]
+
+        if self.names:
+            dicts = [dict(zip(self.names, d.values())) for d in dicts]
+
+        return dicts
+
+    def _iterparse_nodes(self, iterparse: Callable) -> list[dict[str, str | None]]:
+        """
+        Iterparse xml nodes.
+
+        This method will read in local disk, decompressed XML files for elements
+        and underlying descendants using iterparse, a method to iterate through
+        an XML tree without holding entire XML tree in memory.
+
+        Raises
+        ------
+        TypeError
+            * If ``iterparse`` is not a dict or its dict value is not list-like.
+        ParserError
+            * If ``path_or_buffer`` is not a physical file on disk or file-like object.
+            * If no data is returned from selected items in ``iterparse``.
+
+        Notes
+        -----
+        Namespace URIs will be removed from return node values. Also,
+        elements with missing children or attributes in submitted list
+        will have optional keys filled with None values.
+        """
+
+        dicts: list[dict[str, str | None]] = []
+        row: dict[str, str | None] | None = None
+
+        if not isinstance(self.iterparse, dict):
+            raise TypeError(
+                f"{type(self.iterparse).__name__} is not a valid type for iterparse"
+            )
+
+        row_node = next(iter(self.iterparse.keys())) if self.iterparse else ""
+        if not is_list_like(self.iterparse[row_node]):
+            raise TypeError(
+                f"{type(self.iterparse[row_node])} is not a valid type "
+                "for value in iterparse"
+            )
+
+        if (not hasattr(self.path_or_buffer, "read")) and (
+            not isinstance(self.path_or_buffer, (str, PathLike))
+            or is_url(self.path_or_buffer)
+            or is_fsspec_url(self.path_or_buffer)
+            or (
+                isinstance(self.path_or_buffer, str)
+                and self.path_or_buffer.startswith((" list[Any]:
+        """
+        Validate ``xpath``.
+
+        This method checks for syntax, evaluation, or empty nodes return.
+
+        Raises
+        ------
+        SyntaxError
+            * If xpah is not supported or issues with namespaces.
+
+        ValueError
+            * If xpah does not return any nodes.
+        """
+
+        raise AbstractMethodError(self)
+
+    def _validate_names(self) -> None:
+        """
+        Validate names.
+
+        This method will check if names is a list-like and aligns
+        with length of parse nodes.
+
+        Raises
+        ------
+        ValueError
+            * If value is not a list and less then length of nodes.
+        """
+        raise AbstractMethodError(self)
+
+    def _parse_doc(
+        self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str]
+    ) -> Element | etree._Element:
+        """
+        Build tree from path_or_buffer.
+
+        This method will parse XML object into tree
+        either from string/bytes or file location.
+        """
+        raise AbstractMethodError(self)
+
+
+class _EtreeFrameParser(_XMLFrameParser):
+    """
+    Internal class to parse XML into DataFrames with the Python
+    standard library XML module: `xml.etree.ElementTree`.
+    """
+
+    def parse_data(self) -> list[dict[str, str | None]]:
+        from xml.etree.ElementTree import iterparse
+
+        if self.stylesheet is not None:
+            raise ValueError(
+                "To use stylesheet, you need lxml installed and selected as parser."
+            )
+
+        if self.iterparse is None:
+            self.xml_doc = self._parse_doc(self.path_or_buffer)
+            elems = self._validate_path()
+
+        self._validate_names()
+
+        xml_dicts: list[dict[str, str | None]] = (
+            self._parse_nodes(elems)
+            if self.iterparse is None
+            else self._iterparse_nodes(iterparse)
+        )
+
+        return xml_dicts
+
+    def _validate_path(self) -> list[Any]:
+        """
+        Notes
+        -----
+        ``etree`` supports limited ``XPath``. If user attempts a more complex
+        expression syntax error will raise.
+        """
+
+        msg = (
+            "xpath does not return any nodes or attributes. "
+            "Be sure to specify in `xpath` the parent nodes of "
+            "children and attributes to parse. "
+            "If document uses namespaces denoted with "
+            "xmlns, be sure to define namespaces and "
+            "use them in xpath."
+        )
+        try:
+            elems = self.xml_doc.findall(self.xpath, namespaces=self.namespaces)
+            children = [ch for el in elems for ch in el.findall("*")]
+            attrs = {k: v for el in elems for k, v in el.attrib.items()}
+
+            if elems is None:
+                raise ValueError(msg)
+
+            if elems is not None:
+                if self.elems_only and children == []:
+                    raise ValueError(msg)
+                if self.attrs_only and attrs == {}:
+                    raise ValueError(msg)
+                if children == [] and attrs == {}:
+                    raise ValueError(msg)
+
+        except (KeyError, SyntaxError):
+            raise SyntaxError(
+                "You have used an incorrect or unsupported XPath "
+                "expression for etree library or you used an "
+                "undeclared namespace prefix."
+            )
+
+        return elems
+
+    def _validate_names(self) -> None:
+        children: list[Any]
+
+        if self.names:
+            if self.iterparse:
+                children = self.iterparse[next(iter(self.iterparse))]
+            else:
+                parent = self.xml_doc.find(self.xpath, namespaces=self.namespaces)
+                children = parent.findall("*") if parent is not None else []
+
+            if is_list_like(self.names):
+                if len(self.names) < len(children):
+                    raise ValueError(
+                        "names does not match length of child elements in xpath."
+                    )
+            else:
+                raise TypeError(
+                    f"{type(self.names).__name__} is not a valid type for names"
+                )
+
+    def _parse_doc(
+        self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str]
+    ) -> Element:
+        from xml.etree.ElementTree import (
+            XMLParser,
+            parse,
+        )
+
+        handle_data = get_data_from_filepath(
+            filepath_or_buffer=raw_doc,
+            encoding=self.encoding,
+            compression=self.compression,
+            storage_options=self.storage_options,
+        )
+
+        with preprocess_data(handle_data) as xml_data:
+            curr_parser = XMLParser(encoding=self.encoding)
+            document = parse(xml_data, parser=curr_parser)
+
+        return document.getroot()
+
+
+class _LxmlFrameParser(_XMLFrameParser):
+    """
+    Internal class to parse XML into :class:`~pandas.DataFrame` with third-party
+    full-featured XML library, ``lxml``, that supports
+    ``XPath`` 1.0 and XSLT 1.0.
+    """
+
+    def parse_data(self) -> list[dict[str, str | None]]:
+        """
+        Parse xml data.
+
+        This method will call the other internal methods to
+        validate ``xpath``, names, optionally parse and run XSLT,
+        and parse original or transformed XML and return specific nodes.
+        """
+        from lxml.etree import iterparse
+
+        if self.iterparse is None:
+            self.xml_doc = self._parse_doc(self.path_or_buffer)
+
+            if self.stylesheet:
+                self.xsl_doc = self._parse_doc(self.stylesheet)
+                self.xml_doc = self._transform_doc()
+
+            elems = self._validate_path()
+
+        self._validate_names()
+
+        xml_dicts: list[dict[str, str | None]] = (
+            self._parse_nodes(elems)
+            if self.iterparse is None
+            else self._iterparse_nodes(iterparse)
+        )
+
+        return xml_dicts
+
+    def _validate_path(self) -> list[Any]:
+        msg = (
+            "xpath does not return any nodes or attributes. "
+            "Be sure to specify in `xpath` the parent nodes of "
+            "children and attributes to parse. "
+            "If document uses namespaces denoted with "
+            "xmlns, be sure to define namespaces and "
+            "use them in xpath."
+        )
+
+        elems = self.xml_doc.xpath(self.xpath, namespaces=self.namespaces)
+        children = [ch for el in elems for ch in el.xpath("*")]
+        attrs = {k: v for el in elems for k, v in el.attrib.items()}
+
+        if elems == []:
+            raise ValueError(msg)
+
+        if elems != []:
+            if self.elems_only and children == []:
+                raise ValueError(msg)
+            if self.attrs_only and attrs == {}:
+                raise ValueError(msg)
+            if children == [] and attrs == {}:
+                raise ValueError(msg)
+
+        return elems
+
+    def _validate_names(self) -> None:
+        children: list[Any]
+
+        if self.names:
+            if self.iterparse:
+                children = self.iterparse[next(iter(self.iterparse))]
+            else:
+                children = self.xml_doc.xpath(
+                    self.xpath + "[1]/*", namespaces=self.namespaces
+                )
+
+            if is_list_like(self.names):
+                if len(self.names) < len(children):
+                    raise ValueError(
+                        "names does not match length of child elements in xpath."
+                    )
+            else:
+                raise TypeError(
+                    f"{type(self.names).__name__} is not a valid type for names"
+                )
+
+    def _parse_doc(
+        self, raw_doc: FilePath | ReadBuffer[bytes] | ReadBuffer[str]
+    ) -> etree._Element:
+        from lxml.etree import (
+            XMLParser,
+            fromstring,
+            parse,
+        )
+
+        handle_data = get_data_from_filepath(
+            filepath_or_buffer=raw_doc,
+            encoding=self.encoding,
+            compression=self.compression,
+            storage_options=self.storage_options,
+        )
+
+        with preprocess_data(handle_data) as xml_data:
+            curr_parser = XMLParser(encoding=self.encoding)
+
+            if isinstance(xml_data, io.StringIO):
+                if self.encoding is None:
+                    raise TypeError(
+                        "Can not pass encoding None when input is StringIO."
+                    )
+
+                document = fromstring(
+                    xml_data.getvalue().encode(self.encoding), parser=curr_parser
+                )
+            else:
+                document = parse(xml_data, parser=curr_parser)
+
+        return document
+
+    def _transform_doc(self) -> etree._XSLTResultTree:
+        """
+        Transform original tree using stylesheet.
+
+        This method will transform original xml using XSLT script into
+        am ideally flatter xml document for easier parsing and migration
+        to Data Frame.
+        """
+        from lxml.etree import XSLT
+
+        transformer = XSLT(self.xsl_doc)
+        new_doc = transformer(self.xml_doc)
+
+        return new_doc
+
+
+def get_data_from_filepath(
+    filepath_or_buffer: FilePath | bytes | ReadBuffer[bytes] | ReadBuffer[str],
+    encoding: str | None,
+    compression: CompressionOptions,
+    storage_options: StorageOptions,
+) -> str | bytes | ReadBuffer[bytes] | ReadBuffer[str]:
+    """
+    Extract raw XML data.
+
+    The method accepts three input types:
+        1. filepath (string-like)
+        2. file-like object (e.g. open file object, StringIO)
+        3. XML string or bytes
+
+    This method turns (1) into (2) to simplify the rest of the processing.
+    It returns input types (2) and (3) unchanged.
+    """
+    if not isinstance(filepath_or_buffer, bytes):
+        filepath_or_buffer = stringify_path(filepath_or_buffer)
+
+    if (
+        isinstance(filepath_or_buffer, str)
+        and not filepath_or_buffer.startswith((" io.StringIO | io.BytesIO:
+    """
+    Convert extracted raw data.
+
+    This method will return underlying data of extracted XML content.
+    The data either has a `read` attribute (e.g. a file object or a
+    StringIO/BytesIO) or is a string or bytes that is an XML document.
+    """
+
+    if isinstance(data, str):
+        data = io.StringIO(data)
+
+    elif isinstance(data, bytes):
+        data = io.BytesIO(data)
+
+    return data
+
+
+def _data_to_frame(data, **kwargs) -> DataFrame:
+    """
+    Convert parsed data to Data Frame.
+
+    This method will bind xml dictionary data of keys and values
+    into named columns of Data Frame using the built-in TextParser
+    class that build Data Frame and infers specific dtypes.
+    """
+
+    tags = next(iter(data))
+    nodes = [list(d.values()) for d in data]
+
+    try:
+        with TextParser(nodes, names=tags, **kwargs) as tp:
+            return tp.read()
+    except ParserError:
+        raise ParserError(
+            "XML document may be too complex for import. "
+            "Try to flatten document and use distinct "
+            "element and attribute names."
+        )
+
+
+def _parse(
+    path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str],
+    xpath: str,
+    namespaces: dict[str, str] | None,
+    elems_only: bool,
+    attrs_only: bool,
+    names: Sequence[str] | None,
+    dtype: DtypeArg | None,
+    converters: ConvertersArg | None,
+    parse_dates: ParseDatesArg | None,
+    encoding: str | None,
+    parser: XMLParsers,
+    stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None,
+    iterparse: dict[str, list[str]] | None,
+    compression: CompressionOptions,
+    storage_options: StorageOptions,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+    **kwargs,
+) -> DataFrame:
+    """
+    Call internal parsers.
+
+    This method will conditionally call internal parsers:
+    LxmlFrameParser and/or EtreeParser.
+
+    Raises
+    ------
+    ImportError
+        * If lxml is not installed if selected as parser.
+
+    ValueError
+        * If parser is not lxml or etree.
+    """
+
+    p: _EtreeFrameParser | _LxmlFrameParser
+
+    if isinstance(path_or_buffer, str) and not any(
+        [
+            is_file_like(path_or_buffer),
+            file_exists(path_or_buffer),
+            is_url(path_or_buffer),
+            is_fsspec_url(path_or_buffer),
+        ]
+    ):
+        warnings.warn(
+            "Passing literal xml to 'read_xml' is deprecated and "
+            "will be removed in a future version. To read from a "
+            "literal string, wrap it in a 'StringIO' object.",
+            FutureWarning,
+            stacklevel=find_stack_level(),
+        )
+
+    if parser == "lxml":
+        lxml = import_optional_dependency("lxml.etree", errors="ignore")
+
+        if lxml is not None:
+            p = _LxmlFrameParser(
+                path_or_buffer,
+                xpath,
+                namespaces,
+                elems_only,
+                attrs_only,
+                names,
+                dtype,
+                converters,
+                parse_dates,
+                encoding,
+                stylesheet,
+                iterparse,
+                compression,
+                storage_options,
+            )
+        else:
+            raise ImportError("lxml not found, please install or use the etree parser.")
+
+    elif parser == "etree":
+        p = _EtreeFrameParser(
+            path_or_buffer,
+            xpath,
+            namespaces,
+            elems_only,
+            attrs_only,
+            names,
+            dtype,
+            converters,
+            parse_dates,
+            encoding,
+            stylesheet,
+            iterparse,
+            compression,
+            storage_options,
+        )
+    else:
+        raise ValueError("Values for parser can only be lxml or etree.")
+
+    data_dicts = p.parse_data()
+
+    return _data_to_frame(
+        data=data_dicts,
+        dtype=dtype,
+        converters=converters,
+        parse_dates=parse_dates,
+        dtype_backend=dtype_backend,
+        **kwargs,
+    )
+
+
+@doc(
+    storage_options=_shared_docs["storage_options"],
+    decompression_options=_shared_docs["decompression_options"] % "path_or_buffer",
+)
+def read_xml(
+    path_or_buffer: FilePath | ReadBuffer[bytes] | ReadBuffer[str],
+    *,
+    xpath: str = "./*",
+    namespaces: dict[str, str] | None = None,
+    elems_only: bool = False,
+    attrs_only: bool = False,
+    names: Sequence[str] | None = None,
+    dtype: DtypeArg | None = None,
+    converters: ConvertersArg | None = None,
+    parse_dates: ParseDatesArg | None = None,
+    # encoding can not be None for lxml and StringIO input
+    encoding: str | None = "utf-8",
+    parser: XMLParsers = "lxml",
+    stylesheet: FilePath | ReadBuffer[bytes] | ReadBuffer[str] | None = None,
+    iterparse: dict[str, list[str]] | None = None,
+    compression: CompressionOptions = "infer",
+    storage_options: StorageOptions | None = None,
+    dtype_backend: DtypeBackend | lib.NoDefault = lib.no_default,
+) -> DataFrame:
+    r"""
+    Read XML document into a :class:`~pandas.DataFrame` object.
+
+    .. versionadded:: 1.3.0
+
+    Parameters
+    ----------
+    path_or_buffer : str, path object, or file-like object
+        String, path object (implementing ``os.PathLike[str]``), or file-like
+        object implementing a ``read()`` function. The string can be any valid XML
+        string or a path. The string can further be a URL. Valid URL schemes
+        include http, ftp, s3, and file.
+
+        .. deprecated:: 2.1.0
+            Passing xml literal strings is deprecated.
+            Wrap literal xml input in ``io.StringIO`` or ``io.BytesIO`` instead.
+
+    xpath : str, optional, default './\*'
+        The ``XPath`` to parse required set of nodes for migration to
+        :class:`~pandas.DataFrame`.``XPath`` should return a collection of elements
+        and not a single element. Note: The ``etree`` parser supports limited ``XPath``
+        expressions. For more complex ``XPath``, use ``lxml`` which requires
+        installation.
+
+    namespaces : dict, optional
+        The namespaces defined in XML document as dicts with key being
+        namespace prefix and value the URI. There is no need to include all
+        namespaces in XML, only the ones used in ``xpath`` expression.
+        Note: if XML document uses default namespace denoted as
+        `xmlns=''` without a prefix, you must assign any temporary
+        namespace prefix such as 'doc' to the URI in order to parse
+        underlying nodes and/or attributes. For example, ::
+
+            namespaces = {{"doc": "https://example.com"}}
+
+    elems_only : bool, optional, default False
+        Parse only the child elements at the specified ``xpath``. By default,
+        all child elements and non-empty text nodes are returned.
+
+    attrs_only :  bool, optional, default False
+        Parse only the attributes at the specified ``xpath``.
+        By default, all attributes are returned.
+
+    names :  list-like, optional
+        Column names for DataFrame of parsed XML data. Use this parameter to
+        rename original element names and distinguish same named elements and
+        attributes.
+
+    dtype : Type name or dict of column -> type, optional
+        Data type for data or columns. E.g. {{'a': np.float64, 'b': np.int32,
+        'c': 'Int64'}}
+        Use `str` or `object` together with suitable `na_values` settings
+        to preserve and not interpret dtype.
+        If converters are specified, they will be applied INSTEAD
+        of dtype conversion.
+
+        .. versionadded:: 1.5.0
+
+    converters : dict, optional
+        Dict of functions for converting values in certain columns. Keys can either
+        be integers or column labels.
+
+        .. versionadded:: 1.5.0
+
+    parse_dates : bool or list of int or names or list of lists or dict, default False
+        Identifiers to parse index or columns to datetime. The behavior is as follows:
+
+        * boolean. If True -> try parsing the index.
+        * list of int or names. e.g. If [1, 2, 3] -> try parsing columns 1, 2, 3
+          each as a separate date column.
+        * list of lists. e.g.  If [[1, 3]] -> combine columns 1 and 3 and parse as
+          a single date column.
+        * dict, e.g. {{'foo' : [1, 3]}} -> parse columns 1, 3 as date and call
+          result 'foo'
+
+        .. versionadded:: 1.5.0
+
+    encoding : str, optional, default 'utf-8'
+        Encoding of XML document.
+
+    parser : {{'lxml','etree'}}, default 'lxml'
+        Parser module to use for retrieval of data. Only 'lxml' and
+        'etree' are supported. With 'lxml' more complex ``XPath`` searches
+        and ability to use XSLT stylesheet are supported.
+
+    stylesheet : str, path object or file-like object
+        A URL, file-like object, or a raw string containing an XSLT script.
+        This stylesheet should flatten complex, deeply nested XML documents
+        for easier parsing. To use this feature you must have ``lxml`` module
+        installed and specify 'lxml' as ``parser``. The ``xpath`` must
+        reference nodes of transformed XML document generated after XSLT
+        transformation and not the original XML document. Only XSLT 1.0
+        scripts and not later versions is currently supported.
+
+    iterparse : dict, optional
+        The nodes or attributes to retrieve in iterparsing of XML document
+        as a dict with key being the name of repeating element and value being
+        list of elements or attribute names that are descendants of the repeated
+        element. Note: If this option is used, it will replace ``xpath`` parsing
+        and unlike ``xpath``, descendants do not need to relate to each other but can
+        exist any where in document under the repeating element. This memory-
+        efficient method should be used for very large XML files (500MB, 1GB, or 5GB+).
+        For example, ::
+
+            iterparse = {{"row_element": ["child_elem", "attr", "grandchild_elem"]}}
+
+        .. versionadded:: 1.5.0
+
+    {decompression_options}
+
+        .. versionchanged:: 1.4.0 Zstandard support.
+
+    {storage_options}
+
+    dtype_backend : {{'numpy_nullable', 'pyarrow'}}, default 'numpy_nullable'
+        Back-end data type applied to the resultant :class:`DataFrame`
+        (still experimental). Behaviour is as follows:
+
+        * ``"numpy_nullable"``: returns nullable-dtype-backed :class:`DataFrame`
+          (default).
+        * ``"pyarrow"``: returns pyarrow-backed nullable :class:`ArrowDtype`
+          DataFrame.
+
+        .. versionadded:: 2.0
+
+    Returns
+    -------
+    df
+        A DataFrame.
+
+    See Also
+    --------
+    read_json : Convert a JSON string to pandas object.
+    read_html : Read HTML tables into a list of DataFrame objects.
+
+    Notes
+    -----
+    This method is best designed to import shallow XML documents in
+    following format which is the ideal fit for the two-dimensions of a
+    ``DataFrame`` (row by column). ::
+
+            
+                
+                  data
+                  data
+                  data
+                  ...
+               
+               
+                  ...
+               
+               ...
+            
+
+    As a file format, XML documents can be designed any way including
+    layout of elements and attributes as long as it conforms to W3C
+    specifications. Therefore, this method is a convenience handler for
+    a specific flatter design and not all possible XML structures.
+
+    However, for more complex XML documents, ``stylesheet`` allows you to
+    temporarily redesign original document with XSLT (a special purpose
+    language) for a flatter version for migration to a DataFrame.
+
+    This function will *always* return a single :class:`DataFrame` or raise
+    exceptions due to issues with XML document, ``xpath``, or other
+    parameters.
+
+    See the :ref:`read_xml documentation in the IO section of the docs
+    ` for more information in using this method to parse XML
+    files to DataFrames.
+
+    Examples
+    --------
+    >>> from io import StringIO
+    >>> xml = '''
+    ... 
+    ...  
+    ...    square
+    ...    360
+    ...    4.0
+    ...  
+    ...  
+    ...    circle
+    ...    360
+    ...    
+    ...  
+    ...  
+    ...    triangle
+    ...    180
+    ...    3.0
+    ...  
+    ... '''
+
+    >>> df = pd.read_xml(StringIO(xml))
+    >>> df
+          shape  degrees  sides
+    0    square      360    4.0
+    1    circle      360    NaN
+    2  triangle      180    3.0
+
+    >>> xml = '''
+    ... 
+    ...   
+    ...   
+    ...   
+    ... '''
+
+    >>> df = pd.read_xml(StringIO(xml), xpath=".//row")
+    >>> df
+          shape  degrees  sides
+    0    square      360    4.0
+    1    circle      360    NaN
+    2  triangle      180    3.0
+
+    >>> xml = '''
+    ... 
+    ...   
+    ...     square
+    ...     360
+    ...     4.0
+    ...   
+    ...   
+    ...     circle
+    ...     360
+    ...     
+    ...   
+    ...   
+    ...     triangle
+    ...     180
+    ...     3.0
+    ...   
+    ... '''
+
+    >>> df = pd.read_xml(StringIO(xml),
+    ...                  xpath="//doc:row",
+    ...                  namespaces={{"doc": "https://example.com"}})
+    >>> df
+          shape  degrees  sides
+    0    square      360    4.0
+    1    circle      360    NaN
+    2  triangle      180    3.0
+
+    >>> xml_data = '''
+    ...         
+    ...            
+    ...               0
+    ...               1
+    ...               2.5
+    ...               True
+    ...               a
+    ...               2019-12-31 00:00:00
+    ...            
+    ...            
+    ...               1
+    ...               4.5
+    ...               False
+    ...               b
+    ...               2019-12-31 00:00:00
+    ...            
+    ...         
+    ...         '''
+
+    >>> df = pd.read_xml(StringIO(xml_data),
+    ...                  dtype_backend="numpy_nullable",
+    ...                  parse_dates=["e"])
+    >>> df
+       index     a    b      c  d          e
+    0      0     1  2.5   True  a 2019-12-31
+    1      1    4.5  False  b 2019-12-31
+    """
+    check_dtype_backend(dtype_backend)
+
+    return _parse(
+        path_or_buffer=path_or_buffer,
+        xpath=xpath,
+        namespaces=namespaces,
+        elems_only=elems_only,
+        attrs_only=attrs_only,
+        names=names,
+        dtype=dtype,
+        converters=converters,
+        parse_dates=parse_dates,
+        encoding=encoding,
+        parser=parser,
+        stylesheet=stylesheet,
+        iterparse=iterparse,
+        compression=compression,
+        storage_options=storage_options,
+        dtype_backend=dtype_backend,
+    )
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/__init__.py b/.venv/lib/python3.13/site-packages/pandas/plotting/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..55c861e384d679654b8615d4cb5808f536fd8f2e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/__init__.py
@@ -0,0 +1,98 @@
+"""
+Plotting public API.
+
+Authors of third-party plotting backends should implement a module with a
+public ``plot(data, kind, **kwargs)``. The parameter `data` will contain
+the data structure and can be a `Series` or a `DataFrame`. For example,
+for ``df.plot()`` the parameter `data` will contain the DataFrame `df`.
+In some cases, the data structure is transformed before being sent to
+the backend (see PlotAccessor.__call__ in pandas/plotting/_core.py for
+the exact transformations).
+
+The parameter `kind` will be one of:
+
+- line
+- bar
+- barh
+- box
+- hist
+- kde
+- area
+- pie
+- scatter
+- hexbin
+
+See the pandas API reference for documentation on each kind of plot.
+
+Any other keyword argument is currently assumed to be backend specific,
+but some parameters may be unified and added to the signature in the
+future (e.g. `title` which should be useful for any backend).
+
+Currently, all the Matplotlib functions in pandas are accessed through
+the selected backend. For example, `pandas.plotting.boxplot` (equivalent
+to `DataFrame.boxplot`) is also accessed in the selected backend. This
+is expected to change, and the exact API is under discussion. But with
+the current version, backends are expected to implement the next functions:
+
+- plot (describe above, used for `Series.plot` and `DataFrame.plot`)
+- hist_series and hist_frame (for `Series.hist` and `DataFrame.hist`)
+- boxplot (`pandas.plotting.boxplot(df)` equivalent to `DataFrame.boxplot`)
+- boxplot_frame and boxplot_frame_groupby
+- register and deregister (register converters for the tick formats)
+- Plots not called as `Series` and `DataFrame` methods:
+  - table
+  - andrews_curves
+  - autocorrelation_plot
+  - bootstrap_plot
+  - lag_plot
+  - parallel_coordinates
+  - radviz
+  - scatter_matrix
+
+Use the code in pandas/plotting/_matplotib.py and
+https://github.com/pyviz/hvplot as a reference on how to write a backend.
+
+For the discussion about the API see
+https://github.com/pandas-dev/pandas/issues/26747.
+"""
+from pandas.plotting._core import (
+    PlotAccessor,
+    boxplot,
+    boxplot_frame,
+    boxplot_frame_groupby,
+    hist_frame,
+    hist_series,
+)
+from pandas.plotting._misc import (
+    andrews_curves,
+    autocorrelation_plot,
+    bootstrap_plot,
+    deregister as deregister_matplotlib_converters,
+    lag_plot,
+    parallel_coordinates,
+    plot_params,
+    radviz,
+    register as register_matplotlib_converters,
+    scatter_matrix,
+    table,
+)
+
+__all__ = [
+    "PlotAccessor",
+    "boxplot",
+    "boxplot_frame",
+    "boxplot_frame_groupby",
+    "hist_frame",
+    "hist_series",
+    "scatter_matrix",
+    "radviz",
+    "andrews_curves",
+    "bootstrap_plot",
+    "parallel_coordinates",
+    "lag_plot",
+    "autocorrelation_plot",
+    "table",
+    "plot_params",
+    "register_matplotlib_converters",
+    "deregister_matplotlib_converters",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_core.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_core.py
new file mode 100644
index 0000000000000000000000000000000000000000..cb5598a98d5afbc93954d74e3ecc78b4e572606d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_core.py
@@ -0,0 +1,1946 @@
+from __future__ import annotations
+
+import importlib
+from typing import (
+    TYPE_CHECKING,
+    Callable,
+    Literal,
+)
+
+from pandas._config import get_option
+
+from pandas.util._decorators import (
+    Appender,
+    Substitution,
+)
+
+from pandas.core.dtypes.common import (
+    is_integer,
+    is_list_like,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCSeries,
+)
+
+from pandas.core.base import PandasObject
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Hashable,
+        Sequence,
+    )
+    import types
+
+    from matplotlib.axes import Axes
+    import numpy as np
+
+    from pandas._typing import IndexLabel
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+    from pandas.core.groupby.generic import DataFrameGroupBy
+
+
+def hist_series(
+    self: Series,
+    by=None,
+    ax=None,
+    grid: bool = True,
+    xlabelsize: int | None = None,
+    xrot: float | None = None,
+    ylabelsize: int | None = None,
+    yrot: float | None = None,
+    figsize: tuple[int, int] | None = None,
+    bins: int | Sequence[int] = 10,
+    backend: str | None = None,
+    legend: bool = False,
+    **kwargs,
+):
+    """
+    Draw histogram of the input series using matplotlib.
+
+    Parameters
+    ----------
+    by : object, optional
+        If passed, then used to form histograms for separate groups.
+    ax : matplotlib axis object
+        If not passed, uses gca().
+    grid : bool, default True
+        Whether to show axis grid lines.
+    xlabelsize : int, default None
+        If specified changes the x-axis label size.
+    xrot : float, default None
+        Rotation of x axis labels.
+    ylabelsize : int, default None
+        If specified changes the y-axis label size.
+    yrot : float, default None
+        Rotation of y axis labels.
+    figsize : tuple, default None
+        Figure size in inches by default.
+    bins : int or sequence, default 10
+        Number of histogram bins to be used. If an integer is given, bins + 1
+        bin edges are calculated and returned. If bins is a sequence, gives
+        bin edges, including left edge of first bin and right edge of last
+        bin. In this case, bins is returned unmodified.
+    backend : str, default None
+        Backend to use instead of the backend specified in the option
+        ``plotting.backend``. For instance, 'matplotlib'. Alternatively, to
+        specify the ``plotting.backend`` for the whole session, set
+        ``pd.options.plotting.backend``.
+    legend : bool, default False
+        Whether to show the legend.
+
+    **kwargs
+        To be passed to the actual plotting function.
+
+    Returns
+    -------
+    matplotlib.AxesSubplot
+        A histogram plot.
+
+    See Also
+    --------
+    matplotlib.axes.Axes.hist : Plot a histogram using matplotlib.
+
+    Examples
+    --------
+    For Series:
+
+    .. plot::
+        :context: close-figs
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 2, 4, 6, 6], index=lst)
+        >>> hist = ser.hist()
+
+    For Groupby:
+
+    .. plot::
+        :context: close-figs
+
+        >>> lst = ['a', 'a', 'a', 'b', 'b', 'b']
+        >>> ser = pd.Series([1, 2, 2, 4, 6, 6], index=lst)
+        >>> hist = ser.groupby(level=0).hist()
+    """
+    plot_backend = _get_plot_backend(backend)
+    return plot_backend.hist_series(
+        self,
+        by=by,
+        ax=ax,
+        grid=grid,
+        xlabelsize=xlabelsize,
+        xrot=xrot,
+        ylabelsize=ylabelsize,
+        yrot=yrot,
+        figsize=figsize,
+        bins=bins,
+        legend=legend,
+        **kwargs,
+    )
+
+
+def hist_frame(
+    data: DataFrame,
+    column: IndexLabel | None = None,
+    by=None,
+    grid: bool = True,
+    xlabelsize: int | None = None,
+    xrot: float | None = None,
+    ylabelsize: int | None = None,
+    yrot: float | None = None,
+    ax=None,
+    sharex: bool = False,
+    sharey: bool = False,
+    figsize: tuple[int, int] | None = None,
+    layout: tuple[int, int] | None = None,
+    bins: int | Sequence[int] = 10,
+    backend: str | None = None,
+    legend: bool = False,
+    **kwargs,
+):
+    """
+    Make a histogram of the DataFrame's columns.
+
+    A `histogram`_ is a representation of the distribution of data.
+    This function calls :meth:`matplotlib.pyplot.hist`, on each series in
+    the DataFrame, resulting in one histogram per column.
+
+    .. _histogram: https://en.wikipedia.org/wiki/Histogram
+
+    Parameters
+    ----------
+    data : DataFrame
+        The pandas object holding the data.
+    column : str or sequence, optional
+        If passed, will be used to limit data to a subset of columns.
+    by : object, optional
+        If passed, then used to form histograms for separate groups.
+    grid : bool, default True
+        Whether to show axis grid lines.
+    xlabelsize : int, default None
+        If specified changes the x-axis label size.
+    xrot : float, default None
+        Rotation of x axis labels. For example, a value of 90 displays the
+        x labels rotated 90 degrees clockwise.
+    ylabelsize : int, default None
+        If specified changes the y-axis label size.
+    yrot : float, default None
+        Rotation of y axis labels. For example, a value of 90 displays the
+        y labels rotated 90 degrees clockwise.
+    ax : Matplotlib axes object, default None
+        The axes to plot the histogram on.
+    sharex : bool, default True if ax is None else False
+        In case subplots=True, share x axis and set some x axis labels to
+        invisible; defaults to True if ax is None otherwise False if an ax
+        is passed in.
+        Note that passing in both an ax and sharex=True will alter all x axis
+        labels for all subplots in a figure.
+    sharey : bool, default False
+        In case subplots=True, share y axis and set some y axis labels to
+        invisible.
+    figsize : tuple, optional
+        The size in inches of the figure to create. Uses the value in
+        `matplotlib.rcParams` by default.
+    layout : tuple, optional
+        Tuple of (rows, columns) for the layout of the histograms.
+    bins : int or sequence, default 10
+        Number of histogram bins to be used. If an integer is given, bins + 1
+        bin edges are calculated and returned. If bins is a sequence, gives
+        bin edges, including left edge of first bin and right edge of last
+        bin. In this case, bins is returned unmodified.
+
+    backend : str, default None
+        Backend to use instead of the backend specified in the option
+        ``plotting.backend``. For instance, 'matplotlib'. Alternatively, to
+        specify the ``plotting.backend`` for the whole session, set
+        ``pd.options.plotting.backend``.
+
+    legend : bool, default False
+        Whether to show the legend.
+
+    **kwargs
+        All other plotting keyword arguments to be passed to
+        :meth:`matplotlib.pyplot.hist`.
+
+    Returns
+    -------
+    matplotlib.AxesSubplot or numpy.ndarray of them
+
+    See Also
+    --------
+    matplotlib.pyplot.hist : Plot a histogram using matplotlib.
+
+    Examples
+    --------
+    This example draws a histogram based on the length and width of
+    some animals, displayed in three bins
+
+    .. plot::
+        :context: close-figs
+
+        >>> data = {'length': [1.5, 0.5, 1.2, 0.9, 3],
+        ...         'width': [0.7, 0.2, 0.15, 0.2, 1.1]}
+        >>> index = ['pig', 'rabbit', 'duck', 'chicken', 'horse']
+        >>> df = pd.DataFrame(data, index=index)
+        >>> hist = df.hist(bins=3)
+    """
+    plot_backend = _get_plot_backend(backend)
+    return plot_backend.hist_frame(
+        data,
+        column=column,
+        by=by,
+        grid=grid,
+        xlabelsize=xlabelsize,
+        xrot=xrot,
+        ylabelsize=ylabelsize,
+        yrot=yrot,
+        ax=ax,
+        sharex=sharex,
+        sharey=sharey,
+        figsize=figsize,
+        layout=layout,
+        legend=legend,
+        bins=bins,
+        **kwargs,
+    )
+
+
+_boxplot_doc = """
+Make a box plot from DataFrame columns.
+
+Make a box-and-whisker plot from DataFrame columns, optionally grouped
+by some other columns. A box plot is a method for graphically depicting
+groups of numerical data through their quartiles.
+The box extends from the Q1 to Q3 quartile values of the data,
+with a line at the median (Q2). The whiskers extend from the edges
+of box to show the range of the data. By default, they extend no more than
+`1.5 * IQR (IQR = Q3 - Q1)` from the edges of the box, ending at the farthest
+data point within that interval. Outliers are plotted as separate dots.
+
+For further details see
+Wikipedia's entry for `boxplot `_.
+
+Parameters
+----------
+%(data)s\
+column : str or list of str, optional
+    Column name or list of names, or vector.
+    Can be any valid input to :meth:`pandas.DataFrame.groupby`.
+by : str or array-like, optional
+    Column in the DataFrame to :meth:`pandas.DataFrame.groupby`.
+    One box-plot will be done per value of columns in `by`.
+ax : object of class matplotlib.axes.Axes, optional
+    The matplotlib axes to be used by boxplot.
+fontsize : float or str
+    Tick label font size in points or as a string (e.g., `large`).
+rot : float, default 0
+    The rotation angle of labels (in degrees)
+    with respect to the screen coordinate system.
+grid : bool, default True
+    Setting this to True will show the grid.
+figsize : A tuple (width, height) in inches
+    The size of the figure to create in matplotlib.
+layout : tuple (rows, columns), optional
+    For example, (3, 5) will display the subplots
+    using 3 rows and 5 columns, starting from the top-left.
+return_type : {'axes', 'dict', 'both'} or None, default 'axes'
+    The kind of object to return. The default is ``axes``.
+
+    * 'axes' returns the matplotlib axes the boxplot is drawn on.
+    * 'dict' returns a dictionary whose values are the matplotlib
+      Lines of the boxplot.
+    * 'both' returns a namedtuple with the axes and dict.
+    * when grouping with ``by``, a Series mapping columns to
+      ``return_type`` is returned.
+
+      If ``return_type`` is `None`, a NumPy array
+      of axes with the same shape as ``layout`` is returned.
+%(backend)s\
+
+**kwargs
+    All other plotting keyword arguments to be passed to
+    :func:`matplotlib.pyplot.boxplot`.
+
+Returns
+-------
+result
+    See Notes.
+
+See Also
+--------
+pandas.Series.plot.hist: Make a histogram.
+matplotlib.pyplot.boxplot : Matplotlib equivalent plot.
+
+Notes
+-----
+The return type depends on the `return_type` parameter:
+
+* 'axes' : object of class matplotlib.axes.Axes
+* 'dict' : dict of matplotlib.lines.Line2D objects
+* 'both' : a namedtuple with structure (ax, lines)
+
+For data grouped with ``by``, return a Series of the above or a numpy
+array:
+
+* :class:`~pandas.Series`
+* :class:`~numpy.array` (for ``return_type = None``)
+
+Use ``return_type='dict'`` when you want to tweak the appearance
+of the lines after plotting. In this case a dict containing the Lines
+making up the boxes, caps, fliers, medians, and whiskers is returned.
+
+Examples
+--------
+
+Boxplots can be created for every column in the dataframe
+by ``df.boxplot()`` or indicating the columns to be used:
+
+.. plot::
+    :context: close-figs
+
+    >>> np.random.seed(1234)
+    >>> df = pd.DataFrame(np.random.randn(10, 4),
+    ...                   columns=['Col1', 'Col2', 'Col3', 'Col4'])
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2', 'Col3'])  # doctest: +SKIP
+
+Boxplots of variables distributions grouped by the values of a third
+variable can be created using the option ``by``. For instance:
+
+.. plot::
+    :context: close-figs
+
+    >>> df = pd.DataFrame(np.random.randn(10, 2),
+    ...                   columns=['Col1', 'Col2'])
+    >>> df['X'] = pd.Series(['A', 'A', 'A', 'A', 'A',
+    ...                      'B', 'B', 'B', 'B', 'B'])
+    >>> boxplot = df.boxplot(by='X')
+
+A list of strings (i.e. ``['X', 'Y']``) can be passed to boxplot
+in order to group the data by combination of the variables in the x-axis:
+
+.. plot::
+    :context: close-figs
+
+    >>> df = pd.DataFrame(np.random.randn(10, 3),
+    ...                   columns=['Col1', 'Col2', 'Col3'])
+    >>> df['X'] = pd.Series(['A', 'A', 'A', 'A', 'A',
+    ...                      'B', 'B', 'B', 'B', 'B'])
+    >>> df['Y'] = pd.Series(['A', 'B', 'A', 'B', 'A',
+    ...                      'B', 'A', 'B', 'A', 'B'])
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by=['X', 'Y'])
+
+The layout of boxplot can be adjusted giving a tuple to ``layout``:
+
+.. plot::
+    :context: close-figs
+
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+    ...                      layout=(2, 1))
+
+Additional formatting can be done to the boxplot, like suppressing the grid
+(``grid=False``), rotating the labels in the x-axis (i.e. ``rot=45``)
+or changing the fontsize (i.e. ``fontsize=15``):
+
+.. plot::
+    :context: close-figs
+
+    >>> boxplot = df.boxplot(grid=False, rot=45, fontsize=15)  # doctest: +SKIP
+
+The parameter ``return_type`` can be used to select the type of element
+returned by `boxplot`.  When ``return_type='axes'`` is selected,
+the matplotlib axes on which the boxplot is drawn are returned:
+
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2'], return_type='axes')
+    >>> type(boxplot)
+    
+
+When grouping with ``by``, a Series mapping columns to ``return_type``
+is returned:
+
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+    ...                      return_type='axes')
+    >>> type(boxplot)
+    
+
+If ``return_type`` is `None`, a NumPy array of axes with the same shape
+as ``layout`` is returned:
+
+    >>> boxplot = df.boxplot(column=['Col1', 'Col2'], by='X',
+    ...                      return_type=None)
+    >>> type(boxplot)
+    
+"""
+
+_backend_doc = """\
+backend : str, default None
+    Backend to use instead of the backend specified in the option
+    ``plotting.backend``. For instance, 'matplotlib'. Alternatively, to
+    specify the ``plotting.backend`` for the whole session, set
+    ``pd.options.plotting.backend``.
+"""
+
+
+_bar_or_line_doc = """
+        Parameters
+        ----------
+        x : label or position, optional
+            Allows plotting of one column versus another. If not specified,
+            the index of the DataFrame is used.
+        y : label or position, optional
+            Allows plotting of one column versus another. If not specified,
+            all numerical columns are used.
+        color : str, array-like, or dict, optional
+            The color for each of the DataFrame's columns. Possible values are:
+
+            - A single color string referred to by name, RGB or RGBA code,
+                for instance 'red' or '#a98d19'.
+
+            - A sequence of color strings referred to by name, RGB or RGBA
+                code, which will be used for each column recursively. For
+                instance ['green','yellow'] each column's %(kind)s will be filled in
+                green or yellow, alternatively. If there is only a single column to
+                be plotted, then only the first color from the color list will be
+                used.
+
+            - A dict of the form {column name : color}, so that each column will be
+                colored accordingly. For example, if your columns are called `a` and
+                `b`, then passing {'a': 'green', 'b': 'red'} will color %(kind)ss for
+                column `a` in green and %(kind)ss for column `b` in red.
+
+        **kwargs
+            Additional keyword arguments are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        matplotlib.axes.Axes or np.ndarray of them
+            An ndarray is returned with one :class:`matplotlib.axes.Axes`
+            per column when ``subplots=True``.
+"""
+
+
+@Substitution(data="data : DataFrame\n    The data to visualize.\n", backend="")
+@Appender(_boxplot_doc)
+def boxplot(
+    data: DataFrame,
+    column: str | list[str] | None = None,
+    by: str | list[str] | None = None,
+    ax: Axes | None = None,
+    fontsize: float | str | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    figsize: tuple[float, float] | None = None,
+    layout: tuple[int, int] | None = None,
+    return_type: str | None = None,
+    **kwargs,
+):
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.boxplot(
+        data,
+        column=column,
+        by=by,
+        ax=ax,
+        fontsize=fontsize,
+        rot=rot,
+        grid=grid,
+        figsize=figsize,
+        layout=layout,
+        return_type=return_type,
+        **kwargs,
+    )
+
+
+@Substitution(data="", backend=_backend_doc)
+@Appender(_boxplot_doc)
+def boxplot_frame(
+    self: DataFrame,
+    column=None,
+    by=None,
+    ax=None,
+    fontsize: int | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    return_type=None,
+    backend=None,
+    **kwargs,
+):
+    plot_backend = _get_plot_backend(backend)
+    return plot_backend.boxplot_frame(
+        self,
+        column=column,
+        by=by,
+        ax=ax,
+        fontsize=fontsize,
+        rot=rot,
+        grid=grid,
+        figsize=figsize,
+        layout=layout,
+        return_type=return_type,
+        **kwargs,
+    )
+
+
+def boxplot_frame_groupby(
+    grouped: DataFrameGroupBy,
+    subplots: bool = True,
+    column=None,
+    fontsize: int | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    ax=None,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    sharex: bool = False,
+    sharey: bool = True,
+    backend=None,
+    **kwargs,
+):
+    """
+    Make box plots from DataFrameGroupBy data.
+
+    Parameters
+    ----------
+    grouped : Grouped DataFrame
+    subplots : bool
+        * ``False`` - no subplots will be used
+        * ``True`` - create a subplot for each group.
+
+    column : column name or list of names, or vector
+        Can be any valid input to groupby.
+    fontsize : float or str
+    rot : label rotation angle
+    grid : Setting this to True will show the grid
+    ax : Matplotlib axis object, default None
+    figsize : A tuple (width, height) in inches
+    layout : tuple (optional)
+        The layout of the plot: (rows, columns).
+    sharex : bool, default False
+        Whether x-axes will be shared among subplots.
+    sharey : bool, default True
+        Whether y-axes will be shared among subplots.
+    backend : str, default None
+        Backend to use instead of the backend specified in the option
+        ``plotting.backend``. For instance, 'matplotlib'. Alternatively, to
+        specify the ``plotting.backend`` for the whole session, set
+        ``pd.options.plotting.backend``.
+    **kwargs
+        All other plotting keyword arguments to be passed to
+        matplotlib's boxplot function.
+
+    Returns
+    -------
+    dict of key/value = group key/DataFrame.boxplot return value
+    or DataFrame.boxplot return value in case subplots=figures=False
+
+    Examples
+    --------
+    You can create boxplots for grouped data and show them as separate subplots:
+
+    .. plot::
+        :context: close-figs
+
+        >>> import itertools
+        >>> tuples = [t for t in itertools.product(range(1000), range(4))]
+        >>> index = pd.MultiIndex.from_tuples(tuples, names=['lvl0', 'lvl1'])
+        >>> data = np.random.randn(len(index), 4)
+        >>> df = pd.DataFrame(data, columns=list('ABCD'), index=index)
+        >>> grouped = df.groupby(level='lvl1')
+        >>> grouped.boxplot(rot=45, fontsize=12, figsize=(8, 10))  # doctest: +SKIP
+
+    The ``subplots=False`` option shows the boxplots in a single figure.
+
+    .. plot::
+        :context: close-figs
+
+        >>> grouped.boxplot(subplots=False, rot=45, fontsize=12)  # doctest: +SKIP
+    """
+    plot_backend = _get_plot_backend(backend)
+    return plot_backend.boxplot_frame_groupby(
+        grouped,
+        subplots=subplots,
+        column=column,
+        fontsize=fontsize,
+        rot=rot,
+        grid=grid,
+        ax=ax,
+        figsize=figsize,
+        layout=layout,
+        sharex=sharex,
+        sharey=sharey,
+        **kwargs,
+    )
+
+
+class PlotAccessor(PandasObject):
+    """
+    Make plots of Series or DataFrame.
+
+    Uses the backend specified by the
+    option ``plotting.backend``. By default, matplotlib is used.
+
+    Parameters
+    ----------
+    data : Series or DataFrame
+        The object for which the method is called.
+    x : label or position, default None
+        Only used if data is a DataFrame.
+    y : label, position or list of label, positions, default None
+        Allows plotting of one column versus another. Only used if data is a
+        DataFrame.
+    kind : str
+        The kind of plot to produce:
+
+        - 'line' : line plot (default)
+        - 'bar' : vertical bar plot
+        - 'barh' : horizontal bar plot
+        - 'hist' : histogram
+        - 'box' : boxplot
+        - 'kde' : Kernel Density Estimation plot
+        - 'density' : same as 'kde'
+        - 'area' : area plot
+        - 'pie' : pie plot
+        - 'scatter' : scatter plot (DataFrame only)
+        - 'hexbin' : hexbin plot (DataFrame only)
+    ax : matplotlib axes object, default None
+        An axes of the current figure.
+    subplots : bool or sequence of iterables, default False
+        Whether to group columns into subplots:
+
+        - ``False`` : No subplots will be used
+        - ``True`` : Make separate subplots for each column.
+        - sequence of iterables of column labels: Create a subplot for each
+          group of columns. For example `[('a', 'c'), ('b', 'd')]` will
+          create 2 subplots: one with columns 'a' and 'c', and one
+          with columns 'b' and 'd'. Remaining columns that aren't specified
+          will be plotted in additional subplots (one per column).
+
+          .. versionadded:: 1.5.0
+
+    sharex : bool, default True if ax is None else False
+        In case ``subplots=True``, share x axis and set some x axis labels
+        to invisible; defaults to True if ax is None otherwise False if
+        an ax is passed in; Be aware, that passing in both an ax and
+        ``sharex=True`` will alter all x axis labels for all axis in a figure.
+    sharey : bool, default False
+        In case ``subplots=True``, share y axis and set some y axis labels to invisible.
+    layout : tuple, optional
+        (rows, columns) for the layout of subplots.
+    figsize : a tuple (width, height) in inches
+        Size of a figure object.
+    use_index : bool, default True
+        Use index as ticks for x axis.
+    title : str or list
+        Title to use for the plot. If a string is passed, print the string
+        at the top of the figure. If a list is passed and `subplots` is
+        True, print each item in the list above the corresponding subplot.
+    grid : bool, default None (matlab style default)
+        Axis grid lines.
+    legend : bool or {'reverse'}
+        Place legend on axis subplots.
+    style : list or dict
+        The matplotlib line style per column.
+    logx : bool or 'sym', default False
+        Use log scaling or symlog scaling on x axis.
+
+    logy : bool or 'sym' default False
+        Use log scaling or symlog scaling on y axis.
+
+    loglog : bool or 'sym', default False
+        Use log scaling or symlog scaling on both x and y axes.
+
+    xticks : sequence
+        Values to use for the xticks.
+    yticks : sequence
+        Values to use for the yticks.
+    xlim : 2-tuple/list
+        Set the x limits of the current axes.
+    ylim : 2-tuple/list
+        Set the y limits of the current axes.
+    xlabel : label, optional
+        Name to use for the xlabel on x-axis. Default uses index name as xlabel, or the
+        x-column name for planar plots.
+
+        .. versionchanged:: 2.0.0
+
+            Now applicable to histograms.
+
+    ylabel : label, optional
+        Name to use for the ylabel on y-axis. Default will show no ylabel, or the
+        y-column name for planar plots.
+
+        .. versionchanged:: 2.0.0
+
+            Now applicable to histograms.
+
+    rot : float, default None
+        Rotation for ticks (xticks for vertical, yticks for horizontal
+        plots).
+    fontsize : float, default None
+        Font size for xticks and yticks.
+    colormap : str or matplotlib colormap object, default None
+        Colormap to select colors from. If string, load colormap with that
+        name from matplotlib.
+    colorbar : bool, optional
+        If True, plot colorbar (only relevant for 'scatter' and 'hexbin'
+        plots).
+    position : float
+        Specify relative alignments for bar plot layout.
+        From 0 (left/bottom-end) to 1 (right/top-end). Default is 0.5
+        (center).
+    table : bool, Series or DataFrame, default False
+        If True, draw a table using the data in the DataFrame and the data
+        will be transposed to meet matplotlib's default layout.
+        If a Series or DataFrame is passed, use passed data to draw a
+        table.
+    yerr : DataFrame, Series, array-like, dict and str
+        See :ref:`Plotting with Error Bars ` for
+        detail.
+    xerr : DataFrame, Series, array-like, dict and str
+        Equivalent to yerr.
+    stacked : bool, default False in line and bar plots, and True in area plot
+        If True, create stacked plot.
+    secondary_y : bool or sequence, default False
+        Whether to plot on the secondary y-axis if a list/tuple, which
+        columns to plot on secondary y-axis.
+    mark_right : bool, default True
+        When using a secondary_y axis, automatically mark the column
+        labels with "(right)" in the legend.
+    include_bool : bool, default is False
+        If True, boolean values can be plotted.
+    backend : str, default None
+        Backend to use instead of the backend specified in the option
+        ``plotting.backend``. For instance, 'matplotlib'. Alternatively, to
+        specify the ``plotting.backend`` for the whole session, set
+        ``pd.options.plotting.backend``.
+    **kwargs
+        Options to pass to matplotlib plotting method.
+
+    Returns
+    -------
+    :class:`matplotlib.axes.Axes` or numpy.ndarray of them
+        If the backend is not the default matplotlib one, the return value
+        will be the object returned by the backend.
+
+    Notes
+    -----
+    - See matplotlib documentation online for more on this subject
+    - If `kind` = 'bar' or 'barh', you can specify relative alignments
+      for bar plot layout by `position` keyword.
+      From 0 (left/bottom-end) to 1 (right/top-end). Default is 0.5
+      (center)
+
+    Examples
+    --------
+    For Series:
+
+    .. plot::
+        :context: close-figs
+
+        >>> ser = pd.Series([1, 2, 3, 3])
+        >>> plot = ser.plot(kind='hist', title="My plot")
+
+    For DataFrame:
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.DataFrame({'length': [1.5, 0.5, 1.2, 0.9, 3],
+        ...                   'width': [0.7, 0.2, 0.15, 0.2, 1.1]},
+        ...                   index=['pig', 'rabbit', 'duck', 'chicken', 'horse'])
+        >>> plot = df.plot(title="DataFrame Plot")
+
+    For SeriesGroupBy:
+
+    .. plot::
+        :context: close-figs
+
+        >>> lst = [-1, -2, -3, 1, 2, 3]
+        >>> ser = pd.Series([1, 2, 2, 4, 6, 6], index=lst)
+        >>> plot = ser.groupby(lambda x: x > 0).plot(title="SeriesGroupBy Plot")
+
+    For DataFrameGroupBy:
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.DataFrame({"col1" : [1, 2, 3, 4],
+        ...                   "col2" : ["A", "B", "A", "B"]})
+        >>> plot = df.groupby("col2").plot(kind="bar", title="DataFrameGroupBy Plot")
+    """
+
+    _common_kinds = ("line", "bar", "barh", "kde", "density", "area", "hist", "box")
+    _series_kinds = ("pie",)
+    _dataframe_kinds = ("scatter", "hexbin")
+    _kind_aliases = {"density": "kde"}
+    _all_kinds = _common_kinds + _series_kinds + _dataframe_kinds
+
+    def __init__(self, data: Series | DataFrame) -> None:
+        self._parent = data
+
+    @staticmethod
+    def _get_call_args(backend_name: str, data: Series | DataFrame, args, kwargs):
+        """
+        This function makes calls to this accessor `__call__` method compatible
+        with the previous `SeriesPlotMethods.__call__` and
+        `DataFramePlotMethods.__call__`. Those had slightly different
+        signatures, since `DataFramePlotMethods` accepted `x` and `y`
+        parameters.
+        """
+        if isinstance(data, ABCSeries):
+            arg_def = [
+                ("kind", "line"),
+                ("ax", None),
+                ("figsize", None),
+                ("use_index", True),
+                ("title", None),
+                ("grid", None),
+                ("legend", False),
+                ("style", None),
+                ("logx", False),
+                ("logy", False),
+                ("loglog", False),
+                ("xticks", None),
+                ("yticks", None),
+                ("xlim", None),
+                ("ylim", None),
+                ("rot", None),
+                ("fontsize", None),
+                ("colormap", None),
+                ("table", False),
+                ("yerr", None),
+                ("xerr", None),
+                ("label", None),
+                ("secondary_y", False),
+                ("xlabel", None),
+                ("ylabel", None),
+            ]
+        elif isinstance(data, ABCDataFrame):
+            arg_def = [
+                ("x", None),
+                ("y", None),
+                ("kind", "line"),
+                ("ax", None),
+                ("subplots", False),
+                ("sharex", None),
+                ("sharey", False),
+                ("layout", None),
+                ("figsize", None),
+                ("use_index", True),
+                ("title", None),
+                ("grid", None),
+                ("legend", True),
+                ("style", None),
+                ("logx", False),
+                ("logy", False),
+                ("loglog", False),
+                ("xticks", None),
+                ("yticks", None),
+                ("xlim", None),
+                ("ylim", None),
+                ("rot", None),
+                ("fontsize", None),
+                ("colormap", None),
+                ("table", False),
+                ("yerr", None),
+                ("xerr", None),
+                ("secondary_y", False),
+                ("xlabel", None),
+                ("ylabel", None),
+            ]
+        else:
+            raise TypeError(
+                f"Called plot accessor for type {type(data).__name__}, "
+                "expected Series or DataFrame"
+            )
+
+        if args and isinstance(data, ABCSeries):
+            positional_args = str(args)[1:-1]
+            keyword_args = ", ".join(
+                [f"{name}={repr(value)}" for (name, _), value in zip(arg_def, args)]
+            )
+            msg = (
+                "`Series.plot()` should not be called with positional "
+                "arguments, only keyword arguments. The order of "
+                "positional arguments will change in the future. "
+                f"Use `Series.plot({keyword_args})` instead of "
+                f"`Series.plot({positional_args})`."
+            )
+            raise TypeError(msg)
+
+        pos_args = {name: value for (name, _), value in zip(arg_def, args)}
+        if backend_name == "pandas.plotting._matplotlib":
+            kwargs = dict(arg_def, **pos_args, **kwargs)
+        else:
+            kwargs = dict(pos_args, **kwargs)
+
+        x = kwargs.pop("x", None)
+        y = kwargs.pop("y", None)
+        kind = kwargs.pop("kind", "line")
+        return x, y, kind, kwargs
+
+    def __call__(self, *args, **kwargs):
+        plot_backend = _get_plot_backend(kwargs.pop("backend", None))
+
+        x, y, kind, kwargs = self._get_call_args(
+            plot_backend.__name__, self._parent, args, kwargs
+        )
+
+        kind = self._kind_aliases.get(kind, kind)
+
+        # when using another backend, get out of the way
+        if plot_backend.__name__ != "pandas.plotting._matplotlib":
+            return plot_backend.plot(self._parent, x=x, y=y, kind=kind, **kwargs)
+
+        if kind not in self._all_kinds:
+            raise ValueError(
+                f"{kind} is not a valid plot kind "
+                f"Valid plot kinds: {self._all_kinds}"
+            )
+
+        # The original data structured can be transformed before passed to the
+        # backend. For example, for DataFrame is common to set the index as the
+        # `x` parameter, and return a Series with the parameter `y` as values.
+        data = self._parent.copy()
+
+        if isinstance(data, ABCSeries):
+            kwargs["reuse_plot"] = True
+
+        if kind in self._dataframe_kinds:
+            if isinstance(data, ABCDataFrame):
+                return plot_backend.plot(data, x=x, y=y, kind=kind, **kwargs)
+            else:
+                raise ValueError(f"plot kind {kind} can only be used for data frames")
+        elif kind in self._series_kinds:
+            if isinstance(data, ABCDataFrame):
+                if y is None and kwargs.get("subplots") is False:
+                    raise ValueError(
+                        f"{kind} requires either y column or 'subplots=True'"
+                    )
+                if y is not None:
+                    if is_integer(y) and not data.columns._holds_integer():
+                        y = data.columns[y]
+                    # converted to series actually. copy to not modify
+                    data = data[y].copy()
+                    data.index.name = y
+        elif isinstance(data, ABCDataFrame):
+            data_cols = data.columns
+            if x is not None:
+                if is_integer(x) and not data.columns._holds_integer():
+                    x = data_cols[x]
+                elif not isinstance(data[x], ABCSeries):
+                    raise ValueError("x must be a label or position")
+                data = data.set_index(x)
+            if y is not None:
+                # check if we have y as int or list of ints
+                int_ylist = is_list_like(y) and all(is_integer(c) for c in y)
+                int_y_arg = is_integer(y) or int_ylist
+                if int_y_arg and not data.columns._holds_integer():
+                    y = data_cols[y]
+
+                label_kw = kwargs["label"] if "label" in kwargs else False
+                for kw in ["xerr", "yerr"]:
+                    if kw in kwargs and (
+                        isinstance(kwargs[kw], str) or is_integer(kwargs[kw])
+                    ):
+                        try:
+                            kwargs[kw] = data[kwargs[kw]]
+                        except (IndexError, KeyError, TypeError):
+                            pass
+
+                # don't overwrite
+                data = data[y].copy()
+
+                if isinstance(data, ABCSeries):
+                    label_name = label_kw or y
+                    data.name = label_name
+                else:
+                    match = is_list_like(label_kw) and len(label_kw) == len(y)
+                    if label_kw and not match:
+                        raise ValueError(
+                            "label should be list-like and same length as y"
+                        )
+                    label_name = label_kw or data.columns
+                    data.columns = label_name
+
+        return plot_backend.plot(data, kind=kind, **kwargs)
+
+    __call__.__doc__ = __doc__
+
+    @Appender(
+        """
+        See Also
+        --------
+        matplotlib.pyplot.plot : Plot y versus x as lines and/or markers.
+
+        Examples
+        --------
+
+        .. plot::
+            :context: close-figs
+
+            >>> s = pd.Series([1, 3, 2])
+            >>> s.plot.line()  # doctest: +SKIP
+
+        .. plot::
+            :context: close-figs
+
+            The following example shows the populations for some animals
+            over the years.
+
+            >>> df = pd.DataFrame({
+            ...    'pig': [20, 18, 489, 675, 1776],
+            ...    'horse': [4, 25, 281, 600, 1900]
+            ...    }, index=[1990, 1997, 2003, 2009, 2014])
+            >>> lines = df.plot.line()
+
+        .. plot::
+           :context: close-figs
+
+           An example with subplots, so an array of axes is returned.
+
+           >>> axes = df.plot.line(subplots=True)
+           >>> type(axes)
+           
+
+        .. plot::
+           :context: close-figs
+
+           Let's repeat the same example, but specifying colors for
+           each column (in this case, for each animal).
+
+           >>> axes = df.plot.line(
+           ...     subplots=True, color={"pig": "pink", "horse": "#742802"}
+           ... )
+
+        .. plot::
+            :context: close-figs
+
+            The following example shows the relationship between both
+            populations.
+
+            >>> lines = df.plot.line(x='pig', y='horse')
+        """
+    )
+    @Substitution(kind="line")
+    @Appender(_bar_or_line_doc)
+    def line(
+        self, x: Hashable | None = None, y: Hashable | None = None, **kwargs
+    ) -> PlotAccessor:
+        """
+        Plot Series or DataFrame as lines.
+
+        This function is useful to plot lines using DataFrame's values
+        as coordinates.
+        """
+        return self(kind="line", x=x, y=y, **kwargs)
+
+    @Appender(
+        """
+        See Also
+        --------
+        DataFrame.plot.barh : Horizontal bar plot.
+        DataFrame.plot : Make plots of a DataFrame.
+        matplotlib.pyplot.bar : Make a bar plot with matplotlib.
+
+        Examples
+        --------
+        Basic plot.
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({'lab':['A', 'B', 'C'], 'val':[10, 30, 20]})
+            >>> ax = df.plot.bar(x='lab', y='val', rot=0)
+
+        Plot a whole dataframe to a bar plot. Each column is assigned a
+        distinct color, and each row is nested in a group along the
+        horizontal axis.
+
+        .. plot::
+            :context: close-figs
+
+            >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
+            >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
+            >>> index = ['snail', 'pig', 'elephant',
+            ...          'rabbit', 'giraffe', 'coyote', 'horse']
+            >>> df = pd.DataFrame({'speed': speed,
+            ...                    'lifespan': lifespan}, index=index)
+            >>> ax = df.plot.bar(rot=0)
+
+        Plot stacked bar charts for the DataFrame
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.bar(stacked=True)
+
+        Instead of nesting, the figure can be split by column with
+        ``subplots=True``. In this case, a :class:`numpy.ndarray` of
+        :class:`matplotlib.axes.Axes` are returned.
+
+        .. plot::
+            :context: close-figs
+
+            >>> axes = df.plot.bar(rot=0, subplots=True)
+            >>> axes[1].legend(loc=2)  # doctest: +SKIP
+
+        If you don't like the default colours, you can specify how you'd
+        like each column to be colored.
+
+        .. plot::
+            :context: close-figs
+
+            >>> axes = df.plot.bar(
+            ...     rot=0, subplots=True, color={"speed": "red", "lifespan": "green"}
+            ... )
+            >>> axes[1].legend(loc=2)  # doctest: +SKIP
+
+        Plot a single column.
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.bar(y='speed', rot=0)
+
+        Plot only selected categories for the DataFrame.
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.bar(x='lifespan', rot=0)
+    """
+    )
+    @Substitution(kind="bar")
+    @Appender(_bar_or_line_doc)
+    def bar(  # pylint: disable=disallowed-name
+        self, x: Hashable | None = None, y: Hashable | None = None, **kwargs
+    ) -> PlotAccessor:
+        """
+        Vertical bar plot.
+
+        A bar plot is a plot that presents categorical data with
+        rectangular bars with lengths proportional to the values that they
+        represent. A bar plot shows comparisons among discrete categories. One
+        axis of the plot shows the specific categories being compared, and the
+        other axis represents a measured value.
+        """
+        return self(kind="bar", x=x, y=y, **kwargs)
+
+    @Appender(
+        """
+        See Also
+        --------
+        DataFrame.plot.bar: Vertical bar plot.
+        DataFrame.plot : Make plots of DataFrame using matplotlib.
+        matplotlib.axes.Axes.bar : Plot a vertical bar plot using matplotlib.
+
+        Examples
+        --------
+        Basic example
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({'lab': ['A', 'B', 'C'], 'val': [10, 30, 20]})
+            >>> ax = df.plot.barh(x='lab', y='val')
+
+        Plot a whole DataFrame to a horizontal bar plot
+
+        .. plot::
+            :context: close-figs
+
+            >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
+            >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
+            >>> index = ['snail', 'pig', 'elephant',
+            ...          'rabbit', 'giraffe', 'coyote', 'horse']
+            >>> df = pd.DataFrame({'speed': speed,
+            ...                    'lifespan': lifespan}, index=index)
+            >>> ax = df.plot.barh()
+
+        Plot stacked barh charts for the DataFrame
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.barh(stacked=True)
+
+        We can specify colors for each column
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.barh(color={"speed": "red", "lifespan": "green"})
+
+        Plot a column of the DataFrame to a horizontal bar plot
+
+        .. plot::
+            :context: close-figs
+
+            >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
+            >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
+            >>> index = ['snail', 'pig', 'elephant',
+            ...          'rabbit', 'giraffe', 'coyote', 'horse']
+            >>> df = pd.DataFrame({'speed': speed,
+            ...                    'lifespan': lifespan}, index=index)
+            >>> ax = df.plot.barh(y='speed')
+
+        Plot DataFrame versus the desired column
+
+        .. plot::
+            :context: close-figs
+
+            >>> speed = [0.1, 17.5, 40, 48, 52, 69, 88]
+            >>> lifespan = [2, 8, 70, 1.5, 25, 12, 28]
+            >>> index = ['snail', 'pig', 'elephant',
+            ...          'rabbit', 'giraffe', 'coyote', 'horse']
+            >>> df = pd.DataFrame({'speed': speed,
+            ...                    'lifespan': lifespan}, index=index)
+            >>> ax = df.plot.barh(x='lifespan')
+    """
+    )
+    @Substitution(kind="bar")
+    @Appender(_bar_or_line_doc)
+    def barh(
+        self, x: Hashable | None = None, y: Hashable | None = None, **kwargs
+    ) -> PlotAccessor:
+        """
+        Make a horizontal bar plot.
+
+        A horizontal bar plot is a plot that presents quantitative data with
+        rectangular bars with lengths proportional to the values that they
+        represent. A bar plot shows comparisons among discrete categories. One
+        axis of the plot shows the specific categories being compared, and the
+        other axis represents a measured value.
+        """
+        return self(kind="barh", x=x, y=y, **kwargs)
+
+    def box(self, by: IndexLabel | None = None, **kwargs) -> PlotAccessor:
+        r"""
+        Make a box plot of the DataFrame columns.
+
+        A box plot is a method for graphically depicting groups of numerical
+        data through their quartiles.
+        The box extends from the Q1 to Q3 quartile values of the data,
+        with a line at the median (Q2). The whiskers extend from the edges
+        of box to show the range of the data. The position of the whiskers
+        is set by default to 1.5*IQR (IQR = Q3 - Q1) from the edges of the
+        box. Outlier points are those past the end of the whiskers.
+
+        For further details see Wikipedia's
+        entry for `boxplot `__.
+
+        A consideration when using this chart is that the box and the whiskers
+        can overlap, which is very common when plotting small sets of data.
+
+        Parameters
+        ----------
+        by : str or sequence
+            Column in the DataFrame to group by.
+
+            .. versionchanged:: 1.4.0
+
+               Previously, `by` is silently ignore and makes no groupings
+
+        **kwargs
+            Additional keywords are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        :class:`matplotlib.axes.Axes` or numpy.ndarray of them
+
+        See Also
+        --------
+        DataFrame.boxplot: Another method to draw a box plot.
+        Series.plot.box: Draw a box plot from a Series object.
+        matplotlib.pyplot.boxplot: Draw a box plot in matplotlib.
+
+        Examples
+        --------
+        Draw a box plot from a DataFrame with four columns of randomly
+        generated data.
+
+        .. plot::
+            :context: close-figs
+
+            >>> data = np.random.randn(25, 4)
+            >>> df = pd.DataFrame(data, columns=list('ABCD'))
+            >>> ax = df.plot.box()
+
+        You can also generate groupings if you specify the `by` parameter (which
+        can take a column name, or a list or tuple of column names):
+
+        .. versionchanged:: 1.4.0
+
+        .. plot::
+            :context: close-figs
+
+            >>> age_list = [8, 10, 12, 14, 72, 74, 76, 78, 20, 25, 30, 35, 60, 85]
+            >>> df = pd.DataFrame({"gender": list("MMMMMMMMFFFFFF"), "age": age_list})
+            >>> ax = df.plot.box(column="age", by="gender", figsize=(10, 8))
+        """
+        return self(kind="box", by=by, **kwargs)
+
+    def hist(
+        self, by: IndexLabel | None = None, bins: int = 10, **kwargs
+    ) -> PlotAccessor:
+        """
+        Draw one histogram of the DataFrame's columns.
+
+        A histogram is a representation of the distribution of data.
+        This function groups the values of all given Series in the DataFrame
+        into bins and draws all bins in one :class:`matplotlib.axes.Axes`.
+        This is useful when the DataFrame's Series are in a similar scale.
+
+        Parameters
+        ----------
+        by : str or sequence, optional
+            Column in the DataFrame to group by.
+
+            .. versionchanged:: 1.4.0
+
+               Previously, `by` is silently ignore and makes no groupings
+
+        bins : int, default 10
+            Number of histogram bins to be used.
+        **kwargs
+            Additional keyword arguments are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        class:`matplotlib.AxesSubplot`
+            Return a histogram plot.
+
+        See Also
+        --------
+        DataFrame.hist : Draw histograms per DataFrame's Series.
+        Series.hist : Draw a histogram with Series' data.
+
+        Examples
+        --------
+        When we roll a die 6000 times, we expect to get each value around 1000
+        times. But when we roll two dice and sum the result, the distribution
+        is going to be quite different. A histogram illustrates those
+        distributions.
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame(np.random.randint(1, 7, 6000), columns=['one'])
+            >>> df['two'] = df['one'] + np.random.randint(1, 7, 6000)
+            >>> ax = df.plot.hist(bins=12, alpha=0.5)
+
+        A grouped histogram can be generated by providing the parameter `by` (which
+        can be a column name, or a list of column names):
+
+        .. plot::
+            :context: close-figs
+
+            >>> age_list = [8, 10, 12, 14, 72, 74, 76, 78, 20, 25, 30, 35, 60, 85]
+            >>> df = pd.DataFrame({"gender": list("MMMMMMMMFFFFFF"), "age": age_list})
+            >>> ax = df.plot.hist(column=["age"], by="gender", figsize=(10, 8))
+        """
+        return self(kind="hist", by=by, bins=bins, **kwargs)
+
+    def kde(
+        self,
+        bw_method: Literal["scott", "silverman"] | float | Callable | None = None,
+        ind: np.ndarray | int | None = None,
+        **kwargs,
+    ) -> PlotAccessor:
+        """
+        Generate Kernel Density Estimate plot using Gaussian kernels.
+
+        In statistics, `kernel density estimation`_ (KDE) is a non-parametric
+        way to estimate the probability density function (PDF) of a random
+        variable. This function uses Gaussian kernels and includes automatic
+        bandwidth determination.
+
+        .. _kernel density estimation:
+            https://en.wikipedia.org/wiki/Kernel_density_estimation
+
+        Parameters
+        ----------
+        bw_method : str, scalar or callable, optional
+            The method used to calculate the estimator bandwidth. This can be
+            'scott', 'silverman', a scalar constant or a callable.
+            If None (default), 'scott' is used.
+            See :class:`scipy.stats.gaussian_kde` for more information.
+        ind : NumPy array or int, optional
+            Evaluation points for the estimated PDF. If None (default),
+            1000 equally spaced points are used. If `ind` is a NumPy array, the
+            KDE is evaluated at the points passed. If `ind` is an integer,
+            `ind` number of equally spaced points are used.
+        **kwargs
+            Additional keyword arguments are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        matplotlib.axes.Axes or numpy.ndarray of them
+
+        See Also
+        --------
+        scipy.stats.gaussian_kde : Representation of a kernel-density
+            estimate using Gaussian kernels. This is the function used
+            internally to estimate the PDF.
+
+        Examples
+        --------
+        Given a Series of points randomly sampled from an unknown
+        distribution, estimate its PDF using KDE with automatic
+        bandwidth determination and plot the results, evaluating them at
+        1000 equally spaced points (default):
+
+        .. plot::
+            :context: close-figs
+
+            >>> s = pd.Series([1, 2, 2.5, 3, 3.5, 4, 5])
+            >>> ax = s.plot.kde()
+
+        A scalar bandwidth can be specified. Using a small bandwidth value can
+        lead to over-fitting, while using a large bandwidth value may result
+        in under-fitting:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = s.plot.kde(bw_method=0.3)
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = s.plot.kde(bw_method=3)
+
+        Finally, the `ind` parameter determines the evaluation points for the
+        plot of the estimated PDF:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = s.plot.kde(ind=[1, 2, 3, 4, 5])
+
+        For DataFrame, it works in the same way:
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({
+            ...     'x': [1, 2, 2.5, 3, 3.5, 4, 5],
+            ...     'y': [4, 4, 4.5, 5, 5.5, 6, 6],
+            ... })
+            >>> ax = df.plot.kde()
+
+        A scalar bandwidth can be specified. Using a small bandwidth value can
+        lead to over-fitting, while using a large bandwidth value may result
+        in under-fitting:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.kde(bw_method=0.3)
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.kde(bw_method=3)
+
+        Finally, the `ind` parameter determines the evaluation points for the
+        plot of the estimated PDF:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.kde(ind=[1, 2, 3, 4, 5, 6])
+        """
+        return self(kind="kde", bw_method=bw_method, ind=ind, **kwargs)
+
+    density = kde
+
+    def area(
+        self,
+        x: Hashable | None = None,
+        y: Hashable | None = None,
+        stacked: bool = True,
+        **kwargs,
+    ) -> PlotAccessor:
+        """
+        Draw a stacked area plot.
+
+        An area plot displays quantitative data visually.
+        This function wraps the matplotlib area function.
+
+        Parameters
+        ----------
+        x : label or position, optional
+            Coordinates for the X axis. By default uses the index.
+        y : label or position, optional
+            Column to plot. By default uses all columns.
+        stacked : bool, default True
+            Area plots are stacked by default. Set to False to create a
+            unstacked plot.
+        **kwargs
+            Additional keyword arguments are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        matplotlib.axes.Axes or numpy.ndarray
+            Area plot, or array of area plots if subplots is True.
+
+        See Also
+        --------
+        DataFrame.plot : Make plots of DataFrame using matplotlib / pylab.
+
+        Examples
+        --------
+        Draw an area plot based on basic business metrics:
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({
+            ...     'sales': [3, 2, 3, 9, 10, 6],
+            ...     'signups': [5, 5, 6, 12, 14, 13],
+            ...     'visits': [20, 42, 28, 62, 81, 50],
+            ... }, index=pd.date_range(start='2018/01/01', end='2018/07/01',
+            ...                        freq='ME'))
+            >>> ax = df.plot.area()
+
+        Area plots are stacked by default. To produce an unstacked plot,
+        pass ``stacked=False``:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.area(stacked=False)
+
+        Draw an area plot for a single column:
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax = df.plot.area(y='sales')
+
+        Draw with a different `x`:
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({
+            ...     'sales': [3, 2, 3],
+            ...     'visits': [20, 42, 28],
+            ...     'day': [1, 2, 3],
+            ... })
+            >>> ax = df.plot.area(x='day')
+        """
+        return self(kind="area", x=x, y=y, stacked=stacked, **kwargs)
+
+    def pie(self, **kwargs) -> PlotAccessor:
+        """
+        Generate a pie plot.
+
+        A pie plot is a proportional representation of the numerical data in a
+        column. This function wraps :meth:`matplotlib.pyplot.pie` for the
+        specified column. If no column reference is passed and
+        ``subplots=True`` a pie plot is drawn for each numerical column
+        independently.
+
+        Parameters
+        ----------
+        y : int or label, optional
+            Label or position of the column to plot.
+            If not provided, ``subplots=True`` argument must be passed.
+        **kwargs
+            Keyword arguments to pass on to :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        matplotlib.axes.Axes or np.ndarray of them
+            A NumPy array is returned when `subplots` is True.
+
+        See Also
+        --------
+        Series.plot.pie : Generate a pie plot for a Series.
+        DataFrame.plot : Make plots of a DataFrame.
+
+        Examples
+        --------
+        In the example below we have a DataFrame with the information about
+        planet's mass and radius. We pass the 'mass' column to the
+        pie function to get a pie plot.
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame({'mass': [0.330, 4.87 , 5.97],
+            ...                    'radius': [2439.7, 6051.8, 6378.1]},
+            ...                   index=['Mercury', 'Venus', 'Earth'])
+            >>> plot = df.plot.pie(y='mass', figsize=(5, 5))
+
+        .. plot::
+            :context: close-figs
+
+            >>> plot = df.plot.pie(subplots=True, figsize=(11, 6))
+        """
+        if (
+            isinstance(self._parent, ABCDataFrame)
+            and kwargs.get("y", None) is None
+            and not kwargs.get("subplots", False)
+        ):
+            raise ValueError("pie requires either y column or 'subplots=True'")
+        return self(kind="pie", **kwargs)
+
+    def scatter(
+        self,
+        x: Hashable,
+        y: Hashable,
+        s: Hashable | Sequence[Hashable] | None = None,
+        c: Hashable | Sequence[Hashable] | None = None,
+        **kwargs,
+    ) -> PlotAccessor:
+        """
+        Create a scatter plot with varying marker point size and color.
+
+        The coordinates of each point are defined by two dataframe columns and
+        filled circles are used to represent each point. This kind of plot is
+        useful to see complex correlations between two variables. Points could
+        be for instance natural 2D coordinates like longitude and latitude in
+        a map or, in general, any pair of metrics that can be plotted against
+        each other.
+
+        Parameters
+        ----------
+        x : int or str
+            The column name or column position to be used as horizontal
+            coordinates for each point.
+        y : int or str
+            The column name or column position to be used as vertical
+            coordinates for each point.
+        s : str, scalar or array-like, optional
+            The size of each point. Possible values are:
+
+            - A string with the name of the column to be used for marker's size.
+
+            - A single scalar so all points have the same size.
+
+            - A sequence of scalars, which will be used for each point's size
+              recursively. For instance, when passing [2,14] all points size
+              will be either 2 or 14, alternatively.
+
+        c : str, int or array-like, optional
+            The color of each point. Possible values are:
+
+            - A single color string referred to by name, RGB or RGBA code,
+              for instance 'red' or '#a98d19'.
+
+            - A sequence of color strings referred to by name, RGB or RGBA
+              code, which will be used for each point's color recursively. For
+              instance ['green','yellow'] all points will be filled in green or
+              yellow, alternatively.
+
+            - A column name or position whose values will be used to color the
+              marker points according to a colormap.
+
+        **kwargs
+            Keyword arguments to pass on to :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        :class:`matplotlib.axes.Axes` or numpy.ndarray of them
+
+        See Also
+        --------
+        matplotlib.pyplot.scatter : Scatter plot using multiple input data
+            formats.
+
+        Examples
+        --------
+        Let's see how to draw a scatter plot using coordinates from the values
+        in a DataFrame's columns.
+
+        .. plot::
+            :context: close-figs
+
+            >>> df = pd.DataFrame([[5.1, 3.5, 0], [4.9, 3.0, 0], [7.0, 3.2, 1],
+            ...                    [6.4, 3.2, 1], [5.9, 3.0, 2]],
+            ...                   columns=['length', 'width', 'species'])
+            >>> ax1 = df.plot.scatter(x='length',
+            ...                       y='width',
+            ...                       c='DarkBlue')
+
+        And now with the color determined by a column as well.
+
+        .. plot::
+            :context: close-figs
+
+            >>> ax2 = df.plot.scatter(x='length',
+            ...                       y='width',
+            ...                       c='species',
+            ...                       colormap='viridis')
+        """
+        return self(kind="scatter", x=x, y=y, s=s, c=c, **kwargs)
+
+    def hexbin(
+        self,
+        x: Hashable,
+        y: Hashable,
+        C: Hashable | None = None,
+        reduce_C_function: Callable | None = None,
+        gridsize: int | tuple[int, int] | None = None,
+        **kwargs,
+    ) -> PlotAccessor:
+        """
+        Generate a hexagonal binning plot.
+
+        Generate a hexagonal binning plot of `x` versus `y`. If `C` is `None`
+        (the default), this is a histogram of the number of occurrences
+        of the observations at ``(x[i], y[i])``.
+
+        If `C` is specified, specifies values at given coordinates
+        ``(x[i], y[i])``. These values are accumulated for each hexagonal
+        bin and then reduced according to `reduce_C_function`,
+        having as default the NumPy's mean function (:meth:`numpy.mean`).
+        (If `C` is specified, it must also be a 1-D sequence
+        of the same length as `x` and `y`, or a column label.)
+
+        Parameters
+        ----------
+        x : int or str
+            The column label or position for x points.
+        y : int or str
+            The column label or position for y points.
+        C : int or str, optional
+            The column label or position for the value of `(x, y)` point.
+        reduce_C_function : callable, default `np.mean`
+            Function of one argument that reduces all the values in a bin to
+            a single number (e.g. `np.mean`, `np.max`, `np.sum`, `np.std`).
+        gridsize : int or tuple of (int, int), default 100
+            The number of hexagons in the x-direction.
+            The corresponding number of hexagons in the y-direction is
+            chosen in a way that the hexagons are approximately regular.
+            Alternatively, gridsize can be a tuple with two elements
+            specifying the number of hexagons in the x-direction and the
+            y-direction.
+        **kwargs
+            Additional keyword arguments are documented in
+            :meth:`DataFrame.plot`.
+
+        Returns
+        -------
+        matplotlib.AxesSubplot
+            The matplotlib ``Axes`` on which the hexbin is plotted.
+
+        See Also
+        --------
+        DataFrame.plot : Make plots of a DataFrame.
+        matplotlib.pyplot.hexbin : Hexagonal binning plot using matplotlib,
+            the matplotlib function that is used under the hood.
+
+        Examples
+        --------
+        The following examples are generated with random data from
+        a normal distribution.
+
+        .. plot::
+            :context: close-figs
+
+            >>> n = 10000
+            >>> df = pd.DataFrame({'x': np.random.randn(n),
+            ...                    'y': np.random.randn(n)})
+            >>> ax = df.plot.hexbin(x='x', y='y', gridsize=20)
+
+        The next example uses `C` and `np.sum` as `reduce_C_function`.
+        Note that `'observations'` values ranges from 1 to 5 but the result
+        plot shows values up to more than 25. This is because of the
+        `reduce_C_function`.
+
+        .. plot::
+            :context: close-figs
+
+            >>> n = 500
+            >>> df = pd.DataFrame({
+            ...     'coord_x': np.random.uniform(-3, 3, size=n),
+            ...     'coord_y': np.random.uniform(30, 50, size=n),
+            ...     'observations': np.random.randint(1,5, size=n)
+            ...     })
+            >>> ax = df.plot.hexbin(x='coord_x',
+            ...                     y='coord_y',
+            ...                     C='observations',
+            ...                     reduce_C_function=np.sum,
+            ...                     gridsize=10,
+            ...                     cmap="viridis")
+        """
+        if reduce_C_function is not None:
+            kwargs["reduce_C_function"] = reduce_C_function
+        if gridsize is not None:
+            kwargs["gridsize"] = gridsize
+
+        return self(kind="hexbin", x=x, y=y, C=C, **kwargs)
+
+
+_backends: dict[str, types.ModuleType] = {}
+
+
+def _load_backend(backend: str) -> types.ModuleType:
+    """
+    Load a pandas plotting backend.
+
+    Parameters
+    ----------
+    backend : str
+        The identifier for the backend. Either an entrypoint item registered
+        with importlib.metadata, "matplotlib", or a module name.
+
+    Returns
+    -------
+    types.ModuleType
+        The imported backend.
+    """
+    from importlib.metadata import entry_points
+
+    if backend == "matplotlib":
+        # Because matplotlib is an optional dependency and first-party backend,
+        # we need to attempt an import here to raise an ImportError if needed.
+        try:
+            module = importlib.import_module("pandas.plotting._matplotlib")
+        except ImportError:
+            raise ImportError(
+                "matplotlib is required for plotting when the "
+                'default backend "matplotlib" is selected.'
+            ) from None
+        return module
+
+    found_backend = False
+
+    eps = entry_points()
+    key = "pandas_plotting_backends"
+    # entry_points lost dict API ~ PY 3.10
+    # https://github.com/python/importlib_metadata/issues/298
+    if hasattr(eps, "select"):
+        entry = eps.select(group=key)
+    else:
+        # Argument 2 to "get" of "dict" has incompatible type "Tuple[]";
+        # expected "EntryPoints"  [arg-type]
+        entry = eps.get(key, ())  # type: ignore[arg-type]
+    for entry_point in entry:
+        found_backend = entry_point.name == backend
+        if found_backend:
+            module = entry_point.load()
+            break
+
+    if not found_backend:
+        # Fall back to unregistered, module name approach.
+        try:
+            module = importlib.import_module(backend)
+            found_backend = True
+        except ImportError:
+            # We re-raise later on.
+            pass
+
+    if found_backend:
+        if hasattr(module, "plot"):
+            # Validate that the interface is implemented when the option is set,
+            # rather than at plot time.
+            return module
+
+    raise ValueError(
+        f"Could not find plotting backend '{backend}'. Ensure that you've "
+        f"installed the package providing the '{backend}' entrypoint, or that "
+        "the package has a top-level `.plot` method."
+    )
+
+
+def _get_plot_backend(backend: str | None = None):
+    """
+    Return the plotting backend to use (e.g. `pandas.plotting._matplotlib`).
+
+    The plotting system of pandas uses matplotlib by default, but the idea here
+    is that it can also work with other third-party backends. This function
+    returns the module which provides a top-level `.plot` method that will
+    actually do the plotting. The backend is specified from a string, which
+    either comes from the keyword argument `backend`, or, if not specified, from
+    the option `pandas.options.plotting.backend`. All the rest of the code in
+    this file uses the backend specified there for the plotting.
+
+    The backend is imported lazily, as matplotlib is a soft dependency, and
+    pandas can be used without it being installed.
+
+    Notes
+    -----
+    Modifies `_backends` with imported backend as a side effect.
+    """
+    backend_str: str = backend or get_option("plotting.backend")
+
+    if backend_str in _backends:
+        return _backends[backend_str]
+
+    module = _load_backend(backend_str)
+    _backends[backend_str] = module
+    return module
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/__init__.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..75c61da03795af0d4f60cd4d4a8b8e0dd45e3d5e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/__init__.py
@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pandas.plotting._matplotlib.boxplot import (
+    BoxPlot,
+    boxplot,
+    boxplot_frame,
+    boxplot_frame_groupby,
+)
+from pandas.plotting._matplotlib.converter import (
+    deregister,
+    register,
+)
+from pandas.plotting._matplotlib.core import (
+    AreaPlot,
+    BarhPlot,
+    BarPlot,
+    HexBinPlot,
+    LinePlot,
+    PiePlot,
+    ScatterPlot,
+)
+from pandas.plotting._matplotlib.hist import (
+    HistPlot,
+    KdePlot,
+    hist_frame,
+    hist_series,
+)
+from pandas.plotting._matplotlib.misc import (
+    andrews_curves,
+    autocorrelation_plot,
+    bootstrap_plot,
+    lag_plot,
+    parallel_coordinates,
+    radviz,
+    scatter_matrix,
+)
+from pandas.plotting._matplotlib.tools import table
+
+if TYPE_CHECKING:
+    from pandas.plotting._matplotlib.core import MPLPlot
+
+PLOT_CLASSES: dict[str, type[MPLPlot]] = {
+    "line": LinePlot,
+    "bar": BarPlot,
+    "barh": BarhPlot,
+    "box": BoxPlot,
+    "hist": HistPlot,
+    "kde": KdePlot,
+    "area": AreaPlot,
+    "pie": PiePlot,
+    "scatter": ScatterPlot,
+    "hexbin": HexBinPlot,
+}
+
+
+def plot(data, kind, **kwargs):
+    # Importing pyplot at the top of the file (before the converters are
+    # registered) causes problems in matplotlib 2 (converters seem to not
+    # work)
+    import matplotlib.pyplot as plt
+
+    if kwargs.pop("reuse_plot", False):
+        ax = kwargs.get("ax")
+        if ax is None and len(plt.get_fignums()) > 0:
+            with plt.rc_context():
+                ax = plt.gca()
+            kwargs["ax"] = getattr(ax, "left_ax", ax)
+    plot_obj = PLOT_CLASSES[kind](data, **kwargs)
+    plot_obj.generate()
+    plot_obj.draw()
+    return plot_obj.result
+
+
+__all__ = [
+    "plot",
+    "hist_series",
+    "hist_frame",
+    "boxplot",
+    "boxplot_frame",
+    "boxplot_frame_groupby",
+    "table",
+    "andrews_curves",
+    "autocorrelation_plot",
+    "bootstrap_plot",
+    "lag_plot",
+    "parallel_coordinates",
+    "radviz",
+    "scatter_matrix",
+    "register",
+    "deregister",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/boxplot.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/boxplot.py
new file mode 100644
index 0000000000000000000000000000000000000000..80f0349b205e6072abeb63c4727a1efa060b2d36
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/boxplot.py
@@ -0,0 +1,575 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Literal,
+    NamedTuple,
+)
+import warnings
+
+import matplotlib as mpl
+from matplotlib.artist import setp
+import numpy as np
+
+from pandas._libs import lib
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_dict_like
+from pandas.core.dtypes.generic import ABCSeries
+from pandas.core.dtypes.missing import remove_na_arraylike
+
+import pandas as pd
+import pandas.core.common as com
+from pandas.util.version import Version
+
+from pandas.io.formats.printing import pprint_thing
+from pandas.plotting._matplotlib.core import (
+    LinePlot,
+    MPLPlot,
+)
+from pandas.plotting._matplotlib.groupby import create_iter_data_given_by
+from pandas.plotting._matplotlib.style import get_standard_colors
+from pandas.plotting._matplotlib.tools import (
+    create_subplots,
+    flatten_axes,
+    maybe_adjust_figure,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Collection
+
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+    from matplotlib.lines import Line2D
+
+    from pandas._typing import MatplotlibColor
+
+
+def _set_ticklabels(ax: Axes, labels: list[str], is_vertical: bool, **kwargs) -> None:
+    """Set the tick labels of a given axis.
+
+    Due to https://github.com/matplotlib/matplotlib/pull/17266, we need to handle the
+    case of repeated ticks (due to `FixedLocator`) and thus we duplicate the number of
+    labels.
+    """
+    ticks = ax.get_xticks() if is_vertical else ax.get_yticks()
+    if len(ticks) != len(labels):
+        i, remainder = divmod(len(ticks), len(labels))
+        if Version(mpl.__version__) < Version("3.10"):
+            assert remainder == 0, remainder
+        labels *= i
+    if is_vertical:
+        ax.set_xticklabels(labels, **kwargs)
+    else:
+        ax.set_yticklabels(labels, **kwargs)
+
+
+class BoxPlot(LinePlot):
+    @property
+    def _kind(self) -> Literal["box"]:
+        return "box"
+
+    _layout_type = "horizontal"
+
+    _valid_return_types = (None, "axes", "dict", "both")
+
+    class BP(NamedTuple):
+        # namedtuple to hold results
+        ax: Axes
+        lines: dict[str, list[Line2D]]
+
+    def __init__(self, data, return_type: str = "axes", **kwargs) -> None:
+        if return_type not in self._valid_return_types:
+            raise ValueError("return_type must be {None, 'axes', 'dict', 'both'}")
+
+        self.return_type = return_type
+        # Do not call LinePlot.__init__ which may fill nan
+        MPLPlot.__init__(self, data, **kwargs)  # pylint: disable=non-parent-init-called
+
+        if self.subplots:
+            # Disable label ax sharing. Otherwise, all subplots shows last
+            # column label
+            if self.orientation == "vertical":
+                self.sharex = False
+            else:
+                self.sharey = False
+
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls, ax: Axes, y: np.ndarray, column_num=None, return_type: str = "axes", **kwds
+    ):
+        ys: np.ndarray | list[np.ndarray]
+        if y.ndim == 2:
+            ys = [remove_na_arraylike(v) for v in y]
+            # Boxplot fails with empty arrays, so need to add a NaN
+            #   if any cols are empty
+            # GH 8181
+            ys = [v if v.size > 0 else np.array([np.nan]) for v in ys]
+        else:
+            ys = remove_na_arraylike(y)
+        bp = ax.boxplot(ys, **kwds)
+
+        if return_type == "dict":
+            return bp, bp
+        elif return_type == "both":
+            return cls.BP(ax=ax, lines=bp), bp
+        else:
+            return ax, bp
+
+    def _validate_color_args(self, color, colormap):
+        if color is lib.no_default:
+            return None
+
+        if colormap is not None:
+            warnings.warn(
+                "'color' and 'colormap' cannot be used "
+                "simultaneously. Using 'color'",
+                stacklevel=find_stack_level(),
+            )
+
+        if isinstance(color, dict):
+            valid_keys = ["boxes", "whiskers", "medians", "caps"]
+            for key in color:
+                if key not in valid_keys:
+                    raise ValueError(
+                        f"color dict contains invalid key '{key}'. "
+                        f"The key must be either {valid_keys}"
+                    )
+        return color
+
+    @cache_readonly
+    def _color_attrs(self):
+        # get standard colors for default
+        # use 2 colors by default, for box/whisker and median
+        # flier colors isn't needed here
+        # because it can be specified by ``sym`` kw
+        return get_standard_colors(num_colors=3, colormap=self.colormap, color=None)
+
+    @cache_readonly
+    def _boxes_c(self):
+        return self._color_attrs[0]
+
+    @cache_readonly
+    def _whiskers_c(self):
+        return self._color_attrs[0]
+
+    @cache_readonly
+    def _medians_c(self):
+        return self._color_attrs[2]
+
+    @cache_readonly
+    def _caps_c(self):
+        return self._color_attrs[0]
+
+    def _get_colors(
+        self,
+        num_colors=None,
+        color_kwds: dict[str, MatplotlibColor]
+        | MatplotlibColor
+        | Collection[MatplotlibColor]
+        | None = "color",
+    ) -> None:
+        pass
+
+    def maybe_color_bp(self, bp) -> None:
+        if isinstance(self.color, dict):
+            boxes = self.color.get("boxes", self._boxes_c)
+            whiskers = self.color.get("whiskers", self._whiskers_c)
+            medians = self.color.get("medians", self._medians_c)
+            caps = self.color.get("caps", self._caps_c)
+        else:
+            # Other types are forwarded to matplotlib
+            # If None, use default colors
+            boxes = self.color or self._boxes_c
+            whiskers = self.color or self._whiskers_c
+            medians = self.color or self._medians_c
+            caps = self.color or self._caps_c
+
+        color_tup = (boxes, whiskers, medians, caps)
+        maybe_color_bp(bp, color_tup=color_tup, **self.kwds)
+
+    def _make_plot(self, fig: Figure) -> None:
+        if self.subplots:
+            self._return_obj = pd.Series(dtype=object)
+
+            # Re-create iterated data if `by` is assigned by users
+            data = (
+                create_iter_data_given_by(self.data, self._kind)
+                if self.by is not None
+                else self.data
+            )
+
+            # error: Argument "data" to "_iter_data" of "MPLPlot" has
+            # incompatible type "object"; expected "DataFrame |
+            # dict[Hashable, Series | DataFrame]"
+            for i, (label, y) in enumerate(self._iter_data(data=data)):  # type: ignore[arg-type]
+                ax = self._get_ax(i)
+                kwds = self.kwds.copy()
+
+                # When by is applied, show title for subplots to know which group it is
+                # just like df.boxplot, and need to apply T on y to provide right input
+                if self.by is not None:
+                    y = y.T
+                    ax.set_title(pprint_thing(label))
+
+                    # When `by` is assigned, the ticklabels will become unique grouped
+                    # values, instead of label which is used as subtitle in this case.
+                    # error: "Index" has no attribute "levels"; maybe "nlevels"?
+                    levels = self.data.columns.levels  # type: ignore[attr-defined]
+                    ticklabels = [pprint_thing(col) for col in levels[0]]
+                else:
+                    ticklabels = [pprint_thing(label)]
+
+                ret, bp = self._plot(
+                    ax, y, column_num=i, return_type=self.return_type, **kwds
+                )
+                self.maybe_color_bp(bp)
+                self._return_obj[label] = ret
+                _set_ticklabels(
+                    ax=ax, labels=ticklabels, is_vertical=self.orientation == "vertical"
+                )
+        else:
+            y = self.data.values.T
+            ax = self._get_ax(0)
+            kwds = self.kwds.copy()
+
+            ret, bp = self._plot(
+                ax, y, column_num=0, return_type=self.return_type, **kwds
+            )
+            self.maybe_color_bp(bp)
+            self._return_obj = ret
+
+            labels = [pprint_thing(left) for left in self.data.columns]
+            if not self.use_index:
+                labels = [pprint_thing(key) for key in range(len(labels))]
+            _set_ticklabels(
+                ax=ax, labels=labels, is_vertical=self.orientation == "vertical"
+            )
+
+    def _make_legend(self) -> None:
+        pass
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        # GH 45465: make sure that the boxplot doesn't ignore xlabel/ylabel
+        if self.xlabel:
+            ax.set_xlabel(pprint_thing(self.xlabel))
+        if self.ylabel:
+            ax.set_ylabel(pprint_thing(self.ylabel))
+
+    @property
+    def orientation(self) -> Literal["horizontal", "vertical"]:
+        if self.kwds.get("vert", True):
+            return "vertical"
+        else:
+            return "horizontal"
+
+    @property
+    def result(self):
+        if self.return_type is None:
+            return super().result
+        else:
+            return self._return_obj
+
+
+def maybe_color_bp(bp, color_tup, **kwds) -> None:
+    # GH#30346, when users specifying those arguments explicitly, our defaults
+    # for these four kwargs should be overridden; if not, use Pandas settings
+    if not kwds.get("boxprops"):
+        setp(bp["boxes"], color=color_tup[0], alpha=1)
+    if not kwds.get("whiskerprops"):
+        setp(bp["whiskers"], color=color_tup[1], alpha=1)
+    if not kwds.get("medianprops"):
+        setp(bp["medians"], color=color_tup[2], alpha=1)
+    if not kwds.get("capprops"):
+        setp(bp["caps"], color=color_tup[3], alpha=1)
+
+
+def _grouped_plot_by_column(
+    plotf,
+    data,
+    columns=None,
+    by=None,
+    numeric_only: bool = True,
+    grid: bool = False,
+    figsize: tuple[float, float] | None = None,
+    ax=None,
+    layout=None,
+    return_type=None,
+    **kwargs,
+):
+    grouped = data.groupby(by, observed=False)
+    if columns is None:
+        if not isinstance(by, (list, tuple)):
+            by = [by]
+        columns = data._get_numeric_data().columns.difference(by)
+    naxes = len(columns)
+    fig, axes = create_subplots(
+        naxes=naxes,
+        sharex=kwargs.pop("sharex", True),
+        sharey=kwargs.pop("sharey", True),
+        figsize=figsize,
+        ax=ax,
+        layout=layout,
+    )
+
+    _axes = flatten_axes(axes)
+
+    # GH 45465: move the "by" label based on "vert"
+    xlabel, ylabel = kwargs.pop("xlabel", None), kwargs.pop("ylabel", None)
+    if kwargs.get("vert", True):
+        xlabel = xlabel or by
+    else:
+        ylabel = ylabel or by
+
+    ax_values = []
+
+    for i, col in enumerate(columns):
+        ax = _axes[i]
+        gp_col = grouped[col]
+        keys, values = zip(*gp_col)
+        re_plotf = plotf(keys, values, ax, xlabel=xlabel, ylabel=ylabel, **kwargs)
+        ax.set_title(col)
+        ax_values.append(re_plotf)
+        ax.grid(grid)
+
+    result = pd.Series(ax_values, index=columns, copy=False)
+
+    # Return axes in multiplot case, maybe revisit later # 985
+    if return_type is None:
+        result = axes
+
+    byline = by[0] if len(by) == 1 else by
+    fig.suptitle(f"Boxplot grouped by {byline}")
+    maybe_adjust_figure(fig, bottom=0.15, top=0.9, left=0.1, right=0.9, wspace=0.2)
+
+    return result
+
+
+def boxplot(
+    data,
+    column=None,
+    by=None,
+    ax=None,
+    fontsize: int | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    return_type=None,
+    **kwds,
+):
+    import matplotlib.pyplot as plt
+
+    # validate return_type:
+    if return_type not in BoxPlot._valid_return_types:
+        raise ValueError("return_type must be {'axes', 'dict', 'both'}")
+
+    if isinstance(data, ABCSeries):
+        data = data.to_frame("x")
+        column = "x"
+
+    def _get_colors():
+        #  num_colors=3 is required as method maybe_color_bp takes the colors
+        #  in positions 0 and 2.
+        #  if colors not provided, use same defaults as DataFrame.plot.box
+        result = get_standard_colors(num_colors=3)
+        result = np.take(result, [0, 0, 2])
+        result = np.append(result, "k")
+
+        colors = kwds.pop("color", None)
+        if colors:
+            if is_dict_like(colors):
+                # replace colors in result array with user-specified colors
+                # taken from the colors dict parameter
+                # "boxes" value placed in position 0, "whiskers" in 1, etc.
+                valid_keys = ["boxes", "whiskers", "medians", "caps"]
+                key_to_index = dict(zip(valid_keys, range(4)))
+                for key, value in colors.items():
+                    if key in valid_keys:
+                        result[key_to_index[key]] = value
+                    else:
+                        raise ValueError(
+                            f"color dict contains invalid key '{key}'. "
+                            f"The key must be either {valid_keys}"
+                        )
+            else:
+                result.fill(colors)
+
+        return result
+
+    def plot_group(keys, values, ax: Axes, **kwds):
+        # GH 45465: xlabel/ylabel need to be popped out before plotting happens
+        xlabel, ylabel = kwds.pop("xlabel", None), kwds.pop("ylabel", None)
+        if xlabel:
+            ax.set_xlabel(pprint_thing(xlabel))
+        if ylabel:
+            ax.set_ylabel(pprint_thing(ylabel))
+
+        keys = [pprint_thing(x) for x in keys]
+        values = [np.asarray(remove_na_arraylike(v), dtype=object) for v in values]
+        bp = ax.boxplot(values, **kwds)
+        if fontsize is not None:
+            ax.tick_params(axis="both", labelsize=fontsize)
+
+        # GH 45465: x/y are flipped when "vert" changes
+        _set_ticklabels(
+            ax=ax, labels=keys, is_vertical=kwds.get("vert", True), rotation=rot
+        )
+        maybe_color_bp(bp, color_tup=colors, **kwds)
+
+        # Return axes in multiplot case, maybe revisit later # 985
+        if return_type == "dict":
+            return bp
+        elif return_type == "both":
+            return BoxPlot.BP(ax=ax, lines=bp)
+        else:
+            return ax
+
+    colors = _get_colors()
+    if column is None:
+        columns = None
+    elif isinstance(column, (list, tuple)):
+        columns = column
+    else:
+        columns = [column]
+
+    if by is not None:
+        # Prefer array return type for 2-D plots to match the subplot layout
+        # https://github.com/pandas-dev/pandas/pull/12216#issuecomment-241175580
+        result = _grouped_plot_by_column(
+            plot_group,
+            data,
+            columns=columns,
+            by=by,
+            grid=grid,
+            figsize=figsize,
+            ax=ax,
+            layout=layout,
+            return_type=return_type,
+            **kwds,
+        )
+    else:
+        if return_type is None:
+            return_type = "axes"
+        if layout is not None:
+            raise ValueError("The 'layout' keyword is not supported when 'by' is None")
+
+        if ax is None:
+            rc = {"figure.figsize": figsize} if figsize is not None else {}
+            with plt.rc_context(rc):
+                ax = plt.gca()
+        data = data._get_numeric_data()
+        naxes = len(data.columns)
+        if naxes == 0:
+            raise ValueError(
+                "boxplot method requires numerical columns, nothing to plot."
+            )
+        if columns is None:
+            columns = data.columns
+        else:
+            data = data[columns]
+
+        result = plot_group(columns, data.values.T, ax, **kwds)
+        ax.grid(grid)
+
+    return result
+
+
+def boxplot_frame(
+    self,
+    column=None,
+    by=None,
+    ax=None,
+    fontsize: int | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    return_type=None,
+    **kwds,
+):
+    import matplotlib.pyplot as plt
+
+    ax = boxplot(
+        self,
+        column=column,
+        by=by,
+        ax=ax,
+        fontsize=fontsize,
+        grid=grid,
+        rot=rot,
+        figsize=figsize,
+        layout=layout,
+        return_type=return_type,
+        **kwds,
+    )
+    plt.draw_if_interactive()
+    return ax
+
+
+def boxplot_frame_groupby(
+    grouped,
+    subplots: bool = True,
+    column=None,
+    fontsize: int | None = None,
+    rot: int = 0,
+    grid: bool = True,
+    ax=None,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    sharex: bool = False,
+    sharey: bool = True,
+    **kwds,
+):
+    if subplots is True:
+        naxes = len(grouped)
+        fig, axes = create_subplots(
+            naxes=naxes,
+            squeeze=False,
+            ax=ax,
+            sharex=sharex,
+            sharey=sharey,
+            figsize=figsize,
+            layout=layout,
+        )
+        axes = flatten_axes(axes)
+
+        ret = pd.Series(dtype=object)
+
+        for (key, group), ax in zip(grouped, axes):
+            d = group.boxplot(
+                ax=ax, column=column, fontsize=fontsize, rot=rot, grid=grid, **kwds
+            )
+            ax.set_title(pprint_thing(key))
+            ret.loc[key] = d
+        maybe_adjust_figure(fig, bottom=0.15, top=0.9, left=0.1, right=0.9, wspace=0.2)
+    else:
+        keys, frames = zip(*grouped)
+        if grouped.axis == 0:
+            df = pd.concat(frames, keys=keys, axis=1)
+        elif len(frames) > 1:
+            df = frames[0].join(frames[1::])
+        else:
+            df = frames[0]
+
+        # GH 16748, DataFrameGroupby fails when subplots=False and `column` argument
+        # is assigned, and in this case, since `df` here becomes MI after groupby,
+        # so we need to couple the keys (grouped values) and column (original df
+        # column) together to search for subset to plot
+        if column is not None:
+            column = com.convert_to_list_like(column)
+            multi_key = pd.MultiIndex.from_product([keys, column])
+            column = list(multi_key.values)
+        ret = df.boxplot(
+            column=column,
+            fontsize=fontsize,
+            rot=rot,
+            grid=grid,
+            ax=ax,
+            figsize=figsize,
+            layout=layout,
+            **kwds,
+        )
+    return ret
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/converter.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/converter.py
new file mode 100644
index 0000000000000000000000000000000000000000..9acb93ce69a9ca25962139891e6bb1e5e163add8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/converter.py
@@ -0,0 +1,1139 @@
+from __future__ import annotations
+
+import contextlib
+import datetime as pydt
+from datetime import (
+    datetime,
+    timedelta,
+    tzinfo,
+)
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+import warnings
+
+import matplotlib.dates as mdates
+from matplotlib.ticker import (
+    AutoLocator,
+    Formatter,
+    Locator,
+)
+from matplotlib.transforms import nonsingular
+import matplotlib.units as munits
+import numpy as np
+
+from pandas._libs import lib
+from pandas._libs.tslibs import (
+    Timestamp,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import (
+    FreqGroup,
+    periods_per_day,
+)
+from pandas._typing import (
+    F,
+    npt,
+)
+
+from pandas.core.dtypes.common import (
+    is_float,
+    is_float_dtype,
+    is_integer,
+    is_integer_dtype,
+    is_nested_list_like,
+)
+
+from pandas import (
+    Index,
+    Series,
+    get_option,
+)
+import pandas.core.common as com
+from pandas.core.indexes.datetimes import date_range
+from pandas.core.indexes.period import (
+    Period,
+    PeriodIndex,
+    period_range,
+)
+import pandas.core.tools.datetimes as tools
+
+if TYPE_CHECKING:
+    from collections.abc import Generator
+
+    from matplotlib.axis import Axis
+
+    from pandas._libs.tslibs.offsets import BaseOffset
+
+
+_mpl_units = {}  # Cache for units overwritten by us
+
+
+def get_pairs():
+    pairs = [
+        (Timestamp, DatetimeConverter),
+        (Period, PeriodConverter),
+        (pydt.datetime, DatetimeConverter),
+        (pydt.date, DatetimeConverter),
+        (pydt.time, TimeConverter),
+        (np.datetime64, DatetimeConverter),
+    ]
+    return pairs
+
+
+def register_pandas_matplotlib_converters(func: F) -> F:
+    """
+    Decorator applying pandas_converters.
+    """
+
+    @functools.wraps(func)
+    def wrapper(*args, **kwargs):
+        with pandas_converters():
+            return func(*args, **kwargs)
+
+    return cast(F, wrapper)
+
+
+@contextlib.contextmanager
+def pandas_converters() -> Generator[None, None, None]:
+    """
+    Context manager registering pandas' converters for a plot.
+
+    See Also
+    --------
+    register_pandas_matplotlib_converters : Decorator that applies this.
+    """
+    value = get_option("plotting.matplotlib.register_converters")
+
+    if value:
+        # register for True or "auto"
+        register()
+    try:
+        yield
+    finally:
+        if value == "auto":
+            # only deregister for "auto"
+            deregister()
+
+
+def register() -> None:
+    pairs = get_pairs()
+    for type_, cls in pairs:
+        # Cache previous converter if present
+        if type_ in munits.registry and not isinstance(munits.registry[type_], cls):
+            previous = munits.registry[type_]
+            _mpl_units[type_] = previous
+        # Replace with pandas converter
+        munits.registry[type_] = cls()
+
+
+def deregister() -> None:
+    # Renamed in pandas.plotting.__init__
+    for type_, cls in get_pairs():
+        # We use type to catch our classes directly, no inheritance
+        if type(munits.registry.get(type_)) is cls:
+            munits.registry.pop(type_)
+
+    # restore the old keys
+    for unit, formatter in _mpl_units.items():
+        if type(formatter) not in {DatetimeConverter, PeriodConverter, TimeConverter}:
+            # make it idempotent by excluding ours.
+            munits.registry[unit] = formatter
+
+
+def _to_ordinalf(tm: pydt.time) -> float:
+    tot_sec = tm.hour * 3600 + tm.minute * 60 + tm.second + tm.microsecond / 10**6
+    return tot_sec
+
+
+def time2num(d):
+    if isinstance(d, str):
+        parsed = Timestamp(d)
+        return _to_ordinalf(parsed.time())
+    if isinstance(d, pydt.time):
+        return _to_ordinalf(d)
+    return d
+
+
+class TimeConverter(munits.ConversionInterface):
+    @staticmethod
+    def convert(value, unit, axis):
+        valid_types = (str, pydt.time)
+        if isinstance(value, valid_types) or is_integer(value) or is_float(value):
+            return time2num(value)
+        if isinstance(value, Index):
+            return value.map(time2num)
+        if isinstance(value, (list, tuple, np.ndarray, Index)):
+            return [time2num(x) for x in value]
+        return value
+
+    @staticmethod
+    def axisinfo(unit, axis) -> munits.AxisInfo | None:
+        if unit != "time":
+            return None
+
+        majloc = AutoLocator()
+        majfmt = TimeFormatter(majloc)
+        return munits.AxisInfo(majloc=majloc, majfmt=majfmt, label="time")
+
+    @staticmethod
+    def default_units(x, axis) -> str:
+        return "time"
+
+
+# time formatter
+class TimeFormatter(Formatter):
+    def __init__(self, locs) -> None:
+        self.locs = locs
+
+    def __call__(self, x, pos: int | None = 0) -> str:
+        """
+        Return the time of day as a formatted string.
+
+        Parameters
+        ----------
+        x : float
+            The time of day specified as seconds since 00:00 (midnight),
+            with up to microsecond precision.
+        pos
+            Unused
+
+        Returns
+        -------
+        str
+            A string in HH:MM:SS.mmmuuu format. Microseconds,
+            milliseconds and seconds are only displayed if non-zero.
+        """
+        fmt = "%H:%M:%S.%f"
+        s = int(x)
+        msus = round((x - s) * 10**6)
+        ms = msus // 1000
+        us = msus % 1000
+        m, s = divmod(s, 60)
+        h, m = divmod(m, 60)
+        _, h = divmod(h, 24)
+        if us != 0:
+            return pydt.time(h, m, s, msus).strftime(fmt)
+        elif ms != 0:
+            return pydt.time(h, m, s, msus).strftime(fmt)[:-3]
+        elif s != 0:
+            return pydt.time(h, m, s).strftime("%H:%M:%S")
+
+        return pydt.time(h, m).strftime("%H:%M")
+
+
+# Period Conversion
+
+
+class PeriodConverter(mdates.DateConverter):
+    @staticmethod
+    def convert(values, units, axis):
+        if is_nested_list_like(values):
+            values = [PeriodConverter._convert_1d(v, units, axis) for v in values]
+        else:
+            values = PeriodConverter._convert_1d(values, units, axis)
+        return values
+
+    @staticmethod
+    def _convert_1d(values, units, axis):
+        if not hasattr(axis, "freq"):
+            raise TypeError("Axis must have `freq` set to convert to Periods")
+        valid_types = (str, datetime, Period, pydt.date, pydt.time, np.datetime64)
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore", "Period with BDay freq is deprecated", category=FutureWarning
+            )
+            warnings.filterwarnings(
+                "ignore", r"PeriodDtype\[B\] is deprecated", category=FutureWarning
+            )
+            if (
+                isinstance(values, valid_types)
+                or is_integer(values)
+                or is_float(values)
+            ):
+                return get_datevalue(values, axis.freq)
+            elif isinstance(values, PeriodIndex):
+                return values.asfreq(axis.freq).asi8
+            elif isinstance(values, Index):
+                return values.map(lambda x: get_datevalue(x, axis.freq))
+            elif lib.infer_dtype(values, skipna=False) == "period":
+                # https://github.com/pandas-dev/pandas/issues/24304
+                # convert ndarray[period] -> PeriodIndex
+                return PeriodIndex(values, freq=axis.freq).asi8
+            elif isinstance(values, (list, tuple, np.ndarray, Index)):
+                return [get_datevalue(x, axis.freq) for x in values]
+        return values
+
+
+def get_datevalue(date, freq):
+    if isinstance(date, Period):
+        return date.asfreq(freq).ordinal
+    elif isinstance(date, (str, datetime, pydt.date, pydt.time, np.datetime64)):
+        return Period(date, freq).ordinal
+    elif (
+        is_integer(date)
+        or is_float(date)
+        or (isinstance(date, (np.ndarray, Index)) and (date.size == 1))
+    ):
+        return date
+    elif date is None:
+        return None
+    raise ValueError(f"Unrecognizable date '{date}'")
+
+
+# Datetime Conversion
+class DatetimeConverter(mdates.DateConverter):
+    @staticmethod
+    def convert(values, unit, axis):
+        # values might be a 1-d array, or a list-like of arrays.
+        if is_nested_list_like(values):
+            values = [DatetimeConverter._convert_1d(v, unit, axis) for v in values]
+        else:
+            values = DatetimeConverter._convert_1d(values, unit, axis)
+        return values
+
+    @staticmethod
+    def _convert_1d(values, unit, axis):
+        def try_parse(values):
+            try:
+                return mdates.date2num(tools.to_datetime(values))
+            except Exception:
+                return values
+
+        if isinstance(values, (datetime, pydt.date, np.datetime64, pydt.time)):
+            return mdates.date2num(values)
+        elif is_integer(values) or is_float(values):
+            return values
+        elif isinstance(values, str):
+            return try_parse(values)
+        elif isinstance(values, (list, tuple, np.ndarray, Index, Series)):
+            if isinstance(values, Series):
+                # https://github.com/matplotlib/matplotlib/issues/11391
+                # Series was skipped. Convert to DatetimeIndex to get asi8
+                values = Index(values)
+            if isinstance(values, Index):
+                values = values.values
+            if not isinstance(values, np.ndarray):
+                values = com.asarray_tuplesafe(values)
+
+            if is_integer_dtype(values) or is_float_dtype(values):
+                return values
+
+            try:
+                values = tools.to_datetime(values)
+            except Exception:
+                pass
+
+            values = mdates.date2num(values)
+
+        return values
+
+    @staticmethod
+    def axisinfo(unit: tzinfo | None, axis) -> munits.AxisInfo:
+        """
+        Return the :class:`~matplotlib.units.AxisInfo` for *unit*.
+
+        *unit* is a tzinfo instance or None.
+        The *axis* argument is required but not used.
+        """
+        tz = unit
+
+        majloc = PandasAutoDateLocator(tz=tz)
+        majfmt = PandasAutoDateFormatter(majloc, tz=tz)
+        datemin = pydt.date(2000, 1, 1)
+        datemax = pydt.date(2010, 1, 1)
+
+        return munits.AxisInfo(
+            majloc=majloc, majfmt=majfmt, label="", default_limits=(datemin, datemax)
+        )
+
+
+class PandasAutoDateFormatter(mdates.AutoDateFormatter):
+    def __init__(self, locator, tz=None, defaultfmt: str = "%Y-%m-%d") -> None:
+        mdates.AutoDateFormatter.__init__(self, locator, tz, defaultfmt)
+
+
+class PandasAutoDateLocator(mdates.AutoDateLocator):
+    def get_locator(self, dmin, dmax):
+        """Pick the best locator based on a distance."""
+        tot_sec = (dmax - dmin).total_seconds()
+
+        if abs(tot_sec) < self.minticks:
+            self._freq = -1
+            locator = MilliSecondLocator(self.tz)
+            locator.set_axis(self.axis)
+
+            # error: Item "None" of "Axis | _DummyAxis | _AxisWrapper | None"
+            # has no attribute "get_data_interval"
+            locator.axis.set_view_interval(  # type: ignore[union-attr]
+                *self.axis.get_view_interval()  # type: ignore[union-attr]
+            )
+            locator.axis.set_data_interval(  # type: ignore[union-attr]
+                *self.axis.get_data_interval()  # type: ignore[union-attr]
+            )
+            return locator
+
+        return mdates.AutoDateLocator.get_locator(self, dmin, dmax)
+
+    def _get_unit(self):
+        return MilliSecondLocator.get_unit_generic(self._freq)
+
+
+class MilliSecondLocator(mdates.DateLocator):
+    UNIT = 1.0 / (24 * 3600 * 1000)
+
+    def __init__(self, tz) -> None:
+        mdates.DateLocator.__init__(self, tz)
+        self._interval = 1.0
+
+    def _get_unit(self):
+        return self.get_unit_generic(-1)
+
+    @staticmethod
+    def get_unit_generic(freq):
+        unit = mdates.RRuleLocator.get_unit_generic(freq)
+        if unit < 0:
+            return MilliSecondLocator.UNIT
+        return unit
+
+    def __call__(self):
+        # if no data have been set, this will tank with a ValueError
+        try:
+            dmin, dmax = self.viewlim_to_dt()
+        except ValueError:
+            return []
+
+        # We need to cap at the endpoints of valid datetime
+        nmax, nmin = mdates.date2num((dmax, dmin))
+
+        num = (nmax - nmin) * 86400 * 1000
+        max_millis_ticks = 6
+        for interval in [1, 10, 50, 100, 200, 500]:
+            if num <= interval * (max_millis_ticks - 1):
+                self._interval = interval
+                break
+            # We went through the whole loop without breaking, default to 1
+            self._interval = 1000.0
+
+        estimate = (nmax - nmin) / (self._get_unit() * self._get_interval())
+
+        if estimate > self.MAXTICKS * 2:
+            raise RuntimeError(
+                "MillisecondLocator estimated to generate "
+                f"{estimate:d} ticks from {dmin} to {dmax}: exceeds Locator.MAXTICKS"
+                f"* 2 ({self.MAXTICKS * 2:d}) "
+            )
+
+        interval = self._get_interval()
+        freq = f"{interval}ms"
+        tz = self.tz.tzname(None)
+        st = dmin.replace(tzinfo=None)
+        ed = dmin.replace(tzinfo=None)
+        all_dates = date_range(start=st, end=ed, freq=freq, tz=tz).astype(object)
+
+        try:
+            if len(all_dates) > 0:
+                locs = self.raise_if_exceeds(mdates.date2num(all_dates))
+                return locs
+        except Exception:  # pragma: no cover
+            pass
+
+        lims = mdates.date2num([dmin, dmax])
+        return lims
+
+    def _get_interval(self):
+        return self._interval
+
+    def autoscale(self):
+        """
+        Set the view limits to include the data range.
+        """
+        # We need to cap at the endpoints of valid datetime
+        dmin, dmax = self.datalim_to_dt()
+
+        vmin = mdates.date2num(dmin)
+        vmax = mdates.date2num(dmax)
+
+        return self.nonsingular(vmin, vmax)
+
+
+def _from_ordinal(x, tz: tzinfo | None = None) -> datetime:
+    ix = int(x)
+    dt = datetime.fromordinal(ix)
+    remainder = float(x) - ix
+    hour, remainder = divmod(24 * remainder, 1)
+    minute, remainder = divmod(60 * remainder, 1)
+    second, remainder = divmod(60 * remainder, 1)
+    microsecond = int(1_000_000 * remainder)
+    if microsecond < 10:
+        microsecond = 0  # compensate for rounding errors
+    dt = datetime(
+        dt.year, dt.month, dt.day, int(hour), int(minute), int(second), microsecond
+    )
+    if tz is not None:
+        dt = dt.astimezone(tz)
+
+    if microsecond > 999990:  # compensate for rounding errors
+        dt += timedelta(microseconds=1_000_000 - microsecond)
+
+    return dt
+
+
+# Fixed frequency dynamic tick locators and formatters
+
+# -------------------------------------------------------------------------
+# --- Locators ---
+# -------------------------------------------------------------------------
+
+
+def _get_default_annual_spacing(nyears) -> tuple[int, int]:
+    """
+    Returns a default spacing between consecutive ticks for annual data.
+    """
+    if nyears < 11:
+        (min_spacing, maj_spacing) = (1, 1)
+    elif nyears < 20:
+        (min_spacing, maj_spacing) = (1, 2)
+    elif nyears < 50:
+        (min_spacing, maj_spacing) = (1, 5)
+    elif nyears < 100:
+        (min_spacing, maj_spacing) = (5, 10)
+    elif nyears < 200:
+        (min_spacing, maj_spacing) = (5, 25)
+    elif nyears < 600:
+        (min_spacing, maj_spacing) = (10, 50)
+    else:
+        factor = nyears // 1000 + 1
+        (min_spacing, maj_spacing) = (factor * 20, factor * 100)
+    return (min_spacing, maj_spacing)
+
+
+def _period_break(dates: PeriodIndex, period: str) -> npt.NDArray[np.intp]:
+    """
+    Returns the indices where the given period changes.
+
+    Parameters
+    ----------
+    dates : PeriodIndex
+        Array of intervals to monitor.
+    period : str
+        Name of the period to monitor.
+    """
+    mask = _period_break_mask(dates, period)
+    return np.nonzero(mask)[0]
+
+
+def _period_break_mask(dates: PeriodIndex, period: str) -> npt.NDArray[np.bool_]:
+    current = getattr(dates, period)
+    previous = getattr(dates - 1 * dates.freq, period)
+    return current != previous
+
+
+def has_level_label(label_flags: npt.NDArray[np.intp], vmin: float) -> bool:
+    """
+    Returns true if the ``label_flags`` indicate there is at least one label
+    for this level.
+
+    if the minimum view limit is not an exact integer, then the first tick
+    label won't be shown, so we must adjust for that.
+    """
+    if label_flags.size == 0 or (
+        label_flags.size == 1 and label_flags[0] == 0 and vmin % 1 > 0.0
+    ):
+        return False
+    else:
+        return True
+
+
+def _get_periods_per_ymd(freq: BaseOffset) -> tuple[int, int, int]:
+    # error: "BaseOffset" has no attribute "_period_dtype_code"
+    dtype_code = freq._period_dtype_code  # type: ignore[attr-defined]
+    freq_group = FreqGroup.from_period_dtype_code(dtype_code)
+
+    ppd = -1  # placeholder for above-day freqs
+
+    if dtype_code >= FreqGroup.FR_HR.value:
+        # error: "BaseOffset" has no attribute "_creso"
+        ppd = periods_per_day(freq._creso)  # type: ignore[attr-defined]
+        ppm = 28 * ppd
+        ppy = 365 * ppd
+    elif freq_group == FreqGroup.FR_BUS:
+        ppm = 19
+        ppy = 261
+    elif freq_group == FreqGroup.FR_DAY:
+        ppm = 28
+        ppy = 365
+    elif freq_group == FreqGroup.FR_WK:
+        ppm = 3
+        ppy = 52
+    elif freq_group == FreqGroup.FR_MTH:
+        ppm = 1
+        ppy = 12
+    elif freq_group == FreqGroup.FR_QTR:
+        ppm = -1  # placerholder
+        ppy = 4
+    elif freq_group == FreqGroup.FR_ANN:
+        ppm = -1  # placeholder
+        ppy = 1
+    else:
+        raise NotImplementedError(f"Unsupported frequency: {dtype_code}")
+
+    return ppd, ppm, ppy
+
+
+@functools.cache
+def _daily_finder(vmin: float, vmax: float, freq: BaseOffset) -> np.ndarray:
+    # error: "BaseOffset" has no attribute "_period_dtype_code"
+    dtype_code = freq._period_dtype_code  # type: ignore[attr-defined]
+
+    periodsperday, periodspermonth, periodsperyear = _get_periods_per_ymd(freq)
+
+    # save this for later usage
+    vmin_orig = vmin
+    (vmin, vmax) = (int(vmin), int(vmax))
+    span = vmax - vmin + 1
+
+    with warnings.catch_warnings():
+        warnings.filterwarnings(
+            "ignore", "Period with BDay freq is deprecated", category=FutureWarning
+        )
+        warnings.filterwarnings(
+            "ignore", r"PeriodDtype\[B\] is deprecated", category=FutureWarning
+        )
+        dates_ = period_range(
+            start=Period(ordinal=vmin, freq=freq),
+            end=Period(ordinal=vmax, freq=freq),
+            freq=freq,
+        )
+
+    # Initialize the output
+    info = np.zeros(
+        span, dtype=[("val", np.int64), ("maj", bool), ("min", bool), ("fmt", "|S20")]
+    )
+    info["val"][:] = dates_.asi8
+    info["fmt"][:] = ""
+    info["maj"][[0, -1]] = True
+    # .. and set some shortcuts
+    info_maj = info["maj"]
+    info_min = info["min"]
+    info_fmt = info["fmt"]
+
+    def first_label(label_flags):
+        if (label_flags[0] == 0) and (label_flags.size > 1) and ((vmin_orig % 1) > 0.0):
+            return label_flags[1]
+        else:
+            return label_flags[0]
+
+    # Case 1. Less than a month
+    if span <= periodspermonth:
+        day_start = _period_break(dates_, "day")
+        month_start = _period_break(dates_, "month")
+        year_start = _period_break(dates_, "year")
+
+        def _hour_finder(label_interval: int, force_year_start: bool) -> None:
+            target = dates_.hour
+            mask = _period_break_mask(dates_, "hour")
+            info_maj[day_start] = True
+            info_min[mask & (target % label_interval == 0)] = True
+            info_fmt[mask & (target % label_interval == 0)] = "%H:%M"
+            info_fmt[day_start] = "%H:%M\n%d-%b"
+            info_fmt[year_start] = "%H:%M\n%d-%b\n%Y"
+            if force_year_start and not has_level_label(year_start, vmin_orig):
+                info_fmt[first_label(day_start)] = "%H:%M\n%d-%b\n%Y"
+
+        def _minute_finder(label_interval: int) -> None:
+            target = dates_.minute
+            hour_start = _period_break(dates_, "hour")
+            mask = _period_break_mask(dates_, "minute")
+            info_maj[hour_start] = True
+            info_min[mask & (target % label_interval == 0)] = True
+            info_fmt[mask & (target % label_interval == 0)] = "%H:%M"
+            info_fmt[day_start] = "%H:%M\n%d-%b"
+            info_fmt[year_start] = "%H:%M\n%d-%b\n%Y"
+
+        def _second_finder(label_interval: int) -> None:
+            target = dates_.second
+            minute_start = _period_break(dates_, "minute")
+            mask = _period_break_mask(dates_, "second")
+            info_maj[minute_start] = True
+            info_min[mask & (target % label_interval == 0)] = True
+            info_fmt[mask & (target % label_interval == 0)] = "%H:%M:%S"
+            info_fmt[day_start] = "%H:%M:%S\n%d-%b"
+            info_fmt[year_start] = "%H:%M:%S\n%d-%b\n%Y"
+
+        if span < periodsperday / 12000:
+            _second_finder(1)
+        elif span < periodsperday / 6000:
+            _second_finder(2)
+        elif span < periodsperday / 2400:
+            _second_finder(5)
+        elif span < periodsperday / 1200:
+            _second_finder(10)
+        elif span < periodsperday / 800:
+            _second_finder(15)
+        elif span < periodsperday / 400:
+            _second_finder(30)
+        elif span < periodsperday / 150:
+            _minute_finder(1)
+        elif span < periodsperday / 70:
+            _minute_finder(2)
+        elif span < periodsperday / 24:
+            _minute_finder(5)
+        elif span < periodsperday / 12:
+            _minute_finder(15)
+        elif span < periodsperday / 6:
+            _minute_finder(30)
+        elif span < periodsperday / 2.5:
+            _hour_finder(1, False)
+        elif span < periodsperday / 1.5:
+            _hour_finder(2, False)
+        elif span < periodsperday * 1.25:
+            _hour_finder(3, False)
+        elif span < periodsperday * 2.5:
+            _hour_finder(6, True)
+        elif span < periodsperday * 4:
+            _hour_finder(12, True)
+        else:
+            info_maj[month_start] = True
+            info_min[day_start] = True
+            info_fmt[day_start] = "%d"
+            info_fmt[month_start] = "%d\n%b"
+            info_fmt[year_start] = "%d\n%b\n%Y"
+            if not has_level_label(year_start, vmin_orig):
+                if not has_level_label(month_start, vmin_orig):
+                    info_fmt[first_label(day_start)] = "%d\n%b\n%Y"
+                else:
+                    info_fmt[first_label(month_start)] = "%d\n%b\n%Y"
+
+    # Case 2. Less than three months
+    elif span <= periodsperyear // 4:
+        month_start = _period_break(dates_, "month")
+        info_maj[month_start] = True
+        if dtype_code < FreqGroup.FR_HR.value:
+            info["min"] = True
+        else:
+            day_start = _period_break(dates_, "day")
+            info["min"][day_start] = True
+        week_start = _period_break(dates_, "week")
+        year_start = _period_break(dates_, "year")
+        info_fmt[week_start] = "%d"
+        info_fmt[month_start] = "\n\n%b"
+        info_fmt[year_start] = "\n\n%b\n%Y"
+        if not has_level_label(year_start, vmin_orig):
+            if not has_level_label(month_start, vmin_orig):
+                info_fmt[first_label(week_start)] = "\n\n%b\n%Y"
+            else:
+                info_fmt[first_label(month_start)] = "\n\n%b\n%Y"
+    # Case 3. Less than 14 months ...............
+    elif span <= 1.15 * periodsperyear:
+        year_start = _period_break(dates_, "year")
+        month_start = _period_break(dates_, "month")
+        week_start = _period_break(dates_, "week")
+        info_maj[month_start] = True
+        info_min[week_start] = True
+        info_min[year_start] = False
+        info_min[month_start] = False
+        info_fmt[month_start] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+        if not has_level_label(year_start, vmin_orig):
+            info_fmt[first_label(month_start)] = "%b\n%Y"
+    # Case 4. Less than 2.5 years ...............
+    elif span <= 2.5 * periodsperyear:
+        year_start = _period_break(dates_, "year")
+        quarter_start = _period_break(dates_, "quarter")
+        month_start = _period_break(dates_, "month")
+        info_maj[quarter_start] = True
+        info_min[month_start] = True
+        info_fmt[quarter_start] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+    # Case 4. Less than 4 years .................
+    elif span <= 4 * periodsperyear:
+        year_start = _period_break(dates_, "year")
+        month_start = _period_break(dates_, "month")
+        info_maj[year_start] = True
+        info_min[month_start] = True
+        info_min[year_start] = False
+
+        month_break = dates_[month_start].month
+        jan_or_jul = month_start[(month_break == 1) | (month_break == 7)]
+        info_fmt[jan_or_jul] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+    # Case 5. Less than 11 years ................
+    elif span <= 11 * periodsperyear:
+        year_start = _period_break(dates_, "year")
+        quarter_start = _period_break(dates_, "quarter")
+        info_maj[year_start] = True
+        info_min[quarter_start] = True
+        info_min[year_start] = False
+        info_fmt[year_start] = "%Y"
+    # Case 6. More than 12 years ................
+    else:
+        year_start = _period_break(dates_, "year")
+        year_break = dates_[year_start].year
+        nyears = span / periodsperyear
+        (min_anndef, maj_anndef) = _get_default_annual_spacing(nyears)
+        major_idx = year_start[(year_break % maj_anndef == 0)]
+        info_maj[major_idx] = True
+        minor_idx = year_start[(year_break % min_anndef == 0)]
+        info_min[minor_idx] = True
+        info_fmt[major_idx] = "%Y"
+
+    return info
+
+
+@functools.cache
+def _monthly_finder(vmin: float, vmax: float, freq: BaseOffset) -> np.ndarray:
+    _, _, periodsperyear = _get_periods_per_ymd(freq)
+
+    vmin_orig = vmin
+    (vmin, vmax) = (int(vmin), int(vmax))
+    span = vmax - vmin + 1
+
+    # Initialize the output
+    info = np.zeros(
+        span, dtype=[("val", int), ("maj", bool), ("min", bool), ("fmt", "|S8")]
+    )
+    info["val"] = np.arange(vmin, vmax + 1)
+    dates_ = info["val"]
+    info["fmt"] = ""
+    year_start = (dates_ % 12 == 0).nonzero()[0]
+    info_maj = info["maj"]
+    info_fmt = info["fmt"]
+
+    if span <= 1.15 * periodsperyear:
+        info_maj[year_start] = True
+        info["min"] = True
+
+        info_fmt[:] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+
+        if not has_level_label(year_start, vmin_orig):
+            if dates_.size > 1:
+                idx = 1
+            else:
+                idx = 0
+            info_fmt[idx] = "%b\n%Y"
+
+    elif span <= 2.5 * periodsperyear:
+        quarter_start = (dates_ % 3 == 0).nonzero()
+        info_maj[year_start] = True
+        # TODO: Check the following : is it really info['fmt'] ?
+        #  2023-09-15 this is reached in test_finder_monthly
+        info["fmt"][quarter_start] = True
+        info["min"] = True
+
+        info_fmt[quarter_start] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+
+    elif span <= 4 * periodsperyear:
+        info_maj[year_start] = True
+        info["min"] = True
+
+        jan_or_jul = (dates_ % 12 == 0) | (dates_ % 12 == 6)
+        info_fmt[jan_or_jul] = "%b"
+        info_fmt[year_start] = "%b\n%Y"
+
+    elif span <= 11 * periodsperyear:
+        quarter_start = (dates_ % 3 == 0).nonzero()
+        info_maj[year_start] = True
+        info["min"][quarter_start] = True
+
+        info_fmt[year_start] = "%Y"
+
+    else:
+        nyears = span / periodsperyear
+        (min_anndef, maj_anndef) = _get_default_annual_spacing(nyears)
+        years = dates_[year_start] // 12 + 1
+        major_idx = year_start[(years % maj_anndef == 0)]
+        info_maj[major_idx] = True
+        info["min"][year_start[(years % min_anndef == 0)]] = True
+
+        info_fmt[major_idx] = "%Y"
+
+    return info
+
+
+@functools.cache
+def _quarterly_finder(vmin: float, vmax: float, freq: BaseOffset) -> np.ndarray:
+    _, _, periodsperyear = _get_periods_per_ymd(freq)
+    vmin_orig = vmin
+    (vmin, vmax) = (int(vmin), int(vmax))
+    span = vmax - vmin + 1
+
+    info = np.zeros(
+        span, dtype=[("val", int), ("maj", bool), ("min", bool), ("fmt", "|S8")]
+    )
+    info["val"] = np.arange(vmin, vmax + 1)
+    info["fmt"] = ""
+    dates_ = info["val"]
+    info_maj = info["maj"]
+    info_fmt = info["fmt"]
+    year_start = (dates_ % 4 == 0).nonzero()[0]
+
+    if span <= 3.5 * periodsperyear:
+        info_maj[year_start] = True
+        info["min"] = True
+
+        info_fmt[:] = "Q%q"
+        info_fmt[year_start] = "Q%q\n%F"
+        if not has_level_label(year_start, vmin_orig):
+            if dates_.size > 1:
+                idx = 1
+            else:
+                idx = 0
+            info_fmt[idx] = "Q%q\n%F"
+
+    elif span <= 11 * periodsperyear:
+        info_maj[year_start] = True
+        info["min"] = True
+        info_fmt[year_start] = "%F"
+
+    else:
+        # https://github.com/pandas-dev/pandas/pull/47602
+        years = dates_[year_start] // 4 + 1970
+        nyears = span / periodsperyear
+        (min_anndef, maj_anndef) = _get_default_annual_spacing(nyears)
+        major_idx = year_start[(years % maj_anndef == 0)]
+        info_maj[major_idx] = True
+        info["min"][year_start[(years % min_anndef == 0)]] = True
+        info_fmt[major_idx] = "%F"
+
+    return info
+
+
+@functools.cache
+def _annual_finder(vmin: float, vmax: float, freq: BaseOffset) -> np.ndarray:
+    # Note: small difference here vs other finders in adding 1 to vmax
+    (vmin, vmax) = (int(vmin), int(vmax + 1))
+    span = vmax - vmin + 1
+
+    info = np.zeros(
+        span, dtype=[("val", int), ("maj", bool), ("min", bool), ("fmt", "|S8")]
+    )
+    info["val"] = np.arange(vmin, vmax + 1)
+    info["fmt"] = ""
+    dates_ = info["val"]
+
+    (min_anndef, maj_anndef) = _get_default_annual_spacing(span)
+    major_idx = dates_ % maj_anndef == 0
+    minor_idx = dates_ % min_anndef == 0
+    info["maj"][major_idx] = True
+    info["min"][minor_idx] = True
+    info["fmt"][major_idx] = "%Y"
+
+    return info
+
+
+def get_finder(freq: BaseOffset):
+    # error: "BaseOffset" has no attribute "_period_dtype_code"
+    dtype_code = freq._period_dtype_code  # type: ignore[attr-defined]
+    fgroup = FreqGroup.from_period_dtype_code(dtype_code)
+
+    if fgroup == FreqGroup.FR_ANN:
+        return _annual_finder
+    elif fgroup == FreqGroup.FR_QTR:
+        return _quarterly_finder
+    elif fgroup == FreqGroup.FR_MTH:
+        return _monthly_finder
+    elif (dtype_code >= FreqGroup.FR_BUS.value) or fgroup == FreqGroup.FR_WK:
+        return _daily_finder
+    else:  # pragma: no cover
+        raise NotImplementedError(f"Unsupported frequency: {dtype_code}")
+
+
+class TimeSeries_DateLocator(Locator):
+    """
+    Locates the ticks along an axis controlled by a :class:`Series`.
+
+    Parameters
+    ----------
+    freq : BaseOffset
+        Valid frequency specifier.
+    minor_locator : {False, True}, optional
+        Whether the locator is for minor ticks (True) or not.
+    dynamic_mode : {True, False}, optional
+        Whether the locator should work in dynamic mode.
+    base : {int}, optional
+    quarter : {int}, optional
+    month : {int}, optional
+    day : {int}, optional
+    """
+
+    axis: Axis
+
+    def __init__(
+        self,
+        freq: BaseOffset,
+        minor_locator: bool = False,
+        dynamic_mode: bool = True,
+        base: int = 1,
+        quarter: int = 1,
+        month: int = 1,
+        day: int = 1,
+        plot_obj=None,
+    ) -> None:
+        freq = to_offset(freq, is_period=True)
+        self.freq = freq
+        self.base = base
+        (self.quarter, self.month, self.day) = (quarter, month, day)
+        self.isminor = minor_locator
+        self.isdynamic = dynamic_mode
+        self.offset = 0
+        self.plot_obj = plot_obj
+        self.finder = get_finder(freq)
+
+    def _get_default_locs(self, vmin, vmax):
+        """Returns the default locations of ticks."""
+        locator = self.finder(vmin, vmax, self.freq)
+
+        if self.isminor:
+            return np.compress(locator["min"], locator["val"])
+        return np.compress(locator["maj"], locator["val"])
+
+    def __call__(self):
+        """Return the locations of the ticks."""
+        # axis calls Locator.set_axis inside set_m_formatter
+
+        vi = tuple(self.axis.get_view_interval())
+        vmin, vmax = vi
+        if vmax < vmin:
+            vmin, vmax = vmax, vmin
+        if self.isdynamic:
+            locs = self._get_default_locs(vmin, vmax)
+        else:  # pragma: no cover
+            base = self.base
+            (d, m) = divmod(vmin, base)
+            vmin = (d + 1) * base
+            # error: No overload variant of "range" matches argument types "float",
+            # "float", "int"
+            locs = list(range(vmin, vmax + 1, base))  # type: ignore[call-overload]
+        return locs
+
+    def autoscale(self):
+        """
+        Sets the view limits to the nearest multiples of base that contain the
+        data.
+        """
+        # requires matplotlib >= 0.98.0
+        (vmin, vmax) = self.axis.get_data_interval()
+
+        locs = self._get_default_locs(vmin, vmax)
+        (vmin, vmax) = locs[[0, -1]]
+        if vmin == vmax:
+            vmin -= 1
+            vmax += 1
+        return nonsingular(vmin, vmax)
+
+
+# -------------------------------------------------------------------------
+# --- Formatter ---
+# -------------------------------------------------------------------------
+
+
+class TimeSeries_DateFormatter(Formatter):
+    """
+    Formats the ticks along an axis controlled by a :class:`PeriodIndex`.
+
+    Parameters
+    ----------
+    freq : BaseOffset
+        Valid frequency specifier.
+    minor_locator : bool, default False
+        Whether the current formatter should apply to minor ticks (True) or
+        major ticks (False).
+    dynamic_mode : bool, default True
+        Whether the formatter works in dynamic mode or not.
+    """
+
+    axis: Axis
+
+    def __init__(
+        self,
+        freq: BaseOffset,
+        minor_locator: bool = False,
+        dynamic_mode: bool = True,
+        plot_obj=None,
+    ) -> None:
+        freq = to_offset(freq, is_period=True)
+        self.format = None
+        self.freq = freq
+        self.locs: list[Any] = []  # unused, for matplotlib compat
+        self.formatdict: dict[Any, Any] | None = None
+        self.isminor = minor_locator
+        self.isdynamic = dynamic_mode
+        self.offset = 0
+        self.plot_obj = plot_obj
+        self.finder = get_finder(freq)
+
+    def _set_default_format(self, vmin, vmax):
+        """Returns the default ticks spacing."""
+        info = self.finder(vmin, vmax, self.freq)
+
+        if self.isminor:
+            format = np.compress(info["min"] & np.logical_not(info["maj"]), info)
+        else:
+            format = np.compress(info["maj"], info)
+        self.formatdict = {x: f for (x, _, _, f) in format}
+        return self.formatdict
+
+    def set_locs(self, locs) -> None:
+        """Sets the locations of the ticks"""
+        # don't actually use the locs. This is just needed to work with
+        # matplotlib. Force to use vmin, vmax
+
+        self.locs = locs
+
+        (vmin, vmax) = tuple(self.axis.get_view_interval())
+        if vmax < vmin:
+            (vmin, vmax) = (vmax, vmin)
+        self._set_default_format(vmin, vmax)
+
+    def __call__(self, x, pos: int | None = 0) -> str:
+        if self.formatdict is None:
+            return ""
+        else:
+            fmt = self.formatdict.pop(x, "")
+            if isinstance(fmt, np.bytes_):
+                fmt = fmt.decode("utf-8")
+            with warnings.catch_warnings():
+                warnings.filterwarnings(
+                    "ignore",
+                    "Period with BDay freq is deprecated",
+                    category=FutureWarning,
+                )
+                period = Period(ordinal=int(x), freq=self.freq)
+            assert isinstance(period, Period)
+            return period.strftime(fmt)
+
+
+class TimeSeries_TimedeltaFormatter(Formatter):
+    """
+    Formats the ticks along an axis controlled by a :class:`TimedeltaIndex`.
+    """
+
+    axis: Axis
+
+    @staticmethod
+    def format_timedelta_ticks(x, pos, n_decimals: int) -> str:
+        """
+        Convert seconds to 'D days HH:MM:SS.F'
+        """
+        s, ns = divmod(x, 10**9)  # TODO(non-nano): this looks like it assumes ns
+        m, s = divmod(s, 60)
+        h, m = divmod(m, 60)
+        d, h = divmod(h, 24)
+        decimals = int(ns * 10 ** (n_decimals - 9))
+        s = f"{int(h):02d}:{int(m):02d}:{int(s):02d}"
+        if n_decimals > 0:
+            s += f".{decimals:0{n_decimals}d}"
+        if d != 0:
+            s = f"{int(d):d} days {s}"
+        return s
+
+    def __call__(self, x, pos: int | None = 0) -> str:
+        (vmin, vmax) = tuple(self.axis.get_view_interval())
+        n_decimals = min(int(np.ceil(np.log10(100 * 10**9 / abs(vmax - vmin)))), 9)
+        return self.format_timedelta_ticks(x, pos, n_decimals)
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/core.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/core.py
new file mode 100644
index 0000000000000000000000000000000000000000..3a1e589c2279bdadb736ce85312bc2c84f5793eb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/core.py
@@ -0,0 +1,2125 @@
+from __future__ import annotations
+
+from abc import (
+    ABC,
+    abstractmethod,
+)
+from collections.abc import (
+    Hashable,
+    Iterable,
+    Iterator,
+    Sequence,
+)
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    cast,
+    final,
+)
+import warnings
+
+import matplotlib as mpl
+import numpy as np
+
+from pandas._libs import lib
+from pandas.errors import AbstractMethodError
+from pandas.util._decorators import cache_readonly
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import (
+    is_any_real_numeric_dtype,
+    is_bool,
+    is_float,
+    is_float_dtype,
+    is_hashable,
+    is_integer,
+    is_integer_dtype,
+    is_iterator,
+    is_list_like,
+    is_number,
+    is_numeric_dtype,
+)
+from pandas.core.dtypes.dtypes import (
+    CategoricalDtype,
+    ExtensionDtype,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCDatetimeIndex,
+    ABCIndex,
+    ABCMultiIndex,
+    ABCPeriodIndex,
+    ABCSeries,
+)
+from pandas.core.dtypes.missing import isna
+
+import pandas.core.common as com
+from pandas.core.frame import DataFrame
+from pandas.util.version import Version
+
+from pandas.io.formats.printing import pprint_thing
+from pandas.plotting._matplotlib import tools
+from pandas.plotting._matplotlib.converter import register_pandas_matplotlib_converters
+from pandas.plotting._matplotlib.groupby import reconstruct_data_with_by
+from pandas.plotting._matplotlib.misc import unpack_single_str_list
+from pandas.plotting._matplotlib.style import get_standard_colors
+from pandas.plotting._matplotlib.timeseries import (
+    decorate_axes,
+    format_dateaxis,
+    maybe_convert_index,
+    maybe_resample,
+    use_dynamic_x,
+)
+from pandas.plotting._matplotlib.tools import (
+    create_subplots,
+    flatten_axes,
+    format_date_labels,
+    get_all_lines,
+    get_xlim,
+    handle_shared_axes,
+)
+
+if TYPE_CHECKING:
+    from matplotlib.artist import Artist
+    from matplotlib.axes import Axes
+    from matplotlib.axis import Axis
+    from matplotlib.figure import Figure
+
+    from pandas._typing import (
+        IndexLabel,
+        NDFrameT,
+        PlottingOrientation,
+        npt,
+    )
+
+    from pandas import Series
+
+
+def _color_in_style(style: str) -> bool:
+    """
+    Check if there is a color letter in the style string.
+    """
+    from matplotlib.colors import BASE_COLORS
+
+    return not set(BASE_COLORS).isdisjoint(style)
+
+
+class MPLPlot(ABC):
+    """
+    Base class for assembling a pandas plot using matplotlib
+
+    Parameters
+    ----------
+    data :
+
+    """
+
+    @property
+    @abstractmethod
+    def _kind(self) -> str:
+        """Specify kind str. Must be overridden in child class"""
+        raise NotImplementedError
+
+    _layout_type = "vertical"
+    _default_rot = 0
+
+    @property
+    def orientation(self) -> str | None:
+        return None
+
+    data: DataFrame
+
+    def __init__(
+        self,
+        data,
+        kind=None,
+        by: IndexLabel | None = None,
+        subplots: bool | Sequence[Sequence[str]] = False,
+        sharex: bool | None = None,
+        sharey: bool = False,
+        use_index: bool = True,
+        figsize: tuple[float, float] | None = None,
+        grid=None,
+        legend: bool | str = True,
+        rot=None,
+        ax=None,
+        fig=None,
+        title=None,
+        xlim=None,
+        ylim=None,
+        xticks=None,
+        yticks=None,
+        xlabel: Hashable | None = None,
+        ylabel: Hashable | None = None,
+        fontsize: int | None = None,
+        secondary_y: bool | tuple | list | np.ndarray = False,
+        colormap=None,
+        table: bool = False,
+        layout=None,
+        include_bool: bool = False,
+        column: IndexLabel | None = None,
+        *,
+        logx: bool | None | Literal["sym"] = False,
+        logy: bool | None | Literal["sym"] = False,
+        loglog: bool | None | Literal["sym"] = False,
+        mark_right: bool = True,
+        stacked: bool = False,
+        label: Hashable | None = None,
+        style=None,
+        **kwds,
+    ) -> None:
+        import matplotlib.pyplot as plt
+
+        # if users assign an empty list or tuple, raise `ValueError`
+        # similar to current `df.box` and `df.hist` APIs.
+        if by in ([], ()):
+            raise ValueError("No group keys passed!")
+        self.by = com.maybe_make_list(by)
+
+        # Assign the rest of columns into self.columns if by is explicitly defined
+        # while column is not, only need `columns` in hist/box plot when it's DF
+        # TODO: Might deprecate `column` argument in future PR (#28373)
+        if isinstance(data, DataFrame):
+            if column:
+                self.columns = com.maybe_make_list(column)
+            elif self.by is None:
+                self.columns = [
+                    col for col in data.columns if is_numeric_dtype(data[col])
+                ]
+            else:
+                self.columns = [
+                    col
+                    for col in data.columns
+                    if col not in self.by and is_numeric_dtype(data[col])
+                ]
+
+        # For `hist` plot, need to get grouped original data before `self.data` is
+        # updated later
+        if self.by is not None and self._kind == "hist":
+            self._grouped = data.groupby(unpack_single_str_list(self.by))
+
+        self.kind = kind
+
+        self.subplots = type(self)._validate_subplots_kwarg(
+            subplots, data, kind=self._kind
+        )
+
+        self.sharex = type(self)._validate_sharex(sharex, ax, by)
+        self.sharey = sharey
+        self.figsize = figsize
+        self.layout = layout
+
+        self.xticks = xticks
+        self.yticks = yticks
+        self.xlim = xlim
+        self.ylim = ylim
+        self.title = title
+        self.use_index = use_index
+        self.xlabel = xlabel
+        self.ylabel = ylabel
+
+        self.fontsize = fontsize
+
+        if rot is not None:
+            self.rot = rot
+            # need to know for format_date_labels since it's rotated to 30 by
+            # default
+            self._rot_set = True
+        else:
+            self._rot_set = False
+            self.rot = self._default_rot
+
+        if grid is None:
+            grid = False if secondary_y else plt.rcParams["axes.grid"]
+
+        self.grid = grid
+        self.legend = legend
+        self.legend_handles: list[Artist] = []
+        self.legend_labels: list[Hashable] = []
+
+        self.logx = type(self)._validate_log_kwd("logx", logx)
+        self.logy = type(self)._validate_log_kwd("logy", logy)
+        self.loglog = type(self)._validate_log_kwd("loglog", loglog)
+        self.label = label
+        self.style = style
+        self.mark_right = mark_right
+        self.stacked = stacked
+
+        # ax may be an Axes object or (if self.subplots) an ndarray of
+        #  Axes objects
+        self.ax = ax
+        # TODO: deprecate fig keyword as it is ignored, not passed in tests
+        #  as of 2023-11-05
+
+        # parse errorbar input if given
+        xerr = kwds.pop("xerr", None)
+        yerr = kwds.pop("yerr", None)
+        nseries = self._get_nseries(data)
+        xerr, data = type(self)._parse_errorbars("xerr", xerr, data, nseries)
+        yerr, data = type(self)._parse_errorbars("yerr", yerr, data, nseries)
+        self.errors = {"xerr": xerr, "yerr": yerr}
+        self.data = data
+
+        if not isinstance(secondary_y, (bool, tuple, list, np.ndarray, ABCIndex)):
+            secondary_y = [secondary_y]
+        self.secondary_y = secondary_y
+
+        # ugly TypeError if user passes matplotlib's `cmap` name.
+        # Probably better to accept either.
+        if "cmap" in kwds and colormap:
+            raise TypeError("Only specify one of `cmap` and `colormap`.")
+        if "cmap" in kwds:
+            self.colormap = kwds.pop("cmap")
+        else:
+            self.colormap = colormap
+
+        self.table = table
+        self.include_bool = include_bool
+
+        self.kwds = kwds
+
+        color = kwds.pop("color", lib.no_default)
+        self.color = self._validate_color_args(color, self.colormap)
+        assert "color" not in self.kwds
+
+        self.data = self._ensure_frame(self.data)
+
+    @final
+    @staticmethod
+    def _validate_sharex(sharex: bool | None, ax, by) -> bool:
+        if sharex is None:
+            # if by is defined, subplots are used and sharex should be False
+            if ax is None and by is None:  # pylint: disable=simplifiable-if-statement
+                sharex = True
+            else:
+                # if we get an axis, the users should do the visibility
+                # setting...
+                sharex = False
+        elif not is_bool(sharex):
+            raise TypeError("sharex must be a bool or None")
+        return bool(sharex)
+
+    @classmethod
+    def _validate_log_kwd(
+        cls,
+        kwd: str,
+        value: bool | None | Literal["sym"],
+    ) -> bool | None | Literal["sym"]:
+        if (
+            value is None
+            or isinstance(value, bool)
+            or (isinstance(value, str) and value == "sym")
+        ):
+            return value
+        raise ValueError(
+            f"keyword '{kwd}' should be bool, None, or 'sym', not '{value}'"
+        )
+
+    @final
+    @staticmethod
+    def _validate_subplots_kwarg(
+        subplots: bool | Sequence[Sequence[str]], data: Series | DataFrame, kind: str
+    ) -> bool | list[tuple[int, ...]]:
+        """
+        Validate the subplots parameter
+
+        - check type and content
+        - check for duplicate columns
+        - check for invalid column names
+        - convert column names into indices
+        - add missing columns in a group of their own
+        See comments in code below for more details.
+
+        Parameters
+        ----------
+        subplots : subplots parameters as passed to PlotAccessor
+
+        Returns
+        -------
+        validated subplots : a bool or a list of tuples of column indices. Columns
+        in the same tuple will be grouped together in the resulting plot.
+        """
+
+        if isinstance(subplots, bool):
+            return subplots
+        elif not isinstance(subplots, Iterable):
+            raise ValueError("subplots should be a bool or an iterable")
+
+        supported_kinds = (
+            "line",
+            "bar",
+            "barh",
+            "hist",
+            "kde",
+            "density",
+            "area",
+            "pie",
+        )
+        if kind not in supported_kinds:
+            raise ValueError(
+                "When subplots is an iterable, kind must be "
+                f"one of {', '.join(supported_kinds)}. Got {kind}."
+            )
+
+        if isinstance(data, ABCSeries):
+            raise NotImplementedError(
+                "An iterable subplots for a Series is not supported."
+            )
+
+        columns = data.columns
+        if isinstance(columns, ABCMultiIndex):
+            raise NotImplementedError(
+                "An iterable subplots for a DataFrame with a MultiIndex column "
+                "is not supported."
+            )
+
+        if columns.nunique() != len(columns):
+            raise NotImplementedError(
+                "An iterable subplots for a DataFrame with non-unique column "
+                "labels is not supported."
+            )
+
+        # subplots is a list of tuples where each tuple is a group of
+        # columns to be grouped together (one ax per group).
+        # we consolidate the subplots list such that:
+        # - the tuples contain indices instead of column names
+        # - the columns that aren't yet in the list are added in a group
+        #   of their own.
+        # For example with columns from a to g, and
+        # subplots = [(a, c), (b, f, e)],
+        # we end up with [(ai, ci), (bi, fi, ei), (di,), (gi,)]
+        # This way, we can handle self.subplots in a homogeneous manner
+        # later.
+        # TODO: also accept indices instead of just names?
+
+        out = []
+        seen_columns: set[Hashable] = set()
+        for group in subplots:
+            if not is_list_like(group):
+                raise ValueError(
+                    "When subplots is an iterable, each entry "
+                    "should be a list/tuple of column names."
+                )
+            idx_locs = columns.get_indexer_for(group)
+            if (idx_locs == -1).any():
+                bad_labels = np.extract(idx_locs == -1, group)
+                raise ValueError(
+                    f"Column label(s) {list(bad_labels)} not found in the DataFrame."
+                )
+            unique_columns = set(group)
+            duplicates = seen_columns.intersection(unique_columns)
+            if duplicates:
+                raise ValueError(
+                    "Each column should be in only one subplot. "
+                    f"Columns {duplicates} were found in multiple subplots."
+                )
+            seen_columns = seen_columns.union(unique_columns)
+            out.append(tuple(idx_locs))
+
+        unseen_columns = columns.difference(seen_columns)
+        for column in unseen_columns:
+            idx_loc = columns.get_loc(column)
+            out.append((idx_loc,))
+        return out
+
+    def _validate_color_args(self, color, colormap):
+        if color is lib.no_default:
+            # It was not provided by the user
+            if "colors" in self.kwds and colormap is not None:
+                warnings.warn(
+                    "'color' and 'colormap' cannot be used simultaneously. "
+                    "Using 'color'",
+                    stacklevel=find_stack_level(),
+                )
+            return None
+        if self.nseries == 1 and color is not None and not is_list_like(color):
+            # support series.plot(color='green')
+            color = [color]
+
+        if isinstance(color, tuple) and self.nseries == 1 and len(color) in (3, 4):
+            # support RGB and RGBA tuples in series plot
+            color = [color]
+
+        if colormap is not None:
+            warnings.warn(
+                "'color' and 'colormap' cannot be used simultaneously. Using 'color'",
+                stacklevel=find_stack_level(),
+            )
+
+        if self.style is not None:
+            if is_list_like(self.style):
+                styles = self.style
+            else:
+                styles = [self.style]
+            # need only a single match
+            for s in styles:
+                if _color_in_style(s):
+                    raise ValueError(
+                        "Cannot pass 'style' string with a color symbol and "
+                        "'color' keyword argument. Please use one or the "
+                        "other or pass 'style' without a color symbol"
+                    )
+        return color
+
+    @final
+    @staticmethod
+    def _iter_data(
+        data: DataFrame | dict[Hashable, Series | DataFrame]
+    ) -> Iterator[tuple[Hashable, np.ndarray]]:
+        for col, values in data.items():
+            # This was originally written to use values.values before EAs
+            #  were implemented; adding np.asarray(...) to keep consistent
+            #  typing.
+            yield col, np.asarray(values.values)
+
+    def _get_nseries(self, data: Series | DataFrame) -> int:
+        # When `by` is explicitly assigned, grouped data size will be defined, and
+        # this will determine number of subplots to have, aka `self.nseries`
+        if data.ndim == 1:
+            return 1
+        elif self.by is not None and self._kind == "hist":
+            return len(self._grouped)
+        elif self.by is not None and self._kind == "box":
+            return len(self.columns)
+        else:
+            return data.shape[1]
+
+    @final
+    @property
+    def nseries(self) -> int:
+        return self._get_nseries(self.data)
+
+    @final
+    def draw(self) -> None:
+        self.plt.draw_if_interactive()
+
+    @final
+    def generate(self) -> None:
+        self._compute_plot_data()
+        fig = self.fig
+        self._make_plot(fig)
+        self._add_table()
+        self._make_legend()
+        self._adorn_subplots(fig)
+
+        for ax in self.axes:
+            self._post_plot_logic_common(ax)
+            self._post_plot_logic(ax, self.data)
+
+    @final
+    @staticmethod
+    def _has_plotted_object(ax: Axes) -> bool:
+        """check whether ax has data"""
+        return len(ax.lines) != 0 or len(ax.artists) != 0 or len(ax.containers) != 0
+
+    @final
+    def _maybe_right_yaxis(self, ax: Axes, axes_num: int) -> Axes:
+        if not self.on_right(axes_num):
+            # secondary axes may be passed via ax kw
+            return self._get_ax_layer(ax)
+
+        if hasattr(ax, "right_ax"):
+            # if it has right_ax property, ``ax`` must be left axes
+            return ax.right_ax
+        elif hasattr(ax, "left_ax"):
+            # if it has left_ax property, ``ax`` must be right axes
+            return ax
+        else:
+            # otherwise, create twin axes
+            orig_ax, new_ax = ax, ax.twinx()
+            # TODO: use Matplotlib public API when available
+            new_ax._get_lines = orig_ax._get_lines  # type: ignore[attr-defined]
+            # TODO #54485
+            new_ax._get_patches_for_fill = (  # type: ignore[attr-defined]
+                orig_ax._get_patches_for_fill  # type: ignore[attr-defined]
+            )
+            # TODO #54485
+            orig_ax.right_ax, new_ax.left_ax = (  # type: ignore[attr-defined]
+                new_ax,
+                orig_ax,
+            )
+
+            if not self._has_plotted_object(orig_ax):  # no data on left y
+                orig_ax.get_yaxis().set_visible(False)
+
+            if self.logy is True or self.loglog is True:
+                new_ax.set_yscale("log")
+            elif self.logy == "sym" or self.loglog == "sym":
+                new_ax.set_yscale("symlog")
+            return new_ax
+
+    @final
+    @cache_readonly
+    def fig(self) -> Figure:
+        return self._axes_and_fig[1]
+
+    @final
+    @cache_readonly
+    # TODO: can we annotate this as both a Sequence[Axes] and ndarray[object]?
+    def axes(self) -> Sequence[Axes]:
+        return self._axes_and_fig[0]
+
+    @final
+    @cache_readonly
+    def _axes_and_fig(self) -> tuple[Sequence[Axes], Figure]:
+        if self.subplots:
+            naxes = (
+                self.nseries if isinstance(self.subplots, bool) else len(self.subplots)
+            )
+            fig, axes = create_subplots(
+                naxes=naxes,
+                sharex=self.sharex,
+                sharey=self.sharey,
+                figsize=self.figsize,
+                ax=self.ax,
+                layout=self.layout,
+                layout_type=self._layout_type,
+            )
+        elif self.ax is None:
+            fig = self.plt.figure(figsize=self.figsize)
+            axes = fig.add_subplot(111)
+        else:
+            fig = self.ax.get_figure()
+            if self.figsize is not None:
+                fig.set_size_inches(self.figsize)
+            axes = self.ax
+
+        axes = flatten_axes(axes)
+
+        if self.logx is True or self.loglog is True:
+            [a.set_xscale("log") for a in axes]
+        elif self.logx == "sym" or self.loglog == "sym":
+            [a.set_xscale("symlog") for a in axes]
+
+        if self.logy is True or self.loglog is True:
+            [a.set_yscale("log") for a in axes]
+        elif self.logy == "sym" or self.loglog == "sym":
+            [a.set_yscale("symlog") for a in axes]
+
+        axes_seq = cast(Sequence["Axes"], axes)
+        return axes_seq, fig
+
+    @property
+    def result(self):
+        """
+        Return result axes
+        """
+        if self.subplots:
+            if self.layout is not None and not is_list_like(self.ax):
+                # error: "Sequence[Any]" has no attribute "reshape"
+                return self.axes.reshape(*self.layout)  # type: ignore[attr-defined]
+            else:
+                return self.axes
+        else:
+            sec_true = isinstance(self.secondary_y, bool) and self.secondary_y
+            # error: Argument 1 to "len" has incompatible type "Union[bool,
+            # Tuple[Any, ...], List[Any], ndarray[Any, Any]]"; expected "Sized"
+            all_sec = (
+                is_list_like(self.secondary_y)
+                and len(self.secondary_y) == self.nseries  # type: ignore[arg-type]
+            )
+            if sec_true or all_sec:
+                # if all data is plotted on secondary, return right axes
+                return self._get_ax_layer(self.axes[0], primary=False)
+            else:
+                return self.axes[0]
+
+    @final
+    @staticmethod
+    def _convert_to_ndarray(data):
+        # GH31357: categorical columns are processed separately
+        if isinstance(data.dtype, CategoricalDtype):
+            return data
+
+        # GH32073: cast to float if values contain nulled integers
+        if (is_integer_dtype(data.dtype) or is_float_dtype(data.dtype)) and isinstance(
+            data.dtype, ExtensionDtype
+        ):
+            return data.to_numpy(dtype="float", na_value=np.nan)
+
+        # GH25587: cast ExtensionArray of pandas (IntegerArray, etc.) to
+        # np.ndarray before plot.
+        if len(data) > 0:
+            return np.asarray(data)
+
+        return data
+
+    @final
+    def _ensure_frame(self, data) -> DataFrame:
+        if isinstance(data, ABCSeries):
+            label = self.label
+            if label is None and data.name is None:
+                label = ""
+            if label is None:
+                # We'll end up with columns of [0] instead of [None]
+                data = data.to_frame()
+            else:
+                data = data.to_frame(name=label)
+        elif self._kind in ("hist", "box"):
+            cols = self.columns if self.by is None else self.columns + self.by
+            data = data.loc[:, cols]
+        return data
+
+    @final
+    def _compute_plot_data(self) -> None:
+        data = self.data
+
+        # GH15079 reconstruct data if by is defined
+        if self.by is not None:
+            self.subplots = True
+            data = reconstruct_data_with_by(self.data, by=self.by, cols=self.columns)
+
+        # GH16953, infer_objects is needed as fallback, for ``Series``
+        # with ``dtype == object``
+        data = data.infer_objects(copy=False)
+        include_type = [np.number, "datetime", "datetimetz", "timedelta"]
+
+        # GH23719, allow plotting boolean
+        if self.include_bool is True:
+            include_type.append(np.bool_)
+
+        # GH22799, exclude datetime-like type for boxplot
+        exclude_type = None
+        if self._kind == "box":
+            # TODO: change after solving issue 27881
+            include_type = [np.number]
+            exclude_type = ["timedelta"]
+
+        # GH 18755, include object and category type for scatter plot
+        if self._kind == "scatter":
+            include_type.extend(["object", "category", "string"])
+
+        numeric_data = data.select_dtypes(include=include_type, exclude=exclude_type)
+
+        is_empty = numeric_data.shape[-1] == 0
+        # no non-numeric frames or series allowed
+        if is_empty:
+            raise TypeError("no numeric data to plot")
+
+        self.data = numeric_data.apply(type(self)._convert_to_ndarray)
+
+    def _make_plot(self, fig: Figure) -> None:
+        raise AbstractMethodError(self)
+
+    @final
+    def _add_table(self) -> None:
+        if self.table is False:
+            return
+        elif self.table is True:
+            data = self.data.transpose()
+        else:
+            data = self.table
+        ax = self._get_ax(0)
+        tools.table(ax, data)
+
+    @final
+    def _post_plot_logic_common(self, ax: Axes) -> None:
+        """Common post process for each axes"""
+        if self.orientation == "vertical" or self.orientation is None:
+            type(self)._apply_axis_properties(
+                ax.xaxis, rot=self.rot, fontsize=self.fontsize
+            )
+            type(self)._apply_axis_properties(ax.yaxis, fontsize=self.fontsize)
+
+            if hasattr(ax, "right_ax"):
+                type(self)._apply_axis_properties(
+                    ax.right_ax.yaxis, fontsize=self.fontsize
+                )
+
+        elif self.orientation == "horizontal":
+            type(self)._apply_axis_properties(
+                ax.yaxis, rot=self.rot, fontsize=self.fontsize
+            )
+            type(self)._apply_axis_properties(ax.xaxis, fontsize=self.fontsize)
+
+            if hasattr(ax, "right_ax"):
+                type(self)._apply_axis_properties(
+                    ax.right_ax.yaxis, fontsize=self.fontsize
+                )
+        else:  # pragma no cover
+            raise ValueError
+
+    @abstractmethod
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        """Post process for each axes. Overridden in child classes"""
+
+    @final
+    def _adorn_subplots(self, fig: Figure) -> None:
+        """Common post process unrelated to data"""
+        if len(self.axes) > 0:
+            all_axes = self._get_subplots(fig)
+            nrows, ncols = self._get_axes_layout(fig)
+            handle_shared_axes(
+                axarr=all_axes,
+                nplots=len(all_axes),
+                naxes=nrows * ncols,
+                nrows=nrows,
+                ncols=ncols,
+                sharex=self.sharex,
+                sharey=self.sharey,
+            )
+
+        for ax in self.axes:
+            ax = getattr(ax, "right_ax", ax)
+            if self.yticks is not None:
+                ax.set_yticks(self.yticks)
+
+            if self.xticks is not None:
+                ax.set_xticks(self.xticks)
+
+            if self.ylim is not None:
+                ax.set_ylim(self.ylim)
+
+            if self.xlim is not None:
+                ax.set_xlim(self.xlim)
+
+            # GH9093, currently Pandas does not show ylabel, so if users provide
+            # ylabel will set it as ylabel in the plot.
+            if self.ylabel is not None:
+                ax.set_ylabel(pprint_thing(self.ylabel))
+
+            ax.grid(self.grid)
+
+        if self.title:
+            if self.subplots:
+                if is_list_like(self.title):
+                    if len(self.title) != self.nseries:
+                        raise ValueError(
+                            "The length of `title` must equal the number "
+                            "of columns if using `title` of type `list` "
+                            "and `subplots=True`.\n"
+                            f"length of title = {len(self.title)}\n"
+                            f"number of columns = {self.nseries}"
+                        )
+
+                    for ax, title in zip(self.axes, self.title):
+                        ax.set_title(title)
+                else:
+                    fig.suptitle(self.title)
+            else:
+                if is_list_like(self.title):
+                    msg = (
+                        "Using `title` of type `list` is not supported "
+                        "unless `subplots=True` is passed"
+                    )
+                    raise ValueError(msg)
+                self.axes[0].set_title(self.title)
+
+    @final
+    @staticmethod
+    def _apply_axis_properties(
+        axis: Axis, rot=None, fontsize: int | None = None
+    ) -> None:
+        """
+        Tick creation within matplotlib is reasonably expensive and is
+        internally deferred until accessed as Ticks are created/destroyed
+        multiple times per draw. It's therefore beneficial for us to avoid
+        accessing unless we will act on the Tick.
+        """
+        if rot is not None or fontsize is not None:
+            # rot=0 is a valid setting, hence the explicit None check
+            labels = axis.get_majorticklabels() + axis.get_minorticklabels()
+            for label in labels:
+                if rot is not None:
+                    label.set_rotation(rot)
+                if fontsize is not None:
+                    label.set_fontsize(fontsize)
+
+    @final
+    @property
+    def legend_title(self) -> str | None:
+        if not isinstance(self.data.columns, ABCMultiIndex):
+            name = self.data.columns.name
+            if name is not None:
+                name = pprint_thing(name)
+            return name
+        else:
+            stringified = map(pprint_thing, self.data.columns.names)
+            return ",".join(stringified)
+
+    @final
+    def _mark_right_label(self, label: str, index: int) -> str:
+        """
+        Append ``(right)`` to the label of a line if it's plotted on the right axis.
+
+        Note that ``(right)`` is only appended when ``subplots=False``.
+        """
+        if not self.subplots and self.mark_right and self.on_right(index):
+            label += " (right)"
+        return label
+
+    @final
+    def _append_legend_handles_labels(self, handle: Artist, label: str) -> None:
+        """
+        Append current handle and label to ``legend_handles`` and ``legend_labels``.
+
+        These will be used to make the legend.
+        """
+        self.legend_handles.append(handle)
+        self.legend_labels.append(label)
+
+    def _make_legend(self) -> None:
+        ax, leg = self._get_ax_legend(self.axes[0])
+
+        handles = []
+        labels = []
+        title = ""
+
+        if not self.subplots:
+            if leg is not None:
+                title = leg.get_title().get_text()
+                # Replace leg.legend_handles because it misses marker info
+                if Version(mpl.__version__) < Version("3.7"):
+                    handles = leg.legendHandles
+                else:
+                    handles = leg.legend_handles
+                labels = [x.get_text() for x in leg.get_texts()]
+
+            if self.legend:
+                if self.legend == "reverse":
+                    handles += reversed(self.legend_handles)
+                    labels += reversed(self.legend_labels)
+                else:
+                    handles += self.legend_handles
+                    labels += self.legend_labels
+
+                if self.legend_title is not None:
+                    title = self.legend_title
+
+            if len(handles) > 0:
+                ax.legend(handles, labels, loc="best", title=title)
+
+        elif self.subplots and self.legend:
+            for ax in self.axes:
+                if ax.get_visible():
+                    with warnings.catch_warnings():
+                        warnings.filterwarnings(
+                            "ignore",
+                            "No artists with labels found to put in legend.",
+                            UserWarning,
+                        )
+                        ax.legend(loc="best")
+
+    @final
+    @staticmethod
+    def _get_ax_legend(ax: Axes):
+        """
+        Take in axes and return ax and legend under different scenarios
+        """
+        leg = ax.get_legend()
+
+        other_ax = getattr(ax, "left_ax", None) or getattr(ax, "right_ax", None)
+        other_leg = None
+        if other_ax is not None:
+            other_leg = other_ax.get_legend()
+        if leg is None and other_leg is not None:
+            leg = other_leg
+            ax = other_ax
+        return ax, leg
+
+    @final
+    @cache_readonly
+    def plt(self):
+        import matplotlib.pyplot as plt
+
+        return plt
+
+    _need_to_set_index = False
+
+    @final
+    def _get_xticks(self):
+        index = self.data.index
+        is_datetype = index.inferred_type in ("datetime", "date", "datetime64", "time")
+
+        # TODO: be stricter about x?
+        x: list[int] | np.ndarray
+        if self.use_index:
+            if isinstance(index, ABCPeriodIndex):
+                # test_mixed_freq_irreg_period
+                x = index.to_timestamp()._mpl_repr()
+                # TODO: why do we need to do to_timestamp() here but not other
+                #  places where we call mpl_repr?
+            elif is_any_real_numeric_dtype(index.dtype):
+                # Matplotlib supports numeric values or datetime objects as
+                # xaxis values. Taking LBYL approach here, by the time
+                # matplotlib raises exception when using non numeric/datetime
+                # values for xaxis, several actions are already taken by plt.
+                x = index._mpl_repr()
+            elif isinstance(index, ABCDatetimeIndex) or is_datetype:
+                x = index._mpl_repr()
+            else:
+                self._need_to_set_index = True
+                x = list(range(len(index)))
+        else:
+            x = list(range(len(index)))
+
+        return x
+
+    @classmethod
+    @register_pandas_matplotlib_converters
+    def _plot(
+        cls, ax: Axes, x, y: np.ndarray, style=None, is_errorbar: bool = False, **kwds
+    ):
+        mask = isna(y)
+        if mask.any():
+            y = np.ma.array(y)
+            y = np.ma.masked_where(mask, y)
+
+        if isinstance(x, ABCIndex):
+            x = x._mpl_repr()
+
+        if is_errorbar:
+            if "xerr" in kwds:
+                kwds["xerr"] = np.array(kwds.get("xerr"))
+            if "yerr" in kwds:
+                kwds["yerr"] = np.array(kwds.get("yerr"))
+            return ax.errorbar(x, y, **kwds)
+        else:
+            # prevent style kwarg from going to errorbar, where it is unsupported
+            args = (x, y, style) if style is not None else (x, y)
+            return ax.plot(*args, **kwds)
+
+    def _get_custom_index_name(self):
+        """Specify whether xlabel/ylabel should be used to override index name"""
+        return self.xlabel
+
+    @final
+    def _get_index_name(self) -> str | None:
+        if isinstance(self.data.index, ABCMultiIndex):
+            name = self.data.index.names
+            if com.any_not_none(*name):
+                name = ",".join([pprint_thing(x) for x in name])
+            else:
+                name = None
+        else:
+            name = self.data.index.name
+            if name is not None:
+                name = pprint_thing(name)
+
+        # GH 45145, override the default axis label if one is provided.
+        index_name = self._get_custom_index_name()
+        if index_name is not None:
+            name = pprint_thing(index_name)
+
+        return name
+
+    @final
+    @classmethod
+    def _get_ax_layer(cls, ax, primary: bool = True):
+        """get left (primary) or right (secondary) axes"""
+        if primary:
+            return getattr(ax, "left_ax", ax)
+        else:
+            return getattr(ax, "right_ax", ax)
+
+    @final
+    def _col_idx_to_axis_idx(self, col_idx: int) -> int:
+        """Return the index of the axis where the column at col_idx should be plotted"""
+        if isinstance(self.subplots, list):
+            # Subplots is a list: some columns will be grouped together in the same ax
+            return next(
+                group_idx
+                for (group_idx, group) in enumerate(self.subplots)
+                if col_idx in group
+            )
+        else:
+            # subplots is True: one ax per column
+            return col_idx
+
+    @final
+    def _get_ax(self, i: int):
+        # get the twinx ax if appropriate
+        if self.subplots:
+            i = self._col_idx_to_axis_idx(i)
+            ax = self.axes[i]
+            ax = self._maybe_right_yaxis(ax, i)
+            # error: Unsupported target for indexed assignment ("Sequence[Any]")
+            self.axes[i] = ax  # type: ignore[index]
+        else:
+            ax = self.axes[0]
+            ax = self._maybe_right_yaxis(ax, i)
+
+        ax.get_yaxis().set_visible(True)
+        return ax
+
+    @final
+    def on_right(self, i: int):
+        if isinstance(self.secondary_y, bool):
+            return self.secondary_y
+
+        if isinstance(self.secondary_y, (tuple, list, np.ndarray, ABCIndex)):
+            return self.data.columns[i] in self.secondary_y
+
+    @final
+    def _apply_style_colors(
+        self, colors, kwds: dict[str, Any], col_num: int, label: str
+    ):
+        """
+        Manage style and color based on column number and its label.
+        Returns tuple of appropriate style and kwds which "color" may be added.
+        """
+        style = None
+        if self.style is not None:
+            if isinstance(self.style, list):
+                try:
+                    style = self.style[col_num]
+                except IndexError:
+                    pass
+            elif isinstance(self.style, dict):
+                style = self.style.get(label, style)
+            else:
+                style = self.style
+
+        has_color = "color" in kwds or self.colormap is not None
+        nocolor_style = style is None or not _color_in_style(style)
+        if (has_color or self.subplots) and nocolor_style:
+            if isinstance(colors, dict):
+                kwds["color"] = colors[label]
+            else:
+                kwds["color"] = colors[col_num % len(colors)]
+        return style, kwds
+
+    def _get_colors(
+        self,
+        num_colors: int | None = None,
+        color_kwds: str = "color",
+    ):
+        if num_colors is None:
+            num_colors = self.nseries
+        if color_kwds == "color":
+            color = self.color
+        else:
+            color = self.kwds.get(color_kwds)
+        return get_standard_colors(
+            num_colors=num_colors,
+            colormap=self.colormap,
+            color=color,
+        )
+
+    # TODO: tighter typing for first return?
+    @final
+    @staticmethod
+    def _parse_errorbars(
+        label: str, err, data: NDFrameT, nseries: int
+    ) -> tuple[Any, NDFrameT]:
+        """
+        Look for error keyword arguments and return the actual errorbar data
+        or return the error DataFrame/dict
+
+        Error bars can be specified in several ways:
+            Series: the user provides a pandas.Series object of the same
+                    length as the data
+            ndarray: provides a np.ndarray of the same length as the data
+            DataFrame/dict: error values are paired with keys matching the
+                    key in the plotted DataFrame
+            str: the name of the column within the plotted DataFrame
+
+        Asymmetrical error bars are also supported, however raw error values
+        must be provided in this case. For a ``N`` length :class:`Series`, a
+        ``2xN`` array should be provided indicating lower and upper (or left
+        and right) errors. For a ``MxN`` :class:`DataFrame`, asymmetrical errors
+        should be in a ``Mx2xN`` array.
+        """
+        if err is None:
+            return None, data
+
+        def match_labels(data, e):
+            e = e.reindex(data.index)
+            return e
+
+        # key-matched DataFrame
+        if isinstance(err, ABCDataFrame):
+            err = match_labels(data, err)
+        # key-matched dict
+        elif isinstance(err, dict):
+            pass
+
+        # Series of error values
+        elif isinstance(err, ABCSeries):
+            # broadcast error series across data
+            err = match_labels(data, err)
+            err = np.atleast_2d(err)
+            err = np.tile(err, (nseries, 1))
+
+        # errors are a column in the dataframe
+        elif isinstance(err, str):
+            evalues = data[err].values
+            data = data[data.columns.drop(err)]
+            err = np.atleast_2d(evalues)
+            err = np.tile(err, (nseries, 1))
+
+        elif is_list_like(err):
+            if is_iterator(err):
+                err = np.atleast_2d(list(err))
+            else:
+                # raw error values
+                err = np.atleast_2d(err)
+
+            err_shape = err.shape
+
+            # asymmetrical error bars
+            if isinstance(data, ABCSeries) and err_shape[0] == 2:
+                err = np.expand_dims(err, 0)
+                err_shape = err.shape
+                if err_shape[2] != len(data):
+                    raise ValueError(
+                        "Asymmetrical error bars should be provided "
+                        f"with the shape (2, {len(data)})"
+                    )
+            elif isinstance(data, ABCDataFrame) and err.ndim == 3:
+                if (
+                    (err_shape[0] != nseries)
+                    or (err_shape[1] != 2)
+                    or (err_shape[2] != len(data))
+                ):
+                    raise ValueError(
+                        "Asymmetrical error bars should be provided "
+                        f"with the shape ({nseries}, 2, {len(data)})"
+                    )
+
+            # broadcast errors to each data series
+            if len(err) == 1:
+                err = np.tile(err, (nseries, 1))
+
+        elif is_number(err):
+            err = np.tile(
+                [err],
+                (nseries, len(data)),
+            )
+
+        else:
+            msg = f"No valid {label} detected"
+            raise ValueError(msg)
+
+        return err, data
+
+    @final
+    def _get_errorbars(
+        self, label=None, index=None, xerr: bool = True, yerr: bool = True
+    ) -> dict[str, Any]:
+        errors = {}
+
+        for kw, flag in zip(["xerr", "yerr"], [xerr, yerr]):
+            if flag:
+                err = self.errors[kw]
+                # user provided label-matched dataframe of errors
+                if isinstance(err, (ABCDataFrame, dict)):
+                    if label is not None and label in err.keys():
+                        err = err[label]
+                    else:
+                        err = None
+                elif index is not None and err is not None:
+                    err = err[index]
+
+                if err is not None:
+                    errors[kw] = err
+        return errors
+
+    @final
+    def _get_subplots(self, fig: Figure):
+        if Version(mpl.__version__) < Version("3.8"):
+            from matplotlib.axes import Subplot as Klass
+        else:
+            from matplotlib.axes import Axes as Klass
+
+        return [
+            ax
+            for ax in fig.get_axes()
+            if (isinstance(ax, Klass) and ax.get_subplotspec() is not None)
+        ]
+
+    @final
+    def _get_axes_layout(self, fig: Figure) -> tuple[int, int]:
+        axes = self._get_subplots(fig)
+        x_set = set()
+        y_set = set()
+        for ax in axes:
+            # check axes coordinates to estimate layout
+            points = ax.get_position().get_points()
+            x_set.add(points[0][0])
+            y_set.add(points[0][1])
+        return (len(y_set), len(x_set))
+
+
+class PlanePlot(MPLPlot, ABC):
+    """
+    Abstract class for plotting on plane, currently scatter and hexbin.
+    """
+
+    _layout_type = "single"
+
+    def __init__(self, data, x, y, **kwargs) -> None:
+        MPLPlot.__init__(self, data, **kwargs)
+        if x is None or y is None:
+            raise ValueError(self._kind + " requires an x and y column")
+        if is_integer(x) and not self.data.columns._holds_integer():
+            x = self.data.columns[x]
+        if is_integer(y) and not self.data.columns._holds_integer():
+            y = self.data.columns[y]
+
+        self.x = x
+        self.y = y
+
+    @final
+    def _get_nseries(self, data: Series | DataFrame) -> int:
+        return 1
+
+    @final
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        x, y = self.x, self.y
+        xlabel = self.xlabel if self.xlabel is not None else pprint_thing(x)
+        ylabel = self.ylabel if self.ylabel is not None else pprint_thing(y)
+        # error: Argument 1 to "set_xlabel" of "_AxesBase" has incompatible
+        # type "Hashable"; expected "str"
+        ax.set_xlabel(xlabel)  # type: ignore[arg-type]
+        ax.set_ylabel(ylabel)  # type: ignore[arg-type]
+
+    @final
+    def _plot_colorbar(self, ax: Axes, *, fig: Figure, **kwds):
+        # Addresses issues #10611 and #10678:
+        # When plotting scatterplots and hexbinplots in IPython
+        # inline backend the colorbar axis height tends not to
+        # exactly match the parent axis height.
+        # The difference is due to small fractional differences
+        # in floating points with similar representation.
+        # To deal with this, this method forces the colorbar
+        # height to take the height of the parent axes.
+        # For a more detailed description of the issue
+        # see the following link:
+        # https://github.com/ipython/ipython/issues/11215
+
+        # GH33389, if ax is used multiple times, we should always
+        # use the last one which contains the latest information
+        # about the ax
+        img = ax.collections[-1]
+        return fig.colorbar(img, ax=ax, **kwds)
+
+
+class ScatterPlot(PlanePlot):
+    @property
+    def _kind(self) -> Literal["scatter"]:
+        return "scatter"
+
+    def __init__(
+        self,
+        data,
+        x,
+        y,
+        s=None,
+        c=None,
+        *,
+        colorbar: bool | lib.NoDefault = lib.no_default,
+        norm=None,
+        **kwargs,
+    ) -> None:
+        if s is None:
+            # hide the matplotlib default for size, in case we want to change
+            # the handling of this argument later
+            s = 20
+        elif is_hashable(s) and s in data.columns:
+            s = data[s]
+        self.s = s
+
+        self.colorbar = colorbar
+        self.norm = norm
+
+        super().__init__(data, x, y, **kwargs)
+        if is_integer(c) and not self.data.columns._holds_integer():
+            c = self.data.columns[c]
+        self.c = c
+
+    def _make_plot(self, fig: Figure) -> None:
+        x, y, c, data = self.x, self.y, self.c, self.data
+        ax = self.axes[0]
+
+        c_is_column = is_hashable(c) and c in self.data.columns
+
+        color_by_categorical = c_is_column and isinstance(
+            self.data[c].dtype, CategoricalDtype
+        )
+
+        color = self.color
+        c_values = self._get_c_values(color, color_by_categorical, c_is_column)
+        norm, cmap = self._get_norm_and_cmap(c_values, color_by_categorical)
+        cb = self._get_colorbar(c_values, c_is_column)
+
+        if self.legend:
+            label = self.label
+        else:
+            label = None
+        scatter = ax.scatter(
+            data[x].values,
+            data[y].values,
+            c=c_values,
+            label=label,
+            cmap=cmap,
+            norm=norm,
+            s=self.s,
+            **self.kwds,
+        )
+        if cb:
+            cbar_label = c if c_is_column else ""
+            cbar = self._plot_colorbar(ax, fig=fig, label=cbar_label)
+            if color_by_categorical:
+                n_cats = len(self.data[c].cat.categories)
+                cbar.set_ticks(np.linspace(0.5, n_cats - 0.5, n_cats))
+                cbar.ax.set_yticklabels(self.data[c].cat.categories)
+
+        if label is not None:
+            self._append_legend_handles_labels(
+                # error: Argument 2 to "_append_legend_handles_labels" of
+                # "MPLPlot" has incompatible type "Hashable"; expected "str"
+                scatter,
+                label,  # type: ignore[arg-type]
+            )
+
+        errors_x = self._get_errorbars(label=x, index=0, yerr=False)
+        errors_y = self._get_errorbars(label=y, index=0, xerr=False)
+        if len(errors_x) > 0 or len(errors_y) > 0:
+            err_kwds = dict(errors_x, **errors_y)
+            err_kwds["ecolor"] = scatter.get_facecolor()[0]
+            ax.errorbar(data[x].values, data[y].values, linestyle="none", **err_kwds)
+
+    def _get_c_values(self, color, color_by_categorical: bool, c_is_column: bool):
+        c = self.c
+        if c is not None and color is not None:
+            raise TypeError("Specify exactly one of `c` and `color`")
+        if c is None and color is None:
+            c_values = self.plt.rcParams["patch.facecolor"]
+        elif color is not None:
+            c_values = color
+        elif color_by_categorical:
+            c_values = self.data[c].cat.codes
+        elif c_is_column:
+            c_values = self.data[c].values
+        else:
+            c_values = c
+        return c_values
+
+    def _get_norm_and_cmap(self, c_values, color_by_categorical: bool):
+        c = self.c
+        if self.colormap is not None:
+            cmap = mpl.colormaps.get_cmap(self.colormap)
+        # cmap is only used if c_values are integers, otherwise UserWarning.
+        # GH-53908: additionally call isinstance() because is_integer_dtype
+        # returns True for "b" (meaning "blue" and not int8 in this context)
+        elif not isinstance(c_values, str) and is_integer_dtype(c_values):
+            # pandas uses colormap, matplotlib uses cmap.
+            cmap = mpl.colormaps["Greys"]
+        else:
+            cmap = None
+
+        if color_by_categorical and cmap is not None:
+            from matplotlib import colors
+
+            n_cats = len(self.data[c].cat.categories)
+            cmap = colors.ListedColormap([cmap(i) for i in range(cmap.N)])
+            bounds = np.linspace(0, n_cats, n_cats + 1)
+            norm = colors.BoundaryNorm(bounds, cmap.N)
+            # TODO: warn that we are ignoring self.norm if user specified it?
+            #  Doesn't happen in any tests 2023-11-09
+        else:
+            norm = self.norm
+        return norm, cmap
+
+    def _get_colorbar(self, c_values, c_is_column: bool) -> bool:
+        # plot colorbar if
+        # 1. colormap is assigned, and
+        # 2.`c` is a column containing only numeric values
+        plot_colorbar = self.colormap or c_is_column
+        cb = self.colorbar
+        if cb is lib.no_default:
+            return is_numeric_dtype(c_values) and plot_colorbar
+        return cb
+
+
+class HexBinPlot(PlanePlot):
+    @property
+    def _kind(self) -> Literal["hexbin"]:
+        return "hexbin"
+
+    def __init__(self, data, x, y, C=None, *, colorbar: bool = True, **kwargs) -> None:
+        super().__init__(data, x, y, **kwargs)
+        if is_integer(C) and not self.data.columns._holds_integer():
+            C = self.data.columns[C]
+        self.C = C
+
+        self.colorbar = colorbar
+
+        # Scatter plot allows to plot objects data
+        if len(self.data[self.x]._get_numeric_data()) == 0:
+            raise ValueError(self._kind + " requires x column to be numeric")
+        if len(self.data[self.y]._get_numeric_data()) == 0:
+            raise ValueError(self._kind + " requires y column to be numeric")
+
+    def _make_plot(self, fig: Figure) -> None:
+        x, y, data, C = self.x, self.y, self.data, self.C
+        ax = self.axes[0]
+        # pandas uses colormap, matplotlib uses cmap.
+        cmap = self.colormap or "BuGn"
+        cmap = mpl.colormaps.get_cmap(cmap)
+        cb = self.colorbar
+
+        if C is None:
+            c_values = None
+        else:
+            c_values = data[C].values
+
+        ax.hexbin(data[x].values, data[y].values, C=c_values, cmap=cmap, **self.kwds)
+        if cb:
+            self._plot_colorbar(ax, fig=fig)
+
+    def _make_legend(self) -> None:
+        pass
+
+
+class LinePlot(MPLPlot):
+    _default_rot = 0
+
+    @property
+    def orientation(self) -> PlottingOrientation:
+        return "vertical"
+
+    @property
+    def _kind(self) -> Literal["line", "area", "hist", "kde", "box"]:
+        return "line"
+
+    def __init__(self, data, **kwargs) -> None:
+        from pandas.plotting import plot_params
+
+        MPLPlot.__init__(self, data, **kwargs)
+        if self.stacked:
+            self.data = self.data.fillna(value=0)
+        self.x_compat = plot_params["x_compat"]
+        if "x_compat" in self.kwds:
+            self.x_compat = bool(self.kwds.pop("x_compat"))
+
+    @final
+    def _is_ts_plot(self) -> bool:
+        # this is slightly deceptive
+        return not self.x_compat and self.use_index and self._use_dynamic_x()
+
+    @final
+    def _use_dynamic_x(self) -> bool:
+        return use_dynamic_x(self._get_ax(0), self.data)
+
+    def _make_plot(self, fig: Figure) -> None:
+        if self._is_ts_plot():
+            data = maybe_convert_index(self._get_ax(0), self.data)
+
+            x = data.index  # dummy, not used
+            plotf = self._ts_plot
+            it = data.items()
+        else:
+            x = self._get_xticks()
+            # error: Incompatible types in assignment (expression has type
+            # "Callable[[Any, Any, Any, Any, Any, Any, KwArg(Any)], Any]", variable has
+            # type "Callable[[Any, Any, Any, Any, KwArg(Any)], Any]")
+            plotf = self._plot  # type: ignore[assignment]
+            # error: Incompatible types in assignment (expression has type
+            # "Iterator[tuple[Hashable, ndarray[Any, Any]]]", variable has
+            # type "Iterable[tuple[Hashable, Series]]")
+            it = self._iter_data(data=self.data)  # type: ignore[assignment]
+
+        stacking_id = self._get_stacking_id()
+        is_errorbar = com.any_not_none(*self.errors.values())
+
+        colors = self._get_colors()
+        for i, (label, y) in enumerate(it):
+            ax = self._get_ax(i)
+            kwds = self.kwds.copy()
+            if self.color is not None:
+                kwds["color"] = self.color
+            style, kwds = self._apply_style_colors(
+                colors,
+                kwds,
+                i,
+                # error: Argument 4 to "_apply_style_colors" of "MPLPlot" has
+                # incompatible type "Hashable"; expected "str"
+                label,  # type: ignore[arg-type]
+            )
+
+            errors = self._get_errorbars(label=label, index=i)
+            kwds = dict(kwds, **errors)
+
+            label = pprint_thing(label)
+            label = self._mark_right_label(label, index=i)
+            kwds["label"] = label
+
+            newlines = plotf(
+                ax,
+                x,
+                y,
+                style=style,
+                column_num=i,
+                stacking_id=stacking_id,
+                is_errorbar=is_errorbar,
+                **kwds,
+            )
+            self._append_legend_handles_labels(newlines[0], label)
+
+            if self._is_ts_plot():
+                # reset of xlim should be used for ts data
+                # TODO: GH28021, should find a way to change view limit on xaxis
+                lines = get_all_lines(ax)
+                left, right = get_xlim(lines)
+                ax.set_xlim(left, right)
+
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls,
+        ax: Axes,
+        x,
+        y: np.ndarray,
+        style=None,
+        column_num=None,
+        stacking_id=None,
+        **kwds,
+    ):
+        # column_num is used to get the target column from plotf in line and
+        # area plots
+        if column_num == 0:
+            cls._initialize_stacker(ax, stacking_id, len(y))
+        y_values = cls._get_stacked_values(ax, stacking_id, y, kwds["label"])
+        lines = MPLPlot._plot(ax, x, y_values, style=style, **kwds)
+        cls._update_stacker(ax, stacking_id, y)
+        return lines
+
+    @final
+    def _ts_plot(self, ax: Axes, x, data: Series, style=None, **kwds):
+        # accept x to be consistent with normal plot func,
+        # x is not passed to tsplot as it uses data.index as x coordinate
+        # column_num must be in kwds for stacking purpose
+        freq, data = maybe_resample(data, ax, kwds)
+
+        # Set ax with freq info
+        decorate_axes(ax, freq)
+        # digging deeper
+        if hasattr(ax, "left_ax"):
+            decorate_axes(ax.left_ax, freq)
+        if hasattr(ax, "right_ax"):
+            decorate_axes(ax.right_ax, freq)
+        # TODO #54485
+        ax._plot_data.append((data, self._kind, kwds))  # type: ignore[attr-defined]
+
+        lines = self._plot(ax, data.index, np.asarray(data.values), style=style, **kwds)
+        # set date formatter, locators and rescale limits
+        # TODO #54485
+        format_dateaxis(ax, ax.freq, data.index)  # type: ignore[arg-type, attr-defined]
+        return lines
+
+    @final
+    def _get_stacking_id(self) -> int | None:
+        if self.stacked:
+            return id(self.data)
+        else:
+            return None
+
+    @final
+    @classmethod
+    def _initialize_stacker(cls, ax: Axes, stacking_id, n: int) -> None:
+        if stacking_id is None:
+            return
+        if not hasattr(ax, "_stacker_pos_prior"):
+            # TODO #54485
+            ax._stacker_pos_prior = {}  # type: ignore[attr-defined]
+        if not hasattr(ax, "_stacker_neg_prior"):
+            # TODO #54485
+            ax._stacker_neg_prior = {}  # type: ignore[attr-defined]
+        # TODO #54485
+        ax._stacker_pos_prior[stacking_id] = np.zeros(n)  # type: ignore[attr-defined]
+        # TODO #54485
+        ax._stacker_neg_prior[stacking_id] = np.zeros(n)  # type: ignore[attr-defined]
+
+    @final
+    @classmethod
+    def _get_stacked_values(
+        cls, ax: Axes, stacking_id: int | None, values: np.ndarray, label
+    ) -> np.ndarray:
+        if stacking_id is None:
+            return values
+        if not hasattr(ax, "_stacker_pos_prior"):
+            # stacker may not be initialized for subplots
+            cls._initialize_stacker(ax, stacking_id, len(values))
+
+        if (values >= 0).all():
+            # TODO #54485
+            return (
+                ax._stacker_pos_prior[stacking_id]  # type: ignore[attr-defined]
+                + values
+            )
+        elif (values <= 0).all():
+            # TODO #54485
+            return (
+                ax._stacker_neg_prior[stacking_id]  # type: ignore[attr-defined]
+                + values
+            )
+
+        raise ValueError(
+            "When stacked is True, each column must be either "
+            "all positive or all negative. "
+            f"Column '{label}' contains both positive and negative values"
+        )
+
+    @final
+    @classmethod
+    def _update_stacker(cls, ax: Axes, stacking_id: int | None, values) -> None:
+        if stacking_id is None:
+            return
+        if (values >= 0).all():
+            # TODO #54485
+            ax._stacker_pos_prior[stacking_id] += values  # type: ignore[attr-defined]
+        elif (values <= 0).all():
+            # TODO #54485
+            ax._stacker_neg_prior[stacking_id] += values  # type: ignore[attr-defined]
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        from matplotlib.ticker import FixedLocator
+
+        def get_label(i):
+            if is_float(i) and i.is_integer():
+                i = int(i)
+            try:
+                return pprint_thing(data.index[i])
+            except Exception:
+                return ""
+
+        if self._need_to_set_index:
+            xticks = ax.get_xticks()
+            xticklabels = [get_label(x) for x in xticks]
+            # error: Argument 1 to "FixedLocator" has incompatible type "ndarray[Any,
+            # Any]"; expected "Sequence[float]"
+            ax.xaxis.set_major_locator(FixedLocator(xticks))  # type: ignore[arg-type]
+            ax.set_xticklabels(xticklabels)
+
+        # If the index is an irregular time series, then by default
+        # we rotate the tick labels. The exception is if there are
+        # subplots which don't share their x-axes, in which we case
+        # we don't rotate the ticklabels as by default the subplots
+        # would be too close together.
+        condition = (
+            not self._use_dynamic_x()
+            and (data.index._is_all_dates and self.use_index)
+            and (not self.subplots or (self.subplots and self.sharex))
+        )
+
+        index_name = self._get_index_name()
+
+        if condition:
+            # irregular TS rotated 30 deg. by default
+            # probably a better place to check / set this.
+            if not self._rot_set:
+                self.rot = 30
+            format_date_labels(ax, rot=self.rot)
+
+        if index_name is not None and self.use_index:
+            ax.set_xlabel(index_name)
+
+
+class AreaPlot(LinePlot):
+    @property
+    def _kind(self) -> Literal["area"]:
+        return "area"
+
+    def __init__(self, data, **kwargs) -> None:
+        kwargs.setdefault("stacked", True)
+        with warnings.catch_warnings():
+            warnings.filterwarnings(
+                "ignore",
+                "Downcasting object dtype arrays",
+                category=FutureWarning,
+            )
+            data = data.fillna(value=0)
+        LinePlot.__init__(self, data, **kwargs)
+
+        if not self.stacked:
+            # use smaller alpha to distinguish overlap
+            self.kwds.setdefault("alpha", 0.5)
+
+        if self.logy or self.loglog:
+            raise ValueError("Log-y scales are not supported in area plot")
+
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls,
+        ax: Axes,
+        x,
+        y: np.ndarray,
+        style=None,
+        column_num=None,
+        stacking_id=None,
+        is_errorbar: bool = False,
+        **kwds,
+    ):
+        if column_num == 0:
+            cls._initialize_stacker(ax, stacking_id, len(y))
+        y_values = cls._get_stacked_values(ax, stacking_id, y, kwds["label"])
+
+        # need to remove label, because subplots uses mpl legend as it is
+        line_kwds = kwds.copy()
+        line_kwds.pop("label")
+        lines = MPLPlot._plot(ax, x, y_values, style=style, **line_kwds)
+
+        # get data from the line to get coordinates for fill_between
+        xdata, y_values = lines[0].get_data(orig=False)
+
+        # unable to use ``_get_stacked_values`` here to get starting point
+        if stacking_id is None:
+            start = np.zeros(len(y))
+        elif (y >= 0).all():
+            # TODO #54485
+            start = ax._stacker_pos_prior[stacking_id]  # type: ignore[attr-defined]
+        elif (y <= 0).all():
+            # TODO #54485
+            start = ax._stacker_neg_prior[stacking_id]  # type: ignore[attr-defined]
+        else:
+            start = np.zeros(len(y))
+
+        if "color" not in kwds:
+            kwds["color"] = lines[0].get_color()
+
+        rect = ax.fill_between(xdata, start, y_values, **kwds)
+        cls._update_stacker(ax, stacking_id, y)
+
+        # LinePlot expects list of artists
+        res = [rect]
+        return res
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        LinePlot._post_plot_logic(self, ax, data)
+
+        is_shared_y = len(list(ax.get_shared_y_axes())) > 0
+        # do not override the default axis behaviour in case of shared y axes
+        if self.ylim is None and not is_shared_y:
+            if (data >= 0).all().all():
+                ax.set_ylim(0, None)
+            elif (data <= 0).all().all():
+                ax.set_ylim(None, 0)
+
+
+class BarPlot(MPLPlot):
+    @property
+    def _kind(self) -> Literal["bar", "barh"]:
+        return "bar"
+
+    _default_rot = 90
+
+    @property
+    def orientation(self) -> PlottingOrientation:
+        return "vertical"
+
+    def __init__(
+        self,
+        data,
+        *,
+        align="center",
+        bottom=0,
+        left=0,
+        width=0.5,
+        position=0.5,
+        log=False,
+        **kwargs,
+    ) -> None:
+        # we have to treat a series differently than a
+        # 1-column DataFrame w.r.t. color handling
+        self._is_series = isinstance(data, ABCSeries)
+        self.bar_width = width
+        self._align = align
+        self._position = position
+        self.tick_pos = np.arange(len(data))
+
+        if is_list_like(bottom):
+            bottom = np.array(bottom)
+        if is_list_like(left):
+            left = np.array(left)
+        self.bottom = bottom
+        self.left = left
+
+        self.log = log
+
+        MPLPlot.__init__(self, data, **kwargs)
+
+    @cache_readonly
+    def ax_pos(self) -> np.ndarray:
+        return self.tick_pos - self.tickoffset
+
+    @cache_readonly
+    def tickoffset(self):
+        if self.stacked or self.subplots:
+            return self.bar_width * self._position
+        elif self._align == "edge":
+            w = self.bar_width / self.nseries
+            return self.bar_width * (self._position - 0.5) + w * 0.5
+        else:
+            return self.bar_width * self._position
+
+    @cache_readonly
+    def lim_offset(self):
+        if self.stacked or self.subplots:
+            if self._align == "edge":
+                return self.bar_width / 2
+            else:
+                return 0
+        elif self._align == "edge":
+            w = self.bar_width / self.nseries
+            return w * 0.5
+        else:
+            return 0
+
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls,
+        ax: Axes,
+        x,
+        y: np.ndarray,
+        w,
+        start: int | npt.NDArray[np.intp] = 0,
+        log: bool = False,
+        **kwds,
+    ):
+        return ax.bar(x, y, w, bottom=start, log=log, **kwds)
+
+    @property
+    def _start_base(self):
+        return self.bottom
+
+    def _make_plot(self, fig: Figure) -> None:
+        colors = self._get_colors()
+        ncolors = len(colors)
+
+        pos_prior = neg_prior = np.zeros(len(self.data))
+        K = self.nseries
+
+        data = self.data.fillna(0)
+        for i, (label, y) in enumerate(self._iter_data(data=data)):
+            ax = self._get_ax(i)
+            kwds = self.kwds.copy()
+            if self._is_series:
+                kwds["color"] = colors
+            elif isinstance(colors, dict):
+                kwds["color"] = colors[label]
+            else:
+                kwds["color"] = colors[i % ncolors]
+
+            errors = self._get_errorbars(label=label, index=i)
+            kwds = dict(kwds, **errors)
+
+            label = pprint_thing(label)
+            label = self._mark_right_label(label, index=i)
+
+            if (("yerr" in kwds) or ("xerr" in kwds)) and (kwds.get("ecolor") is None):
+                kwds["ecolor"] = mpl.rcParams["xtick.color"]
+
+            start = 0
+            if self.log and (y >= 1).all():
+                start = 1
+            start = start + self._start_base
+
+            kwds["align"] = self._align
+            if self.subplots:
+                w = self.bar_width / 2
+                rect = self._plot(
+                    ax,
+                    self.ax_pos + w,
+                    y,
+                    self.bar_width,
+                    start=start,
+                    label=label,
+                    log=self.log,
+                    **kwds,
+                )
+                ax.set_title(label)
+            elif self.stacked:
+                mask = y > 0
+                start = np.where(mask, pos_prior, neg_prior) + self._start_base
+                w = self.bar_width / 2
+                rect = self._plot(
+                    ax,
+                    self.ax_pos + w,
+                    y,
+                    self.bar_width,
+                    start=start,
+                    label=label,
+                    log=self.log,
+                    **kwds,
+                )
+                pos_prior = pos_prior + np.where(mask, y, 0)
+                neg_prior = neg_prior + np.where(mask, 0, y)
+            else:
+                w = self.bar_width / K
+                rect = self._plot(
+                    ax,
+                    self.ax_pos + (i + 0.5) * w,
+                    y,
+                    w,
+                    start=start,
+                    label=label,
+                    log=self.log,
+                    **kwds,
+                )
+            self._append_legend_handles_labels(rect, label)
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        if self.use_index:
+            str_index = [pprint_thing(key) for key in data.index]
+        else:
+            str_index = [pprint_thing(key) for key in range(data.shape[0])]
+
+        s_edge = self.ax_pos[0] - 0.25 + self.lim_offset
+        e_edge = self.ax_pos[-1] + 0.25 + self.bar_width + self.lim_offset
+
+        self._decorate_ticks(ax, self._get_index_name(), str_index, s_edge, e_edge)
+
+    def _decorate_ticks(
+        self,
+        ax: Axes,
+        name: str | None,
+        ticklabels: list[str],
+        start_edge: float,
+        end_edge: float,
+    ) -> None:
+        ax.set_xlim((start_edge, end_edge))
+
+        if self.xticks is not None:
+            ax.set_xticks(np.array(self.xticks))
+        else:
+            ax.set_xticks(self.tick_pos)
+            ax.set_xticklabels(ticklabels)
+
+        if name is not None and self.use_index:
+            ax.set_xlabel(name)
+
+
+class BarhPlot(BarPlot):
+    @property
+    def _kind(self) -> Literal["barh"]:
+        return "barh"
+
+    _default_rot = 0
+
+    @property
+    def orientation(self) -> Literal["horizontal"]:
+        return "horizontal"
+
+    @property
+    def _start_base(self):
+        return self.left
+
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls,
+        ax: Axes,
+        x,
+        y: np.ndarray,
+        w,
+        start: int | npt.NDArray[np.intp] = 0,
+        log: bool = False,
+        **kwds,
+    ):
+        return ax.barh(x, y, w, left=start, log=log, **kwds)
+
+    def _get_custom_index_name(self):
+        return self.ylabel
+
+    def _decorate_ticks(
+        self,
+        ax: Axes,
+        name: str | None,
+        ticklabels: list[str],
+        start_edge: float,
+        end_edge: float,
+    ) -> None:
+        # horizontal bars
+        ax.set_ylim((start_edge, end_edge))
+        ax.set_yticks(self.tick_pos)
+        ax.set_yticklabels(ticklabels)
+        if name is not None and self.use_index:
+            ax.set_ylabel(name)
+        # error: Argument 1 to "set_xlabel" of "_AxesBase" has incompatible type
+        # "Hashable | None"; expected "str"
+        ax.set_xlabel(self.xlabel)  # type: ignore[arg-type]
+
+
+class PiePlot(MPLPlot):
+    @property
+    def _kind(self) -> Literal["pie"]:
+        return "pie"
+
+    _layout_type = "horizontal"
+
+    def __init__(self, data, kind=None, **kwargs) -> None:
+        data = data.fillna(value=0)
+        if (data < 0).any().any():
+            raise ValueError(f"{self._kind} plot doesn't allow negative values")
+        MPLPlot.__init__(self, data, kind=kind, **kwargs)
+
+    @classmethod
+    def _validate_log_kwd(
+        cls,
+        kwd: str,
+        value: bool | None | Literal["sym"],
+    ) -> bool | None | Literal["sym"]:
+        super()._validate_log_kwd(kwd=kwd, value=value)
+        if value is not False:
+            warnings.warn(
+                f"PiePlot ignores the '{kwd}' keyword",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+        return False
+
+    def _validate_color_args(self, color, colormap) -> None:
+        # TODO: warn if color is passed and ignored?
+        return None
+
+    def _make_plot(self, fig: Figure) -> None:
+        colors = self._get_colors(num_colors=len(self.data), color_kwds="colors")
+        self.kwds.setdefault("colors", colors)
+
+        for i, (label, y) in enumerate(self._iter_data(data=self.data)):
+            ax = self._get_ax(i)
+            if label is not None:
+                label = pprint_thing(label)
+                ax.set_ylabel(label)
+
+            kwds = self.kwds.copy()
+
+            def blank_labeler(label, value):
+                if value == 0:
+                    return ""
+                else:
+                    return label
+
+            idx = [pprint_thing(v) for v in self.data.index]
+            labels = kwds.pop("labels", idx)
+            # labels is used for each wedge's labels
+            # Blank out labels for values of 0 so they don't overlap
+            # with nonzero wedges
+            if labels is not None:
+                blabels = [blank_labeler(left, value) for left, value in zip(labels, y)]
+            else:
+                blabels = None
+            results = ax.pie(y, labels=blabels, **kwds)
+
+            if kwds.get("autopct", None) is not None:
+                patches, texts, autotexts = results
+            else:
+                patches, texts = results
+                autotexts = []
+
+            if self.fontsize is not None:
+                for t in texts + autotexts:
+                    t.set_fontsize(self.fontsize)
+
+            # leglabels is used for legend labels
+            leglabels = labels if labels is not None else idx
+            for _patch, _leglabel in zip(patches, leglabels):
+                self._append_legend_handles_labels(_patch, _leglabel)
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        pass
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/groupby.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/groupby.py
new file mode 100644
index 0000000000000000000000000000000000000000..cbb66065a8039c63b7181619aea3aa74277da4a5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/groupby.py
@@ -0,0 +1,142 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from pandas.core.dtypes.missing import remove_na_arraylike
+
+from pandas import (
+    MultiIndex,
+    concat,
+)
+
+from pandas.plotting._matplotlib.misc import unpack_single_str_list
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from pandas._typing import IndexLabel
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+def create_iter_data_given_by(
+    data: DataFrame, kind: str = "hist"
+) -> dict[Hashable, DataFrame | Series]:
+    """
+    Create data for iteration given `by` is assigned or not, and it is only
+    used in both hist and boxplot.
+
+    If `by` is assigned, return a dictionary of DataFrames in which the key of
+    dictionary is the values in groups.
+    If `by` is not assigned, return input as is, and this preserves current
+    status of iter_data.
+
+    Parameters
+    ----------
+    data : reformatted grouped data from `_compute_plot_data` method.
+    kind : str, plot kind. This function is only used for `hist` and `box` plots.
+
+    Returns
+    -------
+    iter_data : DataFrame or Dictionary of DataFrames
+
+    Examples
+    --------
+    If `by` is assigned:
+
+    >>> import numpy as np
+    >>> tuples = [('h1', 'a'), ('h1', 'b'), ('h2', 'a'), ('h2', 'b')]
+    >>> mi = pd.MultiIndex.from_tuples(tuples)
+    >>> value = [[1, 3, np.nan, np.nan],
+    ...          [3, 4, np.nan, np.nan], [np.nan, np.nan, 5, 6]]
+    >>> data = pd.DataFrame(value, columns=mi)
+    >>> create_iter_data_given_by(data)
+    {'h1':     h1
+         a    b
+    0  1.0  3.0
+    1  3.0  4.0
+    2  NaN  NaN, 'h2':     h2
+         a    b
+    0  NaN  NaN
+    1  NaN  NaN
+    2  5.0  6.0}
+    """
+
+    # For `hist` plot, before transformation, the values in level 0 are values
+    # in groups and subplot titles, and later used for column subselection and
+    # iteration; For `box` plot, values in level 1 are column names to show,
+    # and are used for iteration and as subplots titles.
+    if kind == "hist":
+        level = 0
+    else:
+        level = 1
+
+    # Select sub-columns based on the value of level of MI, and if `by` is
+    # assigned, data must be a MI DataFrame
+    assert isinstance(data.columns, MultiIndex)
+    return {
+        col: data.loc[:, data.columns.get_level_values(level) == col]
+        for col in data.columns.levels[level]
+    }
+
+
+def reconstruct_data_with_by(
+    data: DataFrame, by: IndexLabel, cols: IndexLabel
+) -> DataFrame:
+    """
+    Internal function to group data, and reassign multiindex column names onto the
+    result in order to let grouped data be used in _compute_plot_data method.
+
+    Parameters
+    ----------
+    data : Original DataFrame to plot
+    by : grouped `by` parameter selected by users
+    cols : columns of data set (excluding columns used in `by`)
+
+    Returns
+    -------
+    Output is the reconstructed DataFrame with MultiIndex columns. The first level
+    of MI is unique values of groups, and second level of MI is the columns
+    selected by users.
+
+    Examples
+    --------
+    >>> d = {'h': ['h1', 'h1', 'h2'], 'a': [1, 3, 5], 'b': [3, 4, 6]}
+    >>> df = pd.DataFrame(d)
+    >>> reconstruct_data_with_by(df, by='h', cols=['a', 'b'])
+       h1      h2
+       a     b     a     b
+    0  1.0   3.0   NaN   NaN
+    1  3.0   4.0   NaN   NaN
+    2  NaN   NaN   5.0   6.0
+    """
+    by_modified = unpack_single_str_list(by)
+    grouped = data.groupby(by_modified)
+
+    data_list = []
+    for key, group in grouped:
+        # error: List item 1 has incompatible type "Union[Hashable,
+        # Sequence[Hashable]]"; expected "Iterable[Hashable]"
+        columns = MultiIndex.from_product([[key], cols])  # type: ignore[list-item]
+        sub_group = group[cols]
+        sub_group.columns = columns
+        data_list.append(sub_group)
+
+    data = concat(data_list, axis=1)
+    return data
+
+
+def reformat_hist_y_given_by(y: np.ndarray, by: IndexLabel | None) -> np.ndarray:
+    """Internal function to reformat y given `by` is applied or not for hist plot.
+
+    If by is None, input y is 1-d with NaN removed; and if by is not None, groupby
+    will take place and input y is multi-dimensional array.
+    """
+    if by is not None and len(y.shape) > 1:
+        return np.array([remove_na_arraylike(col) for col in y.T]).T
+    return remove_na_arraylike(y)
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/hist.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/hist.py
new file mode 100644
index 0000000000000000000000000000000000000000..e610f1adb602c46ffd7affa50c0f857ad7d030e4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/hist.py
@@ -0,0 +1,581 @@
+from __future__ import annotations
+
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    Literal,
+    final,
+)
+
+import numpy as np
+
+from pandas.core.dtypes.common import (
+    is_integer,
+    is_list_like,
+)
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+)
+from pandas.core.dtypes.missing import (
+    isna,
+    remove_na_arraylike,
+)
+
+from pandas.io.formats.printing import pprint_thing
+from pandas.plotting._matplotlib.core import (
+    LinePlot,
+    MPLPlot,
+)
+from pandas.plotting._matplotlib.groupby import (
+    create_iter_data_given_by,
+    reformat_hist_y_given_by,
+)
+from pandas.plotting._matplotlib.misc import unpack_single_str_list
+from pandas.plotting._matplotlib.tools import (
+    create_subplots,
+    flatten_axes,
+    maybe_adjust_figure,
+    set_ticks_props,
+)
+
+if TYPE_CHECKING:
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+    from pandas._typing import PlottingOrientation
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+class HistPlot(LinePlot):
+    @property
+    def _kind(self) -> Literal["hist", "kde"]:
+        return "hist"
+
+    def __init__(
+        self,
+        data,
+        bins: int | np.ndarray | list[np.ndarray] = 10,
+        bottom: int | np.ndarray = 0,
+        *,
+        range=None,
+        weights=None,
+        **kwargs,
+    ) -> None:
+        if is_list_like(bottom):
+            bottom = np.array(bottom)
+        self.bottom = bottom
+
+        self._bin_range = range
+        self.weights = weights
+
+        self.xlabel = kwargs.get("xlabel")
+        self.ylabel = kwargs.get("ylabel")
+        # Do not call LinePlot.__init__ which may fill nan
+        MPLPlot.__init__(self, data, **kwargs)  # pylint: disable=non-parent-init-called
+
+        self.bins = self._adjust_bins(bins)
+
+    def _adjust_bins(self, bins: int | np.ndarray | list[np.ndarray]):
+        if is_integer(bins):
+            if self.by is not None:
+                by_modified = unpack_single_str_list(self.by)
+                grouped = self.data.groupby(by_modified)[self.columns]
+                bins = [self._calculate_bins(group, bins) for key, group in grouped]
+            else:
+                bins = self._calculate_bins(self.data, bins)
+        return bins
+
+    def _calculate_bins(self, data: Series | DataFrame, bins) -> np.ndarray:
+        """Calculate bins given data"""
+        nd_values = data.infer_objects(copy=False)._get_numeric_data()
+        values = np.ravel(nd_values)
+        values = values[~isna(values)]
+
+        hist, bins = np.histogram(values, bins=bins, range=self._bin_range)
+        return bins
+
+    # error: Signature of "_plot" incompatible with supertype "LinePlot"
+    @classmethod
+    def _plot(  # type: ignore[override]
+        cls,
+        ax: Axes,
+        y: np.ndarray,
+        style=None,
+        bottom: int | np.ndarray = 0,
+        column_num: int = 0,
+        stacking_id=None,
+        *,
+        bins,
+        **kwds,
+    ):
+        if column_num == 0:
+            cls._initialize_stacker(ax, stacking_id, len(bins) - 1)
+
+        base = np.zeros(len(bins) - 1)
+        bottom = bottom + cls._get_stacked_values(ax, stacking_id, base, kwds["label"])
+        # ignore style
+        n, bins, patches = ax.hist(y, bins=bins, bottom=bottom, **kwds)
+        cls._update_stacker(ax, stacking_id, n)
+        return patches
+
+    def _make_plot(self, fig: Figure) -> None:
+        colors = self._get_colors()
+        stacking_id = self._get_stacking_id()
+
+        # Re-create iterated data if `by` is assigned by users
+        data = (
+            create_iter_data_given_by(self.data, self._kind)
+            if self.by is not None
+            else self.data
+        )
+
+        # error: Argument "data" to "_iter_data" of "MPLPlot" has incompatible
+        # type "object"; expected "DataFrame | dict[Hashable, Series | DataFrame]"
+        for i, (label, y) in enumerate(self._iter_data(data=data)):  # type: ignore[arg-type]
+            ax = self._get_ax(i)
+
+            kwds = self.kwds.copy()
+            if self.color is not None:
+                kwds["color"] = self.color
+
+            label = pprint_thing(label)
+            label = self._mark_right_label(label, index=i)
+            kwds["label"] = label
+
+            style, kwds = self._apply_style_colors(colors, kwds, i, label)
+            if style is not None:
+                kwds["style"] = style
+
+            self._make_plot_keywords(kwds, y)
+
+            # the bins is multi-dimension array now and each plot need only 1-d and
+            # when by is applied, label should be columns that are grouped
+            if self.by is not None:
+                kwds["bins"] = kwds["bins"][i]
+                kwds["label"] = self.columns
+                kwds.pop("color")
+
+            if self.weights is not None:
+                kwds["weights"] = type(self)._get_column_weights(self.weights, i, y)
+
+            y = reformat_hist_y_given_by(y, self.by)
+
+            artists = self._plot(ax, y, column_num=i, stacking_id=stacking_id, **kwds)
+
+            # when by is applied, show title for subplots to know which group it is
+            if self.by is not None:
+                ax.set_title(pprint_thing(label))
+
+            self._append_legend_handles_labels(artists[0], label)
+
+    def _make_plot_keywords(self, kwds: dict[str, Any], y: np.ndarray) -> None:
+        """merge BoxPlot/KdePlot properties to passed kwds"""
+        # y is required for KdePlot
+        kwds["bottom"] = self.bottom
+        kwds["bins"] = self.bins
+
+    @final
+    @staticmethod
+    def _get_column_weights(weights, i: int, y):
+        # We allow weights to be a multi-dimensional array, e.g. a (10, 2) array,
+        # and each sub-array (10,) will be called in each iteration. If users only
+        # provide 1D array, we assume the same weights is used for all iterations
+        if weights is not None:
+            if np.ndim(weights) != 1 and np.shape(weights)[-1] != 1:
+                try:
+                    weights = weights[:, i]
+                except IndexError as err:
+                    raise ValueError(
+                        "weights must have the same shape as data, "
+                        "or be a single column"
+                    ) from err
+            weights = weights[~isna(y)]
+        return weights
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        if self.orientation == "horizontal":
+            # error: Argument 1 to "set_xlabel" of "_AxesBase" has incompatible
+            # type "Hashable"; expected "str"
+            ax.set_xlabel(
+                "Frequency"
+                if self.xlabel is None
+                else self.xlabel  # type: ignore[arg-type]
+            )
+            ax.set_ylabel(self.ylabel)  # type: ignore[arg-type]
+        else:
+            ax.set_xlabel(self.xlabel)  # type: ignore[arg-type]
+            ax.set_ylabel(
+                "Frequency"
+                if self.ylabel is None
+                else self.ylabel  # type: ignore[arg-type]
+            )
+
+    @property
+    def orientation(self) -> PlottingOrientation:
+        if self.kwds.get("orientation", None) == "horizontal":
+            return "horizontal"
+        else:
+            return "vertical"
+
+
+class KdePlot(HistPlot):
+    @property
+    def _kind(self) -> Literal["kde"]:
+        return "kde"
+
+    @property
+    def orientation(self) -> Literal["vertical"]:
+        return "vertical"
+
+    def __init__(
+        self, data, bw_method=None, ind=None, *, weights=None, **kwargs
+    ) -> None:
+        # Do not call LinePlot.__init__ which may fill nan
+        MPLPlot.__init__(self, data, **kwargs)  # pylint: disable=non-parent-init-called
+        self.bw_method = bw_method
+        self.ind = ind
+        self.weights = weights
+
+    @staticmethod
+    def _get_ind(y: np.ndarray, ind):
+        if ind is None:
+            # np.nanmax() and np.nanmin() ignores the missing values
+            sample_range = np.nanmax(y) - np.nanmin(y)
+            ind = np.linspace(
+                np.nanmin(y) - 0.5 * sample_range,
+                np.nanmax(y) + 0.5 * sample_range,
+                1000,
+            )
+        elif is_integer(ind):
+            sample_range = np.nanmax(y) - np.nanmin(y)
+            ind = np.linspace(
+                np.nanmin(y) - 0.5 * sample_range,
+                np.nanmax(y) + 0.5 * sample_range,
+                ind,
+            )
+        return ind
+
+    @classmethod
+    # error: Signature of "_plot" incompatible with supertype "MPLPlot"
+    def _plot(  #  type: ignore[override]
+        cls,
+        ax: Axes,
+        y: np.ndarray,
+        style=None,
+        bw_method=None,
+        ind=None,
+        column_num=None,
+        stacking_id: int | None = None,
+        **kwds,
+    ):
+        from scipy.stats import gaussian_kde
+
+        y = remove_na_arraylike(y)
+        gkde = gaussian_kde(y, bw_method=bw_method)
+
+        y = gkde.evaluate(ind)
+        lines = MPLPlot._plot(ax, ind, y, style=style, **kwds)
+        return lines
+
+    def _make_plot_keywords(self, kwds: dict[str, Any], y: np.ndarray) -> None:
+        kwds["bw_method"] = self.bw_method
+        kwds["ind"] = type(self)._get_ind(y, ind=self.ind)
+
+    def _post_plot_logic(self, ax: Axes, data) -> None:
+        ax.set_ylabel("Density")
+
+
+def _grouped_plot(
+    plotf,
+    data: Series | DataFrame,
+    column=None,
+    by=None,
+    numeric_only: bool = True,
+    figsize: tuple[float, float] | None = None,
+    sharex: bool = True,
+    sharey: bool = True,
+    layout=None,
+    rot: float = 0,
+    ax=None,
+    **kwargs,
+):
+    # error: Non-overlapping equality check (left operand type: "Optional[Tuple[float,
+    # float]]", right operand type: "Literal['default']")
+    if figsize == "default":  # type: ignore[comparison-overlap]
+        # allowed to specify mpl default with 'default'
+        raise ValueError(
+            "figsize='default' is no longer supported. "
+            "Specify figure size by tuple instead"
+        )
+
+    grouped = data.groupby(by)
+    if column is not None:
+        grouped = grouped[column]
+
+    naxes = len(grouped)
+    fig, axes = create_subplots(
+        naxes=naxes, figsize=figsize, sharex=sharex, sharey=sharey, ax=ax, layout=layout
+    )
+
+    _axes = flatten_axes(axes)
+
+    for i, (key, group) in enumerate(grouped):
+        ax = _axes[i]
+        if numeric_only and isinstance(group, ABCDataFrame):
+            group = group._get_numeric_data()
+        plotf(group, ax, **kwargs)
+        ax.set_title(pprint_thing(key))
+
+    return fig, axes
+
+
+def _grouped_hist(
+    data: Series | DataFrame,
+    column=None,
+    by=None,
+    ax=None,
+    bins: int = 50,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    sharex: bool = False,
+    sharey: bool = False,
+    rot: float = 90,
+    grid: bool = True,
+    xlabelsize: int | None = None,
+    xrot=None,
+    ylabelsize: int | None = None,
+    yrot=None,
+    legend: bool = False,
+    **kwargs,
+):
+    """
+    Grouped histogram
+
+    Parameters
+    ----------
+    data : Series/DataFrame
+    column : object, optional
+    by : object, optional
+    ax : axes, optional
+    bins : int, default 50
+    figsize : tuple, optional
+    layout : optional
+    sharex : bool, default False
+    sharey : bool, default False
+    rot : float, default 90
+    grid : bool, default True
+    legend: : bool, default False
+    kwargs : dict, keyword arguments passed to matplotlib.Axes.hist
+
+    Returns
+    -------
+    collection of Matplotlib Axes
+    """
+    if legend:
+        assert "label" not in kwargs
+        if data.ndim == 1:
+            kwargs["label"] = data.name
+        elif column is None:
+            kwargs["label"] = data.columns
+        else:
+            kwargs["label"] = column
+
+    def plot_group(group, ax) -> None:
+        ax.hist(group.dropna().values, bins=bins, **kwargs)
+        if legend:
+            ax.legend()
+
+    if xrot is None:
+        xrot = rot
+
+    fig, axes = _grouped_plot(
+        plot_group,
+        data,
+        column=column,
+        by=by,
+        sharex=sharex,
+        sharey=sharey,
+        ax=ax,
+        figsize=figsize,
+        layout=layout,
+        rot=rot,
+    )
+
+    set_ticks_props(
+        axes, xlabelsize=xlabelsize, xrot=xrot, ylabelsize=ylabelsize, yrot=yrot
+    )
+
+    maybe_adjust_figure(
+        fig, bottom=0.15, top=0.9, left=0.1, right=0.9, hspace=0.5, wspace=0.3
+    )
+    return axes
+
+
+def hist_series(
+    self: Series,
+    by=None,
+    ax=None,
+    grid: bool = True,
+    xlabelsize: int | None = None,
+    xrot=None,
+    ylabelsize: int | None = None,
+    yrot=None,
+    figsize: tuple[float, float] | None = None,
+    bins: int = 10,
+    legend: bool = False,
+    **kwds,
+):
+    import matplotlib.pyplot as plt
+
+    if legend and "label" in kwds:
+        raise ValueError("Cannot use both legend and label")
+
+    if by is None:
+        if kwds.get("layout", None) is not None:
+            raise ValueError("The 'layout' keyword is not supported when 'by' is None")
+        # hack until the plotting interface is a bit more unified
+        fig = kwds.pop(
+            "figure", plt.gcf() if plt.get_fignums() else plt.figure(figsize=figsize)
+        )
+        if figsize is not None and tuple(figsize) != tuple(fig.get_size_inches()):
+            fig.set_size_inches(*figsize, forward=True)
+        if ax is None:
+            ax = fig.gca()
+        elif ax.get_figure() != fig:
+            raise AssertionError("passed axis not bound to passed figure")
+        values = self.dropna().values
+        if legend:
+            kwds["label"] = self.name
+        ax.hist(values, bins=bins, **kwds)
+        if legend:
+            ax.legend()
+        ax.grid(grid)
+        axes = np.array([ax])
+
+        # error: Argument 1 to "set_ticks_props" has incompatible type "ndarray[Any,
+        # dtype[Any]]"; expected "Axes | Sequence[Axes]"
+        set_ticks_props(
+            axes,  # type: ignore[arg-type]
+            xlabelsize=xlabelsize,
+            xrot=xrot,
+            ylabelsize=ylabelsize,
+            yrot=yrot,
+        )
+
+    else:
+        if "figure" in kwds:
+            raise ValueError(
+                "Cannot pass 'figure' when using the "
+                "'by' argument, since a new 'Figure' instance will be created"
+            )
+        axes = _grouped_hist(
+            self,
+            by=by,
+            ax=ax,
+            grid=grid,
+            figsize=figsize,
+            bins=bins,
+            xlabelsize=xlabelsize,
+            xrot=xrot,
+            ylabelsize=ylabelsize,
+            yrot=yrot,
+            legend=legend,
+            **kwds,
+        )
+
+    if hasattr(axes, "ndim"):
+        if axes.ndim == 1 and len(axes) == 1:
+            return axes[0]
+    return axes
+
+
+def hist_frame(
+    data: DataFrame,
+    column=None,
+    by=None,
+    grid: bool = True,
+    xlabelsize: int | None = None,
+    xrot=None,
+    ylabelsize: int | None = None,
+    yrot=None,
+    ax=None,
+    sharex: bool = False,
+    sharey: bool = False,
+    figsize: tuple[float, float] | None = None,
+    layout=None,
+    bins: int = 10,
+    legend: bool = False,
+    **kwds,
+):
+    if legend and "label" in kwds:
+        raise ValueError("Cannot use both legend and label")
+    if by is not None:
+        axes = _grouped_hist(
+            data,
+            column=column,
+            by=by,
+            ax=ax,
+            grid=grid,
+            figsize=figsize,
+            sharex=sharex,
+            sharey=sharey,
+            layout=layout,
+            bins=bins,
+            xlabelsize=xlabelsize,
+            xrot=xrot,
+            ylabelsize=ylabelsize,
+            yrot=yrot,
+            legend=legend,
+            **kwds,
+        )
+        return axes
+
+    if column is not None:
+        if not isinstance(column, (list, np.ndarray, ABCIndex)):
+            column = [column]
+        data = data[column]
+    # GH32590
+    data = data.select_dtypes(
+        include=(np.number, "datetime64", "datetimetz"), exclude="timedelta"
+    )
+    naxes = len(data.columns)
+
+    if naxes == 0:
+        raise ValueError(
+            "hist method requires numerical or datetime columns, nothing to plot."
+        )
+
+    fig, axes = create_subplots(
+        naxes=naxes,
+        ax=ax,
+        squeeze=False,
+        sharex=sharex,
+        sharey=sharey,
+        figsize=figsize,
+        layout=layout,
+    )
+    _axes = flatten_axes(axes)
+
+    can_set_label = "label" not in kwds
+
+    for i, col in enumerate(data.columns):
+        ax = _axes[i]
+        if legend and can_set_label:
+            kwds["label"] = col
+        ax.hist(data[col].dropna().values, bins=bins, **kwds)
+        ax.set_title(col)
+        ax.grid(grid)
+        if legend:
+            ax.legend()
+
+    set_ticks_props(
+        axes, xlabelsize=xlabelsize, xrot=xrot, ylabelsize=ylabelsize, yrot=yrot
+    )
+    maybe_adjust_figure(fig, wspace=0.3, hspace=0.3)
+
+    return axes
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/misc.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/misc.py
new file mode 100644
index 0000000000000000000000000000000000000000..1f9212587e05e2e3689b680ff01ae7780230657e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/misc.py
@@ -0,0 +1,481 @@
+from __future__ import annotations
+
+import random
+from typing import TYPE_CHECKING
+
+from matplotlib import patches
+import matplotlib.lines as mlines
+import numpy as np
+
+from pandas.core.dtypes.missing import notna
+
+from pandas.io.formats.printing import pprint_thing
+from pandas.plotting._matplotlib.style import get_standard_colors
+from pandas.plotting._matplotlib.tools import (
+    create_subplots,
+    do_adjust_figure,
+    maybe_adjust_figure,
+    set_ticks_props,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Hashable
+
+    from matplotlib.axes import Axes
+    from matplotlib.figure import Figure
+
+    from pandas import (
+        DataFrame,
+        Index,
+        Series,
+    )
+
+
+def scatter_matrix(
+    frame: DataFrame,
+    alpha: float = 0.5,
+    figsize: tuple[float, float] | None = None,
+    ax=None,
+    grid: bool = False,
+    diagonal: str = "hist",
+    marker: str = ".",
+    density_kwds=None,
+    hist_kwds=None,
+    range_padding: float = 0.05,
+    **kwds,
+):
+    df = frame._get_numeric_data()
+    n = df.columns.size
+    naxes = n * n
+    fig, axes = create_subplots(naxes=naxes, figsize=figsize, ax=ax, squeeze=False)
+
+    # no gaps between subplots
+    maybe_adjust_figure(fig, wspace=0, hspace=0)
+
+    mask = notna(df)
+
+    marker = _get_marker_compat(marker)
+
+    hist_kwds = hist_kwds or {}
+    density_kwds = density_kwds or {}
+
+    # GH 14855
+    kwds.setdefault("edgecolors", "none")
+
+    boundaries_list = []
+    for a in df.columns:
+        values = df[a].values[mask[a].values]
+        rmin_, rmax_ = np.min(values), np.max(values)
+        rdelta_ext = (rmax_ - rmin_) * range_padding / 2
+        boundaries_list.append((rmin_ - rdelta_ext, rmax_ + rdelta_ext))
+
+    for i, a in enumerate(df.columns):
+        for j, b in enumerate(df.columns):
+            ax = axes[i, j]
+
+            if i == j:
+                values = df[a].values[mask[a].values]
+
+                # Deal with the diagonal by drawing a histogram there.
+                if diagonal == "hist":
+                    ax.hist(values, **hist_kwds)
+
+                elif diagonal in ("kde", "density"):
+                    from scipy.stats import gaussian_kde
+
+                    y = values
+                    gkde = gaussian_kde(y)
+                    ind = np.linspace(y.min(), y.max(), 1000)
+                    ax.plot(ind, gkde.evaluate(ind), **density_kwds)
+
+                ax.set_xlim(boundaries_list[i])
+
+            else:
+                common = (mask[a] & mask[b]).values
+
+                ax.scatter(
+                    df[b][common], df[a][common], marker=marker, alpha=alpha, **kwds
+                )
+
+                ax.set_xlim(boundaries_list[j])
+                ax.set_ylim(boundaries_list[i])
+
+            ax.set_xlabel(b)
+            ax.set_ylabel(a)
+
+            if j != 0:
+                ax.yaxis.set_visible(False)
+            if i != n - 1:
+                ax.xaxis.set_visible(False)
+
+    if len(df.columns) > 1:
+        lim1 = boundaries_list[0]
+        locs = axes[0][1].yaxis.get_majorticklocs()
+        locs = locs[(lim1[0] <= locs) & (locs <= lim1[1])]
+        adj = (locs - lim1[0]) / (lim1[1] - lim1[0])
+
+        lim0 = axes[0][0].get_ylim()
+        adj = adj * (lim0[1] - lim0[0]) + lim0[0]
+        axes[0][0].yaxis.set_ticks(adj)
+
+        if np.all(locs == locs.astype(int)):
+            # if all ticks are int
+            locs = locs.astype(int)
+        axes[0][0].yaxis.set_ticklabels(locs)
+
+    set_ticks_props(axes, xlabelsize=8, xrot=90, ylabelsize=8, yrot=0)
+
+    return axes
+
+
+def _get_marker_compat(marker):
+    if marker not in mlines.lineMarkers:
+        return "o"
+    return marker
+
+
+def radviz(
+    frame: DataFrame,
+    class_column,
+    ax: Axes | None = None,
+    color=None,
+    colormap=None,
+    **kwds,
+) -> Axes:
+    import matplotlib.pyplot as plt
+
+    def normalize(series):
+        a = min(series)
+        b = max(series)
+        return (series - a) / (b - a)
+
+    n = len(frame)
+    classes = frame[class_column].drop_duplicates()
+    class_col = frame[class_column]
+    df = frame.drop(class_column, axis=1).apply(normalize)
+
+    if ax is None:
+        ax = plt.gca()
+        ax.set_xlim(-1, 1)
+        ax.set_ylim(-1, 1)
+
+    to_plot: dict[Hashable, list[list]] = {}
+    colors = get_standard_colors(
+        num_colors=len(classes), colormap=colormap, color_type="random", color=color
+    )
+
+    for kls in classes:
+        to_plot[kls] = [[], []]
+
+    m = len(frame.columns) - 1
+    s = np.array(
+        [(np.cos(t), np.sin(t)) for t in [2 * np.pi * (i / m) for i in range(m)]]
+    )
+
+    for i in range(n):
+        row = df.iloc[i].values
+        row_ = np.repeat(np.expand_dims(row, axis=1), 2, axis=1)
+        y = (s * row_).sum(axis=0) / row.sum()
+        kls = class_col.iat[i]
+        to_plot[kls][0].append(y[0])
+        to_plot[kls][1].append(y[1])
+
+    for i, kls in enumerate(classes):
+        ax.scatter(
+            to_plot[kls][0],
+            to_plot[kls][1],
+            color=colors[i],
+            label=pprint_thing(kls),
+            **kwds,
+        )
+    ax.legend()
+
+    ax.add_patch(patches.Circle((0.0, 0.0), radius=1.0, facecolor="none"))
+
+    for xy, name in zip(s, df.columns):
+        ax.add_patch(patches.Circle(xy, radius=0.025, facecolor="gray"))
+
+        if xy[0] < 0.0 and xy[1] < 0.0:
+            ax.text(
+                xy[0] - 0.025, xy[1] - 0.025, name, ha="right", va="top", size="small"
+            )
+        elif xy[0] < 0.0 <= xy[1]:
+            ax.text(
+                xy[0] - 0.025,
+                xy[1] + 0.025,
+                name,
+                ha="right",
+                va="bottom",
+                size="small",
+            )
+        elif xy[1] < 0.0 <= xy[0]:
+            ax.text(
+                xy[0] + 0.025, xy[1] - 0.025, name, ha="left", va="top", size="small"
+            )
+        elif xy[0] >= 0.0 and xy[1] >= 0.0:
+            ax.text(
+                xy[0] + 0.025, xy[1] + 0.025, name, ha="left", va="bottom", size="small"
+            )
+
+    ax.axis("equal")
+    return ax
+
+
+def andrews_curves(
+    frame: DataFrame,
+    class_column,
+    ax: Axes | None = None,
+    samples: int = 200,
+    color=None,
+    colormap=None,
+    **kwds,
+) -> Axes:
+    import matplotlib.pyplot as plt
+
+    def function(amplitudes):
+        def f(t):
+            x1 = amplitudes[0]
+            result = x1 / np.sqrt(2.0)
+
+            # Take the rest of the coefficients and resize them
+            # appropriately. Take a copy of amplitudes as otherwise numpy
+            # deletes the element from amplitudes itself.
+            coeffs = np.delete(np.copy(amplitudes), 0)
+            coeffs = np.resize(coeffs, (int((coeffs.size + 1) / 2), 2))
+
+            # Generate the harmonics and arguments for the sin and cos
+            # functions.
+            harmonics = np.arange(0, coeffs.shape[0]) + 1
+            trig_args = np.outer(harmonics, t)
+
+            result += np.sum(
+                coeffs[:, 0, np.newaxis] * np.sin(trig_args)
+                + coeffs[:, 1, np.newaxis] * np.cos(trig_args),
+                axis=0,
+            )
+            return result
+
+        return f
+
+    n = len(frame)
+    class_col = frame[class_column]
+    classes = frame[class_column].drop_duplicates()
+    df = frame.drop(class_column, axis=1)
+    t = np.linspace(-np.pi, np.pi, samples)
+    used_legends: set[str] = set()
+
+    color_values = get_standard_colors(
+        num_colors=len(classes), colormap=colormap, color_type="random", color=color
+    )
+    colors = dict(zip(classes, color_values))
+    if ax is None:
+        ax = plt.gca()
+        ax.set_xlim(-np.pi, np.pi)
+    for i in range(n):
+        row = df.iloc[i].values
+        f = function(row)
+        y = f(t)
+        kls = class_col.iat[i]
+        label = pprint_thing(kls)
+        if label not in used_legends:
+            used_legends.add(label)
+            ax.plot(t, y, color=colors[kls], label=label, **kwds)
+        else:
+            ax.plot(t, y, color=colors[kls], **kwds)
+
+    ax.legend(loc="upper right")
+    ax.grid()
+    return ax
+
+
+def bootstrap_plot(
+    series: Series,
+    fig: Figure | None = None,
+    size: int = 50,
+    samples: int = 500,
+    **kwds,
+) -> Figure:
+    import matplotlib.pyplot as plt
+
+    # TODO: is the failure mentioned below still relevant?
+    # random.sample(ndarray, int) fails on python 3.3, sigh
+    data = list(series.values)
+    samplings = [random.sample(data, size) for _ in range(samples)]
+
+    means = np.array([np.mean(sampling) for sampling in samplings])
+    medians = np.array([np.median(sampling) for sampling in samplings])
+    midranges = np.array(
+        [(min(sampling) + max(sampling)) * 0.5 for sampling in samplings]
+    )
+    if fig is None:
+        fig = plt.figure()
+    x = list(range(samples))
+    axes = []
+    ax1 = fig.add_subplot(2, 3, 1)
+    ax1.set_xlabel("Sample")
+    axes.append(ax1)
+    ax1.plot(x, means, **kwds)
+    ax2 = fig.add_subplot(2, 3, 2)
+    ax2.set_xlabel("Sample")
+    axes.append(ax2)
+    ax2.plot(x, medians, **kwds)
+    ax3 = fig.add_subplot(2, 3, 3)
+    ax3.set_xlabel("Sample")
+    axes.append(ax3)
+    ax3.plot(x, midranges, **kwds)
+    ax4 = fig.add_subplot(2, 3, 4)
+    ax4.set_xlabel("Mean")
+    axes.append(ax4)
+    ax4.hist(means, **kwds)
+    ax5 = fig.add_subplot(2, 3, 5)
+    ax5.set_xlabel("Median")
+    axes.append(ax5)
+    ax5.hist(medians, **kwds)
+    ax6 = fig.add_subplot(2, 3, 6)
+    ax6.set_xlabel("Midrange")
+    axes.append(ax6)
+    ax6.hist(midranges, **kwds)
+    for axis in axes:
+        plt.setp(axis.get_xticklabels(), fontsize=8)
+        plt.setp(axis.get_yticklabels(), fontsize=8)
+    if do_adjust_figure(fig):
+        plt.tight_layout()
+    return fig
+
+
+def parallel_coordinates(
+    frame: DataFrame,
+    class_column,
+    cols=None,
+    ax: Axes | None = None,
+    color=None,
+    use_columns: bool = False,
+    xticks=None,
+    colormap=None,
+    axvlines: bool = True,
+    axvlines_kwds=None,
+    sort_labels: bool = False,
+    **kwds,
+) -> Axes:
+    import matplotlib.pyplot as plt
+
+    if axvlines_kwds is None:
+        axvlines_kwds = {"linewidth": 1, "color": "black"}
+
+    n = len(frame)
+    classes = frame[class_column].drop_duplicates()
+    class_col = frame[class_column]
+
+    if cols is None:
+        df = frame.drop(class_column, axis=1)
+    else:
+        df = frame[cols]
+
+    used_legends: set[str] = set()
+
+    ncols = len(df.columns)
+
+    # determine values to use for xticks
+    x: list[int] | Index
+    if use_columns is True:
+        if not np.all(np.isreal(list(df.columns))):
+            raise ValueError("Columns must be numeric to be used as xticks")
+        x = df.columns
+    elif xticks is not None:
+        if not np.all(np.isreal(xticks)):
+            raise ValueError("xticks specified must be numeric")
+        if len(xticks) != ncols:
+            raise ValueError("Length of xticks must match number of columns")
+        x = xticks
+    else:
+        x = list(range(ncols))
+
+    if ax is None:
+        ax = plt.gca()
+
+    color_values = get_standard_colors(
+        num_colors=len(classes), colormap=colormap, color_type="random", color=color
+    )
+
+    if sort_labels:
+        classes = sorted(classes)
+        color_values = sorted(color_values)
+    colors = dict(zip(classes, color_values))
+
+    for i in range(n):
+        y = df.iloc[i].values
+        kls = class_col.iat[i]
+        label = pprint_thing(kls)
+        if label not in used_legends:
+            used_legends.add(label)
+            ax.plot(x, y, color=colors[kls], label=label, **kwds)
+        else:
+            ax.plot(x, y, color=colors[kls], **kwds)
+
+    if axvlines:
+        for i in x:
+            ax.axvline(i, **axvlines_kwds)
+
+    ax.set_xticks(x)
+    ax.set_xticklabels(df.columns)
+    ax.set_xlim(x[0], x[-1])
+    ax.legend(loc="upper right")
+    ax.grid()
+    return ax
+
+
+def lag_plot(series: Series, lag: int = 1, ax: Axes | None = None, **kwds) -> Axes:
+    # workaround because `c='b'` is hardcoded in matplotlib's scatter method
+    import matplotlib.pyplot as plt
+
+    kwds.setdefault("c", plt.rcParams["patch.facecolor"])
+
+    data = series.values
+    y1 = data[:-lag]
+    y2 = data[lag:]
+    if ax is None:
+        ax = plt.gca()
+    ax.set_xlabel("y(t)")
+    ax.set_ylabel(f"y(t + {lag})")
+    ax.scatter(y1, y2, **kwds)
+    return ax
+
+
+def autocorrelation_plot(series: Series, ax: Axes | None = None, **kwds) -> Axes:
+    import matplotlib.pyplot as plt
+
+    n = len(series)
+    data = np.asarray(series)
+    if ax is None:
+        ax = plt.gca()
+        ax.set_xlim(1, n)
+        ax.set_ylim(-1.0, 1.0)
+    mean = np.mean(data)
+    c0 = np.sum((data - mean) ** 2) / n
+
+    def r(h):
+        return ((data[: n - h] - mean) * (data[h:] - mean)).sum() / n / c0
+
+    x = np.arange(n) + 1
+    y = [r(loc) for loc in x]
+    z95 = 1.959963984540054
+    z99 = 2.5758293035489004
+    ax.axhline(y=z99 / np.sqrt(n), linestyle="--", color="grey")
+    ax.axhline(y=z95 / np.sqrt(n), color="grey")
+    ax.axhline(y=0.0, color="black")
+    ax.axhline(y=-z95 / np.sqrt(n), color="grey")
+    ax.axhline(y=-z99 / np.sqrt(n), linestyle="--", color="grey")
+    ax.set_xlabel("Lag")
+    ax.set_ylabel("Autocorrelation")
+    ax.plot(x, y, **kwds)
+    if "label" in kwds:
+        ax.legend()
+    ax.grid()
+    return ax
+
+
+def unpack_single_str_list(keys):
+    # GH 42795
+    if isinstance(keys, list) and len(keys) == 1:
+        keys = keys[0]
+    return keys
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/style.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/style.py
new file mode 100644
index 0000000000000000000000000000000000000000..bf4e4be3bfd82e6ce89d526aa0da555f67b9f565
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/style.py
@@ -0,0 +1,278 @@
+from __future__ import annotations
+
+from collections.abc import (
+    Collection,
+    Iterator,
+)
+import itertools
+from typing import (
+    TYPE_CHECKING,
+    cast,
+)
+import warnings
+
+import matplotlib as mpl
+import matplotlib.colors
+import numpy as np
+
+from pandas._typing import MatplotlibColor as Color
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_list_like
+
+import pandas.core.common as com
+
+if TYPE_CHECKING:
+    from matplotlib.colors import Colormap
+
+
+def get_standard_colors(
+    num_colors: int,
+    colormap: Colormap | None = None,
+    color_type: str = "default",
+    color: dict[str, Color] | Color | Collection[Color] | None = None,
+):
+    """
+    Get standard colors based on `colormap`, `color_type` or `color` inputs.
+
+    Parameters
+    ----------
+    num_colors : int
+        Minimum number of colors to be returned.
+        Ignored if `color` is a dictionary.
+    colormap : :py:class:`matplotlib.colors.Colormap`, optional
+        Matplotlib colormap.
+        When provided, the resulting colors will be derived from the colormap.
+    color_type : {"default", "random"}, optional
+        Type of colors to derive. Used if provided `color` and `colormap` are None.
+        Ignored if either `color` or `colormap` are not None.
+    color : dict or str or sequence, optional
+        Color(s) to be used for deriving sequence of colors.
+        Can be either be a dictionary, or a single color (single color string,
+        or sequence of floats representing a single color),
+        or a sequence of colors.
+
+    Returns
+    -------
+    dict or list
+        Standard colors. Can either be a mapping if `color` was a dictionary,
+        or a list of colors with a length of `num_colors` or more.
+
+    Warns
+    -----
+    UserWarning
+        If both `colormap` and `color` are provided.
+        Parameter `color` will override.
+    """
+    if isinstance(color, dict):
+        return color
+
+    colors = _derive_colors(
+        color=color,
+        colormap=colormap,
+        color_type=color_type,
+        num_colors=num_colors,
+    )
+
+    return list(_cycle_colors(colors, num_colors=num_colors))
+
+
+def _derive_colors(
+    *,
+    color: Color | Collection[Color] | None,
+    colormap: str | Colormap | None,
+    color_type: str,
+    num_colors: int,
+) -> list[Color]:
+    """
+    Derive colors from either `colormap`, `color_type` or `color` inputs.
+
+    Get a list of colors either from `colormap`, or from `color`,
+    or from `color_type` (if both `colormap` and `color` are None).
+
+    Parameters
+    ----------
+    color : str or sequence, optional
+        Color(s) to be used for deriving sequence of colors.
+        Can be either be a single color (single color string, or sequence of floats
+        representing a single color), or a sequence of colors.
+    colormap : :py:class:`matplotlib.colors.Colormap`, optional
+        Matplotlib colormap.
+        When provided, the resulting colors will be derived from the colormap.
+    color_type : {"default", "random"}, optional
+        Type of colors to derive. Used if provided `color` and `colormap` are None.
+        Ignored if either `color` or `colormap`` are not None.
+    num_colors : int
+        Number of colors to be extracted.
+
+    Returns
+    -------
+    list
+        List of colors extracted.
+
+    Warns
+    -----
+    UserWarning
+        If both `colormap` and `color` are provided.
+        Parameter `color` will override.
+    """
+    if color is None and colormap is not None:
+        return _get_colors_from_colormap(colormap, num_colors=num_colors)
+    elif color is not None:
+        if colormap is not None:
+            warnings.warn(
+                "'color' and 'colormap' cannot be used simultaneously. Using 'color'",
+                stacklevel=find_stack_level(),
+            )
+        return _get_colors_from_color(color)
+    else:
+        return _get_colors_from_color_type(color_type, num_colors=num_colors)
+
+
+def _cycle_colors(colors: list[Color], num_colors: int) -> Iterator[Color]:
+    """Cycle colors until achieving max of `num_colors` or length of `colors`.
+
+    Extra colors will be ignored by matplotlib if there are more colors
+    than needed and nothing needs to be done here.
+    """
+    max_colors = max(num_colors, len(colors))
+    yield from itertools.islice(itertools.cycle(colors), max_colors)
+
+
+def _get_colors_from_colormap(
+    colormap: str | Colormap,
+    num_colors: int,
+) -> list[Color]:
+    """Get colors from colormap."""
+    cmap = _get_cmap_instance(colormap)
+    return [cmap(num) for num in np.linspace(0, 1, num=num_colors)]
+
+
+def _get_cmap_instance(colormap: str | Colormap) -> Colormap:
+    """Get instance of matplotlib colormap."""
+    if isinstance(colormap, str):
+        cmap = colormap
+        colormap = mpl.colormaps[colormap]
+        if colormap is None:
+            raise ValueError(f"Colormap {cmap} is not recognized")
+    return colormap
+
+
+def _get_colors_from_color(
+    color: Color | Collection[Color],
+) -> list[Color]:
+    """Get colors from user input color."""
+    if len(color) == 0:
+        raise ValueError(f"Invalid color argument: {color}")
+
+    if _is_single_color(color):
+        color = cast(Color, color)
+        return [color]
+
+    color = cast(Collection[Color], color)
+    return list(_gen_list_of_colors_from_iterable(color))
+
+
+def _is_single_color(color: Color | Collection[Color]) -> bool:
+    """Check if `color` is a single color, not a sequence of colors.
+
+    Single color is of these kinds:
+        - Named color "red", "C0", "firebrick"
+        - Alias "g"
+        - Sequence of floats, such as (0.1, 0.2, 0.3) or (0.1, 0.2, 0.3, 0.4).
+
+    See Also
+    --------
+    _is_single_string_color
+    """
+    if isinstance(color, str) and _is_single_string_color(color):
+        # GH #36972
+        return True
+
+    if _is_floats_color(color):
+        return True
+
+    return False
+
+
+def _gen_list_of_colors_from_iterable(color: Collection[Color]) -> Iterator[Color]:
+    """
+    Yield colors from string of several letters or from collection of colors.
+    """
+    for x in color:
+        if _is_single_color(x):
+            yield x
+        else:
+            raise ValueError(f"Invalid color {x}")
+
+
+def _is_floats_color(color: Color | Collection[Color]) -> bool:
+    """Check if color comprises a sequence of floats representing color."""
+    return bool(
+        is_list_like(color)
+        and (len(color) == 3 or len(color) == 4)
+        and all(isinstance(x, (int, float)) for x in color)
+    )
+
+
+def _get_colors_from_color_type(color_type: str, num_colors: int) -> list[Color]:
+    """Get colors from user input color type."""
+    if color_type == "default":
+        return _get_default_colors(num_colors)
+    elif color_type == "random":
+        return _get_random_colors(num_colors)
+    else:
+        raise ValueError("color_type must be either 'default' or 'random'")
+
+
+def _get_default_colors(num_colors: int) -> list[Color]:
+    """Get `num_colors` of default colors from matplotlib rc params."""
+    import matplotlib.pyplot as plt
+
+    colors = [c["color"] for c in plt.rcParams["axes.prop_cycle"]]
+    return colors[0:num_colors]
+
+
+def _get_random_colors(num_colors: int) -> list[Color]:
+    """Get `num_colors` of random colors."""
+    return [_random_color(num) for num in range(num_colors)]
+
+
+def _random_color(column: int) -> list[float]:
+    """Get a random color represented as a list of length 3"""
+    # GH17525 use common._random_state to avoid resetting the seed
+    rs = com.random_state(column)
+    return rs.rand(3).tolist()
+
+
+def _is_single_string_color(color: Color) -> bool:
+    """Check if `color` is a single string color.
+
+    Examples of single string colors:
+        - 'r'
+        - 'g'
+        - 'red'
+        - 'green'
+        - 'C3'
+        - 'firebrick'
+
+    Parameters
+    ----------
+    color : Color
+        Color string or sequence of floats.
+
+    Returns
+    -------
+    bool
+        True if `color` looks like a valid color.
+        False otherwise.
+    """
+    conv = matplotlib.colors.ColorConverter()
+    try:
+        # error: Argument 1 to "to_rgba" of "ColorConverter" has incompatible type
+        # "str | Sequence[float]"; expected "tuple[float, float, float] | ..."
+        conv.to_rgba(color)  # type: ignore[arg-type]
+    except ValueError:
+        return False
+    else:
+        return True
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/timeseries.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/timeseries.py
new file mode 100644
index 0000000000000000000000000000000000000000..accf418526d9be36f6c613ebad312109727648de
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/timeseries.py
@@ -0,0 +1,367 @@
+# TODO: Use the fact that axis can have units to simplify the process
+
+from __future__ import annotations
+
+import functools
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    cast,
+)
+import warnings
+
+import numpy as np
+
+from pandas._libs.tslibs import (
+    BaseOffset,
+    Period,
+    to_offset,
+)
+from pandas._libs.tslibs.dtypes import (
+    OFFSET_TO_PERIOD_FREQSTR,
+    FreqGroup,
+)
+
+from pandas.core.dtypes.generic import (
+    ABCDatetimeIndex,
+    ABCPeriodIndex,
+    ABCTimedeltaIndex,
+)
+
+from pandas.io.formats.printing import pprint_thing
+from pandas.plotting._matplotlib.converter import (
+    TimeSeries_DateFormatter,
+    TimeSeries_DateLocator,
+    TimeSeries_TimedeltaFormatter,
+)
+from pandas.tseries.frequencies import (
+    get_period_alias,
+    is_subperiod,
+    is_superperiod,
+)
+
+if TYPE_CHECKING:
+    from datetime import timedelta
+
+    from matplotlib.axes import Axes
+
+    from pandas._typing import NDFrameT
+
+    from pandas import (
+        DataFrame,
+        DatetimeIndex,
+        Index,
+        PeriodIndex,
+        Series,
+    )
+
+# ---------------------------------------------------------------------
+# Plotting functions and monkey patches
+
+
+def maybe_resample(series: Series, ax: Axes, kwargs: dict[str, Any]):
+    # resample against axes freq if necessary
+
+    if "how" in kwargs:
+        raise ValueError(
+            "'how' is not a valid keyword for plotting functions. If plotting "
+            "multiple objects on shared axes, resample manually first."
+        )
+
+    freq, ax_freq = _get_freq(ax, series)
+
+    if freq is None:  # pragma: no cover
+        raise ValueError("Cannot use dynamic axis without frequency info")
+
+    # Convert DatetimeIndex to PeriodIndex
+    if isinstance(series.index, ABCDatetimeIndex):
+        series = series.to_period(freq=freq)
+
+    if ax_freq is not None and freq != ax_freq:
+        if is_superperiod(freq, ax_freq):  # upsample input
+            series = series.copy()
+            # error: "Index" has no attribute "asfreq"
+            series.index = series.index.asfreq(  # type: ignore[attr-defined]
+                ax_freq, how="s"
+            )
+            freq = ax_freq
+        elif _is_sup(freq, ax_freq):  # one is weekly
+            how = "last"
+            series = getattr(series.resample("D"), how)().dropna()
+            series = getattr(series.resample(ax_freq), how)().dropna()
+            freq = ax_freq
+        elif is_subperiod(freq, ax_freq) or _is_sub(freq, ax_freq):
+            _upsample_others(ax, freq, kwargs)
+        else:  # pragma: no cover
+            raise ValueError("Incompatible frequency conversion")
+    return freq, series
+
+
+def _is_sub(f1: str, f2: str) -> bool:
+    return (f1.startswith("W") and is_subperiod("D", f2)) or (
+        f2.startswith("W") and is_subperiod(f1, "D")
+    )
+
+
+def _is_sup(f1: str, f2: str) -> bool:
+    return (f1.startswith("W") and is_superperiod("D", f2)) or (
+        f2.startswith("W") and is_superperiod(f1, "D")
+    )
+
+
+def _upsample_others(ax: Axes, freq: BaseOffset, kwargs: dict[str, Any]) -> None:
+    legend = ax.get_legend()
+    lines, labels = _replot_ax(ax, freq)
+    _replot_ax(ax, freq)
+
+    other_ax = None
+    if hasattr(ax, "left_ax"):
+        other_ax = ax.left_ax
+    if hasattr(ax, "right_ax"):
+        other_ax = ax.right_ax
+
+    if other_ax is not None:
+        rlines, rlabels = _replot_ax(other_ax, freq)
+        lines.extend(rlines)
+        labels.extend(rlabels)
+
+    if legend is not None and kwargs.get("legend", True) and len(lines) > 0:
+        title: str | None = legend.get_title().get_text()
+        if title == "None":
+            title = None
+        ax.legend(lines, labels, loc="best", title=title)
+
+
+def _replot_ax(ax: Axes, freq: BaseOffset):
+    data = getattr(ax, "_plot_data", None)
+
+    # clear current axes and data
+    # TODO #54485
+    ax._plot_data = []  # type: ignore[attr-defined]
+    ax.clear()
+
+    decorate_axes(ax, freq)
+
+    lines = []
+    labels = []
+    if data is not None:
+        for series, plotf, kwds in data:
+            series = series.copy()
+            idx = series.index.asfreq(freq, how="S")
+            series.index = idx
+            # TODO #54485
+            ax._plot_data.append((series, plotf, kwds))  # type: ignore[attr-defined]
+
+            # for tsplot
+            if isinstance(plotf, str):
+                from pandas.plotting._matplotlib import PLOT_CLASSES
+
+                plotf = PLOT_CLASSES[plotf]._plot
+
+            lines.append(plotf(ax, series.index._mpl_repr(), series.values, **kwds)[0])
+            labels.append(pprint_thing(series.name))
+
+    return lines, labels
+
+
+def decorate_axes(ax: Axes, freq: BaseOffset) -> None:
+    """Initialize axes for time-series plotting"""
+    if not hasattr(ax, "_plot_data"):
+        # TODO #54485
+        ax._plot_data = []  # type: ignore[attr-defined]
+
+    # TODO #54485
+    ax.freq = freq  # type: ignore[attr-defined]
+    xaxis = ax.get_xaxis()
+    # TODO #54485
+    xaxis.freq = freq  # type: ignore[attr-defined]
+
+
+def _get_ax_freq(ax: Axes):
+    """
+    Get the freq attribute of the ax object if set.
+    Also checks shared axes (eg when using secondary yaxis, sharex=True
+    or twinx)
+    """
+    ax_freq = getattr(ax, "freq", None)
+    if ax_freq is None:
+        # check for left/right ax in case of secondary yaxis
+        if hasattr(ax, "left_ax"):
+            ax_freq = getattr(ax.left_ax, "freq", None)
+        elif hasattr(ax, "right_ax"):
+            ax_freq = getattr(ax.right_ax, "freq", None)
+    if ax_freq is None:
+        # check if a shared ax (sharex/twinx) has already freq set
+        shared_axes = ax.get_shared_x_axes().get_siblings(ax)
+        if len(shared_axes) > 1:
+            for shared_ax in shared_axes:
+                ax_freq = getattr(shared_ax, "freq", None)
+                if ax_freq is not None:
+                    break
+    return ax_freq
+
+
+def _get_period_alias(freq: timedelta | BaseOffset | str) -> str | None:
+    if isinstance(freq, BaseOffset):
+        freqstr = freq.name
+    else:
+        freqstr = to_offset(freq, is_period=True).rule_code
+
+    return get_period_alias(freqstr)
+
+
+def _get_freq(ax: Axes, series: Series):
+    # get frequency from data
+    freq = getattr(series.index, "freq", None)
+    if freq is None:
+        freq = getattr(series.index, "inferred_freq", None)
+        freq = to_offset(freq, is_period=True)
+
+    ax_freq = _get_ax_freq(ax)
+
+    # use axes freq if no data freq
+    if freq is None:
+        freq = ax_freq
+
+    # get the period frequency
+    freq = _get_period_alias(freq)
+    return freq, ax_freq
+
+
+def use_dynamic_x(ax: Axes, data: DataFrame | Series) -> bool:
+    freq = _get_index_freq(data.index)
+    ax_freq = _get_ax_freq(ax)
+
+    if freq is None:  # convert irregular if axes has freq info
+        freq = ax_freq
+    # do not use tsplot if irregular was plotted first
+    elif (ax_freq is None) and (len(ax.get_lines()) > 0):
+        return False
+
+    if freq is None:
+        return False
+
+    freq_str = _get_period_alias(freq)
+
+    if freq_str is None:
+        return False
+
+    # FIXME: hack this for 0.10.1, creating more technical debt...sigh
+    if isinstance(data.index, ABCDatetimeIndex):
+        # error: "BaseOffset" has no attribute "_period_dtype_code"
+        freq_str = OFFSET_TO_PERIOD_FREQSTR.get(freq_str, freq_str)
+        base = to_offset(
+            freq_str, is_period=True
+        )._period_dtype_code  # type: ignore[attr-defined]
+        x = data.index
+        if base <= FreqGroup.FR_DAY.value:
+            return x[:1].is_normalized
+        period = Period(x[0], freq_str)
+        assert isinstance(period, Period)
+        return period.to_timestamp().tz_localize(x.tz) == x[0]
+    return True
+
+
+def _get_index_freq(index: Index) -> BaseOffset | None:
+    freq = getattr(index, "freq", None)
+    if freq is None:
+        freq = getattr(index, "inferred_freq", None)
+        if freq == "B":
+            # error: "Index" has no attribute "dayofweek"
+            weekdays = np.unique(index.dayofweek)  # type: ignore[attr-defined]
+            if (5 in weekdays) or (6 in weekdays):
+                freq = None
+
+    freq = to_offset(freq)
+    return freq
+
+
+def maybe_convert_index(ax: Axes, data: NDFrameT) -> NDFrameT:
+    # tsplot converts automatically, but don't want to convert index
+    # over and over for DataFrames
+    if isinstance(data.index, (ABCDatetimeIndex, ABCPeriodIndex)):
+        freq: str | BaseOffset | None = data.index.freq
+
+        if freq is None:
+            # We only get here for DatetimeIndex
+            data.index = cast("DatetimeIndex", data.index)
+            freq = data.index.inferred_freq
+            freq = to_offset(freq)
+
+        if freq is None:
+            freq = _get_ax_freq(ax)
+
+        if freq is None:
+            raise ValueError("Could not get frequency alias for plotting")
+
+        freq_str = _get_period_alias(freq)
+
+        with warnings.catch_warnings():
+            # suppress Period[B] deprecation warning
+            # TODO: need to find an alternative to this before the deprecation
+            #  is enforced!
+            warnings.filterwarnings(
+                "ignore",
+                r"PeriodDtype\[B\] is deprecated",
+                category=FutureWarning,
+            )
+
+            if isinstance(data.index, ABCDatetimeIndex):
+                data = data.tz_localize(None).to_period(freq=freq_str)
+            elif isinstance(data.index, ABCPeriodIndex):
+                data.index = data.index.asfreq(freq=freq_str)
+    return data
+
+
+# Patch methods for subplot.
+
+
+def _format_coord(freq, t, y) -> str:
+    time_period = Period(ordinal=int(t), freq=freq)
+    return f"t = {time_period}  y = {y:8f}"
+
+
+def format_dateaxis(
+    subplot, freq: BaseOffset, index: DatetimeIndex | PeriodIndex
+) -> None:
+    """
+    Pretty-formats the date axis (x-axis).
+
+    Major and minor ticks are automatically set for the frequency of the
+    current underlying series.  As the dynamic mode is activated by
+    default, changing the limits of the x axis will intelligently change
+    the positions of the ticks.
+    """
+    from matplotlib import pylab
+
+    # handle index specific formatting
+    # Note: DatetimeIndex does not use this
+    # interface. DatetimeIndex uses matplotlib.date directly
+    if isinstance(index, ABCPeriodIndex):
+        majlocator = TimeSeries_DateLocator(
+            freq, dynamic_mode=True, minor_locator=False, plot_obj=subplot
+        )
+        minlocator = TimeSeries_DateLocator(
+            freq, dynamic_mode=True, minor_locator=True, plot_obj=subplot
+        )
+        subplot.xaxis.set_major_locator(majlocator)
+        subplot.xaxis.set_minor_locator(minlocator)
+
+        majformatter = TimeSeries_DateFormatter(
+            freq, dynamic_mode=True, minor_locator=False, plot_obj=subplot
+        )
+        minformatter = TimeSeries_DateFormatter(
+            freq, dynamic_mode=True, minor_locator=True, plot_obj=subplot
+        )
+        subplot.xaxis.set_major_formatter(majformatter)
+        subplot.xaxis.set_minor_formatter(minformatter)
+
+        # x and y coord info
+        subplot.format_coord = functools.partial(_format_coord, freq)
+
+    elif isinstance(index, ABCTimedeltaIndex):
+        subplot.xaxis.set_major_formatter(TimeSeries_TimedeltaFormatter())
+    else:
+        raise TypeError("index type not supported")
+
+    pylab.draw_if_interactive()
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/tools.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/tools.py
new file mode 100644
index 0000000000000000000000000000000000000000..98441c5afbaa47bfdfd7db27f33ef91c90332088
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_matplotlib/tools.py
@@ -0,0 +1,492 @@
+# being a bit too dynamic
+from __future__ import annotations
+
+from math import ceil
+from typing import TYPE_CHECKING
+import warnings
+
+from matplotlib import ticker
+import matplotlib.table
+import numpy as np
+
+from pandas.util._exceptions import find_stack_level
+
+from pandas.core.dtypes.common import is_list_like
+from pandas.core.dtypes.generic import (
+    ABCDataFrame,
+    ABCIndex,
+    ABCSeries,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Iterable,
+        Sequence,
+    )
+
+    from matplotlib.axes import Axes
+    from matplotlib.axis import Axis
+    from matplotlib.figure import Figure
+    from matplotlib.lines import Line2D
+    from matplotlib.table import Table
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+def do_adjust_figure(fig: Figure) -> bool:
+    """Whether fig has constrained_layout enabled."""
+    if not hasattr(fig, "get_constrained_layout"):
+        return False
+    return not fig.get_constrained_layout()
+
+
+def maybe_adjust_figure(fig: Figure, *args, **kwargs) -> None:
+    """Call fig.subplots_adjust unless fig has constrained_layout enabled."""
+    if do_adjust_figure(fig):
+        fig.subplots_adjust(*args, **kwargs)
+
+
+def format_date_labels(ax: Axes, rot) -> None:
+    # mini version of autofmt_xdate
+    for label in ax.get_xticklabels():
+        label.set_horizontalalignment("right")
+        label.set_rotation(rot)
+    fig = ax.get_figure()
+    if fig is not None:
+        # should always be a Figure but can technically be None
+        maybe_adjust_figure(fig, bottom=0.2)  # type: ignore[arg-type]
+
+
+def table(
+    ax, data: DataFrame | Series, rowLabels=None, colLabels=None, **kwargs
+) -> Table:
+    if isinstance(data, ABCSeries):
+        data = data.to_frame()
+    elif isinstance(data, ABCDataFrame):
+        pass
+    else:
+        raise ValueError("Input data must be DataFrame or Series")
+
+    if rowLabels is None:
+        rowLabels = data.index
+
+    if colLabels is None:
+        colLabels = data.columns
+
+    cellText = data.values
+
+    # error: Argument "cellText" to "table" has incompatible type "ndarray[Any,
+    # Any]"; expected "Sequence[Sequence[str]] | None"
+    return matplotlib.table.table(
+        ax,
+        cellText=cellText,  # type: ignore[arg-type]
+        rowLabels=rowLabels,
+        colLabels=colLabels,
+        **kwargs,
+    )
+
+
+def _get_layout(
+    nplots: int,
+    layout: tuple[int, int] | None = None,
+    layout_type: str = "box",
+) -> tuple[int, int]:
+    if layout is not None:
+        if not isinstance(layout, (tuple, list)) or len(layout) != 2:
+            raise ValueError("Layout must be a tuple of (rows, columns)")
+
+        nrows, ncols = layout
+
+        if nrows == -1 and ncols > 0:
+            layout = nrows, ncols = (ceil(nplots / ncols), ncols)
+        elif ncols == -1 and nrows > 0:
+            layout = nrows, ncols = (nrows, ceil(nplots / nrows))
+        elif ncols <= 0 and nrows <= 0:
+            msg = "At least one dimension of layout must be positive"
+            raise ValueError(msg)
+
+        if nrows * ncols < nplots:
+            raise ValueError(
+                f"Layout of {nrows}x{ncols} must be larger than required size {nplots}"
+            )
+
+        return layout
+
+    if layout_type == "single":
+        return (1, 1)
+    elif layout_type == "horizontal":
+        return (1, nplots)
+    elif layout_type == "vertical":
+        return (nplots, 1)
+
+    layouts = {1: (1, 1), 2: (1, 2), 3: (2, 2), 4: (2, 2)}
+    try:
+        return layouts[nplots]
+    except KeyError:
+        k = 1
+        while k**2 < nplots:
+            k += 1
+
+        if (k - 1) * k >= nplots:
+            return k, (k - 1)
+        else:
+            return k, k
+
+
+# copied from matplotlib/pyplot.py and modified for pandas.plotting
+
+
+def create_subplots(
+    naxes: int,
+    sharex: bool = False,
+    sharey: bool = False,
+    squeeze: bool = True,
+    subplot_kw=None,
+    ax=None,
+    layout=None,
+    layout_type: str = "box",
+    **fig_kw,
+):
+    """
+    Create a figure with a set of subplots already made.
+
+    This utility wrapper makes it convenient to create common layouts of
+    subplots, including the enclosing figure object, in a single call.
+
+    Parameters
+    ----------
+    naxes : int
+      Number of required axes. Exceeded axes are set invisible. Default is
+      nrows * ncols.
+
+    sharex : bool
+      If True, the X axis will be shared amongst all subplots.
+
+    sharey : bool
+      If True, the Y axis will be shared amongst all subplots.
+
+    squeeze : bool
+
+      If True, extra dimensions are squeezed out from the returned axis object:
+        - if only one subplot is constructed (nrows=ncols=1), the resulting
+        single Axis object is returned as a scalar.
+        - for Nx1 or 1xN subplots, the returned object is a 1-d numpy object
+        array of Axis objects are returned as numpy 1-d arrays.
+        - for NxM subplots with N>1 and M>1 are returned as a 2d array.
+
+      If False, no squeezing is done: the returned axis object is always
+      a 2-d array containing Axis instances, even if it ends up being 1x1.
+
+    subplot_kw : dict
+      Dict with keywords passed to the add_subplot() call used to create each
+      subplots.
+
+    ax : Matplotlib axis object, optional
+
+    layout : tuple
+      Number of rows and columns of the subplot grid.
+      If not specified, calculated from naxes and layout_type
+
+    layout_type : {'box', 'horizontal', 'vertical'}, default 'box'
+      Specify how to layout the subplot grid.
+
+    fig_kw : Other keyword arguments to be passed to the figure() call.
+        Note that all keywords not recognized above will be
+        automatically included here.
+
+    Returns
+    -------
+    fig, ax : tuple
+      - fig is the Matplotlib Figure object
+      - ax can be either a single axis object or an array of axis objects if
+      more than one subplot was created.  The dimensions of the resulting array
+      can be controlled with the squeeze keyword, see above.
+
+    Examples
+    --------
+    x = np.linspace(0, 2*np.pi, 400)
+    y = np.sin(x**2)
+
+    # Just a figure and one subplot
+    f, ax = plt.subplots()
+    ax.plot(x, y)
+    ax.set_title('Simple plot')
+
+    # Two subplots, unpack the output array immediately
+    f, (ax1, ax2) = plt.subplots(1, 2, sharey=True)
+    ax1.plot(x, y)
+    ax1.set_title('Sharing Y axis')
+    ax2.scatter(x, y)
+
+    # Four polar axes
+    plt.subplots(2, 2, subplot_kw=dict(polar=True))
+    """
+    import matplotlib.pyplot as plt
+
+    if subplot_kw is None:
+        subplot_kw = {}
+
+    if ax is None:
+        fig = plt.figure(**fig_kw)
+    else:
+        if is_list_like(ax):
+            if squeeze:
+                ax = flatten_axes(ax)
+            if layout is not None:
+                warnings.warn(
+                    "When passing multiple axes, layout keyword is ignored.",
+                    UserWarning,
+                    stacklevel=find_stack_level(),
+                )
+            if sharex or sharey:
+                warnings.warn(
+                    "When passing multiple axes, sharex and sharey "
+                    "are ignored. These settings must be specified when creating axes.",
+                    UserWarning,
+                    stacklevel=find_stack_level(),
+                )
+            if ax.size == naxes:
+                fig = ax.flat[0].get_figure()
+                return fig, ax
+            else:
+                raise ValueError(
+                    f"The number of passed axes must be {naxes}, the "
+                    "same as the output plot"
+                )
+
+        fig = ax.get_figure()
+        # if ax is passed and a number of subplots is 1, return ax as it is
+        if naxes == 1:
+            if squeeze:
+                return fig, ax
+            else:
+                return fig, flatten_axes(ax)
+        else:
+            warnings.warn(
+                "To output multiple subplots, the figure containing "
+                "the passed axes is being cleared.",
+                UserWarning,
+                stacklevel=find_stack_level(),
+            )
+            fig.clear()
+
+    nrows, ncols = _get_layout(naxes, layout=layout, layout_type=layout_type)
+    nplots = nrows * ncols
+
+    # Create empty object array to hold all axes.  It's easiest to make it 1-d
+    # so we can just append subplots upon creation, and then
+    axarr = np.empty(nplots, dtype=object)
+
+    # Create first subplot separately, so we can share it if requested
+    ax0 = fig.add_subplot(nrows, ncols, 1, **subplot_kw)
+
+    if sharex:
+        subplot_kw["sharex"] = ax0
+    if sharey:
+        subplot_kw["sharey"] = ax0
+    axarr[0] = ax0
+
+    # Note off-by-one counting because add_subplot uses the MATLAB 1-based
+    # convention.
+    for i in range(1, nplots):
+        kwds = subplot_kw.copy()
+        # Set sharex and sharey to None for blank/dummy axes, these can
+        # interfere with proper axis limits on the visible axes if
+        # they share axes e.g. issue #7528
+        if i >= naxes:
+            kwds["sharex"] = None
+            kwds["sharey"] = None
+        ax = fig.add_subplot(nrows, ncols, i + 1, **kwds)
+        axarr[i] = ax
+
+    if naxes != nplots:
+        for ax in axarr[naxes:]:
+            ax.set_visible(False)
+
+    handle_shared_axes(axarr, nplots, naxes, nrows, ncols, sharex, sharey)
+
+    if squeeze:
+        # Reshape the array to have the final desired dimension (nrow,ncol),
+        # though discarding unneeded dimensions that equal 1.  If we only have
+        # one subplot, just return it instead of a 1-element array.
+        if nplots == 1:
+            axes = axarr[0]
+        else:
+            axes = axarr.reshape(nrows, ncols).squeeze()
+    else:
+        # returned axis array will be always 2-d, even if nrows=ncols=1
+        axes = axarr.reshape(nrows, ncols)
+
+    return fig, axes
+
+
+def _remove_labels_from_axis(axis: Axis) -> None:
+    for t in axis.get_majorticklabels():
+        t.set_visible(False)
+
+    # set_visible will not be effective if
+    # minor axis has NullLocator and NullFormatter (default)
+    if isinstance(axis.get_minor_locator(), ticker.NullLocator):
+        axis.set_minor_locator(ticker.AutoLocator())
+    if isinstance(axis.get_minor_formatter(), ticker.NullFormatter):
+        axis.set_minor_formatter(ticker.FormatStrFormatter(""))
+    for t in axis.get_minorticklabels():
+        t.set_visible(False)
+
+    axis.get_label().set_visible(False)
+
+
+def _has_externally_shared_axis(ax1: Axes, compare_axis: str) -> bool:
+    """
+    Return whether an axis is externally shared.
+
+    Parameters
+    ----------
+    ax1 : matplotlib.axes.Axes
+        Axis to query.
+    compare_axis : str
+        `"x"` or `"y"` according to whether the X-axis or Y-axis is being
+        compared.
+
+    Returns
+    -------
+    bool
+        `True` if the axis is externally shared. Otherwise `False`.
+
+    Notes
+    -----
+    If two axes with different positions are sharing an axis, they can be
+    referred to as *externally* sharing the common axis.
+
+    If two axes sharing an axis also have the same position, they can be
+    referred to as *internally* sharing the common axis (a.k.a twinning).
+
+    _handle_shared_axes() is only interested in axes externally sharing an
+    axis, regardless of whether either of the axes is also internally sharing
+    with a third axis.
+    """
+    if compare_axis == "x":
+        axes = ax1.get_shared_x_axes()
+    elif compare_axis == "y":
+        axes = ax1.get_shared_y_axes()
+    else:
+        raise ValueError(
+            "_has_externally_shared_axis() needs 'x' or 'y' as a second parameter"
+        )
+
+    axes_siblings = axes.get_siblings(ax1)
+
+    # Retain ax1 and any of its siblings which aren't in the same position as it
+    ax1_points = ax1.get_position().get_points()
+
+    for ax2 in axes_siblings:
+        if not np.array_equal(ax1_points, ax2.get_position().get_points()):
+            return True
+
+    return False
+
+
+def handle_shared_axes(
+    axarr: Iterable[Axes],
+    nplots: int,
+    naxes: int,
+    nrows: int,
+    ncols: int,
+    sharex: bool,
+    sharey: bool,
+) -> None:
+    if nplots > 1:
+        row_num = lambda x: x.get_subplotspec().rowspan.start
+        col_num = lambda x: x.get_subplotspec().colspan.start
+
+        is_first_col = lambda x: x.get_subplotspec().is_first_col()
+
+        if nrows > 1:
+            try:
+                # first find out the ax layout,
+                # so that we can correctly handle 'gaps"
+                layout = np.zeros((nrows + 1, ncols + 1), dtype=np.bool_)
+                for ax in axarr:
+                    layout[row_num(ax), col_num(ax)] = ax.get_visible()
+
+                for ax in axarr:
+                    # only the last row of subplots should get x labels -> all
+                    # other off layout handles the case that the subplot is
+                    # the last in the column, because below is no subplot/gap.
+                    if not layout[row_num(ax) + 1, col_num(ax)]:
+                        continue
+                    if sharex or _has_externally_shared_axis(ax, "x"):
+                        _remove_labels_from_axis(ax.xaxis)
+
+            except IndexError:
+                # if gridspec is used, ax.rowNum and ax.colNum may different
+                # from layout shape. in this case, use last_row logic
+                is_last_row = lambda x: x.get_subplotspec().is_last_row()
+                for ax in axarr:
+                    if is_last_row(ax):
+                        continue
+                    if sharex or _has_externally_shared_axis(ax, "x"):
+                        _remove_labels_from_axis(ax.xaxis)
+
+        if ncols > 1:
+            for ax in axarr:
+                # only the first column should get y labels -> set all other to
+                # off as we only have labels in the first column and we always
+                # have a subplot there, we can skip the layout test
+                if is_first_col(ax):
+                    continue
+                if sharey or _has_externally_shared_axis(ax, "y"):
+                    _remove_labels_from_axis(ax.yaxis)
+
+
+def flatten_axes(axes: Axes | Sequence[Axes]) -> np.ndarray:
+    if not is_list_like(axes):
+        return np.array([axes])
+    elif isinstance(axes, (np.ndarray, ABCIndex)):
+        return np.asarray(axes).ravel()
+    return np.array(axes)
+
+
+def set_ticks_props(
+    axes: Axes | Sequence[Axes],
+    xlabelsize: int | None = None,
+    xrot=None,
+    ylabelsize: int | None = None,
+    yrot=None,
+):
+    import matplotlib.pyplot as plt
+
+    for ax in flatten_axes(axes):
+        if xlabelsize is not None:
+            plt.setp(ax.get_xticklabels(), fontsize=xlabelsize)
+        if xrot is not None:
+            plt.setp(ax.get_xticklabels(), rotation=xrot)
+        if ylabelsize is not None:
+            plt.setp(ax.get_yticklabels(), fontsize=ylabelsize)
+        if yrot is not None:
+            plt.setp(ax.get_yticklabels(), rotation=yrot)
+    return axes
+
+
+def get_all_lines(ax: Axes) -> list[Line2D]:
+    lines = ax.get_lines()
+
+    if hasattr(ax, "right_ax"):
+        lines += ax.right_ax.get_lines()
+
+    if hasattr(ax, "left_ax"):
+        lines += ax.left_ax.get_lines()
+
+    return lines
+
+
+def get_xlim(lines: Iterable[Line2D]) -> tuple[float, float]:
+    left, right = np.inf, -np.inf
+    for line in lines:
+        x = line.get_xdata(orig=False)
+        left = min(np.nanmin(x), left)
+        right = max(np.nanmax(x), right)
+    return left, right
diff --git a/.venv/lib/python3.13/site-packages/pandas/plotting/_misc.py b/.venv/lib/python3.13/site-packages/pandas/plotting/_misc.py
new file mode 100644
index 0000000000000000000000000000000000000000..18db460d388a4b748f91282ae42875206ba36cc6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/plotting/_misc.py
@@ -0,0 +1,688 @@
+from __future__ import annotations
+
+from contextlib import contextmanager
+from typing import (
+    TYPE_CHECKING,
+    Any,
+)
+
+from pandas.plotting._core import _get_plot_backend
+
+if TYPE_CHECKING:
+    from collections.abc import (
+        Generator,
+        Mapping,
+    )
+
+    from matplotlib.axes import Axes
+    from matplotlib.colors import Colormap
+    from matplotlib.figure import Figure
+    from matplotlib.table import Table
+    import numpy as np
+
+    from pandas import (
+        DataFrame,
+        Series,
+    )
+
+
+def table(ax: Axes, data: DataFrame | Series, **kwargs) -> Table:
+    """
+    Helper function to convert DataFrame and Series to matplotlib.table.
+
+    Parameters
+    ----------
+    ax : Matplotlib axes object
+    data : DataFrame or Series
+        Data for table contents.
+    **kwargs
+        Keyword arguments to be passed to matplotlib.table.table.
+        If `rowLabels` or `colLabels` is not specified, data index or column
+        name will be used.
+
+    Returns
+    -------
+    matplotlib table object
+
+    Examples
+    --------
+
+    .. plot::
+            :context: close-figs
+
+            >>> import matplotlib.pyplot as plt
+            >>> df = pd.DataFrame({'A': [1, 2], 'B': [3, 4]})
+            >>> fix, ax = plt.subplots()
+            >>> ax.axis('off')
+            (0.0, 1.0, 0.0, 1.0)
+            >>> table = pd.plotting.table(ax, df, loc='center',
+            ...                           cellLoc='center', colWidths=list([.2, .2]))
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.table(
+        ax=ax, data=data, rowLabels=None, colLabels=None, **kwargs
+    )
+
+
+def register() -> None:
+    """
+    Register pandas formatters and converters with matplotlib.
+
+    This function modifies the global ``matplotlib.units.registry``
+    dictionary. pandas adds custom converters for
+
+    * pd.Timestamp
+    * pd.Period
+    * np.datetime64
+    * datetime.datetime
+    * datetime.date
+    * datetime.time
+
+    See Also
+    --------
+    deregister_matplotlib_converters : Remove pandas formatters and converters.
+
+    Examples
+    --------
+    .. plot::
+       :context: close-figs
+
+        The following line is done automatically by pandas so
+        the plot can be rendered:
+
+        >>> pd.plotting.register_matplotlib_converters()
+
+        >>> df = pd.DataFrame({'ts': pd.period_range('2020', periods=2, freq='M'),
+        ...                    'y': [1, 2]
+        ...                    })
+        >>> plot = df.plot.line(x='ts', y='y')
+
+    Unsetting the register manually an error will be raised:
+
+    >>> pd.set_option("plotting.matplotlib.register_converters",
+    ...               False)  # doctest: +SKIP
+    >>> df.plot.line(x='ts', y='y')  # doctest: +SKIP
+    Traceback (most recent call last):
+    TypeError: float() argument must be a string or a real number, not 'Period'
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    plot_backend.register()
+
+
+def deregister() -> None:
+    """
+    Remove pandas formatters and converters.
+
+    Removes the custom converters added by :func:`register`. This
+    attempts to set the state of the registry back to the state before
+    pandas registered its own units. Converters for pandas' own types like
+    Timestamp and Period are removed completely. Converters for types
+    pandas overwrites, like ``datetime.datetime``, are restored to their
+    original value.
+
+    See Also
+    --------
+    register_matplotlib_converters : Register pandas formatters and converters
+        with matplotlib.
+
+    Examples
+    --------
+    .. plot::
+       :context: close-figs
+
+        The following line is done automatically by pandas so
+        the plot can be rendered:
+
+        >>> pd.plotting.register_matplotlib_converters()
+
+        >>> df = pd.DataFrame({'ts': pd.period_range('2020', periods=2, freq='M'),
+        ...                    'y': [1, 2]
+        ...                    })
+        >>> plot = df.plot.line(x='ts', y='y')
+
+    Unsetting the register manually an error will be raised:
+
+    >>> pd.set_option("plotting.matplotlib.register_converters",
+    ...               False)  # doctest: +SKIP
+    >>> df.plot.line(x='ts', y='y')  # doctest: +SKIP
+    Traceback (most recent call last):
+    TypeError: float() argument must be a string or a real number, not 'Period'
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    plot_backend.deregister()
+
+
+def scatter_matrix(
+    frame: DataFrame,
+    alpha: float = 0.5,
+    figsize: tuple[float, float] | None = None,
+    ax: Axes | None = None,
+    grid: bool = False,
+    diagonal: str = "hist",
+    marker: str = ".",
+    density_kwds: Mapping[str, Any] | None = None,
+    hist_kwds: Mapping[str, Any] | None = None,
+    range_padding: float = 0.05,
+    **kwargs,
+) -> np.ndarray:
+    """
+    Draw a matrix of scatter plots.
+
+    Parameters
+    ----------
+    frame : DataFrame
+    alpha : float, optional
+        Amount of transparency applied.
+    figsize : (float,float), optional
+        A tuple (width, height) in inches.
+    ax : Matplotlib axis object, optional
+    grid : bool, optional
+        Setting this to True will show the grid.
+    diagonal : {'hist', 'kde'}
+        Pick between 'kde' and 'hist' for either Kernel Density Estimation or
+        Histogram plot in the diagonal.
+    marker : str, optional
+        Matplotlib marker type, default '.'.
+    density_kwds : keywords
+        Keyword arguments to be passed to kernel density estimate plot.
+    hist_kwds : keywords
+        Keyword arguments to be passed to hist function.
+    range_padding : float, default 0.05
+        Relative extension of axis range in x and y with respect to
+        (x_max - x_min) or (y_max - y_min).
+    **kwargs
+        Keyword arguments to be passed to scatter function.
+
+    Returns
+    -------
+    numpy.ndarray
+        A matrix of scatter plots.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.DataFrame(np.random.randn(1000, 4), columns=['A','B','C','D'])
+        >>> pd.plotting.scatter_matrix(df, alpha=0.2)
+        array([[, ,
+                , ],
+               [, ,
+                , ],
+               [, ,
+                , ],
+               [, ,
+                , ]],
+              dtype=object)
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.scatter_matrix(
+        frame=frame,
+        alpha=alpha,
+        figsize=figsize,
+        ax=ax,
+        grid=grid,
+        diagonal=diagonal,
+        marker=marker,
+        density_kwds=density_kwds,
+        hist_kwds=hist_kwds,
+        range_padding=range_padding,
+        **kwargs,
+    )
+
+
+def radviz(
+    frame: DataFrame,
+    class_column: str,
+    ax: Axes | None = None,
+    color: list[str] | tuple[str, ...] | None = None,
+    colormap: Colormap | str | None = None,
+    **kwds,
+) -> Axes:
+    """
+    Plot a multidimensional dataset in 2D.
+
+    Each Series in the DataFrame is represented as a evenly distributed
+    slice on a circle. Each data point is rendered in the circle according to
+    the value on each Series. Highly correlated `Series` in the `DataFrame`
+    are placed closer on the unit circle.
+
+    RadViz allow to project a N-dimensional data set into a 2D space where the
+    influence of each dimension can be interpreted as a balance between the
+    influence of all dimensions.
+
+    More info available at the `original article
+    `_
+    describing RadViz.
+
+    Parameters
+    ----------
+    frame : `DataFrame`
+        Object holding the data.
+    class_column : str
+        Column name containing the name of the data point category.
+    ax : :class:`matplotlib.axes.Axes`, optional
+        A plot instance to which to add the information.
+    color : list[str] or tuple[str], optional
+        Assign a color to each category. Example: ['blue', 'green'].
+    colormap : str or :class:`matplotlib.colors.Colormap`, default None
+        Colormap to select colors from. If string, load colormap with that
+        name from matplotlib.
+    **kwds
+        Options to pass to matplotlib scatter plotting method.
+
+    Returns
+    -------
+    :class:`matplotlib.axes.Axes`
+
+    See Also
+    --------
+    pandas.plotting.andrews_curves : Plot clustering visualization.
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.DataFrame(
+        ...     {
+        ...         'SepalLength': [6.5, 7.7, 5.1, 5.8, 7.6, 5.0, 5.4, 4.6, 6.7, 4.6],
+        ...         'SepalWidth': [3.0, 3.8, 3.8, 2.7, 3.0, 2.3, 3.0, 3.2, 3.3, 3.6],
+        ...         'PetalLength': [5.5, 6.7, 1.9, 5.1, 6.6, 3.3, 4.5, 1.4, 5.7, 1.0],
+        ...         'PetalWidth': [1.8, 2.2, 0.4, 1.9, 2.1, 1.0, 1.5, 0.2, 2.1, 0.2],
+        ...         'Category': [
+        ...             'virginica',
+        ...             'virginica',
+        ...             'setosa',
+        ...             'virginica',
+        ...             'virginica',
+        ...             'versicolor',
+        ...             'versicolor',
+        ...             'setosa',
+        ...             'virginica',
+        ...             'setosa'
+        ...         ]
+        ...     }
+        ... )
+        >>> pd.plotting.radviz(df, 'Category')  # doctest: +SKIP
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.radviz(
+        frame=frame,
+        class_column=class_column,
+        ax=ax,
+        color=color,
+        colormap=colormap,
+        **kwds,
+    )
+
+
+def andrews_curves(
+    frame: DataFrame,
+    class_column: str,
+    ax: Axes | None = None,
+    samples: int = 200,
+    color: list[str] | tuple[str, ...] | None = None,
+    colormap: Colormap | str | None = None,
+    **kwargs,
+) -> Axes:
+    """
+    Generate a matplotlib plot for visualizing clusters of multivariate data.
+
+    Andrews curves have the functional form:
+
+    .. math::
+        f(t) = \\frac{x_1}{\\sqrt{2}} + x_2 \\sin(t) + x_3 \\cos(t) +
+        x_4 \\sin(2t) + x_5 \\cos(2t) + \\cdots
+
+    Where :math:`x` coefficients correspond to the values of each dimension
+    and :math:`t` is linearly spaced between :math:`-\\pi` and :math:`+\\pi`.
+    Each row of frame then corresponds to a single curve.
+
+    Parameters
+    ----------
+    frame : DataFrame
+        Data to be plotted, preferably normalized to (0.0, 1.0).
+    class_column : label
+        Name of the column containing class names.
+    ax : axes object, default None
+        Axes to use.
+    samples : int
+        Number of points to plot in each curve.
+    color : str, list[str] or tuple[str], optional
+        Colors to use for the different classes. Colors can be strings
+        or 3-element floating point RGB values.
+    colormap : str or matplotlib colormap object, default None
+        Colormap to select colors from. If a string, load colormap with that
+        name from matplotlib.
+    **kwargs
+        Options to pass to matplotlib plotting method.
+
+    Returns
+    -------
+    :class:`matplotlib.axes.Axes`
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.read_csv(
+        ...     'https://raw.githubusercontent.com/pandas-dev/'
+        ...     'pandas/main/pandas/tests/io/data/csv/iris.csv'
+        ... )
+        >>> pd.plotting.andrews_curves(df, 'Name')  # doctest: +SKIP
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.andrews_curves(
+        frame=frame,
+        class_column=class_column,
+        ax=ax,
+        samples=samples,
+        color=color,
+        colormap=colormap,
+        **kwargs,
+    )
+
+
+def bootstrap_plot(
+    series: Series,
+    fig: Figure | None = None,
+    size: int = 50,
+    samples: int = 500,
+    **kwds,
+) -> Figure:
+    """
+    Bootstrap plot on mean, median and mid-range statistics.
+
+    The bootstrap plot is used to estimate the uncertainty of a statistic
+    by relying on random sampling with replacement [1]_. This function will
+    generate bootstrapping plots for mean, median and mid-range statistics
+    for the given number of samples of the given size.
+
+    .. [1] "Bootstrapping (statistics)" in \
+    https://en.wikipedia.org/wiki/Bootstrapping_%28statistics%29
+
+    Parameters
+    ----------
+    series : pandas.Series
+        Series from where to get the samplings for the bootstrapping.
+    fig : matplotlib.figure.Figure, default None
+        If given, it will use the `fig` reference for plotting instead of
+        creating a new one with default parameters.
+    size : int, default 50
+        Number of data points to consider during each sampling. It must be
+        less than or equal to the length of the `series`.
+    samples : int, default 500
+        Number of times the bootstrap procedure is performed.
+    **kwds
+        Options to pass to matplotlib plotting method.
+
+    Returns
+    -------
+    matplotlib.figure.Figure
+        Matplotlib figure.
+
+    See Also
+    --------
+    pandas.DataFrame.plot : Basic plotting for DataFrame objects.
+    pandas.Series.plot : Basic plotting for Series objects.
+
+    Examples
+    --------
+    This example draws a basic bootstrap plot for a Series.
+
+    .. plot::
+        :context: close-figs
+
+        >>> s = pd.Series(np.random.uniform(size=100))
+        >>> pd.plotting.bootstrap_plot(s)  # doctest: +SKIP
+        

+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.bootstrap_plot(
+        series=series, fig=fig, size=size, samples=samples, **kwds
+    )
+
+
+def parallel_coordinates(
+    frame: DataFrame,
+    class_column: str,
+    cols: list[str] | None = None,
+    ax: Axes | None = None,
+    color: list[str] | tuple[str, ...] | None = None,
+    use_columns: bool = False,
+    xticks: list | tuple | None = None,
+    colormap: Colormap | str | None = None,
+    axvlines: bool = True,
+    axvlines_kwds: Mapping[str, Any] | None = None,
+    sort_labels: bool = False,
+    **kwargs,
+) -> Axes:
+    """
+    Parallel coordinates plotting.
+
+    Parameters
+    ----------
+    frame : DataFrame
+    class_column : str
+        Column name containing class names.
+    cols : list, optional
+        A list of column names to use.
+    ax : matplotlib.axis, optional
+        Matplotlib axis object.
+    color : list or tuple, optional
+        Colors to use for the different classes.
+    use_columns : bool, optional
+        If true, columns will be used as xticks.
+    xticks : list or tuple, optional
+        A list of values to use for xticks.
+    colormap : str or matplotlib colormap, default None
+        Colormap to use for line colors.
+    axvlines : bool, optional
+        If true, vertical lines will be added at each xtick.
+    axvlines_kwds : keywords, optional
+        Options to be passed to axvline method for vertical lines.
+    sort_labels : bool, default False
+        Sort class_column labels, useful when assigning colors.
+    **kwargs
+        Options to pass to matplotlib plotting method.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+
+    Examples
+    --------
+
+    .. plot::
+        :context: close-figs
+
+        >>> df = pd.read_csv(
+        ...     'https://raw.githubusercontent.com/pandas-dev/'
+        ...     'pandas/main/pandas/tests/io/data/csv/iris.csv'
+        ... )
+        >>> pd.plotting.parallel_coordinates(
+        ...     df, 'Name', color=('#556270', '#4ECDC4', '#C7F464')
+        ... )  # doctest: +SKIP
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.parallel_coordinates(
+        frame=frame,
+        class_column=class_column,
+        cols=cols,
+        ax=ax,
+        color=color,
+        use_columns=use_columns,
+        xticks=xticks,
+        colormap=colormap,
+        axvlines=axvlines,
+        axvlines_kwds=axvlines_kwds,
+        sort_labels=sort_labels,
+        **kwargs,
+    )
+
+
+def lag_plot(series: Series, lag: int = 1, ax: Axes | None = None, **kwds) -> Axes:
+    """
+    Lag plot for time series.
+
+    Parameters
+    ----------
+    series : Series
+        The time series to visualize.
+    lag : int, default 1
+        Lag length of the scatter plot.
+    ax : Matplotlib axis object, optional
+        The matplotlib axis object to use.
+    **kwds
+        Matplotlib scatter method keyword arguments.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+
+    Examples
+    --------
+    Lag plots are most commonly used to look for patterns in time series data.
+
+    Given the following time series
+
+    .. plot::
+        :context: close-figs
+
+        >>> np.random.seed(5)
+        >>> x = np.cumsum(np.random.normal(loc=1, scale=5, size=50))
+        >>> s = pd.Series(x)
+        >>> s.plot()  # doctest: +SKIP
+
+    A lag plot with ``lag=1`` returns
+
+    .. plot::
+        :context: close-figs
+
+        >>> pd.plotting.lag_plot(s, lag=1)
+        
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.lag_plot(series=series, lag=lag, ax=ax, **kwds)
+
+
+def autocorrelation_plot(series: Series, ax: Axes | None = None, **kwargs) -> Axes:
+    """
+    Autocorrelation plot for time series.
+
+    Parameters
+    ----------
+    series : Series
+        The time series to visualize.
+    ax : Matplotlib axis object, optional
+        The matplotlib axis object to use.
+    **kwargs
+        Options to pass to matplotlib plotting method.
+
+    Returns
+    -------
+    matplotlib.axes.Axes
+
+    Examples
+    --------
+    The horizontal lines in the plot correspond to 95% and 99% confidence bands.
+
+    The dashed line is 99% confidence band.
+
+    .. plot::
+        :context: close-figs
+
+        >>> spacing = np.linspace(-9 * np.pi, 9 * np.pi, num=1000)
+        >>> s = pd.Series(0.7 * np.random.rand(1000) + 0.3 * np.sin(spacing))
+        >>> pd.plotting.autocorrelation_plot(s)  # doctest: +SKIP
+    """
+    plot_backend = _get_plot_backend("matplotlib")
+    return plot_backend.autocorrelation_plot(series=series, ax=ax, **kwargs)
+
+
+class _Options(dict):
+    """
+    Stores pandas plotting options.
+
+    Allows for parameter aliasing so you can just use parameter names that are
+    the same as the plot function parameters, but is stored in a canonical
+    format that makes it easy to breakdown into groups later.
+
+    Examples
+    --------
+
+    .. plot::
+            :context: close-figs
+
+             >>> np.random.seed(42)
+             >>> df = pd.DataFrame({'A': np.random.randn(10),
+             ...                   'B': np.random.randn(10)},
+             ...                   index=pd.date_range("1/1/2000",
+             ...                   freq='4MS', periods=10))
+             >>> with pd.plotting.plot_params.use("x_compat", True):
+             ...     _ = df["A"].plot(color="r")
+             ...     _ = df["B"].plot(color="g")
+    """
+
+    # alias so the names are same as plotting method parameter names
+    _ALIASES = {"x_compat": "xaxis.compat"}
+    _DEFAULT_KEYS = ["xaxis.compat"]
+
+    def __init__(self, deprecated: bool = False) -> None:
+        self._deprecated = deprecated
+        super().__setitem__("xaxis.compat", False)
+
+    def __getitem__(self, key):
+        key = self._get_canonical_key(key)
+        if key not in self:
+            raise ValueError(f"{key} is not a valid pandas plotting option")
+        return super().__getitem__(key)
+
+    def __setitem__(self, key, value) -> None:
+        key = self._get_canonical_key(key)
+        super().__setitem__(key, value)
+
+    def __delitem__(self, key) -> None:
+        key = self._get_canonical_key(key)
+        if key in self._DEFAULT_KEYS:
+            raise ValueError(f"Cannot remove default parameter {key}")
+        super().__delitem__(key)
+
+    def __contains__(self, key) -> bool:
+        key = self._get_canonical_key(key)
+        return super().__contains__(key)
+
+    def reset(self) -> None:
+        """
+        Reset the option store to its initial state
+
+        Returns
+        -------
+        None
+        """
+        # error: Cannot access "__init__" directly
+        self.__init__()  # type: ignore[misc]
+
+    def _get_canonical_key(self, key):
+        return self._ALIASES.get(key, key)
+
+    @contextmanager
+    def use(self, key, value) -> Generator[_Options, None, None]:
+        """
+        Temporarily set a parameter value using the with statement.
+        Aliasing allowed.
+        """
+        old_value = self[key]
+        try:
+            self[key] = value
+            yield self
+        finally:
+            self[key] = old_value
+
+
+plot_params = _Options()
diff --git a/.venv/lib/python3.13/site-packages/pandas/pyproject.toml b/.venv/lib/python3.13/site-packages/pandas/pyproject.toml
new file mode 100644
index 0000000000000000000000000000000000000000..d5a7f71391fef6e9797fb82700bb4021ab906984
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/pyproject.toml
@@ -0,0 +1,819 @@
+[build-system]
+# Minimum requirements for the build system to execute.
+# See https://github.com/scipy/scipy/pull/12940 for the AIX issue.
+requires = [
+    "meson-python>=0.13.1",
+    "meson>=1.2.1,<2",
+    "wheel",
+    "Cython<4.0.0a0",  # Note: sync with setup.py, environment.yml and asv.conf.json
+    # Force numpy higher than 2.0rc1, so that built wheels are compatible
+    # with both numpy 1 and 2
+    "numpy>=2.0",
+    "versioneer[toml]"
+]
+
+build-backend = "mesonpy"
+
+[project]
+name = 'pandas'
+dynamic = [
+  'version'
+]
+description = 'Powerful data structures for data analysis, time series, and statistics'
+readme = 'README.md'
+authors = [
+  { name = 'The Pandas Development Team', email='pandas-dev@python.org' },
+]
+license = {file = 'LICENSE'}
+requires-python = '>=3.9'
+dependencies = [
+  "numpy>=1.22.4; python_version<'3.11'",
+  "numpy>=1.23.2; python_version=='3.11'",
+  "numpy>=1.26.0; python_version>='3.12'",
+  "python-dateutil>=2.8.2",
+  "pytz>=2020.1",
+  "tzdata>=2022.7"
+]
+classifiers = [
+    'Development Status :: 5 - Production/Stable',
+    'Environment :: Console',
+    'Intended Audience :: Science/Research',
+    'License :: OSI Approved :: BSD License',
+    'Operating System :: OS Independent',
+    'Programming Language :: Cython',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3',
+    'Programming Language :: Python :: 3 :: Only',
+    'Programming Language :: Python :: 3.9',
+    'Programming Language :: Python :: 3.10',
+    'Programming Language :: Python :: 3.11',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Programming Language :: Python :: 3.14',
+    'Topic :: Scientific/Engineering'
+]
+
+[project.urls]
+homepage = 'https://pandas.pydata.org'
+documentation = 'https://pandas.pydata.org/docs/'
+repository = 'https://github.com/pandas-dev/pandas'
+
+[project.entry-points."pandas_plotting_backends"]
+matplotlib = "pandas:plotting._matplotlib"
+
+[project.optional-dependencies]
+test = ['hypothesis>=6.46.1', 'pytest>=7.3.2', 'pytest-xdist>=2.2.0']
+pyarrow = ['pyarrow>=10.0.1']
+performance = ['bottleneck>=1.3.6', 'numba>=0.56.4', 'numexpr>=2.8.4']
+computation = ['scipy>=1.10.0', 'xarray>=2022.12.0']
+fss = ['fsspec>=2022.11.0']
+aws = ['s3fs>=2022.11.0']
+gcp = ['gcsfs>=2022.11.0', 'pandas-gbq>=0.19.0']
+excel = ['odfpy>=1.4.1', 'openpyxl>=3.1.0', 'python-calamine>=0.1.7', 'pyxlsb>=1.0.10', 'xlrd>=2.0.1', 'xlsxwriter>=3.0.5']
+parquet = ['pyarrow>=10.0.1']
+feather = ['pyarrow>=10.0.1']
+hdf5 = [# blosc only available on conda (https://github.com/Blosc/python-blosc/issues/297)
+        #'blosc>=1.20.1',
+        'tables>=3.8.0']
+spss = ['pyreadstat>=1.2.0']
+postgresql = ['SQLAlchemy>=2.0.0', 'psycopg2>=2.9.6', 'adbc-driver-postgresql>=0.8.0']
+mysql = ['SQLAlchemy>=2.0.0', 'pymysql>=1.0.2']
+sql-other = ['SQLAlchemy>=2.0.0', 'adbc-driver-postgresql>=0.8.0', 'adbc-driver-sqlite>=0.8.0']
+html = ['beautifulsoup4>=4.11.2', 'html5lib>=1.1', 'lxml>=4.9.2']
+xml = ['lxml>=4.9.2']
+plot = ['matplotlib>=3.6.3']
+output-formatting = ['jinja2>=3.1.2', 'tabulate>=0.9.0']
+clipboard = ['PyQt5>=5.15.9', 'qtpy>=2.3.0']
+compression = ['zstandard>=0.19.0']
+consortium-standard = ['dataframe-api-compat>=0.1.7']
+all = ['adbc-driver-postgresql>=0.8.0',
+       'adbc-driver-sqlite>=0.8.0',
+       'beautifulsoup4>=4.11.2',
+       # blosc only available on conda (https://github.com/Blosc/python-blosc/issues/297)
+       #'blosc>=1.21.3',
+       'bottleneck>=1.3.6',
+       'dataframe-api-compat>=0.1.7',
+       'fastparquet>=2022.12.0',
+       'fsspec>=2022.11.0',
+       'gcsfs>=2022.11.0',
+       'html5lib>=1.1',
+       'hypothesis>=6.46.1',
+       'jinja2>=3.1.2',
+       'lxml>=4.9.2',
+       'matplotlib>=3.6.3',
+       'numba>=0.56.4',
+       'numexpr>=2.8.4',
+       'odfpy>=1.4.1',
+       'openpyxl>=3.1.0',
+       'pandas-gbq>=0.19.0',
+       'psycopg2>=2.9.6',
+       'pyarrow>=10.0.1',
+       'pymysql>=1.0.2',
+       'PyQt5>=5.15.9',
+       'pyreadstat>=1.2.0',
+       'pytest>=7.3.2',
+       'pytest-xdist>=2.2.0',
+       'python-calamine>=0.1.7',
+       'pyxlsb>=1.0.10',
+       'qtpy>=2.3.0',
+       'scipy>=1.10.0',
+       's3fs>=2022.11.0',
+       'SQLAlchemy>=2.0.0',
+       'tables>=3.8.0',
+       'tabulate>=0.9.0',
+       'xarray>=2022.12.0',
+       'xlrd>=2.0.1',
+       'xlsxwriter>=3.0.5',
+       'zstandard>=0.19.0']
+
+# TODO: Remove after setuptools support is dropped.
+[tool.setuptools]
+include-package-data = true
+
+[tool.setuptools.packages.find]
+include = ["pandas", "pandas.*"]
+namespaces = false
+
+[tool.setuptools.exclude-package-data]
+"*" = ["*.c", "*.h"]
+
+# See the docstring in versioneer.py for instructions. Note that you must
+# re-run 'versioneer.py setup' after changing this section, and commit the
+# resulting files.
+[tool.versioneer]
+VCS = "git"
+style = "pep440"
+versionfile_source = "pandas/_version.py"
+versionfile_build = "pandas/_version.py"
+tag_prefix = "v"
+parentdir_prefix = "pandas-"
+
+[tool.meson-python.args]
+setup = ['--vsenv'] # For Windows
+
+[tool.cibuildwheel]
+skip = "cp38-* *_i686 *_ppc64le *_s390x"
+build-verbosity = "3"
+environment = {LDFLAGS="-Wl,--strip-all"}
+# pytz 2024.2 causing some failures
+test-requires = "hypothesis>=6.46.1 pytest>=7.3.2 pytest-xdist>=2.2.0 pytz<2024.2"
+test-command = """
+  PANDAS_CI='1' python -c 'import pandas as pd; \
+  pd.test(extra_args=["-m not clipboard and not single_cpu and not slow and not network and not db", "-n 2", "--no-strict-data-files"]); \
+  pd.test(extra_args=["-m not clipboard and single_cpu and not slow and not network and not db", "--no-strict-data-files"]);' \
+  """
+enable = ["cpython-freethreading"]
+before-build = "PACKAGE_DIR={package} bash {package}/scripts/cibw_before_build.sh"
+
+[tool.cibuildwheel.windows]
+before-build = "pip install delvewheel"
+repair-wheel-command = "delvewheel repair -w {dest_dir} {wheel}"
+
+[[tool.cibuildwheel.overrides]]
+select = "*-manylinux_aarch64*"
+test-command = """
+  PANDAS_CI='1' python -c 'import pandas as pd; \
+  pd.test(extra_args=["-m not clipboard and not single_cpu and not slow and not network and not db and not fails_arm_wheels", "-n 2", "--no-strict-data-files"]); \
+  pd.test(extra_args=["-m not clipboard and single_cpu and not slow and not network and not db", "--no-strict-data-files"]);' \
+  """
+
+[[tool.cibuildwheel.overrides]]
+select = "*-musllinux*"
+before-test = "apk update && apk add musl-locales"
+
+[[tool.cibuildwheel.overrides]]
+select = "*-win*"
+# We test separately for Windows, since we use
+# the windowsservercore docker image to check if any dlls are
+# missing from the wheel
+test-command = ""
+
+[[tool.cibuildwheel.overrides]]
+# Don't strip wheels on macOS.
+# macOS doesn't support stripping wheels with linker
+# https://github.com/MacPython/numpy-wheels/pull/87#issuecomment-624878264
+select = "*-macosx*"
+environment = {CFLAGS="-g0"}
+
+[tool.black]
+target-version = ['py39', 'py310']
+required-version = '23.11.0'
+exclude = '''
+(
+    asv_bench/env
+  | \.egg
+  | \.git
+  | \.hg
+  | \.mypy_cache
+  | \.nox
+  | \.tox
+  | \.venv
+  | _build
+  | buck-out
+  | build
+  | dist
+  | setup.py
+)
+'''
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+fix = true
+unfixable = []
+typing-modules = ["pandas._typing"]
+
+select = [
+  # pyflakes
+  "F",
+  # pycodestyle
+  "E", "W",
+  # flake8-2020
+  "YTT",
+  # flake8-bugbear
+  "B",
+  # flake8-quotes
+  "Q",
+  # flake8-debugger
+  "T10",
+  # flake8-gettext
+  "INT",
+  # pylint
+  "PL",
+  # misc lints
+  "PIE",
+  # flake8-pyi
+  "PYI",
+  # tidy imports
+  "TID",
+  # implicit string concatenation
+  "ISC",
+  # type-checking imports
+  "TCH",
+  # comprehensions
+  "C4",
+  # pygrep-hooks
+  "PGH",
+  # Ruff-specific rules
+  "RUF",
+  # flake8-bandit: exec-builtin
+  "S102",
+  # numpy-legacy-random
+  "NPY002",
+  # Perflint
+  "PERF",
+  # flynt
+  "FLY",
+  # flake8-logging-format
+  "G",
+  # flake8-future-annotations
+  "FA",
+]
+
+ignore = [
+  ### Intentionally disabled
+  # space before : (needed for how black formats slicing)
+  "E203",
+  # module level import not at top of file
+  "E402",
+  # do not assign a lambda expression, use a def
+  "E731",
+  # line break before binary operator
+  # "W503",  # not yet implemented
+  # line break after binary operator
+  # "W504",  # not yet implemented
+  # controversial
+  "B006",
+  # controversial
+  "B007",
+  # controversial
+  "B008",
+  # setattr is used to side-step mypy
+  "B009",
+  # getattr is used to side-step mypy
+  "B010",
+  # tests use assert False
+  "B011",
+  # tests use comparisons but not their returned value
+  "B015",
+  # false positives
+  "B019",
+  # Loop control variable overrides iterable it iterates
+  "B020",
+  # Function definition does not bind loop variable
+  "B023",
+  # Functions defined inside a loop must not use variables redefined in the loop
+  # "B301",  # not yet implemented
+  # Only works with python >=3.10
+  "B905",
+  # Too many arguments to function call
+  "PLR0913",
+  # Too many returns
+  "PLR0911",
+  # Too many branches
+  "PLR0912",
+  # Too many statements
+  "PLR0915",
+  # Redefined loop name
+  "PLW2901",
+  # Global statements are discouraged
+  "PLW0603",
+  # Docstrings should not be included in stubs
+  "PYI021",
+  # Use `typing.NamedTuple` instead of `collections.namedtuple`
+  "PYI024",
+  # No builtin `eval()` allowed
+  "PGH001",
+  # compare-to-empty-string
+  "PLC1901",
+  # while int | float can be shortened to float, the former is more explicit
+  "PYI041",
+  # incorrect-dict-iterator, flags valid Series.items usage
+  "PERF102",
+  # try-except-in-loop, becomes useless in Python 3.11
+  "PERF203",
+
+
+  ### TODO: Enable gradually
+  # Useless statement
+  "B018",
+  # Within an except clause, raise exceptions with ...
+  "B904",
+  # Magic number
+  "PLR2004",
+  # comparison-with-itself
+  "PLR0124",
+  # Consider `elif` instead of `else` then `if` to remove indentation level
+  "PLR5501",
+  # collection-literal-concatenation
+  "RUF005",
+  # pairwise-over-zipped (>=PY310 only)
+  "RUF007",
+  # explicit-f-string-type-conversion
+  "RUF010",
+  # mutable-class-default
+  "RUF012"
+]
+
+exclude = [
+  "doc/sphinxext/*.py",
+  "doc/build/*.py",
+  "doc/temp/*.py",
+  ".eggs/*.py",
+  # vendored files
+  "pandas/util/version/*",
+  "pandas/io/clipboard/__init__.py",
+  # exclude asv benchmark environments from linting
+  "env",
+]
+
+[tool.ruff.per-file-ignores]
+# relative imports allowed for asv_bench
+"asv_bench/*" = ["TID", "NPY002"]
+# to be enabled gradually
+"pandas/core/*" = ["PLR5501"]
+"pandas/tests/*" = ["B028", "FLY"]
+"scripts/*" = ["B028"]
+# Keep this one enabled
+"pandas/_typing.py" = ["TCH"]
+
+[tool.pylint.messages_control]
+max-line-length = 88
+disable = [
+ # intentionally turned off
+  "bad-mcs-classmethod-argument",
+  "broad-except",
+  "c-extension-no-member",
+  "comparison-with-itself",
+  "consider-using-enumerate",
+  "import-error",
+  "import-outside-toplevel",
+  "invalid-name",
+  "invalid-unary-operand-type",
+  "line-too-long",
+  "no-else-continue",
+  "no-else-raise",
+  "no-else-return",
+  "no-member",
+  "no-name-in-module",
+  "not-an-iterable",
+  "overridden-final-method",
+  "pointless-statement",
+  "redundant-keyword-arg",
+  "singleton-comparison",
+  "too-many-ancestors",
+  "too-many-arguments",
+  "too-many-boolean-expressions",
+  "too-many-branches",
+  "too-many-function-args",
+  "too-many-instance-attributes",
+  "too-many-locals",
+  "too-many-nested-blocks",
+  "too-many-public-methods",
+  "too-many-return-statements",
+  "too-many-statements",
+  "unexpected-keyword-arg",
+  "ungrouped-imports",
+  "unsubscriptable-object",
+  "unsupported-assignment-operation",
+  "unsupported-membership-test",
+  "unused-import",
+  "use-dict-literal",
+  "use-implicit-booleaness-not-comparison",
+  "use-implicit-booleaness-not-len",
+  "wrong-import-order",
+  "wrong-import-position",
+  "redefined-loop-name",
+
+ # misc
+  "abstract-class-instantiated",
+  "no-value-for-parameter",
+  "undefined-variable",
+  "unpacking-non-sequence",
+  "used-before-assignment",
+
+ # pylint type "C": convention, for programming standard violation
+  "missing-class-docstring",
+  "missing-function-docstring",
+  "missing-module-docstring",
+  "superfluous-parens",
+  "too-many-lines",
+  "unidiomatic-typecheck",
+  "unnecessary-dunder-call",
+  "unnecessary-lambda-assignment",
+
+  # pylint type "R": refactor, for bad code smell
+  "consider-using-with",
+  "cyclic-import",
+  "duplicate-code",
+  "inconsistent-return-statements",
+  "redefined-argument-from-local",
+  "too-few-public-methods",
+
+  # pylint type "W": warning, for python specific problems
+  "abstract-method",
+  "arguments-differ",
+  "arguments-out-of-order",
+  "arguments-renamed",
+  "attribute-defined-outside-init",
+  "broad-exception-raised",
+  "comparison-with-callable",
+  "dangerous-default-value",
+  "deprecated-module",
+  "eval-used",
+  "expression-not-assigned",
+  "fixme",
+  "global-statement",
+  "invalid-overridden-method",
+  "keyword-arg-before-vararg",
+  "possibly-unused-variable",
+  "protected-access",
+  "raise-missing-from",
+  "redefined-builtin",
+  "redefined-outer-name",
+  "self-cls-assignment",
+  "signature-differs",
+  "super-init-not-called",
+  "try-except-raise",
+  "unnecessary-lambda",
+  "unused-argument",
+  "unused-variable",
+  "using-constant-test",
+
+  # disabled on 2.3.x branch
+  "consider-using-in",
+  "simplifiable-if-expression",
+]
+
+[tool.pytest.ini_options]
+# sync minversion with pyproject.toml & install.rst
+minversion = "7.3.2"
+addopts = "--strict-markers --strict-config --capture=no --durations=30 --junitxml=test-data.xml"
+empty_parameter_set_mark = "fail_at_collect"
+xfail_strict = true
+testpaths = "pandas"
+doctest_optionflags = [
+  "NORMALIZE_WHITESPACE",
+  "IGNORE_EXCEPTION_DETAIL",
+  "ELLIPSIS",
+]
+filterwarnings = [
+  "error:::pandas",
+  "error::ResourceWarning",
+  "error::pytest.PytestUnraisableExceptionWarning",
+  # TODO(PY311-minimum): Specify EncodingWarning
+  # Ignore 3rd party EncodingWarning but raise on pandas'
+  "ignore:.*encoding.* argument not specified",
+  "error:.*encoding.* argument not specified::pandas",
+  "ignore:.*ssl.SSLSocket:pytest.PytestUnraisableExceptionWarning",
+  "ignore:.*ssl.SSLSocket:ResourceWarning",
+  # GH 44844: Can remove once minimum matplotlib version >= 3.7
+  "ignore:.*FileIO:pytest.PytestUnraisableExceptionWarning",
+  "ignore:.*BufferedRandom:ResourceWarning",
+  "ignore::ResourceWarning:asyncio",
+  # From plotting doctests
+  "ignore:More than 20 figures have been opened:RuntimeWarning",
+  # Will be fixed in numba 0.56: https://github.com/numba/numba/issues/7758
+  "ignore:`np.MachAr` is deprecated:DeprecationWarning:numba",
+  "ignore:.*urllib3:DeprecationWarning:botocore",
+  "ignore:Setuptools is replacing distutils.:UserWarning:_distutils_hack",
+  # https://github.com/PyTables/PyTables/issues/822
+  "ignore:a closed node found in the registry:UserWarning:tables",
+  "ignore:`np.object` is a deprecated:DeprecationWarning:tables",
+  "ignore:tostring:DeprecationWarning:tables",
+  "ignore:distutils Version classes are deprecated:DeprecationWarning:pandas_datareader",
+  "ignore:distutils Version classes are deprecated:DeprecationWarning:numexpr",
+  "ignore:distutils Version classes are deprecated:DeprecationWarning:fastparquet",
+  "ignore:distutils Version classes are deprecated:DeprecationWarning:fsspec",
+  # Can be removed once https://github.com/numpy/numpy/pull/24794 is merged
+  "ignore:.*In the future `np.long` will be defined as.*:FutureWarning",
+  # https://github.com/numpy/numpy/pull/29301
+  "ignore:.*align should be passed:",
+]
+junit_family = "xunit2"
+markers = [
+  "single_cpu: tests that should run on a single cpu only",
+  "slow: mark a test as slow",
+  "network: mark a test as network",
+  "db: tests requiring a database (mysql or postgres)",
+  "clipboard: mark a pd.read_clipboard test",
+  "arm_slow: mark a test as slow for arm64 architecture",
+  "skip_ubsan: Tests known to fail UBSAN check",
+  # TODO: someone should investigate this ...
+  # these tests only fail in the wheel builder and don't fail in regular
+  # ARM CI
+  "fails_arm_wheels: Tests that fail in the ARM wheel build only",
+]
+
+[tool.mypy]
+# Import discovery
+mypy_path = "typings"
+files = ["pandas", "typings"]
+namespace_packages = false
+explicit_package_bases = false
+ignore_missing_imports = true
+follow_imports = "normal"
+follow_imports_for_stubs = false
+no_site_packages = false
+no_silence_site_packages = false
+# Platform configuration
+python_version = "3.11"
+platform = "linux-64"
+# Disallow dynamic typing
+disallow_any_unimported = false # TODO
+disallow_any_expr = false # TODO
+disallow_any_decorated = false # TODO
+disallow_any_explicit = false # TODO
+disallow_any_generics = false # TODO
+disallow_subclassing_any = false # TODO
+# Untyped definitions and calls
+disallow_untyped_calls = true
+disallow_untyped_defs = true
+disallow_incomplete_defs = true
+check_untyped_defs = true
+disallow_untyped_decorators = true
+# None and Optional handling
+no_implicit_optional = true
+strict_optional = true
+# Configuring warnings
+warn_redundant_casts = true
+warn_unused_ignores = true
+warn_no_return = true
+warn_return_any = false # TODO
+warn_unreachable = false # GH#27396
+# Suppressing errors
+ignore_errors = false
+enable_error_code = "ignore-without-code"
+# Miscellaneous strictness flags
+allow_untyped_globals = false
+allow_redefinition = false
+local_partial_types = false
+implicit_reexport = true
+strict_equality = true
+# Configuring error messages
+show_error_context = false
+show_column_numbers = false
+show_error_codes = true
+
+[[tool.mypy.overrides]]
+module = [
+  "pandas._config.config", # TODO
+  "pandas._libs.*",
+  "pandas._testing.*", # TODO
+  "pandas.arrays", # TODO
+  "pandas.compat.numpy.function", # TODO
+  "pandas.compat._optional", # TODO
+  "pandas.compat.compressors", # TODO
+  "pandas.compat.pickle_compat", # TODO
+  "pandas.core._numba.executor", # TODO
+  "pandas.core.array_algos.datetimelike_accumulations", # TODO
+  "pandas.core.array_algos.masked_accumulations", # TODO
+  "pandas.core.array_algos.masked_reductions", # TODO
+  "pandas.core.array_algos.putmask", # TODO
+  "pandas.core.array_algos.quantile", # TODO
+  "pandas.core.array_algos.replace", # TODO
+  "pandas.core.array_algos.take", # TODO
+  "pandas.core.arrays.*", # TODO
+  "pandas.core.computation.*", # TODO
+  "pandas.core.dtypes.astype", # TODO
+  "pandas.core.dtypes.cast", # TODO
+  "pandas.core.dtypes.common", # TODO
+  "pandas.core.dtypes.concat", # TODO
+  "pandas.core.dtypes.dtypes", # TODO
+  "pandas.core.dtypes.generic", # TODO
+  "pandas.core.dtypes.inference", # TODO
+  "pandas.core.dtypes.missing", # TODO
+  "pandas.core.groupby.categorical", # TODO
+  "pandas.core.groupby.generic", # TODO
+  "pandas.core.groupby.grouper", # TODO
+  "pandas.core.groupby.groupby", # TODO
+  "pandas.core.groupby.ops", # TODO
+  "pandas.core.indexers.*", # TODO
+  "pandas.core.indexes.*", # TODO
+  "pandas.core.interchange.column", # TODO
+  "pandas.core.interchange.dataframe_protocol", # TODO
+  "pandas.core.interchange.from_dataframe", # TODO
+  "pandas.core.internals.*", # TODO
+  "pandas.core.methods.*", # TODO
+  "pandas.core.ops.array_ops", # TODO
+  "pandas.core.ops.common", # TODO
+  "pandas.core.ops.invalid", # TODO
+  "pandas.core.ops.mask_ops", # TODO
+  "pandas.core.ops.missing", # TODO
+  "pandas.core.reshape.*", # TODO
+  "pandas.core.strings.*", # TODO
+  "pandas.core.tools.*", # TODO
+  "pandas.core.window.common", # TODO
+  "pandas.core.window.ewm", # TODO
+  "pandas.core.window.expanding", # TODO
+  "pandas.core.window.numba_", # TODO
+  "pandas.core.window.online", # TODO
+  "pandas.core.window.rolling", # TODO
+  "pandas.core.accessor", # TODO
+  "pandas.core.algorithms", # TODO
+  "pandas.core.apply", # TODO
+  "pandas.core.arraylike", # TODO
+  "pandas.core.base", # TODO
+  "pandas.core.common", # TODO
+  "pandas.core.config_init", # TODO
+  "pandas.core.construction", # TODO
+  "pandas.core.flags", # TODO
+  "pandas.core.frame", # TODO
+  "pandas.core.generic", # TODO
+  "pandas.core.indexing", # TODO
+  "pandas.core.missing", # TODO
+  "pandas.core.nanops", # TODO
+  "pandas.core.resample", # TODO
+  "pandas.core.roperator", # TODO
+  "pandas.core.sample", # TODO
+  "pandas.core.series", # TODO
+  "pandas.core.sorting", # TODO
+  "pandas.errors", # TODO
+  "pandas.io.clipboard", # TODO
+  "pandas.io.excel._base", # TODO
+  "pandas.io.excel._odfreader", # TODO
+  "pandas.io.excel._odswriter", # TODO
+  "pandas.io.excel._openpyxl", # TODO
+  "pandas.io.excel._pyxlsb", # TODO
+  "pandas.io.excel._xlrd", # TODO
+  "pandas.io.excel._xlsxwriter", # TODO
+  "pandas.io.formats.console", # TODO
+  "pandas.io.formats.css", # TODO
+  "pandas.io.formats.excel", # TODO
+  "pandas.io.formats.format", # TODO
+  "pandas.io.formats.info", # TODO
+  "pandas.io.formats.printing", # TODO
+  "pandas.io.formats.style", # TODO
+  "pandas.io.formats.style_render", # TODO
+  "pandas.io.formats.xml", # TODO
+  "pandas.io.json.*", # TODO
+  "pandas.io.parsers.*", # TODO
+  "pandas.io.sas.sas_xport", # TODO
+  "pandas.io.sas.sas7bdat", # TODO
+  "pandas.io.clipboards", # TODO
+  "pandas.io.common", # TODO
+  "pandas.io.gbq", # TODO
+  "pandas.io.html", # TODO
+  "pandas.io.gbq", # TODO
+  "pandas.io.parquet", # TODO
+  "pandas.io.pytables", # TODO
+  "pandas.io.sql", # TODO
+  "pandas.io.stata", # TODO
+  "pandas.io.xml", # TODO
+  "pandas.plotting.*", # TODO
+  "pandas.tests.*",
+  "pandas.tseries.frequencies", # TODO
+  "pandas.tseries.holiday", # TODO
+  "pandas.util._decorators", # TODO
+  "pandas.util._doctools", # TODO
+  "pandas.util._print_versions", # TODO
+  "pandas.util._test_decorators", # TODO
+  "pandas.util._validators", # TODO
+  "pandas.util", # TODO
+  "pandas._version",
+  "pandas.conftest",
+  "pandas"
+]
+disallow_untyped_calls = false
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+
+[[tool.mypy.overrides]]
+module = [
+  "pandas.tests.*",
+  "pandas._version",
+  "pandas.io.clipboard",
+]
+check_untyped_defs = false
+
+[[tool.mypy.overrides]]
+module = [
+  "pandas.tests.apply.test_series_apply",
+  "pandas.tests.arithmetic.conftest",
+  "pandas.tests.arrays.sparse.test_combine_concat",
+  "pandas.tests.dtypes.test_common",
+  "pandas.tests.frame.methods.test_to_records",
+  "pandas.tests.groupby.test_rank",
+  "pandas.tests.groupby.transform.test_transform",
+  "pandas.tests.indexes.interval.test_interval",
+  "pandas.tests.indexing.test_categorical",
+  "pandas.tests.io.excel.test_writers",
+  "pandas.tests.reductions.test_reductions",
+  "pandas.tests.test_expressions",
+]
+ignore_errors = true
+
+# To be kept consistent with "Import Formatting" section in contributing.rst
+[tool.isort]
+known_pre_libs = "pandas._config"
+known_pre_core = ["pandas._libs", "pandas._typing", "pandas.util._*", "pandas.compat", "pandas.errors"]
+known_dtypes = "pandas.core.dtypes"
+known_post_core = ["pandas.tseries", "pandas.io", "pandas.plotting"]
+sections = ["FUTURE", "STDLIB", "THIRDPARTY" ,"PRE_LIBS" , "PRE_CORE", "DTYPES", "FIRSTPARTY", "POST_CORE", "LOCALFOLDER"]
+profile = "black"
+combine_as_imports = true
+force_grid_wrap = 2
+force_sort_within_sections = true
+skip_glob = "env"
+skip = "pandas/__init__.py"
+
+[tool.pyright]
+pythonVersion = "3.11"
+typeCheckingMode = "basic"
+useLibraryCodeForTypes = false
+include = ["pandas", "typings"]
+exclude = ["pandas/tests", "pandas/io/clipboard", "pandas/util/version", "pandas/core/_numba/extensions.py"]
+# enable subset of "strict"
+reportDuplicateImport = true
+reportInconsistentConstructor = true
+reportInvalidStubStatement = true
+reportOverlappingOverload = true
+reportPropertyTypeMismatch = true
+reportUntypedClassDecorator = true
+reportUntypedFunctionDecorator = true
+reportUntypedNamedTuple = true
+reportUnusedImport = true
+disableBytesTypePromotions = true
+# disable subset of "basic"
+reportGeneralTypeIssues = false
+reportMissingModuleSource = false
+reportOptionalCall = false
+reportOptionalIterable = false
+reportOptionalMemberAccess = false
+reportOptionalOperand = false
+reportOptionalSubscript = false
+reportPrivateImportUsage = false
+reportUnboundVariable = false
+
+[tool.coverage.run]
+branch = true
+omit = ["pandas/_typing.py", "pandas/_version.py"]
+plugins = ["Cython.Coverage"]
+source = ["pandas"]
+
+[tool.coverage.report]
+ignore_errors = false
+show_missing = true
+omit = ["pandas/_version.py"]
+exclude_lines = [
+  # Have to re-enable the standard pragma
+  "pragma: no cover",
+  # Don't complain about missing debug-only code:s
+  "def __repr__",
+  "if self.debug",
+  # Don't complain if tests don't hit defensive assertion code:
+  "raise AssertionError",
+  "raise NotImplementedError",
+  "AbstractMethodError",
+  # Don't complain if non-runnable code isn't run:
+  "if 0:",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.coverage.html]
+directory = "coverage_html_report"
+
+[tool.codespell]
+ignore-words-list = "blocs, coo, hist, nd, sav, ser, recuse, nin, timere, expec, expecs"
+ignore-regex = 'https://([\w/\.])+'
diff --git a/.venv/lib/python3.13/site-packages/pandas/testing.py b/.venv/lib/python3.13/site-packages/pandas/testing.py
new file mode 100644
index 0000000000000000000000000000000000000000..841b55df48556561904b9144a05f747d889ea621
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/testing.py
@@ -0,0 +1,18 @@
+"""
+Public testing utility functions.
+"""
+
+
+from pandas._testing import (
+    assert_extension_array_equal,
+    assert_frame_equal,
+    assert_index_equal,
+    assert_series_equal,
+)
+
+__all__ = [
+    "assert_extension_array_equal",
+    "assert_frame_equal",
+    "assert_series_equal",
+    "assert_index_equal",
+]
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/api/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/api/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/api/test_api.py b/.venv/lib/python3.13/site-packages/pandas/tests/api/test_api.py
new file mode 100644
index 0000000000000000000000000000000000000000..60bcb97aaa3642be064bcacd130edf2084c4a55c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/api/test_api.py
@@ -0,0 +1,383 @@
+from __future__ import annotations
+
+import pytest
+
+import pandas as pd
+from pandas import api
+import pandas._testing as tm
+from pandas.api import (
+    extensions as api_extensions,
+    indexers as api_indexers,
+    interchange as api_interchange,
+    types as api_types,
+    typing as api_typing,
+)
+
+
+class Base:
+    def check(self, namespace, expected, ignored=None):
+        # see which names are in the namespace, minus optional
+        # ignored ones
+        # compare vs the expected
+
+        result = sorted(
+            f for f in dir(namespace) if not f.startswith("__") and f != "annotations"
+        )
+        if ignored is not None:
+            result = sorted(set(result) - set(ignored))
+
+        expected = sorted(expected)
+        tm.assert_almost_equal(result, expected)
+
+
+class TestPDApi(Base):
+    # these are optionally imported based on testing
+    # & need to be ignored
+    ignored = ["tests", "locale", "conftest", "_version_meson"]
+
+    # top-level sub-packages
+    public_lib = [
+        "api",
+        "arrays",
+        "options",
+        "test",
+        "testing",
+        "errors",
+        "plotting",
+        "io",
+        "tseries",
+    ]
+    private_lib = ["compat", "core", "pandas", "util", "_built_with_meson"]
+
+    # misc
+    misc = ["IndexSlice", "NaT", "NA"]
+
+    # top-level classes
+    classes = [
+        "ArrowDtype",
+        "Categorical",
+        "CategoricalIndex",
+        "DataFrame",
+        "DateOffset",
+        "DatetimeIndex",
+        "ExcelFile",
+        "ExcelWriter",
+        "Flags",
+        "Grouper",
+        "HDFStore",
+        "Index",
+        "MultiIndex",
+        "Period",
+        "PeriodIndex",
+        "RangeIndex",
+        "Series",
+        "SparseDtype",
+        "StringDtype",
+        "Timedelta",
+        "TimedeltaIndex",
+        "Timestamp",
+        "Interval",
+        "IntervalIndex",
+        "CategoricalDtype",
+        "PeriodDtype",
+        "IntervalDtype",
+        "DatetimeTZDtype",
+        "BooleanDtype",
+        "Int8Dtype",
+        "Int16Dtype",
+        "Int32Dtype",
+        "Int64Dtype",
+        "UInt8Dtype",
+        "UInt16Dtype",
+        "UInt32Dtype",
+        "UInt64Dtype",
+        "Float32Dtype",
+        "Float64Dtype",
+        "NamedAgg",
+    ]
+
+    # these are already deprecated; awaiting removal
+    deprecated_classes: list[str] = []
+
+    # external modules exposed in pandas namespace
+    modules: list[str] = []
+
+    # top-level functions
+    funcs = [
+        "array",
+        "bdate_range",
+        "concat",
+        "crosstab",
+        "cut",
+        "date_range",
+        "interval_range",
+        "eval",
+        "factorize",
+        "get_dummies",
+        "from_dummies",
+        "infer_freq",
+        "isna",
+        "isnull",
+        "lreshape",
+        "melt",
+        "notna",
+        "notnull",
+        "offsets",
+        "merge",
+        "merge_ordered",
+        "merge_asof",
+        "period_range",
+        "pivot",
+        "pivot_table",
+        "qcut",
+        "show_versions",
+        "timedelta_range",
+        "unique",
+        "value_counts",
+        "wide_to_long",
+    ]
+
+    # top-level option funcs
+    funcs_option = [
+        "reset_option",
+        "describe_option",
+        "get_option",
+        "option_context",
+        "set_option",
+        "set_eng_float_format",
+    ]
+
+    # top-level read_* funcs
+    funcs_read = [
+        "read_clipboard",
+        "read_csv",
+        "read_excel",
+        "read_fwf",
+        "read_gbq",
+        "read_hdf",
+        "read_html",
+        "read_xml",
+        "read_json",
+        "read_pickle",
+        "read_sas",
+        "read_sql",
+        "read_sql_query",
+        "read_sql_table",
+        "read_stata",
+        "read_table",
+        "read_feather",
+        "read_parquet",
+        "read_orc",
+        "read_spss",
+    ]
+
+    # top-level json funcs
+    funcs_json = ["json_normalize"]
+
+    # top-level to_* funcs
+    funcs_to = ["to_datetime", "to_numeric", "to_pickle", "to_timedelta"]
+
+    # top-level to deprecate in the future
+    deprecated_funcs_in_future: list[str] = []
+
+    # these are already deprecated; awaiting removal
+    deprecated_funcs: list[str] = []
+
+    # private modules in pandas namespace
+    private_modules = [
+        "_config",
+        "_libs",
+        "_is_numpy_dev",
+        "_pandas_datetime_CAPI",
+        "_pandas_parser_CAPI",
+        "_testing",
+        "_typing",
+    ]
+    if not pd._built_with_meson:
+        private_modules.append("_version")
+
+    def test_api(self):
+        checkthese = (
+            self.public_lib
+            + self.private_lib
+            + self.misc
+            + self.modules
+            + self.classes
+            + self.funcs
+            + self.funcs_option
+            + self.funcs_read
+            + self.funcs_json
+            + self.funcs_to
+            + self.private_modules
+        )
+        self.check(namespace=pd, expected=checkthese, ignored=self.ignored)
+
+    def test_api_all(self):
+        expected = set(
+            self.public_lib
+            + self.misc
+            + self.modules
+            + self.classes
+            + self.funcs
+            + self.funcs_option
+            + self.funcs_read
+            + self.funcs_json
+            + self.funcs_to
+        ) - set(self.deprecated_classes)
+        actual = set(pd.__all__)
+
+        extraneous = actual - expected
+        assert not extraneous
+
+        missing = expected - actual
+        assert not missing
+
+    def test_depr(self):
+        deprecated_list = (
+            self.deprecated_classes
+            + self.deprecated_funcs
+            + self.deprecated_funcs_in_future
+        )
+        for depr in deprecated_list:
+            with tm.assert_produces_warning(FutureWarning):
+                _ = getattr(pd, depr)
+
+
+class TestApi(Base):
+    allowed_api_dirs = [
+        "types",
+        "extensions",
+        "indexers",
+        "interchange",
+        "typing",
+    ]
+    allowed_typing = [
+        "DataFrameGroupBy",
+        "DatetimeIndexResamplerGroupby",
+        "Expanding",
+        "ExpandingGroupby",
+        "ExponentialMovingWindow",
+        "ExponentialMovingWindowGroupby",
+        "JsonReader",
+        "NaTType",
+        "NAType",
+        "PeriodIndexResamplerGroupby",
+        "Resampler",
+        "Rolling",
+        "RollingGroupby",
+        "SeriesGroupBy",
+        "StataReader",
+        "TimedeltaIndexResamplerGroupby",
+        "TimeGrouper",
+        "Window",
+    ]
+    allowed_api_types = [
+        "is_any_real_numeric_dtype",
+        "is_array_like",
+        "is_bool",
+        "is_bool_dtype",
+        "is_categorical_dtype",
+        "is_complex",
+        "is_complex_dtype",
+        "is_datetime64_any_dtype",
+        "is_datetime64_dtype",
+        "is_datetime64_ns_dtype",
+        "is_datetime64tz_dtype",
+        "is_dict_like",
+        "is_dtype_equal",
+        "is_extension_array_dtype",
+        "is_file_like",
+        "is_float",
+        "is_float_dtype",
+        "is_hashable",
+        "is_int64_dtype",
+        "is_integer",
+        "is_integer_dtype",
+        "is_interval",
+        "is_interval_dtype",
+        "is_iterator",
+        "is_list_like",
+        "is_named_tuple",
+        "is_number",
+        "is_numeric_dtype",
+        "is_object_dtype",
+        "is_period_dtype",
+        "is_re",
+        "is_re_compilable",
+        "is_scalar",
+        "is_signed_integer_dtype",
+        "is_sparse",
+        "is_string_dtype",
+        "is_timedelta64_dtype",
+        "is_timedelta64_ns_dtype",
+        "is_unsigned_integer_dtype",
+        "pandas_dtype",
+        "infer_dtype",
+        "union_categoricals",
+        "CategoricalDtype",
+        "DatetimeTZDtype",
+        "IntervalDtype",
+        "PeriodDtype",
+    ]
+    allowed_api_interchange = ["from_dataframe", "DataFrame"]
+    allowed_api_indexers = [
+        "check_array_indexer",
+        "BaseIndexer",
+        "FixedForwardWindowIndexer",
+        "VariableOffsetWindowIndexer",
+    ]
+    allowed_api_extensions = [
+        "no_default",
+        "ExtensionDtype",
+        "register_extension_dtype",
+        "register_dataframe_accessor",
+        "register_index_accessor",
+        "register_series_accessor",
+        "take",
+        "ExtensionArray",
+        "ExtensionScalarOpsMixin",
+    ]
+
+    def test_api(self):
+        self.check(api, self.allowed_api_dirs)
+
+    def test_api_typing(self):
+        self.check(api_typing, self.allowed_typing)
+
+    def test_api_types(self):
+        self.check(api_types, self.allowed_api_types)
+
+    def test_api_interchange(self):
+        self.check(api_interchange, self.allowed_api_interchange)
+
+    def test_api_indexers(self):
+        self.check(api_indexers, self.allowed_api_indexers)
+
+    def test_api_extensions(self):
+        self.check(api_extensions, self.allowed_api_extensions)
+
+
+class TestTesting(Base):
+    funcs = [
+        "assert_frame_equal",
+        "assert_series_equal",
+        "assert_index_equal",
+        "assert_extension_array_equal",
+    ]
+
+    def test_testing(self):
+        from pandas import testing
+
+        self.check(testing, self.funcs)
+
+    def test_util_in_top_level(self):
+        with pytest.raises(AttributeError, match="foo"):
+            pd.util.foo
+
+
+def test_pandas_array_alias():
+    msg = "PandasArray has been renamed NumpyExtensionArray"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        res = pd.arrays.PandasArray
+
+    assert res is pd.arrays.NumpyExtensionArray
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/api/test_types.py b/.venv/lib/python3.13/site-packages/pandas/tests/api/test_types.py
new file mode 100644
index 0000000000000000000000000000000000000000..fbaa6e7e18bcaa9a574b741b5361818f1be01ecf
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/api/test_types.py
@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import pandas._testing as tm
+from pandas.api import types
+from pandas.tests.api.test_api import Base
+
+
+class TestTypes(Base):
+    allowed = [
+        "is_any_real_numeric_dtype",
+        "is_bool",
+        "is_bool_dtype",
+        "is_categorical_dtype",
+        "is_complex",
+        "is_complex_dtype",
+        "is_datetime64_any_dtype",
+        "is_datetime64_dtype",
+        "is_datetime64_ns_dtype",
+        "is_datetime64tz_dtype",
+        "is_dtype_equal",
+        "is_float",
+        "is_float_dtype",
+        "is_int64_dtype",
+        "is_integer",
+        "is_integer_dtype",
+        "is_number",
+        "is_numeric_dtype",
+        "is_object_dtype",
+        "is_scalar",
+        "is_sparse",
+        "is_string_dtype",
+        "is_signed_integer_dtype",
+        "is_timedelta64_dtype",
+        "is_timedelta64_ns_dtype",
+        "is_unsigned_integer_dtype",
+        "is_period_dtype",
+        "is_interval",
+        "is_interval_dtype",
+        "is_re",
+        "is_re_compilable",
+        "is_dict_like",
+        "is_iterator",
+        "is_file_like",
+        "is_list_like",
+        "is_hashable",
+        "is_array_like",
+        "is_named_tuple",
+        "pandas_dtype",
+        "union_categoricals",
+        "infer_dtype",
+        "is_extension_array_dtype",
+    ]
+    deprecated: list[str] = []
+    dtypes = ["CategoricalDtype", "DatetimeTZDtype", "PeriodDtype", "IntervalDtype"]
+
+    def test_types(self):
+        self.check(types, self.allowed + self.dtypes + self.deprecated)
+
+    def test_deprecated_from_api_types(self):
+        for t in self.deprecated:
+            with tm.assert_produces_warning(FutureWarning):
+                getattr(types, t)(1)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/common.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..b4d153df54059ca2a82f336e19afb4297eb218a2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/common.py
@@ -0,0 +1,7 @@
+from pandas.core.groupby.base import transformation_kernels
+
+# There is no Series.cumcount or DataFrame.cumcount
+series_transform_kernels = [
+    x for x in sorted(transformation_kernels) if x != "cumcount"
+]
+frame_transform_kernels = [x for x in sorted(transformation_kernels) if x != "cumcount"]
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply.py
new file mode 100644
index 0000000000000000000000000000000000000000..1a776892b7bb754e16aaa34e6dbe281b354ee751
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply.py
@@ -0,0 +1,1739 @@
+from datetime import datetime
+import warnings
+
+import numpy as np
+import pytest
+
+from pandas.compat import is_platform_arm
+
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    MultiIndex,
+    Series,
+    Timestamp,
+    date_range,
+)
+import pandas._testing as tm
+from pandas.tests.frame.common import zip_frames
+from pandas.util.version import Version
+
+
+@pytest.fixture
+def int_frame_const_col():
+    """
+    Fixture for DataFrame of ints which are constant per column
+
+    Columns are ['A', 'B', 'C'], with values (per column): [1, 2, 3]
+    """
+    df = DataFrame(
+        np.tile(np.arange(3, dtype="int64"), 6).reshape(6, -1) + 1,
+        columns=["A", "B", "C"],
+    )
+    return df
+
+
+@pytest.fixture(params=["python", pytest.param("numba", marks=pytest.mark.single_cpu)])
+def engine(request):
+    if request.param == "numba":
+        pytest.importorskip("numba")
+    return request.param
+
+
+def test_apply(float_frame, engine, request):
+    if engine == "numba":
+        mark = pytest.mark.xfail(reason="numba engine not supporting numpy ufunc yet")
+        request.node.add_marker(mark)
+    with np.errstate(all="ignore"):
+        # ufunc
+        result = np.sqrt(float_frame["A"])
+        expected = float_frame.apply(np.sqrt, engine=engine)["A"]
+        tm.assert_series_equal(result, expected)
+
+        # aggregator
+        result = float_frame.apply(np.mean, engine=engine)["A"]
+        expected = np.mean(float_frame["A"])
+        assert result == expected
+
+        d = float_frame.index[0]
+        result = float_frame.apply(np.mean, axis=1, engine=engine)
+        expected = np.mean(float_frame.xs(d))
+        assert result[d] == expected
+        assert result.index is float_frame.index
+
+
+@pytest.mark.parametrize("axis", [0, 1])
+@pytest.mark.parametrize("raw", [True, False])
+def test_apply_args(float_frame, axis, raw, engine, request):
+    if engine == "numba":
+        numba = pytest.importorskip("numba")
+        if Version(numba.__version__) == Version("0.61") and is_platform_arm():
+            pytest.skip(f"Segfaults on ARM platforms with numba {numba.__version__}")
+        mark = pytest.mark.xfail(reason="numba engine doesn't support args")
+        request.node.add_marker(mark)
+    result = float_frame.apply(
+        lambda x, y: x + y, axis, args=(1,), raw=raw, engine=engine
+    )
+    expected = float_frame + 1
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_categorical_func():
+    # GH 9573
+    df = DataFrame({"c0": ["A", "A", "B", "B"], "c1": ["C", "C", "D", "D"]})
+    result = df.apply(lambda ts: ts.astype("category"))
+
+    assert result.shape == (4, 2)
+    assert isinstance(result["c0"].dtype, CategoricalDtype)
+    assert isinstance(result["c1"].dtype, CategoricalDtype)
+
+
+def test_apply_axis1_with_ea():
+    # GH#36785
+    expected = DataFrame({"A": [Timestamp("2013-01-01", tz="UTC")]})
+    result = expected.apply(lambda x: x, axis=1)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "data, dtype",
+    [(1, None), (1, CategoricalDtype([1])), (Timestamp("2013-01-01", tz="UTC"), None)],
+)
+def test_agg_axis1_duplicate_index(data, dtype):
+    # GH 42380
+    expected = DataFrame([[data], [data]], index=["a", "a"], dtype=dtype)
+    result = expected.agg(lambda x: x, axis=1)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_mixed_datetimelike():
+    # mixed datetimelike
+    # GH 7778
+    expected = DataFrame(
+        {
+            "A": date_range("20130101", periods=3),
+            "B": pd.to_timedelta(np.arange(3), unit="s"),
+        }
+    )
+    result = expected.apply(lambda x: x, axis=1)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("func", [np.sqrt, np.mean])
+def test_apply_empty(func, engine):
+    # empty
+    empty_frame = DataFrame()
+
+    result = empty_frame.apply(func, engine=engine)
+    assert result.empty
+
+
+def test_apply_float_frame(float_frame, engine):
+    no_rows = float_frame[:0]
+    result = no_rows.apply(lambda x: x.mean(), engine=engine)
+    expected = Series(np.nan, index=float_frame.columns)
+    tm.assert_series_equal(result, expected)
+
+    no_cols = float_frame.loc[:, []]
+    result = no_cols.apply(lambda x: x.mean(), axis=1, engine=engine)
+    expected = Series(np.nan, index=float_frame.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_empty_except_index(engine):
+    # GH 2476
+    expected = DataFrame(index=["a"])
+    result = expected.apply(lambda x: x["a"], axis=1, engine=engine)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_with_reduce_empty():
+    # reduce with an empty DataFrame
+    empty_frame = DataFrame()
+
+    x = []
+    result = empty_frame.apply(x.append, axis=1, result_type="expand")
+    tm.assert_frame_equal(result, empty_frame)
+    result = empty_frame.apply(x.append, axis=1, result_type="reduce")
+    expected = Series([], dtype=np.float64)
+    tm.assert_series_equal(result, expected)
+
+    empty_with_cols = DataFrame(columns=["a", "b", "c"])
+    result = empty_with_cols.apply(x.append, axis=1, result_type="expand")
+    tm.assert_frame_equal(result, empty_with_cols)
+    result = empty_with_cols.apply(x.append, axis=1, result_type="reduce")
+    expected = Series([], dtype=np.float64)
+    tm.assert_series_equal(result, expected)
+
+    # Ensure that x.append hasn't been called
+    assert x == []
+
+
+@pytest.mark.parametrize("func", ["sum", "prod", "any", "all"])
+def test_apply_funcs_over_empty(func):
+    # GH 28213
+    df = DataFrame(columns=["a", "b", "c"])
+
+    result = df.apply(getattr(np, func))
+    expected = getattr(df, func)()
+    if func in ("sum", "prod"):
+        expected = expected.astype(float)
+    tm.assert_series_equal(result, expected)
+
+
+def test_nunique_empty():
+    # GH 28213
+    df = DataFrame(columns=["a", "b", "c"])
+
+    result = df.nunique()
+    expected = Series(0, index=df.columns)
+    tm.assert_series_equal(result, expected)
+
+    result = df.T.nunique()
+    expected = Series([], dtype=np.float64)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_standard_nonunique():
+    df = DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]], index=["a", "a", "c"])
+
+    result = df.apply(lambda s: s[0], axis=1)
+    expected = Series([1, 4, 7], ["a", "a", "c"])
+    tm.assert_series_equal(result, expected)
+
+    result = df.T.apply(lambda s: s[0], axis=0)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_broadcast_scalars(float_frame):
+    # scalars
+    result = float_frame.apply(np.mean, result_type="broadcast")
+    expected = DataFrame([float_frame.mean()], index=float_frame.index)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_broadcast_scalars_axis1(float_frame):
+    result = float_frame.apply(np.mean, axis=1, result_type="broadcast")
+    m = float_frame.mean(axis=1)
+    expected = DataFrame({c: m for c in float_frame.columns})
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_broadcast_lists_columns(float_frame):
+    # lists
+    result = float_frame.apply(
+        lambda x: list(range(len(float_frame.columns))),
+        axis=1,
+        result_type="broadcast",
+    )
+    m = list(range(len(float_frame.columns)))
+    expected = DataFrame(
+        [m] * len(float_frame.index),
+        dtype="float64",
+        index=float_frame.index,
+        columns=float_frame.columns,
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_broadcast_lists_index(float_frame):
+    result = float_frame.apply(
+        lambda x: list(range(len(float_frame.index))), result_type="broadcast"
+    )
+    m = list(range(len(float_frame.index)))
+    expected = DataFrame(
+        {c: m for c in float_frame.columns},
+        dtype="float64",
+        index=float_frame.index,
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_broadcast_list_lambda_func(int_frame_const_col):
+    # preserve columns
+    df = int_frame_const_col
+    result = df.apply(lambda x: [1, 2, 3], axis=1, result_type="broadcast")
+    tm.assert_frame_equal(result, df)
+
+
+def test_apply_broadcast_series_lambda_func(int_frame_const_col):
+    df = int_frame_const_col
+    result = df.apply(
+        lambda x: Series([1, 2, 3], index=list("abc")),
+        axis=1,
+        result_type="broadcast",
+    )
+    expected = df.copy()
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("axis", [0, 1])
+def test_apply_raw_float_frame(float_frame, axis, engine):
+    if engine == "numba":
+        pytest.skip("numba can't handle when UDF returns None.")
+
+    def _assert_raw(x):
+        assert isinstance(x, np.ndarray)
+        assert x.ndim == 1
+
+    float_frame.apply(_assert_raw, axis=axis, engine=engine, raw=True)
+
+
+@pytest.mark.parametrize("axis", [0, 1])
+def test_apply_raw_float_frame_lambda(float_frame, axis, engine):
+    result = float_frame.apply(np.mean, axis=axis, engine=engine, raw=True)
+    expected = float_frame.apply(lambda x: x.values.mean(), axis=axis)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_raw_float_frame_no_reduction(float_frame, engine):
+    # no reduction
+    result = float_frame.apply(lambda x: x * 2, engine=engine, raw=True)
+    expected = float_frame * 2
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("axis", [0, 1])
+def test_apply_raw_mixed_type_frame(axis, engine):
+    if engine == "numba":
+        pytest.skip("isinstance check doesn't work with numba")
+
+    def _assert_raw(x):
+        assert isinstance(x, np.ndarray)
+        assert x.ndim == 1
+
+    # Mixed dtype (GH-32423)
+    df = DataFrame(
+        {
+            "a": 1.0,
+            "b": 2,
+            "c": "foo",
+            "float32": np.array([1.0] * 10, dtype="float32"),
+            "int32": np.array([1] * 10, dtype="int32"),
+        },
+        index=np.arange(10),
+    )
+    df.apply(_assert_raw, axis=axis, engine=engine, raw=True)
+
+
+def test_apply_axis1(float_frame):
+    d = float_frame.index[0]
+    result = float_frame.apply(np.mean, axis=1)[d]
+    expected = np.mean(float_frame.xs(d))
+    assert result == expected
+
+
+def test_apply_mixed_dtype_corner():
+    df = DataFrame({"A": ["foo"], "B": [1.0]})
+    result = df[:0].apply(np.mean, axis=1)
+    # the result here is actually kind of ambiguous, should it be a Series
+    # or a DataFrame?
+    expected = Series(np.nan, index=pd.Index([], dtype="int64"))
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_mixed_dtype_corner_indexing():
+    df = DataFrame({"A": ["foo"], "B": [1.0]})
+    result = df.apply(lambda x: x["A"], axis=1)
+    expected = Series(["foo"], index=[0])
+    tm.assert_series_equal(result, expected)
+
+    result = df.apply(lambda x: x["B"], axis=1)
+    expected = Series([1.0], index=[0])
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.filterwarnings("ignore::RuntimeWarning")
+@pytest.mark.parametrize("ax", ["index", "columns"])
+@pytest.mark.parametrize(
+    "func", [lambda x: x, lambda x: x.mean()], ids=["identity", "mean"]
+)
+@pytest.mark.parametrize("raw", [True, False])
+@pytest.mark.parametrize("axis", [0, 1])
+def test_apply_empty_infer_type(ax, func, raw, axis, engine, request):
+    df = DataFrame(**{ax: ["a", "b", "c"]})
+
+    with np.errstate(all="ignore"):
+        test_res = func(np.array([], dtype="f8"))
+        is_reduction = not isinstance(test_res, np.ndarray)
+
+        result = df.apply(func, axis=axis, engine=engine, raw=raw)
+        if is_reduction:
+            agg_axis = df._get_agg_axis(axis)
+            assert isinstance(result, Series)
+            assert result.index is agg_axis
+        else:
+            assert isinstance(result, DataFrame)
+
+
+def test_apply_empty_infer_type_broadcast():
+    no_cols = DataFrame(index=["a", "b", "c"])
+    result = no_cols.apply(lambda x: x.mean(), result_type="broadcast")
+    assert isinstance(result, DataFrame)
+
+
+def test_apply_with_args_kwds_add_some(float_frame):
+    def add_some(x, howmuch=0):
+        return x + howmuch
+
+    result = float_frame.apply(add_some, howmuch=2)
+    expected = float_frame.apply(lambda x: x + 2)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_with_args_kwds_agg_and_add(float_frame):
+    def agg_and_add(x, howmuch=0):
+        return x.mean() + howmuch
+
+    result = float_frame.apply(agg_and_add, howmuch=2)
+    expected = float_frame.apply(lambda x: x.mean() + 2)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_with_args_kwds_subtract_and_divide(float_frame):
+    def subtract_and_divide(x, sub, divide=1):
+        return (x - sub) / divide
+
+    result = float_frame.apply(subtract_and_divide, args=(2,), divide=2)
+    expected = float_frame.apply(lambda x: (x - 2.0) / 2.0)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_yield_list(float_frame):
+    result = float_frame.apply(list)
+    tm.assert_frame_equal(result, float_frame)
+
+
+def test_apply_reduce_Series(float_frame):
+    float_frame.iloc[::2, float_frame.columns.get_loc("A")] = np.nan
+    expected = float_frame.mean(1)
+    result = float_frame.apply(np.mean, axis=1)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_reduce_to_dict():
+    # GH 25196 37544
+    data = DataFrame([[1, 2], [3, 4]], columns=["c0", "c1"], index=["i0", "i1"])
+
+    result = data.apply(dict, axis=0)
+    expected = Series([{"i0": 1, "i1": 3}, {"i0": 2, "i1": 4}], index=data.columns)
+    tm.assert_series_equal(result, expected)
+
+    result = data.apply(dict, axis=1)
+    expected = Series([{"c0": 1, "c1": 2}, {"c0": 3, "c1": 4}], index=data.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_differently_indexed():
+    df = DataFrame(np.random.default_rng(2).standard_normal((20, 10)))
+
+    result = df.apply(Series.describe, axis=0)
+    expected = DataFrame({i: v.describe() for i, v in df.items()}, columns=df.columns)
+    tm.assert_frame_equal(result, expected)
+
+    result = df.apply(Series.describe, axis=1)
+    expected = DataFrame({i: v.describe() for i, v in df.T.items()}, columns=df.index).T
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_bug():
+    # GH 6125
+    positions = DataFrame(
+        [
+            [1, "ABC0", 50],
+            [1, "YUM0", 20],
+            [1, "DEF0", 20],
+            [2, "ABC1", 50],
+            [2, "YUM1", 20],
+            [2, "DEF1", 20],
+        ],
+        columns=["a", "market", "position"],
+    )
+
+    def f(r):
+        return r["market"]
+
+    expected = positions.apply(f, axis=1)
+
+    positions = DataFrame(
+        [
+            [datetime(2013, 1, 1), "ABC0", 50],
+            [datetime(2013, 1, 2), "YUM0", 20],
+            [datetime(2013, 1, 3), "DEF0", 20],
+            [datetime(2013, 1, 4), "ABC1", 50],
+            [datetime(2013, 1, 5), "YUM1", 20],
+            [datetime(2013, 1, 6), "DEF1", 20],
+        ],
+        columns=["a", "market", "position"],
+    )
+    result = positions.apply(f, axis=1)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_convert_objects():
+    expected = DataFrame(
+        {
+            "A": [
+                "foo",
+                "foo",
+                "foo",
+                "foo",
+                "bar",
+                "bar",
+                "bar",
+                "bar",
+                "foo",
+                "foo",
+                "foo",
+            ],
+            "B": [
+                "one",
+                "one",
+                "one",
+                "two",
+                "one",
+                "one",
+                "one",
+                "two",
+                "two",
+                "two",
+                "one",
+            ],
+            "C": [
+                "dull",
+                "dull",
+                "shiny",
+                "dull",
+                "dull",
+                "shiny",
+                "shiny",
+                "dull",
+                "shiny",
+                "shiny",
+                "shiny",
+            ],
+            "D": np.random.default_rng(2).standard_normal(11),
+            "E": np.random.default_rng(2).standard_normal(11),
+            "F": np.random.default_rng(2).standard_normal(11),
+        }
+    )
+
+    result = expected.apply(lambda x: x, axis=1)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_attach_name(float_frame):
+    result = float_frame.apply(lambda x: x.name)
+    expected = Series(float_frame.columns, index=float_frame.columns)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_attach_name_axis1(float_frame):
+    result = float_frame.apply(lambda x: x.name, axis=1)
+    expected = Series(float_frame.index, index=float_frame.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_attach_name_non_reduction(float_frame):
+    # non-reductions
+    result = float_frame.apply(lambda x: np.repeat(x.name, len(x)))
+    expected = DataFrame(
+        np.tile(float_frame.columns, (len(float_frame.index), 1)),
+        index=float_frame.index,
+        columns=float_frame.columns,
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_attach_name_non_reduction_axis1(float_frame):
+    result = float_frame.apply(lambda x: np.repeat(x.name, len(x)), axis=1)
+    expected = Series(
+        np.repeat(t[0], len(float_frame.columns)) for t in float_frame.itertuples()
+    )
+    expected.index = float_frame.index
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_multi_index():
+    index = MultiIndex.from_arrays([["a", "a", "b"], ["c", "d", "d"]])
+    s = DataFrame([[1, 2], [3, 4], [5, 6]], index=index, columns=["col1", "col2"])
+    result = s.apply(lambda x: Series({"min": min(x), "max": max(x)}), 1)
+    expected = DataFrame([[1, 2], [3, 4], [5, 6]], index=index, columns=["min", "max"])
+    tm.assert_frame_equal(result, expected, check_like=True)
+
+
+@pytest.mark.parametrize(
+    "df, dicts",
+    [
+        [
+            DataFrame([["foo", "bar"], ["spam", "eggs"]]),
+            Series([{0: "foo", 1: "spam"}, {0: "bar", 1: "eggs"}]),
+        ],
+        [DataFrame([[0, 1], [2, 3]]), Series([{0: 0, 1: 2}, {0: 1, 1: 3}])],
+    ],
+)
+def test_apply_dict(df, dicts):
+    # GH 8735
+    fn = lambda x: x.to_dict()
+    reduce_true = df.apply(fn, result_type="reduce")
+    reduce_false = df.apply(fn, result_type="expand")
+    reduce_none = df.apply(fn)
+
+    tm.assert_series_equal(reduce_true, dicts)
+    tm.assert_frame_equal(reduce_false, df)
+    tm.assert_series_equal(reduce_none, dicts)
+
+
+def test_apply_non_numpy_dtype():
+    # GH 12244
+    df = DataFrame({"dt": date_range("2015-01-01", periods=3, tz="Europe/Brussels")})
+    result = df.apply(lambda x: x)
+    tm.assert_frame_equal(result, df)
+
+    result = df.apply(lambda x: x + pd.Timedelta("1day"))
+    expected = DataFrame(
+        {"dt": date_range("2015-01-02", periods=3, tz="Europe/Brussels")}
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_non_numpy_dtype_category():
+    df = DataFrame({"dt": ["a", "b", "c", "a"]}, dtype="category")
+    result = df.apply(lambda x: x)
+    tm.assert_frame_equal(result, df)
+
+
+def test_apply_dup_names_multi_agg():
+    # GH 21063
+    df = DataFrame([[0, 1], [2, 3]], columns=["a", "a"])
+    expected = DataFrame([[0, 1]], columns=["a", "a"], index=["min"])
+    result = df.agg(["min"])
+
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("op", ["apply", "agg"])
+def test_apply_nested_result_axis_1(op):
+    # GH 13820
+    def apply_list(row):
+        return [2 * row["A"], 2 * row["C"], 2 * row["B"]]
+
+    df = DataFrame(np.zeros((4, 4)), columns=list("ABCD"))
+    result = getattr(df, op)(apply_list, axis=1)
+    expected = Series(
+        [[0.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0], [0.0, 0.0, 0.0]]
+    )
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_noreduction_tzaware_object():
+    # https://github.com/pandas-dev/pandas/issues/31505
+    expected = DataFrame(
+        {"foo": [Timestamp("2020", tz="UTC")]}, dtype="datetime64[ns, UTC]"
+    )
+    result = expected.apply(lambda x: x)
+    tm.assert_frame_equal(result, expected)
+    result = expected.apply(lambda x: x.copy())
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_function_runs_once():
+    # https://github.com/pandas-dev/pandas/issues/30815
+
+    df = DataFrame({"a": [1, 2, 3]})
+    names = []  # Save row names function is applied to
+
+    def reducing_function(row):
+        names.append(row.name)
+
+    def non_reducing_function(row):
+        names.append(row.name)
+        return row
+
+    for func in [reducing_function, non_reducing_function]:
+        del names[:]
+
+        df.apply(func, axis=1)
+        assert names == list(df.index)
+
+
+def test_apply_raw_function_runs_once(engine):
+    # https://github.com/pandas-dev/pandas/issues/34506
+    if engine == "numba":
+        pytest.skip("appending to list outside of numba func is not supported")
+
+    df = DataFrame({"a": [1, 2, 3]})
+    values = []  # Save row values function is applied to
+
+    def reducing_function(row):
+        values.extend(row)
+
+    def non_reducing_function(row):
+        values.extend(row)
+        return row
+
+    for func in [reducing_function, non_reducing_function]:
+        del values[:]
+
+        df.apply(func, engine=engine, raw=True, axis=1)
+        assert values == list(df.a.to_list())
+
+
+def test_apply_with_byte_string():
+    # GH 34529
+    df = DataFrame(np.array([b"abcd", b"efgh"]), columns=["col"])
+    expected = DataFrame(np.array([b"abcd", b"efgh"]), columns=["col"], dtype=object)
+    # After we make the apply we expect a dataframe just
+    # like the original but with the object datatype
+    result = df.apply(lambda x: x.astype("object"))
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("val", ["asd", 12, None, np.nan])
+def test_apply_category_equalness(val):
+    # Check if categorical comparisons on apply, GH 21239
+    df_values = ["asd", None, 12, "asd", "cde", np.nan]
+    df = DataFrame({"a": df_values}, dtype="category")
+
+    result = df.a.apply(lambda x: x == val)
+    expected = Series(
+        [np.nan if pd.isnull(x) else x == val for x in df_values], name="a"
+    )
+    tm.assert_series_equal(result, expected)
+
+
+# the user has supplied an opaque UDF where
+# they are transforming the input that requires
+# us to infer the output
+
+
+def test_infer_row_shape():
+    # GH 17437
+    # if row shape is changing, infer it
+    df = DataFrame(np.random.default_rng(2).random((10, 2)))
+    result = df.apply(np.fft.fft, axis=0).shape
+    assert result == (10, 2)
+
+    result = df.apply(np.fft.rfft, axis=0).shape
+    assert result == (6, 2)
+
+
+@pytest.mark.parametrize(
+    "ops, by_row, expected",
+    [
+        ({"a": lambda x: x + 1}, "compat", DataFrame({"a": [2, 3]})),
+        ({"a": lambda x: x + 1}, False, DataFrame({"a": [2, 3]})),
+        ({"a": lambda x: x.sum()}, "compat", Series({"a": 3})),
+        ({"a": lambda x: x.sum()}, False, Series({"a": 3})),
+        (
+            {"a": ["sum", np.sum, lambda x: x.sum()]},
+            "compat",
+            DataFrame({"a": [3, 3, 3]}, index=["sum", "sum", ""]),
+        ),
+        (
+            {"a": ["sum", np.sum, lambda x: x.sum()]},
+            False,
+            DataFrame({"a": [3, 3, 3]}, index=["sum", "sum", ""]),
+        ),
+        ({"a": lambda x: 1}, "compat", DataFrame({"a": [1, 1]})),
+        ({"a": lambda x: 1}, False, Series({"a": 1})),
+    ],
+)
+def test_dictlike_lambda(ops, by_row, expected):
+    # GH53601
+    df = DataFrame({"a": [1, 2]})
+    result = df.apply(ops, by_row=by_row)
+    tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops",
+    [
+        {"a": lambda x: x + 1},
+        {"a": lambda x: x.sum()},
+        {"a": ["sum", np.sum, lambda x: x.sum()]},
+        {"a": lambda x: 1},
+    ],
+)
+def test_dictlike_lambda_raises(ops):
+    # GH53601
+    df = DataFrame({"a": [1, 2]})
+    with pytest.raises(ValueError, match="by_row=True not allowed"):
+        df.apply(ops, by_row=True)
+
+
+def test_with_dictlike_columns():
+    # GH 17602
+    df = DataFrame([[1, 2], [1, 2]], columns=["a", "b"])
+    result = df.apply(lambda x: {"s": x["a"] + x["b"]}, axis=1)
+    expected = Series([{"s": 3} for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+    df["tm"] = [
+        Timestamp("2017-05-01 00:00:00"),
+        Timestamp("2017-05-02 00:00:00"),
+    ]
+    result = df.apply(lambda x: {"s": x["a"] + x["b"]}, axis=1)
+    tm.assert_series_equal(result, expected)
+
+    # compose a series
+    result = (df["a"] + df["b"]).apply(lambda x: {"s": x})
+    expected = Series([{"s": 3}, {"s": 3}])
+    tm.assert_series_equal(result, expected)
+
+
+def test_with_dictlike_columns_with_datetime():
+    # GH 18775
+    df = DataFrame()
+    df["author"] = ["X", "Y", "Z"]
+    df["publisher"] = ["BBC", "NBC", "N24"]
+    df["date"] = pd.to_datetime(
+        ["17-10-2010 07:15:30", "13-05-2011 08:20:35", "15-01-2013 09:09:09"],
+        dayfirst=True,
+    )
+    result = df.apply(lambda x: {}, axis=1)
+    expected = Series([{}, {}, {}])
+    tm.assert_series_equal(result, expected)
+
+
+def test_with_dictlike_columns_with_infer():
+    # GH 17602
+    df = DataFrame([[1, 2], [1, 2]], columns=["a", "b"])
+    result = df.apply(lambda x: {"s": x["a"] + x["b"]}, axis=1, result_type="expand")
+    expected = DataFrame({"s": [3, 3]})
+    tm.assert_frame_equal(result, expected)
+
+    df["tm"] = [
+        Timestamp("2017-05-01 00:00:00"),
+        Timestamp("2017-05-02 00:00:00"),
+    ]
+    result = df.apply(lambda x: {"s": x["a"] + x["b"]}, axis=1, result_type="expand")
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, by_row, expected",
+    [
+        ([lambda x: x + 1], "compat", DataFrame({("a", ""): [2, 3]})),
+        ([lambda x: x + 1], False, DataFrame({("a", ""): [2, 3]})),
+        ([lambda x: x.sum()], "compat", DataFrame({"a": [3]}, index=[""])),
+        ([lambda x: x.sum()], False, DataFrame({"a": [3]}, index=[""])),
+        (
+            ["sum", np.sum, lambda x: x.sum()],
+            "compat",
+            DataFrame({"a": [3, 3, 3]}, index=["sum", "sum", ""]),
+        ),
+        (
+            ["sum", np.sum, lambda x: x.sum()],
+            False,
+            DataFrame({"a": [3, 3, 3]}, index=["sum", "sum", ""]),
+        ),
+        (
+            [lambda x: x + 1, lambda x: 3],
+            "compat",
+            DataFrame([[2, 3], [3, 3]], columns=[["a", "a"], ["", ""]]),
+        ),
+        (
+            [lambda x: 2, lambda x: 3],
+            False,
+            DataFrame({"a": [2, 3]}, ["", ""]),
+        ),
+    ],
+)
+def test_listlike_lambda(ops, by_row, expected):
+    # GH53601
+    df = DataFrame({"a": [1, 2]})
+    result = df.apply(ops, by_row=by_row)
+    tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops",
+    [
+        [lambda x: x + 1],
+        [lambda x: x.sum()],
+        ["sum", np.sum, lambda x: x.sum()],
+        [lambda x: x + 1, lambda x: 3],
+    ],
+)
+def test_listlike_lambda_raises(ops):
+    # GH53601
+    df = DataFrame({"a": [1, 2]})
+    with pytest.raises(ValueError, match="by_row=True not allowed"):
+        df.apply(ops, by_row=True)
+
+
+def test_with_listlike_columns():
+    # GH 17348
+    df = DataFrame(
+        {
+            "a": Series(np.random.default_rng(2).standard_normal(4)),
+            "b": ["a", "list", "of", "words"],
+            "ts": date_range("2016-10-01", periods=4, freq="h"),
+        }
+    )
+
+    result = df[["a", "b"]].apply(tuple, axis=1)
+    expected = Series([t[1:] for t in df[["a", "b"]].itertuples()])
+    tm.assert_series_equal(result, expected)
+
+    result = df[["a", "ts"]].apply(tuple, axis=1)
+    expected = Series([t[1:] for t in df[["a", "ts"]].itertuples()])
+    tm.assert_series_equal(result, expected)
+
+
+def test_with_listlike_columns_returning_list():
+    # GH 18919
+    df = DataFrame({"x": Series([["a", "b"], ["q"]]), "y": Series([["z"], ["q", "t"]])})
+    df.index = MultiIndex.from_tuples([("i0", "j0"), ("i1", "j1")])
+
+    result = df.apply(lambda row: [el for el in row["x"] if el in row["y"]], axis=1)
+    expected = Series([[], ["q"]], index=df.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_infer_output_shape_columns():
+    # GH 18573
+
+    df = DataFrame(
+        {
+            "number": [1.0, 2.0],
+            "string": ["foo", "bar"],
+            "datetime": [
+                Timestamp("2017-11-29 03:30:00"),
+                Timestamp("2017-11-29 03:45:00"),
+            ],
+        }
+    )
+    result = df.apply(lambda row: (row.number, row.string), axis=1)
+    expected = Series([(t.number, t.string) for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+
+def test_infer_output_shape_listlike_columns():
+    # GH 16353
+
+    df = DataFrame(
+        np.random.default_rng(2).standard_normal((6, 3)), columns=["A", "B", "C"]
+    )
+
+    result = df.apply(lambda x: [1, 2, 3], axis=1)
+    expected = Series([[1, 2, 3] for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+    result = df.apply(lambda x: [1, 2], axis=1)
+    expected = Series([[1, 2] for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("val", [1, 2])
+def test_infer_output_shape_listlike_columns_np_func(val):
+    # GH 17970
+    df = DataFrame({"a": [1, 2, 3]}, index=list("abc"))
+
+    result = df.apply(lambda row: np.ones(val), axis=1)
+    expected = Series([np.ones(val) for t in df.itertuples()], index=df.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_infer_output_shape_listlike_columns_with_timestamp():
+    # GH 17892
+    df = DataFrame(
+        {
+            "a": [
+                Timestamp("2010-02-01"),
+                Timestamp("2010-02-04"),
+                Timestamp("2010-02-05"),
+                Timestamp("2010-02-06"),
+            ],
+            "b": [9, 5, 4, 3],
+            "c": [5, 3, 4, 2],
+            "d": [1, 2, 3, 4],
+        }
+    )
+
+    def fun(x):
+        return (1, 2)
+
+    result = df.apply(fun, axis=1)
+    expected = Series([(1, 2) for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("lst", [[1, 2, 3], [1, 2]])
+def test_consistent_coerce_for_shapes(lst):
+    # we want column names to NOT be propagated
+    # just because the shape matches the input shape
+    df = DataFrame(
+        np.random.default_rng(2).standard_normal((4, 3)), columns=["A", "B", "C"]
+    )
+
+    result = df.apply(lambda x: lst, axis=1)
+    expected = Series([lst for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+
+def test_consistent_names(int_frame_const_col):
+    # if a Series is returned, we should use the resulting index names
+    df = int_frame_const_col
+
+    result = df.apply(
+        lambda x: Series([1, 2, 3], index=["test", "other", "cols"]), axis=1
+    )
+    expected = int_frame_const_col.rename(
+        columns={"A": "test", "B": "other", "C": "cols"}
+    )
+    tm.assert_frame_equal(result, expected)
+
+    result = df.apply(lambda x: Series([1, 2], index=["test", "other"]), axis=1)
+    expected = expected[["test", "other"]]
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type(int_frame_const_col):
+    # result_type should be consistent no matter which
+    # path we take in the code
+    df = int_frame_const_col
+
+    result = df.apply(lambda x: [1, 2, 3], axis=1, result_type="expand")
+    expected = df.copy()
+    expected.columns = [0, 1, 2]
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type_shorter_list(int_frame_const_col):
+    # result_type should be consistent no matter which
+    # path we take in the code
+    df = int_frame_const_col
+    result = df.apply(lambda x: [1, 2], axis=1, result_type="expand")
+    expected = df[["A", "B"]].copy()
+    expected.columns = [0, 1]
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type_broadcast(int_frame_const_col, request, engine):
+    # result_type should be consistent no matter which
+    # path we take in the code
+    if engine == "numba":
+        mark = pytest.mark.xfail(reason="numba engine doesn't support list return")
+        request.node.add_marker(mark)
+    df = int_frame_const_col
+    # broadcast result
+    result = df.apply(
+        lambda x: [1, 2, 3], axis=1, result_type="broadcast", engine=engine
+    )
+    expected = df.copy()
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type_broadcast_series_func(int_frame_const_col, engine, request):
+    # result_type should be consistent no matter which
+    # path we take in the code
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="numba Series constructor only support ndarrays not list data"
+        )
+        request.node.add_marker(mark)
+    df = int_frame_const_col
+    columns = ["other", "col", "names"]
+    result = df.apply(
+        lambda x: Series([1, 2, 3], index=columns),
+        axis=1,
+        result_type="broadcast",
+        engine=engine,
+    )
+    expected = df.copy()
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type_series_result(int_frame_const_col, engine, request):
+    # result_type should be consistent no matter which
+    # path we take in the code
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="numba Series constructor only support ndarrays not list data"
+        )
+        request.node.add_marker(mark)
+    df = int_frame_const_col
+    # series result
+    result = df.apply(lambda x: Series([1, 2, 3], index=x.index), axis=1, engine=engine)
+    expected = df.copy()
+    tm.assert_frame_equal(result, expected)
+
+
+def test_result_type_series_result_other_index(int_frame_const_col, engine, request):
+    # result_type should be consistent no matter which
+    # path we take in the code
+
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="no support in numba Series constructor for list of columns"
+        )
+        request.node.add_marker(mark)
+    df = int_frame_const_col
+    # series result with other index
+    columns = ["other", "col", "names"]
+    result = df.apply(lambda x: Series([1, 2, 3], index=columns), axis=1, engine=engine)
+    expected = df.copy()
+    expected.columns = columns
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "box",
+    [lambda x: list(x), lambda x: tuple(x), lambda x: np.array(x, dtype="int64")],
+    ids=["list", "tuple", "array"],
+)
+def test_consistency_for_boxed(box, int_frame_const_col):
+    # passing an array or list should not affect the output shape
+    df = int_frame_const_col
+
+    result = df.apply(lambda x: box([1, 2]), axis=1)
+    expected = Series([box([1, 2]) for t in df.itertuples()])
+    tm.assert_series_equal(result, expected)
+
+    result = df.apply(lambda x: box([1, 2]), axis=1, result_type="expand")
+    expected = int_frame_const_col[["A", "B"]].rename(columns={"A": 0, "B": 1})
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_transform(axis, float_frame):
+    other_axis = 1 if axis in {0, "index"} else 0
+
+    with np.errstate(all="ignore"):
+        f_abs = np.abs(float_frame)
+        f_sqrt = np.sqrt(float_frame)
+
+        # ufunc
+        expected = f_sqrt.copy()
+        result = float_frame.apply(np.sqrt, axis=axis)
+        tm.assert_frame_equal(result, expected)
+
+        # list-like
+        result = float_frame.apply([np.sqrt], axis=axis)
+        expected = f_sqrt.copy()
+        if axis in {0, "index"}:
+            expected.columns = MultiIndex.from_product([float_frame.columns, ["sqrt"]])
+        else:
+            expected.index = MultiIndex.from_product([float_frame.index, ["sqrt"]])
+        tm.assert_frame_equal(result, expected)
+
+        # multiple items in list
+        # these are in the order as if we are applying both
+        # functions per series and then concatting
+        result = float_frame.apply([np.abs, np.sqrt], axis=axis)
+        expected = zip_frames([f_abs, f_sqrt], axis=other_axis)
+        if axis in {0, "index"}:
+            expected.columns = MultiIndex.from_product(
+                [float_frame.columns, ["absolute", "sqrt"]]
+            )
+        else:
+            expected.index = MultiIndex.from_product(
+                [float_frame.index, ["absolute", "sqrt"]]
+            )
+        tm.assert_frame_equal(result, expected)
+
+
+def test_demo():
+    # demonstration tests
+    df = DataFrame({"A": range(5), "B": 5})
+
+    result = df.agg(["min", "max"])
+    expected = DataFrame(
+        {"A": [0, 4], "B": [5, 5]}, columns=["A", "B"], index=["min", "max"]
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_demo_dict_agg():
+    # demonstration tests
+    df = DataFrame({"A": range(5), "B": 5})
+    result = df.agg({"A": ["min", "max"], "B": ["sum", "max"]})
+    expected = DataFrame(
+        {"A": [4.0, 0.0, np.nan], "B": [5.0, np.nan, 25.0]},
+        columns=["A", "B"],
+        index=["max", "min", "sum"],
+    )
+    tm.assert_frame_equal(result.reindex_like(expected), expected)
+
+
+def test_agg_with_name_as_column_name():
+    # GH 36212 - Column name is "name"
+    data = {"name": ["foo", "bar"]}
+    df = DataFrame(data)
+
+    # result's name should be None
+    result = df.agg({"name": "count"})
+    expected = Series({"name": 2})
+    tm.assert_series_equal(result, expected)
+
+    # Check if name is still preserved when aggregating series instead
+    result = df["name"].agg({"name": "count"})
+    expected = Series({"name": 2}, name="name")
+    tm.assert_series_equal(result, expected)
+
+
+def test_agg_multiple_mixed():
+    # GH 20909
+    mdf = DataFrame(
+        {
+            "A": [1, 2, 3],
+            "B": [1.0, 2.0, 3.0],
+            "C": ["foo", "bar", "baz"],
+        }
+    )
+    expected = DataFrame(
+        {
+            "A": [1, 6],
+            "B": [1.0, 6.0],
+            "C": ["bar", "foobarbaz"],
+        },
+        index=["min", "sum"],
+    )
+    # sorted index
+    result = mdf.agg(["min", "sum"])
+    tm.assert_frame_equal(result, expected)
+
+    result = mdf[["C", "B", "A"]].agg(["sum", "min"])
+    # GH40420: the result of .agg should have an index that is sorted
+    # according to the arguments provided to agg.
+    expected = expected[["C", "B", "A"]].reindex(["sum", "min"])
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_multiple_mixed_raises():
+    # GH 20909
+    mdf = DataFrame(
+        {
+            "A": [1, 2, 3],
+            "B": [1.0, 2.0, 3.0],
+            "C": ["foo", "bar", "baz"],
+            "D": date_range("20130101", periods=3),
+        }
+    )
+
+    # sorted index
+    msg = "does not support reduction"
+    with pytest.raises(TypeError, match=msg):
+        mdf.agg(["min", "sum"])
+
+    with pytest.raises(TypeError, match=msg):
+        mdf[["D", "C", "B", "A"]].agg(["sum", "min"])
+
+
+def test_agg_reduce(axis, float_frame):
+    other_axis = 1 if axis in {0, "index"} else 0
+    name1, name2 = float_frame.axes[other_axis].unique()[:2].sort_values()
+
+    # all reducers
+    expected = pd.concat(
+        [
+            float_frame.mean(axis=axis),
+            float_frame.max(axis=axis),
+            float_frame.sum(axis=axis),
+        ],
+        axis=1,
+    )
+    expected.columns = ["mean", "max", "sum"]
+    expected = expected.T if axis in {0, "index"} else expected
+
+    result = float_frame.agg(["mean", "max", "sum"], axis=axis)
+    tm.assert_frame_equal(result, expected)
+
+    # dict input with scalars
+    func = {name1: "mean", name2: "sum"}
+    result = float_frame.agg(func, axis=axis)
+    expected = Series(
+        [
+            float_frame.loc(other_axis)[name1].mean(),
+            float_frame.loc(other_axis)[name2].sum(),
+        ],
+        index=[name1, name2],
+    )
+    tm.assert_series_equal(result, expected)
+
+    # dict input with lists
+    func = {name1: ["mean"], name2: ["sum"]}
+    result = float_frame.agg(func, axis=axis)
+    expected = DataFrame(
+        {
+            name1: Series([float_frame.loc(other_axis)[name1].mean()], index=["mean"]),
+            name2: Series([float_frame.loc(other_axis)[name2].sum()], index=["sum"]),
+        }
+    )
+    expected = expected.T if axis in {1, "columns"} else expected
+    tm.assert_frame_equal(result, expected)
+
+    # dict input with lists with multiple
+    func = {name1: ["mean", "sum"], name2: ["sum", "max"]}
+    result = float_frame.agg(func, axis=axis)
+    expected = pd.concat(
+        {
+            name1: Series(
+                [
+                    float_frame.loc(other_axis)[name1].mean(),
+                    float_frame.loc(other_axis)[name1].sum(),
+                ],
+                index=["mean", "sum"],
+            ),
+            name2: Series(
+                [
+                    float_frame.loc(other_axis)[name2].sum(),
+                    float_frame.loc(other_axis)[name2].max(),
+                ],
+                index=["sum", "max"],
+            ),
+        },
+        axis=1,
+    )
+    expected = expected.T if axis in {1, "columns"} else expected
+    tm.assert_frame_equal(result, expected)
+
+
+def test_nuiscance_columns():
+    # GH 15015
+    df = DataFrame(
+        {
+            "A": [1, 2, 3],
+            "B": [1.0, 2.0, 3.0],
+            "C": ["foo", "bar", "baz"],
+            "D": date_range("20130101", periods=3),
+        }
+    )
+
+    result = df.agg("min")
+    expected = Series([1, 1.0, "bar", Timestamp("20130101")], index=df.columns)
+    tm.assert_series_equal(result, expected)
+
+    result = df.agg(["min"])
+    expected = DataFrame(
+        [[1, 1.0, "bar", Timestamp("20130101").as_unit("ns")]],
+        index=["min"],
+        columns=df.columns,
+    )
+    tm.assert_frame_equal(result, expected)
+
+    msg = "does not support reduction"
+    with pytest.raises(TypeError, match=msg):
+        df.agg("sum")
+
+    result = df[["A", "B", "C"]].agg("sum")
+    expected = Series([6, 6.0, "foobarbaz"], index=["A", "B", "C"])
+    tm.assert_series_equal(result, expected)
+
+    msg = "does not support reduction"
+    with pytest.raises(TypeError, match=msg):
+        df.agg(["sum"])
+
+
+@pytest.mark.parametrize("how", ["agg", "apply"])
+def test_non_callable_aggregates(how):
+    # GH 16405
+    # 'size' is a property of frame/series
+    # validate that this is working
+    # GH 39116 - expand to apply
+    df = DataFrame(
+        {"A": [None, 2, 3], "B": [1.0, np.nan, 3.0], "C": ["foo", None, "bar"]}
+    )
+
+    # Function aggregate
+    result = getattr(df, how)({"A": "count"})
+    expected = Series({"A": 2})
+
+    tm.assert_series_equal(result, expected)
+
+    # Non-function aggregate
+    result = getattr(df, how)({"A": "size"})
+    expected = Series({"A": 3})
+
+    tm.assert_series_equal(result, expected)
+
+    # Mix function and non-function aggs
+    result1 = getattr(df, how)(["count", "size"])
+    result2 = getattr(df, how)(
+        {"A": ["count", "size"], "B": ["count", "size"], "C": ["count", "size"]}
+    )
+    expected = DataFrame(
+        {
+            "A": {"count": 2, "size": 3},
+            "B": {"count": 2, "size": 3},
+            "C": {"count": 2, "size": 3},
+        }
+    )
+
+    tm.assert_frame_equal(result1, result2, check_like=True)
+    tm.assert_frame_equal(result2, expected, check_like=True)
+
+    # Just functional string arg is same as calling df.arg()
+    result = getattr(df, how)("count")
+    expected = df.count()
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("how", ["agg", "apply"])
+def test_size_as_str(how, axis):
+    # GH 39934
+    df = DataFrame(
+        {"A": [None, 2, 3], "B": [1.0, np.nan, 3.0], "C": ["foo", None, "bar"]}
+    )
+    # Just a string attribute arg same as calling df.arg
+    # on the columns
+    result = getattr(df, how)("size", axis=axis)
+    if axis in (0, "index"):
+        expected = Series(df.shape[0], index=df.columns)
+    else:
+        expected = Series(df.shape[1], index=df.index)
+    tm.assert_series_equal(result, expected)
+
+
+def test_agg_listlike_result():
+    # GH-29587 user defined function returning list-likes
+    df = DataFrame({"A": [2, 2, 3], "B": [1.5, np.nan, 1.5], "C": ["foo", None, "bar"]})
+
+    def func(group_col):
+        return list(group_col.dropna().unique())
+
+    result = df.agg(func)
+    expected = Series([[2, 3], [1.5], ["foo", "bar"]], index=["A", "B", "C"])
+    tm.assert_series_equal(result, expected)
+
+    result = df.agg([func])
+    expected = expected.to_frame("func").T
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("axis", [0, 1])
+@pytest.mark.parametrize(
+    "args, kwargs",
+    [
+        ((1, 2, 3), {}),
+        ((8, 7, 15), {}),
+        ((1, 2), {}),
+        ((1,), {"b": 2}),
+        ((), {"a": 1, "b": 2}),
+        ((), {"a": 2, "b": 1}),
+        ((), {"a": 1, "b": 2, "c": 3}),
+    ],
+)
+def test_agg_args_kwargs(axis, args, kwargs):
+    def f(x, a, b, c=3):
+        return x.sum() + (a + b) / c
+
+    df = DataFrame([[1, 2], [3, 4]])
+
+    if axis == 0:
+        expected = Series([5.0, 7.0])
+    else:
+        expected = Series([4.0, 8.0])
+
+    result = df.agg(f, axis, *args, **kwargs)
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("num_cols", [2, 3, 5])
+def test_frequency_is_original(num_cols, engine, request):
+    # GH 22150
+    if engine == "numba":
+        mark = pytest.mark.xfail(reason="numba engine only supports numeric indices")
+        request.node.add_marker(mark)
+    index = pd.DatetimeIndex(["1950-06-30", "1952-10-24", "1953-05-29"])
+    original = index.copy()
+    df = DataFrame(1, index=index, columns=range(num_cols))
+    df.apply(lambda x: x, engine=engine)
+    assert index.freq == original.freq
+
+
+def test_apply_datetime_tz_issue(engine, request):
+    # GH 29052
+
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="numba engine doesn't support non-numeric indexes"
+        )
+        request.node.add_marker(mark)
+
+    timestamps = [
+        Timestamp("2019-03-15 12:34:31.909000+0000", tz="UTC"),
+        Timestamp("2019-03-15 12:34:34.359000+0000", tz="UTC"),
+        Timestamp("2019-03-15 12:34:34.660000+0000", tz="UTC"),
+    ]
+    df = DataFrame(data=[0, 1, 2], index=timestamps)
+    result = df.apply(lambda x: x.name, axis=1, engine=engine)
+    expected = Series(index=timestamps, data=timestamps)
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("df", [DataFrame({"A": ["a", None], "B": ["c", "d"]})])
+@pytest.mark.parametrize("method", ["min", "max", "sum"])
+def test_mixed_column_raises(df, method, using_infer_string):
+    # GH 16832
+    if method == "sum":
+        msg = r'can only concatenate str \(not "int"\) to str|does not support'
+    else:
+        msg = "not supported between instances of 'str' and 'float'"
+    if not using_infer_string:
+        with pytest.raises(TypeError, match=msg):
+            getattr(df, method)()
+    else:
+        getattr(df, method)()
+
+
+@pytest.mark.parametrize("col", [1, 1.0, True, "a", np.nan])
+def test_apply_dtype(col):
+    # GH 31466
+    df = DataFrame([[1.0, col]], columns=["a", "b"])
+    result = df.apply(lambda x: x.dtype)
+    expected = df.dtypes
+
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_mutating(using_array_manager, using_copy_on_write, warn_copy_on_write):
+    # GH#35462 case where applied func pins a new BlockManager to a row
+    df = DataFrame({"a": range(100), "b": range(100, 200)})
+    df_orig = df.copy()
+
+    def func(row):
+        mgr = row._mgr
+        row.loc["a"] += 1
+        assert row._mgr is not mgr
+        return row
+
+    expected = df.copy()
+    expected["a"] += 1
+
+    with tm.assert_cow_warning(warn_copy_on_write):
+        result = df.apply(func, axis=1)
+
+    tm.assert_frame_equal(result, expected)
+    if using_copy_on_write or using_array_manager:
+        # INFO(CoW) With copy on write, mutating a viewing row doesn't mutate the parent
+        # INFO(ArrayManager) With BlockManager, the row is a view and mutated in place,
+        # with ArrayManager the row is not a view, and thus not mutated in place
+        tm.assert_frame_equal(df, df_orig)
+    else:
+        tm.assert_frame_equal(df, result)
+
+
+def test_apply_empty_list_reduce():
+    # GH#35683 get columns correct
+    df = DataFrame([[1, 2], [3, 4], [5, 6], [7, 8], [9, 10]], columns=["a", "b"])
+
+    result = df.apply(lambda x: [], result_type="reduce")
+    expected = Series({"a": [], "b": []}, dtype=object)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_no_suffix_index(engine, request):
+    # GH36189
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="numba engine doesn't support list-likes/dict-like callables"
+        )
+        request.node.add_marker(mark)
+    pdf = DataFrame([[4, 9]] * 3, columns=["A", "B"])
+    result = pdf.apply(["sum", lambda x: x.sum(), lambda x: x.sum()], engine=engine)
+    expected = DataFrame(
+        {"A": [12, 12, 12], "B": [27, 27, 27]}, index=["sum", "", ""]
+    )
+
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_raw_returns_string(engine):
+    # https://github.com/pandas-dev/pandas/issues/35940
+    if engine == "numba":
+        pytest.skip("No object dtype support in numba")
+    df = DataFrame({"A": ["aa", "bbb"]})
+    result = df.apply(lambda x: x[0], engine=engine, axis=1, raw=True)
+    expected = Series(["aa", "bbb"])
+    tm.assert_series_equal(result, expected)
+
+
+def test_aggregation_func_column_order():
+    # GH40420: the result of .agg should have an index that is sorted
+    # according to the arguments provided to agg.
+    df = DataFrame(
+        [
+            (1, 0, 0),
+            (2, 0, 0),
+            (3, 0, 0),
+            (4, 5, 4),
+            (5, 6, 6),
+            (6, 7, 7),
+        ],
+        columns=("att1", "att2", "att3"),
+    )
+
+    def sum_div2(s):
+        return s.sum() / 2
+
+    aggs = ["sum", sum_div2, "count", "min"]
+    result = df.agg(aggs)
+    expected = DataFrame(
+        {
+            "att1": [21.0, 10.5, 6.0, 1.0],
+            "att2": [18.0, 9.0, 6.0, 0.0],
+            "att3": [17.0, 8.5, 6.0, 0.0],
+        },
+        index=["sum", "sum_div2", "count", "min"],
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_getitem_axis_1(engine, request):
+    # GH 13427
+    if engine == "numba":
+        mark = pytest.mark.xfail(
+            reason="numba engine not supporting duplicate index values"
+        )
+        request.node.add_marker(mark)
+    df = DataFrame({"a": [0, 1, 2], "b": [1, 2, 3]})
+    result = df[["a", "a"]].apply(
+        lambda x: x.iloc[0] + x.iloc[1], axis=1, engine=engine
+    )
+    expected = Series([0, 2, 4])
+    tm.assert_series_equal(result, expected)
+
+
+def test_nuisance_depr_passes_through_warnings():
+    # GH 43740
+    # DataFrame.agg with list-likes may emit warnings for both individual
+    # args and for entire columns, but we only want to emit once. We
+    # catch and suppress the warnings for individual args, but need to make
+    # sure if some other warnings were raised, they get passed through to
+    # the user.
+
+    def expected_warning(x):
+        warnings.warn("Hello, World!")
+        return x.sum()
+
+    df = DataFrame({"a": [1, 2, 3]})
+    with tm.assert_produces_warning(UserWarning, match="Hello, World!"):
+        df.agg([expected_warning])
+
+
+def test_apply_type():
+    # GH 46719
+    df = DataFrame(
+        {"col1": [3, "string", float], "col2": [0.25, datetime(2020, 1, 1), np.nan]},
+        index=["a", "b", "c"],
+    )
+
+    # axis=0
+    result = df.apply(type, axis=0)
+    expected = Series({"col1": Series, "col2": Series})
+    tm.assert_series_equal(result, expected)
+
+    # axis=1
+    result = df.apply(type, axis=1)
+    expected = Series({"a": Series, "b": Series, "c": Series})
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_on_empty_dataframe(engine):
+    # GH 39111
+    df = DataFrame({"a": [1, 2], "b": [3, 0]})
+    result = df.head(0).apply(lambda x: max(x["a"], x["b"]), axis=1, engine=engine)
+    expected = Series([], dtype=np.float64)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_return_list():
+    df = DataFrame({"a": [1, 2], "b": [2, 3]})
+    result = df.apply(lambda x: [x.values])
+    expected = DataFrame({"a": [[1, 2]], "b": [[2, 3]]})
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "test, constant",
+    [
+        ({"a": [1, 2, 3], "b": [1, 1, 1]}, {"a": [1, 2, 3], "b": [1]}),
+        ({"a": [2, 2, 2], "b": [1, 1, 1]}, {"a": [2], "b": [1]}),
+    ],
+)
+def test_unique_agg_type_is_series(test, constant):
+    # GH#22558
+    df1 = DataFrame(test)
+    expected = Series(data=constant, index=["a", "b"], dtype="object")
+    aggregation = {"a": "unique", "b": "unique"}
+
+    result = df1.agg(aggregation)
+
+    tm.assert_series_equal(result, expected)
+
+
+def test_any_apply_keyword_non_zero_axis_regression():
+    # https://github.com/pandas-dev/pandas/issues/48656
+    df = DataFrame({"A": [1, 2, 0], "B": [0, 2, 0], "C": [0, 0, 0]})
+    expected = Series([True, True, False])
+    tm.assert_series_equal(df.any(axis=1), expected)
+
+    result = df.apply("any", axis=1)
+    tm.assert_series_equal(result, expected)
+
+    result = df.apply("any", 1)
+    tm.assert_series_equal(result, expected)
+
+
+def test_agg_mapping_func_deprecated():
+    # GH 53325
+    df = DataFrame({"x": [1, 2, 3]})
+
+    def foo1(x, a=1, c=0):
+        return x + a + c
+
+    def foo2(x, b=2, c=0):
+        return x + b + c
+
+    # single func already takes the vectorized path
+    result = df.agg(foo1, 0, 3, c=4)
+    expected = df + 7
+    tm.assert_frame_equal(result, expected)
+
+    msg = "using .+ in Series.agg cannot aggregate and"
+
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df.agg([foo1, foo2], 0, 3, c=4)
+    expected = DataFrame(
+        [[8, 8], [9, 9], [10, 10]], columns=[["x", "x"], ["foo1", "foo2"]]
+    )
+    tm.assert_frame_equal(result, expected)
+
+    # TODO: the result below is wrong, should be fixed (GH53325)
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df.agg({"x": foo1}, 0, 3, c=4)
+    expected = DataFrame([2, 3, 4], columns=["x"])
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_std():
+    df = DataFrame(np.arange(6).reshape(3, 2), columns=["A", "B"])
+
+    with tm.assert_produces_warning(FutureWarning, match="using DataFrame.std"):
+        result = df.agg(np.std)
+    expected = Series({"A": 2.0, "B": 2.0}, dtype=float)
+    tm.assert_series_equal(result, expected)
+
+    with tm.assert_produces_warning(FutureWarning, match="using Series.std"):
+        result = df.agg([np.std])
+    expected = DataFrame({"A": 2.0, "B": 2.0}, index=["std"])
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_dist_like_and_nonunique_columns():
+    # GH#51099
+    df = DataFrame(
+        {"A": [None, 2, 3], "B": [1.0, np.nan, 3.0], "C": ["foo", None, "bar"]}
+    )
+    df.columns = ["A", "A", "C"]
+
+    result = df.agg({"A": "count"})
+    expected = df["A"].count()
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply_relabeling.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply_relabeling.py
new file mode 100644
index 0000000000000000000000000000000000000000..723bdd349c0cb8a8f3fe73ded665b6d22260ffb5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_apply_relabeling.py
@@ -0,0 +1,113 @@
+import numpy as np
+import pytest
+
+from pandas.compat.numpy import np_version_gte1p25
+
+import pandas as pd
+import pandas._testing as tm
+
+
+def test_agg_relabel():
+    # GH 26513
+    df = pd.DataFrame({"A": [1, 2, 1, 2], "B": [1, 2, 3, 4], "C": [3, 4, 5, 6]})
+
+    # simplest case with one column, one func
+    result = df.agg(foo=("B", "sum"))
+    expected = pd.DataFrame({"B": [10]}, index=pd.Index(["foo"]))
+    tm.assert_frame_equal(result, expected)
+
+    # test on same column with different methods
+    result = df.agg(foo=("B", "sum"), bar=("B", "min"))
+    expected = pd.DataFrame({"B": [10, 1]}, index=pd.Index(["foo", "bar"]))
+
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_relabel_multi_columns_multi_methods():
+    # GH 26513, test on multiple columns with multiple methods
+    df = pd.DataFrame({"A": [1, 2, 1, 2], "B": [1, 2, 3, 4], "C": [3, 4, 5, 6]})
+    result = df.agg(
+        foo=("A", "sum"),
+        bar=("B", "mean"),
+        cat=("A", "min"),
+        dat=("B", "max"),
+        f=("A", "max"),
+        g=("C", "min"),
+    )
+    expected = pd.DataFrame(
+        {
+            "A": [6.0, np.nan, 1.0, np.nan, 2.0, np.nan],
+            "B": [np.nan, 2.5, np.nan, 4.0, np.nan, np.nan],
+            "C": [np.nan, np.nan, np.nan, np.nan, np.nan, 3.0],
+        },
+        index=pd.Index(["foo", "bar", "cat", "dat", "f", "g"]),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.xfail(np_version_gte1p25, reason="name of min now equals name of np.min")
+def test_agg_relabel_partial_functions():
+    # GH 26513, test on partial, functools or more complex cases
+    df = pd.DataFrame({"A": [1, 2, 1, 2], "B": [1, 2, 3, 4], "C": [3, 4, 5, 6]})
+    msg = "using Series.[mean|min]"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df.agg(foo=("A", np.mean), bar=("A", "mean"), cat=("A", min))
+    expected = pd.DataFrame(
+        {"A": [1.5, 1.5, 1.0]}, index=pd.Index(["foo", "bar", "cat"])
+    )
+    tm.assert_frame_equal(result, expected)
+
+    msg = "using Series.[mean|min|max|sum]"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df.agg(
+            foo=("A", min),
+            bar=("A", np.min),
+            cat=("B", max),
+            dat=("C", "min"),
+            f=("B", np.sum),
+            kk=("B", lambda x: min(x)),
+        )
+    expected = pd.DataFrame(
+        {
+            "A": [1.0, 1.0, np.nan, np.nan, np.nan, np.nan],
+            "B": [np.nan, np.nan, 4.0, np.nan, 10.0, 1.0],
+            "C": [np.nan, np.nan, np.nan, 3.0, np.nan, np.nan],
+        },
+        index=pd.Index(["foo", "bar", "cat", "dat", "f", "kk"]),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_agg_namedtuple():
+    # GH 26513
+    df = pd.DataFrame({"A": [0, 1], "B": [1, 2]})
+    result = df.agg(
+        foo=pd.NamedAgg("B", "sum"),
+        bar=pd.NamedAgg("B", "min"),
+        cat=pd.NamedAgg(column="B", aggfunc="count"),
+        fft=pd.NamedAgg("B", aggfunc="max"),
+    )
+
+    expected = pd.DataFrame(
+        {"B": [3, 1, 2, 2]}, index=pd.Index(["foo", "bar", "cat", "fft"])
+    )
+    tm.assert_frame_equal(result, expected)
+
+    result = df.agg(
+        foo=pd.NamedAgg("A", "min"),
+        bar=pd.NamedAgg(column="B", aggfunc="max"),
+        cat=pd.NamedAgg(column="A", aggfunc="max"),
+    )
+    expected = pd.DataFrame(
+        {"A": [0.0, np.nan, 1.0], "B": [np.nan, 2.0, np.nan]},
+        index=pd.Index(["foo", "bar", "cat"]),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_reconstruct_func():
+    # GH 28472, test to ensure reconstruct_func isn't moved;
+    # This method is used by other libraries (e.g. dask)
+    result = pd.core.apply.reconstruct_func("min")
+    expected = (False, "min", None, None)
+    tm.assert_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_transform.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_transform.py
new file mode 100644
index 0000000000000000000000000000000000000000..558d76ae8fdc4b95d46bbe94e15822779bd7c53f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_frame_transform.py
@@ -0,0 +1,264 @@
+import numpy as np
+import pytest
+
+from pandas import (
+    DataFrame,
+    MultiIndex,
+    Series,
+)
+import pandas._testing as tm
+from pandas.tests.apply.common import frame_transform_kernels
+from pandas.tests.frame.common import zip_frames
+
+
+def unpack_obj(obj, klass, axis):
+    """
+    Helper to ensure we have the right type of object for a test parametrized
+    over frame_or_series.
+    """
+    if klass is not DataFrame:
+        obj = obj["A"]
+        if axis != 0:
+            pytest.skip(f"Test is only for DataFrame with axis={axis}")
+    return obj
+
+
+def test_transform_ufunc(axis, float_frame, frame_or_series):
+    # GH 35964
+    obj = unpack_obj(float_frame, frame_or_series, axis)
+
+    with np.errstate(all="ignore"):
+        f_sqrt = np.sqrt(obj)
+
+    # ufunc
+    result = obj.transform(np.sqrt, axis=axis)
+    expected = f_sqrt
+    tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, names",
+    [
+        ([np.sqrt], ["sqrt"]),
+        ([np.abs, np.sqrt], ["absolute", "sqrt"]),
+        (np.array([np.sqrt]), ["sqrt"]),
+        (np.array([np.abs, np.sqrt]), ["absolute", "sqrt"]),
+    ],
+)
+def test_transform_listlike(axis, float_frame, ops, names):
+    # GH 35964
+    other_axis = 1 if axis in {0, "index"} else 0
+    with np.errstate(all="ignore"):
+        expected = zip_frames([op(float_frame) for op in ops], axis=other_axis)
+    if axis in {0, "index"}:
+        expected.columns = MultiIndex.from_product([float_frame.columns, names])
+    else:
+        expected.index = MultiIndex.from_product([float_frame.index, names])
+    result = float_frame.transform(ops, axis=axis)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("ops", [[], np.array([])])
+def test_transform_empty_listlike(float_frame, ops, frame_or_series):
+    obj = unpack_obj(float_frame, frame_or_series, 0)
+
+    with pytest.raises(ValueError, match="No transform functions were provided"):
+        obj.transform(ops)
+
+
+def test_transform_listlike_func_with_args():
+    # GH 50624
+    df = DataFrame({"x": [1, 2, 3]})
+
+    def foo1(x, a=1, c=0):
+        return x + a + c
+
+    def foo2(x, b=2, c=0):
+        return x + b + c
+
+    msg = r"foo1\(\) got an unexpected keyword argument 'b'"
+    with pytest.raises(TypeError, match=msg):
+        df.transform([foo1, foo2], 0, 3, b=3, c=4)
+
+    result = df.transform([foo1, foo2], 0, 3, c=4)
+    expected = DataFrame(
+        [[8, 8], [9, 9], [10, 10]],
+        columns=MultiIndex.from_tuples([("x", "foo1"), ("x", "foo2")]),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("box", [dict, Series])
+def test_transform_dictlike(axis, float_frame, box):
+    # GH 35964
+    if axis in (0, "index"):
+        e = float_frame.columns[0]
+        expected = float_frame[[e]].transform(np.abs)
+    else:
+        e = float_frame.index[0]
+        expected = float_frame.iloc[[0]].transform(np.abs)
+    result = float_frame.transform(box({e: np.abs}), axis=axis)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_transform_dictlike_mixed():
+    # GH 40018 - mix of lists and non-lists in values of a dictionary
+    df = DataFrame({"a": [1, 2], "b": [1, 4], "c": [1, 4]})
+    result = df.transform({"b": ["sqrt", "abs"], "c": "sqrt"})
+    expected = DataFrame(
+        [[1.0, 1, 1.0], [2.0, 4, 2.0]],
+        columns=MultiIndex([("b", "c"), ("sqrt", "abs")], [(0, 0, 1), (0, 1, 0)]),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops",
+    [
+        {},
+        {"A": []},
+        {"A": [], "B": "cumsum"},
+        {"A": "cumsum", "B": []},
+        {"A": [], "B": ["cumsum"]},
+        {"A": ["cumsum"], "B": []},
+    ],
+)
+def test_transform_empty_dictlike(float_frame, ops, frame_or_series):
+    obj = unpack_obj(float_frame, frame_or_series, 0)
+
+    with pytest.raises(ValueError, match="No transform functions were provided"):
+        obj.transform(ops)
+
+
+@pytest.mark.parametrize("use_apply", [True, False])
+def test_transform_udf(axis, float_frame, use_apply, frame_or_series):
+    # GH 35964
+    obj = unpack_obj(float_frame, frame_or_series, axis)
+
+    # transform uses UDF either via apply or passing the entire DataFrame
+    def func(x):
+        # transform is using apply iff x is not a DataFrame
+        if use_apply == isinstance(x, frame_or_series):
+            # Force transform to fallback
+            raise ValueError
+        return x + 1
+
+    result = obj.transform(func, axis=axis)
+    expected = obj + 1
+    tm.assert_equal(result, expected)
+
+
+wont_fail = ["ffill", "bfill", "fillna", "pad", "backfill", "shift"]
+frame_kernels_raise = [x for x in frame_transform_kernels if x not in wont_fail]
+
+
+@pytest.mark.parametrize("op", [*frame_kernels_raise, lambda x: x + 1])
+def test_transform_bad_dtype(op, frame_or_series, request):
+    # GH 35964
+    if op == "ngroup":
+        request.applymarker(
+            pytest.mark.xfail(raises=ValueError, reason="ngroup not valid for NDFrame")
+        )
+
+    obj = DataFrame({"A": 3 * [object]})  # DataFrame that will fail on most transforms
+    obj = tm.get_obj(obj, frame_or_series)
+    error = TypeError
+    msg = "|".join(
+        [
+            "not supported between instances of 'type' and 'type'",
+            "unsupported operand type",
+        ]
+    )
+
+    with pytest.raises(error, match=msg):
+        obj.transform(op)
+    with pytest.raises(error, match=msg):
+        obj.transform([op])
+    with pytest.raises(error, match=msg):
+        obj.transform({"A": op})
+    with pytest.raises(error, match=msg):
+        obj.transform({"A": [op]})
+
+
+@pytest.mark.parametrize("op", frame_kernels_raise)
+def test_transform_failure_typeerror(request, op):
+    # GH 35964
+
+    if op == "ngroup":
+        request.applymarker(
+            pytest.mark.xfail(raises=ValueError, reason="ngroup not valid for NDFrame")
+        )
+
+    # Using object makes most transform kernels fail
+    df = DataFrame({"A": 3 * [object], "B": [1, 2, 3]})
+    error = TypeError
+    msg = "|".join(
+        [
+            "not supported between instances of 'type' and 'type'",
+            "unsupported operand type",
+        ]
+    )
+
+    with pytest.raises(error, match=msg):
+        df.transform([op])
+
+    with pytest.raises(error, match=msg):
+        df.transform({"A": op, "B": op})
+
+    with pytest.raises(error, match=msg):
+        df.transform({"A": [op], "B": [op]})
+
+    with pytest.raises(error, match=msg):
+        df.transform({"A": [op, "shift"], "B": [op]})
+
+
+def test_transform_failure_valueerror():
+    # GH 40211
+    def op(x):
+        if np.sum(np.sum(x)) < 10:
+            raise ValueError
+        return x
+
+    df = DataFrame({"A": [1, 2, 3], "B": [400, 500, 600]})
+    msg = "Transform function failed"
+
+    with pytest.raises(ValueError, match=msg):
+        df.transform([op])
+
+    with pytest.raises(ValueError, match=msg):
+        df.transform({"A": op, "B": op})
+
+    with pytest.raises(ValueError, match=msg):
+        df.transform({"A": [op], "B": [op]})
+
+    with pytest.raises(ValueError, match=msg):
+        df.transform({"A": [op, "shift"], "B": [op]})
+
+
+@pytest.mark.parametrize("use_apply", [True, False])
+def test_transform_passes_args(use_apply, frame_or_series):
+    # GH 35964
+    # transform uses UDF either via apply or passing the entire DataFrame
+    expected_args = [1, 2]
+    expected_kwargs = {"c": 3}
+
+    def f(x, a, b, c):
+        # transform is using apply iff x is not a DataFrame
+        if use_apply == isinstance(x, frame_or_series):
+            # Force transform to fallback
+            raise ValueError
+        assert [a, b] == expected_args
+        assert c == expected_kwargs["c"]
+        return x
+
+    frame_or_series([1]).transform(f, 0, *expected_args, **expected_kwargs)
+
+
+def test_transform_empty_dataframe():
+    # https://github.com/pandas-dev/pandas/issues/39636
+    df = DataFrame([], columns=["col1", "col2"])
+    result = df.transform(lambda x: x + 10)
+    tm.assert_frame_equal(result, df)
+
+    result = df["col1"].transform(lambda x: x + 10)
+    tm.assert_series_equal(result, df["col1"])
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_invalid_arg.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_invalid_arg.py
new file mode 100644
index 0000000000000000000000000000000000000000..68f3fe36546a09404f4f390ace4f6266c1512abe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_invalid_arg.py
@@ -0,0 +1,363 @@
+# Tests specifically aimed at detecting bad arguments.
+# This file is organized by reason for exception.
+#     1. always invalid argument values
+#     2. missing column(s)
+#     3. incompatible ops/dtype/args/kwargs
+#     4. invalid result shape/type
+# If your test does not fit into one of these categories, add to this list.
+
+from itertools import chain
+import re
+
+import numpy as np
+import pytest
+
+from pandas.errors import SpecificationError
+
+from pandas import (
+    DataFrame,
+    Series,
+    date_range,
+)
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize("result_type", ["foo", 1])
+def test_result_type_error(result_type):
+    # allowed result_type
+    df = DataFrame(
+        np.tile(np.arange(3, dtype="int64"), 6).reshape(6, -1) + 1,
+        columns=["A", "B", "C"],
+    )
+
+    msg = (
+        "invalid value for result_type, must be one of "
+        "{None, 'reduce', 'broadcast', 'expand'}"
+    )
+    with pytest.raises(ValueError, match=msg):
+        df.apply(lambda x: [1, 2, 3], axis=1, result_type=result_type)
+
+
+def test_apply_invalid_axis_value():
+    df = DataFrame([[1, 2, 3], [4, 5, 6], [7, 8, 9]], index=["a", "a", "c"])
+    msg = "No axis named 2 for object type DataFrame"
+    with pytest.raises(ValueError, match=msg):
+        df.apply(lambda x: x, 2)
+
+
+def test_agg_raises():
+    # GH 26513
+    df = DataFrame({"A": [0, 1], "B": [1, 2]})
+    msg = "Must provide"
+
+    with pytest.raises(TypeError, match=msg):
+        df.agg()
+
+
+def test_map_with_invalid_na_action_raises():
+    # https://github.com/pandas-dev/pandas/issues/32815
+    s = Series([1, 2, 3])
+    msg = "na_action must either be 'ignore' or None"
+    with pytest.raises(ValueError, match=msg):
+        s.map(lambda x: x, na_action="____")
+
+
+@pytest.mark.parametrize("input_na_action", ["____", True])
+def test_map_arg_is_dict_with_invalid_na_action_raises(input_na_action):
+    # https://github.com/pandas-dev/pandas/issues/46588
+    s = Series([1, 2, 3])
+    msg = f"na_action must either be 'ignore' or None, {input_na_action} was passed"
+    with pytest.raises(ValueError, match=msg):
+        s.map({1: 2}, na_action=input_na_action)
+
+
+@pytest.mark.parametrize("method", ["apply", "agg", "transform"])
+@pytest.mark.parametrize("func", [{"A": {"B": "sum"}}, {"A": {"B": ["sum"]}}])
+def test_nested_renamer(frame_or_series, method, func):
+    # GH 35964
+    obj = frame_or_series({"A": [1]})
+    match = "nested renamer is not supported"
+    with pytest.raises(SpecificationError, match=match):
+        getattr(obj, method)(func)
+
+
+@pytest.mark.parametrize(
+    "renamer",
+    [{"foo": ["min", "max"]}, {"foo": ["min", "max"], "bar": ["sum", "mean"]}],
+)
+def test_series_nested_renamer(renamer):
+    s = Series(range(6), dtype="int64", name="series")
+    msg = "nested renamer is not supported"
+    with pytest.raises(SpecificationError, match=msg):
+        s.agg(renamer)
+
+
+def test_apply_dict_depr():
+    tsdf = DataFrame(
+        np.random.default_rng(2).standard_normal((10, 3)),
+        columns=["A", "B", "C"],
+        index=date_range("1/1/2000", periods=10),
+    )
+    msg = "nested renamer is not supported"
+    with pytest.raises(SpecificationError, match=msg):
+        tsdf.A.agg({"foo": ["sum", "mean"]})
+
+
+@pytest.mark.parametrize("method", ["agg", "transform"])
+def test_dict_nested_renaming_depr(method):
+    df = DataFrame({"A": range(5), "B": 5})
+
+    # nested renaming
+    msg = r"nested renamer is not supported"
+    with pytest.raises(SpecificationError, match=msg):
+        getattr(df, method)({"A": {"foo": "min"}, "B": {"bar": "max"}})
+
+
+@pytest.mark.parametrize("method", ["apply", "agg", "transform"])
+@pytest.mark.parametrize("func", [{"B": "sum"}, {"B": ["sum"]}])
+def test_missing_column(method, func):
+    # GH 40004
+    obj = DataFrame({"A": [1]})
+    match = re.escape("Column(s) ['B'] do not exist")
+    with pytest.raises(KeyError, match=match):
+        getattr(obj, method)(func)
+
+
+def test_transform_mixed_column_name_dtypes():
+    # GH39025
+    df = DataFrame({"a": ["1"]})
+    msg = r"Column\(s\) \[1, 'b'\] do not exist"
+    with pytest.raises(KeyError, match=msg):
+        df.transform({"a": int, 1: str, "b": int})
+
+
+@pytest.mark.parametrize(
+    "how, args", [("pct_change", ()), ("nsmallest", (1, ["a", "b"])), ("tail", 1)]
+)
+def test_apply_str_axis_1_raises(how, args):
+    # GH 39211 - some ops don't support axis=1
+    df = DataFrame({"a": [1, 2], "b": [3, 4]})
+    msg = f"Operation {how} does not support axis=1"
+    with pytest.raises(ValueError, match=msg):
+        df.apply(how, axis=1, args=args)
+
+
+def test_transform_axis_1_raises():
+    # GH 35964
+    msg = "No axis named 1 for object type Series"
+    with pytest.raises(ValueError, match=msg):
+        Series([1]).transform("sum", axis=1)
+
+
+def test_apply_modify_traceback():
+    data = DataFrame(
+        {
+            "A": [
+                "foo",
+                "foo",
+                "foo",
+                "foo",
+                "bar",
+                "bar",
+                "bar",
+                "bar",
+                "foo",
+                "foo",
+                "foo",
+            ],
+            "B": [
+                "one",
+                "one",
+                "one",
+                "two",
+                "one",
+                "one",
+                "one",
+                "two",
+                "two",
+                "two",
+                "one",
+            ],
+            "C": [
+                "dull",
+                "dull",
+                "shiny",
+                "dull",
+                "dull",
+                "shiny",
+                "shiny",
+                "dull",
+                "shiny",
+                "shiny",
+                "shiny",
+            ],
+            "D": np.random.default_rng(2).standard_normal(11),
+            "E": np.random.default_rng(2).standard_normal(11),
+            "F": np.random.default_rng(2).standard_normal(11),
+        }
+    )
+
+    data.loc[4, "C"] = np.nan
+
+    def transform(row):
+        if row["C"].startswith("shin") and row["A"] == "foo":
+            row["D"] = 7
+        return row
+
+    msg = "'float' object has no attribute 'startswith'"
+    with pytest.raises(AttributeError, match=msg):
+        data.apply(transform, axis=1)
+
+
+@pytest.mark.parametrize(
+    "df, func, expected",
+    tm.get_cython_table_params(
+        DataFrame([["a", "b"], ["b", "a"]]), [["cumprod", TypeError]]
+    ),
+)
+def test_agg_cython_table_raises_frame(df, func, expected, axis, using_infer_string):
+    # GH 21224
+    if using_infer_string:
+        expected = (expected, NotImplementedError)
+
+    msg = (
+        "can't multiply sequence by non-int of type 'str'"
+        "|cannot perform cumprod with type str"  # NotImplementedError python backend
+        "|operation 'cumprod' not supported for dtype 'str'"  # TypeError pyarrow
+    )
+    warn = None if isinstance(func, str) else FutureWarning
+    with pytest.raises(expected, match=msg):
+        with tm.assert_produces_warning(warn, match="using DataFrame.cumprod"):
+            df.agg(func, axis=axis)
+
+
+@pytest.mark.parametrize(
+    "series, func, expected",
+    chain(
+        tm.get_cython_table_params(
+            Series("a b c".split()),
+            [
+                ("mean", TypeError),  # mean raises TypeError
+                ("prod", TypeError),
+                ("std", TypeError),
+                ("var", TypeError),
+                ("median", TypeError),
+                ("cumprod", TypeError),
+            ],
+        )
+    ),
+)
+def test_agg_cython_table_raises_series(series, func, expected, using_infer_string):
+    # GH21224
+    msg = r"[Cc]ould not convert|can't multiply sequence by non-int of type"
+    if func == "median" or func is np.nanmedian or func is np.median:
+        msg = r"Cannot convert \['a' 'b' 'c'\] to numeric"
+
+    if using_infer_string and func in ("cumprod", np.cumprod, np.nancumprod):
+        expected = (expected, NotImplementedError)
+
+    msg = (
+        msg + "|does not support|has no kernel|Cannot perform|cannot perform|operation"
+    )
+    warn = None if isinstance(func, str) else FutureWarning
+
+    with pytest.raises(expected, match=msg):
+        # e.g. Series('a b'.split()).cumprod() will raise
+        with tm.assert_produces_warning(warn, match="is currently using Series.*"):
+            series.agg(func)
+
+
+def test_agg_none_to_type():
+    # GH 40543
+    df = DataFrame({"a": [None]})
+    msg = re.escape("int() argument must be a string")
+    with pytest.raises(TypeError, match=msg):
+        df.agg({"a": lambda x: int(x.iloc[0])})
+
+
+def test_transform_none_to_type():
+    # GH#34377
+    df = DataFrame({"a": [None]})
+    msg = "argument must be a"
+    with pytest.raises(TypeError, match=msg):
+        df.transform({"a": lambda x: int(x.iloc[0])})
+
+
+@pytest.mark.parametrize(
+    "func",
+    [
+        lambda x: np.array([1, 2]).reshape(-1, 2),
+        lambda x: [1, 2],
+        lambda x: Series([1, 2]),
+    ],
+)
+def test_apply_broadcast_error(func):
+    df = DataFrame(
+        np.tile(np.arange(3, dtype="int64"), 6).reshape(6, -1) + 1,
+        columns=["A", "B", "C"],
+    )
+
+    # > 1 ndim
+    msg = "too many dims to broadcast|cannot broadcast result"
+    with pytest.raises(ValueError, match=msg):
+        df.apply(func, axis=1, result_type="broadcast")
+
+
+def test_transform_and_agg_err_agg(axis, float_frame):
+    # cannot both transform and agg
+    msg = "cannot combine transform and aggregation operations"
+    with pytest.raises(ValueError, match=msg):
+        with np.errstate(all="ignore"):
+            float_frame.agg(["max", "sqrt"], axis=axis)
+
+
+@pytest.mark.filterwarnings("ignore::FutureWarning")  # GH53325
+@pytest.mark.parametrize(
+    "func, msg",
+    [
+        (["sqrt", "max"], "cannot combine transform and aggregation"),
+        (
+            {"foo": np.sqrt, "bar": "sum"},
+            "cannot perform both aggregation and transformation",
+        ),
+    ],
+)
+def test_transform_and_agg_err_series(string_series, func, msg):
+    # we are trying to transform with an aggregator
+    with pytest.raises(ValueError, match=msg):
+        with np.errstate(all="ignore"):
+            string_series.agg(func)
+
+
+@pytest.mark.parametrize("func", [["max", "min"], ["max", "sqrt"]])
+def test_transform_wont_agg_frame(axis, float_frame, func):
+    # GH 35964
+    # cannot both transform and agg
+    msg = "Function did not transform"
+    with pytest.raises(ValueError, match=msg):
+        float_frame.transform(func, axis=axis)
+
+
+@pytest.mark.parametrize("func", [["min", "max"], ["sqrt", "max"]])
+def test_transform_wont_agg_series(string_series, func):
+    # GH 35964
+    # we are trying to transform with an aggregator
+    msg = "Function did not transform"
+
+    with pytest.raises(ValueError, match=msg):
+        string_series.transform(func)
+
+
+@pytest.mark.parametrize(
+    "op_wrapper", [lambda x: x, lambda x: [x], lambda x: {"A": x}, lambda x: {"A": [x]}]
+)
+def test_transform_reducer_raises(all_reductions, frame_or_series, op_wrapper):
+    # GH 35964
+    op = op_wrapper(all_reductions)
+
+    obj = DataFrame({"A": [1, 2, 3]})
+    obj = tm.get_obj(obj, frame_or_series)
+
+    msg = "Function did not transform"
+    with pytest.raises(ValueError, match=msg):
+        obj.transform(op)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_numba.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_numba.py
new file mode 100644
index 0000000000000000000000000000000000000000..c211073f758881fdd9e2acf72b30e86b9aa49cb2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_numba.py
@@ -0,0 +1,129 @@
+import numpy as np
+import pytest
+
+from pandas.compat import is_platform_arm
+import pandas.util._test_decorators as td
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    Index,
+)
+import pandas._testing as tm
+from pandas.util.version import Version
+
+pytestmark = [td.skip_if_no("numba"), pytest.mark.single_cpu, pytest.mark.skipif()]
+
+numba = pytest.importorskip("numba")
+pytestmark.append(
+    pytest.mark.skipif(
+        Version(numba.__version__) == Version("0.61") and is_platform_arm(),
+        reason=f"Segfaults on ARM platforms with numba {numba.__version__}",
+    )
+)
+
+
+@pytest.fixture(params=[0, 1])
+def apply_axis(request):
+    return request.param
+
+
+def test_numba_vs_python_noop(float_frame, apply_axis):
+    func = lambda x: x
+    result = float_frame.apply(func, engine="numba", axis=apply_axis)
+    expected = float_frame.apply(func, engine="python", axis=apply_axis)
+    tm.assert_frame_equal(result, expected)
+
+
+def test_numba_vs_python_string_index():
+    # GH#56189
+    df = DataFrame(
+        1,
+        index=Index(["a", "b"], dtype=pd.StringDtype(na_value=np.nan)),
+        columns=Index(["x", "y"], dtype=pd.StringDtype(na_value=np.nan)),
+    )
+    func = lambda x: x
+    result = df.apply(func, engine="numba", axis=0)
+    expected = df.apply(func, engine="python", axis=0)
+    tm.assert_frame_equal(
+        result, expected, check_column_type=False, check_index_type=False
+    )
+
+
+def test_numba_vs_python_indexing():
+    frame = DataFrame(
+        {"a": [1, 2, 3], "b": [4, 5, 6], "c": [7.0, 8.0, 9.0]},
+        index=Index(["A", "B", "C"]),
+    )
+    row_func = lambda x: x["c"]
+    result = frame.apply(row_func, engine="numba", axis=1)
+    expected = frame.apply(row_func, engine="python", axis=1)
+    tm.assert_series_equal(result, expected)
+
+    col_func = lambda x: x["A"]
+    result = frame.apply(col_func, engine="numba", axis=0)
+    expected = frame.apply(col_func, engine="python", axis=0)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "reduction",
+    [lambda x: x.mean(), lambda x: x.min(), lambda x: x.max(), lambda x: x.sum()],
+)
+def test_numba_vs_python_reductions(reduction, apply_axis):
+    df = DataFrame(np.ones((4, 4), dtype=np.float64))
+    result = df.apply(reduction, engine="numba", axis=apply_axis)
+    expected = df.apply(reduction, engine="python", axis=apply_axis)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("colnames", [[1, 2, 3], [1.0, 2.0, 3.0]])
+def test_numba_numeric_colnames(colnames):
+    # Check that numeric column names lower properly and can be indxed on
+    df = DataFrame(
+        np.array([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dtype=np.int64), columns=colnames
+    )
+    first_col = colnames[0]
+    f = lambda x: x[first_col]  # Get the first column
+    result = df.apply(f, engine="numba", axis=1)
+    expected = df.apply(f, engine="python", axis=1)
+    tm.assert_series_equal(result, expected)
+
+
+def test_numba_parallel_unsupported(float_frame):
+    f = lambda x: x
+    with pytest.raises(
+        NotImplementedError,
+        match="Parallel apply is not supported when raw=False and engine='numba'",
+    ):
+        float_frame.apply(f, engine="numba", engine_kwargs={"parallel": True})
+
+
+def test_numba_nonunique_unsupported(apply_axis):
+    f = lambda x: x
+    df = DataFrame({"a": [1, 2]}, index=Index(["a", "a"]))
+    with pytest.raises(
+        NotImplementedError,
+        match="The index/columns must be unique when raw=False and engine='numba'",
+    ):
+        df.apply(f, engine="numba", axis=apply_axis)
+
+
+def test_numba_unsupported_dtypes(apply_axis):
+    pytest.importorskip("pyarrow")
+    f = lambda x: x
+    df = DataFrame({"a": [1, 2], "b": ["a", "b"], "c": [4, 5]})
+    df["c"] = df["c"].astype("double[pyarrow]")
+
+    with pytest.raises(
+        ValueError,
+        match="Column b must have a numeric dtype. Found 'object|str' instead",
+    ):
+        df.apply(f, engine="numba", axis=apply_axis)
+
+    with pytest.raises(
+        ValueError,
+        match="Column c is backed by an extension array, "
+        "which is not supported by the numba engine.",
+    ):
+        df["c"].to_frame().apply(f, engine="numba", axis=apply_axis)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply.py
new file mode 100644
index 0000000000000000000000000000000000000000..69f84ca74ab0b44e177a4a79a1ef5a6c893efbe8
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply.py
@@ -0,0 +1,701 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    Index,
+    MultiIndex,
+    Series,
+    concat,
+    date_range,
+    timedelta_range,
+)
+import pandas._testing as tm
+from pandas.tests.apply.common import series_transform_kernels
+
+
+@pytest.fixture(params=[False, "compat"])
+def by_row(request):
+    return request.param
+
+
+def test_series_map_box_timedelta(by_row):
+    # GH#11349
+    ser = Series(timedelta_range("1 day 1 s", periods=3, freq="h"))
+
+    def f(x):
+        return x.total_seconds() if by_row else x.dt.total_seconds()
+
+    result = ser.apply(f, by_row=by_row)
+
+    expected = ser.map(lambda x: x.total_seconds())
+    tm.assert_series_equal(result, expected)
+
+    expected = Series([86401.0, 90001.0, 93601.0])
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply(datetime_series, by_row):
+    result = datetime_series.apply(np.sqrt, by_row=by_row)
+    with np.errstate(all="ignore"):
+        expected = np.sqrt(datetime_series)
+    tm.assert_series_equal(result, expected)
+
+    # element-wise apply (ufunc)
+    result = datetime_series.apply(np.exp, by_row=by_row)
+    expected = np.exp(datetime_series)
+    tm.assert_series_equal(result, expected)
+
+    # empty series
+    s = Series(dtype=object, name="foo", index=Index([], name="bar"))
+    rs = s.apply(lambda x: x, by_row=by_row)
+    tm.assert_series_equal(s, rs)
+
+    # check all metadata (GH 9322)
+    assert s is not rs
+    assert s.index is rs.index
+    assert s.dtype == rs.dtype
+    assert s.name == rs.name
+
+    # index but no data
+    s = Series(index=[1, 2, 3], dtype=np.float64)
+    rs = s.apply(lambda x: x, by_row=by_row)
+    tm.assert_series_equal(s, rs)
+
+
+def test_apply_map_same_length_inference_bug():
+    s = Series([1, 2])
+
+    def f(x):
+        return (x, x + 1)
+
+    result = s.apply(f, by_row="compat")
+    expected = s.map(f)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("convert_dtype", [True, False])
+def test_apply_convert_dtype_deprecated(convert_dtype):
+    ser = Series(np.random.default_rng(2).standard_normal(10))
+
+    def func(x):
+        return x if x > 0 else np.nan
+
+    with tm.assert_produces_warning(FutureWarning):
+        ser.apply(func, convert_dtype=convert_dtype, by_row="compat")
+
+
+def test_apply_args():
+    s = Series(["foo,bar"])
+
+    result = s.apply(str.split, args=(",",))
+    assert result[0] == ["foo", "bar"]
+    assert isinstance(result[0], list)
+
+
+@pytest.mark.parametrize(
+    "args, kwargs, increment",
+    [((), {}, 0), ((), {"a": 1}, 1), ((2, 3), {}, 32), ((1,), {"c": 2}, 201)],
+)
+def test_agg_args(args, kwargs, increment):
+    # GH 43357
+    def f(x, a=0, b=0, c=0):
+        return x + a + 10 * b + 100 * c
+
+    s = Series([1, 2])
+    msg = (
+        "in Series.agg cannot aggregate and has been deprecated. "
+        "Use Series.transform to keep behavior unchanged."
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = s.agg(f, 0, *args, **kwargs)
+    expected = s + increment
+    tm.assert_series_equal(result, expected)
+
+
+def test_agg_mapping_func_deprecated():
+    # GH 53325
+    s = Series([1, 2, 3])
+
+    def foo1(x, a=1, c=0):
+        return x + a + c
+
+    def foo2(x, b=2, c=0):
+        return x + b + c
+
+    msg = "using .+ in Series.agg cannot aggregate and"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        s.agg(foo1, 0, 3, c=4)
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        s.agg([foo1, foo2], 0, 3, c=4)
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        s.agg({"a": foo1, "b": foo2}, 0, 3, c=4)
+
+
+def test_series_apply_map_box_timestamps(by_row):
+    # GH#2689, GH#2627
+    ser = Series(date_range("1/1/2000", periods=10))
+
+    def func(x):
+        return (x.hour, x.day, x.month)
+
+    if not by_row:
+        msg = "Series' object has no attribute 'hour'"
+        with pytest.raises(AttributeError, match=msg):
+            ser.apply(func, by_row=by_row)
+        return
+
+    result = ser.apply(func, by_row=by_row)
+    expected = ser.map(func)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_box_dt64():
+    # ufunc will not be boxed. Same test cases as the test_map_box
+    vals = [pd.Timestamp("2011-01-01"), pd.Timestamp("2011-01-02")]
+    ser = Series(vals, dtype="M8[ns]")
+    assert ser.dtype == "datetime64[ns]"
+    # boxed value must be Timestamp instance
+    res = ser.apply(lambda x: f"{type(x).__name__}_{x.day}_{x.tz}", by_row="compat")
+    exp = Series(["Timestamp_1_None", "Timestamp_2_None"])
+    tm.assert_series_equal(res, exp)
+
+
+def test_apply_box_dt64tz():
+    vals = [
+        pd.Timestamp("2011-01-01", tz="US/Eastern"),
+        pd.Timestamp("2011-01-02", tz="US/Eastern"),
+    ]
+    ser = Series(vals, dtype="M8[ns, US/Eastern]")
+    assert ser.dtype == "datetime64[ns, US/Eastern]"
+    res = ser.apply(lambda x: f"{type(x).__name__}_{x.day}_{x.tz}", by_row="compat")
+    exp = Series(["Timestamp_1_US/Eastern", "Timestamp_2_US/Eastern"])
+    tm.assert_series_equal(res, exp)
+
+
+def test_apply_box_td64():
+    # timedelta
+    vals = [pd.Timedelta("1 days"), pd.Timedelta("2 days")]
+    ser = Series(vals)
+    assert ser.dtype == "timedelta64[ns]"
+    res = ser.apply(lambda x: f"{type(x).__name__}_{x.days}", by_row="compat")
+    exp = Series(["Timedelta_1", "Timedelta_2"])
+    tm.assert_series_equal(res, exp)
+
+
+def test_apply_box_period():
+    # period
+    vals = [pd.Period("2011-01-01", freq="M"), pd.Period("2011-01-02", freq="M")]
+    ser = Series(vals)
+    assert ser.dtype == "Period[M]"
+    res = ser.apply(lambda x: f"{type(x).__name__}_{x.freqstr}", by_row="compat")
+    exp = Series(["Period_M", "Period_M"])
+    tm.assert_series_equal(res, exp)
+
+
+def test_apply_datetimetz(by_row):
+    values = date_range("2011-01-01", "2011-01-02", freq="h").tz_localize("Asia/Tokyo")
+    s = Series(values, name="XX")
+
+    result = s.apply(lambda x: x + pd.offsets.Day(), by_row=by_row)
+    exp_values = date_range("2011-01-02", "2011-01-03", freq="h").tz_localize(
+        "Asia/Tokyo"
+    )
+    exp = Series(exp_values, name="XX")
+    tm.assert_series_equal(result, exp)
+
+    result = s.apply(lambda x: x.hour if by_row else x.dt.hour, by_row=by_row)
+    exp = Series(list(range(24)) + [0], name="XX", dtype="int64" if by_row else "int32")
+    tm.assert_series_equal(result, exp)
+
+    # not vectorized
+    def f(x):
+        return str(x.tz) if by_row else str(x.dt.tz)
+
+    result = s.apply(f, by_row=by_row)
+    if by_row:
+        exp = Series(["Asia/Tokyo"] * 25, name="XX")
+        tm.assert_series_equal(result, exp)
+    else:
+        assert result == "Asia/Tokyo"
+
+
+def test_apply_categorical(by_row, using_infer_string):
+    values = pd.Categorical(list("ABBABCD"), categories=list("DCBA"), ordered=True)
+    ser = Series(values, name="XX", index=list("abcdefg"))
+
+    if not by_row:
+        msg = "Series' object has no attribute 'lower"
+        with pytest.raises(AttributeError, match=msg):
+            ser.apply(lambda x: x.lower(), by_row=by_row)
+        assert ser.apply(lambda x: "A", by_row=by_row) == "A"
+        return
+
+    result = ser.apply(lambda x: x.lower(), by_row=by_row)
+
+    # should be categorical dtype when the number of categories are
+    # the same
+    values = pd.Categorical(list("abbabcd"), categories=list("dcba"), ordered=True)
+    exp = Series(values, name="XX", index=list("abcdefg"))
+    tm.assert_series_equal(result, exp)
+    tm.assert_categorical_equal(result.values, exp.values)
+
+    result = ser.apply(lambda x: "A")
+    exp = Series(["A"] * 7, name="XX", index=list("abcdefg"))
+    tm.assert_series_equal(result, exp)
+    assert result.dtype == object if not using_infer_string else "str"
+
+
+@pytest.mark.parametrize("series", [["1-1", "1-1", np.nan], ["1-1", "1-2", np.nan]])
+def test_apply_categorical_with_nan_values(series, by_row):
+    # GH 20714 bug fixed in: GH 24275
+    s = Series(series, dtype="category")
+    if not by_row:
+        msg = "'Series' object has no attribute 'split'"
+        with pytest.raises(AttributeError, match=msg):
+            s.apply(lambda x: x.split("-")[0], by_row=by_row)
+        return
+
+    result = s.apply(lambda x: x.split("-")[0], by_row=by_row)
+    result = result.astype(object)
+    expected = Series(["1", "1", np.nan], dtype="category")
+    expected = expected.astype(object)
+    tm.assert_series_equal(result, expected)
+
+
+def test_apply_empty_integer_series_with_datetime_index(by_row):
+    # GH 21245
+    s = Series([], index=date_range(start="2018-01-01", periods=0), dtype=int)
+    result = s.apply(lambda x: x, by_row=by_row)
+    tm.assert_series_equal(result, s)
+
+
+def test_apply_dataframe_iloc():
+    uintDF = DataFrame(np.uint64([1, 2, 3, 4, 5]), columns=["Numbers"])
+    indexDF = DataFrame([2, 3, 2, 1, 2], columns=["Indices"])
+
+    def retrieve(targetRow, targetDF):
+        val = targetDF["Numbers"].iloc[targetRow]
+        return val
+
+    result = indexDF["Indices"].apply(retrieve, args=(uintDF,))
+    expected = Series([3, 4, 3, 2, 3], name="Indices", dtype="uint64")
+    tm.assert_series_equal(result, expected)
+
+
+def test_transform(string_series, by_row):
+    # transforming functions
+
+    with np.errstate(all="ignore"):
+        f_sqrt = np.sqrt(string_series)
+        f_abs = np.abs(string_series)
+
+        # ufunc
+        result = string_series.apply(np.sqrt, by_row=by_row)
+        expected = f_sqrt.copy()
+        tm.assert_series_equal(result, expected)
+
+        # list-like
+        result = string_series.apply([np.sqrt], by_row=by_row)
+        expected = f_sqrt.to_frame().copy()
+        expected.columns = ["sqrt"]
+        tm.assert_frame_equal(result, expected)
+
+        result = string_series.apply(["sqrt"], by_row=by_row)
+        tm.assert_frame_equal(result, expected)
+
+        # multiple items in list
+        # these are in the order as if we are applying both functions per
+        # series and then concatting
+        expected = concat([f_sqrt, f_abs], axis=1)
+        expected.columns = ["sqrt", "absolute"]
+        result = string_series.apply([np.sqrt, np.abs], by_row=by_row)
+        tm.assert_frame_equal(result, expected)
+
+        # dict, provide renaming
+        expected = concat([f_sqrt, f_abs], axis=1)
+        expected.columns = ["foo", "bar"]
+        expected = expected.unstack().rename("series")
+
+        result = string_series.apply({"foo": np.sqrt, "bar": np.abs}, by_row=by_row)
+        tm.assert_series_equal(result.reindex_like(expected), expected)
+
+
+@pytest.mark.parametrize("op", series_transform_kernels)
+def test_transform_partial_failure(op, request):
+    # GH 35964
+    if op in ("ffill", "bfill", "pad", "backfill", "shift"):
+        request.applymarker(
+            pytest.mark.xfail(reason=f"{op} is successful on any dtype")
+        )
+
+    # Using object makes most transform kernels fail
+    ser = Series(3 * [object])
+
+    if op in ("fillna", "ngroup"):
+        error = ValueError
+        msg = "Transform function failed"
+    else:
+        error = TypeError
+        msg = "|".join(
+            [
+                "not supported between instances of 'type' and 'type'",
+                "unsupported operand type",
+            ]
+        )
+
+    with pytest.raises(error, match=msg):
+        ser.transform([op, "shift"])
+
+    with pytest.raises(error, match=msg):
+        ser.transform({"A": op, "B": "shift"})
+
+    with pytest.raises(error, match=msg):
+        ser.transform({"A": [op], "B": ["shift"]})
+
+    with pytest.raises(error, match=msg):
+        ser.transform({"A": [op, "shift"], "B": [op]})
+
+
+def test_transform_partial_failure_valueerror():
+    # GH 40211
+    def noop(x):
+        return x
+
+    def raising_op(_):
+        raise ValueError
+
+    ser = Series(3 * [object])
+    msg = "Transform function failed"
+
+    with pytest.raises(ValueError, match=msg):
+        ser.transform([noop, raising_op])
+
+    with pytest.raises(ValueError, match=msg):
+        ser.transform({"A": raising_op, "B": noop})
+
+    with pytest.raises(ValueError, match=msg):
+        ser.transform({"A": [raising_op], "B": [noop]})
+
+    with pytest.raises(ValueError, match=msg):
+        ser.transform({"A": [noop, raising_op], "B": [noop]})
+
+
+def test_demo():
+    # demonstration tests
+    s = Series(range(6), dtype="int64", name="series")
+
+    result = s.agg(["min", "max"])
+    expected = Series([0, 5], index=["min", "max"], name="series")
+    tm.assert_series_equal(result, expected)
+
+    result = s.agg({"foo": "min"})
+    expected = Series([0], index=["foo"], name="series")
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("func", [str, lambda x: str(x)])
+def test_apply_map_evaluate_lambdas_the_same(string_series, func, by_row):
+    # test that we are evaluating row-by-row first if by_row="compat"
+    # else vectorized evaluation
+    result = string_series.apply(func, by_row=by_row)
+
+    if by_row:
+        expected = string_series.map(func)
+        tm.assert_series_equal(result, expected)
+    else:
+        assert result == str(string_series)
+
+
+def test_agg_evaluate_lambdas(string_series):
+    # GH53325
+    # in the future, the result will be a Series class.
+
+    with tm.assert_produces_warning(FutureWarning):
+        result = string_series.agg(lambda x: type(x))
+    assert isinstance(result, Series) and len(result) == len(string_series)
+
+    with tm.assert_produces_warning(FutureWarning):
+        result = string_series.agg(type)
+    assert isinstance(result, Series) and len(result) == len(string_series)
+
+
+@pytest.mark.parametrize("op_name", ["agg", "apply"])
+def test_with_nested_series(datetime_series, op_name):
+    # GH 2316
+    # .agg with a reducer and a transform, what to do
+    msg = "cannot aggregate"
+    warning = FutureWarning if op_name == "agg" else None
+    with tm.assert_produces_warning(warning, match=msg):
+        # GH52123
+        result = getattr(datetime_series, op_name)(
+            lambda x: Series([x, x**2], index=["x", "x^2"])
+        )
+    expected = DataFrame({"x": datetime_series, "x^2": datetime_series**2})
+    tm.assert_frame_equal(result, expected)
+
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = datetime_series.agg(lambda x: Series([x, x**2], index=["x", "x^2"]))
+    tm.assert_frame_equal(result, expected)
+
+
+def test_replicate_describe(string_series):
+    # this also tests a result set that is all scalars
+    expected = string_series.describe()
+    result = string_series.apply(
+        {
+            "count": "count",
+            "mean": "mean",
+            "std": "std",
+            "min": "min",
+            "25%": lambda x: x.quantile(0.25),
+            "50%": "median",
+            "75%": lambda x: x.quantile(0.75),
+            "max": "max",
+        },
+    )
+    tm.assert_series_equal(result, expected)
+
+
+def test_reduce(string_series):
+    # reductions with named functions
+    result = string_series.agg(["sum", "mean"])
+    expected = Series(
+        [string_series.sum(), string_series.mean()],
+        ["sum", "mean"],
+        name=string_series.name,
+    )
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "how, kwds",
+    [("agg", {}), ("apply", {"by_row": "compat"}), ("apply", {"by_row": False})],
+)
+def test_non_callable_aggregates(how, kwds):
+    # test agg using non-callable series attributes
+    # GH 39116 - expand to apply
+    s = Series([1, 2, None])
+
+    # Calling agg w/ just a string arg same as calling s.arg
+    result = getattr(s, how)("size", **kwds)
+    expected = s.size
+    assert result == expected
+
+    # test when mixed w/ callable reducers
+    result = getattr(s, how)(["size", "count", "mean"], **kwds)
+    expected = Series({"size": 3.0, "count": 2.0, "mean": 1.5})
+    tm.assert_series_equal(result, expected)
+
+    result = getattr(s, how)({"size": "size", "count": "count", "mean": "mean"}, **kwds)
+    tm.assert_series_equal(result, expected)
+
+
+def test_series_apply_no_suffix_index(by_row):
+    # GH36189
+    s = Series([4] * 3)
+    result = s.apply(["sum", lambda x: x.sum(), lambda x: x.sum()], by_row=by_row)
+    expected = Series([12, 12, 12], index=["sum", "", ""])
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "dti,exp",
+    [
+        (
+            Series([1, 2], index=pd.DatetimeIndex([0, 31536000000])),
+            DataFrame(np.repeat([[1, 2]], 2, axis=0), dtype="int64"),
+        ),
+        (
+            Series(
+                np.arange(10, dtype=np.float64),
+                index=date_range("2020-01-01", periods=10),
+                name="ts",
+            ),
+            DataFrame(np.repeat([[1, 2]], 10, axis=0), dtype="int64"),
+        ),
+    ],
+)
+@pytest.mark.parametrize("aware", [True, False])
+def test_apply_series_on_date_time_index_aware_series(dti, exp, aware):
+    # GH 25959
+    # Calling apply on a localized time series should not cause an error
+    if aware:
+        index = dti.tz_localize("UTC").index
+    else:
+        index = dti.index
+    result = Series(index).apply(lambda x: Series([1, 2]))
+    tm.assert_frame_equal(result, exp)
+
+
+@pytest.mark.parametrize(
+    "by_row, expected", [("compat", Series(np.ones(10), dtype="int64")), (False, 1)]
+)
+def test_apply_scalar_on_date_time_index_aware_series(by_row, expected):
+    # GH 25959
+    # Calling apply on a localized time series should not cause an error
+    series = Series(
+        np.arange(10, dtype=np.float64),
+        index=date_range("2020-01-01", periods=10, tz="UTC"),
+    )
+    result = Series(series.index).apply(lambda x: 1, by_row=by_row)
+    tm.assert_equal(result, expected)
+
+
+def test_apply_to_timedelta(by_row):
+    list_of_valid_strings = ["00:00:01", "00:00:02"]
+    a = pd.to_timedelta(list_of_valid_strings)
+    b = Series(list_of_valid_strings).apply(pd.to_timedelta, by_row=by_row)
+    tm.assert_series_equal(Series(a), b)
+
+    list_of_strings = ["00:00:01", np.nan, pd.NaT, pd.NaT]
+
+    a = pd.to_timedelta(list_of_strings)
+    ser = Series(list_of_strings)
+    b = ser.apply(pd.to_timedelta, by_row=by_row)
+    tm.assert_series_equal(Series(a), b)
+
+
+@pytest.mark.parametrize(
+    "ops, names",
+    [
+        ([np.sum], ["sum"]),
+        ([np.sum, np.mean], ["sum", "mean"]),
+        (np.array([np.sum]), ["sum"]),
+        (np.array([np.sum, np.mean]), ["sum", "mean"]),
+    ],
+)
+@pytest.mark.parametrize(
+    "how, kwargs",
+    [["agg", {}], ["apply", {"by_row": "compat"}], ["apply", {"by_row": False}]],
+)
+def test_apply_listlike_reducer(string_series, ops, names, how, kwargs):
+    # GH 39140
+    expected = Series({name: op(string_series) for name, op in zip(names, ops)})
+    expected.name = "series"
+    warn = FutureWarning if how == "agg" else None
+    msg = f"using Series.[{'|'.join(names)}]"
+    with tm.assert_produces_warning(warn, match=msg):
+        result = getattr(string_series, how)(ops, **kwargs)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops",
+    [
+        {"A": np.sum},
+        {"A": np.sum, "B": np.mean},
+        Series({"A": np.sum}),
+        Series({"A": np.sum, "B": np.mean}),
+    ],
+)
+@pytest.mark.parametrize(
+    "how, kwargs",
+    [["agg", {}], ["apply", {"by_row": "compat"}], ["apply", {"by_row": False}]],
+)
+def test_apply_dictlike_reducer(string_series, ops, how, kwargs, by_row):
+    # GH 39140
+    expected = Series({name: op(string_series) for name, op in ops.items()})
+    expected.name = string_series.name
+    warn = FutureWarning if how == "agg" else None
+    msg = "using Series.[sum|mean]"
+    with tm.assert_produces_warning(warn, match=msg):
+        result = getattr(string_series, how)(ops, **kwargs)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, names",
+    [
+        ([np.sqrt], ["sqrt"]),
+        ([np.abs, np.sqrt], ["absolute", "sqrt"]),
+        (np.array([np.sqrt]), ["sqrt"]),
+        (np.array([np.abs, np.sqrt]), ["absolute", "sqrt"]),
+    ],
+)
+def test_apply_listlike_transformer(string_series, ops, names, by_row):
+    # GH 39140
+    with np.errstate(all="ignore"):
+        expected = concat([op(string_series) for op in ops], axis=1)
+        expected.columns = names
+        result = string_series.apply(ops, by_row=by_row)
+        tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, expected",
+    [
+        ([lambda x: x], DataFrame({"": [1, 2, 3]})),
+        ([lambda x: x.sum()], Series([6], index=[""])),
+    ],
+)
+def test_apply_listlike_lambda(ops, expected, by_row):
+    # GH53400
+    ser = Series([1, 2, 3])
+    result = ser.apply(ops, by_row=by_row)
+    tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops",
+    [
+        {"A": np.sqrt},
+        {"A": np.sqrt, "B": np.exp},
+        Series({"A": np.sqrt}),
+        Series({"A": np.sqrt, "B": np.exp}),
+    ],
+)
+def test_apply_dictlike_transformer(string_series, ops, by_row):
+    # GH 39140
+    with np.errstate(all="ignore"):
+        expected = concat({name: op(string_series) for name, op in ops.items()})
+        expected.name = string_series.name
+        result = string_series.apply(ops, by_row=by_row)
+        tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, expected",
+    [
+        (
+            {"a": lambda x: x},
+            Series([1, 2, 3], index=MultiIndex.from_arrays([["a"] * 3, range(3)])),
+        ),
+        ({"a": lambda x: x.sum()}, Series([6], index=["a"])),
+    ],
+)
+def test_apply_dictlike_lambda(ops, by_row, expected):
+    # GH53400
+    ser = Series([1, 2, 3])
+    result = ser.apply(ops, by_row=by_row)
+    tm.assert_equal(result, expected)
+
+
+def test_apply_retains_column_name(by_row):
+    # GH 16380
+    df = DataFrame({"x": range(3)}, Index(range(3), name="x"))
+    result = df.x.apply(lambda x: Series(range(x + 1), Index(range(x + 1), name="y")))
+    expected = DataFrame(
+        [[0.0, np.nan, np.nan], [0.0, 1.0, np.nan], [0.0, 1.0, 2.0]],
+        columns=Index(range(3), name="y"),
+        index=Index(range(3), name="x"),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_apply_type():
+    # GH 46719
+    s = Series([3, "string", float], index=["a", "b", "c"])
+    result = s.apply(type)
+    expected = Series([int, str, type], index=["a", "b", "c"])
+    tm.assert_series_equal(result, expected)
+
+
+def test_series_apply_unpack_nested_data():
+    # GH#55189
+    ser = Series([[1, 2, 3], [4, 5, 6, 7]])
+    result = ser.apply(lambda x: Series(x))
+    expected = DataFrame({0: [1.0, 4.0], 1: [2.0, 5.0], 2: [3.0, 6.0], 3: [np.nan, 7]})
+    tm.assert_frame_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply_relabeling.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply_relabeling.py
new file mode 100644
index 0000000000000000000000000000000000000000..cdfa054f91c9b67261d715cd7812a53d1b2d4b2f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_apply_relabeling.py
@@ -0,0 +1,39 @@
+import pandas as pd
+import pandas._testing as tm
+
+
+def test_relabel_no_duplicated_method():
+    # this is to test there is no duplicated method used in agg
+    df = pd.DataFrame({"A": [1, 2, 1, 2], "B": [1, 2, 3, 4]})
+
+    result = df["A"].agg(foo="sum")
+    expected = df["A"].agg({"foo": "sum"})
+    tm.assert_series_equal(result, expected)
+
+    result = df["B"].agg(foo="min", bar="max")
+    expected = df["B"].agg({"foo": "min", "bar": "max"})
+    tm.assert_series_equal(result, expected)
+
+    msg = "using Series.[sum|min|max]"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df["B"].agg(foo=sum, bar=min, cat="max")
+    msg = "using Series.[sum|min|max]"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        expected = df["B"].agg({"foo": sum, "bar": min, "cat": "max"})
+    tm.assert_series_equal(result, expected)
+
+
+def test_relabel_duplicated_method():
+    # this is to test with nested renaming, duplicated method can be used
+    # if they are assigned with different new names
+    df = pd.DataFrame({"A": [1, 2, 1, 2], "B": [1, 2, 3, 4]})
+
+    result = df["A"].agg(foo="sum", bar="sum")
+    expected = pd.Series([6, 6], index=["foo", "bar"], name="A")
+    tm.assert_series_equal(result, expected)
+
+    msg = "using Series.min"
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = df["B"].agg(foo=min, bar="min")
+    expected = pd.Series([1, 1], index=["foo", "bar"], name="B")
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_transform.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_transform.py
new file mode 100644
index 0000000000000000000000000000000000000000..82592c4711ece5a7f4b6d421d743e1adbd78c345
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_series_transform.py
@@ -0,0 +1,84 @@
+import numpy as np
+import pytest
+
+from pandas import (
+    DataFrame,
+    MultiIndex,
+    Series,
+    concat,
+)
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "args, kwargs, increment",
+    [((), {}, 0), ((), {"a": 1}, 1), ((2, 3), {}, 32), ((1,), {"c": 2}, 201)],
+)
+def test_agg_args(args, kwargs, increment):
+    # GH 43357
+    def f(x, a=0, b=0, c=0):
+        return x + a + 10 * b + 100 * c
+
+    s = Series([1, 2])
+    result = s.transform(f, 0, *args, **kwargs)
+    expected = s + increment
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "ops, names",
+    [
+        ([np.sqrt], ["sqrt"]),
+        ([np.abs, np.sqrt], ["absolute", "sqrt"]),
+        (np.array([np.sqrt]), ["sqrt"]),
+        (np.array([np.abs, np.sqrt]), ["absolute", "sqrt"]),
+    ],
+)
+def test_transform_listlike(string_series, ops, names):
+    # GH 35964
+    with np.errstate(all="ignore"):
+        expected = concat([op(string_series) for op in ops], axis=1)
+        expected.columns = names
+        result = string_series.transform(ops)
+        tm.assert_frame_equal(result, expected)
+
+
+def test_transform_listlike_func_with_args():
+    # GH 50624
+
+    s = Series([1, 2, 3])
+
+    def foo1(x, a=1, c=0):
+        return x + a + c
+
+    def foo2(x, b=2, c=0):
+        return x + b + c
+
+    msg = r"foo1\(\) got an unexpected keyword argument 'b'"
+    with pytest.raises(TypeError, match=msg):
+        s.transform([foo1, foo2], 0, 3, b=3, c=4)
+
+    result = s.transform([foo1, foo2], 0, 3, c=4)
+    expected = DataFrame({"foo1": [8, 9, 10], "foo2": [8, 9, 10]})
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("box", [dict, Series])
+def test_transform_dictlike(string_series, box):
+    # GH 35964
+    with np.errstate(all="ignore"):
+        expected = concat([np.sqrt(string_series), np.abs(string_series)], axis=1)
+    expected.columns = ["foo", "bar"]
+    result = string_series.transform(box({"foo": np.sqrt, "bar": np.abs}))
+    tm.assert_frame_equal(result, expected)
+
+
+def test_transform_dictlike_mixed():
+    # GH 40018 - mix of lists and non-lists in values of a dictionary
+    df = Series([1, 4])
+    result = df.transform({"b": ["sqrt", "abs"], "c": "sqrt"})
+    expected = DataFrame(
+        [[1.0, 1, 1.0], [2.0, 4, 2.0]],
+        columns=MultiIndex([("b", "c"), ("sqrt", "abs")], [(0, 0, 1), (0, 1, 0)]),
+    )
+    tm.assert_frame_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_str.py b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_str.py
new file mode 100644
index 0000000000000000000000000000000000000000..17e8322dc40e1ef0e65ed6d63a6e4af3a373e29b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/apply/test_str.py
@@ -0,0 +1,326 @@
+from itertools import chain
+import operator
+
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.common import is_number
+
+from pandas import (
+    DataFrame,
+    Series,
+)
+import pandas._testing as tm
+from pandas.tests.apply.common import (
+    frame_transform_kernels,
+    series_transform_kernels,
+)
+
+
+@pytest.mark.parametrize("func", ["sum", "mean", "min", "max", "std"])
+@pytest.mark.parametrize(
+    "args,kwds",
+    [
+        pytest.param([], {}, id="no_args_or_kwds"),
+        pytest.param([1], {}, id="axis_from_args"),
+        pytest.param([], {"axis": 1}, id="axis_from_kwds"),
+        pytest.param([], {"numeric_only": True}, id="optional_kwds"),
+        pytest.param([1, True], {"numeric_only": True}, id="args_and_kwds"),
+    ],
+)
+@pytest.mark.parametrize("how", ["agg", "apply"])
+def test_apply_with_string_funcs(request, float_frame, func, args, kwds, how):
+    if len(args) > 1 and how == "agg":
+        request.applymarker(
+            pytest.mark.xfail(
+                raises=TypeError,
+                reason="agg/apply signature mismatch - agg passes 2nd "
+                "argument to func",
+            )
+        )
+    result = getattr(float_frame, how)(func, *args, **kwds)
+    expected = getattr(float_frame, func)(*args, **kwds)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("arg", ["sum", "mean", "min", "max", "std"])
+def test_with_string_args(datetime_series, arg):
+    result = datetime_series.apply(arg)
+    expected = getattr(datetime_series, arg)()
+    assert result == expected
+
+
+@pytest.mark.parametrize("op", ["mean", "median", "std", "var"])
+@pytest.mark.parametrize("how", ["agg", "apply"])
+def test_apply_np_reducer(op, how):
+    # GH 39116
+    float_frame = DataFrame({"a": [1, 2], "b": [3, 4]})
+    result = getattr(float_frame, how)(op)
+    # pandas ddof defaults to 1, numpy to 0
+    kwargs = {"ddof": 1} if op in ("std", "var") else {}
+    expected = Series(
+        getattr(np, op)(float_frame, axis=0, **kwargs), index=float_frame.columns
+    )
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "op", ["abs", "ceil", "cos", "cumsum", "exp", "log", "sqrt", "square"]
+)
+@pytest.mark.parametrize("how", ["transform", "apply"])
+def test_apply_np_transformer(float_frame, op, how):
+    # GH 39116
+
+    # float_frame will _usually_ have negative values, which will
+    #  trigger the warning here, but let's put one in just to be sure
+    float_frame.iloc[0, 0] = -1.0
+    warn = None
+    if op in ["log", "sqrt"]:
+        warn = RuntimeWarning
+
+    with tm.assert_produces_warning(warn, check_stacklevel=False):
+        # float_frame fixture is defined in conftest.py, so we don't check the
+        # stacklevel as otherwise the test would fail.
+        result = getattr(float_frame, how)(op)
+        expected = getattr(np, op)(float_frame)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "series, func, expected",
+    chain(
+        tm.get_cython_table_params(
+            Series(dtype=np.float64),
+            [
+                ("sum", 0),
+                ("max", np.nan),
+                ("min", np.nan),
+                ("all", True),
+                ("any", False),
+                ("mean", np.nan),
+                ("prod", 1),
+                ("std", np.nan),
+                ("var", np.nan),
+                ("median", np.nan),
+            ],
+        ),
+        tm.get_cython_table_params(
+            Series([np.nan, 1, 2, 3]),
+            [
+                ("sum", 6),
+                ("max", 3),
+                ("min", 1),
+                ("all", True),
+                ("any", True),
+                ("mean", 2),
+                ("prod", 6),
+                ("std", 1),
+                ("var", 1),
+                ("median", 2),
+            ],
+        ),
+        tm.get_cython_table_params(
+            Series("a b c".split()),
+            [
+                ("sum", "abc"),
+                ("max", "c"),
+                ("min", "a"),
+                ("all", True),
+                ("any", True),
+            ],
+        ),
+    ),
+)
+def test_agg_cython_table_series(series, func, expected):
+    # GH21224
+    # test reducing functions in
+    # pandas.core.base.SelectionMixin._cython_table
+    warn = None if isinstance(func, str) else FutureWarning
+    with tm.assert_produces_warning(warn, match="is currently using Series.*"):
+        result = series.agg(func)
+    if is_number(expected):
+        assert np.isclose(result, expected, equal_nan=True)
+    else:
+        assert result == expected
+
+
+@pytest.mark.parametrize(
+    "series, func, expected",
+    chain(
+        tm.get_cython_table_params(
+            Series(dtype=np.float64),
+            [
+                ("cumprod", Series([], dtype=np.float64)),
+                ("cumsum", Series([], dtype=np.float64)),
+            ],
+        ),
+        tm.get_cython_table_params(
+            Series([np.nan, 1, 2, 3]),
+            [
+                ("cumprod", Series([np.nan, 1, 2, 6])),
+                ("cumsum", Series([np.nan, 1, 3, 6])),
+            ],
+        ),
+        tm.get_cython_table_params(
+            Series("a b c".split()), [("cumsum", Series(["a", "ab", "abc"]))]
+        ),
+    ),
+)
+def test_agg_cython_table_transform_series(series, func, expected):
+    # GH21224
+    # test transforming functions in
+    # pandas.core.base.SelectionMixin._cython_table (cumprod, cumsum)
+    warn = None if isinstance(func, str) else FutureWarning
+    with tm.assert_produces_warning(warn, match="is currently using Series.*"):
+        result = series.agg(func)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "df, func, expected",
+    chain(
+        tm.get_cython_table_params(
+            DataFrame(),
+            [
+                ("sum", Series(dtype="float64")),
+                ("max", Series(dtype="float64")),
+                ("min", Series(dtype="float64")),
+                ("all", Series(dtype=bool)),
+                ("any", Series(dtype=bool)),
+                ("mean", Series(dtype="float64")),
+                ("prod", Series(dtype="float64")),
+                ("std", Series(dtype="float64")),
+                ("var", Series(dtype="float64")),
+                ("median", Series(dtype="float64")),
+            ],
+        ),
+        tm.get_cython_table_params(
+            DataFrame([[np.nan, 1], [1, 2]]),
+            [
+                ("sum", Series([1.0, 3])),
+                ("max", Series([1.0, 2])),
+                ("min", Series([1.0, 1])),
+                ("all", Series([True, True])),
+                ("any", Series([True, True])),
+                ("mean", Series([1, 1.5])),
+                ("prod", Series([1.0, 2])),
+                ("std", Series([np.nan, 0.707107])),
+                ("var", Series([np.nan, 0.5])),
+                ("median", Series([1, 1.5])),
+            ],
+        ),
+    ),
+)
+def test_agg_cython_table_frame(df, func, expected, axis):
+    # GH 21224
+    # test reducing functions in
+    # pandas.core.base.SelectionMixin._cython_table
+    warn = None if isinstance(func, str) else FutureWarning
+    with tm.assert_produces_warning(warn, match="is currently using DataFrame.*"):
+        # GH#53425
+        result = df.agg(func, axis=axis)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "df, func, expected",
+    chain(
+        tm.get_cython_table_params(
+            DataFrame(), [("cumprod", DataFrame()), ("cumsum", DataFrame())]
+        ),
+        tm.get_cython_table_params(
+            DataFrame([[np.nan, 1], [1, 2]]),
+            [
+                ("cumprod", DataFrame([[np.nan, 1], [1, 2]])),
+                ("cumsum", DataFrame([[np.nan, 1], [1, 3]])),
+            ],
+        ),
+    ),
+)
+def test_agg_cython_table_transform_frame(df, func, expected, axis):
+    # GH 21224
+    # test transforming functions in
+    # pandas.core.base.SelectionMixin._cython_table (cumprod, cumsum)
+    if axis in ("columns", 1):
+        # operating blockwise doesn't let us preserve dtypes
+        expected = expected.astype("float64")
+
+    warn = None if isinstance(func, str) else FutureWarning
+    with tm.assert_produces_warning(warn, match="is currently using DataFrame.*"):
+        # GH#53425
+        result = df.agg(func, axis=axis)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("op", series_transform_kernels)
+def test_transform_groupby_kernel_series(request, string_series, op):
+    # GH 35964
+    if op == "ngroup":
+        request.applymarker(
+            pytest.mark.xfail(raises=ValueError, reason="ngroup not valid for NDFrame")
+        )
+    args = [0.0] if op == "fillna" else []
+    ones = np.ones(string_series.shape[0])
+
+    warn = FutureWarning if op == "fillna" else None
+    msg = "SeriesGroupBy.fillna is deprecated"
+    with tm.assert_produces_warning(warn, match=msg):
+        expected = string_series.groupby(ones).transform(op, *args)
+    result = string_series.transform(op, 0, *args)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("op", frame_transform_kernels)
+def test_transform_groupby_kernel_frame(request, axis, float_frame, op):
+    if op == "ngroup":
+        request.applymarker(
+            pytest.mark.xfail(raises=ValueError, reason="ngroup not valid for NDFrame")
+        )
+
+    # GH 35964
+
+    args = [0.0] if op == "fillna" else []
+    if axis in (0, "index"):
+        ones = np.ones(float_frame.shape[0])
+        msg = "The 'axis' keyword in DataFrame.groupby is deprecated"
+    else:
+        ones = np.ones(float_frame.shape[1])
+        msg = "DataFrame.groupby with axis=1 is deprecated"
+
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        gb = float_frame.groupby(ones, axis=axis)
+
+    warn = FutureWarning if op == "fillna" else None
+    op_msg = "DataFrameGroupBy.fillna is deprecated"
+    with tm.assert_produces_warning(warn, match=op_msg):
+        expected = gb.transform(op, *args)
+
+    result = float_frame.transform(op, axis, *args)
+    tm.assert_frame_equal(result, expected)
+
+    # same thing, but ensuring we have multiple blocks
+    assert "E" not in float_frame.columns
+    float_frame["E"] = float_frame["A"].copy()
+    assert len(float_frame._mgr.arrays) > 1
+
+    if axis in (0, "index"):
+        ones = np.ones(float_frame.shape[0])
+    else:
+        ones = np.ones(float_frame.shape[1])
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        gb2 = float_frame.groupby(ones, axis=axis)
+    warn = FutureWarning if op == "fillna" else None
+    op_msg = "DataFrameGroupBy.fillna is deprecated"
+    with tm.assert_produces_warning(warn, match=op_msg):
+        expected2 = gb2.transform(op, *args)
+    result2 = float_frame.transform(op, axis, *args)
+    tm.assert_frame_equal(result2, expected2)
+
+
+@pytest.mark.parametrize("method", ["abs", "shift", "pct_change", "cumsum", "rank"])
+def test_transform_method_name(method):
+    # GH 19760
+    df = DataFrame({"A": [-1, 2]})
+    result = df.transform(method)
+    expected = operator.methodcaller(method)(df)
+    tm.assert_frame_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/common.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/common.py
new file mode 100644
index 0000000000000000000000000000000000000000..b608df1554154f4723a0147ea02c04c780839c65
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/common.py
@@ -0,0 +1,155 @@
+"""
+Assertion helpers for arithmetic tests.
+"""
+import numpy as np
+import pytest
+
+from pandas import (
+    DataFrame,
+    Index,
+    Series,
+    array,
+)
+import pandas._testing as tm
+from pandas.core.arrays import (
+    BooleanArray,
+    NumpyExtensionArray,
+)
+
+
+def assert_cannot_add(left, right, msg="cannot add"):
+    """
+    Helper to assert that left and right cannot be added.
+
+    Parameters
+    ----------
+    left : object
+    right : object
+    msg : str, default "cannot add"
+    """
+    with pytest.raises(TypeError, match=msg):
+        left + right
+    with pytest.raises(TypeError, match=msg):
+        right + left
+
+
+def assert_invalid_addsub_type(left, right, msg=None):
+    """
+    Helper to assert that left and right can be neither added nor subtracted.
+
+    Parameters
+    ----------
+    left : object
+    right : object
+    msg : str or None, default None
+    """
+    with pytest.raises(TypeError, match=msg):
+        left + right
+    with pytest.raises(TypeError, match=msg):
+        right + left
+    with pytest.raises(TypeError, match=msg):
+        left - right
+    with pytest.raises(TypeError, match=msg):
+        right - left
+
+
+def get_upcast_box(left, right, is_cmp: bool = False):
+    """
+    Get the box to use for 'expected' in an arithmetic or comparison operation.
+
+    Parameters
+    left : Any
+    right : Any
+    is_cmp : bool, default False
+        Whether the operation is a comparison method.
+    """
+
+    if isinstance(left, DataFrame) or isinstance(right, DataFrame):
+        return DataFrame
+    if isinstance(left, Series) or isinstance(right, Series):
+        if is_cmp and isinstance(left, Index):
+            # Index does not defer for comparisons
+            return np.array
+        return Series
+    if isinstance(left, Index) or isinstance(right, Index):
+        if is_cmp:
+            return np.array
+        return Index
+    return tm.to_array
+
+
+def assert_invalid_comparison(left, right, box):
+    """
+    Assert that comparison operations with mismatched types behave correctly.
+
+    Parameters
+    ----------
+    left : np.ndarray, ExtensionArray, Index, or Series
+    right : object
+    box : {pd.DataFrame, pd.Series, pd.Index, pd.array, tm.to_array}
+    """
+    # Not for tznaive-tzaware comparison
+
+    # Note: not quite the same as how we do this for tm.box_expected
+    xbox = box if box not in [Index, array] else np.array
+
+    def xbox2(x):
+        # Eventually we'd like this to be tighter, but for now we'll
+        #  just exclude NumpyExtensionArray[bool]
+        if isinstance(x, NumpyExtensionArray):
+            return x._ndarray
+        if isinstance(x, BooleanArray):
+            # NB: we are assuming no pd.NAs for now
+            return x.astype(bool)
+        return x
+
+    # rev_box: box to use for reversed comparisons
+    rev_box = xbox
+    if isinstance(right, Index) and isinstance(left, Series):
+        rev_box = np.array
+
+    result = xbox2(left == right)
+    expected = xbox(np.zeros(result.shape, dtype=np.bool_))
+
+    tm.assert_equal(result, expected)
+
+    result = xbox2(right == left)
+    tm.assert_equal(result, rev_box(expected))
+
+    result = xbox2(left != right)
+    tm.assert_equal(result, ~expected)
+
+    result = xbox2(right != left)
+    tm.assert_equal(result, rev_box(~expected))
+
+    msg = "|".join(
+        [
+            "Invalid comparison between",
+            "Cannot compare type",
+            "not supported between",
+            "invalid type promotion",
+            (
+                # GH#36706 npdev 1.20.0 2020-09-28
+                r"The DTypes  and "
+                r" do not have a common DType. "
+                "For example they cannot be stored in a single array unless the "
+                "dtype is `object`."
+            ),
+        ]
+    )
+    with pytest.raises(TypeError, match=msg):
+        left < right
+    with pytest.raises(TypeError, match=msg):
+        left <= right
+    with pytest.raises(TypeError, match=msg):
+        left > right
+    with pytest.raises(TypeError, match=msg):
+        left >= right
+    with pytest.raises(TypeError, match=msg):
+        right < left
+    with pytest.raises(TypeError, match=msg):
+        right <= left
+    with pytest.raises(TypeError, match=msg):
+        right > left
+    with pytest.raises(TypeError, match=msg):
+        right >= left
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/conftest.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/conftest.py
new file mode 100644
index 0000000000000000000000000000000000000000..c7703b34a5e38e7a3887d727b0a8c954016ad836
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/conftest.py
@@ -0,0 +1,139 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import Index
+
+
+@pytest.fixture(params=[1, np.array(1, dtype=np.int64)])
+def one(request):
+    """
+    Several variants of integer value 1. The zero-dim integer array
+    behaves like an integer.
+
+    This fixture can be used to check that datetimelike indexes handle
+    addition and subtraction of integers and zero-dimensional arrays
+    of integers.
+
+    Examples
+    --------
+    dti = pd.date_range('2016-01-01', periods=2, freq='h')
+    dti
+    DatetimeIndex(['2016-01-01 00:00:00', '2016-01-01 01:00:00'],
+    dtype='datetime64[ns]', freq='h')
+    dti + one
+    DatetimeIndex(['2016-01-01 01:00:00', '2016-01-01 02:00:00'],
+    dtype='datetime64[ns]', freq='h')
+    """
+    return request.param
+
+
+zeros = [
+    box_cls([0] * 5, dtype=dtype)
+    for box_cls in [Index, np.array, pd.array]
+    for dtype in [np.int64, np.uint64, np.float64]
+]
+zeros.extend([box_cls([-0.0] * 5, dtype=np.float64) for box_cls in [Index, np.array]])
+zeros.extend([np.array(0, dtype=dtype) for dtype in [np.int64, np.uint64, np.float64]])
+zeros.extend([np.array(-0.0, dtype=np.float64)])
+zeros.extend([0, 0.0, -0.0])
+
+
+@pytest.fixture(params=zeros)
+def zero(request):
+    """
+    Several types of scalar zeros and length 5 vectors of zeros.
+
+    This fixture can be used to check that numeric-dtype indexes handle
+    division by any zero numeric-dtype.
+
+    Uses vector of length 5 for broadcasting with `numeric_idx` fixture,
+    which creates numeric-dtype vectors also of length 5.
+
+    Examples
+    --------
+    arr = RangeIndex(5)
+    arr / zeros
+    Index([nan, inf, inf, inf, inf], dtype='float64')
+    """
+    return request.param
+
+
+# ------------------------------------------------------------------
+# Scalar Fixtures
+
+
+@pytest.fixture(
+    params=[
+        pd.Timedelta("10m7s").to_pytimedelta(),
+        pd.Timedelta("10m7s"),
+        pd.Timedelta("10m7s").to_timedelta64(),
+    ],
+    ids=lambda x: type(x).__name__,
+)
+def scalar_td(request):
+    """
+    Several variants of Timedelta scalars representing 10 minutes and 7 seconds.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        pd.offsets.Day(3),
+        pd.offsets.Hour(72),
+        pd.Timedelta(days=3).to_pytimedelta(),
+        pd.Timedelta("72:00:00"),
+        np.timedelta64(3, "D"),
+        np.timedelta64(72, "h"),
+    ],
+    ids=lambda x: type(x).__name__,
+)
+def three_days(request):
+    """
+    Several timedelta-like and DateOffset objects that each represent
+    a 3-day timedelta
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        pd.offsets.Hour(2),
+        pd.offsets.Minute(120),
+        pd.Timedelta(hours=2).to_pytimedelta(),
+        pd.Timedelta(seconds=2 * 3600),
+        np.timedelta64(2, "h"),
+        np.timedelta64(120, "m"),
+    ],
+    ids=lambda x: type(x).__name__,
+)
+def two_hours(request):
+    """
+    Several timedelta-like and DateOffset objects that each represent
+    a 2-hour timedelta
+    """
+    return request.param
+
+
+_common_mismatch = [
+    pd.offsets.YearBegin(2),
+    pd.offsets.MonthBegin(1),
+    pd.offsets.Minute(),
+]
+
+
+@pytest.fixture(
+    params=[
+        np.timedelta64(4, "h"),
+        pd.Timedelta(hours=23).to_pytimedelta(),
+        pd.Timedelta("23:00:00"),
+    ]
+    + _common_mismatch
+)
+def not_daily(request):
+    """
+    Several timedelta-like and DateOffset instances that are _not_
+    compatible with Daily frequencies.
+    """
+    return request.param
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_array_ops.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_array_ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..2c347d965bbf7353a6a4e81ca955341f8041b6de
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_array_ops.py
@@ -0,0 +1,39 @@
+import operator
+
+import numpy as np
+import pytest
+
+import pandas._testing as tm
+from pandas.core.ops.array_ops import (
+    comparison_op,
+    na_logical_op,
+)
+
+
+def test_na_logical_op_2d():
+    left = np.arange(8).reshape(4, 2)
+    right = left.astype(object)
+    right[0, 0] = np.nan
+
+    # Check that we fall back to the vec_binop branch
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        operator.or_(left, right)
+
+    result = na_logical_op(left, right, operator.or_)
+    expected = right
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_object_comparison_2d():
+    left = np.arange(9).reshape(3, 3).astype(object)
+    right = left.T
+
+    result = comparison_op(left, right, operator.eq)
+    expected = np.eye(3).astype(bool)
+    tm.assert_numpy_array_equal(result, expected)
+
+    # Ensure that cython doesn't raise on non-writeable arg, which
+    #  we can get from np.broadcast_to
+    right.flags.writeable = False
+    result = comparison_op(left, right, operator.ne)
+    tm.assert_numpy_array_equal(result, ~expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_categorical.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_categorical.py
new file mode 100644
index 0000000000000000000000000000000000000000..d6f3a13ce670596a12ca10b9e8d02d69d63c96fb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_categorical.py
@@ -0,0 +1,25 @@
+import numpy as np
+
+from pandas import (
+    Categorical,
+    Series,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalComparisons:
+    def test_categorical_nan_equality(self):
+        cat = Series(Categorical(["a", "b", "c", np.nan]))
+        expected = Series([True, True, True, False])
+        result = cat == cat
+        tm.assert_series_equal(result, expected)
+
+    def test_categorical_tuple_equality(self):
+        # GH 18050
+        ser = Series([(0, 0), (0, 1), (0, 0), (1, 0), (1, 1)])
+        expected = Series([True, False, True, False, False])
+        result = ser == (0, 0)
+        tm.assert_series_equal(result, expected)
+
+        result = ser.astype("category") == (0, 0)
+        tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_datetime64.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_datetime64.py
new file mode 100644
index 0000000000000000000000000000000000000000..a468449efd507fae37f3fcb15f64a3e1bf551f93
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_datetime64.py
@@ -0,0 +1,2469 @@
+# Arithmetic tests for DataFrame/Series/Index/Array classes that should
+# behave identically.
+# Specifically for datetime64 and datetime64tz dtypes
+from datetime import (
+    datetime,
+    time,
+    timedelta,
+)
+from itertools import (
+    product,
+    starmap,
+)
+import operator
+
+import numpy as np
+import pytest
+import pytz
+
+from pandas._libs.tslibs.conversion import localize_pydatetime
+from pandas._libs.tslibs.offsets import shift_months
+from pandas.errors import PerformanceWarning
+
+import pandas as pd
+from pandas import (
+    DateOffset,
+    DatetimeIndex,
+    NaT,
+    Period,
+    Series,
+    Timedelta,
+    TimedeltaIndex,
+    Timestamp,
+    date_range,
+)
+import pandas._testing as tm
+from pandas.core import roperator
+from pandas.tests.arithmetic.common import (
+    assert_cannot_add,
+    assert_invalid_addsub_type,
+    assert_invalid_comparison,
+    get_upcast_box,
+)
+
+# ------------------------------------------------------------------
+# Comparisons
+
+
+class TestDatetime64ArrayLikeComparisons:
+    # Comparison tests for datetime64 vectors fully parametrized over
+    #  DataFrame/Series/DatetimeIndex/DatetimeArray.  Ideally all comparison
+    #  tests will eventually end up here.
+
+    def test_compare_zerodim(self, tz_naive_fixture, box_with_array):
+        # Test comparison with zero-dimensional array is unboxed
+        tz = tz_naive_fixture
+        box = box_with_array
+        dti = date_range("20130101", periods=3, tz=tz)
+
+        other = np.array(dti.to_numpy()[0])
+
+        dtarr = tm.box_expected(dti, box)
+        xbox = get_upcast_box(dtarr, other, True)
+        result = dtarr <= other
+        expected = np.array([True, False, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            "foo",
+            -1,
+            99,
+            4.0,
+            object(),
+            timedelta(days=2),
+            # GH#19800, GH#19301 datetime.date comparison raises to
+            #  match DatetimeIndex/Timestamp.  This also matches the behavior
+            #  of stdlib datetime.datetime
+            datetime(2001, 1, 1).date(),
+            # GH#19301 None and NaN are *not* cast to NaT for comparisons
+            None,
+            np.nan,
+        ],
+    )
+    def test_dt64arr_cmp_scalar_invalid(self, other, tz_naive_fixture, box_with_array):
+        # GH#22074, GH#15966
+        tz = tz_naive_fixture
+
+        rng = date_range("1/1/2000", periods=10, tz=tz)
+        dtarr = tm.box_expected(rng, box_with_array)
+        assert_invalid_comparison(dtarr, other, box_with_array)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            # GH#4968 invalid date/int comparisons
+            list(range(10)),
+            np.arange(10),
+            np.arange(10).astype(np.float32),
+            np.arange(10).astype(object),
+            pd.timedelta_range("1ns", periods=10).array,
+            np.array(pd.timedelta_range("1ns", periods=10)),
+            list(pd.timedelta_range("1ns", periods=10)),
+            pd.timedelta_range("1 Day", periods=10).astype(object),
+            pd.period_range("1971-01-01", freq="D", periods=10).array,
+            pd.period_range("1971-01-01", freq="D", periods=10).astype(object),
+        ],
+    )
+    def test_dt64arr_cmp_arraylike_invalid(
+        self, other, tz_naive_fixture, box_with_array
+    ):
+        tz = tz_naive_fixture
+
+        dta = date_range("1970-01-01", freq="ns", periods=10, tz=tz)._data
+        obj = tm.box_expected(dta, box_with_array)
+        assert_invalid_comparison(obj, other, box_with_array)
+
+    def test_dt64arr_cmp_mixed_invalid(self, tz_naive_fixture):
+        tz = tz_naive_fixture
+
+        dta = date_range("1970-01-01", freq="h", periods=5, tz=tz)._data
+
+        other = np.array([0, 1, 2, dta[3], Timedelta(days=1)])
+        result = dta == other
+        expected = np.array([False, False, False, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dta != other
+        tm.assert_numpy_array_equal(result, ~expected)
+
+        msg = "Invalid comparison between|Cannot compare type|not supported between"
+        with pytest.raises(TypeError, match=msg):
+            dta < other
+        with pytest.raises(TypeError, match=msg):
+            dta > other
+        with pytest.raises(TypeError, match=msg):
+            dta <= other
+        with pytest.raises(TypeError, match=msg):
+            dta >= other
+
+    def test_dt64arr_nat_comparison(self, tz_naive_fixture, box_with_array):
+        # GH#22242, GH#22163 DataFrame considered NaT == ts incorrectly
+        tz = tz_naive_fixture
+        box = box_with_array
+
+        ts = Timestamp("2021-01-01", tz=tz)
+        ser = Series([ts, NaT])
+
+        obj = tm.box_expected(ser, box)
+        xbox = get_upcast_box(obj, ts, True)
+
+        expected = Series([True, False], dtype=np.bool_)
+        expected = tm.box_expected(expected, xbox)
+
+        result = obj == ts
+        tm.assert_equal(result, expected)
+
+
+class TestDatetime64SeriesComparison:
+    # TODO: moved from tests.series.test_operators; needs cleanup
+
+    @pytest.mark.parametrize(
+        "pair",
+        [
+            (
+                [Timestamp("2011-01-01"), NaT, Timestamp("2011-01-03")],
+                [NaT, NaT, Timestamp("2011-01-03")],
+            ),
+            (
+                [Timedelta("1 days"), NaT, Timedelta("3 days")],
+                [NaT, NaT, Timedelta("3 days")],
+            ),
+            (
+                [Period("2011-01", freq="M"), NaT, Period("2011-03", freq="M")],
+                [NaT, NaT, Period("2011-03", freq="M")],
+            ),
+        ],
+    )
+    @pytest.mark.parametrize("reverse", [True, False])
+    @pytest.mark.parametrize("dtype", [None, object])
+    @pytest.mark.parametrize(
+        "op, expected",
+        [
+            (operator.eq, Series([False, False, True])),
+            (operator.ne, Series([True, True, False])),
+            (operator.lt, Series([False, False, False])),
+            (operator.gt, Series([False, False, False])),
+            (operator.ge, Series([False, False, True])),
+            (operator.le, Series([False, False, True])),
+        ],
+    )
+    def test_nat_comparisons(
+        self,
+        dtype,
+        index_or_series,
+        reverse,
+        pair,
+        op,
+        expected,
+    ):
+        box = index_or_series
+        lhs, rhs = pair
+        if reverse:
+            # add lhs / rhs switched data
+            lhs, rhs = rhs, lhs
+
+        left = Series(lhs, dtype=dtype)
+        right = box(rhs, dtype=dtype)
+
+        result = op(left, right)
+
+        tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "data",
+        [
+            [Timestamp("2011-01-01"), NaT, Timestamp("2011-01-03")],
+            [Timedelta("1 days"), NaT, Timedelta("3 days")],
+            [Period("2011-01", freq="M"), NaT, Period("2011-03", freq="M")],
+        ],
+    )
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_nat_comparisons_scalar(self, dtype, data, box_with_array):
+        box = box_with_array
+
+        left = Series(data, dtype=dtype)
+        left = tm.box_expected(left, box)
+        xbox = get_upcast_box(left, NaT, True)
+
+        expected = [False, False, False]
+        expected = tm.box_expected(expected, xbox)
+        if box is pd.array and dtype is object:
+            expected = pd.array(expected, dtype="bool")
+
+        tm.assert_equal(left == NaT, expected)
+        tm.assert_equal(NaT == left, expected)
+
+        expected = [True, True, True]
+        expected = tm.box_expected(expected, xbox)
+        if box is pd.array and dtype is object:
+            expected = pd.array(expected, dtype="bool")
+        tm.assert_equal(left != NaT, expected)
+        tm.assert_equal(NaT != left, expected)
+
+        expected = [False, False, False]
+        expected = tm.box_expected(expected, xbox)
+        if box is pd.array and dtype is object:
+            expected = pd.array(expected, dtype="bool")
+        tm.assert_equal(left < NaT, expected)
+        tm.assert_equal(NaT > left, expected)
+        tm.assert_equal(left <= NaT, expected)
+        tm.assert_equal(NaT >= left, expected)
+
+        tm.assert_equal(left > NaT, expected)
+        tm.assert_equal(NaT < left, expected)
+        tm.assert_equal(left >= NaT, expected)
+        tm.assert_equal(NaT <= left, expected)
+
+    @pytest.mark.parametrize("val", [datetime(2000, 1, 4), datetime(2000, 1, 5)])
+    def test_series_comparison_scalars(self, val):
+        series = Series(date_range("1/1/2000", periods=10))
+
+        result = series > val
+        expected = Series([x > val for x in series])
+        tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "left,right", [("lt", "gt"), ("le", "ge"), ("eq", "eq"), ("ne", "ne")]
+    )
+    def test_timestamp_compare_series(self, left, right):
+        # see gh-4982
+        # Make sure we can compare Timestamps on the right AND left hand side.
+        ser = Series(date_range("20010101", periods=10), name="dates")
+        s_nat = ser.copy(deep=True)
+
+        ser[0] = Timestamp("nat")
+        ser[3] = Timestamp("nat")
+
+        left_f = getattr(operator, left)
+        right_f = getattr(operator, right)
+
+        # No NaT
+        expected = left_f(ser, Timestamp("20010109"))
+        result = right_f(Timestamp("20010109"), ser)
+        tm.assert_series_equal(result, expected)
+
+        # NaT
+        expected = left_f(ser, Timestamp("nat"))
+        result = right_f(Timestamp("nat"), ser)
+        tm.assert_series_equal(result, expected)
+
+        # Compare to Timestamp with series containing NaT
+        expected = left_f(s_nat, Timestamp("20010109"))
+        result = right_f(Timestamp("20010109"), s_nat)
+        tm.assert_series_equal(result, expected)
+
+        # Compare to NaT with series containing NaT
+        expected = left_f(s_nat, NaT)
+        result = right_f(NaT, s_nat)
+        tm.assert_series_equal(result, expected)
+
+    def test_dt64arr_timestamp_equality(self, box_with_array):
+        # GH#11034
+        box = box_with_array
+
+        ser = Series([Timestamp("2000-01-29 01:59:00"), Timestamp("2000-01-30"), NaT])
+        ser = tm.box_expected(ser, box)
+        xbox = get_upcast_box(ser, ser, True)
+
+        result = ser != ser
+        expected = tm.box_expected([False, False, True], xbox)
+        tm.assert_equal(result, expected)
+
+        if box is pd.DataFrame:
+            # alignment for frame vs series comparisons deprecated
+            #  in GH#46795 enforced 2.0
+            with pytest.raises(ValueError, match="not aligned"):
+                ser != ser[0]
+
+        else:
+            result = ser != ser[0]
+            expected = tm.box_expected([False, True, True], xbox)
+            tm.assert_equal(result, expected)
+
+        if box is pd.DataFrame:
+            # alignment for frame vs series comparisons deprecated
+            #  in GH#46795 enforced 2.0
+            with pytest.raises(ValueError, match="not aligned"):
+                ser != ser[2]
+        else:
+            result = ser != ser[2]
+            expected = tm.box_expected([True, True, True], xbox)
+            tm.assert_equal(result, expected)
+
+        result = ser == ser
+        expected = tm.box_expected([True, True, False], xbox)
+        tm.assert_equal(result, expected)
+
+        if box is pd.DataFrame:
+            # alignment for frame vs series comparisons deprecated
+            #  in GH#46795 enforced 2.0
+            with pytest.raises(ValueError, match="not aligned"):
+                ser == ser[0]
+        else:
+            result = ser == ser[0]
+            expected = tm.box_expected([True, False, False], xbox)
+            tm.assert_equal(result, expected)
+
+        if box is pd.DataFrame:
+            # alignment for frame vs series comparisons deprecated
+            #  in GH#46795 enforced 2.0
+            with pytest.raises(ValueError, match="not aligned"):
+                ser == ser[2]
+        else:
+            result = ser == ser[2]
+            expected = tm.box_expected([False, False, False], xbox)
+            tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "datetimelike",
+        [
+            Timestamp("20130101"),
+            datetime(2013, 1, 1),
+            np.datetime64("2013-01-01T00:00", "ns"),
+        ],
+    )
+    @pytest.mark.parametrize(
+        "op,expected",
+        [
+            (operator.lt, [True, False, False, False]),
+            (operator.le, [True, True, False, False]),
+            (operator.eq, [False, True, False, False]),
+            (operator.gt, [False, False, False, True]),
+        ],
+    )
+    def test_dt64_compare_datetime_scalar(self, datetimelike, op, expected):
+        # GH#17965, test for ability to compare datetime64[ns] columns
+        #  to datetimelike
+        ser = Series(
+            [
+                Timestamp("20120101"),
+                Timestamp("20130101"),
+                np.nan,
+                Timestamp("20130103"),
+            ],
+            name="A",
+        )
+        result = op(ser, datetimelike)
+        expected = Series(expected, name="A")
+        tm.assert_series_equal(result, expected)
+
+
+class TestDatetimeIndexComparisons:
+    # TODO: moved from tests.indexes.test_base; parametrize and de-duplicate
+    def test_comparators(self, comparison_op):
+        index = date_range("2020-01-01", periods=10)
+        element = index[len(index) // 2]
+        element = Timestamp(element).to_datetime64()
+
+        arr = np.array(index)
+        arr_result = comparison_op(arr, element)
+        index_result = comparison_op(index, element)
+
+        assert isinstance(index_result, np.ndarray)
+        tm.assert_numpy_array_equal(arr_result, index_result)
+
+    @pytest.mark.parametrize(
+        "other",
+        [datetime(2016, 1, 1), Timestamp("2016-01-01"), np.datetime64("2016-01-01")],
+    )
+    def test_dti_cmp_datetimelike(self, other, tz_naive_fixture):
+        tz = tz_naive_fixture
+        dti = date_range("2016-01-01", periods=2, tz=tz)
+        if tz is not None:
+            if isinstance(other, np.datetime64):
+                pytest.skip(f"{type(other).__name__} is not tz aware")
+            other = localize_pydatetime(other, dti.tzinfo)
+
+        result = dti == other
+        expected = np.array([True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dti > other
+        expected = np.array([False, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dti >= other
+        expected = np.array([True, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dti < other
+        expected = np.array([False, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dti <= other
+        expected = np.array([True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_dti_cmp_nat(self, dtype, box_with_array):
+        left = DatetimeIndex([Timestamp("2011-01-01"), NaT, Timestamp("2011-01-03")])
+        right = DatetimeIndex([NaT, NaT, Timestamp("2011-01-03")])
+
+        left = tm.box_expected(left, box_with_array)
+        right = tm.box_expected(right, box_with_array)
+        xbox = get_upcast_box(left, right, True)
+
+        lhs, rhs = left, right
+        if dtype is object:
+            lhs, rhs = left.astype(object), right.astype(object)
+
+        result = rhs == lhs
+        expected = np.array([False, False, True])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(result, expected)
+
+        result = lhs != rhs
+        expected = np.array([True, True, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(result, expected)
+
+        expected = np.array([False, False, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(lhs == NaT, expected)
+        tm.assert_equal(NaT == rhs, expected)
+
+        expected = np.array([True, True, True])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(lhs != NaT, expected)
+        tm.assert_equal(NaT != lhs, expected)
+
+        expected = np.array([False, False, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(lhs < NaT, expected)
+        tm.assert_equal(NaT > lhs, expected)
+
+    def test_dti_cmp_nat_behaves_like_float_cmp_nan(self):
+        fidx1 = pd.Index([1.0, np.nan, 3.0, np.nan, 5.0, 7.0])
+        fidx2 = pd.Index([2.0, 3.0, np.nan, np.nan, 6.0, 7.0])
+
+        didx1 = DatetimeIndex(
+            ["2014-01-01", NaT, "2014-03-01", NaT, "2014-05-01", "2014-07-01"]
+        )
+        didx2 = DatetimeIndex(
+            ["2014-02-01", "2014-03-01", NaT, NaT, "2014-06-01", "2014-07-01"]
+        )
+        darr = np.array(
+            [
+                np.datetime64("2014-02-01 00:00"),
+                np.datetime64("2014-03-01 00:00"),
+                np.datetime64("nat"),
+                np.datetime64("nat"),
+                np.datetime64("2014-06-01 00:00"),
+                np.datetime64("2014-07-01 00:00"),
+            ]
+        )
+
+        cases = [(fidx1, fidx2), (didx1, didx2), (didx1, darr)]
+
+        # Check pd.NaT is handles as the same as np.nan
+        with tm.assert_produces_warning(None):
+            for idx1, idx2 in cases:
+                result = idx1 < idx2
+                expected = np.array([True, False, False, False, True, False])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx2 > idx1
+                expected = np.array([True, False, False, False, True, False])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 <= idx2
+                expected = np.array([True, False, False, False, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx2 >= idx1
+                expected = np.array([True, False, False, False, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 == idx2
+                expected = np.array([False, False, False, False, False, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 != idx2
+                expected = np.array([True, True, True, True, True, False])
+                tm.assert_numpy_array_equal(result, expected)
+
+        with tm.assert_produces_warning(None):
+            for idx1, val in [(fidx1, np.nan), (didx1, NaT)]:
+                result = idx1 < val
+                expected = np.array([False, False, False, False, False, False])
+                tm.assert_numpy_array_equal(result, expected)
+                result = idx1 > val
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 <= val
+                tm.assert_numpy_array_equal(result, expected)
+                result = idx1 >= val
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 == val
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 != val
+                expected = np.array([True, True, True, True, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+        # Check pd.NaT is handles as the same as np.nan
+        with tm.assert_produces_warning(None):
+            for idx1, val in [(fidx1, 3), (didx1, datetime(2014, 3, 1))]:
+                result = idx1 < val
+                expected = np.array([True, False, False, False, False, False])
+                tm.assert_numpy_array_equal(result, expected)
+                result = idx1 > val
+                expected = np.array([False, False, False, False, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 <= val
+                expected = np.array([True, False, True, False, False, False])
+                tm.assert_numpy_array_equal(result, expected)
+                result = idx1 >= val
+                expected = np.array([False, False, True, False, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 == val
+                expected = np.array([False, False, True, False, False, False])
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = idx1 != val
+                expected = np.array([True, True, False, True, True, True])
+                tm.assert_numpy_array_equal(result, expected)
+
+    def test_comparison_tzawareness_compat(self, comparison_op, box_with_array):
+        # GH#18162
+        op = comparison_op
+        box = box_with_array
+
+        dr = date_range("2016-01-01", periods=6)
+        dz = dr.tz_localize("US/Pacific")
+
+        dr = tm.box_expected(dr, box)
+        dz = tm.box_expected(dz, box)
+
+        if box is pd.DataFrame:
+            tolist = lambda x: x.astype(object).values.tolist()[0]
+        else:
+            tolist = list
+
+        if op not in [operator.eq, operator.ne]:
+            msg = (
+                r"Invalid comparison between dtype=datetime64\[ns.*\] "
+                "and (Timestamp|DatetimeArray|list|ndarray)"
+            )
+            with pytest.raises(TypeError, match=msg):
+                op(dr, dz)
+
+            with pytest.raises(TypeError, match=msg):
+                op(dr, tolist(dz))
+            with pytest.raises(TypeError, match=msg):
+                op(dr, np.array(tolist(dz), dtype=object))
+            with pytest.raises(TypeError, match=msg):
+                op(dz, dr)
+
+            with pytest.raises(TypeError, match=msg):
+                op(dz, tolist(dr))
+            with pytest.raises(TypeError, match=msg):
+                op(dz, np.array(tolist(dr), dtype=object))
+
+        # The aware==aware and naive==naive comparisons should *not* raise
+        assert np.all(dr == dr)
+        assert np.all(dr == tolist(dr))
+        assert np.all(tolist(dr) == dr)
+        assert np.all(np.array(tolist(dr), dtype=object) == dr)
+        assert np.all(dr == np.array(tolist(dr), dtype=object))
+
+        assert np.all(dz == dz)
+        assert np.all(dz == tolist(dz))
+        assert np.all(tolist(dz) == dz)
+        assert np.all(np.array(tolist(dz), dtype=object) == dz)
+        assert np.all(dz == np.array(tolist(dz), dtype=object))
+
+    def test_comparison_tzawareness_compat_scalars(self, comparison_op, box_with_array):
+        # GH#18162
+        op = comparison_op
+
+        dr = date_range("2016-01-01", periods=6)
+        dz = dr.tz_localize("US/Pacific")
+
+        dr = tm.box_expected(dr, box_with_array)
+        dz = tm.box_expected(dz, box_with_array)
+
+        # Check comparisons against scalar Timestamps
+        ts = Timestamp("2000-03-14 01:59")
+        ts_tz = Timestamp("2000-03-14 01:59", tz="Europe/Amsterdam")
+
+        assert np.all(dr > ts)
+        msg = r"Invalid comparison between dtype=datetime64\[ns.*\] and Timestamp"
+        if op not in [operator.eq, operator.ne]:
+            with pytest.raises(TypeError, match=msg):
+                op(dr, ts_tz)
+
+        assert np.all(dz > ts_tz)
+        if op not in [operator.eq, operator.ne]:
+            with pytest.raises(TypeError, match=msg):
+                op(dz, ts)
+
+        if op not in [operator.eq, operator.ne]:
+            # GH#12601: Check comparison against Timestamps and DatetimeIndex
+            with pytest.raises(TypeError, match=msg):
+                op(ts, dz)
+
+    @pytest.mark.parametrize(
+        "other",
+        [datetime(2016, 1, 1), Timestamp("2016-01-01"), np.datetime64("2016-01-01")],
+    )
+    # Bug in NumPy? https://github.com/numpy/numpy/issues/13841
+    # Raising in __eq__ will fallback to NumPy, which warns, fails,
+    # then re-raises the original exception. So we just need to ignore.
+    @pytest.mark.filterwarnings("ignore:elementwise comp:DeprecationWarning")
+    def test_scalar_comparison_tzawareness(
+        self, comparison_op, other, tz_aware_fixture, box_with_array
+    ):
+        op = comparison_op
+        tz = tz_aware_fixture
+        dti = date_range("2016-01-01", periods=2, tz=tz)
+
+        dtarr = tm.box_expected(dti, box_with_array)
+        xbox = get_upcast_box(dtarr, other, True)
+        if op in [operator.eq, operator.ne]:
+            exbool = op is operator.ne
+            expected = np.array([exbool, exbool], dtype=bool)
+            expected = tm.box_expected(expected, xbox)
+
+            result = op(dtarr, other)
+            tm.assert_equal(result, expected)
+
+            result = op(other, dtarr)
+            tm.assert_equal(result, expected)
+        else:
+            msg = (
+                r"Invalid comparison between dtype=datetime64\[ns, .*\] "
+                f"and {type(other).__name__}"
+            )
+            with pytest.raises(TypeError, match=msg):
+                op(dtarr, other)
+            with pytest.raises(TypeError, match=msg):
+                op(other, dtarr)
+
+    def test_nat_comparison_tzawareness(self, comparison_op):
+        # GH#19276
+        # tzaware DatetimeIndex should not raise when compared to NaT
+        op = comparison_op
+
+        dti = DatetimeIndex(
+            ["2014-01-01", NaT, "2014-03-01", NaT, "2014-05-01", "2014-07-01"]
+        )
+        expected = np.array([op == operator.ne] * len(dti))
+        result = op(dti, NaT)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = op(dti.tz_localize("US/Pacific"), NaT)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_dti_cmp_str(self, tz_naive_fixture):
+        # GH#22074
+        # regardless of tz, we expect these comparisons are valid
+        tz = tz_naive_fixture
+        rng = date_range("1/1/2000", periods=10, tz=tz)
+        other = "1/1/2000"
+
+        result = rng == other
+        expected = np.array([True] + [False] * 9)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng != other
+        expected = np.array([False] + [True] * 9)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng < other
+        expected = np.array([False] * 10)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng <= other
+        expected = np.array([True] + [False] * 9)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng > other
+        expected = np.array([False] + [True] * 9)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng >= other
+        expected = np.array([True] * 10)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_dti_cmp_list(self):
+        rng = date_range("1/1/2000", periods=10)
+
+        result = rng == list(rng)
+        expected = rng == rng
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            pd.timedelta_range("1D", periods=10),
+            pd.timedelta_range("1D", periods=10).to_series(),
+            pd.timedelta_range("1D", periods=10).asi8.view("m8[ns]"),
+        ],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_dti_cmp_tdi_tzawareness(self, other):
+        # GH#22074
+        # reversion test that we _don't_ call _assert_tzawareness_compat
+        # when comparing against TimedeltaIndex
+        dti = date_range("2000-01-01", periods=10, tz="Asia/Tokyo")
+
+        result = dti == other
+        expected = np.array([False] * 10)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = dti != other
+        expected = np.array([True] * 10)
+        tm.assert_numpy_array_equal(result, expected)
+        msg = "Invalid comparison between"
+        with pytest.raises(TypeError, match=msg):
+            dti < other
+        with pytest.raises(TypeError, match=msg):
+            dti <= other
+        with pytest.raises(TypeError, match=msg):
+            dti > other
+        with pytest.raises(TypeError, match=msg):
+            dti >= other
+
+    def test_dti_cmp_object_dtype(self):
+        # GH#22074
+        dti = date_range("2000-01-01", periods=10, tz="Asia/Tokyo")
+
+        other = dti.astype("O")
+
+        result = dti == other
+        expected = np.array([True] * 10)
+        tm.assert_numpy_array_equal(result, expected)
+
+        other = dti.tz_localize(None)
+        result = dti != other
+        tm.assert_numpy_array_equal(result, expected)
+
+        other = np.array(list(dti[:5]) + [Timedelta(days=1)] * 5)
+        result = dti == other
+        expected = np.array([True] * 5 + [False] * 5)
+        tm.assert_numpy_array_equal(result, expected)
+        msg = ">=' not supported between instances of 'Timestamp' and 'Timedelta'"
+        with pytest.raises(TypeError, match=msg):
+            dti >= other
+
+
+# ------------------------------------------------------------------
+# Arithmetic
+
+
+class TestDatetime64Arithmetic:
+    # This class is intended for "finished" tests that are fully parametrized
+    #  over DataFrame/Series/Index/DatetimeArray
+
+    # -------------------------------------------------------------
+    # Addition/Subtraction of timedelta-like
+
+    @pytest.mark.arm_slow
+    def test_dt64arr_add_timedeltalike_scalar(
+        self, tz_naive_fixture, two_hours, box_with_array
+    ):
+        # GH#22005, GH#22163 check DataFrame doesn't raise TypeError
+        tz = tz_naive_fixture
+
+        rng = date_range("2000-01-01", "2000-02-01", tz=tz)
+        expected = date_range("2000-01-01 02:00", "2000-02-01 02:00", tz=tz)
+
+        rng = tm.box_expected(rng, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = rng + two_hours
+        tm.assert_equal(result, expected)
+
+        result = two_hours + rng
+        tm.assert_equal(result, expected)
+
+        rng += two_hours
+        tm.assert_equal(rng, expected)
+
+    def test_dt64arr_sub_timedeltalike_scalar(
+        self, tz_naive_fixture, two_hours, box_with_array
+    ):
+        tz = tz_naive_fixture
+
+        rng = date_range("2000-01-01", "2000-02-01", tz=tz)
+        expected = date_range("1999-12-31 22:00", "2000-01-31 22:00", tz=tz)
+
+        rng = tm.box_expected(rng, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = rng - two_hours
+        tm.assert_equal(result, expected)
+
+        rng -= two_hours
+        tm.assert_equal(rng, expected)
+
+    def test_dt64_array_sub_dt_with_different_timezone(self, box_with_array):
+        t1 = date_range("20130101", periods=3).tz_localize("US/Eastern")
+        t1 = tm.box_expected(t1, box_with_array)
+        t2 = Timestamp("20130101").tz_localize("CET")
+        tnaive = Timestamp(20130101)
+
+        result = t1 - t2
+        expected = TimedeltaIndex(
+            ["0 days 06:00:00", "1 days 06:00:00", "2 days 06:00:00"]
+        )
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = t2 - t1
+        expected = TimedeltaIndex(
+            ["-1 days +18:00:00", "-2 days +18:00:00", "-3 days +18:00:00"]
+        )
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        msg = "Cannot subtract tz-naive and tz-aware datetime-like objects"
+        with pytest.raises(TypeError, match=msg):
+            t1 - tnaive
+
+        with pytest.raises(TypeError, match=msg):
+            tnaive - t1
+
+    def test_dt64_array_sub_dt64_array_with_different_timezone(self, box_with_array):
+        t1 = date_range("20130101", periods=3).tz_localize("US/Eastern")
+        t1 = tm.box_expected(t1, box_with_array)
+        t2 = date_range("20130101", periods=3).tz_localize("CET")
+        t2 = tm.box_expected(t2, box_with_array)
+        tnaive = date_range("20130101", periods=3)
+
+        result = t1 - t2
+        expected = TimedeltaIndex(
+            ["0 days 06:00:00", "0 days 06:00:00", "0 days 06:00:00"]
+        )
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = t2 - t1
+        expected = TimedeltaIndex(
+            ["-1 days +18:00:00", "-1 days +18:00:00", "-1 days +18:00:00"]
+        )
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        msg = "Cannot subtract tz-naive and tz-aware datetime-like objects"
+        with pytest.raises(TypeError, match=msg):
+            t1 - tnaive
+
+        with pytest.raises(TypeError, match=msg):
+            tnaive - t1
+
+    def test_dt64arr_add_sub_td64_nat(self, box_with_array, tz_naive_fixture):
+        # GH#23320 special handling for timedelta64("NaT")
+        tz = tz_naive_fixture
+
+        dti = date_range("1994-04-01", periods=9, tz=tz, freq="QS")
+        other = np.timedelta64("NaT")
+        expected = DatetimeIndex(["NaT"] * 9, tz=tz).as_unit("ns")
+
+        obj = tm.box_expected(dti, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = obj + other
+        tm.assert_equal(result, expected)
+        result = other + obj
+        tm.assert_equal(result, expected)
+        result = obj - other
+        tm.assert_equal(result, expected)
+        msg = "cannot subtract"
+        with pytest.raises(TypeError, match=msg):
+            other - obj
+
+    def test_dt64arr_add_sub_td64ndarray(self, tz_naive_fixture, box_with_array):
+        tz = tz_naive_fixture
+        dti = date_range("2016-01-01", periods=3, tz=tz)
+        tdi = TimedeltaIndex(["-1 Day", "-1 Day", "-1 Day"])
+        tdarr = tdi.values
+
+        expected = date_range("2015-12-31", "2016-01-02", periods=3, tz=tz)
+
+        dtarr = tm.box_expected(dti, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = dtarr + tdarr
+        tm.assert_equal(result, expected)
+        result = tdarr + dtarr
+        tm.assert_equal(result, expected)
+
+        expected = date_range("2016-01-02", "2016-01-04", periods=3, tz=tz)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = dtarr - tdarr
+        tm.assert_equal(result, expected)
+        msg = "cannot subtract|(bad|unsupported) operand type for unary"
+        with pytest.raises(TypeError, match=msg):
+            tdarr - dtarr
+
+    # -----------------------------------------------------------------
+    # Subtraction of datetime-like scalars
+
+    @pytest.mark.parametrize(
+        "ts",
+        [
+            Timestamp("2013-01-01"),
+            Timestamp("2013-01-01").to_pydatetime(),
+            Timestamp("2013-01-01").to_datetime64(),
+            # GH#7996, GH#22163 ensure non-nano datetime64 is converted to nano
+            #  for DataFrame operation
+            np.datetime64("2013-01-01", "D"),
+        ],
+    )
+    def test_dt64arr_sub_dtscalar(self, box_with_array, ts):
+        # GH#8554, GH#22163 DataFrame op should _not_ return dt64 dtype
+        idx = date_range("2013-01-01", periods=3)._with_freq(None)
+        idx = tm.box_expected(idx, box_with_array)
+
+        expected = TimedeltaIndex(["0 Days", "1 Day", "2 Days"])
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = idx - ts
+        tm.assert_equal(result, expected)
+
+        result = ts - idx
+        tm.assert_equal(result, -expected)
+        tm.assert_equal(result, -expected)
+
+    def test_dt64arr_sub_timestamp_tzaware(self, box_with_array):
+        ser = date_range("2014-03-17", periods=2, freq="D", tz="US/Eastern")
+        ser = ser._with_freq(None)
+        ts = ser[0]
+
+        ser = tm.box_expected(ser, box_with_array)
+
+        delta_series = Series([np.timedelta64(0, "D"), np.timedelta64(1, "D")])
+        expected = tm.box_expected(delta_series, box_with_array)
+
+        tm.assert_equal(ser - ts, expected)
+        tm.assert_equal(ts - ser, -expected)
+
+    def test_dt64arr_sub_NaT(self, box_with_array, unit):
+        # GH#18808
+        dti = DatetimeIndex([NaT, Timestamp("19900315")]).as_unit(unit)
+        ser = tm.box_expected(dti, box_with_array)
+
+        result = ser - NaT
+        expected = Series([NaT, NaT], dtype=f"timedelta64[{unit}]")
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        dti_tz = dti.tz_localize("Asia/Tokyo")
+        ser_tz = tm.box_expected(dti_tz, box_with_array)
+
+        result = ser_tz - NaT
+        expected = Series([NaT, NaT], dtype=f"timedelta64[{unit}]")
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+    # -------------------------------------------------------------
+    # Subtraction of datetime-like array-like
+
+    def test_dt64arr_sub_dt64object_array(self, box_with_array, tz_naive_fixture):
+        dti = date_range("2016-01-01", periods=3, tz=tz_naive_fixture)
+        expected = dti - dti
+
+        obj = tm.box_expected(dti, box_with_array)
+        expected = tm.box_expected(expected, box_with_array).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = obj - obj.astype(object)
+        tm.assert_equal(result, expected)
+
+    def test_dt64arr_naive_sub_dt64ndarray(self, box_with_array):
+        dti = date_range("2016-01-01", periods=3, tz=None)
+        dt64vals = dti.values
+
+        dtarr = tm.box_expected(dti, box_with_array)
+
+        expected = dtarr - dtarr
+        result = dtarr - dt64vals
+        tm.assert_equal(result, expected)
+        result = dt64vals - dtarr
+        tm.assert_equal(result, expected)
+
+    def test_dt64arr_aware_sub_dt64ndarray_raises(
+        self, tz_aware_fixture, box_with_array
+    ):
+        tz = tz_aware_fixture
+        dti = date_range("2016-01-01", periods=3, tz=tz)
+        dt64vals = dti.values
+
+        dtarr = tm.box_expected(dti, box_with_array)
+        msg = "Cannot subtract tz-naive and tz-aware datetime"
+        with pytest.raises(TypeError, match=msg):
+            dtarr - dt64vals
+        with pytest.raises(TypeError, match=msg):
+            dt64vals - dtarr
+
+    # -------------------------------------------------------------
+    # Addition of datetime-like others (invalid)
+
+    def test_dt64arr_add_dtlike_raises(self, tz_naive_fixture, box_with_array):
+        # GH#22163 ensure DataFrame doesn't cast Timestamp to i8
+        # GH#9631
+        tz = tz_naive_fixture
+
+        dti = date_range("2016-01-01", periods=3, tz=tz)
+        if tz is None:
+            dti2 = dti.tz_localize("US/Eastern")
+        else:
+            dti2 = dti.tz_localize(None)
+        dtarr = tm.box_expected(dti, box_with_array)
+
+        assert_cannot_add(dtarr, dti.values)
+        assert_cannot_add(dtarr, dti)
+        assert_cannot_add(dtarr, dtarr)
+        assert_cannot_add(dtarr, dti[0])
+        assert_cannot_add(dtarr, dti[0].to_pydatetime())
+        assert_cannot_add(dtarr, dti[0].to_datetime64())
+        assert_cannot_add(dtarr, dti2[0])
+        assert_cannot_add(dtarr, dti2[0].to_pydatetime())
+        assert_cannot_add(dtarr, np.datetime64("2011-01-01", "D"))
+
+    # -------------------------------------------------------------
+    # Other Invalid Addition/Subtraction
+
+    # Note: freq here includes both Tick and non-Tick offsets; this is
+    #  relevant because historically integer-addition was allowed if we had
+    #  a freq.
+    @pytest.mark.parametrize("freq", ["h", "D", "W", "2ME", "MS", "QE", "B", None])
+    @pytest.mark.parametrize("dtype", [None, "uint8"])
+    def test_dt64arr_addsub_intlike(
+        self, request, dtype, index_or_series_or_array, freq, tz_naive_fixture
+    ):
+        # GH#19959, GH#19123, GH#19012
+        # GH#55860 use index_or_series_or_array instead of box_with_array
+        #  bc DataFrame alignment makes it inapplicable
+        tz = tz_naive_fixture
+
+        if freq is None:
+            dti = DatetimeIndex(["NaT", "2017-04-05 06:07:08"], tz=tz)
+        else:
+            dti = date_range("2016-01-01", periods=2, freq=freq, tz=tz)
+
+        obj = index_or_series_or_array(dti)
+        other = np.array([4, -1])
+        if dtype is not None:
+            other = other.astype(dtype)
+
+        msg = "|".join(
+            [
+                "Addition/subtraction of integers",
+                "cannot subtract DatetimeArray from",
+                # IntegerArray
+                "can only perform ops with numeric values",
+                "unsupported operand type.*Categorical",
+                r"unsupported operand type\(s\) for -: 'int' and 'Timestamp'",
+            ]
+        )
+        assert_invalid_addsub_type(obj, 1, msg)
+        assert_invalid_addsub_type(obj, np.int64(2), msg)
+        assert_invalid_addsub_type(obj, np.array(3, dtype=np.int64), msg)
+        assert_invalid_addsub_type(obj, other, msg)
+        assert_invalid_addsub_type(obj, np.array(other), msg)
+        assert_invalid_addsub_type(obj, pd.array(other), msg)
+        assert_invalid_addsub_type(obj, pd.Categorical(other), msg)
+        assert_invalid_addsub_type(obj, pd.Index(other), msg)
+        assert_invalid_addsub_type(obj, Series(other), msg)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            3.14,
+            np.array([2.0, 3.0]),
+            # GH#13078 datetime +/- Period is invalid
+            Period("2011-01-01", freq="D"),
+            # https://github.com/pandas-dev/pandas/issues/10329
+            time(1, 2, 3),
+        ],
+    )
+    @pytest.mark.parametrize("dti_freq", [None, "D"])
+    def test_dt64arr_add_sub_invalid(self, dti_freq, other, box_with_array):
+        dti = DatetimeIndex(["2011-01-01", "2011-01-02"], freq=dti_freq)
+        dtarr = tm.box_expected(dti, box_with_array)
+        msg = "|".join(
+            [
+                "unsupported operand type",
+                "cannot (add|subtract)",
+                "cannot use operands with types",
+                "ufunc '?(add|subtract)'? cannot use operands with types",
+                "Concatenation operation is not implemented for NumPy arrays",
+            ]
+        )
+        assert_invalid_addsub_type(dtarr, other, msg)
+
+    @pytest.mark.parametrize("pi_freq", ["D", "W", "Q", "h"])
+    @pytest.mark.parametrize("dti_freq", [None, "D"])
+    def test_dt64arr_add_sub_parr(
+        self, dti_freq, pi_freq, box_with_array, box_with_array2
+    ):
+        # GH#20049 subtracting PeriodIndex should raise TypeError
+        dti = DatetimeIndex(["2011-01-01", "2011-01-02"], freq=dti_freq)
+        pi = dti.to_period(pi_freq)
+
+        dtarr = tm.box_expected(dti, box_with_array)
+        parr = tm.box_expected(pi, box_with_array2)
+        msg = "|".join(
+            [
+                "cannot (add|subtract)",
+                "unsupported operand",
+                "descriptor.*requires",
+                "ufunc.*cannot use operands",
+            ]
+        )
+        assert_invalid_addsub_type(dtarr, parr, msg)
+
+    @pytest.mark.filterwarnings("ignore::pandas.errors.PerformanceWarning")
+    def test_dt64arr_addsub_time_objects_raises(self, box_with_array, tz_naive_fixture):
+        # https://github.com/pandas-dev/pandas/issues/10329
+
+        tz = tz_naive_fixture
+
+        obj1 = date_range("2012-01-01", periods=3, tz=tz)
+        obj2 = [time(i, i, i) for i in range(3)]
+
+        obj1 = tm.box_expected(obj1, box_with_array)
+        obj2 = tm.box_expected(obj2, box_with_array)
+
+        msg = "|".join(
+            [
+                "unsupported operand",
+                "cannot subtract DatetimeArray from ndarray",
+            ]
+        )
+        # pandas.errors.PerformanceWarning: Non-vectorized DateOffset being
+        # applied to Series or DatetimeIndex
+        # we aren't testing that here, so ignore.
+        assert_invalid_addsub_type(obj1, obj2, msg=msg)
+
+    # -------------------------------------------------------------
+    # Other invalid operations
+
+    @pytest.mark.parametrize(
+        "dt64_series",
+        [
+            Series([Timestamp("19900315"), Timestamp("19900315")]),
+            Series([NaT, Timestamp("19900315")]),
+            Series([NaT, NaT], dtype="datetime64[ns]"),
+        ],
+    )
+    @pytest.mark.parametrize("one", [1, 1.0, np.array(1)])
+    def test_dt64_mul_div_numeric_invalid(self, one, dt64_series, box_with_array):
+        obj = tm.box_expected(dt64_series, box_with_array)
+
+        msg = "cannot perform .* with this index type"
+
+        # multiplication
+        with pytest.raises(TypeError, match=msg):
+            obj * one
+        with pytest.raises(TypeError, match=msg):
+            one * obj
+
+        # division
+        with pytest.raises(TypeError, match=msg):
+            obj / one
+        with pytest.raises(TypeError, match=msg):
+            one / obj
+
+
+class TestDatetime64DateOffsetArithmetic:
+    # -------------------------------------------------------------
+    # Tick DateOffsets
+
+    # TODO: parametrize over timezone?
+    @pytest.mark.parametrize("unit", ["s", "ms", "us", "ns"])
+    def test_dt64arr_series_add_tick_DateOffset(self, box_with_array, unit):
+        # GH#4532
+        # operate with pd.offsets
+        ser = Series(
+            [Timestamp("20130101 9:01"), Timestamp("20130101 9:02")]
+        ).dt.as_unit(unit)
+        expected = Series(
+            [Timestamp("20130101 9:01:05"), Timestamp("20130101 9:02:05")]
+        ).dt.as_unit(unit)
+
+        ser = tm.box_expected(ser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = ser + pd.offsets.Second(5)
+        tm.assert_equal(result, expected)
+
+        result2 = pd.offsets.Second(5) + ser
+        tm.assert_equal(result2, expected)
+
+    def test_dt64arr_series_sub_tick_DateOffset(self, box_with_array):
+        # GH#4532
+        # operate with pd.offsets
+        ser = Series([Timestamp("20130101 9:01"), Timestamp("20130101 9:02")])
+        expected = Series(
+            [Timestamp("20130101 9:00:55"), Timestamp("20130101 9:01:55")]
+        )
+
+        ser = tm.box_expected(ser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = ser - pd.offsets.Second(5)
+        tm.assert_equal(result, expected)
+
+        result2 = -pd.offsets.Second(5) + ser
+        tm.assert_equal(result2, expected)
+        msg = "(bad|unsupported) operand type for unary"
+        with pytest.raises(TypeError, match=msg):
+            pd.offsets.Second(5) - ser
+
+    @pytest.mark.parametrize(
+        "cls_name", ["Day", "Hour", "Minute", "Second", "Milli", "Micro", "Nano"]
+    )
+    def test_dt64arr_add_sub_tick_DateOffset_smoke(self, cls_name, box_with_array):
+        # GH#4532
+        # smoke tests for valid DateOffsets
+        ser = Series([Timestamp("20130101 9:01"), Timestamp("20130101 9:02")])
+        ser = tm.box_expected(ser, box_with_array)
+
+        offset_cls = getattr(pd.offsets, cls_name)
+        ser + offset_cls(5)
+        offset_cls(5) + ser
+        ser - offset_cls(5)
+
+    def test_dti_add_tick_tzaware(self, tz_aware_fixture, box_with_array):
+        # GH#21610, GH#22163 ensure DataFrame doesn't return object-dtype
+        tz = tz_aware_fixture
+        if tz == "US/Pacific":
+            dates = date_range("2012-11-01", periods=3, tz=tz)
+            offset = dates + pd.offsets.Hour(5)
+            assert dates[0] + pd.offsets.Hour(5) == offset[0]
+
+        dates = date_range("2010-11-01 00:00", periods=3, tz=tz, freq="h")
+        expected = DatetimeIndex(
+            ["2010-11-01 05:00", "2010-11-01 06:00", "2010-11-01 07:00"],
+            freq="h",
+            tz=tz,
+        ).as_unit("ns")
+
+        dates = tm.box_expected(dates, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        for scalar in [pd.offsets.Hour(5), np.timedelta64(5, "h"), timedelta(hours=5)]:
+            offset = dates + scalar
+            tm.assert_equal(offset, expected)
+            offset = scalar + dates
+            tm.assert_equal(offset, expected)
+
+            roundtrip = offset - scalar
+            tm.assert_equal(roundtrip, dates)
+
+            msg = "|".join(
+                ["bad operand type for unary -", "cannot subtract DatetimeArray"]
+            )
+            with pytest.raises(TypeError, match=msg):
+                scalar - dates
+
+    # -------------------------------------------------------------
+    # RelativeDelta DateOffsets
+
+    @pytest.mark.parametrize("unit", ["s", "ms", "us", "ns"])
+    def test_dt64arr_add_sub_relativedelta_offsets(self, box_with_array, unit):
+        # GH#10699
+        vec = DatetimeIndex(
+            [
+                Timestamp("2000-01-05 00:15:00"),
+                Timestamp("2000-01-31 00:23:00"),
+                Timestamp("2000-01-01"),
+                Timestamp("2000-03-31"),
+                Timestamp("2000-02-29"),
+                Timestamp("2000-12-31"),
+                Timestamp("2000-05-15"),
+                Timestamp("2001-06-15"),
+            ]
+        ).as_unit(unit)
+        vec = tm.box_expected(vec, box_with_array)
+        vec_items = vec.iloc[0] if box_with_array is pd.DataFrame else vec
+
+        # DateOffset relativedelta fastpath
+        relative_kwargs = [
+            ("years", 2),
+            ("months", 5),
+            ("days", 3),
+            ("hours", 5),
+            ("minutes", 10),
+            ("seconds", 2),
+            ("microseconds", 5),
+        ]
+        for i, (offset_unit, value) in enumerate(relative_kwargs):
+            off = DateOffset(**{offset_unit: value})
+
+            exp_unit = unit
+            if offset_unit == "microseconds" and unit != "ns":
+                exp_unit = "us"
+
+            # TODO(GH#55564): as_unit will be unnecessary
+            expected = DatetimeIndex([x + off for x in vec_items]).as_unit(exp_unit)
+            expected = tm.box_expected(expected, box_with_array)
+            tm.assert_equal(expected, vec + off)
+
+            expected = DatetimeIndex([x - off for x in vec_items]).as_unit(exp_unit)
+            expected = tm.box_expected(expected, box_with_array)
+            tm.assert_equal(expected, vec - off)
+
+            off = DateOffset(**dict(relative_kwargs[: i + 1]))
+
+            expected = DatetimeIndex([x + off for x in vec_items]).as_unit(exp_unit)
+            expected = tm.box_expected(expected, box_with_array)
+            tm.assert_equal(expected, vec + off)
+
+            expected = DatetimeIndex([x - off for x in vec_items]).as_unit(exp_unit)
+            expected = tm.box_expected(expected, box_with_array)
+            tm.assert_equal(expected, vec - off)
+            msg = "(bad|unsupported) operand type for unary"
+            with pytest.raises(TypeError, match=msg):
+                off - vec
+
+    # -------------------------------------------------------------
+    # Non-Tick, Non-RelativeDelta DateOffsets
+
+    # TODO: redundant with test_dt64arr_add_sub_DateOffset?  that includes
+    #  tz-aware cases which this does not
+    @pytest.mark.filterwarnings("ignore::pandas.errors.PerformanceWarning")
+    @pytest.mark.parametrize(
+        "cls_and_kwargs",
+        [
+            "YearBegin",
+            ("YearBegin", {"month": 5}),
+            "YearEnd",
+            ("YearEnd", {"month": 5}),
+            "MonthBegin",
+            "MonthEnd",
+            "SemiMonthEnd",
+            "SemiMonthBegin",
+            "Week",
+            ("Week", {"weekday": 3}),
+            "Week",
+            ("Week", {"weekday": 6}),
+            "BusinessDay",
+            "BDay",
+            "QuarterEnd",
+            "QuarterBegin",
+            "CustomBusinessDay",
+            "CDay",
+            "CBMonthEnd",
+            "CBMonthBegin",
+            "BMonthBegin",
+            "BMonthEnd",
+            "BusinessHour",
+            "BYearBegin",
+            "BYearEnd",
+            "BQuarterBegin",
+            ("LastWeekOfMonth", {"weekday": 2}),
+            (
+                "FY5253Quarter",
+                {
+                    "qtr_with_extra_week": 1,
+                    "startingMonth": 1,
+                    "weekday": 2,
+                    "variation": "nearest",
+                },
+            ),
+            ("FY5253", {"weekday": 0, "startingMonth": 2, "variation": "nearest"}),
+            ("WeekOfMonth", {"weekday": 2, "week": 2}),
+            "Easter",
+            ("DateOffset", {"day": 4}),
+            ("DateOffset", {"month": 5}),
+        ],
+    )
+    @pytest.mark.parametrize("normalize", [True, False])
+    @pytest.mark.parametrize("n", [0, 5])
+    @pytest.mark.parametrize("unit", ["s", "ms", "us", "ns"])
+    @pytest.mark.parametrize("tz", [None, "US/Central"])
+    def test_dt64arr_add_sub_DateOffsets(
+        self, box_with_array, n, normalize, cls_and_kwargs, unit, tz
+    ):
+        # GH#10699
+        # assert vectorized operation matches pointwise operations
+
+        if isinstance(cls_and_kwargs, tuple):
+            # If cls_name param is a tuple, then 2nd entry is kwargs for
+            # the offset constructor
+            cls_name, kwargs = cls_and_kwargs
+        else:
+            cls_name = cls_and_kwargs
+            kwargs = {}
+
+        if n == 0 and cls_name in [
+            "WeekOfMonth",
+            "LastWeekOfMonth",
+            "FY5253Quarter",
+            "FY5253",
+        ]:
+            # passing n = 0 is invalid for these offset classes
+            return
+
+        vec = (
+            DatetimeIndex(
+                [
+                    Timestamp("2000-01-05 00:15:00"),
+                    Timestamp("2000-01-31 00:23:00"),
+                    Timestamp("2000-01-01"),
+                    Timestamp("2000-03-31"),
+                    Timestamp("2000-02-29"),
+                    Timestamp("2000-12-31"),
+                    Timestamp("2000-05-15"),
+                    Timestamp("2001-06-15"),
+                ]
+            )
+            .as_unit(unit)
+            .tz_localize(tz)
+        )
+        vec = tm.box_expected(vec, box_with_array)
+        vec_items = vec.iloc[0] if box_with_array is pd.DataFrame else vec
+
+        offset_cls = getattr(pd.offsets, cls_name)
+        offset = offset_cls(n, normalize=normalize, **kwargs)
+
+        # TODO(GH#55564): as_unit will be unnecessary
+        expected = DatetimeIndex([x + offset for x in vec_items]).as_unit(unit)
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(expected, vec + offset)
+        tm.assert_equal(expected, offset + vec)
+
+        expected = DatetimeIndex([x - offset for x in vec_items]).as_unit(unit)
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(expected, vec - offset)
+
+        expected = DatetimeIndex([offset + x for x in vec_items]).as_unit(unit)
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(expected, offset + vec)
+        msg = "(bad|unsupported) operand type for unary"
+        with pytest.raises(TypeError, match=msg):
+            offset - vec
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            np.array([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)]),
+            np.array([pd.offsets.DateOffset(years=1), pd.offsets.MonthEnd()]),
+            np.array(  # matching offsets
+                [pd.offsets.DateOffset(years=1), pd.offsets.DateOffset(years=1)]
+            ),
+        ],
+    )
+    @pytest.mark.parametrize("op", [operator.add, roperator.radd, operator.sub])
+    def test_dt64arr_add_sub_offset_array(
+        self, tz_naive_fixture, box_with_array, op, other
+    ):
+        # GH#18849
+        # GH#10699 array of offsets
+
+        tz = tz_naive_fixture
+        dti = date_range("2017-01-01", periods=2, tz=tz)
+        dtarr = tm.box_expected(dti, box_with_array)
+
+        expected = DatetimeIndex([op(dti[n], other[n]) for n in range(len(dti))])
+        expected = tm.box_expected(expected, box_with_array).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = op(dtarr, other)
+        tm.assert_equal(res, expected)
+
+        # Same thing but boxing other
+        other = tm.box_expected(other, box_with_array)
+        if box_with_array is pd.array and op is roperator.radd:
+            # We expect a NumpyExtensionArray, not ndarray[object] here
+            expected = pd.array(expected, dtype=object)
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = op(dtarr, other)
+        tm.assert_equal(res, expected)
+
+    @pytest.mark.parametrize(
+        "op, offset, exp, exp_freq",
+        [
+            (
+                "__add__",
+                DateOffset(months=3, days=10),
+                [
+                    Timestamp("2014-04-11"),
+                    Timestamp("2015-04-11"),
+                    Timestamp("2016-04-11"),
+                    Timestamp("2017-04-11"),
+                ],
+                None,
+            ),
+            (
+                "__add__",
+                DateOffset(months=3),
+                [
+                    Timestamp("2014-04-01"),
+                    Timestamp("2015-04-01"),
+                    Timestamp("2016-04-01"),
+                    Timestamp("2017-04-01"),
+                ],
+                "YS-APR",
+            ),
+            (
+                "__sub__",
+                DateOffset(months=3, days=10),
+                [
+                    Timestamp("2013-09-21"),
+                    Timestamp("2014-09-21"),
+                    Timestamp("2015-09-21"),
+                    Timestamp("2016-09-21"),
+                ],
+                None,
+            ),
+            (
+                "__sub__",
+                DateOffset(months=3),
+                [
+                    Timestamp("2013-10-01"),
+                    Timestamp("2014-10-01"),
+                    Timestamp("2015-10-01"),
+                    Timestamp("2016-10-01"),
+                ],
+                "YS-OCT",
+            ),
+        ],
+    )
+    def test_dti_add_sub_nonzero_mth_offset(
+        self, op, offset, exp, exp_freq, tz_aware_fixture, box_with_array
+    ):
+        # GH 26258
+        tz = tz_aware_fixture
+        date = date_range(start="01 Jan 2014", end="01 Jan 2017", freq="YS", tz=tz)
+        date = tm.box_expected(date, box_with_array, False)
+        mth = getattr(date, op)
+        result = mth(offset)
+
+        expected = DatetimeIndex(exp, tz=tz).as_unit("ns")
+        expected = tm.box_expected(expected, box_with_array, False)
+        tm.assert_equal(result, expected)
+
+    def test_dt64arr_series_add_DateOffset_with_milli(self):
+        # GH 57529
+        dti = DatetimeIndex(
+            [
+                "2000-01-01 00:00:00.012345678",
+                "2000-01-31 00:00:00.012345678",
+                "2000-02-29 00:00:00.012345678",
+            ],
+            dtype="datetime64[ns]",
+        )
+        result = dti + DateOffset(milliseconds=4)
+        expected = DatetimeIndex(
+            [
+                "2000-01-01 00:00:00.016345678",
+                "2000-01-31 00:00:00.016345678",
+                "2000-02-29 00:00:00.016345678",
+            ],
+            dtype="datetime64[ns]",
+        )
+        tm.assert_index_equal(result, expected)
+
+        result = dti + DateOffset(days=1, milliseconds=4)
+        expected = DatetimeIndex(
+            [
+                "2000-01-02 00:00:00.016345678",
+                "2000-02-01 00:00:00.016345678",
+                "2000-03-01 00:00:00.016345678",
+            ],
+            dtype="datetime64[ns]",
+        )
+        tm.assert_index_equal(result, expected)
+
+
+class TestDatetime64OverflowHandling:
+    # TODO: box + de-duplicate
+
+    def test_dt64_overflow_masking(self, box_with_array):
+        # GH#25317
+        left = Series([Timestamp("1969-12-31")], dtype="M8[ns]")
+        right = Series([NaT])
+
+        left = tm.box_expected(left, box_with_array)
+        right = tm.box_expected(right, box_with_array)
+
+        expected = TimedeltaIndex([NaT], dtype="m8[ns]")
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = left - right
+        tm.assert_equal(result, expected)
+
+    def test_dt64_series_arith_overflow(self):
+        # GH#12534, fixed by GH#19024
+        dt = Timestamp("1700-01-31")
+        td = Timedelta("20000 Days")
+        dti = date_range("1949-09-30", freq="100YE", periods=4)
+        ser = Series(dti)
+        msg = "Overflow in int64 addition"
+        with pytest.raises(OverflowError, match=msg):
+            ser - dt
+        with pytest.raises(OverflowError, match=msg):
+            dt - ser
+        with pytest.raises(OverflowError, match=msg):
+            ser + td
+        with pytest.raises(OverflowError, match=msg):
+            td + ser
+
+        ser.iloc[-1] = NaT
+        expected = Series(
+            ["2004-10-03", "2104-10-04", "2204-10-04", "NaT"], dtype="datetime64[ns]"
+        )
+        res = ser + td
+        tm.assert_series_equal(res, expected)
+        res = td + ser
+        tm.assert_series_equal(res, expected)
+
+        ser.iloc[1:] = NaT
+        expected = Series(["91279 Days", "NaT", "NaT", "NaT"], dtype="timedelta64[ns]")
+        res = ser - dt
+        tm.assert_series_equal(res, expected)
+        res = dt - ser
+        tm.assert_series_equal(res, -expected)
+
+    def test_datetimeindex_sub_timestamp_overflow(self):
+        dtimax = pd.to_datetime(["2021-12-28 17:19", Timestamp.max]).as_unit("ns")
+        dtimin = pd.to_datetime(["2021-12-28 17:19", Timestamp.min]).as_unit("ns")
+
+        tsneg = Timestamp("1950-01-01").as_unit("ns")
+        ts_neg_variants = [
+            tsneg,
+            tsneg.to_pydatetime(),
+            tsneg.to_datetime64().astype("datetime64[ns]"),
+            tsneg.to_datetime64().astype("datetime64[D]"),
+        ]
+
+        tspos = Timestamp("1980-01-01").as_unit("ns")
+        ts_pos_variants = [
+            tspos,
+            tspos.to_pydatetime(),
+            tspos.to_datetime64().astype("datetime64[ns]"),
+            tspos.to_datetime64().astype("datetime64[D]"),
+        ]
+        msg = "Overflow in int64 addition"
+        for variant in ts_neg_variants:
+            with pytest.raises(OverflowError, match=msg):
+                dtimax - variant
+
+        expected = Timestamp.max._value - tspos._value
+        for variant in ts_pos_variants:
+            res = dtimax - variant
+            assert res[1]._value == expected
+
+        expected = Timestamp.min._value - tsneg._value
+        for variant in ts_neg_variants:
+            res = dtimin - variant
+            assert res[1]._value == expected
+
+        for variant in ts_pos_variants:
+            with pytest.raises(OverflowError, match=msg):
+                dtimin - variant
+
+    def test_datetimeindex_sub_datetimeindex_overflow(self):
+        # GH#22492, GH#22508
+        dtimax = pd.to_datetime(["2021-12-28 17:19", Timestamp.max]).as_unit("ns")
+        dtimin = pd.to_datetime(["2021-12-28 17:19", Timestamp.min]).as_unit("ns")
+
+        ts_neg = pd.to_datetime(["1950-01-01", "1950-01-01"]).as_unit("ns")
+        ts_pos = pd.to_datetime(["1980-01-01", "1980-01-01"]).as_unit("ns")
+
+        # General tests
+        expected = Timestamp.max._value - ts_pos[1]._value
+        result = dtimax - ts_pos
+        assert result[1]._value == expected
+
+        expected = Timestamp.min._value - ts_neg[1]._value
+        result = dtimin - ts_neg
+        assert result[1]._value == expected
+        msg = "Overflow in int64 addition"
+        with pytest.raises(OverflowError, match=msg):
+            dtimax - ts_neg
+
+        with pytest.raises(OverflowError, match=msg):
+            dtimin - ts_pos
+
+        # Edge cases
+        tmin = pd.to_datetime([Timestamp.min])
+        t1 = tmin + Timedelta.max + Timedelta("1us")
+        with pytest.raises(OverflowError, match=msg):
+            t1 - tmin
+
+        tmax = pd.to_datetime([Timestamp.max])
+        t2 = tmax + Timedelta.min - Timedelta("1us")
+        with pytest.raises(OverflowError, match=msg):
+            tmax - t2
+
+
+class TestTimestampSeriesArithmetic:
+    def test_empty_series_add_sub(self, box_with_array):
+        # GH#13844
+        a = Series(dtype="M8[ns]")
+        b = Series(dtype="m8[ns]")
+        a = box_with_array(a)
+        b = box_with_array(b)
+        tm.assert_equal(a, a + b)
+        tm.assert_equal(a, a - b)
+        tm.assert_equal(a, b + a)
+        msg = "cannot subtract"
+        with pytest.raises(TypeError, match=msg):
+            b - a
+
+    def test_operators_datetimelike(self):
+        # ## timedelta64 ###
+        td1 = Series([timedelta(minutes=5, seconds=3)] * 3)
+        td1.iloc[2] = np.nan
+
+        # ## datetime64 ###
+        dt1 = Series(
+            [
+                Timestamp("20111230"),
+                Timestamp("20120101"),
+                Timestamp("20120103"),
+            ]
+        )
+        dt1.iloc[2] = np.nan
+        dt2 = Series(
+            [
+                Timestamp("20111231"),
+                Timestamp("20120102"),
+                Timestamp("20120104"),
+            ]
+        )
+        dt1 - dt2
+        dt2 - dt1
+
+        # datetime64 with timetimedelta
+        dt1 + td1
+        td1 + dt1
+        dt1 - td1
+
+        # timetimedelta with datetime64
+        td1 + dt1
+        dt1 + td1
+
+    def test_dt64ser_sub_datetime_dtype(self, unit):
+        ts = Timestamp(datetime(1993, 1, 7, 13, 30, 00))
+        dt = datetime(1993, 6, 22, 13, 30)
+        ser = Series([ts], dtype=f"M8[{unit}]")
+        result = ser - dt
+
+        # the expected unit is the max of `unit` and the unit imputed to `dt`,
+        #  which is "us"
+        exp_unit = tm.get_finest_unit(unit, "us")
+        assert result.dtype == f"timedelta64[{exp_unit}]"
+
+    # -------------------------------------------------------------
+    # TODO: This next block of tests came from tests.series.test_operators,
+    # needs to be de-duplicated and parametrized over `box` classes
+
+    @pytest.mark.parametrize(
+        "left, right, op_fail",
+        [
+            [
+                [Timestamp("20111230"), Timestamp("20120101"), NaT],
+                [Timestamp("20111231"), Timestamp("20120102"), Timestamp("20120104")],
+                ["__sub__", "__rsub__"],
+            ],
+            [
+                [Timestamp("20111230"), Timestamp("20120101"), NaT],
+                [timedelta(minutes=5, seconds=3), timedelta(minutes=5, seconds=3), NaT],
+                ["__add__", "__radd__", "__sub__"],
+            ],
+            [
+                [
+                    Timestamp("20111230", tz="US/Eastern"),
+                    Timestamp("20111230", tz="US/Eastern"),
+                    NaT,
+                ],
+                [timedelta(minutes=5, seconds=3), NaT, timedelta(minutes=5, seconds=3)],
+                ["__add__", "__radd__", "__sub__"],
+            ],
+        ],
+    )
+    def test_operators_datetimelike_invalid(
+        self, left, right, op_fail, all_arithmetic_operators
+    ):
+        # these are all TypeError ops
+        op_str = all_arithmetic_operators
+        arg1 = Series(left)
+        arg2 = Series(right)
+        # check that we are getting a TypeError
+        # with 'operate' (from core/ops.py) for the ops that are not
+        # defined
+        op = getattr(arg1, op_str, None)
+        # Previously, _validate_for_numeric_binop in core/indexes/base.py
+        # did this for us.
+        if op_str not in op_fail:
+            with pytest.raises(
+                TypeError, match="operate|[cC]annot|unsupported operand"
+            ):
+                op(arg2)
+        else:
+            # Smoke test
+            op(arg2)
+
+    def test_sub_single_tz(self, unit):
+        # GH#12290
+        s1 = Series([Timestamp("2016-02-10", tz="America/Sao_Paulo")]).dt.as_unit(unit)
+        s2 = Series([Timestamp("2016-02-08", tz="America/Sao_Paulo")]).dt.as_unit(unit)
+        result = s1 - s2
+        expected = Series([Timedelta("2days")]).dt.as_unit(unit)
+        tm.assert_series_equal(result, expected)
+        result = s2 - s1
+        expected = Series([Timedelta("-2days")]).dt.as_unit(unit)
+        tm.assert_series_equal(result, expected)
+
+    def test_dt64tz_series_sub_dtitz(self):
+        # GH#19071 subtracting tzaware DatetimeIndex from tzaware Series
+        # (with same tz) raises, fixed by #19024
+        dti = date_range("1999-09-30", periods=10, tz="US/Pacific")
+        ser = Series(dti)
+        expected = Series(TimedeltaIndex(["0days"] * 10))
+
+        res = dti - ser
+        tm.assert_series_equal(res, expected)
+        res = ser - dti
+        tm.assert_series_equal(res, expected)
+
+    def test_sub_datetime_compat(self, unit):
+        # see GH#14088
+        ser = Series([datetime(2016, 8, 23, 12, tzinfo=pytz.utc), NaT]).dt.as_unit(unit)
+        dt = datetime(2016, 8, 22, 12, tzinfo=pytz.utc)
+        # The datetime object has "us" so we upcast lower units
+        exp_unit = tm.get_finest_unit(unit, "us")
+        exp = Series([Timedelta("1 days"), NaT]).dt.as_unit(exp_unit)
+        result = ser - dt
+        tm.assert_series_equal(result, exp)
+        result2 = ser - Timestamp(dt)
+        tm.assert_series_equal(result2, exp)
+
+    def test_dt64_series_add_mixed_tick_DateOffset(self):
+        # GH#4532
+        # operate with pd.offsets
+        s = Series([Timestamp("20130101 9:01"), Timestamp("20130101 9:02")])
+
+        result = s + pd.offsets.Milli(5)
+        result2 = pd.offsets.Milli(5) + s
+        expected = Series(
+            [Timestamp("20130101 9:01:00.005"), Timestamp("20130101 9:02:00.005")]
+        )
+        tm.assert_series_equal(result, expected)
+        tm.assert_series_equal(result2, expected)
+
+        result = s + pd.offsets.Minute(5) + pd.offsets.Milli(5)
+        expected = Series(
+            [Timestamp("20130101 9:06:00.005"), Timestamp("20130101 9:07:00.005")]
+        )
+        tm.assert_series_equal(result, expected)
+
+    def test_datetime64_ops_nat(self, unit):
+        # GH#11349
+        datetime_series = Series([NaT, Timestamp("19900315")]).dt.as_unit(unit)
+        nat_series_dtype_timestamp = Series([NaT, NaT], dtype=f"datetime64[{unit}]")
+        single_nat_dtype_datetime = Series([NaT], dtype=f"datetime64[{unit}]")
+
+        # subtraction
+        tm.assert_series_equal(-NaT + datetime_series, nat_series_dtype_timestamp)
+        msg = "bad operand type for unary -: 'DatetimeArray'"
+        with pytest.raises(TypeError, match=msg):
+            -single_nat_dtype_datetime + datetime_series
+
+        tm.assert_series_equal(
+            -NaT + nat_series_dtype_timestamp, nat_series_dtype_timestamp
+        )
+        with pytest.raises(TypeError, match=msg):
+            -single_nat_dtype_datetime + nat_series_dtype_timestamp
+
+        # addition
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp + NaT, nat_series_dtype_timestamp
+        )
+        tm.assert_series_equal(
+            NaT + nat_series_dtype_timestamp, nat_series_dtype_timestamp
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp + NaT, nat_series_dtype_timestamp
+        )
+        tm.assert_series_equal(
+            NaT + nat_series_dtype_timestamp, nat_series_dtype_timestamp
+        )
+
+    # -------------------------------------------------------------
+    # Timezone-Centric Tests
+
+    def test_operators_datetimelike_with_timezones(self):
+        tz = "US/Eastern"
+        dt1 = Series(date_range("2000-01-01 09:00:00", periods=5, tz=tz), name="foo")
+        dt2 = dt1.copy()
+        dt2.iloc[2] = np.nan
+
+        td1 = Series(pd.timedelta_range("1 days 1 min", periods=5, freq="h"))
+        td2 = td1.copy()
+        td2.iloc[1] = np.nan
+        assert td2._values.freq is None
+
+        result = dt1 + td1[0]
+        exp = (dt1.dt.tz_localize(None) + td1[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = dt2 + td2[0]
+        exp = (dt2.dt.tz_localize(None) + td2[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        # odd numpy behavior with scalar timedeltas
+        result = td1[0] + dt1
+        exp = (dt1.dt.tz_localize(None) + td1[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = td2[0] + dt2
+        exp = (dt2.dt.tz_localize(None) + td2[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = dt1 - td1[0]
+        exp = (dt1.dt.tz_localize(None) - td1[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+        msg = "(bad|unsupported) operand type for unary"
+        with pytest.raises(TypeError, match=msg):
+            td1[0] - dt1
+
+        result = dt2 - td2[0]
+        exp = (dt2.dt.tz_localize(None) - td2[0]).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+        with pytest.raises(TypeError, match=msg):
+            td2[0] - dt2
+
+        result = dt1 + td1
+        exp = (dt1.dt.tz_localize(None) + td1).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = dt2 + td2
+        exp = (dt2.dt.tz_localize(None) + td2).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = dt1 - td1
+        exp = (dt1.dt.tz_localize(None) - td1).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+
+        result = dt2 - td2
+        exp = (dt2.dt.tz_localize(None) - td2).dt.tz_localize(tz)
+        tm.assert_series_equal(result, exp)
+        msg = "cannot (add|subtract)"
+        with pytest.raises(TypeError, match=msg):
+            td1 - dt1
+        with pytest.raises(TypeError, match=msg):
+            td2 - dt2
+
+
+class TestDatetimeIndexArithmetic:
+    # -------------------------------------------------------------
+    # Binary operations DatetimeIndex and TimedeltaIndex/array
+
+    def test_dti_add_tdi(self, tz_naive_fixture):
+        # GH#17558
+        tz = tz_naive_fixture
+        dti = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10)
+        tdi = pd.timedelta_range("0 days", periods=10)
+        expected = date_range("2017-01-01", periods=10, tz=tz)
+        expected = expected._with_freq(None)
+
+        # add with TimedeltaIndex
+        result = dti + tdi
+        tm.assert_index_equal(result, expected)
+
+        result = tdi + dti
+        tm.assert_index_equal(result, expected)
+
+        # add with timedelta64 array
+        result = dti + tdi.values
+        tm.assert_index_equal(result, expected)
+
+        result = tdi.values + dti
+        tm.assert_index_equal(result, expected)
+
+    def test_dti_iadd_tdi(self, tz_naive_fixture):
+        # GH#17558
+        tz = tz_naive_fixture
+        dti = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10)
+        tdi = pd.timedelta_range("0 days", periods=10)
+        expected = date_range("2017-01-01", periods=10, tz=tz)
+        expected = expected._with_freq(None)
+
+        # iadd with TimedeltaIndex
+        result = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10)
+        result += tdi
+        tm.assert_index_equal(result, expected)
+
+        result = pd.timedelta_range("0 days", periods=10)
+        result += dti
+        tm.assert_index_equal(result, expected)
+
+        # iadd with timedelta64 array
+        result = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10)
+        result += tdi.values
+        tm.assert_index_equal(result, expected)
+
+        result = pd.timedelta_range("0 days", periods=10)
+        result += dti
+        tm.assert_index_equal(result, expected)
+
+    def test_dti_sub_tdi(self, tz_naive_fixture):
+        # GH#17558
+        tz = tz_naive_fixture
+        dti = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10)
+        tdi = pd.timedelta_range("0 days", periods=10)
+        expected = date_range("2017-01-01", periods=10, tz=tz, freq="-1D")
+        expected = expected._with_freq(None)
+
+        # sub with TimedeltaIndex
+        result = dti - tdi
+        tm.assert_index_equal(result, expected)
+
+        msg = "cannot subtract .*TimedeltaArray"
+        with pytest.raises(TypeError, match=msg):
+            tdi - dti
+
+        # sub with timedelta64 array
+        result = dti - tdi.values
+        tm.assert_index_equal(result, expected)
+
+        msg = "cannot subtract a datelike from a TimedeltaArray"
+        with pytest.raises(TypeError, match=msg):
+            tdi.values - dti
+
+    def test_dti_isub_tdi(self, tz_naive_fixture, unit):
+        # GH#17558
+        tz = tz_naive_fixture
+        dti = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10).as_unit(unit)
+        tdi = pd.timedelta_range("0 days", periods=10, unit=unit)
+        expected = date_range("2017-01-01", periods=10, tz=tz, freq="-1D", unit=unit)
+        expected = expected._with_freq(None)
+
+        # isub with TimedeltaIndex
+        result = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10).as_unit(unit)
+        result -= tdi
+        tm.assert_index_equal(result, expected)
+
+        # DTA.__isub__ GH#43904
+        dta = dti._data.copy()
+        dta -= tdi
+        tm.assert_datetime_array_equal(dta, expected._data)
+
+        out = dti._data.copy()
+        np.subtract(out, tdi, out=out)
+        tm.assert_datetime_array_equal(out, expected._data)
+
+        msg = "cannot subtract a datelike from a TimedeltaArray"
+        with pytest.raises(TypeError, match=msg):
+            tdi -= dti
+
+        # isub with timedelta64 array
+        result = DatetimeIndex([Timestamp("2017-01-01", tz=tz)] * 10).as_unit(unit)
+        result -= tdi.values
+        tm.assert_index_equal(result, expected)
+
+        with pytest.raises(TypeError, match=msg):
+            tdi.values -= dti
+
+        with pytest.raises(TypeError, match=msg):
+            tdi._values -= dti
+
+    # -------------------------------------------------------------
+    # Binary Operations DatetimeIndex and datetime-like
+    # TODO: A couple other tests belong in this section.  Move them in
+    # A PR where there isn't already a giant diff.
+
+    # -------------------------------------------------------------
+
+    def test_dta_add_sub_index(self, tz_naive_fixture):
+        # Check that DatetimeArray defers to Index classes
+        dti = date_range("20130101", periods=3, tz=tz_naive_fixture)
+        dta = dti.array
+        result = dta - dti
+        expected = dti - dti
+        tm.assert_index_equal(result, expected)
+
+        tdi = result
+        result = dta + tdi
+        expected = dti + tdi
+        tm.assert_index_equal(result, expected)
+
+        result = dta - tdi
+        expected = dti - tdi
+        tm.assert_index_equal(result, expected)
+
+    def test_sub_dti_dti(self, unit):
+        # previously performed setop (deprecated in 0.16.0), now changed to
+        # return subtraction -> TimeDeltaIndex (GH ...)
+
+        dti = date_range("20130101", periods=3, unit=unit)
+        dti_tz = date_range("20130101", periods=3, unit=unit).tz_localize("US/Eastern")
+        expected = TimedeltaIndex([0, 0, 0]).as_unit(unit)
+
+        result = dti - dti
+        tm.assert_index_equal(result, expected)
+
+        result = dti_tz - dti_tz
+        tm.assert_index_equal(result, expected)
+        msg = "Cannot subtract tz-naive and tz-aware datetime-like objects"
+        with pytest.raises(TypeError, match=msg):
+            dti_tz - dti
+
+        with pytest.raises(TypeError, match=msg):
+            dti - dti_tz
+
+        # isub
+        dti -= dti
+        tm.assert_index_equal(dti, expected)
+
+        # different length raises ValueError
+        dti1 = date_range("20130101", periods=3, unit=unit)
+        dti2 = date_range("20130101", periods=4, unit=unit)
+        msg = "cannot add indices of unequal length"
+        with pytest.raises(ValueError, match=msg):
+            dti1 - dti2
+
+        # NaN propagation
+        dti1 = DatetimeIndex(["2012-01-01", np.nan, "2012-01-03"]).as_unit(unit)
+        dti2 = DatetimeIndex(["2012-01-02", "2012-01-03", np.nan]).as_unit(unit)
+        expected = TimedeltaIndex(["1 days", np.nan, np.nan]).as_unit(unit)
+        result = dti2 - dti1
+        tm.assert_index_equal(result, expected)
+
+    # -------------------------------------------------------------------
+    # TODO: Most of this block is moved from series or frame tests, needs
+    # cleanup, box-parametrization, and de-duplication
+
+    @pytest.mark.parametrize("op", [operator.add, operator.sub])
+    def test_timedelta64_equal_timedelta_supported_ops(self, op, box_with_array):
+        ser = Series(
+            [
+                Timestamp("20130301"),
+                Timestamp("20130228 23:00:00"),
+                Timestamp("20130228 22:00:00"),
+                Timestamp("20130228 21:00:00"),
+            ]
+        )
+        obj = box_with_array(ser)
+
+        intervals = ["D", "h", "m", "s", "us"]
+
+        def timedelta64(*args):
+            # see casting notes in NumPy gh-12927
+            return np.sum(list(starmap(np.timedelta64, zip(args, intervals))))
+
+        for d, h, m, s, us in product(*([range(2)] * 5)):
+            nptd = timedelta64(d, h, m, s, us)
+            pytd = timedelta(days=d, hours=h, minutes=m, seconds=s, microseconds=us)
+            lhs = op(obj, nptd)
+            rhs = op(obj, pytd)
+
+            tm.assert_equal(lhs, rhs)
+
+    def test_ops_nat_mixed_datetime64_timedelta64(self):
+        # GH#11349
+        timedelta_series = Series([NaT, Timedelta("1s")])
+        datetime_series = Series([NaT, Timestamp("19900315")])
+        nat_series_dtype_timedelta = Series([NaT, NaT], dtype="timedelta64[ns]")
+        nat_series_dtype_timestamp = Series([NaT, NaT], dtype="datetime64[ns]")
+        single_nat_dtype_datetime = Series([NaT], dtype="datetime64[ns]")
+        single_nat_dtype_timedelta = Series([NaT], dtype="timedelta64[ns]")
+
+        # subtraction
+        tm.assert_series_equal(
+            datetime_series - single_nat_dtype_datetime, nat_series_dtype_timedelta
+        )
+
+        tm.assert_series_equal(
+            datetime_series - single_nat_dtype_timedelta, nat_series_dtype_timestamp
+        )
+        tm.assert_series_equal(
+            -single_nat_dtype_timedelta + datetime_series, nat_series_dtype_timestamp
+        )
+
+        # without a Series wrapping the NaT, it is ambiguous
+        # whether it is a datetime64 or timedelta64
+        # defaults to interpreting it as timedelta64
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp - single_nat_dtype_datetime,
+            nat_series_dtype_timedelta,
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp - single_nat_dtype_timedelta,
+            nat_series_dtype_timestamp,
+        )
+        tm.assert_series_equal(
+            -single_nat_dtype_timedelta + nat_series_dtype_timestamp,
+            nat_series_dtype_timestamp,
+        )
+        msg = "cannot subtract a datelike"
+        with pytest.raises(TypeError, match=msg):
+            timedelta_series - single_nat_dtype_datetime
+
+        # addition
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp + single_nat_dtype_timedelta,
+            nat_series_dtype_timestamp,
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_timedelta + nat_series_dtype_timestamp,
+            nat_series_dtype_timestamp,
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timestamp + single_nat_dtype_timedelta,
+            nat_series_dtype_timestamp,
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_timedelta + nat_series_dtype_timestamp,
+            nat_series_dtype_timestamp,
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta + single_nat_dtype_datetime,
+            nat_series_dtype_timestamp,
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_datetime + nat_series_dtype_timedelta,
+            nat_series_dtype_timestamp,
+        )
+
+    def test_ufunc_coercions(self, unit):
+        idx = date_range("2011-01-01", periods=3, freq="2D", name="x", unit=unit)
+
+        delta = np.timedelta64(1, "D")
+        exp = date_range("2011-01-02", periods=3, freq="2D", name="x", unit=unit)
+        for result in [idx + delta, np.add(idx, delta)]:
+            assert isinstance(result, DatetimeIndex)
+            tm.assert_index_equal(result, exp)
+            assert result.freq == "2D"
+
+        exp = date_range("2010-12-31", periods=3, freq="2D", name="x", unit=unit)
+
+        for result in [idx - delta, np.subtract(idx, delta)]:
+            assert isinstance(result, DatetimeIndex)
+            tm.assert_index_equal(result, exp)
+            assert result.freq == "2D"
+
+        # When adding/subtracting an ndarray (which has no .freq), the result
+        #  does not infer freq
+        idx = idx._with_freq(None)
+        delta = np.array(
+            [np.timedelta64(1, "D"), np.timedelta64(2, "D"), np.timedelta64(3, "D")]
+        )
+        exp = DatetimeIndex(
+            ["2011-01-02", "2011-01-05", "2011-01-08"], name="x"
+        ).as_unit(unit)
+
+        for result in [idx + delta, np.add(idx, delta)]:
+            tm.assert_index_equal(result, exp)
+            assert result.freq == exp.freq
+
+        exp = DatetimeIndex(
+            ["2010-12-31", "2011-01-01", "2011-01-02"], name="x"
+        ).as_unit(unit)
+        for result in [idx - delta, np.subtract(idx, delta)]:
+            assert isinstance(result, DatetimeIndex)
+            tm.assert_index_equal(result, exp)
+            assert result.freq == exp.freq
+
+    def test_dti_add_series(self, tz_naive_fixture, names):
+        # GH#13905
+        tz = tz_naive_fixture
+        index = DatetimeIndex(
+            ["2016-06-28 05:30", "2016-06-28 05:31"], tz=tz, name=names[0]
+        ).as_unit("ns")
+        ser = Series([Timedelta(seconds=5)] * 2, index=index, name=names[1])
+        expected = Series(index + Timedelta(seconds=5), index=index, name=names[2])
+
+        # passing name arg isn't enough when names[2] is None
+        expected.name = names[2]
+        assert expected.dtype == index.dtype
+        result = ser + index
+        tm.assert_series_equal(result, expected)
+        result2 = index + ser
+        tm.assert_series_equal(result2, expected)
+
+        expected = index + Timedelta(seconds=5)
+        result3 = ser.values + index
+        tm.assert_index_equal(result3, expected)
+        result4 = index + ser.values
+        tm.assert_index_equal(result4, expected)
+
+    @pytest.mark.parametrize("op", [operator.add, roperator.radd, operator.sub])
+    def test_dti_addsub_offset_arraylike(
+        self, tz_naive_fixture, names, op, index_or_series
+    ):
+        # GH#18849, GH#19744
+        other_box = index_or_series
+
+        tz = tz_naive_fixture
+        dti = date_range("2017-01-01", periods=2, tz=tz, name=names[0])
+        other = other_box([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)], name=names[1])
+
+        xbox = get_upcast_box(dti, other)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = op(dti, other)
+
+        expected = DatetimeIndex(
+            [op(dti[n], other[n]) for n in range(len(dti))], name=names[2], freq="infer"
+        )
+        expected = tm.box_expected(expected, xbox).astype(object)
+        tm.assert_equal(res, expected)
+
+    @pytest.mark.parametrize("other_box", [pd.Index, np.array])
+    def test_dti_addsub_object_arraylike(
+        self, tz_naive_fixture, box_with_array, other_box
+    ):
+        tz = tz_naive_fixture
+
+        dti = date_range("2017-01-01", periods=2, tz=tz)
+        dtarr = tm.box_expected(dti, box_with_array)
+        other = other_box([pd.offsets.MonthEnd(), Timedelta(days=4)])
+        xbox = get_upcast_box(dtarr, other)
+
+        expected = DatetimeIndex(["2017-01-31", "2017-01-06"], tz=tz_naive_fixture)
+        expected = tm.box_expected(expected, xbox).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = dtarr + other
+        tm.assert_equal(result, expected)
+
+        expected = DatetimeIndex(["2016-12-31", "2016-12-29"], tz=tz_naive_fixture)
+        expected = tm.box_expected(expected, xbox).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = dtarr - other
+        tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize("years", [-1, 0, 1])
+@pytest.mark.parametrize("months", [-2, 0, 2])
+@pytest.mark.parametrize("unit", ["s", "ms", "us", "ns"])
+def test_shift_months(years, months, unit):
+    dti = DatetimeIndex(
+        [
+            Timestamp("2000-01-05 00:15:00"),
+            Timestamp("2000-01-31 00:23:00"),
+            Timestamp("2000-01-01"),
+            Timestamp("2000-02-29"),
+            Timestamp("2000-12-31"),
+        ]
+    ).as_unit(unit)
+    shifted = shift_months(dti.asi8, years * 12 + months, reso=dti._data._creso)
+    shifted_dt64 = shifted.view(f"M8[{dti.unit}]")
+    actual = DatetimeIndex(shifted_dt64)
+
+    raw = [x + pd.offsets.DateOffset(years=years, months=months) for x in dti]
+    expected = DatetimeIndex(raw).as_unit(dti.unit)
+    tm.assert_index_equal(actual, expected)
+
+
+def test_dt64arr_addsub_object_dtype_2d():
+    # block-wise DataFrame operations will require operating on 2D
+    #  DatetimeArray/TimedeltaArray, so check that specifically.
+    dti = date_range("1994-02-13", freq="2W", periods=4)
+    dta = dti._data.reshape((4, 1))
+
+    other = np.array([[pd.offsets.Day(n)] for n in range(4)])
+    assert other.shape == dta.shape
+
+    with tm.assert_produces_warning(PerformanceWarning):
+        result = dta + other
+    with tm.assert_produces_warning(PerformanceWarning):
+        expected = (dta[:, 0] + other[:, 0]).reshape(-1, 1)
+
+    tm.assert_numpy_array_equal(result, expected)
+
+    with tm.assert_produces_warning(PerformanceWarning):
+        # Case where we expect to get a TimedeltaArray back
+        result2 = dta - dta.astype(object)
+
+    assert result2.shape == (4, 1)
+    assert all(td._value == 0 for td in result2.ravel())
+
+
+def test_non_nano_dt64_addsub_np_nat_scalars():
+    # GH 52295
+    ser = Series([1233242342344, 232432434324, 332434242344], dtype="datetime64[ms]")
+    result = ser - np.datetime64("nat", "ms")
+    expected = Series([NaT] * 3, dtype="timedelta64[ms]")
+    tm.assert_series_equal(result, expected)
+
+    result = ser + np.timedelta64("nat", "ms")
+    expected = Series([NaT] * 3, dtype="datetime64[ms]")
+    tm.assert_series_equal(result, expected)
+
+
+def test_non_nano_dt64_addsub_np_nat_scalars_unitless():
+    # GH 52295
+    # TODO: Can we default to the ser unit?
+    ser = Series([1233242342344, 232432434324, 332434242344], dtype="datetime64[ms]")
+    result = ser - np.datetime64("nat")
+    expected = Series([NaT] * 3, dtype="timedelta64[ns]")
+    tm.assert_series_equal(result, expected)
+
+    result = ser + np.timedelta64("nat")
+    expected = Series([NaT] * 3, dtype="datetime64[ns]")
+    tm.assert_series_equal(result, expected)
+
+
+def test_non_nano_dt64_addsub_np_nat_scalars_unsupported_unit():
+    # GH 52295
+    ser = Series([12332, 23243, 33243], dtype="datetime64[s]")
+    result = ser - np.datetime64("nat", "D")
+    expected = Series([NaT] * 3, dtype="timedelta64[s]")
+    tm.assert_series_equal(result, expected)
+
+    result = ser + np.timedelta64("nat", "D")
+    expected = Series([NaT] * 3, dtype="datetime64[s]")
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_interval.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_interval.py
new file mode 100644
index 0000000000000000000000000000000000000000..0e316cf419cb0d3be489f474a9c6d889e668e7c9
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_interval.py
@@ -0,0 +1,306 @@
+import operator
+
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.common import is_list_like
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    Index,
+    Interval,
+    IntervalIndex,
+    Period,
+    Series,
+    Timedelta,
+    Timestamp,
+    date_range,
+    period_range,
+    timedelta_range,
+)
+import pandas._testing as tm
+from pandas.core.arrays import (
+    BooleanArray,
+    IntervalArray,
+)
+from pandas.tests.arithmetic.common import get_upcast_box
+
+
+@pytest.fixture(
+    params=[
+        (Index([0, 2, 4, 4]), Index([1, 3, 5, 8])),
+        (Index([0.0, 1.0, 2.0, np.nan]), Index([1.0, 2.0, 3.0, np.nan])),
+        (
+            timedelta_range("0 days", periods=3).insert(3, pd.NaT),
+            timedelta_range("1 day", periods=3).insert(3, pd.NaT),
+        ),
+        (
+            date_range("20170101", periods=3).insert(3, pd.NaT),
+            date_range("20170102", periods=3).insert(3, pd.NaT),
+        ),
+        (
+            date_range("20170101", periods=3, tz="US/Eastern").insert(3, pd.NaT),
+            date_range("20170102", periods=3, tz="US/Eastern").insert(3, pd.NaT),
+        ),
+    ],
+    ids=lambda x: str(x[0].dtype),
+)
+def left_right_dtypes(request):
+    """
+    Fixture for building an IntervalArray from various dtypes
+    """
+    return request.param
+
+
+@pytest.fixture
+def interval_array(left_right_dtypes):
+    """
+    Fixture to generate an IntervalArray of various dtypes containing NA if possible
+    """
+    left, right = left_right_dtypes
+    return IntervalArray.from_arrays(left, right)
+
+
+def create_categorical_intervals(left, right, closed="right"):
+    return Categorical(IntervalIndex.from_arrays(left, right, closed))
+
+
+def create_series_intervals(left, right, closed="right"):
+    return Series(IntervalArray.from_arrays(left, right, closed))
+
+
+def create_series_categorical_intervals(left, right, closed="right"):
+    return Series(Categorical(IntervalIndex.from_arrays(left, right, closed)))
+
+
+class TestComparison:
+    @pytest.fixture(params=[operator.eq, operator.ne])
+    def op(self, request):
+        return request.param
+
+    @pytest.fixture(
+        params=[
+            IntervalArray.from_arrays,
+            IntervalIndex.from_arrays,
+            create_categorical_intervals,
+            create_series_intervals,
+            create_series_categorical_intervals,
+        ],
+        ids=[
+            "IntervalArray",
+            "IntervalIndex",
+            "Categorical[Interval]",
+            "Series[Interval]",
+            "Series[Categorical[Interval]]",
+        ],
+    )
+    def interval_constructor(self, request):
+        """
+        Fixture for all pandas native interval constructors.
+        To be used as the LHS of IntervalArray comparisons.
+        """
+        return request.param
+
+    def elementwise_comparison(self, op, interval_array, other):
+        """
+        Helper that performs elementwise comparisons between `array` and `other`
+        """
+        other = other if is_list_like(other) else [other] * len(interval_array)
+        expected = np.array([op(x, y) for x, y in zip(interval_array, other)])
+        if isinstance(other, Series):
+            return Series(expected, index=other.index)
+        return expected
+
+    def test_compare_scalar_interval(self, op, interval_array):
+        # matches first interval
+        other = interval_array[0]
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+        # matches on a single endpoint but not both
+        other = Interval(interval_array.left[0], interval_array.right[1])
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_compare_scalar_interval_mixed_closed(self, op, closed, other_closed):
+        interval_array = IntervalArray.from_arrays(range(2), range(1, 3), closed=closed)
+        other = Interval(0, 1, closed=other_closed)
+
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_compare_scalar_na(self, op, interval_array, nulls_fixture, box_with_array):
+        box = box_with_array
+        obj = tm.box_expected(interval_array, box)
+        result = op(obj, nulls_fixture)
+
+        if nulls_fixture is pd.NA:
+            # GH#31882
+            exp = np.ones(interval_array.shape, dtype=bool)
+            expected = BooleanArray(exp, exp)
+        else:
+            expected = self.elementwise_comparison(op, interval_array, nulls_fixture)
+
+        if not (box is Index and nulls_fixture is pd.NA):
+            # don't cast expected from BooleanArray to ndarray[object]
+            xbox = get_upcast_box(obj, nulls_fixture, True)
+            expected = tm.box_expected(expected, xbox)
+
+        tm.assert_equal(result, expected)
+
+        rev = op(nulls_fixture, obj)
+        tm.assert_equal(rev, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            0,
+            1.0,
+            True,
+            "foo",
+            Timestamp("2017-01-01"),
+            Timestamp("2017-01-01", tz="US/Eastern"),
+            Timedelta("0 days"),
+            Period("2017-01-01", "D"),
+        ],
+    )
+    def test_compare_scalar_other(self, op, interval_array, other):
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_compare_list_like_interval(self, op, interval_array, interval_constructor):
+        # same endpoints
+        other = interval_constructor(interval_array.left, interval_array.right)
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_equal(result, expected)
+
+        # different endpoints
+        other = interval_constructor(
+            interval_array.left[::-1], interval_array.right[::-1]
+        )
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_equal(result, expected)
+
+        # all nan endpoints
+        other = interval_constructor([np.nan] * 4, [np.nan] * 4)
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_equal(result, expected)
+
+    def test_compare_list_like_interval_mixed_closed(
+        self, op, interval_constructor, closed, other_closed
+    ):
+        interval_array = IntervalArray.from_arrays(range(2), range(1, 3), closed=closed)
+        other = interval_constructor(range(2), range(1, 3), closed=other_closed)
+
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            (
+                Interval(0, 1),
+                Interval(Timedelta("1 day"), Timedelta("2 days")),
+                Interval(4, 5, "both"),
+                Interval(10, 20, "neither"),
+            ),
+            (0, 1.5, Timestamp("20170103"), np.nan),
+            (
+                Timestamp("20170102", tz="US/Eastern"),
+                Timedelta("2 days"),
+                "baz",
+                pd.NaT,
+            ),
+        ],
+    )
+    def test_compare_list_like_object(self, op, interval_array, other):
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_compare_list_like_nan(self, op, interval_array, nulls_fixture):
+        other = [nulls_fixture] * 4
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            np.arange(4, dtype="int64"),
+            np.arange(4, dtype="float64"),
+            date_range("2017-01-01", periods=4),
+            date_range("2017-01-01", periods=4, tz="US/Eastern"),
+            timedelta_range("0 days", periods=4),
+            period_range("2017-01-01", periods=4, freq="D"),
+            Categorical(list("abab")),
+            Categorical(date_range("2017-01-01", periods=4)),
+            pd.array(list("abcd")),
+            pd.array(["foo", 3.14, None, object()], dtype=object),
+        ],
+        ids=lambda x: str(x.dtype),
+    )
+    def test_compare_list_like_other(self, op, interval_array, other):
+        result = op(interval_array, other)
+        expected = self.elementwise_comparison(op, interval_array, other)
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize("length", [1, 3, 5])
+    @pytest.mark.parametrize("other_constructor", [IntervalArray, list])
+    def test_compare_length_mismatch_errors(self, op, other_constructor, length):
+        interval_array = IntervalArray.from_arrays(range(4), range(1, 5))
+        other = other_constructor([Interval(0, 1)] * length)
+        with pytest.raises(ValueError, match="Lengths must match to compare"):
+            op(interval_array, other)
+
+    @pytest.mark.parametrize(
+        "constructor, expected_type, assert_func",
+        [
+            (IntervalIndex, np.array, tm.assert_numpy_array_equal),
+            (Series, Series, tm.assert_series_equal),
+        ],
+    )
+    def test_index_series_compat(self, op, constructor, expected_type, assert_func):
+        # IntervalIndex/Series that rely on IntervalArray for comparisons
+        breaks = range(4)
+        index = constructor(IntervalIndex.from_breaks(breaks))
+
+        # scalar comparisons
+        other = index[0]
+        result = op(index, other)
+        expected = expected_type(self.elementwise_comparison(op, index, other))
+        assert_func(result, expected)
+
+        other = breaks[0]
+        result = op(index, other)
+        expected = expected_type(self.elementwise_comparison(op, index, other))
+        assert_func(result, expected)
+
+        # list-like comparisons
+        other = IntervalArray.from_breaks(breaks)
+        result = op(index, other)
+        expected = expected_type(self.elementwise_comparison(op, index, other))
+        assert_func(result, expected)
+
+        other = [index[0], breaks[0], "foo"]
+        result = op(index, other)
+        expected = expected_type(self.elementwise_comparison(op, index, other))
+        assert_func(result, expected)
+
+    @pytest.mark.parametrize("scalars", ["a", False, 1, 1.0, None])
+    def test_comparison_operations(self, scalars):
+        # GH #28981
+        expected = Series([False, False])
+        s = Series([Interval(0, 1), Interval(1, 2)], dtype="interval")
+        result = s == scalars
+        tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_numeric.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_numeric.py
new file mode 100644
index 0000000000000000000000000000000000000000..d8c1786b6b422c32a0f396b43f51d75b2b3ffe25
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_numeric.py
@@ -0,0 +1,1567 @@
+# Arithmetic tests for DataFrame/Series/Index/Array classes that should
+# behave identically.
+# Specifically for numeric dtypes
+from __future__ import annotations
+
+from collections import abc
+from datetime import timedelta
+from decimal import Decimal
+import operator
+
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    Index,
+    RangeIndex,
+    Series,
+    Timedelta,
+    TimedeltaIndex,
+    array,
+    date_range,
+)
+import pandas._testing as tm
+from pandas.core import ops
+from pandas.core.computation import expressions as expr
+from pandas.tests.arithmetic.common import (
+    assert_invalid_addsub_type,
+    assert_invalid_comparison,
+)
+
+
+@pytest.fixture(autouse=True, params=[0, 1000000], ids=["numexpr", "python"])
+def switch_numexpr_min_elements(request, monkeypatch):
+    with monkeypatch.context() as m:
+        m.setattr(expr, "_MIN_ELEMENTS", request.param)
+        yield request.param
+
+
+@pytest.fixture(params=[Index, Series, tm.to_array])
+def box_pandas_1d_array(request):
+    """
+    Fixture to test behavior for Index, Series and tm.to_array classes
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        # TODO: add more  dtypes here
+        Index(np.arange(5, dtype="float64")),
+        Index(np.arange(5, dtype="int64")),
+        Index(np.arange(5, dtype="uint64")),
+        RangeIndex(5),
+    ],
+    ids=lambda x: type(x).__name__,
+)
+def numeric_idx(request):
+    """
+    Several types of numeric-dtypes Index objects
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[Index, Series, tm.to_array, np.array, list], ids=lambda x: x.__name__
+)
+def box_1d_array(request):
+    """
+    Fixture to test behavior for Index, Series, tm.to_array, numpy Array and list
+    classes
+    """
+    return request.param
+
+
+def adjust_negative_zero(zero, expected):
+    """
+    Helper to adjust the expected result if we are dividing by -0.0
+    as opposed to 0.0
+    """
+    if np.signbit(np.array(zero)).any():
+        # All entries in the `zero` fixture should be either
+        #  all-negative or no-negative.
+        assert np.signbit(np.array(zero)).all()
+
+        expected *= -1
+
+    return expected
+
+
+def compare_op(series, other, op):
+    left = np.abs(series) if op in (ops.rpow, operator.pow) else series
+    right = np.abs(other) if op in (ops.rpow, operator.pow) else other
+
+    cython_or_numpy = op(left, right)
+    python = left.combine(right, op)
+    if isinstance(other, Series) and not other.index.equals(series.index):
+        python.index = python.index._with_freq(None)
+    tm.assert_series_equal(cython_or_numpy, python)
+
+
+# TODO: remove this kludge once mypy stops giving false positives here
+# List comprehension has incompatible type List[PandasObject]; expected List[RangeIndex]
+#  See GH#29725
+_ldtypes = ["i1", "i2", "i4", "i8", "u1", "u2", "u4", "u8", "f2", "f4", "f8"]
+lefts: list[Index | Series] = [RangeIndex(10, 40, 10)]
+lefts.extend([Series([10, 20, 30], dtype=dtype) for dtype in _ldtypes])
+lefts.extend([Index([10, 20, 30], dtype=dtype) for dtype in _ldtypes if dtype != "f2"])
+
+# ------------------------------------------------------------------
+# Comparisons
+
+
+class TestNumericComparisons:
+    def test_operator_series_comparison_zerorank(self):
+        # GH#13006
+        result = np.float64(0) > Series([1, 2, 3])
+        expected = 0.0 > Series([1, 2, 3])
+        tm.assert_series_equal(result, expected)
+        result = Series([1, 2, 3]) < np.float64(0)
+        expected = Series([1, 2, 3]) < 0.0
+        tm.assert_series_equal(result, expected)
+        result = np.array([0, 1, 2])[0] > Series([0, 1, 2])
+        expected = 0.0 > Series([1, 2, 3])
+        tm.assert_series_equal(result, expected)
+
+    def test_df_numeric_cmp_dt64_raises(self, box_with_array, fixed_now_ts):
+        # GH#8932, GH#22163
+        ts = fixed_now_ts
+        obj = np.array(range(5))
+        obj = tm.box_expected(obj, box_with_array)
+
+        assert_invalid_comparison(obj, ts, box_with_array)
+
+    def test_compare_invalid(self):
+        # GH#8058
+        # ops testing
+        a = Series(np.random.default_rng(2).standard_normal(5), name=0)
+        b = Series(np.random.default_rng(2).standard_normal(5))
+        b.name = pd.Timestamp("2000-01-01")
+        tm.assert_series_equal(a / b, 1 / (b / a))
+
+    def test_numeric_cmp_string_numexpr_path(self, box_with_array, monkeypatch):
+        # GH#36377, GH#35700
+        box = box_with_array
+        xbox = box if box is not Index else np.ndarray
+
+        obj = Series(np.random.default_rng(2).standard_normal(51))
+        obj = tm.box_expected(obj, box, transpose=False)
+        with monkeypatch.context() as m:
+            m.setattr(expr, "_MIN_ELEMENTS", 50)
+            result = obj == "a"
+
+        expected = Series(np.zeros(51, dtype=bool))
+        expected = tm.box_expected(expected, xbox, transpose=False)
+        tm.assert_equal(result, expected)
+
+        with monkeypatch.context() as m:
+            m.setattr(expr, "_MIN_ELEMENTS", 50)
+            result = obj != "a"
+        tm.assert_equal(result, ~expected)
+
+        msg = "Invalid comparison between dtype=float64 and str"
+        with pytest.raises(TypeError, match=msg):
+            obj < "a"
+
+
+# ------------------------------------------------------------------
+# Numeric dtypes Arithmetic with Datetime/Timedelta Scalar
+
+
+class TestNumericArraylikeArithmeticWithDatetimeLike:
+    @pytest.mark.parametrize("box_cls", [np.array, Index, Series])
+    @pytest.mark.parametrize(
+        "left", lefts, ids=lambda x: type(x).__name__ + str(x.dtype)
+    )
+    def test_mul_td64arr(self, left, box_cls):
+        # GH#22390
+        right = np.array([1, 2, 3], dtype="m8[s]")
+        right = box_cls(right)
+
+        expected = TimedeltaIndex(["10s", "40s", "90s"], dtype=right.dtype)
+
+        if isinstance(left, Series) or box_cls is Series:
+            expected = Series(expected)
+        assert expected.dtype == right.dtype
+
+        result = left * right
+        tm.assert_equal(result, expected)
+
+        result = right * left
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize("box_cls", [np.array, Index, Series])
+    @pytest.mark.parametrize(
+        "left", lefts, ids=lambda x: type(x).__name__ + str(x.dtype)
+    )
+    def test_div_td64arr(self, left, box_cls):
+        # GH#22390
+        right = np.array([10, 40, 90], dtype="m8[s]")
+        right = box_cls(right)
+
+        expected = TimedeltaIndex(["1s", "2s", "3s"], dtype=right.dtype)
+        if isinstance(left, Series) or box_cls is Series:
+            expected = Series(expected)
+        assert expected.dtype == right.dtype
+
+        result = right / left
+        tm.assert_equal(result, expected)
+
+        result = right // left
+        tm.assert_equal(result, expected)
+
+        # (true_) needed for min-versions build 2022-12-26
+        msg = "ufunc '(true_)?divide' cannot use operands with types"
+        with pytest.raises(TypeError, match=msg):
+            left / right
+
+        msg = "ufunc 'floor_divide' cannot use operands with types"
+        with pytest.raises(TypeError, match=msg):
+            left // right
+
+    # TODO: also test Tick objects;
+    #  see test_numeric_arr_rdiv_tdscalar for note on these failing
+    @pytest.mark.parametrize(
+        "scalar_td",
+        [
+            Timedelta(days=1),
+            Timedelta(days=1).to_timedelta64(),
+            Timedelta(days=1).to_pytimedelta(),
+            Timedelta(days=1).to_timedelta64().astype("timedelta64[s]"),
+            Timedelta(days=1).to_timedelta64().astype("timedelta64[ms]"),
+        ],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_numeric_arr_mul_tdscalar(self, scalar_td, numeric_idx, box_with_array):
+        # GH#19333
+        box = box_with_array
+        index = numeric_idx
+        expected = TimedeltaIndex([Timedelta(days=n) for n in range(len(index))])
+        if isinstance(scalar_td, np.timedelta64):
+            dtype = scalar_td.dtype
+            expected = expected.astype(dtype)
+        elif type(scalar_td) is timedelta:
+            expected = expected.astype("m8[us]")
+
+        index = tm.box_expected(index, box)
+        expected = tm.box_expected(expected, box)
+
+        result = index * scalar_td
+        tm.assert_equal(result, expected)
+
+        commute = scalar_td * index
+        tm.assert_equal(commute, expected)
+
+    @pytest.mark.parametrize(
+        "scalar_td",
+        [
+            Timedelta(days=1),
+            Timedelta(days=1).to_timedelta64(),
+            Timedelta(days=1).to_pytimedelta(),
+        ],
+        ids=lambda x: type(x).__name__,
+    )
+    @pytest.mark.parametrize("dtype", [np.int64, np.float64])
+    def test_numeric_arr_mul_tdscalar_numexpr_path(
+        self, dtype, scalar_td, box_with_array
+    ):
+        # GH#44772 for the float64 case
+        box = box_with_array
+
+        arr_i8 = np.arange(2 * 10**4).astype(np.int64, copy=False)
+        arr = arr_i8.astype(dtype, copy=False)
+        obj = tm.box_expected(arr, box, transpose=False)
+
+        expected = arr_i8.view("timedelta64[D]").astype("timedelta64[ns]")
+        if type(scalar_td) is timedelta:
+            expected = expected.astype("timedelta64[us]")
+
+        expected = tm.box_expected(expected, box, transpose=False)
+
+        result = obj * scalar_td
+        tm.assert_equal(result, expected)
+
+        result = scalar_td * obj
+        tm.assert_equal(result, expected)
+
+    def test_numeric_arr_rdiv_tdscalar(self, three_days, numeric_idx, box_with_array):
+        box = box_with_array
+
+        index = numeric_idx[1:3]
+
+        expected = TimedeltaIndex(["3 Days", "36 Hours"])
+        if isinstance(three_days, np.timedelta64):
+            dtype = three_days.dtype
+            if dtype < np.dtype("m8[s]"):
+                # i.e. resolution is lower -> use lowest supported resolution
+                dtype = np.dtype("m8[s]")
+            expected = expected.astype(dtype)
+        elif type(three_days) is timedelta:
+            expected = expected.astype("m8[us]")
+        elif isinstance(
+            three_days,
+            (pd.offsets.Day, pd.offsets.Hour, pd.offsets.Minute, pd.offsets.Second),
+        ):
+            # closest reso is Second
+            expected = expected.astype("m8[s]")
+
+        index = tm.box_expected(index, box)
+        expected = tm.box_expected(expected, box)
+
+        result = three_days / index
+        tm.assert_equal(result, expected)
+
+        msg = "cannot use operands with types dtype"
+        with pytest.raises(TypeError, match=msg):
+            index / three_days
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            Timedelta(hours=31),
+            Timedelta(hours=31).to_pytimedelta(),
+            Timedelta(hours=31).to_timedelta64(),
+            Timedelta(hours=31).to_timedelta64().astype("m8[h]"),
+            np.timedelta64("NaT"),
+            np.timedelta64("NaT", "D"),
+            pd.offsets.Minute(3),
+            pd.offsets.Second(0),
+            # GH#28080 numeric+datetimelike should raise; Timestamp used
+            #  to raise NullFrequencyError but that behavior was removed in 1.0
+            pd.Timestamp("2021-01-01", tz="Asia/Tokyo"),
+            pd.Timestamp("2021-01-01"),
+            pd.Timestamp("2021-01-01").to_pydatetime(),
+            pd.Timestamp("2021-01-01", tz="UTC").to_pydatetime(),
+            pd.Timestamp("2021-01-01").to_datetime64(),
+            np.datetime64("NaT", "ns"),
+            pd.NaT,
+        ],
+        ids=repr,
+    )
+    def test_add_sub_datetimedeltalike_invalid(
+        self, numeric_idx, other, box_with_array
+    ):
+        box = box_with_array
+
+        left = tm.box_expected(numeric_idx, box)
+        msg = "|".join(
+            [
+                "unsupported operand type",
+                "Addition/subtraction of integers and integer-arrays",
+                "Instead of adding/subtracting",
+                "cannot use operands with types dtype",
+                "Concatenation operation is not implemented for NumPy arrays",
+                "Cannot (add|subtract) NaT (to|from) ndarray",
+                # pd.array vs np.datetime64 case
+                r"operand type\(s\) all returned NotImplemented from __array_ufunc__",
+                "can only perform ops with numeric values",
+                "cannot subtract DatetimeArray from ndarray",
+                # pd.Timedelta(1) + Index([0, 1, 2])
+                "Cannot add or subtract Timedelta from integers",
+            ]
+        )
+        assert_invalid_addsub_type(left, other, msg)
+
+
+# ------------------------------------------------------------------
+# Arithmetic
+
+
+class TestDivisionByZero:
+    def test_div_zero(self, zero, numeric_idx):
+        idx = numeric_idx
+
+        expected = Index([np.nan, np.inf, np.inf, np.inf, np.inf], dtype=np.float64)
+        # We only adjust for Index, because Series does not yet apply
+        #  the adjustment correctly.
+        expected2 = adjust_negative_zero(zero, expected)
+
+        result = idx / zero
+        tm.assert_index_equal(result, expected2)
+        ser_compat = Series(idx).astype("i8") / np.array(zero).astype("i8")
+        tm.assert_series_equal(ser_compat, Series(expected))
+
+    def test_floordiv_zero(self, zero, numeric_idx):
+        idx = numeric_idx
+
+        expected = Index([np.nan, np.inf, np.inf, np.inf, np.inf], dtype=np.float64)
+        # We only adjust for Index, because Series does not yet apply
+        #  the adjustment correctly.
+        expected2 = adjust_negative_zero(zero, expected)
+
+        result = idx // zero
+        tm.assert_index_equal(result, expected2)
+        ser_compat = Series(idx).astype("i8") // np.array(zero).astype("i8")
+        tm.assert_series_equal(ser_compat, Series(expected))
+
+    def test_mod_zero(self, zero, numeric_idx):
+        idx = numeric_idx
+
+        expected = Index([np.nan, np.nan, np.nan, np.nan, np.nan], dtype=np.float64)
+        result = idx % zero
+        tm.assert_index_equal(result, expected)
+        ser_compat = Series(idx).astype("i8") % np.array(zero).astype("i8")
+        tm.assert_series_equal(ser_compat, Series(result))
+
+    def test_divmod_zero(self, zero, numeric_idx):
+        idx = numeric_idx
+
+        exleft = Index([np.nan, np.inf, np.inf, np.inf, np.inf], dtype=np.float64)
+        exright = Index([np.nan, np.nan, np.nan, np.nan, np.nan], dtype=np.float64)
+        exleft = adjust_negative_zero(zero, exleft)
+
+        result = divmod(idx, zero)
+        tm.assert_index_equal(result[0], exleft)
+        tm.assert_index_equal(result[1], exright)
+
+    @pytest.mark.parametrize("op", [operator.truediv, operator.floordiv])
+    def test_div_negative_zero(self, zero, numeric_idx, op):
+        # Check that -1 / -0.0 returns np.inf, not -np.inf
+        if numeric_idx.dtype == np.uint64:
+            pytest.skip(f"Div by negative 0 not relevant for {numeric_idx.dtype}")
+        idx = numeric_idx - 3
+
+        expected = Index([-np.inf, -np.inf, -np.inf, np.nan, np.inf], dtype=np.float64)
+        expected = adjust_negative_zero(zero, expected)
+
+        result = op(idx, zero)
+        tm.assert_index_equal(result, expected)
+
+    # ------------------------------------------------------------------
+
+    @pytest.mark.parametrize("dtype1", [np.int64, np.float64, np.uint64])
+    def test_ser_div_ser(
+        self,
+        switch_numexpr_min_elements,
+        dtype1,
+        any_real_numpy_dtype,
+    ):
+        # no longer do integer div for any ops, but deal with the 0's
+        dtype2 = any_real_numpy_dtype
+
+        first = Series([3, 4, 5, 8], name="first").astype(dtype1)
+        second = Series([0, 0, 0, 3], name="second").astype(dtype2)
+
+        with np.errstate(all="ignore"):
+            expected = Series(
+                first.values.astype(np.float64) / second.values,
+                dtype="float64",
+                name=None,
+            )
+        expected.iloc[0:3] = np.inf
+        if first.dtype == "int64" and second.dtype == "float32":
+            # when using numexpr, the casting rules are slightly different
+            # and int64/float32 combo results in float32 instead of float64
+            if expr.USE_NUMEXPR and switch_numexpr_min_elements == 0:
+                expected = expected.astype("float32")
+
+        result = first / second
+        tm.assert_series_equal(result, expected)
+        assert not result.equals(second / first)
+
+    @pytest.mark.parametrize("dtype1", [np.int64, np.float64, np.uint64])
+    def test_ser_divmod_zero(self, dtype1, any_real_numpy_dtype):
+        # GH#26987
+        dtype2 = any_real_numpy_dtype
+        left = Series([1, 1]).astype(dtype1)
+        right = Series([0, 2]).astype(dtype2)
+
+        # GH#27321 pandas convention is to set 1 // 0 to np.inf, as opposed
+        #  to numpy which sets to np.nan; patch `expected[0]` below
+        expected = left // right, left % right
+        expected = list(expected)
+        expected[0] = expected[0].astype(np.float64)
+        expected[0][0] = np.inf
+        result = divmod(left, right)
+
+        tm.assert_series_equal(result[0], expected[0])
+        tm.assert_series_equal(result[1], expected[1])
+
+        # rdivmod case
+        result = divmod(left.values, right)
+        tm.assert_series_equal(result[0], expected[0])
+        tm.assert_series_equal(result[1], expected[1])
+
+    def test_ser_divmod_inf(self):
+        left = Series([np.inf, 1.0])
+        right = Series([np.inf, 2.0])
+
+        expected = left // right, left % right
+        result = divmod(left, right)
+
+        tm.assert_series_equal(result[0], expected[0])
+        tm.assert_series_equal(result[1], expected[1])
+
+        # rdivmod case
+        result = divmod(left.values, right)
+        tm.assert_series_equal(result[0], expected[0])
+        tm.assert_series_equal(result[1], expected[1])
+
+    def test_rdiv_zero_compat(self):
+        # GH#8674
+        zero_array = np.array([0] * 5)
+        data = np.random.default_rng(2).standard_normal(5)
+        expected = Series([0.0] * 5)
+
+        result = zero_array / Series(data)
+        tm.assert_series_equal(result, expected)
+
+        result = Series(zero_array) / data
+        tm.assert_series_equal(result, expected)
+
+        result = Series(zero_array) / Series(data)
+        tm.assert_series_equal(result, expected)
+
+    def test_div_zero_inf_signs(self):
+        # GH#9144, inf signing
+        ser = Series([-1, 0, 1], name="first")
+        expected = Series([-np.inf, np.nan, np.inf], name="first")
+
+        result = ser / 0
+        tm.assert_series_equal(result, expected)
+
+    def test_rdiv_zero(self):
+        # GH#9144
+        ser = Series([-1, 0, 1], name="first")
+        expected = Series([0.0, np.nan, 0.0], name="first")
+
+        result = 0 / ser
+        tm.assert_series_equal(result, expected)
+
+    def test_floordiv_div(self):
+        # GH#9144
+        ser = Series([-1, 0, 1], name="first")
+
+        result = ser // 0
+        expected = Series([-np.inf, np.nan, np.inf], name="first")
+        tm.assert_series_equal(result, expected)
+
+    def test_df_div_zero_df(self):
+        # integer div, but deal with the 0's (GH#9144)
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+        result = df / df
+
+        first = Series([1.0, 1.0, 1.0, 1.0])
+        second = Series([np.nan, np.nan, np.nan, 1])
+        expected = pd.DataFrame({"first": first, "second": second})
+        tm.assert_frame_equal(result, expected)
+
+    def test_df_div_zero_array(self):
+        # integer div, but deal with the 0's (GH#9144)
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+
+        first = Series([1.0, 1.0, 1.0, 1.0])
+        second = Series([np.nan, np.nan, np.nan, 1])
+        expected = pd.DataFrame({"first": first, "second": second})
+
+        with np.errstate(all="ignore"):
+            arr = df.values.astype("float") / df.values
+        result = pd.DataFrame(arr, index=df.index, columns=df.columns)
+        tm.assert_frame_equal(result, expected)
+
+    def test_df_div_zero_int(self):
+        # integer div, but deal with the 0's (GH#9144)
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+
+        result = df / 0
+        expected = pd.DataFrame(np.inf, index=df.index, columns=df.columns)
+        expected.iloc[0:3, 1] = np.nan
+        tm.assert_frame_equal(result, expected)
+
+        # numpy has a slightly different (wrong) treatment
+        with np.errstate(all="ignore"):
+            arr = df.values.astype("float64") / 0
+        result2 = pd.DataFrame(arr, index=df.index, columns=df.columns)
+        tm.assert_frame_equal(result2, expected)
+
+    def test_df_div_zero_series_does_not_commute(self):
+        # integer div, but deal with the 0's (GH#9144)
+        df = pd.DataFrame(np.random.default_rng(2).standard_normal((10, 5)))
+        ser = df[0]
+        res = ser / df
+        res2 = df / ser
+        assert not res.fillna(0).equals(res2.fillna(0))
+
+    # ------------------------------------------------------------------
+    # Mod By Zero
+
+    def test_df_mod_zero_df(self, using_array_manager):
+        # GH#3590, modulo as ints
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+        # this is technically wrong, as the integer portion is coerced to float
+        first = Series([0, 0, 0, 0])
+        if not using_array_manager:
+            # INFO(ArrayManager) BlockManager doesn't preserve dtype per column
+            # while ArrayManager performs op column-wisedoes and thus preserves
+            # dtype if possible
+            first = first.astype("float64")
+        second = Series([np.nan, np.nan, np.nan, 0])
+        expected = pd.DataFrame({"first": first, "second": second})
+        result = df % df
+        tm.assert_frame_equal(result, expected)
+
+        # GH#38939 If we dont pass copy=False, df is consolidated and
+        #  result["first"] is float64 instead of int64
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]}, copy=False)
+        first = Series([0, 0, 0, 0], dtype="int64")
+        second = Series([np.nan, np.nan, np.nan, 0])
+        expected = pd.DataFrame({"first": first, "second": second})
+        result = df % df
+        tm.assert_frame_equal(result, expected)
+
+    def test_df_mod_zero_array(self):
+        # GH#3590, modulo as ints
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+
+        # this is technically wrong, as the integer portion is coerced to float
+        # ###
+        first = Series([0, 0, 0, 0], dtype="float64")
+        second = Series([np.nan, np.nan, np.nan, 0])
+        expected = pd.DataFrame({"first": first, "second": second})
+
+        # numpy has a slightly different (wrong) treatment
+        with np.errstate(all="ignore"):
+            arr = df.values % df.values
+        result2 = pd.DataFrame(arr, index=df.index, columns=df.columns, dtype="float64")
+        result2.iloc[0:3, 1] = np.nan
+        tm.assert_frame_equal(result2, expected)
+
+    def test_df_mod_zero_int(self):
+        # GH#3590, modulo as ints
+        df = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+
+        result = df % 0
+        expected = pd.DataFrame(np.nan, index=df.index, columns=df.columns)
+        tm.assert_frame_equal(result, expected)
+
+        # numpy has a slightly different (wrong) treatment
+        with np.errstate(all="ignore"):
+            arr = df.values.astype("float64") % 0
+        result2 = pd.DataFrame(arr, index=df.index, columns=df.columns)
+        tm.assert_frame_equal(result2, expected)
+
+    def test_df_mod_zero_series_does_not_commute(self):
+        # GH#3590, modulo as ints
+        # not commutative with series
+        df = pd.DataFrame(np.random.default_rng(2).standard_normal((10, 5)))
+        ser = df[0]
+        res = ser % df
+        res2 = df % ser
+        assert not res.fillna(0).equals(res2.fillna(0))
+
+
+class TestMultiplicationDivision:
+    # __mul__, __rmul__, __div__, __rdiv__, __floordiv__, __rfloordiv__
+    # for non-timestamp/timedelta/period dtypes
+
+    def test_divide_decimal(self, box_with_array):
+        # resolves issue GH#9787
+        box = box_with_array
+        ser = Series([Decimal(10)])
+        expected = Series([Decimal(5)])
+
+        ser = tm.box_expected(ser, box)
+        expected = tm.box_expected(expected, box)
+
+        result = ser / Decimal(2)
+
+        tm.assert_equal(result, expected)
+
+        result = ser // Decimal(2)
+        tm.assert_equal(result, expected)
+
+    def test_div_equiv_binop(self):
+        # Test Series.div as well as Series.__div__
+        # float/integer issue
+        # GH#7785
+        first = Series([1, 0], name="first")
+        second = Series([-0.01, -0.02], name="second")
+        expected = Series([-0.01, -np.inf])
+
+        result = second.div(first)
+        tm.assert_series_equal(result, expected, check_names=False)
+
+        result = second / first
+        tm.assert_series_equal(result, expected)
+
+    def test_div_int(self, numeric_idx):
+        idx = numeric_idx
+        result = idx / 1
+        expected = idx.astype("float64")
+        tm.assert_index_equal(result, expected)
+
+        result = idx / 2
+        expected = Index(idx.values / 2)
+        tm.assert_index_equal(result, expected)
+
+    @pytest.mark.parametrize("op", [operator.mul, ops.rmul, operator.floordiv])
+    def test_mul_int_identity(self, op, numeric_idx, box_with_array):
+        idx = numeric_idx
+        idx = tm.box_expected(idx, box_with_array)
+
+        result = op(idx, 1)
+        tm.assert_equal(result, idx)
+
+    def test_mul_int_array(self, numeric_idx):
+        idx = numeric_idx
+        didx = idx * idx
+
+        result = idx * np.array(5, dtype="int64")
+        tm.assert_index_equal(result, idx * 5)
+
+        arr_dtype = "uint64" if idx.dtype == np.uint64 else "int64"
+        result = idx * np.arange(5, dtype=arr_dtype)
+        tm.assert_index_equal(result, didx)
+
+    def test_mul_int_series(self, numeric_idx):
+        idx = numeric_idx
+        didx = idx * idx
+
+        arr_dtype = "uint64" if idx.dtype == np.uint64 else "int64"
+        result = idx * Series(np.arange(5, dtype=arr_dtype))
+        tm.assert_series_equal(result, Series(didx))
+
+    def test_mul_float_series(self, numeric_idx):
+        idx = numeric_idx
+        rng5 = np.arange(5, dtype="float64")
+
+        result = idx * Series(rng5 + 0.1)
+        expected = Series(rng5 * (rng5 + 0.1))
+        tm.assert_series_equal(result, expected)
+
+    def test_mul_index(self, numeric_idx):
+        idx = numeric_idx
+
+        result = idx * idx
+        tm.assert_index_equal(result, idx**2)
+
+    def test_mul_datelike_raises(self, numeric_idx):
+        idx = numeric_idx
+        msg = "cannot perform __rmul__ with this index type"
+        with pytest.raises(TypeError, match=msg):
+            idx * date_range("20130101", periods=5)
+
+    def test_mul_size_mismatch_raises(self, numeric_idx):
+        idx = numeric_idx
+        msg = "operands could not be broadcast together"
+        with pytest.raises(ValueError, match=msg):
+            idx * idx[0:3]
+        with pytest.raises(ValueError, match=msg):
+            idx * np.array([1, 2])
+
+    @pytest.mark.parametrize("op", [operator.pow, ops.rpow])
+    def test_pow_float(self, op, numeric_idx, box_with_array):
+        # test power calculations both ways, GH#14973
+        box = box_with_array
+        idx = numeric_idx
+        expected = Index(op(idx.values, 2.0))
+
+        idx = tm.box_expected(idx, box)
+        expected = tm.box_expected(expected, box)
+
+        result = op(idx, 2.0)
+        tm.assert_equal(result, expected)
+
+    def test_modulo(self, numeric_idx, box_with_array):
+        # GH#9244
+        box = box_with_array
+        idx = numeric_idx
+        expected = Index(idx.values % 2)
+
+        idx = tm.box_expected(idx, box)
+        expected = tm.box_expected(expected, box)
+
+        result = idx % 2
+        tm.assert_equal(result, expected)
+
+    def test_divmod_scalar(self, numeric_idx):
+        idx = numeric_idx
+
+        result = divmod(idx, 2)
+        with np.errstate(all="ignore"):
+            div, mod = divmod(idx.values, 2)
+
+        expected = Index(div), Index(mod)
+        for r, e in zip(result, expected):
+            tm.assert_index_equal(r, e)
+
+    def test_divmod_ndarray(self, numeric_idx):
+        idx = numeric_idx
+        other = np.ones(idx.values.shape, dtype=idx.values.dtype) * 2
+
+        result = divmod(idx, other)
+        with np.errstate(all="ignore"):
+            div, mod = divmod(idx.values, other)
+
+        expected = Index(div), Index(mod)
+        for r, e in zip(result, expected):
+            tm.assert_index_equal(r, e)
+
+    def test_divmod_series(self, numeric_idx):
+        idx = numeric_idx
+        other = np.ones(idx.values.shape, dtype=idx.values.dtype) * 2
+
+        result = divmod(idx, Series(other))
+        with np.errstate(all="ignore"):
+            div, mod = divmod(idx.values, other)
+
+        expected = Series(div), Series(mod)
+        for r, e in zip(result, expected):
+            tm.assert_series_equal(r, e)
+
+    @pytest.mark.parametrize("other", [np.nan, 7, -23, 2.718, -3.14, np.inf])
+    def test_ops_np_scalar(self, other):
+        vals = np.random.default_rng(2).standard_normal((5, 3))
+        f = lambda x: pd.DataFrame(
+            x, index=list("ABCDE"), columns=["jim", "joe", "jolie"]
+        )
+
+        df = f(vals)
+
+        tm.assert_frame_equal(df / np.array(other), f(vals / other))
+        tm.assert_frame_equal(np.array(other) * df, f(vals * other))
+        tm.assert_frame_equal(df + np.array(other), f(vals + other))
+        tm.assert_frame_equal(np.array(other) - df, f(other - vals))
+
+    # TODO: This came from series.test.test_operators, needs cleanup
+    def test_operators_frame(self):
+        # rpow does not work with DataFrame
+        ts = Series(
+            np.arange(10, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+        ts.name = "ts"
+
+        df = pd.DataFrame({"A": ts})
+
+        tm.assert_series_equal(ts + ts, ts + df["A"], check_names=False)
+        tm.assert_series_equal(ts**ts, ts ** df["A"], check_names=False)
+        tm.assert_series_equal(ts < ts, ts < df["A"], check_names=False)
+        tm.assert_series_equal(ts / ts, ts / df["A"], check_names=False)
+
+    # TODO: this came from tests.series.test_analytics, needs cleanup and
+    #  de-duplication with test_modulo above
+    def test_modulo2(self):
+        with np.errstate(all="ignore"):
+            # GH#3590, modulo as ints
+            p = pd.DataFrame({"first": [3, 4, 5, 8], "second": [0, 0, 0, 3]})
+            result = p["first"] % p["second"]
+            expected = Series(p["first"].values % p["second"].values, dtype="float64")
+            expected.iloc[0:3] = np.nan
+            tm.assert_series_equal(result, expected)
+
+            result = p["first"] % 0
+            expected = Series(np.nan, index=p.index, name="first")
+            tm.assert_series_equal(result, expected)
+
+            p = p.astype("float64")
+            result = p["first"] % p["second"]
+            expected = Series(p["first"].values % p["second"].values)
+            tm.assert_series_equal(result, expected)
+
+            p = p.astype("float64")
+            result = p["first"] % p["second"]
+            result2 = p["second"] % p["first"]
+            assert not result.equals(result2)
+
+    def test_modulo_zero_int(self):
+        # GH#9144
+        with np.errstate(all="ignore"):
+            s = Series([0, 1])
+
+            result = s % 0
+            expected = Series([np.nan, np.nan])
+            tm.assert_series_equal(result, expected)
+
+            result = 0 % s
+            expected = Series([np.nan, 0.0])
+            tm.assert_series_equal(result, expected)
+
+
+class TestAdditionSubtraction:
+    # __add__, __sub__, __radd__, __rsub__, __iadd__, __isub__
+    # for non-timestamp/timedelta/period dtypes
+
+    @pytest.mark.parametrize(
+        "first, second, expected",
+        [
+            (
+                Series([1, 2, 3], index=list("ABC"), name="x"),
+                Series([2, 2, 2], index=list("ABD"), name="x"),
+                Series([3.0, 4.0, np.nan, np.nan], index=list("ABCD"), name="x"),
+            ),
+            (
+                Series([1, 2, 3], index=list("ABC"), name="x"),
+                Series([2, 2, 2, 2], index=list("ABCD"), name="x"),
+                Series([3, 4, 5, np.nan], index=list("ABCD"), name="x"),
+            ),
+        ],
+    )
+    def test_add_series(self, first, second, expected):
+        # GH#1134
+        tm.assert_series_equal(first + second, expected)
+        tm.assert_series_equal(second + first, expected)
+
+    @pytest.mark.parametrize(
+        "first, second, expected",
+        [
+            (
+                pd.DataFrame({"x": [1, 2, 3]}, index=list("ABC")),
+                pd.DataFrame({"x": [2, 2, 2]}, index=list("ABD")),
+                pd.DataFrame({"x": [3.0, 4.0, np.nan, np.nan]}, index=list("ABCD")),
+            ),
+            (
+                pd.DataFrame({"x": [1, 2, 3]}, index=list("ABC")),
+                pd.DataFrame({"x": [2, 2, 2, 2]}, index=list("ABCD")),
+                pd.DataFrame({"x": [3, 4, 5, np.nan]}, index=list("ABCD")),
+            ),
+        ],
+    )
+    def test_add_frames(self, first, second, expected):
+        # GH#1134
+        tm.assert_frame_equal(first + second, expected)
+        tm.assert_frame_equal(second + first, expected)
+
+    # TODO: This came from series.test.test_operators, needs cleanup
+    def test_series_frame_radd_bug(self, fixed_now_ts):
+        # GH#353
+        vals = Series([str(i) for i in range(5)])
+        result = "foo_" + vals
+        expected = vals.map(lambda x: "foo_" + x)
+        tm.assert_series_equal(result, expected)
+
+        frame = pd.DataFrame({"vals": vals})
+        result = "foo_" + frame
+        expected = pd.DataFrame({"vals": vals.map(lambda x: "foo_" + x)})
+        tm.assert_frame_equal(result, expected)
+
+        ts = Series(
+            np.arange(10, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+
+        # really raise this time
+        fix_now = fixed_now_ts.to_pydatetime()
+        msg = "|".join(
+            [
+                "unsupported operand type",
+                # wrong error message, see https://github.com/numpy/numpy/issues/18832
+                "Concatenation operation",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            fix_now + ts
+
+        with pytest.raises(TypeError, match=msg):
+            ts + fix_now
+
+    # TODO: This came from series.test.test_operators, needs cleanup
+    def test_datetime64_with_index(self):
+        # arithmetic integer ops with an index
+        ser = Series(np.random.default_rng(2).standard_normal(5))
+        expected = ser - ser.index.to_series()
+        result = ser - ser.index
+        tm.assert_series_equal(result, expected)
+
+        # GH#4629
+        # arithmetic datetime64 ops with an index
+        ser = Series(
+            date_range("20130101", periods=5),
+            index=date_range("20130101", periods=5),
+        )
+        expected = ser - ser.index.to_series()
+        result = ser - ser.index
+        tm.assert_series_equal(result, expected)
+
+        msg = "cannot subtract PeriodArray from DatetimeArray"
+        with pytest.raises(TypeError, match=msg):
+            # GH#18850
+            result = ser - ser.index.to_period()
+
+        df = pd.DataFrame(
+            np.random.default_rng(2).standard_normal((5, 2)),
+            index=date_range("20130101", periods=5),
+        )
+        df["date"] = pd.Timestamp("20130102")
+        df["expected"] = df["date"] - df.index.to_series()
+        df["result"] = df["date"] - df.index
+        tm.assert_series_equal(df["result"], df["expected"], check_names=False)
+
+    # TODO: taken from tests.frame.test_operators, needs cleanup
+    def test_frame_operators(self, float_frame):
+        frame = float_frame
+
+        garbage = np.random.default_rng(2).random(4)
+        colSeries = Series(garbage, index=np.array(frame.columns))
+
+        idSum = frame + frame
+        seriesSum = frame + colSeries
+
+        for col, series in idSum.items():
+            for idx, val in series.items():
+                origVal = frame[col][idx] * 2
+                if not np.isnan(val):
+                    assert val == origVal
+                else:
+                    assert np.isnan(origVal)
+
+        for col, series in seriesSum.items():
+            for idx, val in series.items():
+                origVal = frame[col][idx] + colSeries[col]
+                if not np.isnan(val):
+                    assert val == origVal
+                else:
+                    assert np.isnan(origVal)
+
+    def test_frame_operators_col_align(self, float_frame):
+        frame2 = pd.DataFrame(float_frame, columns=["D", "C", "B", "A"])
+        added = frame2 + frame2
+        expected = frame2 * 2
+        tm.assert_frame_equal(added, expected)
+
+    def test_frame_operators_none_to_nan(self):
+        df = pd.DataFrame({"a": ["a", None, "b"]})
+        tm.assert_frame_equal(df + df, pd.DataFrame({"a": ["aa", np.nan, "bb"]}))
+
+    @pytest.mark.parametrize("dtype", ("float", "int64"))
+    def test_frame_operators_empty_like(self, dtype):
+        # Test for issue #10181
+        frames = [
+            pd.DataFrame(dtype=dtype),
+            pd.DataFrame(columns=["A"], dtype=dtype),
+            pd.DataFrame(index=[0], dtype=dtype),
+        ]
+        for df in frames:
+            assert (df + df).equals(df)
+            tm.assert_frame_equal(df + df, df)
+
+    @pytest.mark.parametrize(
+        "func",
+        [lambda x: x * 2, lambda x: x[::2], lambda x: 5],
+        ids=["multiply", "slice", "constant"],
+    )
+    def test_series_operators_arithmetic(self, all_arithmetic_functions, func):
+        op = all_arithmetic_functions
+        series = Series(
+            np.arange(10, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+        other = func(series)
+        compare_op(series, other, op)
+
+    @pytest.mark.parametrize(
+        "func", [lambda x: x + 1, lambda x: 5], ids=["add", "constant"]
+    )
+    def test_series_operators_compare(self, comparison_op, func):
+        op = comparison_op
+        series = Series(
+            np.arange(10, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+        other = func(series)
+        compare_op(series, other, op)
+
+    @pytest.mark.parametrize(
+        "func",
+        [lambda x: x * 2, lambda x: x[::2], lambda x: 5],
+        ids=["multiply", "slice", "constant"],
+    )
+    def test_divmod(self, func):
+        series = Series(
+            np.arange(10, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+        other = func(series)
+        results = divmod(series, other)
+        if isinstance(other, abc.Iterable) and len(series) != len(other):
+            # if the lengths don't match, this is the test where we use
+            # `tser[::2]`. Pad every other value in `other_np` with nan.
+            other_np = []
+            for n in other:
+                other_np.append(n)
+                other_np.append(np.nan)
+        else:
+            other_np = other
+        other_np = np.asarray(other_np)
+        with np.errstate(all="ignore"):
+            expecteds = divmod(series.values, np.asarray(other_np))
+
+        for result, expected in zip(results, expecteds):
+            # check the values, name, and index separately
+            tm.assert_almost_equal(np.asarray(result), expected)
+
+            assert result.name == series.name
+            tm.assert_index_equal(result.index, series.index._with_freq(None))
+
+    def test_series_divmod_zero(self):
+        # Check that divmod uses pandas convention for division by zero,
+        #  which does not match numpy.
+        # pandas convention has
+        #  1/0 == np.inf
+        #  -1/0 == -np.inf
+        #  1/-0.0 == -np.inf
+        #  -1/-0.0 == np.inf
+        tser = Series(
+            np.arange(1, 11, dtype=np.float64),
+            index=date_range("2020-01-01", periods=10),
+            name="ts",
+        )
+        other = tser * 0
+
+        result = divmod(tser, other)
+        exp1 = Series([np.inf] * len(tser), index=tser.index, name="ts")
+        exp2 = Series([np.nan] * len(tser), index=tser.index, name="ts")
+        tm.assert_series_equal(result[0], exp1)
+        tm.assert_series_equal(result[1], exp2)
+
+
+class TestUFuncCompat:
+    # TODO: add more dtypes
+    @pytest.mark.parametrize("holder", [Index, RangeIndex, Series])
+    @pytest.mark.parametrize("dtype", [np.int64, np.uint64, np.float64])
+    def test_ufunc_compat(self, holder, dtype):
+        box = Series if holder is Series else Index
+
+        if holder is RangeIndex:
+            if dtype != np.int64:
+                pytest.skip(f"dtype {dtype} not relevant for RangeIndex")
+            idx = RangeIndex(0, 5, name="foo")
+        else:
+            idx = holder(np.arange(5, dtype=dtype), name="foo")
+        result = np.sin(idx)
+        expected = box(np.sin(np.arange(5, dtype=dtype)), name="foo")
+        tm.assert_equal(result, expected)
+
+    # TODO: add more dtypes
+    @pytest.mark.parametrize("holder", [Index, Series])
+    @pytest.mark.parametrize("dtype", [np.int64, np.uint64, np.float64])
+    def test_ufunc_coercions(self, holder, dtype):
+        idx = holder([1, 2, 3, 4, 5], dtype=dtype, name="x")
+        box = Series if holder is Series else Index
+
+        result = np.sqrt(idx)
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index(np.sqrt(np.array([1, 2, 3, 4, 5], dtype=np.float64)), name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+        result = np.divide(idx, 2.0)
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index([0.5, 1.0, 1.5, 2.0, 2.5], dtype=np.float64, name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+        # _evaluate_numeric_binop
+        result = idx + 2.0
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index([3.0, 4.0, 5.0, 6.0, 7.0], dtype=np.float64, name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+        result = idx - 2.0
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index([-1.0, 0.0, 1.0, 2.0, 3.0], dtype=np.float64, name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+        result = idx * 1.0
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index([1.0, 2.0, 3.0, 4.0, 5.0], dtype=np.float64, name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+        result = idx / 2.0
+        assert result.dtype == "f8" and isinstance(result, box)
+        exp = Index([0.5, 1.0, 1.5, 2.0, 2.5], dtype=np.float64, name="x")
+        exp = tm.box_expected(exp, box)
+        tm.assert_equal(result, exp)
+
+    # TODO: add more dtypes
+    @pytest.mark.parametrize("holder", [Index, Series])
+    @pytest.mark.parametrize("dtype", [np.int64, np.uint64, np.float64])
+    def test_ufunc_multiple_return_values(self, holder, dtype):
+        obj = holder([1, 2, 3], dtype=dtype, name="x")
+        box = Series if holder is Series else Index
+
+        result = np.modf(obj)
+        assert isinstance(result, tuple)
+        exp1 = Index([0.0, 0.0, 0.0], dtype=np.float64, name="x")
+        exp2 = Index([1.0, 2.0, 3.0], dtype=np.float64, name="x")
+        tm.assert_equal(result[0], tm.box_expected(exp1, box))
+        tm.assert_equal(result[1], tm.box_expected(exp2, box))
+
+    def test_ufunc_at(self):
+        s = Series([0, 1, 2], index=[1, 2, 3], name="x")
+        np.add.at(s, [0, 2], 10)
+        expected = Series([10, 1, 12], index=[1, 2, 3], name="x")
+        tm.assert_series_equal(s, expected)
+
+
+class TestObjectDtypeEquivalence:
+    # Tests that arithmetic operations match operations executed elementwise
+
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_numarr_with_dtype_add_nan(self, dtype, box_with_array):
+        box = box_with_array
+        ser = Series([1, 2, 3], dtype=dtype)
+        expected = Series([np.nan, np.nan, np.nan], dtype=dtype)
+
+        ser = tm.box_expected(ser, box)
+        expected = tm.box_expected(expected, box)
+
+        result = np.nan + ser
+        tm.assert_equal(result, expected)
+
+        result = ser + np.nan
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_numarr_with_dtype_add_int(self, dtype, box_with_array):
+        box = box_with_array
+        ser = Series([1, 2, 3], dtype=dtype)
+        expected = Series([2, 3, 4], dtype=dtype)
+
+        ser = tm.box_expected(ser, box)
+        expected = tm.box_expected(expected, box)
+
+        result = 1 + ser
+        tm.assert_equal(result, expected)
+
+        result = ser + 1
+        tm.assert_equal(result, expected)
+
+    # TODO: moved from tests.series.test_operators; needs cleanup
+    @pytest.mark.parametrize(
+        "op",
+        [operator.add, operator.sub, operator.mul, operator.truediv, operator.floordiv],
+    )
+    def test_operators_reverse_object(self, op):
+        # GH#56
+        arr = Series(
+            np.random.default_rng(2).standard_normal(10),
+            index=np.arange(10),
+            dtype=object,
+        )
+
+        result = op(1.0, arr)
+        expected = op(1.0, arr.astype(float))
+        tm.assert_series_equal(result.astype(float), expected)
+
+
+class TestNumericArithmeticUnsorted:
+    # Tests in this class have been moved from type-specific test modules
+    #  but not yet sorted, parametrized, and de-duplicated
+    @pytest.mark.parametrize(
+        "op",
+        [
+            operator.add,
+            operator.sub,
+            operator.mul,
+            operator.floordiv,
+            operator.truediv,
+        ],
+    )
+    @pytest.mark.parametrize(
+        "idx1",
+        [
+            RangeIndex(0, 10, 1),
+            RangeIndex(0, 20, 2),
+            RangeIndex(-10, 10, 2),
+            RangeIndex(5, -5, -1),
+        ],
+    )
+    @pytest.mark.parametrize(
+        "idx2",
+        [
+            RangeIndex(0, 10, 1),
+            RangeIndex(0, 20, 2),
+            RangeIndex(-10, 10, 2),
+            RangeIndex(5, -5, -1),
+        ],
+    )
+    def test_binops_index(self, op, idx1, idx2):
+        idx1 = idx1._rename("foo")
+        idx2 = idx2._rename("bar")
+        result = op(idx1, idx2)
+        expected = op(Index(idx1.to_numpy()), Index(idx2.to_numpy()))
+        tm.assert_index_equal(result, expected, exact="equiv")
+
+    @pytest.mark.parametrize(
+        "op",
+        [
+            operator.add,
+            operator.sub,
+            operator.mul,
+            operator.floordiv,
+            operator.truediv,
+        ],
+    )
+    @pytest.mark.parametrize(
+        "idx",
+        [
+            RangeIndex(0, 10, 1),
+            RangeIndex(0, 20, 2),
+            RangeIndex(-10, 10, 2),
+            RangeIndex(5, -5, -1),
+        ],
+    )
+    @pytest.mark.parametrize("scalar", [-1, 1, 2])
+    def test_binops_index_scalar(self, op, idx, scalar):
+        result = op(idx, scalar)
+        expected = op(Index(idx.to_numpy()), scalar)
+        tm.assert_index_equal(result, expected, exact="equiv")
+
+    @pytest.mark.parametrize("idx1", [RangeIndex(0, 10, 1), RangeIndex(0, 20, 2)])
+    @pytest.mark.parametrize("idx2", [RangeIndex(0, 10, 1), RangeIndex(0, 20, 2)])
+    def test_binops_index_pow(self, idx1, idx2):
+        # numpy does not allow powers of negative integers so test separately
+        # https://github.com/numpy/numpy/pull/8127
+        idx1 = idx1._rename("foo")
+        idx2 = idx2._rename("bar")
+        result = pow(idx1, idx2)
+        expected = pow(Index(idx1.to_numpy()), Index(idx2.to_numpy()))
+        tm.assert_index_equal(result, expected, exact="equiv")
+
+    @pytest.mark.parametrize("idx", [RangeIndex(0, 10, 1), RangeIndex(0, 20, 2)])
+    @pytest.mark.parametrize("scalar", [1, 2])
+    def test_binops_index_scalar_pow(self, idx, scalar):
+        # numpy does not allow powers of negative integers so test separately
+        # https://github.com/numpy/numpy/pull/8127
+        result = pow(idx, scalar)
+        expected = pow(Index(idx.to_numpy()), scalar)
+        tm.assert_index_equal(result, expected, exact="equiv")
+
+    # TODO: divmod?
+    @pytest.mark.parametrize(
+        "op",
+        [
+            operator.add,
+            operator.sub,
+            operator.mul,
+            operator.floordiv,
+            operator.truediv,
+            operator.pow,
+            operator.mod,
+        ],
+    )
+    def test_arithmetic_with_frame_or_series(self, op):
+        # check that we return NotImplemented when operating with Series
+        # or DataFrame
+        index = RangeIndex(5)
+        other = Series(np.random.default_rng(2).standard_normal(5))
+
+        expected = op(Series(index), other)
+        result = op(index, other)
+        tm.assert_series_equal(result, expected)
+
+        other = pd.DataFrame(np.random.default_rng(2).standard_normal((2, 5)))
+        expected = op(pd.DataFrame([index, index]), other)
+        result = op(index, other)
+        tm.assert_frame_equal(result, expected)
+
+    def test_numeric_compat2(self):
+        # validate that we are handling the RangeIndex overrides to numeric ops
+        # and returning RangeIndex where possible
+
+        idx = RangeIndex(0, 10, 2)
+
+        result = idx * 2
+        expected = RangeIndex(0, 20, 4)
+        tm.assert_index_equal(result, expected, exact=True)
+
+        result = idx + 2
+        expected = RangeIndex(2, 12, 2)
+        tm.assert_index_equal(result, expected, exact=True)
+
+        result = idx - 2
+        expected = RangeIndex(-2, 8, 2)
+        tm.assert_index_equal(result, expected, exact=True)
+
+        result = idx / 2
+        expected = RangeIndex(0, 5, 1).astype("float64")
+        tm.assert_index_equal(result, expected, exact=True)
+
+        result = idx / 4
+        expected = RangeIndex(0, 10, 2) / 4
+        tm.assert_index_equal(result, expected, exact=True)
+
+        result = idx // 1
+        expected = idx
+        tm.assert_index_equal(result, expected, exact=True)
+
+        # __mul__
+        result = idx * idx
+        expected = Index(idx.values * idx.values)
+        tm.assert_index_equal(result, expected, exact=True)
+
+        # __pow__
+        idx = RangeIndex(0, 1000, 2)
+        result = idx**2
+        expected = Index(idx._values) ** 2
+        tm.assert_index_equal(Index(result.values), expected, exact=True)
+
+    @pytest.mark.parametrize(
+        "idx, div, expected",
+        [
+            # TODO: add more dtypes
+            (RangeIndex(0, 1000, 2), 2, RangeIndex(0, 500, 1)),
+            (RangeIndex(-99, -201, -3), -3, RangeIndex(33, 67, 1)),
+            (
+                RangeIndex(0, 1000, 1),
+                2,
+                Index(RangeIndex(0, 1000, 1)._values) // 2,
+            ),
+            (
+                RangeIndex(0, 100, 1),
+                2.0,
+                Index(RangeIndex(0, 100, 1)._values) // 2.0,
+            ),
+            (RangeIndex(0), 50, RangeIndex(0)),
+            (RangeIndex(2, 4, 2), 3, RangeIndex(0, 1, 1)),
+            (RangeIndex(-5, -10, -6), 4, RangeIndex(-2, -1, 1)),
+            (RangeIndex(-100, -200, 3), 2, RangeIndex(0)),
+        ],
+    )
+    def test_numeric_compat2_floordiv(self, idx, div, expected):
+        # __floordiv__
+        tm.assert_index_equal(idx // div, expected, exact=True)
+
+    @pytest.mark.parametrize("dtype", [np.int64, np.float64])
+    @pytest.mark.parametrize("delta", [1, 0, -1])
+    def test_addsub_arithmetic(self, dtype, delta):
+        # GH#8142
+        delta = dtype(delta)
+        index = Index([10, 11, 12], dtype=dtype)
+        result = index + delta
+        expected = Index(index.values + delta, dtype=dtype)
+        tm.assert_index_equal(result, expected)
+
+        # this subtraction used to fail
+        result = index - delta
+        expected = Index(index.values - delta, dtype=dtype)
+        tm.assert_index_equal(result, expected)
+
+        tm.assert_index_equal(index + index, 2 * index)
+        tm.assert_index_equal(index - index, 0 * index)
+        assert not (index - index).empty
+
+    def test_pow_nan_with_zero(self, box_with_array):
+        left = Index([np.nan, np.nan, np.nan])
+        right = Index([0, 0, 0])
+        expected = Index([1.0, 1.0, 1.0])
+
+        left = tm.box_expected(left, box_with_array)
+        right = tm.box_expected(right, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = left**right
+        tm.assert_equal(result, expected)
+
+
+def test_fill_value_inf_masking():
+    # GH #27464 make sure we mask 0/1 with Inf and not NaN
+    df = pd.DataFrame({"A": [0, 1, 2], "B": [1.1, None, 1.1]})
+
+    other = pd.DataFrame({"A": [1.1, 1.2, 1.3]}, index=[0, 2, 3])
+
+    result = df.rfloordiv(other, fill_value=1)
+
+    expected = pd.DataFrame(
+        {"A": [np.inf, 1.0, 0.0, 1.0], "B": [0.0, np.nan, 0.0, np.nan]}
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_dataframe_div_silenced():
+    # GH#26793
+    pdf1 = pd.DataFrame(
+        {
+            "A": np.arange(10),
+            "B": [np.nan, 1, 2, 3, 4] * 2,
+            "C": [np.nan] * 10,
+            "D": np.arange(10),
+        },
+        index=list("abcdefghij"),
+        columns=list("ABCD"),
+    )
+    pdf2 = pd.DataFrame(
+        np.random.default_rng(2).standard_normal((10, 4)),
+        index=list("abcdefghjk"),
+        columns=list("ABCX"),
+    )
+    with tm.assert_produces_warning(None):
+        pdf1.div(pdf2, fill_value=0)
+
+
+@pytest.mark.parametrize(
+    "data, expected_data",
+    [([0, 1, 2], [0, 2, 4])],
+)
+def test_integer_array_add_list_like(
+    box_pandas_1d_array, box_1d_array, data, expected_data
+):
+    # GH22606 Verify operators with IntegerArray and list-likes
+    arr = array(data, dtype="Int64")
+    container = box_pandas_1d_array(arr)
+    left = container + box_1d_array(data)
+    right = box_1d_array(data) + container
+
+    if Series in [box_1d_array, box_pandas_1d_array]:
+        cls = Series
+    elif Index in [box_1d_array, box_pandas_1d_array]:
+        cls = Index
+    else:
+        cls = array
+
+    expected = cls(expected_data, dtype="Int64")
+
+    tm.assert_equal(left, expected)
+    tm.assert_equal(right, expected)
+
+
+def test_sub_multiindex_swapped_levels():
+    # GH 9952
+    df = pd.DataFrame(
+        {"a": np.random.default_rng(2).standard_normal(6)},
+        index=pd.MultiIndex.from_product(
+            [["a", "b"], [0, 1, 2]], names=["levA", "levB"]
+        ),
+    )
+    df2 = df.copy()
+    df2.index = df2.index.swaplevel(0, 1)
+    result = df - df2
+    expected = pd.DataFrame([0.0] * 6, columns=["a"], index=df.index)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("power", [1, 2, 5])
+@pytest.mark.parametrize("string_size", [0, 1, 2, 5])
+def test_empty_str_comparison(power, string_size):
+    # GH 37348
+    a = np.array(range(10**power))
+    right = pd.DataFrame(a, dtype=np.int64)
+    left = " " * string_size
+
+    result = right == left
+    expected = pd.DataFrame(np.zeros(right.shape, dtype=bool))
+    tm.assert_frame_equal(result, expected)
+
+
+def test_series_add_sub_with_UInt64():
+    # GH 22023
+    series1 = Series([1, 2, 3])
+    series2 = Series([2, 1, 3], dtype="UInt64")
+
+    result = series1 + series2
+    expected = Series([3, 3, 6], dtype="Float64")
+    tm.assert_series_equal(result, expected)
+
+    result = series1 - series2
+    expected = Series([-1, 1, 0], dtype="Float64")
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_object.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_object.py
new file mode 100644
index 0000000000000000000000000000000000000000..44e485d40ba536ba08fabb8d2f5aa4e439177010
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_object.py
@@ -0,0 +1,414 @@
+# Arithmetic tests for DataFrame/Series/Index/Array classes that should
+# behave identically.
+# Specifically for object dtype
+import datetime
+from decimal import Decimal
+import operator
+
+import numpy as np
+import pytest
+
+import pandas.util._test_decorators as td
+
+import pandas as pd
+from pandas import (
+    Series,
+    Timestamp,
+    option_context,
+)
+import pandas._testing as tm
+from pandas.core import ops
+
+# ------------------------------------------------------------------
+# Comparisons
+
+
+class TestObjectComparisons:
+    def test_comparison_object_numeric_nas(self, comparison_op):
+        ser = Series(np.random.default_rng(2).standard_normal(10), dtype=object)
+        shifted = ser.shift(2)
+
+        func = comparison_op
+
+        result = func(ser, shifted)
+        expected = func(ser.astype(float), shifted.astype(float))
+        tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "infer_string", [False, pytest.param(True, marks=td.skip_if_no("pyarrow"))]
+    )
+    def test_object_comparisons(self, infer_string):
+        with option_context("future.infer_string", infer_string):
+            ser = Series(["a", "b", np.nan, "c", "a"])
+
+            result = ser == "a"
+            expected = Series([True, False, False, False, True])
+            tm.assert_series_equal(result, expected)
+
+            result = ser < "a"
+            expected = Series([False, False, False, False, False])
+            tm.assert_series_equal(result, expected)
+
+            result = ser != "a"
+            expected = -(ser == "a")
+            tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_more_na_comparisons(self, dtype):
+        left = Series(["a", np.nan, "c"], dtype=dtype)
+        right = Series(["a", np.nan, "d"], dtype=dtype)
+
+        result = left == right
+        expected = Series([True, False, False])
+        tm.assert_series_equal(result, expected)
+
+        result = left != right
+        expected = Series([False, True, True])
+        tm.assert_series_equal(result, expected)
+
+        result = left == np.nan
+        expected = Series([False, False, False])
+        tm.assert_series_equal(result, expected)
+
+        result = left != np.nan
+        expected = Series([True, True, True])
+        tm.assert_series_equal(result, expected)
+
+
+# ------------------------------------------------------------------
+# Arithmetic
+
+
+class TestArithmetic:
+    def test_add_period_to_array_of_offset(self):
+        # GH#50162
+        per = pd.Period("2012-1-1", freq="D")
+        pi = pd.period_range("2012-1-1", periods=10, freq="D")
+        idx = per - pi
+
+        expected = pd.Index([x + per for x in idx], dtype=object)
+        result = idx + per
+        tm.assert_index_equal(result, expected)
+
+        result = per + idx
+        tm.assert_index_equal(result, expected)
+
+    # TODO: parametrize
+    def test_pow_ops_object(self):
+        # GH#22922
+        # pow is weird with masking & 1, so testing here
+        a = Series([1, np.nan, 1, np.nan], dtype=object)
+        b = Series([1, np.nan, np.nan, 1], dtype=object)
+        result = a**b
+        expected = Series(a.values**b.values, dtype=object)
+        tm.assert_series_equal(result, expected)
+
+        result = b**a
+        expected = Series(b.values**a.values, dtype=object)
+
+        tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize("op", [operator.add, ops.radd])
+    @pytest.mark.parametrize("other", ["category", "Int64"])
+    def test_add_extension_scalar(self, other, box_with_array, op):
+        # GH#22378
+        # Check that scalars satisfying is_extension_array_dtype(obj)
+        # do not incorrectly try to dispatch to an ExtensionArray operation
+
+        arr = Series(["a", "b", "c"])
+        expected = Series([op(x, other) for x in arr])
+
+        arr = tm.box_expected(arr, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = op(arr, other)
+        tm.assert_equal(result, expected)
+
+    def test_objarr_add_str(self, box_with_array):
+        ser = Series(["x", np.nan, "x"])
+        expected = Series(["xa", np.nan, "xa"])
+
+        ser = tm.box_expected(ser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = ser + "a"
+        tm.assert_equal(result, expected)
+
+    def test_objarr_radd_str(self, box_with_array):
+        ser = Series(["x", np.nan, "x"])
+        expected = Series(["ax", np.nan, "ax"])
+
+        ser = tm.box_expected(ser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = "a" + ser
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "data",
+        [
+            [1, 2, 3],
+            [1.1, 2.2, 3.3],
+            [Timestamp("2011-01-01"), Timestamp("2011-01-02"), pd.NaT],
+            ["x", "y", 1],
+        ],
+    )
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_objarr_radd_str_invalid(self, dtype, data, box_with_array):
+        ser = Series(data, dtype=dtype)
+
+        ser = tm.box_expected(ser, box_with_array)
+        msg = "|".join(
+            [
+                "can only concatenate str",
+                "did not contain a loop with signature matching types",
+                "unsupported operand type",
+                "must be str",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            "foo_" + ser
+
+    @pytest.mark.parametrize("op", [operator.add, ops.radd, operator.sub, ops.rsub])
+    def test_objarr_add_invalid(self, op, box_with_array):
+        # invalid ops
+        box = box_with_array
+
+        obj_ser = Series(list("abc"), dtype=object, name="objects")
+
+        obj_ser = tm.box_expected(obj_ser, box)
+        msg = "|".join(
+            [
+                "can only concatenate str",
+                "unsupported operand type",
+                "must be str",
+                "has no kernel",
+                "operation 'add' not supported",
+                "operation 'radd' not supported",
+                "operation 'sub' not supported",
+                "operation 'rsub' not supported",
+            ]
+        )
+        with pytest.raises(Exception, match=msg):
+            op(obj_ser, 1)
+        with pytest.raises(Exception, match=msg):
+            op(obj_ser, np.array(1, dtype=np.int64))
+
+    # TODO: Moved from tests.series.test_operators; needs cleanup
+    def test_operators_na_handling(self):
+        ser = Series(["foo", "bar", "baz", np.nan])
+        result = "prefix_" + ser
+        expected = Series(["prefix_foo", "prefix_bar", "prefix_baz", np.nan])
+        tm.assert_series_equal(result, expected)
+
+        result = ser + "_suffix"
+        expected = Series(["foo_suffix", "bar_suffix", "baz_suffix", np.nan])
+        tm.assert_series_equal(result, expected)
+
+    # TODO: parametrize over box
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_series_with_dtype_radd_timedelta(self, dtype):
+        # note this test is _not_ aimed at timedelta64-dtyped Series
+        # as of 2.0 we retain object dtype when ser.dtype == object
+        ser = Series(
+            [pd.Timedelta("1 days"), pd.Timedelta("2 days"), pd.Timedelta("3 days")],
+            dtype=dtype,
+        )
+        expected = Series(
+            [pd.Timedelta("4 days"), pd.Timedelta("5 days"), pd.Timedelta("6 days")],
+            dtype=dtype,
+        )
+
+        result = pd.Timedelta("3 days") + ser
+        tm.assert_series_equal(result, expected)
+
+        result = ser + pd.Timedelta("3 days")
+        tm.assert_series_equal(result, expected)
+
+    # TODO: cleanup & parametrize over box
+    def test_mixed_timezone_series_ops_object(self):
+        # GH#13043
+        ser = Series(
+            [
+                Timestamp("2015-01-01", tz="US/Eastern"),
+                Timestamp("2015-01-01", tz="Asia/Tokyo"),
+            ],
+            name="xxx",
+        )
+        assert ser.dtype == object
+
+        exp = Series(
+            [
+                Timestamp("2015-01-02", tz="US/Eastern"),
+                Timestamp("2015-01-02", tz="Asia/Tokyo"),
+            ],
+            name="xxx",
+        )
+        tm.assert_series_equal(ser + pd.Timedelta("1 days"), exp)
+        tm.assert_series_equal(pd.Timedelta("1 days") + ser, exp)
+
+        # object series & object series
+        ser2 = Series(
+            [
+                Timestamp("2015-01-03", tz="US/Eastern"),
+                Timestamp("2015-01-05", tz="Asia/Tokyo"),
+            ],
+            name="xxx",
+        )
+        assert ser2.dtype == object
+        exp = Series(
+            [pd.Timedelta("2 days"), pd.Timedelta("4 days")], name="xxx", dtype=object
+        )
+        tm.assert_series_equal(ser2 - ser, exp)
+        tm.assert_series_equal(ser - ser2, -exp)
+
+        ser = Series(
+            [pd.Timedelta("01:00:00"), pd.Timedelta("02:00:00")],
+            name="xxx",
+            dtype=object,
+        )
+        assert ser.dtype == object
+
+        exp = Series(
+            [pd.Timedelta("01:30:00"), pd.Timedelta("02:30:00")],
+            name="xxx",
+            dtype=object,
+        )
+        tm.assert_series_equal(ser + pd.Timedelta("00:30:00"), exp)
+        tm.assert_series_equal(pd.Timedelta("00:30:00") + ser, exp)
+
+    # TODO: cleanup & parametrize over box
+    def test_iadd_preserves_name(self):
+        # GH#17067, GH#19723 __iadd__ and __isub__ should preserve index name
+        ser = Series([1, 2, 3])
+        ser.index.name = "foo"
+
+        ser.index += 1
+        assert ser.index.name == "foo"
+
+        ser.index -= 1
+        assert ser.index.name == "foo"
+
+    def test_add_string(self):
+        # from bug report
+        index = pd.Index(["a", "b", "c"])
+        index2 = index + "foo"
+
+        assert "a" not in index2
+        assert "afoo" in index2
+
+    def test_iadd_string(self):
+        index = pd.Index(["a", "b", "c"])
+        # doesn't fail test unless there is a check before `+=`
+        assert "a" in index
+
+        index += "_x"
+        assert "a_x" in index
+
+    def test_add(self):
+        index = pd.Index([str(i) for i in range(10)])
+        expected = pd.Index(index.values * 2)
+        tm.assert_index_equal(index + index, expected)
+        tm.assert_index_equal(index + index.tolist(), expected)
+        tm.assert_index_equal(index.tolist() + index, expected)
+
+        # test add and radd
+        index = pd.Index(list("abc"))
+        expected = pd.Index(["a1", "b1", "c1"])
+        tm.assert_index_equal(index + "1", expected)
+        expected = pd.Index(["1a", "1b", "1c"])
+        tm.assert_index_equal("1" + index, expected)
+
+    def test_sub_fail(self):
+        index = pd.Index([str(i) for i in range(10)])
+
+        msg = "unsupported operand type|Cannot broadcast|sub' not supported"
+        with pytest.raises(TypeError, match=msg):
+            index - "a"
+        with pytest.raises(TypeError, match=msg):
+            index - index
+        with pytest.raises(TypeError, match=msg):
+            index - index.tolist()
+        with pytest.raises(TypeError, match=msg):
+            index.tolist() - index
+
+    def test_sub_object(self):
+        # GH#19369
+        index = pd.Index([Decimal(1), Decimal(2)])
+        expected = pd.Index([Decimal(0), Decimal(1)])
+
+        result = index - Decimal(1)
+        tm.assert_index_equal(result, expected)
+
+        result = index - pd.Index([Decimal(1), Decimal(1)])
+        tm.assert_index_equal(result, expected)
+
+        msg = "unsupported operand type"
+        with pytest.raises(TypeError, match=msg):
+            index - "foo"
+
+        with pytest.raises(TypeError, match=msg):
+            index - np.array([2, "foo"], dtype=object)
+
+    def test_rsub_object(self, fixed_now_ts):
+        # GH#19369
+        index = pd.Index([Decimal(1), Decimal(2)])
+        expected = pd.Index([Decimal(1), Decimal(0)])
+
+        result = Decimal(2) - index
+        tm.assert_index_equal(result, expected)
+
+        result = np.array([Decimal(2), Decimal(2)]) - index
+        tm.assert_index_equal(result, expected)
+
+        msg = "unsupported operand type"
+        with pytest.raises(TypeError, match=msg):
+            "foo" - index
+
+        with pytest.raises(TypeError, match=msg):
+            np.array([True, fixed_now_ts]) - index
+
+
+class MyIndex(pd.Index):
+    # Simple index subclass that tracks ops calls.
+
+    _calls: int
+
+    @classmethod
+    def _simple_new(cls, values, name=None, dtype=None):
+        result = object.__new__(cls)
+        result._data = values
+        result._name = name
+        result._calls = 0
+        result._reset_identity()
+
+        return result
+
+    def __add__(self, other):
+        self._calls += 1
+        return self._simple_new(self._data)
+
+    def __radd__(self, other):
+        return self.__add__(other)
+
+
+@pytest.mark.parametrize(
+    "other",
+    [
+        [datetime.timedelta(1), datetime.timedelta(2)],
+        [datetime.datetime(2000, 1, 1), datetime.datetime(2000, 1, 2)],
+        [pd.Period("2000"), pd.Period("2001")],
+        ["a", "b"],
+    ],
+    ids=["timedelta", "datetime", "period", "object"],
+)
+def test_index_ops_defer_to_unknown_subclasses(other):
+    # https://github.com/pandas-dev/pandas/issues/31109
+    values = np.array(
+        [datetime.date(2000, 1, 1), datetime.date(2000, 1, 2)], dtype=object
+    )
+    a = MyIndex._simple_new(values)
+    other = pd.Index(other)
+    result = other + a
+    assert isinstance(result, MyIndex)
+    assert a._calls == 1
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_period.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_period.py
new file mode 100644
index 0000000000000000000000000000000000000000..5535fe8ff928d10b994bd6556229e0163a358ab0
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_period.py
@@ -0,0 +1,1675 @@
+# Arithmetic tests for DataFrame/Series/Index/Array classes that should
+# behave identically.
+# Specifically for Period dtype
+import operator
+
+import numpy as np
+import pytest
+
+from pandas._libs.tslibs import (
+    IncompatibleFrequency,
+    Period,
+    Timestamp,
+    to_offset,
+)
+from pandas.errors import PerformanceWarning
+
+import pandas as pd
+from pandas import (
+    PeriodIndex,
+    Series,
+    Timedelta,
+    TimedeltaIndex,
+    period_range,
+)
+import pandas._testing as tm
+from pandas.core import ops
+from pandas.core.arrays import TimedeltaArray
+from pandas.tests.arithmetic.common import (
+    assert_invalid_addsub_type,
+    assert_invalid_comparison,
+    get_upcast_box,
+)
+
+_common_mismatch = [
+    pd.offsets.YearBegin(2),
+    pd.offsets.MonthBegin(1),
+    pd.offsets.Minute(),
+]
+
+
+@pytest.fixture(
+    params=[
+        Timedelta(minutes=30).to_pytimedelta(),
+        np.timedelta64(30, "s"),
+        Timedelta(seconds=30),
+    ]
+    + _common_mismatch
+)
+def not_hourly(request):
+    """
+    Several timedelta-like and DateOffset instances that are _not_
+    compatible with Hourly frequencies.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        np.timedelta64(365, "D"),
+        Timedelta(days=365).to_pytimedelta(),
+        Timedelta(days=365),
+    ]
+    + _common_mismatch
+)
+def mismatched_freq(request):
+    """
+    Several timedelta-like and DateOffset instances that are _not_
+    compatible with Monthly or Annual frequencies.
+    """
+    return request.param
+
+
+# ------------------------------------------------------------------
+# Comparisons
+
+
+class TestPeriodArrayLikeComparisons:
+    # Comparison tests for PeriodDtype vectors fully parametrized over
+    #  DataFrame/Series/PeriodIndex/PeriodArray.  Ideally all comparison
+    #  tests will eventually end up here.
+
+    @pytest.mark.parametrize("other", ["2017", Period("2017", freq="D")])
+    def test_eq_scalar(self, other, box_with_array):
+        idx = PeriodIndex(["2017", "2017", "2018"], freq="D")
+        idx = tm.box_expected(idx, box_with_array)
+        xbox = get_upcast_box(idx, other, True)
+
+        expected = np.array([True, True, False])
+        expected = tm.box_expected(expected, xbox)
+
+        result = idx == other
+
+        tm.assert_equal(result, expected)
+
+    def test_compare_zerodim(self, box_with_array):
+        # GH#26689 make sure we unbox zero-dimensional arrays
+
+        pi = period_range("2000", periods=4)
+        other = np.array(pi.to_numpy()[0])
+
+        pi = tm.box_expected(pi, box_with_array)
+        xbox = get_upcast_box(pi, other, True)
+
+        result = pi <= other
+        expected = np.array([True, False, False, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "scalar",
+        [
+            "foo",
+            Timestamp("2021-01-01"),
+            Timedelta(days=4),
+            9,
+            9.5,
+            2000,  # specifically don't consider 2000 to match Period("2000", "D")
+            False,
+            None,
+        ],
+    )
+    def test_compare_invalid_scalar(self, box_with_array, scalar):
+        # GH#28980
+        # comparison with scalar that cannot be interpreted as a Period
+        pi = period_range("2000", periods=4)
+        parr = tm.box_expected(pi, box_with_array)
+        assert_invalid_comparison(parr, scalar, box_with_array)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            pd.date_range("2000", periods=4).array,
+            pd.timedelta_range("1D", periods=4).array,
+            np.arange(4),
+            np.arange(4).astype(np.float64),
+            list(range(4)),
+            # match Period semantics by not treating integers as Periods
+            [2000, 2001, 2002, 2003],
+            np.arange(2000, 2004),
+            np.arange(2000, 2004).astype(object),
+            pd.Index([2000, 2001, 2002, 2003]),
+        ],
+    )
+    def test_compare_invalid_listlike(self, box_with_array, other):
+        pi = period_range("2000", periods=4)
+        parr = tm.box_expected(pi, box_with_array)
+        assert_invalid_comparison(parr, other, box_with_array)
+
+    @pytest.mark.parametrize("other_box", [list, np.array, lambda x: x.astype(object)])
+    def test_compare_object_dtype(self, box_with_array, other_box):
+        pi = period_range("2000", periods=5)
+        parr = tm.box_expected(pi, box_with_array)
+
+        other = other_box(pi)
+        xbox = get_upcast_box(parr, other, True)
+
+        expected = np.array([True, True, True, True, True])
+        expected = tm.box_expected(expected, xbox)
+
+        result = parr == other
+        tm.assert_equal(result, expected)
+        result = parr <= other
+        tm.assert_equal(result, expected)
+        result = parr >= other
+        tm.assert_equal(result, expected)
+
+        result = parr != other
+        tm.assert_equal(result, ~expected)
+        result = parr < other
+        tm.assert_equal(result, ~expected)
+        result = parr > other
+        tm.assert_equal(result, ~expected)
+
+        other = other_box(pi[::-1])
+
+        expected = np.array([False, False, True, False, False])
+        expected = tm.box_expected(expected, xbox)
+        result = parr == other
+        tm.assert_equal(result, expected)
+
+        expected = np.array([True, True, True, False, False])
+        expected = tm.box_expected(expected, xbox)
+        result = parr <= other
+        tm.assert_equal(result, expected)
+
+        expected = np.array([False, False, True, True, True])
+        expected = tm.box_expected(expected, xbox)
+        result = parr >= other
+        tm.assert_equal(result, expected)
+
+        expected = np.array([True, True, False, True, True])
+        expected = tm.box_expected(expected, xbox)
+        result = parr != other
+        tm.assert_equal(result, expected)
+
+        expected = np.array([True, True, False, False, False])
+        expected = tm.box_expected(expected, xbox)
+        result = parr < other
+        tm.assert_equal(result, expected)
+
+        expected = np.array([False, False, False, True, True])
+        expected = tm.box_expected(expected, xbox)
+        result = parr > other
+        tm.assert_equal(result, expected)
+
+
+class TestPeriodIndexComparisons:
+    # TODO: parameterize over boxes
+
+    def test_pi_cmp_period(self):
+        idx = period_range("2007-01", periods=20, freq="M")
+        per = idx[10]
+
+        result = idx < per
+        exp = idx.values < idx.values[10]
+        tm.assert_numpy_array_equal(result, exp)
+
+        # Tests Period.__richcmp__ against ndarray[object, ndim=2]
+        result = idx.values.reshape(10, 2) < per
+        tm.assert_numpy_array_equal(result, exp.reshape(10, 2))
+
+        # Tests Period.__richcmp__ against ndarray[object, ndim=0]
+        result = idx < np.array(per)
+        tm.assert_numpy_array_equal(result, exp)
+
+    # TODO: moved from test_datetime64; de-duplicate with version below
+    def test_parr_cmp_period_scalar2(self, box_with_array):
+        pi = period_range("2000-01-01", periods=10, freq="D")
+
+        val = pi[3]
+        expected = [x > val for x in pi]
+
+        ser = tm.box_expected(pi, box_with_array)
+        xbox = get_upcast_box(ser, val, True)
+
+        expected = tm.box_expected(expected, xbox)
+        result = ser > val
+        tm.assert_equal(result, expected)
+
+        val = pi[5]
+        result = ser > val
+        expected = [x > val for x in pi]
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize("freq", ["M", "2M", "3M"])
+    def test_parr_cmp_period_scalar(self, freq, box_with_array):
+        # GH#13200
+        base = PeriodIndex(["2011-01", "2011-02", "2011-03", "2011-04"], freq=freq)
+        base = tm.box_expected(base, box_with_array)
+        per = Period("2011-02", freq=freq)
+        xbox = get_upcast_box(base, per, True)
+
+        exp = np.array([False, True, False, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base == per, exp)
+        tm.assert_equal(per == base, exp)
+
+        exp = np.array([True, False, True, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base != per, exp)
+        tm.assert_equal(per != base, exp)
+
+        exp = np.array([False, False, True, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base > per, exp)
+        tm.assert_equal(per < base, exp)
+
+        exp = np.array([True, False, False, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base < per, exp)
+        tm.assert_equal(per > base, exp)
+
+        exp = np.array([False, True, True, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base >= per, exp)
+        tm.assert_equal(per <= base, exp)
+
+        exp = np.array([True, True, False, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base <= per, exp)
+        tm.assert_equal(per >= base, exp)
+
+    @pytest.mark.parametrize("freq", ["M", "2M", "3M"])
+    def test_parr_cmp_pi(self, freq, box_with_array):
+        # GH#13200
+        base = PeriodIndex(["2011-01", "2011-02", "2011-03", "2011-04"], freq=freq)
+        base = tm.box_expected(base, box_with_array)
+
+        # TODO: could also box idx?
+        idx = PeriodIndex(["2011-02", "2011-01", "2011-03", "2011-05"], freq=freq)
+
+        xbox = get_upcast_box(base, idx, True)
+
+        exp = np.array([False, False, True, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base == idx, exp)
+
+        exp = np.array([True, True, False, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base != idx, exp)
+
+        exp = np.array([False, True, False, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base > idx, exp)
+
+        exp = np.array([True, False, False, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base < idx, exp)
+
+        exp = np.array([False, True, True, False])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base >= idx, exp)
+
+        exp = np.array([True, False, True, True])
+        exp = tm.box_expected(exp, xbox)
+        tm.assert_equal(base <= idx, exp)
+
+    @pytest.mark.parametrize("freq", ["M", "2M", "3M"])
+    def test_parr_cmp_pi_mismatched_freq(self, freq, box_with_array):
+        # GH#13200
+        # different base freq
+        base = PeriodIndex(["2011-01", "2011-02", "2011-03", "2011-04"], freq=freq)
+        base = tm.box_expected(base, box_with_array)
+
+        msg = rf"Invalid comparison between dtype=period\[{freq}\] and Period"
+        with pytest.raises(TypeError, match=msg):
+            base <= Period("2011", freq="Y")
+
+        with pytest.raises(TypeError, match=msg):
+            Period("2011", freq="Y") >= base
+
+        # TODO: Could parametrize over boxes for idx?
+        idx = PeriodIndex(["2011", "2012", "2013", "2014"], freq="Y")
+        rev_msg = r"Invalid comparison between dtype=period\[Y-DEC\] and PeriodArray"
+        idx_msg = rev_msg if box_with_array in [tm.to_array, pd.array] else msg
+        with pytest.raises(TypeError, match=idx_msg):
+            base <= idx
+
+        # Different frequency
+        msg = rf"Invalid comparison between dtype=period\[{freq}\] and Period"
+        with pytest.raises(TypeError, match=msg):
+            base <= Period("2011", freq="4M")
+
+        with pytest.raises(TypeError, match=msg):
+            Period("2011", freq="4M") >= base
+
+        idx = PeriodIndex(["2011", "2012", "2013", "2014"], freq="4M")
+        rev_msg = r"Invalid comparison between dtype=period\[4M\] and PeriodArray"
+        idx_msg = rev_msg if box_with_array in [tm.to_array, pd.array] else msg
+        with pytest.raises(TypeError, match=idx_msg):
+            base <= idx
+
+    @pytest.mark.parametrize("freq", ["M", "2M", "3M"])
+    def test_pi_cmp_nat(self, freq):
+        idx1 = PeriodIndex(["2011-01", "2011-02", "NaT", "2011-05"], freq=freq)
+        per = idx1[1]
+
+        result = idx1 > per
+        exp = np.array([False, False, False, True])
+        tm.assert_numpy_array_equal(result, exp)
+        result = per < idx1
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 == pd.NaT
+        exp = np.array([False, False, False, False])
+        tm.assert_numpy_array_equal(result, exp)
+        result = pd.NaT == idx1
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 != pd.NaT
+        exp = np.array([True, True, True, True])
+        tm.assert_numpy_array_equal(result, exp)
+        result = pd.NaT != idx1
+        tm.assert_numpy_array_equal(result, exp)
+
+        idx2 = PeriodIndex(["2011-02", "2011-01", "2011-04", "NaT"], freq=freq)
+        result = idx1 < idx2
+        exp = np.array([True, False, False, False])
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 == idx2
+        exp = np.array([False, False, False, False])
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 != idx2
+        exp = np.array([True, True, True, True])
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 == idx1
+        exp = np.array([True, True, False, True])
+        tm.assert_numpy_array_equal(result, exp)
+
+        result = idx1 != idx1
+        exp = np.array([False, False, True, False])
+        tm.assert_numpy_array_equal(result, exp)
+
+    @pytest.mark.parametrize("freq", ["M", "2M", "3M"])
+    def test_pi_cmp_nat_mismatched_freq_raises(self, freq):
+        idx1 = PeriodIndex(["2011-01", "2011-02", "NaT", "2011-05"], freq=freq)
+
+        diff = PeriodIndex(["2011-02", "2011-01", "2011-04", "NaT"], freq="4M")
+        msg = rf"Invalid comparison between dtype=period\[{freq}\] and PeriodArray"
+        with pytest.raises(TypeError, match=msg):
+            idx1 > diff
+
+        result = idx1 == diff
+        expected = np.array([False, False, False, False], dtype=bool)
+        tm.assert_numpy_array_equal(result, expected)
+
+    # TODO: De-duplicate with test_pi_cmp_nat
+    @pytest.mark.parametrize("dtype", [object, None])
+    def test_comp_nat(self, dtype):
+        left = PeriodIndex([Period("2011-01-01"), pd.NaT, Period("2011-01-03")])
+        right = PeriodIndex([pd.NaT, pd.NaT, Period("2011-01-03")])
+
+        if dtype is not None:
+            left = left.astype(dtype)
+            right = right.astype(dtype)
+
+        result = left == right
+        expected = np.array([False, False, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = left != right
+        expected = np.array([True, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        expected = np.array([False, False, False])
+        tm.assert_numpy_array_equal(left == pd.NaT, expected)
+        tm.assert_numpy_array_equal(pd.NaT == right, expected)
+
+        expected = np.array([True, True, True])
+        tm.assert_numpy_array_equal(left != pd.NaT, expected)
+        tm.assert_numpy_array_equal(pd.NaT != left, expected)
+
+        expected = np.array([False, False, False])
+        tm.assert_numpy_array_equal(left < pd.NaT, expected)
+        tm.assert_numpy_array_equal(pd.NaT > left, expected)
+
+
+class TestPeriodSeriesComparisons:
+    def test_cmp_series_period_series_mixed_freq(self):
+        # GH#13200
+        base = Series(
+            [
+                Period("2011", freq="Y"),
+                Period("2011-02", freq="M"),
+                Period("2013", freq="Y"),
+                Period("2011-04", freq="M"),
+            ]
+        )
+
+        ser = Series(
+            [
+                Period("2012", freq="Y"),
+                Period("2011-01", freq="M"),
+                Period("2013", freq="Y"),
+                Period("2011-05", freq="M"),
+            ]
+        )
+
+        exp = Series([False, False, True, False])
+        tm.assert_series_equal(base == ser, exp)
+
+        exp = Series([True, True, False, True])
+        tm.assert_series_equal(base != ser, exp)
+
+        exp = Series([False, True, False, False])
+        tm.assert_series_equal(base > ser, exp)
+
+        exp = Series([True, False, False, True])
+        tm.assert_series_equal(base < ser, exp)
+
+        exp = Series([False, True, True, False])
+        tm.assert_series_equal(base >= ser, exp)
+
+        exp = Series([True, False, True, True])
+        tm.assert_series_equal(base <= ser, exp)
+
+
+class TestPeriodIndexSeriesComparisonConsistency:
+    """Test PeriodIndex and Period Series Ops consistency"""
+
+    # TODO: needs parametrization+de-duplication
+
+    def _check(self, values, func, expected):
+        # Test PeriodIndex and Period Series Ops consistency
+
+        idx = PeriodIndex(values)
+        result = func(idx)
+
+        # check that we don't pass an unwanted type to tm.assert_equal
+        assert isinstance(expected, (pd.Index, np.ndarray))
+        tm.assert_equal(result, expected)
+
+        s = Series(values)
+        result = func(s)
+
+        exp = Series(expected, name=values.name)
+        tm.assert_series_equal(result, exp)
+
+    def test_pi_comp_period(self):
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+        per = idx[2]
+
+        f = lambda x: x == per
+        exp = np.array([False, False, True, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: per == x
+        self._check(idx, f, exp)
+
+        f = lambda x: x != per
+        exp = np.array([True, True, False, True], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: per != x
+        self._check(idx, f, exp)
+
+        f = lambda x: per >= x
+        exp = np.array([True, True, True, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+        f = lambda x: x > per
+        exp = np.array([False, False, False, True], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+        f = lambda x: per >= x
+        exp = np.array([True, True, True, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+    def test_pi_comp_period_nat(self):
+        idx = PeriodIndex(
+            ["2011-01", "NaT", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+        per = idx[2]
+
+        f = lambda x: x == per
+        exp = np.array([False, False, True, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: per == x
+        self._check(idx, f, exp)
+
+        f = lambda x: x == pd.NaT
+        exp = np.array([False, False, False, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: pd.NaT == x
+        self._check(idx, f, exp)
+
+        f = lambda x: x != per
+        exp = np.array([True, True, False, True], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: per != x
+        self._check(idx, f, exp)
+
+        f = lambda x: x != pd.NaT
+        exp = np.array([True, True, True, True], dtype=np.bool_)
+        self._check(idx, f, exp)
+        f = lambda x: pd.NaT != x
+        self._check(idx, f, exp)
+
+        f = lambda x: per >= x
+        exp = np.array([True, False, True, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+        f = lambda x: x < per
+        exp = np.array([True, False, False, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+        f = lambda x: x > pd.NaT
+        exp = np.array([False, False, False, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+        f = lambda x: pd.NaT >= x
+        exp = np.array([False, False, False, False], dtype=np.bool_)
+        self._check(idx, f, exp)
+
+
+# ------------------------------------------------------------------
+# Arithmetic
+
+
+class TestPeriodFrameArithmetic:
+    def test_ops_frame_period(self):
+        # GH#13043
+        df = pd.DataFrame(
+            {
+                "A": [Period("2015-01", freq="M"), Period("2015-02", freq="M")],
+                "B": [Period("2014-01", freq="M"), Period("2014-02", freq="M")],
+            }
+        )
+        assert df["A"].dtype == "Period[M]"
+        assert df["B"].dtype == "Period[M]"
+
+        p = Period("2015-03", freq="M")
+        off = p.freq
+        # dtype will be object because of original dtype
+        exp = pd.DataFrame(
+            {
+                "A": np.array([2 * off, 1 * off], dtype=object),
+                "B": np.array([14 * off, 13 * off], dtype=object),
+            }
+        )
+        tm.assert_frame_equal(p - df, exp)
+        tm.assert_frame_equal(df - p, -1 * exp)
+
+        df2 = pd.DataFrame(
+            {
+                "A": [Period("2015-05", freq="M"), Period("2015-06", freq="M")],
+                "B": [Period("2015-05", freq="M"), Period("2015-06", freq="M")],
+            }
+        )
+        assert df2["A"].dtype == "Period[M]"
+        assert df2["B"].dtype == "Period[M]"
+
+        exp = pd.DataFrame(
+            {
+                "A": np.array([4 * off, 4 * off], dtype=object),
+                "B": np.array([16 * off, 16 * off], dtype=object),
+            }
+        )
+        tm.assert_frame_equal(df2 - df, exp)
+        tm.assert_frame_equal(df - df2, -1 * exp)
+
+
+class TestPeriodIndexArithmetic:
+    # ---------------------------------------------------------------
+    # __add__/__sub__ with PeriodIndex
+    # PeriodIndex + other is defined for integers and timedelta-like others
+    # PeriodIndex - other is defined for integers, timedelta-like others,
+    #   and PeriodIndex (with matching freq)
+
+    def test_parr_add_iadd_parr_raises(self, box_with_array):
+        rng = period_range("1/1/2000", freq="D", periods=5)
+        other = period_range("1/6/2000", freq="D", periods=5)
+        # TODO: parametrize over boxes for other?
+
+        rng = tm.box_expected(rng, box_with_array)
+        # An earlier implementation of PeriodIndex addition performed
+        # a set operation (union).  This has since been changed to
+        # raise a TypeError. See GH#14164 and GH#13077 for historical
+        # reference.
+        msg = r"unsupported operand type\(s\) for \+: .* and .*"
+        with pytest.raises(TypeError, match=msg):
+            rng + other
+
+        with pytest.raises(TypeError, match=msg):
+            rng += other
+
+    def test_pi_sub_isub_pi(self):
+        # GH#20049
+        # For historical reference see GH#14164, GH#13077.
+        # PeriodIndex subtraction originally performed set difference,
+        # then changed to raise TypeError before being implemented in GH#20049
+        rng = period_range("1/1/2000", freq="D", periods=5)
+        other = period_range("1/6/2000", freq="D", periods=5)
+
+        off = rng.freq
+        expected = pd.Index([-5 * off] * 5)
+        result = rng - other
+        tm.assert_index_equal(result, expected)
+
+        rng -= other
+        tm.assert_index_equal(rng, expected)
+
+    def test_pi_sub_pi_with_nat(self):
+        rng = period_range("1/1/2000", freq="D", periods=5)
+        other = rng[1:].insert(0, pd.NaT)
+        assert other[1:].equals(rng[1:])
+
+        result = rng - other
+        off = rng.freq
+        expected = pd.Index([pd.NaT, 0 * off, 0 * off, 0 * off, 0 * off])
+        tm.assert_index_equal(result, expected)
+
+    def test_parr_sub_pi_mismatched_freq(self, box_with_array, box_with_array2):
+        rng = period_range("1/1/2000", freq="D", periods=5)
+        other = period_range("1/6/2000", freq="h", periods=5)
+
+        rng = tm.box_expected(rng, box_with_array)
+        other = tm.box_expected(other, box_with_array2)
+        msg = r"Input has different freq=[hD] from PeriodArray\(freq=[Dh]\)"
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng - other
+
+    @pytest.mark.parametrize("n", [1, 2, 3, 4])
+    def test_sub_n_gt_1_ticks(self, tick_classes, n):
+        # GH 23878
+        p1_d = "19910905"
+        p2_d = "19920406"
+        p1 = PeriodIndex([p1_d], freq=tick_classes(n))
+        p2 = PeriodIndex([p2_d], freq=tick_classes(n))
+
+        expected = PeriodIndex([p2_d], freq=p2.freq.base) - PeriodIndex(
+            [p1_d], freq=p1.freq.base
+        )
+
+        tm.assert_index_equal((p2 - p1), expected)
+
+    @pytest.mark.parametrize("n", [1, 2, 3, 4])
+    @pytest.mark.parametrize(
+        "offset, kwd_name",
+        [
+            (pd.offsets.YearEnd, "month"),
+            (pd.offsets.QuarterEnd, "startingMonth"),
+            (pd.offsets.MonthEnd, None),
+            (pd.offsets.Week, "weekday"),
+        ],
+    )
+    def test_sub_n_gt_1_offsets(self, offset, kwd_name, n):
+        # GH 23878
+        kwds = {kwd_name: 3} if kwd_name is not None else {}
+        p1_d = "19910905"
+        p2_d = "19920406"
+        freq = offset(n, normalize=False, **kwds)
+        p1 = PeriodIndex([p1_d], freq=freq)
+        p2 = PeriodIndex([p2_d], freq=freq)
+
+        result = p2 - p1
+        expected = PeriodIndex([p2_d], freq=freq.base) - PeriodIndex(
+            [p1_d], freq=freq.base
+        )
+
+        tm.assert_index_equal(result, expected)
+
+    # -------------------------------------------------------------
+    # Invalid Operations
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            # datetime scalars
+            Timestamp("2016-01-01"),
+            Timestamp("2016-01-01").to_pydatetime(),
+            Timestamp("2016-01-01").to_datetime64(),
+            # datetime-like arrays
+            pd.date_range("2016-01-01", periods=3, freq="h"),
+            pd.date_range("2016-01-01", periods=3, tz="Europe/Brussels"),
+            pd.date_range("2016-01-01", periods=3, freq="s")._data,
+            pd.date_range("2016-01-01", periods=3, tz="Asia/Tokyo")._data,
+            # Miscellaneous invalid types
+            3.14,
+            np.array([2.0, 3.0, 4.0]),
+        ],
+    )
+    def test_parr_add_sub_invalid(self, other, box_with_array):
+        # GH#23215
+        rng = period_range("1/1/2000", freq="D", periods=3)
+        rng = tm.box_expected(rng, box_with_array)
+
+        msg = "|".join(
+            [
+                r"(:?cannot add PeriodArray and .*)",
+                r"(:?cannot subtract .* from (:?a\s)?.*)",
+                r"(:?unsupported operand type\(s\) for \+: .* and .*)",
+                r"unsupported operand type\(s\) for [+-]: .* and .*",
+            ]
+        )
+        assert_invalid_addsub_type(rng, other, msg)
+        with pytest.raises(TypeError, match=msg):
+            rng + other
+        with pytest.raises(TypeError, match=msg):
+            other + rng
+        with pytest.raises(TypeError, match=msg):
+            rng - other
+        with pytest.raises(TypeError, match=msg):
+            other - rng
+
+    # -----------------------------------------------------------------
+    # __add__/__sub__ with ndarray[datetime64] and ndarray[timedelta64]
+
+    def test_pi_add_sub_td64_array_non_tick_raises(self):
+        rng = period_range("1/1/2000", freq="Q", periods=3)
+        tdi = TimedeltaIndex(["-1 Day", "-1 Day", "-1 Day"])
+        tdarr = tdi.values
+
+        msg = r"Cannot add or subtract timedelta64\[ns\] dtype from period\[Q-DEC\]"
+        with pytest.raises(TypeError, match=msg):
+            rng + tdarr
+        with pytest.raises(TypeError, match=msg):
+            tdarr + rng
+
+        with pytest.raises(TypeError, match=msg):
+            rng - tdarr
+        msg = r"cannot subtract PeriodArray from TimedeltaArray"
+        with pytest.raises(TypeError, match=msg):
+            tdarr - rng
+
+    def test_pi_add_sub_td64_array_tick(self):
+        # PeriodIndex + Timedelta-like is allowed only with
+        #   tick-like frequencies
+        rng = period_range("1/1/2000", freq="90D", periods=3)
+        tdi = TimedeltaIndex(["-1 Day", "-1 Day", "-1 Day"])
+        tdarr = tdi.values
+
+        expected = period_range("12/31/1999", freq="90D", periods=3)
+        result = rng + tdi
+        tm.assert_index_equal(result, expected)
+        result = rng + tdarr
+        tm.assert_index_equal(result, expected)
+        result = tdi + rng
+        tm.assert_index_equal(result, expected)
+        result = tdarr + rng
+        tm.assert_index_equal(result, expected)
+
+        expected = period_range("1/2/2000", freq="90D", periods=3)
+
+        result = rng - tdi
+        tm.assert_index_equal(result, expected)
+        result = rng - tdarr
+        tm.assert_index_equal(result, expected)
+
+        msg = r"cannot subtract .* from .*"
+        with pytest.raises(TypeError, match=msg):
+            tdarr - rng
+
+        with pytest.raises(TypeError, match=msg):
+            tdi - rng
+
+    @pytest.mark.parametrize("pi_freq", ["D", "W", "Q", "h"])
+    @pytest.mark.parametrize("tdi_freq", [None, "h"])
+    def test_parr_sub_td64array(self, box_with_array, tdi_freq, pi_freq):
+        box = box_with_array
+        xbox = box if box not in [pd.array, tm.to_array] else pd.Index
+
+        tdi = TimedeltaIndex(["1 hours", "2 hours"], freq=tdi_freq)
+        dti = Timestamp("2018-03-07 17:16:40") + tdi
+        pi = dti.to_period(pi_freq)
+
+        # TODO: parametrize over box for pi?
+        td64obj = tm.box_expected(tdi, box)
+
+        if pi_freq == "h":
+            result = pi - td64obj
+            expected = (pi.to_timestamp("s") - tdi).to_period(pi_freq)
+            expected = tm.box_expected(expected, xbox)
+            tm.assert_equal(result, expected)
+
+            # Subtract from scalar
+            result = pi[0] - td64obj
+            expected = (pi[0].to_timestamp("s") - tdi).to_period(pi_freq)
+            expected = tm.box_expected(expected, box)
+            tm.assert_equal(result, expected)
+
+        elif pi_freq == "D":
+            # Tick, but non-compatible
+            msg = (
+                "Cannot add/subtract timedelta-like from PeriodArray that is "
+                "not an integer multiple of the PeriodArray's freq."
+            )
+            with pytest.raises(IncompatibleFrequency, match=msg):
+                pi - td64obj
+
+            with pytest.raises(IncompatibleFrequency, match=msg):
+                pi[0] - td64obj
+
+        else:
+            # With non-Tick freq, we could not add timedelta64 array regardless
+            #  of what its resolution is
+            msg = "Cannot add or subtract timedelta64"
+            with pytest.raises(TypeError, match=msg):
+                pi - td64obj
+            with pytest.raises(TypeError, match=msg):
+                pi[0] - td64obj
+
+    # -----------------------------------------------------------------
+    # operations with array/Index of DateOffset objects
+
+    @pytest.mark.parametrize("box", [np.array, pd.Index])
+    def test_pi_add_offset_array(self, box):
+        # GH#18849
+        pi = PeriodIndex([Period("2015Q1"), Period("2016Q2")])
+        offs = box(
+            [
+                pd.offsets.QuarterEnd(n=1, startingMonth=12),
+                pd.offsets.QuarterEnd(n=-2, startingMonth=12),
+            ]
+        )
+        expected = PeriodIndex([Period("2015Q2"), Period("2015Q4")]).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = pi + offs
+        tm.assert_index_equal(res, expected)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res2 = offs + pi
+        tm.assert_index_equal(res2, expected)
+
+        unanchored = np.array([pd.offsets.Hour(n=1), pd.offsets.Minute(n=-2)])
+        # addition/subtraction ops with incompatible offsets should issue
+        # a PerformanceWarning and _then_ raise a TypeError.
+        msg = r"Input cannot be converted to Period\(freq=Q-DEC\)"
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                pi + unanchored
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                unanchored + pi
+
+    @pytest.mark.parametrize("box", [np.array, pd.Index])
+    def test_pi_sub_offset_array(self, box):
+        # GH#18824
+        pi = PeriodIndex([Period("2015Q1"), Period("2016Q2")])
+        other = box(
+            [
+                pd.offsets.QuarterEnd(n=1, startingMonth=12),
+                pd.offsets.QuarterEnd(n=-2, startingMonth=12),
+            ]
+        )
+
+        expected = PeriodIndex([pi[n] - other[n] for n in range(len(pi))])
+        expected = expected.astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = pi - other
+        tm.assert_index_equal(res, expected)
+
+        anchored = box([pd.offsets.MonthEnd(), pd.offsets.Day(n=2)])
+
+        # addition/subtraction ops with anchored offsets should issue
+        # a PerformanceWarning and _then_ raise a TypeError.
+        msg = r"Input has different freq=-1M from Period\(freq=Q-DEC\)"
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                pi - anchored
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                anchored - pi
+
+    def test_pi_add_iadd_int(self, one):
+        # Variants of `one` for #19012
+        rng = period_range("2000-01-01 09:00", freq="h", periods=10)
+        result = rng + one
+        expected = period_range("2000-01-01 10:00", freq="h", periods=10)
+        tm.assert_index_equal(result, expected)
+        rng += one
+        tm.assert_index_equal(rng, expected)
+
+    def test_pi_sub_isub_int(self, one):
+        """
+        PeriodIndex.__sub__ and __isub__ with several representations of
+        the integer 1, e.g. int, np.int64, np.uint8, ...
+        """
+        rng = period_range("2000-01-01 09:00", freq="h", periods=10)
+        result = rng - one
+        expected = period_range("2000-01-01 08:00", freq="h", periods=10)
+        tm.assert_index_equal(result, expected)
+        rng -= one
+        tm.assert_index_equal(rng, expected)
+
+    @pytest.mark.parametrize("five", [5, np.array(5, dtype=np.int64)])
+    def test_pi_sub_intlike(self, five):
+        rng = period_range("2007-01", periods=50)
+
+        result = rng - five
+        exp = rng + (-five)
+        tm.assert_index_equal(result, exp)
+
+    def test_pi_add_sub_int_array_freqn_gt1(self):
+        # GH#47209 test adding array of ints when freq.n > 1 matches
+        #  scalar behavior
+        pi = period_range("2016-01-01", periods=10, freq="2D")
+        arr = np.arange(10)
+        result = pi + arr
+        expected = pd.Index([x + y for x, y in zip(pi, arr)])
+        tm.assert_index_equal(result, expected)
+
+        result = pi - arr
+        expected = pd.Index([x - y for x, y in zip(pi, arr)])
+        tm.assert_index_equal(result, expected)
+
+    def test_pi_sub_isub_offset(self):
+        # offset
+        # DateOffset
+        rng = period_range("2014", "2024", freq="Y")
+        result = rng - pd.offsets.YearEnd(5)
+        expected = period_range("2009", "2019", freq="Y")
+        tm.assert_index_equal(result, expected)
+        rng -= pd.offsets.YearEnd(5)
+        tm.assert_index_equal(rng, expected)
+
+        rng = period_range("2014-01", "2016-12", freq="M")
+        result = rng - pd.offsets.MonthEnd(5)
+        expected = period_range("2013-08", "2016-07", freq="M")
+        tm.assert_index_equal(result, expected)
+
+        rng -= pd.offsets.MonthEnd(5)
+        tm.assert_index_equal(rng, expected)
+
+    @pytest.mark.parametrize("transpose", [True, False])
+    def test_pi_add_offset_n_gt1(self, box_with_array, transpose):
+        # GH#23215
+        # add offset to PeriodIndex with freq.n > 1
+
+        per = Period("2016-01", freq="2M")
+        pi = PeriodIndex([per])
+
+        expected = PeriodIndex(["2016-03"], freq="2M")
+
+        pi = tm.box_expected(pi, box_with_array, transpose=transpose)
+        expected = tm.box_expected(expected, box_with_array, transpose=transpose)
+
+        result = pi + per.freq
+        tm.assert_equal(result, expected)
+
+        result = per.freq + pi
+        tm.assert_equal(result, expected)
+
+    def test_pi_add_offset_n_gt1_not_divisible(self, box_with_array):
+        # GH#23215
+        # PeriodIndex with freq.n > 1 add offset with offset.n % freq.n != 0
+        pi = PeriodIndex(["2016-01"], freq="2M")
+        expected = PeriodIndex(["2016-04"], freq="2M")
+
+        pi = tm.box_expected(pi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = pi + to_offset("3ME")
+        tm.assert_equal(result, expected)
+
+        result = to_offset("3ME") + pi
+        tm.assert_equal(result, expected)
+
+    # ---------------------------------------------------------------
+    # __add__/__sub__ with integer arrays
+
+    @pytest.mark.parametrize("int_holder", [np.array, pd.Index])
+    @pytest.mark.parametrize("op", [operator.add, ops.radd])
+    def test_pi_add_intarray(self, int_holder, op):
+        # GH#19959
+        pi = PeriodIndex([Period("2015Q1"), Period("NaT")])
+        other = int_holder([4, -1])
+
+        result = op(pi, other)
+        expected = PeriodIndex([Period("2016Q1"), Period("NaT")])
+        tm.assert_index_equal(result, expected)
+
+    @pytest.mark.parametrize("int_holder", [np.array, pd.Index])
+    def test_pi_sub_intarray(self, int_holder):
+        # GH#19959
+        pi = PeriodIndex([Period("2015Q1"), Period("NaT")])
+        other = int_holder([4, -1])
+
+        result = pi - other
+        expected = PeriodIndex([Period("2014Q1"), Period("NaT")])
+        tm.assert_index_equal(result, expected)
+
+        msg = r"bad operand type for unary -: 'PeriodArray'"
+        with pytest.raises(TypeError, match=msg):
+            other - pi
+
+    # ---------------------------------------------------------------
+    # Timedelta-like (timedelta, timedelta64, Timedelta, Tick)
+    # TODO: Some of these are misnomers because of non-Tick DateOffsets
+
+    def test_parr_add_timedeltalike_minute_gt1(self, three_days, box_with_array):
+        # GH#23031 adding a time-delta-like offset to a PeriodArray that has
+        # minute frequency with n != 1.  A more general case is tested below
+        # in test_pi_add_timedeltalike_tick_gt1, but here we write out the
+        # expected result more explicitly.
+        other = three_days
+        rng = period_range("2014-05-01", periods=3, freq="2D")
+        rng = tm.box_expected(rng, box_with_array)
+
+        expected = PeriodIndex(["2014-05-04", "2014-05-06", "2014-05-08"], freq="2D")
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = rng + other
+        tm.assert_equal(result, expected)
+
+        result = other + rng
+        tm.assert_equal(result, expected)
+
+        # subtraction
+        expected = PeriodIndex(["2014-04-28", "2014-04-30", "2014-05-02"], freq="2D")
+        expected = tm.box_expected(expected, box_with_array)
+        result = rng - other
+        tm.assert_equal(result, expected)
+
+        msg = "|".join(
+            [
+                r"bad operand type for unary -: 'PeriodArray'",
+                r"cannot subtract PeriodArray from timedelta64\[[hD]\]",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            other - rng
+
+    @pytest.mark.parametrize("freqstr", ["5ns", "5us", "5ms", "5s", "5min", "5h", "5d"])
+    def test_parr_add_timedeltalike_tick_gt1(self, three_days, freqstr, box_with_array):
+        # GH#23031 adding a time-delta-like offset to a PeriodArray that has
+        # tick-like frequency with n != 1
+        other = three_days
+        rng = period_range("2014-05-01", periods=6, freq=freqstr)
+        first = rng[0]
+        rng = tm.box_expected(rng, box_with_array)
+
+        expected = period_range(first + other, periods=6, freq=freqstr)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = rng + other
+        tm.assert_equal(result, expected)
+
+        result = other + rng
+        tm.assert_equal(result, expected)
+
+        # subtraction
+        expected = period_range(first - other, periods=6, freq=freqstr)
+        expected = tm.box_expected(expected, box_with_array)
+        result = rng - other
+        tm.assert_equal(result, expected)
+        msg = "|".join(
+            [
+                r"bad operand type for unary -: 'PeriodArray'",
+                r"cannot subtract PeriodArray from timedelta64\[[hD]\]",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            other - rng
+
+    def test_pi_add_iadd_timedeltalike_daily(self, three_days):
+        # Tick
+        other = three_days
+        rng = period_range("2014-05-01", "2014-05-15", freq="D")
+        expected = period_range("2014-05-04", "2014-05-18", freq="D")
+
+        result = rng + other
+        tm.assert_index_equal(result, expected)
+
+        rng += other
+        tm.assert_index_equal(rng, expected)
+
+    def test_pi_sub_isub_timedeltalike_daily(self, three_days):
+        # Tick-like 3 Days
+        other = three_days
+        rng = period_range("2014-05-01", "2014-05-15", freq="D")
+        expected = period_range("2014-04-28", "2014-05-12", freq="D")
+
+        result = rng - other
+        tm.assert_index_equal(result, expected)
+
+        rng -= other
+        tm.assert_index_equal(rng, expected)
+
+    def test_parr_add_sub_timedeltalike_freq_mismatch_daily(
+        self, not_daily, box_with_array
+    ):
+        other = not_daily
+        rng = period_range("2014-05-01", "2014-05-15", freq="D")
+        rng = tm.box_expected(rng, box_with_array)
+
+        msg = "|".join(
+            [
+                # non-timedelta-like DateOffset
+                "Input has different freq(=.+)? from Period.*?\\(freq=D\\)",
+                # timedelta/td64/Timedelta but not a multiple of 24H
+                "Cannot add/subtract timedelta-like from PeriodArray that is "
+                "not an integer multiple of the PeriodArray's freq.",
+            ]
+        )
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng + other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng += other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng - other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng -= other
+
+    def test_pi_add_iadd_timedeltalike_hourly(self, two_hours):
+        other = two_hours
+        rng = period_range("2014-01-01 10:00", "2014-01-05 10:00", freq="h")
+        expected = period_range("2014-01-01 12:00", "2014-01-05 12:00", freq="h")
+
+        result = rng + other
+        tm.assert_index_equal(result, expected)
+
+        rng += other
+        tm.assert_index_equal(rng, expected)
+
+    def test_parr_add_timedeltalike_mismatched_freq_hourly(
+        self, not_hourly, box_with_array
+    ):
+        other = not_hourly
+        rng = period_range("2014-01-01 10:00", "2014-01-05 10:00", freq="h")
+        rng = tm.box_expected(rng, box_with_array)
+        msg = "|".join(
+            [
+                # non-timedelta-like DateOffset
+                "Input has different freq(=.+)? from Period.*?\\(freq=h\\)",
+                # timedelta/td64/Timedelta but not a multiple of 24H
+                "Cannot add/subtract timedelta-like from PeriodArray that is "
+                "not an integer multiple of the PeriodArray's freq.",
+            ]
+        )
+
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng + other
+
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng += other
+
+    def test_pi_sub_isub_timedeltalike_hourly(self, two_hours):
+        other = two_hours
+        rng = period_range("2014-01-01 10:00", "2014-01-05 10:00", freq="h")
+        expected = period_range("2014-01-01 08:00", "2014-01-05 08:00", freq="h")
+
+        result = rng - other
+        tm.assert_index_equal(result, expected)
+
+        rng -= other
+        tm.assert_index_equal(rng, expected)
+
+    def test_add_iadd_timedeltalike_annual(self):
+        # offset
+        # DateOffset
+        rng = period_range("2014", "2024", freq="Y")
+        result = rng + pd.offsets.YearEnd(5)
+        expected = period_range("2019", "2029", freq="Y")
+        tm.assert_index_equal(result, expected)
+        rng += pd.offsets.YearEnd(5)
+        tm.assert_index_equal(rng, expected)
+
+    def test_pi_add_sub_timedeltalike_freq_mismatch_annual(self, mismatched_freq):
+        other = mismatched_freq
+        rng = period_range("2014", "2024", freq="Y")
+        msg = "Input has different freq(=.+)? from Period.*?\\(freq=Y-DEC\\)"
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng + other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng += other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng - other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng -= other
+
+    def test_pi_add_iadd_timedeltalike_M(self):
+        rng = period_range("2014-01", "2016-12", freq="M")
+        expected = period_range("2014-06", "2017-05", freq="M")
+
+        result = rng + pd.offsets.MonthEnd(5)
+        tm.assert_index_equal(result, expected)
+
+        rng += pd.offsets.MonthEnd(5)
+        tm.assert_index_equal(rng, expected)
+
+    def test_pi_add_sub_timedeltalike_freq_mismatch_monthly(self, mismatched_freq):
+        other = mismatched_freq
+        rng = period_range("2014-01", "2016-12", freq="M")
+        msg = "Input has different freq(=.+)? from Period.*?\\(freq=M\\)"
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng + other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng += other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng - other
+        with pytest.raises(IncompatibleFrequency, match=msg):
+            rng -= other
+
+    @pytest.mark.parametrize("transpose", [True, False])
+    def test_parr_add_sub_td64_nat(self, box_with_array, transpose):
+        # GH#23320 special handling for timedelta64("NaT")
+        pi = period_range("1994-04-01", periods=9, freq="19D")
+        other = np.timedelta64("NaT")
+        expected = PeriodIndex(["NaT"] * 9, freq="19D")
+
+        obj = tm.box_expected(pi, box_with_array, transpose=transpose)
+        expected = tm.box_expected(expected, box_with_array, transpose=transpose)
+
+        result = obj + other
+        tm.assert_equal(result, expected)
+        result = other + obj
+        tm.assert_equal(result, expected)
+        result = obj - other
+        tm.assert_equal(result, expected)
+        msg = r"cannot subtract .* from .*"
+        with pytest.raises(TypeError, match=msg):
+            other - obj
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            np.array(["NaT"] * 9, dtype="m8[ns]"),
+            TimedeltaArray._from_sequence(["NaT"] * 9, dtype="m8[ns]"),
+        ],
+    )
+    def test_parr_add_sub_tdt64_nat_array(self, box_with_array, other):
+        pi = period_range("1994-04-01", periods=9, freq="19D")
+        expected = PeriodIndex(["NaT"] * 9, freq="19D")
+
+        obj = tm.box_expected(pi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = obj + other
+        tm.assert_equal(result, expected)
+        result = other + obj
+        tm.assert_equal(result, expected)
+        result = obj - other
+        tm.assert_equal(result, expected)
+        msg = r"cannot subtract .* from .*"
+        with pytest.raises(TypeError, match=msg):
+            other - obj
+
+        # some but not *all* NaT
+        other = other.copy()
+        other[0] = np.timedelta64(0, "ns")
+        expected = PeriodIndex([pi[0]] + ["NaT"] * 8, freq="19D")
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = obj + other
+        tm.assert_equal(result, expected)
+        result = other + obj
+        tm.assert_equal(result, expected)
+        result = obj - other
+        tm.assert_equal(result, expected)
+        with pytest.raises(TypeError, match=msg):
+            other - obj
+
+    # ---------------------------------------------------------------
+    # Unsorted
+
+    def test_parr_add_sub_index(self):
+        # Check that PeriodArray defers to Index on arithmetic ops
+        pi = period_range("2000-12-31", periods=3)
+        parr = pi.array
+
+        result = parr - pi
+        expected = pi - pi
+        tm.assert_index_equal(result, expected)
+
+    def test_parr_add_sub_object_array(self):
+        pi = period_range("2000-12-31", periods=3, freq="D")
+        parr = pi.array
+
+        other = np.array([Timedelta(days=1), pd.offsets.Day(2), 3])
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = parr + other
+
+        expected = PeriodIndex(
+            ["2001-01-01", "2001-01-03", "2001-01-05"], freq="D"
+        )._data.astype(object)
+        tm.assert_equal(result, expected)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = parr - other
+
+        expected = PeriodIndex(["2000-12-30"] * 3, freq="D")._data.astype(object)
+        tm.assert_equal(result, expected)
+
+    def test_period_add_timestamp_raises(self, box_with_array):
+        # GH#17983
+        ts = Timestamp("2017")
+        per = Period("2017", freq="M")
+
+        arr = pd.Index([per], dtype="Period[M]")
+        arr = tm.box_expected(arr, box_with_array)
+
+        msg = "cannot add PeriodArray and Timestamp"
+        with pytest.raises(TypeError, match=msg):
+            arr + ts
+        with pytest.raises(TypeError, match=msg):
+            ts + arr
+        msg = "cannot add PeriodArray and DatetimeArray"
+        with pytest.raises(TypeError, match=msg):
+            arr + Series([ts])
+        with pytest.raises(TypeError, match=msg):
+            Series([ts]) + arr
+        with pytest.raises(TypeError, match=msg):
+            arr + pd.Index([ts])
+        with pytest.raises(TypeError, match=msg):
+            pd.Index([ts]) + arr
+
+        if box_with_array is pd.DataFrame:
+            msg = "cannot add PeriodArray and DatetimeArray"
+        else:
+            msg = r"unsupported operand type\(s\) for \+: 'Period' and 'DatetimeArray"
+        with pytest.raises(TypeError, match=msg):
+            arr + pd.DataFrame([ts])
+        if box_with_array is pd.DataFrame:
+            msg = "cannot add PeriodArray and DatetimeArray"
+        else:
+            msg = r"unsupported operand type\(s\) for \+: 'DatetimeArray' and 'Period'"
+        with pytest.raises(TypeError, match=msg):
+            pd.DataFrame([ts]) + arr
+
+
+class TestPeriodSeriesArithmetic:
+    def test_parr_add_timedeltalike_scalar(self, three_days, box_with_array):
+        # GH#13043
+        ser = Series(
+            [Period("2015-01-01", freq="D"), Period("2015-01-02", freq="D")],
+            name="xxx",
+        )
+        assert ser.dtype == "Period[D]"
+
+        expected = Series(
+            [Period("2015-01-04", freq="D"), Period("2015-01-05", freq="D")],
+            name="xxx",
+        )
+
+        obj = tm.box_expected(ser, box_with_array)
+        if box_with_array is pd.DataFrame:
+            assert (obj.dtypes == "Period[D]").all()
+
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = obj + three_days
+        tm.assert_equal(result, expected)
+
+        result = three_days + obj
+        tm.assert_equal(result, expected)
+
+    def test_ops_series_period(self):
+        # GH#13043
+        ser = Series(
+            [Period("2015-01-01", freq="D"), Period("2015-01-02", freq="D")],
+            name="xxx",
+        )
+        assert ser.dtype == "Period[D]"
+
+        per = Period("2015-01-10", freq="D")
+        off = per.freq
+        # dtype will be object because of original dtype
+        expected = Series([9 * off, 8 * off], name="xxx", dtype=object)
+        tm.assert_series_equal(per - ser, expected)
+        tm.assert_series_equal(ser - per, -1 * expected)
+
+        s2 = Series(
+            [Period("2015-01-05", freq="D"), Period("2015-01-04", freq="D")],
+            name="xxx",
+        )
+        assert s2.dtype == "Period[D]"
+
+        expected = Series([4 * off, 2 * off], name="xxx", dtype=object)
+        tm.assert_series_equal(s2 - ser, expected)
+        tm.assert_series_equal(ser - s2, -1 * expected)
+
+
+class TestPeriodIndexSeriesMethods:
+    """Test PeriodIndex and Period Series Ops consistency"""
+
+    def _check(self, values, func, expected):
+        idx = PeriodIndex(values)
+        result = func(idx)
+        tm.assert_equal(result, expected)
+
+        ser = Series(values)
+        result = func(ser)
+
+        exp = Series(expected, name=values.name)
+        tm.assert_series_equal(result, exp)
+
+    def test_pi_ops(self):
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+
+        expected = PeriodIndex(
+            ["2011-03", "2011-04", "2011-05", "2011-06"], freq="M", name="idx"
+        )
+
+        self._check(idx, lambda x: x + 2, expected)
+        self._check(idx, lambda x: 2 + x, expected)
+
+        self._check(idx + 2, lambda x: x - 2, idx)
+
+        result = idx - Period("2011-01", freq="M")
+        off = idx.freq
+        exp = pd.Index([0 * off, 1 * off, 2 * off, 3 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+        result = Period("2011-01", freq="M") - idx
+        exp = pd.Index([0 * off, -1 * off, -2 * off, -3 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+    @pytest.mark.parametrize("ng", ["str", 1.5])
+    @pytest.mark.parametrize(
+        "func",
+        [
+            lambda obj, ng: obj + ng,
+            lambda obj, ng: ng + obj,
+            lambda obj, ng: obj - ng,
+            lambda obj, ng: ng - obj,
+            lambda obj, ng: np.add(obj, ng),
+            lambda obj, ng: np.add(ng, obj),
+            lambda obj, ng: np.subtract(obj, ng),
+            lambda obj, ng: np.subtract(ng, obj),
+        ],
+    )
+    def test_parr_ops_errors(self, ng, func, box_with_array):
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+        obj = tm.box_expected(idx, box_with_array)
+        msg = "|".join(
+            [
+                r"unsupported operand type\(s\)",
+                "can only concatenate",
+                r"must be str",
+                "object to str implicitly",
+            ]
+        )
+
+        with pytest.raises(TypeError, match=msg):
+            func(obj, ng)
+
+    def test_pi_ops_nat(self):
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "NaT", "2011-04"], freq="M", name="idx"
+        )
+        expected = PeriodIndex(
+            ["2011-03", "2011-04", "NaT", "2011-06"], freq="M", name="idx"
+        )
+
+        self._check(idx, lambda x: x + 2, expected)
+        self._check(idx, lambda x: 2 + x, expected)
+        self._check(idx, lambda x: np.add(x, 2), expected)
+
+        self._check(idx + 2, lambda x: x - 2, idx)
+        self._check(idx + 2, lambda x: np.subtract(x, 2), idx)
+
+        # freq with mult
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "NaT", "2011-04"], freq="2M", name="idx"
+        )
+        expected = PeriodIndex(
+            ["2011-07", "2011-08", "NaT", "2011-10"], freq="2M", name="idx"
+        )
+
+        self._check(idx, lambda x: x + 3, expected)
+        self._check(idx, lambda x: 3 + x, expected)
+        self._check(idx, lambda x: np.add(x, 3), expected)
+
+        self._check(idx + 3, lambda x: x - 3, idx)
+        self._check(idx + 3, lambda x: np.subtract(x, 3), idx)
+
+    def test_pi_ops_array_int(self):
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "NaT", "2011-04"], freq="M", name="idx"
+        )
+        f = lambda x: x + np.array([1, 2, 3, 4])
+        exp = PeriodIndex(
+            ["2011-02", "2011-04", "NaT", "2011-08"], freq="M", name="idx"
+        )
+        self._check(idx, f, exp)
+
+        f = lambda x: np.add(x, np.array([4, -1, 1, 2]))
+        exp = PeriodIndex(
+            ["2011-05", "2011-01", "NaT", "2011-06"], freq="M", name="idx"
+        )
+        self._check(idx, f, exp)
+
+        f = lambda x: x - np.array([1, 2, 3, 4])
+        exp = PeriodIndex(
+            ["2010-12", "2010-12", "NaT", "2010-12"], freq="M", name="idx"
+        )
+        self._check(idx, f, exp)
+
+        f = lambda x: np.subtract(x, np.array([3, 2, 3, -2]))
+        exp = PeriodIndex(
+            ["2010-10", "2010-12", "NaT", "2011-06"], freq="M", name="idx"
+        )
+        self._check(idx, f, exp)
+
+    def test_pi_ops_offset(self):
+        idx = PeriodIndex(
+            ["2011-01-01", "2011-02-01", "2011-03-01", "2011-04-01"],
+            freq="D",
+            name="idx",
+        )
+        f = lambda x: x + pd.offsets.Day()
+        exp = PeriodIndex(
+            ["2011-01-02", "2011-02-02", "2011-03-02", "2011-04-02"],
+            freq="D",
+            name="idx",
+        )
+        self._check(idx, f, exp)
+
+        f = lambda x: x + pd.offsets.Day(2)
+        exp = PeriodIndex(
+            ["2011-01-03", "2011-02-03", "2011-03-03", "2011-04-03"],
+            freq="D",
+            name="idx",
+        )
+        self._check(idx, f, exp)
+
+        f = lambda x: x - pd.offsets.Day(2)
+        exp = PeriodIndex(
+            ["2010-12-30", "2011-01-30", "2011-02-27", "2011-03-30"],
+            freq="D",
+            name="idx",
+        )
+        self._check(idx, f, exp)
+
+    def test_pi_offset_errors(self):
+        idx = PeriodIndex(
+            ["2011-01-01", "2011-02-01", "2011-03-01", "2011-04-01"],
+            freq="D",
+            name="idx",
+        )
+        ser = Series(idx)
+
+        msg = (
+            "Cannot add/subtract timedelta-like from PeriodArray that is not "
+            "an integer multiple of the PeriodArray's freq"
+        )
+        for obj in [idx, ser]:
+            with pytest.raises(IncompatibleFrequency, match=msg):
+                obj + pd.offsets.Hour(2)
+
+            with pytest.raises(IncompatibleFrequency, match=msg):
+                pd.offsets.Hour(2) + obj
+
+            with pytest.raises(IncompatibleFrequency, match=msg):
+                obj - pd.offsets.Hour(2)
+
+    def test_pi_sub_period(self):
+        # GH#13071
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+
+        result = idx - Period("2012-01", freq="M")
+        off = idx.freq
+        exp = pd.Index([-12 * off, -11 * off, -10 * off, -9 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+        result = np.subtract(idx, Period("2012-01", freq="M"))
+        tm.assert_index_equal(result, exp)
+
+        result = Period("2012-01", freq="M") - idx
+        exp = pd.Index([12 * off, 11 * off, 10 * off, 9 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+        result = np.subtract(Period("2012-01", freq="M"), idx)
+        tm.assert_index_equal(result, exp)
+
+        exp = TimedeltaIndex([np.nan, np.nan, np.nan, np.nan], name="idx")
+        result = idx - Period("NaT", freq="M")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == exp.freq
+
+        result = Period("NaT", freq="M") - idx
+        tm.assert_index_equal(result, exp)
+        assert result.freq == exp.freq
+
+    def test_pi_sub_pdnat(self):
+        # GH#13071, GH#19389
+        idx = PeriodIndex(
+            ["2011-01", "2011-02", "NaT", "2011-04"], freq="M", name="idx"
+        )
+        exp = TimedeltaIndex([pd.NaT] * 4, name="idx")
+        tm.assert_index_equal(pd.NaT - idx, exp)
+        tm.assert_index_equal(idx - pd.NaT, exp)
+
+    def test_pi_sub_period_nat(self):
+        # GH#13071
+        idx = PeriodIndex(
+            ["2011-01", "NaT", "2011-03", "2011-04"], freq="M", name="idx"
+        )
+
+        result = idx - Period("2012-01", freq="M")
+        off = idx.freq
+        exp = pd.Index([-12 * off, pd.NaT, -10 * off, -9 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+        result = Period("2012-01", freq="M") - idx
+        exp = pd.Index([12 * off, pd.NaT, 10 * off, 9 * off], name="idx")
+        tm.assert_index_equal(result, exp)
+
+        exp = TimedeltaIndex([np.nan, np.nan, np.nan, np.nan], name="idx")
+        tm.assert_index_equal(idx - Period("NaT", freq="M"), exp)
+        tm.assert_index_equal(Period("NaT", freq="M") - idx, exp)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_timedelta64.py b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_timedelta64.py
new file mode 100644
index 0000000000000000000000000000000000000000..d02e827d435cf16c806b5130f5949143f51c15e3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arithmetic/test_timedelta64.py
@@ -0,0 +1,2179 @@
+# Arithmetic tests for DataFrame/Series/Index/Array classes that should
+# behave identically.
+from datetime import (
+    datetime,
+    timedelta,
+)
+
+import numpy as np
+import pytest
+
+from pandas.errors import (
+    OutOfBoundsDatetime,
+    PerformanceWarning,
+)
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    DatetimeIndex,
+    Index,
+    NaT,
+    Series,
+    Timedelta,
+    TimedeltaIndex,
+    Timestamp,
+    offsets,
+    timedelta_range,
+)
+import pandas._testing as tm
+from pandas.core.arrays import NumpyExtensionArray
+from pandas.tests.arithmetic.common import (
+    assert_invalid_addsub_type,
+    assert_invalid_comparison,
+    get_upcast_box,
+)
+
+
+def assert_dtype(obj, expected_dtype):
+    """
+    Helper to check the dtype for a Series, Index, or single-column DataFrame.
+    """
+    dtype = tm.get_dtype(obj)
+
+    assert dtype == expected_dtype
+
+
+def get_expected_name(box, names):
+    if box is DataFrame:
+        # Since we are operating with a DataFrame and a non-DataFrame,
+        # the non-DataFrame is cast to Series and its name ignored.
+        exname = names[0]
+    elif box in [tm.to_array, pd.array]:
+        exname = names[1]
+    else:
+        exname = names[2]
+    return exname
+
+
+# ------------------------------------------------------------------
+# Timedelta64[ns] dtype Comparisons
+
+
+class TestTimedelta64ArrayLikeComparisons:
+    # Comparison tests for timedelta64[ns] vectors fully parametrized over
+    #  DataFrame/Series/TimedeltaIndex/TimedeltaArray.  Ideally all comparison
+    #  tests will eventually end up here.
+
+    def test_compare_timedelta64_zerodim(self, box_with_array):
+        # GH#26689 should unbox when comparing with zerodim array
+        box = box_with_array
+        xbox = box_with_array if box_with_array not in [Index, pd.array] else np.ndarray
+
+        tdi = timedelta_range("2h", periods=4)
+        other = np.array(tdi.to_numpy()[0])
+
+        tdi = tm.box_expected(tdi, box)
+        res = tdi <= other
+        expected = np.array([True, False, False, False])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(res, expected)
+
+    @pytest.mark.parametrize(
+        "td_scalar",
+        [
+            timedelta(days=1),
+            Timedelta(days=1),
+            Timedelta(days=1).to_timedelta64(),
+            offsets.Hour(24),
+        ],
+    )
+    def test_compare_timedeltalike_scalar(self, box_with_array, td_scalar):
+        # regression test for GH#5963
+        box = box_with_array
+        xbox = box if box not in [Index, pd.array] else np.ndarray
+
+        ser = Series([timedelta(days=1), timedelta(days=2)])
+        ser = tm.box_expected(ser, box)
+        actual = ser > td_scalar
+        expected = Series([False, True])
+        expected = tm.box_expected(expected, xbox)
+        tm.assert_equal(actual, expected)
+
+    @pytest.mark.parametrize(
+        "invalid",
+        [
+            345600000000000,
+            "a",
+            Timestamp("2021-01-01"),
+            Timestamp("2021-01-01").now("UTC"),
+            Timestamp("2021-01-01").now().to_datetime64(),
+            Timestamp("2021-01-01").now().to_pydatetime(),
+            Timestamp("2021-01-01").date(),
+            np.array(4),  # zero-dim mismatched dtype
+        ],
+    )
+    def test_td64_comparisons_invalid(self, box_with_array, invalid):
+        # GH#13624 for str
+        box = box_with_array
+
+        rng = timedelta_range("1 days", periods=10)
+        obj = tm.box_expected(rng, box)
+
+        assert_invalid_comparison(obj, invalid, box)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            list(range(10)),
+            np.arange(10),
+            np.arange(10).astype(np.float32),
+            np.arange(10).astype(object),
+            pd.date_range("1970-01-01", periods=10, tz="UTC").array,
+            np.array(pd.date_range("1970-01-01", periods=10)),
+            list(pd.date_range("1970-01-01", periods=10)),
+            pd.date_range("1970-01-01", periods=10).astype(object),
+            pd.period_range("1971-01-01", freq="D", periods=10).array,
+            pd.period_range("1971-01-01", freq="D", periods=10).astype(object),
+        ],
+    )
+    def test_td64arr_cmp_arraylike_invalid(self, other, box_with_array):
+        # We don't parametrize this over box_with_array because listlike
+        #  other plays poorly with assert_invalid_comparison reversed checks
+
+        rng = timedelta_range("1 days", periods=10)._data
+        rng = tm.box_expected(rng, box_with_array)
+        assert_invalid_comparison(rng, other, box_with_array)
+
+    def test_td64arr_cmp_mixed_invalid(self):
+        rng = timedelta_range("1 days", periods=5)._data
+        other = np.array([0, 1, 2, rng[3], Timestamp("2021-01-01")])
+
+        result = rng == other
+        expected = np.array([False, False, False, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng != other
+        tm.assert_numpy_array_equal(result, ~expected)
+
+        msg = "Invalid comparison between|Cannot compare type|not supported between"
+        with pytest.raises(TypeError, match=msg):
+            rng < other
+        with pytest.raises(TypeError, match=msg):
+            rng > other
+        with pytest.raises(TypeError, match=msg):
+            rng <= other
+        with pytest.raises(TypeError, match=msg):
+            rng >= other
+
+
+class TestTimedelta64ArrayComparisons:
+    # TODO: All of these need to be parametrized over box
+
+    @pytest.mark.parametrize("dtype", [None, object])
+    def test_comp_nat(self, dtype):
+        left = TimedeltaIndex([Timedelta("1 days"), NaT, Timedelta("3 days")])
+        right = TimedeltaIndex([NaT, NaT, Timedelta("3 days")])
+
+        lhs, rhs = left, right
+        if dtype is object:
+            lhs, rhs = left.astype(object), right.astype(object)
+
+        result = rhs == lhs
+        expected = np.array([False, False, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rhs != lhs
+        expected = np.array([True, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        expected = np.array([False, False, False])
+        tm.assert_numpy_array_equal(lhs == NaT, expected)
+        tm.assert_numpy_array_equal(NaT == rhs, expected)
+
+        expected = np.array([True, True, True])
+        tm.assert_numpy_array_equal(lhs != NaT, expected)
+        tm.assert_numpy_array_equal(NaT != lhs, expected)
+
+        expected = np.array([False, False, False])
+        tm.assert_numpy_array_equal(lhs < NaT, expected)
+        tm.assert_numpy_array_equal(NaT > lhs, expected)
+
+    @pytest.mark.parametrize(
+        "idx2",
+        [
+            TimedeltaIndex(
+                ["2 day", "2 day", NaT, NaT, "1 day 00:00:02", "5 days 00:00:03"]
+            ),
+            np.array(
+                [
+                    np.timedelta64(2, "D"),
+                    np.timedelta64(2, "D"),
+                    np.timedelta64("nat"),
+                    np.timedelta64("nat"),
+                    np.timedelta64(1, "D") + np.timedelta64(2, "s"),
+                    np.timedelta64(5, "D") + np.timedelta64(3, "s"),
+                ]
+            ),
+        ],
+    )
+    def test_comparisons_nat(self, idx2):
+        idx1 = TimedeltaIndex(
+            [
+                "1 day",
+                NaT,
+                "1 day 00:00:01",
+                NaT,
+                "1 day 00:00:01",
+                "5 day 00:00:03",
+            ]
+        )
+        # Check pd.NaT is handles as the same as np.nan
+        result = idx1 < idx2
+        expected = np.array([True, False, False, False, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = idx2 > idx1
+        expected = np.array([True, False, False, False, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = idx1 <= idx2
+        expected = np.array([True, False, False, False, True, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = idx2 >= idx1
+        expected = np.array([True, False, False, False, True, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = idx1 == idx2
+        expected = np.array([False, False, False, False, False, True])
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = idx1 != idx2
+        expected = np.array([True, True, True, True, True, False])
+        tm.assert_numpy_array_equal(result, expected)
+
+    # TODO: better name
+    def test_comparisons_coverage(self):
+        rng = timedelta_range("1 days", periods=10)
+
+        result = rng < rng[3]
+        expected = np.array([True, True, True] + [False] * 7)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = rng == list(rng)
+        exp = rng == rng
+        tm.assert_numpy_array_equal(result, exp)
+
+
+# ------------------------------------------------------------------
+# Timedelta64[ns] dtype Arithmetic Operations
+
+
+class TestTimedelta64ArithmeticUnsorted:
+    # Tests moved from type-specific test files but not
+    #  yet sorted/parametrized/de-duplicated
+
+    def test_ufunc_coercions(self):
+        # normal ops are also tested in tseries/test_timedeltas.py
+        idx = TimedeltaIndex(["2h", "4h", "6h", "8h", "10h"], freq="2h", name="x")
+
+        for result in [idx * 2, np.multiply(idx, 2)]:
+            assert isinstance(result, TimedeltaIndex)
+            exp = TimedeltaIndex(["4h", "8h", "12h", "16h", "20h"], freq="4h", name="x")
+            tm.assert_index_equal(result, exp)
+            assert result.freq == "4h"
+
+        for result in [idx / 2, np.divide(idx, 2)]:
+            assert isinstance(result, TimedeltaIndex)
+            exp = TimedeltaIndex(["1h", "2h", "3h", "4h", "5h"], freq="h", name="x")
+            tm.assert_index_equal(result, exp)
+            assert result.freq == "h"
+
+        for result in [-idx, np.negative(idx)]:
+            assert isinstance(result, TimedeltaIndex)
+            exp = TimedeltaIndex(
+                ["-2h", "-4h", "-6h", "-8h", "-10h"], freq="-2h", name="x"
+            )
+            tm.assert_index_equal(result, exp)
+            assert result.freq == "-2h"
+
+        idx = TimedeltaIndex(["-2h", "-1h", "0h", "1h", "2h"], freq="h", name="x")
+        for result in [abs(idx), np.absolute(idx)]:
+            assert isinstance(result, TimedeltaIndex)
+            exp = TimedeltaIndex(["2h", "1h", "0h", "1h", "2h"], freq=None, name="x")
+            tm.assert_index_equal(result, exp)
+            assert result.freq is None
+
+    def test_subtraction_ops(self):
+        # with datetimes/timedelta and tdi/dti
+        tdi = TimedeltaIndex(["1 days", NaT, "2 days"], name="foo")
+        dti = pd.date_range("20130101", periods=3, name="bar")
+        td = Timedelta("1 days")
+        dt = Timestamp("20130101")
+
+        msg = "cannot subtract a datelike from a TimedeltaArray"
+        with pytest.raises(TypeError, match=msg):
+            tdi - dt
+        with pytest.raises(TypeError, match=msg):
+            tdi - dti
+
+        msg = r"unsupported operand type\(s\) for -"
+        with pytest.raises(TypeError, match=msg):
+            td - dt
+
+        msg = "(bad|unsupported) operand type for unary"
+        with pytest.raises(TypeError, match=msg):
+            td - dti
+
+        result = dt - dti
+        expected = TimedeltaIndex(["0 days", "-1 days", "-2 days"], name="bar")
+        tm.assert_index_equal(result, expected)
+
+        result = dti - dt
+        expected = TimedeltaIndex(["0 days", "1 days", "2 days"], name="bar")
+        tm.assert_index_equal(result, expected)
+
+        result = tdi - td
+        expected = TimedeltaIndex(["0 days", NaT, "1 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        result = td - tdi
+        expected = TimedeltaIndex(["0 days", NaT, "-1 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        result = dti - td
+        expected = DatetimeIndex(
+            ["20121231", "20130101", "20130102"], dtype="M8[ns]", freq="D", name="bar"
+        )
+        tm.assert_index_equal(result, expected)
+
+        result = dt - tdi
+        expected = DatetimeIndex(
+            ["20121231", NaT, "20121230"], dtype="M8[ns]", name="foo"
+        )
+        tm.assert_index_equal(result, expected)
+
+    def test_subtraction_ops_with_tz(self, box_with_array):
+        # check that dt/dti subtraction ops with tz are validated
+        dti = pd.date_range("20130101", periods=3)
+        dti = tm.box_expected(dti, box_with_array)
+        ts = Timestamp("20130101")
+        dt = ts.to_pydatetime()
+        dti_tz = pd.date_range("20130101", periods=3).tz_localize("US/Eastern")
+        dti_tz = tm.box_expected(dti_tz, box_with_array)
+        ts_tz = Timestamp("20130101").tz_localize("US/Eastern")
+        ts_tz2 = Timestamp("20130101").tz_localize("CET")
+        dt_tz = ts_tz.to_pydatetime()
+        td = Timedelta("1 days")
+
+        def _check(result, expected):
+            assert result == expected
+            assert isinstance(result, Timedelta)
+
+        # scalars
+        result = ts - ts
+        expected = Timedelta("0 days")
+        _check(result, expected)
+
+        result = dt_tz - ts_tz
+        expected = Timedelta("0 days")
+        _check(result, expected)
+
+        result = ts_tz - dt_tz
+        expected = Timedelta("0 days")
+        _check(result, expected)
+
+        # tz mismatches
+        msg = "Cannot subtract tz-naive and tz-aware datetime-like objects."
+        with pytest.raises(TypeError, match=msg):
+            dt_tz - ts
+        msg = "can't subtract offset-naive and offset-aware datetimes"
+        with pytest.raises(TypeError, match=msg):
+            dt_tz - dt
+        msg = "can't subtract offset-naive and offset-aware datetimes"
+        with pytest.raises(TypeError, match=msg):
+            dt - dt_tz
+        msg = "Cannot subtract tz-naive and tz-aware datetime-like objects."
+        with pytest.raises(TypeError, match=msg):
+            ts - dt_tz
+        with pytest.raises(TypeError, match=msg):
+            ts_tz2 - ts
+        with pytest.raises(TypeError, match=msg):
+            ts_tz2 - dt
+
+        msg = "Cannot subtract tz-naive and tz-aware"
+        # with dti
+        with pytest.raises(TypeError, match=msg):
+            dti - ts_tz
+        with pytest.raises(TypeError, match=msg):
+            dti_tz - ts
+
+        result = dti_tz - dt_tz
+        expected = TimedeltaIndex(["0 days", "1 days", "2 days"])
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = dt_tz - dti_tz
+        expected = TimedeltaIndex(["0 days", "-1 days", "-2 days"])
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = dti_tz - ts_tz
+        expected = TimedeltaIndex(["0 days", "1 days", "2 days"])
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = ts_tz - dti_tz
+        expected = TimedeltaIndex(["0 days", "-1 days", "-2 days"])
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+        result = td - td
+        expected = Timedelta("0 days")
+        _check(result, expected)
+
+        result = dti_tz - td
+        expected = DatetimeIndex(
+            ["20121231", "20130101", "20130102"], tz="US/Eastern"
+        ).as_unit("ns")
+        expected = tm.box_expected(expected, box_with_array)
+        tm.assert_equal(result, expected)
+
+    def test_dti_tdi_numeric_ops(self):
+        # These are normally union/diff set-like ops
+        tdi = TimedeltaIndex(["1 days", NaT, "2 days"], name="foo")
+        dti = pd.date_range("20130101", periods=3, name="bar")
+
+        result = tdi - tdi
+        expected = TimedeltaIndex(["0 days", NaT, "0 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        result = tdi + tdi
+        expected = TimedeltaIndex(["2 days", NaT, "4 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        result = dti - tdi  # name will be reset
+        expected = DatetimeIndex(["20121231", NaT, "20130101"], dtype="M8[ns]")
+        tm.assert_index_equal(result, expected)
+
+    def test_addition_ops(self):
+        # with datetimes/timedelta and tdi/dti
+        tdi = TimedeltaIndex(["1 days", NaT, "2 days"], name="foo")
+        dti = pd.date_range("20130101", periods=3, name="bar")
+        td = Timedelta("1 days")
+        dt = Timestamp("20130101")
+
+        result = tdi + dt
+        expected = DatetimeIndex(
+            ["20130102", NaT, "20130103"], dtype="M8[ns]", name="foo"
+        )
+        tm.assert_index_equal(result, expected)
+
+        result = dt + tdi
+        expected = DatetimeIndex(
+            ["20130102", NaT, "20130103"], dtype="M8[ns]", name="foo"
+        )
+        tm.assert_index_equal(result, expected)
+
+        result = td + tdi
+        expected = TimedeltaIndex(["2 days", NaT, "3 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        result = tdi + td
+        expected = TimedeltaIndex(["2 days", NaT, "3 days"], name="foo")
+        tm.assert_index_equal(result, expected)
+
+        # unequal length
+        msg = "cannot add indices of unequal length"
+        with pytest.raises(ValueError, match=msg):
+            tdi + dti[0:1]
+        with pytest.raises(ValueError, match=msg):
+            tdi[0:1] + dti
+
+        # random indexes
+        msg = "Addition/subtraction of integers and integer-arrays"
+        with pytest.raises(TypeError, match=msg):
+            tdi + Index([1, 2, 3], dtype=np.int64)
+
+        # this is a union!
+        # FIXME: don't leave commented-out
+        # pytest.raises(TypeError, lambda : Index([1,2,3]) + tdi)
+
+        result = tdi + dti  # name will be reset
+        expected = DatetimeIndex(["20130102", NaT, "20130105"], dtype="M8[ns]")
+        tm.assert_index_equal(result, expected)
+
+        result = dti + tdi  # name will be reset
+        expected = DatetimeIndex(["20130102", NaT, "20130105"], dtype="M8[ns]")
+        tm.assert_index_equal(result, expected)
+
+        result = dt + td
+        expected = Timestamp("20130102")
+        assert result == expected
+
+        result = td + dt
+        expected = Timestamp("20130102")
+        assert result == expected
+
+    # TODO: Needs more informative name, probably split up into
+    # more targeted tests
+    @pytest.mark.parametrize("freq", ["D", "B"])
+    def test_timedelta(self, freq):
+        index = pd.date_range("1/1/2000", periods=50, freq=freq)
+
+        shifted = index + timedelta(1)
+        back = shifted + timedelta(-1)
+        back = back._with_freq("infer")
+        tm.assert_index_equal(index, back)
+
+        if freq == "D":
+            expected = pd.tseries.offsets.Day(1)
+            assert index.freq == expected
+            assert shifted.freq == expected
+            assert back.freq == expected
+        else:  # freq == 'B'
+            assert index.freq == pd.tseries.offsets.BusinessDay(1)
+            assert shifted.freq is None
+            assert back.freq == pd.tseries.offsets.BusinessDay(1)
+
+        result = index - timedelta(1)
+        expected = index + timedelta(-1)
+        tm.assert_index_equal(result, expected)
+
+    def test_timedelta_tick_arithmetic(self):
+        # GH#4134, buggy with timedeltas
+        rng = pd.date_range("2013", "2014")
+        s = Series(rng)
+        result1 = rng - offsets.Hour(1)
+        result2 = DatetimeIndex(s - np.timedelta64(100000000))
+        result3 = rng - np.timedelta64(100000000)
+        result4 = DatetimeIndex(s - offsets.Hour(1))
+
+        assert result1.freq == rng.freq
+        result1 = result1._with_freq(None)
+        tm.assert_index_equal(result1, result4)
+
+        assert result3.freq == rng.freq
+        result3 = result3._with_freq(None)
+        tm.assert_index_equal(result2, result3)
+
+    def test_tda_add_sub_index(self):
+        # Check that TimedeltaArray defers to Index on arithmetic ops
+        tdi = TimedeltaIndex(["1 days", NaT, "2 days"])
+        tda = tdi.array
+
+        dti = pd.date_range("1999-12-31", periods=3, freq="D")
+
+        result = tda + dti
+        expected = tdi + dti
+        tm.assert_index_equal(result, expected)
+
+        result = tda + tdi
+        expected = tdi + tdi
+        tm.assert_index_equal(result, expected)
+
+        result = tda - tdi
+        expected = tdi - tdi
+        tm.assert_index_equal(result, expected)
+
+    def test_tda_add_dt64_object_array(self, box_with_array, tz_naive_fixture):
+        # Result should be cast back to DatetimeArray
+        box = box_with_array
+
+        dti = pd.date_range("2016-01-01", periods=3, tz=tz_naive_fixture)
+        dti = dti._with_freq(None)
+        tdi = dti - dti
+
+        obj = tm.box_expected(tdi, box)
+        other = tm.box_expected(dti, box)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = obj + other.astype(object)
+        tm.assert_equal(result, other.astype(object))
+
+    # -------------------------------------------------------------
+    # Binary operations TimedeltaIndex and timedelta-like
+
+    def test_tdi_iadd_timedeltalike(self, two_hours, box_with_array):
+        # only test adding/sub offsets as + is now numeric
+        rng = timedelta_range("1 days", "10 days")
+        expected = timedelta_range("1 days 02:00:00", "10 days 02:00:00", freq="D")
+
+        rng = tm.box_expected(rng, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        orig_rng = rng
+        rng += two_hours
+        tm.assert_equal(rng, expected)
+        if box_with_array is not Index:
+            # Check that operation is actually inplace
+            tm.assert_equal(orig_rng, expected)
+
+    def test_tdi_isub_timedeltalike(self, two_hours, box_with_array):
+        # only test adding/sub offsets as - is now numeric
+        rng = timedelta_range("1 days", "10 days")
+        expected = timedelta_range("0 days 22:00:00", "9 days 22:00:00")
+
+        rng = tm.box_expected(rng, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        orig_rng = rng
+        rng -= two_hours
+        tm.assert_equal(rng, expected)
+        if box_with_array is not Index:
+            # Check that operation is actually inplace
+            tm.assert_equal(orig_rng, expected)
+
+    # -------------------------------------------------------------
+
+    def test_tdi_ops_attributes(self):
+        rng = timedelta_range("2 days", periods=5, freq="2D", name="x")
+
+        result = rng + 1 * rng.freq
+        exp = timedelta_range("4 days", periods=5, freq="2D", name="x")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == "2D"
+
+        result = rng - 2 * rng.freq
+        exp = timedelta_range("-2 days", periods=5, freq="2D", name="x")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == "2D"
+
+        result = rng * 2
+        exp = timedelta_range("4 days", periods=5, freq="4D", name="x")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == "4D"
+
+        result = rng / 2
+        exp = timedelta_range("1 days", periods=5, freq="D", name="x")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == "D"
+
+        result = -rng
+        exp = timedelta_range("-2 days", periods=5, freq="-2D", name="x")
+        tm.assert_index_equal(result, exp)
+        assert result.freq == "-2D"
+
+        rng = timedelta_range("-2 days", periods=5, freq="D", name="x")
+
+        result = abs(rng)
+        exp = TimedeltaIndex(
+            ["2 days", "1 days", "0 days", "1 days", "2 days"], name="x"
+        )
+        tm.assert_index_equal(result, exp)
+        assert result.freq is None
+
+
+class TestAddSubNaTMasking:
+    # TODO: parametrize over boxes
+
+    @pytest.mark.parametrize("str_ts", ["1950-01-01", "1980-01-01"])
+    def test_tdarr_add_timestamp_nat_masking(self, box_with_array, str_ts):
+        # GH#17991 checking for overflow-masking with NaT
+        tdinat = pd.to_timedelta(["24658 days 11:15:00", "NaT"])
+        tdobj = tm.box_expected(tdinat, box_with_array)
+
+        ts = Timestamp(str_ts)
+        ts_variants = [
+            ts,
+            ts.to_pydatetime(),
+            ts.to_datetime64().astype("datetime64[ns]"),
+            ts.to_datetime64().astype("datetime64[D]"),
+        ]
+
+        for variant in ts_variants:
+            res = tdobj + variant
+            if box_with_array is DataFrame:
+                assert res.iloc[1, 1] is NaT
+            else:
+                assert res[1] is NaT
+
+    def test_tdi_add_overflow(self):
+        # See GH#14068
+        # preliminary test scalar analogue of vectorized tests below
+        # TODO: Make raised error message more informative and test
+        with pytest.raises(OutOfBoundsDatetime, match="10155196800000000000"):
+            pd.to_timedelta(106580, "D") + Timestamp("2000")
+        with pytest.raises(OutOfBoundsDatetime, match="10155196800000000000"):
+            Timestamp("2000") + pd.to_timedelta(106580, "D")
+
+        _NaT = NaT._value + 1
+        msg = "Overflow in int64 addition"
+        with pytest.raises(OverflowError, match=msg):
+            pd.to_timedelta([106580], "D") + Timestamp("2000")
+        with pytest.raises(OverflowError, match=msg):
+            Timestamp("2000") + pd.to_timedelta([106580], "D")
+        with pytest.raises(OverflowError, match=msg):
+            pd.to_timedelta([_NaT]) - Timedelta("1 days")
+        with pytest.raises(OverflowError, match=msg):
+            pd.to_timedelta(["5 days", _NaT]) - Timedelta("1 days")
+        with pytest.raises(OverflowError, match=msg):
+            (
+                pd.to_timedelta([_NaT, "5 days", "1 hours"])
+                - pd.to_timedelta(["7 seconds", _NaT, "4 hours"])
+            )
+
+        # These should not overflow!
+        exp = TimedeltaIndex([NaT])
+        result = pd.to_timedelta([NaT]) - Timedelta("1 days")
+        tm.assert_index_equal(result, exp)
+
+        exp = TimedeltaIndex(["4 days", NaT])
+        result = pd.to_timedelta(["5 days", NaT]) - Timedelta("1 days")
+        tm.assert_index_equal(result, exp)
+
+        exp = TimedeltaIndex([NaT, NaT, "5 hours"])
+        result = pd.to_timedelta([NaT, "5 days", "1 hours"]) + pd.to_timedelta(
+            ["7 seconds", NaT, "4 hours"]
+        )
+        tm.assert_index_equal(result, exp)
+
+
+class TestTimedeltaArraylikeAddSubOps:
+    # Tests for timedelta64[ns] __add__, __sub__, __radd__, __rsub__
+
+    def test_sub_nat_retain_unit(self):
+        ser = pd.to_timedelta(Series(["00:00:01"])).astype("m8[s]")
+
+        result = ser - NaT
+        expected = Series([NaT], dtype="m8[s]")
+        tm.assert_series_equal(result, expected)
+
+    # TODO: moved from tests.indexes.timedeltas.test_arithmetic; needs
+    #  parametrization+de-duplication
+    def test_timedelta_ops_with_missing_values(self):
+        # setup
+        s1 = pd.to_timedelta(Series(["00:00:01"]))
+        s2 = pd.to_timedelta(Series(["00:00:02"]))
+
+        sn = pd.to_timedelta(Series([NaT], dtype="m8[ns]"))
+
+        df1 = DataFrame(["00:00:01"]).apply(pd.to_timedelta)
+        df2 = DataFrame(["00:00:02"]).apply(pd.to_timedelta)
+
+        dfn = DataFrame([NaT._value]).apply(pd.to_timedelta)
+
+        scalar1 = pd.to_timedelta("00:00:01")
+        scalar2 = pd.to_timedelta("00:00:02")
+        timedelta_NaT = pd.to_timedelta("NaT")
+
+        actual = scalar1 + scalar1
+        assert actual == scalar2
+        actual = scalar2 - scalar1
+        assert actual == scalar1
+
+        actual = s1 + s1
+        tm.assert_series_equal(actual, s2)
+        actual = s2 - s1
+        tm.assert_series_equal(actual, s1)
+
+        actual = s1 + scalar1
+        tm.assert_series_equal(actual, s2)
+        actual = scalar1 + s1
+        tm.assert_series_equal(actual, s2)
+        actual = s2 - scalar1
+        tm.assert_series_equal(actual, s1)
+        actual = -scalar1 + s2
+        tm.assert_series_equal(actual, s1)
+
+        actual = s1 + timedelta_NaT
+        tm.assert_series_equal(actual, sn)
+        actual = timedelta_NaT + s1
+        tm.assert_series_equal(actual, sn)
+        actual = s1 - timedelta_NaT
+        tm.assert_series_equal(actual, sn)
+        actual = -timedelta_NaT + s1
+        tm.assert_series_equal(actual, sn)
+
+        msg = "unsupported operand type"
+        with pytest.raises(TypeError, match=msg):
+            s1 + np.nan
+        with pytest.raises(TypeError, match=msg):
+            np.nan + s1
+        with pytest.raises(TypeError, match=msg):
+            s1 - np.nan
+        with pytest.raises(TypeError, match=msg):
+            -np.nan + s1
+
+        actual = s1 + NaT
+        tm.assert_series_equal(actual, sn)
+        actual = s2 - NaT
+        tm.assert_series_equal(actual, sn)
+
+        actual = s1 + df1
+        tm.assert_frame_equal(actual, df2)
+        actual = s2 - df1
+        tm.assert_frame_equal(actual, df1)
+        actual = df1 + s1
+        tm.assert_frame_equal(actual, df2)
+        actual = df2 - s1
+        tm.assert_frame_equal(actual, df1)
+
+        actual = df1 + df1
+        tm.assert_frame_equal(actual, df2)
+        actual = df2 - df1
+        tm.assert_frame_equal(actual, df1)
+
+        actual = df1 + scalar1
+        tm.assert_frame_equal(actual, df2)
+        actual = df2 - scalar1
+        tm.assert_frame_equal(actual, df1)
+
+        actual = df1 + timedelta_NaT
+        tm.assert_frame_equal(actual, dfn)
+        actual = df1 - timedelta_NaT
+        tm.assert_frame_equal(actual, dfn)
+
+        msg = "cannot subtract a datelike from|unsupported operand type"
+        with pytest.raises(TypeError, match=msg):
+            df1 + np.nan
+        with pytest.raises(TypeError, match=msg):
+            df1 - np.nan
+
+        actual = df1 + NaT  # NaT is datetime, not timedelta
+        tm.assert_frame_equal(actual, dfn)
+        actual = df1 - NaT
+        tm.assert_frame_equal(actual, dfn)
+
+    # TODO: moved from tests.series.test_operators, needs splitting, cleanup,
+    # de-duplication, box-parametrization...
+    def test_operators_timedelta64(self):
+        # series ops
+        v1 = pd.date_range("2012-1-1", periods=3, freq="D")
+        v2 = pd.date_range("2012-1-2", periods=3, freq="D")
+        rs = Series(v2) - Series(v1)
+        xp = Series(1e9 * 3600 * 24, rs.index).astype("int64").astype("timedelta64[ns]")
+        tm.assert_series_equal(rs, xp)
+        assert rs.dtype == "timedelta64[ns]"
+
+        df = DataFrame({"A": v1})
+        td = Series([timedelta(days=i) for i in range(3)])
+        assert td.dtype == "timedelta64[ns]"
+
+        # series on the rhs
+        result = df["A"] - df["A"].shift()
+        assert result.dtype == "timedelta64[ns]"
+
+        result = df["A"] + td
+        assert result.dtype == "M8[ns]"
+
+        # scalar Timestamp on rhs
+        maxa = df["A"].max()
+        assert isinstance(maxa, Timestamp)
+
+        resultb = df["A"] - df["A"].max()
+        assert resultb.dtype == "timedelta64[ns]"
+
+        # timestamp on lhs
+        result = resultb + df["A"]
+        values = [Timestamp("20111230"), Timestamp("20120101"), Timestamp("20120103")]
+        expected = Series(values, dtype="M8[ns]", name="A")
+        tm.assert_series_equal(result, expected)
+
+        # datetimes on rhs
+        result = df["A"] - datetime(2001, 1, 1)
+        expected = Series([timedelta(days=4017 + i) for i in range(3)], name="A")
+        tm.assert_series_equal(result, expected)
+        assert result.dtype == "m8[ns]"
+
+        d = datetime(2001, 1, 1, 3, 4)
+        resulta = df["A"] - d
+        assert resulta.dtype == "m8[ns]"
+
+        # roundtrip
+        resultb = resulta + d
+        tm.assert_series_equal(df["A"], resultb)
+
+        # timedeltas on rhs
+        td = timedelta(days=1)
+        resulta = df["A"] + td
+        resultb = resulta - td
+        tm.assert_series_equal(resultb, df["A"])
+        assert resultb.dtype == "M8[ns]"
+
+        # roundtrip
+        td = timedelta(minutes=5, seconds=3)
+        resulta = df["A"] + td
+        resultb = resulta - td
+        tm.assert_series_equal(df["A"], resultb)
+        assert resultb.dtype == "M8[ns]"
+
+        # inplace
+        value = rs[2] + np.timedelta64(timedelta(minutes=5, seconds=1))
+        rs[2] += np.timedelta64(timedelta(minutes=5, seconds=1))
+        assert rs[2] == value
+
+    def test_timedelta64_ops_nat(self):
+        # GH 11349
+        timedelta_series = Series([NaT, Timedelta("1s")])
+        nat_series_dtype_timedelta = Series([NaT, NaT], dtype="timedelta64[ns]")
+        single_nat_dtype_timedelta = Series([NaT], dtype="timedelta64[ns]")
+
+        # subtraction
+        tm.assert_series_equal(timedelta_series - NaT, nat_series_dtype_timedelta)
+        tm.assert_series_equal(-NaT + timedelta_series, nat_series_dtype_timedelta)
+
+        tm.assert_series_equal(
+            timedelta_series - single_nat_dtype_timedelta, nat_series_dtype_timedelta
+        )
+        tm.assert_series_equal(
+            -single_nat_dtype_timedelta + timedelta_series, nat_series_dtype_timedelta
+        )
+
+        # addition
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta + NaT, nat_series_dtype_timedelta
+        )
+        tm.assert_series_equal(
+            NaT + nat_series_dtype_timedelta, nat_series_dtype_timedelta
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta + single_nat_dtype_timedelta,
+            nat_series_dtype_timedelta,
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_timedelta + nat_series_dtype_timedelta,
+            nat_series_dtype_timedelta,
+        )
+
+        tm.assert_series_equal(timedelta_series + NaT, nat_series_dtype_timedelta)
+        tm.assert_series_equal(NaT + timedelta_series, nat_series_dtype_timedelta)
+
+        tm.assert_series_equal(
+            timedelta_series + single_nat_dtype_timedelta, nat_series_dtype_timedelta
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_timedelta + timedelta_series, nat_series_dtype_timedelta
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta + NaT, nat_series_dtype_timedelta
+        )
+        tm.assert_series_equal(
+            NaT + nat_series_dtype_timedelta, nat_series_dtype_timedelta
+        )
+
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta + single_nat_dtype_timedelta,
+            nat_series_dtype_timedelta,
+        )
+        tm.assert_series_equal(
+            single_nat_dtype_timedelta + nat_series_dtype_timedelta,
+            nat_series_dtype_timedelta,
+        )
+
+        # multiplication
+        tm.assert_series_equal(
+            nat_series_dtype_timedelta * 1.0, nat_series_dtype_timedelta
+        )
+        tm.assert_series_equal(
+            1.0 * nat_series_dtype_timedelta, nat_series_dtype_timedelta
+        )
+
+        tm.assert_series_equal(timedelta_series * 1, timedelta_series)
+        tm.assert_series_equal(1 * timedelta_series, timedelta_series)
+
+        tm.assert_series_equal(timedelta_series * 1.5, Series([NaT, Timedelta("1.5s")]))
+        tm.assert_series_equal(1.5 * timedelta_series, Series([NaT, Timedelta("1.5s")]))
+
+        tm.assert_series_equal(timedelta_series * np.nan, nat_series_dtype_timedelta)
+        tm.assert_series_equal(np.nan * timedelta_series, nat_series_dtype_timedelta)
+
+        # division
+        tm.assert_series_equal(timedelta_series / 2, Series([NaT, Timedelta("0.5s")]))
+        tm.assert_series_equal(timedelta_series / 2.0, Series([NaT, Timedelta("0.5s")]))
+        tm.assert_series_equal(timedelta_series / np.nan, nat_series_dtype_timedelta)
+
+    # -------------------------------------------------------------
+    # Binary operations td64 arraylike and datetime-like
+
+    @pytest.mark.parametrize("cls", [Timestamp, datetime, np.datetime64])
+    def test_td64arr_add_sub_datetimelike_scalar(
+        self, cls, box_with_array, tz_naive_fixture
+    ):
+        # GH#11925, GH#29558, GH#23215
+        tz = tz_naive_fixture
+
+        dt_scalar = Timestamp("2012-01-01", tz=tz)
+        if cls is datetime:
+            ts = dt_scalar.to_pydatetime()
+        elif cls is np.datetime64:
+            if tz_naive_fixture is not None:
+                pytest.skip(f"{cls} doesn support {tz_naive_fixture}")
+            ts = dt_scalar.to_datetime64()
+        else:
+            ts = dt_scalar
+
+        tdi = timedelta_range("1 day", periods=3)
+        expected = pd.date_range("2012-01-02", periods=3, tz=tz)
+
+        tdarr = tm.box_expected(tdi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        tm.assert_equal(ts + tdarr, expected)
+        tm.assert_equal(tdarr + ts, expected)
+
+        expected2 = pd.date_range("2011-12-31", periods=3, freq="-1D", tz=tz)
+        expected2 = tm.box_expected(expected2, box_with_array)
+
+        tm.assert_equal(ts - tdarr, expected2)
+        tm.assert_equal(ts + (-tdarr), expected2)
+
+        msg = "cannot subtract a datelike"
+        with pytest.raises(TypeError, match=msg):
+            tdarr - ts
+
+    def test_td64arr_add_datetime64_nat(self, box_with_array):
+        # GH#23215
+        other = np.datetime64("NaT")
+
+        tdi = timedelta_range("1 day", periods=3)
+        expected = DatetimeIndex(["NaT", "NaT", "NaT"], dtype="M8[ns]")
+
+        tdser = tm.box_expected(tdi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        tm.assert_equal(tdser + other, expected)
+        tm.assert_equal(other + tdser, expected)
+
+    def test_td64arr_sub_dt64_array(self, box_with_array):
+        dti = pd.date_range("2016-01-01", periods=3)
+        tdi = TimedeltaIndex(["-1 Day"] * 3)
+        dtarr = dti.values
+        expected = DatetimeIndex(dtarr) - tdi
+
+        tdi = tm.box_expected(tdi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        msg = "cannot subtract a datelike from"
+        with pytest.raises(TypeError, match=msg):
+            tdi - dtarr
+
+        # TimedeltaIndex.__rsub__
+        result = dtarr - tdi
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_add_dt64_array(self, box_with_array):
+        dti = pd.date_range("2016-01-01", periods=3)
+        tdi = TimedeltaIndex(["-1 Day"] * 3)
+        dtarr = dti.values
+        expected = DatetimeIndex(dtarr) + tdi
+
+        tdi = tm.box_expected(tdi, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdi + dtarr
+        tm.assert_equal(result, expected)
+        result = dtarr + tdi
+        tm.assert_equal(result, expected)
+
+    # ------------------------------------------------------------------
+    # Invalid __add__/__sub__ operations
+
+    @pytest.mark.parametrize("pi_freq", ["D", "W", "Q", "h"])
+    @pytest.mark.parametrize("tdi_freq", [None, "h"])
+    def test_td64arr_sub_periodlike(
+        self, box_with_array, box_with_array2, tdi_freq, pi_freq
+    ):
+        # GH#20049 subtracting PeriodIndex should raise TypeError
+        tdi = TimedeltaIndex(["1 hours", "2 hours"], freq=tdi_freq)
+        dti = Timestamp("2018-03-07 17:16:40") + tdi
+        pi = dti.to_period(pi_freq)
+        per = pi[0]
+
+        tdi = tm.box_expected(tdi, box_with_array)
+        pi = tm.box_expected(pi, box_with_array2)
+        msg = "cannot subtract|unsupported operand type"
+        with pytest.raises(TypeError, match=msg):
+            tdi - pi
+
+        # GH#13078 subtraction of Period scalar not supported
+        with pytest.raises(TypeError, match=msg):
+            tdi - per
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            # GH#12624 for str case
+            "a",
+            # GH#19123
+            1,
+            1.5,
+            np.array(2),
+        ],
+    )
+    def test_td64arr_addsub_numeric_scalar_invalid(self, box_with_array, other):
+        # vector-like others are tested in test_td64arr_add_sub_numeric_arr_invalid
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        tdarr = tm.box_expected(tdser, box_with_array)
+
+        assert_invalid_addsub_type(tdarr, other)
+
+    @pytest.mark.parametrize(
+        "vec",
+        [
+            np.array([1, 2, 3]),
+            Index([1, 2, 3]),
+            Series([1, 2, 3]),
+            DataFrame([[1, 2, 3]]),
+        ],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_td64arr_addsub_numeric_arr_invalid(
+        self, box_with_array, vec, any_real_numpy_dtype
+    ):
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        tdarr = tm.box_expected(tdser, box_with_array)
+
+        vector = vec.astype(any_real_numpy_dtype)
+        assert_invalid_addsub_type(tdarr, vector)
+
+    def test_td64arr_add_sub_int(self, box_with_array, one):
+        # Variants of `one` for #19012, deprecated GH#22535
+        rng = timedelta_range("1 days 09:00:00", freq="h", periods=10)
+        tdarr = tm.box_expected(rng, box_with_array)
+
+        msg = "Addition/subtraction of integers"
+        assert_invalid_addsub_type(tdarr, one, msg)
+
+        # TODO: get inplace ops into assert_invalid_addsub_type
+        with pytest.raises(TypeError, match=msg):
+            tdarr += one
+        with pytest.raises(TypeError, match=msg):
+            tdarr -= one
+
+    def test_td64arr_add_sub_integer_array(self, box_with_array):
+        # GH#19959, deprecated GH#22535
+        # GH#22696 for DataFrame case, check that we don't dispatch to numpy
+        #  implementation, which treats int64 as m8[ns]
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        rng = timedelta_range("1 days 09:00:00", freq="h", periods=3)
+        tdarr = tm.box_expected(rng, box)
+        other = tm.box_expected([4, 3, 2], xbox)
+
+        msg = "Addition/subtraction of integers and integer-arrays"
+        assert_invalid_addsub_type(tdarr, other, msg)
+
+    def test_td64arr_addsub_integer_array_no_freq(self, box_with_array):
+        # GH#19959
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        tdi = TimedeltaIndex(["1 Day", "NaT", "3 Hours"])
+        tdarr = tm.box_expected(tdi, box)
+        other = tm.box_expected([14, -1, 16], xbox)
+
+        msg = "Addition/subtraction of integers"
+        assert_invalid_addsub_type(tdarr, other, msg)
+
+    # ------------------------------------------------------------------
+    # Operations with timedelta-like others
+
+    def test_td64arr_add_sub_td64_array(self, box_with_array):
+        box = box_with_array
+        dti = pd.date_range("2016-01-01", periods=3)
+        tdi = dti - dti.shift(1)
+        tdarr = tdi.values
+
+        expected = 2 * tdi
+        tdi = tm.box_expected(tdi, box)
+        expected = tm.box_expected(expected, box)
+
+        result = tdi + tdarr
+        tm.assert_equal(result, expected)
+        result = tdarr + tdi
+        tm.assert_equal(result, expected)
+
+        expected_sub = 0 * tdi
+        result = tdi - tdarr
+        tm.assert_equal(result, expected_sub)
+        result = tdarr - tdi
+        tm.assert_equal(result, expected_sub)
+
+    def test_td64arr_add_sub_tdi(self, box_with_array, names):
+        # GH#17250 make sure result dtype is correct
+        # GH#19043 make sure names are propagated correctly
+        box = box_with_array
+        exname = get_expected_name(box, names)
+
+        tdi = TimedeltaIndex(["0 days", "1 day"], name=names[1])
+        tdi = np.array(tdi) if box in [tm.to_array, pd.array] else tdi
+        ser = Series([Timedelta(hours=3), Timedelta(hours=4)], name=names[0])
+        expected = Series([Timedelta(hours=3), Timedelta(days=1, hours=4)], name=exname)
+
+        ser = tm.box_expected(ser, box)
+        expected = tm.box_expected(expected, box)
+
+        result = tdi + ser
+        tm.assert_equal(result, expected)
+        assert_dtype(result, "timedelta64[ns]")
+
+        result = ser + tdi
+        tm.assert_equal(result, expected)
+        assert_dtype(result, "timedelta64[ns]")
+
+        expected = Series(
+            [Timedelta(hours=-3), Timedelta(days=1, hours=-4)], name=exname
+        )
+        expected = tm.box_expected(expected, box)
+
+        result = tdi - ser
+        tm.assert_equal(result, expected)
+        assert_dtype(result, "timedelta64[ns]")
+
+        result = ser - tdi
+        tm.assert_equal(result, -expected)
+        assert_dtype(result, "timedelta64[ns]")
+
+    @pytest.mark.parametrize("tdnat", [np.timedelta64("NaT"), NaT])
+    def test_td64arr_add_sub_td64_nat(self, box_with_array, tdnat):
+        # GH#18808, GH#23320 special handling for timedelta64("NaT")
+        box = box_with_array
+        tdi = TimedeltaIndex([NaT, Timedelta("1s")])
+        expected = TimedeltaIndex(["NaT"] * 2)
+
+        obj = tm.box_expected(tdi, box)
+        expected = tm.box_expected(expected, box)
+
+        result = obj + tdnat
+        tm.assert_equal(result, expected)
+        result = tdnat + obj
+        tm.assert_equal(result, expected)
+        result = obj - tdnat
+        tm.assert_equal(result, expected)
+        result = tdnat - obj
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_add_timedeltalike(self, two_hours, box_with_array):
+        # only test adding/sub offsets as + is now numeric
+        # GH#10699 for Tick cases
+        box = box_with_array
+        rng = timedelta_range("1 days", "10 days")
+        expected = timedelta_range("1 days 02:00:00", "10 days 02:00:00", freq="D")
+        rng = tm.box_expected(rng, box)
+        expected = tm.box_expected(expected, box)
+
+        result = rng + two_hours
+        tm.assert_equal(result, expected)
+
+        result = two_hours + rng
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_sub_timedeltalike(self, two_hours, box_with_array):
+        # only test adding/sub offsets as - is now numeric
+        # GH#10699 for Tick cases
+        box = box_with_array
+        rng = timedelta_range("1 days", "10 days")
+        expected = timedelta_range("0 days 22:00:00", "9 days 22:00:00")
+
+        rng = tm.box_expected(rng, box)
+        expected = tm.box_expected(expected, box)
+
+        result = rng - two_hours
+        tm.assert_equal(result, expected)
+
+        result = two_hours - rng
+        tm.assert_equal(result, -expected)
+
+    # ------------------------------------------------------------------
+    # __add__/__sub__ with DateOffsets and arrays of DateOffsets
+
+    def test_td64arr_add_sub_offset_index(self, names, box_with_array):
+        # GH#18849, GH#19744
+        box = box_with_array
+        exname = get_expected_name(box, names)
+
+        tdi = TimedeltaIndex(["1 days 00:00:00", "3 days 04:00:00"], name=names[0])
+        other = Index([offsets.Hour(n=1), offsets.Minute(n=-2)], name=names[1])
+        other = np.array(other) if box in [tm.to_array, pd.array] else other
+
+        expected = TimedeltaIndex(
+            [tdi[n] + other[n] for n in range(len(tdi))], freq="infer", name=exname
+        )
+        expected_sub = TimedeltaIndex(
+            [tdi[n] - other[n] for n in range(len(tdi))], freq="infer", name=exname
+        )
+
+        tdi = tm.box_expected(tdi, box)
+        expected = tm.box_expected(expected, box).astype(object, copy=False)
+        expected_sub = tm.box_expected(expected_sub, box).astype(object, copy=False)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = tdi + other
+        tm.assert_equal(res, expected)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res2 = other + tdi
+        tm.assert_equal(res2, expected)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res_sub = tdi - other
+        tm.assert_equal(res_sub, expected_sub)
+
+    def test_td64arr_add_sub_offset_array(self, box_with_array):
+        # GH#18849, GH#18824
+        box = box_with_array
+        tdi = TimedeltaIndex(["1 days 00:00:00", "3 days 04:00:00"])
+        other = np.array([offsets.Hour(n=1), offsets.Minute(n=-2)])
+
+        expected = TimedeltaIndex(
+            [tdi[n] + other[n] for n in range(len(tdi))], freq="infer"
+        )
+        expected_sub = TimedeltaIndex(
+            [tdi[n] - other[n] for n in range(len(tdi))], freq="infer"
+        )
+
+        tdi = tm.box_expected(tdi, box)
+        expected = tm.box_expected(expected, box).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = tdi + other
+        tm.assert_equal(res, expected)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res2 = other + tdi
+        tm.assert_equal(res2, expected)
+
+        expected_sub = tm.box_expected(expected_sub, box_with_array).astype(object)
+        with tm.assert_produces_warning(PerformanceWarning):
+            res_sub = tdi - other
+        tm.assert_equal(res_sub, expected_sub)
+
+    def test_td64arr_with_offset_series(self, names, box_with_array):
+        # GH#18849
+        box = box_with_array
+        box2 = Series if box in [Index, tm.to_array, pd.array] else box
+        exname = get_expected_name(box, names)
+
+        tdi = TimedeltaIndex(["1 days 00:00:00", "3 days 04:00:00"], name=names[0])
+        other = Series([offsets.Hour(n=1), offsets.Minute(n=-2)], name=names[1])
+
+        expected_add = Series(
+            [tdi[n] + other[n] for n in range(len(tdi))], name=exname, dtype=object
+        )
+        obj = tm.box_expected(tdi, box)
+        expected_add = tm.box_expected(expected_add, box2).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res = obj + other
+        tm.assert_equal(res, expected_add)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res2 = other + obj
+        tm.assert_equal(res2, expected_add)
+
+        expected_sub = Series(
+            [tdi[n] - other[n] for n in range(len(tdi))], name=exname, dtype=object
+        )
+        expected_sub = tm.box_expected(expected_sub, box2).astype(object)
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            res3 = obj - other
+        tm.assert_equal(res3, expected_sub)
+
+    @pytest.mark.parametrize("obox", [np.array, Index, Series])
+    def test_td64arr_addsub_anchored_offset_arraylike(self, obox, box_with_array):
+        # GH#18824
+        tdi = TimedeltaIndex(["1 days 00:00:00", "3 days 04:00:00"])
+        tdi = tm.box_expected(tdi, box_with_array)
+
+        anchored = obox([offsets.MonthEnd(), offsets.Day(n=2)])
+
+        # addition/subtraction ops with anchored offsets should issue
+        # a PerformanceWarning and _then_ raise a TypeError.
+        msg = "has incorrect type|cannot add the type MonthEnd"
+        with pytest.raises(TypeError, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                tdi + anchored
+        with pytest.raises(TypeError, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                anchored + tdi
+        with pytest.raises(TypeError, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                tdi - anchored
+        with pytest.raises(TypeError, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                anchored - tdi
+
+    # ------------------------------------------------------------------
+    # Unsorted
+
+    def test_td64arr_add_sub_object_array(self, box_with_array):
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        tdi = timedelta_range("1 day", periods=3, freq="D")
+        tdarr = tm.box_expected(tdi, box)
+
+        other = np.array([Timedelta(days=1), offsets.Day(2), Timestamp("2000-01-04")])
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = tdarr + other
+
+        expected = Index(
+            [Timedelta(days=2), Timedelta(days=4), Timestamp("2000-01-07")]
+        )
+        expected = tm.box_expected(expected, xbox).astype(object)
+        tm.assert_equal(result, expected)
+
+        msg = "unsupported operand type|cannot subtract a datelike"
+        with pytest.raises(TypeError, match=msg):
+            with tm.assert_produces_warning(PerformanceWarning):
+                tdarr - other
+
+        with tm.assert_produces_warning(PerformanceWarning):
+            result = other - tdarr
+
+        expected = Index([Timedelta(0), Timedelta(0), Timestamp("2000-01-01")])
+        expected = tm.box_expected(expected, xbox).astype(object)
+        tm.assert_equal(result, expected)
+
+
+class TestTimedeltaArraylikeMulDivOps:
+    # Tests for timedelta64[ns]
+    # __mul__, __rmul__, __div__, __rdiv__, __floordiv__, __rfloordiv__
+
+    # ------------------------------------------------------------------
+    # Multiplication
+    # organized with scalar others first, then array-like
+
+    def test_td64arr_mul_int(self, box_with_array):
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box_with_array)
+
+        result = idx * 1
+        tm.assert_equal(result, idx)
+
+        result = 1 * idx
+        tm.assert_equal(result, idx)
+
+    def test_td64arr_mul_tdlike_scalar_raises(self, two_hours, box_with_array):
+        rng = timedelta_range("1 days", "10 days", name="foo")
+        rng = tm.box_expected(rng, box_with_array)
+        msg = "|".join(
+            [
+                "argument must be an integer",
+                "cannot use operands with types dtype",
+                "Cannot multiply with",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            rng * two_hours
+
+    def test_tdi_mul_int_array_zerodim(self, box_with_array):
+        rng5 = np.arange(5, dtype="int64")
+        idx = TimedeltaIndex(rng5)
+        expected = TimedeltaIndex(rng5 * 5)
+
+        idx = tm.box_expected(idx, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = idx * np.array(5, dtype="int64")
+        tm.assert_equal(result, expected)
+
+    def test_tdi_mul_int_array(self, box_with_array):
+        rng5 = np.arange(5, dtype="int64")
+        idx = TimedeltaIndex(rng5)
+        expected = TimedeltaIndex(rng5**2)
+
+        idx = tm.box_expected(idx, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = idx * rng5
+        tm.assert_equal(result, expected)
+
+    def test_tdi_mul_int_series(self, box_with_array):
+        box = box_with_array
+        xbox = Series if box in [Index, tm.to_array, pd.array] else box
+
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        expected = TimedeltaIndex(np.arange(5, dtype="int64") ** 2)
+
+        idx = tm.box_expected(idx, box)
+        expected = tm.box_expected(expected, xbox)
+
+        result = idx * Series(np.arange(5, dtype="int64"))
+        tm.assert_equal(result, expected)
+
+    def test_tdi_mul_float_series(self, box_with_array):
+        box = box_with_array
+        xbox = Series if box in [Index, tm.to_array, pd.array] else box
+
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box)
+
+        rng5f = np.arange(5, dtype="float64")
+        expected = TimedeltaIndex(rng5f * (rng5f + 1.0))
+        expected = tm.box_expected(expected, xbox)
+
+        result = idx * Series(rng5f + 1.0)
+        tm.assert_equal(result, expected)
+
+    # TODO: Put Series/DataFrame in others?
+    @pytest.mark.parametrize(
+        "other",
+        [
+            np.arange(1, 11),
+            Index(np.arange(1, 11), np.int64),
+            Index(range(1, 11), np.uint64),
+            Index(range(1, 11), np.float64),
+            pd.RangeIndex(1, 11),
+        ],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_tdi_rmul_arraylike(self, other, box_with_array):
+        box = box_with_array
+
+        tdi = TimedeltaIndex(["1 Day"] * 10)
+        expected = timedelta_range("1 days", "10 days")._with_freq(None)
+
+        tdi = tm.box_expected(tdi, box)
+        xbox = get_upcast_box(tdi, other)
+
+        expected = tm.box_expected(expected, xbox)
+
+        result = other * tdi
+        tm.assert_equal(result, expected)
+        commute = tdi * other
+        tm.assert_equal(commute, expected)
+
+    # ------------------------------------------------------------------
+    # __div__, __rdiv__
+
+    def test_td64arr_div_nat_invalid(self, box_with_array):
+        # don't allow division by NaT (maybe could in the future)
+        rng = timedelta_range("1 days", "10 days", name="foo")
+        rng = tm.box_expected(rng, box_with_array)
+
+        with pytest.raises(TypeError, match="unsupported operand type"):
+            rng / NaT
+        with pytest.raises(TypeError, match="Cannot divide NaTType by"):
+            NaT / rng
+
+        dt64nat = np.datetime64("NaT", "ns")
+        msg = "|".join(
+            [
+                # 'divide' on npdev as of 2021-12-18
+                "ufunc '(true_divide|divide)' cannot use operands",
+                "cannot perform __r?truediv__",
+                "Cannot divide datetime64 by TimedeltaArray",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            rng / dt64nat
+        with pytest.raises(TypeError, match=msg):
+            dt64nat / rng
+
+    def test_td64arr_div_td64nat(self, box_with_array):
+        # GH#23829
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        rng = timedelta_range("1 days", "10 days")
+        rng = tm.box_expected(rng, box)
+
+        other = np.timedelta64("NaT")
+
+        expected = np.array([np.nan] * 10)
+        expected = tm.box_expected(expected, xbox)
+
+        result = rng / other
+        tm.assert_equal(result, expected)
+
+        result = other / rng
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_div_int(self, box_with_array):
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box_with_array)
+
+        result = idx / 1
+        tm.assert_equal(result, idx)
+
+        with pytest.raises(TypeError, match="Cannot divide"):
+            # GH#23829
+            1 / idx
+
+    def test_td64arr_div_tdlike_scalar(self, two_hours, box_with_array):
+        # GH#20088, GH#22163 ensure DataFrame returns correct dtype
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        rng = timedelta_range("1 days", "10 days", name="foo")
+        expected = Index((np.arange(10) + 1) * 12, dtype=np.float64, name="foo")
+
+        rng = tm.box_expected(rng, box)
+        expected = tm.box_expected(expected, xbox)
+
+        result = rng / two_hours
+        tm.assert_equal(result, expected)
+
+        result = two_hours / rng
+        expected = 1 / expected
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize("m", [1, 3, 10])
+    @pytest.mark.parametrize("unit", ["D", "h", "m", "s", "ms", "us", "ns"])
+    def test_td64arr_div_td64_scalar(self, m, unit, box_with_array):
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        ser = Series([Timedelta(days=59)] * 3)
+        ser[2] = np.nan
+        flat = ser
+        ser = tm.box_expected(ser, box)
+
+        # op
+        expected = Series([x / np.timedelta64(m, unit) for x in flat])
+        expected = tm.box_expected(expected, xbox)
+        result = ser / np.timedelta64(m, unit)
+        tm.assert_equal(result, expected)
+
+        # reverse op
+        expected = Series([Timedelta(np.timedelta64(m, unit)) / x for x in flat])
+        expected = tm.box_expected(expected, xbox)
+        result = np.timedelta64(m, unit) / ser
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_div_tdlike_scalar_with_nat(self, two_hours, box_with_array):
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        rng = TimedeltaIndex(["1 days", NaT, "2 days"], name="foo")
+        expected = Index([12, np.nan, 24], dtype=np.float64, name="foo")
+
+        rng = tm.box_expected(rng, box)
+        expected = tm.box_expected(expected, xbox)
+
+        result = rng / two_hours
+        tm.assert_equal(result, expected)
+
+        result = two_hours / rng
+        expected = 1 / expected
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_div_td64_ndarray(self, box_with_array):
+        # GH#22631
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        rng = TimedeltaIndex(["1 days", NaT, "2 days"])
+        expected = Index([12, np.nan, 24], dtype=np.float64)
+
+        rng = tm.box_expected(rng, box)
+        expected = tm.box_expected(expected, xbox)
+
+        other = np.array([2, 4, 2], dtype="m8[h]")
+        result = rng / other
+        tm.assert_equal(result, expected)
+
+        result = rng / tm.box_expected(other, box)
+        tm.assert_equal(result, expected)
+
+        result = rng / other.astype(object)
+        tm.assert_equal(result, expected.astype(object))
+
+        result = rng / list(other)
+        tm.assert_equal(result, expected)
+
+        # reversed op
+        expected = 1 / expected
+        result = other / rng
+        tm.assert_equal(result, expected)
+
+        result = tm.box_expected(other, box) / rng
+        tm.assert_equal(result, expected)
+
+        result = other.astype(object) / rng
+        tm.assert_equal(result, expected)
+
+        result = list(other) / rng
+        tm.assert_equal(result, expected)
+
+    def test_tdarr_div_length_mismatch(self, box_with_array):
+        rng = TimedeltaIndex(["1 days", NaT, "2 days"])
+        mismatched = [1, 2, 3, 4]
+
+        rng = tm.box_expected(rng, box_with_array)
+        msg = "Cannot divide vectors|Unable to coerce to Series"
+        for obj in [mismatched, mismatched[:2]]:
+            # one shorter, one longer
+            for other in [obj, np.array(obj), Index(obj)]:
+                with pytest.raises(ValueError, match=msg):
+                    rng / other
+                with pytest.raises(ValueError, match=msg):
+                    other / rng
+
+    def test_td64_div_object_mixed_result(self, box_with_array):
+        # Case where we having a NaT in the result inseat of timedelta64("NaT")
+        #  is misleading
+        orig = timedelta_range("1 Day", periods=3).insert(1, NaT)
+        tdi = tm.box_expected(orig, box_with_array, transpose=False)
+
+        other = np.array([orig[0], 1.5, 2.0, orig[2]], dtype=object)
+        other = tm.box_expected(other, box_with_array, transpose=False)
+
+        res = tdi / other
+
+        expected = Index([1.0, np.timedelta64("NaT", "ns"), orig[0], 1.5], dtype=object)
+        expected = tm.box_expected(expected, box_with_array, transpose=False)
+        if isinstance(expected, NumpyExtensionArray):
+            expected = expected.to_numpy()
+        tm.assert_equal(res, expected)
+        if box_with_array is DataFrame:
+            # We have a np.timedelta64(NaT), not pd.NaT
+            assert isinstance(res.iloc[1, 0], np.timedelta64)
+
+        res = tdi // other
+
+        expected = Index([1, np.timedelta64("NaT", "ns"), orig[0], 1], dtype=object)
+        expected = tm.box_expected(expected, box_with_array, transpose=False)
+        if isinstance(expected, NumpyExtensionArray):
+            expected = expected.to_numpy()
+        tm.assert_equal(res, expected)
+        if box_with_array is DataFrame:
+            # We have a np.timedelta64(NaT), not pd.NaT
+            assert isinstance(res.iloc[1, 0], np.timedelta64)
+
+    # ------------------------------------------------------------------
+    # __floordiv__, __rfloordiv__
+
+    def test_td64arr_floordiv_td64arr_with_nat(
+        self, box_with_array, using_array_manager
+    ):
+        # GH#35529
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+
+        left = Series([1000, 222330, 30], dtype="timedelta64[ns]")
+        right = Series([1000, 222330, None], dtype="timedelta64[ns]")
+
+        left = tm.box_expected(left, box)
+        right = tm.box_expected(right, box)
+
+        expected = np.array([1.0, 1.0, np.nan], dtype=np.float64)
+        expected = tm.box_expected(expected, xbox)
+        if box is DataFrame and using_array_manager:
+            # INFO(ArrayManager) floordiv returns integer, and ArrayManager
+            # performs ops column-wise and thus preserves int64 dtype for
+            # columns without missing values
+            expected[[0, 1]] = expected[[0, 1]].astype("int64")
+
+        with tm.maybe_produces_warning(
+            RuntimeWarning, box is pd.array, check_stacklevel=False
+        ):
+            result = left // right
+
+        tm.assert_equal(result, expected)
+
+        # case that goes through __rfloordiv__ with arraylike
+        with tm.maybe_produces_warning(
+            RuntimeWarning, box is pd.array, check_stacklevel=False
+        ):
+            result = np.asarray(left) // right
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.filterwarnings("ignore:invalid value encountered:RuntimeWarning")
+    def test_td64arr_floordiv_tdscalar(self, box_with_array, scalar_td):
+        # GH#18831, GH#19125
+        box = box_with_array
+        xbox = np.ndarray if box is pd.array else box
+        td = Timedelta("5m3s")  # i.e. (scalar_td - 1sec) / 2
+
+        td1 = Series([td, td, NaT], dtype="m8[ns]")
+        td1 = tm.box_expected(td1, box, transpose=False)
+
+        expected = Series([0, 0, np.nan])
+        expected = tm.box_expected(expected, xbox, transpose=False)
+
+        result = td1 // scalar_td
+        tm.assert_equal(result, expected)
+
+        # Reversed op
+        expected = Series([2, 2, np.nan])
+        expected = tm.box_expected(expected, xbox, transpose=False)
+
+        result = scalar_td // td1
+        tm.assert_equal(result, expected)
+
+        # same thing buts let's be explicit about calling __rfloordiv__
+        result = td1.__rfloordiv__(scalar_td)
+        tm.assert_equal(result, expected)
+
+    def test_td64arr_floordiv_int(self, box_with_array):
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box_with_array)
+        result = idx // 1
+        tm.assert_equal(result, idx)
+
+        pattern = "floor_divide cannot use operands|Cannot divide int by Timedelta*"
+        with pytest.raises(TypeError, match=pattern):
+            1 // idx
+
+    # ------------------------------------------------------------------
+    # mod, divmod
+    # TODO: operations with timedelta-like arrays, numeric arrays,
+    #  reversed ops
+
+    def test_td64arr_mod_tdscalar(self, box_with_array, three_days):
+        tdi = timedelta_range("1 Day", "9 days")
+        tdarr = tm.box_expected(tdi, box_with_array)
+
+        expected = TimedeltaIndex(["1 Day", "2 Days", "0 Days"] * 3)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdarr % three_days
+        tm.assert_equal(result, expected)
+
+        warn = None
+        if box_with_array is DataFrame and isinstance(three_days, pd.DateOffset):
+            warn = PerformanceWarning
+            # TODO: making expected be object here a result of DataFrame.__divmod__
+            #  being defined in a naive way that does not dispatch to the underlying
+            #  array's __divmod__
+            expected = expected.astype(object)
+
+        with tm.assert_produces_warning(warn):
+            result = divmod(tdarr, three_days)
+
+        tm.assert_equal(result[1], expected)
+        tm.assert_equal(result[0], tdarr // three_days)
+
+    def test_td64arr_mod_int(self, box_with_array):
+        tdi = timedelta_range("1 ns", "10 ns", periods=10)
+        tdarr = tm.box_expected(tdi, box_with_array)
+
+        expected = TimedeltaIndex(["1 ns", "0 ns"] * 5)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdarr % 2
+        tm.assert_equal(result, expected)
+
+        msg = "Cannot divide int by"
+        with pytest.raises(TypeError, match=msg):
+            2 % tdarr
+
+        result = divmod(tdarr, 2)
+        tm.assert_equal(result[1], expected)
+        tm.assert_equal(result[0], tdarr // 2)
+
+    def test_td64arr_rmod_tdscalar(self, box_with_array, three_days):
+        tdi = timedelta_range("1 Day", "9 days")
+        tdarr = tm.box_expected(tdi, box_with_array)
+
+        expected = ["0 Days", "1 Day", "0 Days"] + ["3 Days"] * 6
+        expected = TimedeltaIndex(expected)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = three_days % tdarr
+        tm.assert_equal(result, expected)
+
+        result = divmod(three_days, tdarr)
+        tm.assert_equal(result[1], expected)
+        tm.assert_equal(result[0], three_days // tdarr)
+
+    # ------------------------------------------------------------------
+    # Operations with invalid others
+
+    def test_td64arr_mul_tdscalar_invalid(self, box_with_array, scalar_td):
+        td1 = Series([timedelta(minutes=5, seconds=3)] * 3)
+        td1.iloc[2] = np.nan
+
+        td1 = tm.box_expected(td1, box_with_array)
+
+        # check that we are getting a TypeError
+        # with 'operate' (from core/ops.py) for the ops that are not
+        # defined
+        pattern = "operate|unsupported|cannot|not supported"
+        with pytest.raises(TypeError, match=pattern):
+            td1 * scalar_td
+        with pytest.raises(TypeError, match=pattern):
+            scalar_td * td1
+
+    def test_td64arr_mul_too_short_raises(self, box_with_array):
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box_with_array)
+        msg = "|".join(
+            [
+                "cannot use operands with types dtype",
+                "Cannot multiply with unequal lengths",
+                "Unable to coerce to Series",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            # length check before dtype check
+            idx * idx[:3]
+        with pytest.raises(ValueError, match=msg):
+            idx * np.array([1, 2])
+
+    def test_td64arr_mul_td64arr_raises(self, box_with_array):
+        idx = TimedeltaIndex(np.arange(5, dtype="int64"))
+        idx = tm.box_expected(idx, box_with_array)
+        msg = "cannot use operands with types dtype"
+        with pytest.raises(TypeError, match=msg):
+            idx * idx
+
+    # ------------------------------------------------------------------
+    # Operations with numeric others
+
+    def test_td64arr_mul_numeric_scalar(self, box_with_array, one):
+        # GH#4521
+        # divide/multiply by integers
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        expected = Series(["-59 Days", "-59 Days", "NaT"], dtype="timedelta64[ns]")
+
+        tdser = tm.box_expected(tdser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdser * (-one)
+        tm.assert_equal(result, expected)
+        result = (-one) * tdser
+        tm.assert_equal(result, expected)
+
+        expected = Series(["118 Days", "118 Days", "NaT"], dtype="timedelta64[ns]")
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdser * (2 * one)
+        tm.assert_equal(result, expected)
+        result = (2 * one) * tdser
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize("two", [2, 2.0, np.array(2), np.array(2.0)])
+    def test_td64arr_div_numeric_scalar(self, box_with_array, two):
+        # GH#4521
+        # divide/multiply by integers
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        expected = Series(["29.5D", "29.5D", "NaT"], dtype="timedelta64[ns]")
+
+        tdser = tm.box_expected(tdser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdser / two
+        tm.assert_equal(result, expected)
+
+        with pytest.raises(TypeError, match="Cannot divide"):
+            two / tdser
+
+    @pytest.mark.parametrize("two", [2, 2.0, np.array(2), np.array(2.0)])
+    def test_td64arr_floordiv_numeric_scalar(self, box_with_array, two):
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        expected = Series(["29.5D", "29.5D", "NaT"], dtype="timedelta64[ns]")
+
+        tdser = tm.box_expected(tdser, box_with_array)
+        expected = tm.box_expected(expected, box_with_array)
+
+        result = tdser // two
+        tm.assert_equal(result, expected)
+
+        with pytest.raises(TypeError, match="Cannot divide"):
+            two // tdser
+
+    @pytest.mark.parametrize(
+        "vector",
+        [np.array([20, 30, 40]), Index([20, 30, 40]), Series([20, 30, 40])],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_td64arr_rmul_numeric_array(
+        self,
+        box_with_array,
+        vector,
+        any_real_numpy_dtype,
+    ):
+        # GH#4521
+        # divide/multiply by integers
+
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        vector = vector.astype(any_real_numpy_dtype)
+
+        expected = Series(["1180 Days", "1770 Days", "NaT"], dtype="timedelta64[ns]")
+
+        tdser = tm.box_expected(tdser, box_with_array)
+        xbox = get_upcast_box(tdser, vector)
+
+        expected = tm.box_expected(expected, xbox)
+
+        result = tdser * vector
+        tm.assert_equal(result, expected)
+
+        result = vector * tdser
+        tm.assert_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "vector",
+        [np.array([20, 30, 40]), Index([20, 30, 40]), Series([20, 30, 40])],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_td64arr_div_numeric_array(
+        self, box_with_array, vector, any_real_numpy_dtype
+    ):
+        # GH#4521
+        # divide/multiply by integers
+
+        tdser = Series(["59 Days", "59 Days", "NaT"], dtype="m8[ns]")
+        vector = vector.astype(any_real_numpy_dtype)
+
+        expected = Series(["2.95D", "1D 23h 12m", "NaT"], dtype="timedelta64[ns]")
+
+        tdser = tm.box_expected(tdser, box_with_array)
+        xbox = get_upcast_box(tdser, vector)
+        expected = tm.box_expected(expected, xbox)
+
+        result = tdser / vector
+        tm.assert_equal(result, expected)
+
+        pattern = "|".join(
+            [
+                "true_divide'? cannot use operands",
+                "cannot perform __div__",
+                "cannot perform __truediv__",
+                "unsupported operand",
+                "Cannot divide",
+                "ufunc 'divide' cannot use operands with types",
+            ]
+        )
+        with pytest.raises(TypeError, match=pattern):
+            vector / tdser
+
+        result = tdser / vector.astype(object)
+        if box_with_array is DataFrame:
+            expected = [tdser.iloc[0, n] / vector[n] for n in range(len(vector))]
+            expected = tm.box_expected(expected, xbox).astype(object)
+            # We specifically expect timedelta64("NaT") here, not pd.NA
+            msg = "The 'downcast' keyword in fillna"
+            with tm.assert_produces_warning(FutureWarning, match=msg):
+                expected[2] = expected[2].fillna(
+                    np.timedelta64("NaT", "ns"), downcast=False
+                )
+        else:
+            expected = [tdser[n] / vector[n] for n in range(len(tdser))]
+            expected = [
+                x if x is not NaT else np.timedelta64("NaT", "ns") for x in expected
+            ]
+            if xbox is tm.to_array:
+                expected = tm.to_array(expected).astype(object)
+            else:
+                expected = xbox(expected, dtype=object)
+
+        tm.assert_equal(result, expected)
+
+        with pytest.raises(TypeError, match=pattern):
+            vector.astype(object) / tdser
+
+    def test_td64arr_mul_int_series(self, box_with_array, names):
+        # GH#19042 test for correct name attachment
+        box = box_with_array
+        exname = get_expected_name(box, names)
+
+        tdi = TimedeltaIndex(
+            ["0days", "1day", "2days", "3days", "4days"], name=names[0]
+        )
+        # TODO: Should we be parametrizing over types for `ser` too?
+        ser = Series([0, 1, 2, 3, 4], dtype=np.int64, name=names[1])
+
+        expected = Series(
+            ["0days", "1day", "4days", "9days", "16days"],
+            dtype="timedelta64[ns]",
+            name=exname,
+        )
+
+        tdi = tm.box_expected(tdi, box)
+        xbox = get_upcast_box(tdi, ser)
+
+        expected = tm.box_expected(expected, xbox)
+
+        result = ser * tdi
+        tm.assert_equal(result, expected)
+
+        result = tdi * ser
+        tm.assert_equal(result, expected)
+
+    # TODO: Should we be parametrizing over types for `ser` too?
+    def test_float_series_rdiv_td64arr(self, box_with_array, names):
+        # GH#19042 test for correct name attachment
+        box = box_with_array
+        tdi = TimedeltaIndex(
+            ["0days", "1day", "2days", "3days", "4days"], name=names[0]
+        )
+        ser = Series([1.5, 3, 4.5, 6, 7.5], dtype=np.float64, name=names[1])
+
+        xname = names[2] if box not in [tm.to_array, pd.array] else names[1]
+        expected = Series(
+            [tdi[n] / ser[n] for n in range(len(ser))],
+            dtype="timedelta64[ns]",
+            name=xname,
+        )
+
+        tdi = tm.box_expected(tdi, box)
+        xbox = get_upcast_box(tdi, ser)
+        expected = tm.box_expected(expected, xbox)
+
+        result = ser.__rtruediv__(tdi)
+        if box is DataFrame:
+            assert result is NotImplemented
+        else:
+            tm.assert_equal(result, expected)
+
+    def test_td64arr_all_nat_div_object_dtype_numeric(self, box_with_array):
+        # GH#39750 make sure we infer the result as td64
+        tdi = TimedeltaIndex([NaT, NaT])
+
+        left = tm.box_expected(tdi, box_with_array)
+        right = np.array([2, 2.0], dtype=object)
+
+        tdnat = np.timedelta64("NaT", "ns")
+        expected = Index([tdnat] * 2, dtype=object)
+        if box_with_array is not Index:
+            expected = tm.box_expected(expected, box_with_array).astype(object)
+            if box_with_array in [Series, DataFrame]:
+                msg = "The 'downcast' keyword in fillna is deprecated"
+                with tm.assert_produces_warning(FutureWarning, match=msg):
+                    expected = expected.fillna(tdnat, downcast=False)  # GH#18463
+
+        result = left / right
+        tm.assert_equal(result, expected)
+
+        result = left // right
+        tm.assert_equal(result, expected)
+
+
+class TestTimedelta64ArrayLikeArithmetic:
+    # Arithmetic tests for timedelta64[ns] vectors fully parametrized over
+    #  DataFrame/Series/TimedeltaIndex/TimedeltaArray.  Ideally all arithmetic
+    #  tests will eventually end up here.
+
+    def test_td64arr_pow_invalid(self, scalar_td, box_with_array):
+        td1 = Series([timedelta(minutes=5, seconds=3)] * 3)
+        td1.iloc[2] = np.nan
+
+        td1 = tm.box_expected(td1, box_with_array)
+
+        # check that we are getting a TypeError
+        # with 'operate' (from core/ops.py) for the ops that are not
+        # defined
+        pattern = "operate|unsupported|cannot|not supported"
+        with pytest.raises(TypeError, match=pattern):
+            scalar_td**td1
+
+        with pytest.raises(TypeError, match=pattern):
+            td1**scalar_td
+
+
+def test_add_timestamp_to_timedelta():
+    # GH: 35897
+    timestamp = Timestamp("2021-01-01")
+    result = timestamp + timedelta_range("0s", "1s", periods=31)
+    expected = DatetimeIndex(
+        [
+            timestamp
+            + (
+                pd.to_timedelta("0.033333333s") * i
+                + pd.to_timedelta("0.000000001s") * divmod(i, 3)[0]
+            )
+            for i in range(31)
+        ]
+    )
+    tm.assert_index_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_arithmetic.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_arithmetic.py
new file mode 100644
index 0000000000000000000000000000000000000000..9ff690cdc914d7f81d134a2bc93287fb914067e2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_arithmetic.py
@@ -0,0 +1,134 @@
+import operator
+
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.fixture
+def data():
+    """Fixture returning boolean array with valid and missing values."""
+    return pd.array(
+        [True, False] * 4 + [np.nan] + [True, False] * 44 + [np.nan] + [True, False],
+        dtype="boolean",
+    )
+
+
+@pytest.fixture
+def left_array():
+    """Fixture returning boolean array with valid and missing values."""
+    return pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+
+
+@pytest.fixture
+def right_array():
+    """Fixture returning boolean array with valid and missing values."""
+    return pd.array([True, False, None] * 3, dtype="boolean")
+
+
+# Basic test for the arithmetic array ops
+# -----------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "opname, exp",
+    [
+        ("add", [True, True, None, True, False, None, None, None, None]),
+        ("mul", [True, False, None, False, False, None, None, None, None]),
+    ],
+    ids=["add", "mul"],
+)
+def test_add_mul(left_array, right_array, opname, exp):
+    op = getattr(operator, opname)
+    result = op(left_array, right_array)
+    expected = pd.array(exp, dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_sub(left_array, right_array):
+    msg = (
+        r"numpy boolean subtract, the `-` operator, is (?:deprecated|not supported), "
+        r"use the bitwise_xor, the `\^` operator, or the logical_xor function instead\."
+    )
+    with pytest.raises(TypeError, match=msg):
+        left_array - right_array
+
+
+def test_div(left_array, right_array):
+    msg = "operator '.*' not implemented for bool dtypes"
+    with pytest.raises(NotImplementedError, match=msg):
+        # check that we are matching the non-masked Series behavior
+        pd.Series(left_array._data) / pd.Series(right_array._data)
+
+    with pytest.raises(NotImplementedError, match=msg):
+        left_array / right_array
+
+
+@pytest.mark.parametrize(
+    "opname",
+    [
+        "floordiv",
+        "mod",
+        "pow",
+    ],
+)
+def test_op_int8(left_array, right_array, opname):
+    op = getattr(operator, opname)
+    if opname != "mod":
+        msg = "operator '.*' not implemented for bool dtypes"
+        with pytest.raises(NotImplementedError, match=msg):
+            result = op(left_array, right_array)
+        return
+    result = op(left_array, right_array)
+    expected = op(left_array.astype("Int8"), right_array.astype("Int8"))
+    tm.assert_extension_array_equal(result, expected)
+
+
+# Test generic characteristics / errors
+# -----------------------------------------------------------------------------
+
+
+def test_error_invalid_values(data, all_arithmetic_operators):
+    # invalid ops
+    op = all_arithmetic_operators
+    s = pd.Series(data)
+    ops = getattr(s, op)
+
+    # invalid scalars
+    msg = (
+        "did not contain a loop with signature matching types|"
+        "BooleanArray cannot perform the operation|"
+        "not supported for the input types, and the inputs could not be safely coerced "
+        "to any supported types according to the casting rule ''safe''|"
+        "not supported for dtype"
+    )
+    with pytest.raises(TypeError, match=msg):
+        ops("foo")
+    msg = "|".join(
+        [
+            r"unsupported operand type\(s\) for",
+            "Concatenation operation is not implemented for NumPy arrays",
+            "has no kernel",
+            "not supported for dtype",
+        ]
+    )
+    with pytest.raises(TypeError, match=msg):
+        ops(pd.Timestamp("20180101"))
+
+    # invalid array-likes
+    if op not in ("__mul__", "__rmul__"):
+        # TODO(extension) numpy's mul with object array sees booleans as numbers
+        msg = "|".join(
+            [
+                r"unsupported operand type\(s\) for",
+                "can only concatenate str",
+                "not all arguments converted during string formatting",
+                "has no kernel",
+                "not implemented",
+                "not supported for dtype",
+            ]
+        )
+        with pytest.raises(TypeError, match=msg):
+            ops(pd.Series("foo", index=s.index))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_astype.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_astype.py
new file mode 100644
index 0000000000000000000000000000000000000000..8c2672218f273c6ff39ae0a0b9c86f21879e45f3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_astype.py
@@ -0,0 +1,59 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+def test_astype(using_infer_string):
+    # with missing values
+    arr = pd.array([True, False, None], dtype="boolean")
+
+    with pytest.raises(ValueError, match="cannot convert NA to integer"):
+        arr.astype("int64")
+
+    with pytest.raises(ValueError, match="cannot convert float NaN to"):
+        arr.astype("bool")
+
+    result = arr.astype("float64")
+    expected = np.array([1, 0, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.astype("str")
+    if using_infer_string:
+        expected = pd.array(
+            ["True", "False", None], dtype=pd.StringDtype(na_value=np.nan)
+        )
+        tm.assert_extension_array_equal(result, expected)
+    else:
+        expected = np.array(["True", "False", ""], dtype=f"{tm.ENDIAN}U5")
+        tm.assert_numpy_array_equal(result, expected)
+
+    # no missing values
+    arr = pd.array([True, False, True], dtype="boolean")
+    result = arr.astype("int64")
+    expected = np.array([1, 0, 1], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.astype("bool")
+    expected = np.array([True, False, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_astype_to_boolean_array():
+    # astype to BooleanArray
+    arr = pd.array([True, False, None], dtype="boolean")
+
+    result = arr.astype("boolean")
+    tm.assert_extension_array_equal(result, arr)
+    result = arr.astype(pd.BooleanDtype())
+    tm.assert_extension_array_equal(result, arr)
+
+
+def test_astype_to_integer_array():
+    # astype to IntegerArray
+    arr = pd.array([True, False, None], dtype="boolean")
+
+    result = arr.astype("Int64")
+    expected = pd.array([1, 0, None], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_comparison.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_comparison.py
new file mode 100644
index 0000000000000000000000000000000000000000..2eeb9da574b1e7973d98390ada40f23f57526203
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_comparison.py
@@ -0,0 +1,60 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.arrays import BooleanArray
+from pandas.tests.arrays.masked_shared import ComparisonOps
+
+
+@pytest.fixture
+def data():
+    """Fixture returning boolean array with valid and missing data"""
+    return pd.array(
+        [True, False] * 4 + [np.nan] + [True, False] * 44 + [np.nan] + [True, False],
+        dtype="boolean",
+    )
+
+
+@pytest.fixture
+def dtype():
+    """Fixture returning BooleanDtype"""
+    return pd.BooleanDtype()
+
+
+class TestComparisonOps(ComparisonOps):
+    def test_compare_scalar(self, data, comparison_op):
+        self._compare_other(data, comparison_op, True)
+
+    def test_compare_array(self, data, comparison_op):
+        other = pd.array([True] * len(data), dtype="boolean")
+        self._compare_other(data, comparison_op, other)
+        other = np.array([True] * len(data))
+        self._compare_other(data, comparison_op, other)
+        other = pd.Series([True] * len(data))
+        self._compare_other(data, comparison_op, other)
+
+    @pytest.mark.parametrize("other", [True, False, pd.NA])
+    def test_scalar(self, other, comparison_op, dtype):
+        ComparisonOps.test_scalar(self, other, comparison_op, dtype)
+
+    def test_array(self, comparison_op):
+        op = comparison_op
+        a = pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        b = pd.array([True, False, None] * 3, dtype="boolean")
+
+        result = op(a, b)
+
+        values = op(a._data, b._data)
+        mask = a._mask | b._mask
+        expected = BooleanArray(values, mask)
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        result[0] = None
+        tm.assert_extension_array_equal(
+            a, pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        )
+        tm.assert_extension_array_equal(
+            b, pd.array([True, False, None] * 3, dtype="boolean")
+        )
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_construction.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_construction.py
new file mode 100644
index 0000000000000000000000000000000000000000..645e763fbf00cec4f62474fc7d2d2be564a4e4ba
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_construction.py
@@ -0,0 +1,325 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.arrays import BooleanArray
+from pandas.core.arrays.boolean import coerce_to_array
+
+
+def test_boolean_array_constructor():
+    values = np.array([True, False, True, False], dtype="bool")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = BooleanArray(values, mask)
+    expected = pd.array([True, False, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+    with pytest.raises(TypeError, match="values should be boolean numpy array"):
+        BooleanArray(values.tolist(), mask)
+
+    with pytest.raises(TypeError, match="mask should be boolean numpy array"):
+        BooleanArray(values, mask.tolist())
+
+    with pytest.raises(TypeError, match="values should be boolean numpy array"):
+        BooleanArray(values.astype(int), mask)
+
+    with pytest.raises(TypeError, match="mask should be boolean numpy array"):
+        BooleanArray(values, None)
+
+    with pytest.raises(ValueError, match="values.shape must match mask.shape"):
+        BooleanArray(values.reshape(1, -1), mask)
+
+    with pytest.raises(ValueError, match="values.shape must match mask.shape"):
+        BooleanArray(values, mask.reshape(1, -1))
+
+
+def test_boolean_array_constructor_copy():
+    values = np.array([True, False, True, False], dtype="bool")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = BooleanArray(values, mask)
+    assert result._data is values
+    assert result._mask is mask
+
+    result = BooleanArray(values, mask, copy=True)
+    assert result._data is not values
+    assert result._mask is not mask
+
+
+def test_to_boolean_array():
+    expected = BooleanArray(
+        np.array([True, False, True]), np.array([False, False, False])
+    )
+
+    result = pd.array([True, False, True], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+    result = pd.array(np.array([True, False, True]), dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+    result = pd.array(np.array([True, False, True], dtype=object), dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+    # with missing values
+    expected = BooleanArray(
+        np.array([True, False, True]), np.array([False, False, True])
+    )
+
+    result = pd.array([True, False, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+    result = pd.array(np.array([True, False, None], dtype=object), dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_to_boolean_array_all_none():
+    expected = BooleanArray(np.array([True, True, True]), np.array([True, True, True]))
+
+    result = pd.array([None, None, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+    result = pd.array(np.array([None, None, None], dtype=object), dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "a, b",
+    [
+        ([True, False, None, np.nan, pd.NA], [True, False, None, None, None]),
+        ([True, np.nan], [True, None]),
+        ([True, pd.NA], [True, None]),
+        ([np.nan, np.nan], [None, None]),
+        (np.array([np.nan, np.nan], dtype=float), [None, None]),
+    ],
+)
+def test_to_boolean_array_missing_indicators(a, b):
+    result = pd.array(a, dtype="boolean")
+    expected = pd.array(b, dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        ["foo", "bar"],
+        ["1", "2"],
+        # "foo",
+        [1, 2],
+        [1.0, 2.0],
+        pd.date_range("20130101", periods=2),
+        np.array(["foo"]),
+        np.array([1, 2]),
+        np.array([1.0, 2.0]),
+        [np.nan, {"a": 1}],
+    ],
+)
+def test_to_boolean_array_error(values):
+    # error in converting existing arrays to BooleanArray
+    msg = "Need to pass bool-like value"
+    with pytest.raises(TypeError, match=msg):
+        pd.array(values, dtype="boolean")
+
+
+def test_to_boolean_array_from_integer_array():
+    result = pd.array(np.array([1, 0, 1, 0]), dtype="boolean")
+    expected = pd.array([True, False, True, False], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+    # with missing values
+    result = pd.array(np.array([1, 0, 1, None]), dtype="boolean")
+    expected = pd.array([True, False, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_to_boolean_array_from_float_array():
+    result = pd.array(np.array([1.0, 0.0, 1.0, 0.0]), dtype="boolean")
+    expected = pd.array([True, False, True, False], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+    # with missing values
+    result = pd.array(np.array([1.0, 0.0, 1.0, np.nan]), dtype="boolean")
+    expected = pd.array([True, False, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_to_boolean_array_integer_like():
+    # integers of 0's and 1's
+    result = pd.array([1, 0, 1, 0], dtype="boolean")
+    expected = pd.array([True, False, True, False], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+    # with missing values
+    result = pd.array([1, 0, 1, None], dtype="boolean")
+    expected = pd.array([True, False, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_coerce_to_array():
+    # TODO this is currently not public API
+    values = np.array([True, False, True, False], dtype="bool")
+    mask = np.array([False, False, False, True], dtype="bool")
+    result = BooleanArray(*coerce_to_array(values, mask=mask))
+    expected = BooleanArray(values, mask)
+    tm.assert_extension_array_equal(result, expected)
+    assert result._data is values
+    assert result._mask is mask
+    result = BooleanArray(*coerce_to_array(values, mask=mask, copy=True))
+    expected = BooleanArray(values, mask)
+    tm.assert_extension_array_equal(result, expected)
+    assert result._data is not values
+    assert result._mask is not mask
+
+    # mixed missing from values and mask
+    values = [True, False, None, False]
+    mask = np.array([False, False, False, True], dtype="bool")
+    result = BooleanArray(*coerce_to_array(values, mask=mask))
+    expected = BooleanArray(
+        np.array([True, False, True, True]), np.array([False, False, True, True])
+    )
+    tm.assert_extension_array_equal(result, expected)
+    result = BooleanArray(*coerce_to_array(np.array(values, dtype=object), mask=mask))
+    tm.assert_extension_array_equal(result, expected)
+    result = BooleanArray(*coerce_to_array(values, mask=mask.tolist()))
+    tm.assert_extension_array_equal(result, expected)
+
+    # raise errors for wrong dimension
+    values = np.array([True, False, True, False], dtype="bool")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    # passing 2D values is OK as long as no mask
+    coerce_to_array(values.reshape(1, -1))
+
+    with pytest.raises(ValueError, match="values.shape and mask.shape must match"):
+        coerce_to_array(values.reshape(1, -1), mask=mask)
+
+    with pytest.raises(ValueError, match="values.shape and mask.shape must match"):
+        coerce_to_array(values, mask=mask.reshape(1, -1))
+
+
+def test_coerce_to_array_from_boolean_array():
+    # passing BooleanArray to coerce_to_array
+    values = np.array([True, False, True, False], dtype="bool")
+    mask = np.array([False, False, False, True], dtype="bool")
+    arr = BooleanArray(values, mask)
+    result = BooleanArray(*coerce_to_array(arr))
+    tm.assert_extension_array_equal(result, arr)
+    # no copy
+    assert result._data is arr._data
+    assert result._mask is arr._mask
+
+    result = BooleanArray(*coerce_to_array(arr), copy=True)
+    tm.assert_extension_array_equal(result, arr)
+    assert result._data is not arr._data
+    assert result._mask is not arr._mask
+
+    with pytest.raises(ValueError, match="cannot pass mask for BooleanArray input"):
+        coerce_to_array(arr, mask=mask)
+
+
+def test_coerce_to_numpy_array():
+    # with missing values -> object dtype
+    arr = pd.array([True, False, None], dtype="boolean")
+    result = np.array(arr)
+    expected = np.array([True, False, pd.NA], dtype="object")
+    tm.assert_numpy_array_equal(result, expected)
+
+    # also with no missing values -> object dtype
+    arr = pd.array([True, False, True], dtype="boolean")
+    result = np.array(arr)
+    expected = np.array([True, False, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+    # force bool dtype
+    result = np.array(arr, dtype="bool")
+    expected = np.array([True, False, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+    # with missing values will raise error
+    arr = pd.array([True, False, None], dtype="boolean")
+    msg = (
+        "cannot convert to 'bool'-dtype NumPy array with missing values. "
+        "Specify an appropriate 'na_value' for this dtype."
+    )
+    with pytest.raises(ValueError, match=msg):
+        np.array(arr, dtype="bool")
+
+
+def test_to_boolean_array_from_strings():
+    result = BooleanArray._from_sequence_of_strings(
+        np.array(["True", "False", "1", "1.0", "0", "0.0", np.nan], dtype=object),
+        dtype="boolean",
+    )
+    expected = BooleanArray(
+        np.array([True, False, True, True, False, False, False]),
+        np.array([False, False, False, False, False, False, True]),
+    )
+
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_to_boolean_array_from_strings_invalid_string():
+    with pytest.raises(ValueError, match="cannot be cast"):
+        BooleanArray._from_sequence_of_strings(["donkey"], dtype="boolean")
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy(box):
+    con = pd.Series if box else pd.array
+    # default (with or without missing values) -> object dtype
+    arr = con([True, False, True], dtype="boolean")
+    result = arr.to_numpy()
+    expected = np.array([True, False, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([True, False, None], dtype="boolean")
+    result = arr.to_numpy()
+    expected = np.array([True, False, pd.NA], dtype="object")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([True, False, None], dtype="boolean")
+    result = arr.to_numpy(dtype="str")
+    expected = np.array([True, False, pd.NA], dtype=f"{tm.ENDIAN}U5")
+    tm.assert_numpy_array_equal(result, expected)
+
+    # no missing values -> can convert to bool, otherwise raises
+    arr = con([True, False, True], dtype="boolean")
+    result = arr.to_numpy(dtype="bool")
+    expected = np.array([True, False, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([True, False, None], dtype="boolean")
+    with pytest.raises(ValueError, match="cannot convert to 'bool'-dtype"):
+        result = arr.to_numpy(dtype="bool")
+
+    # specify dtype and na_value
+    arr = con([True, False, None], dtype="boolean")
+    result = arr.to_numpy(dtype=object, na_value=None)
+    expected = np.array([True, False, None], dtype="object")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype=bool, na_value=False)
+    expected = np.array([True, False, False], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype="int64", na_value=-99)
+    expected = np.array([1, 0, -99], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype="float64", na_value=np.nan)
+    expected = np.array([1, 0, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    # converting to int or float without specifying na_value raises
+    with pytest.raises(ValueError, match="cannot convert to 'int64'-dtype"):
+        arr.to_numpy(dtype="int64")
+
+
+def test_to_numpy_copy():
+    # to_numpy can be zero-copy if no missing values
+    arr = pd.array([True, False, True], dtype="boolean")
+    result = arr.to_numpy(dtype=bool)
+    result[0] = False
+    tm.assert_extension_array_equal(
+        arr, pd.array([False, False, True], dtype="boolean")
+    )
+
+    arr = pd.array([True, False, True], dtype="boolean")
+    result = arr.to_numpy(dtype=bool, copy=True)
+    result[0] = False
+    tm.assert_extension_array_equal(arr, pd.array([True, False, True], dtype="boolean"))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_function.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_function.py
new file mode 100644
index 0000000000000000000000000000000000000000..2b3f3d3d16ac6c49d231ac526fa89570975e4bfb
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_function.py
@@ -0,0 +1,126 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "ufunc", [np.add, np.logical_or, np.logical_and, np.logical_xor]
+)
+def test_ufuncs_binary(ufunc):
+    # two BooleanArrays
+    a = pd.array([True, False, None], dtype="boolean")
+    result = ufunc(a, a)
+    expected = pd.array(ufunc(a._data, a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    s = pd.Series(a)
+    result = ufunc(s, a)
+    expected = pd.Series(ufunc(a._data, a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_series_equal(result, expected)
+
+    # Boolean with numpy array
+    arr = np.array([True, True, False])
+    result = ufunc(a, arr)
+    expected = pd.array(ufunc(a._data, arr), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(arr, a)
+    expected = pd.array(ufunc(arr, a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    # BooleanArray with scalar
+    result = ufunc(a, True)
+    expected = pd.array(ufunc(a._data, True), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(True, a)
+    expected = pd.array(ufunc(True, a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    # not handled types
+    msg = r"operand type\(s\) all returned NotImplemented from __array_ufunc__"
+    with pytest.raises(TypeError, match=msg):
+        ufunc(a, "test")
+
+
+@pytest.mark.parametrize("ufunc", [np.logical_not])
+def test_ufuncs_unary(ufunc):
+    a = pd.array([True, False, None], dtype="boolean")
+    result = ufunc(a)
+    expected = pd.array(ufunc(a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_extension_array_equal(result, expected)
+
+    ser = pd.Series(a)
+    result = ufunc(ser)
+    expected = pd.Series(ufunc(a._data), dtype="boolean")
+    expected[a._mask] = np.nan
+    tm.assert_series_equal(result, expected)
+
+
+def test_ufunc_numeric():
+    # np.sqrt on np.bool_ returns float16, which we upcast to Float32
+    #  bc we do not have Float16
+    arr = pd.array([True, False, None], dtype="boolean")
+
+    res = np.sqrt(arr)
+
+    expected = pd.array([1, 0, None], dtype="Float32")
+    tm.assert_extension_array_equal(res, expected)
+
+
+@pytest.mark.parametrize("values", [[True, False], [True, None]])
+def test_ufunc_reduce_raises(values):
+    arr = pd.array(values, dtype="boolean")
+
+    res = np.add.reduce(arr)
+    if arr[-1] is pd.NA:
+        expected = pd.NA
+    else:
+        expected = arr._data.sum()
+    tm.assert_almost_equal(res, expected)
+
+
+def test_value_counts_na():
+    arr = pd.array([True, False, pd.NA], dtype="boolean")
+    result = arr.value_counts(dropna=False)
+    expected = pd.Series([1, 1, 1], index=arr, dtype="Int64", name="count")
+    assert expected.index.dtype == arr.dtype
+    tm.assert_series_equal(result, expected)
+
+    result = arr.value_counts(dropna=True)
+    expected = pd.Series([1, 1], index=arr[:-1], dtype="Int64", name="count")
+    assert expected.index.dtype == arr.dtype
+    tm.assert_series_equal(result, expected)
+
+
+def test_value_counts_with_normalize():
+    ser = pd.Series([True, False, pd.NA], dtype="boolean")
+    result = ser.value_counts(normalize=True)
+    expected = pd.Series([1, 1], index=ser[:-1], dtype="Float64", name="proportion") / 2
+    assert expected.index.dtype == "boolean"
+    tm.assert_series_equal(result, expected)
+
+
+def test_diff():
+    a = pd.array(
+        [True, True, False, False, True, None, True, None, False], dtype="boolean"
+    )
+    result = pd.core.algorithms.diff(a, 1)
+    expected = pd.array(
+        [None, False, True, False, True, None, None, None, None], dtype="boolean"
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    ser = pd.Series(a)
+    result = ser.diff()
+    expected = pd.Series(expected)
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_indexing.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..6a7daea16963c99fb7c4bbcd4b122d6af53d2576
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_indexing.py
@@ -0,0 +1,13 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize("na", [None, np.nan, pd.NA])
+def test_setitem_missing_values(na):
+    arr = pd.array([True, False, None], dtype="boolean")
+    expected = pd.array([True, None, None], dtype="boolean")
+    arr[1] = na
+    tm.assert_extension_array_equal(arr, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_logical.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_logical.py
new file mode 100644
index 0000000000000000000000000000000000000000..66c117ea3fc66cbc5f847cc96c23e80a98329c5d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_logical.py
@@ -0,0 +1,254 @@
+import operator
+
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.arrays import BooleanArray
+from pandas.core.ops.mask_ops import (
+    kleene_and,
+    kleene_or,
+    kleene_xor,
+)
+from pandas.tests.extension.base import BaseOpsUtil
+
+
+class TestLogicalOps(BaseOpsUtil):
+    def test_numpy_scalars_ok(self, all_logical_operators):
+        a = pd.array([True, False, None], dtype="boolean")
+        op = getattr(a, all_logical_operators)
+
+        tm.assert_extension_array_equal(op(True), op(np.bool_(True)))
+        tm.assert_extension_array_equal(op(False), op(np.bool_(False)))
+
+    def get_op_from_name(self, op_name):
+        short_opname = op_name.strip("_")
+        short_opname = short_opname if "xor" in short_opname else short_opname + "_"
+        try:
+            op = getattr(operator, short_opname)
+        except AttributeError:
+            # Assume it is the reverse operator
+            rop = getattr(operator, short_opname[1:])
+            op = lambda x, y: rop(y, x)
+
+        return op
+
+    def test_empty_ok(self, all_logical_operators):
+        a = pd.array([], dtype="boolean")
+        op_name = all_logical_operators
+        result = getattr(a, op_name)(True)
+        tm.assert_extension_array_equal(a, result)
+
+        result = getattr(a, op_name)(False)
+        tm.assert_extension_array_equal(a, result)
+
+        result = getattr(a, op_name)(pd.NA)
+        tm.assert_extension_array_equal(a, result)
+
+    @pytest.mark.parametrize(
+        "other", ["a", pd.Timestamp(2017, 1, 1, 12), np.timedelta64(4)]
+    )
+    def test_eq_mismatched_type(self, other):
+        # GH-44499
+        arr = pd.array([True, False])
+        result = arr == other
+        expected = pd.array([False, False])
+        tm.assert_extension_array_equal(result, expected)
+
+        result = arr != other
+        expected = pd.array([True, True])
+        tm.assert_extension_array_equal(result, expected)
+
+    def test_logical_length_mismatch_raises(self, all_logical_operators):
+        op_name = all_logical_operators
+        a = pd.array([True, False, None], dtype="boolean")
+        msg = "Lengths must match"
+
+        with pytest.raises(ValueError, match=msg):
+            getattr(a, op_name)([True, False])
+
+        with pytest.raises(ValueError, match=msg):
+            getattr(a, op_name)(np.array([True, False]))
+
+        with pytest.raises(ValueError, match=msg):
+            getattr(a, op_name)(pd.array([True, False], dtype="boolean"))
+
+    def test_logical_nan_raises(self, all_logical_operators):
+        op_name = all_logical_operators
+        a = pd.array([True, False, None], dtype="boolean")
+        msg = "Got float instead"
+
+        with pytest.raises(TypeError, match=msg):
+            getattr(a, op_name)(np.nan)
+
+    @pytest.mark.parametrize("other", ["a", 1])
+    def test_non_bool_or_na_other_raises(self, other, all_logical_operators):
+        a = pd.array([True, False], dtype="boolean")
+        with pytest.raises(TypeError, match=str(type(other).__name__)):
+            getattr(a, all_logical_operators)(other)
+
+    def test_kleene_or(self):
+        # A clear test of behavior.
+        a = pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        b = pd.array([True, False, None] * 3, dtype="boolean")
+        result = a | b
+        expected = pd.array(
+            [True, True, True, True, False, None, True, None, None], dtype="boolean"
+        )
+        tm.assert_extension_array_equal(result, expected)
+
+        result = b | a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        )
+        tm.assert_extension_array_equal(
+            b, pd.array([True, False, None] * 3, dtype="boolean")
+        )
+
+    @pytest.mark.parametrize(
+        "other, expected",
+        [
+            (pd.NA, [True, None, None]),
+            (True, [True, True, True]),
+            (np.bool_(True), [True, True, True]),
+            (False, [True, False, None]),
+            (np.bool_(False), [True, False, None]),
+        ],
+    )
+    def test_kleene_or_scalar(self, other, expected):
+        # TODO: test True & False
+        a = pd.array([True, False, None], dtype="boolean")
+        result = a | other
+        expected = pd.array(expected, dtype="boolean")
+        tm.assert_extension_array_equal(result, expected)
+
+        result = other | a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True, False, None], dtype="boolean")
+        )
+
+    def test_kleene_and(self):
+        # A clear test of behavior.
+        a = pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        b = pd.array([True, False, None] * 3, dtype="boolean")
+        result = a & b
+        expected = pd.array(
+            [True, False, None, False, False, False, None, False, None], dtype="boolean"
+        )
+        tm.assert_extension_array_equal(result, expected)
+
+        result = b & a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        )
+        tm.assert_extension_array_equal(
+            b, pd.array([True, False, None] * 3, dtype="boolean")
+        )
+
+    @pytest.mark.parametrize(
+        "other, expected",
+        [
+            (pd.NA, [None, False, None]),
+            (True, [True, False, None]),
+            (False, [False, False, False]),
+            (np.bool_(True), [True, False, None]),
+            (np.bool_(False), [False, False, False]),
+        ],
+    )
+    def test_kleene_and_scalar(self, other, expected):
+        a = pd.array([True, False, None], dtype="boolean")
+        result = a & other
+        expected = pd.array(expected, dtype="boolean")
+        tm.assert_extension_array_equal(result, expected)
+
+        result = other & a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True, False, None], dtype="boolean")
+        )
+
+    def test_kleene_xor(self):
+        a = pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        b = pd.array([True, False, None] * 3, dtype="boolean")
+        result = a ^ b
+        expected = pd.array(
+            [False, True, None, True, False, None, None, None, None], dtype="boolean"
+        )
+        tm.assert_extension_array_equal(result, expected)
+
+        result = b ^ a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        )
+        tm.assert_extension_array_equal(
+            b, pd.array([True, False, None] * 3, dtype="boolean")
+        )
+
+    @pytest.mark.parametrize(
+        "other, expected",
+        [
+            (pd.NA, [None, None, None]),
+            (True, [False, True, None]),
+            (np.bool_(True), [False, True, None]),
+            (np.bool_(False), [True, False, None]),
+        ],
+    )
+    def test_kleene_xor_scalar(self, other, expected):
+        a = pd.array([True, False, None], dtype="boolean")
+        result = a ^ other
+        expected = pd.array(expected, dtype="boolean")
+        tm.assert_extension_array_equal(result, expected)
+
+        result = other ^ a
+        tm.assert_extension_array_equal(result, expected)
+
+        # ensure we haven't mutated anything inplace
+        tm.assert_extension_array_equal(
+            a, pd.array([True, False, None], dtype="boolean")
+        )
+
+    @pytest.mark.parametrize("other", [True, False, pd.NA, [True, False, None] * 3])
+    def test_no_masked_assumptions(self, other, all_logical_operators):
+        # The logical operations should not assume that masked values are False!
+        a = pd.arrays.BooleanArray(
+            np.array([True, True, True, False, False, False, True, False, True]),
+            np.array([False] * 6 + [True, True, True]),
+        )
+        b = pd.array([True] * 3 + [False] * 3 + [None] * 3, dtype="boolean")
+        if isinstance(other, list):
+            other = pd.array(other, dtype="boolean")
+
+        result = getattr(a, all_logical_operators)(other)
+        expected = getattr(b, all_logical_operators)(other)
+        tm.assert_extension_array_equal(result, expected)
+
+        if isinstance(other, BooleanArray):
+            other._data[other._mask] = True
+            a._data[a._mask] = False
+
+            result = getattr(a, all_logical_operators)(other)
+            expected = getattr(b, all_logical_operators)(other)
+            tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("operation", [kleene_or, kleene_xor, kleene_and])
+def test_error_both_scalar(operation):
+    msg = r"Either `left` or `right` need to be a np\.ndarray."
+    with pytest.raises(TypeError, match=msg):
+        # masks need to be non-None, otherwise it ends up in an infinite recursion
+        operation(True, True, np.zeros(1), np.zeros(1))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_ops.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_ops.py
new file mode 100644
index 0000000000000000000000000000000000000000..95ebe8528c2e5fec1a580b00bd79e0617fe7609f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_ops.py
@@ -0,0 +1,27 @@
+import pandas as pd
+import pandas._testing as tm
+
+
+class TestUnaryOps:
+    def test_invert(self):
+        a = pd.array([True, False, None], dtype="boolean")
+        expected = pd.array([False, True, None], dtype="boolean")
+        tm.assert_extension_array_equal(~a, expected)
+
+        expected = pd.Series(expected, index=["a", "b", "c"], name="name")
+        result = ~pd.Series(a, index=["a", "b", "c"], name="name")
+        tm.assert_series_equal(result, expected)
+
+        df = pd.DataFrame({"A": a, "B": [True, False, False]}, index=["a", "b", "c"])
+        result = ~df
+        expected = pd.DataFrame(
+            {"A": expected, "B": [False, True, True]}, index=["a", "b", "c"]
+        )
+        tm.assert_frame_equal(result, expected)
+
+    def test_abs(self):
+        # matching numpy behavior, abs is the identity function
+        arr = pd.array([True, False, None], dtype="boolean")
+        result = abs(arr)
+
+        tm.assert_extension_array_equal(result, arr)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_reduction.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_reduction.py
new file mode 100644
index 0000000000000000000000000000000000000000..dd8c3eda9ed05b6844c90024631a1e90f755069e
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_reduction.py
@@ -0,0 +1,62 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+
+
+@pytest.fixture
+def data():
+    """Fixture returning boolean array, with valid and missing values."""
+    return pd.array(
+        [True, False] * 4 + [np.nan] + [True, False] * 44 + [np.nan] + [True, False],
+        dtype="boolean",
+    )
+
+
+@pytest.mark.parametrize(
+    "values, exp_any, exp_all, exp_any_noskip, exp_all_noskip",
+    [
+        ([True, pd.NA], True, True, True, pd.NA),
+        ([False, pd.NA], False, False, pd.NA, False),
+        ([pd.NA], False, True, pd.NA, pd.NA),
+        ([], False, True, False, True),
+        # GH-33253: all True / all False values buggy with skipna=False
+        ([True, True], True, True, True, True),
+        ([False, False], False, False, False, False),
+    ],
+)
+def test_any_all(values, exp_any, exp_all, exp_any_noskip, exp_all_noskip):
+    # the methods return numpy scalars
+    exp_any = pd.NA if exp_any is pd.NA else np.bool_(exp_any)
+    exp_all = pd.NA if exp_all is pd.NA else np.bool_(exp_all)
+    exp_any_noskip = pd.NA if exp_any_noskip is pd.NA else np.bool_(exp_any_noskip)
+    exp_all_noskip = pd.NA if exp_all_noskip is pd.NA else np.bool_(exp_all_noskip)
+
+    for con in [pd.array, pd.Series]:
+        a = con(values, dtype="boolean")
+        assert a.any() is exp_any
+        assert a.all() is exp_all
+        assert a.any(skipna=False) is exp_any_noskip
+        assert a.all(skipna=False) is exp_all_noskip
+
+        assert np.any(a.any()) is exp_any
+        assert np.all(a.all()) is exp_all
+
+
+@pytest.mark.parametrize("dropna", [True, False])
+def test_reductions_return_types(dropna, data, all_numeric_reductions):
+    op = all_numeric_reductions
+    s = pd.Series(data)
+    if dropna:
+        s = s.dropna()
+
+    if op in ("sum", "prod"):
+        assert isinstance(getattr(s, op)(), np.int_)
+    elif op == "count":
+        # Oddly on the 32 bit build (but not Windows), this is intc (!= intp)
+        assert isinstance(getattr(s, op)(), np.integer)
+    elif op in ("min", "max"):
+        assert isinstance(getattr(s, op)(), np.bool_)
+    else:
+        # "mean", "std", "var", "median", "kurt", "skew"
+        assert isinstance(getattr(s, op)(), np.float64)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_repr.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_repr.py
new file mode 100644
index 0000000000000000000000000000000000000000..0ee904b18cc9ec6197ed3ad009fae1da593c5219
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/boolean/test_repr.py
@@ -0,0 +1,13 @@
+import pandas as pd
+
+
+def test_repr():
+    df = pd.DataFrame({"A": pd.array([True, False, None], dtype="boolean")})
+    expected = "       A\n0   True\n1  False\n2   "
+    assert repr(df) == expected
+
+    expected = "0     True\n1    False\n2     \nName: A, dtype: boolean"
+    assert repr(df.A) == expected
+
+    expected = "\n[True, False, ]\nLength: 3, dtype: boolean"
+    assert repr(df.A.array) == expected
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_algos.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_algos.py
new file mode 100644
index 0000000000000000000000000000000000000000..d4c19a4970135cfb1865eaa0fae0845dc7d17971
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_algos.py
@@ -0,0 +1,89 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize("ordered", [True, False])
+@pytest.mark.parametrize("categories", [["b", "a", "c"], ["a", "b", "c", "d"]])
+def test_factorize(categories, ordered):
+    cat = pd.Categorical(
+        ["b", "b", "a", "c", None], categories=categories, ordered=ordered
+    )
+    codes, uniques = pd.factorize(cat)
+    expected_codes = np.array([0, 0, 1, 2, -1], dtype=np.intp)
+    expected_uniques = pd.Categorical(
+        ["b", "a", "c"], categories=categories, ordered=ordered
+    )
+
+    tm.assert_numpy_array_equal(codes, expected_codes)
+    tm.assert_categorical_equal(uniques, expected_uniques)
+
+
+def test_factorized_sort():
+    cat = pd.Categorical(["b", "b", None, "a"])
+    codes, uniques = pd.factorize(cat, sort=True)
+    expected_codes = np.array([1, 1, -1, 0], dtype=np.intp)
+    expected_uniques = pd.Categorical(["a", "b"])
+
+    tm.assert_numpy_array_equal(codes, expected_codes)
+    tm.assert_categorical_equal(uniques, expected_uniques)
+
+
+def test_factorized_sort_ordered():
+    cat = pd.Categorical(
+        ["b", "b", None, "a"], categories=["c", "b", "a"], ordered=True
+    )
+
+    codes, uniques = pd.factorize(cat, sort=True)
+    expected_codes = np.array([0, 0, -1, 1], dtype=np.intp)
+    expected_uniques = pd.Categorical(
+        ["b", "a"], categories=["c", "b", "a"], ordered=True
+    )
+
+    tm.assert_numpy_array_equal(codes, expected_codes)
+    tm.assert_categorical_equal(uniques, expected_uniques)
+
+
+def test_isin_cats():
+    # GH2003
+    cat = pd.Categorical(["a", "b", np.nan])
+
+    result = cat.isin(["a", np.nan])
+    expected = np.array([True, False, True], dtype=bool)
+    tm.assert_numpy_array_equal(expected, result)
+
+    result = cat.isin(["a", "c"])
+    expected = np.array([True, False, False], dtype=bool)
+    tm.assert_numpy_array_equal(expected, result)
+
+
+@pytest.mark.parametrize("value", [[""], [None, ""], [pd.NaT, ""]])
+def test_isin_cats_corner_cases(value):
+    # GH36550
+    cat = pd.Categorical([""])
+    result = cat.isin(value)
+    expected = np.array([True], dtype=bool)
+    tm.assert_numpy_array_equal(expected, result)
+
+
+@pytest.mark.parametrize("empty", [[], pd.Series(dtype=object), np.array([])])
+def test_isin_empty(empty):
+    s = pd.Categorical(["a", "b"])
+    expected = np.array([False, False], dtype=bool)
+
+    result = s.isin(empty)
+    tm.assert_numpy_array_equal(expected, result)
+
+
+def test_diff():
+    ser = pd.Series([1, 2, 3], dtype="category")
+
+    msg = "Convert to a suitable dtype"
+    with pytest.raises(TypeError, match=msg):
+        ser.diff()
+
+    df = ser.to_frame(name="A")
+    with pytest.raises(TypeError, match=msg):
+        df.diff()
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_analytics.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_analytics.py
new file mode 100644
index 0000000000000000000000000000000000000000..9a0356cbc422bc534b0cef5aad79ba304e7a77b2
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_analytics.py
@@ -0,0 +1,355 @@
+import re
+import sys
+
+import numpy as np
+import pytest
+
+from pandas.compat import PYPY
+
+from pandas import (
+    Categorical,
+    CategoricalDtype,
+    DataFrame,
+    Index,
+    NaT,
+    Series,
+    date_range,
+)
+import pandas._testing as tm
+from pandas.api.types import is_scalar
+
+
+class TestCategoricalAnalytics:
+    @pytest.mark.parametrize("aggregation", ["min", "max"])
+    def test_min_max_not_ordered_raises(self, aggregation):
+        # unordered cats have no min/max
+        cat = Categorical(["a", "b", "c", "d"], ordered=False)
+        msg = f"Categorical is not ordered for operation {aggregation}"
+        agg_func = getattr(cat, aggregation)
+
+        with pytest.raises(TypeError, match=msg):
+            agg_func()
+
+        ufunc = np.minimum if aggregation == "min" else np.maximum
+        with pytest.raises(TypeError, match=msg):
+            ufunc.reduce(cat)
+
+    def test_min_max_ordered(self, index_or_series_or_array):
+        cat = Categorical(["a", "b", "c", "d"], ordered=True)
+        obj = index_or_series_or_array(cat)
+        _min = obj.min()
+        _max = obj.max()
+        assert _min == "a"
+        assert _max == "d"
+
+        assert np.minimum.reduce(obj) == "a"
+        assert np.maximum.reduce(obj) == "d"
+        # TODO: raises if we pass axis=0  (on Index and Categorical, not Series)
+
+        cat = Categorical(
+            ["a", "b", "c", "d"], categories=["d", "c", "b", "a"], ordered=True
+        )
+        obj = index_or_series_or_array(cat)
+        _min = obj.min()
+        _max = obj.max()
+        assert _min == "d"
+        assert _max == "a"
+        assert np.minimum.reduce(obj) == "d"
+        assert np.maximum.reduce(obj) == "a"
+
+    def test_min_max_reduce(self):
+        # GH52788
+        cat = Categorical(["a", "b", "c", "d"], ordered=True)
+        df = DataFrame(cat)
+
+        result_max = df.agg("max")
+        expected_max = Series(Categorical(["d"], dtype=cat.dtype))
+        tm.assert_series_equal(result_max, expected_max)
+
+        result_min = df.agg("min")
+        expected_min = Series(Categorical(["a"], dtype=cat.dtype))
+        tm.assert_series_equal(result_min, expected_min)
+
+    @pytest.mark.parametrize(
+        "categories,expected",
+        [
+            (list("ABC"), np.nan),
+            ([1, 2, 3], np.nan),
+            pytest.param(
+                Series(date_range("2020-01-01", periods=3), dtype="category"),
+                NaT,
+                marks=pytest.mark.xfail(
+                    reason="https://github.com/pandas-dev/pandas/issues/29962"
+                ),
+            ),
+        ],
+    )
+    @pytest.mark.parametrize("aggregation", ["min", "max"])
+    def test_min_max_ordered_empty(self, categories, expected, aggregation):
+        # GH 30227
+        cat = Categorical([], categories=categories, ordered=True)
+
+        agg_func = getattr(cat, aggregation)
+        result = agg_func()
+        assert result is expected
+
+    @pytest.mark.parametrize(
+        "values, categories",
+        [(["a", "b", "c", np.nan], list("cba")), ([1, 2, 3, np.nan], [3, 2, 1])],
+    )
+    @pytest.mark.parametrize("skipna", [True, False])
+    @pytest.mark.parametrize("function", ["min", "max"])
+    def test_min_max_with_nan(self, values, categories, function, skipna):
+        # GH 25303
+        cat = Categorical(values, categories=categories, ordered=True)
+        result = getattr(cat, function)(skipna=skipna)
+
+        if skipna is False:
+            assert result is np.nan
+        else:
+            expected = categories[0] if function == "min" else categories[2]
+            assert result == expected
+
+    @pytest.mark.parametrize("function", ["min", "max"])
+    @pytest.mark.parametrize("skipna", [True, False])
+    def test_min_max_only_nan(self, function, skipna):
+        # https://github.com/pandas-dev/pandas/issues/33450
+        cat = Categorical([np.nan], categories=[1, 2], ordered=True)
+        result = getattr(cat, function)(skipna=skipna)
+        assert result is np.nan
+
+    @pytest.mark.parametrize("method", ["min", "max"])
+    def test_numeric_only_min_max_raises(self, method):
+        # GH 25303
+        cat = Categorical(
+            [np.nan, 1, 2, np.nan], categories=[5, 4, 3, 2, 1], ordered=True
+        )
+        with pytest.raises(TypeError, match=".* got an unexpected keyword"):
+            getattr(cat, method)(numeric_only=True)
+
+    @pytest.mark.parametrize("method", ["min", "max"])
+    def test_numpy_min_max_raises(self, method):
+        cat = Categorical(["a", "b", "c", "b"], ordered=False)
+        msg = (
+            f"Categorical is not ordered for operation {method}\n"
+            "you can use .as_ordered() to change the Categorical to an ordered one"
+        )
+        method = getattr(np, method)
+        with pytest.raises(TypeError, match=re.escape(msg)):
+            method(cat)
+
+    @pytest.mark.parametrize("kwarg", ["axis", "out", "keepdims"])
+    @pytest.mark.parametrize("method", ["min", "max"])
+    def test_numpy_min_max_unsupported_kwargs_raises(self, method, kwarg):
+        cat = Categorical(["a", "b", "c", "b"], ordered=True)
+        msg = (
+            f"the '{kwarg}' parameter is not supported in the pandas implementation "
+            f"of {method}"
+        )
+        if kwarg == "axis":
+            msg = r"`axis` must be fewer than the number of dimensions \(1\)"
+        kwargs = {kwarg: 42}
+        method = getattr(np, method)
+        with pytest.raises(ValueError, match=msg):
+            method(cat, **kwargs)
+
+    @pytest.mark.parametrize("method, expected", [("min", "a"), ("max", "c")])
+    def test_numpy_min_max_axis_equals_none(self, method, expected):
+        cat = Categorical(["a", "b", "c", "b"], ordered=True)
+        method = getattr(np, method)
+        result = method(cat, axis=None)
+        assert result == expected
+
+    @pytest.mark.parametrize(
+        "values,categories,exp_mode",
+        [
+            ([1, 1, 2, 4, 5, 5, 5], [5, 4, 3, 2, 1], [5]),
+            ([1, 1, 1, 4, 5, 5, 5], [5, 4, 3, 2, 1], [5, 1]),
+            ([1, 2, 3, 4, 5], [5, 4, 3, 2, 1], [5, 4, 3, 2, 1]),
+            ([np.nan, np.nan, np.nan, 4, 5], [5, 4, 3, 2, 1], [5, 4]),
+            ([np.nan, np.nan, np.nan, 4, 5, 4], [5, 4, 3, 2, 1], [4]),
+            ([np.nan, np.nan, 4, 5, 4], [5, 4, 3, 2, 1], [4]),
+        ],
+    )
+    def test_mode(self, values, categories, exp_mode):
+        cat = Categorical(values, categories=categories, ordered=True)
+        res = Series(cat).mode()._values
+        exp = Categorical(exp_mode, categories=categories, ordered=True)
+        tm.assert_categorical_equal(res, exp)
+
+    def test_searchsorted(self, ordered):
+        # https://github.com/pandas-dev/pandas/issues/8420
+        # https://github.com/pandas-dev/pandas/issues/14522
+
+        cat = Categorical(
+            ["cheese", "milk", "apple", "bread", "bread"],
+            categories=["cheese", "milk", "apple", "bread"],
+            ordered=ordered,
+        )
+        ser = Series(cat)
+
+        # Searching for single item argument, side='left' (default)
+        res_cat = cat.searchsorted("apple")
+        assert res_cat == 2
+        assert is_scalar(res_cat)
+
+        res_ser = ser.searchsorted("apple")
+        assert res_ser == 2
+        assert is_scalar(res_ser)
+
+        # Searching for single item array, side='left' (default)
+        res_cat = cat.searchsorted(["bread"])
+        res_ser = ser.searchsorted(["bread"])
+        exp = np.array([3], dtype=np.intp)
+        tm.assert_numpy_array_equal(res_cat, exp)
+        tm.assert_numpy_array_equal(res_ser, exp)
+
+        # Searching for several items array, side='right'
+        res_cat = cat.searchsorted(["apple", "bread"], side="right")
+        res_ser = ser.searchsorted(["apple", "bread"], side="right")
+        exp = np.array([3, 5], dtype=np.intp)
+        tm.assert_numpy_array_equal(res_cat, exp)
+        tm.assert_numpy_array_equal(res_ser, exp)
+
+        # Searching for a single value that is not from the Categorical
+        with pytest.raises(TypeError, match="cucumber"):
+            cat.searchsorted("cucumber")
+        with pytest.raises(TypeError, match="cucumber"):
+            ser.searchsorted("cucumber")
+
+        # Searching for multiple values one of each is not from the Categorical
+        msg = (
+            "Cannot setitem on a Categorical with a new category, "
+            "set the categories first"
+        )
+        with pytest.raises(TypeError, match=msg):
+            cat.searchsorted(["bread", "cucumber"])
+        with pytest.raises(TypeError, match=msg):
+            ser.searchsorted(["bread", "cucumber"])
+
+    def test_unique(self, ordered):
+        # GH38140
+        dtype = CategoricalDtype(["a", "b", "c"], ordered=ordered)
+
+        # categories are reordered based on value when ordered=False
+        cat = Categorical(["a", "b", "c"], dtype=dtype)
+        res = cat.unique()
+        tm.assert_categorical_equal(res, cat)
+
+        cat = Categorical(["a", "b", "a", "a"], dtype=dtype)
+        res = cat.unique()
+        tm.assert_categorical_equal(res, Categorical(["a", "b"], dtype=dtype))
+
+        cat = Categorical(["c", "a", "b", "a", "a"], dtype=dtype)
+        res = cat.unique()
+        exp_cat = Categorical(["c", "a", "b"], dtype=dtype)
+        tm.assert_categorical_equal(res, exp_cat)
+
+        # nan must be removed
+        cat = Categorical(["b", np.nan, "b", np.nan, "a"], dtype=dtype)
+        res = cat.unique()
+        exp_cat = Categorical(["b", np.nan, "a"], dtype=dtype)
+        tm.assert_categorical_equal(res, exp_cat)
+
+    def test_unique_index_series(self, ordered):
+        # GH38140
+        dtype = CategoricalDtype([3, 2, 1], ordered=ordered)
+
+        c = Categorical([3, 1, 2, 2, 1], dtype=dtype)
+        # Categorical.unique sorts categories by appearance order
+        # if ordered=False
+        exp = Categorical([3, 1, 2], dtype=dtype)
+        tm.assert_categorical_equal(c.unique(), exp)
+
+        tm.assert_index_equal(Index(c).unique(), Index(exp))
+        tm.assert_categorical_equal(Series(c).unique(), exp)
+
+        c = Categorical([1, 1, 2, 2], dtype=dtype)
+        exp = Categorical([1, 2], dtype=dtype)
+        tm.assert_categorical_equal(c.unique(), exp)
+        tm.assert_index_equal(Index(c).unique(), Index(exp))
+        tm.assert_categorical_equal(Series(c).unique(), exp)
+
+    def test_shift(self):
+        # GH 9416
+        cat = Categorical(["a", "b", "c", "d", "a"])
+
+        # shift forward
+        sp1 = cat.shift(1)
+        xp1 = Categorical([np.nan, "a", "b", "c", "d"])
+        tm.assert_categorical_equal(sp1, xp1)
+        tm.assert_categorical_equal(cat[:-1], sp1[1:])
+
+        # shift back
+        sn2 = cat.shift(-2)
+        xp2 = Categorical(
+            ["c", "d", "a", np.nan, np.nan], categories=["a", "b", "c", "d"]
+        )
+        tm.assert_categorical_equal(sn2, xp2)
+        tm.assert_categorical_equal(cat[2:], sn2[:-2])
+
+        # shift by zero
+        tm.assert_categorical_equal(cat, cat.shift(0))
+
+    def test_nbytes(self):
+        cat = Categorical([1, 2, 3])
+        exp = 3 + 3 * 8  # 3 int8s for values + 3 int64s for categories
+        assert cat.nbytes == exp
+
+    def test_memory_usage(self, using_infer_string):
+        cat = Categorical([1, 2, 3])
+
+        # .categories is an index, so we include the hashtable
+        assert 0 < cat.nbytes <= cat.memory_usage()
+        assert 0 < cat.nbytes <= cat.memory_usage(deep=True)
+
+        cat = Categorical(["foo", "foo", "bar"])
+        if using_infer_string:
+            if cat.categories.dtype.storage == "python":
+                assert cat.memory_usage(deep=True) > cat.nbytes
+            else:
+                assert cat.memory_usage(deep=True) >= cat.nbytes
+        else:
+            assert cat.memory_usage(deep=True) > cat.nbytes
+
+        if not PYPY:
+            # sys.getsizeof will call the .memory_usage with
+            # deep=True, and add on some GC overhead
+            diff = cat.memory_usage(deep=True) - sys.getsizeof(cat)
+            assert abs(diff) < 100
+
+    def test_map(self):
+        c = Categorical(list("ABABC"), categories=list("CBA"), ordered=True)
+        result = c.map(lambda x: x.lower(), na_action=None)
+        exp = Categorical(list("ababc"), categories=list("cba"), ordered=True)
+        tm.assert_categorical_equal(result, exp)
+
+        c = Categorical(list("ABABC"), categories=list("ABC"), ordered=False)
+        result = c.map(lambda x: x.lower(), na_action=None)
+        exp = Categorical(list("ababc"), categories=list("abc"), ordered=False)
+        tm.assert_categorical_equal(result, exp)
+
+        result = c.map(lambda x: 1, na_action=None)
+        # GH 12766: Return an index not an array
+        tm.assert_index_equal(result, Index(np.array([1] * 5, dtype=np.int64)))
+
+    @pytest.mark.parametrize("value", [1, "True", [1, 2, 3], 5.0])
+    def test_validate_inplace_raises(self, value):
+        cat = Categorical(["A", "B", "B", "C", "A"])
+        msg = (
+            'For argument "inplace" expected type bool, '
+            f"received type {type(value).__name__}"
+        )
+
+        with pytest.raises(ValueError, match=msg):
+            cat.sort_values(inplace=value)
+
+    def test_quantile_empty(self):
+        # make sure we have correct itemsize on resulting codes
+        cat = Categorical(["A", "B"])
+        idx = Index([0.0, 0.5])
+        result = cat[:0]._quantile(idx, interpolation="linear")
+        assert result._codes.dtype == np.int8
+
+        expected = cat.take([-1, -1], allow_fill=True)
+        tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_api.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_api.py
new file mode 100644
index 0000000000000000000000000000000000000000..a939ee5f6f53f805211d46773c625c8361203991
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_api.py
@@ -0,0 +1,501 @@
+import re
+
+import numpy as np
+import pytest
+
+from pandas.compat import PY311
+
+from pandas import (
+    Categorical,
+    CategoricalIndex,
+    DataFrame,
+    Index,
+    Series,
+    StringDtype,
+)
+import pandas._testing as tm
+from pandas.core.arrays.categorical import recode_for_categories
+
+
+class TestCategoricalAPI:
+    def test_to_list_deprecated(self):
+        # GH#51254
+        cat1 = Categorical(list("acb"), ordered=False)
+        msg = "Categorical.to_list is deprecated and will be removed"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            cat1.to_list()
+
+    def test_ordered_api(self):
+        # GH 9347
+        cat1 = Categorical(list("acb"), ordered=False)
+        tm.assert_index_equal(cat1.categories, Index(["a", "b", "c"]))
+        assert not cat1.ordered
+
+        cat2 = Categorical(list("acb"), categories=list("bca"), ordered=False)
+        tm.assert_index_equal(cat2.categories, Index(["b", "c", "a"]))
+        assert not cat2.ordered
+
+        cat3 = Categorical(list("acb"), ordered=True)
+        tm.assert_index_equal(cat3.categories, Index(["a", "b", "c"]))
+        assert cat3.ordered
+
+        cat4 = Categorical(list("acb"), categories=list("bca"), ordered=True)
+        tm.assert_index_equal(cat4.categories, Index(["b", "c", "a"]))
+        assert cat4.ordered
+
+    def test_set_ordered(self):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        cat2 = cat.as_unordered()
+        assert not cat2.ordered
+        cat2 = cat.as_ordered()
+        assert cat2.ordered
+
+        assert cat2.set_ordered(True).ordered
+        assert not cat2.set_ordered(False).ordered
+
+        # removed in 0.19.0
+        msg = (
+            "property 'ordered' of 'Categorical' object has no setter"
+            if PY311
+            else "can't set attribute"
+        )
+        with pytest.raises(AttributeError, match=msg):
+            cat.ordered = True
+        with pytest.raises(AttributeError, match=msg):
+            cat.ordered = False
+
+    def test_rename_categories(self):
+        cat = Categorical(["a", "b", "c", "a"])
+
+        # inplace=False: the old one must not be changed
+        res = cat.rename_categories([1, 2, 3])
+        tm.assert_numpy_array_equal(
+            res.__array__(), np.array([1, 2, 3, 1], dtype=np.int64)
+        )
+        tm.assert_index_equal(res.categories, Index([1, 2, 3]))
+
+        exp_cat = np.array(["a", "b", "c", "a"], dtype=np.object_)
+        tm.assert_numpy_array_equal(cat.__array__(), exp_cat)
+
+        exp_cat = Index(["a", "b", "c"])
+        tm.assert_index_equal(cat.categories, exp_cat)
+
+        # GH18862 (let rename_categories take callables)
+        result = cat.rename_categories(lambda x: x.upper())
+        expected = Categorical(["A", "B", "C", "A"])
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("new_categories", [[1, 2, 3, 4], [1, 2]])
+    def test_rename_categories_wrong_length_raises(self, new_categories):
+        cat = Categorical(["a", "b", "c", "a"])
+        msg = (
+            "new categories need to have the same number of items as the "
+            "old categories!"
+        )
+        with pytest.raises(ValueError, match=msg):
+            cat.rename_categories(new_categories)
+
+    def test_rename_categories_series(self):
+        # https://github.com/pandas-dev/pandas/issues/17981
+        c = Categorical(["a", "b"])
+        result = c.rename_categories(Series([0, 1], index=["a", "b"]))
+        expected = Categorical([0, 1])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_rename_categories_dict(self):
+        # GH 17336
+        cat = Categorical(["a", "b", "c", "d"])
+        res = cat.rename_categories({"a": 4, "b": 3, "c": 2, "d": 1})
+        expected = Index([4, 3, 2, 1])
+        tm.assert_index_equal(res.categories, expected)
+
+        # Test for dicts of smaller length
+        cat = Categorical(["a", "b", "c", "d"])
+        res = cat.rename_categories({"a": 1, "c": 3})
+
+        expected = Index([1, "b", 3, "d"])
+        tm.assert_index_equal(res.categories, expected)
+
+        # Test for dicts with bigger length
+        cat = Categorical(["a", "b", "c", "d"])
+        res = cat.rename_categories({"a": 1, "b": 2, "c": 3, "d": 4, "e": 5, "f": 6})
+        expected = Index([1, 2, 3, 4])
+        tm.assert_index_equal(res.categories, expected)
+
+        # Test for dicts with no items from old categories
+        cat = Categorical(["a", "b", "c", "d"])
+        res = cat.rename_categories({"f": 1, "g": 3})
+
+        expected = Index(["a", "b", "c", "d"])
+        tm.assert_index_equal(res.categories, expected)
+
+    def test_reorder_categories(self):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        old = cat.copy()
+        new = Categorical(
+            ["a", "b", "c", "a"], categories=["c", "b", "a"], ordered=True
+        )
+
+        res = cat.reorder_categories(["c", "b", "a"])
+        # cat must be the same as before
+        tm.assert_categorical_equal(cat, old)
+        # only res is changed
+        tm.assert_categorical_equal(res, new)
+
+    @pytest.mark.parametrize(
+        "new_categories",
+        [
+            ["a"],  # not all "old" included in "new"
+            ["a", "b", "d"],  # still not all "old" in "new"
+            ["a", "b", "c", "d"],  # all "old" included in "new", but too long
+        ],
+    )
+    def test_reorder_categories_raises(self, new_categories):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        msg = "items in new_categories are not the same as in old categories"
+        with pytest.raises(ValueError, match=msg):
+            cat.reorder_categories(new_categories)
+
+    def test_add_categories(self):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        old = cat.copy()
+        new = Categorical(
+            ["a", "b", "c", "a"], categories=["a", "b", "c", "d"], ordered=True
+        )
+
+        res = cat.add_categories("d")
+        tm.assert_categorical_equal(cat, old)
+        tm.assert_categorical_equal(res, new)
+
+        res = cat.add_categories(["d"])
+        tm.assert_categorical_equal(cat, old)
+        tm.assert_categorical_equal(res, new)
+
+        # GH 9927
+        cat = Categorical(list("abc"), ordered=True)
+        expected = Categorical(list("abc"), categories=list("abcde"), ordered=True)
+        # test with Series, np.array, index, list
+        res = cat.add_categories(Series(["d", "e"]))
+        tm.assert_categorical_equal(res, expected)
+        res = cat.add_categories(np.array(["d", "e"]))
+        tm.assert_categorical_equal(res, expected)
+        res = cat.add_categories(Index(["d", "e"]))
+        tm.assert_categorical_equal(res, expected)
+        res = cat.add_categories(["d", "e"])
+        tm.assert_categorical_equal(res, expected)
+
+    def test_add_categories_existing_raises(self):
+        # new is in old categories
+        cat = Categorical(["a", "b", "c", "d"], ordered=True)
+        msg = re.escape("new categories must not include old categories: {'d'}")
+        with pytest.raises(ValueError, match=msg):
+            cat.add_categories(["d"])
+
+    def test_add_categories_losing_dtype_information(self):
+        # GH#48812
+        cat = Categorical(Series([1, 2], dtype="Int64"))
+        ser = Series([4], dtype="Int64")
+        result = cat.add_categories(ser)
+        expected = Categorical(
+            Series([1, 2], dtype="Int64"), categories=Series([1, 2, 4], dtype="Int64")
+        )
+        tm.assert_categorical_equal(result, expected)
+
+        cat = Categorical(Series(["a", "b", "a"], dtype=StringDtype()))
+        ser = Series(["d"], dtype=StringDtype())
+        result = cat.add_categories(ser)
+        expected = Categorical(
+            Series(["a", "b", "a"], dtype=StringDtype()),
+            categories=Series(["a", "b", "d"], dtype=StringDtype()),
+        )
+        tm.assert_categorical_equal(result, expected)
+
+    def test_set_categories(self):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        exp_categories = Index(["c", "b", "a"])
+        exp_values = np.array(["a", "b", "c", "a"], dtype=np.object_)
+
+        cat = cat.set_categories(["c", "b", "a"])
+        res = cat.set_categories(["a", "b", "c"])
+        # cat must be the same as before
+        tm.assert_index_equal(cat.categories, exp_categories)
+        tm.assert_numpy_array_equal(cat.__array__(), exp_values)
+        # only res is changed
+        exp_categories_back = Index(["a", "b", "c"])
+        tm.assert_index_equal(res.categories, exp_categories_back)
+        tm.assert_numpy_array_equal(res.__array__(), exp_values)
+
+        # not all "old" included in "new" -> all not included ones are now
+        # np.nan
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        res = cat.set_categories(["a"])
+        tm.assert_numpy_array_equal(res.codes, np.array([0, -1, -1, 0], dtype=np.int8))
+
+        # still not all "old" in "new"
+        res = cat.set_categories(["a", "b", "d"])
+        tm.assert_numpy_array_equal(res.codes, np.array([0, 1, -1, 0], dtype=np.int8))
+        tm.assert_index_equal(res.categories, Index(["a", "b", "d"]))
+
+        # all "old" included in "new"
+        cat = cat.set_categories(["a", "b", "c", "d"])
+        exp_categories = Index(["a", "b", "c", "d"])
+        tm.assert_index_equal(cat.categories, exp_categories)
+
+        # internals...
+        c = Categorical([1, 2, 3, 4, 1], categories=[1, 2, 3, 4], ordered=True)
+        tm.assert_numpy_array_equal(c._codes, np.array([0, 1, 2, 3, 0], dtype=np.int8))
+        tm.assert_index_equal(c.categories, Index([1, 2, 3, 4]))
+
+        exp = np.array([1, 2, 3, 4, 1], dtype=np.int64)
+        tm.assert_numpy_array_equal(np.asarray(c), exp)
+
+        # all "pointers" to '4' must be changed from 3 to 0,...
+        c = c.set_categories([4, 3, 2, 1])
+
+        # positions are changed
+        tm.assert_numpy_array_equal(c._codes, np.array([3, 2, 1, 0, 3], dtype=np.int8))
+
+        # categories are now in new order
+        tm.assert_index_equal(c.categories, Index([4, 3, 2, 1]))
+
+        # output is the same
+        exp = np.array([1, 2, 3, 4, 1], dtype=np.int64)
+        tm.assert_numpy_array_equal(np.asarray(c), exp)
+        assert c.min() == 4
+        assert c.max() == 1
+
+        # set_categories should set the ordering if specified
+        c2 = c.set_categories([4, 3, 2, 1], ordered=False)
+        assert not c2.ordered
+
+        tm.assert_numpy_array_equal(np.asarray(c), np.asarray(c2))
+
+        # set_categories should pass thru the ordering
+        c2 = c.set_ordered(False).set_categories([4, 3, 2, 1])
+        assert not c2.ordered
+
+        tm.assert_numpy_array_equal(np.asarray(c), np.asarray(c2))
+
+    @pytest.mark.parametrize(
+        "values, categories, new_categories",
+        [
+            # No NaNs, same cats, same order
+            (["a", "b", "a"], ["a", "b"], ["a", "b"]),
+            # No NaNs, same cats, different order
+            (["a", "b", "a"], ["a", "b"], ["b", "a"]),
+            # Same, unsorted
+            (["b", "a", "a"], ["a", "b"], ["a", "b"]),
+            # No NaNs, same cats, different order
+            (["b", "a", "a"], ["a", "b"], ["b", "a"]),
+            # NaNs
+            (["a", "b", "c"], ["a", "b"], ["a", "b"]),
+            (["a", "b", "c"], ["a", "b"], ["b", "a"]),
+            (["b", "a", "c"], ["a", "b"], ["a", "b"]),
+            (["b", "a", "c"], ["a", "b"], ["a", "b"]),
+            # Introduce NaNs
+            (["a", "b", "c"], ["a", "b"], ["a"]),
+            (["a", "b", "c"], ["a", "b"], ["b"]),
+            (["b", "a", "c"], ["a", "b"], ["a"]),
+            (["b", "a", "c"], ["a", "b"], ["a"]),
+            # No overlap
+            (["a", "b", "c"], ["a", "b"], ["d", "e"]),
+        ],
+    )
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_set_categories_many(self, values, categories, new_categories, ordered):
+        c = Categorical(values, categories)
+        expected = Categorical(values, new_categories, ordered)
+        result = c.set_categories(new_categories, ordered=ordered)
+        tm.assert_categorical_equal(result, expected)
+
+    def test_set_categories_rename_less(self):
+        # GH 24675
+        cat = Categorical(["A", "B"])
+        result = cat.set_categories(["A"], rename=True)
+        expected = Categorical(["A", np.nan])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_set_categories_private(self):
+        cat = Categorical(["a", "b", "c"], categories=["a", "b", "c", "d"])
+        cat._set_categories(["a", "c", "d", "e"])
+        expected = Categorical(["a", "c", "d"], categories=list("acde"))
+        tm.assert_categorical_equal(cat, expected)
+
+        # fastpath
+        cat = Categorical(["a", "b", "c"], categories=["a", "b", "c", "d"])
+        cat._set_categories(["a", "c", "d", "e"], fastpath=True)
+        expected = Categorical(["a", "c", "d"], categories=list("acde"))
+        tm.assert_categorical_equal(cat, expected)
+
+    def test_remove_categories(self):
+        cat = Categorical(["a", "b", "c", "a"], ordered=True)
+        old = cat.copy()
+        new = Categorical(["a", "b", np.nan, "a"], categories=["a", "b"], ordered=True)
+
+        res = cat.remove_categories("c")
+        tm.assert_categorical_equal(cat, old)
+        tm.assert_categorical_equal(res, new)
+
+        res = cat.remove_categories(["c"])
+        tm.assert_categorical_equal(cat, old)
+        tm.assert_categorical_equal(res, new)
+
+    @pytest.mark.parametrize("removals", [["c"], ["c", np.nan], "c", ["c", "c"]])
+    def test_remove_categories_raises(self, removals):
+        cat = Categorical(["a", "b", "a"])
+        message = re.escape("removals must all be in old categories: {'c'}")
+
+        with pytest.raises(ValueError, match=message):
+            cat.remove_categories(removals)
+
+    def test_remove_unused_categories(self):
+        c = Categorical(["a", "b", "c", "d", "a"], categories=["a", "b", "c", "d", "e"])
+        exp_categories_all = Index(["a", "b", "c", "d", "e"])
+        exp_categories_dropped = Index(["a", "b", "c", "d"])
+
+        tm.assert_index_equal(c.categories, exp_categories_all)
+
+        res = c.remove_unused_categories()
+        tm.assert_index_equal(res.categories, exp_categories_dropped)
+        tm.assert_index_equal(c.categories, exp_categories_all)
+
+        # with NaN values (GH11599)
+        c = Categorical(["a", "b", "c", np.nan], categories=["a", "b", "c", "d", "e"])
+        res = c.remove_unused_categories()
+        tm.assert_index_equal(res.categories, Index(np.array(["a", "b", "c"])))
+        exp_codes = np.array([0, 1, 2, -1], dtype=np.int8)
+        tm.assert_numpy_array_equal(res.codes, exp_codes)
+        tm.assert_index_equal(c.categories, exp_categories_all)
+
+        val = ["F", np.nan, "D", "B", "D", "F", np.nan]
+        cat = Categorical(values=val, categories=list("ABCDEFG"))
+        out = cat.remove_unused_categories()
+        tm.assert_index_equal(out.categories, Index(["B", "D", "F"]))
+        exp_codes = np.array([2, -1, 1, 0, 1, 2, -1], dtype=np.int8)
+        tm.assert_numpy_array_equal(out.codes, exp_codes)
+        assert out.tolist() == val
+
+        alpha = list("abcdefghijklmnopqrstuvwxyz")
+        val = np.random.default_rng(2).choice(alpha[::2], 10000).astype("object")
+        val[np.random.default_rng(2).choice(len(val), 100)] = np.nan
+
+        cat = Categorical(values=val, categories=alpha)
+        out = cat.remove_unused_categories()
+        assert out.tolist() == val.tolist()
+
+
+class TestCategoricalAPIWithFactor:
+    def test_describe(self):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        # string type
+        desc = factor.describe()
+        assert factor.ordered
+        exp_index = CategoricalIndex(
+            ["a", "b", "c"], name="categories", ordered=factor.ordered
+        )
+        expected = DataFrame(
+            {"counts": [3, 2, 3], "freqs": [3 / 8.0, 2 / 8.0, 3 / 8.0]}, index=exp_index
+        )
+        tm.assert_frame_equal(desc, expected)
+
+        # check unused categories
+        cat = factor.copy()
+        cat = cat.set_categories(["a", "b", "c", "d"])
+        desc = cat.describe()
+
+        exp_index = CategoricalIndex(
+            list("abcd"), ordered=factor.ordered, name="categories"
+        )
+        expected = DataFrame(
+            {"counts": [3, 2, 3, 0], "freqs": [3 / 8.0, 2 / 8.0, 3 / 8.0, 0]},
+            index=exp_index,
+        )
+        tm.assert_frame_equal(desc, expected)
+
+        # check an integer one
+        cat = Categorical([1, 2, 3, 1, 2, 3, 3, 2, 1, 1, 1])
+        desc = cat.describe()
+        exp_index = CategoricalIndex([1, 2, 3], ordered=cat.ordered, name="categories")
+        expected = DataFrame(
+            {"counts": [5, 3, 3], "freqs": [5 / 11.0, 3 / 11.0, 3 / 11.0]},
+            index=exp_index,
+        )
+        tm.assert_frame_equal(desc, expected)
+
+        # https://github.com/pandas-dev/pandas/issues/3678
+        # describe should work with NaN
+        cat = Categorical([np.nan, 1, 2, 2])
+        desc = cat.describe()
+        expected = DataFrame(
+            {"counts": [1, 2, 1], "freqs": [1 / 4.0, 2 / 4.0, 1 / 4.0]},
+            index=CategoricalIndex(
+                [1, 2, np.nan], categories=[1, 2], name="categories"
+            ),
+        )
+        tm.assert_frame_equal(desc, expected)
+
+
+class TestPrivateCategoricalAPI:
+    def test_codes_immutable(self):
+        # Codes should be read only
+        c = Categorical(["a", "b", "c", "a", np.nan])
+        exp = np.array([0, 1, 2, 0, -1], dtype="int8")
+        tm.assert_numpy_array_equal(c.codes, exp)
+
+        # Assignments to codes should raise
+        msg = (
+            "property 'codes' of 'Categorical' object has no setter"
+            if PY311
+            else "can't set attribute"
+        )
+        with pytest.raises(AttributeError, match=msg):
+            c.codes = np.array([0, 1, 2, 0, 1], dtype="int8")
+
+        # changes in the codes array should raise
+        codes = c.codes
+
+        with pytest.raises(ValueError, match="assignment destination is read-only"):
+            codes[4] = 1
+
+        # But even after getting the codes, the original array should still be
+        # writeable!
+        c[4] = "a"
+        exp = np.array([0, 1, 2, 0, 0], dtype="int8")
+        tm.assert_numpy_array_equal(c.codes, exp)
+        c._codes[4] = 2
+        exp = np.array([0, 1, 2, 0, 2], dtype="int8")
+        tm.assert_numpy_array_equal(c.codes, exp)
+
+    @pytest.mark.parametrize(
+        "codes, old, new, expected",
+        [
+            ([0, 1], ["a", "b"], ["a", "b"], [0, 1]),
+            ([0, 1], ["b", "a"], ["b", "a"], [0, 1]),
+            ([0, 1], ["a", "b"], ["b", "a"], [1, 0]),
+            ([0, 1], ["b", "a"], ["a", "b"], [1, 0]),
+            ([0, 1, 0, 1], ["a", "b"], ["a", "b", "c"], [0, 1, 0, 1]),
+            ([0, 1, 2, 2], ["a", "b", "c"], ["a", "b"], [0, 1, -1, -1]),
+            ([0, 1, -1], ["a", "b", "c"], ["a", "b", "c"], [0, 1, -1]),
+            ([0, 1, -1], ["a", "b", "c"], ["b"], [-1, 0, -1]),
+            ([0, 1, -1], ["a", "b", "c"], ["d"], [-1, -1, -1]),
+            ([0, 1, -1], ["a", "b", "c"], [], [-1, -1, -1]),
+            ([-1, -1], [], ["a", "b"], [-1, -1]),
+            ([1, 0], ["b", "a"], ["a", "b"], [0, 1]),
+        ],
+    )
+    def test_recode_to_categories(self, codes, old, new, expected):
+        codes = np.asanyarray(codes, dtype=np.int8)
+        expected = np.asanyarray(expected, dtype=np.int8)
+        old = Index(old)
+        new = Index(new)
+        result = recode_for_categories(codes, old, new)
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_recode_to_categories_large(self):
+        N = 1000
+        codes = np.arange(N)
+        old = Index(codes)
+        expected = np.arange(N - 1, -1, -1, dtype=np.int16)
+        new = Index(expected)
+        result = recode_for_categories(codes, old, new)
+        tm.assert_numpy_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_astype.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_astype.py
new file mode 100644
index 0000000000000000000000000000000000000000..ee930ac84aaf246c6e79cb1c7eb7a7dfe179ff8c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_astype.py
@@ -0,0 +1,155 @@
+import numpy as np
+import pytest
+
+from pandas import (
+    Categorical,
+    CategoricalDtype,
+    CategoricalIndex,
+    DatetimeIndex,
+    Interval,
+    NaT,
+    Period,
+    Timestamp,
+    array,
+    to_datetime,
+)
+import pandas._testing as tm
+
+
+class TestAstype:
+    @pytest.mark.parametrize("cls", [Categorical, CategoricalIndex])
+    @pytest.mark.parametrize("values", [[1, np.nan], [Timestamp("2000"), NaT]])
+    def test_astype_nan_to_int(self, cls, values):
+        # GH#28406
+        obj = cls(values)
+
+        msg = "Cannot (cast|convert)"
+        with pytest.raises((ValueError, TypeError), match=msg):
+            obj.astype(int)
+
+    @pytest.mark.parametrize(
+        "expected",
+        [
+            array(["2019", "2020"], dtype="datetime64[ns, UTC]"),
+            array([0, 0], dtype="timedelta64[ns]"),
+            array([Period("2019"), Period("2020")], dtype="period[Y-DEC]"),
+            array([Interval(0, 1), Interval(1, 2)], dtype="interval"),
+            array([1, np.nan], dtype="Int64"),
+        ],
+    )
+    def test_astype_category_to_extension_dtype(self, expected):
+        # GH#28668
+        result = expected.astype("category").astype(expected.dtype)
+
+        tm.assert_extension_array_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "dtype, expected",
+        [
+            (
+                "datetime64[ns]",
+                np.array(["2015-01-01T00:00:00.000000000"], dtype="datetime64[ns]"),
+            ),
+            (
+                "datetime64[ns, MET]",
+                DatetimeIndex([Timestamp("2015-01-01 00:00:00+0100", tz="MET")]).array,
+            ),
+        ],
+    )
+    def test_astype_to_datetime64(self, dtype, expected):
+        # GH#28448
+        result = Categorical(["2015-01-01"]).astype(dtype)
+        assert result == expected
+
+    def test_astype_str_int_categories_to_nullable_int(self):
+        # GH#39616
+        dtype = CategoricalDtype([str(i) for i in range(5)])
+        codes = np.random.default_rng(2).integers(5, size=20)
+        arr = Categorical.from_codes(codes, dtype=dtype)
+
+        res = arr.astype("Int64")
+        expected = array(codes, dtype="Int64")
+        tm.assert_extension_array_equal(res, expected)
+
+    def test_astype_str_int_categories_to_nullable_float(self):
+        # GH#39616
+        dtype = CategoricalDtype([str(i / 2) for i in range(5)])
+        codes = np.random.default_rng(2).integers(5, size=20)
+        arr = Categorical.from_codes(codes, dtype=dtype)
+
+        res = arr.astype("Float64")
+        expected = array(codes, dtype="Float64") / 2
+        tm.assert_extension_array_equal(res, expected)
+
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_astype(self, ordered):
+        # string
+        cat = Categorical(list("abbaaccc"), ordered=ordered)
+        result = cat.astype(object)
+        expected = np.array(cat)
+        tm.assert_numpy_array_equal(result, expected)
+
+        msg = r"Cannot cast object|str dtype to float64"
+        with pytest.raises(ValueError, match=msg):
+            cat.astype(float)
+
+        # numeric
+        cat = Categorical([0, 1, 2, 2, 1, 0, 1, 0, 2], ordered=ordered)
+        result = cat.astype(object)
+        expected = np.array(cat, dtype=object)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = cat.astype(int)
+        expected = np.array(cat, dtype="int")
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = cat.astype(float)
+        expected = np.array(cat, dtype=float)
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize("dtype_ordered", [True, False])
+    @pytest.mark.parametrize("cat_ordered", [True, False])
+    def test_astype_category(self, dtype_ordered, cat_ordered):
+        # GH#10696/GH#18593
+        data = list("abcaacbab")
+        cat = Categorical(data, categories=list("bac"), ordered=cat_ordered)
+
+        # standard categories
+        dtype = CategoricalDtype(ordered=dtype_ordered)
+        result = cat.astype(dtype)
+        expected = Categorical(data, categories=cat.categories, ordered=dtype_ordered)
+        tm.assert_categorical_equal(result, expected)
+
+        # non-standard categories
+        dtype = CategoricalDtype(list("adc"), dtype_ordered)
+        result = cat.astype(dtype)
+        expected = Categorical(data, dtype=dtype)
+        tm.assert_categorical_equal(result, expected)
+
+        if dtype_ordered is False:
+            # dtype='category' can't specify ordered, so only test once
+            result = cat.astype("category")
+            expected = cat
+            tm.assert_categorical_equal(result, expected)
+
+    def test_astype_object_datetime_categories(self):
+        # GH#40754
+        cat = Categorical(to_datetime(["2021-03-27", NaT]))
+        result = cat.astype(object)
+        expected = np.array([Timestamp("2021-03-27 00:00:00"), NaT], dtype="object")
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_astype_object_timestamp_categories(self):
+        # GH#18024
+        cat = Categorical([Timestamp("2014-01-01")])
+        result = cat.astype(object)
+        expected = np.array([Timestamp("2014-01-01 00:00:00")], dtype="object")
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_astype_category_readonly_mask_values(self):
+        # GH#53658
+        arr = array([0, 1, 2], dtype="Int64")
+        arr._mask.flags["WRITEABLE"] = False
+        result = arr.astype("category")
+        expected = array([0, 1, 2], dtype="Int64").astype("category")
+        tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_constructors.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_constructors.py
new file mode 100644
index 0000000000000000000000000000000000000000..8ac479cf8a0a4a7fb0c11f94f04bad496f7a6343
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_constructors.py
@@ -0,0 +1,787 @@
+from datetime import (
+    date,
+    datetime,
+)
+
+import numpy as np
+import pytest
+
+from pandas._config import using_string_dtype
+
+from pandas.compat import HAS_PYARROW
+
+from pandas.core.dtypes.common import (
+    is_float_dtype,
+    is_integer_dtype,
+)
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    CategoricalIndex,
+    DatetimeIndex,
+    Index,
+    Interval,
+    IntervalIndex,
+    MultiIndex,
+    NaT,
+    Series,
+    Timestamp,
+    date_range,
+    period_range,
+    timedelta_range,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalConstructors:
+    def test_fastpath_deprecated(self):
+        codes = np.array([1, 2, 3])
+        dtype = CategoricalDtype(categories=["a", "b", "c", "d"], ordered=False)
+        msg = "The 'fastpath' keyword in Categorical is deprecated"
+        with tm.assert_produces_warning(DeprecationWarning, match=msg):
+            Categorical(codes, dtype=dtype, fastpath=True)
+
+    def test_categorical_from_cat_and_dtype_str_preserve_ordered(self):
+        # GH#49309 we should preserve orderedness in `res`
+        cat = Categorical([3, 1], categories=[3, 2, 1], ordered=True)
+
+        res = Categorical(cat, dtype="category")
+        assert res.dtype.ordered
+
+    def test_categorical_disallows_scalar(self):
+        # GH#38433
+        with pytest.raises(TypeError, match="Categorical input must be list-like"):
+            Categorical("A", categories=["A", "B"])
+
+    def test_categorical_1d_only(self):
+        # ndim > 1
+        msg = "> 1 ndim Categorical are not supported at this time"
+        with pytest.raises(NotImplementedError, match=msg):
+            Categorical(np.array([list("abcd")]))
+
+    def test_validate_ordered(self):
+        # see gh-14058
+        exp_msg = "'ordered' must either be 'True' or 'False'"
+        exp_err = TypeError
+
+        # This should be a boolean.
+        ordered = np.array([0, 1, 2])
+
+        with pytest.raises(exp_err, match=exp_msg):
+            Categorical([1, 2, 3], ordered=ordered)
+
+        with pytest.raises(exp_err, match=exp_msg):
+            Categorical.from_codes(
+                [0, 0, 1], categories=["a", "b", "c"], ordered=ordered
+            )
+
+    def test_constructor_empty(self):
+        # GH 17248
+        c = Categorical([])
+        expected = Index([])
+        tm.assert_index_equal(c.categories, expected)
+
+        c = Categorical([], categories=[1, 2, 3])
+        expected = Index([1, 2, 3], dtype=np.int64)
+        tm.assert_index_equal(c.categories, expected)
+
+    def test_constructor_empty_boolean(self):
+        # see gh-22702
+        cat = Categorical([], categories=[True, False])
+        categories = sorted(cat.categories.tolist())
+        assert categories == [False, True]
+
+    def test_constructor_tuples(self):
+        values = np.array([(1,), (1, 2), (1,), (1, 2)], dtype=object)
+        result = Categorical(values)
+        expected = Index([(1,), (1, 2)], tupleize_cols=False)
+        tm.assert_index_equal(result.categories, expected)
+        assert result.ordered is False
+
+    def test_constructor_tuples_datetimes(self):
+        # numpy will auto reshape when all of the tuples are the
+        # same len, so add an extra one with 2 items and slice it off
+        values = np.array(
+            [
+                (Timestamp("2010-01-01"),),
+                (Timestamp("2010-01-02"),),
+                (Timestamp("2010-01-01"),),
+                (Timestamp("2010-01-02"),),
+                ("a", "b"),
+            ],
+            dtype=object,
+        )[:-1]
+        result = Categorical(values)
+        expected = Index(
+            [(Timestamp("2010-01-01"),), (Timestamp("2010-01-02"),)],
+            tupleize_cols=False,
+        )
+        tm.assert_index_equal(result.categories, expected)
+
+    def test_constructor_unsortable(self):
+        # it works!
+        arr = np.array([1, 2, 3, datetime.now()], dtype="O")
+        factor = Categorical(arr, ordered=False)
+        assert not factor.ordered
+
+        # this however will raise as cannot be sorted
+        msg = (
+            "'values' is not ordered, please explicitly specify the "
+            "categories order by passing in a categories argument."
+        )
+        with pytest.raises(TypeError, match=msg):
+            Categorical(arr, ordered=True)
+
+    def test_constructor_interval(self):
+        result = Categorical(
+            [Interval(1, 2), Interval(2, 3), Interval(3, 6)], ordered=True
+        )
+        ii = IntervalIndex([Interval(1, 2), Interval(2, 3), Interval(3, 6)])
+        exp = Categorical(ii, ordered=True)
+        tm.assert_categorical_equal(result, exp)
+        tm.assert_index_equal(result.categories, ii)
+
+    def test_constructor(self):
+        exp_arr = np.array(["a", "b", "c", "a", "b", "c"], dtype=np.object_)
+        c1 = Categorical(exp_arr)
+        tm.assert_numpy_array_equal(c1.__array__(), exp_arr)
+        c2 = Categorical(exp_arr, categories=["a", "b", "c"])
+        tm.assert_numpy_array_equal(c2.__array__(), exp_arr)
+        c2 = Categorical(exp_arr, categories=["c", "b", "a"])
+        tm.assert_numpy_array_equal(c2.__array__(), exp_arr)
+
+        # categories must be unique
+        msg = "Categorical categories must be unique"
+        with pytest.raises(ValueError, match=msg):
+            Categorical([1, 2], [1, 2, 2])
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical(["a", "b"], ["a", "b", "b"])
+
+        # The default should be unordered
+        c1 = Categorical(["a", "b", "c", "a"])
+        assert not c1.ordered
+
+        # Categorical as input
+        c1 = Categorical(["a", "b", "c", "a"])
+        c2 = Categorical(c1)
+        tm.assert_categorical_equal(c1, c2)
+
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "b", "c", "d"])
+        c2 = Categorical(c1)
+        tm.assert_categorical_equal(c1, c2)
+
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "c", "b"])
+        c2 = Categorical(c1)
+        tm.assert_categorical_equal(c1, c2)
+
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "c", "b"])
+        c2 = Categorical(c1, categories=["a", "b", "c"])
+        tm.assert_numpy_array_equal(c1.__array__(), c2.__array__())
+        tm.assert_index_equal(c2.categories, Index(["a", "b", "c"]))
+
+        # Series of dtype category
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "b", "c", "d"])
+        c2 = Categorical(Series(c1))
+        tm.assert_categorical_equal(c1, c2)
+
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "c", "b"])
+        c2 = Categorical(Series(c1))
+        tm.assert_categorical_equal(c1, c2)
+
+        # Series
+        c1 = Categorical(["a", "b", "c", "a"])
+        c2 = Categorical(Series(["a", "b", "c", "a"]))
+        tm.assert_categorical_equal(c1, c2)
+
+        c1 = Categorical(["a", "b", "c", "a"], categories=["a", "b", "c", "d"])
+        c2 = Categorical(Series(["a", "b", "c", "a"]), categories=["a", "b", "c", "d"])
+        tm.assert_categorical_equal(c1, c2)
+
+        # This should result in integer categories, not float!
+        cat = Categorical([1, 2, 3, np.nan], categories=[1, 2, 3])
+        assert is_integer_dtype(cat.categories)
+
+        # https://github.com/pandas-dev/pandas/issues/3678
+        cat = Categorical([np.nan, 1, 2, 3])
+        assert is_integer_dtype(cat.categories)
+
+        # this should result in floats
+        cat = Categorical([np.nan, 1, 2.0, 3])
+        assert is_float_dtype(cat.categories)
+
+        cat = Categorical([np.nan, 1.0, 2.0, 3.0])
+        assert is_float_dtype(cat.categories)
+
+        # This doesn't work -> this would probably need some kind of "remember
+        # the original type" feature to try to cast the array interface result
+        # to...
+
+        # vals = np.asarray(cat[cat.notna()])
+        # assert is_integer_dtype(vals)
+
+        # corner cases
+        cat = Categorical([1])
+        assert len(cat.categories) == 1
+        assert cat.categories[0] == 1
+        assert len(cat.codes) == 1
+        assert cat.codes[0] == 0
+
+        cat = Categorical(["a"])
+        assert len(cat.categories) == 1
+        assert cat.categories[0] == "a"
+        assert len(cat.codes) == 1
+        assert cat.codes[0] == 0
+
+        # two arrays
+        #  - when the first is an integer dtype and the second is not
+        #  - when the resulting codes are all -1/NaN
+        with tm.assert_produces_warning(None):
+            Categorical([0, 1, 2, 0, 1, 2], categories=["a", "b", "c"])
+
+        with tm.assert_produces_warning(None):
+            Categorical([0, 1, 2, 0, 1, 2], categories=[3, 4, 5])
+
+        # the next one are from the old docs
+        with tm.assert_produces_warning(None):
+            Categorical([0, 1, 2, 0, 1, 2], [1, 2, 3])
+            cat = Categorical([1, 2], categories=[1, 2, 3])
+
+        # this is a legitimate constructor
+        with tm.assert_produces_warning(None):
+            Categorical(np.array([], dtype="int64"), categories=[3, 2, 1], ordered=True)
+
+    def test_constructor_with_existing_categories(self):
+        # GH25318: constructing with pd.Series used to bogusly skip recoding
+        # categories
+        c0 = Categorical(["a", "b", "c", "a"])
+        c1 = Categorical(["a", "b", "c", "a"], categories=["b", "c"])
+
+        c2 = Categorical(c0, categories=c1.categories)
+        tm.assert_categorical_equal(c1, c2)
+
+        c3 = Categorical(Series(c0), categories=c1.categories)
+        tm.assert_categorical_equal(c1, c3)
+
+    def test_constructor_not_sequence(self):
+        # https://github.com/pandas-dev/pandas/issues/16022
+        msg = r"^Parameter 'categories' must be list-like, was"
+        with pytest.raises(TypeError, match=msg):
+            Categorical(["a", "b"], categories="a")
+
+    def test_constructor_with_null(self):
+        # Cannot have NaN in categories
+        msg = "Categorical categories cannot be null"
+        with pytest.raises(ValueError, match=msg):
+            Categorical([np.nan, "a", "b", "c"], categories=[np.nan, "a", "b", "c"])
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical([None, "a", "b", "c"], categories=[None, "a", "b", "c"])
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical(
+                DatetimeIndex(["nat", "20160101"]),
+                categories=[NaT, Timestamp("20160101")],
+            )
+
+    def test_constructor_with_index(self):
+        ci = CategoricalIndex(list("aabbca"), categories=list("cab"))
+        tm.assert_categorical_equal(ci.values, Categorical(ci))
+
+        ci = CategoricalIndex(list("aabbca"), categories=list("cab"))
+        tm.assert_categorical_equal(
+            ci.values, Categorical(ci.astype(object), categories=ci.categories)
+        )
+
+    def test_constructor_with_generator(self):
+        # This was raising an Error in isna(single_val).any() because isna
+        # returned a scalar for a generator
+
+        exp = Categorical([0, 1, 2])
+        cat = Categorical(x for x in [0, 1, 2])
+        tm.assert_categorical_equal(cat, exp)
+        cat = Categorical(range(3))
+        tm.assert_categorical_equal(cat, exp)
+
+        MultiIndex.from_product([range(5), ["a", "b", "c"]])
+
+        # check that categories accept generators and sequences
+        cat = Categorical([0, 1, 2], categories=(x for x in [0, 1, 2]))
+        tm.assert_categorical_equal(cat, exp)
+        cat = Categorical([0, 1, 2], categories=range(3))
+        tm.assert_categorical_equal(cat, exp)
+
+    def test_constructor_with_rangeindex(self):
+        # RangeIndex is preserved in Categories
+        rng = Index(range(3))
+
+        cat = Categorical(rng)
+        tm.assert_index_equal(cat.categories, rng, exact=True)
+
+        cat = Categorical([1, 2, 0], categories=rng)
+        tm.assert_index_equal(cat.categories, rng, exact=True)
+
+    @pytest.mark.parametrize(
+        "dtl",
+        [
+            date_range("1995-01-01 00:00:00", periods=5, freq="s"),
+            date_range("1995-01-01 00:00:00", periods=5, freq="s", tz="US/Eastern"),
+            timedelta_range("1 day", periods=5, freq="s"),
+        ],
+    )
+    def test_constructor_with_datetimelike(self, dtl):
+        # see gh-12077
+        # constructor with a datetimelike and NaT
+
+        s = Series(dtl)
+        c = Categorical(s)
+
+        expected = type(dtl)(s)
+        expected._data.freq = None
+
+        tm.assert_index_equal(c.categories, expected)
+        tm.assert_numpy_array_equal(c.codes, np.arange(5, dtype="int8"))
+
+        # with NaT
+        s2 = s.copy()
+        s2.iloc[-1] = NaT
+        c = Categorical(s2)
+
+        expected = type(dtl)(s2.dropna())
+        expected._data.freq = None
+
+        tm.assert_index_equal(c.categories, expected)
+
+        exp = np.array([0, 1, 2, 3, -1], dtype=np.int8)
+        tm.assert_numpy_array_equal(c.codes, exp)
+
+        result = repr(c)
+        assert "NaT" in result
+
+    def test_constructor_from_index_series_datetimetz(self):
+        idx = date_range("2015-01-01 10:00", freq="D", periods=3, tz="US/Eastern")
+        idx = idx._with_freq(None)  # freq not preserved in result.categories
+        result = Categorical(idx)
+        tm.assert_index_equal(result.categories, idx)
+
+        result = Categorical(Series(idx))
+        tm.assert_index_equal(result.categories, idx)
+
+    def test_constructor_date_objects(self):
+        # we dont cast date objects to timestamps, matching Index constructor
+        v = date.today()
+
+        cat = Categorical([v, v])
+        assert cat.categories.dtype == object
+        assert type(cat.categories[0]) is date
+
+    def test_constructor_from_index_series_timedelta(self):
+        idx = timedelta_range("1 days", freq="D", periods=3)
+        idx = idx._with_freq(None)  # freq not preserved in result.categories
+        result = Categorical(idx)
+        tm.assert_index_equal(result.categories, idx)
+
+        result = Categorical(Series(idx))
+        tm.assert_index_equal(result.categories, idx)
+
+    def test_constructor_from_index_series_period(self):
+        idx = period_range("2015-01-01", freq="D", periods=3)
+        result = Categorical(idx)
+        tm.assert_index_equal(result.categories, idx)
+
+        result = Categorical(Series(idx))
+        tm.assert_index_equal(result.categories, idx)
+
+    @pytest.mark.parametrize(
+        "values",
+        [
+            np.array([1.0, 1.2, 1.8, np.nan]),
+            np.array([1, 2, 3], dtype="int64"),
+            ["a", "b", "c", np.nan],
+            [pd.Period("2014-01"), pd.Period("2014-02"), NaT],
+            [Timestamp("2014-01-01"), Timestamp("2014-01-02"), NaT],
+            [
+                Timestamp("2014-01-01", tz="US/Eastern"),
+                Timestamp("2014-01-02", tz="US/Eastern"),
+                NaT,
+            ],
+        ],
+    )
+    def test_constructor_invariant(self, values):
+        # GH 14190
+        c = Categorical(values)
+        c2 = Categorical(c)
+        tm.assert_categorical_equal(c, c2)
+
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_constructor_with_dtype(self, ordered):
+        categories = ["b", "a", "c"]
+        dtype = CategoricalDtype(categories, ordered=ordered)
+        result = Categorical(["a", "b", "a", "c"], dtype=dtype)
+        expected = Categorical(
+            ["a", "b", "a", "c"], categories=categories, ordered=ordered
+        )
+        tm.assert_categorical_equal(result, expected)
+        assert result.ordered is ordered
+
+    def test_constructor_dtype_and_others_raises(self):
+        dtype = CategoricalDtype(["a", "b"], ordered=True)
+        msg = "Cannot specify `categories` or `ordered` together with `dtype`."
+        with pytest.raises(ValueError, match=msg):
+            Categorical(["a", "b"], categories=["a", "b"], dtype=dtype)
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical(["a", "b"], ordered=True, dtype=dtype)
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical(["a", "b"], ordered=False, dtype=dtype)
+
+    @pytest.mark.parametrize("categories", [None, ["a", "b"], ["a", "c"]])
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_constructor_str_category(self, categories, ordered):
+        result = Categorical(
+            ["a", "b"], categories=categories, ordered=ordered, dtype="category"
+        )
+        expected = Categorical(["a", "b"], categories=categories, ordered=ordered)
+        tm.assert_categorical_equal(result, expected)
+
+    def test_constructor_str_unknown(self):
+        with pytest.raises(ValueError, match="Unknown dtype"):
+            Categorical([1, 2], dtype="foo")
+
+    @pytest.mark.xfail(
+        using_string_dtype() and HAS_PYARROW, reason="Can't be NumPy strings"
+    )
+    def test_constructor_np_strs(self):
+        # GH#31499 Hashtable.map_locations needs to work on np.str_ objects
+        cat = Categorical(["1", "0", "1"], [np.str_("0"), np.str_("1")])
+        assert all(isinstance(x, np.str_) for x in cat.categories)
+
+    def test_constructor_from_categorical_with_dtype(self):
+        dtype = CategoricalDtype(["a", "b", "c"], ordered=True)
+        values = Categorical(["a", "b", "d"])
+        result = Categorical(values, dtype=dtype)
+        # We use dtype.categories, not values.categories
+        expected = Categorical(
+            ["a", "b", "d"], categories=["a", "b", "c"], ordered=True
+        )
+        tm.assert_categorical_equal(result, expected)
+
+    def test_constructor_from_categorical_with_unknown_dtype(self):
+        dtype = CategoricalDtype(None, ordered=True)
+        values = Categorical(["a", "b", "d"])
+        result = Categorical(values, dtype=dtype)
+        # We use values.categories, not dtype.categories
+        expected = Categorical(
+            ["a", "b", "d"], categories=["a", "b", "d"], ordered=True
+        )
+        tm.assert_categorical_equal(result, expected)
+
+    def test_constructor_from_categorical_string(self):
+        values = Categorical(["a", "b", "d"])
+        # use categories, ordered
+        result = Categorical(
+            values, categories=["a", "b", "c"], ordered=True, dtype="category"
+        )
+        expected = Categorical(
+            ["a", "b", "d"], categories=["a", "b", "c"], ordered=True
+        )
+        tm.assert_categorical_equal(result, expected)
+
+        # No string
+        result = Categorical(values, categories=["a", "b", "c"], ordered=True)
+        tm.assert_categorical_equal(result, expected)
+
+    def test_constructor_with_categorical_categories(self):
+        # GH17884
+        expected = Categorical(["a", "b"], categories=["a", "b", "c"])
+
+        result = Categorical(["a", "b"], categories=Categorical(["a", "b", "c"]))
+        tm.assert_categorical_equal(result, expected)
+
+        result = Categorical(["a", "b"], categories=CategoricalIndex(["a", "b", "c"]))
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("klass", [lambda x: np.array(x, dtype=object), list])
+    def test_construction_with_null(self, klass, nulls_fixture):
+        # https://github.com/pandas-dev/pandas/issues/31927
+        values = klass(["a", nulls_fixture, "b"])
+        result = Categorical(values)
+
+        dtype = CategoricalDtype(["a", "b"])
+        codes = [0, -1, 1]
+        expected = Categorical.from_codes(codes=codes, dtype=dtype)
+
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("validate", [True, False])
+    def test_from_codes_nullable_int_categories(self, any_numeric_ea_dtype, validate):
+        # GH#39649
+        cats = pd.array(range(5), dtype=any_numeric_ea_dtype)
+        codes = np.random.default_rng(2).integers(5, size=3)
+        dtype = CategoricalDtype(cats)
+        arr = Categorical.from_codes(codes, dtype=dtype, validate=validate)
+        assert arr.categories.dtype == cats.dtype
+        tm.assert_index_equal(arr.categories, Index(cats))
+
+    def test_from_codes_empty(self):
+        cat = ["a", "b", "c"]
+        result = Categorical.from_codes([], categories=cat)
+        expected = Categorical([], categories=cat)
+
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("validate", [True, False])
+    def test_from_codes_validate(self, validate):
+        # GH53122
+        dtype = CategoricalDtype(["a", "b"])
+        if validate:
+            with pytest.raises(ValueError, match="codes need to be between "):
+                Categorical.from_codes([4, 5], dtype=dtype, validate=validate)
+        else:
+            # passes, though has incorrect codes, but that's the user responsibility
+            Categorical.from_codes([4, 5], dtype=dtype, validate=validate)
+
+    def test_from_codes_too_few_categories(self):
+        dtype = CategoricalDtype(categories=[1, 2])
+        msg = "codes need to be between "
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes([1, 2], categories=dtype.categories)
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes([1, 2], dtype=dtype)
+
+    def test_from_codes_non_int_codes(self):
+        dtype = CategoricalDtype(categories=[1, 2])
+        msg = "codes need to be array-like integers"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(["a"], categories=dtype.categories)
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(["a"], dtype=dtype)
+
+    def test_from_codes_non_unique_categories(self):
+        with pytest.raises(ValueError, match="Categorical categories must be unique"):
+            Categorical.from_codes([0, 1, 2], categories=["a", "a", "b"])
+
+    def test_from_codes_nan_cat_included(self):
+        with pytest.raises(ValueError, match="Categorical categories cannot be null"):
+            Categorical.from_codes([0, 1, 2], categories=["a", "b", np.nan])
+
+    def test_from_codes_too_negative(self):
+        dtype = CategoricalDtype(categories=["a", "b", "c"])
+        msg = r"codes need to be between -1 and len\(categories\)-1"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes([-2, 1, 2], categories=dtype.categories)
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes([-2, 1, 2], dtype=dtype)
+
+    def test_from_codes(self):
+        dtype = CategoricalDtype(categories=["a", "b", "c"])
+        exp = Categorical(["a", "b", "c"], ordered=False)
+        res = Categorical.from_codes([0, 1, 2], categories=dtype.categories)
+        tm.assert_categorical_equal(exp, res)
+
+        res = Categorical.from_codes([0, 1, 2], dtype=dtype)
+        tm.assert_categorical_equal(exp, res)
+
+    @pytest.mark.parametrize("klass", [Categorical, CategoricalIndex])
+    def test_from_codes_with_categorical_categories(self, klass):
+        # GH17884
+        expected = Categorical(["a", "b"], categories=["a", "b", "c"])
+
+        result = Categorical.from_codes([0, 1], categories=klass(["a", "b", "c"]))
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("klass", [Categorical, CategoricalIndex])
+    def test_from_codes_with_non_unique_categorical_categories(self, klass):
+        with pytest.raises(ValueError, match="Categorical categories must be unique"):
+            Categorical.from_codes([0, 1], klass(["a", "b", "a"]))
+
+    def test_from_codes_with_nan_code(self):
+        # GH21767
+        codes = [1, 2, np.nan]
+        dtype = CategoricalDtype(categories=["a", "b", "c"])
+        with pytest.raises(ValueError, match="codes need to be array-like integers"):
+            Categorical.from_codes(codes, categories=dtype.categories)
+        with pytest.raises(ValueError, match="codes need to be array-like integers"):
+            Categorical.from_codes(codes, dtype=dtype)
+
+    @pytest.mark.parametrize("codes", [[1.0, 2.0, 0], [1.1, 2.0, 0]])
+    def test_from_codes_with_float(self, codes):
+        # GH21767
+        # float codes should raise even if values are equal to integers
+        dtype = CategoricalDtype(categories=["a", "b", "c"])
+
+        msg = "codes need to be array-like integers"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(codes, dtype.categories)
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(codes, dtype=dtype)
+
+    def test_from_codes_with_dtype_raises(self):
+        msg = "Cannot specify"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(
+                [0, 1], categories=["a", "b"], dtype=CategoricalDtype(["a", "b"])
+            )
+
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(
+                [0, 1], ordered=True, dtype=CategoricalDtype(["a", "b"])
+            )
+
+    def test_from_codes_neither(self):
+        msg = "Both were None"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes([0, 1])
+
+    def test_from_codes_with_nullable_int(self):
+        codes = pd.array([0, 1], dtype="Int64")
+        categories = ["a", "b"]
+
+        result = Categorical.from_codes(codes, categories=categories)
+        expected = Categorical.from_codes(codes.to_numpy(int), categories=categories)
+
+        tm.assert_categorical_equal(result, expected)
+
+    def test_from_codes_with_nullable_int_na_raises(self):
+        codes = pd.array([0, None], dtype="Int64")
+        categories = ["a", "b"]
+
+        msg = "codes cannot contain NA values"
+        with pytest.raises(ValueError, match=msg):
+            Categorical.from_codes(codes, categories=categories)
+
+    @pytest.mark.parametrize("dtype", [None, "category"])
+    def test_from_inferred_categories(self, dtype):
+        cats = ["a", "b"]
+        codes = np.array([0, 0, 1, 1], dtype="i8")
+        result = Categorical._from_inferred_categories(cats, codes, dtype)
+        expected = Categorical.from_codes(codes, cats)
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("dtype", [None, "category"])
+    def test_from_inferred_categories_sorts(self, dtype):
+        cats = ["b", "a"]
+        codes = np.array([0, 1, 1, 1], dtype="i8")
+        result = Categorical._from_inferred_categories(cats, codes, dtype)
+        expected = Categorical.from_codes([1, 0, 0, 0], ["a", "b"])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_from_inferred_categories_dtype(self):
+        cats = ["a", "b", "d"]
+        codes = np.array([0, 1, 0, 2], dtype="i8")
+        dtype = CategoricalDtype(["c", "b", "a"], ordered=True)
+        result = Categorical._from_inferred_categories(cats, codes, dtype)
+        expected = Categorical(
+            ["a", "b", "a", "d"], categories=["c", "b", "a"], ordered=True
+        )
+        tm.assert_categorical_equal(result, expected)
+
+    def test_from_inferred_categories_coerces(self):
+        cats = ["1", "2", "bad"]
+        codes = np.array([0, 0, 1, 2], dtype="i8")
+        dtype = CategoricalDtype([1, 2])
+        result = Categorical._from_inferred_categories(cats, codes, dtype)
+        expected = Categorical([1, 1, 2, np.nan])
+        tm.assert_categorical_equal(result, expected)
+
+    @pytest.mark.parametrize("ordered", [None, True, False])
+    def test_construction_with_ordered(self, ordered):
+        # GH 9347, 9190
+        cat = Categorical([0, 1, 2], ordered=ordered)
+        assert cat.ordered == bool(ordered)
+
+    def test_constructor_imaginary(self):
+        values = [1, 2, 3 + 1j]
+        c1 = Categorical(values)
+        tm.assert_index_equal(c1.categories, Index(values))
+        tm.assert_numpy_array_equal(np.array(c1), np.array(values))
+
+    def test_constructor_string_and_tuples(self):
+        # GH 21416
+        c = Categorical(np.array(["c", ("a", "b"), ("b", "a"), "c"], dtype=object))
+        expected_index = Index([("a", "b"), ("b", "a"), "c"])
+        assert c.categories.equals(expected_index)
+
+    def test_interval(self):
+        idx = pd.interval_range(0, 10, periods=10)
+        cat = Categorical(idx, categories=idx)
+        expected_codes = np.arange(10, dtype="int8")
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+        # infer categories
+        cat = Categorical(idx)
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+        # list values
+        cat = Categorical(list(idx))
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+        # list values, categories
+        cat = Categorical(list(idx), categories=list(idx))
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+        # shuffled
+        values = idx.take([1, 2, 0])
+        cat = Categorical(values, categories=idx)
+        tm.assert_numpy_array_equal(cat.codes, np.array([1, 2, 0], dtype="int8"))
+        tm.assert_index_equal(cat.categories, idx)
+
+        # extra
+        values = pd.interval_range(8, 11, periods=3)
+        cat = Categorical(values, categories=idx)
+        expected_codes = np.array([8, 9, -1], dtype="int8")
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+        # overlapping
+        idx = IntervalIndex([Interval(0, 2), Interval(0, 1)])
+        cat = Categorical(idx, categories=idx)
+        expected_codes = np.array([0, 1], dtype="int8")
+        tm.assert_numpy_array_equal(cat.codes, expected_codes)
+        tm.assert_index_equal(cat.categories, idx)
+
+    def test_categorical_extension_array_nullable(self, nulls_fixture):
+        # GH:
+        arr = pd.arrays.StringArray._from_sequence(
+            [nulls_fixture] * 2, dtype=pd.StringDtype()
+        )
+        result = Categorical(arr)
+        assert arr.dtype == result.categories.dtype
+        expected = Categorical(Series([pd.NA, pd.NA], dtype=arr.dtype))
+        tm.assert_categorical_equal(result, expected)
+
+    def test_from_sequence_copy(self):
+        cat = Categorical(np.arange(5).repeat(2))
+        result = Categorical._from_sequence(cat, dtype=cat.dtype, copy=False)
+
+        # more generally, we'd be OK with a view
+        assert result._codes is cat._codes
+
+        result = Categorical._from_sequence(cat, dtype=cat.dtype, copy=True)
+
+        assert not tm.shares_memory(result, cat)
+
+    def test_constructor_datetime64_non_nano(self):
+        categories = np.arange(10).view("M8[D]")
+        values = categories[::2].copy()
+
+        cat = Categorical(values, categories=categories)
+        assert (cat == values).all()
+
+    def test_constructor_preserves_freq(self):
+        # GH33830 freq retention in categorical
+        dti = date_range("2016-01-01", periods=5)
+
+        expected = dti.freq
+
+        cat = Categorical(dti)
+        result = cat.categories.freq
+
+        assert expected == result
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_dtypes.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_dtypes.py
new file mode 100644
index 0000000000000000000000000000000000000000..525663cad1745880bc5e683e7302afdc2c06a527
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_dtypes.py
@@ -0,0 +1,139 @@
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+from pandas import (
+    Categorical,
+    CategoricalIndex,
+    Index,
+    IntervalIndex,
+    Series,
+    Timestamp,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalDtypes:
+    def test_categories_match_up_to_permutation(self):
+        # test dtype comparisons between cats
+
+        c1 = Categorical(list("aabca"), categories=list("abc"), ordered=False)
+        c2 = Categorical(list("aabca"), categories=list("cab"), ordered=False)
+        c3 = Categorical(list("aabca"), categories=list("cab"), ordered=True)
+        assert c1._categories_match_up_to_permutation(c1)
+        assert c2._categories_match_up_to_permutation(c2)
+        assert c3._categories_match_up_to_permutation(c3)
+        assert c1._categories_match_up_to_permutation(c2)
+        assert not c1._categories_match_up_to_permutation(c3)
+        assert not c1._categories_match_up_to_permutation(Index(list("aabca")))
+        assert not c1._categories_match_up_to_permutation(c1.astype(object))
+        assert c1._categories_match_up_to_permutation(CategoricalIndex(c1))
+        assert c1._categories_match_up_to_permutation(
+            CategoricalIndex(c1, categories=list("cab"))
+        )
+        assert not c1._categories_match_up_to_permutation(
+            CategoricalIndex(c1, ordered=True)
+        )
+
+        # GH 16659
+        s1 = Series(c1)
+        s2 = Series(c2)
+        s3 = Series(c3)
+        assert c1._categories_match_up_to_permutation(s1)
+        assert c2._categories_match_up_to_permutation(s2)
+        assert c3._categories_match_up_to_permutation(s3)
+        assert c1._categories_match_up_to_permutation(s2)
+        assert not c1._categories_match_up_to_permutation(s3)
+        assert not c1._categories_match_up_to_permutation(s1.astype(object))
+
+    def test_set_dtype_same(self):
+        c = Categorical(["a", "b", "c"])
+        result = c._set_dtype(CategoricalDtype(["a", "b", "c"]))
+        tm.assert_categorical_equal(result, c)
+
+    def test_set_dtype_new_categories(self):
+        c = Categorical(["a", "b", "c"])
+        result = c._set_dtype(CategoricalDtype(list("abcd")))
+        tm.assert_numpy_array_equal(result.codes, c.codes)
+        tm.assert_index_equal(result.dtype.categories, Index(list("abcd")))
+
+    @pytest.mark.parametrize(
+        "values, categories, new_categories",
+        [
+            # No NaNs, same cats, same order
+            (["a", "b", "a"], ["a", "b"], ["a", "b"]),
+            # No NaNs, same cats, different order
+            (["a", "b", "a"], ["a", "b"], ["b", "a"]),
+            # Same, unsorted
+            (["b", "a", "a"], ["a", "b"], ["a", "b"]),
+            # No NaNs, same cats, different order
+            (["b", "a", "a"], ["a", "b"], ["b", "a"]),
+            # NaNs
+            (["a", "b", "c"], ["a", "b"], ["a", "b"]),
+            (["a", "b", "c"], ["a", "b"], ["b", "a"]),
+            (["b", "a", "c"], ["a", "b"], ["a", "b"]),
+            (["b", "a", "c"], ["a", "b"], ["a", "b"]),
+            # Introduce NaNs
+            (["a", "b", "c"], ["a", "b"], ["a"]),
+            (["a", "b", "c"], ["a", "b"], ["b"]),
+            (["b", "a", "c"], ["a", "b"], ["a"]),
+            (["b", "a", "c"], ["a", "b"], ["a"]),
+            # No overlap
+            (["a", "b", "c"], ["a", "b"], ["d", "e"]),
+        ],
+    )
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_set_dtype_many(self, values, categories, new_categories, ordered):
+        c = Categorical(values, categories)
+        expected = Categorical(values, new_categories, ordered)
+        result = c._set_dtype(expected.dtype)
+        tm.assert_categorical_equal(result, expected)
+
+    def test_set_dtype_no_overlap(self):
+        c = Categorical(["a", "b", "c"], ["d", "e"])
+        result = c._set_dtype(CategoricalDtype(["a", "b"]))
+        expected = Categorical([None, None, None], categories=["a", "b"])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_codes_dtypes(self):
+        # GH 8453
+        result = Categorical(["foo", "bar", "baz"])
+        assert result.codes.dtype == "int8"
+
+        result = Categorical([f"foo{i:05d}" for i in range(400)])
+        assert result.codes.dtype == "int16"
+
+        result = Categorical([f"foo{i:05d}" for i in range(40000)])
+        assert result.codes.dtype == "int32"
+
+        # adding cats
+        result = Categorical(["foo", "bar", "baz"])
+        assert result.codes.dtype == "int8"
+        result = result.add_categories([f"foo{i:05d}" for i in range(400)])
+        assert result.codes.dtype == "int16"
+
+        # removing cats
+        result = result.remove_categories([f"foo{i:05d}" for i in range(300)])
+        assert result.codes.dtype == "int8"
+
+    def test_iter_python_types(self):
+        # GH-19909
+        cat = Categorical([1, 2])
+        assert isinstance(next(iter(cat)), int)
+        assert isinstance(cat.tolist()[0], int)
+
+    def test_iter_python_types_datetime(self):
+        cat = Categorical([Timestamp("2017-01-01"), Timestamp("2017-01-02")])
+        assert isinstance(next(iter(cat)), Timestamp)
+        assert isinstance(cat.tolist()[0], Timestamp)
+
+    def test_interval_index_category(self):
+        # GH 38316
+        index = IntervalIndex.from_breaks(np.arange(3, dtype="uint64"))
+
+        result = CategoricalIndex(index).dtype.categories
+        expected = IntervalIndex.from_arrays(
+            [0, 1], [1, 2], dtype="interval[uint64, right]"
+        )
+        tm.assert_index_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_indexing.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..5e1c5c64fa660f501d2b9d77c9181f47e013267f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_indexing.py
@@ -0,0 +1,388 @@
+import math
+
+import numpy as np
+import pytest
+
+from pandas import (
+    NA,
+    Categorical,
+    CategoricalIndex,
+    Index,
+    Interval,
+    IntervalIndex,
+    NaT,
+    PeriodIndex,
+    Series,
+    Timedelta,
+    Timestamp,
+)
+import pandas._testing as tm
+import pandas.core.common as com
+
+
+class TestCategoricalIndexingWithFactor:
+    def test_getitem(self):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        assert factor[0] == "a"
+        assert factor[-1] == "c"
+
+        subf = factor[[0, 1, 2]]
+        tm.assert_numpy_array_equal(subf._codes, np.array([0, 1, 1], dtype=np.int8))
+
+        subf = factor[np.asarray(factor) == "c"]
+        tm.assert_numpy_array_equal(subf._codes, np.array([2, 2, 2], dtype=np.int8))
+
+    def test_setitem(self):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        # int/positional
+        c = factor.copy()
+        c[0] = "b"
+        assert c[0] == "b"
+        c[-1] = "a"
+        assert c[-1] == "a"
+
+        # boolean
+        c = factor.copy()
+        indexer = np.zeros(len(c), dtype="bool")
+        indexer[0] = True
+        indexer[-1] = True
+        c[indexer] = "c"
+        expected = Categorical(["c", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+
+        tm.assert_categorical_equal(c, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [Categorical(["b", "a"]), Categorical(["b", "a"], categories=["b", "a"])],
+    )
+    def test_setitem_same_but_unordered(self, other):
+        # GH-24142
+        target = Categorical(["a", "b"], categories=["a", "b"])
+        mask = np.array([True, False])
+        target[mask] = other[mask]
+        expected = Categorical(["b", "b"], categories=["a", "b"])
+        tm.assert_categorical_equal(target, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            Categorical(["b", "a"], categories=["b", "a", "c"]),
+            Categorical(["b", "a"], categories=["a", "b", "c"]),
+            Categorical(["a", "a"], categories=["a"]),
+            Categorical(["b", "b"], categories=["b"]),
+        ],
+    )
+    def test_setitem_different_unordered_raises(self, other):
+        # GH-24142
+        target = Categorical(["a", "b"], categories=["a", "b"])
+        mask = np.array([True, False])
+        msg = "Cannot set a Categorical with another, without identical categories"
+        with pytest.raises(TypeError, match=msg):
+            target[mask] = other[mask]
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            Categorical(["b", "a"]),
+            Categorical(["b", "a"], categories=["b", "a"], ordered=True),
+            Categorical(["b", "a"], categories=["a", "b", "c"], ordered=True),
+        ],
+    )
+    def test_setitem_same_ordered_raises(self, other):
+        # Gh-24142
+        target = Categorical(["a", "b"], categories=["a", "b"], ordered=True)
+        mask = np.array([True, False])
+        msg = "Cannot set a Categorical with another, without identical categories"
+        with pytest.raises(TypeError, match=msg):
+            target[mask] = other[mask]
+
+    def test_setitem_tuple(self):
+        # GH#20439
+        cat = Categorical([(0, 1), (0, 2), (0, 1)])
+
+        # This should not raise
+        cat[1] = cat[0]
+        assert cat[1] == (0, 1)
+
+    def test_setitem_listlike(self):
+        # GH#9469
+        # properly coerce the input indexers
+
+        cat = Categorical(
+            np.random.default_rng(2).integers(0, 5, size=150000).astype(np.int8)
+        ).add_categories([-1000])
+        indexer = np.array([100000]).astype(np.int64)
+        cat[indexer] = -1000
+
+        # we are asserting the code result here
+        # which maps to the -1000 category
+        result = cat.codes[np.array([100000]).astype(np.int64)]
+        tm.assert_numpy_array_equal(result, np.array([5], dtype="int8"))
+
+
+class TestCategoricalIndexing:
+    def test_getitem_slice(self):
+        cat = Categorical(["a", "b", "c", "d", "a", "b", "c"])
+        sliced = cat[3]
+        assert sliced == "d"
+
+        sliced = cat[3:5]
+        expected = Categorical(["d", "a"], categories=["a", "b", "c", "d"])
+        tm.assert_categorical_equal(sliced, expected)
+
+    def test_getitem_listlike(self):
+        # GH 9469
+        # properly coerce the input indexers
+
+        c = Categorical(
+            np.random.default_rng(2).integers(0, 5, size=150000).astype(np.int8)
+        )
+        result = c.codes[np.array([100000]).astype(np.int64)]
+        expected = c[np.array([100000]).astype(np.int64)].codes
+        tm.assert_numpy_array_equal(result, expected)
+
+    def test_periodindex(self):
+        idx1 = PeriodIndex(
+            ["2014-01", "2014-01", "2014-02", "2014-02", "2014-03", "2014-03"],
+            freq="M",
+        )
+
+        cat1 = Categorical(idx1)
+        str(cat1)
+        exp_arr = np.array([0, 0, 1, 1, 2, 2], dtype=np.int8)
+        exp_idx = PeriodIndex(["2014-01", "2014-02", "2014-03"], freq="M")
+        tm.assert_numpy_array_equal(cat1._codes, exp_arr)
+        tm.assert_index_equal(cat1.categories, exp_idx)
+
+        idx2 = PeriodIndex(
+            ["2014-03", "2014-03", "2014-02", "2014-01", "2014-03", "2014-01"],
+            freq="M",
+        )
+        cat2 = Categorical(idx2, ordered=True)
+        str(cat2)
+        exp_arr = np.array([2, 2, 1, 0, 2, 0], dtype=np.int8)
+        exp_idx2 = PeriodIndex(["2014-01", "2014-02", "2014-03"], freq="M")
+        tm.assert_numpy_array_equal(cat2._codes, exp_arr)
+        tm.assert_index_equal(cat2.categories, exp_idx2)
+
+        idx3 = PeriodIndex(
+            [
+                "2013-12",
+                "2013-11",
+                "2013-10",
+                "2013-09",
+                "2013-08",
+                "2013-07",
+                "2013-05",
+            ],
+            freq="M",
+        )
+        cat3 = Categorical(idx3, ordered=True)
+        exp_arr = np.array([6, 5, 4, 3, 2, 1, 0], dtype=np.int8)
+        exp_idx = PeriodIndex(
+            [
+                "2013-05",
+                "2013-07",
+                "2013-08",
+                "2013-09",
+                "2013-10",
+                "2013-11",
+                "2013-12",
+            ],
+            freq="M",
+        )
+        tm.assert_numpy_array_equal(cat3._codes, exp_arr)
+        tm.assert_index_equal(cat3.categories, exp_idx)
+
+    @pytest.mark.parametrize(
+        "null_val",
+        [None, np.nan, NaT, NA, math.nan, "NaT", "nat", "NAT", "nan", "NaN", "NAN"],
+    )
+    def test_periodindex_on_null_types(self, null_val):
+        # GH 46673
+        result = PeriodIndex(["2022-04-06", "2022-04-07", null_val], freq="D")
+        expected = PeriodIndex(["2022-04-06", "2022-04-07", "NaT"], dtype="period[D]")
+        assert result[2] is NaT
+        tm.assert_index_equal(result, expected)
+
+    @pytest.mark.parametrize("new_categories", [[1, 2, 3, 4], [1, 2]])
+    def test_categories_assignments_wrong_length_raises(self, new_categories):
+        cat = Categorical(["a", "b", "c", "a"])
+        msg = (
+            "new categories need to have the same number of items "
+            "as the old categories!"
+        )
+        with pytest.raises(ValueError, match=msg):
+            cat.rename_categories(new_categories)
+
+    # Combinations of sorted/unique:
+    @pytest.mark.parametrize(
+        "idx_values", [[1, 2, 3, 4], [1, 3, 2, 4], [1, 3, 3, 4], [1, 2, 2, 4]]
+    )
+    # Combinations of missing/unique
+    @pytest.mark.parametrize("key_values", [[1, 2], [1, 5], [1, 1], [5, 5]])
+    @pytest.mark.parametrize("key_class", [Categorical, CategoricalIndex])
+    @pytest.mark.parametrize("dtype", [None, "category", "key"])
+    def test_get_indexer_non_unique(self, idx_values, key_values, key_class, dtype):
+        # GH 21448
+        key = key_class(key_values, categories=range(1, 5))
+
+        if dtype == "key":
+            dtype = key.dtype
+
+        # Test for flat index and CategoricalIndex with same/different cats:
+        idx = Index(idx_values, dtype=dtype)
+        expected, exp_miss = idx.get_indexer_non_unique(key_values)
+        result, res_miss = idx.get_indexer_non_unique(key)
+
+        tm.assert_numpy_array_equal(expected, result)
+        tm.assert_numpy_array_equal(exp_miss, res_miss)
+
+        exp_unique = idx.unique().get_indexer(key_values)
+        res_unique = idx.unique().get_indexer(key)
+        tm.assert_numpy_array_equal(res_unique, exp_unique)
+
+    def test_where_unobserved_nan(self):
+        ser = Series(Categorical(["a", "b"]))
+        result = ser.where([True, False])
+        expected = Series(Categorical(["a", None], categories=["a", "b"]))
+        tm.assert_series_equal(result, expected)
+
+        # all NA
+        ser = Series(Categorical(["a", "b"]))
+        result = ser.where([False, False])
+        expected = Series(Categorical([None, None], categories=["a", "b"]))
+        tm.assert_series_equal(result, expected)
+
+    def test_where_unobserved_categories(self):
+        ser = Series(Categorical(["a", "b", "c"], categories=["d", "c", "b", "a"]))
+        result = ser.where([True, True, False], other="b")
+        expected = Series(Categorical(["a", "b", "b"], categories=ser.cat.categories))
+        tm.assert_series_equal(result, expected)
+
+    def test_where_other_categorical(self):
+        ser = Series(Categorical(["a", "b", "c"], categories=["d", "c", "b", "a"]))
+        other = Categorical(["b", "c", "a"], categories=["a", "c", "b", "d"])
+        result = ser.where([True, False, True], other)
+        expected = Series(Categorical(["a", "c", "c"], dtype=ser.dtype))
+        tm.assert_series_equal(result, expected)
+
+    def test_where_new_category_raises(self):
+        ser = Series(Categorical(["a", "b", "c"]))
+        msg = "Cannot setitem on a Categorical with a new category"
+        with pytest.raises(TypeError, match=msg):
+            ser.where([True, False, True], "d")
+
+    def test_where_ordered_differs_rasies(self):
+        ser = Series(
+            Categorical(["a", "b", "c"], categories=["d", "c", "b", "a"], ordered=True)
+        )
+        other = Categorical(
+            ["b", "c", "a"], categories=["a", "c", "b", "d"], ordered=True
+        )
+        with pytest.raises(TypeError, match="without identical categories"):
+            ser.where([True, False, True], other)
+
+
+class TestContains:
+    def test_contains(self):
+        # GH#21508
+        cat = Categorical(list("aabbca"), categories=list("cab"))
+
+        assert "b" in cat
+        assert "z" not in cat
+        assert np.nan not in cat
+        with pytest.raises(TypeError, match="unhashable type: 'list'"):
+            assert [1] in cat
+
+        # assert codes NOT in index
+        assert 0 not in cat
+        assert 1 not in cat
+
+        cat = Categorical(list("aabbca") + [np.nan], categories=list("cab"))
+        assert np.nan in cat
+
+    @pytest.mark.parametrize(
+        "item, expected",
+        [
+            (Interval(0, 1), True),
+            (1.5, True),
+            (Interval(0.5, 1.5), False),
+            ("a", False),
+            (Timestamp(1), False),
+            (Timedelta(1), False),
+        ],
+        ids=str,
+    )
+    def test_contains_interval(self, item, expected):
+        # GH#23705
+        cat = Categorical(IntervalIndex.from_breaks(range(3)))
+        result = item in cat
+        assert result is expected
+
+    def test_contains_list(self):
+        # GH#21729
+        cat = Categorical([1, 2, 3])
+
+        assert "a" not in cat
+
+        with pytest.raises(TypeError, match="unhashable type"):
+            ["a"] in cat
+
+        with pytest.raises(TypeError, match="unhashable type"):
+            ["a", "b"] in cat
+
+
+@pytest.mark.parametrize("index", [True, False])
+def test_mask_with_boolean(index):
+    ser = Series(range(3))
+    idx = Categorical([True, False, True])
+    if index:
+        idx = CategoricalIndex(idx)
+
+    assert com.is_bool_indexer(idx)
+    result = ser[idx]
+    expected = ser[idx.astype("object")]
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("index", [True, False])
+def test_mask_with_boolean_na_treated_as_false(index):
+    # https://github.com/pandas-dev/pandas/issues/31503
+    ser = Series(range(3))
+    idx = Categorical([True, False, None])
+    if index:
+        idx = CategoricalIndex(idx)
+
+    result = ser[idx]
+    expected = ser[idx.fillna(False)]
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.fixture
+def non_coercible_categorical(monkeypatch):
+    """
+    Monkeypatch Categorical.__array__ to ensure no implicit conversion.
+
+    Raises
+    ------
+    ValueError
+        When Categorical.__array__ is called.
+    """
+
+    # TODO(Categorical): identify other places where this may be
+    # useful and move to a conftest.py
+    def array(self, dtype=None):
+        raise ValueError("I cannot be converted.")
+
+    with monkeypatch.context() as m:
+        m.setattr(Categorical, "__array__", array)
+        yield
+
+
+def test_series_at():
+    arr = Categorical(["a", "b", "c"])
+    ser = Series(arr)
+    result = ser.at[0]
+    assert result == "a"
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_map.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_map.py
new file mode 100644
index 0000000000000000000000000000000000000000..3d41b7cc7094d237fa8d31501ce90a99b04fe4e6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_map.py
@@ -0,0 +1,154 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    Index,
+    Series,
+)
+import pandas._testing as tm
+
+
+@pytest.fixture(params=[None, "ignore"])
+def na_action(request):
+    return request.param
+
+
+@pytest.mark.parametrize(
+    "data, categories",
+    [
+        (list("abcbca"), list("cab")),
+        (pd.interval_range(0, 3).repeat(3), pd.interval_range(0, 3)),
+    ],
+    ids=["string", "interval"],
+)
+def test_map_str(data, categories, ordered, na_action):
+    # GH 31202 - override base class since we want to maintain categorical/ordered
+    cat = Categorical(data, categories=categories, ordered=ordered)
+    result = cat.map(str, na_action=na_action)
+    expected = Categorical(
+        map(str, data), categories=map(str, categories), ordered=ordered
+    )
+    tm.assert_categorical_equal(result, expected)
+
+
+def test_map(na_action):
+    cat = Categorical(list("ABABC"), categories=list("CBA"), ordered=True)
+    result = cat.map(lambda x: x.lower(), na_action=na_action)
+    exp = Categorical(list("ababc"), categories=list("cba"), ordered=True)
+    tm.assert_categorical_equal(result, exp)
+
+    cat = Categorical(list("ABABC"), categories=list("BAC"), ordered=False)
+    result = cat.map(lambda x: x.lower(), na_action=na_action)
+    exp = Categorical(list("ababc"), categories=list("bac"), ordered=False)
+    tm.assert_categorical_equal(result, exp)
+
+    # GH 12766: Return an index not an array
+    result = cat.map(lambda x: 1, na_action=na_action)
+    exp = Index(np.array([1] * 5, dtype=np.int64))
+    tm.assert_index_equal(result, exp)
+
+    # change categories dtype
+    cat = Categorical(list("ABABC"), categories=list("BAC"), ordered=False)
+
+    def f(x):
+        return {"A": 10, "B": 20, "C": 30}.get(x)
+
+    result = cat.map(f, na_action=na_action)
+    exp = Categorical([10, 20, 10, 20, 30], categories=[20, 10, 30], ordered=False)
+    tm.assert_categorical_equal(result, exp)
+
+    mapper = Series([10, 20, 30], index=["A", "B", "C"])
+    result = cat.map(mapper, na_action=na_action)
+    tm.assert_categorical_equal(result, exp)
+
+    result = cat.map({"A": 10, "B": 20, "C": 30}, na_action=na_action)
+    tm.assert_categorical_equal(result, exp)
+
+
+@pytest.mark.parametrize(
+    ("data", "f", "expected"),
+    (
+        ([1, 1, np.nan], pd.isna, Index([False, False, True])),
+        ([1, 2, np.nan], pd.isna, Index([False, False, True])),
+        ([1, 1, np.nan], {1: False}, Categorical([False, False, np.nan])),
+        ([1, 2, np.nan], {1: False, 2: False}, Index([False, False, np.nan])),
+        (
+            [1, 1, np.nan],
+            Series([False, False]),
+            Categorical([False, False, np.nan]),
+        ),
+        (
+            [1, 2, np.nan],
+            Series([False] * 3),
+            Index([False, False, np.nan]),
+        ),
+    ),
+)
+def test_map_with_nan_none(data, f, expected):  # GH 24241
+    values = Categorical(data)
+    result = values.map(f, na_action=None)
+    if isinstance(expected, Categorical):
+        tm.assert_categorical_equal(result, expected)
+    else:
+        tm.assert_index_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    ("data", "f", "expected"),
+    (
+        ([1, 1, np.nan], pd.isna, Categorical([False, False, np.nan])),
+        ([1, 2, np.nan], pd.isna, Index([False, False, np.nan])),
+        ([1, 1, np.nan], {1: False}, Categorical([False, False, np.nan])),
+        ([1, 2, np.nan], {1: False, 2: False}, Index([False, False, np.nan])),
+        (
+            [1, 1, np.nan],
+            Series([False, False]),
+            Categorical([False, False, np.nan]),
+        ),
+        (
+            [1, 2, np.nan],
+            Series([False, False, False]),
+            Index([False, False, np.nan]),
+        ),
+    ),
+)
+def test_map_with_nan_ignore(data, f, expected):  # GH 24241
+    values = Categorical(data)
+    result = values.map(f, na_action="ignore")
+    if data[1] == 1:
+        tm.assert_categorical_equal(result, expected)
+    else:
+        tm.assert_index_equal(result, expected)
+
+
+def test_map_with_dict_or_series(na_action):
+    orig_values = ["a", "B", 1, "a"]
+    new_values = ["one", 2, 3.0, "one"]
+    cat = Categorical(orig_values)
+
+    mapper = Series(new_values[:-1], index=orig_values[:-1])
+    result = cat.map(mapper, na_action=na_action)
+
+    # Order of categories in result can be different
+    expected = Categorical(new_values, categories=[3.0, 2, "one"])
+    tm.assert_categorical_equal(result, expected)
+
+    mapper = dict(zip(orig_values[:-1], new_values[:-1]))
+    result = cat.map(mapper, na_action=na_action)
+    # Order of categories in result can be different
+    tm.assert_categorical_equal(result, expected)
+
+
+def test_map_na_action_no_default_deprecated():
+    # GH51645
+    cat = Categorical(["a", "b", "c"])
+    msg = (
+        "The default value of 'ignore' for the `na_action` parameter in "
+        "pandas.Categorical.map is deprecated and will be "
+        "changed to 'None' in a future version. Please set na_action to the "
+        "desired value to avoid seeing this warning"
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        cat.map(lambda x: x)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_missing.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_missing.py
new file mode 100644
index 0000000000000000000000000000000000000000..0eeb01b74608890daf81fef083adb29e797e57ce
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_missing.py
@@ -0,0 +1,216 @@
+import collections
+
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.dtypes import CategoricalDtype
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    DataFrame,
+    Index,
+    Series,
+    isna,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalMissing:
+    def test_isna(self):
+        exp = np.array([False, False, True])
+        cat = Categorical(["a", "b", np.nan])
+        res = cat.isna()
+
+        tm.assert_numpy_array_equal(res, exp)
+
+    def test_na_flags_int_categories(self):
+        # #1457
+
+        categories = list(range(10))
+        labels = np.random.default_rng(2).integers(0, 10, 20)
+        labels[::5] = -1
+
+        cat = Categorical(labels, categories)
+        repr(cat)
+
+        tm.assert_numpy_array_equal(isna(cat), labels == -1)
+
+    def test_nan_handling(self):
+        # Nans are represented as -1 in codes
+        c = Categorical(["a", "b", np.nan, "a"])
+        tm.assert_index_equal(c.categories, Index(["a", "b"]))
+        tm.assert_numpy_array_equal(c._codes, np.array([0, 1, -1, 0], dtype=np.int8))
+        c[1] = np.nan
+        tm.assert_index_equal(c.categories, Index(["a", "b"]))
+        tm.assert_numpy_array_equal(c._codes, np.array([0, -1, -1, 0], dtype=np.int8))
+
+        # Adding nan to categories should make assigned nan point to the
+        # category!
+        c = Categorical(["a", "b", np.nan, "a"])
+        tm.assert_index_equal(c.categories, Index(["a", "b"]))
+        tm.assert_numpy_array_equal(c._codes, np.array([0, 1, -1, 0], dtype=np.int8))
+
+    def test_set_dtype_nans(self):
+        c = Categorical(["a", "b", np.nan])
+        result = c._set_dtype(CategoricalDtype(["a", "c"]))
+        tm.assert_numpy_array_equal(result.codes, np.array([0, -1, -1], dtype="int8"))
+
+    def test_set_item_nan(self):
+        cat = Categorical([1, 2, 3])
+        cat[1] = np.nan
+
+        exp = Categorical([1, np.nan, 3], categories=[1, 2, 3])
+        tm.assert_categorical_equal(cat, exp)
+
+    @pytest.mark.parametrize(
+        "fillna_kwargs, msg",
+        [
+            (
+                {"value": 1, "method": "ffill"},
+                "Cannot specify both 'value' and 'method'.",
+            ),
+            ({}, "Must specify a fill 'value' or 'method'."),
+            ({"method": "bad"}, "Invalid fill method. Expecting .* bad"),
+            (
+                {"value": Series([1, 2, 3, 4, "a"])},
+                "Cannot setitem on a Categorical with a new category",
+            ),
+        ],
+    )
+    def test_fillna_raises(self, fillna_kwargs, msg):
+        # https://github.com/pandas-dev/pandas/issues/19682
+        # https://github.com/pandas-dev/pandas/issues/13628
+        cat = Categorical([1, 2, 3, None, None])
+
+        if len(fillna_kwargs) == 1 and "value" in fillna_kwargs:
+            err = TypeError
+        else:
+            err = ValueError
+
+        with pytest.raises(err, match=msg):
+            cat.fillna(**fillna_kwargs)
+
+    @pytest.mark.parametrize("named", [True, False])
+    def test_fillna_iterable_category(self, named):
+        # https://github.com/pandas-dev/pandas/issues/21097
+        if named:
+            Point = collections.namedtuple("Point", "x y")
+        else:
+            Point = lambda *args: args  # tuple
+        cat = Categorical(np.array([Point(0, 0), Point(0, 1), None], dtype=object))
+        result = cat.fillna(Point(0, 0))
+        expected = Categorical([Point(0, 0), Point(0, 1), Point(0, 0)])
+
+        tm.assert_categorical_equal(result, expected)
+
+        # Case where the Point is not among our categories; we want ValueError,
+        #  not NotImplementedError GH#41914
+        cat = Categorical(np.array([Point(1, 0), Point(0, 1), None], dtype=object))
+        msg = "Cannot setitem on a Categorical with a new category"
+        with pytest.raises(TypeError, match=msg):
+            cat.fillna(Point(0, 0))
+
+    def test_fillna_array(self):
+        # accept Categorical or ndarray value if it holds appropriate values
+        cat = Categorical(["A", "B", "C", None, None])
+
+        other = cat.fillna("C")
+        result = cat.fillna(other)
+        tm.assert_categorical_equal(result, other)
+        assert isna(cat[-1])  # didn't modify original inplace
+
+        other = np.array(["A", "B", "C", "B", "A"])
+        result = cat.fillna(other)
+        expected = Categorical(["A", "B", "C", "B", "A"], dtype=cat.dtype)
+        tm.assert_categorical_equal(result, expected)
+        assert isna(cat[-1])  # didn't modify original inplace
+
+    @pytest.mark.parametrize(
+        "values, expected",
+        [
+            ([1, 2, 3], np.array([False, False, False])),
+            ([1, 2, np.nan], np.array([False, False, True])),
+            ([1, 2, np.inf], np.array([False, False, True])),
+            ([1, 2, pd.NA], np.array([False, False, True])),
+        ],
+    )
+    def test_use_inf_as_na(self, values, expected):
+        # https://github.com/pandas-dev/pandas/issues/33594
+        msg = "use_inf_as_na option is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            with pd.option_context("mode.use_inf_as_na", True):
+                cat = Categorical(values)
+                result = cat.isna()
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = Series(cat).isna()
+                expected = Series(expected)
+                tm.assert_series_equal(result, expected)
+
+                result = DataFrame(cat).isna()
+                expected = DataFrame(expected)
+                tm.assert_frame_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "values, expected",
+        [
+            ([1, 2, 3], np.array([False, False, False])),
+            ([1, 2, np.nan], np.array([False, False, True])),
+            ([1, 2, np.inf], np.array([False, False, True])),
+            ([1, 2, pd.NA], np.array([False, False, True])),
+        ],
+    )
+    def test_use_inf_as_na_outside_context(self, values, expected):
+        # https://github.com/pandas-dev/pandas/issues/33594
+        # Using isna directly for Categorical will fail in general here
+        cat = Categorical(values)
+
+        msg = "use_inf_as_na option is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=msg):
+            with pd.option_context("mode.use_inf_as_na", True):
+                result = isna(cat)
+                tm.assert_numpy_array_equal(result, expected)
+
+                result = isna(Series(cat))
+                expected = Series(expected)
+                tm.assert_series_equal(result, expected)
+
+                result = isna(DataFrame(cat))
+                expected = DataFrame(expected)
+                tm.assert_frame_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "a1, a2, categories",
+        [
+            (["a", "b", "c"], [np.nan, "a", "b"], ["a", "b", "c"]),
+            ([1, 2, 3], [np.nan, 1, 2], [1, 2, 3]),
+        ],
+    )
+    def test_compare_categorical_with_missing(self, a1, a2, categories):
+        # GH 28384
+        cat_type = CategoricalDtype(categories)
+
+        # !=
+        result = Series(a1, dtype=cat_type) != Series(a2, dtype=cat_type)
+        expected = Series(a1) != Series(a2)
+        tm.assert_series_equal(result, expected)
+
+        # ==
+        result = Series(a1, dtype=cat_type) == Series(a2, dtype=cat_type)
+        expected = Series(a1) == Series(a2)
+        tm.assert_series_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "na_value, dtype",
+        [
+            (pd.NaT, "datetime64[ns]"),
+            (None, "float64"),
+            (np.nan, "float64"),
+            (pd.NA, "float64"),
+        ],
+    )
+    def test_categorical_only_missing_values_no_cast(self, na_value, dtype):
+        # GH#44900
+        result = Categorical([na_value, na_value])
+        tm.assert_index_equal(result.categories, Index([], dtype=dtype))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_operators.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_operators.py
new file mode 100644
index 0000000000000000000000000000000000000000..4174d2adc810b872e7ec0b1e3ca820e3d2c3920d
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_operators.py
@@ -0,0 +1,414 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    Categorical,
+    DataFrame,
+    Series,
+    Timestamp,
+    date_range,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalOpsWithFactor:
+    def test_categories_none_comparisons(self):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        tm.assert_categorical_equal(factor, factor)
+
+    def test_comparisons(self):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        result = factor[factor == "a"]
+        expected = factor[np.asarray(factor) == "a"]
+        tm.assert_categorical_equal(result, expected)
+
+        result = factor[factor != "a"]
+        expected = factor[np.asarray(factor) != "a"]
+        tm.assert_categorical_equal(result, expected)
+
+        result = factor[factor < "c"]
+        expected = factor[np.asarray(factor) < "c"]
+        tm.assert_categorical_equal(result, expected)
+
+        result = factor[factor > "a"]
+        expected = factor[np.asarray(factor) > "a"]
+        tm.assert_categorical_equal(result, expected)
+
+        result = factor[factor >= "b"]
+        expected = factor[np.asarray(factor) >= "b"]
+        tm.assert_categorical_equal(result, expected)
+
+        result = factor[factor <= "b"]
+        expected = factor[np.asarray(factor) <= "b"]
+        tm.assert_categorical_equal(result, expected)
+
+        n = len(factor)
+
+        other = factor[np.random.default_rng(2).permutation(n)]
+        result = factor == other
+        expected = np.asarray(factor) == np.asarray(other)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = factor == "d"
+        expected = np.zeros(len(factor), dtype=bool)
+        tm.assert_numpy_array_equal(result, expected)
+
+        # comparisons with categoricals
+        cat_rev = Categorical(["a", "b", "c"], categories=["c", "b", "a"], ordered=True)
+        cat_rev_base = Categorical(
+            ["b", "b", "b"], categories=["c", "b", "a"], ordered=True
+        )
+        cat = Categorical(["a", "b", "c"], ordered=True)
+        cat_base = Categorical(["b", "b", "b"], categories=cat.categories, ordered=True)
+
+        # comparisons need to take categories ordering into account
+        res_rev = cat_rev > cat_rev_base
+        exp_rev = np.array([True, False, False])
+        tm.assert_numpy_array_equal(res_rev, exp_rev)
+
+        res_rev = cat_rev < cat_rev_base
+        exp_rev = np.array([False, False, True])
+        tm.assert_numpy_array_equal(res_rev, exp_rev)
+
+        res = cat > cat_base
+        exp = np.array([False, False, True])
+        tm.assert_numpy_array_equal(res, exp)
+
+        # Only categories with same categories can be compared
+        msg = "Categoricals can only be compared if 'categories' are the same"
+        with pytest.raises(TypeError, match=msg):
+            cat > cat_rev
+
+        cat_rev_base2 = Categorical(["b", "b", "b"], categories=["c", "b", "a", "d"])
+
+        with pytest.raises(TypeError, match=msg):
+            cat_rev > cat_rev_base2
+
+        # Only categories with same ordering information can be compared
+        cat_unordered = cat.set_ordered(False)
+        assert not (cat > cat).any()
+
+        with pytest.raises(TypeError, match=msg):
+            cat > cat_unordered
+
+        # comparison (in both directions) with Series will raise
+        s = Series(["b", "b", "b"], dtype=object)
+        msg = (
+            "Cannot compare a Categorical for op __gt__ with type "
+            r""
+        )
+        with pytest.raises(TypeError, match=msg):
+            cat > s
+        with pytest.raises(TypeError, match=msg):
+            cat_rev > s
+        with pytest.raises(TypeError, match=msg):
+            s < cat
+        with pytest.raises(TypeError, match=msg):
+            s < cat_rev
+
+        # comparison with numpy.array will raise in both direction, but only on
+        # newer numpy versions
+        a = np.array(["b", "b", "b"], dtype=object)
+        with pytest.raises(TypeError, match=msg):
+            cat > a
+        with pytest.raises(TypeError, match=msg):
+            cat_rev > a
+
+        # Make sure that unequal comparison take the categories order in
+        # account
+        cat_rev = Categorical(list("abc"), categories=list("cba"), ordered=True)
+        exp = np.array([True, False, False])
+        res = cat_rev > "b"
+        tm.assert_numpy_array_equal(res, exp)
+
+        # check that zero-dim array gets unboxed
+        res = cat_rev > np.array("b")
+        tm.assert_numpy_array_equal(res, exp)
+
+
+class TestCategoricalOps:
+    @pytest.mark.parametrize(
+        "categories",
+        [["a", "b"], [0, 1], [Timestamp("2019"), Timestamp("2020")]],
+    )
+    def test_not_equal_with_na(self, categories):
+        # https://github.com/pandas-dev/pandas/issues/32276
+        c1 = Categorical.from_codes([-1, 0], categories=categories)
+        c2 = Categorical.from_codes([0, 1], categories=categories)
+
+        result = c1 != c2
+
+        assert result.all()
+
+    def test_compare_frame(self):
+        # GH#24282 check that Categorical.__cmp__(DataFrame) defers to frame
+        data = ["a", "b", 2, "a"]
+        cat = Categorical(data)
+
+        df = DataFrame(cat)
+
+        result = cat == df.T
+        expected = DataFrame([[True, True, True, True]])
+        tm.assert_frame_equal(result, expected)
+
+        result = cat[::-1] != df.T
+        expected = DataFrame([[False, True, True, False]])
+        tm.assert_frame_equal(result, expected)
+
+    def test_compare_frame_raises(self, comparison_op):
+        # alignment raises unless we transpose
+        op = comparison_op
+        cat = Categorical(["a", "b", 2, "a"])
+        df = DataFrame(cat)
+        msg = "Unable to coerce to Series, length must be 1: given 4"
+        with pytest.raises(ValueError, match=msg):
+            op(cat, df)
+
+    def test_datetime_categorical_comparison(self):
+        dt_cat = Categorical(date_range("2014-01-01", periods=3), ordered=True)
+        tm.assert_numpy_array_equal(dt_cat > dt_cat[0], np.array([False, True, True]))
+        tm.assert_numpy_array_equal(dt_cat[0] < dt_cat, np.array([False, True, True]))
+
+    def test_reflected_comparison_with_scalars(self):
+        # GH8658
+        cat = Categorical([1, 2, 3], ordered=True)
+        tm.assert_numpy_array_equal(cat > cat[0], np.array([False, True, True]))
+        tm.assert_numpy_array_equal(cat[0] < cat, np.array([False, True, True]))
+
+    def test_comparison_with_unknown_scalars(self):
+        # https://github.com/pandas-dev/pandas/issues/9836#issuecomment-92123057
+        # and following comparisons with scalars not in categories should raise
+        # for unequal comps, but not for equal/not equal
+        cat = Categorical([1, 2, 3], ordered=True)
+
+        msg = "Invalid comparison between dtype=category and int"
+        with pytest.raises(TypeError, match=msg):
+            cat < 4
+        with pytest.raises(TypeError, match=msg):
+            cat > 4
+        with pytest.raises(TypeError, match=msg):
+            4 < cat
+        with pytest.raises(TypeError, match=msg):
+            4 > cat
+
+        tm.assert_numpy_array_equal(cat == 4, np.array([False, False, False]))
+        tm.assert_numpy_array_equal(cat != 4, np.array([True, True, True]))
+
+    def test_comparison_with_tuple(self):
+        cat = Categorical(np.array(["foo", (0, 1), 3, (0, 1)], dtype=object))
+
+        result = cat == "foo"
+        expected = np.array([True, False, False, False], dtype=bool)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = cat == (0, 1)
+        expected = np.array([False, True, False, True], dtype=bool)
+        tm.assert_numpy_array_equal(result, expected)
+
+        result = cat != (0, 1)
+        tm.assert_numpy_array_equal(result, ~expected)
+
+    @pytest.mark.filterwarnings("ignore::RuntimeWarning")
+    def test_comparison_of_ordered_categorical_with_nan_to_scalar(
+        self, compare_operators_no_eq_ne
+    ):
+        # https://github.com/pandas-dev/pandas/issues/26504
+        # BUG: fix ordered categorical comparison with missing values (#26504 )
+        # and following comparisons with scalars in categories with missing
+        # values should be evaluated as False
+
+        cat = Categorical([1, 2, 3, None], categories=[1, 2, 3], ordered=True)
+        scalar = 2
+        expected = getattr(np.array(cat), compare_operators_no_eq_ne)(scalar)
+        actual = getattr(cat, compare_operators_no_eq_ne)(scalar)
+        tm.assert_numpy_array_equal(actual, expected)
+
+    @pytest.mark.filterwarnings("ignore::RuntimeWarning")
+    def test_comparison_of_ordered_categorical_with_nan_to_listlike(
+        self, compare_operators_no_eq_ne
+    ):
+        # https://github.com/pandas-dev/pandas/issues/26504
+        # and following comparisons of missing values in ordered Categorical
+        # with listlike should be evaluated as False
+
+        cat = Categorical([1, 2, 3, None], categories=[1, 2, 3], ordered=True)
+        other = Categorical([2, 2, 2, 2], categories=[1, 2, 3], ordered=True)
+        expected = getattr(np.array(cat), compare_operators_no_eq_ne)(2)
+        actual = getattr(cat, compare_operators_no_eq_ne)(other)
+        tm.assert_numpy_array_equal(actual, expected)
+
+    @pytest.mark.parametrize(
+        "data,reverse,base",
+        [(list("abc"), list("cba"), list("bbb")), ([1, 2, 3], [3, 2, 1], [2, 2, 2])],
+    )
+    def test_comparisons(self, data, reverse, base):
+        cat_rev = Series(Categorical(data, categories=reverse, ordered=True))
+        cat_rev_base = Series(Categorical(base, categories=reverse, ordered=True))
+        cat = Series(Categorical(data, ordered=True))
+        cat_base = Series(
+            Categorical(base, categories=cat.cat.categories, ordered=True)
+        )
+        s = Series(base, dtype=object if base == list("bbb") else None)
+        a = np.array(base)
+
+        # comparisons need to take categories ordering into account
+        res_rev = cat_rev > cat_rev_base
+        exp_rev = Series([True, False, False])
+        tm.assert_series_equal(res_rev, exp_rev)
+
+        res_rev = cat_rev < cat_rev_base
+        exp_rev = Series([False, False, True])
+        tm.assert_series_equal(res_rev, exp_rev)
+
+        res = cat > cat_base
+        exp = Series([False, False, True])
+        tm.assert_series_equal(res, exp)
+
+        scalar = base[1]
+        res = cat > scalar
+        exp = Series([False, False, True])
+        exp2 = cat.values > scalar
+        tm.assert_series_equal(res, exp)
+        tm.assert_numpy_array_equal(res.values, exp2)
+        res_rev = cat_rev > scalar
+        exp_rev = Series([True, False, False])
+        exp_rev2 = cat_rev.values > scalar
+        tm.assert_series_equal(res_rev, exp_rev)
+        tm.assert_numpy_array_equal(res_rev.values, exp_rev2)
+
+        # Only categories with same categories can be compared
+        msg = "Categoricals can only be compared if 'categories' are the same"
+        with pytest.raises(TypeError, match=msg):
+            cat > cat_rev
+
+        # categorical cannot be compared to Series or numpy array, and also
+        # not the other way around
+        msg = (
+            "Cannot compare a Categorical for op __gt__ with type "
+            r""
+        )
+        with pytest.raises(TypeError, match=msg):
+            cat > s
+        with pytest.raises(TypeError, match=msg):
+            cat_rev > s
+        with pytest.raises(TypeError, match=msg):
+            cat > a
+        with pytest.raises(TypeError, match=msg):
+            cat_rev > a
+
+        with pytest.raises(TypeError, match=msg):
+            s < cat
+        with pytest.raises(TypeError, match=msg):
+            s < cat_rev
+
+        with pytest.raises(TypeError, match=msg):
+            a < cat
+        with pytest.raises(TypeError, match=msg):
+            a < cat_rev
+
+    @pytest.mark.parametrize(
+        "ctor",
+        [
+            lambda *args, **kwargs: Categorical(*args, **kwargs),
+            lambda *args, **kwargs: Series(Categorical(*args, **kwargs)),
+        ],
+    )
+    def test_unordered_different_order_equal(self, ctor):
+        # https://github.com/pandas-dev/pandas/issues/16014
+        c1 = ctor(["a", "b"], categories=["a", "b"], ordered=False)
+        c2 = ctor(["a", "b"], categories=["b", "a"], ordered=False)
+        assert (c1 == c2).all()
+
+        c1 = ctor(["a", "b"], categories=["a", "b"], ordered=False)
+        c2 = ctor(["b", "a"], categories=["b", "a"], ordered=False)
+        assert (c1 != c2).all()
+
+        c1 = ctor(["a", "a"], categories=["a", "b"], ordered=False)
+        c2 = ctor(["b", "b"], categories=["b", "a"], ordered=False)
+        assert (c1 != c2).all()
+
+        c1 = ctor(["a", "a"], categories=["a", "b"], ordered=False)
+        c2 = ctor(["a", "b"], categories=["b", "a"], ordered=False)
+        result = c1 == c2
+        tm.assert_numpy_array_equal(np.array(result), np.array([True, False]))
+
+    def test_unordered_different_categories_raises(self):
+        c1 = Categorical(["a", "b"], categories=["a", "b"], ordered=False)
+        c2 = Categorical(["a", "c"], categories=["c", "a"], ordered=False)
+
+        with pytest.raises(TypeError, match=("Categoricals can only be compared")):
+            c1 == c2
+
+    def test_compare_different_lengths(self):
+        c1 = Categorical([], categories=["a", "b"])
+        c2 = Categorical([], categories=["a"])
+
+        msg = "Categoricals can only be compared if 'categories' are the same."
+        with pytest.raises(TypeError, match=msg):
+            c1 == c2
+
+    def test_compare_unordered_different_order(self):
+        # https://github.com/pandas-dev/pandas/issues/16603#issuecomment-
+        # 349290078
+        a = Categorical(["a"], categories=["a", "b"])
+        b = Categorical(["b"], categories=["b", "a"])
+        assert not a.equals(b)
+
+    def test_numeric_like_ops(self):
+        df = DataFrame({"value": np.random.default_rng(2).integers(0, 10000, 100)})
+        labels = [f"{i} - {i + 499}" for i in range(0, 10000, 500)]
+        cat_labels = Categorical(labels, labels)
+
+        df = df.sort_values(by=["value"], ascending=True)
+        df["value_group"] = pd.cut(
+            df.value, range(0, 10500, 500), right=False, labels=cat_labels
+        )
+
+        # numeric ops should not succeed
+        for op, str_rep in [
+            ("__add__", r"\+"),
+            ("__sub__", "-"),
+            ("__mul__", r"\*"),
+            ("__truediv__", "/"),
+        ]:
+            msg = f"Series cannot perform the operation {str_rep}|unsupported operand"
+            with pytest.raises(TypeError, match=msg):
+                getattr(df, op)(df)
+
+        # reduction ops should not succeed (unless specifically defined, e.g.
+        # min/max)
+        s = df["value_group"]
+        for op in ["kurt", "skew", "var", "std", "mean", "sum", "median"]:
+            msg = f"does not support reduction '{op}'"
+            with pytest.raises(TypeError, match=msg):
+                getattr(s, op)(numeric_only=False)
+
+    def test_numeric_like_ops_series(self):
+        # numpy ops
+        s = Series(Categorical([1, 2, 3, 4]))
+        with pytest.raises(TypeError, match="does not support reduction 'sum'"):
+            np.sum(s)
+
+    @pytest.mark.parametrize(
+        "op, str_rep",
+        [
+            ("__add__", r"\+"),
+            ("__sub__", "-"),
+            ("__mul__", r"\*"),
+            ("__truediv__", "/"),
+        ],
+    )
+    def test_numeric_like_ops_series_arith(self, op, str_rep):
+        # numeric ops on a Series
+        s = Series(Categorical([1, 2, 3, 4]))
+        msg = f"Series cannot perform the operation {str_rep}|unsupported operand"
+        with pytest.raises(TypeError, match=msg):
+            getattr(s, op)(2)
+
+    def test_numeric_like_ops_series_invalid(self):
+        # invalid ufunc
+        s = Series(Categorical([1, 2, 3, 4]))
+        msg = "Object with dtype category cannot perform the numpy op log"
+        with pytest.raises(TypeError, match=msg):
+            np.log(s)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_replace.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_replace.py
new file mode 100644
index 0000000000000000000000000000000000000000..3c677142846d73f7cfd08c6681ff0d7814b55bd1
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_replace.py
@@ -0,0 +1,111 @@
+import pytest
+
+import pandas as pd
+from pandas import Categorical
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "to_replace,value,expected,flip_categories",
+    [
+        # one-to-one
+        (1, 2, [2, 2, 3], False),
+        (1, 4, [4, 2, 3], False),
+        (4, 1, [1, 2, 3], False),
+        (5, 6, [1, 2, 3], False),
+        # many-to-one
+        ([1], 2, [2, 2, 3], False),
+        ([1, 2], 3, [3, 3, 3], False),
+        ([1, 2], 4, [4, 4, 3], False),
+        ((1, 2, 4), 5, [5, 5, 3], False),
+        ((5, 6), 2, [1, 2, 3], False),
+        ([1], [2], [2, 2, 3], False),
+        ([1, 4], [5, 2], [5, 2, 3], False),
+        # GH49404: overlap between to_replace and value
+        ([1, 2, 3], [2, 3, 4], [2, 3, 4], False),
+        # GH50872, GH46884: replace with null
+        (1, None, [None, 2, 3], False),
+        (1, pd.NA, [None, 2, 3], False),
+        # check_categorical sorts categories, which crashes on mixed dtypes
+        (3, "4", [1, 2, "4"], False),
+        ([1, 2, "3"], "5", ["5", "5", 3], True),
+    ],
+)
+@pytest.mark.filterwarnings(
+    "ignore:.*with CategoricalDtype is deprecated:FutureWarning"
+)
+def test_replace_categorical_series(to_replace, value, expected, flip_categories):
+    # GH 31720
+
+    ser = pd.Series([1, 2, 3], dtype="category")
+    result = ser.replace(to_replace, value)
+    expected = pd.Series(expected, dtype="category")
+    ser.replace(to_replace, value, inplace=True)
+
+    if flip_categories:
+        expected = expected.cat.set_categories(expected.cat.categories[::-1])
+
+    tm.assert_series_equal(expected, result, check_category_order=False)
+    tm.assert_series_equal(expected, ser, check_category_order=False)
+
+
+@pytest.mark.parametrize(
+    "to_replace, value, result, expected_error_msg",
+    [
+        ("b", "c", ["a", "c"], "Categorical.categories are different"),
+        ("c", "d", ["a", "b"], None),
+        # https://github.com/pandas-dev/pandas/issues/33288
+        ("a", "a", ["a", "b"], None),
+        ("b", None, ["a", None], "Categorical.categories length are different"),
+    ],
+)
+def test_replace_categorical(to_replace, value, result, expected_error_msg):
+    # GH#26988
+    cat = Categorical(["a", "b"])
+    expected = Categorical(result)
+    msg = (
+        r"The behavior of Series\.replace \(and DataFrame.replace\) "
+        "with CategoricalDtype"
+    )
+    warn = FutureWarning if expected_error_msg is not None else None
+    with tm.assert_produces_warning(warn, match=msg):
+        result = pd.Series(cat, copy=False).replace(to_replace, value)._values
+
+    tm.assert_categorical_equal(result, expected)
+    if to_replace == "b":  # the "c" test is supposed to be unchanged
+        with pytest.raises(AssertionError, match=expected_error_msg):
+            # ensure non-inplace call does not affect original
+            tm.assert_categorical_equal(cat, expected)
+
+    ser = pd.Series(cat, copy=False)
+    with tm.assert_produces_warning(warn, match=msg):
+        ser.replace(to_replace, value, inplace=True)
+    tm.assert_categorical_equal(cat, expected)
+
+
+def test_replace_categorical_ea_dtype():
+    # GH49404
+    cat = Categorical(pd.array(["a", "b"], dtype="string"))
+    msg = (
+        r"The behavior of Series\.replace \(and DataFrame.replace\) "
+        "with CategoricalDtype"
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = pd.Series(cat).replace(["a", "b"], ["c", pd.NA])._values
+    expected = Categorical(pd.array(["c", pd.NA], dtype="string"))
+    tm.assert_categorical_equal(result, expected)
+
+
+def test_replace_maintain_ordering():
+    # GH51016
+    dtype = pd.CategoricalDtype([0, 1, 2], ordered=True)
+    ser = pd.Series([0, 1, 2], dtype=dtype)
+    msg = (
+        r"The behavior of Series\.replace \(and DataFrame.replace\) "
+        "with CategoricalDtype"
+    )
+    with tm.assert_produces_warning(FutureWarning, match=msg):
+        result = ser.replace(0, 2)
+    expected_dtype = pd.CategoricalDtype([1, 2], ordered=True)
+    expected = pd.Series([2, 1, 2], dtype=expected_dtype)
+    tm.assert_series_equal(expected, result, check_category_order=True)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_repr.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_repr.py
new file mode 100644
index 0000000000000000000000000000000000000000..7929dfc9270342f188493cc9d51cc8ac013a43b5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_repr.py
@@ -0,0 +1,545 @@
+import numpy as np
+import pytest
+
+from pandas._config import using_string_dtype
+
+from pandas import (
+    Categorical,
+    CategoricalDtype,
+    CategoricalIndex,
+    Index,
+    Series,
+    date_range,
+    option_context,
+    period_range,
+    timedelta_range,
+)
+
+
+class TestCategoricalReprWithFactor:
+    def test_print(self, using_infer_string):
+        factor = Categorical(["a", "b", "b", "a", "a", "c", "c", "c"], ordered=True)
+        dtype = "str" if using_infer_string else "object"
+        expected = [
+            "['a', 'b', 'b', 'a', 'a', 'c', 'c', 'c']",
+            f"Categories (3, {dtype}): ['a' < 'b' < 'c']",
+        ]
+        expected = "\n".join(expected)
+        actual = repr(factor)
+        assert actual == expected
+
+
+class TestCategoricalRepr:
+    def test_big_print(self):
+        codes = np.array([0, 1, 2, 0, 1, 2] * 100)
+        dtype = CategoricalDtype(categories=Index(["a", "b", "c"], dtype=object))
+        factor = Categorical.from_codes(codes, dtype=dtype)
+        expected = [
+            "['a', 'b', 'c', 'a', 'b', ..., 'b', 'c', 'a', 'b', 'c']",
+            "Length: 600",
+            "Categories (3, object): ['a', 'b', 'c']",
+        ]
+        expected = "\n".join(expected)
+
+        actual = repr(factor)
+
+        assert actual == expected
+
+    def test_empty_print(self):
+        factor = Categorical([], Index(["a", "b", "c"], dtype=object))
+        expected = "[], Categories (3, object): ['a', 'b', 'c']"
+        actual = repr(factor)
+        assert actual == expected
+
+        assert expected == actual
+        factor = Categorical([], Index(["a", "b", "c"], dtype=object), ordered=True)
+        expected = "[], Categories (3, object): ['a' < 'b' < 'c']"
+        actual = repr(factor)
+        assert expected == actual
+
+        factor = Categorical([], [])
+        expected = "[], Categories (0, object): []"
+        assert expected == repr(factor)
+
+    def test_print_none_width(self):
+        # GH10087
+        a = Series(Categorical([1, 2, 3, 4]))
+        exp = (
+            "0    1\n1    2\n2    3\n3    4\n"
+            "dtype: category\nCategories (4, int64): [1, 2, 3, 4]"
+        )
+
+        with option_context("display.width", None):
+            assert exp == repr(a)
+
+    @pytest.mark.skipif(
+        using_string_dtype(),
+        reason="Change once infer_string is set to True by default",
+    )
+    def test_unicode_print(self):
+        c = Categorical(["aaaaa", "bb", "cccc"] * 20)
+        expected = """\
+['aaaaa', 'bb', 'cccc', 'aaaaa', 'bb', ..., 'bb', 'cccc', 'aaaaa', 'bb', 'cccc']
+Length: 60
+Categories (3, object): ['aaaaa', 'bb', 'cccc']"""
+
+        assert repr(c) == expected
+
+        c = Categorical(["ああああ", "いいいいい", "ううううううう"] * 20)
+        expected = """\
+['ああああ', 'いいいいい', 'ううううううう', 'ああああ', 'いいいいい', ..., 'いいいいい', 'ううううううう', 'ああああ', 'いいいいい', 'ううううううう']
+Length: 60
+Categories (3, object): ['ああああ', 'いいいいい', 'ううううううう']"""  # noqa: E501
+
+        assert repr(c) == expected
+
+        # unicode option should not affect to Categorical, as it doesn't care
+        # the repr width
+        with option_context("display.unicode.east_asian_width", True):
+            c = Categorical(["ああああ", "いいいいい", "ううううううう"] * 20)
+            expected = """['ああああ', 'いいいいい', 'ううううううう', 'ああああ', 'いいいいい', ..., 'いいいいい', 'ううううううう', 'ああああ', 'いいいいい', 'ううううううう']
+Length: 60
+Categories (3, object): ['ああああ', 'いいいいい', 'ううううううう']"""  # noqa: E501
+
+            assert repr(c) == expected
+
+    def test_categorical_repr(self):
+        c = Categorical([1, 2, 3])
+        exp = """[1, 2, 3]
+Categories (3, int64): [1, 2, 3]"""
+
+        assert repr(c) == exp
+
+        c = Categorical([1, 2, 3, 1, 2, 3], categories=[1, 2, 3])
+        exp = """[1, 2, 3, 1, 2, 3]
+Categories (3, int64): [1, 2, 3]"""
+
+        assert repr(c) == exp
+
+        c = Categorical([1, 2, 3, 4, 5] * 10)
+        exp = """[1, 2, 3, 4, 5, ..., 1, 2, 3, 4, 5]
+Length: 50
+Categories (5, int64): [1, 2, 3, 4, 5]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(np.arange(20, dtype=np.int64))
+        exp = """[0, 1, 2, 3, 4, ..., 15, 16, 17, 18, 19]
+Length: 20
+Categories (20, int64): [0, 1, 2, 3, ..., 16, 17, 18, 19]"""
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_ordered(self):
+        c = Categorical([1, 2, 3], ordered=True)
+        exp = """[1, 2, 3]
+Categories (3, int64): [1 < 2 < 3]"""
+
+        assert repr(c) == exp
+
+        c = Categorical([1, 2, 3, 1, 2, 3], categories=[1, 2, 3], ordered=True)
+        exp = """[1, 2, 3, 1, 2, 3]
+Categories (3, int64): [1 < 2 < 3]"""
+
+        assert repr(c) == exp
+
+        c = Categorical([1, 2, 3, 4, 5] * 10, ordered=True)
+        exp = """[1, 2, 3, 4, 5, ..., 1, 2, 3, 4, 5]
+Length: 50
+Categories (5, int64): [1 < 2 < 3 < 4 < 5]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(np.arange(20, dtype=np.int64), ordered=True)
+        exp = """[0, 1, 2, 3, 4, ..., 15, 16, 17, 18, 19]
+Length: 20
+Categories (20, int64): [0 < 1 < 2 < 3 ... 16 < 17 < 18 < 19]"""
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_datetime(self):
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5)
+        c = Categorical(idx)
+
+        exp = (
+            "[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, "
+            "2011-01-01 12:00:00, 2011-01-01 13:00:00]\n"
+            "Categories (5, datetime64[ns]): [2011-01-01 09:00:00, "
+            "2011-01-01 10:00:00, 2011-01-01 11:00:00,\n"
+            "                                 2011-01-01 12:00:00, "
+            "2011-01-01 13:00:00]"
+            ""
+        )
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = (
+            "[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, "
+            "2011-01-01 12:00:00, 2011-01-01 13:00:00, 2011-01-01 09:00:00, "
+            "2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, "
+            "2011-01-01 13:00:00]\n"
+            "Categories (5, datetime64[ns]): [2011-01-01 09:00:00, "
+            "2011-01-01 10:00:00, 2011-01-01 11:00:00,\n"
+            "                                 2011-01-01 12:00:00, "
+            "2011-01-01 13:00:00]"
+        )
+
+        assert repr(c) == exp
+
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5, tz="US/Eastern")
+        c = Categorical(idx)
+        exp = (
+            "[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, "
+            "2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, "
+            "2011-01-01 13:00:00-05:00]\n"
+            "Categories (5, datetime64[ns, US/Eastern]): "
+            "[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00,\n"
+            "                                             "
+            "2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00,\n"
+            "                                             "
+            "2011-01-01 13:00:00-05:00]"
+        )
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = (
+            "[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, "
+            "2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, "
+            "2011-01-01 13:00:00-05:00, 2011-01-01 09:00:00-05:00, "
+            "2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, "
+            "2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00]\n"
+            "Categories (5, datetime64[ns, US/Eastern]): "
+            "[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00,\n"
+            "                                             "
+            "2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00,\n"
+            "                                             "
+            "2011-01-01 13:00:00-05:00]"
+        )
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_datetime_ordered(self):
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5)
+        c = Categorical(idx, ordered=True)
+        exp = """[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, 2011-01-01 13:00:00]
+Categories (5, datetime64[ns]): [2011-01-01 09:00:00 < 2011-01-01 10:00:00 < 2011-01-01 11:00:00 <
+                                 2011-01-01 12:00:00 < 2011-01-01 13:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, 2011-01-01 13:00:00, 2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, 2011-01-01 13:00:00]
+Categories (5, datetime64[ns]): [2011-01-01 09:00:00 < 2011-01-01 10:00:00 < 2011-01-01 11:00:00 <
+                                 2011-01-01 12:00:00 < 2011-01-01 13:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5, tz="US/Eastern")
+        c = Categorical(idx, ordered=True)
+        exp = """[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00]
+Categories (5, datetime64[ns, US/Eastern]): [2011-01-01 09:00:00-05:00 < 2011-01-01 10:00:00-05:00 <
+                                             2011-01-01 11:00:00-05:00 < 2011-01-01 12:00:00-05:00 <
+                                             2011-01-01 13:00:00-05:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00, 2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00]
+Categories (5, datetime64[ns, US/Eastern]): [2011-01-01 09:00:00-05:00 < 2011-01-01 10:00:00-05:00 <
+                                             2011-01-01 11:00:00-05:00 < 2011-01-01 12:00:00-05:00 <
+                                             2011-01-01 13:00:00-05:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_int_with_nan(self):
+        c = Categorical([1, 2, np.nan])
+        c_exp = """[1, 2, NaN]\nCategories (2, int64): [1, 2]"""
+        assert repr(c) == c_exp
+
+        s = Series([1, 2, np.nan], dtype="object").astype("category")
+        s_exp = """0      1\n1      2\n2    NaN
+dtype: category
+Categories (2, int64): [1, 2]"""
+        assert repr(s) == s_exp
+
+    def test_categorical_repr_period(self):
+        idx = period_range("2011-01-01 09:00", freq="h", periods=5)
+        c = Categorical(idx)
+        exp = """[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00]
+Categories (5, period[h]): [2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00,
+                            2011-01-01 13:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = """[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00, 2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00]
+Categories (5, period[h]): [2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00,
+                            2011-01-01 13:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        idx = period_range("2011-01", freq="M", periods=5)
+        c = Categorical(idx)
+        exp = """[2011-01, 2011-02, 2011-03, 2011-04, 2011-05]
+Categories (5, period[M]): [2011-01, 2011-02, 2011-03, 2011-04, 2011-05]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = """[2011-01, 2011-02, 2011-03, 2011-04, 2011-05, 2011-01, 2011-02, 2011-03, 2011-04, 2011-05]
+Categories (5, period[M]): [2011-01, 2011-02, 2011-03, 2011-04, 2011-05]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_period_ordered(self):
+        idx = period_range("2011-01-01 09:00", freq="h", periods=5)
+        c = Categorical(idx, ordered=True)
+        exp = """[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00]
+Categories (5, period[h]): [2011-01-01 09:00 < 2011-01-01 10:00 < 2011-01-01 11:00 < 2011-01-01 12:00 <
+                            2011-01-01 13:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00, 2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00]
+Categories (5, period[h]): [2011-01-01 09:00 < 2011-01-01 10:00 < 2011-01-01 11:00 < 2011-01-01 12:00 <
+                            2011-01-01 13:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        idx = period_range("2011-01", freq="M", periods=5)
+        c = Categorical(idx, ordered=True)
+        exp = """[2011-01, 2011-02, 2011-03, 2011-04, 2011-05]
+Categories (5, period[M]): [2011-01 < 2011-02 < 2011-03 < 2011-04 < 2011-05]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[2011-01, 2011-02, 2011-03, 2011-04, 2011-05, 2011-01, 2011-02, 2011-03, 2011-04, 2011-05]
+Categories (5, period[M]): [2011-01 < 2011-02 < 2011-03 < 2011-04 < 2011-05]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_timedelta(self):
+        idx = timedelta_range("1 days", periods=5)
+        c = Categorical(idx)
+        exp = """[1 days, 2 days, 3 days, 4 days, 5 days]
+Categories (5, timedelta64[ns]): [1 days, 2 days, 3 days, 4 days, 5 days]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = """[1 days, 2 days, 3 days, 4 days, 5 days, 1 days, 2 days, 3 days, 4 days, 5 days]
+Categories (5, timedelta64[ns]): [1 days, 2 days, 3 days, 4 days, 5 days]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        idx = timedelta_range("1 hours", periods=20)
+        c = Categorical(idx)
+        exp = """[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, 4 days 01:00:00, ..., 15 days 01:00:00, 16 days 01:00:00, 17 days 01:00:00, 18 days 01:00:00, 19 days 01:00:00]
+Length: 20
+Categories (20, timedelta64[ns]): [0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00,
+                                   3 days 01:00:00, ..., 16 days 01:00:00, 17 days 01:00:00,
+                                   18 days 01:00:00, 19 days 01:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx)
+        exp = """[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, 4 days 01:00:00, ..., 15 days 01:00:00, 16 days 01:00:00, 17 days 01:00:00, 18 days 01:00:00, 19 days 01:00:00]
+Length: 40
+Categories (20, timedelta64[ns]): [0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00,
+                                   3 days 01:00:00, ..., 16 days 01:00:00, 17 days 01:00:00,
+                                   18 days 01:00:00, 19 days 01:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+    def test_categorical_repr_timedelta_ordered(self):
+        idx = timedelta_range("1 days", periods=5)
+        c = Categorical(idx, ordered=True)
+        exp = """[1 days, 2 days, 3 days, 4 days, 5 days]
+Categories (5, timedelta64[ns]): [1 days < 2 days < 3 days < 4 days < 5 days]"""
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[1 days, 2 days, 3 days, 4 days, 5 days, 1 days, 2 days, 3 days, 4 days, 5 days]
+Categories (5, timedelta64[ns]): [1 days < 2 days < 3 days < 4 days < 5 days]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        idx = timedelta_range("1 hours", periods=20)
+        c = Categorical(idx, ordered=True)
+        exp = """[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, 4 days 01:00:00, ..., 15 days 01:00:00, 16 days 01:00:00, 17 days 01:00:00, 18 days 01:00:00, 19 days 01:00:00]
+Length: 20
+Categories (20, timedelta64[ns]): [0 days 01:00:00 < 1 days 01:00:00 < 2 days 01:00:00 <
+                                   3 days 01:00:00 ... 16 days 01:00:00 < 17 days 01:00:00 <
+                                   18 days 01:00:00 < 19 days 01:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+        c = Categorical(idx.append(idx), categories=idx, ordered=True)
+        exp = """[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, 4 days 01:00:00, ..., 15 days 01:00:00, 16 days 01:00:00, 17 days 01:00:00, 18 days 01:00:00, 19 days 01:00:00]
+Length: 40
+Categories (20, timedelta64[ns]): [0 days 01:00:00 < 1 days 01:00:00 < 2 days 01:00:00 <
+                                   3 days 01:00:00 ... 16 days 01:00:00 < 17 days 01:00:00 <
+                                   18 days 01:00:00 < 19 days 01:00:00]"""  # noqa: E501
+
+        assert repr(c) == exp
+
+    def test_categorical_index_repr(self):
+        idx = CategoricalIndex(Categorical([1, 2, 3]))
+        exp = """CategoricalIndex([1, 2, 3], categories=[1, 2, 3], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(idx) == exp
+
+        i = CategoricalIndex(Categorical(np.arange(10, dtype=np.int64)))
+        exp = """CategoricalIndex([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], categories=[0, 1, 2, 3, ..., 6, 7, 8, 9], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_ordered(self):
+        i = CategoricalIndex(Categorical([1, 2, 3], ordered=True))
+        exp = """CategoricalIndex([1, 2, 3], categories=[1, 2, 3], ordered=True, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        i = CategoricalIndex(Categorical(np.arange(10, dtype=np.int64), ordered=True))
+        exp = """CategoricalIndex([0, 1, 2, 3, 4, 5, 6, 7, 8, 9], categories=[0, 1, 2, 3, ..., 6, 7, 8, 9], ordered=True, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_datetime(self):
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00:00', '2011-01-01 10:00:00',
+                  '2011-01-01 11:00:00', '2011-01-01 12:00:00',
+                  '2011-01-01 13:00:00'],
+                 categories=[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, 2011-01-01 13:00:00], ordered=False, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5, tz="US/Eastern")
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00:00-05:00', '2011-01-01 10:00:00-05:00',
+                  '2011-01-01 11:00:00-05:00', '2011-01-01 12:00:00-05:00',
+                  '2011-01-01 13:00:00-05:00'],
+                 categories=[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00], ordered=False, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_datetime_ordered(self):
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5)
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['2011-01-01 09:00:00', '2011-01-01 10:00:00',
+                  '2011-01-01 11:00:00', '2011-01-01 12:00:00',
+                  '2011-01-01 13:00:00'],
+                 categories=[2011-01-01 09:00:00, 2011-01-01 10:00:00, 2011-01-01 11:00:00, 2011-01-01 12:00:00, 2011-01-01 13:00:00], ordered=True, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        idx = date_range("2011-01-01 09:00", freq="h", periods=5, tz="US/Eastern")
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['2011-01-01 09:00:00-05:00', '2011-01-01 10:00:00-05:00',
+                  '2011-01-01 11:00:00-05:00', '2011-01-01 12:00:00-05:00',
+                  '2011-01-01 13:00:00-05:00'],
+                 categories=[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00], ordered=True, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        i = CategoricalIndex(Categorical(idx.append(idx), ordered=True))
+        exp = """CategoricalIndex(['2011-01-01 09:00:00-05:00', '2011-01-01 10:00:00-05:00',
+                  '2011-01-01 11:00:00-05:00', '2011-01-01 12:00:00-05:00',
+                  '2011-01-01 13:00:00-05:00', '2011-01-01 09:00:00-05:00',
+                  '2011-01-01 10:00:00-05:00', '2011-01-01 11:00:00-05:00',
+                  '2011-01-01 12:00:00-05:00', '2011-01-01 13:00:00-05:00'],
+                 categories=[2011-01-01 09:00:00-05:00, 2011-01-01 10:00:00-05:00, 2011-01-01 11:00:00-05:00, 2011-01-01 12:00:00-05:00, 2011-01-01 13:00:00-05:00], ordered=True, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_period(self):
+        # test all length
+        idx = period_range("2011-01-01 09:00", freq="h", periods=1)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00'], categories=[2011-01-01 09:00], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        idx = period_range("2011-01-01 09:00", freq="h", periods=2)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00', '2011-01-01 10:00'], categories=[2011-01-01 09:00, 2011-01-01 10:00], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        idx = period_range("2011-01-01 09:00", freq="h", periods=3)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00', '2011-01-01 10:00', '2011-01-01 11:00'], categories=[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        idx = period_range("2011-01-01 09:00", freq="h", periods=5)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01-01 09:00', '2011-01-01 10:00', '2011-01-01 11:00',
+                  '2011-01-01 12:00', '2011-01-01 13:00'],
+                 categories=[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00], ordered=False, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        i = CategoricalIndex(Categorical(idx.append(idx)))
+        exp = """CategoricalIndex(['2011-01-01 09:00', '2011-01-01 10:00', '2011-01-01 11:00',
+                  '2011-01-01 12:00', '2011-01-01 13:00', '2011-01-01 09:00',
+                  '2011-01-01 10:00', '2011-01-01 11:00', '2011-01-01 12:00',
+                  '2011-01-01 13:00'],
+                 categories=[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00], ordered=False, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        idx = period_range("2011-01", freq="M", periods=5)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['2011-01', '2011-02', '2011-03', '2011-04', '2011-05'], categories=[2011-01, 2011-02, 2011-03, 2011-04, 2011-05], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_period_ordered(self):
+        idx = period_range("2011-01-01 09:00", freq="h", periods=5)
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['2011-01-01 09:00', '2011-01-01 10:00', '2011-01-01 11:00',
+                  '2011-01-01 12:00', '2011-01-01 13:00'],
+                 categories=[2011-01-01 09:00, 2011-01-01 10:00, 2011-01-01 11:00, 2011-01-01 12:00, 2011-01-01 13:00], ordered=True, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+        idx = period_range("2011-01", freq="M", periods=5)
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['2011-01', '2011-02', '2011-03', '2011-04', '2011-05'], categories=[2011-01, 2011-02, 2011-03, 2011-04, 2011-05], ordered=True, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_timedelta(self):
+        idx = timedelta_range("1 days", periods=5)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['1 days', '2 days', '3 days', '4 days', '5 days'], categories=[1 days, 2 days, 3 days, 4 days, 5 days], ordered=False, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        idx = timedelta_range("1 hours", periods=10)
+        i = CategoricalIndex(Categorical(idx))
+        exp = """CategoricalIndex(['0 days 01:00:00', '1 days 01:00:00', '2 days 01:00:00',
+                  '3 days 01:00:00', '4 days 01:00:00', '5 days 01:00:00',
+                  '6 days 01:00:00', '7 days 01:00:00', '8 days 01:00:00',
+                  '9 days 01:00:00'],
+                 categories=[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, ..., 6 days 01:00:00, 7 days 01:00:00, 8 days 01:00:00, 9 days 01:00:00], ordered=False, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+    def test_categorical_index_repr_timedelta_ordered(self):
+        idx = timedelta_range("1 days", periods=5)
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['1 days', '2 days', '3 days', '4 days', '5 days'], categories=[1 days, 2 days, 3 days, 4 days, 5 days], ordered=True, dtype='category')"""  # noqa: E501
+        assert repr(i) == exp
+
+        idx = timedelta_range("1 hours", periods=10)
+        i = CategoricalIndex(Categorical(idx, ordered=True))
+        exp = """CategoricalIndex(['0 days 01:00:00', '1 days 01:00:00', '2 days 01:00:00',
+                  '3 days 01:00:00', '4 days 01:00:00', '5 days 01:00:00',
+                  '6 days 01:00:00', '7 days 01:00:00', '8 days 01:00:00',
+                  '9 days 01:00:00'],
+                 categories=[0 days 01:00:00, 1 days 01:00:00, 2 days 01:00:00, 3 days 01:00:00, ..., 6 days 01:00:00, 7 days 01:00:00, 8 days 01:00:00, 9 days 01:00:00], ordered=True, dtype='category')"""  # noqa: E501
+
+        assert repr(i) == exp
+
+    def test_categorical_str_repr(self):
+        # GH 33676
+        result = repr(Categorical([1, "2", 3, 4]))
+        expected = "[1, '2', 3, 4]\nCategories (4, object): [1, 3, 4, '2']"
+        assert result == expected
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_sorting.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_sorting.py
new file mode 100644
index 0000000000000000000000000000000000000000..ae527065b3fb970263609881d217f5c6d2761231
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_sorting.py
@@ -0,0 +1,128 @@
+import numpy as np
+import pytest
+
+from pandas import (
+    Categorical,
+    Index,
+)
+import pandas._testing as tm
+
+
+class TestCategoricalSort:
+    def test_argsort(self):
+        c = Categorical([5, 3, 1, 4, 2], ordered=True)
+
+        expected = np.array([2, 4, 1, 3, 0])
+        tm.assert_numpy_array_equal(
+            c.argsort(ascending=True), expected, check_dtype=False
+        )
+
+        expected = expected[::-1]
+        tm.assert_numpy_array_equal(
+            c.argsort(ascending=False), expected, check_dtype=False
+        )
+
+    def test_numpy_argsort(self):
+        c = Categorical([5, 3, 1, 4, 2], ordered=True)
+
+        expected = np.array([2, 4, 1, 3, 0])
+        tm.assert_numpy_array_equal(np.argsort(c), expected, check_dtype=False)
+
+        tm.assert_numpy_array_equal(
+            np.argsort(c, kind="mergesort"), expected, check_dtype=False
+        )
+
+        msg = "the 'axis' parameter is not supported"
+        with pytest.raises(ValueError, match=msg):
+            np.argsort(c, axis=0)
+
+        msg = "the 'order' parameter is not supported"
+        with pytest.raises(ValueError, match=msg):
+            np.argsort(c, order="C")
+
+    def test_sort_values(self):
+        # unordered cats are sortable
+        cat = Categorical(["a", "b", "b", "a"], ordered=False)
+        cat.sort_values()
+
+        cat = Categorical(["a", "c", "b", "d"], ordered=True)
+
+        # sort_values
+        res = cat.sort_values()
+        exp = np.array(["a", "b", "c", "d"], dtype=object)
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, cat.categories)
+
+        cat = Categorical(
+            ["a", "c", "b", "d"], categories=["a", "b", "c", "d"], ordered=True
+        )
+        res = cat.sort_values()
+        exp = np.array(["a", "b", "c", "d"], dtype=object)
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, cat.categories)
+
+        res = cat.sort_values(ascending=False)
+        exp = np.array(["d", "c", "b", "a"], dtype=object)
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, cat.categories)
+
+        # sort (inplace order)
+        cat1 = cat.copy()
+        orig_codes = cat1._codes
+        cat1.sort_values(inplace=True)
+        assert cat1._codes is orig_codes
+        exp = np.array(["a", "b", "c", "d"], dtype=object)
+        tm.assert_numpy_array_equal(cat1.__array__(), exp)
+        tm.assert_index_equal(res.categories, cat.categories)
+
+        # reverse
+        cat = Categorical(["a", "c", "c", "b", "d"], ordered=True)
+        res = cat.sort_values(ascending=False)
+        exp_val = np.array(["d", "c", "c", "b", "a"], dtype=object)
+        exp_categories = Index(["a", "b", "c", "d"])
+        tm.assert_numpy_array_equal(res.__array__(), exp_val)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+    def test_sort_values_na_position(self):
+        # see gh-12882
+        cat = Categorical([5, 2, np.nan, 2, np.nan], ordered=True)
+        exp_categories = Index([2, 5])
+
+        exp = np.array([2.0, 2.0, 5.0, np.nan, np.nan])
+        res = cat.sort_values()  # default arguments
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        exp = np.array([np.nan, np.nan, 2.0, 2.0, 5.0])
+        res = cat.sort_values(ascending=True, na_position="first")
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        exp = np.array([np.nan, np.nan, 5.0, 2.0, 2.0])
+        res = cat.sort_values(ascending=False, na_position="first")
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        exp = np.array([2.0, 2.0, 5.0, np.nan, np.nan])
+        res = cat.sort_values(ascending=True, na_position="last")
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        exp = np.array([5.0, 2.0, 2.0, np.nan, np.nan])
+        res = cat.sort_values(ascending=False, na_position="last")
+        tm.assert_numpy_array_equal(res.__array__(), exp)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        cat = Categorical(["a", "c", "b", "d", np.nan], ordered=True)
+        res = cat.sort_values(ascending=False, na_position="last")
+        exp_val = np.array(["d", "c", "b", "a", np.nan], dtype=object)
+        exp_categories = Index(["a", "b", "c", "d"])
+        tm.assert_numpy_array_equal(res.__array__(), exp_val)
+        tm.assert_index_equal(res.categories, exp_categories)
+
+        cat = Categorical(["a", "c", "b", "d", np.nan], ordered=True)
+        res = cat.sort_values(ascending=False, na_position="first")
+        exp_val = np.array([np.nan, "d", "c", "b", "a"], dtype=object)
+        exp_categories = Index(["a", "b", "c", "d"])
+        tm.assert_numpy_array_equal(res.__array__(), exp_val)
+        tm.assert_index_equal(res.categories, exp_categories)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_subclass.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_subclass.py
new file mode 100644
index 0000000000000000000000000000000000000000..5b0c0a44e655d5dd943f95415336204aa12f0b67
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_subclass.py
@@ -0,0 +1,26 @@
+from pandas import Categorical
+import pandas._testing as tm
+
+
+class SubclassedCategorical(Categorical):
+    pass
+
+
+class TestCategoricalSubclassing:
+    def test_constructor(self):
+        sc = SubclassedCategorical(["a", "b", "c"])
+        assert isinstance(sc, SubclassedCategorical)
+        tm.assert_categorical_equal(sc, Categorical(["a", "b", "c"]))
+
+    def test_from_codes(self):
+        sc = SubclassedCategorical.from_codes([1, 0, 2], ["a", "b", "c"])
+        assert isinstance(sc, SubclassedCategorical)
+        exp = Categorical.from_codes([1, 0, 2], ["a", "b", "c"])
+        tm.assert_categorical_equal(sc, exp)
+
+    def test_map(self):
+        sc = SubclassedCategorical(["a", "b", "c"])
+        res = sc.map(lambda x: x.upper(), na_action=None)
+        assert isinstance(res, SubclassedCategorical)
+        exp = Categorical(["A", "B", "C"])
+        tm.assert_categorical_equal(res, exp)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_take.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_take.py
new file mode 100644
index 0000000000000000000000000000000000000000..373f1b30a13c2daff23e14a3e0640e7a716cceb3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_take.py
@@ -0,0 +1,89 @@
+import numpy as np
+import pytest
+
+from pandas import Categorical
+import pandas._testing as tm
+
+
+@pytest.fixture(params=[True, False])
+def allow_fill(request):
+    """Boolean 'allow_fill' parameter for Categorical.take"""
+    return request.param
+
+
+class TestTake:
+    # https://github.com/pandas-dev/pandas/issues/20664
+
+    def test_take_default_allow_fill(self):
+        cat = Categorical(["a", "b"])
+        with tm.assert_produces_warning(None):
+            result = cat.take([0, -1])
+
+        assert result.equals(cat)
+
+    def test_take_positive_no_warning(self):
+        cat = Categorical(["a", "b"])
+        with tm.assert_produces_warning(None):
+            cat.take([0, 0])
+
+    def test_take_bounds(self, allow_fill):
+        # https://github.com/pandas-dev/pandas/issues/20664
+        cat = Categorical(["a", "b", "a"])
+        if allow_fill:
+            msg = "indices are out-of-bounds"
+        else:
+            msg = "index 4 is out of bounds for( axis 0 with)? size 3"
+        with pytest.raises(IndexError, match=msg):
+            cat.take([4, 5], allow_fill=allow_fill)
+
+    def test_take_empty(self, allow_fill):
+        # https://github.com/pandas-dev/pandas/issues/20664
+        cat = Categorical([], categories=["a", "b"])
+        if allow_fill:
+            msg = "indices are out-of-bounds"
+        else:
+            msg = "cannot do a non-empty take from an empty axes"
+        with pytest.raises(IndexError, match=msg):
+            cat.take([0], allow_fill=allow_fill)
+
+    def test_positional_take(self, ordered):
+        cat = Categorical(["a", "a", "b", "b"], categories=["b", "a"], ordered=ordered)
+        result = cat.take([0, 1, 2], allow_fill=False)
+        expected = Categorical(
+            ["a", "a", "b"], categories=cat.categories, ordered=ordered
+        )
+        tm.assert_categorical_equal(result, expected)
+
+    def test_positional_take_unobserved(self, ordered):
+        cat = Categorical(["a", "b"], categories=["a", "b", "c"], ordered=ordered)
+        result = cat.take([1, 0], allow_fill=False)
+        expected = Categorical(["b", "a"], categories=cat.categories, ordered=ordered)
+        tm.assert_categorical_equal(result, expected)
+
+    def test_take_allow_fill(self):
+        # https://github.com/pandas-dev/pandas/issues/23296
+        cat = Categorical(["a", "a", "b"])
+        result = cat.take([0, -1, -1], allow_fill=True)
+        expected = Categorical(["a", np.nan, np.nan], categories=["a", "b"])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_take_fill_with_negative_one(self):
+        # -1 was a category
+        cat = Categorical([-1, 0, 1])
+        result = cat.take([0, -1, 1], allow_fill=True, fill_value=-1)
+        expected = Categorical([-1, -1, 0], categories=[-1, 0, 1])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_take_fill_value(self):
+        # https://github.com/pandas-dev/pandas/issues/23296
+        cat = Categorical(["a", "b", "c"])
+        result = cat.take([0, 1, -1], fill_value="a", allow_fill=True)
+        expected = Categorical(["a", "b", "a"], categories=["a", "b", "c"])
+        tm.assert_categorical_equal(result, expected)
+
+    def test_take_fill_value_new_raises(self):
+        # https://github.com/pandas-dev/pandas/issues/23296
+        cat = Categorical(["a", "b", "c"])
+        xpr = r"Cannot setitem on a Categorical with a new category \(d\)"
+        with pytest.raises(TypeError, match=xpr):
+            cat.take([0, 1, -1], fill_value="d", allow_fill=True)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_warnings.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_warnings.py
new file mode 100644
index 0000000000000000000000000000000000000000..68c59706a6c3bf93908108c337b51c8da187cbb4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/categorical/test_warnings.py
@@ -0,0 +1,19 @@
+import pytest
+
+import pandas._testing as tm
+
+
+class TestCategoricalWarnings:
+    def test_tab_complete_warning(self, ip):
+        # https://github.com/pandas-dev/pandas/issues/16409
+        pytest.importorskip("IPython", minversion="6.0.0")
+        from IPython.core.completer import provisionalcompleter
+
+        code = "import pandas as pd; c = pd.Categorical([])"
+        ip.run_cell(code)
+
+        # GH 31324 newer jedi version raises Deprecation warning;
+        #  appears resolved 2021-02-02
+        with tm.assert_produces_warning(None, raise_on_extra_warnings=False):
+            with provisionalcompleter("ignore"):
+                list(ip.Completer.completions("c.", 1))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_constructors.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_constructors.py
new file mode 100644
index 0000000000000000000000000000000000000000..3652b5fec46bbe7a519dd2c3a196ac87bd74784f
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_constructors.py
@@ -0,0 +1,284 @@
+import numpy as np
+import pytest
+
+from pandas._libs import iNaT
+
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import DatetimeArray
+
+
+class TestDatetimeArrayConstructor:
+    def test_from_sequence_invalid_type(self):
+        mi = pd.MultiIndex.from_product([np.arange(5), np.arange(5)])
+        with pytest.raises(TypeError, match="Cannot create a DatetimeArray"):
+            DatetimeArray._from_sequence(mi, dtype="M8[ns]")
+
+    def test_only_1dim_accepted(self):
+        arr = np.array([0, 1, 2, 3], dtype="M8[h]").astype("M8[ns]")
+
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Only 1-dimensional"):
+                # 3-dim, we allow 2D to sneak in for ops purposes GH#29853
+                DatetimeArray(arr.reshape(2, 2, 1))
+
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Only 1-dimensional"):
+                # 0-dim
+                DatetimeArray(arr[[0]].squeeze())
+
+    def test_freq_validation(self):
+        # GH#24623 check that invalid instances cannot be created with the
+        #  public constructor
+        arr = np.arange(5, dtype=np.int64) * 3600 * 10**9
+
+        msg = (
+            "Inferred frequency h from passed values does not "
+            "conform to passed frequency W-SUN"
+        )
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                DatetimeArray(arr, freq="W")
+
+    @pytest.mark.parametrize(
+        "meth",
+        [
+            DatetimeArray._from_sequence,
+            pd.to_datetime,
+            pd.DatetimeIndex,
+        ],
+    )
+    def test_mixing_naive_tzaware_raises(self, meth):
+        # GH#24569
+        arr = np.array([pd.Timestamp("2000"), pd.Timestamp("2000", tz="CET")])
+
+        msg = (
+            "Cannot mix tz-aware with tz-naive values|"
+            "Tz-aware datetime.datetime cannot be converted "
+            "to datetime64 unless utc=True"
+        )
+
+        for obj in [arr, arr[::-1]]:
+            # check that we raise regardless of whether naive is found
+            #  before aware or vice-versa
+            with pytest.raises(ValueError, match=msg):
+                meth(obj)
+
+    def test_from_pandas_array(self):
+        arr = pd.array(np.arange(5, dtype=np.int64)) * 3600 * 10**9
+
+        result = DatetimeArray._from_sequence(arr, dtype="M8[ns]")._with_freq("infer")
+
+        expected = pd.date_range("1970-01-01", periods=5, freq="h")._data
+        tm.assert_datetime_array_equal(result, expected)
+
+    def test_mismatched_timezone_raises(self):
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            arr = DatetimeArray(
+                np.array(["2000-01-01T06:00:00"], dtype="M8[ns]"),
+                dtype=DatetimeTZDtype(tz="US/Central"),
+            )
+        dtype = DatetimeTZDtype(tz="US/Eastern")
+        msg = r"dtype=datetime64\[ns.*\] does not match data dtype datetime64\[ns.*\]"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(TypeError, match=msg):
+                DatetimeArray(arr, dtype=dtype)
+
+        # also with mismatched tzawareness
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(TypeError, match=msg):
+                DatetimeArray(arr, dtype=np.dtype("M8[ns]"))
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(TypeError, match=msg):
+                DatetimeArray(arr.tz_localize(None), dtype=arr.dtype)
+
+    def test_non_array_raises(self):
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="list"):
+                DatetimeArray([1, 2, 3])
+
+    def test_bool_dtype_raises(self):
+        arr = np.array([1, 2, 3], dtype="bool")
+
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        msg = "Unexpected value for 'dtype': 'bool'. Must be"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                DatetimeArray(arr)
+
+        msg = r"dtype bool cannot be converted to datetime64\[ns\]"
+        with pytest.raises(TypeError, match=msg):
+            DatetimeArray._from_sequence(arr, dtype="M8[ns]")
+
+        with pytest.raises(TypeError, match=msg):
+            pd.DatetimeIndex(arr)
+
+        with pytest.raises(TypeError, match=msg):
+            pd.to_datetime(arr)
+
+    def test_incorrect_dtype_raises(self):
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Unexpected value for 'dtype'."):
+                DatetimeArray(np.array([1, 2, 3], dtype="i8"), dtype="category")
+
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Unexpected value for 'dtype'."):
+                DatetimeArray(np.array([1, 2, 3], dtype="i8"), dtype="m8[s]")
+
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Unexpected value for 'dtype'."):
+                DatetimeArray(np.array([1, 2, 3], dtype="i8"), dtype="M8[D]")
+
+    def test_mismatched_values_dtype_units(self):
+        arr = np.array([1, 2, 3], dtype="M8[s]")
+        dtype = np.dtype("M8[ns]")
+        msg = "Values resolution does not match dtype."
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                DatetimeArray(arr, dtype=dtype)
+
+        dtype2 = DatetimeTZDtype(tz="UTC", unit="ns")
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match=msg):
+                DatetimeArray(arr, dtype=dtype2)
+
+    def test_freq_infer_raises(self):
+        depr_msg = "DatetimeArray.__init__ is deprecated"
+        with tm.assert_produces_warning(FutureWarning, match=depr_msg):
+            with pytest.raises(ValueError, match="Frequency inference"):
+                DatetimeArray(np.array([1, 2, 3], dtype="i8"), freq="infer")
+
+    def test_copy(self):
+        data = np.array([1, 2, 3], dtype="M8[ns]")
+        arr = DatetimeArray._from_sequence(data, copy=False)
+        assert arr._ndarray is data
+
+        arr = DatetimeArray._from_sequence(data, copy=True)
+        assert arr._ndarray is not data
+
+    @pytest.mark.parametrize("unit", ["s", "ms", "us", "ns"])
+    def test_numpy_datetime_unit(self, unit):
+        data = np.array([1, 2, 3], dtype=f"M8[{unit}]")
+        arr = DatetimeArray._from_sequence(data)
+        assert arr.unit == unit
+        assert arr[0].unit == unit
+
+
+class TestSequenceToDT64NS:
+    def test_tz_dtype_mismatch_raises(self):
+        arr = DatetimeArray._from_sequence(
+            ["2000"], dtype=DatetimeTZDtype(tz="US/Central")
+        )
+        with pytest.raises(TypeError, match="data is already tz-aware"):
+            DatetimeArray._from_sequence(arr, dtype=DatetimeTZDtype(tz="UTC"))
+
+    def test_tz_dtype_matches(self):
+        dtype = DatetimeTZDtype(tz="US/Central")
+        arr = DatetimeArray._from_sequence(["2000"], dtype=dtype)
+        result = DatetimeArray._from_sequence(arr, dtype=dtype)
+        tm.assert_equal(arr, result)
+
+    @pytest.mark.parametrize("order", ["F", "C"])
+    def test_2d(self, order):
+        dti = pd.date_range("2016-01-01", periods=6, tz="US/Pacific")
+        arr = np.array(dti, dtype=object).reshape(3, 2)
+        if order == "F":
+            arr = arr.T
+
+        res = DatetimeArray._from_sequence(arr, dtype=dti.dtype)
+        expected = DatetimeArray._from_sequence(arr.ravel(), dtype=dti.dtype).reshape(
+            arr.shape
+        )
+        tm.assert_datetime_array_equal(res, expected)
+
+
+# ----------------------------------------------------------------------------
+# Arrow interaction
+
+
+EXTREME_VALUES = [0, 123456789, None, iNaT, 2**63 - 1, -(2**63) + 1]
+FINE_TO_COARSE_SAFE = [123_000_000_000, None, -123_000_000_000]
+COARSE_TO_FINE_SAFE = [123, None, -123]
+
+
+@pytest.mark.parametrize(
+    ("pa_unit", "pd_unit", "pa_tz", "pd_tz", "data"),
+    [
+        ("s", "s", "UTC", "UTC", EXTREME_VALUES),
+        ("ms", "ms", "UTC", "Europe/Berlin", EXTREME_VALUES),
+        ("us", "us", "US/Eastern", "UTC", EXTREME_VALUES),
+        ("ns", "ns", "US/Central", "Asia/Kolkata", EXTREME_VALUES),
+        ("ns", "s", "UTC", "UTC", FINE_TO_COARSE_SAFE),
+        ("us", "ms", "UTC", "Europe/Berlin", FINE_TO_COARSE_SAFE),
+        ("ms", "us", "US/Eastern", "UTC", COARSE_TO_FINE_SAFE),
+        ("s", "ns", "US/Central", "Asia/Kolkata", COARSE_TO_FINE_SAFE),
+    ],
+)
+def test_from_arrow_with_different_units_and_timezones_with(
+    pa_unit, pd_unit, pa_tz, pd_tz, data
+):
+    pa = pytest.importorskip("pyarrow")
+
+    pa_type = pa.timestamp(pa_unit, tz=pa_tz)
+    arr = pa.array(data, type=pa_type)
+    dtype = DatetimeTZDtype(unit=pd_unit, tz=pd_tz)
+
+    result = dtype.__from_arrow__(arr)
+    expected = DatetimeArray._from_sequence(data, dtype=f"M8[{pa_unit}, UTC]").astype(
+        dtype, copy=False
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    result = dtype.__from_arrow__(pa.chunked_array([arr]))
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    ("unit", "tz"),
+    [
+        ("s", "UTC"),
+        ("ms", "Europe/Berlin"),
+        ("us", "US/Eastern"),
+        ("ns", "Asia/Kolkata"),
+        ("ns", "UTC"),
+    ],
+)
+def test_from_arrow_from_empty(unit, tz):
+    pa = pytest.importorskip("pyarrow")
+
+    data = []
+    arr = pa.array(data)
+    dtype = DatetimeTZDtype(unit=unit, tz=tz)
+
+    result = dtype.__from_arrow__(arr)
+    expected = DatetimeArray._from_sequence(np.array(data, dtype=f"datetime64[{unit}]"))
+    expected = expected.tz_localize(tz=tz)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = dtype.__from_arrow__(pa.chunked_array([arr]))
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_from_arrow_from_integers():
+    pa = pytest.importorskip("pyarrow")
+
+    data = [0, 123456789, None, 2**63 - 1, iNaT, -123456789]
+    arr = pa.array(data)
+    dtype = DatetimeTZDtype(unit="ns", tz="UTC")
+
+    result = dtype.__from_arrow__(arr)
+    expected = DatetimeArray._from_sequence(np.array(data, dtype="datetime64[ns]"))
+    expected = expected.tz_localize("UTC")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = dtype.__from_arrow__(pa.chunked_array([arr]))
+    tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_cumulative.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_cumulative.py
new file mode 100644
index 0000000000000000000000000000000000000000..e9d2dfdd0048a42a3f23e41be1d45a89aae11d23
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_cumulative.py
@@ -0,0 +1,44 @@
+import pytest
+
+import pandas._testing as tm
+from pandas.core.arrays import DatetimeArray
+
+
+class TestAccumulator:
+    def test_accumulators_freq(self):
+        # GH#50297
+        arr = DatetimeArray._from_sequence(
+            [
+                "2000-01-01",
+                "2000-01-02",
+                "2000-01-03",
+            ],
+            dtype="M8[ns]",
+        )._with_freq("infer")
+        result = arr._accumulate("cummin")
+        expected = DatetimeArray._from_sequence(["2000-01-01"] * 3, dtype="M8[ns]")
+        tm.assert_datetime_array_equal(result, expected)
+
+        result = arr._accumulate("cummax")
+        expected = DatetimeArray._from_sequence(
+            [
+                "2000-01-01",
+                "2000-01-02",
+                "2000-01-03",
+            ],
+            dtype="M8[ns]",
+        )
+        tm.assert_datetime_array_equal(result, expected)
+
+    @pytest.mark.parametrize("func", ["cumsum", "cumprod"])
+    def test_accumulators_disallowed(self, func):
+        # GH#50297
+        arr = DatetimeArray._from_sequence(
+            [
+                "2000-01-01",
+                "2000-01-02",
+            ],
+            dtype="M8[ns]",
+        )._with_freq("infer")
+        with pytest.raises(TypeError, match=f"Accumulation {func}"):
+            arr._accumulate(func)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_reductions.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_reductions.py
new file mode 100644
index 0000000000000000000000000000000000000000..a941546b13a567b705f61a3a667119cd55a2f0e4
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/datetimes/test_reductions.py
@@ -0,0 +1,183 @@
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.dtypes import DatetimeTZDtype
+
+import pandas as pd
+from pandas import NaT
+import pandas._testing as tm
+from pandas.core.arrays import DatetimeArray
+
+
+class TestReductions:
+    @pytest.fixture(params=["s", "ms", "us", "ns"])
+    def unit(self, request):
+        return request.param
+
+    @pytest.fixture
+    def arr1d(self, tz_naive_fixture):
+        """Fixture returning DatetimeArray with parametrized timezones"""
+        tz = tz_naive_fixture
+        dtype = DatetimeTZDtype(tz=tz) if tz is not None else np.dtype("M8[ns]")
+        arr = DatetimeArray._from_sequence(
+            [
+                "2000-01-03",
+                "2000-01-03",
+                "NaT",
+                "2000-01-02",
+                "2000-01-05",
+                "2000-01-04",
+            ],
+            dtype=dtype,
+        )
+        return arr
+
+    def test_min_max(self, arr1d, unit):
+        arr = arr1d
+        arr = arr.as_unit(unit)
+        tz = arr.tz
+
+        result = arr.min()
+        expected = pd.Timestamp("2000-01-02", tz=tz).as_unit(unit)
+        assert result == expected
+        assert result.unit == expected.unit
+
+        result = arr.max()
+        expected = pd.Timestamp("2000-01-05", tz=tz).as_unit(unit)
+        assert result == expected
+        assert result.unit == expected.unit
+
+        result = arr.min(skipna=False)
+        assert result is NaT
+
+        result = arr.max(skipna=False)
+        assert result is NaT
+
+    @pytest.mark.parametrize("tz", [None, "US/Central"])
+    @pytest.mark.parametrize("skipna", [True, False])
+    def test_min_max_empty(self, skipna, tz):
+        dtype = DatetimeTZDtype(tz=tz) if tz is not None else np.dtype("M8[ns]")
+        arr = DatetimeArray._from_sequence([], dtype=dtype)
+        result = arr.min(skipna=skipna)
+        assert result is NaT
+
+        result = arr.max(skipna=skipna)
+        assert result is NaT
+
+    @pytest.mark.parametrize("tz", [None, "US/Central"])
+    @pytest.mark.parametrize("skipna", [True, False])
+    def test_median_empty(self, skipna, tz):
+        dtype = DatetimeTZDtype(tz=tz) if tz is not None else np.dtype("M8[ns]")
+        arr = DatetimeArray._from_sequence([], dtype=dtype)
+        result = arr.median(skipna=skipna)
+        assert result is NaT
+
+        arr = arr.reshape(0, 3)
+        result = arr.median(axis=0, skipna=skipna)
+        expected = type(arr)._from_sequence([NaT, NaT, NaT], dtype=arr.dtype)
+        tm.assert_equal(result, expected)
+
+        result = arr.median(axis=1, skipna=skipna)
+        expected = type(arr)._from_sequence([], dtype=arr.dtype)
+        tm.assert_equal(result, expected)
+
+    def test_median(self, arr1d):
+        arr = arr1d
+
+        result = arr.median()
+        assert result == arr[0]
+        result = arr.median(skipna=False)
+        assert result is NaT
+
+        result = arr.dropna().median(skipna=False)
+        assert result == arr[0]
+
+        result = arr.median(axis=0)
+        assert result == arr[0]
+
+    def test_median_axis(self, arr1d):
+        arr = arr1d
+        assert arr.median(axis=0) == arr.median()
+        assert arr.median(axis=0, skipna=False) is NaT
+
+        msg = r"abs\(axis\) must be less than ndim"
+        with pytest.raises(ValueError, match=msg):
+            arr.median(axis=1)
+
+    @pytest.mark.filterwarnings("ignore:All-NaN slice encountered:RuntimeWarning")
+    def test_median_2d(self, arr1d):
+        arr = arr1d.reshape(1, -1)
+
+        # axis = None
+        assert arr.median() == arr1d.median()
+        assert arr.median(skipna=False) is NaT
+
+        # axis = 0
+        result = arr.median(axis=0)
+        expected = arr1d
+        tm.assert_equal(result, expected)
+
+        # Since column 3 is all-NaT, we get NaT there with or without skipna
+        result = arr.median(axis=0, skipna=False)
+        expected = arr1d
+        tm.assert_equal(result, expected)
+
+        # axis = 1
+        result = arr.median(axis=1)
+        expected = type(arr)._from_sequence([arr1d.median()], dtype=arr.dtype)
+        tm.assert_equal(result, expected)
+
+        result = arr.median(axis=1, skipna=False)
+        expected = type(arr)._from_sequence([NaT], dtype=arr.dtype)
+        tm.assert_equal(result, expected)
+
+    def test_mean(self, arr1d):
+        arr = arr1d
+
+        # manually verified result
+        expected = arr[0] + 0.4 * pd.Timedelta(days=1)
+
+        result = arr.mean()
+        assert result == expected
+        result = arr.mean(skipna=False)
+        assert result is NaT
+
+        result = arr.dropna().mean(skipna=False)
+        assert result == expected
+
+        result = arr.mean(axis=0)
+        assert result == expected
+
+    def test_mean_2d(self):
+        dti = pd.date_range("2016-01-01", periods=6, tz="US/Pacific")
+        dta = dti._data.reshape(3, 2)
+
+        result = dta.mean(axis=0)
+        expected = dta[1]
+        tm.assert_datetime_array_equal(result, expected)
+
+        result = dta.mean(axis=1)
+        expected = dta[:, 0] + pd.Timedelta(hours=12)
+        tm.assert_datetime_array_equal(result, expected)
+
+        result = dta.mean(axis=None)
+        expected = dti.mean()
+        assert result == expected
+
+    @pytest.mark.parametrize("skipna", [True, False])
+    def test_mean_empty(self, arr1d, skipna):
+        arr = arr1d[:0]
+
+        assert arr.mean(skipna=skipna) is NaT
+
+        arr2d = arr.reshape(0, 3)
+        result = arr2d.mean(axis=0, skipna=skipna)
+        expected = DatetimeArray._from_sequence([NaT, NaT, NaT], dtype=arr.dtype)
+        tm.assert_datetime_array_equal(result, expected)
+
+        result = arr2d.mean(axis=1, skipna=skipna)
+        expected = arr  # i.e. 1D, empty
+        tm.assert_datetime_array_equal(result, expected)
+
+        result = arr2d.mean(axis=None, skipna=skipna)
+        assert result is NaT
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/conftest.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/conftest.py
new file mode 100644
index 0000000000000000000000000000000000000000..5e971c66029d5ba90ecaa5eb3437246f1548557a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/conftest.py
@@ -0,0 +1,48 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas.core.arrays.floating import (
+    Float32Dtype,
+    Float64Dtype,
+)
+
+
+@pytest.fixture(params=[Float32Dtype, Float64Dtype])
+def dtype(request):
+    """Parametrized fixture returning a float 'dtype'"""
+    return request.param()
+
+
+@pytest.fixture
+def data(dtype):
+    """Fixture returning 'data' array according to parametrized float 'dtype'"""
+    return pd.array(
+        list(np.arange(0.1, 0.9, 0.1))
+        + [pd.NA]
+        + list(np.arange(1, 9.8, 0.1))
+        + [pd.NA]
+        + [9.9, 10.0],
+        dtype=dtype,
+    )
+
+
+@pytest.fixture
+def data_missing(dtype):
+    """
+    Fixture returning array with missing data according to parametrized float
+    'dtype'.
+    """
+    return pd.array([np.nan, 0.1], dtype=dtype)
+
+
+@pytest.fixture(params=["data", "data_missing"])
+def all_data(request, data, data_missing):
+    """Parametrized fixture returning 'data' or 'data_missing' float arrays.
+
+    Used to test dtype conversion with and without missing values.
+    """
+    if request.param == "data":
+        return data
+    elif request.param == "data_missing":
+        return data_missing
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_arithmetic.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_arithmetic.py
new file mode 100644
index 0000000000000000000000000000000000000000..009fac4c2f5ed4af079024aea35f60337f85989b
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_arithmetic.py
@@ -0,0 +1,240 @@
+import operator
+
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import FloatingArray
+
+# Basic test for the arithmetic array ops
+# -----------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "opname, exp",
+    [
+        ("add", [1.1, 2.2, None, None, 5.5]),
+        ("mul", [0.1, 0.4, None, None, 2.5]),
+        ("sub", [0.9, 1.8, None, None, 4.5]),
+        ("truediv", [10.0, 10.0, None, None, 10.0]),
+        ("floordiv", [9.0, 9.0, None, None, 10.0]),
+        ("mod", [0.1, 0.2, None, None, 0.0]),
+    ],
+    ids=["add", "mul", "sub", "div", "floordiv", "mod"],
+)
+def test_array_op(dtype, opname, exp):
+    a = pd.array([1.0, 2.0, None, 4.0, 5.0], dtype=dtype)
+    b = pd.array([0.1, 0.2, 0.3, None, 0.5], dtype=dtype)
+
+    op = getattr(operator, opname)
+
+    result = op(a, b)
+    expected = pd.array(exp, dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("zero, negative", [(0, False), (0.0, False), (-0.0, True)])
+def test_divide_by_zero(dtype, zero, negative):
+    # TODO pending NA/NaN discussion
+    # https://github.com/pandas-dev/pandas/issues/32265/
+    a = pd.array([0, 1, -1, None], dtype=dtype)
+    result = a / zero
+    expected = FloatingArray(
+        np.array([np.nan, np.inf, -np.inf, np.nan], dtype=dtype.numpy_dtype),
+        np.array([False, False, False, True]),
+    )
+    if negative:
+        expected *= -1
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_pow_scalar(dtype):
+    a = pd.array([-1, 0, 1, None, 2], dtype=dtype)
+    result = a**0
+    expected = pd.array([1, 1, 1, 1, 1], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**1
+    expected = pd.array([-1, 0, 1, None, 2], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**pd.NA
+    expected = pd.array([None, None, 1, None, None], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**np.nan
+    # TODO np.nan should be converted to pd.NA / missing before operation?
+    expected = FloatingArray(
+        np.array([np.nan, np.nan, 1, np.nan, np.nan], dtype=dtype.numpy_dtype),
+        mask=a._mask,
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    # reversed
+    a = a[1:]  # Can't raise integers to negative powers.
+
+    result = 0**a
+    expected = pd.array([1, 0, None, 0], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = 1**a
+    expected = pd.array([1, 1, 1, 1], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = pd.NA**a
+    expected = pd.array([1, None, None, None], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = np.nan**a
+    expected = FloatingArray(
+        np.array([1, np.nan, np.nan, np.nan], dtype=dtype.numpy_dtype), mask=a._mask
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_pow_array(dtype):
+    a = pd.array([0, 0, 0, 1, 1, 1, None, None, None], dtype=dtype)
+    b = pd.array([0, 1, None, 0, 1, None, 0, 1, None], dtype=dtype)
+    result = a**b
+    expected = pd.array([1, 0, None, 1, 1, 1, 1, None, None], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_rpow_one_to_na():
+    # https://github.com/pandas-dev/pandas/issues/22022
+    # https://github.com/pandas-dev/pandas/issues/29997
+    arr = pd.array([np.nan, np.nan], dtype="Float64")
+    result = np.array([1.0, 2.0]) ** arr
+    expected = pd.array([1.0, np.nan], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("other", [0, 0.5])
+def test_arith_zero_dim_ndarray(other):
+    arr = pd.array([1, None, 2], dtype="Float64")
+    result = arr + np.array(other)
+    expected = arr + other
+    tm.assert_equal(result, expected)
+
+
+# Test generic characteristics / errors
+# -----------------------------------------------------------------------------
+
+
+def test_error_invalid_values(data, all_arithmetic_operators):
+    op = all_arithmetic_operators
+    s = pd.Series(data)
+    ops = getattr(s, op)
+
+    # invalid scalars
+    msg = "|".join(
+        [
+            r"can only perform ops with numeric values",
+            r"FloatingArray cannot perform the operation mod",
+            "unsupported operand type",
+            "not all arguments converted during string formatting",
+            "can't multiply sequence by non-int of type 'float'",
+            "ufunc 'subtract' cannot use operands with types dtype",
+            r"can only concatenate str \(not \"float\"\) to str",
+            "ufunc '.*' not supported for the input types, and the inputs could not",
+            "ufunc '.*' did not contain a loop with signature matching types",
+            "Concatenation operation is not implemented for NumPy arrays",
+            "has no kernel",
+            "not implemented",
+            "not supported for dtype",
+            "Can only string multiply by an integer",
+        ]
+    )
+    with pytest.raises(TypeError, match=msg):
+        ops("foo")
+    with pytest.raises(TypeError, match=msg):
+        ops(pd.Timestamp("20180101"))
+
+    # invalid array-likes
+    with pytest.raises(TypeError, match=msg):
+        ops(pd.Series("foo", index=s.index))
+
+    msg = "|".join(
+        [
+            "can only perform ops with numeric values",
+            "cannot perform .* with this index type: DatetimeArray",
+            "Addition/subtraction of integers and integer-arrays "
+            "with DatetimeArray is no longer supported. *",
+            "unsupported operand type",
+            "not all arguments converted during string formatting",
+            "can't multiply sequence by non-int of type 'float'",
+            "ufunc 'subtract' cannot use operands with types dtype",
+            (
+                "ufunc 'add' cannot use operands with types "
+                rf"dtype\('{tm.ENDIAN}M8\[ns\]'\)"
+            ),
+            r"ufunc 'add' cannot use operands with types dtype\('float\d{2}'\)",
+            "cannot subtract DatetimeArray from ndarray",
+            "has no kernel",
+            "not implemented",
+            "not supported for dtype",
+        ]
+    )
+    with pytest.raises(TypeError, match=msg):
+        ops(pd.Series(pd.date_range("20180101", periods=len(s))))
+
+
+# Various
+# -----------------------------------------------------------------------------
+
+
+def test_cross_type_arithmetic():
+    df = pd.DataFrame(
+        {
+            "A": pd.array([1, 2, np.nan], dtype="Float64"),
+            "B": pd.array([1, np.nan, 3], dtype="Float32"),
+            "C": np.array([1, 2, 3], dtype="float64"),
+        }
+    )
+
+    result = df.A + df.C
+    expected = pd.Series([2, 4, np.nan], dtype="Float64")
+    tm.assert_series_equal(result, expected)
+
+    result = (df.A + df.C) * 3 == 12
+    expected = pd.Series([False, True, None], dtype="boolean")
+    tm.assert_series_equal(result, expected)
+
+    result = df.A + df.B
+    expected = pd.Series([2, np.nan, np.nan], dtype="Float64")
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "source, neg_target, abs_target",
+    [
+        ([1.1, 2.2, 3.3], [-1.1, -2.2, -3.3], [1.1, 2.2, 3.3]),
+        ([1.1, 2.2, None], [-1.1, -2.2, None], [1.1, 2.2, None]),
+        ([-1.1, 0.0, 1.1], [1.1, 0.0, -1.1], [1.1, 0.0, 1.1]),
+    ],
+)
+def test_unary_float_operators(float_ea_dtype, source, neg_target, abs_target):
+    # GH38794
+    dtype = float_ea_dtype
+    arr = pd.array(source, dtype=dtype)
+    neg_result, pos_result, abs_result = -arr, +arr, abs(arr)
+    neg_target = pd.array(neg_target, dtype=dtype)
+    abs_target = pd.array(abs_target, dtype=dtype)
+
+    tm.assert_extension_array_equal(neg_result, neg_target)
+    tm.assert_extension_array_equal(pos_result, arr)
+    assert not tm.shares_memory(pos_result, arr)
+    tm.assert_extension_array_equal(abs_result, abs_target)
+
+
+def test_bitwise(dtype):
+    left = pd.array([1, None, 3, 4], dtype=dtype)
+    right = pd.array([None, 3, 5, 4], dtype=dtype)
+
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left | right
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left & right
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left ^ right
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_astype.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_astype.py
new file mode 100644
index 0000000000000000000000000000000000000000..752ebe194ffcfdccf491d22320a8edcae5a8adab
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_astype.py
@@ -0,0 +1,135 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+def test_astype():
+    # with missing values
+    arr = pd.array([0.1, 0.2, None], dtype="Float64")
+
+    with pytest.raises(ValueError, match="cannot convert NA to integer"):
+        arr.astype("int64")
+
+    with pytest.raises(ValueError, match="cannot convert float NaN to bool"):
+        arr.astype("bool")
+
+    result = arr.astype("float64")
+    expected = np.array([0.1, 0.2, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    # no missing values
+    arr = pd.array([0.0, 1.0, 0.5], dtype="Float64")
+    result = arr.astype("int64")
+    expected = np.array([0, 1, 0], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.astype("bool")
+    expected = np.array([False, True, True], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_astype_to_floating_array():
+    # astype to FloatingArray
+    arr = pd.array([0.0, 1.0, None], dtype="Float64")
+
+    result = arr.astype("Float64")
+    tm.assert_extension_array_equal(result, arr)
+    result = arr.astype(pd.Float64Dtype())
+    tm.assert_extension_array_equal(result, arr)
+    result = arr.astype("Float32")
+    expected = pd.array([0.0, 1.0, None], dtype="Float32")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_astype_to_boolean_array():
+    # astype to BooleanArray
+    arr = pd.array([0.0, 1.0, None], dtype="Float64")
+
+    result = arr.astype("boolean")
+    expected = pd.array([False, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
+    result = arr.astype(pd.BooleanDtype())
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_astype_to_integer_array():
+    # astype to IntegerArray
+    arr = pd.array([0.0, 1.5, None], dtype="Float64")
+
+    result = arr.astype("Int64")
+    expected = pd.array([0, 1, None], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_astype_str(using_infer_string):
+    a = pd.array([0.1, 0.2, None], dtype="Float64")
+
+    if using_infer_string:
+        expected = pd.array(["0.1", "0.2", None], dtype=pd.StringDtype(na_value=np.nan))
+
+        tm.assert_extension_array_equal(a.astype(str), expected)
+        tm.assert_extension_array_equal(a.astype("str"), expected)
+    else:
+        expected = np.array(["0.1", "0.2", ""], dtype="U32")
+
+        tm.assert_numpy_array_equal(a.astype(str), expected)
+        tm.assert_numpy_array_equal(a.astype("str"), expected)
+
+
+def test_astype_copy():
+    arr = pd.array([0.1, 0.2, None], dtype="Float64")
+    orig = pd.array([0.1, 0.2, None], dtype="Float64")
+
+    # copy=True -> ensure both data and mask are actual copies
+    result = arr.astype("Float64", copy=True)
+    assert result is not arr
+    assert not tm.shares_memory(result, arr)
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, orig)
+    result[0] = pd.NA
+    tm.assert_extension_array_equal(arr, orig)
+
+    # copy=False
+    result = arr.astype("Float64", copy=False)
+    assert result is arr
+    assert np.shares_memory(result._data, arr._data)
+    assert np.shares_memory(result._mask, arr._mask)
+    result[0] = 10
+    assert arr[0] == 10
+    result[0] = pd.NA
+    assert arr[0] is pd.NA
+
+    # astype to different dtype -> always needs a copy -> even with copy=False
+    # we need to ensure that also the mask is actually copied
+    arr = pd.array([0.1, 0.2, None], dtype="Float64")
+    orig = pd.array([0.1, 0.2, None], dtype="Float64")
+
+    result = arr.astype("Float32", copy=False)
+    assert not tm.shares_memory(result, arr)
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, orig)
+    result[0] = pd.NA
+    tm.assert_extension_array_equal(arr, orig)
+
+
+def test_astype_object(dtype):
+    arr = pd.array([1.0, pd.NA], dtype=dtype)
+
+    result = arr.astype(object)
+    expected = np.array([1.0, pd.NA], dtype=object)
+    tm.assert_numpy_array_equal(result, expected)
+    # check exact element types
+    assert isinstance(result[0], float)
+    assert result[1] is pd.NA
+
+
+def test_Float64_conversion():
+    # GH#40729
+    testseries = pd.Series(["1", "2", "3", "4"], dtype="object")
+    result = testseries.astype(pd.Float64Dtype())
+
+    expected = pd.Series([1.0, 2.0, 3.0, 4.0], dtype=pd.Float64Dtype())
+
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_comparison.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_comparison.py
new file mode 100644
index 0000000000000000000000000000000000000000..a429649f1ce1dc10fc9610faa73a81dd94255b37
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_comparison.py
@@ -0,0 +1,65 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import FloatingArray
+from pandas.tests.arrays.masked_shared import (
+    ComparisonOps,
+    NumericOps,
+)
+
+
+class TestComparisonOps(NumericOps, ComparisonOps):
+    @pytest.mark.parametrize("other", [True, False, pd.NA, -1.0, 0.0, 1])
+    def test_scalar(self, other, comparison_op, dtype):
+        ComparisonOps.test_scalar(self, other, comparison_op, dtype)
+
+    def test_compare_with_integerarray(self, comparison_op):
+        op = comparison_op
+        a = pd.array([0, 1, None] * 3, dtype="Int64")
+        b = pd.array([0] * 3 + [1] * 3 + [None] * 3, dtype="Float64")
+        other = b.astype("Int64")
+        expected = op(a, other)
+        result = op(a, b)
+        tm.assert_extension_array_equal(result, expected)
+        expected = op(other, a)
+        result = op(b, a)
+        tm.assert_extension_array_equal(result, expected)
+
+
+def test_equals():
+    # GH-30652
+    # equals is generally tested in /tests/extension/base/methods, but this
+    # specifically tests that two arrays of the same class but different dtype
+    # do not evaluate equal
+    a1 = pd.array([1, 2, None], dtype="Float64")
+    a2 = pd.array([1, 2, None], dtype="Float32")
+    assert a1.equals(a2) is False
+
+
+def test_equals_nan_vs_na():
+    # GH#44382
+
+    mask = np.zeros(3, dtype=bool)
+    data = np.array([1.0, np.nan, 3.0], dtype=np.float64)
+
+    left = FloatingArray(data, mask)
+    assert left.equals(left)
+    tm.assert_extension_array_equal(left, left)
+
+    assert left.equals(left.copy())
+    assert left.equals(FloatingArray(data.copy(), mask.copy()))
+
+    mask2 = np.array([False, True, False], dtype=bool)
+    data2 = np.array([1.0, 2.0, 3.0], dtype=np.float64)
+    right = FloatingArray(data2, mask2)
+    assert right.equals(right)
+    tm.assert_extension_array_equal(right, right)
+
+    assert not left.equals(right)
+
+    # with mask[1] = True, the only difference is data[1], which should
+    #  not matter for equals
+    mask[1] = True
+    assert left.equals(right)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_concat.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_concat.py
new file mode 100644
index 0000000000000000000000000000000000000000..2174a834aa959b88d899971f83247258a94476e3
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_concat.py
@@ -0,0 +1,20 @@
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "to_concat_dtypes, result_dtype",
+    [
+        (["Float64", "Float64"], "Float64"),
+        (["Float32", "Float64"], "Float64"),
+        (["Float32", "Float32"], "Float32"),
+    ],
+)
+def test_concat_series(to_concat_dtypes, result_dtype):
+    result = pd.concat([pd.Series([1, 2, pd.NA], dtype=t) for t in to_concat_dtypes])
+    expected = pd.concat([pd.Series([1, 2, pd.NA], dtype=object)] * 2).astype(
+        result_dtype
+    )
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_construction.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_construction.py
new file mode 100644
index 0000000000000000000000000000000000000000..4007ee6b415c9b0f21f580f6240ed85ba1889781
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_construction.py
@@ -0,0 +1,204 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import FloatingArray
+from pandas.core.arrays.floating import (
+    Float32Dtype,
+    Float64Dtype,
+)
+
+
+def test_uses_pandas_na():
+    a = pd.array([1, None], dtype=Float64Dtype())
+    assert a[1] is pd.NA
+
+
+def test_floating_array_constructor():
+    values = np.array([1, 2, 3, 4], dtype="float64")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = FloatingArray(values, mask)
+    expected = pd.array([1, 2, 3, np.nan], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+    tm.assert_numpy_array_equal(result._data, values)
+    tm.assert_numpy_array_equal(result._mask, mask)
+
+    msg = r".* should be .* numpy array. Use the 'pd.array' function instead"
+    with pytest.raises(TypeError, match=msg):
+        FloatingArray(values.tolist(), mask)
+
+    with pytest.raises(TypeError, match=msg):
+        FloatingArray(values, mask.tolist())
+
+    with pytest.raises(TypeError, match=msg):
+        FloatingArray(values.astype(int), mask)
+
+    msg = r"__init__\(\) missing 1 required positional argument: 'mask'"
+    with pytest.raises(TypeError, match=msg):
+        FloatingArray(values)
+
+
+def test_floating_array_disallows_float16():
+    # GH#44715
+    arr = np.array([1, 2], dtype=np.float16)
+    mask = np.array([False, False])
+
+    msg = "FloatingArray does not support np.float16 dtype"
+    with pytest.raises(TypeError, match=msg):
+        FloatingArray(arr, mask)
+
+
+def test_floating_array_disallows_Float16_dtype(request):
+    # GH#44715
+    with pytest.raises(TypeError, match="data type 'Float16' not understood"):
+        pd.array([1.0, 2.0], dtype="Float16")
+
+
+def test_floating_array_constructor_copy():
+    values = np.array([1, 2, 3, 4], dtype="float64")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = FloatingArray(values, mask)
+    assert result._data is values
+    assert result._mask is mask
+
+    result = FloatingArray(values, mask, copy=True)
+    assert result._data is not values
+    assert result._mask is not mask
+
+
+def test_to_array():
+    result = pd.array([0.1, 0.2, 0.3, 0.4])
+    expected = pd.array([0.1, 0.2, 0.3, 0.4], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "a, b",
+    [
+        ([1, None], [1, pd.NA]),
+        ([None], [pd.NA]),
+        ([None, np.nan], [pd.NA, pd.NA]),
+        ([1, np.nan], [1, pd.NA]),
+        ([np.nan], [pd.NA]),
+    ],
+)
+def test_to_array_none_is_nan(a, b):
+    result = pd.array(a, dtype="Float64")
+    expected = pd.array(b, dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_to_array_mixed_integer_float():
+    result = pd.array([1, 2.0])
+    expected = pd.array([1.0, 2.0], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = pd.array([1, None, 2.0])
+    expected = pd.array([1.0, None, 2.0], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        ["foo", "bar"],
+        "foo",
+        1,
+        1.0,
+        pd.date_range("20130101", periods=2),
+        np.array(["foo"]),
+        [[1, 2], [3, 4]],
+        [np.nan, {"a": 1}],
+        # GH#44514 all-NA case used to get quietly swapped out before checking ndim
+        np.array([pd.NA] * 6, dtype=object).reshape(3, 2),
+    ],
+)
+def test_to_array_error(values):
+    # error in converting existing arrays to FloatingArray
+    msg = "|".join(
+        [
+            "cannot be converted to FloatingDtype",
+            "values must be a 1D list-like",
+            "Cannot pass scalar",
+            r"float\(\) argument must be a string or a (real )?number, not 'dict'",
+            "could not convert string to float: 'foo'",
+            r"could not convert string to float: np\.str_\('foo'\)",
+        ]
+    )
+    with pytest.raises((TypeError, ValueError), match=msg):
+        pd.array(values, dtype="Float64")
+
+
+@pytest.mark.parametrize("values", [["1", "2", None], ["1.5", "2", None]])
+def test_construct_from_float_strings(values):
+    # see also test_to_integer_array_str
+    expected = pd.array([float(values[0]), 2, None], dtype="Float64")
+
+    res = pd.array(values, dtype="Float64")
+    tm.assert_extension_array_equal(res, expected)
+
+    res = FloatingArray._from_sequence(values)
+    tm.assert_extension_array_equal(res, expected)
+
+
+def test_to_array_inferred_dtype():
+    # if values has dtype -> respect it
+    result = pd.array(np.array([1, 2], dtype="float32"))
+    assert result.dtype == Float32Dtype()
+
+    # if values have no dtype -> always float64
+    result = pd.array([1.0, 2.0])
+    assert result.dtype == Float64Dtype()
+
+
+def test_to_array_dtype_keyword():
+    result = pd.array([1, 2], dtype="Float32")
+    assert result.dtype == Float32Dtype()
+
+    # if values has dtype -> override it
+    result = pd.array(np.array([1, 2], dtype="float32"), dtype="Float64")
+    assert result.dtype == Float64Dtype()
+
+
+def test_to_array_integer():
+    result = pd.array([1, 2], dtype="Float64")
+    expected = pd.array([1.0, 2.0], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    # for integer dtypes, the itemsize is not preserved
+    # TODO can we specify "floating" in general?
+    result = pd.array(np.array([1, 2], dtype="int32"), dtype="Float64")
+    assert result.dtype == Float64Dtype()
+
+
+@pytest.mark.parametrize(
+    "bool_values, values, target_dtype, expected_dtype",
+    [
+        ([False, True], [0, 1], Float64Dtype(), Float64Dtype()),
+        ([False, True], [0, 1], "Float64", Float64Dtype()),
+        ([False, True, np.nan], [0, 1, np.nan], Float64Dtype(), Float64Dtype()),
+    ],
+)
+def test_to_array_bool(bool_values, values, target_dtype, expected_dtype):
+    result = pd.array(bool_values, dtype=target_dtype)
+    assert result.dtype == expected_dtype
+    expected = pd.array(values, dtype=target_dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_series_from_float(data):
+    # construct from our dtype & string dtype
+    dtype = data.dtype
+
+    # from float
+    expected = pd.Series(data)
+    result = pd.Series(data.to_numpy(na_value=np.nan, dtype="float"), dtype=str(dtype))
+    tm.assert_series_equal(result, expected)
+
+    # from list
+    expected = pd.Series(data)
+    result = pd.Series(np.array(data).tolist(), dtype=str(dtype))
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_contains.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_contains.py
new file mode 100644
index 0000000000000000000000000000000000000000..956642697bf3285e5c661c43047a5f0dafa83144
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_contains.py
@@ -0,0 +1,12 @@
+import numpy as np
+
+import pandas as pd
+
+
+def test_contains_nan():
+    # GH#52840
+    arr = pd.array(range(5)) / 0
+
+    assert np.isnan(arr._data[0])
+    assert not arr.isna()[0]
+    assert np.nan in arr
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_function.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_function.py
new file mode 100644
index 0000000000000000000000000000000000000000..40fd66fd049a621138c2cda074a08a1a94967bb5
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_function.py
@@ -0,0 +1,194 @@
+import numpy as np
+import pytest
+
+from pandas.compat import IS64
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize("ufunc", [np.abs, np.sign])
+# np.sign emits a warning with nans, 
+@pytest.mark.filterwarnings("ignore:invalid value encountered in sign:RuntimeWarning")
+def test_ufuncs_single(ufunc):
+    a = pd.array([1, 2, -3, np.nan], dtype="Float64")
+    result = ufunc(a)
+    expected = pd.array(ufunc(a.astype(float)), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    s = pd.Series(a)
+    result = ufunc(s)
+    expected = pd.Series(expected)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("ufunc", [np.log, np.exp, np.sin, np.cos, np.sqrt])
+def test_ufuncs_single_float(ufunc):
+    a = pd.array([1.0, 0.2, 3.0, np.nan], dtype="Float64")
+    with np.errstate(invalid="ignore"):
+        result = ufunc(a)
+        expected = pd.array(ufunc(a.astype(float)), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    s = pd.Series(a)
+    with np.errstate(invalid="ignore"):
+        result = ufunc(s)
+        expected = pd.Series(ufunc(s.astype(float)), dtype="Float64")
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("ufunc", [np.add, np.subtract])
+def test_ufuncs_binary_float(ufunc):
+    # two FloatingArrays
+    a = pd.array([1, 0.2, -3, np.nan], dtype="Float64")
+    result = ufunc(a, a)
+    expected = pd.array(ufunc(a.astype(float), a.astype(float)), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    # FloatingArray with numpy array
+    arr = np.array([1, 2, 3, 4])
+    result = ufunc(a, arr)
+    expected = pd.array(ufunc(a.astype(float), arr), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(arr, a)
+    expected = pd.array(ufunc(arr, a.astype(float)), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    # FloatingArray with scalar
+    result = ufunc(a, 1)
+    expected = pd.array(ufunc(a.astype(float), 1), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(1, a)
+    expected = pd.array(ufunc(1, a.astype(float)), dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("values", [[0, 1], [0, None]])
+def test_ufunc_reduce_raises(values):
+    arr = pd.array(values, dtype="Float64")
+
+    res = np.add.reduce(arr)
+    expected = arr.sum(skipna=False)
+    tm.assert_almost_equal(res, expected)
+
+
+@pytest.mark.skipif(not IS64, reason="GH 36579: fail on 32-bit system")
+@pytest.mark.parametrize(
+    "pandasmethname, kwargs",
+    [
+        ("var", {"ddof": 0}),
+        ("var", {"ddof": 1}),
+        ("std", {"ddof": 0}),
+        ("std", {"ddof": 1}),
+        ("kurtosis", {}),
+        ("skew", {}),
+        ("sem", {}),
+    ],
+)
+def test_stat_method(pandasmethname, kwargs):
+    s = pd.Series(data=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6, np.nan, np.nan], dtype="Float64")
+    pandasmeth = getattr(s, pandasmethname)
+    result = pandasmeth(**kwargs)
+    s2 = pd.Series(data=[0.1, 0.2, 0.3, 0.4, 0.5, 0.6], dtype="float64")
+    pandasmeth = getattr(s2, pandasmethname)
+    expected = pandasmeth(**kwargs)
+    assert expected == result
+
+
+def test_value_counts_na():
+    arr = pd.array([0.1, 0.2, 0.1, pd.NA], dtype="Float64")
+    result = arr.value_counts(dropna=False)
+    idx = pd.Index([0.1, 0.2, pd.NA], dtype=arr.dtype)
+    assert idx.dtype == arr.dtype
+    expected = pd.Series([2, 1, 1], index=idx, dtype="Int64", name="count")
+    tm.assert_series_equal(result, expected)
+
+    result = arr.value_counts(dropna=True)
+    expected = pd.Series([2, 1], index=idx[:-1], dtype="Int64", name="count")
+    tm.assert_series_equal(result, expected)
+
+
+def test_value_counts_empty():
+    ser = pd.Series([], dtype="Float64")
+    result = ser.value_counts()
+    idx = pd.Index([], dtype="Float64")
+    assert idx.dtype == "Float64"
+    expected = pd.Series([], index=idx, dtype="Int64", name="count")
+    tm.assert_series_equal(result, expected)
+
+
+def test_value_counts_with_normalize():
+    ser = pd.Series([0.1, 0.2, 0.1, pd.NA], dtype="Float64")
+    result = ser.value_counts(normalize=True)
+    expected = pd.Series([2, 1], index=ser[:2], dtype="Float64", name="proportion") / 3
+    assert expected.index.dtype == ser.dtype
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("min_count", [0, 4])
+def test_floating_array_sum(skipna, min_count, dtype):
+    arr = pd.array([1, 2, 3, None], dtype=dtype)
+    result = arr.sum(skipna=skipna, min_count=min_count)
+    if skipna and min_count == 0:
+        assert result == 6.0
+    else:
+        assert result is pd.NA
+
+
+@pytest.mark.parametrize(
+    "values, expected", [([1, 2, 3], 6.0), ([1, 2, 3, None], 6.0), ([None], 0.0)]
+)
+def test_floating_array_numpy_sum(values, expected):
+    arr = pd.array(values, dtype="Float64")
+    result = np.sum(arr)
+    assert result == expected
+
+
+@pytest.mark.parametrize("op", ["sum", "min", "max", "prod"])
+def test_preserve_dtypes(op):
+    df = pd.DataFrame(
+        {
+            "A": ["a", "b", "b"],
+            "B": [1, None, 3],
+            "C": pd.array([0.1, None, 3.0], dtype="Float64"),
+        }
+    )
+
+    # op
+    result = getattr(df.C, op)()
+    assert isinstance(result, np.float64)
+
+    # groupby
+    result = getattr(df.groupby("A"), op)()
+
+    expected = pd.DataFrame(
+        {"B": np.array([1.0, 3.0]), "C": pd.array([0.1, 3], dtype="Float64")},
+        index=pd.Index(["a", "b"], name="A"),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("method", ["min", "max"])
+def test_floating_array_min_max(skipna, method, dtype):
+    arr = pd.array([0.0, 1.0, None], dtype=dtype)
+    func = getattr(arr, method)
+    result = func(skipna=skipna)
+    if skipna:
+        assert result == (0 if method == "min" else 1)
+    else:
+        assert result is pd.NA
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("min_count", [0, 9])
+def test_floating_array_prod(skipna, min_count, dtype):
+    arr = pd.array([1.0, 2.0, None], dtype=dtype)
+    result = arr.prod(skipna=skipna, min_count=min_count)
+    if skipna and min_count == 0:
+        assert result == 2
+    else:
+        assert result is pd.NA
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_repr.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_repr.py
new file mode 100644
index 0000000000000000000000000000000000000000..ea2cdd4fab86ada36d6d5804204c4a479a3e1603
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_repr.py
@@ -0,0 +1,47 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas.core.arrays.floating import (
+    Float32Dtype,
+    Float64Dtype,
+)
+
+
+def test_dtypes(dtype):
+    # smoke tests on auto dtype construction
+
+    np.dtype(dtype.type).kind == "f"
+    assert dtype.name is not None
+
+
+@pytest.mark.parametrize(
+    "dtype, expected",
+    [(Float32Dtype(), "Float32Dtype()"), (Float64Dtype(), "Float64Dtype()")],
+)
+def test_repr_dtype(dtype, expected):
+    assert repr(dtype) == expected
+
+
+def test_repr_array():
+    result = repr(pd.array([1.0, None, 3.0]))
+    expected = "\n[1.0, , 3.0]\nLength: 3, dtype: Float64"
+    assert result == expected
+
+
+def test_repr_array_long():
+    data = pd.array([1.0, 2.0, None] * 1000)
+    expected = """
+[ 1.0,  2.0, ,  1.0,  2.0, ,  1.0,  2.0, ,  1.0,
+ ...
+ ,  1.0,  2.0, ,  1.0,  2.0, ,  1.0,  2.0, ]
+Length: 3000, dtype: Float64"""
+    result = repr(data)
+    assert result == expected
+
+
+def test_frame_repr(data_missing):
+    df = pd.DataFrame({"A": data_missing})
+    result = repr(df)
+    expected = "      A\n0  \n1   0.1"
+    assert result == expected
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_to_numpy.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_to_numpy.py
new file mode 100644
index 0000000000000000000000000000000000000000..e954cecba417afd71059a35f7506c650eb780373
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/floating/test_to_numpy.py
@@ -0,0 +1,132 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import FloatingArray
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy(box):
+    con = pd.Series if box else pd.array
+
+    # default (with or without missing values) -> object dtype
+    arr = con([0.1, 0.2, 0.3], dtype="Float64")
+    result = arr.to_numpy()
+    expected = np.array([0.1, 0.2, 0.3], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([0.1, 0.2, None], dtype="Float64")
+    result = arr.to_numpy()
+    expected = np.array([0.1, 0.2, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_float(box):
+    con = pd.Series if box else pd.array
+
+    # no missing values -> can convert to float, otherwise raises
+    arr = con([0.1, 0.2, 0.3], dtype="Float64")
+    result = arr.to_numpy(dtype="float64")
+    expected = np.array([0.1, 0.2, 0.3], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([0.1, 0.2, None], dtype="Float64")
+    result = arr.to_numpy(dtype="float64")
+    expected = np.array([0.1, 0.2, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype="float64", na_value=np.nan)
+    expected = np.array([0.1, 0.2, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_int(box):
+    con = pd.Series if box else pd.array
+
+    # no missing values -> can convert to int, otherwise raises
+    arr = con([1.0, 2.0, 3.0], dtype="Float64")
+    result = arr.to_numpy(dtype="int64")
+    expected = np.array([1, 2, 3], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    arr = con([1.0, 2.0, None], dtype="Float64")
+    with pytest.raises(ValueError, match="cannot convert to 'int64'-dtype"):
+        result = arr.to_numpy(dtype="int64")
+
+    # automatic casting (floors the values)
+    arr = con([0.1, 0.9, 1.1], dtype="Float64")
+    result = arr.to_numpy(dtype="int64")
+    expected = np.array([0, 0, 1], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_na_value(box):
+    con = pd.Series if box else pd.array
+
+    arr = con([0.0, 1.0, None], dtype="Float64")
+    result = arr.to_numpy(dtype=object, na_value=None)
+    expected = np.array([0.0, 1.0, None], dtype="object")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype=bool, na_value=False)
+    expected = np.array([False, True, False], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = arr.to_numpy(dtype="int64", na_value=-99)
+    expected = np.array([0, 1, -99], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_to_numpy_na_value_with_nan():
+    # array with both NaN and NA -> only fill NA with `na_value`
+    arr = FloatingArray(np.array([0.0, np.nan, 0.0]), np.array([False, False, True]))
+    result = arr.to_numpy(dtype="float64", na_value=-1)
+    expected = np.array([0.0, np.nan, -1.0], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("dtype", ["float64", "float32", "int32", "int64", "bool"])
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_dtype(box, dtype):
+    con = pd.Series if box else pd.array
+    arr = con([0.0, 1.0], dtype="Float64")
+
+    result = arr.to_numpy(dtype=dtype)
+    expected = np.array([0, 1], dtype=dtype)
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("dtype", ["int32", "int64", "bool"])
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_na_raises(box, dtype):
+    con = pd.Series if box else pd.array
+    arr = con([0.0, 1.0, None], dtype="Float64")
+    with pytest.raises(ValueError, match=dtype):
+        arr.to_numpy(dtype=dtype)
+
+
+@pytest.mark.parametrize("box", [True, False], ids=["series", "array"])
+def test_to_numpy_string(box, dtype):
+    con = pd.Series if box else pd.array
+    arr = con([0.0, 1.0, None], dtype="Float64")
+
+    result = arr.to_numpy(dtype="str")
+    expected = np.array([0.0, 1.0, pd.NA], dtype=f"{tm.ENDIAN}U32")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_to_numpy_copy():
+    # to_numpy can be zero-copy if no missing values
+    arr = pd.array([0.1, 0.2, 0.3], dtype="Float64")
+    result = arr.to_numpy(dtype="float64")
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, pd.array([10, 0.2, 0.3], dtype="Float64"))
+
+    arr = pd.array([0.1, 0.2, 0.3], dtype="Float64")
+    result = arr.to_numpy(dtype="float64", copy=True)
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, pd.array([0.1, 0.2, 0.3], dtype="Float64"))
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/conftest.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/conftest.py
new file mode 100644
index 0000000000000000000000000000000000000000..f73400dfe689e91c4c2b457c4be1a0a41380fd6a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/conftest.py
@@ -0,0 +1,68 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    Int16Dtype,
+    Int32Dtype,
+    Int64Dtype,
+    UInt8Dtype,
+    UInt16Dtype,
+    UInt32Dtype,
+    UInt64Dtype,
+)
+
+
+@pytest.fixture(
+    params=[
+        Int8Dtype,
+        Int16Dtype,
+        Int32Dtype,
+        Int64Dtype,
+        UInt8Dtype,
+        UInt16Dtype,
+        UInt32Dtype,
+        UInt64Dtype,
+    ]
+)
+def dtype(request):
+    """Parametrized fixture returning integer 'dtype'"""
+    return request.param()
+
+
+@pytest.fixture
+def data(dtype):
+    """
+    Fixture returning 'data' array with valid and missing values according to
+    parametrized integer 'dtype'.
+
+    Used to test dtype conversion with and without missing values.
+    """
+    return pd.array(
+        list(range(8)) + [np.nan] + list(range(10, 98)) + [np.nan] + [99, 100],
+        dtype=dtype,
+    )
+
+
+@pytest.fixture
+def data_missing(dtype):
+    """
+    Fixture returning array with exactly one NaN and one valid integer,
+    according to parametrized integer 'dtype'.
+
+    Used to test dtype conversion with and without missing values.
+    """
+    return pd.array([np.nan, 1], dtype=dtype)
+
+
+@pytest.fixture(params=["data", "data_missing"])
+def all_data(request, data, data_missing):
+    """Parametrized fixture returning 'data' or 'data_missing' integer arrays.
+
+    Used to test dtype conversion with and without missing values.
+    """
+    if request.param == "data":
+        return data
+    elif request.param == "data_missing":
+        return data_missing
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_arithmetic.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_arithmetic.py
new file mode 100644
index 0000000000000000000000000000000000000000..9fbea2022c87b36a44acdab9e42ac36f0018ae06
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_arithmetic.py
@@ -0,0 +1,345 @@
+import operator
+
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core import ops
+from pandas.core.arrays import FloatingArray
+
+# Basic test for the arithmetic array ops
+# -----------------------------------------------------------------------------
+
+
+@pytest.mark.parametrize(
+    "opname, exp",
+    [("add", [1, 3, None, None, 9]), ("mul", [0, 2, None, None, 20])],
+    ids=["add", "mul"],
+)
+def test_add_mul(dtype, opname, exp):
+    a = pd.array([0, 1, None, 3, 4], dtype=dtype)
+    b = pd.array([1, 2, 3, None, 5], dtype=dtype)
+
+    # array / array
+    expected = pd.array(exp, dtype=dtype)
+
+    op = getattr(operator, opname)
+    result = op(a, b)
+    tm.assert_extension_array_equal(result, expected)
+
+    op = getattr(ops, "r" + opname)
+    result = op(a, b)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_sub(dtype):
+    a = pd.array([1, 2, 3, None, 5], dtype=dtype)
+    b = pd.array([0, 1, None, 3, 4], dtype=dtype)
+
+    result = a - b
+    expected = pd.array([1, 1, None, None, 1], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_div(dtype):
+    a = pd.array([1, 2, 3, None, 5], dtype=dtype)
+    b = pd.array([0, 1, None, 3, 4], dtype=dtype)
+
+    result = a / b
+    expected = pd.array([np.inf, 2, None, None, 1.25], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("zero, negative", [(0, False), (0.0, False), (-0.0, True)])
+def test_divide_by_zero(zero, negative):
+    # https://github.com/pandas-dev/pandas/issues/27398, GH#22793
+    a = pd.array([0, 1, -1, None], dtype="Int64")
+    result = a / zero
+    expected = FloatingArray(
+        np.array([np.nan, np.inf, -np.inf, 1], dtype="float64"),
+        np.array([False, False, False, True]),
+    )
+    if negative:
+        expected *= -1
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_floordiv(dtype):
+    a = pd.array([1, 2, 3, None, 5], dtype=dtype)
+    b = pd.array([0, 1, None, 3, 4], dtype=dtype)
+
+    result = a // b
+    # Series op sets 1//0 to np.inf, which IntegerArray does not do (yet)
+    expected = pd.array([0, 2, None, None, 1], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_floordiv_by_int_zero_no_mask(any_int_ea_dtype):
+    # GH 48223: Aligns with non-masked floordiv
+    # but differs from numpy
+    # https://github.com/pandas-dev/pandas/issues/30188#issuecomment-564452740
+    ser = pd.Series([0, 1], dtype=any_int_ea_dtype)
+    result = 1 // ser
+    expected = pd.Series([np.inf, 1.0], dtype="Float64")
+    tm.assert_series_equal(result, expected)
+
+    ser_non_nullable = ser.astype(ser.dtype.numpy_dtype)
+    result = 1 // ser_non_nullable
+    expected = expected.astype(np.float64)
+    tm.assert_series_equal(result, expected)
+
+
+def test_mod(dtype):
+    a = pd.array([1, 2, 3, None, 5], dtype=dtype)
+    b = pd.array([0, 1, None, 3, 4], dtype=dtype)
+
+    result = a % b
+    expected = pd.array([0, 0, None, None, 1], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_pow_scalar():
+    a = pd.array([-1, 0, 1, None, 2], dtype="Int64")
+    result = a**0
+    expected = pd.array([1, 1, 1, 1, 1], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**1
+    expected = pd.array([-1, 0, 1, None, 2], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**pd.NA
+    expected = pd.array([None, None, 1, None, None], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = a**np.nan
+    expected = FloatingArray(
+        np.array([np.nan, np.nan, 1, np.nan, np.nan], dtype="float64"),
+        np.array([False, False, False, True, False]),
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    # reversed
+    a = a[1:]  # Can't raise integers to negative powers.
+
+    result = 0**a
+    expected = pd.array([1, 0, None, 0], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = 1**a
+    expected = pd.array([1, 1, 1, 1], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = pd.NA**a
+    expected = pd.array([1, None, None, None], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = np.nan**a
+    expected = FloatingArray(
+        np.array([1, np.nan, np.nan, np.nan], dtype="float64"),
+        np.array([False, False, True, False]),
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_pow_array():
+    a = pd.array([0, 0, 0, 1, 1, 1, None, None, None])
+    b = pd.array([0, 1, None, 0, 1, None, 0, 1, None])
+    result = a**b
+    expected = pd.array([1, 0, None, 1, 1, 1, 1, None, None])
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_rpow_one_to_na():
+    # https://github.com/pandas-dev/pandas/issues/22022
+    # https://github.com/pandas-dev/pandas/issues/29997
+    arr = pd.array([np.nan, np.nan], dtype="Int64")
+    result = np.array([1.0, 2.0]) ** arr
+    expected = pd.array([1.0, np.nan], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("other", [0, 0.5])
+def test_numpy_zero_dim_ndarray(other):
+    arr = pd.array([1, None, 2])
+    result = arr + np.array(other)
+    expected = arr + other
+    tm.assert_equal(result, expected)
+
+
+# Test generic characteristics / errors
+# -----------------------------------------------------------------------------
+
+
+def test_error_invalid_values(data, all_arithmetic_operators):
+    op = all_arithmetic_operators
+    s = pd.Series(data)
+    ops = getattr(s, op)
+
+    # invalid scalars
+    with tm.external_error_raised(TypeError):
+        ops("foo")
+    with tm.external_error_raised(TypeError):
+        ops(pd.Timestamp("20180101"))
+
+    # invalid array-likes
+    str_ser = pd.Series("foo", index=s.index)
+    # with pytest.raises(TypeError, match=msg):
+    if all_arithmetic_operators in [
+        "__mul__",
+        "__rmul__",
+    ]:  # (data[~data.isna()] >= 0).all():
+        res = ops(str_ser)
+        expected = pd.Series(["foo" * x for x in data], index=s.index)
+        expected = expected.fillna(np.nan)
+        # TODO: doing this fillna to keep tests passing as we make
+        #  assert_almost_equal stricter, but the expected with pd.NA seems
+        #  more-correct than np.nan here.
+        tm.assert_series_equal(res, expected)
+    else:
+        with tm.external_error_raised(TypeError):
+            ops(str_ser)
+
+    with tm.external_error_raised(TypeError):
+        ops(pd.Series(pd.date_range("20180101", periods=len(s))))
+
+
+# Various
+# -----------------------------------------------------------------------------
+
+
+# TODO test unsigned overflow
+
+
+def test_arith_coerce_scalar(data, all_arithmetic_operators):
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    s = pd.Series(data)
+    other = 0.01
+
+    result = op(s, other)
+    expected = op(s.astype(float), other)
+    expected = expected.astype("Float64")
+
+    # rmod results in NaN that wasn't NA in original nullable Series -> unmask it
+    if all_arithmetic_operators == "__rmod__":
+        mask = (s == 0).fillna(False).to_numpy(bool)
+        expected.array._mask[mask] = False
+
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("other", [1.0, np.array(1.0)])
+def test_arithmetic_conversion(all_arithmetic_operators, other):
+    # if we have a float operand we should have a float result
+    # if that is equal to an integer
+    op = tm.get_op_from_name(all_arithmetic_operators)
+
+    s = pd.Series([1, 2, 3], dtype="Int64")
+    result = op(s, other)
+    assert result.dtype == "Float64"
+
+
+def test_cross_type_arithmetic():
+    df = pd.DataFrame(
+        {
+            "A": pd.Series([1, 2, np.nan], dtype="Int64"),
+            "B": pd.Series([1, np.nan, 3], dtype="UInt8"),
+            "C": [1, 2, 3],
+        }
+    )
+
+    result = df.A + df.C
+    expected = pd.Series([2, 4, np.nan], dtype="Int64")
+    tm.assert_series_equal(result, expected)
+
+    result = (df.A + df.C) * 3 == 12
+    expected = pd.Series([False, True, None], dtype="boolean")
+    tm.assert_series_equal(result, expected)
+
+    result = df.A + df.B
+    expected = pd.Series([2, np.nan, np.nan], dtype="Int64")
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("op", ["mean"])
+def test_reduce_to_float(op):
+    # some reduce ops always return float, even if the result
+    # is a rounded number
+    df = pd.DataFrame(
+        {
+            "A": ["a", "b", "b"],
+            "B": [1, None, 3],
+            "C": pd.array([1, None, 3], dtype="Int64"),
+        }
+    )
+
+    # op
+    result = getattr(df.C, op)()
+    assert isinstance(result, float)
+
+    # groupby
+    result = getattr(df.groupby("A"), op)()
+
+    expected = pd.DataFrame(
+        {"B": np.array([1.0, 3.0]), "C": pd.array([1, 3], dtype="Float64")},
+        index=pd.Index(["a", "b"], name="A"),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "source, neg_target, abs_target",
+    [
+        ([1, 2, 3], [-1, -2, -3], [1, 2, 3]),
+        ([1, 2, None], [-1, -2, None], [1, 2, None]),
+        ([-1, 0, 1], [1, 0, -1], [1, 0, 1]),
+    ],
+)
+def test_unary_int_operators(any_signed_int_ea_dtype, source, neg_target, abs_target):
+    dtype = any_signed_int_ea_dtype
+    arr = pd.array(source, dtype=dtype)
+    neg_result, pos_result, abs_result = -arr, +arr, abs(arr)
+    neg_target = pd.array(neg_target, dtype=dtype)
+    abs_target = pd.array(abs_target, dtype=dtype)
+
+    tm.assert_extension_array_equal(neg_result, neg_target)
+    tm.assert_extension_array_equal(pos_result, arr)
+    assert not tm.shares_memory(pos_result, arr)
+    tm.assert_extension_array_equal(abs_result, abs_target)
+
+
+def test_values_multiplying_large_series_by_NA():
+    # GH#33701
+
+    result = pd.NA * pd.Series(np.zeros(10001))
+    expected = pd.Series([pd.NA] * 10001)
+
+    tm.assert_series_equal(result, expected)
+
+
+def test_bitwise(dtype):
+    left = pd.array([1, None, 3, 4], dtype=dtype)
+    right = pd.array([None, 3, 5, 4], dtype=dtype)
+
+    result = left | right
+    expected = pd.array([None, None, 3 | 5, 4 | 4], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = left & right
+    expected = pd.array([None, None, 3 & 5, 4 & 4], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    result = left ^ right
+    expected = pd.array([None, None, 3 ^ 5, 4 ^ 4], dtype=dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+    # TODO: desired behavior when operating with boolean?  defer?
+
+    floats = right.astype("Float64")
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left | floats
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left & floats
+    with pytest.raises(TypeError, match="unsupported operand type"):
+        left ^ floats
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_comparison.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_comparison.py
new file mode 100644
index 0000000000000000000000000000000000000000..568b0b087bf1db9610960dba12ea2e0bab8f1729
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_comparison.py
@@ -0,0 +1,39 @@
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.tests.arrays.masked_shared import (
+    ComparisonOps,
+    NumericOps,
+)
+
+
+class TestComparisonOps(NumericOps, ComparisonOps):
+    @pytest.mark.parametrize("other", [True, False, pd.NA, -1, 0, 1])
+    def test_scalar(self, other, comparison_op, dtype):
+        ComparisonOps.test_scalar(self, other, comparison_op, dtype)
+
+    def test_compare_to_int(self, dtype, comparison_op):
+        # GH 28930
+        op_name = f"__{comparison_op.__name__}__"
+        s1 = pd.Series([1, None, 3], dtype=dtype)
+        s2 = pd.Series([1, None, 3], dtype="float")
+
+        method = getattr(s1, op_name)
+        result = method(2)
+
+        method = getattr(s2, op_name)
+        expected = method(2).astype("boolean")
+        expected[s2.isna()] = pd.NA
+
+        tm.assert_series_equal(result, expected)
+
+
+def test_equals():
+    # GH-30652
+    # equals is generally tested in /tests/extension/base/methods, but this
+    # specifically tests that two arrays of the same class but different dtype
+    # do not evaluate equal
+    a1 = pd.array([1, 2, None], dtype="Int64")
+    a2 = pd.array([1, 2, None], dtype="Int32")
+    assert a1.equals(a2) is False
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_concat.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_concat.py
new file mode 100644
index 0000000000000000000000000000000000000000..feba574da548fd597c25103f67821145bccec9ed
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_concat.py
@@ -0,0 +1,69 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "to_concat_dtypes, result_dtype",
+    [
+        (["Int64", "Int64"], "Int64"),
+        (["UInt64", "UInt64"], "UInt64"),
+        (["Int8", "Int8"], "Int8"),
+        (["Int8", "Int16"], "Int16"),
+        (["UInt8", "Int8"], "Int16"),
+        (["Int32", "UInt32"], "Int64"),
+        (["Int64", "UInt64"], "Float64"),
+        (["Int64", "boolean"], "object"),
+        (["UInt8", "boolean"], "object"),
+    ],
+)
+def test_concat_series(to_concat_dtypes, result_dtype):
+    # we expect the same dtypes as we would get with non-masked inputs,
+    #  just masked where available.
+
+    result = pd.concat([pd.Series([0, 1, pd.NA], dtype=t) for t in to_concat_dtypes])
+    expected = pd.concat([pd.Series([0, 1, pd.NA], dtype=object)] * 2).astype(
+        result_dtype
+    )
+    tm.assert_series_equal(result, expected)
+
+    # order doesn't matter for result
+    result = pd.concat(
+        [pd.Series([0, 1, pd.NA], dtype=t) for t in to_concat_dtypes[::-1]]
+    )
+    expected = pd.concat([pd.Series([0, 1, pd.NA], dtype=object)] * 2).astype(
+        result_dtype
+    )
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "to_concat_dtypes, result_dtype",
+    [
+        (["Int64", "int64"], "Int64"),
+        (["UInt64", "uint64"], "UInt64"),
+        (["Int8", "int8"], "Int8"),
+        (["Int8", "int16"], "Int16"),
+        (["UInt8", "int8"], "Int16"),
+        (["Int32", "uint32"], "Int64"),
+        (["Int64", "uint64"], "Float64"),
+        (["Int64", "bool"], "object"),
+        (["UInt8", "bool"], "object"),
+    ],
+)
+def test_concat_series_with_numpy(to_concat_dtypes, result_dtype):
+    # we expect the same dtypes as we would get with non-masked inputs,
+    #  just masked where available.
+
+    s1 = pd.Series([0, 1, pd.NA], dtype=to_concat_dtypes[0])
+    s2 = pd.Series(np.array([0, 1], dtype=to_concat_dtypes[1]))
+    result = pd.concat([s1, s2], ignore_index=True)
+    expected = pd.Series([0, 1, pd.NA, 0, 1], dtype=object).astype(result_dtype)
+    tm.assert_series_equal(result, expected)
+
+    # order doesn't matter for result
+    result = pd.concat([s2, s1], ignore_index=True)
+    expected = pd.Series([0, 1, 0, 1, pd.NA], dtype=object).astype(result_dtype)
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_construction.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_construction.py
new file mode 100644
index 0000000000000000000000000000000000000000..64fe40e53a9d287b6240a908b7ed9d0cf7ec1396
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_construction.py
@@ -0,0 +1,245 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.api.types import is_integer
+from pandas.core.arrays import IntegerArray
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    Int32Dtype,
+    Int64Dtype,
+)
+
+
+@pytest.fixture(params=[pd.array, IntegerArray._from_sequence])
+def constructor(request):
+    """Fixture returning parametrized IntegerArray from given sequence.
+
+    Used to test dtype conversions.
+    """
+    return request.param
+
+
+def test_uses_pandas_na():
+    a = pd.array([1, None], dtype=Int64Dtype())
+    assert a[1] is pd.NA
+
+
+def test_from_dtype_from_float(data):
+    # construct from our dtype & string dtype
+    dtype = data.dtype
+
+    # from float
+    expected = pd.Series(data)
+    result = pd.Series(data.to_numpy(na_value=np.nan, dtype="float"), dtype=str(dtype))
+    tm.assert_series_equal(result, expected)
+
+    # from int / list
+    expected = pd.Series(data)
+    result = pd.Series(np.array(data).tolist(), dtype=str(dtype))
+    tm.assert_series_equal(result, expected)
+
+    # from int / array
+    expected = pd.Series(data).dropna().reset_index(drop=True)
+    dropped = np.array(data.dropna()).astype(np.dtype(dtype.type))
+    result = pd.Series(dropped, dtype=str(dtype))
+    tm.assert_series_equal(result, expected)
+
+
+def test_conversions(data_missing):
+    # astype to object series
+    df = pd.DataFrame({"A": data_missing})
+    result = df["A"].astype("object")
+    expected = pd.Series(np.array([pd.NA, 1], dtype=object), name="A")
+    tm.assert_series_equal(result, expected)
+
+    # convert to object ndarray
+    # we assert that we are exactly equal
+    # including type conversions of scalars
+    result = df["A"].astype("object").values
+    expected = np.array([pd.NA, 1], dtype=object)
+    tm.assert_numpy_array_equal(result, expected)
+
+    for r, e in zip(result, expected):
+        if pd.isnull(r):
+            assert pd.isnull(e)
+        elif is_integer(r):
+            assert r == e
+            assert is_integer(e)
+        else:
+            assert r == e
+            assert type(r) == type(e)
+
+
+def test_integer_array_constructor():
+    values = np.array([1, 2, 3, 4], dtype="int64")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = IntegerArray(values, mask)
+    expected = pd.array([1, 2, 3, np.nan], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    msg = r".* should be .* numpy array. Use the 'pd.array' function instead"
+    with pytest.raises(TypeError, match=msg):
+        IntegerArray(values.tolist(), mask)
+
+    with pytest.raises(TypeError, match=msg):
+        IntegerArray(values, mask.tolist())
+
+    with pytest.raises(TypeError, match=msg):
+        IntegerArray(values.astype(float), mask)
+    msg = r"__init__\(\) missing 1 required positional argument: 'mask'"
+    with pytest.raises(TypeError, match=msg):
+        IntegerArray(values)
+
+
+def test_integer_array_constructor_copy():
+    values = np.array([1, 2, 3, 4], dtype="int64")
+    mask = np.array([False, False, False, True], dtype="bool")
+
+    result = IntegerArray(values, mask)
+    assert result._data is values
+    assert result._mask is mask
+
+    result = IntegerArray(values, mask, copy=True)
+    assert result._data is not values
+    assert result._mask is not mask
+
+
+@pytest.mark.parametrize(
+    "a, b",
+    [
+        ([1, None], [1, np.nan]),
+        ([None], [np.nan]),
+        ([None, np.nan], [np.nan, np.nan]),
+        ([np.nan, np.nan], [np.nan, np.nan]),
+    ],
+)
+def test_to_integer_array_none_is_nan(a, b):
+    result = pd.array(a, dtype="Int64")
+    expected = pd.array(b, dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "values",
+    [
+        ["foo", "bar"],
+        "foo",
+        1,
+        1.0,
+        pd.date_range("20130101", periods=2),
+        np.array(["foo"]),
+        [[1, 2], [3, 4]],
+        [np.nan, {"a": 1}],
+    ],
+)
+def test_to_integer_array_error(values):
+    # error in converting existing arrays to IntegerArrays
+    msg = "|".join(
+        [
+            r"cannot be converted to IntegerDtype",
+            r"invalid literal for int\(\) with base 10:",
+            r"values must be a 1D list-like",
+            r"Cannot pass scalar",
+            r"int\(\) argument must be a string",
+        ]
+    )
+    with pytest.raises((ValueError, TypeError), match=msg):
+        pd.array(values, dtype="Int64")
+
+    with pytest.raises((ValueError, TypeError), match=msg):
+        IntegerArray._from_sequence(values)
+
+
+def test_to_integer_array_inferred_dtype(constructor):
+    # if values has dtype -> respect it
+    result = constructor(np.array([1, 2], dtype="int8"))
+    assert result.dtype == Int8Dtype()
+    result = constructor(np.array([1, 2], dtype="int32"))
+    assert result.dtype == Int32Dtype()
+
+    # if values have no dtype -> always int64
+    result = constructor([1, 2])
+    assert result.dtype == Int64Dtype()
+
+
+def test_to_integer_array_dtype_keyword(constructor):
+    result = constructor([1, 2], dtype="Int8")
+    assert result.dtype == Int8Dtype()
+
+    # if values has dtype -> override it
+    result = constructor(np.array([1, 2], dtype="int8"), dtype="Int32")
+    assert result.dtype == Int32Dtype()
+
+
+def test_to_integer_array_float():
+    result = IntegerArray._from_sequence([1.0, 2.0], dtype="Int64")
+    expected = pd.array([1, 2], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    with pytest.raises(TypeError, match="cannot safely cast non-equivalent"):
+        IntegerArray._from_sequence([1.5, 2.0], dtype="Int64")
+
+    # for float dtypes, the itemsize is not preserved
+    result = IntegerArray._from_sequence(
+        np.array([1.0, 2.0], dtype="float32"), dtype="Int64"
+    )
+    assert result.dtype == Int64Dtype()
+
+
+def test_to_integer_array_str():
+    result = IntegerArray._from_sequence(["1", "2", None], dtype="Int64")
+    expected = pd.array([1, 2, np.nan], dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    with pytest.raises(
+        ValueError, match=r"invalid literal for int\(\) with base 10: .*"
+    ):
+        IntegerArray._from_sequence(["1", "2", ""], dtype="Int64")
+
+    with pytest.raises(
+        ValueError, match=r"invalid literal for int\(\) with base 10: .*"
+    ):
+        IntegerArray._from_sequence(["1.5", "2.0"], dtype="Int64")
+
+
+@pytest.mark.parametrize(
+    "bool_values, int_values, target_dtype, expected_dtype",
+    [
+        ([False, True], [0, 1], Int64Dtype(), Int64Dtype()),
+        ([False, True], [0, 1], "Int64", Int64Dtype()),
+        ([False, True, np.nan], [0, 1, np.nan], Int64Dtype(), Int64Dtype()),
+    ],
+)
+def test_to_integer_array_bool(
+    constructor, bool_values, int_values, target_dtype, expected_dtype
+):
+    result = constructor(bool_values, dtype=target_dtype)
+    assert result.dtype == expected_dtype
+    expected = pd.array(int_values, dtype=target_dtype)
+    tm.assert_extension_array_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "values, to_dtype, result_dtype",
+    [
+        (np.array([1], dtype="int64"), None, Int64Dtype),
+        (np.array([1, np.nan]), None, Int64Dtype),
+        (np.array([1, np.nan]), "int8", Int8Dtype),
+    ],
+)
+def test_to_integer_array(values, to_dtype, result_dtype):
+    # convert existing arrays to IntegerArrays
+    result = IntegerArray._from_sequence(values, dtype=to_dtype)
+    assert result.dtype == result_dtype()
+    expected = pd.array(values, dtype=result_dtype())
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_integer_array_from_boolean():
+    # GH31104
+    expected = pd.array(np.array([True, False]), dtype="Int64")
+    result = pd.array(np.array([True, False], dtype=object), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_dtypes.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_dtypes.py
new file mode 100644
index 0000000000000000000000000000000000000000..90879d8bd30633246415acccd2d4d94e7c46124c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_dtypes.py
@@ -0,0 +1,301 @@
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.generic import ABCIndex
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    UInt32Dtype,
+)
+
+
+def test_dtypes(dtype):
+    # smoke tests on auto dtype construction
+
+    if dtype.is_signed_integer:
+        assert np.dtype(dtype.type).kind == "i"
+    else:
+        assert np.dtype(dtype.type).kind == "u"
+    assert dtype.name is not None
+
+
+@pytest.mark.parametrize("op", ["sum", "min", "max", "prod"])
+def test_preserve_dtypes(op):
+    # for ops that enable (mean would actually work here
+    # but generally it is a float return value)
+    df = pd.DataFrame(
+        {
+            "A": ["a", "b", "b"],
+            "B": [1, None, 3],
+            "C": pd.array([1, None, 3], dtype="Int64"),
+        }
+    )
+
+    # op
+    result = getattr(df.C, op)()
+    if op in {"sum", "prod", "min", "max"}:
+        assert isinstance(result, np.int64)
+    else:
+        assert isinstance(result, int)
+
+    # groupby
+    result = getattr(df.groupby("A"), op)()
+
+    expected = pd.DataFrame(
+        {"B": np.array([1.0, 3.0]), "C": pd.array([1, 3], dtype="Int64")},
+        index=pd.Index(["a", "b"], name="A"),
+    )
+    tm.assert_frame_equal(result, expected)
+
+
+def test_astype_nansafe():
+    # see gh-22343
+    arr = pd.array([np.nan, 1, 2], dtype="Int8")
+    msg = "cannot convert NA to integer"
+
+    with pytest.raises(ValueError, match=msg):
+        arr.astype("uint32")
+
+
+@pytest.mark.parametrize("dropna", [True, False])
+def test_construct_index(all_data, dropna):
+    # ensure that we do not coerce to different Index dtype or non-index
+
+    all_data = all_data[:10]
+    if dropna:
+        other = np.array(all_data[~all_data.isna()])
+    else:
+        other = all_data
+
+    result = pd.Index(pd.array(other, dtype=all_data.dtype))
+    expected = pd.Index(other, dtype=all_data.dtype)
+    assert all_data.dtype == expected.dtype  # dont coerce to object
+
+    tm.assert_index_equal(result, expected)
+
+
+@pytest.mark.parametrize("dropna", [True, False])
+def test_astype_index(all_data, dropna):
+    # as an int/uint index to Index
+
+    all_data = all_data[:10]
+    if dropna:
+        other = all_data[~all_data.isna()]
+    else:
+        other = all_data
+
+    dtype = all_data.dtype
+    idx = pd.Index(np.array(other))
+    assert isinstance(idx, ABCIndex)
+
+    result = idx.astype(dtype)
+    expected = idx.astype(object).astype(dtype)
+    tm.assert_index_equal(result, expected)
+
+
+def test_astype(all_data):
+    all_data = all_data[:10]
+
+    ints = all_data[~all_data.isna()]
+    mixed = all_data
+    dtype = Int8Dtype()
+
+    # coerce to same type - ints
+    s = pd.Series(ints)
+    result = s.astype(all_data.dtype)
+    expected = pd.Series(ints)
+    tm.assert_series_equal(result, expected)
+
+    # coerce to same other - ints
+    s = pd.Series(ints)
+    result = s.astype(dtype)
+    expected = pd.Series(ints, dtype=dtype)
+    tm.assert_series_equal(result, expected)
+
+    # coerce to same numpy_dtype - ints
+    s = pd.Series(ints)
+    result = s.astype(all_data.dtype.numpy_dtype)
+    expected = pd.Series(ints._data.astype(all_data.dtype.numpy_dtype))
+    tm.assert_series_equal(result, expected)
+
+    # coerce to same type - mixed
+    s = pd.Series(mixed)
+    result = s.astype(all_data.dtype)
+    expected = pd.Series(mixed)
+    tm.assert_series_equal(result, expected)
+
+    # coerce to same other - mixed
+    s = pd.Series(mixed)
+    result = s.astype(dtype)
+    expected = pd.Series(mixed, dtype=dtype)
+    tm.assert_series_equal(result, expected)
+
+    # coerce to same numpy_dtype - mixed
+    s = pd.Series(mixed)
+    msg = "cannot convert NA to integer"
+    with pytest.raises(ValueError, match=msg):
+        s.astype(all_data.dtype.numpy_dtype)
+
+    # coerce to object
+    s = pd.Series(mixed)
+    result = s.astype("object")
+    expected = pd.Series(np.asarray(mixed, dtype=object))
+    tm.assert_series_equal(result, expected)
+
+
+def test_astype_copy():
+    arr = pd.array([1, 2, 3, None], dtype="Int64")
+    orig = pd.array([1, 2, 3, None], dtype="Int64")
+
+    # copy=True -> ensure both data and mask are actual copies
+    result = arr.astype("Int64", copy=True)
+    assert result is not arr
+    assert not tm.shares_memory(result, arr)
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, orig)
+    result[0] = pd.NA
+    tm.assert_extension_array_equal(arr, orig)
+
+    # copy=False
+    result = arr.astype("Int64", copy=False)
+    assert result is arr
+    assert np.shares_memory(result._data, arr._data)
+    assert np.shares_memory(result._mask, arr._mask)
+    result[0] = 10
+    assert arr[0] == 10
+    result[0] = pd.NA
+    assert arr[0] is pd.NA
+
+    # astype to different dtype -> always needs a copy -> even with copy=False
+    # we need to ensure that also the mask is actually copied
+    arr = pd.array([1, 2, 3, None], dtype="Int64")
+    orig = pd.array([1, 2, 3, None], dtype="Int64")
+
+    result = arr.astype("Int32", copy=False)
+    assert not tm.shares_memory(result, arr)
+    result[0] = 10
+    tm.assert_extension_array_equal(arr, orig)
+    result[0] = pd.NA
+    tm.assert_extension_array_equal(arr, orig)
+
+
+def test_astype_to_larger_numpy():
+    a = pd.array([1, 2], dtype="Int32")
+    result = a.astype("int64")
+    expected = np.array([1, 2], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    a = pd.array([1, 2], dtype="UInt32")
+    result = a.astype("uint64")
+    expected = np.array([1, 2], dtype="uint64")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("dtype", [Int8Dtype(), "Int8", UInt32Dtype(), "UInt32"])
+def test_astype_specific_casting(dtype):
+    s = pd.Series([1, 2, 3], dtype="Int64")
+    result = s.astype(dtype)
+    expected = pd.Series([1, 2, 3], dtype=dtype)
+    tm.assert_series_equal(result, expected)
+
+    s = pd.Series([1, 2, 3, None], dtype="Int64")
+    result = s.astype(dtype)
+    expected = pd.Series([1, 2, 3, None], dtype=dtype)
+    tm.assert_series_equal(result, expected)
+
+
+def test_astype_floating():
+    arr = pd.array([1, 2, None], dtype="Int64")
+    result = arr.astype("Float64")
+    expected = pd.array([1.0, 2.0, None], dtype="Float64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_astype_dt64():
+    # GH#32435
+    arr = pd.array([1, 2, 3, pd.NA]) * 10**9
+
+    result = arr.astype("datetime64[ns]")
+
+    expected = np.array([1, 2, 3, "NaT"], dtype="M8[s]").astype("M8[ns]")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+def test_construct_cast_invalid(dtype):
+    msg = "cannot safely"
+    arr = [1.2, 2.3, 3.7]
+    with pytest.raises(TypeError, match=msg):
+        pd.array(arr, dtype=dtype)
+
+    with pytest.raises(TypeError, match=msg):
+        pd.Series(arr).astype(dtype)
+
+    arr = [1.2, 2.3, 3.7, np.nan]
+    with pytest.raises(TypeError, match=msg):
+        pd.array(arr, dtype=dtype)
+
+    with pytest.raises(TypeError, match=msg):
+        pd.Series(arr).astype(dtype)
+
+
+@pytest.mark.parametrize("in_series", [True, False])
+def test_to_numpy_na_nan(in_series):
+    a = pd.array([0, 1, None], dtype="Int64")
+    if in_series:
+        a = pd.Series(a)
+
+    result = a.to_numpy(dtype="float64", na_value=np.nan)
+    expected = np.array([0.0, 1.0, np.nan], dtype="float64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = a.to_numpy(dtype="int64", na_value=-1)
+    expected = np.array([0, 1, -1], dtype="int64")
+    tm.assert_numpy_array_equal(result, expected)
+
+    result = a.to_numpy(dtype="bool", na_value=False)
+    expected = np.array([False, True, False], dtype="bool")
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("in_series", [True, False])
+@pytest.mark.parametrize("dtype", ["int32", "int64", "bool"])
+def test_to_numpy_dtype(dtype, in_series):
+    a = pd.array([0, 1], dtype="Int64")
+    if in_series:
+        a = pd.Series(a)
+
+    result = a.to_numpy(dtype=dtype)
+    expected = np.array([0, 1], dtype=dtype)
+    tm.assert_numpy_array_equal(result, expected)
+
+
+@pytest.mark.parametrize("dtype", ["int64", "bool"])
+def test_to_numpy_na_raises(dtype):
+    a = pd.array([0, 1, None], dtype="Int64")
+    with pytest.raises(ValueError, match=dtype):
+        a.to_numpy(dtype=dtype)
+
+
+def test_astype_str(using_infer_string):
+    a = pd.array([1, 2, None], dtype="Int64")
+
+    if using_infer_string:
+        expected = pd.array(["1", "2", None], dtype=pd.StringDtype(na_value=np.nan))
+
+        tm.assert_extension_array_equal(a.astype(str), expected)
+        tm.assert_extension_array_equal(a.astype("str"), expected)
+    else:
+        expected = np.array(["1", "2", ""], dtype=f"{tm.ENDIAN}U21")
+
+        tm.assert_numpy_array_equal(a.astype(str), expected)
+        tm.assert_numpy_array_equal(a.astype("str"), expected)
+
+
+def test_astype_boolean():
+    # https://github.com/pandas-dev/pandas/issues/31102
+    a = pd.array([1, 0, -1, 2, None], dtype="Int64")
+    result = a.astype("boolean")
+    expected = pd.array([True, False, True, True, None], dtype="boolean")
+    tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_function.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_function.py
new file mode 100644
index 0000000000000000000000000000000000000000..d48b636a98feb94c5eaeee9eefbf5730fe9c6f79
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_function.py
@@ -0,0 +1,203 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import FloatingArray
+
+
+@pytest.mark.parametrize("ufunc", [np.abs, np.sign])
+# np.sign emits a warning with nans, 
+@pytest.mark.filterwarnings("ignore:invalid value encountered in sign:RuntimeWarning")
+def test_ufuncs_single_int(ufunc):
+    a = pd.array([1, 2, -3, np.nan])
+    result = ufunc(a)
+    expected = pd.array(ufunc(a.astype(float)), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    s = pd.Series(a)
+    result = ufunc(s)
+    expected = pd.Series(pd.array(ufunc(a.astype(float)), dtype="Int64"))
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("ufunc", [np.log, np.exp, np.sin, np.cos, np.sqrt])
+def test_ufuncs_single_float(ufunc):
+    a = pd.array([1, 2, -3, np.nan])
+    with np.errstate(invalid="ignore"):
+        result = ufunc(a)
+        expected = FloatingArray(ufunc(a.astype(float)), mask=a._mask)
+    tm.assert_extension_array_equal(result, expected)
+
+    s = pd.Series(a)
+    with np.errstate(invalid="ignore"):
+        result = ufunc(s)
+    expected = pd.Series(expected)
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("ufunc", [np.add, np.subtract])
+def test_ufuncs_binary_int(ufunc):
+    # two IntegerArrays
+    a = pd.array([1, 2, -3, np.nan])
+    result = ufunc(a, a)
+    expected = pd.array(ufunc(a.astype(float), a.astype(float)), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    # IntegerArray with numpy array
+    arr = np.array([1, 2, 3, 4])
+    result = ufunc(a, arr)
+    expected = pd.array(ufunc(a.astype(float), arr), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(arr, a)
+    expected = pd.array(ufunc(arr, a.astype(float)), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    # IntegerArray with scalar
+    result = ufunc(a, 1)
+    expected = pd.array(ufunc(a.astype(float), 1), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+    result = ufunc(1, a)
+    expected = pd.array(ufunc(1, a.astype(float)), dtype="Int64")
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_ufunc_binary_output():
+    a = pd.array([1, 2, np.nan])
+    result = np.modf(a)
+    expected = np.modf(a.to_numpy(na_value=np.nan, dtype="float"))
+    expected = (pd.array(expected[0]), pd.array(expected[1]))
+
+    assert isinstance(result, tuple)
+    assert len(result) == 2
+
+    for x, y in zip(result, expected):
+        tm.assert_extension_array_equal(x, y)
+
+
+@pytest.mark.parametrize("values", [[0, 1], [0, None]])
+def test_ufunc_reduce_raises(values):
+    arr = pd.array(values)
+
+    res = np.add.reduce(arr)
+    expected = arr.sum(skipna=False)
+    tm.assert_almost_equal(res, expected)
+
+
+@pytest.mark.parametrize(
+    "pandasmethname, kwargs",
+    [
+        ("var", {"ddof": 0}),
+        ("var", {"ddof": 1}),
+        ("std", {"ddof": 0}),
+        ("std", {"ddof": 1}),
+        ("kurtosis", {}),
+        ("skew", {}),
+        ("sem", {}),
+    ],
+)
+def test_stat_method(pandasmethname, kwargs):
+    s = pd.Series(data=[1, 2, 3, 4, 5, 6, np.nan, np.nan], dtype="Int64")
+    pandasmeth = getattr(s, pandasmethname)
+    result = pandasmeth(**kwargs)
+    s2 = pd.Series(data=[1, 2, 3, 4, 5, 6], dtype="Int64")
+    pandasmeth = getattr(s2, pandasmethname)
+    expected = pandasmeth(**kwargs)
+    assert expected == result
+
+
+def test_value_counts_na():
+    arr = pd.array([1, 2, 1, pd.NA], dtype="Int64")
+    result = arr.value_counts(dropna=False)
+    ex_index = pd.Index([1, 2, pd.NA], dtype="Int64")
+    assert ex_index.dtype == "Int64"
+    expected = pd.Series([2, 1, 1], index=ex_index, dtype="Int64", name="count")
+    tm.assert_series_equal(result, expected)
+
+    result = arr.value_counts(dropna=True)
+    expected = pd.Series([2, 1], index=arr[:2], dtype="Int64", name="count")
+    assert expected.index.dtype == arr.dtype
+    tm.assert_series_equal(result, expected)
+
+
+def test_value_counts_empty():
+    # https://github.com/pandas-dev/pandas/issues/33317
+    ser = pd.Series([], dtype="Int64")
+    result = ser.value_counts()
+    idx = pd.Index([], dtype=ser.dtype)
+    assert idx.dtype == ser.dtype
+    expected = pd.Series([], index=idx, dtype="Int64", name="count")
+    tm.assert_series_equal(result, expected)
+
+
+def test_value_counts_with_normalize():
+    # GH 33172
+    ser = pd.Series([1, 2, 1, pd.NA], dtype="Int64")
+    result = ser.value_counts(normalize=True)
+    expected = pd.Series([2, 1], index=ser[:2], dtype="Float64", name="proportion") / 3
+    assert expected.index.dtype == ser.dtype
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("min_count", [0, 4])
+def test_integer_array_sum(skipna, min_count, any_int_ea_dtype):
+    dtype = any_int_ea_dtype
+    arr = pd.array([1, 2, 3, None], dtype=dtype)
+    result = arr.sum(skipna=skipna, min_count=min_count)
+    if skipna and min_count == 0:
+        assert result == 6
+    else:
+        assert result is pd.NA
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("method", ["min", "max"])
+def test_integer_array_min_max(skipna, method, any_int_ea_dtype):
+    dtype = any_int_ea_dtype
+    arr = pd.array([0, 1, None], dtype=dtype)
+    func = getattr(arr, method)
+    result = func(skipna=skipna)
+    if skipna:
+        assert result == (0 if method == "min" else 1)
+    else:
+        assert result is pd.NA
+
+
+@pytest.mark.parametrize("skipna", [True, False])
+@pytest.mark.parametrize("min_count", [0, 9])
+def test_integer_array_prod(skipna, min_count, any_int_ea_dtype):
+    dtype = any_int_ea_dtype
+    arr = pd.array([1, 2, None], dtype=dtype)
+    result = arr.prod(skipna=skipna, min_count=min_count)
+    if skipna and min_count == 0:
+        assert result == 2
+    else:
+        assert result is pd.NA
+
+
+@pytest.mark.parametrize(
+    "values, expected", [([1, 2, 3], 6), ([1, 2, 3, None], 6), ([None], 0)]
+)
+def test_integer_array_numpy_sum(values, expected):
+    arr = pd.array(values, dtype="Int64")
+    result = np.sum(arr)
+    assert result == expected
+
+
+@pytest.mark.parametrize("op", ["sum", "prod", "min", "max"])
+def test_dataframe_reductions(op):
+    # https://github.com/pandas-dev/pandas/pull/32867
+    # ensure the integers are not cast to float during reductions
+    df = pd.DataFrame({"a": pd.array([1, 2], dtype="Int64")})
+    result = df.max()
+    assert isinstance(result["a"], np.int64)
+
+
+# TODO(jreback) - these need testing / are broken
+
+# shift
+
+# set_index (destroys type)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_indexing.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..4b953d699108b2aed1c992cf3a33f3013b298254
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_indexing.py
@@ -0,0 +1,19 @@
+import pandas as pd
+import pandas._testing as tm
+
+
+def test_array_setitem_nullable_boolean_mask():
+    # GH 31446
+    ser = pd.Series([1, 2], dtype="Int64")
+    result = ser.where(ser > 1)
+    expected = pd.Series([pd.NA, 2], dtype="Int64")
+    tm.assert_series_equal(result, expected)
+
+
+def test_array_setitem():
+    # GH 31446
+    arr = pd.Series([1, 2], dtype="Int64").array
+    arr[arr > 1] = 1
+
+    expected = pd.array([1, 1], dtype="Int64")
+    tm.assert_extension_array_equal(arr, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_reduction.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_reduction.py
new file mode 100644
index 0000000000000000000000000000000000000000..1c91cd25ba69ce207c6be3f6dd438a4ae4f37980
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_reduction.py
@@ -0,0 +1,123 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    DataFrame,
+    Series,
+    array,
+)
+import pandas._testing as tm
+
+
+@pytest.mark.parametrize(
+    "op, expected",
+    [
+        ["sum", np.int64(3)],
+        ["prod", np.int64(2)],
+        ["min", np.int64(1)],
+        ["max", np.int64(2)],
+        ["mean", np.float64(1.5)],
+        ["median", np.float64(1.5)],
+        ["var", np.float64(0.5)],
+        ["std", np.float64(0.5**0.5)],
+        ["skew", pd.NA],
+        ["kurt", pd.NA],
+        ["any", True],
+        ["all", True],
+    ],
+)
+def test_series_reductions(op, expected):
+    ser = Series([1, 2], dtype="Int64")
+    result = getattr(ser, op)()
+    tm.assert_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "op, expected",
+    [
+        ["sum", Series([3], index=["a"], dtype="Int64")],
+        ["prod", Series([2], index=["a"], dtype="Int64")],
+        ["min", Series([1], index=["a"], dtype="Int64")],
+        ["max", Series([2], index=["a"], dtype="Int64")],
+        ["mean", Series([1.5], index=["a"], dtype="Float64")],
+        ["median", Series([1.5], index=["a"], dtype="Float64")],
+        ["var", Series([0.5], index=["a"], dtype="Float64")],
+        ["std", Series([0.5**0.5], index=["a"], dtype="Float64")],
+        ["skew", Series([pd.NA], index=["a"], dtype="Float64")],
+        ["kurt", Series([pd.NA], index=["a"], dtype="Float64")],
+        ["any", Series([True], index=["a"], dtype="boolean")],
+        ["all", Series([True], index=["a"], dtype="boolean")],
+    ],
+)
+def test_dataframe_reductions(op, expected):
+    df = DataFrame({"a": array([1, 2], dtype="Int64")})
+    result = getattr(df, op)()
+    tm.assert_series_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "op, expected",
+    [
+        ["sum", array([1, 3], dtype="Int64")],
+        ["prod", array([1, 3], dtype="Int64")],
+        ["min", array([1, 3], dtype="Int64")],
+        ["max", array([1, 3], dtype="Int64")],
+        ["mean", array([1, 3], dtype="Float64")],
+        ["median", array([1, 3], dtype="Float64")],
+        ["var", array([pd.NA], dtype="Float64")],
+        ["std", array([pd.NA], dtype="Float64")],
+        ["skew", array([pd.NA], dtype="Float64")],
+        ["any", array([True, True], dtype="boolean")],
+        ["all", array([True, True], dtype="boolean")],
+    ],
+)
+def test_groupby_reductions(op, expected):
+    df = DataFrame(
+        {
+            "A": ["a", "b", "b"],
+            "B": array([1, None, 3], dtype="Int64"),
+        }
+    )
+    result = getattr(df.groupby("A"), op)()
+    expected = DataFrame(expected, index=pd.Index(["a", "b"], name="A"), columns=["B"])
+
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.mark.parametrize(
+    "op, expected",
+    [
+        ["sum", Series([4, 4], index=["B", "C"], dtype="Float64")],
+        ["prod", Series([3, 3], index=["B", "C"], dtype="Float64")],
+        ["min", Series([1, 1], index=["B", "C"], dtype="Float64")],
+        ["max", Series([3, 3], index=["B", "C"], dtype="Float64")],
+        ["mean", Series([2, 2], index=["B", "C"], dtype="Float64")],
+        ["median", Series([2, 2], index=["B", "C"], dtype="Float64")],
+        ["var", Series([2, 2], index=["B", "C"], dtype="Float64")],
+        ["std", Series([2**0.5, 2**0.5], index=["B", "C"], dtype="Float64")],
+        ["skew", Series([pd.NA, pd.NA], index=["B", "C"], dtype="Float64")],
+        ["kurt", Series([pd.NA, pd.NA], index=["B", "C"], dtype="Float64")],
+        ["any", Series([True, True, True], index=["A", "B", "C"], dtype="boolean")],
+        ["all", Series([True, True, True], index=["A", "B", "C"], dtype="boolean")],
+    ],
+)
+def test_mixed_reductions(op, expected):
+    df = DataFrame(
+        {
+            "A": ["a", "b", "b"],
+            "B": [1, None, 3],
+            "C": array([1, None, 3], dtype="Int64"),
+        }
+    )
+
+    # series
+    result = getattr(df.C, op)()
+    tm.assert_equal(result, expected["C"])
+
+    # frame
+    if op in ["any", "all"]:
+        result = getattr(df, op)()
+    else:
+        result = getattr(df, op)(numeric_only=True)
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_repr.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_repr.py
new file mode 100644
index 0000000000000000000000000000000000000000..168210eed5d06a461bbf42dd1e1fae3db0fd851c
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/integer/test_repr.py
@@ -0,0 +1,67 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas.core.arrays.integer import (
+    Int8Dtype,
+    Int16Dtype,
+    Int32Dtype,
+    Int64Dtype,
+    UInt8Dtype,
+    UInt16Dtype,
+    UInt32Dtype,
+    UInt64Dtype,
+)
+
+
+def test_dtypes(dtype):
+    # smoke tests on auto dtype construction
+
+    if dtype.is_signed_integer:
+        assert np.dtype(dtype.type).kind == "i"
+    else:
+        assert np.dtype(dtype.type).kind == "u"
+    assert dtype.name is not None
+
+
+@pytest.mark.parametrize(
+    "dtype, expected",
+    [
+        (Int8Dtype(), "Int8Dtype()"),
+        (Int16Dtype(), "Int16Dtype()"),
+        (Int32Dtype(), "Int32Dtype()"),
+        (Int64Dtype(), "Int64Dtype()"),
+        (UInt8Dtype(), "UInt8Dtype()"),
+        (UInt16Dtype(), "UInt16Dtype()"),
+        (UInt32Dtype(), "UInt32Dtype()"),
+        (UInt64Dtype(), "UInt64Dtype()"),
+    ],
+)
+def test_repr_dtype(dtype, expected):
+    assert repr(dtype) == expected
+
+
+def test_repr_array():
+    result = repr(pd.array([1, None, 3]))
+    expected = "\n[1, , 3]\nLength: 3, dtype: Int64"
+    assert result == expected
+
+
+def test_repr_array_long():
+    data = pd.array([1, 2, None] * 1000)
+    expected = (
+        "\n"
+        "[   1,    2, ,    1,    2, ,    1,    2, ,    1,\n"
+        " ...\n"
+        " ,    1,    2, ,    1,    2, ,    1,    2, ]\n"
+        "Length: 3000, dtype: Int64"
+    )
+    result = repr(data)
+    assert result == expected
+
+
+def test_frame_repr(data_missing):
+    df = pd.DataFrame({"A": data_missing})
+    result = repr(df)
+    expected = "      A\n0  \n1     1"
+    assert result == expected
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_astype.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_astype.py
new file mode 100644
index 0000000000000000000000000000000000000000..d7a2140f817f3a8e5689d001768cf5642118b105
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_astype.py
@@ -0,0 +1,28 @@
+import pytest
+
+from pandas import (
+    Categorical,
+    CategoricalDtype,
+    Index,
+    IntervalIndex,
+)
+import pandas._testing as tm
+
+
+class TestAstype:
+    @pytest.mark.parametrize("ordered", [True, False])
+    def test_astype_categorical_retains_ordered(self, ordered):
+        index = IntervalIndex.from_breaks(range(5))
+        arr = index._data
+
+        dtype = CategoricalDtype(None, ordered=ordered)
+
+        expected = Categorical(list(arr), ordered=ordered)
+        result = arr.astype(dtype)
+        assert result.ordered is ordered
+        tm.assert_categorical_equal(result, expected)
+
+        # test IntervalIndex.astype while we're at it.
+        result = index.astype(dtype)
+        expected = Index(expected)
+        tm.assert_index_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_formats.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_formats.py
new file mode 100644
index 0000000000000000000000000000000000000000..535efee51937473071c9490330eb68364769d5aa
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_formats.py
@@ -0,0 +1,13 @@
+from pandas.core.arrays import IntervalArray
+
+
+def test_repr():
+    # GH#25022
+    arr = IntervalArray.from_tuples([(0, 1), (1, 2)])
+    result = repr(arr)
+    expected = (
+        "\n"
+        "[(0, 1], (1, 2]]\n"
+        "Length: 2, dtype: interval[int64, right]"
+    )
+    assert result == expected
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval.py
new file mode 100644
index 0000000000000000000000000000000000000000..be4b2c3e7e74cddfaf8b2efa08879d3a6d8f1757
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval.py
@@ -0,0 +1,231 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+from pandas import (
+    Index,
+    Interval,
+    IntervalIndex,
+    Timedelta,
+    Timestamp,
+    date_range,
+    timedelta_range,
+)
+import pandas._testing as tm
+from pandas.core.arrays import IntervalArray
+
+
+@pytest.fixture(
+    params=[
+        (Index([0, 2, 4]), Index([1, 3, 5])),
+        (Index([0.0, 1.0, 2.0]), Index([1.0, 2.0, 3.0])),
+        (timedelta_range("0 days", periods=3), timedelta_range("1 day", periods=3)),
+        (date_range("20170101", periods=3), date_range("20170102", periods=3)),
+        (
+            date_range("20170101", periods=3, tz="US/Eastern"),
+            date_range("20170102", periods=3, tz="US/Eastern"),
+        ),
+    ],
+    ids=lambda x: str(x[0].dtype),
+)
+def left_right_dtypes(request):
+    """
+    Fixture for building an IntervalArray from various dtypes
+    """
+    return request.param
+
+
+class TestAttributes:
+    @pytest.mark.parametrize(
+        "left, right",
+        [
+            (0, 1),
+            (Timedelta("0 days"), Timedelta("1 day")),
+            (Timestamp("2018-01-01"), Timestamp("2018-01-02")),
+            (
+                Timestamp("2018-01-01", tz="US/Eastern"),
+                Timestamp("2018-01-02", tz="US/Eastern"),
+            ),
+        ],
+    )
+    @pytest.mark.parametrize("constructor", [IntervalArray, IntervalIndex])
+    def test_is_empty(self, constructor, left, right, closed):
+        # GH27219
+        tuples = [(left, left), (left, right), np.nan]
+        expected = np.array([closed != "both", False, False])
+        result = constructor.from_tuples(tuples, closed=closed).is_empty
+        tm.assert_numpy_array_equal(result, expected)
+
+
+class TestMethods:
+    @pytest.mark.parametrize("new_closed", ["left", "right", "both", "neither"])
+    def test_set_closed(self, closed, new_closed):
+        # GH 21670
+        array = IntervalArray.from_breaks(range(10), closed=closed)
+        result = array.set_closed(new_closed)
+        expected = IntervalArray.from_breaks(range(10), closed=new_closed)
+        tm.assert_extension_array_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [
+            Interval(0, 1, closed="right"),
+            IntervalArray.from_breaks([1, 2, 3, 4], closed="right"),
+        ],
+    )
+    def test_where_raises(self, other):
+        # GH#45768 The IntervalArray methods raises; the Series method coerces
+        ser = pd.Series(IntervalArray.from_breaks([1, 2, 3, 4], closed="left"))
+        mask = np.array([True, False, True])
+        match = "'value.closed' is 'right', expected 'left'."
+        with pytest.raises(ValueError, match=match):
+            ser.array._where(mask, other)
+
+        res = ser.where(mask, other=other)
+        expected = ser.astype(object).where(mask, other)
+        tm.assert_series_equal(res, expected)
+
+    def test_shift(self):
+        # https://github.com/pandas-dev/pandas/issues/31495, GH#22428, GH#31502
+        a = IntervalArray.from_breaks([1, 2, 3])
+        result = a.shift()
+        # int -> float
+        expected = IntervalArray.from_tuples([(np.nan, np.nan), (1.0, 2.0)])
+        tm.assert_interval_array_equal(result, expected)
+
+        msg = "can only insert Interval objects and NA into an IntervalArray"
+        with pytest.raises(TypeError, match=msg):
+            a.shift(1, fill_value=pd.NaT)
+
+    def test_shift_datetime(self):
+        # GH#31502, GH#31504
+        a = IntervalArray.from_breaks(date_range("2000", periods=4))
+        result = a.shift(2)
+        expected = a.take([-1, -1, 0], allow_fill=True)
+        tm.assert_interval_array_equal(result, expected)
+
+        result = a.shift(-1)
+        expected = a.take([1, 2, -1], allow_fill=True)
+        tm.assert_interval_array_equal(result, expected)
+
+        msg = "can only insert Interval objects and NA into an IntervalArray"
+        with pytest.raises(TypeError, match=msg):
+            a.shift(1, fill_value=np.timedelta64("NaT", "ns"))
+
+
+class TestSetitem:
+    def test_set_na(self, left_right_dtypes):
+        left, right = left_right_dtypes
+        left = left.copy(deep=True)
+        right = right.copy(deep=True)
+        result = IntervalArray.from_arrays(left, right)
+
+        if result.dtype.subtype.kind not in ["m", "M"]:
+            msg = "'value' should be an interval type, got <.*NaTType'> instead."
+            with pytest.raises(TypeError, match=msg):
+                result[0] = pd.NaT
+        if result.dtype.subtype.kind in ["i", "u"]:
+            msg = "Cannot set float NaN to integer-backed IntervalArray"
+            # GH#45484 TypeError, not ValueError, matches what we get with
+            # non-NA un-holdable value.
+            with pytest.raises(TypeError, match=msg):
+                result[0] = np.nan
+            return
+
+        result[0] = np.nan
+
+        expected_left = Index([left._na_value] + list(left[1:]))
+        expected_right = Index([right._na_value] + list(right[1:]))
+        expected = IntervalArray.from_arrays(expected_left, expected_right)
+
+        tm.assert_extension_array_equal(result, expected)
+
+    def test_setitem_mismatched_closed(self):
+        arr = IntervalArray.from_breaks(range(4))
+        orig = arr.copy()
+        other = arr.set_closed("both")
+
+        msg = "'value.closed' is 'both', expected 'right'"
+        with pytest.raises(ValueError, match=msg):
+            arr[0] = other[0]
+        with pytest.raises(ValueError, match=msg):
+            arr[:1] = other[:1]
+        with pytest.raises(ValueError, match=msg):
+            arr[:0] = other[:0]
+        with pytest.raises(ValueError, match=msg):
+            arr[:] = other[::-1]
+        with pytest.raises(ValueError, match=msg):
+            arr[:] = list(other[::-1])
+        with pytest.raises(ValueError, match=msg):
+            arr[:] = other[::-1].astype(object)
+        with pytest.raises(ValueError, match=msg):
+            arr[:] = other[::-1].astype("category")
+
+        # empty list should be no-op
+        arr[:0] = []
+        tm.assert_interval_array_equal(arr, orig)
+
+
+class TestReductions:
+    def test_min_max_invalid_axis(self, left_right_dtypes):
+        left, right = left_right_dtypes
+        left = left.copy(deep=True)
+        right = right.copy(deep=True)
+        arr = IntervalArray.from_arrays(left, right)
+
+        msg = "`axis` must be fewer than the number of dimensions"
+        for axis in [-2, 1]:
+            with pytest.raises(ValueError, match=msg):
+                arr.min(axis=axis)
+            with pytest.raises(ValueError, match=msg):
+                arr.max(axis=axis)
+
+        msg = "'>=' not supported between"
+        with pytest.raises(TypeError, match=msg):
+            arr.min(axis="foo")
+        with pytest.raises(TypeError, match=msg):
+            arr.max(axis="foo")
+
+    def test_min_max(self, left_right_dtypes, index_or_series_or_array):
+        # GH#44746
+        left, right = left_right_dtypes
+        left = left.copy(deep=True)
+        right = right.copy(deep=True)
+        arr = IntervalArray.from_arrays(left, right)
+
+        # The expected results below are only valid if monotonic
+        assert left.is_monotonic_increasing
+        assert Index(arr).is_monotonic_increasing
+
+        MIN = arr[0]
+        MAX = arr[-1]
+
+        indexer = np.arange(len(arr))
+        np.random.default_rng(2).shuffle(indexer)
+        arr = arr.take(indexer)
+
+        arr_na = arr.insert(2, np.nan)
+
+        arr = index_or_series_or_array(arr)
+        arr_na = index_or_series_or_array(arr_na)
+
+        for skipna in [True, False]:
+            res = arr.min(skipna=skipna)
+            assert res == MIN
+            assert type(res) == type(MIN)
+
+            res = arr.max(skipna=skipna)
+            assert res == MAX
+            assert type(res) == type(MAX)
+
+        res = arr_na.min(skipna=False)
+        assert np.isnan(res)
+        res = arr_na.max(skipna=False)
+        assert np.isnan(res)
+
+        res = arr_na.min(skipna=True)
+        assert res == MIN
+        assert type(res) == type(MIN)
+        res = arr_na.max(skipna=True)
+        assert res == MAX
+        assert type(res) == type(MAX)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval_pyarrow.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval_pyarrow.py
new file mode 100644
index 0000000000000000000000000000000000000000..ef8701be81e2b9248c29fc4e901161fd18d72bbe
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_interval_pyarrow.py
@@ -0,0 +1,160 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import IntervalArray
+
+
+def test_arrow_extension_type():
+    pa = pytest.importorskip("pyarrow")
+
+    from pandas.core.arrays.arrow.extension_types import ArrowIntervalType
+
+    p1 = ArrowIntervalType(pa.int64(), "left")
+    p2 = ArrowIntervalType(pa.int64(), "left")
+    p3 = ArrowIntervalType(pa.int64(), "right")
+
+    assert p1.closed == "left"
+    assert p1 == p2
+    assert p1 != p3
+    assert hash(p1) == hash(p2)
+    assert hash(p1) != hash(p3)
+
+
+def test_arrow_array():
+    pa = pytest.importorskip("pyarrow")
+
+    from pandas.core.arrays.arrow.extension_types import ArrowIntervalType
+
+    intervals = pd.interval_range(1, 5, freq=1).array
+
+    result = pa.array(intervals)
+    assert isinstance(result.type, ArrowIntervalType)
+    assert result.type.closed == intervals.closed
+    assert result.type.subtype == pa.int64()
+    assert result.storage.field("left").equals(pa.array([1, 2, 3, 4], type="int64"))
+    assert result.storage.field("right").equals(pa.array([2, 3, 4, 5], type="int64"))
+
+    expected = pa.array([{"left": i, "right": i + 1} for i in range(1, 5)])
+    assert result.storage.equals(expected)
+
+    # convert to its storage type
+    result = pa.array(intervals, type=expected.type)
+    assert result.equals(expected)
+
+    # unsupported conversions
+    with pytest.raises(TypeError, match="Not supported to convert IntervalArray"):
+        pa.array(intervals, type="float64")
+
+    with pytest.raises(TypeError, match="Not supported to convert IntervalArray"):
+        pa.array(intervals, type=ArrowIntervalType(pa.float64(), "left"))
+
+
+def test_arrow_array_missing():
+    pa = pytest.importorskip("pyarrow")
+
+    from pandas.core.arrays.arrow.extension_types import ArrowIntervalType
+
+    arr = IntervalArray.from_breaks([0.0, 1.0, 2.0, 3.0])
+    arr[1] = None
+
+    result = pa.array(arr)
+    assert isinstance(result.type, ArrowIntervalType)
+    assert result.type.closed == arr.closed
+    assert result.type.subtype == pa.float64()
+
+    # fields have missing values (not NaN)
+    left = pa.array([0.0, None, 2.0], type="float64")
+    right = pa.array([1.0, None, 3.0], type="float64")
+    assert result.storage.field("left").equals(left)
+    assert result.storage.field("right").equals(right)
+
+    # structarray itself also has missing values on the array level
+    vals = [
+        {"left": 0.0, "right": 1.0},
+        {"left": None, "right": None},
+        {"left": 2.0, "right": 3.0},
+    ]
+    expected = pa.StructArray.from_pandas(vals, mask=np.array([False, True, False]))
+    assert result.storage.equals(expected)
+
+
+@pytest.mark.filterwarnings(
+    "ignore:Passing a BlockManager to DataFrame:DeprecationWarning"
+)
+@pytest.mark.parametrize(
+    "breaks",
+    [[0.0, 1.0, 2.0, 3.0], pd.date_range("2017", periods=4, freq="D")],
+    ids=["float", "datetime64[ns]"],
+)
+def test_arrow_table_roundtrip(breaks):
+    pa = pytest.importorskip("pyarrow")
+
+    from pandas.core.arrays.arrow.extension_types import ArrowIntervalType
+
+    arr = IntervalArray.from_breaks(breaks)
+    arr[1] = None
+    df = pd.DataFrame({"a": arr})
+
+    table = pa.table(df)
+    assert isinstance(table.field("a").type, ArrowIntervalType)
+    result = table.to_pandas()
+    assert isinstance(result["a"].dtype, pd.IntervalDtype)
+    tm.assert_frame_equal(result, df)
+
+    table2 = pa.concat_tables([table, table])
+    result = table2.to_pandas()
+    expected = pd.concat([df, df], ignore_index=True)
+    tm.assert_frame_equal(result, expected)
+
+    # GH#41040
+    table = pa.table(
+        [pa.chunked_array([], type=table.column(0).type)], schema=table.schema
+    )
+    result = table.to_pandas()
+    tm.assert_frame_equal(result, expected[0:0])
+
+
+@pytest.mark.filterwarnings(
+    "ignore:Passing a BlockManager to DataFrame:DeprecationWarning"
+)
+@pytest.mark.parametrize(
+    "breaks",
+    [[0.0, 1.0, 2.0, 3.0], pd.date_range("2017", periods=4, freq="D")],
+    ids=["float", "datetime64[ns]"],
+)
+def test_arrow_table_roundtrip_without_metadata(breaks):
+    pa = pytest.importorskip("pyarrow")
+
+    arr = IntervalArray.from_breaks(breaks)
+    arr[1] = None
+    df = pd.DataFrame({"a": arr})
+
+    table = pa.table(df)
+    # remove the metadata
+    table = table.replace_schema_metadata()
+    assert table.schema.metadata is None
+
+    result = table.to_pandas()
+    assert isinstance(result["a"].dtype, pd.IntervalDtype)
+    tm.assert_frame_equal(result, df)
+
+
+def test_from_arrow_from_raw_struct_array():
+    # in case pyarrow lost the Interval extension type (eg on parquet roundtrip
+    # with datetime64[ns] subtype, see GH-45881), still allow conversion
+    # from arrow to IntervalArray
+    pa = pytest.importorskip("pyarrow")
+
+    arr = pa.array([{"left": 0, "right": 1}, {"left": 1, "right": 2}])
+    dtype = pd.IntervalDtype(np.dtype("int64"), closed="neither")
+
+    result = dtype.__from_arrow__(arr)
+    expected = IntervalArray.from_breaks(
+        np.array([0, 1, 2], dtype="int64"), closed="neither"
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    result = dtype.__from_arrow__(pa.chunked_array([arr]))
+    tm.assert_extension_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_overlaps.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_overlaps.py
new file mode 100644
index 0000000000000000000000000000000000000000..4853bec51106c05781a4c11921f0e082934147ec
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/interval/test_overlaps.py
@@ -0,0 +1,93 @@
+"""Tests for Interval-Interval operations, such as overlaps, contains, etc."""
+import numpy as np
+import pytest
+
+from pandas import (
+    Interval,
+    IntervalIndex,
+    Timedelta,
+    Timestamp,
+)
+import pandas._testing as tm
+from pandas.core.arrays import IntervalArray
+
+
+@pytest.fixture(params=[IntervalArray, IntervalIndex])
+def constructor(request):
+    """
+    Fixture for testing both interval container classes.
+    """
+    return request.param
+
+
+@pytest.fixture(
+    params=[
+        (Timedelta("0 days"), Timedelta("1 day")),
+        (Timestamp("2018-01-01"), Timedelta("1 day")),
+        (0, 1),
+    ],
+    ids=lambda x: type(x[0]).__name__,
+)
+def start_shift(request):
+    """
+    Fixture for generating intervals of different types from a start value
+    and a shift value that can be added to start to generate an endpoint.
+    """
+    return request.param
+
+
+class TestOverlaps:
+    def test_overlaps_interval(self, constructor, start_shift, closed, other_closed):
+        start, shift = start_shift
+        interval = Interval(start, start + 3 * shift, other_closed)
+
+        # intervals: identical, nested, spanning, partial, adjacent, disjoint
+        tuples = [
+            (start, start + 3 * shift),
+            (start + shift, start + 2 * shift),
+            (start - shift, start + 4 * shift),
+            (start + 2 * shift, start + 4 * shift),
+            (start + 3 * shift, start + 4 * shift),
+            (start + 4 * shift, start + 5 * shift),
+        ]
+        interval_container = constructor.from_tuples(tuples, closed)
+
+        adjacent = interval.closed_right and interval_container.closed_left
+        expected = np.array([True, True, True, True, adjacent, False])
+        result = interval_container.overlaps(interval)
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize("other_constructor", [IntervalArray, IntervalIndex])
+    def test_overlaps_interval_container(self, constructor, other_constructor):
+        # TODO: modify this test when implemented
+        interval_container = constructor.from_breaks(range(5))
+        other_container = other_constructor.from_breaks(range(5))
+        with pytest.raises(NotImplementedError, match="^$"):
+            interval_container.overlaps(other_container)
+
+    def test_overlaps_na(self, constructor, start_shift):
+        """NA values are marked as False"""
+        start, shift = start_shift
+        interval = Interval(start, start + shift)
+
+        tuples = [
+            (start, start + shift),
+            np.nan,
+            (start + 2 * shift, start + 3 * shift),
+        ]
+        interval_container = constructor.from_tuples(tuples)
+
+        expected = np.array([True, False, False])
+        result = interval_container.overlaps(interval)
+        tm.assert_numpy_array_equal(result, expected)
+
+    @pytest.mark.parametrize(
+        "other",
+        [10, True, "foo", Timedelta("1 day"), Timestamp("2018-01-01")],
+        ids=lambda x: type(x).__name__,
+    )
+    def test_overlaps_invalid_type(self, constructor, other):
+        interval_container = constructor.from_breaks(range(5))
+        msg = f"`other` must be Interval-like, got {type(other).__name__}"
+        with pytest.raises(TypeError, match=msg):
+            interval_container.overlaps(other)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/__init__.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/__init__.py
new file mode 100644
index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arithmetic.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arithmetic.py
new file mode 100644
index 0000000000000000000000000000000000000000..f4b571ca627b3da34e943972ba70b03bae74417a
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arithmetic.py
@@ -0,0 +1,248 @@
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+# integer dtypes
+arrays = [pd.array([1, 2, 3, None], dtype=dtype) for dtype in tm.ALL_INT_EA_DTYPES]
+scalars: list[Any] = [2] * len(arrays)
+# floating dtypes
+arrays += [pd.array([0.1, 0.2, 0.3, None], dtype=dtype) for dtype in tm.FLOAT_EA_DTYPES]
+scalars += [0.2, 0.2]
+# boolean
+arrays += [pd.array([True, False, True, None], dtype="boolean")]
+scalars += [False]
+
+
+@pytest.fixture(params=zip(arrays, scalars), ids=[a.dtype.name for a in arrays])
+def data(request):
+    """Fixture returning parametrized (array, scalar) tuple.
+
+    Used to test equivalence of scalars, numpy arrays with array ops, and the
+    equivalence of DataFrame and Series ops.
+    """
+    return request.param
+
+
+def check_skip(data, op_name):
+    if isinstance(data.dtype, pd.BooleanDtype) and "sub" in op_name:
+        pytest.skip("subtract not implemented for boolean")
+
+
+def is_bool_not_implemented(data, op_name):
+    # match non-masked behavior
+    return data.dtype.kind == "b" and op_name.strip("_").lstrip("r") in [
+        "pow",
+        "truediv",
+        "floordiv",
+    ]
+
+
+# Test equivalence of scalars, numpy arrays with array ops
+# -----------------------------------------------------------------------------
+
+
+def test_array_scalar_like_equivalence(data, all_arithmetic_operators):
+    data, scalar = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    check_skip(data, all_arithmetic_operators)
+
+    scalar_array = pd.array([scalar] * len(data), dtype=data.dtype)
+
+    # TODO also add len-1 array (np.array([scalar], dtype=data.dtype.numpy_dtype))
+    for scalar in [scalar, data.dtype.type(scalar)]:
+        if is_bool_not_implemented(data, all_arithmetic_operators):
+            msg = "operator '.*' not implemented for bool dtypes"
+            with pytest.raises(NotImplementedError, match=msg):
+                op(data, scalar)
+            with pytest.raises(NotImplementedError, match=msg):
+                op(data, scalar_array)
+        else:
+            result = op(data, scalar)
+            expected = op(data, scalar_array)
+            tm.assert_extension_array_equal(result, expected)
+
+
+def test_array_NA(data, all_arithmetic_operators):
+    data, _ = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    check_skip(data, all_arithmetic_operators)
+
+    scalar = pd.NA
+    scalar_array = pd.array([pd.NA] * len(data), dtype=data.dtype)
+
+    mask = data._mask.copy()
+
+    if is_bool_not_implemented(data, all_arithmetic_operators):
+        msg = "operator '.*' not implemented for bool dtypes"
+        with pytest.raises(NotImplementedError, match=msg):
+            op(data, scalar)
+        # GH#45421 check op doesn't alter data._mask inplace
+        tm.assert_numpy_array_equal(mask, data._mask)
+        return
+
+    result = op(data, scalar)
+    # GH#45421 check op doesn't alter data._mask inplace
+    tm.assert_numpy_array_equal(mask, data._mask)
+
+    expected = op(data, scalar_array)
+    tm.assert_numpy_array_equal(mask, data._mask)
+
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_numpy_array_equivalence(data, all_arithmetic_operators):
+    data, scalar = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    check_skip(data, all_arithmetic_operators)
+
+    numpy_array = np.array([scalar] * len(data), dtype=data.dtype.numpy_dtype)
+    pd_array = pd.array(numpy_array, dtype=data.dtype)
+
+    if is_bool_not_implemented(data, all_arithmetic_operators):
+        msg = "operator '.*' not implemented for bool dtypes"
+        with pytest.raises(NotImplementedError, match=msg):
+            op(data, numpy_array)
+        with pytest.raises(NotImplementedError, match=msg):
+            op(data, pd_array)
+        return
+
+    result = op(data, numpy_array)
+    expected = op(data, pd_array)
+    tm.assert_extension_array_equal(result, expected)
+
+
+# Test equivalence with Series and DataFrame ops
+# -----------------------------------------------------------------------------
+
+
+def test_frame(data, all_arithmetic_operators):
+    data, scalar = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    check_skip(data, all_arithmetic_operators)
+
+    # DataFrame with scalar
+    df = pd.DataFrame({"A": data})
+
+    if is_bool_not_implemented(data, all_arithmetic_operators):
+        msg = "operator '.*' not implemented for bool dtypes"
+        with pytest.raises(NotImplementedError, match=msg):
+            op(df, scalar)
+        with pytest.raises(NotImplementedError, match=msg):
+            op(data, scalar)
+        return
+
+    result = op(df, scalar)
+    expected = pd.DataFrame({"A": op(data, scalar)})
+    tm.assert_frame_equal(result, expected)
+
+
+def test_series(data, all_arithmetic_operators):
+    data, scalar = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+    check_skip(data, all_arithmetic_operators)
+
+    ser = pd.Series(data)
+
+    others = [
+        scalar,
+        np.array([scalar] * len(data), dtype=data.dtype.numpy_dtype),
+        pd.array([scalar] * len(data), dtype=data.dtype),
+        pd.Series([scalar] * len(data), dtype=data.dtype),
+    ]
+
+    for other in others:
+        if is_bool_not_implemented(data, all_arithmetic_operators):
+            msg = "operator '.*' not implemented for bool dtypes"
+            with pytest.raises(NotImplementedError, match=msg):
+                op(ser, other)
+
+        else:
+            result = op(ser, other)
+            expected = pd.Series(op(data, other))
+            tm.assert_series_equal(result, expected)
+
+
+# Test generic characteristics / errors
+# -----------------------------------------------------------------------------
+
+
+def test_error_invalid_object(data, all_arithmetic_operators):
+    data, _ = data
+
+    op = all_arithmetic_operators
+    opa = getattr(data, op)
+
+    # 2d -> return NotImplemented
+    result = opa(pd.DataFrame({"A": data}))
+    assert result is NotImplemented
+
+    msg = r"can only perform ops with 1-d structures"
+    with pytest.raises(NotImplementedError, match=msg):
+        opa(np.arange(len(data)).reshape(-1, len(data)))
+
+
+def test_error_len_mismatch(data, all_arithmetic_operators):
+    # operating with a list-like with non-matching length raises
+    data, scalar = data
+    op = tm.get_op_from_name(all_arithmetic_operators)
+
+    other = [scalar] * (len(data) - 1)
+
+    err = ValueError
+    msg = "|".join(
+        [
+            r"operands could not be broadcast together with shapes \(3,\) \(4,\)",
+            r"operands could not be broadcast together with shapes \(4,\) \(3,\)",
+        ]
+    )
+    if data.dtype.kind == "b" and all_arithmetic_operators.strip("_") in [
+        "sub",
+        "rsub",
+    ]:
+        err = TypeError
+        msg = (
+            r"numpy boolean subtract, the `\-` operator, is not supported, use "
+            r"the bitwise_xor, the `\^` operator, or the logical_xor function instead"
+        )
+    elif is_bool_not_implemented(data, all_arithmetic_operators):
+        msg = "operator '.*' not implemented for bool dtypes"
+        err = NotImplementedError
+
+    for other in [other, np.array(other)]:
+        with pytest.raises(err, match=msg):
+            op(data, other)
+
+        s = pd.Series(data)
+        with pytest.raises(err, match=msg):
+            op(s, other)
+
+
+@pytest.mark.parametrize("op", ["__neg__", "__abs__", "__invert__"])
+def test_unary_op_does_not_propagate_mask(data, op):
+    # https://github.com/pandas-dev/pandas/issues/39943
+    data, _ = data
+    ser = pd.Series(data)
+
+    if op == "__invert__" and data.dtype.kind == "f":
+        # we follow numpy in raising
+        msg = "ufunc 'invert' not supported for the input types"
+        with pytest.raises(TypeError, match=msg):
+            getattr(ser, op)()
+        with pytest.raises(TypeError, match=msg):
+            getattr(data, op)()
+        with pytest.raises(TypeError, match=msg):
+            # Check that this is still the numpy behavior
+            getattr(data._data, op)()
+
+        return
+
+    result = getattr(ser, op)()
+    expected = result.copy(deep=True)
+    ser[0] = None
+    tm.assert_series_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arrow_compat.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arrow_compat.py
new file mode 100644
index 0000000000000000000000000000000000000000..293ee4095d02e1b35ace33458e38c61d87181373
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_arrow_compat.py
@@ -0,0 +1,210 @@
+import numpy as np
+import pytest
+
+import pandas as pd
+import pandas._testing as tm
+
+pytestmark = pytest.mark.filterwarnings(
+    "ignore:Passing a BlockManager to DataFrame:DeprecationWarning"
+)
+
+
+pa = pytest.importorskip("pyarrow")
+
+from pandas.core.arrays.arrow._arrow_utils import pyarrow_array_to_numpy_and_mask
+
+arrays = [pd.array([1, 2, 3, None], dtype=dtype) for dtype in tm.ALL_INT_EA_DTYPES]
+arrays += [pd.array([0.1, 0.2, 0.3, None], dtype=dtype) for dtype in tm.FLOAT_EA_DTYPES]
+arrays += [pd.array([True, False, True, None], dtype="boolean")]
+
+
+@pytest.fixture(params=arrays, ids=[a.dtype.name for a in arrays])
+def data(request):
+    """
+    Fixture returning parametrized array from given dtype, including integer,
+    float and boolean
+    """
+    return request.param
+
+
+def test_arrow_array(data):
+    arr = pa.array(data)
+    expected = pa.array(
+        data.to_numpy(object, na_value=None),
+        type=pa.from_numpy_dtype(data.dtype.numpy_dtype),
+    )
+    assert arr.equals(expected)
+
+
+def test_arrow_roundtrip(data):
+    df = pd.DataFrame({"a": data})
+    table = pa.table(df)
+    assert table.field("a").type == str(data.dtype.numpy_dtype)
+
+    result = table.to_pandas()
+    assert result["a"].dtype == data.dtype
+    tm.assert_frame_equal(result, df)
+
+
+def test_dataframe_from_arrow_types_mapper():
+    def types_mapper(arrow_type):
+        if pa.types.is_boolean(arrow_type):
+            return pd.BooleanDtype()
+        elif pa.types.is_integer(arrow_type):
+            return pd.Int64Dtype()
+
+    bools_array = pa.array([True, None, False], type=pa.bool_())
+    ints_array = pa.array([1, None, 2], type=pa.int64())
+    small_ints_array = pa.array([-1, 0, 7], type=pa.int8())
+    record_batch = pa.RecordBatch.from_arrays(
+        [bools_array, ints_array, small_ints_array], ["bools", "ints", "small_ints"]
+    )
+    result = record_batch.to_pandas(types_mapper=types_mapper)
+    bools = pd.Series([True, None, False], dtype="boolean")
+    ints = pd.Series([1, None, 2], dtype="Int64")
+    small_ints = pd.Series([-1, 0, 7], dtype="Int64")
+    expected = pd.DataFrame({"bools": bools, "ints": ints, "small_ints": small_ints})
+    tm.assert_frame_equal(result, expected)
+
+
+def test_arrow_load_from_zero_chunks(data):
+    # GH-41040
+
+    df = pd.DataFrame({"a": data[0:0]})
+    table = pa.table(df)
+    assert table.field("a").type == str(data.dtype.numpy_dtype)
+    table = pa.table(
+        [pa.chunked_array([], type=table.field("a").type)], schema=table.schema
+    )
+    result = table.to_pandas()
+    assert result["a"].dtype == data.dtype
+    tm.assert_frame_equal(result, df)
+
+
+def test_arrow_from_arrow_uint():
+    # https://github.com/pandas-dev/pandas/issues/31896
+    # possible mismatch in types
+
+    dtype = pd.UInt32Dtype()
+    result = dtype.__from_arrow__(pa.array([1, 2, 3, 4, None], type="int64"))
+    expected = pd.array([1, 2, 3, 4, None], dtype="UInt32")
+
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_arrow_sliced(data):
+    # https://github.com/pandas-dev/pandas/issues/38525
+
+    df = pd.DataFrame({"a": data})
+    table = pa.table(df)
+    result = table.slice(2, None).to_pandas()
+    expected = df.iloc[2:].reset_index(drop=True)
+    tm.assert_frame_equal(result, expected)
+
+    # no missing values
+    df2 = df.fillna(data[0])
+    table = pa.table(df2)
+    result = table.slice(2, None).to_pandas()
+    expected = df2.iloc[2:].reset_index(drop=True)
+    tm.assert_frame_equal(result, expected)
+
+
+@pytest.fixture
+def np_dtype_to_arrays(any_real_numpy_dtype):
+    """
+    Fixture returning actual and expected dtype, pandas and numpy arrays and
+    mask from a given numpy dtype
+    """
+    np_dtype = np.dtype(any_real_numpy_dtype)
+    pa_type = pa.from_numpy_dtype(np_dtype)
+
+    # None ensures the creation of a bitmask buffer.
+    pa_array = pa.array([0, 1, 2, None], type=pa_type)
+    # Since masked Arrow buffer slots are not required to contain a specific
+    # value, assert only the first three values of the created np.array
+    np_expected = np.array([0, 1, 2], dtype=np_dtype)
+    mask_expected = np.array([True, True, True, False])
+    return np_dtype, pa_array, np_expected, mask_expected
+
+
+def test_pyarrow_array_to_numpy_and_mask(np_dtype_to_arrays):
+    """
+    Test conversion from pyarrow array to numpy array.
+
+    Modifies the pyarrow buffer to contain padding and offset, which are
+    considered valid buffers by pyarrow.
+
+    Also tests empty pyarrow arrays with non empty buffers.
+    See https://github.com/pandas-dev/pandas/issues/40896
+    """
+    np_dtype, pa_array, np_expected, mask_expected = np_dtype_to_arrays
+    data, mask = pyarrow_array_to_numpy_and_mask(pa_array, np_dtype)
+    tm.assert_numpy_array_equal(data[:3], np_expected)
+    tm.assert_numpy_array_equal(mask, mask_expected)
+
+    mask_buffer = pa_array.buffers()[0]
+    data_buffer = pa_array.buffers()[1]
+    data_buffer_bytes = pa_array.buffers()[1].to_pybytes()
+
+    # Add trailing padding to the buffer.
+    data_buffer_trail = pa.py_buffer(data_buffer_bytes + b"\x00")
+    pa_array_trail = pa.Array.from_buffers(
+        type=pa_array.type,
+        length=len(pa_array),
+        buffers=[mask_buffer, data_buffer_trail],
+        offset=pa_array.offset,
+    )
+    pa_array_trail.validate()
+    data, mask = pyarrow_array_to_numpy_and_mask(pa_array_trail, np_dtype)
+    tm.assert_numpy_array_equal(data[:3], np_expected)
+    tm.assert_numpy_array_equal(mask, mask_expected)
+
+    # Add offset to the buffer.
+    offset = b"\x00" * (pa_array.type.bit_width // 8)
+    data_buffer_offset = pa.py_buffer(offset + data_buffer_bytes)
+    mask_buffer_offset = pa.py_buffer(b"\x0E")
+    pa_array_offset = pa.Array.from_buffers(
+        type=pa_array.type,
+        length=len(pa_array),
+        buffers=[mask_buffer_offset, data_buffer_offset],
+        offset=pa_array.offset + 1,
+    )
+    pa_array_offset.validate()
+    data, mask = pyarrow_array_to_numpy_and_mask(pa_array_offset, np_dtype)
+    tm.assert_numpy_array_equal(data[:3], np_expected)
+    tm.assert_numpy_array_equal(mask, mask_expected)
+
+    # Empty array
+    np_expected_empty = np.array([], dtype=np_dtype)
+    mask_expected_empty = np.array([], dtype=np.bool_)
+
+    pa_array_offset = pa.Array.from_buffers(
+        type=pa_array.type,
+        length=0,
+        buffers=[mask_buffer, data_buffer],
+        offset=pa_array.offset,
+    )
+    pa_array_offset.validate()
+    data, mask = pyarrow_array_to_numpy_and_mask(pa_array_offset, np_dtype)
+    tm.assert_numpy_array_equal(data[:3], np_expected_empty)
+    tm.assert_numpy_array_equal(mask, mask_expected_empty)
+
+
+@pytest.mark.parametrize(
+    "arr", [pa.nulls(10), pa.chunked_array([pa.nulls(4), pa.nulls(6)])]
+)
+def test_from_arrow_null(data, arr):
+    res = data.dtype.__from_arrow__(arr)
+    assert res.isna().all()
+    assert len(res) == 10
+
+
+def test_from_arrow_type_error(data):
+    # ensure that __from_arrow__ returns a TypeError when getting a wrong
+    # array type
+
+    arr = pa.array(data).cast("string")
+    with pytest.raises(TypeError, match=None):
+        # we don't test the exact error message, only the fact that it raises
+        # a TypeError is relevant
+        data.dtype.__from_arrow__(arr)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_function.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_function.py
new file mode 100644
index 0000000000000000000000000000000000000000..b259018cd6121c53c767e36e3c757211643262d6
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_function.py
@@ -0,0 +1,74 @@
+import numpy as np
+import pytest
+
+from pandas.core.dtypes.common import is_integer_dtype
+
+import pandas as pd
+import pandas._testing as tm
+from pandas.core.arrays import BaseMaskedArray
+
+arrays = [pd.array([1, 2, 3, None], dtype=dtype) for dtype in tm.ALL_INT_EA_DTYPES]
+arrays += [
+    pd.array([0.141, -0.268, 5.895, None], dtype=dtype) for dtype in tm.FLOAT_EA_DTYPES
+]
+
+
+@pytest.fixture(params=arrays, ids=[a.dtype.name for a in arrays])
+def data(request):
+    """
+    Fixture returning parametrized 'data' array with different integer and
+    floating point types
+    """
+    return request.param
+
+
+@pytest.fixture()
+def numpy_dtype(data):
+    """
+    Fixture returning numpy dtype from 'data' input array.
+    """
+    # For integer dtype, the numpy conversion must be done to float
+    if is_integer_dtype(data):
+        numpy_dtype = float
+    else:
+        numpy_dtype = data.dtype.type
+    return numpy_dtype
+
+
+def test_round(data, numpy_dtype):
+    # No arguments
+    result = data.round()
+    expected = pd.array(
+        np.round(data.to_numpy(dtype=numpy_dtype, na_value=None)), dtype=data.dtype
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+    # Decimals argument
+    result = data.round(decimals=2)
+    expected = pd.array(
+        np.round(data.to_numpy(dtype=numpy_dtype, na_value=None), decimals=2),
+        dtype=data.dtype,
+    )
+    tm.assert_extension_array_equal(result, expected)
+
+
+def test_tolist(data):
+    result = data.tolist()
+    expected = list(data)
+    tm.assert_equal(result, expected)
+
+
+def test_to_numpy():
+    # GH#56991
+
+    class MyStringArray(BaseMaskedArray):
+        dtype = pd.StringDtype()
+        _dtype_cls = pd.StringDtype
+        _internal_fill_value = pd.NA
+
+    arr = MyStringArray(
+        values=np.array(["a", "b", "c"]), mask=np.array([False, True, False])
+    )
+    result = arr.to_numpy()
+    expected = np.array(["a", pd.NA, "c"])
+    tm.assert_numpy_array_equal(result, expected)
diff --git a/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_indexing.py b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_indexing.py
new file mode 100644
index 0000000000000000000000000000000000000000..753d562c87ffa86bbbf665bf3dbbd409eddfdd88
--- /dev/null
+++ b/.venv/lib/python3.13/site-packages/pandas/tests/arrays/masked/test_indexing.py
@@ -0,0 +1,60 @@
+import re
+
+import numpy as np
+import pytest
+
+import pandas as pd
+
+
+class TestSetitemValidation:
+    def _check_setitem_invalid(self, arr, invalid):
+        msg = f"Invalid value '{invalid!s}' for dtype '{arr.dtype}'"
+        msg = re.escape(msg)
+        with pytest.raises(TypeError, match=msg):
+            arr[0] = invalid
+
+        with pytest.raises(TypeError, match=msg):
+            arr[:] = invalid
+
+        with pytest.raises(TypeError, match=msg):
+            arr[[0]] = invalid
+
+        # FIXME: don't leave commented-out
+        # with pytest.raises(TypeError):
+        #    arr[[0]] = [invalid]
+
+        # with pytest.raises(TypeError):
+        #    arr[[0]] = np.array([invalid], dtype=object)
+
+        # Series non-coercion, behavior subject to change
+        ser = pd.Series(arr)
+        with pytest.raises(TypeError, match=msg):
+            ser[0] = invalid
+            # TODO: so, so many other variants of this...
+
+    _invalid_scalars = [
+        1 + 2j,
+        "True",
+        "1",
+        "1.0",
+        pd.NaT,
+        np.datetime64("NaT"),
+        np.timedelta64("NaT"),
+    ]
+
+    @pytest.mark.parametrize(
+        "invalid", _invalid_scalars + [1, 1.0, np.int64(1), np.float64(1)]
+    )
+    def test_setitem_validation_scalar_bool(self, invalid):
+        arr = pd.array([True, False, None], dtype="boolean")
+        self._check_setitem_invalid(arr, invalid)
+
+    @pytest.mark.parametrize("invalid", _invalid_scalars + [True, 1.5, np.float64(1.5)])
+    def test_setitem_validation_scalar_int(self, invalid, any_int_ea_dtype):
+        arr = pd.array([1, 2, None], dtype=any_int_ea_dtype)
+        self._check_setitem_invalid(arr, invalid)
+
+    @pytest.mark.parametrize("invalid", _invalid_scalars + [True])
+    def test_setitem_validation_scalar_float(self, invalid, float_ea_dtype):
+        arr = pd.array([1, 2, None], dtype=float_ea_dtype)
+        self._check_setitem_invalid(arr, invalid)